@cosmicstack/mercury-agent 1.1.0 → 1.1.1

package/README.md

@@ -20,6 +20,10 @@
   <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@cosmicstack/mercury-agent" alt="node"></a>
 </p>
 
+<p align="center">
+  English | <a href="README.zh-CN.md">简体中文</a>
+</p>
+
 ---
 
 ## Quick Start

package/README.zh-CN.md

@@ -0,0 +1,240 @@
+# Mercury Agent 中文文档
+
+> 一个以“灵魂”为中心的 AI Agent，内置权限加固工具、Token 预算、多渠道访问和 SQLite 支持的 Second Brain 记忆。
+
+[English](README.md) | 简体中文
+
+Mercury 会记住重要信息，在执行有风险的操作前先请求确认，并且可以通过 CLI 或 Telegram 以 24/7 后台进程运行。它适合需要本地文件操作、命令执行、长期记忆、定时任务和多模型兜底能力的个人 AI 助手场景。
+
+## 快速开始
+
+直接运行：
+
+```bash
+npx @cosmicstack/mercury-agent
+```
+
+或全局安装：
+
+```bash
+npm i -g @cosmicstack/mercury-agent
+mercury
+```
+
+首次运行会启动配置向导。你需要输入姓名、模型 API Key，并可选择配置 Telegram Bot Token。之后如需重新配置：
+
+```bash
+mercury doctor
+```
+
+## 为什么选择 Mercury
+
+- **权限优先**：Shell 命令有阻止列表，文件读写受目录作用域限制，危险操作会进入待审批流程。
+- **Second Brain 记忆**：基于 SQLite 和 FTS5 的结构化持久记忆，支持自动提取、相关召回、冲突处理和自动整理。
+- **灵魂驱动**：人格由你拥有的 Markdown 文件定义，包括 `soul.md`、`persona.md`、`taste.md` 和 `heartbeat.md`。
+- **Token 感知**：内置每日 Token 预算，超过阈值后自动简洁回复，并支持 `/budget` 查看、重置或临时覆盖。
+- **实时流式输出**：CLI 支持实时 Token 流和 Markdown 重渲染，Telegram 支持可编辑状态消息。
+- **持续运行**：可作为后台守护进程运行，崩溃后自动重启，并支持开机自启、定时任务和主动通知。
+- **可扩展**：支持安装社区 Skill、调度 Skill 定时运行，并兼容 [Agent Skills](https://agentskills.io) 规范。
+
+## 守护进程模式
+
+推荐使用：
+
+```bash
+mercury up
+```
+
+该命令会安装系统服务、启动后台守护进程，并确保 Mercury 正在运行。如果 Mercury 已经运行，它只会确认状态并显示 PID。
+
+常用命令：
+
+```bash
+mercury restart      # 重启后台进程
+mercury stop         # 停止后台进程
+mercury start -d     # 后台启动，不安装系统服务
+mercury logs         # 查看近期守护进程日志
+mercury status       # 查看运行状态
+```
+
+系统服务支持：
+
+| 平台 | 方式 | 是否需要管理员权限 |
+|------|------|--------------------|
+| macOS | LaunchAgent (`~/Library/LaunchAgents/`) | 否 |
+| Linux | systemd user unit (`~/.config/systemd/user/`) | 否，开机启动可能需要 linger |
+| Windows | Task Scheduler (`schtasks`) | 否 |
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `mercury up` | 推荐命令：安装服务、启动守护进程并确保运行 |
+| `mercury` | 启动 Agent，等同于 `mercury start` |
+| `mercury start` | 前台启动 |
+| `mercury start -d` | 后台启动 |
+| `mercury restart` | 重启后台进程 |
+| `mercury stop` | 停止后台进程 |
+| `mercury logs` | 查看近期日志 |
+| `mercury doctor` | 重新配置，回车保留现有值 |
+| `mercury setup` | 重新运行配置向导 |
+| `mercury status` | 查看配置和守护进程状态 |
+| `mercury help` | 查看完整手册 |
+| `mercury upgrade` | 升级到最新版本 |
+| `mercury telegram list` | 查看已批准和待处理的 Telegram 用户 |
+| `mercury telegram approve <code\|id>` | 批准配对码或待处理请求 |
+| `mercury telegram reject <id>` | 拒绝 Telegram 访问请求 |
+| `mercury telegram remove <id>` | 移除已批准用户 |
+| `mercury telegram promote <id>` | 将 Telegram 成员提升为管理员 |
+| `mercury telegram demote <id>` | 将 Telegram 管理员降级为成员 |
+| `mercury telegram reset` | 清空 Telegram 访问状态并重新开始 |
+| `mercury service install` | 安装开机自启系统服务 |
+| `mercury service uninstall` | 卸载系统服务 |
+| `mercury service status` | 查看系统服务状态 |
+| `mercury --verbose` | 使用调试日志启动 |
+
+## 对话内命令
+
+这些命令可在 CLI 或 Telegram 对话中输入，不消耗 API Token。
+
+| 命令 | 说明 |
+|------|------|
+| `/help` | 查看完整手册 |
+| `/status` | 查看 Agent 配置、预算和用量 |
+| `/tools` | 列出已加载工具 |
+| `/skills` | 列出已安装 Skill |
+| `/stream` | 切换 Telegram 文本流式输出 |
+| `/stream off` | 关闭流式输出，改为单条消息 |
+| `/budget` | 查看 Token 预算状态 |
+| `/budget override` | 为单次请求临时覆盖预算 |
+| `/budget reset` | 将用量重置为零 |
+| `/budget set <n>` | 修改每日 Token 预算 |
+| `/permissions` | 修改权限模式 |
+| `/tasks` | 列出定时任务 |
+| `/memory` | 查看和管理 Second Brain 记忆 |
+| `/unpair` | Telegram：重置所有访问 |
+
+## 内置工具
+
+| 分类 | 工具 |
+|------|------|
+| 文件系统 | `read_file`, `write_file`, `create_file`, `edit_file`, `list_dir`, `delete_file`, `send_file`, `approve_scope` |
+| Shell | `run_command`, `cd`, `approve_command` |
+| 消息 | `send_message` |
+| Git | `git_status`, `git_diff`, `git_log`, `git_add`, `git_commit`, `git_push` |
+| Web | `fetch_url` |
+| Skills | `install_skill`, `list_skills`, `use_skill` |
+| 调度 | `schedule_task`, `list_scheduled_tasks`, `cancel_scheduled_task` |
+| 系统 | `budget_status` |
+
+## 渠道
+
+| 渠道 | 能力 |
+|------|------|
+| CLI | Readline 提示符、方向键命令菜单、实时文本流、Markdown 重渲染、权限模式选择 |
+| Telegram | HTML 格式化、可编辑流式消息、文件上传、输入状态、多用户访问和管理员/成员角色 |
+
+### Telegram 访问模型
+
+Mercury 使用组织式访问模型，包含管理员和成员。
+
+- 首次设置：向你的 Bot 发送 `/start`，获取配对码，然后在 CLI 中执行 `mercury telegram approve <code>`。你会成为首位管理员。
+- 新用户：发送 `/start` 请求访问，由管理员在 CLI 中批准或拒绝。
+- 角色：管理员可以批准、拒绝、提升、降级和重置访问；成员可以与 Mercury 对话。
+- 重置：管理员可在 Telegram 发送 `/unpair`，或在 CLI 中执行 `mercury telegram reset`。
+- 仅支持私聊，群聊消息会被忽略。
+
+## 调度器
+
+- **周期任务**：使用 cron 表达式，例如 `0 9 * * *` 表示每天 9 点。
+- **一次性任务**：使用 `delay_seconds`，例如 15 秒后执行。
+- 任务会持久化到 `~/.mercury/schedules.yaml`，重启后自动恢复。
+- 执行结果会返回到创建任务时所在的渠道。
+
+## Second Brain
+
+Mercury 默认启用结构化持久记忆，并会在对话后自动提取、存储和召回与你有关的重要事实。
+
+- 10 种记忆类型：identity、preference、goal、project、habit、decision、constraint、relationship、episode、reflection。
+- 自动提取：每轮对话后提取 0 到 3 条事实，并记录置信度、重要性和持久性。
+- 相关召回：每次消息前注入最相关的前 5 条记忆，默认预算 900 字符。
+- 自动整理：每 60 分钟生成个人资料摘要、活跃状态摘要和反思。
+- 冲突处理：按置信度和时间新旧处理相互冲突的记忆。
+- 自动修剪：活跃作用域记忆 21 天后过期，推断记忆会衰减，低置信持久记忆 120 天后撤销。
+- 用户控制：通过 `/memory` 查看、搜索、暂停、恢复和清空。
+- 禁用方式：设置 `SECOND_BRAIN_ENABLED=false`，或在配置中设置 `memory.secondBrain.enabled: false`。
+
+所有数据都保存在本机 `~/.mercury/memory/second-brain/second-brain.db`，不会上传到云端。
+
+## 配置位置
+
+运行时数据保存在 `~/.mercury/`，不会写入你的项目目录。
+
+| 路径 | 用途 |
+|------|------|
+| `~/.mercury/mercury.yaml` | 主配置，包括提供商、渠道和预算 |
+| `~/.mercury/.env` | API Key 和 Token |
+| `~/.mercury/soul/*.md` | Agent 人格文件 |
+| `~/.mercury/permissions.yaml` | 能力和审批规则 |
+| `~/.mercury/skills/` | 已安装 Skill |
+| `~/.mercury/schedules.yaml` | 定时任务 |
+| `~/.mercury/token-usage.json` | 每日 Token 用量 |
+| `~/.mercury/memory/short-term/` | 每段对话的短期记忆 JSON 文件 |
+| `~/.mercury/memory/long-term/` | 自动提取事实，JSONL 格式 |
+| `~/.mercury/memory/episodic/` | 带时间戳的事件日志，JSONL 格式 |
+| `~/.mercury/memory/second-brain/` | 结构化记忆数据库 |
+| `~/.mercury/daemon.pid` | 后台进程 PID |
+| `~/.mercury/daemon.log` | 守护进程日志 |
+
+## 模型提供商兜底
+
+Mercury 可以配置多个 LLM 提供商，并按顺序自动尝试。如果某个提供商失败，会切换到下一个。
+
+| 提供商 | 默认模型 | API Key | 说明 |
+|--------|----------|---------|------|
+| DeepSeek | `deepseek-chat` | `DEEPSEEK_API_KEY` | 默认、成本较低 |
+| OpenAI | `gpt-4o-mini` | `OPENAI_API_KEY` | 支持 GPT-4o、o3 等 |
+| Anthropic | `claude-sonnet-4` | `ANTHROPIC_API_KEY` | Claude Sonnet、Haiku、Opus |
+| Grok (xAI) | `grok-4` | `GROK_API_KEY` | OpenAI 兼容接口 |
+| Ollama Cloud | `gpt-oss:120b` | `OLLAMA_CLOUD_API_KEY` | 远程 Ollama API |
+| Ollama Local | `gpt-oss:20b` | 无需 Key | 本地 Ollama 实例 |
+
+## 架构
+
+- TypeScript + Node.js 20+
+- Vercel AI SDK v4，支持 `generateText`、`streamText` 和多步 Agent 循环
+- grammY Telegram Bot
+- SQLite + FTS5 Second Brain
+- JSONL 短期、长期和情景记忆
+- 后台守护进程、PID 文件和崩溃恢复
+- macOS、Linux、Windows 系统服务
+
+## 参与贡献
+
+欢迎贡献修复、工具、记忆能力、渠道能力或文档改进。请保持 PR 聚焦，并在提交前运行：
+
+```bash
+npm install
+npm run build
+```
+
+贡献 Mercury 时请特别注意：
+
+- 工具必须走权限系统，不能绕过审批。
+- 面向 Agent 循环设计，尽量保持幂等。
+- 避免冗长输出和过度日志，Token 预算是核心约束。
+- CLI 和 Telegram 行为应尽量一致。
+- 新增依赖、破坏性变更和 soul/persona 系统调整应先讨论。
+
+## 许可证
+
+MIT © [Cosmic Stack](https://github.com/cosmicstack-labs)
+
+## 社区
+
+- Discord：[加入 Mercury Agent Discord](https://discord.gg/5emMpMJy5J)
+- 邮箱：[mercury@cosmicstack.org](mailto:mercury@cosmicstack.org)
+
+## 免责声明
+
+这是 AI 软件，可能出现错误。请自行评估风险后使用。

package/dist/index.js

@@ -4581,6 +4581,22 @@ Or use /budget override, /budget reset, /budget set <number> anytime.`,
       this.shutdown();
       return true;
     }
+    if (cmd === "/permissions") {
+      if (channelType === "cli" && channel instanceof CLIChannel) {
+        const mode = await channel.askPermissionMode?.();
+        if (mode === "allow-all") {
+          this.capabilities.permissions.setAutoApproveAll(true);
+          this.capabilities.permissions.addTempScope("/", true, true);
+          await channel.send("Allow All mode active for this session. All scopes, commands, and loops auto-approved. Resets on restart.", channelId);
+        } else {
+          this.capabilities.permissions.setAutoApproveAll(false);
+          await channel.send("Ask Me mode active. Risky actions will prompt for confirmation.", channelId);
+        }
+        return true;
+      }
+      await channel.send("Use /permissions in CLI to switch permission mode. On Telegram, use the /permissions button or command.", channelId);
+      return true;
+    }
     if (cmd === "/status") {
       const config = ctx.config();
       const budget = ctx.tokenBudget();
@@ -4833,9 +4849,11 @@ Or use /budget override, /budget reset, /budget set <number> anytime.`,
     await channel.withMenu(async (select) => {
       while (true) {
         const streamLabel = this.telegramStreaming ? "Disable Telegram Streaming" : "Enable Telegram Streaming";
+        const permLabel = this.capabilities.permissions.isAutoApproveAll() ? "Switch to Ask Me" : "Switch to Allow All";
         const action = await select("Mercury Commands", [
           { value: "status", label: "Status" },
           { value: "memory", label: "Memory" },
+          { value: "permissions", label: permLabel },
           { value: "telegram", label: "Telegram" },
           { value: "tools", label: "Tools" },
           { value: "skills", label: "Skills" },
@@ -4858,6 +4876,10 @@ Or use /budget override, /budget reset, /budget set <number> anytime.`,
           }
           continue;
         }
+        if (action === "permissions") {
+          await this.handleChatCommand("/permissions", "cli", channelId);
+          continue;
+        }
         if (action === "telegram") {
           await this.openCliTelegramMenu(channel, channelId, select);
           continue;
@@ -5365,6 +5387,11 @@ var ChannelRegistry = class {
 import { existsSync as existsSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "fs";
 import { join as join7 } from "path";
 var TOKEN_FILE = "token-usage.json";
+function safeNumber(value) {
+  if (value === null || value === void 0) return 0;
+  const n = Number(value);
+  return isNaN(n) ? 0 : n;
+}
 var TokenBudget = class {
   constructor(config) {
     this.config = config;
@@ -5380,7 +5407,7 @@ var TokenBudget = class {
   forceNext = false;
   canAfford(estimatedTokens) {
     this.resetIfNewDay();
-    return this.dailyUsed + estimatedTokens <= this.dailyBudget;
+    return safeNumber(this.dailyUsed) + estimatedTokens <= safeNumber(this.dailyBudget);
   }
   isOverBudget() {
     this.resetIfNewDay();
@@ -5388,7 +5415,7 @@ var TokenBudget = class {
       this.forceNext = false;
       return false;
     }
-    return this.dailyUsed >= this.dailyBudget;
+    return safeNumber(this.dailyUsed) >= safeNumber(this.dailyBudget);
   }
   forceAllowNext() {
     this.forceNext = true;
@@ -5416,18 +5443,24 @@ var TokenBudget = class {
   }
   recordUsage(entry) {
     this.resetIfNewDay();
-    const logEntry = { ...entry, timestamp: Date.now() };
-    this.dailyUsed += entry.totalTokens;
+    const inputTokens = safeNumber(entry.inputTokens);
+    const outputTokens = safeNumber(entry.outputTokens);
+    const totalTokens = safeNumber(entry.totalTokens) || inputTokens + outputTokens;
+    const safeEntry = { ...entry, inputTokens, outputTokens, totalTokens };
+    const logEntry = { ...safeEntry, timestamp: Date.now() };
+    this.dailyUsed += totalTokens;
     this.requestLog.push(logEntry);
     this.persist();
   }
   getRemaining() {
     this.resetIfNewDay();
-    return Math.max(0, this.dailyBudget - this.dailyUsed);
+    return Math.max(0, safeNumber(this.dailyBudget) - safeNumber(this.dailyUsed));
   }
   getUsagePercentage() {
     this.resetIfNewDay();
-    return this.dailyBudget > 0 ? this.dailyUsed / this.dailyBudget * 100 : 0;
+    const budget = safeNumber(this.dailyBudget);
+    const used = safeNumber(this.dailyUsed);
+    return budget > 0 ? used / budget * 100 : 0;
   }
   getStatusText() {
     const pct = Math.round(this.getUsagePercentage());
@@ -5466,8 +5499,16 @@ var TokenBudget = class {
       const data = JSON.parse(raw);
       const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
       if (data.lastResetDate === today) {
-        this.dailyUsed = data.dailyUsed ?? 0;
-        this.requestLog = data.requestLog ?? [];
+        const restored = safeNumber(data.dailyUsed);
+        if (!isNaN(restored)) {
+          this.dailyUsed = restored;
+        }
+        this.requestLog = (data.requestLog ?? []).map((entry) => ({
+          ...entry,
+          inputTokens: safeNumber(entry.inputTokens),
+          outputTokens: safeNumber(entry.outputTokens),
+          totalTokens: safeNumber(entry.totalTokens)
+        }));
       }
       this.lastResetDate = data.lastResetDate ?? today;
     } catch (err) {
@@ -5592,7 +5633,6 @@ var PermissionManager = class {
   askHandler;
   autoApproveAll = false;
   elevatedCommands = /* @__PURE__ */ new Set();
-  pendingApprovals = /* @__PURE__ */ new Set();
   currentChannelType = "cli";
   tempScopes = [];
   constructor() {
@@ -5635,12 +5675,6 @@ var PermissionManager = class {
   isShellElevated() {
     return this.elevatedCommands.has("run_command");
   }
-  addPendingApproval(baseCommand) {
-    this.pendingApprovals.add(baseCommand);
-  }
-  clearPendingApprovals() {
-    this.pendingApprovals.clear();
-  }
   load() {
     if (existsSync7(PERMISSIONS_FILE)) {
       try {
@@ -5699,6 +5733,9 @@ var PermissionManager = class {
       if (mode === "write" && tempScope.write) return { allowed: true };
       return { allowed: false, reason: `Permission denied: ${mode} access to ${path3}` };
     }
+    if (!this.autoApproveAll && this.askHandler && this.currentChannelType !== "internal") {
+      return this.requestScopeExternal(path3, mode);
+    }
     return { allowed: false, reason: `Permission denied for ${mode} access to ${path3}` };
   }
   async checkShellCommand(command) {
@@ -5716,10 +5753,6 @@ var PermissionManager = class {
     }
     const trimmed = command.trim();
     const baseCmd = trimmed.split(/\s+/)[0];
-    if (this.pendingApprovals.has(baseCmd)) {
-      logger.info({ cmd: trimmed }, "Shell command auto-approved (pending approval)");
-      return { allowed: true, needsApproval: false };
-    }
     for (const pattern of shell.blocked) {
       if (this.matchPattern(trimmed, pattern)) {
         return { allowed: false, reason: `Blocked command: matches "${pattern}"`, needsApproval: false };
@@ -5742,7 +5775,7 @@ var PermissionManager = class {
     }
     for (const pattern of shell.needsApproval) {
       if (this.matchPattern(trimmed, pattern)) {
-        if (this.currentChannelType === "telegram" && this.askHandler) {
+        if (this.askHandler && this.currentChannelType !== "internal") {
           const result = await this.askHandler(`Run command: ${trimmed}`);
           if (result === "yes") {
             return { allowed: true, needsApproval: false };
@@ -5756,7 +5789,7 @@ var PermissionManager = class {
         return { allowed: false, reason: `Command requires approval: matches "${pattern}"`, needsApproval: true };
       }
     }
-    if (this.currentChannelType === "telegram" && this.askHandler) {
+    if (this.askHandler && this.currentChannelType !== "internal") {
       const result = await this.askHandler(`Run command: ${trimmed}`);
       if (result === "yes") {
         return { allowed: true, needsApproval: false };
@@ -5862,6 +5895,11 @@ Allow access?`;
     return null;
   }
   mergeDefaults(parsed) {
+    const mergeArray = (existing, defaults) => {
+      if (!existing) return [...defaults];
+      const combined = /* @__PURE__ */ new Set([...defaults, ...existing]);
+      return [...combined];
+    };
     return {
       capabilities: {
         filesystem: {
@@ -5870,9 +5908,9 @@ Allow access?`;
         },
         shell: {
           enabled: parsed.capabilities?.shell?.enabled ?? DEFAULT_MANIFEST.capabilities.shell.enabled,
-          blocked: parsed.capabilities?.shell?.blocked ?? DEFAULT_MANIFEST.capabilities.shell.blocked,
-          autoApproved: parsed.capabilities?.shell?.autoApproved ?? DEFAULT_MANIFEST.capabilities.shell.autoApproved,
-          needsApproval: parsed.capabilities?.shell?.needsApproval ?? DEFAULT_MANIFEST.capabilities.shell.needsApproval,
+          blocked: mergeArray(parsed.capabilities?.shell?.blocked, DEFAULT_MANIFEST.capabilities.shell.blocked),
+          autoApproved: mergeArray(parsed.capabilities?.shell?.autoApproved, DEFAULT_MANIFEST.capabilities.shell.autoApproved),
+          needsApproval: mergeArray(parsed.capabilities?.shell?.needsApproval, DEFAULT_MANIFEST.capabilities.shell.needsApproval),
           cwdOnly: parsed.capabilities?.shell?.cwdOnly ?? DEFAULT_MANIFEST.capabilities.shell.cwdOnly
         },
         git: {
@@ -6222,20 +6260,13 @@ function createRunCommandTool(permissions, getCwd, setCwd) {
     description: `Run a shell command in the current working directory. Use the cd tool to change directories first \u2014 cd commands within this tool only affect chained commands (e.g., "cd /path && ls"), not subsequent calls.
 Blocked commands (sudo, rm -rf /, etc.) are never executed.
 Auto-approved commands (ls, cat, git status, curl, etc.) run without asking.
-Other commands require user approval.`,
+Other commands prompt the user for approval before execution.`,
     inputSchema: zodSchema10(z10.object({
       command: z10.string().describe("The shell command to execute")
     })),
     execute: async ({ command }) => {
       const check = await permissions.checkShellCommand(command);
       if (!check.allowed) {
-        if (check.needsApproval) {
-          const baseCmd = command.trim().split(/\s+/)[0];
-          permissions.addPendingApproval(baseCmd);
-          return `\u26A0 Command requires approval: ${command}
-
-Tell the user what this command does and ask for permission. If they approve, try running it again. If they say "always", use the approve_command tool to permanently approve this command type.`;
-        }
         return `Error: ${check.reason}`;
       }
       const cwd = getCwd();
@@ -6711,12 +6742,6 @@ function createGitPushTool(permissions, getCwd) {
     execute: async ({ remote, branch }) => {
       const cmd = `git push ${remote || "origin"} ${branch || ""}`.trim();
       const check = await permissions.checkShellCommand(cmd);
-      if (!check.allowed && check.needsApproval) {
-        const baseCmd = "git";
-        permissions.addPendingApproval(baseCmd);
-        return `\u26A0 This command pushes to a remote: ${cmd}
-Ask the user for permission. If they approve, try again. If they say "always", use the approve_command tool.`;
-      }
       if (!check.allowed) {
         return `Error: ${check.reason}`;
       }