Skip to main content

OpenCode 文件引用与 Shell 调用

· 4 min read

OpenCode 里两个最高频的快捷语法——@path 拉文件、!cmd 跑 shell。看着简单，踩坑的姿势不少。

  1. @ 引用文件：@src/components/Button.tsx 自动把文件读进上下文，比手动复制路径再让 OpenCode 读快得多。
  2. ! 调用 Shell：!ls -la src/ 在 OpenCode 里直接跑命令，输出回传到对话里。
  3. 大文件踩坑：引用 >500 行的文件会爆 token，先 head / Grep -n 截取 再 @。
  4. 高频用法：!pnpm test 看测试输出、!git status 看状态、!ps aux | grep node 查进程。
  5. 核心区别：@ 是"读进来作为上下文"，! 是"执行命令拿到结果"——前者进了历史，后者也是。

OpenCode 里有两个最高频的快捷语法：@path 拉文件、!cmd 跑 shell。看着简单，但用错的姿势不少。这篇把这两块讲透。

@ 引用文件​

@src/components/Button.tsx 这个组件的样式有点问题，帮我看看

OpenCode 会自动把 Button.tsx 读进上下文。比手动复制粘贴路径再让 OpenCode 读文件快得多——尤其在长对话里，路径记不住的时候特别好用。

也支持模糊匹配：

@Button.tsx        # 当前目录下查找
@components/Button # 按目录前缀
@src:Button        # 在 src 目录下找包含 Button 的文件

具体匹配规则看 OpenCode Files 文档，版本之间略有差异。

大文件踩坑​

致命问题：引用大文件会爆 token。

文件大小和 token 数大致换算：

  • 1 行代码 ≈ 10-20 tokens（看语言和复杂度）
  • 500 行 ≈ 5k-10k tokens
  • 1000 行 ≈ 10k-20k tokens

>500 行的文件不建议直接 @——一次引用吃掉 10%+ 的上下文。建议先用 head / Grep -n 截取相关部分：

# 先看文件结构
!head -50 src/components/Button.tsx

# 再用 Grep 找具体行
!grep -n "useEffect" src/components/Button.tsx

# 然后再 @ 整个文件（如果需要）
@src/components/Button.tsx

! 调用 Shell​

!ls -la src/

直接在 OpenCode 里跑 shell 命令，输出会回传到对话里——相当于让模型帮你执行并收集结果。

我经常用 ! 来：

  • 跑测试看输出：!pnpm test
  • 查 git 状态：!git status
  • 查进程：!ps aux | grep node
  • 看磁盘：!df -h
  • 看日志：!tail -100 /var/log/app.log

比让 OpenCode 帮你跑命令再解析输出更直接，反馈也快——尤其是带 grep / pipe 的命令，直接跑比让 AI 翻译再跑快 5 倍。

! 和 Bash 工具的区别​

OpenCode 内部有 Bash 工具（sub-agent 派出去执行），! 是用户直接在主对话里执行：

  • !cmd → 主对话上下文，执行结果进对话历史
  • Bash 工具（sub-agent 调）→ child session 上下文，不进主对话

简单规则：主对话里想自己看一眼结果用 !，让 sub-agent 去执行用 Bash 工具。

长命令和交互式命令的注意​

# 长命令可以多行（用反引号包起来或转义）
!pnpm install && pnpm build && pnpm test

# 交互式命令不能用（vim / less / top 等需要 TTY 的）
!vim README.md   # ❌ 会失败

# 用 nohup / & 跑后台任务
!nohup pnpm dev &

! 拿不到 TTY，所以 vim、less、top、ssh 这种交互式命令会失败。跑后台服务记得 nohup ... &。

组合用法​

最佳实践：高频组合拳

  1. 改 Bug 流程：!git status 看当前改了什么 → 直接描述问题 → 改完用 /undo 兜底
  2. 读大文件：先 !head -50 file 看结构 → 再 @file 整文件读
  3. 跑测试：!pnpm test 2>&1 | tail -50 拿到最后 50 行结果，避免输出刷屏
  4. 查进程 / 日志：!ps aux | grep node / !tail -100 log

References​

  1. OpenCode 官方文档 —— @ / ! 语法完整说明
  2. OpenCode Files 文档 —— @ 路径匹配规则