@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

package/plugins/api/skills/api-field-mapper/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: api-field-mapper
+description: API 字段映射助手。编辑前端 TypeScript/Vue 文件时自动关联 Swagger 接口定义，提示字段映射关系。
+metadata:
+  filePattern:
+    - "src/**/*.ts"
+    - "src/**/*.tsx"
+    - "src/**/*.vue"
+  bashPattern: []
+  priority: 30
+---
+
+# API 字段映射助手
+
+当编辑前端文件时，自动检测是否涉及 API 调用，并关联 Swagger 接口定义提供字段映射辅助。
+
+## 触发条件
+
+编辑以下类型文件时触发：
+- `src/**/*.ts` — TypeScript 文件
+- `src/**/*.tsx` — React 组件
+- `src/**/*.vue` — Vue 组件
+
+## 工作流程
+
+### 1. 检测 API 调用
+
+读取当前编辑的文件，检测是否包含 API 调用特征：
+
+```
+检测模式：
+- import ... from '@/api/...'
+- import ... from '@/services/...'
+- request.get/post/put/delete(...)
+- axios.get/post/put/delete(...)
+- fetch('/api/...')
+- useSWR('/api/...')
+- useQuery(...'/api/...')
+```
+
+### 2. 提取接口路径
+
+从检测到的 API 调用中提取路径：
+
+```typescript
+// 能识别的模式
+request.get<UserDetail>('/api/v1/users/' + id)  → GET /api/v1/users/{id}
+request.post('/api/v1/users', data)             → POST /api/v1/users
+fetch(`/api/v1/orders/${orderId}`)              → GET /api/v1/orders/{id}
+```
+
+### 3. 关联 Swagger 定义
+
+如果项目配置了 `.api-config.json`：
+
+1. 调用 Python 脚本查询匹配的接口定义
+2. 对比代码中使用的字段名与 Swagger 定义
+3. 提示可能的问题
+
+### 4. 辅助提示
+
+当检测到以下情况时主动提示：
+
+**字段名不匹配：**
+```
+💡 API 字段映射提示
+
+文件中使用了 `username`，但接口 GET /api/v1/users/{id} 返回的是 `user_name`
+建议使用映射后的字段名 `userName`（camelCase）
+
+使用 /api:map GET /api/v1/users/{id} 查看完整映射
+```
+
+**缺少类型定义：**
+```
+💡 检测到 API 调用但未找到类型定义
+
+接口：POST /api/v1/users
+建议：/api:gen POST /api/v1/users 生成类型和请求函数
+```
+
+**字段过期（Swagger 中已删除）：**
+```
+⚠️ 字段可能已过期
+
+代码中使用了 `user.nickName`，但当前 Swagger 定义中未找到该字段
+请确认接口是否已更新：/api:map GET /api/v1/users/{id}
+```
+
+## 非侵入原则
+
+- 仅在检测到明确的 API 调用时触发
+- 不自动修改代码，只提供建议
+- `.api-config.json` 不存在时静默跳过
+- 不阻塞正常编辑操作

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

@@ -0,0 +1,140 @@
+---
+name: config
+description: |
+  API 配置管理 - 初始化和管理 Swagger 数据源配置
+---
+
+# API 配置管理
+
+管理 `.api-config.json` 配置文件，包括初始化、添加/删除数据源、查看配置。
+
+## 命令格式
+
+```
+/api:config [子命令] [参数]
+```
+
+## 子命令
+
+| 子命令 | 说明 | 示例 |
+|-------|------|------|
+| `init` | 初始化配置文件 | `/api:config init` |
+| (空) | 查看当前配置 | `/api:config` |
+| `add` | 添加 Swagger 数据源 | `/api:config add` |
+| `remove` | 删除数据源 | `/api:config remove 主服务` |
+
+## 执行流程
+
+### /api:config init
+
+1. 检查项目根目录是否已存在 `.api-config.json`
+   - **已存在** → 显示当前配置，询问是否重新初始化
+   - **不存在** → 继续初始化
+
+2. 交互式引导收集信息：
+   - **Swagger 地址**：询问用户后端 Swagger 文档的 URL 或本地文件路径
+   - **服务名称**：给数据源命名（如「主服务」「支付服务」）
+   - **API 前缀**：可选，如 `/api/v1`
+
+3. 自动检测项目结构确定 codegen 配置：
+   - 检查 `src/api/` 或 `src/services/` 是否存在 → 设为 `outputDir`
+   - 检查 `src/types/` 是否存在 → 设为 `typeDir`
+   - 都不存在 → 使用默认值
+
+4. 生成 `.api-config.json` 写入项目根目录
+
+5. 创建 `docs/api/` 文档骨架，仅当文件不存在时创建：
+
+   | 文件 | 用途 |
+   |------|------|
+   | `field-conventions.md` | 字段命名约定（驼峰/蛇形、分页格式等） |
+   | `error-codes.md` | 业务错误码清单 |
+   | `auth-pattern.md` | 鉴权方式说明 |
+
+   每个文件使用统一的 5 节骨架，节内容留空，在对接接口时与 AI 协作填写。`/api:gen` 生成代码时会自动读取这些文件保持一致性：
+
+   ```markdown
+   # <文档标题>
+
+   > <一行用途说明>
+
+   ## 什么时候用
+
+   <!-- 适用场景 + 不适合的情况 -->
+
+   ## 必备输入
+
+   <!-- 生成/校验前需要确认的前置信息 -->
+
+   ## 触发方式
+
+   <!-- 如何在 prompt 中引用本文档，或写入 CLAUDE.md 的推荐做法 -->
+
+   ## 优质输出标准
+
+   <!-- 符合约定的输出长什么样 -->
+
+   ## 常见失败模式
+
+   | 问题 | 原因 | 解决方案 |
+   |------|------|----------|
+   ```
+
+6. 提示用户将 `.api-config.json` 加入版本控制
+
+### /api:config（查看配置）
+
+读取并展示 `.api-config.json` 内容：
+
+```
+API 配置
+
+数据源：
+  1. 主服务 — http://localhost:8080/swagger/doc.json [/api/v1]
+  2. 支付服务 — ./docs/payment-swagger.json [/pay/v1]
+
+代码生成：
+  请求函数目录：src/api
+  类型定义目录：src/types/api
+  字段命名风格：camelCase
+
+请求库检测：axios (来自 package.json)
+封装文件：src/utils/request.ts
+```
+
+### /api:config add
+
+交互式添加新的 Swagger 数据源：
+
+1. 询问数据源类型（URL / 本地文件）
+2. 收集地址/路径和服务名称
+3. 可选：API 前缀
+4. 验证连通性（URL 类型尝试请求，文件类型检查是否存在）
+5. 追加到 `.api-config.json` 的 `swagger.sources` 数组
+
+### /api:config remove <服务名>
+
+1. 在 `swagger.sources` 中查找匹配的 `name`
+2. 找到 → 展示即将删除的数据源信息，确认后删除
+3. 未找到 → 列出所有可用数据源名称
+
+## 配置文件模板
+
+```json
+{
+  "swagger": {
+    "sources": [
+      {
+        "name": "主服务",
+        "url": "http://localhost:8080/swagger/doc.json",
+        "prefix": "/api/v1"
+      }
+    ]
+  },
+  "codegen": {
+    "outputDir": "src/api",
+    "typeDir": "src/types/api",
+    "fieldCase": "camelCase"
+  }
+}
+```

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

@@ -0,0 +1,345 @@
+---
+name: gen
+description: |
+  代码生成 - 根据接口定义生成 TypeScript 类型和请求函数
+---
+
+# 代码生成
+
+根据 Swagger 接口定义，自动生成 TypeScript 类型定义和请求函数代码。
+
+## 命令格式
+
+```
+/api:gen <METHOD> <path> [--name=服务名] [--type-only] [--request-only] [--tag=分组名]
+```
+
+## 参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `METHOD` | 是 | HTTP 方法，或 `*` 表示该路径所有方法 |
+| `path` | 是 | API 路径 |
+| `--name` | 否 | 指定数据源 |
+| `--type-only` | 否 | 仅生成类型定义 |
+| `--request-only` | 否 | 仅生成请求函数 |
+| `--tag` | 否 | 按 Tag 批量生成该分组下所有接口 |
+
+## 执行流程
+
+### 前置检查
+
+1. 参考 `_common.md` 的「命令执行前置检查」
+2. 执行请求库自动检测（参考 `_common.md`「请求库自动检测」）
+3. 读取 `codegen.outputDir` 和 `codegen.typeDir`
+
+### 生成流程
+
+1. **解析接口定义**
+
+   调用 `swagger-parser.py`（`mode=detail`，传入接口路径），获取接口完整 schema。
+
+2. **检测请求库**
+
+   按 `_common.md`「请求库自动检测」规则检测，确定代码风格。
+
+3. **生成类型定义文件**
+
+   目标路径：`{typeDir}/{模块名}.ts`
+
+   模块名从 API 路径推断：
+   - `/api/v1/users/{id}` → `user.ts`
+   - `/api/v1/orders/{id}/items` → `order.ts`
+   - 同一资源的接口类型合并到同一文件
+
+   **文件已存在时**：
+   - 读取现有文件，检查是否已有同名 interface
+   - 未有 → 追加到文件末尾
+   - 已有 → 进入**字段变更分析**（见步骤 3.1）
+
+#### 3.1 字段变更分析（已有同名 interface 时）
+
+将 Swagger 最新 schema 与项目中已有的 interface 逐字段比对：
+
+```
+检测到已有类型：UserDetailResponse
+
+  字段变更：
+
+  | 字段 | 变化 | 旧定义 | 新定义 |
+  |------|------|--------|--------|
+  | nickName | 新增 | — | string |
+  | avatarUrl | 类型变更 | string | string \| null |
+  | roleList[].permissions | 新增 | — | string[] |
+  | phone | 删除 | string | — |
+
+  无变化字段：id, userName, email, createdAt, isActive（省略）
+```
+
+**无字段变化时**：提示"类型定义无变化，跳过更新"，继续步骤 4。
+
+**有字段变化时**：更新类型定义，并进入步骤 3.2 扫描关联页面。
+
+#### 3.2 关联页面影响分析
+
+AI 在项目中搜索引用了该类型或该请求函数的文件，识别受影响的页面组件：
+
+在项目中搜索引用了该类型和请求函数的文件（`.ts`、`.tsx`、`.vue`）。对每个引用文件，AI 读取代码判断其用途：
+
+| 用途 | 判断依据 | 影响 |
+|------|---------|------|
+| 表单页 | 包含 `<Form>`、`<Input>`、`onSubmit`、`formData` 等 | 新增字段需要加表单项，删除字段需要移除 |
+| 列表/表格页 | 包含 `<Table>`、`columns`、`<List>` 等 | 新增字段可能需要加列，删除字段需要移除列 |
+| 详情页 | 包含只读展示（`<Descriptions>`、`detail.xxx`） | 新增字段可能需要展示，删除字段需要移除 |
+| 其他 | 仅 import 类型用于逻辑处理 | 需检查是否访问了已删除字段 |
+
+输出影响分析报告：
+
+```
+关联页面影响分析：
+
+  变更字段：+2 新增, 1 类型变更, 1 删除
+
+  受影响文件（4个）：
+
+  src/pages/user/UserForm.tsx（表单）
+     - nickName（新增）→ 建议添加表单项
+     - phone（删除）→ 需移除表单项和校验规则
+
+  src/pages/user/UserList.tsx（列表）
+     - nickName（新增）→ 可选：添加表格列
+     - phone（删除）→ 需移除表格列定义
+
+  src/pages/user/UserDetail.tsx（详情）
+     - nickName（新增）→ 建议添加展示项
+     - avatarUrl（类型变更）→ 需处理 null 值
+     - phone（删除）→ 需移除展示项
+
+  src/hooks/useUserPermission.ts（逻辑）
+     - roleList[].permissions（新增）→ 无需改动（新字段）
+
+是否自动生成调整方案？
+```
+
+#### 3.3 生成调整方案（用户确认后）
+
+用户确认后，AI 对每个受影响文件给出具体的修改方案：
+
+```
+调整方案：
+
+1/3 src/pages/user/UserForm.tsx 
+
+  + 添加 nickName 表单项（在 email 字段后）：
+    <Form.Item label="昵称" name="nickName">
+      <Input placeholder="请输入昵称" />
+    </Form.Item>
+
+  - 移除 phone 表单项和校验规则
+
+2/3 src/pages/user/UserList.tsx 
+
+  - 移除 phone 列定义
+  (nickName 为列表非关键字段，建议暂不添加)
+
+3/3 src/pages/user/UserDetail.tsx 
+
+  + 添加 nickName 展示项
+  ~ avatarUrl 添加空值处理：{detail.avatarUrl ?? '—'}
+  - 移除 phone 展示项
+
+是否执行调整？（可选择部分文件执行）
+```
+
+用户可以：
+- 全部执行 → AI 依次修改所有文件
+- 选择部分执行 → 指定文件编号
+- 仅更新类型 → 跳过页面调整，只更新 interface
+
+4. **生成请求函数文件**
+
+   目标路径：`{outputDir}/{模块名}.ts`
+
+   同样合并同一资源到同一文件。
+   **请求函数已存在时**：检查参数和返回类型是否变更，有变更则更新。
+
+5. **展示生成结果**
+
+### 输出格式
+
+```
+代码生成：GET /api/v1/users/{id}
+
+检测请求库：axios（封装文件：src/utils/request.ts）
+
+生成文件 
+
+1. src/types/api/user.ts（类型定义）
+2. src/api/user.ts（请求函数）
+
+预览 
+
+// src/types/api/user.ts
+
+/** 用户详情 - 响应类型 */
+export interface UserDetailResponse {
+  id: number;
+  userName: string;
+  avatarUrl?: string;
+  email: string;
+  createdAt: string;
+  isActive?: boolean;
+  roleList?: {
+    roleId: number;
+    roleName: string;
+  }[];
+}
+
+// src/api/user.ts
+
+import request from '@/utils/request';
+import type { UserDetailResponse } from '@/types/api/user';
+
+/** 获取用户详情 */
+export function getUserDetail(id: number) {
+  return request.get<UserDetailResponse>(`/api/v1/users/${id}`);
+}
+```
+
+确认后写入文件。
+
+### 不同请求库的生成风格
+
+#### 自定义封装（检测到 src/utils/request.ts 等）
+
+```typescript
+import request from '@/utils/request';
+
+/** 获取用户列表 */
+export function getUserList(params?: UserListParams) {
+  return request.get<UserListResponse>('/api/v1/users', { params });
+}
+
+/** 创建用户 */
+export function createUser(data: CreateUserParams) {
+  return request.post<CreateUserResponse>('/api/v1/users', data);
+}
+```
+
+#### axios（package.json 中有 axios）
+
+```typescript
+import axios from 'axios';
+
+/** 获取用户列表 */
+export function getUserList(params?: UserListParams) {
+  return axios.get<UserListResponse>('/api/v1/users', { params });
+}
+```
+
+#### umi-request
+
+```typescript
+import { request } from 'umi';
+
+/** 获取用户列表 */
+export function getUserList(params?: UserListParams) {
+  return request<UserListResponse>('/api/v1/users', { method: 'GET', params });
+}
+```
+
+#### 原生 fetch
+
+```typescript
+/** 获取用户列表 */
+export async function getUserList(params?: UserListParams): Promise<UserListResponse> {
+  const query = params ? '?' + new URLSearchParams(params as any).toString() : '';
+  const res = await fetch(`/api/v1/users${query}`);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+```
+
+#### @tanstack/react-query
+
+```typescript
+import { useQuery, useMutation } from '@tanstack/react-query';
+
+/** 获取用户详情 */
+export function useUserDetail(id: number) {
+  return useQuery({
+    queryKey: ['user', id],
+    queryFn: async () => {
+      const res = await fetch(`/api/v1/users/${id}`);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json() as Promise<UserDetailResponse>;
+    },
+  });
+}
+
+/** 创建用户 */
+export function useCreateUser() {
+  return useMutation({
+    mutationFn: async (data: CreateUserParams) => {
+      const res = await fetch('/api/v1/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json() as Promise<CreateUserResponse>;
+    },
+  });
+}
+```
+
+#### swr
+
+```typescript
+import useSWR from 'swr';
+
+const fetcher = (url: string) => fetch(url).then(res => res.json());
+
+/** 获取用户详情 */
+export function useUserDetail(id: number) {
+  return useSWR<UserDetailResponse>(`/api/v1/users/${id}`, fetcher);
+}
+```
+
+### 批量生成
+
+#### 按 Tag 批量生成
+
+```
+/api:gen --tag=用户管理
+
+→ 生成该 Tag 下所有接口的类型和请求函数
+→ 合并到同一个模块文件
+```
+
+#### 按路径通配
+
+```
+/api:gen * /api/v1/users
+/api:gen * /api/v1/users/{id}
+
+→ 生成该路径下所有 HTTP 方法的代码
+```
+
+### 文件合并策略
+
+同一模块（如 user）的多个接口生成到同一文件：
+
+```
+/api:gen * /api/v1/users
+/api:gen * /api/v1/users/{id}
+
+→ src/types/api/user.ts   包含 UserListResponse, UserDetailResponse, CreateUserParams 等
+→ src/api/user.ts          包含 getUserList, getUserDetail, createUser 等
+```
+
+**合并规则：**
+- 同名 interface 已存在 → 覆盖（确认后）
+- 同名函数已存在 → 覆盖（确认后）
+- 新增的 → 追加到文件末尾
+- import 语句自动去重

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

@@ -0,0 +1,121 @@
+---
+name: help
+description: |
+  使用教程 - 查看 API 对接插件完整使用指南
+---
+
+# API 对接插件 - 使用教程
+
+展示 API 对接插件的使用指南，支持中文 / 英文 / 韩文三语。
+
+## 执行流程
+
+### 1. 决定语言
+
+按以下优先级：
+
+1. 命令参数 `--lang=zh|en|ko`（显式覆盖）
+2. `.claude/settings.local.json` 的 `language` 字段
+3. 默认 `zh`
+
+### 2. 读取教程文件
+
+按语言选择教程文件（相对于插件目录）：
+
+| lang | 文件路径 |
+|------|---------|
+| `zh`（默认） | `<plugin-path>/docs/tutorial.zh.md` |
+| `en` | `<plugin-path>/docs/tutorial.en.md` |
+| `ko` | `<plugin-path>/docs/tutorial.ko.md` |
+
+### 3. 决定输出范围
+
+- 无章节参数 → 输出章节索引
+- 有章节参数 → 按章节名或编号模糊匹配，仅输出对应章节
+
+## 章节索引
+
+无参数时展示对应语言的章节索引。
+
+### 中文（zh）
+
+```
+API 对接插件 - 使用教程
+
+章节：
+ 1. 快速开始
+ 2. 配置管理
+ 3. 导入 Swagger
+ 4. 搜索接口
+ 5. 字段映射
+ 6. 代码生成
+ 7. 自动检测
+ 8. 常见问题
+
+输入章节编号查看详情。
+```
+
+### English (en)
+
+```
+API Plugin — Tutorial
+
+Sections:
+ 1. Quick start
+ 2. Configuration
+ 3. Import Swagger
+ 4. Search endpoints
+ 5. Field mapping
+ 6. Code generation
+ 7. Auto-detection
+ 8. FAQ
+
+Enter a section number to view details.
+```
+
+### 한국어 (ko)
+
+```
+API 플러그인 - 튜토리얼
+
+섹션:
+ 1. 빠른 시작
+ 2. 설정 관리
+ 3. Swagger 임포트
+ 4. 엔드포인트 검색
+ 5. 필드 매핑
+ 6. 코드 생성
+ 7. 자동 감지
+ 8. FAQ
+
+섹션 번호를 입력하여 상세 조회.
+```
+
+## 命令格式
+
+```
+/api:help [章节名或编号] [--lang=zh|en|ko]
+```
+
+示例：
+- `/api:help` → 中文章节索引（或 settings.local.json 中设定的语言）
+- `/api:help --lang=en` → English section index
+- `/api:help 5` → 第 5 章「字段映射」
+- `/api:help 5 --lang=ko` → 섹션 5 "필드 매핑"
+- `/api:help search --lang=en` → English match on "Search endpoints"
+
+## 持久化语言偏好
+
+在 `.claude/settings.local.json` 中设置：
+
+```json
+{
+  "language": "en"
+}
+```
+
+后续 `/req:help`、`/api:help`、`/pm:help` 都会默认用该语言。
+
+## 用户输入
+
+$ARGUMENTS