dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/references/whiteboard/compose.md

@@ -0,0 +1,200 @@
+# 白板构图：Shape、Connector、Frame 与样式
+
+仅在构造 OpenNodes 时读取；通用目标、确认、调用预算和读回规则沿用根 Reference。
+节点放入信封，以 `--source @whiteboard.json` 传入。
+
+## 首次远端写入前检查
+
+- 信封是 `overwrite=false`、`1.0` / `dml-v1`、非空 `nodes`。
+- 每个节点（包括 connector）都有唯一稳定 ID；connector `nodeRef` 和 `parentId`
+  只引用本次节点，后者是 Frame。
+- connector 不含 `x/y/width/height/angle/parentId`：端点只用 point 或同一请求的
+  `scope=request` 节点，节点端点不得引用 connector/hidden 节点或形成自环；straight
+  禁止 waypoints，polyline 至少一个有限坐标点。
+- 坐标有限、尺寸为正；catalog 值来自本页安全子集或一份精确协议依据。
+- 所需节点、文本、连接、父子关系都在同一稳定 Payload 文件。
+- 有边界的分区、泳道和卡片组直接使用 Frame，避免 group 坐标规范化后反复修改。
+
+## 安全子集
+
+geometry：`dml:rect` / `dml:roundRect` / `dml:diamond`；marker：`none` /
+`arrow.open` / `arrow.filled`；icon：`task/task-done`；path：绝对 `M` + 显式绝对
+`Q` 和正数 intrinsic 尺寸。原样复用这些值不读取 catalog；其他值只读对应协议
+章节，不加载完整目录。
+
+## Shape 与 Connector
+
+connector 只能引用同一请求内的临时节点 ID：
+
+```json
+{
+  "overwrite": false,
+  "source": {
+    "schemaVersion": "1.0",
+    "catalogVersion": "dml-v1",
+    "nodes": [
+      {
+        "id": "start",
+        "type": "shape",
+        "x": 80,
+        "y": 100,
+        "width": 160,
+        "height": 72,
+        "geometry": "dml:roundRect",
+        "style": {"fill": {"type": "solid", "color": "#DBEAFE"}},
+        "text": {
+          "blocks": [{
+            "type": "paragraph",
+            "horizontalAlign": "center",
+            "runs": [{"text": "开始", "marks": {"bold": true}}]
+          }],
+          "verticalAlign": "center"
+        }
+      },
+      {
+        "id": "finish",
+        "type": "shape",
+        "x": 360,
+        "y": 100,
+        "width": 160,
+        "height": 72,
+        "geometry": "dml:roundRect",
+        "style": {"fill": {"type": "solid", "color": "#A7F3D0"}},
+        "text": {
+          "blocks": [{
+            "type": "paragraph",
+            "horizontalAlign": "center",
+            "runs": [{"text": "完成", "marks": {"bold": true}}]
+          }],
+          "verticalAlign": "center"
+        }
+      },
+      {
+        "id": "start-to-finish",
+        "type": "connector",
+        "start": {
+          "type": "node",
+          "nodeRef": {"scope": "request", "id": "start"},
+          "anchor": {"mode": "fixed", "side": "right"}
+        },
+        "end": {
+          "type": "node",
+          "nodeRef": {"scope": "request", "id": "finish"},
+          "anchor": {"mode": "fixed", "side": "left"},
+          "marker": {"catalogId": "arrow.filled"}
+        },
+        "routing": "straight"
+      }
+    ]
+  }
+}
+```
+
+## 样式、Icon 与 Path 片段
+
+对象彼此独立，只把本次需要的节点加入 `source.nodes`：
+
+```json
+[
+  {
+    "id": "styled-card",
+    "type": "shape",
+    "x": 80,
+    "y": 80,
+    "width": 300,
+    "height": 140,
+    "geometry": "dml:roundRect",
+    "style": {
+      "fill": {
+        "type": "linearGradient",
+        "angle": 35,
+        "stops": [
+          {"offset": 0, "color": "#3B82F6"},
+          {"offset": 100, "color": "#10B981"}
+        ]
+      },
+      "stroke": {
+        "paint": {"type": "solid", "color": "#2563EB"},
+        "width": 2
+      },
+      "effects": [{
+        "type": "shadow",
+        "offsetX": 5,
+        "offsetY": 7,
+        "blur": 18,
+        "color": "#0F172A",
+        "opacity": 0.22
+      }]
+    }
+  },
+  {
+    "id": "done-icon",
+    "type": "icon",
+    "x": 410,
+    "y": 110,
+    "width": 64,
+    "height": 64,
+    "catalogId": "task/task-done"
+  },
+  {
+    "id": "annotation",
+    "type": "path",
+    "x": 100,
+    "y": 230,
+    "width": 250,
+    "height": 30,
+    "path": {
+      "data": "M0,18 Q60,2 125,16 Q190,30 250,10",
+      "intrinsicWidth": 250,
+      "intrinsicHeight": 30
+    },
+    "style": {
+      "fill": {"type": "none"},
+      "stroke": {
+        "paint": {"type": "solid", "color": "#2563EB"},
+        "width": 6,
+        "lineCap": "round",
+        "lineJoin": "round"
+      }
+    }
+  }
+]
+```
+
+## Frame 与子节点
+
+Frame 页面直属，子节点坐标相对其左上角；connector 不放入 Frame，跨区域连接线
+保持页面直属：
+
+```json
+[
+  {
+    "id": "stage",
+    "type": "frame",
+    "x": 60,
+    "y": 320,
+    "width": 720,
+    "height": 300,
+    "title": {
+      "text": {
+        "blocks": [{
+          "type": "paragraph",
+          "runs": [{"text": "流程阶段", "marks": {"bold": true}}]
+        }]
+      }
+    }
+  },
+  {
+    "id": "stage-item",
+    "type": "shape",
+    "parentId": "stage",
+    "x": 60,
+    "y": 80,
+    "width": 180,
+    "height": 72,
+    "geometry": "dml:rect"
+  }
+]
+```
+
+`presentationOrder` 须唯一且非负；未知字段、跨请求引用或不支持值会拒绝整批。

package/skills/dws/dingtalk-misc/references/whiteboard/open-nodes-v1/01-overview.md

@@ -0,0 +1,57 @@
+# DWS OpenNodes V1 协议说明
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+> 协议版本：`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 局部修改的能力。

package/skills/dws/dingtalk-misc/references/whiteboard/open-nodes-v1/02-query.md

@@ -0,0 +1,288 @@
+# OpenNodes V1 — Query 请求、返回结构和节点公共字段
+
+> 本文件是 DWS OpenNodes V1 协议的拆分章节。按需读取入口见
+> [协议索引](../open-nodes-v1.md)。
+
+## 4. Query 协议
+
+### 4.1 请求
+
+```bash
+dws whiteboard query \
+  --node <DOC_NODE_ID> \
+  --part-id <WHITEBOARD_PART_ID> \
+  --format json
+```
+
+`query` 不接收请求体或 `pageId`。`--node` 和 `--part-id` 的发现规则见
+[白板命令参考](../../whiteboard.md)。CLI 会把服务返回的 `resultJson` JSON
+字符串解析成对象。
+
+### 4.2 返回结构
+
+```ts
+interface OpenNodesDocument {
+  schemaVersion: "1.0";
+  catalogVersion: "dml-v1";
+  pages: OpenPage[];
+}
+
+interface OpenPage {
+  id: string;
+  nodes: OpenNode[];
+}
+```
+
+DWS 当前只支持单页白板，因此 `pages` 固定包含一个页面。调用方仍应从返回值读取
+页面 `id`，但不能把它作为 `pageId` 传给 DWS 命令。
+
+母版节点不会作为独立页面返回，而会合并到引用它的页面 `nodes` 中，并带有：
+
+```json
+{
+  "source": "master",
+  "writeSupport": "readOnly",
+  "unsupportedFeatures": ["node.source.master"]
+}
+```
+
+### 4.3 节点公共字段
+
+`type` 的完整公开枚举如下。前一组可由 update 创建，后一组仅供 query 返回：
+
+```ts
+type WritableOpenNodeType =
+  | "shape"
+  | "text"
+  | "connector"
+  | "stickyNote"
+  | "frame"
+  | "group"
+  | "vector"
+  | "icon"
+  | "path";
+
+type ReadOnlyOpenNodeType =
+  | "image"
+  | "pdf"
+  | "media"
+  | "webLink"
+  | "table"
+  | "chart"
+  | "uml"
+  | "swimlane"
+  | "mind"
+  | "timer"
+  | "placeholder"
+  | "unknown";
+
+type OpenNodeType = WritableOpenNodeType | ReadOnlyOpenNodeType;
+```
+
+每个 query 节点都包含以下公共字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `string` | 白板中真实、稳定的节点 ID。 |
+| `type` | `OpenNodeType` | OpenNodes 公开语义类型，取值见上方枚举。 |
+| `parentId` | `string?` | group/frame 父节点 ID。无父节点时省略。 |
+| `children` | `string[]?` | group/frame 的直接子节点 ID，由服务端推导。 |
+| `x`、`y` | `number` | 有父节点时相对父节点；否则相对页面。单位为 px。 |
+| `width`、`height` | `number` | 节点包围盒尺寸，单位为 px。连接线允许其中一个为 `0`。 |
+| `angle` | `number` | 归一化到 `[0, 360)` 的角度。 |
+| `absoluteBounds` | `OpenBounds` | 页面坐标系中的绝对包围盒。 |
+| `layer` | `background \| normal \| foreground` | 节点所在层。 |
+| `zIndex` | `number` | 同一父节点、同一 layer 内的非负顺序，值越小越靠后。 |
+| `hidden` | `boolean` | 节点是否隐藏。 |
+| `locked` | `boolean` | 节点是否锁定。 |
+| `source` | `page \| master` | 节点来自当前页面还是母版。 |
+| `writeSupport` | `readWrite \| readOnly` | 当前节点能否由 V1 update 表达。 |
+| `unsupportedFeatures` | `string[]?` | 只读原因；`readWrite` 节点省略。 |
+
+公共结构和各节点分支定义如下；分支中的字段含义与写入限制见第 7 节：
+
+```ts
+interface OpenPoint {
+  x: number;
+  y: number;
+}
+
+interface OpenBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  angle: number;
+}
+
+interface OpenNodeBase {
+  id: string;
+  type: OpenNodeType;
+  parentId?: string;
+  children?: string[];
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  angle: number;
+  absoluteBounds: OpenBounds;
+  layer: "background" | "normal" | "foreground";
+  zIndex: number;
+  hidden: boolean;
+  locked: boolean;
+  source: "page" | "master";
+  writeSupport: "readWrite" | "readOnly";
+  unsupportedFeatures?: string[];
+}
+
+interface OpenShapeNode extends OpenNodeBase {
+  type: "shape";
+  geometry: `dml:${string}`;
+  adjustments?: Record<string, number>;
+  text?: OpenText;
+  style?: OpenNodeStyle;
+}
+
+interface OpenTextNode extends OpenNodeBase {
+  type: "text";
+  text: OpenText;
+  style?: OpenNodeStyle;
+}
+
+interface OpenConnectorNode extends OpenNodeBase {
+  type: "connector";
+  start: OpenConnectorEndpoint;
+  end: OpenConnectorEndpoint;
+  routing: OpenConnectorRouting;
+  waypoints?: OpenPoint[];
+  style?: OpenNodeStyle;
+  resolvedPath: OpenResolvedConnectorPath;
+}
+
+interface OpenStickyNoteNode extends OpenNodeBase {
+  type: "stickyNote";
+  text?: OpenText;
+  style?: OpenNodeStyle;
+  creator?: {
+    displayName?: string;
+    hasAvatar?: boolean;
+  };
+  tags?: Array<{
+    id: string;
+    text: string;
+    background: OpenPaint;
+  }>;
+}
+
+interface OpenFrameNode extends OpenNodeBase {
+  type: "frame";
+  title?: {
+    text: OpenText;
+    box: { width: number; height: number };
+  };
+  style?: OpenNodeStyle;
+  presentationOrder?: number;
+  resizeMode: "free" | "fixedAspectRatio";
+}
+
+interface OpenGroupNode extends OpenNodeBase {
+  type: "group";
+  children: string[];
+}
+
+interface OpenVectorNode extends OpenNodeBase {
+  type: "vector";
+  resource: OpenVectorResource;
+}
+
+interface OpenIconNode extends OpenNodeBase {
+  type: "icon";
+  catalogId: string;
+}
+
+interface OpenPathNode extends OpenNodeBase {
+  type: "path";
+  path: OpenPathData;
+  style?: OpenNodeStyle;
+}
+
+interface OpenReadOnlyNode extends OpenNodeBase {
+  type: ReadOnlyOpenNodeType;
+  writeSupport: "readOnly";
+  unsupportedFeatures: string[];
+}
+
+type OpenNode =
+  | OpenShapeNode
+  | OpenTextNode
+  | OpenConnectorNode
+  | OpenStickyNoteNode
+  | OpenFrameNode
+  | OpenGroupNode
+  | OpenVectorNode
+  | OpenIconNode
+  | OpenPathNode
+  | OpenReadOnlyNode;
+```
+
+query 中 `icon.catalogId` 使用 `string`，是为了让无法映射到当前目录的既有图标仍可
+被诊断；update 只能传入 7.10 节 `OpenIconCatalogId` 中列出的值。
+
+### 4.4 Query 示例
+
+```json
+{
+  "schemaVersion": "1.0",
+  "catalogVersion": "dml-v1",
+  "pages": [
+    {
+      "id": "page",
+      "nodes": [
+        {
+          "id": "real-node-id",
+          "type": "text",
+          "x": 120,
+          "y": 80,
+          "width": 240,
+          "height": 48,
+          "angle": 0,
+          "absoluteBounds": {
+            "x": 120,
+            "y": 80,
+            "width": 240,
+            "height": 48,
+            "angle": 0
+          },
+          "layer": "normal",
+          "zIndex": 0,
+          "hidden": false,
+          "locked": false,
+          "source": "page",
+          "writeSupport": "readWrite",
+          "text": {
+            "blocks": [
+              {
+                "type": "paragraph",
+                "horizontalAlign": "left",
+                "runs": [
+                  {
+                    "text": "Hello OpenNodes",
+                    "marks": {
+                      "fontSize": 16,
+                      "color": "#223344"
+                    }
+                  }
+                ]
+              }
+            ],
+            "verticalAlign": "center",
+            "padding": [2, 4],
+            "plainText": "Hello OpenNodes",
+            "writeSupport": "readWrite"
+          }
+        }
+      ]
+    }
+  ]
+}
+```