dsh-molbio-tools 0.21.1 → 0.22.0

package/CHANGELOG.md

@@ -10,6 +10,78 @@
   改为按**包名**引用后模块缓存问题随之消失——没有拷贝，也就没有需要保持同步的版本目录。
   下文历史条目里出现的 `vN` 目录保持原样，作为当时的记录。
 
+## [0.22.0] — 2026-10-25（DSH 0.2.1-rc.3 适配；PubMed 官方 API + NCBI API key）
+
+**工具数不变（60）。新增一条通路：`molbio_pubmed_search` / `molbio_pubmed_abstract` 可以带着
+NCBI API key 走 PubMed 官方 E-utilities。** 没有 key 时两条工具的行为与 0.21.1 相同——检索仍走
+harness 的 web 检索，摘要仍走 `ctx.web.fetch`。
+
+### 1. 为什么要有官方通路
+
+原来的检索完全依赖 harness 的 web 检索服务：它返回的是**搜索引擎索引到的页面**，不是 PubMed 的
+题录。三个具体代价：命中的 PMID 要从 URL 里猜、拿不到期刊/年份/作者/DOI 这些结构化字段、也
+无法用 NCBI 的 API key 提升速率上限（无 key 3 次/秒，有 key 10 次/秒）。官方 API 是两步：
+`esearch`（term → PMID 列表）→ `esummary`（PMID → 题录），摘要另走 `efetch`。
+
+### 2. 通路选择与 key 的来源
+
+| 条件 | 检索通路 | 结果字段 |
+| --- | --- | --- |
+| 有 key（参数或环境变量） | 官方 E-utilities：esearch + esummary | PMID、标题、期刊、年份、作者、DOI，另含 `total_matches` |
+| 无 key | 原来的 harness web 检索（行为不变） | 标题、URL、snippet、从 URL 提取的 PMID |
+
+key 的优先级是 **`api_key` 参数 > `NCBI_API_KEY` > `MOLBIO_NCBI_API_KEY`**；空白值视为未提供
+（不会发出 `api_key=` 这种被 NCBI 以 400 拒绝的空参数）。一次带 key 的检索是 **2 个请求**，
+`molbio_pubmed_abstract` 是 1 个 efetch 请求。
+
+> **内联传 key 会出现在对话记录和工具调用卡片里**，这是参数通路的固有代价；长期使用应设环境
+> 变量。工具的输出、渲染和错误信息都不回显 key。
+
+### 3. 实现
+
+- `papers.mjs` 增加纯函数：`pubmedApiKey`（参数/环境变量优先级）、`pubmedSearchUrl` /
+  `pubmedSummaryUrl` / `pubmedFetchUrl`（三个 URL 构造器，统一带 `tool=dsh-molbio-tools`）、
+  `parseEsearch`（ids + count）、`parseEsummaryRecords`（按 `uids` 顺序归一化题录，
+  DOI 从 `articleids` 里取 `idtype: doi`）、`esummarySource`（转成工具返回的 source 形状）。
+- 传输仍走 `ctx.web.fetch`：官方 API 不是一条绕开沙箱/同意机制的新网络通路。没有 `web.fetch`
+  而用户又给了 key 时，工具明确报「需要 ctx.web.fetch」，而不是悄悄退回 web 检索。
+- 错误处理：NCBI 的 `{"error":"API key invalid"}` 会变成 `PubMed E-utilities error: API key
+  invalid`，**不会被当成「没有结果」**——「搜不到」和「key 错了」是两件事。空结果返回
+  `sources: []` 与 `total_matches: 0`。
+- 输出 schema 扩展：`backend`（`pubmed-eutils` / `web-search`）、`total_matches`，以及 source 上的
+  `doi` / `authors` / `journal` / `year`；全部为可选字段，旧调用的输出形状不变。
+
+### 4. rc.3 适配：这次上游什么都没动，但仍要走完流程
+
+- `@deepseek-ai/dsh-web-app@0.2.1-rc.3` 的 `standard.patch.yml` 与 rc.2 **逐字节一致**（`git diff
+  --no-index` 验证），所以 preset 行清单、`cordis.patch.yml`、`preset-health` 的期望都没有改。
+- 在 rc.3 上全套守卫全绿：`preset-health`（30 行）、`drift-probe`（14 条突变）、`contract`（16 项，
+  含客户端入口与 `presentationMeta` 的行为断言）、`benchmark-profile`（12 行 / 60 工具）。
+- 声明：`engines.dsh` 仍为 `>=0.2.1-rc.2 <0.3.0-0`（rc.2 仍可用）；`dshReleases` 把 rc.3 改成
+  `compatible`；CI 的 test/release 两条工作流钉到 `0.2.1-rc.3`；面板包 `0.1.4 → 0.1.5`（清单的
+  兼容声明变了，客户端产物字节未变，因此只 bump 面板版本线）。
+- 证据用 rc.3 的 CLI 重跑：`docs/store-evidence.md`（0.22.0 tarball 安装 → 启动 → 卸载）。
+
+### 5. benchmark 的处理（以及为什么没有重跑模型）
+
+- 默认通路（无 key）的输出与 0.21.1 相同，`bench --offline` 的 61 题期望值逐条照跑。
+- `literature-search` 仍是 `NETWORK_TASKS` 里唯一的一条：它断言的是模型的最终回答（PMID、标题、
+  摘要措辞），工具结果本来就是**当天的 live PubMed 数据**，没有可以钉住的值。
+- **带 key 的新通路由 `test/smoke.mjs` 覆盖，而不是 benchmark**：benchmark 不能要求真实 key、
+  也不该把 live 记录冻结成期望值。smoke 用 mock 的 esearch/esummary/efetch 断言了四件事——
+  key 同时出现在两个请求里、题录字段解析正确、环境变量能回退、无效 key 会报错；另有一条
+  「无 key 时不碰 E-utilities 传输」的对照。
+
+### 6. 版本与验证
+
+- 根包 `0.21.1 → 0.22.0`；面板 `0.1.4 → 0.1.5`。
+- `npm test`（DSH 0.2.1-rc.3）全绿：smoke、画面四套、客户端四套、contract 16、drift-probe 14 条
+  突变、preset-health 30 行、release 13 项、benchmark 四道守卫 + `bench --offline` 61 题。
+- `node build/preset-patch.mjs --check` 与 `node build/client-bundle.mjs --check` 均报告与源一致
+  （rc.3 适配没有动任何生成物）。
+- 一次性 Profile：tarball **115 个文件 / 约 1.0 MB**；安装 571 ms；启动 `HTTP 200`、38180 字节，
+  `__DSH_BOOT__` 含 `dsh-molbio-tools/client.js&rev=a25c3919676b`；卸载 421 ms，`molbio` 引用 0、
+  lockfile 与 `node_modules` 无残留。
 ## [0.21.1] — 2026-10-25（DSH STORE 提交前置：一个 patch、逐版本兼容声明、一个 tarball 一个清单）
 
 **工具数不变（60），插件运行时行为零改动。** 这一版不加任何计算能力，只把"这个包以什么形状提交"

package/README.md

@@ -224,8 +224,8 @@ dsh plugin --profile <profile> add dsh-molbio-panel
 
 | 工具 | 用途 |
 | --- | --- |
-| `molbio_pubmed_search` | 通过 harness 的 web 检索服务搜文献，自动提取 PMID |
-| `molbio_pubmed_abstract` | 按 PMID 拉取摘要（依赖部署提供 web fetch 能力） |
+| `molbio_pubmed_search` | 搜 PubMed 文献。提供 NCBI API key（`api_key` 参数，或环境变量 `NCBI_API_KEY` / `MOLBIO_NCBI_API_KEY`）时走**官方 E-utilities**（esearch + esummary），返回 PMID/标题/期刊/年份/作者/DOI；无 key 时回退到 harness 的 web 检索 |
+| `molbio_pubmed_abstract` | 按 PMID 拉取摘要（efetch；同样支持 NCBI API key，依赖部署提供 web fetch 能力） |
 | `molbio_paper_add` / `molbio_paper_list` / `molbio_paper_update` / `molbio_paper_remove` | 阅读库（工作区 `papers.json`）：加/列/改/删，按 PMID→URL→标题+年份去重 |
 | `molbio_paper_export_bibtex` | `papers.json` → BibTeX `.bib`（可按 tag 过滤） |
 | `molbio_protocol_add` / `molbio_protocol_list` / `molbio_protocol_update` | 协议库（`protocols.json`）：步骤列表、自由参数、来源文献 |
@@ -556,6 +556,11 @@ mutations remain deferred"）。所以插件无法在工作区里合法地落一
 ### 文献与记录
 
 - 检索与摘要走 harness 的 **web** 服务（部署不提供时工具会明确报错，而不是假装搜到）。
+- 提供 NCBI API key 时，`molbio_pubmed_search` 用官方 E-utilities：esearch 拿 PMID、esummary
+  拿题录（标题/期刊/年份/作者/DOI），`molbio_pubmed_abstract` 用 efetch 拿摘要。key 的来源优先级是
+  `api_key` 参数 > `NCBI_API_KEY` > `MOLBIO_NCBI_API_KEY`；**长期使用请用环境变量**，内联传参会让 key
+  出现在对话记录与工具卡片里。NCBI 的速率上限是**无 key 3 次/秒、有 key 10 次/秒**，一次带 key 的
+  检索是 2 个请求（esearch + esummary）。没有 key 时检索仍走原来的 web 检索通路，行为不变。
 - 阅读库/协议库/实验日志是工作区里的 `papers.json` / `protocols.json` / `experiments.json`，
   写入遵循会话的**沙箱政策**，与其它文件工具同权；面板（Papers tab）直接读 `papers.json`。
 - `molbio_paper_export_bibtex` 可选按 tag 过滤导出。
@@ -649,6 +654,12 @@ node <包目录>\preset\install.mjs --profile web --check  # 只报告，不组
 工具会返回 `notes` 说明放宽哪个约束（Tm 窗口、GC 窗口、扩增子长度、探针长度…）。通常是把
 `amplicon_min/max` 或 `tm_min/max` 放宽一点即可。
 
+**PubMed 的 API key 怎么配？**
+在启动 DSH 的环境里设 `NCBI_API_KEY`（或 `MOLBIO_NCBI_API_KEY`），插件会自动把它带进 E-utilities 请求；
+也可以在单次调用里传 `api_key`。有 key 时 `molbio_pubmed_search` 走官方 API（PubMed 自己的题录，
+含 DOI），没有 key 时仍走 harness 的 web 检索。注意：**内联传的 key 会出现在对话记录和工具调用卡片里**，
+长期用请设环境变量。
+
 **"帮我把这段序列分析一下" 它却问我要参数？**
 把目标说具体即可：要引物还是探针、产物多长、Tm 多少、哪个区域。工具默认值都是常规实验条件
 （例如引物 18–28 nt / Tm 55–65 °C / GC 40–60%），不特别说明时按默认来。

package/benchmark/tasks/08-records.json

@@ -13,7 +13,11 @@
     "whatever PubMed answers today and there is no recorded value to pin. Its",
     "assertions are therefore all `where: \"answer\"` and structural — a PMID",
     "appears, a title appears — and `benchmark/verifications.mjs` deliberately",
-    "declares no offline invocation for it. See NETWORK_TASKS there."
+    "declares no offline invocation for it. See NETWORK_TASKS there.",
+    "",
+    "The 0.22.0 NCBI-API-key path is NOT exercised here: a benchmark cannot",
+    "require a real key or pin live PubMed records. test/smoke.mjs covers it with",
+    "mocked esearch/esummary/efetch responses (including the invalid-key error)."
   ],
   "tasks": [
     {

package/benchmark/verifications.mjs

@@ -402,5 +402,10 @@ export function invocationsFor(task) {
  * answer (structural facts: a PMID appears, a title appears), which is why this
  * module returns no invocations for them and why the offline gate tolerates that
  * specific case while failing every other task that forgets to declare one.
+ *
+ * The NCBI-API-key path added in 0.22.0 is covered by `test/smoke.mjs` instead:
+ * a keyed call is two E-utilities requests (esearch + esummary) whose responses
+ * the mock returns, including the invalid-key error. A benchmark must not need a
+ * real NCBI key or pin live PubMed data, so this task stays network-only.
  */
 export const NETWORK_TASKS = new Set(['literature-search']);

package/build/release-preflight.mjs

@@ -201,7 +201,7 @@ export function tagVersion(tag) {
  * `rc.10 < rc.2`, so a release of `rc.2` after `rc.10` would look like a
  * DOWNGRADE and the gate would refuse a legitimate publish (or, in the other
  * direction, wave through a stale one). This repository does cut prereleases
- * (the harness baseline itself is `0.2.1-rc.2`), so the rule is implemented
+ * (the harness baseline itself is `0.2.1-rc.3`), so the rule is implemented
  * rather than approximated.
  *
  * Semver's rule: split on dots; numeric identifiers compare numerically and rank

package/docs/history.md

@@ -16,6 +16,7 @@
 
 | 包版本 | preset 版本 | 内容 | 工具数 |
 | --- | --- | --- | --- |
+| 0.22.0 | — | **DSH 0.2.1-rc.3 适配 + PubMed 官方 API**：`molbio_pubmed_search`/`_abstract` 支持 NCBI API key（E-utilities），无 key 行为不变 | 60 |
 | 0.21.1 | — | **DSH STORE 提交前置**：单文件 bundle patch、逐版本兼容声明；根 tarball 只带一个插件清单（工具行为零变化） | 60 |
 | 0.21.0 | — | **DSH 0.2.1-rc.2 适配**：preset 行清单逐行重抄；contract 两条断言重锚到行为；两条 suspended 记录用真实模型重录 | 60 |
 | 0.20.1 | — | 插件专属图标（透明底双螺旋 SVG），运行时零改动 | 60 |
@@ -44,6 +45,30 @@
 
 ---
 
+## v0.22.0（2026-10-25，包 0.22.0）
+
+一半是适配（rc.3），一半是新能力（PubMed 官方 API + key）。三条教训。
+
+**(1) 「上游没变」不是可以跳过流程的理由，而是一个需要被证明的结论。**
+rc.3 的 `standard.patch.yml` 与 rc.2 逐字节相同，所以 preset 行、生成物、`preset-health` 的期望
+一行都没动——但这是先 diff 过、再把 `preset-health` / `drift-probe` / `contract` /
+`benchmark-profile` 全套在 rc.3 上跑绿之后才敢下的结论。上一次（0.21.0）同一个文件在补丁级版本里
+改了 12 处结构；把「这次应该没事」当选版本的理由，就是在赌下一次。
+
+**(2) 官方 API 不是「另一条网络通路」，它仍然是一次 `ctx.web.fetch`。**
+PubMed E-utilities 的加入没有引入 `fetch` 依赖，也没有绕开沙箱/同意机制：工具只是把 URL 构造成
+esearch/esummary/efetch，再交给同一个 `ctx.web` 缝。两个细节必须做对：**空结果与鉴权失败是两件
+事**（`{"error":"API key invalid"}` 不能渲染成「没有搜到」）；**key 的优先级要可预测**
+（参数 > `NCBI_API_KEY` > `MOLBIO_NCBI_API_KEY`，空白值视为缺席）。另外，内联传 key 会让它出现在
+对话记录与工具卡片里——这是参数通路的固有代价，所以文档把「长期使用请设环境变量」写在工具描述里，
+而不是只写在 README。
+
+**(3) 需要真实凭证/实时数据的路径，归 smoke，不归 benchmark。**
+benchmark 的 `literature-search` 一直是 `NETWORK_TASKS`：它只断言最终回答的结构，因为工具返回的
+是当天的 PubMed 数据，没有可冻结的值。带 key 的新通路同样不能被 benchmark 钉住（既不能要求一个
+真 key，也不该把 live 记录写进 fixture），于是用 mock 的 esearch/esummary/efetch 在 `test/smoke.mjs`
+里断言「key 真的进了两个请求」「字段解析正确」「环境变量能回退」「坏 key 会报错」，并保留一条
+「无 key 时不碰 E-utilities」的对照——benchmark 负责模型会不会用，smoke 负责这条分支本身对不对。
 ## v0.21.1（2026-10-25，包 0.21.1）
 
 上架前置版：一个工具都没改，只改「提交的形状」。三条教训都关于**契约不止一份**。

package/docs/maintainer.md

@@ -32,7 +32,7 @@
 
 - **包**：`dsh-molbio-tools`，零依赖 DSH 插件包，**60 个 `molbio_*` 工具**（其中
   `molbio_plot` 一个工具承载 8 种图表）。
-- **基线**：DSH **0.2.1-rc.2**；`package.json` 版本 0.21.1。
+- **基线**：DSH **0.2.1-rc.3**；`package.json` 版本 0.22.0。
 - **两条分发渠道**：根包（工具 + 面板）与 `packages/molbio-panel`（只面板），
   **两个独立的 npm 条目、两条独立的版本线**，必须分别发布。
 - **工具只在专属模式里出现**（设计如此）：bundle 的 `cordis.patch.yml` 只插一行**惰性宿主锚点**

package/docs/roadmap.md

@@ -10,12 +10,12 @@ L = 需要新机制或外部资源）。
 
 ---
 
-## 1. 当前状态（0.21.1）
+## 1. 当前状态（0.22.0）
 
 - 60 个 `molbio_*` 工具，零依赖，随 preset 分发（见 [README](../README.md)）。
 - 离线测试金字塔 + 组合漂移守卫全绿；`benchmark/` 提供**模型使用**维度的评估
   （见 [benchmark/README.md](../benchmark/README.md)）。
-- 基线：DSH **0.2.1-rc.2**。
+- 基线：DSH **0.2.1-rc.3**。
 - **CI 已在位**（`.github/workflows/test.yml`，0.18.2 起）：push / PR / 手动都跑全套；harness 装
   **钉死版本**，并用 `npm prefix -g` 显式导出 `DSH_HARNESS_ROOT`。0.18.4 起**同时跑
   `ubuntu-latest` 与 `windows-latest`**——3.6 已修，套件不再依赖宿主分隔符。
@@ -37,6 +37,10 @@ L = 需要新机制或外部资源）。
   `dshReleases`、根 tarball 去掉 `packages/`（一个包只带一个插件清单）。剩下的两条预检规则
   不是改包能解决的，证据与请求见 [store-preset-exemption.md](store-preset-exemption.md)。
   下一版若要动工具，按本文件第 2 节挑候选；若只等商城结论，则不必发版。
+- **0.22.0 是 rc.3 适配 + 文献检索升级**：DSH 基线 0.2.1-rc.2 → 0.2.1-rc.3（上游
+  `standard` 行清单**逐字节未变**，`preset-health` / `drift-probe` / `contract` 在 rc.3 上
+  全绿，因此这一半只改声明与证据）；`molbio_pubmed_search` / `molbio_pubmed_abstract` 增加
+  NCBI API key 通路，走官方 E-utilities（esearch + esummary），无 key 时保持原有 web 检索。
 
 ---
 

package/docs/store-evidence.md

@@ -18,7 +18,7 @@
     "dshReleases": {
       "0.2.1-rc.1": "unknown",
       "0.2.1-rc.2": "compatible",
-      "0.2.1-rc.3": "unknown"
+      "0.2.1-rc.3": "compatible"
     }
   }
 }
@@ -29,19 +29,19 @@
 `@deepseek-ai/dsh-app-boot` 的 `unmetRequirements`）：带 prerelease 选项时 `<0.3.0`
 会放行 `0.3.0-alpha.1`，而 `-0` 不会。
 
-### 为什么 rc.2 是 compatible、rc.1 / rc.3 是 unknown
+### 为什么 rc.2 / rc.3 是 compatible、rc.1 是 unknown
 
 | 版本 | 记录 | 依据 |
 | --- | --- | --- |
 | 0.2.1-rc.1 | unknown | 早于本包基线（0.20.1 钉 `0.2.0-rc.2`），未在此版本上运行过；同时也不在 `engines.dsh` 范围内 |
-| 0.2.1-rc.2 | compatible | CI 基线固定该版本；本文件第 3 节的一次性 Profile 流程；`contract` / `preset-health` / `smoke` 均通过 |
-| 0.2.1-rc.3 | unknown | 未获取到该版本，未验证。`engines.dsh` 的补丁级范围包含它，但**是否授权安装以商城的 `dshReleases` 记录为准**——范围不等于验收 |
+| 0.2.1-rc.2 | compatible | 0.21.0 / 0.21.1 的发布基线；本文件第 3 节的一次性 Profile 流程在 rc.2 上跑过；`contract` / `preset-health` / `smoke` 均通过 |
+| 0.2.1-rc.3 | compatible | 0.22.0 的发布基线（CI 钉该版本）；同一套一次性 Profile 流程在 rc.3 上重跑通过（安装 → 启动 HTTP 200 → 卸载无残留）；`contract` / `preset-health` / `drift-probe` / `benchmark-profile` / `smoke` 在 rc.3 上全绿。上游 `standard` 行清单与 rc.2 **逐字节一致** |
 
 ## 2. 环境
 
 | 项 | 值 |
 | --- | --- |
-| DSH | `0.2.1-rc.2` |
+| DSH | `0.2.1-rc.3` |
 | Node.js | `v26.12.1` |
 | pnpm | `11.22.0` |
 | 平台 | Windows（win32 x64） |
@@ -52,9 +52,9 @@
 
 ```bash
 export DSH_HOME=<workspace>/.tmp/dsh-store-check
-npm pack --pack-destination "$DSH_HOME"          # 得到 dsh-molbio-tools-0.21.1.tgz
+npm pack --pack-destination "$DSH_HOME"          # 得到 dsh-molbio-tools-0.22.0.tgz
 dsh --profile molbio-tgz-check --from-default-profile web --dump-config
-dsh plugin --profile molbio-tgz-check add "$DSH_HOME/dsh-molbio-tools-0.21.1.tgz"
+dsh plugin --profile molbio-tgz-check add "$DSH_HOME/dsh-molbio-tools-0.22.0.tgz"
 dsh --profile molbio-tgz-check --dump-config      # 安装后的组合树
 dsh --profile molbio-tgz-check --no-open --port 0 # 启动，打印 URL
 curl "http://127.0.0.1:<port>/?token=<token>"     # 读回页面
@@ -65,20 +65,20 @@ dsh --profile molbio-tgz-check --dump-config      # 卸载后的组合树
 安装用 **tarball** 而不是目录，因为 tarball 就是发布物本身：它能同时证明 `files`
 白名单带全了运行文件（`host.mjs`、`lib/client.js`、单个 `cordis.patch.yml` 的两个 insert、preset）。
 
-tarball 是 **115 个文件 / 约 999 kB**（`npm pack --dry-run` 实测约 999.3 kB，解包约 3.2 MB；再改文档会让
-字节数在 1 kB 内浮动，文件数不变），且 `package/packages/**` 为 **0**：根包不再内嵌
+tarball 是 **115 个文件 / 约 1.0 MB**（`npm pack` 实测 1,004,017 B，解包约 3.2 MB；再改文档会让字节数
+小幅浮动，文件数不变），且 `package/packages/**` 为 **0**：根包不再内嵌
 `packages/molbio-panel`，一个 tarball 里只有一个插件清单（面板包按自己的地址单独发布）。
 面板本身没有因此消失——根包的 `lib/client.js` 就带着它，第 3.2 节的回读可以作证。
 
-下面这次是在 **0.21.1 的 tarball** 上重跑的（2026-10-25），文件数与发布物一致；
-0.21.0 时代的记录只差版本号与文件数，流程未变。
+下面这次是在 **0.22.0 的 tarball** 上、用 **dsh 0.2.1-rc.3** 的 CLI 重跑的（2026-10-25），
+文件数与发布物一致；更早的记录只差版本号与文件数，流程未变。
 
 ### 3.1 安装
 
 ```
-+ dsh-molbio-tools file:D:/.../dsh-molbio-tools-0.21.1.tgz
++ dsh-molbio-tools file:D:/.../dsh-molbio-tools-0.22.0.tgz
 Packages: +1
-Done in 631ms
+Done in 571ms
 ```
 
 安装后的 `--dump-config` 出现 bundle 层，且 `host.mjs` 解析到**已安装包内**：
@@ -98,19 +98,19 @@ Done in 631ms
 ### 3.2 启动
 
 ```
-dsh web: http://127.0.0.1:61834/?token=...
+dsh web: http://127.0.0.1:50071/?token=...
 ```
 
-读回结果：`HTTP 200`、37721 字节；页面里的 `window.__DSH_BOOT__` 图包含
-`dsh-molbio-tools/client.js&rev=e4e837d570c2`，即浏览器半被宿主 Loader 发现并进了客户端图——
+读回结果：`HTTP 200`、38180 字节；页面里的 `window.__DSH_BOOT__` 图包含
+`dsh-molbio-tools/client.js&rev=a25c3919676b`，即浏览器半被宿主 Loader 发现并进了客户端图——
 这是"启动成功"的可观察证据，而不只是进程没退出。（先用 token 换 cookie，再带 cookie 读 `/`，
 否则第一跳是 303。）
 
 ### 3.3 卸载
 
 ```
-- dsh-molbio-tools file:D:/.../dsh-molbio-tools-0.21.1.tgz
-Done in 452ms
+- dsh-molbio-tools file:D:/.../dsh-molbio-tools-0.22.0.tgz
+Done in 421ms
 ```
 
 卸载后四项同时回到初始状态：
@@ -133,7 +133,7 @@ pnpm 的 hoisted linker 会在 `node_modules/` 留下一个指向仓库目录的
 
 ```
 node test/contract.mjs       → 16 checks passed（host 契约、client 产物、tarball 覆盖）
-node test/preset-health.mjs  → all 30 rows load on dsh 0.2.1-rc.2
+node test/preset-health.mjs  → all 30 rows load on dsh 0.2.1-rc.3
 node test/smoke.mjs          → registered 60 tools, all smoke tests passed
 ```
 

package/docs/store-preset-exemption.md

@@ -43,6 +43,10 @@ or a fixed-source manual review.
 }
 ```
 
+> 这段是**提交时那个固定 commit** 的原文（所以 rc.3 当时是 `unknown`）。0.22.0 起 rc.3 已在其上
+> 跑过同一套一次性 Profile 与守卫，`dshReleases` 已改为 `compatible`，见
+> [store-evidence.md](store-evidence.md) 第 1–2 节。
+
 同一个 patch 文件里的两个 insert（顺序即应用顺序），分工固定：
 
 ```yaml

package/docs/workflow.md

@@ -456,7 +456,7 @@ git status --short           # lib/client.js 与 packages/molbio-panel/lib/clien
 ### DSH 升级后：preset 组合的维护（必做）
 
 `preset/molbio-lab/agent.cordis.yml` 是官方 `standard` 预设的**行清单**副本 + 末尾一行
-`tool-molbio`（当前基线：**dsh 0.2.1-rc.2**）。它不会自动跟随 DSH 升级，因此每次升级
+`tool-molbio`（当前基线：**dsh 0.2.1-rc.3**）。它不会自动跟随 DSH 升级，因此每次升级
 DSH 后：
 
 1. 取新版的 shipped `standard`：

package/index.mjs

@@ -104,9 +104,16 @@ import {
 } from './methylation.mjs';
 import {
   addPapers,
+  esummarySource,
   libraryPath,
   loadLibrary,
+  parseEsearch,
+  parseEsummaryRecords,
   pmidFromUrl,
+  pubmedApiKey,
+  pubmedFetchUrl,
+  pubmedSearchUrl,
+  pubmedSummaryUrl,
   removePaper,
   saveLibrary,
   updatePaper,
@@ -6888,14 +6895,34 @@ const phylogeneticTreeTool = (ctx) => define({
   },
 });
 
+/** Fetch one E-utilities URL through the harness web service and parse JSON. */
+async function eutilsRequest(web, url, signal, label) {
+  let result;
+  try {
+    result = await web.fetch({ url }, signal);
+  } catch (error) {
+    throw new MolbioInputError(`${label} could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const body = result?.body?.content;
+  if (typeof body !== 'string' || body === '') {
+    throw new MolbioInputError(`${label} returned no content (status ${result?.statusCode ?? 'unknown'})`);
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw new MolbioInputError(`${label} returned a non-JSON response (status ${result?.statusCode ?? 'unknown'})`);
+  }
+}
+
 const pubmedAbstractTool = (ctx) => define({
   name: 'molbio_pubmed_abstract',
-  description: 'Fetch PubMed abstracts for PMIDs via NCBI E-utilities (efetch). Requires the deployment to provide the web fetch capability; otherwise it reports that clearly. Use it to pull abstracts for papers found by molbio_pubmed_search before adding them to the library.',
+  description: 'Fetch PubMed abstracts for PMIDs via NCBI E-utilities (efetch). Requires the deployment to provide the web fetch capability; otherwise it reports that clearly. Pass api_key (or set NCBI_API_KEY / MOLBIO_NCBI_API_KEY) to attribute the request to your NCBI key and raise the rate limit. Use it to pull abstracts for papers found by molbio_pubmed_search before adding them to the library.',
   parameters: {
     type: 'object',
     required: ['pmids'],
     properties: {
       pmids: { type: 'array', items: { type: 'string' }, description: 'PubMed IDs, e.g. ["37607951"].' },
+      api_key: { type: 'string', description: 'Optional NCBI API key for E-utilities. Prefer setting NCBI_API_KEY in the environment: an inline key appears in the conversation transcript.' },
     },
   },
   outputSchema: {
@@ -6939,7 +6966,8 @@ const pubmedAbstractTool = (ctx) => define({
     if (web === undefined || typeof web.fetch !== 'function') {
       throw new MolbioInputError('this deployment provides no web fetch capability, so PubMed abstracts cannot be retrieved; molbio_pubmed_search still works for titles and snippets');
     }
-    const url = `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&id=${pmids.join(',')}&retmode=xml`;
+    const apiKey = pubmedApiKey(args);
+    const url = pubmedFetchUrl(pmids, apiKey);
     const result = await web.fetch({ url }, exec?.signal);
     const body = result?.body?.content;
     if (typeof body !== 'string' || body === '') {
@@ -7290,21 +7318,24 @@ function paperServiceDeps(ctx, exec, args) {
 
 const pubmedSearchTool = (ctx) => define({
   name: 'molbio_pubmed_search',
-  description: 'Search the web for literature (PubMed results preferred). Uses the harness web-search service; returns up to max_results sources with titles, snippets, URLs and extracted PMIDs. Add the ones you keep to the reading library with molbio_paper_add.',
+  description: 'Search PubMed for literature. With an NCBI API key (the api_key argument, or NCBI_API_KEY / MOLBIO_NCBI_API_KEY in the environment) it queries the official E-utilities API and returns PubMed records with PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web-search service. Add the papers you keep to the reading library with molbio_paper_add.',
   parameters: {
     type: 'object',
     required: ['query'],
     properties: {
       query: requiredString('Search query, e.g. "CRISPR base editing review 2024" or "site:pubmed.ncbi.nlm.nih.gov KRAS G12D".'),
       max_results: { type: 'integer', description: 'Maximum results (1-20, default 8).' },
+      api_key: { type: 'string', description: 'Optional NCBI API key for the official PubMed E-utilities API. Prefer setting NCBI_API_KEY in the environment: an inline key appears in the conversation transcript.' },
     },
   },
   outputSchema: {
     type: 'object',
     additionalProperties: false,
-    required: ['query', 'sources'],
+    required: ['query', 'backend', 'sources'],
     properties: {
       query: { type: 'string' },
+      backend: { type: 'string', enum: ['pubmed-eutils', 'web-search'] },
+      total_matches: { type: 'integer' },
       answer: { type: 'string' },
       sources: {
         type: 'array',
@@ -7317,14 +7348,22 @@ const pubmedSearchTool = (ctx) => define({
             url: { type: 'string' },
             snippet: { type: 'string' },
             pmid: { type: 'string' },
+            doi: { type: 'string' },
+            authors: { type: 'string' },
+            journal: { type: 'string' },
+            year: { type: 'string' },
           },
         },
       },
     },
   },
   render(value) {
-    if (value.sources.length === 0) return `no results for "${value.query}"`;
-    const lines = [`results for "${value.query}":`];
+    const via = value.backend === 'pubmed-eutils' ? ' via PubMed E-utilities' : '';
+    if (value.sources.length === 0) return `no results for "${value.query}"${via}`;
+    const matches = value.total_matches === undefined
+      ? ''
+      : ` — ${value.total_matches} matching record${value.total_matches === 1 ? '' : 's'}`;
+    const lines = [`results for "${value.query}"${via}${matches}:`];
     if (value.answer !== undefined) lines.push(value.answer);
     for (const source of value.sources) {
       const pmid = source.pmid !== undefined ? ` [PMID ${source.pmid}]` : '';
@@ -7334,12 +7373,26 @@ const pubmedSearchTool = (ctx) => define({
     return lines.join('\n');
   },
   async execute(args, exec) {
-    const web = ctx.get('web');
-    if (web === undefined) throw new MolbioInputError('the web search service is not available in this composition; molbio_pubmed_search needs ctx.web');
     const maxResults = args.max_results ?? 8;
     if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 20) {
       throw new MolbioInputError('max_results must be an integer between 1 and 20');
     }
+    const web = ctx.get('web');
+    const apiKey = pubmedApiKey(args);
+    if (apiKey !== undefined) {
+      if (web === undefined || typeof web.fetch !== 'function') {
+        throw new MolbioInputError('an NCBI API key was provided, but this deployment provides no web fetch capability; the official PubMed API needs ctx.web.fetch');
+      }
+      const search = await eutilsRequest(web, pubmedSearchUrl(args.query, maxResults, apiKey), exec?.signal, 'PubMed esearch');
+      const { ids, count } = parseEsearch(search);
+      if (ids.length === 0) {
+        return { query: args.query, backend: 'pubmed-eutils', total_matches: count, sources: [] };
+      }
+      const summary = await eutilsRequest(web, pubmedSummaryUrl(ids, apiKey), exec?.signal, 'PubMed esummary');
+      const sources = parseEsummaryRecords(summary).map(esummarySource);
+      return { query: args.query, backend: 'pubmed-eutils', total_matches: count, sources };
+    }
+    if (web === undefined) throw new MolbioInputError('the web search service is not available in this composition; molbio_pubmed_search needs ctx.web (or an NCBI API key plus ctx.web.fetch)');
     const result = await web.search({ query: args.query, maxResults }, exec?.signal);
     const sources = result.sources.map((source) => {
       const pmid = pmidFromUrl(source.url ?? '');
@@ -7352,6 +7405,7 @@ const pubmedSearchTool = (ctx) => define({
     });
     return {
       query: args.query,
+      backend: 'web-search',
       ...result.content !== undefined ? { answer: result.content } : {},
       sources,
     };
@@ -7520,9 +7574,9 @@ const PROMPT_SECTION = `Molecular-biology tools (dsh-molbio-tools) are available
 - Sequences & files: molbio_align (local alignment with a readable match line), molbio_msa_align (progressive multiple sequence alignment — pass an array of sequences or a workspace FASTA), molbio_conservation (consensus + per-column identity/conservation + variable positions; accepts aligned rows or raw sequences it aligns first), molbio_sequence_logo (draws the same alignment as a sequence logo SVG — pass the molbio_msa_align output rows as the alignment argument; letters are sized by per-position information content), molbio_fasta_fastq (FASTA/FASTQ stats/extract/convert/QC on workspace files), molbio_batch_analyze (run one summary/ORF/enzyme analysis over every matching FASTA/FASTQ/GenBank/.dna file in a directory and write one CSV/TSV table), molbio_extract_region (pull a CDS/promoter/region from a plasmid file by feature label or coordinates).
 - CRISPR: molbio_grna_design (family-aware guide RNAs over a sequence or plasmid file: cas_family spcas9/sacas9/cas12a/cas13a/cas13b/cas13d selects the PAM side, crRNA length, seed and target type — Cas12a uses a 5' TTTV PAM and 23 nt crRNA; Cas13 targets RNA and reports a PFS preference rather than a PAM. Both strands are scanned for DNA families, the sense strand by default for Cas13; guides are filtered on GC/poly-T/self-complementarity and ranked, with a mismatch-tolerant off-target search over the same sequence — reaching a whole genome simply means passing it as the target). Pass the top candidates on for ordering with save_path (CSV) or map_path (SVG map); the ranking is a heuristic and says so, so present it as candidate ranking, never as a validated efficiency prediction.
 - Map extras: pass gc_skew: true for the GC skew ring, show_unique_cutters: true to mark single-cutting enzymes on the map.
-- Literature & records: molbio_pubmed_abstract (fetch abstracts by PMID — works only when the deployment provides web fetch), molbio_paper_export_bibtex (papers.json → .bib), molbio_protocol_add / molbio_protocol_list / molbio_protocol_update (protocols.json), molbio_experiment_log / molbio_experiment_list (experiments.json).
+- Literature & records: molbio_pubmed_abstract (fetch abstracts by PMID — needs web fetch; pass api_key or set NCBI_API_KEY to use your NCBI key), molbio_paper_export_bibtex (papers.json → .bib), molbio_protocol_add / molbio_protocol_list / molbio_protocol_update (protocols.json), molbio_experiment_log / molbio_experiment_list (experiments.json).
 - Bench analysis (v19): molbio_fastq_qc (read-level QC for a FASTQ file: per-base quality with quartiles, per-read quality, base content, GC distribution, length, exact duplication, over-represented sequences, adapter screen, plus a report SVG — use it for "is this run good"), molbio_codon_usage (CAI/RSCU/Nc/GC3, rare-codon list and CDS CpG against E. coli/yeast/human — use it for "will this gene express"; it explains, molbio_codon_optimize rewrites), molbio_phylogenetic_tree (distance method: p-distance/JC/K2P/Tamura-Nei, UPGMA or neighbour-joining, bootstrap support, consensus, Newick file and an SVG tree — it is NOT a maximum-likelihood or Bayesian analysis, and bootstrap percentages are not p-values), molbio_pcr_simulate (where a primer pair amplifies: product sizes and coordinates on both strands, mismatch detail, the 3'-end exact-match requirement, circular templates, screening other templates, and an expected gel — use it for "what band will I see"), molbio_gc_composition (sliding-window GC, CpG islands under the Gardiner-Garden or Takai criteria, GC/AT skew with the cumulative-skew origin/terminus indication, dinucleotide obs/exp, entropy, complexity, N50/L50, plus a figure — use it for "is this a promoter or an origin").
-- Literature: molbio_pubmed_search (web search), and the reading library molbio_paper_add / molbio_paper_list / molbio_paper_update / molbio_paper_remove (papers.json in the workspace).
+- Literature: molbio_pubmed_search — with an NCBI API key (api_key argument, or NCBI_API_KEY / MOLBIO_NCBI_API_KEY in the environment) it uses the official PubMed E-utilities API and returns PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web search. The reading library is molbio_paper_add / molbio_paper_list / molbio_paper_update / molbio_paper_remove (papers.json in the workspace).
 
 Cloning workflow rules (follow them to avoid slow re-derivation):
 - To clone a sequence into a plasmid, call molbio_clone_simulate FIRST — pass the BARE insert with add_flanks: true and the tool adds the enzyme recognition sites itself. The tool also validates single cutting, insert orientation, and internal sites itself: never pre-verify enzymes, cutting counts, or flank construction by thinking. Its output already contains final_sequence AND the remapped feature coordinates (features field). NEVER recompute feature coordinates or insert positions by reasoning — always take them from the tool output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-molbio-tools",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Zero-dependency molecular-biology plugin bundle for the DeepSeek Harness: sequence analysis, primer design (incl. cross-intron qPCR primers, TaqMan hydrolysis/MGB probes with ordering CSV and multiplex compatibility), in-silico PCR, cloning simulation, SnapGene .dna parsing and plasmid maps, Sanger verification, protein tools (incl. helical wheel and hydropathy plots), methylation-aware restriction analysis with double-digest buffer checks, qPCR analysis and plotting, multiple sequence alignment that conserves every input residue, conservation analysis, sequence logos, codon-usage analysis, phylogenetic trees with bootstrap support, Newick I/O and long-name label wrapping, CpG-island/GC-skew composition analysis, read-level FASTQ QC, batch file analysis with CSV export, silent restriction-site mutagenesis, family-aware CRISPR gRNA design (SpCas9/SaCas9/Cas12a/Cas13) with off-target search, an opt-in hand-off that shows a generated plot to the model as an attached image, plus a browser-side right-sidebar panel (plasmid maps and sequence logos drawn in the Web GUI) and a literature/protocol/experiment record system.",
   "type": "module",
   "main": "index.mjs",
@@ -96,7 +96,7 @@
       "dshReleases": {
         "0.2.1-rc.1": "unknown",
         "0.2.1-rc.2": "compatible",
-        "0.2.1-rc.3": "unknown"
+        "0.2.1-rc.3": "compatible"
       }
     },
     "bundle": {

package/papers.mjs

@@ -132,6 +132,157 @@ export function pmidFromUrl(url) {
   return match?.[1];
 }
 
+// ── PubMed E-utilities (official API) ───────────────────────────────────────
+//
+// `molbio_pubmed_search` used to depend entirely on the harness web-search
+// service. The official API is a different thing: it answers with PubMed's own
+// records (PMIDs, indexed titles, journal/year/DOI) instead of whatever a
+// general search engine indexed, and an NCBI API key raises the rate limit from
+// 3 to 10 requests per second. The helpers below build the request URLs and
+// normalize the responses; the tool keeps the transport (ctx.web.fetch) so the
+// existing sandbox/consent rules still apply.
+
+/** The E-utilities endpoint prefix. */
+export const EUTILS_BASE = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils';
+
+/**
+ * The NCBI API key for this call: an explicit tool argument first, then the two
+ * environment variables a deployment can set once. A blank value counts as
+ * absent, so an empty `api_key` falls back instead of sending `api_key=` (NCBI
+ * rejects the empty form with a 400 that blames the query).
+ */
+export function pubmedApiKey(args, env = process.env) {
+  for (const candidate of [args?.api_key, env?.NCBI_API_KEY, env?.MOLBIO_NCBI_API_KEY]) {
+    if (typeof candidate === 'string' && candidate.trim() !== '') return candidate.trim();
+  }
+  return undefined;
+}
+
+function eutilsUrl(endpoint, params) {
+  const pairs = Object.entries(params)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`);
+  return `${EUTILS_BASE}/${endpoint}?${pairs.join('&')}`;
+}
+
+/** esearch: the PMIDs matching a query, relevance-ranked. */
+export function pubmedSearchUrl(query, maxResults, apiKey) {
+  return eutilsUrl('esearch.fcgi', {
+    db: 'pubmed',
+    term: query,
+    retmax: maxResults,
+    retmode: 'json',
+    sort: 'relevance',
+    tool: 'dsh-molbio-tools',
+    api_key: apiKey,
+  });
+}
+
+/** esummary: title/authors/journal/year/DOI for the PMIDs esearch returned. */
+export function pubmedSummaryUrl(pmids, apiKey) {
+  return eutilsUrl('esummary.fcgi', {
+    db: 'pubmed',
+    id: pmids.join(','),
+    retmode: 'json',
+    tool: 'dsh-molbio-tools',
+    api_key: apiKey,
+  });
+}
+
+/** efetch: the full XML records (abstracts live here, not in esummary). */
+export function pubmedFetchUrl(pmids, apiKey) {
+  return eutilsUrl('efetch.fcgi', {
+    db: 'pubmed',
+    id: pmids.join(','),
+    retmode: 'xml',
+    tool: 'dsh-molbio-tools',
+    api_key: apiKey,
+  });
+}
+
+/** The PMIDs and total hit count in an esearch JSON response. */
+export function parseEsearch(payload) {
+  if (typeof payload?.error === 'string' && payload.error !== '') {
+    throw new MolbioInputError(`PubMed E-utilities error: ${payload.error}`);
+  }
+  const result = payload?.esearchresult;
+  if (result === undefined || result === null || typeof result !== 'object') {
+    throw new MolbioInputError('PubMed esearch returned no esearchresult — is the response really E-utilities JSON?');
+  }
+  if (typeof result.ERROR === 'string' && result.ERROR !== '') {
+    throw new MolbioInputError(`PubMed esearch failed: ${result.ERROR}`);
+  }
+  const ids = Array.isArray(result.idlist)
+    ? result.idlist.map((id) => String(id).trim()).filter((id) => /^\d+$/.test(id))
+    : [];
+  const count = Number.parseInt(String(result.count ?? ''), 10);
+  return { ids, count: Number.isFinite(count) ? count : ids.length };
+}
+
+/**
+ * Normalize the records in an esummary JSON response.
+ *
+ * The response puts a `uids` array beside one object per PMID; walking `uids`
+ * (rather than Object.keys) keeps the esearch order, which is relevance order.
+ */
+export function parseEsummaryRecords(payload) {
+  if (typeof payload?.error === 'string' && payload.error !== '') {
+    throw new MolbioInputError(`PubMed E-utilities error: ${payload.error}`);
+  }
+  const result = payload?.result;
+  if (result === undefined || result === null || typeof result !== 'object') {
+    throw new MolbioInputError('PubMed esummary returned no result — is the response really E-utilities JSON?');
+  }
+  if (typeof result.error === 'string' && result.error !== '') {
+    throw new MolbioInputError(`PubMed esummary failed: ${result.error}`);
+  }
+  const uids = Array.isArray(result.uids) ? result.uids.map(String) : [];
+  const records = [];
+  for (const uid of uids) {
+    const row = result[uid];
+    if (row === undefined || row === null || typeof row !== 'object') continue;
+    const title = typeof row.title === 'string' ? row.title.trim() : '';
+    const authors = Array.isArray(row.authors)
+      ? row.authors
+        .map((author) => (typeof author?.name === 'string' ? author.name.trim() : ''))
+        .filter((name) => name !== '')
+      : [];
+    const articleIds = Array.isArray(row.articleids) ? row.articleids : [];
+    const doi = articleIds.find((id) => id?.idtype === 'doi' && typeof id.value === 'string')?.value ?? '';
+    const pubdate = typeof row.pubdate === 'string' ? row.pubdate : '';
+    const year = /\b(?:1[89]|20)\d{2}\b/.exec(pubdate)?.[0] ?? '';
+    const journal = typeof row.fulljournalname === 'string' && row.fulljournalname !== ''
+      ? row.fulljournalname
+      : (typeof row.source === 'string' ? row.source : '');
+    records.push({
+      pmid: String(row.uid ?? uid),
+      title,
+      authors,
+      journal,
+      pubdate,
+      year,
+      doi,
+    });
+  }
+  return records;
+}
+
+/** One esummary record as a search source (the shape molbio_pubmed_search returns). */
+export function esummarySource(record) {
+  const source = {
+    title: record.title === '' ? `PMID ${record.pmid}` : record.title,
+    url: `https://pubmed.ncbi.nlm.nih.gov/${record.pmid}/`,
+    pmid: record.pmid,
+  };
+  const authorText = record.authors.length > 2 ? `${record.authors[0]} et al.` : record.authors.join(', ');
+  const snippet = [record.journal, record.year, authorText].filter((part) => part !== '').join(' · ');
+  if (snippet !== '') source.snippet = snippet;
+  if (record.authors.length > 0) source.authors = record.authors.join(', ');
+  if (record.journal !== '') source.journal = record.journal;
+  if (record.year !== '') source.year = record.year;
+  if (record.doi !== '') source.doi = record.doi;
+  return source;
+}
 /** Escape a string for BibTeX. */
 function bibtexEscape(text) {
   return String(text)

package/preset/molbio-lab/agent.cordis.yml

@@ -48,14 +48,15 @@
 # list carries no comments of its own, so none appear below; provenance and the
 # upgrade rules live in this header.
 #
-# Baseline: the `standard` preset of dsh 0.2.1-rc.2 (harness root
+# Baseline: the `standard` preset of dsh 0.2.1-rc.3 (harness root
 # `%APPDATA%\npm\node_modules\@deepseek-ai\dsh`, file
 # `node_modules/@deepseek-ai/dsh-web-app/presets/standard.patch.yml`, whose
 # rows live under the `preset-standard` row's `config.plugins:`).
 #
-# 0.2.1-rc.2 is the first bump since 0.1.7-alpha.1 that changed the row list: it
-# added `time-context`, `tool-schedule` and `tool-plugin-market`; dropped the two
-# disabled optional subagent providers (`tool-subagent-codex`,
+# 0.2.1-rc.3 ships the SAME row list as 0.2.1-rc.2 (verified by diffing the
+# file), so no row changed in this bump. The last upstream row change was
+# 0.2.1-rc.2: it added `time-context`, `tool-schedule` and `tool-plugin-market`;
+# dropped the two disabled optional subagent providers (`tool-subagent-codex`,
 # `tool-subagent-claude-code`) and `tool-ralph`; dropped the persona `suffix` and
 # both `backgroundMode: continuable` settings; and reworded the plan-mode
 # section. Absorb such a bump verbatim — see workflow.md §4.

package/test/smoke.mjs

@@ -99,6 +99,9 @@ const memFs = {
 };
 
 const mockWeb = {
+  // Every fetch URL the tools request, so the tests can prove the NCBI key
+  // actually travels in the E-utilities query instead of merely being accepted.
+  calls: [],
   async search({ query }) {
     return {
       content: `answer for ${query}`,
@@ -109,9 +112,45 @@ const mockWeb = {
       truncated: false,
     };
   },
-  async fetch() {
+  async fetch({ url } = {}) {
+    const target = String(url ?? '');
+    this.calls.push(target);
+    const json = (payload, statusCode = 200) => ({
+      url: target,
+      statusCode,
+      body: { kind: 'text', content: JSON.stringify(payload) },
+      truncated: false,
+    });
+    if (target.includes('/esearch.fcgi')) {
+      if (target.includes('api_key=bad-key')) return json({ error: 'API key invalid' }, 400);
+      return json({ esearchresult: { count: '2', retmax: '2', idlist: ['39609418', '12345678'] } });
+    }
+    if (target.includes('/esummary.fcgi')) {
+      return json({
+        result: {
+          uids: ['39609418', '12345678'],
+          '39609418': {
+            uid: '39609418',
+            title: 'SPLICER: a highly efficient base editing toolbox',
+            pubdate: '2024 Nov',
+            source: 'Nat Biotechnol',
+            fulljournalname: 'Nature biotechnology',
+            authors: [{ name: 'Li X' }, { name: 'Wang Y' }, { name: 'Zhang Z' }],
+            articleids: [{ idtype: 'doi', value: '10.1038/s41587-024-02460-4' }],
+          },
+          '12345678': {
+            uid: '12345678',
+            title: 'An older paper',
+            pubdate: '2019',
+            source: 'Cell',
+            authors: [{ name: 'Doe J' }],
+            articleids: [],
+          },
+        },
+      });
+    }
     return {
-      url: 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi',
+      url: target,
       statusCode: 200,
       body: {
         kind: 'text',
@@ -1891,15 +1930,83 @@ function splicedToGenomic(splicedPos, exons) {
 
 // ── pubmed search (mocked web service) ──────────────────────────────────────
 
+// The keys below are cleared for the whole section: a developer machine with
+// NCBI_API_KEY exported must not silently change what these tests exercise.
+const savedNcbiEnv = {
+  NCBI_API_KEY: process.env.NCBI_API_KEY,
+  MOLBIO_NCBI_API_KEY: process.env.MOLBIO_NCBI_API_KEY,
+};
+delete process.env.NCBI_API_KEY;
+delete process.env.MOLBIO_NCBI_API_KEY;
+
 {
+  // no key and no environment: the pre-existing web-search path
+  mockWeb.calls.length = 0;
   const out = await run('molbio_pubmed_search', { query: 'CRISPR' });
   assert.equal(out.query, 'CRISPR');
+  assert.equal(out.backend, 'web-search');
   assert.equal(out.answer, 'answer for CRISPR');
   assert.equal(out.sources.length, 2);
   assert.equal(out.sources[0].pmid, '12345678');
   assert.equal(out.sources[1].pmid, undefined);
+  assert.equal(mockWeb.calls.length, 0, 'the web-search path must not touch the E-utilities transport');
+}
+
+{
+  // official PubMed API: an explicit key switches the tool to E-utilities, and
+  // the key travels in the request (esearch AND esummary) rather than merely
+  // being accepted by the argument schema.
+  mockWeb.calls.length = 0;
+  const out = await run('molbio_pubmed_search', { query: 'CRISPR base editing', api_key: 'test-key-123' });
+  assert.equal(out.backend, 'pubmed-eutils');
+  assert.equal(out.total_matches, 2);
+  assert.equal(out.sources.length, 2);
+  assert.equal(out.sources[0].pmid, '39609418');
+  assert.equal(out.sources[0].url, 'https://pubmed.ncbi.nlm.nih.gov/39609418/');
+  assert.match(out.sources[0].title, /SPLICER/);
+  assert.equal(out.sources[0].journal, 'Nature biotechnology');
+  assert.equal(out.sources[0].year, '2024');
+  assert.equal(out.sources[0].doi, '10.1038/s41587-024-02460-4');
+  assert.match(out.sources[0].snippet, /Nature biotechnology · 2024 · Li X et al\./);
+  assert.equal(out.sources[1].authors, 'Doe J');
+  assert.ok(mockWeb.calls.every((url) => url.includes('api_key=test-key-123')));
+  assert.ok(mockWeb.calls.some((url) => url.includes('/esearch.fcgi')));
+  assert.ok(mockWeb.calls.some((url) => url.includes('/esummary.fcgi')));
+}
+
+{
+  // the environment fallback is what makes "set the key once" possible
+  const saved = process.env.NCBI_API_KEY;
+  process.env.NCBI_API_KEY = 'env-key-456';
+  try {
+    mockWeb.calls.length = 0;
+    const out = await run('molbio_pubmed_search', { query: 'base editing' });
+    assert.equal(out.backend, 'pubmed-eutils');
+    assert.ok(mockWeb.calls.length === 2 && mockWeb.calls.every((url) => url.includes('api_key=env-key-456')));
+  } finally {
+    delete process.env.NCBI_API_KEY;
+    if (saved !== undefined) process.env.NCBI_API_KEY = saved;
+  }
+}
+
+{
+  // an invalid key is reported as such, not presented as "no results"
+  await assert.rejects(() => run('molbio_pubmed_search', { query: 'x', api_key: 'bad-key' }), /API key invalid/);
 }
 
+{
+  // abstracts use the same key and the efetch endpoint
+  mockWeb.calls.length = 0;
+  const out = await run('molbio_pubmed_abstract', { pmids: ['12345678'], api_key: 'test-key-123' });
+  assert.equal(out.abstracts[0].error, '');
+  assert.equal(out.abstracts[0].title, 'Test Article Title');
+  assert.ok(mockWeb.calls.length === 1 && mockWeb.calls[0].includes('/efetch.fcgi') && mockWeb.calls[0].includes('api_key=test-key-123'));
+}
+
+// Restore whatever the developer machine had exported.
+if (savedNcbiEnv.NCBI_API_KEY !== undefined) process.env.NCBI_API_KEY = savedNcbiEnv.NCBI_API_KEY;
+if (savedNcbiEnv.MOLBIO_NCBI_API_KEY !== undefined) process.env.MOLBIO_NCBI_API_KEY = savedNcbiEnv.MOLBIO_NCBI_API_KEY;
+
 // ── paper library (mocked fs service) ───────────────────────────────────────
 
 {