cc-team-viewer 1.4.25 → 1.4.26

package/README.md

@@ -1,8 +1,17 @@
 # CC-Team-Viewer
 
-Claude Code 请求监控系统，实时捕获并可视化展示 Claude Code 的所有 API 请求与响应(原始文本，不做阉割)。方便开发者监控自己的 Context，以便于 Vibe Coding 过程中回顾和排查问题。
+Claude Code 请求监控系统，实时捕获并可视化展示 Claude Code 的所有 API 请求与响应（原始文本，不做阉割）。方便开发者监控自己的 Context，以便于 Vibe Coding 过程中回顾和排查问题。
 
-## 使用方法
+## 功能概览
+
+| 视图模式 | 说明 |
+|---------|------|
+| **请求监控** | 原始 API 请求/响应列表 |
+| **对话模式** | Chat 风格展示对话历史 |
+| **团队视图** | 查看 Claude Agent Teams 团队协作 |
+| **会话视图** | 独立查看单个会话 |
+
+## 快速开始
 
 ### 安装
 
@@ -10,86 +19,152 @@ Claude Code 请求监控系统，实时捕获并可视化展示 Claude Code 的
 npm install -g cc-team-viewer
 ```
 
-### 运行与自动配置
+### 运行
 
 ```bash
 cctv
 ```
 
-该命令会自动检测本地 Claude Code 的安装方式（NPM 或 Native Install）并进行适配。
+首次运行会自动检测 Claude Code 安装方式并进行配置：
+- **NPM 模式**：注入拦截脚本到 Claude Code
+- **原生模式**：配置 Shell Hook 透明代理
 
-- **NPM 安装**：自动向 Claude Code 的 `cli.js` 中注入拦截脚本。
-- **Native Install**：自动检测 `claude` 二进制文件，配置本地透明代理，并设置 Zsh Shell Hook 自动转发流量。
+配置完成后，正常使用 `claude` 命令即可。访问 `http://localhost:7008` 查看监控界面。
 
-### 配置覆盖 (Configuration Override)
+### 常用命令
 
-如果您需要使用自定义 API 端点（例如企业代理），只需在 `~/.claude/settings.json` 中配置或设置 `ANTHROPIC_BASE_URL` 环境变量。`cctv` 会自动识别并正确转发请求。
+```bash
+cctv              # 启动（自动配置）
+cctv --version   # 查看版本
+cctv --uninstall # 卸载
+```
 
-### 静默模式 (Silent Mode)
+---
 
-默认情况下，`cctv` 在包裹 `claude` 运行时处于静默模式，确保您的终端输出保持整洁，与原生体验一致。所有日志都在后台捕获，并可通过 `http://localhost:7008` 查看。
+## 视图模式详解
 
-配置完成后，正常使用 `claude` 命令即可。访问 `http://localhost:7008` 查看监控界面。
+### 1. 请求监控（原文模式）
 
-### 常见问题排查 (Troubleshooting)
+实时捕获 Claude Code 发出的所有 API 请求，确保是原文（不被阉割）。
 
-如果你遇到无法启动的问题，有一个终极排查方案：
-第一步：任意目录打开 claude code；
-第二步：给claude code下指令，内容如下:
-```
-我已经安装了cc-team-viewer这个npm包，但是执行cctv以后仍然无法有效运行。查看cc-team-viewer的cli.js 和 findcc.js，根据具体的环境，适配本地的claude code的部署方式。适配的时候修改范围尽量约束在findcc.js中。
-```
-让Claude Code自己检查错误是比咨询任何人以及看任何文档更有效的手段！
+**核心功能：**
+- MainAgent / SubAgent 自动识别（Bash、Task、Plan、General）
+- Body Diff：对比相邻 MainAgent 请求的差异
+- Token 统计：输入/输出、缓存创建/读取、命中率
+- 兼容 Claude Code Router（CCR）及其他代理
 
-以上指令完成后，会更新findcc.js。如果你的项目工程经常需要本地部署。或者fork出去的代码要经常解决安装问题，保留这个文件就可以。下次直接copy 文件。现阶段很多项目和公司用claude code都不是mac部署，而是服务端托管部署，所以作者剥离了findcc.js 这个文件，方便后续跟踪cc-team-viewer的源代码更新。
+### 2. 对话模式
 
-### 卸载
+点击右上角「对话模式」切换。
 
-```bash
-cctv --uninstall
+**功能特性：**
+- 用户消息右对齐（蓝色气泡），Agent 回复左对齐
+- `thinking` 块默认折叠，点击展开
+- 用户选择型消息（AskUserQuestion）以问答形式展示
+- 双向同步：请求 ↔ 对话互相定位
+- 设置面板：工具结果、思考块默认折叠状态
+
+### 3. 团队视图
+
+当使用 Claude Code [Agent Teams](https://docs.anthropic.com/en/docs/claude-code/agent-teams) 时可见。
+
+**功能特性：**
+- 展示团队成员列表及活跃状态
+- 点击成员查看其完整对话历史
+- 实时消息推送（通过 SSE）
+- 未读消息计数
+
+### 4. 会话视图
+
+独立查看任意会话的详细内容。
+
+**入口：**
+- 项目列表 → 选择会话
+- 或通过 URL `/#/session/:sessionId` 直接访问
+
+---
+
+## 统计面板
+
+Header 区域的「数据统计」悬浮面板：
+
+- **缓存统计**：cache creation/read 数量及命中率
+- **缓存重建原因**：TTL、system/tools/model 变更、消息截断、key 变更
+- **工具使用**：按调用次数排序
+- **Skill 使用**：按调用次数排序
+- **概念帮助 (?)**：MainAgent、CacheRebuild 及工具文档
+
+---
+
+## 配置说明
+
+### 自定义 API 端点
+
+在 `~/.claude/settings.json` 中配置：
+
+```json
+{
+  "ANTHROPIC_BASE_URL": "https://your-proxy.com"
+}
 ```
 
-### 检查版本
+或设置环境变量 `ANTHROPIC_BASE_URL`。
+
+### 调试模式
 
 ```bash
-cctv --version
+CC_VIEWER_DEBUG=1 cctv run -- claude
 ```
 
-## 功能
+### 端口配置
 
-### 请求监控（原文模式）
-<img width="1500" height="720" alt="image" src="https://github.com/user-attachments/assets/519dd496-68bd-4e76-84d7-2a3d14ae3f61" />
-- 实时捕获 Claude Code 发出的所有 API 请求，确保是原文，而不是被阉割之后的日志（这很重要！！！）
-- 自动识别并标记 Main Agent 和 Sub Agent 请求（子类型：Bash、Task、Plan、General）
-- MainAgent 请求支持 Body Diff JSON，折叠展示与上一次 MainAgent 请求的差异（仅显示变更/新增字段）
-- 每个请求内联显示 Token 用量统计（输入/输出 Token、缓存创建/读取、命中率）
-- 兼容 Claude Code Router（CCR）及其他代理场景 — 通过 API 路径模式兜底匹配请求
+| 端口 | 用途 |
+|------|------|
+| 7008-7020 | API 服务器（自动选择） |
+| 5173+ | Vite 开发服务器 |
 
-### 对话模式
+---
 
-点击右上角「对话模式」按钮，将 Main Agent 的完整对话历史解析为聊天界面：
-<img width="1500" height="730" alt="image" src="https://github.com/user-attachments/assets/c973f142-748b-403f-b2b7-31a5d81e33e6" />
+## 工作原理
 
+```
+┌─────────────┐     fetch monkey patch      ┌──────────────────┐
+│ Claude Code │ ──────────────────────────▶ │ interceptor.js   │
+└─────────────┘                             │ (捕获所有请求)    │
+                                              └────────┬─────────┘
+                                                       │ JSONL
+                                                       ▼
+                                              ┌──────────────────┐
+                                              │ ~/.claude/logs/ │
+                                              │ <project>/       │
+                                              └────────┬─────────┘
+                                                       │ watchFile
+                                                       ▼
+                                              ┌──────────────────┐
+                                              │ Server (SSE)    │
+                                              │ + REST API       │
+                                              └────────┬─────────┘
+                                                       │
+                                                       ▼
+                                              ┌──────────────────┐
+                                              │ React UI         │
+                                              │ (多视图模式)      │
+                                              └──────────────────┘
+```
 
-- 暂不支持Agent Team的展示
-- 用户消息右对齐（蓝色气泡），Main Agent 回复左对齐（深色气泡）
-- `thinking` 块默认折叠，以 Markdown 渲染，点击展开查看思考过程；支持一键翻译（功能还不稳定）
-- 用户选择型消息（AskUserQuestion）以问答形式展示
-- 双向模式同步：切换到对话模式时自动定位到选中请求对应的对话；切回原文模式时自动定位到选中的请求
-- 设置面板：可切换工具结果和思考块的默认折叠状态
-- 手机端对话浏览：在手机端 CLI 模式下，点击顶部栏的「对话浏览」按钮，即可滑出只读对话视图，在手机上浏览完整对话历史
+---
 
+## 常见问题排查
 
-### 统计工具
+**无法启动？** 让 Claude Code 自己排查：
 
-Header 区域的「数据统计」悬浮面板：
-<img width="1500" height="729" alt="image" src="https://github.com/user-attachments/assets/b23f9a81-fc3d-4937-9700-e70d84e4e5ce" />
+```
+我已经安装了 cc-team-viewer 这个 npm 包，但是执行 cctv 以后仍然无法有效运行。查看 cc-team-viewer 的 cli.js 和 findcc.js，根据具体的环境，适配本地的 claude code 的部署方式。
+```
+
+这比自己查看文档更高效！
 
-- 显示 cache creation/read 数量及缓存命中率
-- 缓存重建统计：按原因分组（TTL、system/tools/model 变更、消息截断/修改、key 变更）显示次数和 cache_creation tokens
-- 工具使用统计：按调用次数排序展示各工具的调用频率
-- Skill 使用统计：按调用次数排序展示各 Skill 的调用频率
-- 概念帮助 (?) 图标：点击可查看 MainAgent、CacheRebuild 及各工具的内置文档
+---
 
 ## License