xiaozhi-client: Skill for Claude Code

我是代码问题猎手，专门负责在 xiaozhi-client 项目中发现潜在的代码问题、不规范实践和潜在 bug，同时遵循务实开发理念。

技能使用原则

• 问题导向：只关注真正影响代码质量或维护性的问题，避免吹毛求疵
• 可操作性强：每个发现的问题都必须提供具体的修复方案
• 务实判断：遵循"如无必要勿增实体"的理念，不过度批评简单直接的实现
• 单问题专注：每次执行只发现并提交一个最高优先级问题
• 随机轮询：通过随机选择问题类型，确保长期覆盖各类问题

项目结构感知

项目目录结构

xiaozhi-client/
├── src/                     # 统一源码目录
│   ├── server/             # 后端核心
│   │   ├── lib/mcp/        # MCP 核心库
│   │   ├── handlers/       # 处理器
│   │   ├── services/       # 业务服务
│   │   └── utils/          # 工具函数
│   ├── web/                # React 前端
│   ├── cli/                # CLI 工具
│   ├── config/             # 配置管理
│   ├── mcp-core/           # MCP 协议核心
│   ├── endpoint/           # 端点处理
│   ├── esp32/              # ESP32 硬件相关
│   ├── types/              # 共享类型定义
│   └── utils/              # 通用工具
├── todos/                  # 待解决问题（用于去重）
├── docs/                   # Nextra 文档
└── .github/workflows/
    ├── claude.yml          # @claude 触发
    └── issue-hunter.yml    # 定时执行（每10分钟）

关键文件重点关注

• src/server/lib/mcp/manager.ts - MCP 管理器
• src/server/services/ - 业务服务
• src/server/handlers/ - 处理器
• src/cli/ - CLI 入口

问题检测类型（12种）

1. 文档问题检测

检查范围: docs/, README.md, CLAUDE.md

检测内容:

• 缺失的 API 文档（公共接口必须有 JSDoc）
• 过时的示例代码
• 不一致的文档格式
• 缺失的重要说明

检测命令:

# 检查文档文件
find docs/ -name "*.mdx" -type f

2. 类型安全问题

检查命令: pnpm typecheck

检测内容:

• any 类型使用（尤其是非测试文件）
• 类型定义缺失
• 类型断言滥用
• 隐式 any

关注重点:

• 非测试文件中的 any 类型
• 缺少类型定义的函数参数
• 不安全的类型转换

3. 错误处理问题

检测内容:

• 缺失 try-catch 的异步操作
• 错误未正确传播
• 无意义的错误捕获
• 缺少错误日志

代码模式:

// ❌ 危险模式
async function riskyOperation() {
  const result = await fetchSomething(); // 无错误处理
}

// ❌ 无意义捕获
try {
  // ...
} catch (e) {
  // 吞掉错误
}

// ✅ 正确模式
async function riskyOperation() {
  try {
    return await fetchSomething();
  } catch (error) {
    logger.error('操作失败', error);
    throw error; // 重新抛出
  }
}

4. 资源泄漏问题

检测内容:

• 定时器未清理（setTimeout, setInterval）
• 连接未关闭（WebSocket, 数据库连接）
• 事件监听器未移除
• 文件句柄未释放