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

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()stringSearch(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 <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 设计优势

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 提供商、聊天渠道、工具、技能注册中心等，且技能系统采用三层优先级加载机制，灵活性高。