5.17 内置工具

💡 一句话总结：掌握 OpenCode 内置工具的强大功能，提升 AI 编码效率。

学完你能做什么

了解所有内置工具的功能和用法
学会在不同场景下选择合适的工具
通过工具组合实现复杂的自动化任务
优化工具使用效率

你现在的困境

只会用基本的文件操作，不知道有其他工具
AI 偶尔会用你不熟悉的工具，导致不理解
不知道某些任务其实可以用内置工具更快完成

什么时候用这一招

当你需要：充分利用 OpenCode 的所有能力
而且不想：只使用基础功能而错过高级特性

🎒 开始前的准备

确保你已经完成以下事项：

[ ] 完成了 5.1a 配置基础
[ ] 了解 OpenCode 的基本操作

核心思路

工具分类概览

OpenCode 内置了丰富的工具，按功能分为以下几类：

类别	工具数量	主要用途
文件操作	8+	读写、搜索、编辑文件
代码分析	6+	LSP、AST、符号查找
执行环境	4+	命令行、测试、构建
协作集成	5+	Git、会话管理
Web 与网络	3+	搜索、下载、抓取
Agent 管理	4+	任务委派、会话控制

工具使用原则

优先使用专用工具：文件搜索用 Grep，不要用 Bash + grep
组合使用：多个工具配合实现复杂任务
理解工具限制：每个工具都有适用场景和性能边界

内置工具详解

📁 文件操作类

Read - 文件读取

typescript

// 读取文件内容
read(filePath: string): Promise<string>

适用场景：

查看文件完整内容
读取配置文件
分析代码文件

参数说明：

filePath：文件路径（绝对路径）
offset：从第几行开始读（可选，默认 0）
limit：读取多少行（可选，默认 2000）

示例：

Read src/components/Header.tsx
Read src/app.tsx offset=100 limit=50

Write - 文件写入

typescript

// 写入文件内容
write(filePath: string, content: string): Promise<void>

适用场景：

创建新文件
完全重写文件

注意：必须先用 Read 读取过该文件才能写入（安全机制）

Edit - 文件编辑

typescript

// 替换文件中的内容
edit(filePath: string, oldString: string, newString: string): Promise<void>

适用场景：

修改文件的部分内容
替换函数或变量名
更新配置项

参数说明：

filePath：文件路径
oldString：要替换的原文
newString：替换后的内容
replaceAll：是否替换所有匹配项（默认 false）

Glob - 文件匹配

typescript

// 按模式查找文件
glob(pattern: string, path?: string): Promise<string[]>

适用场景：

查找特定类型的所有文件
按路径模式搜索文件

支持的模式：

**/*.ts - 查找所有 TypeScript 文件
src/**/*.tsx - 查找 src 下所有 TSX 文件
**/test.* - 查找所有 test 文件

Grep - 内容搜索

typescript

// 在文件内容中搜索
grep(pattern: string, include?: string, path?: string): Promise<string[]>

适用场景：

搜索代码中的特定模式
查找函数或变量的使用位置
查找错误信息来源

高级用法：

支持正则表达式
可指定文件类型过滤
可限定搜索范围

🔍 代码分析类

LSP 符号工具

LSP Symbols - 获取符号列表

typescript

lsp_symbols(filePath: string, scope: "document" | "workspace", query?: string): Promise<Symbol[]>

适用场景：

查看文件结构（scope="document"）
全项目搜索符号（scope="workspace"）
获取类、函数、变量的完整列表

LSP Go to Definition - 跳转到定义

typescript

lsp_goto_definition(filePath: string, line: number, character: number): Promise<Definition>

适用场景：

查找函数/变量的定义位置
追踪代码依赖关系

LSP Find References - 查找引用

typescript

lsp_find_references(filePath: string, line: number, character: number): Promise<Reference[]>

适用场景：

查找某函数在哪里被调用
分析变量使用范围
重构前评估影响范围

LSP Diagnostics - 获取诊断信息

typescript

lsp_diagnostics(filePath: string, severity?: "error" | "warning"): Promise<Diagnostic[]>

适用场景：

查看代码错误和警告
运行代码分析
验证代码质量

LSP Rename - 符号重命名

typescript

lsp_rename(filePath: string, line: number, character: number, newName: string): Promise<void>

适用场景：

安全地重命名函数、变量、类
自动更新所有引用

注意：会自动应用到所有相关文件

AST Grep - AST 模式搜索

AST Grep Search

typescript

ast_grep_search(pattern: string, lang: string, paths?: string[]): Promise<Match[]>

适用场景：

按代码结构搜索（不是字符串）
查找特定的代码模式
大规模代码重构分析

示例模式：

console.log($MSG) - 查找所有 console.log
async function $NAME($$$) { $$$ } - 查找所有异步函数
def $FUNC($$$): - 查找 Python 函数定义

AST Grep Replace

typescript

ast_grep_replace(pattern: string, rewrite: string, lang: string, dryRun?: boolean): Promise<Result[]>

适用场景：

基于模式的批量重构
安全地进行大规模修改

注意：默认是 dry-run 模式，会显示将要修改的内容而不实际修改

⚙️ 执行环境类

Bash - 命令行执行

typescript

bash(command: string, workdir?: string, timeout?: number): Promise<Output>

适用场景：

执行 Git 命令
运行测试
构建项目
安装依赖

参数说明：

command：要执行的命令
workdir：工作目录（可选）
timeout：超时时间（毫秒，可选，默认 120000）

最佳实践：

优先用 workdir 而不是 cd
多个独立命令可以并行执行
相关命令用 && 串行执行

🤖 Agent 管理类

Delegate Task - 委派任务

typescript

delegate_task(
  category: string,
  load_skills: string[],
  description: string,
  prompt: string,
  run_in_background?: boolean
): Promise<TaskResult>

适用场景：

复杂任务需要专用 Agent 处理
需要并行执行多个独立任务
任务需要特定领域的专业知识

Category 类型：

visual-engineering - 前端 UI/UX
ultrabrain - 复杂逻辑任务
deep - 深度研究
quick - 简单快速任务
writing - 文档写作
artistry - 创意性问题解决

Skills 加载：

playwright - 浏览器自动化
frontend-ui-ux - UI 设计
git-master - Git 操作

Background Output - 获取后台任务结果

typescript

background_output(task_id: string, block?: boolean): Promise<Result>

适用场景：

获取后台运行的任务结果
检查任务完成状态

Background Cancel - 取消后台任务

typescript

background_cancel(task_id?: string, all?: boolean): Promise<void>

适用场景：

取消不需要的后台任务
清理所有后台任务（all=true）

🌐 Web 与网络类

Web Search - 网页搜索

typescript

websearch(query: string, numResults?: number, type?: "auto" | "fast" | "deep"): Promise<SearchResult[]>

适用场景：

搜索最新信息
查找技术文档
获取当前事件

参数说明：

query：搜索关键词
numResults：结果数量（默认 8）
type：搜索类型（auto/balanced, fast/quick, deep/comprehensive）

Code Search - 代码示例搜索

typescript

codesearch(query: string, tokensNum?: number): Promise<CodeExample[]>

适用场景：

查找代码使用示例
学习 API 用法
获取最佳实践参考

注意：专门针对编程任务的搜索

Web Fetch - 网页抓取

typescript

webfetch(url: string, format?: "text" | "markdown" | "html"): Promise<string>

适用场景：

获取网页内容
抓取文档
分析网页结构

📚 会话管理类

Session List - 列出所有会话

typescript

session_list(limit?: number, from_date?: string, to_date?: string): Promise<Session[]>

适用场景：

查看历史会话
按日期筛选会话

Session Read - 读取会话内容

typescript

session_read(session_id: string, include_todos?: boolean, include_transcript?: boolean): Promise<SessionDetail>

适用场景：

查看历史对话
分析工作流程
学习 AI 的解决方案

Session Search - 搜索会话内容

typescript

session_search(query: string, session_id?: string): Promise<SearchMatch[]>

适用场景：

在历史会话中搜索
找到相关的解决方案

🔧 Git 操作类

Git 相关 Bash 命令

虽然 Git 操作通过 Bash 工具执行，但有一些常用模式：

查看状态

bash

git status

查看差异

bash

git diff
git diff --cached

查看提交历史

bash

git log --oneline -10

创建提交

bash

git add .
git commit -m "message"

推荐：复杂 Git 操作建议使用 git-master skill

跟我做

实战 1：理解 AI 如何使用工具

目标：观察 AI 在解决问题时如何选择和组合工具

启动 OpenCode

输入一个复杂任务，例如：

在这个项目中找到所有使用 useState 的地方，并统计它们在哪些文件中出现

观察 AI 使用的工具序列：
- 先用 Glob 查找所有 TSX/TS 文件
- 再用 Grep 搜索 useState
- 可能用 Read 查看具体文件

你应该学到：

工具选择的逻辑
工具组合的方式

实战 2：使用 LSP 工具进行代码导航

目标：掌握 LSP 工具进行代码分析

打开一个有 TypeScript 的项目

输入：

找到 src/App.tsx 中第 20 行定义的函数，并找出它在哪些地方被调用

观察 AI 使用的工具：
- LSP Go to Definition 找到函数定义
- LSP Find References 找到所有调用点

你应该学到：

LSP 工具比文本搜索更准确
理解符号级别的代码分析

实战 3：使用 AST Grep 进行模式搜索

目标：掌握基于结构的代码搜索

在 JavaScript 项目中输入：

找到所有 console.log 的调用，用 logger.info 替换它们

观察 AI 使用的工具：
- AST Grep Search 查找模式 console.log($MSG)
- AST Grep Replace 替换为 logger.info($MSG)
- 先 dry-run 确认，再实际替换

你应该学到：

AST 模式的强大之处
安全重构的流程

📋 常用工具速查表

文件操作

任务	推荐工具	不推荐
查找所有 ts 文件	Glob `*/.ts`	Bash `find . -name "*.ts"`
搜索代码内容	Grep `pattern`	Bash `grep -r "pattern"`
读取文件	Read	Bash `cat`
编辑文件	Edit	Bash `sed`/`awk`
创建文件	Write	Bash `echo >`

代码分析

任务	推荐工具	说明
查看文件结构	LSP Symbols (document)	获取类、函数列表
查找定义	LSP Go to Definition	跳转到符号定义
查找引用	LSP Find References	找到所有使用位置
重命名符号	LSP Rename	自动更新所有引用
代码诊断	LSP Diagnostics	获取错误和警告
结构化搜索	AST Grep Search	基于代码结构搜索

任务执行

任务	推荐工具	说明
运行测试	Bash `npm test`	执行测试命令
Git 操作	Bash `git ...`	或使用 git-master skill
安装依赖	Bash `npm install`	包管理器操作
构建项目	Bash `npm run build`	执行构建脚本

检查点 ✅

全部通过才能继续

[ ] 了解所有主要工具的用途
[ ] 能根据任务选择合适的工具
[ ] 理解工具的参数和返回值
[ ] 掌握工具组合的使用方法

踩坑提醒

现象	原因	解决
工具执行超时	命令执行时间过长	增加 timeout 参数或优化命令
编辑文件失败	oldString 不匹配或出现多次	提供更多上下文使其唯一，或使用 replaceAll
AST 搜索不到结果	模式语法错误或语言不匹配	确保模式是完整有效的代码，指定正确的 lang
LSP 工具无响应	语言服务器未启动	确保项目正确配置了 LSP
并行命令冲突	命令有依赖关系	用 `&&` 串行执行相关命令

本课小结

你学会了：

OpenCode 内置工具的分类和功能
如何根据任务选择合适的工具
文件操作、代码分析、执行环境等核心工具的使用
工具组合的高级技巧
常用工具的速查方法

下一课预告

下一课我们将学习代码格式化器配置，了解如何统一项目代码风格，配置 Prettier、ESLint 等格式化工具。

📚 更多完整模板：Prompt 模板库

5.17 内置工具 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

工具分类概览 ​

工具使用原则 ​

内置工具详解 ​

📁 文件操作类 ​

Read - 文件读取 ​

Write - 文件写入 ​

Edit - 文件编辑 ​

Glob - 文件匹配 ​

Grep - 内容搜索 ​

🔍 代码分析类 ​

LSP 符号工具 ​

AST Grep - AST 模式搜索 ​

⚙️ 执行环境类 ​

Bash - 命令行执行 ​

🤖 Agent 管理类 ​

Delegate Task - 委派任务 ​

Background Output - 获取后台任务结果 ​

Background Cancel - 取消后台任务 ​

🌐 Web 与网络类 ​

Web Search - 网页搜索 ​

Code Search - 代码示例搜索 ​

Web Fetch - 网页抓取 ​

📚 会话管理类 ​

Session List - 列出所有会话 ​

Session Read - 读取会话内容 ​

Session Search - 搜索会话内容 ​

🔧 Git 操作类 ​

Git 相关 Bash 命令 ​

跟我做 ​

实战 1：理解 AI 如何使用工具 ​

实战 2：使用 LSP 工具进行代码导航 ​

实战 3：使用 AST Grep 进行模式搜索 ​

📋 常用工具速查表 ​

文件操作 ​

代码分析 ​

任务执行 ​

检查点 ✅ ​

踩坑提醒 ​

本课小结 ​

下一课预告 ​

5.17 内置工具

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

工具分类概览

工具使用原则

内置工具详解

📁 文件操作类

Read - 文件读取

Write - 文件写入

Edit - 文件编辑

Glob - 文件匹配

Grep - 内容搜索

🔍 代码分析类

LSP 符号工具

AST Grep - AST 模式搜索

⚙️ 执行环境类

Bash - 命令行执行

🤖 Agent 管理类

Delegate Task - 委派任务

Background Output - 获取后台任务结果

Background Cancel - 取消后台任务

🌐 Web 与网络类

Web Search - 网页搜索

Code Search - 代码示例搜索

Web Fetch - 网页抓取

📚 会话管理类

Session List - 列出所有会话

Session Read - 读取会话内容

Session Search - 搜索会话内容

🔧 Git 操作类

Git 相关 Bash 命令

跟我做

实战 1：理解 AI 如何使用工具

实战 2：使用 LSP 工具进行代码导航

实战 3：使用 AST Grep 进行模式搜索

📋 常用工具速查表

文件操作

代码分析

任务执行

检查点 ✅

踩坑提醒

本课小结

下一课预告