前言¶

在 DeepSeek Harness Desktop（DSH）里做会话级草图时，常见做法是依赖浏览器存储或工作区级别的快照，Agent 要理解画板上有什么，往往还得自己读 JSON 或写临时脚本。社区里也有基于 tldraw 5、draw.io、Excalidraw 等的画板插件，但在编辑器许可、持久化位置、以及暴露给 Agent 的接口上各不相同。

下面介绍 dsh-tldraw-canvas：由维护者 amumulam 发布的客户端类 DSH 插件。它在每个 Session 的右侧边栏提供一块 tldraw v1（MIT） 画板，画稿自动写入该 Session 的项目目录，并注册 Host 侧的只读服务与 tldraw_read_canvas 工具，便于 Agent 获取规范化摘要和 PNG 预览，而无需手工打开画板文件。

这是什么¶

插件全名对应仓库 amumulam/dsh-tldraw-canvas（package 名 dsh-tldraw-canvas，当前资料中版本 1.0.0，许可证 MIT）。定位可以概括为：DeepSeek Harness Desktop 插件——每个 Session 在右侧边栏拥有独立的 tldraw v1 画板，持久化落在 Session 项目目录内，并提供 Agent 可读的摘要/预览能力。

与采用商业许可 tldraw 5 SDK 的方案不同，本插件刻意使用 2021–2022 年间的 MIT 版 tldraw v1（开发依赖中 @tldraw/tldraw 1.29.2），因此不需要 license key、水印或生产环境门禁；代价是编辑器不再维护、功能面较旧。插件为独立社区作品，与 tldraw Inc. 无隶属关系。

核心功能¶

右侧边栏画板与自动保存¶

1. 为 Session 打开右侧边栏，从引导中添加标签页，选择 Tldraw Canvas / Tldraw 画板。
2. 在画板上绘制；短暂停顿后会自动保存，关闭标签页时也会再保存一次。
3. 状态栏会显示保存状态以及相对于工作区的文件路径。

客户端通过 debounce 自动保存；Host 提供 GET/PUT /api/tldraw，按 Session 解析路径并原子写入文件，应用重启或切换 Session 后画稿仍在。

持久化位置与 Workspace / Session 目录¶

画板文件路径固定为：

<session project directory>/.dsh/tldraw/<session-id>.json

Host 自行解析 Session 的项目 origin（不可变的 SessionHeader.cwd），浏览器不能任意指定路径。画板锚定在项目 origin，而不是 Session 内可能变化的有效工作目录（working_directory 工具可改后者）。因此在同一 Session 里 cd 不会把画稿拆到多个目录；活跃 Session 与归档回放读的是同一份文件。若需要另一块独立画板，应在另一个目录下开新 Session。

DSH 的 Workspace 是注册表项：命名目录 + 在该目录下创建的 Session 分组；删除 Workspace 不会删除磁盘上的文件夹、文件或 Session 历史。

Agent 工具：tldraw_read_canvas¶

Host 注册 tldrawCanvas 服务，并对 Agent 暴露工具名：

tldraw_read_canvas

参数（资料原文）：

• session_id — 可选；默认当前调用方 Session
• include_preview — 默认 true；是否渲染 PNG 预览

工具返回规范化摘要（格式、形状/笔画/文本数量、点数、边界、逐形状细节等）以及可选预览图，用于回答「画板上有什么」一类问题。实现上同时接受 v1 文档与遗留 v5 快照。

其他 Host 插件可注入 tldrawCanvas 并只读调用：

const analysis = await ctx.tldrawCanvas.inspect(sessionId);
const { analysis, png } = await ctx.tldrawCanvas.render(sessionId);

inspect 与 render 为只读；写入与配置仍由画板标签页及其自动保存负责。

从 tldraw 5 遗留画稿迁移¶

插件首版曾使用 tldraw 5。在旧文件第一次以 v1 保存时，Host 会在旁备份：

.dsh/tldraw/<session-id>.v5.json

客户端检测到 v5 快照时，将自由手绘 draw 形状转换为 v1 点集，并显示 已迁移旧画板 / Legacy canvas migrated 徽章；其他 v5 形状类型不转换，徽章 tooltip 会报告跳过数量。.v5.json 备份不会被插件删除。

安装与启用¶

资料中的安装方式为：取得插件源码目录后，在 DSH 中将其作为 bundle 安装——Plugin Manager → install from folder，或对目录绝对路径使用 install_bundle。仓库说明 client.js 已预构建，安装后的副本不需要 node_modules。

运行环境要求（package.json）：Node >= 20（主要面向插件开发与测试；日常使用依赖 DSH 内置加载）。

安装前请自行审阅 GitHub 源码与 MIT 许可证及 THIRD_PARTY_NOTICES.md。插件在当前 DSH 进程权限下运行，Host 会读写 Session 项目目录下的 .dsh/tldraw/；仅安装你信任的来源。

典型用法¶

按 README 的可复现步骤：

1. 打开目标 Session 的右侧边栏。
2. 从引导添加标签，选择 Tldraw Canvas / Tldraw 画板。
3. 绘制并观察状态栏中的保存状态与 workspace 相对路径。
4. 需要 Agent 理解画板内容时，在会话中调用 tldraw_read_canvas（可按需设置 session_id、include_preview）。

若你维护其他 Host 插件并需在服务端读取画板，可注入 tldrawCanvas 后调用 inspect / render，避免重复解析 JSON 或自写预览逻辑。

与同生态插件的差异（简要）¶

资料中的对比表强调：本插件使用 MIT tldraw v1、每个 Session 一份文件且落在 Session 项目目录、对 Agent 提供只读摘要 + PNG 预览，而不是一整套协同编辑类 whiteboard 工具。具体选型请对照各仓库的编辑器、存储位置与 Agent 接口自行判断。

实现结构（供排查问题）¶

• index.js — Host：GET/PUT /api/tldraw、解析 cwd、原子读写、v5 备份。
• src/client-entry.js — Client：注册 tldraw 标签类型、引导卡片、主题感知编辑器、debounce 自动保存。
• src/migrate.js — v5 笔画解码与 v5 → v1 转换。
• src/canvas-model.js — 与格式无关的分析及无依赖 PNG 预览渲染。
• client.js — 构建产物（npm run build 由 src/client-entry.js 生成）。

开发者本地构建与测试：

npm install
npm run build

node --test test/*.test.mjs

结尾¶

dsh-tldraw-canvas 适合需要在 DSH 里为每个 Session 做轻量白板、且希望画稿跟项目目录走、并让 Agent 通过 tldraw_read_canvas 读懂画板内容的开发者。目录与源码：

• 社区目录页：https://www.skillhub.cn/plugins/amumulam/dsh-tldraw-canvas
• GitHub：https://github.com/amumulam/dsh-tldraw-canvas

社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；使用前请结合许可与安全预期自行评估。