@qxbyte/muse 0.1.1 → 0.1.2

package/README.md

@@ -65,30 +65,32 @@ muse --version
 | OpenAI | https://platform.openai.com | `OPENAI_API_KEY` |
 | Ollama (本地) | https://ollama.com | 不需要 |
 
-### 2. 建模型仓库 `~/.muse/models.json`
+### 2. 建模型仓库 `~/.muse/models.local.json`
 
 ```bash
 mkdir -p ~/.muse
-cat > ~/.muse/models.json <<'EOF'
+cat > ~/.muse/models.local.json <<'EOF'
 {
   "models": [
     {
       "id": "deepseek-chat",
       "vendor": "DeepSeek",
       "baseUrl": "https://api.deepseek.com/v1",
-      "apiKey": "${DEEPSEEK_API_KEY}",
+      "apiKey": "sk-...",
       "supportsToolCall": true
     }
   ],
   "availableModels": ["deepseek-chat"]
 }
 EOF
+chmod 600 ~/.muse/models.local.json
 ```
 
-### 3. 设环境变量并启动
+> 文件名后缀 `.local.json` 是 muse 的视觉提示——本机本地、从不入 git；明文写 apiKey 是 OK 的。
+
+### 3. 启动
 
 ```bash
-export DEEPSEEK_API_KEY=sk-...     # 写入 ~/.zshrc 或 ~/.bashrc 持久化
 muse                                # 进交互模式
 ```
 
@@ -98,19 +100,18 @@ muse                                # 进交互模式
 
 ## 配置详解
 
-muse 用**两个文件**分工：
+muse 用三个文件：
 
 ```
 ~/.muse/
-├── models.json           # 模型仓库：你能调用的所有模型 + 凭证
-├── models.local.json     # 同名兜底，放明文 apiKey（自动 gitignore，优先级更高）
+├── models.local.json     # 模型仓库：你能调用的所有模型 + 凭证（本机本地，从不入 git）
 ├── settings.json         # 运行偏好：当前激活的 model / UI / 权限
-├── settings.local.json   # 同名兜底，仅你本机生效
+├── settings.local.json   # settings 的本机兜底覆盖
 ├── sessions/             # 会话 JSONL 历史
 └── logs/                 # 日志（运行报错排查用）
 ```
 
-### 模型仓库：`~/.muse/models.json`
+### 模型仓库：`~/.muse/models.local.json`
 
 完整字段说明：
 
@@ -120,7 +121,7 @@ muse 用**两个文件**分工：
 | `name` | string | | 显示名，缺省 = id |
 | `vendor` | string | | 厂商名，只在 `/models` selector 里分组显示 |
 | `baseUrl` | string | ✅ | OpenAI 兼容协议**基址**（如 `https://api.deepseek.com/v1`）；填全 endpoint `.../v1/chat/completions` 也行，会自动剥后缀；别名字段 `url` 等价 |
-| `apiKey` | string | | 凭证；支持 `${ENV_VAR}` 占位符（推荐）；本地 Ollama 等可不填 |
+| `apiKey` | string | | 凭证；可直接写明文（推荐，文件本就只在本机），也支持 `${ENV_VAR}` 占位符；本地 Ollama 等可不填 |
 | `supportsToolCall` | bool | | 是否支持 function calling，默认 `true` |
 | `supportsImages` | bool | | 是否支持视觉，默认 `false` |
 | `contextWindow` | number | | 上下文窗口（tokens），用于 `/cost` 估算 |
@@ -225,7 +226,7 @@ muse 用**两个文件**分工：
 
 | 字段 | 说明 |
 |---|---|
-| `llm.model` | 当前激活的 model id，必须在 models.json 的 models 数组里能找到 |
+| `llm.model` | 当前激活的 model id，必须在 models.local.json 的 models 数组里能找到 |
 | `ui.lang` | UI 文案语言，`zh-CN` / `en` |
 | `ui.showBanner` | 启动是否显示彩虹 banner |
 | `permissions.allow` | 直接放行的工具名列表（如 `Read`、`Bash(npm:*)`） |
@@ -237,24 +238,25 @@ muse 用**两个文件**分工：
 
 ### 凭证安全
 
-按推荐顺序：
+`~/.muse/models.local.json` 是凭证唯一落脚点。两种写法：
 
-1. **环境变量 + `${VAR}` 占位符**（最安全）
+1. **直接写明文**（推荐——文件本就只存在于本机）
+   ```json
+   { "apiKey": "sk-..." }
+   ```
+   - 文件名带 `.local.json`，约定**绝不入 git**
+   - 建议 `chmod 600 ~/.muse/models.local.json`
+   - 警惕同步盘（iCloud / Dropbox）：如果 `~/.muse/` 被同步盘覆盖，凭证会扩散
+
+2. **`${VAR}` 占位符 + shell env**（怕同步盘扩散时用）
    ```bash
    # ~/.zshrc 或 ~/.bashrc
    export DEEPSEEK_API_KEY=sk-...
-   export MOONSHOT_API_KEY=sk-...
    ```
-   models.json 里 `"apiKey": "${DEEPSEEK_API_KEY}"`，启动时 muse 展开。
-
-2. **`~/.muse/models.local.json`**（明文 key）
-   - 文件名带 `.local.json`，**所有 `*.local.json` 项目级已 gitignore**
-   - 推荐 `chmod 600 ~/.muse/models.local.json`
-   - 同 id 时 `models.local.json` 覆盖 `models.json`，可以只在 local 里放凭证
-
-3. **`~/.muse/models.json` 直接写明文**（不推荐）
-   - 仅当你 100% 确定该机器 + 账号是私有
-   - 任何同步盘（iCloud、Dropbox）都会让它扩散
+   ```json
+   { "apiKey": "${DEEPSEEK_API_KEY}" }
+   ```
+   muse 启动时自动展开。如果 env 没设，会给出指明缺哪个变量的友好报错。
 
 muse 自身的安全保证：
 - 日志里 apiKey **自动脱敏**（前 4 + 后 4，中间打码）
@@ -272,7 +274,7 @@ muse 自身的安全保证：
 5. 环境变量 `MUSE_PROVIDER` / `MUSE_MODEL`
 6. CLI flags `-p` / `-m`
 
-`models.json` 同理（仅 `~/.muse/` 层，无项目级）。
+`models.local.json` 只有 `~/.muse/` 层，无项目级（模型仓库本质是 user-level）。
 
 ---
 
@@ -367,22 +369,17 @@ assistant 回复里的 markdown（标题、列表、代码块、表格、链接
 
 ### `/models` 显示 "No models registry found"
 
-`~/.muse/models.json` 不存在或解析失败。
+`~/.muse/models.local.json` 不存在或解析失败。
 
-- 路径是否正确？`ls ~/.muse/models.json`
-- JSON 格式是否合法？`jq . ~/.muse/models.json`
+- 路径是否正确？`ls ~/.muse/models.local.json`
+- JSON 格式是否合法？`jq . ~/.muse/models.local.json`
 - 字段错位？看 `~/.muse/logs/<today>.jsonl` 里的 warn
 
-### `Model "..." has no apiKey in env MUSE_ACTIVE_API_KEY`
+### `Model "..." needs an API key but none was found`
 
-启动时 apiKey 没注入到 env。检查：
+启动时 apiKey 没注入到 env。muse 会直接告诉你根因 + 修复方式（缺哪个 env var、改哪个文件）。看报错头几行即可。
 
-1. models.json 里 `apiKey` 字段是否填了
-2. 用了 `${ENV_VAR}` 占位符？对应 env 是否在 shell 里 export 过？  
-   ```bash
-   echo $DEEPSEEK_API_KEY    # 应有值
-   ```
-3. 改完 `~/.zshrc` 后是否 `source ~/.zshrc`？
+如果用了 `${ENV_VAR}` 占位符且 env 没 export，最快修复是直接把明文 key 填进 `~/.muse/models.local.json`（文件就在本机，明文 OK）。
 
 ### 启动时一段 zod warn JSON