基于 CoPaw 与 Crush 深度对比分析的多Agents架构演进蓝图

版本: 1.0
日期: 2026-04-12

目录

1. 执行摘要
2. CoPaw 架构深度分析
3. Crush 架构深度分析
4. 架构对比分析
5. Crush 可学习改进方向
6. 详细演进方案
7. 实施路线图

执行摘要

本方案基于对 CoPaw (AgentScope生态的个人AI助手) 和 Crush (Charmbracelet的终端AI编程助手) 两个项目的深度架构分析，识别出 Crush 在多Agents架构方面可以借鉴和改进的方向。

核心发现：

演进重点：

1. 构建真正的多Agent运行时 (而非仅Subagent委派)
2. 完善Agent生命周期与热重载
3. 建立Agent间协作与消息路由
4. 强化Workspace隔离模型

CoPaw 架构深度分析

2.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                        CoPaw Application                         │
├─────────────────────────────────────────────────────────────────┤
│  Channel Layer (DingTalk/Feishu/Discord/Telegram/Console...)    │
├─────────────────────────────────────────────────────────────────┤
│  MultiAgentManager                                               │
│  ├── Workspace (Agent Instance Container)                       │
│  │   ├── CoPawAgent (ReActAgent + Tools + Skills)              │
│  │   ├── MemoryManager (InMemory + Long-term)                  │
│  │   ├── SkillManager (Workspace-scoped skills)                │
│  │   └── TaskTracker (Background tasks)                        │
│  ├── ServiceManager (Shared services across workspaces)        │
│  └── Router (Message routing between agents)                   │
├─────────────────────────────────────────────────────────────────┤
│  Skills Hub (Global skill pool + manifest)                      │
├─────────────────────────────────────────────────────────────────┤
│  Security Layer (ToolGuard + SkillScanner + Approval)           │
└─────────────────────────────────────────────────────────────────┘

2.2 核心组件详解

2.2.1 MultiAgentManager

文件: src/copaw/app/multi_agent_manager.py

class MultiAgentManager:
    """Manages multiple agent workspaces.
    
    Features:
    - Lazy loading: Workspaces created only when first requested
    - Lifecycle management: Start, stop, reload workspaces
    - Thread-safe: Uses async lock for concurrent access
    - Hot reload: Reload individual workspaces without affecting others
    """

关键能力：

2.2.2 Workspace 模型

文件: src/copaw/app/workspace/workspace.py

Workspace 是 Agent 的运行时容器：

class Workspace:
    """Encapsulates a complete agent environment.
    
    Includes:
    - Agent instance (CoPawAgent)
    - Service manager (shared/reusable services)
    - Task tracker (background task management)
    - Workspace-scoped configuration
    """

关键设计：

• 隔离性: 每个 Workspace 有独立的工作目录、配置、记忆
• 可复用组件: ServiceManager 支持跨 Workspace 共享连接池等资源
• 热重载支持: Workspace 可被重新加载而不影响其他 Agent

2.2.3 CoPawAgent (ReActAgent 扩展)

文件: src/copaw/agents/react_agent.py

class CoPawAgent(ToolGuardMixin, ReActAgent):
    """CoPaw Agent with integrated tools, skills, and memory.
    
    Extension points:
    - ToolGuardMixin: Security interception
    - Built-in tools: shell, file, browser, etc.
    - Dynamic skill loading
    - Memory management with auto-compaction
    - Bootstrap guidance
    """

Hook 系统：

# Pre-reasoning hooks
- bootstrap_hook: 首次交互检查
- memory_compact_hook: 上下文压缩

# Tool execution (via ToolGuardMixin)
- Pre-tool validation
- Post-tool processing

2.2.4 技能系统 (Skills Hub)

文件: src/copaw/agents/skills_manager.py

Skill Pool (Global)
├── builtin/          (打包内置)
├── imported/         (用户导入)
└── manifest.json     (统一元数据)

Workspace Skills
├── skills/           (工作区技能)
├── skill.json        (工作区manifest)
└── Channel routing   (按渠道路由)

关键特性：

• 技能签名: SHA256 内容哈希用于冲突检测
• 渠道路由: 不同渠道可配置不同技能集
• 环境注入: 技能配置自动注入环境变量
• 安全扫描: 自动技能代码扫描

2.3 Agent 协作机制

CoPaw 的"多Agent"实际上是多Workspace模型：

User Message
    ↓
Channel Router
    ↓
MultiAgentManager.get_agent(agent_id)
    ↓
Workspace (独立的Agent实例)
    ↓
CoPawAgent.reply()

协作模式：

1. 独立模式: 每个 Agent 完全独立，无直接通信
2. 共享服务模式: 通过 ServiceManager 共享资源
3. 技能共享: 通过 Skills Hub 共享技能定义

2.4 安全架构

┌────────────────────────────────────────┐
│         Security Layers                │
├────────────────────────────────────────┤
│ 1. ToolGuardMixin                      │
│    ├── Pre-tool validation             │
│    ├── File access control             │
│    └── Command filtering               │
├────────────────────────────────────────┤
│ 2. SkillScanner                        │
│    ├── Pattern-based analysis          │
│    ├── Dangerous code detection        │
│    └── Policy enforcement              │
├────────────────────────────────────────┤
│ 3. Approval Service                    │
│    ├── User confirmation               │
│    ├── Risk assessment                 │
│    └── Audit logging                   │
└────────────────────────────────────────┘

Crush 架构深度分析

3.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                        Crush Application                         │
├─────────────────────────────────────────────────────────────────┤
│  UI Layer (Bubble Tea TUI)                                       │
│  ├── Chat Interface                                              │
│  ├── Subagent Progress Display                                   │
│  └── Slash Commands                                              │
├─────────────────────────────────────────────────────────────────┤
│  AgentCoordinator                                                │
│  ├── SessionAgent (Main conversation handler)                   │
│  ├── SubagentExecutor (Deer-Flow style)                         │
│  │   ├── Worker Pool (Goroutine-based)                          │
│  │   ├── Registry (Agent type definitions)                      │
│  │   └── Middleware (Loop detection, etc.)                      │
│  ├── TeamService (Basic team management)                        │
│  ├── TaskService (Task lifecycle)                               │
│  └── WorkflowEngine (Multi-step workflows)                      │
├─────────────────────────────────────────────────────────────────┤
│  Services                                                        │
│  ├── Session/Memory/Message (SQLite + sqlc)                     │
│  ├── Permission v2 (Rule engine)                                │
│  ├── SkillManager (Auto-reload)                                 │
│  ├── HookManager (Event hooks)                                  │
│  ├── PluginRegistry                                             │
│  └── MCP Manager                                                │
└─────────────────────────────────────────────────────────────────┘

3.2 核心组件详解

3.2.1 AgentCoordinator

文件: internal/agent/coordinator.go

type coordinator struct {
    // Core services
    cfg           *config.ConfigStore
    sessions      session.Service
    messages      message.Service
    permissions   permission.Service
    
    // Agent management
    currentAgent SessionAgent
    agents       map[string]SessionAgent  // Named agents
    
    // Subagent system (Deer-Flow style)
    subagentExecutor subagent.Executor
    subagentRegistry *subagent.Registry
    subagentContext  *subagent.Extractor
    
    // Additional services
    teamService   *team.Service
    scheduler     *scheduler.Scheduler
    skillManager  prompt.SkillManagerInterface
}

关键能力：

3.2.2 Subagent 系统

文件: internal/agent/subagent/*.go

// Deer-Flow style execution
subagent/
├── types.go              # 核心类型定义
├── executor.go           # 执行器 (Worker Pool)
├── registry.go           # Agent类型注册表
├── worker_pool.go        # Goroutine工作池
├── middleware.go         # 中间件链
├── parent_context.go     # 父上下文提取
└── runner.go             # AgentRunner接口

内置 Subagent 类型：

执行模型：

Coordinator
    ↓ ExecuteAsync
SubagentExecutor
    ↓ Submit
WorkerPool (max_workers=3)
    ↓ Goroutine
SubagentRunner
    ↓ LLM Execution
Result Store

3.2.3 Team 服务

文件: internal/agent/team/service.go

// Basic team management - structure only
type Service struct {
    mu     sync.RWMutex
    teams  map[string]*Team      // key: team ID
    byName map[string]string     // key: team name
}

type Team struct {
    ID          string
    Name        string
    Description string
    AgentIDs    []string          // Just IDs, no actual agent references
}

现状： Team 服务目前只是元数据管理，没有实际的 Agent 运行时关联。

3.2.4 Workflow 引擎

文件: internal/agent/workflow/engine.go

type Engine struct {
    workflows  *csync.Map[string, *Workflow]
    executions *csync.Map[string, *Execution]
    broker     *pubsub.Broker[Event]
    handlers   map[StepType]StepHandler
}

// Step types: action, condition, parallel, loop, wait, input

状态： 已实现但可能未完全接入主流程。

3.3 当前多Agent能力评估

实际多Agent能力:
├── ✅ SessionAgent (主对话Agent)
├── ✅ Subagent (委派型子Agent)
│   ├── 异步执行
│   ├── Worker Pool 并发控制
│   └── 结果存储
├── ⚠️ Team (元数据管理，无运行时)
├── ⚠️ Workflow (引擎存在，链路待完善)
└── ❌ True Multi-Agent (独立Agent并行运行)

架构对比分析

4.1 多Agent模型对比

4.2 协作机制对比

4.3 扩展性对比

4.4 Crush 的优势 (CoPaw 可学习)

1. Subagent 执行引擎

   • Deer-Flow 风格的 Worker Pool
   • 中间件系统 (LoopDetection, TokenUsage, Timeout)
   • 更精细的并发控制

2. 权限系统 v2

   • 基于规则的引擎
   • 条件、时间窗口、速率限制
   • Audit 日志

3. Git Worktree 隔离

   • 子代理文件隔离
   • 自动提交/回滚

4. TUI 体验

   • Bubble Tea 专业交互
   • 实时进度显示
   • 富文本渲染

Crush 可学习改进方向

5.1 高优先级 (P0)

5.1.1 构建真正的多Agent运行时

问题： Crush 目前只有 Subagent (委派模式)，缺乏独立运行的多Agent能力。

方案：

// 新增 AgentWorkspace 概念
package workspace

type Workspace struct {
    ID      string
    Agent   agent.SessionAgent
    Config  *AgentConfig
    
    // 隔离资源
    Memory  memory.Service
    History history.Service
    
    // 生命周期
    ctx     context.Context
    cancel  context.CancelFunc
    status  WorkspaceStatus
}

type Manager struct {
    workspaces map[string]*Workspace
    mu         sync.RWMutex
    
    // 共享服务 (从 CoPaw 学习)
    sharedServices *SharedServiceManager
}

关键特性：

1. 每个 Workspace 有独立的 SQLite 连接/事务
2. 懒加载 + 超时释放
3. 热重载支持 (借鉴 CoPaw 的零停机更新)

5.1.2 完善 Team 服务为运行时

当前： Team 只是元数据存储
目标： Team = 协作的 Agent 组

// 扩展现有 Team 服务
type TeamRuntime struct {
    Team      *Team
    Workspaces map[string]*workspace.Workspace  // AgentID -> Workspace
    
    // 协作机制
    Router    MessageRouter
    SharedContext *SharedContext
}

5.2 中优先级 (P1)

5.2.1 Agent 间消息路由

package router

type MessageRouter interface {
    // 发送消息给特定Agent
    Send(toAgentID string, msg Message) error
    
    // 广播给Team所有成员
    Broadcast(teamID string, msg Message) error
    
    // 请求-响应模式
    Request(fromAgentID, toAgentID string, req Request) (Response, error)
}

5.2.2 服务共享管理器 (借鉴 CoPaw)

package services

type SharedServiceManager struct {
    // 可共享的服务实例
    lspManager    *lsp.Manager      // LSP 连接池
    mcpClients    []mcp.Client      // MCP 连接
    skillManager  *skills.Manager   // 技能缓存
    
    // 引用计数
    refs map[string]int
}

func (s *SharedServiceManager) Acquire(serviceName string) (interface{}, error)
func (s *SharedServiceManager) Release(serviceName string)

5.2.3 零停机 Agent 重载

借鉴 CoPaw 的实现：

func (m *Manager) Reload(agentID string) error {
    // 1. 创建新 Workspace (无锁)
    newWS, err := m.createWorkspace(agentID)
    if err != nil {
        return err
    }
    
    // 2. 原子替换 (持锁)
    m.mu.Lock()
    oldWS := m.workspaces[agentID]
    m.workspaces[agentID] = newWS
    m.mu.Unlock()
    
    // 3. 优雅停止旧 Workspace (无锁)
    go m.gracefulStop(oldWS)
    
    return nil
}

5.3 低优先级 (P2)

5.3.1 技能系统增强

• 技能池 (Skill Pool) 全局管理
• 技能签名与版本控制
• 渠道路由 (Channel-based routing)

5.3.2 安全增强

• ToolGuard 模式 (借鉴 CoPaw)
• 技能代码静态扫描
• 敏感信息检测

详细演进方案

6.1 阶段一: Workspace 运行时 (P0)

6.1.1 目标

建立独立的 Agent Workspace 运行时，支持多 Agent 并行运行。

6.1.2 架构设计

internal/agent/workspace/
├── workspace.go        # Workspace 定义与生命周期
├── manager.go          # Workspace 管理器
├── lifecycle.go        # 启动/停止/重载逻辑
├── isolation.go        # 资源隔离 (DB, FS)
└── shared/             # 共享服务
    ├── service_manager.go
    └── refs.go

6.1.3 核心接口

// workspace.go
package workspace

type Workspace struct {
    ID        string
    AgentID   string
    
    // 核心组件
    Agent     agent.SessionAgent
    Config    *config.AgentConfig
    
    // 隔离的服务实例
    Services  *IsolatedServices
    
    // 状态
    status    Status
    ctx       context.Context
    cancel    context.CancelFunc
}

type IsolatedServices struct {
    Session   session.Service
    Messages  message.Service
    History   history.Service
    Memory    *memory.SessionMemoryManager
}

func (w *Workspace) Start() error
func (w *Workspace) Stop(graceful bool) error
func (w *Workspace) Reload() error
func (w *Workspace) Status() Status

6.1.4 与现有系统的集成

// 扩展 Coordinator
type Coordinator interface {
    // 现有方法...
    
    // 新增 Workspace 管理
    GetWorkspace(agentID string) (*workspace.Workspace, error)
    CreateWorkspace(config *AgentConfig) (*workspace.Workspace, error)
    RemoveWorkspace(agentID string) error
    ReloadWorkspace(agentID string) error
    ListWorkspaces() []*workspace.Workspace
}

6.2 阶段二: Team 运行时 (P0-P1)

6.2.1 扩展现有 Team 服务

// internal/agent/team/runtime.go
package team

type Runtime struct {
    Team    *Team
    Manager *workspace.Manager
    
    // 成员 Workspace 引用
    workspaces map[string]*workspace.Workspace
    
    // 协作设施
    Router     *MessageRouter
    SharedMem  *SharedMemory
}

func (r *Runtime) Start() error {
    // 启动所有成员 Workspace
    for _, agentID := range r.Team.AgentIDs {
        ws, err := r.Manager.GetOrCreate(agentID)
        if err != nil {
            return err
        }
        r.workspaces[agentID] = ws
    }
    return nil
}

func (r *Runtime) Dispatch(fromAgentID string, task Task) error {
    // 根据策略选择目标 Agent
    targetID := r.selectAgent(task)
    return r.Router.Send(targetID, task)
}

6.2.2 协作模式支持

type CollaborationMode int

const (
    ModeIndependent CollaborationMode = iota  // 独立运行
    ModeLeaderFollower                         // 主从协作
    ModeRoundRobin                             // 轮询分发
    ModeBroadcast                              // 广播
)

6.3 阶段三: 消息路由系统 (P1)

package router

type Router struct {
    // 本地路由表
    localRoutes map[string]*workspace.Workspace
    
    // 消息队列
    queues map[string]chan Message
    
    // 订阅管理
    subs map[string][]Subscription
}

func (r *Router) Register(agentID string, ws *workspace.Workspace) {
    r.localRoutes[agentID] = ws
    r.queues[agentID] = make(chan Message, 100)
    
    // 启动分发 Goroutine
    go r.dispatchLoop(agentID)
}

func (r *Router) Route(msg Message) error {
    if msg.To != "" {
        // 点对点
        return r.sendDirect(msg.To, msg)
    }
    if msg.Team != "" {
        // 团队广播
        return r.broadcast(msg.Team, msg)
    }
    return fmt.Errorf("no destination")
}

6.4 阶段四: 共享服务管理 (P1)

package shared

// 可共享的服务类型
type Sharable interface {
    ID() string
    RefCount() int
    Acquire() error
    Release() error
}

type Manager struct {
    services map[string]Sharable
    mu       sync.RWMutex
}

func (m *Manager) Register(s Sharable) {
    m.mu.Lock()
    defer m.mu.Unlock()
    m.services[s.ID()] = s
}

func (m *Manager) Get(id string) (Sharable, error) {
    m.mu.RLock()
    defer m.mu.RUnlock()
    
    s, ok := m.services[id]
    if !ok {
        return nil, fmt.Errorf("service not found: %s", id)
    }
    
    if err := s.Acquire(); err != nil {
        return nil, err
    }
    
    return s, nil
}

实施路线图

7.1 时间规划

2026 Q2 (4-6月)
├── Week 1-2: Workspace 核心框架
│   ├── Workspace 类型定义
│   ├── Manager 实现
│   └── 基础生命周期管理
├── Week 3-4: 资源隔离
│   ├── SQLite 隔离
│   ├── 文件系统隔离
│   └── 配置隔离
└── Week 5-6: 与 Coordinator 集成
    ├── API 设计
    ├── 事件传播
    └── 测试覆盖

2026 Q3 (7-9月)
├── Week 1-2: Team 运行时改造
│   ├── Runtime 结构
│   ├── 成员管理
│   └── 状态同步
├── Week 3-4: 消息路由系统
│   ├── Router 核心
│   ├── 消息队列
│   └── 错误处理
├── Week 5-6: 共享服务管理
│   ├── Sharable 接口
│   ├── LSP 共享
│   └── MCP 共享
└── Week 7-8: 零停机重载
    ├── 双实例管理
    ├── 优雅切换
    └── 资源清理

2026 Q4 (10-12月)
├── Week 1-2: 协作模式
├── Week 3-4: UI 集成
├── Week 5-6: 性能优化
└── Week 7-8: 文档与示例

7.2 关键里程碑

7.3 风险与缓解

附录

A. 参考实现代码

A.1 Workspace 创建流程

func (m *Manager) Create(agentID string, cfg *Config) (*Workspace, error) {
    ctx, cancel := context.WithCancel(m.ctx)
    
    ws := &Workspace{
        ID:      uuid.New().String(),
        AgentID: agentID,
        Config:  cfg,
        ctx:     ctx,
        cancel:  cancel,
        status:  StatusCreating,
    }
    
    // 1. 创建隔离的 SQLite 连接
    dbPath := filepath.Join(cfg.WorkDir, "workspace.db")
    conn, err := sql.Open("sqlite3", dbPath)
    if err != nil {
        cancel()
        return nil, err
    }
    
    // 2. 创建隔离的服务
    ws.Services = &IsolatedServices{
        Session:  session.NewService(db.New(conn), conn),
        Messages: message.NewService(db.New(conn)),
        History:  history.NewService(db.New(conn), conn),
    }
    
    // 3. 创建 Agent
    ws.Agent, err = m.agentBuilder.Build(agentID, cfg, ws.Services)
    if err != nil {
        conn.Close()
        cancel()
        return nil, err
    }
    
    // 4. 注册到路由
    m.router.Register(agentID, ws)
    
    ws.status = StatusRunning
    return ws, nil
}

A.2 热重载实现

func (m *Manager) Reload(agentID string) error {
    // Phase 1: 创建新实例 (无锁)
    oldWS, err := m.getWorkspace(agentID)
    if err != nil {
        return err
    }
    
    // 复制配置并更新
    newCfg := oldWS.Config.Clone()
    newCfg.Version++
    
    newWS, err := m.Create(agentID+"-new", newCfg)
    if err != nil {
        return fmt.Errorf("create new workspace: %w", err)
    }
    
    // Phase 2: 原子切换 (持锁)
    m.mu.Lock()
    m.workspaces[agentID] = newWS
    m.mu.Unlock()
    
    // Phase 3: 优雅停止旧实例 (后台)
    go m.gracefulStop(oldWS, 60*time.Second)
    
    return nil
}

B. 术语对照

文档结束

本方案基于对 CoPaw v1.0.2 和 Crush (main@2026-04-12) 的源码分析。
建议每季度回顾并更新方案以匹配最新实现。