bio-tools —— 给 AI Agent 用的生物信息工作站

一个 Windows 上的生信工作目录怎么管的完整答案：唯一事实源 + 一个自检器 + 一套工具封装规范。 工具本体不在本仓（第三方软件，各自有许可与安装包）；本仓给的是壳——目录约定、调用通道、成功判据、文档规范，以及一个能把它们全部对着磁盘验一遍的 bio-doctor。

这个仓库解决什么问题

让 AI（或任何自动化会话）在你的机器上跑生信工具时，最常见的三种翻车不是"工具不会用"，而是：

现象	真实案例（本站实测）
退出码说谎	meme 没装 Ghostscript，只输出 EPS、图片没生成，退出码仍是 0；hmmsearch 参数写错只打一行 Incorrect number of command line arguments，退出码也是 0
旧文件冒充新结果	meme -oc 并不清空输出目录，上一轮的 logo2/3.eps 会残留下来混进本轮结果，看上去"跑成功了"
文档与事实分家	文档写"A 选项"，实际版本没有；文档写"已装 X"，其实没装。AI 照着文档跑，报错后开始瞎猜

本仓的做法是三条硬机制，而不是三条建议：

1. 唯一事实源 registry.json：有哪些工具、入口在哪、什么版本、文档在哪、哪些路由、当前有哪些坑——清单类事实只写这一处。README 只写规则，所以不会过期。
2. 行为契约 + 反向探针：每个工具都要声明"什么算成功"（success：期望退出码 / 必须出现的产物 / 已知失败字样），并且每条判据都必须配一条"故意造失败"的探针证明它真的会喊。判据误报比判据缺失更贵——误报会让 Agent 学会忽略判据。
3. bio-doctor 自检器：把上面两条对着磁盘逐条校验（根目录 / 残留物 / 入口存在 / 文档形状 / 文档链接 / 文档哈希 / 字段完整性 / 判据可用性 / 已知坑回归），退出码 = 错误条数。它还带 -SelfTest——往沙盒里注入故障，证明校验器自己没坏。

设计动机与完整规格见 tools/管理设计.md。

快速开始

:: 1) 克隆。脚本内部所有路径以仓库根为基准，推荐直接克隆到 D:\bio
git clone https://github.com/Paraso42/bio-tools.git D:\bio

:: 2) 若克隆到了别处，跑一次安装脚本把事实源里的根路径改写过来（幂等）
pwsh -NoProfile -ExecutionPolicy Bypass -File D:\bio\install.ps1

:: 3) 跑自检。第一次跑必然报一串错误 —— 那是你的"待安装清单"，不是仓库坏了
D:\bio\tools\bio-doctor.bat

关于第 3 步：本仓只带壳不带工具，所以 bio-doctor 会逐条告诉你"注册了但磁盘上没有"。装一个、消一条，直到 通过 N 警告 0 错误 0。不想用的工具，用 bio-reg 把条目删掉即可（见下）。

仓内自带两个可直接跑通的演示任务（projects/dock-demo、projects/tbtools-demo）和一份公共示例数据（data/examples/），所有《使用说明.md》里的示例都引用它们。

只记这几条命令

命令	用途
tools\bio-doctor.bat	全站自检。退出码 = 错误条数（-Json 给程序读、-SelfTest 检验校验器自身、-Gate 提交把关、-Probe 汇总探针）
tools\bio-run.bat <工具id> [工具参数...]	跑工具并判定到底成没成功：退出码 0 但其实失败会归一化成 3（判据见 registry.json 的 tools[].success）
tools\bio-reg.bat <子命令>	改 registry.json 的唯一通道（备份 + 验 JSON + 保格式 + 冻结文档哈希），子命令见其《使用说明.md》
tools\bio-new-task.bat <任务名> ["标题"]	生成标准任务骨架
各工具入口	见 registry.json 的 tools[]；"要干某件事该用哪个"见 routing[]

bio-run 的退出码约定：0 = 成功，1 = 失败，2 = 用法错，3 = 可疑（跑完了但不像成功）。

架构：三层，各管一件事

层	文件	放什么	谁保证它不过期
事实层	registry.json	工具清单/入口/版本/文档位置/路由表/已知坑/任务清单	bio-doctor 对着磁盘逐条校验
规则层	本文件	目录约定、工作流、铁律、维护契约	不含会变的事实，故不会过期
细则层	tools\*\使用说明.md、projects\<task>\README.md	某个工具/某个任务具体怎么用	bio-doctor 检查文档链接与漂移

铁则：清单类内容（有哪些工具、什么版本、有哪些文件）只准写在 registry.json。在 README 或使用说明里复述清单 = 制造第二份必然会过期的"真相"。

目录结构（白名单）

<根>\
├── README.md          规则（本文件）
├── registry.json      唯一事实源
├── install.ps1        安装/改根路径/环境自检
├── tools\             工具封装（.bat/.ps1 入口）+ 各工具《使用说明.md》
├── projects\          任务，每个任务一套标准骨架
├── data\examples\     所有文档示例共用的公共数据与产物
├── downloads\         安装包备份（清单入库，包不入库）
├── conda\ R\ python\  第三方运行时（可重建，勿手工改；只把《使用说明.md》入库）
└── tools\support\envs\  WSL/conda 环境的可复现规格（*.yml）

根目录只允许出现白名单里的少数几个文件（见 registry.json 的 root_whitelist），其余一律归位，bio-doctor 会报 ERR。

标准工作流（四步，别跳）

1. 接活 → 查 registry.json 的 routing[] / decisions[] 定位工具 → 读该工具的《使用说明.md》
2. 开工 → bio-new-task <名> 建骨架（data/scripts/results/reports/figures/logs/tmp 固定不变）
3. 干活 → 守下面的调用铁律；一次性探索脚本丢 scripts\dev-archive\
4. 收工 → 更新 registry.json（任务状态、新工具、新坑）→ 跑 bio-doctor，错误不归零不算完工

调用铁律（跨工具通用）

1. 绝对路径调用（自动化会话是否继承用户 PATH / R_LIBS_USER 取决于宿主，别赌）；R 一律显式注入 R_LIBS_USER
2. 同时捕获 stdout 与 stderr；退出码非 0 即失败，先读 stderr 再改参数
3. 文本一律 UTF-8；命令行参数避免中文与空格
4. WSL 相关工具一律经 tools\wsl-run.bat（D:\x → /mnt/d/x）
5. GUI 工具（chimerax/pymol/ugene/phylosuite/tbtools）会弹窗驻留 → 自动化优先 CLI 通道
6. 长命令写成 .bat/.py/.R 脚本执行，不要拼一行
7. 数据落 projects\<task>\data\，结果落 projects\<task>\，日志与产物同目录
8. 退出码不可信时（hmmsearch／meme／mast／fastqc／TBtools 系）一律经 tools\bio-run.bat 调用；直接调用时不得用退出码判定成功，必须查声明产物是否存在

维护契约（这是机制，不是建议）

• 事实只写 registry.json。改了工具或参数 → 同批次改《使用说明.md》→ 更新该登记项的 verified 日期；否则 bio-doctor 报文档漂移
• 遇到坑 → 写进 known_issues（带上自动复检方式）；修好后把 status 改 closed，doctor 会复检并在复发时报"回归"
• 新增工具 → 先登记再使用；没登记的入口会被 doctor 报"未登记"
• 写《使用说明.md》 → 一律按 tools\管理设计.md 的六段式（是什么／调用通道／命令格式／示例／输出／注意），示例必须是真跑过一次、可直接粘贴的完整命令；缺段会被 doctor 报"文档形状"
• 一次性脚本用完归档到 projects\<task>\scripts\dev-archive\；一次性修复脚本不许留在 tools\ 当工具暴露
• 改 registry.json 已有条目的字段值（status／note／verified／判据）一律用 bio-reg：它先备份、再改、再验 JSON、再保格式，并告诉你改了第几行。手写一次性脚本反复改事实源，是本站在 2026-09-16 踩过的坑
• 给工具声明成功判据 → 写进该工具条目的 success（expect_exit / out_dir_arg + out_glob / fail_signatures），并且必须配 probe 反向探针（故意造一次失败，证明判据真的会喊）
• 文档改过就要重新冻结哈希：bio-reg freeze-docs → 再跑 bio-doctor，否则报「文档哈希」不符
• 每批改动结束跑一次 bio-doctor；它同时是链接检查器、残留检查器、已知坑回归测试和事实源 schema 校验器

当前状态

不复述（复述必过期）。跑 tools\bio-doctor.bat 看现状，或用 -Json 取结构化结果。

历史留档：tools\体检报告-2026-08-25.md（全量工具体检）、tools\复查报告-2026-09-16.md（架构复查）、tools\修复报告-2026-09-16.md（问题闭环）。

想把工具层搬到别的机器（U 盘、图书馆电脑、只有 CPU 的笔记本）：tools\异地使用指南.md。 设计说明：tools\管理设计.md。

平台支持与致谢

本工作站的建站、重构、复查与日常校验，在**华东师范大学人工智能公共服务平台（ChatECNU）**的模型与平台工具上完成。

对外产物（论文、软著、数据集、开源 Release、对外报告）一律按下列声明照抄标注，中英文按发表语言择用：

本研究工作得到华东师范大学人工智能公共服务平台（ChatECNU）支持。

This work was supported by ChatECNU, the AI Service Platform of East China Normal University.

• 上面两行出自学校《致谢声明模板》，逐字照抄，不要改写、不要节选。
• 单件成果（论文／项目／获奖）另按学校《成果声明模板》出具签字声明书（成果名称、类别、获得时间）。
• 机读版写在 registry.json 的 policy.credit_rule；bio-new-task 生成的每个任务 README 自带这段声明，别删。

许可

代码与文档：MIT（见 LICENSE）。工具本体各自遵循其原始许可，本仓不重新分发。