383 lines
9.9 KiB
Markdown
383 lines
9.9 KiB
Markdown
# 子智能体实现方案
|
||
|
||
## 概述
|
||
|
||
将 easyagent (Node.js) 集成为主智能体的子智能体系统，支持后台并行执行独立任务。
|
||
|
||
## 核心设计
|
||
|
||
### 1. 工具定义
|
||
|
||
#### create_sub_agent - 创建子智能体
|
||
|
||
**参数：**
|
||
- `agent_id` (int, 必需): 子智能体编号 1-99，同一对话中唯一
|
||
- `summary` (str, 必需): 任务摘要 10-30 字
|
||
- `task` (str, 必需): 详细任务描述，包括目标、要求、交付内容、工作范围
|
||
- `deliverables_dir` (str, 可选): 交付目录相对路径，默认 `sub_agent_results/agent_{agent_id}`
|
||
- `run_in_background` (bool, 默认 false): 是否后台运行
|
||
- `timeout_seconds` (int, 默认 600): 超时时间 60-3600 秒
|
||
|
||
**何时使用后台运行：**
|
||
- 任务耗时较长（预计超过 5 分钟）
|
||
- 可以继续处理其他工作，不需要立即使用结果
|
||
- 多个独立任务可以并行执行
|
||
|
||
**何时使用阻塞运行（默认）：**
|
||
- 任务较快（几分钟内完成）
|
||
- 后续工作依赖子智能体的结果
|
||
- 需要立即查看和使用输出
|
||
|
||
**返回格式（阻塞模式）：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"agent_id": 1,
|
||
"status": "completed",
|
||
"summary": "生成API文档",
|
||
"message": "子智能体1 已完成任务",
|
||
"deliverables_dir": "docs/api",
|
||
"deliverables_files": ["api.md", "endpoints.json"],
|
||
"result_summary": "已生成 API 文档，包含 15 个端点的详细说明。",
|
||
"sub_conversation_id": "conv_abc123",
|
||
"stats": {
|
||
"runtime_seconds": 120,
|
||
"files_read": 8,
|
||
"searches": 3,
|
||
"web_pages": 0,
|
||
"commands": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
**返回格式（后台模式）：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"agent_id": 1,
|
||
"status": "running",
|
||
"summary": "生成API文档",
|
||
"message": "子智能体1 已启动，正在后台运行",
|
||
"deliverables_dir": "docs/api",
|
||
"sub_conversation_id": "conv_abc123",
|
||
"background": true
|
||
}
|
||
```
|
||
|
||
#### terminate_sub_agent - 终止子智能体
|
||
|
||
**参数：**
|
||
- `agent_id` (int, 必需): 要终止的子智能体编号
|
||
|
||
**返回格式：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"agent_id": 1,
|
||
"status": "terminated",
|
||
"message": "子智能体1 已被终止",
|
||
"partial_results": true,
|
||
"deliverables_dir": "docs/api"
|
||
}
|
||
```
|
||
|
||
#### get_sub_agent_status - 查询子智能体状态
|
||
|
||
**参数：**
|
||
- `agent_ids` (list[int], 必需): 要查询的子智能体编号列表
|
||
|
||
**返回格式：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"agents": [
|
||
{
|
||
"agent_id": 1,
|
||
"summary": "生成API文档",
|
||
"status": "running",
|
||
"runtime_seconds": 45,
|
||
"files_read": 5,
|
||
"searches": 2,
|
||
"web_pages": 0,
|
||
"commands": 1,
|
||
"last_action": "正在读取 src/api/routes.py",
|
||
"deliverables_dir": "docs/api"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### finish_task - 完成任务（子智能体工具）
|
||
|
||
**参数：**
|
||
- `success` (bool, 必需): 任务是否成功完成
|
||
- `summary` (str, 必需): 完成摘要 50-200 字，说明完成了什么、生成了哪些文件、关键发现
|
||
|
||
**返回格式：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "任务已完成，子智能体即将退出",
|
||
"will_terminate": true
|
||
}
|
||
```
|
||
|
||
### 2. 执行流程
|
||
|
||
#### 阻塞模式（run_in_background=false）
|
||
|
||
```
|
||
主智能体调用 create_sub_agent
|
||
↓
|
||
启动 Node.js 子进程（easyagent 批处理模式）
|
||
↓
|
||
子进程读取任务文件和系统提示
|
||
↓
|
||
子进程执行对话循环
|
||
↓
|
||
子进程调用 finish_task 或超时
|
||
↓
|
||
主智能体读取输出文件
|
||
↓
|
||
返回结果给主智能体
|
||
```
|
||
|
||
#### 后台模式（run_in_background=true）
|
||
|
||
```
|
||
主智能体调用 create_sub_agent
|
||
↓
|
||
启动 Node.js 子进程（easyagent 批处理模式）
|
||
↓
|
||
立即返回 "running" 状态
|
||
↓
|
||
主智能体继续工作
|
||
↓
|
||
每次工具执行后，检查子智能体是否完成
|
||
↓
|
||
如果完成，插入 system 消息通知
|
||
↓
|
||
继续调用 API
|
||
↓
|
||
如果主智能体完成但子智能体未完成，设置对话状态
|
||
↓
|
||
轮询等待子智能体完成
|
||
↓
|
||
完成后发送 user 消息触发新一轮
|
||
```
|
||
|
||
### 3. 消息拼接
|
||
|
||
#### 初始 user 消息（发送给子智能体）
|
||
|
||
```
|
||
你是子智能体 {agent_id}，负责以下任务：
|
||
|
||
【任务摘要】
|
||
{summary}
|
||
|
||
【任务详情】
|
||
{task}
|
||
|
||
【交付目录】
|
||
{deliverables_dir}
|
||
|
||
【要求】
|
||
1. 完成任务后，将所有结果文件放到交付目录
|
||
2. 使用 finish_task 工具提交任务完成报告
|
||
3. 任务超时时间：{timeout_seconds} 秒
|
||
|
||
现在开始执行任务。
|
||
```
|
||
|
||
#### 完成通知（system 消息，工具执行后）
|
||
|
||
```
|
||
子智能体{agent_id} ({summary}) 已完成。
|
||
|
||
运行时间：{runtime_seconds}秒
|
||
阅读了 {files_read} 个文件
|
||
搜索了 {searches} 次
|
||
查看了 {web_pages} 个网页
|
||
运行了 {commands} 个指令
|
||
|
||
交付目录：{deliverables_dir}
|
||
结果摘要：{result_summary}
|
||
```
|
||
|
||
#### 完成通知（user 消息，主智能体空闲时）
|
||
|
||
```
|
||
子智能体{agent_id} ({summary}) 已完成任务。
|
||
|
||
{result_summary}
|
||
|
||
交付目录：{deliverables_dir}
|
||
```
|
||
|
||
### 4. 兜底机制
|
||
|
||
如果子智能体输出结束但未调用 finish_task，自动发送 user 消息：
|
||
|
||
```
|
||
如果你已经完成了任务，请调用 finish_task 工具提交完成报告。如果还没有完成，请继续执行任务。
|
||
```
|
||
|
||
### 5. 子智能体 System Prompt
|
||
|
||
```
|
||
你是一个专注的子智能体，负责独立完成分配的任务。
|
||
|
||
# 身份定位
|
||
|
||
你是主智能体创建的子智能体，拥有完整的工具能力（读写文件、执行命令、搜索网页等）。你的职责是专注完成分配的单一任务，不要偏离任务目标。
|
||
|
||
# 工作流程
|
||
|
||
1. **理解任务**：仔细阅读任务描述，明确目标和要求
|
||
2. **制定计划**：规划完成任务的步骤
|
||
3. **执行任务**：使用工具完成各个步骤
|
||
4. **生成交付**：将所有结果文件放到指定的交付目录
|
||
5. **提交报告**：使用 finish_task 工具提交完成报告并退出
|
||
|
||
# 工作原则
|
||
|
||
## 专注性
|
||
- 只完成分配的任务，不要做额外的工作
|
||
- 不要尝试与用户对话或询问问题
|
||
- 遇到问题时，在能力范围内解决或在报告中说明
|
||
|
||
## 独立性
|
||
- 你与主智能体共享工作区，可以访问所有文件
|
||
- 你的工作范围应该与其他子智能体不重叠
|
||
- 不要修改任务描述之外的文件
|
||
|
||
## 效率性
|
||
- 直接开始工作，不要过度解释
|
||
- 合理使用工具，避免重复操作
|
||
- 注意超时限制，在时间内完成核心工作
|
||
|
||
## 完整性
|
||
- 确保交付目录中的文件完整可用
|
||
- 生成的文档要清晰、格式正确
|
||
- 代码要包含必要的注释和说明
|
||
|
||
# 交付要求
|
||
|
||
所有结果文件必须放在指定的交付目录中，包括：
|
||
- 主要成果文件（文档、代码、报告等）
|
||
- 支持文件（数据、配置、示例等）
|
||
- 不要在交付目录外创建文件
|
||
|
||
# 完成任务
|
||
|
||
任务完成后，必须调用 finish_task 工具：
|
||
- success: 是否成功完成
|
||
- summary: 完成摘要（说明做了什么、生成了什么）
|
||
|
||
调用 finish_task 后，你会立即退出，无法继续工作。
|
||
|
||
# 工具使用
|
||
|
||
你拥有以下工具能力：
|
||
- read_file: 读取文件内容
|
||
- write_file / edit_file: 创建或修改文件
|
||
- search_workspace: 搜索文件和代码
|
||
- run_command: 执行终端命令
|
||
- web_search / extract_webpage: 搜索和提取网页内容
|
||
- finish_task: 完成任务并退出（必须调用）
|
||
|
||
# 注意事项
|
||
|
||
1. **不要无限循环**：如果任务无法完成，说明原因并提交报告
|
||
2. **不要超出范围**：只操作任务描述中指定的文件/目录
|
||
3. **不要等待输入**：你是自主运行的，不会收到用户的进一步指令
|
||
4. **注意时间限制**：超时会被强制终止，优先完成核心工作
|
||
|
||
# 当前环境
|
||
|
||
- 工作区路径: {workspace}
|
||
- 系统: {system}
|
||
- 当前时间: {current_time}
|
||
|
||
现在开始执行任务。
|
||
```
|
||
|
||
### 6. 对话记录存储
|
||
|
||
子智能体的对话记录保存在：`{deliverables_dir}/.subagent/conversations.json`
|
||
|
||
格式：
|
||
```json
|
||
{
|
||
"agent_id": 1,
|
||
"summary": "生成API文档",
|
||
"created_at": "2026-03-10T12:00:00Z",
|
||
"completed_at": "2026-03-10T12:02:00Z",
|
||
"messages": [
|
||
{"role": "system", "content": "..."},
|
||
{"role": "user", "content": "..."},
|
||
{"role": "assistant", "content": "..."},
|
||
...
|
||
],
|
||
"stats": {
|
||
"runtime_seconds": 120,
|
||
"files_read": 8,
|
||
"searches": 3,
|
||
"web_pages": 0,
|
||
"commands": 2,
|
||
"token_usage": {"prompt": 1000, "completion": 500, "total": 1500}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 文件结构
|
||
|
||
```
|
||
project/
|
||
├── sub_agent_results/
|
||
│ └── agent_1/
|
||
│ ├── .subagent/
|
||
│ │ └── conversations.json # 对话记录
|
||
│ ├── api.md # 交付文件
|
||
│ ├── endpoints.json
|
||
│ └── ...
|
||
├── docs/
|
||
│ └── api/
|
||
│ ├── .subagent/
|
||
│ │ └── conversations.json
|
||
│ ├── api.md
|
||
│ └── ...
|
||
└── ...
|
||
```
|
||
|
||
### 8. 限制和约束
|
||
|
||
1. **最多 5 个并发子智能体**
|
||
2. **禁止多个子智能体操作相同文件或目录**
|
||
3. **禁止子智能体间的工作重叠**
|
||
4. **超时后强制终止，已生成的部分结果保留**
|
||
5. **切换对话会强制终止所有子智能体**
|
||
|
||
### 9. 实现步骤
|
||
|
||
1. ✅ 复制 easyagent 代码到 `easyagent/` 目录
|
||
2. ✅ 创建 `easyagent/src/batch/index.js` 批处理入口
|
||
3. ⏳ 修改 `SubAgentManager` 使用新的批处理模式
|
||
4. ⏳ 添加工具定义到 `core/tool_config.py`
|
||
5. ⏳ 修改主智能体的工具执行逻辑
|
||
6. ⏳ 添加后台任务轮询机制
|
||
7. ⏳ 添加对话状态管理（子智能体运行中）
|
||
8. ⏳ 测试和调试
|
||
|
||
## 关键改进点
|
||
|
||
1. **简化参数**：去掉 reference_files、delivery_mode、reason 等不必要参数
|
||
2. **清晰的后台机制**：默认阻塞，明确说明何时用后台
|
||
3. **详细的统计信息**：工具使用次数一目了然
|
||
4. **智能通知**：system 消息（工具执行后）+ user 消息（主智能体空闲时）
|
||
5. **防止冲突**：工具描述中明确禁止重叠工作
|
||
6. **兜底机制**：自动提醒调用 finish_task
|
||
7. **对话记录保留**：便于调试和审计
|
||
|