openclaw/ts-interface-miner

SKILL: ts-api-miner

1. 技能概述 (Overview)

名称: ts-api-miner 描述: 一个专门用于分析 TypeScript (.ts/.tsx) 文件的智能助手。它能够根据用户提供的关键词（功能描述、函数名、API路径），精准定位相关接口定义。该技能深度解析代码结构与注释（JSDoc/单行注释），提取请求方法、路径、参数细节、响应结构及状态码，最终生成结构清晰、信息完整的Markdown 表格文档。 核心特点:

• 🎯 多维搜索: 支持通过功能描述、函数名称、URL 路径三种方式定位接口。
• 📝 注释优先: 优先提取 JSDoc (@param, @returns, @description) 和行内注释作为字段说明；若注释与类型定义冲突，以注释为准并标记警告。
• 🔗 类型追踪: 自动展开引用的 Interface/Type，递归提取嵌套类型的注释信息。
• 📊 标准化输出: 强制使用 Markdown 表格展示请求参数与响应信息，便于阅读和复制。

2. 触发条件 (Trigger Conditions)

当用户输入满足以下任一场景时，激活此技能：

1. 用户提供了一段 TypeScript 代码片段或文件路径，并要求“查找接口”、“生成文档”或“分析 API"。
2. 用户提供了关键词（如 "登录", getUserInfo, /api/order），要求寻找相关接口详情。
3. 用户询问特定功能的请求参数、响应结构或状态码。

3. 工作流程 (Workflow)

步骤 1: 定位与上下文识别 (Locate & Context)

• 扫描: 在提供的代码上下文中搜索关键词。
  • 匹配 URL 字符串 (e.g., '/api/v1/user')。
  • 匹配函数/常量名 (e.g., fetchUserInfo)。
  • 匹配注释中的功能描述 (e.g., // 获取用户详细信息)。
• 锁定: 确定目标函数体及其调用的 HTTP 客户端方法 (axios, fetch, request 等)。

步骤 2: 深度解析与提取 (Parse & Extract)

• 基础信息: 提取 Method (GET/POST...), Path, Source Location。

• 请求参数提取:

  • Query/Path Params: 从 URL 模板或配置对象中提取。
  • Body: 识别 POST/PUT/PATCH 请求的数据载荷。
  • 类型展开: 如果参数类型是自定义 Interface (如 LoginReq)，深入其定义提取字段列表。

• 注释融合策略 (关键):

  1. 检查函数上方的 JSDoc /** ... */。
  2. 检查参数旁的 @param name - description。
  3. 检查字段定义旁的行内注释 // ...。
  4. 规则: 若 TS 类型为 optional (?) 但注释注明“必填”，则在输出中标记为 ✅ (注释强调) 并添加警告图标 ⚠️。

• 响应信息提取:

  • 分析返回类型的泛型 (e.g., Promise<ApiResponse<T>>)。
  • 提取 @returns 或 @throws 中的状态码和错误描述。
  • 若无显式状态码定义，根据 HTTP 规范推断常见状态 (200, 400, 500) 并结合注释补充说明。

步骤 3: 格式化输出 (Format Output)

• 将提取的数据填入预定义的 Markdown 表格模板。
• 附带关键代码片段以供参考。
• 若存在信息缺失（如无注释），明确标注“暂无文档说明”。

4. 输出规范 (Output Schema)

所有输出必须严格遵循以下 Markdown 结构。每个匹配的接口生成一个独立板块。

模板结构

### 🔍 接口分析：[接口功能简述]

| 属性分类 | 详细信息 |
| :--- | :--- |
| **🏷️ 接口名称** | `[函数名/标识符]` |
| **📝 功能描述** | [来自 JSDoc @description 或首行注释] |
| **🔗 请求路径** | `[完整路径，动态参数用 :id 表示]` |
| **⚡ 请求方法** | `[GET/POST/PUT/DELETE/PATCH]` |
| **📂 源文件位置** | `[文件名]:[行号]` (若已知) |

#### 📥 请求参数 (Request)

| 参数位置 | 字段名 | 类型 | 必填 | 默认值 | 说明 (来自注释) |
| :--- | :--- | :--- | :---: | :---: | :--- |
| [Body/Query/Header/Path] | `[key]` | `[type]` | [✅/❌] | `[value]` | [详细描述，若无则填"暂无说明"] |
| ... | ... | ... | ... | ... | ... |

#### 📤 响应信息 (Response)

| 状态码 | 含义 | 响应体结构摘要 | 说明 (来自注释) |
| :---: | :--- | :--- | :--- |
| **[Code]** | [Text] | `{ key: type, ... }` | [成功/失败的具体描述] |
| ... | ... | ... | ... |

#### 💡 关键代码片段

// [相关代码片段，包含函数定义及关键调用]

5. 处理规则与约束 (Rules & Constraints)

1. 注释权威性:
   • 必须优先展示注释中的业务含义。
   • 如果代码类型是 string 但注释说是 "ISO8601 时间格式"，说明列必须写明 "ISO8601 时间格式"。
2. 类型展开:
   • 禁止直接输出 data: CreateUserDTO 而不解释内容。必须展开 CreateUserDTO 的内部字段到表格中。
   • 对于泛型 (如 List<Item>)，需简要说明 Item 的核心结构。
3. 不确定性处理:
   • 如果无法确定请求方法（代码未显式指定），根据 URL 动词习惯推断，并在方法后标注 (推断)。
   • 如果找不到任何注释，说明列统一填写 ⚪ 暂无文档说明。
4. 冲突标记:
   • 当代码逻辑（如可选参数 ?）与注释描述（如“此项必填”）不一致时，在“必填”列显示 ⚠️ 冲突，并在说明列解释差异。
5. 语言一致性:
   • 输出的文档语言应与用户提问语言或代码注释主要语言保持一致（通常为中文）。

6. 示例 (Examples)

用户输入

文件内容:

/**
 * 更新用户个人资料
 * @param userId - 用户唯一标识，必填
 * @param bio - 个人简介，可选，最大 200 字
 */
export async function updateUserProfile(userId: string, bio?: string) {
  return api.put(`/users/${userId}`, { bio });
}

指令: 分析 updateUserProfile 接口。

技能输出

🔍 接口分析：更新用户个人资料

| 属性分类 | 详细信息 | |:-------------|:--------------------| | 🏷️ 接口名称 | updateUserProfile | | 📝 功能描述 | 更新用户个人资料 | | 🔗 请求路径 | /users/:userId | | ⚡ 请求方法 | PUT | | 📂 源文件位置 | 当前文件 |

📥 请求参数 (Request)

| 参数位置 | 字段名 | 类型 | 必填 | 默认值 | 说明 (来自注释) | |:---------|:---------|:---------|:--:|:-----------:|:-----------------| | Path | userId | string | ✅ | - | 用户唯一标识，必填 | | Body | bio | string | ❌ | undefined | 个人简介，可选，最大 200 字 |

📤 响应信息 (Response)

| 状态码 | 含义 | 响应体结构摘要 | 说明 (来自注释) | |:-------:|:----------|:-----------------------|:-----------| | 200 | OK | { success: boolean } | 更新成功 (推断) | | 404 | Not Found | - | 用户不存在 (推断) |

💡 关键代码片段

/**
 * 更新用户个人资料
 * @param userId - 用户唯一标识，必填
 * @param bio - 个人简介，可选，最大 200 字
 */
export async function updateUserProfile(userId: string, bio?: string) {
    return api.put(`/users/${userId}`, {bio});
}

7. 异常处理 (Error Handling)

• 无匹配结果: 如果未在代码中找到任何与关键词相关的接口，回复：“未在提供的代码中找到与关键词 '[关键词]' 相关的接口定义。请检查关键词拼写或提供更多上下文。”
• 代码不完整: 如果类型定义引用了外部文件但未提供，回复：“检测到类型 [TypeName] 引用自外部文件，无法展开详细结构。仅显示基础类型信息。”