dsh-molbio-tools 0.22.0 → 0.22.2

package/CHANGELOG.md

@@ -10,6 +10,127 @@
   改为按**包名**引用后模块缓存问题随之消失——没有拷贝，也就没有需要保持同步的版本目录。
   下文历史条目里出现的 `vN` 目录保持原样，作为当时的记录。
 
+## [0.22.2] — 2026-10-30（DSH 0.2.1-rc.5 适配；契约守卫兼容桌面版）
+
+**工具行为零变化（60 个）。** 0.22.1 的验收基线是 **0.2.1-rc.3**；这一版把基线推到
+**0.2.1-rc.5**，并按 rc.5 的两种安装形态（npm 包 / 桌面 `app.asar`）各跑了一遍。
+
+### 1. 为什么"补丁号在范围内"不等于适配
+
+`engines.dsh` 的 `>=0.2.1-rc.2 <0.3.0-0` 本来就覆盖 rc.5，DSH 的 `unmetRequirements`
+（`@deepseek-ai/dsh-app-boot`）用 `includePrerelease` 判定也通过；但按本仓库的规矩
+（[store-evidence.md](docs/store-evidence.md)），范围只是安装粗筛，**逐版本结论要写进
+`dsh.compatibility.dshReleases`**。rc.3 之后上游发过 rc.4 / rc.5，这一版补上。
+
+### 2. rc.5 上真正跑过的证据
+
+- 桌面版 0.2.1-rc.5（Electron 44.7.0 / Node 24.21.0）的完整流程：`npm pack`（115 文件）→
+  `dsh plugin add` → `--dump-config`（bundle 层与 preset 行都在）→ 启动 HTTP 200 →
+  `__DSH_BOOT__` 含 `dsh-molbio-tools/client.js` → `dsh plugin remove`（0 残留）。
+- `agentPresets/list` 的 `broken` 为空，`pluginInventory/list` 里 molbio-lab 的
+  `tool-molbio` 是 `fiberPhase: "active"`（rules.md 规则 1 的判据，说明 preset 里 60 个工具
+  真的挂上了，而不是"组合树看着对"）。
+- 上游 `dsh-web-app/presets/standard.patch.yml` 在 rc.3 与 rc.5 之间**逐字节一致**
+  （6799 B，同一 sha256），因此 preset 行清单不需要重抄。
+- `preset-health` 30/30 行、`drift-probe` 16/16、`smoke` 60 工具、`bench --offline` 61 题
+  全绿；`contract` 17/17（见下）。
+
+### 3. contract：桌面版不再报"假红"
+
+`app.asar` 为省体积裁掉了 `lib/types/*.d.ts`（`dsh-fs` 整个 `lib/types` 目录都没有），
+于是 0.22.1 的 contract 在桌面版上有两条以 ENOENT 失败——那是**打包差异**，不是契约变化
+（npm tarball 里声明仍在，运行时行为也一致）。这一版把声明守卫改成
+`declarationEvidence()`：先读 `lib/types/*.d.ts`，缺失时读同一份声明的内嵌副本
+（`dsh-llm/lib/typert.host.js`、`dsh-fs-local` / `dsh-attachment-local` 的 runtime），
+两条断言改由同一组谓词驱动；新增第 17 条检查用**突变文本**驱动这些谓词，证明回退
+不是"永远通过"（rules.md 规则 9）。npm 安装与桌面安装现在都是 17/17。
+
+### 4. Node 下限对齐 DSH 桌面运行时
+
+`engines.node` 从 `>=26` 降到 **`>=24`**，CI 矩阵从 26 改到 24：DSH 0.2.1-rc.5 桌面版
+内嵌 **Node 24.21.0**，而 `engines.node` 是给 npm/pnpm 看的（DSH 自己只读 `engines.dsh`）。
+全套测试与 61 题离线 benchmark 都在 24.21.0 上跑过。
+
+### 5. 声明与版本
+
+- 两个包 `dshReleases`：`0.2.1-rc.5: compatible`、`0.2.1-rc.4: unknown`（未装机验证）。
+- CI（`test.yml` / `release.yml`）钉 `@deepseek-ai/dsh@0.2.1-rc.5`，Node 24。
+- 根包 `0.22.1 → 0.22.2`；面板包 `0.1.6 → 0.1.7`（只改清单声明，`lib/client.js` 未变）。
+- 基线文档（maintainer / roadmap / workflow / store-evidence / history）同步到 rc.5。
+
+## [0.22.1] — 2026-10-25（PubMed key 改走 DSH 凭据库；环境变量降为后备）
+
+**工具数不变（60）；没有凭据库的组合，行为与 0.22.0 相同。** 0.22.0 只从 `api_key` 参数与
+`process.env` 读 key；这一版把 DSH 的凭据 seam（`ctx.credentials`）插到两者之间，并把环境变量
+降为最后一级。
+
+### 1. 环境变量为什么不够好
+
+环境变量会被**每个子进程继承**——包括 agent 自己的 shell 工具：一句 `echo $env:NCBI_API_KEY`
+就能把 key 读进对话；它还会出现在进程环境块、崩溃转储与用户的注册表环境里（Windows 的
+`HKCU\Environment` 是明文）。对任何云端凭证这都是不必要的暴露面；NCBI 的 key 虽然只用于
+归属与限速，泄漏仍意味着别人可以用你的配额、顶着你的身份发请求。
+
+DSH 自带的凭据库（`@deepseek-ai/dsh-credentials-local`）就是为这件事存在的：值存在
+`~/.dsh/.credentials.yaml` 里，**不注入环境**、文件仅属主可读、改动热重载，
+`describe()` 只报告是否已设置与来源、从不回显值，而且**存储值优先于启动环境**。
+
+### 2. 新的解析顺序
+
+| 优先级 | 来源 | 说明 |
+| --- | --- | --- |
+| 1 | `api_key` 参数 | 单次调用显式指定；会出现在对话记录与工具卡片里 |
+| 2 | 凭据库 `NCBI_API_KEY` | 推荐；不进入环境，agent 的 shell 子进程读不到 |
+| 3 | 凭据库 `MOLBIO_NCBI_API_KEY` | 同上，插件专用命名 |
+| 4 | 进程环境 `NCBI_API_KEY` / `MOLBIO_NCBI_API_KEY` | 兼容 0.22.0 的用法；暴露面最大 |
+
+实现上调用 `ctx.credentials.resolve(ref)`（存在性检查后才调用），因此凭据库自身的回退层
+（启动环境、项目 `.env`、harness home 的 `.env`）也一并继承；provider 不存在或拒绝该引用时
+**静默回退到 `process.env`**，没有凭据库的组合行为不变。
+
+### 3. key 放进凭据库的三种方式
+
+1. **插件详情页（推荐）**：插件 → 已安装插件 → `dsh-molbio-tools` → **PubMed API key** 一节，
+   粘贴后点 **Save**；见 §4。
+2. 编辑 `~/.dsh/.credentials.yaml`（产品创建、仅属主可读、热重载）：在 `refs:` 下加一行
+   `NCBI_API_KEY: 你的key`；下一次工具调用即生效，无需重启。
+3. 在 DSH 的设置界面保存同名凭据（该界面只显示“是否已设置/来源”，不显示值）。
+
+> **这不是对 agent 的硬隔离。** 凭据库自己的文档写得很清楚：agent 的工具进程以同一个 OS 用户
+> 运行，刻意去读那个文件仍然读得到。它解决的是**自动泄漏**：环境变量会被每个 shell 子进程
+> 无条件继承，而凭据库不会。真正要把密钥挡在 agent 之外，需要换提供方（OS 钥匙串/KMS），
+> 当前产品没有随附这类 provider。
+
+### 4. 图形入口：插件详情页里的 PubMed API key
+
+「改 YAML」对没有计算机基础的用户不是可接受的入口。浏览器半因此注册了一个
+`plugins.detail.section` 条目（`id: molbio-ncbi-key`），只在**本包的 bundle 页**与它声明的**行页**
+上渲染，其它插件返回 `null`：
+
+- 输入框是 `type=password`，只写不读；状态行来自 `ctx.remote.credentials.describe(['NCBI_API_KEY'])`，
+  只显示「已配置 / 未配置 / 来源」，**不回显值**。
+- **Save** 走 `ctx.remote.credentials.set('NCBI_API_KEY', value)`，**Remove** 走 `unset`；
+  保存后输入框立即清空，成功/拒绝消息原样显示（`credential/rejected` 的 provider 原文）。
+- 它和 CLI/工具读的是**同一个**凭据引用，所以两边不需要同步；没有凭据 provider 的部署会显示
+  Unavailable，而工具仍按 §2 的顺序回退到环境变量。
+
+> **测试中发现并修掉的一处真实缺陷（同一版内）**：第一版把 `ctx.remote.credentials` 当成普通
+> 属性直接访问，而它是 **fiber injection**——官方设置页在 `inject` 列表里显式声明
+> `remote.credentials`。没有声明时该命名空间是 `undefined`，点 Save 什么也不会写（状态看起来
+> 只是"没保存"）。现在整段的注册被 `ctx.inject(['remote.credentials'], …)` 门控：有命名空间才
+> 出现，没有则整段不注册（面板不受影响）；写入之后还会重新 `describe`，若 Host 仍报"未配置"
+> 会把这句话显示出来，而不是假装成功。
+
+### 5. 边界与验证
+
+- 默认路径（无 key）仍是 web 检索；有 key 仍是 esearch + esummary + efetch，速率上限不变。
+- 客户端产物因此变了：`lib/client.js` 与 `packages/molbio-panel/lib/client.js` 重新构建，
+  面板包 `0.1.5 → 0.1.6`。
+- smoke 新增三条：**凭据库压过环境变量**、**显式参数压过凭据库**、**provider 抛错时回退到环境**；
+  原有的“无 key 不碰 E-utilities”与“坏 key 报错”保留。`test/client.mjs` 新增详情页座位的
+  等待/注册、本包 subject 渲染、其它 subject 返回 null，以及凭据视图/失败信息三个纯函数。
+- `npm test` 全绿；`client-bundle.mjs --check` 与 `preset-patch.mjs --check` 与源一致。
+
 ## [0.22.0] — 2026-10-25（DSH 0.2.1-rc.3 适配；PubMed 官方 API + NCBI API key）
 
 **工具数不变（60）。新增一条通路：`molbio_pubmed_search` / `molbio_pubmed_abstract` 可以带着

package/README.md

@@ -55,6 +55,10 @@
    装完点 **立即启用**（Enable now）——关掉对话框只会装好、不会启用，之后也可以在插件页打开它的开关。
 3. 重启该 profile，然后在预设选择器里选 "Molecular Biology Lab" 新建会话。
 
+**（可选）PubMed API key**：重启后打开 **插件 → 已安装插件 → `dsh-molbio-tools` 详情页**，
+在 **PubMed API key** 一节粘贴 NCBI key 并点 **Save**。它写进 DSH 凭据库（`~/.dsh/.credentials.yaml`），
+不需要编辑文件、也不进环境变量，下一次检索即生效。没有 key 时检索仍走原来的 web 检索。
+
 ### 次选：命令行安装
 
 没有图形界面时（例如服务器上只用 CLI），用这条命令；它和插件页安装等价，都从 npm registry 取包：
@@ -224,7 +228,7 @@ dsh plugin --profile <profile> add dsh-molbio-panel
 
 | 工具 | 用途 |
 | --- | --- |
-| `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_search` | 搜 PubMed 文献。提供 NCBI API key（`api_key` 参数、**DSH 凭据库**的 `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 过滤） |
@@ -557,10 +561,16 @@ 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 检索通路，行为不变。
+  拿题录（标题/期刊/年份/作者/DOI），`molbio_pubmed_abstract` 用 efetch 拿摘要。key 的解析顺序是
+  **`api_key` 参数 → DSH 凭据库（`NCBI_API_KEY`，其次 `MOLBIO_NCBI_API_KEY`）→ 进程环境变量**。
+  NCBI 的速率上限是**无 key 3 次/秒、有 key 10 次/秒**，一次带 key 的检索是 2 个请求
+  （esearch + esummary）。没有 key 时检索仍走原来的 web 检索通路，行为不变。
+- **优先把 key 放凭据库，而不是环境变量。** 凭据库是 `~/.dsh/.credentials.yaml`（`refs:` 下写
+  `NCBI_API_KEY: …`；图形入口是**插件 → 已安装插件 → dsh-molbio-tools → PubMed API key**）：
+  不进环境、仅属主可读、改完热重载、下一次调用即生效。环境变量会被**每个子进程继承**——包括 agent 自己的 shell 工具，`echo $env:NCBI_API_KEY`
+  就能读出来，而且明文存在用户环境里；内联 `api_key` 还会进入对话记录与工具卡片。
+  > 凭据库不是对 agent 的硬隔离（agent 与你是同一个 OS 用户，刻意去读文件仍可能），但它消除了
+  > 「所有 shell 子进程自动继承」这条泄漏路径——这正是环境变量的主要问题。
 - 阅读库/协议库/实验日志是工作区里的 `papers.json` / `protocols.json` / `experiments.json`，
   写入遵循会话的**沙箱政策**，与其它文件工具同权；面板（Papers tab）直接读 `papers.json`。
 - `molbio_paper_export_bibtex` 可选按 tag 过滤导出。
@@ -655,10 +665,12 @@ node <包目录>\preset\install.mjs --profile web --check  # 只报告，不组
 `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 会出现在对话记录和工具调用卡片里**，
-长期用请设环境变量。
+推荐用**插件详情页**：插件 → 已安装插件 → `dsh-molbio-tools` → **PubMed API key**，粘贴后点 Save
+（写入 DSH 凭据库的 `NCBI_API_KEY`，不进环境变量，下一次检索生效）。也可以手动在
+`~/.dsh/.credentials.yaml` 的 `refs:` 下加一行 `NCBI_API_KEY: 你的key`。
+也可以用环境变量 `NCBI_API_KEY`，或在单次调用里传 `api_key`，但两者都更容易泄漏：**环境变量会被
+agent 的 shell 子进程继承**，内联参数会出现在对话记录与工具卡片里。有 key 时走官方 E-utilities
+（PubMed 自己的题录，含 DOI），没有 key 时仍走 harness 的 web 检索。
 
 **"帮我把这段序列分析一下" 它却问我要参数？**
 把目标说具体即可：要引物还是探针、产物多长、Tm 多少、哪个区域。工具默认值都是常规实验条件

package/build/client-entry.mjs

@@ -32,8 +32,12 @@
 import { createElement as h, useEffect, useMemo, useRef, useState } from 'react';
 import {
   LIBRARY_FILE,
+  NCBI_KEY_REF,
   childPath,
   classifyEntry,
+  credentialInfo,
+  isMolbioDetailSubject,
+  remoteFailure,
   decodeWorkspaceBytes,
   filterPapers,
   isOpenable,
@@ -489,6 +493,142 @@ function PapersPanel({ sessionId, remote, useSessions }) {
     h('div', { style: styles.main }, ...detail));
 }
 
+/** The state of the PubMed key, read from the host's credential store. */
+async function readNcbiKey(remote) {
+  if (remote?.credentials === undefined || typeof remote.credentials.describe !== 'function') {
+    return { phase: 'error', configured: false, writable: false, message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' };
+  }
+  let response;
+  try {
+    response = await remote.credentials.describe([NCBI_KEY_REF]);
+  } catch (error) {
+    response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+  }
+  const failure = remoteFailure(response);
+  if (failure !== '') return { phase: 'error', configured: false, writable: false, message: failure };
+  return { phase: 'ready', ...credentialInfo(response, NCBI_KEY_REF), message: '' };
+}
+
+const keyStyles = {
+  section: { borderTop: '1px solid rgba(127, 127, 127, 0.28)', marginTop: 16, paddingTop: 12, display: 'grid', gap: 8 },
+  title: { margin: 0, fontSize: 14 },
+  note: { margin: 0, fontSize: 12, opacity: 0.75, lineHeight: 1.5 },
+  status: { margin: 0, fontSize: 12 },
+  row: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' },
+  input: { flex: '1 1 240px', minWidth: 200, padding: '4px 8px' },
+  message: { margin: 0, fontSize: 12 },
+};
+
+/**
+ * The Plugins → installed plugin → detail section that stores the NCBI key.
+ *
+ * It renders only for this package's own subject (bundle page, or one of the
+ * row pages the bundle declares) and returns null everywhere else, which is the
+ * contract `plugins.detail.section` asks a contribution to honour. The value is
+ * write-only from here: `credentials.describe` answers whether a key is
+ * configured and where it came from, never the key itself.
+ */
+function NcbiKeySection({ subject, remote }) {
+  const [draft, setDraft] = useState('');
+  const [state, setState] = useState({ phase: 'loading', configured: false, writable: true, message: '' });
+  const subjectToken = isMolbioDetailSubject(subject)
+    ? `${subject.kind}:${subject.pkg.name}:${subject.row?.rowId ?? ''}`
+    : '';
+  useEffect(() => {
+    if (subjectToken === '') return undefined;
+    let live = true;
+    const load = () => readNcbiKey(remote).then((next) => { if (live) setState(next); });
+    load();
+    // Another surface may rotate or clear the same reference (Settings, the
+    // file watcher); follow the host event instead of showing a stale badge.
+    const off = typeof remote?.$on === 'function'
+      ? remote.$on('credentials/reference-updated', (ref) => { if (ref === NCBI_KEY_REF) load(); })
+      : undefined;
+    return () => {
+      live = false;
+      if (typeof off === 'function') off();
+    };
+  }, [remote, subjectToken]);
+  if (!isMolbioDetailSubject(subject)) return null;
+  const busy = state.phase === 'saving';
+  const save = async () => {
+    const value = draft.trim();
+    if (value === '') return;
+    if (remote?.credentials === undefined || typeof remote.credentials.set !== 'function') {
+      setState((previous) => ({ ...previous, phase: 'error', message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' }));
+      return;
+    }
+    setState((previous) => ({ ...previous, phase: 'saving', message: '' }));
+    let response;
+    try {
+      response = await remote.credentials.set(NCBI_KEY_REF, value);
+    } catch (error) {
+      response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+    }
+    const failure = remoteFailure(response);
+    setDraft('');
+    const next = await readNcbiKey(remote);
+    setState(failure !== ''
+      ? { ...next, phase: 'error', message: failure }
+      : next.phase === 'error'
+        ? next
+        : next.configured === true
+          ? { ...next, message: 'Saved. The next PubMed call uses this key.' }
+          : { ...next, phase: 'error', message: 'The host accepted the write but still reports no key configured. Restart the profile and try again.' });
+  };
+  const remove = async () => {
+    if (remote?.credentials === undefined || typeof remote.credentials.unset !== 'function') {
+      setState((previous) => ({ ...previous, phase: 'error', message: 'This deployment exposes no credentials Remote (the settings controller is not mounted).' }));
+      return;
+    }
+    setState((previous) => ({ ...previous, phase: 'saving', message: '' }));
+    let response;
+    try {
+      response = await remote.credentials.unset(NCBI_KEY_REF);
+    } catch (error) {
+      response = { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+    }
+    const failure = remoteFailure(response);
+    const next = await readNcbiKey(remote);
+    setState(failure !== ''
+      ? { ...next, phase: 'error', message: failure }
+      : next.phase === 'error'
+        ? next
+        : next.configured === false
+          ? { ...next, message: 'Removed. PubMed search falls back to web search.' }
+          : { ...next, phase: 'error', message: 'The host still reports a key configured after Remove.' });
+  };
+  const status = state.phase === 'loading'
+    ? 'Checking the credential store…'
+    : state.phase === 'error'
+      ? 'Unavailable'
+      : state.configured
+        ? `Configured${state.source === undefined ? '' : ` (source: ${state.source})`}`
+        : 'Not configured';
+  return h('section', { 'data-molbio-ncbi-key': '', style: keyStyles.section },
+    h('h4', { style: keyStyles.title }, 'PubMed API key'),
+    h('p', { style: keyStyles.note }, 
+      'Stored in the harness credential store. molbio_pubmed_search and molbio_pubmed_abstract use it for the official PubMed E-utilities API; without it they fall back to web search.'),
+    h('p', { 'data-molbio-key-status': state.phase, style: keyStyles.status }, status),
+    h('div', { style: keyStyles.row },
+      h('input', {
+        type: 'password',
+        value: draft,
+        placeholder: 'NCBI API key (36 characters)',
+        autoComplete: 'off',
+        spellCheck: false,
+        'aria-label': 'NCBI API key',
+        style: keyStyles.input,
+        onChange: (event) => setDraft(event.target.value),
+      }),
+      h('button', { type: 'button', disabled: busy || state.writable === false || draft.trim() === '', onClick: save },
+        busy ? 'Saving…' : 'Save'),
+      h('button', { type: 'button', disabled: busy || state.writable === false || state.configured !== true, onClick: remove }, 'Remove')),
+    state.message === '' ? null : h('p', { 'data-molbio-key-message': '', role: 'status', style: keyStyles.message }, state.message),
+    h('p', { style: keyStyles.note },
+      'Create a key under NCBI → Account Settings → API Key Management. Prefer this over an environment variable: the store is not inherited by shell commands.'));
+}
+
 /** Required browser services. */
 const inject = ['slots', 'sidebarRightTabs', 'remote'];
 
@@ -572,6 +712,25 @@ function apply(ctx) {
       key: toolName,
     }, MolbioMapCard)), `molbio panel: ${toolName} card`);
   }
+  // Plugins -> the installed plugin's detail page: the one place a user can
+  // store the NCBI key without editing a YAML file or exporting a variable.
+  //
+  // `remote.credentials` is a FIBER INJECTION, not merely a property on the
+  // Remote carrier: the shipped settings pages declare it in `inject` for the
+  // same reason. Without the declaration `ctx.remote.credentials` is undefined,
+  // which is exactly how the first build of this section made Save a no-op.
+  // The gate keeps the panel working in deployments that expose no credentials
+  // namespace: the section simply never registers there.
+  ctx.effect(() => {
+    const gate = ctx.inject(['remote.credentials'], (keyCtx) => {
+      keyCtx.effect(() => keyCtx.slots.inject('plugins.detail.section', () => keyCtx.slots.register({
+        name: 'plugins.detail.section',
+        id: 'molbio-ncbi-key',
+        order: 100,
+      }, (props) => h(NcbiKeySection, { ...props, remote: keyCtx.remote }))), 'molbio panel: NCBI key section');
+    });
+    return () => { gate.dispose(); };
+  }, 'molbio panel: NCBI key section gate');
 }
 
 export { apply, inject };

package/build/panel-core.mjs

@@ -390,3 +390,41 @@ export function paperLink(paper) {
   if (typeof paper.pmid === 'string' && paper.pmid !== '') return `https://pubmed.ncbi.nlm.nih.gov/${paper.pmid}/`;
   return undefined;
 }
+
+/** The credential reference the PubMed tools read first. */
+export const NCBI_KEY_REF = 'NCBI_API_KEY';
+
+/**
+ * Whether a Plugins-page detail subject is this package's own entry.
+ *
+ * Bundles and rows both expose `pkg.name`; the key section is offered on the
+ * bundle page and on every row page the bundle declares, and on nothing else.
+ */
+export function isMolbioDetailSubject(subject) {
+  if (subject === null || typeof subject !== 'object') return false;
+  if (subject.kind !== 'bundle' && subject.kind !== 'row') return false;
+  const pkg = subject.pkg;
+  return pkg !== null && typeof pkg === 'object' && pkg.name === 'dsh-molbio-tools';
+}
+
+/**
+ * The host failure message carried by a Remote result, or '' on success.
+ * Remote calls answer `{ ok: true, value }` or `{ ok: false, error }`.
+ */
+export function remoteFailure(response) {
+  if (response === null || typeof response !== 'object' || response.ok !== false) return '';
+  const message = response.error?.message;
+  return typeof message === 'string' && message !== '' ? message : 'the host refused the request';
+}
+
+/** One reference's view from a `credentials.describe` response (never the value). */
+export function credentialInfo(response, ref) {
+  const view = response !== null && typeof response === 'object' && response.ok !== false
+    ? response.value?.[ref]
+    : undefined;
+  return {
+    configured: view?.configured === true,
+    writable: view?.writable !== false,
+    ...typeof view?.source === 'string' && view.source !== '' ? { source: view.source } : {},
+  };
+}

package/docs/client-panel.md

@@ -13,6 +13,7 @@
 | **Molbio**（右栏 tab） | 列出会话工作区里的序列文件，选中即画：`.dna`/`.gb`/`.gbk` → 质粒图谱 + 特征表；`.fa`/`.fasta`（≥2 条）→ 序列标识图 | `workspaceFiles.readAll`（二进制，含 SnapGene） |
 | **Papers**（右栏 tab） | 把 `molbio_paper_*` 工具维护的 `papers.json` 渲染成可搜索的阅读列表 + 详情面板（标题/作者/期刊/年份/PMID/URL/标签/笔记，标题链接到 PubMed 或原 URL） | `workspaceFiles.read`（文本） |
 | **图谱调用卡**（`tool.call.toolview`） | `molbio_plasmid_map` / `molbio_plasmid_map_file` 的调用卡：在对话里直接画出这次调用产出的图谱（摘要行 + 写入路径），失败时显示错误文本与 Inspect 入口 | 工具自己声明的 `output.presentationMeta`（见下） |
+| **PubMed API key**（`plugins.detail.section`） | 插件 → 已安装插件 → `dsh-molbio-tools` 详情页里的一段表单：password 输入 + Save/Remove，状态只报「已配置 / 来源 / 未配置」，永不回显值 | `ctx.remote.credentials.describe` / `set` / `unset`（host 的凭据 seam） |
 
 **解析与渲染全部在浏览器里跑本仓库自己的模块**（`lib/genbank/snapgene/plasmid/msa/logo`），
 不经过任何工具调用、不落盘 SVG、不弹系统查看器。
@@ -46,7 +47,7 @@ SVG 随 meta 传输有上限（256 KB）：真实载体的图谱 20-60 KB，但
 | `build/client-bundle-core.mjs` | 打包器的**生成逻辑**（可 import）：`createGenerator({entry, baseDir})` → 模块图 + `renderBundle(packageName)`；`test/contract.mjs` 在进程内用它重算产物做新鲜度检查（不 spawn，受限沙箱下也能验证） |
 | `build/browser-api.mjs` | 浏览器安全面：从**包根的 `.mjs` 源文件**再导出面板可用的一切（单一事实来源） |
 | `build/panel-core.mjs` | 面板的数据通路（分类/解码/解析/渲染/文献库投影），不含 React，可在 Node 里单测 |
-| `build/client-entry.mjs` | 浏览器半本体：两个 tab 类型的注册、正文、标题 chip，以及两个 map 工具的调用卡 |
+| `build/client-entry.mjs` | 浏览器半本体：两个 tab 类型的注册、正文、标题 chip，两个 map 工具的调用卡，以及插件详情页的 key 配置段 |
 | `lib/client.js` | **构建产物**（`exports["./client"]` 指向它；由 `npm run build:client` 生成） |
 | `packages/molbio-panel/` | 面板专用包（宿主半边空实现），面板与 57 个工具解耦的交付通道 |
 | `test/client.mjs` | 按加载器的方式执行产物 + 驱动两条数据通路（含真实 pUC118 夹具） |
@@ -131,6 +132,14 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
 - **图片式交互**：SVG 里注入的是真实 DOM（可缩放、可选中文本），但没有点特征跳转之类的联动。
 - **CSS 内联**：产物刻意不注入样式表——`factory` 里的样式副作用要自己管拆除；
   内联样式让产物保持单文件、零生命周期负担。
+- **key 配置段只在「本包」的详情页出现**：`plugins.detail.section` 是 list 座位，条目自己判断
+  `subject`；本包只在 `kind: bundle|row` 且 `pkg.name === 'dsh-molbio-tools'` 时渲染，其它插件页
+  返回 `null`。它依赖宿主挂载了凭据 provider（默认组合都有）：没有时整段通过
+  `ctx.inject(['remote.credentials'], …)` 门控而不注册，工具仍会按「参数 → 凭据库 → 环境变量」
+  的顺序回退，不会因此不可用。**`remote.credentials` 是 fiber injection，不是普通属性**：
+  官方设置页同样在 `inject` 里声明它；第一版漏了这一步，`ctx.remote.credentials` 是 `undefined`，
+  点 Save 什么也没写（0.22.1 测试中发现并修掉）。**输入框只写不读**：`describe` 的返回里没有值，
+  保存成功后输入框立即清空；写后仍报未配置、或 Remove 后仍报已配置，都会把不一致显示出来。
 - **每次改源都要重新构建**：`lib/client.js` 是**产物**，改了根 `.mjs` 或 `build/*.mjs` 后
   必须重跑 `npm run build:client`，否则面板还跑旧逻辑（这与 preset 的"版本目录"规则是
   两码事：客户端产物靠 `rev` 哈希缓存失效，不靠目录名）。
@@ -146,9 +155,11 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
    `guide`、无 `patterns`、guide `order` 40/41）、四个 keyed 座位的注册、两个正文的 `inject`
    工厂都只交出 `remote`。座位那一层从**一个座位都没声明**的最坏顺序启动（`test/slots-stub.mjs`
    复刻 shell 的 SlotCore 语义）：`apply()` 必须不抛；右栏座位声明后四条注册落地；调用卡座位在
-   ui-tool 声明之前一直**处于等待**、声明之后才落地；重声明不产生重复注册；并当场复刻
-   "未声明座位 `register()` 必抛"的那条 SlotCore 异常——0.7.1 把整个 GUI 卡在
-   "Failed to load plugins" 的就是它。
+   ui-tool 声明之前一直**处于等待**、声明之后才落地；插件详情页座位同样先等待、后注册；重声明
+   不产生重复注册；并当场复刻 "未声明座位 `register()` 必抛"的那条 SlotCore 异常——0.7.1 把整个
+   GUI 卡在 "Failed to load plugins" 的就是它。key 段还断言了：本包 subject 渲染出
+   `section` + password 输入 + Save，其它包的 subject 返回 `null`，以及凭据视图/失败信息
+   三个纯函数（`isMolbioDetailSubject` / `credentialInfo` / `remoteFailure`）。
 3. **组件行为**：`test/panel-render.mjs` 把**真实的面板组件**放进 Node 跑——没有 React
    （harness 里有，浏览器里的 React 由 shell 播种）也没有 DOM，所以这个文件自带一套最小
    钩子宿主（`createElement`/`useState`/`useEffect`/`useMemo`/`useRef`，语义与 React 一致：
@@ -159,7 +170,9 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
    列目录失败的错误态、文献库的列表/搜索/标签过滤/详情/PubMed 链接回退、空库提示、坏库
    报错（**不显示成"空库"**）、以及卸载时中止在途读取。
    这一层抓到过三个真 bug：列表把不可打开的文件也列出来、`sortEntries` 的 `other` 档从不
-   生效、以及坏库时列表仍宣称"还没有文献"。
+   生效、以及坏库时列表仍宣称"还没有文献"。插件详情页的 key 段也被真实驱动：
+   `describe` → 输入 → Save（trim 后写入 `NCBI_API_KEY`）→ 状态刷新 + 清空输入 → Remove →
+   provider 拒绝时消息原样显示。
 4. **数据通路（质粒）**：真实 pUC118 `.dna` → 记录（名称/长度/拓扑/特征，AmpR 2102-2962
    反链）→ SVG；GenBank 文本路径与 Node 工具解析结果**逐字段一致**；FASTA → 比对 → logo；
    扩展名分类、排序、base64 解码、非法输入的错误路径。
@@ -234,6 +247,9 @@ shadow（无冲突），面板的 `remote`/`slot` 服务不受影响。
 
 ## 7. 下一步
 
+- **插件详情页的 key 配置**：✅ 已落地（0.22.1，见第 1 与第 4 节）。后续可把同一个
+  `plugins.detail.section` 模式用于其它凭据（例如文献库的机构代理），前提是它们也有一个
+  稳定的环境变量名。
 - **`tool.call.toolview`**：✅ 已落地（见第 1 与第 3 节），覆盖两个 map 工具。可继续做的
   是给 `molbio_sequence_logo` / `molbio_grna_design` 之类的工具也加上卡片（同一套
   `presentationMeta` + 卡片模式）。**注意上线前先跑 `test/client.mjs` 的抢座位顺序那一层**：

package/docs/history.md

@@ -16,6 +16,8 @@
 
 | 包版本 | preset 版本 | 内容 | 工具数 |
 | --- | --- | --- | --- |
+| 0.22.2 | — | **DSH 0.2.1-rc.5 适配**：基线 rc.3 → rc.5（上游 standard 逐字节未变）；contract 声明守卫兼容桌面版裁掉 `lib/types` 的打包形态（+突变自检）；engines.node 与 CI 降到 24 | 60 |
+| 0.22.1 | — | **PubMed key 改走 DSH 凭据库**：解析顺序 `api_key` → 凭据库 → 环境变量；无凭据库时行为同 0.22.0 | 60 |
 | 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 |
@@ -45,6 +47,25 @@
 
 ---
 
+## v0.22.1（2026-10-25，包 0.22.1）
+
+**环境变量不是唯一选择。** 0.22.0 只从 `api_key` 参数与 `process.env` 读 key；这一版把 DSH 的
+`ctx.credentials` 插到中间，并把环境变量降为后备。
+
+- 新顺序：`api_key` 参数 → 凭据库（`NCBI_API_KEY` / `MOLBIO_NCBI_API_KEY`）→ 进程环境。
+- 为什么：环境变量会被**每个子进程**继承——包括 agent 自己的 shell 工具。凭据库不进入环境、
+  仅属主可读、热重载，`describe()` 不回显值。但 DSH 凭据库的文档也写明：agent 与你是同一个 OS
+  用户，它不是硬隔离，只是消除了「自动继承」这条路径。
+- 没有凭据库的组合（以及 provider 抛错的组合）静默回退到环境，行为与 0.22.0 一致；显式参数仍然
+  最高优先。
+- smoke 新增三条：凭据库压过环境、参数压过凭据库、provider 抛错回退。
+- 0.22.1 同时补了**图形入口**：插件 → 已安装插件 → 本包详情页里的 `plugins.detail.section`
+  表单（password 输入 + Save/Remove，值只写不读）。改 YAML 不该是唯一入口。
+- **测试里抓到的缺陷**：`ctx.remote.credentials` 是 fiber injection，不是 Remote 载体的普通属性。
+  第一版没在 `inject` 里声明它，命名空间就是 `undefined`，Save 静默地什么也没写；官方设置页
+  一直把 `remote.credentials` 写在 `inject` 列表里，那就是这行声明的用途。现在用
+  `ctx.inject(['remote.credentials'], …)` 门控整段注册，并在写后重新 `describe` 核对结果。
+
 ## v0.22.0（2026-10-25，包 0.22.0）
 
 一半是适配（rc.3），一半是新能力（PubMed 官方 API + key）。三条教训。

package/docs/maintainer.md

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

package/docs/roadmap.md

@@ -10,12 +10,12 @@ L = 需要新机制或外部资源）。
 
 ---
 
-## 1. 当前状态（0.22.0）
+## 1. 当前状态（0.22.2）
 
 - 60 个 `molbio_*` 工具，零依赖，随 preset 分发（见 [README](../README.md)）。
 - 离线测试金字塔 + 组合漂移守卫全绿；`benchmark/` 提供**模型使用**维度的评估
   （见 [benchmark/README.md](../benchmark/README.md)）。
-- 基线：DSH **0.2.1-rc.3**。
+- 基线：DSH **0.2.1-rc.5**；DSH 桌面版内嵌 Node 24.21.0，`engines.node` 与 CI 矩阵都按这个下限。
 - **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 已修，套件不再依赖宿主分隔符。
@@ -41,6 +41,16 @@ L = 需要新机制或外部资源）。
   `standard` 行清单**逐字节未变**，`preset-health` / `drift-probe` / `contract` 在 rc.3 上
   全绿，因此这一半只改声明与证据）；`molbio_pubmed_search` / `molbio_pubmed_abstract` 增加
   NCBI API key 通路，走官方 E-utilities（esearch + esummary），无 key 时保持原有 web 检索。
+- **0.22.1 是 key 存放方式的安全加固 + 图形入口**：`molbio_pubmed_search` / `molbio_pubmed_abstract`
+  的 key 解析顺序变为 **`api_key` 参数 → DSH 凭据库 → 环境变量**（环境变量会被 agent 自己的 shell
+  子进程继承，凭据库不会）；同时插件详情页出现 **PubMed API key** 表单，用户不必改 YAML。
+  没有凭据库的组合行为与 0.22.0 相同。
+- **0.22.2 是 rc.5 纯适配版（工具行为零变化）**：基线 rc.3 → rc.5。上游 `standard` 行清单
+  **逐字节未变**；真正的变化在**打包形态**——桌面版 `app.asar` 裁掉 `lib/types`，于是
+  `contract` 的声明守卫改为"npm 包读 `.d.ts`，桌面版读 `typert.host.js` / runtime 内嵌副本"，
+  并加了"突变必须失败"的自检（17 条）。两份 `dshReleases` 增加 rc.5 `compatible`、rc.4
+  `unknown`；`engines.node` 与 CI 降到 DSH 桌面实际内嵌的 **24**。面板包 `0.1.6 → 0.1.7`
+  （只改声明，产物未变）。
 
 ---