你让 Verboo Code 审查一个 PR，结果在讨论功能的对话中途，编程代理读了 40 个文件，把上下文塞满了。子代理可以解决这个问题：它在独立的上下文中执行任务，只使用你允许的工具，遵循你写的指令，最后只把结果交回主对话。本教程带你从编写文件到实际使用，创建一个子代理。
Verboo Code 中的子代理是什么？
它是主会话通过 Agent 工具调用的专用代理。每个子代理都是一个 Markdown 文件：frontmatter 定义名称、何时使用以及可用的工具；文件正文就是它的系统提示词。
Verboo Code 自带几个内置子代理，例如 general-purpose 和 statusline-setup。你创建的子代理会出现在同一个列表中。
如何用 /agents 创建子代理？
在会话中输入：
/agents这会打开代理菜单，列出内置代理和你自己的代理。创建新代理时，向导会依次询问：
- 保存位置：
Project (.verboo/agents/)会进入代码仓库；Personal (~/.verboo/agents)对你的所有项目生效。 - 创建方式：根据你的描述自动生成（标记为 recommended 的选项），或选择
Manual configuration。 - 接着设置：工具、模型、颜色和记忆。
完成后，/agents 会在所选文件夹中写入一个 .md 文件。你也可以手动编写这个文件，下一节就来演示。
如何手动编写子代理文件？
mkdir -p .verboo/agents然后创建 .verboo/agents/revisor.md，一个只读不改的审查代理：
---
name: revisor
description: Reviews the current diff looking for bugs, missing tests and broken contracts. Use proactively after any change in src/.
tools: Read, Grep, Glob, Bash
model: inherit
---
你是一名资深代码审查员。不要编辑任何文件。
1. 运行 git diff 查看改动。
2. 对每个改动的文件，检查：逻辑错误、未测试的边界情况、公共签名的变更。
3. 用简短的列表回复，按严重程度从高到低排列，注明文件和行号。
4. 如果没有发现问题，用一行说明即可。再次运行 /agents，列表中就会出现 revisor。如果你是在会话打开时创建的文件，而它没有出现，请开启一个新会话。
陷阱：frontmatter 中没有 name 的文件会被静默忽略。Verboo Code 会把它当作文件夹里的普通文档，不会给出任何提示。有 name 但没有 description 时，文件解析失败，子代理同样不会加载。这两个字段都是必填的。
frontmatter 支持哪些字段？
| 字段 | 作用 | 不填写时 |
|---|---|---|
name | 子代理的标识符 | 文件被忽略 |
description | 何时使用。主代理据此决定是否委派 | 报错，不加载 |
tools | 逗号分隔的列表，例如 Read, Grep, Glob, Bash | 会话中的全部工具 |
disallowedTools | 即使列表允许也要禁用的工具 | 不禁用任何工具 |
model | inherit 或菜单中的别名（sonnet、opus、haiku） | inherit：与对话使用同一模型 |
effort | 子代理的推理级别 | 会话默认值 |
permissionMode | 独立的权限模式 | 会话的模式 |
maxTurns | 停止前的轮次上限（正整数） | 没有单独限制 |
memory | 持久记忆：user、project 或 local | 无记忆 |
background | true 表示始终在后台运行 | 在前台运行 |
isolation | worktree 表示在隔离的 git worktree 中运行 | 在当前文件夹运行 |
color | 子代理在界面中的颜色 | 无颜色 |
注意 tools：省略该字段表示允许全部工具，而写一个空的 tools: 会让子代理没有任何工具。另外，如果你在设置 tools 列表的同时开启了 memory，Verboo Code 会自动加上 Read、Write 和 Edit，因为子代理需要它们来读写自己的记忆。
如何让 Verboo Code 使用子代理？
有两种方式。最直接的是按名称请求：
use the revisor subagent on what I changed today主代理会用 revisor 调用 Agent 工具，它在自己的上下文中读取 diff，只返回问题列表。
另一种是让主代理自行决定。它根据 description 来选择，所以 description 必须写明何时使用，而不只是角色。"代码审查员"太笼统；"Use proactively after any change in src/" 才是触发条件：当 description 表明子代理应被主动使用时，Agent 工具的提示词会指示模型无需你请求就调用它。
Verboo Code 在哪里查找子代理？
| 文件夹 | 作用范围 |
|---|---|
~/.verboo/agents/ | 你自己的，所有项目通用 |
.verboo/agents/ 或 .claude/agents/ | 项目级。从当前文件夹向上直到 git 仓库根目录都有效 |
项目中原有的 .claude/agents/ 子代理无需复制即可使用。用户文件夹只有 ~/.verboo/agents/；如果你用 VERBOO_CONFIG_DIR 修改了配置目录，它会变为 $VERBOO_CONFIG_DIR/agents/。
两处有相同的 name？更具体的一方胜出，优先级从低到高依次为：内置、插件、你自己的、项目的、--agents 参数，最后是公司统一管理的。项目中的 general-purpose.md 会为所有在该项目工作的人替换内置版本。
能否只为单次运行定义子代理？
可以，使用接收 JSON 的 --agents 参数。适合脚本和 CI，无需创建文件：
verboo --agents '{"revisor": {"description": "Reviews the current diff", "prompt": "You are a code reviewer. Do not edit files.", "tools": ["Read", "Grep", "Glob", "Bash"]}}'JSON 中 description 和 prompt 为必填，tools 是一个列表。该子代理只在本次会话中存在。单数形式的 --agent <name> 是另一回事：它指定主会话本身使用的代理。
子代理、skill 还是 AGENTS.md：该用哪个？
| 子代理 | Skill | AGENTS.md | |
|---|---|---|---|
| 上下文 | 独立，与对话分开 | 对话的上下文 | 对话的上下文 |
| 工具 | 只有你列出的 | 会话的工具 | 会话的工具 |
| 适合 | 读得多、回得少的任务：审查、搜索、分诊 | 按名称调用的可重复流程 | 项目的长期规则 |
如果任务需要对话中已有的内容，请使用 skill。如果是始终适用的规则，就写进 AGENTS.md，参见用 /memory 设置永久指令的教程。子代理用于把繁重的工作隔离在主上下文之外，可以配合 /context 查看上下文占用。
每个子代理都会打开自己的上下文并重新读取文件，因此委派比在主对话中完成所有工作消耗更多 token。在 Verboo Code 上 token 不限量，你可以放心委派，不用算账。
行为已于 2026-11-05 在 Verboo Code 源码（verbeux-ai/code，v0.15.41）中核实：src/commands/agents、src/tools/AgentTool/loadAgentsDir.ts、src/tools/AgentTool/prompt.ts、src/components/agents、src/utils/model/agent.ts、src/utils/markdownConfigLoader.ts 和 src/main.tsx。
