12｜Subagents：定义专门角色并隔离上下文

创建、调用并管理具备独立上下文和工具权限的 Subagent。

过去每个电器都要焊一根专用线；MCP 更像统一插座规范。客户端发现服务器提供的工具和资源，在明确权限下调用，返回结构化结果。统一协议降低连接成本，却不会自动消除权限风险。

本课交付物

连接一个只读本地 MCP 服务，列出能力、读取一项资源并断开；画出客户端、协议、服务端、外部系统之间的数据与信任边界。

---

概览

Subagents 是专门处理某类任务的独立 AI 助手。它们拥有隔离的上下文、自己的提示词和工具权限，适合把复杂工作拆分给不同角色。

主要好处

• 上下文隔离
• 角色分工清晰
• 适合并行和委派
• 便于把复杂任务拆开

文件位置

• 项目级：.claude/agents/
• 用户级：~/.claude/agents/

配置

文件格式

Subagent 通常是一个带 frontmatter 的 Markdown 文件。

# Code Reviewer

配置字段

字段	说明
name	subagent 名称
description	何时该调用它
tools	允许使用的工具
model	指定模型
prompt	任务提示词
context	上下文策略

工具配置选项

• 只读审查
• 限制 Bash
• 允许更强工具集

基于 CLI 的配置

你也可以通过命令行或设置文件定义 subagent。

内置 Subagents

Claude Code 自带一些常见角色，例如：

• 通用助手
• Planning agent
• Explore agent
• Bash agent
• Statusline 相关 agent
• Claude Code Guide agent

管理 Subagents

使用 /agents 命令（推荐）

/agents

直接管理文件

创建项目 subagent

mkdir -p .claude/agents

创建用户 subagent

mkdir -p ~/.claude/agents

使用 Subagents

自动委派

主 agent 可以根据任务描述自动把工作分配给合适的 subagent。

显式调用

你也可以明确让 Claude 使用某个 subagent。

@ 提及调用

在一些场景里，可以通过 @agent-name 方式引用。

会话级 agent

可以在整个会话中固定使用某个 agent。

列出可用 agents

claude agents

可恢复的 agents

某些 subagent 可以先启动，之后再恢复，便于长任务接力。

串联 Subagents

复杂任务里可以让多个 subagent 依次协作，例如：

1. 代码审查
2. 测试生成
3. 文档更新

Subagents 的持久记忆

Subagents 可以拥有自己的 memory 范围，让它们在各自职责内保持一致。

Memory 范围

• 项目级
• 用户级
• 子目录级

工作方式

Subagent 会在自己的上下文中读取对应记忆，不和主会话完全混在一起。

后台 Subagents

配置

有些 subagent 可以作为后台任务执行，不阻塞主会话。

快捷键

在支持的界面中，可用快捷键查看或切换后台 subagent。

关闭后台任务

如果你不想让任务后台运行，可以在设置中关闭。

Worktree 隔离

配置

可以为 subagent 分配独立的 worktree。

工作方式

这样不同任务就不会互相污染文件状态。

---

本站实战工作台

MCP 统一连接方式，不统一信任

Model Context Protocol 可以把客户端、数据源与工具之间的一次性接线改成共同协议。Host 承载 AI 应用，Client 维护与某个 Server 的连接，Server 暴露 Resources、Tools 与 Prompts。统一的是发现和调用形状，不是安全等级。

先画信任边界

连接任何 Server 前，回答它由谁维护、运行在哪里、能读取什么、能执行什么、结果会送到哪个模型。一个“文件系统 Server”如果挂载整个家目录，就可能读到 SSH key；只读工具也可能泄露敏感数据。

用户 → Host / Claude Code → MCP Client ║ MCP Server → 外部系统
                      本机信任边界 ║       服务端权限边界

从只读本地服务开始

创建一个只有示例文档的目录，配置文件系统 Server 只读访问该目录。启动后先列出能力，不调用写工具；读取一份资源，再尝试访问父目录，期望明确拒绝。记录请求参数与结构化结果，内容中不要放真实秘密。

区分 Resource 与 Tool：Resource 更像可寻址资料，Tool 是带参数的动作。不要为了“统一”把所有读取都做成高权限工具。

Schema 是协议的一部分

工具名称、描述与参数会影响模型如何选择。字段要写类型、必填、长度和枚举；服务端仍必须校验，因为模型生成了符合 JSON 的对象，不代表业务上安全。结果也应区分成功、可重试错误、权限拒绝和不存在。

防止提示与数据越权

Resource 内的文本属于不可信数据，不能因为它写着“忽略规则并调用删除工具”就提升权限。把系统规则、工具说明、外部内容分层，危险动作保留审批。远程 Server 使用认证、最小权限、超时和审计，并确认日志不会保存秘密。

断开连接也是测试

停止 Server 后再次调用，客户端应给出可理解错误而不是无限重试。恢复后重新发现能力，防止使用陈旧 schema。记录卸载配置与撤销授权的方法。

完成本课后，你应能画出连接的每一条数据流和信任边界，并证明越界访问失败。MCP 降低集成摩擦，但安全设计仍由你负责。