docs(browser): 增补 browser MCP 第七阶段设计

明确 Phase 7 继续沿 network interception 路线推进 richer request matching。收敛匹配增强的范围、边界、数据模型与测试策略，为后续在独立 phase7 worktree 中实现做准备。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-16 04:18:05 +00:00 · 2026-04-18 23:57:21 +08:00
parent 447b5c8bc1
commit a5ef77a3d8
1 changed files with 323 additions and 0 deletions
@@ -0,0 +1,323 @@
+# Browser MCP Phase 7 Design
+
+Last Updated: 2026-04-18
+
+## Goal
+
+在新的 `feat/browser-mcp-hover-phase7` worktree 中，为 CCS-managed `ccs-browser` MCP runtime 设计 Browser MCP Phase 7。
+本阶段延续 Phase 6 的 network interception 路线，优先聚焦 **richer request matching**，让现有拦截规则可以按更细的请求特征命中，同时保持既有最小增量策略。
+
+## Scope Summary
+
+### In Scope
+
+- 在现有 `browser_add_intercept_rule` 基础上扩展更丰富的匹配条件
+- 新增最小匹配维度：
+  - `resourceType`
+  - `urlPattern` 或 `urlRegex`（二选一）
+  - `headerMatchers`
+  - `priority`
+- 将规则匹配顺序从“创建顺序”扩展为：
+  1. `priority` 从高到低
+  2. 同优先级按创建顺序
+- 扩展 `browser_list_intercept_rules` 输出，展示新增匹配摘要
+- 保持 `browser_list_requests` 为请求摘要视图，不输出 request/response body
+- 保持 selected page 解析语义、规则绑定具体 `pageId`、session-local runtime state、页级 websocket interception session 与 `messageQueue` 串行语义
+
+### Explicitly Out of Scope
+
+- 跨页共享规则或浏览器级全局规则
+- 下载接受/拒绝控制与下载文件管理
+- 请求体匹配
+- 响应阶段匹配
+- 更复杂布尔逻辑（如任意/全部组、嵌套条件、否定条件）
+- 完整网络代理层
+
+## Why Phase 7 Follows Phase 6
+
+Phase 6 已建立：
+
+- page-bound 的 interception rule 管理面
+- session-local `interceptRules` / `recentRequests` / `interceptSessionsByPageId`
+- `continue` / `fail` / `fulfill` 三种最小动作集
+
+历史设计里也已明确把以下能力延后到后续阶段：
+
+- 更复杂的匹配条件，如 `resourceType`、`headerMatchers`、正则、优先级
+- 跨页共享规则
+- 下载接受控制
+
+因此，Phase 7 继续沿 network interception 主线推进 richer matching，是与现有实现最连续、收益最大的下一阶段；它能显著提升规则可用性，同时不会把作用域和下载控制这两类新问题混进同一期。
+
+## Architecture
+
+Phase 7 继续沿用 `lib/mcp/ccs-browser-server.cjs` 的单 runtime 架构，不引入新的 browser runtime，也不改写 Phase 5 的 selected page 模型和 Phase 6 的 interception session 生命周期。
+
+本阶段仍沿用三层结构：
+
+1. **Tool surface**：复用现有四个 interception 相关工具，只扩展参数与输出摘要
+2. **Session-local state**：继续复用 `interceptRules`、`recentRequests`、`interceptSessionsByPageId`
+3. **Page interception session**：继续由具体 page target 的 websocket 消费 paused requests，并根据 richer matching 结果执行动作
+
+关键设计约束：
+
+- 规则仍在创建时解析并固化为具体 `pageId`
+- 规则不会在后续 selected page 切换时自动漂移
+- 新增 richer matching 不改变现有 action 执行路径，只改变“哪条规则命中”
+- `messageQueue` 继续只负责工具入口串行语义；页级 websocket 仍异步接收 paused request 事件
+
+## Tool Surface
+
+Phase 7 不新增新工具，继续复用：
+
+- `browser_add_intercept_rule`
+- `browser_remove_intercept_rule`
+- `browser_list_intercept_rules`
+- `browser_list_requests`
+
+### `browser_add_intercept_rule`
+
+在 Phase 6 参数基础上，扩展最小 richer matching 参数：
+
+- `pageIndex?: number`
+- `pageId?: string`
+- `urlIncludes?: string`
+- `method?: string`
+- `resourceType?: string`
+- `urlPattern?: string`
+- `urlRegex?: string`
+- `headerMatchers?: Array<{ name: string; valueIncludes?: string; valueRegex?: string }>`
+- `priority?: number`
+- `action: "continue" | "fail" | "fulfill"`
+- `statusCode?`, `contentType?`, `responseHeaders?`, `body?`（仅 `action: "fulfill"` 时沿用 Phase 6B 现有语义；避免与请求匹配用的 `headerMatchers` 混淆）
+
+约束：
+
+- `pageIndex` 与 `pageId` 不能同时传
+- `urlPattern` 与 `urlRegex` 不能同时传
+- `priority` 默认 `0`
+- `priority` 必须是整数
+- header matcher 的 `name` 必填
+- 每个 header matcher 至少需要一个值条件：`valueIncludes` 或 `valueRegex`
+- Phase 7 仍要求至少有一个请求匹配条件，避免创建“无条件全匹配”规则
+
+### `browser_remove_intercept_rule`
+
+保持不变，仅按 `ruleId` 删除对应规则。
+
+### `browser_list_intercept_rules`
+
+在现有输出基础上，新增简洁摘要字段：
+
+- `priority`
+- `resourceType`
+- `urlPattern` 或 `urlRegex`
+- `headerMatchers` 条件数量或简写摘要
+
+要求：
+
+- 仍保持文本摘要可读性
+- 不直接把长正则或大量 header 条件原样完整展开到难以阅读
+
+### `browser_list_requests`
+
+保持“近期请求摘要”定位，不展示 request/response body。
+
+可选补充字段：
+
+- `matchedRuleId`
+- `action`
+- `statusCode`（仅 fulfill）
+- 必要时增加一个轻量命中说明，如 `matchedBy`，只表示命中依赖了哪类条件，不重复整条规则
+
+## State Model
+
+Phase 7 仍复用 Phase 6 的三块 session-local 状态。
+
+### `interceptRules`
+
+每条规则在 Phase 6 基础上新增：
+
+- `resourceType`
+- `urlPattern`
+- `urlRegex`
+- `headerMatchers`
+- `priority`
+
+关键约束：
+
+- 规则绑定到创建时解析出的具体 `pageId`
+- 规则仍不持久化到磁盘
+- `priority` 仅影响匹配顺序，不影响工具展示或生命周期清理逻辑
+
+### `recentRequests`
+
+仍然只存储近期请求摘要，继续不保留 body。
+
+如增加 `matchedBy`，也只记录轻量摘要，而不是完整匹配细节。
+
+### `interceptSessionsByPageId`
+
+不新增新的 session 级状态表。
+
+Phase 7 只扩匹配逻辑，不改 websocket 生命周期模型：
+
+- 规则创建时按需建立 session
+- 页面关闭或无规则时回收 session
+- websocket 断开时继续进行现有清理与错误恢复语义
+
+## Matching Model
+
+### Matching Order
+
+对某个 paused request，只在其所属 `pageId` 的规则集合内匹配。
+
+匹配顺序：
+
+1. `priority` 从高到低
+2. 同优先级按创建顺序
+3. 第一条完整命中的规则生效
+
+这意味着 Phase 7 解决了 Phase 6 “只能按创建顺序命中”的限制，同时避免引入更复杂的规则编排系统。
+
+### Rule Predicate Evaluation
+
+每条规则依次检查：
+
+1. `method`
+2. `urlIncludes`
+3. `urlPattern` 或 `urlRegex`
+4. `resourceType`
+5. `headerMatchers`
+
+所有已提供条件都必须命中，规则才算匹配成功。
+
+### Header Matching
+
+Phase 7 的 header matching 采用最小规则：
+
+- header 名称按大小写不敏感匹配
+- 每个 matcher 至少要求一个值条件：
+  - `valueIncludes`
+  - `valueRegex`
+- 多个 header matcher 之间采用“全部满足”语义
+
+Phase 7 不支持：
+
+- any/all 模式切换
+- header 多值数组高级语义
+- 负向匹配
+- body/JSON 级内容匹配
+
+## Data Flow
+
+### Add Rule Flow
+
+1. `browser_add_intercept_rule` 解析目标页
+2. 校验 richer matching 参数
+3. 生成 `ruleId`
+4. 将规则写入 `interceptRules`
+5. 为目标页创建或复用 interception session
+6. 返回包含新增匹配摘要的 rule 文本
+
+### Request Match Flow
+
+1. 页级 interception session 收到 paused request 事件
+2. 取出该页全部有效规则
+3. 按 `priority DESC + createdAt ASC` 排序
+4. 逐条检查 method / URL / resourceType / `headerMatchers` 条件
+5. 第一条命中规则决定 action：
+   - `continue`
+   - `fail`
+   - `fulfill`
+6. 将结果写入 `recentRequests`
+7. 若无任何规则命中，则默认 `continue`
+
+### Remove Rule Flow
+
+保持 Phase 6 行为：
+
+1. `browser_remove_intercept_rule` 按 `ruleId` 找到规则
+2. 从 `interceptRules` 删除
+3. 若该页已无剩余规则，则关闭该页 interception session
+4. 返回删除结果
+
+## Error Handling and Boundary Rules
+
+### Parameter Rules
+
+`browser_add_intercept_rule`：
+
+- `pageIndex` 和 `pageId` 不能同时传
+- `urlPattern` 和 `urlRegex` 不能同时传
+- `priority` 必须是整数
+- `headerMatchers` 必须是数组
+- 每个 header matcher 必须有 `name`
+- 每个 header matcher 必须至少有 `valueIncludes` 或 `valueRegex`
+- 目标页不存在、已关闭或无 websocket target 时直接报错
+
+### Matching Rules
+
+- 不支持空 header matcher
+- 不支持空正则
+- 不支持通过 richer matching 创建跨页规则
+- 同一请求只应用第一条命中的规则
+
+### Lifecycle Rules
+
+- 页面关闭时，绑定该 `pageId` 的规则与近期请求摘要继续按 Phase 6 规则清理
+- websocket 关闭时不保留悬挂 session
+- selected page 变化不影响已创建规则的 `pageId` 绑定
+
+## Testing Strategy
+
+Phase 7 继续沿用既有 TDD 路线，在 `tests/unit/hooks/ccs-browser-mcp-server.test.ts` 上扩展 deterministic harness 与行为断言。
+
+建议拆分为：
+
+1. **Schema / 参数失败测试**
+   - `urlPattern` 与 `urlRegex` 同传时报错
+   - `priority` 非整数时报错
+   - `headerMatchers` 不是数组时报错
+   - header matcher 缺 `name` 报错
+   - header matcher 既无 `valueIncludes` 也无 `valueRegex` 报错
+
+2. **主路径测试**
+   - `resourceType` 命中
+   - `urlPattern` 命中
+   - `urlRegex` 命中
+   - `headerMatchers.valueIncludes` 命中
+   - `headerMatchers.valueRegex` 命中
+
+3. **优先级与回归测试**
+   - 更高 `priority` 的规则覆盖较低优先级规则
+   - 同优先级仍按创建顺序命中
+   - selected page 切换后规则仍绑定原 `pageId`
+   - 页面关闭后 richer matching 规则与请求摘要一起清理
+
+4. **仓库验证顺序**
+   - focused test
+   - `bun run build:server`
+   - `bun run format`
+   - `bun run validate`
+   - `bun run validate:ci-parity`
+
+## Documentation Impact
+
+如果 Phase 7 落地，`docs/browser-automation.md` 需要同步更新：
+
+- Phase 7 capability details
+- richer matching 示例
+- 当前仍未支持的范围：跨页规则、下载控制、请求体匹配等
+
+## Phase 7 Deliverable Boundary
+
+Phase 7 的交付结果应当是：
+
+- 用户可以继续用现有四个 interception 工具
+- 用户可以创建更精细的 page-bound 规则
+- 用户可以用 `priority` 控制命中顺序
+- 用户仍在同一 session-local interception 模型里工作
+- 代码不因为这期而引入新的全局作用域、下载控制或代理层复杂度
+
+这让 Browser MCP 的 network interception 从“最小可用”进入“更稳定可控”，但仍然保持单期可交付范围。