OpenCode 文件引用与快捷命令完全指南：掌握 @ 和 / 的高效协作技巧

在使用 OpenCode 进行日常开发时，有两个核心交互方式能显著提升工作效率：@ 文件引用系统 和 / 快捷命令系统。前者让你精准地将项目文件注入 AI 的上下文，后者让你一键完成会话管理、撤销恢复等操作。本文将从基础用法到高级技巧，全面解析这两个系统的使用之道。

@ 文件引用系统：精准控制 AI 的上下文

OpenCode 的 @ 引用是 TUI 中最常用的交互功能之一。在输入消息时键入 @，会触发一个模糊搜索（fuzzy search），让你快速定位项目中的文件。

基础文件引用

最简单的用法是直接在消息中输入 @ 后跟文件名关键词：

如何解析认证逻辑？请参考 @packages/functions/src/api/index.ts

输入 @ 后，OpenCode 会弹出候选列表，支持模糊匹配。你不需要输入完整的路径，只需要几个关键词就能定位到目标文件。选中后，该文件的完整内容会自动附加到当前会话的上下文中，AI 在生成回答时就能直接参考文件内容。

引用图片

OpenCode 还支持直接在终端中拖放图片。当你拖入一张图片时，它会自动被添加到消息中，AI 能够分析图片内容——这对于设计稿评审、UI 截图分析等场景非常实用。

参考这张设计稿实现新页面的布局
[拖入图片到终端]

配置引用（References）：跨项目文件访问

除了当前项目内的文件引用，OpenCode 还提供了 References 配置系统，允许你在 opencode.json 中定义外部目录或 Git 仓库作为引用源：

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "产品文档，用于确认业务逻辑和文档规范"
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "JavaScript SDK 实现参考"
    },
    "design-system": {
      "path": "../design-system",
      "description": "UI 组件库和设计 Token"
    }
  }
}

配置完成后，在 TUI 中输入 @docs/ 就能模糊搜索该目录下的文件，输入 @sdk 则直接引用远程 Git 仓库的根目录。description 字段会让 AI 在合适的场景下自动检查这些引用，无需手动附加。

高级用法：如果你有一个大型 monorepo 项目，可以将共享库、文档、配置文件分别配置为独立的引用，用 @ 快速切换上下文，而不需要每次都输入冗长的路径。

隐藏引用

有些内部目录你可能不希望出现在 @ 自动补全列表中，但仍希望 AI 知道它们的存在：

{
  "references": {
    "internal": {
      "path": "../internal",
      "hidden": true,
      "description": "内部实现细节"
    }
  }
}

hidden: true 会让该引用从 TUI 的自动补全列表中消失，但如果 AI 认为需要参考该目录，它仍然可以访问。

/ 快捷命令系统：一站式会话控制

OpenCode 的 / 命令系统提供了一系列快捷操作，覆盖会话管理、撤销恢复、配置连接等场景。下面逐一介绍最常用的命令。

会话管理命令

/init — 项目初始化。在项目根目录运行此命令，OpenCode 会分析项目结构并生成 AGENTS.md 文件，其中包含项目概述、技术栈、编码规范等信息。建议将 AGENTS.md 提交到 Git 仓库。

/init

/new — 开启新会话。当你完成一个任务后，用此命令清空当前上下文，开始全新的对话。别名：/clear。快捷键：ctrl+x n。

/new

/sessions — 列出并切换历史会话。OpenCode 会自动保存所有会话，你可以随时回溯之前的对话，继续未完成的任务。别名：/resume、/continue。快捷键：ctrl+x l。

/sessions

/compact — 压缩当前会话。当上下文越来越长时，运行此命令可以让 AI 总结已有对话并压缩 token 占用，释放上下文窗口空间。别名：/summarize。快捷键：ctrl+x c。

/compact

撤销与恢复

/undo — 撤销上一条消息及其产生的所有文件修改。这是 OpenCode 最安全的回退机制——它内部通过 Git 管理文件变更，因此你的项目必须是 Git 仓库才能使用此功能。快捷键：ctrl+x u。

/undo

可以多次执行 /undo 来撤销多步操作。

/redo — 恢复被撤销的操作。如果你误撤销了某些修改，用 /redo 即可还原。快捷键：ctrl+x r。

/redo

这一对组合让你可以像使用版本控制一样，在 AI 的修改之间自由穿梭。

配置与连接

/connect — 添加或切换 AI 模型提供商。OpenCode 支持数十种 LLM 提供商，运行此命令后会弹出交互式选择界面。

/connect

/models — 列出当前已配置的所有可用模型，格式为 provider/model。快捷键：ctrl+x m。

/models

/themes — 浏览和切换 TUI 主题。OpenCode 内置多套主题，你也可以在 tui.json 中自定义主题。快捷键：ctrl+x t。

/themes

编辑与导出

/editor — 打开外部编辑器编写消息。适用于需要编写较长 prompt 的场景。快捷键：ctrl+x e。需要设置 EDITOR 环境变量：

# Linux/macOS
export EDITOR="code --wait"

# Windows
set EDITOR=code --wait

/export — 将当前会话导出为 Markdown 文件，并自动在编辑器中打开。适用于记录调试过程或生成文档。快捷键：ctrl+x x。

/export

分享与协作

/share — 生成当前会话的分享链接，自动复制到剪贴板。你可以将链接发送给团队成员，对方可以直接在浏览器中查看完整的对话记录。

/share

/unshare — 取消分享。如果你不小心分享了包含敏感信息的会话，用此命令可以立即撤销分享。

/unshare

辅助命令

/details — 切换工具执行细节的显示。开启后可以看到 AI 调用了哪些工具、执行了什么命令、读取了哪些文件——对于调试 AI 的行为非常有帮助。

/details

/thinking — 切换思考链（Chain of Thought）的可见性。对于支持深度推理的模型（如 Claude 3.5 Sonnet 的 extended thinking），开启后可以看到模型的推理过程，理解它是如何得出结论的。

/thinking

/help — 显示帮助对话框，列出所有可用命令及其快捷方式。

/help

/exit — 退出 OpenCode。别名：/quit、/q。快捷键：ctrl+x q。

/exit

实战工作流：@ 引用 + / 命令的组合应用

下面以一个实际场景演示如何将二者结合使用。

场景：为项目添加数据导出功能

用 /init 初始化项目上下文，确保 AI 理解项目结构和技术栈

用 /new 开启新会话，避免旧上下文干扰

用 @ 引用相关文件，提供精确上下文：

请参考 @src/services/userService.ts 中的查询逻辑，
以及 @src/types/export.d.ts 中的类型定义，
在 @src/controllers/AdminController.ts 中添加 CSV 导出功能。

用 /editor 打开编辑器编写详细 prompt，描述功能需求

AI 执行修改后，用 /details 查看具体改动了哪些文件

如果不满意，立即用 /undo 回退

满意后，用 /share 将整个对话分享给同事做 Code Review

这套工作流的核心思路是：先用 / 管理会话状态和配置，再用 @ 精确控制输入上下文，让 AI 始终聚焦在你关心的代码上。

总结

OpenCode 的 @ 文件引用和 / 快捷命令构成了 TUI 交互的基石。@ 让你像在 IDE 中跳转定义一样精准地引用文件，而 / 命令则提供了丰富的会话控制能力。熟练掌握这两套系统，可以让你在日常开发中减少重复操作，将更多的精力集中在业务逻辑本身。

建议你打开终端，在项目目录下运行 opencode，逐个尝试本文介绍的命令，形成肌肉记忆后，你会发现 AI 编程的效率会有质的飞跃。