03 · 终端 TUI 工作流

OpenCode 的主战场是终端 TUI。它不是把网页聊天搬进终端，而是把 coding agent 放进你已经在用的 shell、编辑器和项目目录。

TUI 的核心动作

最常用的动作只有几类：

• 输入自然语言任务。
• 用 @ 引用文件。
• 用 ! 执行 shell 命令。
• 用 / 调用内置命令或自定义命令。
• 切换 agent、model、theme、session。
• 压缩会话，继续长任务。

先把这些动作练熟，比一开始研究复杂配置更重要。

文件引用

OpenCode 支持在消息里用 @ 引用文件：

解释 @src/server.ts 的启动流程，并指出配置从哪里读取。

文件引用的价值是“显式给上下文”。不要把上下文管理完全交给模型猜。你越明确告诉它看哪些文件，它越不容易在大项目里跑偏。

比较稳的写法：

只阅读 @src/auth.ts 和 @src/routes/login.ts。
判断登录失败时错误是在哪里被吞掉的。
先解释，不要修改。

这里同时限定了文件、目标和动作顺序。

Shell 命令

以 ! 开头可以执行 shell 命令：

!pnpm test

这让 OpenCode 能把命令输出纳入对话上下文。它适合用来跑测试、看 git 状态、检查 lint、读取脚本结果。

但不要让它随意跑破坏性命令。尤其是下面这些动作，要明确禁止或先要求解释：

• 删除目录。
• 重置 Git 历史。
• 修改全局配置。
• 大范围格式化。
• 上传、发布、部署。

斜杠命令

TUI 中的 / 命令负责常用动作，例如帮助、压缩、分享、切换模型、查看会话等。自定义命令也走这个入口。

当一个提示词反复使用三次以上，就应该考虑沉淀成命令。例如：

/review-auth
/write-release-note
/fix-failing-test

命令的价值不是少打几个字，而是让任务边界、检查顺序和输出格式稳定下来。

会话与压缩

长任务会遇到上下文膨胀。OpenCode 提供 compact / summarize 一类能力，把历史对话压缩后继续。

使用压缩前最好先让 agent 产出一个明确的状态快照：

在压缩前，先列出：
1. 已完成的文件改动
2. 仍未解决的问题
3. 下一步必须检查的命令
4. 不允许回退的用户改动

这样压缩后更容易继续，不会丢掉关键约束。

attach 与 server

OpenCode 可以把 TUI attach 到已经运行的后端 server。这对远程机器、局域网访问或 Web 界面很有用。

典型场景：

opencode web --port 4096 --hostname 0.0.0.0
opencode attach http://10.20.30.40:4096

只要绑定到 0.0.0.0 或开放给局域网，就要设置 server password。coding agent server 等于项目读写入口，不能当普通网页服务处理。