这是一个 Python 脚本，用于调用本地 Git 命令获取指定 Commit 区间或单个 Commit 的变更内容，然后利用大语言模型 (LLM) 生成结构化的变更日志总结，并最终使用 Jinja2 模板将总结渲染成 Markdown 文件。

• 自动获取 Git 变更: 调用 git 命令获取指定 Commit (或 Commit 区间) 的详细信息 (作者、日期、消息) 和文件差异 (diff)。
• 智能 Diff 处理: 在将 diff 发送给 LLM 前进行预处理，可以配置删除/增加内容的最大显示行数，避免 Prompt 过长。
• LLM 驱动的业务总结: 将 Commit messages 和处理后的 diff 发送给大语言模型 (LLM)，由 LLM 从业务/功能角度 分析变更，并在每个变更项中附带 1-2个最相关的关键文件路径。
• 灵活的 LLM 对接: 使用 openai 库，可通过配置轻松对接兼容 OpenAI API 的服务 (如 OpenAI, OpenRouter 等)。
• 结构化输出与解析: 要求 LLM 以 XML 格式 返回总结，脚本使用正则表达式解析该结构化数据。
• 作者信息自动填充: 脚本根据 LLM 返回的 commit hashes 自动查找并填充作者信息，无需 LLM 处理。
• 模板化渲染: 使用 Jinja2 模板引擎将解析后的结构化数据渲染成用户友好的 Markdown 文件。
• 命令行友好: 通过命令行参数指定需要分析的 Commit hash。
• 配置灵活: 脚本顶部的配置区允许轻松修改 Git 仓库路径、LLM API 参数、Diff 处理限制和输出路径等。
• 依赖管理: 提供 requirements.txt 文件方便安装依赖。
• 详细日志: 内置 logging 模块，提供不同级别的日志输出，方便调试和追踪。

• Python: 3.6 或更高版本。
• Git: 需要在系统 PATH 中能够调用 git 命令。
• Python 库: 查看 requirements.txt 文件。通过 pip install -r requirements.txt 安装。

在运行脚本之前，你需要修改 git_summary.py 文件顶部的配置区域：

# --- 配置区域 ---

# Git 仓库的本地路径
# !!! 重要: 修改为你的实际 Git 仓库在本地的绝对或相对路径
GIT_REPO_PATH = '/path/to/your/local/git/repo'

# 大模型 API 配置
# !!! 重要: 填入你使用的 LLM API 的实际信息 (兼容 OpenAI API)
LLM_API_ENDPOINT = 'https://openrouter.ai/api/v1' # 例如: 'https://api.openai.com/v1' 或 OpenRouter
LLM_API_KEY = 'YOUR_API_KEY_HERE' # 你的 API Key
LLM_MODEL_NAME = 'google/gemini-flash-1.5' # 例如: 'gpt-4', 'google/gemini-pro' 等

# Git Diff 处理配置
MAX_DELETION_LINES_PER_FILE = 10 # 每个文件最多显示的删除行数 ('-')
MAX_ADDITION_LINES_PER_FILE = 50 # 每个文件最多显示的增加行数 ('+')

# 输出配置
OUTPUT_DIR = 'generated_summary' # 输出目录名称
OUTPUT_FILENAME_TEMPLATE = 'summary_{}_{}.md' # 输出文件名模板
TEMPLATE_FILE = 'summary_template.md' # Jinja2 模板文件名

# 日志配置
LOG_LEVEL = logging.INFO # 日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_FORMAT = '%(asctime)s - %(levelname)s - %(message)s'

# --- 配置区域结束 ---

关键配置项:

• GIT_REPO_PATH: 必须修改为你的目标 Git 仓库在本地文件系统中的路径。
• LLM_API_ENDPOINT, LLM_API_KEY, LLM_MODEL_NAME: 必须根据你选择的、兼容 OpenAI API 的大语言模型服务提供商的要求进行填写。
• MAX_DELETION_LINES_PER_FILE, MAX_ADDITION_LINES_PER_FILE: 可选配置，用于控制发送给 LLM 的 diff 内容的大小。
• OUTPUT_DIR, OUTPUT_FILENAME_TEMPLATE, TEMPLATE_FILE: 可选配置，用于定义输出文件的存放位置、命名格式和使用的模板。

1. 安装依赖:

   pip install -r requirements.txt

2. 配置脚本: 按照上一节的说明修改 git_summary.py 中的配置，特别是 Git 仓库路径和 LLM API 信息。

3. 运行脚本: 在命令行中，切换到包含 git_summary.py 和 summary_template.md 的目录，然后执行：

   python git_summary.py <commit_hash_1> [commit_hash_2 ...]

   • 你需要提供至少一个 Git Commit 的短 hash 或完整 hash。
   • 如果提供多个 hash，脚本将自动找出这些 commit 中时间最早和最晚的，并获取它们之间的 diff。
   • 如果只提供一个 hash，脚本将获取该 commit 相对于其父 commit 的 diff (或使用 git show)。

   示例:

   # 生成单个 commit 7a3b1f9 的变更摘要
   python git_summary.py 7a3b1f9
   
   # 生成从 commit abc123d 到 def456e (按时间排序后) 的变更摘要
   python git_summary.py abc123d def456e

4. 查看结果: 脚本成功执行后，会在配置的 OUTPUT_DIR (默认为 generated_summary) 目录下生成一个 Markdown 文件。文件名将基于最早和最晚的 commit hash。

1. 解析参数: 获取命令行传入的 commit hash。
2. 获取 Commit 信息: 对每个传入的 hash，获取完整 hash、作者、日期和 commit message。
3. 确定范围: 对有效的 commit 按日期排序，确定时间最早和最晚的 commit。
4. 获取 Diff: 获取最早和最晚 commit 之间的 diff 内容 (或单个 commit 的 diff)。
5. 处理 Diff: 根据配置限制增删行数。
6. 构建 Prompt: 将 commit messages 和处理后的 diff 内容组合成 Prompt，指示 LLM 以业务/功能角度总结每个变更点，并在每个 <item> 标签内附带 1-2 个最相关的关键文件路径，要求输出特定 XML 格式。
7. 调用 LLM: 使用 openai 库将 Prompt 发送给配置的 LLM API。
8. 解析响应: 使用正则表达式解析 LLM 返回的 XML 字符串，提取出每个 <update> 块中的 <hashes>, <time_range> 以及各个分类下的 <item> 列表。
9. 填充作者: 根据解析出的 <hashes>，从步骤 2 获取的 commit 信息中查找并填充每个 <update> 的作者字段。
10. 渲染输出: 使用 summary_template.md 作为 Jinja2 模板，将包含作者信息的结构化数据渲染成最终的 Markdown 文本。
11. 写入文件: 将渲染好的 Markdown 内容写入到指定的输出目录和文件中。

脚本期望 LLM 返回类似以下的 XML 格式:

<summary>
  <update>
    <!-- LLM 不应包含 author -->
    <hashes>abc123d, def456e</hashes>
    <time_range>YYYY-MM-DD - YYYY-MM-DD</time_range>
    <added>
      <item>实现了用户注册流程 (相关文件: src/handlers/auth/register.go, src/models/user.go)</item>
      <item>添加了 API 文档生成器 (相关文件: docs/generator.py)</item>
    </added>
    <changed>
      <item>优化了登录接口的数据库查询性能 (主要涉及: src/db/user_queries.go)</item>
    </changed>
    <!-- 其他分类如 <fixed>, <removed> 等 -->
  </update>
</summary>

解析后的数据（包含脚本自动填充的作者信息）会传递给 summary_template.md 模板进行渲染。模板使用简单的列表结构展示每个分类下的变更项。

• 模板: 编辑 summary_template.md 文件以更改输出 Markdown 的外观。
• LLM Prompt: 修改 main 函数中构建 prompt_template 的部分，可以微调给 LLM 的指令（例如，如何格式化附加的文件名，或要求的文件数量）。
• XML 解析: 如果 LLM 返回的 XML 结构不稳定，或 <item> 内容格式难以用模板处理，可以修改 parse_llm_response 函数进行更复杂的解析。
• Diff 处理: 调整 process_diff 函数或 MAX_..._LINES_PER_FILE 配置。

欢迎提交 Issue 或 Pull Request 来改进这个项目！

本项目采用 MIT 许可证 (如果需要，请自行添加 LICENSE 文件)。