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

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

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

它和“龍蝦”沒有關系——名字只是項目代號，別被誤導。

安裝與運行

1. 環境準備

確保系統滿足以下最低要求：

• 操作系統：Windows 10+、macOS 12+ 或主流 Linux 發行版（如 Ubuntu 20.04+）
• Python：3.8–3.11（推薦 3.10；3.12 尚未全面驗證）
• 其他工具：Git（必須），Node.js（僅當啟用前端插件或 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 版本，避免系統 Python 沖突。
Windows 用戶請使用 PowerShell（非 CMD），并確保 pip 調用的是 Python 3.10+。

2. 安裝 AI Agent平臺

用 pip 安裝穩定版：

pip install ai-agent

如果你打算開發插件或調試源碼，可以克隆倉庫后安裝：

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

3. 初始化配置

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

ai-agent init

然后編輯配置文件：

nano ~/.ai-agent/config.yaml

關鍵字段說明：

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 需用應用專用密碼
  from_address: your@gmail.com

4. 啟動服務

ai-agent start

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

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

5. 發送指令試試

服務就緒后，在已配置的 Telegram Bot 中發送以下任意指令：

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

AI Agent平臺 會解析時間、聯系人、航班號等實體，調用對應插件執行。成功后自動回復確認消息。

6. 快速驗證

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

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

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

常見問題

AI Agent平臺 啟動后不響應消息

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

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

• AI Agent平臺 默認使用中文指令，但對句式敏感。避免嵌套從句，用直白主謂賓結構：

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

插件報錯 “module not found”

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

下一步

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

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