# API Skill

[English](https://unpkg.com/apiskill@latest/README.md) / [中文](https://unpkg.com/apiskill@latest/README.zh.md) / [한국어](https://unpkg.com/apiskill@latest/README.ko.md) / [日本語](https://unpkg.com/apiskill@latest/README.ja.md)

API Skill 是一个本地 OpenAPI/Swagger 工作区，面向前端开发和 AI 辅助编码。它提供一个面向人的工作台和两个面向 AI Agent 的接口，并共享同一份本地缓存接口文档：

- Web 端，主要给人使用：导入、浏览、搜索、查看、测试、版本管理和手动维护接口。
- CLI，主要给 AI Agent 和自动化任务使用：检查文档状态、按需获取接口上下文、维护文档并启动本地服务。
- MCP 服务，主要给 AI Agent 使用：把同一套查询和维护能力直接暴露给 Codex 或其他 MCP 客户端。

## Web 端使用

从 npm 安装后，可以在任意项目目录启动 Web 端：

```bash
npm install -g apiskill
apiskill run web
```

Web、CLI 和 MCP 默认统一使用用户可写的 `~/.apiskill/cache`，共同读写同一份文档和版本。`--cwd` 只改变 Web 进程的工作目录，不再改变共享缓存。需要隔离缓存时，必须为 Web、CLI 和 MCP 设置完全相同的绝对路径 `APISKILL_CACHE_DIR`。开发本仓库时也可以在项目根目录启动：

```bash
npm install
npm run dev
```

打开终端输出的本地地址。“新建文档”弹窗可以导入直接的 OpenAPI JSON/YAML 地址，爬取 Swagger UI / Knife4j / Redoc 页面，上传本地文件，执行返回 OpenAPI 文档的 curl 命令，也可以从零新建空白文档。

页面右上角的“缓存设置”可以查看当前会话缓存位置并修改默认缓存地址。设置保存在 `~/.apiskill/config.json`，不会移动或删除已有缓存文件；Web 重启以及后续 CLI、MCP 进程会使用新地址。版本管理中的“更新缓存地址”可以在确认源地址和目标地址后，将指定版本复制到新的默认缓存目录。

CLI 使用同一份设置：

```bash
apiskill cache show
apiskill cache set /absolute/path/to/apiskill-cache
apiskill cache reset
```

`APISKILL_CACHE_DIR` 仍具有最高优先级，适合临时或自动化隔离，不会覆盖已保存的默认设置。

导入或新建文档后，可以用版本选择器切换缓存文档，按路径、摘要、tag、method 或参数文本搜索接口，并打开接口 tab 查看请求参数、请求体、响应字段、AI 友好的上下文和原始 JSON。也可以新增、编辑、删除手动接口；这些改动会保存为本地缓存版本。

已有 API 文档数据后，可以在 Web 端点击“启动MOCK服务”，或在 CLI 里运行 `apiskill mock`，根据当前接口定义启动本地随机数据 MOCK API 服务。

### AI Agent 快速使用

```bash
# 1. 检查 API 文档是否可用
apiskill check

# 2. 没有文档时初始化缓存
apiskill import https://example.com/openapi.json
apiskill crawl https://example.com/swagger
apiskill import-file ./openapi.yaml
apiskill document create --title "My API" --doc-version 1.0.0

# 3. 只获取当前开发任务需要的接口上下文
apiskill versions
apiskill query /api/v1/users --method GET

# 4. 根据当前文档启动本地随机数据接口
apiskill mock
```

CLI 和 MCP 主要面向 AI 编码 Agent。Agent 应先检查缓存，只在缺少文档时初始化，然后按当前任务精确查询接口，避免每次读取整份 OpenAPI 文档。运行 `apiskill --help` 可以查看全部 CLI 命令；在 MCP 客户端中先调用 `apiskill_check`，再使用 `apiskill_search_endpoints` 或 `apiskill_query_api` 定位接口，调用 `apiskill_help` 可查看完整工具列表。

### AI Agent CLI 增删改查协议

支持 `--json` 的命令应优先使用 JSON 输出并解析字段，不要抓取人类可读文本。需要按项目隔离缓存时，每次调用前将 `APISKILL_CACHE_DIR` 设置为绝对可写目录；未设置时，全局安装默认使用 `~/.apiskill/cache`。

1. 检查缓存；没有上游文档时创建空白文档：

```bash
apiskill check --json
apiskill document create --title "My API" --doc-version 1.0.0 --description "Local API contract" --json
```

从创建结果读取 `meta.versionId`，后续所有写操作都复用这个精确值。现在 `api create` 省略 `--version` 时会默认写入最新版本，但 Agent 仍应显式传入，确保每次都写入目标项目文档。

2. 将接口配置保存为 `api-config.json`：

```json
{
  "api": {
    "method": "post",
    "path": "/api/v1/users/{id}",
    "summary": "创建用户",
    "operationId": "createUser",
    "tags": ["Users"],
    "parameters": [
      { "name": "id", "location": "path", "required": true, "type": "string" }
    ],
    "requestBody": {
      "required": true,
      "contentType": "application/json",
      "fields": [
        { "name": "name", "type": "string", "required": true },
        { "name": "email", "type": "string", "format": "email" }
      ]
    },
    "responses": [
      {
        "status": "200",
        "description": "用户创建成功",
        "contentType": "application/json",
        "fields": [
          { "name": "success", "type": "boolean", "required": true },
          { "name": "userId", "type": "string" }
        ]
      }
    ]
  }
}
```

3. 新增、读取、修改并删除接口：

```bash
APISKILL_VERSION_ID="value-from-meta.versionId"

apiskill api create --version "$APISKILL_VERSION_ID" --file ./api-config.json --json
apiskill api list --version "$APISKILL_VERSION_ID" --query user --method POST --json
apiskill api query POST '/api/v1/users/{id}' --version "$APISKILL_VERSION_ID" --format cli

# 修改返回的 CLI 配置并保存为 api-config.updated.json。
# 下面的 POST 和路径用于定位旧接口，文件中保存替换后的新配置。
apiskill api edit POST '/api/v1/users/{id}' --version "$APISKILL_VERSION_ID" --file ./api-config.updated.json --json

# 如果修改时改变了 method 或 path，删除时使用替换后的值。
apiskill api delete PATCH '/api/v1/users/{id}' --version "$APISKILL_VERSION_ID" --json
```

批量写入多个接口时，每条命令都必须使用同一个 `APISKILL_VERSION_ID`。为了兼容旧版 CLI，Agent 应等待上一条写命令完成后再执行下一条，最后检查完整接口列表：

```bash
apiskill api create --version "$APISKILL_VERSION_ID" --file ./users.get.json --json
apiskill api create --version "$APISKILL_VERSION_ID" --file ./users.create.json --json
apiskill api create --version "$APISKILL_VERSION_ID" --file ./users.delete.json --json
apiskill api list --version "$APISKILL_VERSION_ID" --json
```

当前版本还会在多个进程之间串行化同一缓存目录的写操作，因此 AI 工具即使意外并行执行这些命令，也不会再丢失先写入的接口。

Agent 执行规则：

- `api query` 默认输出 JSON，不支持 `--json`；需要可修改并回写的标准配置时使用 `--format cli`。
- `api edit ORIGINAL_METHOD ORIGINAL_PATH` 的前两个参数定位旧接口，新配置可以改变 method 或 path。
- 包含 `{id}` 等 shell 特殊字符的路径必须加引号。
- `api list --query` 搜索接口元数据和参数，不搜索响应字段名。已知 method 和 path 时使用精确的 `api query METHOD PATH`。
- 空白文档没有任何 path 时，`check --json` 会返回 `ok: false`，直到至少添加一个 API。文档并未丢失，可检查 `versionsCount` 和 `latestVersion`。
- 接口不存在或命令参数无效时，进程返回非零退出码。Agent 应视为失败并读取 stderr。
- `--config '<json-or-yaml>'` 与 `--file` 等效；复杂或嵌套配置优先使用文件，避免 shell 转义错误。
- 批量写入结束后，执行 `api list --version ... --json`，逐一核对预期的 method/path 均存在，再报告任务成功。
- OpenAPI 使用 method/path 组合唯一标识接口；再次创建相同组合会按预期替换原接口。`meta.paths` 统计的是不同路径数，不是接口操作总数。

## 为什么开发这个工具

自从 AI 大模型面世这几年，开发人员使用 AI 写代码的方式一直在变化。最开始，很多人是在 ChatGPT 网页端来回复制粘贴代码、报错和接口文档；后来 Cursor、Codex、Claude Code 这类可以集成整个项目的桌面端或本地开发工具出现，AI 辅助开发逐渐从单次问答变成了围绕整个项目上下文协作。

接口文档的使用方式也在变化。最早通常是直接复制粘贴接口文档，或者把接口文档截图发给 AI；后来有了 Context7 这类工具，可以让 AI 助手直接读取网页端 API 文档。这已经方便了很多，但实际开发里仍然有几个问题：

- AI 解析网页文档会消耗额外 token，文档越大浪费越明显，也会带来更多等待时间。
- 有些内部文档需要登录、cookie、访问密钥或内网环境，AI 工具读取前还要额外处理访问权限问题。
- 即使 AI 能读取到文档，当需要新增、编辑、修正文档时，它通常也没有直接维护接口文档和版本的能力。

因此才有了开发 API Skill 的想法。它把接口文档导入、爬取、从零创建、查询、编辑和多版本管理都放到本地，并通过 Web、CLI、MCP 暴露同一份结构化契约。目标是让接口文档变成 AI 助手可以稳定调用和持续维护的项目级工具，而不是一大段反复粘贴的文本或截图。

### Token 节省评估

实际节省比例取决于文档大小、schema 层级深度和任务本身需要多少上下文，但工程上的趋势比较稳定：

| 方式 | 通常发送给模型的上下文 | 复用性 | 预期 token 影响 |
| --- | --- | --- | --- |
| 文档截图 | 图片 token，加上整页可视内容解析 | 低 | 成本高，也不利于精确引用字段 |
| 复制文档文本 | 整页文本、导航、示例，以及很多无关接口 | 中低 | 单次任务经常是数千到数万 token |
| Context7 这类网页文档读取工具 | AI 在请求时读取并总结网页文档 | 中 | 比手动粘贴更方便，但仍要承担页面获取、解析和较宽泛文档上下文的成本 |
| CLI/MCP 精确查询 | 一个接口或 schema 的结构化 JSON/Markdown | 高 | 接口文档上下文通常可减少约 70-95% |
| MCP 先搜索再查详情 | 小候选列表，再获取精确接口详情 | 高 | 大接口集最划算，常常只需要几百到几千 token |

一个保守例子：如果复制一段 Knife4j/Swagger 模块文档需要 10,000-30,000 token，那么一次针对单接口的 `apiskill_get_endpoint` 或 `apiskill_query_api` 返回通常在 500-2,000 token 左右。仅接口文档这部分，就可能减少约 5 倍到 60 倍的上下文体积。随着前端、后端、测试任务反复使用同一份文档，节省会继续叠加，因为文档已经在本地缓存，不需要每次重新粘贴。

Context7 这类网页文档读取工具很适合公开文档、并且需要实时参考上游资料的场景。但对于内部接口文档或反复迭代的业务项目，API Skill 会更可控：文档已经导入本地，访问权限只需要处理一次，AI 可以查询或编辑很窄的本地接口契约，而不是反复读取大段网页内容。

更大的收益不只是 token 便宜。结构化查询能减少无关上下文，让字段名、必填状态、类型和响应结构更容易被保留，也允许 AI 在确实需要时再继续取更深的 schema。

### 综合性价比

API Skill 的成本主要是一次性配置：安装依赖、导入或爬取文档、配置 CLI 或 MCP。完成后，同一份缓存可以服务日常开发。只要项目接口数量较多、schema 较深、多人协作，或经常让 AI 辅助写页面、服务和测试，通常很快就能回本。

收益主要来自：

- 减少反复粘贴大段文档和截图识别。
- 给 AI agent 一个确定性的接口发现工具，而不是依赖记忆或视觉提取。
- 当上游文档滞后时，可以保留本地修正。
- 让接口上下文同时出现在终端、编辑器、MCP 客户端和 Web 端，不需要改变原始文档来源。

如果项目很小，只有少量稳定接口，直接复制文本也可以接受。但对于需要持续实现页面、服务、mock 或测试的团队，CLI/MCP 通常能同时降低上下文成本和集成错误率。

### CLI 和 MCP 怎么选

CLI 是最通用、最确定的入口。它可以在任何 shell、CI 任务、编辑器任务，或能执行命令的 AI 工具里使用。脚本化批量更新、导入导出检查、可复现自动化这类场景，CLI 通常更容易调试和分享。如果用户或自动化只执行精确命令，并只把精简结果带回对话，CLI 也很省 token。

MCP 更适合 agent 工作流。兼容 MCP 的 AI 客户端可以自动发现工具，直接调用 `apiskill_search_endpoints`、`apiskill_create_document`、`apiskill_create_api`、`apiskill_get_endpoint` 等能力，并只接收结构化结果。这样通常能节省提示词 token，因为用户不需要手动粘贴命令输出或完整接口文档。代价是兼容性：AI 工具需要支持 stdio MCP server 和工具 schema，不同客户端在超时处理、工作目录配置、权限确认体验、工具结果展示上可能会有差异。

如果 CLI 和 MCP 调用同一套 shared core，并传入相同 payload，生成的 API 文档内容应该一致。需要通用自动化和 CI 可复现时优先 CLI；希望 AI agent 在编码过程中自主搜索、创建、编辑、查询接口文档时优先 MCP。

### 项目集成收益

前端团队可以在写页面、hooks、请求 client、表单、表格和校验逻辑时查询精确接口契约。响应字段查询能帮助把 API 数据映射到 UI 状态，而不需要把整页文档贴给模型。

后端团队可以用同一份缓存查看现有契约、对比手动变更，并在上游 OpenAPI 文档更新前先维护临时或修正后的本地接口。这对实现已经变化但文档还没同步的场景很实用。

测试自动化可以基于同一份接口详情生成或检查 mock、fixture、契约断言和端到端测试准备数据。因为 CLI 和 MCP 共享缓存，测试可以绑定到某个已知版本，而不是依赖远程文档站点当前返回的内容。

Agent 工作流最适合接入 MCP。编码 agent 可以先调用 `apiskill_search_endpoints` 搜索接口，再用 `apiskill_get_endpoint` 获取精确详情，需要时用 `apiskill_get_schema` 展开 schema，然后再实现或修改代码。这样接口文档不再是一大坨文本，而变成项目级工具。

## 文档

- Web 端：[English](https://unpkg.com/apiskill@latest/docs/web.md) / [中文](https://unpkg.com/apiskill@latest/docs/web.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/web.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/web.ja.md)
- CLI 配置和使用：[English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)
- MCP 配置和使用：[English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)

## 数据模型

所有入口都读写同一套缓存：

```text
cache/latest-import.json
cache/versions/
```

Web 端和 CLI 可以导入远程或本地 OpenAPI 文档。MCP 服务可以查询缓存；当明确调用写入工具时，也可以导入文档或创建、编辑、删除手动接口。