@civilization/dsh-drawio 0.4.0 → 0.4.2

package/README.md

@@ -30,9 +30,9 @@
   - **SVG (矢量图)**：提取无损矢量图形，任意放大不失真；
   - **XML-PNG (可编辑图)**：在 PNG 图像中内嵌图表 XML 原数据，既能作为常规图片展示，又可随时拖回 Draw.io 继续二次编辑。
 - **三大输出方式**：
-  - **保存到工作区**：在当前画板文件同级目录下自动生成同名图片文件（如 `arch.drawio` -> `arch.png`），自动触发 DSH 文件系统感知；
-  - **复制到剪贴板**：一键将 PNG 图片写入操作系统剪贴板（`navigator.clipboard`），方便在 Markdown、PRD 或聊天工具中直接 `Ctrl + V` 粘贴；
-  - **下载图片文件**：触发浏览器原生下载弹窗保存到本地磁盘。
+  - **保存到工作区（仅 SVG）**：在当前画板文件同级目录下自动生成同名矢量文件（如 `arch.drawio` -> `arch.svg`），自动触发 DSH 文件系统感知。DSH 的 `ctx.fs` 只提供文本写入（无二进制写入口），光栅图落盘会退化成 base64 文本，因此 PNG / XML-PNG 不走此通道；
+  - **复制到剪贴板**：PNG / XML-PNG 写入操作系统剪贴板（`navigator.clipboard`），SVG 复制为源码文本，方便在 Markdown、PRD 或聊天工具中直接 `Ctrl + V` 粘贴；
+  - **下载图片文件**：触发浏览器原生下载弹窗保存到本地磁盘，三种格式均可用。
 
 ## 开发验证
 
@@ -49,7 +49,40 @@ dsh web --port 3082 --no-open
 `.drawio` 文件时，由官方资源路由选择本插件的画板；读取和自动保存通过插件自有的
 `/dsh-drawio/api` 接口完成，并限制在当前会话工作区内。
 
-已在 DSH 0.1.5-rc.2 上验证构建、XML 操作、本地静态资源加载和官方右侧栏注册。
+## 💡 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.2.0-rc.2 上验证构建、XML 操作、本地静态资源加载和官方右侧栏注册。
+
+`peerDependencies` 只声明**下界**（`>=0.1.5-rc.2`，无上界），以便跟随 DSH 的快速迭代：DSH 的兼容性判定用运行时版本比对这些范围，因此新版本不会再被旧插件卡住。代价是不再对未来的破坏性变更提供“响亮拒绝”，且**不保证前序版本**——已发布版本只在上述版本上验证过。
+
+画板地址解析直接复用 DSH 官方 `parseFileAddress`（`@deepseek-ai/dsh-util-workspace-path`），完整支持 `dsh-resource://file/session/<sid>/<path>` 与 `dsh-resource://file/absolute/<path>` 两种 scope；`absolute` 地址只有在文件位于当前会话工作区内时才能打开，工作区外会给出明确提示，服务端仍会二次校验边界。
 
 当前内置的精简 Draw.io runtime 固定为 31.4.5。包含完整满血版内置图库（通用、流程图、UML、ER、BPMN、网络、Kubernetes、AWS、GCP、Cisco、电子、平面图等全部分类均可自由开启）以及 PlantUML 离线渲染模块；
 云盘、在线图库、模板库、VSDX/Gliffy 导入未包含；已全面支持纯本地离线 Canvas + SVG 导出引擎。

package/lib/client.js

@@ -23,11 +23,110 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   apply: () => apply,
-  inject: () => inject,
-  parseDrawioAddress: () => parseDrawioAddress
+  inject: () => inject
 });
 module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
+
+// src/svg.js
+function base64ToText(value) {
+  const clean = value.replace(/\s+/g, "");
+  const binary = atob(clean);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return new TextDecoder().decode(bytes);
+}
+function svgMarkupOf(data) {
+  if (typeof data !== "string") return null;
+  const value = data.trim();
+  if (value === "") return null;
+  if (!value.startsWith("data:")) return value;
+  const comma = value.indexOf(",");
+  if (comma < 0) return null;
+  const header = value.slice("data:".length, comma).toLowerCase();
+  if (!header.startsWith("image/svg+xml")) return null;
+  const body = value.slice(comma + 1);
+  if (header.includes(";base64")) {
+    try {
+      return base64ToText(body);
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return decodeURIComponent(body);
+  } catch {
+    return body;
+  }
+}
+
+// node_modules/.pnpm/@deepseek-ai+dsh-util-workspace-path@0.2.0-rc.2_@deepseek-ai+cordis@4.0.4/node_modules/@deepseek-ai/dsh-util-workspace-path/lib/index.js
+var FILE_ADDRESS_PREFIX = "dsh-resource://file/";
+function isDriveSegment(segment) {
+  return segment !== void 0 && /^[A-Za-z]:$/.test(segment);
+}
+function parseFileAddress(address) {
+  try {
+    if (!address.startsWith(FILE_ADDRESS_PREFIX)) return void 0;
+    const end = address.search(/[?#]/);
+    const [scope, ...rest] = address.slice(20, end === -1 ? void 0 : end).split("/");
+    if (scope === "session") {
+      const [id, ...segments] = rest;
+      if (id === void 0 || id === "" || segments.length === 0) return void 0;
+      return {
+        scope,
+        sessionId: decodeURIComponent(id),
+        path: segments.map(decodeURIComponent).join("/")
+      };
+    }
+    if (scope === "absolute") {
+      const unc = rest[0] === "" && rest.length > 1;
+      const segments = (unc ? rest.slice(1) : rest).map(decodeURIComponent);
+      if (segments.length === 0 || segments[0] === "") return void 0;
+      if (unc) return {
+        scope,
+        path: `//${segments.join("/")}`
+      };
+      return {
+        scope,
+        path: isDriveSegment(segments[0]) ? segments.join("/") : `/${segments.join("/")}`
+      };
+    }
+    return;
+  } catch {
+    return;
+  }
+}
+
+// src/client/address.js
+var DRAWIO_SUFFIX = /\.drawio$/i;
+function parseDrawioAddress(address, fallbackSessionId) {
+  if (typeof address !== "string") return null;
+  const trimmed = address.trim();
+  if (trimmed === "") return null;
+  const parsed = parseFileAddress(trimmed);
+  if (parsed === void 0) return null;
+  if (parsed.path.includes("\0")) return null;
+  if (!DRAWIO_SUFFIX.test(parsed.path)) return null;
+  if (parsed.scope === "session") {
+    return { scope: "session", sessionId: parsed.sessionId, path: parsed.path };
+  }
+  return { scope: "absolute", sessionId: fallbackSessionId || "", path: parsed.path };
+}
+function relativeToWorkspace(path, cwd) {
+  if (typeof path !== "string" || typeof cwd !== "string") return null;
+  const root = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+  if (root === "") return null;
+  const target = path.replace(/\\/g, "/");
+  const foldCase = /^[A-Za-z]:/.test(root) || root.startsWith("//");
+  const left = foldCase ? root.toLowerCase() : root;
+  const right = foldCase ? target.toLowerCase() : target;
+  if (right === left) return "";
+  if (right.startsWith(`${left}/`)) return target.slice(root.length + 1);
+  return null;
+}
+
+// src/client/index.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var inject = ["slots", "sidebarRightTabs"];
 var TAB_ID = "@civilization/dsh-drawio";
@@ -37,7 +136,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");
@@ -66,20 +172,23 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }) {
   const resourceCwd = useSessions((sessions) => resource?.sessionId ? sessions?.byId?.[resource.sessionId]?.cwd : void 0);
   const cwd = activeCwd || resourceCwd;
   const effectiveSessionId = sessionId || resource?.sessionId || "";
+  const relativePath = resource?.scope === "absolute" ? relativeToWorkspace(resource.path, cwd) : null;
+  const outsideWorkspace = resource?.scope === "absolute" && cwd !== void 0 && relativePath === null;
+  const openPath = resource?.scope === "absolute" ? relativePath : resource?.path ?? null;
   const [file, setFile] = (0, import_react.useState)(null);
   const [error, setError] = (0, import_react.useState)(null);
-  const key = `${effectiveSessionId}\0${cwd ?? ""}\0${resource?.path ?? ""}`;
+  const key = `${effectiveSessionId}\0${cwd ?? ""}\0${openPath ?? ""}`;
   (0, import_react.useEffect)(() => {
-    if (!resource?.path || !effectiveSessionId || !cwd) return;
+    if (!openPath || !effectiveSessionId || !cwd) return;
     const controller = new AbortController();
     setError(null);
-    void fsRead({ sessionId: effectiveSessionId, cwd }, resource.path, controller.signal).then((res) => {
+    void fsRead({ sessionId: effectiveSessionId, cwd }, openPath, 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));
     });
     return () => controller.abort();
-  }, [key, resource?.path, effectiveSessionId, cwd]);
+  }, [key, openPath, effectiveSessionId, cwd]);
   if (!resource || !resource.path) {
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       CenteredMessage,
@@ -98,9 +207,19 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }) {
       }
     );
   }
+  if (outsideWorkspace) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      CenteredMessage,
+      {
+        title: "\u65E0\u6CD5\u6253\u5F00\u753B\u677F",
+        detail: `\u8BE5\u6587\u4EF6\u4E0D\u5728\u5F53\u524D\u5DE5\u4F5C\u533A\u5185\uFF0C\u753B\u677F\u53EA\u80FD\u6253\u5F00\u5DE5\u4F5C\u533A\u4E2D\u7684 .drawio \u6587\u4EF6\uFF1A${resource.path}`
+      }
+    );
+  }
+  if (!openPath) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CenteredMessage, { title: "\u65E0\u6CD5\u6253\u5F00\u753B\u677F", detail: "\u65E0\u6CD5\u786E\u5B9A\u753B\u677F\u6587\u4EF6\u7684\u5DE5\u4F5C\u533A\u76F8\u5BF9\u8DEF\u5F84\u3002" });
   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, version: file.version, path: resource.path, scope: { sessionId: effectiveSessionId, cwd } });
+  if (file?.key !== key) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(CenteredMessage, { title: "\u6B63\u5728\u8F7D\u5165\u753B\u677F", detail: fileName(openPath) });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DrawioCanvas, { content: file.content, version: file.version, path: openPath, scope: { sessionId: effectiveSessionId, cwd } });
 }
 function DrawioCanvas({ content, version, truncated, path, scope }) {
   const frame = (0, import_react.useRef)(null);
@@ -221,6 +340,10 @@ function DrawioCanvas({ content, version, truncated, path, scope }) {
   }, []);
   const startExport = (0, import_react.useCallback)((target) => {
     if (!ready || isExporting) return;
+    if (target === "workspace" && exportFormat !== "svg") {
+      showToast("\u4EC5 SVG \u652F\u6301\u4FDD\u5B58\u5230\u5DE5\u4F5C\u533A\uFF0CPNG / XML-PNG \u8BF7\u4F7F\u7528\u4E0B\u8F7D\u6216\u526A\u8D34\u677F");
+      return;
+    }
     const ext = exportFormat === "svg" ? ".svg" : exportFormat === "xmlpng" ? ".drawio.png" : ".png";
     const base = path.replace(/\.drawio$/i, "");
     const targetPath = `${base}${ext}`;
@@ -239,7 +362,7 @@ function DrawioCanvas({ content, version, truncated, path, scope }) {
       border: 10,
       spin: "\u6B63\u5728\u6E32\u67D3\u5BFC\u51FA\u56FE\u7247..."
     });
-  }, [ready, isExporting, exportFormat, isTransparent, path, post]);
+  }, [ready, isExporting, exportFormat, isTransparent, path, post, showToast]);
   const handleExportResult = (0, import_react.useCallback)(async (pending, data) => {
     try {
       if (pending.target === "download") {
@@ -253,7 +376,7 @@ function DrawioCanvas({ content, version, truncated, path, scope }) {
       } else if (pending.target === "clipboard") {
         try {
           if (pending.format === "svg") {
-            const svgText = data.startsWith("data:image/svg+xml") ? decodeURIComponent(data.split(",")[1] || "") : data;
+            const svgText = svgMarkupOf(data) ?? data;
             await navigator.clipboard.writeText(svgText);
             showToast("\u5DF2\u590D\u5236 SVG \u4EE3\u7801\u5230\u526A\u8D34\u677F");
           } else {
@@ -412,19 +535,24 @@ function DrawioCanvas({ content, version, truncated, path, scope }) {
           ),
           /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: "\u900F\u660E\u80CC\u666F" })
         ] }) : null,
+        exportFormat !== "svg" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: styles.menuSub, children: "\u4FDD\u5B58\u5230\u5DE5\u4F5C\u533A\u4EC5\u652F\u6301 SVG\uFF1BPNG / XML-PNG \u8BF7\u7528\u4E0B\u8F7D\u6216\u526A\u8D34\u677F\u3002" }) : null,
         /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.actionCol, children: [
           /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
             "button",
             {
               type: "button",
               onClick: () => startExport("workspace"),
-              style: { ...styles.actionBtn, ...styles.actionBtnPrimary, background: accentColor },
+              disabled: exportFormat !== "svg",
+              title: exportFormat === "svg" ? `\u4FDD\u5B58\u4E3A ${targetExt} \u5230\u753B\u677F\u540C\u7EA7\u76EE\u5F55` : "\u4EC5 SVG \u652F\u6301\u4FDD\u5B58\u5230\u5DE5\u4F5C\u533A\uFF0CPNG / XML-PNG \u8BF7\u4F7F\u7528\u4E0B\u8F7D\u6216\u526A\u8D34\u677F",
+              style: {
+                ...styles.actionBtn,
+                ...exportFormat === "svg" ? { ...styles.actionBtnPrimary, background: accentColor } : { opacity: 0.5, cursor: "not-allowed" }
+              },
               children: [
                 /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SaveIcon, { size: 13 }),
                 /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { children: [
-                  "\u4FDD\u5B58\u5230\u5DE5\u4F5C\u533A (",
-                  targetExt,
-                  ")"
+                  "\u4FDD\u5B58\u5230\u5DE5\u4F5C\u533A ",
+                  exportFormat === "svg" ? `(${targetExt})` : "(\u4EC5 SVG)"
                 ] })
               ]
             }
@@ -578,41 +706,6 @@ function CenteredMessage({ title, detail }) {
   ] });
 }
 var fileName = (path) => path.replace(/\\/g, "/").split("/").pop() || path;
-function parseDrawioAddress(address, fallbackSessionId) {
-  if (!address || typeof address !== "string") return null;
-  try {
-    let clean = address.trim();
-    let parsedSessionId = "";
-    if (clean.startsWith("dsh-resource://file/session/")) {
-      const rest = clean.slice("dsh-resource://file/session/".length);
-      const slashIdx = rest.indexOf("/");
-      if (slashIdx >= 0) {
-        parsedSessionId = decodeURIComponent(rest.slice(0, slashIdx));
-        clean = rest.slice(slashIdx + 1);
-      } else {
-        clean = rest;
-      }
-    } else if (clean.startsWith("dsh-resource://file/")) {
-      clean = clean.slice("dsh-resource://file/".length);
-    } else if (clean.startsWith("file:///")) {
-      clean = clean.slice("file:///".length);
-    }
-    let decodedPath = clean;
-    try {
-      decodedPath = decodeURIComponent(clean);
-    } catch {
-    }
-    decodedPath = decodedPath.replace(/\\/g, "/").replace(/^\/+/, "");
-    if (!/\.drawio$/i.test(decodedPath)) return null;
-    if (decodedPath.includes("\0")) return null;
-    return {
-      sessionId: parsedSessionId || fallbackSessionId || "",
-      path: decodedPath
-    };
-  } catch {
-    return null;
-  }
-}
 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 === "conflict" ? "\u68C0\u6D4B\u5230\u51B2\u7A81" : state === "error" ? "\u4FDD\u5B58\u5931\u8D25" : "\u5DF2\u4FDD\u5B58";
 var fg = "var(--dsw-alias-label-primary, currentColor)";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civilization/dsh-drawio",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Local draw.io canvas and model tools for DeepSeek Harness",
   "license": "Apache-2.0",
   "type": "module",
@@ -51,15 +51,16 @@
     "provenance": true
   },
   "dependencies": {
+    "@deepseek-ai/dsh-util-workspace-path": "0.2.0-rc.2",
     "@deepseek-ai/schemastery": "3.18.2",
     "@xmldom/xmldom": "0.9.12",
     "pako": "2.1.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0 <5.0.0-0",
-    "@deepseek-ai/dsh-fs": ">=0.1.2-rc.1 <0.2.0-0",
-    "@deepseek-ai/dsh-host-webserver": ">=0.1.2-rc.1 <0.2.0-0",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0-0"
+    "@deepseek-ai/dsh-fs": ">=0.1.5-rc.2",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.5-rc.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-sandbox": {
@@ -67,11 +68,11 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-fs": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-sandbox": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-fs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
     "@types/react": "18.3.31",
     "esbuild": "0.28.2",
     "react": "18.3.1",

package/src/client/address.js

@@ -0,0 +1,64 @@
+import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+
+const DRAWIO_SUFFIX = /\.drawio$/i
+
+/**
+ * One Draw.io file named by a sidebar tab address.
+ * @typedef {object} DrawioAddress
+ * @property {'session' | 'absolute'} scope - which scope of the `dsh-resource://file/…` grammar named it.
+ * @property {string} sessionId - the session that resolves the path; empty for an absolute address opened without a pane session.
+ * @property {string} path - workspace-relative or absolute `/`-separated path, exactly as the address carried it.
+ */
+
+/**
+ * Parse one sidebar tab address into the Draw.io file it names.
+ *
+ * The grammar is DSH's own (`dsh-resource://file/session/<sessionId>/<path>` and
+ * `dsh-resource://file/absolute/<path>`), so parsing is delegated to the product
+ * util rather than re-implemented here; only the Draw.io file filter and the
+ * fallback session for a session-less absolute address are added on top. A
+ * session-scoped path stays exactly as written — it may be workspace-relative
+ * or absolute — because the host resolves and confines it.
+ *
+ * @param {string | undefined} address - the address the tab was claimed for.
+ * @param {string} [fallbackSessionId] - the pane's session, used when the address carries none.
+ * @returns {DrawioAddress | null} the parsed file, or `null` when the address names anything else.
+ */
+export function parseDrawioAddress(address, fallbackSessionId) {
+  if (typeof address !== 'string') return null
+  const trimmed = address.trim()
+  if (trimmed === '') return null
+  const parsed = parseFileAddress(trimmed)
+  if (parsed === undefined) return null
+  if (parsed.path.includes('\0')) return null
+  if (!DRAWIO_SUFFIX.test(parsed.path)) return null
+  if (parsed.scope === 'session') {
+    return { scope: 'session', sessionId: parsed.sessionId, path: parsed.path }
+  }
+  return { scope: 'absolute', sessionId: fallbackSessionId || '', path: parsed.path }
+}
+
+/**
+ * The workspace-relative form of an absolute path.
+ *
+ * An absolute address carries no session, so the canvas needs this answer
+ * before it can read through the host: a path under the session workspace is
+ * addressed relatively, and one outside it is not openable at all.
+ *
+ * @param {string | undefined} path - absolute path in either separator spelling.
+ * @param {string | undefined} cwd - the session workspace root.
+ * @returns {string | null} the workspace-relative path (empty for the root itself), or `null` when it is outside.
+ */
+export function relativeToWorkspace(path, cwd) {
+  if (typeof path !== 'string' || typeof cwd !== 'string') return null
+  const root = cwd.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (root === '') return null
+  const target = path.replace(/\\/g, '/')
+  // A Windows drive or UNC root addresses the same file in either case.
+  const foldCase = /^[A-Za-z]:/.test(root) || root.startsWith('//')
+  const left = foldCase ? root.toLowerCase() : root
+  const right = foldCase ? target.toLowerCase() : target
+  if (right === left) return ''
+  if (right.startsWith(`${left}/`)) return target.slice(root.length + 1)
+  return null
+}

package/src/client/index.tsx

@@ -1,5 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { svgMarkupOf } from '../svg.js'
+import { parseDrawioAddress, relativeToWorkspace } from './address.js'
 
 export const inject = ['slots', 'sidebarRightTabs']
 const TAB_ID = '@civilization/dsh-drawio'
@@ -14,7 +16,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,19 +53,25 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }: any): JSX
   const cwd = activeCwd || resourceCwd
   const effectiveSessionId = sessionId || resource?.sessionId || ''
 
+  // An absolute address carries no session, so it is openable only when it names
+  // a file under this session's workspace; the host re-checks that boundary.
+  const relativePath = resource?.scope === 'absolute' ? relativeToWorkspace(resource.path, cwd) : null
+  const outsideWorkspace = resource?.scope === 'absolute' && cwd !== undefined && relativePath === null
+  const openPath = resource?.scope === 'absolute' ? relativePath : resource?.path ?? 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 ?? ''}`
+  const key = `${effectiveSessionId}\0${cwd ?? ''}\0${openPath ?? ''}`
 
   useEffect(() => {
-    if (!resource?.path || !effectiveSessionId || !cwd) return
+    if (!openPath || !effectiveSessionId || !cwd) return
     const controller = new AbortController()
     setError(null)
-    void fsRead({ sessionId: effectiveSessionId, cwd }, resource.path, controller.signal)
+    void fsRead({ sessionId: effectiveSessionId, cwd }, openPath, 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)) })
     return () => controller.abort()
-  }, [key, resource?.path, effectiveSessionId, cwd])
+  }, [key, openPath, effectiveSessionId, cwd])
 
   if (!resource || !resource.path) {
     return (
@@ -74,9 +89,18 @@ function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }: any): JSX
       />
     )
   }
+  if (outsideWorkspace) {
+    return (
+      <CenteredMessage
+        title="无法打开画板"
+        detail={`该文件不在当前工作区内，画板只能打开工作区中的 .drawio 文件：${resource.path}`}
+      />
+    )
+  }
+  if (!openPath) return <CenteredMessage title="无法打开画板" detail="无法确定画板文件的工作区相对路径。" />
   if (error) return <CenteredMessage title="画板载入失败" detail={error} />
-  if (file?.key !== key) return <CenteredMessage title="正在载入画板" detail={fileName(resource.path)} />
-  return <DrawioCanvas content={file.content} version={file.version} path={resource.path} scope={{ sessionId: effectiveSessionId, cwd }} />
+  if (file?.key !== key) return <CenteredMessage title="正在载入画板" detail={fileName(openPath)} />
+  return <DrawioCanvas content={file.content} version={file.version} path={openPath} scope={{ sessionId: effectiveSessionId, cwd }} />
 }
 
 function DrawioCanvas({ content, version, truncated, path, scope }: FileViewerProps): JSX.Element {
@@ -208,6 +232,13 @@ function DrawioCanvas({ content, version, truncated, path, scope }: FileViewerPr
 
   const startExport = useCallback((target: 'workspace' | 'download' | 'clipboard') => {
     if (!ready || isExporting) return
+    // The workspace target is SVG-only: DSH's filesystem service writes text
+    // (there is no binary write seam), so a raster export would land as base64
+    // text. PNG and XML-PNG stay available through download and clipboard.
+    if (target === 'workspace' && exportFormat !== 'svg') {
+      showToast('仅 SVG 支持保存到工作区，PNG / XML-PNG 请使用下载或剪贴板')
+      return
+    }
     const ext = exportFormat === 'svg' ? '.svg' : exportFormat === 'xmlpng' ? '.drawio.png' : '.png'
     const base = path.replace(/\.drawio$/i, '')
     const targetPath = `${base}${ext}`
@@ -227,7 +258,7 @@ function DrawioCanvas({ content, version, truncated, path, scope }: FileViewerPr
       border: 10,
       spin: '正在渲染导出图片...',
     })
-  }, [ready, isExporting, exportFormat, isTransparent, path, post])
+  }, [ready, isExporting, exportFormat, isTransparent, path, post, showToast])
 
   const handleExportResult = useCallback(async (pending: { format: 'png' | 'svg' | 'xmlpng'; target: 'workspace' | 'download' | 'clipboard'; targetPath: string }, data: string) => {
     try {
@@ -242,9 +273,7 @@ function DrawioCanvas({ content, version, truncated, path, scope }: FileViewerPr
       } else if (pending.target === 'clipboard') {
         try {
           if (pending.format === 'svg') {
-            const svgText = data.startsWith('data:image/svg+xml')
-              ? decodeURIComponent(data.split(',')[1] || '')
-              : data
+            const svgText = svgMarkupOf(data) ?? data
             await navigator.clipboard.writeText(svgText)
             showToast('已复制 SVG 代码到剪贴板')
           } else {
@@ -416,14 +445,23 @@ function DrawioCanvas({ content, version, truncated, path, scope }: FileViewerPr
               </label>
             ) : null}
 
+            {exportFormat !== 'svg' ? (
+              <span style={styles.menuSub}>保存到工作区仅支持 SVG；PNG / XML-PNG 请用下载或剪贴板。</span>
+            ) : null}
+
             <div style={styles.actionCol}>
               <button
                 type="button"
                 onClick={() => startExport('workspace')}
-                style={{ ...styles.actionBtn, ...styles.actionBtnPrimary, background: accentColor }}
+                disabled={exportFormat !== 'svg'}
+                title={exportFormat === 'svg' ? `保存为 ${targetExt} 到画板同级目录` : '仅 SVG 支持保存到工作区，PNG / XML-PNG 请使用下载或剪贴板'}
+                style={{
+                  ...styles.actionBtn,
+                  ...(exportFormat === 'svg' ? { ...styles.actionBtnPrimary, background: accentColor } : { opacity: 0.5, cursor: 'not-allowed' }),
+                }}
               >
                 <SaveIcon size={13} />
-                <span>保存到工作区 ({targetExt})</span>
+                <span>保存到工作区 {exportFormat === 'svg' ? `(${targetExt})` : '(仅 SVG)'}</span>
               </button>
 
               <button
@@ -569,51 +607,6 @@ function CenteredMessage({ title, detail }: { title: string; detail: string }):
 }
 
 const fileName = (path: string): string => path.replace(/\\/g, '/').split('/').pop() || path
-
-export function parseDrawioAddress(address?: string, fallbackSessionId?: string): { sessionId: string; path: string } | null {
-  if (!address || typeof address !== 'string') return null
-  try {
-    let clean = address.trim()
-    let parsedSessionId = ''
-
-    if (clean.startsWith('dsh-resource://file/session/')) {
-      const rest = clean.slice('dsh-resource://file/session/'.length)
-      const slashIdx = rest.indexOf('/')
-      if (slashIdx >= 0) {
-        parsedSessionId = decodeURIComponent(rest.slice(0, slashIdx))
-        clean = rest.slice(slashIdx + 1)
-      } else {
-        clean = rest
-      }
-    } else if (clean.startsWith('dsh-resource://file/')) {
-      clean = clean.slice('dsh-resource://file/'.length)
-    } else if (clean.startsWith('file:///')) {
-      clean = clean.slice('file:///'.length)
-    }
-
-    // 处理可能是 URL 编码的 path（支持嵌套目录 %2F）
-    let decodedPath = clean
-    try {
-      decodedPath = decodeURIComponent(clean)
-    } catch {}
-
-    // 规范化斜杠并去除开头的斜杠
-    decodedPath = decodedPath.replace(/\\/g, '/').replace(/^\/+/, '')
-
-    // 必须是 .drawio 文件
-    if (!/\.drawio$/i.test(decodedPath)) return null
-
-    // 防空字符
-    if (decodedPath.includes('\0')) return null
-
-    return {
-      sessionId: parsedSessionId || fallbackSessionId || '',
-      path: decodedPath,
-    }
-  } catch {
-    return null
-  }
-}
 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 === 'conflict' ? '检测到冲突' : state === 'error' ? '保存失败' : '已保存'
 const fg = 'var(--dsw-alias-label-primary, currentColor)'

package/src/index.js

@@ -3,6 +3,7 @@ import { stat, readFile } from 'node:fs/promises'
 import { extname, join, normalize, relative, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { isSvgMarkup, svgMarkupOf } from './svg.js'
 import { editDrawio, inspectDrawio, normalizeDrawio } from './xml.js'
 
 export const name = 'dsh-drawio'
@@ -105,27 +106,19 @@ async function serveCanvasApi(ctx, req, res) {
     const payload = await readJsonBody(req)
 
     if (method === 'save-image') {
-      if (typeof payload.data !== 'string' || !payload.data.trim()) throw new Error('Image data is required.')
+      // The workspace target is SVG-only: DSH's filesystem service writes text,
+      // with no binary seam, so a raster export has no faithful landing place.
+      // PNG and XML-PNG are exported through the browser instead.
+      const markup = svgMarkupOf(payload.data)
+      if (markup === null || !isSvgMarkup(markup)) throw new Error('Only an SVG export can be saved to the workspace.')
+      const svg = markup.trim()
+      const bytes = Buffer.byteLength(svg)
+      if (bytes > MAX_DIAGRAM_BYTES) throw new Error('SVG data is too large to save safely.')
       const target = await resolveCanvasTarget(ctx, payload.cwd, payload.path, true)
-      let buffer
-      if (payload.data.startsWith('data:')) {
-        const comma = payload.data.indexOf(',')
-        const base64 = comma >= 0 ? payload.data.slice(comma + 1) : payload.data
-        buffer = Buffer.from(base64, 'base64')
-      } else if (payload.data.startsWith('<svg') || payload.data.startsWith('<?xml')) {
-        buffer = Buffer.from(payload.data, 'utf8')
-      } else {
-        buffer = Buffer.from(payload.data, 'base64')
-      }
-      if (buffer.length > MAX_REQUEST_BYTES) throw new Error('Image data is too large to save safely.')
       const sandboxPolicy = { mode: 'workspace-write', workspaceRoot: payload.cwd }
-      const outcome = typeof ctx.fs.writeFile === 'function'
-        ? await ctx.fs.writeFile(target, buffer, { kind: 'replace' }, undefined, sandboxPolicy)
-        : typeof ctx.fs.writeBinary === 'function'
-          ? await ctx.fs.writeBinary(target, buffer, { kind: 'replace' }, undefined, sandboxPolicy)
-          : await ctx.fs.writeText(target, payload.path.endsWith('.svg') ? buffer.toString('utf8') : buffer.toString('base64'), { kind: 'replace' }, undefined, sandboxPolicy)
+      const outcome = await ctx.fs.writeText(target, svg, { kind: 'replace' }, undefined, sandboxPolicy)
       ctx.emit?.('fs/observed', target, { kind: 'present', version: outcome?.version }, undefined)
-      return respondJson(res, 200, { ok: true, value: { path: target.displayPath ?? payload.path, bytes: buffer.length } })
+      return respondJson(res, 200, { ok: true, value: { path: target.displayPath ?? payload.path, bytes } })
     }
 
     const target = await resolveCanvasTarget(ctx, payload.cwd, payload.path)
@@ -147,10 +140,10 @@ async function serveCanvasApi(ctx, req, res) {
   }
 }
 
-async function resolveCanvasTarget(ctx, cwd, path, allowImage = false) {
+async function resolveCanvasTarget(ctx, cwd, path, allowSvgExport = false) {
   if (typeof cwd !== 'string' || !cwd.trim()) throw new Error('A workspace is required.')
-  if (allowImage) {
-    assertExportImagePath(path)
+  if (allowSvgExport) {
+    assertSvgExportPath(path)
   } else {
     assertDrawioPath(path)
   }
@@ -159,8 +152,8 @@ async function resolveCanvasTarget(ctx, cwd, path, allowImage = false) {
   return target
 }
 
-function assertExportImagePath(value) {
-  if (typeof value !== 'string' || !/\.(png|svg|xml\.png)$/i.test(value)) throw new Error('path must end with .png or .svg')
+function assertSvgExportPath(value) {
+  if (typeof value !== 'string' || !/\.svg$/i.test(value)) throw new Error('path must end with .svg')
 }
 
 async function readJsonBody(req) {

package/src/svg.js

@@ -0,0 +1,61 @@
+/**
+ * SVG export payload handling shared by the host route and the canvas client.
+ *
+ * The bundled Draw.io runtime hands an export back in one of two carrier
+ * forms: the common `data:image/svg+xml;base64,<base64>` data URL, or a
+ * `data:image/svg+xml,<percent-encoded>` / raw-markup payload. Both are
+ * normalized to markup here so a caller never guesses which one it received.
+ * The module stays browser-safe: it decodes with `atob`/`TextDecoder`, never
+ * with Node's `Buffer`.
+ */
+
+/**
+ * Decode one base64 payload without depending on Node globals.
+ * @param {string} value - base64 text, whitespace tolerated.
+ * @returns {string} the decoded text.
+ */
+function base64ToText(value) {
+  const clean = value.replace(/\s+/g, '')
+  const binary = atob(clean)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)
+  return new TextDecoder().decode(bytes)
+}
+
+/**
+ * Normalize one export payload to SVG markup.
+ * @param {unknown} data - raw markup, or a `data:` URL carrying it.
+ * @returns {string | null} the markup, or `null` when the payload names another media type or cannot be decoded.
+ */
+export function svgMarkupOf(data) {
+  if (typeof data !== 'string') return null
+  const value = data.trim()
+  if (value === '') return null
+  if (!value.startsWith('data:')) return value
+  const comma = value.indexOf(',')
+  if (comma < 0) return null
+  const header = value.slice('data:'.length, comma).toLowerCase()
+  if (!header.startsWith('image/svg+xml')) return null
+  const body = value.slice(comma + 1)
+  if (header.includes(';base64')) {
+    try {
+      return base64ToText(body)
+    } catch {
+      return null
+    }
+  }
+  try {
+    return decodeURIComponent(body)
+  } catch {
+    return body
+  }
+}
+
+/**
+ * Whether one payload is SVG markup the workspace may store as text.
+ * @param {unknown} value - candidate markup.
+ * @returns {boolean} whether a root `<svg>` element is present.
+ */
+export function isSvgMarkup(value) {
+  return typeof value === 'string' && /<svg[\s>]/i.test(value)
+}