| name | git-changes-reporter |
| description | 生成结构化 git 变更报告（JSON + Markdown）。使用此技能当用户提到"git 变更"、"commit 摘要"、"代码审查"、"release note"、"近期改动"、"每日摘要"，或需要分析指定 commit 区间的代码变更。包含三元组结构（设计意图、核心代码、影响范围）的语义化报告，适用于代码审查、发布说明、团队同步、CI/CD 等场景。 |
Git Changes Reporter
何时使用本 Skill
满足以下任一条件时，应使用本 Skill：
- 需要为人类工程师生成可读的变更摘要（团队同步、代码审查、发布说明）
- 需要为 Agent 提供完整 git 变更上下文以回答后续问题
- CI/CD 流水线中需要存储和分析变更记录
- 用户提到"近期改动"、"commit 摘要"、"release note"等需求
不要使用本 Skill 的情况：
- 仅需列出 commit 列表（直接用
git log）
- 单个 commit 的详细分析（直接用
git show）
核心原则
Agent 主导判断
- 脚本：只负责数据收集，不做内容选择
- Agent：阅读数据，判断重要性，选择展示内容，撰写分析
简洁至上
上下文是共享资源。报告应该：
- 聚焦意图：不仅说"做了什么"，更要说"为什么"
- 代码片段优先：5-15 行核心代码胜过长篇解释
- 结构化呈现：用列表和表格而非段落堆砌
渐进式披露
三个分析深度级别：
- Level 1 (基础)：统计信息、目录热度、贡献者分析
- Level 2 (中级)：含代码片段、风险识别、领域聚类（默认）
- Level 3 (深度)：含调用关系、完整风险评估、详细影响分析
工作流程
阶段一：生成结构化 JSON
目的：收集原始数据，自动提取代码片段和风险指标
.claude/skills/git-changes-reporter/scripts/generate-json.js <old_commit> <new_commit> [output_path] [options]
选项：
| 选项 | 说明 | 默认值 |
|---|
--markers=FILE1,FILE2,... | 项目边界特征文件（用于 monorepo 分析） | package.json,Cargo.toml,go.mod,... |
Monorepo 项目检测：
脚本会自动扫描仓库中的特征文件（如 package.json、Cargo.toml）来识别项目边界，支持任意深度的嵌套结构：
generate-json.js HEAD~10 HEAD
generate-json.js HEAD~10 HEAD --markers=pyproject.toml,setup.py
输出内容：
directoryAnalysis：目录热点分析
topLevel[]：顶层目录统计（如 apps, libraries）projects[]：项目级别统计（如 apps/vendor-okx, libraries/protocol）
project：项目路径fileCount：变更文件数marker：检测到的特征文件（如 package.json）
markersUsed：使用的特征文件列表
commits[]：每个 commit 的详细信息
short：短哈希（用于引用）subject：提交主题conventionalCommit：解析的 feat/fix/refactor 等类型files[]：变更文件列表
path：文件路径changeType：added/modified/deleted/renamedcodeSnippets[]：自动提取的函数/类/接口定义（最多 15 行）
analysis.domains[]：自动识别的技术领域analysis.riskIndicators[]：风险指标（breaking_change/large_refactor/no_tests/api_change）contributors[]：贡献者统计
阶段二：Agent 阅读 JSON 并生成报告
Agent 职责：
- 分段读取 JSON 文件（按需读取，避免超出 token 限制）
- 理解变更的技术意图和业务影响
- 选择重要的代码片段展示
- 按照下方模板格式输出最终 Markdown 报告
读取策略（JSON 文件可能较大）：
Read JSON offset=0 limit=100
Read JSON offset=X limit=200
阶段三：质量验证
目的：确保报告符合质量要求，防止胡编乱造
第一次验证：基础检查
验证报告格式和结构完整性：
.claude/skills/git-changes-reporter/scripts/validate-report.js <markdown_file>
检查内容：
- 必需章节（概览、核心变更、贡献者、风险评估）
- 代码片段格式
- 文件引用格式
- Commit hash 格式
- 设计意图完整性
第二次验证：严格模式（默认启用）
验证报告内容真实性，防止胡编乱造：
.claude/skills/git-changes-reporter/scripts/validate-report.js <markdown_file> \
--json <json_file>
严格模式自动检查：
- ✅ Commit 覆盖率：确保 100% 覆盖 JSON 中所有 commits，无遗漏
- ✅ 文件引用真实性：验证所有文件路径存在于仓库（通过
git ls-files）
- ✅ Commit hash 真实性：验证所有 commit hash 存在于仓库（通过
git cat-file）
如需仅做格式检查（不推荐）：
.claude/skills/git-changes-reporter/scripts/validate-report.js <markdown_file> \
--json <json_file> \
--basic
第三次验证：人工复查清单（可选）
生成二次确认清单供 Agent 逐项复查：
.claude/skills/git-changes-reporter/scripts/validate-report.js <markdown_file> \
--json <json_file> \
--checklist
清单内容：
- 列出所有应覆盖的 commits
- 统计代码片段数量
- 显示文件引用列表
工作流建议：
- 首次生成报告：先运行基础验证，修复格式问题
- 内容完善后：运行严格模式（默认启用，只需提供
--json），确保内容真实性
- 提交前：使用
--checklist 进行人工复查
重要：严格验证已默认启用，Agent 无法跳过真实性检查，有效防止胡编乱造。
报告模板与关键要求
Agent 必须使用三元组结构 + 提交明细输出每个核心变更：
- 设计意图（为什么做，至少 50 字）
- 核心代码（5-15 行代码片段 + 文件引用）
- 影响范围（影响的模块和注意事项）
- 提交明细（每个 commit 一句话：
hash: 做了什么）
⚠️ 全覆盖要求：核心变更章节必须涵盖所有提交，不能遗漏任何一个 commit。
完整模板、示例和详细要求：见 references/report-template.md > 避免常见错误：见 references/bad-examples.md
故障排除
| 问题 | 解决方案 |
|---|
| JSON 文件太大无法一次读取 | 分段读取：先读 meta/analysis，再按需读具体 commit |
| 不确定哪些变更重要 | 优先看 riskIndicators 和 conventionalCommit 类型 |
| Commit 数量太多 | 按领域分组，相似变更合并描述 |
参考资源
版本：3.0.0
上次更新：2025-12-06
