前言¶
在 DeepSeek Harness（DSH）裏改科研圖，常見返工意見都是位置性的：標號指錯、圖例缺一條、誤差棒過長。用文字描述慢，也容易和模型理解錯位；只發一張截圖，模型往往只知道「有個紅框」，不知道框對應哪一行元素或哪段 SVG。
dsh-figmark 是維護者 KafukaTree 發佈的客戶端類 DSH 插件：在右側欄文檔預覽裏直接圈畫批註圖片、SVG、PDF 或本機網頁，把幾何位置、元素錨點和你的修改說明合成一條用戶消息交給智能體，讓它去改 Python、DOT、SVG 等生成源，而不是在導出的位圖上塗改。原文檔不會被插件改寫，批註落在側車文件裏；安裝與用法以 GitHub 倉庫 與 SkillHub 目錄頁 爲準。
這是什麼¶
dsh-figmark（npm 包名 dsh-figmark）面向「配圖審閱 → 智能體改圖」這條鏈路：你在預覽裏畫箭頭、框選、圈選、手繪或單點 Pin，並可選中 SVG 圖元、HTML 元素；發送時插件注入結構化批註與（按規則生成的）附圖，並附帶系統提示，要求智能體改生成源、未標註處不動。
插件以 MIT 許可發佈；package.json 中當前版本爲 1.2.3，引擎要求 Node ^22.19.0 || >=24.0.0、DSH >=0.2.1-rc.2。社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係，DSH 生態本身是「一切皆插件」的思路，安裝前建議自行查看源碼與許可證——插件隨當前 dsh 進程權限運行。
核心功能¶
交給智能體的三樣東西¶
每條批註消息裏，插件儘量把下面三類信息一起給出（README 中的設計說明）：
- 圖面座標 —— 箭頭兩端、框的對角、單點位置等幾何；
- 落在哪個元素上 —— SVG 側有
tag/id/包圍盒等；靜態 HTML 與本機網頁側有可從body命中的selector（消息裏會過濾掉說不清的冗長字段，保留能回源碼定位的路徑）； - 你的說明 —— 每條標註一段「這個元素要改什麼」，以及可選的「整張圖整體方向」。
柵格圖（PNG/JPEG 等）只有像素座標，沒有元素錨定；SVG 與本機網頁支持元素級定位。
支持範圍¶
| 文檔類型 | 後綴 | 狀態 |
|---|---|---|
| 圖片 | png jpg jpeg gif webp bmp ico |
支持 |
| SVG | svg |
支持，內聯渲染，可選中圖元 |
pdf |
支持，逐頁批註，保存爲原生 PDF 註釋對象 | |
| 靜態 HTML | html htm |
只讀預覽，可跑自包含腳本；無 Figmark 標註工具與側車 |
| 本機網頁 | http://localhost / 127.0.0.1 / [::1] |
在右側欄「本機網頁」中打開運行中的 loopback 服務 |
| Office | doc docx ppt 等 |
待接入，仍由內置預覽器打開 |
另有測試功能：在輸入框附圖縮略圖上直接標註，「加入輸入框」生成標註 PNG 並追加評論到草稿；不寫側車、不建批註隊列，細節見倉庫內 docs/attachment-annotator-testing.md。
側車產物與不改動原文件¶
批註不修改原圖/PDF 源文件，常見側車命名帶被批註文件自己的擴展名，例如 fig1.svg 對應：
| 文件 | 內容 |
|---|---|
fig1.svg.annot.json |
圖信息（路徑、sha256；PDF 含 pageCount）、marks[]、總體目標 |
fig1.svg.annotated.png |
圖片/SVG：原圖與批註合成圖（最高 2×），隨消息附件 |
fig1.svg.annotated.pdf |
PDF：原件副本 + 原生註釋對象，隨消息附件 |
本機服務頁不留側車文件，消息攜帶頁面 URL 與 anchor.selector。靜態 HTML 預覽不產生批註文件或消息。原圖重新生成導致 sha256 變化時，插件會提示舊批註可能失準。
同一工作區姊妹批註器 Sati 使用 v2 側車形狀；本插件能讀 v2、繼續寫 v1，互通時 v2 獨有字段回存可能丟失。
安裝與啓用¶
下面三條路徑均來自 README，任選其一；裝完後需 完全退出並重開 DSH（README 寫爲 Cmd+Q，Linux 上對應完全結束 dsh 進程後再啓動）。
從插件市場安裝（推薦）¶
在 DSH 打開 側欄 → 插件 → 實驗性插件 → 更多 → 自定義插件市場，添加索引：
https://raw.githubusercontent.com/KafukaTree/dsh-figmark/main/market/index.json
在發現頁搜索 figmark 安裝。
從 npm 安裝¶
dsh plugin add dsh-figmark
命令會把依賴寫入 profile 並加入 dsh.profile.bundles。
從源碼開發¶
需要本地構建時，在克隆後的目錄執行 pnpm install 與 pnpm run build，再用本地路徑安裝：
dsh plugin add "$PWD"
改動 Host 半後必須重啓宿主進程；Client 半刷新頁面即可。開發時可使用隔離實例，例如：
DSH_HOME=/tmp/figmarkdev dsh --profile figmarkdev --port 3099 --no-open
典型用法¶
在右側預覽裏標註文件¶
- 在右欄打開圖片、SVG、PDF，或在本機網頁裏打開正在運行的 loopback 服務。
- 左側浮條切換工具：選擇、箭頭、框選、圈選、手繪、單點；除「選擇」外，畫完會自動回到選擇並彈出說明框。
- 底部浮條：樣式、撤銷/重做、總體目標、標註清單，以及兩個發送入口（見下表）。
- 編輯會自動保存（防抖 600ms）；只有發送成功後才清空面板並刪除磁盤上的批註文件。
| 按鈕 | 行爲 |
|---|---|
| 發送給智能體 | 批註與標註圖作爲一條用戶消息直接進入當前會話 |
| 發送到對話框 | 寫入輸入框草稿（含圖片附件），由你確認後再發送 |
交互要點：圖上只畫標記，不把說明文字燒進圖；雙擊標註編輯說明，Delete/Backspace 刪除選中項；兩條浮條可拖動，位置保存在瀏覽器本地。
本機網頁與靜態 HTML 的區別¶
靜態 .html 走 Figmark 只讀預覽，沒有底部標註工具。要標註 Vite、Next 等開發中的頁面，先在右欄進入「本機網頁」：Host 會按 bounded 規則發現最近地址、package.json 裏寫明的端口及常見開發端口，不會全端口掃描，也不會替你執行任意啓動命令。選中地址後通過 live proxy 打開 127.0.0.1 上的頁面，元素模式可落帶 selector 的元素標註；純元素或純 pin 批註可不生成截圖，消息標記爲「位置標註」；含可見繪圖的批註會截當前可見 surface。
適用場景與注意¶
適合：用 DSH 迭代 matplotlib / Graphviz / 手寫 SVG 等流水線，需要把「指這裏、改那裏」精確交給智能體；需要在 PDF 上留可在閱讀器裏繼續編輯的原生註釋；需要在本地 dev server 頁面上點選 DOM 元素寫修改意見。
務必知曉的限制（README「已知限制」）：
- 插件只採集批註，不做圖面編輯；修圖靠改生成源。
- PDF 一次一頁，無文本層、無連續滾動；註釋不燒進頁面內容，不渲染註釋的閱讀流程看不到標記（可依賴消息附帶的每頁圖）。
- 本機網頁必須有正在運行的 loopback 服務；靜態 HTML 不能 Figmark 標註。
- Office 尚未接入。
安裝前請自行審閱 https://github.com/KafukaTree/dsh-figmark 源碼與 MIT 許可證；插件能力以倉庫 README、CHANGELOG 爲準。
結尾¶
dsh-figmark 把科研配圖返工從「長段文字描述位置」變成「預覽裏圈畫 + 結構化消息」，並強調改圖源、不動未標註區域。進一步瞭解可訪問目錄頁 https://www.skillhub.cn/plugins/KafukaTree/dsh-figmark 與 GitHub https://github.com/KafukaTree/dsh-figmark。
