Scientific Tool Onboarding

Scientific Tool Onboarding

Overview

先判断一个科学工具是否值得进入 ScholarAIO；只有通过 2.x integration gate 后，接入目标才是形成这三个层次的闭环，而不是“写一份长教程”：

• toolref 能查官方接口和参数
• 对应 skill 能指导 agent 何时使用、如何验证
• CLI 在真实使用中足够稳，不只是测试能过

规范参考：

• 公开接入说明统一参照 docs/guide/toolref-onboarding.md
• 产品边界与准入门统一参照 docs/design-docs/2.x-public-contract.md
• 运行时行为统一参照 scientific-runtime skill

When to Use

适用于：

• 新增一个科学计算工具到 scholaraio toolref
• 升级某个工具的官方文档源或版本策略
• 发现现有 scientific skill 过重，需要改成 toolref-first

不适用于：

• 只写一篇一次性笔记
• 只修一个小 typo

Core Workflow

0. 先过 2.x integration gate

不要因为用户提到一个项目、它很热门，或官方文档可抓取，就默认把它接入 ScholarAIO。先逐项确认：

• 它解决的是已经出现的核心学术任务，而不是增加一个新的平台类别
• 当前 agent 原生能力与已有 ScholarAIO 路径不能充分完成这个任务
• 没有另一套重叠适配器在做同一件事，并且有明确维护责任
• 依赖、凭据和运行时可以保持可选并与 core install 隔离
• 可以设计固定语料或端到端 smoke 来证明用户任务确实改善
• 缺凭据、断网、上游漂移或服务不可用时，能给出可执行错误或 fallback

任何一项不满足时，优先采用外部 recipe、用户自管工具或 sidecar；不要继续下面的内置接入流程。升级既有工具时也要重新过门，不因历史存在而自动保留。

1. 再定“官方真源”

优先级：

• 官方文档站
• 官方源码仓库中的文档目录
• 官方维护的 README / man page / PDF

不要优先用：

• 博客
• 第三方教程
• 论坛帖子

要求：

• 记录文档 URL、版本策略、格式（RST / HTML / man / Markdown / PDF）
• 判断适合 git 抓取还是 manifest 抓取

经验判断：

• 如果官方文档天然按源码版本演进、结构稳定、页面很多，优先 git
• 如果官方文档是独立文档站、页面总数可控、但抓取噪音和网络波动明显，优先 manifest
• 不要为了“理论更完整”强行选 git；用户在乎的是 agent 能不能顺手查到
• 如果文档站有“总目录页 / 命令索引页 / 手册页目录”，优先把它作为自动发现种子，而不是手写所有子页面

当前项目里的经验：

• QE / LAMMPS / GROMACS 更适合 git + parser
• OpenFOAM / Bioinformatics 更适合 manifest + curated entry pages

2. 再定“接入粒度”

问自己三个问题：

• 用户会按什么名词来查：求解器、命令、参数、字典、子工具？
• page_name 应该怎么命名，未来最稳？
• program / section / title 该怎样存，show/search 才顺手？

经验规则：

• page_name 要服务 CLI 使用体验，不要只服务抓取方便
• 一个大页面如果天然包含很多独立参数，应该拆页
• 如果工具本来就是多子工具工具链，允许一个 top-level tool 下挂多个 program
• program 要优先贴近用户会说出的名字，而不是内部类名或目录名
• 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，不是单软件；先解决“路由到哪个子工具”

当目标从“最小可用”升级到“主体尽量全量”时：

• 不要继续人工堆 manifest
• 要升级成“seed pages -> automatic discovery -> snapshot manifest -> fetch/index”
• 对于单页大手册，要优先考虑按 anchor / heading 拆成逻辑页

3. 先做最小 manifest / parser，不要一上来追求全量

先做高价值页面：

• 最常用求解器或主程序
• 最关键配置字典或参数页
• 最关键模型页
• 1-2 个典型后处理或分析页

先让 list/show/search 真正可用，再扩充覆盖率。

停止条件也要明确：

• 如果高频真实查询已经稳定命中正确页，就不要为了“全站完整”无限扩张
• “生产级”不等于“把官网每一页都搬下来”
• 对 manifest 工具，优先做到“关键入口完整 + 网络失败不回退成残废状态”

如果用户明确要求“主体尽量全量”：

• 先定义主线边界，再自动扩展
• 例如：OpenFOAM 主体文档可以包含 fundamentals / tools 主线，但排除插件、挂件、开发者扩展
• 例如：Bioinformatics 工具链可以扩展官方子命令页、章节页、命令手册锚点，但不要把随机第三方生态也拖进来

4. TDD 先测 parser 和鲁棒性边角

最低应有测试：

• 解析器能提取 title / synopsis / content
• 版本或 program 规范化逻辑
• top-level scholaraio.stores.toolref 入口在内部重构后仍保持兼容
• manifest 工具的“是否完整”判断
• 失败后残缺目录不会被误判成已完成
• 用户自然说法对应的 alias / query expansion
• 缓存保留和 fallback URL 行为（如果是 manifest 工具）
• 自动发现规则（如果是 discovery-based manifest）
• anchor / heading 切片逻辑（如果是单页大手册拆分）
• meta.json、manifest 快照、SQLite 索引和 toolref list 展示口径一致

如果没有先看到失败场景，就不知道这个工具接入点真正脆不脆。

如果这次工作包含 toolref 内部重构或拆包，必须额外补这类兼容测试：

• import scholaraio.stores.toolref 后旧调用路径仍可用
• 顶层兼容 patch 点仍能影响真实行为
• CLI 不需要知道内部模块名变化
• 旧缓存数据库在新 schema / trigger 下不会损坏或重复触发

5. 实现 fetch/index/show/search 全链路

最低要求：

• fetch 能拉取并落盘
• list 能看到版本和页数
• show 能按用户自然输入命中
• search 能搜到高价值页面

重点防御：

• 网络失败后的残缺目录
• manifest 页面部分失败
• program 名规范化不一致
• 页面命名和用户输入不一致
• 同一概念的不同人话表达
• 主入口页失效后没有降级路径
• 包拆分后顶层兼容 facade 失效
• fetch、index、list 的计数口径漂移

manifest 工具的额外要求：

• 对高价值但不稳定的页面，允许配置 fallback_urls
• force refresh 不能把旧缓存中仍然可用的页面冲掉
• meta.json 要能说清楚：预期页数、失败页数、恢复自缓存的页数
• 自动发现得到的 manifest 必须落盘成快照，不能每次都重新“猜”一遍
• 发现阶段已经拿到的 HTML，正式抓取时应直接复用，避免二次下载
• 当外站超时但本地已有种子页缓存时，应该允许“用缓存继续做结构发现”
• 如果逻辑页来自单页手册的 anchor，正式抓取时要允许 #anchor 页面复用其基础 URL 的种子 HTML
• 预置高价值页名不一定等于真实 heading id；发现阶段要把真实 anchor 元数据回填到这些规范化 page_name
• toolref list 不能盲信过期 meta.json；必要时要与快照和实际索引自校准
• fetch 返回的索引数量要和最终库里的真实可查询条目数一致，而不是解析中间态数量

6. 必须做“真实使用体验”验证

不能只跑测试。必须像用户一样手动执行：

scholaraio toolref fetch <tool>
scholaraio toolref list <tool>
scholaraio toolref show <tool> <natural query>
scholaraio toolref search <tool> "<real query>"

检查：

• show 命中的是不是用户想看的页面
• 正文前是不是被导航噪音淹没
• synopsis 有没有信息量
• 首次失败后，第二次 fetch 是否会卡在脏目录
• 搜索是不是只“有结果”，还是首条结果就是对的
• 结果标题是不是能让用户一眼知道为什么它是对的
• 如果是工具链型工具，用户的描述能不能先路由到对的 program
• fetch 报的页数/条目数，和 list 看到的最终数值是否一致
• manifest 工具在旧缓存存在时，list 会不会出现自相矛盾的显示
• 对外入口是否仍然只需要 scholaraio toolref ...，而不是内部模块命令

如果手感不好，就继续打磨 CLI；不要因为测试是绿的就停。

至少要抽查这三类真实查询：

• 参数名式：如 ecutwfc
• 自然语言式：如 drag coefficient、v-rescale thermostat
• 任务导向式：如 read mapping nanopore、variant calling vcf

如果做了“主体尽量全量”的扩展，还要加两类检查：

• 扩展后的总页数是否显著增加，而不是只换了实现没换覆盖面
• 扩展后 show/search 的核心路径是否仍然稳定，没有被噪音页挤掉