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 核心设计原则

1. 轻量化优先：所有设计决策都以最小化内存占用为首要考虑
2. 零依赖原则：核心功能尽量减少外部依赖
3. 插件化架构：各功能模块松耦合，易于扩展
4. 容错设计：内置多重容错和降级机制
5. 安全沙箱：默认限制智能体的操作范围

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 支持的渠道

渠道	特点
Telegram	易于配置，只需 Token
Discord	需要 Bot Token + Intents
QQ	AppID + AppSecret
DingTalk	中等难度，需要应用凭证
LINE	需要凭证 + Webhook URL
WeCom	支持机器人和自建应用两种方式
Slack	需 Bot Token
WhatsApp	需要 Bridge URL
Feishu	支持 32/64 位两种
MaixCAM	相机设备集成
OneBot	通用机器人协议

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 内置工具

工具	功能
read_file	读取文件
write_file	写入文件
list_dir	列出目录
edit_file	编辑文件
append_file	追加文件
exec	执行命令
web_search	网页搜索
spawn	生成子智能体
message	发送消息
cron	定时任务
skills_install	安装技能
skills_search	搜索技能

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 支持格式：**

1. **YAML 格式**（推荐）
2. **JSON 格式**（向后兼容）

##### 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 ↓ SkillInstaller.InstallFromGitHub() ↓ 检查技能是否已存在 ↓ 从 GitHub 下载 SKILL.md ↓ 创建技能目录 ↓ 写入 SKILL.md 文件 ↓ 完成安装

##### 4.6.6 核心功能

###### 4.6.6.1 技能列表与加载

```go
// 列出所有可用技能
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 命令

命令	功能
picoclaw skills list	列出已安装的技能
picoclaw skills install <repo>	从 GitHub 安装技能
picoclaw skills remove <name>	卸载技能
picoclaw skills search <query>	搜索可用技能
picoclaw skills show <name>	显示技能详情
picoclaw skills install-builtin	安装内置技能
picoclaw skills list-builtin	列出内置技能

4.6.10 设计优势

1. 声明式设计：技能是纯文本，易于编写和理解
2. 三层覆盖机制：灵活的优先级管理
3. 多注册中心支持：可扩展的技能生态
4. 并发搜索：高效的多源搜索
5. 零运行时开销：技能仅在需要时加载到上下文
6. 向后兼容：支持 JSON 和 YAML 两种 Frontmatter 格式

---

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 提供商

步骤：

1. 在 pkg/providers/ 下创建新目录
2. 实现 LLMProvider 接口
3. 在 factory.go 中注册
4. 配置 model_list 即可使用（对于 OpenAI 兼容协议）

7.2 添加新的聊天渠道

步骤：

1. 在 pkg/channels/ 下创建新文件
2. 实现 Channel 接口
3. 在 manager.go 的 initChannels() 中添加初始化代码
4. 在 config/config.go 中添加配置结构

7.3 添加新的工具

步骤：

1. 在 pkg/tools/ 下创建新文件
2. 实现 Tool 接口
3. 在 ToolRegistry 中注册

7.4 添加新的技能注册中心

步骤：

1. 在 pkg/skills/ 下创建新文件（如 myregistry.go）
2. 在 config/config.go 中添加配置结构
3. 在 registry.go 的 NewRegistryManagerFromConfig() 中添加初始化代码

实现 SkillRegistry 接口：

type MyRegistry struct{
	// 配置字段
}
func(r *MyRegistry)Name()string{return"myregistry"}
func(r *MyRegistry)Search(ctx context.Context, query string, limit int)([]SearchResult,error){// 实现搜索逻辑}
func(r *MyRegistry)GetSkillMeta(ctx context.Context, slug string)(*SkillMeta,error){// 实现获取元数据逻辑}
func(r *MyRegistry)DownloadAndInstall(ctx context.Context, slug, version, targetDir string)(*InstallResult,error){// 实现下载和安装逻辑}

7.5 创建自定义技能

步骤：

安装到 workspace：

cp -r my-skill ~/.picoclaw/workspace/skills/

编写 SKILL.md，包含 Frontmatter 和内容：

---
name: my-skill
description: "我的自定义技能"
---
# My Skill
技能内容...

创建技能目录结构：

my-skill/
└── SKILL.md

---

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 采用清晰的分层模块化架构，通过以下关键设计实现了超轻量级和高性能：

1. 清晰的职责分离：各模块高内聚低耦合
2. 统一的接口抽象：Provider、Channel、Tool 等接口
3. 事件驱动架构：消息总线解耦各模块
4. 容错与降级：多重保障机制
5. 安全沙箱：默认限制保护系统
6. 可扩展设计：易于添加新功能

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

关键点回顾

1. 核心架构采用四层分层设计（应用层→业务层→核心层→基础设施层），各层职责清晰、低耦合；
2. 核心特性围绕'轻量化'展开，通过内存优化、启动优化、沙箱限制等实现低资源占用；
3. 扩展性设计完善，支持新增 LLM 提供商、聊天渠道、工具、技能注册中心等，且技能系统采用三层优先级加载机制，灵活性高。