PicoClaw 架构设计，极致轻量・插件化・高可用 AI 智能体

1. 项目概述

1.1 项目简介

PicoClaw 是一个用 Go 语言重构的超轻量级个人 AI 助手，灵感来源于 nanobot。项目采用 AI 自举的方式，由 AI 智能体主导了整个架构迁移和代码优化过程。

1.2 核心特性

• 超轻量级：内存占用 < 10MB，比 Clawdbot 小 99%
• 极低硬件成本：可在价值 $10 的硬件上运行
• 极速启动：在 0.6GHz 单核上 1 秒内启动
• 多平台支持：单一自包含二进制，支持 RISC-V、ARM、x86
• AI 自举：95% 的核心代码由 AI 生成

1.3 技术栈

• 语言：Go 1.25.7
• 核心依赖：
  • github.com/openai/openai-go/v3：OpenAI 兼容 API
  • github.com/anthropics/anthropic-sdk-go：Anthropic API
  • github.com/mymmrac/telego：Telegram Bot
  • github.com/bwmarrin/discordgo：Discord Bot
  • github.com/slack-go/slack：Slack 集成
  • 以及其他 10+ 种渠道的 SDK

2. 架构设计原则

2.1 核心设计原则

2.2 架构风格

采用 分层模块化架构，通过清晰的职责分离和接口抽象实现高内聚低耦合。

3. 系统架构

3.1 整体架构图

┌─────────────────────────────────────────────────────────────────────────┐
│ 应用层 (App Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ CLI (cmd) │ │ Gateway │ │ Onboard │ │ Auth │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 业务层 (Business Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ Agent │ │ Channels │ │ Cron │ │ Skills │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 核心层 (Core Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ Providers │ │ Tools │ │ Session │ │ Bus │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 基础设施层 (Infrastructure Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ Config │ │ Logger │ │ State │ │ Utils │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

3.2 目录结构说明

picoclaw-main/
├── cmd/picoclaw/ # CLI 入口和命令处理
│ ├── main.go # 主入口
│ ├── cmd_*.go # 各子命令实现
├── pkg/ # 核心包
│ ├── agent/ # 智能体核心
│ ├── auth/ # 认证模块
│ ├── bus/ # 消息总线
│ ├── channels/ # 渠道适配器
│ ├── config/ # 配置管理
│ ├── constants/ # 常量定义
│ ├── cron/ # 定时任务
│ ├── devices/ # 设备管理
│ ├── health/ # 健康检查
│ ├── heartbeat/ # 心跳任务
│ ├── logger/ # 日志
│ ├── migrate/ # 数据迁移
│ ├── providers/ # LLM 提供商
│ ├── routing/ # 路由管理
│ ├── session/ # 会话管理
│ ├── skills/ # 技能管理
│ ├── state/ # 状态管理
│ ├── tools/ # 工具集
│ ├── utils/ # 工具函数
│ └── voice/ # 语音转文字
├── config/ # 配置示例
├── docs/ # 文档
└── workspace/ # 工作区模板

4. 核心模块详解

4.1 Agent 模块（pkg/agent）

4.1.1 模块职责

Agent 是整个系统的核心，负责：

• 智能体实例的生命周期管理
• 上下文构建
• 工具调用循环
• 会话管理
• 记忆管理

4.1.2 核心数据结构

// AgentInstance 表示一个完整配置的智能体实例
type AgentInstance struct {
ID string
Name string
Model string
Fallbacks []string
Workspace string
MaxIterations int
MaxTokens int
Temperature float64
ContextWindow int
Provider providers.LLMProvider
Sessions *session.SessionManager
ContextBuilder *ContextBuilder
Tools *tools.ToolRegistry
Subagents *config.SubagentsConfig
SkillsFilter []string
Candidates []providers.FallbackCandidate
}

4.1.3 工作流程

用户输入
↓
加载/创建会话
↓
构建上下文 (ContextBuilder)
↓
┌─────────────────────────────────┐
│ 工具调用循环 (Tool Loop) │
│ ┌───────────────────────────┐ │
│ │ 调用 LLM 获取响应 │ │
│ └───────────────┬───────────┘ │
│ ↓ │
│ ┌───────────────────────────┐ │
│ │ 判断是否需要工具调用？ │ │
│ └───────────────┬───────────┘ │
│ ↓ │
│ ┌───────────────────────────┐ │
│ │ 执行工具并获取结果 │ │
│ └───────────────┬───────────┘ │
│ ↓ │
│ ┌───────────────────────────┐ │
│ │ 将结果加入上下文 │ │
│ └───────────────────────────┘ │
└─────────────────────────────────┘
↓ (达到最大迭代或无工具调用)
返回最终响应给用户

4.2 Providers 模块（pkg/providers）

4.2.1 模块职责

Providers 模块负责与各种 LLM 提供商对接，提供统一的接口。

4.2.2 核心接口

// LLMProvider 定义了 LLM 提供商的统一接口
type LLMProvider interface {
Chat(
ctx context.Context,
messages []Message,
tools []ToolDefinition,
model string,
options map[string]any,
) (*LLMResponse, error)
GetDefaultModel() string
}

4.2.3 支持的提供商

• OpenAI 兼容协议：OpenRouter、OpenAI、Zhipu、Groq、vLLM、Ollama 等
• Anthropic 协议：Claude 原生 API
• 自定义协议：Antigravity、GitHub Copilot 等

4.2.4 容错与降级机制

Primary Model (首选)
↓ (失败)
Fallback 1
↓ (失败)
Fallback 2
↓ (失败)
…

错误分类：

• FailoverAuth：认证失败
• FailoverRateLimit：速率限制
• FailoverBilling：计费问题
• FailoverTimeout：超时
• FailoverFormat：格式错误（不可重试）
• FailoverOverloaded：服务过载
• FailoverUnknown：未知错误

4.3 Channels 模块（pkg/channels）

4.3.1 模块职责

Channels 模块负责与各种聊天应用对接，提供统一的消息收发接口。

4.3.2 支持的渠道

4.3.3 消息流转

外部渠道 (Telegram/Discord/…)
↓
Channel Adapter
↓
Message Bus (bus.InboundMessage)
↓
Agent Processing
↓
Message Bus (bus.OutboundMessage)
↓
Outbound Dispatcher
↓
Channel Adapter
↓
外部渠道

4.3.4 Manager 架构

ChannelManager 负责所有渠道的生命周期管理，包括：

• 初始化配置的渠道
• 启动/停止所有渠道
• 分发出站消息
• 状态查询

4.4 Tools 模块（pkg/tools）

4.4.1 模块职责

Tools 模块提供智能体可使用的各种工具。

4.4.2 内置工具

4.4.3 安全沙箱

默认启用沙箱限制：

• 文件操作限制在 workspace 内
• 命令执行路径限制在 workspace 内
• 阻止危险命令（如 rm -rf、format 等）

4.5 Session 模块（pkg/session）

4.5.1 模块职责

Session 模块负责会话历史的持久化和管理。

4.5.2 存储结构

~/.picoclaw/workspace/sessions/
├── <session-key-1>.json
├── <session-key-2>.json
└── …

4.6 Skills 模块（pkg/skills）

4.6.1 模块职责

Skills 模块负责技能的安装、加载、搜索和管理，是 PicoClaw 扩展性的核心模块之一。

4.6.2 核心设计原理

4.6.2.1 技能概念

技能是一种可扩展的机制，允许智能体学习和应用特定领域的专业知识。技能本质上是 Markdown 格式的知识文档，包含：

• 领域特定的指令和最佳实践
• 工具使用示例
• 工作流程指南

4.6.2.2 三层加载机制

Skills 模块采用三层优先级的加载机制，允许灵活的技能覆盖：

┌─────────────────────────────────────────┐
│ 1. Workspace Skills (最高优先级) │
│ ~/.picoclaw/workspace/skills/ │
│ 项目级别，可覆盖全局和内置技能 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 2. Global Skills (次优先级) │
│ ~/.picoclaw/skills/ │
│ 全局级别，可覆盖内置技能 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 3. Builtin Skills (最低优先级) │
│ 系统内置 │
└─────────────────────────────────────────┘

设计优势：

• 用户可以在项目级别自定义技能
• 全局技能可供所有项目使用
• 内置技能提供基础功能

4.6.3 核心数据结构

// SkillsLoader 负责从三个源加载技能
type SkillsLoader struct {
workspace string
workspaceSkills string // workspace/skills
globalSkills string // ~/.picoclaw/skills
builtinSkills string // 内置目录
}

// SkillInfo 表示一个技能的元信息
type SkillInfo struct {
Name string // 技能名称
Path string // SKILL.md 文件路径
Source string // 来源: workspace/global/builtin
Description string // 技能描述
}

// SkillRegistry 技能注册中心接口
type SkillRegistry interface {
Name() string
Search(ctx context.Context, query string, limit int) ([]SearchResult, error)
GetSkillMeta(ctx context.Context, slug string) (*SkillMeta, error)
DownloadAndInstall(ctx context.Context, slug, version, targetDir string) (*InstallResult, error)
}

// RegistryManager 管理多个技能注册中心
type RegistryManager struct {
registries []SkillRegistry
maxConcurrent int
}

4.6.4 技能文件格式

一个技能由 SKILL.md 文件定义，包含 Frontmatter 和内容两部分：

—
name: github
description: "Interact with GitHub using the `gh` CLI"
metadata: {"nanobot":{"emoji":"🐙","requires":{"bins":["gh"]}}}
—

# GitHub Skill

Use the `gh` CLI to interact with GitHub…

## 示例
```bash
gh pr checks 55 –repo owner/repo

Frontmatter 支持格式：

4.6.5 工作流程

4.6.5.1 技能加载流程

ContextBuilder 构建上下文
↓
SkillsLoader.ListSkills()
↓
遍历三个源目录
↓
┌─────────────────────────────────────┐
│ 1. 读取 workspace/skills/ │
│ 2. 读取 ~/.picoclaw/skills/ │
│ 3. 读取 builtin/skills/ │
└─────────────────────────────────────┘
↓
解析 SKILL.md 的 Frontmatter
↓
验证技能信息（名称、描述）
↓
去重（高优先级覆盖低优先级）
↓
返回 SkillInfo 列表

4.6.5.2 技能搜索流程（多注册中心并发搜索）

用户搜索技能
↓
RegistryManager.SearchAll()
↓
┌─────────────────────────────────────────────┐
│ 创建 Goroutine 池（限制并发数） │
│ ┌─────────────────────────────────────┐ │
│ │ Registry 1 (ClawHub) │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ Registry 2 (其他) │ │
│ └─────────────────────────────────────┘ │
│ … │
└─────────────────────────────────────────────┘
↓
收集所有搜索结果
↓
按分数降序排序
↓
限制返回数量
↓
返回给用户

4.6.5.3 技能安装流程

用户执行 picoclaw skills install <skill-name>
↓
SkillInstaller.InstallFromGitHub()
↓
检查技能是否已存在
↓
从 GitHub 下载 SKILL.md
↓
创建技能目录
↓
写入 SKILL.md 文件
↓
完成安装

4.6.6 核心功能

4.6.6.1 技能列表与加载

// 列出所有可用技能
func (sl *SkillsLoader) ListSkills() []SkillInfo

// 加载指定技能内容（返回 Markdown，去除 Frontmatter）
func (sl *SkillsLoader) LoadSkill(name string) (string, bool)

// 为上下文加载多个技能
func (sl *SkillsLoader) LoadSkillsForContext(skillNames []string) string

// 构建技能摘要（XML 格式）
func (sl *SkillsLoader) BuildSkillsSummary() string

4.6.6.2 技能安装与卸载

// 从 GitHub 安装技能
func (si *SkillInstaller) InstallFromGitHub(ctx context.Context, repo string) error

// 卸载技能
func (si *SkillInstaller) Uninstall(skillName string) error

// 列出可用技能
func (si *SkillInstaller) ListAvailableSkills(ctx context.Context) ([]AvailableSkill, error)

4.6.6.3 多注册中心管理

// 添加注册中心
func (rm *RegistryManager) AddRegistry(r SkillRegistry)

// 并发搜索所有注册中心
func (rm *RegistryManager) SearchAll(ctx context.Context, query string, limit int) ([]SearchResult, error)

// 获取指定注册中心
func (rm *RegistryManager) GetRegistry(name string) SkillRegistry

4.6.7 技能目录结构

~/.picoclaw/
├── skills/ # 全局技能目录
│ ├── github/
│ │ └── SKILL.md
│ └── …
└── workspace/
└── skills/ # 项目级别技能目录
├── weather/
│ └── SKILL.md
└── …

4.6.8 验证与安全

技能加载时会进行以下验证：

• 名称验证：必须是字母数字加连字符，不超过 64 字符
• 描述验证：必填，不超过 1024 字符
• 来源去重：高优先级技能覆盖低优先级同名技能

4.6.9 CLI 命令

Skills 模块提供完整的 CLI 命令：

4.6.10 设计优势

5. 关键设计决策

5.1 模型配置设计（model_list）

5.1.1 设计原则

采用模型为中心的配置方式，而非提供商为中心。

5.1.2 优势

• 零代码添加新提供商
• 灵活的多智能体支持
• 模型降级和负载均衡
• 集中化配置管理

5.1.3 格式

{
"model_list": [
{
"model_name": "gpt-5.2",
"model": "openai/gpt-5.2",
"api_key": "sk-…",
"api_base": "https://api.openai.com/v1"
}
]
}

5.2 消息总线设计（bus）

5.2.1 设计原则

采用事件驱动架构，通过消息总线解耦各模块。

5.2.2 消息类型

• InboundMessage：入站消息（从渠道到智能体）
• OutboundMessage：出站消息（从智能体到渠道）

5.3 工作区设计

5.3.1 目录结构

~/.picoclaw/workspace/
├── sessions/ # 会话历史
├── memory/ # 长期记忆
├── state/ # 持久化状态
├── cron/ # 定时任务数据库
├── skills/ # 自定义技能
├── AGENTS.md # 智能体行为指南
├── HEARTBEAT.md # 周期性任务提示
├── IDENTITY.md # 智能体身份
├── SOUL.md # 智能体灵魂
├── TOOLS.md # 工具描述
└── USER.md # 用户偏好

5.4 心跳任务（Heartbeat）

5.4.1 设计原理

定期读取 HEARTBEAT.md 文件并执行任务。

5.4.2 异步处理

对于耗时任务，使用 spawn 工具创建子智能体异步执行，避免阻塞心跳。

6. 数据流

6.1 完整消息处理流程

1. 用户在 Telegram 发送消息
↓
2. Telegram Channel 接收消息
↓
3. 转换为 InboundMessage 发送到 Bus
↓
4. Gateway 从 Bus 消费 InboundMessage
↓
5. 创建/加载会话
↓
6. ContextBuilder 构建上下文
↓
7. Agent Loop 开始：
├─ 调用 Provider 发送请求
├─ 接收 LLM 响应
├─ 判断是否需要工具调用
├─ 如需要，执行工具
├─ 将结果加入上下文
└─ 重复直到结束
↓
8. 生成 OutboundMessage 发送到 Bus
↓
9. Outbound Dispatcher 从 Bus 消费消息
↓
10. 找到对应的 Channel
↓
11. Channel 发送消息给用户

7. 扩展性设计

7.1 添加新的 LLM 提供商

步骤：

7.2 添加新的聊天渠道

步骤：

7.3 添加新的工具

步骤：

7.4 添加新的技能注册中心

步骤：

7.5 创建自定义技能

步骤：

8. 性能优化策略

8.1 内存优化

• 避免不必要的对象分配
• 使用对象池复用资源
• 及时释放不再需要的引用
• 流式处理大文本

8.2 启动优化

• 延迟加载非核心模块
• 并行初始化独立组件
• 最小化启动时的 I/O 操作

8.3 并发设计

• 使用 Goroutine 处理并发请求
• 合理使用 Channel 进行协程间通信
• 避免共享状态，使用消息传递

9. 安全设计

9.1 访问控制

• 渠道级别的用户白名单
• 工作区沙箱限制

9.2 命令安全

• 阻止危险命令模式
• 路径验证

9.3 数据隔离

• 每个智能体独立的工作区
• 会话数据隔离存储

10. 部署架构

10.1 单机部署

PicoClaw Binary
├─ Agent
├─ Channels (Telegram/Discord/…)
└─ Local Workspace

10.2 Docker 部署

Docker Container
├─ picoclaw-gateway (服务)
├─ picoclaw-agent (一次性)
└─ Volume: config & workspace

11. 总结

PicoClaw 采用清晰的分层模块化架构，通过以下关键设计实现了超轻量级和高性能：

这套架构使得 PicoClaw 能够在极低资源的硬件上运行，同时保持功能的完整性和可扩展性。

关键点回顾