Easydict Agent 提交结果统一报告基于 Git numstat 的确定性统计与回执契约实践【免费下载链接】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 工作流的工程治理改进展开当 AI Agent如 Codex在本地自动执行git commit或worktree分支集成后如何向用户输出一份可复算、可核验、格式统一的提交结果回执。文中将完整拆解git-commitSkill 的提交后报告契约、基于 Git numstat 的确定性文本行统计脚本含代码/文档互斥分类与二进制静默跳过规则以及worktree-rebase-mergeSkill 如何复用该契约补充提交来源与集成状态。读完本文你将掌握一套可迁移到任意 Git 仓库的提交结果统一报告设计统计可复算、回执字段固定、多工作流不重复维护模板。一、背景为什么需要统一提交结果报告在 Easydict 的 Agent 协作体系中AI Agent 被授权在本地执行自动提交与分支集成。改进之前的痛点有两个信息被压缩自动本地提交已经成功执行时Agent 的最终回复可能只显示短哈希和标题用户无法确认提交动作与完整提交内容跨工作流报告不一致worktree-rebase-merge另外维护了更严格的展示要求导致同一个提交在两个工作流普通提交 vs. worktree 集成中呈现的报告详细程度不一致。该问题的完整背景记录在 执行计划 与对应的 完成历史 中。其核心解法是由git-commitSkill 统一定义成功提交后的用户可见结果其他调用方如 worktree 集成流程只复用该契约并补充各自的领域事实。为什么不是简单写长一点背景中明确指出了根因——两套工作流各自维护展示模板属于典型的契约漂移。如果只是把其中一套写得更详细另一套仍然会退化为短哈希 标题。因此本次改进的核心设计原则是唯一来源single source of truthgit-commit是提交结果、统计数据和单提交实际信息的唯一格式来源只读真实数据所有回执字段必须来自 Git 真实对象git rev-parse、git show、git status等不允许 Agent 凭记忆或推断填写可复算统计变动统计由脚本从 Git 原始数据numstat计算而非 Agent 主观估计。二、任务契约目标、边界与验收标准执行计划为本次改进定义了严格的任务契约原文档对应章节用户目标统一提交后的用户可见结果并增加总变动、代码变动和文档变动三组信息。允许动作与修改路径修改仓库 Agent 指南、git-commit与worktree-rebase-mergeSkill增加统计脚本、行为测试、执行计划和完成历史允许修改路径限定为.agents/skills/git-commit/Skill 本体、脚本、测试、参考文档.agents/skills/worktree-rebase-merge/SKILL.mddocs/agents/repository-guide.md本执行计划和完成历史。预期交付物唯一提交后报告契约确定性文本行统计可复算可复用的提交说明。验收标准统计可复算行为测试和静态检查通过。目标清单原文档原文要点由git-commit统一定义成功提交后的用户可见结果明确区分本次创建提交与复用源分支已有提交展示完整提交哈希、完整实际提交信息、工作树状态和 push 状态展示可复算的总变动、代码变动和文档变动文本行数静默忽略二进制文件不在最终结果中显示二进制统计。非目标边界声明不修改产品代码、构建配置或运行时资源不改变 staging、commit、rebase、merge 和 push 的授权边界不为单一案例复制第二套提交展示模板。注意非目标的意义这是一次纯粹的Agent 工作流 / 交付协议层治理不触碰 Easydict 的 Swift/ObjC 产品代码。这也是后续验证环节明确未运行xcodebuild的原因。三、确定性变动统计commit-change-stats.py 深度解析本次改进的核心交付物之一是统计脚本 commit-change-stats.py。它只依赖Python 标准库 Git CLI不引入第三方依赖因此可在任意具备 Python 3 与 Git 的机器上直接复算。3.1 用法单提交与多提交范围单提交统计默认HEAD也可传入任意 revisionpython3 git-commit-skill-dir/scripts/commit-change-stats.py full-commit-hash多提交范围统计三圆点BASE...SOURCE集成区间python3 git-commit-skill-dir/scripts/commit-change-stats.py \ --range target-commit...source-commit参数约束源码parse_argumentsL166-L186revision为可选位置参数默认HEAD使用--range时不允许再传位置参数否则报错do not combine a positional revision with --range--range强制使用BASE...SOURCE形式两侧分别通过git rev-parse --verify rev^{commit}解析为完整对象 ID非法 revision 会以非零退出码报错到 stderr。3.2 数据来源rename-aware numstat脚本从 Git 获取原始变动数据L85-L92单提交git show --format --numstat -z --find-renames revision多提交范围git diff --numstat -z --find-renames base...source两个关键设计点-zNUL 分隔正确处理含空格、中文等特殊字符的文件路径这是行为测试覆盖的边界之一--find-renames重命名检测numstat 输出中重命名记录的第一个字段为空parse_numstat会跳过源路径字段、只取目标路径用于分类L111-L116因为重命名后的目标路径才是分类依据。3.3 代码 / 文档互斥分类规则is_documentation函数L128-L141定义文档类别的判定使用PurePosixPath归一化路径并统一小写比较规则维度命中即归为docs目录路径任意父目录名为docs或documentation固定文件名AGENTS.md、SKILL.md文件名前缀以readme或changelog开头不区分大小写扩展名.md、.mdx、.rst、.adoc其余所有文本文件源码、测试、构建/运行时配置、资源、Skill 脚本等归为code。两条类别互斥且穷尽总计必须严格等于code docs之和这是可复算的数学基础。3.4 二进制静默跳过Git numstat 对二进制文件记录为-新增/删除字段均为-。collect_stats在解析时遇到该标记直接continueL150-L151既不参与统计也不出现在用户可见报告中——这与任务目标中静默忽略二进制文件完全一致。3.5 稳定 JSON 输出脚本最终输出一份sort_keysTrue、ensure_asciiFalse的稳定 JSONL205-L218{ code: { deletions: 2, files: 1, insertions: 8, net: 6 }, docs: { deletions: 13, files: 4, insertions: 60, net: 47 }, revision: full-commit-hash, scope: commit, total: { deletions: 15, files: 5, insertions: 68, net: 53 } }每个类别包含files / insertions / deletions / net四个字段net insertions - deletions。JSON 输出保证了后续任何调用方Agent、CI、脚本都能以结构化方式消费统计结果而非解析人类文本。3.6 错误处理所有 Git 调用失败无效 revision、不可读变更集、格式异常的 numstat 记录都会抛出ChangeStatsError主函数打印error: message到 stderr 并返回退出码 1。这意味着脚本失败时绝不编造统计——该约束同时写入报告契约脚本失败或数字不一致时不编造统计。四、唯一提交后报告契约reporting.md 与回执模板统计脚本只解决数字从哪来的问题而回执长什么样由 reporting.md 定义。4.1 回执证据的采集创建提交后报告契约要求创建提交后收集以下五项证据证据命令用途完整哈希git rev-parse HEADCommit 字段完整实际提交信息git show -s --format%B HEAD实际提交信息区块当前分支git branch --show-current分支字段最终工作树状态git status --short工作树字段干净 / 保留未提交变更变动统计commit-change-stats.py统计表4.2 用户可见回执的固定字段契约规定回执必须完整保留以下字段中文任务使用中文标签英文任务翻译标签但保留字段与顺序提交结果 - 动作已创建提交 - Commitfull-hash - 分支branch - 提交后校验validation-status - 工作树干净 or 保留未提交变更 - Push未执行 变动统计 | 类别 | 文件数 | 新增行 | 删除行 | 净变动 | | --- | ---: | ---: | ---: | ---: | | 总计 | files | insertions | deletions | signed-net | | 代码 | files | insertions | deletions | signed-net | | 文档 | files | insertions | deletions | signed-net | 实际提交信息 text exact output of git show -s --format%B HEAD 净变动的符号约定正值N、负值-N、零值0无变化。代码块中的提交信息必须与 Git 输出完全一致不允许美化或改写。4.3 完整回执示例post-commit-report-example.md 给出了可直接替换占位符的完整示例其中体现了三个值得注意的细节双语文案提交信息Easydict 遵循 Angular 风格的双语提交中文主体 英文标题区块回执中的实际提交信息原样保留这一格式统计表与 JSON 对齐示例中总计 5 文件 / 68 / -15 / 净 53恰好等于代码1 文件 / 8 / -2 / 净 6与文档4 文件 / 60 / -13 / 净 47之和直观演示了总计 代码 文档的可复算约束Push 边界git-commitSkill 明确不执行git push、rebase 或 merge见 SKILL.md 任务与边界表因此回执中 Push 恒为未执行。4.4 与提交主流程的衔接报告契约不是独立存在的它位于 git-commit 提交主流程 的末尾环节起草消息 → 展示完整预览 → 写入任务专用消息文件 → 校验消息 → git commit -F message-file → 以新建完整 commit hash 做提交后一致性校验 → 删除消息文件 → 读取 reporting.md 按真实结果交付其中提交后一致性校验用于确认 Git 实际写入的 message 与预览一致防止 hook 改写或内容漂移。校验失败时保留消息文件、不 amend、不声称交付完成确保回执中的提交后校验字段真实可信。五、worktree-rebase-merge复用契约并补充集成事实单提交场景的契约统一后剩下的问题是worktree 集成场景如何复用而不复制模板worktree 集成回执 给出了分层答案。5.1 两层回执结构worktree 集成完成后的回执分为两层第一层集成结果由worktree-rebase-merge补充的领域事实源分支、目标分支和目标 checkout源提交数与集成模式direct-commit、existing-target-worktree或temporary-target-worktreeRebase、Merge 和 Push 的实际状态直接提交时三者明确写未执行源/目标 worktree 的最终状态、临时 worktree 路径与清理结果原始 detached commit、源分支是创建还是复用。第二层提交回执复用git-commit契约不重新起草5.2 单提交与多提交的差异化处理恰好一个源提交在集成结果后完整附加git-commit回执含统计表和完整实际信息但动作字段按提交来源改写created-this-run→ 写已创建提交preexisting-source-commit→ 写本次未创建新提交合并的是源分支已有提交提交后校验写未执行本次复用已有提交但仍保留完整 hash、统计、实际信息、最终状态和 Push。多个源提交先列出每个完整 hash 和 subject再调用git-commit汇报冻结范围并生成统计因为范围没有单一提交信息绝不用其中一条 message 代表整个范围。5.3 冻结范围的时间点多提交统计有一个易踩的坑如果目标分支在集成后已经前进BASE...SOURCE范围可能读出空结果。因此契约规定多提交统计使用合并前冻结的目标 OID与rebase 后源 OID避免目标已前进后读出空范围。这体现了整个设计对可复算的坚持——统计数字必须与用户看到的集成动作发生在同一时间点。5.4 职责划分原则git-commit是提交结果、统计和单提交实际 message 的唯一格式来源worktree-rebase-merge只补充集成事实。这是整个方案的分层核心展示层契约收敛到一个 Skill领域层事实由各工作流自行补充杜绝了第二套提交展示模板的出现对应非目标中的第三条。六、行为测试与验证用临时仓库验证真实输出确定性统计不能只靠设计必须有测试兜底。测试文件为 test_commit_change_stats.py其特点是以Python 标准库unittest 临时 Git 仓库运行真实命令、校验真实输出而非 mock。执行方式python3 .agents/skills/git-commit/tests/test_commit_change_stats.py6.1 测试覆盖的边界场景结合完成历史与计划进度章节6 个行为测试覆盖场景验证点混合文件代码与文档分类互斥、总计 两类之和分类规则目录、文件名、扩展名各维度的 docs 判定重命名rename-aware 解析、目标路径分类正确中文和空格路径-zNUL 分隔下路径解析正确删除删除行统计与净变动符号多提交区间--range聚合统计空提交与无效 revision错误路径行为非零退出码、不编造统计6.2 完整的验证清单执行计划的验证章节列出了本次改进的完整验收证据统计脚本 6 个行为测试全部通过Python 语法检查通过统计脚本对真实历史提交试运行通过代码、文档和总计可复算两个 Skill 的报告字段、提交来源分类和 Push 边界通过静态检查git diff --check通过无空白错误未运行xcodebuild——因为未修改产品代码、测试或 Xcode 工程元数据与非目标边界一致。七、决策记录关键设计取舍执行计划的决策记录沉淀了四条可复用的工程决策日期决策理由2026-08-21代码与文档分类互斥总计必须等于两类之和保证统计可复算、可审计2026-08-21二进制 numstat 记录静默跳过不进入用户可见报告避免噪声聚焦文本变动2026-08-21单提交集成复用git-commit报告多提交集成报告完整提交列表和区间统计唯一契约 范围事实2026-08-21统计脚本只依赖 Python 标准库和 Git测试使用临时仓库验证真实输出零第三方依赖、零 mock、结果可信八、在 Skill 资产体系中的定位要理解这套 Skill 为何可以独立演进需要知道 Easydict 的 Skill 资产管理策略见 docs/agents/skills.md外部仓库统一维护通用内容skills-lock.json登记的目录是外部权威内容的完整项目快照可离线读取和运行lock 记录来源、ref、入口路径和内容哈希通过重算检查本地漂移通用 Git、Review 和交付算法由受管 Skill维护不通过本地修补或 fork 改写Swift/Xcode、本地化和发布等项目政策则写入宿主规则。git-commit、worktree-rebase-merge属于来源基线tisfeng/skillsv0.6.3 采用范围中的六个 Skill 之二。这套唯一报告契约的设计因此具备了跨项目复用的能力——任何引入该 Skill 的仓库都能获得相同的提交回执体验。九、完成条件与归档执行计划以明确的完成条件收尾它们同时也是验收时的行为断言成功提交后不能再用短哈希和标题代替完整结果用户可见结果包含完整哈希、完整消息、工作树、push 和三组文本变动统计worktree 流程能够准确说明本次创建提交还是复用已有提交计划已归档并在docs/histories/记录结果。对应的归档产物为 执行计划状态completed负责人 Codex关联 Issue/PR 为 none与 完成历史。其中完成历史额外记录了设计意图让git-commit成为单提交结果的唯一报告契约避免调用工作流各自维护不一致的模板文本行统计由可测试脚本从 Git 原始数据计算worktree-rebase-merge只补充提交来源和集成状态。十、总结这套方案的可迁移价值Easydict 的这次治理改进本质上是把AI Agent 交付结果从不可控的自然语言变成了可复算、可审计的结构化协议。其可迁移到其他仓库/团队的要点可以归纳为三条契约收敛所有调用方共享同一个回执契约与统计脚本杜绝每个工作流一套模板的漂移数据只读真实回执字段全部来自 Git 真实对象rev-parse/show/status/ numstat脚本失败或数字不一致时宁可报错也不编造职责分层展示层git-commit与领域层worktree-rebase-merge的集成事实各司其职单提交复用统一报告、多提交补充范围列表与区间统计。对于正在构建 Agent 自动化交付体系自动 commit、自动 PR、worktree 集成的团队本文中的分类规则、回执模板、冻结范围时间点与临时仓库测试方法都可以直接作为设计参考。【免费下载链接】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），仅供参考