Easydict 的 Agent 协作规则体系:AGENTS.md 任务入口与执行工作流全解读
Easydict 的 Agent 协作规则体系:AGENTS.md 任务入口与执行工作流全解读
Easydict 是一款开源的 macOS 词典与翻译应用,支持查词、文本翻译、划词翻译和 OCR 截图翻译,同时接入了有道、苹果系统词典、苹果系统翻译、OpenAI、Gemini、DeepL、Google、Bing、腾讯、百度、阿里、小牛、彩云与火山等多个翻译或 AI 服务提供商。作为一个人工智能 Agent 高度参与开发的开源仓库,Easydict 通过 .claude/CLAUDE.md(内容与仓库根目录的 AGENTS.md 完全一致)为 Agent 定义了唯一的任务入口和完整的协作规则。阅读本文后,你将掌握该仓库的"计划模式 / 执行模式"双模式约定、执行模式下的四步工作流(执行前 → 实现与验证 → Review → 交付)、跨职责文档的单一路由规则,以及构建、测试、编码规范、计划与历史记录等专题文档的完整地图,从而能够像仓库维护者期望的那样,安全、规范地在该仓库中开展研究与开发工作。
AGENTS.md:Agent 的唯一任务入口
在 Easydict 仓库中,AGENTS.md 被明确定位为 Agent 的唯一任务入口。其设计哲学是"现行规则文档单一职责,跨职责使用链接,不复制条款":入口文档只负责告诉 Agent 应该做什么、按什么顺序做、遇到哪类问题去读哪份文档,而具体的细则全部下沉到各自的专题文档中维护。
这种分层设计带来三个直接好处:
- 入口稳定:无论规则如何演进,Agent 只需要从
AGENTS.md出发,通过任务路由找到当前任务真正需要的规则,避免每次任务都重新通读全部文档。 - 避免条款漂移:规则只在一处维护,专题文档通过相对仓库路径互相链接,不会出现同一条款在多份文档中维护而逐渐不一致的问题。
- 按需加载:任务路由明确要求"只读取当前任务需要的专题规则",控制每次任务的上下文开销。
值得注意的是,仓库将同一份入口文档同时放在 .claude/ 目录与仓库根目录,前者面向 Claude 系列 Agent 客户端,后者是通用入口,两者内容保持一致,确保无论使用哪类 Agent 工具链都能获得相同的任务约束。
任务模式:计划模式与执行模式的边界
AGENTS.md 将 Agent 的任务划分为两种模式,边界清晰且互斥:
计划模式(Plan Mode)
当用户要求的是方案、分析、解释或评估时,Agent 进入计划模式。该模式下:
- 只读取和检查现状并给出答复;
- 不修改文件、Git 或外部服务。
计划模式的本质是"只读研究",适合需求澄清、技术调研、可行性分析、方案对比等场景。例如,当用户询问"Easydict 的翻译服务层是如何组织的"时,Agent 应只阅读 Easydict/Swift/Service 下的实现并给出分析,而不应顺手改动任何文件。
执行模式(Execute Mode)
当用户要求的是修改、修复、更新、实现或执行时,Agent 进入执行模式。执行模式有明确的四步顺序(见下一节)。两个模式之间有一条重要的衔接规则:从计划模式转入执行模式后,从"执行前"开始——即使 Agent 在计划模式下已经熟悉了上下文,正式动手写入前仍须重新完成执行前的要求。
从仓库历史看,这套双模式机制经历了持续演进,例如 2026-08-21-agent-task-modes-auto-commit.md、2026-09-17-split-task-modes.md 等历史记录反映了任务模式规则本身的迭代过程。
执行模式四步工作流详解
执行模式要求 Agent 严格按以下顺序完成任务:
第一步:执行前(Pre-Execution)
首次写入前,Agent 必须读取任务路由要求的专题规则;任何可能产生仓库差异的任务都必须读取 docs/exec-plans/README.md 与 docs/histories/README.md,并按其规则判断本次任务是否需要建立 plan(执行计划)和 history(变更历史记录)。
这一步的目的是把"可能修改仓库"的任务纳入治理轨道:多步骤、跨模块或高风险任务需要在 docs/exec-plans/active/ 下按 docs/exec-plans/templates.md 模板创建计划,完成后按文件名月份归档到 docs/exec-plans/completed/YYYY-MM/;产生仓库文件差异的任务则需要在 docs/histories/YYYY-MM/ 下按 docs/histories/template.md 记录结果。计划与历史记录共用 YYYY-MM-DD-<slug>.md 文件名,同一任务共享 slug 并跨轮复用,slug 使用小写 kebab-case。
仓库中大量的已完成计划与历史记录就是这套机制的实践产物,例如 docs/exec-plans/completed/2026-09/2026-09-19-release-2.23.0.md、docs/histories/2026-09/2026-09-17-app-path-management.md 等。
第二步:实现与验证(Implementation & Verification)
完成范围内的修改后,Agent 必须运行风险匹配的验证;失败时修复并重新验证。验证策略遵循 docs/agents/build-and-test.md:
- 纯治理 Markdown、plan、history、注释,以及不进入 Xcode 构建图的脚本或配置,默认只运行相应的静态检查;
- 生产源码、工程/workspace、target、build setting、build phase、依赖、entitlement、Info.plist 或运行时资源发生实质变化时,运行覆盖受影响配置的
xcodebuild build; - 修复 bug、修改可测试行为或测试源码及其 target 引用时,运行覆盖相应行为、suite 或方法的
xcodebuild test。
常用命令矩阵如下(配合 xcbeautify 时需启用 set -o pipefail 以保留 xcodebuild 的真实退出状态):
# Build
set -o pipefail
xcodebuild build \
-workspace Easydict.xcworkspace \
-scheme Easydict | xcbeautify
# Test all tests
xcodebuild test \
-workspace Easydict.xcworkspace \
-scheme Easydict | xcbeautify
# Build for repeated test runs
xcodebuild build-for-testing \
-workspace Easydict.xcworkspace \
-scheme Easydict | xcbeautify
# Run a test suite after a compatible build-for-testing
xcodebuild test-without-building \
-workspace Easydict.xcworkspace \
-scheme Easydict \
-only-testing:EasydictTests/UtilityFunctionsTests | xcbeautify
# Run one test method after a compatible build-for-testing
xcodebuild test-without-building \
-workspace Easydict.xcworkspace \
-scheme Easydict \
-only-testing:EasydictTests/UtilityFunctionsTests/testAES | xcbeautify
构建验证使用默认的 Xcode DerivedData;只有当失败证据指向权限、缓存损坏或 runner 状态时,才允许使用显式临时 DerivedData 重试(例如 -derivedDataPath ~/Library/Developer/Xcode/DerivedData/Easydict-Temporary)。此外,每次变更还需运行 git diff --check,对变更的 .xcstrings 或 JSON 数据运行 jq -e .,对变更的 Shell 脚本运行 bash -n。
测试代码的添加有严格授权边界:只有用户在当前任务中明确要求添加测试代码时,才允许新增或扩写测试;修复真实 bug、新增功能、修改复杂逻辑或判断存在回归风险,都不构成添加测试的授权。未获授权时只能运行和分析现有测试。
第三步:Review
生产代码、复杂逻辑、跨模块或高风险变更在验证通过后,使用 .agents/skills/review/SKILL.md 中描述的 review 技能进行审查;修复有效 finding 后重新验证和审查。纯文档及简单低风险变更除外。
review 技能本身是一份只读审查契约:它不 checkout、不改源码、不操作 Git 索引、不修改远程服务,审查范围可以是单次任务、当前工作树、单个提交、提交范围、文件或模块。审查报告中的 finding 按风险分级:
- P0:严重且明确的数据、安全或核心流程损坏,需立即阻止交付;
- P1:很可能出现的用户可见回归或错误行为;
- P2:可复现的边界、兼容性或需求覆盖缺陷;
- P3:具有具体后果的维护或验证缺口(不包含单纯风格偏好)。
每个 finding 需要给出优先级、准确位置、触发条件、影响、代码证据、最小具体的 Suggested Fix 和验证建议。对于 GitHub PR 场景,则由 review-pr 技能负责提供准确的远程 head、真实的 merge-base diff、验收条件及完整线程上下文。
第四步:交付(Delivery)
更新 history,完成并归档已有的 plan;必要验证和适用的 Review 通过后自动创建本地提交。有两个例外:用户明确要求不提交,或本次任务没有产生差异。
此外还有明确的边界约束:push、创建 Pull Request、发布及其他外部写入仅在用户明确要求时执行;用户的禁止、范围和顺序要求优先于默认流程。这意味着 Agent 的自动化交付止步于本地提交,任何影响外部仓库或服务的操作都必须由用户显式授权。
通用规则:贯穿所有任务的约束
AGENTS.md 中的通用规则是所有任务的底线约束,主要包括:
- 写入授权:无法确认修改授权时保持只读;从计划模式转入执行模式后,从"执行前"开始。
- 操作边界:用户的禁止、范围和顺序要求优先;push、创建 Pull Request、发布及其他外部写入仅在用户明确要求时执行。
- 语言策略:回复使用用户当前请求的语言;已有文档保持原语言;代码标识、API 名称、命令、路径、品牌名称和固定输出契约保留原文。
- 文档治理:现行规则文档单一职责,跨职责使用链接,不复制条款;文档使用相对仓库路径,不提交机器本地绝对路径。
- 证据边界:历史记录与设计文档只在被当前任务明确采用时才构成约束——这保证了历史文档不会凭空约束新任务,只有任务明确采纳时才具有约束力。
任务路由:专题文档地图
任务路由是 AGENTS.md 的核心价值所在。它根据任务主题,将 Agent 导向唯一的专题规则文档,避免通读全部文档:
| 任务主题 | 路由目标 |
|---|---|
| 构建、测试、工程文件与资源、Xcode 验证 | docs/agents/build-and-test.md |
| 跨语言代码质量、Swift、Objective-C、SwiftUI、API 和本地化 | docs/agents/coding-guidelines.md |
| 计划与 history 记录 | docs/exec-plans/README.md 与 docs/histories/README.md |
| 参考资料与外部证据 | docs/references/README.md |
| 外部 Skills 和同步边界 | docs/agents/skills.md |
| 产品代码、跨功能行为或模块边界 | docs/design-docs/application-architecture.md |
| 公共使用或贡献者文档 | docs/user-docs/en 与 docs/user-docs/zh |
下面结合仓库实际内容,逐一展开这些专题文档所承载的规则。
构建与测试:Xcode 验证策略
docs/agents/build-and-test.md 不仅给出命令矩阵,还规定了测试代码的组织方式:
- 测试目录按领域对应源码模块,Swift 测试以
Easydict/Swift/为映射根,例如Easydict/Swift/Service/OpenAI/对应EasydictTests/Service/OpenAI/; - 每个测试文件聚焦一个主要被测类型或行为领域,最多声明一个
@Suite类型; - 跨目录复用的 fixture 或工具放入
EasydictTests/Support/<Domain>/。
仓库中的测试布局完全遵循这一约定,例如 EasydictTests/Service/ClaudeCode/、EasydictTests/Service/CodexCLI/、EasydictTests/Feature/Markdown/MarkdownRendererTests.swift、EasydictTests/Utility/String/StringAnalysisTests.swift 等。此外,新增、移动或删除由 Xcode 管理的源码文件或运行时资源时,必须同步 Easydict.xcodeproj/project.pbxproj 中的 group、文件和 build phase 引用;而仓库治理类的 Markdown、计划、history、skill 等文档不需要工程引用。
编码规范:跨语言代码质量与本地化
docs/agents/coding-guidelines.md 覆盖跨语言代码质量(适用于手写的 Swift、Objective-C、Python、Shell、JavaScript/TypeScript)、语言与迁移策略、Swift 组织与实践、库与 API 约定以及本地化规范:
- 组织与命名:按功能和明确职责组织代码;每个源码文件聚焦一个职责;编译的 Swift、Objective-C 和测试文件使用
UpperCamelCase;代码库已经采用 async/await 时优先沿用。 - 语言与迁移:新功能优先使用 Swift/SwiftUI;现有 Objective-C 允许必要的 bug 修复,迁移只在任务范围内进行。长期迁移路线图记录在 docs/exec-plans/active/swift-migration.md,其中可以看到 Google、Bing、有道、NiuTrans、DeepL、百度等翻译服务以及
QueryService基类已经完成从 Objective-C 到 Swift 的迁移,而Easydict/objc/下仍保留着遗留的 Objective-C 边界。 - 库与 API:SF Symbols 使用 SFSafeSymbols 的类型安全 API;SwiftUI 使用
foregroundStyle而非已弃用的foregroundColor;网络请求使用 Alamofire 的 async/await API;用户偏好使用 Defaults,不直接使用UserDefaults。 - 本地化:所有用户可见 UI 文本必须本地化,
Easydict/App/Localizable.xcstrings是应用主 String Catalog;key 使用小写、点号分隔并按<scope>.<category>.<subcategory>.<element>使用 snake_case 片段;不动态构建本地化 key,也不拼接本地化片段。翻译贡献说明位于 docs/user-docs/en/How-to-translate-Easydict.md 及其中文对应文档。
计划与历史记录:治理轨道
docs/exec-plans/README.md 规定 active/ 保存进行中的计划、completed/YYYY-MM/ 按文件名月份归档已完成计划、templates.md 提供新计划模板。计划需记录目标、范围、步骤、风险和验证,模板(见 docs/exec-plans/templates.md)还要求填写执行上下文(Agent Name、Model、Environment),其中环境使用 sw_vers -productVersion 和 xcodebuild -version 记录。
docs/histories/README.md 则规定:执行任务产生仓库差异时,在 YYYY-MM/ 使用 template.md 记录结果;没有差异时不创建空记录。历史记录与计划共用 YYYY-MM-DD-<slug>.md 文件名,同一任务共享 slug 并跨轮复用,slug 使用小写 kebab-case,完整的标准标识可保留点号(如 release-0.1.1),但不使用空格、下划线、大写字母、斜杠、反斜杠或冒号。
外部 Skill 资产:可离线复现的受管快照
docs/agents/skills.md 描述了 Easydict 管理外部 Skill 的机制:Easydict 直接从仓库运行共享 Skills,skills-lock.json 登记的目录是外部权威内容的完整项目快照,可离线读取和运行;lock 记录来源、ref、入口路径和内容哈希,通过重算检查本地漂移。普通任务不得修改受管快照或手工调整 hash。
.agents/skills/ 目录中可以看到完整的 Skill 资产:通用 Git、Review 和交付算法由受管 Skill 维护(如 review、review-pr、submit-pr、git-commit、worktree-rebase-merge、code-simplifier),而 release-easydict 是不进入 lock 的项目专属 Skill。.claude/skills 指向 .agents/skills,不是独立副本。
应用架构:源码布局与运行时边界
docs/design-docs/application-architecture.md 记录应用支持 macOS 13.0 及更高版本,并给出源码布局:
Easydict/
├── App/ # 入口、资源、plist、本地化
├── Swift/
│ ├── Feature/ # 产品功能和操作流程
│ ├── Model/ # 共享数据模型
│ ├── Service/ # 翻译和 AI 服务提供商
│ ├── Utility/ # 事件监视器和跨功能辅助工具
│ └── View/ # 共享 SwiftUI 和面向 AppKit 的视图
└── objc/ # 遗留 Objective-C 实现
EasydictTests/ # 单元测试和行为测试
Easydict.xcodeproj/ # Xcode 工程和共享 scheme
Easydict.xcworkspace/ # workspace 和 SwiftPM 集成
.agents/skills/release-easydict/ # 发布、签名、打包和 appcast 流程
运行时边界包括:应用入口和共享状态位于 Easydict/App 及相关的 Swift 功能模块;翻译服务提供商在 Easydict/Swift/Service 下实现特定服务的请求和响应解析(可以看到 OpenAI/、Gemini/、DeepL/、Google/、Bing/、Tencent/、Baidu/、Ali/、NiuTrans/、Caiyun/、Volcano/、Youdao/、Apple/ 等目录);Easydict 自主管理的本地文件通过 Utility/AppPathManager 统一定位,其目录布局、迁移和日志导出边界见 docs/design-docs/app-path-management.md。测试应在最窄的稳定边界验证具体行为,避免与视图实现细节耦合。
从入口到落地:一条完整的执行链路示例
将上述规则串联起来,一个典型的高风险执行任务会经历如下链路:
- 收到执行类请求后,Agent 确认存在写入授权,进入执行模式,从"执行前"开始;
- 依据任务路由读取对应专题规则(如修改 Swift 代码则读取 docs/agents/coding-guidelines.md),并读取 docs/exec-plans/README.md 与 docs/histories/README.md 判断治理要求;多步骤、跨模块或高风险任务在
docs/exec-plans/active/按模板创建计划; - 按编码规范完成修改,运行与风险匹配的验证(
xcodebuild build或xcodebuild test,必要时配合-only-testing精确定位),同时运行git diff --check等非 Xcode 检查; - 生产代码、复杂逻辑或跨模块变更通过
review技能审查,修复有效 finding 后重新验证; - 更新 history 并归档 plan,验证与 Review 通过后创建本地提交;push 或 PR 等外部写入仅在用户明确要求时执行。
这条链路同时服务于仓库的两类读者:对人类维护者而言,它是可审计、可复现的开发纪律;对 Agent 而言,它把"安全修改这个复杂仓库"拆解成一组边界明确、证据可追踪的步骤。
小结
Easydict 的 AGENTS.md 入口文档以极小的篇幅定义了完整的 Agent 协作契约:双任务模式划分读写边界,执行模式四步工作流保证"计划—实现—验证—审查—交付"全链路可追踪,任务路由表则把每类任务精确导向唯一权威文档。这种"入口精简、专题深挖、链接导航、相对路径引用"的文档治理模式,加上 docs/exec-plans/ 与 docs/histories/ 提供的计划与历史记录机制,构成了一个既适合人类维护者审阅、也适合 Agent 自动执行的仓库协作体系。对于希望深入 Easydict 源码、构建调试或贡献代码的开发者,从 AGENTS.md 出发,按任务路由逐层下钻,是理解并遵守该项目开发纪律的最短路径。