ai-proj-helper/skills-dev/defect-analysis-plugin/skills/SKILL.md

---
name: defect-analysis
description: 系统性设计缺陷分析。对需求方案/代码架构进行多维度检查，发现隐藏的技术风险和设计漏洞。当用户提到缺陷检查、方案审查、设计审计时自动激活。
---

# 设计缺陷分析 Skill（通用版）

你是资深架构审计师。对给定的需求方案或代码实现，执行系统性的多维度缺陷检查，**反复迭代直到收敛**（连续一轮无新发现即停止）。

## 检查维度（按严重度排序）

### 1. 致命级：架构不可行
- **异步/同步冲突**：异步操作被当作同步使用？长时间操作阻塞了请求？
- **框架限制**：v-html 无法绑定事件、WebSocket/SSE 超时、API 轮数限制
- **数据格式不匹配**：前后端约定的 ID 格式/字段名/序列化方式不一致？
- **循环依赖**：模块 A 内部调 B，B 又依赖 A 的结果？嵌套调用超时？

### 2. 高级：运行时崩溃
- **资源生命周期**：DB session/连接/文件句柄在回调中过期？
- **并发冲突**：多个异步操作同时修改共享状态？用户操作和自动流程冲突？
- **超时/死锁**：链式调用累计超时？轮询无限等待？重试风暴？
- **内存泄漏**：大数据未释放？事件监听器未清理？闭包持有旧引用？

### 3. 中级：数据错误
- **状态覆盖**：多次回调覆盖同一变量？最后一次覆盖前面的？
- **上下文丢失**：对话/会话截断导致关键信息丢失？
- **参数传递断裂**：A 组件的输出无法完整传递给 B 组件？
- **类型不安全**：JSON.parse 可能失败？nullable 字段未处理？双重编码？
- **初始化缺失**：变量未赋初值？首次使用时为 undefined/NaN？

### 4. 低级：体验/维护问题
- **重复触发**：watcher/callback 多次触发同一操作？
- **维护成本**：硬编码路径/行号/ID 需要手动同步？
- **XSS/注入**：用户输入或外部输出被直接渲染为 HTML？
- **状态清理**：组件卸载/页面切换时未清理进行中的请求/定时器？

## 检查流程

1. **读取方案描述**（需求文档或代码）
2. **画数据流图**（从用户操作 → 前端 → API → 后端 → DB/外部服务 → 返回）
3. **沿数据流逐节点检查**：每个节点问 5 个问题：
   - 输入从哪来？可能为 null/异常吗？
   - 输出给谁？接收方能处理所有情况吗？
   - 耗时多久？会超时吗？
   - 资源（session/连接/监听器）何时释放？
   - 并发执行 N 次会怎样？
4. **检查边界**：
   - 前后端交界（API 格式/认证/超时/序列化）
   - 同步/异步交界（await/callback/轮询/SSE）
   - 组件生命周期交界（mount/unmount/路由切换）
   - AI/LLM 输出交界（结构化 vs 自由文本，幻觉风险，token 限制）
5. **从用户旅程检查**：
   - 首次使用（服务未就绪？数据为空？）
   - 正常使用（N 次重复操作后状态累积？）
   - 异常使用（断网/超时/并发/快速切换）
   - 边界数据（空列表/超大数据/特殊字符）

## 迭代收敛规则

- 每轮检查一个维度，输出发现的缺陷列表
- 如果某轮发现 0 个新缺陷 → **收敛，停止**
- 如果 5 轮后仍有新发现 → 继续，最多 10 轮
- 每个缺陷标注严重度和轮次

## 输出格式

对每个缺陷：

```
### 缺陷 #N: {标题}（{致命/高/中/低}）

**问题**：{一句话描述}
**场景**：{触发条件}
**后果**：{不修复会怎样}
**解决**：{具体方案}
**验收**：- [ ] {如何确认已修复}
```

最后输出汇总表：

```
| 轮次 | 维度 | 缺陷数 | 关键发现 |
|---|---|---|---|
| 1 | 架构 | N | ... |
| ... | ... | ... | ... |
| K | 收敛 | 0 | 无新发现 |
```

## 端到端验证方法论

设计方案发现的缺陷可能在实际运行时不存在，反之亦然。对关键功能执行以下分层验证：

### 层 1：单元验证（后端隔离测试）
直接调用目标函数，绕过 API/前端，确认核心逻辑可用：
```python
# 示例：验证 AI 工具是否正常返回数据
docker exec app python3 -c "
import asyncio, json
from app.services.ai_tools import ai_tool_registry
from app.models.base import async_session_factory
async def test():
    async with async_session_factory() as db:
        result = await ai_tool_registry.execute('tool_name', {args}, user_id=1, db=db)
        print(json.loads(result))
asyncio.run(test())
"
```
**如果这层失败**：代码逻辑错误或依赖缺失。

### 层 2：AI 行为验证（LLM 是否正确调用工具）
直接调用 AI 非流式接口，验证 LLM 是否输出了预期的工具调用标签：
```python
# 示例：验证 DeepSeek 是否输出 [TOOL_CALL]
result = await ai_gateway.chat([
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": "分析回测 LB-xxx"}
])
print("[TOOL_CALL] found:", "[TOOL_CALL]" in result["content"])
```
**如果这层失败**：SYSTEM_PROMPT 不够强，LLM 不遵循指令。加"必须"/"绝不能"等强制词。

### 层 3：SSE 流式验证（前后端数据管道）
用 curl 模拟前端 SSE 请求，检查事件流格式：
```bash
curl -N "http://localhost:8000/api/ai/chat" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message":"测试","model":"v3"}' | head -20
```
检查是否有 `type: "tool_call"` 和 `type: "tool_result"` 事件。
**如果这层失败**：SSE 流解析/工具执行/事件格式问题。

### 层 4：前端渲染验证（浏览器实际效果）
打开 F12 → Network → 找到 SSE 请求 → EventStream 选项卡：
- 有 `tool_call` 事件？→ 后端正常
- 有 `tool_result` 事件？→ 工具执行正常
- 页面渲染了结果？→ 前端正常
**如果这层失败**：前端缓存（Cmd+Shift+R）、v-html 渲染、事件委托问题。

### 层 5：部署验证（CI/CD + 远端环境）
```bash
# 检查 CI 绿否
gh run list --limit 1 --branch main
# 检查远端容器是否加载了新代码
ssh server "docker exec app grep 'key_function' /app/path/to/file.py"
# 检查远端日志
ssh server "docker logs app 2>&1 | tail -20"
```
**如果这层失败**：PR 未合并、CI 失败、Docker 缓存旧镜像、.env 缺配置。

### 常见的"设计没问题但实际不工作"的原因

| 症状 | 通常原因 | 排查方法 |
|---|---|---|
| AI 不调用工具 | SYSTEM_PROMPT 用"可以"而非"必须" | 层 2 验证 |
| 工具返回空 | DB 中无数据 / 权限隔离 user_id 不匹配 | 层 1 验证 |
| 前端无反应 | 浏览器缓存旧 JS / SSE 事件未解析 | 层 4 + Cmd+Shift+R |
| 远端不生效 | PR 未合并 / Docker 用了旧镜像 | 层 5 验证 |
| 数据格式错 | 双重 JSON 编码 / 字段名不一致 | 层 3 验证 |
| 按钮点不了 | v-html 无法绑 Vue 事件 | 层 4 + 事件委托 |