dsh-drawai 0.2.0 → 0.2.2

package/README.md

@@ -6,23 +6,24 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/fourzkw/dsh-drawai?style=social)](https://github.com/fourzkw/dsh-drawai) [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-**DSH 右侧栏里的可编辑画布 —— 加上让模型直接改图的两个工具。**
+## 功能一览
 
-> *An editable diagram canvas in the DSH right sidebar, plus two agent tools (`diagram_read` / `diagram_apply`) that read and edit the workspace's native `.drawio` files in place.*
+`dsh-drawai` 把可编辑画布放进 DeepSeek Harness 右侧栏，并给模型两个改图工具；人和 AI 读写的是同一份原生 `.drawio`。
 
-`dsh-drawai` 把一块**可编辑的画布**放进 DeepSeek Harness 的右侧栏，再给模型**两个工具**；两者读写的是同一份文件。
+1. **右侧栏可编辑画布** —— 打开 / 新建工作区 `.drawio`：画节点、连边、就地改字、分层、排序、对齐、导出；双击即可改标签。
+2. **自然语言改图** —— 对话里说需求，模型用 `diagram_read` / `diagram_apply` 读现状、结构化改图、自动布局并原子写回。
+3. **选区感知与回退** —— 你在画布上选中什么，模型就知道什么；模型改动最多可退 8 步。
+4. **SVG 图形节点** —— 图标 / logo 可直接当节点内容，拼流程图与示意图。
+5. **位图矢量化（`traceImage`）** —— 照着工作区图片逐像素描成 SVG 节点，不是凭印象手写近似图。
+6. **原生 `.drawio` 载体** —— 无需导入导出；画布读不懂的单元逐字节保留，文件可直接用 drawio / diagrams.net 继续编辑。
 
-- **画布（右侧栏面板）** —— 打开工作区里的 `.drawio`：画节点、连边、就地改字、分层、排序、对齐、导出，双击节点就能改标签。
-- **`diagram_apply`** —— 模型改图的入口：15 个结构化 ops，改完自动布局并**原子写回**。
-- **`diagram_read`** —— 模型的眼睛：结构、样式键、图层、父级、页面尺寸、**你此刻的选区**、文件指纹 `revision`。
-- **选中与回退** —— 你在画布上选中什么，模型就知道什么；模型的改动最多可以退 8 步。
-- **载体是原生 `.drawio` 文件** —— 不需要导入导出，存出来的文件可以直接用 drawio / diagrams.net 打开继续编辑。
+![整体界面：右侧栏画布与多标签](docs/picture/整体界面图.png)
 
-```
-人（侧边栏画布）      ┐
-AI（diagram_apply）  ├──→  工作区的 .drawio（mxfile）  ──→  用 drawio / diagrams.net 直接打开继续编辑
-drawio 本体           ┘         ↑ 无损写回：画布读不懂的单元逐字节保留
-```
+![从对话到改图的逻辑流程](docs/picture/drawai逻辑图.png)
+
+![用 SVG 节点拼的流程图与图标](docs/picture/图标绘制.png)
+
+![位图矢量化复刻对比](docs/picture/大肥鱼复刻图.png)
 
 ## 安装 / Install
 
@@ -199,7 +200,7 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 
 ## 须知 / Good to know
 
-- **兼容性**：DSH（DeepSeek Harness）Web；官方包以 `peerDependencies` 声明（`@deepseek-ai/dsh-tools`），Node `>= 20`。
+- **兼容性**：DSH（DeepSeek Harness）Web `0.1.x` 与 `0.2.x`（含 `0.2.0-rc.*`）；官方包以 `peerDependencies` 声明（`@deepseek-ai/dsh-tools`），Node `>= 20`。
 - **生效方式**：宿主侧只在 `dsh web` 启动时加载，换 `lib/index.js` 必须**重启**；客户端是独立 bundle，刷新页面即可。
 - **界面语言**：目前只有简体中文，还没有 i18n。
 - **大图性能**：几百个单元时的重渲染与路由开销还没测过。

package/lib/client.js

@@ -1135,6 +1135,38 @@ window.__ModuleLoader__.load({
     }
 
     const POLL_MS = 3000
+    /**
+     * 打开 workspaceFiles 变更流，兼容 DSH 0.1 与 0.2 的不同签名：
+     *   0.1：changes(sessionId, signal) —— 会话级观测写入
+     *   0.2：changes(sessionId, path, signal) —— 按路径订阅
+     *
+     * `changes.length < 3` 时走 0.1；否则（含 length 为 0 / 不可靠的 Remote 代理）在
+     * 有 path 时先试三参，迭代启动失败再退回两参。外层仍有轮询兜底。
+     */
+    async function* openWorkspaceFileChanges(workspaceFiles, sessionId, path, signal) {
+      const changes = workspaceFiles.changes
+      const watchPath = typeof path === 'string' ? path : ''
+      const arity = typeof changes.length === 'number' ? changes.length : 0
+      if (arity > 0 && arity < 3) {
+        yield* changes.call(workspaceFiles, sessionId, signal)
+        return
+      }
+      if (watchPath.length > 0) {
+        try {
+          const stream = changes.call(workspaceFiles, sessionId, watchPath, signal)
+          const iterator = stream[Symbol.asyncIterator]()
+          let first = await iterator.next()
+          while (true) {
+            if (first.done) return
+            yield first.value
+            first = await iterator.next()
+          }
+        } catch {
+          // 三参被拒（老宿主 / 代理 length 说谎）→ 退回 0.1 两参
+        }
+      }
+      yield* changes.call(workspaceFiles, sessionId, signal)
+    }
     /**
      * 选区上报的防抖时间（ms）。
      *
@@ -9357,10 +9389,11 @@ window.__ModuleLoader__.load({
 
         // 主通道：宿主变更流（只报告经 ctx.fs 的"被观测"写入）。
         // 失败不致命 —— 下面的兜底轮询继续工作。
+        // 0.2 要按路径订阅（传当前标签的 target）；0.1 仍是会话级两参，见 openWorkspaceFileChanges。
         if (client.remote !== undefined && client.remote.workspaceFiles !== undefined && typeof client.remote.workspaceFiles.changes === 'function') {
           ;(async () => {
             try {
-              for await (const rawFrame of client.remote.workspaceFiles.changes(sessionId, signal)) {
+              for await (const rawFrame of openWorkspaceFileChanges(client.remote.workspaceFiles, sessionId, target, signal)) {
                 if (!alive) break
                 // 变更流的帧同样可能被信封包着，防御性拆一次。
                 let frame = rawFrame

package/lib/index.js

@@ -809,6 +809,9 @@ async function applyOps(doc, ops, out, opctx) {
       if (typeof op.label === 'string') synthetic.label = op.label
       if (has(op, 'x')) synthetic.x = op.x
       if (has(op, 'y')) synthetic.y = op.y
+      // 就地插一条 addNode 紧随其后（读像素是 async 的，所以这条 op 不能在解析参数时先展开）。
+      // 注意：这里改的必须是**我们自己那份** ops —— 调用方（execute）已经 slice 过，
+      // 因为宿主给的 arguments 是深冻结的，直接 splice 会抛 "object is not extensible"。
       ops.splice(i + 1, 0, synthetic)
       notes.push(
         '🖼 ' + rawImage + ' → 逐像素矢量化：' + metrics.palette.length + ' 色 / ' + metrics.paths + ' 条 path / ' +
@@ -2900,7 +2903,13 @@ export function apply(ctx) {
       const focused = focusedPathFor(sessionIdOf(exec))
       const path =
         typeof args.path === 'string' && args.path.length > 0 ? args.path : focused !== undefined && focused.length > 0 ? focused : DEFAULT_PATH
-      const ops = Array.isArray(args.ops) ? args.ops : []
+      // **入参是宿主深冻结的**：dsh-tools 在 execute 之前把整份 arguments 深冻结
+      // （`arguments: deepFreeze(snapshotJsonValue(exec.arguments))`，见 dsh-tools 的 tool 执行器），
+      // 数组和里面的 op 对象都是 non-extensible。所以这里必须**复制成一份可扩展的数组**再用：
+      // traceImage 会往 ops 里插一条合成的 addNode（见下面 applyOps 里的 `ops.splice`），
+      // 就地改冻结数组会抛 `Cannot add property N, object is not extensible`。
+      // op 落盘语义不受影响 —— 复制出来的数组里元素仍是原来那些（本文件只读它们，从不写回）。
+      const ops = Array.isArray(args.ops) ? args.ops.slice() : []
       if (ops.length === 0) throw new Error('ops must contain at least one operation')
 
       const sessionId = sessionIdOf(exec)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-drawai",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "DSH 右侧栏的可编辑画布 + AI 语义绘图工具（diagram_apply / diagram_read），直接读写原生 .drawio 文件",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.1 <0.1.0 || >=0.1.5-rc.1 <0.2.0-0"
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.1 <0.1.0 || >=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0"
   },
   "dsh": {
     "bundle": {