企业官网建设流程全解析

• 桌面应用
• AI 应用

导读

在自动化 Agent 或多人协作的提交流程中，如何让一次本地 Git 提交"可核验"——从完整哈希、分支、校验状态到分类统计，全部以 Git 真实对象为准——是保证交付质量的关键。本文以 Easydict 仓库中.agents/skills/git-commit技能模块的完整提交回执示例为核心骨架，结合其技能定义、统计与回执规范、提交信息契约及配套脚本与测试，完整讲解回执的字段语义、变动统计规则、双语提交信息结构以及前后校验流程。读完本文，你将能够读懂并亲手生成符合仓库规范的本地提交回执，理解其背后的分类算法与校验器约束。

一、完整提交回执长什么样

仓库通过 post-commit-report-example.md 提供一个"需要参考完整提交回复时阅读"的基准模板。该文档明确指出：示例中的哈希、分支、状态、统计和提交信息必须替换为本次实际结果，并且以 统计与提交回执 与 Git 的实际输出为最高优先级。

示例回执的完整结构如下：

本地 Git 提交完成。 提交结果 - 动作：已创建提交 - Commit：`0123456789abcdef0123456789abcdef01234567` - 分支：`docs/unify-commit-receipts` - 提交后校验：通过 - 工作树：干净 - Push：未执行 变动统计 | 类别 | 文件数 | 新增行 | 删除行 | 净变动 | | --- | ---: | ---: | ---: | ---: | | 总计 | 5 | 68 | 15 | +53 | | 代码 | 1 | 8 | 2 | +6 | | 文档 | 4 | 60 | 13 | +47 | 实际提交信息 ```text docs(git): 统一本地 Git 交付回执 背景：现有提交流程收集了完整结果，但最终回执格式分散，可能被压缩成提交标题。 变更：统一用户可见回执并使用 Markdown 表格展示统计，保留提交信息校验和 JSON 统计数据来源。 影响：这让本地提交提供一致、可核验的结果，并继续保持默认不推送的边界。 ---------------------------------------------------------------------- docs(git): unify local Git delivery receipts context: The existing commit workflow collected complete results, but its final receipt could be reduced to a commit subject. change: Unify the user-visible receipt and render statistics as a Markdown table while preserving message validation and the JSON statistics source. impact: This gives local commits consistent, verifiable results while preserving the default no-push boundary. ```

可以拆解出三个逻辑区块：

1. 提交结果（Receipt Header）：动作、完整哈希、分支、提交后校验、工作树状态、是否 Push。示例中Push：未执行对应技能定义中"本 Skill 不运行git push、rebase 或 merge"的边界（见 SKILL.md）。
2. 变动统计（Change Statistics）：以 Markdown 表格呈现总计/代码/文档三个类别的文件数、新增行、删除行与净变动。
3. 实际提交信息（Actual Message）：git show -s --format=%B HEAD的逐字输出，代码块内容必须与 Git 完全一致。

二、回执证据从哪里来：以 Git 真实对象为准

reporting.md 明确规定：创建提交后需收集以下五项证据，缺一不可：

回执字段的具体约束如下：

• 正净变动写+N，负值写-N，零值写0（无变化）；
• 本次创建且提交后校验通过时，提交后校验写"通过"；
• 复用已有提交时，动作行说明"本次未创建"，校验写"未执行（本次复用已有提交）"，但仍须保留完整哈希、统计、实际信息、最终状态与 Push 字段；
• 多提交范围（range）回执需列出每个完整哈希和 subject，注明未创建新提交、未执行提交后校验，并输出范围统计；由于范围没有单一实际提交信息，不能用其中某一条代替整个范围。

这套"先有证据、再写回执"的顺序保证了回执中的每一个数字和字符串都可溯源，而非凭印象杜撰。

三、变动统计脚本：代码与文档的互斥分类

回执表格的数据由仓库自带的 commit-change-stats.py 生成，它是一个只读 Git 命令封装器（内部通过subprocess.run调用git），支持单提交与范围两种模式：

# 单提交：输出完整哈希对应变更的 JSON 统计 python3 ".agents/skills/git-commit/scripts/commit-change-stats.py" <full-commit-hash> # 多提交范围：聚合 BASE...SOURCE 三点范围 python3 ".agents/skills/git-commit/scripts/commit-change-stats.py" \ --range <target-commit>...<source-commit>

3.1 分类规则

脚本将文本文件划分为两个互斥类别（源码中is_documentation()函数的判定逻辑）：

• docs：满足以下任一条件
  • 位于docs或Documentation目录（目录名大小写不敏感）；
  • 文件名为AGENTS.md或SKILL.md；
  • 文件名以README或CHANGELOG开头；
  • 扩展名为.md、.mdx、.rst、.adoc（见脚本顶部的DOCUMENT_EXTENSIONS、DOCUMENT_DIRECTORIES、DOCUMENT_FILENAMES常量）；
• code：其余所有文本文件，包括源码、测试、构建/运行时配置、资源和 Skill 脚本。

3.2 关键实现细节

• 二进制文件被有意跳过：numstat 记录中插入/删除行为-的条目直接continue（collect_stats中的判断），不计入统计与用户报告，输出中也无binaryFiles字段；
• 重命名感知：读取 numstat 时使用--find-renames，并解析 NUL 分隔记录以保留每个目标路径，重命名记录中的源路径不影响分类；
• 一致性约束：总文件数、新增、删除和净变动必须分别等于code + docs；脚本失败或数字不一致时不允许编造统计；
• 范围校验：--range参数强制要求BASE...SOURCE形式，且不能与位置参数 revision 同时使用（parse_arguments中显式报错）。

3.3 测试验证

仓库配套测试 test_commit_change_stats.py 在临时 Git 仓库中验证了以下行为，可作为回执统计正确性的可执行证据：

• 混合提交中二进制文件被忽略，total == code + docs；
• 文档名（README.md）、文档目录（Documentation/）、SKILL.md均归入 docs，普通配置与脚本归入 code；
• 重命名（含中文与空格路径）、删除场景下统计正确；
• 三点范围（base...source）的聚合结果正确且scope为range；
• 无效 revision 返回非零退出码并在 stderr 输出error:前缀的诊断。

输出为排序后的 JSON（含code、docs、revision、scope、total），也是提交流程中"JSON 统计数据来源"的直接载体。

四、实际提交信息背后的契约

回执末尾的"实际提交信息"不是随意写的，而是必须满足 commit-message.md 定义的提交信息契约。该契约决定了回执示例中那个双语结构的由来。

4.1 语言模式

按以下优先级确定提交信息语言：用户明确指定 > 当前对话主要使用的自然语言 > 系统偏好语言；仍无法判断时使用 English。

• english 模式：只有一个英文区块；
• bilingual 模式（非英语提交，示例即此模式）：本地语言区块 + 空行 + 严格 70 个连字符的分隔线 + 空行 + 英文区块，分隔线即示例中的----------------------------------------------------------------------；
• 不添加Chinese:或English:等区块标签。

4.2 区块结构与标记

中文本地语言区块使用背景：、变更：、影响：三个标记，英文区块使用context:、change:、impact:（冒号后恰好一个空格再接非空正文）。约束包括：

• 每个语言区块恰好三个自然正文段，依次说明背景、变更、影响，通常每段 1–3 句；
• 标题使用最窄且准确的 Angulartype(scope): subject，不超过 80 字符；
• type、scope和!在两个区块保持一致；中文任务第一个 subject 必须含中文，第二个 subject 必须为英文且使用祈使式小写、无句号，不得把同一英文 subject 用于两个区块；
• 仅在不兼容变更时使用!或区块末尾的BREAKING CHANGE:footer，footer 不能替代三个正文段；
• 可选全局References:尾段必须排在所有语言区块及 footer 之后，且每个条目以- [label: ]http(s)://...一行呈现，用于中立地记录影响本次决策的外部 PR/Issue/文档，不使用Closes:/Fixes:/Resolves:代替。

4.3 Type 指南

feat（新用户行为）、fix（缺陷修复）、docs（仅文档）、style（不改功能的格式）、refactor（不改行为的内部结构）、perf（性能改进）、test（仅测试）、build（依赖/打包/构建配置）、ci（CI 工作流）、chore（其他维护）、revert（回滚）。scope 优先使用parser、api、settings等具体模块，避免app或misc等宽泛名称。

五、提交前后校验：确保"所见即所提交"

回执中的提交后校验：通过字段并非口头承诺，而是由校验器 validate-commit-message.py 强制保证的。

5.1 提交前校验

将与可见预览完全一致的内容写入任务专用消息文件后运行：

python3 ".agents/skills/git-commit/scripts/validate-commit-message.py" \ --file <message-file> --mode <english|bilingual>

5.2 提交后校验

git commit之后、删除消息文件之前，使用刚创建的完整哈希运行：

python3 ".agents/skills/git-commit/scripts/validate-commit-message.py" \ --commit <full-commit-hash> --expected-file <message-file> --mode <english|bilingual>

该校验器（--expected-file参数）要求提交到 Git 中的真实消息与消息文件逐字一致；校验失败时保留消息文件、报告 commit hash 和具体错误，且不自动 amend。

5.3 校验器到底检查什么

从脚本源码可以看到一组确定性很强的规则（ALLOWED_TYPES、HEADER_PATTERN、ENGLISH_BODY_LABELS等常量）：

• 标题必须是type(scope): subject形式且 type 在 11 个合法值内，subject 恰好一行、不超过 80 字符；
• 每个语言区块恰好 3 个正文段，段首标记必须按序且标记后紧跟非空内容（必须包含内容紧跟其后，含前导空格也判失败）；
• bilingual 模式必须恰好 1 条 70 连字符分隔线，且前后各恰好一个空行；
• 两个语言区块的type/scope/breaking签名必须一致；英文 subject 不得含汉字且必须含英文；中文 subject 必须含汉字；
• 提交信息中禁止 Markdown 代码围栏（```）；
• BREAKING CHANGE:footer 必须是区块最后一段；References:段至多一个、标题必须精确、条目必须满足 URL 格式且去重。

配套测试 test_validate_commit_message.py 对上述每一条都构造了正反用例，例如"2 段或 4 段正文报错"、"69 个连字符报错"、"重复 URL 报错"、"提交信息与预期文件不一致报does not match"等，是理解回执格式约束最直接的参考。

六、回执在整个提交流程中的位置

回执并非孤立文档，而是 Easydict 仓库 git-commit 技能 的最终交付物。其主流程为：

1. 起草提交信息时读取提交信息契约，在主对话以text代码围栏展示完整消息；仅预览到此结束，确认模式等待批准；
2. 完成唯一暂存（支持已有索引直接提交、git add -- <selected-paths>或根目录git add .三种场景，且自动提交场景禁止git add .）并复验 staged paths 与 raw patch 完全一致；
3. 将预览内容写入任务专用消息文件，用校验器检查，再git commit -F <message-file>；
4. 用新建完整 hash 执行提交后一致性校验；失败则保留消息文件，不 amend，不声称交付完成；
5. 校验通过后删除消息文件，读取统计与提交回执，根据 Git 真实结果交付；需要看完整示例时读取完整提交回执示例。

此外，当submit-pr或worktree-rebase-merge等组合工作流需要任务分支名时，仓库还有一份分支命名规范：根据提交信息契约选择最窄的 Angular type，将摘要转为小写 kebab-case 形成<type>/<kebab-case-summary>，并用git check-ref-format --branch验证字面分支名；返回候选名不授权任何 Git 写操作。

七、实践要点与边界

• 回执数据永远以 Git 与脚本的真实输出为准，示例中的数值（如5 | 68 | 15 | +53）只是格式演示，必须在实际提交后替换；
• 不要跨过证据直接编造统计：脚本失败或total != code + docs时，宁可报告失败，也不得虚构数字；
• 工作树状态只有两种合法取值：干净或保留未提交变更；Push在本技能边界内恒为未执行；
• 双语提交信息的中文与英文区块必须语义一致、签名一致，分隔线严格 70 个连字符，任何偏差都会被校验器拦截；
• 提交后校验失败属于"停止条件"，正确动作是保留现场并报告具体阶段（见 SKILL.md 的"完成与停止条件"），而非自动扩大暂存、重试写入或 amend。

这套"范围校验 → 暂存复验 → 消息校验 → 提交后一致性校验 → 真实统计回执"的闭环，保证了每一次本地 Git 交付都能输出一份可核验、可回溯、格式统一的回执。对于希望将 Agent 提交流程规范化的团队而言，示例文档、统计脚本、校验器 及其测试 构成了一个可直接复用的最小实现。

• 桌面应用
• AI 应用