第21章 OpenCode 工具使用详解:读、写、编辑与搜索
工具 描述期望的结果。OpenCode 会选择可用的工具,在需要时请求批准,并返回结果。 找到请求超时配置的代码,将默认值改为 30 秒,并运行相关的现有测试。 此任务通常使用 grep 或 glob、read、编辑工具以及 shell。 如果你希望采用特定的方法,也可以直接指定工具。 使用 grep 查找所有对 DEFAULT_TIMEOUT 的引用,然后读取匹配的文件。
read 返回文件或非递归的目录列表。提供路径即可;使用 offset 和 limit 对大结果进行分页浏览。 从第 120 行开始读取 src/server.ts,最多返回 80 行。 文本读取包含带行号的内容,每页限制为 2,000 行和 50 KiB。单行超过 2,000 字符会被截断。该工具还会将 PNG、JPEG、GIF、WebP 和 PDF 文件传递给模型,源数据上限为 20 MiB。其他二进制文件会失败。支持的媒体类型和图像处理见“Attachments”。 权限:read,资源为规范化后的路径。
glob 根据模式(如 /*.ts)查找文件路径。默认搜索当前目录,除非用 path 指定其他相对目录;hidden 包含隐藏条目,limit 限制结果数量。 在 packages/core 下使用 glob 匹配 /*.test.ts,最多返回 50 个文件。 默认限制为 100 个文件,搜索超时为 30 秒。 权限:glob,资源为请求的模式。
grep 搜索文件内容并返回路径、行号和预览。其 pattern 使用正则表达式语法,除非 literal 为 true。可以用 path、include、caseSensitive 或 limit 缩小搜索范围。 在 src 中用 grep 查找字面文本 "request timed out",仅包含 *.ts 文件。 默认限制为 100 行匹配结果,搜索超时为 30 秒。 权限:grep,资源为请求的模式,而非搜索路径。
edit 替换现有文件中的文本。提供 path、oldString 和不同的 newString;old 文本必须精确匹配一次,除非 replaceAll 为 true。 在 src/config.ts 中,将唯一的文本 "timeout: 60" 替换为 "timeout: 30"。 edit 用于聚焦修改。OpenCode 在写入后可能会格式化文件。 权限:edit,资源为目标路径。
write 根据 path 和 content 创建或完全替换文本文件。它会创建缺失的父目录,并可能运行已配置的格式化工具。 创建 docs/example.md,包含一个标题和一条设置命令。 如果只需修改现有文件的一部分,请使用 edit。 权限:edit,资源为目标路径。
patch 应用一个补丁,可以添加、更新、移动或删除多个文件。其 patchText 使用 * Add File、* Update File 和 * Delete File 部分。 使用 patch 将 src/old.ts 重命名为 src/new.ts 并更新其导出的名称。 OpenCode 仅为支持的 GPT 模型提供 patch;其他模型将收到 edit 和 write。权限:edit,资源为所有受影响的路径。 位于活动 Location 或其项目 worktree 之外的路径还会针对 external_directory 进行检查,默认允许。路径规范化、规则顺序和已保存的批准见“Permissions”。要按名称使外部材料可用,请配置 References。
shell 在宿主用户的 shell 中执行命令。使用 workdir 代替在命令中写 cd,当默认的 2 分钟前台超时不适用时,设置 timeout(毫秒)。 从 packages/core 运行 bun test,超时设为 5 分钟。 对于开发服务器或其他长期运行的进程,将 background 设为 true。 后台调用立即返回,并在完成时通知会话;除非提供超时,否则没有超时。大输出会被截断,完整输出保留在托管文件中。 权限:shell,资源为每个扫描器生成的命令。扫描器还会检查外部工作目录及可从命令推断的目录。Shell 拥有宿主用户文件系统、进程和网络权限,因此在 Permissions 中请使用窄规则。
webfetch 将单个 HTTP 或 HTTPS URL 获取为 markdown、text 或 html。默认是 markdown;timeout 最长 120 秒。 以 markdown 格式获取 https://example.com/docs。 它接受 HTML、纯文本、JSON 和 XML 等文本响应,但不接受图像或其他二进制下载。大输出可能被截断,全文保留在托管存储中。权限:webfetch,资源为请求的 URL。
websearch 在选定的集成中搜索最新信息。其输入是搜索查询。 搜索网上关于 Bun 最新发布说明。 权限:websearch,资源为查询。提供商、选择、速率限制和禁用工具见“Web search”。
experimental_image_generate 根据提示创建新图像或编辑现有图像。它是实验性的,在连接的提供商具有图像模型时出现。选择其默认模型,见 experimental.image_generate。 生成一个纸飞机在蓝色背景上的扁平应用图标,保存到 assets/icon.png。 提供提示,可选提供要编辑或用作参考的图像、特定模型或保存路径。它在后台运行,图像就绪时通知会话并附保存路径。 权限:experimental_image_generate,资源为选定的模型。
question 暂停执行并向用户呈现一个或多个问题。每个问题有简短标题、提示和选项;multiple 允许多选。始终可提供自由回答。 在更改 API 之前,让我在破坏性更改和兼容性层之间选择。 权限:question,资源为 *。客户端必须支持交互式表单,关闭即取消该问题。
skill 将某个可用 skill ID 的指令和捆绑资源加载到对话中。 在更改此 Effect 代码之前,加载 effect skill。 ID 必须在公布的 skill 列表中,或由用户显式命名。权限:skill,资源为 skill ID。创建、发现和加载规则见“Skills”。
subagent 使用配置的 subagent 启动子会话。提供 agent ID、简短描述和完整提示。 让 explore subagent 映射认证流程并返回关键文件。 前台调用等待结果。background: true 立即返回,并在子会话完成时通知父会话。传递返回的 sessionID 可继续该子对话。仅 subagent-mode agents 可用,默认嵌套深度为 1。 权限:subagent,资源为选定的 agent ID。
execute 在 Code Mode 中运行 JavaScript,使 agent 能调用和组合目录中的工具。它适用于并行独立调用和处理结果,而无需将所有中间值添加到模型上下文。 并行读取 package.json 和 README.md,然后返回相关的设置细节。 运行时没有直接文件系统访问、导入或计时器。它提供 fetch 用于 HTTP 请求;其他都通过其目录中的工具进行。 用资源 * 拒绝 execute 会移除 Code Mode 和仅通过它可达的所有工具,包括未设置 codemode: false 的服务器提供的 MCP 工具。嵌套的内建和 MCP 工具仍执行其自身权限,插件工具执行其声明的权限。
opencode Code Mode 命名空间包含会话工具:
session_rename 更改当前会话或指定 sessionID 的会话的标题。 session_move 将当前会话或指定会话移动到相对或绝对目录。移动在安全边界生效,因此依赖目标目录的工作属于后续调用。
将此会话重命名为 "Timeout cleanup",然后将其移动到新 worktree。
同一命名空间管理项目的 worktrees:
worktree_create 根据名称创建 worktree 并返回目录。项目的 worktree 配置选择目标位置和策略。 worktree_list 列出项目的 worktrees。 worktree_remove 删除 OpenCode 为项目记录的 worktree。设置 force 以丢弃未提交的更改。
创建名为 "login" 的 worktree 并将此会话移入。 worktree_remove 使用 edit 权限,资源为 worktree 目录。其他 worktree 工具不请求内建权限操作。
browser Code Mode 命名空间控制 OpenCode 桌面应用附加的浏览器。打开标签页,保留返回的 tabID,然后将其传递给每个页面操作。 打开 https://example.com,对该标签页进行快照,并报告主标题。 该命名空间包括标签页和导航命令、页面快照和搜索、点击和表单输入、截图、文件传输、控制台和网络检查、性能跟踪、堆检查以及 Lighthouse 审计。 截图需要聚焦且可见的标签页。上传路径是服务器本地的;捕获返回服务器本地路径,每个文件传输限制为 5 MiB。 页面内容、日志、请求头和响应体是不可信数据,而非 agent 指令。浏览器拒绝规则资源 * 会移除浏览器目录;浏览器操作不发出单独的权限提示。
MCP 服务器添加的工具,其名称和输入来自每个连接服务器。其权限操作为