钉钉文档内嵌白板

dws whiteboard 只操作已经存在于钉钉在线文档中的单页内嵌白板。创建白板卡片使用 dws doc whiteboard insert；普通文档块仍使用 dws doc block。

OpenNodes V1 的完整字段、节点类型、目录枚举和错误语义按需读取协议索引；不要根据本页概要猜测节点字段或 geometry、catalogId 等枚举值。渐变卡片、Frame 分支、SVG/Vector 等完整工作流见常用 Recipes。

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	确认后更新白板并按同一稳定目标精确读回

定位白板

每次操作都需要真实的文档 nodeId 和白板 partId。缺少 partId 时先读取文档 JSONML，查找 cardType=hetu 且 metadata.id 非空的 card；uuid 是 blockId，不能当作 partId。多个候选时必须让用户选择，不能取第一个。

dws doc read --node <DOC_ID> --content-format jsonml --scope tags --tags card --format json

读取

dws whiteboard +query --node <DOC_ID> --part-id <PART_ID> --format json

CLI 会把服务端 resultJson 字符串解析为结构化 JSON。白板命令不支持全局 --jq 或 --fields。

更新

更新文件使用 OpenNodes V1 信封：

{
  "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 不能用于局部修改。

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 的资源：

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 复用或传本地路径。

创建和删除白板卡片

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 回查。

4.5 KiB Raw Blame History Unescape Escape

钉钉文档内嵌白板

Shortcuts（无专用脚本/recipe 时优先）

定位白板

读取

更新

Vector / SVG 资源

创建和删除白板卡片

4.5 KiB

Raw Blame History