# WebAPIExtractor

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)
![License](https://img.shields.io/badge/license-custom%20(non--commercial)-orange)

**简体中文** | [English](README.en.md)

**把「只能手动点网页的系统」，变成 AI 能直接调用的工具 —— 你不用写一行代码。**

---

## 这是什么

很多系统只有网页界面，没有 API。你想让 AI 助手帮你查数据、提工单、导报表，
却卡在「它碰不到这个系统」这一步。

WebAPIExtractor 的做法很直接：

> **你在浏览器里怎么点，它就记下来，然后把这些操作变成 AI 可以调用的工具。**

你不用看接口文档，不用写代码，也不用理解任何技术名词。

---

## 谁适合用

- 手上有一套**只能登录网页、手动点操作**的系统（OA、ERP、CRM、工单、报表、
  内部管理后台……）
- 想让 AI 助手替你完成里面的重复操作
- 没有 API 文档，也没有开发资源

**你需要准备：**

- 一个支持「技能 / Skill」的 AI 助手桌面客户端
- 你自己的电脑（所有数据都留在本机）
- **Windows**（完整功能仅 Windows 可用；macOS / Linux 能跑，但凭据加密不可用，见下文）
- 对该系统的**合法授权** —— 只对你自己有权使用的系统使用

---

## 两步就能用起来

### 第一步 · 把技能装进你的 AI 助手

两种装法，选一种 —— **你不需要安装任何库，也不需要运行任何命令**：

- **拖进技能设置页** —— 把技能文件夹（或 `web-api-extractor-agent.zip` 导入包）拖进
  AI 助手的 **「技能 / Skill」** 设置页。不同客户端的入口位置不一样，但都在技能设置里。
- **拖进对话让 Agent 装** —— 直接把技能文件夹（或 zip）拖进对话，跟 AI 说
  「帮我把这个技能装上」即可。

> zip 从哪来？在 [Releases 页面](https://github.com/SH-DaWushi/web-api-extractor/releases/latest)
> 下载 `web-api-extractor-agent.zip` —— 它就是技能文件夹本身打成的包，内容一模一样，
> 只是不用自己去拉整个仓库。

装好后，技能列表里会出现 **web-api-extractor** 这一项。你的 AI 助手从此多了一项能力：
**陪你在浏览器里完成登录、记录你的操作、并把它们做成工具。**

> 首次使用要装一点运行环境（含一个浏览器内核），**这些都由 AI 自己完成**，你不用管。
> 如果你确实想自己动手（或要装给同事），环境准备与启动命令见
> [技术文档的「安装形态」与「启动服务」](https://github.com/SH-DaWushi/web-api-extractor/blob/main/docs/reference.md)。

### 第二步 · 用对话告诉它你要什么

这一步不用记任何命令，像平常聊天一样：

```
你：帮我给我们的 OA 系统做一套 MCP 工具
AI：（打开浏览器）请在弹出的窗口里完成登录，然后告诉我
你：登录好了
AI：登录态已保存。现在请你在浏览器里，把你想变成工具的功能都操作一遍
    —— 比如查列表、点开详情、提交一张单子
你：（操作完）好了
AI：收到，抓到 23 个接口。其中登录接口用了密码加密，我先核实一下再生成
    ……
    生成完成，包含这些工具：
      · 查我的待办        · 查工单详情
      · 提交工单          · 导出报表
    以后你（或任何接上它的 AI）就能直接调用它们了
```

**整个过程你只需要做两件事：在浏览器里登录，然后正常点一遍你要的功能。**

---

## 你会得到什么

一套**可以长期使用、随时能加功能**的工具集：

| 你得到的 | 意味着 |
|---|---|
| AI 能直接操作那个系统 | 不用再手动点网页 |
| 登录态可复用 | 抓包与后续调用都能带登录态，不必每次重新登录 |
| 自动续期（有条件） | 识别到账号密码登录接口时，生成的项目支持 token 过期自动重登录；纯 Cookie / SSO 站点过期需重新授权一次 |
| 后续想加功能，再操作一遍就行 | 不用推倒重做 |
| 可以把分发包给同事 | 对方只能调用，无法改动你的工具 |

---

## 它能做什么 / 它做不到什么

> 这里是给你判断「能不能用」的概览；每条判定规则与代码依据见技术文档的
> 「能力边界（做不到什么）」与「平台矩阵」。

### 能做到

1. **把网页系统变成 AI 的工具集** —— 你在浏览器里正常点一遍，后台记录全部请求与响应。
2. **自动整理接口** —— 同构接口自动合并（`/user/123`、`/user/456` → `/user/{id}`），
   参数按真实样本推导出类型。
3. **两种登录都覆盖** —— 能构造请求的走表单登录；验证码 / 短信 / 单点登录走真实浏览器
   交互式登录（**登录是否完成由你确认**，工具不会自己判定）。
4. **生成可直接运行的 MCP 项目** —— 多域名路由、类型化参数、按实测鉴权方式、写操作需
   `confirm=true`、自带冒烟测试与只读诊断。
5. **凭据加密保存、重启自动恢复、401 自动重登录** —— 前提是识别到了账号密码登录接口，
   且系统是 Windows。
6. **增量迭代** —— 再抓一轮 → 看差异 → 合并 → 重出代码，不用推倒重做；这一轮没抓到的接口
   只标记「本轮未见」，**永不自动删除**。
7. **记录时即脱敏** —— JSON / 表单体里的凭据值当场抹掉，但保留长度与形态，
   便于判断「这是不是密文」。
8. **可导出「用户态分发包」** —— 给同事的那份只能调用与只读诊断，改不了工具集。

### 做不到

| 做不到 | 说明 |
|---|---|
| **上传文件** | 文件上传的请求体既不提取参数、也不脱敏；附件内容不会被分析 |
| **实时推送** | WebSocket 只记录「建立了连接」，推送内容不采集；流式响应也无专门处理 |
| **文件下载** | 下载与普通响应同样对待，不区分、不落盘 |
| **GraphQL** | 当普通接口处理，不展开查询语义 |
| **二进制接口** | protobuf 之类的响应不解码，拿不到结构化字段 |
| **大接口的响应结构** | 响应超过 256 KB 会被整条丢弃（不是截断），因此拿不到响应结构 |
| **纯 Cookie / SSO 站点自动续期** | 这类站点没有自动重登录，过期要重新授权一次 |
| **没有桌面的机器** | 抓包与登录必须弹出真实浏览器窗口 |

### 有条件的

- **只有你操作过的功能才会出现** —— 没点过的接口不会被猜到。
- **用账号密码登录时，账号密码会被明文写进登录态文件** —— 它只该留在你自己的电脑上，
  不要提交、同步、截图或分享。
- **记录不会自动清理** —— 抓包记录只追加、没有自动轮转，长会话会持续变大。
- **不提供验证码 / 登录加密的逆向或绕过** —— 遇到就走交互式授权。

---

## 它是怎么做到的

一句话：**它陪你打开一个真实浏览器，记录你做的每一次操作，再把它们整理成工具。**

中间发生了什么不用你操心 —— 那是 AI 的事。

> 想了解技术实现（接口归一化、凭据脱敏范围、加密识别、生成器能力、环境变量、
> 21 个工具的完整清单、平台矩阵、已知边界），见文末 **[深入了解](#深入了解)**。

---

## 常见问题

| 问题 | 回答 |
|---|---|
| 我需要会编程吗？ | 不需要。全程对话 + 在浏览器里操作。 |
| 我的账号密码安全吗？ | **登录态文件是明文的**（本机 `auth_states/` 目录下的 json；用账号密码登录时，账号密码也会一并写入），所以它只能留在你自己的电脑上，**不要提交、同步、截图或分享**。抓包时 JSON / 表单体里的凭据值会被抹成 `***`，但 **URL 与响应体不脱敏**；生成的项目里凭据是加密保存的（仅 Windows）。完整说明见技术文档「安全设计」（见文末[深入了解](#深入了解)）。 |
| 数据会上传到云端吗？ | 不会。所有记录都在你电脑的数据目录里（`~/.webapiextractor`）。 |
| 支持哪些系统？ | 只要你能用浏览器登录并操作，就能做 —— 包括需要验证码、短信验证、单点登录的内部系统（这类站点走交互式授权，**登录态过期要重新授权一次**，不会自动续期）。 |
| 能做多复杂的功能？ | 取决于你在浏览器里点过什么。上传文件、WebSocket 推送、GraphQL、二进制接口这几类不做，见上文「它做不到什么」。 |
| 生成的工具只能我自己用吗？ | 也可以把分发包给同事；拿到的人只能调用，不能修改工具集。 |
| 系统改版了怎么办？ | 再操作一遍，让 AI 补上变化的部分，不用重做。 |
| 数据会一直变大吗？ | 会。抓包记录只追加、不会自动清理，长会话需自行清理数据目录。 |
| 非 Windows 能用吗？ | 能跑，但凭据加密不可用（只在内存里，重启要重新登录），并且必须有桌面环境。逐项差异见技术文档「平台矩阵」。 |
| 这是 Skill 还是 MCP？ | 你不用区分。它底层是一个 MCP 服务，上层是 Agent 可调用的技能 —— 导入技能就能用。 |

---

## 深入了解

上面讲的是「你能得到什么」；**技术细节、能力边界与安全语义**全部在技术文档里：

📄 **[docs/reference.md](https://github.com/SH-DaWushi/web-api-extractor/blob/main/docs/reference.md)**
—— 技能文件夹里的 `docs/reference.md`，同一份文件。

| 你想知道 | 对应章节 |
|---|---|
| 一共 21 个工具分别是什么、各自要什么参数 | 「工具清单」「工具参数速查」 |
| 哪些系统 / 功能做不了 | 「能力边界（做不到什么）」 |
| Windows、macOS、Linux 各支持到什么程度 | 「平台矩阵」 |
| 凭据和数据到底怎么存、脱敏到哪一步为止 | 「安全设计」 |
| 登录态过期怎么办、什么时候会自动重登录 | 「续期语义」 |
| 数据存在哪、会不会越积越大 | 「数据目录与环境变量」 |
| 打不开接口 / 工具报错怎么办 | `runbook/99-troubleshooting.md`（技能内的排错速查） |
| 自己搭环境、命令行驱动、改代码（给技术同事） | 「安装形态」「启动服务」「测试」 |

> 环境准备、服务启动、命令行驱动**都不是使用者要做的事** —— 装上技能后由 AI 自己处理；
> 技术文档里写它们，是为了给要自己动手的技术人员。

---

## 许可说明

本项目的使用边界与授权约束以 [LICENSE](LICENSE) 为准：

- 允许个人学习、测试和非商业自用
- 修改后再分发须保留原始来源说明
- 基于本项目开发的衍生工作应当开源
- 不允许直接商用

## 免责声明（适用范围）

本项目仅用于合法合规的开发、测试、接口分析、文档生成、集成验证与合规评估场景，目的在于帮助使用者研究、理解和管理**自己拥有授权的系统**接口行为。

使用者必须遵守中华人民共和国法律法规及当地适用法律，并自行确认其使用行为的合法性。下列用途均不被视为本项目的合法用途：

- 用于未经授权的系统探测、攻击、绕过认证、破坏服务可用性或违反网站/平台使用条款的行为
- 用于窃取、泄露、篡改、篡用他人数据或敏感信息
- 用于非法访问、非法抓取、非法分析或非法加工受保护的接口与数据
- 用于造成目标系统宕机、服务中断、拒绝服务或其他损害他人合法权益的行为
- 用于任何违反适用法律、合同、行业规范和安全要求的目的

本项目不对使用者的任何行为承担责任。将本项目用于外部系统时，使用者必须事先确认具备相应授权、合法依据，并自行承担安全与合规责任。