@@ -144,20 +238,128 @@ CraftBotはすべてのLiving UIに組み込まれており、**状態を常に
- **📊 習慣トラッカー** — 習慣を作り、追跡する。開発者がコミットを刻むように、GitHub風のアクティビティカレンダーで習慣を可視化。
- **🐦 Luolinglo** — Duolingoではないですが、新しい言語を学び、フラッシュカードを作り、CraftBotと一緒に練習できます。
-**[Living UIマーケットプレイスを見る・貢献する →](https://craftos.net/marketplace)**
+## 🧩 アーキテクチャの概要
+
+| コンポーネント | 説明 |
+|-----------|-------------|
+| **エージェントベース** | タスクライフサイクルを管理し、コンポーネント間を調整し、メインのエージェントループを処理するコアオーケストレーションレイヤー。 |
+| **LLMインターフェース** | 複数のLLMプロバイダー（OpenAI、Gemini、Anthropic、BytePlus、Ollama）をサポートする統一インターフェース。 |
+| **コンテキストエンジン** | KVキャッシュサポートで最適化されたプロンプトを生成。 |
+| **アクションマネージャー** | ライブラリからアクションを取得して実行。カスタムアクションの拡張が容易。 |
+| **アクションルーター** | タスク要件に基づいて最適なアクションをインテリジェントに選択し、必要に応じてLLMを介して入力パラメータを解決。 |
+| **イベントストリーム** | タスク進行状況の追跡、UI更新、実行モニタリング用のリアルタイムイベント発行システム。 |
+| **メモリマネージャー** | ChromaDBを使用したRAGベースのセマンティックメモリ。メモリのチャンキング、埋め込み、検索、増分更新を処理。 |
+| **ステートマネージャー** | エージェント実行コンテキスト、会話履歴、ランタイム設定を追跡するグローバルステート管理。 |
+| **タスクマネージャー** | タスク定義を管理し、シンプルタスクと複雑タスクモードの切り替え、TODO作成、マルチステップワークフロー追跡を可能にします。 |
+| **スキルマネージャー** | エージェントコンテキストにプラグイン可能なスキルをロードして注入。 |
+| **MCPアダプター** | MCPツールをネイティブアクションに変換するModel Context Protocol統合。 |
---
-
-# CraftBot と他の選択肢を比較
-
-| | v0 / Lovable / Bolt | OpenClaw | Claude Code | **CraftBot** |
-| -------------------------------- | ------------------- | -------------------- | -------------------- | --------------------------------------- |
-| **カスタムアプリを構築** | ✅ 一発生成 | 🚫 | ✅ (手動) | ✅ 会話ベース |
-| **エージェントがそのアプリを操作** | 🚫 | ⚠️ ツール呼び出し | 🚫 | ✅ すべてのLiving UIに組み込み |
-| **永続的なエージェントメモリ** | 🚫 | ✅ | ✅ | ✅ RAG + エージェントファイルシステム + 蒸留 |
-| **セルフホスト** | ⚠️ 一部対応 | ✅ | 🚫 SaaS | ✅ MIT、あなたのマシンで |
-| **モデル非依存** | ✅ | ✅ | ⚠️ 一部対応 | ✅ 主要プロバイダー + OpenRouter |
-
+
+## 🔜 ロードマップ
+
+- [X] **メモリモジュール** — 完了。
+- [ ] **外部ツール統合** — さらに追加中！
+- [X] **MCPレイヤー** — 完了。
+- [X] **スキルレイヤー** — 完了。
+- [ ] **プロアクティブな動作** — 実装予定
+
+---
+
+## 📋 コマンドリファレンス
+
+### install.py
+
+| フラグ | 説明 |
+|------|-------------|
+| `--conda` | conda環境を使用（オプション） |
+
+### run.py
+
+| フラグ | 説明 |
+|------|-------------|
+| (なし) | **ブラウザ**モードで実行（推奨、Node.jsが必要） |
+| `--cli` | **CLI**モードで実行（軽量） |
+
+**インストール例:**
+```bash
+# シンプルなpipインストール（condaなし）
+python install.py
+
+# conda環境を使用（condaユーザー向け推奨）
+python install.py --conda
+```
+
+**CraftBotの実行:**
+
+```powershell
+# ブラウザモード（デフォルト、Node.jsが必要）
+python run.py
+
+# CLIモード（軽量）
+python run.py --cli
+
+# conda環境で
+conda run -n craftbot python run.py
+
+# condaがPATHにない場合はフルパスを使用
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+**Linux/macOS (Bash):**
+```bash
+# ブラウザモード（デフォルト、Node.jsが必要）
+python run.py
+
+# CLIモード（軽量）
+python run.py --cli
+
+# conda環境で
+conda run -n craftbot python run.py
+```
+
+### 🔧 バックグラウンドサービス（推奨）
+
+ターミナルを閉じても CraftBot が動き続けるようにバックグラウンドサービスとして実行します。デスクトップショートカットが自動作成されるので、いつでもブラウザを再度開けます。
+
+```bash
+# 依存関係インストール、ログイン時自動起動の登録、CraftBot の起動
+python craftbot.py install
+```
+
+以上です。ターミナルは自動で閉じ、CraftBot はバックグラウンドで動作し、ブラウザが自動で開きます。
+
+```bash
+# その他のサービスコマンド:
+python craftbot.py start # CraftBot をバックグラウンドで起動
+python craftbot.py status # 実行中かどうか確認
+python craftbot.py stop # CraftBot を停止
+python craftbot.py restart # CraftBot を再起動
+python craftbot.py logs # 最近のログ出力を確認
+```
+
+| コマンド | 説明 |
+|---------|-------------|
+| `python craftbot.py install` | 依存関係インストール、ログイン時自動起動の登録、CraftBot 起動、ブラウザを開き、ターミナルを自動で閉じる |
+| `python craftbot.py start` | CraftBot をバックグラウンドで起動（すでに実行中の場合は自動再起動、ターミナルは自動で閉じる） |
+| `python craftbot.py stop` | CraftBot を停止 |
+| `python craftbot.py restart` | CraftBot を停止して再起動 |
+| `python craftbot.py status` | CraftBot が実行中か、自動起動が有効かを確認 |
+| `python craftbot.py logs` | 最近のログ出力を表示（`-n 100` でより多く表示） |
+| `python craftbot.py uninstall` | CraftBot を停止、自動起動の登録解除、pip パッケージのアンインストール、pip キャッシュの削除 |
+
+> [!TIP]
+> `craftbot.py start` または `craftbot.py install` の後、**CraftBot デスクトップショートカット**が自動作成されます。ブラウザを誤って閉じた場合は、ショートカットをダブルクリックして再度開けます。
+
+> [!NOTE]
+> **インストール:** インストーラーは依存関係が不足している場合、明確なガイダンスを提供します。Node.jsが見つからない場合は、インストールを促すか、CLIモードに切り替えることができます。インストールはGPUの可用性を自動検出し、必要に応じてCPU専用モードにフォールバックします。
+
+> [!TIP]
+> **初回セットアップ:** CraftBotはAPIキー、エージェントの名前、MCP、スキルを設定するオンボーディングシーケンスをガイドします。
+
+> [!NOTE]
+> **Playwright Chromium:** WhatsApp Web連携にはオプションです。インストールに失敗しても、エージェントは他のタスクでは問題なく動作します。後で手動でインストールできます: `playwright install chromium`
+
---
## 🔧 トラブルシューティングとよくある問題
@@ -168,7 +370,7 @@ CraftBotはすべてのLiving UIに組み込まれており、**状態を常に
2. インストール後、ターミナルを再起動
3. もう一度`python run.py`を実行
-**代替手段:** Node.jsが不要なTUIモードを使う:
+**代替手段:** 代わりにCLIモードを使用（Node.js不要）：
```bash
python run.py --cli
```
diff --git a/README.ko.md b/README.ko.md
index fac99d50..8f236403 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -47,15 +47,13 @@
자체 SaaS 도구를 만들고 운영할 수 있는 AI 에이전트라는 점 외에도, CraftBot은 에이전트 하네스로서의 핵심 기능을 모두 갖추고 있어 작업, 도구, 메모리, 일상 워크플로 전반에서 범용 AI 에이전트로 사용자와 함께 일할 수 있습니다.
-- **Living UI.** CraftBot 안에서 동작하는 커스텀 앱을 빌드하고, 가져오고, 진화시킬 수 있습니다. 에이전트는 UI의 상태를 항상 인지하며 그 데이터를 직접 읽고, 쓰고, 조작할 수 있습니다.
-- **멀티태스킹과 세션 라우팅.** 아직도 `/new` 명령을 직접 입력하고 있나요? CraftBot은 새 세션을 시작해야 할 때와 기존 작업을 이어가야 할 때를 스스로 판단해 대화와 컨텍스트를 하나로 유지합니다.
-- **셀프 호스트와 BYOK.** OpenAI, Google Gemini, Anthropic Claude, OpenRouter 등을 지원하는 유연한 LLM 프로바이더 시스템. Ollama로 직접 모델을 호스트해서 토큰을 전혀 쓰지 않을 수도 있습니다.
-- **메모리 시스템.** RAG + 에이전트 파일 시스템 + 디스틸레이션을 통해 사용자와 CraftBot의 상호작용에서 로컬 지식 베이스를 구축합니다. CraftBot은 자정에 "꿈을 꾸며" 하루 동안 일어난 사건들을 통합합니다.
-- **선제적인 에이전트.** 사용자의 선호, 습관, 인생 목표를 학습한 뒤, 계획을 세우고 (물론 승인을 받아) 작업을 시작해 사용자가 더 나은 삶을 살도록 돕습니다.
-- **외부 도구 통합.** 임베디드 자격증명과 OAuth를 지원하며, Google Workspace, Slack, Notion, Zoom, LinkedIn, Discord, Telegram과 연결할 수 있습니다 (더 많은 도구가 추가될 예정입니다!).
-- **Skills와 MCP.** 150개 이상의 MCP와 170개 이상의 Skills가 즉시 사용 가능합니다. 새로운 Skills와 MCP를 빠르게 설치할 수 있고, 완료된 작업으로부터 클릭 한 번으로 Skills를 만들거나 개선할 수 있습니다.
-- **크로스 플랫폼.** Windows, macOS, Linux를 완벽히 지원하며, 플랫폼별 코드 분기와 Docker 컨테이너화를 제공합니다.
-- **브라우저 인터페이스와 CLI 지원.** 사용 환경에 맞춰 선택할 수 있습니다. 일상적인 사용은 가벼운 브라우저 UI로, 스크립팅이나 헤드리스 환경에서는 CLI로 사용하세요.
+> [!IMPORTANT]
+> **GUI 모드는 더 이상 지원되지 않습니다.** CraftBot은 GUI(데스크톱 자동화) 모드를 더 이상 지원하지 않습니다. 대신 Browser 또는 CLI 모드를 사용하세요.
+
+
---
@@ -98,7 +96,79 @@ python craftbot.py uninstall # 중지, 자동 시작 해제, 패키지 제거
- 당신의 워크플로에 딱 맞춘 커스텀 CRM은요?
- CraftBot이 대신 읽고 조작할 수 있는 회사 대시보드는요?
-CraftBot과 나란히 동작하는 Living UI로 띄워두고, 필요에 따라 함께 성장시키세요.
+```bash
+# 1. 리포지토리 클론
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. conda 환경에 설치
+python install.py --conda
+
+# 3. CraftBot 실행
+conda run -n craftbot python run.py
+
+# conda가 PATH에 없는 경우 (Windows 전용):
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+> [!NOTE]
+> CraftBot을 실행할 때마다 `conda run -n craftbot python run.py`를 사용하세요. 백그라운드 서비스가 없으므로 직접 시작하고 중지해야 합니다.
+
+---
+
+### 옵션 3 — 수동 설치 (pip)
+
+**이것을 선택하세요:** Python 환경을 완전히 직접 관리하고 싶고, 자동 서비스나 백그라운드 프로세스 없이 CraftBot을 관리하고 싶은 경우.
+
+`install.py`(플래그 없음)는 현재 활성화된 Python 환경에 표준 pip 설치를 수행합니다. `run.py`로 CraftBot을 수동으로 시작하고 중지합니다.
+
+```bash
+# 1. 리포지토리 클론
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. 활성 Python 환경에 의존성 설치
+python install.py
+
+# 3. CraftBot 실행
+python run.py
+```
+
+첫 실행 시 API 키 설정 과정을 안내해 줍니다.
+
+> [!NOTE]
+> Node.js가 설치되어 있지 않다면 설치 프로그램이 단계별로 안내해 줍니다. CLI 모드를 사용하면 브라우저 모드를 완전히 건너뛸 수도 있습니다 — Node.js 불필요: `python run.py --cli`
+
+### 바로 할 수 있는 일
+- 에이전트와 자연스럽게 대화
+- 복잡한 다단계 작업 요청
+- `/help`를 입력해 사용 가능한 명령 확인
+- Google, Slack, Notion 등과 연결
+
+### 🖥️ 인터페이스 모드
+
+
+
+CraftBot은 여러 UI 모드를 지원합니다. 선호에 따라 선택하세요.
+
+| 모드 | 명령어 | 요구 사항 | 적합한 용도 |
+|------|---------|--------------|----------|
+| **Browser** | `python run.py` | Node.js 18+ | 최신 웹 인터페이스, 가장 사용하기 쉬움 |
+| **CLI** | `python run.py --cli` | 없음 | 커맨드라인, 경량 |
+
+**브라우저 모드**가 기본이자 권장 모드입니다. Node.js가 없는 경우 설치 프로그램이 설치 안내를 제공하거나, 대신 **CLI 모드**를 사용할 수 있습니다.
+
+---
+
+## 🧬 Living UI
+
+**Living UI는 당신의 필요에 따라 진화하는 시스템/앱/대시보드입니다.**
+
+AI 코파일럿이 내장된 칸반 보드가 필요한가요? 당신의 워크플로에 딱 맞게 만든 맞춤형 CRM은요?
+CraftBot이 읽고 조작할 수 있는 회사 대시보드는요?
+Living UI로 실행하세요 — CraftBot과 함께 작동하며, 당신의 필요가 변할수록 함께 성장합니다.
@@ -144,7 +214,21 @@ CraftBot은 모든 Living UI에 내장되어 있으며 그 **상태를 항상
- **📊 습관 트래커** — 습관을 만들고 추적하세요. GitHub 스타일의 활동 캘린더로 개발자처럼 습관을 관리할 수 있습니다.
- **🐦 Luolinglo** — 듀오링고는 아니지만, 새로운 언어를 배우고 플래시카드를 만들며 CraftBot과 함께 연습할 수 있습니다.
-**[Living UI 마켓플레이스 둘러보기 및 기여하기 →](https://craftos.net/marketplace)**
+## 🧩 아키텍처 개요
+
+| 구성 요소 | 설명 |
+|-----------|-------------|
+| **Agent Base** | 작업 라이프사이클을 관리하고 구성 요소 간 조정을 담당하며 주요 에이전틱 루프를 처리하는 핵심 오케스트레이션 계층. |
+| **LLM Interface** | 여러 LLM 제공자(OpenAI, Gemini, Anthropic, BytePlus, Ollama)를 지원하는 통합 인터페이스. |
+| **Context Engine** | KV 캐시를 지원하는 최적화된 프롬프트를 생성합니다. |
+| **Action Manager** | 라이브러리에서 액션을 가져와 실행합니다. 커스텀 액션을 쉽게 확장할 수 있습니다. |
+| **Action Router** | 작업 요구 사항에 가장 잘 맞는 액션을 지능적으로 선택하고, 필요 시 LLM을 통해 입력 매개변수를 해결합니다. |
+| **Event Stream** | 작업 진행 추적, UI 업데이트, 실행 모니터링을 위한 실시간 이벤트 게시 시스템. |
+| **Memory Manager** | ChromaDB 기반의 RAG 시맨틱 메모리. 메모리 청킹, 임베딩, 검색, 점진적 업데이트를 처리합니다. |
+| **State Manager** | 에이전트 실행 컨텍스트, 대화 이력, 런타임 구성을 추적하는 전역 상태 관리. |
+| **Task Manager** | 작업 정의를 관리하며 단순/복잡 작업 모드, 할 일 생성, 다단계 워크플로우 추적을 가능하게 합니다. |
+| **Skill Manager** | 플러그형 스킬을 로드하여 에이전트 컨텍스트에 주입합니다. |
+| **MCP Adapter** | MCP 도구를 네이티브 액션으로 변환하는 Model Context Protocol 통합. |
---
@@ -162,13 +246,121 @@ CraftBot은 모든 Living UI에 내장되어 있으며 그 **상태를 항상
## 🔧 트러블슈팅과 자주 묻는 문제
-### Node.js가 없습니다 (브라우저 모드)
-`python run.py` 실행 시 **"npm not found in PATH"** 가 표시된다면:
-1. [nodejs.org](https://nodejs.org/)에서 LTS 버전 다운로드
+### install.py
+
+| 플래그 | 설명 |
+|------|-------------|
+| `--conda` | conda 환경 사용 (선택 사항) |
+
+### run.py
+
+| 플래그 | 설명 |
+|------|-------------|
+| (없음) | **Browser** 모드로 실행 (권장, Node.js 필요) |
+| `--cli` | **CLI** 모드로 실행 (경량) |
+
+### craftbot.py
+
+| 명령 | 설명 |
+|---------|-------------|
+| `install` | 의존성 설치, 자동 시작 등록, CraftBot 실행 |
+| `start` | CraftBot을 백그라운드에서 실행 |
+| `stop` | CraftBot 중지 |
+| `restart` | 중지 후 다시 시작 |
+| `status` | 실행 상태 및 자동 시작 상태 표시 |
+| `logs [-n N]` | 마지막 N개의 로그 라인 표시 (기본값: 50) |
+| `uninstall` | 자동 시작 등록 해제 |
+
+**설치 예시:**
+```bash
+# 간단한 pip 설치 (conda 미사용)
+python install.py
+
+# conda 환경 사용 (conda 사용자에게 권장)
+python install.py --conda
+```
+
+**CraftBot 실행:**
+
+```powershell
+# Browser 모드 (기본, Node.js 필요)
+python run.py
+
+# CLI 모드 (경량)
+python run.py --cli
+
+# conda 환경에서 실행
+conda run -n craftbot python run.py
+
+# conda가 PATH에 없는 경우 전체 경로 사용
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+**Linux/macOS (Bash):**
+```bash
+# Browser 모드 (기본, Node.js 필요)
+python run.py
+
+# CLI 모드 (경량)
+python run.py --cli
+
+# conda 환경에서 실행
+conda run -n craftbot python run.py
+```
+
+### 🔧 백그라운드 서비스 (권장)
+
+터미널을 닫아도 CraftBot이 계속 실행되도록 백그라운드 서비스로 실행합니다. 데스크톱 바로가기가 자동으로 생성되므로 언제든지 브라우저를 다시 열 수 있습니다.
+
+```bash
+# 의존성 설치, 로그인 시 자동 시작 등록, CraftBot 실행
+python craftbot.py install
+```
+
+이게 전부입니다. 터미널은 자동으로 닫히고, CraftBot은 백그라운드에서 실행되며, 브라우저가 자동으로 열립니다.
+
+```bash
+# 기타 서비스 명령:
+python craftbot.py start # CraftBot을 백그라운드에서 시작
+python craftbot.py status # 실행 여부 확인
+python craftbot.py stop # CraftBot 중지
+python craftbot.py restart # CraftBot 재시작
+python craftbot.py logs # 최근 로그 출력 확인
+```
+
+| 명령 | 설명 |
+|---------|-------------|
+| `python craftbot.py install` | 의존성 설치, 로그인 시 자동 시작 등록, CraftBot 실행, 브라우저 열기 후 터미널 자동 종료 |
+| `python craftbot.py start` | CraftBot을 백그라운드에서 시작 — 이미 실행 중이면 자동 재시작 (터미널 자동 종료) |
+| `python craftbot.py stop` | CraftBot 중지 |
+| `python craftbot.py restart` | CraftBot 중지 후 재시작 |
+| `python craftbot.py status` | CraftBot 실행 여부와 자동 시작 활성화 여부 확인 |
+| `python craftbot.py logs` | 최근 로그 출력 표시 (`-n 100`으로 더 많은 줄 표시) |
+| `python craftbot.py uninstall` | CraftBot 중지, 자동 시작 등록 해제, pip 패키지 제거 및 pip 캐시 정리 |
+
+> [!TIP]
+> `craftbot.py start` 또는 `craftbot.py install` 실행 후 **CraftBot 데스크톱 바로가기**가 자동으로 생성됩니다. 브라우저를 실수로 닫았다면 바로가기를 더블클릭해 다시 열 수 있습니다.
+
+> [!NOTE]
+> **설치:** 의존성이 누락된 경우 설치 프로그램이 명확한 안내를 제공합니다. Node.js가 없으면 설치 여부를 묻거나 CLI 모드로 전환할 수 있습니다. GPU 가용성을 자동으로 감지하고 필요한 경우 CPU 전용 모드로 대체합니다.
+
+> [!TIP]
+> **첫 실행 설정:** CraftBot은 API 키, 에이전트 이름, MCP, 스킬 설정을 위한 온보딩 과정을 안내합니다.
+
+> [!NOTE]
+> **Playwright Chromium:** WhatsApp Web 통합에 필요한 선택 사항입니다. 설치에 실패해도 다른 작업에서는 에이전트가 정상 작동합니다. 나중에 `playwright install chromium`으로 수동 설치할 수 있습니다.
+
+---
+
+## 🔧 문제 해결 및 자주 발생하는 이슈
+
+### Node.js 누락 (브라우저 모드용)
+`python run.py` 실행 시 **"npm not found in PATH"** 오류가 보인다면:
+1. [nodejs.org](https://nodejs.org/)에서 다운로드 (LTS 버전 권장)
2. 설치 후 터미널 재시작
3. 다시 `python run.py` 실행
-**대안:** Node.js가 필요 없는 TUI 모드를 사용하세요:
+**대안:** CLI 모드를 사용하세요 (Node.js 불필요):
```bash
python run.py --cli
```
diff --git a/README.md b/README.md
index debe2e29..57cd7270 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,28 @@ Aside from being an AI agent that can create and operate its own SaaS tools, Cra
---
+## ✨ Features
+
+- **Bring Your Own Key (BYOK)** — Flexible LLM provider system supporting OpenAI, Google Gemini, Anthropic Claude, BytePlus, and local Ollama models. Easily switch between providers.
+- **Memory System** — Distill and consolidate events that happened through the day at midnight.
+- **Proactive Agent** — Learn your preferences, habits, and life goals. Then, perform planning and initiate tasks (with approval, of course) to help you improve in life.
+- **Living UI** — Build, import, or evolve custom apps that live inside CraftBot. The agent stays aware of the UI's state and can read, write, and act on its data directly.
+- **External Tools Integration** — Connect to Google Workspace, Slack, Notion, Zoom, LinkedIn, Discord, and Telegram (more to come!) with embedded credentials and OAuth support.
+- **MCP** — Model Context Protocol integration for extending agent capabilities with external tools and services.
+- **Skills** — Extensible skill framework with built-in skills for task planning, research, code review, git operations, and more.
+- **Cross-Platform** — Full support for Windows, macOS, and Linux with platform-specific code variants and Docker containerization.
+
+> [!IMPORTANT]
+> **GUI mode is deprecated.** CraftBot no longer supports GUI (desktop automation) mode. Please use Browser or CLI mode instead.
+
+
+
+
+
+
+---
+
+
## 🧰 Getting Started
Requirements: Python 3.10+ · Node.js 18+ for browser mode
@@ -98,7 +120,81 @@ python craftbot.py uninstall # Stop, remove auto-start, and uninstall packages
- A custom CRM shaped exactly like your workflow?
- A company dashboard that CraftBot can read and drive on your behalf?
-Spin it up as a Living UI that runs alongside CraftBot and grows as your needs change.
+```bash
+# 1. Clone the repository
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. Install into a conda environment
+python install.py --conda
+
+# 3. Run CraftBot
+conda run -n craftbot python run.py
+
+# If conda is not in PATH (Windows only):
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+> [!NOTE]
+> Each time you want to run CraftBot, use `conda run -n craftbot python run.py`. There is no background service — you start and stop it yourself.
+
+---
+
+### Option 3 — Manual Install (pip)
+
+**Use this if:** you want full control over your Python environment and prefer managing CraftBot yourself with no automatic service or background process.
+
+`install.py` (no flags) does a standard pip install into whichever Python environment is currently active. You start and stop CraftBot manually using `run.py`.
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. Install dependencies into your active Python environment
+python install.py
+
+# 3. Run CraftBot
+python run.py
+```
+
+The first run will guide you through setting up your API keys and preferences.
+
+> [!NOTE]
+> If Node.js is not installed, the installer will provide step-by-step instructions. You can also skip browser mode entirely and use CLI mode — no Node.js required: `python run.py --cli`
+
+---
+
+### What you can do right after?
+- Talk to the agent naturally
+- Ask it to perform complex multi-step tasks
+- Type `/help` to see available commands
+- Connect to Google, Slack, Notion, and more
+
+### 🖥️ Interface Modes
+
+
+
+
+
+CraftBot supports multiple UI modes. Choose based on your preference:
+
+| Mode | Command | Requirements | Best For |
+|------|---------|--------------|----------|
+| **Browser** | `python run.py` | Node.js 18+ | Modern web interface, easiest to use |
+| **CLI** | `python run.py --cli` | None | Command-line, lightweight |
+
+**Browser mode** is the default and recommended. If you don't have Node.js, the installer will provide installation instructions or you can use **CLI mode** instead.
+
+---
+
+## 🧬 Living UI
+
+**Living UI is a system/app/dashboard that evolve with your needs.**
+
+Need a kanban board with an AI co-pilot built in? A custom CRM shaped exactly
+like your workflow? A company dashboard that CraftBot can read and drive on
+your behalf? Spin it up as a Living UI that runs alongside CraftBot and grows as your needs change.
@@ -140,7 +236,19 @@ REST API, and trigger actions on your behalf.
Build, customize, and evolve your own Living UI, and rely less on subscription tools that were never built to fit your needs perfectly.
-We are actively looking for developers to show off their Living UIs, and export them to **[the Living UI marketplace](https://craftos.net/marketplace)**. PRs are welcome!
+| Component | Description |
+|-----------|-------------|
+| **Agent Base** | Core orchestration layer that manages task lifecycle, coordinates between components, and handles the main agentic loop. |
+| **LLM Interface** | Unified interface supporting multiple LLM providers (OpenAI, Gemini, Anthropic, BytePlus, Ollama). |
+| **Context Engine** | Generates optimized prompts with KV-cache support. |
+| **Action Manager** | Retrieves and executes actions from the library. Custom action is easy to extend |
+| **Action Router** | Intelligently selects the best matching action based on task requirements and resolves input parameters via LLM when needed. |
+| **Event Stream** | Real-time event publishing system for task progress tracking, UI updates, and execution monitoring. |
+| **Memory Manager** | RAG-based semantic memory using ChromaDB. Handles memory chunking, embedding, retrieval, and incremental updates. |
+| **State Manager** | Global state management for tracking agent execution context, conversation history, and runtime configuration. |
+| **Task Manager** | Manages task definitions, enable simple and complex tasks bode, create todos, and multi-step workflow tracking. |
+| **Skill Manager** | Loads and injects pluggable skills into the agent context. |
+| **MCP Adapter** | Model Context Protocol integration that converts MCP tools into native actions. |
---
@@ -153,17 +261,82 @@ We are actively looking for developers to show off their Living UIs, and export
**[Browse and contribute to the Living UI marketplace →](https://craftos.net/marketplace)**
---
-
-# CraftBot vs. the alternatives
-
-| | v0 / Lovable / Bolt | OpenClaw | Claude Code | **CraftBot** |
-| -------------------------------- | ------------------- | -------------------- | -------------------- | --------------------------------------- |
-| **Builds custom apps** | ✅ One-shot | 🚫 | ✅ (manual) | ✅ Conversational |
-| **Agent operates the app** | 🚫 | ⚠️ Calls tools | 🚫 | ✅ Embedded in every Living UI |
-| **Persistent agent memory** | 🚫 | ✅ | ✅ | ✅ RAG + Agent file system + Distillation |
-| **Self-hosted** | ⚠️ Partial | ✅ | 🚫 SaaS | ✅ MIT, your machine |
-| **Model agnostic** | ✅ | ✅ | ⚠️ Partial | ✅ Major providers + OpenRouter |
-
+
+## 📋 Command Reference
+
+### craftbot.py — Automatic Setup (Recommended)
+
+| Command | Description |
+|---------|-------------|
+| `python craftbot.py install` | Install dependencies, register auto-start on login, start CraftBot, open browser, and close the terminal automatically |
+| `python craftbot.py start` | Start CraftBot in the background — auto-restarts if already running (terminal closes automatically) |
+| `python craftbot.py stop` | Stop CraftBot |
+| `python craftbot.py restart` | Stop and start CraftBot |
+| `python craftbot.py status` | Check if CraftBot is running and if auto-start is enabled |
+| `python craftbot.py logs` | Show recent log output (`-n 100` for more lines) |
+| `python craftbot.py uninstall` | Stop CraftBot, remove auto-start registration, uninstall pip packages, and purge pip cache |
+
+---
+
+### install.py — Manual Setup
+
+| Flag | Description |
+|------|-------------|
+| (none) | Standard pip install — uses your active Python environment |
+| `--conda` | Install into a conda environment (auto-installs Miniconda if not found) |
+
+```bash
+# Standard pip install
+python install.py
+
+# With conda environment
+python install.py --conda
+```
+
+---
+
+### run.py — Running CraftBot (Manual Setup Only)
+
+> If you used `craftbot.py install`, CraftBot starts automatically. Use `run.py` only when running manually.
+
+| Flag | Description |
+|------|-------------|
+| (none) | Run in **Browser** mode (recommended, requires Node.js) |
+| `--cli` | Run in **CLI** mode (lightweight, no Node.js required) |
+
+**Windows (PowerShell):**
+```powershell
+# Browser mode (default, requires Node.js)
+python run.py
+
+# CLI mode (no Node.js required)
+python run.py --cli
+
+# With conda environment
+conda run -n craftbot python run.py
+
+# Or using full path if conda not in PATH
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+**Linux/macOS (Bash):**
+```bash
+python run.py # Browser mode
+python run.py --cli # CLI mode
+
+# With conda environment
+conda run -n craftbot python run.py
+```
+
+> [!NOTE]
+> **Installation:** The installer now provides clear guidance if dependencies are missing. If Node.js is not found, you'll be prompted to install it or can switch to CLI mode. Installation automatically detects GPU availability and falls back to CPU-only mode if needed.
+
+> [!TIP]
+> **First-time setup:** CraftBot will guide you through an onboarding sequence to configure API keys, the agent's name, MCPs, and Skills.
+
+> [!NOTE]
+> **Playwright Chromium:** Optional for WhatsApp Web integration. If installation fails, the agent will still work fine for other tasks. Install manually later with: `playwright install chromium`
+
---
## 🔧 Troubleshooting & Common Issues
diff --git a/README.pt-BR.md b/README.pt-BR.md
index 9cf76425..d546a0ff 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -61,7 +61,53 @@ Além de ser um agente de IA capaz de criar e operar suas próprias ferramentas
## 🧰 Primeiros passos
-Requisitos: Python 3.10+ · Node.js 18+ para o modo navegador
+- **Bring Your Own Key (BYOK)** — Sistema flexível de provedores de LLM com suporte a OpenAI, Google Gemini, Anthropic Claude, BytePlus e modelos locais do Ollama. Troque de provedor com facilidade.
+- **Sistema de Memória** — Destila e consolida os eventos ocorridos durante o dia à meia-noite.
+- **Agente Proativo** — Aprende suas preferências, hábitos e metas de vida. Depois, planeja e inicia tarefas (com sua aprovação, claro) para ajudá-lo a evoluir.
+- **Living UI** — Construa, importe ou evolua aplicativos personalizados que vivem dentro do CraftBot. O agente permanece ciente do estado da UI e pode ler, escrever e agir sobre seus dados diretamente.
+- **Integração com ferramentas externas** — Conecte-se a Google Workspace, Slack, Notion, Zoom, LinkedIn, Discord e Telegram (mais a caminho!) com credenciais embutidas e suporte a OAuth.
+- **MCP** — Integração com o Model Context Protocol para ampliar as capacidades do agente com ferramentas e serviços externos.
+- **Skills** — Framework de skills extensível com skills embutidas para planejamento de tarefas, pesquisa, revisão de código, operações de git e muito mais.
+- **Multiplataforma** — Suporte completo para Windows, macOS e Linux, com variantes de código específicas por plataforma e conteinerização via Docker.
+
+> [!IMPORTANT]
+> **O modo GUI foi descontinuado.** O CraftBot não oferece mais suporte ao modo GUI (automação de desktop). Use os modos Browser ou CLI em vez disso.
+
+
+
+
+
+
+---
+
+
+## 🧰 Começando
+
+### Pré-requisitos
+- Python **3.10+**
+- `git` (necessário para clonar o repositório)
+- Uma chave de API do provedor LLM escolhido (OpenAI, Gemini ou Anthropic)
+- `Node.js` **18+** (opcional — necessário apenas para a interface no navegador)
+- `conda` (opcional — se não for encontrado, o instalador pode instalar o Miniconda automaticamente)
+
+### Qual opção devo usar?
+
+> **Não sabe qual escolher? Use a Opção 1.** Ela cuida de tudo por você.
+
+| | Opção 1 — Serviço | Opção 2 — Conda | Opção 3 — Manual |
+|---|---|---|---|
+| **Para quem** | A maioria dos usuários, iniciantes, testes | Usuários de Conda que querem ambientes isolados | Usuários avançados, Python personalizado, controle total |
+| **Gerencia Python/ambiente automaticamente?** | ✅ Automático | ✅ Automático | ❌ Você gerencia |
+| **Roda em segundo plano?** | ✅ Sim, como serviço | ❌ Não | ❌ Não |
+| **Como começar** | `python craftbot.py install` | `python install.py --conda` | `python install.py` |
+
+---
+
+### ⭐ Opção 1 — Instalação como serviço (Recomendada)
+
+**Use esta se:** você quer que o CraftBot simplesmente funcione — serviço em segundo plano, início automático no login, atalho na área de trabalho, sem passos manuais.
+
+O `craftbot.py` cuida de tudo: ambiente Python, dependências, gerenciamento de processos em segundo plano e registro de início automático.
```bash
# 1. Clone o repositório
@@ -98,7 +144,80 @@ python craftbot.py uninstall # Para o serviço, remove o autoinício e desinsta
- Um CRM sob medida, exatamente no formato do seu fluxo de trabalho?
- Um dashboard corporativo que o CraftBot consegue ler e operar por você?
-Coloque-o no ar como uma Living UI que roda lado a lado com o CraftBot e cresce conforme suas necessidades mudam.
+```bash
+# 1. Clone o repositório
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. Instale em um ambiente conda
+python install.py --conda
+
+# 3. Execute o CraftBot
+conda run -n craftbot python run.py
+
+# Se o conda não estiver no PATH (somente Windows):
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+> [!NOTE]
+> Sempre que quiser rodar o CraftBot, use `conda run -n craftbot python run.py`. Não há serviço em segundo plano — você inicia e para manualmente.
+
+---
+
+### Opção 3 — Instalação manual (pip)
+
+**Use esta se:** você quer controle total sobre seu ambiente Python e prefere gerenciar o CraftBot por conta própria, sem serviço automático ou processo em segundo plano.
+
+O `install.py` (sem flags) faz uma instalação pip padrão no ambiente Python ativo. Você inicia e para o CraftBot manualmente com `run.py`.
+
+```bash
+# 1. Clone o repositório
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. Instale as dependências no seu ambiente Python ativo
+python install.py
+
+# 3. Execute o CraftBot
+python run.py
+```
+
+Na primeira execução, você será guiado para configurar suas chaves de API e preferências.
+
+> [!NOTE]
+> Se o Node.js não estiver instalado, o instalador fornecerá instruções passo a passo. Você também pode pular completamente o modo navegador e usar o modo CLI — sem Node.js: `python run.py --cli`
+
+### O que você pode fazer logo de cara?
+- Conversar com o agente de forma natural
+- Pedir que ele execute tarefas complexas de várias etapas
+- Digitar `/help` para ver os comandos disponíveis
+- Conectar-se ao Google, Slack, Notion e muito mais
+
+### 🖥️ Modos de interface
+
+
+
+
+
+O CraftBot oferece vários modos de UI. Escolha conforme sua preferência:
+
+| Modo | Comando | Requisitos | Indicado para |
+|------|---------|--------------|----------|
+| **Browser** | `python run.py` | Node.js 18+ | Interface web moderna, a mais fácil de usar |
+| **CLI** | `python run.py --cli` | Nenhum | Linha de comando, leve |
+
+O **modo Browser** é o padrão e recomendado. Se não tiver o Node.js, o instalador fornecerá instruções de instalação, ou você pode usar o **modo CLI**.
+
+---
+
+## 🧬 Living UI
+
+**Living UI é um sistema/app/dashboard que evolui com suas necessidades.**
+
+Precisa de um quadro kanban com um copiloto de IA embutido? Um CRM personalizado
+moldado exatamente para o seu fluxo de trabalho? Um dashboard corporativo que o
+CraftBot possa ler e operar por você? Coloque-o no ar como uma Living UI — ela
+roda junto ao CraftBot e cresce conforme suas necessidades mudam.
@@ -150,20 +269,140 @@ Estamos ativamente procurando desenvolvedores que queiram mostrar suas Living UI
- **📊 Habit Tracker** — Crie e acompanhe seus hábitos. Calendário de atividades no estilo do GitHub para acompanhar seus hábitos como um(a) dev.
- **🐦 Luolinglo** — Não é o Duolingo, mas você pode aprender novos idiomas, criar flashcards e praticar com o CraftBot.
-**[Explore e contribua para o marketplace de Living UI →](https://craftos.net/marketplace)**
+## 🧩 Visão geral da arquitetura
+
+| Componente | Descrição |
+|-----------|-------------|
+| **Agent Base** | Camada central de orquestração que gerencia o ciclo de vida das tarefas, coordena os componentes e cuida do loop principal do agente. |
+| **LLM Interface** | Interface unificada com suporte a vários provedores de LLM (OpenAI, Gemini, Anthropic, BytePlus, Ollama). |
+| **Context Engine** | Gera prompts otimizados com suporte a KV-cache. |
+| **Action Manager** | Recupera e executa ações da biblioteca. Ações personalizadas são fáceis de estender. |
+| **Action Router** | Seleciona de forma inteligente a ação que melhor corresponde aos requisitos da tarefa e resolve parâmetros de entrada via LLM quando necessário. |
+| **Event Stream** | Sistema de publicação de eventos em tempo real para acompanhar o progresso das tarefas, atualizar a UI e monitorar a execução. |
+| **Memory Manager** | Memória semântica baseada em RAG usando o ChromaDB. Lida com chunking, embeddings, recuperação e atualizações incrementais. |
+| **State Manager** | Gerenciamento global de estado para rastrear contexto de execução do agente, histórico de conversas e configurações de runtime. |
+| **Task Manager** | Gerencia definições de tarefas, habilita modos simples e complexos, cria to-dos e rastreia workflows multi-etapa. |
+| **Skill Manager** | Carrega e injeta skills plugáveis no contexto do agente. |
+| **MCP Adapter** | Integração com o Model Context Protocol que converte ferramentas MCP em ações nativas. |
---
-
-# CraftBot vs. as alternativas
-
-| | v0 / Lovable / Bolt | OpenClaw | Claude Code | **CraftBot** |
-| -------------------------------- | ------------------- | -------------------- | -------------------- | --------------------------------------- |
-| **Constrói apps personalizados** | ✅ De uma vez | 🚫 | ✅ (manual) | ✅ Conversacional |
-| **O agente opera o app** | 🚫 | ⚠️ Chama ferramentas | 🚫 | ✅ Embutido em toda Living UI |
-| **Memória persistente do agente** | 🚫 | ✅ | ✅ | ✅ RAG + sistema de arquivos do agente + destilação |
-| **Self-hosted** | ⚠️ Parcial | ✅ | 🚫 SaaS | ✅ MIT, na sua máquina |
-| **Independente de modelo** | ✅ | ✅ | ⚠️ Parcial | ✅ Principais provedores + OpenRouter |
-
+
+## 🔜 Roadmap
+
+- [X] **Módulo de memória** — Concluído.
+- [ ] **Integração com ferramentas externas** — Ainda adicionando mais!
+- [X] **Camada MCP** — Concluída.
+- [X] **Camada de Skills** — Concluída.
+- [ ] **Comportamento proativo** — Em andamento
+
+---
+
+## 📋 Referência de comandos
+
+### install.py
+
+| Flag | Descrição |
+|------|-------------|
+| `--conda` | Usa ambiente conda (opcional) |
+
+### run.py
+
+| Flag | Descrição |
+|------|-------------|
+| (nenhum) | Executa no modo **Browser** (recomendado, requer Node.js) |
+| `--cli` | Executa no modo **CLI** (leve) |
+
+### craftbot.py
+
+| Comando | Descrição |
+|---------|-------------|
+| `install` | Instala deps, registra auto-start e inicia o CraftBot |
+| `start` | Inicia o CraftBot em segundo plano |
+| `stop` | Para o CraftBot |
+| `restart` | Para e inicia novamente |
+| `status` | Mostra o status de execução e do auto-start |
+| `logs [-n N]` | Mostra as últimas N linhas do log (padrão: 50) |
+| `uninstall` | Remove o registro do auto-start |
+
+**Exemplos de instalação:**
+```bash
+# Instalação simples via pip (sem conda)
+python install.py
+
+# Com ambiente conda (recomendado para usuários de conda)
+python install.py --conda
+```
+
+**Executando o CraftBot:**
+
+```powershell
+# Modo Browser (padrão, requer Node.js)
+python run.py
+
+# Modo CLI (leve)
+python run.py --cli
+
+# Com ambiente conda
+conda run -n craftbot python run.py
+
+# Ou usando caminho completo se o conda não estiver no PATH
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+**Linux/macOS (Bash):**
+```bash
+# Modo Browser (padrão, requer Node.js)
+python run.py
+
+# Modo CLI (leve)
+python run.py --cli
+
+# Com ambiente conda
+conda run -n craftbot python run.py
+```
+
+### 🔧 Serviço em segundo plano (recomendado)
+
+Execute o CraftBot como um serviço em segundo plano para que ele continue rodando mesmo após fechar o terminal. Um atalho na área de trabalho é criado automaticamente, permitindo reabrir o navegador a qualquer momento.
+
+```bash
+# Instala dependências, registra auto-start no login e inicia o CraftBot
+python craftbot.py install
+```
+
+É isso. O terminal se fecha sozinho, o CraftBot roda em segundo plano e o navegador abre automaticamente.
+
+```bash
+# Outros comandos do serviço:
+python craftbot.py start # Inicia o CraftBot em segundo plano
+python craftbot.py status # Verifica se está em execução
+python craftbot.py stop # Para o CraftBot
+python craftbot.py restart # Reinicia o CraftBot
+python craftbot.py logs # Mostra logs recentes
+```
+
+| Comando | Descrição |
+|---------|-------------|
+| `python craftbot.py install` | Instala dependências, registra auto-start no login, inicia o CraftBot, abre o navegador e fecha o terminal automaticamente |
+| `python craftbot.py start` | Inicia o CraftBot em segundo plano — reinicia automaticamente se já estiver rodando (o terminal se fecha sozinho) |
+| `python craftbot.py stop` | Para o CraftBot |
+| `python craftbot.py restart` | Para e inicia o CraftBot |
+| `python craftbot.py status` | Verifica se o CraftBot está rodando e se o auto-start está habilitado |
+| `python craftbot.py logs` | Mostra a saída recente do log (`-n 100` para mais linhas) |
+| `python craftbot.py uninstall` | Para o CraftBot, remove o registro de auto-start, desinstala pacotes pip e limpa o cache do pip |
+
+> [!TIP]
+> Após `craftbot.py start` ou `craftbot.py install`, um **atalho do CraftBot na área de trabalho** é criado automaticamente. Se você fechar o navegador por acidente, basta clicar duas vezes no atalho para reabri-lo.
+
+> [!NOTE]
+> **Instalação:** O instalador agora fornece orientações claras se faltarem dependências. Se o Node.js não for encontrado, você será orientado a instalá-lo ou poderá alternar para o modo CLI. A instalação detecta automaticamente a disponibilidade de GPU e recorre ao modo somente CPU quando necessário.
+
+> [!TIP]
+> **Configuração inicial:** O CraftBot vai guiá-lo por um onboarding para configurar chaves de API, o nome do agente, MCPs e Skills.
+
+> [!NOTE]
+> **Playwright Chromium:** Opcional para a integração com o WhatsApp Web. Se a instalação falhar, o agente continuará funcionando normalmente para outras tarefas. Instale manualmente depois com: `playwright install chromium`
+
---
## 🔧 Solução de problemas e dúvidas comuns
@@ -174,7 +413,7 @@ Se ao rodar `python run.py` você vir **"npm not found in PATH"**:
2. Instale e reinicie o terminal
3. Rode `python run.py` novamente
-**Alternativa:** Use o modo TUI, que não precisa de Node.js:
+**Alternativa:** Use o modo CLI (sem necessidade de Node.js):
```bash
python run.py --cli
```
diff --git a/README.zh-TW.md b/README.zh-TW.md
index 1df95154..ba96a478 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -59,6 +59,28 @@
---
+## ✨ 功能特色
+
+- **自帶金鑰（BYOK）** — 靈活的 LLM 供應商系統，支援 OpenAI、Google Gemini、Anthropic Claude、BytePlus 及本地 Ollama 模型，可輕鬆切換。
+- **記憶系統** — 每天午夜時分提煉並整合當日所發生的事件。
+- **主動式代理人** — 學習你的偏好、習慣與人生目標，接著進行規劃並（在取得同意後）主動啟動任務，協助你在生活中不斷進步。
+- **Living UI** — 在 CraftBot 中建立、匯入或演進自訂應用。代理人持續感知 UI 的狀態，並可直接讀取、寫入和操作其資料。
+- **外部工具整合** — 連接 Google Workspace、Slack、Notion、Zoom、LinkedIn、Discord 及 Telegram（更多服務陸續推出！），內建憑證與 OAuth 支援。
+- **MCP** — 整合 Model Context Protocol，以外部工具與服務擴充代理人的能力。
+- **技能（Skills）** — 可擴充的技能框架，內建任務規劃、研究、程式碼審查、Git 操作等多種技能。
+- **跨平台** — 完整支援 Windows、macOS 與 Linux，並提供對應的平台程式碼與 Docker 容器化。
+
+> [!IMPORTANT]
+> **GUI 模式已停用。** CraftBot 不再支援 GUI（桌面自動化）模式。請改用 Browser 或 CLI 模式。
+
+
+
+
+
+
+---
+
+
## 🧰 快速開始
環境需求: Python 3.10+ · 瀏覽器模式需要 Node.js 18+
@@ -98,7 +120,79 @@ python craftbot.py uninstall # 停止執行、移除自動啟動並解除安裝
- 一套完全貼合你工作流程的客製化 CRM?
- 一個 CraftBot 可以代替你讀取並操作的公司儀表板?
-把它做成一個 Living UI,與 CraftBot 一起執行,並隨著你的需求持續成長。
+```bash
+# 1. 複製儲存庫
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. 安裝到 conda 環境
+python install.py --conda
+
+# 3. 執行 CraftBot
+conda run -n craftbot python run.py
+
+# 若 conda 不在 PATH（僅 Windows）：
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+> [!NOTE]
+> 每次要執行 CraftBot 時，請使用 `conda run -n craftbot python run.py`。此方式沒有背景服務——由你手動啟停。
+
+---
+
+### 方案三 — 手動安裝（pip）
+
+**適合你，如果：** 你想完全掌控 Python 環境，不需要任何自動服務或背景程序，自己管理 CraftBot。
+
+`install.py`（不帶旗標）會對目前啟用的 Python 環境執行標準 pip 安裝。透過 `run.py` 手動啟停 CraftBot。
+
+```bash
+# 1. 複製儲存庫
+git clone https://github.com/CraftOS-dev/CraftBot.git
+cd CraftBot
+
+# 2. 在目前 Python 環境中安裝相依套件
+python install.py
+
+# 3. 執行 CraftBot
+python run.py
+```
+
+首次執行時會引導你完成 API 金鑰設定與偏好設定。
+
+> [!NOTE]
+> 若尚未安裝 Node.js，安裝程式會提供逐步指引。你也可以完全略過瀏覽器模式，直接使用 CLI 模式——無需 Node.js：`python run.py --cli`
+
+### 立即能做什麼？
+- 用自然語言與代理人對話
+- 請它執行複雜的多步驟任務
+- 輸入 `/help` 查看可用指令
+- 連接 Google、Slack、Notion 等服務
+
+### 🖥️ 介面模式
+
+
+
+
+
+CraftBot 支援多種 UI 模式，可依個人偏好選擇：
+
+| 模式 | 指令 | 需求 | 適用情境 |
+|------|---------|--------------|----------|
+| **Browser** | `python run.py` | Node.js 18+ | 現代化網頁介面，最易使用 |
+| **CLI** | `python run.py --cli` | 無 | 命令列，輕量化 |
+
+**Browser 模式**為預設與建議選項。若沒有 Node.js，安裝程式會提供安裝指引，或你可改用 **CLI 模式**。
+
+---
+
+## 🧬 Living UI
+
+**Living UI 是隨你需求演進的系統／應用／儀表板。**
+
+需要一個內建 AI 副駕駛的看板？量身打造符合你工作流程的 CRM？
+一個 CraftBot 能讀取並驅動的公司儀表板？
+將它作為 Living UI 啟動——它與 CraftBot 並行運作，並隨著你的需求變化而成長。
@@ -144,20 +238,140 @@ CraftBot 嵌入在每一個 Living UI 中,並且**對其狀態保持感知**:它
- **📊 習慣追蹤器** — 培養並追蹤自己的習慣,用類 GitHub 風格的活動日曆像寫程式一樣維護你的習慣。
- **🐦 Luolinglo** — 不是 Duolingo,但你可以學新語言、做單字卡片,並和 CraftBot 一起練習。
-**[瀏覽並參與貢獻 Living UI 市集 →](https://craftos.net/marketplace)**
+## 🧩 架構概覽
+
+| 元件 | 說明 |
+|-----------|-------------|
+| **Agent Base** | 負責管理任務生命週期、協調各元件並處理主要代理人迴圈的核心編排層。 |
+| **LLM Interface** | 支援多家 LLM 供應商（OpenAI、Gemini、Anthropic、BytePlus、Ollama）的統一介面。 |
+| **Context Engine** | 產生最佳化的 Prompt，支援 KV-Cache。 |
+| **Action Manager** | 從動作庫中擷取並執行動作，方便擴充自訂動作。 |
+| **Action Router** | 依任務需求智慧挑選最合適的動作，並在需要時透過 LLM 解析輸入參數。 |
+| **Event Stream** | 即時事件發佈系統，用於任務進度追蹤、UI 更新與執行監控。 |
+| **Memory Manager** | 以 ChromaDB 為基礎的 RAG 語意記憶，處理記憶分塊、嵌入、檢索與增量更新。 |
+| **State Manager** | 全域狀態管理，追蹤代理人執行脈絡、對話歷史與執行期設定。 |
+| **Task Manager** | 管理任務定義，支援簡單與複雜任務模式、待辦清單建立，以及多步驟流程追蹤。 |
+| **Skill Manager** | 載入並將可插拔技能注入到代理人情境中。 |
+| **MCP Adapter** | Model Context Protocol 整合，將 MCP 工具轉換為原生動作。 |
---
-
-# CraftBot 與其他方案比較
-
-| | v0 / Lovable / Bolt | OpenClaw | Claude Code | **CraftBot** |
-| -------------------------------- | ------------------- | -------------------- | -------------------- | --------------------------------------- |
-| **建立客製化應用** | ✅ 一次性生成 | 🚫 | ✅ (手動) | ✅ 對話式持續打造 |
-| **Agent 能操作這個應用** | 🚫 | ⚠️ 透過工具呼叫 | 🚫 | ✅ 內嵌於每一個 Living UI |
-| **持久化的 Agent 記憶** | 🚫 | ✅ | ✅ | ✅ RAG + Agent 檔案系統 + 蒸餾 |
-| **自架部署** | ⚠️ 部分支援 | ✅ | 🚫 SaaS | ✅ MIT 授權,跑在你自己的機器 |
-| **模型無關** | ✅ | ✅ | ⚠️ 部分支援 | ✅ 主流供應商 + OpenRouter |
-
+
+## 🔜 藍圖
+
+- [X] **記憶模組** — 完成。
+- [ ] **外部工具整合** — 仍在持續新增！
+- [X] **MCP 層** — 完成。
+- [X] **技能層** — 完成。
+- [ ] **主動式行為** — 進行中
+
+---
+
+## 📋 指令參考
+
+### install.py
+
+| 旗標 | 說明 |
+|------|-------------|
+| `--conda` | 使用 conda 環境（選用） |
+
+### run.py
+
+| 旗標 | 說明 |
+|------|-------------|
+| （無） | 以 **Browser** 模式執行（建議，需 Node.js） |
+| `--cli` | 以 **CLI** 模式執行（輕量） |
+
+### craftbot.py
+
+| 指令 | 說明 |
+|---------|-------------|
+| `install` | 安裝相依套件、註冊開機自動啟動，並啟動 CraftBot |
+| `start` | 在背景啟動 CraftBot |
+| `stop` | 停止 CraftBot |
+| `restart` | 停止後重新啟動 |
+| `status` | 顯示執行狀態與自動啟動狀態 |
+| `logs [-n N]` | 顯示最後 N 行記錄（預設 50） |
+| `uninstall` | 移除自動啟動註冊 |
+
+**安裝範例：**
+```bash
+# 單純使用 pip 安裝（不使用 conda）
+python install.py
+
+# 使用 conda 環境（建議給 conda 使用者）
+python install.py --conda
+```
+
+**執行 CraftBot：**
+
+```powershell
+# Browser 模式（預設，需 Node.js）
+python run.py
+
+# CLI 模式（輕量）
+python run.py --cli
+
+# 使用 conda 環境
+conda run -n craftbot python run.py
+
+# 若 conda 不在 PATH，使用完整路徑
+&"$env:USERPROFILE\miniconda3\Scripts\conda.exe" run -n craftbot python run.py
+```
+
+**Linux/macOS（Bash）：**
+```bash
+# Browser 模式（預設，需 Node.js）
+python run.py
+
+# CLI 模式（輕量）
+python run.py --cli
+
+# 使用 conda 環境
+conda run -n craftbot python run.py
+```
+
+### 🔧 背景服務（建議）
+
+將 CraftBot 當成背景服務執行，即使關閉終端機仍能持續運作。系統會自動建立桌面捷徑，讓你隨時可重新開啟瀏覽器。
+
+```bash
+# 安裝相依套件、註冊登入時自動啟動並啟動 CraftBot
+python craftbot.py install
+```
+
+這樣就完成了。終端機會自動關閉，CraftBot 在背景執行，瀏覽器也會自動開啟。
+
+```bash
+# 其他服務指令：
+python craftbot.py start # 在背景啟動 CraftBot
+python craftbot.py status # 檢查是否正在執行
+python craftbot.py stop # 停止 CraftBot
+python craftbot.py restart # 重新啟動 CraftBot
+python craftbot.py logs # 檢視最近的記錄
+```
+
+| 指令 | 說明 |
+|---------|-------------|
+| `python craftbot.py install` | 安裝相依套件、註冊登入時自動啟動、啟動 CraftBot、開啟瀏覽器並自動關閉終端機 |
+| `python craftbot.py start` | 在背景啟動 CraftBot——若已在執行，會自動重啟（終端機自動關閉） |
+| `python craftbot.py stop` | 停止 CraftBot |
+| `python craftbot.py restart` | 停止並重新啟動 CraftBot |
+| `python craftbot.py status` | 檢查 CraftBot 是否執行中，以及自動啟動是否啟用 |
+| `python craftbot.py logs` | 顯示最近的記錄（使用 `-n 100` 顯示更多行） |
+| `python craftbot.py uninstall` | 停止 CraftBot、移除自動啟動註冊、解除 pip 套件並清除 pip 快取 |
+
+> [!TIP]
+> 執行 `craftbot.py start` 或 `craftbot.py install` 後，會自動建立 **CraftBot 桌面捷徑**。若不小心關閉了瀏覽器，雙擊捷徑即可重新開啟。
+
+> [!NOTE]
+> **安裝：** 若相依套件缺失，安裝程式會提供清楚的指引。若找不到 Node.js，會提示你安裝或切換至 CLI 模式。安裝程式會自動偵測 GPU 是否可用，必要時會自動回退至 CPU 模式。
+
+> [!TIP]
+> **首次設定：** CraftBot 會引導你完成初始化流程，包含設定 API 金鑰、代理人名稱、MCP 與技能。
+
+> [!NOTE]
+> **Playwright Chromium：** 整合 WhatsApp Web 時選用。若安裝失敗，代理人仍可正常執行其他任務。稍後可以手動安裝：`playwright install chromium`。
+
---
## 🔧 疑難排解與常見問題
@@ -168,7 +382,7 @@ CraftBot 嵌入在每一個 Living UI 中,並且**對其狀態保持感知**:它
2. 安裝完成後重啟終端機
3. 再次執行 `python run.py`
-**替代方案:** 改用不需要 Node.js 的 TUI 模式:
+**替代方案：** 改用 CLI 模式（不需 Node.js）：
```bash
python run.py --cli
```
diff --git a/app/ui_layer/browser/frontend/src/components/ui/StatusIndicator.module.css b/app/ui_layer/browser/frontend/src/components/ui/StatusIndicator.module.css
index a9502b63..5d4f42d6 100644
--- a/app/ui_layer/browser/frontend/src/components/ui/StatusIndicator.module.css
+++ b/app/ui_layer/browser/frontend/src/components/ui/StatusIndicator.module.css
@@ -16,7 +16,7 @@
.running,
.thinking,
.working {
- color: #FF4F18;
+ color: var(--text-primary);
}
.completed {
diff --git a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.module.css b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.module.css
index 8cfcfa12..b9a42334 100644
--- a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.module.css
+++ b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.module.css
@@ -42,8 +42,8 @@
}
.stepDot.active {
- background: #FF4F18;
- border-color: #FF4F18;
+ background: var(--text-primary);
+ border-color: var(--text-primary);
color: var(--color-white);
}
@@ -82,7 +82,7 @@
}
.stepConnector.active {
- background: #FF4F18;
+ background: var(--text-primary);
}
/* Main Content */
@@ -159,15 +159,6 @@
overflow: visible;
}
-/* The embedded panel's root (.settingsSection) ships with a 600px max-width
- and auto margins for the Settings page. Inside the onboarding card those
- constraints leave dead space on the right, so we let it fill the card.
- Scoped to .integrationsPanel — the Settings page is untouched. */
-.integrationsPanel :global([class*="settingsSection"]) {
- max-width: none;
- margin: 0;
-}
-
/* Scrollbar styling */
.optionsList::-webkit-scrollbar,
.integrationsPanel::-webkit-scrollbar {
diff --git a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
index edbfbb83..a6c14840 100644
--- a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
@@ -591,7 +591,7 @@ export function OnboardingPage() {
if (isIntegrationsStep) {
return (
-
+
)
}
diff --git a/requirements.txt b/requirements.txt
index 870d76be..87661cc8 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -41,15 +41,14 @@ python-dotenv
scikit-learn
watchdog
telethon
-lark-oapi # Lark Long-Connection / WebSocket listener
-croniter>=2.0.0 # Cron expression parsing for scheduler
-playwright # WhatsApp Web browser automation
-opencv-python-headless # Video analysis keyframe extraction
-babel>=2.14.0 # Language list for onboarding
-boto3>=1.34.0 # AWS Bedrock provider (LLM/VLM/embedding via Converse + Titan)
-pdfplumber # PDF text, table, and bbox extraction (read_pdf primary engine)
-pypdfium2 # PDF page dimensions for scanned document fallback (read_pdf)
-pdfminer.six # PDF text extraction fallback (read_pdf)
-pymupdf # PDF editing engine — redaction, annotations, replace (edit_pdf)
-pypdf # AcroForm field filling and PDF merging (edit_pdf)
-
+lark-oapi
+croniter>=2.0.0
+playwright
+opencv-python-headless
+babel>=2.14.0
+boto3>=1.34.0
+pdfplumber
+pypdfium2
+pdfminer.six
+pymupdf
+pypdf
\ No newline at end of file