在开源项目里跑 AI Agent：维护者视角的工程笔记
我们团队从去年开始在几个开源项目里引入 AI Agent，处理 issue triage、PR review 辅助、依赖更新、文档检查等重复性工作。
到目前为止，有些地方跑得比预想好，有些地方踩了不小的坑。这篇是一个实践者视角的工程笔记，不是方案推销。
开源项目的特殊性
在私有项目里引入 AI Agent，你控制所有参与者，可以统一制定规则。
开源项目不一样。开源项目的核心资产是社区信任——贡献者信任维护者的判断，用户信任项目的决策过程是公开透明的。引入 AI Agent 之后，这个信任链条变得复杂：
- 一个 AI Agent 关闭了某个 issue，理由充分吗？社区成员服气吗？
- 一个 AI Agent 在 PR review 里提出修改意见，贡献者是否会觉得自己在和机器辩论？
- 当 Agent 犯错时，维护者要怎么对社区解释？
这些不是技术问题，是治理问题。但它们会反过来约束技术选型和 Agent 的行为边界。
跑得比较好的场景
依赖自动更新。 这件事机械、有明确的成功标准（CI 通过），且失败代价低（关掉 PR 即可）。Renovate 这类工具早就在做，Agent 化之后可以加入更多判断：比如某个依赖更新会引入 breaking change，Agent 可以主动在 PR 里标记并请求人工 review。
Issue 分类和去重。 新 issue 进来，判断是 bug report、feature request 还是 question，自动打标签，查找可能的重复 issue 并链接。这件事维护者每天要做但非常低价值，Agent 准确率有限但够用，偶尔分错人工纠正即可。成本低，收益明确。
发布说明草稿。 给定一段时间内的 commit 列表和关联 PR，自动生成 CHANGELOG 草稿。维护者审阅修改，而不是从零撰写。这个场景的关键是 Agent 的输出是中间产物，不直接对外发布，人工审阅在流程里。
文档链接检查。 定期扫描文档里的外链是否失效，API 示例是否还能跑通，这类机械检查任务。
踩坑比较多的场景
PR Review 的”深度”问题。 我们最初期待 Agent 能做有价值的代码审查，发现结果分化严重：对格式、命名、简单逻辑问题，Agent 的 review 相当准确；但涉及设计决策、性能权衡、与项目整体方向的一致性，Agent 的意见往往泛泛而谈，甚至会误导贡献者。
更严重的问题是：贡献者收到 Agent 的 review 意见时，常常不确定该不该改。有维护者背书的 review 意见和机器生成的 review 意见，在 PR 界面上看起来一样，但权重完全不同。我们后来做了一个决定：Agent 只能留 inline comment，不能提交 “Request Changes” 级别的 review decision，最终的 approve 或 reject 必须由人做。
关闭 issue 的信任问题。 Agent 关闭 issue 在技术上很容易，但我们很快发现这件事需要极度谨慎。被 AI 关闭的 issue，提交者往往不满意，即使关闭理由写得很清楚。社区对 AI 做”拒绝”类决策的接受度，比我们预期的低很多。
现在的做法是：Agent 只能把 issue 标记为”待关闭”并加说明，维护者确认后再执行关闭操作。多了一个步骤，但社区反馈好很多。
上下文跨越 PR 边界。 Agent 在处理某个 issue 时，可能需要理解过去一年的相关讨论、已关闭的 PR、设计文档，甚至某次同步会议的结论。这个 cross-context 检索问题，目前没有很好的工程解。
我们的 Agent 在 issue triage 时偶尔会因为”不知道某件事已经被讨论过并被否定”而做出错误分类，导致重复讨论。这是 Agentic Memory 问题在开源场景下的具体表现——不只是存不存的问题，是 Agent 不知道自己不知道什么。
一个关键设计原则：Agent 只能建议，不能决定
在开源场景里，我们逐渐收敛到一个设计原则：对任何有外部可见性的操作，Agent 只能建议，决定权在人。
这个原则比听起来更难落实。难点不在于技术，而在于定义”外部可见性”的边界：
- Agent 关闭 issue：外部可见，需要人工确认
- Agent 在 PR 里留 comment：外部可见，但影响力比 review decision 小，我们决定放开
- Agent 更新 CI 配置：不直接对外可见，但影响所有贡献者的工作流，保留人工确认
- Agent 自动 merge 依赖更新 PR：CI 通过且是 patch 版本，放开自动 merge
这些决定没有通用答案，每个项目的社区敏感度不同，需要维护者自己判断。但做判断的过程本身是有价值的——它逼着你想清楚”这件事出错的代价是什么”。
工程实现上的几个建议
Dry-run 模式先跑一段时间。 Agent 配置好之后，先在 dry-run 模式下运行 2-4 周：Agent 生成操作但不执行，而是以 comment 形式汇报”如果我执行，我会做这些事”。维护者检查汇报，判断 Agent 的行为是否符合预期，再逐步开放权限。
每个操作都要可追溯。 Agent 做的每个操作，必须能溯源到”为什么做这个操作”。不是简单的日志，而是可以在 issue/PR 界面上直接看到的推理链路。社区成员需要能理解和质疑 Agent 的决策。
分级授权，从最小权限开始。 不要一上来就给 Agent 完整权限，从最低风险的操作开始（打标签），稳定运行几个月后再扩展（留 comment），再到下一层（关闭 issue）。每一层的扩展都需要维护者有意识地决定。
给社区成员一个覆盖机制。 任何 Agent 的操作，社区成员应该能轻松撤回，且撤回后 Agent 不会”反复撤销”。Agent 要能识别人工覆盖的情况并停止干预。这件事在 Harness 层做比在应用层做更可靠——如果工具本身就有”操作被覆盖”的事件通知，Agent 就不需要靠逻辑推理来判断。
开源社区和 AI Agent 的关系
有一个更大的问题值得思考：开源社区和 AI Agent 的关系是什么？
一个正在发生的趋势是：越来越多的 AI Agent 开始以”贡献者”的身份参与开源项目——提 issue、提 PR、留 review 意见。这件事没有坏处，但它对维护者的要求在悄悄变化。
过去，维护者处理的是人写的代码、人提的问题，判断是否 merge 的标准相对清晰。现在，你需要判断一个 PR 的作者是人还是 Agent，它背后是否有人在监督，这段代码的实际意图是什么。
这不是”AI 威胁开源”的故事，而是开源协作的参与者结构在扩展，维护者需要建立新的审查框架来适应。
我认为方向不是拒绝 AI 参与开源，而是建立清晰的 AI 贡献者规范：Agent 提交的变更应该有明确的来源标注，背后应该有人类维护者负责，审查标准应该更严格而不是更宽松。
在开源项目里跑 AI Agent，本质上是在把一个技术问题（自动化重复工作）和一个治理问题（谁有权做什么决定）捆绑在一起解决。
技术问题可以工程化；治理问题需要和社区对话。两件事都不省心，但都值得做。