文件内容
README.md
# 我写了一个团队体检报告生成器，把摸鱼的同事扒出来了😅
> 你有没有好奇过，你的队友到底是几点写的代码？是凌晨三点灵感爆发的夜猫子，还是朝九晚五准时下班的养生达人？
## 用法很简单
作为 Skill 插件，你可以直接在对话中触发：
```
"分析一下这个仓库 Alice 的研发效率"
"帮我看看团队成员的工作习惯"
"对比一下 Alice 和 Bob 的代码质量"
```
## 一切的起源：一个深夜的疑问
故事要从一个加班到凌晨两点的夜晚说起。
那天我照例在提交代码，突然发现 Git log 里有一条提交时间是 03:47，来自我们组的后端同学。我震惊之余又有点心疼，然后下意识地翻了翻其他人的记录，发现了更多有趣的事：有人专挑周末提交，有人的 commit message 永远只有一个字 "fix"，还有人一个提交能改 500 个文件……
我心想，如果把这些数据系统地分析一下，会不会看到一幅很有意思的开发者画像？
这就是 [code-analysis-skills](https://clawhub.ai/Wscats/code-analysis-skills) 诞生的初心。
## 它是什么？
简单来说，这是一个 Git 仓库分析工具的 Skill 插件。它做的事情很纯粹：扫描你指定的 Git 仓库，或者一整个目录下的所有仓库，然后像一个沉默的观察者，把每个开发者的行为数据抽丝剥茧，最终生成一份五维度的体检报告。
五个维度分别是：
* **提交习惯** -- 你一天提交几次？每次改多少行？commit message 写了几个字？
* **工作习惯** -- 你是早起鸟还是夜猫子？周末有没有在偷偷加班？最长连续写了几天代码？
* **研发效率** -- 你写的代码有多少后来又被删了？是不是经常在同一个文件上反复改？
* **代码风格** -- 你主要写什么语言？commit message 有没有遵循规范？
* **代码质量** -- 修 bug 的提交占了多大比例？有没有动不动就一个大提交甩上来？
## 扒出来的「真实画像」
我用它分析了团队仓库后，看到的一些真实画面：
### 深夜战士 -- "A 同学"
```
Peak Hour: 22:00
Weekend Ratio: 100.0%
Late Night Ratio: 100.0%
```
这位老兄的提交时间几乎全部集中在深夜，而且清一色在周末。如果你半夜两点 @ 他，大概率能秒回。他不是不睡觉，他只是把白天的时间让给了生活，然后在万籁俱寂的时候打开编辑器，一个人安静地写代码。
不过看数据也会发现一些值得关注的信号：他的代码流失率高达 66%，意味着写下的代码有三分之二后来又被删除了。这可能是探索性编码的正常现象 -- 毕竟深夜写代码，有时候是先写再想，写完再推倒重来。他的返工率也有 46.2%，7 天内重复修改同一个文件的频率不低。
但换个角度想，这也许恰恰说明他是一个追求完美的人，代码写完不满意，再改，改完还是不满意，接着改。
### 批量输出者 -- "B 同学"
```
Total Lines Added: 84,224
Avg Lines per Commit: 21,056
Large Commit Ratio: 50.0%
Ownership Ratio: 100.0%
```
看到这个数据的时候我差点以为分析工具出了 bug，单次提交平均两万行？再仔细一看，原来是做项目初始化和大规模迁移的。他拥有仓库中 100% 的文件所有权，是当之无愧的项目奠基人。
有趣的是，他的代码流失率为 0%，写下的每一行代码都还活着。搞基建的人就是这样，一砖一瓦都是实打实的。不过他的 commit message 也就 30 来个字符，简洁高效，有那味了。
### 周末勇士 -- "C 同学"
```
Weekend Ratio: 66.7%
Late Night Ratio: 33.3%
Churn Rate: 3.8%
```
三分之二的提交都在周末，还有三分之一在深夜。但看另一组数据就知道，这是一个效率极高的人：代码流失率只有 3.8%，几乎不做无用功。每一次提交都目标明确，落笔精准。如果说深夜战士是先写再想，那这位就是想清楚再写。
### 偶尔现身的贡献者 -- "D 同学"
```
Total Commits: 1
Active Span: 1 day
```
有些人在项目中只留下了一个提交，但那一个提交可能就是修了一个关键 bug，或者补上了一段缺失的文档。开源世界里不存在贡献太少这一说，每一个 commit 背后，都是一个真实的人在某个时刻打开了编辑器，读懂了代码，然后伸出了手。
## 技术解剖：它是怎么做到的？
### 架构一览
整个项目的架构非常清晰，像一条流水线：
```
路径输入 → Scanner 发现仓库 → 5 个 Analyzer 遍历 Git 历史 → Reporter 生成报告
```
* **Scanner** 负责扫描，找到指定路径下的所有 Git 仓库（最深 5 层），用 GitPython 验证合法性，跳过裸仓库和符号链接循环
* **5 个 Analyzer** 各司其职，用 [PyDriller](https://github.com/ishepard/pydriller) 遍历提交历史，按作者分组聚合数据
* **3 个 Reporter** 提供 Markdown、JSON、HTML 三种输出格式
### 核心算法亮点
几个我觉得设计得比较巧妙的地方：
**1. 返工率 Rework Ratio 的计算**
如果你在 7 天内对同一个文件改了两次以上，就算一次返工。这个定义很现实 -- 真正的返工通常发生在短时间内反复修改同一个地方，可能是需求变了，可能是 code review 的反馈，也可能是自己发现了之前的问题。
**2. 文件所有权 Ownership 的判定**
如果你对某个文件的修改次数超过了所有人修改该文件总次数的 50%，你就拥有这个文件。这个概念借鉴了 Google 的 Code Ownership 实践 -- 每个文件都应该有一个主人，出了问题知道找谁。
**3. Bus Factor 的衡量**
如果某个人被公交车撞了，不是真的，项目还能继续吗？工具统计每个文件有多少独立贡献者，取平均值。如果这个数字低于 2，说明知识过于集中，团队需要注意知识共享。
**4. 深夜编码的精确定义**
22:00 到次日 04:59 都算深夜编码。这不是为了抓考勤，而是为了发现团队健康问题。如果一个人的深夜编码比例长期超过 15%，也许不是他效率高，而是白天的会议太多了。
### 代码风格检测
工具还会检测 commit message 是否遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范，以及是否关联了 Issue 编号。这两个数据看似简单，其实反映了一个团队的工程化成熟度。
如果你的团队 Conventional Commit 遵循率低于 50%，可能需要考虑引入 commitlint 之类的工具了。
## 也可以直接用命令行使用：
```bash
# 分析单个仓库
python -m src.main -r /path/to/repo
# 扫描整个目录
python -m src.main -r /path/to/projects --scan-all
# 指定时间范围，生成 HTML 报告
python -m src.main -r /path/to/repo -s 2025-01-01 -u 2025-12-31 -f html -o report.html
# 同时生成 Markdown + HTML + PDF
python -m src.main -r /path/to/repo -f "markdown,html,pdf" -o report
```
生成的报告长这样：
| Author | Commits | Lines Changed | Commits/Day | Weekend % | Late Night % | Bug Fix % | Churn Rate |
|--------|---------|---------------|-------------|-----------|-------------|-----------|------------|
| wscats | 7 | 102 | 3.5 | 100.0% | 42.9% | 0.0% | 43.7% |
| enoyao | 4 | 84, 226 | 1.33 | 25.0% | 0.0% | 0.0% | 0.0% |
| reky | 3 | 27 | 1.0 | 66.7% | 33.3% | 0.0% | 3.8% |
每个人的数据都是一面镜子。
## 写在最后：数据不是枷锁
我必须坦诚地说：**这个工具不是用来搞绩效考核的。**
数据可以帮我们发现问题，但不能定义一个人的价值。那个凌晨三点提交代码的同事，也许比任何人都更热爱这个项目；那个 commit message 只写 "fix" 的人，也许正在争分夺秒地修复一个线上事故；那个只贡献了一个提交的人，也许是花了整整一周才理解了代码才敢动手。
写这个工具的初心，是想透过冰冷的 Git 记录，看到背后一个个**真实的、有温度的人**。看到他们的工作节奏，理解他们的习惯，在必要时帮助他们 -- 比如发现某人连续深夜加班，也许该找他聊聊是不是遇到了什么困难。
代码会说话，但只有用心听，才能听到正确的答案。
## ⚠️ 隐私与数据安全声明
> **重要提示**：本工具会从 Git 提交历史中提取开发者个人活动数据（提交时间、频率、行为模式等）。
**使用前请务必注意：**
- ✅ 本工具**完全本地运行**，不会向任何外部服务器传输数据
- ⚠️ 分析他人仓库前，请**获得相关开发者的知情同意**
- 🚫 分析结果**不应直接用于**绩效考核、薪酬决策或惩罚性管理
- 🔒 生成的报告包含个人信息，请**妥善保管**，不应公开分享
- 📋 使用前请确认符合组织的 HR 政策和当地数据保护法规（如 GDPR）
## 🆕 v1.1.0 新增功能
- 🐟 **摸鱼指数** — 综合 7 大信号（稀疏度、琐碎提交、消失模式、低产出等）评估开发者投入度
- 🏆 **开发者评估** — 六维度加权评分（S/A/B/C/D/E/F 等级），严肃直接的优缺点点评和建议
- 📊 **排行榜** — 开发者评分排行 + 摸鱼指数排行
- 📄 **PDF 输出** — 支持生成带样式的 PDF 报告（基于 reportlab）
- 🔀 **多格式同时输出** — 一条命令同时生成 Markdown + HTML + PDF
---
*项目地址：[https://clawhub.ai/Wscats/code-analysis-skills](https://clawhub.ai/Wscats/code-analysis-skills)*
*技术栈：Python + GitPython + PyDriller + Radon + Jinja2 + Click + ReportLab*
*开源协议：MIT -- 拿去用，拿去改，拿去看看你的团队。*