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

package/README.md

@@ -17,7 +17,7 @@ Genome-scale metabolic model builder for dsh: genome in, validated SBML out.
 | Python | 3.10+，且装 **`cobra`** | 分析/验证/补洞/账本/基准/导出 —— 除 `gem_build` 外的 22 个工具 |
 | `pyrodigal` | 装在同一个 Python 环境（可选但建议） | 裸基因组自动注释兜底（`gem_annotate` / fna 输入） |
 | **CarveMe** | 独立 venv `~/.dsh/dsh-bio-gem/venv-carveme`，含 `carve.exe` + **`diamond.exe`** | `gem_build`（carveme 引擎） |
-| WSL2 + gapseq | 可选，按本机拓扑（见第 4 节） | `gem_build`（gapseq 引擎） |
+| WSL2 + gapseq | 可选，按 WSL2 环境拓扑（见第 4 节） | `gem_build`（gapseq 引擎） |
 
 > **Python 环境从哪来（v0.1.4 起）**：解释器探测顺序为
 > `GEM_PYTHON` → **宿主 `dsh-bio-genie` 的自举环境** → `CONDA_PREFIX` → `PATH` 中的 `python`，
@@ -38,7 +38,7 @@ npx -y @deepseek-ai/dsh plugin --profile web add @dsh-bio/dsh-bio-gem
 # 方式二：从 GitHub 安装（拉源码；本插件纯 ESM 无构建步骤，可直接加载）
 npx -y @deepseek-ai/dsh plugin --profile web add github:moonbowterfly/dsh-bio-gem
 
-# 方式三：从本地目录安装（开发调试）
+# 方式三：从本地目录安装（本地源码）
 npx -y @deepseek-ai/dsh plugin --profile web add ./dsh-bio-gem
 ```
 
@@ -53,10 +53,10 @@ npx -y @deepseek-ai/dsh plugin --profile web add ./dsh-bio-gem
 
 3. 重新打开桌面端生效（也可直接在桌面端内 **「插件」页**输入包名安装，无需退出应用）。
 
-- 本机若已全局安装 dsh CLI，把 `npx -y @deepseek-ai/dsh` 换成 `dsh` 即可。
+- 若已全局安装 dsh CLI，把 `npx -y @deepseek-ai/dsh` 换成 `dsh` 即可。
 - `--profile <name>` 是**必填选项**（不传报 `required option '--profile <name>' not specified`）；Web 端固定用 `web`，桌面端固定用 `desktop`。
 - 安装完**重启对应的 dsh**（web：重新双击启动入口；桌面端：重开应用）。
-- **引擎兼容**：0.1.x 侧经 dsh 0.1.5-rc.2 走廊逐卡走查与实机验证；**0.2.0+（含官方桌面端）已于 2026-10-01 实测**（工具全量注册 + `gem_media_resolve` 真实执行）。
+- **引擎兼容**：0.1.x 侧经 dsh 0.1.5-rc.2 完整兼容核验与实机验证；**0.2.0+（含官方桌面端）已于 2026-10-01 实测**（工具全量注册 + `gem_media_resolve` 真实执行）。
 - 版本刚发布时可能短时间拉不到：registry 首次分发有几分钟延迟，`pnpm` 还可能缓存住 404。遇到 `ERR_PNPM_FETCH_404 ... is not in the npm registry` 时等几分钟重试，或在命令末尾追加 `--registry https://registry.npmjs.org/` 绕过缓存。
 
 验证插件层已生效（不用启动服务）：
@@ -121,13 +121,15 @@ unzip -o diamond.zip diamond.exe -d "$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts
 
 ### 4.（可选）gapseq 引擎（WSL2）
 
-`gem_build` 的 `engine=gapseq` 走 WSL2 桥（`gem_gapseq` 原子四步：setup / launch / status / fetch），质量档耗时 30-60 分钟/模型，非必需——默认的 `engine=carveme` 已能出可验证模型。桥按本机拓扑实现（WSL2 + `/opt/miniforge3` conda 环境 `gapseq` + 本地序列库），换机器需改 `python/gapseq_wsl.py` 顶部常量，故目前**视为实验性可选能力**。没有 WSL2 不影响其余 22 个工具与 carveme 构建。
+`gem_build` 的 `engine=gapseq` 走 WSL2 桥（`gem_gapseq` 原子四步：setup / launch / status / fetch），质量档耗时 30-60 分钟/模型，非必需——默认的 `engine=carveme` 已能出可验证模型。桥按 WSL2 + conda 环境拓扑实现（默认路径见 `python/gapseq_wsl.py` 顶部常量，换机器需相应调整），故目前**视为实验性可选能力**。没有 WSL2 不影响其余 22 个工具与 carveme 构建。
+
+能力探针只读检查 `doall` 使用的环境内 `seq/Bacteria` 元数据和 `rev/rxn/unrev` 文件，不请求 Zenodo。检查路径与当前固定的 conda 环境路径一致。
 
 ### 5. 自检（仓库源码目录内）
 
 ```sh
 # 冒烟：不依赖 dsh，直测 Python 层 + 工具注册表
-# 断言锚定本机 C58 夹具路径（见 test/smoke.js 顶部常量），换机器先改路径
+# 资产（C58 模型等）不在仓库内：用 --assets-root 或 DSH_BIO_GEM_ASSETS 指定；缺资产时相关检查 SKIP
 GEM_PYTHON=<你的-cobra-python> node test/smoke.js --skip-build   # 跳过 ~70s 的 build 单测
 GEM_PYTHON=<你的-cobra-python> node test/smoke.js                # 含 build 单测
 # 托管领域扩展的只读 integration 协议（无需 dsh 实例）
@@ -196,7 +198,7 @@ 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.
 
-## 工具（20）
+## 工具（23）
 
 | 工具 | 作用 | 状态 |
 |---|---|---|
@@ -210,7 +212,7 @@ CarveMe + diamond are required only by `gem_build`; the other 20 tools need noth
 | `gem_essentiality` | 全量必需基因扫描（FVA 预筛 + 手工敲除）| ✅ C58: 必需 155 |
 | `gem_annotate` | 基因组→蛋白（官方优先 + pyrodigal 兜底，纯 Windows）| ✅ pyrodigal 5330 |
 | `gem_build` | CarveMe/gapseq 双引擎构建（fna/faa；后台 job + 进度；M9 或目标介质验证闭环）| ✅ carveme 70s / fna 全链 63.5s / gapseq 实测中 |
-| `gem_gapseq` | gapseq 原子四步（WSL 可选：setup/launch/status/fetch）| ✅ 本机全通 |
+| `gem_gapseq` | gapseq 原子四步（WSL 可选：setup/launch/status/fetch）| ✅ 实测全通 |
 | `gem_media_resolve` | 跨引擎介质解析 RPC（自然名→EX ID；消费侧统一入口）| ✅ AB→20 EX |
 | `gem_fluxscan` | 通量区间制（FVA 区间+pFBA 点值；条件对比区间分离判定，overlap=伪影禁止引用）| ✅ C58 AB 0.519981 / 蔗糖 supplement 0.97077 |
 | `gem_sensitivity` | 结构性灵敏度（GAM×biomass 22 组合全量+稳定性三分类+单组分漂移+模型卡鲁棒性 v3）| ✅ C58 基准复现 155 |
@@ -224,7 +226,7 @@ CarveMe + diamond are required only by `gem_build`; the other 20 tools need noth
 | `gem_quality` | 模型质量报告（gem-qi-v1：blocked/环路(fastcc 方向锥)/元素平衡/孤儿与死端/覆盖/连通性 + 启发式聚合分；分项与 failed_checks 为准）| ✅ C58+AB: qi 67.23 / blocked 1032 / cyclic 289 |
 | `gem_sample` | 通量空间采样（ACHR 默认 / OptGP 大样本；growth_floor_fraction 受限空间；全空间 vs 受限边界声明）| ✅ C58+AB: 全空间 median 0.019 / floor-0.9 min 0.468 |
 
-架构/决策见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)、[docs/DECISIONS-2026-08-29.md](docs/DECISIONS-2026-08-29.md)。
+架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
 
 ## 开发速查
 

package/docs/ARCHITECTURE.md

@@ -1,47 +1,47 @@
-# dsh-bio-gem — 架构文档（M1 定稿 2026-08-29）
+# dsh-bio-gem — 架构文档（2026-08-29 起）
 
 ## 1. 定位一句话
 
 dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质粒/多染色体），自动构建→验证→补洞→出报告（标准 SBML + 模型卡），产出后可被 dsh-bio-genie 现有消费工具（FBA/必需性/生产包络线/模型面板）直接加载使用。
 
-硬性原则（沿袭 bio-genie）：**用户零手动安装、零自愈、通用化（不可本机特化）、结论可溯源**。
+硬性原则（沿袭 bio-genie）：**用户零手动安装、零自愈、通用化（不针对特定机器特化）、结论可溯源**。
 
 ## 2. 决策记录（为什么这么设计）
 
 | 日期 | 决策 | 依据 |
 |---|---|---|
-| 08-28 | 插件名 dsh-bio-gem；资产盘点：消费侧已就绪、补构建侧闭环 | 用户拍板 |
-| 08-29 | 引擎路线：**任务门槛路由**（不是简单 auto）；落地节奏 **M1 CarveMe+补洞 → M2 gapseq WSL 桥 → M3 双引擎交叉** | 第三方 GLM 独立评估 + 本机实测（CarveMe AB 不生长=补洞是生存线；WSL 桥显著降级交付风险；Docker 非 WSL 替代）|
+| 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 | 修正 GLM 建议：弃 μ 判据用 FBA 通量判据；pyrodigal 注释前端降 backlog；测试矩阵首版收敛 C58+2 公开株 | 本机输出口径为 objective_value；默认输入是带注释基因组 |
+| 08-29 | 修正建议：弃 μ 判据用 FBA 通量判据；pyrodigal 注释前端降 backlog；测试矩阵首版收敛 C58+2 公开株 | 输出口径为 objective_value；默认输入是带注释基因组 |
 
-**裁决原则**：GLM 分析质量高但缺本机上下文（输出单位、输入形态、部署面=本机为主的现实），凡冲突处以本机实测与产品原则为准。
+**采纳原则**：外部分析缺实际环境上下文时，凡冲突处以实测与产品原则为准。
 
 ## 3. 工具契约（21 工具 ↔ Python 层；21 op + build CLI）
 
-| 工具 | Python 层 | 阶段 |
+| 工具 | Python 层 | 状态 |
 |---|---|---|
-| gem_build | build.py CLI（CarveMe M9 gapfill；fna 自动注释）| ✅ M1+模块 DONE（C58 63-70s）|
-| gem_validate | op validate（G1-G6 + GATE_REGISTRY）| ✅ M1 DONE |
-| gem_gapfind | op gapfind（L1-L3 分级 + 跨引擎介质归一化）| ✅ M1 DONE |
-| gem_gapfill | op gapfill（L1/L2 规则 + provenance）| ✅ M1 DONE |
-| gem_phenotype | op phenotype_fix（表型回填迭代）| ✅ A3 DONE |
+| gem_build | build.py CLI（CarveMe M9 gapfill；fna 自动注释）| ✅ 已完成（C58 63-70s）|
+| gem_validate | op validate（G1-G6 + GATE_REGISTRY）| ✅ 已完成 |
+| 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_gapseq | op gapseq（WSL 原子四步，可选项）| ✅ 桥全通 |
-| gem_l3_fix | op l3_fix（L3 补洞：L3a 连通性 + L3b 白名单/BiGG；证据分级 + 预算闸门 + G6 回滚）| ✅ B' DONE（C58 Arabinose 0→0.851）|
+| gem_l3_fix | op l3_fix（L3 补洞：L3a 连通性 + L3b 白名单/BiGG；证据分级 + 预算闸门 + G6 回滚）| ✅ 已完成（C58 Arabinose 0→0.851）|
 | gem_report | op model_info（+ ledger_summary 基率摘要）| ✅ DONE |
 | gem_media_resolve | op media_resolve（介质解析 RPC，消费侧统一入口）| ✅ DONE |
-| gem_biomass | op biomass_inspect / biomass_apply（inspect 组分+对照参考；apply 覆盖表+三联对照+原文件不动回滚）| ✅ Q2 DONE（复位 delta 0.0）|
-| gem_fluxscan | op fluxscan（通量区间制：FVA 区间+pFBA 点值+条件对区间分离判定，overlap=伪影禁止引用）| ✅ 阶段A-M1 DONE（C58 AB 0.519981 / 蔗糖 supplement 0.97077）|
-| gem_sensitivity | op sensitivity（GAM×biomass 22 组合全量+稳定性三分类+单组分漂移；模型卡 robustness v3）| ✅ 阶段A-M2 DONE（基准复现 155）|
-| gem_ledger | op ledger（prediction ledger：list/query/update；幂等追加式账本）| ✅ 阶段A-M3 DONE（C58 155+19 条幂等复跑）|
-| gem_benchmark | op benchmark（通用基准对比：六关并列/生长[介质层两级策略]/biomass 探针/必需性对比含退化护栏/表型/账本回填/md 落盘；model 参数支持 bigg:<id> 下载）| ✅ 阶段B-B1/B2/B3 DONE |
-| gem_secretion | op secretion（可分泌谱：production envelope；边界声明内置；wt<=EPS 退化护栏不登记）| ✅ 阶段C-C1 DONE（C58 85 可分泌）|
-| gem_double_knockout | op double_knockout（双敲 v1：GPR 穷尽先验+全扫 max_pairs 预算；假设声明内置）| ✅ 阶段C-C2 DONE（Atu3364↔Atu4682 对应命中）|
-| gem_enrichment | op enrichment（必需基因通路富集：超几何+BH FDR；无注释 annotation_unavailable 兜底）| ✅ 阶段C-C3 DONE（C58 55 条 FDR 显著）|
-| gem_targets | op targets（靶点规范导出：11 字段锁定 schema；账本计数闭合；引物设计不做）| ✅ 阶段C-C4 DONE（258 行三类闭合）|
-| gem_precursor_scan | op precursor_scan（阻塞前体分析：基线通量→可生长即返「无阻塞」；不生长则逐前体移除测试定位阻塞点）| ✅ 2026-09-11（E2E 绕道归因产出）|
+| gem_biomass | op biomass_inspect / biomass_apply（inspect 组分+对照参考；apply 覆盖表+三联对照+原文件不动回滚）| ✅ 已完成（复位 delta 0.0）|
+| gem_fluxscan | op fluxscan（通量区间制：FVA 区间+pFBA 点值+条件对区间分离判定，overlap=伪影禁止引用）| ✅ 已完成（C58 AB 0.519981 / 蔗糖 supplement 0.97077）|
+| gem_sensitivity | op sensitivity（GAM×biomass 22 组合全量+稳定性三分类+单组分漂移；模型卡 robustness v3）| ✅ 已完成（基准复现 155）|
+| gem_ledger | op ledger（prediction ledger：list/query/update；幂等追加式账本）| ✅ 已完成（C58 155+19 条幂等复跑）|
+| gem_benchmark | op benchmark（通用基准对比：六关并列/生长[介质层两级策略]/biomass 探针/必需性对比含退化护栏/表型/账本回填/md 落盘；model 参数支持 bigg:&lt;id&gt; 下载）| ✅ 已完成 |
+| gem_secretion | op secretion（可分泌谱：production envelope；边界声明内置；wt<=EPS 退化护栏不登记）| ✅ 已完成（C58 85 可分泌）|
+| 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（实测归因产出）|
 
 > 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 拉起）。
 >
@@ -49,15 +49,15 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 
 > **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）。**生长/通量数值口径（阶段A-M4）**：所有产出生长/通量数值的工具输出均带 `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: mmol/gDW/h` 与单点 FBA 声明；条件间通量对比一律走 gem_fluxscan 区间分离判定（overlap=伪影禁止引用）。
 
 ## 4. 引擎路线（M1→M2→M3）
 
 - **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 代码完成，doall 实测进行中）**：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 每步落盘 → 断点续跑）待做。
+- **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 粒度不同）。
 
-## 5. 验证关卡规格（HANDOFF-03 产品化 + G0）
+## 5. 验证关卡规格（产品化 + G0）
 
 | 关卡 | 内容 | 首版 | 判定线 |
 |---|---|---|---|
@@ -69,7 +69,7 @@ dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质
 | G5 | 必需基因抽检（≤30 基因）| 条件 | 有参照集才跑；映射覆盖 <80% 时 SKIP(WARN) |
 | G6 | ATP 泄漏检测（全关交换后 ATP demand 应≈0）| ✅ | leak ≤0.01 判 PASS；ATP 解析走 id→name→formula 三级回退（跨 ID 体系）|
 
-**G0 的由来（2026-09-10 E2E 实测）**：MetaCyc 风格 id 的公开模型（iNX1344_v3）上，
+**G0 的由来（2026-09-10 实测）**：MetaCyc 风格 id 的公开模型（iNX1344_v3）上，
 `gem_gapfind` 报 5 个 L3「内部通路缺口」，实为 biomass 前体未映射所致——agent 为逐个
 证伪手写 cobra 代码 18 次。现 `gem_validate` 在 G1 之前输出 `g0`，`gem_gapfind` 返回
 `coherence_warning` + `interpretation_guard`，把该结论前置给 agent。
@@ -126,7 +126,7 @@ job 化 + 进度事件（粒度 ≤5s）+ 分步 checkpoint（每步落盘，可
 
 零手动干预下：**基因组进 → 四个消费工具（FBA/必需性/包络线/面板）不经修改即可用的 SBML 出**，且模型在声明培养基上生长为正；C58 端到端演示通过（build→面板可见→FBA 可跑→必需性可跑）；模型卡齐全（引擎/版本/补洞记录/验证结果，同输入重跑一致）；5-6 Mb 基因组 p95 ≤ 20 min。
 
-## 附录 A：性能基准（阶段 A-M6，2026-08-30 本机实测，独占运行）
+## 附录 A：性能基准（2026-08-30 实测，独占运行）
 
 分析 Python 3.13.13 / cobra 0.32.1 / GLPK；C58=gapseq 2485 反应/1084 基因；iNX1344_v4=1441 反应/1344 基因。
 
@@ -142,4 +142,4 @@ job 化 + 进度事件（粒度 ≤5s）+ 分步 checkpoint（每步落盘，可
 | 单组分 ±25% 灵敏度 | 75 组分×2=150 次 FBA，54.4s | 47 组分×2=94 次 FBA，7.9s |
 | 必需性漂移 top10（含生长探针） | 522.0s（含 7 刚性对跳过探针） | 33.8s（20/20 全部"不生长跳过"） |
 
-> 注：FVA 占单条件耗时 ~75%；sensitivity 线性于组合数（每组合 fresh 读模+FVA+敲除循环）。GLPK 对个别扰动 LP 有病态停摆前科，sensitivity 内置 LP_TIMEOUT_S=30 护栏（见 docs/DECISIONS-阶段A.md M2-5）。
+> 注：FVA 占单条件耗时 ~75%；sensitivity 线性于组合数（每组合 fresh 读模+FVA+敲除循环）。GLPK 对个别扰动 LP 有病态停摆前科，sensitivity 内置 LP_TIMEOUT_S=30 护栏。

package/docs/releases/v0.1.12.md

@@ -17,7 +17,7 @@
 - `test/smoke.js` 重构：模型资产**多候选解析**（`--assets-root` / `DSH_BIO_GEM_ASSETS` / 新旧位置）——资产迁移后不再硬编码路径崩溃；**缺资产 / 缺账本标记 SKIP 而非失败**（`--require-assets` 供 CI 严格模式）；CarveMe 跳过判断移至调用前；子进程非零退出 fail-closed。
 - `npm test` 接线：smoke + integration + optional-injection（真注册验证，此前未纳入任何 npm 入口）。
 
-**引擎兼容（2026-09-19）**：经 dsh **0.1.5-rc.2** 走廊逐卡走查（55 张变更卡：零适配命中）与实机验证（工具注册 / 代谢建模面板 / 账本与模型数据）。
+**引擎兼容（2026-09-19）**：经 dsh **0.1.5-rc.2** 完整兼容核验（全量变更：零适配命中）与实机验证（工具注册 / 代谢建模面板 / 账本与模型数据）。
 
 ## 安装
 
@@ -38,6 +38,6 @@ dsh plugin --profile web add @dsh-bio/dsh-bio-gem
 
 ## 已知边界（诚实清单）
 
-- `gem_build` 的 gapseq 引擎为实验性（WSL2 本机拓扑绑定，30–60 分钟/模型）；默认 carveme 引擎已可出可验证模型。
+- `gem_build` 的 gapseq 引擎为实验性（WSL2 拓扑绑定，30–60 分钟/模型）；默认 carveme 引擎已可出可验证模型。
 - CarveMe 运行时需手动准备一次（README 第 3 节）——「装完插件」不等于「构建可用」，分析/验证类能力不受影响。
 - 注释依赖 SBML groups（gapseq 系模型自带）；无注释模型按契约返回 `annotation_unavailable` 兜底，不伪造通路。

package/docs/releases/v0.1.16.md

@@ -0,0 +1,31 @@
+# @dsh-bio/dsh-bio-gem v0.1.16
+
+> **主题**：导出与工作区修复批次 + 公开文档整理。
+> 基因组尺度代谢模型（GEM）构建插件：基因组输入 → 构建 → 验证 → 补洞 → 出报告（标准 SBML + 模型卡）。
+
+## 修复与改进
+
+**导出产物规范化**
+- CSV 导出保持**纯数据表**（标准表头 + 行）；声明/参数/免责信息移入旁车文件 `<path>.meta.json`（返回体附 `export_csv_meta` 路径）——标准解析器（pandas 等）可直接读取。
+- 导出路径父目录不存在时**自动创建**（mkdir -p 语义），不再报 FileNotFoundError。
+
+**工作区与运行环境**
+- 工具相对路径基于会话工作区解析（python 子进程 cwd 对齐会话目录）。
+- gapseq 能力探针改为只读检查本地序列库元数据，不再依赖在线检查（离线环境不再误报）。
+
+**公开文档整理**
+- 清理内部流程信息；架构文档措辞规范化。
+
+## 安装
+
+```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/docs/releases/v0.1.17.md

@@ -0,0 +1,32 @@
+# @dsh-bio/dsh-bio-gem v0.1.17
+
+> **主题**：默认值通用化与公开信息审计修复。
+> 基因组尺度代谢模型（GEM）构建插件：基因组输入 → 构建 → 验证 → 补洞 → 出报告（标准 SBML + 模型卡）。
+
+## 修复与改进
+
+**默认值通用化（面向所有用户）**
+- 资源路径默认值不再绑定开发机目录：解释器/工具与参考资源改为**插件数据目录 + 环境变量**优先
+  （`GEM_GAPSEQ_DB` / `GEM_DIAMOND` / `GEM_WHITELIST_DB_DIR` / `GEM_UNIVERSAL_MODEL` / `GEM_INX_MODEL`），
+  缺失时给出可操作提示而非静默失败。
+- BiGG 模型下载的代理回退改为读取**环境变量代理**（`HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`），
+  不再固定本机端口；描述与实现一致。
+
+**测试与文档**
+- 回归脚本资产配置显式化：`--assets-root` 或 `DSH_BIO_GEM_ASSETS` 指定模型资产；缺资产时相关检查 SKIP（不误报为回归失败）。
+- 文档一致性：生长值单位口径说明（归一化 biomass 为 1/h；一般反应通量为 mmol/gDW/h）、工具计数、
+  架构文档状态与内部代号清理、基准报告路径通用化。
+
+## 安装
+
+```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.15",
+  "version": "0.1.17",
   "description": "基因组尺度代谢模型（GEM）构建插件：输入细菌全基因组（蛋白FASTA，支持多质粒/多染色体），自动构建+验证+补洞+出报告（SBML + 模型卡），供 dsh-bio-genie 消费工具加载使用 | Genome-scale metabolic model builder for dsh",
   "repository": {
     "type": "git",
@@ -52,7 +52,7 @@
   },
   "scripts": {
     "smoke": "node test/smoke.js",
-    "test": "node test/check-version-source.mjs && node test/smoke.js --skip-build && node test/integration.js && node test/capabilities.js && node --import ./test/register-dsh-tools.mjs test/optional-injection.js && node --import ./test/register-dsh-tools.mjs test/check-capabilities.mjs && node test/check-counts.mjs && node test/capabilities-warn-state.mjs",
+    "test": "node test/check-version-source.mjs && node test/smoke.js --skip-build && python -I test/test_gapseq_probe.py && python -I test/test_fsutil.py && node test/integration.js && node test/capabilities.js && node --import ./test/register-dsh-tools.mjs test/optional-injection.js && node --import ./test/register-dsh-tools.mjs test/check-capabilities.mjs && node test/check-counts.mjs && node test/capabilities-warn-state.mjs && node test/workdir.mjs",
     "test:full": "node test/smoke.js && node test/integration.js && node test/capabilities.js && node --import ./test/register-dsh-tools.mjs test/optional-injection.js && node --import ./test/register-dsh-tools.mjs test/check-capabilities.mjs && node test/check-counts.mjs"
   },
   "peerDependencies": {
@@ -63,4 +63,4 @@
       "optional": true
     }
   }
-}
+}

package/python/annotate.py

@@ -1,5 +1,5 @@
 # annotate.py — 路线 P0 注释步骤（纯 Windows）
-# 策略（GLM 二轮 Q1 采纳 + 验证协议）：官方注释优先 + pyrodigal 兜底
+# 策略（设计评审采纳 + 验证协议）：官方注释优先 + pyrodigal 兜底
 #   1) 同目录 *_protein.faa 存在（NCBI dataset 常见）→ 直接用
 #   2) 同目录 *.gff（含 CDS）→ 解析坐标从 fna 提取 + 翻译（transl_table 11）
 #   3) 仅 .fna → pyrodigal（多序列模式；总长 <100kb 时 meta 模式）

package/python/benchmark.py

@@ -125,7 +125,7 @@ def _essential_full_scan(model_path, medium, log, tag):
 
 def map_genes(genes, model_b):
     """基因映射尽力而为（与物种无关）：策略1 identity（同 id）；策略2 gene.name 匹配。
-    反应桥（EC/名字）需两侧注释充分；本机两命名空间注释层不足时不启用，如实报告。"""
+    反应桥（EC/名字）需两侧注释充分；两侧命名空间注释层不足时不启用，如实报告。"""
     b_by_id = {g.id for g in model_b.genes}
     b_by_name = {}
     for g in model_b.genes:
@@ -387,9 +387,10 @@ def write_md(path, out):
 def fetch_bigg_model(model_id, dest_dir=None):
     """从 BiGG 下载模型 SBML（B3 最小版）。
     URL 策略（实测 2026-08-30）：静态库 http://bigg.ucsd.edu/static/models/<id>.xml 返回标准 SBML；
-    任务书给的 /api/v2/universal/models/<id>/download 实为 404（universal 是 reactions 命名空间），
+    `/api/v2/universal/models/<id>/download` 实为 404（universal 是 reactions 命名空间），
     /api/v2/models/<id>/download 返回 200 但内容是 BiGG JSON（非 SBML）——两者均不采用。
-    直连失败走本机代理 127.0.0.1:27890；都失败抛错（调用方如实报告，不阻塞本地对比）。"""
+    直连失败时按环境变量代理（HTTP_PROXY/HTTPS_PROXY/ALL_PROXY）重试一次；
+    未配置环境代理或仍失败则抛错（调用方如实报告，不阻塞本地对比）。"""
     import urllib.request
     import shutil
     urls = [f"http://bigg.ucsd.edu/static/models/{model_id}.xml"]
@@ -398,10 +399,11 @@ def fetch_bigg_model(model_id, dest_dir=None):
     dest = os.path.join(dest_dir, f"bigg_{model_id}.xml")
     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}
+    fallbacks = [("direct", None)] + ([("env-proxy", env_proxies)] if env_proxies else [])
     last_err = None
     for url in urls:
-        for tag, proxies in (("direct", None), ("proxy", {"http": "http://127.0.0.1:27890",
-                                                         "https": "http://127.0.0.1:27890"})):
+        for tag, proxies in fallbacks:
             try:
                 t0 = time.time()
                 req = urllib.request.Request(url, headers={"User-Agent": "dsh-bio-gem benchmark/1.0"})
@@ -417,7 +419,7 @@ def fetch_bigg_model(model_id, dest_dir=None):
                 last_err = f"{type(e).__name__}: {str(e)[:200]}"
                 if os.path.exists(dest + ".tmp"):
                     os.remove(dest + ".tmp")
-    raise RuntimeError(f"bigg download failed（直连+代理均失败）: {last_err}")
+    raise RuntimeError(f"bigg download failed（直连与代理回退均失败）: {last_err}")
 
 
 def medium_adaptation_hints(model_path, medium, max_hints=5, progress=None):

package/python/biomass_tools.py

@@ -1,4 +1,4 @@
-# biomass_tools.py — biomass 精修工具链（Q2 任务一）
+# biomass_tools.py — biomass 精修工具链（inspect / apply）
 # inspect（只读）: biomass 组分表 + 类别分布（氨基酸/核酸/脂质/辅因子/金属/其他）+ 原子总量
 #                  + 可选参考对照（内置 iML1515 biomass；iNX1344_v4 按代谢物名同义尽力翻译，翻不了明示 unmapped）
 # apply（显式）: biomass_profile 覆盖表（op=set|add|remove）→ 副本替换 biomass → 强制 G1-G6 重验
@@ -16,8 +16,14 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import cobra
 
 EX_PREFIX = ("EX_", "DM_", "SK_")
-DEFAULT_UNIVERSAL = r"D:\Program\hermes\temp\gem_universal\iML1515.xml"
-DEFAULT_INX = r"F:\A_NGJ plan\Zcode\models\iNX1344_v4.xml"
+DEFAULT_UNIVERSAL = os.environ.get(
+    "GEM_UNIVERSAL_MODEL",
+    os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "models", "iML1515.xml"),
+)
+DEFAULT_INX = os.environ.get(
+    "GEM_INX_MODEL",
+    os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "models", "iNX1344_v4.xml"),
+)
 GROWTH_UNITS = "1/h"
 EPS = 1e-6
 

package/python/budget.py

@@ -1,4 +1,4 @@
-# budget.py — 防过补第五闸门（B' 后半新增，全局预算）
+# budget.py — 防过补第五闸门（全局预算）
 # 规格: PROMPT-L3 §2「单模型补洞历史累计新增反应数 ≤ max(5, 模型总反应数*5%)；
 #       超限返回 budget_exceeded + confirm_required，需显式 confirm_budget=true 才能继续」。
 # 计数口径: 反应 notes["source"] ∈ {gem-gapfill, gem-l3fix}（两代补洞的 provenance 约定）。

package/python/build_whitelist.py

@@ -1,12 +1,15 @@
-# build_whitelist.py — B' 白名单 B0/B1：gapseq rxn 库 -> 反应白名单（本地基准，license 守则：不分发）
+# build_whitelist.py — 反应白名单构建（B0/B1 两级）：gapseq rxn 库 → 反应白名单（本地基准，license 守则：不分发）
 # B0: 聚合 rxn/*.fasta（非空）→ rxn_proteins.fa + mapping（序列header -> 反应ID）
 # B1: diamond makedb + blastp 目标物种 faa → 命中反应集（EVIDENCE_sequence 候选池）
 import os
 import sys
 import time
 
-SEQDB = os.environ.get("GEM_GAPSEQ_DB", r"F:\Datasets\gapseq\db\Bacteria")
-DIAMOND = r"C:\Users\shuai\.dsh\dsh-bio-gem\venv-carveme\Scripts\diamond.exe"
+SEQDB = os.environ.get("GEM_GAPSEQ_DB", "")
+DIAMOND = os.environ.get(
+    "GEM_DIAMOND",
+    os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "venv-carveme", "Scripts", "diamond.exe"),
+)
 
 
 def build_rxn_fasta(out_fa, out_map=None, min_size=100):
@@ -115,7 +118,10 @@ def subprocess_run(cmd, timeout=3600):
 
 if __name__ == "__main__":
     import json
-    fa = sys.argv[1] if len(sys.argv) > 1 else r"D:\Program\hermes\temp\gem_whitelist\rxn_all.fa"
+    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/ 子目录）")
     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,7 +3,7 @@
 # 目的：在 G3/G4/G5 与 gapfind 之前，先判断**模型自身数据质量是否允许下结论**，
 # 避免把「未映射代谢物」这类数据问题，误报成「通路缺口 / 必需基因异常」。
 #
-# 实测来源（2026-09-10 E2E，iNX1344_v3 —— MetaCyc 风格 id 的公开模型）：
+# 实测来源（2026-09-10，iNX1344_v3 —— MetaCyc 风格 id 的公开模型）：
 #   - gem_gapfind 报 5 个 L3「内部通路缺口」，根因实为 biomass 前体未映射；
 #   - agent 为证伪这些假阳性，手写 cobra 代码 18 次（占该轮调用的一半）。
 #
@@ -16,7 +16,7 @@
 #  2. 「前体可达性（demand 逐前体 FBA）」——初版实现同样在 e_coli_core 上把
 #     atp_c / accoa_c / nad_c / nadph_c 误报为「既不能合成也不能摄取」。全开交换下
 #     的 demand 语义与胞内辅因子/能量货币的循环补给路径纠缠，判据未成熟。
-#     正确方法（agent 在 E2E 中手工探索过）待重新设计后引入。
+#     正确方法（agent 曾手工探索过）待重新设计后引入。
 #
 # 保留的判据都经过「问题模型报出真问题 + 标准模型零误报」双向验证：
 #   - id 体系识别（信息性，决定下游名称映射口径）

package/python/double_knockout.py

@@ -18,6 +18,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 from silentio import silent_read_sbml
 from essential_scan import setup_model_medium, scan_essentiality, EPS
+from fsutil import ensure_parent_dir, write_meta_sidecar
 
 ASSUMPTION_NOTE = "细菌双敲验证率无大规模实验数据支撑，本结果=假设生成，供实验设计参考非结论"
 
@@ -174,16 +175,35 @@ def double_knockout(model_path, medium=None, max_pairs=5000, export_csv=None,
 
 
 def _export_csv(path, results, out):
+    """纯数据 CSV（标准表头，机器可读）+ 旁车 meta。
+
+    2026-10-05 修：此前把 assumption_note 写成首行 `"# assumption", note` 双字段行——
+    pandas/自动解析会把它当表头或脏行（实测 agent 需专门跳过 '#' 行）。
+    现改为：CSV 保持纯表；说明与参数写入 <path>.meta.json（返回体 export_csv_meta）。
+    """
+    path = ensure_parent_dir(path)
     n = 0
     with open(path, "w", newline="", encoding="utf-8-sig") as f:
         w = csv.writer(f)
-        w.writerow(["# assumption", out["assumption_note"]])
         w.writerow(["gene_a", "gene_b", "single_a_growth", "single_b_growth",
                     "double_growth", "rationale", "source"])
         for r in results:
             w.writerow([r["pair"][0], r["pair"][1], r["single_a_growth"],
                         r["single_b_growth"], r["double_growth"], r["rationale"], r["source"]])
             n += 1
+    meta = write_meta_sidecar(path, {
+        "assumption_note": out.get("assumption_note"),
+        "model": out.get("model"),
+        "medium": out.get("medium"),
+        "medium_preset": out.get("medium_preset"),
+        "wt_growth": out.get("wt_growth"),
+        "units": out.get("units"),
+        "eps": out.get("eps"),
+        "max_pairs": out.get("max_pairs"),
+        "pairs_found": out.get("pairs_found"),
+    })
+    if meta:
+        out["export_csv_meta"] = meta
     return n
 
 

package/python/enrichment.py

@@ -13,6 +13,7 @@ from math import comb
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 from silentio import silent_read_sbml
+from fsutil import ensure_parent_dir
 
 NOTE_UNAVAILABLE = ("模型无 SBML groups（通路）注释。可补途径：①用 gapseq 重建（自带 MetaCyc pathway "
                     "groups）；②从 BiGG API 取模型 subsystem 后注入 groups；③按 ec-code 注释做粗分类。")
@@ -153,6 +154,7 @@ def enrichment(model_path, gene_list=None, pathway_source=None, ledger_path=None
         "timing_seconds": round(time.time() - t0, 1),
     }
     if export_csv:
+        export_csv = ensure_parent_dir(export_csv)
         with open(export_csv, "w", newline="", encoding="utf-8-sig") as f:
             w = csv.writer(f)
             w.writerow(["pathway", "genes_hit_count", "genes_hit", "background_hit",

package/python/essential_scan.py

@@ -63,7 +63,7 @@ def scan_essentiality(m, gene_subset=None, progress=None, return_candidates=Fals
     print(f"[scan] 候选基因（关联可通量反应）{len(cand_genes)}", file=sys.stderr)
     print(f"[scan]         预计免敲 {max(0, len(m.genes) - len(cand_genes))} 个（{max(0, len(m.genes)-len(cand_genes))/max(1,len(m.genes))*100:.0f}%）", file=sys.stderr)
 
-    # 2) 手工敲除循环（HANDOFF-03：不用 single_gene_deletion）
+    # 2) 手工敲除循环（不用 single_gene_deletion）
     t0 = time.time()
     essential = []
     for gid in sorted(cand_genes):
@@ -149,7 +149,7 @@ def essential_scan(model_path, medium=None, gene_subset=None, progress=None, led
     result.update({
         "medium_preset": preset,
         "medium_unresolved": unresolved,
-        "note": "必需判定=A 培养基下敲除生长<1e-6；evidence 分级按基因支撑反应是否含 EVIDENCE_math（Q2）",
+        "note": "必需判定=A 培养基下敲除生长<1e-6；evidence 分级按基因支撑反应是否含 EVIDENCE_math",
         # 阶段A-M4 口径声明（只增）：wt_growth 为单点 FBA 值
         "units": "1/h",
         "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定",

package/python/fluxscan.py

@@ -1,5 +1,5 @@
 # fluxscan.py — M1 通量区间制（阶段 A 可信度内核第一件）
-# 语义（bsp 锁稿，一字不改）：每反应输出 fva_min/fva_max/pfba；条件对比消费区间分离判定；
+# 语义（已锁定）：每反应输出 fva_min/fva_max/pfba；条件对比消费区间分离判定；
 #   overlap = 点值差异是求解器伪影，禁止引用。
 # 计算口径：每 condition 独立 silent_read_sbml 重读模型（勿深拷贝）；介质 setup 对齐 validate G3
 #   （expand_medium -> 全交换清零 EX_/DM_/SK_/boundary -> resolve_medium 设 bounds）；
@@ -21,6 +21,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from silentio import silent_read_sbml
 from gapfind import expand_medium, resolve_medium, build_ex_index, match_ex
 from validate import parse_formula
+from fsutil import ensure_parent_dir
 
 EX_PREFIX = ("EX_", "DM_", "SK_")
 DEFAULT_FRACTION = 0.9999
@@ -168,6 +169,7 @@ def _pair_result(a_name, b_name, data_a, data_b, scope, tol, only_diff):
 
 def _export_csv(path, model_reactions, pair_results):
     """全量 CSV：每行 = 条件对 × 反应（双侧区间/点值/判定）。返回 (rows, bytes)。"""
+    path = ensure_parent_dir(path)
     names = {r.id: r for r in model_reactions}
     rows = 0
     with open(path, "w", newline="", encoding="utf-8-sig") as f:
@@ -267,15 +269,15 @@ if __name__ == "__main__":
     # 双协议（历史坑：stdin 与 argv-file 两派并存，新脚本必须都支持）
     if "--selftest" in sys.argv:
         cases = [
-            # (la, ua, lb, ub, tol, direction, hard)  —— 任务书 5 组判定样例
+            # (la, ua, lb, ub, tol, direction, hard)  —— 5 组判定样例
             (1.0, 2.0, 5.0, 6.0, 1e-6, "b_higher", True),      # ① 分离：b 高
             (5.0, 6.0, 1.0, 2.0, 1e-6, "a_higher", True),      # ① 分离：a 高
             (1.0, 3.0, 2.0, 4.0, 1e-6, None, False),           # ② 重叠（伪影）
             (1.0, 3.0, 3.0, 5.0, 1e-6, None, False),           # ② 接触容差内仍 overlap（边界）
             (-5.0, -2.0, 0.0, 0.0, 1e-6, "b_higher", True),    # ③ 零通量/负向
             (-5.0, -2.0, 0.0, 0.0, 0.0, "b_higher", True),     # ④ 精确边界（tol=0）
-            # ⑤ 容差：锁定公式下 gap=5e-7 < tol=1e-6 -> overlap（任务书该行样例期望"分离"，
-            #    与锁定公式 ua+tol<lb 矛盾：5e-7 不大于 1e-6。按公式实现，差异上报 bsp 裁决）
+            # ⑤ 容差：锁定公式下 gap=5e-7 < tol=1e-6 -> overlap（该样例期望"分离"，
+            #    与锁定公式 ua+tol<lb 矛盾：5e-7 不大于 1e-6。按公式实现）
             (1.0, 1.0000005, 1.000001, 2.0, 1e-6, None, False),
             # 同数字、tol(1e-7)<gap(5e-7) -> 分离：证明容差机制本身生效
             (1.0, 1.0000005, 1.000001, 2.0, 1e-7, "b_higher", True),

package/python/fsutil.py

@@ -0,0 +1,44 @@
+"""fsutil.py — 文件系统小工具（导出路径处理，2026-10-05 增补）。
+
+背景（round1 TC4 观察 GEM-2，round2 复核）：export_csv/export_path 传相对路径
+且父目录不存在时，直接 FileNotFoundError ——对用户是零价值的报错（需手动 mkdir）。
+统一改为自动创建父目录（mkdir -p 语义），返回绝对路径。
+- 部分导出曾把声明文本写成 CSV 首行 `"# xxx", note` 双字段行——标准 CSV 解析器
+  （pandas 默认）会把它当表头或脏行（实测 agent 需专门跳过 '#' 行）。
+  统一改为：CSV 保持纯数据表，声明与参数写入旁车文件 <path>.meta.json。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+
+def ensure_parent_dir(path: str) -> str:
+    """确保导出路径的父目录存在，返回绝对路径。
+
+    空 dirname（纯文件名 → 当前目录）时只返回绝对路径；
+    目录已存在时为幂等 no-op。
+    """
+    abspath = os.path.abspath(path)
+    parent = os.path.dirname(abspath)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    return abspath
+
+
+def write_meta_sidecar(path: str, payload: dict) -> str | None:
+    """在导出文件旁写 <path>.meta.json（声明/参数/时间戳）。失败仅告警返回 None。
+
+    调用方约定：CSV 本体只放纯数据；任何注释性说明（assumption/boundary 等）
+    放进 payload，由本函数落盘。
+    """
+    meta_path = path + ".meta.json"
+    try:
+        data = dict(payload)
+        data.setdefault("generated_at", time.strftime("%Y-%m-%dT%H:%M:%S%z"))
+        with open(meta_path, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False, indent=1)
+        return meta_path
+    except Exception:
+        return None