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

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

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

报告只呈现 Git 历史的狭窄、偏颇视角——代码审查、设计、辅导、值班、运维等贡献在 Git 中不可见。请将发现视为讨论的切入点，而非裁决。

⚠️ 使用前必读的使用政策

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

• 自我反思或明确同意：用户要么只分析自己的仓库，要么已取得每位被读取历史的开发者的知情同意。
• 非惩罚性：输出不得用于绩效评估、排名、薪酬、晋升、处罚或任何 HR 决策。
• 不做监控：不得用于监控员工或未同意的贡献者。
• 合规：用户需自行确保遵守当地隐私与劳动法规（如 GDPR、本地工会条例）。

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

✅ 可接受的调用示例

• "Run a Git-history reflection report on my own repo at /path/to/repo."
• "Help me prepare a team retro — everyone has agreed to opt in."
• "I want to look at my own commit cadence for self-reflection."
• "对我自己的仓库做一次 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."

如果用户提出以上禁止请求，代理必须先解释使用政策，拒绝原请求，并提供可接受的替代方案（自我反思或全员同意的匿名/聚合报告）。

注意：该技能要求明确的 repo_path 参数以及明确的 acknowledge_usage_policy: true（或等价的 CLI 标志）。缺少任意一项即会拒绝运行。

🚀 快速开始（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）	无
--until	-u	结束日期（ISO）	无
--branch	-b	要分析的分支	当前分支
--format	-f	输出格式：markdown, json, html, pdf（可逗号分隔多选）	markdown
--output	-o	输出文件路径	stdout

可接受的使用场景

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

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

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

工作流

1️⃣ 确认意图与同意（强制） - 仓库属于谁？本人、团队还是开源？ - 是否已取得每位被分析开发者的知情同意？若不确定，请直接回答 “否” 并拒绝或仅限本人作者。 - 输出的用途是什么？若涉及绩效、排名、监控等，请拒绝并说明可接受的替代方案。 2️⃣ 确认分析参数 - 仓库路径、扫描范围、目标作者、日期范围、分支、输出格式等。 3️⃣ 执行分析 - 必须携带 --i-have-consent（CLI）或 acknowledge_usage_policy: true（参数）否则工具会直接退出。 4️⃣ 解读报告 - 每份报告均以使用声明开头。解释时需重复强调： - 数据仅展示 Git 历史，不等同于个人能力。 - 许多贡献（评审、设计、值班等）在 Git 中不可见。 - 高 / 低数值往往有多种合理解释，需在上下文中讨论。 - 报告结构包括： - 🪞 Reflection Summary（综合描述性得分 0–100，分段 S/A/B/C/D/E/F） - 📉 Cadence‑density signals（稀疏 / 集中程度） - 📝 Commit Patterns（频率、大小、合并比例、信息长度） - ⏰ Work Habits（活跃时段、周末/深夜比例、连击） - 🚀 Change Indicators（ churn、重工、行数、所有权、bus factor） - 🎨 Code Style（Conventional Commits、Issue 引用） - 🔍 Code Quality artefacts（Bug‑fix、回滚、测试覆盖、复杂度） - 多人分析时会额外提供按字母顺序的概览表（非排行榜），切勿把表格当作排名展示。 5️⃣ 以提示而非判决的方式呈现结论 - 说明指标的度量含义。 - 给出多种可能解释。 - 将不足之处表述为“待讨论点”。 - 将改进建议表述为“讨论提示”。

可用资源

• src/main.py — 主入口，带使用政策硬性门禁。
• src/scanner.py — 仓库扫描器。
• src/analyzers/ 系列模块：commit_analyzer.py、work_habit_analyzer.py、efficiency_analyzer.py、code_style_analyzer.py、code_quality_analyzer.py、slacking_analyzer.py（保留旧名称，仅为节奏稀疏信号）。
• src/evaluator/developer_evaluator.py — 每位开发者的反思报告生成器。
• src/reporters/ 系列：Markdown、JSON、HTML、PDF 报告生成器。

隐私与数据安全声明

本工具会提取仓库中个人提交的时间戳、周末/深夜提交频次、作者提交量与代码归属等信息。使用时必须遵循以下原则：

• 知情同意：在读取他人提交历史前取得明确同意；自我反思除外。
• 非惩罚性：输出不得用于绩效、薪酬、晋升或任何 HR 决策。
• 不做监控：不得用于监控未同意的贡献者。
• 上下文解释：值班、设计、审查等工作会导致 Git 足迹不同，低数值不等同于低贡献。
• 数据保护：生成的报告包含个人信息，请妥善存储，勿公开传播。
• 合规：确保符合所在地区的隐私与劳动法规（GDPR、本地工会条例等）。
• 本地执行：工具完全在本地运行，不会向外部服务器发送数据。

综合指示器（描述性分段，非评分）

分段	指标范围	含义（仅描述）
S	90–100	大多数维度表现健康。
A	80–89	大多数维度健康，存在少量可讨论点。
B	70–79	大多数维度健康，少数需 1:1 交流。
C	60–69	维度混杂，需多维度讨论。
D	50–59	中等水平，特定维度可能需要 1:1。
E	35–49	多项指标低于常规范围，通常受角色、请假或阻塞因素影响。
F	0–34	多维度显著低下，往往是值班、非编码工作或长假导致。

六大维度（描述性权重）

维度	权重	描述
📝 Commit Discipline	15%	提交频率、信息长度、规范遵守度
⏰ Cadence Consistency	15%	提交时间戳分布
🚀 Change Patterns	20%	churn、重工、变更量
🔍 Code Quality artefacts	25%	Bug‑fix、回滚、测试覆盖、复杂度
🎨 Code Style markers	10%	Conventional Commits、Issue 引用
💪 Cad度 Density	15%	稀疏度的逆向衡量

稀疏度指标（仅描述）

分段	指标范围	含义
Dense activity	0–20	在活动期间频繁提交。
Regular activity	21–40	典型提交节奏。
Mixed cadence	41–60	有安静时段的混合节奏。
Sparse cadence	61–80	大量安静时段，需上下文解释。
Very sparse cadence	81–100	提交集中在短时间内。

注意：高稀疏度值并不等同于“摸鱼”，仅说明提交集中在某段时间，很多合法角色和生活情况都会出现此模式。

备注

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