7.5 智能体系统的内置工具

上一节介绍了 CLI 智能体的基本运行方式。CLI 智能体之所以能完成复杂任务，关键在于它内置了一组精心设计的工具。这些工具覆盖文件操作、搜索、命令执行和网络访问等基本能力，构成智能体与计算机系统交互的基础设施。

本节系统介绍 Opencode 等 CLI 智能体的内置工具体系，并进一步讨论 Browser Use 和 Computer Use 两种前沿交互方式。

7.5.1 内置工具的设计理念

内置工具分类体系

内置工具（Built-in Tools）是智能体系统预先集成的核心能力模块。与 7.3 节介绍的 MCP 外部工具不同，内置工具无需额外安装或配置，开箱即用。

两者的区别在于：内置工具由智能体系统开发者深度优化，与系统核心紧密集成；MCP 工具由第三方开发者按标准协议接入，需要额外的配置和连接步骤。

内置工具的设计遵循三条原则：

原则	含义	举例
职责单一	每个工具只做一件事	Read 只读文件，Write 只写文件
接口明确	参数和返回值定义清晰	Grep 接收搜索模式，返回匹配结果
可组合	多个工具串联完成复杂任务	Glob 找文件 → Read 读内容 → Edit 修改

重要核心概念

内置工具体现了 Unix 哲学：每个工具做好一件事，通过组合实现复杂功能。智能体的核心能力，正是判断何时调用哪个工具、如何将多个工具串联起来。

7.5.2 文件操作工具

文件操作是智能体最基础的能力。CLI 智能体通常提供三个文件操作工具：Read、Write 和 Edit。

Read：读取文件

Read 工具读取指定路径的文件内容。它的能力不限于纯文本，还支持图像（PNG、JPG）、PDF 文档和 Jupyter Notebook 等格式。

典型用法：

智能体调用 Read 工具，参数：
  file_path: "/project/data/report.pdf"
  pages: "1-5"

返回：report.pdf 第 1-5 页的文本内容

Read 是使用频率最高的内置工具。智能体在修改任何文件之前，都应先用 Read 了解文件当前内容，避免盲目操作。

Write：创建或覆盖文件

Write 工具将指定内容写入文件。如果文件已存在，会完全覆盖原有内容；如果文件不存在，则新建文件。

智能体调用 Write 工具，参数：
  file_path: "/project/output/analysis.md"
  content: "# 分析报告\n\n## 摘要\n..."

结果：创建（或覆盖）analysis.md 文件

Edit：精确修改文件

Edit 工具对文件进行局部修改，只替换指定的文本片段，保留文件其余部分不变。

智能体调用 Edit 工具，参数：
  file_path: "/project/config.json"
  old_string: "\"timeout\": 30"
  new_string: "\"timeout\": 60"

结果：仅将 timeout 的值从 30 改为 60，其余内容不变

Edit 比 Write 更安全。用 Write 修改文件，需要重写整个文件内容，过程中可能遗漏或误改其他部分。Edit 只替换目标区域，保留文件其余部分不变，降低了出错风险。

三者的使用场景对比

工具	适用场景	风险等级
Read	查看文件内容、理解现有代码或数据	低
Write	创建新文件、生成完整报告	中
Edit	修改配置项、修复代码中的特定错误	低

提示教学提示

文件操作工具的选择逻辑：需要查看内容用 Read，需要创建新文件用 Write，需要局部修改用 Edit。实际工作中，智能体往往按照 Read → Edit 或 Read → Write 的顺序组合使用——先读后改，是最基本的安全习惯。

权限模型

文件操作工具的权限设计体现了安全优先原则：

• Read：不需要用户授权。读取文件不会改变系统状态，属于无副作用操作。
• Write 和 Edit：需要用户确认后才能执行。因为写入操作会修改文件，属于有副作用操作，必须经过人的审批。

这一设计遵循最小权限原则：无副作用的操作自动执行，有副作用的操作需要授权。

7.5.3 搜索工具

在包含大量文件的项目中，快速定位目标信息至关重要。CLI 智能体提供两类搜索工具，分别面向不同的搜索需求。

Grep：按内容搜索

Grep 工具在文件内容中搜索匹配指定模式的文本行。底层通常使用 ripgrep（rg）引擎，搜索速度极快，支持正则表达式（Regular Expression）语法。

正则表达式是一种文本模式匹配语言，用特定符号描述搜索规则。例如 \d+ 匹配一个或多个数字，PE.*ratio 匹配包含 PE 和 ratio 的文本行（中间可以有任意字符）。

智能体调用 Grep 工具，参数：
  pattern: "市盈率|PE ratio"
  path: "/project/reports/"
  glob: "*.md"

返回：reports 目录下所有 .md 文件中包含「市盈率」或「PE ratio」的行

Glob：按文件名搜索

Glob 工具根据文件名模式查找文件，不关心文件内容。常用的模式符号包括：

符号	含义	示例
*	匹配任意字符	*.csv 匹配所有 CSV 文件
**	匹配任意层级目录	**/*.py 匹配所有子目录中的 Python 文件
?	匹配单个字符	report_?.md 匹配 report_1.md、report_2.md

智能体调用 Glob 工具，参数：
  pattern: "**/*财报*.xlsx"
  path: "/project/data/"

返回：data 目录及其子目录下所有文件名包含「财报」的 Excel 文件路径

Grep 与 Glob 的分工

简单概括：Grep 搜内容，Glob 搜文件名。

• 知道要找什么内容，但不知道在哪个文件里——用 Grep
• 知道文件名的大致特征，但不知道在哪个目录下——用 Glob
• 先用 Glob 缩小文件范围，再用 Grep 在目标文件中搜索——组合使用

7.5.4 命令执行工具

Bash：Shell 命令执行

Bash 工具是内置工具中最灵活的一个。它允许智能体执行任意 Shell 命令，能力范围覆盖操作系统的全部命令行功能。

Bash 工具的能力范围包括：

能力	示例命令	金融场景
安装软件包	pip install akshare	安装金融数据库
运行脚本	python analysis.py	执行量化分析脚本
Git 操作	git commit -m "更新报告"	版本管理研究报告
数据处理	wc -l data.csv	统计数据行数
环境管理	python --version	检查运行环境

智能体调用 Bash 工具，参数：
  command: "python -c \"import akshare as ak; df = ak.stock_zh_a_spot_em(); print(df.head())\""

返回：A 股实时行情数据的前 5 行

警告安全提示

Bash 工具功能强大，但也意味着风险更高。它可以执行任意命令，包括删除文件、修改系统配置等危险操作。因此 Bash 工具通常设有三重安全机制：

1. 用户确认：执行前显示即将运行的命令，等待用户批准
2. 超时控制：命令执行时间超过限制会被自动终止
3. 沙箱隔离：部分系统会限制 Bash 工具的可访问范围

7.5.5 网络工具

网络工具让智能体能够访问互联网，获取训练数据截止日期之后的实时信息。

WebSearch：搜索引擎查询

WebSearch 工具向搜索引擎发送查询请求，返回搜索结果列表。智能体可以据此获取最新的新闻、研究报告或市场数据。

智能体调用 WebSearch 工具，参数：
  query: "2025年中国GDP增速"

返回：包含标题、摘要和链接的搜索结果列表

WebFetch：获取网页内容

WebFetch 工具访问指定 URL，返回网页的文本内容。适合从已知网址提取信息，如政策文件、公司公告等。

智能体调用 WebFetch 工具，参数：
  url: "https://example.com/annual-report-2024.html"

返回：该网页的文本内容

WebSearch 和 WebFetch 通常配合使用：先用 WebSearch 找到目标页面的 URL，再用 WebFetch 获取完整内容。

注记知识卡片

WebFetch 只能获取网页的静态 HTML 内容。许多现代网站使用 JavaScript 动态加载数据——页面的 HTML 源码中并不包含你在浏览器中看到的全部内容。对于这类网站，WebFetch 可能无法获取到有效数据，需要使用下文介绍的 Browser Use 方案。

7.5.6 前沿交互方式：Browser Use 与 Computer Use

除了上述内置工具，智能体领域还在探索两种更高级的交互方式。

Browser Use 让智能体像人一样操作浏览器——点击按钮、填写表单、提取动态加载的数据。底层依赖 Playwright、Puppeteer 等浏览器自动化框架。与 WebFetch 只能获取静态 HTML 不同，Browser Use 能完整执行 JavaScript，适合处理需要登录的金融数据平台和动态渲染的报表页面。

Computer Use 更进一步，将操控范围扩展到整个桌面环境。模型通过截屏理解界面状态，输出鼠标和键盘操作指令，可以操作 Excel、Wind 终端等任意桌面软件。Anthropic 于 2024 年发布了这一功能，目前仍处于实验阶段，存在精确度有限、速度较慢、成本较高等局限。

维度	WebFetch	Browser Use	Computer Use
操控范围	静态网页内容	浏览器内网页	整个桌面环境
交互能力	仅读取	点击、填写、滚动	鼠标、键盘全操作
成熟度	成熟	较成熟	实验阶段

这两种方式代表了智能体发展的重要方向：让 AI 使用人类设计的任何软件，而不局限于 API 或命令行。

7.5.7 工具权限与安全模型

内置工具的权限管理是智能体安全运行的基石。不同工具根据其潜在风险，被赋予不同的默认权限级别。

三级权限体系

权限级别	含义	对应工具
自动允许	无需用户确认，直接执行	Read、Grep、Glob
需要确认	执行前弹出提示，用户批准后执行	Write、Edit、Bash
禁止执行	默认禁用，需用户主动开启	部分高风险 Bash 命令

这一设计背后的逻辑是：读取和搜索操作不改变系统状态，风险极低，可以自动执行；写入和命令执行操作可能产生不可逆后果，必须经过人的审批。

为什么安全控制如此重要

智能体与传统软件的关键区别在于：传统软件按预设逻辑运行，行为完全可预测；智能体则根据模型推理自主决策调用哪些工具、传入什么参数。这种自主性带来了灵活性，也引入了不确定性。

一个设想场景：如果智能体在分析财务数据时，错误地判断需要删除某个临时文件，而该文件实际上是重要的原始数据——没有权限控制，这次误判就可能导致数据丢失。

重要核心概念

工具权限管理的本质是人在回路（Human-in-the-Loop, HITL）机制在工具层面的体现。7.3 节讨论的 MCP 安全边界、本节的内置工具权限，以及第 5 章介绍的护栏机制（Guardrails），都服务于同一目标：确保人类对智能体行为保持最终控制权。

权限配置实践

在 Opencode 中，可以通过 opencode.json 配置文件调整工具权限。例如，在可信的开发环境中，可以将部分低风险的 Write 操作设为自动允许，提高工作效率：

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Write(chapters/**/*.md)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

上述配置允许智能体自动写入 chapters 目录下的 Markdown 文件，但禁止执行删除和提权命令。这种细粒度控制在实际项目中很实用——既保证了工作效率，又守住了安全底线。

7.5.8 内置工具的协作模式

单个内置工具的能力有限，智能体的真正优势在于将多个工具灵活组合。以下是两个典型的工具协作模式。

模式一：探索-理解-修改-验证

这是最常见的工作流，适用于修改已有文件：

步骤	工具	操作
1	Glob	在项目中查找目标文件
2	Read	读取文件，理解当前内容
3	Edit	对文件进行精确修改
4	Bash	运行测试或验证脚本，确认修改正确

模式二：搜索-分析-生成

适用于信息收集和报告生成场景：

步骤	工具	操作
1	WebSearch	搜索最新市场数据或政策信息
2	WebFetch	获取关键网页的完整内容
3	Bash	运行 Python 脚本进行数据分析
4	Write	将分析结果写入报告文件

提示教学提示

理解内置工具时，不必逐一记忆每个工具的参数细节。重点把握两件事：一是每个工具能做什么（能力边界），二是工具之间如何配合（组合模式）。智能体在实际运行中，会自动选择合适的工具并填入正确的参数——这正是大语言模型的推理能力所在。