feat(sync): add install-skills.sh + install metadata to all 62 plugins
- Add install_name, install_type, dir_category fields to all 62 plugin.json files to resolve name-mapping and skill-vs-command routing issues - Add install-skills.sh: idempotent cross-machine skill sync script - Routes skill→~/.claude/skills/<name>/, command→~/.claude/commands/<name>.md - rsync full skills/ directory (preserves multi-file skills like dev-test, req-deploy) - State file ~/.claude/.installed-skills.json tracks installed versions - Conflict detection: warns before overwriting locally modified files - --dry-run, --category, --force, --cleanup, --list flags - Add 9 new plugins migrated from local ~/.claude (agent-swarm, ai-chat, defect-analysis, executing-plans, finishing-branch, frontend-design, req-audit, req-lookback, req-retro) - Add update-plugin-meta.py helper used to bulk-update plugin.json - Fix siyuan SKILL.md: remove hardcoded server credentials, use env vars Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
11
skills-dev/defect-analysis-plugin/.claude-plugin/plugin.json
Normal file
11
skills-dev/defect-analysis-plugin/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "defect-analysis-plugin",
|
||||
"description": "系统性设计缺陷分析。对需求方案/代码架构进行多维度检查，发现隐藏的技术风险和设计漏洞。当用户提到缺陷检查、方案审查、设计审计时自动激活。",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "qiudl"
|
||||
},
|
||||
"install_name": "defect-analysis",
|
||||
"install_type": "command",
|
||||
"dir_category": "dev"
|
||||
}
|
||||
159
skills-dev/defect-analysis-plugin/skills/SKILL.md
Normal file
159
skills-dev/defect-analysis-plugin/skills/SKILL.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
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 + 事件委托 |
|
||||
Reference in New Issue
Block a user