Subagent（子代理）是 SolonCode 的核心能力，支持将复杂任务委派给具备特定专业技能的专家代理（可以串行，或并行），实现"让专业的人做专业的事"或者“同时多人干活”。


### 1、核心架构

```
┌─────────────────────────────────────────────────────────┐
│                    用户交互入口                           │
│                       ↓                                 │
│                  主代理 (ReActAgent)                     │
│              - 接收指令、分析任务                          │
│              - 任务分解、委派调度                          │
│              - 结果汇总、响应输出                          │
└─────────────────────────────────────────────────────────┘
                         │
           ┌─────────────┼───────────────────┐
           ↓             ↓                   ↓
    ┌────────────┐  ┌─────────────────┐  ┌──────────┐
    │ Architect  │  │   Development   │  │  Tester  │
    └────────────┘  └─────────────────┘  └──────────┘
```

**工作流程：**

```
用户指令 → 主代理分析 → 任务分解 → 子代理执行 → 结果汇总 → 响应用户
```



### 2、预置子代理

| 名称 | 职责 | 特点 |
|---|---|---|
| `general` | 通用执行专家 | 其他代理不合适时使用 |
| `explore` | 本地与网络信息探索 | 无写权限，适合调研 |
| `bash` | 命令行执行 | 无写权限，适合 git、构建、诊断 |
| `plan` | 规划专家 | 无写权限，适合复杂方案设计 |

CLI 与 Web 都支持用 `@agentName` 指定代理：

```text
@explore 分析一下这个项目的模块结构
@plan 给我设计一个迁移方案
@bash 运行 git status 和 mvn test，提取关键结果
```

CLI 中可用 `@(tab)` 查看可选子代理。

### 3、配置位置

| 位置 | 作用 |
|---|---|
| `~/.soloncode/agents/` | 全局子代理 |
| `.soloncode/agents/` | 工作区子代理 |

同名子代理可用于覆盖默认定义。工作区代理更适合项目专属角色，例如“后端开发”“前端开发”“测试工程师”。

### 4、子代理文件格式

示例 `.soloncode/agents/backend-dev.md`：

```markdown
---
name: "backend-dev"
description: "Solon 后端开发专家，负责接口、服务、测试。"
model: "coder-model"
tools: ["read", "grep", "glob", "edit", "bash", "code", "todo"]
disallowedTools: []
maxTurns: 30
---

你是 Solon 后端开发专家。

工作要求：
1. 修改前先阅读相关文件。
2. 修改后运行测试。
3. 输出变更清单与验证结果。
```

常用元数据：

| 字段 | 说明 |
|---|---|
| `name` | 子代理名称，必填 |
| `description` | 能力描述，必填，会影响主代理选择 |
| `model` | 指定模型，可选 |
| `tools` | 允许工具列表 |
| `disallowedTools` | 禁止工具列表 |
| `sessionWindowSize` | 会话窗口 |
| `summaryWindowSize` | 摘要窗口 |
| `summaryWindowToken` | 摘要 token 阈值 |
| `maxTurns` | 最大执行回合 |
| `autoRethink` | 是否允许自我反思继续 |



### 5、工具权限建议

- `description` 要写清楚，主代理会依据它判断是否委派。
- 给探索类代理去掉写权限，降低误操作风险。
- 给开发类代理保留 `read`、`edit`、`bash`、`code`、`todo`。
- 如果某个代理只做规划，不要给 `write/edit/bash`。
- 不要为了省事给所有代理 `tools: ["*"]`。

### 6、验证是否生效

启动 CLI 后输入：

```text
@(tab)
```

或直接指定：

```text
@explore 说明你的职责和可用工具
```

### 7、团队编排建议

可以先让主代理生成团队方案，再保存为项目文档：

```text
请为这个权限系统设计 agent team，至少包含 architect、backend-dev、frontend-dev、tester。先输出分工和阶段计划，保存到 .soloncode/agents 需要的代理定义中，然后按阶段执行。
```

建议把团队协作过程写清楚：谁先做设计、谁并行开发、谁负责验证、失败时如何回退。


示例：

> 我想开发一个经典的权限管理系统（项目名为 demo1-web，里面再建两个目录分为前端与后端），后端基于 solon v3.10.1，java8，前端基于 vue3 开发，界面要清爽好看。先帮我设计一个 agent team （至少要有架构师，前端开发，后端开发，测试员四个角色，架构师先做好设计，然后并行开发，之后测试）分工去做这个事，团队设计案保存为 demo1-team.md（经常要看下，避免忘记）。子代理生成时要保存为文件（万一任务中断，也可以复用）。然后驱动团队去完成开发，单元测试，界面测试（用无头浏览器去测试）。全好了后，运行起来，让我检查效果。


或者自己编写团队配置文件（例：demo-team.md，提示词要求使用这个团队文件即可）：