mercury-agent-deployment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mercury Agent Deployment

Mercury Agent 部署指南

Skill by ara.so — AI Agent Skills collection.

Mercury is a soul-driven AI agent framework with permission-hardened tools, token budgets, multi-channel access (CLI + Telegram), persistent memory (Second Brain), and 24/7 daemon mode. It runs TypeScript-based agents with 31 built-in tools, extensible skills, and SQLite-backed memory.

由 ara.so 提供的Skill——AI Agent技能集合。

Mercury是一款智能AI代理框架，具备权限强化工具、令牌预算管理、多渠道访问（CLI + Telegram）、持久化记忆（第二大脑）以及7×24小时守护进程模式。它运行基于TypeScript的代理，内置31种工具，支持可扩展技能，采用SQLite存储记忆。

Installation

安装

Quick Start (npx)

快速启动（npx方式）

bash

npx @cosmicstack/mercury-agent

bash

npx @cosmicstack/mercury-agent

Global Installation

全局安装

bash

npm i -g @cosmicstack/mercury-agent
mercury

First run triggers setup wizard for:

Agent name
LLM provider (OpenAI, Anthropic, etc.)
Optional Telegram bot integration
Permission defaults

bash

npm i -g @cosmicstack/mercury-agent
mercury

首次运行会触发设置向导，配置以下内容：

代理名称
LLM提供商（OpenAI、Anthropic等）
可选Telegram机器人集成
默认权限设置

Core Commands

核心命令

Daemon & Service Management

守护进程与服务管理

bash

undefined

bash

undefined

Recommended: install service + start daemon

推荐：安装服务并启动守护进程

mercury up

Start in foreground

前台启动

mercury start

Start as background daemon

后台守护进程启动

mercury start -d

Daemon control

守护进程控制

mercury restart mercury stop mercury logs mercury status

System service (auto-start on boot)

系统服务（开机自启）

mercury service install mercury service status mercury service uninstall

undefined

mercury service install mercury service status mercury service uninstall

undefined

Configuration

配置管理

bash

undefined

bash

undefined

Reconfigure setup

重新配置设置

mercury doctor

Platform diagnostics

平台诊断

mercury doctor --platform

Re-run setup wizard

重新运行设置向导

mercury setup

Check status

检查状态

mercury status

Upgrade to latest

升级至最新版本

mercury upgrade

undefined

mercury upgrade

undefined

Telegram Access Management

Telegram访问管理

bash

undefined

bash

undefined

List all users

列出所有用户

mercury telegram list

Approve pairing code or pending request

批准配对码或待处理请求

mercury telegram approve <code|id>

Reject pending request

拒绝待处理请求

mercury telegram reject <id>

Remove approved user

删除已批准用户

mercury telegram remove <id>

Role management

角色管理

mercury telegram promote <id> mercury telegram demote <id>

Reset all access

重置所有访问权限

mercury telegram reset

undefined

mercury telegram reset

undefined

Configuration Files

配置文件

All runtime data in

~/.mercury/

~/.mercury/
├── mercury.yaml              # Main config
├── .env                      # API keys
├── permissions.yaml          # Tool capabilities
├── token-usage.json          # Budget tracking
├── schedules.yaml            # Scheduled tasks
├── soul/                     # Personality files
│   ├── soul.md
│   ├── persona.md
│   ├── taste.md
│   └── heartbeat.md
├── skills/                   # Installed skills
├── memory/
│   ├── short-term/          # Conversation JSON
│   ├── long-term/           # Extracted facts (JSONL)
│   ├── episodic/            # Event log (JSONL)
│   └── second-brain/        # SQLite + FTS5
└── logs/

所有运行时数据存储在

~/.mercury/

目录下：

~/.mercury/
├── mercury.yaml              # 主配置文件
├── .env                      # API密钥
├── permissions.yaml          # 工具权限配置
├── token-usage.json          # 预算跟踪
├── schedules.yaml            # 定时任务
├── soul/                     # 个性配置文件
│   ├── soul.md
│   ├── persona.md
│   ├── taste.md
│   └── heartbeat.md
├── skills/                   # 已安装技能
├── memory/
│   ├── short-term/          # 对话记录JSON
│   ├── long-term/           # 提取的事实（JSONL格式）
│   ├── episodic/            # 事件日志（JSONL格式）
│   └── second-brain/        # SQLite + FTS5
└── logs/

Example mercury.yaml

mercury.yaml示例

yaml

agentName: Mercury
soul:
  path: ~/.mercury/soul
providers:
  - type: openai
    model: gpt-4o
    apiKeyEnv: OPENAI_API_KEY
  - type: anthropic
    model: claude-3-5-sonnet-20241022
    apiKeyEnv: ANTHROPIC_API_KEY
channels:
  telegram:
    enabled: true
    tokenEnv: TELEGRAM_BOT_TOKEN
    persistence: ~/.mercury/telegram.json
permissions:
  defaultMode: ask
  filesystem:
    read: ask
    write: ask
    delete: ask
  shell:
    execute: ask
    blocklist:
      - sudo
      - rm -rf /
      - mkfs
      - dd if=
budget:
  daily: 200000
  warningThreshold: 0.7
memory:
  secondBrain:
    enabled: true
    dbPath: ~/.mercury/memory/second-brain/second-brain.db

yaml

agentName: Mercury
soul:
  path: ~/.mercury/soul
providers:
  - type: openai
    model: gpt-4o
    apiKeyEnv: OPENAI_API_KEY
  - type: anthropic
    model: claude-3-5-sonnet-20241022
    apiKeyEnv: ANTHROPIC_API_KEY
channels:
  telegram:
    enabled: true
    tokenEnv: TELEGRAM_BOT_TOKEN
    persistence: ~/.mercury/telegram.json
permissions:
  defaultMode: ask
  filesystem:
    read: ask
    write: ask
    delete: ask
  shell:
    execute: ask
    blocklist:
      - sudo
      - rm -rf /
      - mkfs
      - dd if=
budget:
  daily: 200000
  warningThreshold: 0.7
memory:
  secondBrain:
    enabled: true
    dbPath: ~/.mercury/memory/second-brain/second-brain.db

Example .env

.env示例

bash

undefined

bash

undefined

LLM Providers

LLM提供商

OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-...

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

Optional: Spotify (for music control tools)

可选：Spotify（用于音乐控制工具）

SPOTIFY_CLIENT_ID=... SPOTIFY_CLIENT_SECRET=...

Optional: Enable inline album art (iTerm only)

可选：启用内嵌专辑封面（仅iTerm支持）

MERCURY_SPOTIFY_ART=1

Optional: Disable Second Brain

可选：禁用第二大脑

SECOND_BRAIN_ENABLED=false

undefined

SECOND_BRAIN_ENABLED=false

undefined

In-Chat Commands

聊天内命令

These work in both CLI and Telegram without consuming tokens:

bash

/help                 # Show manual
/status              # Config, budget, usage
/tools               # List loaded tools
/skills              # List installed skills
/budget              # Token budget status
/budget override     # Override budget once
/budget reset        # Reset usage to zero
/budget set <n>      # Change daily limit
/permissions         # Toggle Ask Me / Allow All
/view                # Toggle balanced/detailed progress
/stream              # Toggle Telegram streaming
/code agent <task>   # Delegate coding task to sub-agent
/ws exit             # Exit workspace IDE mode
/tasks               # List scheduled tasks
/memory              # View/manage Second Brain
/unpair              # Telegram: reset access

以下命令在CLI和Telegram中均可使用，且不消耗令牌：

bash

/help                 # 显示手册
/status              # 查看配置、预算和使用情况
/tools               # 列出已加载工具
/skills              # 列出已安装技能
/budget              # 令牌预算状态
/budget override     # 临时覆盖预算限制
/budget reset        # 将使用量重置为零
/budget set <n>      # 修改每日限额
/permissions         # 切换"询问我"/"全部允许"模式
/view                # 切换平衡/详细进度视图
/stream              # 切换Telegram流式输出
/code agent <task>   # 将编码任务委托给子代理
/ws exit             # 退出工作区IDE模式
/tasks               # 列出定时任务
/memory              # 查看/管理第二大脑
/unpair              # Telegram：重置访问权限

Built-in Tools

内置工具

Filesystem Tools

文件系统工具

typescript

// Mercury auto-requests permission for file operations
// Example conversation:
// User: "Read package.json"
// Mercury uses: read_file

// Approve folder scope for batch operations
// User: "Read all TypeScript files in src/"
// Mercury prompts: approve_scope for src/

// File operations
read_file({ path: "package.json" })
write_file({ path: "config.json", content: "{...}" })
create_file({ path: "new.ts", content: "export ..." })
edit_file({ path: "app.ts", operations: [...] })
list_dir({ path: "src/" })
delete_file({ path: "temp.txt" })
send_file({ path: "report.pdf" })  // Telegram only

typescript

// Mercury会自动请求文件操作权限
// 对话示例：
// 用户："读取package.json"
// Mercury调用：read_file

// 批准文件夹范围以进行批量操作
// 用户："读取src/下所有TypeScript文件"
// Mercury提示：批准src/的访问范围

// 文件操作
read_file({ path: "package.json" })
write_file({ path: "config.json", content: "{...}" })
create_file({ path: "new.ts", content: "export ..." })
edit_file({ path: "app.ts", operations: [...] })
list_dir({ path: "src/" })
delete_file({ path: "temp.txt" })
send_file({ path: "report.pdf" })  # 仅Telegram支持

Shell Tools

Shell工具

typescript

// Blocklist prevents dangerous commands
// Blocked: sudo, rm -rf /, mkfs, dd if=, etc.

run_command({ command: "npm install" })
cd({ path: "/path/to/project" })
approve_command({ command: "git push" })  // Pre-approve

typescript

undefined

Git Tools

黑名单阻止危险命令

—

已阻止：sudo, rm -rf /, mkfs, dd if=等

typescript

git_status()
git_diff({ staged: true })
git_log({ limit: 10 })
git_add({ files: ["src/app.ts"] })
git_commit({ message: "feat: add feature" })
git_push()

run_command({ command: "npm install" }) cd({ path: "/path/to/project" }) approve_command({ command: "git push" }) # 预先批准

undefined

Web Tools

Git工具

typescript

fetch_url({ url: "https://api.example.com/data" })

typescript

git_status()
git_diff({ staged: true })
git_log({ limit: 10 })
git_add({ files: ["src/app.ts"] })
git_commit({ message: "feat: add feature" })
git_push()

Messaging Tools

Web工具

typescript

// Send proactive messages
send_message({ 
  channel: "telegram", 
  content: "Build complete!" 
})

typescript

fetch_url({ url: "https://api.example.com/data" })

Scheduler Tools

消息工具

typescript

// Recurring task (cron syntax)
schedule_task({
  name: "morning-standup",
  cron: "0 9 * * *",  // 9am daily
  task: "Send standup reminder"
})

// One-shot delayed task
schedule_task({
  name: "reminder",
  delay_seconds: 900,  // 15 minutes
  task: "Check deployment status"
})

list_scheduled_tasks()
cancel_scheduled_task({ name: "morning-standup" })

typescript

// 发送主动消息
send_message({ 
  channel: "telegram", 
  content: "构建完成！" 
})

Skill Management Tools

调度工具

typescript

// Install community skill
install_skill({ name: "web-search" })

// List installed
list_skills()

// Execute skill
use_skill({ 
  name: "web-search", 
  query: "latest TypeScript features" 
})

typescript

// 周期性任务（cron语法）
schedule_task({
  name: "morning-standup",
  cron: "0 9 * * *",  // 每天上午9点
  task: "发送站会提醒"
})

// 一次性延迟任务
schedule_task({
  name: "reminder",
  delay_seconds: 900,  // 15分钟
  task: "检查部署状态"
})

list_scheduled_tasks()
cancel_scheduled_task({ name: "morning-standup" })

Creating Custom Skills

技能管理工具

Skills are markdown files in

~/.mercury/skills/<skill-name>/SKILL.md

typescript

// 安装社区技能
install_skill({ name: "web-search" })

// 列出已安装技能
list_skills()

// 执行技能
use_skill({ 
  name: "web-search", 
  query: "最新TypeScript特性" 
})

Example: GitHub Integration Skill

创建自定义技能

bash

mkdir -p ~/.mercury/skills/github-pr-review

~/.mercury/skills/github-pr-review/SKILL.md

markdown

---
name: github-pr-review
description: Review GitHub pull requests and provide feedback
triggers:
  - "review this pull request"
  - "check github pr"
  - "analyze code changes"
---

技能是存储在

~/.mercury/skills/<skill-name>/SKILL.md

中的markdown文件：

GitHub PR Review Skill

示例：GitHub集成技能

Prerequisites

—

bash

undefined

bash

mkdir -p ~/.mercury/skills/github-pr-review

~/.mercury/skills/github-pr-review/SKILL.md

markdown

---
name: github-pr-review
description: Review GitHub pull requests and provide feedback
triggers:
  - "review this pull request"
  - "check github pr"
  - "analyze code changes"
---

Install GitHub CLI

GitHub PR评审技能

—

前置条件

brew install gh # macOS

bash

undefined

or: sudo apt install gh # Linux

安装GitHub CLI

Authenticate

—

gh auth login

undefined

brew install gh # macOS

Usage

或：sudo apt install gh # Linux

—

认证登录

When user requests PR review:

Fetch PR diff:
```
gh pr diff <number>
```
Analyze changes for:
- Code quality
- Security issues
- Breaking changes
- Test coverage

Post review:

gh pr review <number> --comment -b "feedback"

gh auth login

undefined

Example Flow

使用方法

bash

undefined

当用户请求PR评审时：

获取PR差异：
```
gh pr diff <number>
```
分析变更内容，检查：
- 代码质量
- 安全问题
- 破坏性变更
- 测试覆盖率

提交评审：

gh pr review <number> --comment -b "feedback"

Get PR list

示例流程

gh pr list

bash

undefined

Get diff

获取PR列表

gh pr diff 123

gh pr list

Review with approval

获取差异

gh pr review 123 --approve -b "LGTM! Great work on error handling."

gh pr diff 123

Request changes

批准并留下评论

gh pr review 123 --request-changes -b "Please add tests for the new endpoint."

undefined

gh pr review 123 --approve -b "LGTM! 错误处理做得很棒。"

Best Practices

请求修改

Always check CI status before review
Look for security vulnerabilities in dependencies
Verify backward compatibility
Check for adequate test coverage

undefined

gh pr review 123 --request-changes -b "请为新端点添加测试。"

undefined

Install Custom Skill

最佳实践

bash

undefined

评审前务必检查CI状态
检查依赖中的安全漏洞
验证向后兼容性
确认测试覆盖率足够

undefined

Mercury auto-detects skills in ~/.mercury/skills/

安装自定义技能

Or install programmatically:

—

mercury # Start agent

bash

undefined

In chat:

Mercury会自动检测~/.mercury/skills/目录下的技能

User: "Install the github-pr-review skill"

或通过编程方式安装：

Mercury uses: install_skill

—

undefined

mercury # 启动代理

Second Brain Memory System

在聊天中：

—

用户："安装github-pr-review技能"

—

Mercury调用：install_skill

Mercury's persistent memory system with automatic extraction and recall.

undefined

Memory Types

第二大脑记忆系统

identity — Core facts about user (name, role, location)
preference — User preferences (tools, coding style, communication)
goal — Objectives and targets
project — Active projects and context
habit — Recurring patterns and routines
decision — Important choices made
constraint — Limitations and boundaries
relationship — People and connections
episode — Significant events
reflection — Patterns and insights

Mercury的持久化记忆系统，支持自动提取和召回。

Memory Lifecycle

记忆类型

typescript

// Automatic after each conversation:
// 1. Extract 0-3 facts with confidence/importance/durability scores
// 2. Store in SQLite with FTS5 full-text search
// 3. Auto-consolidation every 60 minutes
// 4. Conflict resolution (higher confidence wins)
// 5. Auto-pruning (stale after 21 days for active-scope)

identity — 用户核心信息（姓名、角色、所在地）
preference — 用户偏好（工具、编码风格、沟通方式）
goal — 目标与任务
project — 活跃项目与上下文
habit — 重复模式与日常习惯
decision — 重要决策
constraint — 限制与边界
relationship — 人际关系
episode — 重要事件
reflection — 模式与洞察

Memory Commands

记忆生命周期

bash

undefined

typescript

// 每次对话后自动执行：
// 1. 提取0-3个带有置信度/重要性/持久性评分的事实
// 2. 存储到带FTS5全文搜索的SQLite数据库
// 3. 每60分钟自动整合
// 4. 冲突解决（置信度高的内容优先）
// 5. 自动清理（活跃范围的内容超过21天视为过期）

In-chat memory management

记忆管理命令

/memory # Show overview /memory search AI # Search memories /memory pause # Pause extraction /memory resume # Resume extraction /memory clear # Clear all memories

bash

undefined

Disable Second Brain entirely

聊天内记忆管理

In .env:

—

SECOND_BRAIN_ENABLED=false

/memory # 显示概览 /memory search AI # 搜索记忆 /memory pause # 暂停提取 /memory resume # 恢复提取 /memory clear # 清空所有记忆

Or in mercury.yaml:

完全禁用第二大脑

—

在.env中：

memory: secondBrain: enabled: false

undefined

SECOND_BRAIN_ENABLED=false

Memory Data Structure

或在mercury.yaml中：

typescript

// ~/.mercury/memory/second-brain/second-brain.db (SQLite)
// Tables:
// - memories: id, type, content, confidence, importance, durability
// - memories_fts: FTS5 index for full-text search
// - consolidations: profile summaries, active state, reflections

// Example memory record:
{
  type: "preference",
  content: "User prefers TypeScript over JavaScript for new projects",
  confidence: 0.95,
  importance: 0.8,
  durability: "durable",  // or "transient"
  scope: "active",        // or "background"
  extractedAt: "2026-05-16T10:30:00Z",
  lastAccessedAt: "2026-05-16T10:30:00Z"
}

memory: secondBrain: enabled: false

undefined

Permission System

记忆数据结构

Permission Modes

—

bash

undefined

typescript

// ~/.mercury/memory/second-brain/second-brain.db (SQLite)
// 表：
// - memories: id, type, content, confidence, importance, durability
// - memories_fts: FTS5全文搜索索引
// - consolidations: 个人资料摘要、活跃状态、反思内容

// 记忆记录示例：
{
  type: "preference",
  content: "User prefers TypeScript over JavaScript for new projects",
  confidence: 0.95,
  importance: 0.8,
  durability: "durable",  // 或 "transient"
  scope: "active",        // 或 "background"
  extractedAt: "2026-05-16T10:30:00Z",
  lastAccessedAt: "2026-05-16T10:30:00Z"
}

Ask Me: Prompt for each tool use

权限系统

Allow All: Auto-approve all tools

权限模式

Toggle in-chat:

—

/permissions

bash

undefined

Or configure default in mercury.yaml:

询问我：每次使用工具前提示

—

全部允许：自动批准所有工具使用

—

在聊天中切换：

permissions: defaultMode: ask # or: allow

undefined

/permissions

Permission Configuration

或在mercury.yaml中配置默认模式：

~/.mercury/permissions.yaml

yaml

filesystem:
  read: ask          # ask, allow, deny
  write: ask
  delete: ask
  scopes:
    - path: ~/projects/safe-dir
      read: allow
      write: allow

shell:
  execute: ask
  blocklist:
    - sudo
    - rm -rf /
    - mkfs
    - dd if=
    - "> /dev/"
  allowlist:
    - npm
    - git
    - node

messaging:
  send: allow

git:
  read: allow        # status, diff, log
  write: ask         # commit, push

web:
  fetch: ask

permissions: defaultMode: ask # 或：allow

undefined

Scope Approval

权限配置

bash

undefined

~/.mercury/permissions.yaml

yaml

filesystem:
  read: ask          # ask, allow, deny
  write: ask
  delete: ask
  scopes:
    - path: ~/projects/safe-dir
      read: allow
      write: allow

shell:
  execute: ask
  blocklist:
    - sudo
    - rm -rf /
    - mkfs
    - dd if=
    - "> /dev/"
  allowlist:
    - npm
    - git
    - node

messaging:
  send: allow

git:
  read: allow        # status, diff, log
  write: ask         # commit, push

web:
  fetch: ask

User: "Update all TypeScript files in src/ to use strict mode"

范围批准

Mercury prompts:

—

┌─────────────────────────────────────────┐

—

│ Approve folder scope? │

—

│ Path: ~/project/src │

—

│ Read: allow │

—

│ Write: allow │

—

│ → Yes No Allow All │

—

└─────────────────────────────────────────┘

—

Keyboard shortcuts:

—

Y - Yes (approve this scope)

—

N - No (deny)

—

A - Allow All (switch to Allow All mode)

—

Arrow keys + Enter

—

undefined

bash

undefined

Telegram Integration

用户："将src/下所有TypeScript文件更新为严格模式"

Bot Setup

Mercury提示：

—

┌─────────────────────────────────────────┐

—

│ 是否批准文件夹访问范围？ │

—

│ 路径：~/project/src │

—

│ 读取：允许 │

—

│ 写入：允许 │

—

│ → 是否全部允许 │

—

└─────────────────────────────────────────┘

—

键盘快捷键：

—

Y - 是（批准此范围）

—

N - 否（拒绝）

—

A - 全部允许（切换至全部允许模式）

—

方向键 + 回车键

Create bot with @BotFather
Get token from BotFather
Add to
```
~/.mercury/.env
```
:

bash

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

Enable in
```
mercury.yaml
```
:

yaml

channels:
  telegram:
    enabled: true
    tokenEnv: TELEGRAM_BOT_TOKEN
    persistence: ~/.mercury/telegram.json

undefined

First-Time Pairing

Telegram集成

—

机器人设置

bash

undefined

通过@BotFather创建机器人
从BotFather获取令牌
添加到
```
~/.mercury/.env
```
：

bash

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

在
```
mercury.yaml
```
中启用：

yaml

channels:
  telegram:
    enabled: true
    tokenEnv: TELEGRAM_BOT_TOKEN
    persistence: ~/.mercury/telegram.json

1. Start Mercury

首次配对

mercury up

bash

undefined

2. In Telegram, send to your bot:

1. 启动Mercury

/start

mercury up

3. Bot responds with pairing code: TG-ABC123

2. 在Telegram中向你的机器人发送：

4. In CLI, approve:

—

mercury telegram approve TG-ABC123

/start

You're now the first admin!

3. 机器人回复配对码：TG-ABC123

—

4. 在CLI中批准：

undefined

mercury telegram approve TG-ABC123

Multi-User Access

你现在成为第一个管理员！

bash

undefined

undefined

Admin workflow:

多用户访问

1. New user sends /start to bot

—

2. Admin sees pending request in:

—

mercury telegram list

bash

undefined

3. Approve or reject:

管理员工作流程：

—

1. 新用户向机器人发送/start

—

2. 管理员在以下命令中查看待处理请求：

mercury telegram approve <user-id> mercury telegram reject <user-id>

mercury telegram list

Promote to admin:

3. 批准或拒绝：

mercury telegram promote <user-id>

mercury telegram approve <user-id> mercury telegram reject <user-id>

Demote to member:

提升为管理员：

mercury telegram demote <user-id>

mercury telegram promote <user-id>

Remove user:

降级为普通成员：

mercury telegram remove <user-id>

undefined

mercury telegram demote <user-id>

Telegram Features

删除用户：

typescript

// HTML formatting (bold, italic, code)
// Editable streaming messages (live token updates)
// File uploads (send_file tool)
// Typing indicators
// Multi-user with role-based access (admin/member)
// Private chat only (groups ignored)

// Example interaction:
// User: "Show me the last commit"
// Mercury: git_log → formatted HTML response with code blocks

mercury telegram remove <user-id>

undefined

Token Budget Management

Telegram功能

Budget Configuration

—

yaml

undefined

typescript

// HTML格式（粗体、斜体、代码块）
// 可编辑流式消息（实时令牌更新）
// 文件上传（send_file工具）
// 输入指示器
// 基于角色的多用户访问（管理员/成员）
// 仅支持私聊（忽略群组）

// 交互示例：
// 用户："显示最后一次提交"
// Mercury调用git_log → 返回带代码块的格式化HTML响应

mercury.yaml

令牌预算管理

—

预算配置

budget: daily: 200000 # tokens per day warningThreshold: 0.7 # 70% warning

undefined

yaml

undefined

Budget Commands

mercury.yaml

bash

undefined

budget: daily: 200000 # 每日令牌限额 warningThreshold: 0.7 # 70%触发警告

undefined

Check status

预算命令

/budget

bash

undefined

Override for one request

检查状态

/budget override

/budget

Reset usage

临时覆盖单次请求的预算限制

/budget reset

/budget override

Change daily limit

重置使用量

/budget set 300000

undefined

/budget reset

Auto-Concise Mode

修改每日限额

typescript

// When usage > 70%, Mercury automatically:
// 1. Switches to concise response mode
// 2. Notifies user: "⚠️ 75% of daily budget used. Responses will be concise."
// 3. Continues normally but shorter responses

// Usage tracked in:
// ~/.mercury/token-usage.json
{
  "2026-05-16": {
    "used": 150000,
    "limit": 200000,
    "requests": 42
  }
}

/budget set 300000

undefined

CLI Workspace Mode

自动简洁模式

Keyboard Shortcuts

—

bash

undefined

typescript

// 当使用量超过70%时，Mercury自动：
// 1. 切换为简洁响应模式
// 2. 通知用户："⚠️ 已使用每日预算的75%。响应将转为简洁模式。"
// 3. 继续正常响应，但内容更简短

In workspace/coding mode:

使用量记录在：

—

~/.mercury/token-usage.json

Ctrl+P # Switch to Plan mode Ctrl+X # Switch to Execute mode Esc / Ctrl+Q # Exit workspace → general chat Ctrl+V # Toggle progress view

{ "2026-05-16": { "used": 150000, "limit": 200000, "requests": 42 } }

undefined

Progress view modes:

CLI工作区模式

- balanced: compact, key steps only

键盘快捷键

- detailed: full tool calls, reasoning, output

—

undefined

bash

undefined

Code Agent Delegation

在工作区/编码模式下：

bash

undefined

Ctrl+P # 切换至规划模式 Ctrl+X # 切换至执行模式 Esc / Ctrl+Q # 退出工作区 → 普通聊天 Ctrl+V # 切换进度视图

In-chat command:

进度视图模式：

—

- balanced: 紧凑模式，仅显示关键步骤

—

- detailed: 完整模式，显示所有工具调用、推理过程和输出

/code agent implement user authentication with JWT

undefined

Mercury spawns sub-agent in background:

代码代理委托

1. Plans implementation

—

2. Executes code changes

—

3. Reports back with file changes

—

4. You review and approve

—

undefined

bash

undefined

Daemon Mode Production Setup

聊天内命令：

Systemd (Linux)

—

bash

undefined

/code agent implement user authentication with JWT

Install service

Mercury在后台启动子代理：

—

1. 规划实现方案

—

2. 执行代码变更

—

3. 返回文件变更报告

—

4. 你进行评审并批准

mercury service install

undefined

Service file created at:

守护进程模式生产环境设置

~/.config/systemd/user/mercury-agent.service

Systemd（Linux）

Enable linger (start on boot without login)

—

sudo loginctl enable-linger $USER

bash

undefined

Service commands

安装服务

systemctl --user status mercury-agent systemctl --user restart mercury-agent systemctl --user stop mercury-agent

mercury service install

View logs

服务文件创建于：

—

~/.config/systemd/user/mercury-agent.service

—

启用 linger（无需登录即可开机自启）

journalctl --user -u mercury-agent -f

undefined

sudo loginctl enable-linger $USER

LaunchAgent (macOS)

服务命令

bash

undefined

systemctl --user status mercury-agent systemctl --user restart mercury-agent systemctl --user stop mercury-agent

Install service

查看日志

mercury service install

journalctl --user -u mercury-agent -f

undefined

Plist created at:

LaunchAgent（macOS）

~/Library/LaunchAgents/org.cosmicstack.mercury-agent.plist

—

Service commands

—

launchctl list | grep mercury launchctl unload ~/Library/LaunchAgents/org.cosmicstack.mercury-agent.plist launchctl load ~/Library/LaunchAgents/org.cosmicstack.mercury-agent.plist

bash

undefined

View logs

安装服务

mercury logs

undefined

mercury service install

Task Scheduler (Windows)

Plist文件创建于：

—

~/Library/LaunchAgents/org.cosmicstack.mercury-agent.plist

—

服务命令

bash

undefined

launchctl list | grep mercury launchctl unload ~/Library/LaunchAgents/org.cosmicstack.mercury-agent.plist launchctl load ~/Library/LaunchAgents/org.cosmicstack.mercury-agent.plist

Install service

查看日志

mercury service install

mercury logs

undefined

Task created via schtasks

任务计划程序（Windows）

Location: Task Scheduler Library

—

View task

—

schtasks /query /tn "MercuryAgent"

bash

undefined

Service commands via mercury CLI

安装服务

mercury service status mercury service uninstall

undefined

mercury service install

Crash Recovery

通过schtasks创建任务

—

位置：任务计划程序库

—

查看任务

typescript

// Built-in exponential backoff:
// - Max 10 restarts per minute
// - Delay doubles on each crash: 1s, 2s, 4s, 8s, ...
// - Resets after 60s of stable run

// Logs crash details to:
// ~/.mercury/logs/daemon.log

schtasks /query /tn "MercuryAgent"

Common Patterns

通过mercury CLI执行服务命令

Morning Standup Automation

—

bash

undefined

mercury service status mercury service uninstall

undefined

Schedule daily standup report

崩溃恢复

mercury # Start agent

typescript

undefined

In chat:

内置指数退避机制：

"Schedule a daily standup at 9am that checks:

- 每分钟最多重启10次

- Yesterday's git commits

- 每次崩溃延迟时间翻倍：1s, 2s, 4s, 8s, ...

- Open GitHub issues assigned to me

- 稳定运行60秒后重置延迟

- Calendar for today

崩溃详情记录在：

and sends a summary to Telegram"

~/.mercury/logs/daemon.log

Mercury uses: schedule_task with cron: "0 9 * * *"

—

undefined

undefined

Project Context Persistence

常见使用模式

—

晨间站会自动化

typescript

// Mercury's Second Brain remembers:
// - Current project: "Working on Mercury agent skills"
// - Preferences: "Prefers TypeScript, avoids any types"
// - Coding style: "Uses async/await, ESM imports"
// - Active goals: "Ship v1.2.0 by end of month"

// Example conversation:
// User: "Add a new skill for git operations"
// Mercury recalls project context, checks existing skills,
// suggests implementation that matches established patterns

bash

undefined

File Scope Workflow

调度每日站会报告

bash

undefined

mercury # 启动代理

Efficient batch operations:

在聊天中：

User: "Refactor all components in src/components/ to use hooks"

"调度每日上午9点的站会，检查：

Mercury prompts once:

- 昨天的git提交

"Approve folder scope for src/components/?"

- 分配给我的GitHub开放议题

→ Yes

- 今日日程

Then processes all files without re-prompting

并将总结发送到Telegram"

—

Mercury调用：schedule_task，cron设置为"0 9 * * *"

undefined

undefined

Multi-Channel Notifications

项目上下文持久化

typescript

// Use send_message for proactive updates:
// 1. Long-running build starts
// 2. Mercury sends: "Build started for v1.2.0"
// 3. Build completes
// 4. Mercury sends: "✅ Build complete in 3m 42s"

// Works in both CLI and Telegram
send_message({ 
  channel: "telegram",  // or "cli"
  content: "Deployment to production successful!" 
})

typescript

undefined

Troubleshooting

Mercury的第二大脑会记住：

Agent Not Responding

- 当前项目："开发Mercury Agent技能"

—

- 偏好："偏好TypeScript，避免使用any类型"

—

- 编码风格："使用async/await，ESM导入"

—

- 活跃目标："月底前发布v1.2.0版本"

—

对话示例：

—

用户："添加一个Git操作的新技能"

—

Mercury回忆项目上下文，检查现有技能，

—

建议符合既定模式的实现方案

bash

undefined

undefined

Check daemon status

文件范围工作流

mercury status

bash

undefined

View logs

高效批量操作：

—

用户："重构src/components/下所有组件以使用hooks"

—

Mercury仅提示一次：

—

"是否批准src/components/的文件夹访问范围？"

—

→ 是

—

然后无需再次提示即可处理所有文件

mercury logs

undefined

Restart daemon

多渠道通知

mercury restart

typescript

undefined

Or kill and start fresh

使用send_message发送主动更新：

—

1. 长时间运行的构建启动

—

2. Mercury发送："v1.2.0版本构建已启动"

—

3. 构建完成

—

4. Mercury发送："✅ 构建完成，耗时3分42秒"

—

CLI和Telegram均支持此功能

mercury stop mercury up

undefined

send_message({ channel: "telegram", // 或 "cli" content: "生产环境部署成功！" })

undefined

Telegram Bot Not Working

故障排除

—

代理无响应

bash

undefined

bash

undefined

Verify token

检查守护进程状态

cat ~/.mercury/.env | grep TELEGRAM_BOT_TOKEN

mercury status

Check bot status with BotFather

查看日志

Ensure bot is not blocked

—

Reset access and re-pair

—

mercury telegram reset

mercury logs

Then send /start to bot again

重启守护进程

undefined

mercury restart

Permission Errors

或终止后重新启动

bash

undefined

mercury stop mercury up

undefined

Check permissions.yaml

Telegram机器人无法工作

cat ~/.mercury/permissions.yaml

bash

undefined

Reset to defaults

验证令牌

mercury doctor

cat ~/.mercury/.env | grep TELEGRAM_BOT_TOKEN

Or edit manually:

通过BotFather检查机器人状态

—

确保机器人未被封禁

—

重置访问权限并重新配对

nano ~/.mercury/permissions.yaml

undefined

mercury telegram reset

Token Budget Exceeded

然后再次向机器人发送/start

bash

undefined

undefined

Check usage

权限错误

/budget

bash

undefined

Reset today's usage

检查permissions.yaml

/budget reset

cat ~/.mercury/permissions.yaml

Increase limit

重置为默认设置

/budget set 500000

mercury doctor

Or override once

或手动编辑：

/budget override

undefined

nano ~/.mercury/permissions.yaml

undefined

Memory Database Issues

令牌预算超限

bash

undefined

bash

undefined

Check Second Brain status

检查使用情况

/memory

/budget

Clear and rebuild

重置今日使用量

/memory clear

/budget reset

Or disable entirely

提高限额

In .env:

—

echo "SECOND_BRAIN_ENABLED=false" >> ~/.mercury/.env mercury restart

undefined

/budget set 500000

Service Won't Start on Boot

或临时覆盖一次

bash

undefined

/budget override

undefined

Linux: Enable linger

记忆数据库问题

sudo loginctl enable-linger $USER

bash

undefined

macOS: Check LaunchAgent

检查第二大脑状态

launchctl list | grep mercury

/memory

Windows: Verify task exists

清空并重建

schtasks /query /tn "MercuryAgent"

/memory clear

Reinstall service

或完全禁用

—

在.env中：

mercury service uninstall mercury service install

undefined

echo "SECOND_BRAIN_ENABLED=false" >> ~/.mercury/.env mercury restart

undefined

High Memory Usage

服务无法开机自启

bash

undefined

bash

undefined

Check daemon stats

Linux：启用linger

ps aux | grep mercury

sudo loginctl enable-linger $USER

Clear old conversation memory

macOS：检查LaunchAgent

rm -rf ~/.mercury/memory/short-term/*.json

launchctl list | grep mercury

Restart daemon

Windows：验证任务是否存在

mercury restart

undefined

schtasks /query /tn "MercuryAgent"

Skill Not Loading

重新安装服务

bash

undefined

mercury service uninstall mercury service install

undefined

List installed skills

内存占用过高

/skills

bash

undefined

Check skill directory

检查守护进程统计信息

ls -la ~/.mercury/skills/

ps aux | grep mercury

Reinstall skill

清除旧对话记忆

mercury # Start agent

rm -rf ~/.mercury/memory/short-term/*.json

In chat: "Install the web-search skill"

重启守护进程

Or manually:

—

mkdir -p ~/.mercury/skills/my-skill nano ~/.mercury/skills/my-skill/SKILL.md

undefined

mercury restart

undefined

Resources

技能无法加载

Homepage: https://mercury.cosmicstack.org/
GitHub: https://github.com/cosmicstack-labs/mercury-agent
npm: https://www.npmjs.com/package/@cosmicstack/mercury-agent
Agent Skills: https://agentskills.io
License: MIT

bash

undefined

—

列出已安装技能

—

/skills

—

检查技能目录

—

ls -la ~/.mercury/skills/

—

重新安装技能

—

mercury # 启动代理

—

在聊天中："安装web-search技能"

—

或手动创建：

—

mkdir -p ~/.mercury/skills/my-skill nano ~/.mercury/skills/my-skill/SKILL.md

undefined

—

资源

—

主页: https://mercury.cosmicstack.org/
GitHub: https://github.com/cosmicstack-labs/mercury-agent
npm: https://www.npmjs.com/package/@cosmicstack/mercury-agent
Agent Skills: https://agentskills.io
许可证: MIT ",