82 lines
2.5 KiB
Markdown
82 lines
2.5 KiB
Markdown
---
|
||
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]]
|