# webinterface-interceptor-ai-auto-annotation

**Repository Path**: ismartyx/webinterface-interceptor-ai-auto-annotation

## Basic Information

- **Project Name**: webinterface-interceptor-ai-auto-annotation
- **Description**: 一款拦截系统访问接口并对接口生成swagger文档的软件
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔍 Web Interface API 拦截器 - AI 增强 Swagger 生成器

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![PyQt5](https://img.shields.io/badge/PyQt5-5.15+-green.svg)](https://www.riverbankcomputing.com/software/pyqt/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

一款功能强大的 API 拦截工具，支持 CDP（Chrome DevTools Protocol）拦截网络请求，并通过 AI 自动生成 Swagger/OpenAPI 文档。

## ✨ 核心功能

- **🌐 CDP 拦截**：基于 Chrome DevTools Protocol 拦截 HTTP/HTTPS 请求
- **🔍 智能过滤**：自动过滤静态资源（CSS、JS、图片等）
- **🤖 AI 智能分析**：支持所有 OpenAI 兼容模型（OpenAI GPT、DeepSeek、Azure、Ollama 等）
- **📝 自动文档化**：一键导出 Swagger/OpenAPI 格式文档（JSON/YAML）
- **🎯 请求管理**：
  - 查看详细的请求/响应数据
  - 多选和批量操作
  - 重复检测和去重
  - 右键菜单快捷操作
  - 复制 curl 命令
- **💾 数据持久化**：SQLite 本地存储，批量事务优化
- **🎨 现代化界面**：简洁直观的 UI，灵感来自 Burp Suite

##  系统要求

- Python 3.8 或更高版本
- PyQt5 和 PyQt5-WebEngine
- PyYAML
- Requests 库
- pyppeteer

## 🚀 安装步骤

### 1. 安装依赖

```bash
cd blocks/src/final_version
pip install PyQt5 PyQt5-WebEngine pyyaml requests pyppeteer openai
```

或使用清华镜像源（国内更快）：
```bash
pip install PyQt5 PyQt5-WebEngine pyyaml requests pyppeteer openai -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2. 启动应用

```bash
cd blocks/src/final_version
python burp_api_refactored.py
```

## 🎮 使用方法

### 基础使用

1. **启动应用程序**：
   ```bash
   cd blocks/src/final_version
   python burp_api_refactored.py
   ```

2. **打开浏览器窗口**：
   - 点击 `🌐 浏览器` → `🔗 打开独立浏览器窗口`
   - 导航到目标 Web 应用程序

3. **拦截请求**：
   - 所有 API 请求将被自动捕获
   - 在主窗口的请求树中查看详情

4. **导出文档**：
   - 点击 `📄 文件` → `💾 导出 Swagger JSON` 或 `💾 导出 Swagger YAML`
   - 选择输出位置

### AI 增强工作流

1. **配置 AI**：
   - 点击 `⚙️ 配置` → `🤖 AI 配置`
   - 输入 API Key、Base URL 和模型名称
   - 选择简洁模式或详细模式

2. **注释 API**：
   - **批量模式**：点击 `🤖 AI 翻译` → `🔄 批量注释所有接口`
   - **选择模式**：勾选请求后点击 `🤖 AI 注释选中项`
   - **去重模式**：右键点击 → `🧹 去重后 AI 注释`

3. **查看结果**：
   - AI 生成的摘要显示在请求树中
   - 在请求详情面板查看详细描述

## 📁 项目结构

```
webinterface-interceptor-ai-auto-annotation/
├── blocks/
│   └── src/
│       └── final_version/
│           ├── burp_api_refactored.py          # Python 主程序
│           ├── cdp_interceptor.py              # CDP 拦截器
│           ├── db_manager.py                  # 数据库管理
│           └── interceptor.py                 # 基础拦截器
├── README.md                                    # 英文说明文档
└── README_CN.md                                 # 中文说明文档（本文件）
```

## 🔧 配置说明

### AI 配置

支持所有兼容 OpenAI 接口的 AI 服务：

| 服务商 | Base URL | 推荐模型 |
|--------|----------|----------|
| OpenAI | `https://api.openai.com/v1` | `gpt-4`, `gpt-3.5-turbo` |
| DeepSeek | `https://api.deepseek.com` | `deepseek-chat`, `deepseek-coder` |
| Azure OpenAI | `你的 Azure 端点` | `gpt-4`, `gpt-35-turbo` |
| Ollama | `http://localhost:11434/v1` | `llama2`, `mistral` |
| LM Studio | `http://localhost:1234/v1` | 任意本地模型 |

### AI 模式

- **简洁模式**（推荐）：约 200-300 tokens/接口，快速生成
- **详细模式**：约 500-800 tokens/接口，完整提示词

## 🎯 功能详解

### CDP 拦截

基于 Chrome DevTools Protocol 拦截网络请求：
- 自动过滤静态资源（CSS、JS、图片、字体等）
- 响应体大小限制（1MB），避免内存溢出
- 跳过二进制资源（视频、PDF等）
- 完整捕获请求/响应头和体

### AI 分析

AI 自动生成以下内容：
- **接口摘要**：一句话描述接口功能
- **详细描述**：包括参数、返回值等详细说明
- **请求参数**：参数类型、含义
- **响应字段**：字段类型、描述、示例
- **标签**：用于接口分类
- **注意事项**：特殊说明和注意事项

### Swagger 导出

生成标准的 OpenAPI 3.0 文档，包含：
- 完整的路径参数、查询参数
- 请求体 Schema（自动解析）
- 响应 Schema（支持 AI 字段注释）
- Tags 分类
- operationId
- 示例数据
- 支持 JSON 和 YAML 两种格式

### curl 命令复制

右键点击请求可复制 curl 命令：
- 自动转义特殊字符
- 排除自动添加的请求头
- 限制请求体长度
- 包含 AI 摘要注释

## 🐛 故障排除

### 常见问题

1. **PyQt5 导入错误**：
   ```bash
   pip install --upgrade PyQt5 PyQt5-WebEngine
   ```

2. **CDP 浏览器无法启动**：
   - 检查系统是否安装了 Chrome 浏览器
   - 需要配置 Chrome 路径

3. **AI 功能不工作**：
   - 验证 API Key 是否正确
   - 检查 Base URL 格式
   - 确保有网络连接
   - 查看控制台输出的错误信息
   - 检查 AI 响应是否为空（AI 可能拒绝回答）

4. **导出失败**：
   - 确保对输出目录有写入权限
   - 检查是否至少捕获了一个请求
   - 验证文件路径是否有效

## 📊 输出格式

### Swagger JSON 示例

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "拦截的 API 文档",
    "version": "1.0.0"
  },
  "paths": {
    "/api/users": {
      "get": {
        "summary": "获取用户列表",
        "description": "查询系统中的所有用户信息，支持分页和筛选...",
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    }
  }
}
```

## 🤝 贡献指南

欢迎贡献！请随时提交 Pull Request。

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m '添加某个很棒的功能'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📝 开源协议

本项目采用 MIT 协议 - 详见 LICENSE 文件。

## 🙏 致谢

- **特别感谢**：群里大佬提供的公益 AI 站点 Token 赞助！吃水不忘挖井人！
- 基于 [PyQt5](https://www.riverbankcomputing.com/software/pyqt/) 构建
- AI 技术支持所有兼容 OpenAI 接口的服务
- 界面设计灵感来自 [Burp Suite](https://portswigger.net/burp)

## 📧 联系方式

如有问题或需要支持，请在 GitHub 上提交 issue。

## 🔄 版本历史

### v3.0（当前版本）
- ✅ CDP 拦截器响应体优化（大小限制、二进制过滤）
- ✅ AI 服务空内容判断和错误处理增强
- ✅ Swagger YAML 导出支持
- ✅ curl 命令复制功能
- ✅ 数据库批量保存优化
- ✅ 响应对象结构改进（status、headers、body）
- ✅ AI 增强的 API 注释
- ✅ 多选和批量操作
- ✅ 重复检测
- ✅ 右键菜单支持
- ✅ 改进的 UI/UX
- ✅ 配置持久化
- ✅ CDP 拦截器实现

### v2.0
- ✅ 内嵌浏览器
- ✅ 请求/响应拦截
- ✅ 基础 Swagger 导出

### v1.0
- ✅ 初始版本
- ✅ 基础 API 拦截

## 💡 使用技巧

### 提高 AI 注释质量

1. **确保请求完整**：等待响应数据加载完成后再进行 AI 注释
2. **合理去重**：使用去重功能避免重复注释相同接口
3. **批量处理**：对于大量接口，建议分批次处理，避免 API 限流
4. **选择合适模式**：推荐使用简洁模式，节省 token 成本

### 优化性能

1. **过滤无关请求**：工具已自动过滤静态资源，无需额外配置
2. **定期清理**：对于长时间运行，建议定期清理已捕获的请求
3. **选择性导出**：只导出需要的接口，提高文档质量

### 最佳实践

1. **先测试后导出**：在导出前先浏览几个接口，确认拦截正常
2. **保存配置**：配置好 AI 后记得保存，避免重复输入
3. **备份数据**：重要的拦截数据建议及时导出保存
4. **API Key 安全**：不要将 API Key 提交到公共仓库

## 🎓 学习资源

- [OpenAPI 规范](https://swagger.io/specification/)
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
- [PyQt5 文档](https://www.riverbankcomputing.com/static/Docs/PyQt5/)
- [OpenAI API 文档](https://platform.openai.com/docs)

## 🔐 安全提示

- **API 密钥安全**：请妥善保管 API 密钥，不要提交到公共仓库
- **数据隐私**：拦截的请求可能包含敏感信息，请注意保护
- **合法使用**：仅用于授权的测试和开发环境

---

**用 ❤️ 为 API 开发者和安全研究人员打造**