> ## 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.

# 插件工具体系总览

> Profy 三层交互工具架构：computer、browser、chrome

# 三层交互工具体系

Profy 提供三层交互工具，覆盖从像素级桌面操控到 DOM 感知浏览器控制的完整谱系。每层工具使用统一的 `tool(action=...)` 调用范式。

## 架构总览

```mermaid theme={null}
graph TB
    subgraph layers ["三层交互工具"]
        computer["computer(action=...)"]
        browser["browser(action=...)"]
        chrome["chrome(action=...)"]
    end

    subgraph backends ["执行后端"]
        cloud["Cloud Sandbox (CDP + noVNC)"]
        desktop["Desktop (Electron CUA)"]
        ext["Chrome Extension (Native Messaging)"]
    end

    computer -->|"Cloud: noVNC pixel"| cloud
    computer -->|"Desktop: sky.* 等效"| desktop
    browser -->|"Cloud: CDP on sandbox Chromium"| cloud
    browser -->|"Desktop: Electron in-app browser"| desktop
    chrome -->|"Desktop + Extension"| ext
```

## 三层对比

| 层            | 工具名                    | 作用域       | 感知方式                     | 后端                             |
| ------------ | ---------------------- | --------- | ------------------------ | ------------------------------ |
| **computer** | `computer(action=...)` | 整个屏幕/窗口   | 像素级截图 + 坐标               | Cloud: noVNC / Desktop: CUA    |
| **browser**  | `browser(action=...)`  | 受控浏览器     | DOM + Accessibility Tree | Cloud: CDP / Desktop: Electron |
| **chrome**   | `chrome(action=...)`   | 用户 Chrome | DOM + Accessibility Tree | Chrome Extension CDP           |

## 使用场景选择

### 使用 `computer` 的场景

* 操作原生桌面应用（Finder、Terminal、IDE）
* 游戏自动化
* 任何非浏览器的 GUI 应用
* 需要屏幕级截图验证

### 使用 `browser` 的场景

* 浏览公开网页
* 测试开发中的网站（localhost）
* 网页数据抓取
* 表单自动填写（无需登录态）
* 3D/WebGL 场景的视觉验证

### 使用 `chrome` 的场景

* 需要用户已登录态的操作
* 访问需要认证的内部系统
* 代替用户完成已登录网站上的操作
* 安全的凭证管理

## 统一调用范式

所有三层工具共享相同的调用模式：

```python theme={null}
# 截图
computer(action="screenshot")
browser(action="screenshot", url="http://localhost:5173")
chrome(action="screenshot")

# 点击
computer(action="click", x=100, y=200)
browser(action="click", ref="button[0]")
chrome(action="click", ref="button[0]")

# 输入
computer(action="type", text="Hello")
browser(action="type", ref="input[0]", text="Hello")
chrome(action="type", ref="input[0]", text="Hello")
```

## 后端多态性

同一个工具名在不同执行环境下路由到不同后端：

* **Cloud Sandbox**：`computer` → noVNC 像素流，`browser` → CDP 协议
* **Desktop**：`computer` → macOS CUA 守护进程，`browser` → Electron webview
* **Chrome Extension**：`chrome` → Native Messaging → Extension CDP

Agent 编写者无需关心底层后端差异，只需选择正确的工具层级。

## 确认策略

| 工具         | 确认策略  | 原因        |
| ---------- | ----- | --------- |
| `computer` | 视操作而定 | 可能影响系统    |
| `browser`  | 不需要   | 完全沙箱隔离    |
| `chrome`   | 4 级确认 | 操作用户真实浏览器 |

## 相关文档

<CardGroup cols={3}>
  <Card title="Computer Use" icon="display" href="/zh/documentation/plugins/computer">
    像素级桌面控制
  </Card>

  <Card title="Browser" icon="globe" href="/zh/documentation/plugins/browser">
    DOM 感知浏览器控制
  </Card>

  <Card title="Chrome Extension" icon="chrome" href="/zh/documentation/plugins/chrome">
    用户 Chrome 浏览器控制
  </Card>

  <Card title="渲染面" icon="window-maximize" href="/zh/documentation/plugins/rendering-surfaces">
    八种内容展示通道
  </Card>

  <Card title="A2UI" icon="grid-2" href="/zh/documentation/plugins/a2ui">
    声明式交互 UI 组件
  </Card>

  <Card title="视频制作" icon="video" href="/zh/documentation/plugins/video-production">
    AI 视频制作管线与时间线编辑
  </Card>

  <Card title="3D 与可视化" icon="cube" href="/zh/documentation/plugins/3d-development">
    数据可视化、3D 场景与游戏开发
  </Card>
</CardGroup>