使用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導致提示詞預算超限，透過預處理提取關鍵後設資料解決。

最終，文件不再是事後補救，而是產品完成的一部分。工程師在合併程式碼後幾分鐘內即可收到文件草稿並審閱。文件作者從機械的反向工程中解放，專注於敘事性內容、示例程式和概念指南。安全約束反而使系統更可信、更正確。對於產品與文件分離的團隊，這一模式提供了可複用的參考。