@myskyline_ai/ccdebug 0.2.4 → 0.2.5

package/README.en.md

@@ -0,0 +1,164 @@
+# CCDebug - Claude Code Debugging Tool
+
+CCDebug is a debugging tool for Claude Code. It records and visualizes Claude Code execution traces, and also supports “edit & replay” for a single LLM request so you can quickly pinpoint deviations caused by prompts/context/tool calls.
+
+This project is a derivative work based on [lemmy/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace).
+
+## ✨ Key Features
+
+### 📊 Timeline view for Claude Code execution
+
+![Timeline](./docs/img/时间线.png)
+
+- **Conversation timeline**: visualize the full conversation flow and tool call chain.
+- **Filter by step type**: filter timeline nodes by type (user message, assistant reply, tool call, etc.).
+- **Combined tool call + result**: tool input and its output are shown together for easier inspection.
+- **Session selector & sub-agent labels**: choose a main session log; sub-agent logs are shown using agent name/description.
+- **Project switching**: switch projects under `~/.claude/projects` in the Web UI to avoid running multiple servers.
+
+### 🛠️ Step-level LLM request debugging
+
+![LLM Request Debug](./docs/img/LLM请求调试.png)
+
+![Send Modified Request](./docs/img/发送修改后的LLM请求.png)
+
+- **Track LLM requests**: record all LLM request/response logs made by Claude Code.
+- **Replay requests**: edit the request payload and resend it to validate the response repeatedly.
+
+## 🚀 Quick Start
+
+### Install
+
+```bash
+# Recommended: install from npm
+npm install -g @myskyline_ai/ccdebug
+
+# Or install from a local tgz artifact
+# npm install -g /path/to/@myskyline_ai-ccdebug-x.y.z.tgz
+```
+
+### Basic usage
+
+#### 1) Launch Claude and record traffic
+
+```bash
+# Basic usage - start Claude and record logs
+ccdebug
+
+# Include all requests (not only /v1/messages)
+ccdebug --include-all-requests
+
+# Pass all subsequent arguments to Claude (example)
+ccdebug --run-with -p "Do the work as requested" --verbose
+```
+
+#### 2) Start the Web timeline server
+
+```bash
+# Start the Web server (default port: 3001, default project dir: current working directory)
+ccdebug --serve
+
+# Custom port
+ccdebug --serve --port 3001
+
+# Specify project directory
+ccdebug --serve --project /path/to/your/cc_workdir
+```
+
+### Log output directories
+
+- **Claude Code standard logs (for timeline)**: `.claude-trace/cclog/*.jsonl` (includes main logs and `agent-*.jsonl` sub-agent logs)
+- **Claude API tracing logs (for LLM debugging)**: `.claude-trace/tracelog/*.jsonl`
+- **Saved LLM request overrides (for replay)**: `.claude-trace/tracelog/llm_requests/*.json`
+
+Notes:
+
+- After a `ccdebug`-launched Claude session ends, CCDebug automatically copies the corresponding Claude Code standard logs into `.claude-trace/cclog/`, and renames the API tracing log to `{sessionId}.jsonl`.
+- If you are using the **native Claude Code binary** (not the npm script version), CCDebug cannot intercept API requests, so LLM request debugging won’t work. You can still use the Web UI to view existing standard logs.
+
+## 📋 CLI Options
+
+| Option | Description |
+|------|------|
+| `--serve` | Start the Web timeline server |
+| `--log, -l` | Start the Web timeline server (`--log` without a value behaves like `--serve`; prefer `-l` to avoid confusion with `--log <name>`) |
+| `--port <number>` | Web server port (default: 3001) |
+| `--project <path>` | Project directory |
+| `--run-with <args>` | Pass subsequent args to the Claude process |
+| `--include-all-requests` | Capture all Claude-related requests, not only chat requests |
+| `--no-open` | Do not auto-open the generated HTML in a browser (currently only effective for `--generate-html`) |
+| `--claude-path <path>` | Custom path to the Claude binary or `cli.js` |
+| `--log <name>` | Base name for API tracing logs (affects files under `.claude-trace/tracelog/`) |
+| `--generate-html <input.jsonl> [output.html]` | Generate an HTML report from a JSONL file |
+| `--index` | Generate conversation summaries & an index under `.claude-trace/` (will call Claude and incur token usage) |
+| `--extract-token` | Extract OAuth token and exit |
+| `--version, -v` | Print version |
+| `--help, -h` | Show help |
+
+## 🏗️ Architecture
+
+### Core components
+
+- **HTTP/API interceptor**: intercepts Node.js HTTP/HTTPS + fetch to capture Anthropic/Bedrock requests and responses.
+- **Standard log collection**: on exit, copies main and sub-agent Claude Code logs into `.claude-trace/cclog/`.
+- **Web server**: Express provides APIs for file listing, session management, project switching, and LLM request read/save/replay.
+- **Frontend**: Vue 3 + Vite + Pinia + Arco Design.
+
+### Data flow
+
+```
+HTTP request/response → interceptor → raw JSONL → processors → structured data → Web UI
+```
+
+## 📁 Project Structure
+
+```
+ccdebug/
+├── src/                     # CLI & interceptors
+│   ├── cli.ts              # CLI entry
+│   ├── interceptor.ts      # API interception and tracelog recording
+│   ├── html-generator.ts   # HTML report generator (based on frontend)
+│   └── index-generator.ts  # conversation summaries and index
+├── web/                     # Web timeline site (Vite + Vue 3)
+│   ├── src/                # frontend source
+│   ├── dist/               # build output
+│   └── server/             # Express backend (required by CLI to start)
+├── frontend/                # standalone HTML report frontend (bundle injected into HTML)
+├── scripts/                 # packaging scripts
+└── docs/                    # docs and design notes
+```
+
+## 🔧 Development
+
+### Requirements
+
+- Node.js >= 16.0.0
+- npm or yarn
+
+### Local development
+
+```bash
+# Clone
+git clone https://github.com/ThinkingBeing/ccdebug.git
+cd ccdebug
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Dev mode (watch core code + web frontend)
+npm run dev
+
+# Run CLI via tsx (for development/debugging)
+npx tsx src/cli.ts --help
+npx tsx src/cli.ts --serve --port 3001 --project /path/to/your/cc_workdir
+
+# Package (artifacts will be placed under release/)
+npm run package
+```
+
+## 🔗 Links
+
+- [GitHub repository](https://github.com/ThinkingBeing/ccdebug)

package/README.md

@@ -1,7 +1,9 @@
 # CCDebug - Claude Code 调试工具
 
 
-CCDebug 是一个针对 Claude Code的简单调试工具，能够记录、分析和可视化您与 Claude API 的所有交互过程。通过拦截 HTTP 请求，CCDebug 提供了详细的对话时间线、工具调用追踪和多种数据展示视图。本项目基于 [lemmy/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace) 二次开发。
+CCDebug 是一个针对 Claude Code 的调试工具，用于记录并可视化 CC 运行轨迹，同时支持对单个 LLM 请求进行“修改-重放”，帮助你快速定位提示词/上下文/工具调用导致的偏差。本项目基于 [lemmy/claude-trace](https://github.com/badlogic/lemmy/tree/main/apps/claude-trace) 二次开发。
+
+英文版：[README.en.md](./README.en.md)
 
 ## ✨ 主要功能
 
@@ -10,6 +12,8 @@ CCDebug 是一个针对 Claude Code的简单调试工具，能够记录、分析
 - **对话时间线**: 直观展示完整的对话流程和工具调用链
 - **按节点类型过滤**: 按不同类型的时间线节点过滤，如用户输入、LLM回复、工具调用等
 - **工具调用和结果整合展示**: 将工具调用和调用结果整合在一个节点展示，方便查看工具调用的输入参数和输出结果
+- **会话选择与子代理识别**: 支持主日志会话选择，子代理日志下拉框显示 agent 名称/描述
+- **项目切换**: Web 站点内可切换到 `~/.claude/projects` 下的其他项目，避免重复启动多个站点
 
 ### 🛠️ 对CC步骤单点调试
 ![对CC步骤单点调试](./docs/img/LLM请求调试.png)
@@ -19,11 +23,14 @@ CCDebug 是一个针对 Claude Code的简单调试工具，能够记录、分析
 
 ## 🚀 快速开始
 
-### 安装（暂仅支持本地包安装）
+### 安装
 
 ```bash
-# 全局安装
-npm install -g @myskyline_ai-ccdebug-0.1.1.tgz
+# 推荐：从 npm 全局安装
+npm install -g @myskyline_ai/ccdebug
+
+# 或：安装本地/发布产物 tgz
+# npm install -g /path/to/@myskyline_ai-ccdebug-x.y.z.tgz
 ```
 
 ### 基本使用
@@ -36,40 +43,62 @@ ccdebug
 
 # 包含所有请求（不仅仅是对话）
 ccdebug --include-all-requests
+
+# 将后续参数传递给 Claude 进程（示例）
+ccdebug --run-with -p "请按要求工作" --verbose
 ```
 
 #### 2. 启动 Web 站点查看时间线轨迹
 
 ```bash
-# 启动 Web 服务器查看时间线
-ccdebug --serve --port 3001 --project /path/to/your/cc_workdir
+# 启动 Web 服务器查看时间线（默认端口 3001，默认项目目录为当前目录）
+ccdebug --serve
+
+# 在自定义端口启动
+ccdebug --serve --port 3001
+
+# 指定项目目录启动
+ccdebug --serve --project /path/to/your/cc_workdir
 ```
 
+### 日志输出目录
+
+- **CC 标准日志（用于时间线）**: `.claude-trace/cclog/*.jsonl`（包含主日志与 `agent-*.jsonl` 子代理日志）
+- **CC API 跟踪日志（用于 LLM 请求调试）**: `.claude-trace/tracelog/*.jsonl`
+- **已保存的 LLM 请求（用于覆盖/重放）**: `.claude-trace/tracelog/llm_requests/*.json`
+
+说明：
+
+- 运行 `ccdebug` 启动 Claude 会话后，会将本次会话对应的 CC 标准日志自动拷贝到 `.claude-trace/cclog/`，并将 API 跟踪日志重命名为 `{sessionId}.jsonl`。
+- 如果你使用的是 Claude Code **原生二进制版本**（非 NPM 脚本形式），CCDebug 无法拦截 API 请求，LLM 请求调试能力将不可用（仍可通过 Web 站点查看已有 CC 标准日志）。
+
 ## 📋 命令行选项
 
 | 选项 | 描述 |
 |------|------|
-| `--extract-token` | 提取 OAuth token 并退出 |
-| `--generate-html` | 从 JSONL 文件生成 HTML 报告 |
-| `--index` | 为 .claude-trace/ 目录生成对话摘要和索引 |
 | `--serve` | 启动 Web 时间线服务器 |
+| `--log, -l` | 启动 Web 时间线服务器（当 `--log` 不带参数时等同于 `--serve`；建议用 `-l` 避免与 `--log <name>` 混淆） |
 | `--port <number>` | 指定 Web 服务器端口（默认 3001） |
 | `--project <path>` | 指定项目目录路径 |
 | `--run-with <args>` | 将后续参数传递给 Claude 进程 |
 | `--include-all-requests` | 包含所有 fetch 请求，而不仅仅是对话 |
-| `--no-open` | 不在浏览器中自动打开生成的 HTML |
-| `--log <name>` | 指定自定义日志文件基础名称 |
+| `--no-open` | 不在浏览器中自动打开生成的 HTML（当前仅对 `--generate-html` 生效） |
 | `--claude-path <path>` | 指定 Claude 二进制文件的自定义路径 |
+| `--log <name>` | 指定 API 跟踪日志基础名称（影响 `.claude-trace/tracelog/` 下文件名） |
+| `--generate-html <input.jsonl> [output.html]` | 从 JSONL 文件生成 HTML 报告 |
+| `--index` | 为 `.claude-trace/` 目录生成对话摘要和索引（会调用 Claude 产生额外 token 消耗） |
+| `--extract-token` | 提取 OAuth token 并退出 |
+| `--version, -v` | 显示版本信息 |
 | `--help, -h` | 显示帮助信息 |
 
 ## 🏗️ 技术架构
 
 ### 核心组件
 
-- **HTTP 拦截器**: 基于 Node.js 的 HTTP/HTTPS 模块拦截机制
-- **数据处理管道**: 将原始 HTTP 数据转换为结构化的对话数据
-- **Web 服务器**: Express.js + Socket.IO 实现实时数据推送
-- **前端界面**: Vue.js + Arco Design 构建的现代化 Web 界面
+- **HTTP/API 拦截器**: 基于 Node.js 的 HTTP/HTTPS + fetch 拦截机制，记录对 Anthropic/Bedrock 的请求与响应
+- **CC 标准日志整理**: 退出会话时自动将 CC 标准日志（主日志与子代理日志）拷贝到 `.claude-trace/cclog/`
+- **Web 服务器**: Express.js 提供文件列表、会话管理、项目切换、LLM 请求读取/保存/重放等 API
+- **前端界面**: Vue 3 + Vite + Pinia + Arco Design
 
 ### 数据流程
 
@@ -81,17 +110,18 @@ HTTP 请求/响应 → 拦截器 → 原始数据(JSONL) → 数据处理器 →
 
 ```
 ccdebug/
-├── src/                    # CLI 工具源码
-│   ├── cli.ts             # 命令行入口
-│   ├── interceptor.ts     # HTTP 拦截器
-│   ├── html-generator.ts  # HTML 报告生成器
-│   └── types.ts           # 类型定义
-├── web/                   # Web 界面
-│   ├── src/               # Vue.js 前端源码
-│   └── server/            # Express.js 后端服务
-├── frontend/              # 独立 HTML 报告前端
-└── docs/                  # 项目文档
-└── ccdemo/                # cc示例项目的工作目录
+├── src/                     # CLI 与拦截器
+│   ├── cli.ts              # 命令行入口
+│   ├── interceptor.ts      # API 拦截与 tracelog 记录
+│   ├── html-generator.ts   # HTML 报告生成器（基于 frontend）
+│   └── index-generator.ts  # 对话摘要与索引生成
+├── web/                     # Web 时间线站点（Vite + Vue 3）
+│   ├── src/                # 前端源码
+│   ├── dist/               # 构建产物
+│   └── server/             # Express 后端（供 CLI 直接 require 启动）
+├── frontend/                # 独立 HTML 报告前端（bundle 注入到 HTML）
+├── scripts/                 # 打包脚本
+└── docs/                    # 文档与设计说明
 ```
 
 ## 🔧 开发
@@ -114,11 +144,12 @@ npm install
 # 构建项目
 npm run build
 
-# 运行cc，执行cc任务
-npx tsx src/cli.ts
+# 开发模式（同时 watch 核心代码 + 前端）
+npm run dev
 
-# 退出cc后，运行web站点
-npx tsx src/cli.ts --serve --port 3001 --project ./ccdemo
+# 使用 tsx 直接运行 CLI（开发调试用）
+npx tsx src/cli.ts --help
+npx tsx src/cli.ts --serve --port 3001 --project /path/to/your/cc_workdir
 
 # 功能ok后打包，包会出现在release目录
 npm run package

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@myskyline_ai/ccdebug",
-	"version": "0.2.4",
+	"version": "0.2.5",
 	"description": "跟踪记录CC请求，可针对特定请求反复调试验证，以更直观的时间线形式展示CC日志",
 	"publishConfig": {
 		"access": "public"