From a5ef77a3d8928440d927c84d207477993cae3d6a Mon Sep 17 00:00:00 2001 From: walker1211 <13750528578@163.com> Date: Sat, 18 Apr 2026 23:57:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(browser):=20=E5=A2=9E=E8=A1=A5=20browser?= =?UTF-8?q?=20MCP=20=E7=AC=AC=E4=B8=83=E9=98=B6=E6=AE=B5=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 明确 Phase 7 继续沿 network interception 路线推进 richer request matching。 收敛匹配增强的范围、边界、数据模型与测试策略，为后续在独立 phase7 worktree 中实现做准备。 Co-Authored-By: Claude Opus 4.7 --- .../2026-04-18-browser-mcp-phase7-design.md | 323 ++++++++++++++++++ 1 file changed, 323 insertions(+) create mode 100644 docs/reports/2026-04-18-browser-mcp-phase7-design.md diff --git a/docs/reports/2026-04-18-browser-mcp-phase7-design.md b/docs/reports/2026-04-18-browser-mcp-phase7-design.md new file mode 100644 index 00000000..73ab8d82 --- /dev/null +++ b/docs/reports/2026-04-18-browser-mcp-phase7-design.md @@ -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 从“最小可用”进入“更稳定可控”，但仍然保持单期可交付范围。