⚫ BAW — Black And White ⚪

No LangChain. No AutoGPT. Just a courtroom of Angels and Devils debating every agent call.

_{Built from scratch • 由零打造 • 100% vendor-agnostic • Cost-transparent}

🤍🖤 Angel/Devil Dual-Soul Court • Self-Evolution • Multi-Model Fusion • Telegram Bot
🤍🖤 Angel/Devil 雙魂法庭 • 自我進化 • 多模型融合 • Telegram Bot

⚔️ Why BAW? (vs The Alternatives)

BAW in action — CLI setup wizard + project analysis with built-in Angel/Devil court

	BAW (this)	LangChain / LangGraph	CrewAI	AutoGen	OpenAI Agents SDK
Architecture	100% from scratch	Wraps dozens of libs	Wraps LangChain	Wraps OpenAI	Proprietary
Lock-in	Zero — swap any provider	Heavy framework lock-in	Heavy framework lock-in	Heavy OpenAI lock-in	Total OpenAI lock-in
Execution Guard	🤍🖤 Angel/Devil adversarial court	❌ None	❌ None	❌ None	❌ None
Code size	~15K LOC	500K+ LOC	~100K LOC	~100K LOC	Closed
Cost Transparency	✅ Token cost per message	❌ None	❌ None	❌ None	❌ None
Self-Evolution	✅ Learn skills + optimize	❌ None	❌ None	❌ None	❌ None
Auto-Heal	✅ 3-layer ModuleNotFoundError auto-fix	❌ None	❌ None	❌ None	❌ None
Multi-Platform Bot	Telegram / Discord / Slack / Signal	❌ None	❌ None	❌ None	❌ None
Setup	`pip install` + `baw --setup`	Complex chains	Complex setup	Multiple installs	API-dependent
License	MIT	MIT	MIT	MIT (older)	Proprietary

🔄 完全獨立 (Full Independence)

BAW v1.18.0 係一個完全獨立嘅 Agent Platform — 唔需要第二個系統介入設定或 setup。

Phase	能力	Tools
1 — Code Management	Git commit/push/build/restart via self-evolution	self-evolve pipeline
2 — Self Operation	System health, diagnostics, cron scheduler, auto-cleanup	`--doctor`, cron jobs
3 — Self Knowledge	SOUL.md, ARCHITECTURE.md, capability discovery	`--capabilities`, `--learn-skill`
4 — Self Extension	LLM-generated tools, auto-register, smoke test	`--learn-skill`, tool registry
5 — Self Hosting	install.sh bootstrap on any Linux, Bare metal systemd deployment	install.sh, systemd

⚡ One-Line Install

curl -fsSL https://raw.githubusercontent.com/cornreform/baw-agent-platform/main/install.sh | bash

📋 Step-by-Step (Manual)

# 1. Clone the repo
git clone https://github.com/cornreform/baw-agent-platform.git ~/BAW
cd ~/BAW

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up config
mkdir -p ~/.baw
cp SOUL.md ~/.baw/
cp CAPABILITIES.md ~/.baw/
cp config.sample.yaml ~/.baw/config.yaml

# 5. Install CLI wrapper (so 'baw' works from anywhere)
sudo tee /usr/local/bin/baw << '''EOF'''
#!/bin/bash
BAW_DIR="${BAW_HOME:-$HOME/BAW}"
cd "$BAW_DIR" || exit 1
export PYTHONPATH="$BAW_DIR:$PYTHONPATH"
# Route subcommands to Rich CLI, flags to old script
case "${1:-}" in
  ""|chat|tui-chat|status|models|config|router|soul|logs|dashboard|setup|memory|todo|tools|sessions|evolve|court|skill|restart|rebuild|self-test|preflight)
    exec "$BAW_DIR/venv/bin/python3" -m cli.main "$@" ;;
  *)
    exec "$BAW_DIR/venv/bin/python3" "$BAW_DIR/baw" "$@" ;;
esac
EOF
sudo chmod 755 /usr/local/bin/baw

# 8. Run setup wizard (configures API keys, model, Telegram token)
baw --setup

# 9. Start BAW
systemctl --user enable --now baw

📖 English

What is BAW?

BAW (Black And White) is an agent platform built entirely from scratch — no LangChain, no AutoGPT, no vendor framework. Named after two dogs (black & white), it embodies the core philosophy of 🤍 Angel (executor) vs 🖤 Devil (opposition) courtroom-style adversarial debate.

We built BAW for our own use — an AI agent platform that combines multi-model LLM orchestration with a built-in adversarial court system that reviews every action before execution. Every model call, tool invocation, and file write runs through an Angel/Devil debate before anything happens. It is not a framework wrapper; it is an autonomous LLM agent platform built from scratch, designed to run independently without vendor lock-in or external dependencies. If that sounds useful to you, you are welcome to use it too.

🚀 Quick Start

# Install
git clone https://github.com/cornreform/baw-agent-platform.git
cd baw-agent-platform
pip install -r requirements.txt
ln -sf $PWD/baw ~/.local/bin/baw

# Interactive setup wizard (英文)
baw --setup

# Or manually add an API key
echo "STEPFUN_API_KEY=***" >> ~/.baw/.env

# ✨ Go!
baw "list files in current directory"
baw --doctor           # Health check
baw --update           # Pull latest + restart service
baw                    # Interactive Chat mode

💡 First time?
Run baw --setup — it walks through Telegram token, default model, API keys, auto-configures providers + STT + TTS + vision.
Plan selection: setup asks about your plan type (standard / step-plan / code-plan / etc.) — never hardcodes endpoints.

💻 CLI Demo

$ baw --version
BAW (Black And White) Agent Platform v1.18.0
Commit: 807a933 (v1.18.0)
Home: /app
Architecture: self-improving loop with Angel/Devil adversarial court

$ baw --help
🖤  BAW CLI — Black And White Agent Platform

  All commands run as systemd user service.
  Pass --help to see full command reference.

  Quick start:
    baw              # Interactive chat
    baw tui-chat     # Full-screen TUI chat
    baw dashboard    # Live dashboard
    baw status       # Health overview
    baw --help       # Full command reference (inside container)

🔧 Prerequisites

Requirement	Check / Install
Python 3.11+	`python3 --version` — if missing: `brew install python@3.12` (macOS) or `sudo apt install python3.12` (Linux)
Git	`git --version` — if missing: `brew install git` (macOS) or `sudo apt install git` (Linux)
pip	`python3 -m pip --version` — if missing: `python3 -m ensurepip --upgrade`
~/.local/bin in PATH	`echo $PATH` should include `~/.local/bin`

🤖 One-Command Install

# 1. Clone
git clone https://github.com/cornreform/baw-agent-platform.git ~/BAW
cd ~/BAW

# 2. Venv + deps
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 3. Config
mkdir -p ~/.baw
cp SOUL.md ~/.baw/
cp CAPABILITIES.md ~/.baw/
cp config.sample.yaml ~/.baw/config.yaml

# 4. Fix symlink
ln -sf ~/BAW ~/baw

# 5. Create service
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/baw.service << '''EOF'''
[Unit]
Description=BAW Agent Platform (Bare Metal)
After=network.target
[Service]
Type=simple
ExecStart=%h/BAW/venv/bin/python3 %h/BAW/baw-bot --config %h/.baw/config.yaml
Restart=always
RestartSec=5
WorkingDirectory=%h/BAW
EnvironmentFile=%h/.baw/.env
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload

# 6. Install CLI wrapper
sudo tee /usr/local/bin/baw << '''EOF'''
#!/bin/bash
BAW_DIR="${BAW_HOME:-$HOME/BAW}"
cd "$BAW_DIR" || exit 1
export PYTHONPATH="$BAW_DIR:$PYTHONPATH"
# Route subcommands to Rich CLI, flags to old script
case "${1:-}" in
  ""|chat|tui-chat|status|models|config|router|soul|logs|dashboard|setup|memory|todo|tools|sessions|evolve|court|skill|restart|rebuild|self-test|preflight)
    exec "$BAW_DIR/venv/bin/python3" -m cli.main "$@" ;;
  *)
    exec "$BAW_DIR/venv/bin/python3" "$BAW_DIR/baw" "$@" ;;
esac
EOF
sudo chmod 755 /usr/local/bin/baw

# 7. Setup wizard
baw --setup

# 8. Start
systemctl --user enable --now baw

🎯 Core Features

Feature	Description
⚖️ Angel/Devil Court	Devil speaks first with ZERO execution power. Angel listens then acts. Devil score > Angel → STOP
🧠 Never Surrender	Fail → retry → replan → rollback. Exhausts 6 strategies before reporting
🔌 Protocol-agnostic LLM	OpenAI / Anthropic / Google protocols. One-line config switch, built-in cost tracking
⚙️ 3 Execution Modes	Quick (fastest) / Hybrid (balanced) / Tight (full court+plan+verify)
🗣️ 6 Tone Profiles	casual / business / teaching / client-doc / ot-rt / stepwise
📝 Self-Learning Skills	`--learn-skill` auto-analyzes and generates YAML skill
🔄 Cron Scheduler	Cron-expression scheduled tasks, 60s background daemon
📁 Background Tasks	`--delegate` runs in background, main terminal freed instantly
🐙 GitHub Integration	issues / PRs / CI / repos directly from CLI
🔍 Open Search Provider	Built-in DuckDuckGo (free), pluggable upgrade
💾 Multi-Layer Memory Network	JSONL persistent store + edges.json graph (Jaccard 2-hop) + auto-scoring (access boost + time decay) + auto-compression (group similar → summarize)
🧬 Self-Evolution	3-layer learning: behavior tracking → pattern detection → auto-optimize
🤖 Agent Delegation	Main brain decomposes tasks → sub-agents execute → synthesises
🔄 Hot Reload	`/reload` reloads tools/config/SOUL without restarting
🎙️ Voice STT	Telegram voice auto-detected: auto-probes OpenAI / SSE protocols, local faster-whisper fallback
🔧 Tool Self-Config	BAW discovers & registers its own CLI tools
🛡️ 3-Level Permission Engine	High (block) / Medium (warn) / Low (allow)
🗺️ Route Plan Execution	Multi-step plan with 60s timeout + anti-stuck skip
🎯 Per-Task Model Routing	keyword matching routes sub-agents to optimal models
🏛️ Tribunal Consensus	Multi-model courtroom — judges evaluate independently, Chief Justice unifies verdict
🧪 Real-World Validator	Zero-mock validation — real API calls, real file writes, real execution verification
🧘 Self-Evolution	4-phase learning: behavior tracking → health monitor → auto-fix → pattern optimization
📊 HTML Dashboard	`--board` generates dark-themed system dashboard
📁 File History + Auto Git	Every write logged with SHA256 + auto commit
👨‍⚕️ Doctor Health Check	`--doctor [--fix]` — validate config, deps, disk, API keys
🔄 Self-Update	`--update` — git pull + restart
📦 Backup & Restore	`--backup` / `--restore` — config, .env, memory, sessions
📎 Auto MEDIA Delivery	Detects generated files in output, auto-sends via MEDIA: tag — agent never says 'can't attach'
🔍 Complete Model Discovery	Auto-probes multiple endpoint paths (/v1/models) to discover ALL provider models, dedup across URLs
🆓 DuckDuckGo Fallback	Free built-in search provider via ddgs — no API key, out-of-box, fallback for any configured provider
👤 Profile Management	`--profile-*` — isolated instances with independent configs
🔬 Diagnostics	`--diagnostics` — system debug info dump
🔐 Reset	`--reset` — factory reset with confirmation
🐚 Shell Completion	`--completion bash\|zsh` — tab completion

Plan-Based Endpoint Selection

BAW asks about your plan type when adding API keys. Never hardcodes endpoints:

Provider	Plans	Base URL
Stepfun	Standard / Step Plan / China	`api.stepfun.ai/v1` / `step_plan/v1` / `stepfun.com/v1`
Kimi/Moonshot	Standard / Code Plan	`api.moonshot.ai/v1`
MiniMax	Standard / Subscription	`api.minimax.io/v1`

⚙️ Full Command Reference

# Core Agent
baw "prompt"                     # Run agent (single-shot)
baw                              # Interactive Chat mode
baw --mode quick/hybrid/tight    # Execution mode
baw --tone <profile>             # Tone override
baw --model <id>                # Model override
baw --verbose                    # Verbose output + cost
baw --dry-run                    # Dry run (no changes)
baw --btw "question"             # Quick LLM question

# Background Tasks
baw --delegate "task"            # Background task
baw --task-id <id>              # Check task status
baw --tasks                      # List background tasks
baw --task-cancel <id>          # Cancel background task

# Setup & Config
baw --setup                      # Interactive setup wizard (英文)
baw --cfg list                   # Show all settings
baw --cfg get <key>             # Query a setting
baw --cfg set <key> <value>     # Change immediately
baw --cfg edit                   # Open in $EDITOR
baw --cfg path                   # Show config path
baw --cfg env-path               # Show .env path
baw --cfg check                  # Validate required sections

# Health & Maintenance
baw --doctor                     # Health check
baw --doctor --fix               # Health check + auto-repair
baw --update                     # Pull latest + restart service
baw --version                    # Version + build info
baw --diagnostics                # System debug info
baw --logs [N]                   # View journal logs (N lines)
baw --reset                      # Factory reset

# Memory & Sessions
baw --remember "text"            # Save memory
baw --search "query"             # Search memory
baw --memory-stats               # Memory store statistics
baw --dream                      # Self-curation

# Profiles & Backups
baw --profile-list               # List profiles
baw --profile-create <name>     # Create profile
baw --profile-use <name>        # Switch profile
baw --profile-delete <name>     # Delete profile
baw --backup                     # Backup all data
baw --restore [path]             # Restore from backup

# Skills
baw --skill-list                 # List skills
baw --skill-run <name>          # Run a skill
baw --learn-skill "desc"         # Self-learn skill from description
baw --learn-url <url>           # Learn skill from URL

# Integrations
baw --gh issues|prs|ci|repos     # GitHub operations
baw --board                      # HTML Dashboard
baw --search-provider list|test  # Search provider mgmt
baw --schedule-list|add|rm       # Schedule management
baw --completion bash|zsh        # Shell completion

# Tools
baw --tools-list                 # List registered tools
baw --status                     # System status

🏗️ Architecture

baw/                        ← Code repo
├── baw                     CLI entrypoint (Python)
├── baw-bot                 Bot daemon entrypoint
├── core/                   Core modules
│   ├── loop.py             Agent loop (plan → execute → report)
│   ├── llm.py              Multi-protocol LLM abstraction
│   ├── adversarial.py      Angel/Devil dual-soul court
│   ├── tools.py            Tool registry
│   ├── permission.py       3-level permission engine
│   ├── memory.py           JSONL memory + scoring
│   ├── fact_checker.py     3-mode fact verification
│   ├── tone.py             Tone profiles
│   ├─── scheduler.py        Cron scheduler daemon
│   ├─── tribunal.py         Tribunal consensus engine
│   ├─── validator.py        Real-world validator (zero-mock)
│   ├─── test_runner.py      Telegram test suite
│   ├─── watchdog.py         Health monitor + emergency cleanup
│   ├─── skills.py           YAML skill system
│   ├─── learn.py            Self-learning skills
│   ├─── board.py            HTML Dashboard generator
│   ├─── task_manager.py     Async task manager
│   ├─── github.py           GitHub integration
│   ├─── search.py           Open search provider registry
│   ├─── setup.py            Setup wizard + Config CLI
│   ├─── commands.py         Slash commands
│   ├─── display.py          Step display formatter
│   ├─── dream.py            Weekly self-curation + self-evolution
│   ├─── evolve.py           3-layer self-evolution engine
│   ├─── checkpoint.py       Checkpoint / rollback
│   └─── degradation.py      Tool degradation chains
│   ├── file_history.py     File SHA256 history
│   ├── autosave.py         Auto git commit
│   ├── render.py           HTML renderer
│   ├── verifier.py         Per-step LLM verification
│   ├── doctor.py           Health check (--doctor)
│   ├── update.py           Self-update + version
│   ├── backup.py           Backup & restore
│   ├── profile.py          Profile management
│   └── diagnostics.py      System diagnostics
├── tools/                  Built-in tools
│   ├── bash.py             Shell execution
│   ├── read_file.py        File reading
│   ├── write_file.py       File writing
│   ├── web_search.py       Web search
│   ├── web_extract.py      Web content extraction
│   ├── search_files.py     Codebase search (ripgrep)
│   ├── patch.py            Targeted find-replace editing
│   ├── memory.py           Memory read/write/search
│   ├── todo.py             Task list management
│   ├── delegate_task.py    Sub-agent delegation
│   ├── vision.py           Image analysis (MiniMax)
│   ├── browser.py          Web automation (stub)
│   ├── image_generate.py   AI image generation (stub)
│   ├── tts.py              Text-to-speech (MiniMax)
│   └── execute_code.py     Python sandbox (stub)
├── config.yaml             Default config
├── SETUP.md                First-install quickstart
├── SOUL.default.md         Template SOUL.md for new profiles
└── docs/                   GitHub Pages documentation

~/.baw/                     ← User data directory
├── config.yaml             User config
├── SOUL.md                 Soul / behaviour rules
├── ORCHESTRATOR.md         Sub-agent optimization rules
├── .env                    API keys
├── memory/store.jsonl      Memory storage
├── skills/*.yaml           Custom skills
├── tasks/                  Background task output
├── sessions/               Session transcripts
├── backups/                Backup archives
└── profiles/               Multi-profile directories

🔧 Configuration

# Interactive setup wizard (recommended for first time)
baw --setup

# Real-time Config CLI
baw --cfg list                    # Show all settings
baw --cfg get model.default       # Query a setting
baw --cfg set capabilities.stt.method auto-asr
baw --cfg set capabilities.tts.model stepaudio-2.5-tts
baw --cfg edit                    # Open in $EDITOR
baw --cfg check                   # Validate required sections

📡 Multi-Platform Messaging

BAW connects to messaging platforms via the baw-bot daemon:

Platform	Status	Setup
📱 Telegram	✅ Full (voice STT, TTS, images)	`@BotFather` → token → `baw-bot`
💬 Discord	✅ Full support	Discord Developer Portal → token → prefix
💚 Slack	✅ Socket Mode (no public URL)	Slack API → bot + app token
📢 Signal	⚙️ signal-cli required	`signal-cli` daemon + config
💚 WhatsApp	⚙️ Cloud/Business API	Meta Developer account → webhook
🧩 Matrix	✅ Full support	Any Matrix account + homeserver

# Start all configured connectors
baw-bot

# Start specific platform
baw-bot --platform telegram
baw-bot --platform discord
baw-bot --platform slack

# List available connectors
baw-bot --list

# Quick setup with CLI token
baw-bot --token "YOUR_TELEGRAM_TOKEN"

Platform Quick Setup

📱 Telegram

Message @BotFather on Telegram → /newbot
Copy the token (looks like 123456:ABC-DEF...)
Run baw --setup → select Telegram → paste token
Start: baw-bot

💬 Discord

Go to Discord Developer Portal → New Application → Bot
Enable "Message Content Intent"
Copy Bot Token
Run baw --setup → select Discord → paste token → set prefix
Invite bot to your server with bot + Send Messages scopes
Start: baw-bot --platform discord

💚 Slack (Socket Mode)

Go to Slack API → Create New App → From scratch
Enable Socket Mode → Generate App-Level Token (scope: connections:write)
OAuth & Permissions → Add Bot Token Scopes: chat:write, app_mentions:read, im:history
Install to workspace → copy Bot User OAuth Token (xoxb-...)
Basic Info → copy App-Level Token (xapp-...)
Run baw --setup → select Slack → paste both tokens
Start: baw-bot --platform slack

🧩 Matrix

Register account on any homeserver (e.g. matrix.org)
Get access token: Settings → Help & About → Access Token
Run baw --setup → select Matrix → enter homeserver + username + token
Start: baw-bot --platform matrix

📢 Signal

Install signal-cli: https://github.com/AsamK/signal-cli
Register: signal-cli -u +1555... register
Verify: signal-cli -u +1555... verify <code>
Start daemon: signal-cli -u +1555... daemon
Run baw --setup → select Signal → enter phone number
Start: baw-bot --platform signal

💚 WhatsApp

Go to Meta Developers → Create App → WhatsApp → Setup
Copy Phone Number ID and Permanent Access Token
Configure webhook endpoint (requires public URL + reverse proxy)
Run baw --setup → select WhatsApp → paste token + phone ID
Start: baw-bot --platform whatsapp

📖 繁體中文

BAW 係咩？

BAW (Black And White) 係一套由零開始構建嘅 Agent Platform，唔依賴 LangChain、AutoGPT、或任何現有 framework。系統嘅核心哲學：🤍 Angel（執行者） vs 🖤 Devil（反對派） 嘅法庭式對抗。

🚀 Quick Start

# 安裝
git clone https://github.com/cornreform/baw-agent-platform.git
cd baw-agent-platform
pip install -r requirements.txt
ln -sf $PWD/baw ~/.local/bin/baw

# 互動式設定精靈（英文界面）
baw --setup

# 或直接加 API Key
echo "STEPFUN_API_KEY=*** >> ~/.baw/.env

# ✨ 即刻用！
baw "list files in current directory"
baw --doctor           # 健康檢查
baw --update           # 更新 + 重啟服務
baw                    # 互動式 Chat 模式

💡 第一次用？
執行 baw --setup — 設定精靈會逐步行：Telegram token、default model、API keys、自動配置 provider + STT + TTS + vision。
Plan 選擇： setup 會問你用緊邊個 plan（標準 / step-plan / code-plan 等），唔會 hardcode endpoint。

🔧 系統要求

要求	檢查／安裝
Python 3.11+	`python3 --version` — macOS: `brew install python@3.12` / Linux: `sudo apt install python3.12`
Git	`git --version` — macOS: `brew install git` / Linux: `sudo apt install git`
pip	`python3 -m pip --version`
~/.local/bin in PATH	`echo $PATH` 應該包含 `~/.local/bin`

🎯 核心特色

特色	說明
⚖️ Angel/Devil 法庭	Devil 永遠先發言，零執行權限；Angel 聽完再行。Devil 分數 > Angel → STOP
🧠 永不放棄哲學	失敗 → retry → replan → rollback。6 種策略用盡先上報
🔌 協議無關 LLM	OpenAI / Anthropic / Google 協議通吃。一行 config 轉模型
⚙️ 三種執行模式	Quick（最快）/ Hybrid（平衡）/ Tight（完整 court+plan+verify）
🗣️ 6 種語氣 Profile	casual / business / teaching / client-doc / ot-rt / stepwise
📝 自我學習技能	`--learn-skill` 自動分析拆解生成 YAML skill
🔄 Scheduler 排程	Cron 表達式定時任務，60s 背景 daemon
📁 背景 Task	`--delegate` 背景執行，主 terminal 即時 free
🐙 GitHub 整合	issues / PRs / CI / repos 直接操作
🔍 開放 Search Provider	內置 DuckDuckGo（免費），可 pluggable 升級
💾 統一記憶	JSONL append‑only + edges.json 圖譜 + 2-hop 關聯
🏛️ Tribunal 共識引擎	多模型法庭 — 法官獨立判決，首席法官統一意見
🧪 現實驗證器	零 mock — 真實 API 呼叫、真實寫檔、真實執行驗證
🧘 自我進化	4 階段學習：行為追蹤 → 健康監控 → 自動修復 → 模式優化
🤖 Agent Delegation	主腦拆任務 → 子 agent 執行 → 綜合報告
🎙️ Voice STT	Telegram 語音自動檢測，auto-probe OpenAI/SSE 協議，本地 faster-whisper fallback
👨‍⚕️ 健康檢查	`--doctor [--fix]` — config、依賴、Disk、API key 全面檢查
🔄 自更新	`--update` — git pull + 重啟服務 + 重啟
📦 備份還原	`--backup` / `--restore` — 全部資料一鍵打包
👤 Profile 管理	`--profile-*` — 獨立設定、記憶、session 隔離
🔐 出廠重置	`--reset` — 確認後 wipe 全部數據

Plan-Based Endpoint 選擇

Set up 時會問你用緊邊個 plan，唔會 hardcode endpoint：

Provider	Plans	Base URL
Stepfun	標準 / Step Plan / 內地版	`api.stepfun.ai/v1` / `step_plan/v1` / `stepfun.com/v1`
Kimi/Moonshot	標準 / Code Plan	`api.moonshot.ai/v1`
MiniMax	標準 / 付費計劃	`api.minimax.io/v1`

⚙️ 完整指令一覽

# Agent 核心
baw "prompt"                     # 執行 agent（單句模式）
baw                              # 互動式 Chat 模式
baw --mode quick/hybrid/tight    # 執行模式
baw --tone <profile>             # 語氣 override
baw --model <id>                # 模型 override
baw --btw "question"             # 快速一問一答

# Set up & Config
baw --setup                      # 互動設定精靈（英文）
baw --cfg list                   # 顯示所有設定
baw --cfg get <key>             # 查設定
baw --cfg set <key> <value>     # 即時修改
baw --cfg edit                   # 用編輯器改 config
baw --cfg check                  # 驗證必要設定

# 健康維護
baw --doctor                     # 健康檢查
baw --doctor --fix               # 檢查 + 自動修復
baw --update                     # 更新 + 重啟服務
baw --diagnostics                # 系統除錯資訊
baw --logs [N]                   # System logs
baw --version                    # 版本資訊
baw --reset                      # 出廠重置

# 記憶與 Session
baw --remember "text"            # 儲存記憶
baw --search "query"             # 搜尋記憶
baw --memory-stats               # 記憶統計
baw --dream                      # 自我整理

# Profile 與備份
baw --profile-list               # 列出 profiles
baw --profile-create <name>     # 建立 profile
baw --profile-use <name>        # 切換 profile
baw --backup                     # 備份所有數據
baw --restore [path]             # 從備份還原

# Skills
baw --skill-list                 # 列出 skills
baw --learn-skill "desc"         # 自我學習技能
baw --learn-url <url>           # 從 URL 學技能

# 整合功能
baw --gh issues|prs|ci|repos     # GitHub 操作
baw --board                      # HTML Dashboard
baw --schedule-list|add|rm       # 排程管理
baw --completion bash|zsh        # Shell 補全
baw --tools-list                 # 列出 tools

🏗️ 架構

baw/                        ← Code repo
├── baw                     CLI entry point（Python）
├── baw-bot                 Bot daemon entry point
├── core/                   核心模組
│   ├── loop.py             Agent loop（plan → execute → report）
│   ├── llm.py              多協議 LLM abstraction
│   ├── adversarial.py      Angel/Devil 雙魂法庭
│   ├── tools.py            Tool registry
│   ├── permission.py       三級權限引擎
│   ├── memory.py           JSONL 記憶 + 評分
│   ├── fact_checker.py     事實查證（三級）
│   ├─── tone.py             語氣 profile
│   ├─── scheduler.py        Cron 排程 daemon
│   ├─── tribunal.py         Tribunal 共識引擎
│   ├─── validator.py        現實驗證器（零 mock）
│   ├─── test_runner.py      Telegram 測試套件
│   ├─── watchdog.py         健康監控 + 緊急清理
│   ├─── skills.py           YAML skill 系統
│   ├─── learn.py            自我學習技能
│   ├─── board.py            HTML Dashboard
│   ├─── task_manager.py     背景 Task 管理
│   ├─── github.py           GitHub 整合
│   ├─── search.py           開放 search provider
│   ├─── setup.py            設定精靈 + Config CLI
│   ├─── doctor.py           健康檢查 (--doctor)
│   ├─── update.py           自更新 + 版本
│   ├── backup.py           備份還原
│   ├── profile.py          Profile 管理
│   ├── diagnostics.py      系統除錯
│   ├── commands.py         Slash commands
│   ├── display.py          步驟顯示格式化
│   └── dream.py            每週自我整理
├── tools/                  內置工具
│   ├── bash.py             命令執行
│   ├── read_file.py        讀檔案
│   ├── write_file.py       寫檔案
│   ├── web_search.py       Web 搜尋
│   ├── patch.py            精準檔案編輯
│   └── ...（共 15 個 tools）
├── config.yaml             預設配置
├── SETUP.md                首次安裝指南
├── SOUL.default.md         Template SOUL.md
└── docs/                   GitHub Pages 文檔

🖥️ CLI Reference

BAW ships with a full-featured CLI. Just type baw in your terminal.

🚀 Quick Start

baw                  # → Direct interactive chat (default)
baw --help           # → Full help with examples
baw --doctor         # → Health check
baw --setup          # → Guided setup wizard

📋 All Commands

Command	Description
`baw --doctor [--fix]`	🩺 Health check + auto-repair
`baw --setup`	🎯 Interactive setup wizard
`baw --update`	🔄 Pull latest + restart service
`baw --version`	📌 Version, commit, branch, Commit SHA
`baw --backup`	💾 Backup config, .env, memory, sessions
`baw --restore [path]`	📂 Restore from backup
`baw --profile-list`	👤 List profiles
`baw --profile-create <name>`	👤 Create profile
`baw --diagnostics`	🔬 System debug info
`baw --logs [N]`	📜 Tail System logs
`baw --reset`	🔐 Factory reset
`baw --cfg list`	⚙️ Show all settings
`baw --cfg set <k> <v>`	⚙️ Change setting
`baw --cfg edit`	⚙️ Open in editor
`baw --cfg check`	⚙️ Validate config
`baw --board`	📊 Generate HTML system dashboard
`baw --delegate <task>`	👥 Background task delegation
`baw --mode [quick\|hybrid\|tight]`	⚡ Set execution mode
`baw --tone [casual\|business\|...]`	🎭 Set response tone
`baw --learn-skill <topic>`	📖 Auto-generate YAML skill
`baw --tribunal <question>`	🏛️ Multi-model consensus
`baw --validate [subcmd]`	🧪 Real-world validation

🙏 Acknowledgments / 鳴謝

BAW 嘅開發受以下開源項目同平台啟發，衷心感謝佢哋嘅貢獻。我哋唔想隱瞞任何參考過嘅項目 — 每一樣都為 BAW 帶嚟咗有價值嘅靈感：

Project / 項目	Author / 作者	啟發咗我哋嘅功能
🧞 Hermes Agent	Nous Research	BAW 本身運行喺 Hermes Agent 之上，用嘅係 Hermes 嘅 profile system、tool execution framework、skills 系統、cron scheduler。我哋嘅 MasterSkills routing 概念亦受 Hermes 嘅 skills loading 機制啟發。Hermes 係我哋嘅 foundation layer。
🦞 OpenClaw	OpenClaw Team	OpenClaw 嘅 agent skill system（SKILL.md router + reference files pattern）直接啟發咗 BAW 嘅 MasterSkills routing + references 設計。Agent Reach 嘅 SKILL.md 三層 router 亦係受 OpenClaw 啟發。
🕵️ Agent Reach	Neo Reid (Panniantong)	本地 HTML→Markdown 提取理念、RSS feed 閱讀、platform health doctor 概念。Agent Reach 嘅「每個 platform 有 preferred + fallback backend」routing 理念啟發咗我哋嘅 web_extract 多層 fallback 設計。37K ⭐ 實至名歸。
📖 Jina AI Reader	Jina AI (acquired by Elastic)	ReaderLM-v2 嘅 HTML→Markdown 轉換理念啟發咗我哋用本地 html2text 實現類似效果。雖然我哋最終選擇咗完全本地方案（唔用 r.jina.ai API），但 Jina Reader 證明咗 clean extraction 嘅價值同 token 節省潛力（75-82%）。
🏢 Clay	Clay	Waterfall Enrichment pattern（multi-provider lookup with circuit-breaker）啟發咗我哋嘅多源數據檢索思路。雖然我哋嘅實作最終用 delegate_task + web_extract 取代咗專用 enrichment engine，但 Clay 嘅架構理念（sequential provider fallback、circuit-breaker pattern）係重要嘅參考。

🧰 Core Libraries & Tools / 核心函式庫

以下開源函式庫係 BAW 核心功能嘅技術基礎，唔係設計靈感，但冇咗佢哋 BAW 就唔會 work：

Library / 函式庫	Author / 作者	功能 / 用途
html2text	Alir3z4 (based on Aaron Swartz's original)	本地 HTML→Markdown 轉換引擎 — web_extract tool 嘅核心
feedparser	Kurt McKee	RSS/Atom feed 解析 — rss_feed tool 嘅基礎
faster-whisper	Guillaume Klein / SYSTRAN	本地語音識別引擎（CTranslate2-based Whisper）— 本地 STT，毋須外部 API
edge-tts	rany2	本地免費 TTS（Microsoft Edge TTS 封裝）— BAW 預設 TTS provider，支援粵語
Textual	Will McGugan / Textualize	TUI 框架 — powers baw --board dashboard 同 baw --tui-chat 互動界面
Rich	Will McGugan / Textualize	Terminal 格式化 — powers 所有 CLI table/panel/syntax highlight 輸出
MCP Python SDK	Anthropic	Model Context Protocol SDK — BAW 連接 MCP server 做 tool discovery
FastAPI	Sebastián Ramírez (tiangolo)	Web framework — Telegram webhook mode 嘅 async transport layer
Uvicorn	Encode / Tom Christie	ASGI server — 執行 FastAPI webhook server
🗺️ OpenStreetMap / Overpass API	OpenStreetMap Foundation	免費地理數據源 — BAW 嘅 geospatial query 同 location/restaurant search 基礎
signal-cli	AsamK	Signal 通訊 CLI — BAW 嘅 Signal messaging platform 整合依賴

BAW 本身都係 MIT License 開源項目 — 歡迎參考、改進、分享。我哋嘅理念係：如果一個開源項目幫過我哋，我哋就有責任公開鳴謝，並且將同樣嘅 open 精神傳遞落去。

📝 Changelog

v1.18.0 — 自我修復依賴 + 穩定 Telegram 輪詢 (2026-06-24)

🛡️ 自我修復依賴系統 — 3 層 safety net：tool 執行 auto-install、connector import wrapper、startup main() wrapper，ModuleNotFoundError 自動 pip install + retry
🔗 Telegram 409 Conflict 根因修復 — 刪除危險嘅 logOut() API，connect() 加 resilient retry + close() + deleteWebhook
🐳 Dockerfile 全面 dep baking — html2text, websocket-client, croniter, requests, beautifulsoup4 baked in；chown 權限 fix 令非 root pip install 可行
🧠 MASTERSKILLS.md 行為規則擴充 — rule #4 自動修復優先、rule #5 Error 要 actionable、NEVER call logOut()

v1.14.14 — 完全本地 web_extract + AI Research + RSS tools

web_extract 重寫：html2text + BeautifulSoup 本地提取，68-78% token 節省，零外部 API
ai_research — 新 built-in tool：URL + question → 結構化 JSON research
rss_feed — 新 built-in tool：feedparser 本地 RSS/Atom feed 閱讀
鳴謝：Agent Reach (Panniantong) 啟發咗本地 extraction + RSS 方案
鳴謝：Jina AI Reader 啟發咗 HTML→Markdown 轉換概念
鳴謝：Clay 啟發咗 waterfall enrichment 多源查詢思路

Version sync: all files now report v1.18.0
Community health files: CONTRIBUTING.md + issue templates added
README: GitHub stars/last-commit badges, CLI demo section, humility-toned description
CHANGELOG.md: v1.8-v1.14 entries appended with detailed content
GitHub: repo description + topics + releases (v1.8-v1.14) all updated

v1.12.0

Anti-Stuck mechanism — route replan on execution deadlock
Route Plan Engine — step-by-step plan with rollback support
Telegram bot deep integration with async message queue

v1.10.0

Angel/Devil Dual-Soul Court — multi-model adversarial debate
Tribunal consensus engine — multi-model court judgment
Real-world validator — zero mock, real API + file validation
Hallucination Guard — detect & block fake execution promises

v1.8.0

Direct Execution Shortcuts — bypass LLM for common commands
Setup wizard rewrite — API key live test, plan auto-detect
CLI install flow overhaul — auto uv, Python, PATH setup

Name		Name	Last commit message	Last commit date
.github		.github
REFERENCES		REFERENCES
backups		backups
bin		bin
cli		cli
core		core
data		data
deploy		deploy
docs		docs
knowledge		knowledge
references		references
scripts		scripts
search_providers		search_providers
skills		skills
tests		tests
tools		tools
vault		vault
.codebase_cache.json		.codebase_cache.json
.coverage		.coverage
.gitignore		.gitignore
.schedule.yaml		.schedule.yaml
ARCHITECTURE.md		ARCHITECTURE.md
BAW-INTRODUCTION.html		BAW-INTRODUCTION.html
BAW_MASTERSKILLS.md		BAW_MASTERSKILLS.md
CAPABILITIES.md		CAPABILITIES.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
DEVGUIDE.md		DEVGUIDE.md
Dockerfile		Dockerfile
INDEX.md		INDEX.md
README.md		README.md
RELEASE-v0.11.md		RELEASE-v0.11.md
RELEASE-v0.12.md		RELEASE-v0.12.md
RELEASE-v0.13.md		RELEASE-v0.13.md
SETUP.md		SETUP.md
SOUL.default.md		SOUL.default.md
SOUL.md		SOUL.md
baw		baw
baw-bot		baw-bot
baw-bot.log		baw-bot.log
bawrun.py		bawrun.py
bench_3mode.py		bench_3mode.py
bench_plan_overhead.py		bench_plan_overhead.py
chart_bar.png		chart_bar.png
chart_generator.py		chart_generator.py
chart_line.png		chart_line.png
chart_pie.png		chart_pie.png
chart_sample.png		chart_sample.png
config.sample.yaml		config.sample.yaml
config.yaml		config.yaml
contract.docx		contract.docx
de_bens_moveis.pdf		de_bens_moveis.pdf
delegate_test.txt		delegate_test.txt
docker-compose.yml		docker-compose.yml
dog_adoption_channels_summary.md		dog_adoption_channels_summary.md
extract_docx.py		extract_docx.py
fusion_test.txt		fusion_test.txt
fusion_test2.txt		fusion_test2.txt
install.sh		install.sh
kg_curate.py		kg_curate.py
output.pptx		output.pptx
pptx_generator.py		pptx_generator.py
pytest.ini		pytest.ini
requirements.txt		requirements.txt
scan_report.html		scan_report.html
schedule.yaml		schedule.yaml
slide_content.json		slide_content.json
slide_content_input.py		slide_content_input.py
slide_content_test_20260609_124254.json		slide_content_test_20260609_124254.json
test_chart.png		test_chart.png
五菱添龍項目日程表.md		五菱添龍項目日程表.md

Latest commit

History

Folders and files

Repository files navigation

⚫ BAW — Black And White ⚪

⚔️ Why BAW? (vs The Alternatives)

🔄 完全獨立 (Full Independence)

⚡ One-Line Install

📋 Step-by-Step (Manual)

📖 English

What is BAW?

🚀 Quick Start

💻 CLI Demo

🔧 Prerequisites

🤖 One-Command Install

🎯 Core Features

Plan-Based Endpoint Selection

⚙️ Full Command Reference

🏗️ Architecture

🔧 Configuration

📡 Multi-Platform Messaging

Platform Quick Setup

📖 繁體中文

BAW 係咩？

🚀 Quick Start

🔧 系統要求

🎯 核心特色

Plan-Based Endpoint 選擇

⚙️ 完整指令一覽

🏗️ 架構

🖥️ CLI Reference

🚀 Quick Start

📋 All Commands

🙏 Acknowledgments / 鳴謝

🧰 Core Libraries & Tools / 核心函式庫

📝 Changelog

v1.18.0 — 自我修復依賴 + 穩定 Telegram 輪詢 (2026-06-24)

v1.14.14 — 完全本地 web_extract + AI Research + RSS tools

v1.12.0

v1.10.0

v1.8.0

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages