engineering-retro

工程回顾

为可配置的时间范围生成基于 Git 的结构化工程回顾。这是只读分析——除可选的 JSON 快照外，不会修改任何文件。

参数

/engineering-retro [TIME_WINDOW] [PATH_SCOPE]

• TIME_WINDOW（可选）：24h、7d（默认）、14d、30d
• PATH_SCOPE（可选）：将分析范围限制在某个子目录（支持 monorepo），例如 services/api

示例：

• /engineering-retro — 最近 7 天，整个仓库
• /engineering-retro 30d — 最近 30 天，整个仓库
• /engineering-retro 14d services/api — 最近 14 天，范围限定为 services/api/

执行步骤

步骤 1：检测环境

开始分析前，先检测运行时上下文：

# Default branch
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$DEFAULT_BRANCH" ]; then
  DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
fi

# System timezone
TZ_NAME=$(date +%Z)

# Time window — convert argument to --since format
# 24h → "24 hours ago", 7d → "7 days ago", 14d → "14 days ago", 30d → "30 days ago"

如果 DEFAULT_BRANCH 检测失败，则报错并中止——不要猜测。

步骤 2：收集原始 Git 数据

收集检测到的默认分支在时间范围内的提交：

# All commits in window (with optional path scope)
git log origin/$DEFAULT_BRANCH --since="$SINCE" --format="%H|%aI|%aN|%s" -- $PATH_SCOPE

# Diff stats for the window
git log origin/$DEFAULT_BRANCH --since="$SINCE" --numstat --format="%H" -- $PATH_SCOPE

记录：提交哈希、作者日期（ISO 格式）、作者姓名、主题行、变更文件、添加行数、删除行数。

步骤 3：计算汇总指标

根据原始数据计算：

• 时间范围内的提交总数
• 唯一贡献者（不同作者姓名）
• 变更文件数（所有提交中不重复的文件路径）
• 添加行数（添加行数之和）
• 删除行数（删除行数之和）
• 净变化量（添加数 - 删除数）
• 平均提交规模（变更总行数 / 提交总数）

步骤 4：时间分布

分析提交时间戳（转换为系统时区 $TZ_NAME）：

• 每周各日的提交数：周一至周日的直方图
• 每小时的提交数：0 至 23 点的直方图
• 提交高峰日：提交数最多的日期
• 活跃高峰时段：活动最多的时段

以紧凑的文本直方图呈现。

步骤 5：工作时段分析

使用超过 2 小时的间隔作为时段边界，将提交分组为工作时段：

1. 按作者和时间戳排序提交
2. 对每位作者按时间顺序遍历——如果相邻提交间隔超过 2 小时，则开始新的时段
3. 计算每个时段的时长（从首次提交到最后一次提交）和提交数
4. 汇总：时段总数、平均时段时长、最长时段、每个时段的平均提交数

只有一次提交的时段，默认时长为 0（时间点）。

步骤 6：提交类型分类

根据主题行中的 Conventional Commit 前缀对每个提交分类：

前缀模式	类别
feat:、feat(	feature
fix:、fix(、bugfix	fix
refactor:、refactor(	refactor
chore:、chore(、build:、ci:	chore
docs:、doc:	docs
test:、tests:	test
perf:	perf
style:	style

对于不带 Conventional Commit 前缀的提交，使用 diff 启发式规则：

• 主要新增文件 → feature
• 主要删除文件 → refactor
• 仅包含测试文件 → test
• 仅包含配置/CI 文件 → chore
• 仅包含文档文件 → docs
• 其他情况 → uncategorized

报告每个类别的数量和百分比。

步骤 7：热点分析

按被提交修改的次数，找出修改最多的 10 个文件：

git log origin/$DEFAULT_BRANCH --since="$SINCE" --name-only --format="" -- $PATH_SCOPE | sort | uniq -c | sort -rn | head -20

将修改次数超过提交总数 50% 的文件标记为热点。热点可能表示：

• 活跃的开发区域（功能开发期间属预期情况）
• 潜在的耦合问题（无关提交持续修改同一文件）
• 可能需要拆分（如果文件较大）

步骤 8：PR 分析

如果远程仓库是 GitHub（检查 git remote get-url origin 是否包含 github.com）：

# Merged PRs in window
gh pr list --state merged --base $DEFAULT_BRANCH --search "merged:>=$SINCE_DATE" --json number,title,author,mergedAt,additions,deletions,changedFiles,reviews

计算：

• 已合并 PR 总数
• 规模分布：S（<50 行）、M（50-200 行）、L（200-500 行）、XL（>500 行）
• 评审周转时间：从 PR 创建到首次评审的时间（中位数、p90）
• 合并周转时间：从 PR 创建到合并的时间（中位数、p90）

如果远程仓库不是 GitHub，或 gh 不可用，则跳过此步骤并在输出中注明。

步骤 9：专注度分数

计算专注型提交（涉及 3 个或更少文件）占总提交数的比例：

focus_score = commits_touching_le_3_files / total_commits

解读：

• >0.8：专注度很高，变更较小且循序渐进
• 0.5-0.8：专注度适中，针对性变更与广泛变更并存
• <0.5：广泛变更占主导，可能表明存在大型重构或提交纪律较弱

步骤 10：按作者细分

对于每位贡献者，报告：

• 提交数
• 新增 / 删除行数
• 修改最多的 3 个文件
• 主要提交类型（来自步骤 6）
• 会话数和平均会话时长（来自步骤 5）

将此部分作为贡献者亮点，用于肯定已完成的工作，而非排名或绩效指标。按作者姓名的字母顺序排列。

步骤 11：逐周比较

检查 .engineering-retros/ 中是否有之前的快照：

• 找到最新的 *.json 文件
• 如果文件存在，且覆盖相邻的前一个时间窗口，则计算差值：
  • 提交数差值（%）
  • 变更行数差值（%）
  • 贡献者数量差值
  • 专注度分数差值
  • 类别分布变化

如果不存在之前的快照，注明这是首次回顾，并跳过比较。

步骤 12：保存快照

保存 JSON 快照，以便后续比较：

.engineering-retros/<YYYY-MM-DD>.json

架构：

{
  "date": "YYYY-MM-DD",
  "window": "7d",
  "path_scope": null,
  "branch": "main",
  "timezone": "PST",
  "metrics": {
    "commits": 0,
    "contributors": 0,
    "files_changed": 0,
    "lines_added": 0,
    "lines_removed": 0,
    "net_delta": 0,
    "focus_score": 0.0
  },
  "categories": {},
  "hotspots": [],
  "sessions": {
    "total": 0,
    "avg_length_minutes": 0
  },
  "authors": {},
  "pr_stats": null
}

如果 .engineering-retros/ 目录不存在，则创建该目录。确保 .engineering-retros/ 位于 .gitignore 中（如果缺少则添加——这是唯一允许修改的文件）。

步骤 13：生成总结说明

按以下结构生成最终输出：

---

工程回顾 — [DATE_RANGE]（[TIMEZONE]） 分支： [DEFAULT_BRANCH] | 范围： [PATH_SCOPE 或 "完整仓库"]

指标

• 提交：N | 贡献者：N | 变更文件：N
• 行数：+N / -N（净值：+/-N）
• 平均提交规模：N 行 | 专注度分数：N.NN

时间模式

• 提交高峰日：[DAY] | 提交高峰时段：[RANGE]
• [精简直方图]
• 会话：总计 N 次 | 平均时长：Nm | 最长：Nm

工作细分

• [类别]：N 次提交（NN%）
• ...

热点

• path/to/file — N 次提交 [HOTSPOT，若 >50%]
• ...

贡献者亮点

• [作者]：N 次提交，+N/-N 行，主要关注 [主要文件]，提交类型以 [类别] 为主
• ...

PR 总结（如有）

• 已合并：N | 规模分布：S/M/L/XL | 评审周转时间中位数：Xh

逐周比较（如有）

• 提交：+/-N% | 行数：+/-N% | 专注度：+/-N.NN

观察

• [2-4 条要点，指出模式、成果和值得关注的方面]
• 仅依据数据——不猜测意图，也不对个人作质量评价

---

约束

• 只读：不得修改代码、切换分支或执行会改变状态的 git 操作
• 不硬编码时区：始终通过 date +%Z 检测
• 不硬编码分支：始终通过 git symbolic-ref 或 git remote show 动态检测
• 不对个人作绩效评价：作者细分用于肯定贡献，而非评估表现
• 遵守路径范围：提供范围时，所有 git 命令都必须包含 -- $PATH_SCOPE
• 快照存储位置：仅限 .engineering-retros/，绝不使用 .context/retros/