子智能体、斜杠命令、MCP 与 CI 自动化

这一课做完你会得到什么

还是在 hello-opencode 仓库里，你会给 OpenCode 加上四样能力：

• 一个只读的代码审查子智能体。
• 一个 /test 自定义命令。
• 一个 MCP 服务器。
• 一条能放进脚本或 CI 的 JSON 输出命令。

最后附一张 V1 配置迁移对照表。

先认识内置智能体

「主」智能体直接和你对话。「子」智能体由主智能体派出去，在独立的子会话里干活，干完把结果交回来。想先让它出方案、确认后再动手，就用 plan：

opencode run --agent plan "给 stats.py 加方差函数，先给方案不要改文件"

第 1 步：写一个只读审查子智能体

新建 .opencode/agents/reviewer.md。文件名 reviewer 就是智能体 ID，正文会成为它的系统提示词：

---
description: 只读代码审查，按严重程度列出问题
mode: subagent
permissions:
  - action: edit
    resource: "*"
    effect: deny
---
审查当前改动。按严重程度列出问题，每条带文件名和行号；不要修改任何文件。

description 一定要写清楚，主智能体靠它决定什么时候派这个子智能体。然后故意写一个有 bug 的函数，最后一行把 - 1 写在了括号外面：

cat >> stats.py <<'PY'


def variance(numbers):
    m = mean(numbers)
    return sum((x - m) ** 2 for x in numbers) / len(numbers) - 1
PY
opencode run "用 reviewer 子智能体审查我当前未提交的改动，把它的结论原样转述。"

对照结果（2026-10-26 实测，约 43 秒，节选）：

**核心公式有实质性错误，会输出负方差；同时缺少 docstring 和任何测试**
……建议先修正 `stats.py:34` 的公式、补中文 docstring 和空列表校验，再补上
`variance` 的测试并实际运行 `uv run --with pytest pytest -q`

它不仅找出了 bug，还引用了 AGENTS.md 里「中文 docstring」「跑测试」的规矩。审查过程中它没有改动任何文件，git diff 里只有你刚追加的那几行。审完把练习用的 bug 撤掉：

git checkout stats.py

第 2 步：写一个 /test 命令

在 .opencode/commands/ 下每放一个 .md 文件，就多一个斜杠命令，正文就是提示词模板。新建 .opencode/commands/test.md：

---
description: 跑测试并总结
---
运行 `uv run --with pytest pytest -q`，用一句话总结结果。$ARGUMENTS

模板里能用三类变量：

• $ARGUMENTS：命令后面跟的全部文字，原样替换。
• $1、$2：按位置取参数，带空格的参数用引号括起来。
• !`命令`：先在本地执行这条 shell 命令，再把输出插进提示词。例如 !`git diff`。

官方特别提醒：!`…` 里的命令不经过权限系统，所以只用你信得过的命令，也不要把不可信的参数塞进去。

在全屏界面里输入 /test 即可调用。opencode run 也认斜杠命令：

opencode run "/test"

对照结果（2026-10-26 实测，节选）：

已按项目要求运行测试：
uv run --with pytest pytest -q
结果：**11 passed**（耗时 0.01s），全部通过。

命令文件改了不用重启，OpenCode 会自动重新加载。

第 3 步：接一个 MCP 服务器

MCP 服务器能给智能体加上新工具。用命令行添加官方的演示服务器 server-everything（需要本机有 Node.js）：

opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything

对照结果（2026-10-26 实测）：

MCP server "everything" added to …/hello-opencode/opencode.jsonc

它写进项目配置的内容如下。V2 的服务器统一放在 mcp.servers 下：

"mcp": {
  "servers": {
    "everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

查看连接状态：

opencode mcp list

对照结果（2026-10-26 实测）：

✓ everything  connected

本机实测时，刚添加完马上 list，显示的是 No MCP servers configured，等了十几秒再查才变成 connected。原因是后台服务要先重新加载配置。

几个常用写法：

• 远程服务器：opencode mcp add 名字 --url https://…/mcp，默认走 OAuth 登录。
• 需要登录时：在全屏界面里运行 /mcps 完成授权，或运行 opencode mcp auth 名字。
• 暂时停用：给服务器加 "disabled": true。注意不是 V1 的 enabled。
• Key：用 "{env:变量名}" 引用环境变量，别直接写进配置文件。

MCP 工具会占用模型的上下文，只接真正需要的服务器。本机实测时，接好服务器后让模型调用它的加法工具，那一步因免费额度用完没有跑成，所以这里不给模型调用 MCP 的输出。

第 4 步：在脚本和 CI 里用 JSON 输出

加上 --format json，opencode run 会把每个事件按「一行一个 JSON」的格式输出，方便脚本解析：

opencode run --format json "stats.py 里一共定义了几个函数？只回答数字。" \
  > run.jsonl

对照结果（2026-10-26 实测，当时免费额度已用完，正好拿到一个错误事件，字段有删减）：

{"type":"step_start","sessionID":"ses_e8c240e4…","part":{"type":"step-start"}}
{"type":"error","error":{"type":"provider.free-limit","status":429,
 "retryAfterMs":27644000}}

在脚本里判断有没有出错，可以这样写：

if grep -q '"type":"error"' run.jsonl; then
  echo "OpenCode 运行失败"; exit 1
fi

放进 CI 前先想清楚三件事：

• 权限：CI 里没人能点确认。要么在配置里把需要的命令明确 allow，要么加 --auto。危险命令一律 deny。
• 模型：免费模型有额度上限，CI 应该接自己的提供方，Key 放进 CI 的密钥变量。
• 隔离：想不和本机的共享后台服务混在一起，加 --standalone，用一个独立的私有服务。

第 5 步：从 V1 迁移

V1 的配置在 V2 里大多能直接用。V2 会在内存里转换，不改你的原文件。官方建议的迁移顺序：

• 先保留原配置，启动 V2，核对模型、凭据、智能体、权限和 MCP 是否正常。
• 必须重写的只有插件和调用服务端 API 的集成，这两块是不兼容的。
• 想换成 V2 原生格式时，可以直接让 OpenCode 帮你改。

常见字段对照：

还有两处默认行为变了：

• 项目外的目录：V2 默认放行，V1 默认会先问。想要旧行为，见第 2 课的 external_directory 规则。
• 待办清单（todo）：V2 默认关闭，要用 experimental.todo 打开。

本课小结

• 子智能体：在 .opencode/agents/<名字>.md 里写好 description 和 permissions，就能派它干只读审查这类活。
• 斜杠命令：在 .opencode/commands/<名字>.md 里写模板，支持 $ARGUMENTS、$1 和 !`命令`。
• MCP：opencode mcp add 添加，opencode mcp list 检查状态，配置在 mcp.servers 下。
• 自动化：opencode run --format json 加上明确的权限规则，就能放进脚本和 CI。