# 代码质量保障系统

一套完整的 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 写出更完善的代码！** 🚀