GitHub 把文档 PR 也交给 Agent 了

GitHub 官方博客这两天放出了一篇挺值得琢磨的实践复盘：.NET Aspire 团队把跨仓库的文档更新流程用 Agentic Workflows 跑了起来。产品仓库里一个 feature PR 被合并，另一个文档仓库里就会自动冒出一个对应的文档更新 PR，作者是 Agent，审核交给领域专家（SME）。整个链路不再需要工程师手动开 issue 提醒文档同事，也不需要文档同事回头爬 changelog 猜这周到底改了什么。

这件事单看不算大新闻——GitHub Agentic Workflows（内部代号 gh-aw）从今年 3 月官方 Checkout 频道正式介绍以来，已经跑了小半年，社区里叫它"super Dependabot"的人不在少数。但 Aspire 这个案例的意义在于，它第一次把 Agentic Workflows 用在了一个所有工程团队都痛、但又长期没被认真解决的问题上：产品变更与文档的时间差。

文档滞后这件事，为什么一直修不好

任何做过一定规模开源或商业产品的团队都知道，代码合并到文档同步之间那道缝是永远合不上的。原因也不神秘：

• 写代码的人不一定是最擅长写文档的人，反之亦然；
• 文档往往在独立仓库（docs repo），跟产品仓库解耦，PR 作者没有动力跨仓库开第二个 PR；
• Release notes 是有的，但把 release notes 翻译成"用户该怎么用这个新 API"是另一件事；
• 就算流程上要求"代码 + 文档同 PR"，实际执行也很容易被 deadline 冲垮。

结果就是文档总是慢半拍。用户翻到的文档还是上个版本的，issue 区里一半的问题是"文档里说的 X 参数怎么不存在了"。

Aspire 团队的做法是把这件事拆成一条流水线，让 Agent 承担中间那段最没人愿意干的翻译工作。

Aspire 是怎么串起来的

按博客里披露的做法，整条流程大致长这样：

1. 触发器：产品仓库 dotnet/aspire 里，一个带有 docs-needed 标签的 PR 被合并到 main。
2. Agent 启动：一个用 Markdown 描述的 agentic workflow 被 GitHub Actions 拉起来，任务是"读懂这次合并的改动，判断哪些文档需要更新"。
3. 跨仓库读写：Agent 拿着受限的 token，去 dotnet/docs-aspire 仓库里检索相关文档、读取现有内容、生成 diff。
4. 产出 PR：Agent 在文档仓库开一个新 PR，body 里带上原始 PR 链接、变更摘要、修改理由。
5. 人工审核：SME 收到通知，进 PR review，改文风、补上下文、合并。

关键的一点是，这里的 Agent 不是那种"读一下 diff 就生成一段话"的浅层脚本。它拿到的输入包括：原 PR 的标题、描述、diff、被改到的代码文件、代码里的 XML doc comments，以及文档仓库现有的对应章节。它要判断的是"这次改动会影响哪些用户可见的行为"，然后决定"应该在文档的哪个位置改什么"。这更像是让一个初级 tech writer 干活，而不是让脚本套模板。

Agentic Workflows 本身是个什么东西

对不熟悉的读者简单交代一下背景。GitHub Agentic Workflows（gh-aw）是 GitHub Next 孵化出来的一套东西，简单说就是"用自然语言写 GitHub Actions"。你在 .github/workflows/ 里放的不再是纯 YAML，而是一份 Markdown 文件——顶部一段 frontmatter 声明触发器、权限、工具，正文用英文（或中文）写清楚你想让 Agent 干什么。gh-aw 会把这份 Markdown 编译成一份带安全护栏的 YAML，跑在标准的 GitHub Actions runner 上，底层调用 Copilot 编码 Agent 执行。

一份典型的 agentic workflow 骨架长这样：

---
on:
  pull_request:
    types: [closed]
    branches: [main]
permissions:
  contents: read
  pull-requests: write
safe-outputs:
  create-pull-request:
    target-repo: dotnet/docs-aspire
timeout_minutes: 20
---

# Sync docs for merged Aspire PR

When a PR is merged into `dotnet/aspire` with the `docs-needed` label:

1. Read the PR diff and identify user-facing API changes.
2. Locate the corresponding pages in `dotnet/docs-aspire`.
3. Draft updates that reflect the new behavior.
4. Open a pull request against `dotnet/docs-aspire` and
   assign the docs SME as reviewer.

注意其中的 safe-outputs。这是 gh-aw 的核心设计之一：Agent 本身跑在一个受限的环境里，它不能直接 push 代码、不能直接 merge、不能直接调外部 API。它能做的"副作用"必须通过 safe-outputs 声明，由框架代为执行。想开 PR？只能开到你允许的目标仓库。想评论 issue？评论内容会经过一层过滤。想调用某个 MCP 工具？工具白名单是编译期决定的，运行时改不了。

这套护栏机制解决的是 Agent 落地里最容易出事的一类问题——权限失控。传统 GitHub Actions 里如果你给了 workflow 一个 write token，出了 prompt injection 基本就是裸奔。gh-aw 的做法是把 Agent 的执行域和副作用域切开，Agent 想干什么必须通过声明式的出口，出口本身由 GitHub 托管的可信步骤执行。

这套东西真的能替代人吗

先说结论：替代不了 SME，但能替代 SME 之前那段没人愿意干的活。

从 Aspire 团队给出的数据能看出来，Agent 生成的 PR 不是拿来直接合的。SME 平均每个 PR 会有若干轮修改，改文风、补背景、纠正 Agent 对某些 API 意图的误解。这跟大家对 LLM 生成内容的一贯经验一致——它给你的是一份"70 分的初稿"，把你从冷启动里救出来，但离能发布还差一段。

但这个 70 分的价值恰恰在于它把最难启动的那部分做完了。写文档最痛苦的从来不是敲字，是"这次改了啥、影响哪些页面、要不要改示例代码"这种上下文回忆和跨仓库定位。Agent 把这些前置工作做完，SME 打开 PR 时看到的是一份已经定位到具体章节、已经把 diff 关联起来的草稿，改起来的心智负担和从零开始完全不是一回事。

另一个我觉得值得留意的点是审核责任的重新分配。以前"代码合了、文档没跟上"这件事没人负责——写代码的人觉得不是自己的事，文档同事觉得没人通知我。现在流程变成了"Agent 负责起草，SME 负责审核"，责任明确落到 SME 头上。这看似给 SME 加了活，实际上因为草稿已经存在，SME 的工作从"主动发现 + 撰写"变成了"审核 + 微调"，总量反而下降。

跟传统方案比，差在哪儿

有人会说，这事用传统脚本 + 模板不也能干吗？合并 PR 触发一个 job，把 PR 描述贴到文档仓库开个 issue 提醒一下——技术上完全可行。但两者的差别在于理解深度。

模板化的方案只能做到"提醒"，做不到"起草"。它没法读懂 diff、没法判断哪些改动是 breaking change、没法在文档里定位到具体段落。SME 收到的还是一个空 issue，工作量该多少还是多少。

Agentic Workflow 的价值就在于它把"读懂代码变更"和"定位文档位置"这两个需要理解力的环节交给了 LLM，而把"什么时候触发、允许写到哪里、超时怎么办"这些需要确定性的环节交给了 GitHub Actions。这个分工比"从头到尾全交给 Agent"或者"从头到尾都是脚本"都合理。

顺带说一句更大的趋势

把这件事放到更大的图景里看，其实是软件交付流水线的进一步 AI 化。过去两年我们看到 CI/CD 里陆陆续续冒出各种 AI 辅助环节——AI 生成的 PR 描述、AI review 代码、AI 分类 issue、AI 升级依赖（Dependabot 的新版本已经开始用 Copilot 处理 breaking change）。文档同步是这条流水线里最后一个还大量依赖人工的环节，现在也开始被啃下来了。

对开发团队来说，值得思考的问题是：哪些流程环节本质上是"翻译"？——把 A 系统里的信息翻译成 B 系统需要的格式。这类环节几乎都是 Agentic Workflow 的candidates。产品变更翻译成文档、issue 翻译成 changelog、bug report 翻译成复现步骤、用户反馈翻译成 backlog item……每一个都可以套 Aspire 这套模式。

另一件事是，这类 Agent 跑起来之后对 API 调用量的需求是持续的。一个中等规模的开源项目一周几十上百个 PR，每个 PR 都要跑一次多轮工具调用，token 消耗不小。国内团队如果想跑类似的东西，模型选型和 API 通路的稳定性都得提前想清楚。OpenAI Hub 这类聚合平台的价值在这类场景里会比较明显——一个 Key 挂在 workflow 里，底层想切 Claude 还是 GPT 还是 DeepSeek 都能来回换，不用为了对比效果重写认证逻辑。

一点保留意见

最后泼点冷水。这套东西目前跑得好的案例，几乎都是结构良好的产品——.NET Aspire 有清晰的 API 边界，文档也是章节化组织的。换到一个 API 混乱、文档到处飘的老项目上，Agent 大概率会开出一堆改错位置、漏掉关键上下文的 PR，SME 反而要花更多时间收拾。

所以别把这当成万能药。它更像是给已经把工程规范做好的团队的一份加成，而不是给混乱项目的一次拯救。文档同步能自动化的前提是文档本身有结构，代码变更能被 Agent 理解的前提是代码本身有清晰的意图。工具再强也没法替你把地基打好。

但方向是对的。产品到文档这条以前靠人工拉的线，现在开始有像样的自动化方案了。下一个被啃掉的会是哪个环节，值得盯着。

参考来源

• Creating GitHub Agentic Workflows - GitHub 官方文档：官方对 agentic workflows 编写方式、组织级配置的说明。
• 技术速递｜使用 GitHub Agentic Workflows 自动化仓库任务：知乎上对 gh-aw 基本概念和运行机制的中文介绍。