@dsh-bio/dsh-bio-gem 0.1.17 → 0.1.18

package/README.md

@@ -196,7 +196,7 @@ unzip -o diamond.zip diamond.exe -d "$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts
 npx -y @deepseek-ai/dsh --profile web --dump-config | grep dsh-bio-gem
 ```
 
-CarveMe + diamond are required only by `gem_build`; the other 20 tools need nothing but a `cobra`-enabled Python.
+CarveMe + diamond are required only by `gem_build`; the other 22 tools need nothing but a `cobra`-enabled Python.
 
 ## 工具（23）
 

package/docs/ARCHITECTURE.md

@@ -6,18 +6,15 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 
 硬性原则（沿袭 bio-genie）：**用户零手动安装、零自愈、通用化（不针对特定机器特化）、结论可溯源**。
 
-## 2. 决策记录（为什么这么设计）
-
-| 日期 | 决策 | 依据 |
-|---|---|---|
-| 08-28 | 插件名 dsh-bio-gem；资产盘点：消费侧已就绪、补构建侧闭环 | 用户决策 |
-| 08-29 | 引擎路线：**任务门槛路由**（不是简单 auto）；落地节奏 **M1 CarveMe+补洞 → M2 gapseq WSL 桥 → M3 双引擎交叉** | 独立设计评估 + 实测（CarveMe AB 不生长=补洞是生存线；WSL 桥显著降级交付风险；Docker 非 WSL 替代）|
-| 08-29 | MVP 工具集：gem_build / gem_validate（G1G2G3 必做，G4 条件、G5 抽检）/ gem_gapfind（L1L2L3）/ gem_gapfill（L1L2 规则自动）/ gem_report（薄版模型卡）；**gem_essentiality 不进首版** | 消费侧 bio_gene_knockout 已存在，避免重复实现 |
-| 08-29 | 修正建议：弃 μ 判据用 FBA 通量判据；pyrodigal 注释前端降 backlog；测试矩阵首版收敛 C58+2 公开株 | 输出口径为 objective_value；默认输入是带注释基因组 |
-
-**采纳原则**：外部分析缺实际环境上下文时，凡冲突处以实测与产品原则为准。
-
-## 3. 工具契约（21 工具 ↔ Python 层；21 op + build CLI）
+## 2. 关键设计取舍
+
+| 取舍 | 结论 | 依据 |
+|---|---|---|
+| 引擎路线 | **任务门槛路由**（不是简单 auto）；落地顺序 CarveMe+补洞 → gapseq WSL 桥 → 双引擎交叉 | 实测（CarveMe AB 不生长=补洞是生存线；WSL 桥显著降级交付风险；Docker 非 WSL 替代）|
+| MVP 工具集 | gem_build / gem_validate（G1G2G3 必做，G4 条件、G5 抽检）/ gem_gapfind（L1L2L3）/ gem_gapfill（L1L2 规则自动）/ gem_report（薄版模型卡）；gem_essentiality 不进首版 | 消费侧 bio_gene_knockout 已存在，避免重复实现 |
+| 判据口径 | 弃 μ 判据用 FBA 通量判据；注释前端（pyrodigal）为可选兜底；回归矩阵覆盖 C58 与公开株 | 输出口径为 objective_value；默认输入是带注释基因组 |
+
+## 3. 工具契约（23 工具 ↔ Python 层；23 op + build CLI）
 
 | 工具 | Python 层 | 状态 |
 |---|---|---|
@@ -26,8 +23,8 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 | gem_gapfind | op gapfind（L1-L3 分级 + 跨引擎介质归一化）| ✅ 已完成 |
 | gem_gapfill | op gapfill（L1/L2 规则 + provenance）| ✅ 已完成 |
 | gem_phenotype | op phenotype_fix（表型回填迭代）| ✅ 已完成 |
-| gem_essentiality | op essential_scan（FVA 预筛 + 手工敲除；预测自动入账本）| ✅ P0 DONE |
-| gem_annotate | op annotate（官方优先 + pyrodigal）| ✅ P0 DONE |
+| gem_essentiality | op essential_scan（FVA 预筛 + 手工敲除；预测自动入账本）| ✅ 已完成 |
+| gem_annotate | op annotate（官方优先 + pyrodigal）| ✅ 已完成 |
 | gem_gapseq | op gapseq（WSL 原子四步，可选项）| ✅ 桥全通 |
 | gem_l3_fix | op l3_fix（L3 补洞：L3a 连通性 + L3b 白名单/BiGG；证据分级 + 预算闸门 + G6 回滚）| ✅ 已完成（C58 Arabinose 0→0.851）|
 | gem_report | op model_info（+ ledger_summary 基率摘要）| ✅ DONE |
@@ -41,21 +38,23 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 | gem_double_knockout | op double_knockout（双敲 v1：GPR 穷尽先验+全扫 max_pairs 预算；假设声明内置）| ✅ 已完成（Atu3364↔Atu4682 对应命中）|
 | gem_enrichment | op enrichment（必需基因通路富集：超几何+BH FDR；无注释 annotation_unavailable 兜底）| ✅ 已完成（C58 55 条 FDR 显著）|
 | gem_targets | op targets（靶点规范导出：11 字段锁定 schema；账本计数闭合；引物设计不做）| ✅ 已完成（258 行三类闭合）|
-| gem_precursor_scan | op precursor_scan（阻塞前体分析：基线通量→可生长即返「无阻塞」；不生长则逐前体移除测试定位阻塞点）| ✅ 2026-09-11（实测归因产出）|
+| gem_precursor_scan | op precursor_scan（阻塞前体分析：基线通量→可生长即返「无阻塞」；不生长则逐前体移除测试定位阻塞点）| ✅ 2026-09-11（实测归因产出）|
+| gem_quality | op quality（模型质量报告：blocked/cyclic/GPR 覆盖等可分解审计）| ✅ 已完成 |
+| gem_sample | op sample（ACHR 通量采样；growth_floor 与边界声明）| ✅ 已完成 |
 
 > Python 分发器 `gem_ops.py` 共 **23 个 op**（annotate/benchmark/biomass_apply/biomass_inspect/double_knockout/enrichment/essential_scan/fluxscan/gapfill/gapfind/gapseq/l3_fix/ledger/media_resolve/model_info/phenotype_fix/precursor_scan/quality/sample/secretion/sensitivity/targets/validate）；`gem_build` 不经分发器，由 `build.py` CLI 直接调用（长任务，jobs.js 拉起）。
 >
-> **工具数（23）与 op 数（23）的关系**：不等且不是简单的 +1 —— `gem_biomass` 一个工具映射 `biomass_inspect` / `biomass_apply` 两个 op（工具 −1），而 `gem_build` 走 CLI 不占 op（工具 +1），两项相抵故数值相同。核验口径：`len(gem_ops.OPS)` 与 `grep -c 'ctx.tools.register(' src/tools.js`。
+> **工具数（23）与 op 数（23）**：数值恰好相同但并非恒等——`gem_biomass` 一个工具映射两个 op（`biomass_inspect` / `biomass_apply`），而 `gem_build` 走 CLI 不占 op，两项相抵。核验口径：`len(gem_ops.OPS)` 与 `grep -c 'ctx.tools.register(' src/tools.js`。
 
 > **precursor_scan 的判据取舍（勿回退）**：初版曾用「全开交换下逐前体 demand 能否净生产」的**绝对可达性**判据，在教科书模型 e_coli_core 上把 atp_c/accoa_c/nad_c/nadph_c 误报为「结构缺失」（辅因子有循环补给路径，稳态下不净生产 ≠ 网络不能供给），故否决。现行判据为**相对判断**：先测基线通量，可生长即直接返回「无阻塞」；不生长才逐前体做移除测试，由「移除后是否恢复通量」直接定义阻塞点。验证锚：toy 单点阻塞模型（精确命中）、e_coli_core（growable，零误报）、iNX1344_v3（infeasible_or_constrained，与 agent 手工探索结论一致）。
 
-> 其余工具层约定：附模型卡统一写入 `python/model_card.py`（lineage/verified_phenotypes/essential_genes/robustness v3）与往返保真自检 `python/roundtrip_check.py`；预测账本 `python/ledger.py`（一个模型一个账本：`~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl`，按模型 basename 分，显式 ledger_path 可覆盖；无参查询=聚合全局视图；旧全局 predictions.jsonl 已迁移为 legacy）。**生长/通量数值口径**：所有产出生长/通量数值的工具输出均带 `units: mmol/gDW/h` 与单点 FBA 声明；条件间通量对比一律走 gem_fluxscan 区间分离判定（overlap=伪影禁止引用）。
+> 其余工具层约定：附模型卡统一写入 `python/model_card.py`（lineage/verified_phenotypes/essential_genes/robustness v3）与往返保真自检 `python/roundtrip_check.py`；预测账本 `python/ledger.py`（一个模型一个账本：`~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl`，按模型 basename 分，显式 ledger_path 可覆盖；无参查询=聚合全局视图；旧全局 predictions.jsonl 已迁移为 legacy）。**生长/通量数值口径**：所有产出生长/通量数值的工具输出均带 `units` 声明——归一化 biomass 反应（产物系数=1）的生长值为 `1/h`（比生长速率 μ）；一般反应通量为 `mmol/gDW/h`。另带单点 FBA 声明；条件间通量对比一律走 gem_fluxscan 区间分离判定（overlap=伪影禁止引用）。
 
-## 4. 引擎路线（M1→M2→M3）
+## 4. 引擎路线（三个阶段）
 
-- **M1（已完成 08-29，C58 实测）**：CarveMe 纯 Windows（独立 venv ~/.dsh/dsh-bio-gem/venv-carveme + diamond PATH 注入）。输入（protein.faa）→ carve -g M9（54s）→ 精确 M9 介质（media_db 提取）G3 PASS（C58 测 0.782）→ 用户目标介质 resolve（跨引擎自然名）→ G3 FAIL 时 L1/L2 规则补洞 → 模型卡。**CarveMe 模型实测：M9 可生长；AB 目标介质 FAIL 且为 L3 内部路径（L1/L2 规则不可修）——诚实报告为已知边界（研究设计既有结论：CarveMe M9 补洞局限）。**
-- **M2（2026-08-29 起）**：gapseq WSL2 桥（`python/gapseq_wsl.py`）。能力探测四件套（wsl/发行版/gapseq 版本/序列库注册 up-to-date——防假已装 UniProt 灾难）；新版 wsl.exe 输出 UTF-8（旧版 UTF-16LE，双解码兼容）；doall 哨兵文件轮询（30-60min，每 2min 进度 + 日志尾部旁观）；产物拷回 → 目标介质验证（AB 自然名）→ L1/L2 补洞闭环 → 模型卡。gem_build `engine` 参数（carveme|gapseq）+ 60min 超时。分发时采用**私有发行版**（wsl --import 自包含 bundle：R+gapseq+序列库 v1.5+哈希校验，版本钉死）。任务分步化（draft/build/transport/fill/adjust 每步落盘 → 断点续跑）待做。
-- **M3**：双引擎交叉验证，产出**分歧清单**（两引擎不一致反应/基因 = 低置信区，需文献/实验校验）而非平均；可选集成 gemsembler（先验证成熟度）；所有比对按**反应级等价类**而非基因级（引擎 GPR 粒度不同）。
+- **阶段一 · CarveMe 纯 Windows（已完成，C58 实测）**：（独立 venv ~/.dsh/dsh-bio-gem/venv-carveme + diamond PATH 注入）。输入（protein.faa）→ carve -g M9（54s）→ 精确 M9 介质（media_db 提取）G3 PASS（C58 测 0.782）→ 用户目标介质 resolve（跨引擎自然名）→ G3 FAIL 时 L1/L2 规则补洞 → 模型卡。**CarveMe 模型实测：M9 可生长；AB 目标介质 FAIL 且为 L3 内部路径（L1/L2 规则不可修）——诚实报告为已知边界（研究设计既有结论：CarveMe M9 补洞局限）。**
+- **阶段二 · gapseq WSL2 桥（2026-08-29 起）**：（`python/gapseq_wsl.py`）。能力探测四件套（wsl/发行版/gapseq 版本/序列库注册 up-to-date——防假已装 UniProt 灾难）；新版 wsl.exe 输出 UTF-8（旧版 UTF-16LE，双解码兼容）；doall 哨兵文件轮询（30-60min，每 2min 进度 + 日志尾部旁观）；产物拷回 → 目标介质验证（AB 自然名）→ L1/L2 补洞闭环 → 模型卡。gem_build `engine` 参数（carveme|gapseq）+ 60min 超时。分发时采用**私有发行版**（wsl --import 自包含 bundle：R+gapseq+序列库 v1.5+哈希校验，版本钉死）。任务分步化（draft/build/transport/fill/adjust 每步落盘 → 断点续跑）待做。
+- **阶段三 · 双引擎交叉验证**：产出**分歧清单**（两引擎不一致反应/基因 = 低置信区，需文献/实验校验）而非平均；可选集成 gemsembler（先验证成熟度）；所有比对按**反应级等价类**而非基因级（引擎 GPR 粒度不同）。
 
 ## 5. 验证关卡规格（产品化 + G0）
 
@@ -70,8 +69,8 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 | G6 | ATP 泄漏检测（全关交换后 ATP demand 应≈0）| ✅ | leak ≤0.01 判 PASS；ATP 解析走 id→name→formula 三级回退（跨 ID 体系）|
 
 **G0 的由来（2026-09-10 实测）**：MetaCyc 风格 id 的公开模型（iNX1344_v3）上，
-`gem_gapfind` 报 5 个 L3「内部通路缺口」，实为 biomass 前体未映射所致——agent 为逐个
-证伪手写 cobra 代码 18 次。现 `gem_validate` 在 G1 之前输出 `g0`，`gem_gapfind` 返回
+`gem_gapfind` 报 5 个 L3「内部通路缺口」，实为 biomass 前体未映射所致——逐个
+证伪需手写 cobra 代码，成本高。现 `gem_validate` 在 G1 之前输出 `g0`，`gem_gapfind` 返回
 `coherence_warning` + `interpretation_guard`，把该结论前置给 agent。
 
 > ⚠️ **G0 判据的取舍（勿回退）**：曾试过「biomass 元素配平」与「前体可达性（demand 逐前体
@@ -87,13 +86,13 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 
 - **L1 缺交换**：培养基成分表 vs 模型 EX_ 列表的集合差 → 修复=补 EX_ 反应（完善环境定义，最安全）
 - **L2 缺转运**：e0↔c0 区室连通性（代谢物在胞外存在但无转运反应入胞）→ 修复=补转运（GPR 可空，标注未表征）
-- **L3 内部路径**：底物有交换+转运却无法达中心代谢 → 需文献反应（M1 报告清单，不自动补）
+- **L3 内部路径**：底物有交换+转运却无法达中心代谢 → 需文献反应（补洞报告清单，不自动补）
 
 已知规律（P1 实测）：多数"不能利用某碳源"缺口是 L1/L2 而非 L3。
 **2026-09-11 补充**：L3 清单须与 G0 一起解读——模型数据质量有问题时 L3 多为症状
 （`find_gaps` 返回值已内置 `coherence_warning` 与 `interpretation_guard`）。
 
-**防过补四闸门**：分级规则优先于 MILP（M1 不做 MILP）；新增反应数封顶（max_add=20）；逐条 provenance 打标（来源/原因/是否借自模板）；修复后强制重验 G3 + 生长值合理性上限告警（>1.0 时 WARN 过补嫌疑）。
+**防过补四闸门**：分级规则优先于 MILP；新增反应数封顶（max_add=20）；逐条 provenance 打标（来源/原因/是否借自模板）；修复后强制重验 G3 + 生长值合理性上限告警（>1.0 时 WARN 过补嫌疑）。
 
 ## 7. 模型卡（sidecar JSON，与 SBML 同目录同名 .card.json）
 
@@ -105,9 +104,9 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 ```
 写盘用 cobra.io.write_sbml_model（cobra 0.32.1 无 Model.save_model——坑位记档）。
 
-## 8. 后台任务（M1 基建，约 30% 工程量）
+## 8. 后台任务（基建）
 
-job 化 + 进度事件（粒度 ≤5s）+ 分步 checkpoint（每步落盘，可断点续跑）+ 结果可重入。引擎无关，M2 gapseq 直接复用。
+job 化 + 进度事件（粒度 ≤5s）+ 分步 checkpoint（每步落盘，可断点续跑）+ 结果可重入。引擎无关，gapseq 引擎直接复用。
 
 ## 9. 与 bio-genie 衔接
 
@@ -122,7 +121,7 @@ job 化 + 进度事件（粒度 ≤5s）+ 分步 checkpoint（每步落盘，可
 - 静态 Cordis `inject` 只声明 `tools`、`skills`；`webServer` 通过 `ctx.inject(['webServer'], cb)` 动态等待。无 webServer 时仍照常注册 23 个 `gem_*` 工具和 gem-expert skill；服务出现后才注册两条路由，并在约 8 秒后后台预热一次 status 缓存。gapseq 先做 `wsl.exe -l -q` 发行版预检，再用固定只读版本命令；子进程 stdin 使用 pipe 并立即关闭，避免 WSL 因 `stdin=ignore` 慢启动。gem 不注册浏览器设置入口，一级入口和五态 UI 由 BioGenie 唯一拥有。
 - 本批严格只读：不实现 job API、安装/删除、配置 schema、自动修复或跨插件命令执行。
 
-## 10. 验收（M1 最小可用判定线）
+## 10. 验收（最小可用判定线）
 
 零手动干预下：**基因组进 → 四个消费工具（FBA/必需性/包络线/面板）不经修改即可用的 SBML 出**，且模型在声明培养基上生长为正；C58 端到端演示通过（build→面板可见→FBA 可跑→必需性可跑）；模型卡齐全（引擎/版本/补洞记录/验证结果，同输入重跑一致）；5-6 Mb 基因组 p95 ≤ 20 min。
 
@@ -133,7 +132,7 @@ job 化 + 进度事件（粒度 ≤5s）+ 分步 checkpoint（每步落盘，可
 | 项目 | C58 | iNX1344_v4 |
 |---|---|---|
 | model_info（读模+摘要） | 6.6s | 3.7s |
-| validate G1-G6 | 7.9s（G3 PASS 0.519981） | 3.7s（G3 WARN，介质层不兼容见 M5） |
+| validate G1-G6 | 7.9s（G3 PASS 0.519981） | 3.7s（G3 WARN，介质层不兼容） |
 | essential_scan 全量（FVA 预筛+手工敲除） | ~50s（FVA 32.3s + 敲除 16.8s，818 候选） | ~30s（FVA 11.9s + 敲除 16.8s，1066 候选） |
 | fluxscan 1 条件（读模+FBA+FVA+pFBA） | ~31s（FVA 24-42s 为主） | ~14s（FVA ~12s） |
 | fluxscan 2 条件 1 对 | 63-72s | 28.5s |

package/docs/releases/v0.1.18.md

@@ -0,0 +1,30 @@
+# @dsh-bio/dsh-bio-gem v0.1.18
+
+> **主题**：公开信息审计复核修复批次（含小型行为修复）。
+> 基因组尺度代谢模型（GEM）构建插件：基因组输入 → 构建 → 验证 → 补洞 → 出报告（标准 SBML + 模型卡）。
+
+## 修复与改进
+
+**行为修复**
+- BiGG 模型下载的代理回退：显式将 `ALL_PROXY` 映射到 http/https（此前仅声明支持、实际未生效）；直连失败时按系统/环境代理重试。
+- 白名单构建入口守卫：`GEM_GAPSEQ_DB` 未配置或无效时在任何文件操作前给出可操作错误（生产调用链同样受控，不再隐式使用相对目录）。
+- 回归脚本解释器默认值沿用 `DSH_HOME`（与生产解析规则一致；显式 `GEM_PYTHON` 仍最高优先）。
+
+**文档与一致性**
+- 架构文档：去内部阶段代号与决策史；工具契约表补 `gem_quality` / `gem_sample`（23 工具 / 23 op）；生长/通量单位口径统一（归一化 biomass 为 1/h；一般通量为 mmol/gDW/h）。
+- 计数一致性：README 英文段 22 工具（除 build 外）；中文标题 23。
+- 过程叙事中性化：代码注释与工具返回文案中的开发阶段标签、调用经历记录全部清除（保留判据依据与错误条件）。
+
+## 安装
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web add @dsh-bio/dsh-bio-gem
+```
+
+桌面端（0.2.0+）：用桌面端自带 CLI（`--profile desktop`）或应用内「插件」页安装。
+分析用 Python（cobra）优先复用 dsh-bio-genie 自举环境；未装 genie 时见 README 第 2 节。
+
+## 已知边界（诚实清单）
+
+- `gem_build` 的 gapseq 引擎为实验性（WSL2 环境绑定，30–60 分钟/模型）；默认 carveme 引擎已可出可验证模型。
+- 其余边界见 v0.1.12 清单。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-bio/dsh-bio-gem",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "基因组尺度代谢模型（GEM）构建插件：输入细菌全基因组（蛋白FASTA，支持多质粒/多染色体），自动构建+验证+补洞+出报告（SBML + 模型卡），供 dsh-bio-genie 消费工具加载使用 | Genome-scale metabolic model builder for dsh",
   "repository": {
     "type": "git",

package/python/annotate.py

@@ -75,7 +75,7 @@ def nucleotide_to_protein(fna_path, out_faa=None, prefer_existing=True):
     base = os.path.splitext(os.path.basename(fna_path))[0]
     if out_faa is None:
         out_faa = os.path.join(d, base + ".gem_annot.faa")
-    # P2-8 修复（2026-08-31 LBA9402 会话首调真实事故）：输出目录不存在直接 FileNotFoundError
+    # 输出目录不存在时自动创建（避免 FileNotFoundError）
     out_dir = os.path.dirname(os.path.abspath(out_faa)) or "."
     os.makedirs(out_dir, exist_ok=True)
 

package/python/benchmark.py

@@ -1,4 +1,4 @@
-# benchmark.py — 阶段B-B1 gem_benchmark 通用基准对比（与物种无关）
+# benchmark.py — gem_benchmark 通用基准对比（与物种无关）
 # 六件通用能力：①介质解析两级策略复用（gapfind.build_ex_index 回退 boundary）②biomass 可行性探针
 # ③六关 G1-G6 并列 ④必需性对比+差异归因（退化侧只报结构不做垃圾对比）⑤账本 comparison_refs 回填
 # （update 语义幂等可重入）⑥可复现性评估。
@@ -400,6 +400,10 @@ def fetch_bigg_model(model_id, dest_dir=None):
     if os.path.exists(dest) and os.path.getsize(dest) > 100000:
         return dest, "cached（已有本地副本）"
     env_proxies = {k: v for k, v in urllib.request.getproxies().items() if v}
+    # ALL_PROXY（getproxies 的 "all" 键）对 http/https 请求不会自动生效，显式映射
+    if env_proxies.get("all"):
+        for _sch in ("http", "https"):
+            env_proxies.setdefault(_sch, env_proxies["all"])
     fallbacks = [("direct", None)] + ([("env-proxy", env_proxies)] if env_proxies else [])
     last_err = None
     for url in urls:
@@ -423,7 +427,7 @@ def fetch_bigg_model(model_id, dest_dir=None):
 
 
 def medium_adaptation_hints(model_path, medium, max_hints=5, progress=None):
-    """阶段C-C5：B3 molybdate 式诊断自动化（通用函数）。介质下 wt<=EPS 时，在严格介质基础上
+    """B3 molybdate 式诊断自动化（通用函数）。介质下 wt<=EPS 时，在严格介质基础上
     逐个补充模型其它交换反应（单变量 lb=-10 试验），报告能恢复生长的成分 -> '介质疑似缺 X'。"""
     m = silent_read_sbml(model_path)
     resolved, unresolved, preset = setup_model_medium(m, medium)

package/python/biomass_tools.py

@@ -293,7 +293,7 @@ def apply_biomass(model_path, biomass_profile, medium=None, phenotype_table=None
         "out": out, "units": GROWTH_UNITS,
         "before_after": {
             "growth": {"before": growth_b, "after": growth_a, "units": GROWTH_UNITS,
-                       # 阶段A-M4 口径声明（只增）
+                       # 口径声明（只增）
                        "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"},
             "phenotype": {"before": {"matched": ph_b.get("matched"), "total": ph_b.get("total")},
                           "after": {"matched": ph_a.get("matched"), "total": ph_a.get("total")}},

package/python/build_whitelist.py

@@ -14,6 +14,10 @@ DIAMOND = os.environ.get(
 
 def build_rxn_fasta(out_fa, out_map=None, min_size=100):
     """聚合 rxn/ 非空文件（文件名=反应 ID）→ 序列 fasta + mapping。返回 (seqs, files_used)。"""
+    if not SEQDB or not os.path.isdir(os.path.join(SEQDB, "rxn")):
+        raise RuntimeError(
+            "GEM_GAPSEQ_DB 未配置或无效：构建白名单需要 gapseq 序列库目录"
+            "（<db>/Bacteria，内含 rxn/ 子目录）")
     rxn_dir = os.path.join(SEQDB, "rxn")
     n_seq = 0
     n_file = 0
@@ -120,8 +124,7 @@ if __name__ == "__main__":
     import json
     fa = sys.argv[1] if len(sys.argv) > 1 else os.path.join(
         os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "whitelist", "rxn_all.fa")
-    if not SEQDB or not os.path.isdir(os.path.join(SEQDB, "rxn")):
-        sys.exit("GEM_GAPSEQ_DB 未设置或无效：请指向 gapseq 序列库目录（<db>/Bacteria，内含 rxn/ 子目录）")
+    # SEQDB 有效性由 build_rxn_fasta 统一守卫（生产调用链同样受控）
     out_dir = os.path.dirname(fa) or "."
     os.makedirs(out_dir, exist_ok=True)
     map_p = os.path.join(out_dir, "rxn_map.tsv")

package/python/coherence.py

@@ -3,9 +3,9 @@
 # 目的：在 G3/G4/G5 与 gapfind 之前，先判断**模型自身数据质量是否允许下结论**，
 # 避免把「未映射代谢物」这类数据问题，误报成「通路缺口 / 必需基因异常」。
 #
-# 实测来源（2026-09-10，iNX1344_v3 —— MetaCyc 风格 id 的公开模型）：
+# 触发场景（iNX1344_v3 —— MetaCyc 风格 id 的公开模型）：
 #   - gem_gapfind 报 5 个 L3「内部通路缺口」，根因实为 biomass 前体未映射；
-#   - agent 为证伪这些假阳性，手写 cobra 代码 18 次（占该轮调用的一半）。
+#   - 逐个手工证伪成本高（需手写 cobra 代码），故把该结论前置给 agent。
 #
 # ⚠️⚠️ 判据设计原则：**零误报优先**。以下两类判据在设计中被实测否决，切勿加回：
 #
@@ -16,7 +16,7 @@
 #  2. 「前体可达性（demand 逐前体 FBA）」——初版实现同样在 e_coli_core 上把
 #     atp_c / accoa_c / nad_c / nadph_c 误报为「既不能合成也不能摄取」。全开交换下
 #     的 demand 语义与胞内辅因子/能量货币的循环补给路径纠缠，判据未成熟。
-#     正确方法（agent 曾手工探索过）待重新设计后引入。
+#     正确方法待重新设计后引入。
 #
 # 保留的判据都经过「问题模型报出真问题 + 标准模型零误报」双向验证：
 #   - id 体系识别（信息性，决定下游名称映射口径）

package/python/double_knockout.py

@@ -1,11 +1,11 @@
-# double_knockout.py — 阶段C-C2 双敲 v1（合成致死预测，L2 非平凡）
+# double_knockout.py — 双敲 v1（合成致死预测，L2 非平凡）
 # 候选池（预算可控）：① GPR 结构先验——纯 or 型且恰 2 基因的反应 = 穷尽型同工酶对（廉价必做）；
 #   ② FVA 预筛活性反应关联基因中"共享反应"的基因对（复用 essential_scan.prescreen_candidates +
 #   scan_essentiality；全扫受 max_pairs 预算上限，默认 5000，超限截断+报告）。
 # 判定：单敲双活（>EPS）且双敲死（<=EPS）→ 合成致死对。单敲生长值按对惰性计算并缓存。
 # 假设声明（方案文件要求，内置于输出与 description）：细菌双敲验证率无大规模实验数据支撑，
 #   本结果=假设生成，供实验设计参考非结论。
-# 退化护栏（阶段 A/B 教训）：wt<=EPS（介质下不生长）→ 不扫描不登记账本，degenerate:true + 介质适配提示。
+# 退化护栏（实测教训）：wt<=EPS（介质下不生长）→ 不扫描不登记账本，degenerate:true + 介质适配提示。
 import os
 import re
 import sys
@@ -70,7 +70,7 @@ def double_knockout(model_path, medium=None, max_pairs=5000, export_csv=None,
     if out["degenerate"]:
         out["degenerate_note"] = (f"wt_growth={wt}<=EPS：被测模型在指定介质下不生长，双敲判定无意义，"
                                   "未扫描、未登记账本。提示：内置介质预设为根瘤菌科（C58）调校，"
-                                  "非根瘤菌模型需先做介质适配（阶段B-B3 molybdate 教训）。")
+                                  "非根瘤菌模型需先做介质适配（molybdate 介质适配教训）。")
         try:
             from benchmark import medium_adaptation_hints
             out["medium_adaptation_hints"] = medium_adaptation_hints(model_path, medium)

package/python/enrichment.py

@@ -1,4 +1,4 @@
-# enrichment.py — 阶段C-C3 必需基因通路富集（超几何 + BH FDR；菌种通用）
+# enrichment.py — 必需基因通路富集（超几何 + BH FDR；菌种通用）
 # 通路注释源（C3 开工探索结论）：gapseq 模型在 SBML groups 里写入 MetaCyc 通路分组
 #   （C58 实测 1051 个 PWY groups，9942 个反应成员关系）；BiGG 静态下载模型无 groups
 #   （iML1515 实测 0）——无 groups 时按契约返回 annotation_unavailable 兜底（不伪造通路）。

package/python/essential_scan.py

@@ -2,7 +2,7 @@
 # 流程: 介质设置 -> FVA(全范围) 预筛可通量基因（死基因免敲）-> 手工单基因敲除
 #       -> 必需基因列表 + 模型卡章节数据（证据分级配色字段）
 # Windows 纪律: FVA processes=1（无 fork）；手工敲除循环；GLPK 快速线性
-# 阶段A-M2: 介质 setup 与扫描核心拆为 setup_model_medium/scan_essentiality 供 sensitivity 复用
+# 介质 setup 与扫描核心拆为 setup_model_medium/scan_essentiality 供 sensitivity 复用
 #           （行为不变，C58 AB 必需 155 锚点必须原样复现）
 import os
 import sys
@@ -19,7 +19,7 @@ FVA_EPS = 1e-9
 
 def setup_model_medium(m, medium=None):
     """介质 setup（对齐 validate G3）：expand_medium -> 全交换清零 -> resolve_medium 设 bounds。
-    阶段A-M2 抽出：essential_scan 与 sensitivity 共用同一介质口径。返回 (resolved, unresolved, preset)。"""
+    抽出（供复用）：essential_scan 与 sensitivity 共用同一介质口径。返回 (resolved, unresolved, preset)。"""
     med, preset = expand_medium(medium) if medium else ({}, None)
     resolved, unresolved = resolve_medium(m, med) if med else ({}, [])
     for r in m.reactions:
@@ -32,7 +32,7 @@ def setup_model_medium(m, medium=None):
 
 
 def prescreen_candidates(m, gene_subset=None):
-    """FVA(fraction=0) 预筛（阶段C-C2 抽出复用）：返回 (active_rxns, cand_genes, n_tested, fva_s)。
+    """FVA(fraction=0) 预筛（抽出复用）：返回 (active_rxns, cand_genes, n_tested, fva_s)。
     cand_genes = 关联至少一个可通量反应的基因（死基因免敲）；n_tested = FVA 检查的反应总数。"""
     t0 = time.time()
     fva = flux_variability_analysis(m, fraction_of_optimum=0.0, processes=1)
@@ -50,7 +50,7 @@ def prescreen_candidates(m, gene_subset=None):
 
 
 def scan_essentiality(m, gene_subset=None, progress=None, return_candidates=False):
-    """必需性扫描核心（阶段A-M2 抽出复用）。输入：介质 bounds 已设好的模型。
+    """必需性扫描核心（抽出复用）。输入：介质 bounds 已设好的模型。
     FVA(fraction=0) 预筛 -> 可通量反应关联基因 -> 手工敲除（<EPS 判必需）。
     返回 {wt_growth, total_genes, fva_tested_reactions, active_reactions, tested_genes,
     essential_count, essential_genes, organs, fva_seconds, knock_seconds}。"""
@@ -88,7 +88,7 @@ def scan_essentiality(m, gene_subset=None, progress=None, return_candidates=Fals
         "fva_seconds": fva_s,
         "knock_seconds": knock_s,
     }
-    if return_candidates:  # 阶段C-C2：double_knockout 复用（避免二次 FVA 预筛）
+    if return_candidates:  # double_knockout 复用（避免二次 FVA 预筛）
         out["candidate_genes"] = sorted(cand_genes)
         out["active_rxn_ids"] = sorted(active_rxns)
     return out
@@ -150,7 +150,7 @@ def essential_scan(model_path, medium=None, gene_subset=None, progress=None, led
         "medium_preset": preset,
         "medium_unresolved": unresolved,
         "note": "必需判定=A 培养基下敲除生长<1e-6；evidence 分级按基因支撑反应是否含 EVIDENCE_math",
-        # 阶段A-M4 口径声明（只增）：wt_growth 为单点 FBA 值
+        # 口径声明（只增）：wt_growth 为单点 FBA 值
         "units": "1/h",
         "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定",
     })
@@ -161,7 +161,7 @@ def essential_scan(model_path, medium=None, gene_subset=None, progress=None, led
             set_essential_genes(model_path, result, model=m)
     except Exception:
         pass
-    # 阶段A遗留修正（退化护栏，只增分支）：wt<=EPS 时必需性判定恒真（v=0 使全部候选判"必需"，
+    # 退化护栏（只增分支）：wt<=EPS 时必需性判定恒真（v=0 使全部候选判"必需"，
     # M5 实测曾把 iNX1344_v4 的 1066 条此类退化预测写入真实账本）——跳过 ledger 自动登记。
     # C58 正常路径（wt>EPS）不进此分支，登记行为不变。
     if result["wt_growth"] <= EPS:
@@ -171,7 +171,7 @@ def essential_scan(model_path, medium=None, gene_subset=None, progress=None, led
                                          "skipped_degraded": len(result["essential_genes"]),
                                          "degraded": True, "warn": warn}
         return result
-    # 阶段A-M3: prediction ledger 自动登记（每必需基因一条；幂等去重；写入失败仅 WARN 不阻塞）
+    # prediction ledger 自动登记（每必需基因一条；幂等去重；写入失败仅 WARN 不阻塞）
     try:
         import ledger as _ledger
         from model_card import load_card as _load_card

package/python/fluxscan.py

@@ -1,4 +1,4 @@
-# fluxscan.py — M1 通量区间制（阶段 A 可信度内核第一件）
+# fluxscan.py — 通量区间制（FVA 区间 + pFBA 点值 + 条件对区间分离判定）
 # 语义（已锁定）：每反应输出 fva_min/fva_max/pfba；条件对比消费区间分离判定；
 #   overlap = 点值差异是求解器伪影，禁止引用。
 # 计算口径：每 condition 独立 silent_read_sbml 重读模型（勿深拷贝）；介质 setup 对齐 validate G3

package/python/gapfind.py

@@ -133,7 +133,7 @@ def build_met_index(m, compartment="c0"):
 
 def build_ex_index(m):
     """EX 交换名索引（去 -e0 后缀小写）-> EX 反应 id。
-    两级策略（阶段B）：
+    两级策略：
       ① EX_/DM_/SK_ 前缀优先——现有行为逐字保留（仅 EX_ 前缀反应入索引）；
       ② 仅当模型 EX_ 索引整体为空（全模型无 EX_ 前缀交换反应）时，回退用 boundary
          单代谢物反应（恰好 1 个代谢物且 rxn.boundary=True）作为交换候选，返回
@@ -150,7 +150,7 @@ def build_ex_index(m):
                     idx.setdefault(norm(nm), r.id)
     if idx:
         return idx
-    # 阶段B 两级策略②：EX_ 层整体缺失 -> boundary 单代谢物反应回退
+    # 两级策略②：EX_ 层整体缺失 -> boundary 单代谢物反应回退
     bidx = BoundaryExIndex()
     for r in m.reactions:
         if r.boundary and len(r.metabolites) == 1:
@@ -170,7 +170,7 @@ def match_ex(sub, ex_idx, allow_substring=None):
       - 短 key（<=4 且不含 '+'）：只允许前缀匹配（n.startswith(key)）
       - 含 '+' 的 key（金属离子）：允许前缀或后缀（iron(fe3+)→ironfe3+ endswith fe3+）
       - 长 key（>=5）：允许子串
-    阶段B：受控子串层可对单个索引禁用——boundary 回退索引（BoundaryExIndex）跨命名空间
+    受控子串层可对单个索引禁用——boundary 回退索引（BoundaryExIndex）跨命名空间
     短名易误配（实测 'd-glucose' ⊂ 'd-glucose1-phosphate' 会把 G1P 交换错当葡萄糖），
     故其 allow_substring=False；普通 dict 索引默认 True，既有行为逐字保留。"""
     key = norm(sub)
@@ -209,7 +209,7 @@ def match_ex(sub, ex_idx, allow_substring=None):
 
 
 class BoundaryExIndex(dict):
-    """两级策略②的 boundary 回退索引（阶段B）。
+    """两级策略②的 boundary 回退索引。
     仅当全模型无 EX_ 前缀交换反应时由 build_ex_index 产出；禁用受控子串回退层
     （跨命名空间误配实证：d-glucose ⊂ d-glucose1-phosphate）。"""
     allow_substring = False

package/python/gem_ops.py

@@ -69,7 +69,7 @@ def op_model_info(args):
             repl["_".join(parts[:2])] += 1
         else:
             repl["other"] += 1
-    # 阶段A-M3: prediction ledger 基率摘要（文件不存在 -> {total: 0}；ledger_path 可覆盖默认账本）
+    # prediction ledger 基率摘要（文件不存在 -> {total: 0}；ledger_path 可覆盖默认账本）
     # P1-3：传 model=path 让摘要给 by_model 分布 + own_model_entries（防「本模型账本 N 条」误报）
     ledger_summary, ledger_context = None, None
     try:
@@ -234,7 +234,7 @@ def op_media_resolve(args):
         "medium_preset": preset,
         "unresolved": unresolved,
         "model": model,
-        # 阶段B-B1 附加（只增）：两级策略②启用标注 + 规范展示名
+        # 附加（只增）：两级策略②启用标注 + 规范展示名
         "boundary_style": boundary_style,
     }
     if boundary_style:
@@ -263,7 +263,7 @@ def op_l3_fix(args):
 
 
 # ---------------------------------------------------------------------------
-# op: fluxscan — 阶段A-M1 通量区间制（FVA 区间 + pFBA 点值 + 条件对区间分离判定）
+# op: fluxscan — 通量区间制（FVA 区间 + pFBA 点值 + 条件对区间分离判定）
 # 语义锁定：overlap = 求解器伪影禁止引用；判定公式见 fluxscan.judge_interval（单测锁定）
 # ---------------------------------------------------------------------------
 def op_fluxscan(args):
@@ -282,7 +282,7 @@ def op_fluxscan(args):
 
 
 # ---------------------------------------------------------------------------
-# op: sensitivity — 阶段A-M2 结构性灵敏度（GAM×biomass 网格 22 组合 + 必需性重扫 + 单组分漂移）
+# op: sensitivity — 结构性灵敏度（GAM×biomass 网格 22 组合 + 必需性重扫 + 单组分漂移）
 # action=probe 秒级只读（GAM 载体定位/组分计数）；缺省 full=22 组合全量（约 35-45min，长任务）
 # ---------------------------------------------------------------------------
 def op_sensitivity(args):
@@ -410,7 +410,7 @@ OPS["sensitivity"] = op_sensitivity
 
 
 # ---------------------------------------------------------------------------
-# op: ledger — 阶段A-M3 prediction ledger（list/query/update；只读/追加/更新，不删行）
+# op: ledger — prediction ledger（list/query/update；只读/追加/更新，不删行）
 # 默认账本 ~/.dsh/dsh-bio-gem/ledger/predictions.jsonl；ledger_path 可覆盖（测试用临时路径）
 # ---------------------------------------------------------------------------
 def op_ledger(args):
@@ -436,7 +436,7 @@ def op_ledger(args):
 
 
 # ---------------------------------------------------------------------------
-# op: benchmark — 阶段B-B1 通用基准对比（六关并列/生长/含边界介质回退/biomass 探针/必需性对比
+# op: benchmark — 通用基准对比（六关并列/生长/含边界介质回退/biomass 探针/必需性对比
 #     含退化护栏/表型/可复现性/账本 comparison_refs 回填；md 落盘可选）
 # ---------------------------------------------------------------------------
 def op_benchmark(args):
@@ -462,7 +462,7 @@ OPS["benchmark"] = op_benchmark
 
 
 # ---------------------------------------------------------------------------
-# op: secretion — 阶段C-C1 可分泌代谢物谱（production envelope 扫描；纯拓扑边界声明内置；
+# op: secretion — 可分泌代谢物谱（production envelope 扫描；纯拓扑边界声明内置；
 #     wt<=EPS 退化护栏不登记；type=secretion 账本登记幂等）
 # ---------------------------------------------------------------------------
 def op_secretion(args):
@@ -481,7 +481,7 @@ OPS["secretion"] = op_secretion
 
 
 # ---------------------------------------------------------------------------
-# op: double_knockout — 阶段C-C2 双敲 v1（合成致死；GPR 穷尽先验 + FVA 预筛全扫，max_pairs 预算；
+# op: double_knockout — 双敲 v1（合成致死；GPR 穷尽先验 + FVA 预筛全扫，max_pairs 预算；
 #     假设声明内置；wt<=EPS 退化护栏不登记；type=synthetic_lethal 账本登记幂等）
 # ---------------------------------------------------------------------------
 def op_double_knockout(args):
@@ -499,7 +499,7 @@ OPS["double_knockout"] = op_double_knockout
 
 
 # ---------------------------------------------------------------------------
-# op: enrichment — 阶段C-C3 必需基因通路富集（超几何单侧 + BH FDR；通路源=SBML groups
+# op: enrichment — 必需基因通路富集（超几何单侧 + BH FDR；通路源=SBML groups
 #     [gapseq MetaCyc PWY]；无注释模型按契约 annotation_unavailable 兜底；不登记账本）
 # ---------------------------------------------------------------------------
 def op_enrichment(args):
@@ -516,7 +516,7 @@ OPS["enrichment"] = op_enrichment
 
 
 # ---------------------------------------------------------------------------
-# op: targets — 阶段C-C4 靶点清单规范导出（账本三类预测 -> 锁定 schema；供下游引物/编辑
+# op: targets — 靶点清单规范导出（账本三类预测 -> 锁定 schema；供下游引物/编辑
 #     工具直接输入；与账本计数闭合；引物/质粒设计本身不做）
 # ---------------------------------------------------------------------------
 def op_targets(args):

package/python/l3_fix.py

@@ -422,7 +422,7 @@ def l3_fix(model_path, medium=None, substrates=None, out=None,
         g = _growth_sole(m, resolved_med, exid)
         if exid and exid in m.reactions and g < 1e-6:
             l3.append({"substrate": sub, "exchange": exid, "growth_sole_before": round(g, 6),
-                       # 阶段A-M4 口径声明（只增）
+                       # 口径声明（只增）
                        "units": "1/h",
                        "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"})
 

package/python/ledger.py

@@ -1,5 +1,5 @@
-# ledger.py — 阶段A-M3 prediction ledger（预测账本，可追踪可实验兑现）
-# 文件: ~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl（一个模型一个账本，2026-08-31 用户决策）
+# ledger.py — prediction ledger（预测账本，可追踪可实验兑现）
+# 文件: ~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl（一个模型一个账本）
 #       ——默认账本按模型文件 basename 推导（model_ledger_path），显式 ledger_path 仍可覆盖；
 #       ——无 model 无 path 的查询/摘要 = 聚合所有模型账本（全局视图，by_model 分布保留）。
 # 迁移：旧全局 predictions.jsonl 已拆分为各模型账本（predictions.jsonl.legacy-20260831 保留备份，
@@ -42,7 +42,7 @@ def _norm_path(p):
 
 
 # ---------------------------------------------------------------------------
-# 账本文件解析：一个模型一个账本（2026-08-31 用户决策）
+# 账本文件解析：一个模型一个账本
 # ---------------------------------------------------------------------------
 def model_ledger_path(model_path):
     """默认账本 = ledger/<模型文件名去扩展名>.jsonl（一个模型一个账本）。"""
@@ -161,7 +161,7 @@ def query_ledger(rtype=None, status=None, condition=None, model=None,
                  limit=None, offset=0, path=None, deprecated=None):
     """条件过滤（type/status/condition/model 前缀匹配、大小写不敏感、可组合）+ 分页。
     账本定位：显式 path > model（该模型自己的账本）> 聚合所有模型账本。
-    阶段D-P2：deprecated 过滤（True=仅打标行；False=仅未打标行；缺省=全部）。"""
+    deprecated 过滤（True=仅打标行；False=仅未打标行；缺省=全部）。"""
     rows, corrupt = _resolve_rows(path=path, model=model)
 
     def _pref(v, q):
@@ -189,7 +189,7 @@ def query_ledger(rtype=None, status=None, condition=None, model=None,
 
 
 def mark_deprecated_duplicates(path=None, progress=None):
-    """阶段D-P2：跨斜杠风格重复打标（一次性运维用；不删行、不改既有字段）。
+    """跨斜杠风格重复打标（一次性运维用；不删行、不改既有字段）。
     识别规则：同一归一化 content hash 的行组内，model 含反斜杠且存在正斜杠同预测 -> 打标
     deprecated=true + superseded_by=<正斜杠版 prediction_id>。path=None 时对每个活动账本执行。
     返回聚合计数。"""
@@ -310,7 +310,7 @@ def ledger_summary(path=None, model=None):
     """账本摘要：{total, by_status, by_type, by_model, deprecated_count}。
     账本定位：显式 path > model（该模型自己的账本）> 聚合所有模型账本。
     P1-3（2026-08-31）：按模型给 own_model_entries=该模型账本条数，防「把全局账本当作本模型预测」误读。
-    2026-08-31 用户决策后：一个模型一个账本，model 定位时 total 即该模型预测数。"""
+    约定：一个模型一个账本，model 定位时 total 即该模型预测数。"""
     rows, corrupt = _resolve_rows(path=path, model=model)
     by_status, by_type, by_model = {}, {}, {}
     dep = 0
@@ -474,7 +474,7 @@ if __name__ == "__main__":
         # 幂等：同内容复跑不追加
         r2 = register_predictions([mk(1), mk(2), mk(3)], path=p)
         assert r2["appended"] == 0 and r2["skipped_duplicates"] == 3, r2
-        # 阶段D P1：model 路径斜杠/大小写不同但指向同一文件 -> 仍判重复
+        # model 路径斜杠/大小写不同但指向同一文件 -> 仍判重复
         r2b = register_predictions([{**mk(1), "model": "f:\\m.XML"}], path=p)
         assert r2b["appended"] == 0 and r2b["skipped_duplicates"] == 1, r2b
         # 新增一条 + ID 连续
@@ -506,7 +506,7 @@ if __name__ == "__main__":
         update_row("P0002", status="literature_supported", path=p)
         rows2, corrupt2 = load_rows(p)
         assert len(corrupt2) == 1 and len(rows2) == 4, (corrupt2, rows2)
-        # 阶段D-P2：直写一条反斜杠 model 的历史态重复行（模拟归一化修复前的存量），
+        # 直写一条反斜杠 model 的历史态重复行（模拟归一化修复前的存量），
         # mark_deprecated_duplicates 打标（不删行）+ query 过滤 + summary deprecated_count
         n_before = len(load_rows(p)[0])
         with open(p, "a", encoding="utf-8") as f:

package/python/model_card.py

@@ -39,7 +39,7 @@ def save_card(model_path, card):
 
 def _ensure_v2(card):
     """legacy 卡（build 直写，无 schema/lineage）即时迁移到 v2。
-    v3 卡（阶段A-M2 起，含 robustness 章节）视为已迁移，不降级。"""
+    v3 卡（含 robustness 章节）视为已迁移，不降级。"""
     if card.get("schema") in (SCHEMA, "v3") and "model_lineage" in card:
         return card
     card.setdefault("schema", SCHEMA)
@@ -165,7 +165,7 @@ def set_essential_genes(model_path, scan_result, model=None):
 
 
 def set_robustness(model_path, sensitivity_result):
-    """sensitivity 结果写入 card.robustness（阶段A-M2：schema v3 起步，向后兼容 v2 卡只增字段）。
+    """sensitivity 结果写入 card.robustness（schema v3 起步，向后兼容 v2 卡只增字段）。
     sensitivity_result: sensitivity() 返回（含 wt_growth_grid/stability/component_sensitivity/gam_carrier）。
     无 card 返回 None（不凭空造卡——纪律同 set_essential_genes）。"""
     card = load_card(model_path)
@@ -218,7 +218,7 @@ if __name__ == "__main__":
         assert back["verified_phenotypes"]["matched"] == 13
         assert back["essential_genes"]["count"] == 2
         assert back["essential_genes"]["genes"][0]["evidence_level"] == "high_confidence"
-        # 阶段A-M2：robustness 章节（v2→v3 只增字段）+ 无 card 不造卡
+        # robustness 章节（v2→v3 只增字段）+ 无 card 不造卡
         assert set_robustness(mp + ".nonexistent", {"wt_growth_grid": []}) is None
         c4 = set_robustness(mp, {"combinations": 22, "baseline_reproduced": True,
                                  "wt_growth_grid": [{"biomass": 1.0, "gam": 40.0, "growth": 0.519981,

package/python/phenotype_fix.py

@@ -92,7 +92,7 @@ def phenotype_fix(model_path, phenotype_table=None, medium=None, max_add=20, out
     except Exception:
         pass
     result["card_version"] = card_version
-    # 阶段A-M3: prediction ledger 自动登记（每底物一条 G4 结果；幂等去重；失败仅 WARN）
+    # prediction ledger 自动登记（每底物一条 G4 结果；幂等去重；失败仅 WARN）
     try:
         import ledger as _ledger
         from model_card import load_card as _load_card

package/python/secretion.py

@@ -1,11 +1,11 @@
-# secretion.py — 阶段C-C1 可分泌代谢物谱（菌种通用）
+# secretion.py — 可分泌代谢物谱（菌种通用）
 # 候选 = 介质层两级策略导出的交换反应（build_ex_index：EX_ 型与 boundary 型模型都适用）。
 # 可分泌判定 = production envelope 扫描：固定生长分数 {0.25,0.5,0.75,0.9,0.99,1.0} 下产物交换最大化
 #   （强制 biomass 通量 >= fraction*wt，最大化交换反应的分泌方向通量）；
 #   任一分数 >0 且产物交换 > 1e-6 → 可分泌。
 # 边界声明（方案文件要求，内置于输出）：未考虑毒性/渗透压/调控，纯拓扑/线性规划结果。
-# 退化护栏（阶段 A/B 教训）：被测模型 wt<=EPS（介质下不生长，如 AB 预设对非根瘤菌科物种——
-#   阶段B-B3 molybdate 教训）→ 不扫描不登记账本，输出 degenerate:true + 介质适配提示。
+# 退化护栏（实测教训）：被测模型 wt<=EPS（介质下不生长，如 AB 预设对非根瘤菌科物种——
+#   molybdate 介质适配经验）→ 不扫描不登记账本，输出 degenerate:true + 介质适配提示。
 import os
 import sys
 import csv
@@ -77,7 +77,7 @@ def secretion(model_path, medium=None, fractions=None, export_csv=None,
     if out["degenerate"]:
         out["degenerate_note"] = (f"wt_growth={wt}<=EPS：被测模型在指定介质下不生长，production envelope 无意义，"
                                   "未扫描、未登记账本。提示：内置介质预设为根瘤菌科（C58）调校，非根瘤菌模型需先做介质适配"
-                                  "（阶段B-B3 教训：iML1515 严格 AB 缺 molybdate）。")
+                                  "（经验：iML1515 严格 AB 缺 molybdate）。")
         try:
             from benchmark import medium_adaptation_hints
             out["medium_adaptation_hints"] = medium_adaptation_hints(model_path, medium)

package/python/sensitivity.py

@@ -1,4 +1,4 @@
-# sensitivity.py — 阶段A-M2 结构性灵敏度（把"模型不确定"量化）
+# sensitivity.py — 结构性灵敏度（把"模型不确定"量化）
 # 网格（全量，不抽样）: biomass 组分系数 ×{0.75, 1.0, 1.25} × GAM {1,5,10,20,30,40,50} = 21 扫点
 #   + 1 基准组合（biomass×1.0 且 GAM=原始值，不扰动）= 22 组合；每组合 wt growth + 必需性重扫
 #   （复用 essential_scan.setup_model_medium / scan_essentiality——M2 顺带工程改进）。
@@ -85,7 +85,7 @@ def find_biomass_gam(m):
         if role and abs(coeff) > 1.0 and role not in stub:
             stub[role] = met.id
             stub_coeffs[role] = coeff
-    # 阶段A-M5 适配（iNX1344_v4 探索结论）：H2O 角色的代谢物可能公式缺失（如 M00001_c
+    # 适配（iNX1344_v4 探索结论）：H2O 角色的代谢物可能公式缺失（如 M00001_c
     # formula=None），且其量级与 GAM 净水电解量（ADP 系数）一致——量级回退补判。
     if {"atp", "adp", "pi", "h"} <= set(stub) and "h2o" not in stub:
         gam_scale = abs(stub_coeffs["adp"])
@@ -240,7 +240,7 @@ def sensitivity(model_path, medium=None, biomass_scales=None, gam_grid=None,
     base_row["baseline"] = True
     grid.append(base_row)
     baseline_set = set(base_row["essential_genes"])
-    degenerate = base_row["growth"] <= EPS  # 阶段A-M5 发现：wt=0 时必需性判定退化（候选全判"必需"）
+    degenerate = base_row["growth"] <= EPS  # 实测：wt=0 时必需性判定退化（候选全判"必需"）
     if degenerate:
         log("[sens] WARN: 基准组合 wt_growth<=0（介质不可解析/模型不生长）——必需性判定退化，"
             "结果仅证明工具在该模型上跑通，essential 集无生物学意义")

package/python/targets.py

@@ -1,4 +1,4 @@
-# targets.py — 阶段C-C4 靶点清单规范导出（下游接口面；菌种通用）
+# targets.py — 靶点清单规范导出（下游接口面；菌种通用）
 # 汇总来源：账本（essentiality/synthetic_lethal/secretion 预测；essential 默认读账本不重扫）。
 # 输出 schema（锁定，每行 11 字段）：target_id/type/genes/met_ids/condition/rationale/
 #   evidence_tier/status/growth_or_maxprod/source/exported_at。

package/python/validate.py

@@ -196,7 +196,7 @@ class Validator:
             "growth_all_closed": round(g_closed, 6),
             "ratio_vs_reference": round(ratio, 4) if ratio is not None else None,
             "checks": {"medium>0": ok_grow, "no_carbon==0": ok_noc, "closed==0": ok_closed},
-            # 阶段A-M4 口径声明（只增）：单点 FBA 值非硬结论
+            # 口径声明（只增）：单点 FBA 值非硬结论
             "units": "1/h",
             "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定",
         }
@@ -312,7 +312,7 @@ class Validator:
                 matched += 1
             results.append({"substrate": sub, "published": int(pub), "predicted": int(pred),
                             "growth": round(g, 6), "exchange": exid or None, "match": bool(ok),
-                            # 阶段A-M4 口径声明（只增）：每底物 growth 为单点 FBA 值
+                            # 口径声明（只增）：每底物 growth 为单点 FBA 值
                             "units": "1/h",
                             "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"})
         rep = {

package/src/jobs.js

@@ -84,7 +84,7 @@ export function readProgress(jobId) {
   }
 }
 
-// 阶段D-P2：失败透明化——job 目录内容摘要 + stderr 尾部（成功路径不计算不返回）
+// 失败透明化——job 目录内容摘要 + stderr 尾部（成功路径不计算不返回）
 function jobDetail(jobDir) {
   let files = []
   try {

package/src/tools.js

@@ -1,4 +1,4 @@
-// dsh-bio-gem — 工具层（defineTool 注册，23 语义化工具，2026-08-30 阶段C-C4 起）
+// dsh-bio-gem — 工具层（defineTool 注册，23 语义化工具）
 // 全部执行走 python/gem_ops.py（JSON stdin 协议）或 build.py CLI（gem_build 长任务）。
 // op 与工具对照：23 op + gem_build（build CLI 直调）；详见 docs/ARCHITECTURE.md §3。
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -324,7 +324,7 @@ export function registerTools(ctx) {
     },
   })))
 
-  // gem_fluxscan：通量区间制（阶段A-M1：FVA 区间 + pFBA 点值 + 条件对区间分离判定）
+  // gem_fluxscan：通量区间制（FVA 区间 + pFBA 点值 + 条件对区间分离判定）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_fluxscan',
     description:
@@ -353,7 +353,7 @@ export function registerTools(ctx) {
     timeoutMs: 900_000,
   })))
 
-  // gem_sensitivity：结构性灵敏度（阶段A-M2：GAM×biomass 网格 22 组合 + 稳定性三分类 + 单组分漂移）
+  // gem_sensitivity：结构性灵敏度（GAM×biomass 网格 22 组合 + 稳定性三分类 + 单组分漂移）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_sensitivity',
     description:
@@ -381,7 +381,7 @@ export function registerTools(ctx) {
     timeoutMs: 3_600_000,
   })))
 
-  // gem_ledger：prediction ledger 预测账本（阶段A-M3：gem_essentiality/gem_phenotype 自动登记的预测可查询/更新/追踪）
+  // gem_ledger：prediction ledger 预测账本（gem_essentiality/gem_phenotype 自动登记的预测可查询/更新/追踪）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_ledger',
     description:
@@ -412,7 +412,7 @@ export function registerTools(ctx) {
     timeoutMs: 60_000,
   })))
 
-  // gem_benchmark：通用基准对比（阶段B-B1：任何两个 GEM 的规范对比表，六关并列+生长+biomass 探针+必需性+表型+账本回填）
+  // gem_benchmark：通用基准对比（任何两个 GEM 的规范对比表，六关并列+生长+biomass 探针+必需性+表型+账本回填）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_benchmark',
     description:
@@ -440,7 +440,7 @@ export function registerTools(ctx) {
     timeoutMs: 1_200_000,
   })))
 
-  // gem_secretion：可分泌代谢物谱（阶段C-C1：production envelope 扫描，纯拓扑边界声明内置）
+  // gem_secretion：可分泌代谢物谱（production envelope 扫描，纯拓扑边界声明内置）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_secretion',
     description:
@@ -467,7 +467,7 @@ export function registerTools(ctx) {
     timeoutMs: 900_000,
   })))
 
-  // gem_double_knockout：双敲 v1 合成致死（阶段C-C2：GPR 穷尽先验 + FVA 预筛全扫，假设声明内置）
+  // gem_double_knockout：双敲 v1 合成致死（GPR 穷尽先验 + FVA 预筛全扫，假设声明内置）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_double_knockout',
     description:
@@ -491,7 +491,7 @@ export function registerTools(ctx) {
     timeoutMs: 1_200_000,
   })))
 
-  // gem_enrichment：必需基因通路富集（阶段C-C3：超几何+BH FDR；通路源=SBML groups[MetaCyc PWY]）
+  // gem_enrichment：必需基因通路富集（超几何+BH FDR；通路源=SBML groups[MetaCyc PWY]）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_enrichment',
     description:
@@ -512,7 +512,7 @@ export function registerTools(ctx) {
     timeoutMs: 300_000,
   })))
 
-  // gem_targets：靶点清单规范导出（阶段C-C4：账本三类预测 -> 锁定 schema，供下游引物/编辑工具直接输入）
+  // gem_targets：靶点清单规范导出（账本三类预测 -> 锁定 schema，供下游引物/编辑工具直接输入）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_targets',
     description: