release-note-generator

name	release-note-generator
description	Generates release notes from git commits/diffs and outputs one Chinese MD file. Invoke when user asks for release notes bounded by previous non-alpha version.

Release Note Generator

用于基于当前仓库的 git 历史自动生成发布说明，确保不遗漏提交，并为每条变更记录追加提交人的 GitHub ID（@id）。默认输出一个 Markdown 文件到 .trae/documents 目录：变更内容。

触发时机

• 用户要求生成 Release Note / 更新日志
• 用户要求基于最近提交和实际代码变更做汇总
• 用户要求以“上一个非 alpha 版本”为边界统计变更

输入约定

• 默认分支当前 HEAD
• 版本边界规则：从最新提交向后遍历，遇到“提交信息包含版本号且不含 alpha”的最近一个提交作为边界
• 若用户指定分支、Tag 或版本正则，优先使用用户指定
• 未指定时，默认输出文档路径为：.trae/documents/release_notes-<version>.md

实战经验（本项目）

• 不直接依赖终端长输出：大量 git log 在终端中容易被截断，导致误判“提交缺失”
• 不用 | 等普通分隔符解析：提交标题可能包含分隔符，必须使用 NUL 分隔（\x00）保证可解析
• 统一 UTF-8：PowerShell 下中文提交信息可能乱码，调用 git 时需显式设置输出编码
• 避免在 RunCommand 的内联脚本中直接硬编码中文常量（标题、分类名、文件名）：在 Windows/PowerShell 链路中可能被替换为 ?
• 发布文件名使用 ASCII：不要在文件名中使用中文（如 ReleaseNotes-变更内容-<version>.md），否则编码异常时会变成非法字符 ? 导致写文件失败
• 中文文案仅放在 Markdown 内容里，并在写入后做一次乱码校验：若出现 ???、### ?? 等占位符，必须重新生成
• 明确分支范围：优先使用 HEAD 可达历史，必要时用 --first-parent 辅助核对发布主线
• 先计数再明细：先取 rev-list --count，再逐条采集，最后做数量一致性校验
• 版本边界要可回退：目标版本不存在时，自动回退到最近可识别的“上一非 alpha 版本”并在结果中声明

日志采集方式（强制）

• 必须使用 Python 脚本拉取 commit 与 diff，不直接用终端拼接命令产出最终结果
• Python 内通过 subprocess.run([...], check=True, capture_output=True, text=True, encoding="utf-8", errors="replace") 调 git