@oldsuns/pi-switch 0.3.2 → 0.3.5

package/README.md

@@ -1,6 +1,6 @@
 # pi-switch
 
-维护本地 provider 库并按需同步 [Pi](https://github.com/earendil-works/pi) 配置的终端 TUI：管理 provider / 模型 / 默认模型，以及 Pi session 的列表、预览与删除。
+维护本地 provider 库并按需同步 [Pi](https://github.com/earendil-works/pi) 配置的终端 TUI 与本地 Web 界面：管理 provider / 模型 / 默认模型，以及 Pi session 的列表、预览与删除。
 
 CLI：`pi-switch` · npm 包：`@oldsuns/pi-switch` · Node 薄壳 + Rust/napi 原生核心
 
@@ -35,6 +35,8 @@ CLI：
 ```bash
 pi-switch                 # 打开 TUI（等同 tui）
 pi-switch tui
+pi-switch --web           # 启动本地 Web 界面并打开浏览器
+pi-switch --web --port 5210 --no-open  # 指定端口，只打印访问地址
 pi-switch doctor         # 校验配置与默认模型
 pi-switch --version      # / -v
 pi-switch --help         # / -h / help
@@ -42,6 +44,19 @@ pi-switch --help         # / -h / help
 
 Windows 上无需 Rust：预构建原生模块随 npm 包分发，`pi-switch` 开箱即用。本地开发见下文「开发者」。
 
+## Web 界面
+
+`pi-switch --web` 启动仅监听 `127.0.0.1` 的本地服务，自动选择空闲端口并打开浏览器；终端会打印访问地址，按 `Ctrl+C` 停止服务。可使用 `--port` 指定端口、`--no-open` 禁用自动打开。
+
+- **主页**：本地 provider / 模型计数、Pi 可用模型、直接切换默认模型、最近会话与常用操作。
+- **配置**：provider / 模型主从分栏、搜索、创建、编辑、复制、删除、同步与默认模型；在线多选导入、元数据来源选择。
+- **会话**：按工作目录浏览，支持命名筛选、用户消息筛选、分支折叠、树状与 Markdown 阅读、复制和删除。
+- **设置**：中英文、模型元数据与缺省参数、配置检查、备份恢复、OpenCode 导入、手动检查和安装更新。自动检查更新开关与 TUI 共享，控制 TUI 启动时的检查。
+
+Web 在「设置 → 外观」中提供 Catppuccin Mocha 暗色与 Latte 亮色主题，切换立即生效，并在浏览器中保存选择。沿用 TUI 的四页导航和状态语义，支持窄屏布局、键盘操作与减少动画偏好。按 `1`–`4` 切换页面，`/` 搜索，`?` 查看完整快捷键；文本输入期间不触发快捷键。
+
+Web 与 TUI 共用 Rust 文档层，使用相同的文件锁、备份、校验和未知字段保留规则。取消默认 provider 的同步、删除和恢复备份均会明确确认。浏览器不会将 API key 保存到 localStorage；会话 Markdown 中的原始 HTML 以文本展示，图片以替代文字展示，不自动加载远程图片。
+
 ## 开发者
 
 从源码构建：
@@ -50,10 +65,14 @@ Windows 上无需 Rust：预构建原生模块随 npm 包分发，`pi-switch`
 npm install
 npm run build:native:debug
 node ./bin/pi-switch.js
+# 启动本地 Web 界面
+npm run dev:web
 ```
 
 贡献流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
+Web 实现与使用说明见 [web/README.md](./web/README.md)。
+
 ## 界面与快捷键
 
 全局导航：`j/k` 或方向键移动；菜单中 `Enter` / `l` 进入内容，各内容页按自己的方向键切换焦点；`?` 帮助；`q` 退出（多数界面 `Ctrl+C` 也退出，会话预览除外）。
@@ -128,7 +147,8 @@ Session 根目录优先级：非空 `PI_CODING_AGENT_SESSION_DIR` → `<Pi agent
 - 已同步 provider 的编辑与 model 变更会同步两份文件；不同步项只更新本地库。
 - 在线导入 model **不会**隐式同步到 Pi。
 - 启动或手动重载时，以 `models.json` 中同 ID provider 为准回灌本地库；外部从 Pi 删除的 provider 仍作为不同步项保留。
-- 从 Pi 移除当前默认 provider 会先确认并清除默认模型；`d` 永久删除本地副本，必要时同时从 Pi 删除。
+- 从 Pi 移除当前默认 provider 会先确认并清除默认模型；`d` 永久删除本地副本，必要时同时从 Pi 删除；若该 provider 在 `auth.json` 有 `api_key` 凭据，删除时会询问是否一并删除（OAuth 等凭据不会被删除）。
+- API 密钥保存位置可在 Settings 里切换：默认写入 Pi 的 `auth.json`（provider 的 ID 映射到 `{"type":"api_key","key":...}`，`models.json` 与 `providers.json` 不保存密钥）；可切换回旧的 `models.json` 行为。provider 重命名时凭据随之迁移（重命名并输入新密钥时源 OAuth 凭据保留原位），目标 ID 已有凭据时先询问。切到 `models.json` 后保存密钥会移除同名 ID 上的 auth.json 条目（否则它会继续优先于 models.json）；该条目含 `env` 等配置时先询问。回到 `auth.json` 后保存会清掉 provider 文档里遗留的同名明文密钥。
 
 ## 模型导入与价格
 
@@ -140,8 +160,8 @@ Session 根目录优先级：非空 `PI_CODING_AGENT_SESSION_DIR` → `<Pi agent
    - `GET /api/pricing`  
    成功则按 NewAPI 换算覆盖模型 `cost`（`1 USD = 500_000 quota`，每 1M tokens 成本 ≈ `ratio × 2` USD）；失败静默忽略。
 3. 若开启 models.dev 元数据：请求 `https://models.dev/api.json`，补全 `contextWindow`、`maxTokens`、`cost`、reasoning 等。  
-   - **在线导入**遇到同 model ID 多源歧义时：**自动取第一个候选**，不弹选择框；缺少可用元数据的模型跳过并提示计数。  
-   - 导入列表会标注价格来源：`ratio_config` 或 `models.dev`。  
+   - **在线导入**遇到同 model ID 多源歧义时：需要选择元数据来源；缺少匹配元数据或 models.dev 不可达时，选中的模型使用 Settings 中的默认参数导入，并明确提示。
+   - 先选择服务商返回的模型 ID，再为选中项获取元数据和价格；TUI 与 Web 使用相同流程。
    - 网关价格在 catalog 元数据之上叠加。
 4. 关闭实时元数据：使用 Settings 中的默认参数；空字段回落 Pi 官方默认（context window `128000`、max tokens `16384`、cost `0`）。
 
@@ -174,6 +194,7 @@ Pi `settings.json` 中由 pi-switch 管理的字段：
 |------|------|
 | `language` | `en` \| `zh-CN` |
 | `fetchModelMetadata` | 是否拉 models.dev（默认 `true`） |
+| `keyStorage` | API 密钥保存位置：`auth.json`（默认）或 `models.json` |
 | `checkForUpdates` | 是否启动时检查 npm 新版本（默认 `true`） |
 | `modelDefaults` | 关闭实时元数据时的导入缺省（context / maxTokens / cost） |
 
@@ -184,6 +205,7 @@ Pi `settings.json` 中由 pi-switch 管理的字段：
 - 写前备份 `providers.json`、Pi `models.json` / `settings.json` 和 pi-switch `settings.json` 到 `~/.pi-switch/backups/`（version 3）；最多保留最近 10 份。现有 version 2 备份仍可恢复并自动拆分设置，version 1 备份不支持恢复。
 - 写入使用 `write.lock` 互斥；异常残留锁时 `doctor` 会提示。
 - `providers.json` 损坏时归档为 `corrupt-providers-*.json`，再从当前 Pi 配置重建，启动时显示归档路径。
+- `auth.json` 不参与备份；写入前以 `<auth.json>.lock` 目录与 Pi 的 proper-lockfile 互斥，并额外持有 `<auth.json>.lock.guard` 这个 OS 级锁（进程退出时内核自动释放），因此崩溃遗留的锁目录会在 30 秒后被安全接管，不会永久阻塞写入。新文件权限 `0600`，只修改目标 provider 的条目（OAuth 等其他凭据原样保留）。要替换目标 ID 上不属于该 provider 的凭据（重命名落到已有凭据的 ID、或给已有 OAuth 登录的 ID 写 API 密钥）时会先询问，未确认不写入。
 - 原子写入，只 patch 目标字段，保留未知 JSON；格式错误时停止写入并显示错误。
 - 支持 Pi 的 `$ENV` / `${ENV}` 插值与 `$$` / `$!` 转义；`!command` 原样保存，在线拉取**不会**执行它。
 - Session 删除只作用于选中的 JSONL，并校验路径必须位于 session 根目录内；优先调用系统 `trash`，失败后再永久删除。

package/bin/pi-switch.js

@@ -8,6 +8,9 @@ if (command === "--help" || command === "-h" || command === "help") {
 
 Usage:
   pi-switch              open the terminal UI
+  pi-switch --web         open the local Web interface
+  pi-switch --web --port 5210 --no-open
+                         choose a port without opening a browser
   pi-switch doctor       validate Pi documents and defaults
   pi-switch --version    print the native module version
 `);
@@ -21,7 +24,15 @@ Usage:
   if (checks.some((check) => !check.ok)) process.exitCode = 1;
 } else if (!command || command === "tui") {
   runTui();
+} else if (command === "--web" || command === "web") {
+  try {
+    const { parseWebOptions, startWeb } = await import("../web/start.js");
+    await startWeb(parseWebOptions(process.argv.slice(3)));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
 } else {
-  console.error("Usage: pi-switch [tui|doctor|--version]");
+  console.error("Usage: pi-switch [tui|--web|doctor|--version|--help]");
   process.exitCode = 2;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oldsuns/pi-switch",
-  "version": "0.3.2",
-  "description": "A focused terminal UI for Pi provider and model configuration",
+  "version": "0.3.5",
+  "description": "A local terminal and Web UI for Pi provider and model configuration",
   "type": "module",
   "bin": {
     "pi-switch": "./bin/pi-switch.js"
@@ -10,6 +10,11 @@
   "types": "./index.d.ts",
   "files": [
     "bin",
+    "web/public",
+    "web/server.js",
+    "web/start.js",
+    "web/native-client.js",
+    "web/native-worker.js",
     "index.js",
     "index.d.ts",
     "pi-switch-native.cjs",
@@ -26,8 +31,9 @@
     ]
   },
   "scripts": {
-    "build:native": "napi build --platform --release --dts native.d.ts",
-    "build:native:debug": "napi build --platform --dts native.d.ts",
+    "dev:web": "node ./bin/pi-switch.js --web",
+    "build:native": "napi build --platform --no-js --release --dts native.d.ts",
+    "build:native:debug": "napi build --platform --no-js --dts native.d.ts",
     "test": "cargo test --locked --lib",
     "check": "cargo fmt --check && cargo clippy --locked --all-targets -- -D warnings",
     "pack:check": "npm pack --dry-run"

package/web/native-client.js

@@ -0,0 +1,51 @@
+import { Worker } from "node:worker_threads";
+
+export async function createNativeClient() {
+  const worker = new Worker(new URL("./native-worker.js", import.meta.url));
+  const pending = new Map();
+  let nextId = 0;
+  let failure;
+  let readyResolve;
+  let readyReject;
+  const ready = new Promise((resolve, reject) => {
+    readyResolve = resolve;
+    readyReject = reject;
+  });
+
+  function fail(error) {
+    failure = error;
+    readyReject(error);
+    for (const entry of pending.values()) entry.reject(error);
+    pending.clear();
+  }
+
+  worker.on("error", fail);
+  worker.on("exit", (code) => fail(new Error("The native Web worker stopped (exit " + code + ").")));
+  worker.on("message", (message) => {
+    if (message.ready) {
+      readyResolve();
+      return;
+    }
+    const entry = pending.get(message.id);
+    if (!entry) return;
+    pending.delete(message.id);
+    if (message.error) entry.reject(new Error(message.error));
+    else entry.resolve(message.result);
+  });
+  await ready;
+
+  return {
+    request(payload) {
+      if (failure) return Promise.reject(failure);
+      return new Promise((resolve, reject) => {
+        const id = ++nextId;
+        pending.set(id, { resolve, reject });
+        worker.postMessage({ id, payload });
+      });
+    },
+    async close() {
+      fail(new Error("The Web server is shutting down."));
+      await worker.terminate();
+    },
+  };
+}

package/web/native-worker.js

@@ -0,0 +1,17 @@
+import { parentPort } from "node:worker_threads";
+import binding from "../pi-switch-native.cjs";
+
+if (typeof binding.WebSession !== "function") {
+  throw new Error("The native module has no Web interface. Run npm run build:native:debug first.");
+}
+const session = new binding.WebSession();
+
+parentPort.on("message", ({ id, payload }) => {
+  try {
+    const result = JSON.parse(session.request(JSON.stringify(payload)));
+    parentPort.postMessage({ id, result });
+  } catch (error) {
+    parentPort.postMessage({ id, error: error.message });
+  }
+});
+parentPort.postMessage({ ready: true });