前言¶

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