feat(zh): add Chinese translations in zh/ directory
Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
This commit is contained in:
Luong NGUYEN
380
zh/04-subagents/README.md
Normal file
380
zh/04-subagents/README.md
Normal file
@@ -0,0 +1,380 @@
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
|
||||
<img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
|
||||
</picture>
|
||||
|
||||
# Subagents 完整参考
|
||||
|
||||
## 概览
|
||||
|
||||
Subagents 是专门处理某类任务的独立 AI 助手。它们拥有隔离的上下文、自己的提示词和工具权限，适合把复杂工作拆分给不同角色。
|
||||
|
||||
## 主要好处
|
||||
|
||||
- 上下文隔离
|
||||
- 角色分工清晰
|
||||
- 适合并行和委派
|
||||
- 便于把复杂任务拆开
|
||||
|
||||
## 文件位置
|
||||
|
||||
- 项目级：`.claude/agents/`
|
||||
- 用户级：`~/.claude/agents/`
|
||||
|
||||
## 配置
|
||||
|
||||
### 文件格式
|
||||
|
||||
Subagent 通常是一个带 frontmatter 的 Markdown 文件。
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: 审查代码质量和安全问题
|
||||
tools: Read, Grep, Bash
|
||||
---
|
||||
|
||||
# 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` 命令（推荐）
|
||||
|
||||
```bash
|
||||
/agents
|
||||
```
|
||||
|
||||
### 直接管理文件
|
||||
|
||||
#### 创建项目 subagent
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/agents
|
||||
```
|
||||
|
||||
#### 创建用户 subagent
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.claude/agents
|
||||
```
|
||||
|
||||
## 使用 Subagents
|
||||
|
||||
### 自动委派
|
||||
|
||||
主 agent 可以根据任务描述自动把工作分配给合适的 subagent。
|
||||
|
||||
### 显式调用
|
||||
|
||||
你也可以明确让 Claude 使用某个 subagent。
|
||||
|
||||
### `@` 提及调用
|
||||
|
||||
在一些场景里，可以通过 `@agent-name` 方式引用。
|
||||
|
||||
### 会话级 agent
|
||||
|
||||
可以在整个会话中固定使用某个 agent。
|
||||
|
||||
### 列出可用 agents
|
||||
|
||||
```bash
|
||||
claude agents
|
||||
```
|
||||
|
||||
## 可恢复的 agents
|
||||
|
||||
某些 subagent 可以先启动，之后再恢复，便于长任务接力。
|
||||
|
||||
## 串联 Subagents
|
||||
|
||||
复杂任务里可以让多个 subagent 依次协作，例如：
|
||||
|
||||
1. 代码审查
|
||||
2. 测试生成
|
||||
3. 文档更新
|
||||
|
||||
## Subagents 的持久记忆
|
||||
|
||||
Subagents 可以拥有自己的 memory 范围，让它们在各自职责内保持一致。
|
||||
|
||||
### Memory 范围
|
||||
|
||||
- 项目级
|
||||
- 用户级
|
||||
- 子目录级
|
||||
|
||||
### 工作方式
|
||||
|
||||
Subagent 会在自己的上下文中读取对应记忆，不和主会话完全混在一起。
|
||||
|
||||
## 后台 Subagents
|
||||
|
||||
### 配置
|
||||
|
||||
有些 subagent 可以作为后台任务执行，不阻塞主会话。
|
||||
|
||||
### 快捷键
|
||||
|
||||
在支持的界面中，可用快捷键查看或切换后台 subagent。
|
||||
|
||||
### 关闭后台任务
|
||||
|
||||
如果你不想让任务后台运行，可以在设置中关闭。
|
||||
|
||||
## Worktree 隔离
|
||||
|
||||
### 配置
|
||||
|
||||
可以为 subagent 分配独立的 worktree。
|
||||
|
||||
### 工作方式
|
||||
|
||||
这样不同任务就不会互相污染文件状态。
|
||||
|
||||
## 限制可启动的 Subagents
|
||||
|
||||
你可以限制 Claude 只能 spawn 某些 subagent，以降低风险。
|
||||
|
||||
### 示例
|
||||
|
||||
- 只允许审查类 agent
|
||||
- 禁止高风险自动化 agent
|
||||
|
||||
## `claude agents` CLI 命令
|
||||
|
||||
用于查看和管理当前可用的 agent。
|
||||
|
||||
## Agent Teams（实验性）
|
||||
|
||||
Agent teams 是更高级的协作模式，适合多个 subagent 并行处理复杂任务。
|
||||
|
||||
### Subagents vs Agent Teams
|
||||
|
||||
- Subagents 侧重委派单个任务
|
||||
- Agent teams 侧重多角色协作
|
||||
|
||||
### 启用 Agent Teams
|
||||
|
||||
通过设置打开实验性功能。
|
||||
|
||||
### 启动团队
|
||||
|
||||
团队模式会把不同任务分配给不同角色。
|
||||
|
||||
### 显示模式
|
||||
|
||||
可以选择更适合终端或图形界面的显示方式。
|
||||
|
||||
### 导航
|
||||
|
||||
你可以在 team 中切换角色、查看状态和读取消息。
|
||||
|
||||
### 团队配置
|
||||
|
||||
适合为大型流程定义清晰角色。
|
||||
|
||||
### 架构
|
||||
|
||||
agent team 本质上是多个专门角色围绕同一任务协作。
|
||||
|
||||
### 任务分配与消息
|
||||
|
||||
主 agent 会负责把任务拆分并转发给对应 subagent。
|
||||
|
||||
### 计划审批流程
|
||||
|
||||
如果是 plan 驱动流程，团队会先审计划再执行。
|
||||
|
||||
### 团队相关 hook 事件
|
||||
|
||||
一些 hook 可以在 team 生命周期里触发。
|
||||
|
||||
### 最佳实践
|
||||
|
||||
- 角色定义要清楚
|
||||
- 任务边界要明确
|
||||
- 不要让多个 agent 做重复工作
|
||||
|
||||
### 局限
|
||||
|
||||
- 实验性功能可能会变化
|
||||
- 复杂团队需要更多配置
|
||||
|
||||
## 插件中的 Subagent 安全
|
||||
|
||||
插件分发的 subagent 要特别注意权限、工具范围和边界条件。
|
||||
|
||||
## 架构
|
||||
|
||||
### 高层架构
|
||||
|
||||
主 agent、subagent、文件系统和工具权限共同构成执行链。
|
||||
|
||||
### 生命周期
|
||||
|
||||
1. 创建
|
||||
2. 分配任务
|
||||
3. 执行
|
||||
4. 返回结果
|
||||
5. 结束或恢复
|
||||
|
||||
## 上下文管理
|
||||
|
||||
### 关键点
|
||||
|
||||
- 子上下文尽量小
|
||||
- 让每个 subagent 只负责自己的事
|
||||
- 避免把所有信息都塞进去
|
||||
|
||||
### 性能考虑
|
||||
|
||||
过多的上下文会拖慢速度并降低准确性。
|
||||
|
||||
### 关键行为
|
||||
|
||||
subagent 在隔离上下文里工作，但仍能把结果汇总回主会话。
|
||||
|
||||
## 什么时候使用 Subagents
|
||||
|
||||
- 任务可拆分
|
||||
- 需要隔离上下文
|
||||
- 需要明确角色分工
|
||||
- 需要并行协作
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 设计原则
|
||||
|
||||
- 单一职责
|
||||
- 描述明确
|
||||
- 工具权限最小化
|
||||
|
||||
### System Prompt 最佳实践
|
||||
|
||||
- 任务说明要具体
|
||||
- 不要写太长
|
||||
- 只保留执行任务所需的信息
|
||||
|
||||
### 工具访问策略
|
||||
|
||||
- 审查型 subagent 只读
|
||||
- 实现型 subagent 适度开放写权限
|
||||
- 高风险动作要保持审批
|
||||
|
||||
## 本目录中的示例 Subagents
|
||||
|
||||
### 1. [Code Reviewer](./code-reviewer.md)
|
||||
|
||||
用于全面代码质量审查。
|
||||
|
||||
### 2. [Test Engineer](./test-engineer.md)
|
||||
|
||||
用于测试策略、覆盖率和测试生成。
|
||||
|
||||
### 3. [Documentation Writer](./documentation-writer.md)
|
||||
|
||||
用于技术文档写作和更新。
|
||||
|
||||
### 4. [Secure Reviewer](./secure-reviewer.md)
|
||||
|
||||
用于安全检查，通常只读。
|
||||
|
||||
### 5. [Implementation Agent](./implementation-agent.md)
|
||||
|
||||
用于功能实现和代码修改。
|
||||
|
||||
### 6. [Debugger](./debugger.md)
|
||||
|
||||
用于定位 bug 和分析异常。
|
||||
|
||||
### 7. [Data Scientist](./data-scientist.md)
|
||||
|
||||
用于分析数据、解释结果和生成报告。
|
||||
|
||||
### 8. [Clean Code Reviewer](./clean-code-reviewer.md)
|
||||
|
||||
用于按 Clean Code 原则做专门审查。
|
||||
|
||||
## 安装说明
|
||||
|
||||
### 方法 1：使用 `/agents`
|
||||
|
||||
```bash
|
||||
/agents
|
||||
```
|
||||
|
||||
### 方法 2：复制到项目
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/agents
|
||||
cp 04-subagents/*.md .claude/agents/
|
||||
```
|
||||
|
||||
### 方法 3：复制到用户目录
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.claude/agents
|
||||
cp 04-subagents/*.md ~/.claude/agents/
|
||||
```
|
||||
|
||||
### 验证
|
||||
|
||||
- 运行 `/agents`
|
||||
- 检查对应 agent 是否出现在列表中
|
||||
- 试着让 Claude 委派一个简单任务
|
||||
|
||||
## 文件结构
|
||||
|
||||
```text
|
||||
.claude/agents/
|
||||
├── clean-code-reviewer.md
|
||||
├── code-reviewer.md
|
||||
├── data-scientist.md
|
||||
├── debugger.md
|
||||
├── documentation-writer.md
|
||||
├── implementation-agent.md
|
||||
├── secure-reviewer.md
|
||||
├── test-engineer.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 相关概念
|
||||
|
||||
- [Skills 中文指南](../03-skills/README.md)
|
||||
- [Memory 中文指南](../02-memory/README.md)
|
||||
- [Hooks 中文指南](../06-hooks/README.md)
|
||||
- [Plugins 中文指南](../07-plugins/README.md)
|
||||
Reference in New Issue
Block a user