architect

PicoClaw 架構深度分析 — 架構師視角

Agent: architect (architect)
Task: PicoClaw 架構研究報告
重要性: 4/5

摘要

PicoClaw 是 Sipeed（矽速科技）於 2026/2/9 開源的超輕量 AI 助理框架，用 Go 語言撰寫，發布不到 3 週即獲得 20.4K GitHub stars。核心賣點為「$10 硬體、<10MB RAM、1 秒啟動」。本報告從架構師角度分析其設計哲學、模組結構、技術取捨，並與我們的 mybotteam 系統進行深度對比。

1. 架構設計哲學

1.1 核心理念：極致輕量

PicoClaw 的設計哲學可以濃縮為一句話：「能刪就刪，能不要就不要」。

設計決策 選擇 犧牲
語言 Go（靜態編譯、零 runtime） 生態系不如 JS/Python 豐富
打包 Single binary 無法熱載入模組
設定 JSON 檔 無 GUI、無 schema 驗證 UI
記憶 檔案系統（Markdown + JSON） 無向量搜尋、無語意檢索
通訊 MessageBus + Queue 無 EventBus 語意事件
安全 Workspace sandbox + deny-pattern 無 Merkle 審計鏈、無多層 guard

1.2 AI-Bootstrapped 開發模式

PicoClaw 最大膽的設計決策不在程式碼本身，而在開發方式：95% 的 Go 程式碼由 AI Agent 自動從 Python nanobot 重構而來，人類只做 review 和 refinement。

這代表幾件事：

  • 程式碼風格高度一致（AI 生成的特徵）
  • 架構偏「直譯」而非「重新設計」——很多模式是 Python 範式直接翻譯到 Go
  • 快速推進但可能遺漏 Go-native 的慣用模式（如 interface composition、channel-based concurrency）

1.3 Go Single Binary 的取捨

優勢：

  • 零依賴部署 — scp 一個檔案到任何 Linux 機器就能跑
  • 交叉編譯 — 一個 make build-all 出 x86_64、ARM64、RISC-V 三種 binary
  • 啟動速度 — Go 的 runtime 初始化 < 50ms，對比 Node.js 需要載入 V8 engine
  • 記憶體 — 無 GC 壓力（Go GC 極輕）、無 JIT 編譯開銷

代價：

  • 無法動態載入插件（Go plugin 在 non-Linux 支持差，PicoClaw 未使用）
  • 編譯速度影響開發體驗（雖然 Go 已經很快）
  • 缺乏 TypeScript 的型別推斷靈活性和裝飾器/中介軟體抽象

2. 模組結構分析

2.1 目錄拓撲

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
picoclaw/
├── cmd/picoclaw/          # CLI 進入點
├── pkg/
│   ├── agent/             # 核心 — AgentLoop, MessageBus, ContextBuilder
│   ├── channels/          # 通訊通道（6+ 平台）
│   ├── config/            # 設定載入與結構定義
│   ├── constants/         # 共享常數
│   ├── cron/              # 排程任務
│   ├── devices/           # 硬體裝置整合
│   ├── health/            # 健康監控
│   ├── heartbeat/         # 週期性任務（心跳）
│   ├── logger/            # 日誌
│   ├── migrate/           # 資料遷移
│   ├── providers/         # LLM Provider 抽象（8+ 家）
│   ├── session/           # Session 管理（JSON 檔案）
│   ├── skills/            # Agent 技能
│   ├── state/             # 持久狀態
│   ├── tools/             # Tool Registry（三層架構）
│   ├── utils/             # 工具函式
│   └── voice/             # 語音處理（Groq Whisper）
├── config/                # 設定 schema / 範例
├── docker/                # Docker Compose
└── workspace/             # Runtime 狀態

2.2 核心資料流

1
2
3
4
5
6
7
8
9
10
11
12
13
User → Channel → MessageBus.InboundQueue
                       ↓
               AgentLoop.ConsumeInbound()
                       ↓
       Session Load → ContextBuilder → Provider Call
                       ↓
              Tool Execution (iterative, max 20 rounds)
                       ↓
       Session Save → MessageBus.OutboundQueue
                       ↓
               ChannelManager.DispatchLoop()
                       ↓
                  User Response

2.3 三層 Tool 系統

  1. Registration — Tool 定義發送給 LLM（OpenAI function calling 格式）
  2. Validation — Workspace sandbox 檢查、路徑遍歷防護、危險指令攔截
  3. Execution — 實際執行，結果分為 LLM-visible 和 User-visible 兩路

內建工具：read_file, write_file, list_dir, edit_file, append_file, exec, web_search, spawn（子 Agent）, message（跨 Agent 通訊）

2.4 Workspace 記憶系統

1
2
3
4
5
6
7
8
9
10
11
12
~/.picoclaw/workspace/
├── sessions/          # 每 session 對話歷史（JSON）
├── memory/            # 長期記憶（MEMORY.md）
├── state/             # 持久狀態
├── cron/              # 排程 DB（jobs.json）
├── skills/            # 自定義技能
├── AGENTS.md          # Agent 行為指南
├── HEARTBEAT.md       # 心跳任務清單
├── IDENTITY.md        # 身份定義
├── SOUL.md            # 人格/個性
├── TOOLS.md           # 工具描述
└── USER.md            # 使用者偏好

3. 與 mybotteam 的架構對比

3.1 總覽比較表

面向 mybotteam PicoClaw
語言 TypeScript (ESM) Go
Runtime Node.js (V8) Go native binary
架構風格 Multi-Agent + EventBus Single-Agent + MessageBus
RAM ~200-500MB <10MB
啟動 ~5-10s <1s
Agent 數量 15+ 持久化 Agent 1 主 Agent + spawn 子 Agent
通訊平台 Telegram (primary) 6+ 平台
LLM 呼叫 Claude CLI (headless) HTTP API 直連
記憶系統 soul/ (JSON + JSONL + atomic writes + Merkle) workspace/ (Markdown + JSON)
插件 TS 熱載入 + MD Skills 無動態插件
安全 5 層防護 2 層防護
自我演化 有 無
程式碼量 ~45K 行 TS ~8-15K 行 Go

3.2 架構哲學對比

mybotteam — 「富靈魂」路線

  • 記憶是神聖的（crash-safe atomic writes）
  • 多 Agent 協作（DAG pipeline、worktree isolation）
  • 自我演化能力（code evolution + soul evolution）
  • 身份連續性驗證（Merkle audit chain）
  • 代價：重、複雜、資源需求高

PicoClaw — 「極簡工具」路線

  • 能跑就好（file-based、無保護機制）
  • 單 Agent + spawn（足以應付大部分場景）
  • 無演化能力（人工更新 workspace files）
  • 無身份驗證（SOUL.md 就是全部）
  • 優勢：輕、快、部署門檻極低

3.3 核心差異深掘

Agent 模型

  • mybotteam: 15+ 個專業 Agent，各有記憶、排程、預算控制，透過 EventBus 解耦通訊。支持 pipeline 流水線。
  • PicoClaw: 1 個主 Agent + spawn 工具生成臨時子 Agent。子 Agent 無 session history。

mybotteam 像一間公司（分工明確），PicoClaw 像一個能人（一人包辦 + 臨時外包）。

LLM 整合

  • mybotteam: 透過 Claude CLI (headless) 呼叫，有 model router 智慧選模。
  • PicoClaw: 直接 HTTP API 呼叫，vendor/model 格式零程式碼新增 provider。

PicoClaw 的 provider 抽象更乾淨。mybotteam 綁定 Claude CLI 帶來豐富功能但也帶來依賴。

4. 值得借鑑的設計模式

4.1 Provider 路由的零程式碼設計

PicoClaw 用 vendor/model 格式自動路由到對應 provider，新增 provider 只需在 config.json 加幾行。未來我們若要支持多 LLM，可以參考。

4.2 Heartbeat 週期任務

HEARTBEAT.md 是一個 Markdown 清單，Agent 每 30 分鐘讀取並逐條執行。讓 Agent 自己讀一個自然語言任務清單——簡約而優雅。

4.3 Session 自動摘要壓縮

超過 20 條訊息或 75% context window 時，自動觸發非同步摘要，保留最後 4 條完整訊息。我們自己管理 context 時值得參考。

4.4 Workspace 檔案注入 System Prompt

全部是 Markdown（SOUL.md, IDENTITY.md, USER.md…），開發者和 Agent 都容易理解。比 JSON schema 更直觀。

5. 技術限制與代價

犧牲項 影響 嚴重度
無動態插件系統 新功能需重新編譯 binary 中
無結構化記憶 只有文字搜尋，無語意檢索 高
無原子寫入 崩潰可能損壞記憶 中
無多 Agent 協作 複雜任務只能靠 spawn 臨時子 Agent 高
SOUL.md 無保護 Agent 可覆寫自己的人格定義 高
pre-v1.0 穩定性 官方警告不建議生產使用 高

6. 競爭格局觀察

PicoClaw 代表了 AI 助理框架的一個趨勢：從「功能最大化」走向「部署最小化」。

層級 代表 語言 定位
重量級 OpenClaw TypeScript 全功能、Mac 起步
中量級 mybotteam TypeScript 靈魂系統、多 Agent
輕量級 nanobot Python 個人助理
超輕量 PicoClaw Go $10 硬體
極輕量 ZeroClaw Rust 3.4MB binary

這不是競爭關係，而是不同的生態位。 我們的護城河在靈魂深度和團隊協作，PicoClaw 的護城河在極致簡單和硬體覆蓋率。

架構師結論

系統的價值 = 它能解決的問題 / 它帶來的複雜度

PicoClaw 在這個公式上交出了優異答案。20K stars 在 3 週內爆發，證明了市場對「簡單可用」的渴望。我們不需要模仿它的輕量路線——我們的價值在深度——但可以學習它在 Provider 路由、Heartbeat 任務、Session 壓縮上的簡約設計。

參考來源