feat: v1.8.0 usability and hardening upgrade

Close the biggest day-to-day gaps while keeping the live-gateway
advantage (in-session model switching):

- ccmr doctor: provider-side failures (expired keys, unactivated
  models, wrong endpoints) were only discoverable mid-session; now one
  command sends a tiny real request per model and surfaces the upstream
  error verbatim
- ccmr claude auto-starts the gateway: removes the two-terminal flow
- Hot reload of models.yaml/.env + ~/.ccmr global fallback + ccmr use:
  no more restart-to-apply or cwd-dependent config mismatches
- ccmr stats + GET /usage: per-model request/token accounting
- fallback chains: variant-level failover on upstream 5xx/429/timeouts
- init guards .env into .gitignore: a stray git add -A must not
  publish provider keys

Hardening: drop ESM-only node-fetch (CJS dist crashed on Node <22.12,
making engines >=18 a false promise) in favor of built-in fetch; stream
idle watchdog so a hung upstream cannot pin a connection forever;
timing-safe inbound auth comparison; friendly EADDRINUSE error.

Engineering: vitest suite (69 tests) incl. a DEFAULT_CONFIG<->YAML
template consistency test that already caught two real drifts; GitHub
Actions CI on Node 18/20/24 with a stale-dist check.

Author: 鲁工

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # 18 is the engines floor; verify it stays honest (built-in fetch, no ESM-only deps)
+        node-version: [18.x, 20.x, 24.x]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Verify committed dist matches source
+        run: |
+          if ! git diff --exit-code --stat dist/; then
+            echo "::error::dist/ is stale - run 'npm run build' and commit the result"
+            exit 1
+          fi
+
+      - name: Smoke test CLI
+        run: |
+          node dist/cli.js --version
+          node dist/cli.js models | head -30

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,23 @@
+# v1.8.0 实施计划（易用性 + 风险修复）
+
+按 review 结论分 5 个阶段实施，测试先行（vitest 基线 → 新功能 red-green）。
+
+| # | 阶段 | 内容 | 状态 |
+|---|------|------|------|
+| 0 | 测试基建 | vitest + ConfigManager/ModelRouter 基线测试 + DEFAULT_CONFIG↔YAML 模板一致性测试 | ✅ 完成 |
+| 1 | doctor + init 防护 | `ccmr doctor` 真实连通性自检；init 自动 .gitignore `.env` | ✅ 完成 |
+| 2 | 自动拉起 + 版本提示 | `ccmr claude` 探测 /health，不可达自动拉起网关；版本不一致警告 | ✅ 完成 |
+| 3 | CI | GitHub Actions: Node 18/20/24 build + test + dist 一致性 | ✅ 完成 |
+| 4 | 全局配置 + 热重载 + use | `~/.ccmr/` 兜底；watchFile 热重载；`ccmr use <model>` | ✅ 完成 |
+| 5 | 用量 + failover | UsageTracker + GET /usage + `ccmr stats`；fallback 降级链 | ✅ 完成 |
+| 6 | 杂项风险 | 流式空闲超时、timingSafeEqual、无条件日志、EADDRINUSE、移除 node-fetch/chalk | ✅ 完成 |
+| 7 | 自测 + 发布准备 | 69 测试全绿；init/use/热重载/doctor/自动拉起/stats 全部真实运行验证；README；v1.8.0 | ✅ 完成 |
+
+## 自测记录（2026-07-07）
+
+- `vitest run`：69/69 通过；一致性测试当场抓到模板两处真实漂移（`default_variant: 5.2` 未加引号、缺 `kimi-k2.6` 别名）并修复
+- `ccmr init`（scratch git 仓库）：`.env` 自动写入 `.gitignore` ✅
+- 热重载：`ccmr use kimi` → 网关日志出现 `[reload]`，`/health` 的 default_model 免重启切换 ✅
+- `ccmr doctor`（真实 key，ccmr-start）：7 ok / 3 fail / 18 skip；确认 seed-2.1-pro 已开通可用，暴露 seed-2.1-turbo 未开通、mimo-token-cn Key 失效 ✅
+- 自动拉起 E2E：`ccmr claude -p ... --gateway-port 8096`（空端口）→ 网关自动拉起 → DeepSeek 真实请求返回 `SELFTEST-OK` ✅
+- `ccmr stats`：正确显示 1 次请求 39148/41 tokens ✅

README.md

@@ -16,56 +16,75 @@
 npm install -g claude-code-model-router
 
 # 然后使用 ccmr 命令
-ccmr init
-ccmr start
+ccmr init      # 初始化配置（git 仓库内自动把 .env 加入 .gitignore）
+               # 或 ccmr init --global 写入 ~/.ccmr 全目录共享
+ccmr doctor    # （可选）连通性体检，确认各模型可用
 
-# 启动 Claude Code
+# 启动 Claude Code（网关未运行时自动拉起，无需单独开终端）
 ccmr claude    # 第三方模型（网关模式）
 claude         # 官方订阅（默认模式）
+
+# 日常切换默认模型
+ccmr use kimi
 ```
 
 ### 方式二：使用 npx
 
 ```bash
-# 1. 初始化配置文件
+# 1. 初始化配置文件（git 仓库内自动把 .env 加入 .gitignore）
 npx claude-code-model-router init
 
 # 2. 编辑 .env 文件，填入 API Keys
 
-# 3. 启动网关
-npx claude-code-model-router start
+# 3. （可选）连通性体检，确认各模型可用
+npx claude-code-model-router doctor
 
-# 4. 新开终端，启动 Claude Code
+# 4. 启动 Claude Code——网关未运行时会自动拉起，无需单独开终端
 # 第三方模型（网关模式）：
 npx claude-code-model-router claude
 
 # 官方订阅（默认模式）：
 claude
 ```
 
+> 也可以手动 `ccmr start` 前台启动网关（日志直接可见）；`ccmr claude` 自动拉起的网关日志在 `~/.ccmr/gateway.log`。
 
 ## 命令说明
 
 ```bash
-# 初始化配置文件
+# 初始化配置文件（git 仓库内会自动把 .env 加入 .gitignore）
 npx claude-code-model-router init
+npx claude-code-model-router init --global  # 写入 ~/.ccmr，全目录共享一份配置
 
-# 启动网关
+# 启动网关（models.yaml / .env 修改后自动热重载，无需重启）
 npx claude-code-model-router start
 npx claude-code-model-router start --port 9000  # 指定端口
 npx claude-code-model-router start --host 0.0.0.0  # 监听所有网卡（见下方安全提示）
 
 # 查看可用模型
 npx claude-code-model-router models
 
-# 启动 Claude Code（网关模式，使用第三方模型）
+# 切换默认模型（持久化写回 models.yaml，运行中的网关自动生效）
+npx claude-code-model-router use kimi
+
+# 连通性体检：对每个已配 Key 的模型发一条微型真实请求
+# 一次性暴露端点错误、Key 失效、账号未开通模型等问题
+npx claude-code-model-router doctor            # 检查全部
+npx claude-code-model-router doctor seed kimi  # 只检查指定模型
+
+# 查看网关的按模型用量统计（请求数 / 错误数 / tokens）
+npx claude-code-model-router stats
+
+# 启动 Claude Code（网关模式；网关未启动时会自动拉起）
 npx claude-code-model-router claude
 npx claude-code-model-router claude --gateway-port 9000  # 自定义网关端口
 
 # 启动 Claude Code（官方订阅）
 claude
 ```
 
+> **配置发现顺序**：`-c 指定路径` > `./models.yaml` > `./config/models.yaml` > `./.claude-router.yaml` > `~/.ccmr/models.yaml`。`.env` 同理：`./.env` 优先，`~/.ccmr/.env` 兜底（环境变量 `CCMR_HOME` 可改写全局目录位置）。
+
 > **安全提示**：网关默认绑定到 `127.0.0.1`（仅本机可访问）。网关会用你本地配置的各厂商 API Key 代理上游请求，因此任何能访问该端口的人都能消耗你的额度。
 > 若确需通过 `--host 0.0.0.0` 暴露到局域网，请务必设置环境变量 `CCMR_REQUIRED_AUTH_TOKEN`，此时调用方必须在 `x-api-key` 或 `Authorization: Bearer <token>` 中携带该令牌。未设置时绑定非回环地址会打印警告。
 
@@ -214,6 +233,22 @@ MiMo Token Plan 的 Base URL 与购买套餐所在集群绑定。默认 `mimo` 
 
 可以自定义供应商、模型变体、别名等。运行 `init` 命令会生成 `providers -> variants` 结构的模板；旧版平铺 `models` 配置仍然兼容。
 
+网关运行中修改 `models.yaml` 或 `.env` 会**自动热重载**（轮询检测，约 1 秒生效），加模型、换 Key 都不用重启。注意：`gateway.host` / `gateway.port` 变更仍需重启才能重新绑定。
+
+#### 故障降级（fallback）
+
+任意 variant 可声明降级链，上游返回 5xx/429 或连接失败（含超时）时按序切换到备选模型；4xx 客户端错误不会触发降级，流式响应一旦开始输出也不再切换：
+
+```yaml
+providers:
+  deepseek:
+    # ...
+    variants:
+      v4-pro:
+        model_id: deepseek-v4-pro
+        fallback: [kimi-k2.6, glm-5.2]  # 依次降级
+```
+
 ## 使用场景
 
 ### 双模式使用（配置完全隔离）
@@ -340,7 +375,8 @@ npx claude-code-model-router claude
 |------|------|------|
 | `/v1/messages` | POST | Anthropic Messages API |
 | `/v1/models` | GET | 列出可用模型 |
-| `/health` | GET | 健康检查 |
+| `/usage` | GET | 按模型的用量统计（请求数 / 错误数 / tokens，网关重启后清零） |
+| `/health` | GET | 健康检查（含网关版本号） |
 
 ## 开发
 
@@ -365,6 +401,14 @@ ccmr start
 
 ## 故障排除
 
+### 第一步：先跑 doctor
+
+```bash
+npx claude-code-model-router doctor
+```
+
+对每个已配 Key 的模型发一条微型真实请求，直接给出结论：连通（含延迟）/ 上游报错原文（Key 失效、模型未开通、端点错误）/ 未配 Key。绝大多数"模型用不了"的问题一条命令即可定位。
+
 ### 端口被占用
 
 ```bash
@@ -374,9 +418,10 @@ npx claude-code-model-router start --port 9000
 
 ### API Key 错误
 
-1. 检查 .env 文件中的 Key 是否正确
-2. 确认账户有余额
-3. 运行 `npx claude-code-model-router models` 查看状态
+1. 运行 `npx claude-code-model-router doctor` 查看上游的具体报错
+2. 检查 .env 文件中的 Key 是否正确（修改后网关自动热重载，无需重启）
+3. 确认账户有余额
+4. 运行 `npx claude-code-model-router models` 查看 Key 配置状态
 
 ### 网关模式提示地区不支持
 
@@ -388,6 +433,29 @@ DeepSeek Anthropic 兼容接口会忽略 `metadata` 字段，但某些 Claude Co
 
 ## 更新日志
 
+### v1.8.0
+
+**易用性**
+- 新增 `ccmr doctor [models...]`：对每个已配 Key 的模型发一条微型真实请求做连通性体检，一次性暴露端点错误、Key 失效、账号未开通模型等问题
+- 新增 `ccmr use <model>`：持久化切换默认模型（文本级改写 `default_model`，保留注释），运行中的网关自动生效
+- 新增 `ccmr stats` 与 `GET /usage`：按模型统计请求数 / 错误数 / 输入输出 tokens
+- `ccmr claude` 检测网关未启动时**自动拉起**（detached，日志在 `~/.ccmr/gateway.log`）；检测到网关与 CLI 版本不一致时给出警告
+- 配置热重载：网关运行中修改 `models.yaml` / `.env` 约 1 秒内自动生效，无需重启
+- 全局配置目录：`~/.ccmr/models.yaml` 与 `~/.ccmr/.env` 作为兜底（cwd 优先），`ccmr init --global` 一键生成；`CCMR_HOME` 可改写位置
+- 新增模型降级链：variant 级 `fallback: [...]`，上游 5xx/429/连接失败时按序切换备选模型
+
+**风险修复**
+- `ccmr init` 在 git 仓库内自动把 `.env` 加入 `.gitignore`，防止 API Key 被误提交
+- 移除 ESM-only 的 node-fetch（CJS 产物在 Node <22.12 会 `ERR_REQUIRE_ESM` 崩溃），改用 Node 18+ 内置 fetch，`engines: >=18` 恢复真实；同时移除未使用的 chalk 依赖
+- 流式转发增加空闲超时看门狗，上游挂死不再永久悬挂连接
+- 入站鉴权改为常量时间比较（`crypto.timingSafeEqual`）
+- 端口被占用时给出友好错误提示（原为裸堆栈崩溃）
+- 配置热重载遇到损坏的 YAML 时保留旧配置继续运行，不再静默退化为默认配置
+
+**工程化**
+- 引入 vitest 测试体系（69 个测试）：路由解析 / URL 构建 / SSE 转发 / 鉴权 / 热重载 / failover / 用量统计，以及 DEFAULT_CONFIG 与 YAML 模板的一致性测试（当场修复了模板中 `default_variant: 5.2` 未加引号、缺失 `kimi-k2.6` 别名两处漂移）
+- 新增 GitHub Actions CI：Node 18/20/24 矩阵构建 + 测试 + dist 一致性校验
+
 ### v1.7.1
 - 修正 Doubao Seed 接入点：按量付费应走 `https://ark.cn-beijing.volces.com/api/compatible`（而非旧 Coding Plan 的 `/api/coding`），模型 ID 带版本后缀 `doubao-seed-2-1-pro-260628` / `doubao-seed-2-1-turbo-260628`
 - 新增 Agent Plan 订阅入口 `seed-plan`（`https://ark.cn-beijing.volces.com/api/plan`，需 `ARK_PLAN_API_KEY`），与按量付费 `seed` 区分，模式同 `step` / `step-plan`