oc/skills/opencode-config/references/01-agents.md

01 — Agents (代理)

源: https://opencode.ai/docs/zh-cn/agents/ 适用: 创建/修改 opencode 子代理 (.opencode/agent/*.md) 或 opencode.json 的 agent 段

类型

• 主代理 (primary): 用户直接交互,Tab 切换;默认 Build (全工具) + Plan (只读/ask)
• 子代理 (subagent): 主代理自动调用,或用户 @ 提及

内置代理清单

名称	模式	用途	工具
build	primary	默认开发	全开
plan	primary	规划/分析 (不写)	edit/bash = ask
general	subagent	通用多步任务	几乎全开 (无 todowrite)
explore	subagent	代码库搜索	只读
scout	subagent	外部库/upstream 对比	只读 + 克隆到缓存
compaction / title / summary	primary (隐藏)	系统内部	—

自定义代理可覆盖内置:agent: { build: { ... } } 或 agent/build.md。

两种配置形式

JSON 形式 (opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "review": {
      "description": "Reviews code for best practices",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-6",
      "tools": { "write": false, "edit": false, "bash": false },
      "prompt": "{file:./prompts/review.txt}"
    }
  }
}

Markdown 形式 (推荐,本仓库使用) — .opencode/agent/<name>.md 或 .opencode/agents/<name>.md:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-6
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

文件名即代理名: review.md → review。prompt 写在 frontmatter 还是 body 选一个,别两处都写。

Frontmatter 全字段

字段	必填	类型	说明
name	是 (内联必填,文件可选)	string	代理名
description	是	string	必需,决定自动调用时机
mode	否	primary | subagent | all	默认 all
model	否	provider/model-id	子代理默认继承主代理模型
prompt	否	string / {file:...}	系统提示词;路径相对配置文件所在目录
temperature	否	0.0-1.0	0=确定, 0.55=Qwen 默认, 0.7=创意
top_p	否	0.0-1.0	温度的替代
steps	否	int	最大迭代步数 (旧 maxSteps 弃用)
tools	否	object	{ "<name>": bool } 或 glob "mymcp_*": false
permission	否	object	覆盖全局权限 (见 02-skills / 05-tools)
mode	否	string	—
hidden	否	bool	true 时从 @ 补全菜单隐藏 (仅 subagent)
color	否	#RRGGBB | 主题色	UI 颜色: primary/secondary/accent/success/warning/error/info
disable	否	bool	true 禁用
steps	否	int	—
options	否	object	其他键进 options,透传到模型 (如 reasoningEffort: "high")
variant	否	string	—

未知 top-level 字段 → 静默进 options (透传模型)。不是抛错。

权限 (重点)

支持值: "allow" / "ask" / "deny"。

Glob 规则 — 最后匹配优先:

permission:
  bash:
    "*": ask              # 兜底
    "git status *": allow # 放行具体

permission.task 控制子代理能调谁:

permission:
  task:
    "*": deny
    "orchestrator-*": allow
    "code-reviewer": ask

deny 时,该子代理从 Task 工具描述中完全移除,模型看不到它。用户仍能用 @ 直接调。

创建代理的官方命令

opencode agent create   # 交互式: 位置/描述/工具/生成

实战示例 (照搬官方)

文档代理 (~/.config/opencode/agents/docs-writer.md):

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
You are a technical writer. Create clear, comprehensive documentation.

安全审计代理 (~/.config/opencode/agents/security-auditor.md):

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---
You are a security expert. Focus on:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

本仓库现状

• .opencode/agents/dba.md — 已存在的 DBA 子代理 (本项目自定义)
• ~/.config/opencode/agent/* — 全局子代理位置

验证清单 (改完跑一遍)

1. frontmatter description 非空,mode 正确。
2. 工具权限: 不需要的都 false,尤其 bash / edit / write。
3. 全局权限 vs 代理权限: 子代理用 permission: 块覆盖。
4. 退出并重启 opencode。
5. 在 UI 用 @<agent-name> 试调,或主代理根据 description 自动触发。