@minniexcode/codex-switch 0.0.4 → 0.0.5

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

@@ -1,77 +1,80 @@
-# codex-switch `0.1.0` 目标 PRD
+# codex-switch `0.0.5` PRD
 
 ## 文档信息
 
-- 状态：Target PRD
+- 状态：Active PRD
 - 产品名：`codex-switch`
 - CLI 命令名：`codexs`
-- 当前基线版本：`0.0.3`
-- 目标版本：`0.1.0`
-- 文档定位：从 `0.0.3` 走向 `0.1.0` 的目标规格与阶段性演进路线
+- 当前基线版本：`0.0.4`
+- 目标版本：`0.0.5`
+- 文档定位：定义 `0.0.4 -> 0.0.5` 的直接需求范围
 - 历史基线 PRD：[`codex-switch-prd.md`](./codex-switch-prd.md)
+- 后续演进 PRD：[`codex-switch-prd-v0.0.5-to-v0.1.0.md`](./codex-switch-prd-v0.0.5-to-v0.1.0.md)
 - 对应研究稿：[`../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)
 
 ## 一句话定义
 
-`codex-switch` 的 `0.1.0` 目标，是从一个已经验证可行的本地 provider/profile 管理 CLI，演进为一套对人类和 AI 都稳定、可初始化、可诊断、可恢复、可持续扩展的发布级命令体系。
+`0.0.5` 的目标不是继续堆命令，而是把 `config.toml` 从“只能浅层切换 active profile”升级为“可以结构化读取、受控维护 provider-linked profiles，并与 `providers.json` 保持一致”。
 
-## 版本语义
-
-- `0.0.x`：测试 / 验证阶段版本，用于收敛模型、命令面和失败语义
-- `0.1.0`：第一条稳定发布规格线，不要求当前立刻完成，但要求目标边界清晰
-- 当前仓库状态：`0.0.3` 已完成 MVP 核心命令面与交互式增强
-
-这意味着本文件不是“下一版马上发布什么”的短期计划，而是 `0.0.3` 之后持续演进到 `0.1.0` 的目标 PRD。
-
-## 当前基线：`0.0.3`
+## 当前基线：`0.0.4`
 
 当前已落地能力：
 
 - `list` / `current` / `status`
 - `switch <provider>`
-- `import <file>` / `export <file>`
-- `add <provider>` / `remove <provider>`
+- `import <file>` / `import <file> --merge` / `export <file>`
+- `add <provider>` / `edit <provider>` / `show <provider>` / `remove <provider>`
+- `setup`
 - `doctor`
-- `rollback`
+- `backups list`
+- `rollback` / `rollback <backup-id>`
 
-当前基线已经具备的工程特征：
+当前基线已具备的工程特征：
 
 - 本地文件模型围绕 `~/.codex/`
 - `providers.json` 作为 management SSOT
 - `config.toml` 与 `auth.json` 作为 runtime state
 - 写命令统一走备份、锁和失败回滚
 - `--json` 输出固定 envelope
-- 高频写命令支持 TTY 渐进式交互
 
-当前基线仍然存在的边界：
+当前主要缺口：
 
-- 缺少首次初始化 / bootstrap 命令
-- 只支持 latest rollback，不支持按备份条目恢复
-- provider 查看和编辑仍然偏基础
-- 错误码体系仍带有 MVP 阶段的复用痕迹
-- 尚未进入第三方 auth / extension 集成阶段
+- `config.toml` 仍以轻量字符串匹配方式处理
+- provider 管理命令不能稳定同步 linked profile sections
+- 缺少结构化展示 config 的稳定命令面
+- 历史 profile、共享 profile、缺失 section 的一致性规则还不完整
 
-## `0.1.0` 目标
+## `0.0.5` 目标
 
-`0.1.0` 需要同时满足以下目标：
+`0.0.5` 需要完成四件事：
 
-- 保持当前 CLI 和 JSON 契约稳定
-- 让首次用户可以通过 `setup` 完成从环境检测到 registry 初始化的主流程
-- 让 provider registry 的查看、编辑、导入合并能力更完整
-- 让备份与回滚从“最新一次”演进到“显式备份条目”
-- 为未来 auth / extension 集成保留明确边界，而不把远期需求提前塞进稳定主线
+- 引入结构化 TOML 读取与非破坏性修改能力
+- 增加稳定的 config 查看命令，供人类、AI 和脚本消费
+- 让 provider 写命令同步维护 linked profile sections
+- 补齐历史状态、一致性信号和安全删除规则
 
-## 长期演进守则
+## 范围
 
-如果继续扩展命令面，后续新增命令统一遵守下面三条：
+### In Scope
 
-- 不破坏当前 JSON envelope
-- 不复用语义不匹配的错误码
-- 所有写命令默认纳入备份与回滚模型
+- 顶层 active `profile`
+- `[profiles.<name>]` 受管 section
+- 第一批正式受管字段：`model`
+- `config show`
+- `config list-profiles`
+- `add` / `edit` / `remove` / `setup` / `import --merge` 的 provider-config 一致性
+- `doctor` / `status` 的一致性信号
 
-## 稳定公共契约
+### Out of Scope
+
+- 整个 `config.toml` 的通用编辑器
+- 任意顶层键的自由增删改
+- 更大 profile schema 的首版正式规格
+- 第三方 auth / extension 集成
+
+## 数据与契约
 
 ### JSON Envelope
 
@@ -87,307 +90,254 @@
 }
 ```
 
-约束：
-
-- 顶层 shape 保持不变
-- 后续字段扩展只做加法
-- 详细结果进入 `data`
-- 非致命提示进入 `warnings`
-- 结构化失败信息继续进入 `error`
-
-### 数据模型
-
-`providers.json` 继续是 managed registry 的单一事实源：
-
-```json
-{
-  "providers": {
-    "packycode": {
-      "profile": "packycode",
-      "apiKey": "sk-xxx",
-      "baseUrl": "https://example.com/v1",
-      "note": "primary free model route",
-      "tags": ["free", "daily"]
-    }
-  }
-}
-```
-
-`0.1.0` 之前默认不放宽这个模型：
-
-- `profile` 仍然必填
-- `apiKey` 仍然按完整 managed provider 处理
-- 不引入“半初始化 provider”作为正式稳定状态
+要求：
 
-### 错误码演进原则
+- 顶层 shape 不变
+- 新字段只追加到 `data` / `warnings`
+- 错误信息继续进入 `error`
 
-保留现有领域错误码，并把错误码体系从 MVP 复用模式收紧到语义匹配模式。
+### `providers.json`
 
-现有保留：
+`providers.json` 继续是 provider registry 的单一事实源：
 
-- `CONFIG_NOT_FOUND`
-- `PROVIDERS_NOT_FOUND`
-- `PROVIDERS_PARSE_ERROR`
-- `PROVIDER_NOT_FOUND`
-- `PROFILE_NOT_FOUND`
-- `BACKUP_FAILED`
-- `CODEX_LOGIN_FAILED`
-- `ROLLBACK_FAILED`
-- `LOCK_CONFLICT`
-- `LIVE_STATE_DRIFT`
+- `profile` 必填
+- `apiKey` 仍按完整 managed provider 处理
+- 不引入“半初始化 provider”作为稳定状态
 
-后续新增命令应逐步引入更精确的错误码，而不是继续把无关问题塞进 `INVALID_IMPORT_FILE`。
+### `config.toml`
 
-建议新增 / 预留：
+到 `0.0.5` 为止，`config.toml` 的受管范围限定为：
 
-- `INVALID_ARGUMENT`
-- `UNKNOWN_COMMAND`
-- `PROMPT_CANCELLED`
-- `CODEX_NOT_INSTALLED`
-- `CODEX_VERSION_UNSUPPORTED`
-- `CODEX_DIR_NOT_FOUND`
-- `CODEX_DIR_AMBIGUOUS`
-- `PROVIDERS_ALREADY_EXISTS`
-- `IMPORT_MERGE_CONFLICT`
-- `BACKUP_NOT_FOUND`
+- 顶层 active `profile`
+- 与 provider 关联的 `[profiles.<name>]`
+- section 内最小正式字段：`model`
 
 约束：
 
-- `CODEX_LOGIN_FAILED` 只表示登录失败
-- codex 缺失与版本过低必须使用环境类错误码
-- rollback 找不到目标备份时必须使用恢复类错误码
-
-## `0.0.4` 功能里程碑
+- `providers.json` 仍是 provider 身份、凭据和管理元数据的 SSOT
+- `config.toml` 只承载运行态投影，不升级为对等事实源
+- 非受管 TOML 内容允许存在，但不进入通用编辑范围
 
-下面这些内容暂时作为 `0.0.4` 的功能里程碑。它们属于从 `0.0.3` 往 `0.1.0` 推进过程中的下一阶段，不代表已经锁定整个 `0.1.0` 的最终范围。
+### Managed Profile View
 
-### 1. `codexs setup`
+读取命令应围绕稳定视图返回，而不是直接暴露内部持久化细节。最小视图建议包含：
 
-#### 目标
-
-提供首次初始化主流程，让用户从“本机已有 Codex 环境，但还没有 codex-switch 管理态文件”平滑进入受管状态。
-
-#### 目标命令
-
-```bash
-codexs setup
+```json
+{
+  "name": "packycode",
+  "model": "gpt-5",
+  "linkedProviders": ["packycode"],
+  "isActive": true,
+  "managed": true
+}
 ```
 
-#### 行为顺序
-
-`setup` 的主流程固定为：
-
-1. 检查本机是否已安装 `codex`
-2. 检查 `codex` 是否满足最低支持版本门槛
-3. 发现候选 Codex 目录
-4. 当存在多个候选目录时，在 TTY 下交给用户选择，也允许自定义输入
-5. 读取目标目录下的 `config.toml`
-6. 从现有配置中发现 profile 列表
-7. 为每个准备纳入管理的 profile 构造 provider 草稿
-8. 对无法从现有状态可靠恢复的 `apiKey` 等关键字段，在交互模式下补问
-9. 检查目标目录是否已存在 `providers.json`
-10. 若已存在，在交互模式下让用户选择 `overwrite`、`merge` 或 `cancel`
-11. 写入或合并后的 `providers.json` 继续纳入备份与回滚模型
-12. 初始化成功后自动执行 `doctor`
-13. 输出当前 Codex 状态和后续建议命令
-
-#### 目录发现原则
-
-- 默认优先使用明确指定的 `--codex-dir`
-- 未显式指定时，可以发现多个候选目录
-- TTY 下多个候选目录必须选择，不自动猜测
-- 非交互下多个候选目录且未显式指定时，返回歧义错误
-- 任意时刻都允许用户手动输入自定义目录
+## Config Management 规则
 
-#### 凭据初始化原则
+### 受管与非受管
 
-因为 `config.toml` 不能可靠恢复所有 provider 的 `apiKey`，所以：
+- managed profile：被至少一个 provider 引用，允许被写命令同步维护
+- unmanaged profile：存在于 `config.toml`，但当前没有任何 provider 引用，默认只读展示
+- orphaned managed reference：`providers.json` 引用了 profile，但 `config.toml` 缺失对应 section，属于不一致状态
 
-- `setup` 不自动伪造或猜测 API key
-- 交互模式下可以补问缺失的 `apiKey`
-- 非交互模式下，如果缺失关键字段，应中止写入并返回明确错误
-- `0.0.4` 里程碑中不引入“缺 key 的正式 provider 记录”
+### 共享 profile
 
-#### Codex 版本门槛
+多个 provider 指向同一个 profile 在 `0.0.5` 继续合法：
 
-- `setup` 和 `doctor` 都应支持最低 Codex 版本检查
-- 最低版本门槛在 PRD 中定义为“必须存在的可配置门槛”
-- 具体版本号不在本文件中写死，由实现常量和发布说明控制
+- profile section 不归单个 provider 独占
+- 只有当没有任何 provider 引用时，才允许删除对应 section
+- `remove` / `edit` 不能因单个 provider 操作误删共享 profile
 
-### 2. CLI 契约收紧
+### TOML 处理原则
 
-在 `0.0.4` 里程碑中，需要把当前命令层从“已经可用”继续收紧到“更稳定可依赖”：
+- 不再以字符串匹配作为唯一修改策略
+- 对受管 section 的读取、创建、删除、字段更新必须可验证
+- 修改受管部分时，不应破坏非受管内容、顺序、空行和注释
 
-- 将参数错误与业务错误分离
-- 将环境问题与登录问题分离
-- 保持命令帮助、TTY 行为和 `--json` 行为一致
-- 让新增命令默认沿用当前 envelope、锁、备份和回滚模型
+## 新增命令
 
-### 3. 命令增强候选
+### `codexs config show`
 
-下面这些命令方向暂时也归入 `0.0.4` 里程碑候选池，用于指导下一阶段设计和实现优先级；它们仍然不是当前已完成范围。
+用途：
 
-### `codexs show <provider>`
+- 展示结构化 config 视图
+- 同时服务人类和 AI / 自动化读取
 
-目标：
-
-- 展示单个 provider 的完整详情
-- 既服务人类，也服务 AI 读取结构化 provider 数据
-
-定位：
-
-- 只读命令
-- 不进入备份与回滚流程
-
-### `codexs edit <provider>`
+输入：
 
-目标：
-
-- 修改单个 provider 的字段内容
-
-默认交互模型：
-
-- 显式参数优先
-- 允许使用 `--profile`、`--api-key`、`--base-url`、`--note`、`--tag`
-- TTY 下只补全缺失项或确认危险写入
-- 不以外部编辑器作为默认形态
+```bash
+codexs config show [profile] [--json] [--codex-dir <path>]
+```
 
-约束：
+最小返回要求：
 
-- 作为写命令，默认纳入备份、锁和失败回滚
+- `activeProfile`
+- `profiles`
+- `includedProfiles`
 
-### `codexs backups list`
+`profiles[]` 中每项至少包含：
 
-目标：
+- `name`
+- `managed`
+- `isActive`
+- `linkedProviders`
+- `managedFields`
+- `source`
 
-- 列出历史备份条目
-- 让用户和 AI 能显式选择恢复目标
+### `codexs config list-profiles`
 
-建议输出字段：
+用途：
 
-- `backupId`
-- `createdAt`
-- `reason`
-- `files`
-- `backupPath`
+- 列出当前 `config.toml` 中的 profile 视图
+- 明确显示 profile 与 provider 的关联关系
 
-备份 ID 规则：
+输入：
 
-- 默认以备份目录 basename 作为稳定 `backupId`
-- 例如 `20260511-221457-switch`
+```bash
+codexs config list-profiles [--json] [--codex-dir <path>]
+```
 
-### `codexs rollback <backup-id>`
+`data.profiles[]` 至少包含：
 
-目标：
+- `name`
+- `managed`
+- `isActive`
+- `linkedProviders`
+- `model`
 
-- 从“只支持 latest rollback”演进到“支持显式备份条目恢复”
+## 现有写命令升级
 
-约束：
+### `codexs add <provider>`
 
-- `rollback` 继续保留 latest 入口
-- `rollback <backup-id>` 作为增强能力引入
-- 指定备份不存在时必须返回专门错误码，而不是复用 generic rollback failure
+新增或锁定：
 
-### `codexs import --merge`
+- `--model <name>`
+- `--create-profile`
 
-目标：
+规则：
 
-- 在不整体替换当前 registry 的前提下导入 provider 清单
+- 当目标 profile 已存在时，允许直接建立映射
+- 当目标 profile 不存在时，只有显式传入 `--create-profile --model <name>` 才允许创建 section
+- 缺少最小受管字段时，返回 `MANAGED_PROFILE_FIELDS_MISSING`
 
-默认冲突策略：
+### `codexs edit <provider>`
 
-- 当导入文件和当前 registry 出现同名 provider 冲突时，以导入文件内容为准
-- 未冲突条目继续保留
-- 最终结果仍作为一次受管写操作进入备份与回滚流程
+新增或锁定：
 
-## `0.1.0` 远期目标与能力域
+- `--profile <name>`
+- `--model <name>`
+- `--create-profile`
 
-下面这些方向明确有价值，但当前不进入 `0.0.4` 里程碑，只作为继续走向 `0.1.0` 的远期能力域。
+规则：
 
-### 第三方 auth / extension 集成
+- `edit --profile <missing>` 且未传 `--create-profile` 时失败
+- `edit --profile <missing> --create-profile` 但未传 `--model` 时失败
+- 旧 profile 若仍被其他 provider 引用，则保留
+- 旧 profile 若已无引用且不是 active profile，则可以删除
+- 不隐式 rename 或 copy 旧 section 到新 profile
 
-示例方向：
+### `codexs remove <provider>`
 
-- 接入 Copilot auth
-- 在本地启动代理服务，使特定上游可在 Codex 中使用
-- 安装和管理第三方依赖
+新增或锁定：
 
-当前定位：
+- `--switch-to <profile>`
 
-- 作为单独能力域保留
-- 不在当前主 PRD 中锁定具体命令名和具体交互细节
-- 不进入 `0.1.0` 稳定主线的验收标准
+规则：
 
-### 交互式依赖安装
+- 删除 provider 记录后，若 profile 仍被其他 provider 引用，则保留 section
+- 若 profile 已无任何引用，则允许删除 section
+- 若该 profile 仍是当前 active 且最后一个引用，必须先 `switch` 或显式传 `--switch-to`
+- 不允许把 active profile 留成悬空状态
 
-未来如果引入：
+### `codexs switch <provider>`
 
-- 应采用交互式多选模式
-- 类似 skills 安装体验
-- 支持一次选择多个可选依赖
+- 继续只负责切换顶层 active profile
+- 不负责修复 profile section 内容
+- 执行前提仍是目标 profile section 必须存在且可识别
 
-但当前阶段仅记录方向，不进入正式规格。
+## `setup` 升级
 
-## 主题里程碑
+`setup` 在 `0.0.5` 需要与新一致性模型兼容：
 
-从 `0.0.3` 走向 `0.1.0`，建议按能力主题推进，而不是现在就预写死每个小版本号。
+- 支持扫描多个候选 Codex 目录
+- 多候选下，TTY 允许选择或手动输入目录
+- 非交互模式下，多候选且未显式传 `--codex-dir` 时返回 `CODEX_DIR_AMBIGUOUS`
+- 未发现任何候选目录时，TTY 可手动输入；非交互返回 `CODEX_DIR_NOT_FOUND`
+- 对从现有 `config.toml` 发现的 profile，允许 adopt 为受管 profile
+- 不制造新的 registry-config 不一致
 
-### 里程碑 A：`0.0.4` / Bootstrap / Setup
+## Write Result Contract
 
-目标：
+下列写命令成功时，建议在 JSON `data` 中稳定返回结果字段：
 
-- 完成 `setup` 规格与实现
-- 把首次初始化从“手工准备文件”提升到“命令引导完成”
-- 补齐 codex 安装和版本检查语义
+- `add`
+- `edit`
+- `remove`
+- `setup`
+- `import --merge`
 
-详细设计文档：
+建议字段：
 
-- [`../codex-switch-v0.0.4-design.md`](../codex-switch-v0.0.4-design.md)
+- `provider`
+- `profile`
+- `createdProfileSections`
+- `deletedProfileSections`
+- `keptSharedProfiles`
+- `switchedActiveProfile`
+- `adoptedProfiles`
+- `repairedProfiles`
 
-### 里程碑 B：Provider Registry Ergonomics
+## 事务与回滚
 
-目标：
+所有可能同时修改 `providers.json` 和 `config.toml` 的命令，默认遵守：
 
-- 增强 provider 的查看与编辑能力
-- 保持 `providers.json` 作为管理态事实源
-- 不默认把 runtime 文件反向回写到 registry
+- 单次锁
+- 单次备份
+- 单次失败整体回滚
 
-### 里程碑 C：Backup / Recovery Evolution
+不能接受的结果：
 
-目标：
+- `providers.json` 已更新但 `config.toml` 未同步
+- `config.toml` 已更新但 `providers.json` 未同步
+- active profile 指向已不存在的 section
 
-- 引入 `backups list`
-- 引入按 `backupId` 回滚
-- 为 `import --merge` 提供完整恢复语义
+## 迁移与诊断
 
-### 里程碑 D：Extensions / Auth Integration
+需要识别的历史状态：
 
-目标：
+- `providers.json` 可用，但 `config.toml` 中只有手工维护 profile
+- `providers.json` 引用了 profile，但对应 section 不存在
+- `config.toml` 存在历史 profile，但没有任何 provider 引用
+- 当前 active profile 指向 unmanaged profile
 
-- 评估第三方 auth 与本地代理集成
-- 评估交互式依赖安装与 extension 管理
-- 在不破坏主 CLI 契约的前提下扩展能力边界
+迁移原则：
 
-## 对实现的要求
+- 不要求用户先手工清空历史状态
+- `setup`、`import --merge`、`doctor`、`status` 必须能识别这些状态
+- 可安全 adopt 的 unmanaged profile，允许纳入受管
+- 对悬空引用或缺失 section，默认不静默修复，必须告知用户下一步建议
 
-从现在到 `0.1.0` 的所有新增能力，默认遵守：
+`doctor` / `status` 至少需要覆盖：
 
-- 命令帮助必须明确人类模式和 `--json` 模式行为
-- 非交互环境不允许依赖 prompt 才能完成核心自动化流程
-- 所有写命令默认走锁、备份、回滚
-- 所有新增错误码都必须语义清晰
-- 所有新增 JSON 返回都只能扩展 `data` 和 `warnings`
+- orphaned profile reference
+- unmanaged active profile
+- shared profile reference count
+- orphaned profile section
+- destructive remove blocked
 
-## `0.1.0` 目标完成标准
+## 验收标准
 
-达到下面这些条件时，可以认为 `0.1.0` 主线目标基本收敛：
+达到以下条件时，`0.0.5` 可以认为完成：
 
-- 用户可以通过 `setup` 完成首次初始化
-- provider registry 的查看、编辑、导入合并能力完整
-- 历史备份可被显式枚举和恢复
-- CLI 错误码不再存在明显语义复用问题
-- 主 CLI 契约对 AI 和脚本调用保持稳定
+- `config show` 在文本和 `--json` 模式下返回稳定结构
+- `config list-profiles` 能稳定展示 `managed`、`isActive`、`linkedProviders` 和 `model`
+- `add` / `edit` / `remove` 会同步维护 linked profile sections
+- 共享 profile 场景不会误删仍被引用的 section
+- active profile 不会因删除 provider 或迁移 profile 而悬空
+- 历史 `0.0.4` 状态可被识别，并通过 adopt / repair 路径收敛
+- 结构化 TOML 修改后，非受管内容、顺序和注释保持稳定
+- 双写失败时 `providers.json` 与 `config.toml` 能整体回滚
 
 ## 结论
 
-`0.1.0` 不是简单地把现有 MVP 重命名为稳定版，而是要在保持当前本地事务式切换模型不变的前提下，补齐初始化能力、增强 registry 操作、收紧错误契约，并为未来更大范围的 auth / extension 集成留出清晰边界。
+`0.0.5` 是 `codex-switch` 从 provider registry 工具走向 config-aware CLI 的第一步。它的重点不是扩张命令面，而是建立稳定的 config 管理、一致性事务和可诊断能力，为后续 `0.0.5 -> 0.1.0` 演进打基础。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minniexcode/codex-switch",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Local-first CLI for managing and switching Codex provider/profile configuration.",
   "license": "MIT",
   "type": "commonjs",