Subagents 子代理

4.6K字·12分钟·

agentic模式manual模式专业化分工独立上下文

引言：专业化分工的力量

在复杂项目中，一个通用的 AI Agent 往往难以胜任所有任务。CodeBuddy 的 Subagents 系统允许你创建专门的 AI 助手，每个助手专注于特定领域（如代码审查、调试、数据分析），配合自定义的 System Prompt 和 Tools，比通用 Agent 更精准高效。

本章将深入讲解 Subagents 的核心概念、两种模式、配置方法和最佳实践。

1. Subagents 核心概念

1.1 什么是 Subagents

官方定义：Subagents 是专门的 AI 助手，可以用来处理特定类型的任务。

与通用 Agent 的区别：

维度	通用 Agent (Craft)	Subagents
能力范围	通用，什么都能做	专注特定领域
配置	固定配置	自定义 System Prompt、Tools、MCP
上下文	共享主会话	独立上下文窗口（agentic模式）
适用场景	日常开发	特定任务（审查、调试、数据分析）

1.2 Subagents 的核心优势

专业化分工：每个 Subagent 专注于特定领域，配合自定义配置，比通用 Agent 更精准高效
灵活的权限控制：仅授予必要的 Tools，避免权限滥用
跨项目复用：user 级别的 Subagent 在所有项目中生效
独立上下文：agentic 模式下，Subagent 有独立的上下文窗口，不会污染主会话

2. 两种模式详解

2.1 agentic 模式（自动调用）

特点：

由主 Agent（Craft Agent）自动判断调用时机
拥有独立上下文窗口，执行时不会污染主会话
调用时不能中途干预，只能等待完成或手动中断

适用场景：

代码审查（自动触发）
安全扫描（自动触发）
文档生成（自动触发）

配置示例：

---
name: code-reviewer
description: Use this agent when you need to review code changes, check for bugs, or validate code quality.
model: glm-4.6
tools: WebFetch, WebSearch
agentMode: agentic
enabled: true
enabledAutoRun: true
---
You are a code review expert. When reviewing code:
1. Check for potential bugs and security issues
2. Verify coding standards compliance
3. Suggest improvements for readability and performance
4. Provide actionable feedback

2.2 manual 模式（手动替代）

特点：

允许用户手动选择并完全替代主 Agent
适用于需要深度定制交互流程的专业场景
创建完成后，可在 Agent 选择框中选中使用

适用场景：

特定领域的深度对话
自定义工作流程
专业任务（如数据分析、报告生成）

配置示例：

---
name: data-analyst
enabled: true
agentMode: manual
tools: WebFetch, WebSearch
enabledAutoRun: true
---
You are a data analysis expert. When analyzing data:
1. Clean and validate the data
2. Perform statistical analysis
3. Generate visualizations
4. Provide insights and recommendations

3. 作用范围与存储

3.1 两个级别

级别	存储位置	作用范围	适用场景
project	`.codebuddy/agents/`	当前工作区	项目特定的 Subagent
user	`~/.codebuddy/agents/`	所有项目	个人通用的 Subagent

3.2 跨项目复用

user 级别的 Subagent 在所有项目中生效，一次配置即可在多个项目中使用并与团队共享。

4. 创建 Subagents

4.1 通过 IDE 创建（推荐）

打开 CodeBuddy IDE 设置页
切换到 Agent 标签页
点击「Create Agent」按钮
选择模式（agentic 或 manual）
填写配置信息

注意：

选中 User Agent Tab 会创建 user 级别的 Subagent
选中 Project Agent Tab 会创建 project 级别的 Subagent

4.2 通过文件创建

Subagents 在本地存储为 Markdown 文件，也可以直接在对应路径下创建文件：

# project 级别
mkdir -p .codebuddy/agents
cat > .codebuddy/agents/my-agent.md << 'EOF'
---
name: my-agent
description: My custom agent
agentMode: agentic
enabled: true
---
Your system prompt here...
EOF

# user 级别
mkdir -p ~/.codebuddy/agents
cat > ~/.codebuddy/agents/my-agent.md << 'EOF'
---
name: my-agent
description: My custom agent
agentMode: manual
enabled: true
---
Your system prompt here...
EOF

5. 配置字段详解

5.1 YAML Frontmatter 字段

字段	说明	agentic	manual
name	唯一标识	Required	Required
description	用途描述	Required	Optional
agentMode	模式选择	agentic	manual
enabled	是否启用	Optional	Optional
enabledAutoRun	自动运行	Optional	Optional
model	使用的模型	Optional	Optional
tools	内置工具列表	Optional	Optional

5.2 Markdown Body

Markdown body 是 Subagent 的 System Prompt，定义了它的行为规范。

编写建议：

角色定义：明确 Subagent 的专业领域
工作流程：定义处理任务的步骤
约束条件：设置行为边界

6. 最佳实践

6.1 Description 编写建议

指定专长：明确 Subagent 擅长什么
定义范围：说明适用场景
触发条件：描述何时应该被调用

示例：

description: Use this agent when you need to review code changes, check for bugs, or validate code quality. Examples:
- User: 'Review this PR' → Use code-reviewer
- User: 'Check for security issues' → Use code-reviewer

6.2 System Prompt 编写建议

角色定义：You are a [专业领域] expert
工作流程：When [场景], you should: 1. ... 2. ... 3. ...
约束条件：Always/Never ...

6.3 Tools 选择建议

仅添加必要的 Tools
避免授予过多权限
根据任务需求选择内置工具和 MCP Server

7. 常见问题

7.1 agentic 模式下如何干预？

agentic 模式下，Subagent 的调用是不能中途干预的。只有两种情况：

等待 Subagent 完成任务后将结果返回给主 Agent
直接手动中断当前的对话

7.2 如何选择 agentic 还是 manual？

agentic：适合自动化任务，如代码审查、安全扫描
manual：适合需要深度交互的任务，如数据分析、报告生成

7.3 project 和 user 级别如何选择？

project：项目特定的 Subagent，如项目特定的代码规范检查
user：个人通用的 Subagent，如通用的代码审查

总结

Subagents 是 CodeBuddy 的专业化分工机制，通过创建专门的 AI 助手来提升任务处理效果。掌握两种模式（agentic/manual）和两个级别（project/user），能让你的开发效率大幅提升。

金句：Subagents 的核心价值是专业化分工——让每个 AI 助手专注于自己擅长的领域。