dsh-molbio-tools 0.24.0 → 0.25.0

package/charts.mjs

@@ -60,6 +60,25 @@ import {
   textRun,
 } from './svgio.mjs';
 
+// ── data-sized min/max ──────────────────────────────────────────────────────
+//
+// A table this module accepts can hold MAX_ROWS (200 000) values. Spreading an
+// array that large into Math.min/Math.max overflows the engine's argument limit
+// with a RangeError, so the data-sized extrema are computed with loops. Fixed-
+// size arrays (bins, colour stops, density grids) still use the spread form.
+
+function minData(values) {
+  let min = Infinity;
+  for (const value of values) if (value < min) min = value;
+  return min;
+}
+
+function maxData(values) {
+  let max = -Infinity;
+  for (const value of values) if (value > max) max = value;
+  return max;
+}
+
 // ── canvas ──────────────────────────────────────────────────────────────────
 
 export const CHART_WIDTH = 720;
@@ -130,8 +149,8 @@ export function histogramBins(values, requestedBins) {
   const finite = values.filter((value) => Number.isFinite(value));
   if (finite.length === 0) throw new MolbioInputError('a histogram needs at least one finite value');
   const n = finite.length;
-  const min = Math.min(...finite);
-  const max = Math.max(...finite);
+  const min = minData(finite);
+  const max = maxData(finite);
   let binCount;
   let rule;
   if (requestedBins !== undefined) {
@@ -634,9 +653,9 @@ export function renderBoxPlot({ title, x_label, y_label, series }) {
     const stats = boxStats(validateFinite(entry.values, `series ${index + 1} values`));
     return { label, stats, color: entry.color ?? SERIES_COLORS[index % SERIES_COLORS.length] };
   });
-  const lows = prepared.map((entry) => Math.min(entry.stats.whisker_low, ...entry.stats.outliers, entry.stats.min));
-  const highs = prepared.map((entry) => Math.max(entry.stats.whisker_high, ...entry.stats.outliers, entry.stats.max));
-  const [domainMin, domainMax] = padDomain(Math.min(...lows), Math.max(...highs));
+  const lows = prepared.map((entry) => Math.min(entry.stats.whisker_low, minData(entry.stats.outliers), entry.stats.min));
+  const highs = prepared.map((entry) => Math.max(entry.stats.whisker_high, maxData(entry.stats.outliers), entry.stats.max));
+  const [domainMin, domainMax] = padDomain(minData(lows), maxData(highs));
   const { parts, plot } = frame(title);
   const y = yAxis(parts, plot, domainMin, domainMax, y_label);
   const slot = plot.width / prepared.length;
@@ -695,8 +714,8 @@ export function renderLineChart({ title, x_label, y_label, series, markers = tru
   });
   const allX = prepared.flatMap((entry) => entry.xs);
   const allY = prepared.flatMap((entry) => entry.ys);
-  const [xMin, xMax] = padDomain(Math.min(...allX), Math.max(...allX));
-  const [yMin, yMax] = padDomain(Math.min(...allY), Math.max(...allY));
+  const [xMin, xMax] = padDomain(minData(allX), maxData(allX));
+  const [yMin, yMax] = padDomain(minData(allY), maxData(allY));
   const { parts, plot } = frame(title);
   const y = yAxis(parts, plot, yMin, yMax, y_label);
   const x = linearScale([xMin, xMax], [plot.x, plot.x + plot.width]);
@@ -719,11 +738,11 @@ export function renderLineChart({ title, x_label, y_label, series, markers = tru
   return {
     svg,
     stats: {
-      series: prepared.map((entry) => ({ label: entry.label, points: entry.xs.length, x_min: Math.min(...entry.xs), x_max: Math.max(...entry.xs), y_min: Math.min(...entry.ys), y_max: Math.max(...entry.ys) })),
+      series: prepared.map((entry) => ({ label: entry.label, points: entry.xs.length, x_min: minData(entry.xs), x_max: maxData(entry.xs), y_min: minData(entry.ys), y_max: maxData(entry.ys) })),
       series_count: prepared.length,
       point_count: prepared.reduce((sum, entry) => sum + entry.xs.length, 0),
-      x_range: [Math.min(...allX), Math.max(...allX)],
-      y_range: [Math.min(...allY), Math.max(...allY)],
+      x_range: [minData(allX), maxData(allX)],
+      y_range: [minData(allY), maxData(allY)],
     },
     marks: prepared.reduce((sum, entry) => sum + entry.xs.length, 0),
     plot,
@@ -815,7 +834,7 @@ export function renderViolinPlot({ title, x_label, y_label, series, bandwidth, s
   });
   const lows = prepared.map((entry) => entry.stats.min);
   const highs = prepared.map((entry) => entry.stats.max);
-  const [domainMin, domainMax] = padDomain(Math.min(...lows), Math.max(...highs));
+  const [domainMin, domainMax] = padDomain(minData(lows), maxData(highs));
   const { parts, plot } = frame(title);
   const y = yAxis(parts, plot, domainMin, domainMax, y_label);
   const slot = plot.width / prepared.length;
@@ -890,8 +909,8 @@ export function renderVolcanoPlot({ title, x_label, y_label, points, fold_change
   const significant = (point) => Math.abs(point.fold) >= fold_change_threshold && point.p <= p_threshold;
   const xs = prepared.map((point) => point.fold);
   const ys = prepared.map((point) => point.significance);
-  const [xMin, xMax] = padDomain(Math.min(0, ...xs), Math.max(0, ...xs));
-  const [yMin, yMax] = padDomain(0, Math.max(...ys, -Math.log10(p_threshold)));
+  const [xMin, xMax] = padDomain(Math.min(0, minData(xs)), Math.max(0, maxData(xs)));
+  const [yMin, yMax] = padDomain(0, Math.max(maxData(ys), -Math.log10(p_threshold)));
   const { parts, plot } = frame(title);
   const y = yAxis(parts, plot, yMin, yMax, y_label ?? '-log10 p');
   const x = linearScale([xMin, xMax], [plot.x, plot.x + plot.width]);
@@ -936,7 +955,7 @@ export function renderVolcanoPlot({ title, x_label, y_label, points, fold_change
       down_count: prepared.filter((point) => significant(point) && point.fold < 0).length,
       fold_change_threshold,
       p_threshold,
-      max_significance: Math.max(...ys),
+      max_significance: maxData(ys),
       labelled: [...labelled],
     },
     marks: prepared.length,
@@ -1000,8 +1019,8 @@ export function renderHeatmap({ title, x_label, y_label, rows, columns, matrix,
   }
   const flat = values.flat().filter((value) => value !== null);
   if (flat.length === 0) throw new MolbioInputError('the matrix has no finite values to draw');
-  const min = Math.min(...flat);
-  const max = Math.max(...flat);
+  const min = minData(flat);
+  const max = maxData(flat);
   const ramp = color_scale ?? (min < 0 ? 'divergingRedBlue' : 'viridis');
   if (COLOR_RAMPS[ramp] === undefined) {
     throw new MolbioInputError(`unknown color_scale ${JSON.stringify(color_scale)}; use ${Object.keys(COLOR_RAMPS).join(', ')}`);

package/cordis.patch.yml

@@ -21,7 +21,7 @@
 #
 # Keep the tool in the PRESET and only the anchor here. An earlier version of
 # this file inserted a host row for the tool itself (`name: dsh-molbio-tools`),
-# which both registered all 60 tools globally and collided with the preset's own
+# which both registered every tool globally and collided with the preset's own
 # copy of that row:
 #
 #     broken: "tool-molbio (...): never started"

package/docs/client-panel.md

@@ -10,14 +10,14 @@
 
 | 落点 | 内容 | 数据来源 |
 | --- | --- | --- |
-| **Molbio**（右栏 tab） | 列出会话工作区里的序列文件，选中即画：`.dna`/`.gb`/`.gbk` → 质粒图谱 + 特征表；`.fa`/`.fasta`（≥2 条）→ 序列标识图 | `workspaceFiles.readAll`（二进制，含 SnapGene） |
+| **Molbio**（右栏 tab） | 列出会话工作区里的序列与结构文件，选中即画：`.dna`/`.gb`/`.gbk` → 质粒图谱 + 特征表；`.fa`/`.fasta`（≥2 条）→ 序列标识图；`.pdb`/`.ent`/`.cif`/`.mmcif`/`.sdf`/`.mol` → 可旋转的 3D ball-and-stick / space-filling 模型 | `workspaceFiles.readAll` / `readBytes`（二进制，含 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`（见下） |
 | **图形调用卡**（`tool.call.toolview`） | `molbio_sequence_logo` / `molbio_grna_design` 的调用卡：logo 直接画图；gRNA 画 `map_path` 并列出前 5 条 guide（无 map 时仍有摘要与表格） | 同上，kind = `molbio-figure` |
 | **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、不弹系统查看器。
+**解析与渲染全部在浏览器里跑本仓库自己的模块**（`lib/genbank/snapgene/plasmid/msa/logo`
+与 `structure-preview` / `structure-render`），不经过任何工具调用、不落盘 SVG、不弹系统查看器。
 
 ### 调用卡的数据通路（`presentationMeta`）
 
@@ -174,8 +174,9 @@ seed）、禁止动态 `import()`、禁止跨插件值导入。它自己只降
    生效、以及坏库时列表仍宣称"还没有文献"。插件详情页的 key 段也被真实驱动：
    `describe` → 输入 → Save（trim 后写入 `NCBI_API_KEY`）→ 状态刷新 + 清空输入 → Remove →
    provider 拒绝时消息原样显示。
-4. **数据通路（质粒）**：真实 pUC118 `.dna` → 记录（名称/长度/拓扑/特征，AmpR 2102-2962
-   反链）→ SVG；GenBank 文本路径与 Node 工具解析结果**逐字段一致**；FASTA → 比对 → logo；
+4. **数据通路（质粒 / 比对 / 结构）**：真实 pUC118 `.dna` → 记录（名称/长度/拓扑/特征，
+   AmpR 2102-2962 反链）→ SVG；GenBank 文本路径与 Node 工具解析结果**逐字段一致**；
+   FASTA → 比对 → logo；PDB → 3D 模型（点选后 canvas 被绘制，拖拽触发重绘）；
    扩展名分类、排序、base64 解码、非法输入的错误路径。
 5. **数据通路（文献库）**：`readWorkspaceText` 的三种结果（有文本 / 文件不存在 / 读取失败）
    分别对应"有库 / 空库 / 报错"；`parseLibrary` 与工具侧契约一致（`{papers: [...]}`）且
@@ -243,7 +244,7 @@ dsh plugin --profile <profile> add dsh-molbio-tools              # 或 npm 包
 `/plugins/dsh-molbio-tools/client.js?rev=<hash>` → 页面刷新时按需拉取、物化、执行
 `apply`。**不需要重建 Web 应用**（这正是客户端模块体系的设计目的）。
 
-与 preset 渠道共存时：preset 提供 57 个工具，bundle 提供面板；同名工具由 preset 层
+与 preset 渠道共存时：preset 提供 64 个工具，bundle 提供面板；同名工具由 preset 层
 shadow（无冲突），面板的 `remote`/`slot` 服务不受影响。
 
 ## 7. 下一步
@@ -256,6 +257,11 @@ shadow（无冲突），面板的 `remote`/`slot` 服务不受影响。
   后续可考虑把同样的卡片给 `molbio_dotplot` 等新画图工具。**任何新卡片上线前先跑
   `test/client.mjs` 的抢座位顺序那一层**：0.7.1 的卡片因为裸 `register()` 抢座位而让 GUI
   起不来（0.7.2 修复，见 §4 第一条）；`contract` 会从产物里的 key 表反推投影数。
+- **结构预览**：✅ 已落地（0.25.0）。Molbio tab 直接读 PDB/mmCIF/SDF-MOL V2000，
+  用 canvas 画可旋转的 3D **ball-and-stick / space-filling** 模型（软件光栅化 + z-buffer +
+  Phong 光照）；明确的边界是 12,000 重原子、5 MB、无 V3000、无分子表面/静电势、
+  “preview, not for measurements”。没有走 `ctx.documentPreviews`：现有 tab 已有文件列表、
+  canvas 与错误态，新增 keyed 容器换不来新的用户能力。
 - **文献库写回**（可选）：若要面板内编辑笔记/标签，需要先定义与 `molbio_paper_*` 工具
   一致的并发契约（乐观版本号或串行化队列），或让工具走同一条 RPC。
 - **上游提案（路径 B）**：preset 渠道挂 client 仍是真实生态需求，可以在社区反馈时

package/docs/history.md

@@ -16,6 +16,8 @@
 
 | 包版本 | preset 版本 | 内容 | 工具数 |
 | --- | --- | --- | --- |
+| 0.25.0 | — | **浏览器内真实 3D 结构预览**：Molbio 面板读 PDB/mmCIF/SDF-MOL V2000，软件光栅化 ball-and-stick / space-filling，拖拽旋转、滚轮缩放；工具数不变 | 64 |
+| 0.24.1 | — | **输入边界与数据安全加固**：BibTeX 不再覆盖文献库、相对读取按会话工作区、批量/glob/并发声明修复、20 万行输入不再 `RangeError`；工具数不变 | 64 |
 | 0.24.0 | — | **数据卫生版**：新增 `molbio_contamination_screen`（内置载体/接头短签名，双链、0–2 错配）与 `molbio_fastq_trim`（质量/接头/引物/poly/N/长度，写 FASTQ/FASTA）；修 FASTQ QC 接头表 Small RNA 5' 的 RNA→DNA 静默错 | 62 → 64 |
 | 0.23.0 | — | **2.0 遗留修复 + 2.9a 调用卡 + 两个候选池工具**：跨内含子引物报告真实反向分子（F 在 R 上游）、logo/gRNA 调用卡、`molbio_protein_charge`、`molbio_dotplot`；同版完成 **DSH 0.2.2-rc.1 适配**（删掉上游已移除的 `list-agents` 子路径行、subagent 模型选择改用新键、守卫补上 specifier 解析） | 60 → 62 |
 | 0.22.2 | — | **DSH 0.2.1-rc.5 适配**：基线 rc.3 → rc.5（上游 standard 逐字节未变）；contract 声明守卫兼容桌面版裁掉 `lib/types` 的打包形态（+突变自检）；engines.node 与 CI 降到 24 | 60 |
@@ -49,6 +51,58 @@
 
 ---
 
+## v0.25.0（2026-11-10，包 0.25.0）
+
+**三条教训，关于“看得见”“同一份源码”和“产物真的能跑”。**
+
+**(1) 2D PCA 不是文献里的结构图。** 第一版把 3D 坐标投到两个主轴，画一张静态 SVG；
+它保留了相对位置，却丢掉深度、遮挡和空间关系，蛋白质像线稿、核酸像折线。学术界常见的
+配图是立体的 ball-and-stick、space-filling 或 surface，而不是单张投影。0.25.0 在发布前
+改为**真实原子模型**：透视、z-buffer、Phong 光照、深度雾化；球和键按元素着色，支持
+ball-and-stick 与 space-filling 两种表示。没有采用卡通 ribbon：它需要二级结构、朝向和
+带宽的额外几何，且不是这一版要解决的问题。
+
+**(2) 软件光栅化让“浏览器里看到的”和“测试里验证的”是同一套像素。** 不引入 WebGL 或
+Three.js；`structure-render.mjs` 返回 RGB 缓冲，面板只把它 `putImageData` 到 canvas。
+Node 测试能直接检查中心原子、非背景像素、两种表示和 PNG 编码；否则 canvas 行为只能靠
+肉眼或第二个渲染器验证，二者必分叉。代价是 CPU 渲染：拖动时 1× 采样，松开后 2×，
+12,000 个重原子封顶。
+
+**(3) 产物能生成，不等于产物能运行。** 加结构预览时发现 bundler 在生成 re-export 时
+丢掉了 imported name，所有 `browser-api.mjs` 再导出在产物里都是
+`require(target).undefined`；格式/模块存在性检查全绿，但真实浏览器半拿到 undefined。
+现在保留 imported name，并在 `test/client.mjs` 加一条“产物不得含
+`require(...).undefined`”的结构断言。这也是为什么“同一份源码”必须配合**执行**产物的
+守卫，而不只是文本对比。
+
+**顺带记录**：只改浏览器半也会改变根包产物，所以根包 `0.24.1 → 0.25.0`、面板包
+`0.1.10 → 0.1.11` 同时升版本。工具数保持 64，benchmark 保持 65 题。结构解析与渲染在
+`structure-preview.mjs` / `structure-render.mjs`，面板用 canvas 承载，不再使用
+`ctx.documentPreviews`（现有 tab 已有文件列表、错误态与画布）。
+
+## v0.24.1（2026-11-08，包 0.24.1）
+
+**三条教训，都是“合法输入 + 默认路径”才会暴露的错。**
+
+**(1) “自定义文件名”不能等于“库文件本身”。** `molbio_paper_export_bibtex` 的默认输出是
+`path.replace(/\.json$/i, '.bib')`；当用户传 `file: refs.txt` 时这个替换是 no-op，
+于是导出的 BibTeX **直接覆盖文献库**。修法不是拒绝 `refs.txt`，而是先判断 `.json` 是否存在，
+不存在就追加 `.bib`。教训：**默认值必须是“另一个文件”的证明**，不能依赖字符串替换恰好命中。
+
+**(2) 用户规模数组不能 spread 进 `Math.min`/`Math.max`。** 图表接受 200,000 行、
+FASTQ QC 接受约 200,000 条 reads，而 `Math.min(...values)` 在这些规模上会以
+`RangeError` 失败；错误发生在参数个数上限，不是算法。现在所有可能跟随输入增长的极值
+都用循环；固定的 64 项密码子表之类仍可 spread。教训：**先问数组的上界是谁定的**，再决定写法。
+
+**(3) `safe` 声明要照着“默认写入”写，不是照着“参数是否为空”写。** 四个画图工具在
+`output_path` 省略时仍会写默认 SVG，旧谓词却返回 `true`；并发调用会互相覆盖文件。
+同样的问题在 `molbio_fasta_fastq extract` 带 `output_path` 时也存在。教训：**并发安全
+是“这次调用碰不碰共享状态”，默认值也算碰。**
+
+**顺带记录**：两个客户端产物因 `seqio.mjs` / `protein-structure.mjs` 改动而重建，
+面板包按仓库规则 `0.1.9 → 0.1.10`；工具数保持 64，preset 行清单与 DSH 基线不变。
+`benchmark-changed` 的 POSIX 路径断言在本地沙箱因 Node 无法 spawn `git` 未执行，CI 会执行。
+
 ## v0.24.0（2026-11-05，包 0.24.0）
 
 **三条教训，都关于“表/边界看起来对、实际不对”。**

package/docs/maintainer.md

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

package/docs/roadmap.md

@@ -10,7 +10,7 @@ L = 需要新机制或外部资源）。
 
 ---
 
-## 1. 当前状态（0.23.0）
+## 1. 当前状态（0.25.0）
 
 - 64 个 `molbio_*` 工具，零依赖，随 preset 分发（见 [README](../README.md)）。
 - 离线测试金字塔 + 组合漂移守卫全绿；`benchmark/` 提供**模型使用**维度的评估
@@ -45,6 +45,15 @@ L = 需要新机制或外部资源）。
   的 key 解析顺序变为 **`api_key` 参数 → DSH 凭据库 → 环境变量**（环境变量会被 agent 自己的 shell
   子进程继承，凭据库不会）；同时插件详情页出现 **PubMed API key** 表单，用户不必改 YAML。
   没有凭据库的组合行为与 0.22.0 相同。
+- **0.25.0 交付 2.9c 真实 3D 结构预览（工具数不变）**：Molbio 面板新增 PDB/mmCIF/SDF-MOL
+  V2000 的 **ball-and-stick / space-filling** 软件光栅化（透视、z-buffer、Phong 光照、
+  深度雾化、CPK 配色），支持拖拽旋转、滚轮缩放与表示切换；12,000 重原子封顶，
+  明确拒绝 V3000，并标注"preview, not for measurements"。根包 `0.24.1 → 0.25.0`、
+  面板包 `0.1.10 → 0.1.11`。同版修掉客户端 bundler 丢掉 re-export imported name 的缺陷。
+- **0.24.1 是输入边界与数据安全加固版（工具数不变）**：修掉 BibTeX 导出覆盖文献库、
+  相对路径按 provider cwd 解析、四个默认写 SVG 的工具被误标并发安全、批量 glob /
+  `max_files` / 坏路径、文献与协议库坏条目，以及 20 万行表格 / 13 万条 reads 触发的
+  `Math.min(...)` RangeError。面板包 `0.1.9 → 0.1.10`（客户端产物重建）。
 - **0.24.0 是数据卫生版**：新增 survey #11 载体/接头污染筛查与 #12 FASTQ 修剪/过滤；
   同时修掉 FASTQ QC 接头表里 Small RNA 5' 的 RNA→DNA 归一化静默错（旧表在 DNA reads 上
   只能命中反向互补）。工具 62 → 64，benchmark 63 → 65；客户端产物仅因
@@ -166,9 +175,10 @@ v16 的 CRISPR 已有订购 CSV 先例，可直接复用格式。
   （`molbio-figure` 投影 + `FIGURE_TOOL_KEYS`；logo 画图，gRNA 画图谱并列出前 5 条 guide）。
   `test/map-card.mjs` 现在同时跑两种卡片，`contract` 从产物里的两张 key 表反推投影数。
 - 文献库**写回**需先定并发契约（当前只读）；
-- 结构文件的浏览器内预览（`.pdb/.cif/.sdf/.mol`）：`ctx.documentPreviews.register` +
-  keyed 座位是**容器**，不是现成的 3D 查看器——要么只做 2D 投影（Cα 轨迹/二级结构条带），
-  要么单独估工。
+- ✅ **已做（0.25.0）**：结构文件的浏览器内预览（`.pdb/.ent/.cif/.mmcif/.sdf/.mol`）
+  接在现有 Molbio tab 里，做**真实 3D 原子模型**（ball-and-stick / space-filling，
+  透视 + z-buffer + Phong 光照）；拖拽旋转、滚轮缩放。没有走 `ctx.documentPreviews`，
+  也没有做卡通 ribbon、分子表面或静电势。边界与测试见 [history.md](history.md) 的 v0.25.0 段。
 
 ### 2.10 ✅ 图表八种全部落地（0.17.0 第一批 3 种，0.18.0 第二批 3 种 + 色带）
 

package/docs/store-evidence.md

@@ -150,9 +150,9 @@ pnpm 的 hoisted linker 会在 `node_modules/` 留下一个指向仓库目录的
 ```
 node test/contract.mjs       → 17 checks passed（host 契约、client 产物、tarball 覆盖、声明回退的突变自检）
 node test/preset-health.mjs  → all 29 rows load on dsh 0.2.2-rc.1
-node test/smoke.mjs          → registered 62 tools, all smoke tests passed
+node test/smoke.mjs          → registered 64 tools, all smoke tests passed
 node test/drift-probe.mjs    → 16/16（15 个突变全部被抓到）
-node benchmark/run.mjs --offline → 63 tasks checked against the shipped tools
+node benchmark/run.mjs --offline → 65 tasks checked against the shipped tools
 ```
 
 `test/release.mjs` 在完整权限的本地会话里整套通过（包括末尾的 npm 版本探测）；

package/fastq-qc.mjs

@@ -115,7 +115,10 @@ function entropyOf(counts) {
  * that tapers is not mistaken for a quality drop.
  */
 function perPosition(entries, maxBases) {
-  const longest = Math.max(...entries.map((entry) => entry.sequence.length));
+  // A loop, not Math.max(...lengths): a 200k-read run is within the supported
+  // cap and would otherwise overflow the argument limit with a RangeError.
+  let longest = 0;
+  for (const entry of entries) if (entry.sequence.length > longest) longest = entry.sequence.length;
   const length = Math.min(longest, maxBases);
   const rows = [];
   for (let position = 0; position < length; position++) {
@@ -411,9 +414,24 @@ export function fastqQcReport(entries, options = {}) {
   }
 
   const perBase = perPosition(selected, settings.max_plot_bases);
-  const summaryQualities = selected.flatMap((entry) => [...entry.quality].map(phredOf));
-  const q20 = summaryQualities.filter((value) => value >= 20).length;
-  const q30 = summaryQualities.filter((value) => value >= 30).length;
+  // One streaming pass over the qualities. The previous version materialised
+  // every Phred score of every sampled read in one array (200k reads x 150 bp
+  // is 30 million numbers) and then filtered it twice; the counters need none
+  // of that memory, and the statistics are unchanged.
+  let qualitySum = 0;
+  let qualityCount = 0;
+  let q20 = 0;
+  let q30 = 0;
+  for (const entry of selected) {
+    for (const character of entry.quality) {
+      const value = phredOf(character);
+      qualitySum += value;
+      qualityCount++;
+      if (value >= 20) q20++;
+      if (value >= 30) q30++;
+    }
+  }
+  if (qualityCount === 0) throw new MolbioInputError('the FASTQ reads contain no quality values');
   const gcCount = selected.reduce((sum, entry) => {
     let gc = 0;
     for (const base of entry.sequence) if (base === 'G' || base === 'C') gc++;
@@ -441,9 +459,9 @@ export function fastqQcReport(entries, options = {}) {
     gc_percent: Math.round(gcFraction * 10000) / 100,
     n_bases: nCount,
     n_percent: Math.round((nCount / allBases) * 10000) / 100,
-    quality_mean: Math.round(mean(summaryQualities) * 100) / 100,
-    quality_q20_percent: Math.round((q20 / summaryQualities.length) * 10000) / 100,
-    quality_q30_percent: Math.round((q30 / summaryQualities.length) * 10000) / 100,
+    quality_mean: Math.round((qualitySum / qualityCount) * 100) / 100,
+    quality_q20_percent: Math.round((q20 / qualityCount) * 10000) / 100,
+    quality_q30_percent: Math.round((q30 / qualityCount) * 10000) / 100,
     quality_tail_below_30: tailPosition(perBase, 30),
     quality_tail_below_20: tailPosition(perBase, 20),
     per_base: perBase,

package/host.mjs

@@ -27,8 +27,8 @@
  *
  * ── WHY NOT JUST ANCHOR ON index.mjs ───────────────────────────────────────
  *
- * `index.mjs` is the TOOL plugin: importing it must register 57 tools and a
- * prompt section. A host row naming it would put every tool back into every
+ * `index.mjs` is the TOOL plugin: importing it must register all 64 tools and
+ * a prompt section. A host row naming it would put every tool back into every
  * session, which is the thing the preset split exists to avoid. This anchor is
  * deliberately inert.
  *

package/index.mjs

@@ -2211,7 +2211,14 @@ function fsService(ctx) {
 
 async function readFileBytes(ctx, exec, path) {
   const fs = fsService(ctx);
-  const target = await fs.resolve(path);
+  // Resolve a model-supplied relative name against the SESSION workspace, not
+  // the provider's process cwd. `ctx.fs.resolve(path)` alone uses the backend
+  // default (process.cwd()), which is why tool-fs asks `workingDirectory` for
+  // the agent's cwd; the sandbox policy carries the same root here. Absolute
+  // paths are still accepted unchanged (workspaceFilePath leaves them alone).
+  const sandboxPolicyService = ctx.get('sandboxPolicy');
+  const policy = sandboxPolicyService?.resolve({ ...exec?.agent !== undefined ? { session: exec.agent.session } : {} });
+  const target = await fs.resolve(workspaceFilePath(path, exec, policy?.workspaceRoot), { signal: exec?.signal });
   return await fs.readBytes(target, exec?.signal, MAX_DNA_BYTES);
 }
 
@@ -3547,6 +3554,8 @@ const proteinPropsTool = define({
 });
 
 const proteinChargeTool = (ctx) => define({
+  // Always writes protein-charge.svg and may open a viewer.
+  safe: false,
   name: 'molbio_protein_charge',
   description: 'Plot a protein\'s net charge across a pH range and report the isoelectric point on the same curve (Henderson-Hasselbalch summation over the terminal groups, K/R/H positive and D/E/C/Y negative). pka_set selects the pK table: bjellqvist (the set molbio_protein_props uses, so the pI matches) or emboss (the Epk.dat values). The SVG is written to the workspace and opened with the OS default viewer (auto_view, default true); the sampled curve and the charge at pH 7.4 are returned too. pI is an estimate and is only meaningful together with the named pK set.',
   parameters: {
@@ -3620,6 +3629,8 @@ const proteinChargeTool = (ctx) => define({
 });
 
 const dotplotTool = (ctx) => define({
+  // Always writes dotplot.svg and may open a viewer.
+  safe: false,
   name: 'molbio_dotplot',
   description: 'Compute and draw a self-comparison dotplot of a DNA sequence by exact word matching: a black cell at (i,j) means the k-mer at i equals the k-mer at j (direct repeat); a red cell means it equals the REVERSE COMPLEMENT of the k-mer at j (inverted repeat). word defaults to 8 (4-12); lower words find shorter repeats and produce more dots. The plot is binned to a fixed grid so a repetitive sequence cannot produce an enormous file; direct/inverted match counts and any scan/plot caps are reported. The SVG is written and opened with the OS default viewer (auto_view, default true). Exact k-mer view — not a windowed identity/scoring dotplot.',
   parameters: {
@@ -3803,7 +3814,9 @@ const WHEEL_RESIDUE_SCHEMA = {
 };
 
 const helicalWheelTool = (ctx) => define({
-  safe: (args) => args.output_path === undefined || args.output_path === '',
+  // It always writes the SVG (output_path only chooses the name), so it is
+  // never concurrency-safe; the old predicate marked the common case safe.
+  safe: false,
   name: 'molbio_helical_wheel',
   description: 'Draw the helical wheel (Schiffer-Edmundson projection) of a peptide or protein stretch and analyse it: residues are placed 100° apart on the circle (3.6 residues per turn of an ideal alpha-helix), coloured by residue class (hydrophobic/polar/acidic/basic), with the Eisenberg hydrophobic moment μH of the stretch and the maximum μH over every window of moment_window residues (11 by default). An amphipathic helix shows one hydrophobic face and one polar face. The tool WRITES an SVG file and opens it with the OS default viewer (auto_view, default true); all values are sequence-propensity estimates from published scales, not a structure prediction.',
   parameters: {
@@ -3922,7 +3935,8 @@ const HYDROPATHY_PEAK_SCHEMA = {
 };
 
 const hydropathyTool = (ctx) => define({
-  safe: (args) => args.output_path === undefined || args.output_path === '',
+  // Always writes the SVG; see the helical-wheel note.
+  safe: false,
   name: 'molbio_hydropathy_plot',
   description: 'Plot the Kyte-Doolittle hydropathy profile of a protein: a sliding-window average (window, default 9; use 19-21 for transmembrane spans), the GRAVY value, and every peak whose window average reaches the threshold (default 1.6, the classic membrane-spanning cutoff). The tool WRITES an SVG file and opens it with the OS default viewer (auto_view, default true); the per-residue profile is also returned so it can feed further analysis. Values are the Kyte-Doolittle propensity scale, not a topology prediction.',
   parameters: {
@@ -5484,7 +5498,10 @@ function validateGrnaOptions(args) {
 }
 
 const fastaFastqTool = (ctx) => define({
-  safe: (args) => args.action !== 'convert' && args.action !== 'extract',
+  // convert always writes; extract writes only when output_path is given, so
+  // stats/qc (and extract without a path) are the pure cases.
+  safe: (args) => !(args.action === 'convert'
+    || (args.action === 'extract' && args.output_path !== undefined && args.output_path !== '')),
   name: 'molbio_fasta_fastq',
   description: 'Work with FASTA/FASTQ files in the workspace. action=stats: per-entry and overall statistics (length/GC). action=extract: pull entries by id (exact or substring) and optionally write them to a FASTA file. action=convert: FASTQ → FASTA (output_path required). action=qc: FASTQ quality statistics (mean/min/max Phred, low-quality fraction, per-position means).',
   parameters: {
@@ -5652,13 +5669,22 @@ async function batchFileList(ctx, exec, args, policy, root) {
   const files = [];
   let truncated = false;
   if (Array.isArray(args.paths) && args.paths.length > 0) {
-    for (const supplied of args.paths) {
+    // The directory walk enforces max_files; the explicit list must too, or the
+    // documented 1-500 bound disappears for the easier input form.
+    const maxFiles = Math.min(args.max_files ?? 50, BATCH_LIMITS.maxFiles);
+    for (const supplied of args.paths.slice(0, maxFiles)) {
       const absolute = workspaceFilePath(supplied, exec, root);
-      const target = await fs.resolve(absolute);
       const label = relative(root, absolute).split(sep).join('/');
-      files.push({ target, label });
+      try {
+        const target = await fs.resolve(absolute);
+        files.push({ target, label });
+      } catch (error) {
+        // A bad explicit path is one error ROW, not a failed batch: the same
+        // contract the directory walk provides for files it cannot parse.
+        files.push({ label, resolveError: error instanceof Error ? error.message : String(error) });
+      }
     }
-    return { fs, files, truncated, maxBytes };
+    return { fs, files, truncated: args.paths.length > files.length, maxBytes };
   }
   if (typeof fs.listDir !== 'function') {
     throw new MolbioInputError('this harness fs service has no listDir; pass an explicit paths array instead of a directory');
@@ -5818,6 +5844,10 @@ const batchAnalyzeTool = (ctx) => define({
     const rows = [];
     for (const file of files) {
       const format = detectBatchFormat(file.label, '');
+      if (file.resolveError !== undefined) {
+        rows.push(batchErrorRow(file.label, format, file.resolveError));
+        continue;
+      }
       try {
         const info = file.size === undefined ? await fs.stat(file.target) : { size: file.size };
         if (info?.size !== undefined && info.size > maxBytes) {
@@ -7441,7 +7471,14 @@ const pubmedAbstractTool = (ctx) => define({
     }
     const apiKey = await pubmedKey(args, ctx);
     const url = pubmedFetchUrl(pmids, apiKey);
-    const result = await web.fetch({ url }, exec?.signal);
+    let result;
+    try {
+      result = await web.fetch({ url }, exec?.signal);
+    } catch (error) {
+      // Same contract as eutilsRequest: a transport failure is a tool-input
+      // error the caller can report, not a raw exception escaping the tool.
+      throw new MolbioInputError(`PubMed efetch could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const body = result?.body?.content;
     if (typeof body !== 'string' || body === '') {
       throw new MolbioInputError(`efetch returned no content (status ${result?.statusCode ?? 'unknown'})`);
@@ -7501,9 +7538,13 @@ const bibtexTool = (ctx) => define({
     const { fs, path, policy } = paperServiceDeps(ctx, exec, args);
     const library = await loadLibrary(fs, path);
     const bibtex = toBibtex(library.papers, args.tag_filter);
+    // Never fall back to the LIBRARY path itself: a custom `file` without a
+    // .json suffix used to make this replace a no-op, so the export overwrote
+    // the library with BibTeX. Always derive a distinct .bib name.
+    const defaultOutput = /\.json$/i.test(path) ? path.replace(/\.json$/i, '.bib') : `${path}.bib`;
     const output = args.output_path !== undefined && args.output_path !== ''
       ? workspaceFilePath(args.output_path, exec, policy?.workspaceRoot)
-      : path.replace(/\.json$/i, '.bib');
+      : defaultOutput;
     await writeWorkspaceFile(fs, output, bibtex, policy);
     return { output_path: output, count: bibtex.trim() === '' ? 0 : library.papers.filter((paper) => args.tag_filter === undefined || args.tag_filter.length === 0 || (paper.tags !== undefined && args.tag_filter.some((tag) => paper.tags.includes(tag)))).length };
   },