docs: add CLI system docs

2026-06-02 00:57:41 +08:00 · 2026-03-29 17:57:12 +08:00
parent e06925ab85
commit 3cb5a0fbd6
62 changed files with 2995 additions and 750 deletions
--- a/docs/tools/browser.mdx
+++ b/docs/tools/browser.mdx
@@ -1,25 +1,109 @@
 ---
 title: browser - 浏览器
-description: 访问和操作网页
+description: 控制浏览器访问和操作网页
 ---

-使用浏览器访问和操作网页，支持 JavaScript 渲染的动态页面。
+控制 Chromium 浏览器进行网页导航、元素交互和内容提取。支持 JavaScript 渲染的动态页面，使用精简 DOM 快照让 Agent 高效理解页面结构。

-## 依赖
+## 安装

-| 依赖 | 安装命令 |
-| --- | --- |
-| `browser-use` ≥ 0.1.40 | `pip install browser-use` |
-| `markdownify` | `pip install markdownify` |
-| `playwright` + chromium | `pip install playwright && playwright install chromium` |
+<Tabs>
+  <Tab title="CLI 安装（推荐）">
+    ```bash
+    cow install-browser
+    ```
+
+    该命令会自动完成：
+    - 安装 `playwright` Python 包（旧系统自动降级兼容版本）
+    - 在 Linux 上安装系统依赖
+    - 下载 Chromium 浏览器（Linux 服务器自动使用无头精简版）
+    - 自动检测国内网络并使用镜像加速
+  </Tab>
+  <Tab title="手动安装">
+    ```bash
+    pip install playwright
+    playwright install chromium
+    ```
+
+    Linux 服务器还需安装系统依赖：
+    ```bash
+    sudo playwright install-deps chromium
+    ```
+
+    如果系统较旧（如 Ubuntu 18.04，glibc < 2.28），需安装兼容版本：
+    ```bash
+    pip install playwright==1.28.0
+    python -m playwright install chromium
+    ```
+
+    国内网络下载 Chromium 较慢，可设置镜像加速：
+    ```bash
+    export PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright
+    python -m playwright install chromium
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+  支持 Ubuntu 20.04+、Debian 10+、macOS、Windows。Ubuntu 18.04 等旧系统会自动降级安装兼容版本。
+</Note>
+
+## 工作流程
+
+Agent 使用浏览器的典型流程：
+
+1. **`navigate`** — 打开目标 URL
+2. **`snapshot`** — 获取页面精简 DOM，交互元素自动编号（ref）
+3. **`click` / `fill` / `select`** — 通过 ref 编号操作元素
+4. **`snapshot`** — 再次快照验证操作结果
+
+## 支持的操作
+
+| 操作 | 说明 | 关键参数 |
+| --- | --- | --- |
+| `navigate` | 打开 URL | `url` |
+| `snapshot` | 获取页面结构化文本（主要方式） | `selector`（可选） |
+| `click` | 点击元素 | `ref` 或 `selector` |
+| `fill` | 填入文本 | `ref` 或 `selector`，`text` |
+| `select` | 下拉选择 | `ref` 或 `selector`，`value` |
+| `scroll` | 滚动页面 | `direction`（up/down/left/right） |
+| `screenshot` | 截图保存到工作区 | `full_page` |
+| `wait` | 等待元素或超时 | `selector`，`timeout` |
+| `press` | 按键（Enter、Tab 等） | `key` |
+| `back` / `forward` | 浏览器前进/后退 | - |
+| `get_text` | 获取元素文本内容 | `selector` |
+| `evaluate` | 执行 JavaScript | `script` |

 ## 使用场景

- 访问指定 URL 获取页面内容
- 操作网页元素（点击、输入等）
+- 访问指定 URL 获取动态页面内容
+- 填写表单、登录操作
+- 操作网页元素（点击按钮、选择选项等）
 - 验证部署后的网页效果
 - 抓取需要 JS 渲染的动态内容

+## 运行模式
+
+浏览器会根据运行环境自动选择模式：
+
+| 环境 | 模式 |
+| --- | --- |
+| macOS / Windows | 有头模式（显示浏览器窗口） |
+| Linux 桌面（有 DISPLAY） | 有头模式 |
+| Linux 服务器（无 DISPLAY） | 无头模式（headless） |
+
+可在 `config.json` 中手动覆盖：
+
+```json
+{
+  "tools": {
+    "browser": {
+      "headless": true
+    }
+  }
+}
+```
+
 <Note>
-  浏览器工具依赖较重，如不需要可不安装。轻量的网页内容获取可使用 `web-fetch` 技能。
+  浏览器工具依赖较重（~300MB），如不需要可不安装。轻量的网页内容获取可使用 `web_fetch` 工具。
 </Note>
--- a/docs/tools/index.mdx
+++ b/docs/tools/index.mdx
@@ -31,6 +31,15 @@ description: CowAgent 内置工具系统
  <Card title="memory - 记忆" icon="brain" href="/tools/memory">
    搜索和读取长期记忆
  </Card>
+  <Card title="env_config - 环境变量" icon="key" href="/tools/env-config">
+    管理 API Key 等秘钥配置
+  </Card>
+  <Card title="web_fetch - 网页获取" icon="globe" href="/tools/web-fetch">
+    获取网页或文档内容
+  </Card>
+  <Card title="scheduler - 定时任务" icon="clock" href="/tools/scheduler">
+    创建和管理定时任务
+  </Card>
 </CardGroup>

 ## 可选工具
@@ -38,13 +47,13 @@ description: CowAgent 内置工具系统
 以下工具需要安装额外依赖或配置 API Key 后启用：

 <CardGroup cols={2}>
-  <Card title="env_config - 环境变量" icon="key" href="/tools/env-config">
-    管理 API Key 等秘钥配置
-  </Card>
-  <Card title="scheduler - 定时任务" icon="clock" href="/tools/scheduler">
-    创建和管理定时任务
-  </Card>
  <Card title="web_search - 联网搜索" icon="magnifying-glass" href="/tools/web-search">
    搜索互联网获取实时信息
  </Card>
+  <Card title="vision - 图片分析" icon="eye" href="/tools/vision">
+    分析图片内容（识别、描述、OCR 文字提取等）
+  </Card>
+  <Card title="browser - 浏览器" icon="window" href="/tools/browser">
+    控制浏览器访问和操作网页
+  </Card>
 </CardGroup>
--- a/docs/tools/vision.mdx
+++ b/docs/tools/vision.mdx
@@ -0,0 +1,36 @@
+---
+title: vision - 图片分析
+description: 分析图片内容（识别、描述、OCR 等）
+---
+
+使用 Vision API 分析本地图片或图片 URL，支持内容描述、文字提取（OCR）、物体识别等。
+
+## 依赖
+
+需要配置至少一个 API Key（通过 `env_config` 工具或工作空间 `.env` 文件配置）：
+
+| 后端 | 环境变量 | 优先级 |
+| --- | --- | --- |
+| OpenAI | `OPENAI_API_KEY` | 优先使用 |
+| LinkAI | `LINKAI_API_KEY` | 备选 |
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `image` | string | 是 | 本地文件路径或 HTTP(S) 图片 URL |
+| `question` | string | 是 | 对图片提出的问题 |
+| `model` | string | 否 | 模型名称（默认 gpt-4.1-mini） |
+
+支持的图片格式：jpg、jpeg、png、gif、webp
+
+## 使用场景
+
+- 描述图片中的内容
+- 提取图片中的文字（OCR）
+- 识别物体、颜色、场景
+- 分析截图、文档扫描件
+
+<Note>
+  超过 1MB 的图片会自动压缩后上传。如果未配置任何 Vision API Key，该工具不会被加载。
+</Note>
--- a/docs/tools/web-fetch.mdx
+++ b/docs/tools/web-fetch.mdx
@@ -0,0 +1,32 @@
+---
+title: web_fetch - 网页获取
+description: 获取网页或文档内容
+---
+
+获取 HTTP/HTTPS URL 的内容。对网页提取可读文本，对文档文件（PDF、Word、Excel 等）自动下载并解析内容。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | string | 是 | HTTP/HTTPS URL（网页或文档链接） |
+
+## 支持的文件类型
+
+| 类型 | 格式 |
+| --- | --- |
+| PDF | `.pdf` |
+| Word | `.docx` |
+| 文本 | `.txt`、`.md`、`.csv`、`.log` |
+| 表格 | `.xls`、`.xlsx` |
+| 演示文稿 | `.ppt`、`.pptx` |
+
+## 使用场景
+
+- 获取网页的文本内容
+- 下载并解析远程文档
+- 获取 API 响应内容
+
+<Note>
+  `web_fetch` 只能获取静态 HTML 内容。如果页面需要 JavaScript 渲染（如 SPA 单页应用），请使用 `browser` 工具。
+</Note>