主题
3.2 文件引用与上下文控制
AI 编程助手的效果，80% 取决于你给了它多少上下文。@ 引用文件、$ 执行命令、/ 斜杠命令——这三招让你精准控制 AI 能看到什么。
这一节在讲什么？
你有没有遇到过这种情况——问 OpenCode "帮我改一下登录逻辑"，它改的完全不是你想改的地方？或者问"这个 bug 怎么修"，它给的方案跟你的项目完全不搭？这些问题 80% 是因为上下文不够——AI 不知道你想改哪个文件、你的项目用什么框架、当前的错误信息是什么。OpenCode 提供了三种强大的上下文控制机制：@ 文件引用、$ 命令引用、/ 斜杠命令。这一节我们把这三种机制讲透，帮你从"AI 瞎答"升级到"AI 精准答"。
@ 文件引用：让 AI 看到你的代码
@ 是 OpenCode 最常用的上下文控制方式——它让 AI "看到"你指定的文件或目录的内容。
引用单个文件：
看一下 @src/auth/login.ts 的认证逻辑有没有安全问题AI 会读取 src/auth/login.ts 的内容，基于文件的实际代码来回答你的问题——而不是泛泛地说"认证一般有这些安全问题"。
引用目录：
分析一下 @src/components/ 目录下的组件结构AI 会扫描整个目录，了解组件的组织方式、命名规范、依赖关系。
使用 glob 模式：
检查一下 @**/*.test.ts 里的测试有没有问题AI 会匹配所有符合 **/*.test.ts 模式的文件，批量分析。
引用多个文件：
对比一下 @src/auth/login.ts 和 @src/auth/register.ts 的逻辑AI 会同时读取两个文件，进行对比分析。
@ 引用的底层原理：当你用 @filename 引用文件时，OpenCode 会把文件内容作为上下文发送给 LLM。这意味着引用的文件会占用上下文窗口——引用太多文件会导致上下文溢出，AI 的回答质量反而会下降。
@ 引用的最佳实践：
✅ 好的做法：
- 只引用跟问题直接相关的文件
- 用具体的文件路径，不用太大的目录
- 一次引用 2-3 个文件，不要一次引用整个项目
❌ 常见错误：
- @src/ 引用整个源码目录（上下文爆炸）
- 引用跟问题无关的文件（浪费上下文窗口）
- 不用 @ 引用，让 AI 自己猜（回答质量低）$ 命令引用：让 AI 看到命令输出
$ 让 AI 能看到命令的执行输出——这在调试、分析日志、查看项目状态时非常有用。
基本用法：
$ npm run build 的输出有什么错误？帮我修复AI 会执行 npm run build，获取输出，分析错误，然后给出修复方案。
引入命令输出作为上下文：
$ git diff 的改动看起来对吗？AI 会执行 git diff，查看当前的代码变更，然后给出审查意见。
查看日志：
$ cat logs/error.log 里的错误是什么原因？查看系统状态：
$ docker ps 看看哪些容器在运行$$ 双美元符号：$$ 会执行命令并把输出加入上下文，但不会让 AI 直接分析——你可以在后续对话中引用这个输出：
$$ cat package.json
现在帮我升级所有依赖到最新版本斜杠命令大全
斜杠命令是 OpenCode 的"快捷操作"——输入 / 加命令名，就能执行特定的操作。这是你跟 OpenCode 交互的"控制面板"。
/init：初始化项目
/init分析项目结构，生成 AGENTS.md 文件。这是你在一个新项目中使用 OpenCode 时应该运行的第一个命令。AGENTS.md 是 AI 的"项目说明书"——没有它，AI 对你的项目一无所知。
/clear：清空会话
/clear清空当前会话的所有对话历史，重新开始。当你想换一个全新的话题，或者对话历史太长导致 AI 回答质量下降时，用这个命令。
/compact：压缩对话历史
/compact手动触发对话历史的压缩。OpenCode 会把之前的对话总结成一段摘要，保留关键信息，丢弃冗余细节。压缩后，AI 仍然知道之前讨论了什么，但上下文占用大幅减少。
/models：切换模型
/models在 TUI 中打开模型选择界面，列出所有可用的模型。你可以选择不同的模型来处理不同复杂度的任务。
/sessions：管理会话
/sessions查看和管理所有会话。你可以切换到之前的会话、创建新会话、删除旧会话。
/share：分享会话
/share生成当前对话的分享链接，复制到剪贴板。你可以把这个链接发给同事，让他们看到你和 AI 的完整对话。这在团队协作和知识分享时非常有用。
/cost：查看使用成本
/cost查看当前会话的 token 使用量和费用。如果你关心 API 调用成本，这个命令能帮你实时监控。
/undo 和 /redo：撤销和重做
/undo撤销 AI 的最后一次修改。如果 AI 改的代码不是你想要的，用 /undo 回退到修改前的状态。
/redo重做之前撤销的修改。如果你发现撤销错了，用 /redo 恢复。
/context：管理上下文
/context查看当前上下文中包含了哪些文件和命令输出。当你觉得 AI 的回答"不对劲"时，用这个命令检查上下文——可能是 AI 看到了错误的文件，或者缺少关键信息。
上下文管理策略
上下文管理是使用 AI 编程助手的核心技能。好的上下文管理能让 AI 的回答精准高效，差的上下文管理会让 AI "迷路"。
策略一：精准引用，不要贪多
❌ 差的做法：
"帮我看看项目有什么问题"
→ AI 不知道看哪里，回答泛泛
✅ 好的做法：
"看一下 @src/api/auth.ts 的错误处理有没有遗漏"
→ AI 聚焦在具体文件，回答精准策略二：用 $ 引入关键信息
❌ 差的做法：
"测试失败了，帮我修"
→ AI 不知道什么测试、什么错误
✅ 好的做法：
"$ npm test 的输出有 2 个失败，帮我修复"
→ AI 能看到具体的错误信息，精准定位策略三：长对话定期 /compact 或开新会话
对话轮数 AI 回答质量
─────────────────────────
1-10 轮 ⭐⭐⭐⭐⭐ 很好
10-20 轮 ⭐⭐⭐⭐ 还行
20-30 轮 ⭐⭐⭐ 开始下降
30+ 轮 ⭐⭐ 明显下降
建议：
- 20 轮左右执行 /compact
- 换话题时开新会话（/clear 或新 session）
- 复杂任务分成多个小会话策略四：一次只做一件事
❌ 差的做法：
"帮我修一下登录 bug，顺便加个注册功能，再把首页样式调一下"
→ 三个任务混在一起，AI 容易遗漏或混淆
✅ 好的做法：
先在一个会话里修登录 bug
→ 完成后开新会话加注册功能
→ 再开新会话调首页样式常见误区
误区一：上下文越多越好
不是。上下文窗口是有限的（Claude Sonnet 约 200K token），塞太多无关信息会让 AI "迷路"——它会在大量信息中找不到重点，回答质量反而下降。好的做法是提供精准的上下文——只引用跟问题直接相关的文件和命令输出。
误区二：不用 @ 引用，让 AI 自己找
AI 确实有 SEARCH 工具可以自己搜索文件，但它的搜索是"猜测式"的——它不知道你心里想的是哪个文件。用 @ 明确引用文件，比让 AI 自己找更高效、更准确。特别是当项目有多个同名文件（比如多个 index.ts）时，AI 可能找到错误的文件。
误区三：/compact 会丢失重要信息
不会。/compact 不是"删除历史"，而是"压缩历史"——OpenCode 会把之前的对话总结成一段摘要，保留关键信息（你问了什么、AI 做了什么修改、当前的进度），丢弃冗余的细节（比如中间的调试过程、重复的讨论）。压缩后，AI 仍然知道之前讨论了什么，只是占用的上下文空间更少了。
误区四：一个会话搞定所有事
这是很多人的习惯——一个会话从头用到尾，什么问题都在里面问。但长对话的 AI 回答质量会逐渐下降，因为上下文越来越长，AI 需要在大量历史中找到相关信息。好的做法是"一事一会话"——每个独立的任务开一个新会话，保持上下文干净。
小结
这一节我们学习了 OpenCode 的三种上下文控制机制：@ 文件引用让 AI 看到你的代码，$ 命令引用让 AI 看到命令输出，/ 斜杠命令提供快捷操作。上下文管理的核心原则是"精准而不贪多"——只提供跟问题直接相关的上下文，长对话定期压缩，每个独立任务开新会话。下一节我们深入 OpenCode 的 Agent 工具系统，看看 AI 到底能调用哪些工具、怎么控制工具权限。