340 lines
28 KiB
Markdown
340 lines
28 KiB
Markdown
# universal-web-api 项目分析与后续开发方向(2026-09)
|
||
|
||
> 分析日期:2026-09-26 · 基准:`main@6209bdf`(已合并 P1+P2 安全修复)· `VERSION=3.0.0`(最新 Release 为 2.10.0)
|
||
>
|
||
> 范围:架构梳理、工程现状体检、用户反馈与竞品对照、战略定位与路线图。**本轮只做分析,未修改任何业务代码。**
|
||
>
|
||
> 验证口径:沙盒内轻量检查(pytest 纯逻辑子集、compileall、ruff 语法/未定义名、`node --check`),
|
||
> 以及对 `fix/review-p1-p2-b` 分支的**无提交试合并**。未安装 Playwright/Chromium,未运行浏览器 E2E,未截图,未压测。
|
||
> 站点可用性相关结论均为静态推断。
|
||
|
||
---
|
||
|
||
## 0. 一页结论
|
||
|
||
**定位**:本机运行的"已登录 AI 网页 → OpenAI / Anthropic 兼容 API"桥接工具。实际上它已经长成了一个面向 AI 网页的
|
||
**可配置浏览器自动化平台**:工作流 DSL、命令引擎、标签页池、路由组,外加 Site / Workflow / Operations 三个可视化 Studio。
|
||
|
||
**成熟度判断**:功能面在同类项目中领先(12 个站点、3 套协议、网络+DOM 双通道抓取、可视化适配),
|
||
但**工程化明显落后于功能**:没有 CI、Release 靠手工打包、测试资产没有全部入库、巨型类多、行尾混乱导致社区 PR 基本无法合并。
|
||
|
||
**当前最该做的 6 件事**(详见 §6 阶段 0):
|
||
|
||
1. **合并 `fix/review-p1-p2-b`**:P3 的 16/17 项已在该分支完成(18 个提交),尚未进入 main。试合并只有 1 处文档冲突,合并后 **691 passed / 63 skipped / 0 failed**。
|
||
2. **发布阻断项**:`start.py:1490` 用了只有 **Python ≥ 3.12** 才能解析的 f-string 写法,而 README 声明支持 3.10+。
|
||
`start.bat` 检测到 PATH 里有 `python` 就直接执行 `python start.py`,不检查版本。结果是默认 Python 为 3.10/3.11 的用户
|
||
(Windows、Ubuntu 22.04、Debian 12 等)一启动就报 SyntaxError。该行 2026-09-24 引入,**还没进入任何 Release,必须在 3.0.0 发布前修掉**(P3 分支也还没修)。
|
||
3. **CI + 自动化发包**:避免 #25(2.9.8 发布包漏了 `static/js/`,面板一直卡在"加载中")这类事故再次发生;同时统一版本号,清理误打的 `3.7.5` 标签。
|
||
4. **测试资产入库**:`tests/` 在 `.gitignore` 里默认忽略、只放行白名单,导致 CHANGELOG-3.0.0 列出的约 10 个测试文件(`test_stream_snapshot.py`、`test_cdp_hygiene.py`、`test_idle_maintenance.py`……)**从未提交过**。
|
||
5. **统一行尾**:41 个文件在同一文件内混用 CRLF 和 LF,统一后才能重新打开社区贡献通道。
|
||
6. **把"站点适配器"当作独立产品线来做**:Schema、版本、独立热更新通道、金标测试、健康巡检。这是本项目相对竞品真正的护城河,也是用户痛点最集中的地方(#20、#24)。
|
||
|
||
**不建议投入**:继续扩大验证码/Turnstile 自动通过、指纹伪装、代理轮换这类规避能力(原因见 §3.5、§6.5)。
|
||
|
||
---
|
||
|
||
## 1. 项目画像
|
||
|
||
| 维度 | 数据 |
|
||
| --- | --- |
|
||
| 仓库 | `lumingya/universal-web-api`,AGPL-3.0,公开;446★ / 101 forks |
|
||
| 历史 | 2025-12-17 创建;main 262 个提交(所有分支合计 280),基本由维护者一人完成;2026-09 单月 67 个提交 |
|
||
| 发布 | 共 66 个 Release(从 0.1 到 2.10.0),近 6 个月 30 个,约每周一版;资产累计下载约 2.1k 次 |
|
||
| 规模 | `app/`:171 个 Python 文件,约 10.9 万行;测试约 1.6 万行;前端 JS 约 3.3 万行(无构建),CSS 约 1.1 万行;`config/sites.json` 7311 行 / 271KB |
|
||
| 技术栈 | FastAPI 0.109 + Uvicorn + Pydantic v2;DrissionPage 4.1(通过 CDP 驱动有头 Chromium);Vue 3 全局构建 + 浏览器端 Tailwind Play CDN;数据用 JSON 文件持久化 |
|
||
| 协议 | OpenAI:Chat Completions、Responses(实验)、Models;Anthropic:Messages、count_tokens;共 149 个 HTTP 路由 |
|
||
| 站点 | ChatGPT、DeepSeek、Gemini、Claude、Kimi、Qwen、Grok、豆包、AI Studio、Arena、GLM、MiMo(12 个,另有 `_global`) |
|
||
| 平台 | Windows 支持最完整;macOS/Linux 可用核心功能;目前只支持单浏览器实例、单 Profile |
|
||
|
||
---
|
||
|
||
## 2. 架构解析
|
||
|
||
### 2.1 分层
|
||
|
||
```mermaid
|
||
graph TD
|
||
C[客户端 SDK / Agent] --> API[API 层 app/api<br/>OpenAI · Anthropic · Responses · 管理接口]
|
||
API --> RM[请求生命周期 RequestManager<br/>排队 · 取消 · 历史]
|
||
RM --> WF[浏览器工作流 BrowserWorkflowMixin]
|
||
WF --> POOL[标签页池 TabPoolManager / TabSession<br/>路由组 · 冻结 · CDP 回收 · 等待上限]
|
||
WF --> EXE[工作流引擎 WorkflowExecutor + flow_runtime DSL]
|
||
WF --> TR{request_transport}
|
||
TR -->|workflow| UI[模拟输入 / 点击 / 粘贴 / 附件]
|
||
TR -->|page_fetch| PF[页面内 fetch 直连<br/>DeepSeek、Kimi profile]
|
||
UI --> CAP[输出捕获]
|
||
PF --> CAP
|
||
CAP --> NM[NetworkMonitor + 17 个站点解析器]
|
||
CAP --> SM[StreamMonitor 页面快照 + 提取器]
|
||
CAP --> MEDIA[媒体管线:白名单 + 嗅探 + 落盘]
|
||
API --> TOOLS[工具调用:提示注入 · 解析 · Schema 校验 · 修复重试]
|
||
CMD[命令引擎:定时 / 触发式自动化] --> POOL
|
||
CFG[ConfigEngine:sites.json · 预设 · 本地覆盖] -.-> WF
|
||
STUDIO[控制台 + Site / Workflow / Operations Studio] --> API
|
||
START[start.py 启动器 · 重启交接代理 · updater] -.-> API
|
||
```
|
||
|
||
### 2.2 一次 `/v1/chat/completions` 请求的路径
|
||
|
||
1. `chat.py` 校验请求并解析路由(域名 / 预设 / 标签页 / 精确 URL / 路由组),把工具定义转成提示词。
|
||
2. `RequestManager` 创建上下文并排队;`TabPoolManager.acquire*` 分配会话。等待队列有总量上限,满了返回 503(可重试)。
|
||
3. `BrowserWorkflowMixin` 读取预设,`_build_prompt_from_messages` 把**全部 messages 扁平化为 `role: text` 文本**,超长时改用文件粘贴,然后按工作流 DSL 执行(新建对话 → 填充 → 发送 → `STREAM_WAIT`)。
|
||
默认每次都新建网页对话;开启时间阈值复用会话后,仍然会**重复发送完整历史**。
|
||
4. 输出捕获:优先走网络监听加站点解析器,不满足条件时回退到 DOM 快照;媒体经过白名单和内容嗅探后落盘。
|
||
5. `sse_formatter` 按协议组装 SSE 或 JSON。工具调用从文本中解析出来,经 Schema 校验,必要时修复重试。
|
||
|
||
### 2.3 子系统体量
|
||
|
||
| 子系统 | 约行数 | 代表文件 |
|
||
| --- | --- | --- |
|
||
| 工作流引擎 | 13.9K | `workflow/executor*`、`text_input.py`(2122)、`attachment_monitor.py` |
|
||
| API 层 | ~16K | `tab_routes.py`(5142)、`chat.py`(3326)、`config_routes.py`、`system.py` |
|
||
| 命令引擎 | 9.2K | `command_engine.py`(3870,132 个方法)、`command_engine_actions.py`(3166) |
|
||
| 媒体 | 8.4K | `browser/media.py`(3226)、`extractors/media_extractor.py`(3253) |
|
||
| 解析器 | 7.1K | 17 个 `*_parser.py` |
|
||
| 标签页池 | ~6K | `tab_pool_parts/manager.py`(4567,136 个方法)、`session.py` |
|
||
| 工具调用 | 3.4K | `tool_calling_parse.py`、`tool_calling_validation_retry.py` |
|
||
| Arena 专项 | 20 个文件,10.3K | `arena_*` 服务、5 个 lmarena 解析器 |
|
||
|
||
### 2.4 核心资产判断
|
||
|
||
- **真正的护城河**是"配置驱动的站点适配器"(选择器 + 工作流 DSL + 流配置 + 解析器)以及围绕它的可视化工具链。协议层和标签页池是通用能力,竞品也有。
|
||
- **最大的不稳定来源**同样是适配器:站点前端改版(哈希类名,例如 DeepSeek 预设里的 `div._5a8ac7a`、`._7436101.bcc55ca1`)或者接口格式变化(#20、#24)。
|
||
- Arena 专项代码约占十分之一,而且集中了规避类能力,和"通用"的定位有偏离。
|
||
|
||
---
|
||
|
||
## 3. 工程现状体检
|
||
|
||
### 3.1 做得好的地方
|
||
|
||
- 协议覆盖广:OpenAI、Anthropic、Responses 三套,六种路由写法;同时接受 `Authorization` 和 `x-api-key`。
|
||
- 网络和 DOM 双通道抓取,带自动回退;`page_fetch` 传输模式为后续"少模拟、多直连"打下了基础。
|
||
- 3.0.0 的性能重构有量化数据:每次轮询的 CDP 命令从约 138 条降到 1 条,已移除 DOM 残留从 6007 个降到 7 个,LMArena 解析快约 125 倍。所有改动都带回退开关,这个做法值得延续。
|
||
- 2026-09 完成安全加固:P1(6)、P2(15) 全部修复,约 118 项回归测试;认证和 CORS 改为 fail-closed,媒体走白名单,SSRF 加了 DNS pinning,交接代理可以防请求走私。
|
||
- 自动更新做了 SHA-256 校验、ZIP 路径/体积/压缩比限制,失败可回滚。
|
||
- Studio 和教程完善,非开发者也能上手。
|
||
|
||
### 3.2 分支与合并状态(重要)
|
||
|
||
| 分支 | 内容 | 状态 |
|
||
| --- | --- | --- |
|
||
| `main@6209bdf` | P1+P2 修复,并融合了 S2/S4/S6 | 线上 |
|
||
| `origin/fix/review-p1-p2-b` | 基于 `c562a48` 另开的 **18 个提交**:P3 16/17 项(B4、B6、B7、S7、S14、H2、H3、H5、H6 计划、H7、H8、H10、H11、H13、H14、T2)以及 `test_review_fixes_p3.py` | **未合并**;只有 H4(行尾)等待决定 |
|
||
|
||
无提交试合并(`git merge --no-commit`)的结果:
|
||
|
||
- 只有 `docs/review/DEVLOG-fixes-2026-09.md` 一处冲突,`main.py` 自动合并。
|
||
- 合并后的测试:**691 passed / 63 skipped / 0 failed**(main 是 652 / 63)。
|
||
- 合并后 ruff(py310)剩下 `start.py` 的 f-string 语法问题(P3 未覆盖),以及测试文件里一处 `BaseExceptionGroup`(3.11+)。
|
||
|
||
### 3.3 本次新发现或复核的问题
|
||
|
||
| # | 级别 | 问题 | 证据 |
|
||
| --- | --- | --- | --- |
|
||
| N1 | **高(发布阻断)** | `start.py:1490` 在 f-string 内复用外层引号(PEP 701),只有 3.12+ 能解析。README 写 3.10+,`start.bat` 回退路径和 `start.py` 自检只要求 ≥3.8,`start.bat` 首选路径根本不检查版本 | `ruff --target-version py310` 报 invalid-syntax;`git blame` 指向 `270e814`(2026-09-24),不在 2.10.0 中 |
|
||
| N2 | 高 | 没有任何 CI(Actions 工作流数为 0),Release 手工打包:#25(漏 `static/js/`)、#9(Release 与 git 不同步);资产命名多次变化 | GitHub API |
|
||
| N3 | 高 | `tests/` 采用白名单入库,v3.0.0 的约 10 个测试文件和 `_real_browser.py`、两个 e2e 脚本从未提交。CHANGELOG 写"900 项通过",main 实际可收集 715 项(合并 P3 后 754 项) | `git log --all -- tests/<name>` 为空 |
|
||
| N4 | 中 | 存在误打的 `3.7.5` 标签(指向 2026-04-02 的市场投稿提交),按语义版本比 3.0.0 还"新",会误导按标签取版本的工具和后续自动发包 | `git tag` |
|
||
| N5 | 中 | 行尾:41 个文件同一文件内混用 CRLF/LF,39 个纯 CRLF,没有 `.gitattributes`。社区 PR #16/#17/#18(+3.8K 到 +7.3K 行)和 #21(+1679/-859)因噪音 diff 未合并,维护者只能手工吸收思路;只有 +38 行的 #26 被合并 | 统计脚本 |
|
||
| N6 | 中 | 主流解析器(chatgpt、claude、deepseek、gemini、kimi、qwen、aistudio、glm)在测试里**零引用**;没有 `/v1/messages`、Responses 的协议一致性测试 | grep |
|
||
| N7 | 中 | 测试入口不唯一:`python -m unittest discover` 绕过 `conftest.py`,出现 6 个失败、20 个错误;部分 browser 模块在顶层 `import playwright`,裸跑 `pytest tests` 在收集阶段就失败;没有 `pyproject.toml` 和 pytest 配置 | 实测 |
|
||
| N8 | 中 | DrissionPage 的许可证是"仅限学习和合法非盈利目的,商用需授权,不得用于可能有损他人利益的项目,遵守 Robots 协议,违反即失效",与 AGPL-3.0 赋予的自由有冲突。另外 `patch_drissionpage.py`(972 行)会直接改写 site-packages 里的源码,而依赖范围 `<5.0.0` 太宽:4.2.0 已发到 b20,5.0.0 也进入了 beta。4.2.0 正式版一发布就会被自动安装,字符串补丁随时可能失配 | 许可证原文、补丁脚本、PyPI |
|
||
| N9 | 中 | 配置蔓延:代码直接读取约 126 个环境变量(153 处 `os.getenv`),其中约 69 个不在 `.env.example` 里;前端 `dashboard-schema.js` 又维护了一份默认值 | 粗略统计 |
|
||
| N10 | 中 | 依赖陈旧:FastAPI 0.109.2(最新 0.141.1)、Starlette 0.36.3(最新 1.7.0)、Uvicorn <0.30(最新 0.54.0),没有锁文件。P3 分支已有升级计划和新版试跑结果(`docs/review/DEPENDENCY_UPGRADE_PLAN.md`) | PyPI |
|
||
| N11 | 低 | 巨型类:TabPoolManager 136 个方法、CommandEngine 132、ConfigEngine 93、RequestManager 90、NetworkMonitor 88;另有 1454 处 `except Exception` 和 164 处 `time.sleep` 轮询 | AST 统计 |
|
||
| N12 | 低 | 残留:`app/core/browser.py` 被同名包遮蔽,从不生效;插件市场代码 2026-07 已删除,但 `upload_url` 还指向不存在的 issue 模板;性能文档引用的 `refactor_report.md`(Layer 1–3 规划)不在仓库中 | — |
|
||
| N13 | 低 | 前端在浏览器里运行 Tailwind Play CDN(407KB JIT 编译器,控制台会提示不要用于生产),没有构建和模块化;`?v=` 缓存戳混乱,路径混用相对和绝对写法 | `static/index.html` |
|
||
| N14 | 低 | 提交信息:main 的 262 个提交中有 153 个标题只写了"更新",不利于追溯和自动生成 CHANGELOG | git log |
|
||
|
||
### 3.4 P3 状态
|
||
|
||
合并 `fix/review-p1-p2-b` 后,P3 只剩 **H4 行尾统一**。建议的执行方式:先合并 P3 分支,再**单独做一次**
|
||
`.gitattributes` + `git add --renormalize .` 的提交,提交信息写清楚"仅行尾",并在 `.git-blame-ignore-revs` 里登记这次提交,避免污染 blame。
|
||
|
||
### 3.5 合规与供应链风险
|
||
|
||
- **规避类能力**:`cf_turnstile_solver.py`(Turnstile / 5 秒盾自动点击)、`human_mouse.py`(拟人鼠标轨迹)、`arena_proxy_rotation.py`(Clash 节点轮换)、预设里的 `stealth` 和 `prompt_padding`(随机填充)。
|
||
这类能力最容易违反目标站点条款,也有被代码托管平台处理的风险,而且和 README "这不是绕过验证码或访问控制"的说法相矛盾。
|
||
- **自动更新的信任根**:updater 校验的是 GitHub 记录的资产摘要,能发现传输损坏,但**防不住仓库或令牌被盗后上传的恶意 Release**。所有开了自动更新的用户,其安全都取决于仓库凭据的安全。
|
||
- **协作令牌**:AI 或自动化协作时应使用只授权本仓库 `contents:write`、有效期短的细粒度令牌,用完即撤销;main 应配置规则集(禁止强推,要求 CI 通过)。
|
||
|
||
---
|
||
|
||
## 4. 用户反馈与竞品对照
|
||
|
||
### 4.1 Issue / PR 信号(21 个 Issue、5 个 PR,全部已关闭)
|
||
|
||
| 类别 | 代表 | 含义 |
|
||
| --- | --- | --- |
|
||
| 站点适配失效 | #20 DeepSeek 搜索时回复为空;#24 Grok 流式抓取失败 | 修复要等下个 Release,或让用户手改 JSON,**时效差** |
|
||
| 发布质量 | #25 发布包漏 `static/js`;#9 Release 与 git 不同步 | 需要 CI 和清单校验 |
|
||
| 部署 | #22 请求 Docker(同类项目基本都有) | 关闭时没有回复,需求仍在 |
|
||
| Agent 场景 | #3 CrewAI 长提示词超时(16 条评论);#7 工具调用 | 长上下文、首包等待、工具调用的可靠性 |
|
||
| 生态 | 9 个"[市场投稿]"issue(含 3 个测试) | 用户有分享预设的意愿,但市场功能已下线 |
|
||
| 贡献 | 5 个外部 PR 只合并了 1 个 | 行尾噪音和巨型文件抬高了合并成本 |
|
||
|
||
### 4.2 同类项目对照(信息来自各自 README)
|
||
|
||
| 能力 | 本项目 | [WebAI-to-API](https://github.com/Amm1rr/WebAI-to-API) | [AIstudioProxyAPI](https://github.com/CJackHwang/AIstudioProxyAPI) | [Chat2API-web](https://github.com/LeeSpo/Chat2API-web) | [ai-web2api](https://github.com/yaohuiwu/ai-web2api) |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 接入方式 | DOM 自动化 + 页面内 fetch | WebAPI / Playwright | Playwright + Camoufox | 网页账号凭据直连 | Playwright DOM 自动化 |
|
||
| 多站点通用配置 | ✅ 12 站,可视化新增 | 以 Gemini 为主 | 仅 AI Studio | 多站点(内置 provider) | 3 站,YAML 选择器 |
|
||
| 可视化工作流/选择器编辑 | ✅ **独有** | — | — | — | DOM 调试接口 |
|
||
| Anthropic / Responses | ✅ / 实验 | — | — | Responses ✅ | — |
|
||
| 工具调用 | 模拟 + Schema 修复重试 | — | auto / native / emulated 三模式带回退 | ✅ | 提示注入 |
|
||
| Docker / 无显示器部署 | ❌ | ✅ | — | ✅ | MJPEG 实时画面 + 登录态导入 |
|
||
| 多账号 / 多 Profile 路由 | ❌ | — | Profile 轮换 | 轮询 / 填满 / 故障转移 | 多 context |
|
||
| 长任务控制 | 取消 / 超时 / 等待上限 | 就绪端点 | — | 上下文压缩、keep-alive、准入队列 | — |
|
||
|
||
### 4.3 结论
|
||
|
||
- **差异化优势**:通用性,加上可视化适配工具链,加上双通道抓取。
|
||
- **短板**:部署形态(Docker、远程登录画面)、多账号池、适配器的分发与自愈、工程可信度(CI、测试、发布)。
|
||
|
||
---
|
||
|
||
## 5. 战略定位与北极星
|
||
|
||
### 5.1 三条可选路线
|
||
|
||
| 路线 | 内容 | 评价 |
|
||
| --- | --- | --- |
|
||
| A. 本机 AI 网页网关 | 深耕现有能力:协议兼容、稳定性、Agent 体验 | **主干**,用户基础在这里 |
|
||
| B. AI 网页自动化平台 | 把工作流和命令开放成可编程接口,接入 MCP | 以较低成本延伸,复用现有工作流引擎 |
|
||
| C. 适配器生态 | 社区贡献站点适配器,建注册表、签名分发 | **增长引擎**,同时把维护压力分摊给社区 |
|
||
|
||
**建议**:以 A 为主干,C 作为增长引擎,B 通过 MCP 适度延伸。
|
||
|
||
### 5.2 北极星指标
|
||
|
||
1. **适配器 MTTR**:从站点改版导致失效,到修复送达用户的中位时长。目标 < 24 小时,依赖 §6.2 的独立更新通道。
|
||
2. **Agent 场景一次成功率**:长提示词加工具调用的请求,无需重试就成功的比例。
|
||
|
||
---
|
||
|
||
## 6. 路线图
|
||
|
||
**指导原则**:① 先保证可交付,再加新功能;② 适配器就是数据,也是产品;③ 用契约测试做护栏,保证无浏览器也能在 CI 跑;
|
||
④ 渐进式重构,接口先行,每一步都能用开关回退(延续 3.0.0 的做法);⑤ 不扩大规避能力。
|
||
|
||
### 6.1 阶段 0:止血与发布工程(1–2 周)
|
||
|
||
| ID | 事项 | 验收标准 |
|
||
| --- | --- | --- |
|
||
| R0-1 | 合并 `fix/review-p1-p2-b`(解决 DEVLOG 冲突),然后删除该分支 | main 测试 ≥ 691 通过、0 失败 |
|
||
| R0-2 | 修复 N1:改写 `start.py:1490`;四处最低版本统一为 3.10(start.bat 快速路径加版本检查、start.py 自检、README、requirements 注释) | `ruff --target-version py310` 没有 invalid-syntax;CI 覆盖 3.10–3.13 |
|
||
| R0-3 | GitHub Actions:ruff(E9/F821/F811)+ compileall + `node --check` + `pytest -m "not local_fixture"`,Windows、Ubuntu × Python 3.10 / 3.12 / 3.13 | PR 必须通过 CI 才能合并 |
|
||
| R0-4 | 自动发包:打标签后用 `git archive` 生成 zip → 清单校验(`static/js` 存在、VERSION 与标签一致、不含 `chrome_profile` 和 `.env`)→ 上传 → 生成构建证明(artifact attestation);删除或更名 `3.7.5` 标签 | #25、#9 类问题不再出现 |
|
||
| R0-5 | 测试入库:`.gitignore` 从白名单改为黑名单,补交 v3.0.0 的测试;新增 `pyproject.toml`(pytest markers:`browser` / `real_browser` / `local_fixture`,默认排除浏览器测试);browser 模块改用 `pytest.importorskip("playwright")` | 直接运行 `python -m pytest` 即可 |
|
||
| R0-6 | H4 行尾统一(单独提交,并登记到 `.git-blame-ignore-revs`) | 混用行尾的文件数为 0 |
|
||
| R0-7 | 发布 3.0.0,附迁移说明和回退开关表;此后 README 的版本号由脚本或测试保证与 VERSION 一致(P3 已加测试) | Release 与 main 一致 |
|
||
| R0-8 | 仓库安全:细粒度最小权限令牌、main 规则集、维护者账号开启 2FA | — |
|
||
|
||
### 6.2 阶段 1:适配器工程化(1–2 个月),核心护城河
|
||
|
||
| ID | 事项 | 说明 |
|
||
| --- | --- | --- |
|
||
| R1-1 | 站点适配器 Schema v1 | 为 preset 的 selectors、workflow、stream_config、file_paste、image_extraction、request_transport 定义 JSON Schema 和 `schema_version`,保存、导入、CI 三处都做校验;迁移复用 `docs/migrations` 的机制 |
|
||
| R1-2 | 拆分 271KB 的 `sites.json` | 改为 `sites/<domain>.json`,每个站点独立带 `adapter_version`、`min_app_version`、`last_verified`,运行时合并。这样能减少冲突,审阅也更方便 |
|
||
| R1-3 | 适配器独立更新通道 | 不发整包就能热更新站点配置:发布带签名或摘要的适配器索引,客户端校验后合并,并保留本地覆盖。#24 这类修复可以从"等下个版本或手改 JSON"缩短到小时级。插件市场也可以在此基础上改用 PR 审核(而不是 issue 投稿)重新上线 |
|
||
| R1-4 | 解析器金标测试 | 为 17 个解析器录制脱敏后的网络流样本(SSE / NDJSON / JSON),断言正文、思考过程、图片和结束标志;新增站点必须附带样本 |
|
||
| R1-5 | 协议一致性测试 | 用官方 openai、anthropic Python SDK 作为客户端,对接"假浏览器后端",覆盖流式和非流式、工具调用、usage、错误码、Anthropic 事件顺序、Responses 续接 |
|
||
| R1-6 | 适配器健康巡检 | 每个站点做低成本自检:页面可达、登录态、关键选择器能命中,全程不发消息;合成请求只在用户显式开启时执行。结果接入 `/v1/provider/status` 和面板,失败时直接提示"选择器失效 / 需要登录 / 被验证页拦截" |
|
||
| R1-7 | 选择器韧性 | 优先使用语义锚点(role、aria、占位文本、结构关系)代替哈希类名;支持候选列表和打分;Site Studio 根据 DOM 给出修复建议,**人工确认后才生效** |
|
||
|
||
### 6.3 阶段 2:架构演进,对应 Layer 1–3(2–4 个月)
|
||
|
||
| ID | 事项 | 说明 |
|
||
| --- | --- | --- |
|
||
| R2-1 | 浏览器驱动接口 `BrowserDriver` | 抽象 run_js、run_cdp、find、click、type、listen、screenshot。先用 DrissionPage 实现,再评估 Playwright `connect_over_cdp`(Apache-2.0)或自研的薄 CDP 客户端。把 `patch_drissionpage.py` 的监听增强收进项目自己的网络层,不再改写第三方源码,也解决许可证的不确定性(N8)。改造前先把 DrissionPage 版本锁死 |
|
||
| R2-2 | 统一内部请求模型 | OpenAI、Anthropic、Responses(以及以后的 MCP)都先翻译成同一个 ChatJob;`chat.py` 和 `anthropic_routes.py` 退化为薄的协议适配层 |
|
||
| R2-3 | 拆解巨型类 | TabPoolManager 拆成分配器、路由组、恢复、维护;CommandEngine 拆成存储、调度、触发器、动作插件;ConfigEngine 拆成仓储、校验、迁移;`tab_routes.py` 按资源拆分 |
|
||
| R2-4 | 类型化配置 | 以 pydantic-settings 作为单一事实源,自动生成 `.env.example`、面板 schema 和文档;启动时校验,并打印脱敏后的生效配置(解决 N9) |
|
||
| R2-5 | 持久化 | 请求历史、命令结果、统计改用 SQLite(WAL 模式)替代 JSON 文件,支持查询和保留策略 |
|
||
| R2-6 | 进程模型 | 可选把浏览器 worker 和 API 进程分开,通过队列通信:崩溃互相隔离,API 重启不中断,也能简化现有的交接代理 |
|
||
| R2-7 | 可观测性 | 提供 `/metrics`(Prometheus)、结构化日志,以及贯穿 API → 标签页池 → 工作流 → 解析器的请求 ID;收窄 `except Exception`,统一错误分类(延续 `error_metadata`) |
|
||
| R2-8 | 前端工程化 | 预编译 Tailwind CSS,去掉 407KB 的浏览器端编译器;改用 ES Modules;拆分 3315 行的 `dashboard-methods.js`;引入不依赖浏览器的 Node 端逻辑测试(jsdom) |
|
||
|
||
### 6.4 阶段 3:能力扩展(3–6 个月以上)
|
||
|
||
| ID | 方向 | 说明 |
|
||
| --- | --- | --- |
|
||
| R3-1 | 官方 Docker 镜像 | Chromium + Xvfb + noVNC 或实时画面用于登录;Profile 和 config 挂载为卷;提供 docker-compose,支持 amd64 和 arm64(回应 #22) |
|
||
| R3-2 | 多 Profile / 多账号池 | 支持多个浏览器实例或多个 Profile,路由策略包括轮询、填满、故障转移;每个账号单独设并发和冷却时间,**遵守各站点的使用限制** |
|
||
| R3-3 | 会话亲和与增量发送 | 用消息前缀哈希关联网页会话:如果客户端历史是上一次请求的前缀,就只发新增的轮次,否则回退到全量。这样长对话的粘贴量和首字延迟都会明显下降(对应 §2.2 第 3 点) |
|
||
| R3-4 | Agent 长上下文策略 | 按站点的上下文上限,自动在"直接输入 / 文件粘贴 / 压缩摘要"之间选择;首包等待期间发送 SSE keep-alive;为 Claude Code、Codex、CrewAI 给出超时配置建议(#3) |
|
||
| R3-5 | 工具调用 2.0 | 站点有原生能力时走 native,否则用 emulated 加 Schema 约束修复;支持流式 tool_call 增量;建一个小型评测集,按站点输出工具调用成功率 |
|
||
| R3-6 | MCP 服务端 | 按 MCP 2026-07-28 规范(Streamable HTTP)把"向某站点提问 / 执行某个工作流"暴露为工具,长任务用 Tasks 扩展,让 IDE 和 Agent 可以直接调用 |
|
||
| R3-7 | 插件 SDK | 解析器、提取器、传输以 entry-point 插件的形式发布,并声明自身能力;自定义代码默认在独立的低权限子进程中运行,取代进程内 AST 过滤 |
|
||
| R3-8 | 国际化 | 控制台提供英文界面,建立文档站点,扩大非中文用户群 |
|
||
|
||
### 6.5 明确不建议
|
||
|
||
- 扩大验证码 / Turnstile 自动通过、浏览器指纹伪装、为规避限流而做的 IP 轮换。现有相关模块建议默认关闭,拆成可选组件并写清责任边界,长期考虑移出默认发行包。
|
||
- 面向公网的多租户网关或计费转售。这和"单机调试工具"的安全模型、目标站点的条款都有冲突。
|
||
- 以"免费无限调用"作为卖点宣传。
|
||
|
||
---
|
||
|
||
## 7. 优先级矩阵
|
||
|
||
| 优先级 | 事项 | 价值 | 成本 |
|
||
| --- | --- | --- | --- |
|
||
| P0 | R0-2 修复 3.12 语法(发布阻断) | 高 | 极低 |
|
||
| P0 | R0-1 合并 P3 分支 | 高 | 低 |
|
||
| P0 | R0-3 / R0-4 CI + 自动发包 | 高 | 低 |
|
||
| P0 | R0-5 测试入库,统一测试入口 | 高 | 低 |
|
||
| P1 | R0-6 行尾统一 | 中高(解锁社区贡献) | 低 |
|
||
| P1 | R1-4 / R1-5 金标测试 + 协议契约测试 | 高 | 中 |
|
||
| P1 | R1-1 / R1-3 适配器 Schema + 热更新通道 | 很高 | 中 |
|
||
| P1 | R1-6 健康巡检 | 高 | 中 |
|
||
| P2 | R3-1 Docker | 高(用户呼声) | 中 |
|
||
| P2 | R2-1 驱动接口 | 高(长期) | 高 |
|
||
| P2 | R2-2 / R2-3 统一请求模型 + 拆类 | 中高 | 高 |
|
||
| P3 | R3-2 / R3-3 / R3-5 / R3-6 | 中高 | 中到高 |
|
||
|
||
---
|
||
|
||
## 8. 建议跟踪的指标
|
||
|
||
- **发布**:CI 通过率、Release 清单校验通过率、Release 落后 main 的提交数。
|
||
- **适配器**:失效到修复的中位时长(目标 < 24h)、健康巡检在线率、每站点每月选择器失效次数。
|
||
- **质量**:内置解析器金标覆盖率(目标 100%)、协议一致性用例通过率、`except Exception` 数量趋势、超过 2000 行的文件数。
|
||
- **性能**:首字延迟 P50 / P95、N 次请求后渲染进程内存、每个请求的 CDP 调用次数。
|
||
- **社区**:外部 PR 合并率、Issue 首次响应时长。
|
||
|
||
---
|
||
|
||
## 9. 附录
|
||
|
||
### 9.1 本次运行的检查(Python 3.13 虚拟环境,位于工作区之外)
|
||
|
||
```text
|
||
pytest(排除 10 个需要浏览器 / Playwright 的模块)
|
||
main@6209bdf → 652 passed, 63 skipped, 0 failed(约 12s)
|
||
main + fix/review-p1-p2-b(试合并) → 691 passed, 63 skipped, 0 failed
|
||
python -m unittest discover -s tests → Ran 60, failures=6, errors=20(绕过 conftest,不是有效入口)
|
||
python -m compileall app main.py start.py updater.py → OK
|
||
ruff --select E9,F821,F822,F823,F811 --target-version py310(main)
|
||
→ 16 项:start.py f-string 语法 2 项、F821 6 项(含 1 项测试)、F811 8 项
|
||
node --check static/js/**/*.js(33 个文件)→ 全部通过
|
||
git merge-tree --write-tree main origin/fix/review-p1-p2-b → 仅 DEVLOG 冲突
|
||
```
|
||
|
||
### 9.2 数据来源
|
||
|
||
- GitHub REST API:仓库元数据、Release、标签、Issue、PR、Actions 工作流。
|
||
- PyPI JSON API:依赖的最新版本。
|
||
- DrissionPage 许可证原文:已安装包的 `dist-info/licenses/LICENSE`。
|
||
- 同类项目:[WebAI-to-API](https://github.com/Amm1rr/WebAI-to-API)、[AIstudioProxyAPI](https://github.com/CJackHwang/AIstudioProxyAPI)、
|
||
[Chat2API-web](https://github.com/LeeSpo/Chat2API-web)、[ai-web2api](https://github.com/yaohuiwu/ai-web2api)。
|
||
- MCP:[2026-07-28 规范说明](https://blog.cloudflare.com/mcp-v2/)、[版本时间线](https://hidekazu-konishi.com/entry/mcp_specification_version_timeline.html)、
|
||
[官方 Python SDK](https://github.com/modelcontextprotocol/python-sdk)。
|
||
|
||
### 9.3 本轮没有做的事
|
||
|
||
- 没有安装 Playwright / Chromium,没有运行浏览器 E2E,没有截图,没有压测。
|
||
- 没有修改任何业务代码,也没有合并分支;试合并用的是临时 worktree,已删除。
|
||
- 本文不包含任何凭据。
|