322 lines
8.5 KiB
Markdown
322 lines
8.5 KiB
Markdown
# 代码质量保障系统
|
||
|
||
一套完整的 Agent + Hook + Skill 组合，让 AI 能够写出更完善的代码。
|
||
|
||
## 🎯 核心功能
|
||
|
||
### 1. 自动完成检查 (Auto-Complete Hook)
|
||
- 拦截 Agent 任务结束，自动检查代码质量
|
||
- 检测未完成的功能、TODO、空函数、占位符
|
||
- 最多允许 3 次迭代修复
|
||
- 未通过时阻止任务完成，生成修复要求
|
||
|
||
### 2. 深度质量检查 (Code-Quality Skill)
|
||
- 手动触发命令：`/code-quality`
|
||
- 全面检查：功能、代码、测试、文档、规范、安全
|
||
- 生成详细的质量报告
|
||
- 提供修复建议和自动修复选项
|
||
|
||
### 3. 智能通知系统
|
||
- Windows 桌面通知
|
||
- 声音提醒（成功/警告/注意）
|
||
- 异步发送，不阻塞工作流程
|
||
|
||
## 📁 文件结构
|
||
|
||
```
|
||
code-quality-system/
|
||
├── hooks/ # Hook 脚本
|
||
│ ├── auto-complete-check.py # 主检查逻辑
|
||
│ ├── requirements-tracker.py # 需求追踪器
|
||
│ ├── code-analyzer.py # 代码分析器
|
||
│ ├── notification-sender.py # 通知发送器
|
||
│ └── requirements.txt # Python 依赖
|
||
├── custom-skills/ # 自定义技能
|
||
│ └── code-quality/
|
||
│ ├── skill.json # 技能定义
|
||
│ └── instructions.md # 技能指令
|
||
├── config/ # 配置文件
|
||
│ └── code-quality-config.json # 系统配置
|
||
├── sounds/ # 声音资源
|
||
│ ├── README.md # 声音文件说明
|
||
│ ├── success.wav # 成功提示音
|
||
│ ├── warning.wav # 警告提示音
|
||
│ └── attention.wav # 注意提示音
|
||
├── deploy.bat # 一键部署脚本
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方法 1: 使用一键部署脚本（推荐）
|
||
|
||
1. 双击运行 `deploy.bat`
|
||
2. 选择部署模式：
|
||
- **全局部署**：所有项目自动启用
|
||
- **项目部署**：仅当前项目启用
|
||
3. 重启 Claude Code
|
||
4. 完成！
|
||
|
||
### 方法 2: 手动部署
|
||
|
||
#### 全局部署
|
||
|
||
```bash
|
||
# 1. 复制文件到 Claude Code 配置目录
|
||
cp -r hooks/* ~/.claude/hooks/
|
||
cp -r custom-skills/* ~/.claude/custom-skills/
|
||
cp config/code-quality-config.json ~/.claude/
|
||
|
||
# 2. 安装 Python 依赖
|
||
pip install plyer pygame
|
||
|
||
# 3. 配置 settings.json
|
||
# 添加以下内容到 ~/.claude/settings.json:
|
||
{
|
||
"hooks": {
|
||
"TaskEnd": [
|
||
{
|
||
"type": "command",
|
||
"command": "python ~/.claude/hooks/auto-complete-check.py"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 项目部署
|
||
|
||
```bash
|
||
# 1. 复制文件到项目目录
|
||
cp -r hooks/* .claude/hooks/
|
||
cp -r custom-skills/* .claude/custom-skills/
|
||
cp config/code-quality-config.json .claude/
|
||
|
||
# 2. 安装 Python 依赖
|
||
pip install plyer pygame
|
||
```
|
||
|
||
## 🔧 配置说明
|
||
|
||
编辑 `code-quality-config.json` 自定义系统行为：
|
||
|
||
```json
|
||
{
|
||
"enabled": true, // 是否启用
|
||
"checkLevel": "standard", // 检查级别: standard/deep
|
||
"maxIterations": 3, // 最大迭代次数
|
||
"notification": {
|
||
"enabled": true, // 启用通知
|
||
"sound": true, // 启用声音
|
||
"desktop": true, // 启用桌面通知
|
||
"soundVolume": 0.7 // 音量 (0.0-1.0)
|
||
},
|
||
"thresholds": {
|
||
"passingScore": 80, // 通过分数
|
||
"warningScore": 60, // 警告分数
|
||
"maxTodos": 5, // 最大 TODO 数量
|
||
"maxEmptyFunctions": 0, // 最大空函数数量
|
||
"maxPlaceholders": 0 // 最大占位符数量
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📖 使用方法
|
||
|
||
### 自动检查（默认启用）
|
||
|
||
系统会在以下情况自动触发检查：
|
||
- 主 Agent 完成任务时
|
||
- 任何子 Agent 完成任务时
|
||
- 不需要手动干预
|
||
|
||
### 手动检查
|
||
|
||
使用 `/code-quality` 命令：
|
||
|
||
```
|
||
# 标准检查
|
||
/code-quality
|
||
|
||
# 深度检查
|
||
/code-quality --deep
|
||
|
||
# 聚焦特定方面
|
||
/code-quality --focus security
|
||
/code-quality --focus documentation
|
||
/code-quality --focus code-style
|
||
```
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
┌─────────────────┐
|
||
│ AI 开始编码 │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ AI 声明完成 │
|
||
└────────┬────────┘
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Hook 拦截 │◄───────────────┐
|
||
└────────┬────────┘ │
|
||
│ │
|
||
▼ │
|
||
┌─────────────────┐ │
|
||
│ 执行快速检查 │ │
|
||
└────────┬────────┘ │
|
||
│ │
|
||
┌────┴────┐ │
|
||
│ │ │
|
||
通过❌ 通过✅ │
|
||
│ │ │
|
||
▼ ▼ │
|
||
┌─────────┐ ┌──────────┐ │
|
||
│迭代+1 │ │允许结束 │ │
|
||
└────┬────┘ └──────────┘ │
|
||
│ │
|
||
▼ │
|
||
┌─────────┐ │
|
||
│生成修复 │ │
|
||
│要求 │ │
|
||
└────┬────┘ │
|
||
│ │
|
||
▼ │
|
||
┌─────────────────┐ │
|
||
│ AI 继续修复 │────────────────┘
|
||
└─────────────────┘
|
||
```
|
||
|
||
## 🔍 检查维度
|
||
|
||
### 1. 功能完整性
|
||
- 对比需求清单
|
||
- 验证所有功能已实现
|
||
- 检查缺失的功能
|
||
|
||
### 2. 代码完整性
|
||
- 检测 TODO、FIXME
|
||
- 检测空函数、占位符
|
||
- 检测被注释的代码
|
||
- 检测调试语句
|
||
|
||
### 3. 代码规范
|
||
- 命名规范
|
||
- 格式一致性
|
||
- 语言特定规范（ESLint、PEP 8、Clippy）
|
||
- 项目特定规范
|
||
|
||
### 4. 测试覆盖
|
||
- 测试文件存在性
|
||
- 测试用例数量
|
||
- 关键功能测试
|
||
|
||
### 5. 文档完整性
|
||
- 函数/类注释
|
||
- README 文档
|
||
- API 文档
|
||
|
||
### 6. 安全检查
|
||
- SQL 注入风险
|
||
- XSS 漏洞
|
||
- 硬编码密钥
|
||
- 不安全的函数调用
|
||
|
||
## 📊 检查报告示例
|
||
|
||
```
|
||
## 代码质量检查报告
|
||
|
||
### 总体评分：85/100
|
||
|
||
### 完成度分析
|
||
✅ 用户登录功能 (100%)
|
||
✅ 数据库连接 (100%)
|
||
⚠️ API 错误处理 (60%) - 缺少部分错误码
|
||
❌ 日志记录 (0%) - 未实现
|
||
|
||
### 代码质量
|
||
- TODO: 3 个
|
||
- 空函数: 0 个
|
||
- 被注释代码: 2 处
|
||
- 占位符: 1 个
|
||
|
||
### 修复建议（按优先级）
|
||
1. [高] 实现日志记录模块
|
||
2. [高] 补充 API 错误码
|
||
3. [中] 清理被注释的代码
|
||
4. [低] 处理 TODO 项
|
||
```
|
||
|
||
## 🛠️ 故障排除
|
||
|
||
### 通知不工作
|
||
|
||
1. 检查依赖是否安装：
|
||
```bash
|
||
pip install plyer pygame
|
||
```
|
||
|
||
2. 测试通知：
|
||
```bash
|
||
python ~/.claude/hooks/notification-sender.py test
|
||
```
|
||
|
||
3. 检查配置文件中的 `notification.enabled` 是否为 `true`
|
||
|
||
### Hook 不触发
|
||
|
||
1. 检查 `settings.json` 配置是否正确
|
||
2. 检查 Python 脚本是否有执行权限
|
||
3. 查看 Claude Code 日志：`~/.claude/logs/`
|
||
|
||
### 声音文件缺失
|
||
|
||
系统会自动使用 Windows 系统 Beep 音效作为回退，不影响功能。
|
||
|
||
如需自定义声音，参考 `sounds/README.md`。
|
||
|
||
## 📝 卸载
|
||
|
||
### 使用部署脚本
|
||
|
||
1. 运行 `deploy.bat`
|
||
2. 选择"卸载"
|
||
3. 选择要卸载的组件（全局/项目）
|
||
|
||
### 手动卸载
|
||
|
||
```bash
|
||
# 全局部署
|
||
rm ~/.claude/hooks/auto-complete-check.py
|
||
rm ~/.claude/hooks/requirements-tracker.py
|
||
rm ~/.claude/hooks/code-analyzer.py
|
||
rm ~/.claude/hooks/notification-sender.py
|
||
rm -rf ~/.claude/custom-skills/code-quality
|
||
rm ~/.claude/code-quality-config.json
|
||
|
||
# 项目部署
|
||
rm -rf .claude
|
||
```
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交问题和改进建议！
|
||
|
||
## 📄 许可
|
||
|
||
MIT License
|
||
|
||
## 🔗 相关资源
|
||
|
||
- [Claude Code 官方文档](https://github.com/anthropics/claude-code)
|
||
- [Hook 开发指南](./README.md) - 项目根目录的 Hook 使用指南
|
||
- [Superpowers 技能集](https://github.com/obra/superpowers-marketplace)
|
||
|
||
---
|
||
|
||
**让 AI 写出更完善的代码！** 🚀
|