使用GitHub Agentic Workflows实现跨仓库文档自动化

在软件开发中，文档滞后是一个常见痛点。Aspire团队（一个为分布式应用构建开发工具的小团队）也曾面临这个问题：工程师合并功能代码后，文档作者需花费数周反向工程变更内容。如今，他们利用GitHub Agentic Workflows实现了跨仓库文档自动化，将这一过程从数周缩短至中位44.8小时。

核心挑战在于跨仓库自动化。产品代码存储在microsoft/aspire，文档站点则在microsoft/aspire.dev——拥有不同的仓库、部署目标和审查链。传统方法依赖宽泛的仓库级令牌，但安全团队通常限制此类令牌。GitHub Agentic Workflows通过分离代理意图与实际执行解决了这一问题：代理仅生成JSON描述（意图），由独立的、权限受限的安全输出处理程序执行写操作。

具体流程如下：工作流pr-docs-check.md在microsoft/aspire中监听已合并的PR。首先，通过确定性bash脚本解析目标分支，利用PR里程碑（如13.4）映射到文档仓库的对应发布分支（如release/13.4）。随后，代理读取diff、检查关联问题，判断是否需要文档。若需要，它会在aspire.dev工作区中按现有规范起草内容，并触发安全输出以创建PR。该PR标记为草稿，指定产品PR的评审者为文档审阅者，标签为[docs-from-code]，且仅允许向main或release/*分支提交。

安全措施包括：每个工作流使用独立的GitHub App令牌，仅授权两个仓库；代理无法修改AGENTS.md、依赖清单等保护文件；若PR创建失败，自动回退为提交Issue。

在30天窗口内（涵盖Aspire 13.3和13.4发布），系统处理了396个产品PR，生成了82个文档PR，全部合并，中位合并时间44.8小时，其中96%在7天内完成。代理准确识别了需要文档的变更，拒绝了300多个无需文档的内部重构或测试修复。

该方案的成功得益于里程碑到分支的映射、草稿+开发者评审模式，以及严格的权限控制。初期代理对“是否需要文档”判断过于宽松，通过收紧提示词（加入反例）后误报率下降。此外，大diff导致提示词预算超限，通过预处理提取关键元数据解决。

最终，文档不再是事后补救，而是产品完成的一部分。工程师在合并代码后几分钟内即可收到文档草稿并审阅。文档作者从机械的反向工程中解放，专注于叙事性内容、示例程序和概念指南。安全约束反而使系统更可信、更正确。对于产品与文档分离的团队，这一模式提供了可复用的参考。