@yhong91/cpac 0.1.13 → 0.1.15

package/README.md

@@ -10,7 +10,7 @@ CPAC 将 Codex 和 Claude Code 接入远端 CLIProxyAPI（CPA）：
 ## 要求
 
 - [Node.js](https://nodejs.org/) 20 或更新版本（npm 随 Node 安装）
-- 已安装需要使用的 agent：`codex` 或 `claude`
+- 已安装需要使用的 agent：`codex`、`claude`、`pi`、`kimi` 或 `opencode`
 - 有权访问的 CPA API key
 
 ## 安装
@@ -22,15 +22,77 @@ npm install -g @yhong91/cpac
 cpac
 ```
 
-开发目录中安装：
+## 快速上手
 
 ```bash
-npm install
-npm run build
-npm install -g .
+# 1. 安装
+npm install -g @yhong91/cpac
+
+# 2. 配置密钥：无参数运行进入交互引导，自动写入 shell 启动文件；
+#    也可手动写入（zsh 示例）：
 cpac
+echo 'export CPA_API_KEY="<你的key>"' >> ~/.zshrc && source ~/.zshrc
+
+# 3. 验证
+cpac status
+
+# 4a. 持久注入（长期生效，写入 agent 配置，可完整恢复）
+cpac install --all                     # 注入所有检测到的目标（codex/pi/kimi）
+cpac install --target codex            # 只注入 Codex（默认开启 multi-agent v2）
+cpac install --target codex --v2_models  # 先多选 spawn_agent 模型再注入
+cpac uninstall --target codex          # 字节级恢复原配置
+
+# 4b. 临时接管（退出无痕，不写任何配置文件）
+cpac claude                            # Claude Code 走 CPA
+cpac opencode                          # opencode 走 CPA（模型选 cpac/<模型名>）
+
+# 5. 可选：Claude 模型槽位覆盖（持久缓存；默认自动选择已覆盖多数场景，见下文）
+cpac claude-models                     # 查看当前覆盖
+cpac claude-models --haiku             # 下拉选择 haiku 槽模型
+
+# 6. 升级
+cpac upgrade --check
+npm install -g @yhong91/cpac@latest
+```
+
+各命令的完整参数与行为见下方对应章节。
+
+## Agent 自动化安装指南
+
+本节面向 AI agent：按顺序执行即可完成安装与配置，**全程无交互**。注意：`--v2_models` 复选框和 `claude-models` 不带值的下拉选择是 TTY-only，agent 必须走下方直接写配置 JSON 的路径。
+
+1. **检查前置**：`node --version` ≥ 20；确认用户需要哪些 agent（`codex`/`claude`/`pi`/`kimi`/`opencode` 在 PATH 上）。向用户索取 CPA API key。
+
+2. **安装与密钥**：
+
+```bash
+npm install -g @yhong91/cpac
+echo 'export CPA_API_KEY="<key>"' >> ~/.zshrc   # bash 用 ~/.bash_profile 或 ~/.bashrc
+source ~/.zshrc
+cpac status   # 验证：CPA_API_KEY 应显示 configured
+```
+
+3. **写入模型配置**（创建或合并 `~/.config/cpac/config.json`，已有键保留）：
+
+```json
+{
+  "spawn_models": ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gemini-3.7-flash-high", "grok-4.6"]
+}
 ```
 
+   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)。
+
+4. **持久注入**（只对检测到的目标；codex 会应用步骤 3 的 spawn_models）：
+
+```bash
+cpac install --all
+cpac status   # 验证：各 target 显示 ready/injected
+```
+
+5. **临时接管类 agent 无需安装**，直接告知用户用 `cpac claude` / `cpac opencode` 启动（步骤 3 的 claude_models 自动生效）。
+
+失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac uninstall --target <id>` 恢复原配置。
+
 ## 首次引导
 
 无参数运行 `cpac` 会显示当前 CPA、密钥状态和可用命令：
@@ -140,11 +202,14 @@ CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1
 cpac claude-models                                            # 查看当前覆盖
 cpac claude-models --opus claude-opus-4-8 --haiku glm-5.3     # 设置/合并
 cpac claude-models --haiku                                    # 不带值：arrow-key 下拉选择
-cpac claude-models --classifier claude-sonnet-4-6             # Auto mode 审批分类器模型
 cpac claude-models --reset                                    # 恢复自动选择
 ```
 
-所有设定写入配置文件持久缓存，每次 `cpac claude` 启动自动生效。`--classifier` 对应 `CLAUDE_CODE_AUTO_MODE_MODEL`（Auto mode 的审批分类器，默认跟随 Claude Code 内置选择）；不设置则不注入。
+未设置的槽位启动时自动选择：claude 池内同家族模型优先，否则按 gemini → grok → luna → 目录第一个回退；opus 无匹配则不设。
+
+所有设定写入配置文件持久缓存，每次 `cpac claude` 启动自动生效。
+
+`--opus` / `--sonnet` / `--haiku` 对应 `ANTHROPIC_DEFAULT_*_MODEL`（haiku 同时写入 `ANTHROPIC_SMALL_FAST_MODEL`）。旧版的 `--classifier` 已移除：`CLAUDE_CODE_AUTO_MODE_MODEL` 在 Claude Code 2.1.224 上不被读取，Auto mode 分类器由官方自选（默认 Sonnet 5）；现版本唯一能影响分类器替身的旋钮是 `--sonnet`（副作用：同时改 `sonnet` 别名）。完整选择顺序、回退规则与出处见 [docs/claude-auto-mode-classifier.md](docs/claude-auto-mode-classifier.md)。
 
 你自己 export 同名环境变量时以你为准。
 
@@ -319,40 +384,3 @@ export CPAC_CONFIG=/path/to/cpac.json
 - shell 启动文件和 Codex 配置均通过同目录临时文件原子替换。
 - CPA 请求失败、catalog 无效或 key 缺失时，首次注入不会修改 Codex 配置。
 - `restore` 只删除 CPAC 自有的 state、backup 和 catalog，不删除 `state_dir` 中的其他文件。
-
-## 开发
-
-```bash
-npm install
-npm test
-npm run check
-npm run build
-npm run check:pi
-npm run pack:check
-```
-
-发布包的 CLI 入口为 `dist/cpac.js`。`dist/` 是构建产物，不应手工编辑。
-
-## npm 发布
-
-`.github/workflows/publish.yml` 在推送到 `main` 或手动触发时执行测试、类型检查、构建并发布到 npm。发布前会确认 `package.json` 中的版本尚未存在；因此每次计划发布的 push 都必须先提升版本。普通 PR 仅运行 CI。
-
-首次发布前：
-
-1. 在 npm 创建账号并启用 2FA。
-2. 因为新包尚不存在，先创建允许 publish 且可绕过 2FA 的 npm granular access token，在仓库的 **Settings → Secrets and variables → Actions** 添加 `NPM_TOKEN`，然后手动运行 `Publish to npm` workflow 完成首次发布。
-3. 首次发布后，在 npm 包 `@yhong91/cpac` 的设置中添加 Trusted Publisher：GitHub 用户 `yhong91`、仓库 `cpac`、workflow 文件 `publish.yml`，允许 `npm publish`。
-4. Trusted Publisher 生效后删除 GitHub 的 `NPM_TOKEN`；后续 workflow 自动使用 OIDC。
-
-正常发布新版本：
-
-```bash
-npm version patch --no-git-tag-version   # 或 minor / major
-git add package.json package-lock.json
-git commit -m 'Release 0.1.1'
-git push
-```
-
-也可以手工修改并提交两个版本文件。push 到 `main` 后 Action 自动发布；若忘记提升版本，发布 workflow 会明确失败，不会覆盖 npm 已发布版本。
-
-仓库当前为 private，因此 npm Trusted Publishing 可以使用，但 npm 不会为发布包生成 provenance。

package/cpac.example.json

@@ -5,8 +5,7 @@
   "claude_models": {
     "opus": "claude-opus-4-8",
     "sonnet": "claude-sonnet-4-6",
-    "haiku": "glm-5.3",
-    "classifier": "claude-sonnet-4-6"
+    "haiku": "glm-5.3"
   },
   "spawn_models": ["gpt-5.5", "claude-opus-4-8"]
 }

package/dist/cpac.js

@@ -25,7 +25,7 @@ const CONFIG_KEYS = new Set([
 // Codex advertises only the first 5 picker-visible catalog models as
 // spawn_agent overrides (codex-rs MAX_SPAWN_AGENT_MODEL_OVERRIDES).
 const MAX_SPAWN_MODELS = 5;
-const CLAUDE_SLOT_KEYS = ["opus", "sonnet", "haiku", "classifier"];
+const CLAUDE_SLOT_KEYS = ["opus", "sonnet", "haiku"];
 const REQUIRED_STATE_KEYS = new Set([
     "config_path",
     "config_existed",
@@ -131,7 +131,9 @@ export function loadConfig(path, useDefaultsIfMissing = false) {
         if (!objectValue(claudeModelsRaw))
             throw new CPACError("claude_models must be an object");
         const unknownSlots = Object.keys(claudeModelsRaw)
-            .filter((key) => !CLAUDE_SLOT_KEYS.includes(key))
+            // "classifier" was a shipped slot; its env var turned out unread by
+            // Claude Code, so the key is dropped on load instead of erroring.
+            .filter((key) => key !== "classifier" && !CLAUDE_SLOT_KEYS.includes(key))
             .sort();
         if (unknownSlots.length)
             throw new CPACError(`unknown claude_models slots: ${unknownSlots.join(", ")}`);
@@ -778,25 +780,29 @@ function shouldMarkOneMillion(id, window, compactWindow) {
         return true;
     return compactWindow !== undefined && window > 200_000 && window >= compactWindow;
 }
-// Auto tier defaults: prefer claude-family models; within the pool match by
-// family keyword first (opus/sonnet/haiku) so equal context windows don't
-// collapse every slot onto the first catalog entry, then fall back to
-// biggest-window (opus/sonnet) and smallest-window (haiku).
+// Auto tier defaults. Within the claude-family pool (whole catalog when no
+// claude model exists), opus matches its family name or stays unset; sonnet
+// and haiku match their family name first, then fall back through
+// gemini → grok → luna → first catalog row.
 function defaultClaudeSlots(models) {
     if (!models.length)
         return undefined;
     const claudeRows = models.filter((model) => model.id.startsWith("claude"));
     const pool = claudeRows.length ? claudeRows : models;
-    const biggest = [...pool].sort((a, b) => b.window - a.window)[0];
-    const smallest = pool
-        .filter((model) => model.window > 0)
-        .sort((a, b) => a.window - b.window)[0];
     const family = (keyword) => pool.find((model) => model.id.includes(keyword));
-    return {
-        opus: (family("opus") ?? biggest).id,
-        sonnet: (family("sonnet") ?? biggest).id,
-        haiku: (family("haiku") ?? smallest ?? biggest).id,
+    const fallback = (keyword) => family(keyword) ??
+        models.find((model) => model.id.includes("gemini")) ??
+        models.find((model) => model.id.includes("grok")) ??
+        models.find((model) => model.id.includes("luna")) ??
+        models[0];
+    const slots = {
+        sonnet: fallback("sonnet").id,
+        haiku: fallback("haiku").id,
     };
+    const opus = family("opus");
+    if (opus)
+        slots.opus = opus.id;
+    return slots;
 }
 // Resolve the tier-model env values: config overrides win over catalog
 // defaults; values are [1m]-marked per the predicate above (Claude Code
@@ -810,11 +816,14 @@ export function claudeTierSlots(override, models, compactWindow) {
         shouldMarkOneMillion(id, windowById.get(id) ?? 0, compactWindow)
         ? `${id}[1m]`
         : id;
-    return {
-        opus: mark(override?.opus ?? defaults.opus),
+    const slots = {
         sonnet: mark(override?.sonnet ?? defaults.sonnet),
         haiku: mark(override?.haiku ?? defaults.haiku),
     };
+    const opus = override?.opus ?? defaults.opus;
+    if (opus)
+        slots.opus = mark(opus);
+    return slots;
 }
 function catalogModelRows(document) {
     if (!objectValue(document))
@@ -1590,14 +1599,14 @@ export async function runClaude(config, args, executable = "claude") {
     };
     if (slots) {
         // Route haiku/subagent tier traffic at catalog models instead of the
-        // stock claude-haiku-* ids the gateway does not carry.
-        setSlot("ANTHROPIC_DEFAULT_OPUS_MODEL", slots.opus);
+        // stock claude-haiku-* ids the gateway does not carry. The opus slot
+        // stays unset when the catalog has no opus-family model.
+        if (slots.opus)
+            setSlot("ANTHROPIC_DEFAULT_OPUS_MODEL", slots.opus);
         setSlot("ANTHROPIC_DEFAULT_SONNET_MODEL", slots.sonnet);
         setSlot("ANTHROPIC_DEFAULT_HAIKU_MODEL", slots.haiku);
         setSlot("ANTHROPIC_SMALL_FAST_MODEL", slots.haiku);
     }
-    if (config.claude_models?.classifier)
-        setSlot("CLAUDE_CODE_AUTO_MODE_MODEL", config.claude_models.classifier);
     delete env.ANTHROPIC_API_KEY;
     delete env.CLAUDE_CODE_USE_ANTHROPIC_AWS;
     delete env.CLAUDE_CODE_USE_BEDROCK;
@@ -1994,7 +2003,7 @@ function usage() {
         "       cpac proxy [--config PATH]",
         "       cpac claude [--config PATH] [--] [claude args...]",
         "       cpac opencode [--config PATH] [--] [opencode args...]",
-        "       cpac claude-models [--opus [M]] [--sonnet [M]] [--haiku [M]] [--classifier [M]] [--reset] [--config PATH]",
+        "       cpac claude-models [--opus [M]] [--sonnet [M]] [--haiku [M]] [--reset] [--config PATH]",
         "       cpac pi <install|uninstall|status> [--config PATH]",
         "       cpac kimi <install|uninstall|status> [--config PATH]",
         "       cpac detect [--json] [--home PATH]",
@@ -2089,7 +2098,7 @@ function parseArgs(args) {
     if (args[0] === "claude-models") {
         if (args.includes("-h") || args.includes("--help")) {
             console.log([
-                "Usage: cpac claude-models [--opus [M]] [--sonnet [M]] [--haiku [M]] [--classifier [M]] [--reset] [--config PATH]",
+                "Usage: cpac claude-models [--opus [M]] [--sonnet [M]] [--haiku [M]] [--reset] [--config PATH]",
                 "",
                 "Sets the model Claude Code uses per task tier. Saved to the config file",
                 "and applied on every `cpac claude` launch:",
@@ -2097,8 +2106,9 @@ function parseArgs(args) {
                 "  --sonnet      main conversation default tier (ANTHROPIC_DEFAULT_SONNET_MODEL)",
                 "  --haiku       high-frequency small tasks: titles, summaries, background",
                 "                (ANTHROPIC_DEFAULT_HAIKU_MODEL + ANTHROPIC_SMALL_FAST_MODEL)",
-                "  --classifier  auto-mode approval classifier (CLAUDE_CODE_AUTO_MODE_MODEL);",
-                "                unset follows Claude Code's built-in default",
+                "",
+                "Unset slots auto-select from the catalog: same-family claude model first,",
+                "then gemini → grok → luna → first model (opus stays unset without a match).",
                 "",
                 "A slot without a value opens an arrow-key picker over the CPA catalog;",
                 "--reset clears all overrides back to catalog auto-selection.",
@@ -2122,8 +2132,7 @@ function parseArgs(args) {
             }
             else if (arg === "--opus" ||
                 arg === "--sonnet" ||
-                arg === "--haiku" ||
-                arg === "--classifier") {
+                arg === "--haiku") {
                 const slot = arg.slice(2);
                 const value = args[index + 1];
                 if (value !== undefined && !value.startsWith("-")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yhong91/cpac",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Connect Codex and Claude Code to a remote CLIProxyAPI gateway",
   "type": "module",
   "bin": {