科研工坊 raktim-mondol/dsh-researchcraft

dsh-researchcraft

ResearchCraft 作为 DeepSeek Harness 配置文件：DSH Web UI 和 DSH agent，配备 ResearchCraft 的科学技能、实时实验室笔记本和专家子代理。

安装

1. 首先安装 DeepSeek Harness（dsh）。按照该仓库的 README 操作——例如：

npm install -g @deepseek-ai/dsh

或者无需全局安装直接运行：npx @deepseek-ai/dsh web。在进行下一步之前，你需要一个可用的 dsh CLI。

2. 然后添加此插件：

dsh plugin --profile researchcraft add github:raktim-mondol/dsh-researchcraft

这会创建 researchcraft DSH 配置文件（如果尚不存在），并将插件添加到其中。

更新到最新版本：

dsh plugin --profile researchcraft update dsh-researchcraft

改为从本地检出安装（用于插件开发）：

dsh plugin --profile researchcraft add /path/to/dsh-plugin

该配置文件还必须在此 bundle 之前列出 @deepseek-ai/dsh-web-app。

运行

dsh --profile researchcraft
或者，如果你使用共享启动器： dsh-researchcraft

打开 Harness Web UI（通常为 http://127.0.0.1:3080）。

一次只能运行一个 DSH 界面。 dsh-web、dsh-tui、dsh-martty 和 dsh-researchcraft 共享 $DSH_HOME（包括端口 3080 和 zvec-grep 守护进程）。Ctrl+C 并不总是等待它们退出，因此当其中一个仍在后台运行时启动另一个启动器会失败或选错进程。共享启动器（scripts/dsh-launch，安装为上述四个命令）会在 exec 之前停止残留的 DSH 进程并执行 zg server off。如果你直接调用 dsh --profile …，请先停止前一个：

残留的 Web UI ss -ltnp | grep 3080 残留的 zg 守护进程 zg server off

切换到 dsh-tui / dsh-web 还会清除已保存的全局 agent-presets 默认值 researchcraft。该默认值位于 ~/.dsh/settings.yaml 中，并在各配置文件之间共享——dsh-tui 不附带 dsh-researchcraft/ 插件，因此使用该默认值启动会导致 agent 崩溃。ResearchCraft 配置文件仍会从其自身的补丁中默认使用 ResearchCraft 预设。

为每个对话选择 ResearchCraft agent 预设。 安装此插件会在 agent 预设选择器中添加一个 ResearchCraft* 选项——它不会替换你当前的默认预设（通常是 "Standard mode" / "PTC mode"）。新对话会以该默认值启动，而不是 ResearchCraft，直到你明确选择它：

1. 启动一个新会话。
2. 点击消息框顶部的预设选择器（默认显示 "PTC mode"、"Standard mode" 或类似内容）。
3. 从列表中选择 ResearchCraft。
该角色设定、较长的研究系统提示词（笔记本规范、专家名册、连接器指南等）、学术搜索（mcp__parallel__、parallel_search、mcp__firecrawl__、mcp__scite__、consensus_search）、PaperMemory（mcp__papermemory__）、工作区语义搜索（mcp__zvec_grep__zvec_grep_search）以及 paper_mcp（Paper2Agent stdio 挂载）仅存在于该预设中——停留在默认预设的会话将不具备这些功能，要求它使用例如 Parallel 连接器将失败并报错 tools[name] is not a function。以下通用工具（notebook、image_generate、sci_inspect、latex_compile、pdf_to_markdown、modal_run/runpod_run、workflow）在所有预设中均可用，因为它们是在插件/捆绑包级别注册的，而非在 ResearchCraft 预设内部。原生 grep / glob 来自 ResearchCraft 预设的文件系统搜索行。

预设选择器会按浏览器记住你的上次选择，因此通常你只需执行一次此操作。

它添加了什么

- ResearchCraft 代理预设——角色设定、研究系统提示词（笔记本规范、专家名册、连接器指南）、标准编码工具，以及下方的学术搜索连接器。在每个聊天中显式选择它——参见运行。
- 科学技能目录从开源目录收录到 skills/ 中，与下方的专家简报一样随插件捆绑——无需单独检出或设置（参见 NOTICE 了解与各来源相比具体更改了哪些内容）：
- 140 个领域技能（化学、基因组学/生物信息学、成像、统计、机器学习、写作等）——scientific-agent-skills
- 16 个研究学科/方法论技能（问题构建、预注册、声明前验证、红队评审等）——science-superpowers
- 503 个特定职业的专家推理技能（加速器物理学家、动物学家、精算科学家等），从 AGENTS.md 配置文件转换而来——scientific-agents
- 23 个小分子/蛋白质治疗技能（autodock-vina、逆合成、蛋白质结合剂设计等）——drug-discovery-agent-skills
- 一个 docx-editor-zotero 技能（编辑 .docx 文件而不破坏 Zotero 引用）——改编自 claude-scientific-writer
- 一个 agentic-data-science-pipeline 技能（用于大型多阶段任务的计划/评审/实现/验证/反思循环）——改编自 agentic-data-scientist
- 一个 hyperparameter-optimization 技能（用于调优深度学习/大语言模型的预注册、声明前验证搜索循环）——改编自 karpathy
- 一个 scientific-figure-making 技能（出版级 matplotlib 内部样式 + 用于柱状图/趋势图/热力图的辅助工具）——改编自 figures4papers
- 一个 diagram-design 技能（39 种编辑级 HTML+SVG 图表类型；拒绝 Mermaid 式的粗制滥造）——取自 diagram-design
- 一个 generating-scientific-hypotheses 技能（基于文献的假设生成：经检索核验的新颖性、排序后的可证伪卡片）——第一方技能，提炼自 Gottweis et al. / Ghareeb et al. 2026（见 NOTICE）
- 一个 paper2agent 技能（将一篇论文和/或其代码仓库转化为经过审阅的论文技能，以及一个经过测试的 FastMCP 服务器）——取自 Paper2Agent——见 论文智能体

RESEARCHCRAFT_SKILLS_DIR（或 ~/scientific-agent-skills/skills 检出目录）仍可作为覆盖项使用，如果你想要一个不同的目录集合——在每个预设中均可用
- notebook 工具——记录、读取并导出实时实验记录本（JSONL 位于 /.dsh/notebook/ 下），在子智能体委派树中共享，并支持与纯 Markdown 导出并行的 zip 打包导出——每个预设
- scientific_result 工具——一张结构化、经模式校验的“最终发现”卡片（表格或统计检验），与实验记录本的运行日志不同——每个预设
- 面向 DSH subagent 工具的专家简报（code-reviewer、literature-researcher 等），外加 subagent_pro 和 subagent_vision——另外两个委派工具，分别固定到不同的模型，用于异常繁重的推理任务和图像阅读任务——见 子智能体模型路由——每个预设
- image_generate 工具，用于概念性科学图表（默认使用 Gemini “nano banana”）——每个预设
- sci_inspect 工具，用于科学文件格式（化学、结构、质谱、数组、成像、AnnData）——每个预设
- latex_compile 工具（.tex → PDF，可识别 bibtex/biber）——每个预设
- pdf_to_markdown 工具（PDF → Markdown，通过 pdf-inspector），用于将下载的论文转换为文献综述——每个预设
- modal_run / runpod_run 工具，用于远程 GPU/CPU 计算卸载，外加捆绑的 modal/runpod 技能，覆盖每个 CLI 的其余部分（Serverless 端点、卷/密钥、Hub 模板等）——见 远程计算——每个预设
- research_template 工具，基于约 330 个研究任务模板的目录（不是 DSH 的 Rhai workflow 编排器）——每个预设
- 学术搜索：Parallel、Firecrawl、Scite（MCP 连接器）、parallel_search / consensus_search（原生 REST 工具），以及 paper_download（Unpaywall 开放获取 PDF 解析器）——仅 ResearchCraft 预设
- paper_mcp 工具——从当前工作区注册一个 Paper2MCP stdio 服务器（/.dsh/paper-mcps.json），使其工具以 mcp____ 的形式出现——仅限 ResearchCraft 预设——参见 Paper agents
- PaperMemory 本地学术记忆：mcp__papermemory__（search、ingest、cite、cite-check、recap、remember、claim）。首次启动 ResearchCraft 时使用 PATH 上的 papermemory，或将内置包安装到 ~/.dsh/papermemory。paper_download 会自动摄取已保存的 PDF。存储位置：~/.local/share/papermemory/papermemory.db——仅限 ResearchCraft 预设——参见 Paper memory
- 通过 zvec-grep 进行工作区语义搜索：mcp__zvec_grep__zvec_grep_search（本地 BM25 + 向量）。首次启动 ResearchCraft 时会将 zg CLI 安装到 ~/.dsh/zvec-grep。默认在会话开始时关闭索引（Settings → Index at session start）；你可以稍后从聊天中建立索引，当语义搜索有帮助时，agent 会先询问。索引期间会显示带预计时间和 Cancel 的进度条（无超时）——精确查找仍使用原生 grep / glob——仅限 ResearchCraft 预设——参见 Workspace search
- 内置的 agent-browser 技能，用于交互式网页浏览（导航、登录、填写表单、下载数据集），截图委托给 subagent_vision——参见 Browsing the web——所有预设均适用
- 一个 Settings → ResearchCraft API keys 页面，用于上述连接器和模型——无需 shell 环境变量。PaperMemory 不需要密钥。

API keys

以下每个凭据（PARALLEL_API_KEY、FIRECRAWL_API_KEY、CONSENSUS_API_KEY、SCITE_API_KEY、UNPAYWALL_EMAIL、GEMINI_API_KEY、MODAL_TOKEN_ID、MODAL_TOKEN_SECRET、RUNPOD_API_KEY、ZVEC_GREP_API_KEY）都可以通过两种方式设置：

- DSH Web UI 中的 Settings → ResearchCraft API keys——输入密钥，点击 Save。持久化到配置文件的 settings.yaml 中；空白字段始终表示“保留当前值”，Clear 会将其移除。
- Shell 环境变量——当两者都设置时，优先于 Settings。
同一个设置页面还有一个用于 IMAGE_MODEL 的 Image model 下拉菜单——它不是凭据，因此不会以密码方式掩码，并且在选择后立即生效，无需点击 Save（参见图像生成）。它还有另外两个模型 ID 下拉菜单，Complex-task model（SUBAGENT_MODEL_COMPLEX）和 Image-reading model（SUBAGENT_MODEL_VISION）——它们也不是凭据，但这两个的行为与下面的 MCP 连接器类似，而不像 Image model：它们需要重启才能生效（参见子代理模型路由）。zvec-grep embedding（ZVEC_GREP_EMBEDDING）也是同样需要重启的下拉菜单：它在挂载时被传入 zg server on。Index at session start（ZVEC_GREP_AUTO_INDEX，默认 No）对下一个 ResearchCraft 会话即时生效——无需重启（参见工作区搜索）。

每次调用时都调用 resolveEnv() 的工具（image_generate、modal_run、runpod_run、consensus_search、parallel_search、paper_download）会在下一次调用时立即获取到 Settings 的更改，无需重启。

MCP 连接器（Parallel、Firecrawl、Scite、zvec-grep、PaperMemory）以及两个子代理模型字段则不同：researchcraft 代理预设作为常驻组合只挂载一次，在运行中的 dsh 进程的整个生命周期内由每个聊天会话共享，因此更改只有在停止并重启 dsh 本身之后才会到达它们——在同一运行进程上新建聊天会话是不够的。consensus_search 和 parallel_search 不是 MCP 连接器——见下文——因此它们没有这一重启要求。

还要确保聊天会话确实处于 ResearchCraft 预设上。 MCP 连接器、原生学术搜索工具（consensus_search、parallel_search）、mcp__zvec_grep__zvec_grep_search 以及 mcp__papermemory__ 只接入 researchcraft 代理预设；留在默认预设（Standard/PTC 等）上的会话没有这些工具，调用其中之一会失败并报 tools[name] is not a function。在要求代理进行搜索之前，请检查会话标题旁的预设选择器（新聊天在消息框顶部，已有聊天在左上角）显示为“ResearchCraft”。

工作区搜索

zvec-grep（zg）是 ResearchCraft 预设上的本地优先混合搜索层：在磁盘索引上运行 BM25 + 向量，以 mcp__zvec_grep__zvec_grep_search 的形式暴露。精确词、引号、标识符、文件名、正则表达式以及详尽命中列表仍使用该预设的原生 grep / glob（@deepseek-ai/dsh-tool-fs-search）。开放网络和文献搜索仍使用 Parallel / Consensus / Firecrawl / Scite——zg 仅限工作区。
你不需要自己安装 zg。在 dsh plugin add 之后，ResearchCraft 预设首次挂载时，插件会运行 npm install --prefix ~/.dsh/zvec-grep @zvec/zvec-grep@^0.2.2，启动 zg server on（回环守护进程），并通过 Streamable HTTP 在 http://127.0.0.1:7999/mcp 上挂载搜索——无需第二次重启。首次启动可能需要几分钟（npm 加上之后约 130 MB 的 Potion 模型）。之后的启动会复用 ~/.dsh/zvec-grep，如果捆绑副本早于 0.2.2 则将其升级，并再次启动守护进程。停止 dsh 会运行 zg server off，因此守护进程不会在后台保持运行。如果你已有想保留的 zg 二进制文件，可用 ZVEC_GREP_CLI 覆盖。如果安装或守护进程失败，预设的其余部分仍会加载，搜索工具则不可用（会记录一条警告）。

插件通过 HTTP 与守护进程通信（DSH 的 MCP 客户端是 Streamable HTTP），而不是 zg server --stdio。0.2.2+ 还修复了 stdio 心跳竞态问题（zvec-grep#106）；HTTP 仍是我们使用的挂载方式。

索引是选择性启用的。设置 → ResearchCraft API 密钥 → 会话开始时索引默认为否。当为否（默认值）时，新聊天不会建立索引；你仍然可以在聊天中输入“index this workspace”，并且每当语义搜索会有帮助时，智能体会先询问（只有你同意才会建立索引）。当为是时，打开 ResearchCraft 会话会在后台为该工作区建立索引（如果尚不存在索引）（zg index --embedding local/potion-retrieval-32m，本地，无需 API 密钥）。

当索引运行时——无论是从会话开始还是从聊天触发——UI 会在设置和会话标题栏中显示带预计时间的进度条，并且取消始终可用。没有超时。现有索引不会被改动（不会静默重建/删除）。主目录和 / 不会被索引。索引位于 /.zvec-grep/；模型缓存为 ~/.zvec-grep/models（一次约 130 MB）。

仅当你想手动建立索引或选择其他本地模型时 zg index --embedding local/potion-retrieval-32m # 默认——论文 / 笔记 / 混合内容 zg index --embedding local/potion-code-16m-v2 # 更小（约 65 MB 模型），代码密集型目录树 zg status --check-ready

每次 MCP 调用都需要一个绝对 root（会话工作目录）。相对路径会失败。原生 zvec_index 工具（start / status / cancel）是智能体使用的工具，而不是通过 shell 调用 zg index。

| 设置 / 环境变量 | 作用 |
| ZVEC_GREP_AUTO_INDEX | yes / no。当 ResearchCraft 会话打开时为此工作区建立索引。默认 no。对下一个会话生效（无需重启）。 |
| ZVEC_GREP_EMBEDDING | 新索引的默认模型 id。未设置表示 local/potion-retrieval-32m。现有索引保留其存储的模型。更改后重启 dsh——下次启动会以新值启动一个全新的守护进程。 |
| ZVEC_GREP_API_KEY | 不使用，默认使用本地 Potion 模型。仅当你选择启用远程（Qwen）嵌入提供程序时才需要。 |
| ZVEC_GREP_CLI | zg 或 @zvec/zvec-grep 的 dist/cli/index.js 的绝对路径。仅通过环境变量设置。 |

~/.zvec-grep/daemon/ 下的回环守护进程以 ResearchCraft 预设启动，并在 dsh 退出时停止。你无需手动执行 zg server off。

面向 agent 的安装、索引和路由细节包含在捆绑的 zvec-grep 技能中（skills/zvec-grep）。

学术搜索

三个文献/网络 MCP 服务器已接入 researchcraft 预设，并以 mcp__parallel__、mcp__firecrawl__、mcp__scite__ 工具的形式呈现：

| 连接器 | 密钥 | 没有它时 |
| Parallel — mcp__parallel__web_search（搜索回退，始终为 basic）和 mcp__parallel__web_fetch（读取 URL） | PARALLEL_API_KEY（必需） | 连接器保持禁用。该密钥始终作为 Bearer token 发送，因此 MCP 调用不受匿名速率限制。 |
| Firecrawl — 抓取/爬取/提取 | FIRECRAWL_API_KEY（可选） | 无需密钥即可使用，但受速率限制 |
| Scite — 智能引用、撤稿/更正检查、证据数据集（专利、临床试验、基金、药物安全性等） | SCITE_API_KEY（必需） | 连接器保持禁用 |

parallel_search 是主要的 Parallel 搜索工具：对 POST /v1/search 的原生 REST 调用（x-api-key 认证）。它需要 PARALLEL_API_KEY，并且每次调用都必须指定 mode。mcp__parallel__web_search 是同一搜索任务，但锁定为 basic —— 只有当 parallel_search 缺失或出错时，agent 才会被引导使用它。mcp__parallel__web_fetch 用于读取特定 URL，而非用于搜索。传入 objective、1–5 个关键词 search_queries 和 mode：

| 模式 | 延迟 | 最适合 |
| turbo | ~250ms | 简单事实查询、当前数字、大批量预筛选。仅支持英语和日语查询。 |
| fast | ~700ms | 大多数 agent 循环的推荐默认值（交互式查询、工具调用）。 |
| basic | ~1s | 每个来源的摘录更长；2–3 个高质量查询。与 MCP 搜索工具始终使用的模式相同。 |
| advanced | ~3s | 用于文献综述、深度研究、代码审查背景的多跳检索。 |

系统提示会引导 agent 对同行评审文献同时使用 consensus_search 和 parallel_search（basic 或 advanced），仅对普通的非文献查询使用 fast，并且仅当 parallel_search 不可用时才将 mcp__parallel__web_search 用作回退。在 Settings 中更改 PARALLEL_API_KEY 会在下一次 parallel_search 调用时生效；MCP 连接器仍需要重启 dsh。
Consensus 是一个原生 consensus_search 工具（不是 MCP 连接器），基于其 GET /v1/search REST API——使用简单的 x-api-key 认证，无需 OAuth。需要 CONSENSUS_API_KEY（必需——未设置时该工具会返回明确的错误，而不是禁用连接器）。支持该 API 的完整筛选集：研究类型、年份/月份范围、样本量、期刊分区（SJR）、引用次数、研究时长、领域、国家、出版商、开放获取/预印本/人类/对照/临床指南标志，以及分页。

Unpaywall 为 paper_download 提供支持（同样是一个原生 REST 工具，不是 MCP 连接器）：给定一个 DOI，它会解析出最佳的开放获取位置，该工具会将该 PDF 直接下载到工作区（或者下载你已有的直接 URL，无需 DOI）。需要 UNPAYWALL_EMAIL——Unpaywall 的 API 要求调用者用真实的联系邮箱表明身份；未设置时该工具会返回明确的错误，而不是禁用连接器，并且绝不会替你编造一个。当某个 DOI 没有开放获取副本时，该工具会返回一个普通的“付费墙”结果（附带落地页 URL），而不是错误——引导 agent 如实报告这一点，而不是从搜索摘要中推断论文内容。保存前还会将响应与 PDF 魔数字节进行校验，因此当返回的是登录/CAPTCHA 页面而非真实文件时，会显示为明确的错误，而不是损坏的“PDF”。成功下载后会摄取到 PaperMemory（参见 论文记忆）；摄取失败不会导致下载失败。

论文记忆

PaperMemory 是 ResearchCraft 预设上的本地学术记忆层：论文（标题、作者、年份、发表场所、DOI、arXiv、bibtex 键）、带引用证据的主张、引用图谱、手稿回顾和引用核查。它让 agent 记住已读过的论文并在引用时不编造参考文献——开放网络和同行评审的发现仍由 Parallel / Consensus / Firecrawl / Scite 负责。

你不需要自己安装 PaperMemory。在 dsh plugin add 之后 ResearchCraft 预设首次挂载时，如果 PATH 上已有 papermemory，插件会直接使用它，否则通过 uv（或 python -m venv + pip）将内置包（含 pypdf）安装到 ~/.dsh/papermemory。然后它通过 stdio（papermemory mcp）挂载 mcp__papermemory__——无需第二次重启。如果安装或 MCP 握手失败，预设的其余部分仍会加载，记忆工具则缺失（会记录一条警告）。如果你已有想保留的二进制文件，可用 PAPERMEMORY_CLI 覆盖；PAPERMEMORY_SKIP_INSTALL=1 会跳过捆绑的 venv。

SQLite 存储是 PaperMemory 的默认方式：~/.local/share/papermemory/papermemory.db（可覆盖 PAPERMEMORY_DB 或 PAPERMEMORY_DATA_DIR）。独立的 papermemory CLI、Grok 和 ResearchCraft 共享同一个数据库。无需 API 密钥。

| 工具 | 功能 |
| mcp__papermemory__papermemory_recap | 写作项目简报：目标venue、章节、贡献、引用缺口 |
| mcp__papermemory__papermemory_search | 对论文、论断、片段、笔记、经验教训进行混合搜索 |
| mcp__papermemory__papermemory_ingest | 摄取本地 PDF/BibTeX/markdown/手稿路径，或 arXiv id / DOI |
| mcp__papermemory__papermemory_get | 按 id 或 bibtex key 获取论文，附带论断和片段 |
| mcp__papermemory__papermemory_cite | 查找已存储的论文以进行引用。结果为空意味着不要编造引用 |
| mcp__papermemory__papermemory_cite_check | 将手稿的正文引用键与记忆库进行比对 |
| mcp__papermemory__papermemory_remember | 保存一个写作/阅读决策 |
| mcp__papermemory__papermemory_claim | 存储一个论断，可选附带证据引文 |
| mcp__papermemory__papermemory_lesson | 保存一条持久的学术写作/阅读规则 |

paper_download 会对保存的 PDF 调用 ingest（如果给出了 DOI，还会处理 DOI 元数据）。在论文写作任务中，agent 会被引导去使用 recap，只引用记忆库中的命中结果，并在将某个章节视为完成之前先执行 cite_check。加载捆绑的 papermemory 技能（skills/papermemory）以获取完整工作流。

论文 agent（Paper2Agent）

捆绑的 paper2agent 技能（jmiao24/Paper2Agent，MIT）可将一篇论文和/或其代码仓库转化为 (1) 一个经过审查的紧凑论文技能，以及 (2) 一个经过测试的、包含该论文方法的 FastMCP 服务器。当用户要求将论文 agent 化时，使用 skill 工具加载它。它不能替代 pdf_to_markdown（快速、未经审查的提取），也不能替代诸如 scanpy 之类的目录技能（操作指南）。

完整的仓库转换耗时很长（许多 subagent 专家加上独立验证者）。agent 应先确认范围。在获得经过验证的 ZIP 后，仅在要求时连接服务器，在 ResearchCraft 预设上使用原生 paper_mcp（register / status / unregister）。这会写入 /.dsh/paper-mcps.json（解释器、服务器脚本、环境变量名称——绝不包含密钥），并尝试通过 stdio 挂载服务器，使工具以 mcp____ 的形式出现。这些挂载在 dsh 的整个生命周期内持续存在，与 Parallel/Scite 相同：如果工具没有出现，请重启 dsh。如果另一个工作区复用了相同的 serverName，也需要重启。

不要运行 claude mcp add。GPU 论文使用 runpod_run / modal_run，而不是静默回退到 CPU。

| 设置 / 环境变量 | 作用 |
| PAPERMEMORY_CLI | papermemory 二进制文件的绝对路径。仅通过环境变量设置。 |
| PAPERMEMORY_DB / PAPERMEMORY_DATA_DIR | 覆盖 SQLite 存储位置。仅通过环境变量设置。 |
| PAPERMEMORY_PROJECT | paper_download 自动摄取的默认项目 slug。仅通过环境变量设置；否则使用工作区目录名。 |
| PAPERMEMORY_SKIP_INSTALL | 设为 1 以跳过安装捆绑的 venv（PATH / PAPERMEMORY_CLI 仍然有效）。 |

浏览网页
内置的 web_search 可用（DeepSeek 搜索提供方）。内置的 web_fetch 不可用——没有 fetch 提供方，因此它会以 WEB_PROVIDER_UNAVAILABLE 失败。要抓取 URL，agent 会使用 mcp__firecrawl__firecrawl_scrape（Firecrawl 的抓取）或 mcp__parallel__web_fetch。对于任何需要真实渲染浏览器的事情——交互式探索网站、登录、填写表单、点击进入数据集下载，或验证页面是否确实正确渲染——agent 会加载捆绑的 agent-browser 技能（skills/agent-browser，以与上述技能相同的方式随附并预置），并通过 bash 直接驱动 agent-browser CLI。该 CLI 并未与此插件的包捆绑在一起，但 agent 会在缺失时自行安装（npm i -g agent-browser && agent-browser install，或对于一次性任务使用 npx agent-browser@latest ...），而不是要求用户安装。

它所做的大部分事情——导航、阅读、填写表单、提取数据、下载文件——都基于无障碍树快照工作，完全不需要图像。唯一的例外是 screenshot：由于会话自身的模型不保证具有视觉输入，该技能会引导 agent 将读取任何截图的任务委托给 subagent_vision（参见 Subagent model routing），而不是对其内容进行猜测。

通过 Settings → ResearchCraft API keys 或匹配的环境变量设置其中任意一项（参见 API keys）。SCITE_API_KEY 是来自 scite.ai/users/me/api 的 mcp 作用域密钥——这是 Scite 自己记录的面向 MCP 客户端的非交互式路径，作为 bearer token 发送到 https://api.scite.ai/mcp（无 OAuth 或令牌交换）。Scite 也提供 OAuth 流程，但仅适用于其第一方 ChatGPT/Claude 插件和其他交互式客户端——与此处无关。

Subagent model routing

除了普通的 subagent/subagent_fork 委托工具外，researchcraft 预设还添加了两个工具，它们通过 agentOptions.model 将委托的子任务固定到特定模型，这样 agent 就可以将任务路由到适合它的模型，而不是在当前聊天会话碰巧使用的任何模型上运行所有内容：

| Tool | Use it for | Model (Settings or env) | Default |
| subagent | 普通的委托工作——大多数专家调用 | —（继承父会话的模型） | — |
| subagent_pro | 难度而非长度是瓶颈的任务：困难的证明/推导、因果推断或实验设计批评、追踪细微的方法论缺陷、多步反应/通路推理、大型多文件重构 | SUBAGENT_MODEL_COMPLEX | deepseek-flash |
| subagent_vision | 需要使用 read_image 看到某些内容的委托任务——图表、扫描件、示意图、截图或渲染后的 LaTeX PDF 页面 | SUBAGENT_MODEL_VISION | deepseek-flash |
两个固定工具都默认使用 deepseek-flash（DeepSeek-V4.1-Flash）。旧名称 deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 仍被 API 接受，但这些模型已退役，其请求由 Flash 处理。

subagent 被有意设置为不固定模型：将每一次常规委派都强制到一个硬编码的模型 id 上，会在该 id 未注册于会话所用提供商的情况下直接破坏委派。只有两条升级路径被固定，且仅在 agent 选择使用特定模型而非回退到它当前所用模型时才会生效。

系统提示词引导 subagent_pro 关注难度而非长度：逐步验证数学推导或在多阶段计算中传播不确定性、因果推断批判（发现隐藏的混杂因素、权衡多项研究中相互矛盾的证据）、追踪贯穿多个相互关联部分的细微方法学缺陷（多阶段 ML 流水线中的数据泄漏、静默出错的嵌套交叉验证设置）、多步反应机理或通路推理，以及需要保持大量调用点一致的大型多文件重构。它明确引导避开常规审查、查找、简单数据验证或文献检索，因为这些任务在普通 subagent 上以极低的成本和延迟就能获得同等质量。

subagent_vision 仅将子任务路由到某个模型；子任务仍会自行调用 read_image（@deepseek-ai/dsh-tool-fs），而该工具会拒绝读取图像，除非调用路由解析出的模型在本部署的模型目录中确实声明了 image 输入——请选择一个以该方式注册的 SUBAGENT_MODEL_VISION 值。

Beyond a plain "look at this image" request, the system prompt steers the agent to delegate to subagent_vision for scientific reading tasks specifically: interpreting a plot or trend, comparing panels in a multi-panel figure, reviewing a microscopy/gel/medical-imaging scan for qualitative features, checking a chemical structure/phylogenetic tree/pathway diagram for correctness, and comparing a generated figure against what was asked for. It also covers a case text tools can't: auditing a compiled LaTeX PDF's page layout — a table split across a page break, a table or figure that drifted into the references section, an overfull line, a caption stranded from its figure — since read_image only accepts PNG/JPEG/WebP/GIF, the agent renders the PDF pages first with pdftoppm -png -r 150 file.pdf page (poppler, usually already present alongside TeX Live) before delegating.

Set SUBAGENT_MODEL_COMPLEX/SUBAGENT_MODEL_VISION via Settings → ResearchCraft API keys (two more dropdowns beside Image model) or the matching env var — env wins when both are set, same resolution order as the API keys above. Unlike Image model, these two need a dsh restart to take effect (see API keys).

Figures

The system prompt steers the agent to pick a figure tool by content, not by habit, and to load the matching skill before drawing:

- Numeric data (plots, charts, distributions, trends) — scientific-figure-making: real matplotlib over real computed data, house-style helpers, PNG+PDF export. Never image_generate and never fabricated values. Named journals also load scientific-visualization for column widths.
- Structural diagrams (architecture, pipelines, flowcharts, method schematics, CONSORT, trees, timelines) — diagram-design: self-contained HTML+SVG editorial diagrams (one accent, no shadows, orthogonal connectors). Not Mermaid rounded boxes, not image_generate. For a paper or compiled PDF the agent also exports PNG/SVG. Mermaid is only when the user explicitly wants a git-diffable markdown diagram.
- Conceptual illustrations with no defined structure and no real numbers — image_generate.

Image generation

image_generate writes conceptual schematics, diagrams, and illustrations to the workspace — not quantitative plots (those should be real Python/matplotlib output over real data).

- Default (Gemini): set GEMINI_API_KEY (Settings or env). Model defaults to gemini-2.5-flash-image ("nano banana"); pick a different one from the Image model dropdown in Settings → ResearchCraft API keys (gemini-3.1-flash-image "nano banana 2", gemini-3-pro-image "nano banana pro", or a custom model id), or set IMAGE_MODEL (env). Unlike the API-key fields, the dropdown applies immediately on selection — no Save button, and (like resolveEnv() fields) no restart needed.
- OpenAI-compatible Images API instead: set IMAGE_PROVIDER=openai, IMAGE_MODEL (Settings or env), IMAGE_BASE_URL (env only) plus IMAGE_API_KEY (Settings or env).

Scientific file inspection

sci_inspect summarizes SMILES/MOL/SDF, PDB/CIF, mzML and other mass-spec formats, npy/npz/parquet/hdf5, TIFF/NIfTI/DICOM, and h5ad files by shelling out to the bundled Python helpers under python-helpers/.

Set up the helper venv once (needs uv):

cd python-helpers && uv sync

The tool finds python-helpers/.venv automatically. Override with RESEARCHCRAFT_HELPERS_DIR (a different helpers checkout) or RESEARCHCRAFT_PYTHON (a specific interpreter).

LaTeX

latex_compile compiles a .tex file to PDF: latexmk when it's on PATH (handles bibtex/biber automatically), otherwise a pdflatex/xelatex/lualatex fallback with a bibtex/biber pass when the source needs one. Requires a TeX Live (or similar) install.

Downloading and reading papers

Two tools cover the full loop for actually reading a paper rather than just its abstract: paper_download (ResearchCraft preset only — see Academic search) gets the PDF onto disk, and pdf_to_markdown (every preset) turns it into readable text. A successful paper_download is also ingested into PaperMemory (see Paper memory).

PDF to Markdown

pdf_to_markdown converts a PDF to Markdown using pdf-inspector (@firecrawl/pdf-inspector, native Rust/napi) — built for literature-survey workflows where a lot of downloaded papers need converting. It classifies the PDF (text-based/scanned/image-based/mixed) and, for text-based PDFs, extracts headings, lists, tables, and reading order locally in milliseconds without OCR.

- path — the PDF to convert.
- pages — optional 1-indexed page numbers to limit conversion to.
- write_to — workspace-relative output path for the Markdown. Recommended for anything but a short excerpt; converting many papers with write_to set keeps each paper's full text out of the conversation and on disk instead (e.g. literature/-.md).
- ocr — selectively OCR pages flagged as low quality (mode Auto). Requires the PDFium and ONNX Runtime shared libraries installed locally (set PDFIUM_LIB_PATH/ORT_DYLIB_PATH if they're not on the library search path — see pdf-inspector's OCR runtime guide); without them, a scanned PDF still comes back with pages_needing_ocr populated, so the agent knows to fall back to subagent_vision on rendered page images instead.

Prebuilt native binaries ship as optionalDependencies for Linux (x64/ARM64, glibc and musl), macOS (ARM64), and Windows (x64) — a plain npm install picks up the right one, no Rust toolchain needed.

Remote compute

modal_run and runpod_run offload a command to a remote CPU/GPU instance — upload inputs, run, download outputs, always terminate when done.

| Tool | Key (Settings or env) | Get credentials |
| modal_run | MODAL_TOKEN_ID, MODAL_TOKEN_SECRET | https://modal.com/settings |
| runpod_run | RUNPOD_API_KEY | https://console.runpod.io/user/settings |

runpod_run also needs ssh, scp, and ssh-keygen on PATH (standard OpenSSH client tools) to provision and reach the ephemeral pod.

By default every runpod_run call is a brand-new, disposable pod — /workspace (and anything uploaded into it) is gone once the pod terminates, so only what's named in files_out comes back. Pass volume_name to persist data across calls instead: it mounts a Runpod network volume at /workspace, and reusing the same volume_name on a later call reattaches the same storage — e.g. upload a large dataset once, then run several training/eval passes against it without re-uploading it with files_in each time. The volume is looked up by name and created automatically the first time it's used, which requires data_center_id (network volumes are pinned to a data center); volume_size_gb (default 20) only applies when creating a new one. The pod's compute is always deleted after the call regardless — a named volume is not, and keeps costing storage until deleted from the Runpod console (this tool has no delete-volume path, so it won't silently remove a dataset).

For anything beyond what modal_run/runpod_run cover — Serverless endpoints, Hub templates, direct volume/secret management, a deployed app, checking GPU availability — the agent loads the bundled runpod/modal skills (skills/runpod, skills/modal, shipped and seeded the same way as the specialist skills above) and drives the runpodctl/modal CLIs directly via bash. Neither CLI ships inside this plugin's package, but the agent installs whichever it needs itself, user-locally and without root, per the steps baked into each skill — runpodctl as a plain release binary into ~/.local/bin, modal via uvx modal ... (no persistent install needed) or uv tool install modal for a longer session — rather than asking the user to set it up first.

Note: runpod_run/runpod-client.js talk to Runpod's REST v1 API (https://rest.runpod.io/v1), which Runpod has flagged for retirement on 2026-11-15 in favor of REST v2 — no action needed yet, but worth knowing before that date.

Lab notebook

notebook keeps a running JSONL log per session at /.dsh/notebook/.jsonl — action: "log" for a hypothesis/method/observation/decision/note, action: "read" to recall it, action: "export" to render it to Markdown (or a .zip bundling that Markdown with every artifact file the entries link to — set export_format: "zip").

A subagent the top-level agent delegates to runs in its own DSH session, but its notebook calls resolve to the same file as its ancestor's — the tool walks the session's delegation lineage (session.header.parentSession) back to the root, so a specialist's findings land in the one shared notebook rather than a file nobody reads.

Scientific results

scientific_result is a structured, schema-validated card for a terminal finding — a results table (kind: "table") or a statistical-test summary (kind: "statistical_test") — with up to 20 linked workspace-relative artifacts (role: figure/table/script/report/data/log). Use it once you have a concrete finding to report; use notebook for the running log on the way there. It has no separate storage — the call and its result are already part of the session transcript.

Workflow templates

research_template browses (action: "list", filterable by category/query) and retrieves (action: "get", with values filling {placeholder} tokens) a catalogue of ~330 one-click research-task prompt templates across 22 disciplines, ported from ResearchCraft's own template library. It is a different tool from DSH's workflow (Rhai multi-agent scripts); the ResearchCraft preset mounts both, so they cannot share a name.

Development

Every server-side file is plain ESM JS — no build step. The Settings page (client/) is the exception: it's a browser bundle (React, esbuild) served to the DSH web client, built with:

npm install # once, for esbuild
npm run build # after any client/ change — rebuilds lib/client.js

lib/client.js is committed so installing the plugin never needs a build step or pnpm approve-builds for this package itself.

License

MIT — see LICENSE. Scientific skills are vendored or adapted from several open-source catalogues; see NOTICE for exactly what was copied, renamed, or adapted from each.