产品代码合并以后，文档常常慢半拍：发布说明先走，用户问题先来，文档 PR 还在排队。GitHub 博客里提到 Aspire 团队正在用 GitHub Agentic Workflows 缩短这个时间差：把已经合并的产品变更转化为文档仓库里的 pull request，再交给主题专家（SME）审阅。关键不是让 AI 直接发布文档，而是把“发现变更、起草文档、发起审阅”这段重复劳动自动化。
真正要自动化的是跨仓库交接
很多团队的产品代码和文档不在同一个仓库里。代码仓库里有 PR、commit、issue、测试和实现细节；文档仓库里有 Markdown、导航结构、版本目录和审核规则。人工流程通常长这样：工程师合并功能，文档工程师追踪变更，找 SME 问细节，然后开一个文档 PR。
Agentic Workflow 的价值在于把这条链路编排起来：
- 从已合并的产品 PR 中提取变更意图、用户可见行为、配置项、限制条件。
- 在文档仓库里定位可能需要修改的页面。
- 生成一个草稿 PR，而不是绕过审阅直接合并。
- 自动请求对应 SME 审阅，让知识责任人仍然在闭环里。
这点很重要。文档不是代码 diff 的散文版。产品行为、边界条件、迁移说明、弃用策略，都需要人确认。自动化应该压缩等待时间，而不是删除判断环节。
从“合并事件”到“文档 PR”的工作流形状
可以把这类流程拆成四个动作：监听、收集上下文、生成修改、发起审阅。
监听通常发生在产品仓库：当 PR merge 到主分支，或者打上 needs-docs 标签时触发。收集上下文时，工作流需要拿到 PR 标题、正文、变更文件、相关 issue，必要时还要拉取文档仓库内容。生成修改可以交给 agent 或脚本完成，但输出必须落到一个普通分支上。发起审阅则使用 GitHub PR、CODEOWNERS、reviewer request 或团队标签。
这类设计有一个很实际的好处：失败点清晰。如果 agent 找不到文档位置，它可以开一个包含 TODO 的草稿 PR；如果 SME 认为内容不准确，可以直接在文档 PR 上评论；如果变更不需要文档，可以关闭 PR 并留下原因。
可以这样实践：用 GitHub Actions 串起跨仓库文档草稿
下面是一个可改造的最小工作流。假设产品仓库在 PR 合并后触发，文档仓库是 acme/docs，并且你准备在后续步骤里接入自己的 LLM、GitHub Agentic Workflow 或内部文档生成服务。
需要替换的地方：
DOCS_REPO：你的文档仓库。SME_REVIEWERS：GitHub 用户名，逗号分隔。DOCS_BOT_TOKEN：有权限读取产品仓库、向文档仓库推分支并创建 PR 的 token。
name: Create docs draft from merged product PR
on:
pull_request:
types: [closed]
permissions:
contents: read
pull-requests: read
jobs:
docs-draft:
if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'needs-docs')
runs-on: ubuntu-latest
env:
DOCS_REPO: acme/docs
SME_REVIEWERS: alice,bob
PRODUCT_PR_NUMBER: ${{ github.event.pull_request.number }}
PRODUCT_PR_TITLE: ${{ github.event.pull_request.title }}
PRODUCT_PR_BODY: ${{ github.event.pull_request.body }}
steps:
- name: Checkout product repo
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Collect merged PR context
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
mkdir -p /tmp/docs-agent
gh pr view "$PRODUCT_PR_NUMBER" \
--json title,body,files,commits,author,labels,url \
> /tmp/docs-agent/product-pr.json
- name: Checkout docs repo
uses: actions/checkout@v4
with:
repository: ${{ env.DOCS_REPO }}
token: ${{ secrets.DOCS_BOT_TOKEN }}
path: docs
- name: Generate docs patch
working-directory: docs
run: |
branch="docs/product-pr-${PRODUCT_PR_NUMBER}"
git checkout -b "$branch"
mkdir -p drafts
cat > "drafts/product-pr-${PRODUCT_PR_NUMBER}.md" <<EOF
# Documentation draft for product PR #${PRODUCT_PR_NUMBER}
Product change: ${PRODUCT_PR_TITLE}
Source PR summary:
${PRODUCT_PR_BODY}
SME checklist:
- [ ] Confirm user-visible behavior
- [ ] Confirm configuration names and defaults
- [ ] Confirm limitations or migration notes
- [ ] Move this draft into the correct documentation page
EOF
git config user.name "docs-agent-bot"
git config user.email "docs-agent-bot@example.com"
git add "drafts/product-pr-${PRODUCT_PR_NUMBER}.md"
git commit -m "Draft docs for product PR #${PRODUCT_PR_NUMBER}"
git push origin "$branch"
- name: Open docs pull request
working-directory: docs
env:
GH_TOKEN: ${{ secrets.DOCS_BOT_TOKEN }}
run: |
gh pr create \
--repo "$DOCS_REPO" \
--title "Docs draft for product PR #${PRODUCT_PR_NUMBER}" \
--body "Automated draft from merged product PR. SME review required before merge." \
--reviewer "$SME_REVIEWERS"
这个例子故意把生成内容做得保守：它先创建草稿页和检查清单。你可以把 Generate docs patch 替换为 agent 调用，让它读取 /tmp/docs-agent/product-pr.json 和文档目录，直接修改目标 Markdown 页面。
例如，可以给 agent 这样的任务边界：
You are preparing a documentation pull request.
Use the merged product PR metadata in /tmp/docs-agent/product-pr.json.
Update only files under docs/.
Do not invent product behavior.
If a detail is missing, add an HTML comment starting with TODO-SME.
Keep the change small enough for a subject matter expert to review in one pass.
这个 prompt 的重点是限制写入范围、禁止编造、把不确定性显式交给 SME。跨仓库文档自动化最怕“看起来完整但事实错误”的文本，宁可留下清晰 TODO，也不要生成自信的猜测。
审阅机制比生成能力更关键
把文档 PR 自动开出来之后，真正决定质量的是审阅机制。建议至少加上三层保护：
- 用标签控制触发范围，例如只有
needs-docs或public-api-change才启动流程。 - 用 CODEOWNERS 或 reviewer 映射表请求 SME，而不是让所有文档 PR 都找同一批人。
- 在 PR 模板里要求确认行为、默认值、版本、限制和迁移路径。
一个简单的 reviewer 映射可以放在产品仓库里：
# .github/docs-reviewers.yml
areas:
aspire-hosting:
paths:
- "src/Hosting/**"
reviewers:
- alice
aspire-dashboard:
paths:
- "src/Dashboard/**"
reviewers:
- bob
后续工作流可以根据变更文件匹配 reviewer。这样，自动化不会把所有知识债都推给文档团队，而是把正确的问题送到正确的人面前。
落地时要守住边界
这类 Agentic Workflow 最适合处理“已合并变更到文档草稿”的连接层，而不是替代产品判断。落地前可以用下面的清单收口：
- 触发条件是否足够窄，避免每个内部重构都生成文档 PR？
- token 是否只给必要仓库和必要权限？
- agent 是否只能修改文档目录，不能改构建脚本或发布配置？
- 生成文本是否保留来源 PR、文件列表和未确认 TODO？
- SME 审阅是否是必需状态检查，而不是可选提醒？
Aspire 团队的做法给了一个清晰方向：让自动化追上产品发布节奏，但把发布前的最终判断留给人。文档流水线不需要神奇，它需要准时、可审、可回滚。做到这三点，跨仓库文档 PR 就能从“发布后补作业”变成合并流程里的正常产物。