1. 项目概述1.1 项目简介PicoClaw 是一个用 Go 语言重构的超轻量级个人 AI 助手灵感来源于 nanobot。项目采用 AI 自举的方式由 AI 智能体主导了整个架构迁移和代码优化过程。1.2 核心特性超轻量级内存占用 10MB比 Clawdbot 小 99%极低硬件成本可在价值 $10 的硬件上运行极速启动在 0.6GHz 单核上 1 秒内启动多平台支持单一自包含二进制支持 RISC-V、ARM、x86AI 自举95% 的核心代码由 AI 生成1.3 技术栈语言Go 1.25.7核心依赖github.com/openai/openai-go/v3OpenAI 兼容 APIgithub.com/anthropics/anthropic-sdk-goAnthropic APIgithub.com/mymmrac/telegoTelegram Botgithub.com/bwmarrin/discordgoDiscord Botgithub.com/slack-go/slackSlack 集成以及其他 10 种渠道的 SDK2. 架构设计原则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/agent4.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/providers4.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/channels4.3.1 模块职责Channels 模块负责与各种聊天应用对接提供统一的消息收发接口。4.3.2 支持的渠道渠道特点Telegram易于配置只需 TokenDiscord需要 Bot Token IntentsQQAppID AppSecretDingTalk中等难度需要应用凭证LINE需要凭证 Webhook URLWeCom支持机器人和自建应用两种方式Slack需 Bot TokenWhatsApp需要 Bridge URLFeishu支持 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/tools4.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/session4.5.1 模块职责Session 模块负责会话历史的持久化和管理。4.5.2 存储结构~/.picoclaw/workspace/sessions/ ├── session-key-1.json ├── session-key-2.json └── ...4.6 Skills 模块pkg/skills4.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/repoFrontmatter 支持格式YAML 格式推荐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去除 Frontmatterfunc(sl*SkillsLoader)LoadSkill(namestring)(string,bool)// 为上下文加载多个技能func(sl*SkillsLoader)LoadSkillsForContext(skillNames[]string)string// 构建技能摘要XML 格式func(sl*SkillsLoader)BuildSkillsSummary()string4.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)SkillRegistry4.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 设计优势声明式设计技能是纯文本易于编写和理解三层覆盖机制灵活的优先级管理多注册中心支持可扩展的技能生态并发搜索高效的多源搜索零运行时开销技能仅在需要时加载到上下文向后兼容支持 JSON 和 YAML 两种 Frontmatter 格式5. 关键设计决策5.1 模型配置设计model_list5.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 消息总线设计bus5.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 心跳任务Heartbeat5.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 提供商步骤在pkg/providers/下创建新目录实现LLMProvider接口在factory.go中注册配置model_list即可使用对于 OpenAI 兼容协议7.2 添加新的聊天渠道步骤在pkg/channels/下创建新文件实现Channel接口在manager.go的initChannels()中添加初始化代码在config/config.go中添加配置结构7.3 添加新的工具步骤在pkg/tools/下创建新文件实现Tool接口在ToolRegistry中注册7.4 添加新的技能注册中心步骤在pkg/skills/下创建新文件如myregistry.go实现SkillRegistry接口typeMyRegistrystruct{// 配置字段}func(r*MyRegistry)Name()string{returnmyregistry}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){// 实现下载和安装逻辑}在config/config.go中添加配置结构在registry.go的NewRegistryManagerFromConfig()中添加初始化代码7.5 创建自定义技能步骤创建技能目录结构my-skill/ └── SKILL.md编写SKILL.md包含 Frontmatter 和内容--- name: my-skill description: 我的自定义技能 --- # My Skill 技能内容...安装到 workspacecp-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 Workspace10.2 Docker 部署Docker Container ├─ picoclaw-gateway (服务) ├─ picoclaw-agent (一次性) └─ Volume: config workspace11. 总结PicoClaw 采用清晰的分层模块化架构通过以下关键设计实现了超轻量级和高性能清晰的职责分离各模块高内聚低耦合统一的接口抽象Provider、Channel、Tool 等接口事件驱动架构消息总线解耦各模块容错与降级多重保障机制安全沙箱默认限制保护系统可扩展设计易于添加新功能这套架构使得 PicoClaw 能够在极低资源的硬件上运行同时保持功能的完整性和可扩展性。关键点回顾核心架构采用四层分层设计应用层→业务层→核心层→基础设施层各层职责清晰、低耦合核心特性围绕“轻量化”展开通过内存优化、启动优化、沙箱限制等实现低资源占用扩展性设计完善支持新增 LLM 提供商、聊天渠道、工具、技能注册中心等且技能系统采用三层优先级加载机制灵活性高。