@cc-x/cc-x 0.4.6 → 0.4.7

package/README.en.md

@@ -1,25 +1,44 @@
-# ccx
+<h1 align="center">CC-X</h1>
+
+<p align="center">
+  <strong>No config files · Process isolation · Parallel terminals · Zero deps</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/becomeless/cc-x/releases/latest"><img src="https://img.shields.io/github/v/release/becomeless/cc-x?style=flat-square&color=blue" alt="version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/becomeless/cc-x?style=flat-square" alt="license"></a>
+  <a href="https://github.com/becomeless/cc-x/releases/latest"><img src="https://img.shields.io/github/downloads/becomeless/cc-x/total?style=flat-square&color=success" alt="downloads"></a>
+  <a href="https://github.com/becomeless/cc-x/actions"><img src="https://img.shields.io/github/actions/workflow/status/becomeless/cc-x/release.yml?style=flat-square&label=build" alt="build"></a>
+</p>
+
+<p align="center">
+  <a href="README.md">🇨🇳 中文</a> · <a href="README.en.md">🇺🇸 English</a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> · <a href="#60-second-quick-start">Quick Start</a> · <a href="#two-modes-the-key-concept">Concepts</a> · <a href="#configuration">Config</a> · <a href="#faq">FAQ</a>
+</p>
+
+---
 
 > `xx` — one command to switch Claude Code between APIs. **Zero config risk.**
->
-> [简体中文](README.md) | English
 
 Switching Claude Code between the official account and third-party APIs means juggling
-environment variables — or trusting a tool that rewrites your Claude config. ccx takes a
+environment variables — or trusting a tool that rewrites your Claude config. CC-X takes a
 different path: **switching happens purely at the environment-variable layer.** It never
 reads or writes any Claude Code config file. Your MCP, plugins, hooks — it won't touch them.
 
 ```text
-  cc-x v0.4.6 · Claude Code API switcher     (default = used by bare `claude` in new terminals)
+  CC-X v0.4.7 · Claude Code API switcher     Default: Official
 
    ▶ Official          (default)[Logged in]
-     DeepSeek                   [Key set] — work
-     智谱GLM                    [No key]
-     小米MiMo                   [No key]
+     DeepSeek            [Key set] — work
+     Zhipu GLM           [No key]
+     Xiaomi MiMo         [No key]
 
-     New profile  ·  切换到中文  ·  Update check: off  ·  Exit
+     New profile  ·  Switch to 中文  ·  Update check: off  ·  Exit
 
-  ↑↓ move · Enter open · Shift+↑↓ reorder · q quit
+  ↑↓ move · Enter open · e edit · s session · d set-default · Shift+↑↓ reorder · q quit
 ```
 
 > **Two builds**: the **native Go build** is recommended — GitHub Releases provide a lightweight
@@ -32,6 +51,8 @@ reads or writes any Claude Code config file. Your MCP, plugins, hooks — it won
 
 > Install [Claude Code](https://claude.ai/code) first (`claude` on PATH). **Open a new terminal** after installing.
 
+### Step 1 · Install CC-X
+
 **Windows (native, recommended)**
 
 ```powershell
@@ -55,6 +76,19 @@ it prints a hint (the Unix installer deliberately doesn't edit your shell config
 npm install -g @cc-x/cc-x
 ```
 
+### Step 2 · Configure your API key
+
+```bash
+xx   # First run seeds 4 presets — pick one, edit, paste your key
+```
+
+### Step 3 · Start using it
+
+```bash
+xx DeepSeek -s     # Use this session, launch Claude now
+xx DeepSeek        # Set as default for new terminals
+```
+
 ---
 
 ## 60-second quick start
@@ -79,7 +113,7 @@ xx --help          # all options
 
 ## Two modes (the key concept)
 
-Which API Claude uses is decided by **environment variables**. ccx offers two scopes:
+Which API Claude uses is decided by **environment variables**. CC-X offers two scopes:
 
 | | Use this session (`-s`) | Set default |
 |---|---|---|
@@ -88,8 +122,11 @@ Which API Claude uses is decided by **environment variables**. ccx offers two sc
 | Running sessions | Unaffected | Unaffected (env freezes at process start) |
 | Best for | Parallel terminals on different APIs | Set your daily-driver API once |
 
-**Parallel example**: open 4 terminals and run `xx Official -s`, `xx DeepSeek -s`, `xx 智谱GLM -s`,
-`xx 小米MiMo -s` — four Claudes running at once, each on its own API, zero interference.
+> 💡 **Analogy**: "Use this session" is a quick oil change — just for this trip. "Set default" is
+> refilling the tank — every new drive uses it from now on.
+
+**Parallel example**: open 4 terminals and run `xx Official -s`, `xx DeepSeek -s`, `xx "Zhipu GLM" -s`,
+`xx "Xiaomi MiMo" -s` — four Claudes running at once, each on its own API, zero interference.
 
 **Why not a global config file?** `settings.json` is shared globally; editing it hits running
 sessions (classic symptom: another terminal suddenly says `cannot be parsed as a URL`).
@@ -97,11 +134,21 @@ Environment variables are naturally process-isolated.
 
 ---
 
-## ccx vs cc-switch
+## When CC-X is NOT the right tool
+
+- You need to manage MCP, hooks, plugins, or multiple CLIs → use [cc-switch](https://github.com/farion1231/cc-switch)
+- You only use the official API, never switch → you don't need CC-X
+- You want automatic config migration/backup → that's outside CC-X's scope
+
+CC-X cares more about boundaries than features. It does one thing: **switch APIs**.
+
+---
+
+## CC-X vs cc-switch
 
-cc-switch is an excellent full-featured GUI; ccx takes the opposite, minimal approach.
+cc-switch is an excellent full-featured GUI; CC-X takes the opposite, minimal approach.
 
-| | ccx (`xx`) | cc-switch |
+| | CC-X (`xx`) | cc-switch |
 |---|---|---|
 | Form | Terminal command (lightweight) | Desktop GUI (full-featured) |
 | Scope | Just API switching | API + MCP + multiple CLIs + prompts… |
@@ -109,18 +156,18 @@ cc-switch is an excellent full-featured GUI; ccx takes the opposite, minimal app
 | Can lose MCP? | **Physically impossible** | Users have reported it |
 | Parallel terminals | **Native** (process isolation) | Global switch; sessions can clash |
 
-- → **ccx**: terminal natives, parallel-session runners, anyone burned by a config-wrecking switcher, "just switch the API" people
+- → **CC-X**: terminal natives, parallel-session runners, anyone burned by a config-wrecking switcher, "just switch the API" people
 - → **cc-switch**: GUI preference, all-in-one MCP + multi-CLI management
 
 ---
 
 ## Design philosophy
 
-> ccx cares more about boundaries than features.
+> CC-X cares more about boundaries than features.
 
-Claude Code already has its own config system, MCP ecosystem, and session state. ccx is not trying to become a control panel above it, or to copy user config into another database. It stands at one narrow point before Claude Code starts: prepare the 7 managed environment variables, then let Claude Code run.
+Claude Code already has its own config system, MCP ecosystem, and session state. CC-X is not trying to become a control panel above it, or to copy user config into another database. It stands at one narrow point before Claude Code starts: prepare the 7 managed environment variables, then let Claude Code run.
 
-That constraint is deliberate: no writes to Claude Code config files, no MCP management, no automatic migration, no resident background controller. If process environment variables can solve it, ccx avoids global files; if a choice matters, the user makes it explicitly. Doing less keeps the failure surface small.
+That constraint is deliberate: no writes to Claude Code config files, no MCP management, no automatic migration, no resident background controller. If process environment variables can solve it, CC-X avoids global files; if a choice matters, the user makes it explicitly. Doing less keeps the failure surface small.
 
 Issues / PRs are welcome, but the direction is clear: **make switching steadier, clearer, and less intrusive** before adding broader management power. Anything that writes a Claude Code config file will not be accepted.
 
@@ -140,7 +187,7 @@ Issues / PRs are welcome, but the direction is clear: **make switching steadier,
 | haiku → model | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | |
 | effort level | `CLAUDE_CODE_EFFORT_LEVEL` | `low`–`max`; `auto` = model default; empty = unset. Third parties may not honor it |
 
-> ccx **deliberately does not set** `ANTHROPIC_MODEL`. Use `/model opus|sonnet|haiku` in-session;
+> CC-X **deliberately does not set** `ANTHROPIC_MODEL`. Use `/model opus|sonnet|haiku` in-session;
 > the mapping table translates to the provider's real model name.
 
 ### Auth field: AUTH_TOKEN vs API_KEY
@@ -186,7 +233,7 @@ Issues / PRs are welcome, but the direction is clear: **make switching steadier,
   - Same semantics either way: **only affects new terminals**; switching to "Official" clears all managed vars
 - **No Claude Code config file is ever modified.**
 
-ccx only touches these 7 "managed" variables (and clears the ones a target profile doesn't use):
+CC-X only touches these 7 "managed" variables (and clears the ones a target profile doesn't use):
 `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ANTHROPIC_DEFAULT_OPUS_MODEL`,
 `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `CLAUDE_CODE_EFFORT_LEVEL`.
 

package/README.md

@@ -1,15 +1,34 @@
-# ccx
+<h1 align="center">CC-X</h1>
+
+<p align="center">
+  <strong>不碰配置 · 进程隔离 · 多端并行 · 零依赖</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/becomeless/cc-x/releases/latest"><img src="https://img.shields.io/github/v/release/becomeless/cc-x?style=flat-square&color=blue" alt="version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/becomeless/cc-x?style=flat-square" alt="license"></a>
+  <a href="https://github.com/becomeless/cc-x/releases/latest"><img src="https://img.shields.io/github/downloads/becomeless/cc-x/total?style=flat-square&color=success" alt="downloads"></a>
+  <a href="https://github.com/becomeless/cc-x/actions"><img src="https://img.shields.io/github/actions/workflow/status/becomeless/cc-x/release.yml?style=flat-square&label=build" alt="build"></a>
+</p>
+
+<p align="center">
+  <a href="README.md">🇨🇳 中文</a> · <a href="README.en.md">🇺🇸 English</a>
+</p>
+
+<p align="center">
+  <a href="#安装">安装</a> · <a href="#60-秒上手">上手</a> · <a href="#两种模式核心概念">概念</a> · <a href="#配置说明">配置</a> · <a href="#faq">FAQ</a>
+</p>
+
+---
 
 > `xx` — Claude Code 多 API 切换，一个命令搞定。**不碰配置，不怕翻车。**
->
-> 简体中文 | [English](README.en.md)
 
 用 Claude Code 连第三方 API？每次手打环境变量太烦，换工具切又怕弄丢 MCP。
-ccx 把这事儿做到了最简——切换只在环境变量层，**不读写任何 Claude Code 配置文件**。
+CC-X 把这事儿做到了最简——切换只在环境变量层，**不读写任何 Claude Code 配置文件**。
 你的 MCP、插件、hooks，它碰都不会碰。
 
 ```text
-  cc-x v0.4.6 · Claude Code API 切换器     （默认 = 新终端裸敲 claude 用的）
+  CC-X v0.4.7 · Claude Code API 切换器     默认：官方
 
    ▶ 官方            （默认）[登录态]
      DeepSeek                [密钥已设] — 公司
@@ -18,7 +37,7 @@ ccx 把这事儿做到了最简——切换只在环境变量层，**不读写
 
      新增配置  ·  切换到 English  ·  更新检查：关闭  ·  退出
 
-  ↑↓ 选择 · Enter 进入 · Shift+↑↓ 排序 · q 退出
+  ↑↓ 选择 · Enter 进入 · e 编辑 · s 启动 · d 设默认 · Shift+↑↓ 排序 · q 退出
 ```
 
 > **两个版本**：推荐 **Go 原生版**——GitHub Release 提供轻量 `xx` / `xx.exe`，无需 Node.js，
@@ -31,6 +50,8 @@ ccx 把这事儿做到了最简——切换只在环境变量层，**不读写
 
 > 先装好 [Claude Code](https://claude.ai/code)（`claude` 在 PATH 中）。装完**新开一个终端**。
 
+### Step 1 · 安装 CC-X
+
 **Windows（推荐原生版）**
 
 ```powershell
@@ -53,6 +74,19 @@ curl -fsSL https://github.com/becomeless/cc-x/releases/latest/download/install.s
 npm install -g @cc-x/cc-x
 ```
 
+### Step 2 · 配置 API 密钥
+
+```bash
+xx   # 首次运行自动生成 4 个预设，选一个 → 编辑 → 填入你的 key
+```
+
+### Step 3 · 开始使用
+
+```bash
+xx DeepSeek -s     # 本次启用，立即启动 Claude
+xx DeepSeek        # 设为默认，以后新终端自动生效
+```
+
 ---
 
 ## 60 秒上手
@@ -76,7 +110,7 @@ xx --help          # 全部参数
 
 ## 两种模式（核心概念）
 
-Claude 用哪个 API 由**环境变量**决定。ccx 提供两种作用范围：
+Claude 用哪个 API 由**环境变量**决定。CC-X 提供两种作用范围：
 
 | | 本次启用 (`-s`) | 设为默认 |
 |---|---|---|
@@ -85,17 +119,29 @@ Claude 用哪个 API 由**环境变量**决定。ccx 提供两种作用范围：
 | 对正在跑的会话 | 零影响 | 零影响（进程启动时已定型） |
 | 适合 | 多终端并行，各跑各的 API | 定好主力 API，不用老切 |
 
+> 💡 **打个比方**：「本次启用」是临时换油——只管这一趟；「设为默认」是换了油箱里的油——以后新上车都用这个。
+
 **并行示例**：开 4 个终端分别 `xx 官方 -s`、`xx DeepSeek -s`、`xx 智谱GLM -s`、`xx 小米MiMo -s`——四个 Claude 同时干活、各用各的 API、互不打架。
 
 **为什么不用配置文件？** `settings.json` 全局共享，改它会波及正在跑的会话（典型症状：另一终端突然报 `cannot be parsed as a URL`）。环境变量天然进程隔离，避开了这个坑。
 
 ---
 
+## 什么时候不该用 CC-X
+
+- 你需要管理 MCP、hooks、插件、多 CLI → 用 [cc-switch](https://github.com/farion1231/cc-switch)
+- 你只用官方 API，不切第三方 → 不需要 CC-X
+- 你要自动迁移/备份配置 → 不在 CC-X 范围内
+
+CC-X 的边界比功能更重要。它只做一件事：**切 API**。
+
+---
+
 ## 和 cc-switch 怎么选
 
-cc-switch 是优秀的全能 GUI；ccx 走相反的极简路线。
+cc-switch 是优秀的全能 GUI；CC-X 走相反的极简路线。
 
-| | ccx (`xx`) | cc-switch |
+| | CC-X (`xx`) | cc-switch |
 |---|---|---|
 | 形态 | 终端命令（轻量） | 桌面 GUI（全能） |
 | 职责 | 只切 API | API + MCP + 多 CLI + 提示词… |
@@ -103,16 +149,16 @@ cc-switch 是优秀的全能 GUI；ccx 走相反的极简路线。
 | 能弄丢 MCP？ | **不可能** | 有用户反馈被覆盖 |
 | 多终端并行 | **原生支持**（进程隔离） | 全局切换，容易互扰 |
 
-- → **ccx**：命令行党、常多开终端、被切配置坑过、只想要「切 API」一件事
+- → **CC-X**：命令行党、常多开终端、被切配置坑过、只想要「切 API」一件事
 - → **cc-switch**：要 GUI、要一站式管 MCP 和多 CLI
 
 ---
 
 ## 设计哲学
 
-> ccx 的边界比功能更重要。
+> CC-X 的边界比功能更重要。
 
-Claude Code 已经有自己的配置系统、MCP 生态和会话状态。ccx 不想再造一个“上层控制台”，也不想把用户的配置收编进自己的数据库。它只站在 Claude Code 进程启动前的那一小步：把 7 个受管环境变量准备好，然后让 Claude Code 自己工作。
+Claude Code 已经有自己的配置系统、MCP 生态和会话状态。CC-X 不想再造一个"上层控制台"，也不想把用户的配置收编进自己的数据库。它只站在 Claude Code 进程启动前的那一小步：把 7 个受管环境变量准备好，然后让 Claude Code 自己工作。
 
 所以它的取舍是有意的：不写 Claude Code 配置文件，不接管 MCP，不做自动迁移，不做后台常驻管理。能用进程环境变量解决，就不碰全局文件；能让用户显式选择，就不替用户自动决定。少做一点，是为了把风险面压到足够小。
 
@@ -134,7 +180,7 @@ Claude Code 已经有自己的配置系统、MCP 生态和会话状态。ccx 不
 | haiku → 模型 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | |
 | effort 思考档 | `CLAUDE_CODE_EFFORT_LEVEL` | `low` ~ `max`；`auto`=模型默认；留空=不设。第三方不一定生效 |
 
-> ccx **刻意不设** `ANTHROPIC_MODEL`。在会话里用 `/model opus|sonnet|haiku` 选档，映射表负责翻译成对应供应商的模型名。
+> CC-X **刻意不设** `ANTHROPIC_MODEL`。在会话里用 `/model opus|sonnet|haiku` 选档，映射表负责翻译成对应供应商的模型名。
 
 ### 认证字段：AUTH_TOKEN vs API_KEY
 
@@ -173,7 +219,7 @@ Claude Code 已经有自己的配置系统、MCP 生态和会话状态。ccx 不
   - 语义一致：**只影响新终端**；切到「官方」会清除全部受管变量
 - **不修改任何 Claude Code 配置文件。**
 
-ccx 只动这 7 个「受管」环境变量，切换时清掉目标不用的：
+CC-X 只动这 7 个「受管」环境变量，切换时清掉目标不用的：
 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`CLAUDE_CODE_EFFORT_LEVEL`。
 
 > 💡 需要改 `settings.json`？直接用 Claude Code 的 `/update-config` 说需求（如"允许 npm 命令"），比让外部工具改可靠。

package/dist/actions.js

@@ -20,6 +20,7 @@ export function launchSession(p) {
     const res = sessionLaunch(p);
     if (res.claudeMissing) {
         console.error(`  ${T('session.noClaude')}`);
+        console.error(`  ${T('session.noClaudeHint')}`);
         process.exitCode = 1;
         return;
     }

package/dist/check.js

@@ -0,0 +1,59 @@
+/**
+ * Minimal read-only connectivity probe for a profile.
+ */
+import { getProviderEnvMap } from './config/store.js';
+import { T } from './i18n/index.js';
+const TIMEOUT_MS = 5000;
+/** Probe GET {base}/v1/models with the profile's configured auth. */
+export async function checkProfile(p) {
+    const m = getProviderEnvMap(p);
+    const base = (m.ANTHROPIC_BASE_URL ?? '').trim();
+    if (!base)
+        return { ok: false, message: T('check.noUrl') };
+    const headers = authHeaders(m);
+    if (!headers)
+        return { ok: false, message: T('check.noKey') };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const resp = await fetch(`${base.replace(/\/+$/, '')}/v1/models`, {
+            method: 'GET',
+            headers: { ...headers, 'anthropic-version': '2023-06-01' },
+            signal: controller.signal,
+        });
+        return classifyHttp(resp.status);
+    }
+    catch (e) {
+        if (e.name === 'AbortError')
+            return { ok: false, message: T('check.timeout') };
+        const code = e.cause && typeof e.cause === 'object'
+            ? e.cause.code
+            : e.code;
+        if (code === 'ENOTFOUND' || code === 'EAI_AGAIN')
+            return { ok: false, message: T('check.dns') };
+        return { ok: false, message: T('check.network') };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** HTTP 状态码 -> 结果分层（纯函数，便于测试）。 */
+export function classifyHttp(status) {
+    const code = String(status);
+    if (status >= 200 && status < 300)
+        return { ok: true, message: T('check.ok', code) };
+    if (status === 401 || status === 403)
+        return { ok: false, message: T('check.auth', code) };
+    if (status === 404)
+        return { ok: false, message: T('check.notFound', code) };
+    return { ok: false, message: T('check.http', code) };
+}
+export function authHeaders(m) {
+    const apiKey = (m.ANTHROPIC_API_KEY ?? '').trim();
+    if (apiKey)
+        return { 'x-api-key': apiKey };
+    const token = (m.ANTHROPIC_AUTH_TOKEN ?? '').trim();
+    if (token)
+        return { Authorization: `Bearer ${token}` };
+    return undefined;
+}

package/dist/i18n/index.js

@@ -49,5 +49,13 @@ export function resolveLang(explicit, storeLang) {
  * 其余是专有名词，原样显示 `name`。
  */
 export function providerDisplayName(p) {
-    return isOfficial(p) ? T('provider.official') : p.name;
+    if (isOfficial(p))
+        return T('provider.official');
+    if (p.name === 'DeepSeek')
+        return T('provider.deepseek');
+    if (p.name === '智谱GLM')
+        return T('provider.zhipu');
+    if (p.name === '小米MiMo')
+        return T('provider.mimo');
+    return p.name;
 }

package/dist/i18n/messages.js

@@ -24,17 +24,25 @@ export const messages = {
     'state.noKey': { zh: '密钥未填', en: 'No key' },
     'state.apiKey': { zh: '密钥·API_KEY', en: 'Key · API_KEY' },
     'state.hasKey': { zh: '密钥已设', en: 'Key set' },
-    // —— 供应商显示名（仅官方这种普通名词需要翻译；DeepSeek/GLM/MiMo 是专有名词不翻）——
+    // —— 当前终端环境（只读）——
+    'terminal.current': { zh: '当前终端：{0}', en: 'Current terminal: {0}' },
+    'terminal.official': { zh: '未设置 / 官方登录态', en: 'not set / official login' },
+    'terminal.matched': { zh: '{0} → {1}', en: '{0} -> {1}' },
+    'terminal.unmatched': { zh: '{0}（未匹配配置）', en: '{0} (no matching profile)' },
+    // —— 供应商显示名（只影响显示，不改变 providers.json 里的 profile key）——
     'provider.official': { zh: '官方', en: 'Official' },
+    'provider.deepseek': { zh: 'DeepSeek', en: 'DeepSeek' },
+    'provider.zhipu': { zh: '智谱GLM', en: 'Zhipu GLM' },
+    'provider.mimo': { zh: '小米MiMo', en: 'Xiaomi MiMo' },
     // —— 菜单通用 ——
     'menu.prompt': { zh: '输入序号 (q 取消): ', en: 'Enter number (q to cancel): ' },
     'menu.mainTitle': {
-        zh: 'cc-x v{0} · Claude Code API 切换器     （默认 = 新终端裸敲 claude 用的）',
-        en: 'cc-x v{0} · Claude Code API switcher     (default = used by bare `claude` in new terminals)',
+        zh: 'CC-X v{0} · Claude Code API 切换器     默认：{1}',
+        en: 'CC-X v{0} · Claude Code API switcher     Default: {1}',
     },
     'menu.mainHint': {
-        zh: '↑↓ 选择 · Enter 进入 · Shift+↑↓（或 PgUp/PgDn）排序 · q 退出',
-        en: '↑↓ move · Enter open · Shift+↑↓ (or PgUp/PgDn) reorder · q quit',
+        zh: '↑↓ 选择 · Enter 进入 · e 编辑 · s 启动 · d 设默认 · Shift+↑↓ 排序 · q 退出',
+        en: '↑↓ move · Enter open · e edit · s session · d set-default · Shift+↑↓ reorder · q quit',
     },
     'menu.newProfile': { zh: '新增配置', en: 'New profile' },
     'menu.exit': { zh: '退出', en: 'Exit' },
@@ -44,6 +52,7 @@ export const messages = {
     'menu.updateOff': { zh: '更新检查：关闭', en: 'Update check: off' },
     'menu.updateNotify': { zh: '更新检查：提醒', en: 'Update check: notify' },
     'menu.updateAvailable': { zh: '有新版本 {0} · 升级：{1}', en: 'New version {0} · upgrade: {1}' },
+    'menu.firstRunHint': { zh: '首次配置：① 选供应商 → ② 填密钥 → ③ 本次启用', en: 'First setup: 1. pick a provider -> 2. paste key -> 3. use this session' },
     // —— 动作菜单 ——
     'action.titlePrefix': { zh: '配置：', en: 'Profile: ' },
     'action.session': {
@@ -54,13 +63,14 @@ export const messages = {
         zh: '设为默认    — 新终端裸敲 claude 默认用它（不影响运行中会话）',
         en: 'Set default — used by bare claude in new terminals (running sessions unaffected)',
     },
+    'action.check': { zh: '配置自检    — 只读探测 API 地址与密钥', en: 'Check config — read-only probe for API URL and key' },
     'action.edit': { zh: '编辑', en: 'Edit' },
     'action.delete': { zh: '删除', en: 'Delete' },
     'action.back': { zh: '返回', en: 'Back' },
     'action.hint': { zh: '↑↓ 选择 · Enter 确认 · q 返回', en: '↑↓ move · Enter select · q back' },
     'action.deleteConfirm': { zh: '确认删除 [{0}]? (y/N): ', en: 'Delete [{0}]? (y/N): ' },
     'action.deleteOfficialWarn': { zh: '建议保留『官方』。', en: 'Keeping "Official" is recommended.' },
-    'menu.language': { zh: '切换到 English', en: '切换到中文' },
+    'menu.language': { zh: '切换到 English', en: 'Switch to 中文' },
     // —— 通用占位 ——
     'empty.paren': { zh: '(空)', en: '(empty)' },
     // —— 编辑表单 ——
@@ -107,6 +117,7 @@ export const messages = {
     // —— 错误 ——
     'error.notFound': { zh: '找不到配置：{0}', en: 'Profile not found: {0}' },
     'error.existing': { zh: '现有：{0}', en: 'Existing: {0}' },
+    'error.notFoundHint': { zh: '下一步：运行 `xx -l` 查看配置，或运行 `xx` 打开菜单。', en: 'Next: run `xx -l` to list profiles, or `xx` to open the menu.' },
     'error.storeRead': { zh: '配置文件读取失败：{0}', en: 'Failed to read config file: {0}' },
     'error.storeCorrupt': { zh: '配置文件解析失败（JSON 语法错误）：{0}', en: 'Failed to parse config file (invalid JSON): {0}' },
     'error.storeFormat': { zh: '配置文件结构不正确（顶层须为对象、providers 须为数组且条目结构合法）：{0}', en: 'Config file has invalid structure (top-level must be an object, providers must be an array with valid profile entries): {0}' },
@@ -114,6 +125,7 @@ export const messages = {
         zh: '为避免误删，未对它做任何改动。请修复后重试；或删除该文件以重新生成默认配置（会丢失已填的密钥）。',
         en: 'Left untouched to avoid data loss. Fix it and retry; or delete the file to regenerate defaults (loses any saved keys).',
     },
+    'error.storeBackupHint': { zh: '修复前先备份：{0}', en: 'Back it up first: {0}' },
     // —— 本次启用（session）——
     'session.noKey': { zh: '⚠ 配置 [{0}] 还没填密钥。', en: '⚠ Profile [{0}] has no key set.' },
     'session.launch': {
@@ -125,12 +137,28 @@ export const messages = {
         en: 'Launching Claude… (returns here after Claude exits)',
     },
     'session.noClaude': { zh: '未找到 claude 命令，请确认它在 PATH 中。', en: 'claude not found on PATH.' },
+    'session.noClaudeHint': { zh: '下一步：安装 Claude Code 后新开终端；npm 用户可运行 `npm install -g @anthropic-ai/claude-code`。', en: 'Next: install Claude Code and open a new terminal; npm users can run `npm install -g @anthropic-ai/claude-code`.' },
+    // —— 配置自检（只读网络探测）——
+    'check.noUrl': { zh: '官方登录态 / 未设置 API 地址，无需自检。', en: 'Official login / no API URL set; nothing to probe.' },
+    'check.noKey': { zh: '还没填密钥，无法自检。', en: 'No key set; cannot probe.' },
+    'check.ok': { zh: '✓ 配置自检通过（HTTP {0}）', en: '✓ Config check passed (HTTP {0})' },
+    'check.auth': { zh: '鉴权失败（HTTP {0}），检查密钥和认证字段。', en: 'Authentication failed (HTTP {0}); check key and auth field.' },
+    'check.dns': { zh: 'DNS 解析失败，检查 API 地址或网络。', en: 'DNS lookup failed; check API URL or network.' },
+    'check.timeout': { zh: '连接超时，请稍后重试或检查网络。', en: 'Connection timed out; retry later or check network.' },
+    'check.notFound': { zh: '接口不存在（HTTP {0}），检查 API 地址是否缺少 /anthropic 等后缀。', en: 'Endpoint not found (HTTP {0}); check whether the API URL is missing a suffix like /anthropic.' },
+    'check.http': { zh: '请求返回 HTTP {0}，检查 API 地址、密钥或账户状态。', en: 'Request returned HTTP {0}; check API URL, key, or account state.' },
+    'check.network': { zh: '网络请求失败，检查网络或 curl 是否可用。', en: 'Network request failed; check network or curl availability.' },
     // —— 设为默认（default）——
     'default.writing': { zh: '正在写入用户环境变量…', en: 'Writing user environment variables…' },
+    'default.noKey': {
+        zh: '⚠ {0} 还没填密钥；设为默认后，新终端的 claude 仍不可用。',
+        en: '⚠ {0} has no key; after setting it as default, claude in new terminals will still fail.',
+    },
     'default.done': {
         zh: '✓ 已设为默认：{0}  ·  新开终端裸敲 claude 生效（不影响运行中会话）',
         en: '✓ Default set: {0}  ·  effective in newly opened terminals (running sessions unaffected)',
     },
+    'default.hintSession': { zh: '若只想本次使用：xx -s {0}', en: 'To use this session only: xx -s {0}' },
     'default.dryRun': {
         zh: '（dry-run：--default-scope process，未改系统，仅更新存储）',
         en: '(dry-run: --default-scope process; system untouched, store only)',

package/dist/index.js

@@ -8,11 +8,12 @@
  */
 import { createRequire } from 'node:module';
 import { Command, Option } from 'commander';
-import { launchSession, warnIfNoKey } from './actions.js';
-import { loadStore, peekStoreLang, resolveStorePaths, StoreError } from './config/store.js';
+import { launchSession } from './actions.js';
+import { getProviderState, loadStore, peekStoreLang, resolveStorePaths, StoreError } from './config/store.js';
 import { loadPresets } from './config/presets.js';
 import { setDefault } from './env/default.js';
 import { providerDisplayName, resolveLang, setLang, T } from './i18n/index.js';
+import { currentTerminalLine } from './runtime-info.js';
 import { noteSuffix, stateLabel } from './ui/format.js';
 import { openMenu } from './ui/menus.js';
 import { padDisplay } from './utils/display.js';
@@ -75,6 +76,9 @@ async function dispatch(name, opts) {
             const head = e.kind === 'read' ? 'error.storeRead' : e.kind === 'format' ? 'error.storeFormat' : 'error.storeCorrupt';
             console.error(`  ${T(head, e.file)}`);
             console.error(`  ${T('error.storeCorruptHint')}`);
+            if (e.kind === 'parse' || e.kind === 'format') {
+                console.error(`  ${T('error.storeBackupHint', backupCommand(e.file))}`);
+            }
             process.exitCode = 1;
             return;
         }
@@ -87,10 +91,11 @@ async function dispatch(name, opts) {
         return;
     }
     if (name) {
-        const target = store.providers.find((p) => p.name === name);
+        const target = findProviderForCli(store, name);
         if (!target) {
             console.error(`  ${T('error.notFound', name)}`);
-            console.error(`  ${T('error.existing', store.providers.map((p) => p.name).join(', '))}`);
+            console.error(`  ${T('error.existing', store.providers.map((p) => providerDisplayName(p)).join(', '))}`);
+            console.error(`  ${T('error.notFoundHint')}`);
             process.exitCode = 1;
             return;
         }
@@ -102,11 +107,15 @@ async function dispatch(name, opts) {
     }
     await openMenu(paths, store, opts.defaultScope, pkg.version, loadPresets(opts.storeDir));
 }
+function findProviderForCli(store, name) {
+    return store.providers.find((p) => p.name === name) ?? store.providers.find((p) => providerDisplayName(p) === name);
+}
 /** `--list`：列出所有配置及状态。官方档显示名走 i18n（评审①），其余原样。 */
 function runList(store) {
     const cur = store.providers.find((p) => p.name === store.current);
     console.log('');
     console.log(`  ${T('list.default', cur ? providerDisplayName(cur) : store.current)}`);
+    console.log(`  ${currentTerminalLine(store)}`);
     for (const p of store.providers) {
         const mark = p.name === store.current ? '▶' : ' ';
         console.log(`   ${mark} ${padDisplay(providerDisplayName(p), 18)}[${stateLabel(p)}]${noteSuffix(p)}`);
@@ -115,12 +124,13 @@ function runList(store) {
 }
 /** 设为默认：写用户环境变量（或 dry-run）+ 更新 store.current。 */
 function runDefault(paths, store, p, scope) {
-    warnIfNoKey(p);
+    warnIfNoKeyForDefault(p);
     const name = providerDisplayName(p);
     const r = setDefault(paths, store, p, scope);
     if (r.dryRun) {
         console.log(`  ${T('default.done', name)}`);
         console.log(`  ${T('default.dryRun')}`);
+        console.log(`  ${T('default.hintSession', quoteArg(p.name))}`);
         return;
     }
     if (r.windows && !r.windows.ok) {
@@ -135,5 +145,27 @@ function runDefault(paths, store, p, scope) {
     console.log(`  ${T('default.done', name)}`);
     if (r.unix)
         console.log(`  ${T('default.unixWrote', r.unix.file)}`);
+    console.log(`  ${T('default.hintSession', quoteArg(p.name))}`);
+}
+function warnIfNoKeyForDefault(p) {
+    if (getProviderState(p).key === 'noKey') {
+        console.log(`  ${T('default.noKey', providerDisplayName(p))}`);
+    }
+}
+function backupCommand(file) {
+    const dst = `${file}.bak`;
+    if (process.platform === 'win32') {
+        return `Copy-Item -LiteralPath ${psQuote(file)} -Destination ${psQuote(dst)}`;
+    }
+    return `cp ${shQuote(file)} ${shQuote(dst)}`;
+}
+function psQuote(s) {
+    return `'${s.replaceAll("'", "''")}'`;
+}
+function shQuote(s) {
+    return `'${s.replaceAll("'", `'"'"'`)}'`;
+}
+function quoteArg(s) {
+    return `"${s.replaceAll('"', '\\"')}"`;
 }
 main();

package/dist/runtime-info.js

@@ -0,0 +1,33 @@
+/**
+ * Read-only facts about the current terminal process.
+ */
+import { getProviderEnvMap } from './config/store.js';
+import { providerDisplayName, T } from './i18n/index.js';
+/** Key-safe description of the API currently visible to this terminal process. */
+export function currentTerminalLine(store) {
+    return T('terminal.current', currentTerminalTarget(store));
+}
+function currentTerminalTarget(store) {
+    const base = (process.env.ANTHROPIC_BASE_URL ?? '').trim();
+    if (!base)
+        return T('terminal.official');
+    const host = hostOf(base);
+    const match = store.providers.find((p) => sameBase(base, getProviderEnvMap(p).ANTHROPIC_BASE_URL ?? ''));
+    if (match)
+        return T('terminal.matched', host, providerDisplayName(match));
+    return T('terminal.unmatched', host);
+}
+function sameBase(a, b) {
+    return a.trim().replace(/\/+$/, '') === b.trim().replace(/\/+$/, '');
+}
+/** 从 API 地址提取 host（解析失败则原样返回），供菜单行尾显示复用。 */
+export function hostOf(raw) {
+    const r = raw.trim();
+    try {
+        const u = new URL(r);
+        return u.host || r;
+    }
+    catch {
+        return r;
+    }
+}

package/dist/ui/edit.js

@@ -24,11 +24,15 @@ function fromProvider(p) {
         effort: m.CLAUDE_CODE_EFFORT_LEVEL ?? '',
     };
 }
-/** 编辑 `prov`（就地修改）；保存返回 true，放弃返回 false。 */
-export async function editForm(prov, store, catalog) {
+/**
+ * 编辑 `prov`（就地修改）；保存返回 true，放弃返回 false。
+ * focusKey=true 时初始光标落在密钥行（#9：无 key 配置 Enter 直达填密钥的最短路径）。
+ */
+export async function editForm(prov, store, catalog, focusKey = false) {
     const W = fromProvider(prov);
     let showSecret = false;
-    let start = 0;
+    // rows 布局固定：provider,note,base,auth,key,…（密钥行索引为 4）。
+    let start = focusKey ? 4 : 0;
     for (;;) {
         const v = (x) => (x === '' ? T('empty.paren') : x);
         const keyDisp = W.token === '' ? T('empty.paren') : showSecret ? W.token : '********';

package/dist/ui/menus.js

@@ -5,30 +5,32 @@
  * 动作菜单：本次启用 / 设为默认（绿条 toast）/ 编辑 / 删除（二次确认）/ 返回。
  * 编辑表单见 ui/edit.ts（含密钥明文切换）。
  */
-import { createInterface } from 'node:readline';
 import { launchSession } from '../actions.js';
-import { isOfficial, reconcileCurrent, saveStore } from '../config/store.js';
+import { checkProfile } from '../check.js';
+import { getProviderEnvMap, getProviderState, isOfficial, reconcileCurrent, saveStore } from '../config/store.js';
 import { setDefault } from '../env/default.js';
 import { getLang, providerDisplayName, setLang, T } from '../i18n/index.js';
+import { currentTerminalLine, hostOf } from '../runtime-info.js';
 import { banner as updateBanner, maybeRefresh, MODE_NOTIFY, upgradeCommand } from '../update/update.js';
+import { paint } from '../utils/ansi.js';
 import { padDisplay } from '../utils/display.js';
 import { editForm } from './edit.js';
 import { noteSuffix, stateLabel } from './format.js';
-import { selectMenu } from './select.js';
-async function readLine(prompt) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const ans = await new Promise((res) => rl.question(prompt, res));
-    rl.close();
-    return ans.trim();
-}
+import { confirmKey, selectMenu } from './select.js';
 /** 一级 · 主菜单。布局：[profiles…] '' 新增 语言 '' 退出。 */
 export async function openMenu(paths, store, scope, version, catalog) {
     let sel = 0;
     let refreshed = false;
+    let flash;
+    let warnFlash;
     for (;;) {
         const n = store.providers.length;
         // 更新检查（仅 notify 模式）：首轮触发一次后台刷新；横幅永远读缓存（瞬时、不阻塞）。
-        let notice;
+        const notices = [currentTerminalLine(store)];
+        if (needsFirstRunHint(store))
+            notices.push(T('menu.firstRunHint'));
+        if (warnFlash)
+            notices.push(warnFlash);
         if (store.update === MODE_NOTIFY) {
             if (!refreshed) {
                 maybeRefresh(paths.dir);
@@ -36,13 +38,13 @@ export async function openMenu(paths, store, scope, version, catalog) {
             }
             const latest = updateBanner(paths.dir, version);
             if (latest)
-                notice = T('menu.updateAvailable', latest, upgradeCommand());
+                notices.push(T('menu.updateAvailable', latest, upgradeCommand()));
         }
         const updLabel = store.update === MODE_NOTIFY ? T('menu.updateNotify') : T('menu.updateOff');
         const buildItems = () => {
             const labels = store.providers.map((p) => {
                 const dft = p.name === store.current ? T('menu.default') : '';
-                return `${padDisplay(providerDisplayName(p), 16)}${padDisplay(dft, 8)}[${stateLabel(p)}]${noteSuffix(p)}`;
+                return `${padDisplay(providerDisplayName(p), 16)}${padDisplay(dft, 8)}[${stateLabel(p)}]${noteSuffix(p)}${hostSuffix(p)}`;
             });
             return [...labels, '', T('menu.newProfile'), T('menu.language'), updLabel, '', T('menu.exit')];
         };
@@ -57,17 +59,51 @@ export async function openMenu(paths, store, scope, version, catalog) {
             }
             return buildItems();
         };
+        const defaultName = defaultDisplayName(store);
+        let shortcut = '';
         sel = await selectMenu({
-            title: T('menu.mainTitle', version),
-            ...(notice ? { notice } : {}),
+            title: T('menu.mainTitle', version, defaultName),
+            notice: notices.join('\n'),
+            ...(flash ? { status: flash } : {}),
             items: buildItems(),
             colors: { [n + 1]: 'yellow' },
             start: sel,
             movableCount: n,
             onMove,
+            onKey: (r, idx) => {
+                if (idx >= n)
+                    return -1;
+                if (r === 'e' || r === 's' || r === 'd') {
+                    shortcut = r;
+                    return idx;
+                }
+                return -1;
+            },
             hint: T('menu.mainHint'),
             noNumber: true,
         });
+        flash = undefined;
+        warnFlash = undefined;
+        if (shortcut && sel >= 0 && sel < n) {
+            const target = store.providers[sel];
+            if (!target)
+                continue;
+            if (shortcut === 'e') {
+                const old = target.name;
+                if (await editForm(target, store, catalog)) {
+                    if (store.current === old)
+                        store.current = target.name;
+                    saveStore(paths, store);
+                }
+            }
+            else if (shortcut === 's') {
+                launchSession(target);
+            }
+            else if (shortcut === 'd') {
+                ({ warn: warnFlash, toast: flash } = applyDefault(paths, store, target, scope));
+            }
+            continue;
+        }
         if (sel < 0 || sel === n + 5)
             return; // 退出 / Esc / q
         if (sel === n + 1) {
@@ -96,8 +132,20 @@ export async function openMenu(paths, store, scope, version, catalog) {
         }
         else if (sel < n) {
             const target = store.providers[sel];
-            if (target)
-                await actionMenu(paths, store, target, scope, catalog);
+            if (target) {
+                if (!isOfficial(target) && getProviderState(target).key === 'noKey') {
+                    // #9：无密钥的第三方配置，Enter 直达编辑并聚焦密钥行（铺平首次成功路径）。
+                    const old = target.name;
+                    if (await editForm(target, store, catalog, true)) {
+                        if (store.current === old)
+                            store.current = target.name;
+                        saveStore(paths, store);
+                    }
+                }
+                else {
+                    await actionMenu(paths, store, target, scope, catalog);
+                }
+            }
             if (sel >= store.providers.length)
                 sel = Math.max(0, store.providers.length - 1); // 删除后夹取
         }
@@ -107,19 +155,36 @@ export async function openMenu(paths, store, scope, version, catalog) {
 async function actionMenu(paths, store, p, scope, catalog) {
     let sel = 0;
     let flash;
+    let warnFlash; // 黄字警告（如缺密钥），走 notice 与绿色 status 区分
     for (;;) {
         const dft = p.name === store.current ? T('menu.default') : '';
         const title = `${T('action.titlePrefix')}${providerDisplayName(p)}${dft}${noteSuffix(p)}    [${stateLabel(p)}]`;
-        const items = [T('action.session'), T('action.setDefault'), T('action.edit'), T('action.delete'), T('action.back')];
-        sel = await selectMenu({ title, items, start: sel, ...(flash ? { status: flash } : {}), hint: T('action.hint'), noNumber: true });
+        const items = [T('action.session'), T('action.setDefault'), T('action.check'), T('action.edit'), T('action.delete'), T('action.back')];
+        sel = await selectMenu({
+            title,
+            items,
+            start: sel,
+            ...(warnFlash ? { notice: warnFlash } : {}),
+            ...(flash ? { status: flash } : {}),
+            hint: T('action.hint'),
+            noNumber: true,
+        });
         flash = undefined;
+        warnFlash = undefined;
         if (sel === 0) {
             launchSession(p);
         }
         else if (sel === 1) {
-            flash = applyDefault(paths, store, p, scope);
+            ({ warn: warnFlash, toast: flash } = applyDefault(paths, store, p, scope));
         }
         else if (sel === 2) {
+            const result = await checkProfile(p);
+            if (result.ok)
+                flash = result.message;
+            else
+                warnFlash = result.message;
+        }
+        else if (sel === 3) {
             const old = p.name;
             if (await editForm(p, store, catalog)) {
                 if (store.current === old)
@@ -127,11 +192,10 @@ async function actionMenu(paths, store, p, scope, catalog) {
                 saveStore(paths, store);
             }
         }
-        else if (sel === 3) {
+        else if (sel === 4) {
             if (isOfficial(p))
                 console.log(`  ${T('action.deleteOfficialWarn')}`);
-            const ans = await readLine(`  ${T('action.deleteConfirm', providerDisplayName(p))}`);
-            if (ans === 'y' || ans === 'Y') {
+            if (await confirmKey(T('action.deleteConfirm', providerDisplayName(p)))) {
                 store.providers = store.providers.filter((x) => x !== p);
                 reconcileCurrent(store);
                 saveStore(paths, store);
@@ -143,15 +207,43 @@ async function actionMenu(paths, store, p, scope, catalog) {
         }
     }
 }
-/** 设为默认并返回一行 toast 文案。 */
+function defaultDisplayName(store) {
+    if (!store.current)
+        return '—';
+    return providerDisplayName(store.providers.find((p) => p.name === store.current) ?? { name: store.current, env: {} });
+}
+/**
+ * 设为默认，返回 { warn, toast }：warn 为黄字警告（缺密钥），toast 为绿色结果。
+ * 分开返回让调用方各自上色，避免警告被染成「成功」绿。
+ */
 function applyDefault(paths, store, p, scope) {
     const name = providerDisplayName(p);
+    const warn = getProviderState(p).key === 'noKey' ? T('default.noKey', name) : '';
     const r = setDefault(paths, store, p, scope);
     if (r.dryRun)
-        return `${T('default.done', name)}  ${T('default.dryRun')}`;
+        return { warn, toast: `${T('default.done', name)}  ${T('default.dryRun')}` };
     if (r.windows && !r.windows.ok)
-        return T('default.failed', r.windows.error ?? '');
+        return { warn, toast: T('default.failed', r.windows.error ?? '') };
     if (r.unix?.unsupported)
-        return T('default.fishUnsupported');
-    return T('default.done', name);
+        return { warn, toast: T('default.fishUnsupported') };
+    return { warn, toast: T('default.done', name) };
+}
+// hostSuffix 返回行尾的灰字 host（如 ` · api.deepseek.com`）；无 base（官方/未填）返回空。
+// 超宽时由 selectMenu 的 ANSI-aware 截断从行尾裁掉，不会切坏颜色。
+function hostSuffix(p) {
+    const base = (getProviderEnvMap(p).ANTHROPIC_BASE_URL ?? '').trim();
+    if (!base)
+        return '';
+    return paint(` · ${hostOf(base)}`, 'dim');
+}
+function needsFirstRunHint(store) {
+    let hasThirdParty = false;
+    for (const p of store.providers) {
+        if (isOfficial(p))
+            continue;
+        hasThirdParty = true;
+        if (getProviderState(p).key !== 'noKey')
+            return false;
+    }
+    return hasThirdParty;
 }

package/dist/ui/select.js

@@ -42,10 +42,14 @@ export async function selectMenu(opts) {
             lines.push(`  ${paint(opts.title, 'cyan')}`, '');
         }
         if (opts.notice) {
-            lines.push(`  ${paint(opts.notice, 'yellow')}`, '');
+            for (const line of splitNonEmptyLines(opts.notice))
+                lines.push(`  ${paint(line, 'yellow')}`);
+            lines.push('');
         }
         if (opts.status) {
-            lines.push(`  ${paint(opts.status, 'green')}`, '');
+            for (const line of splitNonEmptyLines(opts.status))
+                lines.push(`  ${paint(line, 'green')}`);
+            lines.push('');
         }
         for (let i = 0; i < items.length; i++) {
             const it = items[i] ?? '';
@@ -124,8 +128,15 @@ export async function selectMenu(opts) {
                     cleanup(n - 1);
                 return;
             }
-            if (ch === 'q')
+            if (ch === 'q') {
                 cleanup(-1);
+                return;
+            }
+            if (opts.onKey) {
+                const r = opts.onKey(ch, idx);
+                if (r >= 0)
+                    cleanup(r);
+            }
         };
         stdin.on('keypress', onKey);
         render();
@@ -137,9 +148,20 @@ async function fallbackSelect(opts, items) {
     stdout.write('\n');
     if (opts.title)
         stdout.write(`  ${opts.title}\n\n`);
+    if (opts.notice) {
+        splitNonEmptyLines(opts.notice).forEach((line) => stdout.write(`  ${line}\n`));
+        stdout.write('\n');
+    }
+    if (opts.status) {
+        splitNonEmptyLines(opts.status).forEach((line) => stdout.write(`  ${line}\n`));
+        stdout.write('\n');
+    }
+    const indexMap = [];
     items.forEach((it, i) => {
-        if (it !== '')
-            stdout.write(`   ${i + 1}. ${it}\n`);
+        if (it !== '') {
+            indexMap.push(i);
+            stdout.write(`   ${indexMap.length}. ${it}\n`);
+        }
     });
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ans = await new Promise((res) => rl.question(`  ${T('menu.prompt')}`, res));
@@ -149,8 +171,49 @@ async function fallbackSelect(opts, items) {
         return -1;
     if (/^\d+$/.test(t)) {
         const n = Number.parseInt(t, 10);
-        if (n >= 1 && n <= items.length && items[n - 1] !== '')
-            return n - 1;
+        if (n >= 1 && n <= indexMap.length)
+            return indexMap[n - 1] ?? -1;
     }
     return -1;
 }
+function splitNonEmptyLines(s) {
+    return s
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim() !== '');
+}
+/**
+ * raw 模式下读一个按键确认（y/Y=是，其余任意键=否），无需回车，与菜单 raw 体验一致。
+ * 非 TTY 时回退到 cooked 读行。对应 Go 版 confirmKey。
+ */
+export async function confirmKey(prompt) {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        const ans = await new Promise((res) => rl.question(`  ${prompt}`, res));
+        rl.close();
+        const t = ans.trim();
+        return t === 'y' || t === 'Y';
+    }
+    stdout.write(`  ${prompt}`);
+    emitKeypressEvents(stdin);
+    const wasRaw = stdin.isRaw ?? false;
+    stdin.setRawMode(true);
+    stdin.resume();
+    return new Promise((resolve) => {
+        const onKey = (str, key) => {
+            stdin.off('keypress', onKey);
+            if (!wasRaw)
+                stdin.setRawMode(false);
+            stdin.pause();
+            stdout.write('\n');
+            if (key?.ctrl && key.name === 'c') {
+                resolve(false);
+                return;
+            }
+            resolve((str ?? '').toLowerCase() === 'y');
+        };
+        stdin.on('keypress', onKey);
+    });
+}

package/dist/utils/display.js

@@ -11,18 +11,47 @@ export function padDisplay(s, width) {
     const w = stringWidth(s);
     return w < width ? s + ' '.repeat(width - w) : s;
 }
-/** 按显示宽度截断到 `max`（防止超宽行在终端换行打乱原地重绘的行数计算）。 */
+/**
+ * 按显示宽度截断到 `max`（防止超宽行在终端换行打乱原地重绘的行数计算）。
+ * ANSI-aware：转义序列（\x1b[…m）不计入宽度且整段保留；着色中途截断时补 \x1b[0m 防颜色泄漏。
+ * （`stringWidth` 本身会剥离 ANSI，故首行判断已是可见宽度；逐字符循环需自行跳过转义序列。）
+ */
 export function truncateDisplay(s, max) {
     if (stringWidth(s) <= max)
         return s;
-    let w = 0;
+    const chars = [...s];
     let out = '';
-    for (const ch of s) {
-        const cw = stringWidth(ch);
+    let w = 0;
+    let colored = false;
+    for (let i = 0; i < chars.length; i++) {
+        if (chars[i] === '\x1b') {
+            const end = csiEnd(chars, i);
+            for (let k = i; k <= end; k++)
+                out += chars[k];
+            colored = true;
+            i = end;
+            continue;
+        }
+        const cw = stringWidth(chars[i] ?? '');
         if (w + cw > max)
             break;
-        out += ch;
+        out += chars[i];
         w += cw;
     }
+    if (colored)
+        out += '\x1b[0m';
     return out;
 }
+/** 从 ESC（chars[i]==='\x1b'）起返回 CSI 序列的最后一个下标（含终止字节 0x40–0x7E）。 */
+function csiEnd(chars, i) {
+    if (i + 1 >= chars.length || chars[i + 1] !== '[')
+        return i; // 孤立 ESC
+    let j = i + 2; // 跳过 ESC 和引导符 '['
+    while (j < chars.length) {
+        const c = chars[j] ?? '';
+        if (c >= '@' && c <= '~')
+            return j; // 终止字节
+        j++;
+    }
+    return chars.length - 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cc-x/cc-x",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Claude Code API 切换器（命令 xx）：在官方账号与第三方 Anthropic 兼容 API 间切换，纯环境变量、不碰 Claude Code 配置文件。",
   "keywords": [
     "claude",
@@ -29,6 +29,7 @@
   "files": [
     "dist/**/*.js",
     "!dist/release/**",
+    "!dist/**/*.test.js",
     "!dist/**/*.exe",
     "!dist/**/*.zip",
     "!dist/**/*.md",
@@ -47,6 +48,7 @@
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/check.test.ts src/runtime-info.test.ts",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {