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

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`）。