@minniexcode/codex-switch 0.0.4 → 0.0.6

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

@@ -1,77 +1,131 @@
-# codex-switch `0.1.0` 目标 PRD
+# codex-switch `0.0.6` PRD
 
 ## 文档信息
 
-- 状态：Target PRD
+- 状态：Active PRD
 - 产品名：`codex-switch`
 - CLI 命令名：`codexs`
-- 当前基线版本：`0.0.3`
-- 目标版本：`0.1.0`
-- 文档定位：从 `0.0.3` 走向 `0.1.0` 的目标规格与阶段性演进路线
+- 当前基线版本：`0.0.5`
+- 目标版本：`0.0.6`
+- 文档定位：定义 `0.0.5 -> 0.0.6` 的直接需求范围
 - 历史基线 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-prd-v0.1.0.md`
+- 本文档内容语义以当前 active PRD 为准，本次版本更新不处理文件重命名
+
 ## 一句话定义
 
-`codex-switch` 的 `0.1.0` 目标，是从一个已经验证可行的本地 provider/profile 管理 CLI，演进为一套对人类和 AI 都稳定、可初始化、可诊断、可恢复、可持续扩展的发布级命令体系。
+`0.0.6` 的目标不是继续扩张命令面，而是先修复 `0.0.5` 的功能稳定性问题，冻结当前 CLI 公共契约，并把实现从“单入口持续膨胀的命令调度器”收敛为适合继续扩展的模块化分层架构。
+
+## 当前基线：`0.0.5`
+
+当前已具备的命令面：
+
+- `config-show`
+- `config-list-profiles`
+- `list`
+- `show`
+- `current`
+- `status`
+- `setup`
+- `edit`
+- `add`
+- `switch`
+- `remove`
+- `import`
+- `export`
+- `backups`
+- `doctor`
+- `rollback`
 
-## 版本语义
+当前基线已具备的工程特征：
 
-- `0.0.x`：测试 / 验证阶段版本，用于收敛模型、命令面和失败语义
-- `0.1.0`：第一条稳定发布规格线，不要求当前立刻完成，但要求目标边界清晰
-- 当前仓库状态：`0.0.3` 已完成 MVP 核心命令面与交互式增强
+- `providers.json` 继续作为管理态单一事实源
+- `config.toml` 具备结构化读取与受管 section 写入能力
+- 写命令统一走锁、备份、失败回滚
+- `--json` 继续使用统一 envelope
+- CLI 帮助页已经具备稳定命令分组和文案基础
 
-这意味着本文件不是“下一版马上发布什么”的短期计划，而是 `0.0.3` 之后持续演进到 `0.1.0` 的目标 PRD。
+当前主要问题：
 
-## 当前基线：`0.0.3`
+- `0.0.5` 需要继续收敛边界行为和失败语义，提升已有功能的稳定性
+- `src/cli.ts` 已经承担过多命令分发、交互编排和参数补全逻辑
+- 当前四层结构仍然成立，但 CLI 入口和应用编排层需要进一步细化职责
+- 未来第三方 auth / 本地代理 / 外部依赖接入已具备现实需求，但当前扩展边界还不够明确
 
-当前已落地能力：
+## `0.0.6` 目标
 
-- `list` / `current` / `status`
-- `switch <provider>`
-- `import <file>` / `export <file>`
-- `add <provider>` / `remove <provider>`
-- `doctor`
-- `rollback`
+`0.0.6` 需要完成三件事：
 
-当前基线已经具备的工程特征：
+- 修复 `0.0.5` 命令行为中的稳定性问题，巩固已有能力
+- 重整 CLI 与应用层分层，解决 `cli.ts` 持续膨胀问题
+- 为未来第三方 auth / 本地 proxy / 外部 SDK 集成建立清晰边界，但本版不交付这些集成功能
 
-- 本地文件模型围绕 `~/.codex/`
-- `providers.json` 作为 management SSOT
-- `config.toml` 与 `auth.json` 作为 runtime state
-- 写命令统一走备份、锁和失败回滚
-- `--json` 输出固定 envelope
-- 高频写命令支持 TTY 渐进式交互
+## 范围
 
-当前基线仍然存在的边界：
+### In Scope
 
-- 缺少首次初始化 / bootstrap 命令
-- 只支持 latest rollback，不支持按备份条目恢复
-- provider 查看和编辑仍然偏基础
-- 错误码体系仍带有 MVP 阶段的复用痕迹
-- 尚未进入第三方 auth / extension 集成阶段
+- 现有命令面的稳定性修复与一致性收敛
+- 顶层 help 文案、命令分组、示例和危险提示的一致性
+- `--json` 契约、TTY 交互规则、非交互失败语义的一致性
+- `setup` / `add` / `edit` / `remove` / `import` / `export` / `switch` / `rollback` 的事务与恢复稳定性
+- `status` / `doctor` / `config-show` / `config-list-profiles` 的读取稳定性
+- CLI 入口再分层
+- 应用编排与运行时集成边界收敛
+- 为未来第三方 integration 预留明确架构边界
 
-## `0.1.0` 目标
+### Out of Scope
 
-`0.1.0` 需要同时满足以下目标：
+- 新增大型命令族
+- 真实 Copilot auth 登录接入
+- 本地代理服务启动、停止、守护和生命周期管理
+- 第三方 SDK 安装器或依赖下载体验
+- GUI / TUI / daemon 化
+- 把 `config.toml` 升级为通用配置编辑器
 
-- 保持当前 CLI 和 JSON 契约稳定
-- 让首次用户可以通过 `setup` 完成从环境检测到 registry 初始化的主流程
-- 让 provider registry 的查看、编辑、导入合并能力更完整
-- 让备份与回滚从“最新一次”演进到“显式备份条目”
-- 为未来 auth / extension 集成保留明确边界，而不把远期需求提前塞进稳定主线
+## 稳定公共契约
 
-## 长期演进守则
+### CLI 命令面
 
-如果继续扩展命令面，后续新增命令统一遵守下面三条：
+`0.0.6` 默认锁定当前 help 所表达的命令面与分组，不以“新增命令数量”作为版本目标。
 
-- 不破坏当前 JSON envelope
-- 不复用语义不匹配的错误码
-- 所有写命令默认纳入备份与回滚模型
+Usage 级别的公共入口保持：
 
-## 稳定公共契约
+```text
+codexs <command> [options]
+codexs help <command>
+```
+
+当前命令分组继续保留：
+
+- Read Commands
+- Change Commands
+- Diagnostics And Recovery
+
+当前命令名继续保留：
+
+- `config-show`
+- `config-list-profiles`
+- `list`
+- `show`
+- `current`
+- `status`
+- `setup`
+- `edit`
+- `add`
+- `switch`
+- `remove`
+- `import`
+- `export`
+- `backups`
+- `doctor`
+- `rollback`
 
 ### JSON Envelope
 
@@ -87,307 +141,177 @@
 }
 ```
 
-约束：
-
-- 顶层 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”作为正式稳定状态
-
-### 错误码演进原则
-
-保留现有领域错误码，并把错误码体系从 MVP 复用模式收紧到语义匹配模式。
-
-现有保留：
-
-- `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`
-
-后续新增命令应逐步引入更精确的错误码，而不是继续把无关问题塞进 `INVALID_IMPORT_FILE`。
-
-建议新增 / 预留：
-
-- `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`
-
-约束：
-
-- `CODEX_LOGIN_FAILED` 只表示登录失败
-- codex 缺失与版本过低必须使用环境类错误码
-- rollback 找不到目标备份时必须使用恢复类错误码
-
-## `0.0.4` 功能里程碑
-
-下面这些内容暂时作为 `0.0.4` 的功能里程碑。它们属于从 `0.0.3` 往 `0.1.0` 推进过程中的下一阶段，不代表已经锁定整个 `0.1.0` 的最终范围。
-
-### 1. `codexs setup`
-
-#### 目标
-
-提供首次初始化主流程，让用户从“本机已有 Codex 环境，但还没有 codex-switch 管理态文件”平滑进入受管状态。
-
-#### 目标命令
-
-```bash
-codexs setup
-```
-
-#### 行为顺序
-
-`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.toml` 不能可靠恢复所有 provider 的 `apiKey`，所以：
-
-- `setup` 不自动伪造或猜测 API key
-- 交互模式下可以补问缺失的 `apiKey`
-- 非交互模式下，如果缺失关键字段，应中止写入并返回明确错误
-- `0.0.4` 里程碑中不引入“缺 key 的正式 provider 记录”
-
-#### Codex 版本门槛
-
-- `setup` 和 `doctor` 都应支持最低 Codex 版本检查
-- 最低版本门槛在 PRD 中定义为“必须存在的可配置门槛”
-- 具体版本号不在本文件中写死，由实现常量和发布说明控制
-
-### 2. CLI 契约收紧
-
-在 `0.0.4` 里程碑中，需要把当前命令层从“已经可用”继续收紧到“更稳定可依赖”：
-
-- 将参数错误与业务错误分离
-- 将环境问题与登录问题分离
-- 保持命令帮助、TTY 行为和 `--json` 行为一致
-- 让新增命令默认沿用当前 envelope、锁、备份和回滚模型
-
-### 3. 命令增强候选
-
-下面这些命令方向暂时也归入 `0.0.4` 里程碑候选池，用于指导下一阶段设计和实现优先级；它们仍然不是当前已完成范围。
-
-### `codexs show <provider>`
-
-目标：
-
-- 展示单个 provider 的完整详情
-- 既服务人类，也服务 AI 读取结构化 provider 数据
-
-定位：
-
-- 只读命令
-- 不进入备份与回滚流程
-
-### `codexs edit <provider>`
-
-目标：
-
-- 修改单个 provider 的字段内容
+要求：
 
-默认交互模型：
+- 顶层 shape 不变
+- 新字段只追加到 `data` / `warnings`
+- 错误信息继续进入 `error`
+- 架构重构不得破坏已有自动化消费方式
 
-- 显式参数优先
-- 允许使用 `--profile`、`--api-key`、`--base-url`、`--note`、`--tag`
-- TTY 下只补全缺失项或确认危险写入
-- 不以外部编辑器作为默认形态
+### 交互规则
 
-约束：
+交互能力继续只是 TTY 中的人类增强层，不改变自动化契约：
 
-- 作为写命令，默认纳入备份、锁和失败回滚
+- `--json` 一律禁用交互
+- 非 TTY 一律不进入交互
+- 危险写命令继续要求显式确认或显式参数
+- 用户取消 prompt 时不得产生文件写入
 
-### `codexs backups list`
+## 数据与状态边界
 
-目标：
+### `providers.json`
 
-- 列出历史备份条目
-- 让用户和 AI 能显式选择恢复目标
+`providers.json` 继续是 provider registry 的单一事实源：
 
-建议输出字段：
+- `profile` 必填
+- `apiKey` 仍按完整 managed provider 处理
+- 不引入“半初始化 provider”作为稳定状态
 
-- `backupId`
-- `createdAt`
-- `reason`
-- `files`
-- `backupPath`
+### `config.toml`
 
-备份 ID 规则：
+到 `0.0.6` 为止，`config.toml` 的定位继续保持：
 
-- 默认以备份目录 basename 作为稳定 `backupId`
-- 例如 `20260511-221457-switch`
+- 顶层 active `profile`
+- 与 provider 关联的 `[profiles.<name>]`
+- 第一批受管字段：`model`、`model_provider`
+- 非受管内容允许存在，但不进入通用编辑器范围
 
-### `codexs rollback <backup-id>`
+### `auth.json`
 
-目标：
+`auth.json` 继续是认证态运行时文件：
 
-- 从“只支持 latest rollback”演进到“支持显式备份条目恢复”
+- 可以被 `switch`、`rollback`、备份系统纳入事务边界
+- 不是 provider registry 的事实源
+- 不在 `0.0.6` 中扩展为第三方 auth 统一数据库
 
-约束：
+## 架构目标边界
 
-- `rollback` 继续保留 latest 入口
-- `rollback <backup-id>` 作为增强能力引入
-- 指定备份不存在时必须返回专门错误码，而不是复用 generic rollback failure
+### 现状问题
 
-### `codexs import --merge`
+当前 `cli / app / domain / infra` 四层结构仍然是可用基线，但 `cli.ts` 已同时承担：
 
-目标：
+- 命令分发
+- 参数归一化
+- 交互分支判断
+- 渐进式补问
+- 输出路径拼装
 
-- 在不整体替换当前 registry 的前提下导入 provider 清单
+这会让后续每增加一个命令或 integration，都继续把复杂度堆回 CLI 入口。
 
-默认冲突策略：
+### `0.0.6` 架构调整目标
 
-- 当导入文件和当前 registry 出现同名 provider 冲突时，以导入文件内容为准
-- 未冲突条目继续保留
-- 最终结果仍作为一次受管写操作进入备份与回滚流程
+`0.0.6` 不要求彻底推翻现有分层，但要求把职责边界进一步显式化，至少收敛为下面几类模块能力：
 
-## `0.1.0` 远期目标与能力域
+- `Command Surface`
+  - 负责命令定义、help 文案、命令 key、参数规格、子命令分发
+- `Interaction Layer`
+  - 负责 TTY prompt、危险确认、渐进式补问、交互取消语义
+- `Application Use Cases`
+  - 负责单命令业务编排、跨仓储事务边界、结果契约组装
+- `Domain Policies`
+  - 负责 provider/profile/config consistency 规则、错误码、纯规则判断
+- `Storage Repositories`
+  - 负责 `providers.json`、`config.toml`、backups 的文件访问和持久化
+- `Runtime Integrations`
+  - 负责 `codex` CLI 调用，以及未来第三方 auth adapter、本地 proxy runtime、外部 SDK 封装
 
-下面这些方向明确有价值，但当前不进入 `0.0.4` 里程碑，只作为继续走向 `0.1.0` 的远期能力域。
+### 架构约束
 
-### 第三方 auth / extension 集成
+`0.0.6` 需要明确以下约束：
 
-示例方向：
+- 不把第三方 SDK 调用直接塞进 CLI 入口
+- 不把 prompt 逻辑继续散落到每个命令分支内部
+- 不让 `app` 层直接依赖终端输出细节
+- 不让运行时集成逻辑反向污染领域规则
+- 不因未来接入 Copilot 或其他 provider，就改变本地事务与回滚的安全语义
 
-- 接入 Copilot auth
-- 在本地启动代理服务，使特定上游可在 Codex 中使用
-- 安装和管理第三方依赖
+## `0.0.6` 稳定性要求
 
-当前定位：
+### 命令行为一致性
 
-- 作为单独能力域保留
-- 不在当前主 PRD 中锁定具体命令名和具体交互细节
-- 不进入 `0.1.0` 稳定主线的验收标准
+现有命令在 `0.0.6` 需要重点收敛：
 
-### 交互式依赖安装
+- help 文案与真实命令行为一致
+- 默认文本输出与 `--json` 输出语义一致
+- TTY 与非交互模式下的失败路径可预测
+- 危险命令的确认规则一致
+- 同一类错误优先映射到同一类错误码
 
-未来如果引入：
+### 写命令安全语义
 
-- 应采用交互式多选模式
-- 类似 skills 安装体验
-- 支持一次选择多个可选依赖
+所有会修改 `providers.json`、`config.toml`、`auth.json` 的命令继续默认遵守：
 
-但当前阶段仅记录方向，不进入正式规格。
+- 单次锁
+- 单次备份
+- 单次失败整体回滚
 
-## 主题里程碑
+不能接受的结果：
 
-从 `0.0.3` 走向 `0.1.0`，建议按能力主题推进，而不是现在就预写死每个小版本号。
+- `providers.json` 已更新但 `config.toml` 未同步
+- `config.toml` 已更新但 `providers.json` 未同步
+- `auth.json` 或 active profile 因失败留在半切换状态
 
-### 里程碑 A：`0.0.4` / Bootstrap / Setup
+### 读取稳定性
 
-目标：
+读取命令在 `0.0.6` 至少需要满足：
 
-- 完成 `setup` 规格与实现
-- 把首次初始化从“手工准备文件”提升到“命令引导完成”
-- 补齐 codex 安装和版本检查语义
+- 不因历史 workspace 或边缘状态轻易崩溃
+- `status` 与 `doctor` 的诊断信号保持一致语义
+- `config-show` 与 `config-list-profiles` 输出结构稳定
+- 对缺失文件、解析失败和不一致状态给出可预测错误或警告
 
-详细设计文档：
+## Future-Ready Integration 边界
 
-- [`../codex-switch-v0.0.4-design.md`](../codex-switch-v0.0.4-design.md)
+### 为什么 `0.0.6` 要预留这条线
 
-### 里程碑 B：Provider Registry Ergonomics
+未来存在明确扩展需求：
 
-目标：
+- 通过第三方 auth 获取认证态
+- 借助本地代理使特定上游可在 Codex 中使用
+- 接入外部 SDK，例如 GitHub Copilot 相关能力
 
-- 增强 provider 的查看与编辑能力
-- 保持 `providers.json` 作为管理态事实源
-- 不默认把 runtime 文件反向回写到 registry
+如果继续沿用当前“命令直接长在 `cli.ts` 上”的方式，后续集成会快速把架构拖回高耦合状态。
 
-### 里程碑 C：Backup / Recovery Evolution
+### `0.0.6` 的预留目标
 
-目标：
+本版只要求建立边界，不要求交付真实功能：
 
-- 引入 `backups list`
-- 引入按 `backupId` 回滚
-- 为 `import --merge` 提供完整恢复语义
+- 允许未来把第三方 auth 封装为独立 integration 模块
+- 允许未来把本地 proxy runtime 封装为独立运行时组件
+- 允许未来把外部依赖探测、可用性检查、错误语义收敛到 runtime integration 层
+- 不在本版锁定具体命令名、交互细节或 SDK 选型细节
 
-### 里程碑 D：Extensions / Auth Integration
+### Copilot 作为代表性场景
 
-目标：
+GitHub Copilot 相关 auth / SDK / 本地代理能力，在 `0.0.6` 里的定位是：
 
-- 评估第三方 auth 与本地代理集成
-- 评估交互式依赖安装与 extension 管理
-- 在不破坏主 CLI 契约的前提下扩展能力边界
+- 作为未来架构设计的代表性输入
+- 用于验证 `Runtime Integrations` 分层是否足够清晰
+- 不作为 `0.0.6` 必须实现的命令需求
 
 ## 对实现的要求
 
-从现在到 `0.1.0` 的所有新增能力，默认遵守：
+从 `0.0.5` 到 `0.0.6` 的改造，默认遵守：
 
-- 命令帮助必须明确人类模式和 `--json` 模式行为
-- 非交互环境不允许依赖 prompt 才能完成核心自动化流程
-- 所有写命令默认走锁、备份、回滚
-- 所有新增错误码都必须语义清晰
-- 所有新增 JSON 返回都只能扩展 `data` 和 `warnings`
+- 不破坏现有命令名
+- 不破坏统一 JSON envelope
+- 不破坏备份、回滚、锁模型
+- 不引入只能靠交互完成的核心流程
+- 不把未来第三方集成耦合进当前 provider/config 领域规则
+- 允许内部文件和模块重组，但外部 CLI 契约保持稳定
 
-## `0.1.0` 目标完成标准
+## 验收标准
 
-达到下面这些条件时，可以认为 `0.1.0` 主线目标基本收敛：
+达到以下条件时，`0.0.6` 可以认为完成：
 
-- 用户可以通过 `setup` 完成首次初始化
-- provider registry 的查看、编辑、导入合并能力完整
-- 历史备份可被显式枚举和恢复
-- CLI 错误码不再存在明显语义复用问题
-- 主 CLI 契约对 AI 和脚本调用保持稳定
+- 当前 help 文案与命令行为、参数、危险提示基本一致
+- 现有命令在 TTY / 非交互 / `--json` 模式下行为稳定
+- 读取命令对历史状态和异常状态的处理更稳，不产生明显回归
+- 写命令继续满足锁、备份、失败回滚语义
+- `cli.ts` 不再承担持续膨胀的主调度与交互编排复杂度
+- 应用编排、交互层、运行时集成边界比 `0.0.5` 更清晰
+- 为未来第三方 auth / 本地 proxy / SDK 接入预留了清楚但非侵入式的扩展边界
 
 ## 结论
 
-`0.1.0` 不是简单地把现有 MVP 重命名为稳定版，而是要在保持当前本地事务式切换模型不变的前提下，补齐初始化能力、增强 registry 操作、收紧错误契约，并为未来更大范围的 auth / extension 集成留出清晰边界。
+`0.0.6` 是一个修复型版本，但它不是“只修 bug 不动结构”的保守补丁版。它的真正目标，是在不破坏当前 CLI 公共契约的前提下，把 `0.0.5` 已经长出来的命令面和事务能力稳住，并把代码结构调整到足以支撑下一阶段 integration-ready 演进的状态。

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

@@ -191,7 +191,7 @@ MVP 固定使用以下结构：
   - 用于执行 `codex login --with-api-key`
 - `baseUrl`
   - 选填
-  - v1 允许存储，但不要求回写到 `config.toml`
+  - v1 允许存储在 `providers.json`，但不要求回写到 `config.toml`
 - `note`
   - 选填
   - 面向人类和 AI 的说明字段

package/docs/cli-usage.md

@@ -226,6 +226,7 @@ codexs setup --merge --codex-dir ./.tmp-codex
 行为说明：
 
 - 读取 `config.toml` 中已有 profile
+- 仅 adopt 已具备 `model`、`model_provider` 且能解析到匹配 `model_providers.*.base_url` 的 profile
 - 收集每个 profile 对应的 provider 记录
 - 在受管备份流程下写入 `providers.json`
 - 成功后会自动运行一次 `doctor`
@@ -262,7 +263,7 @@ codexs add
 - `provider`：provider 名称，也是后续 `switch/show/edit/remove` 的标识
 - `--profile`：写入到 `config.toml` 的 profile 名称
 - `--api-key`：provider API key
-- `--base-url`：可选的 API base URL
+- `--base-url`：可选的 provider 元数据，不会写回 `[profiles.*]`
 - `--note`：备注
 - `--tag`：标签，可重复传多次