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

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

@@ -0,0 +1,624 @@
+# 文档页数据字段全量枚举
+
+> 按 TipTap JSON 的 **`type` 逐个列出全部 `attrs`（及 `text` / `marks`）** 与含义。  
+> 依据：本仓库扩展源码 + TipTap/StarterKit 默认字段；形态对照真实草稿（如 `paragraph` + `attrs`）。  
+> 正文无内嵌服务端 HTTP；媒体二进制经宿主 `DocMediaHooks`（或 Demo IndexedDB）。本文是草稿 JSON 契约。存储键见文末。  
+> **Agent 生成请用精简契约** [`AGENT_SCHEMA.doc.md`](./AGENT_SCHEMA.doc.md) + `node "<技能目录>/scripts/yos-doc.mjs" validate`，勿把本文整份塞进 prompt。
+
+---
+
+## 0. 节点通用形
+
+```json
+{
+  "type": "<节点名>",
+  "attrs": {},
+  "content": [],
+  "marks": [],
+  "text": "仅 text 节点"
+}
+```
+
+| 字段      | 含义                                    |
+| --------- | --------------------------------------- |
+| `type`    | 节点/标记种类                           |
+| `attrs`   | 该 type 的参数表；无参数时可省略或 `{}` |
+| `content` | 子节点数组                              |
+| `marks`   | 仅挂在 `text` 上的行内样式              |
+| `text`    | 纯文本内容（仅 `type: "text"`）         |
+
+草稿根：
+
+```json
+{
+  "title": "文档标题（不在 doc 树内）",
+  "content": { "type": "doc", "content": [/* 块节点 */] }
+}
+```
+
+---
+
+## 1. `doc`（根）
+
+| 参数         | 有无 | 说明         |
+| ------------ | ---- | ------------ |
+| （无 attrs） | —    | 根容器       |
+| `content`    | 必有 | 块级节点列表 |
+
+---
+
+## 2. `paragraph`（段落）
+
+```json
+{
+  "type": "paragraph",
+  "attrs": { "indent": 0, "textAlign": null },
+  "content": [{ "type": "text", "text": "…" }]
+}
+```
+
+| 参数        | 类型             | 默认   | 含义                         | 取值                                                            |
+| ----------- | ---------------- | ------ | ---------------------------- | --------------------------------------------------------------- |
+| `indent`    | `number`         | `0`    | 段落左缩进级数（非列表嵌套） | `0`～`8`；每级 24px                                             |
+| `textAlign` | `string \| null` | `null` | 水平对齐                     | `null`（未设）/ `"left"` / `"center"` / `"right"` / `"justify"` |
+| `content`   | 节点[]           |        | 行内：`text` 等              | 可空（空段）                                                    |
+
+---
+
+## 3. `heading`（标题）
+
+| 参数        | 类型             | 默认    | 含义                         | 取值              |
+| ----------- | ---------------- | ------- | ---------------------------- | ----------------- |
+| `level`     | `number`         | `1`     | 标题级别                     | `1`～`6`（H1–H6） |
+| `indent`    | `number`         | `0`     | 缩进级数                     | `0`～`8`          |
+| `textAlign` | `string \| null` | `null`  | 对齐                         | 同 paragraph      |
+| `collapsed` | `boolean`        | `false` | 是否折叠本节（至同级/更高级标题前） | `true` / `false`  |
+| `content`   | 节点[]           |         | 行内文本                     |                   |
+
+```json
+{
+  "type": "heading",
+  "attrs": { "level": 1, "indent": 0, "textAlign": null, "collapsed": false },
+  "content": [{ "type": "text", "text": "一级标题" }]
+}
+```
+
+---
+
+## 4. `blockquote`（引用）
+
+| 参数         | 有无 | 含义                           |
+| ------------ | ---- | ------------------------------ |
+| （无 attrs） | —    | 左侧竖线引用块                 |
+| `content`    | 必有 | 一块或多块（多为 `paragraph`） |
+
+---
+
+## 5. `horizontalRule`（分割线）
+
+| 参数         | 有无 | 含义                          |
+| ------------ | ---- | ----------------------------- |
+| （无 attrs） | —    | 水平分割线 atom，无 `content` |
+
+```json
+{ "type": "horizontalRule" }
+```
+
+---
+
+## 5.1 `hardBreak`（软换行）
+
+| 参数         | 有无 | 含义                                    |
+| ------------ | ---- | --------------------------------------- |
+| （无 attrs） | —    | 行内硬换行（Shift+Enter），无 `content` |
+
+```json
+{ "type": "hardBreak" }
+```
+
+> 属 StarterKit 内联节点；落在 `paragraph` / `heading` 等的 `content` 里，与 `text` 并列。
+
+---
+
+## 6. `bulletList`（无序列表）
+
+| 参数         | 有无 | 含义                                     |
+| ------------ | ---- | ---------------------------------------- |
+| （无 attrs） | —    | 项目符号列表                             |
+| `content`    | 必有 | `listItem` 数组；可多层嵌套 `bulletList` |
+
+---
+
+## 7. `orderedList`（有序列表）
+
+| 参数      | 类型             | 默认   | 含义            | 取值                                           |
+| --------- | ---------------- | ------ | --------------- | ---------------------------------------------- |
+| `start`   | `number`         | `1`    | 起始序号        | 正整数                                         |
+| `type`    | `string \| null` | `null` | HTML ol 的 type | 本 Demo 常为 `null`（由层级样式控制 1./a./i.） |
+| `content` | 节点[]           |        | `listItem` 列表 |                                                |
+
+---
+
+## 8. `listItem`（列表项）
+
+| 参数        | 类型      | 默认    | 含义                                           | 取值             |
+| ----------- | --------- | ------- | ---------------------------------------------- | ---------------- |
+| `collapsed` | `boolean` | `false` | 是否折叠本项下嵌套的有序/无序列表              | `true` / `false` |
+| `content`   | 节点[]    |         | 通常为 `paragraph`/`heading`，其后可再跟嵌套列表 |                  |
+
+```json
+{
+  "type": "listItem",
+  "attrs": { "collapsed": false },
+  "content": [
+    { "type": "paragraph", "content": [{ "type": "text", "text": "一级" }] },
+    {
+      "type": "bulletList",
+      "content": [
+        {
+          "type": "listItem",
+          "attrs": { "collapsed": false },
+          "content": [
+            { "type": "paragraph", "content": [{ "type": "text", "text": "二级" }] }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 9. `taskList`（任务列表）
+
+| 参数         | 有无 | 含义            |
+| ------------ | ---- | --------------- |
+| （无 attrs） | —    | 待办列表容器    |
+| `content`    | 必有 | `taskItem` 数组 |
+
+---
+
+## 10. `taskItem`（任务项）
+
+| 参数      | 类型      | 默认    | 含义                     | 取值             |
+| --------- | --------- | ------- | ------------------------ | ---------------- |
+| `checked` | `boolean` | `false` | 是否勾选完成             | `true` / `false` |
+| `content` | 节点[]    |         | 多为带文本的 `paragraph` |                  |
+
+```json
+{
+  "type": "taskItem",
+  "attrs": { "checked": true },
+  "content": [
+    {
+      "type": "paragraph",
+      "attrs": { "indent": 0, "textAlign": null },
+      "content": [{ "type": "text", "text": "123123123" }]
+    }
+  ]
+}
+```
+
+---
+
+## 11. `codeBlock`（代码块）
+
+| 参数          | 类型        | 默认          | 含义                                      | 取值                                                                         |
+| ------------- | ----------- | ------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
+| `language`    | `string`    | `"plaintext"` | 语法高亮语言 id                           | 如 `javascript`、`python`、`plaintext` 等（见 `constants/codeLanguages.ts`） |
+| `wrap`        | `boolean`   | `false`       | 是否自动换行                              | `true` / `false`                                                             |
+| `caption`     | `string`    | `"代码块"`    | 顶栏标题                                  | 任意字符串                                                                   |
+| `collapsed`   | `boolean`   | `false`       | 整块是否折叠（仅展示顶栏）                | `true` / `false`                                                             |
+| `regionFolds` | `number[]`  | `[]`          | 块内已折叠区域的起始行号（1-based）       | 如 `[1, 10]`；无效行号加载后会被校正丢掉                                     |
+| `content`     | 节点[]      |               | 一般为单个 `text`（整段代码）             |                                                                              |
+
+```json
+{
+  "type": "codeBlock",
+  "attrs": {
+    "language": "javascript",
+    "wrap": false,
+    "caption": "代码块",
+    "collapsed": false,
+    "regionFolds": [1]
+  },
+  "content": [{ "type": "text", "text": "function demo() {\n  console.log(1)\n}" }]
+}
+```
+
+> `collapsed` / `regionFolds` 随文档 JSON 持久化；Markdown / DOCX 导出不保留折叠 UI（正文仍为完整代码）。`regionFolds` 按行号锚定，在折叠点上方增删行可能导致错位。
+
+---
+
+## 12. `callout`（高亮块）
+
+| 参数              | 类型             | 默认   | 含义           | 取值                                                                  |
+| ----------------- | ---------------- | ------ | -------------- | --------------------------------------------------------------------- |
+| `emoji`           | `string`         | `"💡"` | 左侧图标 emoji | 任意短字符串                                                          |
+| `backgroundColor` | `string \| null` | `null` | 填充色         | CSS 色如 `"#e1eafe"`；`null` 用默认浅红底；`"transparent"` 无填充     |
+| `borderColor`     | `string \| null` | `null` | 边框色         | CSS 色如 `"#80a7f9"`；`null` 用默认浅红描边；`"transparent"` 无边框色 |
+| `content`         | 节点[]           |        | 一块或多块正文 |                                                                       |
+
+---
+
+## 13. `table`（表格）
+
+| 参数         | 有无 | 含义            |
+| ------------ | ---- | --------------- |
+| （无 attrs） | —    | 表格容器        |
+| `content`    | 必有 | `tableRow` 数组 |
+
+---
+
+## 14. `tableRow`（表行）
+
+| 参数      | 类型             | 默认   | 含义                        | 取值                              |
+| --------- | ---------------- | ------ | --------------------------- | --------------------------------- |
+| `height`  | `number \| null` | `null` | 行高（px）                  | `null` 用默认最小行高；数字为像素 |
+| `content` | 节点[]           |        | `tableHeader` / `tableCell` |                                   |
+
+---
+
+## 15. `tableHeader`（表头格）
+
+| 参数              | 类型               | 默认   | 含义                           | 取值                                       |
+| ----------------- | ------------------ | ------ | ------------------------------ | ------------------------------------------ |
+| `colspan`         | `number`           | `1`    | 横向合并列数                   | ≥1                                         |
+| `rowspan`         | `number`           | `1`    | 纵向合并行数                   | ≥1                                         |
+| `colwidth`        | `number[] \| null` | `null` | 本格覆盖的各列像素宽           | 长度应等于 `colspan`；删列后应保留剩余列宽 |
+| `align`           | `string \| null`   | `null` | 单元格内容对齐（TipTap Table） | `null` / 对齐字面量                        |
+| `backgroundColor` | `string \| null`   | `null` | 单元格背景色                   | CSS 色，如 `"#f8e6a0"`；`null` 无底色      |
+| `content`         | 节点[]             |        | 多为 `paragraph`               |                                            |
+
+---
+
+## 16. `tableCell`（表体格）
+
+| 参数              | 类型               | 默认   | 含义                 | 取值                 |
+| ----------------- | ------------------ | ------ | -------------------- | -------------------- |
+| `colspan`         | `number`           | `1`    | 横向合并列数         | ≥1                   |
+| `rowspan`         | `number`           | `1`    | 纵向合并行数         | ≥1                   |
+| `colwidth`        | `number[] \| null` | `null` | 本格覆盖的各列像素宽 | 长度应等于 `colspan` |
+| `align`           | `string \| null`   | `null` | 单元格内容对齐       | `null` / 对齐字面量  |
+| `backgroundColor` | `string \| null`   | `null` | 单元格背景色         | CSS 色或 `null`      |
+| `content`         | 节点[]             |        | 多为 `paragraph`     |                      |
+
+（与 `tableHeader` 字段集合相同，语义同 §15。）
+
+---
+
+## 17. `image`（图片）
+
+| 参数          | 类型             | 默认     | 含义           | 取值 / 说明                           |
+| ------------- | ---------------- | -------- | -------------- | ------------------------------------- |
+| `src`         | `string \| null` | `null`   | 展示图地址     | 生产为 `upload` 回传的 `http(s)`；会话内可为 `blob:`；旧草稿多为 `data:` |
+| `mediaId`     | `string`         | `""`     | 媒体持久化主键 | 由 `DocMediaHooks.upload` 返回；旧草稿可无 |
+| `alt`         | `string \| null` | `null`   | 替代文本       | 常为文件名                            |
+| `title`       | `string \| null` | `null`   | 标题属性       |                                       |
+| `width`       | `number \| null` | `null`   | 展示宽度（px） | 拖拽改宽后写入；最小约 80             |
+| `height`      | `number \| null` | `null`   | 展示高度       | Demo 通常 `null`（高度随图）          |
+| `align`       | `string`         | `"left"` | 块对齐         | `"left"` / `"center"` / `"right"`     |
+| `caption`     | `string`         | `""`     | 图注           |                                       |
+| `originalSrc` | `string \| null` | `null`   | 裁剪前原图     | 有值时可「还原原图」                  |
+| `uploadStatus`| `string \| null` | `null`   | 上传瞬态       | `"uploading"` / `"error"`；成功后清除 |
+| `uploadId`    | `string`         | `""`     | 临时上传键     | 仅会话内占位回填用；成功后清除        |
+
+无 `content`（atom）。插入时先本地 `blob:` 占位并展示进度，再 `upload` 回填。
+
+---
+
+## 18. `video`（视频）
+
+| 参数       | 类型             | 默认     | 含义                     | 取值 / 说明                          |
+| ---------- | ---------------- | -------- | ------------------------ | ------------------------------------ |
+| `src`      | `string`         | `""`     | 播放地址                 | 生产为 `upload` 回传的 `http(s)`；否则会话内 `blob:` |
+| `mediaId`  | `string`         | `""`     | 媒体持久化主键 | 由 `DocMediaHooks.upload` 返回；Demo 为 IndexedDB key |
+| `filename` | `string`         | `""`     | 原始文件名               |                                      |
+| `mime`     | `string`         | `""`     | MIME                     | 如 `video/mp4`                       |
+| `align`    | `string`         | `"left"` | 对齐                     | `"left"` / `"center"` / `"right"`    |
+| `caption`  | `string`         | `""`     | 图注                     |                                      |
+| `width`    | `number \| null` | `null`   | 宽度（px）               | 拖拽改宽；最小约 160                 |
+| `uploadStatus` | `string \| null` | `null` | 上传瞬态 | `"uploading"` / `"error"`；成功后清除 |
+| `uploadId` | `string`         | `""`     | 临时上传键               | 会话内占位回填；成功后清除           |
+
+无 `content`。单文件上限 80MB。插入时先占位再异步上传。
+
+---
+
+## 19. `audio`（音频）
+
+| 参数       | 类型             | 默认     | 含义               | 取值 / 说明                       |
+| ---------- | ---------------- | -------- | ------------------ | --------------------------------- |
+| `src`      | `string`         | `""`     | 播放地址           | 同视频：生产为线上 URL，否则会话内 `blob:` |
+| `mediaId`  | `string`         | `""`     | 媒体持久化主键 | 同视频，来自 `upload`                         |
+| `filename` | `string`         | `""`     | 文件名             |                                   |
+| `mime`     | `string`         | `""`     | MIME               | 如 `audio/wav`                    |
+| `align`    | `string`         | `"left"` | 对齐               | `"left"` / `"center"` / `"right"` |
+| `caption`  | `string`         | `""`     | 图注               |                                   |
+| `duration` | `number \| null` | `null`   | 预解析总时长（秒） | AAC 等用于锁定结束时间；可 `null` |
+| `width`    | `number \| null` | `null`   | 播放条宽度（px）   | **只改宽，高度固定**；最小约 200  |
+| `uploadStatus` | `string \| null` | `null` | 上传瞬态 | `"uploading"` / `"error"`；成功后清除 |
+| `uploadId` | `string`         | `""`     | 临时上传键         | 会话内占位回填；成功后清除        |
+
+无 `content`。插入时先占位再异步上传。
+
+---
+
+## 20. `mindmap`（思维导图）
+
+| 参数      | 类型     | 默认                     | 含义                 | 取值 / 说明                      |
+| --------- | -------- | ------------------------ | -------------------- | -------------------------------- |
+| `mapData` | `string` | 默认中心主题 JSON 字符串 | mind-elixir 整图数据 | **必须是 JSON 字符串**，不是对象 |
+| `outline` | `string` | `""`                     | 旧版大纲文本         | 仅迁移兼容；新数据应 `""`        |
+
+无 `content`。
+
+`mapData` 解析后核心字段：
+
+| 字段                | 含义                                       |
+| ------------------- | ------------------------------------------ |
+| `nodeData.id`       | 节点 id                                    |
+| `nodeData.topic`    | 节点文案                                   |
+| `nodeData.children` | 子节点数组（同结构）                       |
+| `nodeData.image`    | 可选；节点配图 `{ url, width, height, fit? }`（画板粘贴写入，多为 data URL） |
+| `direction`         | 布局方向（如 SIDE=`2`）                    |
+| `theme` 等          | 画板可能写入的扩展字段，导入时建议原样保留 |
+
+---
+
+## 20.1 `flowchart`（流程图）
+
+| 参数        | 类型     | 默认                       | 含义               | 取值 / 说明                                     |
+| ----------- | -------- | -------------------------- | ------------------ | ----------------------------------------------- |
+| `graphData` | `string` | 默认示例流程图 JSON 字符串 | LogicFlow 整图数据 | **必须是 JSON 字符串**，不是对象                |
+| `themeId`   | `string` | `"feishu"`                 | 历史兼容字段（已固定默认色板，切换 UI 已去除） | 读写仍保留；画板始终按默认色渲染 |
+
+`graphData.nodes[].type` 除内置 `ellipse` / `rect` / `diamond` / `text` / `polyline` 外，还可含自定义：`free-line`、`sticky`、`partition`、`fc-group`（组合框，`properties.children` 为直接成员 id，可嵌套组；`properties.isCollapsed` 表示折叠；成员 `properties.groupId` 指向所属组）、`fc-table`、`fc-icon`、`fc-image`、`free-path`，以及泳道 `pool` / `lane`（LogicFlow PoolElements）；扩展几何/流程形：`fc-parallelogram`、`fc-trapezoid`、`fc-triangle`、`fc-right-triangle`、`fc-pentagon`、`fc-hexagon`、`fc-octagon`、`fc-star`、`fc-arrow-left` / `fc-arrow-right` / `fc-arrow-double`、`fc-manual-input`、`fc-offpage`、`fc-cylinder`、`fc-document`、`fc-delay`、`fc-predefined`、`fc-bubble`、`fc-rect-bubble`、`fc-cloud`。
+
+跨线圆弧（B14）为**运行时渲染**：覆盖内置 `polyline` 的 View，在交点插入 SVG 圆弧；**不**在 edge attrs / `properties` 中持久化 `jumps`。
+
+无 `content`。
+
+`graphData` 解析后核心字段：
+
+| 字段      | 含义                                                                                       |
+| --------- | ------------------------------------------------------------------------------------------ |
+| `nodes[]` | 节点：`id` / `type`（`ellipse`\|`rect`\|`diamond` 等）/ `x` / `y` / `text` / `properties`  |
+| `edges[]` | 边：`id` / `type`（多为 `polyline`）/ `sourceNodeId` / `targetNodeId` / `text`（连线说明） |
+
+节点 `properties` 常用子字段：
+
+| 字段 | 含义 |
+| ---- | ---- |
+| `style` | 填充/描边/虚实/粗细/透明度/翻转等 |
+| `textStyle` | **整节点**文本样式（非行内混排）：`fontSize` / `color` / `backgroundColor` / `fontWeight` / `fontStyle` / `textDecoration` / `textAlign`；LogicFlow `getTextStyle` 原生合并 |
+| `locked` | 锁定 |
+| `nodeKind` | Demo 语义标签（start / process 等） |
+| `direction` | 泳道 `pool`：`horizontal` / `vertical` |
+| `rows` / `cols` / `cells` | 表格 `fc-table`：行列数与 `{ text, fill }[][]` |
+| `icon` | 图标 `fc-icon` 字形 |
+| `src` | 图片 `fc-image` 的 data URL |
+
+---
+
+## 20.2 `columnBlock`（分栏容器）
+
+| 参数     | 类型       | 默认        | 含义                         |
+| -------- | ---------- | ----------- | ---------------------------- |
+| `widths` | `number[]` | `[50, 50]`  | 各列宽度百分比，和为 100     |
+| `content` | 节点[]    |             | 2～5 个 `column`             |
+
+不允许嵌套分栏。Markdown 导出按列顺序拼接，列间 `---`。
+
+## 20.3 `column`（分栏列）
+
+| 参数      | 有无 | 含义            |
+| --------- | ---- | --------------- |
+| （无 attrs） | — | 一列正文容器 |
+| `content` | 必有 | `block+`（段落、图、表等，不含 `columnBlock` 插入） |
+
+## 20.4 `file`（正文文件卡片）
+
+| 参数       | 类型     | 默认 | 含义              |
+| ---------- | -------- | ---- | ----------------- |
+| `src`      | `string` | `""` | 线上 / 会话内预览 URL（生产应为 `http(s)`，来自 `upload.src`） |
+| `mediaId`  | `string` | `""` | 媒体持久化主键（`upload` 返回） |
+| `filename` | `string` | `""` | 原始文件名        |
+| `mime`     | `string` | `""` | MIME              |
+| `size`     | `number` | `0`  | 字节数            |
+| `displayMode` | `"text" \| "card" \| "preview" \| null` | `null` | 展示形态（空则按类型默认） |
+| `uploadStatus` | `"uploading" \| "error" \| null` | `null` | 上传瞬态；成功后清除 |
+| `uploadId` | `string` | `""` | 临时上传键；成功后清除 |
+
+无 `content`。与标题下文档级附件互相独立。插入时先按后缀出预览壳再异步上传。
+
+---
+
+## 21. `text`（文本叶子）
+
+| 参数         | 类型     | 含义                        |
+| ------------ | -------- | --------------------------- |
+| `text`       | `string` | 可见字符（不在 `attrs` 里） |
+| `marks`      | Mark[]   | 可选，行内样式列表          |
+| （无 attrs） | —        |                             |
+
+```json
+{
+  "type": "text",
+  "marks": [{ "type": "bold" }],
+  "text": "123123"
+}
+```
+
+---
+
+## 22. Marks（挂在 `text.marks[]`）
+
+### 22.1 无参数
+
+| `type`      | 含义     |
+| ----------- | -------- |
+| `bold`      | 加粗     |
+| `italic`    | 斜体     |
+| `strike`    | 删除线   |
+| `underline` | 下划线   |
+| `code`      | 行内代码 |
+
+```json
+{ "type": "bold" }
+```
+
+### 22.2 `link`
+
+| 参数     | 类型             | 默认/常见                        | 含义       |
+| -------- | ---------------- | -------------------------------- | ---------- |
+| `href`   | `string`         |                                  | 链接地址   |
+| `target` | `string`         | `"_blank"`                       | 打开方式   |
+| `rel`    | `string`         | `"noopener noreferrer nofollow"` | rel        |
+| `class`  | `string`         | `"yos-docs-editor-link"`              | CSS class  |
+| `title`  | `string \| null` | `null`                           | title 属性 |
+
+### 22.3 `textStyle`（字体颜色）
+
+| 参数    | 类型             | 含义     | 取值示例                                                                                                                               |
+| ------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `color` | `string \| null` | 文字颜色 | `null` 未设/默认；亦可为 `""`；色板如 `#8f959e` 灰、`#f54a45` 红、`#ff8800` 橙、`#f5c60a` 黄、`#34c724` 绿、`#3370ff` 蓝、`#7b61ff` 紫 |
+
+### 22.4 `highlight`（文字背景）
+
+| 参数    | 类型             | 含义   | 取值示例                                                               |
+| ------- | ---------------- | ------ | ---------------------------------------------------------------------- |
+| `color` | `string \| null` | 背景色 | `null` 无；否则见 `DOC_BG_COLORS`（如 `#faf1d1` 浅黄、`#f8e6a0` 黄等） |
+
+### 22.5 `glossaryTerm`（词条）
+
+| 参数     | 类型             | 含义                  |
+| -------- | ---------------- | --------------------- |
+| `termId` | `string \| null` | 对应词条库条目的 `id` |
+
+释义不在 mark 里，在旁路词条库（见下）。
+
+---
+
+## 23. 旁路存储（非 TipTap 节点）
+
+### 23.1 词条库
+
+`glossaryTerm` mark 只存 `termId`；释义在旁路词条库，**不进** TipTap JSON。
+
+**生产**：宿主传入 `DocEditor` 的 `glossary` prop（`GlossaryHooks`）：
+
+| 方法 | 含义 |
+| ---- | ---- |
+| `listTerms` | 列出全部词条（打开草稿时用于正文补 mark） |
+| `getTerm` | 按 id 取词条 |
+| `findTermByTitle` | 按标题精确匹配（新建时复用 id） |
+| `upsertTerm` | 新增或更新词条 |
+
+`GlossaryTerm` 字段：
+
+| 参数         | 类型     | 含义                          |
+| ------------ | -------- | ----------------------------- |
+| `id`         | `string` | = `glossaryTerm.attrs.termId` |
+| `title`      | `string` | 词条名                        |
+| `definition` | `string` | 释义                          |
+| `createdAt`  | `number` | 创建时间戳（ms）              |
+
+不传 `glossary` 时隐藏词条入口；**Demo 回退**（`persist`）：`localStorage["demo.doc.glossary.v1"]`，数组元素字段同上。
+
+### 23.2 媒体库与 `DocMediaHooks`
+
+图片 / 音视频 / 正文 `file` / 文档级附件的二进制**不进** TipTap JSON；JSON 存 `mediaId`，生产还应把 `upload` 回传的线上 `src` 写入节点 / 附件，**DOM 渲染优先用该地址**。插入时包内先占位展示进度，再异步调用 `upload`。
+
+**生产**：宿主传入 `DocEditor` 的 `media` prop（`DocMediaHooks`）：
+
+| 方法 | 签名 | 含义 |
+| ---- | ---- | ---- |
+| `upload` | `(file: File, options?: { onProgress?: (percent: number) => void }) => Promise<{ mediaId: string; src?: string }>` | 上传后返回持久化主键；**应同时返回线上 URL 作 `src`**；可选 `onProgress`（0–100）驱动 UI 进度条 |
+| `load` | `(mediaId: string) => Promise<Blob \| null>` | 无可用线上 `src` 时，播放 / 导出按 id 取回二进制 |
+
+解析顺序：优先 `load(mediaId)` → 再 `http(s)` / `//` 的 `src` → 其它 `src`（如会话内 `blob:`）。
+
+`mediaId` **只来自** `upload` 的返回值（或宿主自行生成后写入返回）；包内不会向服务端要 id。可选导出 `createMediaId()` 作客户端 UUID。
+
+**Demo 回退**（未传 `media` 且 `persist`）：IndexedDB `demo.doc.media.v1` / `files`
+
+| 项    | 含义             |
+| ----- | ---------------- |
+| key   | `mediaId` 字符串 |
+| value | 音视频 / 文件 `Blob`    |
+
+### 23.3 草稿 `localStorage["demo.doc.draft.v1"]`
+
+| 参数       | 含义                                                         |
+| ---------- | ------------------------------------------------------------ |
+| `title`    | 文档标题                                                     |
+| `content`  | 上文整棵 `doc` 树                                            |
+| `readOnly` | 可选；`true` 时恢复为只读模式；旧草稿无此字段视为可编辑     |
+| `attachments` | 可选；文档级附件元数据（标题下方附件栏，**不进** `content`）；与正文 `file` 节点互相独立 |
+
+`attachments[]` 元素（`DocAttachment`）：
+
+| 参数       | 类型     | 含义                          |
+| ---------- | -------- | ----------------------------- |
+| `id`       | `string` | 附件记录 id                   |
+| `name`     | `string` | 文件名                        |
+| `size`     | `number` | 字节数                        |
+| `mime`     | `string` | MIME                          |
+| `mediaId`  | `string` | 媒体键（`DocMediaHooks.upload` / Demo IndexedDB）；上传中可为空 |
+| `src`      | `string` | 可选；线上可访问 URL（`upload` 回传）；有则预览 / 下载优先用 |
+| `createdAt`| `number` | 创建时间戳（ms）              |
+| `uploadStatus` | `"uploading" \| "error" \| null` | 可选；上传瞬态，成功后应清除 |
+
+可粘贴整篇骨架见 [`doc-draft.template.json`](./doc-draft.template.json)（含 `attachments` 示例）。
+
+查询参数：`?readonly=1` 进入页时强制只读（可与 `?skipDraft=1` 并存）。
+
+---
+
+## 24. 类型索引（速查）
+
+| type                        | 有 attrs？                                                                                | 关键   |
+| --------------------------- | ----------------------------------------------------------------------------------------- | ------ |
+| `doc`                       | 无                                                                                        | §1     |
+| `paragraph`                 | `indent`, `textAlign`                                                                     | §2     |
+| `heading`                   | `level`, `indent`, `textAlign`, `collapsed`                                               | §3     |
+| `blockquote`                | 无                                                                                        | §4     |
+| `horizontalRule`            | 无                                                                                        | §5     |
+| `hardBreak`                 | 无                                                                                        | §5.1   |
+| `bulletList`                | 无                                                                                        | §6     |
+| `orderedList`               | `start`, `type`                                                                           | §7     |
+| `listItem`                  | `collapsed`                                                                               | §8     |
+| `taskList`                  | 无                                                                                        | §9     |
+| `taskItem`                  | `checked`                                                                                 | §10    |
+| `codeBlock`                 | `language`, `wrap`, `caption`, `collapsed`, `regionFolds`                                 | §11    |
+| `callout`                   | `emoji` / `backgroundColor` / `borderColor`                                               | §12    |
+| `table`                     | 无                                                                                        | §13    |
+| `tableRow`                  | `height`                                                                                  | §14    |
+| `tableHeader` / `tableCell` | `colspan`, `rowspan`, `colwidth`, `align`, `backgroundColor`                              | §15–16 |
+| `image`                     | `src`, `mediaId`, `alt`, `title`, `width`, `height`, `align`, `caption`, `originalSrc`, `uploadStatus`, `uploadId` | §17    |
+| `video`                     | `src`, `mediaId`, `filename`, `mime`, `align`, `caption`, `width`, `uploadStatus`, `uploadId` | §18    |
+| `audio`                     | 视频字段 + `duration` + `width` + 上传瞬态                                              | §19    |
+| `mindmap`                   | `mapData`, `outline`                                                                      | §20    |
+| `flowchart`                 | `graphData`, `themeId`                                                                    | §20.1  |
+| `columnBlock`               | `widths`                                                                                  | §20.2  |
+| `column`                    | 无                                                                                        | §20.3  |
+| `file`                      | `src`, `mediaId`, `filename`, `mime`, `size`, `displayMode`, `uploadStatus`, `uploadId`   | §20.4  |
+| `text`                      | 用 `text`/`marks`，无 attrs                                                               | §21    |
+| Marks                       | `bold` `italic` `strike` `underline` `code` `link` `textStyle` `highlight` `glossaryTerm` | §22    |
+
+### 24.1 与运行时 Schema 核对
+
+在 `/main/doc?skipDraft=1` 对 `editor.schema` dump，结论：
+
+| 项                  | 结果                                                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| 节点                | 与文档对齐后 **26 个**一致（含 `flowchart` / `columnBlock` / `column` / `file`）                                                                                  |
+| Mark                | **9 个**与文档一致                                                                                                            |
+| 各 type 的 attrs 名 | 与 `spec.attrs` **一一对应**                                                                                                  |
+| 不进 JSON 的扩展    | Placeholder / Dropcursor / Gapcursor / UndoRedo / NodeRange / SlashCommand / MarkdownPaste / DocTableCellDrag 等 **无需枚举** |
+
+可粘贴整篇骨架：[`doc-draft.template.json`](./doc-draft.template.json)。
+
+该模版已覆盖 **全部 26 个节点 + 9 个 marks**，以及草稿级 `attachments`（含 `blockquote` / `orderedList` / `hardBreak` / `columnBlock` / `column` / `file`，以及 `italic` `strike` `underline` `code` `highlight` `glossaryTerm` 等）；并示范表格 `colspan`/`rowspan`>1、`image.mediaId` / `originalSrc`、有序列表 `start`/`type` 与 `listItem` 内 `heading`、分栏 `widths`、文件 `displayMode`（`card` / `text` / `preview`）。