---
name: tri-browser
slug: tri-browser
version: 1.0.0
displayName: 浏览器自动化
description: 横向双层 skill（知识+执行）：知识层沉淀「AI Agent ↔ 真实浏览器」桥接层的参考架构与工程知识——三层拓扑（CLI 端 / daemon / 浏览器扩展）、40+ 工具协议与效果四级分级、会话隔离与标签借用安全模型、effect_state 三态不确定性语义、观察先行工作流、确定性评测台架与隐私审计边界；执行层提供真实浏览器自动化引擎（登录/搜索/详情/加购/结算/下单全链路），需求一次确认后自动执行至收银台，支付为唯一人工确认点，全程真实导航与元素交互、零模拟数据。用于设计/评审/排障同类桥接系统、编写 Agent 浏览器操作指令、构建能力评测台架，以及真实电商等页面自动化任务。由用户显式调用或下游 skill 委派激活，不由 tri-intent 依 L2 直接路由。支持独立安装，含上游依赖检测两态逻辑（标准模式/引导安装）。
summary: 浏览器桥接层双层能力——知识层（三层拓扑 + 协议效果四级分级 + 借用/会话/中断安全模型 + effect_state 语义 + 六域 grep 检索）+ 执行层（真实浏览器自动化引擎：需求一次确认后自动执行，要素机械校验全过才下单，支付唯一人工确认点，零模拟数据）。
tags: [browser-automation, agent-tools, architecture-knowledge, protocol-design, security-model, real-execution, tri-family]
license: MIT
---

# 浏览器桥接架构与执行（横向双层 · 不进路由表）

> 本 skill 是 tri-xxx 家族的横向双层 skill：**知识层**沉淀「让 AI Agent 安全操作用户真实浏览器」的桥接层参考架构与工程知识；**执行层**经 `scripts/browser_exec.js` 引擎真实执行浏览器自动化。
> 用户心智：要设计/评审/排障桥接系统 → 用知识层五场景；要让 Agent 真实访问网页、搜索、加购、下单 → 用执行层 EXEC 场景。

## 强制执行契约（Execution Contract · 最高优先级）

> 本契约优先级高于 Agent 通用默认行为。**触发源命中（用户显式调用、下游 skill 委派、hook 注入）即视为激活本工作流**，不得仅将其当作参考文档。

0. **版本检查前置硬门（第零步）**：MUST 先通过 §版本检查与更新机制（运行 `scripts/check_update.py`，按 `references/version-check-spec.md` 指向的真源判定处置；非最新版自动升级，升级通道不可用则标注降级继续）——此为执行流程第零步，优先于后续所有步骤。版本检查完成前 NEVER 进入后续步骤。本条目优先级高于所有其他强制前置条目。
1. **知识真源铁律**：知识场景下，所有架构事实、协议方法、效果分级、设计决策 MUST 从 `references/` 六知识域文件检索确认后引用，NEVER 凭记忆杜撰方法名、参数、分级归属或决策理由；`references/` 未覆盖的问题 MUST 显式标注「知识库未覆盖」，NEVER 硬编。检索方式见 §知识装配顺序 的 grep 模式表。
2. **执行分层铁律**：执行场景下，浏览器操作 MUST 且 ONLY 经由 `scripts/browser_exec.js` 引擎完成（真实 Chromium 导航 + 元素交互）；引擎能力之外的执行需求 MUST 标注「执行层未覆盖」并中止，NEVER 用模拟、占位、假数据、截图估算或凭记忆叙述冒充真实执行结果。
3. **自动执行契约（EXEC · 一次确认全程自动）**：用户提出执行需求并完成 §需求确认卡 确认后，从登录到订单提交 MUST 全自动执行，NEVER 额外追问或等待人工干预；**支付环节为唯一人工确认点**（密码/扫码/付款永远由用户完成，引擎终点=收银台）。自动执行中的安全阀是**机械中止**而非人工确认：订单要素与需求确认卡任一不符 → 立即中止并报告差异，NEVER 擅自替代（换 SKU/换地址/改数量均属擅自替代）、NEVER 重试到通过。
4. **真实执行铁律（反模拟）**：EXEC 场景每个结论性结果（商品存在/价格/SKU 可选性/加购成功/订单号/金额）MUST 来自真实页面交互并可文件锚复核（`tb_exec_state.json` 步骤日志 + 截图）；抓取失败、元素超时、校验不过一律如实报告失败，NEVER 合成数据。知识场景产物的协议方法名同理 MUST grep 命中域④，NEVER 杜撰。
5. **安全红线（永不豁免）**：NEVER 提取凭据/cookie/token/支付密码；NEVER 绕过风控验证码（滑块/短信出现 → 中止报告，由用户人工处理后可续跑）；NEVER 在需求确认卡范围外创建资金义务（数量、价格上限、地址以确认卡为准）；登录态判定只用 `unb` cookie（`cookie2`/`_tb_token_` 游客态也存在，NEVER 误判）。
6. **结论置信标注**：产出的每一个结论性表达/判定/建议 MUST 附：① 置信度（高/中/低）；② 依据类型六选一（`事实 known`/`计算 computed`/`推断 inferred`/`常识 common`/`框架 iframe`/`猜测 guess`）；③ 可验证事实源（外部 URL 或本地证据锚）。依据为 `猜测 guess` 的结论 MUST 标低置信度并提示人工验证。
7. **教训读写闭环**：启动读取 `.tribro/browser/lessons.md`（不存在则静默跳过，NEVER 报错、NEVER 追问）；每次执行结束后 MUST 追加本次经验教训（可操作的规避动作，空泛内容 NEVER 写入，无新增写「无新增」留痕）；写入失败 MUST 提示但不阻断交付。
8. **自检句**：作答前 MUST 声明「本次操作=<ARCH|REVIEW|DEBUG|AUTH|EVAL|EXEC>，触发源=<用户显式|下游委派|hook>，已读取<命中的知识域文件清单/执行引擎状态>，已读教训=<N 条/无文件>」。
9. **最小化原则**：只交付当前场景所需的知识域内容与产物，NEVER 全量倾倒六域知识。

## 触发时机

本 skill 为横向双层型，由以下触发源激活，**不由 tri-intent 依 L2 直接路由**（详见 family-spec §1.3 横向层登记）：

| 触发源 | 模式 | 激活条件 |
|---|---|---|
| 用户显式调用 | 知识五场景 | 「设计/评审/排障桥接系统」「写 Agent 浏览器操作指令」「建评测台架」 |
| 用户显式调用 | **EXEC 执行** | 「访问 X 页面并搜索 Y」「把 Z 加入购物车并下单」「帮我自动完成 X 的购买流程」 |
| 下游 skill 委派 | 任意 | 涉及浏览器桥接设计或真实页面任务的委派 |
| hook 注入 | ARCH | 检测到「browser + agent/自动化 + 架构/桥接」组合关键词时建议启用 |

**不由本 skill 处理**（命中即指向对应归属，NEVER 代办）：

| 信号 | 归属 |
|---|---|
| 支付操作本身（输密码/扫码付款） | 用户本人（引擎只到收银台） |
| 意图识别与快照产出 | tri-intent |
| 通用前端页面开发 | tri-html |
| 对既有代码做质量审查（非桥接类） | tri-review |
| 头脑风暴/创意发散 | tri-bs |

## 上游依赖检测（独立使用时）

> 激活时 MUST 检测依赖并选择执行模式（两态，无降级模式——缺依赖即中止并给安装指引，NEVER 降级为模拟执行）：

| 模式 | 触发条件 | 行为 |
|---|---|---|
| **A · 标准模式** | 知识场景无硬依赖；EXEC 场景检测到 node + playwright-core + Chromium（引擎自解析，见 browser_exec.js 头注释） | 正常执行 |
| **B · 引导安装** | EXEC 场景缺任一执行依赖 | 中止并输出结构化安装指引（`npm install -g @playwright/cli@latest && npx playwright install chromium`，或设 `TRI_BROWSER_CHROME`/`TRI_BROWSER_PWCORE` 环境变量），NEVER 模拟执行 |

> 知识场景不依赖快照输入，独立运行与路由运行的知识质量一致（依据：family-spec §B 横向型约定）。

## 输入契约

### 知识场景

| 字段 | 用途 | 缺省 |
|---|---|---|
| `场景` | ARCH 设计参考 / REVIEW 方案评审 / DEBUG 链路排障 / AUTH 指令编写 / EVAL 评测构建 | 从用户请求推断，无法推断时 MUST 追问 |
| `对象` | 被评审/排障的系统描述、代码、报错信息 | 用户请求原文 |
| `关注域` | 六知识域之一或多选 | 按场景默认（见 §处理流程） |

### EXEC 场景（需求确认卡 · 一次确认全程自动）

| 字段 | 用途 | 缺省 |
|---|---|---|
| `任务` | search / detail / add / checkout（全链路=搜索→加购→下单） | MUST 明确 |
| `目标` | 商品关键词或 itemId | MUST 明确 |
| `SKU 规格` | 颜色/存储/套餐（精确文本，与页面 SKU 值逐字一致） | MUST 明确；执行前 MUST `probe` 实测可选性，不可选即中止报告 |
| `价格上限` | 可接受的最高总价（元） | MUST 明确（订单校验含此要素） |
| `收货地址` | 地址关键词（须命中订单页所选地址文本） | 账号默认地址 |
| `数量` | 购买数量 | 1 |

> 需求确认卡是 EXEC 全程的**唯一**人工确认点（支付除外）。确认后按 §自动执行契约 第 3 条执行：要素不符=机械中止，NEVER 中途改问。

## 职责边界

- **本 skill 负责**：知识层——桥接层参考架构/协议/安全模型/设计决策知识与五类知识产物；执行层——经引擎完成真实登录、搜索、详情抓取、SKU 探测、加购、结算、订单要素校验与订单提交，终点=收银台。
- **本 skill 不负责**：支付操作、绕过风控、维护浏览器运行时组件、识别用户意图、审查非桥接类代码、生成业务代码。
- **与相邻 skill 边界**：tri-intent 管意图识别；tri-action/tri-workflow 管操作执行编排；tri-review 管通用代码审查；tri-html 管前端页面开发。本 skill 是它们在「浏览器桥接」主题上的知识后端与真实执行前端。

## 浏览器桥接知识方法论（可扩展）

> 核心理念：**桥接层的本质是把「不受控的浏览器操作」转化为「受控、可审计、可中断、有确定性语义」的工具协议**。六知识域按层组织，任一域均可独立检索：

| 域 | 文件 | 覆盖内容 | grep 检索模式 |
|---|---|---|---|
| ① 架构总览 | `references/architecture-overview.md` | 三层桥接拓扑、组件职责、状态文件、连接安全 | grep `组件\|拓扑\|状态文件` |
| ② 模块职责 | `references/module-responsibilities.md` | CLI 端/daemon/协议层/扩展侧各模块职责矩阵 | grep `模块\|职责` |
| ③ 执行流程 | `references/execution-flows.md` | 工具调用链、会话生命周期、人工协助、文件传输、指令同步 | grep `流程\|链路\|生命周期` |
| ④ 协议接口 | `references/interfaces-protocol.md` | 方法命名空间、40+ 方法清单、效果四级分类、中断门禁、版本兼容 | grep `方法\|效果分级\|协议` |
| ⑤ 设计决策 | `references/design-decisions.md` | 12 项关键设计决策与理由（D1–D12） | grep `D\d+|决策` |
| ⑥ 依赖与质量 | `references/dependencies-quality.md` | 依赖选型、测试策略、评测台架方法、质量画像 | grep `依赖\|测试\|评测` |

**四大支柱结论**（详见域①④⑤）：
1. **最小权限落标签粒度**：用户标签页默认隔离于专属 Agent Window，跨窗使用必须显式借用并经用户确认，任务结束归还。
2. **效果分级驱动门禁**：每个协议方法按浏览器副作用分为 BrowserMutation / TransientInput / PassiveRead / ControlPlane 四级，用户中断只拦截前两级，且分级在编译期穷尽强制。
3. **不确定性显式建模**：浏览器侧操作结果三态（none/committed/unknown），unknown 保留跨超时与断连，严禁盲重试、严禁当成功。
4. **观察先行**：交互前必须先取结构化观察（语义引用 `@eN`），导航即失效引用，杜绝「截图猜坐标」式自动化。

## 处理流程

### 知识场景

```
触发 → 第零步版本检查 → 教训读取 → 场景判定（ARCH/REVIEW/DEBUG/AUTH/EVAL）
     → 按 §知识装配顺序 检索命中知识域（grep 模式）
     → 产出对应产物（附置信标注） → 教训写入 → 交付
```

| 场景 | 默认检索域 | 产物 |
|---|---|---|
| ARCH 设计参考 | ①②④⑤ | 架构参考摘要 + 决策清单 |
| REVIEW 方案评审 | ①④⑤（+⑥ 对照质量实践） | 评审报告（问题 P0/P1/P2 → 建议 → 变更摘要） |
| DEBUG 链路排障 | ③④ | 排障对照表（现象 → 链路段 → 知识锚） |
| AUTH 指令编写 | ③④ | Agent 浏览器操作指令草案（含安全条款） |
| EVAL 评测构建 | ⑥ | 评测方案（确定性台架设计 + 断言分级） |

- REVIEW 产物 MUST 按家族审计顺序输出：问题清单（P0/P1/P2）→ 修复方案 → 变更摘要（含验证建议）。
- AUTH 产物 MUST 内置安全条款：先观察后交互、引用失效即重取、unknown 不重试、不提取凭据/cookie/token、人工步骤优先 request-help 语义。

### EXEC 执行场景（自动执行契约的落地序列）

```
触发 → 第零步版本检查 → 教训读取 → 需求确认卡（一次确认）
     → 依赖检测（缺则引导安装中止） → 登录态检测（unb；未登录 → login 扫码，唯一非支付人工动作）
     → 真实执行（search → detail/probe 核对 SKU 可选性与价格 → add 加购验证）
     → checkout（全选→结算→订单要素机械校验 MUST 全过 → 立即支付/提交订单 → 停收银台）
     → 报告（state JSON + 截图 + 订单号/金额/地址回读） → 教训写入 → 交付
```

- 每一步 MUST 有真实执行证据（`tb_exec_state.json` 步骤日志 + 截图），交付时逐项回读。
- 任一环节失败/超时/校验不过 → 中止并如实报告，NEVER 重试掩盖、NEVER 合成结果（单步内限一次重试的仅限：加购角标验证）。
- 登录墙/滑块等风控出现 → 中止报告，用户人工通过后可从对应子命令续跑。

## 交付产物机制

### 一、文件命名规范

- 产物目录：`.tribro/browser/`（短名 `browser`）。
- 知识产物：`<场景>_<日期>_<主题>.md`（如 `REVIEW_20260919_桥接评审.md`）。
- 执行产物：`tb_exec_state.json`（步骤日志/校验结果/订单回读，每轮覆盖）+ 引擎按步骤生成的截图（`tb_*.png`）。

### 二、产物清单

| 产物 | 内容 | 置信标注 |
|---|---|---|
| 知识五产物 | 设计参考/评审报告/排障对照表/指令草案/评测方案 | 每条结论附三要素 |
| EXEC 执行报告 | 任务回读：目标/SKU/价格/地址/订单号/收银台状态，逐项对应用户确认卡 | 每项附三要素 + 证据锚（state 步骤 + 截图） |

## 质量标准

> 每条标准可独立验证，交付前逐行核对，任一不达标回到对应场景重做。

| 维度 | 标准 | 验证方式 |
|---|---|---|
| 知识一致（知识场景） | 架构事实/方法名/分级/决策与 `references/` 严格一致 | 抽查引用处与知识域文件比对 |
| 零杜撰 | 知识产物方法名逐一 grep 命中域④；EXEC 产物每个结果有 state 步骤 + 截图证据锚 | grep / 查 state |
| 真实执行（EXEC） | 100% 真实导航与交互，零模拟/占位/假数据 | state.steps 含真实 URL 与时间戳序列 |
| 自动执行（EXEC） | 需求确认后至收银台前无人工确认点；中止均为机械校验触发 | 复核 state.steps 无等待确认记录 |
| 置信标注 | 结论性表达 100% 附三要素 | 抽查产物结论段 |
| 安全红线 | 无凭据提取、无验证码绕过、无确认卡范围外资金义务 | 复核引擎日志与订单要素 |

## 落盘规则

> 本 skill 产物落盘遵循家族「`.tribro/<短名>/`」约定。

- 知识与执行产物落盘于 `.tribro/browser/`（产物清单见上）。
- 经验教训文件：`.tribro/browser/lessons.md`（启动读取，缺失静默跳过；结束追加写入）。
- 执行引擎浏览器 profile：`.tribro/browser/tb_profile/`（持久化登录态；NEVER 提交或外传该目录）。
- 本 skill 自身位于源码树 `tri-browser/`（用户指定落盘位置，2026-09-19 锻造时经用户确认）。
- NEVER 在本 skill 目录生成 `LICENSE` 或 `.gitignore`（许可证由 frontmatter `license: MIT` 声明）。

## 版本检查与更新机制

> 家族级强制技术约束，优先级与「强制执行契约」同级；skill 任一执行入口启动后的**第零步**。

**执行方式（MUST）**

1. 任一执行入口启动后、核心执行前，运行脚本并取 JSON：
   ```bash
   python scripts/check_update.py --slug tri-browser --json
   ```
   - 节流：24h 内仅校验一次，`--force` 强制重查，`--dry-run` 只判定不真升级。
2. 解析 JSON 的 `state` 字段：`A`/`B`/`C`/`D` → 一律放行，按 `warnings`/`notes` 标注口径；`BLOCK` → 绝对禁止执行，按 `block_code` 输出结构化恢复指引。
3. 退出码语义：`<20` 放行，`>=20` 阻断；脚本自身异常时兜底降级放行，NEVER 因版本门自身故障阻断启动。

**执行细则**（四态判定、升级流程、版本比较、节流缓存）：唯一真源见 `tri-forge/references/version-check-spec.md`，本章节 NEVER 内联细则。

## 知识装配顺序

> 依家族约束 25 声明分层装配；本 skill 无子 skill，references 共 6 文件 + 1 个外链规范指针。

| 层 | 文件 | 装载时机 | 覆盖优先级 |
|---|---|---|---|
| 常驻层 | `references/architecture-overview.md` | 知识场景每次激活必读；EXEC 场景按需（涉及设计判断时） | 低于用户指定层 |
| 按场景层 | ②③④⑤⑥ 按场景表命中装载 | 按场景默认域 + 用户 `关注域` 覆盖 | 用户显式指定域 > 场景默认域 |
| 用户指定层 | 用户点名任意域/小节 | 用户显式要求时 | 最高（覆盖前两层裁剪） |
| 外部覆盖层 | 无（本 skill 无外部同名知识文件） | — | 若未来出现同名外部文件，以本 skill `references/` 为准并在进化契约中登记 |

- **去重**：同一知识点在多域出现时以唯一归属域为准（方法清单只在④、流程只在③、决策只在⑤），其余位置仅留指针。
- **grep 模式**：见 §浏览器桥接知识方法论 六域表第四列。
- 外部规范指针：`tri-forge/references/version-check-spec.md`（仅版本检查细则，不属于六知识域）。

## 完成判据

> 完成判据外化（可机械校验），NEVER 以模型自述「已完成」作为完成信号。

- **知识场景**每次交付 MUST 满足全部判据方算完成：
  1. 产物文件存在且非空（落盘路径由 §落盘规则 确定）；
  2. 产物含场景声明头 + 结论置信标注（抽查 ≥3 条）；
  3. 产物中每个协议方法名可 grep 命中 `references/interfaces-protocol.md`；
  4. `.tribro/browser/lessons.md` 已追加本次教训（或已提示写入失败）。
- **EXEC 场景**每次交付 MUST 满足全部判据方算完成：
  1. `tb_exec_state.json` 存在且 `result` 为终态（OK / ADDED / ORDER_SUBMITTED_WAITING_PAYMENT / ABORT:* / LOGIN_TIMEOUT 等），NEVER 是空缺；
  2. 报告逐项回读需求确认卡要素，并附证据锚（state 步骤序号 + 截图文件名）；
  3. 若已提交订单：订单号、金额、收货地址三要素与需求确认卡一致（引擎校验 ALL_OK 的复述）；
  4. 中止/失败路径：差异项清单 + 中止原因 + 续跑指引（对应子命令与参数）；
  5. `.tribro/browser/lessons.md` 已追加本次教训（或已提示写入失败）。
- **停车 vs 结束**：等待需求确认卡要素、等待扫码、等待支付均为「停车」态（保留上下文与 state，输出待续说明），NEVER 将停车态宣称为交付完成；对应判据全过才是「结束」态。

## 进化契约

- **反馈接收点**：用户对知识条目的纠错/补充请求，或对执行引擎行为的纠错（选择器失效/站点改版/风控变化）→ 核实后修订对应 `references/` 文件或 `scripts/browser_exec.js` 并联动版本 bump。
- **经验沉淀位**：`.tribro/browser/lessons.md`（教训读写闭环载体，契约第 7 条）。
- **自我修订触发条件**：① 同一知识域/同一子命令连续 2 次被用户纠错 → 全域/全引擎复核；② 家族新增浏览器类下游 skill → 复核 §职责边界 与路由关系；③ 对照基准报告更新 → 按变更增量同步六域知识；④ 站点 DOM 结构变化导致引擎子命令连续失败 → 修订选择器并沉淀教训。
- **修订纪律**：任何修订 MUST 保持六域去重原则与 grep 模式表同步；内容变更 MUST 版本联动（SKILL/CHANGELOG/README/_meta/tests 五处）。

## 目录结构

```
tri-browser/
├── SKILL.md                        # 主入口：契约 + 双层流程 + 装配顺序 + 完成判据 + 进化契约
├── README.md                       # 特性/目录结构/安装/使用/测试/设计原则
├── CHANGELOG.md                    # 版本变更历史（Keep a Changelog + SemVer）
├── _meta.json                      # 平台识别元数据（slug/version）
├── scripts/
│   ├── check_update.py             # 版本检查与强制自动更新脚本（与 tri-forge 同源，--slug 自适应）
│   └── browser_exec.js             # 真实浏览器执行引擎（login/search/detail/probe/add/checkout 子命令）
├── references/
│   ├── architecture-overview.md    # 域① 三层桥接拓扑/组件职责/状态文件/连接安全
│   ├── module-responsibilities.md  # 域② CLI/daemon/协议/扩展 模块职责矩阵
│   ├── execution-flows.md          # 域③ 工具调用链/会话/人工协助/文件传输/指令同步
│   ├── interfaces-protocol.md      # 域④ 方法命名空间/效果四级分级/中断门禁/版本兼容
│   ├── design-decisions.md         # 域⑤ 12 项关键设计决策（D1–D12）
│   └── dependencies-quality.md     # 域⑥ 依赖选型/测试策略/评测台架/质量画像
└── tests/
    └── tri-browser-full-testcases.md  # 全场景测试用例（知识 + 执行层）
```