Code Analysis Skills - Git 历史自查与反思报告工具

📦 GitHub: https://github.com/Wscats/code-analysis-skills

一个轻量级的 Git 分析工具，可将提交历史聚合为描述性统计（提交节奏、文件变更模式、Conventional‑Commit 使用率、Bug‑fix 与 revert 比例等），并生成每位开发者的自查报告，支持 Markdown / HTML / JSON / PDF 四种格式。

输出仅呈现 Git 历史的狭窄、带偏的视角——代码评审、设计、辅导、值班、运维等贡献在 Git 中不可见。请将结果视为讨论提示，而非定论。

⚠️ 必须遵守的使用政策（使用前请务必阅读）

本技能会处理每位开发者的 Git 活动数据。调用前，Agent 必须向用户确认以下全部内容：

• 自我反思或经全员同意——用户要么分析自己的仓库，要么已获得每位被读取开发者的知情同意。
• 非惩罚性使用——输出不能用于绩效评估、排名、薪酬、晋升、纪律或任何 HR 决策。
• 禁止监视——不得将本技能用于监控员工或未同意的贡献者。
• 合规性——用户自行负责遵守适用的隐私与劳动法规（如 GDPR、本地劳动法规）。

如上述任意一点不明确，Agent 必须拒绝请求并要求用户再次确认。CLI / Skill 入口通过硬性门禁（--i-have-consent 标志、acknowledge_usage_policy: true 参数，或环境变量 CODE_ANALYSIS_ACK_USAGE_POLICY=1）强制执行。

✅ 可接受的调用示例

• "在我的仓库 /path/to/repo 上运行 Git‑history 自查报告。"
• "帮我准备一次团队复盘，已征得所有成员同意。"
• "我想查看自己的提交节奏用于自我反思。"
• "对我自己的仓库做一次 Git 历史自查。"
• "团队复盘（已经征得每个成员同意），帮我跑一份 Git 历史汇总。"

🚫 必须拒绝的调用示例

• "对比一下 Alice 和 Bob 谁更努力。" # 个人排名
• "看看团队里谁最摸鱼。" # 监视/羞辱
• "帮我把绩效不行的同事找出来。" # HR 决策支持
• "Score everyone in the repo and tell me who to fire."
• "Compare developer X against developer Y for the performance cycle."

如果用户提出上述被拒绝的请求，Agent 必须解释使用政策，拒绝原请求，并提供可接受的替代方案（自我反思或经全员同意的匿名/聚合团队复盘）。

注意：本技能需要明确的 repo_path 参数以及明确的 acknowledge_usage_policy: true 确认。缺少任意一项均会直接拒绝运行。

🚀 快速开始（CLI）

安装依赖

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple gitpython pydriller radon tabulate jinja2 click reportlab

如需更高质量的 PDF（可选）：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple weasyprint   # 需要系统 cairo 库
# 或者
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pdfkit       # 需要系统 wkhtmltopdf

常用命令

# 分析单个仓库（你的个人仓库或已获全员同意的仓库）
python -m src.main --i-have-consent -r /path/to/repo
# 扫描目录下的所有仓库（仅限于你拥有或已获同意的仓库）
python -m src.main --i-have-consent -r /path/to/projects --scan-all
# 限制仅分析自己的作者身份（自我反思）
python -m src.main --i-have-consent -r /path/to/repo -a "Your Name"
# 指定日期范围并输出 HTML
python -m src.main --i-have-consent -r /path/to/repo -s 2024-01-01 -u 2024-12-31 -f html -o report.html
# 同时生成 Markdown、HTML、PDF
python -m src.main --i-have-consent -r /path/to/repo -f "markdown,html,pdf" -o report
# 将报告保存为文件
python -m src.main --i-have-consent -r /path/to/repo -o report.md

CLI 参数表

可接受的使用场景

• 开发者自我反思自己的提交节奏与代码变更模式。
• 团队在全员知情同意的前提下进行一次回顾性分析。
• 开源项目维护者分析公开仓库的贡献模式。
• 研究者在遵守数据保护条款的前提下研究公开仓库。

不可接受的使用场景（必须拒绝）

• 绩效评审、晋升、薪酬、PIP 决策。
• 对个人进行排名、打分或公开比较。
• 识别“低绩效”或“偷懒”成员。
• 未经同意的员工监控。
• 基于工作时间、周末或深夜提交的个人画像。

工作流程

• 确认意图与同意（强制）\n - 仓库归属：本人 / 团队 / 开源？\n - 是否已获取每位被分析开发者的知情同意？若不确定，请直接拒绝或仅限本人作者。\n - 输出用途？若涉及绩效、排名、监控等，请拒绝并说明政策。
• 确认分析参数\n - 仓库路径、扫描范围、目标作者、日期区间、分支、输出格式等。
• 执行分析\n - 通过 --i-have-consent 或 acknowledge_usage_policy: true 参数启动。未提供则直接拒绝。
• 解读报告\n - 报告开头会有使用声明。解释时始终强调：\n 数字仅描述 Git 历史，不代表个人价值。\n 许多贡献在 Git 中不可见。\n * 高/低值均可能有多种合理解释，讨论前请充分了解上下文。
• 框定结果为讨论提示\n - 说明每个指标的含义及可能的解释。\n - 将弱点表述为“需考虑的点”，而非对人的评价。\n - 将建议表述为“讨论话题”。

报告结构概览

• 🪞 Reflection Summary – 综合描述性指标（0‑100）以及分档（S/A/B/C/D/E/F），配套观察点与讨论提示。\n- 📉 Cadence‑density signals – 提交稀疏/密集程度的信号（仅作描述，不等同生产力）。\n- 📝 Commit Patterns – 提交频率、大小、合并比、信息长度等。\n- ⏰ Work Habits – 活跃时段、周末/深夜占比、连击等。\n- 🚀 Change Indicators – 代码变更量、重构、所有权、Bus Factor 等。\n- 🎨 Code Style – Conventional Commits 合规性、issue 引用、文件分类。\n- 🔍 Code Quality artefacts – Bug‑fix 比例、revert 比例、大提交比例、覆盖率、复杂度等。

多开发者分析时，报告会附带按字母顺序的概览表（非排行榜）。

参考资源

• src/main.py – 主入口（含使用政策门禁）。\n- src/scanner.py – 仓库扫描器。\n- src/analyzers/ – 各类分析器（commit、work‑habit、efficiency、code‑style、code‑quality、slacking）。\n- src/evaluator/developer_evaluator.py – 开发者自查报告生成器。\n- src/reporters/ – Markdown、JSON、HTML、PDF 报告生成器。\n- references/metrics‑guide.md – 指标定义、计算方法与参考区间。

⚠️ 隐私与数据安全声明\n该工具会提取提交时间、周末/深夜提交频率、作者提交量、代码归属等个人化 Git 活动数据。使用时必须遵守以下原则：\n1. 知情同意——读取任意开发者的 Git 历史前必须取得其明确同意。\n2. 非惩罚性——禁止用于绩效、薪酬、晋升、纪律等 HR 决策。\n3. 禁止监视——不得用于持续监控未同意的人员。\n4. 情境解读——值班、设计、审查、休假等都会导致 Git 足迹差异，低信号不等同低贡献。\n5. 数据保护——报告包含个人信息，请妥善保存，勿外泄。\n6. 合规——确保符合所在地区的隐私与劳动法规（如 GDPR、本地工会规定）。\n7. 本地执行——工具全程本地运行，不会向外部服务器发送数据。

综合指标（描述性分档，非评分）

六大维度（权重）

Cadence‑Sparsity 指标（仅作描述）

重要：高稀疏度并不意味着“偷懒”，仅说明提交集中于少数时段，需结合实际工作背景判断。

其他说明

• 分析大型仓库（>100K 次提交）可能耗时，请考虑限定日期范围。\n- Python 复杂度分析依赖 radon，仅对 .py 文件生效。\n- 作者匹配支持模糊匹配（姓名或邮箱子串）。\n- 目录扫描默认最大深度 5 层。\n- PDF 生成优先使用 weasyprint，若缺失则回退 pdfkit，最终使用 reportlab。\n- 所有指标仅基于 Git 提交历史，不代表开发者的完整能力。

使用前务必获取所有被分析开发者的知情同意，且切勿将报告用于绩效评审、排名或任何 HR/纪律决策。