@minniexcode/codex-switch 0.0.12 → 0.1.1

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

@@ -1,205 +1,217 @@
-# codex-switch `0.1.0` Release Gate PRD
-
-## 文档信息
-
-- 状态：Release Gate Draft
-- 产品名：`codex-switch`
-- CLI 命令名：`codexs`
-- 当前预发布基线：`0.0.12` beta
-- 目标版本：`0.1.0`
-- 文档定位：定义 `codex-switch` 何时可以从 `0.0.x` 进入第一个正式稳定发布版本
-- 关联 beta PRD：[`./codex-switch-prd-v0.0.12.md`](./codex-switch-prd-v0.0.12.md)
-- 关联长期演进稿：[`./codex-switch-prd-v0.0.5-to-v0.1.0.md`](./codex-switch-prd-v0.0.5-to-v0.1.0.md)
-
-## 一句话定义
-
-`0.1.0` 不是“功能再多一点”的版本，而是 `codex-switch` 第一条可正式对外承诺的稳定产品线：命令入口稳定、输出契约稳定、主工作流清晰、恢复与诊断可信、文档与包内容一致。
-
-## 发布语义
-
-一旦进入 `0.1.0`，这个版本就不再只是“作者自己知道怎么用”的工具，而需要满足：
-
-- 新用户看 README 与 help 就能走通主路径
-- 自动化调用方可以信赖 `--json` 的稳定契约
-- direct provider 和 Copilot provider 都有明确、可解释、可恢复的工作流
-- 文档、包内容、help、测试和实际行为是同一套事实
-
-`0.1.0` 不是自动升级目标。只有当 release gate 满足时，才允许发布。
-
-## `0.1.0` 必须稳定的内容
-
-### 1. CLI 命令面
-
-以下命令面在 `0.1.0` 时视为稳定：
-
-- `init`
-- `login`
-- `list`
-- `show`
-- `current`
-- `status`
-- `doctor`
-- `config show`
-- `config list-profiles`
-- `add`
-- `edit`
-- `switch`
-- `remove`
-- `import`
-- `export`
-- `bridge start`
-- `bridge status`
-- `bridge stop`
-- `backups list`
-- `rollback`
-
-说明：
-
-- `setup` 可以继续保留为 deprecated entry
-- `migrate` 可以继续保留，但其“高级 adopt 工具”定位必须明确
-
-### 2. JSON Envelope
-
-`--json` 顶层 envelope 在 `0.1.0` 前必须冻结为：
-
-```json
-{
-  "ok": true,
-  "command": "list",
-  "data": {},
-  "warnings": [],
-  "error": null
-}
-```
-
-要求：
-
-- 顶层字段不改名
-- 顶层 shape 不重排
-- 新信息只允许追加到 `data`、`warnings` 或 `error.details`
-
-### 3. 双路径模型
-
-`0.1.0` 前必须把以下边界视为正式产品 contract：
-
-- tool home：
-  - `codex-switch.json`
-  - `providers.json`
-  - `backups/`
-  - `runtime/`
-  - `runtimes/`
-- target Codex runtime：
-  - `config.toml`
-  - `auth.json`
-
-其中：
-
-- `providers.json` 是管理态 SSOT
-- `config.toml` 是受管 runtime routing 文件
-- `auth.json` 是受管 auth projection 文件
-
-### 4. 主工作流
-
-#### Direct Provider
-
-正式推荐路径必须清晰稳定：
-
-```bash
-codexs init
-codexs add <provider> --profile <name> --api-key <key>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-#### Copilot Provider
-
-正式推荐路径必须清晰稳定：
-
-```bash
-codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <name>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-#### `migrate`
-
-`migrate` 在 `0.1.0` 可以保留，但必须满足：
-
-- 产品定位明确为高级 adopt helper
-- 不与 fresh install 主路径混淆
-- 文档不把它写成所有用户都应先执行的默认第一步
-
-## Release Gate
-
-只有以下条件全部满足，才允许发布 `0.1.0`：
-
-### A. 工作流可信
-
-- direct provider 主路径可在 fresh tool home 下稳定走通
-- Copilot 主路径可在 fresh tool home 下稳定走通
-- `switch` 成功语义仍然等于 config + auth 投影都正确
-- `rollback` 对受管写操作仍然可信
-
-### B. 输出可信
-
-- `--json` 读命令输出稳定
-- 非交互模式不会意外 prompt
-- 错误码和 issue code 对常见失败场景足够稳定
-- `status` 与 `doctor` 输出能解释下一步修复动作
-
-### C. 文档可信
-
-- README、README.CN、README.AI、CLI usage、product overview、PRD、changelog 与实际行为一致
-- 不再残留旧 `~/.codex/providers.json` / `backups/` 叙述
-- 主路径在所有面向用户的文档中一致
-
-### D. 包内容可信
-
-- `npm pack --dry-run` 结果合理
-- tarball 中包含正确的 README、LICENSE、docs、dist
-- `codexs --help`、`codexs --version`、安装指引与 npm 包元数据一致
-
-### E. 结构可信
-
-- 不再保留明显误导性的历史目录语义
-- 关键稳定模块有足够 JSDoc 和边界说明
-- 新问题不再需要反复回到超大入口文件做修补
-
-## 明确不要求 `0.1.0` 完成的内容
-
-以下内容不是 `0.1.0` 的发布前置条件：
-
-- 新 upstream
-- GUI / TUI
-- daemon / background supervisor
-- plugin system
-- 多账号平台
-- 自动迁移旧状态
-- `migrate` 的完整非交互产品化
-- 通用 `config.toml` 编辑器
-
-## 若 Release Gate 未通过
-
-如果以下任一问题仍明显存在，则不应强行发布 `0.1.0`：
-
-- 文档和行为仍有明显漂移
-- `migrate` 与主路径仍然混淆
-- Copilot 路径仍需要过多背景知识才能理解
-- 回滚与诊断场景仍存在不稳定或不可解释行为
-- 包内容、安装体验或帮助页仍像开发中工具
-
-此时应继续发布：
-
-- `0.0.13`
-- `0.0.14`
-- 其他后续 beta / rc 版本
-
-而不是为了版本号好看提前进入 `0.1.0`。
-
-## 结论
-
-`0.1.0` 的意义，不在于“项目终于到 1.0 之前先过一个数字门槛”，而在于 `codex-switch` 首次具备了可以向外明确承诺的稳定产品边界。只有当工作流、输出、恢复、文档和包发布面都同时稳定时，这个版本号才成立。
+# codex-switch `0.1.0` Release Gate PRD
+
+## 文档信息
+
+- 状态：Release Gate
+- 产品名：`codex-switch`
+- CLI 命令名：`codexs`
+- 当前稳定基线：`0.0.12`
+- 目标版本：`0.1.0`
+- 文档定位：定义 `codex-switch` 第一次稳定发布前必须满足的门槛
+- 关联 beta PRD：[`./codex-switch-prd-v0.0.12.md`](./codex-switch-prd-v0.0.12.md)
+- 关联实现约束设计：[`../Design/codex-switch-v0.1.0-design.md`](../Design/codex-switch-v0.1.0-design.md)
+- 关联长期演进稿：[`./codex-switch-prd-v0.0.5-to-v0.1.0.md`](./codex-switch-prd-v0.0.5-to-v0.1.0.md)
+
+## 1. 定位
+
+`0.1.0` 是 `codex-switch` 的第一条稳定发布线，不是继续扩 feature surface 的版本，也不是把 `0.0.12` 再包装一次。
+
+这个版本的判断标准只有一个：当前仓库已经足够稳定，能把命令面、输出契约、主工作流、诊断语义和文档事实对外固定下来，并且不需要再依赖开发期解释来“补全理解”。
+
+## 2. 当前阻塞项
+
+以下问题仍然阻止 `0.1.0` 成为真正可发布的稳定版本：
+
+1. `tests/` 被忽略，导致测试无法被版本化和审阅。
+2. README 里仍有失效的 `docs/Tests/testing.md` 链接，用户会直接遇到死链。
+3. 版本叙事仍停留在 `0.0.12`，对外材料没有把 `0.1.0` 讲成稳定发布线。
+4. 发布故事和实现状态还没有完全对齐，尤其是主工作流、`migrate` 定位和 `setup` 定位。
+
+这些阻塞项必须先被收口，`0.1.0` 才能成立。
+
+## 3. `0.1.0` 的稳定合同
+
+`0.1.0` 必须把以下内容视为稳定合同，不再当作可随意重写的草案。
+
+### 3.1 命令面
+
+稳定命令面包括：
+
+- `init`
+- `login`
+- `list`
+- `show`
+- `current`
+- `status`
+- `doctor`
+- `config show`
+- `config list-profiles`
+- `add`
+- `edit`
+- `switch`
+- `remove`
+- `import`
+- `export`
+- `bridge start`
+- `bridge status`
+- `bridge stop`
+- `backups list`
+- `rollback`
+
+其中：
+
+- `migrate` 只能是高级 adopt helper。
+- `setup` 只能是 deprecated entry。
+
+### 3.2 `--json` envelope
+
+`--json` 的顶层 envelope 必须保持不变：
+
+```json
+{
+  "ok": true,
+  "command": "list",
+  "data": {},
+  "warnings": [],
+  "error": null
+}
+```
+
+约束如下：
+
+- 顶层字段名不变。
+- 顶层字段顺序和 shape 不变。
+- 新信息只能继续追加到 `data`、`warnings` 或 `error.details`。
+
+### 3.3 dual-path model
+
+`0.1.0` 必须把以下分层固定为正式合同：
+
+- tool home：
+  - `codex-switch.json`
+  - `providers.json`
+  - `backups/`
+  - `runtime/`
+  - `runtimes/`
+- target Codex runtime：
+  - `config.toml`
+  - `auth.json`
+
+含义必须稳定：
+
+- `providers.json` 是管理态 SSOT。
+- `config.toml` 是受管 runtime routing 文件。
+- `auth.json` 是受管 auth projection 文件。
+
+### 3.4 主工作流
+
+Direct provider 主路径：
+
+```bash
+codexs init
+codexs add <provider> --profile <name> --api-key <key>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+Copilot provider 主路径：
+
+```bash
+codexs init
+codexs login copilot
+codexs add <provider> --copilot --profile <name>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+`migrate` 的定位必须明确为：
+
+- 面向已有 runtime state 的高级 adopt helper。
+- 不应与 fresh install 主路径混淆。
+- 不应被写成所有新用户都应先执行的默认步骤。
+
+## 4. Release Gate
+
+只有以下条件全部满足，才允许发布 `0.1.0`。
+
+### 4.1 工作流
+
+- fresh tool home 下 direct provider 主路径可稳定走通。
+- fresh tool home 下 Copilot 主路径可稳定走通。
+- `switch` 的成功语义仍然等于 config 和 auth projection 都正确。
+- `rollback` 对受管写操作仍然可信。
+
+### 4.2 输出与语义
+
+- `--json` 读命令输出稳定。
+- 非交互模式不会意外触发 prompt。
+- 错误码和 issue code 对常见失败场景足够稳定。
+- `status` 与 `doctor` 能清楚说明下一步修复动作。
+- `list`、`status`、`doctor` 的人类可读输出和交互提示一致。
+
+### 4.3 文档
+
+- README、README.CN、README.AI、CLI usage、product overview、PRD、design 和 changelog 与实际行为一致。
+- `docs/Tests/testing.md` 不能继续停留在忽略状态，测试回归必须落仓库并可版本化。
+- 主路径在所有面向用户的文档中必须一致。
+- `0.1.0` 的定位必须压过旧的 `0.0.12` 叙事。
+
+### 4.4 包内容
+
+- `npm pack --dry-run` 结果合理。
+- tarball 中包含正确的 README、LICENSE、docs、dist。
+- `codexs --help`、`codexs --version`、安装指引与 npm 包元数据一致。
+
+### 4.5 结构
+
+- 不再保留明显误导性的历史目录语义。
+- 稳定模块的边界说明足够清楚。
+- 新问题不再需要反复回到超大入口文件修补。
+
+## 5. 可执行验证清单
+
+`0.1.0` 的发布前验证必须至少覆盖以下项目：
+
+```bash
+npm run build
+npm test
+npx tsc --noEmit
+npm pack --dry-run
+node dist/cli.js --help
+node dist/cli.js --version
+```
+
+同时必须做以下行为验证：
+
+- fresh direct provider flow。
+- fresh Copilot provider flow。
+- `list/status/doctor` 语义检查。
+- `--json` 输出检查。
+- `migrate` 作为高级 adopt helper 的检查。
+- `setup` 作为 deprecated entry 的检查。
+
+## 6. 明确不在范围内
+
+`0.1.0` 不要求完成以下内容：
+
+- 新 upstream。
+- GUI / TUI。
+- daemon。
+- plugin system。
+- auto migration。
+- 兼容层。
+- dual-read / dual-write。
+- `migrate` 的完整非交互产品化。
+- 旧状态的自动升级保留逻辑。
+
+## 7. 若 Gate 未通过
+
+如果任何阻塞项仍然存在，就不要强行发布 `0.1.0`。
+
+此时应继续发布 beta 或 rc 版本，而不是为了版本号好看提前进入稳定线。
+
+## 8. 结论
+
+`0.1.0` 的本质不是“功能更多”，而是“承诺更稳”。当命令面、输出契约、主工作流、诊断语义、包内容和文档事实完全一致时，这个版本号才成立。

package/docs/Reference/codex-config-reference.md

@@ -137,6 +137,12 @@ model_reasoning_effort = "high"
 approval_policy = "never"
 ```
 
+Important `codex-switch` note:
+
+- official Codex still supports profiles
+- `codex-switch` `0.1.1` does not treat top-level `profile` as the recommended managed runtime selector
+- in `codex-switch`, legacy `profile` and `[profiles.*]` are mainly inspect-and-adopt inputs for `migrate`, `doctor`, and `config` inspection flows
+
 ## 4. `config.toml` by topic
 
 ### 4.1 Model, reasoning, and response style
@@ -194,6 +200,8 @@ Core keys:
 - `model_providers.<id>.env_http_headers`
 - `model_providers.<id>.query_params`
 - `model_providers.<id>.request_max_retries`
+- `model_providers.<id>.wire_api`
+- `model_providers.<id>.requires_openai_auth`
 
 Authentication options for custom providers include:
 
@@ -214,6 +222,22 @@ Related Bedrock keys:
 - `model_providers.amazon-bedrock.aws.profile`
 - `model_providers.amazon-bedrock.aws.region`
 
+#### `codex-switch` 0.1.1 managed projection
+
+When `codex-switch` manages a direct OpenAI-compatible route for Codex `0.134.0+`, it intentionally projects a narrower runtime shape than the full official provider schema:
+
+- top-level `model` is the active model selector
+- top-level `model_provider` is the active route selector
+- projected `[model_providers.<id>]` keeps `base_url`
+- projected `[model_providers.<id>]` fixes `wire_api = "responses"`
+- projected `[model_providers.<id>]` fixes `requires_openai_auth = true`
+- projected runtime config does not keep `env_key`
+- projected runtime config does not keep `env_key_instructions`
+
+Authentication is projected through `auth.json` with `OPENAI_API_KEY`, not through `env_key` in the managed runtime config.
+
+That is a `codex-switch` product decision, not a limitation of Codex itself. If you hand-write or independently manage Codex config, `env_key` remains a valid official mechanism.
+
 ### 4.3.1 `openai_base_url` vs custom providers
 
 If you only want to point the built-in OpenAI provider to a proxy, router, or residency-specific endpoint, use:
@@ -539,6 +563,23 @@ env_key = "OPENAI_API_KEY"
 http_headers = { "X-Team" = "platform" }
 ```
 
+This is an official Codex-style custom provider example.
+
+If you are using `codex-switch` managed direct-provider projection instead, the runtime projection is intentionally narrower:
+
+```toml
+model = "gpt-5.4"
+model_provider = "proxy"
+
+[model_providers.proxy]
+name = "proxy"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+In that managed projection, `OPENAI_API_KEY` is expected in `auth.json` rather than through `env_key` in `config.toml`.
+
 ### 6.4 Locked-down shell environment
 
 ```toml

package/docs/Reference/codex-config-reference.zh-CN.md

@@ -149,6 +149,12 @@ model_reasoning_effort = "high"
 approval_policy = "never"
 ```
 
+对 `codex-switch` 0.1.1 的补充说明：
+
+- 官方 Codex 仍然支持 profiles
+- `codex-switch` 不再把顶层 `profile` 视为推荐的受管 runtime selector
+- 在 `codex-switch` 里，legacy `profile` 和 `[profiles.*]` 主要用于 `migrate`、`doctor` 和 `config` 检视的 adopt / inspect 场景
+
 ## 4. `config.toml` 主题整理
 
 ### 4.1 模型、推理强度与输出风格
@@ -206,6 +212,8 @@ Codex 把“当前使用哪个 provider”和“provider 怎么定义”拆开
 - `model_providers.<id>.env_http_headers`
 - `model_providers.<id>.query_params`
 - `model_providers.<id>.request_max_retries`
+- `model_providers.<id>.wire_api`
+- `model_providers.<id>.requires_openai_auth`
 
 自定义 provider 的认证方式包括：
 
@@ -229,6 +237,22 @@ Bedrock 相关 key：
 - `model_providers.amazon-bedrock.aws.profile`
 - `model_providers.amazon-bedrock.aws.region`
 
+#### `codex-switch` 0.1.1 的受管投影
+
+当 `codex-switch` 为 Codex `0.134.0+` 管理一个 direct OpenAI-compatible route 时，它会有意把运行态投影限制在一组更窄的字段上：
+
+- 顶层 `model` 是活动模型选择器
+- 顶层 `model_provider` 是活动路由选择器
+- 投影后的 `[model_providers.<id>]` 保留 `base_url`
+- 投影后的 `[model_providers.<id>]` 固定写 `wire_api = "responses"`
+- 投影后的 `[model_providers.<id>]` 固定写 `requires_openai_auth = true`
+- 受管运行态投影不会保留 `env_key`
+- 受管运行态投影不会保留 `env_key_instructions`
+
+认证信息会通过 `auth.json` 里的 `OPENAI_API_KEY` 投影，而不是通过运行态 `config.toml` 中的 `env_key`。
+
+这属于 `codex-switch` 的产品约束，不是 Codex 官方能力限制。如果你是手工维护或独立维护 Codex config，`env_key` 仍然是官方支持的方式。
+
 ### 4.3.1 `openai_base_url` 和自定义 provider 的区别
 
 如果你只是想把内置 `openai` provider 指向公司网关、路由层或者某个数据驻留 endpoint，官方建议直接用：
@@ -568,6 +592,23 @@ env_key = "OPENAI_API_KEY"
 http_headers = { "X-Team" = "platform" }
 ```
 
+这段是官方 Codex 风格的自定义 provider 示例。
+
+如果你走的是 `codex-switch` 的受管 direct-provider 投影，运行态会被有意收窄为：
+
+```toml
+model = "gpt-5.4"
+model_provider = "proxy"
+
+[model_providers.proxy]
+name = "proxy"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+在这种受管投影下，`OPENAI_API_KEY` 预期写在 `auth.json`，而不是通过 `config.toml` 里的 `env_key` 暴露。
+
 ### 6.4 最小暴露的 shell 环境策略
 
 ```toml

package/docs/Tests/testing.md

@@ -1,78 +1,31 @@
-# Testing Guide
-
-Version under test: `0.0.12`
-
-这份文档同时是测试说明和 beta release checklist。
-
-## Active Suites
-
-- `tests/commands.spec.js`: argument parsing, help rendering, and command registry contract
-- `tests/cli-e2e.spec.js`: built CLI help/version plus human-readable and JSON output behavior
-- `tests/interaction.spec.js`: prompt boundaries
-- `tests/runtime.spec.js`: runtime probing behavior
-- `tests/workflows.spec.js`: file-backed mutation and rollback behavior
-
-## Required Commands
-
-```bash
-npm run build
-npm test
-npx tsc --noEmit
-npm pack --dry-run
-```
-
-## Release Checklist
-
-Read checks:
-
-- built CLI `--help`
-- built CLI `--version`
-- `list --json`
-- `status --json`
-- `doctor --json`
-
-Primary workflow checks:
-
-- fresh tool home direct path
-- fresh tool home Copilot path
-- read commands in `--json`
-- write commands in sandbox
-
-Specific `0.0.12` checks:
-
-- top-level help shows direct primary workflow before `migrate`
-- `migrate` is clearly presented as advanced adopt
-- `setup` remains deprecation-only
-- human-readable `init` output shows tool home, tool config, and providers registry
-- human-readable `status` output shows tool home and target runtime
-- human-readable `doctor` output is repair-oriented
-- `--version` matches `package.json.version`
-
-## Test Limits
-
-- `login copilot` depends on SDK install, official CLI invocation, and auth recheck. Automation should distinguish mocked coverage from real-environment validation.
-- `migrate` remains intentionally interactive for adopt detail collection. Non-interactive tests should verify the current failure contract rather than force a fake full automation path.
-
-## Reporting Template
-
-```text
-Version under test: 0.0.12
-Build: PASS/FAIL
-Suite results:
-- commands: PASS/FAIL
-- cli-e2e: PASS/FAIL
-- interaction: PASS/FAIL
-- runtime: PASS/FAIL
-- workflows: PASS/FAIL
-
-Release checks:
-- help/version: PASS/FAIL
-- direct path: PASS/FAIL
-- copilot path: PASS/FAIL
-- json reads: PASS/FAIL
-- sandbox writes: PASS/FAIL
-
-Open risks:
-- <risk 1>
-- <risk 2>
-```
+# codex-switch Testing Guide
+
+This guide records the release gate for `0.1.0`.
+
+## Required checks
+
+Run these commands before publishing or reviewing release changes:
+
+```bash
+npm run build
+npm test
+npx tsc --noEmit
+npm pack --dry-run
+node dist/cli.js --help
+node dist/cli.js --version
+```
+
+## Release scenarios
+
+- Fresh direct-provider flow: `init -> add -> switch -> status -> doctor`
+- Fresh Copilot flow: `init -> login copilot -> add --copilot -> switch -> status -> doctor`
+- Ambiguous active profile: `list`, `status`, and provider pickers must surface ambiguity instead of inventing a unique current provider
+- `--json` envelope: top-level `ok`, `command`, `data`, `warnings`, and `error` must remain stable
+- `migrate`: advanced adopt helper only
+- `setup`: deprecated entry only
+
+## Fixture guidance
+
+- Prefer isolated temp directories for mutating tests.
+- Keep fixtures small and realistic.
+- Use `dev-codex/local-sandbox` only when a test needs a representative Codex directory layout.