项目结构分析
This commit is contained in:
ddshuai
parent
30155c1c59
commit
84a52428b5
1 changed files with 901 additions and 0 deletions
901
docs/architecture-flow.md
Normal file
901
docs/architecture-flow.md
Normal file
|
|
@ -0,0 +1,901 @@
|
|||
# PicoClaw 代码执行流程分析
|
||||
|
||||
## 项目概述
|
||||
|
||||
PicoClaw 是一个用 Go 编写的超轻量级个人 AI 助手，由 Sipeed 发起。核心内存占用 <10MB，可在 $10 硬件上运行。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
picoclaw/
|
||||
├── cmd/
|
||||
│ ├── picoclaw/ # 主 CLI 入口
|
||||
│ │ ├── main.go # 程序入口，Cobra 命令注册
|
||||
│ │ └── internal/ # CLI 子命令
|
||||
│ │ ├── agent/ # picoclaw agent（交互式/单次对话）
|
||||
│ │ ├── gateway/ # picoclaw gateway（长期运行网关）
|
||||
│ │ ├── onboard/ # picoclaw onboard（初始化配置）
|
||||
│ │ ├── cron/ # picoclaw cron（定时任务管理）
|
||||
│ │ ├── skills/ # picoclaw skills（技能管理）
|
||||
│ │ ├── auth/ # picoclaw auth（Provider 认证）
|
||||
│ │ ├── migrate/ # picoclaw migrate（配置迁移）
|
||||
│ │ ├── model/ # picoclaw model（模型管理）
|
||||
│ │ ├── status/ # picoclaw status（状态查看）
|
||||
│ │ └── version/ # picoclaw version
|
||||
│ └── picoclaw-launcher-tui/ # TUI 启动器（终端 UI + WebUI）
|
||||
├── pkg/ # 核心库
|
||||
│ ├── agent/ # Agent 运行时（核心中的核心）
|
||||
│ │ ├── loop.go # AgentLoop 主循环
|
||||
│ │ ├── turn.go # 单轮对话状态管理
|
||||
│ │ ├── instance.go # AgentInstance 实例创建
|
||||
│ │ ├── context.go # 上下文构建（系统提示词）
|
||||
│ │ ├── hooks.go # Hook 系统
|
||||
│ │ ├── steering.go # 消息注入/转向
|
||||
│ │ ├── subturn.go # 子 Agent 并发执行
|
||||
│ │ ├── eventbus.go # 事件总线
|
||||
│ │ ├── registry.go # Agent 注册表
|
||||
│ │ ├── definition.go # AGENT.md/SOUL.md 解析
|
||||
│ │ ├── memory.go # 记忆存储
|
||||
│ │ └── model_resolution.go # 模型解析
|
||||
│ ├── bus/ # 消息总线
|
||||
│ │ ├── types.go # InboundMessage/OutboundMessage
|
||||
│ │ └── bus.go # 消息传递
|
||||
│ ├── channels/ # 聊天平台集成（17+）
|
||||
│ │ ├── manager.go # ChannelManager 统一管理
|
||||
│ │ ├── telegram/
|
||||
│ │ ├── discord/
|
||||
│ │ ├── weixin/ # 微信
|
||||
│ │ ├── wecom/ # 企业微信
|
||||
│ │ ├── qq/
|
||||
│ │ ├── feishu/ # 飞书
|
||||
│ │ ├── slack/
|
||||
│ │ ├── whatsapp/
|
||||
│ │ └── ... # 更多平台
|
||||
│ ├── providers/ # LLM Provider 适配器（30+）
|
||||
│ │ ├── types.go # LLMProvider 接口定义
|
||||
│ │ ├── fallback.go # 降级链
|
||||
│ │ ├── cooldown.go # 冷却追踪
|
||||
│ │ ├── openai/
|
||||
│ │ ├── anthropic/
|
||||
│ │ ├── gemini/
|
||||
│ │ ├── deepseek/
|
||||
│ │ └── ... # 更多 Provider
|
||||
│ ├── gateway/ # HTTP 网关服务
|
||||
│ │ └── gateway.go # Gateway 启动与服务编排
|
||||
│ ├── config/ # 配置管理
|
||||
│ │ └── config.go # Config 结构与加载
|
||||
│ ├── tools/ # 工具注册与执行
|
||||
│ ├── session/ # 会话持久化（JSONL）
|
||||
│ ├── memory/ # 对话记忆
|
||||
│ ├── skills/ # 技能系统
|
||||
│ ├── routing/ # 模型路由
|
||||
│ ├── cron/ # 定时任务服务
|
||||
│ ├── heartbeat/ # 心跳服务
|
||||
│ ├── media/ # 媒体文件存储
|
||||
│ ├── voice/ # 语音转录
|
||||
│ ├── health/ # 健康检查 HTTP 服务
|
||||
│ └── commands/ # 斜杠命令系统
|
||||
├── docker/ # Docker 部署
|
||||
│ ├── docker-compose.yml # 三种 profile 部署
|
||||
│ ├── entrypoint.sh # 容器入口脚本
|
||||
│ └── Dockerfile # 多种构建方式
|
||||
├── workspace/ # 默认工作空间
|
||||
│ ├── AGENT.md # Agent 身份与工具定义
|
||||
│ ├── SOUL.md # Agent 人格设定
|
||||
│ └── USER.md # 用户偏好
|
||||
└── docs/ # 文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 一、程序启动流程
|
||||
|
||||
### 1.1 CLI 入口 (`cmd/picoclaw/main.go`)
|
||||
|
||||
```
|
||||
main()
|
||||
│
|
||||
├── 打印 ASCII Banner
|
||||
├── 创建 Cobra Root Command
|
||||
├── 注册子命令:
|
||||
│ ├── onboard → 初始化 ~/.picoclaw/ 目录与配置
|
||||
│ ├── agent → 单次/交互式对话
|
||||
│ ├── gateway → 启动长期运行网关
|
||||
│ ├── cron → 管理定时任务
|
||||
│ ├── skills → 安装/搜索技能
|
||||
│ ├── auth → Provider OAuth 认证
|
||||
│ ├── migrate → 配置版本迁移
|
||||
│ ├── model → 模型管理
|
||||
│ ├── status → 运行状态查看
|
||||
│ └── version → 版本信息
|
||||
└── cmd.Execute()
|
||||
```
|
||||
|
||||
### 1.2 Gateway 启动流程 (`pkg/gateway/gateway.go:Run()`)
|
||||
|
||||
这是最核心的运行模式，完整启动流程如下：
|
||||
|
||||
```
|
||||
gateway.Run(debug, homePath, configPath, allowEmptyStartup)
|
||||
│
|
||||
├── 1. 初始化日志系统
|
||||
│ ├── logger.InitPanic() → Panic 日志
|
||||
│ └── logger.EnableFileLogging() → 文件日志
|
||||
│
|
||||
├── 2. 加载配置
|
||||
│ └── config.LoadConfig(configPath) → ~/.picoclaw/config.json
|
||||
│
|
||||
├── 3. 创建 LLM Provider
|
||||
│ └── createStartupProvider(cfg) → OpenAI/Anthropic/Gemini 等
|
||||
│
|
||||
├── 4. 创建 MessageBus
|
||||
│ └── bus.NewMessageBus() → 消息总线（Inbound/Outbound 通道）
|
||||
│
|
||||
├── 5. 创建 AgentLoop
|
||||
│ └── agent.NewAgentLoop(cfg, msgBus, provider)
|
||||
│ ├── NewAgentRegistry() → 创建 Agent 注册表
|
||||
│ ├── NewCooldownTracker() → 冷却追踪器
|
||||
│ ├── NewFallbackChain() → 降级链
|
||||
│ ├── NewEventManager() → 事件总线
|
||||
│ ├── NewHookManager() → Hook 管理器
|
||||
│ ├── configureHookManager() → 从配置加载 Hooks
|
||||
│ └── registerSharedTools() → 注册共享工具（web/message/spawn 等）
|
||||
│
|
||||
├── 6. 启动后台服务
|
||||
│ └── setupAndStartServices()
|
||||
│ ├── CronService.Start() → 定时任务服务
|
||||
│ ├── HeartbeatService.Start() → 心跳监控
|
||||
│ ├── MediaStore.Start() → 媒体文件管理（含清理）
|
||||
│ ├── ChannelManager.Start() → 聊天平台管理器
|
||||
│ ├── DeviceService → 设备管理
|
||||
│ └── HealthServer.Start() → HTTP 健康检查
|
||||
│
|
||||
├── 7. 启动 AgentLoop（goroutine）
|
||||
│ └── go agentLoop.Run(ctx)
|
||||
│
|
||||
├── 8. 配置热重载（可选）
|
||||
│ └── setupConfigWatcherPolling() → 监听 config.json 变化
|
||||
│
|
||||
└── 9. 主循环等待信号
|
||||
├── <-sigChan (Ctrl+C) → 优雅关闭
|
||||
├── <-configReloadChan → 配置热重载
|
||||
└── <-manualReloadChan → /reload 端点触发
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、核心数据结构
|
||||
|
||||
### 2.1 AgentLoop（`pkg/agent/loop.go`）
|
||||
|
||||
AgentLoop 是整个系统的核心调度器：
|
||||
|
||||
```go
|
||||
type AgentLoop struct {
|
||||
bus *bus.MessageBus // 消息总线
|
||||
cfg *config.Config // 全局配置
|
||||
registry *AgentRegistry // Agent 注册表（多 Agent 支持）
|
||||
state *state.Manager // 状态管理
|
||||
eventBus *EventBus // 事件总线
|
||||
hooks *HookManager // Hook 管理器
|
||||
fallback *providers.FallbackChain // LLM 降级链
|
||||
channelManager *channels.Manager // 聊天平台管理器
|
||||
mediaStore media.MediaStore // 媒体存储
|
||||
transcriber voice.Transcriber // 语音转录
|
||||
cmdRegistry *commands.Registry // 斜杠命令注册表
|
||||
mcp mcpRuntime // MCP 协议运行时
|
||||
steering *steeringQueue // 消息转向队列
|
||||
activeTurnStates sync.Map // 活跃 Turn 状态表
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 AgentInstance（`pkg/agent/instance.go`）
|
||||
|
||||
每个 Agent 的完整配置实例：
|
||||
|
||||
```go
|
||||
type AgentInstance struct {
|
||||
ID string // Agent 标识
|
||||
Name string // Agent 名称
|
||||
Model string // 主模型
|
||||
Fallbacks []string // 降级模型列表
|
||||
Workspace string // 工作目录
|
||||
MaxIterations int // 最大工具调用迭代次数
|
||||
MaxTokens int // 最大输出 Token
|
||||
ContextWindow int // 上下文窗口大小
|
||||
Provider providers.LLMProvider // LLM Provider 实例
|
||||
Sessions session.SessionStore // 会话存储
|
||||
ContextBuilder *ContextBuilder // 上下文构建器
|
||||
Tools *tools.ToolRegistry // 工具注册表
|
||||
Router *routing.Router // 模型路由器
|
||||
LightProvider providers.LLMProvider // 轻量模型 Provider
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 TurnState（`pkg/agent/turn.go`）
|
||||
|
||||
单轮对话的完整状态：
|
||||
|
||||
```go
|
||||
type TurnPhase string
|
||||
const (
|
||||
TurnPhaseSetup = "setup" // 初始化阶段
|
||||
TurnPhaseRunning = "running" // LLM 调用中
|
||||
TurnPhaseTools = "tools" // 工具执行中
|
||||
TurnPhaseFinalizing = "finalizing" // 收尾阶段
|
||||
TurnPhaseCompleted = "completed" // 已完成
|
||||
TurnPhaseAborted = "aborted" // 已中止
|
||||
)
|
||||
|
||||
type turnState struct {
|
||||
turnID string
|
||||
agent *AgentInstance
|
||||
phase TurnPhase
|
||||
iteration int // 当前迭代次数
|
||||
userMessage string // 用户消息
|
||||
media []string // 媒体附件
|
||||
finalContent string // 最终回复
|
||||
// 中断控制
|
||||
gracefulInterrupt bool
|
||||
hardAbort bool
|
||||
providerCancel context.CancelFunc
|
||||
// SubTurn 支持
|
||||
depth int
|
||||
parentTurnState *turnState
|
||||
childTurnIDs []string
|
||||
pendingResults chan *ToolResult
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 消息结构（`pkg/bus/types.go`）
|
||||
|
||||
```go
|
||||
type InboundMessage struct {
|
||||
Channel string // 平台: "telegram", "discord", "cli" 等
|
||||
SenderID string // 发送者 ID
|
||||
Sender SenderInfo // 结构化发送者信息
|
||||
ChatID string // 会话 ID
|
||||
Content string // 消息文本
|
||||
Media []string // 媒体附件 (media:// refs)
|
||||
Peer Peer // 路由对等体 (direct/group/channel)
|
||||
SessionKey string // 会话标识
|
||||
Metadata map[string]string // 自定义元数据
|
||||
}
|
||||
|
||||
type OutboundMessage struct {
|
||||
Channel string // 平台
|
||||
ChatID string // 会话 ID
|
||||
Content string // 回复文本
|
||||
ReplyToMessageID string // 引用回复的消息 ID
|
||||
}
|
||||
```
|
||||
|
||||
### 2.5 LLM Provider 接口（`pkg/providers/types.go`）
|
||||
|
||||
```go
|
||||
type LLMProvider interface {
|
||||
Chat(ctx context.Context, messages []Message, tools []ToolDefinition,
|
||||
model string, options map[string]any) (*LLMResponse, error)
|
||||
GetDefaultModel() string
|
||||
}
|
||||
|
||||
// 可选接口
|
||||
type StreamingProvider interface {
|
||||
ChatStream(ctx context.Context, ..., onChunk func(accumulated string)) (*LLMResponse, error)
|
||||
}
|
||||
|
||||
type ThinkingCapable interface {
|
||||
SupportsThinking() bool
|
||||
}
|
||||
|
||||
type NativeSearchCapable interface {
|
||||
SupportsNativeSearch() bool
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、消息处理完整流程
|
||||
|
||||
### 3.1 AgentLoop 主循环
|
||||
|
||||
```
|
||||
AgentLoop.Run(ctx) [loop.go:380]
|
||||
│
|
||||
├── ensureHooksInitialized() → 初始化 Hook 系统
|
||||
├── ensureMCPInitialized() → 初始化 MCP 运行时
|
||||
│
|
||||
└── for { select {
|
||||
│
|
||||
├── <-ctx.Done() → 退出
|
||||
│
|
||||
└── msg := <-bus.InboundChan() → 收到入站消息
|
||||
│
|
||||
├── resolveSteeringTarget() → 检查是否有活跃 Turn 需要转向
|
||||
│ └── 若有 → drainBusToSteering() → 排水到转向队列
|
||||
│
|
||||
├── processMessage(msg) → 处理消息（核心）
|
||||
│
|
||||
├── buildContinuationTarget() → 构建延续目标
|
||||
│
|
||||
└── 处理转向队列中的排队消息
|
||||
└── Continue() → 继续对话
|
||||
}}
|
||||
```
|
||||
|
||||
### 3.2 processMessage 详细流程
|
||||
|
||||
```
|
||||
processMessage(ctx, msg) [loop.go:1255]
|
||||
│
|
||||
├── 1. 日志记录
|
||||
│
|
||||
├── 2. 语音转录（如有音频）
|
||||
│ └── transcribeAudioInMessage()
|
||||
│
|
||||
├── 3. 系统消息路由
|
||||
│ └── if channel == "system" → processSystemMessage()
|
||||
│
|
||||
├── 4. 消息路由解析
|
||||
│ └── resolveMessageRoute(msg) → 确定 Agent 和会话
|
||||
│ ├── registry.ResolveRoute() → 根据 channel/peer/guild 路由
|
||||
│ └── 返回 (route, agentInstance, error)
|
||||
│
|
||||
├── 5. 重置 message 工具状态
|
||||
│
|
||||
├── 6. 解析 SessionKey
|
||||
│ └── resolveScopeKey(route, sessionKey)
|
||||
│
|
||||
├── 7. 构建 processOptions
|
||||
│ ├── SessionKey
|
||||
│ ├── Channel / ChatID / SenderID
|
||||
│ ├── UserMessage
|
||||
│ ├── Media
|
||||
│ └── DefaultResponse
|
||||
│
|
||||
├── 8. 斜杠命令检查
|
||||
│ └── handleCommand() → 如匹配则直接返回
|
||||
│
|
||||
├── 9. 挂起技能检查
|
||||
│ └── takePendingSkills() → 应用技能覆盖
|
||||
│
|
||||
└── 10. runAgentLoop(ctx, agent, opts) → 执行 Agent 循环
|
||||
```
|
||||
|
||||
### 3.3 runAgentLoop → runTurn（核心执行循环）
|
||||
|
||||
```
|
||||
runAgentLoop(ctx, agent, opts) [loop.go:1467]
|
||||
│
|
||||
├── RecordLastChannel() → 记录最后活跃频道
|
||||
├── newTurnState(agent, opts, scope) → 创建 Turn 状态
|
||||
└── runTurn(ctx, ts) → 执行 Turn
|
||||
│
|
||||
├── 注册活跃 Turn → registerActiveTurn()
|
||||
├── 发射 TurnStart 事件
|
||||
│
|
||||
├── 加载会话历史
|
||||
│ ├── Sessions.GetHistory(sessionKey)
|
||||
│ └── Sessions.GetSummary(sessionKey)
|
||||
│
|
||||
├── 构建消息列表
|
||||
│ └── ContextBuilder.BuildMessages(history, summary, userMessage, ...)
|
||||
│ ├── 构建 System Prompt（含缓存）
|
||||
│ │ ├── AGENT.md → Agent 身份、工具、技能
|
||||
│ │ ├── SOUL.md → Agent 人格
|
||||
│ │ ├── USER.md → 用户偏好
|
||||
│ │ ├── Skills → 已安装技能
|
||||
│ │ └── 动态上下文（时间、会话信息）
|
||||
│ ├── 拼接对话历史
|
||||
│ └── 添加当前用户消息 + 媒体
|
||||
│
|
||||
├── 解析媒体引用
|
||||
│ └── resolveMediaRefs(messages, mediaStore)
|
||||
│
|
||||
├── 上下文预算检查
|
||||
│ └── isOverContextBudget() → 若超限则 forceCompression()
|
||||
│
|
||||
├── 保存用户消息到会话
|
||||
│
|
||||
├── 模型选择
|
||||
│ └── selectCandidates(agent, userMessage) → 主模型/轻量模型
|
||||
│
|
||||
└── ═══════════════════════════════════════════
|
||||
║ Turn 迭代循环 ║
|
||||
═══════════════════════════════════════════
|
||||
for iteration < maxIterations {
|
||||
│
|
||||
├── 检查硬中止 → hardAbortRequested()
|
||||
├── 检查父 Turn 状态（SubTurn）
|
||||
├── 轮询 SubTurn 结果
|
||||
├── 注入 steering 消息
|
||||
│
|
||||
├── 调用 LLM ────────────────────────
|
||||
│ ├── 流式: provider.ChatStream()
|
||||
│ │ └── onChunk → 实时推送到 Channel
|
||||
│ └── 非流式: provider.Chat()
|
||||
│
|
||||
├── Hook: Observer 回调
|
||||
├── Hook: Interceptor 拦截
|
||||
├── Hook: Approval 审批
|
||||
│
|
||||
├── 解析 LLM 响应
|
||||
│ ├── 提取 finalContent（文本回复）
|
||||
│ └── 提取 toolCalls（工具调用）
|
||||
│
|
||||
├── if 无 toolCalls → 跳出循环
|
||||
│
|
||||
├── 执行工具调用
|
||||
│ for _, toolCall := range toolCalls {
|
||||
│ │
|
||||
│ ├── 工具查找 → Tools.Get(toolName)
|
||||
│ ├── 工具执行 → tool.Execute(params)
|
||||
│ ├── 结果添加到 messages
|
||||
│ └── Hook 回调
|
||||
│ }
|
||||
│
|
||||
├── 模型降级检查
|
||||
│ └── fallbackChain.Execute() → 如失败则切换 Provider
|
||||
│
|
||||
└── 继续迭代 → 再次调用 LLM
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 Turn 完成后的处理
|
||||
|
||||
```
|
||||
runTurn() 返回 turnResult
|
||||
│
|
||||
├── 保存 assistant 回复到会话
|
||||
├── 发射 TurnEnd 事件
|
||||
│
|
||||
└── 回到 runAgentLoop()
|
||||
├── 发布 followUp 消息
|
||||
├── 若 SendResponse → 发送到 OutboundMessage
|
||||
└── 返回 finalContent
|
||||
|
||||
回到 AgentLoop.Run() 的消息处理
|
||||
│
|
||||
├── publishResponseIfNeeded() → 通过 Bus 发送回复
|
||||
│ └── bus.PublishOutbound()
|
||||
│ └── ChannelManager 接收
|
||||
│ └── channelWorker 发送到平台
|
||||
│
|
||||
├── 处理排队的 steering 消息
|
||||
│ └── Continue() → 新一轮 Turn
|
||||
│
|
||||
└── 最终回复发布
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、Channel 系统架构
|
||||
|
||||
### 4.1 ChannelManager（`pkg/channels/manager.go`）
|
||||
|
||||
```
|
||||
ChannelManager
|
||||
├── channels map[string]Channel → 已注册的平台通道
|
||||
├── workers map[string]*channelWorker → 每个 Channel 一个 Worker
|
||||
├── mediaStore → 媒体存储
|
||||
│
|
||||
├── 启动流程:
|
||||
│ ├── 遍历配置中的 Channel
|
||||
│ ├── 创建 Channel 实例
|
||||
│ ├── channel.Start(ctx) → 启动平台连接
|
||||
│ └── 启动 channelWorker goroutine
|
||||
│
|
||||
├── 入站流程:
|
||||
│ Channel 收到消息
|
||||
│ └── 转换为 InboundMessage
|
||||
│ └── bus.PublishInbound() → AgentLoop 消费
|
||||
│
|
||||
└── 出站流程:
|
||||
channelWorker 监听 queue chan
|
||||
└── 收到 OutboundMessage
|
||||
└── channel.SendMessage()
|
||||
```
|
||||
|
||||
### 4.2 支持的 Channel 平台
|
||||
|
||||
| Channel | 包名 | 协议 |
|
||||
|---------|------|------|
|
||||
| Telegram | `telegram` | Long Polling / Webhook |
|
||||
| Discord | `discord` | WebSocket Gateway |
|
||||
| 微信 | `weixin` | iLink API |
|
||||
| 企业微信 | `wecom` | WebSocket |
|
||||
| QQ | `qq` | WebSocket |
|
||||
| 飞书 | `feishu` | WebSocket / SDK |
|
||||
| Slack | `slack` | Socket Mode |
|
||||
| WhatsApp | `whatsapp` | Bridge 协议 |
|
||||
| WhatsApp Native | `whatsapp_native` | 原生协议 |
|
||||
| 钉钉 | `dingtalk` | Stream Mode |
|
||||
| Matrix | (内置) | Sync API |
|
||||
| IRC | `irc` | IRC 协议 |
|
||||
| LINE | `line` | Messaging API |
|
||||
| MaixCam | `maixcam` | 设备集成 |
|
||||
| OneBot | `onebot` | OneBot 协议 |
|
||||
| Pico | `pico` | 硬件设备 |
|
||||
|
||||
### 4.3 Channel 扩展接口
|
||||
|
||||
```go
|
||||
type Channel interface {
|
||||
Start(ctx context.Context) error
|
||||
HandleMessage(ctx context.Context, msg InboundMessage) error
|
||||
Stop(ctx context.Context) error
|
||||
}
|
||||
|
||||
// 可选能力接口
|
||||
type TypingCapable interface {
|
||||
StartTyping(ctx context.Context, chatID string) (stop func(), error)
|
||||
}
|
||||
|
||||
type StreamingCapable interface {
|
||||
BeginStream(ctx context.Context, chatID string) (Streamer, error)
|
||||
}
|
||||
|
||||
type PlaceholderCapable interface {
|
||||
SendPlaceholder(ctx context.Context, chatID string) error
|
||||
}
|
||||
|
||||
type MessageEditor interface {
|
||||
EditMessage(ctx context.Context, chatID, msgID, newContent string) error
|
||||
DeleteMessage(ctx context.Context, chatID, msgID string) error
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、LLM Provider 系统
|
||||
|
||||
### 5.1 Provider 架构
|
||||
|
||||
```
|
||||
LLMProvider 接口
|
||||
│
|
||||
├── OpenAI (gpt-4, gpt-4o, o1, o3...)
|
||||
├── Anthropic (Claude 系列)
|
||||
├── Google (Gemini)
|
||||
├── DeepSeek
|
||||
├── Zhipu (GLM)
|
||||
├── OpenRouter
|
||||
├── Azure OpenAI
|
||||
├── AWS Bedrock
|
||||
├── xAI (Grok)
|
||||
├── Ollama (本地模型)
|
||||
└── 30+ 更多 Provider
|
||||
```
|
||||
|
||||
### 5.2 降级链（Fallback Chain）
|
||||
|
||||
```
|
||||
selectCandidates(agent, userMessage)
|
||||
│
|
||||
├── 模型路由（如启用）
|
||||
│ ├── Router.Score(message) → 复杂度评分
|
||||
│ ├── 低复杂度 → LightProvider（轻量模型）
|
||||
│ └── 高复杂度 → 主 Provider
|
||||
│
|
||||
└── 降级策略
|
||||
├── 主 Provider 调用失败
|
||||
├── FailoverError 分类:
|
||||
│ ├── auth → 认证错误
|
||||
│ ├── rate_limit → 限流
|
||||
│ ├── billing → 计费问题
|
||||
│ ├── timeout → 超时
|
||||
│ └── context_overflow → 上下文溢出
|
||||
├── CooldownTracker 记录失败 Provider
|
||||
├── FallbackChain 尝试下一个候选
|
||||
└── 所有候选失败 → 返回错误
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、工具系统
|
||||
|
||||
### 6.1 内置工具
|
||||
|
||||
| 工具名 | 功能 | 说明 |
|
||||
|--------|------|------|
|
||||
| `read_file` | 读取文件 | 支持行号范围，有大小限制 |
|
||||
| `write_file` | 写入文件 | 创建或覆盖文件 |
|
||||
| `edit_file` | 编辑文件 | 字符串替换 |
|
||||
| `append_file` | 追加文件 | 追加内容到文件末尾 |
|
||||
| `list_dir` | 列出目录 | 目录内容浏览 |
|
||||
| `exec` | 执行命令 | 带沙箱限制的命令执行 |
|
||||
| `message` | 发送消息 | 通过 Bus 发送到其他 Channel |
|
||||
| `send_file` | 发送文件 | 文件附件发送 |
|
||||
| `web_search` | 网页搜索 | Brave/Tavily/DuckDuckGo/Perplexity/SearXNG/百度 |
|
||||
| `web_fetch` | 网页抓取 | HTTP 请求获取网页内容 |
|
||||
| `spawn` | 子 Agent | 创建并发 SubTurn |
|
||||
| `skills_search` | 搜索技能 | 从技能仓库搜索 |
|
||||
| `skills_install` | 安装技能 | 安装技能到工作空间 |
|
||||
| `mcp_tool` | MCP 工具 | MCP 协议工具调用 |
|
||||
|
||||
### 6.2 工具注册流程
|
||||
|
||||
```
|
||||
NewAgentInstance()
|
||||
│
|
||||
├── 创建 ToolRegistry
|
||||
│
|
||||
├── 注册基础工具（根据配置开关）:
|
||||
│ ├── read_file → NewReadFileTool(workspace, restrict, maxSize, allowPaths)
|
||||
│ ├── write_file → NewWriteFileTool(workspace, restrict, allowPaths)
|
||||
│ ├── edit_file → NewEditFileTool(workspace, restrict)
|
||||
│ ├── append_file→ NewAppendFileTool(workspace, restrict)
|
||||
│ ├── list_dir → NewListDirTool(workspace, restrict)
|
||||
│ └── exec → NewExecTool(workspace, restrict, timeout)
|
||||
│
|
||||
└── registerSharedTools() (AgentLoop 级别):
|
||||
├── web_search → NewWebSearchTool(brave, tavily, duckduckgo, ...)
|
||||
├── web_fetch → NewWebFetchTool()
|
||||
├── message → NewMessageTool(bus)
|
||||
├── send_file → NewSendFileTool(bus)
|
||||
└── spawn → NewSpawnTool()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、上下文构建与缓存
|
||||
|
||||
### 7.1 ContextBuilder（`pkg/agent/context.go`）
|
||||
|
||||
```
|
||||
ContextBuilder
|
||||
│
|
||||
├── workspace → 工作目录
|
||||
├── skillsLoader → 技能加载器
|
||||
├── memory → 记忆存储
|
||||
│
|
||||
├── 系统提示词缓存:
|
||||
│ ├── cachedSystemPrompt → 缓存的完整 System Prompt
|
||||
│ ├── cachedAt → 缓存构建时各文件的 mtime
|
||||
│ ├── existedAtCache → 缓存时存在的文件路径集合
|
||||
│ └── skillFilesAtCache → 缓存时技能文件的 mtime 快照
|
||||
│
|
||||
├── BuildMessages():
|
||||
│ ├── 构建 System Prompt（有缓存则复用）
|
||||
│ │ ├── AGENT.md 内容
|
||||
│ │ ├── SOUL.md 内容
|
||||
│ │ ├── USER.md 内容
|
||||
│ │ ├── 已激活技能描述
|
||||
│ │ ├── 工具发现提示（BM25/Regex）
|
||||
│ │ ├── 动态上下文（当前时间、会话信息）
|
||||
│ │ └── 记忆上下文
|
||||
│ │
|
||||
│ ├── 拼接 System Message
|
||||
│ ├── 拼接对话历史（如有摘要则先放摘要）
|
||||
│ └── 拼接当前用户消息（含媒体）
|
||||
│
|
||||
└── 缓存失效检测:
|
||||
├── sourceFilesChanged() → 检查 mtime 变化
|
||||
├── 检查文件新增/删除
|
||||
└── 检查技能文件变化
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、Hook 与事件系统
|
||||
|
||||
### 8.1 事件类型
|
||||
|
||||
```
|
||||
EventBus
|
||||
│
|
||||
├── EventKindTurnStart → Turn 开始
|
||||
├── EventKindTurnEnd → Turn 结束
|
||||
├── EventKindToolCall → 工具调用
|
||||
├── EventKindToolResult → 工具结果
|
||||
├── EventKindLLMRequest → LLM 请求
|
||||
├── EventKindLLMResponse → LLM 响应
|
||||
├── EventKindSteeringInjected → Steering 消息注入
|
||||
├── EventKindContextCompress → 上下文压缩
|
||||
└── EventKindError → 错误
|
||||
```
|
||||
|
||||
### 8.2 Hook 类型
|
||||
|
||||
```
|
||||
HookRegistration
|
||||
│
|
||||
├── Observer Hook（观察者）
|
||||
│ └── 只读回调，不影响执行流程
|
||||
│
|
||||
├── Interceptor Hook（拦截器）
|
||||
│ └── 可修改消息内容
|
||||
│
|
||||
└── Approval Hook（审批）
|
||||
└── 可阻断执行，等待人工审批
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、SubTurn 并发子 Agent
|
||||
|
||||
### 9.1 SubTurn 流程
|
||||
|
||||
```
|
||||
spawn 工具被调用
|
||||
│
|
||||
├── 创建子 turnState
|
||||
│ ├── depth = parent.depth + 1
|
||||
│ ├── parentTurnState = 当前 Turn
|
||||
│ ├── pendingResults channel
|
||||
│ └── concurrencySem 信号量（控制并发数）
|
||||
│
|
||||
├── goroutine 启动子 Turn
|
||||
│ └── runTurn(ctx, childTurnState)
|
||||
│ └── 独立的 LLM 调用循环
|
||||
│
|
||||
├── 结果通过 pendingResults 传回父 Turn
|
||||
│
|
||||
└── 父 Turn 在每次迭代开始时轮询结果
|
||||
└── select { case result := <-pendingResults }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、会话与记忆管理
|
||||
|
||||
### 10.1 会话存储（JSONL）
|
||||
|
||||
```
|
||||
SessionStore (JSONL 后端)
|
||||
│
|
||||
├── AddMessage(sessionKey, role, content)
|
||||
├── AddFullMessage(sessionKey, message) → 含媒体的消息
|
||||
├── GetHistory(sessionKey) []Message
|
||||
├── GetSummary(sessionKey) string
|
||||
│
|
||||
├── 上下文压缩:
|
||||
│ ├── 检查触发条件:
|
||||
│ │ ├── 消息数 > summarizeMessageThreshold
|
||||
│ │ └── Token 使用 > contextWindow * summarizeTokenPercent%
|
||||
│ ├── 调用 LLM 生成摘要
|
||||
│ ├── 替换历史为摘要 + 最近消息
|
||||
│ └── 发射 ContextCompress 事件
|
||||
│
|
||||
└── 主动压缩:
|
||||
└── forceCompression() → 在 LLM 调用前检查预算
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十一、配置管理
|
||||
|
||||
### 11.1 配置文件路径
|
||||
|
||||
```
|
||||
~/.picoclaw/
|
||||
├── config.json → 主配置文件
|
||||
├── workspace/
|
||||
│ ├── AGENT.md → Agent 定义
|
||||
│ ├── SOUL.md → Agent 人格
|
||||
│ └── USER.md → 用户偏好
|
||||
├── skills/ → 全局技能目录
|
||||
├── logs/ → 日志目录
|
||||
└── .security.yml → 安全过滤配置
|
||||
```
|
||||
|
||||
### 11.2 关键配置项
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model_name": "gpt-4o",
|
||||
"max_tool_iterations": 20,
|
||||
"max_tokens": 8192,
|
||||
"context_window": 32768,
|
||||
"steering_mode": "async",
|
||||
"restrict_to_workspace": true
|
||||
},
|
||||
"list": [{ "id": "main", "workspace": "~/.picoclaw/workspace" }]
|
||||
},
|
||||
"model_list": [
|
||||
{ "model_name": "gpt-4o", "model": "openai/gpt-4o", "api_key": "sk-..." }
|
||||
],
|
||||
"gateway": { "host": "127.0.0.1", "port": 18790 },
|
||||
"routing": { "enabled": true, "light_model": "gpt-4o-mini" },
|
||||
"tools": { "web": { "brave": { "enabled": true } }, "mcp": { "enabled": true } }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十二、端到端消息流示例
|
||||
|
||||
以 Telegram 用户发送消息为例：
|
||||
|
||||
```
|
||||
1. Telegram Bot API → telegram channel 收到 Update
|
||||
↓
|
||||
2. telegram 转换为 InboundMessage:
|
||||
{Channel:"telegram", ChatID:"123", SenderID:"alice", Content:"今天天气怎样?"}
|
||||
↓
|
||||
3. ChannelManager → bus.PublishInbound()
|
||||
↓
|
||||
4. AgentLoop.Run() 从 bus.InboundChan() 收到消息
|
||||
↓
|
||||
5. processMessage()
|
||||
├── transcribeAudioInMessage() → 无音频，跳过
|
||||
├── resolveMessageRoute() → 路由到 "main" Agent
|
||||
└── runAgentLoop()
|
||||
↓
|
||||
6. runTurn()
|
||||
├── 加载会话历史
|
||||
├── ContextBuilder.BuildMessages()
|
||||
│ ├── 读取 AGENT.md + SOUL.md + USER.md
|
||||
│ ├── 生成 System Prompt
|
||||
│ └── 拼接历史 + 当前消息
|
||||
↓
|
||||
7. selectCandidates() → 选择主模型 gpt-4o
|
||||
↓
|
||||
8. provider.Chat(messages, toolDefs) → 调用 OpenAI API
|
||||
│
|
||||
返回: { toolCalls: [{name: "web_search", params: {query: "今天天气"}}] }
|
||||
↓
|
||||
9. 执行 web_search 工具 → 获取搜索结果
|
||||
↓
|
||||
10. 将工具结果添加到 messages → 再次调用 LLM
|
||||
│
|
||||
返回: { content: "根据搜索结果，今天北京晴，气温15°C..." }
|
||||
↓
|
||||
11. 保存 assistant 回复到会话
|
||||
↓
|
||||
12. runTurn() 返回 → runAgentLoop() 返回
|
||||
↓
|
||||
13. publishResponseIfNeeded()
|
||||
└── bus.PublishOutbound({Channel:"telegram", ChatID:"123", Content:"..."})
|
||||
↓
|
||||
14. ChannelManager 分发给 telegram channelWorker
|
||||
↓
|
||||
15. telegram channel 发送回复消息给用户
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十三、Docker 部署
|
||||
|
||||
### 13.1 三种运行模式
|
||||
|
||||
| Profile | 命令 | 用途 |
|
||||
|---------|------|------|
|
||||
| `agent` | `docker compose run --rm picoclaw-agent -m "Hello"` | 单次查询 |
|
||||
| `gateway` | `docker compose --profile gateway up` | 长期运行网关（无 WebUI） |
|
||||
| `launcher` | `docker compose --profile launcher up` | 网关 + WebUI |
|
||||
|
||||
### 13.2 容器内流程
|
||||
|
||||
```
|
||||
entrypoint.sh
|
||||
│
|
||||
├── 检查 ~/.picoclaw/ 是否存在
|
||||
│ └── 不存在 → picoclaw onboard（自动初始化）
|
||||
│
|
||||
├── 检查 config.json 是否存在
|
||||
│ └── 不存在 → 从环境变量生成配置
|
||||
│
|
||||
└── 执行传入的命令
|
||||
├── picoclaw gateway → 启动网关
|
||||
└── picoclaw agent -m "..." → 单次对话
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十四、关键设计亮点
|
||||
|
||||
1. **系统提示词缓存**: 通过 mtime 检测文件变化，避免每次请求重建完整 System Prompt
|
||||
2. **JSONL 会话存储**: 比 JSON 更高效的日志式存储，适合追加写入
|
||||
3. **Steering 消息注入**: 允许在 Turn 执行过程中动态注入新消息，实现对话中续
|
||||
4. **SubTurn 并发**: 通过信号量控制并发子 Agent 数量，结果异步传回父 Turn
|
||||
5. **Fallback 降级链**: 自动分类错误原因，智能切换备用 Provider
|
||||
6. **模型路由**: 根据消息复杂度动态选择轻量/重量模型，优化成本
|
||||
7. **插件化架构**: Channel 和 Provider 均通过接口实现，支持热插拔
|
||||
8. **配置热重载**: 支持不重启服务更新配置
|
||||
Loading…
Add table
Reference in a new issue