+
+PicoClaw: Go で書かれた超効率 AI アシスタント
+ +$10 ハードウェア · 10MB RAM · 1秒起動 · 行くぜ、シャコ！
+ + +
+
+
+
+
|
+
+ |
+
+
+ |
+
+
+
+## 🦾 デモンストレーション
+### 🛠️ スタンダードアシスタントワークフロー
+🧩 フルスタックエンジニア |
+ 🗂️ ログ＆計画管理 |
+ 🔎 Web 検索＆学習 |
+
|---|---|---|
|
+
|
+
|
+
| 開発 · デプロイ · スケール | +スケジュール · 自動化 · メモリ | +発見 · インサイト · トレンド | +
+
+
+## 🐛 トラブルシューティング
+
+### Web 検索で「API 設定の問題」と表示される
+
+検索 API キーをまだ設定していない場合、これは正常です。PicoClaw は手動検索用の便利なリンクを提供します。
+
+Web 検索を有効にするには：
+1. [https://brave.com/search/api](https://brave.com/search/api) で無料の API キーを取得（月 2000 クエリ無料）
+2. `~/.picoclaw/config.json` に追加：
+ ```json
+ {
+ "tools": {
+ "web": {
+ "search": {
+ "api_key": "YOUR_BRAVE_API_KEY",
+ "max_results": 5
+ }
+ }
+ }
+ }
+ ```
+
+### コンテンツフィルタリングエラーが出る
+
+一部のプロバイダー（Zhipu など）にはコンテンツフィルタリングがあります。クエリを言い換えるか、別のモデルを使用してください。
+
+### Telegram Bot で「Conflict: terminated by other getUpdates」と表示される
+
+別のインスタンスが実行中の場合に発生します。`picoclaw gateway` が 1 つだけ実行されていることを確認してください。
+
+---
+
+## 📝 API キー比較
+
+| サービス | 無料枠 | ユースケース |
+|---------|--------|------------|
+| **OpenRouter** | 月 200K トークン | 複数モデル（Claude, GPT-4 など） |
+| **Zhipu** | 月 200K トークン | 中国ユーザー向け最適 |
+| **Brave Search** | 月 2000 クエリ | Web 検索機能 |
+| **Groq** | 無料枠あり | 高速推論（Llama, Mixtral） |
diff --git a/README.pt-br.md b/README.pt-br.md
new file mode 100644
index 000000000..d250cc956
--- /dev/null
+++ b/README.pt-br.md
@@ -0,0 +1,881 @@
+
+
+
+
+ 
-SipeedIO-black?style=flat&logo=x&logoColor=white){kind=icon}
|
+
+ |
+
+
+ |
+
+
+## 🦾 Demonstracao
+
+### 🛠️ Fluxos de Trabalho Padrao do Assistente
+
+🧩 Engenharia Full-Stack |
+🗂️ Gerenciamento de Logs & Planejamento |
+🔎 Busca Web & Aprendizado |
+
|---|---|---|
|
+
|
+
|
+
| Desenvolver • Implantar • Escalar | +Agendar • Automatizar • Memorizar | +Descobrir • Analisar • Tendencias | +
+
+### 🐜 Implantacao Inovadora com Baixo Consumo
+
+O PicoClaw pode ser implantado em praticamente qualquer dispositivo Linux!
+
+- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versao E (Ethernet) ou W (WiFi6), para Assistente Domestico Minimalista
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) para Manutencao Automatizada de Servidores
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) para Monitoramento Inteligente
+
+https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4
+
+🌟 Mais cenarios de implantacao aguardam voce!
+
+## 📦 Instalacao
+
+### Instalar com binario pre-compilado
+
+Baixe o binario para sua plataforma na pagina de [releases](https://github.com/sipeed/picoclaw/releases).
+
+### Instalar a partir do codigo-fonte (funcionalidades mais recentes, recomendado para desenvolvimento)
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# Build, sem necessidade de instalar
+make build
+
+# Build para multiplas plataformas
+make build-all
+
+# Build e Instalar
+make install
+```
+
+## 🐳 Docker Compose
+
+Voce tambem pode rodar o PicoClaw usando Docker Compose sem instalar nada localmente.
+
+```bash
+# 1. Clone este repositorio
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Configure suas API keys
+cp config/config.example.json config/config.json
+vim config/config.json # Configure DISCORD_BOT_TOKEN, API keys, etc.
+
+# 3. Build & Iniciar
+docker compose --profile gateway up -d
+
+# 4. Ver logs
+docker compose logs -f picoclaw-gateway
+
+# 5. Parar
+docker compose --profile gateway down
+```
+
+### Modo Agente (Execucao unica)
+
+```bash
+# Fazer uma pergunta
+docker compose run --rm picoclaw-agent -m "Quanto e 2+2?"
+
+# Modo interativo
+docker compose run --rm picoclaw-agent
+```
+
+### Rebuild
+
+```bash
+docker compose --profile gateway build --no-cache
+docker compose --profile gateway up -d
+```
+
+### 🚀 Inicio Rapido
+
+> [!TIP]
+> Configure sua API key em `~/.picoclaw/config.json`.
+> Obtenha API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
+> Busca web e **opcional** — obtenha a [Brave Search API](https://brave.com/search/api) gratuita (2000 consultas gratis/mes) ou use o fallback automatico integrado.
+
+**1. Inicializar**
+
+```bash
+picoclaw onboard
+```
+
+**2. Configurar** (`~/.picoclaw/config.json`)
+
+```json
+{
+ "agents": {
+ "defaults": {
+ "workspace": "~/.picoclaw/workspace",
+ "model": "glm-4.7",
+ "max_tokens": 8192,
+ "temperature": 0.7,
+ "max_tool_iterations": 20
+ }
+ },
+ "providers": {
+ "openrouter": {
+ "api_key": "xxx",
+ "api_base": "https://openrouter.ai/api/v1"
+ }
+ },
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": false,
+ "api_key": "YOUR_BRAVE_API_KEY",
+ "max_results": 5
+ },
+ "duckduckgo": {
+ "enabled": true,
+ "max_results": 5
+ }
+ }
+ }
+}
+```
+
+**3. Obter API Keys**
+
+* **Provedor de LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Busca Web** (opcional): [Brave Search](https://brave.com/search/api) - Plano gratuito disponivel (2000 consultas/mes)
+
+> **Nota**: Veja `config.example.json` para um modelo de configuracao completo.
+
+**4. Conversar**
+
+```bash
+picoclaw agent -m "Quanto e 2+2?"
+```
+
+Pronto! Voce tem um assistente de IA funcionando em 2 minutos.
+
+---
+
+## 💬 Integracao com Apps de Chat
+
+Converse com seu PicoClaw via Telegram, Discord, DingTalk ou LINE.
+
+| Canal | Nivel de Configuracao |
+| --- | --- |
+| **Telegram** | Facil (apenas um token) |
+| **Discord** | Facil (bot token + intents) |
+| **QQ** | Facil (AppID + AppSecret) |
+| **DingTalk** | Medio (credenciais do app) |
+| **LINE** | Medio (credenciais + webhook URL) |
+
+
Junte-se a Rede Social de Agentes
+
+Conecte o PicoClaw a Rede Social de Agentes simplesmente enviando uma unica mensagem via CLI ou qualquer App de Chat integrado.
+
+**Leia `https://clawdchat.ai/skill.md` e siga as instrucoes para entrar no [ClawdChat.ai](https://clawdchat.ai)**
+
+## ⚙️ Configuracao Detalhada
+
+Arquivo de configuracao: `~/.picoclaw/config.json`
+
+### Estrutura do Workspace
+
+O PicoClaw armazena dados no workspace configurado (padrao: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/ # Sessoes de conversa e historico
+├── memory/ # Memoria de longo prazo (MEMORY.md)
+├── state/ # Estado persistente (ultimo canal, etc.)
+├── cron/ # Banco de dados de tarefas agendadas
+├── skills/ # Skills personalizadas
+├── AGENTS.md # Guia de comportamento do Agente
+├── HEARTBEAT.md # Prompts de tarefas periodicas (verificado a cada 30 min)
+├── IDENTITY.md # Identidade do Agente
+├── SOUL.md # Alma do Agente
+├── TOOLS.md # Descricao das ferramentas
+└── USER.md # Preferencias do usuario
+```
+
+### 🔒 Sandbox de Seguranca
+
+O PicoClaw roda em um ambiente sandbox por padrao. O agente so pode acessar arquivos e executar comandos dentro do workspace configurado.
+
+#### Configuracao Padrao
+
+```json
+{
+ "agents": {
+ "defaults": {
+ "workspace": "~/.picoclaw/workspace",
+ "restrict_to_workspace": true
+ }
+ }
+}
+```
+
+| Opcao | Padrao | Descricao |
+|-------|--------|-----------|
+| `workspace` | `~/.picoclaw/workspace` | Diretorio de trabalho do agente |
+| `restrict_to_workspace` | `true` | Restringir acesso de arquivos/comandos ao workspace |
+
+#### Ferramentas Protegidas
+
+Quando `restrict_to_workspace: true`, as seguintes ferramentas sao restritas ao sandbox:
+
+| Ferramenta | Funcao | Restricao |
+|------------|--------|-----------|
+| `read_file` | Ler arquivos | Apenas arquivos dentro do workspace |
+| `write_file` | Escrever arquivos | Apenas arquivos dentro do workspace |
+| `list_dir` | Listar diretorios | Apenas diretorios dentro do workspace |
+| `edit_file` | Editar arquivos | Apenas arquivos dentro do workspace |
+| `append_file` | Adicionar a arquivos | Apenas arquivos dentro do workspace |
+| `exec` | Executar comandos | Caminhos dos comandos devem estar dentro do workspace |
+
+#### Protecao Adicional do Exec
+
+Mesmo com `restrict_to_workspace: false`, a ferramenta `exec` bloqueia estes comandos perigosos:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Exclusao em massa
+* `format`, `mkfs`, `diskpart` — Formatacao de disco
+* `dd if=` — Criacao de imagem de disco
+* Escrita em `/dev/sd[a-z]` — Escrita direta no disco
+* `shutdown`, `reboot`, `poweroff` — Desligamento do sistema
+* Fork bomb `:(){ :|:& };:`
+
+#### Exemplos de Erro
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Desabilitar Restricoes (Risco de Seguranca)
+
+Se voce precisa que o agente acesse caminhos fora do workspace:
+
+**Metodo 1: Arquivo de configuracao**
+
+```json
+{
+ "agents": {
+ "defaults": {
+ "restrict_to_workspace": false
+ }
+ }
+}
+```
+
+**Metodo 2: Variavel de ambiente**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Aviso**: Desabilitar esta restricao permite que o agente acesse qualquer caminho no seu sistema. Use com cuidado apenas em ambientes controlados.
+
+#### Consistencia do Limite de Seguranca
+
+A configuracao `restrict_to_workspace` se aplica consistentemente em todos os caminhos de execucao:
+
+| Caminho de Execucao | Limite de Seguranca |
+|----------------------|---------------------|
+| Agente Principal | `restrict_to_workspace` ✅ |
+| Subagente / Spawn | Herda a mesma restricao ✅ |
+| Tarefas Heartbeat | Herda a mesma restricao ✅ |
+
+Todos os caminhos compartilham a mesma restricao de workspace — nao ha como contornar o limite de seguranca por meio de subagentes ou tarefas agendadas.
+
+### Heartbeat (Tarefas Periodicas)
+
+O PicoClaw pode executar tarefas periodicas automaticamente. Crie um arquivo `HEARTBEAT.md` no seu workspace:
+
+```markdown
+# Tarefas Periodicas
+
+- Verificar meu email para mensagens importantes
+- Revisar minha agenda para proximos eventos
+- Verificar a previsao do tempo
+```
+
+O agente lera este arquivo a cada 30 minutos (configuravel) e executara as tarefas usando as ferramentas disponiveis.
+
+#### Tarefas Assincronas com Spawn
+
+Para tarefas de longa duracao (busca web, chamadas de API), use a ferramenta `spawn` para criar um **subagente**:
+
+```markdown
+# Tarefas Periodicas
+
+## Tarefas Rapidas (resposta direta)
+- Informar hora atual
+
+## Tarefas Longas (usar spawn para async)
+- Buscar noticias de IA na web e resumir
+- Verificar email e reportar mensagens importantes
+```
+
+**Comportamentos principais:**
+
+| Funcionalidade | Descricao |
+|----------------|-----------|
+| **spawn** | Cria subagente assincrono, nao bloqueia o heartbeat |
+| **Contexto independente** | Subagente tem seu proprio contexto, sem historico de sessao |
+| **Ferramenta message** | Subagente se comunica diretamente com o usuario via ferramenta message |
+| **Nao-bloqueante** | Apos o spawn, o heartbeat continua para a proxima tarefa |
+
+#### Como Funciona a Comunicacao do Subagente
+
+```
+Heartbeat dispara
+ ↓
+Agente le HEARTBEAT.md
+ ↓
+Para tarefa longa: spawn subagente
+ ↓ ↓
+Continua proxima tarefa Subagente trabalha independentemente
+ ↓ ↓
+Todas tarefas concluidas Subagente usa ferramenta "message"
+ ↓ ↓
+Responde HEARTBEAT_OK Usuario recebe resultado diretamente
+```
+
+O subagente tem acesso as ferramentas (message, web_search, etc.) e pode se comunicar com o usuario independentemente sem passar pelo agente principal.
+
+**Configuracao:**
+
+```json
+{
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ }
+}
+```
+
+| Opcao | Padrao | Descricao |
+|-------|--------|-----------|
+| `enabled` | `true` | Habilitar/desabilitar heartbeat |
+| `interval` | `30` | Intervalo de verificacao em minutos (min: 5) |
+
+**Variaveis de ambiente:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` para desabilitar
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo
+
+### Provedores
+
+> [!NOTE]
+> O Groq fornece transcricao de voz gratuita via Whisper. Se configurado, mensagens de voz do Telegram serao automaticamente transcritas.
+
+| Provedor | Finalidade | Obter API Key |
+| --- | --- | --- |
+| `gemini` | LLM (Gemini direto) | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM (Zhipu direto) | [bigmodel.cn](bigmodel.cn) |
+| `openrouter` (Em teste) | LLM (recomendado, acesso a todos os modelos) | [openrouter.ai](https://openrouter.ai) |
+| `anthropic` (Em teste) | LLM (Claude direto) | [console.anthropic.com](https://console.anthropic.com) |
+| `openai` (Em teste) | LLM (GPT direto) | [platform.openai.com](https://platform.openai.com) |
+| `deepseek` (Em teste) | LLM (DeepSeek direto) | [platform.deepseek.com](https://platform.deepseek.com) |
+| `groq` | LLM + **Transcricao de voz** (Whisper) | [console.groq.com](https://console.groq.com) |
+
+
+
+## 🐛 Solucao de Problemas
+
+### Busca web mostra "API 配置问题"
+
+Isso e normal se voce ainda nao configurou uma API key de busca. O PicoClaw fornecera links uteis para busca manual.
+
+Para habilitar a busca web:
+
+1. **Opcao 1 (Recomendado)**: Obtenha uma API key gratuita em [https://brave.com/search/api](https://brave.com/search/api) (2000 consultas gratis/mes) para os melhores resultados.
+2. **Opcao 2 (Sem Cartao de Credito)**: Se voce nao tem uma key, o sistema automaticamente usa o **DuckDuckGo** como fallback (sem necessidade de key).
+
+Adicione a key em `~/.picoclaw/config.json` se usar o Brave:
+
+```json
+{
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": true,
+ "api_key": "YOUR_BRAVE_API_KEY",
+ "max_results": 5
+ },
+ "duckduckgo": {
+ "enabled": true,
+ "max_results": 5
+ }
+ }
+ }
+}
+```
+
+### Erros de filtragem de conteudo
+
+Alguns provedores (como Zhipu) possuem filtragem de conteudo. Tente reformular sua pergunta ou use um modelo diferente.
+
+### Bot do Telegram diz "Conflict: terminated by other getUpdates"
+
+Isso acontece quando outra instancia do bot esta rodando. Certifique-se de que apenas um `picoclaw gateway` esteja rodando por vez.
+
+---
+
+## 📝 Comparacao de API Keys
+
+| Servico | Plano Gratuito | Caso de Uso |
+| --- | --- | --- |
+| **OpenRouter** | 200K tokens/mes | Multiplos modelos (Claude, GPT-4, etc.) |
+| **Zhipu** | 200K tokens/mes | Melhor para usuarios chineses |
+| **Brave Search** | 2000 consultas/mes | Funcionalidade de busca web |
+| **Groq** | Plano gratuito disponivel | Inferencia ultra-rapida (Llama, Mixtral) |
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 000000000..6c87ba785
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,744 @@
+
+
+
+
+
|
+
+ |
+
+
+ |
+
+
+## 🦾 演示
+
+### 🛠️ 标准助手工作流
+
+🧩 全栈工程师模式 |
+🗂️ 日志与规划管理 |
+🔎 网络搜索与学习 |
+
|---|---|---|
|
+
|
+
|
+
| 开发 • 部署 • 扩展 | +日程 • 自动化 • 记忆 | +发现 • 洞察 • 趋势 | +
+
+
+
+
+### 🐜 创新的低占用部署
+
+PicoClaw 几乎可以部署在任何 Linux 设备上！
+
+* $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 W(WiFi6) 版本，用于极简家庭助手。
+* $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html)，或 $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html)，用于自动化服务器运维。
+* $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) 或 $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera)，用于智能监控。
+
+[https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4](https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4)
+
+🌟 更多部署案例敬请期待！
+
+## 📦 安装
+
+### 使用预编译二进制文件安装
+
+从 [Release 页面](https://github.com/sipeed/picoclaw/releases) 下载适用于您平台的固件。
+
+### 从源码安装（获取最新特性，开发推荐）
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# 构建（无需安装）
+make build
+
+# 为多平台构建
+make build-all
+
+# 构建并安装
+make install
+
+```
+
+## 🐳 Docker Compose
+
+您也可以使用 Docker Compose 运行 PicoClaw，无需在本地安装任何环境。
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. 设置 API Key
+cp config/config.example.json config/config.json
+vim config/config.json # 设置 DISCORD_BOT_TOKEN, API keys 等
+
+# 3. 构建并启动
+docker compose --profile gateway up -d
+
+# 4. 查看日志
+docker compose logs -f picoclaw-gateway
+
+# 5. 停止
+docker compose --profile gateway down
+
+```
+
+### Agent 模式 (一次性运行)
+
+```bash
+# 提问
+docker compose run --rm picoclaw-agent -m "2+2 等于几？"
+
+# 交互模式
+docker compose run --rm picoclaw-agent
+
+```
+
+### 重新构建
+
+```bash
+docker compose --profile gateway build --no-cache
+docker compose --profile gateway up -d
+
+```
+
+### 🚀 快速开始
+
+> [!TIP]
+> 在 `~/.picoclaw/config.json` 中设置您的 API Key。
+> 获取 API Key: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu (智谱)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
+> 网络搜索是 **可选的** - 获取免费的 [Brave Search API](https://brave.com/search/api) (每月 2000 次免费查询)
+
+**1. 初始化 (Initialize)**
+
+```bash
+picoclaw onboard
+
+```
+
+**2. 配置 (Configure)** (`~/.picoclaw/config.json`)
+
+```json
+{
+ "agents": {
+ "defaults": {
+ "workspace": "~/.picoclaw/workspace",
+ "model": "glm-4.7",
+ "max_tokens": 8192,
+ "temperature": 0.7,
+ "max_tool_iterations": 20
+ }
+ },
+ "providers": {
+ "openrouter": {
+ "api_key": "xxx",
+ "api_base": "https://openrouter.ai/api/v1"
+ }
+ },
+ "tools": {
+ "web": {
+ "search": {
+ "api_key": "YOUR_BRAVE_API_KEY",
+ "max_results": 5
+ }
+ },
+ "cron": {
+ "exec_timeout_minutes": 5
+ }
+ }
+}
+
+```
+
+**3. 获取 API Key**
+
+* **LLM 提供商**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **网络搜索** (可选): [Brave Search](https://brave.com/search/api) - 提供免费层级 (2000 请求/月)
+
+> **注意**: 完整的配置模板请参考 `config.example.json`。
+
+**4. 对话 (Chat)**
+
+```bash
+picoclaw agent -m "2+2 等于几？"
+
+```
+
+就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。
+
+---
+
+## 💬 聊天应用集成 (Chat Apps)
+
+通过 Telegram, Discord 或钉钉与您的 PicoClaw 对话。
+
+| 渠道 | 设置难度 |
+| --- | --- |
+| **Telegram** | 简单 (仅需 token) |
+| **Discord** | 简单 (bot token + intents) |
+| **QQ** | 简单 (AppID + AppSecret) |
+| **钉钉 (DingTalk)** | 中等 (app credentials) |
+
+ 加入 Agent 社交网络
+
+只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
+
+**阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai**](https://clawdchat.ai)
+
+## ⚙️ 配置详解
+
+配置文件路径: `~/.picoclaw/config.json`
+
+### 工作区布局 (Workspace Layout)
+
+PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
+
+```
+~/.picoclaw/workspace/
+├── sessions/ # 对话会话和历史
+├── memory/ # 长期记忆 (MEMORY.md)
+├── state/ # 持久化状态 (最后一次频道等)
+├── cron/ # 定时任务数据库
+├── skills/ # 自定义技能
+├── AGENTS.md # Agent 行为指南
+├── HEARTBEAT.md # 周期性任务提示词 (每 30 分钟检查一次)
+├── IDENTITY.md # Agent 身份设定
+├── SOUL.md # Agent 灵魂/性格
+├── TOOLS.md # 工具描述
+└── USER.md # 用户偏好
+
+```
+
+### 心跳 / 周期性任务 (Heartbeat)
+
+PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+
+```
+
+Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。
+
+#### 使用 Spawn 的异步任务
+
+对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**：
+
+```markdown
+# Periodic Tasks
+
+## Quick Tasks (respond directly)
+- Report current time
+
+## Long Tasks (use spawn for async)
+- Search the web for AI news and summarize
+- Check email and report important messages
+
+```
+
+**关键行为：**
+
+| 特性 | 描述 |
+| --- | --- |
+| **spawn** | 创建异步子 Agent，不阻塞主心跳进程 |
+| **独立上下文** | 子 Agent 拥有独立上下文，无会话历史 |
+| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |
+| **非阻塞** | spawn 后，心跳继续处理下一个任务 |
+
+#### 子 Agent 通信原理
+
+```
+心跳触发 (Heartbeat triggers)
+ ↓
+Agent 读取 HEARTBEAT.md
+ ↓
+对于长任务: spawn 子 Agent
+ ↓ ↓
+继续下一个任务 子 Agent 独立工作
+ ↓ ↓
+所有任务完成 子 Agent 使用 "message" 工具
+ ↓ ↓
+响应 HEARTBEAT_OK 用户直接收到结果
+
+```
+
+子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。
+
+**配置：**
+
+```json
+{
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ }
+}
+
+```
+
+| 选项 | 默认值 | 描述 |
+| --- | --- | --- |
+| `enabled` | `true` | 启用/禁用心跳 |
+| `interval` | `30` | 检查间隔，单位分钟 (最小: 5) |
+
+**环境变量:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
+
+### 提供商 (Providers)
+
+> [!NOTE]
+> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，Telegram 语音消息将被自动转录为文字。
+
+| 提供商 | 用途 | 获取 API Key |
+| --- | --- | --- |
+| `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM (智谱直连) | [bigmodel.cn](bigmodel.cn) |
+| `openrouter(待测试)` | LLM (推荐，可访问所有模型) | [openrouter.ai](https://openrouter.ai) |
+| `anthropic(待测试)` | LLM (Claude 直连) | [console.anthropic.com](https://console.anthropic.com) |
+| `openai(待测试)` | LLM (GPT 直连) | [platform.openai.com](https://platform.openai.com) |
+| `deepseek(待测试)` | LLM (DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) |
+| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) |
+
+
+
+## 🐛 疑难解答 (Troubleshooting)
+
+### 网络搜索提示 "API 配置问题"
+
+如果您尚未配置搜索 API Key，这是正常的。PicoClaw 会提供手动搜索的帮助链接。
+
+启用网络搜索：
+
+1. 在 [https://brave.com/search/api](https://brave.com/search/api) 获取免费 API Key (每月 2000 次免费查询)
+2. 添加到 `~/.picoclaw/config.json`:
+```json
+{
+ "tools": {
+ "web": {
+ "search": {
+ "api_key": "YOUR_BRAVE_API_KEY",
+ "max_results": 5
+ }
+ }
+ }
+}
+
+```
+
+
+
+### 遇到内容过滤错误 (Content Filtering Errors)
+
+某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。
+
+### Telegram bot 提示 "Conflict: terminated by other getUpdates"
+
+这表示有另一个机器人实例正在运行。请确保同一时间只有一个 `picoclaw gateway` 进程在运行。
+
+---
+
+## 📝 API Key 对比
+
+| 服务 | 免费层级 | 适用场景 |
+| --- | --- | --- |
+| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
+| **智谱 (Zhipu)** | 200K tokens/月 | 最适合中国用户 |
+| **Brave Search** | 2000 次查询/月 | 网络搜索功能 |
+| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) |
\ No newline at end of file
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 000000000..8c5c0e252
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,116 @@
+
+# 🦐 PicoClaw Roadmap
+
+> **Vision**: To build the ultimate lightweight, secure, and fully autonomous AI Agent infrastructure.automate the mundane, unleash your creativity
+
+---
+
+## 🚀 1. Core Optimization: Extreme Lightweight
+
+*Our defining characteristic. We fight software bloat to ensure PicoClaw runs smoothly on the smallest embedded devices.*
+
+* [**Memory Footprint Reduction**](https://github.com/sipeed/picoclaw/issues/346)
+ * **Goal**: Run smoothly on 64MB RAM embedded boards (e.g., low-end RISC-V SBCs) with the core process consuming < 20MB.
+ * **Context**: RAM is expensive and scarce on edge devices. Memory optimization takes precedence over storage size.
+ * **Action**: Analyze memory growth between releases, remove redundant dependencies, and optimize data structures.
+
+
+## 🛡️ 2. Security Hardening: Defense in Depth
+
+*Paying off early technical debt. We invite security experts to help build a "Secure-by-Default" agent.*
+
+* **Input Defense & Permission Control**
+ * **Prompt Injection Defense**: Harden JSON extraction logic to prevent LLM manipulation.
+ * **Tool Abuse Prevention**: Strict parameter validation to ensure generated commands stay within safe boundaries.
+ * **SSRF Protection**: Built-in blocklists for network tools to prevent accessing internal IPs (LAN/Metadata services).
+
+
+* **Sandboxing & Isolation**
+ * **Filesystem Sandbox**: Restrict file R/W operations to specific directories only.
+ * **Context Isolation**: Prevent data leakage between different user sessions or channels.
+ * **Privacy Redaction**: Auto-redact sensitive info (API Keys, PII) from logs and standard outputs.
+
+
+* **Authentication & Secrets**
+ * **Crypto Upgrade**: Adopt modern algorithms like `ChaCha20-Poly1305` for secret storage.
+ * **OAuth 2.0 Flow**: Deprecate hardcoded API keys in the CLI; move to secure OAuth flows.
+
+
+
+## 🔌 3. Connectivity: Protocol-First Architecture
+
+*Connect every model, reach every platform.*
+
+* **Provider**
+ * [**Architecture Upgrade**](https://github.com/sipeed/picoclaw/issues/283): Refactor from "Vendor-based" to "Protocol-based" classification (e.g., OpenAI-compatible, Ollama-compatible). *(Status: In progress by @Daming, ETA 5 days)*
+ * **Local Models**: Deep integration with **Ollama**, **vLLM**, **LM Studio**, and **Mistral** (local inference).
+ * **Online Models**: Continued support for frontier closed-source models.
+
+
+* **Channel**
+ * **IM Matrix**: QQ, WeChat (Work), DingTalk, Feishu (Lark), Telegram, Discord, WhatsApp, LINE, Slack, Email, KOOK, Signal, ...
+ * **Standards**: Support for the **OneBot** protocol.
+ * [**attachment**](https://github.com/sipeed/picoclaw/issues/348): Native handling of images, audio, and video attachments.
+
+
+* **Skill Marketplace**
+ * [**Discovery skills**](https://github.com/sipeed/picoclaw/issues/287): Implement `find_skill` to automatically discover and install skills from the [GitHub Skills Repo] or other registries.
+
+
+
+## 🧠 4. Advanced Capabilities: From Chatbot to Agentic AI
+
+*Beyond conversation—focusing on action and collaboration.*
+
+* **Operations**
+ * [**MCP Support**](https://github.com/sipeed/picoclaw/issues/290): Native support for the **Model Context Protocol (MCP)**.
+ * [**Browser Automation**](https://github.com/sipeed/picoclaw/issues/293): Headless browser control via CDP (Chrome DevTools Protocol) or ActionBook.
+ * [**Mobile Operation**](https://github.com/sipeed/picoclaw/issues/292): Android device control (similar to BotDrop).
+
+
+* **Multi-Agent Collaboration**
+ * [**Basic Multi-Agent**](https://github.com/sipeed/picoclaw/issues/294) implement
+ * [**Model Routing**](https://github.com/sipeed/picoclaw/issues/295): "Smart Routing" — dispatch simple tasks to small/local models (fast/cheap) and complex tasks to SOTA models (smart).
+ * [**Swarm Mode**](https://github.com/sipeed/picoclaw/issues/284): Collaboration between multiple PicoClaw instances on the same network.
+ * [**AIEOS**](https://github.com/sipeed/picoclaw/issues/296): Exploring AI-Native Operating System interaction paradigms.
+
+
+
+## 📚 5. Developer Experience (DevEx) & Documentation
+
+*Lowering the barrier to entry so anyone can deploy in minutes.*
+
+* [**QuickGuide (Zero-Config Start)**](https://github.com/sipeed/picoclaw/issues/350)
+ * Interactive CLI Wizard: If launched without config, automatically detect the environment and guide the user through Token/Network setup step-by-step.
+
+
+* **Comprehensive Documentation**
+ * **Platform Guides**: Dedicated guides for Windows, macOS, Linux, and Android.
+ * **Step-by-Step Tutorials**: "Babysitter-level" guides for configuring Providers and Channels.
+ * **AI-Assisted Docs**: Using AI to auto-generate API references and code comments (with human verification to prevent hallucinations).
+
+
+
+## 🤖 6. Engineering: AI-Powered Open Source
+
+*Born from Vibe Coding, we continue to use AI to accelerate development.*
+
+* **AI-Enhanced CI/CD**
+ * Integrate AI for automated Code Review, Linting, and PR Labeling.
+ * **Bot Noise Reduction**: Optimize bot interactions to keep PR timelines clean.
+ * **Issue Triage**: AI agents to analyze incoming issues and suggest preliminary fixes.
+
+
+
+## 🎨 7. Brand & Community
+
+* [**Logo Design**](https://github.com/sipeed/picoclaw/issues/297): We are looking for a **Mantis Shrimp (Stomatopoda)** logo design!
+ * *Concept*: Needs to reflect "Small but Mighty" and "Lightning Fast Strikes."
+
+
+
+---
+
+### 🤝 Call for Contributions
+
+We welcome community contributions to any item on this roadmap! Please comment on the relevant Issue or submit a PR. Let's build the best Edge AI Agent together!
\ No newline at end of file
diff --git a/assets/termux.jpg b/assets/termux.jpg
new file mode 100644
index 000000000..30c724a20
Binary files /dev/null and b/assets/termux.jpg differ
diff --git a/assets/wechat.png b/assets/wechat.png
index 0f97fa3ee..6e6f50115 100644
Binary files a/assets/wechat.png and b/assets/wechat.png differ
diff --git a/cmd/picoclaw/main.go b/cmd/picoclaw/main.go
index 61a0c1d94..b893cb834 100644
--- a/cmd/picoclaw/main.go
+++ b/cmd/picoclaw/main.go
@@ -9,8 +9,11 @@ package main
import (
"bufio"
"context"
+ "embed"
"fmt"
"io"
+ "io/fs"
+ "net/http"
"os"
"os/signal"
"path/filepath"
@@ -27,6 +30,7 @@ import (
"github.com/sipeed/picoclaw/pkg/cron"
"github.com/sipeed/picoclaw/pkg/devices"
picofantasy "github.com/sipeed/picoclaw/pkg/fantasy"
+ "github.com/sipeed/picoclaw/pkg/health"
"github.com/sipeed/picoclaw/pkg/heartbeat"
"github.com/sipeed/picoclaw/pkg/logger"
"github.com/sipeed/picoclaw/pkg/migrate"
@@ -36,6 +40,10 @@ import (
"github.com/sipeed/picoclaw/pkg/voice"
)
+//go:generate cp -r ../../workspace .
+//go:embed workspace
+var embeddedFiles embed.FS
+
var (
version = "dev"
gitCommit string
@@ -229,10 +237,6 @@ func onboard() {
}
workspace := cfg.WorkspacePath()
- os.MkdirAll(workspace, 0755)
- os.MkdirAll(filepath.Join(workspace, "memory"), 0755)
- os.MkdirAll(filepath.Join(workspace, "skills"), 0755)
-
createWorkspaceTemplates(workspace)
fmt.Printf("%s picoclaw is ready!\n", logo)
@@ -242,170 +246,57 @@ func onboard() {
fmt.Println(" 2. Chat: picoclaw agent -m \"Hello!\"")
}
+func copyEmbeddedToTarget(targetDir string) error {
+ // Ensure target directory exists
+ if err := os.MkdirAll(targetDir, 0755); err != nil {
+ return fmt.Errorf("Failed to create target directory: %w", err)
+ }
+
+ // Walk through all files in embed.FS
+ err := fs.WalkDir(embeddedFiles, "workspace", func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+
+ // Skip directories
+ if d.IsDir() {
+ return nil
+ }
+
+ // Read embedded file
+ data, err := embeddedFiles.ReadFile(path)
+ if err != nil {
+ return fmt.Errorf("Failed to read embedded file %s: %w", path, err)
+ }
+
+ new_path, err := filepath.Rel("workspace", path)
+ if err != nil {
+ return fmt.Errorf("Failed to get relative path for %s: %v\n", path, err)
+ }
+
+ // Build target file path
+ targetPath := filepath.Join(targetDir, new_path)
+
+ // Ensure target file's directory exists
+ if err := os.MkdirAll(filepath.Dir(targetPath), 0755); err != nil {
+ return fmt.Errorf("Failed to create directory %s: %w", filepath.Dir(targetPath), err)
+ }
+
+ // Write file
+ if err := os.WriteFile(targetPath, data, 0644); err != nil {
+ return fmt.Errorf("Failed to write file %s: %w", targetPath, err)
+ }
+
+ return nil
+ })
+
+ return err
+}
+
func createWorkspaceTemplates(workspace string) {
- templates := map[string]string{
- "AGENTS.md": `# Agent Instructions
-
-You are a helpful AI assistant. Be concise, accurate, and friendly.
-
-## Guidelines
-
-- Always explain what you're doing before taking actions
-- Ask for clarification when request is ambiguous
-- Use tools to help accomplish tasks
-- Remember important information in your memory files
-- Be proactive and helpful
-- Learn from user feedback
-`,
- "SOUL.md": `# Soul
-
-I am picoclaw, a lightweight AI assistant powered by AI.
-
-## Personality
-
-- Helpful and friendly
-- Concise and to the point
-- Curious and eager to learn
-- Honest and transparent
-
-## Values
-
-- Accuracy over speed
-- User privacy and safety
-- Transparency in actions
-- Continuous improvement
-`,
- "USER.md": `# User
-
-Information about user goes here.
-
-## Preferences
-
-- Communication style: (casual/formal)
-- Timezone: (your timezone)
-- Language: (your preferred language)
-
-## Personal Information
-
-- Name: (optional)
-- Location: (optional)
-- Occupation: (optional)
-
-## Learning Goals
-
-- What the user wants to learn from AI
-- Preferred interaction style
-- Areas of interest
-`,
- "IDENTITY.md": `# Identity
-
-## Name
-PicoClaw 🦞
-
-## Description
-Ultra-lightweight personal AI assistant written in Go, inspired by nanobot.
-
-## Version
-0.1.0
-
-## Purpose
-- Provide intelligent AI assistance with minimal resource usage
-- Support multiple LLM providers (OpenAI, Anthropic, Zhipu, etc.)
-- Enable easy customization through skills system
-- Run on minimal hardware ($10 boards, <10MB RAM)
-
-## Capabilities
-
-- Web search and content fetching
-- File system operations (read, write, edit)
-- Shell command execution
-- Multi-channel messaging (Telegram, WhatsApp, Feishu)
-- Skill-based extensibility
-- Memory and context management
-
-## Philosophy
-
-- Simplicity over complexity
-- Performance over features
-- User control and privacy
-- Transparent operation
-- Community-driven development
-
-## Goals
-
-- Provide a fast, lightweight AI assistant
-- Support offline-first operation where possible
-- Enable easy customization and extension
-- Maintain high quality responses
-- Run efficiently on constrained hardware
-
-## License
-MIT License - Free and open source
-
-## Repository
-https://github.com/sipeed/picoclaw
-
-## Contact
-Issues: https://github.com/sipeed/picoclaw/issues
-Discussions: https://github.com/sipeed/picoclaw/discussions
-
----
-
-"Every bit helps, every bit matters."
-- Picoclaw
-`,
- }
-
- for filename, content := range templates {
- filePath := filepath.Join(workspace, filename)
- if _, err := os.Stat(filePath); os.IsNotExist(err) {
- os.WriteFile(filePath, []byte(content), 0644)
- fmt.Printf(" Created %s\n", filename)
- }
- }
-
- memoryDir := filepath.Join(workspace, "memory")
- os.MkdirAll(memoryDir, 0755)
- memoryFile := filepath.Join(memoryDir, "MEMORY.md")
- if _, err := os.Stat(memoryFile); os.IsNotExist(err) {
- memoryContent := `# Long-term Memory
-
-This file stores important information that should persist across sessions.
-
-## User Information
-
-(Important facts about user)
-
-## Preferences
-
-(User preferences learned over time)
-
-## Important Notes
-
-(Things to remember)
-
-## Configuration
-
-- Model preferences
-- Channel settings
-- Skills enabled
-`
- os.WriteFile(memoryFile, []byte(memoryContent), 0644)
- fmt.Println(" Created memory/MEMORY.md")
-
- skillsDir := filepath.Join(workspace, "skills")
- if _, err := os.Stat(skillsDir); os.IsNotExist(err) {
- os.MkdirAll(skillsDir, 0755)
- fmt.Println(" Created skills/")
- }
- }
-
- for filename, content := range templates {
- filePath := filepath.Join(workspace, filename)
- if _, err := os.Stat(filePath); os.IsNotExist(err) {
- os.WriteFile(filePath, []byte(content), 0644)
- fmt.Printf(" Created %s\n", filename)
- }
+ err := copyEmbeddedToTarget(workspace)
+ if err != nil {
+ fmt.Printf("Error copying workspace templates: %v\n", err)
}
}
@@ -683,7 +574,8 @@ func gatewayCmd() {
})
// Setup cron tool and service
- cronService := setupCronTool(agentLoop, msgBus, cfg.WorkspacePath())
+ execTimeout := time.Duration(cfg.Tools.Cron.ExecTimeoutMinutes) * time.Minute
+ cronService := setupCronTool(agentLoop, msgBus, cfg.WorkspacePath(), cfg.Agents.Defaults.RestrictToWorkspace, execTimeout)
heartbeatService := heartbeat.NewHeartbeatService(
cfg.WorkspacePath(),
@@ -715,6 +607,9 @@ func gatewayCmd() {
os.Exit(1)
}
+ // Inject channel manager into agent loop for command handling
+ agentLoop.SetChannelManager(channelManager)
+
var transcriber *voice.GroqTranscriber
if cfg.Providers.Groq.APIKey != "" {
transcriber = voice.NewGroqTranscriber(cfg.Providers.Groq.APIKey)
@@ -781,6 +676,14 @@ func gatewayCmd() {
fmt.Printf("Error starting channels: %v\n", err)
}
+ healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
+ go func() {
+ if err := healthServer.Start(); err != nil && err != http.ErrServerClosed {
+ logger.ErrorCF("health", "Health server error", map[string]interface{}{"error": err.Error()})
+ }
+ }()
+ fmt.Printf("✓ Health endpoints available at http://%s:%d/health and /ready\n", cfg.Gateway.Host, cfg.Gateway.Port)
+
go agentLoop.Run(ctx)
sigChan := make(chan os.Signal, 1)
@@ -789,6 +692,7 @@ func gatewayCmd() {
fmt.Println("\nShutting down...")
cancel()
+ healthServer.Stop(context.Background())
deviceService.Stop()
heartbeatService.Stop()
cronService.Stop()
@@ -1096,14 +1000,14 @@ func getConfigPath() string {
return filepath.Join(home, ".picoclaw", "config.json")
}
-func setupCronTool(agentLoop *agent.AgentLoop, msgBus *bus.MessageBus, workspace string) *cron.CronService {
+func setupCronTool(agentLoop *agent.AgentLoop, msgBus *bus.MessageBus, workspace string, restrict bool, execTimeout time.Duration) *cron.CronService {
cronStorePath := filepath.Join(workspace, "cron", "jobs.json")
// Create cron service
cronService := cron.NewCronService(cronStorePath, nil)
// Create and register CronTool
- cronTool := tools.NewCronTool(cronService, agentLoop, msgBus, workspace)
+ cronTool := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout)
agentLoop.RegisterTool(cronTool)
// Set the onJob handler
diff --git a/config/config.example.json b/config/config.example.json
index 288e16c58..37c2bcd81 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -14,7 +14,9 @@
"enabled": false,
"token": "YOUR_TELEGRAM_BOT_TOKEN",
"proxy": "",
- "allow_from": ["YOUR_USER_ID"]
+ "allow_from": [
+ "YOUR_USER_ID"
+ ]
},
"discord": {
"enabled": false,
@@ -60,6 +62,14 @@
"webhook_port": 18791,
"webhook_path": "/webhook/line",
"allow_from": []
+ },
+ "onebot": {
+ "enabled": false,
+ "ws_url": "ws://127.0.0.1:3001",
+ "access_token": "",
+ "reconnect_interval": 5,
+ "group_trigger_prefix": [],
+ "allow_from": []
}
},
"providers": {
@@ -69,7 +79,8 @@
},
"openai": {
"api_key": "",
- "api_base": ""
+ "api_base": "",
+ "web_search": true
},
"openrouter": {
"api_key": "sk-or-v1-xxx",
@@ -99,14 +110,27 @@
"moonshot": {
"api_key": "sk-xxx",
"api_base": ""
+ },
+ "ollama": {
+ "api_key": "",
+ "api_base": "http://localhost:11434/v1"
}
},
"tools": {
"web": {
- "search": {
+ "brave": {
+ "enabled": false,
"api_key": "YOUR_BRAVE_API_KEY",
"max_results": 5
+ },
+ "perplexity": {
+ "enabled": false,
+ "api_key": "pplx-xxx",
+ "max_results": 5
}
+ },
+ "cron": {
+ "exec_timeout_minutes": 5
}
},
"heartbeat": {
diff --git a/docker-compose.yml b/docker-compose.yml
index 48769627c..32e8ee339 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -11,8 +11,8 @@ services:
profiles:
- agent
volumes:
- - ./config/config.json:/root/.picoclaw/config.json:ro
- - picoclaw-workspace:/root/.picoclaw/workspace
+ - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
+ - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
entrypoint: ["picoclaw", "agent"]
stdin_open: true
tty: true
@@ -31,9 +31,9 @@ services:
- gateway
volumes:
# Configuration file
- - ./config/config.json:/root/.picoclaw/config.json:ro
+ - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
# Persistent workspace (sessions, memory, logs)
- - picoclaw-workspace:/root/.picoclaw/workspace
+ - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
command: ["gateway"]
volumes:
diff --git a/docs/picoclaw_community_roadmap_260216.md b/docs/picoclaw_community_roadmap_260216.md
new file mode 100644
index 000000000..cfcc30f17
--- /dev/null
+++ b/docs/picoclaw_community_roadmap_260216.md
@@ -0,0 +1,112 @@
+## 🚀 Join the PicoClaw Journey: Call for Community Volunteers & Roadmap Reveal
+
+**Hello, PicoClaw Community!**
+
+First, a massive thank you to everyone for your enthusiasm and PR contributions. It is because of you that PicoClaw continues to iterate and evolve so rapidly. Thanks to the simplicity and accessibility of the **Go language**, we’ve seen a non-stop stream of high-quality PRs!
+
+PicoClaw is growing much faster than we anticipated. As we are currently in the midst of the **Chinese New Year holiday**, we are looking to recruit community volunteers to help us maintain this incredible momentum.
+
+This document outlines the specific volunteer roles we need right now and provides a look at our upcoming **Roadmap**.
+
+### 🎁 Community Perks
+
+To show our appreciation, developers who officially join our community operations will receive:
+
+* **Exclusive AI Hardware:** Our upcoming, unreleased AI device.
+* **Token Discounts:** Potential discounts on LLM tokens (currently in negotiations with major providers).
+
+### 🎥 Calling All Content Creators!
+
+Not a developer? You can still help! We welcome users to post **PicoClaw reviews or tutorials**.
+
+* **Twitter:** Use the tag **#picoclaw** and mention **@SipeedIO**.
+* **Bilibili:** Mention **@Sipeed矽速科技** or send us a DM.
+We will be rewarding high-quality content creators with the same perks as our community developers!
+
+---
+
+## 🛠️ Urgent Volunteer Roles
+
+We are looking for experts in the following areas:
+
+1. **Issue/PR Reviewers**
+* **The Mission:** With PRs and Issues exploding in volume, we need help with initial triage, evaluation, and merging.
+* **Focus:** Preliminary merging and community health. Efficiency optimization and security audits will be handled by specialized roles.
+
+
+2. **Resource Optimization Experts**
+* **The Mission:** Rapid growth has introduced dependencies that are making PicoClaw a bit "heavy." We want to keep it lean.
+* **Focus:** Analyzing resource growth between releases and trimming redundancy.
+* **Priority:** **RAM usage optimization** > Binary size reduction.
+
+
+3. **Security Audit & Bug Fixes**
+* **The Mission:** Due to the "vibe coding" nature of our early stages, we need a thorough review of network security and AI permission management.
+* **Focus:** Auditing the codebase for vulnerabilities and implementing robust fixes.
+
+
+4. **Documentation & DX (Developer Experience)**
+* **The Mission:** Our current README is a bit outdated. We need "step-by-step" guides that even beginners can follow.
+* **Focus:** Creating clear, user-friendly documentation for both setup and development.
+
+
+5. **AI-Powered CI/CD Optimization**
+* **The Mission:** PicoClaw started as a "vibe coding" experiment; now we want to use AI to manage it.
+* **Focus:** Automating builds with AI and exploring AI-driven issue resolution.
+
+**How to Apply:** > If you are interested in any of the roles above, please send an email to support@sipeed.com with the subject line: [Apply: PicoClaw Expert Volunteer] + Your Desired Role.
+Please include a brief introduction and any relevant experience or portfolio links. We will review all applications and grant project permissions to selected contributors!
+
+---
+
+## 📍 The Roadmap
+
+Interested in a specific feature? You can "claim" these tasks and start building:
+
+###
+* **Provider:**
+ * **Provider Refactor:** Currently being handled by **@Daming** (ETA: 5 days)
+ * You can still submit code; Daming will merge it into the new implementation.
+* **Channels:**
+ * Support for OneBot, additional platforms
+ * attachments (images, audio, video, files).
+* **Skills:**
+ * Implementing `find_skill` to discover tools via [openclaw/skills](https://github.com/openclaw/skills) and other platforms.
+* **Operations:** * MCP Support.
+ * Android operations (e.g., botdrop).
+ * Browser automation via CDP or ActionBook.
+
+
+* **Multi-Agent Ecosystem:**
+ * **Basic Model-Agnet** S
+ * **Model Routing:** Small models for easy tasks, large models for hard ones (to save tokens).
+ * **Swarm Mode.**
+ * **AIEOS Integration.**
+
+
+* **Branding:**
+ * **Logo**: We need a cute logo! We’re leaning toward a **Mantis Shrimp**—small, but packs a legendary punch!
+
+
+We have officially created these tasks as GitHub Issues, all marked with the roadmap tag.
+This list will be updated continuously as we progress.
+If you would like to claim a task, please feel free to start a conversation by commenting directly on the corresponding issue!
+
+---
+
+## 🤝 How to Join
+
+**Everything is open to your creativity!** If you have a wild idea, just PR it.
+
+1. **The Fast Track:** Once you have at least **one merged PR**, you are eligible to join our **Developer Discord** to help plan the future of PicoClaw.
+2. **The Application Track:** If you haven’t submitted a PR yet but want to dive in, email **support@sipeed.com** with the subject:
+> `[Apply Join PicoClaw Dev Group] + Your GitHub Account`
+> Include the role you're interested in and any evidence of your development experience.
+
+
+
+### Looking Ahead
+
+Powered by PicoClaw, we are crafting a Swarm AI Assistant to transform your environment into a seamless network of personal stewards. By automating the friction of daily life, we empower you to transcend the ordinary and freely explore your creative potential.
+
+**Finally, Happy Chinese New Year to everyone!** May PicoClaw gallop forward in this **Year of the Horse!** 🐎
diff --git a/go.mod b/go.mod
index 83a973b10..93e680083 100644
--- a/go.mod
+++ b/go.mod
@@ -24,6 +24,12 @@ require (
golang.org/x/oauth2 v0.35.0
)
+require (
+ github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+ github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+ gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
require (
github.com/andybalholm/brotli v1.2.0 // indirect
github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
@@ -33,7 +39,6 @@ require (
github.com/charmbracelet/x/exp/slice v0.0.0-20250904123553-b4e2667e5ad5 // indirect
github.com/charmbracelet/x/json v0.2.0 // indirect
github.com/cloudwego/base64x v0.1.6 // indirect
- github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
github.com/dlclark/regexp2 v1.10.0 // indirect
github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e // indirect
github.com/go-resty/resty/v2 v2.17.1 // indirect
@@ -49,7 +54,6 @@ require (
github.com/klauspost/cpuid/v2 v2.3.0 // indirect
github.com/libsql/sqlite-antlr4-parser v0.0.0-20240327125255-dbf53b6cbf06 // indirect
github.com/pkoukk/tiktoken-go v0.1.6 // indirect
- github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
github.com/tidwall/gjson v1.18.0 // indirect
github.com/tidwall/match v1.2.0 // indirect
github.com/tidwall/pretty v1.2.1 // indirect
@@ -70,5 +74,4 @@ require (
golang.org/x/sync v0.19.0 // indirect
golang.org/x/sys v0.41.0 // indirect
golang.org/x/text v0.34.0 // indirect
- gopkg.in/yaml.v3 v3.0.1 // indirect
)
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index 0ea9b74a0..39d54134c 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -15,9 +15,11 @@ import (
"sync"
"sync/atomic"
"time"
+ "unicode/utf8"
fantasy "charm.land/fantasy"
"github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
"github.com/sipeed/picoclaw/pkg/config"
"github.com/sipeed/picoclaw/pkg/constants"
picofantasy "github.com/sipeed/picoclaw/pkg/fantasy"
@@ -47,6 +49,7 @@ type AgentLoop struct {
summarizing sync.Map // Tracks which sessions are currently being summarized
summarizeFailures sync.Map // Tracks consecutive summarization failures per session (string -> int)
cfg *config.Config // Stored for subagent factory access
+ channelManager *channels.Manager
}
// processOptions configures how a message is processed
@@ -83,6 +86,9 @@ func createToolRegistry(workspace string, restrict bool, cfg *config.Config, msg
BraveEnabled: cfg.Tools.Web.Brave.Enabled,
DuckDuckGoMaxResults: cfg.Tools.Web.DuckDuckGo.MaxResults,
DuckDuckGoEnabled: cfg.Tools.Web.DuckDuckGo.Enabled,
+ PerplexityAPIKey: cfg.Tools.Web.Perplexity.APIKey,
+ PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults,
+ PerplexityEnabled: cfg.Tools.Web.Perplexity.Enabled,
}); searchTool != nil {
registry.Register(searchTool)
}
@@ -256,6 +262,10 @@ func (al *AgentLoop) RegisterTool(tool tools.Tool) {
al.tools.Register(tool)
}
+func (al *AgentLoop) SetChannelManager(cm *channels.Manager) {
+ al.channelManager = cm
+}
+
// RecordLastChannel records the last active channel for this workspace.
// This uses the atomic state save mechanism to prevent data loss on crash.
func (al *AgentLoop) RecordLastChannel(channel string) error {
@@ -343,6 +353,11 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
return al.processSystemMessage(ctx, msg)
}
+ // Check for commands
+ if response, handled := al.handleCommand(ctx, msg); handled {
+ return response, nil
+ }
+
// Process as user message
return al.runAgentLoop(ctx, processOptions{
SessionKey: msg.SessionKey,
@@ -525,7 +540,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, opts processOptions) (str
// 13. Optional: summarization
if opts.EnableSummary {
- al.maybeSummarize(opts.SessionKey)
+ al.maybeSummarize(opts.SessionKey, opts.Channel, opts.ChatID)
}
// 14. Optional: send response via bus
@@ -677,7 +692,7 @@ func (al *AgentLoop) runAgentLoopStreaming(ctx context.Context, opts processOpti
// 12. Summarization
if opts.EnableSummary {
- al.maybeSummarize(opts.SessionKey)
+ al.maybeSummarize(opts.SessionKey, opts.Channel, opts.ChatID)
}
// 13. Log response
@@ -717,7 +732,7 @@ func (al *AgentLoop) updateToolContexts(channel, chatID string) {
}
// maybeSummarize triggers summarization if the session history exceeds thresholds.
-func (al *AgentLoop) maybeSummarize(sessionKey string) {
+func (al *AgentLoop) maybeSummarize(sessionKey, channel, chatID string) {
newHistory := al.sessions.GetHistory(sessionKey)
tokenEstimate := al.estimateTokens(newHistory)
threshold := al.contextWindow * 75 / 100
@@ -726,12 +741,80 @@ func (al *AgentLoop) maybeSummarize(sessionKey string) {
if _, loading := al.summarizing.LoadOrStore(sessionKey, true); !loading {
go func() {
defer al.summarizing.Delete(sessionKey)
+ // Notify user about optimization if not an internal channel
+ if !constants.IsInternalChannel(channel) {
+ al.bus.PublishOutbound(bus.OutboundMessage{
+ Channel: channel,
+ ChatID: chatID,
+ Content: "⚠️ Memory threshold reached. Optimizing conversation history...",
+ })
+ }
al.summarizeSession(sessionKey)
}()
}
}
}
+// forceCompression aggressively reduces context when the limit is hit.
+// It drops the oldest 50% of messages (keeping system prompt and last user message).
+func (al *AgentLoop) forceCompression(sessionKey string) {
+ history := al.sessions.GetHistory(sessionKey)
+ if len(history) <= 4 {
+ return
+ }
+
+ // Keep system prompt (usually [0]) and the very last message (user's trigger)
+ // We want to drop the oldest half of the *conversation*
+ // Assuming [0] is system, [1:] is conversation
+ conversation := history[1 : len(history)-1]
+ if len(conversation) == 0 {
+ return
+ }
+
+ // Helper to find the mid-point of the conversation
+ mid := len(conversation) / 2
+
+ // New history structure:
+ // 1. System Prompt
+ // 2. [Summary of dropped part] - synthesized
+ // 3. Second half of conversation
+ // 4. Last message
+
+ // Simplified approach for emergency: Drop first half of conversation
+ // and rely on existing summary if present, or create a placeholder.
+
+ droppedCount := mid
+ keptConversation := conversation[mid:]
+
+ newHistory := make([]messages.Message, 0)
+ newHistory = append(newHistory, history[0]) // System prompt
+
+ // Add a note about compression
+ compressionNote := fmt.Sprintf("[System: Emergency compression dropped %d oldest messages due to context limit]", droppedCount)
+ // If there was an existing summary, we might lose it if it was in the dropped part (which is just messages).
+ // The summary is stored separately in session.Summary, so it persists!
+ // We just need to ensure the user knows there's a gap.
+
+ // We only modify the messages list here
+ newHistory = append(newHistory, messages.Message{
+ Role: "system",
+ Content: compressionNote,
+ })
+
+ newHistory = append(newHistory, keptConversation...)
+ newHistory = append(newHistory, history[len(history)-1]) // Last message
+
+ // Update session
+ al.sessions.SetHistory(sessionKey, newHistory)
+ al.sessions.Save(sessionKey)
+
+ logger.WarnCF("agent", "Forced compression executed", map[string]interface{}{
+ "session_key": sessionKey,
+ "dropped_msgs": droppedCount,
+ "new_count": len(newHistory),
+ })
+}
+
// GetStartupInfo returns information about loaded tools and skills for logging.
func (al *AgentLoop) GetStartupInfo() map[string]interface{} {
info := make(map[string]interface{})
@@ -806,7 +889,7 @@ func (al *AgentLoop) summarizeSession(sessionKey string) {
if m.Role != "user" && m.Role != "assistant" {
continue
}
- msgTokens := len(m.Content) / 4
+ msgTokens := len(m.Content) / 2
if msgTokens > maxMessageTokens {
omitted = true
continue
@@ -908,9 +991,92 @@ func (al *AgentLoop) callModel(ctx context.Context, prompt string) (string, erro
// estimateTokens estimates the number of tokens in a message list.
func (al *AgentLoop) estimateTokens(msgs []messages.Message) int {
- total := 0
+ totalChars := 0
for _, m := range msgs {
- total += len(m.Content) / 4 // Simple heuristic: 4 chars per token
+ totalChars += utf8.RuneCountInString(m.Content)
}
- return total
+ return totalChars * 2 / 5
+}
+
+func (al *AgentLoop) handleCommand(ctx context.Context, msg bus.InboundMessage) (string, bool) {
+ content := strings.TrimSpace(msg.Content)
+ if !strings.HasPrefix(content, "/") {
+ return "", false
+ }
+
+ parts := strings.Fields(content)
+ if len(parts) == 0 {
+ return "", false
+ }
+
+ cmd := parts[0]
+ args := parts[1:]
+
+ switch cmd {
+ case "/show":
+ if len(args) < 1 {
+ return "Usage: /show [model|channel]", true
+ }
+ switch args[0] {
+ case "model":
+ return fmt.Sprintf("Current model: %s", al.model), true
+ case "channel":
+ return fmt.Sprintf("Current channel: %s", msg.Channel), true
+ default:
+ return fmt.Sprintf("Unknown show target: %s", args[0]), true
+ }
+
+ case "/list":
+ if len(args) < 1 {
+ return "Usage: /list [models|channels]", true
+ }
+ switch args[0] {
+ case "models":
+ // TODO: Fetch available models dynamically if possible
+ return "Available models: glm-4.7, claude-3-5-sonnet, gpt-4o (configured in config.json/env)", true
+ case "channels":
+ if al.channelManager == nil {
+ return "Channel manager not initialized", true
+ }
+ channels := al.channelManager.GetEnabledChannels()
+ if len(channels) == 0 {
+ return "No channels enabled", true
+ }
+ return fmt.Sprintf("Enabled channels: %s", strings.Join(channels, ", ")), true
+ default:
+ return fmt.Sprintf("Unknown list target: %s", args[0]), true
+ }
+
+ case "/switch":
+ if len(args) < 3 || args[1] != "to" {
+ return "Usage: /switch [model|channel] to 
+ 
+ 
