EP-Hub-Skill/.agents/skills/dingtalk-misc/references/whiteboard/open-nodes-v1/02-query.md

# 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"
          }
        }
      ]
    }
  ]
}
```