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

name, description

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

设计缺陷分析 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/前端，确认核心逻辑可用：

# 示例：验证 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 是否输出了预期的工具调用标签：

# 示例：验证 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 请求，检查事件流格式：

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 + 远端环境）

# 检查 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 + 事件委托