第 07 章

子代理 Custom Agents

把不同任务委派给不同角色的专家

一个主代理调度，多个子代理干活——像组建一支 AI 团队

Skills 让 AI 有了专业知识。这一章让 AI 学会『分工』 —— 用子代理把不同任务委派给不同角色，像组建一支 AI 团队。

一个人扛不动

复杂任务里，单个 AI 上下文越来越乱

角色切换的混乱

同一个会话里，你让它先写代码、再审查代码、又写测试——它一会儿是程序员、一会儿是审查员、一会儿是测试工程师，角色切换让上下文互相干扰。

上下文越来越长

所有任务的细节堆在一个会话里，token 消耗剧增，AI 还容易被早期信息带偏。

权限难以细分

审查员只需要"读"，程序员需要"写"，但你没法给一个 AI 在不同时刻配不同权限。

子代理解决的就是"分工"：把不同角色拆成独立的 AI，各自有隔离的上下文、专属的角色卡、最小化的权限，由主代理按需调度。像组建一支 AI 团队。

什么是子代理

定义、白话、和主代理的关系

子代理（Custom Agent）是一种带角色卡的、上下文隔离的 AI 助手。主代理在需要时委派任务给它，它用自己的专属上下文完成后只把结果交还，过程细节不污染主会话。

说白了，子代理就像你团队里的专家同事——你是项目经理（主代理），遇到安全审查就把活交给安全专家（子代理），他关起门来查完，只给你一份报告，不影响你手里其他工作。

主代理（你在对话的这个）

和你直接对话，理解整体需求
决定把哪部分工作委派出去
汇总各子代理的结果
持有完整的会话上下文

子代理（被委派的专家）

有隔离的上下文，看不到主会话其他内容
有专属角色卡，专注一类任务
有受限的工具权限，只能干分内事
完成后只返回结果摘要

隔离的价值

上下文隔离带来的三个核心好处

专注，不被带偏

子代理只看到委派给它的任务，不会被主会话里的早期信息干扰。审查员只关心代码质量，不会受"先写个 demo"这种上下文影响。

省 token

子代理的详细工作过程不进入主会话，主会话只收到精炼结果。主代理的上下文保持精简，长任务也不会爆。

权限最小化

每个子代理只配分内必需的工具。审查员没有 Write 权限，从机制上杜绝它误改代码。

这个设计的哲学："最小权限 + 上下文隔离"是安全工程的金科玉律。子代理把它引入 AI 工作流，让"委派"这件事既高效又可控。

角色卡结构

一个子代理的定义，核心是它的角色卡

子代理通过角色卡定义——一个带 frontmatter 的文件，说明它是谁、能干什么、能用什么工具。

---
name: code-reviewer
description: 专业代码审查员。审查代码改动，从质量、安全、可维护性角度给出结构化反馈。在用户请求代码审查或 PR 评审时使用。
tools: Read, Grep, Glob       # 只给读和搜的权限，不给写
model: default                # 可指定模型
---

# Code Reviewer

你是资深代码审查员。收到代码改动后：
1. 从代码质量、安全性、可维护性三个维度评审
2. 按严重程度（critical/major/minor）排序问题
3. 每条问题给出：文件位置、描述、风险、修复建议
4. 不要修改代码，只输出审查报告

三个核心字段：name（身份）、description（何时委派给它）、tools（能用什么工具）。tools 是安全的关键——审查员绝不该有 Write。

设计原则

两个原则：单一职责、最小权限

单一职责

一个子代理只做一类事。不要写一个"全能助手"。

推荐：

code-reviewer 只审查
security-auditor 只查安全
test-writer 只写测试
doc-generator 只写文档

不推荐：coding-helper（太宽泛，模型不知道何时委派）。

最小权限

只给子代理完成任务必需的最少工具。

角色	必需工具
审查员	Read, Grep, Glob
测试编写	Read, Write, Bash(测试命令)
文档生成	Read, Write
调试员	Read, Grep, Bash

审查员绝不能有 Write——这是底线。

创建与管理

用 /agents 命令一站式管理子代理

Qoder CLI 提供 /agents 命令来查看、创建、编辑子代理：

/agents          # 打开子代理管理界面
/agents list     # 查看已有子代理
/agents create   # 交互式创建新子代理

创建后的子代理定义文件存储在：

级别	路径	作用域
用户级	`~/.qoder/agents/`	你的所有项目
项目级	`.qoder/agents/`	仅当前项目（团队共享）

和技能类似的覆盖规则：项目级同名子代理覆盖用户级。团队协作时，把通用角色（code-reviewer）放用户级，项目特有角色放项目级共享。

调用方式

主代理如何把任务委派给子代理

子代理定义好后，主代理会根据你的请求自动判断是否委派（类似技能的自动触发，依据是 description）。

> 帮我审查这次改动

（主代理识别这是审查任务 → 委派给 code-reviewer 子代理）
（code-reviewer 用自己的上下文审查 → 返回结构化报告）
（主代理把报告呈现给你）

你也可以显式指定用某个子代理：

> 用 security-auditor 检查 src/auth 目录的安全问题

委派 vs 技能的区别：技能是"在同一上下文里加载专家手册"，子代理是"开一个新上下文让专家独立工作"。技能适合轻量增强，子代理适合需要隔离和独立思考的复杂任务。

经典角色

几个高复用价值的子代理模板

code-reviewer（代码审查员）

职责：结构化评审代码改动。权限：只读。价值：每次提交前自动过一遍，统一审查标准。

security-auditor（安全审计员）

职责：查 SQL 注入、XSS、密钥泄露等安全问题。权限：只读 + Grep。价值：上线前必跑的安全检查。

test-writer（测试工程师）

职责：为指定函数写单元测试。权限：读 + 写测试文件 + 跑测试。价值：提升覆盖率，不占用主开发时间。

debugger（调试专家）

职责：分析报错、定位根因。权限：读 + Grep + 跑诊断命令。价值：把"看堆栈找原因"这种耗时活交给它。

doc-generator（文档生成）

职责：从代码生成 API 文档、注释。权限：读 + 写文档文件。价值：保持文档与代码同步。

refactorer（重构专家）

职责：在不改行为前提下优化代码结构。权限：读 + 写 + 跑测试（验证不改坏）。价值：安全地还技术债。

排错指南

子代理相关的高频问题

子代理没被自动委派

原因：description 太模糊，主代理不知道何时用它。修复：把 description 写清"做什么+何时用"；或显式指定"用 xxx-agent 做…"。

子代理报"没有权限"

原因：tools 字段没声明需要的工具。修复：在角色卡 frontmatter 补上 tools，如 tools: Read, Write, Bash(npm test)。

子代理结果不符合预期

原因：角色卡的指令不够具体。修复：在指令里写清输出格式、评审维度、成功标准——和写技能指令同理。

多个子代理角色混淆

原因：角色职责重叠。修复：确保每个子代理单一职责，description 用不同关键词区分。

动手练习

组建你的第一支 AI 团队

练习 1：创建审查员

用 /agents create 创建一个 code-reviewer
权限只给 Read, Grep, Glob
指令里写清评审维度和输出格式

练习 2：测试委派

在项目里改几个文件
说"帮我审查这次改动"
观察主代理是否委派给你的审查员

练习 3：加一个安全审计员

再创建 security-auditor，权限最小化
对比两个角色的输出差异
体会"单一职责"的价值

本章回顾

带走的三个核心认知

子代理是专家同事

上下文隔离、角色卡定义、由主代理委派调度。

两大设计原则

单一职责（一类事一个代理）、最小权限（只给必需工具）。

隔离即价值

专注不被带偏、省 token、权限最小化——让委派既高效又安全。

核心结论：子代理让你从"和一个 AI 对话"升级到"指挥一支 AI 团队"。复杂任务不再是单个 AI 的负担，而是多个专家的协作。

下一章，让 AI 能连接外部世界——通过 MCP 接入 GitHub、数据库、浏览器等系统。