llm-simple-router 0.6.3 → 0.6.5

package/config/recommended-retry-rules.json

@@ -6,6 +6,5 @@
   { "name": "ZAI 操作失败 (code 500)", "status_code": 400, "body_pattern": "\"type\"\\s*:\\s*\"error\".*\"code\"\\s*:\\s*\"500\"", "retry_strategy": "exponential", "retry_delay_ms": 5000, "max_retries": 10, "max_delay_ms": 60000 },
   { "name": "ZAI 速率限制 (HTTP 200, code 1302)", "status_code": 200, "body_pattern": "\"error\".*\"code\"\\s*:\\s*\"1302\"", "retry_strategy": "exponential", "retry_delay_ms": 5000, "max_retries": 10, "max_delay_ms": 60000 },
   { "name": "ZAI SSE 错误 (HTTP 200, code 500)", "status_code": 200, "body_pattern": "\"error\".*\"code\"\\s*:\\s*\"500\"", "retry_strategy": "exponential", "retry_delay_ms": 5000, "max_retries": 10, "max_delay_ms": 60000 },
-  { "name": "ZAI SSE 错误 (HTTP 200, code 1234)", "status_code": 200, "body_pattern": "\"error\".*\"code\"\\s*:\\s*\"1234\"", "retry_strategy": "exponential", "retry_delay_ms": 5000, "max_retries": 10, "max_delay_ms": 60000 },
-  { "name": "ZAI 过载限流 (HTTP 200, code 1305)", "status_code": 200, "body_pattern": "\"error\".*\"code\"\\s*:\\s*\"1305\"", "retry_strategy": "exponential", "retry_delay_ms": 5000, "max_retries": 10, "max_delay_ms": 60000 }
+  { "name": "ZAI SSE 错误 (HTTP 200, code 1234)", "status_code": 200, "body_pattern": "\"error\".*\"code\"\\s*:\\s*\"1234\"", "retry_strategy": "exponential", "retry_delay_ms": 5000, "max_retries": 10, "max_delay_ms": 60000 }
 ]

package/dist/admin/proxy-enhancement.js

@@ -3,6 +3,8 @@ import { setSetting } from "../db/settings.js";
 import { loadEnhancementConfig } from "../proxy/enhancement-config.js";
 const UpdateProxyEnhancementSchema = Type.Object({
     claude_code_enabled: Type.Boolean(),
+    tool_call_loop_enabled: Type.Boolean(),
+    stream_loop_enabled: Type.Boolean(),
 });
 const SessionParamsSchema = Type.Object({
     keyId: Type.String(),
@@ -16,12 +18,16 @@ export const adminProxyEnhancementRoutes = (app, options, done) => {
         const config = loadEnhancementConfig(db);
         return reply.send({
             claude_code_enabled: config.claude_code_enabled,
+            tool_call_loop_enabled: config.tool_call_loop_enabled,
+            stream_loop_enabled: config.stream_loop_enabled,
         });
     });
     app.put("/admin/api/proxy-enhancement", { schema: { body: UpdateProxyEnhancementSchema } }, async (request, reply) => {
         const body = request.body;
         const config = {
             claude_code_enabled: body.claude_code_enabled,
+            tool_call_loop_enabled: body.tool_call_loop_enabled,
+            stream_loop_enabled: body.stream_loop_enabled,
         };
         setSetting(db, "proxy_enhancement", JSON.stringify(config));
         return reply.send({ success: true });

package/dist/constants.d.ts

@@ -5,6 +5,7 @@ export declare const HTTP_NOT_FOUND = 404;
 export declare const HTTP_CONFLICT = 409;
 export declare const HTTP_INTERNAL_ERROR = 500;
 export declare const HTTP_BAD_GATEWAY = 502;
+export declare const HTTP_UNPROCESSABLE_ENTITY = 422;
 export declare const HTTP_SERVICE_UNAVAILABLE = 503;
 export declare const PROXY_API_TYPES: Record<string, string>;
 export declare function getProxyApiType(url: string): string | null;

package/dist/constants.js

@@ -6,6 +6,7 @@ export const HTTP_NOT_FOUND = 404;
 export const HTTP_CONFLICT = 409;
 export const HTTP_INTERNAL_ERROR = 500;
 export const HTTP_BAD_GATEWAY = 502;
+export const HTTP_UNPROCESSABLE_ENTITY = 422;
 export const HTTP_SERVICE_UNAVAILABLE = 503;
 // api_type 路由映射：proxy path → api type，用于全局 hook/errorHandler 中识别代理请求
 export const PROXY_API_TYPES = {

package/dist/index.js

@@ -23,6 +23,8 @@ import { ProviderSemaphoreManager } from "./proxy/semaphore.js";
 import { RequestTracker } from "./monitor/request-tracker.js";
 import { modelState } from "./proxy/model-state.js";
 import { UsageWindowTracker } from "./proxy/usage-window-tracker.js";
+import { SessionTracker } from "./proxy/loop-prevention/session-tracker.js";
+import { DEFAULT_LOOP_PREVENTION_CONFIG } from "./proxy/loop-prevention/types.js";
 import { scheduleLogCleanup } from "./db/log-cleaner.js";
 import { scheduleDbSizeMonitor } from "./db/db-size-monitor.js";
 import { startUpgradeChecker, stopUpgradeChecker } from "./admin/upgrade.js";
@@ -156,6 +158,8 @@ export async function buildApp(options) {
     // 5h 用量窗口追踪器，启动时自动补齐缺失窗口
     const usageWindowTracker = new UsageWindowTracker(db);
     usageWindowTracker.reconcileOnStartup();
+    // Session tracker（工具调用循环检测用），始终创建但检测受 proxy_enhancement 配置控制
+    const sessionTracker = new SessionTracker(DEFAULT_LOOP_PREVENTION_CONFIG.sessionTracker);
     // 从 DB 读取已有 provider 的并发配置，初始化信号量管理器和 tracker
     const allProviders = getAllProviders(db);
     for (const p of allProviders) {
@@ -182,6 +186,7 @@ export async function buildApp(options) {
         semaphoreManager,
         tracker,
         usageWindowTracker,
+        sessionTracker,
     });
     app.register(anthropicProxy, {
         db,
@@ -191,6 +196,7 @@ export async function buildApp(options) {
         semaphoreManager,
         tracker,
         usageWindowTracker,
+        sessionTracker,
     });
     app.register(adminRoutes, { db, matcher, tracker, semaphoreManager });
     // 前端静态文件服务（生产环境）
@@ -229,6 +235,7 @@ export async function buildApp(options) {
             logCleanup.stop();
             dbSizeMonitor.stop();
             tracker.stopPushInterval();
+            sessionTracker.stop();
             await app.close();
             db.close();
         },

package/dist/metrics/sse-metrics-transform.d.ts

@@ -6,6 +6,8 @@ export interface MetricsTransformOptions {
     onMetrics?: (metrics: MetricsResult) => void;
     /** 每收到一个 SSE data 行时触发，传入原始文本行 */
     onChunk?: (rawLine: string) => void;
+    /** 每次提取到内容文本（thinking / text / tool JSON delta）时触发，用于流式循环检测 */
+    onContentDelta?: (text: string) => void;
     /** 回调节流间隔（毫秒），默认 5000 */
     throttleMs?: number;
 }
@@ -18,8 +20,10 @@ export interface MetricsTransformOptions {
 export declare class SSEMetricsTransform extends Transform {
     private parser;
     private extractor;
+    private readonly apiType;
     private onMetrics?;
     private onChunk?;
+    private onContentDelta?;
     private throttleMs;
     private lastCallbackTime;
     private flushed;
@@ -27,6 +31,13 @@ export declare class SSEMetricsTransform extends Transform {
     _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
     _flush(callback: TransformCallback): void;
     getExtractor(): MetricsExtractor;
+    /** 从 SSE 事件中提取内容文本，触发 onContentDelta 回调 */
+    private emitContentDelta;
+    /**
+     * 从 SSE data 字段中提取实际内容文本（thinking / text / tool JSON delta）。
+     * 忽略框架事件（message_start、ping 等），仅返回模型输出的内容。
+     */
+    private extractContentDelta;
     /** 节流逻辑：首次或距上次回调超过 throttleMs 时触发 */
     private emitMetricsIfReady;
 }

package/dist/metrics/sse-metrics-transform.js

@@ -11,17 +11,21 @@ const DEFAULT_THROTTLE_MS = 5000;
 export class SSEMetricsTransform extends Transform {
     parser;
     extractor;
+    apiType;
     onMetrics;
     onChunk;
+    onContentDelta;
     throttleMs;
     lastCallbackTime = 0;
     flushed = false;
     constructor(apiType, requestStartTime, options) {
         super();
+        this.apiType = apiType;
         this.parser = new SSEParser();
         this.extractor = new MetricsExtractor(apiType, requestStartTime);
         this.onMetrics = options?.onMetrics;
         this.onChunk = options?.onChunk;
+        this.onContentDelta = options?.onContentDelta;
         this.throttleMs = options?.throttleMs ?? DEFAULT_THROTTLE_MS;
     }
     _transform(chunk, _encoding, callback) {
@@ -29,7 +33,7 @@ export class SSEMetricsTransform extends Transform {
         const events = this.parser.feed(text);
         for (const event of events) {
             this.extractor.processEvent(event);
-            // 将解析后的事件还原为 SSE data 行格式传给 onChunk
+            this.emitContentDelta(event);
             if (event.data != null && this.onChunk) {
                 this.onChunk(`data: ${event.data}`);
             }
@@ -41,8 +45,8 @@ export class SSEMetricsTransform extends Transform {
         const events = this.parser.flush();
         for (const event of events) {
             this.extractor.processEvent(event);
+            this.emitContentDelta(event);
         }
-        // flush 无条件推送最终状态，确保消费者能拿到完整指标
         if (this.onMetrics && !this.flushed) {
             this.flushed = true;
             this.lastCallbackTime = Date.now();
@@ -53,6 +57,47 @@ export class SSEMetricsTransform extends Transform {
     getExtractor() {
         return this.extractor;
     }
+    /** 从 SSE 事件中提取内容文本，触发 onContentDelta 回调 */
+    emitContentDelta(event) {
+        if (!this.onContentDelta || !event.data)
+            return;
+        const delta = this.extractContentDelta(event.data);
+        if (delta)
+            this.onContentDelta(delta);
+    }
+    /**
+     * 从 SSE data 字段中提取实际内容文本（thinking / text / tool JSON delta）。
+     * 忽略框架事件（message_start、ping 等），仅返回模型输出的内容。
+     */
+    extractContentDelta(data) {
+        try {
+            const parsed = JSON.parse(data);
+            if (this.apiType === "anthropic") {
+                if (parsed.type !== "content_block_delta" || typeof parsed.delta !== "object" || !parsed.delta)
+                    return undefined;
+                const delta = parsed.delta;
+                if (delta.type === "thinking_delta" && typeof delta.thinking === "string")
+                    return delta.thinking;
+                if (delta.type === "text_delta" && typeof delta.text === "string")
+                    return delta.text;
+                if (delta.type === "input_json_delta" && typeof delta.partial_json === "string")
+                    return delta.partial_json;
+            }
+            else {
+                const choices = parsed.choices;
+                if (!Array.isArray(choices) || choices.length === 0)
+                    return undefined;
+                const first = choices[0];
+                if (typeof first.delta !== "object" || !first.delta)
+                    return undefined;
+                const delta = first.delta;
+                if (typeof delta.content === "string")
+                    return delta.content;
+            }
+        }
+        catch { /* 非 JSON 数据行，跳过 */ }
+        return undefined;
+    }
     /** 节流逻辑：首次或距上次回调超过 throttleMs 时触发 */
     emitMetricsIfReady() {
         if (!this.onMetrics)

package/dist/proxy/anthropic.d.ts

@@ -12,5 +12,6 @@ export interface AnthropicProxyOptions {
     semaphoreManager?: ProviderSemaphoreManager;
     tracker?: RequestTracker;
     usageWindowTracker?: UsageWindowTracker;
+    sessionTracker?: import("./loop-prevention/session-tracker.js").SessionTracker;
 }
 export declare const anthropicProxy: FastifyPluginCallback<AnthropicProxyOptions>;

package/dist/proxy/anthropic.js

@@ -18,7 +18,7 @@ const ANTHROPIC_ERROR_TYPE = {
 };
 const anthropicErrors = createErrorFormatter((kind, message) => ({ type: "error", error: { type: ANTHROPIC_ERROR_TYPE[kind], message } }));
 const anthropicProxyRaw = (app, opts, done) => {
-    const { db, streamTimeoutMs, retryBaseDelayMs, matcher, semaphoreManager, tracker, usageWindowTracker } = opts;
+    const { db, streamTimeoutMs, retryBaseDelayMs, matcher, semaphoreManager, tracker, usageWindowTracker, sessionTracker } = opts;
     const orchestrator = createOrchestrator(semaphoreManager, tracker);
     app.post(MESSAGES_PATH, async (request, reply) => {
         if (!orchestrator) {
@@ -34,7 +34,7 @@ const anthropicProxyRaw = (app, opts, done) => {
             const e = anthropicErrors.providerUnavailable();
             return reply.code(e.statusCode).send(e.body);
         }
-        const deps = { db, streamTimeoutMs, retryBaseDelayMs, matcher, tracker, orchestrator, usageWindowTracker };
+        const deps = { db, streamTimeoutMs, retryBaseDelayMs, matcher, tracker, orchestrator, usageWindowTracker, sessionTracker };
         return handleProxyRequest(request, reply, "anthropic", MESSAGES_PATH, anthropicErrors, deps);
     });
     done();

package/dist/proxy/enhancement/enhancement-handler.d.ts

@@ -1,5 +1,6 @@
 import type { FastifyRequest } from "fastify";
 import Database from "better-sqlite3";
+import { type EnhancementConfig } from "../enhancement-config.js";
 export interface InterceptResponse {
     statusCode: number;
     body: unknown;
@@ -18,6 +19,6 @@ export interface EnhancementResult {
  * 在代理转发前应用代理增强逻辑（指令解析 + 会话记忆 + 模型替换 + 命令拦截）。
  * 仅当 proxy_enhancement.claude_code_enabled 开启时生效。
  */
-export declare function applyEnhancement(db: Database.Database, request: FastifyRequest, clientModel: string, sessionId?: string): EnhancementResult;
+export declare function applyEnhancement(db: Database.Database, request: FastifyRequest, clientModel: string, sessionId?: string, enhancementConfig?: EnhancementConfig): EnhancementResult;
 /** 生成注入到非流式响应中的模型信息标签 */
 export declare function buildModelInfoTag(effectiveModel: string): string;

package/dist/proxy/enhancement/enhancement-handler.js

@@ -60,9 +60,9 @@ function buildDisplayModels(db, allowedModelsRaw) {
  * 在代理转发前应用代理增强逻辑（指令解析 + 会话记忆 + 模型替换 + 命令拦截）。
  * 仅当 proxy_enhancement.claude_code_enabled 开启时生效。
  */
-export function applyEnhancement(db, request, clientModel, sessionId) {
+export function applyEnhancement(db, request, clientModel, sessionId, enhancementConfig) {
     const nullResult = { effectiveModel: clientModel, originalModel: null, interceptResponse: null };
-    const enhancement = loadEnhancementConfig(db);
+    const enhancement = enhancementConfig ?? loadEnhancementConfig(db);
     if (!enhancement.claude_code_enabled) {
         return nullResult;
     }

package/dist/proxy/enhancement-config.d.ts

@@ -1,6 +1,8 @@
 import Database from "better-sqlite3";
 export interface EnhancementConfig {
     claude_code_enabled: boolean;
+    tool_call_loop_enabled: boolean;
+    stream_loop_enabled: boolean;
 }
 /** 集中加载 proxy_enhancement 配置，避免多处重复 getSetting + JSON.parse */
 export declare function loadEnhancementConfig(db: Database.Database): EnhancementConfig;

package/dist/proxy/enhancement-config.js

@@ -1,6 +1,8 @@
 import { getSetting } from "../db/settings.js";
 const DEFAULT_CONFIG = {
     claude_code_enabled: false,
+    tool_call_loop_enabled: false,
+    stream_loop_enabled: false,
 };
 /** 集中加载 proxy_enhancement 配置，避免多处重复 getSetting + JSON.parse */
 export function loadEnhancementConfig(db) {
@@ -11,6 +13,8 @@ export function loadEnhancementConfig(db) {
         const parsed = JSON.parse(raw);
         return {
             claude_code_enabled: parsed.claude_code_enabled ?? false,
+            tool_call_loop_enabled: parsed.tool_call_loop_enabled ?? false,
+            stream_loop_enabled: parsed.stream_loop_enabled ?? false,
         };
     }
     catch {

package/dist/proxy/loop-prevention/detectors/detector.d.ts

@@ -0,0 +1,10 @@
+export interface LoopDetectorStatus {
+    detected: boolean;
+    reason?: string;
+    details?: Record<string, unknown>;
+}
+export interface LoopDetector {
+    feed(text: string): boolean;
+    reset(): void;
+    getStatus(): LoopDetectorStatus;
+}

package/dist/proxy/loop-prevention/detectors/detector.js

@@ -0,0 +1 @@
+export {};

package/dist/proxy/loop-prevention/detectors/ngram-detector.d.ts

@@ -0,0 +1,15 @@
+import type { LoopDetector, LoopDetectorStatus } from "./detector.js";
+import type { NGramDetectorConfig } from "../types.js";
+export declare class NGramLoopDetector implements LoopDetector {
+    private readonly config;
+    private window;
+    private ngramCounts;
+    private detected;
+    private maxPeakCount;
+    private peakNgram;
+    private totalCharsProcessed;
+    constructor(config: NGramDetectorConfig);
+    feed(text: string): boolean;
+    reset(): void;
+    getStatus(): LoopDetectorStatus;
+}

package/dist/proxy/loop-prevention/detectors/ngram-detector.js

@@ -0,0 +1,65 @@
+export class NGramLoopDetector {
+    config;
+    window = [];
+    ngramCounts = new Map();
+    detected = false;
+    maxPeakCount = 0;
+    peakNgram = "";
+    totalCharsProcessed = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    feed(text) {
+        if (this.detected)
+            return true;
+        for (const char of text) {
+            this.window.push(char);
+            this.totalCharsProcessed++;
+            if (this.window.length >= this.config.n) {
+                const ngram = this.window.slice(-this.config.n).join("");
+                const count = (this.ngramCounts.get(ngram) ?? 0) + 1;
+                this.ngramCounts.set(ngram, count);
+                if (count > this.maxPeakCount) {
+                    this.maxPeakCount = count;
+                    this.peakNgram = ngram;
+                }
+            }
+            if (this.window.length > this.config.windowSize) {
+                const leaving = this.window.slice(0, this.config.n).join("");
+                this.window.shift();
+                if (this.window.length >= this.config.n) {
+                    const c = this.ngramCounts.get(leaving);
+                    if (c && c > 1)
+                        this.ngramCounts.set(leaving, c - 1);
+                    else
+                        this.ngramCounts.delete(leaving);
+                }
+            }
+        }
+        if (this.maxPeakCount >= this.config.repeatThreshold) {
+            this.detected = true;
+        }
+        return this.detected;
+    }
+    reset() {
+        this.window = [];
+        this.ngramCounts.clear();
+        this.detected = false;
+        this.maxPeakCount = 0;
+        this.peakNgram = "";
+        this.totalCharsProcessed = 0;
+    }
+    getStatus() {
+        return {
+            detected: this.detected,
+            reason: this.detected ? `NGram '${this.peakNgram}' repeated ${this.maxPeakCount} times` : undefined,
+            details: {
+                peakNgram: this.peakNgram,
+                peakCount: this.maxPeakCount,
+                threshold: this.config.repeatThreshold,
+                totalChars: this.totalCharsProcessed,
+                windowSize: this.window.length,
+            },
+        };
+    }
+}

package/dist/proxy/loop-prevention/session-tracker.d.ts

@@ -0,0 +1,14 @@
+import type { ToolCallRecord, SessionTrackerConfig } from "./types.js";
+export declare class SessionTracker {
+    private readonly config;
+    private sessions;
+    private cleanupTimer;
+    constructor(config: SessionTrackerConfig);
+    stop(): void;
+    recordAndGetHistory(sessionKey: string, record: ToolCallRecord): ToolCallRecord[];
+    incrementLoopCount(sessionKey: string): number;
+    resetLoopCount(sessionKey: string): void;
+    getLoopCount(sessionKey: string): number;
+    private cleanup;
+    getActiveSessionCount(): number;
+}

package/dist/proxy/loop-prevention/session-tracker.js

@@ -0,0 +1,67 @@
+export class SessionTracker {
+    config;
+    sessions = new Map();
+    cleanupTimer = null;
+    constructor(config) {
+        this.config = config;
+        if (config.cleanupIntervalMs > 0) {
+            this.cleanupTimer = setInterval(() => this.cleanup(), config.cleanupIntervalMs);
+            this.cleanupTimer.unref();
+        }
+    }
+    stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    recordAndGetHistory(sessionKey, record) {
+        let session = this.sessions.get(sessionKey);
+        if (!session) {
+            session = { lastAccessTime: Date.now(), toolCalls: [], loopDetectedCount: 0 };
+            this.sessions.set(sessionKey, session);
+        }
+        else {
+            // If TTL expired, clear tool call history (session stays in active map)
+            if (Date.now() - session.lastAccessTime > this.config.sessionTtlMs) {
+                session.toolCalls = [];
+            }
+            session.lastAccessTime = Date.now();
+        }
+        // 同一 tool_use 不重复记录（模型切换、重试等场景会复用历史）
+        if (record.toolUseId && session.toolCalls.some(r => r.toolUseId === record.toolUseId)) {
+            return session.toolCalls;
+        }
+        session.toolCalls.push(record);
+        if (session.toolCalls.length > this.config.maxToolCallRecords) {
+            session.toolCalls = session.toolCalls.slice(-this.config.maxToolCallRecords);
+        }
+        return session.toolCalls;
+    }
+    incrementLoopCount(sessionKey) {
+        const session = this.sessions.get(sessionKey);
+        if (!session)
+            return 0;
+        session.loopDetectedCount++;
+        return session.loopDetectedCount;
+    }
+    resetLoopCount(sessionKey) {
+        const session = this.sessions.get(sessionKey);
+        if (session)
+            session.loopDetectedCount = 0;
+    }
+    getLoopCount(sessionKey) {
+        return this.sessions.get(sessionKey)?.loopDetectedCount ?? 0;
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [key, session] of this.sessions) {
+            if (now - session.lastAccessTime > this.config.sessionTtlMs) {
+                this.sessions.delete(key);
+            }
+        }
+    }
+    getActiveSessionCount() {
+        return this.sessions.size;
+    }
+}

package/dist/proxy/loop-prevention/stream-loop-guard.d.ts

@@ -0,0 +1,12 @@
+import type { LoopDetector } from "./detectors/detector.js";
+import type { StreamLoopGuardConfig } from "./types.js";
+export declare class StreamLoopGuard {
+    private readonly config;
+    private readonly detector;
+    private readonly onLoopDetected;
+    private triggered;
+    constructor(config: StreamLoopGuardConfig, detector: LoopDetector, onLoopDetected: (reason: string) => void);
+    feed(text: string): void;
+    isTriggered(): boolean;
+    reset(): void;
+}

package/dist/proxy/loop-prevention/stream-loop-guard.js

@@ -0,0 +1,28 @@
+export class StreamLoopGuard {
+    config;
+    detector;
+    onLoopDetected;
+    triggered = false;
+    constructor(config, detector, onLoopDetected) {
+        this.config = config;
+        this.detector = detector;
+        this.onLoopDetected = onLoopDetected;
+    }
+    feed(text) {
+        if (this.triggered)
+            return;
+        if (!this.config.enabled)
+            return;
+        if (this.detector.feed(text)) {
+            this.triggered = true;
+            this.onLoopDetected(this.detector.getStatus().reason ?? "stream_content_loop");
+        }
+    }
+    isTriggered() {
+        return this.triggered;
+    }
+    reset() {
+        this.triggered = false;
+        this.detector.reset();
+    }
+}

package/dist/proxy/loop-prevention/tool-loop-guard.d.ts

@@ -0,0 +1,13 @@
+import type { ToolCallRecord, ToolLoopGuardConfig, LoopCheckResult } from "./types.js";
+import { SessionTracker } from "./session-tracker.js";
+export declare class ToolLoopGuard {
+    private readonly tracker;
+    private readonly config;
+    constructor(tracker: SessionTracker, config: ToolLoopGuardConfig);
+    /**
+     * 检查本次工具调用是否构成循环。
+     * 如果 sessionKey 不可用（无 sessionId），返回 detected: false。
+     */
+    check(sessionKey: string | null, toolCall: ToolCallRecord | null): LoopCheckResult;
+    injectLoopBreakPrompt(body: Record<string, unknown>, apiType: "openai" | "anthropic", toolName: string): void;
+}

package/dist/proxy/loop-prevention/tool-loop-guard.js

@@ -0,0 +1,63 @@
+// src/proxy/loop-prevention/tool-loop-guard.ts
+import { NGramLoopDetector } from "./detectors/ngram-detector.js";
+export class ToolLoopGuard {
+    tracker;
+    config;
+    constructor(tracker, config) {
+        this.tracker = tracker;
+        this.config = config;
+    }
+    /**
+     * 检查本次工具调用是否构成循环。
+     * 如果 sessionKey 不可用（无 sessionId），返回 detected: false。
+     */
+    check(sessionKey, toolCall) {
+        if (!sessionKey || !toolCall)
+            return { detected: false };
+        if (!this.config.enabled)
+            return { detected: false };
+        const history = this.tracker.recordAndGetHistory(sessionKey, toolCall);
+        // 第一层：筛选同名的 tool_name 记录
+        // 未达阈值时不重置 loopCount，保留跨请求升级到层级 2/3 的可能性
+        const sameNameRecords = history.filter(r => r.toolName === toolCall.toolName);
+        if (sameNameRecords.length < this.config.minConsecutiveCount) {
+            return { detected: false };
+        }
+        // 第二层：N-gram 检测 input 参数文本
+        const detector = new NGramLoopDetector(this.config.detectorConfig);
+        for (const record of sameNameRecords) {
+            detector.feed(record.inputText);
+        }
+        if (detector.getStatus().detected) {
+            this.tracker.incrementLoopCount(sessionKey);
+            return { detected: true, reason: "tool_call_loop", history: sameNameRecords };
+        }
+        this.tracker.resetLoopCount(sessionKey);
+        return { detected: false };
+    }
+    injectLoopBreakPrompt(body, apiType, toolName) {
+        const prompt = `你正在重复调用同一个工具 "${toolName}"。` +
+            `这很可能陷入了一个循环。请仔细回顾对话历史，` +
+            `分析之前调用该工具的结果，停止重复调用，` +
+            `改用其他方式完成任务或直接告知用户你遇到的问题。`;
+        if (apiType === "anthropic") {
+            const system = body.system;
+            if (Array.isArray(system)) {
+                system.push({ type: "text", text: prompt });
+            }
+            else if (typeof system === "string") {
+                body.system = [{ type: "text", text: system }, { type: "text", text: prompt }];
+            }
+            else {
+                body.system = [{ type: "text", text: prompt }];
+            }
+        }
+        else {
+            // OpenAI: 在 messages 开头插入 system message
+            const messages = body.messages;
+            if (messages) {
+                messages.unshift({ role: "system", content: prompt });
+            }
+        }
+    }
+}

package/dist/proxy/loop-prevention/types.d.ts

@@ -0,0 +1,38 @@
+export interface NGramDetectorConfig {
+    n: number;
+    windowSize: number;
+    repeatThreshold: number;
+}
+export interface StreamLoopGuardConfig {
+    enabled: boolean;
+    detectorConfig: NGramDetectorConfig;
+}
+export interface ToolLoopGuardConfig {
+    enabled: boolean;
+    minConsecutiveCount: number;
+    detectorConfig: NGramDetectorConfig;
+}
+export interface SessionTrackerConfig {
+    sessionTtlMs: number;
+    maxToolCallRecords: number;
+    cleanupIntervalMs: number;
+}
+export interface LoopPreventionConfig {
+    enabled: boolean;
+    stream: StreamLoopGuardConfig;
+    toolCall: ToolLoopGuardConfig;
+    sessionTracker: SessionTrackerConfig;
+}
+export declare const DEFAULT_LOOP_PREVENTION_CONFIG: LoopPreventionConfig;
+export interface ToolCallRecord {
+    toolName: string;
+    toolUseId?: string;
+    inputHash: string;
+    inputText: string;
+    timestamp: number;
+}
+export interface LoopCheckResult {
+    detected: boolean;
+    reason?: "tool_call_loop" | "stream_content_loop";
+    history?: ToolCallRecord[];
+}

package/dist/proxy/loop-prevention/types.js

@@ -0,0 +1,18 @@
+/* eslint-disable no-magic-numbers -- DEFAULT 配置值本身就是语义化命名 */
+export const DEFAULT_LOOP_PREVENTION_CONFIG = {
+    enabled: false,
+    stream: {
+        enabled: true,
+        detectorConfig: { n: 6, windowSize: 1000, repeatThreshold: 10 },
+    },
+    toolCall: {
+        enabled: true,
+        minConsecutiveCount: 3,
+        detectorConfig: { n: 6, windowSize: 500, repeatThreshold: 5 },
+    },
+    sessionTracker: {
+        sessionTtlMs: 30 * 60 * 1000,
+        maxToolCallRecords: 50,
+        cleanupIntervalMs: 5 * 60 * 1000,
+    },
+};