@civilization/dsh-drawio 0.3.0 → 0.4.1

package/README.md

@@ -14,13 +14,12 @@
 
 ## Agent 工具与 Skill
 
-- `drawio-operation` Skill：向模型注入 Draw.io 画板整体架构、离线导出机制与最佳绘图工作流。
-- `drawio_inspect`：把画板读取为页面、节点、连线和几何信息。
-- `drawio_edit`：批量新增、更新、删除节点和连线。
+- `drawio-operation` Skill：向模型注入 Draw.io 画板整体架构、工业级排版规范、现代配色方案、离线导出机制与最佳绘图工作流。
+- `drawio_inspect`：把画板读取为页面、节点、连线和几何信息，自动提取去除 HTML 的纯文本标题与容器子节点列表。
+- `drawio_edit`：批量新增、更新、删除节点与连线，支持 `add_page`、`rename_page`、`delete_page` 多页面管理，以及 `stylePatch` 局部增量更新样式。
 - `drawio_write`：校验并写入完整的 Draw.io XML。
 
-工具统一保存为未压缩 XML，便于 Agent 继续修改，也便于 Git 查看差异。画板会
-自动保存，并轮询同步 Agent 对同一文件的修改。
+工具统一保存为未压缩 XML，便于 Agent 继续修改，也便于 Git 查看差异。画板具备真乐观并发控制（防静默覆盖冲突），并采用轻量版本感知机制自动同步 Agent 对同一文件的修改。
 
 ## 本地离线图片导出 (Export)
 
@@ -50,6 +49,35 @@ dsh web --port 3082 --no-open
 `.drawio` 文件时，由官方资源路由选择本插件的画板；读取和自动保存通过插件自有的
 `/dsh-drawio/api` 接口完成，并限制在当前会话工作区内。
 
+## 💡 DSH Tab 认领机制与模式声明（避坑指南）
+
+本插件向 DSH 官方 `sidebarRightTabs` 注册画板 Tab 类型时，声明了双重匹配模式：
+
+```typescript
+patterns: ['dsh-resource://file/**/*.drawio', '*.drawio']
+```
+
+### 为什么必须包含整地址模式？
+
+DSH 的 `sidebarRightTabs` 在判定「由谁打开此文件」时，采用如下候选排序规则（详见官方 `tab-registry.ts` 的 `candidates()`）：
+
+1. **优先级分档（Priority Band）**：如 `builtin`、`extension` 等；
+2. **命中模式长度（Matched Pattern Length）**：同档位下，**匹配命中的模式字符数更长者胜**；
+3. **注册顺序（Registration Order）**。
+
+#### 潜在冲突场景
+若插件仅声明裸扩展名 `*.drawio`（8 字符），一旦用户安装了带有“接管所有文件”的通用编辑器插件（例如某些侧边栏/文件编辑插件声明了 `dsh-resource://file/**`，长 22 字符）：
+- 二者同属 `extension` 优先级；
+- 长度比对：`22 > 8`，通用文件编辑器**按字符长度胜出并强行接管**；
+- 结果：用户在文件树点击 `.drawio`，打开的是别人的纯文本编辑器并展示 XML 源码，本插件画板排第二永不渲染（即便 `*.drawio` 在语义上更精确）。
+
+#### 最佳实践解法
+- **`dsh-resource://file/**/*.drawio`**（31 字符）：含冒号的分隔符模式执行整地址匹配（如 `dsh-resource://file/session/<sid>/out/arch.drawio`），以 31 > 22 字符在同档位中反超通用编辑器，稳稳赢得 `.drawio` 文件的专属画板渲染权；
+- **`*.drawio`**：不带分隔符的模式按 URI basename 匹配，继续兼容覆盖非 `dsh-resource://` 开头的任意形态地址。
+
+> [!TIP]
+> 此规则对所有**“按特定扩展名注册定制编辑器 / 视图 Tab”**的 DSH 插件均成立。编写特定扩展名 Tab 时，务必补全 `dsh-resource://file/**/*.ext` 整地址模式，防止被通用文件接管插件按模式长度压制。
+
 已在 DSH 0.1.5-rc.2 上验证构建、XML 操作、本地静态资源加载和官方右侧栏注册。
 
 当前内置的精简 Draw.io runtime 固定为 31.4.5。包含完整满血版内置图库（通用、流程图、UML、ER、BPMN、网络、Kubernetes、AWS、GCP、Cisco、电子、平面图等全部分类均可自由开启）以及 PlantUML 离线渲染模块；

package/lib/client.js

@@ -37,7 +37,14 @@ function apply(ctx) {
   ctx.effect(() => official.sidebarRightTabs.register({
     id: TAB_ID,
     kind: TAB_KIND,
-    patterns: ["*.drawio"],
+    // The whole-address glob is what actually wins this file: tab types are
+    // ranked by priority band, then by the length of the matched pattern, so a
+    // bare `*.drawio` (8 characters) loses the claim to any type declaring a
+    // broader address glob in the same `extension` band — e.g.
+    // dsh-better-sidebar's file editor (`dsh-resource://file/**`, 22), which
+    // then renders the XML instead of this canvas. Keeping both patterns makes
+    // the specific one win wherever it matches.
+    patterns: ["dsh-resource://file/**/*.drawio", "*.drawio"],
     priority: "extension",
     title: (address) => fileName(parseDrawioAddress(address)?.path ?? "Draw.io")
   }), "dsh-drawio: official tab definition");
@@ -73,8 +80,8 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }) {
     if (!resource?.path || !effectiveSessionId || !cwd) return;
     const controller = new AbortController();
     setError(null);
-    void fsRead({ sessionId: effectiveSessionId, cwd }, resource.path, controller.signal).then((content) => {
-      if (!controller.signal.aborted) setFile({ key, content });
+    void fsRead({ sessionId: effectiveSessionId, cwd }, resource.path, controller.signal).then((res) => {
+      if (!controller.signal.aborted) setFile({ key, content: res.content, version: res.version });
     }).catch((reason) => {
       if (!controller.signal.aborted) setError(messageOf(reason));
     });
@@ -100,12 +107,13 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }) {
   }
   if (error) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CenteredMessage, { title: "\u753B\u677F\u8F7D\u5165\u5931\u8D25", detail: error });
   if (file?.key !== key) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CenteredMessage, { title: "\u6B63\u5728\u8F7D\u5165\u753B\u677F", detail: fileName(resource.path) });
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DrawioCanvas, { content: file.content, path: resource.path, scope: { sessionId: effectiveSessionId, cwd } });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DrawioCanvas, { content: file.content, version: file.version, path: resource.path, scope: { sessionId: effectiveSessionId, cwd } });
 }
-function DrawioCanvas({ content, truncated, path, scope }) {
+function DrawioCanvas({ content, version, truncated, path, scope }) {
   const frame = (0, import_react.useRef)(null);
   const latestFile = (0, import_react.useRef)(content ?? "");
   const latestEditor = (0, import_react.useRef)(content ?? "");
+  const latestVersion = (0, import_react.useRef)(version);
   const saveTimer = (0, import_react.useRef)(void 0);
   const saveGeneration = (0, import_react.useRef)(0);
   const [ready, setReady] = (0, import_react.useState)(false);
@@ -114,24 +122,46 @@ function DrawioCanvas({ content, truncated, path, scope }) {
   const lastUserActivity = (0, import_react.useRef)(0);
   const isInteracting = (0, import_react.useRef)(false);
   const { dark, accent: accentColor } = useDshTheme();
-  const src = (0, import_react.useMemo)(() => `/dsh-drawio/runtime/index.html?embed=1&proto=json&spin=1&offline=1&local=1&ui=min&libraries=1&configure=1&noExitBtn=1&saveAndExit=0&dark=${dark ? "1" : "0"}`, [dark]);
+  const initialDark = (0, import_react.useRef)(dark);
+  const src = (0, import_react.useMemo)(() => `/dsh-drawio/runtime/index.html?embed=1&proto=json&spin=1&offline=1&local=1&ui=min&libraries=1&configure=1&noExitBtn=1&saveAndExit=0&dark=${initialDark.current ? "1" : "0"}`, []);
   const post = (0, import_react.useCallback)((message) => {
     frame.current?.contentWindow?.postMessage(JSON.stringify(message), window.location.origin);
   }, []);
+  const reloadFromDisk = (0, import_react.useCallback)(async () => {
+    try {
+      setSaveState("loading");
+      const result = await fsRead(scope, path);
+      latestFile.current = result.content;
+      latestEditor.current = result.content;
+      latestVersion.current = result.version;
+      post({ action: "load", xml: result.content, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 });
+      setSaveState("saved");
+      setError(null);
+    } catch (reason) {
+      setError(messageOf(reason));
+    }
+  }, [scope, path, dark, post]);
   const persist = (0, import_react.useCallback)(async (xml) => {
     const generation = ++saveGeneration.current;
     setSaveState("saving");
     try {
-      await fsWrite(scope, path, xml);
+      const outcome = await fsWrite(scope, path, xml, latestVersion.current);
       if (generation !== saveGeneration.current) return;
       latestFile.current = xml;
       latestEditor.current = xml;
+      if (outcome?.version) latestVersion.current = outcome.version;
       setSaveState("saved");
       setError(null);
     } catch (reason) {
       if (generation !== saveGeneration.current) return;
-      setSaveState("error");
-      setError(messageOf(reason));
+      const msg = messageOf(reason);
+      if (msg.includes("modified by an external process") || msg.includes("409")) {
+        setSaveState("conflict");
+        setError("\u6587\u4EF6\u5DF2\u88AB\u5916\u90E8\u6216 AI \u4FEE\u6539\uFF0C\u5F53\u524D\u5B58\u5728\u5E76\u53D1\u51B2\u7A81\uFF0C\u70B9\u51FB\u53EF\u91CD\u65B0\u8F7D\u5165\u6700\u65B0\u5185\u5BB9");
+      } else {
+        setSaveState("error");
+        setError(msg);
+      }
     }
   }, [scope.sessionId, scope.cwd, path]);
   const scheduleSave = (0, import_react.useCallback)((xml, immediate = false) => {
@@ -153,7 +183,8 @@ function DrawioCanvas({ content, truncated, path, scope }) {
   (0, import_react.useEffect)(() => {
     latestFile.current = content ?? "";
     latestEditor.current = content ?? "";
-  }, [content, path]);
+    latestVersion.current = version;
+  }, [content, version, path]);
   const markActivity = (0, import_react.useCallback)(() => {
     lastUserActivity.current = Date.now();
   }, []);
@@ -227,15 +258,25 @@ function DrawioCanvas({ content, truncated, path, scope }) {
         document.body.removeChild(link);
         showToast(`\u5DF2\u5F00\u59CB\u4E0B\u8F7D\uFF1A${fileName(pending.targetPath)}`);
       } else if (pending.target === "clipboard") {
-        if (pending.format === "svg") {
-          const svgText = data.startsWith("data:image/svg+xml") ? decodeURIComponent(data.split(",")[1] || "") : data;
-          await navigator.clipboard.writeText(svgText);
-          showToast("\u5DF2\u590D\u5236 SVG \u4EE3\u7801\u5230\u526A\u8D34\u677F");
-        } else {
-          const res = await fetch(data);
-          const blob = await res.blob();
-          await navigator.clipboard.write([new ClipboardItem({ "image/png": blob })]);
-          showToast("\u5DF2\u590D\u5236\u56FE\u7247\u5230\u526A\u8D34\u677F");
+        try {
+          if (pending.format === "svg") {
+            const svgText = data.startsWith("data:image/svg+xml") ? decodeURIComponent(data.split(",")[1] || "") : data;
+            await navigator.clipboard.writeText(svgText);
+            showToast("\u5DF2\u590D\u5236 SVG \u4EE3\u7801\u5230\u526A\u8D34\u677F");
+          } else {
+            const res = await fetch(data);
+            const blob = await res.blob();
+            await navigator.clipboard.write([new ClipboardItem({ "image/png": blob })]);
+            showToast("\u5DF2\u590D\u5236\u56FE\u7247\u5230\u526A\u8D34\u677F");
+          }
+        } catch {
+          const link = document.createElement("a");
+          link.download = fileName(pending.targetPath);
+          link.href = data;
+          document.body.appendChild(link);
+          link.click();
+          document.body.removeChild(link);
+          showToast(`\u526A\u8D34\u677F\u65E0\u6743\u9650\uFF0C\u5DF2\u81EA\u52A8\u4E0B\u8F7D\uFF1A${fileName(pending.targetPath)}`);
         }
       } else if (pending.target === "workspace") {
         const result = await fsSaveImage(scope, pending.targetPath, data);
@@ -294,12 +335,19 @@ function DrawioCanvas({ content, truncated, path, scope }) {
       if (saveTimer.current !== void 0) return;
       if (typeof document !== "undefined" && document.hidden) return;
       try {
-        const xml = await fsRead(scope, path);
+        const stat = await fsStat(scope, path);
         if (cancelled || isInteracting.current || Date.now() - lastUserActivity.current < 1200) return;
-        if (xml === latestFile.current || xml === latestEditor.current) return;
-        latestFile.current = xml;
-        latestEditor.current = xml;
-        post({ action: "load", xml, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 });
+        if (stat.version && latestVersion.current && stat.version === latestVersion.current) return;
+        const res = await fsRead(scope, path);
+        if (cancelled || isInteracting.current || Date.now() - lastUserActivity.current < 1200) return;
+        if (res.content === latestFile.current || res.content === latestEditor.current) {
+          latestVersion.current = res.version;
+          return;
+        }
+        latestFile.current = res.content;
+        latestEditor.current = res.content;
+        latestVersion.current = res.version;
+        post({ action: "load", xml: res.content, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 });
         setSaveState("external");
         window.setTimeout(() => {
           if (!cancelled) setSaveState("saved");
@@ -318,7 +366,7 @@ function DrawioCanvas({ content, truncated, path, scope }) {
   }, [ready, truncated, scope.sessionId, scope.cwd, path, dark, post]);
   (0, import_react.useEffect)(() => () => {
     if (saveTimer.current !== void 0) window.clearTimeout(saveTimer.current);
-    if (latestEditor.current !== latestFile.current) void fsWrite(scope, path, latestEditor.current, true);
+    if (latestEditor.current !== latestFile.current) void fsWrite(scope, path, latestEditor.current, latestVersion.current, true);
   }, [scope.sessionId, scope.cwd, path]);
   if (truncated) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CenteredMessage, { title: "\u65E0\u6CD5\u6253\u5F00\u753B\u677F", detail: "\u6587\u4EF6\u5185\u5BB9\u5DF2\u88AB\u622A\u65AD\uFF0C\u7EE7\u7EED\u7F16\u8F91\u53EF\u80FD\u635F\u574F\u539F\u6587\u4EF6\u3002" });
   const targetExt = exportFormat === "svg" ? ".svg" : exportFormat === "xmlpng" ? ".drawio.png" : ".png";
@@ -419,11 +467,23 @@ function DrawioCanvas({ content, truncated, path, scope }) {
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CheckIcon, { size: 14 }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: toast })
     ] }) : null,
-    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { role: "status", "aria-live": "polite", style: { ...styles.status, ...saveState === "error" ? styles.statusError : {} }, children: [
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: { ...styles.dot, background: accentColor } }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { role: "status", "aria-live": "polite", style: { ...styles.status, ...saveState === "error" || saveState === "conflict" ? styles.statusError : {} }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: { ...styles.dot, background: saveState === "conflict" ? "var(--dsw-alias-warning, #e6a23c)" : accentColor } }),
       statusText(saveState)
     ] }),
-    error ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", title: error, onClick: () => setError(null), style: styles.error, children: "\u4FDD\u5B58\u5931\u8D25 \xB7 \u70B9\u51FB\u5173\u95ED" }) : null
+    error ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        title: error,
+        onClick: () => {
+          if (saveState === "conflict") void reloadFromDisk();
+          setError(null);
+        },
+        style: styles.error,
+        children: saveState === "conflict" ? "\u26A0\uFE0F \u68C0\u6D4B\u5230\u5916\u90E8\u4FEE\u6539 \xB7 \u70B9\u51FB\u91CD\u65B0\u8F7D\u5165" : "\u4FDD\u5B58\u5931\u8D25 \xB7 \u70B9\u51FB\u5173\u95ED"
+      }
+    ) : null
   ] });
 }
 function useDshTheme() {
@@ -464,12 +524,14 @@ function detectDark() {
   if (numbers?.length === 3) return numbers[0] * 0.299 + numbers[1] * 0.587 + numbers[2] * 0.114 < 128;
   return document.documentElement.classList.contains("dark") || window.matchMedia("(prefers-color-scheme: dark)").matches;
 }
+async function fsStat(scope, path, signal) {
+  return call("stat", scope, { path }, false, signal);
+}
 async function fsRead(scope, path, signal) {
-  const value = await call("read", scope, { path }, false, signal);
-  return value.content;
+  return call("read", scope, { path }, false, signal);
 }
-async function fsWrite(scope, path, content, keepalive = false) {
-  await call("write", scope, { path, content }, keepalive);
+async function fsWrite(scope, path, content, version, keepalive = false) {
+  return call("write", scope, { path, content, ...version ? { version } : {} }, keepalive);
 }
 async function fsSaveImage(scope, path, data) {
   return call("save-image", scope, { path, data });
@@ -559,7 +621,7 @@ function parseDrawioAddress(address, fallbackSessionId) {
   }
 }
 var messageOf = (reason) => reason instanceof Error ? reason.message : String(reason);
-var statusText = (state) => state === "loading" ? "\u6B63\u5728\u8F7D\u5165" : state === "saving" ? "\u6B63\u5728\u4FDD\u5B58" : state === "external" ? "\u5DF2\u540C\u6B65 AI \u4FEE\u6539" : state === "error" ? "\u4FDD\u5B58\u5931\u8D25" : "\u5DF2\u4FDD\u5B58";
+var statusText = (state) => state === "loading" ? "\u6B63\u5728\u8F7D\u5165" : state === "saving" ? "\u6B63\u5728\u4FDD\u5B58" : state === "external" ? "\u5DF2\u540C\u6B65 AI \u4FEE\u6539" : state === "conflict" ? "\u68C0\u6D4B\u5230\u51B2\u7A81" : state === "error" ? "\u4FDD\u5B58\u5931\u8D25" : "\u5DF2\u4FDD\u5B58";
 var fg = "var(--dsw-alias-label-primary, currentColor)";
 var muted = "var(--dsw-alias-label-secondary, rgba(127,127,127,.9))";
 var layer = "var(--dsw-alias-container-bg, Canvas)";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civilization/dsh-drawio",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Local draw.io canvas and model tools for DeepSeek Harness",
   "license": "Apache-2.0",
   "type": "module",

package/skills/drawio-operation/SKILL.md

@@ -1,53 +1,80 @@
 ---
 name: drawio-operation
-description: Read, inspect, create, and semantically edit Draw.io diagrams and architecture flows, collaborate with the native offline canvas, and guide export workflows.
+description: 读取、检查、创建和语义化编辑 Draw.io 架构图与流程图，协同原生离线画板，并指导导出与排版工作流。
 ---
 
-# Draw.io operation
-
-The `dsh-drawio` plugin integrates a 100% local, offline Draw.io diagram editor into DeepSeek Harness (DSH) right sidebar and equips the model with structured diagram editing tools.
-
-When the user asks about Draw.io capabilities or diagram tools, describe the available tools and features directly without scanning or probing the workspace.
-
-## Core Model Tools
-
-1. **`drawio_inspect`**:
-   - Reads an existing `.drawio` file into structured pages, nodes, edges, labels, and geometry bounds.
-   - Always call this before modifying an existing diagram to understand existing cell IDs, hierarchy, and connection points.
-   - Set `include_xml: true` only when raw XML attributes or specific unparsed mxCell metadata are needed.
-
-2. **`drawio_edit`**:
-   - Applies targeted semantic operations to an existing `.drawio` file.
-   - Supported batch operations:
-     - `add_node`: Add a new vertex with `id`, `label`, `style`, `x`, `y`, `width`, `height`.
-     - `add_edge`: Connect vertices with `id`, `source`, `target`, `label`, and routing `style`.
-     - `update`: Modify existing node or edge properties without disturbing unchanged geometry.
-     - `delete`: Safely remove a cell and automatically cascade clean-up of connected edges.
-   - Maintain stable, unique, descriptive cell IDs (e.g. `client`, `api_gateway`, `db_cluster`).
-
-3. **`drawio_write`**:
-   - Validates and writes a complete Draw.io `mxfile` or `mxGraphModel` XML document.
-   - Automatically normalizes the XML to uncompressed, human-readable format for reliable Git diffs and future AI edits.
-   - Prefer `drawio_write` when creating a brand-new diagram from scratch, and prefer `drawio_edit` for incremental revisions.
-
-## Canvas & Offline Export Capabilities
-
-- **Interactive Right-Sidebar Canvas**:
-  - Double-clicking any `.drawio` file in the DSH workspace opens the full-featured Draw.io canvas.
-  - Changes made by the model via `drawio_edit` or `drawio_write` are polled and synchronized into the canvas automatically without overwriting active user dragging.
-- **Pure Local Image Export**:
-  - The canvas includes a built-in offline export engine in the top-right toolbar:
-    - **PNG (2x Ultra HD)**: High-resolution rasterization with optional transparent background.
-    - **SVG (Vector)**: Infinite resolution vector diagram.
-    - **XML-PNG**: Dual-mode image embedding editable diagram XML metadata.
-  - Supports saving directly back into the current workspace (e.g. `architecture.png`), copying directly to the system clipboard, or downloading to local disk.
-
-## Recommended Workflows
-
-- **Creating a new diagram**:
-  - Propose clear architecture/flowchart structure.
-  - Call `drawio_write` with a clean `mxfile` XML document at a workspace path ending in `.drawio`.
-  - Inform the user that the diagram is immediately viewable and editable in the right sidebar tab and can be exported to PNG/SVG from the canvas toolbar.
-- **Updating an existing diagram**:
-  - Call `drawio_inspect` first.
-  - Formulate precise `operations` and call `drawio_edit`.
+# Draw.io 画板与图表协同指南
+
+`dsh-drawio` 插件为 DeepSeek Harness (DSH) 提供 100% 本地离线的 Draw.io 画板，并向 Agent 注册结构化图表编辑工具。
+
+当用户询问 Draw.io 功能或需要绘制图表时，直接说明支持的画板功能与工具，无需探测工作区无关文件。
+
+## 核心模型工具
+
+### 1. `drawio_inspect`
+- **功能**：将现有 `.drawio` 文件解析为结构化的页面、节点、连线、文本内容及几何坐标。
+- **最佳实践**：修改已有图表前必须先调用 `drawio_inspect`，获取已有 cell ID、父子层级关系及连线端点。
+- **字段**：返回的 `plainText` 是已去除 HTML 格式的纯净标签；`children` 标识该容器节点包含的子节点 ID。
+- 仅在需要查看原始底层 XML 属性时设置 `include_xml: true`。
+
+### 2. `drawio_edit`
+- **功能**：对现有 `.drawio` 文件应用批量语义化增量修改，支持多页面管理。
+- **支持的批量操作类型**：
+  - `add_node`：新增节点。属性：`id`, `label`, `style`, `parent`, `x`, `y`, `width`, `height`。
+  - `add_edge`：新增连线。属性：`id`, `source`, `target`, `label`, `style`, `parent`。
+  - `update`：更新已有节点或连线属性。
+    - 推荐使用 `stylePatch: { fillColor: '#dae8fc', strokeColor: '#6c8ebf' }` 局部增量修改颜色或边框，避免冲掉节点的已有样式（如圆角、对齐等）。
+    - 也支持整体更新 `label`, `style`, `x`, `y`, `width`, `height`。
+  - `delete`：安全删除节点，并自动级联清理连接到该节点的孤立连线。
+  - `add_page`：在当前文档中新增图表页面。属性：`id`, `name`（如 `部署拓扑`、`时序交互`）。
+  - `rename_page`：重命名页面。属性：`page` (索引或ID), `name`。
+  - `delete_page`：删除指定页面。属性：`page`。
+- **规范**：节点 ID 应具备稳定且语义化的英文标识（例如 `client`, `api_gateway`, `auth_service`, `db_cluster`），严禁使用易冲突的纯数字 ID。
+
+### 3. `drawio_write`
+- **功能**：校验并写入完整的 Draw.io `mxfile` 或 `mxGraphModel` XML 文档。
+- 自动格式化为未压缩的规范 XML，便于后续 AI 审查与 Git diff 跟踪。
+- **建议**：从零构建新图表时首选 `drawio_write`；对现有图表进行局部修改或扩展时首选 `drawio_edit`。
+
+---
+
+## 架构图排版与设计规范
+
+为了保证大模型生成的图表整洁、专业、无重叠，请遵循以下工业级排版规范：
+
+### 1. 坐标与网格系统
+- **基准网格**：Draw.io 默认 `gridSize=10`，所有坐标 `x`, `y`, `width`, `height` 请取 10 的整数倍。
+- **标准节点尺寸**：
+  - 常规服务/模块：`width: 140, height: 60`
+  - 数据库/存储：`width: 120, height: 70`
+  - 外部系统/客户端：`width: 130, height: 50`
+  - 分组容器（Group/VPC）：根据内部节点数量自适应（如 `width: 600, height: 320`）
+- **间距推荐**：
+  - 横向流式布局：节点水平间距保持在 `80px ~ 120px`（如 `x1=40, x2=240, x3=440`）；
+  - 纵向分层架构：分层垂直间距保持在 `90px ~ 130px`（如 Layer 1: `y=40`，Layer 2: `y=160`，Layer 3: `y=280`）。
+
+### 2. 经典高质感现代配色方案（Flat Palette）
+
+| 分类/层级 | 填充色 `fillColor` | 边框色 `strokeColor` | 字体色 `fontColor` | 推荐使用场景 |
+| :--- | :--- | :--- | :--- | :--- |
+| **接入/网关** | `#dae8fc` (浅蓝) | `#6c8ebf` (深蓝) | `#000000` | Client, Nginx, API Gateway, CDN |
+| **业务服务** | `#d5e8d4` (浅绿) | `#82b366` (深绿) | `#000000` | OrderService, UserService, K8s Pods |
+| **存储/数据库** | `#ffe6cc` (暖橙) | `#d79b00` (深橙) | `#000000` | MySQL, Redis, MongoDB, S3 |
+| **异步队列/通信** | `#e1d5e7` (浅紫) | `#9673a6` (深紫) | `#000000` | Kafka, RabbitMQ, EventBus |
+| **告警/高风险** | `#f8cecc` (浅红) | `#b85450` (深红) | `#000000` | ErrorHandler, DeadLetter, Alert |
+| **容器/分组边框** | `#f5f5f5` (极浅灰) | `#cccccc` (浅灰) | `#333333` | VPC, Kubernetes Cluster, Subnet |
+
+### 3. 连线样式（Edge Styles）
+- 统一使用正交折线：`edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;`
+- 若要强调特定流向，可增加线宽 `strokeWidth=2;`，异步/订阅连线推荐增加虚线 `dashed=1;`。
+
+---
+
+## 离线画板协同与图片导出
+
+- **右侧栏实时双向协同**：
+  - 用户在 DSH 中打开任何 `.drawio` 文件即可在右侧栏全功能画板中直观交互；
+  - 模型调用 `drawio_edit` 或 `drawio_write` 保存后，画板会自动轻量检测版本变化并同步刷新，且不会中断用户正在进行的画布拖拽。
+- **纯本地离线图片导出**：
+  - 画板右上角内置纯本地导出面板，支持导出为 **PNG (2x 超清)**、**SVG (矢量无损)** 和 **XML-PNG (双模可编辑图)**；
+  - 支持一键**保存到工作区**（自动生成同名图片）、**写入系统剪贴板**（便于直接粘贴到文档或聊天窗口）或**下载到本地磁盘**。

package/src/client/index.tsx

@@ -6,7 +6,7 @@ const TAB_ID = '@civilization/dsh-drawio'
 const TAB_KIND = 'drawio'
 
 interface SessionScope { sessionId: string; cwd?: string }
-interface FileViewerProps { content?: string; truncated?: boolean; path: string; scope: SessionScope }
+interface FileViewerProps { content?: string; version?: string; truncated?: boolean; path: string; scope: SessionScope }
 interface OfficialContext extends Context { slots: any; sidebarRightTabs: any }
 
 export function apply(ctx: Context): void {
@@ -14,7 +14,14 @@ export function apply(ctx: Context): void {
   ctx.effect(() => official.sidebarRightTabs.register({
     id: TAB_ID,
     kind: TAB_KIND,
-    patterns: ['*.drawio'],
+    // The whole-address glob is what actually wins this file: tab types are
+    // ranked by priority band, then by the length of the matched pattern, so a
+    // bare `*.drawio` (8 characters) loses the claim to any type declaring a
+    // broader address glob in the same `extension` band — e.g.
+    // dsh-better-sidebar's file editor (`dsh-resource://file/**`, 22), which
+    // then renders the XML instead of this canvas. Keeping both patterns makes
+    // the specific one win wherever it matches.
+    patterns: ['dsh-resource://file/**/*.drawio', '*.drawio'],
     priority: 'extension',
     title: (address: string) => fileName(parseDrawioAddress(address)?.path ?? 'Draw.io'),
   }), 'dsh-drawio: official tab definition')
@@ -44,7 +51,7 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }: any): JSX
   const cwd = activeCwd || resourceCwd
   const effectiveSessionId = sessionId || resource?.sessionId || ''
 
-  const [file, setFile] = useState<{ key: string; content: string } | null>(null)
+  const [file, setFile] = useState<{ key: string; content: string; version?: string } | null>(null)
   const [error, setError] = useState<string | null>(null)
   const key = `${effectiveSessionId}\0${cwd ?? ''}\0${resource?.path ?? ''}`
 
@@ -53,7 +60,7 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }: any): JSX
     const controller = new AbortController()
     setError(null)
     void fsRead({ sessionId: effectiveSessionId, cwd }, resource.path, controller.signal)
-      .then(content => { if (!controller.signal.aborted) setFile({ key, content }) })
+      .then(res => { if (!controller.signal.aborted) setFile({ key, content: res.content, version: res.version }) })
       .catch(reason => { if (!controller.signal.aborted) setError(messageOf(reason)) })
     return () => controller.abort()
   }, [key, resource?.path, effectiveSessionId, cwd])
@@ -76,41 +83,65 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }: any): JSX
   }
   if (error) return <CenteredMessage title="画板载入失败" detail={error} />
   if (file?.key !== key) return <CenteredMessage title="正在载入画板" detail={fileName(resource.path)} />
-  return <DrawioCanvas content={file.content} path={resource.path} scope={{ sessionId: effectiveSessionId, cwd }} />
+  return <DrawioCanvas content={file.content} version={file.version} path={resource.path} scope={{ sessionId: effectiveSessionId, cwd }} />
 }
 
-function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX.Element {
+function DrawioCanvas({ content, version, truncated, path, scope }: FileViewerProps): JSX.Element {
   const frame = useRef<HTMLIFrameElement>(null)
   const latestFile = useRef(content ?? '')
   const latestEditor = useRef(content ?? '')
+  const latestVersion = useRef(version)
   const saveTimer = useRef<number | undefined>(undefined)
   const saveGeneration = useRef(0)
   const [ready, setReady] = useState(false)
-  const [saveState, setSaveState] = useState<'loading' | 'saved' | 'saving' | 'external' | 'error'>('loading')
+  const [saveState, setSaveState] = useState<'loading' | 'saved' | 'saving' | 'external' | 'conflict' | 'error'>('loading')
   const [error, setError] = useState<string | null>(truncated ? '文件过大，DSH 只返回了截断内容，无法安全打开。' : null)
   const lastUserActivity = useRef(0)
   const isInteracting = useRef(false)
   const { dark, accent: accentColor } = useDshTheme()
-  const src = useMemo(() => `/dsh-drawio/runtime/index.html?embed=1&proto=json&spin=1&offline=1&local=1&ui=min&libraries=1&configure=1&noExitBtn=1&saveAndExit=0&dark=${dark ? '1' : '0'}`, [dark])
+  const initialDark = useRef(dark)
+  const src = useMemo(() => `/dsh-drawio/runtime/index.html?embed=1&proto=json&spin=1&offline=1&local=1&ui=min&libraries=1&configure=1&noExitBtn=1&saveAndExit=0&dark=${initialDark.current ? '1' : '0'}`, [])
 
   const post = useCallback((message: unknown) => {
     frame.current?.contentWindow?.postMessage(JSON.stringify(message), window.location.origin)
   }, [])
 
+  const reloadFromDisk = useCallback(async () => {
+    try {
+      setSaveState('loading')
+      const result = await fsRead(scope, path)
+      latestFile.current = result.content
+      latestEditor.current = result.content
+      latestVersion.current = result.version
+      post({ action: 'load', xml: result.content, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 })
+      setSaveState('saved')
+      setError(null)
+    } catch (reason) {
+      setError(messageOf(reason))
+    }
+  }, [scope, path, dark, post])
+
   const persist = useCallback(async (xml: string) => {
     const generation = ++saveGeneration.current
     setSaveState('saving')
     try {
-      await fsWrite(scope, path, xml)
+      const outcome = await fsWrite(scope, path, xml, latestVersion.current)
       if (generation !== saveGeneration.current) return
       latestFile.current = xml
       latestEditor.current = xml
+      if (outcome?.version) latestVersion.current = outcome.version
       setSaveState('saved')
       setError(null)
     } catch (reason) {
       if (generation !== saveGeneration.current) return
-      setSaveState('error')
-      setError(messageOf(reason))
+      const msg = messageOf(reason)
+      if (msg.includes('modified by an external process') || msg.includes('409')) {
+        setSaveState('conflict')
+        setError('文件已被外部或 AI 修改，当前存在并发冲突，点击可重新载入最新内容')
+      } else {
+        setSaveState('error')
+        setError(msg)
+      }
     }
   }, [scope.sessionId, scope.cwd, path])
 
@@ -134,7 +165,8 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
   useEffect(() => {
     latestFile.current = content ?? ''
     latestEditor.current = content ?? ''
-  }, [content, path])
+    latestVersion.current = version
+  }, [content, version, path])
 
   const markActivity = useCallback(() => {
     lastUserActivity.current = Date.now()
@@ -215,17 +247,28 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
         document.body.removeChild(link)
         showToast(`已开始下载：${fileName(pending.targetPath)}`)
       } else if (pending.target === 'clipboard') {
-        if (pending.format === 'svg') {
-          const svgText = data.startsWith('data:image/svg+xml')
-            ? decodeURIComponent(data.split(',')[1] || '')
-            : data
-          await navigator.clipboard.writeText(svgText)
-          showToast('已复制 SVG 代码到剪贴板')
-        } else {
-          const res = await fetch(data)
-          const blob = await res.blob()
-          await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })])
-          showToast('已复制图片到剪贴板')
+        try {
+          if (pending.format === 'svg') {
+            const svgText = data.startsWith('data:image/svg+xml')
+              ? decodeURIComponent(data.split(',')[1] || '')
+              : data
+            await navigator.clipboard.writeText(svgText)
+            showToast('已复制 SVG 代码到剪贴板')
+          } else {
+            const res = await fetch(data)
+            const blob = await res.blob()
+            await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })])
+            showToast('已复制图片到剪贴板')
+          }
+        } catch {
+          // 剪贴板受限或报错时降级为自动下载
+          const link = document.createElement('a')
+          link.download = fileName(pending.targetPath)
+          link.href = data
+          document.body.appendChild(link)
+          link.click()
+          document.body.removeChild(link)
+          showToast(`剪贴板无权限，已自动下载：${fileName(pending.targetPath)}`)
         }
       } else if (pending.target === 'workspace') {
         const result = await fsSaveImage(scope, pending.targetPath, data)
@@ -289,14 +332,23 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
       if (typeof document !== 'undefined' && document.hidden) return
 
       try {
-        const xml = await fsRead(scope, path)
+        // 轻量检查版本号
+        const stat = await fsStat(scope, path)
+        if (cancelled || isInteracting.current || Date.now() - lastUserActivity.current < 1200) return
+        if (stat.version && latestVersion.current && stat.version === latestVersion.current) return
+
+        const res = await fsRead(scope, path)
         // 5. 响应返回后二次防护：若这期间用户按下了鼠标或开始拖动，果断丢弃本次结果
         if (cancelled || isInteracting.current || Date.now() - lastUserActivity.current < 1200) return
-        if (xml === latestFile.current || xml === latestEditor.current) return
+        if (res.content === latestFile.current || res.content === latestEditor.current) {
+          latestVersion.current = res.version
+          return
+        }
 
-        latestFile.current = xml
-        latestEditor.current = xml
-        post({ action: 'load', xml, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 })
+        latestFile.current = res.content
+        latestEditor.current = res.content
+        latestVersion.current = res.version
+        post({ action: 'load', xml: res.content, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 })
         setSaveState('external')
         window.setTimeout(() => { if (!cancelled) setSaveState('saved') }, 1200)
       } catch (reason) {
@@ -310,7 +362,7 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
 
   useEffect(() => () => {
     if (saveTimer.current !== undefined) window.clearTimeout(saveTimer.current)
-    if (latestEditor.current !== latestFile.current) void fsWrite(scope, path, latestEditor.current, true)
+    if (latestEditor.current !== latestFile.current) void fsWrite(scope, path, latestEditor.current, latestVersion.current, true)
   }, [scope.sessionId, scope.cwd, path])
 
   if (truncated) return <CenteredMessage title="无法打开画板" detail="文件内容已被截断，继续编辑可能损坏原文件。" />
@@ -411,10 +463,22 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
         </div>
       ) : null}
 
-      <div role="status" aria-live="polite" style={{ ...styles.status, ...(saveState === 'error' ? styles.statusError : {}) }}>
-        <span style={{ ...styles.dot, background: accentColor }} />{statusText(saveState)}
+      <div role="status" aria-live="polite" style={{ ...styles.status, ...(saveState === 'error' || saveState === 'conflict' ? styles.statusError : {}) }}>
+        <span style={{ ...styles.dot, background: saveState === 'conflict' ? 'var(--dsw-alias-warning, #e6a23c)' : accentColor }} />{statusText(saveState)}
       </div>
-      {error ? <button type="button" title={error} onClick={() => setError(null)} style={styles.error}>保存失败 · 点击关闭</button> : null}
+      {error ? (
+        <button
+          type="button"
+          title={error}
+          onClick={() => {
+            if (saveState === 'conflict') void reloadFromDisk()
+            setError(null)
+          }}
+          style={styles.error}
+        >
+          {saveState === 'conflict' ? '⚠️ 检测到外部修改 · 点击重新载入' : '保存失败 · 点击关闭'}
+        </button>
+      ) : null}
     </div>
   )
 }
@@ -460,13 +524,16 @@ function detectDark(): boolean {
   return document.documentElement.classList.contains('dark') || window.matchMedia('(prefers-color-scheme: dark)').matches
 }
 
-async function fsRead(scope: SessionScope, path: string, signal?: AbortSignal): Promise<string> {
-  const value = await call<{ content: string }>('read', scope, { path }, false, signal)
-  return value.content
+async function fsStat(scope: SessionScope, path: string, signal?: AbortSignal): Promise<{ version: string; size: number }> {
+  return call<{ version: string; size: number }>('stat', scope, { path }, false, signal)
+}
+
+async function fsRead(scope: SessionScope, path: string, signal?: AbortSignal): Promise<{ content: string; version: string }> {
+  return call<{ content: string; version: string }>('read', scope, { path }, false, signal)
 }
 
-async function fsWrite(scope: SessionScope, path: string, content: string, keepalive = false): Promise<void> {
-  await call('write', scope, { path, content }, keepalive)
+async function fsWrite(scope: SessionScope, path: string, content: string, version?: string, keepalive = false): Promise<{ version?: string }> {
+  return call<{ version?: string }>('write', scope, { path, content, ...(version ? { version } : {}) }, keepalive)
 }
 
 async function fsSaveImage(scope: SessionScope, path: string, data: string): Promise<{ path: string; bytes: number }> {
@@ -555,7 +622,7 @@ export function parseDrawioAddress(address?: string, fallbackSessionId?: string)
   }
 }
 const messageOf = (reason: unknown): string => reason instanceof Error ? reason.message : String(reason)
-const statusText = (state: string): string => state === 'loading' ? '正在载入' : state === 'saving' ? '正在保存' : state === 'external' ? '已同步 AI 修改' : state === 'error' ? '保存失败' : '已保存'
+const statusText = (state: string): string => state === 'loading' ? '正在载入' : state === 'saving' ? '正在保存' : state === 'external' ? '已同步 AI 修改' : state === 'conflict' ? '检测到冲突' : state === 'error' ? '保存失败' : '已保存'
 const fg = 'var(--dsw-alias-label-primary, currentColor)'
 const muted = 'var(--dsw-alias-label-secondary, rgba(127,127,127,.9))'
 const layer = 'var(--dsw-alias-container-bg, Canvas)'

package/src/index.js

@@ -46,7 +46,7 @@ export async function apply(ctx) {
   }))
   register(ctx, defineTool({
     name: 'drawio_edit',
-    description: 'Apply a batch of semantic edits to an existing .drawio file. Supported operations are add_node, add_edge, update and delete. Cell ids must be stable and unique. Inspect the file first when modifying an existing diagram.',
+    description: 'Apply a batch of semantic edits to an existing .drawio file. Supported operations: add_node, add_edge, update, delete, add_page, delete_page, rename_page. Cell ids must be stable and unique. Inspect the file first when modifying an existing diagram.',
     parameters: {
       path: pathParameter,
       page: { oneOf: [{ type: 'string' }, { type: 'number' }] },
@@ -55,8 +55,9 @@ export async function apply(ctx) {
         items: {
           type: 'object', additionalProperties: false,
           properties: {
-            type: { type: 'string', enum: ['add_node', 'add_edge', 'update', 'delete'], required: true },
-            id: { type: 'string', required: true }, label: { type: 'string' }, style: { type: 'string' }, parent: { type: 'string' },
+            type: { type: 'string', enum: ['add_node', 'add_edge', 'update', 'delete', 'add_page', 'delete_page', 'rename_page'], required: true },
+            id: { type: 'string' }, label: { type: 'string' }, name: { type: 'string' }, page: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+            style: { type: 'string' }, stylePatch: { type: 'object', additionalProperties: true }, parent: { type: 'string' },
             source: { type: 'string' }, target: { type: 'string' },
             x: { type: 'number' }, y: { type: 'number' }, width: { type: 'number' }, height: { type: 'number' },
           },
@@ -100,7 +101,7 @@ async function serveCanvasApi(ctx, req, res) {
   try {
     const pathname = new URL(req.url || '/', 'http://dsh.internal').pathname
     const method = pathname.slice('/dsh-drawio/api/'.length)
-    if (!['read', 'write', 'save-image'].includes(method)) return respondJson(res, 404, { ok: false, error: { message: 'Unknown Draw.io operation.' } })
+    if (!['stat', 'read', 'write', 'save-image'].includes(method)) return respondJson(res, 404, { ok: false, error: { message: 'Unknown Draw.io operation.' } })
     const payload = await readJsonBody(req)
 
     if (method === 'save-image') {
@@ -131,12 +132,16 @@ async function serveCanvasApi(ctx, req, res) {
     const info = await ctx.fs.stat(target)
     if (!info || info.type !== 'file') throw new Error('Draw.io file was not found.')
     if (Number(info.size) > MAX_DIAGRAM_BYTES) throw new Error('Draw.io file is too large to open safely.')
-    if (method === 'read') return respondJson(res, 200, { ok: true, value: { content: await ctx.fs.readText(target) } })
+    if (method === 'stat') return respondJson(res, 200, { ok: true, value: { version: info.version, size: Number(info.size), mtime: info.mtime } })
+    if (method === 'read') return respondJson(res, 200, { ok: true, value: { content: await ctx.fs.readText(target), version: info.version } })
     if (typeof payload.content !== 'string' || Buffer.byteLength(payload.content) > MAX_DIAGRAM_BYTES) throw new Error('Draw.io content is too large to save safely.')
+    if (payload.version !== undefined && info.version !== undefined && String(payload.version) !== String(info.version)) {
+      return respondJson(res, 409, { ok: false, conflict: true, error: { message: 'File has been modified by an external process or agent.' } })
+    }
     const xml = normalizeDrawio(payload.content)
     const sandboxPolicy = { mode: 'workspace-write', workspaceRoot: payload.cwd }
-    await ctx.fs.writeText(target, xml, { kind: 'replaceIfVersion', version: info.version }, undefined, sandboxPolicy)
-    return respondJson(res, 200, { ok: true, value: { ok: true } })
+    const outcome = await ctx.fs.writeText(target, xml, { kind: 'replaceIfVersion', version: payload.version ?? info.version }, undefined, sandboxPolicy)
+    return respondJson(res, 200, { ok: true, value: { ok: true, version: outcome?.version ?? info.version } })
   } catch (error) {
     return respondJson(res, 400, { ok: false, error: { message: String(error?.message || error).slice(0, 500) } })
   }

package/src/xml.js

@@ -10,18 +10,42 @@ export function inspectDrawio(source, includeXml = false) {
   const pages = pageNodes(document).map((page, index) => {
     const model = modelForPage(page)
     const cells = Array.from(model.getElementsByTagName('mxCell'))
+    const nodeCells = cells.filter(cell => cell.getAttribute('vertex') === '1')
+    const edgeCells = cells.filter(cell => cell.getAttribute('edge') === '1')
+    const childMap = new Map()
+    for (const cell of nodeCells) {
+      childMap.set(cell.getAttribute('id'), [])
+    }
+    for (const cell of nodeCells) {
+      const parentId = cell.getAttribute('parent')
+      if (parentId && childMap.has(parentId)) {
+        childMap.get(parentId).push(cell.getAttribute('id'))
+      }
+    }
     return {
       index,
       id: page.getAttribute('id') || `page-${index + 1}`,
       name: page.getAttribute('name') || `Page-${index + 1}`,
-      nodes: cells.filter(cell => cell.getAttribute('vertex') === '1').map(cell => cellSummary(cell)),
-      edges: cells.filter(cell => cell.getAttribute('edge') === '1').map(cell => ({
-        id: cell.getAttribute('id'),
-        label: cell.getAttribute('value') || '',
-        source: cell.getAttribute('source') || '',
-        target: cell.getAttribute('target') || '',
-        style: cell.getAttribute('style') || '',
-      })),
+      nodes: nodeCells.map(cell => {
+        const id = cell.getAttribute('id')
+        const rawValue = cell.getAttribute('value') || ''
+        return {
+          ...cellSummary(cell),
+          plainText: stripHtml(rawValue),
+          children: childMap.get(id) || [],
+        }
+      }),
+      edges: edgeCells.map(cell => {
+        const rawValue = cell.getAttribute('value') || ''
+        return {
+          id: cell.getAttribute('id'),
+          label: rawValue,
+          plainText: stripHtml(rawValue),
+          source: cell.getAttribute('source') || '',
+          target: cell.getAttribute('target') || '',
+          style: cell.getAttribute('style') || '',
+        }
+      }),
     }
   })
   return { pages, ...(includeXml ? { xml: serializer.serializeToString(document) } : {}) }
@@ -29,14 +53,51 @@ export function inspectDrawio(source, includeXml = false) {
 
 export function editDrawio(source, operations, pageSelector) {
   const document = parseDrawio(source || EMPTY_DRAWIO)
-  const pages = pageNodes(document)
-  const page = selectPage(pages, pageSelector)
-  const model = modelForPage(page)
-  const root = model.getElementsByTagName('root')[0]
+  let pages = pageNodes(document)
+  let currentPage = selectPage(pages, pageSelector)
+  let model = modelForPage(currentPage)
+  let root = model.getElementsByTagName('root')[0]
   if (!root) throw new Error('The selected page has no mxGraphModel/root element.')
 
-  for (const operation of operations) applyOperation(document, root, operation)
-  replacePageModel(document, page, model)
+  for (const operation of operations) {
+    if (!operation || typeof operation !== 'object') throw new Error('Every operation must be an object.')
+    const { type } = operation
+    if (type === 'add_page') {
+      const newPageId = operation.id || `page-${Date.now().toString(36)}`
+      const newPageName = operation.name || `Page-${pages.length + 1}`
+      const newDiagram = document.createElement('diagram')
+      newDiagram.setAttribute('id', newPageId)
+      newDiagram.setAttribute('name', newPageName)
+      const templateDoc = parseDrawio(EMPTY_DRAWIO)
+      const templateModel = modelForPage(pageNodes(templateDoc)[0])
+      newDiagram.appendChild(document.importNode(templateModel, true))
+      document.documentElement.appendChild(newDiagram)
+      pages = pageNodes(document)
+      continue
+    }
+    if (type === 'delete_page') {
+      if (pages.length <= 1) throw new Error('Cannot delete the only remaining diagram page.')
+      const targetPage = selectPage(pages, operation.page)
+      document.documentElement.removeChild(targetPage)
+      pages = pageNodes(document)
+      if (currentPage === targetPage) {
+        currentPage = pages[0]
+        model = modelForPage(currentPage)
+        root = model.getElementsByTagName('root')[0]
+      }
+      continue
+    }
+    if (type === 'rename_page') {
+      const targetPage = operation.page !== undefined ? selectPage(pages, operation.page) : currentPage
+      const newName = required(operation.name, 'rename_page.name')
+      targetPage.setAttribute('name', newName)
+      continue
+    }
+
+    applyOperation(document, root, operation)
+  }
+
+  replacePageModel(document, currentPage, model)
   document.documentElement.setAttribute('compressed', 'false')
   document.documentElement.setAttribute('modified', new Date().toISOString())
   return serializer.serializeToString(document)
@@ -49,6 +110,46 @@ export function normalizeDrawio(source) {
   return serializer.serializeToString(document)
 }
 
+export function stripHtml(input) {
+  if (!input || typeof input !== 'string') return ''
+  return input
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+export function patchStyle(currentStyle = '', patch = {}) {
+  const parts = currentStyle.split(';').map(s => s.trim()).filter(Boolean)
+  const map = new Map()
+  const bareKeys = []
+  for (const part of parts) {
+    const eqIdx = part.indexOf('=')
+    if (eqIdx >= 0) {
+      map.set(part.slice(0, eqIdx), part.slice(eqIdx + 1))
+    } else {
+      bareKeys.push(part)
+    }
+  }
+  for (const [key, val] of Object.entries(patch)) {
+    if (val === null || val === undefined || val === '') {
+      map.delete(key)
+    } else {
+      map.set(key, String(val))
+    }
+  }
+  const serialized = [
+    ...bareKeys,
+    ...Array.from(map.entries()).map(([k, v]) => `${k}=${v}`),
+  ].join(';')
+  return serialized ? `${serialized};` : ''
+}
+
 function applyOperation(document, root, operation) {
   if (!operation || typeof operation !== 'object') throw new Error('Every operation must be an object.')
   const type = operation.type
@@ -97,6 +198,10 @@ function applyOperation(document, root, operation) {
     const cell = assertCell(root, required(operation.id, 'update.id'))
     if (operation.label !== undefined) cell.setAttribute('value', stringValue(operation.label))
     if (operation.style !== undefined) cell.setAttribute('style', stringValue(operation.style))
+    if (operation.stylePatch && typeof operation.stylePatch === 'object') {
+      const current = cell.getAttribute('style') || ''
+      cell.setAttribute('style', patchStyle(current, operation.stylePatch))
+    }
     if (operation.parent !== undefined) cell.setAttribute('parent', stringValue(operation.parent))
     const geometryKeys = ['x', 'y', 'width', 'height']
     if (geometryKeys.some(key => operation[key] !== undefined)) {