---
created: 2026-03-29
updated: 2026-04-06
type: project
status: COMPLETED (2026-03-30)
parent: "[[Smart Support]]"
phase: 3
timeline: 第 4-6 周
tags:
  - phase-3
  - openapi
  - mcp
  - ssrf
  - security
  - llm-classification
  - code-generation
  - api-parsing
  - async-import
---

# Phase 3：OpenAPI 自动发现

> Status: COMPLETED (2026-03-30)

## 目标

实现 Smart Support 的「10x 差异化功能」：用户粘贴 OpenAPI 规范 URL，系统自动生成 @tool 函数和 Agent 配置。

## 阶段产出

- SSRF 防护模块：私有 IP 拦截、DNS 重绑定防御、重定向链验证
- OpenAPI 获取器：SSRF 安全、JSON/YAML 自动检测、10MB 大小限制
- 结构化 OpenAPI 验证器：3.0.x 和 3.1.x
- 端点解析器：$ref 解析、参数提取、自动生成 operationId
- 启发式 + LLM 端点分类器：GET=read, POST/PUT/PATCH/DELETE=write，LLM 失败回退启发式
- 审核 API（/api/openapi）：导入任务、分类审核、批准生成
- @tool 代码生成器：async 函数 + httpx
- Agent YAML 生成器：按分类分组端点
- 导入编排器：fetch -> validate -> parse -> classify 全流程
- 内存任务存储：导入状态追踪

## 新增文件

| 文件 | 用途 | 行数 |
|------|------|------|
| `app/openapi/models.py` | 冻结数据类：EndpointInfo, ClassificationResult, ImportJob | 68 |
| `app/openapi/ssrf.py` | SSRF 防护（validate_url, safe_fetch, DNS 解析） | 162 |
| `app/openapi/fetcher.py` | SSRF 安全规范获取 | 94 |
| `app/openapi/validator.py` | 结构化规范验证 | 52 |
| `app/openapi/parser.py` | 端点提取 + $ref 解析 | 153 |
| `app/openapi/classifier.py` | 启发式 + LLM 分类器 | 164 |
| `app/openapi/review_api.py` | 导入/审核 API 路由 | 180 |
| `app/openapi/generator.py` | @tool 代码 + YAML 生成 | 157 |
| `app/openapi/importer.py` | 异步导入流水线 | 117 |

## 测试覆盖

- 新增测试：125 个（118 单元 + 7 集成）
- 总测试：322
- 覆盖率：93.23%
- SSRF 测试最多：42 个

## 与计划的偏差

- 未构建自定义工具基类（架构文档明确禁止）
- 使用轻量级结构化验证器而非包装外部库
- 内存任务存储而非数据库（可后续迁移 PostgreSQL）
- 前端审核 UI 推迟到 Phase 5

## 技术债务

- 前端 ReviewPage 推迟（API 就绪）
- 代码生成基于字符串模板
- LLM 分类提示可用真实案例调优
- 审核 API 无速率限制

## Related

- [[Smart Support/Phase 2 - 多 Agent + 安全]]
- [[Smart Support/Phase 4 - 分析 + 回放]]
- [[Smart Support]]