@oldsuns/pi-switch 0.2.2 → 0.2.4

package/README.md

@@ -6,10 +6,10 @@ CLI：`pi-switch` · npm 包：`@oldsuns/pi-switch` · Node 薄壳 + Rust/napi
 
 ## 功能
 
-- **主页**：provider / model 计数、默认模型、关键路径
+- **主页**：provider / model 计数、默认模型、关键路径；启动后台静默检查 npm 新版本，有更新时弹出确认对话框可一键安装
 - **配置 (Profiles)**：本地 provider 库与 Pi 启用子集；新建 / 编辑 / 删除 / 复制；在线导入模型
 - **会话 (Sessions)**：浏览 JSONL session、筛选、预览、复制消息、删除
-- **设置 (Settings)**：语言、models.dev 元数据、默认参数、重载、校验、备份、OpenCode 导入
+- **设置 (Settings)**：语言、models.dev 元数据、默认参数、重载、校验、备份、OpenCode 导入、自动检查更新、手动检查更新
 - 完整库保存在 `~/.pi-switch/providers.json`，只有已启用项写入 Pi 的 `models.json`
 
 ## 要求
@@ -28,7 +28,7 @@ npm install -g @oldsuns/pi-switch
 pi-switch
 ```
 
-首次运行会自动把现有的 `~/.pi/agent/models.json` 全量导入本地库，**不修改** Pi 配置；随后即可在 Profiles 中勾选要加入 Pi 的 provider / model。
+首次运行会自动把现有的 `~/.pi/agent/models.json` 全量导入本地库，**不修改** Pi 配置；随后即可在 Profiles 中勾选要同步到 Pi 的 provider / model。
 
 CLI：
 
@@ -61,8 +61,8 @@ node ./bin/pi-switch.js
 | 键 | 作用 |
 |----|------|
 | `n` / `e` / `d` / `c` | 新建 / 编辑 / 删除 / 复制当前焦点（provider 或 model） |
-| `Space`（provider） | 加入 / 移出 Pi；`[x]` 已加入，`[ ]` 仅本地 |
-| `Space`（model） | 设为默认模型（仅已加入 Pi 的 provider） |
+| `Space`（provider） | 同步到 Pi / 取消同步；`[x]` 已同步，`[ ]` 不同步 |
+| `Space`（model） | 设为默认模型（仅已同步到 Pi 的 provider） |
 | `i` | 从当前 provider 在线导入模型 |
 | `/` | 筛选 provider |
 | `Enter` / `l` | 进入模型列表 |
@@ -71,7 +71,7 @@ node ./bin/pi-switch.js
 | `b` | 浏览备份 |
 | `v` | 校验配置（doctor） |
 
-新建 provider 默认加入 Pi，表单可关闭；复制继承源的加入状态。
+新建 provider 默认同步到 Pi，表单可关闭；复制继承源的同步状态。
 
 Provider 表单：`baseUrl`、`api`（`openai-completions` / `openai-responses` / `anthropic-messages` / `google-generative-ai`）、`apiKey`、`authHeader`、Headers（独立 `User-Agent` + 其余 JSON）、`compat`（含一等开关 Session affinity = `sendSessionAffinityHeaders`）。
 
@@ -103,6 +103,8 @@ Session 根目录优先级：`PI_CODING_AGENT_SESSION_DIR` → `PI_CODING_AGENT_
 |----|------|
 | 语言 | English / 中文（`en` / `zh-CN`） |
 | 从 models.dev 获取模型信息 | 开关实时元数据（默认开） |
+| 自动检查更新 | 启动时后台自动检查 npm `@oldsuns/pi-switch` 新版本（开关，默认开） |
+| 检查更新（手动） | 立即检查新版本（绕过 24h 缓存） |
 | 默认模型参数 | 仅关闭实时元数据时显示，用于导入缺省 |
 | 重载配置 | 从磁盘重读 |
 | 验证配置 | doctor |
@@ -113,11 +115,11 @@ Session 根目录优先级：`PI_CODING_AGENT_SESSION_DIR` → `PI_CODING_AGENT_
 
 ## Provider 库与 Pi 同步
 
-- `~/.pi-switch/providers.json` 是完整本地库；`~/.pi/agent/models.json` 只含当前加入 Pi 的子集。
+- `~/.pi-switch/providers.json` 是完整本地库；`~/.pi/agent/models.json` 只含当前已同步到 Pi 的子集。
 - 首次运行把现有 `models.json` 全量导入本地库，不修改 Pi 配置。
-- 已加入 provider 的编辑与 model 变更会同步两份文件；仅本地项只更新本地库。
-- 在线导入 model **不会**隐式加入 Pi。
-- 启动或手动重载时，以 `models.json` 中同 ID provider 为准回灌本地库；外部从 Pi 删除的 provider 仍作为仅本地项保留。
+- 已同步 provider 的编辑与 model 变更会同步两份文件；不同步项只更新本地库。
+- 在线导入 model **不会**隐式同步到 Pi。
+- 启动或手动重载时，以 `models.json` 中同 ID provider 为准回灌本地库；外部从 Pi 删除的 provider 仍作为不同步项保留。
 - 从 Pi 移除当前默认 provider 会先确认并清除默认模型；`d` 永久删除本地副本，必要时同时从 Pi 删除。
 
 ## 模型导入与价格
@@ -135,18 +137,19 @@ Session 根目录优先级：`PI_CODING_AGENT_SESSION_DIR` → `PI_CODING_AGENT_
    - 网关价格在 catalog 元数据之上叠加。
 4. 关闭实时元数据：使用 Settings 中的默认参数；空字段回落 Pi 官方默认（context window `128000`、max tokens `16384`、cost `0`）。
 
-**OpenCode 导入**（Settings）：只读 `~/.config/opencode/opencode.json`，可全选或勾选 provider；导入项默认加入 Pi。若 models.dev 仍有歧义，**需要用户选择候选**。OpenCode 配置本身不会被修改。
+**OpenCode 导入**（Settings）：只读 `~/.config/opencode/opencode.json`，可全选或勾选 provider；导入项默认同步到 Pi。若 models.dev 仍有歧义，**需要用户选择候选**。OpenCode 配置本身不会被修改。
 
 ## 配置路径与 Settings 字段
 
 | 路径 | 角色 |
 |------|------|
 | `~/.pi-switch/providers.json` | 完整本地 provider 库（`version: 1`） |
-| `~/.pi/agent/models.json` | 已加入 Pi 的 provider 子集 |
+| `~/.pi/agent/models.json` | 已同步到 Pi 的 provider 子集 |
 | `~/.pi/agent/settings.json` | 默认模型 + pi-switch 设置 |
 | `~/.config/opencode/opencode.json` | OpenCode 只读导入源 |
 | `~/.pi-switch/backups/` | version 2 备份（providers + models + settings），最多 10 份 |
 | `~/.pi-switch/write.lock` | 写入互斥锁 |
+| `~/.pi-switch/update.json` | npm 新版本检查缓存（`lastCheck` + `latest` + `dismissed`，每 24h 最多联网一次） |
 
 `settings.json` 中与 pi-switch 相关的字段：
 
@@ -155,6 +158,7 @@ Session 根目录优先级：`PI_CODING_AGENT_SESSION_DIR` → `PI_CODING_AGENT_
 | `defaultProvider` + `defaultModel` | 默认模型（成对存在或同时缺省） |
 | `piSwitch.language` | `en` \| `zh-CN` |
 | `piSwitch.fetchModelMetadata` | 是否拉 models.dev（默认 `true`） |
+| `piSwitch.checkForUpdates` | 是否启动时检查 npm 新版本（默认 `true`） |
 | `piSwitch.modelDefaults` | 关闭实时元数据时的导入缺省（context / maxTokens / cost） |
 
 ## 数据安全
@@ -167,6 +171,22 @@ Session 根目录优先级：`PI_CODING_AGENT_SESSION_DIR` → `PI_CODING_AGENT_
 - Session 删除只作用于选中的 JSONL，并校验路径必须位于 session 根目录内；优先调用系统 `trash`，失败后再永久删除。
 - 正常退出、错误和 panic 都会恢复 raw mode、alternate screen 与光标。
 
+## 自动更新检查与安装
+
+启动时若 Settings 中「自动检查更新」开启（默认开），pi-switch 会在后台线程静默访问 npm registry 查询 `@oldsuns/pi-switch` 的 `latest` 版本，与当前版本对比：
+
+- 有新版本：弹出确认对话框（显示 `当前 → 最新`），用户可选择立即安装或跳过。跳过后同一版本不再弹窗，但主页仍显示横幅。手动检查（Settings 中「检查更新」）始终弹窗。
+- 无新版本、离线或请求失败：静默无提示，不打扰用户。
+
+安装流程：
+
+1. 用户在确认对话框按 `Enter/y` 确认 → 后台执行 `npm install -g @oldsuns/pi-switch`，显示加载动画。
+2. 安装成功 → 通知「更新已安装，请重启 pi-switch 生效」。
+3. 安装失败 → 弹出错误通知（如权限不足、网络问题）。
+4. 用户按 `Esc/n` 跳过 → 记录已跳过的版本到缓存，同一版本不再自动弹窗；主页横幅仍提示有新版本。
+
+检查结果缓存在 `~/.pi-switch/update.json`，自动检查每 24h 最多联网一次。后台线程独立于目录导入任务，不阻塞 UI。Settings 中可随时关闭「自动检查更新」。
+
 ## 验证
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oldsuns/pi-switch",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "A focused terminal UI for Pi provider and model configuration",
   "type": "module",
   "bin": {