OpenCode 编码代理
委派编码任务给 OpenCode CLI（功能开发、PR 审查）
OpenCode CLI
将 OpenCode 作为自主编码工作者使用，由 Hermes 的终端/进程工具编排调度。OpenCode 是一个与提供商无关的开源 AI 编码代理，同时提供 TUI 和 CLI。
使用场景
用户明确要求使用 OpenCode
你希望由外部编码代理来实现/重构/审查代码
你需要可周期性检查进度的长时间编码会话
你希望在隔离的工作目录/worktree 中并行执行任务
前置条件
已安装 OpenCode：npm i -g opencode-ai@latest 或 brew install anomalyco/tap/opencode
已完成认证配置：opencode auth login 或设置提供商环境变量（OPENROUTER_API_KEY 等）
验证：opencode auth list 应至少显示一个提供商
用于代码任务的 git 仓库（推荐）
交互式 TUI 会话需要 pty=true
二进制文件解析（重要）
不同的 Shell 环境可能解析到不同的 OpenCode 二进制文件。如果终端与 Hermes 中的行为不一致，请检查：
terminal(command="which -a opencode")
terminal(command="opencode --version")
如有需要，可固定显式的二进制路径：
terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)
一次性任务
对于有边界、非交互式的任务，使用 opencode run：
terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")
使用 -f 附加上下文文件：
terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")
使用 --thinking 显示模型思考过程：
terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")
强制指定模型：
terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")
交互式会话（后台）
对于需要多轮往来的迭代式工作，可在后台启动 TUI：
terminal(command="opencode", workdir="~/project", background=true, pty=true)
# Returns session_id
# Send a prompt
process(action="submit", session_id="", data="Implement OAuth refresh flow and add tests")
# Monitor progress
process(action="poll", session_id="")
process(action="log", session_id="")
# Send follow-up input
process(action="submit", session_id="", data="Now add error handling for token expiry")
# Exit cleanly — Ctrl+C
process(action="write", session_id="", data="x03")
# Or just kill the process
process(action="kill", session_id="")
重要：不要使用 /exit——它不是有效的 OpenCode 命令，反而会打开代理选择对话框。应使用 Ctrl+C（x03）或 process(action="kill") 退出。
TUI 快捷键
| 键 | 操作 |
| `Enter` | 提交消息（必要时按两次） |
| `Tab` | 在代理之间切换（build/plan） |
| `Ctrl+P` | 打开命令面板 |
| `Ctrl+X L` | 切换会话 |
| `Ctrl+X M` | 切换模型 |
| `Ctrl+X N` | 新建会话 |
| `Ctrl+X E` | 打开编辑器 |
| `Ctrl+C` | 退出 OpenCode |
恢复会话
退出后，OpenCode 会输出一个会话 ID。可使用以下方式恢复：
terminal(command="opencode -c", workdir="~/project", background=true, pty=true) # Continue last session
terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true) # Specific session
常用标志
| 标志 | 用途 |
| `run 'prompt'` | 一次性执行并退出 |
| `--continue` / `-c` | 继续上一次 OpenCode 会话 |
| `--session ` / `-s` | 继续指定会话 |
| `--agent ` | 选择 OpenCode 代理（build 或 plan） |
| `--model provider/model` | 强制指定模型 |
| `--format json` | 机器可读的输出/事件 |
| `--file ` / `-f` | 为消息附加文件 |
| `--thinking` | 显示模型思考块 |
| `--variant ` | 推理力度（high、max、minimal） |
| `--title ` | 为会话命名 |
| `--attach ` | 连接到正在运行的 opencode 服务器 |
操作流程
验证工具是否就绪：
terminal(command="opencode --version")
terminal(command="opencode auth list")
对于有边界的任务，使用 opencode run '...'（无需 pty）。
对于迭代式任务，以 background=true, pty=true 启动 opencode。
使用 process(action="poll"|"log") 监控长任务。
如果 OpenCode 请求输入，通过 process(action="submit", ...) 响应。
使用 process(action="write", data="x03") 或 process(action="kill") 退出。
向用户总结文件变更、测试结果和后续步骤。
PR 审查工作流
OpenCode 内置了 PR 命令：
terminal(command="opencode pr 42", workdir="~/project", pty=true)
也可以在临时克隆中进行审查以实现隔离：
terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr 'n' ' ')", pty=true)
并行工作模式
使用独立的工作目录/worktree 以避免冲突：
terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
process(action="list")
会话与成本管理
列出历史会话：
terminal(command="opencode session list")
查看 token 用量与成本：
terminal(command="opencode stats")
terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")
注意事项
交互式 opencode（TUI）会话需要 pty=true。opencode run 命令则不需要 pty。
/exit 不是有效命令——它会打开代理选择器。退出 TUI 请使用 Ctrl+C。
PATH 不一致可能导致选错 OpenCode 二进制文件/模型配置。
如果 OpenCode 看似卡住，先查看日志再终止进程：
process(action="log", session_id="")
避免多个并行的 OpenCode 会话共享同一个工作目录。
在 TUI 中提交消息可能需要按两次 Enter（一次确认文本，一次发送）。
验证
冒烟测试：
terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")
成功标准：
输出包含 OPENCODE_SMOKE_OK
命令退出时没有提供商/模型错误
对于代码任务：预期文件已变更且测试通过
规则
一次性自动化优先使用 opencode run——更简单，且不需要 pty。
仅在需要迭代时才使用交互式后台模式。
始终将 OpenCode 会话限定在单一仓库/工作目录内。
对于长任务，根据 process 日志提供进度更新。
报告具体结果（变更的文件、测试、遗留风险）。
退出交互式会话使用 Ctrl+C 或 kill，绝不使用 /exit。
