first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -0,0 +1,110 @@
+# 钉钉文档内嵌白板
+
+`dws whiteboard` 只操作已经存在于钉钉在线文档中的单页内嵌白板。创建白板卡片使用
+`dws doc whiteboard insert`；普通文档块仍使用 `dws doc block`。
+
+OpenNodes V1 的完整字段、节点类型、目录枚举和错误语义按需读取
+[协议索引](./whiteboard/open-nodes-v1.md)；不要根据本页概要猜测节点字段或
+`geometry`、`catalogId` 等枚举值。渐变卡片、Frame 分支、SVG/Vector 等完整
+工作流见 [常用 Recipes](./whiteboard/recipes.md)。
+
+<!-- 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 -->
+
+## 定位白板
+
+每次操作都需要真实的文档 `nodeId` 和白板 `partId`。缺少 `partId` 时先读取文档
+JSONML，查找 `cardType=hetu` 且 `metadata.id` 非空的 card；`uuid` 是 blockId，
+不能当作 partId。多个候选时必须让用户选择，不能取第一个。
+
+```bash
+dws doc read --node <DOC_ID> --content-format jsonml --scope tags --tags card --format json
+```
+
+## 读取
+
+```bash
+dws whiteboard +query --node <DOC_ID> --part-id <PART_ID> --format json
+```
+
+CLI 会把服务端 `resultJson` 字符串解析为结构化 JSON。白板命令不支持全局
+`--jq` 或 `--fields`。
+
+## 更新
+
+更新文件使用 OpenNodes V1 信封：
+
+```json
+{
+  "overwrite": false,
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "title",
+        "type": "text",
+        "x": 40,
+        "y": 40,
+        "width": 240,
+        "height": 48,
+        "text": {
+          "blocks": [
+            {
+              "type": "paragraph",
+              "runs": [{"text": "方案"}]
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+- `overwrite=false`：追加，`nodes` 至少一个对象。
+- `overwrite=true`：整页重建，允许空数组；执行前必须先 query 保存当前内容。
+- 所有更新都是远端写入，必须先获得用户对本次写入的确认；存储示例不携带 `--yes`，执行层只能在确认后添加。
+- Query 返回不能直接作为 update 输入；真实节点 ID 不能用于局部修改。
+
+```bash
+dws whiteboard +update --node <DOC_ID> --part-id <PART_ID> \
+  --source @whiteboard.json --format json
+```
+
+`+update` 会严格验证终态 receipt、请求节点到真实节点的映射，并对同一 `nodeId` / `partId` 执行独立读回；不需要再以手写原子命令拼装验证链。
+
+常用节点类型包括 `text`、`shape`、`frame`、`group`、`connector`、`vector`。
+节点可用请求内临时 `id` 建立 `parentId` 或 connector 引用；服务端负责完整字段、
+层级和枚举校验，未知字段会使整次更新失败。
+
+## Vector / SVG 资源
+
+本地 SVG 不能直接写入 OpenNodes。先上传为绑定到同一文档 nodeId 的资源：
+
+```bash
+dws doc media upload --node <DOC_ID> --file ./icon.svg \
+  --mime-type image/svg+xml --yes --format json
+```
+
+将返回的 `resourceId` 和 `resourceUrl` 分别映射为 Vector resource 的
+`resourceId` 与 `url`。禁止使用临时 uploadUrl、跨 nodeId 复用或传本地路径。
+
+## 创建和删除白板卡片
+
+```bash
+dws doc whiteboard insert --node <DOC_ID> --yes --format json
+dws doc block delete --node <DOC_ID> --block-id <BLOCK_ID> --yes --format json
+```
+
+insert 返回 `blockId` 和 `whiteboardId`。前者用于块删除，后者就是后续 whiteboard
+命令的 partId；两者不可混用。插入成功但回查暂未取到 partId 时，命令会返回
+`whiteboardId: null` 并提示稍后按 blockId 回查。