client-report-from-commits

client-report-from-commits

将指定日期范围内的 Git 历史整理成可直接复制粘贴、按功能分组的非技术客户更新。

决策树

你已经掌握哪些信息？

• 确切的开始日期为 YYYY-MM-DD，且当前工作目录就是目标 Git 仓库：继续。
• 确切的开始日期为 YYYY-MM-DD，但目标仓库位于其他位置：使用明确的仓库路径并继续。
• 相对日期明确，且时钟、时区和相关上下文可靠：先确定日期，并说明确切的 YYYY-MM-DD 边界和时区，然后再收集历史记录。无需重复确认。
• 范围确实含糊，例如“最近”、“某个未明确起止日的周”或“自上次推送以来”，但没有已知事件边界：提出一个有针对性的问题。不要根据提交时间猜测推送或部署日期。
• 当前工作目录中没有可读取的 Git 仓库，且用户未提供仓库路径：停止并要求提供可读取的 Git 仓库路径。
• 用户需要的是工程发布说明、开发者变更日志或代码审查：不要使用此技能。

快速参考

任务	操作
确认仓库	在当前目录运行 git rev-parse --show-toplevel；若用户提供了仓库路径，则运行 git -C /path/to/repo rev-parse --show-toplevel。
收集提交上下文	使用 Git 历史记录和差异，或运行 python3 scripts/collect_git_changes.py --repo /path/to/repo --since YYYY-MM-DD 获取结构化清单。
查看更多细节	阅读 references/workflow.md，然后使用 git show <commit> 检查目标提交。
编写客户更新	遵循用户要求的格式；templates/client-report-template.md 可作为可选起点，references/output-format.md 提供写作指导。
处理边缘情况	阅读 references/gotchas.md。

操作规则

1. 根据用户请求或可靠上下文确定真实的日历日期边界。辅助工具只接受 YYYY-MM-DD；调用前先解析相对日期，不要更改其严格的解析器。
2. 确认仓库上下文。如果当前工作目录不是可读取的 Git 仓库，则必须要求用户提供明确的仓库路径。
3. 根据相关历史记录和差异撰写报告。如果 scripts/collect_git_changes.py 的清单有帮助，则使用它；若已有证据足以完成任务，不要重复收集。
4. 按功能、工作流或产品领域对工作进行分组。不要按提交、文件、分支或工程师分组。
5. 面向非技术客户撰写。删除哈希、文件名、代码术语、重构行话和内部工具名称，除非它们确实面向客户。
6. 按要求的形式保持报告简洁。根据内容选择标题、段落或项目符号数量，不要为了满足配额而写。
7. 只陈述有证据支持的变更。提交记录不能证明部署、采用情况或业务影响；即便是听起来较为克制的说法，也需要证据支持。

建议工作流

1. 确定目标仓库。
2. 确定并说明确切的 YYYY-MM-DD 日期边界及任何重要的时区假设。
3. 直接收集历史记录，或运行 python3 scripts/collect_git_changes.py --repo /path/to/repo --since YYYY-MM-DD 并检查 JSON 输出。
4. 如果功能分组不明显，检查几个有代表性的提交或差异。
5. 先按功能列出大纲，再撰写适合客户阅读的要点。
6. 按要求的形式交付报告；默认使用可直接复制粘贴的 Markdown。

报告规范

除非用户要求其他形式，否则使用以下默认规则：

• 以一句简短介绍开头，例如 Here is a high-level update for work completed since 2026-04-01.
• 按功能划分报告章节，并使用简短、便于读者理解的标题。
• 只使用区分重要变更所需数量的要点或句子；不要为了凑数而填充或遗漏证据。
• 每条要点都应先说明结果，并避免技术性表述。
• 确保输出可直接复制粘贴。不要添加分析说明或开发者前言。
• 如果所请求的时间范围内没有对客户有实际影响的变更，请直截了当地说明，不要填充内容。

阅读指南

需求	阅读
仓库检查、命令流程和 git 收集步骤	references/workflow.md
语气、分组和要点撰写规则	references/output-format.md
失败模式及注意事项	references/gotchas.md
可直接用于客户报告的空白结构	templates/client-report-template.md

注意事项

1. 仅当时钟、时区和时间范围含义明确时，才解析相对日期。如果缺少的边界条件可能影响报告，请先询问。
2. 冗长的 git 日志不等于客户报告。按功能归纳；对客户没有帮助的低价值内部变更应省略。
3. 面向非技术读者时，技术性提交说明往往会造成误导。将其改写为面向客户的要点前，请检查差异或相关文件。
4. 多个提交可能对应一项成果。应将它们合并到同一个功能章节，而不是重复相同主题。
5. 不要夸大仅涉及基础设施的变更。如果这些变更确实重要，应将其描述为稳定性或基础建设工作，并谨慎措辞。

指引不足时

如果收集指引已过时或与仓库情况冲突，请使用仓库历史、差异、配置和当前官方 Git 文档来确认相关行为。在任务只读范围内使用经过验证的命令；如有无法访问或不完整的历史记录，请予以说明。应提出规范的技能修正建议，并附上来源和可复现的 git 示例或检查，而不是悄悄修改已安装的副本。常规报告无需浏览资料。