@minniexcode/codex-switch 0.0.8 → 0.0.10

package/docs/PRD/codex-switch-prd-v0.0.9.md

@@ -0,0 +1,166 @@
+# codex-switch `0.0.9` PRD
+
+## 文档信息
+
+- 状态：Active PRD
+- 产品名：`codex-switch`
+- CLI 命令名：`codexs`
+- 当前基线版本：`0.0.8`
+- 目标版本：`0.0.9`
+- 文档定位：定义 `0.0.8 -> 0.0.9` 的直接需求范围
+- 关联设计文档：`../Design/codex-switch-v0.0.9-design.md`（待产出）
+- 关联上一版设计：[`../Design/codex-switch-v0.0.8-design.md`](../Design/codex-switch-v0.0.8-design.md)
+
+## 一句话定义
+
+`0.0.9` 的目标，是把 GitHub Copilot 的本地 bridge 从“切换时临时可用”收敛成“可按需自动拉起、可手动管理、可诊断恢复”的稳定运行态能力。
+
+## In Scope
+
+- 官方 `@github/copilot-sdk`
+- 本地 Node/TypeScript bridge
+- detached 用户态 bridge 守护进程
+- `switch` 的 bridge 自动启动 / 复用
+- `bridge start`
+- `bridge stop`
+- `bridge status`
+- 单实例 bridge 生命周期管理
+- 5 位数 bridge 端口默认策略
+- 端口冲突自动探测与自动换端口
+- runtime state manifest 的持久化与诊断
+- `status` / `doctor` 的 bridge 生命周期诊断
+- direct provider 回归稳定性
+
+## Out of Scope
+
+- 开机自启动
+- 登录自启动
+- Windows Service / 系统服务注册
+- 多实例 bridge 编排
+- 非官方 SDK
+- 独立 GUI / TUI
+- Responses API、Embeddings、图像/音频接口
+- 持久化 GitHub token 到 `providers.json` / `auth.json`
+
+## 运行形态
+
+- bridge 是由 `codex-switch` 启动和管理的本地后台进程
+- bridge 不是系统服务，也不注册开机或登录自动启动项
+- `switch` 到 Copilot provider 时，bridge 应自动启动或复用
+- 用户也可以通过 `bridge` 命令族手动启动、停止和查看状态
+- `0.0.9` 的“守护进程”语义仅指 detached 用户态后台进程，不等同于 OS service
+
+## 命令面
+
+新增命令：
+
+- `codexs bridge start [provider]`
+- `codexs bridge stop [provider]`
+- `codexs bridge status [provider]`
+
+命令规则：
+
+- `bridge` 命令族只服务于 Copilot runtime-backed provider
+- `provider` 可显式传入；未传入时优先使用当前 active provider
+- 如果未传入且当前 active provider 不是 Copilot provider：
+  - TTY 下允许交互选择目标 Copilot provider
+  - 非交互或 `--json` 下必须明确失败
+- `bridge start` 必须先完成：
+  - provider 解析
+  - runtime 配置校验
+  - SDK probe
+  - Copilot auth state 校验
+  - bridge 启动或复用
+  - healthcheck
+- `bridge stop` 只停止当前受管 bridge 进程并清理 runtime state manifest，不修改 provider registry
+- `bridge status` 返回 runtime state、provider 绑定关系、healthcheck 结果与异常原因
+
+## 生命周期规则
+
+- `add --copilot` 只负责创建 provider 和可选安装 SDK，不负责启动 bridge
+- `switch <copilot-provider>` 仍然是最常见的自动启动入口
+- `bridge start` 与 `switch` 共享同一套 bridge 启动与复用逻辑
+- 同一时刻只允许一个 bridge 实例处于受管运行状态
+- 如果 bridge 已为同一 provider 运行且健康，则 `bridge start` 和 `switch` 都直接复用
+- 如果已有 bridge 为另一 Copilot provider 运行：
+  - `bridge start <new-provider>` 先停止旧实例，再启动新实例
+  - `switch <new-provider>` 也遵守同样的单实例替换规则
+- `bridge stop` 应该是幂等的：bridge 已停止时不报致命错误
+
+## 端口策略
+
+- `--bridge-host` 默认 `127.0.0.1`
+- `--bridge-port` 默认值必须是 5 位数端口
+- Copilot provider 的默认端口不再使用 `4141`
+- 如果 provider 指定端口已被占用：
+  - bridge 启动阶段必须自动检测冲突
+  - 自动选择新的可用 5 位数端口
+  - 自动更新 provider 的 runtime 配置和对应 `baseUrl`
+  - 自动保持 `config.toml` runtime projection 与 provider 配置一致
+- 自动换端口后的新端口必须持久化，避免下一次启动再次撞到旧端口
+- 端口自动切换只允许在 Copilot bridge provider 路径发生，不能影响 direct provider
+
+## 依赖策略
+
+- `@github/copilot-sdk` 继续不进入 core CLI 默认依赖
+- 命中 Copilot 路径时才 probe SDK
+- SDK 自动安装仍然只允许发生在 `add --copilot`
+- `bridge start`、`switch`、`status`、`doctor` 都不能隐式安装 SDK
+- `bridge start` 在 SDK 缺失时必须明确失败，并提示回到 `add --copilot --install-copilot-sdk`
+- SDK 运行前提仍然是用户本机已具备可用的 GitHub Copilot CLI / login 状态，`codex-switch` 不托管这部分登录数据
+
+## 数据边界
+
+- `providers.json` 保存 Copilot provider、bridge host/port、`baseUrl` 与 shared secret
+- `config.toml` 保存 Copilot provider 对应的 runtime `base_url` 与 `env_key`
+- `auth.json` 只保存 Codex 到本地 bridge 的 shared secret
+- runtime state manifest 保存当前 bridge 进程状态、provider 绑定、最后健康检查时间
+- runtime state manifest 不进入 managed backup 事务
+- GitHub/Copilot 上游认证状态仍然只由官方 SDK 管理，不进入受管 registry
+
+## 错误语义
+
+`0.0.9` 继续稳定并收敛以下错误码：
+
+- `COPILOT_SDK_MISSING`
+- `COPILOT_SDK_INSTALL_FAILED`
+- `COPILOT_SDK_INSTALL_REQUIRES_TTY`
+- `COPILOT_SDK_UNSUPPORTED`
+- `COPILOT_AUTH_REQUIRED`
+- `COPILOT_PREMIUM_UNAVAILABLE`
+- `BRIDGE_PORT_CONFLICT`
+- `BRIDGE_START_FAILED`
+- `BRIDGE_HEALTHCHECK_FAILED`
+- `RUNTIME_PROVIDER_INVALID`
+- `PROVIDER_BASE_URL_MISMATCH`
+
+新增要求：
+
+- `bridge start`、`switch`、`bridge status` 对同一类 bridge 失败应尽量映射到同一类错误码
+- 端口冲突在自动恢复成功时不应向上冒泡为致命失败
+- 只有在无法找到可用端口或无法持久化新端口时，才允许保留 `BRIDGE_PORT_CONFLICT` 失败
+
+## 验收标准
+
+- `add --copilot` 可以创建 Copilot provider，并写入 5 位数默认端口
+- `switch` 到 Copilot provider 时完成 `probe -> auth check -> start or reuse bridge -> healthcheck -> config/auth write`
+- `codexs bridge start [provider]` 可以手动启动或复用 bridge
+- `codexs bridge stop [provider]` 可以手动停止当前 bridge，并清理 runtime state
+- `codexs bridge status [provider]` 可以给出 bridge 是否运行、绑定哪个 provider、端口是多少、是否健康
+- 当 bridge 目标端口被占用时，系统会自动切换到新的可用 5 位数端口，并持久化该变更
+- direct provider 不经过 Copilot 特有的 runtime gate
+- `status` / `doctor` 能诊断 SDK 缺失、认证缺失、bridge 不健康、stale runtime state、runtime base_url 漂移
+
+## 测试重点
+
+- `bridge start/stop/status` 参数解析与帮助文案
+- 省略 provider 时的 active provider 解析路径
+- TTY 下的 Copilot provider 交互选择路径
+- 非交互下目标 provider 不明确时的失败路径
+- 单实例 bridge 的复用路径
+- 单实例 bridge 的替换路径
+- `switch` 与 `bridge start` 共享生命周期逻辑的回归
+- 端口占用时的自动换端口与持久化
+- stale runtime state 的诊断与清理
+- `bridge stop` 幂等性
+- direct provider 回归

package/docs/Tests/testing-bridge-v0.0.9.md

@@ -0,0 +1,367 @@
+# `0.0.9` Bridge Automated Testing Guide
+
+This document defines the automated test strategy for the `0.0.9` Copilot bridge release.
+
+## Goal
+
+The release must prove that the managed Copilot bridge can:
+
+- resolve the correct provider target
+- start, stop, and report status through the public CLI surface
+- reuse one healthy instance for the same provider
+- replace an existing managed instance for a different provider
+- recover from preferred-port conflicts using another 5-digit port
+- persist recovered ports into `providers.json` and `config.toml`
+- clean up newly started workers when persistence fails
+- surface stale runtime-state diagnostics through `status` and `doctor`
+
+## Test Layers
+
+Bridge coverage is intentionally split across four layers.
+
+### 1. Runtime Layer
+
+File: `tests/runtime.spec.js`
+
+Use this layer for low-level worker/runtime behaviors:
+
+- bridge HTTP health endpoint behavior
+- worker fallback defaults
+- port conflict recovery
+- single-instance replacement at the runtime-state layer
+- direct `probeCopilotBridgeRuntime()` status behavior
+
+### 2. Workflow Layer
+
+File: `tests/workflows.spec.js`
+
+Use this layer for app use cases and filesystem side effects:
+
+- `startBridge`
+- `stopBridge`
+- `statusBridge`
+- `switchProvider`
+- `runDoctor`
+- persistence and rollback behavior
+
+### 3. Command Layer
+
+File: `tests/commands.spec.js`
+
+Use this layer for registry, argument parsing, and dispatch wiring:
+
+- nested command parsing
+- help text
+- `executeCommand()` dispatch for `bridge start|stop|status`
+- mismatch-guard and unresolved-target error contracts
+
+### 4. Built CLI Layer
+
+File: `tests/cli-e2e.spec.js`
+
+Use this layer only for a small number of user-visible end-to-end checks:
+
+- `bridge start --json`
+- `bridge status --json`
+- `bridge stop --json`
+- stable JSON error envelopes for bridge failures
+
+## Shared Fixtures And Helpers
+
+### Existing helpers
+
+- `tests/helpers.js`
+  - `makeSandboxCopy()`
+  - `makeEmptyCodexDir()`
+  - `runBuiltCli()`
+  - `runJsonCli()`
+- `tests/workflows.spec.js`
+  - `makeFixture()`
+  - `withCodexAvailable()`
+  - `withFakeCopilotSdk()`
+  - `getFreePort()`
+  - `requestJson()`
+- `tests/commands.spec.js`
+  - `makeTempCodexDir()`
+  - `writeBridgeFixture()`
+  - `withFakeCopilotSdk()`
+
+### Environment hooks
+
+Mock bridge-oriented tests should continue to use:
+
+- `CODEX_SWITCH_COPILOT_RUNTIME_DIR`
+- `CODEX_SWITCH_RUNTIME_STATE_DIR`
+
+These keep SDK loading and runtime-state persistence isolated inside temporary directories.
+
+## Required Automated Coverage
+
+### Runtime tests
+
+Required scenarios:
+
+- healthy in-process bridge serves `/healthz`
+- worker fallback port remains `41415`
+- `ensureCopilotBridge()` reuses a healthy worker for the same provider
+- `ensureCopilotBridge()` replaces a different managed provider instance
+- `ensureCopilotBridge()` recovers from preferred-port conflicts
+- `ensureCopilotBridge()` reports startup failures with `BRIDGE_START_FAILED`
+
+Recommended additions when extending runtime coverage:
+
+- `probeCopilotBridgeRuntime()` with missing state
+- `probeCopilotBridgeRuntime()` with stale state and no active Copilot provider
+- `probeCopilotBridgeRuntime()` with base URL mismatch
+- `probeCopilotBridgeRuntime()` with failed healthcheck
+
+### Workflow tests
+
+Required scenarios:
+
+- explicit `bridge start|status|stop`
+- `bridge stop` idempotency without runtime state
+- recovered-port persistence into `providers.json` and `config.toml`
+- cleanup when recovered-port persistence fails for a newly started worker
+- cleanup when recovered-port persistence fails after replacing a previous worker
+- providers rollback when config projection update fails
+- stale runtime-state surfaced by `status` and `doctor` while a direct provider is active
+- `switchProvider()` keeps bridge cleanup semantics on failure
+
+Recommended additions when extending workflow coverage:
+
+- active-provider bridge target resolution without explicit provider argument
+- sole Copilot provider resolution without explicit provider argument
+- explicit mismatch guard for `bridge stop`
+- explicit mismatch guard for `bridge status`
+- `BRIDGE_TARGET_UNRESOLVED` for non-interactive multi-provider ambiguity
+
+### Command tests
+
+Required scenarios:
+
+- nested `bridge` command parsing
+- bridge help text rendering
+- `executeCommand()` dispatches `bridge start|status|stop`
+
+Recommended additions when extending command coverage:
+
+- `executeCommand()` mismatch guard for `bridge stop`
+- `executeCommand()` mismatch guard for `bridge status`
+- `executeCommand()` unresolved target failures
+
+### Built CLI tests
+
+Required scenarios:
+
+- `bridge start|status|stop` through the built CLI entrypoint
+- read-command JSON envelope remains stable while `doctor` now may report multiple issue codes
+
+Recommended additions when extending CLI coverage:
+
+- `bridge status` stale runtime-state envelope
+- `bridge start` unresolved-target envelope
+
+## Fast Execution Order
+
+When time is limited, implement and verify tests in this order:
+
+1. `tests/commands.spec.js`
+2. `tests/workflows.spec.js`
+3. `tests/cli-e2e.spec.js`
+4. `tests/runtime.spec.js`
+
+This order catches the highest-value regressions first:
+
+- wiring regressions
+- persistence/cleanup regressions
+- user-visible CLI regressions
+- low-level runtime regressions
+
+## Running The Suite
+
+Build and run all tests:
+
+```bash
+npm test
+```
+
+This runs:
+
+```bash
+npm run build
+node tests/run-tests.js
+```
+
+## Release Gate For `0.0.9`
+
+Treat bridge automation as release-ready only when all of the following are true:
+
+- `commands`, `runtime`, `workflows`, and `cli-e2e` all pass
+- `bridge start|stop|status` are covered at both app and CLI layers
+- single-instance reuse and replacement are covered
+- recovered-port persistence and cleanup failure paths are covered
+- stale runtime-state diagnostics are covered in both `status` and `doctor`
+
+## Remaining Manual Smoke Checks
+
+Automated coverage does not replace a final real-environment smoke pass.
+
+Before shipping, still run a logged-in Copilot smoke check for:
+
+- real `bridge start`
+- real `bridge status`
+- one real request through `/v1/chat/completions`
+- real `bridge stop`
+- real `switch <copilot-provider>` reuse/replacement behavior
+
+## Minimal Manual Smoke Checklist
+
+Use this short checklist after the automated suite passes and after you have logged into Copilot in the real target environment.
+
+### Preconditions
+
+- run from the repository root
+- use the real Codex directory you intend to validate
+- ensure the target Copilot provider already exists in `providers.json`
+- ensure the optional Copilot SDK is installed
+- ensure you are logged into Copilot before starting the live smoke pass
+
+Suggested placeholder values:
+
+- `<CODEX_DIR>`: your real Codex directory
+- `<COPILOT_PROVIDER>`: the Copilot-backed provider name you want to validate
+
+### 1. Confirm the automated gate is still green
+
+```bash
+npm test
+```
+
+Expected result:
+
+- build succeeds
+- all automated suites pass
+
+### 2. Start the real managed bridge
+
+```bash
+node dist/cli.js bridge start <COPILOT_PROVIDER> --json --codex-dir <CODEX_DIR>
+```
+
+Expected result:
+
+- command exits successfully
+- JSON payload reports the requested provider
+- payload includes `host`, `port`, and `baseUrl`
+- `reused` is `false` on the first successful start unless a healthy matching bridge is already running
+
+### 3. Confirm bridge status
+
+```bash
+node dist/cli.js bridge status <COPILOT_PROVIDER> --json --codex-dir <CODEX_DIR>
+```
+
+Expected result:
+
+- command exits successfully
+- `health.ok` is `true`
+- `active` is `true`
+- `matches` is `true`
+
+### 4. Send one real request through the bridge
+
+Use the `baseUrl` and API key from the selected provider record. Replace `<BRIDGE_BASE_URL>` and `<BRIDGE_API_KEY>` with real values from your environment.
+
+```bash
+curl -sS <BRIDGE_BASE_URL>/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <BRIDGE_API_KEY>" \
+  -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with the single word OK.\"}]}"
+```
+
+Expected result:
+
+- HTTP request succeeds
+- response contains a completion payload
+- model output proves the request reached the live bridge successfully
+
+If your shell or environment prefers the OpenAI-style path, validate the same request against:
+
+```text
+<BRIDGE_BASE_URL>/chat/completions
+```
+
+### 5. Verify same-provider reuse
+
+Run the start command again:
+
+```bash
+node dist/cli.js bridge start <COPILOT_PROVIDER> --json --codex-dir <CODEX_DIR>
+```
+
+Expected result:
+
+- command exits successfully
+- `reused` is `true`
+- reported `port` remains stable
+
+### 6. Verify switch reuse or replacement behavior
+
+Run a real switch into the Copilot provider:
+
+```bash
+node dist/cli.js switch <COPILOT_PROVIDER> --json --codex-dir <CODEX_DIR>
+```
+
+Expected result:
+
+- command exits successfully
+- provider/profile switch succeeds
+- if the same healthy bridge is already running, it is reused
+- if another managed bridge instance was active, it is replaced cleanly
+
+If you have a second Copilot provider available, also validate explicit replacement:
+
+```bash
+node dist/cli.js bridge start <SECOND_COPILOT_PROVIDER> --json --codex-dir <CODEX_DIR>
+```
+
+Expected result:
+
+- previous managed instance is replaced
+- status for the new provider is healthy
+- no stale runtime-state mismatch is left behind
+
+### 7. Stop the managed bridge
+
+```bash
+node dist/cli.js bridge stop <COPILOT_PROVIDER> --json --codex-dir <CODEX_DIR>
+```
+
+Expected result:
+
+- command exits successfully
+- payload reports `stopped: true`
+
+### 8. Confirm shutdown state
+
+```bash
+node dist/cli.js bridge status <COPILOT_PROVIDER> --json --codex-dir <CODEX_DIR>
+```
+
+Expected result:
+
+- command may either report inactive bridge health or a missing runtime state, depending on the exact environment state
+- it must not falsely report a healthy active managed bridge after stop
+
+### Manual Pass Criteria
+
+Treat the live smoke pass as complete only when all of the following are true:
+
+- `bridge start` succeeds in a logged-in real environment
+- `bridge status` reports a healthy active bridge
+- one real request succeeds through the bridge
+- repeated `bridge start` reuses the same healthy instance
+- `switch <copilot-provider>` preserves expected reuse/replacement behavior
+- `bridge stop` shuts the managed instance down cleanly

package/docs/cli-usage.md

@@ -1,6 +1,6 @@
 # codex-switch CLI Usage
 
-本文档详细介绍 `codex-switch` 在 `0.0.4` 版本中的命令、参数、交互规则和典型使用方式。
+本文档详细介绍 `codex-switch` 在 `0.0.10` 版本中的命令、参数、交互规则和典型使用方式。
 
 可执行命令名：
 
@@ -260,9 +260,9 @@ codexs migrate --merge --codex-dir ./.tmp-codex
 行为说明：
 
 - 读取 `config.toml` 中已有 profile
-- 仅 adopt 已具备 `model`、`model_provider` 且能解析到匹配 `model_providers.*.base_url` 和 `env_key` 的 unmanaged profile
+- 仅 adopt 已具备 `model`、`model_provider` 且能解析到匹配 `model_providers.*.base_url` 的 unmanaged profile
 - 收集每个 profile 对应的 provider 记录
-- 保持现有受管备份、锁、`auth.json` mirror 和 post-run `doctor` 流程
+- 保持现有受管备份、锁和 post-run `doctor` 流程，不重写 `auth.json`
 
 交互模式：
 
@@ -291,14 +291,15 @@ codexs setup
 
 ### 5.4 `add`
 
-新增一个 provider。
+新增一个 provider。`add` 当前同时支持 direct provider 和 Copilot bridge provider 两条路径。
 
 ```bash
 codexs add <provider> --profile <name> --api-key <key> [--base-url <url>] [--note <text>] [--tag <tag> ...]
-codexs add [--profile <name>] [--api-key <key>] [--base-url <url>] [--note <text>] [--tag <tag> ...]
+codexs add <provider> --copilot --profile <name> [--bridge-host <host>] [--bridge-port <port>] [--bridge-api-key <secret>] [--install-copilot-sdk]
+codexs add
 ```
 
-示例：
+direct provider 示例：
 
 ```bash
 codexs add packycode --profile packycode --api-key sk-xxx
@@ -306,7 +307,14 @@ codexs add packycode --profile packycode --api-key sk-xxx --tag paid --tag daily
 codexs add
 ```
 
-字段说明：
+Copilot provider 示例：
+
+```bash
+codexs add copilot-main --copilot --profile copilot-main --install-copilot-sdk
+codexs add copilot-main --copilot --profile copilot-main --bridge-port 41415 --bridge-api-key local-secret
+```
+
+direct provider 字段说明：
 
 - `provider`：provider 名称，也是后续 `switch/show/edit/remove` 的标识
 - `--profile`：写入到 `config.toml` 的 profile 名称
@@ -315,16 +323,31 @@ codexs add
 - `--note`：备注
 - `--tag`：标签，可重复传多次
 
+Copilot provider 字段说明：
+
+- `--copilot`：切换到 Copilot provider 模式
+- `--profile`：必填
+- `--api-key`：在 `--copilot` 下禁止使用；Copilot 不接收 direct provider API key
+- `--bridge-host`：本地 bridge host，默认 `127.0.0.1`
+- `--bridge-port`：本地 bridge port，默认 `41415`
+- `--bridge-api-key`：本地 bridge shared secret；留空时自动生成
+- `--install-copilot-sdk`：允许在首次接入时安装可选 Copilot SDK runtime
+
 交互模式：
 
-- 如果缺少 `provider`、`profile`、`apiKey`，会在 TTY 中补问
-- profile 选择会优先复用现有 `config.toml` profile
-- API key 的隐藏输入会做二次确认
-- tag 仅支持预设选项多选
+- direct provider 缺少 `provider`、`profile`、`apiKey` 时，会在 TTY 中补问
+- direct provider 的 API key 隐藏输入会做二次确认
+- Copilot provider 会先做固定 preflight：检查 SDK、必要时立即安装、检查 GitHub Copilot 登录态、必要时执行官方 `copilot login`，全部通过后才进入专用输入流
+- Copilot provider 的专用输入流只采集 provider/profile/model、note/tags 和 bridge 参数
+- Copilot provider 不会提示 `API key`、`Confirm API key` 或输出 `API key is required.`
+- 若官方 `copilot login` 无法启动，会回退为人工提示：运行 `copilot login`，完成 GitHub 官方 device/browser 流程后执行一次明确 recheck
+- `add --copilot --json` 永远不会启动登录流程；若 auth 未就绪，直接返回 `COPILOT_AUTH_REQUIRED`，并提示手动运行 `copilot login`
 
 非交互模式：
 
-- 必须显式传入所有必填字段
+- direct provider 必须显式传入所有必填字段
+- `add --copilot` 必须显式传入 `<provider>` 和 `--profile`
+- `add --copilot --json` 不会进入任何 prompt；若 SDK 缺失且未传 `--install-copilot-sdk`，直接失败；若 auth 未就绪，也直接返回 `COPILOT_AUTH_REQUIRED`
 
 ### 5.5 `edit`
 
@@ -377,8 +400,9 @@ codexs switch
 
 - 根据 `providers.json` 找到目标 provider
 - 更新相关运行态配置
-- 重写当前 active provider 对应的 `auth.json` mirror
-- 会先备份 `config.toml` 和 `auth.json`
+- direct provider 会切换当前 active profile，并将 `auth.json` 重写为 `auth_mode = "apikey"` 和 `OPENAI_API_KEY = <provider.apiKey>`
+- Copilot bridge provider 不写 `OPENAI_API_KEY`，而是维护本地 bridge 路由
+- 备份 `config.toml`，并在 direct provider 切换时一并备份 `auth.json`
 
 交互模式：
 

package/docs/codex-switch-product-overview.md

@@ -150,7 +150,7 @@ MVP 的能力范围主要包括：
 
 - `config.toml` 是主配置文件
 - `providers.json` 是 `codex-switch` 自身维护的 provider 清单
-- `auth.json` 在存在时会被纳入备份与回滚考虑
+- `auth.json` 是当前 active direct provider 的认证投影文件；切换 direct provider 时会刷新 `OPENAI_API_KEY`
 - `backups/` 用于保存历史备份
 
 产品不会要求用户先理解全部内部实现，只暴露统一的命令接口。
@@ -167,7 +167,7 @@ MVP 的能力范围主要包括：
 
 ### 场景 3：切换到目标 provider
 
-用户执行切换命令后，工具会完成校验、备份、修改和必要的登录动作。
+用户执行切换命令后，工具会完成校验、备份、修改运行态配置，并在 direct provider 场景下同步 `auth.json`。
 
 ### 场景 4：出现异常时恢复
 

package/docs/codex-switch-technical-architecture.md

@@ -98,7 +98,7 @@
 - `Low Coupling`
   - 参数解析、业务编排、文件访问、错误模型彼此解耦
 - `Split State Model`
-  - `providers.json` 是管理态事实源，`config.toml` / `auth.json` 是运行态镜像
+- `providers.json` 是管理态事实源，`config.toml` 是运行态路由文件，`auth.json` 是 direct provider 的认证投影
 - `Lightweight Transactions`
   - 单次写操作要有锁、备份、回滚边界
 
@@ -125,7 +125,8 @@ Infrastructure 层
 当前实现还明确区分三类状态对象：
 
 - 管理态单一事实源：`providers.json`
-- 运行态镜像：`config.toml`、`auth.json`
+- 运行态路由：`config.toml`
+- 当前 active direct provider 的认证投影：`auth.json`
 - 回滚态：`backups/latest.json` 和对应 manifest
 
 这意味着未来即使引入 GUI / MCP / HTTP 适配层，核心同步目标仍然是 runtime files，而不是把 runtime files 本身当成长期管理数据库。
@@ -555,13 +556,13 @@ scripts/
 - 深度解析 profile 内部更多字段
 - 管理 base URL 或模型等 profile 内容
 
-它在当前架构里属于运行态镜像，只承担“当前活跃 profile 落地”的职责。
+它在当前架构里是 direct provider 的认证投影文件，不承担 provider 选择职责，也不作为 provider registry 的事实源。
 
 ### 5.3 `auth.json`
 
 当前实现不直接建模其内部字段，但它有明确架构角色：
 
-- 属于运行态镜像
+- 属于 direct provider 的认证投影
 - 在存在时纳入备份与回滚
 - 不是 provider registry 的事实源
 
@@ -622,7 +623,7 @@ scripts/
 6. 校验 provider 对应的 `profile` 在配置中存在
 7. 创建备份：
    - `config.toml`
-   - `auth.json`（如果存在）
+- `auth.json` 仅在历史备份清单已包含时由 rollback 兼容恢复
 8. 更新顶层 `profile`
 9. 如果未传 `--no-login`，执行 `codex login --with-api-key`
 10. 成功后把这次备份记录为 `latest.json`