Use when adding or upgrading ScholarAIO support for a new scientific computing tool, especially when the work needs official docs ingestion, toolref integration, lightweight skill design, and end-to-end CLI verification
把一个新科学工具接入 ScholarAIO，目标不是“写一份长教程”，而是形成这三个层次的闭环：
toolref 能查官方接口和参数skill 能指导 agent 何时使用、如何验证规范参考：
scientific-runtime skill适用于：
scholaraio toolreftoolref-first不适用于：
优先级：
不要优先用：
要求：
git 抓取还是 manifest 抓取经验判断：
gitmanifestgit；用户在乎的是 agent 能不能顺手查到当前项目里的经验：
QE / LAMMPS / GROMACS 更适合 git + parserOpenFOAM / Bioinformatics 更适合 manifest + curated entry pages问自己三个问题：
page_name 应该怎么命名，未来最稳？program / section / title 该怎样存，show/search 才顺手？经验规则：
page_name 要服务 CLI 使用体验，不要只服务抓取方便programprogram 要优先贴近用户会说出的名字，而不是内部类名或目录名section 要反映用户排查问题时的思路，例如 solver / dictionary / variant-calling从现有工具得到的粒度经验：
QE：程序名 + namelist + 参数名，这样 show qe pw ecutwfc 才顺LAMMPS：命令家族一定要做 alias 聚合，不然 fix npt 这种自然输入会漂走GROMACS：mdp 参数页必须尽量保留 options，不然会变成只有变量名的空页OpenFOAM：不要一上来想抓完整站点，先抓 solver / dictionary / post-processing 关键页Bioinformatics：要承认它是 toolchain，不是单软件；先解决“路由到哪个子工具”当目标从“最小可用”升级到“主体尽量全量”时：
先做高价值页面：
先让 list/show/search 真正可用，再扩充覆盖率。
停止条件也要明确：
如果用户明确要求“主体尽量全量”：
最低应有测试：
scholaraio.toolref 入口在内部重构后仍保持兼容meta.json、manifest 快照、SQLite 索引和 toolref list 展示口径一致如果没有先看到失败场景，就不知道这个工具接入点真正脆不脆。
如果这次工作包含 toolref 内部重构或拆包，必须额外补这类兼容测试：
import scholaraio.toolref 后旧调用路径仍可用最低要求：
fetch 能拉取并落盘list 能看到版本和页数show 能按用户自然输入命中search 能搜到高价值页面重点防御：
fetch、index、list 的计数口径漂移manifest 工具的额外要求：
fallback_urlsforce refresh 不能把旧缓存中仍然可用的页面冲掉meta.json 要能说清楚：预期页数、失败页数、恢复自缓存的页数#anchor 页面复用其基础 URL 的种子 HTMLpage_nametoolref list 不能盲信过期 meta.json；必要时要与快照和实际索引自校准fetch 返回的索引数量要和最终库里的真实可查询条目数一致，而不是解析中间态数量不能只跑测试。必须像用户一样手动执行：
scholaraio toolref fetch <tool>
scholaraio toolref list <tool>
scholaraio toolref show <tool> <natural query>
scholaraio toolref search <tool> "<real query>"
检查：
show 命中的是不是用户想看的页面synopsis 有没有信息量fetch 是否会卡在脏目录programfetch 报的页数/条目数，和 list 看到的最终数值是否一致list 会不会出现自相矛盾的显示scholaraio toolref ...，而不是内部模块命令如果手感不好，就继续打磨 CLI；不要因为测试是绿的就停。
至少要抽查这三类真实查询：
ecutwfcdrag coefficient、v-rescale thermostatread mapping nanopore、variant calling vcf如果做了“主体尽量全量”的扩展，还要加两类检查：
show/search 的核心路径是否仍然稳定，没有被噪音页挤掉toolref-first对应 scientific SKILL.md 应只保留：
toolref 查询入口不要把 skill 写成第二份 API 手册。
分工应始终是：
skill = 路由 + 方法论 + 验证规范toolref = 官方接口与参数scientific-runtime = 运行时退化与用户体验协议不要把内部包结构泄漏到 skill：
scholaraio toolref ...scholaraio.toolreffetch.py / manifest.py / storage.py 之类内部模块写成公开入口一个新工具只有同时满足下面几条，才算真正接入完成：
toolreffetch/list/show/search 都能真实使用toolref-first如果你要判断“是否已经够生产，不要再打磨了”，就看这几条：
show 查询能直接命中search 查询 rank 1 基本正确fetch/list 的统计口径不会把用户带沟里满足这些，就应该把精力转回 demo 和真实科研任务，而不是继续无止境磨 toolref
page_name 为抓取方便而设计，导致 show 很难用scholaraio.toolref 顶层兼容面fetch、数据库真实条目数、和 list 展示数字彼此不一致program + section + variable 粒度一旦对了，show 体验会非常稳fix npt，show 必须能稳稳落到 fix_nh，search 至少要把 fix_nh 放进最前排结果samtools / bcftools / iqtree 这类工具，应该利用官方总目录页、命令索引、章节 anchor 自动扩页ultrafast-bootstrap，但上游文档的实际锚点可能是 ultrafast-bootstrap-parameters面向 ScholarAIO 用户时，要始终记住：
toolref 的fetch/list/show/search 已手动体验fetch/list 计数口径已核对show/search 已验证scientific-runtime 协议兼容