开发code-quality
This commit is contained in:
@@ -0,0 +1,321 @@
|
||||
# 代码质量保障系统
|
||||
|
||||
一套完整的 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 写出更完善的代码！** 🚀
|
||||
Reference in New Issue
Block a user