手绘画布 Jegozhou/dsh-excalidraw

DSH Excalidraw

一个原生 DeepSeek Harness 插件，把 Obsidian Excalidraw 的核心绘图能力带进 Harness：真实可交互的 Excalidraw 画布、带修订围栏的 .excalidraw 文件持久化，以及带类型的智能体工具，用来创建和编辑用户正在看的同一份场景。

中文摘要：本项目不是把 Obsidian 插件整体搬进 Harness，也不是桥接 Obsidian。它用 MIT 许可的上游 Excalidraw 渲染器 + 原创的 MIT 场景核心，实现 Harness 原生插件：可交互画布、带修订号与幂等重试的文件持久化、5 个带 JSON Schema 与权限边界的 Agent 工具。仓库包含原始源码证据、三方案对比、ADR、黄金语料、56 个自动化测试、13 步真实浏览器 E2E 和真实 Host 工具调用探针。详见 docs/00-index.md。

Harness 内的 Excalidraw 页面，含矩形、箭头和输入的文字

状态

- 版本： 0.1.0（MVP，架构与验证已完成）
- 目标： DeepSeek Harness 0.2.1-rc.2（已实测），使用 Harness 0.2.x 客户端模块加载器的插件契约
- 渲染器： @excalidraw/excalidraw@0.18.1（MIT），React 18 来自 Harness 页面模块表
- 验证： 56 个自动化 Host/核心测试、13 步真实浏览器 E2E、5 个智能体工具在真实隔离的 Harness Host 内执行、用 MIT Excalidraw 运行时生成的黄金语料
- 这是什么： 可安装的 DSH 插件，以及 DSH 原生的绘图编辑器
- 这不是什么： Obsidian 桥接、独立 Web 应用，也不是 AGPL Obsidian 插件的副本

功能

| 能力 | 实现 | 证据 |
| 通过官方插件机制安装 / 加载 / 卸载 / 配置 | cordis.patch.yml 里一行 bundle；每个资源都是 ctx.effect；配置在 apply 中钳制 | 平台证据、生命周期测试、验证 |
| 查看并交互编辑支持的 Excalidraw 场景 | 真正的 @excalidraw/excalidraw 组件注册进 Harness main 面板，并带侧边栏入口 | 渲染探针、E2E 截图 |
| 智能体通过带类型、带权限的工具创建 / 读取 / 修改绘图 | 五个 JSON Schema 工具，背后是与 UI 共用的同一服务 | 智能体探针、契约 |
| 可靠的保存、重新打开与结构保真 | 原子写入 + fsync + 回读哈希校验、sidecar 修订号、幂等请求 id、冲突恢复、备份恢复 | 存储测试、E2E、黄金语料 |

架构

┌──────────────────────────── Harness page (browser) ────────────────────────────┐
│ sidebar.panellist icon ──► main panel: ExcalidrawPage │
│ ├─ genuine Excalidraw canvas (React 18) │
│ ├─ scene list, save, conflict banner │
│ └─ 同源 fetch（会话 cookie） │ └───────────────────────────────────────┬────────────────────────────────────────┘ │ /dsh-excalidraw/api/* (connection fence) ┌───────────────────────────────────────▼────────────────────────────────────────┐ │ Host half (Cordis plugin, Node) │ │ ExcalidrawService ── SceneStore (atomic + revision + lock + backups) │ │ │ │ │ │ ├─ 5 agent tools └─ <DSH_HOME>/excalidraw/drawings/.excalidraw │ │ └─ /dsh-excalidraw/assets/ (fonts, locale chunks, CSS) │ └────────────────────────────────────────────────────────────────────────────────┘

一个 npm 包里装两半：
- Host（lib/index.js）：场景存储、HTTP API、资源路由、智能体工具。零运行时依赖，只用 Node 内置模块。
- Client（lib/client.js）：loader 格式的 bundle（window.__ModuleLoader__.load({id, factory(require)})），React 走 external。里面是 Excalidraw 0.18.1、页面 UI 和样式表文本。

安装

构建好的 lib/ 和 assets/ 目录已提交，安装不需要构建步骤，也不需要联网。

DSH Desktop / 插件管理器 —— 把仓库目录作为 bundle 安装：

plugin_manager install_bundle target: /absolute/path/to/dsh-excalidraw

或者在某个配置档里用命令行：

dsh plugin --profile <profile> add /absolute/path/to/dsh-excalidraw

bundle 会把 dsh-excalidraw 加进 dsh.profile.bundles。新装的包可能需要重启 Harness；插件管理器会报 restart-required 并说明原因。重启后，在左侧边栏打开 Excalidraw。

配置

cordis.patch.yml 里那一行暴露了可调项；用户覆盖写进配置档自己的 cordis.patch.yml。

- id: dsh-excalidraw
name: 'dsh-excalidraw'
config:
drawingsDir: '' # default: <DSH_HOME>/excalidraw/drawings
maxSceneBytes: 16777216 # 1 MiB .. 64 MiB
maxElements: 5000 # 1 .. 20000
maxFiles: 64 # 0 .. 256
maxTextLength: 20000 # 100 .. 100000

这里故意没写 engines.dsh 版本范围：插件只在 0.2.1-rc.2 上验证过，加一个没测过的范围等于宣称证据覆盖不到的兼容性。

使用

人

1. 点侧边栏里的 Excalidraw。
2. 输入小写的场景名，点 New scene。
3. 用 Excalidraw 工具栏画图；Save（或 Cmd/Ctrl+S）写入文件。
4. 如果智能体或别的写入方改过场景，保存时会返回冲突横幅：Reload from disk 保留对方的版本，Overwrite anyway 把你的版本写成下一个修订。

智能体

配置档里的每个智能体都能看到这五个工具：

| 工具 | 用途 | 关键参数 |
| excalidraw_scene_list | 发现场景 | — |
| excalidraw_scene_read | 读取场景 + 修订号 + sha256 | name、include（full/summary）、element_type |
| excalidraw_scene_create | 用带类型的元素创建场景 | name、elements、app_state、files、request_id |
| excalidraw_scene_apply | 在修订号栅栏下原子地增删改 | name、expected_revision、operations、app_state、request_id |
| excalidraw_scene_validate | 校验任意 .excalidraw 文档 | scene |

模型应遵循的示例调用顺序：

1. excalidraw_scene_list
2. excalidraw_scene_read { name: "architecture" } -> revision 7, sha256 ...
3. excalidraw_scene_apply {
name: "architecture",
expected_revision: 7,
request_id: "agent-2026-10-28-1",
operations: [
{ op: "add", element: { id: "api", type: "rectangle", x: 40, y: 40, width: 160, height: 90, backgroundColor: "#a5d8ff" } },
{ op: "add", element: { type: "text", x: 40, y: 150, text: "API" } },
{ op: "add", element: { type: "arrow", x: 210, y: 80, points: [[0,0],[140,40]], startElementId: "api" } }
]
}
4. excalidraw_scene_read { name: "architecture" } -> revision 8

以下规则由 Host 强制执行，不靠提示词约束：
- 场景名必须符合严格的文件名字符集；不允许路径，不允许符号链接。
- apply 要求传入最近一次读取返回的修订号。并发写入会返回 revision_conflict，并附带当前修订号和 sha256。
- 操作要么全部成功，要么全部失败；只要有一个元素不合法或绑定悬空，整个调用就会被拒绝。
- 重复的 request_id 会返回已提交的修订号，并带上 duplicate: true，不会再次改动数据。
- 只有字节写入、fsync、回读、解析、哈希校验全部完成后，保存才返回成功。

数据模型与兼容性

- 格式： 纯 .excalidraw JSON（type: "excalidraw"、version: 2）—— 就是 Excalidraw 自己保存的格式。
- 可创建的元素： rectangle、ellipse、diamond、arrow、line、text、freedraw、image（配合 files 的 data-URL 映射）。
- 可读取/保留的元素： 上述元素，外加 frame、magicframe、embeddable、iframe；这些元素上未知但格式正确的字段会原样保留。
- 不支持： Obsidian 的 .excalidraw.md Markdown 封装、Obsidian 脚本引擎、PDF/Mermaid 转换、素材库、协作/加密，以及非图片附件。见兼容性说明。
- 修订元数据存放在 <drawings>/.dsh-excalidraw/ 下，不写进 .excalidraw 文件，因此绘图始终可移植。

验证

pnpm install # dev tooling only; installation of the plugin does not need it
node scripts/verify.mjs # typecheck + build + 56 unit/integration tests + packaging checks

本仓库中的证据：
- 验证报告 —— 测试清单、确切命令、结果。
- E2E 报告 — 在真实 Chrome 中针对隔离的 Harness 跑完 13 步：创建，用真实输入画矩形、箭头、文本，保存，校验字节、哈希、元数据，重新加载，外部写入方冲突，覆盖，重新打开。
- 智能体探测报告 — 通过真实 Host 工具注册表调用五个工具：创建、读取、应用、幂等重试、过期 fence、非法名称、校验、磁盘哈希比对。
- 验证记录 — 完整的一次通过运行。
- 渲染预研 — 为什么选择嵌入真正的 Excalidraw 画布。

E2E 测试需要有一个隔离的 Harness 在运行；它刻意不放进 verify，这样例行检查永远不会碰到用户的实时配置档。复现步骤见 test/e2e/README.md。

架构决策与对比

- 方案对比 — A（桥接 Obsidian 命令行）、B（完整移植）、C（共享绘图核心 + DSH 原生适配层），附实测或引用的结果。
- ADR-0001 — 采纳的设计（C 形拆分：MIT 的 Excalidraw 渲染器 + 原创场景核心 + DSH 原生宿主），以及明确放弃的路线。
- 上游证据 — Obsidian 插件的固定提交与 file:line 调用路径。
- DSH 平台证据 — 插件、工具、客户端加载器和传输层的精确契约。
- 许可证审计 — 上游 AGPL/MIT 的矛盾、哪些没有复制、我们接受哪些义务。

许可证

插件的原创代码和场景核心是 MIT（见 LICENSE）。浏览器部分打包了 MIT 许可的 @excalidraw/excalidraw@0.18.1 及其 MIT/ISC/Apache/0BSD 依赖闭包；上游 Obsidian 插件没有复制，其 AGPL/MIT 元数据矛盾已记录在案，没有悄悄抹平。字体二进制文件从 Excalidraw 发行版原样分发，其内嵌许可证记录在 THIRD_PARTY_NOTICES.md。

坦率说明的限制

- 客户端包 8.0 MiB（gzip 后 2.39 MiB）。页面启动时要拉取、解析并执行它。已验证可用，但这是目前已知的最大开销；按包内 client.<name>.js 分块是 v0.2 的第一项任务。
- .excalidraw.md（Obsidian 的现代封装格式）不在范围内；只读写纯 .excalidraw JSON。
- 智能体生成的文本，宽度用确定性近似计算，不用浏览器度量；Excalidraw 打开时会重新测量。智能体创建的场景里的文本，可能和手绘文本差几个像素。
- UI 刻意只持久化一小部分 appState（viewBackgroundColor、gridSize、网格模式）。缩放、滚动和主题不存进文件。
- 跨进程安全靠锁文件实现，并带过期恢复；它不是分布式锁，不适用于网络文件系统。
- 首次安装时，正在运行的 Desktop 配置档会收到 restart-required；插件是在另一个隔离配置档里完整跑通的，没有重启你正在读这段话的会话。
- 没有执行由模型驱动的「自然语言 → 工具调用」对话，因为隔离配置档没有模型凭据；工具本身由一个探针 bundle 通过真实的 Harness 工具注册表执行（证据）。剩下的一环是模型选择调用工具，这一环由 Harness 负责。