> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Chrome Extension

> chrome(action=...) — 用户 Chrome 浏览器控制工具

# Chrome Extension

`chrome(action=...)` 通过 Chrome Extension + Native Messaging 控制用户的真实 Chrome 浏览器，可以利用用户已登录的会话执行操作。

## 概述

Chrome 工具是最高层的浏览器交互工具——它连接到用户真实的 Chrome 浏览器，可以操作用户已登录的网站。由于涉及用户真实数据和认证状态，所有写操作遵循 4 级确认策略。

## 架构

```mermaid theme={null}
sequenceDiagram
    Agent->>+Runtime: chrome(action="...")
    Runtime->>+Desktop: WebSocket
    Desktop->>+Extension: Native Messaging
    Extension->>+Chrome: CDP
    Chrome-->>-Extension: Result
    Extension-->>-Desktop: Response
    Desktop-->>-Runtime: Response
    Runtime-->>-Agent: Tool Result
```

## 可用 Actions

| Action         | 说明                    | 关键参数                      |
| -------------- | --------------------- | ------------------------- |
| `list_tabs`    | 列出所有打开的标签页            | —                         |
| `claim_tab`    | 接管一个标签页               | `tab_id`                  |
| `navigate`     | 导航到 URL               | `url`, `new_tab`          |
| `screenshot`   | 当前标签页截图               | `full_page`               |
| `click`        | 点击元素                  | `selector`/`ref`          |
| `type`         | 逐键输入                  | `selector`/`ref`, `text`  |
| `fill`         | 瞬间设置值                 | `selector`/`ref`, `text`  |
| `extract`      | 提取页面内容                | `selector`                |
| `scroll`       | 滚动                    | `direction`, `amount`     |
| `press_key`    | 按键                    | `key`                     |
| `execute_js`   | 执行 JavaScript         | `code`                    |
| `snapshot`     | 获取 Accessibility Tree | `selector`                |
| `browser_auth` | 安全凭证操作                | `auth_action`, `auth_uri` |

## Tab 生命周期

Chrome 工具使用 **claim-based** 模型防止误操作：

```python theme={null}
# 1. 发现
chrome(action="list_tabs")
# → [{id: "tab1", url: "https://github.com", title: "GitHub"}...]

# 2. 接管
chrome(action="claim_tab", tab_id="tab1")

# 3. 交互
chrome(action="extract", selector="main")
chrome(action="screenshot")

# 4. 释放（自动）
```

## 确认策略（4 级）

### Level 1: 必须交接（Hand-Off Required）

Agent 必须停止并要求用户亲自完成：

* 密码修改或重置
* 绕过安全警告
* 大额金融交易
* 删除账号或关键数据
* 授权新应用 OAuth 权限

### Level 2: 需要确认（Confirmation Required）

Agent 需要用户明确确认后才能执行：

* CAPTCHA 验证（让用户完成）
* 不可逆删除（邮件、文件、消息）
* 安装未知来源软件
* 创建新凭证或 API Key
* 公开发布（社交媒体、论坛）

### Level 3: 可预批准（Pre-Approval Allowed）

如果用户已预先批准该任务类型，可直接执行：

* 保存密码提示
* 创建非关键账号
* 修改非安全设置
* 确认受信任站点登录

### Level 4: 无需确认（Not Required）

Agent 可自由执行：

* 只读浏览和导航
* 关闭 Cookie 弹窗
* 滚动和查看内容
* 截图
* 提取文本

## 安全凭证管理（browser\_auth）

`browser_auth` 子系统提供安全的凭证操作，敏感数据始终保留在 Extension 的安全存储中，**永不**暴露给模型。

```python theme={null}
# 检查是否有存储的凭证（返回 true/false，不返回密码）
chrome(action="browser_auth", auth_action="get_credentials", auth_uri="https://github.com")

# 提示用户保存凭证（Extension 显示原生弹窗）
chrome(action="browser_auth", auth_action="store_credentials", auth_uri="https://github.com")

# 清除会话
chrome(action="browser_auth", auth_action="clear_session", auth_uri="https://github.com")
```

## 安全约束

以下操作**绝对禁止**：

* ❌ 返回 cookie、token 或会话数据到对话
* ❌ 在 browser\_auth 通道外存储或记录凭证
* ❌ 导航到钓鱼或已知恶意 URL
* ❌ 绕过 2FA 或安全挑战
* ❌ 访问 `chrome://` 内部页面
* ❌ 修改浏览器设置或扩展

## 先决条件

使用 `chrome` 工具需要：

1. **Profy Desktop** 应用运行中
2. **Profy Browser Extension** 已安装并启用
3. Chrome 浏览器运行中

如果 `list_tabs` 失败，引导用户检查以上条件。

## 使用场景示例

### 读取用户正在查看的页面

```python theme={null}
chrome(action="list_tabs")
chrome(action="claim_tab", tab_id="TAB_ID")
chrome(action="extract")
```

### 自动填写表单

```python theme={null}
chrome(action="claim_tab", tab_id="TAB_ID")
chrome(action="snapshot")
chrome(action="fill", ref="input[0]", text="John Doe")
chrome(action="fill", ref="input[1]", text="john@example.com")
# ⚠️ 需要用户确认后才能提交
chrome(action="click", ref="button[0]")
```

### 研究并提取内容

```python theme={null}
chrome(action="navigate", url="https://docs.example.com/api", new_tab=true)
chrome(action="extract", selector="main")
```