前言¶

在 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 / 幻方無官方從屬關係；使用前請結合許可與安全預期自行評估。