PicoClaw 架构

整体架构

        flowchart TB
    subgraph Channels["消息渠道层"]
        TG[Telegram]
        DC[Discord]
        FS[飞书]
        DT[钉钉]
        SK[Slack]
        QQ[QQ]
        WC[企业微信]
        WA[WhatsApp]
        LN[LINE]
        MX[Matrix]
        IRC[IRC]
        MC[MaixCAM]
    end

    subgraph Bus["消息总线"]
        IB[InboundMessage]
        OB[OutboundMessage]
    end

    subgraph Core["Agent 核心"]
        AL[AgentLoop]
        AI[AgentInstance]
        CB[ContextBuilder]
        RT[Router]
        SM[SessionManager]
        MM[Memory]
    end

    subgraph Tools["工具层"]
        RF[read_file]
        WF[write_file]
        EF[edit_file]
        EX[exec]
        WS[web_search]
        WFE[web_fetch]
        CR[cron]
        SP[spawn]
        MSG[message]
        MCP[mcp_tool]
        HW[i2c / spi]
    end

    subgraph Providers["LLM Provider 层"]
        OAI[OpenAI Compatible]
        ANT[Anthropic Native]
        AZR[Azure OpenAI]
        OLL[Ollama / vLLM]
        FB[FallbackChain]
    end

    subgraph Services["后台服务"]
        CRON[CronService]
        HB[HeartbeatService]
        HL[HealthServer]
        DEV[DeviceService]
        MS[MediaStore]
    end

    Channels -->|InboundMessage| IB
    IB --> AL
    AL --> AI
    AI --> CB
    AI --> RT
    AI --> SM
    AI --> MM
    AL -->|Tool Calls| Tools
    AL -->|LLM Chat| FB
    FB --> OAI & ANT & AZR & OLL
    AL -->|OutboundMessage| OB
    OB --> Channels
    CRON & HB & HL & DEV & MS -.-> AL

核心组件

1. Gateway（网关）

pkg/gateway/gateway.go 是整个系统的组装点，负责：

  • 加载配置（config.Config）

  • 创建 LLM Provider 和 FallbackChain

  • 初始化 AgentLoop

  • 启动所有后台服务（Cron、Heartbeat、Health、Device）

  • 启动所有消息渠道

  • 处理优雅关闭（graceful shutdown）

type services struct {
    CronService      *cron.CronService
    HeartbeatService *heartbeat.HeartbeatService
    MediaStore       media.MediaStore
    ChannelManager   *channels.Manager
    DeviceService    *devices.Service
    HealthServer     *health.Server
}

2. AgentLoop（Agent 循环）

pkg/agent/loop.go 是核心处理引擎，实现了完整的 Agent 循环：

接收消息 → 路由到 Agent → 构建上下文 → 调用 LLM → 解析工具调用 → 执行工具 → 循环直到完成 → 发送响应

关键方法：

方法

职责

Run()

启动消息监听循环

processMessage()

处理单条消息的完整流程

resolveMessageRoute()

根据消息内容路由到目标 Agent

runAgentLoop()

执行 LLM ↔ Tool 迭代循环

runLLMIteration()

单次 LLM 调用 + 工具执行

selectCandidates()

选择 Provider 候选（支持 Smart Routing）

maybeSummarize()

上下文过长时触发摘要

3. AgentInstance（Agent 实例）

pkg/agent/instance.go 封装了单个 Agent 的完整配置：

  • 模型选择（主模型 + 备选模型列表）

  • 工作空间路径

  • 工具注册表

  • 会话管理器

  • 上下文构建器

  • 温度、最大 Token、思考级别等参数

  • Smart Router（轻量模型路由）

4. 消息总线（Message Bus）

pkg/bus/bus.go 实现了进程内的发布-订阅消息总线：

// 入站消息（渠道 → Agent）
type InboundMessage struct {
    Channel    string
    SenderID   string
    Sender     SenderInfo
    ChatID     string
    Content    string
    Media      []string
    Peer       Peer        // direct | group | channel
    SessionKey string
    Metadata   map[string]string
}

// 出站消息（Agent → 渠道）
type OutboundMessage struct {
    Channel          string
    ChatID           string
    Content          string
    ReplyToMessageID string
}

5. Provider 层

Provider 层采用协议优先的架构（正在从 Vendor-based 重构为 Protocol-based）：

        flowchart LR
    subgraph Factory["Provider Factory"]
        F[factory.go]
    end

    subgraph Protocols["协议适配"]
        OC[OpenAI Compatible]
        AM[Anthropic Messages]
        AS[Anthropic SDK]
        AZ[Azure OpenAI]
        AG[Antigravity/OAuth]
        CC[Claude CLI]
        CX[Codex CLI]
    end

    subgraph Fallback["故障转移"]
        FC[FallbackChain]
        EC[ErrorClassifier]
        CD[Cooldown]
    end

    F -->|"openai/*"| OC
    F -->|"anthropic-messages/*"| AM
    F -->|"anthropic/*"| AS
    F -->|"azure/*"| AZ
    F -->|"antigravity/*"| AG
    F -->|"claude-cli/*"| CC
    F -->|"codex-cli/*"| CX

    OC & AM & AS & AZ & AG --> FC
    FC --> EC --> CD

故障转移机制：

  • FallbackChain 按优先级尝试多个 Provider

  • ErrorClassifier 将错误分类为 auth / rate_limit / billing / timeout / overloaded / format

  • Cooldown 对失败的 Provider 实施冷却期

  • FailoverFormat 类型的错误不触发重试（请求本身有问题）

6. 渠道层

每个渠道通过 init() 自注册到全局 Registry：

// pkg/channels/telegram/init.go
func init() {
    channels.Register("telegram", func(cfg json.RawMessage, bus *bus.MessageBus) (channels.Channel, error) {
        return NewTelegramChannel(cfg, bus)
    })
}

渠道管理器（channels/Manager）负责：

  • 根据配置启动/停止渠道

  • 消息分发（长消息自动分片 split.go）

  • 错误处理和重试

7. 工具系统

工具通过 ToolRegistry 注册，每个工具实现 Tool 接口：

type Tool interface {
    Name() string
    Description() string
    Parameters() map[string]any
    Execute(ctx context.Context, args map[string]any) (*ToolResult, error)
}

工具在 AgentInstance 创建时根据配置选择性注册。特殊工具：

  • spawn：创建子 Agent 异步执行任务

  • mcp_tool：桥接 MCP 服务器提供的工具

  • i2c / spi：直接操作嵌入式硬件（Linux only）

8. 技能系统

技能（Skills）是可安装的能力扩展包：

workspace/skills/{skill-name}/
├── SKILL.md          # 技能定义（名称、描述、指令）
├── scripts/          # 可执行脚本
└── references/       # 参考文档

  • skills/loader.go：从工作空间加载已安装技能

  • skills/installer.go：从 Git 仓库安装技能

  • skills/clawhub_registry.go：ClawHub 公共技能市场搜索

关键调用链

消息处理主流程

Channel.OnMessage()
  → bus.Publish(InboundMessage)
    → AgentLoop.processMessage()
      → resolveMessageRoute()          // 路由到目标 Agent
      → agent.Sessions.Load()          // 加载会话历史
      → agent.ContextBuilder.Build()   // 构建系统提示词
      → runAgentLoop()                 // 进入 LLM 循环
        → selectCandidates()           // 选择 Provider（Smart Routing）
        → runLLMIteration()            // 调用 LLM
          → FallbackChain.Chat()       // 带故障转移的 LLM 调用
          → parseToolCalls()           // 解析工具调用
          → tools.Execute()            // 执行工具
          → (循环直到无工具调用或达到最大迭代)
      → maybeSummarize()               // 可能触发上下文摘要
      → bus.Publish(OutboundMessage)   // 发送响应

上下文构建

ContextBuilder.Build()
  → 读取 AGENTS.md（Agent 指令）
  → 读取 SOUL.md（人格定义）
  → 读取 USER.md（用户画像）
  → 读取 TOOLS.md（工具使用说明）
  → 读取 MEMORY.md（长期记忆）
  → 加载已安装 Skills 的 SKILL.md
  → 注入运行时上下文（时间、渠道、ChatID）
  → 组装为 system prompt

跨切面关注点

认证

  • OAuth 2.0 + PKCE 流程（pkg/auth/）

  • 凭证加密存储（pkg/credential/，支持 ChaCha20-Poly1305）

  • 每个渠道独立的 allow_from 白名单

日志

  • 结构化日志（pkg/logger/）

  • 可配置日志级别

错误处理

  • Provider 层：FailoverError 分类 + 自动重试

  • 渠道层：pkg/channels/errors.go 统一错误类型

  • 工具层：ToolResult 包含 success/error 状态

配置管理

  • JSON 配置文件（config.json）

  • 环境变量覆盖（caarlos0/env）

  • 配置版本迁移（pkg/config/migration.go）

  • 运行时热重载（Provider + 配置）

安全

  • 文件系统沙箱（restrict_to_workspace）

  • 路径白名单（allow_read_paths / allow_write_paths）

  • Shell 命令危险操作拦截

  • SSRF 防护（网络工具内置黑名单）

  • 会话隔离（不同用户/渠道独立会话）