OpenCode TUI 完全使用教程

外观

附录 G · 反模式清单与多机同步（dotfiles） ​

第一部分把全书的「坏处 / 不这么做的问题」浓缩成一页速查；第二部分给出用 Git 管理 OpenCode 配置、跨机器同步的方案。

第一部分：反模式速查清单 ​

Prompt 与协作 ​

  • ❌ 一句话模糊指令（「帮我搞一下这个」）→ 结果随机返工。
  • ❌ 不给约束 / 不给验收标准 → AI 自行脑补方向。
  • ❌ 只在脑子里想清楚，却不复述目标 → 双方理解错位。
  • ❌ AI 一错就重复同一句话 → 不补证据、不改方式，必然再错。

TUI 操作 ​

  • ❌ 中途想改却只会干等或重开 → 应直接 Enter 引导（steer）或 Esc 中断。
  • ❌ 长 Prompt 按 Enter 才发现想换行 → 用 Shift+Enter / Ctrl+J 换行。
  • ❌ 任务做完不提交，只靠 undo → undo 只覆盖近期快照，不能替代 Git。

上下文与规则 ​

  • ❌ 把长期规则只留在对话里 → 压缩 / 换会话即丢，应写进 AGENTS.md。
  • ❌ 规则写得含糊、互相矛盾 → 加载了也难执行。
  • ❌ 把所有资料一次性塞进上下文 → 噪音淹没重点，应按需 @ 引用。
  • ❌ 写 CLAUDE.md 期待回退 → V2 只认 AGENTS.md。

Agent / 扩展 ​

  • ❌ 用 Shift+Tab 找 subagent → 只循环 primary，subagent 应被「派出」。
  • ❌ 不分任务难度，全程用同一个模型 → 浪费或力不从心。
  • ❌ 能用 Skill / Command 解决却硬写 Plugin → 过度工程。
  • ❌ 插件放根目录 plugins/ 却不配置 → 不被自动发现。
  • ❌ 插件不锁版本 → 上游突变。
  • ❌ 用 Policies 期待弹窗确认 → 它只二元 allow/deny，没有 ask。

交付与验证 ​

  • ❌ 只跑新增测试就宣布修好 → 应全量测试 + 构建 + 手动复现。
  • ❌ 不看 diff 直接接受 → 容易混入顺手重构与调试残留。
  • ❌ 偶发 bug 不复现就急着改 → 没有靶子，修复无法验证。
  • ❌ 任务结束不复盘、不沉淀 → 同样的弯路下次还走。

自动化 ​

  • ❌ CI 里硬开 TUI → 无 TTY 直接挂起，应用 opencode run。
  • ❌ 无人值守不加 --auto → 卡在 ask。
  • ❌ 解析人类可读输出而非 --format json → 格式一变脚本就崩。
  • ❌ CI 依赖交互登录 → 应环境变量注入凭证。

💡 把这一页当作「自检卡」：每次准备提交、或对结果不满意时，回来扫一遍，通常能立刻定位问题出在哪一环。

第二部分：多机同步（dotfiles 方案） ​

目标：把个人偏好、规则、自定义 Agent / Command / Skill 用 Git 管理，换机器一键拉取，而不是从头重配。

第 1 步：建立一个 dotfiles 仓库 ​

bash
mkdir -p ~/dotfiles && cd ~/dotfiles
git init

第 2 步：确定要同步什么、不同步什么 ​

建议同步：

  • AGENTS.md：全局规则；
  • opencode.jsonc：全局配置（先检查是否含敏感信息）；
  • 自定义的 agents/、commands/、skills/、plugins/；
  • cli.json：终端偏好 / 键位 / 主题。

不要提交：

  • 密钥、Token、凭证文件；
  • 缓存、日志、会话数据库等运行时数据。

用 .gitignore 明确排除，例如：

gitignore
# 凭证与运行时数据
**/credentials*
**/*.key
auth.json
cache/
log/

⚠️ 提交前务必逐个确认文件内没有 API Key / Token。若不确定，优先只同步明确安全的文件。凭证在新机器上通过登录或环境变量重新注入。

第 3 步：用软链把仓库接入配置目录 ​

一种常见做法是把文件放在 dotfiles 仓库，再软链到 ~/.config/opencode/：

bash
mkdir -p ~/.config/opencode
ln -sf ~/dotfiles/opencode/AGENTS.md       ~/.config/opencode/AGENTS.md
ln -sf ~/dotfiles/opencode/cli.json        ~/.config/opencode/cli.json
ln -sf ~/dotfiles/opencode/agents          ~/.config/opencode/agents
ln -sf ~/dotfiles/opencode/commands        ~/.config/opencode/commands
ln -sf ~/dotfiles/opencode/skills          ~/.config/opencode/skills

（目录可用软链整体接入，也可只链具体文件，按你的偏好选择。）

第 4 步：推送到远程仓库 ​

bash
git add -A
git commit -m "init opencode dotfiles"
git remote add origin <你的私有仓库地址>
git push -u origin main

建议使用私有仓库，即使已排除凭证也更稳妥。

第 5 步：在新机器上恢复 ​

bash
git clone <你的私有仓库地址> ~/dotfiles
# 然后重复第 3 步的软链命令；凭证重新登录或注入

小建议 ​

  • 可以把第 3、5 步的软链命令写成 install.sh 放进仓库，换机一键执行；
  • 项目级配置（项目里的 AGENTS.md、.opencode/）应跟随各项目仓库提交，团队共享；全局配置才走个人 dotfiles。两者分工不同，不要混淆。