Archived

This repository has been archived on 2026-03-09. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

T

starmen1265 3367268ace 开发code-quality

2026-01-30 00:42:33 +08:00

8.5 KiB

Raw Permalink Blame History

代码质量保障系统

一套完整的 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: 使用一键部署脚本（推荐）

双击运行 deploy.bat
选择部署模式：
- 全局部署：所有项目自动启用
- 项目部署：仅当前项目启用
重启 Claude Code
完成！

方法 2: 手动部署

全局部署

# 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"
      }
    ]
  }
}

项目部署

# 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 自定义系统行为：

{
  "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 项

🛠️ 故障排除

通知不工作

检查依赖是否安装：
```
pip install plyer pygame
```

测试通知：

python ~/.claude/hooks/notification-sender.py test

检查配置文件中的 notification.enabled 是否为 true

Hook 不触发

检查 settings.json 配置是否正确
检查 Python 脚本是否有执行权限
查看 Claude Code 日志：~/.claude/logs/

声音文件缺失

系统会自动使用 Windows 系统 Beep 音效作为回退，不影响功能。

如需自定义声音，参考 sounds/README.md。

📝 卸载

使用部署脚本

运行 deploy.bat
选择"卸载"
选择要卸载的组件（全局/项目）

手动卸载

# 全局部署
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 官方文档
Hook 开发指南 - 项目根目录的 Hook 使用指南
Superpowers 技能集

让 AI 写出更完善的代码！ 🚀

8.5 KiB Raw Permalink Blame History Unescape Escape