dsh-excalidraw
作为原生 DeepSeek Harness 插件的 Excalidraw 核心功能：交互式场景编辑、可靠的 .excalidraw 持久化和类型化代理工具。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Jegozhou/dsh-excalidraw#02ff68df28247779f60925218f92fc8d76bf46ab
Excalidraw 以 dsh-excalidraw 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A native DeepSeek Harness plugin that brings the core drawing capabilities of Obsidian Excalidraw to the Harness: a real, interactive Excalidraw canvas, durable .excalidraw file persistence with revision fences, and typed agent tools that create and edit the same scenes the person is looking at.
中文摘要：本项目不是把 Obsidian 插件整体搬进 Harness，也不是桥接 Obsidian。它用 MIT 许可的上游 Excalidraw 渲染器 + 原创的 MIT 场景核心，实现 Harness 原生插件：可交互画布、带修订号与幂等重试的文件持久化、5 个带 JSON Schema 与权限边界的 Agent 工具。仓库包含原始源码证据、三方案对比、ADR、黄金语料、56 个自动化测试、13 步真实浏览器 E2E 和真实 Host 工具调用探针。详见 docs/00-index.md。
The Excalidraw page inside Harness, with rectangle, arrow and typed text
@excalidraw/excalidraw@0.18.1 (MIT), React 18 from the Harness page module table| Capability | Implementation | Evidence |
|---|---|---|
| Install / load / unload / configure through the official plugin mechanism | One bundle row in cordis.patch.yml; every resource is a ctx.effect; config clamped in apply | platform evidence, lifecycle tests, verification |
| View and interactively edit supported Excalidraw scenes | Genuine @excalidraw/excalidraw component registered in the Harness main panel, with a sidebar entry | render spike, E2E screenshots |
| Agent creates / reads / modifies drawings through typed, permissioned tools | Five JSON-Schema tools backed by the same service the UI uses | agent probe, contract |
| Reliable save, reopen, and structural fidelity | Atomic write + fsync + read-back hash verification, sidecar revision, idempotent request ids, conflict recovery, backup recovery | store tests, E2E, golden corpus |
┌──────────────────────────── Harness page (browser) ────────────────────────────┐
│ sidebar.panellist icon ──► main panel: ExcalidrawPage │
│ ├─ genuine Excalidraw canvas (React 18) │
│ ├─ scene list, save, conflict banner │
│ └─ same-origin fetch (session 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) │
└────────────────────────────────────────────────────────────────────────────────┘
Two halves in one npm package:
lib/index.js): scene store, HTTP API, asset route, agent tools. Zero runtime dependencies; Node built-ins only.lib/client.js): the loader-format bundle (window.__ModuleLoader__.load({id, factory(require)})) with React external. It contains Excalidraw 0.18.1, the page UI, and the stylesheet text.The built lib/ and assets/ directories are committed, so installation needs no build step and no network.
DSH Desktop / plugin manager — install the repository directory as a bundle:
plugin_manager install_bundle target: /absolute/path/to/dsh-excalidraw
Or from the CLI in a profile:
dsh plugin --profile <profile> add /absolute/path/to/dsh-excalidraw
The bundle adds dsh-excalidraw to dsh.profile.bundles. A newly installed package may require a Harness restart; the plugin manager reports restart-required with the reason. After restart, open Excalidraw in the left sidebar.
The row in cordis.patch.yml exposes the tunables; user overrides belong in the profile's own 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
There is deliberately no engines.dsh range yet: the plugin was verified on 0.2.1-rc.2 and adding an untested range would claim compatibility the evidence does not cover.
Cmd/Ctrl+S) writes the file.The five tools are visible to every agent in the profile:
| Tool | Purpose | Key arguments |
|---|---|---|
excalidraw_scene_list | Discover scenes | — |
excalidraw_scene_read | Read scene + revision + sha256 | name, include (full/summary), element_type |
excalidraw_scene_create | Create a scene from typed elements | name, elements, app_state, files, request_id |
excalidraw_scene_apply | Atomic add/update/delete under a revision fence | name, expected_revision, operations, app_state, request_id |
excalidraw_scene_validate | Validate an arbitrary .excalidraw document | scene |
Example sequence the model is expected to follow:
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
Rules enforced by the Host, not by prompt text:
apply requires the revision returned by a recent read. A concurrent write returns revision_conflict with the current revision and sha256.request_id returns the committed revision with duplicate: true and does not mutate again..excalidraw JSON (type: "excalidraw", version: 2) — the format Excalidraw itself saves.files data-URL map).frame, magicframe, embeddable, iframe; unknown well-formed fields on those elements are preserved..excalidraw.md Markdown envelopes, Obsidian script engine, PDF/Mermaid conversion, libraries, collaboration/encryption, and non-image attachments. See compatibility.<drawings>/.dsh-excalidraw/, not inside the .excalidraw file, so drawings stay portable.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
Evidence in this repository:
The E2E test requires a running isolated Harness; it is intentionally not part of verify so the routine check never touches a user's live profile. Reproduction steps are in test/e2e/README.md.
The plugin's original code and the scene core are MIT (see LICENSE). The browser half bundles the MIT-licensed @excalidraw/excalidraw@0.18.1 and its MIT/ISC/Apache/0BSD dependency closure; the upstream Obsidian plugin is not copied and its AGPL/MIT metadata contradiction is documented rather than silently resolved. Font binaries are shipped unmodified from the Excalidraw distribution with their embedded licenses recorded in THIRD_PARTY_NOTICES.md.
client.<name>.js is the first v0.2 task..excalidraw.md (Obsidian's modern envelope) is out of scope; only plain .excalidraw JSON is read and written.appState subset (viewBackgroundColor, gridSize, grid mode). Zoom, scroll and theme are not stored in the file.restart-required on first install; the plugin was fully exercised in a separate isolated profile rather than restarting the session you are reading this in.