前言¶

DSH 的插件生態裏，製圖類工具大多是一句話的模板生成器：把數據往裏丟，出一張靜態圖，參數想微調只能重寫 prompt。對科研寫作來說這不夠，因爲最終要落在論文裏的是圖，而不是會話裏的一段描述；而且圖表規範（字號、字欄寬、色帶刻度、數據來源腳註）必須在圖上直接可見、可改。

SciFigure Studio 是 wzgytuA888 維護的一個 DSH 客戶端插件，定位是交互式 SCI 單圖工作臺：對話裏按數據生成草圖，再進整頁工作臺實時調投影、經緯網、圖例、配色、座標軸，每個圖同時產出一份可獨立運行的 Python 代碼。它只做單圖，不提供拼接、合成、圖庫這類功能。

下面的介紹基於倉庫 README 與目錄頁信息，命令和配置項均取自原文。

定位與邊界¶

一句話：這是個「把 matplotlib / cartopy 的渲染參數搬進插件工作臺」的工具，前面是對話和 UI，後面是一個倉庫自帶 Python 渲染引擎，中間用 spec.json 承載參數。

值得先明確的邊界：

1. 只做單圖。地圖/研究區圖、柱狀/折線/散點/熱力/箱線圖各自一張，不做多子圖合成、不做圖組管理。
2. 產物分兩層：界面上的預覽圖，和 components/<id>/component.py（與引擎渲染一致的可運行腳本）。
3. 需要本機有 Python ≥ 3.10，並預裝一批繪圖依賴。這不是零部署插件。

倉庫分類爲客戶端（Client），需要 Web 或桌面端 Harness 才能看到工作臺界面。

核心功能¶

地圖與統計圖¶

三種改圖路徑¶

1. 界面工具區手動調（適合精確控制）。
2. 「一句話改圖」，中文直接說要改什麼，插件解析成參數補丁，例如「圖例放右下角，字號調到 8」「換成墨卡托投影」「用第 3 套配色」。
3. Agent 側直接調 scifig 工具（適合腳本化和批量）。

這三種路徑最終都落在同一個參數表上，所以在界面裏改的和 Agent 改的是同一份 spec。

代碼即產物¶

每張圖都對應一份 component.py，參數寫在腳本里，參數和渲染結果與工作臺一致。可以直接 python component.py --out x.png 跑，也可以拿來繼續改。這一點對需要把圖復現到投審稿環境（換機器、換 Python 版本）的場景比較關鍵。

會話與工作區¶

工作臺可切換會話，能對歷史對話裏已經生成的圖繼續調整。刪除工作區支持單圖 / 單會話 / 全部三種粒度，其中「全部」需要顯式 confirm。

安裝與啓用¶

環境準備¶

需要 DeepSeek Harness（Web/桌面端）、Node ≥ 20、Python ≥ 3.10。Python 側裝依賴：

pip install matplotlib cartopy geopandas shapely pyproj pandas numpy pillow scipy adjustText

注意 cartopy 首次使用會下載 Natural Earth 底圖，離線環境需要預置 cartopy 數據目錄。中文出圖需要系統裏有宋體/黑體/微軟雅黑任意一種。

安裝插件¶

用 Harness 的 plugin manager 安裝本地 bundle 目錄：

plugin_manager install_bundle  target = <本倉庫目錄>

或者把倉庫放進 ~/.dsh/plugins/，在 profile 的 cordis.patch.yml 裏插入：

- insert:
    - id: scifig-studio
      name: 'dsh-scifig-studio'

配置 Python¶

倉庫不含任何機器路徑，Python 解釋器和輸出目錄通過下面三種方式之一配置，優先級遞減直到回退到 PATH。

1. 插件 config：

config: { python: '/path/to/python', workDir: '/path/to/figures' }

2. 環境變量：

SCIFIG_PYTHON=/path/to/python
SCIFIG_WORKDIR=/path/to/figures

3. 插件目錄下建 .scifig-config.json（已 gitignore）：

{ "python": "C:\\venvs\\scifig\\Scripts\\python.exe" }

都沒配時，依次回退到 <bundle>/.venv/… 和 PATH 上的 python。

啓用¶

安裝後左側任務欄出現「科研製圖」圖標，Agent 側多出 scifig 工具。改 client.js 後刷新頁面即可生效；改 host 側邏輯後需要停用再啓用該插件。

典型用法¶

用法一：對話裏提需求¶

用 samples/map_points.csv 畫新疆土壤鹽分空間分佈圖，點符號按鹽分值分級，加經緯網、比例尺、指北針，色帶單位 dS m⁻¹，Nature 風格雙欄。

Agent 調 scifig{draft} 生成草圖，工具卡上顯示縮略圖。接下來左側任務欄「科研製圖」進入整頁工作臺，有預覽和代碼兩個頁籤；工具區裏地圖只顯示投影 chips、經緯網、色帶、比例尺等地圖參數，統計圖只顯示座標軸、圖例、線型等參數，改動實時重繪。最後可以一句話改圖、導出 PNG、複製路徑或查看代碼。

用法二：Agent 側直接調工具¶

{ "action": "draft", "dataFile": "samples/map_points.csv", "kind": "map",
  "description": "新疆土壤鹽分空間分佈，分級設色，經緯網 5 度，比例尺+指北針，Nature 雙欄" }

{ "action": "patch", "set": { "map.projection": "mercator", "style.palette": "ppt-03",
                              "map.colorbar.palette": "ppt-17", "legend.position": "lower right" } }

{ "action": "nl", "text": "圖例放右下角，字號調到 8" }
{ "action": "export" }        // 導出 PNG
{ "action": "code" }          // 取可獨立運行的 Python 代碼
{ "action": "delete", "mode": "figure" }   // mode=all 需 confirm:true

用法三：走 HTTP API¶

插件在同源 /scifig 前綴下暴露一組接口：health controls palettes state sessions patch nl preset image export download active code workspace/delete。本地自檢時可以直接 curl：

curl http://127.0.0.1:3080/scifig/api/health
curl -X POST http://127.0.0.1:3080/scifig/api/patch \
  -H 'content-type: application/json' \
  -d '{"figureId":"fig-...","set":{"map.projection":"robinson"}}'

需要提醒：compose / decompose / library 等拼接類端點已被移除，調用會返回「功能已移除」。這與插件「只做單圖」的定位一致。

自定義配色¶

py/scifig/palettes.json 是配色數據源，字段裏有 kind: categorical | sequential | diverging。可以從自己的 PPTX 重新提取一套：

python scripts/extract_palettes.py "my-deck.pptx" \
    --out py/scifig/palettes.json --preview out/palettes-preview.png

改完代碼本地自檢¶

npm run check:client              # node 語法
python -m compileall -q py/scifig # Python 語法
python py/tools/selftest.py --mode samples
powershell -ExecutionPolicy Bypass -File scripts/verify-api.ps1 -Origin http://127.0.0.1:3080

前三項檢查語法和示例渲染，最後是接口驗收腳本，覆蓋 45 項接口，適合本地改完 host 或 client 後跑一遍。

結構速覽¶

對想動手改源碼的人，需要先知道參數表不是手寫維護的，而是由工具生成。

index.js            Host 入口：註冊工具 / HTTP 路由 / system prompt
client.js           瀏覽器端：左側任務欄圖標 + 整頁工作臺（預覽 / 工具區 / 代碼）
host/               Host 邏輯：api / ops / store / render / controls / infer / nl / spec / palettes ...
py/scifig/          渲染引擎：engine / charts / spec / legend / controls.json / presets.json / palettes.json
py/tools/           引擎自檢與資產生成器（controls.json、SPEC.md 由它們生成）
samples/            示例數據與 spec
docs/SPEC.md        參數全集（124 項）與已知限制
docs/CONTRACT.md    設計契約（Host / Client / Renderer 邊界、API、工具 schema）
scripts/            verify-api.ps1（45 項接口驗收）、extract_palettes.py（從 PPTX 重提配色）

產物目錄默認在 <bundle>/out：

out/<figureId>/{spec.json, figure.png, history/<rev>.json, meta.json}
components/<id>/component.py     # 可獨立運行：python component.py --out x.png

history/<rev>.json 保存每次改動的快照，與工具區的撤銷/重做對應。

適用場景與注意¶

適合這幾類人：

1. 需要論文配圖、但不想每次從零寫 matplotlib/cartopy 代碼的人。
2. 需要把圖從插件裏搬到投審稿環境、從代碼層面復現的人。
3. 想用 Agent 自動生成圖、再由人工在工作臺微調的混合工作流。

上手前要留意的：

1. 插件以當前 DSH 進程權限運行，裝不改源碼前建議先讀 docs/SPEC.md、docs/CONTRACT.md 和 index.js / client.js，確認渲染與 API 邊界。許可爲 MIT，作者 wzgytuA888，示例數據說明是合成數據。
2. 有 Python 依賴和 cartopy 底圖下載需求，內網或離線機器要提前部署。
3. 只做單圖。要做多子圖拼版，得自己處理 component.py，或換其他工具。
4. 目錄頁顯示星標爲 0，屬於新倉庫，遇到問題主要靠 issue。

結尾¶

SciFigure Studio 的價值在於把「生成一張科研圖」拆成三件可分離的事：Agent 建站、界面調參、代碼復現。它沒有把製圖功能塞成一堆 prompt 模板，而是用 spec 作爲統一的參數載體，並讓渲染結果與產物代碼保持一致。如果只做單圖，這是個值得試的客戶端插件。

• 目錄頁：https://www.skillhub.cn/plugins/wzgytuA888/scifig-studio
• GitHub：https://github.com/wzgytuA888/scifig-studio