70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# 什么是 AgentFox
|
||
|
||
AgentFox 是一个 MCP 驱动的 API 文档服务，让 AI 编程助手（如 Claude Code、Cursor、GitHub Copilot）能够高效地查询你的 API 文档。
|
||
|
||
## 解决什么问题？
|
||
|
||
当你使用 AI 编程助手调用第三方 API 时，通常需要将 API 文档提供给 LLM。传统做法是将整个 OpenAPI 规范复制粘贴到对话中，这带来了几个问题：
|
||
|
||
- **Token 浪费**：一份完整的 OpenAPI 规范可能消耗 10,000-100,000+ tokens，而你可能只需要其中一个端点的信息
|
||
- **上下文污染**：大量无关信息会降低 LLM 的理解准确度
|
||
- **手动操作**：每次都需要手动查找、复制文档
|
||
|
||
## AgentFox 如何工作？
|
||
|
||
```
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ OpenAPI 文档 │───▶│ AgentFox │───▶│ MCP 端点 │
|
||
│ (JSON/YAML) │ │ 解析 & 索引 │ │ /mcp/:id │
|
||
└──────────────┘ └──────────────┘ └──────────────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ LLM 按需查询 │
|
||
│ ~200-2K tokens │
|
||
└──────────────┘
|
||
```
|
||
|
||
1. **导入**：上传 OpenAPI 3.x 或 Swagger 2.0 文档（JSON/YAML 文件或 URL）
|
||
2. **解析**：AgentFox 自动解引用所有 `$ref`，将文档解析为模块和端点
|
||
3. **生成 MCP 端点**：每个项目获得唯一的 MCP 服务 URL
|
||
4. **LLM 按需查询**：AI 工具通过 5 个 MCP 工具渐进式获取所需信息
|
||
|
||
## 核心优势
|
||
|
||
### 渐进式下钻
|
||
|
||
LLM 不需要一次获取所有信息。它可以：
|
||
- 先查看项目概览，了解有哪些模块
|
||
- 再查看特定模块的端点列表
|
||
- 最后获取具体端点的完整参数和响应格式
|
||
|
||
### Token 高效
|
||
|
||
| 操作 | Token 消耗 |
|
||
|------|-----------|
|
||
| `get_project_overview` | ~200 tokens |
|
||
| `list_modules` | ~100-300 tokens |
|
||
| `list_endpoints` | ~200-500 tokens |
|
||
| `get_endpoint_detail` | ~500-2,000 tokens |
|
||
| `search_endpoints` | ~200-500 tokens |
|
||
| **全量 OpenAPI 规范** | **10,000-100,000+ tokens** |
|
||
|
||
典型的 API 集成任务只需 2-3 次工具调用（约 1,300 tokens），相比全量规范节省 **80-95%** 的 token 消耗。
|
||
|
||
### 全规范支持
|
||
|
||
- OpenAPI 3.0 / 3.1
|
||
- Swagger 2.0
|
||
- JSON 和 YAML 格式
|
||
- 所有 `$ref` 引用自动解引用
|
||
|
||
### 一键导入
|
||
|
||
粘贴 URL 或上传文件，API 文档即时解析并索引。支持从 localhost 和内网地址获取文档。
|
||
|
||
## 下一步
|
||
|
||
- [了解 MCP 协议](what-is-mcp.md)
|
||
- [快速开始](../getting-started/README.md)
|