From 836cbc3066d6af5ac9e25e2a8ccd6e89f06b670e Mon Sep 17 00:00:00 2001 From: BeaconCat Date: Sat, 28 Mar 2026 18:46:21 +0800 Subject: [PATCH] docs: add Malay README and docs, add v0.2.4 news to all languages - Add README.my.md (full Malay translation from English, including macOS guide, MiMo provider, unified WeCom row, all sections) - Add docs/my/ (chat-apps, configuration, debug, docker, spawn-tasks, troubleshooting) from upstream PR #1770 - Add [Malay](README.my.md) language link to all 8 existing READMEs - Add v0.2.4 news entry to all 9 READMEs (en/zh/fr/ja/pt-br/vi/id/it/my) - Move 2026-02-26 20K Stars entry into Earlier news in all READMEs Co-Authored-By: Claude Opus 4.6 --- README.fr.md | 10 +- README.id.md | 10 +- README.it.md | 10 +- README.ja.md | 12 +- README.md | 8 +- README.my.md | 599 +++++++++++++++++++++++++++++++++++++ README.pt-br.md | 8 +- README.vi.md | 8 +- README.zh.md | 8 +- docs/my/chat-apps.md | 431 ++++++++++++++++++++++++++ docs/my/configuration.md | 216 +++++++++++++ docs/my/debug.md | 33 ++ docs/my/docker.md | 166 ++++++++++ docs/my/spawn-tasks.md | 61 ++++ docs/my/troubleshooting.md | 43 +++ 15 files changed, 1594 insertions(+), 29 deletions(-) create mode 100644 README.my.md create mode 100644 docs/my/chat-apps.md create mode 100644 docs/my/configuration.md create mode 100644 docs/my/debug.md create mode 100644 docs/my/docker.md create mode 100644 docs/my/spawn-tasks.md create mode 100644 docs/my/troubleshooting.md diff --git a/README.fr.md b/README.fr.md index f9812bd64..4fd326102 100644 --- a/README.fr.md +++ b/README.fr.md @@ -18,7 +18,7 @@ Discord

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md) +[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md) @@ -57,17 +57,19 @@ ## 📢 Actualités +2026-03-25 🚀 **v0.2.4 publiée !** Refonte de l'architecture Agent (SubTurn, Hooks, Steering, EventBus), intégration WeChat/WeCom, renforcement de la sécurité (.security.yml, filtrage des données sensibles), nouveaux providers (AWS Bedrock, Azure, Xiaomi MiMo), et 35 corrections de bugs. PicoClaw a atteint **26K Stars** ! + 2026-03-17 🚀 **v0.2.3 publiée !** Interface system tray (Windows & Linux), requête de statut des sous-agents (`spawn_status`), rechargement à chaud expérimental du Gateway, sécurisation Cron, et 2 correctifs de sécurité. PicoClaw a atteint **25K Stars** ! -2026-03-09 🎉 **v0.2.1 — La plus grande mise à jour à ce jour !** Support du protocole MCP, 4 nouveaux channels (Matrix/IRC/WeCom/Discord Proxy), 3 nouveaux providers (Kimi/Minimax/Avian), pipeline vision, stockage mémoire JSONL, routage de modèles. +2026-03-09 🎉 **v0.2.1 — Plus grande mise à jour à ce jour !** Support du protocole MCP, 4 nouveaux channels (Matrix/IRC/WeCom/Discord Proxy), 3 nouveaux providers (Kimi/Minimax/Avian), pipeline vision, stockage mémoire JSONL, routage de modèles. 2026-02-28 📦 **v0.2.0** publiée avec support Docker Compose et Web UI Launcher. -2026-02-26 🎉 PicoClaw atteint **20K Stars** en seulement 17 jours ! L'orchestration automatique des channels et les interfaces de capacités sont disponibles. -
Actualités précédentes... +2026-02-26 🎉 PicoClaw atteint **20K Stars** en seulement 17 jours ! L'orchestration automatique des channels et les interfaces de capacités sont disponibles. + 2026-02-16 🎉 PicoClaw dépasse 12K Stars en une semaine ! Rôles de mainteneurs communautaires et [Roadmap](ROADMAP.md) officiellement lancés. 2026-02-13 🎉 PicoClaw dépasse 5000 Stars en 4 jours ! Roadmap du projet et groupes de développeurs en cours. diff --git a/README.id.md b/README.id.md index 4ef999ac2..d88f5eb32 100644 --- a/README.id.md +++ b/README.id.md @@ -18,7 +18,7 @@ Discord

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [English](README.md) | **Bahasa Indonesia** +[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Malay](README.my.md) | [English](README.md) | **Bahasa Indonesia** @@ -56,17 +56,19 @@ ## 📢 Berita +2026-03-25 🚀 **v0.2.4 Dirilis!** Perombakan arsitektur Agent (SubTurn, Hooks, Steering, EventBus), integrasi WeChat/WeCom, penguatan keamanan (.security.yml, penyaringan data sensitif), provider baru (AWS Bedrock, Azure, Xiaomi MiMo), dan 35 perbaikan bug. PicoClaw telah mencapai **26K Stars**! + 2026-03-17 🚀 **v0.2.3 Dirilis!** UI system tray (Windows & Linux), pelacakan status sub-agent (`spawn_status`), eksperimental Gateway hot-reload, gerbang keamanan Cron, dan 2 perbaikan keamanan. PicoClaw telah mencapai **25K Stars**! -2026-03-09 🎉 **v0.2.1 — Update terbesar sejauh ini!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline vision, penyimpanan memori JSONL, routing model. +2026-03-09 🎉 **v0.2.1 — Pembaruan terbesar sejauh ini!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline visi, penyimpanan memori JSONL, perutean model. 2026-02-28 📦 **v0.2.0** dirilis dengan dukungan Docker Compose dan Web UI Launcher. -2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas kini aktif. -
Berita sebelumnya... +2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas kini aktif. + 2026-02-16 🎉 PicoClaw menembus 12K Stars dalam satu minggu! Peran maintainer komunitas dan [Roadmap](ROADMAP.md) resmi diluncurkan. 2026-02-13 🎉 PicoClaw menembus 5000 Stars dalam 4 hari! Roadmap proyek dan grup pengembang sedang dalam proses. diff --git a/README.it.md b/README.it.md index b715ea33a..5ed82f15d 100644 --- a/README.it.md +++ b/README.it.md @@ -18,7 +18,7 @@ Discord

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [English](README.md) +[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md) @@ -56,17 +56,19 @@ ## 📢 Novità +2026-03-25 🚀 **v0.2.4 rilasciata!** Revisione dell'architettura Agent (SubTurn, Hooks, Steering, EventBus), integrazione WeChat/WeCom, rafforzamento della sicurezza (.security.yml, filtraggio dati sensibili), nuovi provider (AWS Bedrock, Azure, Xiaomi MiMo) e 35 correzioni di bug. PicoClaw raggiunge **26K Stars**! + 2026-03-17 🚀 **v0.2.3 rilasciata!** Interfaccia system tray (Windows & Linux), query sullo stato dei sub-agent (`spawn_status`), hot-reload sperimentale del Gateway, gate di sicurezza per Cron e 2 correzioni di sicurezza. PicoClaw raggiunge **25K Stars**! -2026-03-09 🎉 **v0.2.1 — Il più grande aggiornamento di sempre!** Supporto al protocollo MCP, 4 nuovi canali (Matrix/IRC/WeCom/Discord Proxy), 3 nuovi provider (Kimi/Minimax/Avian), pipeline di visione, store di memoria JSONL e routing dei modelli. +2026-03-09 🎉 **v0.2.1 — Il più grande aggiornamento di sempre!** Supporto al protocollo MCP, 4 nuovi canali (Matrix/IRC/WeCom/Discord Proxy), 3 nuovi provider (Kimi/Minimax/Avian), pipeline visiva, archivio memoria JSONL, routing dei modelli. 2026-02-28 📦 **v0.2.0** rilasciata con supporto Docker Compose e Web UI Launcher. -2026-02-26 🎉 PicoClaw raggiunge **20K stelle** in soli 17 giorni! Orchestrazione automatica dei canali e interfacce di capacità sono attive. -
Notizie precedenti... +2026-02-26 🎉 PicoClaw raggiunge **20K stelle** in soli 17 giorni! Orchestrazione automatica dei canali e interfacce di capacità sono attive. + 2026-02-16 🎉 PicoClaw supera 12K stelle in una settimana! Ruoli di maintainer della community e [Roadmap](ROADMAP.md) pubblicati ufficialmente. 2026-02-13 🎉 PicoClaw supera 5000 stelle in 4 giorni! Roadmap del progetto e gruppi sviluppatori in fase di avvio. diff --git a/README.ja.md b/README.ja.md index 6b2bfc2b3..47d43eb56 100644 --- a/README.ja.md +++ b/README.ja.md @@ -18,7 +18,7 @@ Discord

-[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md) +[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md) @@ -56,17 +56,19 @@ ## 📢 ニュース +2026-03-25 🚀 **v0.2.4 リリース！** Agent アーキテクチャ全面刷新（SubTurn、Hooks、Steering、EventBus）、WeChat/WeCom 統合、セキュリティ強化（.security.yml、機密データフィルタリング）、新プロバイダー（AWS Bedrock、Azure、Xiaomi MiMo）、35 件のバグ修正。PicoClaw **26K ⭐** 達成！ + 2026-03-17 🚀 **v0.2.3 リリース！** システムトレイ UI（Windows & Linux）、サブエージェントステータス追跡（`spawn_status`）、実験的 Gateway ホットリロード、cron セキュリティゲート、セキュリティ修正 2 件。PicoClaw **25K ⭐** 達成！ -2026-03-09 🎉 **v0.2.1 — 史上最大のアップデート！** MCP プロトコル対応、4 つの新 Channel（Matrix/IRC/WeCom/Discord Proxy）、3 つの新 Provider（Kimi/Minimax/Avian）、ビジョンパイプライン、JSONL メモリストア、モデルルーティング。 +2026-03-09 🎉 **v0.2.1 — 最大のアップデート！** MCP プロトコルサポート、4 つの新チャンネル (Matrix/IRC/WeCom/Discord Proxy)、3 つの新プロバイダー (Kimi/Minimax/Avian)、ビジョンパイプライン、JSONL メモリストア、モデルルーティング。 -2026-02-28 📦 **v0.2.0** リリース — Docker Compose 対応と Web UI Launcher。 - -2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成！Channel 自動オーケストレーションとケイパビリティインターフェースが実装されました。 +2026-02-28 📦 **v0.2.0** リリース — Docker Compose と Web UI Launcher サポート。
過去のニュース... +2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成！Channel 自動オーケストレーションとケイパビリティインターフェースが実装されました。 + 2026-02-16 🎉 PicoClaw が 1 週間で 12K スター達成！コミュニティメンテナーの役割と[ロードマップ](ROADMAP.md)が正式に公開されました。 2026-02-13 🎉 PicoClaw が 4 日間で 5000 スター達成！プロジェクトロードマップと開発者グループの準備が進行中。 diff --git a/README.md b/README.md index 31ae19eb4..e963fb1cf 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Discord

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **English** +[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | **English** @@ -56,17 +56,19 @@ ## 📢 News +2026-03-25 🚀 **v0.2.4 Released!** Agent architecture overhaul (SubTurn, Hooks, Steering, EventBus), WeChat/WeCom integration, security hardening (.security.yml, sensitive data filtering), new providers (AWS Bedrock, Azure, Xiaomi MiMo), and 35 bug fixes. PicoClaw has reached **26K Stars**! + 2026-03-17 🚀 **v0.2.3 Released!** System tray UI (Windows & Linux), sub-agent status query (`spawn_status`), experimental Gateway hot-reload, Cron security gating, and 2 security fixes. PicoClaw has reached **25K Stars**! 2026-03-09 🎉 **v0.2.1 — Biggest update yet!** MCP protocol support, 4 new channels (Matrix/IRC/WeCom/Discord Proxy), 3 new providers (Kimi/Minimax/Avian), vision pipeline, JSONL memory store, model routing. 2026-02-28 📦 **v0.2.0** released with Docker Compose and Web UI Launcher support. -2026-02-26 🎉 PicoClaw hits **20K Stars** in just 17 days! Channel auto-orchestration and capability interfaces are live. -
Earlier news... +2026-02-26 🎉 PicoClaw hits **20K Stars** in just 17 days! Channel auto-orchestration and capability interfaces are live. + 2026-02-16 🎉 PicoClaw breaks 12K Stars in one week! Community maintainer roles and [Roadmap](ROADMAP.md) officially launched. 2026-02-13 🎉 PicoClaw breaks 5000 Stars in 4 days! Project roadmap and developer groups in progress. diff --git a/README.my.md b/README.my.md new file mode 100644 index 000000000..2f1a38942 --- /dev/null +++ b/README.my.md @@ -0,0 +1,599 @@ +
+PicoClaw + +

PicoClaw: Pembantu AI Ultra-Cekap dalam Go

+ +

Perkakasan $10 · RAM 10MB · Boot ms · Jom, PicoClaw!

+

+ Go + Hardware + License +
+ Website + Docs + Wiki +
+ Twitter + + Discord +

+ +[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **Malay** | [English](README.md) + +
+ +--- + +> **PicoClaw** adalah projek sumber terbuka bebas yang dilancarkan oleh [Sipeed](https://sipeed.com), ditulis sepenuhnya dalam **Go** dari awal — bukan cabang OpenClaw, NanoBot, atau projek lain. + +**PicoClaw** adalah pembantu AI peribadi ultra-ringan yang terinspirasi oleh [NanoBot](https://github.com/HKUDS/nanobot). Ia dibina semula dari awal dalam **Go** melalui proses "self-bootstrapping" — AI Agent itu sendiri yang memacu migrasi seni bina dan pengoptimuman kod. + +**Berjalan pada perkakasan $10 dengan RAM <10MB** — 99% lebih sedikit memori daripada OpenClaw dan 98% lebih murah daripada Mac mini! + + + + + + +
+

+ +

+		 +

+ +

+
+ +> [!CAUTION] +> **Notis Keselamatan** +> +> * **TIADA KRIPTO:** PicoClaw **tidak** mengeluarkan sebarang token atau mata wang kripto rasmi. Semua tuntutan di `pump.fun` atau platform dagangan lain adalah **penipuan**. +> * **DOMAIN RASMI:** Satu-satunya laman web rasmi ialah **[picoclaw.io](https://picoclaw.io)**, dan laman web syarikat ialah **[sipeed.com](https://sipeed.com)** +> * **BERHATI-HATI:** Banyak domain `.ai/.org/.com/.net/...` telah didaftarkan oleh pihak ketiga. Jangan percayai mereka. +> * **NOTA:** PicoClaw dalam pembangunan pesat awal. Mungkin terdapat isu keselamatan yang belum diselesaikan. Jangan deploy ke pengeluaran sebelum v1.0. + + +## 📢 Berita + +2026-03-25 🚀 **v0.2.4 Dikeluarkan!** Penstrukturan semula seni bina Agent (SubTurn, Hooks, Steering, EventBus), integrasi WeChat/WeCom, penguatan keselamatan (.security.yml, penapisan data sensitif), penyedia baharu (AWS Bedrock, Azure, Xiaomi MiMo), dan 35 pembetulan pepijat. PicoClaw mencapai **26K Stars**! + +2026-03-17 🚀 **v0.2.3 Dikeluarkan!** UI dulang sistem (Windows & Linux), pertanyaan status sub-agent (`spawn_status`), muat semula panas Gateway eksperimental, kawalan keselamatan Cron, dan 2 pembetulan keselamatan. PicoClaw mencapai **25K Stars**! + +2026-03-09 🎉 **v0.2.1 — Kemas kini terbesar setakat ini!** Sokongan protokol MCP, 4 saluran baharu (Matrix/IRC/WeCom/Discord Proxy), 3 penyedia baharu (Kimi/Minimax/Avian), saluran paip visi, storan memori JSONL, penghalaan model. + +2026-02-28 📦 **v0.2.0** dikeluarkan dengan sokongan Docker Compose dan Pelancar Web UI. + +
+Berita terdahulu... + +2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi saluran automatik dan antara muka keupayaan kini aktif. + +2026-02-16 🎉 PicoClaw melepasi 12K Stars dalam seminggu! Peranan penyelenggara komuniti dan [Peta Jalan](ROADMAP.md) dilancarkan secara rasmi. + +2026-02-13 🎉 PicoClaw melepasi 5000 Stars dalam 4 hari! Peta jalan projek dan kumpulan pembangun sedang dalam proses. + +2026-02-09 🎉 **PicoClaw Dikeluarkan!** Dibina dalam 1 hari untuk membawa AI Agent ke perkakasan $10 dengan RAM <10MB. Jom, PicoClaw! + +
+ +## ✨ Ciri-ciri + +🪶 **Ultra-ringan**: Jejak memori teras <10MB — 99% lebih kecil daripada OpenClaw.* + +💰 **Kos minimum**: Cukup cekap untuk berjalan pada perkakasan $10 — 98% lebih murah daripada Mac mini. + +⚡️ **Boot kilat**: 400x lebih pantas. Boot dalam <1s walaupun pada pemproses teras tunggal 0.6GHz. + +🌍 **Benar-benar mudah alih**: Binari tunggal merentasi seni bina RISC-V, ARM, MIPS, dan x86. + +🤖 **Dibantu AI**: Pelaksanaan Go tulen — 95% kod teras dijana oleh Agent dan diperhalusi melalui semakan manusia. + +🔌 **Sokongan MCP**: Integrasi [Model Context Protocol](https://modelcontextprotocol.io/) natif. + +👁️ **Saluran paip visi**: Hantar imej dan fail terus ke Agent — pengekodan base64 automatik untuk LLM multimodal. + +🧠 **Penghalaan pintar**: Penghalaan model berasaskan peraturan — pertanyaan mudah ke model ringan, menjimatkan kos API. + +_*Binaan terkini mungkin menggunakan 10-20MB disebabkan penggabungan PR yang pesat. Pengoptimuman sumber dirancang. Perbandingan kelajuan boot berdasarkan penanda aras teras tunggal 0.8GHz (lihat jadual di bawah)._ + +
+ +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **Bahasa** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB*** | +| **Masa Boot** (teras 0.8GHz) | >500s | >30s | **<1s** | +| **Kos** | Mac Mini $599 | Kebanyakan papan Linux ~$50 | **Mana-mana papan Linux dari $10** | + +PicoClaw + +
+ +> **[Senarai Keserasian Perkakasan](docs/hardware-compatibility.md)** — Lihat semua papan yang diuji, dari RISC-V $5 hingga Raspberry Pi hingga telefon Android. + +

+Keserasian Perkakasan PicoClaw +

+ +## 🦾 Demonstrasi + +### 🛠️ Aliran Kerja Pembantu Standard + + + + + + + + + + + + + + + + + +

Mod Jurutera Full-Stack

Pengelogan & Perancangan

Carian Web & Pembelajaran

Bangun · Deploy · SkalaJadual · Automatik · IngatTemui · Wawasan · Trend
+ +### 🐜 Deployment Jejak Rendah yang Inovatif + +PicoClaw boleh digunakan pada hampir mana-mana peranti Linux! + +- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) untuk pembantu rumah minimal +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html) untuk operasi pelayan automatik +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) untuk pengawasan pintar + + + +🌟 Lebih Banyak Kes Deployment Menanti! + + +## 📦 Pemasangan + +### Muat turun dari picoclaw.io (Disyorkan) + +Lawati **[picoclaw.io](https://picoclaw.io)** — laman web rasmi mengesan platform anda secara automatik dan menyediakan muat turun satu klik. + +### Muat turun binari pra-kompil + +Muat turun binari untuk platform anda dari halaman [GitHub Releases](https://github.com/sipeed/picoclaw/releases). + +### Bina dari sumber (untuk pembangunan) + +```bash +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw +make deps + +# Bina binari teras +make build + +# Bina Pelancar Web UI (diperlukan untuk mod WebUI) +make build-launcher + +# Bina untuk pelbagai platform +make build-all + +# Bina untuk Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64) +make build-pi-zero + +# Bina dan pasang +make install +``` + +**Raspberry Pi Zero 2 W:** Gunakan binari yang sepadan dengan OS anda: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Atau jalankan `make build-pi-zero` untuk membina kedua-duanya. + +## 🚀 Panduan Permulaan Pantas + +### 🌐 Pelancar WebUI (Disyorkan untuk Desktop) + +Pelancar WebUI menyediakan antara muka berasaskan pelayar untuk konfigurasi dan sembang. Ini adalah cara termudah untuk bermula — tiada pengetahuan baris arahan diperlukan. + +**Pilihan 1: Klik dua kali (Desktop)** + +Selepas memuat turun dari [picoclaw.io](https://picoclaw.io), klik dua kali `picoclaw-launcher` (atau `picoclaw-launcher.exe` pada Windows). Pelayar anda akan dibuka secara automatik di `http://localhost:18800`. + +**Pilihan 2: Baris arahan** + +```bash +picoclaw-launcher +# Buka http://localhost:18800 dalam pelayar anda +``` + +> [!TIP] +> **Akses jauh / Docker / VM:** Tambah bendera `-public` untuk mendengar pada semua antara muka: +> ```bash +> picoclaw-launcher -public +> ``` + +

+Pelancar WebUI +

+ +**Memulakan:** Buka WebUI, kemudian: **1)** Konfigurasikan Penyedia (tambah kunci API LLM) -> **2)** Konfigurasikan Saluran (cth. Telegram) -> **3)** Mulakan Gateway -> **4)** Sembang! + +Untuk dokumentasi WebUI terperinci, lihat [docs.picoclaw.io](https://docs.picoclaw.io). + +
+Docker (alternatif) + +```bash +# 1. Klon repo ini +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. Jalankan pertama kali — jana docker/data/config.json secara automatik kemudian keluar +docker compose -f docker/docker-compose.yml --profile launcher up + +# 3. Tetapkan kunci API anda +vim docker/data/config.json + +# 4. Mulakan +docker compose -f docker/docker-compose.yml --profile launcher up -d +# Buka http://localhost:18800 +``` + +> **Pengguna Docker / VM:** Gateway mendengar pada `127.0.0.1` secara lalai. Tetapkan `PICOCLAW_GATEWAY_HOST=0.0.0.0` atau gunakan bendera `-public` untuk membolehkan akses dari hos. + +```bash +# Semak log +docker compose -f docker/docker-compose.yml logs -f + +# Henti +docker compose -f docker/docker-compose.yml --profile launcher down + +# Kemas kini +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ + +
+macOS — Amaran Keselamatan Pelancaran Pertama + +macOS mungkin menyekat `picoclaw-launcher` pada pelancaran pertama kerana ia dimuat turun dari internet dan tidak disahkan melalui Mac App Store. + +**Langkah 1:** Klik dua kali `picoclaw-launcher`. Anda akan melihat amaran keselamatan: + +

+Amaran macOS Gatekeeper +

+ +> *"picoclaw-launcher" Tidak Dibuka — Apple tidak dapat mengesahkan "picoclaw-launcher" bebas daripada perisian hasad yang mungkin membahayakan Mac anda atau menjejaskan privasi anda.* + +**Langkah 2:** Buka **Tetapan Sistem** → **Privasi & Keselamatan** → tatal ke bawah ke bahagian **Keselamatan** → klik **Buka Juga** → sahkan dengan mengklik **Buka Juga** dalam dialog. + +

+macOS Privasi & Keselamatan — Buka Juga +

+ +Selepas langkah sekali ini, `picoclaw-launcher` akan dibuka secara normal pada pelancaran seterusnya. + +
+ +### 💻 Pelancar TUI (Disyorkan untuk Headless / SSH) + +Pelancar TUI menyediakan antara muka terminal lengkap untuk konfigurasi dan pengurusan. Sesuai untuk pelayan, Raspberry Pi, dan persekitaran tanpa kepala lain. + +```bash +picoclaw-launcher-tui +``` + +

+Pelancar TUI +

+ +**Memulakan:** + +Gunakan menu TUI untuk: **1)** Konfigurasikan Penyedia -> **2)** Konfigurasikan Saluran -> **3)** Mulakan Gateway -> **4)** Sembang! + +Untuk dokumentasi TUI terperinci, lihat [docs.picoclaw.io](https://docs.picoclaw.io). + +### 📱 Android + +Berikan telefon lama anda kehidupan baru! Jadikannya Pembantu AI pintar dengan PicoClaw. + +**Pilihan 1: Termux (tersedia sekarang)** + +1. Pasang [Termux](https://github.com/termux/termux-app) (muat turun dari [GitHub Releases](https://github.com/termux/termux-app/releases), atau cari di F-Droid / Google Play) +2. Jalankan arahan berikut: + +```bash +# Muat turun keluaran terkini +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot menyediakan susun atur sistem fail Linux standard +``` + +Kemudian ikuti bahagian Pelancar Terminal di bawah untuk melengkapkan konfigurasi. + +PicoClaw pada Termux + +**Pilihan 2: APK (akan datang)** + +APK Android bebas dengan WebUI terbina dalam sedang dalam pembangunan. Nantikan! + +
+Pelancar Terminal (untuk persekitaran terhad sumber) + +Untuk persekitaran minimal di mana hanya binari teras `picoclaw` tersedia (tiada UI Pelancar), anda boleh mengkonfigurasi semua melalui baris arahan dan fail konfigurasi JSON. + +**1. Mulakan** + +```bash +picoclaw onboard +``` + +Ini mencipta `~/.picoclaw/config.json` dan direktori ruang kerja. + +**2. Konfigurasikan** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4" + } + ] +} +``` + +> Lihat `config/config.example.json` dalam repo untuk templat konfigurasi lengkap. Nota: kunci API kini disimpan dalam `.security.yml`, bukan `config.json`. + +**3. Sembang** + +```bash +picoclaw agent -m "Apa itu 2+2?" + +# Mod interaktif +picoclaw agent + +# Mulakan gateway untuk integrasi aplikasi sembang +picoclaw gateway +``` + +
+ + +## 🔌 Penyedia (LLM) + +PicoClaw menyokong 30+ penyedia LLM melalui konfigurasi `model_list`. Gunakan format `protokol/model`: + +| Penyedia | Protokol | Kunci API | Nota | +|----------|----------|-----------|------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Diperlukan | GPT-5.4, GPT-4o, o3, dll. | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Diperlukan | Claude Opus 4.6, Sonnet 4.6, dll. | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Diperlukan | Gemini 3 Flash, 2.5 Pro, dll. | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Diperlukan | 200+ model, API bersatu | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Diperlukan | GLM-4.7, GLM-5, dll. | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Diperlukan | DeepSeek-V3, DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | Diperlukan | Doubao, model Ark | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Diperlukan | Qwen3, Qwen-Max, dll. | +| [Groq](https://console.groq.com/keys) | `groq/` | Diperlukan | Inferens pantas (Llama, Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Diperlukan | Model Kimi | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Diperlukan | Model MiniMax | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Diperlukan | Mistral Large, Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Diperlukan | Model hos NVIDIA | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Diperlukan | Inferens pantas | +| [Novita AI](https://novita.ai/) | `novita/` | Diperlukan | Pelbagai model terbuka | +| [Xiaomi MiMo](https://platform.xiaomimimo.com/) | `mimo/` | Diperlukan | Model MiMo | +| [Ollama](https://ollama.com/) | `ollama/` | Tidak perlu | Model tempatan, self-hosted | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | Tidak perlu | Deployment tempatan, serasi OpenAI | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Berbeza | Proksi untuk 100+ penyedia | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Diperlukan | Deployment Azure perusahaan | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Log masuk kod peranti | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | +| [AWS Bedrock](https://console.aws.amazon.com/bedrock)* | `bedrock/` | Kelayakan AWS | Claude, Llama, Mistral pada AWS | + +> \* AWS Bedrock memerlukan tag binaan: `go build -tags bedrock`. Tetapkan `api_base` kepada nama rantau (cth. `us-east-1`) untuk resolusi endpoint automatik merentasi semua partition AWS. Apabila menggunakan URL endpoint penuh, anda juga perlu mengkonfigurasi `AWS_REGION` melalui pemboleh ubah persekitaran. + +
+Deployment tempatan (Ollama, vLLM, dll.) + +**Ollama:** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM:** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +Untuk butiran konfigurasi penyedia penuh, lihat [Penyedia & Model](docs/providers.md). + +
+ + +## 💬 Saluran (Aplikasi Sembang) + +Bercakap dengan PicoClaw anda melalui 17+ platform pemesejan: + +| Saluran | Persediaan | Protokol | Dok | +|---------|-----------|----------|-----| +| **Telegram** | Mudah (token bot) | Long polling | [Panduan](docs/channels/telegram/README.md) | +| **Discord** | Mudah (token bot + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) | +| **WhatsApp** | Mudah (imbas QR atau URL jambatan) | Natif / Jambatan | [Panduan](docs/chat-apps.md#whatsapp) | +| **Weixin** | Mudah (imbas QR natif) | iLink API | [Panduan](docs/chat-apps.md#weixin) | +| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) | +| **Slack** | Mudah (token bot + app) | Socket Mode | [Panduan](docs/channels/slack/README.md) | +| **Matrix** | Sederhana (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) | +| **DingTalk** | Sederhana (kelayakan klien) | Stream | [Panduan](docs/channels/dingtalk/README.md) | +| **Feishu / Lark** | Sederhana (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) | +| **LINE** | Sederhana (kelayakan + webhook) | Webhook | [Panduan](docs/channels/line/README.md) | +| **WeCom** | Mudah (log masuk QR atau manual) | WebSocket | [Panduan](docs/channels/wecom/README.md) | +| **IRC** | Sederhana (pelayan + nick) | Protokol IRC | [Panduan](docs/chat-apps.md#irc) | +| **OneBot** | Sederhana (URL WebSocket) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) | +| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) | +| **Pico** | Mudah (aktifkan) | Protokol natif | Terbina dalam | +| **Pico Client** | Mudah (URL WebSocket) | WebSocket | Terbina dalam | + +> Semua saluran berasaskan webhook berkongsi satu pelayan HTTP Gateway (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). Feishu menggunakan mod WebSocket/SDK dan tidak menggunakan pelayan HTTP yang dikongsi. + +Untuk arahan persediaan saluran terperinci, lihat [Konfigurasi Aplikasi Sembang](docs/my/chat-apps.md). + +## 🔧 Alat + +### 🔍 Carian Web + +PicoClaw boleh mencari web untuk menyediakan maklumat terkini. Konfigurasikan dalam `tools.web`: + +| Enjin Carian | Kunci API | Peringkat Percuma | Pautan | +|-------------|-----------|-------------------|--------| +| DuckDuckGo | Tidak perlu | Tanpa had | Sandaran terbina dalam | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Diperlukan | 1000 pertanyaan/hari | Dikuasai AI, dioptimumkan untuk China | +| [Tavily](https://tavily.com) | Diperlukan | 1000 pertanyaan/bulan | Dioptimumkan untuk AI Agent | +| [Brave Search](https://brave.com/search/api) | Diperlukan | 2000 pertanyaan/bulan | Pantas dan peribadi | +| [Perplexity](https://www.perplexity.ai) | Diperlukan | Berbayar | Carian dikuasai AI | +| [SearXNG](https://github.com/searxng/searxng) | Tidak perlu | Self-hosted | Enjin metasearch percuma | +| [GLM Search](https://open.bigmodel.cn/) | Diperlukan | Berbeza | Carian web Zhipu | + +### ⚙️ Alat Lain + +PicoClaw menyertakan alat terbina dalam untuk operasi fail, pelaksanaan kod, penjadualan, dan banyak lagi. Lihat [Konfigurasi Alat](docs/tools_configuration.md) untuk butiran. + +## 🎯 Kemahiran + +Kemahiran adalah keupayaan modular yang melanjutkan Agent anda. Ia dimuatkan dari fail `SKILL.md` dalam ruang kerja anda. + +**Pasang kemahiran dari ClawHub:** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**Konfigurasikan token ClawHub** (pilihan, untuk had kadar lebih tinggi): + +Tambah ke `config.json` anda: +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +Untuk butiran lanjut, lihat [Konfigurasi Alat - Kemahiran](docs/tools_configuration.md#skills-tool). + +## 🔗 MCP (Protokol Konteks Model) + +PicoClaw menyokong [MCP](https://modelcontextprotocol.io/) secara natif — sambungkan mana-mana pelayan MCP untuk melanjutkan keupayaan Agent anda dengan alat dan sumber data luaran. + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +Untuk konfigurasi MCP penuh (pengangkutan stdio, SSE, HTTP, Penemuan Alat), lihat [Konfigurasi Alat - MCP](docs/tools_configuration.md#mcp-tool). + +## ClawdChat Sertai Rangkaian Sosial Agent + +Sambungkan PicoClaw ke Rangkaian Sosial Agent dengan menghantar satu mesej melalui CLI atau mana-mana Aplikasi Sembang yang disepadukan. + +**Baca `https://clawdchat.ai/skill.md` dan ikuti arahan untuk menyertai [ClawdChat.ai](https://clawdchat.ai)** + +## 🖥️ Rujukan CLI + +| Arahan | Penerangan | +| ------ | ---------- | +| `picoclaw onboard` | Mulakan konfigurasi & ruang kerja | +| `picoclaw auth weixin` | Sambungkan akaun WeChat melalui QR | +| `picoclaw agent -m "..."` | Sembang dengan agent | +| `picoclaw agent` | Mod sembang interaktif | +| `picoclaw gateway` | Mulakan gateway | +| `picoclaw status` | Tunjukkan status | +| `picoclaw version` | Tunjukkan maklumat versi | +| `picoclaw model` | Lihat atau tukar model lalai | +| `picoclaw cron list` | Senaraikan semua kerja berjadual | +| `picoclaw cron add ...` | Tambah kerja berjadual | +| `picoclaw cron disable` | Lumpuhkan kerja berjadual | +| `picoclaw cron remove` | Buang kerja berjadual | +| `picoclaw skills list` | Senaraikan kemahiran yang dipasang | +| `picoclaw skills install` | Pasang kemahiran | +| `picoclaw migrate` | Migrasi data dari versi lama | +| `picoclaw auth login` | Sahkan dengan penyedia | + +### ⏰ Tugasan Berjadual / Peringatan + +PicoClaw menyokong peringatan berjadual dan tugasan berulang melalui alat `cron`: + +* **Peringatan sekali**: "Ingatkan saya dalam 10 minit" -> pencetus sekali selepas 10 minit +* **Tugasan berulang**: "Ingatkan saya setiap 2 jam" -> pencetus setiap 2 jam +* **Ungkapan Cron**: "Ingatkan saya pada pukul 9 pagi setiap hari" -> menggunakan ungkapan cron + +## 📚 Dokumentasi + +Untuk panduan terperinci melebihi README ini: + +| Topik | Penerangan | +|-------|------------| +| [Docker & Permulaan Pantas](docs/my/docker.md) | Persediaan Docker Compose, mod Launcher/Agent | +| [Aplikasi Sembang](docs/my/chat-apps.md) | Panduan persediaan 17+ saluran | +| [Konfigurasi](docs/my/configuration.md) | Pemboleh ubah persekitaran, susun atur ruang kerja | +| [Penyedia & Model](docs/providers.md) | 30+ penyedia LLM, penghalaan model | +| [Spawn & Tugasan Async](docs/my/spawn-tasks.md) | Tugasan pantas, tugasan panjang dengan spawn | +| [Penyelesaian Masalah](docs/my/troubleshooting.md) | Isu biasa dan penyelesaian | +| [Konfigurasi Alat](docs/tools_configuration.md) | Aktif/nyahaktif alat, dasar exec, MCP, Kemahiran | +| [Keserasian Perkakasan](docs/hardware-compatibility.md) | Papan yang diuji, keperluan minimum | + +## 🤝 Sumbangan & Peta Jalan + +PR dialu-alukan! Kod sumber sengaja dibuat kecil dan mudah dibaca. + +Lihat [Peta Jalan Komuniti](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan. + +Kumpulan pembangun sedang dibina, sertai selepas PR pertama anda digabungkan! + +Kumpulan Pengguna: + +Discord: + +WeChat: +Kod QR kumpulan WeChat diff --git a/README.pt-br.md b/README.pt-br.md index a3024e264..42ce5cc95 100644 --- a/README.pt-br.md +++ b/README.pt-br.md @@ -18,7 +18,7 @@ Discord

-[中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md) +[中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md) @@ -56,17 +56,19 @@ ## 📢 Novidades +2026-03-25 🚀 **v0.2.4 Lançada!** Reformulação da arquitetura Agent (SubTurn, Hooks, Steering, EventBus), integração WeChat/WeCom, fortalecimento de segurança (.security.yml, filtragem de dados sensíveis), novos providers (AWS Bedrock, Azure, Xiaomi MiMo) e 35 correções de bugs. O PicoClaw atingiu **26K Stars**! + 2026-03-17 🚀 **v0.2.3 Lançada!** UI na bandeja do sistema (Windows e Linux), consulta de status de sub-agent (`spawn_status`), hot-reload experimental do Gateway, controle de segurança do Cron e 2 correções de segurança. O PicoClaw atingiu **25K Stars**! 2026-03-09 🎉 **v0.2.1 — Maior atualização até agora!** Suporte ao protocolo MCP, 4 novos channels (Matrix/IRC/WeCom/Discord Proxy), 3 novos providers (Kimi/Minimax/Avian), pipeline de visão, armazenamento de memória JSONL, roteamento de modelos. 2026-02-28 📦 **v0.2.0** lançada com suporte a Docker Compose e Web UI Launcher. -2026-02-26 🎉 O PicoClaw atinge **20K Stars** em apenas 17 dias! Orquestração automática de channels e interfaces de capacidade estão disponíveis. -
Notícias anteriores... +2026-02-26 🎉 O PicoClaw atinge **20K Stars** em apenas 17 dias! Orquestração automática de channels e interfaces de capacidade estão disponíveis. + 2026-02-16 🎉 O PicoClaw ultrapassa 12K Stars em uma semana! Funções de mantenedor da comunidade e [Roadmap](ROADMAP.md) lançados oficialmente. 2026-02-13 🎉 O PicoClaw ultrapassa 5000 Stars em 4 dias! Roadmap do projeto e grupos de desenvolvedores em andamento. diff --git a/README.vi.md b/README.vi.md index 7274167c3..5ca39d99d 100644 --- a/README.vi.md +++ b/README.vi.md @@ -18,7 +18,7 @@ Discord

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md) +[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md) @@ -56,17 +56,19 @@ ## 📢 Tin tức +2026-03-25 🚀 **v0.2.4 đã phát hành!** Tái cấu trúc kiến trúc Agent (SubTurn, Hooks, Steering, EventBus), tích hợp WeChat/WeCom, tăng cường bảo mật (.security.yml, lọc dữ liệu nhạy cảm), provider mới (AWS Bedrock, Azure, Xiaomi MiMo) và 35 bản vá lỗi. PicoClaw đã đạt **26K Stars**! + 2026-03-17 🚀 **v0.2.3 đã phát hành!** Giao diện system tray (Windows & Linux), truy vấn trạng thái sub-agent (`spawn_status`), thử nghiệm Gateway hot-reload, bảo mật Cron, và 2 bản vá bảo mật. PicoClaw đã đạt **25K Stars**! 2026-03-09 🎉 **v0.2.1 — Bản cập nhật lớn nhất từ trước đến nay!** Hỗ trợ giao thức MCP, 4 Channel mới (Matrix/IRC/WeCom/Discord Proxy), 3 Provider mới (Kimi/Minimax/Avian), pipeline thị giác, bộ nhớ JSONL, định tuyến mô hình. 2026-02-28 📦 **v0.2.0** phát hành với hỗ trợ Docker Compose và Web UI Launcher. -2026-02-26 🎉 PicoClaw đạt **20K Stars** chỉ trong 17 ngày! Tự động điều phối Channel và giao diện khả năng đã hoạt động. -
Tin tức trước đó... +2026-02-26 🎉 PicoClaw đạt **20K Stars** chỉ trong 17 ngày! Tự động điều phối Channel và giao diện khả năng đã hoạt động. + 2026-02-16 🎉 PicoClaw vượt 12K Stars trong một tuần! Vai trò người duy trì cộng đồng và [Lộ trình](ROADMAP.md) chính thức ra mắt. 2026-02-13 🎉 PicoClaw vượt 5000 Stars trong 4 ngày! Lộ trình dự án và nhóm nhà phát triển đang được xây dựng. diff --git a/README.zh.md b/README.zh.md index 021f1e28c..7ca20b1ed 100644 --- a/README.zh.md +++ b/README.zh.md @@ -18,7 +18,7 @@ Discord

-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md) +**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md) @@ -56,17 +56,19 @@ ## 📢 新闻 +2026-03-25 🚀 **v0.2.4 发布！** Agent 架构全面重构（SubTurn、Hook、Steering、EventBus）、微信/企业微信深度集成、安全体系升级（.security.yml、敏感数据过滤）、新增 Provider（AWS Bedrock、Azure、小米 MiMo），以及 35 项 Bug 修复。PicoClaw 已达 **26K ⭐**！ + 2026-03-17 🚀 **v0.2.3 发布！** 系统托盘 UI（Windows & Linux）、子 Agent 状态查询 (`spawn_status`)、实验性 Gateway 热重载、Cron 安全门控，以及 2 项安全修复。PicoClaw 已达 **25K ⭐**！ 2026-03-09 🎉 **v0.2.1 — 史上最大更新！** MCP 协议支持、4 个新频道 (Matrix/IRC/WeCom/Discord Proxy)、3 个新 Provider (Kimi/Minimax/Avian)、视觉管线、JSONL 记忆存储、模型路由。 2026-02-28 📦 **v0.2.0** 发布，支持 Docker Compose 和 Web UI 启动器。 -2026-02-26 🎉 PicoClaw 仅 17 天突破 **20K Stars**！频道自动编排和能力接口上线。 -
更早的新闻... +2026-02-26 🎉 PicoClaw 仅 17 天突破 **20K Stars**！频道自动编排和能力接口上线。 + 2026-02-16 🎉 PicoClaw 一周内突破 12K Stars！社区维护者角色和 [路线图](ROADMAP.md) 正式发布。 2026-02-13 🎉 PicoClaw 4 天内突破 5000 Stars！项目路线图和开发者群组筹建中。 diff --git a/docs/my/chat-apps.md b/docs/my/chat-apps.md new file mode 100644 index 000000000..35a35a7cc --- /dev/null +++ b/docs/my/chat-apps.md @@ -0,0 +1,431 @@ +# 💬 Konfigurasi Aplikasi Sembang + +> Kembali ke [README](../../README.my.md) + +## 💬 Aplikasi Sembang + +Berbual dengan picoclaw anda melalui Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot, MaixCam, atau Pico (protokol asli) + +> **Nota**: Semua saluran berasaskan webhook (LINE, WeCom, dan sebagainya) diservis pada satu pelayan HTTP Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). Tiada port khusus per saluran untuk dikonfigurasikan. Nota: Feishu menggunakan mod WebSocket/SDK dan tidak menggunakan pelayan HTTP webhook yang dikongsi. + +| Saluran | Penyediaan | +| ---------------- | ------------------------------------------ | +| **Telegram** | Mudah (hanya token) | +| **Discord** | Mudah (token bot + intents) | +| **WhatsApp** | Mudah (asli: imbas QR; atau bridge URL) | +| **Matrix** | Sederhana (homeserver + access token bot) | +| **QQ** | Mudah (AppID + AppSecret) | +| **DingTalk** | Sederhana (kelayakan aplikasi) | +| **LINE** | Sederhana (kelayakan + webhook URL) | +| **WeCom AI Bot** | Sederhana (Token + kunci AES) | +| **Feishu** | Sederhana (App ID + Secret, mod WebSocket) | +| **Slack** | Sederhana (Bot token + App token) | +| **IRC** | Sederhana (pelayan + konfigurasi TLS) | +| **OneBot** | Sederhana (QQ melalui protokol OneBot) | +| **MaixCam** | Mudah (integrasi perkakasan Sipeed) | +| **Pico** | Protokol PicoClaw asli | + +
+Telegram (Disyorkan) + +**1. Cipta bot** + +* Buka Telegram, cari `@BotFather` +* Hantar `/newbot`, ikut arahan +* Salin token + +**2. Konfigurasi** + +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allow_from": ["YOUR_USER_ID"], + "use_markdown_v2": false, + } + } +} +``` + +> Dapatkan user ID anda daripada `@userinfobot` di Telegram. + +**3. Jalankan** + +```bash +picoclaw gateway +``` + +**4. Menu arahan Telegram (auto-register semasa startup)** + +PicoClaw kini menyimpan definisi arahan dalam satu registry bersama. Semasa startup, Telegram akan mendaftarkan arahan bot yang disokong secara automatik (contohnya `/start`, `/help`, `/show`, `/list`) supaya menu arahan dan tingkah laku runtime sentiasa selari. +Pendaftaran menu arahan Telegram kekal sebagai UX penemuan setempat saluran; pelaksanaan arahan generik dikendalikan secara berpusat dalam gelung agen melalui commands executor. + +Jika pendaftaran arahan gagal (ralat sementara rangkaian/API), saluran tetap akan bermula dan PicoClaw akan mencuba semula pendaftaran di latar belakang. + +**4. Pemformatan Lanjutan** +Anda boleh menetapkan `use_markdown_v2: true` untuk mengaktifkan pilihan pemformatan yang lebih maju. Ini membolehkan bot menggunakan keseluruhan set ciri Telegram MarkdownV2, termasuk gaya bersarang, spoiler, dan blok lebar tetap tersuai. + +
+ +
+Discord + +**1. Cipta bot** + +* Pergi ke +* Cipta aplikasi → Bot → Add Bot +* Salin token bot + +**2. Aktifkan intents** + +* Dalam tetapan Bot, aktifkan **MESSAGE CONTENT INTENT** +* (Pilihan) Aktifkan **SERVER MEMBERS INTENT** jika anda bercadang menggunakan allow list berasaskan data ahli + +**3. Dapatkan User ID anda** +* Discord Settings → Advanced → aktifkan **Developer Mode** +* Klik kanan avatar anda → **Copy User ID** + +**4. Konfigurasi** + +```json +{ + "channels": { + "discord": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` + +**5. Jemput bot** + +* OAuth2 → URL Generator +* Scopes: `bot` +* Bot Permissions: `Send Messages`, `Read Message History` +* Buka URL jemputan yang dijana dan tambahkan bot ke pelayan anda + +**Pilihan: Mod trigger kumpulan** + +Secara lalai bot membalas semua mesej dalam saluran pelayan. Untuk mengehadkan balasan kepada @mention sahaja, tambah: + +```json +{ + "channels": { + "discord": { + "group_trigger": { "mention_only": true } + } + } +} +``` + +Anda juga boleh mencetuskan dengan awalan kata kunci (contohnya `!bot`): + +```json +{ + "channels": { + "discord": { + "group_trigger": { "prefixes": ["!bot"] } + } + } +} +``` + +**6. Jalankan** + +```bash +picoclaw gateway +``` + +
+ +
+WhatsApp (asli melalui whatsmeow) + +PicoClaw boleh menyambung ke WhatsApp dalam dua cara: + +- **Asli (disyorkan):** Dalam proses menggunakan [whatsmeow](https://github.com/tulir/whatsmeow). Tiada bridge berasingan. Tetapkan `"use_native": true` dan biarkan `bridge_url` kosong. Pada larian pertama, imbas kod QR dengan WhatsApp (Linked Devices). Sesi disimpan di bawah workspace anda (contohnya `workspace/whatsapp/`). Saluran asli ini adalah **pilihan** untuk memastikan binari lalai kekal kecil; bina dengan `-tags whatsapp_native` (contohnya `make build-whatsapp-native` atau `go build -tags whatsapp_native ./cmd/...`). +- **Bridge:** Sambung ke bridge WebSocket luaran. Tetapkan `bridge_url` (contohnya `ws://localhost:3001`) dan biarkan `use_native` sebagai false. + +**Konfigurasi (asli)** + +```json +{ + "channels": { + "whatsapp": { + "enabled": true, + "use_native": true, + "session_store_path": "", + "allow_from": [] + } + } +} +``` + +Jika `session_store_path` kosong, sesi akan disimpan dalam `/whatsapp/`. Jalankan `picoclaw gateway`; pada larian pertama, imbas kod QR yang dipaparkan dalam terminal menggunakan WhatsApp → Linked Devices. + +
+ +
+QQ + +**1. Cipta bot** + +- Pergi ke [QQ Open Platform](https://q.qq.com/#) +- Cipta aplikasi → Dapatkan **AppID** dan **AppSecret** + +**2. Konfigurasi** + +```json +{ + "channels": { + "qq": { + "enabled": true, + "app_id": "YOUR_APP_ID", + "app_secret": "YOUR_APP_SECRET", + "allow_from": [] + } + } +} +``` + +> Tetapkan `allow_from` kepada kosong untuk membenarkan semua pengguna, atau nyatakan nombor QQ untuk mengehadkan akses. + +**3. Jalankan** + +```bash +picoclaw gateway +``` + +
+ +
+DingTalk + +**1. Cipta bot** + +* Pergi ke [Open Platform](https://open.dingtalk.com/) +* Cipta aplikasi dalaman +* Salin Client ID dan Client Secret + +**2. Konfigurasi** + +```json +{ + "channels": { + "dingtalk": { + "enabled": true, + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET", + "allow_from": [] + } + } +} +``` + +> Tetapkan `allow_from` kepada kosong untuk membenarkan semua pengguna, atau nyatakan user ID DingTalk untuk mengehadkan akses. + +**3. Jalankan** + +```bash +picoclaw gateway +``` +
+ +
+Matrix + +**1. Sediakan akaun bot** + +* Gunakan homeserver pilihan anda (contohnya `https://matrix.org` atau self-hosted) +* Cipta pengguna bot dan dapatkan access tokennya + +**2. Konfigurasi** + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "homeserver": "https://matrix.org", + "user_id": "@your-bot:matrix.org", + "access_token": "YOUR_MATRIX_ACCESS_TOKEN", + "allow_from": [] + } + } +} +``` + +**3. Jalankan** + +```bash +picoclaw gateway +``` + +Untuk pilihan penuh (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), lihat [Panduan Konfigurasi Saluran Matrix](docs/channels/matrix/README.md). + +
+ +
+LINE + +**1. Cipta Akaun Rasmi LINE** + +- Pergi ke [LINE Developers Console](https://developers.line.biz/) +- Cipta provider → Cipta saluran Messaging API +- Salin **Channel Secret** dan **Channel Access Token** + +**2. Konfigurasi** + +```json +{ + "channels": { + "line": { + "enabled": true, + "channel_secret": "YOUR_CHANNEL_SECRET", + "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", + "webhook_path": "/webhook/line", + "allow_from": [] + } + } +} +``` + +> Webhook LINE diservis pada pelayan Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). + +**3. Tetapkan Webhook URL** + +LINE memerlukan HTTPS untuk webhook. Gunakan reverse proxy atau tunnel: + +```bash +# Contoh dengan ngrok (port lalai gateway ialah 18790) +ngrok http 18790 +``` + +Kemudian tetapkan Webhook URL dalam LINE Developers Console kepada `https://your-domain/webhook/line` dan aktifkan **Use webhook**. + +**4. Jalankan** + +```bash +picoclaw gateway +``` + +> Dalam sembang kumpulan, bot hanya membalas apabila @disebut. Balasan akan memetik mesej asal. + +
+ +
+WeCom (企业微信) + +PicoClaw menyokong tiga jenis integrasi WeCom: + +**Pilihan 1: WeCom Bot (Bot)** - Penyediaan lebih mudah, menyokong sembang kumpulan +**Pilihan 2: WeCom App (Custom App)** - Lebih banyak ciri, pemesejan proaktif, sembang peribadi sahaja +**Pilihan 3: WeCom AI Bot (AI Bot)** - AI Bot rasmi, balasan streaming, menyokong sembang kumpulan & peribadi + +Lihat [Panduan Konfigurasi WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) untuk arahan penyediaan terperinci. + +**Quick Setup - WeCom Bot:** + +**1. Cipta bot** + +* Pergi ke WeCom Admin Console → Group Chat → Add Group Bot +* Salin webhook URL (format: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`) + +**2. Konfigurasi** + +```json +{ + "channels": { + "wecom": { + "enabled": true, + "token": "YOUR_TOKEN", + "encoding_aes_key": "YOUR_ENCODING_AES_KEY", + "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY", + "webhook_path": "/webhook/wecom", + "allow_from": [] + } + } +} +``` + +> Webhook WeCom diservis pada pelayan Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). + +**Quick Setup - WeCom App:** + +**1. Cipta aplikasi** + +* Pergi ke WeCom Admin Console → App Management → Create App +* Salin **AgentId** dan **Secret** +* Pergi ke halaman "My Company", salin **CorpID** + +**2. Konfigurasi penerimaan mesej** + +* Dalam butiran aplikasi, klik "Receive Message" → "Set API" +* Tetapkan URL kepada `http://your-server:18790/webhook/wecom-app` +* Jana **Token** dan **EncodingAESKey** + +**3. Konfigurasi** + +```json +{ + "channels": { + "wecom_app": { + "enabled": true, + "corp_id": "wwxxxxxxxxxxxxxxxx", + "corp_secret": "YOUR_CORP_SECRET", + "agent_id": 1000002, + "token": "YOUR_TOKEN", + "encoding_aes_key": "YOUR_ENCODING_AES_KEY", + "webhook_path": "/webhook/wecom-app", + "allow_from": [] + } + } +} +``` + +**4. Jalankan** + +```bash +picoclaw gateway +``` + +> **Nota**: Callback webhook WeCom diservis pada port Gateway (lalai 18790). Gunakan reverse proxy untuk HTTPS. + +**Quick Setup - WeCom AI Bot:** + +**1. Cipta AI Bot** + +* Pergi ke WeCom Admin Console → App Management → AI Bot +* Dalam tetapan AI Bot, konfigurasikan callback URL: `http://your-server:18791/webhook/wecom-aibot` +* Salin **Token** dan klik "Random Generate" untuk **EncodingAESKey** + +**2. Konfigurasi** + +```json +{ + "channels": { + "wecom_aibot": { + "enabled": true, + "token": "YOUR_TOKEN", + "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY", + "webhook_path": "/webhook/wecom-aibot", + "allow_from": [], + "welcome_message": "Hello! How can I help you?" + } + } +} +``` + +**3. Jalankan** + +```bash +picoclaw gateway +``` + +> **Nota**: WeCom AI Bot menggunakan protokol streaming pull — tiada isu timeout balasan. Tugasan panjang (>30 saat) akan bertukar secara automatik kepada penghantaran push `response_url`. + +
diff --git a/docs/my/configuration.md b/docs/my/configuration.md new file mode 100644 index 000000000..f798bd9bd --- /dev/null +++ b/docs/my/configuration.md @@ -0,0 +1,216 @@ +# ⚙️ Panduan Konfigurasi + +> Kembali ke [README](../../README.my.md) + +## ⚙️ Konfigurasi + +Fail konfigurasi: `~/.picoclaw/config.json` + +### Pemboleh Ubah Persekitaran + +Anda boleh menggantikan laluan lalai menggunakan pemboleh ubah persekitaran. Ini berguna untuk pemasangan mudah alih, deployment dalam container, atau menjalankan picoclaw sebagai system service. Pemboleh ubah ini saling bebas dan mengawal laluan yang berbeza. + +| Pemboleh Ubah | Penerangan | Laluan Lalai | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | +| `PICOCLAW_CONFIG` | Menindih laluan ke fail konfigurasi. Ini memberitahu picoclaw secara terus fail `config.json` yang perlu dimuatkan, dengan mengabaikan lokasi lain. | `~/.picoclaw/config.json` | +| `PICOCLAW_HOME` | Menindih direktori root untuk data picoclaw. Ini mengubah lokasi lalai bagi `workspace` dan direktori data lain. | `~/.picoclaw` | + +**Contoh:** + +```bash +# Jalankan picoclaw menggunakan fail config tertentu +# Laluan workspace akan dibaca daripada fail config tersebut +PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway + +# Jalankan picoclaw dengan semua data disimpan di /opt/picoclaw +# Config akan dimuatkan dari lalai ~/.picoclaw/config.json +# Workspace akan dicipta di /opt/picoclaw/workspace +PICOCLAW_HOME=/opt/picoclaw picoclaw agent + +# Gunakan kedua-duanya untuk setup yang disesuaikan sepenuhnya +PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway +``` + +### Susun Atur Workspace + +PicoClaw menyimpan data dalam workspace yang dikonfigurasikan (lalai: `~/.picoclaw/workspace`): + +``` +~/.picoclaw/workspace/ +├── sessions/ # Sesi perbualan dan sejarah +├── memory/ # Memori jangka panjang (MEMORY.md) +├── state/ # Keadaan persisten (saluran terakhir, dll.) +├── cron/ # Pangkalan data job berjadual +├── skills/ # Skill tersuai +├── AGENTS.md # Panduan tingkah laku agen +├── HEARTBEAT.md # Prompt tugasan berkala (disemak setiap 30 minit) +├── IDENTITY.md # Identiti agen +├── SOUL.md # Jiwa agen +└── USER.md # Keutamaan pengguna +``` + +### Sumber Skill + +Secara lalai, skill dimuatkan daripada: + +1. `~/.picoclaw/workspace/skills` (workspace) +2. `~/.picoclaw/skills` (global) +3. `/skills` (builtin) + +Untuk setup lanjutan/ujian, anda boleh menindih root builtin skills dengan: + +```bash +export PICOCLAW_BUILTIN_SKILLS=/path/to/skills +``` + +### Polisi Pelaksanaan Arahan Bersepadu + +- Generic slash command dilaksanakan melalui satu laluan dalam `pkg/agent/loop.go` melalui `commands.Executor`. +- Adapter saluran tidak lagi menggunakan generic command secara setempat; ia memajukan teks masuk ke laluan bus/agent. Telegram masih auto-register arahan yang disokong semasa startup. +- Slash command yang tidak dikenali (contohnya `/foo`) akan diteruskan ke pemprosesan LLM biasa. +- Arahan yang didaftarkan tetapi tidak disokong pada saluran semasa (contohnya `/show` di WhatsApp) akan memulangkan ralat yang jelas kepada pengguna dan menghentikan pemprosesan lanjut. + +### 🔒 Security Sandbox + +PicoClaw berjalan dalam persekitaran bersandbox secara lalai. Agen hanya boleh mengakses fail dan melaksanakan arahan dalam workspace yang dikonfigurasikan. + +#### Konfigurasi Lalai + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "restrict_to_workspace": true + } + } +} +``` + +| Option | Default | Description | +| ----------------------- | ----------------------- | ----------------------------------------- | +| `workspace` | `~/.picoclaw/workspace` | Direktori kerja untuk agen | +| `restrict_to_workspace` | `true` | Hadkan akses fail/arahan kepada workspace | + +#### Tools yang Dilindungi + +Apabila `restrict_to_workspace: true`, tools berikut disandboxkan: + +| Tool | Fungsi | Sekatan | +| ------------- | ----------------- | ----------------------------------- | +| `read_file` | Baca fail | Hanya fail dalam workspace | +| `write_file` | Tulis fail | Hanya fail dalam workspace | +| `list_dir` | Senarai direktori | Hanya direktori dalam workspace | +| `edit_file` | Edit fail | Hanya fail dalam workspace | +| `append_file` | Tambah ke fail | Hanya fail dalam workspace | +| `exec` | Jalankan arahan | Laluan arahan mesti dalam workspace | + +#### Perlindungan Exec Tambahan + +Walaupun dengan `restrict_to_workspace: false`, tool `exec` menyekat arahan berbahaya berikut: + +* `rm -rf`, `del /f`, `rmdir /s` — Pemadaman pukal +* `format`, `mkfs`, `diskpart` — Pemformatan cakera +* `dd if=` — Pengimejan cakera +* Menulis ke `/dev/sd[a-z]` — Tulis terus ke cakera +* `shutdown`, `reboot`, `poweroff` — Penutupan sistem +* Fork bomb `:(){ :|:& };:` + +### Kawalan Akses Fail + +| Kunci Config | Jenis | Lalai | Penerangan | +| ------------------------- | -------- | ----- | --------------------------------------------------------------- | +| `tools.allow_read_paths` | string[] | `[]` | Laluan tambahan yang dibenarkan untuk dibaca di luar workspace | +| `tools.allow_write_paths` | string[] | `[]` | Laluan tambahan yang dibenarkan untuk ditulis di luar workspace | + +### Keselamatan Exec + +| Kunci Config | Jenis | Lalai | Penerangan | +| ---------------------------------- | -------- | ------- | ------------------------------------------------------------ | +| `tools.exec.allow_remote` | bool | `false` | Benarkan tool exec dari saluran jauh (Telegram/Discord dll.) | +| `tools.exec.enable_deny_patterns` | bool | `true` | Aktifkan pemintasan arahan berbahaya | +| `tools.exec.custom_deny_patterns` | string[] | `[]` | Corak regex tersuai untuk disekat | +| `tools.exec.custom_allow_patterns` | string[] | `[]` | Corak regex tersuai untuk dibenarkan | + +> **Nota Keselamatan:** Perlindungan symlink diaktifkan secara lalai — semua laluan fail akan diselesaikan melalui `filepath.EvalSymlinks` sebelum dipadankan dengan whitelist, bagi mengelakkan serangan melarikan diri melalui symlink. + +#### Had yang Diketahui: Proses Anak Daripada Build Tools + +Pengawal keselamatan exec hanya memeriksa baris arahan yang PicoClaw lancarkan secara terus. Ia tidak memeriksa secara rekursif proses anak yang dilancarkan oleh tools pembangun yang dibenarkan seperti `make`, `go run`, `cargo`, `npm run`, atau skrip build tersuai. + +Ini bermakna arahan peringkat atas masih boleh mengkompil atau melancarkan binari lain selepas ia melepasi semakan awal pengawal. Dalam amalan, anggap build script, Makefile, package script, dan binari terjana sebagai kod boleh laksana yang memerlukan tahap semakan yang sama seperti arahan shell terus. + +Untuk persekitaran yang lebih berisiko: + +* Semak build script sebelum pelaksanaan. +* Utamakan kelulusan/semakan manual untuk aliran kerja compile-and-run. +* Jalankan PicoClaw dalam container atau VM jika anda memerlukan pengasingan yang lebih kuat daripada pengawal terbina dalam. + +#### Contoh Ralat + +``` +[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)} +``` + +#### Menyahaktifkan Sekatan (Risiko Keselamatan) + +Jika anda perlu membenarkan agen mengakses laluan di luar workspace: + +**Kaedah 1: Fail config** + +```json +{ + "agents": { + "defaults": { + "restrict_to_workspace": false + } + } +} +``` + +**Kaedah 2: Pemboleh ubah persekitaran** + +```bash +export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false +``` + +> ⚠️ **Amaran**: Menyahaktifkan sekatan ini membenarkan agen mengakses mana-mana laluan pada sistem anda. Gunakan dengan berhati-hati hanya dalam persekitaran terkawal. + +#### Ketekalan Sempadan Keselamatan + +Tetapan `restrict_to_workspace` digunakan secara konsisten merentas semua laluan pelaksanaan: + +| Execution Path | Security Boundary | +| ---------------- | --------------------------- | +| Main Agent | `restrict_to_workspace` ✅ | +| Subagent / Spawn | Inherits same restriction ✅ | +| Heartbeat tasks | Inherits same restriction ✅ | + +Semua laluan berkongsi sekatan workspace yang sama — tiada cara untuk memintas sempadan keselamatan melalui subagent atau tugasan berjadual. + +### Heartbeat (Tugasan Berkala) + +PicoClaw boleh melaksanakan tugasan berkala secara automatik. Cipta fail `HEARTBEAT.md` dalam workspace anda: + +```markdown +# Periodic Tasks + +- Check my email for important messages +- Review my calendar for upcoming events +- Check the weather forecast +``` + +Agen akan membaca fail ini setiap 30 minit (boleh dikonfigurasi) dan melaksanakan sebarang tugasan menggunakan tools yang tersedia. + +#### Tugasan Async dengan Spawn + +Untuk tugasan yang berjalan lama (carian web, panggilan API), gunakan tool `spawn` untuk mencipta **subagent**: + +```markdown +# Periodic Tasks diff --git a/docs/my/debug.md b/docs/my/debug.md new file mode 100644 index 000000000..6ab28365e --- /dev/null +++ b/docs/my/debug.md @@ -0,0 +1,33 @@ +# Penyahpepijatan PicoClaw + +PicoClaw melakukan pelbagai interaksi kompleks di sebalik tabir untuk setiap permintaan yang diterimanya, daripada menghala mesej dan menilai kerumitan, hinggalah melaksanakan tools dan menyesuaikan diri dengan kegagalan model. Keupayaan melihat dengan tepat apa yang sedang berlaku sangat penting, bukan sahaja untuk menyelesaikan masalah, malah untuk benar-benar memahami cara agen ini beroperasi. +## Memulakan PicoClaw dalam Mod Debug + +Untuk mendapatkan maklumat terperinci tentang apa yang sedang dilakukan oleh agen (permintaan LLM, panggilan tool, penghalaan mesej), anda boleh memulakan gateway PicoClaw dengan flag debug: + +```bash +picoclaw gateway --debug +# or +picoclaw gateway -d +``` + +Dalam mod ini, sistem akan memformat log dengan lebih terperinci dan memaparkan pratonton system prompt serta hasil pelaksanaan tool. + +## Menyahaktifkan Pemotongan Log (Log Penuh) + +Secara lalai, PicoClaw memotong rentetan yang sangat panjang (seperti *System Prompt* atau hasil output JSON yang besar) dalam log debug supaya konsol kekal mudah dibaca. + +Jika anda perlu memeriksa output penuh sesuatu arahan atau payload tepat yang dihantar kepada model LLM, anda boleh menggunakan flag `--no-truncate`. + +**Nota:** Flag ini *hanya* berfungsi apabila digabungkan dengan mod `--debug`. + +```bash +picoclaw gateway --debug --no-truncate + +``` + +Apabila flag ini aktif, fungsi pemotongan global dinyahaktifkan. Ini sangat berguna untuk: + +* Mengesahkan sintaks tepat mesej yang dihantar kepada penyedia. +* Membaca output lengkap daripada tools seperti `exec`, `web_fetch`, atau `read_file`. +* Menyahpepijat sejarah sesi yang disimpan dalam memori. diff --git a/docs/my/docker.md b/docs/my/docker.md new file mode 100644 index 000000000..8fe1aed8c --- /dev/null +++ b/docs/my/docker.md @@ -0,0 +1,166 @@ +# 🐳 Panduan Docker & Quick Start + +> Kembali ke [README](../../README.my.md) + +## 🐳 Docker Compose + +Anda juga boleh menjalankan PicoClaw menggunakan Docker Compose tanpa memasang apa-apa secara setempat. + +```bash +# 1. Clone repo ini +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. Larian pertama — jana docker/data/config.json secara automatik kemudian keluar +docker compose -f docker/docker-compose.yml --profile gateway up +# Container akan memaparkan "First-run setup complete." dan berhenti. + +# 3. Tetapkan kunci API anda +vim docker/data/config.json # Tetapkan API key penyedia, token bot, dan sebagainya. + +# 4. Mula +docker compose -f docker/docker-compose.yml --profile gateway up -d +``` + +> [!TIP] +> **Pengguna Docker**: Secara lalai, Gateway mendengar pada `127.0.0.1` yang tidak boleh diakses dari host. Jika anda perlu mengakses health endpoint atau mendedahkan port, tetapkan `PICOCLAW_GATEWAY_HOST=0.0.0.0` dalam persekitaran anda atau kemas kini `config.json`. + +```bash +# 5. Semak log +docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway + +# 6. Hentikan +docker compose -f docker/docker-compose.yml --profile gateway down +``` + +### Mod Launcher (Konsol Web) + +Imej `launcher` merangkumi ketiga-tiga binari (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) dan memulakan konsol web secara lalai, yang menyediakan UI berasaskan pelayar untuk konfigurasi dan sembang. + +```bash +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +Buka http://localhost:18800 dalam pelayar anda. Launcher mengurus proses gateway secara automatik. + +> [!WARNING] +> Konsol web belum menyokong autentikasi. Elakkan mendedahkannya ke internet awam. + +### Mod Agent (One-shot) + +```bash +# Tanyakan soalan +docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?" + +# Mod interaktif +docker compose -f docker/docker-compose.yml run --rm picoclaw-agent +``` + +### Kemas kini + +```bash +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile gateway up -d +``` + +### 🚀 Quick Start + +> [!TIP] +> Tetapkan API Key anda dalam `~/.picoclaw/config.json`. Dapatkan API Key: [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Carian web adalah pilihan — dapatkan [Tavily API](https://tavily.com) percuma (1000 pertanyaan percuma/bulan) atau [Brave Search API](https://brave.com/search/api) (2000 pertanyaan percuma/bulan). + +**1. Inisialisasi** + +```bash +picoclaw onboard +``` + +**2. Konfigurasi** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "model_name": "gpt-5.4", + "max_tokens": 8192, + "temperature": 0.7, + "max_tool_iterations": 20 + } + }, + "model_list": [ + { + "model_name": "ark-code-latest", + "model": "volcengine/ark-code-latest", + "api_key": "sk-your-api-key", + "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3" + }, + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "your-api-key", + "request_timeout": 300 + }, + { + "model_name": "claude-sonnet-4.6", + "model": "anthropic/claude-sonnet-4.6", + "api_key": "your-anthropic-key" + } + ], + "tools": { + "web": { + "enabled": true, + "fetch_limit_bytes": 10485760, + "format": "plaintext", + "brave": { + "enabled": false, + "api_key": "YOUR_BRAVE_API_KEY", + "max_results": 5 + }, + "tavily": { + "enabled": false, + "api_key": "YOUR_TAVILY_API_KEY", + "max_results": 5 + }, + "duckduckgo": { + "enabled": true, + "max_results": 5 + }, + "perplexity": { + "enabled": false, + "api_key": "YOUR_PERPLEXITY_API_KEY", + "max_results": 5 + }, + "searxng": { + "enabled": false, + "base_url": "http://your-searxng-instance:8888", + "max_results": 5 + } + } + } +} +``` + +> **Baharu**: Format konfigurasi `model_list` membolehkan penambahan penyedia tanpa perubahan kod. Lihat [Konfigurasi Model](#konfigurasi-model-model_list) untuk butiran. +> `request_timeout` adalah pilihan dan menggunakan saat. Jika diabaikan atau ditetapkan kepada `<= 0`, PicoClaw menggunakan timeout lalai (120s). + +**3. Dapatkan API Key** + +* **Penyedia 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) +* **Carian Web** (pilihan): + * [Brave Search](https://brave.com/search/api) - Berbayar ($5/1000 pertanyaan, ~$5-6/bulan) + * [Perplexity](https://www.perplexity.ai) - Carian berkuasa AI dengan antara muka sembang + * [SearXNG](https://github.com/searxng/searxng) - Enjin meta-carian hos kendiri (percuma, tidak perlu API key) + * [Tavily](https://tavily.com) - Dioptimumkan untuk AI Agents (1000 permintaan/bulan) + * DuckDuckGo - Fallback terbina dalam (tidak memerlukan API key) + +> **Nota**: Lihat `config.example.json` untuk templat konfigurasi penuh. + +**4. Sembang** + +```bash +picoclaw agent -m "What is 2+2?" +``` + +Itu sahaja! Anda kini mempunyai pembantu AI yang berfungsi dalam masa 2 minit. + +--- diff --git a/docs/my/spawn-tasks.md b/docs/my/spawn-tasks.md new file mode 100644 index 000000000..c0c3e8f92 --- /dev/null +++ b/docs/my/spawn-tasks.md @@ -0,0 +1,61 @@ +# 🔄 Spawn & Tugasan Async + +> Kembali ke [README](../../README.my.md) + +## Tugasan Cepat (balas terus) + +- Laporkan masa semasa + +## Tugasan Panjang (guna spawn untuk async) + +- Cari berita AI di web dan ringkaskan +- Semak e-mel dan laporkan mesej penting +``` + +**Tingkah laku utama:** + +| Feature | Description | +| ----------------------- | --------------------------------------------------------- | +| **spawn** | Mencipta sub-agen async, tidak menyekat heartbeat | +| **Independent context** | Sub-agen mempunyai konteks sendiri, tiada sejarah sesi | +| **message tool** | Sub-agen berkomunikasi terus dengan pengguna melalui message tool | +| **Non-blocking** | Selepas spawn, heartbeat terus ke tugasan seterusnya | + +#### Cara Komunikasi Sub-agen Berfungsi + +``` +Heartbeat dicetuskan + ↓ +Agen membaca HEARTBEAT.md + ↓ +Untuk tugasan panjang: spawn sub-agen + ↓ ↓ +Terus ke tugasan seterusnya Sub-agen bekerja secara bebas + ↓ ↓ +Semua tugasan selesai Sub-agen menggunakan tool "message" + ↓ ↓ +Balas HEARTBEAT_OK Pengguna menerima hasil secara terus +``` + +Sub-agen mempunyai akses kepada tools (message, web_search, dan sebagainya) dan boleh berkomunikasi dengan pengguna secara bebas tanpa melalui agen utama. + +**Konfigurasi:** + +```json +{ + "heartbeat": { + "enabled": true, + "interval": 30 + } +} +``` + +| Option | Default | Description | +| ---------- | ------- | ---------------------------------------- | +| `enabled` | `true` | Hidupkan/matikan heartbeat | +| `interval` | `30` | Selang semakan dalam minit (minimum: 5) | + +**Pemboleh ubah persekitaran:** + +* `PICOCLAW_HEARTBEAT_ENABLED=false` untuk nyahaktifkan +* `PICOCLAW_HEARTBEAT_INTERVAL=60` untuk menukar selang diff --git a/docs/my/troubleshooting.md b/docs/my/troubleshooting.md new file mode 100644 index 000000000..c9d987ab4 --- /dev/null +++ b/docs/my/troubleshooting.md @@ -0,0 +1,43 @@ +# Penyelesaian Masalah + +## "model ... not found in model_list" atau OpenRouter "free is not a valid model ID" + +**Gejala:** Anda akan melihat salah satu daripada mesej berikut: + +- `Error creating provider: model "openrouter/free" not found in model_list` +- OpenRouter memulangkan 400: `"free is not a valid model ID"` + +**Punca:** Medan `model` dalam entri `model_list` anda ialah nilai yang dihantar ke API. Untuk OpenRouter, anda mesti menggunakan ID model **penuh**, bukan bentuk singkatan. + +- **Salah:** `"model": "free"` → OpenRouter menerima `free` dan menolaknya. +- **Betul:** `"model": "openrouter/free"` → OpenRouter menerima `openrouter/free` (routing auto free-tier). + +**Penyelesaian:** Dalam `~/.picoclaw/config.json` (atau laluan config anda): + +1. **agents.defaults.model** mesti sepadan dengan `model_name` dalam `model_list` (contohnya `"openrouter-free"`). +2. Medan **model** bagi entri tersebut mesti merupakan ID model OpenRouter yang sah, contohnya: + - `"openrouter/free"` – auto free-tier + - `"google/gemini-2.0-flash-exp:free"` + - `"meta-llama/llama-3.1-8b-instruct:free"` + +Example snippet: + +```json +{ + "agents": { + "defaults": { + "model": "openrouter-free" + } + }, + "model_list": [ + { + "model_name": "openrouter-free", + "model": "openrouter/free", + "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY", + "api_base": "https://openrouter.ai/api/v1" + } + ] +} +``` + +Dapatkan kunci anda di [OpenRouter Keys](https://openrouter.ai/keys).