dsh-crwu-workbench 0.0.10

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

@@ -0,0 +1,249 @@
+# OpenNodes V1 — Update 信封、Append/Overwrite 和公共写入字段
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+## 5. Update 协议
+
+### 5.1 请求信封
+
+```ts
+interface OpenNodesUpdateRequest {
+  overwrite?: boolean;
+  source: {
+    schemaVersion: "1.0";
+    catalogVersion: "dml-v1";
+    nodes: OpenNodeWrite[];
+  };
+}
+```
+
+字段含义：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `overwrite` | 否 | `false` 或省略为 append；`true` 为 overwrite。 |
+| `source.schemaVersion` | 是 | 必须为 `1.0`。 |
+| `source.catalogVersion` | 是 | 必须为 `dml-v1`。 |
+| `source.nodes` | 是 | 本次创建的节点数组。append 至少一个；overwrite 允许空数组。 |
+
+`source` 不能直接使用 query 返回的 `OpenNodesDocument`，也不接受 `pages`。
+DWS 不接受 `pageId`；传入会在 CLI 本地校验阶段失败。
+
+V1 没有“按真实节点 ID patch 既有节点”的语义。`source.nodes` 中的每一项都会
+创建一个新节点，`id` 仅是本次请求内建立父子关系和连接线引用的临时 ID：
+append 是新增节点，overwrite 是整页删除后重新创建。
+
+### 5.2 Append 与 Overwrite
+
+> **注意：** `overwrite: true` 是破坏性操作，会删除当前白板页面的全部自有
+> 节点。调用前应先 query 并确认影响范围；`nodes: []` 会清空页面。不希望删除
+> 既有内容时，应使用 append。
+
+| 行为 | append | overwrite |
+| --- | --- | --- |
+| `overwrite` | `false` 或省略 | `true` |
+| 空 `nodes` | 禁止 | 允许，用于清空当前页面 |
+| 当前页面旧节点 | 全部保留 | 删除页面自有节点后创建新节点 |
+| 母版节点 | 保留 | 保留 |
+| 页面级设置 | 保留 | 保留 |
+| 原子性 | 全部成功或全部回滚 | 全部成功或全部回滚 |
+
+overwrite 会替换当前页面的全部自有节点，不要求旧节点本身可由 OpenNodes V1
+写入。因此页面中存在 image、PDF、复杂文本等只读节点，不会单独阻止清空页面。
+
+overwrite 会在删除前执行安全预检；以下情况会拒绝执行：
+
+- 节点被锁定：`lockedNode`。
+- 节点不允许被删除：`deleteForbidden`。
+- 页面包含无法安全保留或清理的关联数据：`unknownMetadataReference`。
+- 目标节点未能完整删除：`deleteFailed`。
+
+与被删除节点绑定且有明确清理规则的关联数据会随节点清理；无法安全保留或清理的
+关联数据会使 overwrite 失败。
+
+overwrite 只替换当前页面节点，不会重建页面，也不会修改主题等页面级设置。
+白板已有的主题会被保留；白板没有有效主题时也不会自动添加。调用方应使用
+已配置有效主题的白板，或者显式提供不依赖主题的颜色。
+
+### 5.3 成功结果
+
+```ts
+interface DWSWhiteboardUpdateResponse {
+  success: true;
+  nodeId: string;
+  partId: string;
+  resultJson: {
+    mode: "append" | "overwrite";
+    createdNodeIds: string[];
+    idMap: Record<string, string>;
+    deletedNodeCount: number;
+    message: string;
+  };
+}
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `success` | `true` 表示本次 DWS 调用成功。 |
+| `nodeId` | 输入的文档节点 ID。 |
+| `partId` | 输入的白板标识。 |
+| `resultJson.mode` | 实际执行的模式。 |
+| `resultJson.createdNodeIds` | 按请求节点顺序返回真实节点 ID。 |
+| `resultJson.idMap` | 请求中显式临时 ID 到真实节点 ID 的映射。 |
+| `resultJson.deletedNodeCount` | append 恒为 `0`；overwrite 为删除的页面自有节点数。 |
+| `resultJson.message` | 供人阅读的结果摘要，不应作为机器判断依据。 |
+
+响应可能增加其他可选字段；Agent 不应依赖本节未声明的字段。
+
+示例：
+
+```json
+{
+  "success": true,
+  "nodeId": "DOC_NODE_ID",
+  "partId": "WHITEBOARD_PART_ID",
+  "resultJson": {
+    "mode": "append",
+    "createdNodeIds": ["generated-title-id", "generated-body-id"],
+    "idMap": {
+      "title": "generated-title-id",
+      "body": "generated-body-id"
+    },
+    "deletedNodeCount": 0,
+    "message": "Created 2 Whiteboard nodes"
+  }
+}
+```
+
+## 6. Update 公共节点字段
+
+V1 可写节点公共字段如下：
+
+```ts
+interface OpenNodeWriteBase {
+  id?: string;
+  layer?: "background" | "normal" | "foreground";
+  zIndex?: number;
+  hidden?: boolean;
+}
+
+interface OpenChildNodeWriteBase extends OpenNodeWriteBase {
+  parentId?: string;
+}
+
+interface OpenSizedNodeWriteBase extends OpenChildNodeWriteBase {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  angle?: number;
+}
+
+interface OpenShapeNodeWrite extends OpenSizedNodeWriteBase {
+  type: "shape";
+  geometry: `dml:${string}`;
+  text?: OpenTextWrite;
+  style?: OpenNodeStyleWrite;
+}
+
+interface OpenTextNodeWrite extends OpenSizedNodeWriteBase {
+  type: "text";
+  text: OpenTextWrite;
+  style?: OpenNodeStyleWrite;
+}
+
+interface OpenConnectorNodeWrite extends OpenNodeWriteBase {
+  type: "connector";
+  start: OpenConnectorEndpointWrite;
+  end: OpenConnectorEndpointWrite;
+  routing: OpenConnectorRouting;
+  waypoints?: OpenPoint[];
+  style?: OpenNodeStyleWrite;
+}
+
+interface OpenStickyNoteNodeWrite extends OpenSizedNodeWriteBase {
+  type: "stickyNote";
+  text?: OpenTextWrite;
+  style?: OpenNodeStyleWrite;
+}
+
+interface OpenFrameNodeWrite extends OpenNodeWriteBase {
+  type: "frame";
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  angle?: 0;
+  title?: {
+    text: OpenTextWrite;
+    box?: { width: number; height: number };
+  };
+  style?: OpenNodeStyleWrite;
+  presentationOrder?: number;
+  resizeMode?: "free" | "fixedAspectRatio";
+}
+
+interface OpenGroupNodeWrite extends OpenChildNodeWriteBase {
+  id: string;
+  type: "group";
+  x: number;
+  y: number;
+}
+
+interface OpenVectorNodeWrite extends OpenSizedNodeWriteBase {
+  type: "vector";
+  resource: OpenManagedVectorResourceWrite;
+}
+
+interface OpenIconNodeWrite extends OpenSizedNodeWriteBase {
+  type: "icon";
+  catalogId: OpenIconCatalogId;
+}
+
+interface OpenPathNodeWrite extends OpenSizedNodeWriteBase {
+  type: "path";
+  path: OpenPathDataWrite;
+  style?: OpenNodeStyleWrite;
+}
+
+type OpenNodeWrite =
+  | OpenShapeNodeWrite
+  | OpenTextNodeWrite
+  | OpenConnectorNodeWrite
+  | OpenStickyNoteNodeWrite
+  | OpenFrameNodeWrite
+  | OpenGroupNodeWrite
+  | OpenVectorNodeWrite
+  | OpenIconNodeWrite
+  | OpenPathNodeWrite;
+```
+
+上面的联合类型是 update 的字段白名单。各辅助结构和完整枚举值在第 7 节定义；
+未出现在对应分支中的字段不能发送。
+
+| 字段 | 规则 |
+| --- | --- |
+| `id` | 可选的请求级临时 ID；非空、区分大小写、在请求内唯一。被引用时必须提供。 |
+| `type` | 必填，必须是 V1 可写类型。 |
+| `parentId` | 可选，引用同一请求中 group/frame 的临时 ID。 |
+| `x`、`y` | 除 connector 外必填；有父节点时为父节点相对坐标。 |
+| `width`、`height` | shape/text/stickyNote/frame/vector/icon/path 必填且大于 `0`；group/connector 只读。 |
+| `angle` | 可选，默认 `0`；frame 只允许 `0`；group/connector 只读。 |
+| `layer` | 可选；frame 默认 `background`，其他节点默认 `normal`。 |
+| `zIndex` | 可选的非负整数；相同值时按请求顺序稳定排序。 |
+| `hidden` | 可选布尔值，默认 `false`。 |
+
+以下 query 字段禁止写回：
+
+`children`、`absoluteBounds`、`locked`、`source`、`writeSupport`、
+`unsupportedFeatures`。
+
+关系规则：
+
+- `parentId` 只能引用同一请求中的 group 或 frame。
+- frame 和 connector 必须是页面直属节点，不能带 `parentId`。
+- group 可以嵌套，也可以放在 frame 中。
+- `children` 始终由各子节点的 `parentId` 推导。
+- 父子关系不能成环。
+- group 必须有临时 `id`、至少两个直接子节点，且不能全部隐藏。

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

@@ -0,0 +1,395 @@
+# OpenNodes V1 — 支持矩阵、富文本和样式
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+## 7. 节点类型
+
+### 7.1 支持矩阵
+
+| `type` | query | update | 主要字段 |
+| --- | --- | --- | --- |
+| `shape` | 支持 | 支持 | `geometry`、`text?`、`style?` |
+| `text` | 支持 | 支持 | `text`、`style?` |
+| `connector` | 支持 | 支持 | `start`、`end`、`routing`、`waypoints?`、`style?` |
+| `stickyNote` | 支持 | 支持 | `text?`、`style?` |
+| `frame` | 支持 | 支持 | `title?`、`style?`、`presentationOrder?`、`resizeMode?` |
+| `group` | 支持 | 支持 | 子关系通过 `parentId` 表达 |
+| `image` | 支持 | 只读 | 仅公共字段 |
+| `vector` | 支持 | 支持 | `resource` |
+| `icon` | 支持 | 支持 | `catalogId` |
+| `path` | 支持 | 支持 | `path`、`style?` |
+| `pdf` | 支持 | 只读 | 仅公共字段 |
+| `media` | 支持 | 只读 | 仅公共字段 |
+| `webLink` | 支持 | 只读 | 仅公共字段 |
+| `table` | 支持 | 只读 | 仅公共字段 |
+| `chart` | 支持 | 只读 | 仅公共字段 |
+| `uml` | 支持 | 只读 | 仅公共字段 |
+| `swimlane` | 支持 | 只读 | 仅公共字段 |
+| `mind` | 支持 | 只读 | 仅公共字段 |
+| `timer` | 支持 | 只读 | 仅公共字段 |
+| `placeholder` | 支持 | 只读 | 仅公共字段 |
+| `unknown` | 支持 | 只读 | 未识别或尚未定义独立语义的节点统一映射到此类型 |
+
+表中标记为只读的类型仍会完整返回公共几何、层级和顺序信息，但 update 提交会以
+`nodeTypeUnsupported` 失败。
+
+`timer`、`table`、`webLink` 不支持 V1 update。query 仅返回这些节点的公共几何、
+层级、顺序和诊断字段，不承诺完整业务字段。文字 run 中的 `link` 是富文本能力，
+不属于 `webLink` 节点，V1 支持读写。
+
+`webLink` 只保留只读查询；OpenNodes V1 不支持创建或重建该节点。
+
+### 7.2 Text
+
+query 和 update 均支持普通段落、无序列表、有序列表、多 block、多 run 和文字
+链接：
+
+```ts
+interface OpenTextRun {
+  text: string;
+  marks?: {
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    color?: string;
+    highlight?: string;
+  };
+  link?: { url: string };
+}
+
+interface OpenTextBlock {
+  type: "paragraph" | "bulletList" | "orderedList";
+  horizontalAlign?: "left" | "center" | "right";
+  runs: OpenTextRun[];
+}
+
+interface OpenTextWrite {
+  blocks: OpenTextBlock[];
+  verticalAlign?: "top" | "center" | "bottom";
+  padding?: number | [number, number];
+}
+
+interface OpenText extends OpenTextWrite {
+  plainText: string;
+  writeSupport: "readWrite" | "readOnly";
+  unsupportedFeatures?: string[];
+}
+```
+
+约束：
+
+- `blocks.length >= 1`，每个 block 的 `type` 必须是 `paragraph`、
+  `bulletList` 或 `orderedList`。
+- 每个 block 都必须满足 `runs.length >= 1`。
+- run 的 `text` 不能包含 `\r`、`\n`、U+2028 或 U+2029。换行和列表项使用
+  独立 block 表达；每一段或每个列表项应写成一个 block，而不是把原始换行符
+  放进单个 run。
+- 每个 `bulletList` / `orderedList` block 表示一个列表项；服务端会把连续且同类的
+  block 解释为同一个列表中的多个列表项。
+- `link.url` 长度必须为 `1..2048`，不能包含控制字符、`<`、`>`。支持无 scheme
+  的相对/裸链接，以及 `http`、`https`、`mailto`、`tel`、`dingtalk` scheme；
+  `javascript:`、`data:` 等可执行或未知 scheme 会被拒绝。
+- 相邻且 URL 相同的 linked run 会呈现为同一个链接，同时保留各 run 自己的 marks。
+- `fontSize > 0`，padding 各项必须大于等于 `0`。
+- `plainText`、文本级 `writeSupport` 和 `unsupportedFeatures` 是 query-only。
+- text 节点必须提供 `text`；shape 和 stickyNote 的 `text` 可省略。
+- 受支持的 paragraph、列表、链接、多 run 都保持
+  `writeSupport = "readWrite"`；未知 list style、非法链接、未支持的 block 或
+  run marks 会令文本和所属节点变为 `readOnly`。
+
+下面的文本会显示为两个段落，第一段由两个不同样式的 run 组成：
+
+```json
+{
+  "blocks": [
+    {
+      "type": "paragraph",
+      "horizontalAlign": "left",
+      "runs": [
+        {
+          "text": "OpenNodes ",
+          "marks": { "fontSize": 18, "bold": true, "color": "#2563EB" }
+        },
+        {
+          "text": "rich text",
+          "marks": { "fontSize": 18, "italic": true, "color": "#0F172A" }
+        }
+      ]
+    },
+    {
+      "type": "paragraph",
+      "horizontalAlign": "right",
+      "runs": [
+        {
+          "text": "第二段",
+          "marks": { "fontSize": 16, "underline": true, "color": "#047857" }
+        }
+      ]
+    }
+  ],
+  "verticalAlign": "center",
+  "padding": [4, 8]
+}
+```
+
+同一 `OpenTextWrite` 结构适用于独立 text 节点、shape 文本、stickyNote 文本和
+frame title。
+
+下面三个 block 会生成两个无序列表项，其中第二项包含文字链接：
+
+```json
+{
+  "blocks": [
+    {
+      "type": "bulletList",
+      "runs": [{ "text": "准备输入数据" }]
+    },
+    {
+      "type": "bulletList",
+      "runs": [
+        {
+          "text": "查看钉钉文档",
+          "marks": { "underline": true },
+          "link": { "url": "https://alidocs.dingtalk.com" }
+        }
+      ]
+    },
+    {
+      "type": "orderedList",
+      "runs": [{ "text": "执行生成" }]
+    }
+  ]
+}
+```
+
+颜色接受以下 CSS 形式：3/4/6/8 位十六进制、颜色名，以及
+`rgb()`、`rgba()`、`hsl()`、`hsla()`、`oklch()`、`lab()`、`lch()`、
+`color()`。字符串最长 128 字符，不能包含控制字符、`<`、`>` 或 `;`。
+这里只接受可独立解析的字面量；依赖外部样式上下文的 `var()`、`calc()`、
+`color-mix()` 等动态表达式不属于 V1。颜色名必须是标准 CSS named color，
+任意字母串不会被当成颜色。
+
+### 7.3 Style
+
+query 可表达：
+
+- `none`、`solid`、`theme`、线性渐变、径向渐变和图片 paint。
+- shadow、blur 和 unknown effect。
+
+V1 update 支持 `none`、`solid`、`theme`、线性渐变、九方向径向渐变，以及
+单个自定义 shadow。主题明暗参数和渐变色标位置使用 `0～100` 的百分比，
+不会归一化成 `0～1`：
+
+```ts
+type OpenRadialGradientPosition =
+  | "topLeft"
+  | "topCenter"
+  | "topRight"
+  | "centerLeft"
+  | "center"
+  | "centerRight"
+  | "bottomLeft"
+  | "bottomCenter"
+  | "bottomRight";
+
+interface OpenColorStop {
+  offset: number;
+  color: string;
+  opacity?: number;
+}
+
+interface OpenImagePaint {
+  type: "image";
+  resource: {
+    kind: "managed" | "external" | "embedded" | "unresolved";
+    resourceId?: string;
+  };
+  intrinsicWidth: number;
+  intrinsicHeight: number;
+}
+
+type OpenPaint =
+  | { type: "none" }
+  | { type: "solid"; color: string; opacity?: number }
+  | {
+      type: "theme";
+      token: string;
+      lumMod?: number;
+      lumOff?: number;
+      resolvedColor?: string;
+    }
+  | {
+      type: "linearGradient";
+      angle: number;
+      stops: OpenColorStop[];
+    }
+  | {
+      type: "radialGradient";
+      position: OpenRadialGradientPosition | "custom";
+      stops: OpenColorStop[];
+    }
+  | OpenImagePaint;
+
+type OpenEffect =
+  | {
+      type: "shadow";
+      offsetX: number;
+      offsetY: number;
+      blur: number;
+      color: string;
+      opacity: number;
+    }
+  | { type: "blur"; blur: number }
+  | { type: "unknown" };
+
+interface OpenNodeStyle {
+  opacity?: number;
+  fill?: OpenPaint;
+  stroke?: {
+    paint: OpenPaint;
+    width?: number;
+    dash?: number[];
+    lineCap?: "butt" | "round" | "square";
+    lineJoin?: "miter" | "round" | "bevel";
+  };
+  effects?: OpenEffect[];
+  writeSupport: "readWrite" | "readOnly";
+  unsupportedFeatures?: string[];
+}
+
+interface OpenColorStopWrite {
+  offset: number; // [0, 100]，百分比
+  color: string;
+  opacity?: number; // [0, 1]
+}
+
+type OpenPaintWrite =
+  | { type: "none" }
+  | { type: "solid"; color: string; opacity?: number }
+  | {
+      type: "theme";
+      token: string;
+      lumMod?: number; // [0, 100]，默认 100
+      lumOff?: number; // [0, 100]，默认 0
+    }
+  | {
+      type: "linearGradient";
+      angle: number;
+      stops: OpenColorStopWrite[];
+    }
+  | {
+      type: "radialGradient";
+      position: OpenRadialGradientPosition;
+      stops: OpenColorStopWrite[];
+    };
+
+interface OpenShadowEffectWrite {
+  type: "shadow";
+  offsetX: number;
+  offsetY: number;
+  blur: number;
+  color: string;
+  opacity: number;
+}
+
+interface OpenNodeStyleWrite {
+  opacity?: number;
+  fill?: OpenPaintWrite;
+  stroke?: {
+    paint: OpenPaintWrite;
+    width?: number;
+    dash?: number[];
+    lineCap?: "butt" | "round" | "square";
+    lineJoin?: "miter" | "round" | "bevel";
+  };
+  effects?: OpenShadowEffectWrite[];
+}
+```
+
+约束：
+
+- opacity 范围为 `[0, 1]`。
+- solid paint 的 `color` 与 `opacity` 在 query 后仍保持独立字段，不会合并为
+  动态 CSS 表达式。
+- theme 的 `token` 必须能在当前白板主题中解析；
+  `lumMod`、`lumOff` 范围均为 `[0, 100]`。token 不存在时在
+  Request graph 阶段返回 `themeTokenNotFound`，不会写出部分节点。
+  token 长度为 `1～64`，首尾不能有空白，也不能包含空白、控制字符、
+  `<`、`>` 或 `;`。
+- query 的 theme paint 还会返回按当前白板主题计算出的 query-only
+  `resolvedColor`。调用方写入时只传 `token/lumMod/lumOff`，不传
+  `resolvedColor`。
+- 渐变必须至少有一个 stop；`offset` 范围为 `[0, 100]`，单位是百分比。
+- 线性渐变 `angle` 范围为 `[0, 360]`。
+- 径向渐变只接受上述九宫格位置。query 遇到九宫格以外的位置时返回
+  `position: "custom"` 并将该节点标为只读。
+- `effects` 最多包含一个 `shadow`；`offsetX/offsetY` 必须是有限数，
+  `blur >= 0`，shadow opacity 范围为 `[0, 1]`。
+- stroke width 和 dash 各项必须大于等于 `0`。
+- 一旦提供 stroke，`stroke.paint` 必填。
+- 样式级 `writeSupport` 和 `unsupportedFeatures` 是 query-only。
+- 能在当前白板主题中解析且明暗参数合法的 theme paint 可写。无法解析的主题
+  token、越界的主题明暗参数、image paint、blur、unknown effect、叠加 effect
+  或自定义径向位置会令节点只读；受支持的 theme、渐变和单个 shadow 本身不会
+  令节点只读。
+
+主题色示例：
+
+```json
+{
+  "fill": {
+    "type": "theme",
+    "token": "ac3",
+    "lumMod": 20,
+    "lumOff": 80
+  },
+  "stroke": {
+    "paint": {
+      "type": "theme",
+      "token": "sk1",
+      "lumMod": 80,
+      "lumOff": 20
+    },
+    "width": 2
+  }
+}
+```
+
+示例中的 `ac3`、`sk1` 只是主题 token 示例，不是所有白板都可用的全局枚举。
+调用方只能使用已确认可由当前白板主题解析的 token；无法确认时应改用
+`solid` 颜色。
+
+DWS 不提供新增、修改或切换主题的命令。当前白板没有有效主题时，应改用
+`solid`。
+
+示例：
+
+```json
+{
+  "fill": {
+    "type": "linearGradient",
+    "angle": 35,
+    "stops": [
+      { "offset": 0, "color": "#1677ff", "opacity": 0.4 },
+      { "offset": 100, "color": "#69b1ff" }
+    ]
+  },
+  "effects": [
+    {
+      "type": "shadow",
+      "offsetX": 8,
+      "offsetY": 8,
+      "blur": 19,
+      "color": "rgba(93,190,172,1)",
+      "opacity": 0.5
+    }
+  ]
+}
+```
+
+未传 `style` 时使用节点类型的默认样式。调用方如需稳定的视觉结果，应显式传入
+`fill` 和 `stroke`。