@minniexcode/codex-switch 0.2.0 → 0.2.2

package/README.AI.md

@@ -1,24 +1,22 @@
-# AI README
+# README.AI
 
-This file summarizes the current operational contract for AI agents, automation scripts, and contributors.
+This file is the current AI-facing fact sheet for `@minniexcode/codex-switch`.
 
-## Package Context
+Current repository version: `0.2.1`
 
-- Package: `@minniexcode/codex-switch`
-- CLI name: `codexs`
-- Current repository version: `0.1.5`
-- Version status: development line
-- Runtime contract target: Codex `0.134.0+`
+Current fact sources:
 
-## Product Role
+- `docs/PRD/codex-switch-prd-v0.2.1.md`
+- `docs/Design/codex-switch-v0.2.1-design.md`
+- `docs/cli-usage.md`
 
-`codex-switch` is a local-first TypeScript CLI that manages provider and model-provider routing state for Codex while keeping tool-managed state separate from the target Codex runtime.
+## Product Positioning
 
-The managed source of truth is the tool home. Runtime files under the target Codex directory are projected outputs, not the main registry.
+`codex-switch` is a local-first provider/model-provider management CLI for Codex. It manages local provider records, projects Codex `model_provider` sections, writes the active top-level `model` / `model_provider` route, and maintains backups around mutating commands.
 
-## Primary Workflows
+Do not describe the current product as a direct-vs-Copilot dual path. In `0.2.1`, there is only the provider-management workflow for OpenAI-compatible provider endpoints.
 
-Direct provider workflow:
+## Primary Workflow
 
 ```bash
 codexs init
@@ -28,70 +26,47 @@ codexs status
 codexs doctor
 ```
 
-GitHub Copilot workflow:
+`--profile` means managed `model_provider` id alias. It is not the legacy Codex top-level `profile` selector.
 
-```bash
-codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <model-provider-id> --model <model>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Advanced adopt workflow:
-
-```bash
-codexs init
-codexs migrate
-```
-
-`migrate` is not a fresh-install default. It is an advanced adopt helper for existing runtime state.
-
-## Runtime Route Contract
-
-For Codex `0.134.0+`, the live route is selected by:
+## Current Command Surface
 
-- top-level `model`
-- top-level `model_provider`
-
-Important implications for automation:
-
-- treat `model_provider` as the active provider selector
-- treat `--profile` as an alias for a managed `model_provider` id
-- do not describe top-level `profile` or `[profiles.*]` as the primary runtime path
-- managed direct-provider projection does not keep `env_key` or `env_key_instructions`
-- managed provider projection fixes `wire_api = "responses"` and `requires_openai_auth = true`
+Document only these current commands:
 
-Expected managed direct-provider projection:
-
-```toml
-model = "gpt-5.5"
-model_provider = "proxy"
-
-[model_providers.proxy]
-name = "proxy"
-base_url = "https://proxy.example.com/v1"
-wire_api = "responses"
-requires_openai_auth = true
+```text
+init
+migrate
+list
+show
+current
+status
+config show
+config list-profiles
+add
+edit
+switch
+remove
+import
+export
+backups list
+rollback
+doctor
+setup
 ```
 
-Authentication remains projected through `auth.json` with `OPENAI_API_KEY`.
+`setup` is deprecated and only points callers to `init` or `migrate`.
 
-## Important Paths
+## State Model
 
 Tool home:
 
 ```text
-~/.config/codex-switch/
+~/.codex-switch/
   codex-switch.json
   providers.json
   backups/
-  runtime/
-  runtimes/
 ```
 
-Target Codex runtime:
+Target Codex directory:
 
 ```text
 ~/.codex/
@@ -99,45 +74,42 @@ Target Codex runtime:
   auth.json
 ```
 
-Operational meaning:
+Managed projection for current Codex versions is route-first:
 
-- `providers.json` is the managed provider registry.
-- `codex-switch.json` stores tool-level metadata such as the default target Codex directory.
-- `config.toml` is the active runtime routing file.
-- `auth.json` is the active auth projection file.
+- top-level `model`
+- top-level `model_provider`
+- matching `[model_providers.<id>]`
+- API-key auth projection in `auth.json`
 
-## Command Notes
+Do not present top-level `profile` or `[profiles.*]` as the current managed runtime path. They may be inspected for adoption or legacy diagnostics only.
 
-Shared flags:
+## Current Non-Goals
 
-```bash
---json
---codex-dir <path>
---help
---version
-```
+`0.2.1` does not include:
 
-Relevant environment variables:
+- Copilot SDK integration.
+- GitHub device-flow login.
+- `login copilot`.
+- `add --copilot`.
+- `bridge start`, `bridge status`, or `bridge stop`.
+- HTTP proxy bridge or local bridge worker runtime.
+- `runtime/` or `runtimes/` managed service directories.
+- Bridge logs or bridge runtime state.
+- Built-in third-party router packaging.
+- Automatic migration of old Copilot or bridge state.
 
-```bash
-CODEXS_HOME
-CODEXS_CODEX_DIR
-```
+A future release may integrate a third-party router-like capability. Do not write current commands, schema, or runtime paths for that in `0.2.1` docs or code.
 
-Important behavioral constraints:
+## Development-Version Policy
 
-- Prefer `--json` for programmatic invocation whenever the command supports it.
-- `login copilot` requires a real TTY and does not support `--json`.
-- `login copilot` currently installs the local Copilot SDK when needed, tries the bundled runtime CLI first, falls back to `PATH` when necessary, and rechecks auth readiness before reporting success.
-- `add --copilot` assumes SDK install and upstream Copilot auth are already ready.
-- Non-interactive automation should pass `--profile` explicitly. In TTY mode, `add` and `edit` can prompt for missing required fields.
-- `migrate` remains interactive when provider adoption requires human input.
-- `status` is the main dual-path summary command.
-- `doctor` is the deeper repair-oriented diagnostic command.
-- The current `0.1.5` line focuses on Copilot Bridge process visibility, Responses commentary/reasoning stream events, defensive SDK-event normalization, and unknown-event redaction hardening rather than command-surface expansion.
+Treat `0.2.1` as development-version software unless the user explicitly declares a real release. Do not add automatic migration shims, dual-read/dual-write behavior, or compatibility preservation for old experimental local state unless asked in the current task.
 
-## Safety Notes
+## Verification Commands
 
-- Treat `providers.json` as sensitive because it may contain API keys.
-- Human-readable output may mask secrets, but JSON output can expose full provider payloads.
-- Managed write operations rely on backup and rollback flow; do not describe manual file edits as the primary workflow.
+```bash
+npx tsc --noEmit
+npm test
+node dist/cli.js --help
+node dist/cli.js --version
+npm pack --dry-run
+```

package/README.CN.md

@@ -1,153 +1,108 @@
-# @minniexcode/codex-switch
+# codex-switch
 
-`@minniexcode/codex-switch` 是一个本地优先的 CLI，用来安全地管理和切换 Codex 的 provider 与 model-provider 路由配置。
+`@minniexcode/codex-switch` 是一个本地优先的 Codex provider/model-provider 管理 CLI。
 
-它把 `codex-switch` 自己的工具状态和目标 Codex runtime 明确分开，让 provider 管理、备份与 runtime 投影有一套受管流程，而不是依赖手工改文件。
+它把 `codex-switch` 自己的工具状态和目标 Codex 目录分开，让 provider 管理、备份和 `model_provider` 投影通过明确命令完成，而不是手工编辑文件。
 
-## 版本定位
+当前包版本：`0.2.1`
 
-当前包版本：`0.1.5`
-
-这是当前仓库开发线。`0.1.5` 是 Copilot Bridge 过程可见性补丁，聚焦于 commentary/reasoning 流式信号、SDK 事件防御性归一化，以及未知运行态事件的更安全脱敏，同时不扩展 provider 命令面。
+`0.2.1` 是当前仓库开发线，也是 provider-management-only 收敛版本：只管理本地 OpenAI-compatible provider 记录，并把它们投影到 Codex `config.toml` / `auth.json`。本版本不包含之前实验过的账号登录、本地 bridge 或后台 runtime 能力。
 
 ## 安装
 
 ```bash
 npm install -g @minniexcode/codex-switch
+codexs --help
 ```
 
-不全局安装时也可以直接运行：
+本地开发：
 
 ```bash
-npx @minniexcode/codex-switch --help
+npm install
+npm run build
+node dist/cli.js --help
 ```
 
-CLI 命令名：
-
-```bash
-codexs --help
-```
+需要 Node.js `>=18`。
 
 ## 主工作流
 
-Direct provider 主路径：
-
-```bash
-codexs init
-codexs add my-provider --profile my-provider --model gpt-5.5 --base-url https://gateway.example.com/v1 --api-key sk-xxx
-codexs switch my-provider
-codexs status
-codexs doctor
-```
-
-GitHub Copilot 主路径：
-
 ```bash
 codexs init
-codexs login copilot
-codexs add copilot-main --copilot --profile copilot-main --model gpt-4.1
-codexs switch copilot-main
+codexs add packycode --profile packycode --model gpt-5 --api-key sk-xxx --base-url https://api.example/v1
+codexs switch packycode
 codexs status
 codexs doctor
 ```
 
-说明：
-
-- `init` 负责初始化 `codex-switch` 的 tool home 与受管状态文件。
-- `login copilot` 负责上游 Copilot onboarding 和登录可用性检查。
-- `add --copilot` 不负责替你登录，它假设上游 Copilot 已经 ready。
-- 非交互调用请显式传入 `--profile`；在 TTY 模式下，`add` 和 `edit` 可以补问缺失的必填项。
-- `switch` 会把选中的 provider 投影到目标 Codex runtime 的顶层 `model` 与 `model_provider`。
-- `status` 是切换后的主读取命令。
-- `doctor` 是主诊断命令，用于解释问题和下一步修复动作。
-
-## Runtime 路由模型
-
-对于 Codex `0.134.0+`，活动 runtime route 由 `config.toml` 顶层的 `model` 和 `model_provider` 决定。
-
-`codex-switch` 按这套 contract 管理运行态：
-
-- 顶层 `model` 表示当前活动模型
-- 顶层 `model_provider` 表示当前活动 provider route
-- 受管的 `[model_providers.<id>]` 是 runtime provider 定义投影
-- `--profile` 只作为受管 `model_provider` id 的 alias，不再是主 runtime selector
-
-Direct provider 的运行态投影会写入：
-
-- 顶层 `model`
-- 顶层 `model_provider`
-- `[model_providers.<id>]`
-- 带 `OPENAI_API_KEY` 的 `auth.json`
-
-受管 direct provider 投影不会再保留 `env_key` 或 `env_key_instructions`。`switch`、`add` 和 `edit` 会在写入活动路由前清理这些旧字段。
-
-对受管的 OpenAI-compatible route，投影后的 provider 结构固定为：
-
-```toml
-model = "gpt-5.5"
-model_provider = "my-provider"
-
-[model_providers.my-provider]
-name = "my-provider"
-base_url = "https://gateway.example.com/v1"
-wire_api = "responses"
-requires_openai_auth = true
-```
-
-## Advanced Adopt 路径
-
-如果你已经有现成的 Codex runtime 状态，希望把它 adopt 到受管 `providers.json`，再使用：
-
-```bash
-codexs init
-codexs migrate
-```
+- `init` 创建 `codex-switch` 工具状态文件。
+- `add` 在 `providers.json` 中保存受管 provider，并创建或更新对应 `[model_providers.<id>]`。
+- `switch` 写入目标 Codex 配置的顶层 `model` / `model_provider`，并把 `OPENAI_API_KEY` 投影到 `auth.json`。
+- `status` 汇总当前映射、认证投影和漂移状态。
+- `doctor` 输出问题优先的诊断结果。
 
-`migrate` 是高级 adopt helper，不是 fresh install 的默认第一步。
+`--profile` 是受管 Codex `model_provider` id 的 CLI alias，不是旧 Codex 顶层 `profile` selector。
 
 ## 命令面
 
-```bash
+`0.2.1` 当前命令：
+
+```text
 codexs init
-codexs login copilot
 codexs migrate
 codexs list
 codexs show <provider>
 codexs current
 codexs status
-codexs config show [profile]
+codexs config show
 codexs config list-profiles
 codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> [--base-url <url>]
-codexs add <provider> --copilot --profile <model-provider-id> --model <model>
-codexs edit <provider>
+codexs edit <provider> [options]
 codexs switch <provider>
-codexs remove <provider> [--force] [--switch-to <provider>]
+codexs remove <provider> --force
 codexs import <file>
-codexs export <file> [--force]
-codexs bridge start [provider]
-codexs bridge status [provider]
-codexs bridge stop [provider]
+codexs export <file>
 codexs backups list
 codexs rollback [backup-id]
 codexs doctor
+codexs setup
+```
+
+`setup` 已废弃，只保留为指向 `init` 或 `migrate` 的兼容入口。
+
+## Runtime 投影
+
+Codex `0.134.0+` 的活动路由由 `config.toml` 顶层 `model` 和 `model_provider` 决定。
+
+受管 provider 的投影形态：
+
+```toml
+model = "gpt-5"
+model_provider = "packycode"
+
+[model_providers.packycode]
+name = "packycode"
+base_url = "https://api.example/v1"
+wire_api = "responses"
+requires_openai_auth = true
 ```
 
-`setup` 仍然存在，但只作为已弃用兼容入口，用来提示调用方改用 `init` 或 `migrate`。
+`codex-switch` 不为新受管 provider 写入旧 `[profiles.*]`，并会在写入受管投影时清理旧 `env_key` / `env_key_instructions` 字段。
 
-## 双路径模型
+认证会投影到目标 Codex `auth.json`，使用 API-key 模式和 `OPENAI_API_KEY`。不要提交真实 API key、`auth.json` 或私有 provider 导出。
 
-tool home：
+## 状态位置
+
+工具 home：
 
 ```text
-~/.config/codex-switch/
+~/.codex-switch/
   codex-switch.json
   providers.json
   backups/
-  runtime/
-  runtimes/
 ```
 
-目标 Codex runtime：
+目标 Codex 目录：
 
 ```text
 ~/.codex/
@@ -155,64 +110,54 @@ tool home：
   auth.json
 ```
 
-关键边界：
+环境变量：
 
-- `providers.json` 是受管 provider 注册表，位于 tool home。
-- `codex-switch.json` 保存工具级元数据，例如 `defaultCodexDir`。
-- `config.toml` 仍然是目标 runtime 里的活动路由文件。
-- `auth.json` 仍然是目标 runtime 里的活动认证投影文件。
-- Direct provider 切换会改写活动 runtime 中的 `OPENAI_API_KEY`。
-- Copilot provider 保持上游 GitHub 登录留在官方 Copilot runtime 中，`codex-switch` 只管理本地 bridge 状态与路由。
+- `CODEXS_HOME` 覆盖 `codex-switch` 工具 home。
+- `CODEXS_CODEX_DIR` 在未传 `--codex-dir` 时提供默认目标 Codex 目录。
+- 开发环境下，`NODE_ENV=development` 且没有显式覆盖时默认使用 `./dev-codex/local-sandbox`。
 
-路径控制：
+## 迁移与采用
 
-- `--codex-dir <path>` 显式指定目标 Codex runtime 目录。
-- `CODEXS_CODEX_DIR` 在未传 `--codex-dir` 时提供默认目标目录。
-- `CODEXS_HOME` 用于覆盖 tool home 位置。
+只有当你已经有 Codex 配置，并希望把它 adopt 到受管 `providers.json` 时才使用 `migrate`。新安装默认使用 `init`。
 
-## 自动化说明
+```bash
+codexs migrate
+codexs migrate --overwrite --codex-dir ~/.codex
+```
 
-这个 CLI 同时支持人类终端使用和非交互自动化。
+本仓库按开发版本处理，包括 `0.2.1`。旧实验状态不会自动迁移；从旧本地实验切换过来时，请手动清理或重新添加 provider。
 
-全局参数：
+## 当前非目标
 
-```bash
---json
---codex-dir <path>
---help
---version
-```
+`0.2.1` 不实现也不预留以下 runtime 代码路径：
 
-当前实现边界：
+- GitHub Copilot SDK 集成。
+- GitHub device-flow 登录。
+- `login copilot`。
+- `add --copilot`。
+- HTTP proxy bridge 或本地 bridge worker 命令。
+- 后台 runtime service、bridge log 或 bridge runtime state。
+- 内置第三方 router 封装。
+- 账号系统或云同步。
+- 旧 Copilot / bridge 状态的自动迁移。
 
-- `login copilot` 必须运行在真实 TTY 下，不支持 `--json`。
-- `migrate` 在需要人工补齐 adopt 信息时仍然保持交互式语义。
-- 自动化调用应尽量显式传参，并优先使用 `--json`。
+未来版本可能接入类似第三方 router 的能力，但 `0.2.1` 不承诺工作流、schema 或 runtime 行为。
 
-## 本地开发
+## 开发
 
 ```bash
 npm run build
-npm test
 npx tsc --noEmit
+npm test
 node dist/cli.js --help
+node dist/cli.js --version
 npm pack --dry-run
 ```
 
-## 相关文档
-
-- [English README](./README.md)
-- [AI README](./README.AI.md)
-- [详细 CLI 文档](./docs/cli-usage.md)
-- [产品概览](./docs/codex-switch-product-overview.md)
-- [测试说明](./docs/Tests/testing.md)
-- [PRD 0.1.1](./docs/PRD/codex-switch-prd-v0.1.1.md)
-- [Design 0.1.1](./docs/Design/codex-switch-v0.1.1-design.md)
-- [PRD 0.1.2](./docs/PRD/codex-switch-prd-v0.1.2.md)
-- [Design 0.1.2](./docs/Design/codex-switch-v0.1.2-design.md)
-- [PRD 0.1.5](./docs/PRD/codex-switch-prd-v0.1.5.md)
-- [Design 0.1.5](./docs/Design/codex-switch-v0.1.5-design.md)
+## 当前事实源
 
-## License
+- [PRD 0.2.1](./docs/PRD/codex-switch-prd-v0.2.1.md)
+- [Design 0.2.1](./docs/Design/codex-switch-v0.2.1-design.md)
+- [CLI usage](./docs/cli-usage.md)
 
-MIT
+旧 `0.1.x` / `0.2.0` 文档保留为历史记录。