111 lines
4.5 KiB
Markdown
111 lines
4.5 KiB
Markdown
# 钉钉文档内嵌白板
|
||
|
||
`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 回查。
|