Skip to content

browser-validation.md

Latest commit

 

History

History
172 lines (116 loc) · 9.74 KB

browser-validation.md

File metadata and controls

172 lines (116 loc) · 9.74 KB
Raw

Browser Validation Protocol（浏览器验证协议）

由 AGENTS.md §Browser Validation Protocol 锚定的浏览器自动化与认证态使用协议。本协议是工程行为准则的子集，任何 AI Agent 在执行浏览器自动化任务前必须完整遵循。

协议版本：v1.0 ｜ 生效范围：所有面向本仓库的 AI Agent 协作场景

关联工具：chrome-devtools MCP、claude-in-chrome MCP、playwright MCP

[TOC]

1. 协议目的

为 AI Agent 在浏览器自动化场景下提供统一、可审计、不可绕过的认证态使用规范，解决以下问题：

  • AI Agent 不应也不可代用户决策"我是谁"——所有登录态归属问题必须由用户本人主导
  • 浏览器自动化能力一旦失控，可能在用户毫不知情时产生不可撤销的副作用（消息发送、订单提交、权限变更等）
  • OAuth / SSO 同意屏在自动化上下文中存在被绕过的潜在风险，违反平台 ToS 与基本伦理

本协议通过"原则—红线—操作流程—验证"四层结构，将上述问题约束在工程可控范围内。

2. 核心原则

原则 具体含义
登录态归属于用户 Agent 不得自行完成、绕过或模拟任何 OAuth / SSO 认证流程；所有登录态来源于用户已认证的 Chrome 主 profile
真实主 profile 优先 浏览器自动化默认接入用户日常使用的 Chrome 主 profile，复用其 Cookie / Session / SSO 状态
可审计、可回放 浏览器路径关键操作（点击、表单填写、跳转）应留下可被 GIF 回放或日志追溯的痕迹
最小副作用 优先以只读方式（查看、提取、断言）完成任务；写操作（提交、发送）需在协议第 5 节框架下显式确认

3. 安全红线

以下条款不可协商，违反任一条款即视为协议违反。

  1. 禁止跳转 Google 同意屏：在 Sandbox / 自动化浏览器环境内严禁触发 Google OAuth 同意屏跳转。同意屏只能在用户主 profile 的真实浏览会话中由用户本人完成。
  2. 禁止模拟身份：禁止以模拟用户身份、虚构 Cookie、第三方账号或测试账号替代真实登录态完成任务。
  3. 禁止凭证泄露：禁止要求用户在 chat 中粘贴密码、Cookie、Session Token、二维码扫描结果或任何形式的验证码（含 6 位数字、短信、TOTP）。
  4. 禁止跨账号操作：在多用户环境下，Agent 不得在未经显式确认的情况下切换 profile 或账号身份。
  5. 禁止规避 ToS：不得通过 Headless 模式、UA 伪装、Captcha 自动求解等方式规避目标站点的服务条款。
  6. 禁止下载执行：浏览器路径触发的任何文件下载需在主对话中显式确认；下载文件不得自动执行或注入到项目目录。

4. 连通性自检（Connectivity Probe）

执行浏览器自动化任务前，Agent 必须完成以下自检序列：

步骤 操作 通过判据
4.1 工具可用性 列出当前会话可用的 MCP 工具 至少存在 chrome-devtools / claude-in-chrome 之一
4.2 主 profile 加载 通过工具调用获取当前 Tab 列表或 Page 列表 返回非空，且 Tab 标题来自用户真实浏览历史而非空白会话
4.3 目标域名可达 通过 navigate_page 或 browser_navigate 访问目标域名首页 HTTP 200 / 已登录态正常加载
4.4 登录态识别 在目标域名首页定位"已登录"标识（头像、用户名、退出按钮） 能在 Snapshot / AOM 中找到一致标识
4.5 异常路径分类 若 4.4 失败，按"未登录 vs 会话过期 vs 拒绝服务"分类，不自动重登 输出明确分类，转入第 5 节的用户接力流程

失败处置：自检任一步骤失败，Agent 必须停止任务、向用户输出诊断结论，不得尝试 OAuth / 凭证补救。

5. 凭证管理（Credential Lifecycle）

5.1 发现路径

凭证通过以下路径被动发现，Agent 不主动读取、导出或日志化：

  • 浏览器 Cookie / LocalStorage（仅由浏览器引擎内部使用）
  • 浏览器扩展（如 Claude in Chrome）持有的 Session
  • 用户在 chat 中以"我刚登录了 X"形式给出的事实陈述（非凭证本身）

5.2 过期检测信号

信号 处置
HTTP 401 / 403 转 5.3 接力流程
重定向到登录页（含 /login、/signin） 转 5.3 接力流程
同意屏触发（OAuth scope 变更） 立即停止，由用户在主 profile 完成同意
Captcha 出现 立即停止，输出"需用户介入"

5.3 用户接力流程（Re-authentication Handoff）

1. Agent 检测到登录态失效
2. Agent 向用户输出：（a）失效域名 （b）建议在用户主 profile 完成登录的指引
3. Agent 暂停浏览器任务，**不**触发任何登录流程
4. 用户在真实浏览器完成登录后，回到 chat 通知 Agent
5. Agent 重新执行第 4 节连通性自检
6. 自检通过后恢复任务

5.4 凭证刷新约束

  • Agent 不调用任何 refresh_token / device_code 接口
  • Agent 不触发邮箱链接、短信验证码、TOTP 输入
  • 凭证刷新由用户在原始登录路径自主完成

6. E2E 集成（End-to-End Integration）

6.1 与项目 OAuth 模块的边界

本项目内置 GitHub Device Flow 与 Google OAuth 模块（src/coding/proxy/auth/）。浏览器协议与之的边界如下：

  • 项目 OAuth 模块：服务端运行时凭证管理，由 coding-proxy auth login/reauth CLI 触发，目标是给 proxy 自身获取上游 API 凭证
  • 本协议：客户端浏览器自动化场景，目标是让 Agent 协助用户完成日常任务（如查文档、填表单）

二者互不调用：Agent 不调用 coding-proxy auth 替用户完成项目 OAuth；项目 OAuth 流程也不依赖本协议第 4 节自检。

6.2 与 CLI 命令的协同

场景 由谁触发
给 proxy 注入 GitHub PAT 用户运行 auth login
给 proxy 注入 Google OAuth 用户运行 auth login
凭证过期重认证 用户运行 auth reauth
浏览器查看 GitHub Token 状态 Agent 通过本协议浏览器访问

6.3 测试用例的浏览器隔离

  • 单元测试（tests/unit/）不触发任何浏览器路径
  • 集成测试（tests/integration/）不触发任何浏览器路径
  • 浏览器路径仅在交互式 Agent 会话中触发，不进入 CI 自动化测试链路

7. 实机回归（Real-Device Regression）

7.1 提交前的浏览器路径自检清单

涉及浏览器路径的改动在提交前需手工核验：

  • 第 4 节连通性自检在用户主 profile 通过
  • 第 3 节安全红线未被触碰（特别是同意屏、密码粘贴）
  • 浏览器路径的关键操作有 GIF / Snapshot 留痕
  • 失败路径输出明确的用户接力指引

7.2 与 CI 的边界

CI 流水线（详见 ops/ci-cd.md）不触发浏览器自动化路径。所有浏览器侧验证均在本地实机完成。

7.3 回归失败上报

若实机回归失败：

  1. 在 docs/issue.md 记录现象、根因、防范
  2. 若涉及协议本身缺陷，提交 PR 修订本文件并同步 AGENTS.md 锚点
  3. 不通过的 Agent 行为应在 knowledge-map.md 标注为已知问题

8. 引用规范

附录 A：术语对照

术语 说明
主 profile 用户日常使用的 Chrome / Edge 浏览器档案，含真实登录态
Sandbox 浏览器 自动化工具启动的临时/隔离浏览器，无真实用户态
同意屏（Consent） OAuth 流程中用户授予权限范围的页面
接力流程 Agent 停止 → 用户介入完成 → Agent 恢复 的三段式协作
实机回归 在用户真实终端（非 CI）完成的端到端验证