mirror of
https://github.com/tiennm99/ccs.git
synced 2026-10-13 00:14:15 +00:00
chore(browser): drop phase design reports
This commit is contained in:
Tam Nhu Tran committed
1 parent
c24033dc6b
commit
e51b53fab9
3 files changed
-1050
No files matched your search
@@ -1,272 +0,0 @@
|
||||
# Browser MCP Phase 6 Design
|
||||
|
||||
Last Updated: 2026-04-18
|
||||
|
||||
## Goal
|
||||
|
||||
在 `feat/browser-mcp-hover-phase6` worktree 中，为 CCS-managed `ccs-browser` MCP runtime 设计 Browser MCP Phase 6。
|
||||
本阶段延续既有 browser MCP 能力蓝图，优先聚焦 network interception / mock responses，并保持 Phase 1-5 一致的最小增量策略。
|
||||
|
||||
Phase 6 不在当前阶段一次性做完整网络代理层，而是拆成两个连续子阶段：
|
||||
|
||||
- **Phase 6A**：request observation + scoped interception skeleton
|
||||
- **Phase 6B**：mock responses
|
||||
|
||||
## Scope Summary
|
||||
|
||||
### In Scope for Phase 6A
|
||||
|
||||
- 新增会话级 interception rule 管理能力
|
||||
- 新增近期请求摘要查看能力
|
||||
- 基于目标页建立 Fetch interception 会话
|
||||
- 支持最小匹配集：`urlIncludes`、`method`
|
||||
- 支持最小动作集：`continue`、`fail`
|
||||
- 维持 session-local state，不做跨 runtime 重启持久化
|
||||
|
||||
### Deferred to Phase 6B
|
||||
|
||||
- `fulfill` / mock response action
|
||||
- 自定义 status / headers / body
|
||||
- response body 编码与更复杂序列化
|
||||
- 更复杂的匹配条件，如资源类型、headers、正则、优先级
|
||||
- 浏览器级或跨页共享拦截规则
|
||||
|
||||
## Architecture
|
||||
|
||||
Phase 6 继续沿用现有 `lib/mcp/ccs-browser-server.cjs` 单 runtime 架构，不额外引入第二套 browser server，也不改写当前页面选择与工具注册模型。
|
||||
|
||||
现有 runtime 已具备两类基础能力：
|
||||
|
||||
- 页面级 CDP 请求发送：`sendCdpCommand(page, method, params)`
|
||||
- 事件型 websocket 监听：当前 `browser_wait_for_event` 已能在页级 websocket 上启用 `Page.enable` / `Network.enable`
|
||||
|
||||
Phase 6 在这一基础上增加一层 **session-local interception state**，而不是引入新的全局配置层。
|
||||
|
||||
整体结构分为三层：
|
||||
|
||||
1. **Tool surface**：新增规则管理和请求查看工具
|
||||
2. **Session-local state**：记录规则、近期请求和页级 interception session
|
||||
3. **Page interception session**：在具体 page target 上维护 Fetch domain 长连接，处理 paused requests
|
||||
|
||||
## Tool Surface
|
||||
|
||||
Phase 6A 先只新增四个工具，形成最小闭环。
|
||||
|
||||
### `browser_add_intercept_rule`
|
||||
|
||||
为某个页面添加一条会话级拦截规则。
|
||||
|
||||
建议参数：
|
||||
|
||||
- `pageIndex?: number`
|
||||
- `pageId?: string`
|
||||
- `urlIncludes?: string`
|
||||
- `method?: string`
|
||||
- `action: "continue" | "fail"`
|
||||
|
||||
行为：
|
||||
|
||||
- 如果省略 `pageIndex/pageId`，按调用当下的 selected page 解析一次目标页
|
||||
- 解析结果固化为具体 `pageId`
|
||||
- 创建 ruleId 并返回
|
||||
- 若目标页尚未建立 interception session，则启动该页的 Fetch interception 长连接
|
||||
|
||||
### `browser_remove_intercept_rule`
|
||||
|
||||
按 `ruleId` 删除一条规则。
|
||||
|
||||
建议参数：
|
||||
|
||||
- `ruleId: string`
|
||||
|
||||
行为：
|
||||
|
||||
- 删除对应规则
|
||||
- 如果某页已无任何规则，回收该页 interception session
|
||||
|
||||
### `browser_list_intercept_rules`
|
||||
|
||||
列出当前 MCP runtime 内存中的有效规则。
|
||||
|
||||
返回字段最小化，建议包含：
|
||||
|
||||
- `ruleId`
|
||||
- `pageId`
|
||||
- `pageTitle`
|
||||
- `urlIncludes`
|
||||
- `method`
|
||||
- `action`
|
||||
|
||||
### `browser_list_requests`
|
||||
|
||||
返回近期观测到的请求摘要。
|
||||
|
||||
建议参数：
|
||||
|
||||
- `pageIndex?: number`
|
||||
- `pageId?: string`
|
||||
- `limit?: number`
|
||||
|
||||
返回字段最小化，建议包含：
|
||||
|
||||
- `requestId`
|
||||
- `pageId`
|
||||
- `url`
|
||||
- `method`
|
||||
- `resourceType`
|
||||
- `matchedRuleId`
|
||||
- `action`
|
||||
|
||||
## State Model
|
||||
|
||||
Phase 6A 在 runtime 内维护三块 session-local 状态：
|
||||
|
||||
### `interceptRules`
|
||||
|
||||
存储当前有效规则列表。每条规则至少包含：
|
||||
|
||||
- `ruleId`
|
||||
- `pageId`
|
||||
- `pageTitleSnapshot`
|
||||
- `urlIncludes`
|
||||
- `method`
|
||||
- `action`
|
||||
- `createdAt`
|
||||
|
||||
关键约束：
|
||||
|
||||
- 规则绑定到**创建时解析出的具体 pageId**
|
||||
- 规则不会在后续切换 selected page 时自动漂移
|
||||
- 规则不持久化到磁盘
|
||||
|
||||
### `recentRequests`
|
||||
|
||||
存储近期请求摘要，供 `browser_list_requests` 使用。
|
||||
|
||||
关键约束：
|
||||
|
||||
- 固定上限，建议 100 条
|
||||
- 超过上限时丢弃最旧记录
|
||||
- 只保留摘要，不保留 body
|
||||
|
||||
### `interceptSessionsByPageId`
|
||||
|
||||
存储每个被拦截页面对应的长连接会话。
|
||||
|
||||
每个 session 至少需要管理：
|
||||
|
||||
- `pageId`
|
||||
- `webSocketDebuggerUrl`
|
||||
- websocket 实例
|
||||
- 当前是否已启用 `Fetch.enable`
|
||||
- 关联规则数量
|
||||
- 最近错误状态（如果需要）
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Add Rule Flow
|
||||
|
||||
1. `browser_add_intercept_rule` 解析目标页
|
||||
2. 校验参数与最小匹配条件
|
||||
3. 生成 `ruleId`
|
||||
4. 将规则写入 `interceptRules`
|
||||
5. 为目标页创建或复用 interception session
|
||||
6. 在该页 websocket 上启用 `Fetch.enable`
|
||||
7. 返回 rule 摘要
|
||||
|
||||
### Request Interception Flow
|
||||
|
||||
1. 页级 interception session 收到 paused request 事件
|
||||
2. 从该页规则中按创建顺序依次匹配
|
||||
3. 第一条命中规则决定动作
|
||||
4. 执行动作：
|
||||
- `continue` -> 放行请求
|
||||
- `fail` -> 以固定错误原因中止请求
|
||||
5. 写入 `recentRequests`
|
||||
6. 若无命中规则，则默认 `continue`
|
||||
|
||||
### Remove Rule Flow
|
||||
|
||||
1. `browser_remove_intercept_rule` 按 `ruleId` 找到规则
|
||||
2. 从 `interceptRules` 删除
|
||||
3. 若规则所属页已无剩余规则，则关闭该页 interception session
|
||||
4. 返回删除结果
|
||||
|
||||
### List Requests Flow
|
||||
|
||||
1. `browser_list_requests` 按可选 page filter 过滤
|
||||
2. 按时间倒序返回近期摘要
|
||||
3. 应用 `limit`
|
||||
|
||||
## Error Handling and Boundary Rules
|
||||
|
||||
### Parameter Rules
|
||||
|
||||
`browser_add_intercept_rule`：
|
||||
|
||||
- `pageIndex` 和 `pageId` 不能同时传
|
||||
- `action` 只能是 `continue` 或 `fail`
|
||||
- 至少要有一个匹配条件：`urlIncludes` 或 `method`
|
||||
- 目标页不存在、已关闭或无 websocket target 时直接报错
|
||||
|
||||
`browser_remove_intercept_rule`：
|
||||
|
||||
- `ruleId` 不存在时报错
|
||||
|
||||
`browser_list_requests`：
|
||||
|
||||
- `pageIndex` 和 `pageId` 不能同时传
|
||||
- `limit` 越界时回退到安全默认值
|
||||
|
||||
### Lifecycle Rules
|
||||
|
||||
- 所有 interception 规则都是 session-local in-memory state
|
||||
- 目标页关闭后，该页规则自动失效并从规则列表中清除
|
||||
- `browser_list_intercept_rules` 只返回当前仍有效的规则
|
||||
- runtime 重启后，所有规则和请求摘要都会丢失
|
||||
|
||||
### Concurrency Rules
|
||||
|
||||
- 规则管理工具继续沿用当前 runtime 的串行消息语义，避免状态竞态
|
||||
- 真正的请求拦截事件在页级长连接中异步处理
|
||||
- 页级拦截事件只允许修改自身 pageId 对应的 interception session 状态，以及共享的 `recentRequests`
|
||||
|
||||
## Interaction with Existing Phase 5 State
|
||||
|
||||
Phase 6 必须与现有 selected page 语义兼容：
|
||||
|
||||
- 添加规则时若省略目标页参数，只在创建当下读取 selected page 一次
|
||||
- 规则创建完成后绑定到具体 pageId，不再受后续切页影响
|
||||
- `browser_select_page`、`browser_open_page`、`browser_close_page` 不直接重写既有规则的 page binding
|
||||
- 如果 `browser_close_page` 关闭了被规则绑定的页面，相关规则应自动清理
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
Phase 6A 测试应继续扩展 `tests/unit/hooks/ccs-browser-mcp-server.test.ts` 里的 deterministic harness。
|
||||
|
||||
最小测试集建议覆盖：
|
||||
|
||||
1. 工具列表与 schema 暴露正确
|
||||
2. 添加规则后能在规则列表中看到
|
||||
3. 删除规则后规则消失
|
||||
4. 两条规则按创建顺序匹配，先命中者生效
|
||||
5. 省略 `pageIndex/pageId` 时按当前 selected page 绑定
|
||||
6. 切换 selected page 后，旧规则仍绑定原 pageId
|
||||
7. 关闭绑定页面后规则自动清理
|
||||
8. `browser_list_requests` 只返回摘要并 obey `limit`
|
||||
9. 无命中规则时默认 continue
|
||||
10. `fail` 动作能生成稳定且可断言的结果
|
||||
|
||||
## Why This Split
|
||||
|
||||
将 Phase 6 拆成 6A / 6B 的原因是：
|
||||
|
||||
- 先稳定规则管理、页级会话和 paused request 生命周期
|
||||
- 再叠加 mock fulfill response，避免一开始把匹配、状态管理、headers/body 序列化全耦合到一起
|
||||
- 与 Phase 1-5 的最小闭环推进方式保持一致
|
||||
|
||||
6A 解决的是“能稳定地拦住并控制请求”；6B 再解决“能把响应内容完全替换掉”。
|
||||
|
||||
## Out of Scope in This Design Pass
|
||||
|
||||
本轮设计确认只覆盖 Phase 6 的拆分方式与 6A 的最小闭环，不直接进入 6B 的详细实现步骤，也不在这里展开 implementation plan。
|
||||
@@ -1,323 +0,0 @@
|
||||
# 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 从“最小可用”进入“更稳定可控”，但仍然保持单期可交付范围。
|
||||
@@ -1,455 +0,0 @@
|
||||
# Browser MCP Phase 8 Design
|
||||
|
||||
Last Updated: 2026-04-19
|
||||
|
||||
## Goal
|
||||
|
||||
在当前已完成并提交的 Browser MCP Phase 7 基线之上，为 CCS-managed `ccs-browser` MCP runtime 设计 Browser MCP Phase 8。
|
||||
|
||||
本阶段延续历史 roadmap 中 Phase 7 预留的 file-transfer / lifecycle completion 方向，但按当前官方 CDP 能力边界做最小修正：
|
||||
|
||||
- **下载控制**：采用 session-local、browser-scoped 的下载策略与下载结果摘要
|
||||
- **最小上传**：采用 page-scoped 的 file input 设置能力
|
||||
|
||||
Phase 8 的目标是补齐“文件流转”这一类真实浏览器工作流缺口，让 browser MCP 不再只有页面交互与网络拦截，还能覆盖最常见的下载与表单文件上传场景。
|
||||
|
||||
## Why Phase 8 Follows Phase 7
|
||||
|
||||
历史 spec 的主路线是：
|
||||
|
||||
- Phase 5：page/tab control
|
||||
- Phase 6：network interception + mock responses
|
||||
- Phase 7：file-transfer and lifecycle completion
|
||||
- Phase 8+：recording / replay / higher-level orchestration
|
||||
|
||||
后来实际交付里，Phase 6 被拆成 6A / 6B，Phase 7 又继续完成了 richer request matching。因此当前 browser MCP 已经把 interception 线打磨到了一个较完整的最小闭环：
|
||||
|
||||
- page-bound interception rules
|
||||
- session-local state
|
||||
- `continue` / `fail` / `fulfill`
|
||||
- richer request matching
|
||||
- recent request summaries
|
||||
|
||||
下一阶段如果继续深挖 interception，会开始落入 request body matching、更复杂 boolean matcher groups、cross-page shared rules 这类更重的规则编排问题；而历史 roadmap 里原本预留的 file transfer 缺口仍未补上。
|
||||
|
||||
因此，Phase 8 应该回到原 roadmap，优先补：
|
||||
|
||||
- **download handling**
|
||||
- **minimal upload handling**
|
||||
|
||||
这样既尊重了最初路线，也能让 browser MCP 覆盖更多真实 end-to-end workflow。
|
||||
|
||||
## Scope Summary
|
||||
|
||||
### In Scope
|
||||
|
||||
1. **下载控制**
|
||||
- 为当前 attach session 设置下载策略：接受或拒绝下载
|
||||
- 支持 session-local 下载目录配置
|
||||
- 记录近期下载摘要
|
||||
- 支持取消进行中的下载
|
||||
- 继续兼容现有 `browser_wait_for_event(kind=download)` 事件等待能力
|
||||
|
||||
2. **最小上传**
|
||||
- 为 `<input type="file">` 设置一个或多个本地文件
|
||||
- 支持当前已有 selector 作用域能力：`nth`、`frameSelector`、`pierceShadow`
|
||||
- 保持 selected page 解析语义
|
||||
|
||||
3. **状态可见性**
|
||||
- 通过新的下载列表工具查看近期下载摘要与状态
|
||||
- 返回清晰的 upload / download 结果摘要
|
||||
|
||||
### Explicitly Out of Scope
|
||||
|
||||
- 原生系统文件选择器接管
|
||||
- drag-and-drop 上传
|
||||
- 下载文件内容读取、解析或回传
|
||||
- 上传后自动点击 submit 或自动编排后续页面流程
|
||||
- 跨 runtime 持久化下载策略或下载记录
|
||||
- 基于 interception 的下载内容改写
|
||||
- 录制 / 回放 / 宏编排
|
||||
- request body matching
|
||||
- 更复杂 boolean matcher groups
|
||||
- 跨页共享 interception rules
|
||||
|
||||
## CDP Constraint and Scope Correction
|
||||
|
||||
Phase 8 的关键设计修正来自当前官方 CDP 能力边界：
|
||||
|
||||
### Uploads
|
||||
|
||||
上传侧可基于 `DOM.setFileInputFiles` 实现，因此天然适合继续沿用当前 browser MCP 的 page-scoped / selector-scoped 工具模型。
|
||||
|
||||
### Downloads
|
||||
|
||||
下载侧主要依赖 Browser domain：
|
||||
|
||||
- `Browser.setDownloadBehavior`
|
||||
- `Browser.cancelDownload`
|
||||
- `Browser.downloadWillBegin`
|
||||
- `Browser.downloadProgress`
|
||||
|
||||
这些接口更接近 **browser-scoped / browser-context-scoped** 能力，而不是某个 page target 独占的 page-bound 能力。因此 Phase 8 不应伪装成“每页独立下载开关”，而应明确采用：
|
||||
|
||||
- **下载控制：session-local, browser-scoped**
|
||||
- **上传控制：page-scoped**
|
||||
|
||||
这是一个有意的混合作用域设计，但它与 CDP 现实能力一致，也避免了 misleading 的 page-local 承诺。
|
||||
|
||||
## Architecture
|
||||
|
||||
Phase 8 继续沿用 `lib/mcp/ccs-browser-server.cjs` 的单 runtime 架构，不引入新的 browser runtime，也不重写 Phase 5 selected page 模型或 Phase 6-7 的 interception 架构。
|
||||
|
||||
本阶段分成两条并行但边界清晰的能力线：
|
||||
|
||||
1. **Download control line**
|
||||
- browser-scoped CDP Browser domain 控制
|
||||
- session-local 下载策略与下载摘要
|
||||
2. **File input upload line**
|
||||
- page-scoped selector 解析
|
||||
- DOM file input 赋值
|
||||
|
||||
### Design Principles
|
||||
|
||||
- 下载控制尊重 CDP Browser domain 的真实作用域，不伪造成 page-bound
|
||||
- 上传继续复用已有 selector / frame / shadow 解析模型，不新建第二套选择器系统
|
||||
- 继续保持 session-local state，不持久化到磁盘
|
||||
- 继续保持最小增量策略，不把 download/upload 扩展成完整文件管理系统
|
||||
- 不为了 Phase 8 重构现有 wait / event / interception 基础设施
|
||||
|
||||
## Tool Surface
|
||||
|
||||
Phase 8 推荐新增三个工具。
|
||||
|
||||
### 1. `browser_set_download_behavior`
|
||||
|
||||
为当前 attach session 设置下载策略。
|
||||
|
||||
建议参数：
|
||||
|
||||
- `behavior: "accept" | "deny"`
|
||||
- `downloadPath?: string`
|
||||
- `eventsEnabled?: boolean`
|
||||
|
||||
行为：
|
||||
|
||||
- `behavior=accept` 时允许下载
|
||||
- `behavior=deny` 时拒绝下载
|
||||
- `downloadPath` 仅在 accept 时有效；如省略，则 runtime 选择 session-local 默认下载目录
|
||||
- `eventsEnabled` 默认开启，保证下载事件和结果摘要可见
|
||||
- 作用域为当前 attach session / browser context，而不是单个页面
|
||||
|
||||
返回字段建议最小包含：
|
||||
|
||||
- `scope: browser`
|
||||
- `behavior`
|
||||
- `downloadPath`
|
||||
- `eventsEnabled`
|
||||
- `status`
|
||||
|
||||
### 2. `browser_list_downloads`
|
||||
|
||||
列出当前 MCP runtime 记录的近期下载摘要。
|
||||
|
||||
建议参数：
|
||||
|
||||
- `limit?: number`
|
||||
- `pageId?: string`
|
||||
|
||||
行为：
|
||||
|
||||
- 默认返回最近下载摘要
|
||||
- 可按触发下载时记录的 `pageId` 过滤
|
||||
- 不读取下载文件内容
|
||||
- 只返回摘要和状态
|
||||
|
||||
返回字段建议最小包含：
|
||||
|
||||
- `downloadId`
|
||||
- `guid`
|
||||
- `pageId`
|
||||
- `url`
|
||||
- `suggestedFilename`
|
||||
- `status`
|
||||
- `savedPath`
|
||||
- `startedAt`
|
||||
- `finishedAt`
|
||||
|
||||
### 3. `browser_cancel_download`
|
||||
|
||||
取消进行中的下载。
|
||||
|
||||
建议参数：
|
||||
|
||||
- `downloadId?: string`
|
||||
- `guid?: string`
|
||||
|
||||
行为：
|
||||
|
||||
- 按 runtime 记录的 `downloadId` 或底层 `guid` 定位目标
|
||||
- 调用 Browser domain cancel 能力
|
||||
- 更新 `recentDownloads` 中对应项状态
|
||||
|
||||
约束：
|
||||
|
||||
- `downloadId` 与 `guid` 至少提供一个
|
||||
- 两者同时提供时必须指向同一条下载记录，否则报错
|
||||
|
||||
### 4. `browser_set_file_input`
|
||||
|
||||
为 `<input type="file">` 直接设置本地文件。
|
||||
|
||||
建议参数：
|
||||
|
||||
- `selector: string`
|
||||
- `files: string[]`
|
||||
- `pageIndex?: number`
|
||||
- `pageId?: string`
|
||||
- `nth?: number`
|
||||
- `frameSelector?: string`
|
||||
- `pierceShadow?: boolean`
|
||||
|
||||
行为：
|
||||
|
||||
- 解析目标页
|
||||
- 解析 selector 作用域
|
||||
- 定位目标节点
|
||||
- 要求目标是 `<input type="file">`
|
||||
- 将本地文件路径集合设置到该 input
|
||||
- 返回设置结果摘要
|
||||
|
||||
返回字段建议最小包含：
|
||||
|
||||
- `pageId`
|
||||
- `pageIndex`
|
||||
- `selector`
|
||||
- `fileCount`
|
||||
- `status`
|
||||
|
||||
## State Model
|
||||
|
||||
Phase 8 继续使用 session-local in-memory state。
|
||||
|
||||
### `downloadBehaviorState`
|
||||
|
||||
存储当前 attach session 的下载行为配置。
|
||||
|
||||
建议字段：
|
||||
|
||||
- `behavior`
|
||||
- `downloadPath`
|
||||
- `eventsEnabled`
|
||||
- `updatedAt`
|
||||
|
||||
关键约束：
|
||||
|
||||
- browser-scoped
|
||||
- 不绑定 pageId
|
||||
- runtime 重启后丢失
|
||||
|
||||
### `recentDownloads`
|
||||
|
||||
记录近期下载摘要。
|
||||
|
||||
建议字段：
|
||||
|
||||
- `downloadId`
|
||||
- `guid`
|
||||
- `pageId`
|
||||
- `url`
|
||||
- `suggestedFilename`
|
||||
- `status: "started" | "inProgress" | "completed" | "canceled" | "denied" | "failed"`
|
||||
- `savedPath`
|
||||
- `receivedBytes`
|
||||
- `totalBytes`
|
||||
- `startedAt`
|
||||
- `finishedAt`
|
||||
|
||||
关键约束：
|
||||
|
||||
- 固定上限，建议 100 条
|
||||
- 只保留摘要，不读文件内容
|
||||
- 通过 `guid` 关联 Browser domain 下载事件
|
||||
|
||||
### Existing selected page state
|
||||
|
||||
上传工具继续复用现有 selected page 模型：
|
||||
|
||||
- 显式 `pageIndex` 优先
|
||||
- 否则走 selected page
|
||||
- stale selected page 时回退到第一可用页面
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Download behavior update flow
|
||||
|
||||
1. `browser_set_download_behavior` 校验参数
|
||||
2. 若 `behavior=accept` 且未提供 `downloadPath`，计算 session-local 默认下载目录
|
||||
3. 调用 `Browser.setDownloadBehavior`
|
||||
4. 更新 `downloadBehaviorState`
|
||||
5. 返回当前配置摘要
|
||||
|
||||
### Download observation flow
|
||||
|
||||
1. runtime 接收 `Browser.downloadWillBegin`
|
||||
2. 生成 `downloadId`
|
||||
3. 写入 `recentDownloads`，状态为 `started`
|
||||
4. 记录触发时关联的 `pageId`（若能确定）
|
||||
5. 若后续收到 `Browser.downloadProgress`：
|
||||
- 更新 `receivedBytes` / `totalBytes`
|
||||
- 当 state=`completed` 时写入 `finishedAt` 和可用 `savedPath`
|
||||
- 当 state=`canceled` 时更新状态
|
||||
|
||||
### Download cancel flow
|
||||
|
||||
1. `browser_cancel_download` 解析目标记录
|
||||
2. 调用 `Browser.cancelDownload`
|
||||
3. 更新 `recentDownloads` 为 `canceled`
|
||||
4. 返回取消结果摘要
|
||||
|
||||
### File input upload flow
|
||||
|
||||
1. `browser_set_file_input` 解析目标页
|
||||
2. 解析 `selector` / `nth` / `frameSelector` / `pierceShadow`
|
||||
3. 定位 DOM 节点
|
||||
4. 校验目标是 `<input type="file">`
|
||||
5. 校验所有本地文件路径存在且为普通文件
|
||||
6. 调用 `DOM.setFileInputFiles`
|
||||
7. 返回设置结果摘要
|
||||
|
||||
## Error Handling and Boundary Rules
|
||||
|
||||
### `browser_set_download_behavior`
|
||||
|
||||
- `behavior` 只能是 `accept` 或 `deny`
|
||||
- `behavior=deny` 时不接受 `downloadPath`
|
||||
- `downloadPath` 不可写时报错
|
||||
- Browser domain 下载能力不可用时报错
|
||||
|
||||
### `browser_list_downloads`
|
||||
|
||||
- `limit` 越界时回退到安全默认值
|
||||
- `pageId` 不存在时返回空列表，不报错
|
||||
|
||||
### `browser_cancel_download`
|
||||
|
||||
- `downloadId` 与 `guid` 至少传一个
|
||||
- 指定下载不存在时报错
|
||||
- 下载已完成时取消应报明确错误或返回 no-op 状态，但语义必须固定
|
||||
|
||||
### `browser_set_file_input`
|
||||
|
||||
- `pageIndex` 与 `pageId` 不能同时传
|
||||
- `selector` 不能为空
|
||||
- `files` 必须是非空数组
|
||||
- 文件不存在时报错
|
||||
- 文件路径不是普通文件时报错
|
||||
- selector 无匹配时报错
|
||||
- 多匹配但未提供 `nth` 时应保持与当前 selector 工具一致的目标解析语义
|
||||
- 命中的元素不是 `<input type="file">` 时报错
|
||||
- 跨域 iframe 不支持
|
||||
- closed shadow root 不支持
|
||||
|
||||
## Interaction with Existing Capabilities
|
||||
|
||||
### With `browser_wait_for_event`
|
||||
|
||||
Phase 8 不替换 `browser_wait_for_event(kind=download)`；它继续负责：
|
||||
|
||||
- 等待下载开始事件
|
||||
- 作为轻量事件观察能力存在
|
||||
|
||||
Phase 8 新增的下载工具负责：
|
||||
|
||||
- 设置下载策略
|
||||
- 查看下载摘要
|
||||
- 取消下载
|
||||
|
||||
### With selected page semantics
|
||||
|
||||
- 下载行为是 browser-scoped，不依赖 selected page
|
||||
- 上传行为继续遵循 selected page 解析语义
|
||||
- 这两者的作用域不同是有意设计，不属于不一致 bug
|
||||
|
||||
### With interception state
|
||||
|
||||
- 下载工具不复用 interception rule 管理面
|
||||
- 下载记录与 request summaries 是并行状态，不相互嵌套
|
||||
- 不把 download handling 强行建模成 interception action
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
Phase 8 继续扩展：
|
||||
|
||||
- `tests/unit/hooks/ccs-browser-mcp-server.test.ts`
|
||||
|
||||
并在 deterministic harness 上增加最小 download / upload 模拟能力。
|
||||
|
||||
### Required download coverage
|
||||
|
||||
1. 工具列表与 schema 暴露正确
|
||||
2. `browser_set_download_behavior` accept 成功
|
||||
3. `browser_set_download_behavior` deny 成功
|
||||
4. `behavior=deny` + `downloadPath` 报错
|
||||
5. 下载开始后 `browser_list_downloads` 能看到 started 摘要
|
||||
6. 下载完成后能看到 completed 状态与文件路径
|
||||
7. 下载取消后能看到 canceled 状态
|
||||
8. `browser_wait_for_event(kind=download)` 继续兼容
|
||||
9. `limit` 和 `pageId` 过滤生效
|
||||
|
||||
### Required upload coverage
|
||||
|
||||
1. 单文件上传成功
|
||||
2. 多文件上传成功
|
||||
3. selector 无匹配失败
|
||||
4. 命中的不是 file input 失败
|
||||
5. 文件不存在失败
|
||||
6. `frameSelector` 作用域成功
|
||||
7. `pierceShadow` 作用域成功
|
||||
8. 省略 `pageIndex/pageId` 时命中当前 selected page
|
||||
9. 显式 `pageIndex` 仍覆盖 selected page
|
||||
|
||||
### Repository validation order
|
||||
|
||||
继续遵循该区域已稳定使用的验证顺序：
|
||||
|
||||
1. focused browser MCP unit tests
|
||||
2. `bun run build:server`
|
||||
3. `bun run format`
|
||||
4. `bun run validate`
|
||||
5. `bun run validate:ci-parity`
|
||||
|
||||
## Documentation Impact
|
||||
|
||||
如果 Phase 8 实现落地，至少需要同步：
|
||||
|
||||
- `docs/browser-automation.md`
|
||||
|
||||
需要新增：
|
||||
|
||||
- Phase 8 capability details
|
||||
- 下载控制与上传示例
|
||||
- browser-scoped downloads / page-scoped uploads 的作用域说明
|
||||
- 新的 out-of-scope 边界说明
|
||||
|
||||
## Worktree Requirement
|
||||
|
||||
后续实现不应继续直接在当前 Phase 7 worktree 上混写。
|
||||
|
||||
推荐隔离方式：
|
||||
|
||||
1. 保留 `feat/browser-mcp-hover-phase7` 作为已完成 checkpoint
|
||||
2. 基于其已验证提交创建新的 Phase 8 worktree
|
||||
3. 在新 worktree 中完成 Phase 8 plan 与实现
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Phase 8 成功的标志是：
|
||||
|
||||
1. 用户可以显式控制当前 attach session 的下载接受/拒绝行为
|
||||
2. 用户可以查看近期下载摘要并取消进行中的下载
|
||||
3. 用户可以向 `<input type="file">` 设置本地文件
|
||||
4. 下载与上传能力都遵循清晰、真实的作用域语义
|
||||
5. 本期不引入 drag-and-drop、原生文件选择器接管、内容读取或 orchestration 复杂度
|
||||
|
||||
这使 Browser MCP 在当前阶段从“页面交互 + 网络拦截”扩展到“最小文件流转闭环”，为后续更高阶的录制、回放和 workflow orchestration 打下更完整的基础。
|
||||
Reference in new issue
Block a user