| name | issue-hunter |
| description | 自动发现项目中的代码问题并提交 GitHub Issue |
我是代码问题猎手，专门负责在 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 入口检查范围: docs/, README.md, CLAUDE.md
检测内容:
检测命令:
# 检查文档文件
find docs/ -name "*.mdx" -type f
检查命令: pnpm typecheck
检测内容:
关注重点:
检测内容:
代码模式:
// ❌ 危险模式
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 src/ -name "*.ts" -type f -exec wc -l {} + | sort -rn | head -20
检查命令: pnpm check:cpd (jscpd)
阈值: 报告重复率超过 5% 的文件 重点关注: 跨包重复代码
分析输出:
# 运行重复代码检测
pnpm check:cpd
检测内容:
检查方法:
检查范围: src/web/
检测内容:
检查命令:
pnpm typecheck - TypeScript 类型错误pnpm build - 构建错误关注点:
检测内容:
pnpm audit)检测命令:
# 安全审计
pnpm audit
# 检查过时依赖
pnpm outdated
检测内容:
正确模式:
// ✅ 推荐（使用路径别名）
import { MCPManager } from "@/mcp-core";
import { ConfigService } from "@/config";
// ❌ 避免（相对路径）
import { MCPManager } from "../mcp-core";
import { ConfigService } from "../config";
检查命令: pnpm lint
检测内容:
步骤 1.1: 获取现有 open issues
gh issue list --state open --limit 100 --json number,title
步骤 1.2: 读取 todos 目录
ls -la todos/
步骤 1.3: 解析现有问题和 todos
去重策略：
步骤 2.1: 随机选择问题类型
// 使用当前时间戳作为随机种子
const problemTypes = [
'文档问题', '类型安全问题', '错误处理问题', '资源泄漏问题',
'性能问题', '代码重复', '架构问题', '组件设计问题',
'编译时问题', '依赖问题', '路径别名问题', '代码规范问题'
];
const selectedIndex = Math.floor(Date.now() / 1000) % problemTypes.length;
const selectedType = problemTypes[selectedIndex];
步骤 2.2: 针对选定类型执行检测
# 检查公共接口的 JSDoc 覆盖
find src/server src/cli -name "*.ts" ! -path "*/__tests__/*" ! -name "*.test.ts" -exec grep -l "export" {} \;
pnpm typecheck 2>&1 | grep -A 5 "error TS"
# 查找未处理异常的异步函数
grep -r "await.*fetch\|await.*request" src/ --include="*.ts" | grep -v "try\|catch" | head -20
# 查找 setInterval 但没有 clearInterval
grep -r "setInterval" src/ --include="*.ts" -A 10 | grep -v "clearInterval"
# 查找大文件
find src/ -name "*.ts" -type f -exec wc -l {} + | sort -rn | head -20
pnpm check:cpd --threshold 5
# 分析模块依赖
grep -r "import.*from.*\.\./\.\./\.\." src/ --include="*.ts" | head -20
# 查找大组件文件
find src/web -name "*.tsx" -type f -exec wc -l {} + | sort -rn | head -20
pnpm typecheck
pnpm build
pnpm audit --json
pnpm outdated
# 查找相对路径导入
grep -r "from.*\.\./\.\." src/ --include="*.ts" | grep -v "__tests__" | head -20
pnpm lint 2>&1 | grep -E "error|warning"
步骤 2.3: 评估问题严重程度
严重程度标准：
步骤 3.1: 选择最高优先级问题
步骤 3.2: 生成 Issue 报告
报告结构：
## 问题描述
[详细说明发现的问题]
## 问题位置
`path/to/file.ts:行号`
## 严重程度
[Critical / High / Medium / Low]
## 影响范围
[说明问题可能造成的影响]
## 修复方案
[详细的修复步骤或代码示例]
## 相关代码
\`\`\`typescript
[有问题的代码片段]
\`\`\`
Issue 标题格式：
Claude: [BUG] 简短描述Claude: [CODE] 简短描述Claude: [SECURITY] 简短描述Claude: [PERF] 简短描述Claude: [ARCH] 简短描述标签使用：
bug - 功能错误code-quality - 代码质量问题security - 安全问题performance - 性能问题architecture - 架构问题documentation - 文档问题good first issue - 适合新手修复的简单问题步骤 3.3: 创建 Issue
gh issue create \
--title "Claude: [类型] 简短描述" \
--body "Issue 内容" \
--label "bug,code-quality"
创建 Issue 后，
.github/workflows/auto-claude-comment.ymlworkflow 会自动添加 "@claude" 评论来触发处理流程。
使用以下命令调用此技能：
/issue-hunter
或使用 Skill 工具：
{
"skill": "issue-hunter"
}
技能执行后会返回：
## 问题发现报告
**选定问题类型**: [类型]
**发现的问题数量**: [数量]
**最高优先级问题**: [问题]
### 问题详情
**问题类型**: [类型]
**严重程度**: [严重程度]
**文件位置**: `path/to/file.ts:行号`
### 问题描述
[详细描述]
### 修复方案
[修复步骤或代码]
### Issue 已创建
🔗 [Issue #XXX: 标题](https://github.com/shenjingnan/xiaozhi-client/issues/XXX)
issue-hunter 发现问题后创建 Issueci-validator 检查代码是否通过 CIpath-alias-validator 检查路径别名使用issue-hunter 记录严重违规行为type-validator 检查类型问题issue-hunter 记录未解决的类型安全问题🔍 正在分析项目代码...
⚠️ 随机选择问题类型: 资源泄漏问题
🔍 检测范围: src/server/lib/mcp/, src/server/utils/
⚠️ 发现问题：WebSocket 连接未正确关闭
📍 位置：src/server/utils/某个传输相关文件:45
📊 严重程度：High
📝 问题描述：
当连接失败时，WebSocket 连接没有被正确关闭，可能导致资源泄漏。
✨ 修复方案：
```typescript
// 在 catch 块中添加连接关闭逻辑
catch (error) {
if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
this.ws.close();
}
throw error;
}
📮 Issue 已创建： 🔗 Issue #123: Claude: [BUG] WebSocket 连接未正确关闭导致资源泄漏
### 示例 2：发现类型安全问题
🔍 正在分析项目代码...
⚠️ 随机选择问题类型: 类型安全问题
🔍 检测命令: pnpm typecheck
⚠️ 发现问题：非测试文件中使用 any 类型
📍 位置：src/server/services/某个服务文件.ts:78
📊 严重程度：Medium
📝 问题描述： 非测试文件中使用 any 类型绕过类型检查，降低了代码的类型安全性。
✨ 修复方案：
// 将 any 替换为具体的类型定义
interface ProcessOptions {
endpoint: string;
timeout: number;
}
function processData(options: ProcessOptions): Result {
// ...
}
📮 Issue 已创建： 🔗 Issue #124: Claude: [CODE] 非测试文件中 any 类型使用不当
### 示例 3：发现架构问题
🔍 正在分析项目代码...
⚠️ 随机选择问题类型: 架构问题
🔍 检测范围: src/server/services/, src/server/handlers/
⚠️ 发现问题：模块职责不清晰
📍 位置：src/server/services/某个服务文件.ts
📊 严重程度：Medium
📝 问题描述： StatusService 同时负责状态管理和通知发送，违反了单一职责原则。建议将通知发送逻辑拆分到 NotificationService。
✨ 修复方案：
// 重构 StatusService，只保留状态管理逻辑
// 将通知发送逻辑移至 NotificationService
class StatusService {
getStatus(): ServiceStatus {
return this.currentStatus;
}
updateStatus(status: ServiceStatus): void {
this.currentStatus = status;
// 移除通知发送逻辑
}
}
📮 Issue 已创建： 🔗 Issue #125: Claude: [ARCH] StatusService 职责不清晰
## 务实开发指导
### 何时报告问题
- **实际遇到问题**：当代码确实存在 bug 或风险时
- **影响可维护性**：当问题严重影响代码维护时
- **违反项目规范**：当代码明显违反 CLAUDE.md 规定时
- **安全或性能风险**：当存在安全漏洞或性能瓶颈时
### 何时不报告问题
- **预防性设计**：为了"可能的需要"而建议的改进
- **理论完美**：为了代码的"优雅"而过度抽象
- **过度优化**：在没有性能问题时优化性能
- **设计模式**：为了使用设计模式而使用
### 判断标准
在报告问题前，问自己：
1. 这个问题是否真的影响功能或维护性？
2. 这个问题是否在其他地方已经被覆盖（todos 或 open issues）？
3. 修复这个问题的收益是否大于成本？
4. 是否符合"如无必要勿增实体"的原则？
安全审计技能，用于检查和修复依赖安全问题
文档自动生成
CI检查验证和质量保障
生成代码评审友好的 commit 信息
开发流程检查技能，确保代码修改后执行必要的质量检查
文档创建技能，用于创建标准化的项目文档