Excalidraw 架构图 tokenaissance/dsh-excalidraw

dsh-excalidraw

在 DSH 侧边栏里实时展示 Excalidraw 架构图。

让智能体在 Excalidraw 里画代码架构，或者刷新它；dsh-excalidraw 会通过 Excalidraw+ MCP 服务器拉取场景，存进工作区，再由 Excalidraw 侧边栏标签页重新渲染——不用刷新页面，也不用截图。

agent ──▶ tool: excalidraw_refresh ──▶ Excalidraw+ MCP (get_scene_content)
│
▼
<cwd>/.dsh/excalidraw/<slug>.excalidraw
│ (revision bump + focus pointer)
▼
sidebar tab «Excalidraw» ◀── /excalidraw/api/* ◀── host HTTP routes

写第一行代码之前，先用 Excalidraw 画好的设计：架构图 ·侧边栏线框图

预览

原版 DSH 上的 Excalidraw 视图，与 Chat、Trajectory 并排：

原版 DSH 上的 Excalidraw 视图

同一场景，在 dsh-better-sidebar 里作为 Excalidraw 标签页：

Excalidraw 侧边栏标签页

安装

from a directory that holds this package
dsh plugin --profile desktop add "$PWD"
then restart DSH so the Host row and the client bundle load

这里的版本是纯 ESM 打包产物：安装时不需要构建（client.js 已提交）。不过 npm run build 会重新构建它，所以如果你在 src/ 里改过代码，安装前必须先重新构建。

如果这个仓库放在 LayerFS 里（tokenaissance 里就是这种情况），先把它导出到真实的主机目录——dsh plugin add 需要文件系统路径：

from a session bound to the LayerFS project
layerfs fs read main /dsh-excalidraw/... # or mount a Workspace and copy the tree out
dsh plugin --profile desktop add /path/to/exported/dsh-excalidraw

前提：Excalidraw+ MCP token。 从 Excalidraw+ 拉取场景（excalidraw_refresh、标签页上的 Refresh 按钮）需要 Excalidraw+ 账号和它的 MCP bearer token——在插件行上设置 mcpToken，或者设置 EXCALIDRAW_MCP_TOKEN，或者沿用你配置档里为 excalidraw MCP 服务器已有的 Authorization: Bearer … 请求头；为空时，工具会在 MCP 端点处失败。没有 token 时，查看器对本地已有内容仍可只读使用：.excalidraw 文件查看器能打开任意场景文件，Excalidraw 视图能渲染 <workspace>/.dsh/excalidraw/ 里已有的场景。

要求：DSH 0.2.1-rc.1+（Excalidraw 视图渲染在 DSH 自己的 conversation.view 槽位上，所以不需要第三方侧边栏）。搭配 dsh-better-sidebar 0.28+ 时，你此外，你还能获得右侧边栏标签页、.excalidraw 文件查看器、文件图标，以及自动打开焦点监听器。

交互（仅预览）

场景视图是只读查看器，但导航方式与 Excalidraw 一致：

| 手势 | 效果 |
| 拖拽（或中键拖拽） | 平移 |
| 滚轮 / 双指滚动 | 平移（按住 shift：水平方向） |
| ⌘/Ctrl + 滚轮，或双指捏合 | 以光标为中心缩放 |
| 单击 | 选中光标下最上层的元素 |
| Shift + 单击 | 将该元素加入选区或移出选区 |
| Shift + 拖拽 | 框选矩形触及的所有元素 |
| ⌘/Ctrl + A | 选中全部元素 · Esc 清除选区 |
| 双击 | 适应场景（在元素上双击：缩放到该元素） |
| + / - / 0 | 放大 / 缩小 / 回到 100% |
| Shift+1 或 Home | 适应窗口 |
| Shift+2 | 缩放到选区 |
| 方向键 | 平移 40 px |

右下角的缩放控件显示当前百分比，并提供适应窗口 / 100% 两个选项。选区以轮廓线绘制，绝不会改动场景：不能编辑、移动或调整大小。

用法

1. 让智能体刷新架构，例如 “把代码架构刷新到 Excalidraw，然后侧边栏给我看”。
智能体会带上 Excalidraw+ 场景 id 调用 excalidraw_refresh。
2. 宿主拉取 get_scene_content，写入 <cwd>/.dsh/excalidraw/architecture.excalidraw，递增修订号，并为发起调用的会话留下 focus 指针。
3. Excalidraw 标签页打开（或重新聚焦），把场景渲染成 SVG。之后的刷新会就地重新渲染；标签页可见时会轮询 /excalidraw/api/rev，所以不需要额外操作。

同一个侧边栏服务还附带这些功能：

- 任何 .excalidraw 文件都会在侧边栏中作为图表打开（只读），而不是显示原始 JSON；旧版 .excalidraw.json 场景仍可通过 Excalidraw 标签页读取（better-sidebar 只对有 head 的文件嗅探内容，所以这些文件仍会在 JSON 预览中打开）；
- 文件树会为这些文件显示图表图标；
- 标签页自带的 Refresh 按钮会重新拉取上次存储的场景。

工具

| 工具 | 参数 | 效果 |
| excalidraw_refresh | { sceneId?, name?, slug? } | 从 Excalidraw+ 拉取场景到工作区存储；返回 { ok, slug, file, sceneId, elements, revision, opened } |
| excalidraw_open | { slug? } | 为已存储的场景聚焦 Excalidraw 标签页 |
| excalidraw_export | { slug?, format? } | 把场景写成 <scenesDir>/<slug>.svg（PNG 由标签页的按钮生成，在浏览器里栅格化） |

标签页没有插件本地设置：自动打开跟随宿主的 autoOpen，轮询间隔是宿主的 pollIntervalMs（通过 /rev 下发给客户端）。

字体

插件内置了可再分发的 Excalidraw 网页字体——Comic Shanns（MIT）、Virgil（SIL OFL）和 Lilita One（SIL OFL）——并从包内提供，因此场景中的手绘文字能按 Excalidraw 的绘制方式渲染，无需任何第三方请求。Excalifont（Excalidraw 自带的默认字体）不包含在内，因为它没有附带许可授权；使用它的场景会回退到浏览器的字体栈。参见 fonts/README.md 和 docs/FIDELITY.md。

配置（cordis 行 config）

| 键 | 默认值 | 含义 |
| mcpUrl | https://api.excalidraw.com/api/v1/mcp | Excalidraw+ MCP 端点 |
| mcpToken | '' | bearer token；为空时回退到 EXCALIDRAW_MCP_TOKEN，再回退到配置档自己的 mcp-excalidraw 行 |
| scenesDir | .dsh/excalidraw | 场景目录，相对于会话工作区 |
| extraFontsDir | '' | 可选目录，存放用户自备字体（fonts.json + 字体文件）；会提供给标签页，导出时也会用到——这是添加 Excalifont 的合法方式 |
| pollIntervalMs | 1500 | 客户端轮询修订号的间隔（500–10000） |
| autoOpen | true | 刷新后打开/聚焦标签页 |
| maxSceneBytes | 4194304 | 拒绝更大的场景文件 |

构建方式

- 宿主部分（index.js + lib/）：一个 cordis 插件，注册七条 HTTP 路由外加 /excalidraw/fonts/ 前缀、三个模型工具，以及按工作区隔离的场景存储，写入原子化，修订号单调递增。零运行时依赖；Excalidraw MCP 客户端就是普通的 fetch + 基于 streamable HTTP 的 JSON-RPC。
- 客户端部分（client.js，由 scripts/build-client.mjs 从 src/client.mjs + src/renderer.mjs + src/fonts-data.mjs 生成）：一个 window.__ModuleLoader__.load 模块，把场景视图挂到两个界面上——DSH 原生的 conversation.view 槽位（Chat/Trajectory 旁边的 Excalidraw 视图，所以原版 DSH 也能用），以及存在时的 dsh-better-sidebar 标签页，连同它的文件查看器和文件图标。
- 渲染器（src/renderer.mjs）：纯函数、确定性的 Excalidraw→SVG 转换，只覆盖绘图工具会产出的那部分元素；不依赖 @excalidraw/。

设计见 docs/DESIGN.md，规范性通信契约见 docs/CONTRACT.md，各部分实现说明见 docs/HOST-NOTES.md / docs/CLIENT-NOTES.md / docs/RENDERER-NOTES.md。

从别处发布 / 安装

- 任意 DSH： 设置 → 插件 → 添加插件*，接受本地目录、.tgz 或 Git URL；命令行等价写法是 dsh plugin --profile desktop add 。
- npm： npm publish --access public，然后按包名安装（dsh plugin --profile desktop add dsh-excalidraw）。
- 社区目录： 在 awesome-dsh-plugin 里加一条 YAML 条目（data/plugins/<owner>__<repo>.yml）；合并后市场和 插件 → 发现 会自动收录。

具体命令、目录条目和发布前检查见 docs/PUBLISHING.md。

测试

npm test # node --test test/ (212 tests, zero deps) — it does NOT rebuild:

陈旧的 client.js 会故意让构建签名测试失败

npm run build # 重新生成 src/fonts-data.mjs 和 client.js
node scripts/render-scene.mjs test/fixtures/design-scene.json /tmp/design.svg

渲染器会对照同一场景的 Excalidraw 渲染参考结果做检查（墨迹覆盖率和宽高比），store 和 MCP 客户端有单元测试，宿主路由逐个 handler 跑过，客户端模块则通过打桩的模块加载器加载。

限制（v1）

只读：编辑仍然在 Excalidraw 里做（查看器支持平移、缩放、选择和框选，但从不把场景写回）。roughness/hachure 按干净样式渲染；image 元素只从场景 files 里已有的 data:image/…;base64, URL 渲染；不从网络拉取任何内容。Excalidraw 的字体不随包发布，所以 family 5（Excalifont）用随包发布的 Virgil 回退字体渲染，Excalidraw 自己的技术栈也是这么做的；family 2/3/4/6 回退到浏览器字体栈。Comic Shanns（8）、Virgil（1）和 Lilita One（7）随包发布。