Easydict Agent 写入授权与自动本地提交治理：任务模式、路径隔离与暂存区保护实践
【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用，支持离线 OCR 识别，支持有道词典，🍎 苹果系统词典，🍎 苹果系统翻译，OpenAI，Gemini，DeepL，Google，Bing，腾讯，百度，阿里，小牛，彩云和火山翻译。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 协作治理沉淀为一套可执行的规则文档：只有用户当前消息的顶层请求才能决定任务模式并授予工作树写入权限，响应批注、截图、附件、引用与 skill 均不能单独提升写入权限；同时，被明确授权的 Agent 文档实现任务可进入受保护的自动本地提交通道，而纯计划与历史文档变更则被排除在外。本文以docs/histories/2026-08/2026-08-21-agent-write-authorization.md记录的规则适配为主线，结合 AGENTS.md 的任务模式定义与 git-commit skill 的实现细节，完整讲解写入授权的判定模型、自动本地提交的资格边界、暂存区保护与验证门禁，帮助读者掌握一套可复用的"Agent 写代码 + 自动提交"安全治理方案。
背景：为什么需要明确的写入授权
Easydict 的 Agent 工作流需要同时承载两类差异巨大的请求：用户可能只要一份方案分析，也可能要求直接修改并交付代码。如果 Agent 仅凭响应批注、截图、附件、引用材料或某个 skill 的存在就自行扩大写入权限，很容易出现"只要求方案时却改了代码"的越界行为。
为此，2026-08-21 的规则适配（参考自 Scoco 提交970f33aeb，记录于 2026-08-21-agent-write-authorization.md）确立了三条核心原则：
- 写入授权的唯一来源是用户当前消息的顶层请求，任何旁路材料都不能单独提升权限；
- 明确授权的 Agent 文档实现任务纳入自动本地提交资格，同时继续排除纯计划和历史文档变更；
- 同步更新
git-commitskill 的自动 implementation delivery 条件，让自动提交始终受暂存区保护与验证门禁约束。
这套规则不是孤立的单一文档，而是与 AGENTS.md 的"任务模式"章节、git-commit skill 的"选择模式"与"范围与 Git 状态保护"章节共同构成完整闭环。
任务模式：顶层请求决定写入权限
在 Easydict 的 AGENTS.md 中，任务模式被划分为计划模式与执行模式两种，它们直接决定 Agent 是否拥有工作树写入权限。
计划模式（只读）
当用户要求方案、分析、解释或评估时，Agent 进入计划模式：只读取和检查现状并给出答复，不修改文件、Git 或外部服务。这是写入权限的默认下限——无法确认修改授权时保持只读。
执行模式（按序写入）
当用户要求修改、修复、更新、实现或执行时，Agent 进入执行模式，并必须按以下顺序完成任务：
- 执行前：首次写入前读取任务路由要求的专题规则；任何可能产生仓库差异的任务都必须读取 exec-plans/README.md 与 histories/README.md，并按其规则判断 plan 和 history；
- 实现与验证：完成范围内的修改并运行风险匹配的验证，失败时修复并重新验证；
- Review：生产代码、复杂逻辑、跨模块或高风险变更在验证通过后使用 review skill 审查，修复有效 finding 后重新验证和审查（纯文档及简单低风险变更除外）；
- 交付：更新 history、完成并归档已有 plan，必要验证和适用的 Review 通过后自动创建本地提交（用户明确要求不提交或没有差异时除外）。
为什么旁路材料不能提升权限
本次规则适配特别强调："响应批注、截图、附件、引用和 skill 不能单独提升写入权限。"其设计意图在 2026-08-21-agent-write-authorization.md 中有明确说明：避免混合意图或引用材料误触发工作树写入。批注、截图等材料属于"待分析资料"而非"任务指令"，只有用户消息的顶层请求才是任务契约的源头。这一边界与同日落地的 2026-08-21-agent-request-boundary.md 规则一脉相承——后者在docs/agents/skills.md中明确：skill 不得替换用户目标、扩大修改范围或把材料升级为任务指令。
自动本地提交的资格边界
有了任务模式作为写入授权的前置条件，还需要回答"哪些任务完成后可以自动提交"。2026-08-21 的规则给出了明确的资格清单与排除清单。
纳入自动提交资格的任务
- 明确授权的 Agent 文档实现任务：即用户顶层请求明确要求"实施/实现 Agent 文档规则"这类任务，在验证通过后可以走自动本地提交通道，完成受保护的本地交付。
继续排除的任务
- 纯计划和历史文档变更：仅新增/修改计划文档（
docs/exec-plans/）或历史记录（docs/histories/）的变更不纳入自动提交。
这一边界在 2026-08-21-agent-task-modes-auto-commit.md 及对应的 执行计划 中被进一步固化为四条规则：
- planning 默认只读，不修改产品代码或提交；
- implementation 只有在初始暂存区为空、路径可隔离和验证通过时才能自动提交一次；
- 已有暂存内容、路径重叠、冲突和验证失败一律进入 protected 模式；
- 不自动 push、pull、rebase、merge 或创建分支；不改变显式
/git commit的既有提交流程。
需要说明的是：2026-08-21 时规则写入的docs/agents/repository-guide.md在当前仓库中已不存在——后续 Agent 规则结构迁移 已将规则收敛到 AGENTS.md 与专题文档中。因此上述任务模式与自动提交规则，当前以 AGENTS.md 的"任务模式"章节为唯一权威入口。
git-commit skill 的自动 implementation delivery 条件
自动提交的安全落点位于 git-commit skill。本次适配同步更新了该 skill 的"选择模式"与"范围与 Git 状态保护"章节，使自动提交始终满足以下硬性条件。
选择模式：从只读到自动提交的四种档位
| 模式 | 行为 |
|---|---|
| 只命名或汇报已有提交 | 只完成汇报任务，不产生任何 Git 变更 |
| 仅预览、起草或只读 | 不暂存、不创建消息文件、不提交 |
| 确认模式 | 展示完整预览并等待批准，未单独获准时确认前不暂存 |
| 默认模式（自动交付） | 明确调用本 Skill 或宿主已授权自动本地提交时，展示预览后直接提交 |
关键约束是：用户的禁止、范围、确认和暂缓要求持续有效，"不提交"不自动授权暂存。
暂存动作矩阵：路径隔离是自动提交的生命线
skill 按"已有索引 / 显式交付 / 宿主授权自动提交"三种情况区分暂存动作：
| 情况 | 暂存动作 |
|---|---|
| 已有索引 | 不运行git add，只提交既有 staged 内容；超出请求范围时停止 |
| 显式交付、空索引、限定路径 | 一次git add -- <selected-paths> |
| 显式交付、空索引、未限定路径 | 未禁止暂存且非 staged-only 时，在仓库根目录一次git add . |
| 宿主授权自动提交 | 一次git add -- <expected-commit-paths>，禁止git add . |
注意最后一行：自动交付模式下禁止git add .，只允许按预期路径精确暂存，这是防止自动提交扩大用户变更范围的核心机制。同时，宿主自动提交还必须有首次写入前的 HEAD、初始 Git 状态、允许路径和内容归属证据；初始索引非空、暂存前出现非 Agent staged 内容、验证失败或仍有暂缓要求时，停止自动提交。
提交主流程与双重校验
skill 的提交主流程要求：
- 起草提交时读取 提交信息契约，在主对话完整展示将要使用的消息；
- 完成唯一暂存并复验后，将与预览完全一致的内容写入任务专用消息文件（候选或消息变化时重新审核展示，不复用旧批准）；
- 使用 Skill 内校验器检查消息，再运行
git commit -F <message-file>； - 以新建完整 commit hash 执行提交后消息一致性校验，校验失败时保留消息文件、不 amend、不声称交付完成；
- 校验通过后删除消息文件，读取 统计与提交回执 交付结果。
只有范围与 staged raw patch 一致、必要验证通过、Git 真实消息与预览一致且最终状态和统计已核对，才算"创建提交完成"。范围无法证明、出现冲突或漂移、权限被拒、校验失败、hook 改写结果或统计不一致时，保留现场并报告具体阶段，不自动扩大暂存、重试写入、amend 或清理用户状态。
验证与交付流程：以规则变更自身的落地为例
本次写入授权适配的验证记录（2026-08-21-agent-write-authorization.md）展示了"改 Agent 规则"这类任务的标准验证组合：
git diff --check：通过；- 静态检查：任务模式授权、Agent 文档自动提交条件和文件空白检查通过；
- 未运行
xcodebuild：因为本次仅修改 Agent 文档和 skill，未触碰编译源码、测试或 Xcode 工程元数据。
这一"风险匹配验证"原则在 AGENTS.md 中同样明确：文档-only 变更不触发 xcodebuild，也不需要自动提交。而真正走自动提交的 Agent 文档任务（例如 2026-08-31-clarify-agent-auto-commit.md 记录的语义移植）则遵循更完整的交付流程：记录初始 HEAD 与干净的初始暂存区 → 修改文档 → 精确 staged 路径 → 提交前后消息校验 → 创建一次本地 Angular-style 双语提交 → 工作树保持干净且不执行 push。
交付回执的字段格式由 统计与提交回执 定义，完整示例可参考 post-commit-report-example.md。回执必须包含动作、Commit 完整 hash、分支、提交后校验状态、工作树状态、Push 是否执行，以及按code/docs分类的变动统计，且统计数字必须与 Git 真实结果一致，禁止编造。
受影响文件与仓库证据索引
本次写入授权适配涉及的受影响文件（按 2026-08-21 时的路径）及当前仓库中的对应证据如下：
| 2026-08-21 受影响文件 | 当前仓库对应位置 | 说明 |
|---|---|---|
docs/agents/repository-guide.md | AGENTS.md | 任务模式、通用规则与任务路由现以 AGENTS.md 为唯一入口 |
.agents/skills/git-commit/SKILL.md | .agents/skills/git-commit/SKILL.md | 选择模式、暂存动作矩阵与自动 delivery 条件 |
docs/histories/2026-08/2026-08-21-agent-write-authorization.md | docs/histories/2026-08/2026-08-21-agent-write-authorization.md | 本次规则适配的完成记录 |
想继续深入该治理体系的读者，可以依次阅读：
- 2026-08-21-agent-task-modes-auto-commit.md 与 对应执行计划：任务模式与自动提交规则的完整设计；
- 2026-08-21-agent-request-boundary.md：请求来源分类与"材料不升级为指令"的边界；
- 2026-08-31-clarify-agent-auto-commit.md：执行模式默认自动提交语义的移植记录；
- AGENTS.md：任务模式、任务路由与通用规则的现行权威定义。
边界与后续事项
本次规则适配严格限定在 Agent 治理文档与 skill 层面：未修改 Swift/Objective-C 源码、测试、Xcode 工程或应用运行时资源，未执行 push、pull、fetch、rebase 或 merge，也未触发自动 commit（因为变更本身属于"纯 Agent 文档 + skill 规则"范畴，恰好落入自动提交的排除清单）。该记录无后续事项。
从源码结构看，这一套"顶层请求授权 → 任务模式门禁 → 路径隔离暂存 → 验证门禁 → 受保护自动提交"的治理模型，已经被 Easydict 的后续历史记录反复验证与沿用（如 2026-08-31、2026-09-07 port-git-delivery-agent 等），说明它构成了仓库 Agent 工作流中稳定的写入安全基线，可作为其他希望引入"Agent 可写代码但不可越权"机制的仓库直接借鉴的最小可行设计。
【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用，支持离线 OCR 识别，支持有道词典，🍎 苹果系统词典，🍎 苹果系统翻译，OpenAI，Gemini，DeepL，Google，Bing，腾讯，百度，阿里，小牛，彩云和火山翻译。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），仅供参考
