coding-tool-x 3.2.0

package/docs/model-redirection.md

@@ -0,0 +1,251 @@
+# 模型重定向功能
+
+## 功能概述
+
+模型重定向功能允许在代理模式下自动将高成本模型请求重定向到低成本模型，从而节省 token 消耗。
+
+例如：将 `claude-opus-4` 重定向到 `claude-sonnet-4-5`，可以大幅降低成本，同时保持良好的性能。
+
+## 使用场景
+
+- GitHub 插件或 oh-my-claudecode skills 默认使用 opus 模型
+- 修改这些插件/skills 的模型配置过于复杂
+- 希望在不修改代码的情况下降低 token 消耗
+
+## 工作原理
+
+### 双重语义
+
+`modelConfig` 字段根据代理状态有不同的含义：
+
+| 代理状态 | 语义 | 行为 |
+|---------|------|------|
+| **代理关闭** | 模型映射 | 写入 `~/.claude/settings.json`，Claude Code CLI 读取环境变量 |
+| **代理开启** | 模型重定向 | 在代理服务器中拦截请求，修改 `model` 字段 |
+
+### 重定向规则
+
+1. **层级检测**：根据模型名称检测层级（opus/sonnet/haiku）
+2. **优先级匹配**：
+   - 优先使用层级特定配置（如 `opusModel`）
+   - 回退到通用配置（`model`）
+   - 无配置则保持原样
+
+### 示例
+
+**配置**：
+```json
+{
+  "modelConfig": {
+    "opusModel": "claude-sonnet-4-5",
+    "sonnetModel": "",
+    "haikuModel": ""
+  }
+}
+```
+
+**重定向结果**：
+- `claude-opus-4-20250514` → `claude-sonnet-4-5`
+- `claude-sonnet-4-5` → `claude-sonnet-4-5`（不变）
+- `claude-3-5-haiku-20241022` → `claude-3-5-haiku-20241022`（不变）
+
+## 配置方法
+
+### 1. 官方渠道
+
+在渠道编辑面板中，展开 **"模型重定向"** 部分：
+
+- **Haiku 重定向**：将所有 haiku 模型重定向到指定模型
+- **Sonnet 重定向**：将所有 sonnet 模型重定向到指定模型
+- **Opus 重定向**：将所有 opus 模型重定向到指定模型（推荐配置为 sonnet）
+
+### 2. 非官方渠道
+
+在渠道编辑面板中，展开 **"模型配置"** 部分：
+
+- 代理关闭时：作为模型映射使用
+- 代理开启时：作为模型重定向使用
+
+## 测试步骤
+
+### 前置条件
+
+1. 启动代理：`ctx proxy start`
+2. 配置渠道的模型重定向规则
+3. 确保渠道已启用
+
+### 测试用例
+
+#### 测试 1：Opus → Sonnet 重定向
+
+**配置**：
+```json
+{
+  "opusModel": "claude-sonnet-4-5"
+}
+```
+
+**测试命令**：
+```bash
+curl -X POST http://localhost:<proxy-port>/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: sk-test" \
+  -d '{
+    "model": "claude-opus-4-20250514",
+    "max_tokens": 100,
+    "messages": [{"role": "user", "content": "Hello"}]
+  }'
+```
+
+**预期结果**：
+- 控制台输出：`[Model Redirect] claude-opus-4-20250514 → claude-sonnet-4-5 (channel: <渠道名>)`
+- 请求成功返回
+
+#### 测试 2：无重定向配置
+
+**配置**：
+```json
+{
+  "opusModel": "",
+  "sonnetModel": "",
+  "haikuModel": ""
+}
+```
+
+**测试命令**：同上
+
+**预期结果**：
+- 无控制台输出（不重定向）
+- 请求使用原始模型
+
+#### 测试 3：Haiku 保持不变
+
+**配置**：
+```json
+{
+  "opusModel": "claude-sonnet-4-5",
+  "haikuModel": ""
+}
+```
+
+**测试命令**：
+```bash
+curl -X POST http://localhost:<proxy-port>/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: sk-test" \
+  -d '{
+    "model": "claude-3-5-haiku-20241022",
+    "max_tokens": 100,
+    "messages": [{"role": "user", "content": "Hello"}]
+  }'
+```
+
+**预期结果**：
+- 无控制台输出（haiku 未配置重定向）
+- 请求使用原始 haiku 模型
+
+## 实现细节
+
+### 代码位置
+
+- **后端逻辑**：
+  - `src/server/proxy-server.js` (Claude 代理)
+  - `src/server/codex-proxy-server.js` (Codex 代理)
+
+- **前端 UI**：
+  - `src/web/src/components/channel/channelPanelFactories.js`
+
+### 核心函数
+
+```javascript
+// 检测模型层级
+function detectModelTier(modelName) {
+  if (!modelName) return null;
+  const lower = modelName.toLowerCase();
+  if (lower.includes('opus')) return 'opus';
+  if (lower.includes('sonnet')) return 'sonnet';
+  if (lower.includes('haiku')) return 'haiku';
+  return null;
+}
+
+// 应用模型重定向
+function redirectModel(originalModel, modelConfig) {
+  if (!modelConfig || !originalModel) return originalModel;
+
+  const tier = detectModelTier(originalModel);
+
+  // 优先级：层级特定配置 > 通用模型覆盖
+  if (tier === 'opus' && modelConfig.opusModel) {
+    return modelConfig.opusModel;
+  }
+  if (tier === 'sonnet' && modelConfig.sonnetModel) {
+    return modelConfig.sonnetModel;
+  }
+  if (tier === 'haiku' && modelConfig.haikuModel) {
+    return modelConfig.haikuModel;
+  }
+
+  // 回退到通用模型覆盖
+  if (modelConfig.model) {
+    return modelConfig.model;
+  }
+
+  return originalModel;
+}
+```
+
+### 请求流程
+
+```
+Client Request
+    ↓
+Proxy Server (allocate channel)
+    ↓
+Check req.body.model
+    ↓
+Apply redirectModel(originalModel, channel.modelConfig)
+    ↓
+Update req.body.model & req.rawBody
+    ↓
+Forward to upstream API
+```
+
+## 注意事项
+
+1. **仅在代理开启时生效**：代理关闭时，modelConfig 用于模型映射
+2. **不修改响应**：只修改请求中的 model 字段，不影响响应
+3. **日志记录**：每次重定向都会在控制台输出日志
+4. **向后兼容**：未配置重定向时，保持原有行为
+
+## 常见问题
+
+### Q: 为什么我的重定向没有生效？
+
+A: 检查以下几点：
+1. 代理是否已启动（`ctx proxy status`）
+2. 渠道的 modelConfig 是否正确配置
+3. 渠道是否已启用
+4. 查看控制台是否有重定向日志
+
+### Q: 可以将 sonnet 重定向到 opus 吗？
+
+A: 可以，但不推荐。重定向的目的是降低成本，将低成本模型重定向到高成本模型会增加开销。
+
+### Q: 重定向会影响响应质量吗？
+
+A: 取决于重定向的目标模型。例如 opus → sonnet 可能会略微降低质量，但通常差异不大。建议根据实际场景测试。
+
+### Q: 可以为不同渠道配置不同的重定向规则吗？
+
+A: 可以。每个渠道都有独立的 modelConfig，可以配置不同的重定向规则。
+
+## 成本节省示例
+
+假设使用 oh-my-claudecode 的 opus 级别 agent：
+
+| 场景 | 原始模型 | 重定向模型 | 输入成本 | 输出成本 | 节省比例 |
+|------|---------|-----------|---------|---------|---------|
+| 默认 | opus-4 | - | $15/M | $75/M | - |
+| 重定向 | opus-4 | sonnet-4-5 | $3/M | $15/M | 80% |
+
+对于大量使用 opus 的场景，成本节省非常显著。

package/docs/multi-channel-load-balancing.md

@@ -0,0 +1,249 @@
+# 多渠道负载均衡与智能切换
+
+本文档详细说明 Coding-Tool 的多渠道负载均衡系统的设计和工作原理。
+
+## 功能概述
+
+多渠道负载均衡系统允许用户配置多个 API 渠道，系统会根据权重、并发限制和健康状态智能分配请求，实现：
+
+- **负载分散**：将请求分散到多个渠道，避免单点压力
+- **故障转移**：自动检测故障渠道并切换到健康渠道
+- **会话连续性**：可选的会话绑定，保证对话上下文
+
+## 模块架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        proxy-server.js                          │
+│                      (代理服务器入口)                            │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │ 请求分配 / 结果记录
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    channel-scheduler.js                         │
+│                      (渠道调度器)                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
+│  │ 加权随机选择 │  │ 并发控制    │  │ 会话绑定    │             │
+│  └─────────────┘  └─────────────┘  └─────────────┘             │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │ 健康检查
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     channel-health.js                           │
+│                      (健康检查模块)                              │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
+│  │ 故障检测    │  │ 冻结管理    │  │ 自动恢复    │             │
+│  └─────────────┘  └─────────────┘  └─────────────┘             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 核心模块说明
+
+### 1. channel-scheduler.js（渠道调度器）
+
+负责请求的渠道分配和并发控制。
+
+#### 主要功能
+
+| 功能 | 说明 |
+|------|------|
+| `allocateChannel()` | 分配一个可用渠道 |
+| `releaseChannel()` | 释放渠道（请求完成时调用） |
+| `getSchedulerState()` | 获取调度器状态 |
+
+#### 加权随机算法
+
+```javascript
+// 权重越高，被选中概率越大
+// 例如：渠道A(权重2) + 渠道B(权重1) + 渠道C(权重1)
+// A 被选中概率 = 2/4 = 50%
+// B 被选中概率 = 1/4 = 25%
+// C 被选中概率 = 1/4 = 25%
+```
+
+#### 并发控制
+
+- `maxConcurrency = null`：无并发限制
+- `maxConcurrency = N`：最多同时处理 N 个请求
+- 超过并发限制的请求进入队列等待（最长 15 秒）
+
+#### 会话绑定（可选）
+
+- **开启时**：同一 sessionId 的请求始终使用同一渠道
+- **关闭时**：每次请求独立进行加权随机分配
+- 配置位置：设置 → 高级设置 → 多渠道负载会话绑定
+
+### 2. channel-health.js（健康检查模块）
+
+负责监控渠道健康状态，自动冻结故障渠道。
+
+#### 状态流转
+
+```
+         连续成功5次
+    ┌──────────────────┐
+    │                  │
+    ▼                  │
+┌────────┐  连续失败3次  ┌──────────┐  冻结到期  ┌──────────┐
+│ healthy │────────────►│  frozen  │──────────►│ checking │
+│ (健康)  │             │  (冻结)  │           │ (检测中) │
+└────────┘              └──────────┘           └────┬─────┘
+    ▲                        ▲                      │
+    │                        │    连续失败3次       │
+    │                        └──────────────────────┘
+    │         连续成功5次
+    └──────────────────────────────────────────────┘
+```
+
+#### 冻结时间策略
+
+| 次数 | 冻结时间 |
+|------|----------|
+| 第1次 | 1 分钟 |
+| 第2次 | 2 分钟 |
+| 第3次 | 4 分钟 |
+| 第4次 | 8 分钟 |
+| 第5次 | 16 分钟 |
+| 第6次+ | 30 分钟（上限）|
+
+#### 恢复检测
+
+- 冻结到期后，渠道进入"检测中"状态
+- 使用真实请求进行健康检测（被动检测，不消耗额外配额）
+- 连续 5 次成功后恢复为"健康"状态
+- 检测期间失败则重新冻结
+
+### 3. proxy-server.js（代理服务器）
+
+负责接收请求、转发到选定渠道、记录结果。
+
+#### 请求处理流程
+
+```
+1. 接收请求
+   │
+2. 调用 allocateChannel() 获取渠道
+   │
+3. 转发请求到渠道
+   │
+4. 等待响应
+   │
+   ├── 成功 → recordSuccess() → 更新健康状态
+   │
+   └── 失败 → recordFailure() → 可能触发冻结
+   │
+5. 调用 releaseChannel() 释放并发位
+```
+
+## 配置参数
+
+### 渠道配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `name` | string | - | 渠道名称 |
+| `baseUrl` | string | - | API 地址 |
+| `apiKey` | string | - | API 密钥 |
+| `enabled` | boolean | true | 是否启用 |
+| `weight` | number | 1 | 权重（越高越容易被选中）|
+| `maxConcurrency` | number/null | null | 最大并发（null=不限制）|
+
+### 全局配置
+
+| 参数 | 位置 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enableSessionBinding` | 高级设置 | true | 是否启用会话绑定 |
+
+### 健康检查配置
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| `failureThreshold` | 3 | 连续失败多少次触发冻结 |
+| `initialFreezeTime` | 60秒 | 初始冻结时间 |
+| `maxFreezeTime` | 30分钟 | 最大冻结时间 |
+| `freezeMultiplier` | 2 | 冻结时间倍增系数 |
+| `healthCheckWindow` | 5 | 恢复需要连续成功次数 |
+
+## 使用场景
+
+### 场景1：多渠道负载均衡
+
+```
+配置：
+- 渠道A：权重=2, 并发=不限制
+- 渠道B：权重=1, 并发=不限制
+- 渠道C：权重=1, 并发=不限制
+
+效果：
+- A 处理 50% 的请求
+- B 处理 25% 的请求
+- C 处理 25% 的请求
+```
+
+### 场景2：主备切换
+
+```
+配置：
+- 主渠道：权重=100, 并发=不限制
+- 备渠道：权重=1, 并发=不限制
+
+效果：
+- 正常情况：几乎所有请求走主渠道
+- 主渠道故障：自动切换到备渠道
+- 主渠道恢复：自动切回主渠道
+```
+
+### 场景3：并发控制
+
+```
+配置：
+- 渠道A：权重=1, 并发=2
+- 渠道B：权重=1, 并发=2
+
+效果：
+- 同时最多 4 个请求（每个渠道 2 个）
+- 超过 4 个请求时排队等待
+```
+
+## 前端展示
+
+### 渠道卡片状态
+
+- 🟢 **绿色左边框**：健康状态
+- 🟡 **黄色左边框 + 渐变背景**：检测中状态
+- 🔴 **红色左边框 + 渐变背景**：冻结状态
+- ⚪ **灰色左边框**：未启用
+
+### 卡片信息
+
+- `W:N`：权重值
+- `C:N` 或 `C:∞`：并发限制
+- 冻结标签显示剩余时间
+
+## API 接口
+
+### 获取渠道列表（含健康状态）
+
+```
+GET /api/channels
+Response: {
+  channels: [{
+    id, name, baseUrl, apiKey, enabled, weight, maxConcurrency,
+    health: { status, statusText, freezeRemaining, ... }
+  }]
+}
+```
+
+### 重置渠道健康状态
+
+```
+POST /api/channels/:id/reset-health
+Response: { success: true, health: {...} }
+```
+
+## 注意事项
+
+1. **会话绑定与故障转移**：渠道被冻结时，绑定到该渠道的会话会自动解绑
+2. **被动健康检测**：不主动发送检测请求，使用真实请求检测
+3. **冻结时间递增**：避免频繁检测故障渠道
+4. **手动重置**：可在前端手动重置渠道健康状态

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "coding-tool-x",
+  "version": "3.2.0",
+  "description": "Vibe Coding 增强工作助手 - 智能会话管理、动态渠道切换、全局搜索、实时监控",
+  "main": "src/index.js",
+  "bin": {
+    "ctx": "bin/ctx.js"
+  },
+  "scripts": {
+    "start": "node bin/ctx.js",
+    "test": "npm run test:basic && npm run test:api && npm run test:codex-agents",
+    "test:basic": "node scripts/test-basic.js",
+    "test:api": "node scripts/test-api-consistency.js",
+    "test:codex-agents": "node scripts/test-codex-agents.js",
+    "benchmark:codex": "node scripts/benchmark-codex-loading.js",
+    "build:web": "cd src/web && npm run build",
+    "dev:web": "cd src/web && npm run dev",
+    "dev:server": "nodemon"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-cli",
+    "session-manager",
+    "cli",
+    "interactive",
+    "conversation",
+    "history",
+    "cc switch"
+  ],
+  "author": "CooperJiang",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/commands/",
+    "src/config/",
+    "src/plugins/",
+    "src/server/",
+    "src/ui/",
+    "src/utils/",
+    "src/index.js",
+    "src/reset-config.js",
+    "docs/",
+    "dist/",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "adm-zip": "^0.5.16",
+    "ajv": "^8.12.0",
+    "cc-tool-web": "file:src/web",
+    "chalk": "^4.1.2",
+    "express": "^4.18.2",
+    "http-proxy": "^1.18.1",
+    "https-proxy-agent": "^7.0.6",
+    "inquirer": "^8.2.7",
+    "open": "^8.4.2",
+    "ora": "^5.4.1",
+    "pm2": "^5.4.3",
+    "semver": "^7.6.0",
+    "toml": "^3.0.0",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZeaoZhang/coding-tool.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ZeaoZhang/coding-tool/issues"
+  },
+  "homepage": "https://github.com/ZeaoZhang/coding-tool#readme"
+}