Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
docs: add Chinese translations for README, ARCHITECTURE and CHANGELOG (#53)
Chasen Liaob5f4bb59e442
diff --git a/ARCHITECTURE.zh-CN.md b/ARCHITECTURE.zh-CN.mdnew file mode 100644index 00000000..13445e3b--- /dev/null+++ b/ARCHITECTURE.zh-CN.md@@ -0,0 +1,501 @@+# Mercury — 架构++> 活文档,随系统演进持续更新。++## 概述++Mercury 是一个以灵魂驱动、Token 高效的 AI Agent,全天候运行。它是一个**编排器**,不仅仅是聊天机器人。它能读写文件、运行命令、执行多步骤 Agent 流程——所有操作均受严格权限系统管控。它通过渠道(CLI、Telegram,未来:Signal、Discord、Slack)通信,并维护持久化记忆。++## 人类类比++| Mercury 概念 | 人类类比 | 文件/模块 |+|---|---|---|+| soul.md | 心脏 | `soul/soul.md` |+| persona.md | 面容 | `soul/persona.md` |+| taste.md | 味觉 | `soul/taste.md` |+| heartbeat.md | 呼吸 | `soul/heartbeat.md` |+| 短期记忆 | 工作记忆 | `src/memory/store.ts` |+| 情景记忆 | 近期经历 | `src/memory/store.ts` |+| 长期记忆 | 人生经验 | `src/memory/store.ts` |+| 第二大脑 | 结构化长期用户模型 | `src/memory/user-memory.ts` + `src/memory/second-brain-db.ts` |+| Providers | 感官 | `src/providers/` |+| Capabilities | 手与工具 | `src/capabilities/` |+| Permissions | 边界 | `src/capabilities/permissions.ts` |+| Channels | 沟通 | `src/channels/` |+| Heartbeat/调度器 | 生物钟 | `src/core/scheduler.ts` |+| 生命周期 | 醒着/睡眠/思考 | `src/core/lifecycle.ts` |+| 子 Agent | 工蜂 | `src/core/sub-agent.ts` + `src/core/supervisor.ts` |+| 文件锁 | 协调 | `src/core/file-lock.ts` |+| 任务板 | 共享状态 | `src/core/task-board.ts` |+| 资源管理器 | 容量规划 | `src/core/resource-manager.ts` |++## 目录结构++```+src/+├── index.ts # CLI 入口 (commander)+├── channels/ # 通信接口+│ ├── base.ts # 抽象渠道+│ ├── cli.ts # CLI 适配器 (readline + 内联权限提示)+│ ├── telegram.ts # Telegram 适配器 (grammY)+│ └── registry.ts # 渠道管理器+├── core/ # 渠道无关的脑子+│ ├── agent.ts # 多步骤 Agent 循环 (generateText + tools)+│ ├── lifecycle.ts # 状态机+│ ├── scheduler.ts # Cron + 心跳+│ ├── sub-agent.ts # 子 Agent 工作器 (隔离的 Agent 循环)+│ ├── supervisor.ts # 子 Agent 监督器 (生成/停止/编排)+│ ├── file-lock.ts # 文件锁管理器 (读写锁)+│ ├── task-board.ts # 共享任务状态持久化+│ └── resource-manager.ts # 系统资源检测+├── capabilities/ # Agent 工具 & 权限+│ ├── permissions.ts # 权限管理器 (读写作用域、Shell 黑名单)+│ ├── registry.ts # 注册所有 AI SDK 工具 + skill/调度器工具+│ ├── filesystem/ # 文件操作:读、写、创建、列表、删除+│ ├── shell/ # Shell 执行(含黑名单)+│ ├── skills/ # Skill 管理工具+│ │ ├── install-skill.ts+│ │ ├── list-skills.ts+│ │ └── use-skill.ts+│ └── scheduler/ # 调度工具+│ ├── schedule-task.ts+│ ├── list-tasks.ts+│ └── cancel-task.ts+│ └── subagents/ # 子 Agent 工具+│ ├── delegate-task.ts+│ ├── list-agents.ts+│ └── stop-agent.ts+├── memory/ # 持久化层+│ ├── store.ts # 短/长/情景记忆+│ ├── second-brain-db.ts # SQLite 存储引擎 (FTS5)+│ └── user-memory.ts # 第二大脑:自主结构化记忆+├── providers/ # LLM API+│ ├── base.ts # 抽象 Provider + getModelInstance()+│ ├── openai-compat.ts+│ ├── anthropic.ts+│ └── registry.ts+├── soul/ # 意识+│ └── identity.ts # Soul/persona/taste 加载器 + 护栏+├── skills/ # 模块化能力 (Agent Skills 规范)+│ ├── types.ts # SkillMeta, SkillDiscovery, Skill 类型+│ ├── loader.ts # SKILL.md 解析器,渐进式披露+│ └── index.ts # 桶式导出+├── types/ # 类型定义+└── utils/ # 配置、日志、Token+```++## Agent 循环++Mercury 使用 Vercel AI SDK 的多步 `generateText()` 配合工具:++```+用户消息 → Agent 加载系统提示 (soul + 护栏 + persona)+ → Agent 调用 generateText({ tools, maxSteps: 10 })+ → LLM 决定:回复文本 或 调用工具+ → 如果调用工具:+ → 权限检查 (文件系统作用域 / Shell 黑名单)+ → 如果允许:执行工具,返回结果给 LLM+ → 如果拒绝:LLM 收到拒绝消息,调整方案+ → LLM 继续 (下一步) — 可能调用更多工具或回复+ → 如果文本:最终响应返回给用户+ → Agent 通过渠道发送最终响应+```++## 权限系统++### 文件系统权限(目录级作用域)++- 没有作用域的路径 = **无访问**,必须询问用户+- 用户可授予:`y`(一次性)、`always`(保存到清单)、`n`(拒绝)+- 清单保存在 `~/.mercury/permissions.yaml`+- 可随时编辑 — Mercury 不会绕过++### Shell 权限++- **阻止**(永不执行):`sudo *`、`rm -rf /`、`mkfs`、`dd if=`、`fork bombs`、`shutdown`、`reboot`+- **自动批准**(无需提示):`ls`、`cat`、`pwd`、`git status/diff/log`、`node`、`npm run/test`+- **需要批准**:`npm publish`、`git push`、`docker`、`rm -r`、`chmod`、`管道 `curl | sh`+- 命令限制在 CWD + 批准的文件作用域内++### 内联权限 UX++当 Mercury 需要没有的作用域时:+```+ ⚠ Mercury 需要写入 ~/projects/myapp 的权限。允许?(y/n/always):+ > always+ [作用域已保存到 ~/.mercury/permissions.yaml]+```++## 工具++| 工具 | 描述 | 权限检查 |+|---|---|---|+| `read_file` | 读取文件内容 | 路径的读作用域 |+| `write_file` | 写入已有文件 | 路径的写作用域 |+| `create_file` | 创建新文件 + 目录 | 父目录的写作用域 |+| `list_dir` | 列出目录内容 | 路径的读作用域 |+| `delete_file` | 删除文件 | 写作用域,总需确认 |+| `run_command` | 执行 Shell 命令 | 黑名单 + 批准列表 + 作用域 |+| `install_skill` | 从内容或 URL 安装 Skill | 无限制 |+| `list_skills` | 列出已安装的 Skill | 无限制 |+| `use_skill` | 加载并调用 Skill 指令 | 无限制 |+| `schedule_task` | 调度循环 Cron 任务 | 验证 Cron 表达式 |+| `list_scheduled_tasks` | 列出调度任务 | 无限制 |+| `cancel_scheduled_task` | 取消调度任务 | 无限制 |++## Agent 生命周期++```+unborn → birthing → onboarding → idle ⇄ thinking → responding → idle+ ↓+ idle → sleeping → awakening → idle+```++## 运行时数据位置++所有运行时数据位于 `~/.mercury/`(而非项目目录):++| 内容 | 位置 |+|---|---|+| 配置 | `~/.mercury/mercury.yaml` |+| Soul 文件 | `~/.mercury/soul/*.md` |+| 记忆 | `~/.mercury/memory/` |+| Skills | `~/.mercury/skills/` |+| 调度 | `~/.mercury/schedules.yaml` |+| 权限 | `~/.mercury/permissions.yaml` |++## Token 预算++- 系统提示(soul + 护栏 + persona):每次请求约 500 Token+- 短期上下文:最近 10 条消息+- 长期事实:关键词匹配,约注入 3 条事实+- 第二大脑:通过 `retrieveRelevant()` 注入相关用户记忆(约 900 字符)+- 默认每日限额:1,000,000 Token++## 第二大脑++Mercury 的第二大脑是一个自主、持久的用户模型,从对话中学习。它不是原始聊天记录,也不是文档转储。它存储紧凑的结构化记忆,认为这些可能有助于未来的对话。++### 它如何学习(后台、无感)++每轮非平凡对话:+1. Mercury 正常回复用户。+2. 之后后台调用 `extractMemory()` 提取 0-3 条带类型的记忆候选(preference、goal、project 等),使用独立 LLM 调用(约 800 Token)。+3. 每条候选经过 `UserMemoryStore.remember()` 处理,该函数:+ - 如果重叠度 >= 74% 则与现有记忆合并(增强证据)+ - 自动解决冲突(更高置信度胜出,相同置信度 → 更新者胜出)+ - 自动分层:identity/preference → durable,goal/project → active+ - 3+ 次强化后自动晋升:active → durable+ - 存储低置信度弱记忆 — 它们自然衰减+4. 每次心跳时,Mercury 进行整合(重新合成 profile/active 摘要,生成反思记忆)并修剪(清除陈旧记忆,强化已晋升者)。++用户永远不会看到或等待这个过程。Agent 循环中不涉及工具调用。++### 它不存储什么++- 问候语、寒暄、客套话+- 低信号的一次性细节(低于 0.55 置信度下限)+- 推测性的助手猜测++### `/memory` 命令++```+/memory → 打开方向键菜单 (CLI) 或发送概览 (Telegram)++菜单:+ Overview — 记忆总数、按类型细分、学习状态+ Recent — 最近 10 条记忆(类型 + 摘要 + 置信度)+ Search — 全文本搜索所有记忆+ Pause Learning — 切换:停止/恢复存储新记忆+ Clear All — 确认后清除所有记忆+ Back+```++### 用户控制++第二大脑在学习和管理上是自主的。用户的唯一控制是:+- **暂停/恢复**学习(用于敏感对话)+- **清除全部**记忆(重新开始)+- **观察**通过概览、最近和搜索++无审核队列、无手动固定、无手动冲突解决、无手动编辑。++## 渠道++### CLI+- 基于 Readline,带内联权限提示+- `mercury start` 或直接 `mercury`++### Telegram+- grammY 框架 + @grammyjs/stream 流式处理+- 处理中显示 Typing 指示器+- 通过心跳主动发送消息+- `.env` 或 `mercury.yaml` 中的 `TELEGRAM_BOT_TOKEN`++## Skill 系统++Mercury 支持 Agent Skills 规范。Skill 是模块化的可安装指令集,无需代码更改即可扩展 Mercury 的能力。++### Skill 格式++每个 Skill 是一个位于 `~/.mercury/skills/` 下的目录,包含 `SKILL.md`:++```+~/.mercury/skills/+├── daily-digest/+│ └── SKILL.md # 必需:YAML 前置元数据 + markdown 指令+├── code-review/+│ ├── SKILL.md+│ ├── scripts/ # 可选:可执行脚本+│ └── references/ # 可选:参考文档+└── _template/+ └── SKILL.md # 新 Skill 的种子模板+```++### SKILL.md 结构++```markdown+---+name: daily-digest+description: 发送每日活动摘要+version: 0.1.0+allowed-tools:+ - read_file+ - list_dir+ - run_command+---++# Daily Digest++当此 Skill 被调用时,Mercury 遵循的指令...+```++### 渐进式披露++- **启动时**:仅加载 Skill 名称 + 描述(Token 高效)+- **调用时**:按需通过 `use_skill` 工具加载完整 Skill 指令+- 这样系统提示保持精简,同时 Skill 可用++### Skill 工具++- `install_skill`:从 markdown 内容或 URL 安装+- `list_skills`:显示所有已安装的 Skill+- `use_skill`:加载并将 Skill 指令注入 Agent 上下文++## 调度器++Mercury 可以使用 cron 表达式调度循环任务。任务持久化到 `~/.mercury/schedules.yaml`,并在启动时恢复。++### 调度任务字段++| 字段 | 描述 |+|---|---|+| `id` | 唯一任务标识符 |+| `cron` | 标准 5 字段 cron 表达式 |+| `description` | 人类可读描述 |+| `prompt` | 任务触发时发送给 Agent 的文本提示 |+| `skill_name` | 可选:任务触发时调用的 Skill |+| `createdAt` | ISO 时间戳 |++### 任务如何执行++当调度任务触发时:+1. 如果设置了 `skill_name`,Mercury 通过 `use_skill` 调用该 Skill+2. 如果设置了 `prompt`,Mercury 将其作为内部(非渠道)消息处理+3. 内部消息不会产生可见的渠道响应 — 它们在 Agent 循环中静默运行++### 调度工具++- `schedule_task`:创建带 prompt 或 skill_name 的 Cron 任务+- `list_scheduled_tasks`:显示所有调度任务+- `cancel_scheduled_task`:移除调度任务++## 子 Agent++Mercury 支持子 Agent — 作为异步协程在同一 Node.js 进程中运行的独立工作进程。子 Agent 允许 Mercury 并发处理多个任务而不阻塞主 Agent。++### 为什么用子 Agent?++- **非阻塞**:主 Agent 在子 Agent 工作时保持对新消息的可用性+- **资源感知**:最大并发数根据 CPU 核心数和可用 RAM 自动检测+- **协调**:文件锁防止 Agent 间冲突写入+- **可控**:`/agents`、`/halt`、`/stop`、`/reset` 命令供用户完全控制+- **非阻塞**:子 Agent 在后台运行 — 主 Agent 保持对新消息的响应+- **可见**:进度通知(`🔄 Agent a1: Using: read_file`)和完成消息(`✅ Agent a1 completed (8.2s)`)发送到用户渠道+- **快速命令**:斜杠命令如 `/agents`、`/halt`、`/spotify`、`/code` 即使在主 Agent 繁忙时也立即处理++### 架构++```+用户消息 → 主 Agent → 决定:+ ├─ 快速响应 → 直接处理并回复+ └─ 重型任务 → delegate_task 工具 → 生成子 Agent(非阻塞)+ → 主 Agent 回复:"🤖 Agent a1 正在处理..."+ → 主 Agent 保持对下一条消息的可用性+ → 子 Agent 进度:"🔄 Agent a1: Using: read_file, edit_file"+ → 子 Agent 完成:"✅ Agent a1 completed (8.2s): result..."+ → 用户可随时输入 /agents 检查状态+```++### 组件概述++| 组件 | 文件 | 用途 |+|---|---|---|+| SubAgent | `src/core/sub-agent.ts` | 工作器:带中止、文件锁、进度的隔离 Agent 循环 |+| SubAgentSupervisor | `src/core/supervisor.ts` | 编排器:生成/停止/队列、资源管理 |+| FileLockManager | `src/core/file-lock.ts` | 读写锁:多读者、排他写者、自动释放 |+| TaskBoard | `src/core/task-board.ts` | 共享状态:任务状态、进度、持久化到磁盘 |+| ResourceManager | `src/core/resource-manager.ts` | 系统检测:CPU 核心数、RAM、最大并发公式 |++### 资源限制++默认最大并发子 Agent = `clamp(1, cpus - 1, floor(availableRAM_GB / 2))`++通过 `/agents set max <n>` 或 `SUBAGENTS_MAX_CONCURRENT` 环境变量覆盖。++### 生命周期++```+unborn → birthing → onboarding → idle ⇄ thinking → responding → idle+ ↓+ idle → delegating → idle+ idle → sleeping → awakening → idle+```++`delegating` 状态涵盖主 Agent 将任务交给子 Agent 时。++### 子 Agent 工具++| 工具 | 描述 |+|---|---|+| `delegate_task` | 将任务委托给子 Agent 工作器 |+| `list_agents` | 列出活跃子 Agent 及其状态 |+| `stop_agent` | 停止子 Agent(或全部) |++### 用户命令++| 命令 | 描述 |+|---|---|+| `/agents` | 列出所有子 Agent(状态、任务、进度) |+| `/agents stop <id>` | 停止特定子 Agent |+| `/agents stop all` | 停止所有子 Agent |+| `/agents pause <id>` | 在当前步骤后暂停子 Agent |+| `/agents resume <id>` | 恢复暂停的子 Agent |+| `/agents config` | 显示资源分配 |+| `/agents set max <n>` | 覆盖最大并发 Agent 数 |+| `/halt` | 紧急停止所有 Agent + 清除队列 |+| `/stop` | 停止所有 Agent + 清除队列 + 释放锁 + 清除任务板 |+| `/reset` | 完全重置:停止所有 + 清除上下文(需要确认) |++### 编程模式++Mercury 有内置编程模式(通过 `/code plan` 激活),针对 IDE 级编码任务进行优化。它在两种状态下运行:++**计划模式**(`/code plan`):Mercury 探索代码库、分析问题、通过 `ask_user` 呈现多种方案,并勾勒逐步实现计划 — 不写代码。++**执行模式**(`/code execute`):Mercury 逐步实现批准的计划,在更改后运行构建/测试,在检查点提交,并将独立子任务委托给子 Agent。++| 命令 | 描述 |+|---|---|+| `/code` | 显示当前编程模式状态 |+| `/code plan` | 切换到计划模式(分析、呈现选项、不编码) |+| `/code execute` | 切换到执行模式(逐步实现计划) |+| `/code off` | 退出编程模式 |+| `/code toggle` | 循环:off → plan → execute → off |++`ask_user` 工具使 Mercury 能够在 CLI 中呈现选项(方向键菜单)和 Telegram 中呈现选项(内联键盘)。++### 文件锁语义++- **读锁**:多个子 Agent 可以同时读取同一文件+- **写锁**:排他性 — 一次只有一个 Agent 可以写入文件+- **自动释放**:当子 Agent 终止时锁释放(完成、失败或停止)+- **死锁检测**:监督器检测 Agent 之间的循环等待条件++### 任务板持久化++所有子 Agent 任务状态持久化到 `~/.mercury/memory/task-board.json`,在进程重启后存活。++### 配置++```yaml+subagents:+ enabled: true # 启用/禁用子 Agent 系统+ maxConcurrent: 0 # 0 = 从 CPU/RAM 自动检测,>0 = 手动覆盖+ mode: auto # auto = 自动检测,manual = 使用 maxConcurrent 值+```++环境变量覆盖:`SUBAGENTS_ENABLED`、`SUBAGENTS_MAX_CONCURRENT`、`SUBAGENTS_MODE`++## Spotify 集成++Mercury 可以通过 Spotify Web API 远程控制用户的 Spotify 播放。音乐播放在用户自己的设备上(手机、网页、桌面、TV、音箱)— 不在本地。++### 设置++1. 在 https://developer.spotify.com/dashboard 创建 Spotify 应用+2. 将重定向 URI 设置为 `http://127.0.0.1:8888/callback`+3. 在 `.env` 中设置 `SPOTIFY_CLIENT_ID` 和 `SPOTIFY_CLIENT_SECRET`+4. 在 Mercury 中运行 `/spotify auth` — 这会打开浏览器进行 OAuth 授权+5. 令牌保存在 `~/.mercury/mercury.yaml` 中并自动刷新++### 设备选择++Spotify 的设备 API 列出了用户登录的所有活跃设备。Mercury 将播放/暂停/跳过命令发送到用户选择的设备 — 它从不本地播放音频。++### DJ Skill++`spotify` Skill(`/skills/spotify/SKILL.md`)激活 DJ 模式:+- 根据心情/流派/活动搜索 Spotify+- 通过 `ask_user` 呈现选项(CLI 方向键,Telegram 内联按钮)+- 管理播放、队列、喜欢和播放列表+- 根据用户口味创建策划播放列表++### 播放器 UI++**CLI**:`/spotify player` 打开交互式方向键菜单:+```+ ▶ 播放 / 恢复+ ⏸ 暂停+ ⏭ 下一曲+ ⏮ 上一曲+ 🔀 切换随机播放+ 🔁 循环模式+ 🎵 正在播放+ 📱 设备+ 🔍 搜索并播放+ 🔊 设置音量+ 📋 加入队列+ ❤️ 喜欢当前曲目+ ✕ 退出播放器+```++**Telegram**:播放控制作为内联键盘按钮。++### 命令++| 命令 | 描述 |+|---|---|+| `/spotify` | 显示连接状态 |+| `/spotify auth` | 开始 OAuth 流程(打开浏览器) |+| `/spotify player` | 交互式播放器(仅 CLI) |+| `/spotify devices` | 列出活跃 Spotify 设备 |+| `/spotify device <id>` | 设置活跃设备 |+| `/spotify now` | 显示当前播放曲目 |++### 配置++```yaml+spotify:+ enabled: true+ clientId: ...+ clientSecret: ...+ redirectUri: http://127.0.0.1:8888/callback+ accessToken: ...+ refreshToken: ...+ expiresAt: ...+ scopes: [...]+ deviceId: ...+```++环境变量覆盖:`SPOTIFY_CLIENT_ID`、`SPOTIFY_CLIENT_SECRET`、`SPOTIFY_REDIRECT_URI`\ No newline at end of filediff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.mdnew file mode 100644index 00000000..729c22be--- /dev/null+++ b/CHANGELOG.zh-CN.md@@ -0,0 +1,206 @@+# 更新日志++## 1.1.5 — 更顺畅的引导流程++### 修复:引导流程不再阻塞没有 Ollama 的用户++引导流程存在一个关键 UX 问题:如果用户没有本地运行的 Ollama 或没有现成的 API key,他们会陷入无限循环,无法跳过。这是一个重大体验改进。++**主要变化:**++1. **Ollama 本地现可跳过** — 如果 Ollama 没有运行,你可以直接跳过或手动输入模型名称。不会再有无限的重复循环。++2. **所有 Provider 设置允许跳过** — 每个 API key 提示现在在 Provider API 不可达时都提供手动模型名称输入选项和跳过选项。错误消息从红色(失败)改为黄色(警告)以减少挫败感。++3. **移除"无 Provider"陷阱** — 之前如果你无法配置任何 Provider,就会陷入无限循环。现在你可以输入"skip"保存配置稍后通过 `mercury doctor` 回来,并显示关于 DeepSeek 免费 API 的提示。++4. **清除 Ollama 本地默认模型** — 默认值是 `gpt-oss:20b`(非标准模型)。现在默认为空,首选模型列表使用常见名称如 `llama3.2`、`mistral`、`phi3` 等。++5. **更清晰的首次运行说明** — LLM Provider 步骤现在显示"你可以按 Enter 跳过任何 Provider"并注明 DeepSeek 提供免费 key。++### 变更摘要++| 文件 | 变更 |+|------|--------|+| `src/index.ts` | `promptOllamaLocalModelSelection` — 允许跳过 base URL,获取失败时手动输入模型 |+| `src/index.ts` | `promptApiKeyWithModelSelection` — API 获取失败时手动输入模型,提供跳过选项 |+| `src/index.ts` | `configure()` — 无 Provider 配置时提供"skip"选项,显示免费 key 提示 |+| `src/utils/config.ts` | Ollama 本地默认模型从 `gpt-oss:20b` 改为空字符串 |+| `src/utils/provider-models.ts` | Ollama 本地首选模型更新为常见名称 |++## 1.1.4 — OpenAI 兼容 Provider & Provider 可见性++### 新增:OpenAI 兼容 Provider++一个专用于**自托管、第三方或任何 OpenAI 兼容 API** 的新 Provider — 无论是在你的系统上、自托管还是云服务。社区需要一种连接任意 OpenAI 兼容端点的方式,而不绑定到特定供应商。++**设置向导流程:**+1. 输入服务器 base URL(必需)— 例如 `http://localhost:8000/v1` 或 `https://my-llm.example.com/v1`+2. 可选输入 API key(按 Enter 跳过 — 本地/自托管服务器通常不需要)+3. Mercury 尝试从 `/models` 端点获取模型列表+4. 如果成功 — 显示交互式模型选择器并提供输入自定义名称的选项+5. 如果获取失败 — 提示手动输入模型名称+6. 你可以随时在保存前输入自定义模型名称++**关键设计点:**+- API key 是**可选的** — 本地和自托管服务器通常无需身份验证即可运行+- 使用 Chat Completions API(`/chat/completions`),而非 Responses API(`/responses`)+- `isProviderConfigured` 需要 `baseUrl + model` 但不需要 `apiKey`+- 不过滤模型名称 — 接受服务器返回的所有模型 ID+- 可设置为默认 Provider+- 环境变量:`OPENAI_COMPAT_API_KEY`、`OPENAI_COMPAT_BASE_URL`、`OPENAI_COMPAT_MODEL`、`OPENAI_COMPAT_ENABLED`++### 新增:会话启动时的 Provider & 模型可见性++活动 Provider 和模型现在在会话启动时突出显示 — 一个**洋红色徽章**(`⚡ Provider · Model`)让人立即清楚正在使用哪个 LLM。完整 Provider 列表显示在下方,带 `← default` 标记。++之前:+```+ Providers: DeepSeek, OpenAI+ Models: DeepSeek: deepseek-chat | OpenAI: gpt-4o-mini+```++之后:+```+ ⚡ DeepSeek · deepseek-chat+ Providers: DeepSeek: deepseek-chat ← default · OpenAI: gpt-4o-mini+```++### 修复:`fetchOpenAICompatModels` 可选 API key 处理++内部 `fetchOpenAICompatModels` 函数现在仅在配置了 API key 时才发送 `Authorization: Bearer` header — 之前即使 key 为空也会发送 header,导致不需要 auth header 的本地服务器出现认证错误。++`OpenAICompatProvider` 现在也通过传递 `'no-key'` 作为 `createOpenAI()` 的回退值来优雅处理空 API key,防止在未认证服务器上崩溃。++### 变更摘要++| 文件 | 变更 |+|------|--------|+| `src/utils/config.ts` | 添加 `openaiCompat` 到 `ProviderName`、配置接口、默认值、`isProviderConfigured()` |+| `src/providers/registry.ts` | 路由 `openaiCompat` → `OpenAICompatProvider`,`useChatApi: true` |+| `src/providers/openai-compat.ts` | 使用 `'no-key'` 回退处理空 API key 以配合 `createOpenAI()` |+| `src/utils/provider-models.ts` | `OPENAI_COMPAT_PREFERRED_MODELS`、模型获取中的可选 auth header、`openaiCompat` 不过滤模型、路由 |+| `src/index.ts` | "OpenAI Compilations" 在 `PROVIDER_OPTIONS` 中,`promptOpenAICompatSetup()` 使用获取→回退流程,会话启动时显示洋红色默认 Provider 徽章 |+| `.env.example` | 添加 `OPENAI_COMPAT_*` 环境变量 |+| `src/utils/provider-models.test.ts` | 添加 2 个 `openaiCompat` 模型目录测试 |++## 1.1.3 — 修复 Ollama Cloud Provider++### 问题描述++Ollama Cloud 完全损坏 — 每个请求都返回 `404 Not Found`。两个独立 bug 导致 `ollamaCloud` 无法工作:++### Bug 1:错误的 SDK — 本地 Ollama API 而非 OpenAI 兼容 Chat Completions++`ollamaCloud` 通过 `OllamaProvider` 路由,该 Provider 使用 `ollama-ai-provider` 包。这个包专为**本地** Ollama 服务器设计,目标是 `/api/chat` 和 `/api/tags` 端点。Ollama Cloud 暴露的是**OpenAI 兼容** API,位于 `/v1/chat/completions` 和 `/v1/models` — 一个完全不同的线格式。++- **模型列表**调用 `${baseUrl}/tags` → `https://ollama.com/api/tags` → 404+- **聊天补全**调用 `${baseUrl}/chat` → `https://ollama.com/api/chat` → 404++**修复**:`ollamaCloud` 现在通过 `OpenAICompatProvider` 路由(使用 `createOpenAI()` 来自 `@ai-sdk/openai`),匹配所有其他 OpenAI 兼容云提供商(MiMo、Grok)使用的模式。++### Bug 2:错误的默认 base URL++默认 `OLLAMA_CLOUD_BASE_URL` 设置为 `https://ollama.com/api` — 本地 Ollama 服务器路径。Ollama Cloud OpenAI 兼容 API 的正确 base URL 是 `https://ollama.com/v1`。++**修复**:更新默认值并添加配置迁移(`migrateLegacyOllamaCloudBaseUrl`),在启动时自动将现有 `mercury.yaml` 文件从 `/api` 升级到 `/v1`。++### Bug 3:Responses API 而非 Chat Completions API++修复 Bug 1 后,`OpenAICompatProvider` 使用 `createOpenAI()()` 默认到 OpenAI 的 **Responses API**(`/responses`)。Ollama Cloud 只支持 **Chat Completions API**(`/chat/completions`),导致 `https://ollama.com/api/responses` → 404。++**修复**:向 `OpenAICompatProvider` 添加 `useChatApi` 选项。启用时(对 `ollamaCloud`),它调用 `client.chat(model)` 而非 `client(model)`,目标是 `/chat/completions`。++### Bug 4:ollamaCloud 没有 baseUrl 验证++`isProviderConfigured()` 和 `OllamaProvider.isAvailable()` 只检查 `ollamaCloud` 的 `apiKey.length > 0` — 缺失或空的 `baseUrl` 不会被捕获,导致在请求时出现神秘故障。++**修复**:在 `isProviderConfigured()` 和 `isAvailable()` 中添加显式 `ollamaCloud` 分支,验证 `apiKey` 和 `baseUrl`。++### 变更摘要++| 文件 | 变更 |+|------|--------|+| `src/providers/registry.ts` | 路由 `ollamaCloud` → `OpenAICompatProvider`,`useChatApi: true` |+| `src/providers/openai-compat.ts` | 添加 `useChatApi` 选项使用 Chat Completions API |+| `src/utils/config.ts` | 默认 base URL `https://ollama.com/api` → `https://ollama.com/v1`;添加 `ollamaCloud` 到 `isProviderConfigured()`;添加 `migrateLegacyOllamaCloudBaseUrl()` |+| `src/utils/provider-models.ts` | 新的 `fetchOllamaCloudModels()` 使用 `/models`(OpenAI 兼容);重命名 `fetchOllamaModels` → `fetchOllamaLocalModels`(仅本地 `/tags`);单独路由 `ollamaCloud` |+| `src/providers/ollama.ts` | `isAvailable()` 也验证非本地 Provider 的 `baseUrl` |+| `.env.example` | `OLLAMA_CLOUD_BASE_URL` 默认值更新为 `https://ollama.com/v1` |+| `src/utils/provider-models.test.ts` | 添加 2 个 `ollamaCloud` 模型目录测试 |++## 1.1.2 — MiMo Provider & 预算加固++## 1.0.0 — 第二大脑++这是一个**主要版本**,因为它引入了第二大脑 — 一个由 SQLite 全文搜索支持的持久化结构化记忆系统 — 以及 Mercury 存储数据和渲染输出的方式的基本变更。++### 为什么是 1.0.0?++Mercury 通过 0.x 版本快速开发。第二大脑功能代表了基本能力转变:Mercury 现在可以**跨对话记忆**,自动提取、整合和召回关于你的事实。结合全 `~/.mercury/` 数据架构和实时 CLI 流式输出,这标记着一个值得主要版本的稳定、生产就绪的基础。++### 第二大脑 🧠++- **10 种记忆类型** — identity、preference、goal、project、habit、decision、constraint、relationship、episode、reflection+- **自动提取** — 每轮对话后提取 0 到 3 条事实,带置信度、重要性和持久性分数+- **相关召回** — 每次消息前在 900 字符预算内注入最匹配的 5 条记忆+- **自动整合** — 每 60 分钟合成个人资料摘要、活跃状态摘要,并从检测到的模式生成反思记忆+- **冲突解决** — 对立记忆按置信度和时间新旧解决;否定检测处理"喜欢 X"与"不喜欢 X"+- **活跃 → 持久晋升** — 记忆被强化 3+ 次后自动从短期 `active` 作用域晋升到长期 `durable` 作用域+- **自动修剪** — 活跃作用域记忆 21 天后过期;推断记忆会衰减;低置信度持久记忆 120 天后 dismissal+- **SQLite + FTS5** — 全文搜索即时召回,所有数据本地存储在 `~/.mercury/memory/second-brain/second-brain.db`+- **用户控制** — `/memory` 用于概览、搜索、暂停、恢复和清除,CLI 和 Telegram 都支持++### CLI 流式输出恢复++- **实时文本流** — 原始响应 Token 流式传输到终端,然后使用正确的 markdown 格式重新渲染完整响应(青色标题带 `■` 标记,黄色代码块, dim 项目符号, dim 边框的块引用)+- **光标保存/恢复** — 使用 `\x1b7`/`\x1b8` ANSI 序列而非脆弱的行计数,消除单行答案的重复响应 bug+- **流式传输期间的工具反馈** — 工具调用在流式传输期间内联显示,并被跟踪以进行准确的输出替换++### 数据架构:全在 `~/.mercury/`++- **之前**:记忆(短期、长期、情景)相对于 CWD 存储在 `./memory/`,在随机项目目录中创建文件+- **之后**:所有状态现在位于 `~/.mercury/` — 配置、soul、记忆、权限、skills、调度、Token 跟踪、守护进程状态+- **`getMemoryDir()`** 辅助函数返回 `~/.mercury/memory/` — 不再有 `memory.dir` 配置字段+- **自动迁移** — 首次运行时,Mercury 检测并移动任何遗留 `./memory/` 目录到 `~/.mercury/memory/`,然后删除旧目录+- **移除的配置字段**:`memory.dir`、`memory.secondBrain.dbPath` — 现在从 `getMercuryHome()` 自动计算++### 权限模式++- **问我** — 文件写入前确认,需要批准的 Shell 命令和作用域更改(CLI 和 Telegram 的默认模式)+- **全部允许** — 自动批准本次会话的所有内容(作用域、命令、循环继续)。重启后重置。+- CLI:启动时方向键菜单。Telegram:首条消息内联键盘,`/permissions` 更改。++### 逐步工具反馈++- **编号步骤** — 每个工具调用获得步骤编号(`1. read_file foo.ts`)+- **旋转器** — 工具执行时显示带已用时间的动画旋转器+- **结果摘要** — 每个步骤后显示简洁结果(例如 `42 行,3 个匹配`)++### 其他变更++- **改进的 markdown 渲染器** — 青色标题带 `■` 标记,黄色内联代码, dim 删除线,蓝色下划线链接带 dim URL,边框块引用,边框表格+- **HTML 实体解码** — 修复 marked HTML 输出的双重编码+- **Telegram 组织访问** — 管理员和成员,具有批准/拒绝/晋升/降级流程+- **引导期间的模型选择** — 验证 API key 后,Mercury 获取可用模型并让你选择+- **Telegram 可编辑状态消息** — 流式更新使用 `editMessageText` 进行实时响应编辑+- **调度任务通知** — Mercury 在调度任务运行时通知原始渠道+- **调度任务的完整临时作用域** — 任务在全部允许模式下运行,作用域自动批准++### 破坏性变更++- 记忆数据路径从 `./memory/` 更改为 `~/.mercury/memory/` — 自动迁移处理+- 配置字段 `memory.dir` 移除 — 无需操作,值被忽略+- 配置字段 `memory.secondBrain.dbPath` 移除 — 路径现在自动计算++### 完整更新日志++**0.5.4** — 修复流式对齐,移除 Agent 名称重复,更干净的块格式+**0.5.3** — 添加 mercury upgrade 命令,ENOTEMPTY 修复+**0.5.2** — 修复 readline 提示处理、流式重新渲染、交互式循环检测、HTML 实体解码+**0.5.1** — Bug 修复+**0.5.0** — Telegram 组织访问、模型选择、更新文档+**0.4.0** — 社交媒体 skills、GitHub 伴侣+**0.3.0** — 权限系统、skill 系统、调度器+**0.2.0** — Telegram 流式传输、文件上传、守护进程模式+**0.1.0** — 初始版本\ No newline at end of filediff --git a/README.zh-CN.md b/README.zh-CN.mdindex ba1bd220..0d8cef4a 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -1,14 +1,38 @@-# Mercury Agent 中文文档+# Mercury — 以灵魂驱动的 AI Agent-> 一个以“灵魂”为中心的 AI Agent,内置权限加固工具、Token 预算、多渠道访问和 SQLite 支持的 Second Brain 记忆。+<p align="center">+ <picture>+ <source media="(prefers-color-scheme: dark)" srcset="docs/img/card-dark.png">+ <source media="(prefers-color-scheme: light)" srcset="docs/img/card-light.png">+ <img alt="Mercury — Soul-Driven AI Agent" src="docs/img/card-light.png" width="600">+ </picture>+</p>-[English](README.md) | 简体中文+<p align="center">+ <strong>以灵魂驱动、内置权限加固工具、Token 预算和多渠道访问的 AI Agent。</strong>+</p>-Mercury 会记住重要信息,在执行有风险的操作前先请求确认,并且可以通过 CLI 或 Telegram 以 24/7 后台进程运行。它适合需要本地文件操作、命令执行、长期记忆、定时任务和多模型兜底能力的个人 AI 助手场景。+<p align="center">+ 记住重要信息。行动前先请求确认。通过 CLI 或 Telegram 全天候运行。31 个内置工具、可扩展的 Skills、基于 SQLite 的第二大脑记忆。+</p>-## 快速开始+<p align="center">+ <a href="https://www.npmjs.com/package/@cosmicstack/mercury-agent"><img src="https://img.shields.io/npm/v/@cosmicstack/mercury-agent" alt="npm"></a>+ <a href="https://github.com/cosmicstack-labs/mercury-agent"><img src="https://img.shields.io/github/license/cosmicstack-labs/mercury-agent" alt="license"></a>+ <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@cosmicstack/mercury-agent" alt="node"></a>+</p>++<p align="center">+ <strong>🔖 当前稳定版:v1.1.6</strong>+</p>++<p align="center">+ <a href="README.md">English</a> | 简体中文+</p>-直接运行:+---++## 快速开始```bashnpx @cosmicstack/mercury-agent@@ -21,223 +45,324 @@ npm i -g @cosmicstack/mercury-agentmercury```-首次运行会启动配置向导(姓名、模型、可选 Telegram)。完成后会进入 Ink TUI 启动画面,并在进入聊天前让你选择权限模式(`Ask Me` / `Allow All`)。之后如需重新配置:+首次运行会触发设置向导(姓名、Provider、可选 Telegram)。设置完成后,Mercury 打开 Ink TUI 启动画面,并在聊天开始前请求权限模式(`Ask Me` 或 `Allow All`)。++之后重新配置(更改 key、名称、设置):```bashmercury doctor+mercury doctor --platform```-## 为什么选择 Mercury+## 为什么选择 Mercury?++每个 AI Agent 都能读写文件、运行命令和获取 URL。大多数默默做这些事。**Mercury 先询问 — 并且记住重要的事。**++- **权限加固** — Shell 黑名单(`sudo`、`rm -rf /` 等永不执行)。目录级读/写作用域。待批准流程。会话级"问我"或"全部允许"。无意外。+- **第二大脑** — 基于 SQLite + FTS5 全文搜索的持久化结构化记忆。10 种记忆类型、自动提取、冲突解决、自动整合。Mercury 无需手动输入即可学习你的偏好、目标和习惯。+- **灵魂驱动** — 人格由你拥有的 Markdown 文件定义(`soul.md`、`persona.md`、`taste.md`、`heartbeat.md`)。无企业包装。+- **Token 感知** — 每日预算强制执行。超过 70% 时自动简洁。`/budget` 命令查看、重置或覆盖。+- **实时流式输出** — CLI 实时 Token 流式输出,带光标保存/恢复和 markdown 重渲染。Telegram 流式输出配合可编辑状态消息。+- **全天候运行** — 在任何操作系统上作为后台守护进程运行。崩溃后自动重启。开机自启。Crontab 调度、心跳监控和主动通知。+- **可扩展** — 一条命令安装社区 Skills。将 Skills 调度为循环任务。基于 [Agent Skills](https://agentskills.io) 规范。-- **权限优先**: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) 规范。+Mercury 现在在首次运行时在 `~/.mercury/skills/web-search/SKILL.md` 中植入默认 `web-search` Skill。## 守护进程模式-推荐使用:+**一条命令让 Mercury 持久化:**```bashmercury up```-该命令会安装系统服务、启动后台守护进程,并确保 Mercury 正在运行。如果 Mercury 已经运行,它只会确认状态并显示 PID。+这会安装系统服务(如果未安装)、启动后台守护进程,并确保 Mercury 正在运行。将此作为你的常用命令。-常用命令:+如果 Mercury 已在运行,`mercury up` 仅确认状态并显示 PID。++### 其他守护进程命令```bashmercury restart # 重启后台进程mercury stop # 停止后台进程-mercury start -d # 后台启动,不安装系统服务+mercury start -d # 后台启动(不安装服务)mercury logs # 查看近期守护进程日志-mercury status # 查看运行状态+mercury status # 显示守护进程是否运行+```++守护进程模式内置崩溃恢复 — 如果进程崩溃,它会自动重启并使用指数退避(最高每分钟 10 次重启)。++### 系统服务(开机自启)++`mercury up` 自动安装此服务。你也可以直接管理它:++```bash+mercury service install```-系统服务支持:+| 平台 | 方式 | 需要管理员 |+|------|------|-----------|+| **macOS** | LaunchAgent (`~/Library/LaunchAgents/`) | 否 |+| **Linux** | systemd user unit (`~/.config/systemd/user/`) | 否(开机自启可能需要 linger) |+| **Windows** | Task Scheduler (`schtasks`) | 否 |-| 平台 | 方式 | 是否需要管理员权限 |-|------|------|--------------------|-| macOS | LaunchAgent (`~/Library/LaunchAgents/`) | 否 |-| Linux | systemd user unit (`~/.config/systemd/user/`) | 否,开机启动可能需要 linger |-| Windows | Task Scheduler (`schtasks`) | 否 |+```bash+mercury service status # 检查服务是否运行+mercury service uninstall # 移除系统服务+```++在守护进程模式下,Telegram 成为主要渠道 — CLI 是纯日志,因为没有终端输入。## CLI 命令-| 命令 | 说明 |+| 命令 | 描述 ||------|------|-| `mercury up` | 推荐命令:安装服务、启动守护进程并确保运行 |-| `mercury` | 启动 Agent,等同于 `mercury start` |+| `mercury up` | **推荐。** 安装服务 + 启动守护进程 + 确保运行 |+| `mercury` | 启动 Agent(等同于 `mercury start`) || `mercury start` | 前台启动 |-| `mercury start -d` | 后台启动 |+| `mercury start -d` | 后台启动(守护进程模式) || `mercury restart` | 重启后台进程 || `mercury stop` | 停止后台进程 |-| `mercury logs` | 查看近期日志 |-| `mercury doctor` | 重新配置 Mercury(姓名、Provider、频道、权限默认项) |-| `mercury setup` | 重新运行配置向导 |-| `mercury status` | 查看配置和守护进程状态 |-| `mercury help` | 查看完整手册 |+| `mercury logs` | 查看近期守护进程日志 |+| `mercury doctor` | 重新配置(姓名、Provider、渠道、权限默认项) |+| `mercury doctor --platform` | 显示跨平台终端/守护进程兼容性诊断 |+| `mercury setup` | 重新运行设置向导 |+| `mercury status` | 显示配置和守护进程状态 |+| `mercury help` | 显示完整手册 || `mercury upgrade` | 升级到最新版本 |-| `mercury telegram list` | 查看已批准和待处理的 Telegram 用户 |+| `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 reject <id>` | 拒绝待处理的 Telegram 访问请求 |+| `mercury telegram remove <id>` | 移除已批准的 Telegram 用户 |+| `mercury telegram promote <id>` | 将 Telegram 成员晋升为管理员 || `mercury telegram demote <id>` | 将 Telegram 管理员降级为成员 |-| `mercury telegram reset` | 清空 Telegram 访问状态并重新开始 |-| `mercury service install` | 安装开机自启系统服务 |+| `mercury telegram reset` | 清除所有 Telegram 访问并重新开始 |+| `mercury service install` | 安装为系统服务(开机自启) || `mercury service uninstall` | 卸载系统服务 |-| `mercury service status` | 查看系统服务状态 |+| `mercury service status` | 显示系统服务状态 || `mercury --verbose` | 使用调试日志启动 |## 对话内命令-这些命令可在 CLI 或 Telegram 对话中输入,不消耗 API Token。+在对话中输入这些 — 它们不消耗 API Token。CLI 和 Telegram 都适用。-| 命令 | 说明 |+| 命令 | 描述 ||------|------|-| `/help` | 查看完整手册 |-| `/status` | 查看 Agent 配置、预算和用量 |-| `/tools` | 列出已加载工具 |-| `/skills` | 列出已安装 Skill |+| `/help` | 显示完整手册 |+| `/status` | 显示 Agent 配置、预算和用量 |+| `/tools` | 列出所有已加载的工具 |+| `/skills` | 列出已安装的 Skills || `/stream` | 切换 Telegram 文本流式输出 |-| `/stream off` | 关闭流式输出,改为单条消息 |-| `/budget` | 查看 Token 预算状态 |-| `/budget override` | 为单次请求临时覆盖预算 |+| `/stream off` | 禁用流式输出(单条消息) |+| `/budget` | 显示 Token 预算状态 |+| `/budget override` | 单次请求覆盖预算 || `/budget reset` | 将用量重置为零 |-| `/budget set <n>` | 修改每日 Token 预算 |-| `/permissions` | 修改权限模式 |-| `/view` | 切换进度视图(balanced/detailed) |-| `/view balanced` | 使用精简进度视图 |-| `/view detailed` | 使用详细进度视图 |-| `/tasks` | 列出定时任务 |-| `/memory` | 查看和管理 Second Brain 记忆 |+| `/budget set <n>` | 更改每日 Token 预算 |+| `/permissions` | 更改权限模式(问我 / 全部允许) |+| `/view` | 切换进度视图(平衡 / 详细) |+| `/view balanced` | 设置精简进度视图 |+| `/view detailed` | 设置完整进度视图 |+| `/code agent <task>` | 将编码任务委托给后台子 Agent |+| `/ws exit` | 退出工作区 IDE 模式回到常规聊天 |+| `/tasks` | 列出调度任务 |+| `/memory` | 查看和管理第二大脑记忆 || `/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` |+| **文件系统** | `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 | Ink TUI、启动权限模式选择、交互式权限审批(方向键 + Enter,支持 Y/N/A 快捷键)、balanced/detailed 进度视图、实时文本流 |-| Telegram | HTML 格式化、可编辑流式消息、文件上传、输入状态、多用户访问和管理员/成员角色 |+| **CLI** | Ink TUI、启动权限模式选择器、交互式权限提示(方向键 + Enter;Y/N/A 快捷键)、进度视图(平衡/详细)、实时流式输出 |+| **Telegram** | HTML 格式化、可编辑流式消息、文件上传、输入状态指示器、多用户访问与管理员/成员角色 |++### 工作区/编码快捷键(CLI)++- `Ctrl+P` → 切换到计划模式+- `Ctrl+X` → 切换到执行模式+- `Esc` 或 `Ctrl+Q` → 退出工作区回到常规聊天+- `Ctrl+V` → 切换进度视图(当终端拦截 Ctrl+V 时 `/view` 作为后备)-### Telegram 访问模型+### Spotify UI 注意事项(CLI)-Mercury 使用组织式访问模型,包含管理员和成员。+- Spotify 面板支持键盘快捷键:`N` 下一曲、`P` 上一曲、`+/-` 音量、`Z` 正在播放。+- 内联专辑封面是可选的且安全屏蔽:+ - 用 `MERCURY_SPOTIFY_ART=1` 启用+ - 目前仅在本地 iTerm 会话中渲染+ - 在 SSH/移动端/轻量终端中自动回退到纯文本 UI-- 首次设置:向你的 Bot 发送 `/start`,获取配对码,然后在 CLI 中执行 `mercury telegram approve <code>`。你会成为首位管理员。-- 新用户:发送 `/start` 请求访问,由管理员在 CLI 中批准或拒绝。-- 角色:管理员可以批准、拒绝、提升、降级和重置访问;成员可以与 Mercury 对话。-- 重置:管理员可在 Telegram 发送 `/unpair`,或在 CLI 中执行 `mercury telegram reset`。-- 仅支持私聊,群聊消息会被忽略。+### Telegram 访问++Mercury 使用**组织访问模型**,包含管理员和成员。++- **首次设置:** 向你的 Bot 发送 `/start`,收到配对码,然后在 CLI 中输入 `mercury telegram approve <code>`。你成为首位管理员。+- **其他用户:** 发送 `/start` 请求访问。管理员从 CLI 批准或拒绝。+- **角色:** 管理员可以批准/拒绝请求、晋升/降级用户和重置访问。成员可以与 Mercury 聊天。+- **重置:** 管理员可以在 Telegram 发送 `/unpair`,或在 CLI 中运行 `mercury telegram reset` 清除所有访问并重新开始。+- 仅限私聊 — 群组消息始终被忽略。++CLI 命令:`mercury telegram list|approve|reject|remove|promote|demote|reset`## 调度器-- **周期任务**:使用 cron 表达式,例如 `0 9 * * *` 表示每天 9 点。-- **一次性任务**:使用 `delay_seconds`,例如 15 秒后执行。-- 任务会持久化到 `~/.mercury/schedules.yaml`,重启后自动恢复。-- 执行结果会返回到创建任务时所在的渠道。+- **循环**:使用 cron 表达式的 `schedule_task`(`0 9 * * *` 每天 9 点)+- **一次性**:使用 `delay_seconds` 的 `schedule_task`(例如 15 秒)+- 任务持久化到 `~/.mercury/schedules.yaml`,重启后恢复+- 响应路由回创建任务的渠道-## Second Brain+## 第二大脑-Mercury 默认启用结构化持久记忆,并会在对话后自动提取、存储和召回与你有关的重要事实。+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`。+- **10 种记忆类型** — identity、preference、goal、project、habit、decision、constraint、relationship、episode、reflection+- **自动提取** — 每轮对话后,Mercury 提取 0–3 条带置信度、重要性和持久性分数的事实+- **相关召回** — 每次消息前,将最匹配的 5 条记忆(900 字符预算)注入上下文+- **自动整合** — 每 60 分钟,Mercury 构建个人资料摘要、活跃状态摘要,并从模式生成反思+- **冲突解决** — 对立记忆按置信度(更高者胜出)或新旧(更新者胜出)解决+- **自动修剪** — 活跃作用域记忆 21 天后过期;推断记忆会衰减;低置信度持久记忆 120 天后清除+- **用户控制** — `/memory` 用于概览、搜索、暂停、恢复和清除+- **禁用** — `SECOND_BRAIN_ENABLED=false` 环境变量或配置中的 `memory.secondBrain.enabled: false`-所有数据都保存在本机 `~/.mercury/memory/second-brain/second-brain.db`,不会上传到云端。+所有数据保留在你机器的 `~/.mercury/memory/second-brain/second-brain.db`(SQLite + FTS5)。不上云。-## 配置位置+## 配置-运行时数据保存在 `~/.mercury/`,不会写入你的项目目录。+所有运行时数据位于 `~/.mercury/` — 不在你的项目目录中。| 路径 | 用途 ||------|------|-| `~/.mercury/mercury.yaml` | 主配置,包括提供商、渠道和预算 |-| `~/.mercury/.env` | API Key 和 Token |-| `~/.mercury/soul/*.md` | Agent 人格文件 |+| `~/.mercury/mercury.yaml` | 主配置(Provider、渠道、预算) |+| `~/.mercury/.env` | API key 和 Token(与项目 .env 一起加载) |+| `~/.mercury/soul/*.md` | Agent 人格(soul、persona、taste、heartbeat) || `~/.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/skills/` | 已安装的 Skills |+| `~/.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/` | 结构化记忆数据库(SQLite + FTS5) || `~/.mercury/daemon.pid` | 后台进程 PID |-| `~/.mercury/daemon.log` | 守护进程日志 |+| `~/.mercury/daemon.log` | 守护进程模式日志 |++## Provider 兜底++配置多个 LLM Provider。Mercury 按顺序尝试并自动兜底:-## 模型提供商兜底+| Provider | 默认模型 | 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` | 通过 API 的远程 Ollama |+| **Ollama Local** | gpt-oss:20b | 无需 Key | 本地 Ollama 实例 |-Mercury 可以配置多个 LLM 提供商,并按顺序自动尝试。如果某个提供商失败,会切换到下一个。+当 Provider 失败时,Mercury 自动尝试下一个。它记住最后一个成功的 Provider,并在下次请求时从那里开始。-| 提供商 | 默认模型 | 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 实例 |+> **更多 Provider 即将到来** — Google Gemini、Mistral 等已在路线图上。Mercury 的 OpenAI 兼容架构也支持通过 base URL 配置自定义端点。## 架构-- TypeScript + Node.js 20+-- Vercel AI SDK v4,支持 `generateText`、`streamText` 和多步 Agent 循环-- grammY Telegram Bot-- SQLite + FTS5 Second Brain-- JSONL 短期、长期和情景记忆-- 后台守护进程、PID 文件和崩溃恢复-- macOS、Linux、Windows 系统服务+- **TypeScript + Node.js 18+** — ESM,tsup 构建+- **Vercel AI SDK v4** — `generateText` + `streamText`,10 步 Agent 循环,Provider 兜底+- **grammY** — Telegram Bot,带输入指示器、可编辑流式输出和文件上传+- **SQLite + FTS5** — 第二大脑,带全文搜索、冲突解决、自动整合+- **JSONL** — 短期、长期和情景对话记忆+- **守护进程管理器** — 后台生成 + PID 文件 + 看门狗崩溃恢复+- **系统服务** — macOS LaunchAgent、Linux systemd、Windows Task Scheduler-## 参与贡献+## 许可证-欢迎贡献修复、工具、记忆能力、渠道能力或文档改进。请保持 PR 聚焦,并在提交前运行:+MIT © [Cosmic Stack](https://github.com/cosmicstack-labs)-```bash-npm install-npm run build-```+----贡献 Mercury 时请特别注意:+## 免责声明-- 工具必须走权限系统,不能绕过审批。-- 面向 Agent 循环设计,尽量保持幂等。-- 避免冗长输出和过度日志,Token 预算是核心约束。-- CLI 和 Telegram 行为应尽量一致。-- 新增依赖、破坏性变更和 soul/persona 系统调整应先讨论。+**这是 AI 软件 — 有时可能会出问题,请自行评估风险后使用。**-## 许可证+----MIT © [Cosmic Stack](https://github.com/cosmicstack-labs)+## 参与贡献-## 社区+我们欢迎贡献!Mercury 是为演进而构建的,我们欢迎社区的帮助。无论是修复 bug、添加工具、改善记忆还是改进 soul — 所有高质量的贡献都受欢迎。-- Discord:[加入 Mercury Agent Discord](https://discord.gg/5emMpMJy5J)-- 邮箱:[[email protected]](mailto:[email protected])+### 🎯 Agent 专业知识 — 贡献者必读-## 免责声明+Mercury 不只是一个开源项目 — 它是一个**以灵魂驱动的 Agent**,全天候运行,管理权限,记住上下文,并在多个渠道间交互。如果你正在贡献,你必须像 Agent 构建者一样思考,而不只是库贡献者。这些是每个贡献者都应该内化的不可协商的原则:++| 原则 | 含义 |+|------|------|+| 🧠 **以循环思维** | Mercury 在 10 步 Agent 循环中运行。你的工具或功能每轮对话会被调用多次。尽可能保持幂等。 |+| 🔐 **权限优先** | 每个触碰外部世界的行为(文件、shell、网络、git)必须经过权限系统。永远不要假设批准。 |+| 💾 **记忆感知** | 如果你的功能生成关于用户的事实,考虑接入第二大脑。如果它读取用户数据,先检查记忆。 |+| 📏 **Token 意识** | Mercury 有每日 Token 预算。日志、冗长输出和大上下文转储会快速消耗 Token。保持精简。 |+| 🔌 **渠道无关** | 工具应该在 CLI 和 Telegram 上表现一致。不要假设终端、键盘,甚至另一端是人。 |+| 🔁 **优雅降级** | 如果 Provider 失败、工具出错或文件不存在 — Mercury 应该恢复,而不是崩溃。始终处理边缘情况。 |+| 📋 **自文档化** | 你的工具的名称和描述是 Mercury 决定何时使用它的依据。让它们清晰、具体和面向行动。 |+| 🧪 **测试循环,不只是函数** | 在隔离中工作的工具在 Agent 循环中可能失败(例如,返回太多数据,阻塞下一步)。端到端测试。 |++### 代码质量 — 做++| 做 | 为什么 |+|---|--------|+| ✅ 写干净的、可读的带显式类型的 TypeScript | Mercury's codebase 是类型安全的 — 保持这样 |+| ✅ 在公共函数和工具上添加 JSDoc 注释 | 帮助其他贡献者和 Agent 理解意图 |+| ✅ 保持函数小而单一职责 | 更易于测试、审查和推理 |+| ✅ 使用 async/await 而不是原始 Promise | 一致的错误处理和可读性 |+| ✅ 为新工具和记忆功能写测试 | 对 24/7 Agent 来说可靠性很重要 |+| ✅ 遵循现有项目结构(`src/tools/`、`src/memory/`、`src/channels/`) | 保持代码库可导航 |+| ✅ 使用 Agent Skills 规范用于新的基于 skill 的功能 | 确保与 skills 生态系统的兼容性 |+| ✅ 在 PR 描述中记录破坏性变更 | 帮助维护者正确版本管理 |++### 代码质量 — 不做++| 不做 | 为什么 |+|------|--------|+| ❌ 未经讨论不添加依赖 | Mercury 很精简 — 每个依赖增加表面积 |+| ❌ 不硬编码 API key、Token 或路径 | 像代码库其他部分一样使用 config/env 变量 |+| ❌ 不绕过权限系统 | 工具必须先请求再行动 — 这是 Mercury 的核心承诺 |+| ❌ 不在热路径中引入同步/阻塞 I/O | Mercury 是异步优先的,有原因 |+| ❌ 不提交大二进制文件或 secrets | 使用 `.gitignore` 和 env 文件 |+| ❌ 未经讨论不更改 soul/persona 系统 | 它是 Mercury 的核心 — 更改需要谨慎 |+| ❌ 不提交未测试的 Telegram 或守护进程更改 | 这些在合并后很难调试 |+| ❌ 不忽略 Token 预算系统 | 每个工具都应该注意 Token 消耗 |++### 开始++1. Fork 仓库+2. 运行 `npm install`+3. 进行更改+4. 运行 `npm run build` 验证编译+5. 本地使用 `mercury` 测试+6. 打开 PR,清晰描述你更改了什么和为什么++### PR 指南++- 保持 PR 聚焦 — 每个 PR 一个功能/修复+- 在描述中包含前/后行为+- 适当时标记相关 issues+- 对审查反馈响应迅速++### 需要帮助?++打开 issue 或联系 [[email protected]](mailto:[email protected])。我们很友好。++---++## 社区-这是 AI 软件,可能出现错误。请自行评估风险后使用。+1. **Discord** — [加入 Mercury Agent Discord](https://discord.gg/5emMpMJy5J) 获取实时聊天、支持和小社区讨论。\ No newline at end of file