claude-code-inspector 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+
+      - name: Build
+        run: yarn build
+
+      - name: Run tests
+        run: yarn test

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,33 @@
+name: Publish npm Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build
+        run: yarn build
+
+      - name: Run tests
+        run: yarn test
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,199 @@
+# CC Inspector
+
+CC Inspector 是一个用于监控和记录 Claude Code API 请求的开发者工具。它通过代理拦截 `/v1/messages` 请求，记录详细的请求/响应数据，并提供实时可视化面板。
+
+## 功能特性
+
+- **请求代理**: 拦截并转发 Claude Code API 请求到上游服务器
+- **实时日志**: 记录所有请求的 headers、body、response 和 streaming events
+- **监控面板**: 可视化展示请求状态、tokens 使用量、延迟和成本
+- **WebSocket 推送**: 实时推送新请求和更新到前端
+- **数据持久化**: 使用 SQLite 存储所有请求日志
+- **导出功能**: 支持 JSON 和 CSV 格式导出请求数据
+- **Token 统计**: 自动计算 input/output tokens 和缓存使用量
+- **成本估算**: 根据模型自动计算每次请求的成本
+
+## 技术栈
+
+- **框架**: Next.js 16 + React 19
+- **语言**: TypeScript
+- **数据库**: SQLite (better-sqlite3)
+- **WebSocket**: ws
+- **样式**: Tailwind CSS 4
+- **测试**: Vitest
+
+## 快速开始
+
+### 环境要求
+
+- Node.js 18+
+- npm / yarn / pnpm
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 启动开发服务器
+
+```bash
+npm run dev
+```
+
+访问以下地址：
+- **Dashboard**: http://localhost:3000/dashboard
+- **首页**: http://localhost:3000
+
+### 配置 LLM 服务 API
+
+CC Inspector 需要知道将请求转发到哪个 LLM 服务提供商。配置方式有两种：
+
+**方式 1：在项目根目录创建 `.env.local` 文件**
+
+```bash
+# .env.local
+UPSTREAM_BASE_URL=https://api.anthropic.com  # 上游 API 基础 URL
+UPSTREAM_API_KEY=your-api-key                 # 上游 API Key
+```
+
+**方式 2：在 Claude Code 全局配置中设置 (`~/.claude/settings.json`)**
+
+```json
+{
+  "env": {
+    "UPSTREAM_BASE_URL": "https://api.anthropic.com",
+    "UPSTREAM_API_KEY": "your-api-key"
+  }
+}
+```
+
+> 注意：如果未设置 `UPSTREAM_BASE_URL`，程序会自动使用 `ANTHROPIC_BASE_URL` 的值。
+
+### 配置 Claude Code 使用代理
+
+CC Inspector 启动后，需要让 Claude Code 将请求发送到代理服务器而不是直接发送到 Anthropic API。
+
+在 Claude Code 中执行以下命令配置 baseURL：
+
+```bash
+/mcp set anthropic_base_url http://localhost:3000/api/proxy
+```
+
+或者手动编辑 `~/.claude/settings.json`：
+
+```json
+{
+  "anthropic_base_url": "http://localhost:3000/api/proxy"
+}
+```
+
+配置完成后，Claude Code 的所有 API 请求都会先经过 CC Inspector，然后转发到上游 API。
+
+**验证配置：**
+
+1. 启动 CC Inspector：`npm run dev`
+2. 访问 Dashboard：http://localhost:3000/dashboard
+3. 在 Claude Code 中发起任意请求
+4. Dashboard 应显示新请求的记录
+
+## 项目结构
+
+```
+cc-inspector/
+├── app/                       # Next.js App Router
+│   ├── dashboard/            # 监控面板页面
+│   ├── api/                  # API 路由
+│   │   ├── proxy/           # 代理端点
+│   │   ├── requests/        # 请求日志 API
+│   │   └── events/          # SSE 事件 API
+│   └── v1/messages/         # 原始消息端点
+├── lib/                      # 核心逻辑库
+│   ├── proxy/               # 代理转发器
+│   │   ├── handlers.ts      # 请求处理器
+│   │   ├── forwarder.ts     # 转发器
+│   │   └── ws-server.ts     # WebSocket 服务器
+│   └── recorder/            # 数据记录器
+│       ├── index.ts         # 记录器入口
+│       ├── store.ts         # SQLite 存储
+│       └── schema.ts        # 数据库 Schema
+├── components/              # React 组件
+│   ├── JsonViewer.tsx      # JSON 查看器
+│   └── JsonModal.tsx       # JSON 模态框
+├── db/                      # SQLite 数据库文件
+└── server.ts               # 自定义服务器（WebSocket + Next.js）
+```
+
+## API 端点
+
+| 端点 | 方法 | 描述 |
+|------|------|------|
+| `/api/proxy` | POST | 代理转发请求到上游 |
+| `/api/requests` | GET | 获取最近的请求日志 |
+| `/api/requests/:id` | GET | 获取单个请求详情 |
+| `/api/requests/export` | GET | 导出请求数据（JSON/CSV） |
+| `/api/events` | GET | SSE 事件流 |
+| `/api/ws` | WebSocket | 实时推送连接 |
+
+## 数据模型
+
+请求日志包含以下字段：
+
+- `id`: 请求唯一标识
+- `session_id`: 会话标识
+- `endpoint`: 请求端点
+- `method`: HTTP 方法
+- `request_headers/body`: 请求头和请求体
+- `response_status/body/headers`: 响应状态、响应体和响应头
+- `streaming_events`: SSE 流式事件
+- `input_tokens/output_tokens`: 输入/输出 tokens
+- `cache_read_tokens/cache_creation_tokens`: 缓存读取/创建 tokens
+- `latency_ms`: 请求延迟（毫秒）
+- `first_token_ms`: 首 token 时间（毫秒）
+- `model`: 使用的模型
+- `cost_usd`: 估算成本（美元）
+- `error_message`: 错误信息（如有）
+
+## 脚本命令
+
+```bash
+# 开发
+npm run dev          # 启动开发服务器
+
+# 构建和运行
+npm run build        # 构建生产版本
+npm run start        # 启动生产服务器
+
+# 测试和检查
+npm run test         # 运行测试
+npm run lint         # ESLint 检查
+```
+
+## 数据库
+
+数据存储在 `db/inspector.sqlite`，包含以下表：
+
+- `request_logs`: 请求日志
+- `settings`: 配置设置
+
+## 注意事项
+
+1. **WebSocket**: 生产环境建议使用 `wss://` 连接
+2. **代理模式**: 确保 Claude Code 配置为使用代理端点
+3. **Token 计算**: 成本估算基于官方定价，仅供参考
+
+## 开发
+
+### 运行测试
+
+```bash
+npm run test
+```
+
+### 调试
+
+服务器日志会输出所有请求和 WebSocket 连接信息。查看控制台输出或使用 `db/inspector.sqlite` 直接查询数据库。
+
+## License
+
+MIT

package/app/api/events/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * SSE 实时推送端点
+ */
+export async function GET(request: NextRequest) {
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      // 发送初始连接消息
+      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'connected', timestamp: Date.now() })}\n\n`));
+
+      // 定期发送心跳
+      const heartbeat = setInterval(() => {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'heartbeat', timestamp: Date.now() })}\n\n`));
+      }, 30000);
+
+      // 当客户端断开时清理
+      request.signal.addEventListener('abort', () => {
+        clearInterval(heartbeat);
+        controller.close();
+      });
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    },
+  });
+}

package/app/api/proxy/route.ts

@@ -0,0 +1,42 @@
+import { handleMessages } from '@/lib/proxy/handlers';
+
+/**
+ * 代理服务器入口
+ * 拦截 /v1/messages 请求并记录
+ */
+export async function POST(request: Request) {
+  try {
+    // 提取请求头和 body
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    const body = await request.json();
+
+    // 转发到处理器
+    return handleMessages(request, body, headers);
+  } catch (error: any) {
+    console.error('Proxy error:', error);
+    return new Response(
+      JSON.stringify({ error: error?.message || 'Proxy error' }),
+      {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      }
+    );
+  }
+}
+
+/**
+ * GET 请求用于健康检查
+ */
+export async function GET() {
+  return new Response(
+    JSON.stringify({ status: 'ok', message: 'CC Inspector Proxy Running' }),
+    {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    }
+  );
+}

package/app/api/requests/[id]/route.ts

@@ -0,0 +1,82 @@
+import { NextResponse } from 'next/server';
+import { getStore } from '@/lib/recorder';
+
+/**
+ * 获取单个请求的详细信息
+ */
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const req = getStore().findById(id);
+
+    if (!req) {
+      return NextResponse.json({ error: 'Request not found' }, { status: 404 });
+    }
+
+    // 解析 JSON 字符串
+    let requestBody = null;
+    let responseBody = null;
+    let requestHeaders = null;
+    let responseHeaders = null;
+    let streamingEvents = null;
+
+    try {
+      requestBody = req.request_body ? JSON.parse(req.request_body) : null;
+    } catch {
+      requestBody = req.request_body;
+    }
+
+    try {
+      responseBody = req.response_body ? JSON.parse(req.response_body) : null;
+    } catch {
+      responseBody = req.response_body;
+    }
+
+    try {
+      requestHeaders = req.request_headers ? JSON.parse(req.request_headers) : null;
+    } catch {
+      requestHeaders = req.request_headers;
+    }
+
+    try {
+      responseHeaders = req.response_headers ? JSON.parse(req.response_headers) : null;
+    } catch {
+      responseHeaders = req.response_headers;
+    }
+
+    try {
+      streamingEvents = req.streaming_events ? JSON.parse(req.streaming_events) : null;
+    } catch {
+      streamingEvents = req.streaming_events;
+    }
+
+    return NextResponse.json({
+      id: req.id,
+      session_id: req.session_id,
+      endpoint: req.endpoint,
+      method: req.method,
+      request_headers: requestHeaders,
+      request_body: requestBody,
+      response_status: req.response_status,
+      response_headers: responseHeaders,
+      response_body: responseBody,
+      streaming_events: streamingEvents,
+      input_tokens: req.input_tokens,
+      output_tokens: req.output_tokens,
+      cache_read_tokens: req.cache_read_tokens,
+      cache_creation_tokens: req.cache_creation_tokens,
+      latency_ms: req.latency_ms,
+      first_token_ms: req.first_token_ms,
+      model: req.model,
+      cost_usd: req.cost_usd,
+      error_message: req.error_message,
+      created_at: req.created_at,
+    });
+  } catch (error: any) {
+    console.error('Failed to fetch request:', error);
+    return NextResponse.json({ error: error?.message || 'Failed to fetch request' }, { status: 500 });
+  }
+}

package/app/api/requests/export/route.ts

@@ -0,0 +1,124 @@
+import { NextResponse } from 'next/server';
+import { getStore } from '@/lib/recorder';
+
+/**
+ * 导出请求数据为 JSON 或 CSV 格式
+ */
+export async function GET(request: Request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const format = searchParams.get('format') || 'json';
+    const ids = searchParams.get('ids'); // 可选，导出指定 ID 的请求
+
+    let requests: any[];
+
+    if (ids) {
+      // 导出指定 ID 的请求
+      const idList = ids.split(',');
+      requests = idList.map((id) => getStore().findById(id.trim())).filter(Boolean) as any[];
+    } else {
+      // 导出最近的请求
+      requests = getStore().getRecentRequests(500);
+    }
+
+    // 转换为前端友好的格式
+    const formattedRequests = requests.map((r) => ({
+      id: r.id,
+      session_id: r.session_id,
+      endpoint: r.endpoint,
+      method: r.method,
+      response_status: r.status_code,
+      input_tokens: r.input_tokens,
+      output_tokens: r.output_tokens,
+      cache_read_tokens: r.cache_read_tokens,
+      cache_creation_tokens: r.cache_creation_tokens,
+      latency_ms: r.latency_ms,
+      first_token_ms: r.first_token_ms,
+      model: r.model,
+      cost_usd: r.cost_usd,
+      created_at: r.created_at,
+    }));
+
+    if (format === 'csv') {
+      return exportToCSV(formattedRequests);
+    } else {
+      return exportToJSON(formattedRequests);
+    }
+  } catch (error: any) {
+    console.error('Failed to export requests:', error);
+    return NextResponse.json({ error: error?.message || 'Failed to export requests' }, { status: 500 });
+  }
+}
+
+/**
+ * 导出为 JSON 格式
+ */
+function exportToJSON(requests: any[]) {
+  const jsonContent = JSON.stringify(requests, null, 2);
+
+  return new NextResponse(jsonContent, {
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Disposition': 'attachment; filename="cc-inspector-requests.json"',
+    },
+  });
+}
+
+/**
+ * 导出为 CSV 格式
+ */
+function exportToCSV(requests: any[]) {
+  const headers = [
+    'id',
+    'session_id',
+    'endpoint',
+    'method',
+    'response_status',
+    'input_tokens',
+    'output_tokens',
+    'cache_read_tokens',
+    'cache_creation_tokens',
+    'latency_ms',
+    'first_token_ms',
+    'model',
+    'cost_usd',
+    'created_at',
+  ];
+
+  const rows = requests.map((r) =>
+    [
+      r.id,
+      r.session_id || '',
+      r.endpoint,
+      r.method,
+      r.response_status || '',
+      r.input_tokens,
+      r.output_tokens,
+      r.cache_read_tokens,
+      r.cache_creation_tokens,
+      r.latency_ms || '',
+      r.first_token_ms || '',
+      r.model || '',
+      r.cost_usd || '',
+      r.created_at,
+    ]
+      .map((field) => {
+        // 处理包含逗号或引号的字段
+        const str = String(field);
+        if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+          return `"${str.replace(/"/g, '""')}"`;
+        }
+        return str;
+      })
+      .join(',')
+  );
+
+  const csvContent = [headers.join(','), ...rows].join('\n');
+
+  return new NextResponse(csvContent, {
+    headers: {
+      'Content-Type': 'text/csv',
+      'Content-Disposition': 'attachment; filename="cc-inspector-requests.csv"',
+    },
+  });
+}

package/app/api/requests/route.ts

@@ -0,0 +1,32 @@
+import { NextResponse } from 'next/server';
+import { getStore } from '@/lib/recorder';
+
+/**
+ * 获取最近的请求列表
+ */
+export async function GET() {
+  try {
+    const requests = getStore().getRecentRequests(100);
+    // 转换为前端需要的格式
+    const formattedRequests = requests.map((r: any) => ({
+      id: r.id,
+      session_id: r.session_id,
+      endpoint: r.endpoint,
+      method: r.method,
+      response_status: r.status_code,
+      input_tokens: r.input_tokens,
+      output_tokens: r.output_tokens,
+      cache_read_tokens: r.cache_read_tokens,
+      cache_creation_tokens: r.cache_creation_tokens,
+      latency_ms: r.latency_ms,
+      first_token_ms: r.first_token_ms,
+      model: r.model,
+      cost_usd: r.cost_usd,
+      created_at: r.created_at,
+    }));
+    return NextResponse.json(formattedRequests);
+  } catch (error: any) {
+    console.error('Failed to fetch requests:', error);
+    return NextResponse.json({ error: error?.message || 'Failed to fetch requests' }, { status: 500 });
+  }
+}