AI Agent平臺 新手指南：構(gòu)建你的個人AI工作流助理

用 AI Agent平臺 自動處理郵件、日程和航班提醒

你不需要等一個“完美”的 AI 助理上線。AI Agent平臺 是一個輕量級開源 Agent 框架，能直接跑在本地，理解自然語言指令，并通過 WhatsApp、Telegram 等常用聊天應(yīng)用接收任務(wù)。它不依賴大模型 API 中轉(zhuǎn)，所有指令解析和插件調(diào)度都在本地完成，隱私可控，響應(yīng)快。

它和“龍蝦”沒有關(guān)系——名字只是項目代號，別被誤導(dǎo)。

安裝與運行

1. 環(huán)境準(zhǔn)備

確保系統(tǒng)滿足以下最低要求：

• 操作系統(tǒng)：Windows 10+、macOS 12+ 或主流 Linux 發(fā)行版（如 Ubuntu 20.04+）
• Python：3.8–3.11（推薦 3.10；3.12 尚未全面驗證）
• 其他工具：Git（必須），Node.js（僅當(dāng)啟用前端插件或 Web UI 時需要）

# Ubuntu/Debian 示例
sudo apt update
sudo apt install -y python3.10 python3.10-venv python3-pip git

# 可選：Node.js（v16.x 或 v18.x）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

macOS 用戶建議用 pyenv 管理 Python 版本，避免系統(tǒng) Python 沖突。
Windows 用戶請使用 PowerShell（非 CMD），并確保 pip 調(diào)用的是 Python 3.10+。

2. 安裝 AI Agent平臺

用 pip 安裝穩(wěn)定版：

pip install ai-agent

如果你打算開發(fā)插件或調(diào)試源碼，可以克隆倉庫后安裝：

git clone https://github.com/ai-agent/ai-agent.git
cd ai-agent
pip install -e .

3. 初始化配置

運行初始化命令，生成默認(rèn)配置目錄和 config.yaml：

ai-agent init

然后編輯配置文件：

nano ~/.ai-agent/config.yaml

關(guān)鍵字段說明：

llm:
  backend: ollama          # 支持 ollama / llama-cpp / transformers
  model: qwen2:7b          # 本地模型名（需提前用 ollama pull）

plugins:
  email: true              # 啟用郵件插件（需 SMTP 配置）
  calendar: true           # 啟用日歷插件（支持 iCal 文件或 Google Calendar API）
  flight: true             # 啟用航班提醒（基于 IATA 航班號 + 日期）

channels:
  telegram:
    enabled: true
    token: "YOUR_TELEGRAM_BOT_TOKEN"
  whatsapp:
    enabled: false         # WhatsApp 需額外配置 Twilio 或 360dialog

郵件插件示例（SMTP）：

email:
  smtp_host: smtp.gmail.com
  smtp_port: 587
  username: your@gmail.com
  password: "APP_PASSWORD_HERE"  # Gmail 需用應(yīng)用專用密碼
  from_address: your@gmail.com

4. 啟動服務(wù)

ai-agent start

服務(wù)啟動后，會在后臺運行。默認(rèn)日志輸出到 ~/.ai-agent/logs/，出問題時先看 app.log。

提示：首次啟動會自動下載并加載配置的 LLM（如 qwen2:7b），耗時取決于網(wǎng)絡(luò)和磁盤速度。可另開終端執(zhí)行 ollama list 觀察進(jìn)度。

5. 發(fā)送指令試試

服務(wù)就緒后，在已配置的 Telegram Bot 中發(fā)送以下任意指令：

• 發(fā)郵件
  發(fā)郵件給 alice@company.com，主題：周報提交提醒，內(nèi)容：請今天下班前提交 Q3 周報。
• 加日程
  明天下午 3 點和張三視頻會議，時長 45 分鐘，日歷備注：客戶方案評審
• 設(shè)航班提醒
  提醒我 CA123 航班，2024-10-15 08:20 起飛，提前 2 小時通知

AI Agent平臺 會解析時間、聯(lián)系人、航班號等實體，調(diào)用對應(yīng)插件執(zhí)行。成功后自動回復(fù)確認(rèn)消息。

6. 快速驗證

不用等真實場景，立刻驗證三件事：

失敗時，直接查 ~/.ai-agent/logs/app.log，常見錯誤包括：

• SMTP 認(rèn)證失敗（檢查密碼是否為應(yīng)用專用密碼）
• Telegram token 無效（重新在 BotFather 獲取）
• LLM 加載超時（確認(rèn) ollama serve 正在運行）

常見問題

AI Agent平臺 啟動后不響應(yīng)消息

• 檢查 ai-agent status 是否顯示 running
• 查看 app.log 末尾是否有 Channel telegram started 類似日志
• 如果用 Telegram，確認(rèn) Bot 已在群組中被設(shè)為管理員（需 post messages 權(quán)限）

指令總是被忽略或解析錯誤

• AI Agent平臺 默認(rèn)使用中文指令，但對句式敏感。避免嵌套從句，用直白主謂賓結(jié)構(gòu)：

  • ? 把文檔發(fā)給李四，附件是 report.pdf
  • ? 請將我昨天寫的那份報告，就是帶圖表的那版，發(fā)給李四
• 模型太小（如 phi3:3.8b）可能導(dǎo)致實體識別不準(zhǔn)。換 qwen2:7b 或 llama3:8b 通常更穩(wěn)。

插件報錯 “module not found”

• 運行 pip list | grep ai-agent，確認(rèn)插件包已安裝（如 ai-agent-email）
• 插件需單獨安裝：pip install ai-agent-email ai-agent-calendar
• 某些插件依賴系統(tǒng)庫（如 libmagic），Ubuntu 上執(zhí)行 sudo apt install libmagic1

下一步

• 修改 config.yaml 中的 llm.model，換用你本地跑得動的模型（Ollama 模型庫 可查量化版本）
• 在 ~/.ai-agent/plugins/ 下寫一個 Python 文件，實現(xiàn)自定義插件（參考 email.py 結(jié)構(gòu)）
• 關(guān)閉 channels.telegram.enabled，改用 channels.cli: true，直接在終端交互調(diào)試，跳過消息平臺環(huán)節(jié)

AI Agent平臺 不是黑盒。它的核心邏輯就藏在 ai-agent/agent/ 和各插件的 main.py 里——遇到問題，grep 一下比讀文檔更快。