voidborne-d/sober-coding
GitHub: voidborne-d/sober-coding
一款专为 AI 生成代码设计的技术债务检测与修复工具，能精准识别氛围编程产生的代码异味并给出可操作的修复建议。
Stars: 2 | Forks: 0
# 🧳 Sober Coding
**氛围编程的宿醉解药。分析 AI 生成的代码质量，定位技术债务，并提供可操作的修复建议。**
[](https://github.com/voidborne-d/sober-coding)
[](LICENSE)
[](#supported-languages)
[](#claude-code)
**[中文文档](README_CN.md)**
## 理念
我们并不反对氛围编程。AI 生成的代码代表着未来。
但氛围编程有一个致命缺陷：**它产生技术债务的速度是人类的 10 倍。**
传统工具（如 ESLint、SonarQube）主要用于捕捉人类编码时的错误。而 AI 生成的代码有其特有的“异味”——重复模式、过度生成、缺失边缘情况以及结构冗余。
Sober Coding 专门针对这些 AI 原生模式，帮助你在技术债务失控之前将其清理干净。
## 问题所在
你用 Cursor、Claude Code 或 Copilot 通过氛围编程写了一个项目。它能运行。但在内心深处，你清楚以下问题：
- 🔴 **随处可见的死代码** — AI 生成了 5 个版本，你只保留了最后一个，其余 4 个仍然残留其中
- 🔴 **复制粘贴地狱** — 相同的逻辑出现了 3 次，因为 AI 每次都从头重写
- 🔴 **没有错误处理** — 正常路径堪称完美，但其他情况一触即溃
- 🔴 **上帝文件** — 2000 行的 `utils.py` 包揽了一切
- 🔴 **依赖混乱** — 安装了 47 个包，实际只用到了 12 个
- 🔴 **安全漏洞** — 硬编码的密钥、SQL 注入、路径遍历
- 🔴 **零测试** — “在我电脑上能跑”是唯一的测试
Sober Coding 能找出所有这些问题，告诉你首先该修复什么，以及如何修复。
## 真实项目演示
扫描一个真实的氛围编程全栈项目（Python + Vue.js，50 个文件，1.3 万行代码）：
```
sober scan ./RedInk
```
```
🧊 Sober Coding v0.1.0 — Let's see what we're working with.
Scanning ./RedInk (50 files, 13,579 lines)
╭────────────────────────────────────────╮
│ SOBRIETY SCORE: 0/100 🔴 BLACKOUT │
╰────────────────────────────────────────╯
🟠 High (fix this week)
ERR-001 Empty except block in backend/routes/config_routes.py:231
ERR-001 Empty except block in backend/services/content.py:111
ERR-001 Empty catch block in frontend/src/views/HistoryView.vue:189
... (7 total)
🟡 Medium (fix this sprint)
ARC-004 Deep nesting in backend/app.py:89
DED-004 Unreachable code in backend/generators/google_genai.py:372
DUP-001 Exact duplicate code block in backend/generators/image_api.py:68
ARC-001 God file: backend/generators/google_genai.py (500+ lines)
ERR-002 No error handling in backend/services/content.py:45
... (1,067 total)
⚪ Low (when you can)
DUP-003 Structural clone detected in backend/generators/image_api.py:51
DED-002 Unused import: Dict in backend/app.py:2
... (94 total)
💊 Run `sober fix ERR-001` to get fix instructions
```
**共发现 1,172 个问题。** 最严重的问题如下：
| 问题 | 数量 | 含义 |
|-------|-------|---------------|
| ARC-004 | 604 | 深层嵌套（>4 层）—— AI 喜欢嵌套的 if/for/try |
| DED-004 | 226 | return/break 后的不可达代码 |
| DUP-001 | 180 | 跨文件的完全重复代码块 |
| DUP-003 | 81 | 相同的控制流结构，仅变量名不同 |
| ERR-002 | 30 | 无错误处理的异步调用 |
这就是氛围编程在表面之下的真实面貌。
## 修复模式
它不仅指出问题，还会告诉你如何修复它们：
```
sober fix DUP-012
```
```
🔧 DUP-012: Near-duplicate code detected (89% similarity)
File A: utils/parse.py:45-92
File B: helpers/format.py:12-58
WHY IT MATTERS:
Fix a bug in one, the other still has it. AI didn't know it already wrote this.
HOW TO FIX:
1. Extract shared logic into a single function
2. Both files import from the shared module
3. Delete the duplicate
SUGGESTED REFACTOR:
┌─ shared/text_utils.py (new) ─────────────────┐
│ def normalize_text(raw: str) -> str: │
│ """Merge of parse.py:45-92 & format.py""" │
│ ... │
└────────────────────────────────────────────────┘
AUTO-FIX AVAILABLE: sober fix DUP-012 --apply
```
## 安装
```
# npm (推荐)
npm install -g sober-coding
# pip
pip install sober-coding
# 从源码构建
git clone https://github.com/voidborne-d/sober-coding.git
cd sober-coding && npm link
# Claude Code Skill
npx skills add https://github.com/voidborne-d/sober-coding.git
# ClawHub
clawhub install sober-coding
```
零配置。无需 API 密钥。100% 本地运行。
## Claude Code
将斜杠命令复制到你的项目中：
```
cp sober-coding/claude-code/*.md YOUR_PROJECT/.claude/commands/
```
然后直接使用：
```
/sober-scan # Full project scan
/sober-fix DUP-012 # Get fix instructions
/sober-report # Generate HTML report
/sober-watch # Watch mode — scan on every save
```
## 检查内容
### 🔒 安全性
| ID | 检查项 | 描述 |
|---|---|---|
| SEC-001 | 硬编码密钥 | 源代码中包含 API 密钥、密码、token |
| SEC-002 | SQL 注入 | SQL 查询中的字符串拼接 |
| SEC-003 | 路径遍历 | 文件路径中直接使用用户输入 |
| SEC-004 | 不安全的依赖项 | 已知存在漏洞的依赖版本 |
| SEC-005 | CORS 配置错误 | `Access-Control-Allow-Origin: *` |
### 🏗️ 架构
| ID | 检查项 | 描述 |
|---|---|---|
| ARC-001 | 上帝文件 | 单个文件超过 500 行 |
| ARC-002 | 循环依赖 | 模块间存在循环导入 |
| ARC-003 | 混合关注点 | 单个文件中混杂了 API + 数据库 + 业务逻辑 |
| ARC-004 | 深层嵌套 | 缩进超过 4 层 |
| ARC-005 | 意大利面条式导入 | 导入图熵值过高 |
### 🔄 重复代码
| ID | 检查项 | 描述 |
|---|---|---|
| DUP-001 | 完全克隆 | 完全相同的代码块 |
| DUP-002 | 近似克隆 | 高相似度（>70%），典型的 AI 行为 |
| DUP-003 | 结构克隆 | 结构相同，仅变量名不同 |
### ⚠️ 错误处理
| ID | 检查项 | 描述 |
|---|---|---|
| ERR-001 | 空 catch 块 | `catch (e) {}` 吞掉了所有错误 |
| ERR-002 | 无错误处理 | 异步调用未使用 try-catch |
| ERR-003 | 笼统的 catch | 使用单一顶层 catch 处理所有异常 |
| ERR-004 | 缺少输入验证 | 用户输入未经任何验证 |
### 📦 依赖
| ID | 检查项 | 描述 |
|---|---|---|
| DEP-001 | 未使用的依赖 | 在配置清单中声明但从未被导入 |
| DEP-002 | 重复功能 | 同时安装了 lodash 和 underscore |
| DEP-003 | 过时的版本 | 核心依赖落后 2 个或更多主版本 |
### 🧪 测试
| ID | 检查项 | 描述 |
|---|---|---|
| TST-001 | 无测试 | 未找到任何测试文件 |
| TST-002 | 低覆盖率 | 测试覆盖率低于阈值 |
| TST-003 | 无边缘情况 | 仅测试了正常路径 |
### 💀 死代码
| ID | 检查项 | 描述 |
|---|---|---|
| DED-001 | 未使用的函数 | 已定义但从未调用 |
| DED-002 | 未使用的导入 | 已导入但从未使用 |
| DED-003 | 被注释掉的代码 | 大段被注释掉的代码块 |
| DED-004 | 不可达代码 | return/break 之后的代码 |
## 评分
| 分数 | 等级 | 含义 |
|---|---|---|
| 80-100 | 🟢 **SOBER** | 整洁、可维护的代码。可以直接发布。 |
| 60-79 | 🟡 **TIPSY** | 存在一些问题。在恶化前尽快修复。 |
| 40-59 | 🟠 **HUNGOVER** | 技术债务严重。需要进行一次清理冲刺。 |
| 0-39 | 🔴 **BLACKOUT** | 存在严重问题。停止构建新功能，立即开始修复。 |
每个维度的评分为 0-10 分，加权计算得出总分。权重支持自定义配置。
## 支持的语言
| 语言 | 扫描 | 修复 | 自动修复 |
|---|---|---|---|
| JavaScript / TypeScript | ✅ | ✅ | ✅ |
| Python | ✅ | ✅ | ✅ |
| Go | ✅ | ✅ | 🔜 |
| Rust | ✅ | ✅ | 🔜 |
| Java | ✅ | ✅ | 🔜 |
| Ruby | ✅ | 🔜 | 🔜 |
| PHP | ✅ | 🔜 | 🔜 |
| C/C++ | ✅ | 🔜 | 🔜 |
与语言无关的检查（重复代码、死代码、依赖、安全性）适用于所有语言。
## 配置
开箱即用零配置。可通过项目根目录下的 `.soberrc.json` 进行自定义：
```
{
"thresholds": {
"god_file_lines": 500,
"max_nesting": 4,
"min_test_coverage": 60,
"duplication_similarity": 70
},
"ignore": [
"node_modules",
"dist",
"*.generated.*"
],
"weights": {
"security": 2.0,
"architecture": 1.5,
"duplication": 1.0,
"error_handling": 1.5,
"dependencies": 0.8,
"testing": 1.2,
"dead_code": 0.8
},
"severity": "medium"
}
```
## CI/CD 集成
```
# GitHub Actions
- name: Sober Check
run: npx sober-coding scan . --ci --fail-on=critical
```
```
# GitLab CI
sober-check:
script:
- npx sober-coding scan . --ci --fail-on=high
allow_failure: false
```
CI 模式输出兼容 GitHub Code Scanning 的 SARIF 格式。
## 对比其他工具
| | Sober Coding | pyscn | ESLint/Ruff | SonarQube |
|---|---|---|---|---|
| 专为氛围编程打造 | ✅ | ✅ | ❌ | ❌ |
| 语言无关性 | ✅ | ❌ 仅限 Python | ❌ 按语言区分 | ✅ |
| 技术债务评分 | ✅ 0-100 | ✅ | ❌ | ✅ |
| AI 模式检测 | ✅ | ✅ | ❌ | ❌ |
| 修复建议 | ✅ 附带代码 | ❌ | ❌ | 部分 |
| 自动修复 | ✅ `--apply` | ❌ | 部分 | ❌ |
| 零配置 | ✅ | ✅ | ❌ | ❌ |
| 本地运行 | ✅ | ✅ | ✅ | ❌ 需服务器 |
| Claude Code 集成 | ✅ | ❌ | ❌ | ❌ |
| 免费 | ✅ | ✅ | ✅ | ⚠️ 免费增值模式 |
## 路线图
- [x] 核心扫描引擎
- [x] 安全性检查 (SEC-001~005)
- [x] 架构检查 (ARC-001~005)
- [x] 重复代码检测 (DUP-001~003)
- [x] 错误处理检查 (ERR-001~004)
- [x] 依赖检查 (DEP-001~003)
- [x] 测试检查 (TST-001~003)
- [x] 死代码检测 (DED-001~004)
- [x] 带评分的 CLI
- [x] 修复建议 (`sober fix `)
- [x] `.soberrc.json` 配置支持
- [x] CI 模式 (`--ci`, `--fail-on`)
- [ ] 自动修复引擎 (`--apply`)
- [ ] HTML/PDF 报告生成
- [ ] VS Code 扩展
- [ ] GitHub Action (市场)
- [ ] 监视模式 (保存时扫描)
- [ ] AI 模式指纹识别 (检测代码由哪种 AI 生成)
- [ ] 团队仪表板
## 出自同一 workshop
属于 [voidborne-d](https://github.com/voidborne-d) 处理 AI 生成输出的工具集。这三款工具的核心理念相同：**AI 会留下指纹——而这些工具正是为了检测、清理或重新利用它们而生的。**
- **[humanize-chinese](https://github.com/voidborne-d/humanize-chinese)** — 自然语言层面的同类工具。通过 n-gram 困惑度 + 20 多种模式检测器 + 学术 AIGC 降重（知网/维普/万方），检测并重写 AI 生成的中文文本。纯 Python 编写，零依赖。
- **[lambda-lang](https://github.com/voidborne-d/lambda-lang)** — 压缩的 agent 间通信语言。包含 139 个原子词，具备 5–8 倍的压缩率，由 Go 实现。当你的氛围编程 agent 们需要互相交流，又不想在冗长的自然语言上浪费 token 时，这个工具将大显身手。
## 贡献
欢迎提交 PR。详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT — 随意使用、fork、发布。永久免费。
标签：AI, AI代码检测, AI辅助开发, CISA项目, Claude Code, Language-Agnostic, MITM代理, Vibe Coding, 二进制发布, 代码优化, 代码冗余检测, 代码坏味道, 代码质量分析, 依赖管理, 多语言支持, 威胁情报, 安全测试框架, 安全漏洞扫描, 开发者工具, 开源工具, 技术债务, 数据管道, 文档结构分析, 无配置(Zero Config), 暗色界面, 死代码清理, 自动化代码审查, 自动化攻击, 软件工程, 逆向工具, 错误基检测, 静态代码分析