Initial commit

This commit is contained in:
Alex committed 2026-11-02 22:54:14 +08:00
commit 57fc3525eb
7311 files changed
+1291398

No files matched your search

@@ -0,0 +1,130 @@
# R2-1 BrowserDriver 接口与 R2-6 进程模型:设计与分阶段计划
> 状态(2026-09-27 更新):
> - **R2-1 已完成**:业务代码经由 `app/core/driver/` 访问浏览器,由棘轮测试保证除驱动包外零直接调用;
> - **R2-6 已实现为实验性的 process 模式**(`UWAPI_WORKER_MODE=process`),默认仍是 inproc,见 §5「实现情况」。
>
> 原设计说明如下:两项改动都会触及浏览器层的每一条路径,必须在用户本机用真实浏览器逐阶段回归。
> 为此本文把工作拆成可以独立合并、独立回滚的小步。现状数据来自 2026-09-27 对 `dev/roadmap-phase0-2` 的统计。
## 1. 为什么要做
- **许可证风险**:DrissionPage 的许可只允许非商业学习使用,而且违规即自动终止(路线图 §4)。只要浏览器调用散落在 50 个文件里,替换它的成本就高到做不了。
- **可测试性**:现在测试浏览器行为,只能起真实 Chrome,或者针对每个调用点单独打桩。有了统一接口,就可以用一个内存假驱动覆盖大部分逻辑。
- **稳定性**:浏览器卡死、崩溃会拖垮整个 API 进程(重启守护的存在就是证据)。进程拆分以后,浏览器侧出问题只需要重启 worker。
## 2. 现状清单(直接调用 DrissionPage API 的位置)
| 类别 | 调用数 | 说明 |
|------|------:|------|
| `run_js` / `run_js_loaded` | 163 | 页面内脚本:取快照、输入、点击、观察者等 |
| `run_cdp` / `_run_cdp` | 55 | CDP 命令:Input.*、Page.*、Runtime.*、Network.* |
| `ele` / `eles` | 30 | 元素查找(DrissionPage 定位语法) |
| `actions.*` / `input()` | 33 | 键鼠动作链、文本输入 |
| `listen.*` | 13 | 网络监听(集中在 `network_monitor.py`) |
| `from DrissionPage` | 7 个文件 | 类型与异常的直接导入 |
共涉及 **50 个文件**。调用最集中的是:
- `workflow/text_input.py`(34 处)
- `arena_gpt_image_command.py`(19 处)
- `command_engine_actions.py`(17 处)
- `browser/media.py`、`workflow/executor_actions.py`、`workflow/executor_interaction.py`(各 15 处)
- `media_extractor.py`、`workflow/executor.py`(各 13 处)
- `human_mouse.py`(10 处)
## 3. R2-1:接口设计
```python
class TabDriver(Protocol): # 一个标签页(对应现在的 DrissionPage tab 对象)
tab_id: str
url: str
def run_js(self, script: str, *args, timeout: float | None = None, as_expr: bool = False) -> Any: ...
def run_cdp(self, method: str, **params) -> dict: ...
def find(self, locator: str, timeout: float = 0) -> ElementHandle | None: ...
def find_all(self, locator: str, timeout: float = 0) -> list[ElementHandle]: ...
def navigate(self, url: str, timeout: float | None = None) -> None: ...
def reload(self, ignore_cache: bool = False) -> None: ...
def screenshot(self, path: str | None = None, full_page: bool = False) -> bytes: ...
def listen(self, patterns: list[str]) -> NetworkListener: ... # 流式响应捕获
def input_text(self, text: str) -> None: ... # 键盘输入(CDP Input.insertText 等)
def mouse(self) -> MouseDriver: ... # 点击、拖动、滚动
class BrowserDriver(Protocol): # 浏览器进程(对应现在的 Chromium / BrowserCore 连接)
def tabs(self) -> list[TabDriver]: ...
def new_tab(self, url: str | None = None, *, context_id: str | None = None) -> TabDriver: ...
def close_tab(self, tab_id: str) -> None: ...
def create_context(self) -> str: ... # 站点独立 Cookie(Target.createBrowserContext)
def dispose_context(self, context_id: str) -> None: ...
```
- 定位语法沿用现有规则,与 `ElementFinder` 和 `adapter_health.to_locator` 一致:
- `css:`、`xpath:`、`tag:`、`@属性` 原样传递;
- 以 `/` 或 `(` 开头的按 XPath 处理;
- 其余按 CSS 处理。
DrissionPage 实现可以直接透传;其他实现在接口层做转换。
- 异常统一为三类:`DriverDisconnected`、`ContextLost`(例如 “Cannot find context with specified id”)、`DriverTimeout`,替代现在各处对 DrissionPage 异常文本的字符串匹配。
## 4. R2-1:分阶段迁移(每一步独立提交,并在本机做真实浏览器回归)
1. **接口与 DrissionPage 实现**:新增 `app/core/driver/`,包含 `base.py`(Protocol 与异常)、`drission.py`(包装现有 tab 对象,只转发调用、翻译异常)和 `fake.py`(内存假驱动,供单测使用)。
- `TabSession` 增加 `driver` 属性(懒创建)。
- 这一步不改任何调用点,行为零变化。
2. **只读路径**:`adapter_health`、`stream_snapshot`、`media_extractor` 的快照读取。这些只查询、不交互,回归风险最低。
3. **CDP 集中点**:`human_mouse`、`browser_profile_identity`、`tab_pool_parts/pool_contexts` 的 run_cdp。
4. **交互路径**:`workflow/text_input`、`executor_actions`、`executor_interaction`、`attachment_upload`。
- 这是最关键的输入、点击、上传链路,每个子文件单独一步。
- 本机要跑 `test_text_input_atomic`、`test_attachment_browser`、真实浏览器用例,并对常用站点做手工冒烟。
5. **网络监听**:`network_monitor` 的 `listen.*`。流式捕获依赖它,最后迁移。
6. **收口**:新增测试,保证 `app/` 下除 `app/core/driver/drission.py` 以外不再直接导入 DrissionPage,也不再直接调用 `.run_js(` 或 `.run_cdp(`,即便未来加新代码也不会回退。
- 完成后,替换为 Playwright(CDP 连接模式)或直接 CDP 的实现,只需要新写一个驱动文件。
## 5. R2-6:进程模型
目标:API 进程(FastAPI 与协议转换)与浏览器 worker 进程(BrowserCore、TabPool、工作流执行)分离。
```
客户端 ─HTTP→ API 进程(uvicorn)──本地 IPC──→ 浏览器 worker(单进程,持有 CDP 连接与标签页池)
▲ │
└──── 流式事件(ChatEvent)─────┘
```
- **IPC**:优先用本机回环 HTTP 或 WebSocket(worker 监听 127.0.0.1 的随机端口,令牌通过环境变量传递)。与 multiprocessing Queue 相比,它跨平台行为一致,Windows 上也不受 spawn 限制,还能单独调试 worker。
- 流式输出直接传 R2-2 的 `ChatEvent`,这正是 R2-2 把事件类型化的原因之一。
- **边界**:API 进程只保留协议转换、鉴权、指标、配置读写;与执行相关的一切(`get_browser()`、`request_manager` 的执行部分、`command_engine` 的调度)都进入 worker。
- **生命周期**:由 `start.py` 拉起两个进程。worker 崩溃时,API 进程对进行中的请求返回 503,并请求重启 worker,不影响 API 进程本身,也不丢配置。
- 现有的「定时重启守护」可以简化为只重启 worker。
- **分阶段**:
1. 先在同一进程内,把执行入口收敛到一个可以序列化的调用面:输入是 `ChatJob` 加 `ChatRequest`,输出是 `ChatEvent` 流。
2. 把这个调用面实现为 worker 的 HTTP 端点,API 进程通过配置开关 `UWAPI_WORKER_MODE=inproc|process` 选择;默认仍是进程内。
3. 本机长时间回归通过后,再把默认改为 process。
- **依赖**:R2-1 的第 1、2 步完成后再做更稳妥,因为 worker 内部的浏览器调用最好先经过统一接口。
## 6. 需要用户配合的地方
- 每个迁移步骤合并前,在本机跑一遍真实浏览器用例;工作流相关步骤还需要对常用站点手工冒烟。改动不涉及账号,只需要已登录的受控浏览器。
- R2-6 切换默认之前,建议先以 process 模式日常使用一周。
## 7. 实现情况(R2-6)
- **启用**:在 `.env` 中设置 `UWAPI_WORKER_MODE=process`。API 进程启动时会自动拉起 worker:
- 命令是 `python -m uvicorn main:app`,只监听 127.0.0.1,端口自动选择,也可用 `UWAPI_WORKER_PORT` 指定;
- 令牌与代理密钥在启动时随机生成,API 进程退出时 worker 随之关闭。
- **职责划分**:
- worker 运行完整应用(`UWAPI_WORKER_ROLE=worker`),持有浏览器、标签页池与命令调度,另外提供 `/internal/worker/*` 接口,要求令牌正确且来源为本机。
- API 进程:协议接口(/v1、/url、/tab)在本进程完成协议转换、鉴权与计量,执行时经 `RemoteBrowserProxy` 交给 worker;所有 `/api/*` 面板请求整体转发给 worker,所以面板功能完整。
- 转发时带上 `UWAPI_PROXY_SECRET` 对应的密钥和 `X-Forwarded-For`,worker 因此看到真实的客户端地址,按来源判断的限制照常生效。
- **传输**:执行结果以 NDJSON 逐块传回,worker 约每秒发一次心跳。API 侧检测到停止请求就关闭连接,worker 随即置位 stop_checker。
- **API 进程可用的远程能力**:
- 五个 `execute_workflow*` 方法;
- 标签页池的白名单方法(get_tabs_with_index、set_tab_model_name、apply_runtime_config、terminate_by_index、set_tab_preset、get_route_groups_snapshot 等)与配置属性;
- get_pool_status 与 health_check。
- 其他能力在 API 进程中访问会抛 `WorkerModeUnsupported`,并说明原因。
- **恢复与限制**:
- `WorkerSupervisor` 监控 worker 子进程;意外退出后立即尝试重启,启动失败时按指数退避(默认 1–30 秒)持续重试;API 关闭时先停止监控,再关闭 worker。
- 内部健康检查同样要求回环来源与随机令牌,避免把端口上的其他服务误认成当前 worker。
- worker 重启窗口内,在途请求仍可能报错;process 模式仍为实验性,默认保持 `inproc`,切默认前需在专用副本做长时间 soak test。
- 面板的流式接口经转发层透传,已测试普通请求与流式透传,但尚未做长时间实机验证。
- **测试**:`tests/test_worker_mode.py` 覆盖远程执行、停止传播、白名单与鉴权、转发与真实客户端地址、process 模式下经官方 SDK 的端到端请求、真实拉起/关闭 worker,以及意外退出后的自动重启。
+46
View File
@@ -0,0 +1,46 @@
# 聊天请求管线(R2-2)
## 总览
```
客户端协议 入口(转换请求) 执行(唯一入口) 输出(按协议渲染)
────────────────────────────────────────────────────────────────────────────────────────────────────────────────
OpenAI Chat /v1/chat/completions、/tab/…/v1、/url/…/v1 ─┐
Anthropic /v1/messages、/url/…/v1/messages ─→ 转 ChatRequest ├─→ chat_completions / tab_routes ─→ 浏览器层
OpenAI Responses /v1/responses ─→ 转 ChatRequest ───────────────┘ │ 产出 OpenAI 形状的 SSE chunk
▼
iter_openai_sse_payloads / iter_chat_events(app/core/chat_job.py)
▼
OpenAI:原样透传 │ Anthropic:_anthropic_stream_from_openai │ Responses:_stream_responses_compat
```
- **内部请求**是 `ChatRequest`(OpenAI Chat 形状)加上 `ChatJob`。`ChatJob` 记录协议、模型、是否流式、路由目标和 `X-Request-ID`。
- 协议入口用 `use_chat_job(job_for(...))` 设置 ChatJob;流式响应体在端点函数返回之后才执行,所以要用 `with_chat_job(job, 生成器)` 包起来。
- 执行入口 `request_manager.create_request()` 据此设置 `RequestContext.protocol`,`finish_request()` 再按协议和最终状态记录 `uwapi_chat_requests_total` 与 `uwapi_chat_request_duration_seconds`。
- **内部事件**:执行层的输出统一由 `iter_openai_sse_payloads` 解码(处理增量 UTF-8、CRLF、跨块分帧、注释帧和 `[DONE]`),再由 `events_from_openai_chunk` 拆成类型化的 `ChatEvent`:
| kind | 含义 | 字段 |
|------|------|------|
| `text` | 正文增量 | `text` |
| `reasoning` | 思考过程增量 | `text` |
| `tool_call` | 工具调用增量(OpenAI tool_call 形状) | `data` |
| `media` | 生成的图片、视频等 | `data` |
| `usage` | 用量 | `data` |
| `finish` | 结束原因 | `data["finish_reason"]` |
| `error` | 错误 | `text`、`data` |
## 新增一种客户端协议
1. **请求转换**:把新协议的请求转换成 `ChatRequest`,可参考 `anthropic_routes._anthropic_request_to_openai_payload`。
2. **入口**:新建路由,调用 `chat_api.chat_completions(...)`(或按域名、标签页路由的 `tab_routes` 处理函数),并用 `use_chat_job(job_for("新协议名", ...))` 包住。
- 同时把协议名加入 `app/core/chat_job.PROTOCOLS`。
3. **输出渲染**:流式时用 `iter_chat_events(response.body_iterator)` 消费 `ChatEvent`,渲染成新协议的事件;非流式时把 OpenAI 形状的 JSON 结果转换过去。
- 工具调用、停止序列、媒体、会话续接等能力由执行层统一实现,渲染器只做格式映射。
4. **测试**:
- 在 `tests/test_protocol_conformance.py` 里用该协议的官方 SDK 走一遍流式和非流式;
- 在 `tests/test_chat_job.py::test_each_protocol_is_tagged_and_counted` 里加上该协议。
## 现状与后续
- 现有的 Anthropic 与 Responses 渲染器是两个成熟的状态机(约 1300 行),覆盖工具调用增量、停止序列、媒体、用量、错误映射等细节,已有官方 SDK 一致性测试保护。本次**没有重写**它们,只统一了解码入口;Anthropic 适配器的 `_iter_openai_stream_chunks` 已是共享解码器的别名。
- 下一步可以让浏览器层直接产出 `ChatEvent`,省掉「序列化成 SSE 再解码」这一步;渲染器届时只需改为消费事件。这一步与 R2-1(BrowserDriver 接口)一起做更合适。
+27
View File
@@ -0,0 +1,27 @@
# 异常处理规范(R2-7)
## 原则
1. **捕获具体的异常类型。**
- 类型转换:`int()`、`float()` 用 `(TypeError, ValueError, OverflowError)`;`json.loads()` 用 `(TypeError, ValueError, RecursionError)`(`JSONDecodeError` 是 `ValueError` 的子类)。
- 读写文件:`OSError`(包括 `FileNotFoundError`、`PermissionError`)。
- 解析数据:`ValueError`(`UnicodeDecodeError` 也是它的子类)。
- 浏览器操作:`app.core.driver` 的驱动异常,包括 `ContextLost`(页面刷新或导航,稍后重试即可)、`DriverDisconnected`、`DriverTimeout`、`ScriptError`,基类是 `DriverError`。
2. **确有必要的宽泛捕获,在 except 行注明理由**:`except Exception: # broad-except: 理由`。典型场景:
- 回滚或清理之后原样重新抛出;
- 尽力而为的收尾操作(关闭连接、清理缓存);
- 接口层把任何内部错误转换为 HTTP 错误码;
- 指标抓取、心跳这类绝不能让调用方失败的路径。
3. **不要静默吞掉异常。** 至少记一条 debug 日志(`logger.debug(..., exc_info=True)`),排查问题时才有线索。
## 收窄时的注意事项
- `try` 块里的**每一个表达式**都可能抛出异常,而不只是你关心的那个调用。`int(data["x"])` 会先抛 `KeyError`,`float(cfg.get("a"))` 在 `cfg` 为 `None` 时会抛 `AttributeError`。收窄前要确认 `try` 块里没有别的可能出错的表达式;如有,要么一并列出它们的异常类型,要么把它们移出 `try`。
- 驱动层只翻译 DrissionPage 自身的异常,Python 内置异常(`TypeError`、`OSError` 等)原样抛出。所以依赖 `except TypeError` 做兼容退回的代码不受影响。
## 棘轮
`tests/test_exception_ratchet.py` 按文件统计宽泛捕获的数量,**只减不增**,基线在 `tests/fixtures/broad_except_ratchet.json`。收窄之后运行 `python tests/test_exception_ratchet.py --update`,把进度锁定。
- 起点:1511 处。
- R2-7 做了两件事:一是机械收窄 50 处「`try` 里只有一句类型转换、参数是变量或常量」的写法;二是对新模块逐个审阅,收窄或注明了 28 处。现为 1433 处。