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

為什么選 AI Agent平臺？

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

消息平臺接入實打實：WhatsApp（通過 Termux 或 Webhook）、Telegram Bot API、Discord Gateway、Slack App、Line、飛書、釘釘……目前穩(wěn)定支持 32 個入口，不是“計劃支持”。

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

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

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

什么是 AI Agent平臺？

AI Agent平臺 是一個智能體運行時（agent runtime），不是低代碼拖拽工具，也不是封裝好的 SaaS。它提供：

• 統一的消息總線：把不同平臺進來的消息轉成標準結構體
• 模型抽象層：換模型只需改 config 里一行 model: claude-3-haiku，不用動業(yè)務邏輯
• 任務生命周期管理：啟動、暫停、熱重載腳本、按需加載插件
• 原生 Python API：所有能力都通過 from ai-agent import * 暴露，不藏黑盒

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

它不替你思考，只幫你把想法快速變成可運行的服務。

如何安裝和配置 AI Agent平臺？

1. 準備工作

確認系統已裝好：

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

檢查命令：

python --version  # 應輸出 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平臺.git
cd AI Agent平臺

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

3. 安裝依賴

pip install -r requirements.txt

requirements.txt 里包含核心依賴：httpx（異步 HTTP）、pydantic（配置校驗）、watchfiles（熱重載）、各平臺 SDK（如 python-telegram-bot）。如果報錯缺 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。加進 .gitignore：

config.yaml
*.log
__pycache__/

5. 啟動 AI Agent平臺

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

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

如何使用 AI Agent平臺？

1. 連接平臺

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

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

WhatsApp 需要額外步驟：用 whatsapp-web.js 啟動瀏覽器實例，或配 Twilio。詳細見 docs/platforms/whatsapp.md。

2. 創(chuàng)建任務

新建 tasks/echo.py：

from ai-agent import TelegramBot

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

bot = TelegramBot()
bot.on_message(handle_message)

AI Agent平臺 會自動掃描 tasks/ 目錄下的 .py 文件，加載并注冊 on_message 回調。不需要手動 bot.start() —— runtime 啟動時自動接管。

3. 運行任務

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

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

驗證安裝和配置

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

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

常見問題

1. Telegram 收不到消息

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

2. pip install 報編譯錯誤（尤其 macOS M1/M2）

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

3. 任務腳本修改后不生效

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

下一步學習建議

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

文檔地址：

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