# 子智能体实现方案

## 概述

将 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. **对话记录保留**：便于调试和审计