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

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

@@ -0,0 +1,233 @@
+---
+name: yos-sheet
+description: YOS 云表格（在线表格）的正文编写规范（SheetWorkbook JSON 数据结构与列宽等推荐做法）。用户提到 yos/YOS 且要新建或修改知识库里的云表格（在线表格，非办公文件；即 docs create --type sheet 与 docs update 改云表格正文）时，先读本技能确定正文结构；云文档（在线文档）走 yos-doc 技能；上传办公文件（kb upload）与写 Markdown 文档（--type md）不需要本技能
+---
+
+# YOS 云表格编写（SheetWorkbook）
+
+**往 YOS 知识库写"云表格"（在线表格）的正文内容（新建或修改）前，必须先读本技能。** 云表格正文不是 CSV / Excel 文件，而是结构化 JSON（SheetWorkbook，对齐 `@yos/sheet-editor`），且服务端**不做 schema 校验**（原样存储）——结构写错要到客户端打开时才暴露；本技能自带官方校验器（§4），草稿写完先本地校验再上传。
+
+云文档（在线文档）的正文结构完全不同，见 `yos-doc` 技能。
+
+## 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-doc 技能） |
+| **写云表格（在线表格）** | `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 的 SheetWorkbook 结构写成本地文件（多行 JSON 不要用 `--content` 拼字符串）。**建表默认按 §2.4 估算并写入列宽**；写好后先用技能自带校验器过一遍（§4，含列宽的常规草稿用 `--tier B`）
+2. **上传**：
+
+   ```bash
+   # 新建（--parent 为目标文件夹编码，缺省库根；--kb 与 --parent 至少一个）
+   yos docs create "<标题>" --kb <kbCode> [--parent <folderCode>] --type sheet --file <草稿.json>
+
+   # 修改已有（正文整体覆盖：先读回完整正文，本地编辑后整体回传）
+   yos docs update <nodeCode> --title "<新标题>" --file <草稿.json>
+   ```
+
+3. **读回自查**：`yos docs content <nodeCode> --json` 确认 `docType=sheet` 与正文 JSON 完整落库、结构未变形
+
+## 2. SheetWorkbook JSON（--type sheet）
+
+### 2.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` 自拟唯一字符串即可
+- `appVersion` 固定 `0.25.1`、`locale` 固定 `zhCN`
+- `sheetOrder` 决定页签顺序（至少 1 项，id 必须在 `sheets` 中存在）；多页签时在 `sheets` 中并列多个表对象（每个表自己的 `name` ≤ 31 字符，Excel 限制）
+- `styles`：样式表（见 §2.5）；纯值和列宽表格可省略
+- `resources` 必须为 `[]`（禁止编造插件数据，见 §2.3）
+
+### 2.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` | 公式，须含前导 `=`（如 `=SUM(B2:B3)`）；建议同时用 `v` 写计算结果（客户端会重算） |
+| `s` | 样式 id（指向根 `styles`）或内联样式对象（见 §2.5） |
+
+禁止单元格字段：`p` / `si` / `ref` / `xf`（编辑器内核复杂字段）。
+
+### 2.3 工作表字段与能力全景
+
+工作表（`sheets` 中每个表对象）支持的能力分三类：
+
+**① 基础信息（值 / 公式类，直接写）**
+
+| 能力 | 字段 | 说明 |
+| ---- | ---- | ---- |
+| 多页签 | `sheetOrder` + `sheets` | `sheetOrder` 列页签顺序；多表时并列多个表对象 |
+| 单元格值 | `cellData` 的 `v` / `t` | §2.2 |
+| 公式 | `cellData` 的 `f` | 含前导 `=`；建议同带 `v` 预估值 |
+| 表尺寸 | `rowCount` / `columnCount` | 按实际规模写；`rowCount` ≤ 10000 |
+| 工作表隐藏 | `hidden` | `0` / `1` |
+| 网格线 | `showGridlines` | `0` / `1` |
+
+**② 版式能力（扩展字段）**
+
+| 能力 | 字段 | 使用时机 | 说明 |
+| ---- | ---- | -------- | ---- |
+| 列宽 | `columnData` 的 `w` | **建表默认写** | 按内容估算，§2.4 |
+| 行高 | `rowData` 的 `h` | 按需（表头行常用） | §2.4 |
+| 行 / 列隐藏 | `rowData` / `columnData` 的 `hd` | 按需 | `0` / `1` |
+| 表头与单元格样式 | 根 `styles` + 单元格 `s` | 按需（表头加样式很常见） | 粗体 / 背景 / 对齐 / 边框，§2.5 |
+| 数字格式 | 样式 `n.pattern` | 按需 | 如 `"0.00"`、`"#,##0"`、`"0%"`，§2.5 |
+| 合并单元格 | `mergeData` | 按需（如通栏大标题） | 左上角写值，§2.5 |
+| 冻结窗格 | `freeze` | 按需（长表冻结首行） | §2.5 |
+| 页签颜色 | `tabColor` | 按需 | 如 `"#3491FA"` |
+
+**③ 客户端交互能力（不写进草稿）**
+
+筛选、条件格式、数据验证、批注、超链接、图表等由用户在编辑器内操作产生、运行时写入 `resources` 插件数据——**草稿禁止手写 `resources`**（必须为 `[]`，禁止编造 `SHEET_*_PLUGIN` 数据）。xlsx 导入导出同为客户端能力：值 / 公式 / 基础样式 / 合并可保留，行列宽 / 条件格式 / 图表不保留。
+
+> 上表 ② 的字段均属校验器的 **tier B**；草稿用到任一（常规建表至少会写列宽）时校验用 `--tier B`（§4.1）。本文未列出的其余字段（`defaultColumnWidth`、`rowHeader` 等）与样式全量字段见 `references/SHEET_DATA_API.md`。
+
+### 2.4 列宽与行高（建表推荐默认）
+
+**列宽是建表默认动作**：不写列宽时所有列用编辑器默认宽（约 88px），中文长内容 / 日期 / 描述会显示不全，用户打开还需要逐列手动调整。按内容估算列宽，让表格一打开就可读。
+
+**按内容估算列宽**：
+
+1. 对每一列，取「表头文字 + 该列全部单元格」中最长的内容
+2. 中文每字约 16px，英文 / 数字 / 符号每字符约 9px，再加 16px 余量
+3. 结果夹在 64 ~ 320px；超长文本列（备注 / 描述）给 240 ~ 320px 即可，不必完整容纳长句
+4. 常用列型参考：序号 / 状态 64~80、日期 100~120、名称 / 人名 100~160、数量 / 金额 80~120、描述 / 备注 240~320
+
+**写法**（`columnData` 按列索引给 `w`，`rowData` 按行索引给 `h`；key 从 `0` 起，单位 px）：
+
+```json
+"columnData": { "0": { "w": 96 }, "1": { "w": 72 }, "2": { "w": 96 }, "3": { "w": 96 } },
+"rowData": { "0": { "h": 28 } }
+```
+
+- 每列都写上估算宽度（只写有内容的列即可，稀疏存储）；行高不写时用默认 24px，表头行加高到 28~32px 更醒目（配合表头样式见 §2.5）
+- 列宽 / 行高属扩展字段：**草稿写了 `columnData` / `rowData` 后校验用 `--tier B`**（§4.1）；只有极简纯值表（无列宽）才用默认 tier A
+
+### 2.5 扩展能力示例（样式 / 数字格式 / 合并 / 冻结 / 页签色）
+
+样式等扩展字段在**用户明确要求或有明确必要性**（如表头美化、通栏标题、长表冻结首行）时使用；综合形态如下（片段仅示增量字段，实际草稿按 §2.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" }`；全量样式字段（字体 / 字号 / 换行 / 旋转 / 内边距等）见 `references/SHEET_DATA_API.md` §4
+- 样式定义在根 `styles`（可复用），单元格 `s` 引用样式 id；表头统一样式最常用（示例中的 `header`）
+- `mergeData`：合并区左上角单元格写值，被合并覆盖的格子不写
+- `freeze`：冻结首行 `{ "xSplit": 0, "ySplit": 1, "startRow": 1, "startColumn": 0 }`；冻结首列把 `xSplit` 改 1、`startColumn` 改 1
+
+### 2.6 约束
+
+- `rowCount` ≤ 10000；按内容规模设置（简单表 100 行 × 20 列即可）
+- 禁止非空 `resources`、禁止编造 `SHEET_*_PLUGIN` 插件数据
+- 纯空表格用 §2.1 骨架即可（一张 sheet、`cellData` 留空对象）；不要用极简体 `{"id":"","sheetOrder":[],"sheets":{}}`（过不了校验器）
+
+## 3. 常见任务编排
+
+**新建云表格并落到指定文件夹**
+
+```bash
+yos kb list --keyword <库名>                 # 1. 拿 kbCode
+yos docs tree KBxxxx --json                  # 2. 找目标文件夹 resourceCode（须 resourceType=folder）
+#                                           3. 写草稿：按 §2 结构 + §2.4 估算列宽，如 draft.sheet.json
+yos docs create "值班排期表" --parent NDxxxx --type sheet --file draft.sheet.json
+yos docs content NDyyyy --json               # 4. 读回自查
+```
+
+**修改已有云表格的正文**（整体覆盖，保留未改动部分）
+
+```bash
+yos docs content NDyyyy --json               # 1. 取回完整正文 content
+#                                           2. 本地编辑目标单元格/列宽，其余原样保留
+yos docs update NDyyyy --title "标题" --file edited.sheet.json   # 3. 整体回传
+```
+
+改数据、列宽、样式都走同一份 SheetWorkbook 整体回传，不要试图只传增量的行列。
+
+## 4. 校验与避坑（实测）
+
+### 4.1 本地校验器（技能自带，先校验再上传）
+
+本技能自带与官方编辑器同源的校验器（Node ≥ 18，纯 ESM），用法（`<技能目录>` 即本 SKILL.md 所在目录）：
+
+```bash
+node "<技能目录>/scripts/yos-sheet.mjs" validate draft.json --tier A|B
+```
+
+- **常规建表草稿用 `--tier B`**：推荐默认写列宽（§2.4），而列宽与样式 / 合并 / 冻结 / 页签色等同属扩展字段（tier B）；只有不含任何扩展字段的纯值表才用默认 `--tier A`
+- 通过 exit 0；失败 exit 1 并逐条输出 `字段路径: 原因`；参数错误 exit 2
+- `schema` 子命令打印当前档位白名单（JSON）；`paths` 子命令打印 references 各文档的绝对路径
+
+### 4.2 参考文档（references/，全量契约）
+
+- `references/AGENT_SCHEMA.sheet.md`：官方 Agent 契约完整版（本文档的同源展开）
+- `references/SHEET_DATA_API.md`：编辑器全量数据 API（样式全字段、行列属性、resources 等本文未覆盖的字段查这里）
+- `references/few-shot.workbook.json`：可直接参考的草稿示例（按推荐做法带列宽，`--tier B` 通过）
+- `references/sheet-workbook.template.json` 仅作字段形态参考、不要照抄：tier B 全特性模板（`--tier B` 通过，简单表勿用）
+
+### 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-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 "<技能目录>/scripts/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. 建表推荐默认按内容估算列宽（列宽属 tier B，常规草稿校验用 `--tier B`）；纯值简表可用默认 A；表头样式 / 合并 / 冻结按需再加。
+4. **不要**手写插件 `resources`（筛选 / 条件格式等由用户在编辑器内操作后 `save()`）。
+
+## few-shot
+
+见 [`few-shot.workbook.json`](./few-shot.workbook.json)（按推荐做法带列宽，`--tier B` 通过校验）。  
+含样式 / 合并的完整骨架见 [`sheet-workbook.template.json`](./sheet-workbook.template.json)（需 `--tier B`）。