结构化 Git 提交规范（Technical Commit Convention）

目标

为任何项目提供一套统一、结构化、技术可追溯的 Git 提交信息规范，让每次提交清晰说明代码层的变更（模块、算法、配置、依赖等），同时保持面向开发者的可读性，且便于自动化生成更新日志。

核心理念

• 技术可追溯：每次提交清晰说明代码层面的变更，包括模块、算法、配置、依赖等。
• 面向开发者：提交信息是可读的，但核心是技术描写，避免含糊表述。
• 结构化：采用轻量级标记（类型、范围、主体、技术细节），便于自动化解析与生成更新日志。

输入与输出

• 输入：本次变更的文件列表或变更描述（可由用户提供，或基于代码推断）。
• 输出：可直接用于 git commit -m 的纯文本提交信息。

格式定义

<type>(<scope>): <subject>

<technical body>  (必填，至少一条技术描述)

[optional footer]

1. Type（类型，技术语义，必填）

2. Scope（范围，必填）

用单词语义指定受影响的技术模块，例如：template、router、api、auth、ui、style、config、deploy、docs、analytics、test、script 等。无法归入单一模块时，可省略 (<scope>)。

3. Subject（主题，简洁技术描述，必填）

用中文，10~20 字，直接说明做了什么技术变更，例如：

• 重构分页逻辑，改用游标分页
• 升级 marked 库并修复 XSS 隐患
• 添加 webp 支持并实现降级方案

4. Technical Body（技术正文，必填）

必须包含至少一条具体的技术描写，多条可用列表。内容包括但不限于：

• 实现方式：用了什么 API、算法、数据结构、设计模式。
• 修改前后对比：关键代码逻辑的变化。
• 性能指标：优化前后的加载时间、包体积等。
• 依赖变更：新增/升级了哪些依赖包及版本号。
• 配置调整：构建、lint、测试等配置改动。
• Bug 根因：错误产生的原因及修复原理。

示例格式：

- 技术实现：
  - 将分页参数 from offset 改为 after timestamp，基于 createTime 索引查询，减少大偏移量下的慢查询。
  - 前端修改 API 调用方式：`GET /items?after=xxx&limit=10`。
- 性能影响：接口延迟从 320ms 降至 210ms（压测结果）。
- 涉及文件：`routes/items.js`, `src/api.ts`

5. Footer（脚注，可选）

• Breaking change: 描述不兼容的变更。
• Closes #issue 关联任务或问题。
• See also 相关文档链接。

工作流

1. 当用户要求"根据本次代码变更生成提交信息"时，主动询问变更的文件列表或描述；若未提供，则基于文件扩展名和常见模式推断（如 .scss 变化写样式细节、.js/.ts 写逻辑细节），并提醒用户补充。
2. 判断变更主类型，选定 type 与 scope。
3. 写中文 subject（10~20 字），再补至少一条技术正文。
4. 需要时附加 footer。
5. 输出纯文本，可直接用于 git commit -m。

守则

• 生成的提交信息必须包含至少一条技术描写，不能只写"更新了样式"这种模糊描述。
• 若用户提供的信息不足以写清技术细节，基于常见模式推断并在结果后提醒用户按需补充。
• 输出保持结构化、可追溯，面向开发者可读。