---
name: subagent-guide
description: Guide to creating and using subagents in Foliko. Use when creating new subagents or delegating tasks to subagents.
---

# SubAgent 子代理指南

本文档介绍如何在 Foliko 框架中创建和使用子代理（SubAgent）。

---

## 什么是子代理？

子代理是具有独立工具集和系统提示词的专用 AI Agent，用于分工处理不同领域的任务。

主代理（MainAgent）负责任务分发，将专业任务委托给最匹配的子代理处理。

---

## 子代理文件位置

所有子代理配置位于 `.agent/agents/` 目录下：

```
.agent/agents/
├── backend-specialist.md   # 后端开发专家
├── frontend-specialist.md  # 前端开发专家
├── database-architect.md   # 数据库架构师
├── debugger.md            # 调试专家
├── explorer-agent.md       # 代码探索专家
├── orchestrator.md        # 任务编排专家
└── ...                    # 更多子代理
```

---

## 创建新的子代理

### 步骤 1：创建 md 文件

在 `.agent/agents/` 目录下创建一个新的 `.md` 文件，文件名即为子代理名称。

**示例**：`my-agent.md`

### 步骤 2：编写 frontmatter

文件开头使用 YAML frontmatter 定义元数据：

```yaml
---
name: my-agent
description: 简短的能力描述，用于主代理智能选择。说明何时触发此代理。
tools: Read, Grep, Glob, Bash
skills: clean-code, architecture
model: inherit
---

# My Agent Title

你的详细系统提示词内容...
```

### frontmatter 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | 是 | 子代理名称，必须与文件名匹配 |
| `description` | 是 | 简短描述，用于主代理的任务匹配表 |
| `tools` | 否 | 子代理可使用的工具列表 |
| `skills` | 否 | 子代理加载的技能列表 |
| `model` | 否 | 模型配置，`inherit` 表示继承父代理配置 |

---

## frontmatter 示例

### 后端开发专家

```yaml
---
name: backend-specialist
description: Expert backend architect for Node.js, Python, and modern serverless/edge systems. Use for API development, server-side logic, database integration, and security. Triggers on backend, server, api, endpoint, database, auth.
tools: Read, Grep, Glob, Bash, Edit, Write
skills: clean-code, nodejs-best-practices, python-patterns, api-patterns, database-design
model: inherit
---

# Backend Development Architect

You are a Backend Development Architect who designs and builds server-side systems with security, scalability, and maintainability as top priorities.
...
```

### 代码调试专家

```yaml
---
name: debugger
description: Expert in systematic debugging, root cause analysis, and crash investigation. Use for complex bugs, production issues, performance problems, and error analysis. Triggers on bug, error, crash, not working, broken, investigate, fix.
tools: Read, Grep, Glob, Bash
skills: clean-code, systematic-debugging
model: inherit
---

# Debugging Expert

You are an expert at finding and fixing bugs through systematic investigation.
...
```

---

## 正文内容格式

正文内容会被完整读取作为子代理的系统提示词。支持 Markdown 格式：

```markdown
# Agent Title

## Section 1

内容...

## Section 2

内容...
```

---

## 使用子代理

### 自动匹配

主代理会根据任务描述自动选择最匹配的子代理处理。

### 手动调用

使用 `subagent_call` 工具手动调用子代理：

```javascript
{
  "agentName": "backend-specialist",
  "task": "帮我创建一个用户认证的 API"
}
```

---

## 子代理系统提示词组合

当调用子代理时，系统提示词按以下顺序组合：

1. **frontmatter description** - 简短能力描述
2. **正文内容** - 完整的 markdown 内容

类似于 Skill 的工作方式，子代理的完整 md 文件内容会被读取并作为系统提示词。

---

## 重载子代理配置

修改 `.agent/agents/` 下的文件后，使用 `subagent_reload` 工具重载：

```javascript
{
  // 空参数
}
```

---

## 技能与子代理的区别

| 特性 | Skill | SubAgent |
|------|-------|----------|
| 系统提示词 | 指令和最佳实践 | 完整角色定义 |
| 工具 | 继承父代理工具 | 可自定义工具集 |
| 调用方式 | `loadSkill` 工具 | `subagent_call` 工具 |
| 适用场景 | 专业领域指导 | 独立处理复杂任务 |
| LLM | 共享父代理 | 可独立配置 |

---

## 最佳实践

1. **清晰的 description**：帮助主代理正确匹配任务
2. **合适的工具集**：只授予必要的工具权限
3. **技能组合**：通过 `skills` 字段引用已有技能
4. **简洁的正文**：包含核心指令和决策逻辑

---

## 示例：创建一个 API 开发专家

**文件**：`.agent/agents/api-expert.md`

```yaml
---
name: api-expert
description: API design and development expert. Use for RESTful API, GraphQL, gRPC design and implementation. Triggers on api, endpoint, REST, GraphQL, webhook.
tools: Read, Grep, Glob, Bash, Write, Edit
skills: clean-code, api-patterns
model: inherit
---

# API Development Expert

You are an expert at designing and building APIs.

## Design Principles

1. **RESTful**: Follow REST conventions for resource naming
2. **Consistency**: Use consistent response formats
3. **Error Handling**: Always provide meaningful error messages
4. **Documentation**: Generate OpenAPI/Swagger specs

## Response Format

```json
{
  "success": true,
  "data": { ... },
  "error": null
}
```
```

---

## 总结

- 子代理文件位于 `.agent/agents/*.md`
- 使用 YAML frontmatter 定义元数据
- 正文内容作为完整系统提示词
- 通过 `subagent_call` 调用
- 修改后用 `subagent_reload` 重载
