OpenSkillIndex← back to search
claude-code

Skills ts-interface-miner

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

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/9talk/ts-interface-miner" ~/.claude/skills/clawdbot-skills-ts-interface-miner && rm -rf "$T"
manifest: skills/9talk/ts-interface-miner/SKILL.md
source content

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)

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

💡 关键代码片段

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

7. 异常处理 (Error Handling)

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