dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/references/whiteboard/open-nodes-v1/07-examples-errors-write-support.md

@@ -0,0 +1,270 @@
+# OpenNodes V1 — Update 示例、回写规则、错误模型和 writeSupport
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+## 8. Update 示例
+
+### 8.1 Append 一个文本节点
+
+```json
+{
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "title",
+        "type": "text",
+        "x": 120,
+        "y": 80,
+        "width": 240,
+        "height": 48,
+        "text": {
+          "blocks": [
+            {
+              "type": "paragraph",
+              "horizontalAlign": "left",
+              "runs": [
+                {
+                  "text": "Hello OpenNodes",
+                  "marks": {
+                    "fontSize": 16,
+                    "color": "#223344"
+                  }
+                }
+              ]
+            }
+          ],
+          "verticalAlign": "center",
+          "padding": [2, 4]
+        }
+      }
+    ]
+  }
+}
+```
+
+### 8.2 Append 两个形状和一条引用连接线
+
+```json
+{
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "left",
+        "type": "shape",
+        "x": 80,
+        "y": 100,
+        "width": 120,
+        "height": 80,
+        "geometry": "dml:roundRect"
+      },
+      {
+        "id": "right",
+        "type": "shape",
+        "x": 360,
+        "y": 100,
+        "width": 120,
+        "height": 80,
+        "geometry": "dml:roundRect"
+      },
+      {
+        "id": "line",
+        "type": "connector",
+        "start": {
+          "type": "node",
+          "nodeRef": {
+            "scope": "request",
+            "id": "left"
+          },
+          "anchor": {
+            "mode": "fixed",
+            "side": "right"
+          }
+        },
+        "end": {
+          "type": "node",
+          "nodeRef": {
+            "scope": "request",
+            "id": "right"
+          },
+          "anchor": {
+            "mode": "fixed",
+            "side": "left"
+          },
+          "marker": {
+            "catalogId": "arrow.filled"
+          }
+        },
+        "routing": "straight"
+      }
+    ]
+  }
+}
+```
+
+### 8.3 Overwrite 整页
+
+```json
+{
+  "overwrite": true,
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "replacement",
+        "type": "text",
+        "x": 120,
+        "y": 80,
+        "width": 240,
+        "height": 48,
+        "text": {
+          "blocks": [
+            {
+              "type": "paragraph",
+              "runs": [
+                {
+                  "text": "Replacement content"
+                }
+              ]
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+### 8.4 清空当前页面
+
+```json
+{
+  "overwrite": true,
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": []
+  }
+}
+```
+
+## 9. Query 数据不能直接回写
+
+query 是完整可读投影，update 是受约束的创建协议，两者不是对称 JSON：
+
+| Query 字段/能力 | Update 处理方式 |
+| --- | --- |
+| 真实 `id` | 只能作为请求级临时 ID；不能引用既有 document 节点。 |
+| `children` | 删除，通过子节点 `parentId` 重建。 |
+| `absoluteBounds` | 删除；普通节点使用 `x/y/width/height`，connector 使用端点和路由字段。 |
+| `locked`、`source`、`writeSupport`、`unsupportedFeatures` | 删除，均为 query-only。 |
+| 文本 `plainText` | 删除，由服务端根据 paragraph 和 run 重新计算。 |
+| 多 paragraph、列表、多 run、文字链接 | 可以保留；每个 block 必须是受支持类型，且 run 内不能包含原始换行符。 |
+| 未知 list style、非法链接或未支持的 block/marks | 需要移除或降级为受支持的 block/run。 |
+| theme paint | 保留 `token/lumMod/lumOff`，删除 query-only `resolvedColor`；token 必须能在当前白板主题中解析。 |
+| image paint | 需要降级成受支持的 paint，或不更新该节点。 |
+| 受支持的 linear/radial gradient、单个 shadow | 可以保留；gradient offset 使用 `0～100`，radial `custom` 不能回写。 |
+| blur、unknown 或叠加 effects | 需要删除、降级成单个 shadow，或不更新该节点。 |
+| connector `scope: "document"` | 不能回写；改为引用同一请求节点的 `scope: "request"`。 |
+| connector `resolvedPoint`、`position`、`resolvedPath` | 删除，均由服务端重新计算。 |
+| shape `adjustments` | V1 不支持写入。 |
+| stickyNote `creator`、`tags` | V1 不支持写入。 |
+
+即使 query 节点显示 `writeSupport = "readWrite"`，update 仍会对版本、目录、
+字段和请求关系做完整校验。调用方不应跳过 update 错误处理。
+
+## 10. 错误模型
+
+### 10.1 顶层错误码
+
+| 错误码 | 含义 |
+| --- | --- |
+| `invalidRequest.whiteboard.schemaInvalid` | JSON、字段或节点 schema 不合法。 |
+| `invalidRequest.whiteboard.catalogVersionUnsupported` | catalogVersion 不受支持。 |
+| `invalidRequest.whiteboard.validationFailed` | 节点间引用、父子关系或路径关系不合法。 |
+| `invalidRequest.whiteboard.emptySource` | append 的 nodes 为空。 |
+| `invalidRequest.whiteboard.overwriteUnsafe` | overwrite 安全预检失败。 |
+
+### 10.2 DWS 错误输出
+
+远端校验失败时，DWS 以统一 CLI 错误结构返回：
+
+```json
+{
+  "error": {
+    "category": "api",
+    "reason": "business_error",
+    "server_key": "whiteboard",
+    "server_error_code": "invalidRequest.whiteboard.validationFailed",
+    "message": "Whiteboard request graph is invalid",
+    "trace_id": "TRACE_ID"
+  }
+}
+```
+
+部分服务错误会使用更宽泛的 `invalidRequest.inputArgs.invalid`。Agent 应结合
+`server_error_code` 和 `message` 修正输入；需要排障时保留 `trace_id`。JSON 或
+信封级错误可能由 CLI 本地返回，不一定包含 `server_key` 和 `trace_id`。
+
+校验类错误不可通过原样重试恢复。常见原因包括：
+
+- Schema：缺少字段、未知字段、类型或枚举值错误、提交 query-only 字段、
+  节点类型不支持。
+- 请求关系：临时 ID 重复、引用不存在、父子关系非法、连接线目标不支持、
+  路径退化或主题 token 不存在。
+- Overwrite 预检：锁定节点、禁止删除、关联数据无法安全处理或删除失败。
+
+任一阶段失败都不会保留部分更新。
+
+## 11. writeSupport 的含义
+
+`writeSupport` 表示当前 query 节点是否能由 V1 update 无损表达，不代表用户
+权限，也不代表 overwrite 是否允许移除该既有节点。
+
+以下 `unsupportedFeatures` 均为对外返回的诊断枚举值：
+
+- `node.source.master`、`node.locked`、`node.role`、`node.placeholder`、
+  `node.extras`、`node.ability`。
+- `node.type.image`、`node.type.pdf`、`node.type.media`、
+  `node.type.webLink`、`node.type.table`、`node.type.chart`、
+  `node.type.uml`、`node.type.swimlane`、`node.type.mind`、
+  `node.type.timer`、`node.type.placeholder`、`node.type.unknown`。
+- `text.list.unsupported`、`text.link.unsupported`、`text.block.unsupported`、
+  `text.lineBreak.unsupported`、`text.marks.unsupported`、
+  `text.color.unsupported`、`text.highlight.unsupported`。
+- `style.fill.color`、`style.fill.opacity`、`style.fill.theme.token`、
+  `style.fill.theme.unresolved`、`style.fill.theme.modifier`、
+  `style.fill.theme.opacity`、
+  `style.fill.gradient.angle`、`style.fill.gradient.offset`、
+  `style.fill.gradient.color`、`style.fill.gradient.opacity`、
+  `style.fill.gradient.position`、`style.fill.image`。
+- `style.stroke.color`、`style.stroke.opacity`、`style.stroke.theme.token`、
+  `style.stroke.theme.unresolved`、
+  `style.stroke.theme.modifier`、`style.stroke.theme.opacity`、
+  `style.stroke.gradient.angle`、`style.stroke.gradient.offset`、
+  `style.stroke.gradient.color`、`style.stroke.gradient.opacity`、
+  `style.stroke.gradient.position`、`style.stroke.image`。
+- `style.effects`。
+- `shape.adjustments`、`stickyNote.creator`、`stickyNote.tags`。
+- `vector.resource.external`、`vector.resource.embedded`、
+  `vector.resource.unresolved`、`vector.fill`、`vector.stroke`、
+  `vector.opacity`、`vector.effect`、`vector.adjustments`。
+- `icon.catalogId`、`icon.opacity`、`icon.effect`、`icon.text`、
+  `icon.adjustments`。
+- `path.commands`、`path.data.size`、`path.commands.limit`、`path.text`、
+  `path.fillRule`、`path.adjustments`。
+- `connector.parent`、`connector.marker.unsupported`、
+  `connector.target.unexposed`、`connector.target.unsupported`、
+  `connector.anchor.unresolved`、`connector.anchor.custom`、
+  `connector.selfLoop`。
+- `group.angle`、`group.children.minimum`、`group.children.hidden`、
+  `group.child.readOnly`。
+- `frame.angle`、`frame.child.frame`、`frame.child.readOnly`。
+
+调用方应把 `unsupportedFeatures` 当作诊断信息，不应把当前枚举穷举写死为
+业务逻辑。真正可写与否以 `writeSupport` 和 update 校验结果为准。

package/skills/dws/dingtalk-misc/references/whiteboard/open-nodes-v1/08-catalogs.md

@@ -0,0 +1,61 @@
+# OpenNodes V1 — dml-v1 Geometry 和 Icon 完整目录
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+## 附录 A：dml-v1 geometry 目录
+
+写入时在以下名称前加 `dml:`，例如 `rect` 写成 `dml:rect`。当前目录共
+183 项，目录版本由 `catalogVersion = "dml-v1"` 标识。
+
+```text
+accentBorderCallout1 accentBorderCallout2 accentBorderCallout3
+accentCallout1 accentCallout2 accentCallout3 actionButtonBackPrevious
+actionButtonBeginning actionButtonBlank actionButtonDocument actionButtonEnd
+actionButtonForwardNext actionButtonHelp actionButtonHome
+actionButtonInformation actionButtonMovie actionButtonReturn actionButtonSound
+active allGeneralization arc attribute bentArrow bentUpArrow bevel bind blockArc
+borderCallout1 borderCallout2 borderCallout3 bracePair bracketPair callout1
+callout2 callout3 can chevron chord circularArrow cloud cloudCallout comment
+component control convert corner cube curvedDownArrow curvedLeftArrow
+curvedRightArrow curvedUpArrow dataStorage decagon delete diagStripe diamond
+dodecagon donut doubleWave downArrow downArrowCallout ellipse ellipseRibbon
+ellipseRibbon2 entity entitySet flowChartAlternateProcess flowChartCollate
+flowChartConnector flowChartDecision flowChartDelay flowChartDisplay
+flowChartDocument flowChartExtract flowChartInputOutput flowChartInternalStorage
+flowChartMagneticDisk flowChartMagneticDrum flowChartMagneticTape
+flowChartManualInput flowChartManualOperation flowChartMerge
+flowChartMultidocument flowChartOffpageConnector flowChartOnlineStorage
+flowChartOr flowChartPredefinedProcess flowChartPreparation
+flowChartPunchedCard flowChartPunchedTape flowChartSort
+flowChartSummingJunction flowChartTerminator foldedCorner frame generalization
+halfFrame heart heptagon hexagon history homePlate horizontalDivCircle
+horizontalScroll irregularSeal1 irregularSeal2 leftArrow leftArrowCallout
+leftBrace leftBracket leftRightArrow leftRightArrowCallout leftRightUpArrow
+leftUpArrow lightningBolt mathDivide mathEqual mathMinus mathMultiply
+mathNotEqual mathPlus moon multiClass multiValuedAttribute noSmoking node
+nonIsoscelesTrapezoid notchedRightArrow octagon parallelogram pentagon person
+pie plaque plus quadArrow quadArrowCallout receiveSignal rect relationship
+ribbon ribbon2 rightArrow rightArrowCallout rightBrace rightBracket round1Rect
+round2DiagRect round2SameRect roundRect rtTriangle smileyFace snip1Rect
+snip2DiagRect snip2SameRect snipRoundRect star10 star12 star16 star24 star32
+star4 star5 star6 star7 star8 stripedRightArrow sun teardrop triangle upArrow
+upArrowCallout upDownArrow user uturnArrow verticalDivCircle verticalScroll
+wave weakEntitySet weakRelationship wedgeEllipseCallout wedgeRectCallout
+wedgeRoundRectCallout
+```
+
+## 附录 B：dml-v1 icon 目录
+
+写入时必须使用完整的 `<group>/<name>`。当前共 4 组 49 项，目录版本由
+`catalogVersion = "dml-v1"` 标识。
+
+| group | 数量 | name（组成 `group/name`） |
+| --- | ---: | --- |
+| `emoji` | 14 | `happy`、`smile`、`laugh`、`fighting`、`like`、`ok`、`please`、`face-plam`、`tears-of-joy`、`cry`、`question`、`face-with-sweat`、`bloody-nose`、`doggy` |
+| `tools` | 21 | `pad`、`blue-note`、`yellow-notes`、`chart`、`chart-2`、`pencil`、`pen`、`bag`、`rocket`、`fire`、`gold`、`light`、`pin`、`red-flag`、`tea`、`island`、`ball`、`lucky-fish`、`coffee`、`milky-tea`、`pan` |
+| `priority` | 7 | `priority-1`、`priority-2`、`priority-3`、`priority-4`、`priority-5`、`priority-6`、`priority-7` |
+| `task` | 7 | `task-start`、`task-oct`、`task-3oct`、`task-half`、`task-5oct`、`task-7oct`、`task-done` |
+
+注意：`emoji/face-plam` 是 V1 保留的历史兼容枚举值，拼写虽然异常但属于协议值；
+传入 `emoji/face-palm` 会被拒绝。

package/skills/dws/dingtalk-misc/references/whiteboard/open-nodes-v1.md

@@ -0,0 +1,54 @@
+# OpenNodes V1（DWS 白板协议索引）
+
+本目录承载 `dws whiteboard query/update` 使用的 OpenNodes V1 协议。协议按
+调用阶段拆分，Agent 只加载当前任务所需章节，避免一次性读取全部内容。
+
+## DWS 使用规则
+
+- 只通过 `dws whiteboard query/update` 读写白板。
+- 每次调用必须提供承载白板的文档 `--node` 和目标白板 `--part-id`。
+- DWS 当前只支持单页白板：命令没有 `--page-id`，update 文件禁止包含
+  `pageId`。
+- `query` 不接收请求体；CLI 会把返回的 `resultJson` 解析成对象。
+- 白板命令不支持使用全局 `--jq` 或 `--fields` 过滤输出；传入任一参数都会报错，
+  Agent 直接读取 CLI 返回的结构化 JSON。
+- `update --source` 使用 `overwrite + source` 信封；append 和 overwrite 都是
+  远端写入，获得用户确认后必须通过 `--yes` 显式确认。
+- 原子 `whiteboard update` 本地预检 JSON、信封、版本、`nodes` 对象数组和 append 非空。
+  首选的 `whiteboard +update` 还在调用服务前校验节点 ID 唯一且 type 非空，以及 connector 的
+  端点类型/有限坐标、同请求 `nodeRef` 引用及目标可用性、anchor、marker、routing 和
+  waypoints 组合，拒绝自环及已识别的 query-only/推导字段。本地校验失败不会调用服务。
+  其余节点字段、枚举、层级和业务约束仍由白板服务完整校验；远端提交后的连接中断或
+  读回失败不代表未写入，必须保留回执和稳定 ID，不能盲目重发。
+- 原子命令返回 `success`、`nodeId`、`partId`、`resultJson` 和可选的 `resultSummary`。
+  `+query/+update` 使用统一结果信封；`+update` 的 `data.receipt` 区分真实终态回执与
+  `dryRun=true/executed=false` 预览，真实成功经独立读回验证且不重复返回完整快照。
+
+## 按任务读取
+
+| 当前任务 | 必读章节 |
+|---|---|
+| 理解版本、兼容和命令语义 | [01-overview](open-nodes-v1/01-overview.md) |
+| 读取或解释 query 结果 | [02-query](open-nodes-v1/02-query.md) |
+| 构造 append、overwrite 或清空请求 | [03-update](open-nodes-v1/03-update.md) |
+| 写富文本、列表、链接、主题色、渐变或阴影 | [04-text-style](open-nodes-v1/04-text-style.md) |
+| 写 shape、便签、frame、group 或 connector | [05-shape-frame-group-connector](open-nodes-v1/05-shape-frame-group-connector.md) |
+| 写已上传 Vector、内置 Icon 或自由 Path | [06-vector-icon-path](open-nodes-v1/06-vector-icon-path.md) |
+| 处理错误、query 转写或判断 writeSupport | [07-examples-errors-write-support](open-nodes-v1/07-examples-errors-write-support.md) |
+| 选择合法 geometry 或 icon catalogId | [08-catalogs](open-nodes-v1/08-catalogs.md) |
+
+## 强制读取规则
+
+- [构图 Reference](compose.md) 已评审并内嵌
+  `dml:rect` / `dml:roundRect` / `dml:diamond`、三种 connector marker、
+  `task/task-done` 和一条合法 Path 模板；原样复用这些值时不重复读取目录章节。
+- 使用安全子集之外的 `shape.geometry` 前必须读取
+  [08-catalogs](open-nodes-v1/08-catalogs.md)，不得猜测 geometry。
+- 使用安全子集之外的 `icon.catalogId` 前必须读取
+  [06-vector-icon-path](open-nodes-v1/06-vector-icon-path.md) 和
+  [08-catalogs](open-nodes-v1/08-catalogs.md)。
+- 原样复用 `compose.md` 的安全 Path 无需额外读取；其他 Path 必须读取
+  [06-vector-icon-path](open-nodes-v1/06-vector-icon-path.md)，不得把它当作通用 SVG Path。
+- Query 结果不能直接作为 update source；转换前必须读取
+  [03-update](open-nodes-v1/03-update.md) 和
+  [07-examples-errors-write-support](open-nodes-v1/07-examples-errors-write-support.md)。

package/skills/dws/dingtalk-misc/references/whiteboard/replace.md

@@ -0,0 +1,41 @@
+# 白板整页替换与清空
+
+仅在用户明确要求整页重绘或清空时读取本页。overwrite 会替换整个单页白板，不是
+局部节点更新。
+
+## 执行顺序
+
+1. 对同一 `nodeId/partId` 执行一次 `+query`，保留完整当前快照并汇总将被删除的
+   节点。
+2. 向用户说明目标、overwrite 影响和新节点数量，按 Runtime gate 取得确认。
+3. 一次提交完整终态；不要先清空再追加。
+4. `+update` 成功且 `verified=true` 表示已在内部对同一 `nodeId/partId` 完成最终
+   读回校验，直接依据验证结果、summary 和 receipt 交付，不再追加 `+query`。
+5. 仅用户明确要求更新后完整快照时，才对同一目标追加一次 `+query`；若此次读取
+   失败，分别报告更新已验证成功、快照获取失败，不把已验证的写入改报失败或重放。
+
+```bash
+# 旧版快照
+dws whiteboard +query --node <DOC_NODE_ID> --part-id <PART_ID> --format json
+dws whiteboard +update --node <DOC_NODE_ID> --part-id <PART_ID> \
+  --source @overwrite.json --format json
+```
+
+清空整页的更新文件：
+
+```json
+{
+  "overwrite": true,
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": []
+  }
+}
+```
+
+只有用户明确要求清空时才允许空数组。整页重绘使用相同信封，但 `nodes` 必须包含
+完整终态。`+update` 自身的回执缺失、读回失败或不一致不能报告完整成功；保留旧快照、
+完整新 Payload、可用 receipt 和差异。超时或 commit-unknown 同样不证明未提交：
+停止写入，最多再对同一目标 `+query` 一次只读对账，报告已提交但未验证或提交状态
+不明，不自动重放 overwrite、清空或追加。

package/skills/dws/dingtalk-misc/references/whiteboard/vector.md

@@ -0,0 +1,51 @@
+# 白板托管资源 Vector
+
+仅在白板需要 SVG/Vector 资源时读取本页。资源必须绑定到承载白板的同一
+`nodeId`；本地文件、临时 upload URL、独立文件节点 URL 和其他文档的资源都不能
+直接写入 OpenNodes。
+
+## 上传与映射
+
+```bash
+dws doc media upload --node <DOC_NODE_ID> --file ./whiteboard-asset.svg \
+  --mime-type image/svg+xml --format json
+```
+
+上传只准备资源，不插入文档正文。从同一次成功回执取稳定 `resourceId` 和
+`resourceUrl`，不要重新搜索或改写 URL；`resourceId` 原样映射为
+`resource.resourceId`，`resourceUrl` 原样映射为 `resource.url`。
+
+## Vector 更新文件
+
+```json
+{
+  "overwrite": false,
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "managed-vector",
+        "type": "vector",
+        "x": 80,
+        "y": 80,
+        "width": 160,
+        "height": 160,
+        "resource": {
+          "kind": "managed",
+          "resourceId": "<RESOURCE_ID>",
+          "url": "<RESOURCE_URL>"
+        }
+      }
+    ]
+  }
+}
+```
+
+按根 Reference 的 update 命令提交 `@vector.json`。上传和 update 必须使用同一个
+`DOC_NODE_ID`。成功结果中的读回 Vector 必须保留同一 `resourceId`；
+`verified=false`、资源身份变化或缺少读回都不能报告成功。
+
+需要 Icon/Path 或非托管 Vector 时改读
+[06-vector-icon-path.md](./open-nodes-v1/06-vector-icon-path.md)，不要同时加载构图
+Reference。

package/skills/dws/dingtalk-misc/references/whiteboard.md

@@ -0,0 +1,115 @@
+# 钉钉文档内嵌白板
+
+本页是 Whiteboard 的默认入口。白板/画布中的 OpenNodes 图形、文本、分组、连接线、
+Vector 和布局由 Whiteboard 负责；Doc 只负责创建文档以及插入、定位、删除白板卡片
+容器。已知命令直接执行；仅真实 `unknown command` / `unknown flag` 时读一次 leaf
+Help，契约不确定时读一次 compact leaf Schema。
+
+根据本次操作只读取以下一份操作 Reference，不预加载完整协议或多个示例集：
+
+- Shape、Connector、Frame、样式、Icon 或 Path：
+  [compose.md](./whiteboard/compose.md)
+- 已上传或本地 SVG/Vector 资源：[vector.md](./whiteboard/vector.md)
+- 整页替换或清空：[replace.md](./whiteboard/replace.md)
+
+读取已有白板或普通定位不需要额外 Reference。每个普通任务最多读取一份操作
+Reference；只有操作页仍缺少具体字段时，才读取一份精确协议章节。
+
+## 执行契约
+
+- 同一 profile，目标须有真实 `nodeId` 和 `whiteboardId/partId`；零/多目标、身份
+  不明或 profile 不一致时停止，不能取第一个候选。
+- Runtime 确认后执行层才添加 `--yes`；存储示例不得预置确认。
+- 成功须同时满足终态 receipt、请求节点映射和同板读回；`verified=false`、partial、
+  commit-unknown 不得报成功或盲重试。
+- `+update` 内部仍使用完整同板 query 校验；成功结果只返回稳定目标、mode、验证节点
+  数、summary 和精简 receipt，不返回 `source.pages[].nodes` 完整快照。用户明确要求
+  更新后完整快照时，再执行一次 `+query`；否则不得为补输出重复查询。
+- append 和 overwrite 的 `verified=true` 均包含独立读回证据，不再追加 query；
+  额外 query 仅用于用户要求完整快照，或未验证/提交状态不明时的有界只读对账。
+
+## 调用与上下文预算
+
+- 每板建立 `{blockId, whiteboardId, payloadFile}`，禁止重复 fetch、insert 或搜索。
+- 每阶段最多一次 update；提交前校验错误只修相关字段一次。相同 Payload、
+  `--verbose` 或 commit-unknown 不重放；commit-unknown 按同一稳定目标 query 对账。
+- 先用单次响应完整校验，再无损投影；ID、mode、verified、节点摘要和链接只是最小
+  集合，用户要求及后续操作依赖的几何、样式、文本、关系必须保留。
+- 投影只减少重复上下文，不删除业务信息：query/export/audit 需要完整快照时原样
+  交付；写入 `source` 保留在 Payload 文件中，不得因丢字段而重发远端请求。
+
+## 稳定 ID
+
+| ID | 来源 | 用途 |
+|---|---|---|
+| `nodeId` | `doc +create` / 文档解析 | 文档和白板命令的 `--node` |
+| `blockId` | `doc whiteboard insert` | 文档块定位、排序和删除 |
+| `whiteboardId` | `doc whiteboard insert` | 白板命令的 `--part-id` |
+| 请求节点 `id` | 本地 OpenNodes 文件 | 同一请求的 parent/connector 引用 |
+| 真实节点 ID | `+query` / `+update` 读回 | 读回身份；不能直接做局部 update |
+
+insert 返回 `whiteboardId` 后直接使用；若为 null，只 fetch 一次并按本次 `blockId`
+定位，仍未落库则报 pending，禁止重复插入。
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "whiteboard +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws whiteboard <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service whiteboard --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws whiteboard +query` | read | 严格读取已有文档白板的 OpenNodes 快照 |
+| `dws whiteboard +update` | high-risk-write | 确认后更新白板并按同一稳定目标精确读回 |
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## 定位与调用
+
+```bash
+# 新建文档和白板卡片
+dws doc +create --name "<文档标题>" --format json
+dws doc whiteboard insert --node <DOC_ID> --format json
+
+# 在指定块后插入
+dws doc +fetch --node <DOC_ID> --detail with-ids --format json
+dws doc whiteboard insert --node <DOC_ID> \
+  --ref-block <BLOCK_ID> --where after --format json
+
+# 读取与更新
+dws whiteboard +query --node <DOC_ID> --part-id <PART_ID> --format json
+dws whiteboard +update --node <DOC_ID> --part-id <PART_ID> \
+  --source @whiteboard.json --format json
+```
+
+`--source` 接受 JSON、`@relative-file.json` 或 stdin；本地文件必须加 `@`，裸路径
+会被当作 JSON。白板 shortcut 不支持 `--jq` / `--fields`。
+
+## 坐标读回与稳定结构
+
+坐标读回采用统一数值语义：整数、浮点数和 JSON Number 等价，并允许最多 0.5 像素
+的服务端规范化偏差。超过容差返回 `readback_field_mismatch`，不能声明成功：
+
+1. **已提交**：已有成功回执或已读到真实节点时，停止重提并只读对账。
+   append 会创建新节点，不会修正已有节点；改成 frame 再 append 仍会重复创建。
+   Runtime 保留 `error.details` 中的 `nodeId/partId/mode`、`commitState=committed`、
+   `verified=false` 和 `receipt.createdNodeIds/idMap/deletedNodeCount`，标记
+   `execution_started=true` 且不可重试。保留原始 Payload 和当前差异；如需核实，
+   最多再 query 同一白板一次，按回执真实 ID 对账，不循环轮询。
+2. **提交状态不明**：连接中断、缺少回执或暂未读到节点，都不能证明未提交；
+   停止写入，按同一稳定目标只读对账，仍不明确则报告阻塞，不重放。
+3. **明确未提交**：仅本地预检未发请求，或服务端明确保证未提交/无副作用，才可
+   修正相关字段后至多重试一次；`retryable=false` 的服务错误仍须先解决阻塞条件。
+
+已提交但未验证不能报告完整成功，也不得自动 overwrite、删除节点或重新 append。
+布局修复属于新操作，须先对账并另行确认范围和授权，不能作为校验失败的自动重试。
+有边界的分区、泳道和卡片组在提交前优先使用 frame 和容器内相对坐标；frame 是布局
+设计选择，不是已落库节点的修复手段。临时逻辑组合才使用 group。
+
+## 精确协议补充
+
+| 仅当操作 Reference 未覆盖时 | 读取 |
+|---|---|
+| 富文本、列表、链接、主题色、罕见样式 | [04-text-style.md](./whiteboard/open-nodes-v1/04-text-style.md) |
+| 罕见 shape/frame/group/connector 约束 | [05-shape-frame-group-connector.md](./whiteboard/open-nodes-v1/05-shape-frame-group-connector.md) |
+| 非托管 Vector、Icon、Path | [06-vector-icon-path.md](./whiteboard/open-nodes-v1/06-vector-icon-path.md) |
+| query 快照转换和错误语义 | [07-examples-errors-write-support.md](./whiteboard/open-nodes-v1/07-examples-errors-write-support.md) |
+| 新 geometry / icon catalog 值 | [08-catalogs.md](./whiteboard/open-nodes-v1/08-catalogs.md) |