tiennm99/ccs
1
0 Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-10-13 16:14:31 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
4af967559cd985b0829bbb197edcae1bb264bdc0
ccs/docs/reports/2026-04-18-browser-mcp-phase7-design.md
T
walker1211andClaude Opus 4.7 a5ef77a3d8 docs(browser): 增补 browser MCP 第七阶段设计 
明确 Phase 7 继续沿 network interception 路线推进 richer request matching。
收敛匹配增强的范围、边界、数据模型与测试策略，为后续在独立 phase7 worktree 中实现做准备。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-18 23:57:21 +08:00

10 KiB
Raw Blame History

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 从“最小可用”进入“更稳定可控”，但仍然保持单期可交付范围。

Reference in new issue View Git Blame Copy Permalink