| name | opencode |
| description | Delegate coding to the OpenCode CLI (implement features, fix bugs, refactor, write tests, review PRs) by driving `opencode run` non-interactively through the bash tool. Use whenever a bounded, self-contained engineering task — or a read-only PR / code review — can be handed off end-to-end to an autonomous coding agent, especially larger multi-file changes or when you want a second agent to do the coding while you orchestrate. Covers install/auth, the `run` flag set (model, agent, format, session/continue/fork, auto, dir), the permission (allow/ask/deny) safety model, PR review via `opencode pr` and a read-only review agent, resuming a session, and troubleshooting. |
| category | autonomous-ai-agents |
OpenCode CLI 委派编码（opencode run）
用本 skill 把一段有边界、能独立完成的编码任务（加功能、修 bug、重构、写测试）
或一次只读的 PR / 代码审查整段交给 OpenCode CLI 跑完再拿回结果。OpenCode 是
SST 开源的 AI coding agent（终端 / 桌面 app / IDE 扩展，同 Claude Code、Codex 一类），
所有操作都通过 bash 工具跑 opencode run（非交互模式）——本 skill 不封装 Python
tool，就是一套调用配方。
Reply in Chinese unless the user clearly uses another language.
何时使用
- 任务是自包含的工程活：实现一个功能、修一个 bug、重构一个模块、补测试，
且你能把「做什么、改哪些文件、怎么验证」讲清楚。
- 要做代码审查 / PR review：让 OpenCode 拉一个 GitHub PR 分支、分析改动、
给出意见，且不落任何编辑（用只读权限的审查 agent，见下）。
- 你想让另一个自主编码 agent 去干活、自己专注编排；或改动跨多文件、体量偏大，
适合整段委派而不是逐行自己写。
不用本 skill：
- 小改动 / 你自己能直接改 → 用
read / write / edit。
- 只是跑命令、看输出 → 用
bash / powershell。
- 想委派给 OpenAI Codex → 用
codex skill；委派给 Anthropic Claude Code → 用 claude_code tool。
安全模型（最高优先级）
opencode run 是非交互的：它跑到底、不会停下来当面问你要不要批准某个操作。因此
「它能碰什么」由 permission 配置（每条规则解析成 allow / ask / deny）加上
命令行的 --auto 共同决定，务必按任务最小授权：
--auto：自动批准所有没被显式 deny 的权限请求。非交互脚本里几乎必须带它，
否则遇到 ask 的操作会卡住等不到人批。它只影响本会「否则要问」的请求，
显式 deny 规则始终生效——所以真正的护栏是 permission 里的 deny。- permission 三态（配在
opencode.json 或 agent frontmatter）：
edit（改文件：edit/write/patch）、bash（跑 shell）、webfetch（抓 URL）
各自可设 allow / ask / deny；"*" 设全局默认。规则最后匹配的胜出，
常把 catch-all "*" 放最前、具体规则放后。
- 只读审查：审查/分析不许改动时，用
edit: deny（配合 bash: ask、webfetch: deny），
或直接跑一个 mode: subagent 的只读 review agent（见「PR / 代码审查」）。
其它安全约定：
- 凭据是 CLI 自己的事，跟
gh 一样：OpenCode 把 provider key 存在
~/.local/share/opencode/auth.json（opencode auth login 管）。本 skill
不打印、不写入、不提交任何 token。
- 委派 ≠ 免检：OpenCode 跑完后先
git diff 复查它产生的改动再决定是否提交/推送，
别盲目信任。开 PR / 推分支这类外发操作，按仓库规矩确认后再让它做。
- 破坏性 / 大范围操作（删文件、force-push、改生产配置）不要直接丢给一个
edit: allow
的 agent 无人值守跑——先让它在只读或受限权限下产出方案 / diff，你复查后再动手。
Setup（首次或报错时）
OpenCode 是外部 CLI，不是 pip 包。缺失时 bash 会报 opencode: command not found——
照实转达用户，别假装成功。安装 + 认证是用户级操作，agent 只引导：
opencode --version 2>&1 || echo "opencode 未安装"
curl -fsSL https://opencode.ai/install | bash
opencode auth login
opencode run --help 2>&1 | head -40
Windows 官方建议在 WSL 里跑体验最好；原生装可用 npm / scoop / choco。
bash 工具调用 CLI 走 shell，能正常找到 shim。
核心工作流
-
想清楚再委派：把任务写成一段明确的 prompt——目标、要改哪些文件、约束、怎么验证
（跑哪个测试 / build）。边界越清楚，OpenCode 一趟跑完的成功率越高。
-
在仓库根跑 opencode run，非交互务必带 --auto，用 permission 卡住不该做的事：
opencode run --dir /path/to/repo --auto --format json \
"在 src/api.py 加一个 GET /health 端点返回 {status:'ok'}，并在 tests/test_api.py 补一个测试，最后跑 pytest 确认通过" \
</dev/null
不加 --format json 则输出人类可读的格式化文本；json 是原始 JSON 事件流，
脚本里更好解析最终结果。
-
复查再落地：git -C /path/to/repo diff 看它改了什么，满意再 commit（或让它开 PR）。
-
指定模型 / agent：-m provider/model 选模型（opencode models 列可用的），
--agent <name> 选 agent（如内置 build 或你定义的 review agent）。
PR / 代码审查（只读）
两条路子：
A. 拉现成的 GitHub PR 再审——opencode pr <number> 会 checkout 该 PR 分支并跑 OpenCode：
opencode pr 123 --agent review --auto --format json \
"审查这个 PR：找出 bug、安全问题、缺失的测试，按文件给出具体行级意见，不要改任何代码" \
</dev/null
B. 审当前工作区 / 某段 diff——直接 opencode run 配只读 agent：
opencode run --dir /path/to/repo --agent review --auto \
"审查 HEAD~1..HEAD 的改动，指出问题与改进点，不要编辑文件" </dev/null
只读 review agent 用一个 markdown agent 定义（放 ~/.config/opencode/agent/review.md
或项目内 .opencode/agent/review.md）：
---
description: Code review without edits
mode: subagent
permission:
edit: deny
bash: ask
webfetch: deny
---
只分析代码、指出问题并给出修改建议，绝不修改任何文件。
edit: deny 是硬护栏——即便带了 --auto 也不会被放开（--auto 只放开「本会问」的，
不碰显式 deny）。也可临时用 opencode agent create 非交互建一个受限 agent。
Flag 速查（opencode run [message..]）
Prompt 作为 message 位置参数传入。
| Flag | 作用 |
|---|
--dir <dir> | 运行目录（一般是仓库根）。 |
--auto | 自动批准非 deny 的权限请求（非交互脚本几乎必带）。 |
-m, --model <provider/model> | 选模型（opencode models 列可用）。 |
--agent <name> | 选 agent（如 build / 自定义 review）。 |
--format <default|json> | default=格式化文本，json=原始事件流（脚本用）。 |
-c, --continue | 续最近一次 session。 |
-s, --session <id> | 按 session id 续。 |
--fork | 续 session 时 fork 一份（配合 -c / -s）。 |
-f, --file <path> | 附带文件（可重复）。 |
--title <t> | 设 session 标题。 |
--share | 分享该 session（生成分享链接，注意别泄私有代码）。 |
--thinking | 显示思考块。 |
--attach <url> | 附到已跑的 opencode serve 实例，省 MCP 冷启动。 |
相关子命令：opencode models [provider]（列模型）、opencode agent list、
opencode session list、opencode auth login/list/logout、opencode serve（无头 HTTP 服务）。
迭代同一个任务（resume）
OpenCode 的续跑是 run 的 flag（不像 codex 是子命令）：
opencode run -c --auto "继续把边界情况的单测补上" </dev/null
opencode run -s <session-id> --auto "改用参数化测试重写" </dev/null
opencode run -c --fork --auto "在不改动原会话的前提下试另一种实现" </dev/null
opencode session list --format json 可查历史 session id。续跑继承原 session 上下文，
别再重复贴一遍背景。
版本差异与排错
OpenCode CLI 迭代快，flag 名 / 子命令可能随版本变。动手前用 opencode run --help 核对
当前版本，别照记忆硬套。
| 症状 | 原因 / 处理 |
|---|
opencode: command not found | 未安装 → 走 Setup，引导用户装（curl 脚本 / npm / brew）。 |
| 认证失败 / 没有可用模型 | 未配 provider → opencode auth login；opencode auth list 查状态、opencode models 看有没有模型。本 skill 不代管凭据。 |
| 命令挂着不动、等输入 | 通过 bash 管道调用时 stdin 非 tty 会等 → 命令末尾加 </dev/null。 |
| 一直卡在「等待批准」 | 非交互没带 --auto → 加 --auto（但真正该拦的用 permission deny）。 |
| 改动没落盘 / 说没权限写 | permission 里 edit 被 deny（或审查 agent） → 换 build agent 或把 edit 放开。 |
| 联网 / webfetch 被拒 | webfetch: deny → 需要时在 config / agent 里放开。 |
| 想省 MCP 冷启动 | 先 opencode serve，再 opencode run --attach http://localhost:PORT ...。 |
与 codex / claude_code 的区别
三者都是「委派编码给外部 CLI」，选型看你要哪个：opencode=SST OpenCode（本 skill，
opencode run，权限靠 permission allow/ask/deny + --auto，且原生有 opencode pr 做 PR review），
codex=OpenAI Codex（skill，codex exec，权限靠 sandbox），
claude_code=Anthropic Claude Code（tool，claude -p，权限靠 permission-mode）。
功能定位一致，都归 autonomous-ai-agents。
