Easydict 贡献文档中的 Agent 协作流程:从 AGENTS.md 任务入口到 PR Review 的完整实践
Easydict 贡献文档中的 Agent 协作流程:从 AGENTS.md 任务入口到 PR Review 的完整实践
本篇技术指南围绕 Easydict 开源仓库在 2026-09-07 落地的一次贡献文档治理任务展开,系统讲解该项目如何将"编程 Agent 参与开发"制度化为一套可跳转、可验证、不随模型版本漂移的协作流程。读者将掌握:Easydict 中 Agent 的计划/执行两种任务模式与任务路由机制、AGENTS.md 唯一入口的设计意图、常用 Skill 与子代理的边界、PR 提交前后的人工 review 与自动 Codex review 双轨流程,以及维护者处理周期与高质量 PR 的优先条件。文中所有结论均以仓库内的 CONTRIBUTING.md、AGENTS.md、执行计划 与 变更历史 为事实依据。
背景与动机:贡献指南为什么需要"Agent 化"升级
Easydict 是一个深度集成 Agent 辅助开发流程的 macOS 词典翻译应用。在本次改进之前,仓库根目录的贡献指南主要覆盖传统开发与 PR 要求,存在三个明确缺口:
- Agent 开发流程缺失:没有完整说明 Agent 从任务入口、规则路由到交付的完整链路;
- 自动 review 说明缺失:没有介绍为 GitHub Pull Request 启用的 Codex Automatic reviews 以及贡献者的审查责任;
- 模型建议容易过期:两个 README 的 AI 辅助说明固定推荐
GPT-5.4,而模型名称迭代极快,硬编码版本很快就会过时。
因此,该任务的意图模式为 implementation,交付授权为 auto-local-commit,目标结果是"建立清晰、可跳转且不依赖具体模型版本的 Agent 贡献和 PR review 指南"。允许修改的路径被严格限定为 CONTRIBUTING.md、README.md、README_ZH.md、docs/exec-plans/、docs/histories/2026-09/,并明确禁止修改产品代码、Agent 规则或外部服务,禁止 push、pull、rebase 或 merge——这本身就是仓库 Agent 治理纪律的一个实例。
从仓库的 AGENTS.md 可以看到这套治理纪律的根源:AGENTS.md 被定义为"Agent 的唯一任务入口",详细规则只在对应专题文档维护;任何可能产生仓库差异的任务都必须先读取 exec-plans/README.md 与 histories/README.md,按规则判断 plan 和 history 的创建时机。
仓库的 Agent 基础设施:任务模式、路由与记录制度
要理解贡献文档改进的实际落点,必须先看清 Easydict 仓库围绕 Agent 建立的三层基础设施。
计划模式与执行模式
AGENTS.md 将 Agent 任务划分为两种模式:
- 计划模式:用户要求方案、分析、解释或评估时,只读取和检查现状并给出答复,不修改文件、Git 或外部服务;
- 执行模式:用户要求修改、修复、更新、实现或执行时,按"执行前 → 实现与验证 → Review → 交付"四步完成。其中执行前要求首次写入前读取任务路由要求的专题规则;交付阶段要求更新 history、完成并归档已有 plan,必要时验证通过后自动创建本地提交(用户明确要求不提交或没有差异时除外)。
本次贡献文档改进任务正是以执行模式运行的典型案例:其任务摘要中记录了"受阻操作及原因:none",写入前检查 pass,初始 HEAD 为 c29cfd3ebc26dbaeaae5b4a9c9bec0847ecd6f28,且初始 staged、unstaged、untracked 路径均为空——这些字段来自 计划模板 中"写入前状态"部分的设计,用于精确圈定 Agent-owned paths,确保自动本地提交不会误纳入无关改动。
任务路由:单一职责的专题规则
任务路由表是 AGENTS.md 的核心,它将不同职责的规则分散到独立文档,通过链接交叉引用而非复制条款:
- 构建、测试、工程文件与资源、Xcode 验证 → build-and-test.md;
- 跨语言代码质量、Swift、Objective-C、SwiftUI、API 和本地化 → coding-guidelines.md;
- 计划与 history 记录 → exec-plans/README.md 与 histories/README.md;
- 外部 Skills 和同步边界 → skills.md;
- 产品代码、跨功能行为或模块边界 → application-architecture.md;
- 公共使用或贡献者文档 → docs/user-docs/。
plan 与 history 的双轨记录
exec-plans/README.md 规定:多步骤、跨模块或高风险的执行任务在 active/ 使用模板创建计划,完成后按文件名月份移动到 completed/YYYY-MM/;计划文件与 history 文件共用 YYYY-MM-DD-<slug>.md 命名并跨轮复用 slug。histories/README.md 则规定:执行任务产生仓库差异时,在 YYYY-MM/ 记录最终结果与关键决策,不复制完整对话;存在 plan 时 history 链接归档后的 plan。
本次任务的记录结构即为标准范式:归档后的 执行计划 与 变更历史 共享 slug improve-contributing-agent-workflow,history 通过相对链接指向已完成 plan。
贡献指南重组:一次可验证的文档治理实践
本次任务的工作计划分四步执行:重组 CONTRIBUTING.md 并添加可跳转链接、精简两个 README 的 AI 辅助说明并移除具体模型版本、检查链接与需求覆盖、更新 history 并归档计划后按规则本地提交。最终落点都体现在当前仓库的 CONTRIBUTING.md 中。
突出 AGENTS.md 唯一入口
改进后的贡献指南在"使用编程 Agent"一节明确写道:Easydict 已深度集成 Agent 辅助开发流程,开始贡献前强烈建议阅读 AGENTS.md,并按其任务路由阅读相关规则。这一安排与 AGENTS.md"唯一任务入口"的定位相互呼应,避免了规则分散在各处造成的维护成本。
Skill 与子代理:用途与边界
贡献指南指出,常用 Skill 包括 review、review-pr、submit-pr、git-commit 和 worktree-rebase-merge 等,由上游统一维护。结合 skills.md 可以进一步理解其治理方式:
- 上游
tisfeng/skills的六个完整 Skill 目录(code-simplifier、git-commit、review、review-pr、submit-pr、worktree-rebase-merge)通过skills@1.5.25安装器以--copy --full-depth方式快照进仓库,skills-lock.json登记来源、ref、入口路径和内容哈希; - 快照保存完整目录,是为了离线可审查、历史可复现、可回滚;
- 通用 Git、Review 和交付算法由受管 Skill 维护,不通过本地修补或 fork 改写;Swift/Xcode、本地化和发布等项目政策则写入宿主规则。
变更历史中提到的 planner 和 reviewer 子代理,分别承担规划与评审职责,边界同样由上述专题规则约束。一个值得注意的细节是:v0.6.3 版本强制双语提交使用本地语言与英文标题分别撰写、保持相同的 Angular type、scope 与 breaking 语义,这体现了 Skill 层面就已经把提交规范固化。
模型建议不再硬编码版本
任务背景明确指出"两个 README 中的 AI 辅助说明固定推荐 GPT-5.4,容易过期"。改进后的处理方式是:README 与贡献指南统一采用"当前最新、适合复杂编程任务的 GPT 或 Claude 模型"这类稳定表述。例如 README_ZH.md 的"AI 辅助编程"一节写道"建议选择当前最新、适合复杂编程任务的 GPT 或 Claude 模型,并仔细 review 和测试最终改动",README.md 的 AI Coding 一节表述一致。
这一决策在任务的"风险与决策"中给出了明确理由:模型名称变化快,因此只推荐最新可用模型;README 只保留简洁引导,完整规则集中在贡献指南,避免规则重复和模型版本随时间漂移。
PR 全生命周期:人工 review、场景验证与自动 Codex review 的双轨制
贡献指南用"提交前"与"提交后"两个阶段完整定义了 Agent 参与 PR 时的质量责任。
提交前:review 最终 diff 与实际场景验证
CONTRIBUTING.md 明确:对于 Agent 参与的改动,提交 PR 前必须仔细 review 最终 diff,并在实际使用场景中运行验证,至少覆盖原问题或目标场景、正常流程和受影响的关键边界;"Agent review、自动测试和 CI 都不能替代实际场景验证"。PR 中需要写明验证环境、步骤、结果和未验证项;纯文档或其他静态修改按实际范围完成链接、格式或配置检查即可,且"不要把未运行的构建或测试写成已通过"。
这一原则与 build-and-test.md 的验证方法论一脉相承:根据变更需要证明的结果选择最小且充分的验证——纯治理 Markdown 默认只运行静态检查,生产源码变化才运行 xcodebuild build,修复 bug 或修改可测试行为才运行 xcodebuild test。本次任务仅修改治理和公开 Markdown 文档,因此验证阶段明确记录"不运行 xcodebuild"。
提交后:Codex Automatic reviews 与评论处理纪律
项目为 GitHub Pull Request 启用了 Codex Automatic reviews。PR 进入 review 后,Codex 会按照适用的 AGENTS.md 规则提供额外审查,贡献者也可以通过 @codex review 请求审查。任务验证阶段确认了这些术语与 OpenAI Docs 一致。
对于 Codex 和其他 reviewer 的意见,贡献指南给出了明确的分流处理纪律:
- 有效问题应修复并重新验证;
- 不准确或不适用的评论不必盲从,但应回复原因,并提供代码、测试或运行证据;
- 有分歧时继续讨论,不要只为清空状态而直接 resolve thread;
- 更新代码后检查 CI、冲突和剩余评论,确认没有无人回应或尚未处理的有效 review 问题。
同时反复强调:自动 review 是额外的质量检查,不能替代贡献者 review、测试、分支保护或维护者的最终判断。
维护者处理周期与高质量 PR 的优先条件
贡献指南如实说明了维护资源现实:当前活跃维护者数量有限,待 review 的贡献 PR 较多,因此人工 review 周期可能较长,也无法承诺固定处理时间。等待期间,贡献者被要求主动推进 review 流程:自查 diff、处理 CI 和冲突、回复 review 评论、补齐验证证据,准备完成后简要说明进展并请求复审。
在此基础上,范围明确、证据充分的高质量 PR 通常会被优先处理,标准全部可验证:
- 明确修复可复现的 bug,或解决具体且已充分说明的问题;
- 改动聚焦,代码清晰,并符合现有架构与代码规范;
- 提供自动测试或可靠的实际场景验证结果,且 CI 通过;
- review 意见已充分处理,没有无人回应或尚未处理的有效开放问题。
任务决策中还特意强调"高质量 PR 使用可验证标准描述,不承诺必然优先或合并"——优先处理不代表必然合并,维护者仍会根据正确性、产品方向、兼容性和维护成本作出最终判断。
验证方法论:本次任务如何自证
该任务在执行计划中记录了完整的验证矩阵,这既是本次文档改动的质量证明,也是仓库 Agent 验证纪律的示范:
git diff --check:通过;- Markdown 相对链接:通过,贡献指南引用的仓库文件均存在;
- 官方 Codex review 文档:通过,
@codex review与 Automatic reviews 的术语与 OpenAI Docs 一致; - 模型版本扫描:通过,
CONTRIBUTING.md、README.md和README_ZH.md未硬编码 GPT 或 Claude 版本; - 内容复核:通过,Agent 入口、能力简介、人工 review、场景验证、自动 review、维护周期、自助推进和高质量 PR 标准均有明确落点;
markdownlint:未运行,当前环境未安装该命令,已完成 Markdown 人工结构检查;xcodebuild:不运行,本次只修改治理和公开 Markdown 文档。
这套"运行了什么、为什么未运行什么"都如实记录的做法,与 build-and-test.md 中"不把未运行、失败或环境阻塞的检查写成通过"的原则完全一致,也是贡献者可以沿用的自查清单。
总结
Easydict 通过这次贡献文档治理,把 Agent 协作从"可用"推进到"有章可循":AGENTS.md 作为唯一入口统领任务模式与路由,专题规则单一职责、链接互引;贡献指南完整覆盖 Skill/子代理边界、提交前 review 与场景验证、提交后自动 Codex review 评论处理、维护周期与高质量 PR 优先标准;README 则回归简洁引导,不再硬编码易过期的模型版本。
对希望参与 Easydict 开发或借鉴其 Agent 治理模式的开发者而言,最佳起点是 AGENTS.md 与其任务路由表,随后按需进入 CONTRIBUTING.md、exec-plans/README.md 与 histories/README.md。本次任务的完整记录(计划与 history)可以作为研读仓库 Agent 协作纪律的第一份样本。