LowHow 文档

中文

English

中文

English

深色模式

OpenCode AI 助手工具集实战教程：从文件查找到代码修改 ​

📚 分类: AI 编程辅助工具 ⏱️ 预计耗时: 45 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode (基于终端的 AI 编程助手)

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 掌握 OpenCode AI 助手的核心工具：文件搜索、内容查找、文件操作和系统交互
  • [ ] 独立使用 glob、grep 等工具高效浏览和理解代码库
  • [ ] 安全地使用 view、write、edit 工具修改文件，并理解其最佳实践
  • [ ] 使用 bash、diagnostics 等工具进行调试和验证

最终效果 ​

你将能够通过自然语言指令，让 OpenCode 的 AI 助手执行一系列复杂的代码库操作，例如：查找所有 TypeScript 文件、在特定文件中搜索并替换文本、运行测试命令等。你将理解如何像一个经验丰富的开发者一样，与 AI 助手协作，高效地完成日常开发任务。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
OpenCode最新稳定版opencode --version

1. 了解 OpenCode 的交互模式 ​

OpenCode 支持两种模式：交互模式和非交互模式。

  • 交互模式：在终端中直接输入 opencode 启动，进入一个类似聊天的界面。
  • 非交互模式：通过 opencode -m "你的指令" 一次性执行任务。

本教程将主要基于 交互模式 进行讲解，因为它更直观，能让你看到 AI 助手的思考过程。

✅ 验证：在终端输入 opencode 并按回车，如果成功启动一个对话界面，说明环境就绪。

第 1 步：使用 glob 工具查找文件 ​

🎯 目标：学会使用 glob 工具，根据文件名模式（如 *.ts）快速定位项目中的文件。

📝 操作：

假设你有一个项目，你想找到所有 TypeScript 文件。在 OpenCode 的交互界面中，输入以下指令：

text
请帮我使用 glob 工具，查找当前目录下所有以 .ts 结尾的文件。

AI 助手会理解你的指令，并执行相应的 glob 工具。它内部执行的命令类似于：

bash
# 在 OpenCode 内部，AI 助手会调用 glob 工具
# 参数 pattern: "*.ts"
# 参数 path: "." (默认当前工作目录)

✅ 验证： AI 助手会返回一个文件列表。你应该会看到类似下面的输出（取决于你的项目）：

text
找到以下匹配文件：
- src/utils/helper.ts
- src/index.ts
- tests/unit.test.ts

💡 提示：glob 的 pattern 参数非常灵活。

  • **/*.ts：匹配任何子目录下的 .ts 文件。
  • src/**/*.{ts,tsx}：匹配 src 目录下所有 .ts 和 .tsx 文件。

🤔 为什么要这样做？glob 工具是 AI 助手了解你项目文件结构的“眼睛”。通过指定模式，你可以让 AI 快速定位到你需要操作的文件，而无需手动在文件系统中翻找。

⚠️ 常见错误： 如果你想让 AI 在 src 目录下查找，但忘记指定 path，它会在当前目录查找。如果当前目录不是项目根目录，可能找不到任何文件。始终明确指定 path 参数是一个好习惯。

第 2 步：使用 grep 工具搜索文件内容 ​

🎯 目标：学会使用 grep 工具，在文件内容中搜索特定的文本或正则表达式。

📝 操作：

上一步我们学会了根据文件名找文件。现在，假设你想找到项目中所有使用了 handleRequest 函数的地方。

在 OpenCode 的交互界面中，输入以下指令：

text
请帮我使用 grep 工具，搜索项目所有文件中包含 "handleRequest" 文本的行。

AI 助手会调用 grep 工具，其内部逻辑类似：

bash
# 参数 pattern: "handleRequest"
# 参数 path: "." (默认当前工作目录)

✅ 验证： AI 助手会返回一个包含匹配内容的列表，类似于：

text
找到 3 处匹配：
/path/to/your/project/src/handler.ts:
  Line 42: export function handleRequest() {
  Line 56: const result = handleRequest();
/path/to/your/project/src/utils.ts:
  Line 12: import { handleRequest } from './handler';

💡 提示：

  • 如果你想搜索包含特殊字符（如 .、*）的文本，可以加上 literal_text: true 参数，告诉 AI 工具将其视为普通文本，而不是正则表达式。例如，搜索 log.Error 时，literal_text: true 可以避免 . 被解释为“匹配任意字符”。
  • 你也可以指定搜索范围，例如 include: "*.go"，只搜索 Go 文件。

第 3 步：使用 view 工具查看文件内容 ​

🎯 目标：学会使用 view 工具，安全地读取文件内容，为后续修改做准备。

📝 操作：

现在，你已经找到了包含 handleRequest 的文件 src/handler.ts。你想查看它的完整内容。

在 OpenCode 中，输入以下指令：

text
请帮我使用 view 工具，查看 src/handler.ts 文件的内容。

AI 助手会调用 view 工具，其内部逻辑是：

bash
# 参数 file_path: "/absolute/path/to/your/project/src/handler.ts"

✅ 验证： AI 助手会返回文件内容，并显示行号，类似于：

text
<file>
1| import { useState } from 'react';
2| 
3| export function MyComponent() {
4|   const [count, setCount] = useState(0);
5|   return <div>{count}</div>;
6| }
</file>

🤔 为什么要这样做？view 工具是修改文件的第一步。官方最佳实践明确指出：在修改文件之前，必须先使用 view 工具读取它。这能确保 AI 助手知道你文件的最新状态，避免覆盖你最近的手动修改。

⚠️ 常见错误： 如果直接让 AI 修改文件而不先 view，它可能会：

  • 使用过时的文件内容进行修改，导致你的工作丢失。
  • 因为不知道文件的实际内容，而生成错误的修改指令。

第 4 步：使用 edit 工具修改文件 ​

🎯 目标：学会使用 edit 工具，安全地替换文件中的特定文本。

📝 操作：

上一步我们已经查看了 src/handler.ts，假设我们要将函数名 handleRequest 改为 processRequest。

在 OpenCode 中，输入以下指令：

text
请帮我使用 edit 工具，修改 src/handler.ts 文件。
将 "export function handleRequest() {" 替换为 "export function processRequest() {"。

AI 助手会调用 edit 工具，并遵循严格的规则：

  1. 再次确认：它会确认你刚刚已经 view 过这个文件。
  2. 唯一性检查：它会确保 old_string（要替换的文本）在文件中是唯一的。
  3. 执行替换：
bash
# edit 工具参数示例
# file_path: "/absolute/path/to/your/project/src/handler.ts"
# old_string: "export function handleRequest() {"
# new_string: "export function processRequest() {"

✅ 验证： AI 助手会返回一个“差异”（diff）输出，显示修改前后的对比：

diff
- export function handleRequest() {
+ export function processRequest() {

并且，AI 助手会自动运行 LSP 诊断，检查修改后的文件是否有语法错误。如果一切正常，它会告诉你修改成功。

🤔 为什么要这样做？edit 工具通过精确匹配 old_string 来定位修改点，这比简单的“替换第 X 行”更安全，因为它不依赖于行号，即使文件内容在其他地方有微小变动，也能准确定位。

⚠️ 常见错误：

  • old_string 不唯一：如果文件中有两处完全相同的文本，edit 工具会报错。你需要提供更多上下文（例如，包含 old_string 前后的几行代码）来确保唯一性。
  • old_string 找不到：如果你输入的 old_string 与实际文件内容有微小的空格或缩进差异，工具也会失败。最佳实践是：直接从 view 的输出中复制你要替换的文本。

第 5 步：使用 bash 工具执行命令 ​

🎯 目标：学会使用 bash 工具，让 AI 助手在终端中执行命令，例如运行测试或查看 Git 状态。

📝 操作：

现在，假设我们修改了代码，想运行测试来验证修改是否正确。

在 OpenCode 中，输入以下指令：

text
请帮我使用 bash 工具，在项目根目录下运行 npm test 命令。

AI 助手会调用 bash 工具执行命令：

bash
$ cd /path/to/your/project
$ npm test

✅ 验证： AI 助手会实时显示命令的输出，包括测试结果。

text
> my-project@1.0.0 test
> jest

 PASS  src/__tests__/handler.test.ts
  ✓ should process request correctly (5 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.234 s
Ran all test suites.

💡 提示：

  • bash 工具在一个 持久化 的 shell 会话中运行。这意味着你可以在一个步骤中 cd 到一个目录，在下一个步骤中执行该目录下的命令。
  • 一些网络工具（如 curl、wget）和浏览器命令被列为“不安全”，需要用户确认才能执行。OpenCode 提供了专门的 fetch 工具来安全地获取网络资源。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 使用 patch 工具进行多文件原子操作：当你需要同时修改多个文件时（例如，重命名一个函数并更新所有引用它的地方），可以使用 patch 工具。它允许你一次性提交所有修改，要么全部成功，要么全部失败，避免了中途出错导致项目状态不一致的风险。

  2. 使用 sourcegraph 工具研究开源代码：如果你想学习某个知名库（如 lodash）的实现方式，可以告诉 AI：“请使用 sourcegraph 工具，在 lodash 仓库中搜索 debounce 函数的实现”。这能帮你快速找到最佳实践示例。

常见问题 (FAQ) ​

Q1: 报错 old_string 在文件中出现多次怎么办？A: 这意味着你需要提供更精确的 old_string。不要只提供要替换的那一行，而是提供包含该行的前后 3-5 行上下文。例如，替换 const value = 123; 时，可以指定 old_string 为：

function someFunc() {
  const value = 123;
  return value;
}

这样就能唯一定位到你要修改的位置。

Q2: 如何让 AI 助手一次性执行多个独立任务？A: 你可以在一次对话中，向 AI 助手发送多个独立的指令，例如：“先帮我用 glob 查找所有 .json 文件，然后用 grep 搜索这些文件中包含 version 的行”。AI 助手会并行执行这些不相关的工具调用，提高效率。

Q3: 如何让 AI 助手在会话期间记住我的授权？A: 当 AI 助手执行一个需要你授权的操作（如 write、edit）时，它会弹出一个权限对话框。你可以按键盘上的 A 键，为该 整个会话 授予权限。这样，在当前 OpenCode 会话结束前，AI 助手执行所有类似的写操作都无需再次确认。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 文件搜索：使用 glob（按文件名）和 grep（按文件内容）快速定位代码。
  2. 文件读取：使用 view 工具安全地读取文件内容，这是任何修改操作的前提。
  3. 文件修改：使用 edit 工具进行精确的文本替换，并使用 patch 工具处理多文件原子性变更。
  4. 系统交互：使用 bash 工具执行命令（如测试、Git 操作）进行验证和调试。
  5. 最佳实践：始终先 view 再 edit，使用唯一上下文进行匹配，利用 diagnostics 检查错误。

© 2026 LowHow