@tonyclaw/llm-inspector 1.8.0 → 1.9.0

package/README.md

@@ -10,63 +10,22 @@ llm-inspector 是一个 LLM API 透明代理，能够捕获 AI 编程工具（Cl
 
 ---
 
-## 核心特性 / Features
+## 文档目录
 
-### 请求重放调试 / Request Replay
-
-![Replay](docs/Replay.png)
-
-回放任意历史请求，快速复现问题。支持流式/非流式两种模式。
-
-### 实时 SSE 流更新 / Real-Time SSE Streaming
-
-SSE 流式响应实时推送，无需轮询，即时查看每个数据块。
-
-### 健康检查 / Health Check
-
-`GET /api/health` 端点，支持 Docker Compose 健康检查和容器编排。
-
-### 支持多种 AI 编程工具 / Multiple AI Coding Tools
-
-```bash
-# Claude Code
-ANTHROPIC_BASE_URL=http://localhost:25947/proxy claude
-
-# OpenCode
-LLM_BASE_URL=http://localhost:25947/proxy opencode
-
-# Cursor, Cody 等 / etc.
-ANTHROPIC_BASE_URL=http://localhost:25947/proxy <your-tool>
-```
-
-### 支持双 API 格式 / Dual API Format Support
-
-| API 格式 | 端点 | 工具 |
-|----------|------|------|
-| Anthropic | `/v1/messages` | Claude Code 等 |
-| OpenAI | `/v1/chat/completions` | OpenAI、DeepSeek 等 |
-
-### 多 LLM 提供商支持 / Multi-Provider Support
-
-| 提供商 | 模型前缀 | API 格式 |
-|--------|---------|----------|
-| Anthropic | `claude-*` | Anthropic |
-| OpenAI | `gpt-*`, `o1-*`, `o3-*` | OpenAI |
-| DeepSeek | `deepseek-*` | OpenAI |
-| MiniMax | `MiniMax-*` | Anthropic/OpenAI |
-| Qwen | `qwen-*` | OpenAI |
-| ZhipuAI | `glm-*` | OpenAI |
+- [特性 (Features)](docs/Features.md) - 核心功能介绍
+- [安装 (Installation)](docs/Installation.md) - 安装指南
+- [使用 (Usage)](docs/Usage.md) - 详细使用说明
+- [架构 (Architecture)](docs/Architecture.md) - 系统架构
+- [开发 (Development)](docs/Development.md) - 开发指南
 
 ---
 
-## 快速开始 / Quick Start
+## 快速开始
 
-### npm 安装（推荐）
+### npm 安装
 
 ```bash
 npm install -g @tonyclaw/llm-inspector
-
-# 启动
 llm-inspector
 ```
 
@@ -79,170 +38,10 @@ docker-compose up -d
 ### 源码运行
 
 ```bash
-# 安装依赖
 bun install
-
-# 启动开发服务器
 bun run dev
 ```
 
-设置环境变量并启动 AI 编程工具：
-
-```bash
-# Claude Code
-ANTHROPIC_BASE_URL=http://localhost:25947/proxy claude
-
-# OpenCode
-LLM_BASE_URL=http://localhost:25947/proxy opencode
-```
-
 打开浏览器访问 http://localhost:25947 查看实时捕获的请求。
 
 ![Proxy Hello](docs/Proxy%20Hello.png)
-
----
-
-## Docker 部署 / Docker Deployment
-
-```bash
-# 构建并启动
-docker-compose up -d
-
-# 查看日志
-docker-compose logs -f
-
-# 停止
-docker-compose down
-```
-
-容器默认暴露 `25947` 端口，包含健康检查，可直接接入 Docker Compose 或 Kubernetes。
-
----
-
-## 实时仪表盘 / Real-Time Dashboard
-
-### 日志列表 / Log List
-
-虚拟滚动列表展示每个被代理的请求，每条记录显示：
-
-- **模型标签** — 如 `claude-sonnet-4-20250514`
-- **API 格式** — Anthropic（橙色）/ OpenAI（蓝色）
-- **响应状态** — 绿色 2xx / 黄色 4xx / 红色 5xx
-- **Token 用量** — 输入 / 输出，自动 K/M 格式化
-- **流式标识** — 区分流式与非流式响应
-
-### 解析响应视图 / Parsed Response View
-
-**Anthropic 响应：**
-- 模型、停止原因、Token 用量
-- 内容块分类渲染：文本（Markdown）、思考（可折叠紫色块）、工具调用（可折叠蓝色块）
-
-**OpenAI 响应：**
-- 模型、结束原因、Token 用量
-- 推理内容（紫色块）、文本、函数调用
-
-### SSE 流式数据 / SSE Streaming
-
-![Full Mode](docs/FULL.png)
-
-流式响应显示：
-- **SSE 数据块面板** — 懒加载，按索引分组
-- **JSON 树查看器** — 类型颜色编码（字符串绿/数字黄/布尔蓝）
-- **重建响应** — 从 SSE 片段重建完整 JSON
-
-### 提供商测试 / Provider Testing
-
-![Provider Test](docs/Provider%20Test.png)
-
-内置连接测试功能，同时测试非流式和流式连接，测试结果直接显示在日志列表中。
-
----
-
-## 架构 / Architecture
-
-```
-AI Coding Tool  →  llm-inspector (:25947/proxy/*)  →  LLM Provider
-                                  ↓
-                            Web UI (:25947)
-```
-
-| 模块 | 路径 | 职责 |
-|------|------|------|
-| 代理处理器 | `src/proxy/handler.ts` | HTTP 代理、请求/响应捕获、SSE 流式 |
-| 格式处理器 | `src/proxy/formats/` | Anthropic/OpenAI 格式抽象 |
-| 提供商管理 | `src/proxy/providers.ts` | 多提供商配置存储 |
-| 格式协议 | `src/proxy/formats/anthropic/` `src/proxy/formats/openai/` | 格式特定解析器 |
-| 客户端追踪 | `src/proxy/socketTracker.ts` | PID、CWD、项目名 |
-| 日志存储 | `src/proxy/logger.ts`, `store.ts` | 内存缓冲区 + 磁盘持久化 |
-
----
-
-## 命令行 / CLI
-
-```bash
-llm-inspector                    # 启动服务
-llm-inspector --port 3000       # 指定端口
-llm-inspector --no-open         # 禁止自动打开浏览器
-```
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `--port`, `-p` | `25947` | 监听端口 |
-| `--open` | `true` | 启动时自动打开浏览器 |
-
-### 环境变量
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `PORT` | `25947` | 服务器端口 |
-| `LOG_DIR` | `~/.llm-inspector/logs/` | 日志存储目录 |
-| `LOG_RETENTION_DAYS` | `7` | 日志保留天数 |
-| `CHUNKS_DIR` | `~/.llm-inspector/chunks/` | SSE 数据块存储 |
-
----
-
-## 直接测试 / Direct Testing
-
-不通过 AI 编程工具，直接用 curl 测试提供商连接：
-
-```bash
-# Anthropic
-curl http://localhost:25947/proxy/v1/messages \
-  -H 'content-type: application/json' \
-  -d '{"model":"claude-sonnet-4-20250514","max_tokens":100,"messages":[{"role":"user","content":"hello"}]}'
-
-# OpenAI
-curl http://localhost:25947/proxy/v1/chat/completions \
-  -H 'content-type: application/json' \
-  -d '{"model":"gpt-4o-mini","max_tokens":100,"messages":[{"role":"user","content":"hello"}]}'
-```
-
----
-
-## 开发 / Development
-
-```bash
-# 类型检查、Lint、格式化
-bun run check
-
-# 生产构建
-bun run build
-```
-
----
-
-## 发布 / Publishing
-
-```bash
-# 1. 更新版本号
-git commit -m "chore: bump version"
-git tag v<version>
-
-# 2. 推送代码和标签
-git push origin main --tags
-
-# 3. 发布到 npm
-npm publish --access public
-```
-
-包名：`@tonyclaw/llm-inspector`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/llm-inspector",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "description": "LLM API proxy inspector — captures and displays requests/responses from AI coding tools in a web UI",
   "license": "MIT",

package/src/components/ProxyViewerContainer.tsx

@@ -63,6 +63,7 @@ export function ProxyViewerContainer(): JSX.Element {
   const [viewMode, setViewMode] = useState<"simple" | "full">("simple");
   const [error, setError] = useState<string | null>(null);
   const eventSourceRef = useRef<EventSource | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const fetchSessionsAndModels = useCallback(async () => {
     try {
@@ -152,8 +153,12 @@ export function ProxyViewerContainer(): JSX.Element {
     es.onerror = () => {
       setError("SSE connection lost, reconnecting...");
       es.close();
+      // Clear any existing reconnect timeout
+      if (reconnectTimeoutRef.current !== null) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
       // Reconnect after 3 seconds
-      setTimeout(connectSSE, 3000);
+      reconnectTimeoutRef.current = setTimeout(connectSSE, 3000);
     };
 
     void fetchSessionsAndModels();
@@ -166,6 +171,10 @@ export function ProxyViewerContainer(): JSX.Element {
         eventSourceRef.current.close();
         eventSourceRef.current = null;
       }
+      if (reconnectTimeoutRef.current !== null) {
+        clearTimeout(reconnectTimeoutRef.current);
+        reconnectTimeoutRef.current = null;
+      }
     };
   }, [connectSSE]);
 

package/src/components/providers/ProviderCard.tsx

@@ -20,7 +20,7 @@ import {
 } from "lucide-react";
 import type { ProviderConfig } from "../../proxy/providers";
 
-// Known provider documentation links
+// Known provider documentation links (fallback when apiDocsUrl is not configured)
 const KNOWN_PROVIDER_DOCS: Record<string, string> = {
   deepseek: "https://api-docs.deepseek.com/zh-cn/",
 };
@@ -169,6 +169,13 @@ export function ProviderCard({
 }: ProviderCardProps): JSX.Element {
   const [showApiKey, setShowApiKey] = useState(false);
 
+  // Get docs URL: use provider.apiDocsUrl if configured, otherwise check KNOWN_PROVIDER_DOCS
+  const docsUrl =
+    provider.apiDocsUrl ??
+    Object.entries(KNOWN_PROVIDER_DOCS).find(([keyword]) =>
+      provider.name.toLowerCase().includes(keyword),
+    )?.[1];
+
   return (
     <div className="border rounded-lg p-4 flex flex-col gap-3 bg-card">
       <div className="flex items-start justify-between gap-2">
@@ -179,20 +186,17 @@ export function ProviderCard({
               : provider.name}
           </span>
         </div>
-        {Object.entries(KNOWN_PROVIDER_DOCS).map(([keyword, url]) =>
-          provider.name.toLowerCase().includes(keyword) ? (
-            <a
-              key={keyword}
-              href={url}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="text-muted-foreground hover:text-foreground transition-colors flex items-center gap-1 text-xs"
-              title="View API documentation"
-            >
-              <ExternalLink className="size-3" />
-              <span className="sr-only">Docs</span>
-            </a>
-          ) : null,
+        {docsUrl !== undefined && (
+          <a
+            href={docsUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-muted-foreground hover:text-foreground transition-colors flex items-center gap-1 text-xs"
+            title="View API documentation"
+          >
+            <ExternalLink className="size-3" />
+            <span className="sr-only">Docs</span>
+          </a>
         )}
       </div>
 

package/src/components/providers/ProviderForm.tsx

@@ -41,6 +41,7 @@ type ProviderFormProps = {
     model?: string;
     format: "anthropic" | "openai";
     baseUrl?: string;
+    apiDocsUrl?: string;
   }) => void;
   onCancel: () => void;
 };
@@ -51,6 +52,7 @@ export function ProviderForm({ provider, onSubmit, onCancel }: ProviderFormProps
   const [model, setModel] = useState(provider?.model ?? "");
   const [format, setFormat] = useState<"anthropic" | "openai">(provider?.format ?? "anthropic");
   const [baseUrl, setBaseUrl] = useState(provider?.baseUrl ?? "");
+  const [apiDocsUrl, setApiDocsUrl] = useState(provider?.apiDocsUrl ?? "");
   const [errors, setErrors] = useState<Record<string, string>>({});
   const [isSubmitting, setIsSubmitting] = useState(false);
 
@@ -69,6 +71,7 @@ export function ProviderForm({ provider, onSubmit, onCancel }: ProviderFormProps
       setModel(provider.model ?? "");
       setFormat(provider.format ?? "anthropic");
       setBaseUrl(provider.baseUrl ?? "");
+      setApiDocsUrl(provider.apiDocsUrl ?? "");
       setManualBaseUrlOverride(false);
     }
   }, [provider]);
@@ -135,6 +138,7 @@ export function ProviderForm({ provider, onSubmit, onCancel }: ProviderFormProps
         model: model.trim() || undefined,
         format,
         baseUrl: baseUrl.trim() || undefined,
+        apiDocsUrl: apiDocsUrl.trim() || undefined,
       });
     } finally {
       setIsSubmitting(false);
@@ -246,6 +250,23 @@ export function ProviderForm({ provider, onSubmit, onCancel }: ProviderFormProps
         <p className="text-xs text-muted-foreground">Base URL for the provider API.</p>
       </div>
 
+      <div className="space-y-2">
+        <label htmlFor="provider-api-docs-url" className="text-sm font-medium">
+          API Docs URL
+        </label>
+        <input
+          id="provider-api-docs-url"
+          type="text"
+          value={apiDocsUrl}
+          onChange={(e) => setApiDocsUrl(e.target.value)}
+          placeholder="https://api.example.com/docs"
+          className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:border-ring focus-visible:outline-ring focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50"
+        />
+        <p className="text-xs text-muted-foreground">
+          Optional API documentation URL. If not set, uses known provider docs.
+        </p>
+      </div>
+
       <div className="flex gap-2 justify-end pt-2">
         <Button type="button" variant="outline" onClick={onCancel} disabled={isSubmitting}>
           Cancel

package/src/components/proxy-viewer/LogEntry.tsx

@@ -182,6 +182,12 @@ export const LogEntry = memo(function LogEntry({
 
               <TabsContent value="raw">
                 <div className="px-4 py-3 space-y-3">
+                  {log.error !== undefined && log.error !== null && (
+                    <div className="rounded border border-destructive/50 bg-destructive/10 p-3 text-xs">
+                      <div className="font-semibold text-destructive mb-1">SSE Error</div>
+                      <div className="text-muted-foreground font-mono">{log.error}</div>
+                    </div>
+                  )}
                   <div className="flex justify-end">
                     <CopyButton
                       text={log.responseText}
@@ -215,6 +221,7 @@ export const LogEntry = memo(function LogEntry({
                     cacheCreationInputTokens={log.cacheCreationInputTokens}
                     cacheReadInputTokens={log.cacheReadInputTokens}
                     apiFormat={log.apiFormat}
+                    error={log.error}
                   />
                 </div>
               </TabsContent>

package/src/components/proxy-viewer/ResponseView.tsx

@@ -19,6 +19,8 @@ export type ResponseViewProps = {
   cacheCreationInputTokens?: number | null;
   cacheReadInputTokens?: number | null;
   apiFormat?: "anthropic" | "openai" | "unknown";
+  /** SSE error message from streaming response */
+  error?: string | null;
 };
 
 function getStatusClasses(category: StatusCategory): string {
@@ -95,8 +97,9 @@ export function ResponseView({
   cacheCreationInputTokens,
   cacheReadInputTokens,
   apiFormat,
+  error,
 }: ResponseViewProps): JSX.Element {
-  if (responseText === null) {
+  if (responseText === null && error === undefined) {
     return (
       <div className="flex items-center gap-2 py-3">
         <StatusIndicator status={responseStatus} />
@@ -105,18 +108,41 @@ export function ResponseView({
     );
   }
 
-  const isError = responseStatus !== null && responseStatus >= 400;
+  const isHttpError = responseStatus !== null && responseStatus >= 400;
 
-  if (isError) {
+  if (isHttpError) {
     return (
       <div className="space-y-2">
         <StatusIndicator status={responseStatus} />
-        <ErrorResponseView text={responseText} />
+        <ErrorResponseView text={responseText ?? ""} />
+        {error !== undefined && error !== null && (
+          <div className="rounded border border-destructive/50 bg-destructive/10 p-3 text-xs">
+            <div className="font-semibold text-destructive mb-1">SSE Error</div>
+            <div className="text-muted-foreground font-mono">{error}</div>
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  if (error !== undefined && error !== null) {
+    return (
+      <div className="space-y-2">
+        <StatusIndicator status={responseStatus} />
+        <div className="rounded border border-destructive/50 bg-destructive/10 p-3 text-xs">
+          <div className="font-semibold text-destructive mb-1">SSE Error</div>
+          <div className="text-muted-foreground font-mono">{error}</div>
+        </div>
+        {responseText !== null && (
+          <div className="mt-2">
+            <ErrorResponseView text={responseText} />
+          </div>
+        )}
       </div>
     );
   }
 
-  const parsed = parseResponse(responseText, apiFormat);
+  const parsed = responseText !== null ? parseResponse(responseText, apiFormat) : null;
 
   if (parsed !== null) {
     return (
@@ -155,7 +181,7 @@ export function ResponseView({
           </span>
         )}
       </div>
-      <MarkdownFallbackView text={responseText} />
+      <MarkdownFallbackView text={responseText ?? ""} />
     </div>
   );
 }

package/src/proxy/chunkStorage.ts

@@ -8,6 +8,7 @@ import {
   copyFileSync,
 } from "node:fs";
 import { join, isAbsolute } from "node:path";
+import { logger } from "./logger";
 import { z } from "zod";
 import { JsonValueSchema, type StreamingChunk } from "./schemas";
 
@@ -63,8 +64,7 @@ export function writeChunks(logId: number, chunks: StreamingChunk[], truncated?:
   try {
     mkdirSync(dir, { recursive: true });
   } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error("[chunkStorage] Failed to create chunks directory:", err);
+    logger.error("[chunkStorage] Failed to create chunks directory:", String(err));
   }
 
   const data: StreamingChunksData = { chunks, truncated };
@@ -73,8 +73,7 @@ export function writeChunks(logId: number, chunks: StreamingChunk[], truncated?:
   try {
     writeFileSync(tempPath, JSON.stringify(data), "utf-8");
   } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error("[chunkStorage] Failed to write chunks temp file:", err);
+    logger.error("[chunkStorage] Failed to write chunks temp file:", String(err));
     return targetPath;
   }
 
@@ -89,8 +88,7 @@ export function writeChunks(logId: number, chunks: StreamingChunk[], truncated?:
       copyFileSync(tempPath, targetPath);
       unlinkSync(tempPath);
     } catch (copyErr) {
-      // eslint-disable-next-line no-console
-      console.error("[chunkStorage] Failed to copy chunks file:", copyErr);
+      logger.error("[chunkStorage] Failed to copy chunks file:", String(copyErr));
     }
   }
 

package/src/proxy/formats/anthropic/schemas.ts

@@ -196,6 +196,14 @@ const SsePingEvent = z.object({
   type: z.literal("ping"),
 });
 
+const SseErrorEvent = z.object({
+  type: z.literal("error"),
+  error: z.object({
+    type: z.string(),
+    message: z.string(),
+  }),
+});
+
 export const SseEventSchema = z.discriminatedUnion("type", [
   SseMessageStartEvent,
   SseContentBlockStartEvent,
@@ -204,6 +212,7 @@ export const SseEventSchema = z.discriminatedUnion("type", [
   SseMessageDeltaEvent,
   SseMessageStopEvent,
   SsePingEvent,
+  SseErrorEvent,
 ]);
 
 export type AnthropicRequest = z.infer<typeof AnthropicRequestSchema>;

package/src/proxy/formats/anthropic/stream.ts

@@ -133,6 +133,17 @@ export function extractAnthropicStream(
           stopSequence = data.delta.stop_sequence ?? null;
           outputTokens = data.usage.output_tokens;
           log.outputTokens = outputTokens;
+          // Cache tokens may also be present in message_delta usage
+          if (data.usage.cache_creation_input_tokens !== undefined) {
+            log.cacheCreationInputTokens = data.usage.cache_creation_input_tokens;
+          }
+          if (data.usage.cache_read_input_tokens !== undefined) {
+            log.cacheReadInputTokens = data.usage.cache_read_input_tokens;
+          }
+          break;
+        case "error":
+          // Store error info on the log for display
+          log.error = data.error.message;
           break;
         case "content_block_stop":
         case "message_stop":

package/src/proxy/formats/openai/stream.ts

@@ -42,6 +42,21 @@ export function extractOpenAIStream(
 
     try {
       const parsed: unknown = JSON.parse(dataStr);
+      // Check for error object in SSE stream before trying to parse as chunk
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        const errorDesc = Object.getOwnPropertyDescriptor(parsed, "error");
+        if (
+          errorDesc !== undefined &&
+          typeof errorDesc.value === "object" &&
+          errorDesc.value !== null
+        ) {
+          const msgDesc = Object.getOwnPropertyDescriptor(errorDesc.value, "message");
+          if (msgDesc !== undefined && typeof msgDesc.value === "string") {
+            log.error = msgDesc.value;
+          }
+          continue;
+        }
+      }
       const chunkResult = OpenAISSERawChunkSchema.safeParse(parsed);
       if (!chunkResult.success) continue;
       const chunk = chunkResult.data;