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

package/README.md

@@ -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` 是自包含的安装配置引导，可单独下载到发布仓库供用户引导装机。

package/dist/skills/yos/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: yos
-description: YOS 企业 AI 能力总入口：公司/部门/工作/个人等各类知识的检索与文档管理、录音转写、帮助手册、客户端升级与反馈。用户提到 yos/YOS/小y 即使用本技能；用户问制度/流程/规范、要查或整理资料文档、要看会议录音转写、需要 YOS 客户端帮助时使用；不确定该用哪个 YOS 能力时先读本文件
+description: YOS 企业 AI 能力总入口：公司/部门/工作/个人等各类知识的检索与文档管理、云文档/云表格编写、录音转写、帮助手册、客户端升级与反馈。用户提到 yos/YOS 即使用本技能；用户问制度/流程/规范、要查或整理资料文档、要写云文档/云表格、要看会议录音转写、需要 YOS 客户端帮助时使用；不确定该用哪个 YOS 能力时先读本文件
 ---
 
 # YOS 能力总入口
 
-YOS 是企业 AI 底座：公司知识、会议录音、帮助手册等能力都可通过本机 `yos` 命令查询与操作（呼出别名「小y」，用户提 yos / 小y 均指本能力）。本文件只做**路由与前置判断**，每个命令的参数、返回字段、报错都在对应领域 skill 里，执行前务必读那一本。
+YOS 是企业 AI 底座：公司知识、会议录音、帮助手册等能力都可通过本机 `yos` 命令查询与操作。本文件只做**路由与前置判断**，每个命令的参数、返回字段、报错都在对应领域 skill 里，执行前务必读那一本。
 
 ## 0. 开工前先确认环境（30 秒）
 
@@ -42,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` 回显
@@ -70,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

@@ -1,11 +1,11 @@
 ---
 name: yos-doc-sheet
-description: YOS 云文档与云表格的正文编写规范（DocDraft / SheetWorkbook JSON 数据结构）。用户提到 yos/YOS/小y 且要新建或修改知识库里的云文档、云表格（在线文档/在线表格，非办公文件；即 docs create --type cloud/sheet 与 docs update 改正文）时，先读本技能确定正文结构；上传办公文件（kb upload）与写 Markdown 文档（--type md）不需要本技能
+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 校验**（原样存储）——结构写错要到客户端打开时才暴露。
+**往 YOS 知识库写"云文档"或"云表格"的正文内容（新建或修改）前，必须先读本技能。** 两者的正文不是纯文本，而是结构化 JSON（不是 Markdown / HTML / CSV），且服务端**不做 schema 校验**（原样存储）——结构写错要到客户端打开时才暴露；本技能自带官方校验器（§5），草稿写完先本地校验再上传。
 
 ## 0. 适用边界（先分清楚再动手）
 
@@ -21,7 +21,7 @@ description: YOS 云文档与云表格的正文编写规范（DocDraft / SheetWo
 
 ## 1. 三步流程
 
-1. **写 JSON 草稿**：云文档按 §2 的 DocDraft 结构；云表格按 §3 的 SheetWorkbook 结构。草稿一律落成本地文件（多行 JSON 不要用 `--content` 拼字符串）
+1. **写 JSON 草稿**：云文档按 §2 的 DocDraft 结构；云表格按 §3 的 SheetWorkbook 结构。草稿一律落成本地文件（多行 JSON 不要用 `--content` 拼字符串），写好后先用技能自带校验器过一遍（§5）
 2. **上传**：
 
    ```bash
@@ -52,7 +52,17 @@ description: YOS 云文档与云表格的正文编写规范（DocDraft / SheetWo
 - `attachments`：必须为 `[]`（禁止非空、禁止编造 mediaId）
 - `content`：TipTap 文档树，`type` 固定为 `doc`，节点放 `content` 数组
 
-### 2.2 常用节点（实测可正常落库）
+### 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` 建议保留为下述形态）：
 
@@ -60,46 +70,104 @@ description: YOS 云文档与云表格的正文编写规范（DocDraft / SheetWo
 {"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"正文内容"}]}
 ```
 
-标题（`level` 1~3）：
+标题（`level` 1~6）：
 
 ```json
-{"type":"heading","attrs":{"level":2,"textAlign":null},"content":[{"type":"text","text":"小节标题"}]}
+{"type":"heading","attrs":{"level":2,"indent":0,"textAlign":null,"collapsed":false},"content":[{"type":"text","text":"小节标题"}]}
 ```
 
-无序列表（`bulletList` → `listItem` → `paragraph`，可嵌套）：
+无序列表（`bulletList` → `listItem` → `paragraph`，可嵌套；有序列表把 type 换成 `orderedList` 并加 `attrs":{"start":1,"type":null}`，其余相同）：
 
 ```json
 {"type":"bulletList","content":[
-  {"type":"listItem","content":[
+  {"type":"listItem","attrs":{"collapsed":false},"content":[
     {"type":"paragraph","attrs":{"indent":0,"textAlign":null},"content":[{"type":"text","text":"列表项"}]}
   ]}
 ]}
 ```
 
-引用（`blockquote` 内放 `paragraph`）：
+任务列表（`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":null},"content":[{"type":"text","text":"yos kb list\nyos doctor"}]}
+{"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"}]}
+    ]}
+  ]}
+]}
 ```
 
-行内样式用 `marks`（可叠加，如加粗+斜体同放数组）：
+分隔线与强制换行：`{"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":"链接"}
 ```
 
-### 2.3 禁止与注意事项
+可叠加：加粗+斜体同放数组，如 `[{"type":"bold"},{"type":"italic"}]`。
+
+### 2.6 禁止与注意事项
 
-- 禁止节点：`mindmap`、`flowchart`、`video`、`audio`、`file`、`glossaryTerm`
-- 默认只写基础结构（tier A）；分栏、外链图等高级布局（tier B）仅在用户明确要求时使用
-- **不要以 Markdown 作为最终产物**：先定内容结构再落成上述节点 JSON；转换时逐段映射（标题→heading、列表→bulletList、引用→blockquote）
+- 禁止节点：`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
 
@@ -113,6 +181,7 @@ description: YOS 云文档与云表格的正文编写规范（DocDraft / SheetWo
   "name": "工作簿名称",
   "appVersion": "0.25.1",
   "locale": "zhCN",
+  "styles": {},
   "sheetOrder": ["sheet-1"],
   "sheets": {
     "sheet-1": {
@@ -127,27 +196,85 @@ description: YOS 云文档与云表格的正文编写规范（DocDraft / SheetWo
 }
 ```
 
-- `name`：与 `docs create` 的标题参数保持一致；`id` 自拟唯一字符串即可
+- `name`：与 `docs create` 的标题参数保持一致；`id` 自拟唯一字符串即可；工作表 `name` ≤ 31 字符（Excel 限制）
 - `appVersion` 固定 `0.25.1`、`locale` 固定 `zhCN`
-- `sheetOrder` 决定页签顺序；多页签时在 `sheets` 中并列多个表对象
-- `resources` 必须为 `[]`
+- `sheetOrder` 决定页签顺序（至少 1 项，id 必须在 `sheets` 中存在）；多页签时在 `sheets` 中并列多个表对象
+- `styles`：tier B 样式表（见 3.4）；纯值表格省略即可
+- `resources` 必须为 `[]`（禁止编造插件数据）
 
-### 3.2 cellData（Univer 结构）
+### 3.2 单元格 cellData
 
-`{ "行索引": { "列索引": { "v": 值 } } }`——行列索引从 `0` 起、以字符串作键，只写有值的单元格：
+`{ "行索引": { "列索引": { 字段 } } }`——行列索引从 `0` 起、以字符串作键，稀疏存储（空行 / 空列不写）：
 
 ```json
 "cellData": {
-  "0": { "0": { "v": "项目" }, "1": { "v": "说明" } },
-  "1": { "0": { "v": "云文档" }, "1": { "v": "DocDraft JSON 存储" } }
+  "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 } }
 }
 ```
 
-### 3.3 约束
+| 字段 | 说明 |
+| ---- | ---- |
+| `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 约束
 
-- 单元格只写 `v`（值），不写 `p` / `si` 等复杂字段；样式、合并、冻结等（tier B）仅在用户明确要求时使用
 - `rowCount` ≤ 10000；按内容规模设置（简单表 100 行 × 20 列即可）
-- 禁止非空 `resources`、禁止编造插件数据
+- 禁止非空 `resources`、禁止编造 `SHEET_*_PLUGIN` 插件数据
 - 纯空表格骨架（仅建空表时用）：`{"id":"","sheetOrder":[],"sheets":{}}`
 
 ## 4. 常见任务编排
@@ -174,7 +301,29 @@ yos docs update NDyyyy --title "标题" --file edited.yosdoc.json   # 3. 整体
 
 ## 5. 校验与避坑（实测）
 
-- **没有在线校验**：CLI 与服务端都不校验正文 schema，写入即原样存储。自查手段：草稿先本地过 JSON 语法（如 `jq . draft.json`）→ 上传后 `docs content --json` 读回核对结构
+### 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` 反馈

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

@@ -0,0 +1,68 @@
+# Agent DocDraft 精简契约
+
+> 完整字段见同包 [`DOC_DATA_API.md`](../DOC_DATA_API.md)。Agent **只读本文 + few-shot**，勿整份塞入 prompt。  
+> 校验：`node packages/doc-editor/bin/yos-doc.mjs validate <file.json> [--tier A|B]`
+
+## 输出根形状
+
+```json
+{
+  "title": "文档标题",
+  "attachments": [],
+  "content": { "type": "doc", "content": [/* 块节点 */] }
+}
+```
+
+- `attachments` 必须为 `[]`（媒体由宿主 `DocMediaHooks` 上传）。
+- `content.type` 必须为 `"doc"`。
+
+## 档位
+
+| 档 | 节点 | 默认 |
+| -- | ---- | ---- |
+| **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 校验）。

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

@@ -0,0 +1,105 @@
+# Agent SheetWorkbook 精简契约
+
+> 完整字段见同包 [`SHEET_DATA_API.md`](../SHEET_DATA_API.md)。Agent **只读本文 + few-shot**，勿整份塞入 prompt。  
+> 校验：`node packages/sheet-editor/bin/yos-sheet.mjs validate <file.json> [--tier A|B]`
+
+## 输出根形状
+
+```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": []
+}
+```
+
+- 宿主加载：`sheetEditorRef.loadSnapshot(workbook)`（或 prop `workbook`）。
+- `resources` 必须为 `[]` 或省略（禁止编造插件状态）。
+- `sheetOrder` 中每个 id 必须在 `sheets` 中存在；`sheets[id].id` 建议与 key 一致。
+
+## 档位
+
+| 档 | 允许内容 | 默认 |
+| -- | -------- | ---- |
+| **A** | 值 / 公式：`cellData` 的 `v` / `f` / `t`；基本表尺寸 | 默认开启 |
+| **B** | + `styles`、单元格 `s`、`mergeData`、`freeze`、`rowData` / `columnData`、页签色等 | `--tier B` |
+| **禁止** | 非空 `resources`、编造 `SHEET_*_PLUGIN` 数据、`rowCount` > 10000 | 永远禁止 |
+
+## 单元格（`ICellData`）
+
+```json
+{ "v": "品名", "t": 1 }
+{ "v": 10.5, "t": 2 }
+{ "f": "=B2*C2", "v": 21, "t": 2 }
+```
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `v` | 显示 / 原始值（`string` \| `number` \| `boolean` \| `null`） |
+| `t` | `1` STRING / `2` NUMBER / `3` BOOLEAN / `4` FORCE_STRING |
+| `f` | 公式，须含前导 `=` |
+| `s` | **仅 tier B**：样式 id（指向根 `styles`）或内联样式对象 |
+
+`cellData` 为稀疏矩阵，行 / 列均为 **0-based** 数字键（字符串或数字均可）：
+
+```json
+{
+  "0": { "0": { "v": "列1", "t": 1 }, "1": { "v": 2, "t": 2 } },
+  "1": { "3": { "f": "=B2*C2", "v": 20, "t": 2 } }
+}
+```
+
+空行 / 空列不要写入。
+
+## 工作表常用字段
+
+| 字段 | 档 | 说明 |
+| ---- | -- | ---- |
+| `id` / `name` | A | 必有；`name` ≤ 31 字符（Excel 限制） |
+| `rowCount` / `columnCount` | A | 建议写；`rowCount` ≤ 10000 |
+| `cellData` | A | 稀疏单元格 |
+| `hidden` / `showGridlines` | A | `BooleanNumber`：`0` / `1` |
+| `styles`（根）+ 单元格 `s` | B | 样式表 + 引用 |
+| `mergeData` | B | `{ startRow, startColumn, endRow, endColumn }` |
+| `freeze` | B | 如冻结首行：`{ xSplit:0, ySplit:1, startRow:1, startColumn:0 }` |
+| `rowData` / `columnData` | B | 行高 `h` / 列宽 `w` 等 |
+| `tabColor` | B | 页签颜色，如 `"#3491FA"` |
+
+## 样式（tier B）
+
+挂在根 `styles`，单元格 `s` 写样式 id：
+
+```json
+{
+  "styles": {
+    "header": { "bl": 1, "ht": 2, "bg": { "rgb": "#E8F3FF" } }
+  }
+}
+```
+
+常用：`bl` 粗体、`it` 斜体、`bg`/`cl` 背景/前景、`ht` 水平对齐（`2` CENTER）、`vt` 垂直对齐、`n.pattern` 数字格式。
+
+## 结构要点
+
+1. 至少一张 sheet；`sheetOrder.length >= 1`。
+2. 公式格建议同时带计算结果 `v`（可先估，运行时会重算）。
+3. 默认档 A 即可完成多数表格；需要表头样式 / 合并 / 冻结时再升 B。
+4. **不要**手写插件 `resources`（筛选 / 条件格式等由用户在编辑器内操作后 `save()`）。
+
+## few-shot
+
+见 [`few-shot.workbook.json`](./few-shot.workbook.json)（已通过 tier A 校验）。  
+含样式 / 合并的完整骨架见 [`fixtures/sheet-workbook.template.json`](../fixtures/sheet-workbook.template.json)（需 `--tier B`）。