Skip to content

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.md
new file mode 100644
index 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 file
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
new file mode 100644
index 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 file
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 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>
-直接运行:
+---
+
+## 快速开始
```bash
npx @cosmicstack/mercury-agent
@@ -21,223 +45,324 @@ npm i -g @cosmicstack/mercury-agent
mercury
```
-首次运行会启动配置向导(姓名、模型、可选 Telegram)。完成后会进入 Ink TUI 启动画面,并在进入聊天前让你选择权限模式(`Ask Me` / `Allow All`)。之后如需重新配置:
+首次运行会触发设置向导(姓名、Provider、可选 Telegram)。设置完成后,Mercury 打开 Ink TUI 启动画面,并在聊天开始前请求权限模式(`Ask Me` 或 `Allow All`)。
+
+之后重新配置(更改 key、名称、设置):
```bash
mercury 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 持久化:**
```bash
mercury up
```
-该命令会安装系统服务、启动后台守护进程,并确保 Mercury 正在运行。如果 Mercury 已经运行,它只会确认状态并显示 PID。
+这会安装系统服务(如果未安装)、启动后台守护进程,并确保 Mercury 正在运行。将此作为你的常用命令。
-常用命令:
+如果 Mercury 已在运行,`mercury up` 仅确认状态并显示 PID。
+
+### 其他守护进程命令
```bash
mercury 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)
+### 🎯 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