主题
1.2 OpenCode 的工作原理：Agent + 工具 + 上下文
AI 编程助手不是"聊天机器人"——它是一个能看懂你的项目、会动手改代码、知道什么时候该用什么工具的 Agent。理解这一点，是从"会用"到"用好"的关键。
这一节在讲什么？
上一节我们聊了 OpenCode 是什么、它跟其他工具有什么区别。这一节我们要往深处走——OpenCode 内部是怎么工作的？当你输入一个问题，到 AI 给出回答并修改代码，中间发生了什么？理解这个过程不是"炫技"，而是"必修课"——因为只有理解了 Agent 的工作原理，你才能知道什么时候该用 Plan 模式、什么时候该用 Build 模式、什么时候该手动提供上下文、什么时候 AI 会"迷路"。这一节会帮你建立对 OpenCode 内部机制的完整认知。
Agent 架构：Plan 和 Build 的双模式设计
OpenCode 的核心是一个 Agent——它不是一个简单的"问答机器人"，而是一个能自主决策、调用工具、多轮迭代的智能体。理解 Agent 和聊天机器人的区别很重要：
聊天机器人的工作流：
用户提问 → LLM 生成回答 → 返回给用户
（一轮就结束，LLM 只能"说"，不能"做"）
Agent 的工作流：
用户提问 → LLM 分析任务 → 决定调用哪些工具
→ 调用工具（读文件、执行命令...）→ 获取工具结果
→ LLM 根据结果继续推理 → 可能再调用工具
→ ...（多轮迭代）→ 生成最终回答
（多轮迭代，LLM 既能"说"，也能"做"）比如，你让 OpenCode "给这个项目添加一个健康检查接口"，一个聊天机器人只能给你一段代码让你自己粘贴，但 Agent 会这样做：
- 读取项目结构，了解这是什么框架（Express? FastAPI? Spring Boot?）
- 找到现有的路由文件，了解代码风格
- 创建新的路由文件或修改现有文件
- 运行测试，确认没有引入错误
- 如果测试失败，分析失败原因并修复
- 返回最终结果
这个过程可能涉及 5~10 次工具调用，而用户只需要输入一句话。这就是 Agent 的力量。
OpenCode 提供了两种 Agent 模式：
Plan 模式（规划模式）：AI 只分析任务、制定方案，但不执行任何修改。适合复杂任务的方案设计——你先看 AI 的计划是否合理，再决定是否执行。在 TUI 里按 Tab 键切换到 Plan 模式，右下角会显示 "Plan" 指示器。
Build 模式（执行模式）：AI 直接执行文件修改和命令。适合快速迭代——你信任 AI 的判断，让它直接动手。这是默认模式。
为什么要分两种模式？因为 AI 不是万能的——它可能会误解你的意图、修改不该改的文件、执行危险的命令。Plan 模式给你一个"安全网"——先看方案，再决定执行。对于复杂任务（比如重构、架构调整），强烈建议先用 Plan 模式；对于简单任务（比如修个 bug、加个字段），直接 Build 模式就行。
Plan 模式 vs Build 模式的选择策略：
简单修改（修 bug、加字段、改文案）
→ Build 模式，直接执行
中等任务（添加新接口、新页面）
→ 先 Plan 看方案，再 Build 执行
复杂任务（重构、架构调整、跨文件修改）
→ 必须先 Plan，审查方案后再 Build
不确定的任务
→ 先 Plan，看看 AI 怎么理解你的需求工具系统：AI 的"手和脚"
Agent 如果没有工具，就像一个只能说话不能动手的顾问——它知道该怎么做，但做不了。OpenCode 的工具系统就是 AI 的"手和脚"，让它能真正操作你的项目。
OpenCode 的内置工具：
| 工具 | 能力 | 典型使用场景 |
|---|---|---|
| READ | 读取文件内容 | AI 读取你的源码来理解上下文 |
| WRITE | 创建或修改文件 | AI 修改代码、创建新文件 |
| RUN | 执行 shell 命令 | 运行测试、安装依赖、查看日志 |
| SEARCH | 搜索代码和文件 | 在项目中搜索函数定义、查找引用 |
| DIAGNOSTICS | 代码诊断（LSP） | 获取类型错误、lint 警告 |
这些工具不是随意调用的——AI 会根据任务需要自主决定调用哪些工具、以什么顺序调用。比如，当你问"这个函数为什么报错"时，AI 可能会：
- 先用 READ 读取报错的文件
- 用 DIAGNOSTICS 获取 LSP 诊断信息
- 用 SEARCH 查找相关函数的定义
- 用 READ 读取相关文件
- 综合分析后给出修复方案
整个过程 AI 自主完成，你不需要手动指定每一步。
工具权限也是可控的。在配置文件中，你可以限制 Agent 能使用哪些工具：
json
{
"agents": {
"coder": {
"model": "anthropic/claude-sonnet-4-20250514",
"maxTokens": 16384,
"tools": {
"READ": true,
"WRITE": true,
"RUN": true,
"SEARCH": true,
"DIAGNOSTICS": true
}
}
}
}比如，如果你只想让 AI 读取和分析代码，但不让它修改文件，可以把 WRITE 设为 false。这在代码审查场景很有用——让 AI 看代码、找问题，但不让它改代码。
上下文管理：AI 怎么"理解"你的项目
AI 编程助手的效果，很大程度上取决于它能看到多少上下文。如果你只给 AI 一段代码片段，它只能给出泛泛的建议；如果你给 AI 整个项目的上下文，它就能给出精准的修改方案。OpenCode 的上下文管理是它区别于简单聊天机器人的关键能力。
OpenCode 的上下文来源有四个：
1. 项目文件扫描
当你在一个项目目录下启动 OpenCode 时，它会自动扫描项目结构——目录树、主要文件、配置文件。这让 AI 知道你的项目用了什么框架、什么语言、什么依赖。/init 命令会进一步分析项目并生成 AGENTS.md 文件，作为项目的"AI 说明书"。
2. LSP 代码智能
OpenCode 集成了 LSP（Language Server Protocol），这意味着 AI 能获取代码的语义信息——类型定义、函数签名、引用关系。当 AI 修改一个函数时，它能通过 LSP 知道哪些地方调用了这个函数，修改会不会影响其他模块。这是纯文本搜索做不到的。
3. 会话历史
你和 AI 的对话历史也是上下文的一部分。AI 能记住你之前说过什么、它之前做了什么修改。但上下文窗口是有限的——当对话太长时，OpenCode 会自动压缩历史（Auto Compact），保留关键信息的摘要。
4. 用户主动提供的上下文
你可以通过 @ 引用文件、$ 执行命令并引入输出，主动给 AI 提供更多上下文。这是你能控制的部分，也是最容易被忽略的部分——很多用户抱怨"AI 不理解我的项目"，其实是因为他们没有主动提供足够的上下文。
上下文管理的最佳实践：
✅ 好的做法：
- 启动后先运行 /init，让 AI 了解项目
- 用 @filename 引用关键文件
- 用 $ command 引入命令输出
- 长对话定期 /compact 或开新会话
❌ 常见错误：
- 不运行 /init，AI 对项目一无所知
- 问题描述太笼统："帮我改一下代码"
- 对话太长不压缩，AI 在大量历史中"迷路"
- 一次问多个不相关的问题，上下文互相干扰数据流：从输入到输出的完整过程
现在我们把上面的内容串起来，看看当你输入一个问题到 AI 给出回答，OpenCode 内部发生了什么：
用户输入："给这个项目添加一个 /health 健康检查接口"
┌─────────────────────────────────────────────┐
│ 1. 上下文收集 │
│ - 读取 AGENTS.md（项目架构信息） │
│ - 读取项目目录结构 │
│ - 读取会话历史（之前的对话） │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ 2. LLM 推理（第一轮） │
│ - 分析任务：需要添加一个 HTTP 接口 │
│ - 决定工具调用：先读取路由文件 │
│ - 输出：tool_call(READ, "src/routes.ts") │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ 3. 工具执行 │
│ - READ 工具读取 src/routes.ts │
│ - 返回文件内容 │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ 4. LLM 推理（第二轮） │
│ - 分析路由文件：这是 Express 项目 │
│ - 决定工具调用：修改路由文件添加 /health │
│ - 输出：tool_call(WRITE, "src/routes.ts")│
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ 5. 工具执行 │
│ - WRITE 工具修改 src/routes.ts │
│ - 返回修改结果 │
└──────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ 6. LLM 推理（第三轮） │
│ - 确认修改完成 │
│ - 生成最终回答：已添加 /health 接口 │
└─────────────────────────────────────────────┘这个过程有几个关键点值得注意：
多轮迭代：Agent 不是一次调用就结束——它可能需要多次工具调用，每次调用后根据结果继续推理。上面的例子是 3 轮，复杂任务可能需要 10+ 轮。
自主决策：AI 自己决定调用什么工具、以什么顺序调用。你不需要告诉它"先读文件再改文件"——它自己会推理出这个顺序。
上下文累积：每一轮的工具调用结果都会加入上下文，AI 在后续推理中能看到所有之前的信息。这意味着上下文会越来越长——这也是为什么 Auto Compact 机制很重要。
与 Claude Code 的架构对比
OpenCode 和 Claude Code 都采用 Agent 架构，但有几个关键区别：
| 维度 | OpenCode | Claude Code |
|---|---|---|
| 开源 | ✅ MIT | ❌ 闭源 |
| 模型 | 75+ 提供商 | 仅 Claude |
| MCP 扩展 | ✅ 原生支持 | ❌ 不支持 |
| LSP 集成 | ✅ 支持 | ❌ 不支持 |
| 界面 | TUI（图形化终端界面） | CLI（纯命令行） |
| Plan/Build 模式 | ✅ Tab 切换 | ❌ 无 |
| 会话管理 | ✅ 多会话并行 | ❌ 单会话 |
| 代码可审计 | ✅ 完全开源 | ❌ 无法审计 |
最本质的区别在于可扩展性：OpenCode 通过 MCP 协议可以连接任意外部工具，而 Claude Code 是一个封闭系统——你能用的工具只有它内置的那几个。这意味着 OpenCode 的能力边界是"你能配置多少 MCP 服务器"，而 Claude Code 的能力边界是"Anthropic 给你多少内置工具"。
常见误区
误区一：Agent 就是聊天机器人
不是。聊天机器人只能"说"——生成文本回答。Agent 既能"说"也能"做"——它能调用工具、执行操作、多轮迭代。当你让 OpenCode "修复这个 bug"，它不是给你一段代码让你自己粘贴，而是自己读取文件、分析问题、修改代码、运行测试。这个区别是根本性的。
误区二：Plan 模式没用，直接 Build 更快
对于简单任务确实如此。但对于复杂任务，Plan 模式是"安全网"——AI 可能会误解你的意图，直接 Build 可能导致错误的修改。先 Plan 看 AI 的理解是否正确，再 Build 执行，比盲目执行后 /undo 更高效。
误区三：上下文越多越好
不一定。上下文窗口是有限的，塞太多无关信息反而会让 AI "迷路"——它会在大量信息中找不到重点。好的做法是提供精准的上下文——用 @ 引用关键文件，用 $ 引入关键命令输出，而不是把整个项目都塞进去。
误区四：AI 每次都能正确选择工具
大部分时候 AI 的工具选择是合理的，但不是 100% 可靠。有时候 AI 会在不该修改文件的时候修改文件，或者在不该执行命令的时候执行命令。这就是为什么 Plan 模式和 /undo 命令很重要——它们给你"后悔药"。
小结
这一节我们深入了 OpenCode 的工作原理：它的 Agent 架构通过 Plan/Build 双模式平衡了安全性和效率；它的工具系统让 AI 能真正操作你的项目（读写文件、执行命令、搜索代码、LSP 诊断）；它的上下文管理通过项目扫描、LSP 智能和会话历史让 AI 理解你的项目；整个数据流是多轮迭代的——AI 自主决定调用什么工具，根据结果继续推理。理解了这些，你就能在下一节的快速体验中知道"为什么 AI 要先读文件再改文件"、"为什么长对话需要压缩"、"为什么 Plan 模式很重要"。