周报全自动：从 Git 记录到成稿的一条龙

flowchart LR
    A["① 拉取提交 fetch<br />git log 取 subject/author/date<br />判定:只读信息,绝不读 diff"] --> B["② 时间窗过滤 filter<br />Python 侧按日期比较<br />判定:窗口起点可复现"]
    B --> C["③ 按类型归类 classify<br />约定式提交前缀 feat/fix/...<br />判定:无前缀归'其他'单列"]
    C --> D["④ 模板渲染 render<br />按分类生成 Markdown<br />判定:输出可复现"]
    D --> E["⑤ 成稿归档 archive<br />按日期存文件<br />判定:0条判失败 exit 1"]
    E -.->|"可选"| F["接 WorkBuddy 定时<br />每周五自动跑<br />判定:失败有人喊,不静默"]
    F -.->|"可选"| G["接 ima 知识库<br />打 周报 标签<br />判定:攒一月能问答"]

"""
weekly_report.py —— 周报自动生成器（示例代码，已实测可运行）
流程：git 拉取全部提交 -> Python 侧按时间窗过滤 -> 按类型归类 -> 模板渲染 -> 成稿归档
依赖：仅 Python 标准库 + 本地 git 命令（git 须在 PATH 中）
重要：脚本只读取提交信息（subject/author/date），绝不读取 diff，避免泄露源码与密钥。
为何时间窗在 Python 侧算、不交给 `git --since`：`git --since` 的边界判定依赖提交时间戳时区与本地时区，
相对表述（如 7 days ago）在不同环境下容易产生边界漂移，实测中无法稳定复现同一窗口结果；
把窗口比较放在 Python 里、以显式日期为起点，结果可复现。
"""
import argparse
import datetime as dt
import re
import shutil
import subprocess
from pathlib import Path

# 约定式提交（Conventional Commits）前缀 -> 中文分类
TYPE_LABELS = {
"feat": "新功能",
"fix": "缺陷修复",
"docs": "文档",
"refactor": "重构",
"perf": "性能优化",
"test": "测试",
"style": "格式调整",
"chore": "杂项",
"build": "构建/依赖",
"ci": "CI/构建",
}
ORDER = list(TYPE_LABELS.keys()) + ["other"]

def git_available() -> bool:
return shutil.which("git") is not None

def pull_all(repo: str, author: str) -> list[dict]:
"""拉取全部提交，仅取 hash/author/committer日期/subject，绝不取 diff。"""
# 字段用 \x1f（单元分隔符）分隔，避免与提交内容中的逗号/空格冲突
# %ci = committer 日期，类 ISO 8601（ISO 8601-like，形如 2026-10-22 10:00:00 +0800）；过滤时只取前 10 位日期部分。若只需 YYYY-MM-DD，可直接改用 %cs
fmt = "%H%x1f%an%x1f%ci%x1f%s"
cmd = ["git", "-C", repo, "log", f"--pretty=format:{fmt}"]
if author:
cmd.append(f"--author={author}")
proc = subprocess.run(cmd, capture_output=True, text=True)
if proc.returncode != 0:
raise RuntimeError(proc.stderr.strip() or "git log 执行失败")
rows = []
for line in proc.stdout.splitlines():
parts = line.split("\x1f")
if len(parts) != 4:
continue
h, who, cdate, subject = parts
rows.append({"hash": h[:8], "author": who, "cdate": cdate.strip(), "subject": subject.strip()})
return rows

def parse_since(since: str) -> dt.date:
"""支持 '7 days ago' / '14 days ago' / '2026-10-20' 三种写法，返回窗口起始日期（含）。

'N days ago' 按「过去 N 个自然日（含今天）」解释：起点 = 今天 - (N-1) 天，
配合 in_window 的 >= 比较，窗口正好覆盖 N 个自然日。
"""
s = since.strip().lower()
m = re.match(r"^(\d+)\s*days?\s*ago$", s)
if m:
return dt.date.today() - dt.timedelta(days=int(m.group(1)) - 1)
m2 = re.match(r"^(\d{4}-\d{2}-\d{2})$", s)
if m2:
return dt.date.fromisoformat(m2.group(1))
raise ValueError(f"无法解析 --since 参数：{since!r}（支持 '7 days ago' 或 '2026-10-20'）")

def in_window(cdate: str, cutoff: dt.date) -> bool:
# cdate 形如 '2026-10-22 10:00:00 +0800'，取前 10 位按提交者本地日期比较，不做跨时区换算，保证边界稳定
return dt.date.fromisoformat(cdate[:10]) >= cutoff

def classify(subject: str) -> str:
# scope 用字符类 [(] / [)] 表示括号，避免反斜杠转义在渲染或复制时丢失
m = re.match(r"^(feat|fix|docs|refactor|perf|test|style|chore|ci|build)([(][^)]+[)])?!?:", subject, re.I)
return m.group(1).lower() if m else "other"

def render(rows: list[dict], out_dir: Path, repo_name: str, window: str) -> Path:
by_type: dict[str, list[dict]] = {}
for r in rows:
by_type.setdefault(classify(r["subject"]), []).append(r)

lines = [
f"# 周报 · {repo_name}（窗口：{window}）",
"",
"> 数据来源：git log（仅提交信息，不含 diff）",
f"> 提交总数：{len(rows)}",
"",
]
for t in ORDER:
items = by_type.get(t)
if not items:
continue
label = TYPE_LABELS.get(t, "其他")
lines.append(f"## {label}（{len(items)}）")
for r in items:
lines.append(f"- [{r['cdate'][:10]}] {r['subject']}  _{r['hash']}_")
lines.append("")

out_dir.mkdir(parents=True, exist_ok=True)
path = out_dir / f"周报-{repo_name}-{window.replace(' ', '_')}.md"
path.write_text("\n".join(lines), encoding="utf-8")
return path

def main() -> int:
ap = argparse.ArgumentParser()
ap.add_argument("--repo", default=".", help="仓库路径，默认当前目录")
ap.add_argument("--since", default="7 days ago", help="时间窗起点：'7 days ago' 或 '2026-10-20'，默认近 7 天（含当天共 7 个自然日）")
ap.add_argument("--author", default="", help="按作者过滤，留空不过滤")
ap.add_argument("--out", default="weekly", help="成稿输出目录")
args = ap.parse_args()

if not git_available():
print("[error] 未找到 git 命令，请先安装并加入 PATH")
return 2

try:
cutoff = parse_since(args.since)
except ValueError as e:
print(f"[error] {e}")
return 2

all_rows = pull_all(args.repo, args.author)
rows = [r for r in all_rows if in_window(r["cdate"], cutoff)]
if not rows:
# 守卫：空窗口直接判失败，避免生成"空白周报"还假装成功
print(f"[error] 窗口（{cutoff.isoformat()} 起）内没有提交，周报无法生成（请检查 --since 或 --author）")
return 1

path = render(rows, Path(args.out), Path(args.repo).resolve().name, args.since)
print(f"[done] 拉取 {len(all_rows)} 条提交，窗口内 {len(rows)} 条，分 {len({classify(r['subject']) for r in rows})} 类")
print(f"[done] 周报已生成：{path}")
return 0

if __name__ == "__main__":
raise SystemExit(main())

$ python weekly_report.py --repo ./repo --since "7 days ago" --out weekly
[done] 拉取 6 条提交，窗口内 4 条，分 4 类
[done] 周报已生成：weekly/周报-repo-7_days_ago.md

# 周报 · repo（窗口：7 days ago）

> 数据来源：git log（仅提交信息，不含 diff）
> 提交总数：4

## 新功能（1）
- [2026-10-23] feat(auth): 支持企业微信扫码登录  _d0f6f37e_

## 缺陷修复（1）
- [2026-10-24] fix(export): 修复导出大文件时内存溢出  _d6694598_

## 文档（1）
- [2026-10-26] docs: 补充定时任务配置说明  _c232aa07_

## 性能优化（1）
- [2026-10-28] perf(report): 周报渲染耗时从 800ms 降到 120ms  _a786b045_

$ python weekly_report.py --repo ./repo --since "2026-10-30" --out weekly
[error] 窗口（2026-10-30 起）内没有提交，周报无法生成（请检查 --since 或 --author）

flowchart TD
    S["一条 commit subject<br />例: feat(auth): 支持扫码登录"] --> M{"匹配正则<br />^(feat|fix|docs/...)!?:"}
    M -->|"匹配"| T["取前缀作分类<br />feat 新功能 / fix 缺陷修复"]
    M -->|"不匹配"| O["归入'其他'<br />判定:人工补分类或推行约定式提交"]

flowchart TD
    E["周报不对劲"] --> Q1{"生成的周报是空的?"}
    Q1 -->|"是"| C1["时间窗/作者过滤太窄<br />看 [error] 提示<br />判定:放宽 --since 或去掉 --author"]
    Q1 -->|"否"| Q2{"分类大量落到'其他'?"}
    Q2 -->|"是"| C2["提交未用约定式前缀<br />判定:推行 Conventional Commits"]
    Q2 -->|"否"| Q3{"含敏感/内部信息?"}
    Q3 -->|"是"| C3["脚本误读了 diff<br />判定:确认只读 subject,绝不 git show"]
    Q3 -->|"否"| Q4{"接定时后不按时跑?"}
    Q4 -->|"是"| C4["本地任务关机即停/权限不足<br />判定:看运行记录+开启推送"]

flowchart LR
    L1["第1级 手动脚本<br />你敲命令它跑<br />判定:代码实测跑通+日志可见"] --> L2["第2级 定时自动<br />WorkBuddy 到点执行<br />判定:失败有推送,不静默"]
    L2 --> L3["第3级 沉淀知识库<br />周报进 ima 打标签<br />判定:攒一月能问答检索"]
    L3 --> L4["第4级 多项目汇总<br />多仓库合并成月报<br />判定:每步仍可单独验证"]