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 表示一个完整配置的智能体实例typeAgentInstancestruct{IDstringNamestringModelstringFallbacks[]stringWorkspacestringMaxIterationsintMaxTokensintTemperaturefloat64ContextWindowintProvider providers.LLMProvider Sessions*session.SessionManager ContextBuilder*ContextBuilder Tools*tools.ToolRegistry Subagents*config.SubagentsConfig SkillsFilter[]stringCandidates[]providers.FallbackCandidate}

4.1.3 工作流程

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

4.2 Providers 模块（pkg/providers）

4.2.1 模块职责

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

4.2.2 核心接口

// LLMProvider 定义了 LLM 提供商的统一接口typeLLMProviderinterface{Chat(ctx context.Context,messages[]Message,tools[]ToolDefinition,modelstring,optionsmap[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 负责从三个源加载技能typeSkillsLoaderstruct{workspacestringworkspaceSkillsstring// workspace/skillsglobalSkillsstring// ~/.picoclaw/skillsbuiltinSkillsstring// 内置目录}// SkillInfo 表示一个技能的元信息typeSkillInfostruct{Namestring// 技能名称Pathstring// SKILL.md 文件路径Sourcestring// 来源: workspace/global/builtinDescriptionstring// 技能描述}// SkillRegistry 技能注册中心接口typeSkillRegistryinterface{Name()stringSearch(ctx context.Context,querystring,limitint)([]SearchResult,error)GetSkillMeta(ctx context.Context,slugstring)(*SkillMeta,error)DownloadAndInstall(ctx context.Context,slug,version,targetDirstring)(*InstallResult,error)}// RegistryManager 管理多个技能注册中心typeRegistryManagerstruct{registries[]SkillRegistry maxConcurrentint}

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(namestring)(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,repostring)error// 卸载技能func(si*SkillInstaller)Uninstall(skillNamestring)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,querystring,limitint)([]SearchResult,error)// 获取指定注册中心func(rm*RegistryManager)GetRegistry(namestring)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 命令：

命令	功能
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. 实现SkillRegistry接口：

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

3. 在config/config.go中添加配置结构
4. 在registry.go的NewRegistryManagerFromConfig()中添加初始化代码

7.5 创建自定义技能

步骤：

1. 创建技能目录结构：

   my-skill/ └── SKILL.md

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

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

3. 安装到 workspace：

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

---

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