API 文档收割机

要解决的问题

很多团队的 API 文档散落在各家厂商站点上：文档站是 SPA，正文藏在打包文件里；导出的 OpenAPI spec 也与实际页面渐行渐远。最直觉的做法是驱动浏览器、把每一页丢给模型阅读——这条路径又贵又脆：页面一改脚本就挂，token 消耗巨大，产出的 schema 还常常带着模型脑补出来的 enum。apidoc-harvester 要回答的是：能不能把抓取变成一次配置、一条可复跑的流水线，而不是每次重新爬一遍？

核心思路：脚本化确定性，模型只做判断

两条原则撑起整条流水线：

• 最便宜的获取方式优先。 文档页面几乎总是从后端接口拉数据的。策略按成本从低到高排列：已发布的 OpenAPI/Swagger spec（spec_import，源头数据，支持 Swagger 2.0→3.0 转换与确定性 lint 修复）→ 直接命中内容接口（content_api）→ 从 SPA 打包文件静态提取（js_bundle，不执行 JS）→ 预下载的静态 HTML → 最后才是 headless 浏览器（rendered）。找到一次内容接口，整条流程就退化成普通 HTTP 脚本。
• 转换全部确定性化。 HTML→Markdown、表格→schema、schema→OpenAPI、校验都是脚本。模型只负责构建和改进这些脚本、发现内容接口、裁决文档矛盾、细化 enum 语义、产出判断类产物。

每个站点只是一个 YAML 配置，引擎保持通用。运行后在 out/<site>/ 下产出 Markdown、models.json、openapi.yaml 和 checks-report.json。

关键步骤

1. 复制 config/_template.yaml，填好选择器与结构，config/fadada.yaml 是完整样例。
2. 运行 python run.py config/<site>.yaml，读 checks-report.json 判断是否通过。
3. 失败时按 runbook/LOOP.md 的信号→修复表分类，提出最小改动，展示 diff、拿到许可再改，重跑直到稳定。
4. 已收割站点走维护路径：--sync-pages 检查页面增删，--update 复用未变更的 Markdown；拉取失败的接口会让本次运行直接失败，而不是被旧产物掩盖。
5. 稳定后把验证过的 Markdown 冻结进 golden/ 做回归快照，引擎行为变化记入 CHANGELOG.md——这是流水线的长期记忆。

适用边界与注意点

• rendered 只是兜底，能用 content_api 就别上浏览器。
• 生成的 OpenAPI 不会从散文里猜 enum，enum 细化留给模型辅助的可选步骤，保证基线输出准确。
• 超大 spec（多 MB、schema 图很重，如 DocuSign）生成 HTML 预览可能触发 Node 堆内存溢出，调大 NODE_OPTIONS 也救不回来，需要 inline Scalar 客户端 bundle 的降级方案。HTML 预览只是锦上添花，不影响主流程的成功判定，checks-report.json 是唯一裁判。
• 文档自身的矛盾（字段拼写、示例与表格不一致）会被保留并标注，而不是静默"修复"。
• 引擎脚本和站点配置是用户的长期代码：任何改动先 diff、再等确认，仅新站点的一次性配置可以直接写。
• 目标工作区已有拷贝引擎时，只刷新引擎自有系统文件（run.py、harvester/、runbook/ 等），保留用户数据；执行前用 python run.py --version 确认版本没有漂移。