AI Agent平臺：異步協(xié)作與本地化部署的開源個人AI助手

AI Agent平臺 是一個開源個人 AI 助手，專注解決真實(shí)協(xié)作場景中的痛點(diǎn)：時區(qū)錯位、敏感數(shù)據(jù)不出內(nèi)網(wǎng)、以及開發(fā)者需要可控的集成路徑。它不依賴云端大模型 API，核心邏輯可全量運(yùn)行在本地，任務(wù)調(diào)度和狀態(tài)同步通過輕量級消息隊(duì)列實(shí)現(xiàn)。

異步協(xié)作：按需觸發(fā)，不卡流程

團(tuán)隊(duì)成員不在同一時間在線？會議排期總湊不齊？AI Agent平臺 把協(xié)作從“實(shí)時對齊”轉(zhuǎn)向“狀態(tài)對齊”。

它不強(qiáng)制所有人同時在線，而是把任務(wù)、上下文和預(yù)期結(jié)果固化為可序列化的單元，交由本地服務(wù)異步流轉(zhuǎn)。典型工作流：

• 用戶 A 提交一個「分析上周銷售日志并生成摘要」任務(wù)，附帶原始日志文件和提示模板
• AI Agent平臺 將任務(wù)寫入本地 SQLite 任務(wù)隊(duì)列，標(biāo)記為 pending
• 用戶 B 在自己方便的時間拉取該任務(wù)，執(zhí)行后提交結(jié)果（文本、圖表或代碼片段）
• 系統(tǒng)自動更新任務(wù)狀態(tài)為 completed，通知 A 查看，并將輸出存檔到本地知識庫

關(guān)鍵設(shè)計(jì)點(diǎn)：

• 任務(wù)自帶上下文快照（含當(dāng)前系統(tǒng)時間、用戶角色、關(guān)聯(lián)文件哈希），避免“我改了但你沒看到最新版”
• 所有狀態(tài)變更通過本地 SQLite WAL 模式記錄，支持?jǐn)嚯娀謴?fù)
• Git 集成僅用于同步提示詞模板和工作流定義（.claw/ 目錄），不托管原始業(yè)務(wù)數(shù)據(jù)

沒有中心化服務(wù)器協(xié)調(diào)，也沒有長連接保活——靠本地文件鎖 + 輕量輪詢完成協(xié)作閉環(huán)。

本地化部署：數(shù)據(jù)不動，模型可選

AI Agent平臺 默認(rèn)不聯(lián)網(wǎng)。所有數(shù)據(jù)落盤在用戶指定目錄（如 ~/.ai-agent/data），數(shù)據(jù)庫、日志、緩存、模型權(quán)重全部隔離在本地文件系統(tǒng)中。

你可以選擇：

• 完全離線：用 llama.cpp 加載 GGUF 格式量化模型，CPU 推理（實(shí)測 M2 Ultra 上 3B 模型響應(yīng) < 800ms）
• 混合模式：調(diào)用本地 Ollama 或 LM Studio 的 HTTP 接口，仍不經(jīng)過公網(wǎng)
• 企業(yè)網(wǎng)關(guān)：對接內(nèi)部 vLLM 集群，AI Agent平臺 僅作任務(wù)編排層

實(shí)際效果：

• 醫(yī)療機(jī)構(gòu)用它處理脫敏后的患者隨訪記錄，原始 CSV 文件從不離開內(nèi)網(wǎng)服務(wù)器
• 金融團(tuán)隊(duì)在無外網(wǎng)的開發(fā)機(jī)上跑合規(guī)檢查腳本，提示詞經(jīng)法務(wù)審核后固化為 Git tag
• 網(wǎng)絡(luò)不穩(wěn)定時，任務(wù)隊(duì)列持續(xù)接收新條目，網(wǎng)絡(luò)恢復(fù)后自動重試失敗步驟

Windows/macOS/Linux 均提供單二進(jìn)制分發(fā)包，無 Python 環(huán)境依賴，安裝即用。

開發(fā)者友好性：少抽象，多控制

AI Agent平臺 的代碼結(jié)構(gòu)直接映射到使用場景：

├── cmd/          # CLI 入口（ai-agent start / ai-agent task submit）
├── core/         # 任務(wù)調(diào)度器、狀態(tài)機(jī)、本地存儲引擎
├── adapters/     # Ollama / llama.cpp / vLLM 的適配層（各 100 行以內(nèi)）
├── web/          # 基于 HTMX 的極簡前端（無 JS 框架，純 HTML + SSE）
└── examples/     # 可直接運(yùn)行的 workflow.yaml（含郵件自動歸檔、周報(bào)生成等）

API 設(shè)計(jì)克制：

• POST /v1/tasks 提交任務(wù)（JSON body，字段直白：prompt, files, assignee）
• GET /v1/tasks?status=completed 拉取結(jié)果（返回純文本或 base64 編碼附件）
• 所有端點(diǎn)默認(rèn)走 http://localhost:8080，無需鑒權(quán)（由操作系統(tǒng)進(jìn)程隔離保障安全）

社區(qū)貢獻(xiàn)集中在具體問題：

• 新增一個 git diff 解析器，讓任務(wù)能自動提取 PR 中的變更文件列表
• 為 Windows 添加服務(wù)注冊腳本（ai-agent install-service）
• 修復(fù) Outlook .msg 文件解析的編碼異常

沒有“平臺抽象層”，沒有自定義 DSL——所有擴(kuò)展都落在標(biāo)準(zhǔn)工具鏈上。

Windows 環(huán)境快速配置指南

1. 下載
   訪問 https://ai-agent.io/downloads，下載 ai-agent-v0.8.2-windows-amd64.exe（或 arm64）

2. 安裝

   • 雙擊運(yùn)行，選擇安裝路徑（例如 C:\Program Files\AI Agent平臺）
   • 勾選「添加到 PATH」（推薦）

3. 初始化

   # 啟動服務(wù)（首次運(yùn)行會創(chuàng)建 ~/.ai-agent 目錄）
   ai-agent start
   
   # 提交第一個測試任務(wù)
   ai-agent task submit --prompt "列出當(dāng)前目錄下所有 .txt 文件名" --cwd .

4. 訪問界面
   瀏覽器打開 http://localhost:8080

   • 左側(cè)導(dǎo)航欄查看任務(wù)隊(duì)列
   • 點(diǎn)擊任務(wù) ID 查看完整輸入/輸出/執(zhí)行日志
   • 設(shè)置頁可切換本地模型路徑（如 C:\models\phi-3-mini.Q4_K_M.gguf）
5. 驗(yàn)證離線能力
   斷開網(wǎng)絡(luò)，重復(fù)步驟 3 —— 任務(wù)仍能提交、執(zhí)行、返回結(jié)果。所有操作發(fā)生在本地進(jìn)程內(nèi)。

下一步：從運(yùn)行到改造

• 想替換默認(rèn)模型？修改 ~/.ai-agent/config.yaml 中的 model_path，指向你的 GGUF 文件
• 需要對接內(nèi)部系統(tǒng)？用 ai-agent task submit --webhook http://intranet/api/v1/hooks 觸發(fā)回調(diào)
• 做自動化辦公？復(fù)制 examples/email-archive.workflow.yaml，把 imap_server 改成公司郵箱地址

AI Agent平臺 不是黑盒助手，而是一套可拆解、可替換、可審計(jì)的協(xié)作原語。它的價(jià)值不在“多聰明”，而在“多可靠”——當(dāng)網(wǎng)絡(luò)中斷、政策收緊、或你需要知道每一行輸出從哪來時，它依然在你機(jī)器里安靜運(yùn)行。