4. 自定义 agent 与命令

这是什么：agent（智能体） = 一个有专属提示词、专属模型、专属权限的 AI 助手；AGENTS.md = 放在项目里、每次会话自动加载的「项目说明书」。

为什么用：默认的 opencode 只有一个模子：什么都能干，也什么都不熟。你要的是一个「只读不改的评审员」和一个「专门跑测试的」——不自定义，就只能每次在提示词里重复交代。

如何用：本章先写 AGENTS.md，再手写一个评审 agent 并给它划权限边界，最后做一个 /review 斜杠命令。

4.1 AGENTS.md：把项目规矩写下来

位置	作用范围
项目根目录 `AGENTS.md`	只对这个项目（及其子目录）生效，建议提交 Git
`~/.config/opencode/AGENTS.md`	你个人的全局规矩，所有项目通用
`~/.claude/CLAUDE.md`	兼容层：项目级和全局的 `AGENTS.md` 都没有时才读它

同一类里先找到的先生效：AGENTS.md 存在就不会再读 CLAUDE.md。

# 项目说明

## 技术栈
Python 3.12 + FastAPI + SQLAlchemy，包管理用 uv。

## 常用命令
- 装依赖：uv sync
- 跑测试：uv run pytest -q
- 起服务：uv run uvicorn app.main:app --reload

## 代码约定
- 所有对外接口返回 Pydantic 模型，不直接返回 dict
- 数据库迁移必须手写 SQL，不许用 ORM 自动生成

/init 能自动生成初版，但生成完一定要自己改：它只知道文件名，不知道你们组的规矩。

还可以在 opencode.json 里用 instructions 挂更多说明文件：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", "packages/*/AGENTS.md"]
}

4.2 两类 agent

类型	谁能调用	内置的	切换方式
primary（主 agent）	你	`build`、`plan`	按 `Tab` 循环切换
subagent（子 agent）	你，或别的 agent 通过 Task 工具调用	`general`、`explore`、`scout`	在消息里 `@名字`

explore 是只读探索员（找文件、搜代码），scout 查外部文档和依赖源码，general 是全能打杂的。默认不允许子 agent 再套子 agent，用 subagent_depth 调。

4.3 手写一个自己的 agent

放一个 Markdown 文件，文件名就是 agent 名字。放 .opencode/agents/review.md（项目级）或 ~/.config/opencode/agents/review.md（全局）。

---
description: 只读地审查代码，挑出 bug、安全问题和风格问题
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
permission:
  edit: deny
  shell:
    "*": deny
    "git diff*": allow
    "grep*": allow
---

你在做代码评审。只输出问题清单，不直接修改任何文件。

重点看：
- 潜在的空指针 / 越界 / 并发问题
- 输入校验缺失
- 依赖调用的错误处理

每条结论都要给出文件路径和行号。

写好后，在消息里 @review 就能叫它。也可以用命令造一个：

opencode agent create    # 交互式：问你要保存到哪、干什么、给哪些权限
opencode agent list      # 列出所有 agent

你会看到（示意）：

  build      primary   默认的开发 agent，全工具
  plan       primary   只规划不改代码
  review     subagent  只读地审查代码
  explore    subagent  只读探索代码库

4.4 给 agent 划权限边界

权限键	管住什么	可选值
`read` / `list` / `glob` / `grep`	读文件、列目录、搜文件	`allow` / `ask` / `deny`
`edit`	写文件、改文件、打补丁	同上
`shell`	执行命令	同上，还能按命令名配
`task`	调用别的子 agent	同上，支持通配
`webfetch` / `websearch`	联网	同上
`external_directory`	读写项目目录之外的文件	同上

两条规则要记牢：

agent 里的 tools 字段已废弃，新配置一律用 permission。
shell 可以按命令粒度配，最后一条命中的规则说了算，所以把 * 放最前面兜底：

{
  "agent": {
    "build": {
      "permission": {
        "shell": {
          "*": "ask",
          "git status *": "allow",
          "npm test": "allow"
        }
      }
    }
  }
}

你会看到（示意）：

$ opencode debug config
{
  "agent": {
    "build": {
      "permission": { "shell": { "*": "ask", "git status *": "allow", "npm test": "allow" } }
    }
  }
}

4.5 自定义斜杠命令

命令就是「存好的提示词」。新建 .opencode/commands/review.md：

---
description: 审查当前改动
agent: review
---

审查本次改动，!`git diff --stat` 先给我一个改动清单，然后逐条挑问题。

在 TUI 里敲 /review 就能触发。正文里可以用三种占位：

写法	作用
`$ARGUMENTS`	整段参数；也可以用 `$1`、`$2` 取第几个
!`命令`	把 shell 命令的输出插进提示词
`@文件名`	把文件内容插进提示词

/review 重点看 src/auth 目录

想让命令别污染当前主对话、单独开个子会话？加 subtask: true（或者 agent 指向一个 mode: subagent 的 agent）。

自定义命令可以覆盖内置命令，同名即覆盖。JSON 写法等价物是 opencode.json 里的 command 字段（template / description / agent / model / subtask）。

动手改

给你的项目写一份 AGENTS.md，至少包含「怎么装依赖、怎么跑测试、代码风格三条」，提交进 Git。
用 opencode agent create 造一个 tester agent：只允许跑测试命令，不许改文件，然后用 @tester 叫它跑一遍测试。
做一个 /changelog 命令：用 shell 输出占位符把 git log --oneline -10 的输出插进提示词，让它按「新增 / 修复 / 破坏性变更」三段总结最近 10 条提交。

小结

AGENTS.md 放项目根目录，/init 生成初版，记得手动改 + 提交 Git
agent 分 primary（Tab 切换）和 subagent（@名字 调用），内置 build / plan / general / explore / scout
权限用 permission 字段（tools 已废弃），shell 支持按命令配，最后命中者胜
自定义命令就是模板文件：三种占位——参数用 $ARGUMENTS、shell 输出用「反引号里写 ! 加命令」、文件用 @ 加路径

下一章：MCP 与扩展 🐸