《龍蝦新手指南：AI Agent平臺入門教程》

一、什么是AI Agent平臺？

AI Agent平臺 是一個開源的本地 AI 自動化框架。它不依賴云服務，所有任務都在你自己的設備上運行。支持 WhatsApp、Telegram、Discord、Twitter、Slack、Instagram 等 30+ 平臺，能自動完成消息回復、內容發布、數據抓取等操作。

它不是玩具項目。你可以把 AI Agent平臺 嵌入現有工作流，用它調度 Claude、GPT 系列 API，也能直接接入本地模型（比如 Llama 3、Phi-3、Qwen2），做文本生成、分類、摘要或結構化提取。

二、為什么用 AI Agent平臺？

本地運行，數據不出設備

• 所有輸入、中間狀態、輸出都保留在本地。聊天記錄、截圖、文件不會上傳。
• 斷網時照常工作——適合內網環境、敏感場景或旅行途中。
• 直接調用 GPU/CPU，沒有網絡延遲和 API 配額限制。大模型推理、OCR、截圖識別都能壓到本地跑。

跨平臺任務統一編排

它把不同平臺抽象成一致的操作接口：

• 即時通訊：WhatsApp（通過 Twilio）、Telegram Bot API、Discord Gateway
• 社交平臺：Twitter v2 API、Mastodon、Reddit（PRAW）
• 協作工具：Slack Events API、Microsoft Graph（Teams）

典型用法：

• 在 Telegram 收到“訂單查詢”，自動查數據庫并回傳結果
• 每小時從 Discord 和 Slack 抓取帶 #bug 標簽的消息，匯總進 Notion 表格
• 同步發布圖文到 Twitter、Mastodon 和 Bluesky（自動適配字數/附件格式）

模型可插拔，按需切換

AI Agent平臺 不綁定任何模型。你在配置里聲明能力需求，框架自動路由：

models:
  default: "llama3-8b-instruct"
  fallback: "gpt-4o-mini"
  models:
    llama3-8b-instruct:
      type: "llm"
      backend: "llama.cpp"
      path: "./models/llama3.Q4_K_M.gguf"
      n_gpu_layers: 40
    gpt-4o-mini:
      type: "api"
      provider: "openai"
      api_key: "${OPENAI_API_KEY}"

實際使用中：

• 用本地 Llama 3 處理日常對話、日志摘要（零成本、低延遲）
• 遇到復雜推理或代碼生成失敗時，自動降級到 GPT-4o-mini（靠 fallback 規則）
• 用微調過的 Phi-3 做客服工單分類（加載 .gguf 即可，不用改代碼）

三、安裝與配置

環境要求

• OS：Windows 10+、macOS 12+、主流 Linux 發行版（Ubuntu 22.04、Debian 12）
• Python：3.9–3.12（推薦 3.11）
• Git：用于拉取代碼

?? 提示：Windows 用戶建議開啟 WSL2；macOS M 系列芯片用戶優先用 llama.cpp + Metal 后端。

安裝步驟

1. 克隆代碼庫

git clone https://github.com/your-repo/AI Agent平臺.git
cd AI Agent平臺

2. 創建并激活虛擬環境（強烈建議）

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

3. 安裝依賴

pip install --upgrade pip
pip install -r requirements.txt

部分平臺需要額外依賴（如 WhatsApp 用 Twilio）：

pip install twilio  # 如果要用 WhatsApp
pip install python-telegram-bot  # Telegram

4. 配置模型

編輯 config.yaml，填入你的模型憑證和路徑：

models:
  default: "llama3-8b-instruct"
  models:
    llama3-8b-instruct:
      type: "llm"
      backend: "llama.cpp"
      path: "./models/llama3.Q4_K_M.gguf"
    claude-3-haiku:
      type: "api"
      provider: "anthropic"
      api_key: "sk-ant-api03-..."

? 注意：API 密鑰不要硬編碼。用環境變量更安全：

api_key: "${ANTHROPIC_API_KEY}"

然后啟動前執行 export ANTHROPIC_API_KEY=...

5. 配置平臺連接

修改 platforms.yaml，只填你實際用的平臺：

platforms:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
  discord:
    token: "${DISCORD_BOT_TOKEN}"
    intents: ["message_content", "guild_messages"]

?? 獲取方式：

• Telegram：@BotFather 創建 bot，拿到 token
• Discord：Discord Developer Portal → Application → Bot → Token
• WhatsApp：Twilio 控制臺 → Account SID + Auth Token

6. 啟動

python main.py

首次運行會自動下載默認模型（可選），之后直接進入監聽狀態。

四、動手寫兩個例子

示例 1：Telegram 關鍵詞自動回復

在 skills/telegram_reply.py 中寫：

from ai-agent import AI Agent平臺

oc = AI Agent平臺()

@oc.on_message("telegram")
def handle_hello(message):
    if "hello" in message.text.lower():
        return "Hello! Try `/help` for commands."
    elif message.text.startswith("/help"):
        return (
            "Available commands:\n"
            "/status — show running tasks\n"
            "/ping — test bot responsiveness"
        )

保存后重啟 main.py，發 /help 到你的 bot 就能看到響應。

示例 2：定時抓取 Twitter 熱門話題

新建 skills/twitter_trends.py：

from ai-agent import AI Agent平臺

oc = AI Agent平臺()

@oc.on_interval("twitter", interval=300)  # 每 5 分鐘執行一次
def fetch_trends():
    trends = oc.get_trends(woeid=1)  # 全球趨勢
    top_3 = trends[:3]
    for i, t in enumerate(top_3, 1):
        print(f"{i}. {t.name} ({t.tweet_volume or 'low volume'})")

?? 注意：Twitter v2 API 需要申請 Academic Research 訪問權限，并在 config.yaml 中配置 bearer_token。

五、排障清單

六、下一步怎么走？

• 把 skills/ 下的示例改成你的真實需求：比如自動歸檔郵件附件、同步飛書多維表格到本地 SQLite
• 讀 examples/ 目錄里的完整工作流（含錯誤重試、限流、日志埋點）
• 在 GitHub Issues 里搜 good first issue，提 PR 修一個小 bug 或加一個平臺適配器

七、資源鏈接

• AI Agent平臺 GitHub 倉庫
• 配置項完整說明（config.yaml）
• 各平臺接入指南（含截圖和權限開關位置）
• 本地模型量化與部署小抄（.gguf 下載 + llama.cpp 參數）