Skip to main content

dsh-science

24Stars3Forks1Issues0Watchers

Claude Science-style research workbench: ReAct research-loop engine (research_* tools), versioned artifacts with provenance (artifact_* tools), and 10 science skills for genomics/pathogens/bioinformatics.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
JavaScript
License
MIT
Branch
main
dsh-plugindsh-plugins

Install

cmdweb profile
$ dsh plugin --profile web add dsh-science

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin biociao/dsh-science for me: review the repository at https://github.com/biociao/dsh-science first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

一句话定位

把 Claude Science 的整套科研工作台带到 DeepSeek Harness 上:维护一个 ReAct 式研究循环的状态机、把重要结果保存为带 SHA-256 校验与溯源的版本化工件、通过 SSH 把生信长时作业提交到实验室工作站或 HPC 集群并持续监控,再附带 11 个科研技能(文献/评审/论文撰写/并行委派/conda 环境等)。

核心能力

  • 持久化研究循环:在项目根生成 research-manifest.json 并维护"问题 → 假设 → 实验 → 观察 → 分析 → 结论 → 下一轮问题"的状态机,假设状态机强制经过 testing 才能得出 supported/refuted/inconclusive 结论;阶段只能前进,回退需显式开启 allowPhaseRewind
  • 版本化工件与溯源:把分析结果(数据表、图、模型输出)保存到 artifacts/<name>/v<N>/,流式计算 SHA-256、相同内容去重(硬链接,跨设备降级为复制)、记录命令/输入/环境/envFile 哈希到 provenance.md,可重算校验或生成复现指引
  • SSH 远程计算(16 个工具):通过 ~/.ssh/config 别名连接工作站或 HPC 集群,注册时自动只读探测(CPU/内存/GPU/CUDA/conda/sbatch/SLURM 分区),长时任务以 detached 进程或 sbatch 提交,断连不杀,状态自动迁移 succeeded/failed/killed;输出按大小阈值分流(≤100MB 拉回本地,超大文件留在主机并记录路径)
  • 项目级主机访问白名单:首次在某个项目使用某台主机会弹审批,批准后写入项目自己的 .dsh/remotes/allowlist.json,同工作区里的多个研究项目彼此独立、不互相授权
  • 远程主机设置页:浏览器里以页面形式增删改查 SSH 主机,宿主侧走 /dsh-science/remote-hosts/* REST API,与远程引擎共享同一份 hosts.json / allowlist.json / jobs.json
  • 配套模型分档路由(独立 bundle dsh-model-tier,按会话 opt-in):在会话模型选择器里注册虚拟 provider「智能分档」,把辅助请求(标题/压缩)与子任务分流到轻量档、复杂任务升级到强档,每档可指向不同 provider;未选中的会话零路由
  • 11 个科研技能:研究循环、项目初始化、工件溯源、科学评审(子代理对照执行记录核查论断)、文献连接、并行委派、论文撰写、生物信息工具箱、conda 环境、数据清单、远程计算

技术实现

  • 语言: Node.js ESM(.mjs),零第三方 npm 依赖的引擎源码;客户端用 React 18
  • 关键依赖: 无 npm 原生模块;宿主侧仅用 node:fs / node:path / node:os / node:crypto / node:child_process;远程能力依赖本机系统 OpenSSH 客户端(ssh / scp / 可选 sbatch / squeue / sacct / scancel)
  • 架构模式: DSH Cordis bundle —— 通过 cordis.patch.yml 在 profile 层插入 4 个 science 引擎(science-research-loop / science-artifact-registry / science-remote-compute / science-remote-hosts-ui)+ 配套的 model-tier / model-tier-ui,每个引擎都导出 name 和 inject(如 tools / webServer / llm)并通过 ctx.tools.register 注册工具;客户端 bundle 通过 package.json#dsh.client 注入;同一份源码另存为 agent preset(preset/engines/)用于"科学模式"会话
  • 入口文件: engines/remote-hosts-ui.mjs(作为 package.json 的 main,是 web 侧最先加载的入口);其余引擎 engines/research-loop.mjs、engines/artifact-registry.mjs、engines/remote-compute.mjs 由 cordis patch 装载

适用场景

做基因组、病原体、生物信息类研究的用户希望把"提问题 → 设计实验 → 跑分析 → 沉淀结果 → 引用与复现"这条工作流交由 AI 主导:插件负责把每一步的状态、文件、命令和环境哈希落盘,让会话中断后能恢复上下文,让长时生信作业能在工作站或 HPC 集群上无人值守跑完并归档结果。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.6(已实验验证)仓库 README 与 CI 均固定此版本做 bundle 验证;更高小版本一般兼容,破坏性变更需重新验证
Node.js>=18package.json#engines.node 声明 18+;冒烟/稳定性测试在 node 18/20 跑,bundle 验证用 node 22(dsh 0.1.0-rc.6 内部依赖 node:sqlite)
平台跨平台引擎本身是纯 Node;远程计算额外依赖本机 OpenSSH 客户端(macOS/Linux 自带,Windows 需 WSL 或 Git for Windows 的 ssh)和可用的 ~/.ssh/config 别名;远程主机侧零安装
原生模块无不依赖 npm 上的原生模块;远程能力仅复用系统已装的 ssh/scp/sbatch 等二进制

安装方式

dsh plugin --profile web add github:biociao/dsh-science

安装后需要在 profile 层重启(或刷新 Web GUI)让 4 个 science 引擎 + model-tier 引擎被装载。

配置项

插件的所有可调项都在 cordis.patch.yml 的引擎 config 块里——通过覆盖 profile 的 cordis.patch.yml(用 - update: [{id, config}])即可改写。常用项:

配置类型说明默认值
science-remote-compute.requireApproval布尔每次 remote_run 提交作业时是否弹审批true
science-remote-compute.requireHostAccess布尔首次在某项目使用某主机时是否弹授权审批true
science-remote-compute.hostsDir字符串主机注册表所在目录(hosts.json)$DSH_HOME/remotes
science-remote-compute.execTimeoutMs数字(毫秒)remote_exec 默认超时120000
science-remote-compute.markers字符串数组项目根识别标记(按优先级)["research-manifest.json",".dsh",".git"]
science-research-loop.allowPhaseRewind布尔是否允许回退循环阶段(默认只许前进)false
science-research-loop.markers字符串数组项目根识别标记[".dsh",".git"]
science-artifact-registry.maxFileBytes数字(字节)单个工件文件大小上限(超出会报错)8589934592(8 GiB)
science-artifact-registry.allowHardlink布尔相同内容是否用硬链接去重(跨设备自动降级为复制)true
*.lock.timeoutMs / *.lock.staleMs数字(毫秒)文件锁等待与陈旧锁回收阈值10000 / 30000
model-tier.tiers.{strong,default,light}{provider, model, reasoningEffort?}三个档位对应的真实模型,可跨 provider见 cordis.patch.yml 示例
model-tier.routing.auxiliary字符串数组视为"辅助请求"的 purpose 列表["session-title","compaction"]
model-tier.routing.subagents字符串子任务路由档位(如 "light")或不路由"light"
model-tier.routing.subagentDepthStrong数字深链子任务升级强档的深度阈值null(关闭)
model-tier.routing.escalateOnChars数字单步用户输入超过多少字符升级强档null(关闭)
model-tier.routing.classify布尔/对象是否启用 LLM 前置分类器(按复杂度再分档)null(关闭)
model-tier.enabled布尔总开关,关闭则选择器里不出现「智能分档」true

注册主机时还可以针对单台机器覆盖 scratch(作业根目录)、maxConcurrent(并发作业上限,默认 100)、timeoutMinutes(默认作业超时,默认 30)、bigFileThresholdBytes(超过此大小的文件不被拉回本地,默认 100 MB)等参数,详见 remote_host_add 工具说明。

常见问题

Q: 安装后 DSH 必须重启吗?

A: 需要重启 profile(或刷新 Web GUI)才能让 cordis.patch.yml 里的 4 个 science 引擎以及 model-tier / model-tier-ui 引擎生效;之后改 artifacts、改研究状态、跑作业都不需要再重启。远程主机设置页(science-remote-hosts-ui)首次启用也需要一次重启,让客户端 bundle 被注入到 Web UI。

Q: 远程主机设置页看不到怎么办?

A: 对应 science-remote-hosts-ui 引擎。检查两点:1)cordis.patch.yml 里 science-remote-hosts-ui 行的 name 必须是包根名 dsh-science(客户端 bundle 按此定位 dsh.client 声明);2)profile 重启后才会出现在设置侧栏。宿主侧 REST API 在 /dsh-science/remote-hosts/*,POST-only 且要求同源。

Q: remote_run 提交后连接断开,作业会丢吗?

A: 不会。工作站模式用 nohup + setsid 启动 detached 进程(断连不杀),SLURM 集群用 sbatch 提交;作业目录在主机的 scratch 下,本地 remote_status 通过 ssh/squeue/sacct 重探测并把状态写回 <项目根>/.dsh/remotes/jobs.json,跨会话持续。remote_pull 结束后标准动作链是:remote_status(确认终态)→ remote_pull → artifact_save → research_findings。

Q: SSH 主机需要装什么额外软件吗?

A: 不需要。引擎只依赖本机的 ssh/scp/可选 sbatch/squeue/sacct/scancel 二进制(系统 OpenSSH),主机侧零安装。但本机必须先在 ~/.ssh/config 里配好别名(或用 user@host),并确保密钥已配好(推荐 ssh-agent + BatchMode=yes);不要把密码写进任何工具参数。

Q: 怎么避免每次都弹审批?

A: 首次在某项目使用某主机(注册/探测/exec/run)会弹一次授权审批,批准后该主机写入项目自己的 .dsh/remotes/allowlist.json(按项目隔离),同项目不再询问;之后每次 remote_run 仍默认弹"Run this job on ?"作业审批。CI/无人值守场景在 cordis.patch.yml 的 science-remote-compute 引擎 config 里把 requireApproval 与 requireHostAccess 都设为 false 即可同时关掉两道审批。

Q: research_* 工具什么时候该用?

A: 进入一个科研项目时先调 research_init(创建 research-manifest.json + 项目目录骨架,包括 experiments/、literature/、artifacts/、analyses/、figures/、manuscript/、reviews/、data/、envs/)。之后每轮迭代按 research_hypothesis(H1/H2/…)→ research_experiment(自动分配 E01、E02…,关联假设进入 testing)→ 写代码跑实验 → research_findings(追加观察日志、可推进假设状态、设下一轮问题开启新 iteration)。research_state 任何会话开始先看一次可恢复上下文。

Q: 工件和实验日志有什么区别?

A: 实验目录 experiments/E0X/{design.md,log.md,code/,results/} 记录一次实验的完整执行;artifact_save 则把"值得引用或复现"的结果归档到 artifacts/<name>/v<N>/,每个版本带流式 SHA-256、相同内容自动去重(硬链接)、溯源信息(命令/输入/输入哈希/环境/envFile 哈希)追加到 provenance.md,可随时 artifact_verify 重算校验或用 artifact_reproduce 输出复现指引。

Q: 卸载会影响现有项目数据吗?

A: 引擎只读写 research-manifest.json、artifacts/、.dsh/remotes/ 这些目录与文件;从 cordis.patch.yml 移除插件行并重启后,项目数据原样保留;想彻底清理可用 dsh plugin remove 后手动删除项目里的 .dsh/、artifacts/ 等目录。

上手难度

进阶 — 安装一行命令就能用默认档位,但要真正发挥作用需要:先在 ~/.ssh/config 配好 SSH 别名与免密登录,理解项目级白名单与作业审批的"按项目隔离"语义,并根据团队实际 provider 替换 model-tier 示例档位;首次跑通一次完整的"研究循环 + 远程作业 + 工件归档"流程后才算熟悉。

已知问题与限制

  • 远程能力依赖本机系统 OpenSSH 客户端(ssh/scp/可选 SLURM 命令),Windows 需 WSL 或 Git for Windows 提供 ssh;主机侧零安装但不提供图形化的 SLURM 队列管理,所有 SLURM 操作经 ssh 调用 squeue/sacct/scancel
  • 拿不到会话工作目录(agent.session.header.cwd)时,远程工具要求显式传 root=;否则走"项目根不可解析"分支并 fail-closed(不会回退到 process.cwd(),避免跨项目共享白名单/作业)
  • 刚提交 20 秒内的作业在 remote_status 里会被宽容处理,不会被误报为 unknown;之后状态机才会自动迁移 running → succeeded/failed/killed
  • remote_run 的作业超时默认 30 分钟、最长 10080 分钟(7 天);timeoutMinutes 必须为 1–10080 的整数,超长任务需显式给超时
  • 拉回本地的输出按 100 MB 阈值分流:小于等于阈值的文件 scp 拉回本地并写入 pulled-manifest.json,超过的文件路径记录在 bigFiles,需要时可用 remote_exec 手动下载
  • 单个工件文件大小上限 8 GiB(maxFileBytes),超过会报 ERR_QUOTA;同内容默认用硬链接去重,跨设备自动降级为复制(allowHardlink: false 可关闭)
  • 模型分档路由的分类器目标建议选非 thinking 模型:thinking 模型的推理内容同样消耗 maxTokens 额度(默认 512),曾出现把额度用光导致拿不到分类词的情况
  • 跨档位混用历史时,若 thinking 模式目标因历史工具调用消息缺 reasoning_content 拒绝请求,引擎会自动补占位推理块透明重试一次(日志有 warn)
  • 模型分档路由在选中「智能分档」后的极短窗口内新建会话可能"继承"分档(平台把会话模型选择写到了全局默认模型),属已知 best-effort 限制;其他时刻未选中的会话零路由
  • 远程主机设置页的客户端 bundle 由 scripts/build-client-bundle.mjs 打包到 client/remote-hosts-ui/lib/client.js,发布前需运行 npm run build:client,否则设置页可能不出现

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/biociao/dsh-science)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory