@nvae/llmswitch 0.4.0 → 0.5.0

package/README.md

@@ -1,49 +1,16 @@
 <p align="center">
-  <img src="./assets/readme/hero.svg" width="100%" alt="llmswitch：为 Claude Code、Codex 和 OpenCode 切换供应商与模型，并按需转换 API 协议">
+  <img src="./assets/readme/hero.svg" width="100%" alt="llmswitch：为 Claude Code、Codex 和 OpenCode 切换供应商与模型工具">
 </p>
 
 <p align="center">
-  <strong>用一套 CLI 管理 Claude Code、Codex 与 OpenCode 的供应商、模型、代理和启动流程。</strong>
+  <strong>一个 CLI 工具管理 Claude Code、Codex 与 OpenCode 的模型切换。</strong>
 </p>
 
 <p align="center">
   <strong>简体中文</strong> · <a href="./README_EN.md">English</a>
 </p>
 
-<p align="center">
-  <a href="#快速开始">快速开始</a> ·
-  <a href="#兼容性">兼容性</a> ·
-  <a href="#命令参考">命令参考</a> ·
-  <a href="#配置与安全">配置与安全</a> ·
-  <a href="./LICENSE">MIT License</a>
-</p>
-
-## llmswitch 是什么？
-
-`llmswitch` 是一个面向 **Claude Code、Codex 和 OpenCode** 的本地命令行工具。它使用彼此独立的 profile 管理每种工具的 API 地址、密钥、模型和代理，并将选中的 profile 合并写入目标工具的原生配置。
-
-原生协议可以直接连接；当 Claude Code 或 Codex 需要访问仅兼容 OpenAI Chat Completions 的上游时，`llmswitch` 会自动启动一个仅监听本机的 bridge，完成常用请求、响应和 SSE 事件的协议转换。
-
-```text
-                            ┌─ Claude Code ── Anthropic Messages
-provider profiles ─ llms ──┼─ Codex ──────── OpenAI Responses
-                            └─ OpenCode ────── 原生 provider
-                                  │
-                     协议不兼容时启用 local bridge
-                                  │
-                            OpenAI Chat API
-```
-
-## 核心能力
-
-- **统一操作三种工具**：使用一致的命令管理 Claude Code、Codex 和 OpenCode。
-- **配置相互隔离**：每种工具独立保存 profile、默认项和当前启用项，不会混用供应商配置。
-- **一条命令切换并启动**：选择 profile 和模型、更新配置，然后启动目标 CLI。
-- **按需转换协议**：在 Messages / Responses 与 Chat Completions 之间转换常用文本、工具调用、工具结果及流式事件。
-- **保留现有配置**：只合并受管理字段，并在修改已有目标文件前创建时间戳备份。
-- **支持模型发现**：尝试从上游 `/models` 获取模型；失败时可手动输入模型 ID。
-- **支持上游代理**：每个 profile 可独立配置 HTTP、HTTPS 或 ALL proxy。
-- **便于脚本集成**：查询、切换、启动计划和 bridge 状态等命令支持 JSON 输出。
+---
 
 ## 快速开始
 
@@ -57,247 +24,194 @@ npm install -g @nvae/llmswitch
 bun add -g @nvae/llmswitch
 ```
 
-安装后可直接使用 `llms`（或 `llm-switch`）命令。本地开发可用：
+安装后使用 `llms`（或 `llm-switch`、`llmswitch`）命令。直接输入 `llms` 会自动选择工具并启动；`llms <tool>` 同理。
+
+### 0. 一键启动（连贯流程）
+
+```bash
+# 选择工具并启动；未配置供应商时会自动引导：添加供应商 → 选模型 → 启用 → 启动
+llms
+
+# 直接启动 Codex（等价于 llms launch codex）
+llms codex
+```
+
+`llms <tool>` 会根据状态自动衔接：
+
+- 已配置供应商 → 直接启动（使用当前启用 / 默认供应商及其默认模型）
+- 未配置 → 自动引导添加供应商、选择模型，静默启用后自动启动
+
+### 1. 显式引导配置
 
 ```bash
-bun run src/index.ts --help
+llms setup
 ```
 
-### 1. 添加供应商
+向导会依次引导：选择工具 → 添加供应商（API 地址、Key）→ 选择模型 → 启用 → 启动工具。已安装的工具会自动识别，只装一个时无需手动选择。
+
+```bash
+# 跳过工具选择，直接为 Codex 引导
+llms setup --tool codex
+```
 
-分别为需要使用的工具创建 profile：
+### 2. 添加供应商配置
 
 ```bash
+# 为 Claude Code 添加配置
 llms claude provider
+
+# 为 Codex 添加配置
 llms codex provider
+
+# 为 OpenCode 添加配置
 llms opencode provider
 ```
 
-交互界面支持添加、查看、编辑、删除、设为默认以及启用/禁用 profile。可从以下模板开始：
+按提示输入：API 地址、API Key、显示名称。
+
+自定义上游时，工具会自动探测接口类型（Anthropic / OpenAI Chat / OpenAI Responses），无需手动选择；仅当自动识别失败时才需要手动指定。支持本地 Ollama（`/v1` 兼容或原生 `/api/tags`，无需 API Key），预设中也有「Ollama（本地）」可选。
 
-| 模板 | 默认 API 格式 | 默认 Base URL |
-| --- | --- | --- |
-| 自定义（OpenAI 兼容） | Chat Completions | 手动填写 |
-| OpenAI | Responses | `https://api.openai.com/v1` |
-| Anthropic | Messages | `https://api.anthropic.com` |
+Profile 名称会自动生成（5 位随机小写字母数字，如 `69pjb`），所有命令都可通过名称或显示名称引用供应商：
 
-其他供应商可通过兼容的 OpenAI 或 Anthropic API 地址接入；这不代表所有厂商、字段或扩展协议都已完整适配。
+```bash
+# 名称与显示名称均可引用
+llms codex use 69pjb
+llms codex use DeepSeek
+llms launch codex --profile deepseek   # 归一化模糊匹配（忽略大小写/分隔符）
+```
 
-### 2. 选择模型
+### 3. 选择模型
 
 ```bash
+# 为当前工具选择模型
 llms codex model
-# 为指定 profile 选择模型
+
+# 为指定配置选择模型
 llms codex model --profile my-provider
 ```
 
-有 API Key 时，`llmswitch` 会尝试获取上游模型列表。使用空格多选、回车确认，然后指定默认模型；请求失败或上游没有兼容的模型端点时，可手动输入模型 ID。
+有 API Key 时会自动获取上游模型列表，也可手动输入模型 ID。
 
-### 3. 启用 profile
+### 4. 启用配置
 
 ```bash
 llms codex use my-provider
+
+# 查看当前配置状态
 llms codex current
 ```
 
-`use` 会备份现有目标配置、合并新的供应商设置，并将该 profile 记录为当前启用项。
-
-### 4. 切换模型并启动
+### 5. 启动工具
 
 ```bash
+# 启动 Codex 并使用指定模型
 llms launch codex gpt-4.1
 
-# 等价写法
-llms launch codex --model gpt-4.1
-
-# 显式指定 profile
-llms launch claude --profile my-provider --model claude-sonnet-4
+# 启动 Claude Code
+llms launch claude --model claude-sonnet-4-20250514
 
-# run 是 launch 的别名
+# 启动 OpenCode
 llms run opencode my-model
-```
-
-未指定 `--profile` 时，profile 的选择顺序为：
 
-1. 模型列表中包含目标模型的 profile；
-2. 当前启用的 profile；
-3. 默认 profile。
+# 指定配置启动
+llms launch claude --profile my-provider --model claude-sonnet-4
+```
 
-模型匹配会忽略大小写和常见分隔符。例如，`gpt4.1` 可匹配 `gpt-4.1`。如果输入的模型不在 profile 中，它会被加入模型列表并设为该 profile 的默认模型。
+未指定 `--profile` 时，会自动选择包含目标模型的配置。
 
-### 5. 预览或只写配置
+### 6. 预览执行计划
 
 ```bash
-# 只查看执行计划，不修改配置、不启动 CLI
+# 只查看计划，不实际启动
 llms launch codex gpt-4.1 --dry-run
 
-# 输出 JSON 计划
+# 输出 JSON 格式
 llms launch codex gpt-4.1 --dry-run --json
-
-# 写入配置，但不启动目标 CLI
-llms launch opencode my-model --print-only
-
-# 将额外参数透传给目标 CLI
-llms launch opencode my-model -- --resume
 ```
 
-如目标 CLI 不在 `PATH` 中，可指定可执行文件：
+### 7. 管理本地 Bridge
 
-```bash
-export CLAUDE_BIN=/path/to/claude
-export CODEX_BIN=/path/to/codex
-export OPENCODE_BIN=/path/to/opencode
-```
-
-## 兼容性
-
-| 目标工具 | Anthropic Messages | OpenAI Chat Completions | OpenAI Responses |
-| --- | :---: | :---: | :---: |
-| Claude Code | 直连 | 通过 bridge | 不支持 |
-| Codex | 不支持 | 通过 bridge | 直连 |
-| OpenCode | 直连 | 直连 | 直连 |
-
-OpenCode 会根据 API 格式写入对应的 AI SDK provider：
-
-- Anthropic：`@ai-sdk/anthropic`
-- OpenAI Responses：`@ai-sdk/openai`
-- OpenAI Chat：`@ai-sdk/openai-compatible`
-
-OpenAI 格式的 Base URL 会规范为末尾恰好一个 `/v1`；Anthropic 格式只移除末尾多余的 `/`。如果某个特殊网关不使用 `/v1` 路径，它可能无法直接使用当前的 OpenAI 格式 profile。
-
-## 本地 bridge
-
-Claude Code 和 Codex 共用一个 bridge 进程，但两侧上游配置相互隔离，可以同时连接不同供应商。默认监听 `127.0.0.1:17890`：
-
-```text
-Claude Code  POST /v1/messages  ─┐
-                                 ├─ local bridge ─→ POST /v1/chat/completions
-Codex        POST /v1/responses ─┘
-```
-
-当启用需要 bridge 的 profile 时，进程会自动启动；切回原生格式后会清理对应侧上游，两侧均不再使用 bridge 时会停止进程。
-
-常用管理命令：
+Claude Code 或 Codex 使用非原生协议时，会自动启动本地 Bridge。
 
 ```bash
+# 查看 Bridge 状态
 llms bridge status
-llms bridge status --json
+
+# 手动启动/停止
 llms bridge start
 llms bridge stop
+
+# 重载配置
 llms bridge reload claude
 llms bridge reload codex --profile my-provider
-
-# 前台运行，便于排查问题
-llms bridge serve
-```
-
-Bridge 提供以下本地端点：
-
-| 方法 | 路径 | 用途 |
-| --- | --- | --- |
-| `GET` | `/health`、`/v1/health` | 查看服务及两侧上游状态 |
-| `GET` | `/models`、`/v1/models` | 合并已配置上游的模型列表 |
-| `POST` | `/messages`、`/v1/messages` | Anthropic Messages → Chat |
-| `POST` | `/responses`、`/v1/responses` | OpenAI Responses → Chat/Completions |
-
-```bash
-curl http://127.0.0.1:17890/health
 ```
 
-> [!WARNING]
-> Bridge 本身没有身份认证、限流或请求体大小限制。请保持默认回环地址，不要将其作为公网或多租户生产网关使用。
+---
 
-## 上游代理
-
-添加或编辑 profile 时可以配置：
-
-- `HTTP_PROXY`
-- `HTTPS_PROXY`
-- `ALL_PROXY`，例如 `socks5h://127.0.0.1:1080`
-
-```bash
-llms claude provider
-# 选择“添加”或“编辑”，然后填写代理字段
-```
-
-原生直连 profile 会将适用的代理变量合并到目标工具配置；bridge profile 则由 bridge 使用对应上游的代理设置。实际代理行为仍取决于目标 CLI、Node.js 网络环境和代理协议，建议在真实环境中验证。
-
-## 命令参考
-
-统一形式为 `llms <tool> <action>`，其中 `<tool>` 为 `claude`、`codex` 或 `opencode`。
+## 常用命令
 
 | 命令 | 说明 |
 | --- | --- |
-| `llms <tool> provider` | 交互式管理 profile；`--json` 可查看列表 |
-| `llms <tool> use [name]` | 启用已有 profile；支持 `--json` |
-| `llms <tool> current` | 查看默认项和当前启用项；API Key 会脱敏 |
-| `llms <tool> model [--profile name]` | 获取、选择并保存模型；支持 `--json` |
-| `llms launch\|run <tool> [model]` | 切换 profile/模型并启动目标 CLI |
-| `llms bridge status` | 查看 bridge 进程和两侧上游状态 |
-| `llms bridge start\|stop` | 手动启动或停止 bridge |
-| `llms bridge reload [tool]` | 从当前或指定 profile 刷新 bridge 上游 |
-| `llms bridge serve` | 在前台运行 bridge |
-| `llms path` | 显示 llmswitch 本地数据目录 |
-
-查看完整参数：
+| `llms` | 选择工具并启动（未配置时自动引导） |
+| `llms <tool>` | 直接启动工具（未配置时自动引导完整链路） |
+| `llms setup [--tool <tool>]` | 显式引导配置（添加供应商 → 模型 → 启用 → 启动） |
+| `llms <tool> provider` | 管理供应商配置（添加、查看、编辑、删除） |
+| `llms <tool> use [name]` | 启用指定配置 |
+| `llms <tool> current` | 查看当前配置 |
+| `llms <tool> model` | 选择模型 |
+| `llms launch/run <tool> [model]` | 启动工具 |
+| `llms bridge status` | 查看 Bridge 状态 |
+| `llms path` | 查看数据目录 |
+
+`<tool>` 可选 `claude`、`codex`、`opencode`。
+
+查看完整帮助：
 
 ```bash
 llms --help
 llms launch --help
-llms bridge --help
-llms codex --help
 ```
 
-## 配置与安全
+---
 
-### 配置位置
+## 配置位置
 
-| 数据 | 默认位置 | 覆盖方式 |
-| --- | --- | --- |
-| llmswitch（macOS/Linux） | `~/.config/llm-switch/` | `LLM_SWITCH_HOME` 或 `XDG_CONFIG_HOME` |
-| llmswitch（Windows） | `%APPDATA%\llm-switch\` | `LLM_SWITCH_HOME` |
-| Claude Code | `~/.claude/settings.json` | `CLAUDE_CONFIG_DIR` |
-| Codex | `~/.codex/config.toml`、`~/.codex/.env` | `CODEX_HOME` |
-| OpenCode 配置 | `~/.config/opencode/opencode.json` | `OPENCODE_CONFIG_DIR` 或 `XDG_CONFIG_HOME` |
-| OpenCode认证 | `~/.local/share/opencode/auth.json` | `OPENCODE_DATA_DIR` 或 `XDG_DATA_HOME` |
+| 数据 | 位置 |
+| --- | --- |
+| llmswitch 配置 | `~/.config/llm-switch/` |
+| Claude Code | `~/.claude/settings.json` |
+| Codex | `~/.codex/config.toml` |
+| OpenCode | `~/.config/opencode/opencode.json` |
 
-为兼容当前程序和已有配置，llmswitch 的默认数据目录仍使用 `llm-switch` 目录名。Windows 下，OpenCode 认证默认位于 `%LOCALAPPDATA%\opencode\auth.json`。运行以下命令可查看当前环境中的实际数据目录：
+查看实际路径：
 
 ```bash
 llms path
 ```
 
-### 备份策略
-
-修改或禁用配置前，已存在的目标文件会备份到对应工具目录的 `backups/` 中，文件名包含时间戳。首次创建的文件没有可备份内容。写入过程使用同目录临时文件再重命名，降低配置只写入一部分的风险。
+---
 
-### API Key
+## 指定可执行文件路径
 
-API Key 会以**明文**保存在本机 profile、目标工具认证文件或 bridge 上游配置中。llmswitch 会尝试将新写文件权限设置为 `0600`，但不会使用系统钥匙串，也不会加密密钥。
+如果工具不在 `PATH` 中，可通过环境变量指定：
 
-请保护配置目录，不要将其中内容提交到版本控制，不要在不受信任的设备上保存长期密钥。JSON 查询结果会对 API Key 脱敏，但磁盘文件仍包含真实值。
-
-## 已知限制
+```bash
+export CLAUDE_BIN=/path/to/claude
+export CODEX_BIN=/path/to/codex
+export OPENCODE_BIN=/path/to/opencode
+```
 
-- Bridge 是面向本地使用的协议适配器，不保证 OpenAI 与 Anthropic 协议 100% 等价。
-- Responses 中的加密 reasoning 内容不会转发；未识别的工具类型可能被忽略。
-- Anthropic 转换主要覆盖文本、工具调用和工具结果，图片等非文本内容可能无法完整保留。
-- Codex 的 Completions 模式是降级路径：对话会被展平为 prompt，复杂工具调用或 agent 流程可能表现不佳。
-- Codex Chat 模式仅在上游返回 HTTP `404` 或 `405` 时回退到 Completions；认证、网络及其他错误不会触发回退。
-- 请求中的托管 `web_search` 会转换为普通 Chat function；若上游自行搜索并以完整 `<web_search>...</web_search>` 块返回结果，bridge 会将其恢复为 Responses `web_search_call`，并保留去标签后的结果正文。
-- 自动发现模型需要 API Key 和兼容的 `/models` 端点；失败时需手动输入模型。
+---
 
-## 参与贡献
+## 反馈与建议
 
-欢迎通过 Issue 报告兼容性问题，或提交 Pull Request 改进配置适配、协议转换、测试和文档。
+遇到问题或有改进想法，欢迎反馈：
 
-提交新供应商或协议适配时，建议同时提供：
+- 邮箱：rchdg50@gmail.com
+- GitHub Issues：https://github.com/rchdg/llmswitch/issues
 
-- 目标工具与 API 格式；
-- 可复现的请求和响应行为；
-- 普通响应与流式响应的测试；
-- 工具调用、工具结果和错误响应等边界场景。
+---
 
 ## License
 
-本项目基于 [MIT License](./LICENSE) 开源。
+MIT License - 查看 [LICENSE](./LICENSE)

package/dist/cli.js

@@ -3,13 +3,16 @@ import { TOOLS } from "./types.js";
 import { registerToolCommand } from "./commands/tool.js";
 import { registerLaunchCommand } from "./commands/launch-cmd.js";
 import { registerBridgeCommand } from "./commands/bridge-cmd.js";
+import { registerSetupCommand } from "./commands/setup-cmd.js";
+import { registerHomeCommand } from "./commands/home-cmd.js";
 import { getAppConfigRoot } from "./utils/paths.js";
+import { getVersion } from "./utils/version.js";
 export function createProgram() {
     const program = new Command();
     program
         .name("llms")
         .description("为 Claude Code / Codex / OpenCode 切换供应商、模型与上游代理")
-        .version("0.2.0")
+        .version(getVersion())
         .option("--json", "部分命令支持 JSON 输出（见子命令）");
     program
         .command("path")
@@ -19,12 +22,15 @@ export function createProgram() {
     });
     registerLaunchCommand(program);
     registerBridgeCommand(program);
+    registerSetupCommand(program);
     for (const tool of TOOLS) {
         registerToolCommand(program, tool);
     }
+    registerHomeCommand(program);
     program.configureOutput({
         writeErr: (str) => process.stderr.write(str),
     });
+    program.addHelpText("afterAll", "\n反馈与建议：rchdg50@gmail.com\nGitHub Issues：https://github.com/rchdg/llmswitch/issues\n");
     return program;
 }
 export async function run(argv = process.argv) {

package/dist/commands/bridge-cmd.js

@@ -2,7 +2,7 @@ import { ensureBridgeForProfile, isBridgeAlive, isPidRunning, readPid, runBridge
 import { bridgeBaseUrl, bridgeRootUrl, readBridgeState, } from "../bridge/state.js";
 import { parseBridgePort } from "../bridge/runtime.js";
 import { DEFAULT_BRIDGE_HOST, DEFAULT_BRIDGE_PORT } from "../bridge/types.js";
-import { getActiveProfile, requireProfile } from "../store/profiles.js";
+import { getActiveProfile, resolveProfileOrThrow } from "../store/profiles.js";
 import { isTool } from "../types.js";
 export function registerBridgeCommand(program) {
     const bridge = program
@@ -104,7 +104,7 @@ export function registerBridgeCommand(program) {
         }
         const tool = toolName;
         const profile = opts.profile
-            ? requireProfile(tool, opts.profile)
+            ? resolveProfileOrThrow(tool, opts.profile)
             : getActiveProfile(tool);
         if (!profile) {
             throw new Error(`没有可用的 ${tool} profile`);

package/dist/commands/home-cmd.js

@@ -0,0 +1,8 @@
+import { pickSetupTool, runToolFlow } from "./setup-cmd.js";
+/** 无子命令时：选择工具 → 连贯启动（未配置则自动引导）。 */
+export function registerHomeCommand(program) {
+    program.action(async () => {
+        const tool = await pickSetupTool();
+        await runToolFlow(tool);
+    });
+}

package/dist/commands/launch-cmd.js

@@ -1,5 +1,8 @@
+import * as p from "@clack/prompts";
 import { isTool, TOOLS } from "../types.js";
+import { listProfiles } from "../store/profiles.js";
 import { launchTool, resolveBinary, resolveLaunchTarget, } from "./launch.js";
+import { runSetupWizard } from "./setup-cmd.js";
 /**
  * ollama-like quick start:
  *   llms launch codex --model gpt-4.1
@@ -23,6 +26,21 @@ export function registerLaunchCommand(program) {
         if (!isTool(toolArg)) {
             throw new Error(`未知工具「${toolArg}」。可选：${TOOLS.join(", ")}`);
         }
+        if (listProfiles(toolArg).length === 0 &&
+            process.stdin.isTTY &&
+            !opts.dryRun) {
+            const setup = await p.confirm({
+                message: `${toolArg} 尚未配置供应商，是否进入引导？`,
+                initialValue: true,
+            });
+            if (p.isCancel(setup)) {
+                p.cancel("已取消");
+                process.exit(0);
+            }
+            if (setup) {
+                await runSetupWizard(toolArg);
+            }
+        }
         let model = opts.model?.trim() || undefined;
         const queue = [...parts];
         if (!model && queue[0] && !queue[0].startsWith("-")) {

package/dist/commands/launch.js

@@ -3,7 +3,7 @@ import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import { isTool } from "../types.js";
 import { applyProfile } from "../adapters/index.js";
-import { getActiveProfile, getDefaultProfile, listProfiles, requireProfile, saveProfile, ensureDefaultProvider, } from "../store/profiles.js";
+import { getActiveProfile, getDefaultProfile, listProfiles, requireProfile, resolveProfileOrThrow, saveProfile, ensureDefaultProvider, } from "../store/profiles.js";
 const BINARY = {
     claude: "claude",
     codex: "codex",
@@ -75,7 +75,7 @@ export function resolveLaunchTarget(tool, opts) {
     const modelQuery = opts.model?.trim() || undefined;
     let profile = null;
     if (opts.profile) {
-        profile = requireProfile(tool, opts.profile);
+        profile = resolveProfileOrThrow(tool, opts.profile);
     }
     if (!profile && modelQuery) {
         profile = findProfileForModel(profiles, modelQuery);