issue-hunter

xiaozhi-client/ (Monorepo)
├── apps/                    # 应用层
│   ├── backend/            # 后端核心
│   │   ├── lib/mcp/        # MCP 核心库
│   │   ├── handlers/       # 16个处理器
│   │   ├── services/       # 业务服务
│   │   └── transports/     # 传输适配器
│   └── frontend/           # React 前端
├── packages/               # 共享包
│   ├── cli/               # CLI 工具
│   ├── config/            # 配置管理
│   ├── mcp-core/          # MCP 核心库
│   └── shared-types/      # 共享类型
├── todos/                  # 待解决问题（用于去重）
├── docs/                   # Nextra 文档
└── .github/workflows/
    ├── claude.yml          # @claude 触发
    └── issue-hunter.yml    # 定时执行（每10分钟）

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

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

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

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

// ❌ 未清理定时器
const timer = setInterval(() => {
  // ...
}, 1000);
// 缺少 clearInterval

// ✅ 正确清理
const timer = setInterval(() => {
  // ...
}, 1000);
// 在 cleanup 中清理
cleanup() {
  clearInterval(timer);
}

# 查找大文件
find apps/ packages/ -name "*.ts" -type f -exec wc -l {} + | sort -rn | head -20

# 运行重复代码检测
pnpm check:cpd

# 安全审计
pnpm audit

# 检查过时依赖
pnpm outdated

// ✅ 推荐（使用路径别名）
import { UnifiedMCPServer } from "@core";
import { WebSocketAdapter } from "@transports";

// ❌ 避免（相对路径）
import { UnifiedMCPServer } from "../core";
import { WebSocketAdapter } from "../transports";

gh issue list --state open --limit 100 --json number,title

ls -la todos/

// 使用当前时间戳作为随机种子
const problemTypes = [
  '文档问题', '类型安全问题', '错误处理问题', '资源泄漏问题',
  '性能问题', '代码重复', '架构问题', '组件设计问题',
  '编译时问题', '依赖问题', '路径别名问题', '代码规范问题'
];
const selectedIndex = Math.floor(Date.now() / 1000) % problemTypes.length;
const selectedType = problemTypes[selectedIndex];

# 检查公共接口的 JSDoc 覆盖
find apps/backend packages/cli -name "*.ts" ! -path "*/__tests__/*" ! -name "*.test.ts" -exec grep -l "export" {} \;

pnpm check:type 2>&1 | grep -A 5 "error TS"

# 查找未处理异常的异步函数
grep -r "await.*fetch\|await.*request" apps/ packages/ --include="*.ts" | grep -v "try\|catch" | head -20

# 查找 setInterval 但没有 clearInterval
grep -r "setInterval" apps/ packages/ --include="*.ts" -A 10 | grep -v "clearInterval"

# 查找大文件
find apps/ packages/ -name "*.ts" -type f -exec wc -l {} + | sort -rn | head -20

pnpm check:cpd --threshold 5

# 分析模块依赖
grep -r "import.*from.*\.\./\.\./\.\." apps/ packages/ --include="*.ts" | head -20

# 查找大组件文件
find apps/frontend/src -name "*.tsx" -type f -exec wc -l {} + | sort -rn | head -20

pnpm check:type
pnpm build

pnpm audit --json
pnpm outdated

# 查找相对路径导入
grep -r "from.*\.\./\.\." apps/ packages/ --include="*.ts" | grep -v "__tests__" | head -20

pnpm lint 2>&1 | grep -E "error|warning"

## 问题描述

[详细说明发现的问题]

## 问题位置

`path/to/file.ts:行号`

## 严重程度

[Critical / High / Medium / Low]

## 影响范围

[说明问题可能造成的影响]

## 修复方案

[详细的修复步骤或代码示例]

## 相关代码

\`\`\`typescript
[有问题的代码片段]
\`\`\`

gh issue create \
  --title "Claude: [类型] 简短描述" \
  --body "Issue 内容" \
  --label "bug,code-quality"

/issue-hunter

{
  "skill": "issue-hunter"
}

## 问题发现报告

**选定问题类型**: [类型]
**发现的问题数量**: [数量]
**最高优先级问题**: [问题]

### 问题详情

**问题类型**: [类型]
**严重程度**: [严重程度]
**文件位置**: `path/to/file.ts:行号`

### 问题描述

[详细描述]

### 修复方案

[修复步骤或代码]

### Issue 已创建

🔗 [Issue #XXX: 标题](https://github.com/shenjingnan/xiaozhi-client/issues/XXX)

🔍 正在分析项目代码...

⚠️ 随机选择问题类型: 资源泄漏问题

🔍 检测范围: apps/backend/lib/mcp/, apps/backend/transports/

⚠️ 发现问题：WebSocket 连接未正确关闭

📍 位置：apps/backend/transports/WebSocketAdapter.ts:45

📊 严重程度：High

📝 问题描述：
当连接失败时，WebSocket 连接没有被正确关闭，可能导致资源泄漏。

✨ 修复方案：
```typescript
// 在 catch 块中添加连接关闭逻辑
catch (error) {
  if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
    this.ws.close();
  }
  throw error;
}

### 示例 2：发现类型安全问题

// 将 any 替换为具体的类型定义
interface ProcessOptions {
  endpoint: string;
  timeout: number;
}

function processData(options: ProcessOptions): Result {
  // ...
}

### 示例 3：发现架构问题

// 重构 StatusService，只保留状态管理逻辑
// 将通知发送逻辑移至 NotificationService

class StatusService {
  getStatus(): ServiceStatus {
    return this.currentStatus;
  }

  updateStatus(status: ServiceStatus): void {
    this.currentStatus = status;
    // 移除通知发送逻辑
  }
}

## 务实开发指导

### 何时报告问题
- **实际遇到问题**：当代码确实存在 bug 或风险时
- **影响可维护性**：当问题严重影响代码维护时
- **违反项目规范**：当代码明显违反 CLAUDE.md 规定时
- **安全或性能风险**：当存在安全漏洞或性能瓶颈时

### 何时不报告问题
- **预防性设计**：为了"可能的需要"而建议的改进
- **理论完美**：为了代码的"优雅"而过度抽象
- **过度优化**：在没有性能问题时优化性能
- **设计模式**：为了使用设计模式而使用

### 判断标准
在报告问题前，问自己：
1. 这个问题是否真的影响功能或维护性？
2. 这个问题是否在其他地方已经被覆盖（todos 或 open issues）？
3. 修复这个问题的收益是否大于成本？
4. 是否符合"如无必要勿增实体"的原则？