@qxbyte/muse 0.1.3 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # Muse
 
-> A TypeScript agent CLI built around OpenAI-compatible APIs. First-class support for self-hostable and Chinese LLMs (DeepSeek, Qwen, Kimi, GLM, Ollama, MiMo).
+> 围绕 OpenAI 兼容协议构建的 TypeScript Agent CLI,内建权限管控 + 长期记忆 + 向量召回。一线支持国内 LLM(DeepSeek / Qwen / Kimi / GLM / Ollama / MiMo)。
 
-**状态：v0.1 MVP**。API 可能调整，请关注 release notes。
+**v0.2.0 新增**:跨项目 + 项目级双层长期记忆(`/memory` + `/remember`)· `MUSE.md` / `AGENTS.md` 多层 hierarchy · 向量召回(6 个 OpenAI 兼容 preset + 4 个本地 transformers preset,默认关闭) · trust 分级(trusted/verified/auto)· 9 节 compaction schema · 上下文管理升级(用户消息保护 / tool result 自动折叠 / facts 自动 promote 等)。完整配置见 [`docs/操作手册.md`](./docs/操作手册.md)。
 
 ---
 
@@ -12,6 +12,7 @@
 - [快速开始](#快速开始)
 - [配置详解](#配置详解)
 - [使用](#使用)
+- [长期记忆与向量召回](#长期记忆与向量召回)
 - [常见问题](#常见问题)
 - [License](#license)
 
@@ -65,11 +66,11 @@ muse --version
 | OpenAI | https://platform.openai.com | `OPENAI_API_KEY` |
 | Ollama (本地) | https://ollama.com | 不需要 |
 
-### 2. 建模型仓库 `~/.muse/models.local.json`
+### 2. 建模型仓库 `~/.muse/model.local.json`
 
 ```bash
 mkdir -p ~/.muse
-cat > ~/.muse/models.local.json <<'EOF'
+cat > ~/.muse/model.local.json <<'EOF'
 {
   "models": [
     {
@@ -83,7 +84,7 @@ cat > ~/.muse/models.local.json <<'EOF'
   "availableModels": ["deepseek-chat"]
 }
 EOF
-chmod 600 ~/.muse/models.local.json
+chmod 600 ~/.muse/model.local.json
 ```
 
 > 文件名后缀 `.local.json` 是 muse 的视觉提示——本机本地、从不入 git；明文写 apiKey 是 OK 的。
@@ -94,7 +95,7 @@ chmod 600 ~/.muse/models.local.json
 muse                                # 进交互模式
 ```
 
-第一次启动会自动写 `~/.muse/settings.json` 记录默认模型；在 TUI 里输入 `/models` 可以切换。
+第一次启动会自动写 `~/.muse/settings.json` 记录默认模型；在 TUI 里输入 `/model` 可以切换。
 
 ---
 
@@ -111,7 +112,7 @@ muse 用三个文件：
 └── logs/                 # 日志（运行报错排查用）
 ```
 
-### 模型仓库：`~/.muse/models.local.json`
+### 模型仓库：`~/.muse/model.local.json`
 
 完整字段说明：
 
@@ -119,13 +120,13 @@ muse 用三个文件：
 |---|---|---|---|
 | `id` | string | ✅ | 模型唯一标识，**你自己起的名字**；slash 命令和 settings.json 用它引用 |
 | `name` | string | | 显示名，缺省 = id |
-| `vendor` | string | | 厂商名，只在 `/models` selector 里分组显示 |
+| `vendor` | string | | 厂商名，只在 `/model` selector 里分组显示 |
 | `baseUrl` | string | ✅ | OpenAI 兼容协议**基址**（如 `https://api.deepseek.com/v1`）；填全 endpoint `.../v1/chat/completions` 也行，会自动剥后缀；别名字段 `url` 等价 |
 | `apiKey` | string | | 凭证；可直接写明文（推荐，文件本就只在本机），也支持 `${ENV_VAR}` 占位符；本地 Ollama 等可不填 |
 | `supportsToolCall` | bool | | 是否支持 function calling，默认 `true` |
 | `supportsImages` | bool | | 是否支持视觉，默认 `false` |
 | `contextWindow` | number | | 上下文窗口（tokens），用于 `/cost` 估算 |
-| `availableModels` | string[] | | 顶层数组；决定 `/models` selector 里显示哪些 id（不填 = 全部 models） |
+| `availableModels` | string[] | | 顶层数组；决定 `/model` selector 里显示哪些 id（不填 = 全部 models） |
 
 ### 多 Provider 配置示例
 
@@ -234,18 +235,18 @@ muse 用三个文件：
 | `permissions.deny` | 永远拒绝的工具 |
 | `permissions.defaultMode` | `strict`（未匹配 → ask）、`relaxed`（未匹配 → allow）、`ask`（默认） |
 
-> 用 `/models` 切换模型时，muse 会自动写回 `llm.model`，**不需要手动改**。
+> 用 `/model` 切换模型时，muse 会自动写回 `llm.model`，**不需要手动改**。
 
 ### 凭证安全
 
-`~/.muse/models.local.json` 是凭证唯一落脚点。两种写法：
+`~/.muse/model.local.json` 是凭证唯一落脚点。两种写法：
 
 1. **直接写明文**（推荐——文件本就只存在于本机）
    ```json
    { "apiKey": "sk-..." }
    ```
    - 文件名带 `.local.json`，约定**绝不入 git**
-   - 建议 `chmod 600 ~/.muse/models.local.json`
+   - 建议 `chmod 600 ~/.muse/model.local.json`
    - 警惕同步盘（iCloud / Dropbox）：如果 `~/.muse/` 被同步盘覆盖，凭证会扩散
 
 2. **`${VAR}` 占位符 + shell env**（怕同步盘扩散时用）
@@ -306,37 +307,43 @@ muse --help
 
 ### Slash 命令
 
-启动后在 TUI 输入 `/` 会弹出补全列表，↑↓ 导航，Tab/Enter 接受。
+启动后在 TUI 输入 `/` 会弹出补全列表,↑↓ 导航,Tab/Enter 接受。`/help` 输出按分类分组 + 按键提示。
 
 | 命令 | 作用 |
 |---|---|
-| `/help` | 列出所有命令 |
+| `/help` | 列所有命令(按分类分组)+ 按键速查表 |
 | `/clear` | 清空当前会话 |
 | `/cost` | 当前会话 token 用量 + 费用估算 |
-| `/status` | 模型 / cwd / 历史 / token 综合状态 |
-| `/models` | 弹出 selector，↑↓ + Enter 切换模型（自动写回 settings.json + 注入 env） |
-| `/config` | 显示 effective 配置（apiKey 脱敏） |
-| `/config reload` | 不重启 muse 热加载所有配置 |
-| `/config path` | 列出配置文件路径 |
-| `/compact` | 摘要老消息释放上下文（`--keep N` 保留最近 N 条） |
-| `/resume` | ↑↓ 选历史会话加载；带参 `/resume <id-prefix>` 直接加载 |
-| `/mcp` | MCP server 状态 |
-| `/quit` / `/exit` | 退出 |
+| `/model` | 弹出 selector,↑↓ 选模型(自动写回 settings.json) |
+| `/config [reload\|path]` | 显示 effective 配置 / 热加载 / 列配置文件路径 |
+| `/compact [--keep N]` | 摘要老消息释放上下文(9 节结构化 schema + facts 自动 promote 到 memory) |
+| `/memory [子命令]` | 长期记忆管理(详见 [`docs/操作手册.md`](./docs/操作手册.md) §4.3)<br>`list` / `view <name>` / `edit <name>` / `delete <name>` / `promote <name>` / `promote-scope <name>` / `trust <name> <level>` / `search <query>` / `diff` / `diagnose` |
+| `/remember [--user\|--project] <text>` | 用户显式存记忆 — LLM 把口语化文本抽取成结构化 memory(默认 user 跨项目) |
+| `/btw <question>` | 旁白问答:浮层显示,**不**进历史 |
+| `/resume` | ↑↓ 选历史会话加载;带参 `/resume <id-prefix>` 直接加载 |
+| `/mcp` | MCP server 状态(预留,v0.3 落地) |
+| `/mode [<mode>]` | 切权限模式(default / acceptEdits / plan / bypassPermissions) |
+| `/exit` | 退出 |
 
 ### 内置工具
 
-LLM 在执行任务时可调用：
+LLM 在执行任务时可调用:
 
 | 工具 | 作用 |
 |---|---|
-| `Read` | 读文件，支持 offset / limit 分页 |
-| `Write` | 写文件（必须先 Read 过才能 Write，防误覆盖） |
-| `Edit` | 精确字符串替换（比全文重写省 token） |
+| `Read` | 读文件,支持 offset / limit 分页 |
+| `Write` | 写文件(必须先 Read 过才能 Write,防误覆盖) |
+| `Edit` | 精确字符串替换(比全文重写省 token) |
 | `Grep` | ripgrep 包装 |
 | `Glob` | 文件匹配 |
-| `Bash` | 执行 shell 命令；危险命令（rm -rf / sudo / curl…|sh）硬拒绝 |
+| `Bash` | 执行 shell 命令;危险命令(rm -rf / sudo / curl…\|sh)硬拒绝 |
+| `WebFetch` | 抓取 URL → markdown(SSRF 防护 + http→https + 30s + 1MB) |
+| `TodoWrite` | 任务清单(session 内),固定显示在输入框上方 |
+| `MemoryRead` | 读单条长期 memory(`MEMORY.md` 索引行自动注入 system prompt) |
+| `MemoryWrite` | 写长期 memory(支持 `scope: "project" \| "user"` 双层) |
+| `AskUserQuestion` | 弹结构化 picker 同步问用户(单 / 多选 + Notes) |
 
-所有写操作 / Bash 默认走权限弹窗（y/n 确认），权限模式可调（见下）。
+所有写操作 / Bash 默认走权限弹窗(y/n 确认),权限模式可调(见下)。
 
 ### 权限模式（Shift+Tab 循环）
 
@@ -355,31 +362,71 @@ LLM 在执行任务时可调用：
 
 两种方式：
 
-1. **TUI 内**：输入 `/models` → ↑↓ 选 → Enter，自动写回 settings.json + 注入 env
+1. **TUI 内**：输入 `/model` → ↑↓ 选 → Enter，自动写回 settings.json + 注入 env
 2. **命令行临时**：`muse -m kimi-k2 "..."`（不持久化）
 3. **手动编辑**：改 `~/.muse/settings.json` 里的 `llm.model`，TUI 里 `/config reload` 热加载
 
 ### Markdown 渲染
 
-assistant 回复里的 markdown（标题、列表、代码块、表格、链接）会被渲染成富文本。流式输出过程中是纯文本，本轮结束后自动替换成格式化版本。
+assistant 回复里的 markdown(标题、列表、代码块、表格、链接)会被渲染成富文本。流式输出过程中是纯文本,本轮结束后自动替换成格式化版本。
+
+---
+
+## 长期记忆与向量召回
+
+v0.2.0 新增。`/memory` 命令族管理跨 session 持久化记忆;`/remember` 是用户显式入口。
+
+**两层独立存储 + 合并召回**:
+
+| scope | 路径 | 用途 |
+|---|---|---|
+| `project` | `~/.muse/projects/<hash>/memory/` | 项目专属(团队约定 / 项目 bug 修复 / 架构决策) |
+| `user` | `~/.muse/memory/` | 跨项目用户级(编辑器偏好 / 工作语言 / 工具偏好) |
+
+召回时两层合并,**项目优先**(同分时 project 排前)。trust 分级:`trusted`(`MUSE.md`/`AGENTS.md`,硬约束)/ `verified`(用户编辑过)/ `auto`(LLM 自动写,可被新证据覆盖)。
+
+**`MUSE.md` / `AGENTS.md` hierarchy**:5 层 — `~/.muse/MUSE.md`(全局)→ `<project>/MUSE.md`(团队)→ `<project>/.muse/MUSE.local.md`(个人本地)→ 子目录惰性加载。`AGENTS.md` 兼容读取(跨工具事实标准)。
+
+**向量召回**(默认关闭,启用一行配置):
+
+```jsonc
+// ~/.muse/settings.local.json
+{
+  "memory": {
+    "embedding": {
+      "enabled": true,
+      "preset": "dashscope-v3",          // 阿里 DashScope(国内直连,推荐中文场景)
+      "apiKey": "${DASHSCOPE_API_KEY}"
+    }
+  }
+}
+```
+
+支持的 preset:
+- **云端 OpenAI 协议**:`dashscope-v3`(阿里 1024-dim)/ `zhipu-3`(智谱 2048-dim)/ `openai-3-small`(1536-dim) / `openai-3-large`(3072-dim)/ `ollama-nomic` / `ollama-bge-m3`(本地零成本)
+- **本地 transformers**(需先 `npm i -g @huggingface/transformers`):`local-bge-zh` / `local-bge-en` / `local-minilm` / `local-bge-m3`
+
+**配置失败永不阻塞** — 自动降级到 `hash-bag`(本地零依赖) → 全文模式(`MEMORY.md` 索引前 200 行注入)。`muse` 内跑 `/memory diagnose` 看状态 + 修复建议。
+
+完整章节见 [`docs/操作手册.md`](./docs/操作手册.md) §3.7 / §4.3 / §4.4 / §9.7。
 
 ---
 
 ## 常见问题
 
-### `/models` 显示 "No models registry found"
+### `/model` 显示 "No models registry found"
 
-`~/.muse/models.local.json` 不存在或解析失败。
+`~/.muse/model.local.json` 不存在或解析失败。
 
-- 路径是否正确？`ls ~/.muse/models.local.json`
-- JSON 格式是否合法？`jq . ~/.muse/models.local.json`
+- 路径是否正确？`ls ~/.muse/model.local.json`
+- JSON 格式是否合法？`jq . ~/.muse/model.local.json`
 - 字段错位？看 `~/.muse/logs/<today>.jsonl` 里的 warn
 
 ### `Model "..." needs an API key but none was found`
 
 启动时 apiKey 没注入到 env。muse 会直接告诉你根因 + 修复方式（缺哪个 env var、改哪个文件）。看报错头几行即可。
 
-如果用了 `${ENV_VAR}` 占位符且 env 没 export，最快修复是直接把明文 key 填进 `~/.muse/models.local.json`（文件就在本机，明文 OK）。
+如果用了 `${ENV_VAR}` 占位符且 env 没 export，最快修复是直接把明文 key 填进 `~/.muse/model.local.json`（文件就在本机，明文 OK）。
 
 ### 启动时一段 zod warn JSON
 
@@ -412,9 +459,26 @@ muse           # 进 TUI
 
 ```bash
 npm uninstall -g @qxbyte/muse
-rm -rf ~/.muse                            # 清配置 / 会话 / 日志（可选）
+rm -rf ~/.muse                            # 清配置 / 会话 / 日志(可选)
 ```
 
+### 启用 embedding 后召回不准 / 启动报错
+
+在 muse 里跑 `/memory diagnose`,会显示:
+- 当前 embedding 配置(preset / model / apiKey 是否设)
+- 索引文件状态(每 scope 的 `.index.json` 是否存在)
+- Live probe 结果(✓ / ✗ HTTP 错)
+- 按错误类型分类的修复建议
+
+任何失败都自动降级到 hash-bag / 全文模式,muse 永远可用。
+
+---
+
+## 更多文档
+
+- [`docs/操作手册.md`](./docs/操作手册.md) — 完整配置 / 命令参考 / 三套 embedding 启用清单(阿里 / OpenAI / Ollama)/ FAQ
+- [`CHANGELOG`](https://github.com/qxbyte/muse/releases) — 各版本变更
+
 ---
 
 ## License