JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b6462ff1e2
agent-Specialization/SUB_AGENT_IMPLEMENTATION_PLAN.md

9.9 KiB
Raw Blame History

子智能体实现方案

概述

将 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 分钟）
  • 可以继续处理其他工作，不需要立即使用结果
  • 多个独立任务可以并行执行

何时使用阻塞运行（默认）：

  • 任务较快（几分钟内完成）
  • 后续工作依赖子智能体的结果
  • 需要立即查看和使用输出

返回格式（阻塞模式）：

{
  "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
  }
}

返回格式（后台模式）：

{
  "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, 必需): 要终止的子智能体编号

返回格式：

{
  "success": true,
  "agent_id": 1,
  "status": "terminated",
  "message": "子智能体1 已被终止",
  "partial_results": true,
  "deliverables_dir": "docs/api"
}

get_sub_agent_status - 查询子智能体状态

参数：

  • agent_ids (list[int], 必需): 要查询的子智能体编号列表

返回格式：

{
  "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 字，说明完成了什么、生成了哪些文件、关键发现

返回格式：

{
  "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

格式：

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