YounesBensafia/DevLens
GitHub: YounesBensafia/DevLens
DevLens是一款基于Python代码复杂度评估的工具，帮助团队识别和理解难度高的代码文件。
Stars: 26 | Forks: 0
# DevLens
**代码库理解扫描器 + AI 垃圾检测器**
[](https://pypi.org/project/devlens-tool/)
[](https://pypi.org/project/devlens-tool/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/YounesBensafia/DevLens)
[安装](#installation) . [使用说明](#usage) . [配置](#configuration) . [贡献](#contributing) . [许可证](#license)
## 功能介绍
对新的代码库感到迷茫？DevLens 会扫描你的 Python 项目，并根据理解难度对每个文件进行 0 到 100 的评分。它结合使用代码复杂度指标、git 历史记录信号以及可选的 AI 判断，精准定位你的团队难以理解的文件。它还能显示项目统计数据（语言、代码行数、目录），并可以用 AI 总结每个文件。
DevLens 还能使用纯启发式信号检测 AI 生成的或低质量的 pull request：无需调用 LLM，无 API 成本，完全确定性。将其放入 CI 中，在垃圾代码合并前将其拦截。
## 为什么它很有用
- 新开发者入职？他们知道该先询问哪些文件。
- 规划 sprint？你可以看到自上次扫描以来哪些文件变得更糟了。
- 向经理汇报？你可以展示一条趋势线：“我们的代码库得分本季度从 45 提升到了 62。”
## 快速开始
```
pip install devlens-tool
```
设置你的 API key（用于 AI 功能）：
```
export LLM_API_KEY=your_key_here
```
运行扫描：
```
cd my-project
devlens -scan .
```
## 命令
| 命令 | 功能 |
|---|---|
| `devlens -scan
` | 包含所有三层的全面扫描（需要 API key） |
| `devlens -scan --no-llm` | 不使用 AI 进行扫描（确定性，适用于 CI） |
| `devlens -scan --trend` | 显示项目得分随时间的变化 |
| `devlens -scan --regression` | 列出自上次扫描以来变得更糟的文件 |
| `devlens -scan --since 14` | 与 14 天前的扫描结果进行比较 |
| `devlens -st ` | 项目统计：文件、行数、语言、目录 |
| `devlens -an ` | AI 生成的每个文件的单段落摘要 |
| `devlens check-pr` | 检测 AI 生成或低质量的 PR（无需 LLM） |
## 扫描输出示例
```
Project Score: 62
Files Analyzed: 47
High Risk Files: 3
Bus Factor Risks: 2
File Comprehension Scores:
Risk File Score CC MI Docs Git
high src/parser/lexer.py 34 +- 8 18 28 0% 340d solo
med src/api/handler.py 52 +- 5 12 45 10% 120d ago
low src/models/user.py 72 +- 2 3 82 90% 5d ago
good tests/test_utils.py 88 +- 2 1 95 100% 1d ago
```
每个得分都有一个置信区间（+-2、+-5 或 +-8），用于告诉你这三个层次的判断一致程度。较大的偏差意味着你需要对这个数字保持怀疑。
## 垃圾检测
DevLens 使用 **6 种启发式信号** 检测可能由 AI 生成或低质量的 pull request：无需调用 LLM，无 API 成本，完全确定性。
### 信号
| 信号 | 权重 | 检测内容 |
|---|---|---|
| `docstring_uniformity` | 20% | AI 模板化的 docstring（TF-IDF 余弦相似度） |
| `identifier_entropy` | 15% | 可疑的命名模式（过于随机或过于重复） |
| `comment_to_code_ratio` | 15% | 过度注释的 AI 代码（注释行大于 35%） |
| `diff_size_vs_description_ratio` | 20% | 庞大的 diff 搭配极简的描述 + AI 凑字数的短语 |
| `churn_pattern` | 15% | 高重写率（增加的行数等于删除的行数） |
| `new_author_large_diff` | 15% | 新贡献者一次性倾倒 100 多行代码 |
### 用法
```
# 针对 main 检查 PR branch
devlens check-pr --repo . --base main --head my-feature
# 包含 PR 描述（用于 diff/description 比例）
devlens check-pr --repo . --base main --head feature --pr-body "Adds user login"
# 用于 CI 解析的 JSON 输出
devlens check-pr --repo . --base main --head feature --output json
# 如果 slop score >= threshold 则使 CI 失败
devlens check-pr --repo . --base main --head feature --fail-on-slop --threshold 65
```
### 垃圾检测输出示例
```
╔══════════════════════════════════════════════════════════════════════╗
║ DEVENS SLOP REPORT: POSSIBLE AI SLOP ║
╚══════════════════════════════════════════════════════════════════════╝
Slop Score: 73/100 (threshold: 65)
╭─────────────────────────────┬─────────┬──────────┬─────────────╮
│ Signal │ Raw Val │ Weighted │ Verdict │
├─────────────────────────────┼─────────┼──────────┼─────────────┤
│ docstring uniformity │ 87.0 │ 17.4 │ FAIL │
│ identifier entropy │ 12.3 │ 1.8 │ PASS │
│ comment to code ratio │ 55.0 │ 8.3 │ WARN │
│ diff size vs description │ 90.0 │ 18.0 │ FAIL │
│ churn pattern │ 45.0 │ 6.8 │ WARN │
│ new author large diff │ 80.0 │ 12.0 │ FAIL │
├─────────────────────────────┼─────────┼──────────┼─────────────┤
│ Total │ │ 73.0 │ POSSIBLE AI │
╰─────────────────────────────┴─────────┴──────────┴─────────────╯
```
### CI 集成
将以下内容添加到 `.github/workflows/devlens-slop-check.yml`：
```
name: DevLens Slop Check
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
slop-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install DevLens
run: pip install devlens-tool
- name: Save PR body
run: echo "${{ github.event.pull_request.body }}" > .pr_body.txt
- name: Run slop check
run: |
devlens check-pr \
--repo . \
--base ${{ github.event.pull_request.base.ref }} \
--head ${{ github.event.pull_request.head.ref }} \
--output json --fail-on-slop --threshold 65
```
## 配置
你可以通过在 `pyproject.toml` 中添加以下内容来更改分数的计算方式：
```
[tool.devlens]
weights = { metrics = 0.70, git = 0.10, llm = 0.20 }
```
默认值为 50/30/20。这三个权重相加必须等于 1.0。
## 使用其他 AI 提供商
DevLens 兼容任何 OpenAI 兼容的 API。设置这些环境变量：
```
# 对于 OpenAI
LLM_API_URL=https://api.openai.com/v1/chat/completions
LLM_API_KEY=sk-your-key
LLM_MODEL=gpt-4o-mini
# 对于本地模型（Ollama）
LLM_API_URL=http://localhost:11434/v1/chat/completions
LLM_API_KEY=ollama
LLM_MODEL=llama3.2
# 对于 Groq（默认）
LLM_API_URL=https://api.groq.com/openai/v1/chat/completions
LLM_API_KEY=your_groq_key
```
## CI 集成
将以下内容添加到你的 CI pipeline 中：
```
- name: Check code comprehension
run: devlens -scan . --no-llm
```
`--no-llm` 标志使其快速且确定——无 API 调用，无网络请求，无随机性。
## 路线图
- [x] 项目统计和语言细分
- [x] AI 驱动的文件分析
- [x] 理解债务扫描（0-100 评分）
- [x] 得分趋势随时间追踪
- [x] 可配置的评分权重
- [x] 得分置信区间
- [x] 多提供商 LLM 支持
- [x] AI 垃圾检测（启发式，零 LLM 成本）
- [ ] 依赖图可视化
## 许可证
MIT。详见 [LICENSE](LICENSE)。
**由 [Younes Bensafia](https://github.com/YounesBensafia) 构建**
如果 DevLens 对你有帮助，请考虑点个 star。
标签：Python, SOC Prime, 云安全监控, 人工智能辅助, 代码复杂度, 代码统计, 代码质量分析, 开发工具, 无后门, 静态分析