cosmicstack-labs/mercury-agent
Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.
Mercury — 「靈魂驅動」的AI代理
是什麼 – Mercury 是一個在本地運行、權限嚴格強化的AI助理，您可透過命令列、Web儀表板或Telegram與之對話。它與大型語言模型提供者（OpenAI、Anthropic、DeepSeek、Ollama等）通訊，能讀取/寫入檔案、執行shell命令、取得URL、管理Git、排程任務等。所有操作皆受顯式權限模型限制，代理會在您的機器上保留一個持久、可搜尋的「第二腦」記憶。
核心理念
| 理念 | Mercury 如何實現 |
|---|---|
| 權限強化的工具 | 所有內建工具（檔案、shell、git、web等）在執行危險操作（如 sudo、rm -rf /）時預設被阻止。您可以選擇「詢問我」（每次操作前提示）或「全部允許」（整個會話中允許）。 |
| 第二腦記憶 | SQLite + FTS5 將提取的事實儲存在十種類型中（身分、目標、習慣等）。每次對話後，Mercury 會自動提取少量高置信度事實，每小時整合一次，並將前5個最相關的記憶注入LLM上下文。 |
| 靈魂驅動的個性 | 您自己的Markdown文件（soul.md、persona.md、taste.md、heartbeat.md）定義了代理的個性，使「個性」脫離任何企業服務。 |
| Token感知的預算 | 追蹤每日Token預算；當使用量超過70%時，Mercury會自動縮短回覆。您可透過 /budget 命令查看、重設或覆蓋預算。 |
| 始終運行的守護程序 | mercury up 安裝使用者級系統服務（LaunchAgent、systemd使用者單元或Windows工作排程器），在崩潰後自動重啟，並可在開機時自動運行。在守護程序模式下，Telegram成為主要聊天通道。 |
| 可擴充的技能 | 社群貢獻的「技能」（迷你代理）遵循 Agent Skills 規範，可透過單一指令安裝（mercury skills install …）。技能作為額外工具出現，可從聊天中呼叫或排程。 |
快速開始（無需Node.js）
# macOS / Linux – 下載自包含二進位檔
curl -fsSL https://mercuryagent.sh/install.sh | sh
# Windows PowerShell
irm https://mercuryagent.sh/install.ps1 | iex
安裝程式將 mercury 可執行檔放置在 ~/.local/bin（或Windows等效位置）。首次執行會啟動向導，設定您的姓名、LLM提供者API金鑰和可選的Telegram配對。
如果您已安裝Node 20+，也可執行：
npx @cosmicstack/mercury-agent # 一次性執行
npm i -g @cosmicstack/mercury-agent && mercury # 全域安裝
主要命令列介面
| 命令 | 功能 |
|---|---|
mercury / mercury start |
啟動互動式Ink TUI聊天會話。 |
mercury up |
安裝使用者級服務（如需）並啟動後台守護程序。 |
mercury stop / restart / status / logs |
管理守護程序。 |
mercury doctor |
重新執行設定向導或檢查設定。 |
mercury telegram … |
配對、批准或管理Telegram使用者（管理員 vs. 成員角色）。 |
mercury skills … |
搜尋、檢視、安裝、更新或移除社群技能。 |
mercury upgrade |
拉取最新版本（二進位或npm）。 |
在聊天中，您可以輸入不消耗LLM Token的斜線指令，例如：
/tools– 列出目前載入的工具/budget– 顯示每日Token使用情況/memory– 浏覽第二腦/code agent <task>– 啟動子代理在背景處理編碼任務/tasks– 列出已排程的任務
Web儀表板與看板板
執行 mercury doctor 可在 http://127.0.0.1:6174 啟用本地Web UI。它提供：
- 伺服器傳送事件串流式聊天
- 每張卡片可由Mercury自動處理的視覺化看板板
- 第二腦記憶圖譜檢視
- 代碼編輯任務的輕量級IDE式工作區
儀表板預設使用憑證（mercury / Mercury@123）保護，並僅綁定到本機。
擴充Mercury
- 技能 – 描述工具集和Markdown文件
SKILL.md的套件。透過mercury skills install <category>/<slug>安裝。技能儲存在~/.mercury/skills/，下次啟動時自動載入。 - 提供者 – 在
~/.mercury/mercury.yaml中新增任何OpenAI相容端點。Mercury會依序嘗試，並自動回退。 - 自訂工具 – 由於核心基於Vercel AI SDK和簡單的工具分發迴圈，開發者可新增新的TypeScript模組，公開
run函數，並在設定中註冊。
從原始碼安裝
git clone https://github.com/cosmicstack-labs/mercury-agent.git
cd mercury-agent
npm install # Node ≥ 20
npm run build # 產生 dist/ 套件
npm start # 從原始碼執行
為實現真正獨立的二進位檔（無需終端使用者Node執行時），倉儲使用 Bun：
npm run build:bin # 在 release/ 中產生平台特定可執行檔
發行佈局包含macOS（arm64 & x64）、Linux（arm64 & x64）和Windows的獨立二進位檔，以及Web UI的tarball和SHA‑256校驗和。
許可證與安全
- 許可證： MIT（參見
LICENSE）。 - 安全模型： 所有潛在破壞性操作均透過shell封鎖清單阻止，並需顯式使用者批准。代理僅在呼叫特定工具（如
fetch_url）時才會將本地檔案或命令輸出傳送至遠端服務。 - 資料本地性： 所有記憶、日誌和設定均位於您機器的
~/.mercury/目錄下；除非設定遠端LLM提供者，否則不使用雲端儲存。
哪些人可能需要？
- 希望擁有個人AI助理，能編輯程式碼、執行建置或管理git，但又不授予其無限制shell存取權限的開發者。
- 喜歡可搜尋、自動整理的「第二腦」，且完全儲存在筆電上的知識工作者。
- 需要自架設、權限感知的Telegram或私人Web UI機器人的團隊。
總結：Mercury 是一個功能齊全、本地運行的AI代理，強調安全性（權限提示、Token預算）、持久性（SQLite支援的記憶與看板板）和可擴充性（社群技能、多提供者回退）。它可透過單行安裝腳本立即使用，或從原始碼建構以實現更深入的客製化。
相關
- 專案
- 專案
- 專案
- 專案
- 專案