科研可视化台 Astepluver/dsh-sci-viz

dsh-sci-viz · 科研可视化工作台

一个 DSH 插件，把三件事放进同一个面板：蛋白质三维结构、统计图表、技能库浏览器。
目的很直白：不要再让 AI 用文字描述「一个由 964 个残基组成的细长螺旋束」，直接看图。

- 随取随用：195 个技能随插件一起分发（data/skill-pack.json.gz，含完整 SKILL.md 正文），挂载时全部注册进 DSH 技能系统 —— 对方装上就能直接调用，不需要任何本地技能目录。
- 零依赖：宿主半边只用 node: 内置模块，浏览器半边只 require 平台自带的 react。
- 零构建：没有打包步骤，改完 lib/.js 刷新页面即生效。
- 体积：运行时读的文件合计约 1.2 MB（其中技能包 0.84 MB）。见「八、体积」。

零、怎么装

1. 打开 DSH → 设置 → 插件
2. 在安装框里粘贴这一行： https://github.com/Astepluver/dsh-sci-viz/releases/latest/download/dsh-sci-viz.tgz
3. 等它装完，重启一次 DSH
4. 刷新页面，右下角会出现一枚可拖动的图标，点它打开面板

也可以下载 .tgz 后在安装框里填本地绝对路径。注意安装框不认 zip 文件本身的路径 ——要先解压，再指向解压出来的目录。

Release 还没建/附件坏了时的兜底：直接把仓库地址粘进安装框也行 —— https://github.com/Astepluver/dsh-sci-viz（DSH 会走 git 安装，公开仓库无需登录）。

为什么要重启：插件分两半，负责计算的那一半是 ESM 模块，Node 按 URL 缓存，改完只有重启才会重新加载；负责绘制的那一半每次刷新页面重新取。

怎么确认装好了：打开 http://127.0.0.1:19387/api/sci-viz/health，应当看到 skillRegistration.registered: 195 与 registry: { ours: 195, oursExpected: 195 } ——那是直接向 DSH 技能系统核对的结果，不是插件的自报数。

3.1.0 新增了什么

这一版加的是保险，不是新图型 —— 插件以前只负责画，画得对不对全靠用它的人自觉。

- 插件自带验证规程：挂载时注册一段系统提示，把「图对不对」拆成四层（通道自检 → 契约层纯读 → 数值对拍 → 几何与视觉），并要求交付声明分三档（已对拍 / 仅契约校验 / 待人工确认）。跟着插件走，分享出去对方也有。
- 子代理验证通道：子代理的 write/edit 默认被拒，只有 <会话 cwd>/.dsh-verify/ 内放行，拒绝时带原因；Agent Teams 队友自动豁免。可用 verifyProtocol 整体关掉。
- 可移植 oracle tools/recompute.py：纯 Python 标准库（不依赖 scipy）， --selftest 自检 10 个已发表临界值，覆盖 t / ANOVA / 卡方 / 回归 / 描述统计。
- 规程自检 tools/check-verify-protocol.mjs：33 条断言，防止这段保险静默失效。
- 工具调度纪律写进规程：验证时不得调用 sci_viz_（会覆盖唯一真源、冲掉用户正在看的面板）。

详见第五节「可视化是怎么验证的」。

3.0.1 新增了什么

- 热图（heatmap）：发散色阶 0 居中，可选行列层次聚类树，带色阶条
- 序列 Logo（logo）：字母高度 = 信息量（bits），自动区分核酸/蛋白，间隙不计入
- 基因互作网络（network）：力导向布局，无随机数（同输入必得同图）
- 生存曲线（survival）：KM 阶梯 + 删失竖杠 + 中位虚线 + log-rank 检验
- ROC 曲线（roc）：正方形绘图区 + AUC + 最佳切点，支持多模型对比
- SVG 矢量导出：工具栏新按钮，投稿用；10 种面板都验证过产出合法 SVG
- 基因组页能自己干活了：顶部输入条粘 Newick/FASTA/TSV 直接出图，Ctrl+Enter 跑
- 变异密度分箱：2.4 万个变异画成 496 个密度柱，而不是 24000 条糊成实线的刻度
- 独立窗口（3.0.1）：工具栏「⧉ 独立窗口」把可视化放进浏览器新窗口，可以拖到聊天框旁边看。
那个窗口用的还是本插件的渲染器（同一份代码），三维结构照样能拖能缩放，另有 PNG / SVG 导出

数值内核新增 KM / log-rank / ROC，与 scipy 逐项对拍（log-rank χ² 相对误差 1.2e-16）。

一、它长什么样

三个入口，随便哪个都能打开（入口这种东西不能只押一个位置 —— 第三方皮肤会替换侧边栏，自定义的 panellist 条目在那种皮肤里根本不会渲染）：

| 入口 | 位置 | 是否受皮肤影响 |
| 🔬 可视化 药丸 | 悬浮在界面右下角，可拖动换位置 | 不受（挂在 body 上） |
| 🔬 可视化 按钮 | 输入框工具行左侧（conversation.input.left），就在「+」旁边 | 一般不受（composer 属 shipped UI） |
| 科研可视化 图标 | 侧边栏面板图标行（sidebar.panellist） | 受：maid-atelier 这类整体替换侧边栏的皮肤不会显示 |

点一下打开，再点一下切回对话；面板标题栏右侧还有「← 返回对话」按钮，Esc 同样可以退出。
标题栏的 ⇥ 开关控制「AI 推来新图时是否自动跳到本面板」—— 不想被打断就关掉，内容照常更新，有新内容时入口药丸会亮一个小点提示你。

面板本身是 DSH 主面板里的一页（main 键位槽，和官方「插件」页同一个机制），三个标签页：

| 标签页 | 内容 |
| 三维结构 | PDB/mmCIF 交互式查看：卡通 / 骨架 / 球棍 / 空间填充 / 仅配体；按链 / 二级结构 / B 因子 / 残基性质 / 元素 / 彩虹着色；N 端（绿）/ C 端（紫）/ 指定位点（红）三类高亮，都带标签；focus 聚焦把镜头推进到口袋并把远处结构淡出；拖拽旋转、滚轮缩放、Shift 拖拽平移、双击复位 |
| 统计图表 | 正态分布曲线、t 分布拒绝域、F 分布、箱线图 + 抖动散点、直方图 + 正态拟合、Q-Q 图、效应量森林图、残差图、功效曲线；图下附统计表与一句话结论 |
| 技能库 | 195 个技能随插件分发（含完整 SKILL.md 正文，打包 0.85 MB），挂载时全部注册进 DSH 技能系统 —— 分享给别人，对方装上就能直接调用；面板里可检索、可按分类与来源筛选、可读正文 |

分享这件事：data/skill-pack.json.gz 里是 195 个技能的完整正文，apply() 时通过
ctx.skills.register({ source: 'bundled', ... }) 逐个注册。所以对方不需要任何本地技能目录，
装上插件技能就能用。附属资源（scripts/ references/，源目录合计约 59 MB）没有打包，由 tools/build-skill-pack.mjs 把清单记在正文里。

早期版本用「即用层 / 技能库层」标注，那是原工作区目录结构的划分；现在技能全部随插件注册，这个区别对使用者不再有意义，已改成按来源标注（自带 / 本地目录）。

踩过的坑，记在这里免得重犯：
1. 早期版本浮窗没有关闭按钮、侧栏入口在皮肤下不渲染，结果「打开了出不去、关上了进不来」。
现在入口有三个、出口有两个（按钮 + Esc），且主面板和浮窗共用同一份 createPanel 实现。
2. 绝不用 PowerShell 的 Get-Content / Set-Content 搬运这个插件的源码。Windows PowerShell 5.1 按 ANSI（GBK）读 UTF-8 文件，写回时中文变乱码、尾字节还会吞掉相邻的引号/反引号/换行 ——一次这样的「裁剪」把 lib/index.js 写坏了，最后是靠重放会话日志里的 write + 每次 edit 才救回来。
改文件只用编辑器工具（read / edit / write）；要用脚本就直接在 Node 里用 fs，让编码归 Node 管。

二、模型侧：5 个工具

| 工具 | 用途 |
| sci_viz_structure | 打开一个结构。source 支持本地路径、4 位 PDB ID（自动从 RCSB 下载）、http(s) 链接；highlight 支持 S315T / S315 / 315 / A:315 |
| sci_viz_stats | 跑统计并出图。kind = normal / ttest / anova / chisq / regression / power / descriptives / survival / roc |
| sci_viz_genomics | 基因组学出图。kind = phylo / msa / enrich / genome / coverage / volcano / heatmap / network / logo |
| sci_viz_plot | 通用逃生门：直接给面板定义，画任何 sci_viz_stats 覆盖不到的图 |
| sci_viz_skills | 把面板切到技能页并按关键词 / 分类 / 层级筛选、高亮 |

// 看一个突变位点 { "source": "1SJ0", "label": "KatG S315T", "highlight": ["S315T"], "style": "ballstick", "colorBy": "element", "focus": [10.2, 4.5, 22.1] }

// 两组 MIC 比一比 { "kind": "ttest",
"groups": [{ "label": "野生型 H37Rv", "values": [8.2,7.9,8.5,8.1] },
{ "label": "katG S315T", "values": [7.1,6.8,7.4,7.0] }] }

// 三组以上的 MIC { "kind": "anova", "groups": [ { "label": "敏感株", "values": [ /* … / ] }, { "label": "单耐药", "values": [ / … / ] }, { "label": "耐多药", "values": [ / … / ] } ] }

三、便携性（不依赖本地 skill 包）

技能清单的两层来源：

| 来源 | 提供什么 | 是否必需 |
| 插件自带 data/taxonomy.json | 195 个技能的目录名、分类、中文说明、英文说明、标签、权重、层级 | 必需，已随插件打包 |
| 配置项 skillsDirs 指向的技能目录 | SKILL.md 正文、路径、体积、是否有 scripts/ references/ | 可选增强 |

- 不配 skillsDirs：技能库照常浏览，分类/搜索/标签全部可用；点开某条只显示快照说明。
- 配了但目录不存在（换机器最常见的情况）：静默跳过，不报错、不降级、不影响其它功能。
- tools/enrich-taxonomy.mjs 负责把 SKILL.md 的标题与说明抄进快照 —— 这是构建期 的一次性动作，运行期不再需要技能目录。

GET /api/sci-viz/health 会报告 config.portable 与 skills.readable，一眼能看出当前是哪种形态。

四、统计的可靠性

数值内核 lib/core/numeric.js 是纯函数，没有查表近似：正态走不完全 Gamma， t / F 走不完全 Beta，卡方走不完全 Gamma，p 值是精确值。

tools/verify-math.mjs + tools/verify-math.py 用工作区里现成的 scipy 1.18 独立对拍：

node tools/verify-math.mjs
.venv-skills\stat\Scripts\python.exe tools/verify-math.py
→ checked=546 failures=0
覆盖 546 项：正态 PDF/CDF/分位数、t PDF/CDF/分位数（df = 1…1000）、F、卡方、非中心 t、不完全 Beta/Gamma、erf/lgamma；描述统计（含偏度/峰度的无偏定义）、单样本/独立/Welch/配对 t 检验、单因素 ANOVA（含事后比较）、卡方（含 Yates）、线性回归、Shapiro-Wilk（n = 6…1000）、 t 检验功效与非中心 t 积分。容差 rtol = 1e-8 / atol = 1e-10。

已知边界：ANOVA / 卡方的 F、χ² 分布图在观测统计量远大于临界值时横轴会被拉得很长，曲线挤在左侧。图仍然正确（观测值标在右侧、拒绝域涂红），只是形态不美观。

五、可视化是怎么验证的

5.1 渲染层：没有浏览器也能确认画面对不对

客户端渲染器只用一个受限的 Canvas2D 指令子集， tools/verify-visual.mjs 里有一个 Canvas2D → SVG 记录器，把浏览器端同一份代码 的绘制调用录成 SVG，再用 profile 里已有的 sharp 光栅化成 PNG 交给人眼检查。

node tools/verify-visual.mjs # 32 张，检查完自动删掉中间产物
node tools/verify-visual.mjs --keep # 保留 PNG/SVG 自己看

覆盖：5 种结构表现方式 × 多种着色、高亮 + 标签、7 种统计图、通用绘图入口、窄版式。
渲染器一旦用到 shim 没实现的 canvas 成员，脚本直接抛错而不是静默画错。

但它验不到语义：断言全是数量与几何量（图元数、rect/path 比例、标签配平、旋转矩阵、缩放比），没有像素基线；measureText 只是按字宽估算（CJK 1.0em / 其余 0.55em）。
所以标签遮挡、截断、配色语义、数据→几何映射是否正确，机器判不了 —— 必须由人确认。

5.2 规程层：插件自带的验证规程（3.1.0 起）

插件挂载时会注册一段系统提示（lib/verify-protocol.js，order 750），把「图对不对」拆成四层，任何一层都不许冒充另一层：

| 层 | 做什么 | 谁能做 |
| 0 通道自检 | 先确认这台机器上哪些验证通道真能跑；跑不起来就如实标「不可用」 | 模型 |
| 1 契约层 | 纯读状态文件与工具返回：doc.kind／分组／样本量／来源与日期／数字可追溯 | 模型 |
| 2 数值对拍 | 用 tools/recompute.py 独立重算关键统计量，容差 rtol≈1e-6 | 模型 |
| 3 几何与视觉 | 机器只验几何量；语义、遮挡、配色交回人 | 人 |

同时给子代理会话加一道只读守卫：write / edit 默认被拒， 只有 <会话 cwd>/.dsh-verify/ 内放行（验证经常要写对拍脚本，全禁会让验证做不了）。
Agent Teams 队友自动豁免。全部可在 cordis.patch.yml 的 verifyProtocol 关掉：

verifyProtocol:
enabled: true
verifyScratchDir: '.dsh-verify' # 相对会话 cwd subagentReadOnly: true allowScratchWrites: true
deniedTools: [write, edit]
denyShell: false # 拦了 shell，子代理就跑不了对拍脚本

5.3 数值层：两条互补的对拍通道

| 通道 | 覆盖 | 依赖 |
| tools/verify-math.py（配 verify-math.mjs） | JS 数值内核 vs scipy，546 项 | 需要 scipy；没有就标该通道不可用 |
| tools/recompute.py（3.1.0 新增） | 独立重算 t / ANOVA / 卡方 / 回归 / 描述统计 | 纯 Python 标准库，分享到任何机器都能跑 |

python tools/recompute.py --selftest # 先自检：10 个已发表临界值全过才允许用
python tools/recompute.py spec.json # 对拍：{"test":"t_test","args":{...}}

5.4 规程自检

node tools/check-verify-protocol.mjs # 33 条断言：身份分发/该拦该放/越界/降级/不写死用户目录

存在的理由很具体：这段保险的失败模式是静默失效（不注入、不生效、且没有报错），所以把它钉成断言 —— 谁改了 verify-protocol.js，跑一遍就知道有没有把它改坏。

六、安装 / 卸载

用 plugin_manager 工具（推荐）：install_bundle，target = 插件目录或命令行：
node "<dsh 命令>" plugin --profile desktop add "<插件目录>"

本地路径安装走 pnpm 的 link:，不复制文件，改完即可生效。
卸载：plugin_manager 的 remove_bundle，或在 Plugins 页面里关掉这一行。

改了 lib/index.js（宿主半边）之后，插件管理器的启用/禁用切换不一定会重新 import 那个模块（Node 的 ESM 缓存按 URL 记）。要确保宿主侧改动生效，重启 DSH 最稳。
浏览器半边 lib/client.js 是每次从磁盘读并带版本号的，刷新页面即可拿到最新版。

七、目录

dsh-sci-viz/
├─ package.json # dsh.bundle.patch → cordis.patch.yml；dsh.client → ./client ├─ cordis.patch.yml # 插入行 + 可覆盖的配置（skillsDirs / structureRoots / stateDir） ├─ lib/ │ ├─ index.js # 宿主半边：路由、工具、技能清单、图表构造 │ ├─ client.js # 浏览器半边：主面板 + 隐形 watcher + 三维渲染 + 二维图表（单文件自包含） │ └─ core/ │ ├─ numeric.js # 分布函数与统计检验（纯函数） │ └─ structure.js # PDB/mmCIF 解析 + 结构几何编译 ├─ data/taxonomy.json # 195 个技能的自包含快照（78 KB） ├─ 功能清单.md # 完整功能说明（工具参数表由 tools/make-manifest.mjs 从代码生成） ├─ tools/ # 验证与构建脚本（不参与运行时） │ ├─ verify-math.mjs/.py # 数值内核对拍 scipy │ ├─ verify-visual.mjs # Canvas2D→SVG→PNG 视觉验证 + 回归断言 │ ├─ smoke-host.mjs # 假 ctx 挂载：工具/路由/便携模式 │ ├─ smoke-structure.mjs # 解析器冒烟 │ ├─ check-client.mjs # 入口与出口链路自检 │ ├─ check-delivery.mjs # 零依赖 / 零构建 / 体积约束 │ ├─ push-viz.mjs # 命令行推图（不经过工具注册，直接写状态文件） │ ├─ make-manifest.mjs # 生成《功能清单.md》 │ └─ enrich-taxonomy.mjs # 把 SKILL.md 标题与说明抄进快照（构建期，一次性） └─ state/current.json # 当前可视化文档（唯一真源，运行期产物）

改完怎么重新生成清单：node tools/make-manifest.mjs。工具参数表是从实际注册的定义里读出来渲染的，所以只要重跑就不会和代码脱节。

八、体积

| 部分 | 大小 |
| lib/index.js + lib/core/ | 约 124 KB |
| lib/client.js | 约 100 KB |
| data/taxonomy.json（195 技能快照） | 78 KB |
| tools/（验证/构建，可不随插件走） | 约 60 KB |
| 运行时合计 | 约 250 KB |
| state/current.json | 随当前文档变化（结构几十~几百 KB，图表 10–30 KB，只有一个文件、每次覆盖） |

.tmp/ 是验证脚本的中间产物（约 10 MB），脚本默认用完即删；--keep 才保留。

九、实现上的几个刻意选择

1. 不 import @deepseek-ai/。 插件以 link: 装在工作区目录，Node 按 realpath 解析 bare specifier，走到 插件\ 就断了 —— 找不到 profile 的 node_modules。所以宿主半边只用内置模块；工具用普通对象直接交给 ctx.tools.register()（它只要求 defineTool 产出的那个形状：原始 JSON Schema + output.render），参数校验自己补上（validateAgainst），因为 register() 不会替我们校验。
2. 主面板 + 隐形 watcher。 面板只有被选中时才挂载，所以轮询放在 shell.overlay 里一个不可见的 watcher 上：它负责取文档、按开关决定要不要 layout.selectPanel() 翻页；页面组件只订阅结果。用户停在对话页时新图也能被发现，不想被打断就关掉 ⇥。
3. 状态文件是唯一真源。 工具、命令行、任何外部脚本都只是往 state/current.json 写一份文档，浏览器轮询 GET /api/sci-viz/state?rev= 取。于是「推一张图到面板」不依赖工具注册是否成功，node -e "..." 也能做到。
4. 取景用投影包围盒，不是包围球。 细长结构（长螺旋束、MCE 转运体）用包围球会被缩到只占一角；按当前姿态的投影包围盒取景，球状和棒状都能撑满画布。