2.5 KiB
2.5 KiB
DWS OpenNodes V1 协议说明
本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见 协议索引。
协议版本：
schemaVersion = "1.0"，catalogVersion = "dml-v1"。
1. 协议用途
OpenNodes 是 DWS 白板命令使用的语义节点协议，提供两类能力：
dws whiteboard query：返回稳定、可理解的页面和节点数据。dws whiteboard update：接收受约束的节点描述，以append或overwrite模式修改白板。
调用方只应依赖本文声明的语义字段和行为：
query不修改白板。update全部成功或全部回滚，不返回中间状态。- 未声明的存储字段、类型名称和处理过程不属于协议承诺。
OpenNodes V1 支持的节点类型、字段和读写范围见第 7 节。
DWS 负责身份认证和权限校验。Vector 资源准备使用 dws doc media upload，
具体流程见白板命令参考。
2. 版本与兼容原则
| 字段 | 当前值 | 作用 |
|---|---|---|
schemaVersion |
1.0 |
控制文档结构、节点字段和字段语义。 |
catalogVersion |
dml-v1 |
控制允许写入的 DML 几何、连接线标记和内置 icon 目录。 |
V1 采用严格校验：
- 必填字段缺失会失败。
- 未声明字段会失败，不会被静默忽略。
- query-only 字段出现在 update 中会以
readOnlyField失败。 - 不支持的节点类型、目录值或引用范围会失败。
null不代表“使用默认值”；除非字段类型明确允许，否则会失败。
本文列出的请求枚举值都是协议字面量，调用方必须按文档中的大小写和拼写原样传入， 不能自行转换或猜测。响应中未来可能增加可选字段，调用方应忽略不认识的响应字段。
调用方必须原样携带当前版本值。新增不兼容结构时应升级
schemaVersion；修改 DML、marker 或 icon 目录时应评估并升级
catalogVersion。
3. DWS 命令一览
| 命令 | 所需权限 | 效果 |
|---|---|---|
dws whiteboard query --node ... --part-id ... |
可查看白板 | 读取单页白板，不修改内容。 |
dws whiteboard update --node ... --part-id ... --source ... --yes |
可编辑白板 | 追加节点或整页重建；所有更新都需先取得用户确认。 |
DWS 当前只支持文字文档中已有的单页内嵌白板。命令不接收 pageId，也不提供
创建页面、切换页面或按既有节点 ID 局部修改的能力。