@yhong91/cpac 0.1.24 → 0.1.26

package/README.md

@@ -47,9 +47,9 @@ cpac uninstall --target codex          # 字节级恢复原配置
 cpac claude                            # Claude Code 走 CPA
 cpac opencode                          # opencode 走 CPA（模型选 cpac/<模型名>）
 
-# 5. 可选：Claude 模型槽位覆盖（持久缓存；默认自动选择已覆盖多数场景，见下文）
-cpac claude-models                     # 查看当前覆盖
-cpac claude-models --haiku             # 下拉选择 haiku 槽模型
+# 5. 可选：Agent 配置向导与模型选择
+cpac codex setup                       # 进入 Codex 配置向导（Subagent 模型多选、最大上下文、Multi-Agent V2）
+cpac claude setup                      # 进入 Claude Code 模型向导（Sonnet、Haiku、Opus 槽位选择）
 
 # 6. 升级（装上新版本后自动 sync 已接入的 agent）
 cpac upgrade
@@ -59,7 +59,7 @@ cpac upgrade
 
 ## Agent 自动化安装指南
 
-本节面向 AI agent：按顺序执行即可完成安装与配置，**全程无交互**。注意：`--v2_models` 复选框和 `claude-models` 不带值的下拉选择是 TTY-only，agent 必须走下方直接写配置 JSON 的路径。
+本节面向 AI agent：按顺序执行即可完成安装与配置，**全程无交互**。注意：`cpac codex --config` 和 `cpac claude --config` 的交互向导是 TTY-only，agent 必须走下方直接写配置 JSON 的路径。
 
 1. **检查前置**：`node --version` ≥ 20；确认用户需要哪些 agent（`codex`/`claude`/`pi`/`kimi`/`opencode` 在 PATH 上）。向用户索取 CPA API key。
 
@@ -72,7 +72,7 @@ source ~/.zshrc
 cpac status   # 验证：CPA_API_KEY 应显示 configured
 ```
 
-3. **写入模型配置**（创建或合并 `~/.config/cpac/config.json`，已有键保留）：
+1. **写入模型配置**（创建或合并 `~/.config/cpac/config.json`，已有键保留）：
 
 ```json
 {
@@ -80,20 +80,23 @@ cpac status   # 验证：CPA_API_KEY 应显示 configured
 }
 ```
 
-   Claude 槽位（opus/sonnet/haiku）通常不用配：cpac 启动时自动选择——同家族 claude 模型优先，否则 gemini → grok → luna → 目录第一个；opus 无匹配则不设。这个链条在常见目录上正好给出理想结果：sonnet 落在 claude-sonnet-*（它同时充当 Auto mode 分类器的替身，避免分类请求失败后回退到昂贵的会话主模型），haiku 落在快的 gemini flash。只有目录奇怪时才用 `cpac claude-models --opus/--sonnet/--haiku <模型>` 显式覆盖。codex spawn subagent 取三个 GPT + gemini + grok 五席（顺序即优先级，Codex 只广告 catalog 前 5）。候选替换：`mimo-v2.5`（haiku）、`grok-4.5`（haiku）。若上述 slug 不在目录中（`curl -s -H "Authorization: Bearer $CPA_API_KEY" "$CPA_BASE_URL/v1/models"` 可查），按家族就近替换。分类器机制细节见 [docs/claude-auto-mode-classifier.md](docs/claude-auto-mode-classifier.md)。
+   Claude 槽位（opus/sonnet/haiku）通常不用配：cpac 启动时自动选择——同家族 claude 模型优先，否则 gemini → grok → luna → 目录第一个；opus 无匹配则不设。这个链条在常见目录上正好给出理想结果：sonnet 落在 claude-sonnet-*（它同时充当 Auto mode 分类器的替身，避免分类请求失败后回退到昂贵的会话主模型），haiku 落在快的 gemini flash。只有目录奇怪时才用 `cpac claude setup` 交互式配置。codex spawn subagent 取三个 GPT + gemini + grok 五席（顺序即优先级，Codex 只广告 catalog 前 5），可通过 `cpac codex setup` 交互式配置。候选替换：`mimo-v2.5`（haiku）、`grok-4.5`（haiku）。若上述 slug 不在目录中（`curl -s -H "Authorization: Bearer $CPA_API_KEY" "$CPA_BASE_URL/v1/models"` 可查），按家族就近替换。分类器机制细节见 [docs/claude-auto-mode-classifier.md](docs/claude-auto-mode-classifier.md)。
 
-4. **持久注入**（只对检测到的目标；codex 会应用步骤 3 的 spawn_models）：
+1. **持久注入**（只对检测到的目标；codex 会应用步骤 3 的 spawn_models）：
 
 ```bash
 cpac install --all
 cpac status   # 验证：各 target 显示 ready/injected
 ```
 
-5. **临时接管类 agent 无需安装**，直接告知用户用 `cpac claude` / `cpac opencode` 启动（步骤 3 的 claude_models 自动生效）。
+1. **统一启动与配置**：
+   - 启动：`cpac <codex|claude|kimi|grok|pi|opencode> [args...]`（所有原生参数如 `-c` 等原样透明传递）
+   - 配置：`cpac <codex|claude> setup`（交互式配置模型与特性）
+   - 还原：`cpac <agent> clear`（还原或重置配置）
 
-6. **已安装后升级**：npm 发布新版本后，等 publish 成功再执行 `cpac upgrade`。它会按需 `npm install -g`，再对已接入的 Codex / Pi / Kimi 做 `sync`。不要拆成 `npm install -g @yhong91/cpac` 再手动 `cpac sync`。只刷新配置、不升 CLI 时才用 `cpac sync`。
+2. **已安装后升级**：npm 发布新版本后，等 publish 成功再执行 `cpac upgrade`。它会按需 `npm install -g`，再对已接入的 Codex / Pi / Kimi / Grok 做 `sync`。不要拆成 `npm install -g @yhong91/cpac` 再手动 `cpac sync`。只刷新配置、不升 CLI 时才用 `cpac sync`。
 
-失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac uninstall --target <id>` 恢复原配置。
+失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac <agent> clear` 或 `cpac restore --target <id>` 恢复原配置。
 
 ## 首次引导
 
@@ -179,34 +182,20 @@ cpac version
 
 ### Claude Code
 
-通过 CPA 启动 Claude Code，后续参数原样传递：
+通过 CPA 启动 Claude Code，后续所有原生参数原样传递（如 `-c` 继续会话、`--model` 等）：
 
 ```bash
 cpac claude
+cpac claude -c                         # 继续上一次对话（原生 -c 原样直通）
 cpac claude --model claude-sonnet-4-5
 cpac claude -- -p "检查当前项目"
 ```
 
-`cpac claude` 会在本地起一个临时 loopback 代理，并为 Claude Code 子进程设置：
+#### 配置与清除
 
-```text
-ANTHROPIC_BASE_URL=http://127.0.0.1:<临时端口>
-ANTHROPIC_AUTH_TOKEN=<CPA_API_KEY>
-CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
-CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1
-```
-
-同时清除可能覆盖网关选择的 `ANTHROPIC_API_KEY` 和 Claude Code 云 provider 环境变量。它不会修改 `~/.claude/`，并原样返回 Claude Code 的退出码。
-
-代理开启 Claude Code 的 gateway model discovery：`/model` 选择器会列出 CPA 目录里的全部模型。claude 系模型直接使用原 id；其它模型以 `claude-cpac--<模型名>` 别名出现（例如 `claude-cpac--gpt-5.6-sol`），请求发出时由代理还原为真实模型名。
-
-启动时还会把模型槽位（`ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL` 及 `ANTHROPIC_SMALL_FAST_MODEL`）指向目录里的模型，避免 haiku/subagent 任务打到网关不认识的默认 id。默认自动选择（claude 系优先：按家族名匹配 opus/sonnet/haiku，否则最大窗口给 opus/sonnet、最小窗口给 haiku），可用命令覆盖：
-
-```sh
-cpac claude-models                                            # 查看当前覆盖
-cpac claude-models --opus claude-opus-4-8 --haiku glm-5.3     # 设置/合并
-cpac claude-models --haiku                                    # 不带值：arrow-key 下拉选择
-cpac claude-models --reset                                    # 恢复自动选择
+```bash
+cpac claude setup                      # 交互式依次配置 Sonnet / Haiku / Opus
+cpac claude clear                      # 重置所有覆盖，恢复自动选择
 ```
 
 未设置的槽位启动时自动选择：claude 池内同家族模型优先，否则按 gemini → grok → luna → 目录第一个回退；opus 无匹配则不设。
@@ -223,33 +212,25 @@ Claude Code 的发现协议不携带 context 信息，claude 前缀的未知模
 
 ### Codex
 
-注入 CPA 模型目录：
+启动 Codex，后续所有原生参数原样传递（如 `-c` 动态覆盖配置、`exec` 等）：
 
 ```bash
-cpac inject [--v2_off] [--v2_models] [--max_context] [--config PATH]
+cpac codex                             # 自动确保注入和代理后拉起 Codex
+cpac codex -c model="gpt-5"            # 动态覆盖 Codex 配置（原生 -c 原样直通）
+cpac codex exec "帮我写一个测试"
 ```
 
-查看状态：
+#### 配置与清除
 
 ```bash
-cpac status
+cpac codex setup                       # 交互式配置 Subagent 候选模型、最大上下文和 Multi-Agent V2
+cpac codex clear                       # 还原 Codex 原生配置并关闭代理
 ```
 
-`status` 列出所有支持的 agent 及当前状态：
-
-```text
-codex: injected proxy=http://127.0.0.1:10101/v1 sha256=...
-claude: ready
-pi: ready
-```
-
-- **codex**：`native`（未注入）、`injected`（已注入，附代理地址和配置摘要）、`injected (loopback proxy stopped)` 或 `injected (config missing)`
-- **claude**：`ready`（密钥已配置）或 `not configured`
-- **pi**：`ready`（密钥已配置）或 `not configured`
-
-恢复注入前的原配置：
+#### 传统注入命令
 
 ```bash
+cpac inject [--v2_off] [--v2_models] [--max_context] [--config PATH]
 cpac restore
 ```