docs: make English the default docs language and fix link paths

2026-07-19 12:47:25 +08:00 · 2026-05-31 17:52:22 +08:00
parent 126649f70f
commit 7bf4ef3d05
231 changed files with 8999 additions and 8974 deletions
--- a/docs/zh/tools/bash.mdx
+++ b/docs/zh/tools/bash.mdx
@@ -0,0 +1,28 @@
+---
+title: bash - 终端
+description: 执行系统命令
+---
+
+在当前工作目录执行 Bash 命令，返回 stdout 和 stderr。`env_config` 中配置的 API Key 会自动注入到环境变量中。
+
+## 依赖
+
+无额外依赖，默认可用。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `command` | string | 是 | 要执行的命令 |
+| `timeout` | integer | 否 | 超时时间（秒） |
+
+## 使用场景
+
+- 安装软件包和依赖
+- 运行代码和测试
+- 部署应用和服务（Nginx 配置、进程管理等）
+- 系统运维和排查
+
+<Frame>
+  <img src="https://cdn.link-ai.tech/doc/20260203121008.png" width="800" />
+</Frame>
--- a/docs/zh/tools/browser.mdx
+++ b/docs/zh/tools/browser.mdx
@@ -0,0 +1,172 @@
+---
+title: browser - 浏览器
+description: 控制浏览器访问和操作网页
+---
+
+控制 Chromium 浏览器进行网页导航、元素交互和内容提取。支持 JavaScript 渲染的动态页面，使用精简 DOM 快照让 Agent 高效理解页面结构。
+
+## 安装
+
+<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>
+  1. 支持 Ubuntu 20.04+、Debian 10+、macOS、Windows。Ubuntu 18.04 等旧系统会自动降级安装兼容版本。
+  2. 浏览器工具依赖较重（约300MB），为可选安装。轻量的网页内容获取可使用 `web_fetch` 工具。
+</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 获取动态页面内容
+- 填写表单、登录操作
+- 操作网页元素（点击按钮、选择选项等）
+- 验证部署后的网页效果
+- 抓取需要 JS 渲染的动态内容
+
+## 运行模式
+
+浏览器会根据运行环境自动选择模式：
+
+| 环境 | 模式 |
+| --- | --- |
+| macOS / Windows | 有头模式（显示浏览器窗口） |
+| Linux 桌面（有 DISPLAY） | 有头模式 |
+| Linux 服务器（无 DISPLAY） | 无头模式（headless） |
+
+可在 `config.json` 中手动覆盖：
+
+```json
+{
+  "tools": {
+    "browser": {
+      "headless": true
+    }
+  }
+}
+```
+
+## 登录态持久化
+
+**只需登录一次目标网站，Agent 后续可直接使用**。提供两种方式：
+
+### 方式一：Persistent 模式（默认）
+
+开箱即用，登录信息保存在 `~/.cow/browser_profile`。无需任何配置。
+
+如需关闭持久化模式，每次都用纯净环境：
+
+```json
+{
+  "tools": {
+    "browser": {
+      "persistent": false
+    }
+  }
+}
+```
+
+### 方式二：CDP 模式（接管真实 Chrome）
+
+让 Agent 连接独立启动的真实 Chrome（而非 Playwright 自带的 Chromium），获得完整浏览器指纹，适合反爬严格的网站。
+
+启动 Chrome 时加上调试端口和独立用户目录：
+
+<Tabs>
+  <Tab title="macOS">
+    ```bash
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+      --remote-debugging-port=9222 \
+      --user-data-dir="$HOME/.cow/chrome-cdp"
+    ```
+  </Tab>
+  <Tab title="Linux">
+    ```bash
+    google-chrome \
+      --remote-debugging-port=9222 \
+      --user-data-dir="$HOME/.cow/chrome-cdp"
+    ```
+  </Tab>
+  <Tab title="Windows">
+    ```powershell
+    & "C:\Program Files\Google\Chrome\Application\chrome.exe" `
+      --remote-debugging-port=9222 `
+      --user-data-dir="$env:USERPROFILE\.cow\chrome-cdp"
+    ```
+  </Tab>
+</Tabs>
+
+在 `config.json` 中配置端点：
+
+```json
+{
+  "tools": {
+    "browser": {
+      "cdp_endpoint": "http://localhost:9222"
+    }
+  }
+}
+```
+
+<Note>
+  Chrome 137+ 限制 `--remote-debugging-port` 必须搭配独立 `--user-data-dir`，因此 CDP 启动的 Chrome **无法直接复用你日常 Chrome 的登录态**，需要在独立目录中重新登录一次。
+</Note>
--- a/docs/zh/tools/edit.mdx
+++ b/docs/zh/tools/edit.mdx
@@ -0,0 +1,24 @@
+---
+title: edit - 文件编辑
+description: 通过精确文本替换编辑文件
+---
+
+通过精确文本替换编辑文件。如果 `oldText` 为空则追加到文件末尾。
+
+## 依赖
+
+无额外依赖，默认可用。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | string | 是 | 文件路径 |
+| `oldText` | string | 是 | 要替换的原始文本（为空时追加到末尾） |
+| `newText` | string | 是 | 替换后的文本 |
+
+## 使用场景
+
+- 修改配置文件中的特定参数
+- 修复代码中的 bug
+- 在文件指定位置插入内容
--- a/docs/zh/tools/env-config.mdx
+++ b/docs/zh/tools/env-config.mdx
@@ -0,0 +1,36 @@
+---
+title: env_config - 环境变量
+description: 管理 API Key 等秘钥配置
+---
+
+管理工作空间 `.env` 文件中的环境变量（API Key 等秘钥），支持通过对话安全地添加和更新。内置安全保护和脱敏策略。
+
+## 依赖
+
+| 依赖 | 安装命令 |
+| --- | --- |
+| `python-dotenv` ≥ 1.0.0 | `pip install python-dotenv>=1.0.0` |
+
+安装扩展依赖时已包含：`pip3 install -r requirements-optional.txt`
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `action` | string | 是 | 操作类型：`get`、`set`、`list`、`delete` |
+| `key` | string | 否 | 环境变量名称 |
+| `value` | string | 否 | 环境变量值（仅 `set` 时需要） |
+
+## 使用方式
+
+直接告诉 Agent 需要配置的秘钥，Agent 会自动调用该工具：
+
+- "帮我配置 BOCHA_API_KEY"
+- "设置 OPENAI_API_KEY 为 sk-xxx"
+- "查看已配置的环境变量"
+
+配置的秘钥会自动注入到 `bash` 工具的执行环境中。
+
+<Frame>
+  <img src="https://cdn.link-ai.tech/doc/20260202234939.png" width="800" />
+</Frame>
--- a/docs/zh/tools/index.mdx
+++ b/docs/zh/tools/index.mdx
@@ -0,0 +1,69 @@
+---
+title: 工具概览
+description: CowAgent 内置工具系统
+---
+
+工具是 Agent 访问操作系统资源的核心能力。Agent 会根据任务需求智能选择和调用工具，完成文件操作、命令执行、联网搜索、定时任务等各类操作。工具实现在项目的 `agent/tools/` 目录下。
+
+## 内置工具
+
+以下工具默认可用，无需额外配置：
+
+<CardGroup cols={2}>
+  <Card title="read - 文件读取" icon="file" href="/zh/tools/read">
+    读取文件内容，支持文本、图片、PDF
+  </Card>
+  <Card title="write - 文件写入" icon="pen" href="/zh/tools/write">
+    创建或覆盖写入文件
+  </Card>
+  <Card title="edit - 文件编辑" icon="pen-to-square" href="/zh/tools/edit">
+    通过精确文本替换编辑文件
+  </Card>
+  <Card title="ls - 目录列表" icon="folder-open" href="/zh/tools/ls">
+    列出目录内容
+  </Card>
+  <Card title="bash - 终端" icon="terminal" href="/zh/tools/bash">
+    执行系统命令
+  </Card>
+  <Card title="send - 文件发送" icon="paper-plane" href="/zh/tools/send">
+    向用户发送文件或图片
+  </Card>
+  <Card title="memory - 记忆" icon="brain" href="/zh/tools/memory">
+    搜索和读取长期记忆
+  </Card>
+  <Card title="env_config - 环境变量" icon="key" href="/zh/tools/env-config">
+    管理 API Key 等秘钥配置
+  </Card>
+  <Card title="web_fetch - 网页获取" icon="globe" href="/zh/tools/web-fetch">
+    获取网页或文档内容
+  </Card>
+  <Card title="scheduler - 定时任务" icon="clock" href="/zh/tools/scheduler">
+    创建和管理定时任务
+  </Card>
+</CardGroup>
+
+## 可选工具
+
+以下工具需要安装额外依赖或配置 API Key 后启用：
+
+<CardGroup cols={2}>
+  <Card title="web_search - 联网搜索" icon="magnifying-glass" href="/zh/tools/web-search">
+    搜索互联网获取实时信息
+  </Card>
+  <Card title="vision - 图片理解" icon="eye" href="/zh/tools/vision">
+    分析图片内容（识别、描述、OCR 文字提取等）
+  </Card>
+  <Card title="browser - 浏览器" icon="window" href="/zh/tools/browser">
+    控制浏览器访问和操作网页
+  </Card>
+</CardGroup>
+
+## MCP 工具
+
+通过 [Model Context Protocol](https://modelcontextprotocol.io) 接入社区生态中的各种MCP工具，配置一次 `mcp.json` 即用即得：
+
+<CardGroup cols={1}>
+  <Card title="MCP - 外部工具生态" icon="plug" href="/zh/tools/mcp">
+    支持 stdio / SSE 标准协议，热更新，零代码接入
+  </Card>
+</CardGroup>
--- a/docs/zh/tools/ls.mdx
+++ b/docs/zh/tools/ls.mdx
@@ -0,0 +1,23 @@
+---
+title: ls - 目录列表
+description: 列出目录内容
+---
+
+列出目录内容，按字母排序，目录名带 `/` 后缀，包含隐藏文件。
+
+## 依赖
+
+无额外依赖，默认可用。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | string | 是 | 目录路径，相对路径基于工作空间目录 |
+| `limit` | integer | 否 | 最大返回条目数，默认 500 |
+
+## 使用场景
+
+- 浏览项目结构
+- 查找特定文件
+- 检查目录是否存在
--- a/docs/zh/tools/mcp.mdx
+++ b/docs/zh/tools/mcp.mdx
@@ -0,0 +1,112 @@
+---
+title: MCP 工具
+description: 通过 Model Context Protocol 接入外部工具生态
+---
+
+CowAgent 支持 [Model Context Protocol (MCP)](https://modelcontextprotocol.io)，让 Agent 能够直接调用社区中数以万计的 MCP 工具。配置一次 `mcp.json`，工具就会以与内置工具完全相同的方式呈现给 LLM，可被自动选择和调用。
+
+## 配置文件
+
+CowAgent 读取 `~/cow/mcp.json`。文件不存在时不会启用任何 MCP 工具，也不会报错。
+
+Docker 部署时，官方 `docker-compose.yml` 已经把宿主机 `./cow` 挂载到容器内 `/home/agent/cow`（即容器用户的 `~/cow`），把 `mcp.json` 放进宿主机 `./cow/` 目录即可生效。
+
+### 标准格式
+
+完全兼容 MCP 社区标准，同 Claude Desktop / Cursor 一致：
+
+```json
+{
+  "mcpServers": {
+    "<server-name>": {
+      "command": "npx",
+      "args": ["-y", "some-mcp-package"],
+      "env": {
+        "API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `command` | stdio | 启动 server 的可执行命令（如 `npx`、`python`、`uvx`） |
+| `args` | 否 | 传给 command 的参数列表 |
+| `env` | 否 | 子进程的环境变量，常用于 API Key |
+| `url` | SSE / Streamable HTTP | 远程端点 URL（与 `command` 二选一） |
+| `type` | 远程 | 远程传输类型，可选 `sse` 或 `streamable-http`，默认 `sse` |
+| `headers` | 否 | 远程请求附加 HTTP 头（如 `Authorization`），仅 Streamable HTTP 使用 |
+| `disabled` | 否 | `true` 时跳过该 server，便于临时关闭 |
+
+### 完整示例
+
+```json
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "uvx",
+      "args": ["mcp-server-fetch"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+- **fetch**：通用网页抓取，返回页面文本内容，无需 API Key
+- **github**：访问 GitHub 仓库、Issue、PR 等，需要 Personal Access Token
+
+## 让 Agent 帮你配置
+
+CowAgent 自带 `read` / `write` / `edit` 工具，**直接把要装的 MCP 配置发给 Agent，让它写到配置文件中：
+
+例如：
+
+```markdown
+帮我把这个 MCP 加到 ~/cow/mcp.json 里：
+
+{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}
+```
+
+Agent 会：
+
+1. 访问 MCP 配置文件，合并新 server 配置，保留已有项
+2. 自动重载增量的 MCP Server，下一次对话即可使用相应 Tools
+
+## 工作方式
+
+- 启动时**异步加载**：`mcp.json` 中配置的所有 server 会在后台异步加载，不阻塞主流程，对话可以立刻使用
+- **热更新**：用户或 Agent 修改 `mcp.json` 后，消息处理完成时会自动重载变更的 server，无需重启 cow
+- **平铺呈现**：每个 MCP server 暴露的多个方法会平铺为独立的工具，LLM 直接选择调用，不需要二次决策
+
+## 支持的传输协议
+
+| 协议 | 说明 | 配置字段 |
+| --- | --- | --- |
+| **stdio** | 子进程通信，最常见，社区生态最丰富 | `command` + `args` |
+| **SSE** | HTTP Server-Sent Events，旧版远程协议 | `url`（默认） |
+| **Streamable HTTP** | 新版远程协议，单端点收发，逐步取代 SSE | `type: "streamable-http"` + `url` |
+
+## 排错
+
+| 现象 | 排查方向 |
+| --- | --- |
+| 启动后 Agent 没有 MCP 工具 | 检查 `~/cow/mcp.json` 是否存在、JSON 格式是否合法 |
+| 某个 server 加载失败 | 查看启动日志中的 `[MCP] Server 'xxx' load failed`，常见为依赖未装、API Key 缺失 |
+| 修改 `mcp.json` 没有生效 | 改动会在**下一条消息**生效；若 server 配置不变（如只改注释），不会触发重启 |
+| Docker 部署 | 确认宿主机 `./cow` 已挂载到容器内 `/home/agent/cow`，`mcp.json` 直接放进宿主机 `./cow/` 目录即可，或者直接对话 Agent 安装 |
+
+## MCP 市场推荐
+
+可以从各个第三方广场寻找现成的 MCP server，复制 JSON 配置即可使用，例如：
+
+- [mcp.so](https://mcp.so) — 全球 MCP 服务索引
+- [ModelScope MCP 广场](https://modelscope.cn/mcp) — 魔搭社区 MCP 广场，国内访问更稳定
+
+只要遵循 MCP 标准协议（stdio / SSE / Streamable HTTP），都可以直接接入 CowAgent。
--- a/docs/zh/tools/memory.mdx
+++ b/docs/zh/tools/memory.mdx
@@ -0,0 +1,43 @@
+---
+title: memory - 记忆与知识
+description: 搜索和读取长期记忆及知识库文件
+---
+
+记忆工具包含两个子工具：`memory_search`（搜索记忆）和 `memory_get`（读取记忆或知识文件）。
+
+当 [知识库](/knowledge) 功能开启时，这两个工具同时支持访问 `memory/` 和 `knowledge/` 目录下的文件。
+
+## 依赖
+
+无额外依赖，默认可用。由 Agent Core 的记忆系统管理。
+
+## memory_search
+
+搜索历史记忆和知识库内容，支持关键词和向量混合检索。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `query` | string | 是 | 搜索查询 |
+
+## memory_get
+
+读取特定记忆文件或知识库文件的内容。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | string | 是 | 文件的相对路径（如 `MEMORY.md`、`memory/2026-01-01.md`、`knowledge/concepts/rag.md`） |
+| `start_line` | integer | 否 | 起始行号 |
+| `end_line` | integer | 否 | 结束行号 |
+
+## 工作方式
+
+Agent 会在以下场景自动调用记忆工具：
+
+- 用户分享重要信息时 → 存储到记忆
+- 需要参考历史信息时 → 搜索相关记忆
+- 对话达到一定长度时 → 提取摘要存储
+- 讨论到专业知识时 → 检索知识库中的相关页面
+
+<Note>
+  当 `knowledge` 配置为 `false` 时，工具的描述和搜索范围会自动调整为仅包含记忆文件。
+</Note>
--- a/docs/zh/tools/read.mdx
+++ b/docs/zh/tools/read.mdx
@@ -0,0 +1,24 @@
+---
+title: read - 文件读取
+description: 读取文件内容
+---
+
+读取文件内容。支持文本文件、PDF 文件、图片（返回元数据）等格式。
+
+## 依赖
+
+无额外依赖，默认可用。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | string | 是 | 文件路径，相对路径基于工作空间目录 |
+| `offset` | integer | 否 | 起始行号（1-indexed），负值表示从末尾读取 |
+| `limit` | integer | 否 | 读取行数 |
+
+## 使用场景
+
+- 查看配置文件、日志文件
+- 读取代码文件进行分析
+- 检查图片/视频的文件信息
--- a/docs/zh/tools/scheduler.mdx
+++ b/docs/zh/tools/scheduler.mdx
@@ -0,0 +1,80 @@
+---
+title: scheduler - 定时任务
+description: 创建和管理定时任务
+---
+
+创建和管理动态定时任务，支持灵活的调度方式和执行模式。
+
+## 依赖
+
+| 依赖 | 安装命令 |
+| --- | --- |
+| `croniter` ≥ 2.0.0 | `pip install croniter>=2.0.0` |
+
+安装核心依赖时已包含：`pip3 install -r requirements.txt`
+
+## 调度方式
+
+| 方式 | 说明 |
+| --- | --- |
+| 一次性任务 | 在指定时间执行一次 |
+| 固定间隔 | 按固定时间间隔重复执行 |
+| Cron 表达式 | 使用 Cron 语法定义复杂调度规则 |
+
+## 执行模式
+
+- **固定消息发送**：到达触发时间时发送预设消息
+- **Agent 动态任务**：到达触发时间时由 Agent 智能执行任务
+
+## 使用方式
+
+通过自然语言即可创建和管理定时任务：
+
+- "每天早上 9 点给我发天气预报"
+- "每隔 2 小时检查一下服务器状态"
+- "明天下午 3 点提醒我开会"
+- "查看所有定时任务"
+
+<Frame>
+  <img src="https://cdn.link-ai.tech/doc/20260202195402.png" width="800" />
+</Frame>
+
+## 结果进入会话上下文
+
+定时任务在隔离 session 中执行（内部规划与 tool 调用不污染用户会话），但**最终输出**会作为一对消息回写到接收者的真实会话，用户可以直接追问"刚才那条第二点展开说说"。
+
+**默认策略**
+
+- Agent 动态任务的输出进入上下文
+- 固定消息类任务默认不进入上下文（可通过配置打开）
+- 每个会话最多保留最近 **3 对** scheduler 消息，更早的自动清理；普通用户消息不受影响
+
+**配置项**
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `scheduler_inject_to_session` | `true` | 总开关 |
+| `scheduler_inject_max_per_session` | `3` | 每会话保留 scheduler 消息对数上限 |
+| `scheduler_inject_send_message` | `false` | 是否同时注入固定消息类任务 |
+
+```json
+{
+  "scheduler_inject_to_session": true,
+  "scheduler_inject_max_per_session": 3,
+  "scheduler_inject_send_message": false
+}
+```
+
+## 任务执行时的上下文
+
+定时任务的隔离 session 会保留最近几次执行的对话历史，便于做"对比上次"、"延续之前结论"等操作；但为了避免高频任务（如每 5 分钟监控）prompt 越积越长，会按公式自动裁剪：
+
+```
+scheduler_keep_turns = max(1, agent_max_context_turns / 5)
+```
+
+`agent_max_context_turns` 默认为 `20`，所以定时任务每次执行默认带最近 **4 轮**历史。需要更长记忆可调大 `agent_max_context_turns`。
+
+<Note>
+群聊场景（飞书 / 企微群机器人 / 钉钉等）下用户的真实 session_id 形如 `user_id:group_id`，与 receiver 不同。创建任务时会自动记录正确的 session_id；老的 `tasks.json` 缺该字段时回落到 receiver，行为与历史版本一致。
+</Note>
--- a/docs/zh/tools/send.mdx
+++ b/docs/zh/tools/send.mdx
@@ -0,0 +1,23 @@
+---
+title: send - 文件发送
+description: 向用户发送文件
+---
+
+向用户发送文件（图片、视频、音频、文档等），当用户明确要求发送/分享文件时使用。
+
+## 依赖
+
+无额外依赖，默认可用。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | string | 是 | 文件路径，可以是绝对路径或相对于工作空间的路径 |
+| `message` | string | 否 | 附带的消息说明 |
+
+## 使用场景
+
+- 将生成的代码或文档发送给用户
+- 发送截图、图表
+- 分享下载的文件
--- a/docs/zh/tools/vision.mdx
+++ b/docs/zh/tools/vision.mdx
@@ -0,0 +1,75 @@
+---
+title: vision - 图片理解
+description: 分析图片内容（识别、描述、OCR 等）
+---
+
+使用 Vision API 分析本地图片或图片 URL，支持内容描述、文字提取（OCR）、物体识别等。
+
+## 模型选择
+
+Vision 工具采用多级自动选择 + 自动兜底策略，无需手动配置即可使用：
+
+1. **主模型** — 优先使用当前配置的主模型进行图像识别（需要是多模态模型）
+2. **其他已配置模型** — 自动发现已配置 API Key 的其他多模态模型作为备选
+
+如果当前 provider 调用失败，会自动尝试下一个，直到成功或全部失败。
+
+### 支持的模型
+
+| 厂商 | 视觉模型 | 说明 |
+| --- | --- | --- |
+| OpenAI / 兼容协议 | 使用主模型 | 支持所有 OpenAI 协议兼容的多模态模型 |
+| 通义千问 (DashScope) | 使用主模型 | 例如 qwen3.6-plus 等 |
+| Claude | 使用主模型 | Anthropic 原生图像格式 |
+| Gemini | 使用主模型 | inlineData 格式 |
+| 豆包 (Doubao) | 使用主模型 | doubao-seed-2-0 系列原生支持 |
+| Kimi (Moonshot) | 使用主模型 | kimi-k2.6、kimi-k2.5 原生支持 |
+| 百度千帆 (Qianfan) | 使用主模型 | 默认使用多模态主模型 (如 ernie-5.1)，主模型不支持时兜底使用 ernie-4.5-turbo-vl |
+| 智谱 AI | glm-5v-turbo | 固定使用视觉专用模型 |
+| MiniMax | MiniMax-Text-01 | 固定使用视觉专用模型 |
+
+<Note>
+  智谱和 MiniMax 的文本模型不支持图像理解，因此始终使用对应的视觉专用模型，无需手动指定。
+</Note>
+
+> 当 `use_linkai=true` 时，默认使用 LinkAI 的多模态模型进行
+
+## 自定义配置
+
+如果希望指定 Vision 使用的模型，可在 `config.json` 中配置，例如：
+
+```json
+{
+    "tools": {
+        "vision": {
+            "model": "gpt-4.1"
+        }
+    }
+}
+```
+
+指定的模型会被**优先使用**，工具会根据模型名自动路由到对应的 provider；若调用失败，会自动 fallback 到其他已配置的 provider。
+
+大多数情况下无需配置，主模型支持多模态或配置任意一个支持视觉的 API Key 即可自动工作。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `image` | string | 是 | 本地文件路径或 HTTP(S) 图片 URL |
+| `question` | string | 是 | 对图片提出的问题 |
+
+支持的图片格式：jpg、jpeg、png、gif、webp
+
+
+
+## 使用场景
+
+- 描述图片中的内容
+- 提取图片中的文字（OCR）
+- 识别物体、颜色、场景
+- 分析截图、文档扫描图片等
+
+<Note>
+  超过 1MB 的图片会自动压缩后上传，所有图片（包括远程 URL）会统一转为 base64 传输，确保兼容所有模型后端。
+</Note>
--- a/docs/zh/tools/web-fetch.mdx
+++ b/docs/zh/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>
--- a/docs/zh/tools/web-search.mdx
+++ b/docs/zh/tools/web-search.mdx
@@ -0,0 +1,51 @@
+---
+title: web_search - 联网搜索
+description: 搜索互联网获取实时信息，支持多个搜索厂商
+---
+
+搜索互联网获取实时信息、新闻、研究等内容。支持博查、百度千帆、智谱、LinkAI 四个后端，配置任意一家即可使用。
+
+<Tip>
+  推荐通过 [Web 控制台](/zh/channels/web) 的「模型管理 → 搜索」面板可视化配置厂商与策略，无需手动编辑配置文件。
+</Tip>
+
+## 厂商
+
+| 厂商 | 凭证 | 申请入口 |
+| --- | --- | --- |
+| 博查 Bocha | `tools.web_search.bocha_api_key` | [博查开放平台](https://open.bochaai.com/) |
+| 百度千帆 | 复用 `qianfan_api_key` | [千帆控制台](https://cloud.baidu.com/doc/qianfan/s/2mh4su4uy) |
+| 智谱 Zhipu | 复用 `zhipu_ai_api_key` | [智谱开放平台](https://docs.bigmodel.cn/cn/guide/tools/web-search) |
+| LinkAI | 复用 `linkai_api_key` | [LinkAI 控制台](https://link-ai.tech/console/interface) |
+
+除博查需要单独的 `bocha_api_key` 外，其他三家直接复用对应模型的 API Key，配好模型即同时获得搜索能力。
+
+## 路由策略
+
+```json
+{
+  "tools": {
+    "web_search": {
+      "strategy": "auto",
+      "provider": ""
+    }
+  }
+}
+```
+
+- `auto`（默认）：由 Agent 在已配置的厂商中智能选择，并可在一次任务中多次调用、切换不同厂商以获取更全面的结果；未指定时按 `bocha → qianfan → zhipu → linkai` 顺序兜底。
+- `fixed`：固定使用 `provider` 指定的厂商；该厂商凭证缺失时自动回落到 auto 顺序。
+
+## 工具参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `query` | string | 是 | 搜索关键词 |
+| `count` | integer | 否 | 返回结果数量（1–50，默认 10） |
+| `freshness` | string | 否 | 时间范围：`noLimit`（默认）、`oneDay`、`oneWeek`、`oneMonth`、`oneYear`，或日期范围如 `2025-01-01..2025-02-01` |
+| `summary` | boolean | 否 | 是否返回页面摘要（默认 false） |
+| `provider` | string | 否 | `auto` 策略下配置了多个厂商时可见，用于单次切换厂商 |
+
+<Note>
+  四家凭证均未配置时，该工具不会注册到 Agent。
+</Note>
--- a/docs/zh/tools/write.mdx
+++ b/docs/zh/tools/write.mdx
@@ -0,0 +1,27 @@
+---
+title: write - 文件写入
+description: 创建或覆盖写入文件
+---
+
+写入内容到文件。文件不存在则自动创建，已存在则覆盖。自动创建父目录。
+
+## 依赖
+
+无额外依赖，默认可用。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `path` | string | 是 | 文件路径 |
+| `content` | string | 是 | 要写入的内容 |
+
+## 使用场景
+
+- 创建新的代码文件或脚本
+- 生成配置文件
+- 保存处理结果
+
+<Note>
+  单次写入不应超过 10KB。对于大文件，建议先创建骨架，再使用 edit 工具分块添加内容。
+</Note>