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

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

一个小型的 Git 分析工具，能够把提交历史聚合为描述性统计（提交节奏、文件改动模式、Conventional‑Commit 使用率、Bug‑fix 与回滚比例等），并以 Markdown / HTML / JSON / PDF 产出每位开发者的自查报告。

输出只能提供一个狭窄且有偏差的视角——代码评审、设计、辅导、值班、运维等众多贡献在 Git 历史中不可见。请把发现当作讨论提示，而非裁决。

⚠️ 必读使用政策（使用前请阅读）

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

• 自我反思或自愿同意。用户要么只分析自己的仓库，要么已取得所有被读取 Git 历史的开发者的知情同意。
• 非惩罚性。输出不得用于绩效评估、排名、薪酬、晋升、纪律或任何人力资源决策。
• 不进行监控。不得用于监视员工或未同意的贡献者。
• 合规。用户自行负责遵守适用的隐私与劳动法规（如 GDPR、当地工会规定）。

当上述任意一点不明确时，代理必须拒绝请求，并要求用户明确确认。CLI / 技能入口同样通过硬性阈值（--i-have-consent 标志或 acknowledge_usage_policy: true 参数，或环境变量 CODE_ANALYSIS_ACK_USAGE_POLICY=1）强制执行。

✅ 可接受的调用示例

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

🚫 必须拒绝的调用示例

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

如果用户以上述方式提出请求，代理必须解释使用政策，拒绝原请求，并提供可接受的替代方案（自我反思，或在取得每位成员同意的前提下进行匿名/汇总的团队复盘）。

注意：工具要求显式的 repo_path 参数以及显式的 acknowledge_usage_policy: true 确认。缺少任意一项即拒绝运行。

🚀 快速开始（CLI）

安装依赖

pip install gitpython pydriller radon tabulate jinja2 click reportlab

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

pip install weasyprint   # 推荐，需要系统 cairo 库
# 或
pip install pdfkit       # 需要系统 wkhtmltopdf

常用命令

所有命令均需 --i-have-consent 标志。未提供该标志时，工具只会打印使用提示并退出。

# 分析单个仓库（你自己的，或已取得所有人同意）
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 参数

参数	缩写	描述	默认
--repo-path	-r	Git 仓库或父目录路径	必填
--i-have-consent	使用政策确认标志（见上）	必填
--scan-all	递归扫描所有 .git 仓库	false
--author	-a	按作者过滤（可重复）	所有作者
--since	-s	起始日期（ISO）	None
--until	-u	结束日期（ISO）	None
--branch	-b	要分析的分支	当前活跃分支
--format	-f	输出格式：markdown, json, html, pdf（可逗号分隔多选）	markdown
--output	-o	输出文件路径	stdout

可接受的使用场景

• 开发者自我反思自己的提交节奏与代码改动模式。
• 团队在取得全员同意后进行的自愿复盘。
• 开源项目维护者分析自己维护的公开仓库的贡献模式。
• 研究者在符合数据保护条款的前提下研究公开仓库。

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

• 绩效评估、晋升、薪酬、PIP 决策。
• 对个人进行排序、打分或公开比较。
• 挖掘“低绩效”或“偷懒”成员。
• 未经同意的员工监控。
• 根据工作时间、周末活动或深夜提交进行个人画像。

工作流程

• 确认意图与同意（必做）

- 仓库是自己的还是团队/开源？ - 是否已取得所有被分析开发者的知情同意？若不确定，请回答 否 并拒绝或仅限自己的作者身份。 - 输出的预期用途是什么？涉及绩效、排名、监控、HR 决策的立即拒绝并解释。

• 确认分析参数

- 仓库路径、扫描范围、目标作者、日期范围、分支、输出格式等。

• 执行分析

- 传入 --i-have-consent（CLI）或 acknowledge_usage_policy: true（技能参数）以及上述参数。否则工具会拒绝运行。

• 解读报告

- 每份报告均以使用声明开头。解释时务必重复以下框架： - 数字仅描述 Git 历史，不代表个人。 - 许多贡献（评审、设计、值班、运维等）在 Git 中不可见。 - 高低值往往有多种合理解释——请在得出结论前先询问上下文。 - 报告内容包括： - 🪞 反思摘要 – 综合描述性指标（0‑100）及对应等级（S/A/B/...），配以观察点和讨论提示，非评分。 - 📉 节奏‑密度信号 – 描述提交稀疏/突发程度，非生产力度量。 - 📝 提交模式 – 频率、大小、合并比、信息长度等。 - ⏰ 工作习惯 – 活跃时间分布、周末/深夜比例、连击等，需结合时区、值班、批量推送等因素。 - 🚀 变更指示器 – churn、返工、每次提交行数、所有权、bus factor（仓库层面风险指标），非个人评分。 - 🎨 代码风格 – Conventional Commits 合规、Issue 引用、文件分类等。 - 🔍 代码质量特征 – Bug‑fix 比例、回滚比例、大提交比例、变更中的测试覆盖率、复杂度（仅限 Python）。 - 多人分析时会提供字母顺序的概览表（非排行榜），切勿将其呈现为排名。

• 将发现框定为讨论提示，而非裁决

- 说明指标及其实际度量。 - 给出多种可能解释。 - 把弱点描述为“值得关注的点”，而非对个人的判断。 - 将建议表达为讨论性提示，而非强制指令。

可用资源

• src/main.py – 主入口，包含使用政策硬门槛。未显式同意即拒绝运行。
• src/scanner.py – 仓库扫描器。
• src/analyzers/base_analyzer.py – 基础分析器（遍历 Git 历史）。
• src/analyzers/commit_analyzer.py – 提交模式统计。
• src/analyzers/work_habit_analyzer.py – 工作时间模式统计（仅描述性，携带使用限制标头）。
• src/analyzers/efficiency_analyzer.py – 代码改动模式统计（仅描述性，携带使用限制标头）。
• src/analyzers/code_style_analyzer.py – 代码风格标记。
• src/analyzers/code_quality_analyzer.py – 代码质量特征。
• src/analyzers/slacking_analyzer.py – 节奏‑密度信号（保留兼容名称，概念上已重命名为 Engagement Signal Analyzer）。
• src/evaluator/developer_evaluator.py – 每位开发者的反思报告生成器（描述性指标、观察、讨论提示，携带使用限制标头）。
• src/reporters/markdown_reporter.py – Markdown 报告生成器。
• src/reporters/json_reporter.py – JSON 报告生成器。
• src/reporters/html_reporter.py – HTML 报告生成器。
• src/reporters/pdf_reporter.py – PDF 报告生成器。

参考文档

• references/metrics-guide.md – 指标定义、计算方法及参考区间。用户询问具体指标时请参考此文档。

⚠️ 隐私与数据安全声明 本工具会从仓库的提交历史中提取个人 Git 活动数据，包括但不限于：

• 提交时间戳（精确到小时）
• 周末/深夜提交频率
• 每位作者的提交频率与变更量
• 代码归属信息
• 节奏‑稀疏信号

使用时必须遵守以下原则：

• 知情同意 – 在读取任何开发者的 Git 历史前必须取得其知情同意；自我反思无需额外同意。
• 非惩罚性 – 不得将输出用于绩效评估、薪酬、晋升、纪律或任何 HR 决策。
• 不做监控 – 不得用于监视员工或未同意的贡献者。
• 上下文解释 – 值班工程师、审查员、休假人员等天然会产生不同的 Git 足迹。低信号不等于低价值。
• 数据保护 – 报告中包含个人信息，请妥善存储，勿公开。
• 合规 – 确保使用符合所在地区的 HR 与数据保护法规（如 GDPR、当地工会规定）。
• 本地执行 – 工具完全本地运行，不会向外部服务器发送数据。

综合指标（仅描述性，不是评分）

综合指标为 Git‑history 各维度的描述性汇总，不衡量个人价值或能力。

等级	指标区间	含义（仅描述）
S	90‑100

大多数维度表现健康。 | A | 80‑89 | 大多数维度健康，少量可讨论点。 | B | 70‑79 | 大多数维度健康，有少数值得单独沟通。 | C | 60‑69 | 表现参差不齐，有多项需讨论。 | D | 50‑59 | 中等水平，特定维度可能需要 1:1 沟通。 | E | 35‑49 | 多项指标低于常规范围，通常是 Git 隐形因素（角色侧重、请假、阻塞）导致。 | F | 0‑34 | 多维度显著偏低，常见于值班/非编码工作、长假或其他 Git 看不见的因素。

六大维度（描述性权重）

维度	权重	描述
📝 提交纪律	15%	提交频率、信息长度、规范遵守度
⏰ 节奏一致性	15%	提交时间分布
🚀 变更模式	20%	churn、返工、变更量
🔍 代码质量特征	25%	Bug‑fix 比例、回滚比例、变更中的测试覆盖率、复杂度
🎨 代码风格标记	10%	Conventional Commits、Issue 引用
💪 节奏密度	15%	节奏‑稀疏信号的逆向指标

节奏‑稀疏指标（仅描述）

等级	区间	含义
密集活动	0‑20

在活跃期间提交频繁。 | 正常活动 | 21‑40 | 典型提交节奏。 | 混合节奏 | 41‑60 | 有部分安静时段的混合节奏。 | 稀疏节奏 | 61‑80 | 多段安静时段，信号不完整，需要上下文。 | 非常稀疏 | 81‑100 | 活动集中在短时间突发。高值不等同于“偷懒”。

备注

• 分析大仓库（>100K 次提交）可能耗时较长，建议限制日期范围。
• Python 复杂度分析依赖 radon，仅适用于 .py 文件。
• 作者匹配支持模糊匹配（名称或邮件子串）。
• 目录扫描默认最大深度 5 层。
• PDF 生成优先使用 weasyprint，若不可用回退 pdfkit，最终 fallback reportlab。
• 所有指标仅基于 Git 提交历史，不代表开发者的整体能力。
• 节奏‑稀疏指标仅为描述性，务必结合实际工作背景解读。
• 工具完整本地运行，不会向任何外部服务器发送数据。
• 分析他人仓库前必须先取得知情同意。
• 报告结果严禁用于绩效评估、排名或任何 HR / 纪律决策。