summarize-changes

# summarize-changes — 代码更改总结 分析当前 Git 工作区的变更（diff），结合当前对话上下文（如适用），理解修改了什么、为什么修改，生成简洁的 commit message。 ## 触发方式 ``` /summarize-changes [--staged] ``` - 不带参数：从 `git diff`（工作区 + 暂存区所有未提交变更）获取内容。 - `--staged`：只总结暂存区变更，从 `git diff --cached` 获取内容。 ## 使用场景 1. **变更结束后直接调用**（推荐）：在同一对话中刚完成一项改动后调用。对话历史包含改动的目标、背景与决策过程，是 commit 标题与背景最可靠的来源，可避免仅凭 diff 猜测目标时被改动量分布误导。 2. **独立总结现有变更**：对话与本次改动无关（如新开会话总结工作区遗留变更）。仅从 diff 分析。 ## 执行流程 0. **安全检查**（仅默认模式，`--staged` 模式跳过）： - 运行 `.omp/skills/summarize-changes/check-changes.sh` 获取工作区全貌： - 退出码 0（无未暂存/未跟踪文件）：展示输出后直接进入步骤 0.5。 - 退出码 1（存在未暂存或未跟踪文件）：展示输出，通过 `ask` 询问是否继续/切换 `--staged`/中止。 0.5. **提取会话上下文**（仅场景 1）： - 回顾当前对话，确认是否包含本次改动的开发过程（原始需求、方案讨论、决策、范围说明、验证过程）。若不包含 → 按场景 2 处理，跳过本步骤。（若改动早期讨论已超出上下文窗口，可用 `history://` 读取本会话完整记录。） - 依次提取： - **改动目标**：用户最初要解决什么问题 → commit header 与 Why 的来源。 - **决策与取舍**：为什么选当前方案、讨论中否掉/放弃的备选 → What & Impact 的来源。 - **范围边界**：用户明确声明包含/排除的内容，用于识别 diff 中的附带改动。 - **验证过程**：冒烟测试、测试结果等，作为影响描述的佐证。 - **关联 issue**：本次改动是为解决哪个平台上的哪个 issue（如 github #92），作为 header 后缀的来源；对话未提及时按步骤 6 的兜底规则处理。 - **目标判定以对话为准**：commit 标题描述对话确立的目标，而非 diff 中改动量最大的领域。某领域虽改动量大但与对话目标无关，属于附带改动，仅在 body 中概括为次要要点。 - 若对话包含多个独立任务且当前 diff 混有多个任务的内容，按任务分组提炼，必要时 `ask` 用户确认本次 commit 范围。 1. **收集变更信息**：运行 `git diff HEAD --stat` 和 `git diff HEAD`（或 `--cached` 对应版本）获取变更内容。 2. **容量检测**：stat 中变更文件 > 15 个时，禁止逐一文件详解，改为按**变更目的**分组概括。 3. **单文件上下文限制**：单个文件变更块上下文 > 200 行或变更行数 > 500 行时，禁止 Read 完整文件，仅基于 diff 片段分析。 4. **理解改动**： - 场景 1 先核对 diff 与步骤 0.5 的目标是否一致： - 目标内容在 diff 中缺失（改动未完成或 diff 属于其他任务）→ 提示用户「diff 与对话目标不符」。 - diff 包含对话之外的大块改动 → `ask` 用户是否纳入本次 commit，或单独归类描述。 - 对话讨论过但未落地的方案，**不写入** commit。 - 阅读 diff，理解改了什么、为什么改。**不需逐一罗列每处修改**，同类变更合并为一条概括描述。 - **输出篇幅与变更规模成正比**：小改动（≤5 文件、≤100 行 diff net）的 body 控制在 5–10 行内；中型 ≤15 行。body 不设逐行 70 字符限制，精简优先。 - 关注**问题根因**和**高阶解决方案**，而非逐行翻译 diff。 5. **分析根因**（仅修复类变更）：从 diff 反推发生了什么错误。 6. **生成 commit message**： ``` <type>(<scope>): <一句用户视角的话，描述提交后的最终效果> **🤔 背景与动机 (Why)** 2–4 个要点，描述问题或痛点。 **✨ 解决方案与影响 (What & Impact)** 2–4 个要点，描述高阶解决方案和核心影响。 ``` - **场景 1：header 与 Why 直接来自步骤 0.5 的对话目标**，What & Impact 结合对话决策与 diff 验证结果；场景 2 按原规则从 diff 推断。 - **header ≤100 字符**（commitlint `header-max-length`），且不含标点结尾。 - **关联 issue 标记**：本次改动是为解决/实现某平台上的某个 issue 时，header 末尾追加该平台与编号。 - 格式：以空格与标题分隔，括号内为小写平台名 + `#` 编号，如 `(github #92)`；平台名用惯用写法（`github`、`gitcode`、`gitee`、`atomgit`）。 - 来源：场景 1 以对话为准（用户贴出的 issue 链接/编号、修复诉求）；场景 2 从分支名、近期提交、diff 与仓库 issue 线索推断。推断不出用 `ask` 问用户，**禁止编造编号**。 - 无明确关联不追加；同一平台多个编号并列写在同一括号内（如 `(github #92, #95)`）；后缀计入 header 的 100 字符上限。 - **body 每行 ≤100 字符**（commitlint `body-max-line-length`）。 - **subject 首词避用大写拉丁字母**：commitlint `subject-case` 禁止 sentence-case / start-case / pascal-case / upper-case，以全大写缩写（`SDK`、`API`、`IPC`、`CLI`）或首字母大写的英文单词开头都会违规；中文或小写开头（如 `sdk crates 版本解耦`）则通过。规避方法：缩写改小写（`sdk`），或改用中文/其他措辞开头。 - 使用中文 body，**不含**双引号 `"`。 - **每节要点 ≤4 个**，用抽象概括代替逐项枚举（不列函数名、文件数、测试数）。 - **禁止在 body 中嵌入超过 50 字符的代码/路径/符号引用**。必须用自然语言描述行为，而非复现代码符号： - ❌ `在 validate_settings() 之前调用 component.apply_settings(component.get_default_settings())` - ✅ `在注册时预置 schema 默认值，使校验前已持有符合约束的初始状态` - ❌ `src-tauri/src/core/config/manager.rs:54-64` - ✅ 只描述「在哪层做了什么」即可，不列具体行号 - **Scope 规则**：基于对 diff 的理解，用能代表本次改动所属领域的短名称作 scope（如 `translator`、`config`、`i18n`）。目录结构仅作参考，不作机械判定： - 改动可归入单一领域（功能、子系统、配置域或横切工作如 i18n/性能）→ 用领域名，即使文件散落在多个目录（如后端、前端与语言资源共同完成同一功能）。 6.4. **scope 大小写**：scope 须为小写/中划线/驼峰/帕斯卡命名，避免大写缩写开头（如 `SDK` 会触发 `scope-case` 违规），示例 `workspace`、`api`、`i18n` 均合规。 6.5. **commitlint 校验**：将生成的 commit message 送入仓库的 commitlint 检测——与 `.husky/commit-msg` 钩子同一规则源，覆盖 `subject-case`、`type-case`、`scope-case`、`header-max-length`、`body-max-line-length` 等全部规则（不再依赖自写脚本）： - 命令（在仓库根目录执行）：`printf '%s\n' '<commit message>' | bun x --no -- commitlint`，多行消息可用 heredoc 传入，空行须保留。 - 退出码 0 → 合规，进入步骤 7；退出码 1 → 按报错规则修正（超长压缩措辞、subject/type/scope 大小写调整），**重新生成** commit message 后再次校验，直至通过。 - commitlint 按字符统计长度（对宽字符与英文一致计数），header 与 body 上限均为 100。 - 若本地无 bun 或 commitlint 不可用，回退为行长度检查（header ≤100、body ≤100）。 7. **输出结果**：展示给用户，不执行 `git commit`。 ## 输出示例 ``` fix(core): 在注册时预置 schema 默认值避免零值与约束冲突 **🤔 背景与动机 (Why)** - 组件注册先于持久化配置加载，校验时读取的是 struct 零值而非 schema 默认值。 - min_items(1) 等约束下的空数组等零值导致「当前配置值无效」错误。 **✨ 解决方案与影响 (What & Impact)** - 注册流程中先应用 schema 默认值作为初始状态，再执行校验。 - 持久化配置随后加载覆盖，不影响用户已保存的值。 ``` ## 注意事项 - 专注**总结变更**，不继续扩展新改动。 - **同类变更合并描述**，不逐行罗列 diff 细节。 - 涉及依赖版本变更时在 body 里注明原因。 - **场景 1 目标判定以对话为准**：diff 的改动量分布只影响 body 的详略与附带改动归类，不改变标题指向的目标。 - 对话中讨论过但未实施的方案（备选、被否决策）不写入 commit，只描述实际落地内容。