feat: deploy skill

2026-04-12 20:15:41 +08:00
parent 6fe04f4893
commit 71c604411d
37 changed files with 1701 additions and 2 deletions
--- a/docs/mcp-tools/README.md
+++ b/docs/mcp-tools/README.md
@@ -0,0 +1,48 @@
+# MCP 工具概述
+
+AgentFox 提供 5 个 MCP 工具，采用渐进式下钻设计，让 LLM 按需获取精确信息。
+
+## 设计理念
+
+传统方式是将完整 API 规范一次性提供给 LLM（10,000+ tokens）。AgentFox 将信息分层，LLM 按需逐层获取：
+
+```
+get_project_overview          ← 项目级：名称、版本、模块摘要（~200 tokens）
+    │
+    ├── list_modules          ← 模块级：模块描述和端点数量（~100-300 tokens）
+    │       │
+    │       └── list_endpoints    ← 端点列表：方法、路径、摘要（~200-500 tokens）
+    │               │
+    │               └── get_endpoint_detail  ← 端点详情：参数、请求体、响应（~500-2000 tokens）
+    │
+    └── search_endpoints      ← 关键词搜索：跨模块搜索端点（~200-500 tokens）
+```
+
+## 推荐调用流程
+
+对于典型的 API 集成任务，LLM 通常会按以下顺序调用：
+
+1. **`get_project_overview`** — 了解项目结构和可用模块
+2. **`list_endpoints`** — 浏览目标模块的端点列表（或用 `search_endpoints` 搜索）
+3. **`get_endpoint_detail`** — 获取目标端点的完整信息
+
+大多数任务只需要 2-3 次调用，总共约 1,000-1,500 tokens。
+
+## Token 消耗对比
+
+| 工具 | 平均 Token 消耗 | 说明 |
+|------|----------------|------|
+| `get_project_overview` | ~200 | 最轻量，建议首先调用 |
+| `list_modules` | ~100-300 | 按模块数量线性增长 |
+| `list_endpoints` | ~200-500 | 按端点数量线性增长 |
+| `get_endpoint_detail` | ~500-2,000 | 取决于参数和响应 schema 复杂度 |
+| `search_endpoints` | ~200-500 | 最多返回 20 条结果 |
+| **全量 OpenAPI 规范** | **10,000-100,000+** | 传统方式 |
+
+## 工具列表
+
+- [`get_project_overview`](get-project-overview.md) — 获取项目概览
+- [`list_modules`](list-modules.md) — 列出所有模块
+- [`list_endpoints`](list-endpoints.md) — 列出模块中的端点
+- [`get_endpoint_detail`](get-endpoint-detail.md) — 获取端点完整详情
+- [`search_endpoints`](search-endpoints.md) — 按关键词搜索端点
--- a/docs/mcp-tools/get-endpoint-detail.md
+++ b/docs/mcp-tools/get-endpoint-detail.md
@@ -0,0 +1,92 @@
+# get_endpoint_detail
+
+获取端点的完整详细信息，包括参数、请求体和响应格式。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `endpointId` | string | 是 | 端点 ID，可从 `list_endpoints` 或 `search_endpoints` 获取 |
+
+## 返回结果
+
+```json
+{
+  "id": "ep_001",
+  "method": "POST",
+  "path": "/v1/charges",
+  "summary": "Create a charge",
+  "description": "Creates a new charge object. If the charge fails, the API returns an error.",
+  "operationId": "createCharge",
+  "moduleName": "Payments",
+  "parameters": [
+    {
+      "name": "Idempotency-Key",
+      "in": "header",
+      "required": false,
+      "schema": { "type": "string" },
+      "description": "Unique key for idempotent requests"
+    }
+  ],
+  "requestBody": {
+    "required": true,
+    "content": {
+      "application/json": {
+        "schema": {
+          "type": "object",
+          "required": ["amount", "currency"],
+          "properties": {
+            "amount": { "type": "integer", "description": "Amount in cents" },
+            "currency": { "type": "string", "description": "Three-letter ISO currency code" },
+            "source": { "type": "string", "description": "Payment source token" }
+          }
+        }
+      }
+    }
+  },
+  "responses": {
+    "200": {
+      "description": "Charge created successfully",
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "amount": { "type": "integer" },
+              "status": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "deprecated": false
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 端点 ID |
+| `method` | string | HTTP 方法 |
+| `path` | string | API 路径 |
+| `summary` | string | 端点摘要 |
+| `description` | string | 端点详细描述 |
+| `operationId` | string | 操作标识符 |
+| `moduleName` | string | 所属模块名称 |
+| `parameters` | array | URL/查询/头部/Cookie 参数列表（原始 OpenAPI schema） |
+| `requestBody` | object | 请求体规范 |
+| `responses` | object | HTTP 响应规范（按状态码分组） |
+| `deprecated` | boolean | 是否已弃用 |
+
+## Token 消耗
+
+约 **500-2,000 tokens**，取决于参数数量和响应 schema 的复杂程度。这是 token 消耗最多的工具，但也是信息最丰富的。
+
+## 使用场景
+
+- 需要了解如何调用某个具体端点
+- 查看请求参数的类型、是否必填、描述
+- 查看响应格式以便解析返回数据
--- a/docs/mcp-tools/get-project-overview.md
+++ b/docs/mcp-tools/get-project-overview.md
@@ -0,0 +1,52 @@
+# get_project_overview
+
+获取项目的基本信息和模块摘要。这是推荐的第一个调用工具。
+
+## 参数
+
+无参数。
+
+## 返回结果
+
+```json
+{
+  "name": "Stripe API",
+  "description": "The Stripe REST API",
+  "version": "3.0.0",
+  "baseUrl": "https://api.stripe.com",
+  "totalEndpoints": 247,
+  "modules": [
+    {
+      "id": "mod_abc123",
+      "name": "Payments",
+      "endpointCount": 15
+    },
+    {
+      "id": "mod_def456",
+      "name": "Customers",
+      "endpointCount": 8
+    }
+  ]
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 项目名称（来自 OpenAPI 的 `info.title`） |
+| `description` | string | 项目描述 |
+| `version` | string | OpenAPI 规范版本 |
+| `baseUrl` | string \| null | API 基础 URL |
+| `totalEndpoints` | number | 端点总数 |
+| `modules` | array | 模块列表（含 id、名称和端点数量） |
+
+## Token 消耗
+
+约 **200 tokens**，是最轻量的工具。
+
+## 使用场景
+
+- 初次连接时了解 API 的整体结构
+- 查看有哪些模块可供探索
+- 获取模块 ID 以供后续调用 `list_endpoints`
--- a/docs/mcp-tools/list-endpoints.md
+++ b/docs/mcp-tools/list-endpoints.md
@@ -0,0 +1,59 @@
+# list_endpoints
+
+列出指定模块中的所有端点摘要信息。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `moduleId` | string | 是 | 模块 ID，可从 `get_project_overview` 或 `list_modules` 获取 |
+
+## 返回结果
+
+```json
+[
+  {
+    "id": "ep_001",
+    "method": "POST",
+    "path": "/v1/charges",
+    "summary": "Create a charge",
+    "deprecated": false
+  },
+  {
+    "id": "ep_002",
+    "method": "GET",
+    "path": "/v1/charges/{id}",
+    "summary": "Retrieve a charge",
+    "deprecated": false
+  },
+  {
+    "id": "ep_003",
+    "method": "POST",
+    "path": "/v1/refunds",
+    "summary": "Create a refund",
+    "deprecated": false
+  }
+]
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 端点 ID，用于 `get_endpoint_detail` |
+| `method` | string | HTTP 方法（GET、POST、PUT、DELETE 等） |
+| `path` | string | API 路径 |
+| `summary` | string | 端点简短描述 |
+| `deprecated` | boolean | 是否已弃用 |
+
+结果按路径字母排序，然后按 HTTP 方法排序。
+
+## Token 消耗
+
+约 **200-500 tokens**，取决于模块中的端点数量。
+
+## 使用场景
+
+- 浏览特定模块中的所有端点
+- 找到目标端点的 ID，用于调用 `get_endpoint_detail`
+- 了解 API 提供了哪些操作
--- a/docs/mcp-tools/list-modules.md
+++ b/docs/mcp-tools/list-modules.md
@@ -0,0 +1,49 @@
+# list_modules
+
+列出项目中的所有模块及其描述信息。
+
+## 参数
+
+无参数。
+
+## 返回结果
+
+```json
+[
+  {
+    "id": "mod_abc123",
+    "name": "Payments",
+    "description": "Manage charges, refunds, and payment intents",
+    "endpointCount": 15
+  },
+  {
+    "id": "mod_def456",
+    "name": "Customers",
+    "description": "Create and manage customer records",
+    "endpointCount": 8
+  }
+]
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 模块 ID，用于 `list_endpoints` 和 `search_endpoints` |
+| `name` | string | 模块名称 |
+| `description` | string | 模块描述 |
+| `endpointCount` | number | 模块中的端点数量 |
+
+## Token 消耗
+
+约 **100-300 tokens**，取决于模块数量。
+
+## 使用场景
+
+- 需要查看模块的详细描述（`get_project_overview` 不包含描述）
+- 决定要探索哪个模块时
+- 需要获取模块 ID 用于后续调用
+
+## 与 get_project_overview 的区别
+
+`get_project_overview` 返回的模块列表只包含 id、名称和端点数量，不包含描述。如果需要模块描述来判断探索哪个模块，使用 `list_modules`。
--- a/docs/mcp-tools/search-endpoints.md
+++ b/docs/mcp-tools/search-endpoints.md
@@ -0,0 +1,64 @@
+# search_endpoints
+
+按关键词搜索端点。支持跨模块搜索，也可以限定在特定模块内。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `keyword` | string | 是 | 搜索关键词 |
+| `moduleId` | string | 否 | 限定搜索范围的模块 ID，不填则搜索所有模块 |
+
+## 搜索范围
+
+关键词会匹配以下字段（不区分大小写）：
+- 端点路径（`path`）
+- 端点摘要（`summary`）
+- 端点描述（`description`）
+- 操作标识符（`operationId`）
+
+## 返回结果
+
+```json
+[
+  {
+    "id": "ep_001",
+    "method": "POST",
+    "path": "/v1/charges",
+    "summary": "Create a charge",
+    "moduleName": "Payments",
+    "deprecated": false
+  },
+  {
+    "id": "ep_005",
+    "method": "POST",
+    "path": "/v1/payment_intents",
+    "summary": "Create a PaymentIntent",
+    "moduleName": "Payments",
+    "deprecated": false
+  }
+]
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 端点 ID，可传给 `get_endpoint_detail` |
+| `method` | string | HTTP 方法 |
+| `path` | string | API 路径 |
+| `summary` | string | 端点摘要 |
+| `moduleName` | string | 所属模块名称 |
+| `deprecated` | boolean | 是否已弃用 |
+
+最多返回 **20 条**结果，按路径和方法排序。
+
+## Token 消耗
+
+约 **200-500 tokens**。
+
+## 使用场景
+
+- 不知道端点在哪个模块，通过关键词搜索
+- 快速定位与某个功能相关的端点
+- 模糊搜索，如搜索 "user" 找到所有用户相关端点