《龍蝦新手指南》專欄文章：AI Agent平臺——讓AI自動化真正落地

為什么選擇AI Agent平臺？

AI Agent平臺 是一個國產開源 AI 自動化框架，目標很實在：在本地跑起來、能干活、不挑環境。

它不是玩具項目。所有功能都經過真實場景驗證，支持離線運行，跨平臺任務編排，原生兼容 WhatsApp、Telegram、Discord、Slack、GitHub、RSS 等 30+ 應用。模型層不綁定廠商——Claude、GPT-3.5/4、本地 LLM（如 Llama 3、Phi-3、Qwen2）都能按需調度，配置文件里切一下就行。

本地化部署的真實好處

• 數據不出設備：聊天記錄、文檔、截圖、日志全留在你自己的機器上，不上傳、不中轉、不緩存。
• 斷網照常工作：沒有網絡？沒關系。本地模型 + 本地消息隊列 + 本地規則引擎，整個流水線照跑。
• 硬件說了算：CPU、GPU、Apple Silicon 都能壓榨。模型量化、KV Cache 優化、批處理調度都開箱即用，不用改代碼。

AI Agent平臺 的核心功能

1. 跨平臺任務編排

AI Agent平臺 把不同平臺的 API 封裝成統一的動作接口。你寫一次邏輯，就能在多個平臺復用。

支持的平臺包括：

• 即時通訊：WhatsApp（通過 WWebJS）、Telegram（Bot API）、Discord（Gateway）
• 社交媒體：Twitter/X（v2 API）、Reddit（PRAW）、Mastodon（ActivityPub）
• 協作工具：Slack（Events API）、Microsoft Teams（Graph API）、Trello（REST）
• 開發與信息流：GitHub（Webhooks）、RSS（Feedparser）、Notion（API）

典型用法：

• 在 Telegram 群里監聽關鍵詞，自動轉發到 Slack 頻道并 @ 相關成員
• 監控 GitHub PR 評論，用本地小模型做代碼風格初篩，只把高風險評論推給 Reviewer
• 每天早 8 點從 RSS 抓取技術博客摘要，用 Qwen2-1.5B 生成中文簡報，發到 WhatsApp 工作群

2. 模型調度機制

AI Agent平臺 不預設“哪個模型最好”，而是提供一致的調用契約：

# 所有模型都遵循這個簽名
def infer(prompt: str, **kwargs) -> str:
    ...

實際支持：

• 遠程模型：Claude（Anthropic API）、GPT（OpenAI / Azure / Ollama 兼容端點）、Gemini（Google AI SDK）
• 本地模型：Transformers（pipeline 或 generate）、llama.cpp（GGUF）、Ollama（ollama run）、vLLM（HTTP API）
• 輕量模型：Sentence Transformers（嵌入）、FastChat（多輪對話管理）、LiteLLM（統一路由層）

調度策略可配：

• 按任務類型分發（例如：/summarize → 本地 Qwen2；/code-review → 遠程 Claude-3.5）
• 按負載降級（遠程超時 → 自動 fallback 到本地 Phi-3）
• 按 token 成本路由（短 prompt 走小模型，長 context 走大模型）

安裝與配置指南

1. 環境準備

確認系統滿足：

• OS：Linux（推薦 Ubuntu 22.04+）、macOS（13+）、Windows（WSL2 或原生 Python 3.9+）
• Python：3.9–3.12（避免 3.13，部分依賴尚未適配）
• 基礎工具：git、curl、make（Linux/macOS），或 build-tools（Windows）

?? Windows 用戶優先用 WSL2。原生 Windows 支持有限，尤其涉及 Chromium 自動化（WhatsApp）時。

2. 克隆倉庫

git clone https://github.com/ai-agent-org/AI Agent平臺.git
cd AI Agent平臺

注意：官方倉庫是 ai-agent-org/AI Agent平臺，不是 your-repo。原文鏈接已修正。

3. 安裝依賴

pip install -r requirements.txt

requirements.txt 分三類依賴：

• core: 必需（httpx, pyyaml, playwright）
• platforms: 按需啟用（python-telegram-bot, discord.py, webwhatsapi）
• models: 按需啟用（transformers, llama-cpp-python, litellm）

不需要 WhatsApp？注釋掉 webwhatsapi 行再安裝。

4. 配置平臺憑證

編輯 config.yaml：

platforms:
  telegram:
    token: "789123456:ABCdefGhIjKlmNoPqrStUvWxYz"
    chat_id: -1001234567890
  discord:
    token: "MTIzNDU2Nzg5MDExMjMyNDU2.Cxyz.ABC-defghijklmnopqrstuvwxyz"
    channel_id: "123456789012345678"
  whatsapp:
    headless: true
    timeout: 60

• Telegram Bot Token 從 @BotFather 獲取
• Discord Token 從 Discord Developer Portal 創建 Bot 得到
• WhatsApp 使用 Playwright 啟動 Chromium 掃碼登錄，無需第三方網關

5. 啟動服務

python main.py

啟動后你會看到：

[INFO] Loaded 3 platforms: telegram, discord, whatsapp
[INFO] Model router ready: claude-3-haiku (remote), qwen2-1.5b (local)
[INFO] HTTP server listening on http://127.0.0.1:8000
[INFO] WebSocket gateway active

服務默認提供 REST API 和 WebSocket 接口，也支持 CLI 直接觸發任務。

使用指南

1. 寫一個任務

AI Agent平臺 的任務是純 Python 函數，用 @task 裝飾器注冊：

# tasks/greet.py
from ai-agent import task

@task(name="morning-greeting", trigger="cron:0 8 * * *")
def send_morning_greeting():
    return {
        "platform": "telegram",
        "message": "?? 早安！今日待辦：\n1. 查看昨日 GitHub PR\n2. 同步 Notion 周計劃"
    }

保存后執行：

ai-agent run morning-greeting

支持觸發方式：

• cron:（系統級定時）
• webhook:（接收 HTTP POST）
• event:（監聽平臺事件，如 telegram:message）
• cli:（手動運行）

2. 調用模型做決策

模型調用封裝為 ai-agent.llm.infer()，屏蔽底層差異：

# tasks/summarize_rss.py
from ai-agent import task, llm

@task(name="rss-summary")
def summarize_latest_post():
    # 從 RSS 抓最新條目（內置 feedparser）
    entry = get_latest_rss_entry("https://example.com/feed.xml")
    
    # 用本地模型生成摘要
    summary = llm.infer(
        model="qwen2-1.5b",
        prompt=f"用中文總結以下技術文章，限 100 字：\n{entry.title}\n{entry.content}"
    )
    
    return {
        "platform": "discord",
        "channel": "tech-news",
        "message": f"?? {entry.title}\n{summary}"
    }

模型名直接對應 config.yaml 中定義的別名，切換模型只需改字符串。

常見問題

1. AI Agent平臺 支持哪些平臺？

完整列表見 Supported Platforms。新增平臺只需實現 3 個方法：connect(), listen(), send()。已有 PR 正在集成 LINE 和飛書。

2. 怎么加自己的模型？

兩種方式：

• HTTP 模型：在 config.yaml 加 endpoint，AI Agent平臺 自動適配 OpenAI 兼容格式
• Python 模型：寫一個模塊，暴露 infer(prompt, **kwargs) 函數，放進 models/ 目錄，重啟服務即可識別

示例：models/my-rag.py

def infer(prompt: str, **kwargs) -> str:
    return rag_query(prompt)  # 你的 RAG 邏輯

3. 離線能跑嗎？

能。只要：

• 平臺接入方式支持離線（Telegram Bot、Discord Gateway、RSS 都行；WhatsApp 需掃碼但后續可離線收消息）
• 模型是本地加載（transformers, llama.cpp, Ollama）
• 關閉所有遠程依賴（注釋 litellm, openai, anthropic 相關行）

實測 M2 Mac Mini（16GB）可同時跑 Qwen2-1.5B + Telegram + RSS，內存占用 < 4GB。

下一步學習建議

• 動手改一個現有任務：把 examples/echo.py 改成監聽 GitHub Issue 新建事件，自動用本地模型寫回復草稿
• 試跑本地模型：用 llama.cpp 轉換 Qwen2-0.5B GGUF，填進 config.yaml，對比響應速度和質量
• 看日志定位問題：AI Agent平臺 默認輸出結構化 JSON 日志到 logs/，用 jq 或 tail -f logs/app.log | jq '.' 實時觀察動作流

遇到卡點？先查 logs/error.log，再搜 GitHub Issues。社區不灌水，PR 都帶測試用例。