@yosai/cli 0.2.1-test.7 → 0.2.1-test.9

package/README.md

@@ -10,7 +10,7 @@ YOS 能力的 Agent 执行入口：终端直调 YOS 工具 + 知识库文件上
 ## 快速开始
 
 ```bash
-yos login                          # 配置访问令牌（客户端「个人设置-访问令牌」页创建并复制）与服务环境
+yos login                          # 配置访问令牌（客户端「个人设置-访问令牌」页创建并复制）
 yos doctor                         # 诊断配置与连通（显示当前身份）
 yos ping                           # 探活：连接与令牌有效性（退出码即结论，客户端对接用）
 yos kb list                        # 我的知识库
@@ -27,7 +27,7 @@ yos tool list                      # 底层工具通道（领域命令未覆盖
 
 | 命令 | 说明 |
 |---|---|
-| `yos login` | 配置访问令牌与服务环境（校验身份后保存） |
+| `yos login` | 配置访问令牌（校验身份后保存） |
 | `yos doctor` | 诊断配置、访问令牌、连通、Skill 状态与 CLI 版本 |
 | `yos ping` | 探活：检查连接是否成功、令牌是否有效（退出码 0/2/3/4 即结论，客户端检测对接用） |
 | `yos kb <动作>` | 知识库：`list` / `detail` / `update` / `upload`（建库、删库请到 YOS 客户端） |
@@ -37,7 +37,7 @@ yos tool list                      # 底层工具通道（领域命令未覆盖
 | `yos transcript <动作>` | 转写：`list` / `detail` |
 | `yos tool list` / `schema` / `call` | 底层工具通道（领域命令未覆盖时兜底） |
 | `yos version [--check]` | CLI 版本（`--check` 比对对应通道最新版） |
-| `yos update [--check]` | 手动升级到对应通道最新版并自动重同步 Skill（平时后台自动更新，一般无需执行） |
+| `yos update [--check]` | 升级到对应通道最新版并自动重同步 Skill（命令执行后检测到新版本会有升级提示，照提示执行即可） |
 | `yos skill install [--target <dir>]` | 安装内置 Skill |
 
 所有命令支持 `--json` 输出与统一退出码（0 成功 / 1 业务失败 / 2 参数错误 / 3 网络 / 4 鉴权 / 5 版本过低）。
@@ -45,7 +45,7 @@ yos tool list                      # 底层工具通道（领域命令未覆盖
 ## 给 Agent 使用
 
 ```bash
-yos skill install      # 安装 7 个内置 Skill（总入口 + 领域 + 安装引导）到 Claude Code / Cursor / Codex / Qoder / WorkBuddy 等技能目录
+yos skill install      # 安装 8 个内置 Skill（总入口 + 领域 + 安装引导）到 Claude Code / Cursor / Codex / Qoder / WorkBuddy 等技能目录
 ```
 
 安装后重启 Agent 工具，即可用自然语言驱动（如「把这份报告上传到知识库」）。`yos` 为能力总入口（何时使用 / 能力地图 / 命令使用方式），Agent 据此路由到各领域细则；`yos-shared` 收录跨领域约定（输出解析、退出码契约、仍需自行校验内容的场景、安全纪律）；`yos-install` 是自包含的安装配置引导，可单独下载到发布仓库供用户引导装机。
@@ -56,8 +56,8 @@ yos skill install      # 安装 7 个内置 Skill（总入口 + 领域 + 安装
 
 - 配置文件：`~/.config/yos/config.json`（权限 0600；目录可用 `YOS_CONFIG_DIR` 覆盖）
 - 环境变量（均优先于配置文件，适合 CI/容器场景）：`YOS_API_KEY` 访问令牌、`YOS_ENV` 服务环境（prod / test / dev）
-- 自动更新：命令执行后会在后台检查对应通道并静默更新到最新版（下次运行生效，自动重同步 Skill）；升级通道跟随服务环境——测试环境跟随 test 通道，dev 不自动更新；设置 `YOS_NO_AUTO_UPDATE=1` 可关闭
-- 服务环境：缺省生产；`yos login --env test` 切到测试环境，`--env dev` 指向本机开发服务（http://localhost:8080）；`yos doctor` 显示当前生效环境及其来源
+- 版本检查：命令执行后会在后台检查对应通道最新版，落后时以 stderr 提示「请先执行 yos update 升级再继续任务」；升级通道自动跟随服务环境（测试环境跟 test 通道）。CLI 不静默安装，升级由用户或 Agent 按提示显式执行
+- 服务环境（测试/开发用）：`yos login --env test` 切到测试环境，`--env dev` 指向本机开发服务（http://localhost:8080）
 
 ## 故障排查
 

package/dist/cli.js

@@ -187,6 +187,6 @@ export async function dispatch(argv) {
         return EXIT.BUSINESS;
     }
     finally {
-        handleUpdateNotice(argv, command.name);
+        handleUpdateNotice(command.name);
     }
 }

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { register } from '../cli.js';
 import { loadConfig, maskKey, resolveEnv, resolveKey } from '../config.js';
-import { endpointOfEnv, envLabel } from '../endpoints.js';
+import { DEFAULT_ENV, endpointOfEnv, envLabel } from '../endpoints.js';
 import { CliError, EXIT } from '../errors.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print, printJson } from '../output.js';
@@ -23,11 +23,13 @@ register({
             ok: config !== null,
             detail: config ? '已找到' : '未找到，请执行 yos login',
         });
-        checks.push({
-            name: '服务环境',
-            ok: true,
-            detail: `${envLabel(env)}（来自 ${endpointSource(config)}）`,
-        });
+        if (env !== DEFAULT_ENV) {
+            checks.push({
+                name: '服务环境',
+                ok: true,
+                detail: `${envLabel(env)}（来自 ${endpointSource(config)}）`,
+            });
+        }
         let key = null;
         try {
             key = resolveKey(config);
@@ -58,10 +60,11 @@ register({
             detail: skillDirs.length > 0 ? skillDirs.join(', ') : '尚未安装，执行 yos skill install',
         });
         const meta = readPackageMeta();
+        const envNote = env === DEFAULT_ENV ? '' : `（环境=${envLabel(env)}）`;
         checks.push({
             name: 'CLI 版本',
             ok: meta !== null,
-            detail: meta ? `${meta.version}（环境=${envLabel(env)}）` : 'unknown（未找到 package.json）',
+            detail: meta ? `${meta.version}${envNote}` : 'unknown（未找到 package.json）',
         });
         const state = loadVersionState();
         checks.push({

package/dist/commands/login.js

@@ -1,6 +1,6 @@
 import { register } from '../cli.js';
 import { loadConfig, maskKey, resolveEnv, saveConfig } from '../config.js';
-import { endpointOfEnv, envLabel } from '../endpoints.js';
+import { DEFAULT_ENV, endpointOfEnv, envLabel } from '../endpoints.js';
 import { UsageError } from '../errors.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print } from '../output.js';
@@ -30,6 +30,7 @@ register({
         }
         const identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
         saveConfig({ ...config, env, apiKey: key });
-        print(`已保存配置：环境=${envLabel(env)}，key=${maskKey(key)}，身份 ${formatIdentity(identity)}`);
+        const envNote = env === DEFAULT_ENV ? '' : `环境=${envLabel(env)}，`;
+        print(`已保存配置：${envNote}key=${maskKey(key)}，身份 ${formatIdentity(identity)}`);
     },
 });

package/dist/domain-commands.js

@@ -24,19 +24,28 @@ export const DOMAIN_COMMANDS = [
             },
             { flag: 'keyword', param: 'keyword', kind: 'string', description: '名称关键词（仅匹配库名，不搜正文）' },
             { flag: 'page', param: 'page', kind: 'number', description: '页码（缺省 1）', min: 1 },
-            { flag: 'size', param: 'size', kind: 'number', description: '每页条数（缺省 10，上限 50）', min: 1, max: 50 },
+            { flag: 'size', param: 'size', kind: 'number', description: '每页条数（缺省 50）', min: 1, max: 50, defaultValue: 50 },
         ],
         render: (result) => {
             const data = parseToolJson(result);
             const records = data.records ?? [];
+            const total = data.total ?? records.length;
+            const page = data.page ?? 1;
             if (records.length === 0) {
-                print('（无知识库）');
+                print(total > 0 ? `（本页无数据：共 ${total} 条，--page ${page} 超出范围）` : '（无知识库）');
                 return;
             }
             print(renderRows(records.map((r) => [
                 String(r.kbCode ?? r.kb_code ?? ''),
                 String(r.kbName ?? r.kb_name ?? r.name ?? ''),
             ])));
+            const shown = (page - 1) * (data.size ?? records.length) + records.length;
+            if (shown < total) {
+                print(`（共 ${total} 条，还有 ${total - shown} 条；翻页加 --page ${page + 1}）`);
+            }
+            else if (page > 1) {
+                print(`（共 ${total} 条，已到末页）`);
+            }
         },
     },
     {
@@ -116,7 +125,7 @@ export const DOMAIN_COMMANDS = [
             {
                 flag: 'type', param: 'doc_type', kind: 'string',
                 description: '文档类型（缺省 md）：md=Markdown 文本 / cloud=云文档 / sheet=表格；'
-                    + 'cloud 与 sheet 的正文须为对应草稿 JSON，一般场景一律用 md',
+                    + 'cloud 与 sheet 的正文为对应草稿 JSON（结构见 yos-doc-sheet 技能），一般场景一律用 md',
                 values: ['md', 'cloud', 'sheet'],
             },
             { flag: 'content', param: 'content', kind: 'string', description: '正文文本（与 --file 二选一）' },
@@ -154,7 +163,7 @@ export const DOMAIN_COMMANDS = [
         flags: [
             { flag: 'title', param: 'title', kind: 'string', description: '新标题' },
             { flag: 'content', param: 'content', kind: 'string', description: '新正文，整体覆盖原正文（与 --file 二选一）' },
-            { flag: 'file', param: 'content', kind: 'string', description: '新正文文件路径，整体覆盖原正文（与 --content 二选一）' },
+            { flag: 'file', param: 'content', kind: 'string', description: '新正文文件路径，整体覆盖原正文（与 --content 二选一）；云文档/云表格节点传对应草稿 JSON（结构见 yos-doc-sheet 技能）' },
             { flag: 'description', param: 'description', kind: 'string', description: '新简介（≤100 字）' },
         ],
         buildArgs: (context) => {

package/dist/domain-executor.js

@@ -35,6 +35,9 @@ function buildDeclaredArgs(spec, context) {
             if (flag.required) {
                 throw new UsageError(`缺少 --${flag.flag}`, `用法: ${buildUsageForSpec(spec)}`);
             }
+            if (flag.defaultValue !== undefined) {
+                args[flag.param] = flag.defaultValue;
+            }
             continue;
         }
         const values = Array.isArray(raw) ? raw : [raw];

package/dist/endpoints.js

@@ -22,12 +22,12 @@ export function channelOfEnv(env) {
 export function envLabel(env) {
     return ENVIRONMENTS[env]?.label ?? env;
 }
-export function labelOfEndpoint(endpoint) {
+export function envNoteOfEndpoint(endpoint) {
     const normalized = endpoint.replace(/\/+$/, '');
-    for (const env of Object.values(ENVIRONMENTS)) {
+    for (const [name, env] of Object.entries(ENVIRONMENTS)) {
         if (env.url === normalized) {
-            return env.label;
+            return name === DEFAULT_ENV ? '' : `（${env.label}）`;
         }
     }
-    return endpoint;
+    return `（${normalized}）`;
 }

package/dist/openapis-client.js

@@ -1,6 +1,6 @@
 import { readFile, stat } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { labelOfEndpoint } from './endpoints.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;
@@ -42,13 +42,13 @@ export class OpenApisClient {
             });
         }
         catch (e) {
-            throw new NetworkError(`无法连接 YOS 服务（${envLabelOfBase(this.base)}），原因：${e.message}`);
+            throw new NetworkError(`无法连接 YOS 服务${envNoteOfBase(this.base)}，原因：${e.message}`);
         }
         return parseEnvelope(response);
     }
 }
-function envLabelOfBase(base) {
-    return labelOfEndpoint(base.replace(/\/open-apis$/, ''));
+function envNoteOfBase(base) {
+    return envNoteOfEndpoint(base.replace(/\/open-apis$/, ''));
 }
 async function parseEnvelope(response) {
     if (response.status === 401) {
@@ -129,7 +129,7 @@ export async function uploadKnowledgeFile(endpoint, apiKey, filePath, kbCode, pa
         });
     }
     catch (e) {
-        throw new NetworkError(`无法连接 YOS 服务（${labelOfEndpoint(endpoint)}），原因：${e.message}`);
+        throw new NetworkError(`无法连接 YOS 服务${envNoteOfEndpoint(endpoint)}，原因：${e.message}`);
     }
     return parseEnvelope(response);
 }

package/dist/skill-sync.js

@@ -5,7 +5,7 @@ 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-knowledge', 'yos-retrieval', 'yos-transcript', 'yos-support', 'yos-install'];
+export const BUILTIN_SKILLS = ['yos', 'yos-shared', 'yos-knowledge', 'yos-doc-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));

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,13 +10,13 @@ YOS 是企业 AI 底座：公司知识、会议录音、帮助手册等能力都
 ## 0. 开工前先确认环境（30 秒）
 
 ```bash
-yos doctor      # 七项 ✓ 才继续：配置文件 / 服务环境 / 访问令牌 / 服务连通（回显身份）/ Skill 安装 / CLI 版本 / Skill 同步
+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`）；CLI 会后台自动更新（跟随当前环境通道，无需手动升级），需要立即升级用 `yos update`
+- 已装但检查项没全 ✓ → 先修好再执行任务；`yos doctor` 的失败项自带修复提示
+- 查版本用 `yos version`（或 `yos --version`）；命令执行后 stderr 若出现「提示: 有新版本」，先执行 `yos update` 升级再继续任务（约定详见 yos-shared）
 
 ## 1. 意图路由
 
@@ -28,6 +28,7 @@ yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴
 | 浏览/搜索自己的知识库与文档内容 | `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/sheet`、`docs update` | **先读 yos-doc-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 +42,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-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` 回显
@@ -50,8 +51,8 @@ yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴
 
 1. 用户在 YOS 客户端「个人设置-访问令牌」页创建并复制令牌（40 位小写 hex）
 2. `yos login` 交互粘贴（不回显）；Agent 代执行时用 `yos login --key <令牌>`
-3. 配置文件 `~/.config/yos/config.json`（0600）。环境变量**优先于配置文件**：`YOS_CONFIG_DIR`（换配置目录）、`YOS_API_KEY`（换令牌）、`YOS_ENV`（换服务环境，如 test）
-4. 服务环境缺省生产，切换用 `yos login --env test`（临时可用 `YOS_ENV=test`）；开发者本地调试用 `--env dev`（指向本机 8080 起的服务）；`yos doctor` 会显示当前生效环境及其来源
+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 +70,13 @@ yos kb upload ./报告.pdf --kb KB20261009000001             # 单文件上传
 yos docs download ND20261009000012 --out ./归档/            # 取回上传的原文件（仅 docType=file）
 yos docs count ND20261009000012                            # 删除前查影响范围
 
+# 往知识库写云文档 / 云表格（正文是结构化 JSON 而非文本；动手前先读 yos-doc-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

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

@@ -0,0 +1,330 @@
+---
+name: yos-doc-sheet
+description: YOS 云文档与云表格的正文编写规范（DocDraft / SheetWorkbook JSON 数据结构）。用户提到 yos/YOS 且要新建或修改知识库里的云文档、云表格（在线文档/在线表格，非办公文件；即 docs create --type cloud/sheet 与 docs update 改正文）时，先读本技能确定正文结构；上传办公文件（kb upload）与写 Markdown 文档（--type md）不需要本技能
+---
+
+# YOS 云文档与云表格编写（DocDraft / SheetWorkbook）
+
+**往 YOS 知识库写"云文档"或"云表格"的正文内容（新建或修改）前，必须先读本技能。** 两者的正文不是纯文本，而是结构化 JSON（不是 Markdown / HTML / CSV），且服务端**不做 schema 校验**（原样存储）——结构写错要到客户端打开时才暴露；本技能自带官方校验器（§5），草稿写完先本地校验再上传。
+
+## 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 docs mkdir/rename/move/delete/restore` | 否（见 yos-knowledge） |
+
+判断一个已有节点属于哪类：`docs tree` / `docs content` 的 `docType` 字段——`cloud` = 云文档、`sheet` = 云表格、`md` = Markdown、`file` = 上传的办公文件。
+
+## 1. 三步流程
+
+1. **写 JSON 草稿**：云文档按 §2 的 DocDraft 结构；云表格按 §3 的 SheetWorkbook 结构。草稿一律落成本地文件（多行 JSON 不要用 `--content` 拼字符串），写好后先用技能自带校验器过一遍（§5）
+2. **上传**：
+
+   ```bash
+   # 新建（--parent 为目标文件夹编码，缺省库根；--kb 与 --parent 至少一个）
+   yos docs create "<标题>" --kb <kbCode> [--parent <folderCode>] --type cloud|sheet --file <草稿.json>
+
+   # 修改已有（正文整体覆盖：先读回完整正文，本地编辑后整体回传）
+   yos docs update <nodeCode> --title "<新标题>" --file <草稿.json>
+   ```
+
+3. **读回自查**：`yos docs content <nodeCode> --json` 确认 `docType`（cloud/sheet）与正文 JSON 完整落库、结构未变形
+
+## 2. 云文档（--type cloud）—— DocDraft JSON
+
+对齐编辑器：`@yos/doc-editor`。
+
+### 2.1 顶层结构
+
+```json
+{
+  "title": "文档标题",
+  "attachments": [],
+  "content": { "type": "doc", "content": [] }
+}
+```
+
+- `title`：与 `docs create` 的标题参数保持一致
+- `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）
+
+## 3. 云表格（--type sheet）—— SheetWorkbook JSON
+
+对齐编辑器：`@yos/sheet-editor`。
+
+### 3.1 顶层结构
+
+```json
+{
+  "id": "workbook-id",
+  "name": "工作簿名称",
+  "appVersion": "0.25.1",
+  "locale": "zhCN",
+  "styles": {},
+  "sheetOrder": ["sheet-1"],
+  "sheets": {
+    "sheet-1": {
+      "id": "sheet-1",
+      "name": "Sheet1",
+      "rowCount": 100,
+      "columnCount": 20,
+      "cellData": {}
+    }
+  },
+  "resources": []
+}
+```
+
+- `name`：与 `docs create` 的标题参数保持一致；`id` 自拟唯一字符串即可；工作表 `name` ≤ 31 字符（Excel 限制）
+- `appVersion` 固定 `0.25.1`、`locale` 固定 `zhCN`
+- `sheetOrder` 决定页签顺序（至少 1 项，id 必须在 `sheets` 中存在）；多页签时在 `sheets` 中并列多个表对象
+- `styles`：tier B 样式表（见 3.4）；纯值表格省略即可
+- `resources` 必须为 `[]`（禁止编造插件数据）
+
+### 3.2 单元格 cellData
+
+`{ "行索引": { "列索引": { 字段 } } }`——行列索引从 `0` 起、以字符串作键，稀疏存储（空行 / 空列不写）：
+
+```json
+"cellData": {
+  "0": { "0": { "v": "项目", "t": 1 }, "1": { "v": "数量", "t": 1 } },
+  "1": { "0": { "v": "示例 A", "t": 1 }, "1": { "v": 2, "t": 2 } },
+  "2": { "2": { "f": "=B2*2", "v": 4, "t": 2 } }
+}
+```
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `v` | 显示 / 原始值：string / number / boolean / null |
+| `t` | 类型：`1` 文本 / `2` 数字 / `3` 布尔 / `4` 强制文本（建议显式写） |
+| `f` | 公式，须含前导 `=`；建议同时用 `v` 写计算结果（客户端会重算） |
+| `s` | 仅 tier B：样式 id（指向根 `styles`）或内联样式对象 |
+
+禁止单元格字段：`p` / `si` / `ref` / `xf`（编辑器内核复杂字段）。
+
+### 3.3 工作表字段档位
+
+| 字段 | 档 | 说明 |
+| ---- | -- | ---- |
+| `id` / `name` | A | 必有；name ≤ 31 字符 |
+| `rowCount` / `columnCount` | A | 建议写；rowCount ≤ 10000 |
+| `cellData` | A | 稀疏单元格 |
+| `hidden` / `showGridlines` | A | 0 / 1 |
+| `styles`（根）+ 单元格 `s` | B | 样式表 + 引用 |
+| `mergeData` | B | 合并单元格 |
+| `freeze` | B | 冻结行列 |
+| `rowData` / `columnData` | B | 行高 `h` / 列宽 `w` |
+| `tabColor` | B | 页签颜色，如 `"#3491FA"` |
+
+tier B 字段仅在用户明确要求（如"表头加样式""调整列宽""冻结首行"）时使用；其余工作表字段（defaultColumnWidth 等）见 `references/SHEET_DATA_API.md`。
+
+### 3.4 tier B 结构（用户明确要求时）
+
+样式表 + 合并 + 冻结 + 列宽 + 页签色综合形态（片段仅示增量字段，实际草稿按 3.1 骨架补全 id/appVersion/locale/sheetOrder/resources 等）：
+
+```json
+{
+  "styles": {
+    "header": { "bl": 1, "ht": 2, "bg": { "rgb": "#E8F3FF" }, "cl": { "rgb": "#1F2329" } },
+    "number": { "ht": 3, "n": { "pattern": "0.00" } }
+  },
+  "sheets": {
+    "sheet-1": {
+      "tabColor": "#3491FA",
+      "freeze": { "xSplit": 0, "ySplit": 1, "startRow": 1, "startColumn": 0 },
+      "mergeData": [{ "startRow": 0, "startColumn": 0, "endRow": 0, "endColumn": 3 }],
+      "rowData": { "0": { "h": 30 } },
+      "columnData": { "0": { "w": 120 }, "1": { "w": 96 } },
+      "cellData": {
+        "0": { "0": { "v": "销售明细", "t": 1, "s": "header" } },
+        "1": { "0": { "v": "数量", "t": 1, "s": "header" }, "1": { "v": 2, "t": 2 } },
+        "2": { "0": { "v": "示例 A", "t": 1 }, "1": { "v": 2, "t": 2 }, "2": { "f": "=B3*2", "v": 4, "t": 2, "s": "number" } }
+      }
+    }
+  }
+}
+```
+
+- 样式常用键：`bl` 粗体、`it` 斜体、`bg` 背景色、`cl` 前景色、`ht` 水平对齐（2=居中）、`vt` 垂直对齐、`n.pattern` 数字格式、`bd` 边框；颜色写成 `{ "rgb": "#E8F3FF" }`
+- `mergeData`：合并区左上角单元格写值，被合并覆盖的格子不写
+- `freeze`：冻结首行 `{ "xSplit": 0, "ySplit": 1, "startRow": 1, "startColumn": 0 }`
+- 行高 / 列宽：`rowData`/`columnData` 按行 / 列索引给 `h` / `w`（单位 px）
+
+### 3.5 约束
+
+- `rowCount` ≤ 10000；按内容规模设置（简单表 100 行 × 20 列即可）
+- 禁止非空 `resources`、禁止编造 `SHEET_*_PLUGIN` 插件数据
+- 纯空表格骨架（仅建空表时用）：`{"id":"","sheetOrder":[],"sheets":{}}`
+
+## 4. 常见任务编排
+
+**新建云文档并落到指定文件夹**
+
+```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. 整体回传
+```
+
+**云表格**同理：草稿换成 §3 的 SheetWorkbook 结构、`--type sheet`；修改同样走 `docs update` 整体覆盖。
+
+## 5. 校验与避坑（实测）
+
+### 5.1 本地校验器（技能自带，先校验再上传）
+
+本技能自带与官方编辑器同源的校验器（Node ≥ 18，纯 ESM），用法（`<技能目录>` 即本 SKILL.md 所在目录）：
+
+```bash
+node "<技能目录>/scripts/yos-sheet.mjs" validate draft.json --tier A|B   # 云表格
+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 各文档的绝对路径
+
+### 5.2 参考文档（references/，全量契约）
+
+- `references/AGENT_SCHEMA.sheet.md`、`references/AGENT_SCHEMA.doc.md`：官方 Agent 契约完整版（本文档的同源展开）
+- `references/SHEET_DATA_API.md`、`references/DOC_DATA_API.md`：编辑器全量数据 API（本文档未覆盖的字段查这里）
+- `references/few-shot.workbook.json`、`references/few-shot.draft.json`：可直接参考的草稿示例（均过 tier A 校验）
+- 两个模板仅作字段形态参考、不要照抄：`sheet-workbook.template.json` 是 tier B 全特性模板（`--tier B` 通过，简单表勿用）；`doc-draft.template.json` 是编辑器全量能力演示（含 attachments、glossaryTerm、禁止节点），任何档位都无法直接通过校验，其中 `attachments` 非空仅为展示、写草稿必须为 `[]`
+
+### 5.3 避坑
+
+- **没有在线校验**：CLI 与服务端都不校验正文 schema，写入即原样存储。自查手段：草稿先过 5.1 校验器或本地 JSON 语法（如 `jq . draft.json`）→ 上传后 `docs content --json` 读回核对结构
+- `docs content` 读回的 `content` 是 **JSON 字符串**，需对 `text` 再 `JSON.parse` 两次（外层信封 + content 字符串）
+- `docs update` 的正文是**整体覆盖**不是局部替换——改一处也要先取全文再整体回传，否则其余内容会丢
+- 渲染效果（尤其高级结构、代码块、表格样式）以 YOS 客户端打开为准；发现渲染异常先确认草稿结构，必要时用 `yos support feedback` 反馈
+- 同一文件重复上传不会去重；同名云文档可并存，创建前可先 `docs tree` 看目标位置是否已有同名节点