# yapi-skill

**Repository Path**: wufeifei_admin/yapi-skill

## Basic Information

- **Project Name**: yapi-skill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YAPI Skill

查询、创建、更新 YAPI 接口文档，管理 Mock 数据和执行接口测试。

## 安装位置

**用户级安装（全局）**：
```
~/.qoder/skills/yapi-skill/          # Qoder
~/.cursor/skills/yapi-skill/         # Cursor
~/.vscode/extensions/yapi-skill/     # VS Code
```

**项目级安装**：
```
项目根目录/.qoder/skills/yapi-skill/          # Qoder
项目根目录/.cursor/skills/yapi-skill/         # Cursor
项目根目录/.vscode/extensions/yapi-skill/     # VS Code
```

## 依赖

```bash
# 基础依赖（必需）
pip install requests

# BM25 快速搜索功能（可选，推荐）
pip install llama-index-core
```

**兼容性说明**：
- ✅ **不安装 llama-index-core**：使用传统API方式查询（较慢但可用）
- ✅ **安装 llama-index-core**：启用BM25快速搜索（推荐）

## 环境变量配置

### 环境变量读取优先级

1. **项目根目录的 `.env` 文件**（强烈推荐）
   - ⚠️ **只读**：如果文件不存在，**不要创建或修改它**

2. **系统环境变量**

3. **读不到就报错**

### ⚠️ 重要规则

- ❌ **禁止创建或修改 `.env` 文件**
- ✅ 只读取已存在的 `.env` 文件

#### 方式 A：系统环境变量

```bash
# YAPI Configuration
export YAPI_URL=http://mapi.code.mob.com
export YAPI_EMAIL=<your_email>
export YAPI_PASSWORD=<your_password>
```

⚠️ **重要提示**：
- 敏感字段（Token等）**不要**在调用 Skill 的 `params` 中传入
- 因为明文会显示在日志和输出中，不安全
- 必须在调用前设置环境变量，Skill 会自动从环境变量读取

#### 方式 B：项目级 .env

```bash
# 项目根目录/.env
YAPI_URL=http://mapi.code.mob.com
YAPI_EMAIL=<your_email>
YAPI_PASSWORD=<your_password>
```

#### 环境变量说明

| 变量名 | 必填 | 说明 | 示例值 |
|--------|------|------|--------|
| `YAPI_URL` | ✅ | YAPI 服务器地址 | `http://mapi.code.mob.com` |
| `YAPI_EMAIL` | ✅ | YAPI 账号邮箱 | `<your_email>` |
| `YAPI_PASSWORD` | ✅ | YAPI 密码 | `<your_password>` |
| `YAPI_SKILL_GLOBAL_CONFIG` | ❌ | 全局配置文件路径 | `~/.qoder/skills/yapi-skill/config/project.json` |
| `YAPI_SKILL_PROJECT_CONFIG` | ❌ | 项目配置文件路径 | `项目/.qoder/skills/yapi-skill/config/project.json` |

#### 参数获取规则

**优先级顺序**：
1. 优先从**当前对话**获取参数值
2. 其次从**配置文件** (project.json) 读取参数定义和默认值
3. **禁止使用历史记忆**中的参数值

**重要规则**：

1. ❌ **禁止传入配置中不存在的参数**

2. ✅ **必填参数必须从对话获取**
   - 只能从当前对话中获取，不能使用默认值
   - ⚠️ **如果必填参数未提供，Skill 会报错并终止任务**

3. ✅ **非必填参数可以使用默认值**

## 功能列表

| 功能 | 说明 |
|------|------|
| `list_groups` | 获取所有项目分组列表 |
| `list_projects` | 列出所有项目（支持按分组过滤） |
| `get_project` | 获取项目详情（包含分类信息） |
| `list_categories` | 获取接口分类列表 |
| `list_interfaces` | 获取接口列表 |
| `get_interface` | 获取接口详情（包含完整的请求/响应参数） |
| `create_interface` | 创建新接口 |
| `update_interface` | 更新接口 |
| `delete_interface` | 删除接口 |
| `test_interface` | 测试接口（调用真实接口） |
| `test_mock` | Mock 测试接口（调用 YAPI Mock 服务） |
| `get_mock_data` | 获取 Mock 数据 |
| `create_category` | 创建接口分类 |
| `get_project_stats` | 获取项目统计信息 |
| `export_interfaces` | 导出接口列表（Markdown 格式） |
| **BM25 快速搜索** |  |
| `search_interface_smart` | **智能搜索**（推荐，自动选择最优方式） |
| `build_bm25_index` | 构建BM25检索索引（首次使用或YAPI更新后） |
| `search_interface_bm25` | BM25关键词搜索接口（快速检索） |
| `navigate_interface` | 分层导航：项目 → 分类 → 接口 |
| `refresh_bm25_index` | 刷新BM25索引 |
| `get_index_status` | 获取索引状态 |
| `clear_bm25_index` | 清理BM25索引 |

## 使用示例

### 列出所有项目

```python
import os
import sys

os.environ['YAPI_URL'] = 'http://yapi.example.com'
os.environ['YAPI_TOKEN'] = '<your_token>'
os.environ['YAPI_SKILL_GLOBAL_CONFIG'] = '<user_home>/.qoder/skills/yapi-skill/config/project.json'

sys.path.insert(0, '<user_home>/.qoder/skills/yapi-skill/scripts')
import main

result = main.list_projects({})
```

### 获取接口列表

```python
result = main.list_interfaces({
    "project_id": 123,
    "category_id": 456
})
```

### 创建新接口

```python
result = main.create_interface({
    "project_id": 123,
    "title": "获取用户信息",
    "path": "/api/user",
    "method": "GET",
    "desc": "根据用户ID获取用户信息"
})
```

### 获取接口详情

```python
result = main.get_interface({
    "interface_id": 789
})
```

### 更新接口

```python
result = main.update_interface({
    "interface_id": 789,
    "desc": "更新后的接口描述"
})
```

### 获取 Mock 数据

```python
result = main.get_mock_data({
    "project_id": 123,
    "path": "/api/user",
    "method": "GET"
})
```

## BM25 快速搜索

### 0. 智能搜索（推荐）

**自动选择最优查询方式**，无需手动管理索引：

```python
# 场景1：关键词搜索
result = main.search_interface_smart({
    "keyword": "收件人"
})
# 自动：检查索引 → 构建（如果需要） → BM25搜索

# 场景2：查看分类
result = main.search_interface_smart({
    "project_name": "SDK-PushSDK",
    "category_name": "周报"
})
# 自动：使用分层导航

# 场景3：分类中搜索
result = main.search_interface_smart({
    "project_name": "SDK-PushSDK",
    "category_name": "周报",
    "keyword": "收件人"
})
# 自动：BM25搜索 + 过滤
```

**优势**：
- ✅ 自动构建索引（首次使用）
- ✅ 自动选择最优查询方式
- ✅ 友好的提示信息
- ✅ 零学习成本
- ✅ **向后兼容**：未安装llama-index-core时自动降级到传统API

---

### 1. 构建索引（首次使用）

```python
# 构建BM25索引（会遍历所有项目、分类、接口）
result = main.build_bm25_index({})
# 输出：✅ BM25索引构建完成！接口数: 1234
```

### 2. 关键词搜索

```python
# 全局搜索接口
result = main.search_interface_bm25({
    "keyword": "收件人"
})

# 限定项目搜索
result = main.search_interface_bm25({
    "keyword": "收件人",
    "project_name": "SDK-PushSDK"
})

# 限定项目和分类
result = main.search_interface_bm25({
    "keyword": "黑名单",
    "project_name": "SDK-PushSDK",
    "category_name": "周报"
})
```

### 3. 分层导航

```python
# 查看项目的所有分类
result = main.navigate_interface({
    "project_name": "SDK-PushSDK"
})

# 查看分类下的所有接口
result = main.navigate_interface({
    "project_name": "SDK-PushSDK",
    "category_name": "周报"
})

# 在分类中搜索接口
result = main.navigate_interface({
    "project_name": "SDK-PushSDK",
    "category_name": "周报",
    "keyword": "收件人"
})
```

### 4. 索引管理

```python
# 查看索引状态
result = main.get_index_status({})
# 输出：{"status": "available", "age_hours": 2.5, ...}

# 刷新索引（YAPI更新后）
result = main.refresh_bm25_index({})

# 清理索引
result = main.clear_bm25_index({})
```

### 索引说明

- **索引位置**：`<skill_root>/cache/bm25_index/`
- **有效期**：24小时（过期后自动提示刷新）
- **搜索限制**：最多返回100个最相关的结果
- **依赖**：`pip install llama-index-core`（BM25不需要向量模型）