统一 Agent 架构设计文档

// 当前：SubAgent 通过函数调用，返回纯 string
result, err := ctx.Manager.RunSubAgent(parentCtx, task, systemPrompt, allowedTools)
// result 是 string，丢失了所有元信息（channel、sender、media 等）

// bus/bus.go

// InboundMessage 统一的入站消息。
// 来源可以是 IM 渠道（feishu/qq/cli）或其他 Agent（agent 内部调用）。
type InboundMessage struct {
    // === 路由 ===
    Channel    string            // 消息来源: "feishu", "qq", "cli", "agent"
    SenderID   string            // 发送者标识（IM 用户 ID 或父 Agent ID）
    SenderName string            // 发送者姓名
    ChatID     string            // 会话标识（IM 群组 ID 或 Agent 会话 ID）
    ChatType   string            // "p2p" / "group" / "agent"

    // === 内容 ===
    Content    string            // 消息文本
    Media      []string          // 媒体文件路径/URL

    // === 元数据 ===
    Metadata   map[string]string // 渠道/调用方特定元数据
    Time       time.Time
    RequestID  string            // 请求追踪 ID

    // === 调度标记 ===
    IsCron     bool              // 是否由 cron 定时任务触发

    // === Agent 间通信扩展 ===
    ParentAgentID string         // 父 Agent ID（仅 channel="agent" 时有值）
    SystemPrompt  string         // 覆盖 system prompt（仅 channel="agent" 时有值）
    AllowedTools  []string       // 工具白名单（仅 channel="agent" 时有值，空=全部）
    RoleName      string         // SubAgent 角色名（仅 channel="agent" 时有值）
}

// IsFromAgent 判断消息是否来自其他 Agent（而非 IM 渠道）
func (m *InboundMessage) IsFromAgent() bool {
    return m.Channel == "agent"
}

// OriginChannel 获取原始 IM 渠道（Agent 间调用时从 Metadata 继承）
func (m *InboundMessage) OriginChannel() string {
    if m.Channel == "agent" {
        if ch, ok := m.Metadata["origin_channel"]; ok {
            return ch
        }
    }
    return m.Channel
}

// OriginChatID 获取原始 IM 会话 ID
func (m *InboundMessage) OriginChatID() string {
    if m.Channel == "agent" {
        if id, ok := m.Metadata["origin_chat_id"]; ok {
            return id
        }
    }
    return m.ChatID
}

// OriginSenderID 获取原始 IM 发送者 ID
func (m *InboundMessage) OriginSenderID() string {
    if m.Channel == "agent" {
        if id, ok := m.Metadata["origin_sender"]; ok {
            return id
        }
    }
    return m.SenderID
}

// OutboundMessage 统一的出站消息。
// 目标可以是 IM 渠道或调用方 Agent。
type OutboundMessage struct {
    // === 路由 ===
    Channel  string            // 目标渠道: "feishu", "qq", "agent"
    ChatID   string            // 目标会话

    // === 内容 ===
    Content  string            // 消息文本
    Media    []string          // 附件文件路径

    // === 元数据 ===
    Metadata map[string]string // 附加元数据

    // === Agent 间通信扩展 ===
    ToolsUsed   []string       // 使用过的工具列表（SubAgent 返回时携带）
    WaitingUser bool           // 是否等待用户响应
    Error       error          // 执行错误（SubAgent 返回时携带）
}

// agent/engine.go

// RunConfig 统一的 Agent 运行配置。
// 主 Agent 和 SubAgent 使用同一个 Run() 方法，差异通过配置注入。
type RunConfig struct {
    // === 必需 ===
    LLMClient llm.LLM
    Model     string
    Tools     *tools.Registry
    Messages  []llm.ChatMessage

    // === 身份（从 InboundMessage 提取） ===
    AgentID    string // "main", "main/code-reviewer"
    Channel    string // 原始 IM 渠道（用于 ToolContext）
    ChatID     string // 原始 IM 会话
    SenderID   string // 原始发送者
    SenderName string

    // === 循环控制 ===
    MaxIterations int // 0 = 使用默认值 100

    // === 可选能力（nil = 不启用） ===

    // Session 持久化（nil = 纯内存，不持久化）
    Session *session.TenantSession

    // SessionKey 工具激活的 session key（为空时从 Channel+ChatID 生成）
    SessionKey string

    // ProgressNotifier 进度通知回调（nil = 不通知）
    ProgressNotifier func(lines []string)

    // AutoCompress 自动上下文压缩配置（nil = 不压缩）
    AutoCompress *CompressConfig

    // SendFunc 向 IM 渠道发送消息（nil = 不能发消息）
    SendFunc func(channel, chatID, content string) error

    // Memory 记忆提供者（nil = 无记忆）
    Memory memory.MemoryProvider

    // ToolContextExtras 额外的 ToolContext 字段注入
    ToolContextExtras *ToolContextExtras

    // SpawnAgent SubAgent 创建能力（nil = 不能创建子 Agent）
    // 输入输出都是统一消息：InboundMessage → OutboundMessage
    SpawnAgent func(ctx context.Context, msg bus.InboundMessage) (*bus.OutboundMessage, error)

    // OAuthHandler OAuth 自动触发处理器（nil = 不处理 OAuth）
    OAuthHandler func(ctx context.Context, tc llm.ToolCall, execErr error) (content string, handled bool)
}

// CompressConfig 自动压缩配置
type CompressConfig struct {
    MaxContextTokens     int
    CompressionThreshold float64
    CompressFunc         func(ctx context.Context, messages []llm.ChatMessage, model string) ([]llm.ChatMessage, error)
}

// ToolContextExtras Letta 记忆相关的 ToolContext 扩展字段
type ToolContextExtras struct {
    TenantID              int64
    CoreMemory            *sqlite.CoreMemoryService
    ArchivalMemory        *vectordb.ArchivalService
    MemorySvc             *sqlite.MemoryService
    RecallTimeRange       vectordb.RecallTimeRangeFunc
    ToolIndexer           memory.ToolIndexer
    InjectInbound         func(channel, chatID, senderID, content string)
    Registry              *tools.Registry
    InvalidateAllSessionMCP func()
}

// agent/engine.go（新文件，从 agent.go 提取）

// Run 统一的 Agent 循环。
// 输入：RunConfig（从 InboundMessage 构建）
// 输出：OutboundMessage（可直接发送到 IM 或返回给父 Agent）
func Run(ctx context.Context, cfg RunConfig) *bus.OutboundMessage {
    maxIter := cfg.MaxIterations
    if maxIter == 0 {
        maxIter = 100
    }
    sessionKey := cfg.SessionKey
    if sessionKey == "" && cfg.Channel != "" {
        sessionKey = cfg.Channel + ":" + cfg.ChatID
    }
    messages := cfg.Messages

    var toolsUsed []string
    var waitingUser bool
    var progressLines []string

    // 进度通知
    notifyProgress := func(extra string) {
        if cfg.ProgressNotifier == nil {
            return
        }
        lines := progressLines
        if extra != "" {
            lines = append(append([]string{}, progressLines...), extra)
        }
        cfg.ProgressNotifier(lines)
    }

    // 自动压缩
    maybeCompress := func() {
        if cfg.AutoCompress == nil || len(messages) <= 3 {
            return
        }
        // ... 与当前 runLoop 中的 maybeCompress 逻辑相同
    }

    // 工具激活 tick
    if sessionKey != "" {
        cfg.Tools.TickSession(sessionKey)
    }

    // 主循环
    for i := 0; i < maxIter; i++ {
        maybeCompress()

        if cfg.ProgressNotifier != nil && i > 0 {
            notifyProgress("> 💭 思考中...")
        }

        toolDefs := cfg.Tools.AsDefinitionsForSession(sessionKey)
        response, err := cfg.LLMClient.Generate(ctx, cfg.Model, messages, toolDefs)
        if err != nil {
            if ctx.Err() != nil {
                return &bus.OutboundMessage{
                    Channel: cfg.Channel, ChatID: cfg.ChatID,
                    Content: "Agent was cancelled.", Error: ctx.Err(),
                    ToolsUsed: toolsUsed,
                }
            }
            return &bus.OutboundMessage{
                Channel: cfg.Channel, ChatID: cfg.ChatID,
                Error: fmt.Errorf("%w: %w", ErrLLMGenerate, err),
                ToolsUsed: toolsUsed,
            }
        }

        if !response.HasToolCalls() {
            return &bus.OutboundMessage{
                Channel: cfg.Channel, ChatID: cfg.ChatID,
                Content:     llm.StripThinkBlocks(response.Content),
                ToolsUsed:   toolsUsed,
                WaitingUser: waitingUser,
            }
        }

        // ... tool call 处理（读写分离并行、OAuth、进度通知）
        // 与当前 runLoop 逻辑相同，但通过 cfg 字段控制差异
    }

    return &bus.OutboundMessage{
        Channel: cfg.Channel, ChatID: cfg.ChatID,
        Content:   "已达到最大迭代次数，请重新描述你的需求。",
        ToolsUsed: toolsUsed,
    }
}

// buildToolContext 统一构建 ToolContext
func buildToolContext(ctx context.Context, cfg *RunConfig) *tools.ToolContext {
    tc := &tools.ToolContext{
        Ctx:        ctx,
        AgentID:    cfg.AgentID,
        Channel:    cfg.Channel,
        ChatID:     cfg.ChatID,
        SenderID:   cfg.SenderID,
        SenderName: cfg.SenderName,
        SendFunc:   cfg.SendFunc,
    }

    // 注入 SpawnAgent（包装为 SubAgentManager 接口）
    if cfg.SpawnAgent != nil {
        tc.Manager = &spawnAgentAdapter{
            spawnFn:  cfg.SpawnAgent,
            parentID: cfg.AgentID,
            channel:  cfg.Channel,
            chatID:   cfg.ChatID,
            senderID: cfg.SenderID,
        }
    }

    // 注入 Letta 记忆字段
    if ext := cfg.ToolContextExtras; ext != nil {
        tc.TenantID = ext.TenantID
        tc.CoreMemory = ext.CoreMemory
        tc.ArchivalMemory = ext.ArchivalMemory
        tc.MemorySvc = ext.MemorySvc
        tc.RecallTimeRange = ext.RecallTimeRange
        tc.ToolIndexer = ext.ToolIndexer
        tc.InjectInbound = ext.InjectInbound
        tc.Registry = ext.Registry
        tc.InvalidateAllSessionMCP = ext.InvalidateAllSessionMCP
    }

    return tc
}

// spawnAgentAdapter 将 SpawnAgent 函数适配为 SubAgentManager 接口。
// 核心职责：将 (task, prompt, tools) 函数签名转换为统一的 InboundMessage。
type spawnAgentAdapter struct {
    spawnFn  func(ctx context.Context, msg bus.InboundMessage) (*bus.OutboundMessage, error)
    parentID string
    channel  string
    chatID   string
    senderID string
}

func (a *spawnAgentAdapter) RunSubAgent(parentCtx *tools.ToolContext, task string, systemPrompt string, allowedTools []string) (string, error) {
    // 构造统一的 InboundMessage
    msg := bus.InboundMessage{
        Channel:       "agent",
        Content:       task,
        SenderID:      parentCtx.SenderID,
        SenderName:    parentCtx.SenderName,
        ChatID:        parentCtx.ChatID,
        ChatType:      "agent",
        ParentAgentID: a.parentID,
        SystemPrompt:  systemPrompt,
        AllowedTools:  allowedTools,
        Time:          time.Now(),
        Metadata: map[string]string{
            "origin_channel": a.channel,
            "origin_chat_id": a.chatID,
            "origin_sender":  a.senderID,
        },
    }

    out, err := a.spawnFn(parentCtx.Ctx, msg)
    if err != nil {
        return "", err
    }
    if out.Error != nil {
        return out.Content, out.Error
    }
    return out.Content, nil
}

// agent/agent.go

func (a *Agent) processMessage(ctx context.Context, msg bus.InboundMessage) (*bus.OutboundMessage, error) {
    // ... 现有的前置逻辑（requestID、session、command 匹配等）不变

    // 构建 LLM 消息
    messages, err := a.buildPrompt(ctx, msg, tenantSession)
    if err != nil {
        return nil, err
    }

    // 构建 RunConfig（从 InboundMessage 提取路由信息）
    llmClient, model := a.llmFactory.GetLLM(msg.SenderID)
    sessionKey := msg.Channel + ":" + msg.ChatID

    cfg := RunConfig{
        LLMClient:     llmClient,
        Model:         model,
        Tools:         a.tools,
        Messages:      messages,
        AgentID:       "main",
        Channel:       msg.Channel,
        ChatID:        msg.ChatID,
        SenderID:      msg.SenderID,
        SenderName:    msg.SenderName,
        MaxIterations: a.maxIterations,
        Session:       tenantSession,
        SessionKey:    sessionKey,
        SendFunc:      a.sendMessage,
        ToolContextExtras: a.buildToolContextExtras(ctx, msg, tenantSession),
    }

    // SpawnAgent：接收 InboundMessage，返回 OutboundMessage
    cfg.SpawnAgent = func(ctx context.Context, subMsg bus.InboundMessage) (*bus.OutboundMessage, error) {
        return a.handleSubAgentMessage(ctx, subMsg)
    }

    // 进度通知
    if preReplyNotify {
        cfg.ProgressNotifier = func(lines []string) {
            _ = a.sendMessage(msg.Channel, msg.ChatID, formatProgressLines(lines))
        }
    }

    // 自动压缩
    if a.enableAutoCompress {
        cfg.AutoCompress = &CompressConfig{
            MaxContextTokens:     a.maxContextTokens,
            CompressionThreshold: a.compressionThreshold,
            CompressFunc:         a.compressContext,
        }
    }

    // 运行统一引擎
    out := Run(ctx, cfg)

    // 后处理（保存会话、发送回复、添加 reaction）
    // ... 从 out.Content / out.ToolsUsed / out.WaitingUser / out.Error 提取结果
    return out, out.Error
}

// agent/agent.go

// handleSubAgentMessage 处理来自其他 Agent 的消息（统一入口）
func (a *Agent) handleSubAgentMessage(ctx context.Context, msg bus.InboundMessage) (*bus.OutboundMessage, error) {
    // 1. 从 InboundMessage 提取 SubAgent 配置
    roleName := msg.RoleName
    parentAgentID := msg.ParentAgentID
    task := msg.Content
    systemPrompt := msg.SystemPrompt
    allowedTools := msg.AllowedTools

    // 2. 工具集准备
    subTools := a.tools.Clone()
    subTools.Unregister("SubAgent")
    if len(allowedTools) > 0 {
        allowed := make(map[string]bool, len(allowedTools))
        for _, name := range allowedTools {
            allowed[name] = true
        }
        for _, tool := range subTools.List() {
            if !allowed[tool.Name()] {
                subTools.Unregister(tool.Name())
            }
        }
    }

    // 3. 构建消息
    if wd := msg.Metadata["workspace_root"]; wd != "" {
        systemPrompt += fmt.Sprintf("\n\nWorking directory: %s\n", wd)
    }
    messages := []llm.ChatMessage{
        llm.NewSystemMessage(systemPrompt),
        llm.NewUserMessage(task),
    }

    // 4. 记忆注入（Phase 2 新增）
    var memoryProvider memory.MemoryProvider
    var toolExtras *ToolContextExtras
    // if role.Memory { memoryProvider, toolExtras = a.createSubAgentMemory(roleName, msg) }

    // 5. 从 InboundMessage 继承原始 IM 信息
    originChannel := msg.OriginChannel()
    originChatID := msg.OriginChatID()
    originSender := msg.OriginSenderID()

    // 6. 构建 RunConfig
    cfg := RunConfig{
        LLMClient:     a.llmClient,
        Model:         a.model,
        Tools:         subTools,
        Messages:      messages,
        AgentID:       parentAgentID + "/" + roleName,
        Channel:       originChannel,
        ChatID:        originChatID,
        SenderID:      originSender,
        SenderName:    msg.SenderName,
        MaxIterations: 100,
        Memory:        memoryProvider,
        ToolContextExtras: toolExtras,
    }

    log.WithFields(log.Fields{
        "parent": parentAgentID,
        "role":   roleName,
        "task":   tools.Truncate(task, 80),
    }).Info("SubAgent started via unified message")

    // 7. 运行统一引擎
    out := Run(ctx, cfg)

    log.WithFields(log.Fields{
        "parent": parentAgentID,
        "role":   roleName,
        "tools":  out.ToolsUsed,
    }).Info("SubAgent completed")

    return out, nil
}

// tools/subagent.go — 零改动

func (t *SubAgentTool) Execute(ctx *ToolContext, input string) (*ToolResult, error) {
    // ... 解析参数、查找角色定义（不变）

    // SubAgentManager.RunSubAgent 签名不变
    // spawnAgentAdapter 内部完成 (task, prompt, tools) → InboundMessage → OutboundMessage → string
    result, err := ctx.Manager.RunSubAgent(ctx, params.Task, role.SystemPrompt, role.AllowedTools)
    if err != nil {
        return NewResult(fmt.Sprintf("Sub-agent error: %v", err)), nil
    }
    return NewResult(result), nil
}

-- 新表（替代 core_memory_blocks）
CREATE TABLE agent_memory_blocks (
    agent_id   TEXT NOT NULL DEFAULT 'main',  -- "main", "main/code-reviewer", ...
    tenant_id  INTEGER NOT NULL DEFAULT 0,    -- 聊天窗口（working_context 用）
    block_name TEXT NOT NULL,                 -- "persona", "human", "working_context"
    user_id    TEXT NOT NULL DEFAULT '',       -- 调用者 ID（human 用）
    content    TEXT NOT NULL DEFAULT '',
    char_limit INTEGER NOT NULL DEFAULT 2000,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (agent_id, tenant_id, block_name, user_id)
);

-- 迁移旧数据
INSERT INTO agent_memory_blocks (agent_id, tenant_id, block_name, user_id, content, char_limit)
    SELECT 'main', tenant_id, block_name, user_id, content, char_limit
    FROM core_memory_blocks;

// 旧接口（tenantID=0 hack 硬编码在每个方法里）
GetBlock(tenantID int64, blockName, userID string) (string, int, error)
SetBlock(tenantID int64, blockName, content, userID string) error

// 新接口（agentID 显式传入，路由逻辑统一）
GetBlock(agentID string, tenantID int64, blockName, userID string) (string, int, error)
SetBlock(agentID string, tenantID int64, blockName, content, userID string) error
GetAllBlocks(agentID string, tenantID int64, userID string) (map[string]string, error)
InitBlocks(agentID string, tenantID int64, userID string) error

// collection 命名规则
func archivalCollectionName(agentID string, tenantID int64) string {
    // 主 Agent:    "archival_main_42"
    // SubAgent:    "archival_main/code-reviewer_42"
    return fmt.Sprintf("archival_%s_%d", agentID, tenantID)
}

// ForAgent 返回一个绑定到特定 agentID 的 ArchivalService 视图。
// collection 名从 "archival_{tenantID}" 变为 "archival_{agentID}_{tenantID}"。
func (s *ArchivalService) ForAgent(agentID string) *ArchivalService {
    return &ArchivalService{
        db:            s.db,
        embeddingFunc: s.embeddingFunc,
        agentID:       agentID,  // 新字段
    }
}

func (a *Agent) createSubAgentMemory(role string, tenantID int64, msg bus.InboundMessage) (memory.MemoryProvider, *ToolContextExtras) {
    subAgentID := msg.ParentAgentID + "/" + role

    // 1. 获取或创建 SubAgent persona（和 agentID 绑定）
    persona, _, _ := a.coreSvc.GetBlock(subAgentID, 0, "persona", "")
    if persona == "" {
        roleDef, _ := tools.GetSubAgentRole(role)
        if roleDef != nil {
            persona = fmt.Sprintf("I am %s. %s", role, roleDef.Description)
            a.coreSvc.SetBlock(subAgentID, 0, "persona", persona, "")
        }
    }

    // 2. 继承调用者的 human block（只读，和 userID 绑定）
    originSender := msg.OriginSenderID()
    human, _, _ := a.coreSvc.GetBlock("main", 0, "human", originSender)

    // 3. 获取 SubAgent 的 working_context（和 agentID+tenant 绑定，持久化）
    workingCtx, _, _ := a.coreSvc.GetBlock(subAgentID, tenantID, "working_context", "")

    // 4. 创建 SubAgent 专用的 ArchivalService（和 agentID+tenant 绑定）
    archival := a.archivalSvc.ForAgent(subAgentID)

    // 5. 构建 SubAgentMemory
    mem := letta.NewSubAgentMemory(persona, human, workingCtx, archival)

    // 6. 构建 ToolContextExtras
    extras := &ToolContextExtras{
        TenantID:       tenantID,
        CoreMemory:     a.coreSvc,
        ArchivalMemory: archival,
        MemorySvc:      a.memorySvc,
    }

    return mem, extras
}

// agent/call_chain.go

type callChainKey struct{}

// CallChain 调用链上下文
type CallChain struct {
    Chain []string // ["main", "main/code-reviewer"]
}

const MaxSubAgentDepth = 3

func CallChainFromContext(ctx context.Context) *CallChain {
    if cc, ok := ctx.Value(callChainKey{}).(*CallChain); ok {
        return cc
    }
    return &CallChain{Chain: []string{"main"}}
}

func WithCallChain(ctx context.Context, cc *CallChain) context.Context {
    return context.WithValue(ctx, callChainKey{}, cc)
}

func (cc *CallChain) CanSpawn(targetRole string) error {
    if len(cc.Chain) >= MaxSubAgentDepth {
        return fmt.Errorf("max SubAgent depth %d reached (chain: %v)", MaxSubAgentDepth, cc.Chain)
    }
    currentID := cc.Chain[len(cc.Chain)-1]
    targetID := currentID + "/" + targetRole
    for _, id := range cc.Chain {
        if id == targetID {
            return fmt.Errorf("circular SubAgent call: %s already in chain %v", targetID, cc.Chain)
        }
    }
    return nil
}

func (cc *CallChain) Spawn(targetRole string) *CallChain {
    currentID := cc.Chain[len(cc.Chain)-1]
    newChain := make([]string, len(cc.Chain)+1)
    copy(newChain, cc.Chain)
    newChain[len(cc.Chain)] = currentID + "/" + targetRole
    return &CallChain{Chain: newChain}
}

---
name: code-reviewer
description: "Code review specialist"
tools:
  - Shell
  - Read
  - Grep
  - Glob
  - Fetch
  - WebSearch
# === 新增字段（Phase 2+） ===
memory: true              # 启用记忆（persona + archival）
send_message: false       # 不能直接发消息（默认 false）
max_iterations: 50        # 自定义迭代上限（默认 100）
---

type SubAgentRole struct {
    Name          string
    Description   string
    SystemPrompt  string
    AllowedTools  []string
    // Phase 2 新增
    Memory        bool // 启用记忆
    SendMessage   bool // 能直接发消息
    MaxIterations int  // 自定义迭代上限（0 = 默认 100）
}

// bus/address.go

// Address 统一寻址标识。
// 格式: scheme://id[/sub]
//
// 实体类型与 scheme 对应：
//   - im://feishu/ou_xxx          → 飞书用户（私聊）
//   - im://feishu/oc_xxx          → 飞书群聊
//   - im://qq/xxx                 → QQ 用户/群
//   - agent://main                → 主 Agent
//   - agent://main/code-reviewer  → SubAgent
//   - system://cron               → 定时任务
//   - system://cli                → CLI 调试
type Address struct {
    Scheme string // "im", "agent", "system"
    Domain string // "feishu", "qq", "main", "cron"
    ID     string // "ou_xxx", "oc_xxx", "code-reviewer"
}

// String 返回 URI 格式: scheme://domain/id
func (a Address) String() string {
    if a.ID == "" {
        return a.Scheme + "://" + a.Domain
    }
    return a.Scheme + "://" + a.Domain + "/" + a.ID
}

// ParseAddress 从 URI 字符串解析 Address
func ParseAddress(s string) (Address, error) {
    // "im://feishu/ou_xxx" → {Scheme:"im", Domain:"feishu", ID:"ou_xxx"}
    // "agent://main"       → {Scheme:"agent", Domain:"main", ID:""}
    // "agent://main/code-reviewer" → {Scheme:"agent", Domain:"main", ID:"code-reviewer"}
    ...
}

// 便捷构造函数
func IMAddress(channel, id string) Address {
    return Address{Scheme: "im", Domain: channel, ID: id}
}

func AgentAddress(parts ...string) Address {
    if len(parts) == 1 {
        return Address{Scheme: "agent", Domain: parts[0]}
    }
    return Address{Scheme: "agent", Domain: parts[0], ID: strings.Join(parts[1:], "/")}
}

func SystemAddress(name string) Address {
    return Address{Scheme: "system", Domain: name}
}

// 判断方法
func (a Address) IsIM() bool     { return a.Scheme == "im" }
func (a Address) IsAgent() bool  { return a.Scheme == "agent" }
func (a Address) IsSystem() bool { return a.Scheme == "system" }

// Channel 返回 IM 渠道名（仅 im:// 有意义）
func (a Address) Channel() string {
    if a.Scheme == "im" {
        return a.Domain
    }
    return ""
}

// bus/bus.go

type InboundMessage struct {
    // === 统一寻址 ===
    From Address // 消息发送方（IM 用户 / 父 Agent / cron）
    To   Address // 消息接收方（Agent）

    // === 内容 ===
    Content  string
    Media    []string
    Metadata map[string]string
    Time     time.Time

    // === 调度 ===
    RequestID string

    // === Agent 间通信（仅 From.IsAgent() 时有值）===
    SystemPrompt string
    AllowedTools []string
    RoleName     string

    // === 兼容字段（过渡期，逐步废弃）===
    // Deprecated: 使用 From.Channel() 代替
    Channel string
    // Deprecated: 使用 From.ID 代替
    SenderID string
    // ...
}

// 便捷方法（过渡期兼容 + 语义清晰）
func (m *InboundMessage) SenderAddress() Address { return m.From }
func (m *InboundMessage) TargetAddress() Address { return m.To }

// OriginIM 获取原始 IM 地址（Agent 间调用时从 Metadata 追溯）
func (m *InboundMessage) OriginIM() Address {
    if m.From.IsIM() {
        return m.From
    }
    if origin, ok := m.Metadata["origin_address"]; ok {
        addr, _ := ParseAddress(origin)
        return addr
    }
    return Address{}
}

type OutboundMessage struct {
    // === 统一寻址 ===
    From Address // 发送方 Agent
    To   Address // 接收方（IM 用户/群 / 父 Agent）

    // === 内容 ===
    Content  string
    Media    []string
    Metadata map[string]string

    // === Agent 返回扩展 ===
    ToolsUsed   []string
    WaitingUser bool
    Error       error

    // === 兼容字段（过渡期）===
    Channel string
    ChatID  string
}