commit-chronicle — turn any git repository's commit history into a weekly changelog post (pure stdlib)
commit-chronicle 把任意 git 仓库过去一段时间的提交史，折叠成一篇结构化的周记 Markdown：按 conventional 前缀（feat/fix/docs/chore/refactor/其他）分组，给出本周亮点、修复清单、其他变更和数字摘要（提交数 / 增删行），并自动用 ISO 周号命名 posts/YYYY-Www.md。纯 Python 标准库，零依赖，确定性输出（同样的输入永远产生同样的字节）。
真实示例：本仓库的 examples/sample-week.md 就是用本工具对真实 git 仓库（gitgrave 的提交史）生成的 dogfood 产物，不是编造。
- 想着手写周报/周更博客，但懒得从
git log里人肉整理。 - 想给团队或订阅者一份结构稳定、可自动发布的周变更摘要。
- 想在 CI 里每周自动更新博客的 posts 目录（附带了 GitHub Action）。
无需安装依赖（标准库 + 系统 git）。两种运行方式：
# 直接以模块运行（推荐）
python -m commit_chronicle.cli --help
# 或 pip 安装为命令行工具
pip install .
commit-chronicle --help要求：Python ≥ 3.10，PATH 上有 git。
# 1) 生成当前仓库最近 7 天的周记，写入 posts/2026-W35.md
python -m commit_chronicle.cli .
# 2) 指定日期窗口，输出到 stdout（hash 变成链接）
python -m commit_chronicle.cli . --since 2026-08-19 --until 2026-08-25 \
--repo-url https://github.com/me/project --stdout
# 3) 指定输出文件（供示例/CI 使用）
python -m commit_chronicle.cli /path/to/repo --since 2026-08-19 \
--out-dir examples --output sample-week.md# GitGrave 周记 2026-W35（2026-08-25 ~ 2026-08-25）
过去一周（2026-08-25 ~ 2026-08-25）项目共 **2** 个提交（+223 行 / -16 行），亮点与修复如下。
## 本周亮点
- `59c8a1e` feat: v0.1.0 — GitGrave 死代码讣告墓园（stdlib only）
## 修复清单
- `6df7ebd` fix(review): Windows只读夹具清理、CLI UTF-8输出、pyproject>=3.10、帮助文本测试静音
## 数字摘要
本周共 **2** 个提交，新增 **+223** 行，删除 **-16** 行。
> 生成时间：2026-08-25 20:00:00（本地时区）· 由 commit-chronicle v0.1.0 生成（以上为模拟排版；完整真实输出见 examples/sample-week.md。）
| 参数 | 说明 |
|---|---|
repo |
git 仓库路径（默认 .） |
--days N |
最近 N 个自然日（含今天，默认 7；与 --since 互斥） |
--since YYYY-MM-DD |
起始日期（含当天 00:00 起） |
--until YYYY-MM-DD |
截止日期（含当天 23:59:59，默认今天） |
--repo-url URL |
仓库主页 URL；给定时提交 hash 渲染为 [abc1234](URL/commit/abc1234) |
--repo-name NAME |
周记标题里的仓库名（默认取 origin remote 或目录名） |
--out-dir DIR |
输出目录（默认 posts） |
--output FILE |
输出文件名（默认 YYYY-Www.md，Www 为窗口截止日的 ISO 周号） |
--stdout |
不写文件，直接打印 Markdown |
--ai-endpoint URL |
OpenAI 兼容 chat/completions 端点，用于润色开头导语 |
--ai-key KEY |
Bearer token（缺省读取环境变量 COMMIT_CHRONICLE_AI_KEY） |
--ai-model MODEL |
AI 模型名（默认 gpt-4o-mini） |
--ai-timeout SEC |
AI 请求超时（默认 30 秒） |
--version |
打印版本 |
分组规则：提交标题匹配严格小写 type(scope): subject 形式；feat→本周亮点、fix→修复清单、docs/chore/refactor→其他变更子节；不匹配或未知前缀（如 perf/test/ci）归入「其他变更」。
不传 --ai-endpoint 时工具完全不发起网络请求，导语由内置模板生成。传了端点则调用一次 OpenAI 兼容接口生成 2~3 句中文导语；任何失败（无网络、超时、非 200、解析失败）都自动降级为模板导语，不影响产出。
export COMMIT_CHRONICLE_AI_KEY="sk-..."
python -m commit_chronicle.cli . --days 7 \
--ai-endpoint https://api.openai.com/v1/chat/completions仓库自带 action.yml（composite action）：在 checkout 之后的仓库上运行本工具，并把生成的 posts/ 提交回去。用法见 docs/action-setup.md。
- uses: only-aa/commit-chronicle@v1
with:
days: 7
repo-url: https://github.com/only-aa/commit-chronicle- v0.1.0：核心周记生成（收集/分组/模板/数字摘要/ISO 周号），CLI + 确定性输出
- 多周合并报告（--weeks 3 生成月报）
- 按 author 的作者维度统计与排行榜
- 推送渠道插件：GitHub Discussion、邮件、Telegram
- sitemap / RSS 聚合脚本
MIT — 见 LICENSE。贡献者：2025 commit-chronicle contributors。
$ commit_chronicle --helpIssues and PRs welcome - run pytest locally before submitting.