Easydict 仓库 Agent 协作规则体系GPT-6 Astra 指令适配与 Terra 测试委派实战解析【免费下载链接】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/EasydictEasydict 是一个使用 Swift/Objective-C 开发的 macOS 词典翻译应用同时也是一个深度工程化的Agent 协作仓库仓库根目录的AGENTS.md是 Agent 任务的唯一入口配合 plan、history、skill 与测试子代理形成了完整的规则驱动交付体系。本文基于 2026-09-06 的变更历史记录 2026-09-06-astra-agent-rules.md 及其配套执行计划完整复盘本次参考 GPT-6 Astra 官方建议适配 AGENTS.md 与文档规则、并新增 Terra 测试子代理的治理改造包括请求语义判定、操作级保护状态、测试文档合并、skill 冲突修订以及受限验证的完整边界。读者将从中理解如何把指令遵循、自主完成、委派、表达与验证的最佳实践落到一套可维护、可验证的仓库规则体系中以及如何在无法暴露 custom agent 的运行时里用显式模型参数完成可信的委派验证。任务背景为什么要参考 GPT-6 Astra 建议重写 Agent 规则2026-09-06 的这次治理任务源于一个明确的用户请求参考 GPT-6 Astra 官方建议检查并适配根目录AGENTS.md与文档规则。用户批准了完整方案并额外要求合并测试文档、新增一个使用gpt-5.6-terra编写测试和运行验证的子代理。官方建议的采用范围被明确记录在仓库的参考资料目录中。查看 astra-agent-guidance.md 可以看到该文件只承担来源证据单一职责状态标记为历史参考原采用范围限定为官方 Prompting best practices 中的指令遵循、自主完成、委派、表达和验证五类建议文件末尾明确声明本文只保留来源证据当前行为以根AGENTS.md路由的现行规则为准。这一点是理解整套治理体系的关键参考资料目录docs/references/只提供证据不定义执行规则。规则的唯一现行来源是根目录 AGENTS.md其余专题文档全部通过相对链接按需加载。docs/references/README.md对此的表述是参考资料只提供证据不定义 Easydict 的执行规则Skills 的来源基线与同步命令由docs/agents/skills.md统一维护。配套的执行计划 2026-09-06-astra-agent-rules.md 记录了任务的完整授权轮廓意图模式implementation交付授权auto-local-commit安全状态normal用户在两轮修订方案后明确要求执行tester 使用gpt-5.6-terra high允许修改路径被精确圈定AGENTS.md、docs/agents/、docs/exec-plans/README.md、docs/exec-plans/templates.md、docs/histories/README.md、docs/references/、.codex/agents/tester.toml、.agents/overrides/README.md以及git-commit、review-pr、release-easydict三个 skill 的SKILL.md非目标明确列出不修改产品、上游镜像、历史记录或远程状态不改变现有提交和 PR 固定格式。变更一请求语义、跨轮约束与操作级保护状态本次改造的第一个核心问题是消除请求判定环节的歧义。原规则在什么是有效用户指令、指令可以跨多少轮、什么算完整语义上表述不清会导致像 Astra 这类对指令边界敏感的模型过早暂停或误判。history 记录对应的变更条目是明确用户有效指令优先级、跨轮限制和完整语义判定区分分析与工作流准备副作用将保护状态限定到具体操作而不是笼统地保护整个 Git 状态同时保留 staged 交付、范围内修复与 history 补齐路径。落实到现行 AGENTS.md 中可以看到这些语义已经沉淀为通用规则授权不可假设无法确认修改授权时保持只读从计划模式转入执行模式后从执行前开始用户指令优先于一切用户的禁止、范围和顺序要求优先push、创建 Pull Request、发布及其他外部写入仅在用户明确要求时执行文档采用单一职责现行规则文档单一职责跨职责使用链接不复制条款文档使用相对仓库路径不提交机器本地绝对路径历史记录不构成默认约束历史记录与设计文档只在被当前任务明确采用时才构成约束。AGENTS.md还保留了清晰的双任务模式划分计划模式只读不写用户要求方案、分析、解释或评估时只读取和检查现状并给出答复不修改文件、Git 或外部服务执行模式则按执行前 → 实现与验证 → Review → 交付四步推进。这与 Astra 建议中的自主完成和表达要求一一对应每一步都有明确的完成条件避免 Agent 在不该动手的时候动手。变更二合并测试文档并新增 Terra/tester 配置第二个核心变更是测试职责的收敛与委派边界的建立。history 记录合并测试文档新增 Terra/high tester 配置统一测试价值、构建条件和委派边界tester 只处理分配的测试范围主 Agent 负责生产修复、共享构建与最终交付。从执行计划的风险与决策一节可以还原这次设计的取舍逻辑授权与安全状态分开表达——安全状态只描述当前执行环境的危险等级不代表授权范围验证失败可以修复但不能跳过——防止 Agent 在验证失败时偷偷绕过保留大变更构建阈值——避免把纯治理文档检查扩展为应用测试即治理文档类改动不强制跑 Xcode 全量测试应用代码改动才需要两者风险等级不同。任务执行时gpt-5.6-terra测试子代理在临时目录编写并运行标准库脚本完成了 3 项检查详见下文验证体系一节临时脚本不加入仓库。需要特别说明的是history 中记录的.codex/agents/tester.toml属于任务产物Custom Agent 配置在当前仓库镜像快照中并未包含.codex/目录这符合custom agent 配置属于运行时/本地环境而非仓库跟踪内容的定位——从源码结构看仓库实际跟踪的 agent 资产统一收敛在 .agents/skills/ 下每个 skill 自带agents/openai.yaml、references/、scripts/、tests/目录。变更三修订 git-commit、review-pr、release-easydict 三个 skill 的冲突第三部分是对直接冲突的 skill 进行修订。history 记录修订提交、review 和发布 skill 的直接冲突同步入口、overlay、语言和计划模板。以 git-commit/SKILL.md 为例可以直观看到本次修订后保护状态限定到具体操作是如何落地的。该 skill 的范围与 Git 状态保护一节用一张决策表精确规定了每种 Git 状态下的暂存动作情况暂存动作已有索引不运行git add只提交既有 staged 内容超出请求范围时停止显式交付、空索引、限定路径一次git add -- selected-paths显式交付、空索引、未限定路径未禁止暂存且非 staged-only 时在仓库根目录一次git add .宿主授权自动提交一次git add -- expected-commit-paths禁止git add .同时它设定了明确的停止条件范围无法证明、出现冲突或漂移、权限被拒、提交前/后校验失败、hook 改写结果或统计不一致时保留现场并报告具体阶段不自动扩大暂存、重试写入、amend 或清理用户状态。这些条款正是对保护状态限定到具体操作的落地不笼统地禁止一切 Git 操作而是把每个操作读 HEAD、读 status、暂存、提交、校验拆开逐项给出允许与禁止的边界。skill 的 frontmatter 也体现了入口即边界的设计description明确用于明确的提交交付分支集成使用 worktree-rebase-merge不 push从模型读取 skill 的第一刻就圈定了职责范围。设计意图保留自动本地提交、history、planner 与固定交付格式本次改造的一个关键约束是不推翻已有制度。history 的设计意图一节写道保留自动本地提交、history、planner 以及固定交付格式消除会令 Astra 过早暂停的歧义。tester 只处理分配的测试范围主 Agent 负责生产修复、共享构建与最终交付。从执行计划还能看到更细的授权设计用户在两轮修订方案后明确要求执行——多轮确认后才进入执行这与 Astra 建议中指令遵循的要求一致允许修改路径被逐条列出防止 Agent 越界改动产品代码或历史记录。这套制度在现行仓库中仍然完整可见plan 生命周期docs/exec-plans/README.md 规定多步骤、跨模块或高风险的执行任务在active/使用 templates.md 创建计划完成后按文件名月份移动到completed/YYYY-MM/模板中的必填字段、章节和顺序不可删改。history 记录docs/histories/README.md 规定执行任务产生仓库差异时在YYYY-MM/使用 template.md 记录结果没有差异时不创建空记录记录与计划共用YYYY-MM-DD-slug.md文件名同一任务共享 slug 并跨轮复用。plan 模板docs/exec-plans/templates.md 要求记录 Agent Name、Model、Environmentsw_vers -productVersion与xcodebuild -version并区分允许修改路径/用户限制/非目标/验收标准——这为验证阶段的证据可复现提供了基础。验证体系从静态检查、Terra 受限验证到独立场景走读本次改造最值得借鉴的部分是它的分层验证策略。history 的验证一节记录了完整的证据链静态结构检查三个修改后的 skill 通过quick_validate.py最后修改的git-commit也复验通过。空白错误检查git diff --check通过未发现空白错误。Terra 子代理独立验证在临时目录编写并运行标准库脚本3 项检查全部通过——两个 Agent TOML 的配置契约变更 Markdown 的本地链接目标防止相对链接失效有效入口已移除旧测试文档引用。独立场景走读覆盖规划、跨轮禁止提交、staged、失败修复、history 限制、只读 review、发布本地计划和 tester 构建协调未发现规则冲突主 Agent 已复核脚本与证据。执行计划在验证与完成条件中进一步明确了证据的区分原则区分静态检查、场景走读、显式 Terra 调用和 custom agent 注册结果——四种验证方式的证据强度不同不能混为一谈。这直接对应到 history后续事项中的诚实声明当前运行时未暴露 tester custom agent使用 gpt-5.6-terra high 显式回退调用成功。未验证角色自动发现或一般模型行为未运行 Xcode 或远程工作流。也就是说验证只证明了显式调用 tester 指令这条路可行不证明角色自动发现可用同时因为是纯治理文档改动未运行 Xcode 全量构建这与保留大变更构建阈值的决策一致。这种做到哪一步就说哪一步的记录方式本身就是 Astra 建议中验证环节的最佳示范。后续演进从本次适配到文档精简2026-09-06 的适配并非终点。2026-09-13 的后续记录 2026-09-13-astra-agent-docs-follow-up.md 显示在通用 Skills 升级到 v0.4.0 后仓库继续参考 GPT-6 Astra 建议精简Agent 文档将计划模式、执行模式、自动本地提交和外部写入边界合并到根AGENTS.md删除所有任务都要额外读取的docs/agents/task-modes.md合并build-and-test.md中重复的 Xcode 验证、测试范围和 DerivedData 说明将release-easydict的详细 Release 生命周期、状态、内容选择和恢复流程集中到按需读取的references/release-workflow.md根 Skill 只保留动作路由、授权边界和完成条件。这印证了本次适配建立的核心原则——根入口提供最小决策边界专题文档按需加载渐进披露细节——并最终沉淀为现行 AGENTS.md 的任务路由表构建测试、编码规范、plan/history、参考资料、外部 Skills、应用架构、用户文档各有单一入口Agent 只读取当前任务需要的专题规则。总结一套可验证、可演进、边界清晰的 Agent 规则治理范式回看这次 Astra 规则适配它解决的核心问题可以概括为四点语义无歧义明确用户指令的优先级、跨轮限制与完整语义判定区分分析与写入副作用保护粒度化把保护状态从整仓只读细化到具体操作允许/禁止保留 staged 交付、范围内修复等合法路径职责单一化测试合并为一个文档、tester 只处理分配范围、主 Agent 负责生产修复与最终交付避免责任重叠验证分层化静态检查、场景走读、显式 Terra 调用、custom agent 注册结果四类证据分开记录结论不超过证据边界。对于任何想为仓库建立或改进 Agent 协作规则的团队Easydict 这套根 AGENTS.md 唯一入口 plan/history 生命周期 skill 边界声明 分层验证 诚实记录验证边界的组合是一份可直接参考的工程模板。想深入了解完整规则建议从 AGENTS.md 入口开始沿任务路由逐个阅读 docs/agents/、docs/exec-plans/README.md、docs/histories/README.md 与 .agents/skills/ 下的 skill 定义再对照 astra-agent-guidance.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），仅供参考