@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

package/plugins/api/skills/import/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: import
+description: |
+  导入 Swagger - 解析 OpenAPI 文档并展示接口概览
+---
+
+# 导入 Swagger
+
+从配置的数据源解析 Swagger/OpenAPI 文档，展示接口概览。
+
+## 命令格式
+
+```
+/api:import [--name=服务名] [--url=临时URL] [--file=临时文件]
+```
+
+## 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| `--name` | 仅导入指定名称的数据源（默认导入所有） |
+| `--url` | 临时指定 URL，不修改配置文件 |
+| `--file` | 临时指定本地文件，不修改配置文件 |
+
+## 执行流程
+
+### 前置检查
+
+参考 `_common.md` 的「命令执行前置检查」。
+
+### 解析流程
+
+1. **读取数据源配置**
+   - 有 `--url` 或 `--file` 参数 → 使用临时数据源
+   - 无参数 → 从 `.api-config.json` 读取所有 sources
+   - 有 `--name` → 过滤匹配的 source
+
+2. **逐个解析数据源**
+
+   对每个 source 调用 `swagger-parser.py`（`mode=summary`；URL 数据源用 `--url`，本地文件用 `--file`）。
+
+3. **展示解析结果**
+
+   ```
+   导入 Swagger 文档
+
+   === 主服务 (http://localhost:8080/swagger/doc.json) ===
+   版本：OpenAPI 3.0.1
+   标题：My API Server
+   接口总数：42
+
+   按 Tag 分组：
+   
+   Tag          数量 描述                        
+   
+   用户管理      8   用户注册、登录、信息管理      
+   订单管理      12  订单创建、查询、状态流转      
+   商品管理      10  商品 CRUD、分类、搜索        
+   系统设置      6   权限、角色、配置管理          
+   无分组        6   未归类接口                   
+   
+
+   ✅ 导入完成，使用 /api:search <关键词> 搜索接口
+   ```
+
+4. **解析失败处理**
+
+   | 错误 | 提示 |
+   |------|------|
+   | URL 无法访问 | `❌ 无法访问 <url>，请检查后端服务是否启动` |
+   | 文件不存在 | `❌ 文件 <path> 不存在` |
+   | 格式错误 | `❌ 文件格式不是有效的 OpenAPI 文档` |
+   | Python 未安装 | `❌ 需要 Python 3，请先安装：brew install python3` |
+
+## 多数据源导入
+
+配置了多个数据源时，逐个导入并汇总：
+
+```
+导入 Swagger 文档
+
+=== 主服务 ===
+接口总数：42 ✅
+
+=== 支付服务 ===
+接口总数：15 ✅
+
+汇总：2 个数据源，57 个接口
+```
+
+## 注意事项
+
+- 每次 import 都是实时解析，不做缓存
+- 大型 Swagger 文档（>500 接口）时，Python 脚本仅输出摘要，具体接口按需查询
+- 如果 Swagger 文档需要认证（如 Bearer Token），需在 URL 中携带或在配置中添加 headers（后续版本支持）

package/plugins/api/skills/map/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: map
+description: |
+  字段映射 - 分析接口请求/响应字段并映射到前端类型
+---
+
+# 字段映射
+
+解析指定 API 接口的请求参数和响应字段，展示后端到前端的完整字段映射关系。
+
+## 命令格式
+
+```
+/api:map <METHOD> <path> [--name=服务名] [--case=camelCase|snake_case|original]
+```
+
+## 参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `METHOD` | 是 | HTTP 方法：GET / POST / PUT / DELETE / PATCH |
+| `path` | 是 | API 路径，如 `/api/v1/users/{id}` |
+| `--name` | 否 | 指定数据源，默认搜索所有数据源 |
+| `--case` | 否 | 覆盖配置的字段命名风格 |
+
+## 执行流程
+
+### 前置检查
+
+参考 `_common.md` 的「命令执行前置检查」。
+
+### 映射流程
+
+1. **解析接口定义**
+
+   调用 `swagger-parser.py`（`mode=detail`，传入接口路径），获取该接口的完整 schema（参数、请求体、响应体、$ref 解析后的结构）。
+
+2. **AI 分析字段映射**
+
+   读取 Python 脚本输出的 JSON，按 `_common.md` 中的「字段映射规则」和「类型映射」进行分析。
+
+3. **展示映射结果**
+
+   分三个部分展示：路径/查询参数、请求体、响应体。
+
+### 输出格式
+
+```
+字段映射：GET /api/v1/users/{id}
+
+描述：获取用户详情
+Tag：用户管理
+
+路径参数 
+
+| 字段 | 类型 | 必填 | 前端字段名 | 说明 |
+|------|------|------|-----------|------|
+| id   | integer | ✅ | id | 用户ID |
+
+查询参数 
+
+（无）
+
+响应字段映射 (200) 
+
+| # | 后端字段 | 类型 | 必填 | 前端字段名 | 转换 | 说明 |
+|---|---------|------|------|-----------|------|------|
+| 1 | id | integer | ✅ | id | — | 用户ID |
+| 2 | user_name | string | ✅ | userName | snake→camel | 用户名 |
+| 3 | avatar_url | string | — | avatarUrl | snake→camel | 头像地址 |
+| 4 | email | string | ✅ | email | — | 邮箱 |
+| 5 | created_at | string(date-time) | ✅ | createdAt | snake→camel | 创建时间 |
+| 6 | is_active | boolean | — | isActive | snake→camel | 是否激活 |
+| 7 | role_list | array | — | roleList | snake→camel | 角色列表 |
+| 7.1 | role_id | integer | ✅ | roleId | snake→camel | 角色ID |
+| 7.2 | role_name | string | ✅ | roleName | snake→camel | 角色名 |
+| 8 | department | object | — | department | — | 所属部门 |
+| 8.1 | dept_id | integer | ✅ | deptId | snake→camel | 部门ID |
+| 8.2 | dept_name | string | ✅ | deptName | snake→camel | 部门名 |
+
+TypeScript 类型预览 
+
+interface UserDetailResponse {
+  id: number;
+  userName: string;
+  avatarUrl?: string;
+  email: string;
+  createdAt: string;
+  isActive?: boolean;
+  roleList?: {
+    roleId: number;
+    roleName: string;
+  }[];
+  department?: {
+    deptId: number;
+    deptName: string;
+  };
+}
+
+使用 /api:gen GET /api/v1/users/{id} 生成完整代码
+```
+
+### POST/PUT 请求体映射
+
+POST/PUT 等有请求体的接口，额外展示请求体映射：
+
+```
+请求体字段映射 (application/json) 
+
+| # | 后端字段 | 类型 | 必填 | 前端字段名 | 转换 | 说明 |
+|---|---------|------|------|-----------|------|------|
+| 1 | user_name | string | ✅ | userName | snake→camel | 用户名 |
+| 2 | email | string | ✅ | email | — | 邮箱 |
+| 3 | password | string | ✅ | password | — | 密码 |
+| 4 | role_ids | array[integer] | — | roleIds | snake→camel | 角色ID列表 |
+
+TypeScript 类型预览 
+
+interface CreateUserParams {
+  userName: string;
+  email: string;
+  password: string;
+  roleIds?: number[];
+}
+```
+
+### 嵌套对象处理
+
+- 嵌套对象使用 `` 缩进展示层级关系
+- 编号使用点号分隔表示层级（如 `7.1`、`7.2`）
+- TypeScript 类型中，嵌套对象复杂时提取为独立 interface
+
+### 接口未找到
+
+```
+❌ 未找到接口：GET /api/v1/users/{id}
+
+可能原因：
+- 路径拼写有误
+- 使用 /api:search 用户 查找正确路径
+- 使用 /api:import 确认数据源已导入
+```
+
+## 批量映射
+
+支持通配符批量映射同一路径下的所有方法：
+
+```
+/api:map * /api/v1/users/{id}
+
+→ 展示 GET、PUT、DELETE /api/v1/users/{id} 的所有映射
+```

package/plugins/api/skills/search/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: search
+description: |
+  搜索接口 - 按关键词搜索 Swagger 中的 API 接口
+---
+
+# 搜索接口
+
+从 Swagger 文档中按关键词搜索匹配的 API 接口。
+
+## 命令格式
+
+```
+/api:search <关键词> [--name=服务名] [--tag=分组名] [--method=GET|POST|PUT|DELETE]
+```
+
+## 参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `关键词` | 是 | 搜索关键词，匹配路径、描述、summary |
+| `--name` | 否 | 指定数据源名称，默认搜索所有 |
+| `--tag` | 否 | 按 Tag 分组过滤 |
+| `--method` | 否 | 按 HTTP 方法过滤 |
+
+## 执行流程
+
+### 前置检查
+
+参考 `_common.md` 的「命令执行前置检查」。
+
+### 搜索流程
+
+1. **读取数据源配置**
+
+2. **调用 `swagger-parser.py`**（`mode=search`，传入关键词）搜索匹配接口。
+
+3. **展示搜索结果**
+
+   ```
+   搜索「用户」
+
+   找到 5 个匹配接口（主服务）：
+
+   
+   #  方法    路径                      描述            
+   
+   1  GET     /api/v1/users            获取用户列表     
+   2  POST    /api/v1/users            创建用户         
+   3  GET     /api/v1/users/{id}       获取用户详情     
+   4  PUT     /api/v1/users/{id}       更新用户信息     
+   5  DELETE  /api/v1/users/{id}       删除用户         
+   
+
+   使用 /api:map GET /api/v1/users/{id} 查看字段映射
+   使用 /api:gen GET /api/v1/users/{id} 生成代码
+   ```
+
+4. **无结果时**
+
+   ```
+   搜索「xxx」
+
+   未找到匹配接口。
+
+   尝试：
+   - 使用更短的关键词
+   - /api:import 确认数据源已导入
+   - /api:search --tag=用户管理 按分组浏览
+   ```
+
+### 搜索匹配规则
+
+关键词同时匹配以下字段（任一匹配即返回）：
+- API 路径（如 `/users` 匹配 `/api/v1/users`）
+- summary / description（中英文模糊匹配）
+- operationId
+- Tag 名称
+
+### 按 Tag 浏览
+
+不传关键词时列出所有 Tag 供浏览：
+
+```
+/api:search --tag=用户管理
+
+用户管理 — 8 个接口
+
+
+#  方法    路径                      描述            
+
+1  GET     /api/v1/users            获取用户列表     
+......     ...                      ...             
+
+```

package/plugins/diag/skills/audit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: audit
+description: |
+  查询 Diag 审计日志 - 按主机/服务/时间过滤
+---
+
+# /diag:audit - 审计查询
+
+查询 Diag 插件的 SSH 命令审计日志。审计记录按日切分，保留 30 天。
+
+---
+
+## 参数
+
+| 参数 | 说明 | 默认 |
+|---|---|---|
+| `--host=<name>` | 按目标主机过滤 | 全部 |
+| `--service=<name>` | 按服务名过滤 | 全部 |
+| `--from=YYYY-MM-DD` | 起始日期（本地时区） | 7 天前 |
+| `--to=YYYY-MM-DD` | 截止日期 | 今天 |
+| `--limit=<N>` | 最多输出条数 | 50 |
+| `--temp-files` | 只显示有远端临时文件写入的记录 | 关闭 |
+
+---
+
+## 执行流程
+
+### 1. 扫描审计文件
+
+```bash
+ls ~/.claude-diag/audit/command_audit-*.jsonl 2>/dev/null
+```
+
+若目录不存在或无文件 → 提示"暂无审计记录，`/diag:init` 初始化后使用 `/diag:diagnose` 会产生记录"。
+
+### 2. 按日期过滤文件
+
+审计文件名是 `command_audit-YYYY-MM-DD.jsonl`，按 `--from` / `--to` 范围筛选要读的文件。
+
+默认 `--from` = 今天前 7 天，`--to` = 今天。
+
+### 3. 读取并过滤记录
+
+```bash
+cat ~/.claude-diag/audit/command_audit-{dates}.jsonl | jq -c '
+    select(
+        (.host == "<host>" or "<host>" == "") and
+        (.service == "<service>" or "<service>" == "")
+    )
+' | tail -n <limit>
+```
+
+字段：`timestamp / session_id / diag_session_id / operator / host / service / command / exit_code / stdout_length / log_snippet_hash / tmp_write / hooks_passed`
+
+`--temp-files` 时用 jq 过滤 `tmp_write != null`：
+
+```bash
+cat ... | jq -c 'select(.tmp_write != null)'
+```
+
+### 4. 格式化输出
+
+表格形式（默认）：
+
+```
+Diag 审计（2026-04-13 至 2026-04-20，共 23 条）
+
+时间                    主机            服务        命令                                        退出码
+2026-04-20T02:30:15Z   prod-web-01    order-api   ssh prod-web-01 tail -n 2000 /v/l/order.l    0
+2026-04-20T02:31:08Z   prod-web-01    order-api   ssh prod-web-01 grep ERROR /v/l/order.l      0
+2026-04-19T22:05:42Z   prod-web-02    user-svc    ssh prod-web-02 tail -n 500 /v/l/user.log    0
+...
+
+完整记录：cat ~/.claude-diag/audit/command_audit-*.jsonl | jq '.'
+```
+
+聚合摘要（若记录 > 20）：
+```
+统计
+- 主机分布：prod-web-01 (15), prod-web-02 (8)
+- 服务分布：order-api (15), user-svc (8)
+- 成功率：23/23 (100%)
+- 高频命令：tail (18), grep (5)
+```
+
+### 5. 边界说明
+
+- 审计日志**不含** stdout 全文（只存 SHA-256 哈希 + 字节长度），保护敏感信息
+- 若审计文件损坏（无效 JSON 行），跳过该行并提示"⚠️ 第 N 行 JSON 解析失败"
+- 只读查询，**不修改**审计文件
+
+---
+
+## 常用场景
+
+```bash
+/diag:audit                                              # 近 7 天全部
+/diag:audit --host=prod-web-01                           # 指定主机
+/diag:audit --service=order-api --from=2026-04-15        # 服务 + 起始日期
+/diag:audit --limit=5                                    # 只看最近 5 条
+/diag:audit --temp-files                                 # 只看有远端临时文件写入的记录
+/diag:audit --temp-files --host=prod-web-01              # 指定主机的临时文件记录
+```

package/plugins/diag/skills/diag/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: diag
+description: |
+  生产诊断插件 - 列出 init / diagnose / audit 子命令
+---
+
+# Diag - 生产诊断插件
+
+**只读拉日志 · AI 解析堆栈 · 关联代码 · 给修复建议**
+
+与 [claude-safe-ops](https://github.com/zhouhao4221/claude-safe-ops) 互补：它管**执行类**运维动作，本插件管**只读诊断**。
+
+---
+
+## 子命令
+
+| 命令 | 用途 |
+|---|---|
+| `/diag:init` | 初始化 `~/.claude-diag/` + 生成服务清单模板 + 依赖检查 |
+| `/diag:diagnose <报错描述> [--service=<name>]` | 报错定位主流程（SSH 拉日志 → 堆栈解析 → 代码关联 → 修复建议） |
+| `/diag:audit [--host] [--service] [--from] [--to] [--limit]` | 审计日志查询（默认近 7 天） |
+
+---
+
+## 快速开始
+
+```bash
+/diag:init                              # 初始化配置
+# 编辑 ~/.claude-diag/config/services.yaml，登记真实服务
+/diag:diagnose 订单接口刚才报 500        # 开始诊断
+```
+
+---
+
+## 核心边界
+
+- ✅ **读**：`tail / head / cat / grep / awk / sed / less / wc / find -name / ls / ps / df / free / uptime` 等只读命令
+- ❌ **写**：禁止 `rm / mv / cp / chmod / 重定向 / 服务控制 / 包管理 / DB 写 / 一切修改类操作`
+- ❌ **代码**：修复建议以文字形式给出，插件**不触发** Edit / Write 改动仓库
+
+所有 SSH 操作都会被 5 类风控 Hook 拦截校验，并落 JSONL 审计。

package/plugins/diag/skills/diagnose/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: diagnose
+description: |
+  生产报错定位 - SSH 拉日志 → AI 解析堆栈 → 本地代码关联 → 修复建议
+---
+
+# /diag:diagnose - 报错定位
+
+通过自然语言描述报错 → 插件拉取生产日志 → AI 识别堆栈 → 在本地代码关联源码 → 输出诊断报告和修复建议。
+
+**全程只读**，所有 SSH 命令都会经过 5 类 Hook 校验，审计落盘。
+
+---
+
+## 参数
+
+| 参数 | 说明 | 默认 |
+|---|---|---|
+| `<报错描述>` | 自然语言描述（必填），如 "订单提交接口刚才报 500" | - |
+| `--service=<name>` | 指定服务（可选，否则让用户选） | - |
+| `--lines=<N>` | 拉取日志的行数（tail -n N） | 2000 |
+| `--pattern=<regex>` | grep 过滤的正则，覆盖默认 | `ERROR\|Exception\|FATAL\|PANIC` |
+
+---
+
+## 执行流程
+
+### 0. Session 初始化
+
+每次执行 `/diag:diagnose` 时，在读取服务清单前先完成 session 管理：
+
+1. 清理本地超过 2h 的遗留 session 文件（`$DIAG_HOME/tmp/.current-session`、`runtime/tmp-*.json`）
+2. 若上一轮 session 文件仍存在，读取旧 session id，对本次诊断涉及的每台主机各执行一次远端清理（`rm -f /tmp/claude-diag-<OLD_SESSION>-*`）；此命令通过 write-guard 的 tmp 白名单，审计落盘
+3. 生成新 session id（8 位十六进制），写入本地 session 文件
+
+### 1. 读取服务清单
+
+调用 `services-config.sh list` 获取服务列表。配置文件不存在 → 提示 `/diag:init`，终止。
+
+### 2. 选择目标服务
+
+- `--service` 已指定 → 校验存在后使用
+- 未指定 → 向用户展示服务列表，让用户选（单选或"全部"）
+
+也接受自然语言匹配：用户描述里提到 "订单接口"，AI 可以匹配 `order-api` 服务，展示后让用户确认。
+
+### 3. 构造 SSH 拉日志命令
+
+从选中服务读取：
+- `host`
+- `log_paths`（数组）
+- `language_hint`（可选，传给 stack-analyzer 技能作识别提示）
+
+**命令模板**（每条日志单独执行一次）：
+
+```bash
+# 标准只读（优先使用）
+ssh <host> "tail -n <lines> <log_path> | grep -B2 -A 30 -E '<pattern>'"
+
+# 落远端临时文件（数据量大、需要多步处理时使用）
+ssh <host> "tail -n <lines> <log_path> | grep -E '<pattern>' | tee -a /tmp/claude-diag-<session>-<topic>.log"
+# 之后读回
+ssh <host> "cat /tmp/claude-diag-<session>-<topic>.log"
+# 清理（诊断结束时执行）
+ssh <host> "rm -f /tmp/claude-diag-<session>-*"
+```
+
+**命令约束**：
+- 优先纯 stream（stdout 回本地），避免不必要的远端写入
+- 远端临时文件路径必须以 `/tmp/claude-diag-<session>-` 开头（`<session>` 即当前 session id）
+- 写入只允许 `tee -a`（append），禁止裸 `>` / `>>`
+- 清理只允许 `rm -f /tmp/claude-diag-<session>-*`，禁止 `-r` / `-rf`
+- 禁止在 `/tmp` 下创建子目录
+- 生产机 `/tmp` 可能有容量或 noexec 限制；若 `tee -a` 失败，降级到纯 stream 模式
+- 目标 host 必须在 `services.yaml` 登记
+
+### 4. 执行 SSH 拉日志
+
+通过 Bash 工具执行构造好的命令。Hook 链会依次校验：
+- `validate-hooks`（首次校验完整性）
+- `host-whitelist`（host 在白名单）
+- `command-whitelist`（每个 verb 在白名单）
+- `write-guard`（无写操作）
+
+若任一 Hook 拒绝 → 展示拒绝理由给用户，**不要**尝试绕过（如删选项、改写命令），而是向用户说明并询问是否调整需求。
+
+### 5. AI 识别堆栈（stack-analyzer 技能）
+
+日志拉回后，由 `stack-analyzer` 技能（自动触发）根据 `language_hint` 识别堆栈格式，抽取：
+- 异常类 / 错误类型
+- 错误消息
+- 堆栈帧（文件、行号、方法名）
+
+### 6. 本地代码关联
+
+对每个堆栈帧：
+- 用 `Grep` 在当前仓库按 类名 / 方法名 / 文件名 查找
+- 用 `Read` 查看命中位置的前后 15 行，理解上下文
+
+若堆栈帧对应的源码在当前仓库找不到 → 标注"**本仓库外**"，不强行定位。
+
+### 7. 生成诊断报告
+
+**固定模板**：
+
+```
+原因：<异常类型> - <根本原因推断>
+
+相关代码：
+  - <file_path>:<line> - <方法/类>（<匹配方式：精确匹配 / 模糊匹配 / 本仓库外>）
+  - ...
+
+完整堆栈：
+  <堆栈前 5-10 帧>
+
+修复建议：
+  <具体到文件/函数的文字建议；必要时给出代码片段，但不自动应用>
+
+审计：
+  - 主机：<host>
+  - 拉取日志：<log_paths>
+  - SSH 命令：<3-5 条>
+  - 审计记录：~/.claude-diag/audit/command_audit-<date>.jsonl
+
+未改动任何远程资源和本地代码。如需应用修复，你自己决定并手动执行。
+
+Session 清理：
+  - 远端临时文件：/tmp/claude-diag-<session>-* 已清理 / 无遗留
+  - 本地 session 文件：~/.claude-diag/tmp/.current-session
+```
+
+### 8. 清理远端临时文件
+
+诊断结束后（输出报告之前），对本次涉及的每台主机执行清理：
+
+```bash
+ssh <host> "rm -f /tmp/claude-diag-<session>-*"
+```
+
+**条件**：仅在本次诊断过程中确实用了 `tee -a` 写入过远端临时文件时执行；纯 stream 模式无需清理。
+
+清理失败不中断诊断报告输出，但在 Session 清理一栏标注"⚠️ 清理失败，请手动执行"。
+
+### 9. 可选：追查链路
+
+若用户要求深入（"再看下 user.log"），按同样流程再拉一次，不主动扩大范围。
+
+---
+
+## 边界
+
+- **只拉日志**：本期不查 DB、不摸文件内容、不看进程
+- **不改代码**：修复建议纯文字，不触发 Edit / Write
+- **不递归**：Claude 不应在本次会话中"为了调查而 SSH 到其他未登记主机"
+- **审计友好**：所有 SSH 命令走 Bash 工具，自动被 `audit-log.sh` 记录
+
+---
+
+## 故障排查
+
+| 现象 | 可能原因 |
+|---|---|
+| Hook 拒绝 host | 服务未在 `services.yaml` 登记 → `/diag:init` 补充 |
+| Hook 拒绝命令 | AI 构造了非白名单命令，需要调整（如不要用 `tee`） |
+| 拉不到日志 | SSH 本身不通（key / agent / 网络）→ 先本地测 `ssh <host> echo ok` |
+| 堆栈识别不准 | 服务设置 `language_hint` 后重试；或把日志片段粘给用户让其确认 |
+| 本地找不到代码 | 堆栈属于第三方依赖或其他仓库，标注后跳过，不要硬猜 |