# 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`):

```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`:

```markdown
---
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 规则 — 最后匹配优先**:

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

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

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

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

## 创建代理的官方命令

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

## 实战示例 (照搬官方)

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

```markdown
---
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`):

```markdown
---
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 自动触发。