前言¶

在 DeepSeek Harness（DSH）里做架构说明、流程图或协作草图时，常见做法是贴截图、写 Markdown，或让 Agent 输出 Mermaid 等文本格式。这些方式要么不能直接在 Harness 里交互编辑，要么和你在界面上看到的内容不是同一份数据。社区插件 dsh-excalidraw（维护者 Jegozhou）把 MIT 许可的上游 @excalidraw/excalidraw 渲染器与自研场景存储接到 Harness 官方插件机制上：人在侧边栏打开真实画布编辑，Agent 通过带 JSON Schema 与权限边界的工具读写同一套 .excalidraw 文件。它不是 Obsidian Excalidraw 插件的搬运或桥接，也不是独立 Web 应用。

这是什么¶

dsh-excalidraw 是可安装的 DSH 原生插件（server 类 Cordis bundle + Web 客户端注入）。当前版本 0.1.0（README 标注为 MVP，架构与验证已完成），在 DeepSeek Harness 0.2.1-rc.2 上做过 live 验证；渲染器为 @excalidraw/excalidraw@0.18.1（MIT），React 18 来自 Harness 页面模块表。仓库采用 MIT 许可证，GitHub：https://github.com/Jegozhou/dsh-excalidraw；社区目录页：https://www.skillhub.cn/plugins/Jegozhou/dsh-excalidraw（独立站点，与 DeepSeek / 幻方无官方从属关系）。

核心功能¶

下面按 README 中的能力表归纳，每项在仓库文档与测试中有对应证据（如 docs/08-verification.md、单元/E2E 测试等）。

插件生命周期与配置¶

通过官方插件机制安装、加载、卸载与配置：cordis.patch.yml 中一条 bundle 行，资源以 ctx.effect 注册，配置在 apply 中做 clamp。

可交互画布¶

在 Harness main 面板注册 genuine Excalidraw 组件，侧边栏有 Excalidraw 入口；支持查看与编辑 Excalidraw 所支持的场景类型。

持久化与并发¶

场景以 plain .excalidraw JSON（type: "excalidraw", version: 2）存于默认目录 <DSH_HOME>/excalidraw/drawings/*.excalidraw。Host 侧 SceneStore 提供原子写入、fsync、读回 hash 校验、sidecar revision、幂等 request_id、冲突与备份恢复。人机保存若遇并发修改，界面会提示 Reload from disk 或 Overwrite anyway。

五个 Agent 工具¶

与 UI 共用 ExcalidrawService，对 profile 内 Agent 可见：

Host 端 HTTP：/dsh-excalidraw/api/*；静态资源：/dsh-excalidraw/assets/*。仓库自述含 56 个自动化 Host/core 测试、13 步真实浏览器 E2E、真实 Host 内 Agent 工具探针等验证材料。

安装与启用¶

仓库已提交构建产物 lib/ 与 assets/，安装无需本地 build、也无需联网拉依赖。

方式一：DSH Desktop / 插件管理器 — 将仓库目录作为 bundle 安装：

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

方式二：CLI（指定 profile）：

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

安装后 bundle 会写入 dsh.profile.bundles。新装包可能提示 restart-required，需重启 Harness；重启后在左侧侧边栏打开 Excalidraw。

配置项¶

可在 profile 自带的 cordis.patch.yml 中覆盖插件默认值（字段来自 bundle 内 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

README 说明尚未声明 engines.dsh 版本区间，因兼容性证据目前仅覆盖 0.2.1-rc.2。

典型用法¶

人工编辑¶

1. 点击侧边栏 Excalidraw。
2. 输入小写场景名，点 New scene。
3. 用 Excalidraw 工具栏绘制，Save 或 Cmd/Ctrl+S 写盘。
4. 若 Agent 或其他写入方已改场景，按冲突横幅选择重载或强制覆盖为下一 revision。

Agent 改图（README 示例序列）¶

先 list，再 read 拿到 expected_revision，再 apply，最后 read 确认 revision 递增。Host 强制：场景名符合严格文件名字符集；apply 必须带最近一次 read 的 revision，并发写返回 revision_conflict；操作全成功或全拒绝；重复 request_id 返回 duplicate: true 且不重复变更。

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

创建元素类型包括 rectangle、ellipse、diamond、arrow、line、text 等（以 README 完整列表为准）。

适用场景与注意¶

适合谁： 已在 DSH 0.2.x 环境工作、需要「人画 + Agent 改」同一份 Excalidraw 文件、并看重 revision 与持久化语义的用户或插件作者。

运行与权限： 插件以当前 DSH Host 进程权限运行，可读写配置的 drawings 目录并通过 API 暴露工具；安装前应阅读源码、LICENSE 与 THIRD_PARTY_NOTICES.md，确认符合你的安全与合规要求。

边界： 不是 AGPL 的 Obsidian Excalidraw 插件拷贝；不声称未验证的 DSH 版本兼容。Node 引擎要求 >=22.5（见 package.json）。

结尾¶

dsh-excalidraw 在 Harness 内提供真实 Excalidraw 画布、带修订栅栏的 .excalidraw 持久化，以及五个 typed Agent 工具，并用测试与文档留证。进一步了解实现与验证索引见仓库 docs/00-index.md。

• 目录页：https://www.skillhub.cn/plugins/Jegozhou/dsh-excalidraw
• GitHub：https://github.com/Jegozhou/dsh-excalidraw