kai/knowledge-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cadfa01e3b1d97b39bd65b773f5bd1b4a5aa75ea
knowledge-base/2 - Projects/Smart Support/Phase 3 - OpenAPI 自动发现.md

8.3 KiB
Raw Blame History

created, type, status, parent, phase, timeline
created type status parent phase timeline
2026-03-29 project 未开始 Smart Support 3 第 4-6 周

Phase 3：OpenAPI 自动发现

目标

实现 Smart Support 的「10x 差异化功能」：用户粘贴 OpenAPI 规范 URL，系统自动生成 MCP 服务器和 Agent 配置。这个阶段结束时，用户无需写代码，只需提供 API 文档就能让 AI Agent 操作他们的系统。

前置条件

阶段产出

  • 粘贴 OpenAPI spec URL → 自动解析 + 生成 MCP 服务器 + 注册 Agent
  • LLM 自动分类端点（读/写、客户参数、Agent 分组）
  • 运维审核界面确认/修正 LLM 分类结果
  • SSRF 防护保障 URL 获取安全
  • 导入过程异步执行，WebSocket 实时推送进度

集成检查点

第 6 周末验证：

  1. 粘贴一个真实的 OpenAPI 3.0 spec URL → 解析成功
  2. 生成的 MCP 服务器正确包装每个端点
  3. LLM 分类结果合理（GET = read，DELETE = write）
  4. 运维审核后，agent 自动注册到 supervisor
  5. 在聊天中使用新生成的工具完成操作
  6. SSRF 攻击被拦截（私有 IP、localhost）

任务清单

1. SSRF 防护模块

独立模块 backend/app/openapi/ssrf.py，可与 Phase 1-2 并行开发

  • URL 解析：提取 host，解析 DNS 获取 IP
  • 屏蔽私有 IP 范围：
    • 10.0.0.0/8
    • 172.16.0.0/12
    • 192.168.0.0/16
    • 127.0.0.0/8（localhost）
    • 169.254.0.0/16（link-local，云元数据端点）
    • 0.0.0.0/8
    • ::1（IPv6 localhost）
  • DNS 重绑定防护：解析 DNS → 检查 IP → 使用解析后的 IP 发起请求（不让 DNS 在检查和请求之间变化）
  • URL 协议限制：仅允许 http:// 和 https://，拒绝 file://, ftp://, gopher:// 等
  • 可选 URL 白名单：通过配置限制只允许特定域名
  • 单元测试覆盖所有拦截场景

2. OpenAPI 规范解析器

  • 支持 OpenAPI 3.0+ 规范（JSON 和 YAML 格式）
  • 使用 openapi-spec-validator 验证规范合法性
  • 通过 SSRF 安全模块获取远程 URL 内容
  • 解析每个端点提取：
    • HTTP 方法 + 路径
    • 描述 / summary
    • 请求参数（path params, query params, request body schema）
    • 响应 schema
    • 认证要求（API key, Bearer token, OAuth）
  • 错误处理：
    • 无效 URL → 「无法访问该地址，请检查 URL 是否正确」
    • 无效规范格式 → 「该文件不是有效的 OpenAPI 3.0 规范：[具体原因]」
    • 认证要求无法自动满足 → 提示用户提供 API key
  • OpenAPI 2.0 (Swagger) → 返回明确提示：「检测到 Swagger 2.0 格式，请升级到 OpenAPI 3.0」
  • 大型规范（100+ 端点）→ 正常处理，不超时

3. MCP 服务器生成器

  • 为每个解析到的端点生成 MCP tool 定义
  • Tool 名称：从路径 + 方法自动生成（如 GET /orders/{id} → get_order_by_id）
  • Tool 描述：使用端点的 summary/description
  • Tool 参数：从 path params + query params + request body 提取，保留类型信息
  • 生成可运行的 MCP 服务器代码（Python，使用 mcp SDK）
  • 处理复杂 request body（嵌套对象、数组）→ 扁平化或保留 JSON 结构
  • 认证注入：生成的服务器支持在配置中设置 API key / Bearer token，自动添加到请求 header

4. LLM 辅助端点分类

  • 将解析后的端点信息（方法、路径、描述）发送给 LLM
  • LLM 分类任务：
    1. 读/写分类：每个端点标记为 read（不触发 interrupt）或 write（触发 interrupt）
    2. 客户参数识别：哪些参数代表客户标识（customer_id, email, phone）
    3. Agent 分组建议：将端点按功能分组为不同 Agent（如「订单管理」「用户管理」「支付操作」）
  • 分类提示模板：
你是一个 API 安全分析师。分析以下 API 端点列表，为每个端点提供：
1. 操作类型：read（查询/获取数据）或 write（创建/修改/删除数据）
2. 客户参数：哪些参数代表客户身份标识
3. 建议的 Agent 分组名称

规则：
- GET 请求通常是 read，但要看描述（如 GET /export 可能是 write）
- POST/PUT/PATCH/DELETE 通常是 write
- 涉及金钱、订单状态变更、账号操作的必须标记为 write
  • 分类结果缓存：同一规范不重复分类
  • 成本控制：使用 prompt caching 减少重复输入成本

5. 运维审核/修正 UI

  • API 端点：GET /api/openapi/review/{import_id} → 返回 LLM 分类结果
  • API 端点：POST /api/openapi/review/{import_id} → 提交修正后的分类
  • 前端审核界面：
    • 端点列表，每行显示：方法、路径、描述、LLM 分类（read/write）、Agent 分组
    • 每个分类可以点击修改（下拉选择）
    • 「全部确认」按钮 → 生成最终 MCP 服务器 + Agent YAML
  • 修正后重新生成不需要再次调用 LLM

6. Agent YAML 自动生成

  • 根据 LLM 分类 + 运维修正结果，生成 Agent YAML 配置
  • 每个 Agent 分组 → 一个 agent 条目
  • permission 根据分组内端点的最高权限决定（有一个 write 端点就标记为 write）
  • 自动生成 agent description（基于分组内端点的描述汇总）
  • 生成的 YAML 合并到 agent 注册表，热加载到 supervisor（不需要重启）

7. 异步导入 + 进度更新

  • 导入流程作为后台任务执行（asyncio.create_task）
  • 通过 WebSocket 推送进度更新：
{"type": "import_progress", "step": "parsing", "message": "正在解析 OpenAPI 规范..."}
{"type": "import_progress", "step": "classifying", "message": "正在分析端点 12/50..."}
{"type": "import_progress", "step": "generating", "message": "正在生成 MCP 服务器..."}
{"type": "import_progress", "step": "review", "message": "分析完成，请审核分类结果", "review_url": "/review/abc123"}
{"type": "import_progress", "step": "done", "message": "导入完成！新增 3 个 Agent，15 个工具"}
  • 导入期间聊天功能不受影响
  • 导入失败 → 推送错误消息 + 错误详情

8. 测试

  • SSRF 测试： 私有 IP (10.x, 172.16.x, 192.168.x) → 拦截
  • SSRF 测试： localhost / 127.0.0.1 → 拦截
  • SSRF 测试： 169.254.169.254（云元数据）→ 拦截
  • SSRF 测试： 合法公网 URL → 放行
  • SSRF 测试： file:// 协议 → 拦截
  • 解析测试： 有效 OpenAPI 3.0 JSON → 正确解析端点
  • 解析测试： 有效 OpenAPI 3.0 YAML → 正确解析端点
  • 解析测试： 无效规范 → 明确错误信息
  • 解析测试： 大型规范（100+ 端点）→ 不超时
  • 生成测试： 端点 → MCP tool 定义（名称、参数、描述匹配）
  • 分类测试： mock LLM 响应 → 正确解析分类结果
  • 分类测试： GET 端点 → 默认 read，DELETE 端点 → 默认 write
  • 集成测试： 完整流程：URL → 解析 → 分类 → 生成 → 注册
  • E2E 测试： 粘贴 spec URL → 进度更新 → 审核 → 新工具在聊天中可用

技术要点

功能 技术选型 说明
规范验证 openapi-spec-validator PyPI 包，支持 3.0+
URL 获取 httpx + SSRF 模块 异步 HTTP，IP 检查
MCP 生成 mcp SDK (Python) 生成 stdio MCP 服务器
LLM 分类 ChatAnthropic structured output JSON mode 确保输出格式
异步任务 asyncio.create_task FastAPI 内后台任务

风险与缓解

风险 影响 缓解措施
LLM 分类不准确 读操作被标记为写（多余确认）或反之（危险） 运维审核 UI 作为安全网，默认偏向标记为 write
复杂 request body 无法处理 部分端点工具不可用 跳过无法处理的端点，在审核 UI 中标注
DNS 重绑定绕过 SSRF 安全漏洞 解析后绑定 IP 发请求，不二次解析
大规范生成慢 用户等待久 异步 + 进度条，分批生成

Related