dsh-drawai

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 的右侧栏，再给模型两个工具；两者读写的是同一份文件。

• 画布（右侧栏面板） —— 打开工作区里的 .drawio：画节点、连边、就地改字、分层、排序、对齐、导出，双击节点就能改标签。
• diagram_apply —— 模型改图的入口：15 个结构化 ops，改完自动布局并原子写回。
• diagram_read —— 模型的眼睛：结构、样式键、图层、父级、页面尺寸、你此刻的选区、文件指纹 revision。
• 选中与回退 —— 你在画布上选中什么，模型就知道什么；模型的改动最多可以退 8 步。
• 载体是原生 .drawio 文件 —— 不需要导入导出，存出来的文件可以直接用 drawio / diagrams.net 打开继续编辑。

人（侧边栏画布）      ┐
AI（diagram_apply）  ├──→  工作区的 .drawio（mxfile）  ──→  用 drawio / diagrams.net 直接打开继续编辑
drawio 本体           ┘         ↑ 无损写回：画布读不懂的单元逐字节保留

安装 / Install

dsh plugin --profile web add github:fourzkw/dsh-drawai

然后重启 dsh web —— 宿主侧只在启动时加载，这一步不能省。

更新：从 GitHub 安装的包，重新执行上面这条命令即可。等发布到 npm 之后，才会有 dsh plugin --profile web update dsh-drawai@latest 这种按版本更新的写法。

重启之后，你会看到：

装好后的变化	出现在哪里
「DrawAI 画布」面板，负责打开 **/*.drawio	右侧栏
diagram_read / diagram_apply	模型工具集
drawai-canvas 技能	会话技能目录（模型按需取全文）

• 仓库里没有 prepare / postinstall 脚本，lib/ 是已提交的构建产物 —— 从 GitHub 源码安装不需要 allowBuilds 构建授权。
• 还没有发布到 npm，所以 dsh plugin add dsh-drawai 这种预构建安装暂时用不了，请用上面的 GitHub 形式。
• 手动挂载的兜底写法，以及本地 link 的开发做法，见设计文档的「安装」一节。

使用 / Usage

一块画布、两个工具、一份文件：人改的、模型改的、drawio 改的，最后都落在同一个 .drawio 上。

入口	你能得到什么
右侧栏画布	打开或新建画布、画节点与连线、就地改字、图层、顺序、多选对齐、复制粘贴、导出 SVG / PNG
diagram_apply	让模型按 ops 改图：增删改、重接边、复制、排序、分层、导出；支持 ids 批量、as 别名、expectRevision
diagram_read	让模型看见图的结构与样式、图层与父级、页面尺寸、你此刻的选区、文件指纹 revision
选中与回退	你选中什么模型就知道什么；模型的每一轮改动都能在界面上退回去

🗂️ 画布面板 / The canvas panel

刚打开面板时它是空的（不会替你预开一张图）：用 文件 → 新建画布… 或 文件 → 打开…（列出工作区里所有 .drawio）开始。

功能	它解决什么问题
画布外观	9 种形状（矩形 / 圆角 / 椭圆 / 菱形 / 圆柱 / 文档…）、8 色调色板、白纸 + 网格、正交折线 + 障碍避让、明暗切换
文本	双击节点就地改字；「T 文字」放一段无边框、无底色的独立文字；字号有 10 / 12 / 14 / 18 / 24 五档，也可以手调 8–72；字色板
连线	四选一画法（直线 / 直角折线 / 圆角折线 / 曲线）× 线型（含虚线间距）× 箭头（单向 / 双向 / 无 / 反向）× 颜色 × 引出段长度；自环；悬空端（从节点脱开后成为自由端点，还能再拖回去）
连线上的文字	双击改、按住拖（半格 + 贴线吸附）、右键「标签居中」；线在文字的位置真的断开（不盖白底）
选中与移动	框选 / Shift 加选 / Ctrl+A；整体拖动（折点与自由端点跟着同一个位移走）；对齐辅助线；多选对齐与分布
图层	列出 / 新建 / 显示隐藏 / 设为当前层；隐藏状态会写入文件（用 drawio 打开同样是隐藏的），层里的单元一个字节都不动
顺序	置顶 / 上移 / 下移 / 置底 —— 写回时真的改动文件里单元的先后（否则重新打开就变回去了）
自定义数据	右键「编辑数据」，按 key=value 一行一项改单元属性；按 user object 存回文件，drawio 打开不会丢
导出	SVG / PNG(2×)；「看一眼画布效果」走 DSH 附件服务，不在工作区落文件
回退	「编辑 → 撤销 AI 改动」最多可以连着退 8 步

🤖 两个工具 / The two tools

diagram_apply —— 模型怎么改图

结构化 ops，改完自动布局并原子写回（布局默认 dagre-tb，另有 dagre-lr / grid / none）：

类别	ops
增删	addNode addEdge remove duplicate
修改	setLabel setLabelPos setStyle setEdge move
结构	addLayer setLayer setLayerProps order
交互	highlight（让画布替你选中，不改文档、不重排）
输出	export（svg 落在 .drawio 旁边；png 走浏览器下载）

• 批量修改：setStyle / setLabel / move / remove 都接受 ids:[…]，不必发 N 个 op。
• expectRevision：把上次 diagram_read 返回的 revision 传进来 —— 对不上（说明你在 drawio 里同时改过）就报错，且一个字节都不写，重读再改。
• 写盘之前就报错：边引用了不存在的节点会直接失败，并列出已知 id。
• 不动手工摆好的版面：ops 里自带几何时（addNode 给了 x/y，或者有 move）不会重排 —— 否则"挪 40px"会被布局立刻冲掉。

diagram_read —— 模型怎么看见图

读回：节点 / 边 / 标签、每个单元的样式键（就是文件里那串 style，另外给出派生的形状、线型、箭头、颜色名便于阅读）、图层表与单元所属层、容器父级 parent、页面尺寸、边标签的 labelX/labelY、revision（文件内容指纹）、当前选区。

• 可以只读一层（layer）或只看几个单元（ids）—— 大图上能省下不少上下文；过滤时会同时报 totalNodes / totalEdges，免得漏看。
• render:true 会让画布把当前画面渲成 PNG 交给模型"看一眼"；图片走 DSH 的附件服务，不在工作区落任何文件。

让模型少猜的三条通道

通道	它解决了什么
选区上报	你在画布上选中什么，模型读得到 —— "把这几个改一下"里的"这几个"（按文件配对、按存在过滤）
当前画布	不传 path 时默认就是你正打开的那张；切换标签页会主动告诉模型换成了哪张
结构化返回 + 别名	返回的 created / changed / removed 都带 id，不必解析自然语言；{op:'addNode', as:'start'} 之后，同一个 ops 数组里就能直接 from:'start'

一段典型的对话是这样的：

你：画一张登录流程图，三条分支
模型：diagram_apply(addNode×5 + addEdge×5 + layout:'dagre-tb')
      → 写回 docs/登录流程.drawio，返回 created / changed / removed（含自动分配的 id）

你：（在画布上框选两个节点）把这两个换成绿色
模型：diagram_read → 看到 selection:["n3","n5"] → diagram_apply(setStyle, ids:["n3","n5"], style:"green")

你：这张图导出一份给我
模型：diagram_apply(export, format:"svg") → 渲染在浏览器侧执行，SVG 落在 .drawio 旁边

📄 载体：原生 .drawio 文件 / Native .drawio files

不需要导入导出，也不把你锁在私有格式里。 画布读写的就是 .drawio 本身（drawio 的 mxfile）， 所以同一份文件可以直接用 drawio / diagrams.net 打开接着改，改完回到画布上也照样能编辑。

难点不在读，在写。 这个格式能表达的东西比本画布多（多页、分组层级、图片、HTML 标签、自定义属性、旋转翻转、页面设置…）， 而本画布只理解其中一个子集。如果写回是"按模型重新生成整份 XML"，用户稿子里我们不理解的部分就会在保存时被悄悄删掉 —— "悄悄"是最糟的失败方式（用户以为在编辑，其实在删）。所以写回做的是外科手术：

规则	说明
页 1 的 <root> 之外	其他页、mxfile 属性 —— 逐字节保留
我们拥有的单元（节点 / 边）	只重写 value / style / 几何 / 端点这几处属性，其余原样
我们不认识的单元	原样留着，不因为不认识就删
只有"导入过、模型里又没了"的单元	才删 —— 那才是用户真的删掉了它
压缩形态	原本压缩的页体，写回后依然压缩

由此得到一条可以断言的性质：打开后原样保存，文件逐字节不变（tools/check-mxfile.mjs 里有断言盯着）。

读不懂的地方一律如实报。 多页只显示第 1 页、分组按绝对位置显示、图片按矩形显示 —— 这些会作为 notes 出现在工作栏和 diagram_read 的返回里。用户会拿这份文件继续在 drawio 里编辑，不说明就等于骗人。

revision 不是时间戳，而是文件内容的指纹 —— 所以无论 drawio 还是别的编辑器改过文件，乐观锁照样准。

画布是自己实现的：纯 SVG + DOM，没有 iframe，也不依赖任何外部编辑器资源。换来的是每个单元都有 id / layer / parent、选区能上报给模型、写回是逐单元的、画布本身能被模型驱动；代价是只覆盖这个格式的一个子集。

⚙️ 配置与默认值 / Configuration

目前还没有设置页：下面这些默认值都写在代码里；能通过 AI 侧改的，在右列给出等价做法。

现在的默认值	怎么改
自动布局默认 dagre-tb	diagram_apply 的 layout: 'dagre-lr' / 'grid' / 'none'
节点与独立文字默认字号 12、连线 10	画布右键「字号」，或 ops 的 fontSize:18（null = 删键回缺省）
缺省线型（实线、单向箭头、直角折线）	画布右键，或 ops 的 dash / arrow / line
像素格 10px、吸附半格 5px	菜单「整理几何（吸附到格线）」做一次性对齐
主题跟随 DSH 的明暗	——
显示层、当前层	「图层」菜单（会写进文件）

须知 / Good to know

• 兼容性：DSH（DeepSeek Harness）Web；官方包以 peerDependencies 声明（@deepseek-ai/dsh-tools），Node >= 20。
• 生效方式：宿主侧只在 dsh web 启动时加载，换 lib/index.js 必须重启；客户端是独立 bundle，刷新页面即可。
• 界面语言：目前只有简体中文，还没有 i18n。
• 大图性能：几百个单元时的重渲染与路由开销还没测过。
• 数据与网络：插件只读写工作区里的 .drawio 文件；不发网络请求、不读凭据，也没有安装期脚本。

已知限制 / Limitations

• 图层只到 v1：画布菜单里还不能锁定、重命名、删除图层，也不能把选中单元移到别的层（AI 侧可以用 setLayer 做到）。
• 分组与多页：文件里的层级与其余页逐字节保留，但画布按绝对位置拍平显示，只显示和编辑第 1 页。
• 所有边都画在所有节点下面（文件里是按单元顺序混合层叠的）；绕法是把那条边放进更上面的一层。
• 独立 edgeLabel 单元只读；entityRelation 等其它 edgeStyle、箭头字形、旋转 / 翻转 / 透明、stencil 形状只保留、不渲染；.drawio.svg / .png / .html 内嵌载体不支持。
• 导出只有 SVG 与 PNG(2×)：没有 PDF，也不能"只导出选中部分"。
• 交互细节：没有方向键微移、没有查找；对齐辅助线只跟节点比（不与折点、端点对齐）；单条选中的连线不能复制。

完整的取舍与实现细节在 docs/design.md。

开发 / Development

npm run watch   # 常驻：监听 src/，变化即重建 lib/
npm run build   # 一次性构建
npm run check   # 安装前烟测（含 lib 与 src 是否同步）
npm test        # 五份自测（mxfile 编解码 / 路由预览 / 宿主行为 / 渲染 / 组件），1472 项断言

⚠️ 绝不改 lib/ 下的文件 —— 它们是构建产物，会被覆盖。改 src/。 npm test 需要包能解析到 @deepseek-ai/dsh-tools，本机自测要先建一个 junction（写法在 docs/design.md 的「烟测」一节）。

目录结构，以及两侧各自的生效路径，见 docs/design.md 的「目录」一节。

觉得有用？ / Like it?

如果这块画布帮上了忙，欢迎在 GitHub 上点个 ⭐；issue 与 PR 同样欢迎。

License

MIT