龍蝦新手指南：從零入門 AI Agent平臺(tái) 智能體生態(tài)

為什么選 AI Agent平臺(tái)？

它不賣云服務(wù)，不收訂閱費(fèi)，代碼全開源，能跑在你自己的筆記本、樹莓派甚至舊 Mac 上。支持 Claude、GPT、Ollama 本地模型，也能切到 Llama 3 或 Qwen 等開源權(quán)重——模型是你挑，不是它塞。

消息平臺(tái)接入實(shí)打?qū)崳篧hatsApp（通過 Termux 或 Webhook）、Telegram Bot API、Discord Gateway、Slack App、Line、飛書、釘釘……目前穩(wěn)定支持 32 個(gè)入口，不是“計(jì)劃支持”。

所有數(shù)據(jù)留在本地。聊天記錄、任務(wù)日志、配置文件，全在你硬盤上。config.yaml 里沒一行發(fā)出去，main.py 就不會(huì)連一次外網(wǎng)（除非你主動(dòng)配了遠(yuǎn)程模型）。

GitHub 31 萬 star 不是刷的——那是真實(shí)開發(fā)者每天在提 issue、寫插件、修 WebSocket 心跳超時(shí)、調(diào) Telegram webhook 路由。工程細(xì)節(jié)扎實(shí)：有重試機(jī)制、會(huì)話上下文隔離、多 bot 并行、失敗任務(wù)自動(dòng)歸檔。

如果你不想被廠商鎖死，又需要今天寫完腳本、明天就能用 WhatsApp 接客戶詢盤，AI Agent平臺(tái) 是少數(shù)幾個(gè)真能落地的選擇。

什么是 AI Agent平臺(tái)？

AI Agent平臺(tái) 是一個(gè)智能體運(yùn)行時(shí)（agent runtime），不是低代碼拖拽工具，也不是封裝好的 SaaS。它提供：

• 統(tǒng)一的消息總線：把不同平臺(tái)進(jìn)來的消息轉(zhuǎn)成標(biāo)準(zhǔn)結(jié)構(gòu)體
• 模型抽象層：換模型只需改 config 里一行 model: claude-3-haiku，不用動(dòng)業(yè)務(wù)邏輯
• 任務(wù)生命周期管理：?jiǎn)?dòng)、暫停、熱重載腳本、按需加載插件
• 原生 Python API：所有能力都通過 from ai-agent import * 暴露，不藏黑盒

舉個(gè)實(shí)際例子：
你寫一個(gè)函數(shù)，接收 Telegram 消息 → 提取訂單號(hào) → 查本地 SQLite 訂單表 → 生成物流狀態(tài)文本 → 發(fā)回 Telegram。整個(gè)鏈路里，AI Agent平臺(tái) 只管“怎么收”和“怎么發(fā)”，中間查庫、拼文案、調(diào)本地 Ollama，全由你控制。

它不替你思考，只幫你把想法快速變成可運(yùn)行的服務(wù)。

如何安裝和配置 AI Agent平臺(tái)？

1. 準(zhǔn)備工作

確認(rèn)系統(tǒng)已裝好：

• Python 3.8+（3.7 已棄用，部分 asyncio 特性不兼容）
• Git（用于拉代碼）
• pip（隨 Python 自帶，無需單獨(dú)裝）

檢查命令：

python --version  # 應(yīng)輸出 3.8.x 或更高
git --version
pip --version

沒裝？Python 去 python.org 下 macOS/Windows 安裝包；Linux 用戶用 apt install python3 git 或 brew install python git。

2. 克隆倉庫

git clone https://github.com/ai-agent/AI Agent平臺(tái).git
cd AI Agent平臺(tái)

注意：官方倉庫是 ai-agent/AI Agent平臺(tái)，不是 yourusername。fork 后再 clone 也行，但首次建議直接克隆主倉，避免同步問題。

3. 安裝依賴

pip install -r requirements.txt

requirements.txt 里包含核心依賴：httpx（異步 HTTP）、pydantic（配置校驗(yàn)）、watchfiles（熱重載）、各平臺(tái) SDK（如 python-telegram-bot）。如果報(bào)錯(cuò)缺 wheel，先 pip install wheel 再重試。

4. 配置 API 密鑰

編輯 config.yaml，填入你有的模型密鑰：

api_keys:
  openai: sk-xxx  # OpenAI
  anthropic: sk-ant-api03-xxx  # Anthropic
  ollama: http://localhost:11434  # 本地 Ollama 地址（不用密鑰）

?? 別把 config.yaml 提交到 GitHub。加進(jìn) .gitignore：

config.yaml
*.log
__pycache__/

5. 啟動(dòng) AI Agent平臺(tái)

python main.py

看到類似輸出即成功：

[INFO] Loaded 3 platforms: telegram, discord, whatsapp_web
[INFO] Model provider 'openai' ready (gpt-4o-mini)
[INFO] Agent runtime started on http://localhost:8000

此時(shí) AI Agent平臺(tái) 已監(jiān)聽平臺(tái)事件，但還沒定義任何任務(wù)——下一步才是讓它干活。

如何使用 AI Agent平臺(tái)？

1. 連接平臺(tái)

以 Telegram 為例，在 config.yaml 中添加：

telegram:
  token: 123456789:ABCdefGhIjKlmNoPqrStUvWxYz  # BotFather 給的 token
  chat_id: -1001234567890  # 群組 ID，私聊用用戶 ID（正數(shù)）

WhatsApp 需要額外步驟：用 whatsapp-web.js 啟動(dòng)瀏覽器實(shí)例，或配 Twilio。詳細(xì)見 docs/platforms/whatsapp.md。

2. 創(chuàng)建任務(wù)

新建 tasks/echo.py：

from ai-agent import TelegramBot

def handle_message(message):
    return f"收到：{message.text[:50]}...（自動(dòng)回復(fù)）"

bot = TelegramBot()
bot.on_message(handle_message)

AI Agent平臺(tái) 會(huì)自動(dòng)掃描 tasks/ 目錄下的 .py 文件，加載并注冊(cè) on_message 回調(diào)。不需要手動(dòng) bot.start() —— runtime 啟動(dòng)時(shí)自動(dòng)接管。

3. 運(yùn)行任務(wù)

保存文件后，AI Agent平臺(tái) 默認(rèn)啟用熱重載。你改完 echo.py，幾秒內(nèi)新邏輯就生效。
想手動(dòng)觸發(fā)重載，發(fā) /reload 給 Telegram Bot（需在 config 中開啟 admin 權(quán)限）。

測(cè)試：給 Bot 發(fā)一條消息，應(yīng)該立刻收到帶“自動(dòng)回復(fù)”的回執(zhí)。

驗(yàn)證安裝和配置

• 看日志：終端輸出 Loaded X platforms 和 Model provider Y ready 表示基礎(chǔ)通了
• 查連接：發(fā) /status 給 Telegram Bot（或訪問 http://localhost:8000/status），返回各平臺(tái)在線狀態(tài)
• 測(cè)閉環(huán)：發(fā)消息 → 看日志是否打印 Received message from @xxx → 看是否收到回復(fù)
• 斷網(wǎng)測(cè)試：拔網(wǎng)線，用本地 Ollama 模型跑任務(wù)——依然能工作，證明沒偷偷連云端

如果卡在某步，直接翻 logs/app.log，錯(cuò)誤堆棧比文檔更誠實(shí)。

常見問題

1. Telegram 收不到消息

• 檢查 token 是否復(fù)制完整（末尾 = 別漏）
• 確認(rèn) Bot 在群組里有“管理員”權(quán)限（至少要“能發(fā)消息”）
• 運(yùn)行 python -m ai-agent.platforms.telegram test 手動(dòng)驗(yàn)證 token

2. pip install 報(bào)編譯錯(cuò)誤（尤其 macOS M1/M2）

• 先 brew install libpq（PostgreSQL 依賴）
• 再 pip install --no-binary :all: psycopg2
• 或改用 pip install "psycopg2-binary>=2.9"

3. 任務(wù)腳本修改后不生效

• 確認(rèn)文件放在 tasks/ 目錄下（不是子目錄）
• 檢查文件名是否含非法字符（如空格、中文）
• 日志里搜 Reloaded task，沒這行說明沒被掃描到

下一步學(xué)習(xí)建議

• 讀 examples/ 目錄：里面有真實(shí)場(chǎng)景腳本——自動(dòng)歸檔飛書審批、解析郵件附件、定時(shí)推送 RSS
• 改 config.yaml 的 model 字段：切到 ollama:llama3，對(duì)比響應(yīng)速度和成本
• 加日志：在任務(wù)函數(shù)里寫 logger.info("訂單 %s 已處理", order_id)，日志自動(dòng)歸集到 logs/tasks.log
• 寫插件：參考 plugins/ 結(jié)構(gòu)，用 @plugin 裝飾器注入自定義功能（比如對(duì)接 MySQL）
• 看 PR 記錄：GitHub 上搜 label:good-first-issue，挑一個(gè)修——社區(qū)歡迎真實(shí)補(bǔ)丁，不是“Hello World”

文檔地址：

• GitHub 倉庫
• 中文快速上手
• docs/ 目錄下全是離線可用的 Markdown，git pull 就能更新