@minniexcode/codex-switch 0.0.1 → 0.0.3

package/docs/codex-switch-command-design.md

@@ -0,0 +1,646 @@
+# codex-switch 命令设计说明
+
+## 文档信息
+
+- 文档类型：命令设计文档
+- 适用范围：`codex-switch` MVP
+- 关联文档：
+  - [`codex-switch-prd.md`](./codex-switch-prd.md)
+  - [`codex-switch-technical-architecture.md`](./codex-switch-technical-architecture.md)
+
+## 1. 文档目标
+
+这份文档把 `codex-switch` 的每个 CLI 命令拆开描述，重点沉淀下面这些内容：
+
+- 命令用途
+- 输入参数
+- 成功输出
+- 失败错误码
+- 关键行为语义
+- 对 AI / 自动化调用的注意事项
+
+这份文档是 PRD 的命令规格落地版，也是技术架构文档的命令视角补充。
+
+## 1.1 与 `cc-switch` / `codex-auth` 的命令形态差异
+
+为了帮助后续继续演进，这里先明确三者的命令/交互边界：
+
+- `codex-switch`
+  - 目标是稳定 CLI 命令
+  - 聚焦 provider/profile 切换、导入导出、诊断、回滚
+- `codex-auth`
+  - 更偏账号 / auth 管理 CLI
+  - 对本项目的参考点是命令组织方式
+- `cc-switch`
+  - 更偏 GUI / 桌面管理器
+  - 即使内部也有切换逻辑，用户主入口不是命令行，而是桌面界面
+
+这意味着 `codex-switch` 的命令设计原则应继续保持：
+
+- 参数显式
+- 输出稳定
+- 能被 AI 和脚本直接消费
+- 交互只作为 TTY 中的人类增强层，而不是自动化契约
+
+## 2. 公共命令约定
+
+### 2.1 命令入口
+
+统一命令名：
+
+```bash
+codexs
+```
+
+### 2.2 公共参数
+
+所有支持的命令共享以下全局参数：
+
+- `--json`
+  - 返回统一 JSON envelope
+- `--codex-dir <path>`
+  - 指定目标工作目录
+
+### 2.3 JSON 输出结构
+
+统一 envelope：
+
+```json
+{
+  "ok": true,
+  "command": "list",
+  "data": {},
+  "warnings": [],
+  "error": null
+}
+```
+
+失败时：
+
+```json
+{
+  "ok": false,
+  "command": "list",
+  "data": null,
+  "warnings": [],
+  "error": {
+    "code": "PROVIDERS_NOT_FOUND",
+    "message": "providers.json does not exist.",
+    "details": {
+      "file": "C:\\Users\\name\\.codex\\providers.json"
+    }
+  }
+}
+```
+
+### 2.4 固定错误码
+
+当前命令层统一使用：
+
+- `CONFIG_NOT_FOUND`
+- `PROVIDERS_NOT_FOUND`
+- `PROVIDERS_PARSE_ERROR`
+- `PROVIDER_NOT_FOUND`
+- `PROFILE_NOT_FOUND`
+- `BACKUP_FAILED`
+- `CODEX_LOGIN_FAILED`
+- `ROLLBACK_FAILED`
+- `INVALID_IMPORT_FILE`
+
+### 2.5 渐进式交互约定
+
+- `--json` 一律禁用交互
+- 非 TTY 一律不进入交互
+- 交互主要服务于人类高频写命令，不改变自动化显式参数契约
+- 用户取消 prompt、`Ctrl+C`、或确认选择否时，不应产生任何文件写入
+
+## 3. 命令清单概览
+
+```bash
+codexs list
+codexs current
+codexs switch <provider>
+codexs status
+codexs import <file>
+codexs export <file>
+codexs add <provider>
+codexs remove <provider>
+codexs doctor
+codexs rollback
+```
+
+## 4. 命令逐项设计
+
+### 4.1 `codexs list`
+
+#### 目标
+
+列出当前 `providers.json` 中的 provider 清单。
+
+#### 输入
+
+```bash
+codexs list [--json] [--codex-dir <path>]
+```
+
+#### 成功输出
+
+默认输出示意：
+
+```text
+freemodel -> freemodel
+packycode -> packycode tags=daily note=primary
+```
+
+JSON 输出示意：
+
+```json
+{
+  "ok": true,
+  "command": "list",
+  "data": {
+    "providers": [
+      {
+        "name": "freemodel",
+        "profile": "freemodel",
+        "note": null,
+        "tags": []
+      }
+    ],
+    "count": 1
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 失败错误码
+
+- `PROVIDERS_NOT_FOUND`
+- `PROVIDERS_PARSE_ERROR`
+
+#### AI 调用建议
+
+- 优先使用 `--json`
+- 不要依赖默认输出格式做机器解析
+
+### 4.2 `codexs current`
+
+#### 目标
+
+返回当前 `config.toml` 顶层 `profile`。
+
+#### 输入
+
+```bash
+codexs current [--json] [--codex-dir <path>]
+```
+
+#### 成功输出
+
+默认：
+
+```text
+Current profile: packycode
+```
+
+JSON：
+
+```json
+{
+  "ok": true,
+  "command": "current",
+  "data": {
+    "profile": "packycode"
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 失败错误码
+
+- `CONFIG_NOT_FOUND`
+- `PROFILE_NOT_FOUND`
+
+### 4.3 `codexs status`
+
+#### 目标
+
+给出本地配置的浅状态概览。
+
+#### 输入
+
+```bash
+codexs status [--json] [--codex-dir <path>]
+```
+
+#### 当前返回字段
+
+- `codexDir`
+- `configExists`
+- `providersExists`
+- `currentProfile`
+- `currentProfileMapped`
+- `provider`
+
+#### 成功输出
+
+JSON 示例：
+
+```json
+{
+  "ok": true,
+  "command": "status",
+  "data": {
+    "codexDir": "C:\\Users\\name\\.codex",
+    "configExists": true,
+    "providersExists": true,
+    "currentProfile": "packycode",
+    "currentProfileMapped": true,
+    "provider": "packycode"
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 设计说明
+
+- `status` 是概览，不做深度建议
+- 深度问题检测交给 `doctor`
+
+### 4.4 `codexs switch <provider>`
+
+#### 目标
+
+切换到指定 provider，并默认同步更新登录状态。
+
+#### 输入
+
+```bash
+codexs switch <provider> [--no-login] [--json] [--codex-dir <path>]
+```
+
+#### 交互行为
+
+- 当 `<provider>` 缺失且当前是 TTY 时，先从 `providers.json` 读取 provider 列表，再用选择器选择 provider
+- 当 `<provider>` 已显式传入时，不额外确认
+- `--no-login` 仍保持显式 flag，不进入提问
+
+#### 前置校验
+
+- `providers.json` 必须存在
+- provider 必须存在
+- provider 对应的 `profile` 必须存在于 `config.toml`
+
+#### 执行步骤
+
+1. 读取 provider 数据
+2. 校验 profile
+3. 备份 `config.toml`
+4. 如果存在，备份 `auth.json`
+5. 更新顶层 `profile`
+6. 默认执行 `codex login --with-api-key`
+7. 成功则保存为最近一次备份
+8. 失败则按 manifest 回滚
+
+#### 成功输出
+
+JSON 示例：
+
+```json
+{
+  "ok": true,
+  "command": "switch",
+  "data": {
+    "provider": "freemodel",
+    "profile": "freemodel",
+    "loginPerformed": true,
+    "backupPath": "C:\\Users\\name\\.codex\\backups\\20260511-221550-switch"
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 失败错误码
+
+- `PROVIDER_NOT_FOUND`
+- `PROFILE_NOT_FOUND`
+- `BACKUP_FAILED`
+- `CODEX_LOGIN_FAILED`
+- `ROLLBACK_FAILED`
+
+#### 注意事项
+
+- `--no-login` 仅跳过登录，不跳过备份和 profile 修改
+- 登录失败时当前实现会附带 `rollbackApplied: true`
+
+### 4.5 `codexs import <file>`
+
+#### 目标
+
+整体替换当前 `providers.json`。
+
+#### 输入
+
+```bash
+codexs import <file> [--json] [--codex-dir <path>]
+```
+
+#### 行为语义
+
+- 只支持整体替换
+- 不支持 merge
+- 写入前备份当前 `providers.json`
+- 路径参数必须显式传入
+- TTY 中实际替换前增加一次确认
+
+#### 成功输出
+
+```json
+{
+  "ok": true,
+  "command": "import",
+  "data": {
+    "importedProviders": ["imported"],
+    "backupPath": "C:\\Users\\name\\.codex\\backups\\20260511-221457-import"
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 失败错误码
+
+- `INVALID_IMPORT_FILE`
+- `BACKUP_FAILED`
+- `ROLLBACK_FAILED`
+
+### 4.6 `codexs export <file>`
+
+#### 目标
+
+导出当前 `providers.json` 到指定位置。
+
+#### 输入
+
+```bash
+codexs export <file> [--force] [--json] [--codex-dir <path>]
+```
+
+#### 行为语义
+
+- 默认不覆盖已有文件
+- 传 `--force` 后允许覆盖
+- 路径参数必须显式传入
+- 当目标文件已存在、当前是 TTY 且未传 `--force` 时，可通过确认后继续覆盖
+
+#### 成功输出
+
+```json
+{
+  "ok": true,
+  "command": "export",
+  "data": {
+    "exportedTo": "C:\\path\\providers-export.json",
+    "count": 3
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 失败错误码
+
+- `INVALID_IMPORT_FILE`
+- `PROVIDERS_NOT_FOUND`
+- `PROVIDERS_PARSE_ERROR`
+
+### 4.7 `codexs add <provider>`
+
+#### 目标
+
+新增一条 provider 记录。
+
+#### 输入
+
+```bash
+codexs add <provider> \
+  --profile <name> \
+  --api-key <key> \
+  [--base-url <url>] \
+  [--note <text>] \
+  [--tag <tag>] \
+  [--json] \
+  [--codex-dir <path>]
+```
+
+#### 行为语义
+
+- provider 名必须唯一
+- 写入前备份旧 `providers.json`
+- 显式参数模式保持可用
+- 当缺少必填字段且 stdin/stdout 都是 TTY 时，允许渐进式提问
+- `--json` 或非 TTY 场景下仍要求显式传入必填参数
+- `profile` 优先从 `config.toml` 已有 profile 列表里选择，获取失败时退回文本输入
+- `apiKey` 使用隐藏输入并要求二次确认
+
+#### 成功输出
+
+```json
+{
+  "ok": true,
+  "command": "add",
+  "data": {
+    "provider": "temp",
+    "profile": "freemodel",
+    "backupPath": "C:\\Users\\name\\.codex\\backups\\20260511-221457-add"
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 失败错误码
+
+- `INVALID_IMPORT_FILE`
+- `BACKUP_FAILED`
+- `ROLLBACK_FAILED`
+
+### 4.8 `codexs remove <provider>`
+
+#### 目标
+
+删除一条 provider 记录。
+
+#### 输入
+
+```bash
+codexs remove <provider> [--force] [--json] [--codex-dir <path>]
+```
+
+#### 行为语义
+
+- TTY 中若缺少 `<provider>`，允许先选择 provider
+- TTY 中始终需要确认，确认文案必须带 provider 名
+- TTY 中即使未传 `--force`，也可通过确认完成删除
+- 非 TTY 或 `--json` 场景下仍要求显式 `<provider> --force`
+- 先备份再删除
+
+#### 失败错误码
+
+- `PROVIDER_NOT_FOUND`
+- `INVALID_IMPORT_FILE`
+- `BACKUP_FAILED`
+- `ROLLBACK_FAILED`
+
+### 4.9 `codexs doctor`
+
+#### 目标
+
+返回结构化问题列表，而不是只给一个总体状态。
+
+#### 输入
+
+```bash
+codexs doctor [--json] [--codex-dir <path>]
+```
+
+#### 当前诊断项
+
+- `config.toml` 是否存在
+- `providers.json` 是否存在
+- `providers.json` 是否可解析
+- provider 的 profile 是否存在
+- `codex` CLI 是否可执行
+
+#### 当前返回结构
+
+```json
+{
+  "ok": true,
+  "command": "doctor",
+  "data": {
+    "healthy": false,
+    "issues": [
+      {
+        "code": "CODEX_LOGIN_FAILED",
+        "message": "codex CLI is not available.",
+        "cause": "spawnSync codex EPERM"
+      }
+    ],
+    "codexDir": "C:\\Users\\name\\.codex"
+  },
+  "warnings": ["doctor found 1 issue(s)"],
+  "error": null
+}
+```
+
+#### 说明
+
+- 当前实现把 codex CLI 缺失归到 `CODEX_LOGIN_FAILED`
+- 后续可按需要拆分更细错误码
+
+### 4.10 `codexs rollback`
+
+#### 目标
+
+恢复最近一次备份对应的文件状态。
+
+#### 输入
+
+```bash
+codexs rollback [--json] [--codex-dir <path>]
+```
+
+#### 行为语义
+
+- 读取 `backups/latest.json`
+- 恢复 manifest 中记录的文件
+- 如果最近一次备份包含 `auth.json`，一并恢复
+- TTY 中执行前会展示备份目录和受影响文件摘要，并请求确认
+
+#### 成功输出
+
+```json
+{
+  "ok": true,
+  "command": "rollback",
+  "data": {
+    "restoredFiles": ["config.toml", "auth.json"],
+    "backupPath": "C:\\Users\\name\\.codex\\backups\\20260511-221550-switch"
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+#### 失败错误码
+
+- `ROLLBACK_FAILED`
+
+## 5. 默认输出与敏感信息策略
+
+默认输出遵循：
+
+- 不打印完整 `apiKey`
+- 不打印无关调试信息
+- 成功时尽量只返回命令核心结果
+
+JSON 输出也遵循相同策略：
+
+- `error.details` 不应包含完整 `apiKey`
+- 主要返回路径、命令对象、回滚状态等可操作信息
+
+## 6. AI / 自动化调用建议
+
+对 AI 代理或自动化脚本，推荐以下调用约定：
+
+- 一律使用 `--json`
+- 严格按 `error.code` 判断失败类型
+- 对 `switch` 命令关注：
+  - `provider`
+  - `profile`
+  - `loginPerformed`
+  - `backupPath`
+  - `rollbackApplied`
+- 对 `doctor` 命令关注：
+  - `healthy`
+  - `issues[]`
+
+推荐模式：
+
+1. 先调用 `status --json`
+2. 再调用 `doctor --json`
+3. 满足前置条件后调用 `switch --json`
+4. 失败时根据错误码决定是否提示用户手动执行 `rollback`
+
+## 7. 后续命令演进建议
+
+如果继续扩展命令面，建议新增命令时遵守下面三条：
+
+- 不破坏当前 JSON envelope
+- 不复用语义不匹配的错误码
+- 所有写命令默认纳入备份与回滚模型
+
+未来候选命令：
+
+- `codexs show <provider>`
+- `codexs edit <provider>`
+- `codexs backups list`
+- `codexs rollback <backup-id>`
+- `codexs import --merge`
+
+## 8. 结论
+
+`codex-switch` 当前命令设计已经具备下面几个工程特征：
+
+- 命令面稳定
+- 参数风格统一
+- JSON 输出可机器解析
+- 写操作具备安全语义
+- 错误码已可作为 AI 调用契约
+
+这意味着它已经不再只是“能切换配置的脚本集合”，而是一套具备持续演进空间的 CLI 命令体系。

package/docs/codex-switch-prd.md

@@ -8,6 +8,8 @@
 - 版本范围：MVP / CLI First
 - 文档定位：正式 PRD
 - 对应研究稿：[`codex-switch-product-research.md`](./codex-switch-product-research.md)
+- 对应技术架构：[`codex-switch-technical-architecture.md`](./codex-switch-technical-architecture.md)
+- 对应命令设计：[`codex-switch-command-design.md`](./codex-switch-command-design.md)
 
 ## 一句话定义
 
@@ -97,6 +99,10 @@ AI 需要通过 `status` 或 `doctor --json` 判断本地配置是否完整、
 
 关键命令必须提供稳定、可解析的 `--json` 输出。
 
+### Progressive For Humans
+
+高频人类写命令可以在 TTY 中提供渐进式交互，但这层体验不能改变自动化的显式参数契约。
+
 ### Local First
 
 MVP 的核心对象是本地文件与本机配置，不依赖云端控制面。
@@ -276,6 +282,12 @@ MVP 固定包含以下命令：
 - 位置参数：`<provider>`
 - 可选参数：`--no-login`
 
+交互边界：
+
+- 当 `<provider>` 缺失且运行在 TTY 中时，允许用户从 provider 列表中选择
+- `--json` 或非 TTY 场景下仍要求显式 provider
+- 当 provider 已显式传入时，不做额外确认
+
 前置校验：
 
 - `providers.json` 存在且可解析
@@ -344,6 +356,8 @@ MVP 固定包含以下命令：
 说明：
 
 - MVP 不做 merge 导入，固定为整体替换
+- 路径参数保持显式，不做路径向导
+- TTY 中在真正覆盖前增加确认
 
 ### `codexs export <file>`
 
@@ -359,6 +373,8 @@ MVP 固定包含以下命令：
 
 - 默认不覆盖已有文件
 - 只有传入 `--force` 时才允许覆盖
+- TTY 中若目标已存在且未传 `--force`，允许通过确认覆盖
+- 非 TTY 与 `--json` 保持显式 `--force` 契约
 
 ### `codexs add <provider>`
 
@@ -381,8 +397,11 @@ MVP 固定包含以下命令：
 
 范围限制：
 
-- MVP 只支持显式参数模式
-- 不提供交互式 wizard
+- 显式参数模式仍是自动化主路径
+- 当 `add` 缺少必填参数且运行在 TTY 中时，允许进入渐进式交互录入
+- `--json` 或非 TTY 场景下仍要求显式传参
+- `profile` 优先展示 `config.toml` 中现有 profile 供选择
+- `apiKey` 以隐藏输入采集并要求二次确认
 
 ### `codexs remove <provider>`
 
@@ -404,7 +423,8 @@ MVP 固定包含以下命令：
 
 范围限制：
 
-- 自动化调用场景下，要求显式传 `--force`
+- TTY 中可选择 provider，并通过确认代替 `--force`
+- 自动化调用场景下，仍要求显式传 `--force`
 
 ### `codexs doctor`
 
@@ -440,6 +460,7 @@ MVP 固定包含以下命令：
 说明：
 
 - `rollback` 进入 MVP，因为它直接支撑“默认安全”的产品承诺
+- TTY 中在恢复前展示将被恢复的文件摘要，并请求确认
 
 ## 输出契约
 

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

@@ -10,6 +10,8 @@
 
 - 研究输入稿：[`codex-switch-product-research.md`](./codex-switch-product-research.md)
 - 正式 PRD：[`codex-switch-prd.md`](./codex-switch-prd.md)
+- 技术架构设计：[`codex-switch-technical-architecture.md`](./codex-switch-technical-architecture.md)
+- 命令设计说明：[`codex-switch-command-design.md`](./codex-switch-command-design.md)
 
 ## 产品概述