dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/references/whiteboard/open-nodes-v1/05-shape-frame-group-connector.md

@@ -0,0 +1,186 @@
+# OpenNodes V1 — Shape、Text、Sticky note、Frame、Group 和 Connector
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+### 7.4 Shape
+
+shape 必须提供 `geometry`，格式为 `dml:<name>`：
+
+```json
+{
+  "id": "shape-1",
+  "type": "shape",
+  "x": 100,
+  "y": 80,
+  "width": 160,
+  "height": 100,
+  "geometry": "dml:roundRect",
+  "style": {
+    "fill": {
+      "type": "solid",
+      "color": "#DCEEFF"
+    },
+    "stroke": {
+      "paint": {
+        "type": "solid",
+        "color": "#225588"
+      },
+      "width": 2
+    }
+  }
+}
+```
+
+query 可能返回 `adjustments`，但 V1 update 不支持写入；带 adjustments 的
+shape 会标为只读。`dml-v1` 的完整 geometry 目录见附录 A。
+
+### 7.5 Text node 与 Sticky note
+
+text node 使用公共几何、必填 `text` 和可选 `style`。
+
+stickyNote 使用公共几何、可选 `text` 和可选 `style`。省略 `text` 时创建空
+便签。query 还可能返回：
+
+- `creator`：创建者展示信息。
+- `tags`：标签 ID、文本和背景 paint。
+
+这两个字段是 query-only；存在 creator 或 tags 的 stickyNote 会被标为只读。
+
+### 7.6 Frame
+
+frame 的 update 结构见第 6 节 `OpenFrameNodeWrite`。
+
+约束：
+
+- frame 必须是页面直属节点，不能带 `parentId`。
+- angle 只允许 `0`。
+- `presentationOrder` 是非负整数，并且不能和已有或本次创建的 frame 冲突。
+- frame 的子节点通过子节点 `parentId` 引用 frame 临时 ID。
+- frame 不能包含 frame 或 connector。
+- frame 默认 layer 为 `background`。
+
+### 7.7 Group
+
+group 的写入字段只有公共字段中的 `id`、`parentId?`、`x`、`y`、`layer?`、
+`zIndex?` 和 `hidden?`。其 width、height、angle 和 children 都由服务端根据
+子节点推导。
+
+group 必须：
+
+- 提供临时 `id`。
+- 至少包含两个直接子节点。
+- 至少有一个直接子节点可见。
+
+group 的任一子节点为只读时，query 会把 group 一并标为只读。
+
+### 7.8 Connector
+
+connector 的几何由端点和路由推导，因此 update 不能提供 `x`、`y`、
+`width`、`height` 或 `angle`。
+
+query 的连接线结构如下：
+
+```ts
+type OpenConnectorRouting =
+  | "straight"
+  | "polyline"
+  | "curve"
+  | "orthogonal";
+
+interface OpenConnectorMarker {
+  catalogId: string;
+}
+
+type OpenConnectorAnchor =
+  | {
+      mode: "fixed";
+      side: "top" | "right" | "bottom" | "left";
+      position: OpenPoint;
+    }
+  | {
+      mode: "fixed";
+      side: "custom";
+      position: OpenPoint;
+    };
+
+type OpenConnectorEndpoint =
+  | {
+      type: "point";
+      point: OpenPoint;
+      marker: OpenConnectorMarker;
+    }
+  | {
+      type: "node";
+      nodeRef: { scope: "document"; id: string };
+      anchor: OpenConnectorAnchor;
+      resolvedPoint: OpenPoint;
+      marker: OpenConnectorMarker;
+    };
+
+interface OpenBezierSegment {
+  start: OpenPoint;
+  control1: OpenPoint;
+  control2: OpenPoint;
+  end: OpenPoint;
+}
+
+type OpenResolvedConnectorPath =
+  | { type: "polyline"; points: OpenPoint[] }
+  | { type: "bezier"; segments: OpenBezierSegment[] };
+```
+
+update 端点有两种形式：
+
+```ts
+type OpenConnectorEndpointWrite =
+  | {
+      type: "point";
+      point: { x: number; y: number };
+      marker?: { catalogId: "none" | "arrow.open" | "arrow.filled" };
+    }
+  | {
+      type: "node";
+      nodeRef: { scope: "request"; id: string };
+      anchor?:
+        | { mode: "auto" }
+        | {
+            mode: "fixed";
+            side: "top" | "right" | "bottom" | "left";
+          };
+      marker?: { catalogId: "none" | "arrow.open" | "arrow.filled" };
+    };
+```
+
+query 的 marker `catalogId` 使用 `string`，以便返回无法映射的既有 marker；
+update 只接受上面列出的 `"none"`、`"arrow.open"`、`"arrow.filled"`。
+
+路由规则：
+
+| `routing` | `waypoints` |
+| --- | --- |
+| `straight` | 禁止提供，包括空数组。 |
+| `polyline` | 必须至少提供一个。 |
+| `curve` | 可选。 |
+| `orthogonal` | 可选；显式点路径的相邻线段必须水平或垂直。 |
+
+其他约束：
+
+- 所有 point 和 waypoint 都使用页面绝对坐标。
+- node 端点只能引用同一请求中的 shape、text、stickyNote、frame、group 或 path。
+- node 端点不能引用隐藏节点、connector 或 query 中既有节点。
+- update 引用范围固定为 `scope: "request"`；query 返回的节点引用范围为
+  `scope: "document"`，不能直接回写。
+- 同一连接线的两端不能引用同一个节点。
+- 零长度或无效路径会被拒绝。
+- marker 省略时默认为 `none`。
+- anchor 省略时按 `auto` 处理。
+
+query 额外返回服务端解析后的：
+
+- node 端点 `resolvedPoint`。
+- fixed anchor 的归一化 `position`。
+- `resolvedPath`，类型为 polyline points 或 cubic bezier segments。
+- 由真实路径推导的 `absoluteBounds`。
+
+这些解析字段都是 query-only。

package/skills/dws/dingtalk-misc/references/whiteboard/open-nodes-v1/06-vector-icon-path.md

@@ -0,0 +1,313 @@
+# OpenNodes V1 — Vector、Icon 和 Path
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+### 7.9 Vector（已上传 SVG/矢量资源）
+
+`vector` 表示已经通过 `dws doc media upload` 获得稳定引用的 SVG/矢量图片。
+OpenNodes 只接收上传结果中的资源引用，不接收本地路径或原始 SVG/XML 内容。
+
+上传时必须使用与后续白板更新相同的文档 `nodeId`：
+
+```bash
+dws doc media upload \
+  --node <DOC_NODE_ID> \
+  --file ./icon.svg \
+  --mime-type image/svg+xml \
+  --format json
+```
+
+将上传结果的 `resourceId` 和 `resourceUrl` 分别写入
+`resource.resourceId` 和 `resource.url`。
+
+Update 必须提供完整的托管资源信息：
+
+```ts
+interface OpenManagedVectorResourceWrite {
+  kind: "managed";
+  resourceId: string;
+  url: string;
+}
+```
+
+完整节点结构见第 6 节 `OpenVectorNodeWrite`。
+
+`resource` 字段规则：
+
+| 字段 | 必填 | 规则 |
+| --- | --- | --- |
+| `kind` | 是 | 当前只允许固定值 `managed`，表示资源已经通过 DWS 上传。 |
+| `resourceId` | 是 | 资源稳定 ID，长度 1～256，只允许字母、数字、`.`、`_`、`:`、`-`。 |
+| `url` | 是 | 已上传资源地址，最长 4096；必须包含且只能包含一个同值的 `resourceId` 查询参数。 |
+
+`url` 必须直接使用 `dws doc media upload` 返回的 `resourceUrl`，不得自行拼装
+或修改。
+
+以下内容会被拒绝：
+
+- 原始 SVG/XML、`data:`、`blob:`、`http:` URL。
+- `//host/path` 协议相对地址，以及自行构造或修改的其他相对地址。
+- 含空白、控制字符、反斜杠、fragment 或用户凭证的 URL。
+- URL 缺少 `resourceId`、重复出现 `resourceId`，或者 URL 中 ID 与显式
+  `resource.resourceId` 不一致。
+- `resource` 缺失、字段不完整、`kind` 不是 `managed`，或包含未知字段。
+
+完整 Append 示例：
+
+```json
+{
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "uploaded-svg-1",
+        "type": "vector",
+        "x": 100,
+        "y": 80,
+        "width": 240,
+        "height": 180,
+        "angle": 0,
+        "resource": {
+          "kind": "managed",
+          "resourceId": "0c1c94e1-f9af-4228-b32f-42bbd1555253",
+          "url": "https://resources.example.com/assets/opaque-path?resourceId=0c1c94e1-f9af-4228-b32f-42bbd1555253"
+        }
+      }
+    ]
+  },
+  "overwrite": false
+}
+```
+
+示例中的 `resources.example.com` 是占位域名，实际调用必须使用
+`dws doc media upload` 返回的 `resourceUrl`。
+
+`resourceId` 同时显式出现并包含在 URL 中，用于校验资源身份与地址是否一致。
+两者必须来自同一次 `dws doc media upload` 结果。
+
+Query 的 `resource` 可能是：
+
+```ts
+type OpenVectorResource =
+  | { kind: "managed"; resourceId: string; url: string }
+  | { kind: "external" | "embedded" | "unresolved" };
+```
+
+- 能识别为托管资源的引用返回完整 `managed` 信息。
+- HTTP(S) 外链但不满足托管资源契约时返回 `external`。
+- `data:`/`blob:` 返回 `embedded`。
+- 其他缺失或无法识别的地址返回 `unresolved`。
+- 非 `managed` 资源会令节点只读，并分别产生
+  `vector.resource.external`、`vector.resource.embedded` 或
+  `vector.resource.unresolved`。
+
+V1 vector update 不接受 `style`。既有节点包含 V1 无法表达的 fill、stroke、
+opacity、effect 或 adjustments 时，query 仍可读取资源和几何，但节点会标为只读。
+不影响资源内容的兼容性装饰不会单独令节点变为只读。
+
+DWS 会校验资源引用。上传与 `whiteboard update` 必须使用同一个文档
+`nodeId`；不要跨文档复用资源，也不要使用临时 `uploadUrl`。
+
+### 7.10 Icon（内置图标）
+
+`icon` 表示内置图标。OpenNodes 使用版本化的 `catalogId` 作为稳定标识，
+允许值见下列类型定义和附录 B。
+
+Update 结构：
+
+```ts
+type OpenIconCatalogId =
+  | `emoji/${
+      | "happy"
+      | "smile"
+      | "laugh"
+      | "fighting"
+      | "like"
+      | "ok"
+      | "please"
+      | "face-plam"
+      | "tears-of-joy"
+      | "cry"
+      | "question"
+      | "face-with-sweat"
+      | "bloody-nose"
+      | "doggy"}`
+  | `tools/${
+      | "pad"
+      | "blue-note"
+      | "yellow-notes"
+      | "chart"
+      | "chart-2"
+      | "pencil"
+      | "pen"
+      | "bag"
+      | "rocket"
+      | "fire"
+      | "gold"
+      | "light"
+      | "pin"
+      | "red-flag"
+      | "tea"
+      | "island"
+      | "ball"
+      | "lucky-fish"
+      | "coffee"
+      | "milky-tea"
+      | "pan"}`
+  | `priority/priority-${1 | 2 | 3 | 4 | 5 | 6 | 7}`
+  | `task/${
+      | "task-start"
+      | "task-oct"
+      | "task-3oct"
+      | "task-half"
+      | "task-5oct"
+      | "task-7oct"
+      | "task-done"}`;
+```
+
+完整节点结构见第 6 节 `OpenIconNodeWrite`。
+
+完整 Append 示例：
+
+```json
+{
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "pencil-icon",
+        "type": "icon",
+        "x": 100,
+        "y": 80,
+        "width": 48,
+        "height": 48,
+        "catalogId": "tools/pencil"
+      }
+    ]
+  },
+  "overwrite": false
+}
+```
+
+规则：
+
+- `catalogId` 必填，格式为 `<group>/<name>`，并且必须精确命中附录 B 的
+  `dml-v1` allowlist；大小写、连字符和历史拼写都不能自行修正。
+- 当前目录有 `emoji`、`tools`、`priority`、`task` 四组，共 49 项。
+- update 只接受 `catalogId`，不接受 `group`、`name`、`style` 或 `resource`。
+- 内置 icon 不需要调用方上传资源，也不需要 `resourceId`。
+- 任意已上传 SVG 或自定义图标应使用 `vector`，并按 7.9 节提供完整
+  `resource` 信息，不能伪造一个 icon `catalogId`。
+- icon 可以作为 group/frame 子节点；V1 connector 的 node 端点当前仍不接受
+  icon 作为目标。
+
+Query 返回相同的 `catalogId`。既有 icon 无法映射到当前目录时，节点仍会以
+`type: "icon"` 返回以便诊断，但 `writeSupport` 为 `readOnly`，原因包含
+`icon.catalogId`。非默认 opacity、filter/effect、text 或 adjustments 同样会令节点
+只读。
+
+### 7.11 Path（自由画笔）
+
+`path` 表示自由画笔轨迹。OpenNodes 保留两组互相独立的尺寸：
+
+- 节点公共 `width` / `height` 是画布上的实际渲染尺寸，缩放节点时会变化。
+- `path.intrinsicWidth` / `path.intrinsicHeight` 是 SVG path 自身的坐标空间尺寸，
+  表示 `path.data` 使用的内部坐标空间。
+
+```ts
+interface OpenPathData {
+  data: string;
+  intrinsicWidth: number;
+  intrinsicHeight: number;
+}
+
+type OpenPathDataWrite = OpenPathData;
+```
+
+完整 update 节点结构见第 6 节 `OpenPathNodeWrite`。query 和 update 的 `path`
+字段结构相同，但 update 仍必须满足下方命令子集和大小限制。
+
+```json
+{
+  "id": "freehand-stroke",
+  "type": "path",
+  "x": 120,
+  "y": 100,
+  "width": 500,
+  "height": 150,
+  "path": {
+    "data": "M0,75 Q50,0 100,75 Q150,150 200,75 Q250,0 300,75 Q350,150 400,75 Q450,0 500,75",
+    "intrinsicWidth": 500,
+    "intrinsicHeight": 150
+  },
+  "style": {
+    "fill": { "type": "none" },
+    "stroke": {
+      "paint": { "type": "solid", "color": "#7C3AED" },
+      "width": 10,
+      "lineCap": "round",
+      "lineJoin": "round"
+    }
+  }
+}
+```
+
+下面是一个仍然只使用 V1 命令子集、但包含 12 段二次贝塞尔曲线的蝴蝶轮廓。
+它显式回到起点，因此不需要使用尚未支持的 `Z`：
+
+```json
+{
+  "id": "complex-butterfly-path",
+  "type": "path",
+  "x": 1500,
+  "y": 1215,
+  "width": 500,
+  "height": 420,
+  "path": {
+    "data": "M250,180 Q210,105 145,70 Q55,25 35,110 Q10,195 125,220 Q35,275 80,355 Q125,415 210,315 Q235,285 250,250 Q265,285 290,315 Q375,415 420,355 Q465,275 375,220 Q490,195 465,110 Q445,25 355,70 Q290,105 250,180",
+    "intrinsicWidth": 500,
+    "intrinsicHeight": 420
+  },
+  "style": {
+    "opacity": 0.96,
+    "fill": {
+      "type": "solid",
+      "color": "#EDE9FE",
+      "opacity": 0.72
+    },
+    "stroke": {
+      "paint": {
+        "type": "solid",
+        "color": "#6D28D9"
+      },
+      "width": 8,
+      "lineCap": "round",
+      "lineJoin": "round"
+    }
+  }
+}
+```
+
+V1 path 写入约束如下：
+
+- `data` 必须是一个绝对 `M`，后跟至少一个显式写出的绝对 `Q`；不接受相对命令，
+  也不接受 `L`、`C`、`A`、`Z` 等通用 SVG 命令。
+- 所有命令参数必须完整且为有限数值；单节点 `data` 最长 1 MiB，最多 50,000 个
+  命令。
+- `intrinsicWidth` 和 `intrinsicHeight` 必须为有限正数；它们不要求等于节点的
+  `width` 和 `height`。
+- 未传 `style` 时，默认使用透明填充、`#222222` 描边、宽度 5，以及 round
+  line cap/join。需要稳定视觉结果时仍应显式传入 `style`。
+- path 可以作为 group/frame 的子节点，也可以作为同一 update 请求中 connector
+  的 node 端点。
+
+query 会把其他能够解析的 SVG path 保留为 `type: "path"`，但标记为
+`readOnly`，原因包含 `path.commands`；超出上述 V1 限制时使用
+`path.data.size` 或 `path.commands.limit`。既有 path 带 text、adjustments、非
+`nonzero` fillRule 或 V1 无法表达的样式时也会只读。仅包含不影响画笔几何的
+兼容性信息时，不会因此变为只读。theme stroke 遵循通用 style 契约：query 会
+保留 token 和明暗参数；只要 token 能在当前白板主题中解析，就可以按 theme
+paint 回写。