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）以及工作区语义搜索（mcp__zvec_grep__zvec_grep_search）仅存在于该预设中——留在默认预设上的会话将不具备这些功能，要求它使用例如 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 技能（用于调优 DL/LLM 模型的预注册、声明前验证搜索循环）——改编自 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）

RESEARCHCRAFT_SKILLS_DIR（或 ~/scientific-agent-skills/skills 检出目录）仍可作为覆盖项使用，如果你想改用不同的目录——在每个预设中均可用
- notebook 工具——记录、读取并导出实时实验记录本（JSONL 位于 /.dsh/notebook/ 下），在子代理委派树中共享，并支持与纯 Markdown 导出并存的 zip 打包导出——每个预设
- scientific_result 工具——结构化、经模式验证的“最终发现”卡片（表格或统计检验），区别于 notebook 的持续日志——每个预设
- 面向 DSH subagent 工具的专家简报（code-reviewer、literature-researcher 等），外加 subagent_pro 和 subagent_vision——另外两个委派工具，分别固定到不同模型，用于异常繁重的推理任务和图像阅读任务——见 Subagent model routing——每个预设
- 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 模板等）——见 Remote compute——每个预设
- workflow 工具，基于约 330 个模板的研究任务目录——每个预设
- 学术搜索：Parallel、Firecrawl、Scite（MCP 连接器）、parallel_search / consensus_search（原生 REST 工具），以及 paper_download（Unpaywall 开放获取 PDF 解析器）——仅限 ResearchCraft 预设
- 通过 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 环境变量

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。

同一个 Settings 页面还有一个用于 IMAGE_MODEL 的 Image model 下拉菜单 —— 它不是凭据，因此不会被密码掩码，并且在选择后立即生效，无需 Save（参见 Image generation）。它还有另外两个 model-id 下拉菜单，Complex-task model（SUBAGENT_MODEL_COMPLEX）和 Image-reading model（SUBAGENT_MODEL_VISION）—— 它们也不是凭据，但这两个的行为类似于下面的 MCP 连接器，而不是 Image model：它们需要重启才能生效（参见 Subagent model routing）。zvec-grep embedding（ZVEC_GREP_EMBEDDING）是同样的需要重启的下拉菜单：它在挂载时被传入 zg server on。Index at session start（ZVEC_GREP_AUTO_INDEX，默认 No）对下一个 ResearchCraft 会话实时生效 —— 无需重启（参见 Workspace search）。

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

还要确保聊天会话确实处于 ResearchCraft 预设上。 MCP 连接器、原生学术搜索工具（consensus_search、parallel_search）以及 mcp__zvec_grep__zvec_grep_search 只接入到 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）。

only if you want to index by hand or pick a different local model
zg index --embedding local/potion-retrieval-32m    # default — papers / notes / mixed
zg index --embedding local/potion-code-16m-v2      # smaller (~65 MB model), code-heavy trees
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。

面向智能体的安装、索引和路由细节位于捆绑的 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 令牌发送，因此 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 作为后备。在设置中更改 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），而不是错误 —— 代理会被引导如实报告这一点，而不是从搜索摘要中推断论文内容。响应在保存前还会对照 PDF 魔数进行检查，因此如果返回的是登录/CAPTCHA 页面而非真实文件，会以明确的错误呈现，而不是一个损坏的“PDF”。

浏览网页

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

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

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

子代理模型路由
除了普通的 subagent/subagent_fork 委派工具之外，researchcraft 预设还额外添加了两个工具，它们通过 agentOptions.model 将委派的子代理固定到特定模型，这样代理就可以把任务路由到适合它的模型，而不是把所有事情都跑在当前聊天会话碰巧使用的模型上：

| 工具 | 适用场景 | 模型（Settings 或环境变量） | 默认值 |
|---|---|---|---|
| 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 未注册于会话所用提供商的情况下直接破坏委派。只有两条升级路径被固定模型，而且仅在代理主动选择使用某个特定模型、而非回退到它已经在用的模型时才如此。

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

subagent_vision 只负责将子代理路由到某个模型；子代理仍会自行调用 read_image（@deepseek-ai/dsh-tool-fs），而除非调用路由解析出的模型在本部署的模型目录中确实声明了 image 输入，否则该工具会拒绝读取图像——请选择一个以这种方式注册的 SUBAGENT_MODEL_VISION 值。
除了单纯的“看看这张图”请求之外，系统提示还会引导智能体将科学阅读任务专门委派给 subagent_vision：解读图表或趋势、比较多面板图中的各个面板、审查显微/凝胶/医学影像扫描中的定性特征、检查化学结构/系统发育树/通路图是否正确，以及将生成的图与所要求的内容进行对比。它还覆盖了文本工具无法处理的一种情况：审查编译后的 LaTeX PDF 的页面布局——表格跨分页断开、表格或图漂移到参考文献部分、行溢出、图注与其图分离——由于 read_image 只接受 PNG/JPEG/WebP/GIF，智能体会先用 pdftoppm -png -r 150 file.pdf page（poppler，通常已随 TeX Live 一起安装）将 PDF 页面渲染出来，然后再进行委派。

通过 Settings → ResearchCraft API keys（Image model 旁边的另外两个下拉框）或匹配的环境变量设置 SUBAGENT_MODEL_COMPLEX/SUBAGENT_MODEL_VISION——两者都设置时环境变量优先，解析顺序与上面的 API 密钥相同。与 Image model 不同，这两个需要重启 dsh 才能生效（参见 API keys）。

图

系统提示会引导智能体根据内容而非习惯来选择绘图工具，并在绘制前加载匹配的技能：

- 数值数据（图、图表、分布、趋势）——scientific-figure-making：基于真实计算数据的真实 matplotlib、house-style 辅助函数、PNG+PDF 导出。绝不使用 image_generate，绝不使用捏造的值。指定期刊还会加载 scientific-visualization 以获取栏宽。
- 结构图（架构、流水线、流程图、方法示意图、CONSORT、树、时间线）——diagram-design：自包含的 HTML+SVG 编辑式图表（单一强调色、无阴影、正交连接线）。不是 Mermaid 圆角框，不是 image_generate。对于论文或编译后的 PDF，智能体还会导出 PNG/SVG。只有当用户明确想要可进行 git diff 的 markdown 图时才使用 Mermaid。
- 概念性插图，没有定义的结构也没有真实数字——image_generate。

图像生成

image_generate 将概念性示意图、图表和插图写入工作区——而不是定量图（那些应基于真实数据使用真实的 Python/matplotlib 输出）。

- 默认（Gemini）： 设置 GEMINI_API_KEY（Settings 或环境变量）。模型默认为 gemini-2.5-flash-image（“nano banana”）；可从 Settings → ResearchCraft API keys 的 Image model 下拉框中选择其他模型（gemini-3.1-flash-image“nano banana 2”、gemini-3-pro-image“nano banana pro”，或自定义模型 id），或设置 IMAGE_MODEL（环境变量）。与 API 密钥字段不同，下拉框在选择后立即生效——没有 Save 按钮，并且（与 resolveEnv() 字段一样）无需重启。
- 改用 OpenAI 兼容的 Images API： 设置 IMAGE_PROVIDER=openai、IMAGE_MODEL（Settings 或环境变量）、IMAGE_BASE_URL（仅环境变量）以及 IMAGE_API_KEY（Settings 或环境变量）。

科学文件检查

sci_inspect 通过调用 python-helpers/ 下捆绑的 Python 辅助脚本，对 SMILES/MOL/SDF、PDB/CIF、mzML 及其他质谱格式、npy/npz/parquet/hdf5、TIFF/NIfTI/DICOM 和 h5ad 文件进行汇总。

一次性设置辅助 venv（需要 uv）：

cd python-helpers && uv sync

该工具会自动找到 python-helpers/.venv。可通过 RESEARCHCRAFT_HELPERS_DIR（另一个辅助脚本检出目录）或 RESEARCHCRAFT_PYTHON（指定解释器）进行覆盖。

LaTeX

latex_compile 将 .tex 文件编译为 PDF：当 latexmk 在 PATH 上时使用它（自动处理 bibtex/biber），否则回退到 pdflatex/xelatex/lualatex，并在源文件需要时执行一次 bibtex/biber 处理。需要安装 TeX Live（或类似发行版）。

下载和阅读论文

有两个工具覆盖了真正阅读一篇论文（而不仅仅是其摘要）的完整流程：paper_download（仅 ResearchCraft 预设——见学术搜索）将 PDF 下载到磁盘，而 pdf_to_markdown（所有预设）将其转换为可读文本。

PDF 转 Markdown

pdf_to_markdown 使用 pdf-inspector（@firecrawl/pdf-inspector，原生 Rust/napi）将 PDF 转换为 Markdown——专为文献综述工作流打造，其中大量下载的论文需要转换。它对 PDF 进行分类（基于文本/扫描/基于图像/混合），并且对于基于文本的 PDF，在本地以毫秒级速度提取标题、列表、表格和阅读顺序，无需 OCR。

- path —— 要转换的 PDF。
- pages —— 可选的从 1 开始的页码，用于限制转换范围。
- write_to —— Markdown 的工作区相对输出路径。对于除简短摘录以外的任何内容都推荐使用；设置 write_to 转换多篇论文可将每篇论文的全文保留在磁盘上而非对话中（例如 literature/-.md）。
- ocr —— 选择性地对被标记为低质量的页面进行 OCR（模式 Auto）。需要在本地安装 PDFium 和 ONNX Runtime 共享库（如果它们不在库搜索路径上，请设置 PDFIUM_LIB_PATH/ORT_DYLIB_PATH——见 pdf-inspector 的 OCR 运行时指南）；没有它们时，扫描版 PDF 仍会返回填充了 pages_needing_ocr 的结果，因此 agent 知道应改为对渲染后的页面图像回退到 subagent_vision。

预构建的原生二进制文件作为 optionalDependencies 提供，适用于 Linux（x64/ARM64，glibc 和 musl）、macOS（ARM64）和 Windows（x64）——普通的 npm install 会选取正确的版本，无需 Rust 工具链。

远程计算

modal_run 和 runpod_run 将命令卸载到远程 CPU/GPU 实例——上传输入、运行、下载输出，完成后始终终止。
| 工具 | 密钥（设置或环境变量） | 获取凭据 |
|---|---|---|
| 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 还需要 PATH 上有 ssh、scp 和 ssh-keygen（标准的 OpenSSH 客户端工具），以便配置并访问临时 pod。

默认情况下，每次 runpod_run 调用都是一个全新的、一次性的 pod —— pod 终止后，/workspace（以及上传到其中的任何内容）都会消失，因此只有 files_out 中指定的内容会被带回。传入 volume_name 可以在多次调用之间持久化数据：它会在 /workspace 挂载一个 Runpod 网络卷，并且在后续调用中复用同一个 volume_name 会重新挂载同一份存储 —— 例如，上传一次大型数据集，然后针对它运行多次训练/评估，而无需每次都通过 files_in 重新上传。该卷按名称查找，并在首次使用时自动创建，这需要 data_center_id（网络卷固定绑定到某个数据中心）；volume_size_gb（默认 20）仅在创建新卷时适用。无论怎样，pod 的计算资源在调用结束后总会被删除 —— 但命名卷不会，并且会持续产生存储费用，直到从 Runpod 控制台删除（此工具没有删除卷的途径，因此它不会悄悄删除数据集）。

对于 modal_run/runpod_run 覆盖范围之外的任何需求 —— Serverless 端点、Hub 模板、直接管理卷/密钥、已部署的应用、检查 GPU 可用性 —— agent 会加载捆绑的 runpod/modal 技能（skills/runpod、skills/modal，其发布和预置方式与上述专家技能相同），并通过 bash 直接驱动 runpodctl/modal CLI。这两个 CLI 都不随此插件的包一起提供，但 agent 会按照每个技能中内置的步骤，自行以用户本地方式、无需 root 权限安装所需的那个 —— runpodctl 作为普通发布二进制文件安装到 ~/.local/bin，modal 通过 uvx modal ...（无需持久安装）或对于较长的会话使用 uv tool install modal —— 而不是先要求用户进行设置。

注意：runpod_run/runpod-client.js 与 Runpod 的 REST v1 API（https://rest.runpod.io/v1）通信，Runpod 已将其标记为将于 2026-11-15 退役，转而支持 REST v2 —— 目前无需采取任何行动，但在此日期之前值得了解。

实验笔记本

notebook 会在 /.dsh/notebook/.jsonl 为每个会话保留一份持续追加的 JSONL 日志 —— action: "log" 用于记录假设/方法/观察/决策/笔记，action: "read" 用于回顾它，action: "export" 用于将其渲染为 Markdown（或将该 Markdown 与条目所链接的每个产物文件打包成一个 .zip —— 设置 export_format: "zip"）。
顶层 agent 委派的子 agent 会在自己的 DSH 会话中运行，但它的 notebook 调用会解析到与其祖先相同的文件——该工具会沿着会话的委派谱系（session.header.parentSession）回溯到根会话，因此专家的发现会落入同一个共享 notebook，而不是一个没人会读的文件。

科学结果

scientific_result 是一张结构化、经 schema 校验的卡片，用于终态发现——结果表（kind: "table"）或统计检验摘要（kind: "statistical_test"）——最多可关联 20 个工作区相对路径的产物（role：figure/table/script/report/data/log）。一旦有了具体发现需要报告，就使用它；在达成发现的过程中，用 notebook 记录运行日志。它没有单独的存储——该调用及其结果已经是会话记录的一部分。

工作流模板

workflow 可浏览（action: "list"，可按 category/query 过滤）和检索（action: "get"，用 values 填充 {placeholder} 占位符）一个包含约 330 个一键式研究任务提示模板的目录，覆盖 22 个学科，移植自 ResearchCraft 自己的模板库。

开发

每个服务端文件都是纯 ESM JS——无需构建步骤。Settings 页面（client/）是例外：它是提供给 DSH Web 客户端的浏览器 bundle（React、esbuild），构建方式如下：

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

lib/client.js 已提交，因此安装该插件永远不需要构建步骤，也不需要为此包执行 pnpm approve-builds。

许可证

MIT——见 LICENSE。科学技能来自多个开源目录的 vendored 或改编版本；关于每个目录中具体复制、重命名或改编了什么，请参见 NOTICE。