DSH Science Plugin

August 14, 2026 · View on GitHub

dsh-science-plugin 是 DSH 0.1.0-rc.6 的科研工作区插件。它把数据库检索、计算产物、Deep Search、审查和远程任务保存为项目内可重放的证据链，而不是只保留聊天结论。

“无幻觉”在本项目中指工程门禁：缺少来源或计算证据的声明会被阻断或标记。插件不承诺模型在理论上绝不出错。

当前状态

  • 里程碑 A（证据后端：ScienceStore、Reviewer、Connector、MCP、Deep Search、DSH 工具/UI、SSH/Slurm/PBS、8 个 Skills）：已完成。
  • 里程碑 B 任务 11–13（规格扩展、本地计算内核账本、ResearchPlan 人工计划门）：已完成。
  • 里程碑 B 任务 14/15/17/18（实时 Compute UI、项目级 Artifact 工作区、报告导出浏览器验收、跨平台最终验收）：未完成——缺少真实浏览器/Web 会话验证，Windows 实机安装和真实 Slurm/PBS 集群也未验证。完整任务清单、依赖和证据见 openspec/changes/001-build-dsh-science-plugin/tasks.md。
  • 已验证平台：macOS（dsh 0.1.0-rc.6）。Windows/Linux 上的安装步骤应当一致，但尚待实机验证，欢迎反馈结果。

安装

需要 Node.js ^22.19 || >=24 和已安装的 DSH 0.1.0-rc.6+。dsh plugin 命令依赖 PATH 上的 pnpm，安装前建议先确认 pnpm -v 能执行。

方式一：下载已构建的包（推荐）

从 Releases 下载 dsh-science-plugin-<version>.tgz，核对页面给出的 SHA-256 后安装：

dsh plugin --profile science-dev add ./dsh-science-plugin-0.1.0.tgz
dsh --profile science-dev --dump-config
dsh --profile science-dev

方式二：从源码构建

git clone https://github.com/SPYfighting/dsh-science-plugin.git
cd dsh-science-plugin
npm install
npm run check   # typecheck + test + build
npm pack
dsh plugin --profile science-dev add ./dsh-science-plugin-0.1.0.tgz

Web profile 与其他 profile 相互独立，配置不共享。要装入全局 Web profile，把上面命令里的 science-dev 换成 web，最后用 dsh web 启动。

Windows 使用同一个 npm 包，命令中的路径需用正斜杠，例如 C:/work/dsh-science-plugin-0.1.0.tgz。首版已覆盖 Windows/POSIX 路径规则的单元测试，但尚无 Windows 实机安装验证。

科研闭环

  1. science_run 创建或恢复科研运行。
  2. 任何会写文件、联网、启动本地/远程计算或导出报告的科研动作，先用 science_plan 保存结构化计划并显式启动对应步骤。人工批准绑定计划版本与 SHA-256；修订后旧批准立即失效。全部批准、逐步批准、要求修改和取消都由 DSH 人工问题界面记录。
  3. science_compute 启动命名 Python/R 环境。Python 已验证同一内核保持变量和四内核并行；每个单元的完整源代码、输出、错误、耗时和生成文件写入 run。没有 Rscript 时明确记录运行时缺失。
  4. science_connector 查询 29 个文献和生物数据库连接器；联网前由 DSH 人工问题界面逐次确认外传。
  5. science_deep_search 使用 DSH 官方 workflow 和 Haiku/Sonnet 拆分检索维度，多轮补齐证据缺口，随后强制进入人工讨论检查点。讨论确认后，综合代理只能引用已保存且明确纳入的题录和摘要，并为每条声明生成 ClaimEvidence。
  6. science_artifact 将脚本、数据、结果和图表登记为不可变版本并计算 SHA-256；本地计算工作目录中的新文件会自动登记。
  7. science_evidence 为普通计算或数据库结果登记声明—产物/来源链接；Reviewer 总是审查账本中的全部声明，调用方不能用空列表漏审。
  8. science_library 保存研究者提供的准确题录、全文/许可状态和项目内 PDF/RIS/BibTeX 原文件，按 DOI、PMID 或题名—年份去重，并永久保留带理由的排除记录。local-file 只证明 PDF 字节已登记，不冒充已完成 OCR 或自动题录解析。
  9. science_review 的确定性门禁始终启用，检查文件、哈希、命令、计算单元、计划状态、图表上游、图表 QA、声明证据和当前证据快照；设置开关只控制额外的只读模型语义复核。证据变化后旧审查自动失效；完成后的 run 不再允许写入。
  10. science_remote 通过用户配置的 SSH alias 执行 SSH、Slurm 或 PBS 任务，保存任务号、同步清单和本地/服务器端哈希。上传和下载使用文件流，不把整份科研数据装入 DSH 内存；普通命令输出有大小上限。连接中断或返回 255 时状态为 unknown。Slurm/PBS 使用唯一任务名，支持中断后从活动队列或历史账本找回任务号。
  11. science_compute command 用字面参数数组运行一次性本地命令，不经过 shell；完整参数、标准输出、错误、退出码和不可变命令源产物写入 run。science_export 只从当前已通过且未过期的 Reviewer 快照生成 Markdown 报告、Jupyter Notebook、机器可读 evidence/review/provenance、corpus.csv、BibTeX 和 CSL-JSON。只有已保存的 LibraryRecord 可生成正常题名和文献类型；只有来源标识符时导出为明确的 unresolved 条目。完成门会逐个复核导出文件哈希。

工具返回规范 JSON、locations 和展示元数据。DSH 会话保留工具调用，项目文件保留权威运行状态，因此刷新或重启后可从 run.json 恢复。

本地证据目录

.dsh-science/config.yaml
research/runs/<run-id>/
├── inputs/
├── scripts/
├── configs/
├── results/
├── figures/
├── sources/
├── reviews/
├── logs/
├── workspaces/
├── events.jsonl
└── run.json
  • run.json 保存产物、声明证据、检索、审查、图表人工复核、人工检查点、外传决定和远程任务。
  • events.jsonl 是追加式事件记录。
  • 同名产物使用 v1、v2 递增，不覆盖旧证据。
  • 同一 run 的写入使用跨进程目录锁，DSH 与独立 MCP 进程同时写入时不会覆盖彼此；锁由所有者周期更新，进程崩溃后仅在超过安全时限时原子接管，使任务可以恢复而不需要手工删除锁文件。
  • 产物预览 RPC 只接受 artifactId，不能提交任意本地路径。

连接器

首批来源包括：

  • 文献：PubMed、Europe PMC、Crossref、OpenAlex、Semantic Scholar、bioRxiv/medRxiv、arXiv。
  • 临床：ClinicalTrials.gov。
  • 基因、基因组与变异：NCBI Gene、Genome、GEO、Ensembl、ClinVar、dbSNP、EMBL-EBI Proteins Variation（包含映射到 UniProt 的 gnomAD 等大规模变异来源）。
  • 蛋白、家族与结构：UniProt、InterPro、RCSB PDB、AlphaFold DB。
  • 表达与单细胞：BioStudies 中的 ArrayExpress collection，以及带 gxa-sc 链接的 Single Cell Expression Atlas 研究元数据。
  • 化学与结合：PubChem、ChEMBL、BindingDB。
  • 通路：Reactome、KEGG。
  • 相互作用与靶点：STRING、Open Targets Platform。
  • 药物监管：openFDA Drugs@FDA。

连接器规范化 DOI、PMID、arXiv id 和 accession，并区分无结果、限流、认证、网络和来源错误。受许可限制的来源只保存查询、请求地址、响应哈希和允许保存的元数据。

新增 EMBL-EBI 连接器以官方公开接口为契约来源：Proteins API、InterPro API 和 BioStudies API。当前测试使用不含密钥的官方结构 fixture；受本轮 Codex 网络额度限制，四个新增入口仍需在可联网环境做最小真实响应复核。

外部 stdio 或 Streamable HTTP MCP 继续由 DSH 原生 MCP 客户端配置。本包另提供可独立启动的本地 stdio 服务：

dsh-science-mcp
npm run mcp:smoke

MCP 的 search、fetch 和 deep_search 也执行外传门禁：调用方必须提供现有 runId 以及实际请求 origin、数据类别完全匹配、允许且尚未使用的 egressDecisionId。普通查询按单请求批准；Deep Search 在检索规划后展示准确检索式、目标和最大请求次数，只允许消费一次有界批次授权。所有使用事件写回 run，HTTP 重定向不会自动跨到未经批准的来源。

独立 stdio MCP 提供 approve_egress，它使用 MCP form elicitation 让客户端向真实用户提问，模型不能自行批准。支持 elicitation 的宿主可由此创建单请求或有界 Deep Search 批次的 EgressDecision；不支持的客户端会得到 human-interaction-required。MCP 只暴露设置中启用的连接器，并把 search/fetch 响应登记为带哈希产物；缺少批准时网络工具返回 egress-confirmation-required。

连接器设置会实际限制 DSH 工具可用来源；禁用的来源不能通过显式参数绕过。fetch 无记录时返回分类后的 not-found，不会用请求 ID 伪造成功记录。

Web UI

插件向 DSH Web UI 注册：

  • Science 设置页：连接器、Reviewer、SSH/调度器、外传策略和凭据引用。
  • Science 会话页：Runs、Artifacts、Reviews、Literature / Evidence、Servers。
  • Science 会话页另显示 ResearchPlan 版本/哈希/步骤/人工决定，以及命名本地内核和执行单元。
  • 基于 artifactId 的 Markdown/代码/JSONL/CSV/TSV、FASTA、PDB/mmCIF、CLUSTAL、BED/GFF/VCF 预览，以及图像/PDF 实际渲染和哈希展示。非法结构或坐标文件会明确失败；截断字节不会伪装成完整下载。
  • Generated 汇总、命名内核的 CPU/RSS 样本、一次性命令与远程任务状态。
  • 可选 Better Sidebar 标签及表格、序列、结构、比对和基因组区间查看器。

凭据设置只接受诸如 env:NCBI_API_KEY 的引用，不保存密钥值。远程模块不读取 ~/.ssh 或私钥，只把设置中的 alias 交给系统 OpenSSH。证据综合和模型 Reviewer 需要当前 DSH 模型提供方暴露 Haiku 或 Sonnet；插件不会自动切换到 Opus。

开发与验证

npm run typecheck
npm test -- --run
npm run build
npm run mcp:smoke
npm pack --dry-run

关键入口：

src/index.ts            Cordis 宿主入口与审查 Hook
src/store.ts            文件、哈希、事件和恢复
src/workflow.ts         多维度、多轮 Deep Search
src/reviewer.ts         确定性审查与阻断状态机
src/connectors.ts       数据库连接器
src/remote.ts           SSH/Slurm/PBS 与同步
src/local-compute.ts    命名 Python/R 环境、单元账本和生成文件提升
src/harness.ts          ResearchPlan、人工计划门和步骤恢复
src/exporter.ts         报告、Notebook、证据、溯源和引用库导出
src/library.ts          项目内文献题录、文件溯源、去重与筛选
src/client/             DSH Web UI
skills/                 八个科研 Skills
openspec/changes/001-build-dsh-science-plugin/

安全与当前边界

  • 上传和下载默认不覆盖、不删除；路径逃逸和符号链接逃逸会被拒绝。
  • 上传从本地文件流向 SSH，下载直接流入排他创建的目标文件；stderr 和普通命令输出限制为 1 MB。真实超大文件与慢速链路仍需在目标集群复验吞吐和断点策略。
  • 普通 SSH 可由当前 DSH 会话停止本地连接，但远端进程是否终止不能可靠确认，因此 run 记录为 unknown，不会误报 cancelled；需要可靠取消和跨重启恢复的长任务应提交到 Slurm 或 PBS。
  • 本地内核或远程任务只要仍为活动状态或 unknown，Reviewer 与 run 完成门都会阻断交付；自动恢复失败后，必须由人先在操作系统/调度器中核实进程确已终止，再通过 resolve-unknown 写明核查依据。这个动作不会杀进程，也不能只靠模型自行放行。
  • 每张图必须登记 <图文件名>.qa.json，绑定已登记的绘图脚本、图和输入 SHA-256。首版确定性方法会从 CSV 重新读取指定数值列并与 QA 中的期望值比较；自报 passed 不会放行。通用像素内容与科学表达必须再通过 science_review visual-review 的人工问题门，确认会绑定当前图表 SHA-256；未确认保持 not-verifiable。
  • 格式正确的 DOI、PMID 或 accession 不能单独支持交付；每条支持证据还必须指向已登记、可重哈希的来源产物。失败的连接器请求同样写入 run 的 SearchRecord。
  • 本地文献库当前保存准确的人工题录、研究者提供的全文/许可状态与原文件哈希；PDF OCR、全文自动解析、页段自动抽取和 RIS/BibTeX 自动解析尚未实现。页码或段落只能作为研究者提供的 locator 留痕。
  • KEGG 等来源可能受许可或使用条款限制，使用者应按所属机构许可执行。
  • 首版不含全部科研 Skills、商业数据库、Modal 或 BioNeMo NIM。
  • macOS 是本版本的实际验证平台；Windows 实机与真实集群需在目标环境再次验收。

参考与许可

实现参考了 omdsh-dev/dsh-plugin-dev、dsh-plugin-skills、dsh-custom-tool、dsh-open-in-vscode、DSH-better-sidebar 和 dsh-deep-research 的 DSH 插件约定，并参考 OpenScience 的科研工作流能力范围。代码为独立实现，没有复制 OpenScience 源码。

本项目采用 MIT License。