@yosai/cli 0.2.1-test.0 → 0.2.1-test.10

package/dist/npm-meta.js

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
@@ -23,6 +23,11 @@ export function readPackageMeta() {
         dir = parent;
     }
 }
+let cliVersionCache;
+export function getCliVersion() {
+    cliVersionCache ??= readPackageMeta()?.version ?? 'unknown';
+    return cliVersionCache;
+}
 export async function runNpm(args) {
     const useCmdWrapper = process.platform === 'win32';
     const command = useCmdWrapper ? (process.env.ComSpec ?? 'cmd.exe') : 'npm';
@@ -45,21 +50,39 @@ export async function runNpm(args) {
         };
     }
 }
-export async function fetchLatestVersion(name) {
-    const result = await runNpm(['view', name, 'version', `--registry=${PUBLIC_REGISTRY}`]);
+export async function fetchLatestVersion(name, channel = 'latest') {
+    const result = await runNpm(['view', `${name}@${channel}`, 'version', `--registry=${PUBLIC_REGISTRY}`]);
     if (!result.ok) {
         const reason = result.stderr.split(/\r?\n/)[0]?.trim() || result.stdout.split(/\r?\n/)[0]?.trim() || '';
-        throw new NetworkError(`无法获知 ${name} 的最新版本：npm view 调用失败`, `${reason ? `${reason}；` : ''}离线或 npm 不可用时，手动升级请执行 npm install -g ${name}@latest`);
+        throw new NetworkError(`无法获知 ${name}（${channel} 通道）的最新版本：npm view 调用失败`, `${reason ? `${reason}；` : ''}离线或 npm 不可用时，手动升级请执行 npm install -g ${name}@${channel}`);
     }
     const latest = result.stdout.split(/\r?\n/)[0]?.trim() ?? '';
     if (!/^\d+\.\d+\.\d+/.test(latest)) {
-        throw new NetworkError(`无法解析 ${name} 的最新版本输出`, `npm view 返回：${result.stdout.slice(0, 120)}`);
+        throw new NetworkError(`无法解析 ${name}（${channel} 通道）的最新版本输出`, `npm view 返回：${result.stdout.slice(0, 120)}`);
     }
     return latest;
 }
 export function compareVersions(a, b) {
-    const left = toSegments(a);
-    const right = toSegments(b);
+    const left = splitVersion(a);
+    const right = splitVersion(b);
+    const coreDiff = compareCoreSegments(left.core, right.core);
+    if (coreDiff !== 0) {
+        return coreDiff;
+    }
+    return comparePreRelease(left.pre, right.pre);
+}
+function splitVersion(version) {
+    const trimmed = version.trim();
+    const dash = trimmed.indexOf('-');
+    const coreText = dash === -1 ? trimmed : trimmed.slice(0, dash);
+    const core = coreText.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    if (dash === -1) {
+        return { core, pre: null };
+    }
+    const pre = trimmed.slice(dash + 1).split('.').filter((part) => part !== '');
+    return { core, pre: pre.length > 0 ? pre : null };
+}
+function compareCoreSegments(left, right) {
     for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
         const diff = (left[i] ?? 0) - (right[i] ?? 0);
         if (diff !== 0) {
@@ -68,20 +91,74 @@ export function compareVersions(a, b) {
     }
     return 0;
 }
+function comparePreRelease(left, right) {
+    if (!left && !right) {
+        return 0;
+    }
+    if (!left) {
+        return 1;
+    }
+    if (!right) {
+        return -1;
+    }
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const l = left[i];
+        const r = right[i];
+        if (l === undefined) {
+            return -1;
+        }
+        if (r === undefined) {
+            return 1;
+        }
+        const diff = comparePreIdentifier(l, r);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+function comparePreIdentifier(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+        const l = Number(left);
+        const r = Number(right);
+        if (l === r) {
+            return 0;
+        }
+        return l < r ? -1 : 1;
+    }
+    if (leftNumeric !== rightNumeric) {
+        return leftNumeric ? -1 : 1;
+    }
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}
 export async function detectGlobalInstall(meta) {
     const result = await runNpm(['prefix', '-g']);
     if (!result.ok || result.stdout.length === 0) {
         return { global: false, prefix: '' };
     }
     const prefix = stripTrailingSep(resolve(result.stdout));
-    const packageDir = stripTrailingSep(meta.dir);
     return {
-        global: packageDir === prefix || packageDir.startsWith(`${prefix}${sep}`),
+        global: isPackageUnderPrefix(meta.dir, prefix),
         prefix,
     };
 }
-function toSegments(version) {
-    return version.trim().split('-')[0].split('.').map((part) => Number.parseInt(part, 10) || 0);
+export function isPackageUnderPrefix(packageDir, prefix) {
+    const dir = stripTrailingSep(realpathOrSelf(packageDir));
+    const base = stripTrailingSep(realpathOrSelf(prefix));
+    return dir === base || dir.startsWith(`${base}${sep}`);
+}
+function realpathOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
 }
 function tryParseJson(path) {
     try {

package/dist/openapis-client.js

@@ -1,7 +1,10 @@
 import { readFile, stat } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { AuthError, BusinessError, NetworkError } from './errors.js';
+import { envNoteOfEndpoint } from './endpoints.js';
+import { AuthError, BusinessError, NetworkError, UpgradeError } from './errors.js';
+import { getCliVersion } from './npm-meta.js';
 export const MAX_UPLOAD_SIZE_BYTES = 20 * 1024 * 1024;
+export const CLI_VERSION_HEADER = 'X-Yos-Cli-Version';
 export function formatIdentity(identity) {
     return identity.userName ? `${identity.userName}（${identity.userCode}）` : identity.userCode;
 }
@@ -33,16 +36,20 @@ export class OpenApisClient {
                 headers: {
                     'Content-Type': 'application/json',
                     'Authorization': `Bearer ${this.apiKey}`,
+                    [CLI_VERSION_HEADER]: getCliVersion(),
                 },
                 body: JSON.stringify(body ?? {}),
             });
         }
         catch (e) {
-            throw new NetworkError(`无法连接 YOS 服务：endpoint=${this.base}，原因：${e.message}`);
+            throw new NetworkError(`无法连接 YOS 服务${envNoteOfBase(this.base)}，原因：${e.message}`);
         }
         return parseEnvelope(response);
     }
 }
+function envNoteOfBase(base) {
+    return envNoteOfEndpoint(base.replace(/\/open-apis$/, ''));
+}
 async function parseEnvelope(response) {
     if (response.status === 401) {
         let reason = '访问令牌无效或已过期';
@@ -57,7 +64,23 @@ async function parseEnvelope(response) {
         throw new AuthError(`鉴权失败：${reason}`);
     }
     if (response.status === 404) {
-        throw new NetworkError(`HTTP 404：服务端不存在该接口（${response.url}）`, '确认服务端已部署开放接口通道；端点配错时用 yos login --endpoint <url> --key <key> 重新指定');
+        throw new NetworkError(`HTTP 404：服务端不存在该接口（${response.url}）`, '确认服务端已部署开放接口通道；环境选择有误时用 yos login --env 重新指定');
+    }
+    if (response.status === 426) {
+        let message = 'CLI 版本过低，请升级后重试';
+        let hint;
+        try {
+            const body = await response.json();
+            if (body.error) {
+                message = body.error;
+            }
+            if (body.upgradeCommand) {
+                hint = `执行 \`${body.upgradeCommand}\` 升级后重试`;
+            }
+        }
+        catch {
+        }
+        throw new UpgradeError(message, hint);
     }
     let payload;
     try {
@@ -101,12 +124,12 @@ export async function uploadKnowledgeFile(endpoint, apiKey, filePath, kbCode, pa
     try {
         response = await fetch(`${endpoint}/open-apis/knowledge/file_upload`, {
             method: 'POST',
-            headers: { 'Authorization': `Bearer ${apiKey}` },
+            headers: { 'Authorization': `Bearer ${apiKey}`, [CLI_VERSION_HEADER]: getCliVersion() },
             body: form,
         });
     }
     catch (e) {
-        throw new NetworkError(`无法连接 YOS 服务：endpoint=${endpoint}，原因：${e.message}`);
+        throw new NetworkError(`无法连接 YOS 服务${envNoteOfEndpoint(endpoint)}，原因：${e.message}`);
     }
     return parseEnvelope(response);
 }

package/dist/skill-sync.js

@@ -5,8 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { readPackageMeta } from './npm-meta.js';
 import { updateConfig } from './config.js';
 import { saveVersionState } from './version-state.js';
-export const BUILTIN_SKILLS = ['yos', 'yos-shared', 'yos-kb', 'yos-retrieval', 'yos-transcript', 'yos-support', 'yos-install'];
-const AGENT_SKILL_DIRS = ['.claude/skills', '.workbuddy/skills', '.cursor/skills', '.codex/skills', '.qoder/skills', '.qoder-cn/skills', '.agentskill'];
+export const BUILTIN_SKILLS = ['yos', 'yos-shared', 'yos-knowledge', 'yos-doc', 'yos-sheet', 'yos-retrieval', 'yos-transcript', 'yos-support', 'yos-install'];
+const AGENT_SKILL_DIRS = ['.claude/skills', '.workbuddy/skills', '.cursor/skills', '.codex/skills', '.qoder/skills', '.qoder-cn/skills', '.agents/skills'];
 export function skillsSourceDir() {
     const here = dirname(fileURLToPath(import.meta.url));
     const distCandidate = join(here, 'skills');

package/dist/skills/yos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yos
-description: YOS 企业 AI 能力总入口：公司知识库检索、文档管理、录音转写、帮助手册、客户端升级与反馈。用户问公司制度/流程/资料、要查或整理知识库文档、要看会议录音转写、需要 YOS 客户端帮助时使用；不确定该用哪个 YOS 能力时先读本文件
+description: YOS 企业 AI 能力总入口：公司/部门/工作/个人等各类知识的检索与文档管理、云文档/云表格编写、录音转写、帮助手册、客户端升级与反馈。用户提到 yos/YOS 即使用本技能；用户问制度/流程/规范、要查或整理资料文档、要写云文档/云表格、要看会议录音转写、需要 YOS 客户端帮助时使用；不确定该用哪个 YOS 能力时先读本文件
 ---
 
 # YOS 能力总入口
@@ -10,24 +10,26 @@ YOS 是企业 AI 底座：公司知识、会议录音、帮助手册等能力都
 ## 0. 开工前先确认环境（30 秒）
 
 ```bash
-yos doctor      # 七项 ✓ 才继续：配置文件 / 服务端点 / 访问令牌 / 服务连通（回显身份）/ Skill 安装 / CLI 版本 / Skill 同步
-yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴权）
+yos doctor      # 全部 ✓ 才继续：配置文件 / 访问令牌 / 服务连通（回显身份）/ Skill 安装 / CLI 版本 / Skill 同步
+yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴权 / 5 版本过低）
 ```
 
 - `command not found: yos` 或 `yos doctor` 报「未找到配置文件」→ 按 `yos-install` skill 引导用户装 CLI 与登录，不要继续猜命令
-- 已装但七项没全 ✓ → 先修环境再执行任务；`yos doctor` 的失败项自带修复提示
-- 查版本用 `yos version`（或 `yos --version`）；升级到 npmjs 最新版用 `yos update`
+- 已装但检查项没全 ✓ → 先修好再执行任务；`yos doctor` 的失败项自带修复提示
+- 查版本用 `yos version`（或 `yos --version`）；命令输出前 stderr 若出现「提示: 有新版本」，先执行 `yos update` 升级再继续任务（约定详见 yos-shared）
 
 ## 1. 意图路由
 
 | 用户在问什么 | 用哪个命令 | 先读哪本 skill |
 |---|---|---|
 | 「公司制度/流程/规范/报销标准/产品资料」等**要一个公司里的答案** | `retrieve search` → `retrieve grep` 定位 → `retrieve read` 读原文 | yos-retrieval |
-| 「有哪些文档 / 共几份 / 文档目录结构」 | `retrieve outline`（检索层）或 `docs tree`（管理层） | yos-retrieval / yos-kb |
+| 「有哪些文档 / 共几份 / 文档目录结构」 | `retrieve outline`（检索层）或 `docs tree`（管理层） | yos-retrieval / yos-knowledge |
 | 找**配套/相关**材料、跨文档关系 | `retrieve neighbors`、`retrieve search --entity/--topic` | yos-retrieval |
-| 浏览/搜索自己的知识库与文档内容 | `kb list` `kb detail` `docs tree` `docs content` | yos-kb |
-| 把知识库里的上传文件取回本地 | `docs download <node_code> --out <路径>` | yos-kb |
-| 上传本地文件或目录、新建文档/文件夹、改名、移动、删除、回收站恢复 | `kb upload` `docs create` `docs mkdir` `docs update` `docs rename` `docs move` `docs delete` `docs restore` | yos-kb |
+| 浏览/搜索自己的知识库与文档内容 | `kb list` `kb detail` `docs tree` `docs content` | yos-knowledge |
+| 把知识库里的上传文件取回本地 | `docs download <node_code> --out <路径>` | yos-knowledge |
+| 上传本地文件或目录、新建文档/文件夹、改名、移动、删除、回收站恢复 | `kb upload` `docs create` `docs mkdir` `docs update` `docs rename` `docs move` `docs delete` `docs restore` | yos-knowledge |
+| 往知识库**写云文档**（在线文档；非办公文件） | `docs create --type cloud`、`docs update` | **先读 yos-doc**（正文是结构化 JSON，结构与编写规范都在这本） |
+| 往知识库**写云表格**（在线表格；非办公文件） | `docs create --type sheet`、`docs update` | **先读 yos-sheet**（正文是结构化 JSON，结构与列宽等推荐做法都在这本） |
 | 会议录音转写、纪要、逐句发言 | `transcript list` → `transcript detail` | yos-transcript |
 | 「YOS 怎么用」、客户端最新版本、提交问题反馈 | `support manual*` `support upgrade*` `support feedback` | yos-support |
 | 领域命令没覆盖的能力 | `tool list` → `tool schema <name>` → `tool call <name> --params '{...}'` | yos-shared |
@@ -41,7 +43,7 @@ yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴
 1. **`--json` 是双层包装**：外层 `{"text":"<JSON 字符串>","isError":false}`，要拿字段必须对 `text` 再 `JSON.parse` 一次；`isError:true` 时 `text` 是错误文案而非数据
 2. **参数错误一律 exit=2 且不发请求**：非法枚举、越界 `--size`、日期格式非法或区间倒置、URN 非法、必填缺失都由 CLI 本地拦下，照 `提示:` 改参数即可，不要重试原命令。exit=0 仍需自行校验内容的场景见 yos-shared
 3. **引用作答必须读原文**：`retrieve search` 的 `snippet` 只是线索，不能作为引用依据；未 `retrieve read` 之前不下结论
-4. **写操作先复述再执行**：`kb update`、`docs create/update/mkdir/rename/move`、`kb upload`、`support feedback` 都要让用户确认最终文案；`docs update` 是**整体覆盖**（正文传什么就替换什么）
+4. **写操作先复述再执行**：`kb update`、`docs create/update/mkdir/rename/move`、`kb upload`、`support feedback` 都要让用户确认最终文案；`docs update` 是**整体覆盖**（正文传什么就替换什么）；写云文档/云表格（`--type cloud/sheet`）的正文前**先读 yos-doc（云文档）/ yos-sheet（云表格）技能**——正文是结构化 JSON 且服务端不校验，写错要到客户端打开才暴露
 5. **删除必须两步**：`yos docs count <node_code>` 查受影响文档数 → 展示给用户 → 用户明确同意后才 `yos docs delete`。未经确认不得调用
 6. **令牌不出现在任何输出里**：不写进日志、命令、对用户的回复；只以掩码形式（`xxxxxxxx****xxxx`，即前 8 位 + `****` + 后 4 位）引用
 7. **日期参数分两类，别混用**：`transcript list --start/--end`、`support upgrade-log --start/--end` **只收 `yyyy-MM-dd`**，中文表达由 CLI 本地拒绝（`错误: --start 日期格式应为 yyyy-MM-dd：本周`，exit 2），须自己换算；`retrieve search/outline` 的 `--occurred-*`/`--effective-*` **收自然语言**（`上季度`、`8 月` 直接传，由服务端解析），`retrieve search` 还会把 `--query` 文本里的时间表达解析为时间窗并在 `time_window` 回显
@@ -49,9 +51,9 @@ yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴
 ## 3. 登录与配置
 
 1. 用户在 YOS 客户端「个人设置-访问令牌」页创建并复制令牌（40 位小写 hex）
-2. `yos login` 交互粘贴（不回显）；Agent 代执行时用 `yos login --key <令牌>`（注意令牌会进入 shell 历史，优先让用户自己在终端执行，或用 `YOS_API_KEY`）
-3. 配置文件 `~/.config/yos/config.json`（0600）。三个环境变量**优先于配置文件**：`YOS_CONFIG_DIR`（换配置目录）、`YOS_API_KEY`（换令牌）、`YOS_ENDPOINT`（换端点）
-4. 端点缺省生产环境 `https://yos-bff.linkduoo.com`，切换用 `yos login --endpoint <url>`（本地联调 `http://localhost:8080`）；临时切换可用 `YOS_ENDPOINT`，`yos doctor` 会显示当前生效端点及其来源
+2. `yos login` 交互粘贴（不回显）；Agent 代执行时用 `yos login --key <令牌>`
+3. 配置文件 `~/.config/yos/config.json`（0600）。环境变量**优先于配置文件**：`YOS_CONFIG_DIR`（换配置目录）、`YOS_API_KEY`（换令牌）、`YOS_ENV`（换服务环境）
+4. 切换服务环境（测试/开发用途）：`yos login --env test`（临时可用 `YOS_ENV=test`），本地调试 `--env dev`（指向本机 8080 起的服务）
 5. 退出码 4 = 令牌无效/已吊销/已过期 → 引导重新 `yos login`，不要反复重试同一命令
 
 ## 4. 常用编排（已实测）
@@ -69,6 +71,13 @@ yos kb upload ./报告.pdf --kb KB20261009000001             # 单文件上传
 yos docs download ND20261009000012 --out ./归档/            # 取回上传的原文件（仅 docType=file）
 yos docs count ND20261009000012                            # 删除前查影响范围
 
+# 往知识库写云文档 / 云表格（正文是结构化 JSON 而非文本；动手前先读 yos-doc / yos-sheet 技能）
+# 场景：会议结论/方案等沉淀为在线文档 → 云文档 --type cloud；登记表/对照表/排期表 → 云表格 --type sheet
+yos docs create "上线检查清单" --kb KB20261009000001 --type cloud --file draft.yosdoc.json
+yos docs create "值班排期表" --kb KB20261009000001 --type sheet --file draft.sheet.json
+yos docs content ND20261010000030 --json                     # 写后自查：读回确认正文完整落库、结构未变形
+yos docs update ND20261010000030 --file edited.yosdoc.json    # 改正文=整体覆盖：先读回全文，本地编辑后整体回传
+
 # 会议内容
 yos transcript list --json                                 # 取 transcriptionUserId（不是 TT 开头编码）
 yos transcript detail 2105108032979103745 --json           # 取 summary / sentences
@@ -82,5 +91,5 @@ yos support upgrade --platform MAC_ARM64                    # 客户端最新版
 
 - 默认输出人类可读文本；需要字段时**加 `--json` 再解析**，不要正则刮文本
 - 分页壳不统一：`kb list` / `support upgrade-log` 为 `records` / `total` / `page` / `size`；`transcript list` 为 `list` / `current` / `size` / `pages` / `total`（转写域解析细则见 yos-transcript）
-- 命令报错时先看退出码：`2` 用法错误（CLI 本地拦截，未发请求，按 `提示:` 改参数）、`1` 业务失败（服务端结论，文案里带具体编码，可直接引给用户）、`3` 网络、`4` 鉴权
+- 命令报错时先看退出码：`2` 用法错误（CLI 本地拦截，未发请求，按 `提示:` 改参数）、`1` 业务失败（服务端结论，文案里带具体编码，可直接引给用户）、`3` 网络、`4` 鉴权、`5` 版本过低（先 `yos update` 升级再原样重试）
 - 领域命令找不到对应能力时，`yos tool list` 看全量工具，`yos tool schema <name> --json` 拿完整参数说明（不带 `--json` 会截断描述），再 `yos tool call`

package/dist/skills/yos-doc/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: yos-doc
+description: YOS 云文档（在线文档）的正文编写规范（DocDraft JSON 数据结构）。用户提到 yos/YOS 且要新建或修改知识库里的云文档（在线文档，非办公文件；即 docs create --type cloud 与 docs update 改云文档正文）时，先读本技能确定正文结构；云表格（在线表格）走 yos-sheet 技能；上传办公文件（kb upload）与写 Markdown 文档（--type md）不需要本技能
+---
+
+# YOS 云文档编写（DocDraft）
+
+**往 YOS 知识库写"云文档"（在线文档）的正文内容（新建或修改）前，必须先读本技能。** 云文档正文不是纯文本，而是结构化 JSON（不是 Markdown / HTML），且服务端**不做 schema 校验**（原样存储）——结构写错要到客户端打开时才暴露；本技能自带官方校验器（§4），草稿写完先本地校验再上传。
+
+云表格（在线表格）的正文结构完全不同，见 `yos-sheet` 技能。
+
+## 0. 适用边界（先分清楚再动手）
+
+| 场景 | 走哪个命令 | 用本技能？ |
+|---|---|---|
+| 上传办公文件（docx/xlsx/pdf/png…） | `yos kb upload`（落库为 docType=file） | 否 |
+| 写 Markdown 文档 | `yos docs create`（缺省 `--type md`） | 否 |
+| **写云文档（在线文档）** | `yos docs create --type cloud`、`yos docs update` | **是，先读本技能** |
+| 写云表格（在线表格） | `yos docs create --type sheet`、`yos docs update` | 否（先读 yos-sheet 技能） |
+| 目录管理（建文件夹 / 改名 / 移动 / 删除 / 恢复） | `yos docs mkdir/rename/move/delete/restore` | 否（见 yos-knowledge） |
+
+判断一个已有节点属于哪类：`docs tree` / `docs content` 的 `docType` 字段——`cloud` = 云文档、`sheet` = 云表格、`md` = Markdown、`file` = 上传的办公文件。
+
+## 1. 三步流程
+
+1. **写 JSON 草稿**：按 §2 的 DocDraft 结构写成本地文件（多行 JSON 不要用 `--content` 拼字符串），写好后先用技能自带校验器过一遍（§4）
+2. **上传**：
+
+   ```bash
+   # 新建（--parent 为目标文件夹编码，缺省库根；--kb 与 --parent 至少一个）
+   yos docs create "<标题>" --kb <kbCode> [--parent <folderCode>] --type cloud --file <草稿.json>
+
+   # 修改已有（正文整体覆盖：先读回完整正文，本地编辑后整体回传）
+   yos docs update <nodeCode> --title "<新标题>" --file <草稿.json>
+   ```
+
+3. **读回自查**：`yos docs content <nodeCode> --json` 确认 `docType=cloud` 与正文 JSON 完整落库、结构未变形
+
+## 2. DocDraft JSON（--type cloud）
+
+对齐编辑器：`@yos/doc-editor`。
+
+### 2.1 顶层结构
+
+```json
+{
+  "title": "文档标题",
+  "attachments": [],
+  "content": { "type": "doc", "content": [] }
+}
+```
+
+- `title`：与 `docs create` 的标题参数保持一致；**正文 `content` 不需要再写文档标题**（文档名由 title 单独展示，正文里重复写标题会显示两遍，从正文内容直接开始即可）
+- `attachments`：必须为 `[]`（禁止非空、禁止编造 mediaId）
+- `content`：TipTap 文档树，`type` 固定为 `doc`，节点放 `content` 数组
+
+### 2.2 节点档位
+
+| 档 | 节点 | 用法 |
+| -- | ---- | ---- |
+| **tier A（默认）** | `paragraph` `heading` `blockquote` `horizontalRule` `hardBreak` `bulletList` `orderedList` `listItem` `taskList` `taskItem` `codeBlock` `callout` `table` `tableRow` `tableHeader` `tableCell` `text` | 直接写 |
+| **tier B（用户明确要求）** | `columnBlock` `column`（分栏）、`image`（外链图） | 仅在明确要求时写 |
+| **禁止（永远不写）** | `mindmap` `flowchart` `video` `audio` `file` | — |
+
+行内 marks 允许：`bold` `italic` `strike` `underline` `code` `link` `textStyle` `highlight`；禁止 `glossaryTerm`。
+
+### 2.3 常用节点示例
+
+段落与文本（`attrs` 建议保留为下述形态）：
+
+```json
+{"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"正文内容"}]}
+```
+
+标题（`level` 1~6）：
+
+```json
+{"type":"heading","attrs":{"level":2,"indent":0,"textAlign":null,"collapsed":false},"content":[{"type":"text","text":"小节标题"}]}
+```
+
+无序列表（`bulletList` → `listItem` → `paragraph`，可嵌套；有序列表把 type 换成 `orderedList` 并加 `attrs":{"start":1,"type":null}`，其余相同）：
+
+```json
+{"type":"bulletList","content":[
+  {"type":"listItem","attrs":{"collapsed":false},"content":[
+    {"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"列表项"}]}
+  ]}
+]}
+```
+
+任务列表（`taskList` → `taskItem` → `paragraph`，`checked` 控制勾选态）：
+
+```json
+{"type":"taskList","content":[
+  {"type":"taskItem","attrs":{"checked":false},"content":[
+    {"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"待办项"}]}
+  ]}
+]}
+```
+
+引用与提示块：
+
+```json
+{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"引用内容"}]}]}
+{"type":"callout","attrs":{"emoji":"💡","backgroundColor":null,"borderColor":null},"content":[{"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"提示内容"}]}]}
+```
+
+代码块（换行用 `\n` 写在同一 `text` 内）：
+
+```json
+{"type":"codeBlock","attrs":{"language":"plaintext","wrap":false,"caption":"代码块","collapsed":false,"regionFolds":[]},"content":[{"type":"text","text":"yos kb list\nyos doctor"}]}
+```
+
+表格（`table` → `tableRow` → `tableHeader`/`tableCell` → `paragraph`；首行用 `tableHeader`，数据行用 `tableCell`）：
+
+```json
+{"type":"table","content":[
+  {"type":"tableRow","attrs":{"height":null},"content":[
+    {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"align":null,"backgroundColor":null},"content":[
+      {"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"列 A"}]}
+    ]}
+  ]},
+  {"type":"tableRow","attrs":{"height":null},"content":[
+    {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"align":null,"backgroundColor":null},"content":[
+      {"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"1"}]}
+    ]}
+  ]}
+]}
+```
+
+分隔线与强制换行：`{"type":"horizontalRule"}`（无 content）；`{"type":"hardBreak"}` 放在 paragraph / heading 的 content 内。
+
+### 2.4 节点 attrs 速查
+
+| type | attrs |
+| ---- | ----- |
+| `paragraph` | `{ "indent": 0, "textAlign": null }`；indent 0~8；textAlign null/left/center/right/justify |
+| `heading` | `{ "level": 1, "indent": 0, "textAlign": null, "collapsed": false }`；level 1~6 |
+| `orderedList` | `{ "start": 1, "type": null }` |
+| `listItem` | `{ "collapsed": false }` |
+| `taskItem` | `{ "checked": false }` |
+| `codeBlock` | `{ "language": "plaintext", "wrap": false, "caption": "代码块", "collapsed": false, "regionFolds": [] }` |
+| `callout` | `{ "emoji": "💡", "backgroundColor": null, "borderColor": null }` |
+| `tableRow` | `{ "height": null }` |
+| `tableHeader` / `tableCell` | `{ "colspan": 1, "rowspan": 1, "colwidth": null, "align": null, "backgroundColor": null }` |
+| `blockquote` `bulletList` `taskList` `table` `horizontalRule` `hardBreak` | 无 attrs |
+
+tier B 节点（用户明确要求时）：
+
+- `columnBlock`：attrs `{ "widths": [50, 50] }`，含 2~5 个 `column`（`column` 无 attrs，内放块节点）
+- `image`：attrs 完整字段 `{ "src": "https://…", "mediaId": "", "alt": null, "title": null, "width": null, "height": null, "align": "left", "caption": "", "originalSrc": null, "uploadStatus": null, "uploadId": "" }`——`src` 仅 http(s)；**勿编造 `mediaId` / `upload*`**（媒体由客户端宿主上传）
+
+### 2.5 行内 marks
+
+```json
+{"type":"text","marks":[{"type":"bold"}],"text":"加粗"}
+{"type":"text","marks":[{"type":"italic"}],"text":"斜体"}
+{"type":"text","marks":[{"type":"strike"}],"text":"删除线"}
+{"type":"text","marks":[{"type":"underline"}],"text":"下划线"}
+{"type":"text","marks":[{"type":"code"}],"text":"行内代码"}
+{"type":"text","marks":[{"type":"textStyle","attrs":{"color":"#3370ff"}}],"text":"彩色文字"}
+{"type":"text","marks":[{"type":"highlight","attrs":{"color":"#faf1d1"}}],"text":"高亮"}
+{"type":"text","marks":[{"type":"link","attrs":{"href":"https://example.com","target":"_blank","rel":"noopener noreferrer nofollow","class":"yos-docs-editor-link","title":null}}],"text":"链接"}
+```
+
+可叠加：加粗+斜体同放数组，如 `[{"type":"bold"},{"type":"italic"}]`。
+
+### 2.6 禁止与注意事项
+
+- 禁止节点：`mindmap`、`flowchart`、`video`、`audio`、`file`；禁止 mark：`glossaryTerm`
+- 默认只写 tier A 结构；分栏、外链图等 tier B 仅在用户明确要求时使用
+- **不要以 Markdown 作为最终产物**：先定内容结构再落成上述节点 JSON；转换时逐段映射（小节标题→heading、列表→bulletList、有序列表→orderedList、待办→taskList、引用→blockquote、表格→table、提示→callout）；文档大标题（如 `# 标题`）不映射进正文，由 title 承载（见 §2.1）
+
+## 3. 常见任务编排
+
+**新建云文档并落到指定文件夹**
+
+```bash
+yos kb list --keyword <库名>                 # 1. 拿 kbCode
+yos docs tree KBxxxx --json                  # 2. 找目标文件夹 resourceCode（须 resourceType=folder）
+#                                           3. 写草稿（§2 结构），如 draft.yosdoc.json
+yos docs create "文档标题" --parent NDxxxx --type cloud --file draft.yosdoc.json
+yos docs content NDyyyy --json               # 4. 读回自查
+```
+
+**修改已有云文档的正文**（整体覆盖，保留未改动部分）
+
+```bash
+yos docs content NDyyyy --json               # 1. 取回完整正文 content
+#                                           2. 本地编辑目标段落，其余节点原样保留
+yos docs update NDyyyy --title "标题" --file edited.yosdoc.json   # 3. 整体回传
+```
+
+## 4. 校验与避坑（实测）
+
+### 4.1 本地校验器（技能自带，先校验再上传）
+
+本技能自带与官方编辑器同源的校验器（Node ≥ 18，纯 ESM），用法（`<技能目录>` 即本 SKILL.md 所在目录）：
+
+```bash
+node "<技能目录>/scripts/yos-doc.mjs" validate draft.json --tier A|B
+```
+
+- 默认 tier A；草稿含 tier B 节点（分栏、外链图）时必须显式 `--tier B`，否则校验器按字段路径逐条拒绝
+- 通过 exit 0；失败 exit 1 并逐条输出 `字段路径: 原因`；参数错误 exit 2
+- `schema` 子命令打印当前档位白名单（JSON）；`paths` 子命令打印 references 各文档的绝对路径
+
+### 4.2 参考文档（references/，全量契约）
+
+- `references/AGENT_SCHEMA.doc.md`：官方 Agent 契约完整版（本文档的同源展开）
+- `references/DOC_DATA_API.md`：编辑器全量数据 API（本文档未覆盖的字段查这里）
+- `references/few-shot.draft.json`：可直接参考的草稿示例（过 tier A 校验）
+- `references/doc-draft.template.json` 仅作字段形态参考、不要照抄：它是编辑器全量能力演示（含 attachments、glossaryTerm、禁止节点），任何档位都无法直接通过校验，其中 `attachments` 非空仅为展示、写草稿必须为 `[]`
+
+### 4.3 避坑
+
+- **没有在线校验**：CLI 与服务端都不校验正文 schema，写入即原样存储。自查手段：草稿先过 4.1 校验器或本地 JSON 语法（如 `jq . draft.json`）→ 上传后 `docs content --json` 读回核对结构
+- `docs content` 读回的 `content` 是 **JSON 字符串**，需对 `text` 再 `JSON.parse` 两次（外层信封 + content 字符串）
+- `docs update` 的正文是**整体覆盖**不是局部替换——改一处也要先取全文再整体回传，否则其余内容会丢
+- 渲染效果（尤其高级结构、代码块、表格样式）以 YOS 客户端打开为准；发现渲染异常先确认草稿结构，必要时用 `yos support feedback` 反馈
+- 同名云文档可并存，创建前可先 `docs tree` 看目标位置是否已有同名节点

package/dist/skills/yos-doc/references/AGENT_SCHEMA.doc.md

@@ -0,0 +1,69 @@
+# Agent DocDraft 精简契约
+
+> 完整字段见同目录 [`DOC_DATA_API.md`](./DOC_DATA_API.md)。Agent **只读本文 + few-shot**，勿整份塞入 prompt。  
+> 校验：`node "<技能目录>/scripts/yos-doc.mjs" validate <file.json> [--tier A|B]`
+
+## 输出根形状
+
+```json
+{
+  "title": "文档标题",
+  "attachments": [],
+  "content": { "type": "doc", "content": [/* 块节点 */] }
+}
+```
+
+- `attachments` 必须为 `[]`（媒体由宿主 `DocMediaHooks` 上传）。
+- `content.type` 必须为 `"doc"`。
+- 正文 `content` 不需要再写文档标题（文档名由 `title` 承载）；正文从小节或正文内容直接开始。
+
+## 档位
+
+| 档 | 节点 | 默认 |
+| -- | ---- | ---- |
+| **A** | `paragraph` `heading` `blockquote` `horizontalRule` `hardBreak` `bulletList` `orderedList` `listItem` `taskList` `taskItem` `codeBlock` `callout` `table` `tableRow` `tableHeader` `tableCell` `text` | 默认开启 |
+| **B** | + `columnBlock` `column` `image` | `--tier B` |
+| **C 禁止** | `mindmap` `flowchart` `video` `audio` `file` | 永远禁止 |
+
+Marks 允许：`bold` `italic` `strike` `underline` `code` `link` `textStyle` `highlight`。  
+禁止：`glossaryTerm`。
+
+## 常用节点默认 attrs
+
+| type | attrs 默认 / 约束 |
+| ---- | ----------------- |
+| `paragraph` | `{ "indent": 0, "textAlign": null }`；indent 0～8；textAlign null\|left\|center\|right\|justify |
+| `heading` | `{ "level": 1, "indent": 0, "textAlign": null, "collapsed": false }`；level 1～6 |
+| `orderedList` | `{ "start": 1, "type": null }` |
+| `listItem` | `{ "collapsed": false }`；content 多为 paragraph，可再嵌套列表 |
+| `taskItem` | `{ "checked": false }` |
+| `codeBlock` | `{ "language": "plaintext", "wrap": false, "caption": "代码块", "collapsed": false, "regionFolds": [] }`；content 单 `text` |
+| `callout` | `{ "emoji": "💡", "backgroundColor": null, "borderColor": null }` |
+| `tableRow` | `{ "height": null }` |
+| `tableHeader` / `tableCell` | `{ "colspan": 1, "rowspan": 1, "colwidth": null, "align": null, "backgroundColor": null }`；格内多为 paragraph |
+| `blockquote` / `bulletList` / `taskList` / `table` / `horizontalRule` | 无 attrs；HR 无 content |
+| `hardBreak` | 无 attrs；落在 paragraph/heading 的 content 内 |
+| `columnBlock`（B） | `{ "widths": [50, 50] }`；2～5 个 `column`；widths.length = 列数 |
+| `column`（B） | 无 attrs；`block+` |
+| `image`（B） | `{ "src": "https://…", "mediaId": "", "alt": null, "title": null, "width": null, "height": null, "align": "left", "caption": "", "originalSrc": null, "uploadStatus": null, "uploadId": "" }`；**勿编造 mediaId / upload\***；src 仅 http(s) |
+
+## text / marks
+
+```json
+{ "type": "text", "text": "字", "marks": [{ "type": "bold" }] }
+```
+
+- `link`：`attrs` 含非空 `href`；建议 `target: "_blank"`, `rel: "noopener noreferrer nofollow"`, `class: "yos-docs-editor-link"`, `title: null`
+- `textStyle`：`{ "color": "#3370ff" }`
+- `highlight`：`{ "color": "#faf1d1" }`
+
+## 结构要点
+
+1. 列表：`bulletList`/`orderedList` → `listItem` → `paragraph`（再可选嵌套列表）。
+2. 任务：`taskList` → `taskItem` → `paragraph`。
+3. 表格：`table` → `tableRow` → `tableHeader`|`tableCell` → `paragraph`。
+4. 每个块尽量带齐默认 attrs（与编辑器 dump 一致，避免缺字段）。
+
+## few-shot
+
+见 [`few-shot.draft.json`](./few-shot.draft.json)（已通过 tier A 校验）。