Easydict Agent 规则职责拆分与 planning 边界实战指南

桌面应用AI 应用【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址https://gitcode.com/gh_mirrors/ea/Easydict点击查看免费下载本文以 Easydict 仓库 2026-08-25 的 Agent 治理重构history2026-08-25-agent-rule-structure-port.md为主线完整解读如何将散落在单一大文档中的 Agent 规则按请求边界、执行安全、Git 工作流、文档治理、回复表达五个职责拆分到独立文档并落地 planning 的只读语义、Mutation Gate 与 active/completed 计划生命周期。读完本文你将掌握一套可复制的 Agent 规则治理方法并能在 Easydict 当前入口路由AGENTS.md与执行计划体系docs/exec-plans/README.md中定位每一个职责边界。一、变更背景为什么要把 Agent 规则拆开在本次重构之前Easydict 的 Agent 规则集中承载于单一文档中请求解析、执行安全、Git 交付、文档治理等多类职责混在一起。随着项目引入 PR review、Planning 子代理、submit-pr技能与 Xcode 工程边界等 Easydict 专属规则单文档的维护成本与读取成本快速上升。本次变更对应 history 2026-08-25-agent-rule-structure-port.md完成了三件事语义移植完整移植 Scoco 提交1a933fff9、8ac8d066c和bf029bd1f的 Agent 规则语义而非机械复制文件职责拆分将请求边界、执行安全、Git 工作流、文档治理和回复表达拆分到 docs/agents/ 的独立文档并同步更新 AGENTS.md、目录 README 与规则入口边界明确明确 planning 的只读语义、Mutation Gate、active/completed 计划生命周期以及 Easydict 的submit-pr、PR review、Planning 子代理和 Xcode 文档边界。本次修改仅涉及 Agent 规则、执行计划模板、完成计划和 history产品代码、测试、Xcode 工程、运行时资源和外部服务均未改动。二、当前仓库的 Agent 规则结构2.1 唯一任务入口AGENTS.md重构后AGENTS.md 成为 Agent 的唯一任务入口只承担入口 路由职责详细规则只在对应专题文档中维护。其结构包含三个层次任务模式区分计划模式只读与执行模式可写见下文第三节通用规则跨模式约束如授权边界、回复语言、文档单一职责、相对路径要求任务路由按任务类型指向对应专题文档。2.2 专题文档路由AGENTS.md 中任务路由一节给出了清晰的按需加载规则——Agent 只读取当前任务需要的专题规则任务类型目标文档构建、测试、工程文件、Xcode 验证docs/agents/build-and-test.md跨语言代码质量、Swift/ObjC/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/这种唯一入口 按需路由的设计使根 AGENTS.md 保持短小可扫描同时每个专题文档聚焦单一职责。配合通用规则中的现行规则文档单一职责跨职责使用链接不复制条款文档使用相对仓库路径不提交机器本地绝对路径可避免规则文本在多个文档间漂移。2.3 职责拆分的演进脉络值得注意的是本次拆分并非一次到位的终点后续演进见 2026-08-26-agent-documentation-structure-port.md进一步将 AGENTS.md 收敛为唯一入口移除了repository-guide.md的二次路由并把文档生命周期归入docs/agents/README.md。阅读本文时应将 08-25 的职责拆分与 08-26 的入口收敛合并理解才能看到当前仓库的完整治理形态。三、任务模式与 planning 只读边界3.1 计划模式只读按 AGENTS.md 的定义用户要求方案、分析、解释或评估时只读取和检查现状并给出答复不修改文件、Git 或外部服务。计划模式是一个纯只读边界Agent 可以读取仓库、搜索源码、分析现状但禁止任何写入动作。这一点正是本次移植的核心语义——planning 完全只读只有获准 implementation 后才创建 active 计划。3.2 执行模式四步流程执行模式按编号流程推进对应 2026-09-17-split-task-modes.md 的后续整理执行前首次写入前读取任务路由要求的专题规则任何可能产生仓库差异的任务都必须读取 docs/exec-plans/README.md 与 docs/histories/README.md并按规则判断 plan 与 history实现与验证完成范围内修改并运行风险匹配的验证失败则修复并重新验证Review生产代码、复杂逻辑、跨模块或高风险变更在验证通过后使用review技能审查纯文档及简单低风险变更除外交付更新 history完成并归档已有 plan必要验证和适用的 Review 通过后自动创建本地提交用户明确要求不提交或没有差异时除外。3.3 模式切换与 Mutation Gate通用规则明确了模式切换的语义无法确认修改授权时保持只读从计划模式转入执行模式后从执行前开始。从执行前开始意味着方案讨论结束后转入实际执行时必须重新检查任务范围和文档治理要求——这是防止 Agent 将执行视为计划讨论简单续接、进而跳过 plan 或 history 的关键闸门。Mutation Gate 即指这一从只读到可写的授权闸门只有经过确认的写入授权implementation 模式才会放行文件修改在执行计划 2026-08-25-agent-rule-structure-port.md 的风险与缓解中也明确记录了确认三提交范围后执行 Mutation Gate的过程。3.4 外部写入的授权边界通用规则进一步限定push、创建 Pull Request、发布及其他外部写入仅在用户明确要求时执行用户的禁止、范围和顺序要求优先。同时要求回复使用用户当前请求的语言已有文档保持原语言代码标识、API 名称、命令、路径与固定输出契约保留原文。四、计划生命周期active / completed4.1 目录约定docs/exec-plans/README.md 定义了执行计划目录的语义active/进行中的计划completed/YYYY-MM/按计划文件名月份归档的已完成计划templates.md新计划模板。多步骤、跨模块或高风险的执行任务在active/使用模板创建计划完成后按文件名月份移动到completed/YYYY-MM/。当前 docs/exec-plans/active/swift-migration.md 是唯一的长期 Objective-C-to-Swift 迁移路线图不适用按任务命名规则作为长期文档常驻 active 目录。4.2 计划模板的必填骨架新计划必须保留模板docs/exec-plans/templates.md中的必填字段、章节和顺序章节核心内容文件头状态active、创建日期、负责人、关联 Issue/PR文件名遵循YYYY-MM-DD-slug.md执行上下文Agent Name、Model、Environmentsw_vers -productVersion、xcodebuild -version背景问题、当前状态、为什么需要这项工作目标与范围目标结果、允许修改路径、同任务 history、用户限制、非目标、验收标准工作计划按顺序执行的工作列表风险与决策兼容性/数据/运行时/发布风险、重要选择及原因进度待完成工作的 checkbox 列表验证执行过的检查、结果与未运行的检查完成条件归档到completed/YYYY-MM/前必须满足的条件本次重构正是为模板新增了请求语义与计划生命周期回归案例使模板能反向约束 Agent 的规划行为。4.3 命名与 slug 规则docs/histories/README.md 规定history 与 plan 共用YYYY-MM-DD-slug.md文件名同一任务共享 slug 并跨轮复用。slug 使用小写 kebab-case完整标准标识可保留点号如release-0.1.1、upgrade-skills-v0.3.8不使用空格、下划线、大写字母、斜杠、反斜杠或冒号。这保证了 plan 与 history 的可追溯配对。五、从计划到落地本次重构的完整执行记录5.1 执行计划中的任务契约本次重构的完整执行计划归档于 2026-08-25-agent-rule-structure-port.md其任务契约清晰展示了 Easydict 的执行计划规范任务模式implementation用户目标将三个 Scoco Agent 规则提交完整适配到 Easydict允许修改路径AGENTS.md、docs/agents/、docs/exec-plans/templates.md、本计划及对应完成历史预期交付物职责清晰的 Agent 文档、完整的 planning 只读边界、更新后的入口路由和验证记录验收标准三个提交的语义均被保留Easydict 专属规则不丢失文档链接和格式检查通过。计划还记录了自动提交状态eligible → committed与输入来源分类用户明确请求、仓库规则、附件/引用材料、仅作证据的内容这正是请求边界治理在计划层的形式化表达。5.2 风险与缓解策略执行计划中记录的三项风险与缓解体现了本次拆分的核心方法论风险缓解措施机械复制 Scoco 文件会覆盖 Easydict 专属规则按职责迁移语义逐项保留目标仓库的 PR、Git、skill 和 Xcode 条款planning 任务模式与计划文件生命周期出现矛盾同步检查请求边界、执行安全、文档治理、任务工作流和模板新增文档的相对链接或路由不完整执行本地链接、路由、职责唯一归属和绝对路径检查5.3 决策记录计划中的决策记录说明了三次关键取舍按用户确认完整包含三个提交不采用仅移植后两个提交的范围采用职责拆分语义适配不直接复制 Scoco 的完成计划和历史事实保留 Easydict 的 PR review、Planning 子代理、submit-pr 参数和 Xcode 工程边界并将详细规则分别归档到职责文档。六、验证方式与质量门禁6.1 本次变更的验证history 2026-08-25-agent-rule-structure-port.md 记录的验证包括git diff --check通过完成文档尾随空白、相对链接目标、入口路由和关键语义静态检查未运行xcodebuild——本次变更不涉及源码或 Xcode 工程。这体现了 Easydict 的验证分级原则验证与任务风险匹配纯文档治理变更不需要走完整构建链路。6.2 文档治理的通用检查结合 docs/histories/README.md 与后续 2026-08-26-agent-documentation-structure-port.md 的实践Easydict 的文档级验证通常覆盖新增 Markdown 无尾随空白活跃 Markdown 相对链接目标存在、标题锚点可解析入口路由无死链如已删除文件不再被活跃规则引用无源项目专属规则泄漏关键语义静态确认任务模式、Mutation Gate、history 门禁、精确暂存、禁止默认远程操作。七、可复用的实践要点从本次重构中可以提炼出一套通用的 Agent 规则治理方法论职责单一每条规则只在一个文档中维护跨职责使用链接而非复制条款AGENTS.md 只保留入口与路由只读边界显式化planning 严格只读写入授权通过 Mutation Gate 显式确认模式切换后从执行前重新走治理流程生命周期闭环plan 从模板创建active到验证后归档completed/YYYY-MM/history 与 plan 共享 slug 配对形成可追溯闭环验证分级文档变更与代码变更采用不同强度的验证xcodebuild只在涉及源码或工程时运行移植而非复制从上游移植规则时按职责迁移语义逐项保留本项目专属条款防止机械复制覆盖本地规则。这套方法已在 Easydict 的 Agent 文档体系中持续演进——docs/histories/ 中 2026-08 至 2026-09 的系列记录如 2026-08-27-planning-agent-entry.md、2026-09-17-split-task-modes.md展示了从拆分、收敛到任务模式细化的完整演化路径可作为设计自有 Agent 规则体系的直接参考。赞分享桌面应用AI 应用【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址https://gitcode.com/gh_mirrors/ea/Easydict点击查看免费下载相关推荐Easydict Agent 规则职责拆分与 Planning 只读边界移植实践Easydict Agent 规则职责拆分与 Planning 只读边界移植实践 Easydict 仓库通过一次代号为 agent rule structure桌面应用AI 应用Easydict Git 交付策略精简项目规则与受管 Skill/TOML 的职责边界划分Easydict Git 交付策略精简项目规则与受管 Skill/TOML 的职责边界划分 导读 本文基于 Easydict 仓库 2026 09 10 的历桌面应用AI 应用Easydict Agent 文档体系重构实践按职责分离规则、架构、任务记录与公共文档Easydict Agent 文档体系重构实践按职责分离规则、架构、任务记录与公共文档 Easydict 在 2026 08 09 完成了一次面向 AI Ag桌面应用AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考