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 结构。每个匹配的接口生成一个独立板块。

### 模板结构

```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)

### 用户输入
> **文件内容**:
> ```typescript
> /**
>  * 更新用户个人资料
>  * @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 | -                      | 用户不存在 (推断) |

#### 💡 关键代码片段

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

## 7. 异常处理 (Error Handling)

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