PicoClaw 核心工作流

工作流 1：消息处理（Message Processing）

概述

用户通过任意渠道（Telegram、飞书、Discord 等）发送消息，PicoClaw 接收后路由到对应 Agent，调用 LLM 生成回复，可能执行工具调用，最终将结果返回给用户。

流程图

        sequenceDiagram
    participant U as 用户
    participant CH as Channel
    participant BUS as MessageBus
    participant AL as AgentLoop
    participant RT as Router
    participant AI as AgentInstance
    participant LLM as LLM Provider
    participant T as Tools

    U->>CH: 发送消息
    CH->>BUS: Publish(InboundMessage)
    BUS->>AL: processMessage()
    AL->>RT: resolveMessageRoute()
    RT-->>AL: AgentInstance + Route
    AL->>AI: Sessions.Load(sessionKey)
    AL->>AI: ContextBuilder.Build()
    loop LLM 迭代循环
        AL->>LLM: FallbackChain.Chat()
        LLM-->>AL: LLMResponse
        alt 有工具调用
            AL->>T: tool.Execute()
            T-->>AL: ToolResult
        else 无工具调用
            AL-->>AL: 循环结束
        end
    end
    AL->>AI: Sessions.Save()
    AL->>BUS: Publish(OutboundMessage)
    BUS->>CH: SendMessage()
    CH->>U: 回复消息

关键代码入口

步骤	文件	函数
消息接收	`pkg/channels/{platform}/{platform}.go`	`handleMessage()`
消息路由	`pkg/agent/loop.go`	`resolveMessageRoute()`
Agent 循环	`pkg/agent/loop.go`	`runAgentLoop()`
LLM 调用	`pkg/providers/fallback.go`	`FallbackChain.Chat()`
工具执行	`pkg/tools/toolloop.go`	`ExecuteToolCalls()`
响应发送	`pkg/channels/manager.go`	`SendMessage()`

错误分支

Provider 失败：FallbackChain 自动切换到下一个候选 Provider
工具执行失败：返回错误信息给 LLM，LLM 决定是否重试
超过最大迭代：返回默认提示消息
上下文过长：触发 maybeSummarize() 压缩历史

工作流 2：Gateway 启动

概述

picoclaw gateway 命令启动完整的消息网关服务，包括 Agent 初始化、渠道连接、后台服务启动。

流程

        flowchart TD
    A[加载 config.json] --> B[创建 LLM Provider]
    B --> C[构建 FallbackChain]
    C --> D[创建 AgentLoop]
    D --> E[注册内置工具]
    E --> F[初始化 MCP 客户端]
    F --> G[启动后台服务]
    G --> G1[CronService]
    G --> G2[HeartbeatService]
    G --> G3[HealthServer]
    G --> G4[DeviceService]
    G --> G5[MediaStore]
    G --> H[启动消息渠道]
    H --> H1[Telegram Bot]
    H --> H2[Discord Bot]
    H --> H3[飞书 Webhook]
    H --> H4[其他渠道...]
    H --> I[监听信号]
    I --> J{收到 SIGTERM/SIGINT?}
    J -->|是| K[优雅关闭]
    K --> K1[停止渠道]
    K --> K2[停止后台服务]
    K --> K3[关闭 Provider]

关键代码入口

步骤	文件	函数
命令入口	`cmd/picoclaw/internal/gateway/command.go`	`NewGatewayCommand()`
网关启动	`pkg/gateway/gateway.go`	`Run()`
Agent 创建	`pkg/agent/instance.go`	`NewAgentInstance()`
渠道启动	`pkg/channels/manager.go`	`StartAll()`

工作流 3：子 Agent（Spawn）

概述

主 Agent 可以通过 spawn 工具创建子 Agent 异步执行耗时任务。子 Agent 有独立的会话和上下文，完成后通过消息总线报告结果。

流程

        sequenceDiagram
    participant MA as 主 Agent
    participant SP as Spawn Tool
    participant SA as 子 Agent
    participant LLM as LLM Provider
    participant BUS as MessageBus

    MA->>SP: spawn(task="翻译文档")
    SP->>SA: 创建子 AgentInstance
    SP-->>MA: "子 Agent 已启动 (id: xxx)"
    Note over MA: 主 Agent 继续处理其他事务

    par 子 Agent 异步执行
        SA->>LLM: Chat(task context)
        LLM-->>SA: Response + ToolCalls
        SA->>SA: 执行工具...
        SA->>SA: 迭代直到完成
    end

    SA->>BUS: Publish(完成通知)
    BUS->>MA: "[Subagent 'xxx' completed]"

关键代码入口

步骤	文件
Spawn 工具	`pkg/tools/spawn.go`
状态查询	`pkg/tools/spawn_status.go`
子 Agent 工具	`pkg/tools/subagent.go`

工作流 4：定时任务（Cron）

概述

用户可以通过 cron 工具创建定时提醒和周期性任务。CronService 在后台运行，到时间时触发 Agent 处理。

流程

        flowchart LR
    A[用户请求创建定时任务] --> B[cron 工具]
    B --> C[CronService.Add]
    C --> D[持久化到 cron.json]
    D --> E[gronx 调度器]
    E -->|到达触发时间| F[AgentLoop.ProcessDirect]
    F --> G[Agent 处理任务]
    G --> H[通过渠道发送结果]

关键代码入口

步骤	文件
Cron 工具	`pkg/tools/cron.go`
Cron 服务	`pkg/cron/service.go`
心跳服务	`pkg/heartbeat/service.go`

工作流 5：Smart Routing（智能路由）

概述

当配置了 model_routing 时，AgentLoop 会根据消息复杂度自动选择轻量模型（快速/便宜）或重量模型（智能/贵）。

流程

        flowchart TD
    A[收到消息] --> B{配置了 Router?}
    B -->|否| C[使用默认 Candidates]
    B -->|是| D[Router.Score 消息]
    D --> E{复杂度评分}
    E -->|低| F[使用 LightCandidates]
    E -->|高| G[使用主 Candidates]
    F --> H[调用轻量模型]
    G --> I[调用重量模型]

关键代码入口

步骤	文件
路由器	`pkg/routing/router.go`
特征提取	`pkg/routing/features.go`
分类器	`pkg/routing/classifier.go`
候选选择	`pkg/agent/loop.go` → `selectCandidates()`