Easydict 的 Planning 子代理启动入口迁移Agent 文档治理重构执行方案解析【免费下载链接】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 仓库中一份已完成的执行计划docs/exec-plans/completed/2026-08/2026-08-27-planning-agent-entry.md展开剖析该项目如何把上游 Scoco 仓库的 Planning 委派启动契约语义移植到自身 Agent 文档结构中。读完本文你将理解 Easydict 如何通过AGENTS.md、request-boundary.md、planner.toml等治理文档的拆分与重组实现只读 planner 委派、回退机制、主 Agent 责任的统一边界以及一个执行计划从任务契约、适配决策到验证归档的完整落地流程。任务背景为什么需要迁移 Planning 启动入口Easydict 使用AGENTS.md作为 Agent 的唯一任务入口详细规则只在专题文档维护。在本次任务之前仓库中的 Agent 治理文档存在职责混杂的问题docs/agents/skills.md同时承载了外部 Skill 资产说明、Planning 委派规则、发布release、PRsubmit-pr、OpenAI 入口和本地 overlay 路由等多种语义。该任务的源头是 Scoco 仓库的提交2b6ff71a1350dd5d731ac360754271a65d5ca1c9其目标是将 Planning 子代理的委派启动契约适配到 Easydict 的 Agent 文档结构且明确不直接 cherry-pick 来源提交而是按 Easydict 的文档治理规范重新组织语义。从当前仓库快照看AGENTS.md中的任务路由仍将外部 Skills 和同步边界指向docs/agents/skills.md而docs/agents/目录下仅有coding-guidelines.md与skills.md两个文件——这正对应执行计划所描述的迁移前状态读者可以对照现状理解迁移的切入点。任务契约与变更边界执行计划首先定义了严格的任务契约这是 Easydict 执行计划模板的必备结构模板规则见docs/exec-plans/README.md任务模式implementation用户目标将 Scoco 的 Planning 委派启动契约适配到 Easydict 的 Agent 文档结构允许修改路径AGENTS.md、docs/agents/README.md、docs/agents/request-boundary.md、docs/agents/skills.md、.codex/agents/planner.toml、本计划、同任务 history禁止动作不直接 cherry-pick不修改产品源码、测试、Xcode 工程、运行时资源或远程 Git 状态不执行 fetch、pull、rebase、merge 或 push计划还记录了初始 Git 快照初始分支dev、initial_head为b69e2bfec3a3504ad133a309a17ed32907a3b156、暂存区为空、工作树干净、无冲突为后续验证提供可回溯的基准。这一契约 快照的写法保证了执行过程中任何差异都可被精确定位。迁移目标与验收标准计划给出了五条可验证的验收标准构成了整个迁移的目标全景request-boundary.md成为每个任务的 Planning 启动契约统一规定只读 planner 委派、回退和主 Agent 责任AGENTS.md直接区分 Planning 子代理、具体 Skill 和 Easydict 专属路由planner.toml适用于所有 planning 任务不再使用非简单 planning表述同时保留现有模型、推理强度和只读沙箱删除职责混杂的docs/agents/skills.md前迁移其仍有效的 Easydict Skill、OpenAI 入口和 overlay 路由不丢失release-easydict、submit-pr或技术图规则docs/agents/README.md独立维护应用内置 Agent、运行时资源和后端契约边界不复制 Scoco 专属目录或同步脚本。其中关于 planner 的配置语义固定模型、推理强度、只读沙箱可追溯到更早的docs/exec-plans/completed/2026-08/2026-08-23-planning-subagent.md该计划为项目新增只读plannercustom agent固定使用gpt-5.6-sol模型、xhigh推理强度并通过sandbox_mode与文档规则双重约束禁止 planning 写入。本次迁移保留了这些配置只将适用面从非简单 planning泛化为所有 planning 任务。实施步骤详解计划将整个迁移拆解为五个顺序步骤迁移委派规则将 Planning 委派、回退和只读约束从docs/agents/skills.md移到docs/agents/request-boundary.md使启动契约独立成文更新根入口更新AGENTS.md的启动契约和直接路由把仍需发现的 Easydict Skill 入口补齐整理边界并清理旧文档将应用内置 Agent 边界整理到docs/agents/README.md更新planner.toml删除旧的docs/agents/skills.md记录与验证创建同任务 history运行文档、TOML、链接、范围和格式验证归档本计划到docs/exec-plans/completed/本地交付在验证通过且 Git 门禁仍满足时只暂存本任务路径并创建一个本地 Angular-style 双语提交不执行 push。步骤 5 中提到的Angular-style 双语提交与docs/agents/skills.md中描述的受管 Skill 约定一致——v0.6.3 强制双语提交本地语言与英文标题分别使用对应语言并保持相同的 Angular type、scope 与 breaking 语义。由此可以看到仓库治理文档之间通过链接互相引用、保持语义一致而不是复制条款AGENTS.md通用规则明确现行规则文档单一职责跨职责使用链接不复制条款。Easydict 适配决策不机械照搬来源迁移不是简单复制计划明确列出了适配决策来源的Scoco/Swift/Feature/AIChat/Agent/Docs/、agent-home、ScocoBackend/Docs和sync-agent-docs在 Easydict 中不存在不移植Easydict 的docs/agents/skills.md比来源版本多出发布、PR、OpenAI 入口和本地 overlay 说明这些语义要迁移到目标仓库现有入口不能机械删除后丢失已有 history 和 completed plan 中对旧docs/agents/skills.md的引用属于历史事实不批量改写但活动治理文档不得残留失效引用。这一决策体现了治理迁移的通用原则来源实现中的执行事实具体产品目录、运行时资源、后端同步脚本不属于通用契约不应带入库而本地已有的语义资产必须逐条盘点后安置到新结构中。同任务 historydocs/histories/2026-08/2026-08-27-planning-agent-entry.md记录了同样的适配结论可作为交叉验证。风险与验证体系计划对可能的风险做了前置识别与缓解设计风险缓解措施删除skills.md造成路由遗漏逐条迁移盘点、根入口扫描、关键路径存在性检查静态规则正确不等于宿主运行时一定启动 planner本任务只验证文件和配置不伪装成 runtime smoke test只改文档却误触发构建仅修改 Agent 文档和 TOML不运行xcodebuild完成记录中列出的已验证项包括git diff --check空白与差异格式检查planner TOML 的tomllib解析活动文档失效引用扫描Easydict 专属路由扫描Markdown 相对链接检查精确变更范围复核这套验证组合与仓库其他 Agent 治理任务的验证方式保持一致——例如docs/exec-plans/completed/2026-08/2026-08-21-agent-request-boundary.md同样采用git diff --check与针对性rg检查且都注明未运行xcodebuild因为没有修改编译源码、测试或 Xcode 工程元数据。这从侧面印证了 Easydict 的一个治理原则静态文档/配置任务的验证边界应与变更范围严格匹配不为了形式而执行无关的构建。与仓库现状对照迁移前结构一览结合当前仓库快照可以观察到执行计划所针对的迁移前结构AGENTS.md的任务路由按专题拆分build-and-test.md、coding-guidelines.md、exec-plans/README.md、references/README.md、skills.md、application-architecture.md、docs/user-docs/其中skills.md同时承担了外部 Skills 和同步边界职责docs/agents/skills.md内容分为背景与设计操作规则来源基线tisfeng/skills来源基线fireworks-tech-graph四部分包含skills-lock.json快照机制、sha256 内容哈希约定、npx -y skills1.5.25 add ...安装命令等实操细节docs/exec-plans/README.md规定多步骤、跨模块或高风险任务在active/按templates.md创建计划完成后按文件名月份归档到completed/YYYY-MM/——本计划归档到completed/2026-08/正是该规则的落地。迁移完成后skills.md中仍有效的 Skill 语义会分流到AGENTS.md根路由与docs/agents/README.md应用内置 Agent、运行时资源与后端契约边界而 Planning 委派语义集中到docs/agents/request-boundary.md形成根入口精简路由 专题文档单一职责的最终结构。总结从本执行计划可借鉴的治理模式2026-08-27-planning-agent-entry.md虽然是一份针对 Agent 文档的小范围执行计划但它完整示范了 Easydict 治理文档变更的标准化流程可提炼为可复用的模式先立契约再动手任务模式、允许修改路径、禁止动作、初始 Git 快照四要素缺一不可保证变更可审计语义迁移而非文件搬运以不丢失release-easydict、submit-pr、技术图规则为底线逐条盘点旧文档中的有效语义再安置到新入口验收标准先行每条目标都有可静态验证的验收描述TOML 可解析、路由存在、引用无失效验证与范围匹配文档/配置变更采用git diff --check、tomllib解析、链接扫描等静态手段不越界运行构建或伪装运行时验证历史事实与活动治理分离已归档文档中的旧路径引用保留为历史事实只确保当前活动治理文档不残留失效引用。对于正在建设 Agent 协作文档体系的项目这套契约驱动、语义迁移、静态验证、边界清晰的方法论具有直接的参考价值相关模板与归档规则可进一步查阅docs/exec-plans/templates.md与docs/histories/README.md。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考