opencode-sync
164 lines
5.0 KiB
Markdown
164 lines
5.0 KiB
Markdown
# 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 自动触发。
|