docs: 说明文档自动化的使用方式与当前暂不启用云端 full CI 的原因

[Chris-godz]

背景

PR #16 已经把当前这版文档自动化接入仓库，包括：

• 本地闭环文档自动化入口
• PR 文档校验流程
• Core CI 中预留的 full doc automation job
• docs/generated/ 相关证据和诊断输出

另外需要说明的是：当前仓库这批文档本身，已经基本是靠这套文档自动化流程自举出来的。
也就是说，这套东西不是“还停留在概念阶段”，而是已经真实参与了仓库文档的生成、整理和迭代。

现在怎么用

当前推荐的主入口是：

bash scripts/docgen/run_docgen_e2e_closed.sh

常见用法：

REF=main bash scripts/docgen/run_docgen_e2e_closed.sh

输出通常会写到：

• docs/generated/

其中包括：

• change_facts.json
• doc_scope_decision.json
• reference_context.json
• verify_report.json
• docgen_validation_report.md
• e2e_run.log

当前 CI 负责什么

现在 PR / push 上的 CI 主要负责外围校验，而不是完整 AI 闭环写作，包括：

• ./build.sh test
• 文档结构校验
• docgen 回归测试
• 聚合 verify
• mdbook build

它的目标是保证基础流程可验证、可回归，而不是在每次 PR 时直接跑完整文档自动化。

为什么现在没有正式启用云端 full CI

目前最现实的原因是：OpenAI API 成本太高。

完整的 full doc automation 会真实调用 Codex / OpenAI API 做闭环写作、验证、回顾和修补。如果把它作为组织仓库里的常规云端流程运行，会带来：

• 较高的模型调用成本
• 难以控制的持续消耗
• 不适合对每次改动都自动触发

所以当前策略是：

• 先把 CI 结构和校验壳子接好
• 先让 PR CI 负责轻量、稳定、可复现的验证
• 暂时不把昂贵的 full end-to-end 闭环作为常规云端流程启用

当前建议

现阶段更推荐：

1. 本地运行 scripts/docgen/run_docgen_e2e_closed.sh
2. 本地检查 docs/generated/ 下的证据和输出
3. 人工确认结果后再提交真实文档改动
4. 让仓库 CI 继续负责轻量校验和回归验证

结论

当前状态不是“文档自动化没做完”，而是：

• 本地入口已经可用
• 当前仓库文档已经靠这套流程完成过自举和迭代
• PR 校验已经接好
• 云端 full CI 已预留结构

但考虑到 OpenAI API 成本较高，现阶段更建议在本地跑 end-to-end，而不是在组织仓库中常态化启用完整云端闭环。