Skip to content

multi-agent.zh.md

Latest commit

 

History

History
671 lines (448 loc) · 18.6 KB

multi-agent.zh.md

File metadata and controls

671 lines (448 loc) · 18.6 KB

多智能体

CoPaw 支持多智能体，允许您在同一个 CoPaw 实例中运行多个独立的 AI 智能体。

本功能在 v0.1.0 中引入。

本文档包含两部分内容：

  1. 多智能体工作区 - 如何创建和管理多个智能体，每个智能体拥有独立的配置、记忆、技能和对话历史
  2. 智能体间协作 - 如何启用协作技能，让智能体之间可以互相通信，共同完成复杂任务

第一部分：多智能体工作区

什么是多智能体？

简单来说，多智能体就是让您可以在一个 CoPaw 中运行多个"分身"，每个分身：

  • 有自己的性格和专长（通过不同的人设文件配置）
  • 记住各自的对话（互不干扰）
  • 使用不同的技能（一个擅长代码，一个擅长写作）
  • 连接不同的频道（一个负责钉钉，一个负责 Discord）

就像您有多个助手，每个助手各司其职。

为什么需要多智能体？

场景一：按用途分工

您可能需要：

  • 一个日常助手 - 闲聊、查资料、记待办
  • 一个代码助手 - 专注代码审查和开发
  • 一个写作助手 - 专注文档撰写和润色

每个智能体专注自己的领域，互不干扰。

场景二：按平台分离

您可能在多个平台使用 CoPaw：

  • 钉钉 - 工作相关对话
  • Discord - 社区讨论
  • 控制台 - 私人使用

不同平台的对话和配置完全隔离，不会混在一起。

场景三：测试与生产隔离

您可能需要：

  • 生产智能体 - 稳定配置，用于日常工作
  • 测试智能体 - 实验新功能，不影响生产环境

如何使用？（推荐方式）

在控制台中管理智能体

这是最简单的方式，无需任何命令行操作。

1. 查看和切换智能体

启动 CoPaw 后，在控制台右上角可以看到智能体切换器：

┌───────────────────────────────────┐
│  当前智能体  [默认智能体 ▼] (1)    │
└───────────────────────────────────┘

点击下拉框可以：

  • 查看所有智能体的名称和描述
  • 切换到其他智能体
  • 看到当前智能体的 ID

切换后，页面会自动刷新，显示新智能体的配置和数据。

2. 创建新智能体

进入设置 → 智能体管理页面：

  1. 点击"创建智能体"按钮
  2. 填写信息：
    • 名称：给智能体起个名字（如"代码助手"）
    • 描述：说明这个智能体的专长和用途（重要）
    • ID：留空自动生成，或自定义（如"coder"）
  3. 点击"确定"

创建后，新智能体会出现在列表中，您可以立即切换过去使用。

重要提示：描述字段非常重要！如果您计划使用多智能体协作功能，请在描述中清晰说明这个智能体的专长领域和擅长的任务类型。例如："专注于 Python/JavaScript 代码审查和重构优化"。智能体间协作时会读取这个描述来判断应该调用哪个智能体。

3. 为智能体配置专属设置

切换到某个智能体后，您可以为它单独配置：

  • 频道 - 去"控制 → 频道"页面，启用/配置频道
  • 技能 - 去"智能体 → 技能"页面，启用/禁用技能
  • 工具 - 去"智能体 → 工具"页面，开关内置工具
  • 人设 - 去"智能体 → 工作区"页面，编辑 AGENTS.md 和 SOUL.md

这些配置只影响当前智能体，不会影响其他智能体。

4. 编辑和删除智能体

在设置 → 智能体管理页面：

  • 点击"编辑"按钮修改智能体的名称和描述（修改描述后，系统会自动更新 PROFILE.md）
  • 点击"删除"按钮移除智能体（默认智能体不能删除）

使用场景示例

示例一：工作与生活分离

场景：您希望工作对话和私人对话分开。

配置：

  1. 在控制台创建两个智能体：

    • work - 工作助手
    • personal - 私人助手

  2. 为 work 智能体：

    • 启用钉钉频道
    • 启用代码、文档相关技能
    • 配置正式的人设（AGENTS.md）

  3. 为 personal 智能体：

    • 启用 Discord 或控制台
    • 启用娱乐、新闻相关技能
    • 配置轻松的人设

使用：在钉钉聊天时自动使用 work 智能体，在 Discord 聊天时使用 personal 智能体。

示例二：专业助手团队

场景：您希望有多个专业领域的助手。

配置：

  1. 创建三个智能体：

    • coder - 代码助手（启用代码审查、文件操作技能）
    • writer - 写作助手（启用文档处理、新闻摘要技能）
    • planner - 任务助手（启用定时任务、邮件技能）

  2. 根据需要切换到对应的智能体使用。

优点：每个智能体专注自己的领域，人设更精准，对话历史不会混淆。

示例三：多语言支持

场景：您需要中英文两个助手。

配置：

  1. 创建两个智能体：

    • zh-assistant - 中文助手（language: "zh"）
    • en-assistant - 英文助手（language: "en"）

  2. 分别编辑它们的 AGENTS.md 和 SOUL.md 为对应语言。

使用：需要中文对话时切换到 zh-assistant，需要英文时切换到 en-assistant。

常见问题

Q: 我需要创建多个智能体吗？

不一定。如果您的使用场景简单，只用默认智能体完全足够。

建议创建多个智能体的情况：

  • 需要明确的功能分离（工作/生活、开发/写作等）
  • 连接多个平台，希望每个平台有独立的对话历史
  • 需要测试新配置，不想影响日常使用的智能体

Q: 智能体切换会丢失对话吗？

不会。每个智能体的对话历史都是独立保存的，切换只是改变当前查看的智能体。

Q: 多个智能体会增加成本吗？

不会。智能体只在使用时才调用 LLM，闲置的智能体不会产生费用。

Q: 可以同时使用多个智能体吗？

可以。如果您在钉钉和 Discord 都配置了不同的智能体，它们可以同时响应各自频道的消息。

Q: 如何删除智能体？

在控制台的"设置 → 智能体管理"页面点击删除按钮。

注意：删除后工作区目录会保留（防止误删数据），如需彻底清理，请手动删除 ~/.copaw/workspaces/{agent_id} 目录。

Q: 默认智能体可以删除吗？

不建议删除。default 智能体是系统的默认后备，删除可能导致兼容性问题。

Q: 智能体之间可以共享什么？

全局共享：

  • 模型提供商配置（API Key、模型选择）
  • 环境变量（TAVILY_API_KEY 等）

独立配置：

  • 频道配置
  • 技能启用状态
  • 对话历史
  • 定时任务
  • 人设文件

从单智能体升级

如果您之前使用 CoPaw v0.0.x，升级到 v0.1.0 时会自动迁移：

  1. 首次启动时自动迁移

    • 旧的配置和数据会自动移动到 default 智能体工作区
    • 您无需手动操作任何文件

  2. 验证迁移

    • 启动 CoPaw 后，在控制台查看智能体列表
    • 应该能看到一个名为"默认智能体"的智能体
    • 您的旧对话和配置都应该还在

  3. 备份建议 升级前备份工作目录：

    cp -r ~/.copaw ~/.copaw.backup

第二部分：智能体间协作

智能体之间可以互相通信和协作，完成单个智能体难以完成的复杂任务。

什么是智能体协作？

多智能体协作（Multi-Agent Collaboration） 是一个内置技能，启用后，您的智能体可以：

  • 请求其他智能体的专业能力（如让代码智能体审查代码，让写作智能体润色文档）
  • 访问其他智能体的工作区数据（如读取另一个智能体的配置或文件）
  • 寻求第二意见或专业复核
  • 在用户明确要求时调用指定的智能体

如何启用协作功能？

方式一：在控制台中启用（推荐）

  1. 切换到需要启用协作的智能体
  2. 进入智能体 → 技能页面
  3. 找到 Multi-Agent Collaboration（多智能体协作） 技能
  4. 勾选启用
  5. 点击"保存"

方式二：使用 CLI 启用

# 为默认智能体启用
copaw skills config

# 为特定智能体启用
copaw skills config --agent-id abc123

# 在交互界面中：
# - 使用 ↑/↓ 键找到 "multi_agent_collaboration"
# - 按空格键勾选
# - 按回车键确认保存

协作如何触发？

启用协作技能后，智能体会在以下情况自动发起协作：

触发方式一：用户明确要求

用户在对话中直接要求调用其他智能体：

示例：

用户：请让代码助手帮我审查这段代码

当前智能体会：

  1. 识别到用户要求调用"代码助手"
  2. 查询可用智能体列表
  3. 向"代码助手"发送审查请求
  4. 等待"代码助手"返回结果
  5. 将结果整合后回复用户

触发方式二：智能体主动判断

智能体在处理任务时，如果判断需要其他智能体的专业能力，会主动发起协作：

示例：

用户：帮我生成一份技术文档并用专业语言润色

当前智能体的处理流程：
1. [生成技术文档初稿]
2. [判断：润色需要写作专长，调用写作助手]
3. [将初稿发送给写作助手]
4. [接收写作助手返回的润色版本]
5. [返回最终文档给用户]

使用场景示例

场景一：跨领域协作

用户：请分析我的项目结构并生成架构文档

流程：
1. 代码智能体分析项目结构
2. 代码智能体调用写作智能体
3. 写作智能体生成专业文档
4. 代码智能体返回最终结果

场景二：专业复核

用户：这段代码有什么问题？让资深助手也看看

流程：
1. 当前智能体先分析代码
2. 识别用户要求"资深助手"参与
3. 调用"资深助手"进行复核
4. 综合两方意见返回给用户

场景三：数据共享

用户：把财务智能体的月度报告发给我

流程：
1. 当前智能体识别需要"财务智能体"的数据
2. 向财务智能体请求月度报告
3. 接收报告数据
4. 格式化后发送给用户

协作的优势

  • 专业分工：每个智能体专注自己的领域，协作时发挥各自优势
  • 上下文隔离：不同智能体的对话历史互不干扰，避免混淆
  • 灵活组合：根据任务需要动态组合不同智能体的能力
  • 可扩展性：添加新智能体即可扩展整个系统的能力

智能体描述的重要性

为了让智能体间协作更有效，需要为每个智能体提供清晰的描述信息。

智能体如何识别彼此？

当智能体 A 需要与智能体 B 协作时，会先查询可用智能体列表。系统会读取并展示每个智能体的：

  • 名称（name）- 智能体的显示名称
  • ID（agent_id）- 唯一标识符
  • 描述（description）- 用户在创建智能体时填写的专长和用途说明
  • PROFILE.md（自动生成）- 系统根据智能体的配置自动生成的详细能力描述

如何填写描述？

在创建智能体时，描述字段应清晰说明：

✅ 好的描述示例：

专注于 Python/JavaScript 代码审查、重构和性能优化

负责文档撰写、内容润色和技术写作，擅长中英文双语

处理财务数据分析、报表生成和预算管理

❌ 不好的描述示例：

我的助手

测试用

（留空）

描述的关键要素：

  1. 明确的专长领域（如"代码审查"、"文档撰写"）
  2. 具体的技能范围（如"Python/JavaScript"、"中英文双语"）
  3. 擅长的任务类型（如"重构优化"、"数据分析"）

PROFILE.md 自动生成

系统会根据智能体的配置（包括名称、描述、技能、人设文件等）自动生成 PROFILE.md 文件，存放在工作区目录：

~/.copaw/workspaces/{agent_id}/PROFILE.md

您可以在智能体 → 工作区页面查看自动生成的 PROFILE.md。

查看智能体信息

使用 CLI 查看所有智能体的信息：

copaw agents list

# 输出示例：
# Agent ID: code_reviewer
# Name: 代码审查助手
# Description: 专注于 Python/JavaScript 代码审查、重构和性能优化
# Workspace: ~/.copaw/workspaces/code_reviewer
# Profile: [自动生成的详细能力描述]

智能体在协作时会综合参考 Description 和 PROFILE.md 来做出决策。

注意事项

  • 需要先启用 skill：协作功能需要显式启用"多智能体协作"技能
  • 填写清晰的描述：创建智能体时，在描述字段清晰说明其专长和擅长的任务类型
  • 系统自动生成 Profile：PROFILE.md 由系统自动生成，无需手动编写
  • 自动化处理：启用后，智能体会根据需要自动发起协作，用户无需手动操作
  • 性能考虑：协作涉及多个智能体，可能需要更多时间和 API 调用
  • 合理规划：建议根据实际需求创建 3-5 个智能体，避免过度复杂化

进阶：CLI 和 API

如果您不熟悉命令行或 API，可以跳过这部分。所有功能都可以在控制台中完成。

智能体协作相关 CLI

智能体在启用协作技能后，会在后台自动使用以下 CLI 命令：

查询可用智能体

copaw agents list

此命令会列出所有已配置的智能体，包括：

  • Agent ID：智能体的唯一标识
  • Name：智能体名称
  • Description：用户创建智能体时填写的专长和用途说明
  • Workspace：工作区路径
  • Profile：系统自动生成的 PROFILE.md 文件内容（如果存在）

示例输出：

Agent ID: code_reviewer
Name: 代码审查助手
Description: 专注于 Python/JavaScript 代码审查、重构和性能优化
Workspace: ~/.copaw/workspaces/code_reviewer
Profile: [自动生成的详细能力描述，基于配置和人设文件]

Agent ID: writer_bot
Name: 写作助手
Description: 负责文档撰写、内容润色和技术写作，擅长中英文双语
Workspace: ~/.copaw/workspaces/writer_bot
Profile: [自动生成的详细能力描述]

智能体在决定调用哪个智能体时，会综合参考 Description 和 Profile 来做出最佳选择。

与其他智能体通信

# 发起新对话
copaw agents chat \
  --from-agent <current_agent> \
  --to-agent <target_agent> \
  --text "请求内容"

# 多轮对话（保持上下文）
copaw agents chat \
  --from-agent <current_agent> \
  --to-agent <target_agent> \
  --session-id "<session_id>" \
  --text "继续请求"

说明：这些命令由智能体自动执行，通常无需用户手动调用。详见 CLI - 智能体。

智能体管理 CLI

所有支持多智能体的 CLI 命令都接受 --agent-id 参数（默认为 default）：

# 查看特定智能体的配置
copaw channels list --agent-id abc123
copaw cron list --agent-id abc123
copaw skills list --agent-id abc123

# 为特定智能体创建定时任务
copaw cron create \
  --agent-id abc123 \
  --type agent \
  --name "检查待办" \
  --cron "0 9 * * *" \
  --channel console \
  --target-user "user1" \
  --target-session "session1" \
  --text "我有什么待办事项？"

支持 --agent-id 的命令：

  • copaw channels - 频道管理
  • copaw cron - 定时任务
  • copaw daemon - 运行状态
  • copaw chats - 对话管理
  • copaw skills - 技能管理

不支持 --agent-id 的命令（全局操作）：

  • copaw init - 初始化
  • copaw providers - 模型提供商
  • copaw models - 模型配置
  • copaw env - 环境变量

REST API

智能体管理 API

端点 方法 说明
/api/agents GET 列出所有智能体
/api/agents POST 创建新智能体
/api/agents/{agent_id} GET 获取智能体详情
/api/agents/{agent_id} PUT 更新智能体配置
/api/agents/{agent_id} DELETE 删除智能体
/api/agents/{agent_id}/active POST 激活智能体

智能体专属 API

所有智能体专属的 API 都支持 X-Agent-Id HTTP 头：

# 获取特定智能体的对话列表
curl -H "X-Agent-Id: abc123" http://localhost:7860/api/chats

# 为特定智能体创建定时任务
curl -X POST http://localhost:7860/api/cron/jobs \
  -H "X-Agent-Id: abc123" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

支持 X-Agent-Id 的 API 端点：

  • /api/chats/* - 对话管理
  • /api/cron/* - 定时任务
  • /api/config/* - 频道和心跳配置
  • /api/skills/* - 技能管理
  • /api/tools/* - 工具管理
  • /api/mcp/* - MCP 客户端管理
  • /api/agent/* - 工作区文件和记忆

配置文件结构

如果您需要直接编辑配置文件：

旧结构（v0.0.x）

~/.copaw/
├── config.json          # 包含所有配置
├── chats.json
├── jobs.json
├── AGENTS.md
└── ...

新结构（v0.1.0+）

~/.copaw/
├── config.json          # 全局配置（providers, agents.profiles）
└── workspaces/
    ├── default/         # 默认智能体工作区
    │   ├── agent.json   # 智能体专属配置
    │   ├── chats.json
    │   ├── jobs.json
    │   ├── AGENTS.md
    │   └── ...
    └── abc123/          # 其他智能体
        └── ...

最佳实践

合理规划智能体数量

✅ 推荐：3-5 个智能体，按主要功能或平台分类 ❌ 不推荐：为每个小功能都创建智能体

过多智能体会增加管理复杂度，得不偿失。

使用清晰的名称

✅ 好的命名：

  • default - 默认智能体
  • work-assistant - 工作助手
  • code-reviewer - 代码审查助手

❌ 不好的命名：

  • abc123 - 无意义的随机字符
  • test1, test2 - 不清楚用途

定期备份

重要智能体的工作区建议定期备份：

# 备份特定智能体
cp -r ~/.copaw/workspaces/abc123 ~/backups/agent-abc123-$(date +%Y%m%d)

# 备份所有智能体
cp -r ~/.copaw/workspaces ~/backups/workspaces-$(date +%Y%m%d)

相关页面