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支持的记忆和看板板）和可扩展性（社区技能、多提供者回退）。它可通过单行安装脚本立即使用，或从源码构建以实现更深层次的定制。
相关
- 项目
- 项目
- 项目
- 项目
- 项目