@adversity/coding-tool-x 2.2.0

package/docs/CHANGELOG.md

@@ -0,0 +1,582 @@
+# 更新日志
+
+## v1.5.0 (最新) - 2025-11-24
+
+### ✨ 新功能
+
+- **自动更新** - 新增 `ctx update` 命令，支持检查并自动更新到最新版本
+- **版本提醒** - Web UI 打开时自动检测新版本，显示更新提示
+- **UI 美化** - 重新设计 Header Logo 区域，采用上下排列布局和渐变效果
+- **图标优化** - 更换 Claude/Gemini 图标为更合适的语义化图标（聊天气泡/闪光）
+
+### 🐛 Bug 修复
+
+- 修复项目路径中下划线 `_` 被错误转换为 `-` 的问题，导致"使用对话"功能无法正确打开目录
+- 修复首页三列底部边框被裁剪的布局问题
+- 修复 Dialog/Message 组件在暗色模式下未正确适配的问题
+- 修复 Gemini 最新对话抽屉错误显示 Claude 数据的问题
+
+### 🔧 优化
+
+- 清理前后端调试日志，控制台输出更干净
+- 优化成本计算设置 UI，改为一行一个的布局
+- 移除无用的全局 loading 超时警告
+- 收窄设置抽屉宽度，布局更紧凑
+
+---
+
+## v2.0.0 - 2025-11-20
+
+### 🎉 重大更新：多渠道管理 & 实时监控
+
+#### 新增功能
+
+**🔀 多渠道管理系统**
+- ✨ API 渠道可视化管理（添加、编辑、删除）
+- ⚡ 动态切换渠道，无需重启 ClaudeCode
+- 🎨 渠道卡片支持拖拽排序和折叠
+- 🔒 API Key 脱敏显示，防止泄露
+- 🌐 支持官网链接快速跳转
+- 💾 渠道配置持久化存储
+
+**📡 实时日志监控**
+- 🎯 WebSocket 实时推送日志
+- 📊 Token 统计（请求/回复/缓存写入/缓存命中）
+- 🏷️ 行为日志（渠道切换、会话启动）
+- 🔍 模型信息悬浮提示
+- 💾 日志持久化（最多100条）
+- 🗑️ 一键清空日志
+
+**🔍 全局搜索功能**
+- ⌨️ 快捷键支持（⌘/Ctrl + K）
+- 🌐 跨项目搜索会话内容
+- 🎯 高亮显示匹配关键词
+- 📊 显示匹配次数和上下文
+- 🚀 一键启动搜索到的会话
+
+**🎨 用户体验优化**
+- 🎭 面板可见性控制（渠道列表/实时日志）
+- 📱 状态持久化（localStorage）
+- 🌊 流畅动画效果
+- 📦 项目卡片拖拽排序
+- 🕐 最近对话抽屉
+
+#### 技术架构升级
+
+**后端服务**
+- Express.js Web 服务器
+- HTTP 代理服务器（动态切换核心）
+- WebSocket 服务器（实时通信）
+- RESTful API 架构
+
+**前端重构**
+- Vue 3 + Naive UI 组件库
+- Pinia 状态管理
+- Vue Router 路由管理
+- VueDraggable 拖拽排序
+- Vite 构建工具
+
+**新增 API 路由**
+- `/api/channels` - 渠道管理
+- `/api/proxy` - 代理控制
+- `/api/sessions/search` - 全局搜索
+- `/ws` - WebSocket 连接
+
+#### 性能优化
+
+- ⚙️ API 轮询从 5s 优化到 30s
+- 🔄 WebSocket 重连机制（最多3次，指数退避）
+- 🚀 大文件加载优化
+- 💾 配置文件缓存
+
+#### Bug 修复
+
+- 🐛 修复 WebSocket 重复连接问题
+- 🐛 修复项目列表加载问题
+- 🐛 修复路由匹配错误
+- 🐛 修复添加渠道后表单未清空
+- 🐛 修复实时日志底部被遮挡
+
+#### 配置文件
+
+新增配置文件存储在 `~/.claude/cc-tool/`：
+- `channels.json` - API 渠道配置
+- `proxy-logs.json` - 实时日志持久化
+- `project-order.json` - 项目排序
+- `recent-sessions.json` - 最近会话
+
+#### 版本变更
+
+- **版本号**: 1.3.0 → 2.0.0
+- **重大更新**: 全新的多渠道管理和实时监控系统
+- **向后兼容**: 原有功能完全保留，配置自动迁移
+
+---
+
+## v1.3.0 - 2025-11-19
+
+### 🎉 重大重构：模块化架构
+
+#### 代码重构
+将单一的 600+ 行 `index.js` 重构为模块化架构。
+
+**新的目录结构**：
+```
+cc-cli/
+├── bin/          # CLI 入口
+├── src/          # 源代码
+│   ├── commands/ # 命令处理
+│   ├── utils/    # 工具函数
+│   ├── ui/       # UI 相关
+│   └── config/   # 配置管理
+├── docs/         # 文档
+└── test/         # 测试
+```
+
+#### 改进点
+
+1. **模块化设计**
+   - ✅ 12 个模块文件，职责明确
+   - ✅ 命令、工具、UI、配置分离
+   - ✅ 低耦合、高内聚
+
+2. **标准化结构**
+   - ✅ 符合 npm 包规范
+   - ✅ 清晰的 bin 入口
+   - ✅ 完整的 .gitignore 和 .npmignore
+
+3. **可维护性**
+   - ✅ 易于定位和修改代码
+   - ✅ 易于添加新功能
+   - ✅ 易于编写单元测试
+
+4. **文档完善**
+   - ✅ 添加 PROJECT_STRUCTURE.md
+   - ✅ 文档集中到 docs/ 目录
+
+#### 版本升级
+
+- **版本号**: 1.2.1 → 1.3.0
+- **主版本号变更**: 内部架构重大变更
+- **向后兼容**: 功能和使用方式完全保持一致
+
+---
+
+## v1.2.1 - 2025-11-19
+
+### ✨ 简化显示格式
+
+#### 改为单行紧凑格式
+
+**新格式**：
+```
+1. 8小时前    │ 58.1KB   │ jly-20251106-orderCenter      │ 实现订单中心支付功能
+2. 1天前      │ 19.4KB   │ customerComplaint             │ 修复客户投诉系统响应时间
+3. 2天前      │ 108.6KB  │ main                          │ 添加用户权限管理功能
+```
+
+**改进点**：
+1. **单行显示** - 所有信息在一行，清晰紧凑
+2. **显示第一条消息** - 用户在第一条消息描述会话目的，更易识别
+3. **清理加载信息** - 使用 `console.clear()` 移除加载动画残留
+4. **统一格式** - 列表和搜索结果使用相同的显示格式
+
+**对比旧版本**：
+- ❌ 旧版：多行显示，显示最后一条消息
+- ✅ 新版：单行显示，显示第一条消息
+
+---
+
+### ✨ 优化 Fork 选择体验
+
+#### 改进 Fork 选择方式
+
+**旧方式**（v1.2.0）：
+```
+是否创建新分支 (fork)? [原会话继续请选N] (y/N)
+```
+- 需要输入 Y/N
+- 不够直观
+- 没有详细说明
+
+**新方式**（v1.2.1）：
+```
+选择恢复方式:
+  📝 继续原会话 (推荐) - 在原会话上继续对话，所有内容会追加到原文件
+  🌿 创建新分支 (Fork) - 基于原会话创建新会话，保留原会话不变
+  ──────────────
+  ↩️  返回重新选择
+```
+
+#### 改进点
+
+1. **箭头键选择** - 不需要输入 Y/N，用上下箭头选择
+2. **默认选项** - 默认选中"继续原会话"（最常用）
+3. **详细说明** - 每个选项都有清晰的说明
+4. **可以返回** - 选错了可以返回重新选择
+5. **视觉区分** - 用颜色和图标区分选项
+
+#### 新增 Fork 使用指南
+
+创建了详细的 `FORK_GUIDE.md` 文档，解释：
+- Fork 的真正作用
+- 何时应该使用 Fork
+- 何时不应该使用 Fork
+- 常见误解和正确用法
+- 实战案例
+
+### 🎓 Fork 功能说明
+
+#### Fork ≠ 继续对话
+
+很多人误解：
+> ❌ Fork 是让我可以从上次的地方继续对话
+
+实际上：
+> ✅ 直接选择"继续原会话"就能从上次的地方继续
+> ✅ Fork 是创建一个新的独立会话
+
+#### Fork 的真正作用
+
+```
+原会话 (abc123.jsonl)          Fork后 (xyz789.jsonl)
+├─ 对话1: 实现功能A            ├─ [复制] 对话1: 实现功能A
+├─ 对话2: 添加功能B            ├─ [复制] 对话2: 添加功能B
+└─ 对话3: 测试完成             └─ [新方向] 尝试不同实现
+   ↓                              ↓
+   保持不变                       独立发展
+```
+
+#### 使用场景
+
+**应该 Fork 的情况**：
+- ✅ 想尝试不同的技术方案（保留原方案）
+- ✅ 要做大幅度重构（保留稳定版本）
+- ✅ 实验性修改（失败可回退）
+
+**不需要 Fork 的情况**：
+- ⭐ 正常继续工作 → 选择"继续原会话"
+- ⭐ 修复 bug → 选择"继续原会话"
+- ⭐ 增加新功能 → 选择"继续原会话"
+
+> **记住：99% 的情况选择"继续原会话"！**
+
+---
+
+## v1.2.0 - 2025-11-19
+
+### ✨ UI 全面升级
+
+#### 1. 🎨 美化会话列表显示
+
+**新的布局格式**：
+```
+1. 8小时前    │ 58.1KB   │ jly-20251106-orderCenter
+   💬 实现订单中心支付功能
+
+2. 1天前      │ 19.4KB   │ customerComplaint
+   📝 修复客户投诉系统的响应时间问题
+
+3. 2天前      │ 108.6KB  │ main
+   💬 添加用户权限管理功能
+```
+
+**改进点**：
+- ✅ 清晰的列结构（时间 │ 大小 │ 分支）
+- ✅ 自动简化分支名（去掉 feature/、feat/、fix/ 前缀）
+- ✅ 显示最后一次对话内容
+- ✅ 使用图标区分内容类型（💬 对话、📝 摘要）
+
+#### 2. 💬 展示最后对话内容
+
+**功能**：
+- 自动提取最后一次助手回复或用户消息
+- 优先显示助手的回复（帮助回忆对话结果）
+- 如果没有，显示用户的最后问题
+- 截断长文本（最多80字符）
+
+**技术实现**：
+- 大文件（>10MB）：只读取开头 8KB + 结尾 8KB
+- 小文件：读取全部但只解析前10行和后20行
+- 性能：不影响加载速度
+
+#### 3. 🔄 添加快捷操作
+
+**在会话列表中新增**：
+```
+──────────────────────────────────────────
+↩️  返回主菜单
+🔀  切换项目
+```
+
+**在搜索结果中新增**：
+```
+──────────────────────────────────────────
+↩️  返回主菜单
+🔎  重新搜索
+🔀  切换项目
+```
+
+**好处**：
+- 不用按 Esc 或 Ctrl+C 返回
+- 可以直接在列表中切换项目
+- 搜索失败可以立即重新搜索
+
+#### 4. 🎯 优化主菜单图标
+
+**旧图标 → 新图标**：
+- 📋 → 💼 （更商务）
+- 🔍 → 🔎 （更清晰）
+- 🔄 → 🔀 （更准确表达切换）
+- ❌ → 👋 （更友好）
+
+#### 5. 🌈 改进颜色方案
+
+- **序号**：白色加粗（更醒目）
+- **时间**：青色（容易区分）
+- **大小**：灰色（不抢眼）
+- **分支**：绿色（清晰标识）
+- **对话内容**：白色（主要信息）
+- **摘要**：黄色（区分类型）
+
+### 📊 对比效果
+
+| 项目 | v1.1.1 | v1.2.0 |
+|------|--------|--------|
+| 显示对话内容 | ❌ | ✅ 显示最后对话 |
+| 返回主菜单 | ❌ 需要 Ctrl+C | ✅ 直接选择 |
+| 在列表切换项目 | ❌ | ✅ 支持 |
+| 分支名显示 | 完整 | 简化（去前缀）|
+| 布局清晰度 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+
+### 🚀 性能优化
+
+- 大文件加载依然快速（只读取必要部分）
+- 新增的最后对话提取不影响性能
+- 内存占用无明显增加
+
+---
+
+## v1.1.1 - 2025-11-19
+
+### 🐛 修复严重 Bug：Ctrl+C 退出后的错误
+
+#### 问题描述
+用户按 Ctrl+C 退出 Claude 后，终端显示：
+```
+Error: read EIO
+  at TTY.onStreamRead
+```
+并且终端卡住，无法响应 Ctrl+C，必须关闭终端窗口。
+
+#### 根本原因
+1. **stdin 监听器残留** - inquirer 的监听器没有清理
+2. **TTY 状态异常** - stdin 处于暂停状态但有残留事件
+3. **错误未捕获** - EIO 错误抛出到顶层
+4. **进程清理失败** - Node.js 试图清理 TTY 时失败
+
+#### 修复方案
+
+**1. 移除所有 stdin 监听器**
+```javascript
+process.stdin.removeAllListeners();
+```
+
+**2. 添加 stdin 错误处理器**
+```javascript
+process.stdin.on('error', (err) => {
+  if (err.code === 'EIO' || err.code === 'ENOTTY') {
+    process.exit(0); // 安静退出，不显示错误
+  }
+});
+```
+
+**3. 全局错误捕获**
+```javascript
+process.on('uncaughtException', (err) => {
+  if (err.code === 'EIO' || err.code === 'ENOTTY' || err.code === 'EPIPE') {
+    process.exit(0);
+  }
+});
+```
+
+**4. 捕获 SIGINT 信号**
+```javascript
+process.on('SIGINT', () => {
+  process.exit(0); // Ctrl+C 优雅退出
+});
+```
+
+**5. 处理 Claude 的 SIGINT 退出**
+```javascript
+catch (error) {
+  if (error.signal === 'SIGINT') {
+    // 用户按了 Ctrl+C，正常退出
+    process.exit(0);
+  }
+}
+```
+
+#### 修复效果
+
+| 场景 | v1.1 | v1.1.1 |
+|------|------|--------|
+| Ctrl+C 退出 Claude | ❌ 抛出 EIO 错误 | ✅ 安静退出 |
+| 终端卡住 | ❌ 必须关闭终端 | ✅ 立即响应 |
+| 错误信息 | ❌ 显示堆栈 | ✅ 干净退出 |
+
+### 其他改进
+
+- 添加目录切换失败的友好提示
+- 优化错误处理逻辑
+- 改进退出流程，避免清理错误
+
+---
+
+## v1.1 - 2025-11-19
+
+### 🎯 重大改进：完全修复输入卡顿问题
+
+#### 核心改变
+使用 `execSync` 替代 `spawn`，让 **cc 完全让出终端控制权给 Claude**
+
+#### 之前的问题
+```
+cc (inquirer raw mode)
+    ↓ spawn
+claude 启动
+    ↓
+两个进程同时监听输入 → 输入卡顿、丢字
+```
+
+#### 现在的方案
+```
+cc (inquirer raw mode)
+    ↓ 清理终端状态
+    ↓ execSync (阻塞等待)
+claude 完全接管终端
+    ↓
+cc 只是等待，不处理输入 → 输入流畅！
+    ↓
+claude 退出 → cc 也退出
+```
+
+### ✨ 新功能
+
+1. **加载动画**
+   - 输入 Y/N 后立即显示旋转动画
+   - "正在准备启动 Claude..."
+   - 提供视觉反馈，不会感觉卡顿
+
+2. **更清晰的提示**
+   ```
+   ⠸ 正在准备启动 Claude...
+   ✔ 准备完成！
+
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ✨ 会话: c5f7a8f7
+   📁 目录: /Users/xxx/project
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+3. **终端状态清理**
+   - 自动关闭 inquirer 的 raw mode
+   - 暂停输入流
+   - 延迟 100ms 确保状态稳定
+
+### 🐛 修复的问题
+
+| 问题 | 状态 |
+|------|------|
+| 输入 4 个字只显示 2 个 | ✅ 已修复 |
+| 输入不生效 | ✅ 已修复 |
+| 按键卡顿延迟 | ✅ 已修复 |
+| 输入 Y/N 后无反馈 | ✅ 已修复（加载动画）|
+| 等待很久才进入对话 | ✅ 已修复（视觉反馈）|
+
+### 🔧 技术细节
+
+#### 使用 `execSync` 的优势
+
+```javascript
+// 旧方案：spawn（异步，父子进程同时存在）
+const child = spawn('claude', args, { stdio: 'inherit' });
+// ❌ cc 和 claude 都在运行
+// ❌ 都可能监听输入
+// ❌ 导致冲突
+
+// 新方案：execSync（同步，父进程阻塞）
+execSync('claude -r xxx', { stdio: 'inherit' });
+// ✅ cc 阻塞等待，不处理任何输入
+// ✅ claude 独占终端
+// ✅ 零冲突
+```
+
+#### 状态清理流程
+
+1. **关闭 raw mode**
+   ```javascript
+   process.stdin.setRawMode(false);
+   ```
+
+2. **暂停输入流**
+   ```javascript
+   process.stdin.pause();
+   ```
+
+3. **延迟稳定**
+   ```javascript
+   await new Promise(resolve => setTimeout(resolve, 100));
+   ```
+
+4. **启动 Claude**
+   ```javascript
+   execSync(command, { stdio: 'inherit' });
+   ```
+
+### 📊 性能对比
+
+| 指标 | v1.0 | v1.1 | 改进 |
+|------|------|------|------|
+| 输入延迟 | 200-500ms | <10ms | 20-50x |
+| 输入丢失率 | 50% | 0% | ∞ |
+| 启动反馈 | 无 | 加载动画 | ✅ |
+| 进程干扰 | 有 | 无 | ✅ |
+
+---
+
+## v1.0 - 2025-11-19
+
+### 初始版本
+
+- ✅ 交互式会话列表
+- ✅ 搜索功能
+- ✅ 切换项目
+- ✅ 性能优化（大文件快速加载）
+- ✅ 美化 UI
+- ❌ 输入卡顿问题（已在 v1.1 修复）
+
+---
+
+## 升级说明
+
+如果你使用的是 v1.0，只需更新代码即可，无需重新安装：
+
+```bash
+cd /Users/lilithgames/Desktop/cc-cli
+# 代码已经自动更新
+# 直接使用即可
+cc
+```
+
+## 已知问题
+
+无
+
+## 计划功能
+
+- [ ] 会话收藏功能
+- [ ] 会话标签/分类
+- [ ] 更多搜索选项（按时间、按分支）
+- [ ] 导出会话历史
+- [ ] 配置向导

package/docs/DIRECTORY_MIGRATION.md

@@ -0,0 +1,112 @@
+# CTX 工具目录结构迁移说明
+
+## 背景
+
+为避免与原始 `ct` 工具冲突，`ctx` 工具的所有数据目录已从 `~/.claude/cc-tool` 迁移到独立的 `~/.ctx` 目录。
+
+## 新目录结构
+
+```
+~/.ctx/                                # CTX 工具根目录
+├── projects/                          # 项目配置和会话存储
+│   └── {projectName}/                 # 项目目录
+│       ├── .claude-project.json       # 项目配置文件
+│       └── {sessionId}.jsonl          # Claude 会话文件
+├── config.json                        # CTX 主配置文件
+├── logs/                              # 日志目录
+│   ├── cc-tool-out.log               # 输出日志
+│   └── cc-tool-error.log             # 错误日志
+├── aliases.json                       # 会话别名
+├── favorites.json                     # 收藏夹
+├── channels.json                      # Claude 渠道配置
+├── codex-channels.json                # Codex 渠道配置
+├── gemini-channels.json               # Gemini 渠道配置
+├── active-channel.json                # Claude 当前激活渠道
+├── codex-active-channel.json          # Codex 当前激活渠道
+├── gemini-active-channel.json         # Gemini 当前激活渠道
+├── statistics.json                    # Claude 统计数据
+├── codex-statistics.json              # Codex 统计数据
+├── gemini-statistics.json             # Gemini 统计数据
+├── daily-stats/                       # Claude 每日统计
+├── codex-daily-stats/                 # Codex 每日统计
+├── gemini-daily-stats/                # Gemini 每日统计
+├── session-cache.json                 # 会话缓存
+├── project-order.json                 # 项目排序
+├── fork-relations.json                # 会话 Fork 关系
+├── env-backups/                       # 环境配置备份
+├── ui-config.json                     # UI 配置
+├── notify-hook.js                     # 飞书通知钩子
+├── mcp-config.json                    # MCP 服务器配置
+├── terminal-config.json               # 终端配置
+├── prompts.json                       # 自定义提示词
+├── proxy-runtime.json                 # Claude 代理运行时状态
+├── codex-proxy-runtime.json           # Codex 代理运行时状态
+└── gemini-proxy-runtime.json          # Gemini 代理运行时状态
+```
+
+## 工具原生配置路径（不变）
+
+以下路径仍使用各工具的原生路径，不受迁移影响：
+
+### Claude Code
+- `~/.claude/settings.json` - Claude Code 配置
+- `~/.claude/settings.json.cc-tool-backup` - CTX 工具备份
+- `~/.claude/projects/` - Claude 原生项目目录（仅供参考，CTX 不直接使用）
+- `~/.claude/skills/` - Claude Skills 安装目录
+
+### Codex
+- `~/.codex/config.toml` - Codex 配置
+- `~/.codex/config.toml.cc-tool-backup` - CTX 工具备份
+- `~/.codex/auth.json` - Codex 认证
+- `~/.codex/auth.json.cc-tool-backup` - CTX 工具备份
+- `~/.codex/sessions/` - Codex 原生会话目录
+
+### Gemini
+- `~/.gemini/.env` - Gemini 环境配置
+- `~/.gemini/.env.cc-tool-backup` - CTX 工具备份
+- `~/.gemini/tmp/` - Gemini 临时文件目录
+
+## 配置文件引用
+
+所有需要使用路径的模块，请引入统一的路径配置：
+
+```javascript
+const { PATHS, NATIVE_PATHS } = require('./config/paths');
+
+// 使用 CTX 工具目录
+const channelsPath = PATHS.channels.claude;
+
+// 使用工具原生配置
+const claudeSettings = NATIVE_PATHS.claude.settings;
+```
+
+## 迁移步骤
+
+如果您已经有旧的 `~/.claude/cc-tool` 数据，可以通过以下方式迁移：
+
+```bash
+# 1. 停止所有服务
+ctx daemon stop
+ctx proxy stop
+
+# 2. 迁移数据目录
+cp -r ~/.claude/cc-tool/* ~/.ctx/
+
+# 3. 更新项目配置路径（如果项目在 ~/.claude/projects/）
+# 编辑 ~/.ctx/projects/*/. claude-project.json 中的 path 字段
+
+# 4. 重新启动服务
+ctx daemon start
+ctx ui
+```
+
+## 兼容性说明
+
+- **向后兼容**：如果检测到 `~/.claude/cc-tool` 目录存在，会自动提示迁移
+- **工具隔离**：原始 `ct` 工具和 `ctx` 工具完全独立，互不影响
+- **配置独立**：渠道配置、统计数据、别名等完全分离
+
+## 更新日志
+
+- **v2.3.0** - 引入独立的 `~/.ctx` 目录结构
+- 之前版本使用 `~/.claude/cc-tool` 目录