@leeandrew94/ccm 0.4.0 → 0.5.0

package/README.md

@@ -10,7 +10,7 @@ Language：[English](#english) | [中文](README.zh.md)
 
 Run Claude Code with different AI models in separate terminals. One command per terminal, zero config conflicts.
 
-ccm (Claude Code Model Manager) is a CLI tool that lets you run Claude Code with different AI models in different terminal windows at the same time. Each terminal gets its own model, API endpoint, and credentials — no shared config files, no conflicts. Switch models by name, track running instances, and manage profiles from the command line.
+ccm (Claude Code Model Manager) is a CLI tool that lets you run Claude Code with different AI models in different terminal windows at the same time. Each launch gets its own model, API endpoint and credentials without rewriting Claude Code's global config. Existing Claude Code user and project settings still apply. Switch models by name, track running instances, and manage profiles from the command line.
 
 ## Prerequisites
 
@@ -64,12 +64,20 @@ ccm ps
 | `ccm kill <name>` | Kill a running instance |
 | `ccm kill --all` | Kill all running instances |
 | `ccm check` | Check if claude is installed |
+| `ccm ping [name]` | Test round-trip latency and connection speed |
 | `ccm test [name]` | Test API connection (omit name to test all) |
+| `ccm test [name] --speed` | Compare full short-request times |
+| `ccm stats / cost` | Token throughput & estimated cost dashboard |
 | `ccm balance [name]` | Query model balance/credits (omit name to query all) |
+| `ccm pin [name] / unpin` | Pin / unpin default preferred model for current project |
+| `ccm export [-o file]` | Safe redacted export for team sharing and backup |
+| `ccm import <file>` | Import profiles and connections from package |
 | `ccm sessions` | Browse session history (interactive terminal list) |
+| `ccm resume [name]` | Resume a session in the current project, optionally with another model |
 | `ccm sessions --web` | Open session viewer in browser |
 | `ccm sessions --restore [id]` | Restore a deleted session from trash |
 | `ccm sessions --purge` | Permanently empty the trash |
+| `ccm update` | Check and update CCM to the latest version |
 
 ## Session Management
 
@@ -118,7 +126,7 @@ source <(ccm completions bash)
 
 ## Configuration
 
-Profile config file `~/.ccm/profiles.json` (managed via `ccm add` / `ccm edit`):
+Configuration lives in `~/.ccm/profiles.json` (managed via `ccm add` / `ccm edit`). This legacy format remains readable; the first save backs it up and migrates it to version 2 (see Storage below):
 
 ```json
 {
@@ -142,6 +150,127 @@ Profile config file `~/.ccm/profiles.json` (managed via `ccm add` / `ccm edit`):
 | `ANTHROPIC_DEFAULT_SONNET_MODEL` | No | Sonnet model mapping |
 | `ANTHROPIC_DEFAULT_OPUS_MODEL` | No | Opus model mapping |
 
+## Terminal setup and model controls
+
+Existing shortcuts such as `ccm mimo` are preserved. Run `ccm` to search and launch profiles, or start setup on first use.
+
+- Presets for MiMo, DeepSeek, Kimi API / Kimi Code, GLM, MiniMax, Qwen, Anthropic, OpenRouter and custom compatible endpoints.
+- Reuse a connection for multiple models; maintain its credentials once. Editing a shared connection lists affected profiles.
+- Search model catalogs; account-scoped cached or preset suggestions are explicitly labeled. Manual IDs remain available.
+- New profiles map Haiku / Sonnet / Opus tasks to the main model by default; customize under advanced options.
+- Field-based editing and hidden API key entry. Esc / Ctrl+C cancels the current operation; previously saved fields remain.
+- Chinese and English UI, without changing Claude Code's language.
+
+```bash
+ccm
+ccm init
+ccm add kimi
+ccm edit mimo
+ccm mimo --effort high
+ccm edit mimo --effort high
+ccm edit mimo --effort default
+ccm mimo --effort default
+ccm config --language en            # zh / en / auto
+ccm --lang zh list                  # one invocation
+ccm mimo --backup                   # manually pick a saved backup
+
+```
+
+Effort is requested from Claude Code; actual support depends on its version, model and endpoint. GPT requires an Anthropic-compatible gateway (OpenRouter or a custom gateway), not the native OpenAI endpoint. ccm does not translate protocols or provide load balancing / automatic request failover. Backups are manual launch choices, not automatic restarts or live session migration.
+
+Balance adapters cover DeepSeek, Kimi API, OpenRouter and GLM pay-as-you-go. Unsupported lookup is distinct from zero balance; money does not imply remaining plan allowance. Changing a preset endpoint disables its original balance lookup rather than forwarding your key to another host.
+
+`ccm test` now sends a short Messages inference request and may incur a small cost. A 400 or host reachability alone is not success; tools, effort and long contexts are not verified.
+
+For verified DeepSeek V4 Pro / Flash IDs on the official endpoint, ccm normalizes ID casing in existing profiles, model selection and diagnostics. `ccm deepseek` declares the documented 1M context window in that launch's environment and settings snapshot. No additional flags or configuration migration are needed. An explicit `CLAUDE_CODE_MAX_CONTEXT_TOKENS` is respected; passing Claude's `--model` leaves window selection to Claude Code. Gateway aliases and unknown models are preserved. Sources: [DeepSeek model details](https://api-docs.deepseek.com/quick_start/pricing/), [Claude Code custom model windows](https://code.claude.com/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id).
+
+### Qwen / Alibaba Cloud Model Studio
+
+Run `ccm add qwen`, choose **Add connection** if prompted, then search for `Qwen` or `千问`. Choose API CN (Beijing), API Global (Singapore), Coding Plan CN or Token Plan CN, enter the matching API key and select a model. Launch with `ccm qwen`.
+
+These presets use the official Anthropic-compatible endpoints; regional and plan-specific keys must match the selected endpoint. The API presets use the still-supported shared DashScope domains; workspace-dedicated domains can be set through **Edit shared endpoint / key**. Since the Anthropic interface does not provide a model catalog, ccm shows labeled preset candidates and allows manual model IDs. Candidates do not guarantee access for your account or region. Qwen balance lookup is currently unsupported.
+
+References: [Claude Code setup](https://help.aliyun.com/en/model-studio/claude-code), [Anthropic-compatible API](https://help.aliyun.com/zh/model-studio/anthropic-api-messages), [regional endpoints](https://docs.bailian.console.aliyun.com/en/model-studio/base-url).
+
+### Independent connection networking
+
+Run `ccm edit <name>` and choose **Connection network policy**:
+
+- **Inherit terminal environment** (default): uses HTTP(S) proxy variables and `NO_PROXY` from the launching terminal, not the operating system's proxy settings.
+- **Connect directly**: clears inherited proxy variables and sets `NO_PROXY=*` for this launch.
+- **Use an HTTP(S) proxy**: stores a dedicated proxy URL, such as `http://127.0.0.1:7890`. Authentication is supported with hidden input. Inherited proxy bypass rules are cleared so this connection uses its selected proxy.
+
+The same policy applies to Claude Code, model discovery, balance queries and `ccm test`. Editing a shared connection affects every profile using it on future launches. Proxy settings are written to the launch snapshot; the parent terminal stays unchanged. Only HTTP(S) proxies are supported; `ALL_PROXY` is cleared. Direct mode does not bypass a VPN or TUN route.
+
+In version 2 configuration, these optional fields belong to a **connection**, alongside `baseUrl`, `token` and `auth`:
+
+```json
+{
+  "proxyPolicy": "custom",
+  "proxyUrl": "http://127.0.0.1:7890"
+}
+```
+
+### Connection latency and Quick Resume
+
+```bash
+ccm ping                           # compare connection round-trip latency across all endpoints
+ccm ping deepseek                  # test latency for a specific profile
+ccm resume                         # pick a session in this project, then choose model
+ccm resume kimi                    # resume session in this project with kimi
+ccm resume kimi --effort high       # override reasoning effort for this resume
+ccm test --speed                    # alias for speed comparison
+```
+
+- **Quick Resume**: Lists recently active sessions in the current project (with first question prompt, original model, and activity time), with an option to search all project sessions. Reads real transcript timestamps for accurate ordering. Context and tool-history compatibility depend on target model; resuming may rebuild cache. Native `ccm kimi -c` and `ccm kimi -r` retain Claude Code's original behavior.
+- **Connection Latency (`ccm ping`)**: Measures full round-trip request duration (**not TTFT**); groups requests by origin and credentials (serial within origin, parallel across origins) to prevent 429 rate limit triggers. Each probe may incur a small charge.
+
+### Token Throughput & Cost Analytics (`ccm stats / cost`)
+
+Native Claude Code `/cost` hardcodes Anthropic standard rates, giving misleading estimates when using third-party providers. `ccm stats` scans local transcripts to extract real token consumption and calculate estimated costs:
+
+```bash
+ccm stats                           # view token usage and costs for the current project
+ccm stats [directory]               # view token usage and costs for a specific project
+ccm stats --all                     # global breakdown across all projects on this machine
+ccm stats -d 7                      # analyze daily trends for the last 7 days
+```
+
+- **Built-in Model Rates**: Preconfigured with standard pricing for Claude, DeepSeek, Doubao, Kimi, GLM, MiniMax, Qwen, and custom profile pricing.
+- **Prompt Caching Metrics**: Accurately tracks cache read tokens, displaying cache hit rate (typically >90%) and prompt caching savings.
+
+### Directory Memory & Pinned Profile (`ccm pin`)
+
+Eliminate typing model names repeatedly when switching between multiple project repositories:
+
+```bash
+ccm                                 # opens menu with cursor defaulted to this project's recent model; Enter to launch
+ccm pin deepseek                    # pin deepseek as the preferred default model for this project
+ccm unpin                           # remove pinned preference
+```
+
+- **Smart Focus**: Automatically highlights the recent profile used in the current directory (`[★ recent]`). Hit Enter to launch immediately or arrow keys to switch.
+- **Security Constrained**: Directory memory strictly references existing local profile names without executing or loading arbitrary files from the repository directory.
+
+### Safe Config Export & Team Sharing (`ccm export / ccm import`)
+
+Share gateway endpoints, models, and task mappings with team members safely:
+
+```bash
+ccm export                          # print safe redacted JSON (API keys stripped by default)
+ccm export -o team-config.json       # save shareable redacted config to file
+ccm export --with-keys -o backup.json # full backup including plaintext keys (with prominent warning)
+ccm import team-config.json         # import package; interactively prompts for missing API keys
+```
+
+**Storage**
+
+`~/.ccm/profiles.json` version 2 contains preferences, connections and profiles in one atomically replaced file. Legacy profiles are read without writes. The first explicit mutation keeps `profiles.json.v1.bak`; later mutations keep the previous generation in `profiles.json.bak`. Restore an appropriate backup before downgrading to an old ccm release.
+
+Writes use a lock, a flushed temporary file and atomic replacement, with 0600 file permissions. Files and backups contain plaintext credentials. Invalid configuration blocks writes. Each launch uses its own settings snapshot, cleaned on normal exit; a forcibly killed process may leave one behind. A stale write lock requires manual cleanup after confirming no writer is active.
+
+`CCM_HOME` selects an independent data directory; the default remains `~/.ccm`. The existing `ccm config <name>` export command **contains plaintext keys**.
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/chart?repos=leeandrew94/ccm-cli&type=date&legend=top-left)](https://www.star-history.com/?type=date&repos=leeandrew94%2Fccm-cli)

package/README.zh.md

@@ -10,7 +10,7 @@
 
 在不同终端窗口用不同 AI 模型运行 Claude Code，一行命令切换，互不干扰。
 
-ccm（Claude Code Model Manager）是一个命令行工具，让你在不同终端窗口同时使用不同的 AI 模型运行 Claude Code。每个终端独立绑定模型、API 地址和密钥，不修改全局配置，终端之间完全隔离。通过命令行按名称切换模型、查看运行实例、管理配置。
+ccm（Claude Code Model Manager）是一个命令行工具，让你在不同终端窗口同时使用不同的 AI 模型运行 Claude Code。每次启动独立绑定模型、API 地址和密钥，不修改 Claude Code 全局配置；原有用户设置和项目设置仍然适用。通过命令行按名称切换模型、查看运行实例、管理配置。
 
 ## 环境要求
 
@@ -64,12 +64,20 @@ ccm ps
 | `ccm kill <name>` | 停止指定实例 |
 | `ccm kill --all` | 停止所有实例 |
 | `ccm check` | 检查 claude 是否安装 |
+| `ccm ping [name]` | 测试线路连接延迟与短请求往返耗时 |
 | `ccm test [name]` | 测试 API 连接（不指定则测试全部） |
+| `ccm test [name] --speed` | 对比完整短请求耗时 |
+| `ccm stats / cost` | 本地真实 Token 消耗与预估费用看板 |
 | `ccm balance [name]` | 查询模型余额（不指定则查询全部） |
+| `ccm pin [name] / unpin` | 钉选/取消当前项目的专属默认模型 |
+| `ccm export [-o file]` | 安全脱敏导出配置（用于团队分享与多机迁移） |
+| `ccm import <file>` | 从导出文件导入模型配置与连接 |
 | `ccm sessions` | 浏览会话历史（终端交互式列表） |
+| `ccm resume [name]` | 接续当前项目会话，可换用其他模型 |
 | `ccm sessions --web` | 在浏览器中打开会话查看器 |
 | `ccm sessions --restore [id]` | 从回收站恢复已删除的会话 |
 | `ccm sessions --purge` | 永久清空回收站 |
+| `ccm update` | 检查并一键升级 CCM 到最新版本 |
 
 ## 会话管理
 
@@ -118,7 +126,7 @@ source <(ccm completions bash)
 
 ## 配置
 
-Profile 配置文件 `~/.ccm/profiles.json`（通过 `ccm add` / `ccm edit` 管理）：
+配置文件 `~/.ccm/profiles.json` 通过 `ccm add` / `ccm edit` 管理。以下旧格式仍可读取，首次保存会迁移为 version 2 并备份（详见下方“配置与迁移”）：
 
 ```json
 {
@@ -142,6 +150,129 @@ Profile 配置文件 `~/.ccm/profiles.json`（通过 `ccm add` / `ccm edit` 管
 | `ANTHROPIC_DEFAULT_SONNET_MODEL` | 否 | Sonnet 映射 |
 | `ANTHROPIC_DEFAULT_OPUS_MODEL` | 否 | Opus 映射 |
 
+## 新版终端配置体验
+
+原来的名称和命令继续可用，例如 `ccm mimo`。直接运行 `ccm` 可以搜索并启动已有配置；没有配置时进入向导。
+
+- 厂商预设：MiMo、DeepSeek、Kimi API / Kimi Code、智谱 GLM、MiniMax、千问 Qwen、Anthropic、OpenRouter，以及自定义兼容接口。
+- 地址按区域和套餐区分。模型优先从接口获取，失败时明确标记账号缓存或预设候选；始终允许手动输入。
+- 同一连接的地址和密钥只保存一次。添加其他模型时可复用；修改共享连接会提示受影响的配置。
+- 新配置默认让 Haiku / Sonnet / Opus 任务都使用所选模型，可在高级设置修改。
+- 编辑按字段保存；API Key 隐藏输入。Esc / Ctrl+C 取消当前操作，已保存的字段保留。
+- 自动选择中英文；CCM 只切换自己的界面，不修改 Claude Code 的语言。
+
+```bash
+ccm
+ccm init
+ccm add kimi
+ccm edit mimo
+ccm mimo --effort high              # 仅本次
+ccm edit mimo --effort high         # 保存默认强度
+ccm edit mimo --effort default      # 清除 ccm 默认强度
+ccm mimo --effort default           # 本次不采用 ccm 默认强度
+ccm config --language zh            # 持久保存 zh / en / auto
+ccm --lang en list                  # 仅本次语言
+ccm mimo --backup                   # 从编辑页设置的备用列表中手动选择
+
+```
+
+**兼容范围**
+
+强度设置是向 Claude Code 提交的请求，不代表第三方一定采用。可用档位取决于 Claude Code 版本、模型和接入渠道。GPT 需使用 Anthropic 兼容网关（可选 OpenRouter 或自定义网关），不能直接填写 OpenAI 原生接口；ccm 不内置协议转换、负载均衡或请求级自动接替。备用列表用于本次启动的手动选择，不会重启或自动迁移运行中的会话。
+
+余额当前适配 DeepSeek、Kimi API、OpenRouter 和智谱按量 API；其他连接显示“不支持查询”，不把未知额度当成零，也不猜测套餐剩余次数。修改预设地址后，不再向原厂商余额地址发送此连接的密钥。
+
+`ccm test` 已改为实际发送短 Messages 请求，可能产生少量费用；HTTP 400 或仅地址可达不再算成功。它不验证工具调用、强度或长上下文。
+
+使用官方 DeepSeek 接口时，已确认的 V4 Pro / Flash 模型会自动规范 ID 大小写，覆盖旧配置启动、模型选择和诊断。仍然只需 `ccm deepseek`，ccm 会在该窗口的启动环境和设置快照中声明官方文档的 1M 上下文，无需额外参数或配置迁移。用户显式设置的 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 优先；透传 Claude 的 `--model` 时不套用原模型窗口。网关别名和未知模型保持原样。依据：[DeepSeek 模型规格](https://api-docs.deepseek.com/quick_start/pricing/)、[Claude Code 自定义模型窗口](https://code.claude.com/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。
+
+### 千问 / 阿里云百炼
+
+运行 `ccm add qwen`，若提示复用连接则选择“添加新连接”，搜索 `Qwen` 或 `千问`。按账号选择北京按量 API、新加坡按量 API、Coding Plan CN 或 Token Plan CN，输入对应密钥并选择模型，保存后用 `ccm qwen` 启动。
+
+预设使用官方 Anthropic 兼容地址；地域与套餐必须和 API Key 配套。按量 API 默认使用仍受支持的 DashScope 公共域名，如需业务空间专属域名，可通过“修改连接地址或密钥”替换。Anthropic 接口不提供模型列表，因此直接展示已标注的预设候选，保留手动输入；候选不代表账号或地域一定可用。千问暂不支持余额查询。
+
+官方说明：[Claude Code 接入](https://help.aliyun.com/zh/model-studio/claude-code)、[Anthropic 兼容接口](https://help.aliyun.com/zh/model-studio/anthropic-api-messages)、[地域与接入地址](https://docs.bailian.console.aliyun.com/en/model-studio/base-url)。
+
+### 连接独立网络策略
+
+运行 `ccm edit <名称>`，选择 **连接网络策略**：
+
+- **继承当前终端环境**（默认）：读取启动终端的 HTTP(S) 代理变量与 `NO_PROXY`，不读取操作系统代理设置。
+- **强制直连**：为本次启动清空继承的代理变量，并设置 `NO_PROXY=*`。
+- **指定 HTTP(S) 代理**：保存独立代理地址，例如 `http://127.0.0.1:7890`；支持认证，输入时隐藏。清空继承的代理绕过规则，确保此连接使用指定代理。
+
+同一策略覆盖 Claude Code、模型列表、余额查询和 `ccm test`。修改共享连接会影响所有使用它的配置，下次启动生效。启动快照中的代理设置同步更新，当前终端环境不受影响。只支持 HTTP(S) 代理，清空 `ALL_PROXY`；直连模式不能绕过 VPN 或 TUN 路由。
+
+version 2 配置中，以下可选字段属于 **connection**，与 `baseUrl`、`token`、`auth` 同级：
+
+```json
+{
+  "proxyPolicy": "custom",
+  "proxyUrl": "http://127.0.0.1:7890"
+}
+```
+
+### 快速接续与线路测速
+
+```bash
+ccm ping                           # 快速并发测试所有线路延迟与完整短请求耗时
+ccm ping deepseek                  # 仅测指定配置
+ccm resume                         # 选当前项目会话，再选接续模型
+ccm resume kimi                    # 用 kimi 接续当前项目的指定会话
+ccm resume kimi --effort high       # 本次接续使用高思考强度
+ccm test --speed                    # 诊断测速对比（与 ccm ping 等价）
+```
+
+- **快速接续**：展示当前项目目录最近活跃的 5 个会话（带问题摘要、原模型与最近活动时间），可展开搜索本目录全部会话。优先读取 transcript 真实事件时间，准确排序。跨模型接续效果取决于上下文和工具历史兼容性，可能重建缓存。原生 `ccm kimi -c`、`ccm kimi -r` 的语义保持不变。
+- **线路测速 (`ccm ping`)**：测量建连加响应的完整短请求往返耗时（注：**非首字延迟 TTFT**）；按站点源与凭据智能分组，同凭据串行、跨源并行，避免自发触发 429。每次探测产生极少量费用。
+
+### Token 消耗与消费看板 (ccm stats / ccm cost)
+
+解决原生 Claude Code 内部 `/cost` 估算失真（原生硬编码 Anthropic 官方高额单价）的问题。`ccm stats` 离线扫描本地会话历史，准确提取每个模型的输入、输出与 Prompt Caching 命中量，并计算预估费用：
+
+```bash
+ccm stats                           # 查看当前项目的用量与花费
+ccm stats [项目目录]                 # 查看指定项目的用量与花费
+ccm stats --all                     # 查看全机所有项目的全局统计与排行
+ccm stats -d 7                      # 仅统计最近 7 天的每日消耗趋势
+```
+
+- **内置主流模型基准单价**：支持 Claude 官方、DeepSeek、豆包 (Doubao)、Kimi、智谱 GLM、MiniMax 等，同时支持在配置中自定义覆盖。
+- **Prompt Caching 命中统计**：精确提取缓存读取量，直观展示缓存命中率（通常 >90%）和实际节省的费用。
+
+### 项目专属模型与目录记忆 (ccm pin)
+
+在多项目并行开发时，消除每次进入目录都要重复敲长命令或选择模型的繁琐：
+
+```bash
+ccm                                 # 打开主菜单时光标自动停留在本项目上次使用的模型上，回车即启动
+ccm pin deepseek                    # 将 deepseek 钉选为当前项目的专属默认模型
+ccm unpin                           # 取消钉选
+```
+
+- **智能聚焦**：根据项目运行历史自动高亮最近模型（标记为 `[★ 本项目常用]`），敲回车即可直达。
+- **安全约束**：目录记忆仅绑定本地已有的合法 Profile 名称，不读取项目仓库内的外部文件，杜绝恶意仓库供应链投毒风险。
+
+### 配置安全导出与团队共享 (ccm export / ccm import)
+
+方便团队分享厂商 BaseURL / 模型映射规则，或在多台设备间安全迁移：
+
+```bash
+ccm export                          # 输出安全脱敏的配置 JSON（默认自动剥离 API Key，可放心公开分享）
+ccm export -o team-config.json       # 保存脱敏配置到文件
+ccm export --with-keys -o backup.json # 全量备份（包含明文密钥，带有黄色警示）
+ccm import team-config.json         # 交互式导入配置包；遇到无密钥连接会自动提示补充输入 Key
+```
+
+**配置与迁移**
+
+`~/.ccm/profiles.json` 使用 version 2 格式，在同一文件中保存 preferences、connections、profiles，保证整体替换。旧的环境变量格式仍可读取，启动不改写；第一次主动保存时保留原文件 `profiles.json.v1.bak`，后续保存保留上一版 `profiles.json.bak`。升级后的格式不能直接交给旧版 ccm，降级前需手动恢复备份。
+
+配置使用写锁、临时文件刷盘后原子替换和 0600 文件权限；凭据为本地明文，备份也包含凭据。读取损坏配置时停止写入并提示修复。每次启动生成独立设置文件，正常退出时清理，不覆盖同名配置的其他实例。强制终止进程可能留下设置文件；异常退出留下的写锁需在确认没有配置写入进程后清理。
+
+可用 `CCM_HOME` 指定独立数据目录，默认仍为 `~/.ccm`。`ccm config <名称>` 保持输出环境变量的原有行为，**包含明文密钥**，请勿公开分享。
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/chart?repos=leeandrew94/ccm-cli&type=date&legend=top-left)](https://www.star-history.com/?type=date&repos=leeandrew94%2Fccm-cli)