@jsonstudio/llms 0.4.2

package/dist/hooks/hooks-integration.js

@@ -0,0 +1,519 @@
+/**
+ * LLMSwitch V2 Hooks 集成器（业务命名）
+ *
+ * 集成现有2hooks系统到LLMSwitch V2架构
+ */
+import { LLMSwitchHookStage } from '../api/llmswitch-types.js';
+/**
+ * Hook执行上下文构建器
+ */
+export class HookContextBuilder {
+    /**
+     * 构建Hook执行上下文
+     */
+    static buildContext(stage, endpoint, originalProtocol, targetProtocol, pathIdentifier, processingMode, hookSequence, totalHooks, additionalData) {
+        return {
+            executionId: this.generateExecutionId(),
+            stage,
+            startTime: Date.now(),
+            requestId: additionalData?.requestId,
+            moduleId: additionalData?.moduleId,
+            metadata: {
+                ...additionalData,
+                endpoint,
+                originalProtocol,
+                targetProtocol,
+                pathIdentifier,
+                processingMode,
+                hookSequence,
+                totalHooks
+            },
+            endpoint,
+            originalProtocol,
+            targetProtocol,
+            pathIdentifier,
+            processingMode,
+            hookSequence,
+            totalHooks
+        };
+    }
+    /**
+     * 生成执行ID
+     */
+    static generateExecutionId() {
+        return `llmswitch-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+}
+/**
+ * 简化的快照服务
+ */
+export class SnapshotService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async start() {
+        if (this.config.enabled && SNAPSHOT_LOG_ENABLED) {
+            console.log('SnapshotService started');
+        }
+    }
+    async stop() {
+        if (this.config.enabled && SNAPSHOT_LOG_ENABLED) {
+            console.log('SnapshotService stopped');
+        }
+    }
+    async saveSnapshot(path, data) {
+        if (!this.config.enabled || (this.config.level && this.config.level !== 'verbose')) {
+            return;
+        }
+        try {
+            // 实际快照保存：写入 JSON 文件到 basePath 下
+            const os = await import('os');
+            const fs = await import('fs');
+            const fsp = await import('fs/promises');
+            const pathMod = await import('path');
+            const expandHome = (p) => p.startsWith('~') ? pathMod.join(os.homedir(), p.slice(1)) : p;
+            const base = expandHome(this.config.basePath);
+            const dir = pathMod.join(base, pathMod.dirname(path));
+            const file = pathMod.join(base, `${path}.json`);
+            fs.mkdirSync(dir, { recursive: true });
+            await fsp.writeFile(file, JSON.stringify(data, null, 2), 'utf-8');
+        }
+        catch (error) {
+            console.warn('Failed to save snapshot:', error);
+        }
+    }
+    getStats() {
+        return {
+            enabled: this.config.enabled,
+            basePath: this.config.basePath
+        };
+    }
+}
+function resolveSnapshotBasePath() {
+    const candidates = [
+        process.env.LLMSWITCH_SNAPSHOT_BASE,
+        process.env.ROUTECODEX_SNAPSHOT_BASE,
+        process.env.ROUTECODEX_SNAPSHOT_BASEPATH,
+        process.env.RCC_SNAPSHOT_BASE,
+        process.env.RCC_SNAPSHOT_BASEPATH
+    ];
+    for (const candidate of candidates) {
+        if (candidate && candidate.trim()) {
+            return candidate.trim();
+        }
+    }
+    return '~/.routecodex/codex-samples';
+}
+/**
+ * Hook管理器（简化实现）
+ */
+export class HookManager {
+    handlers = new Map();
+    registerHandler(stage, handler) {
+        this.handlers.set(stage, handler);
+    }
+    async executeHook(stage, params) {
+        const handler = this.handlers.get(stage);
+        if (!handler) {
+            return {
+                success: true,
+                data: params.data
+            };
+        }
+        try {
+            const result = await handler(params);
+            return {
+                success: true,
+                data: result
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error
+            };
+        }
+    }
+    getStats() {
+        return {
+            totalHandlers: this.handlers.size,
+            registeredStages: Array.from(this.handlers.keys())
+        };
+    }
+    clear() {
+        this.handlers.clear();
+    }
+}
+/**
+ * LLMSwitch V2 Hooks适配器
+ */
+export class HooksIntegration {
+    hookManager;
+    snapshotService;
+    config;
+    modulePolicies = {};
+    constructor(config) {
+        this.config = config;
+        this.hookManager = new HookManager();
+        this.snapshotService = new SnapshotService({
+            enabled: config.snapshot.enabled,
+            level: config.snapshot.level,
+            basePath: config.snapshot.basePath,
+            endpointIsolation: config.snapshot.endpointIsolation
+        });
+        this.modulePolicies = HooksIntegration.loadModulePoliciesFromEnv(config.modulePolicies);
+    }
+    /**
+     * 初始化Hook适配器
+     */
+    async initialize() {
+        if (this.config.enabled) {
+            await this.snapshotService.start();
+            console.log('HooksIntegration initialized');
+        }
+    }
+    /**
+     * 执行Hook
+     */
+    async executeHook(stage, context, data) {
+        if (!this.config.enabled) {
+            return {
+                success: true,
+                data,
+                executionTime: 0,
+                metadata: {
+                    endpoint: context.endpoint,
+                    originalProtocol: context.originalProtocol,
+                    targetProtocol: context.targetProtocol,
+                    processingMode: context.processingMode,
+                    stage: context.stage,
+                    hookResults: []
+                }
+            };
+        }
+        const startTime = Date.now();
+        let hookResults = [];
+        let error;
+        try {
+            // 执行Hook
+            const result = await this.performHookExecution(stage, context, data);
+            hookResults = result.results || [];
+            // 处理快照
+            if (this.config.snapshot.enabled) {
+                await this.handleSnapshot(stage, context, data, result);
+            }
+            return {
+                success: true,
+                data: result.data || data,
+                executionTime: Date.now() - startTime,
+                metadata: {
+                    endpoint: context.endpoint,
+                    originalProtocol: context.originalProtocol,
+                    targetProtocol: context.targetProtocol,
+                    processingMode: context.processingMode,
+                    stage: context.stage,
+                    hookResults
+                }
+            };
+        }
+        catch (err) {
+            error = err;
+            return {
+                success: false,
+                error,
+                executionTime: Date.now() - startTime,
+                metadata: {
+                    endpoint: context.endpoint,
+                    originalProtocol: context.originalProtocol,
+                    targetProtocol: context.targetProtocol,
+                    processingMode: context.processingMode,
+                    stage: context.stage,
+                    hookResults
+                }
+            };
+        }
+    }
+    /**
+     * 批量执行Hooks
+     */
+    async executeHooks(stages, context, data) {
+        if (this.config.parallel) {
+            // 并行执行
+            const promises = stages.map(stage => this.executeHook(stage, context, data));
+            return Promise.all(promises);
+        }
+        else {
+            // 串行执行
+            const results = [];
+            let currentData = data;
+            for (const stage of stages) {
+                const result = await this.executeHook(stage, context, currentData);
+                results.push(result);
+                if (!result.success) {
+                    // 如果执行失败，停止后续执行
+                    break;
+                }
+                currentData = result.data;
+            }
+            return results;
+        }
+    }
+    /**
+     * 注册Hook处理器
+     */
+    registerHookHandler(stage, handler) {
+        this.hookManager.registerHandler(stage.toString(), handler);
+    }
+    /**
+     * 获取Hook统计信息
+     */
+    getHookStats() {
+        return this.hookManager.getStats();
+    }
+    /**
+     * 获取快照统计信息
+     */
+    getSnapshotStats() {
+        return this.snapshotService.getStats();
+    }
+    /**
+     * 执行Hook的核心逻辑
+     */
+    async performHookExecution(stage, context, data) {
+        const hookId = stage.toString();
+        // 模块级开关：可按 moduleId 禁用 hook 执行
+        const moduleId = String(context.moduleId || 'llmswitch');
+        const policy = this.modulePolicies[moduleId];
+        if (policy && policy.enabled === false) {
+            return { success: true, data, results: [] };
+        }
+        // 构建Hook参数
+        const hookParams = {
+            context,
+            data,
+            stage,
+            endpoint: context.endpoint,
+            protocol: context.originalProtocol,
+            metadata: context.metadata
+        };
+        // 执行Hook（带重试机制）
+        let attempt = 0;
+        let lastError;
+        while (attempt <= this.config.retryAttempts) {
+            try {
+                const result = await this.hookManager.executeHook(hookId, hookParams);
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                attempt++;
+                if (attempt <= this.config.retryAttempts) {
+                    // 等待重试延迟
+                    await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+                }
+            }
+        }
+        throw lastError || new Error('Hook execution failed');
+    }
+    /**
+     * 处理快照
+     */
+    async handleSnapshot(stage, context, data, hookResult) {
+        try {
+            // 模块级策略优先：仅在 verbose 级别保存
+            const moduleId = String(context.moduleId || 'llmswitch');
+            const envLevel = String(process.env.ROUTECODEX_HOOKS_VERBOSITY || process.env.RCC_HOOKS_VERBOSITY || '').toLowerCase();
+            const globalLevel = this.config?.snapshot?.level || (envLevel || 'normal');
+            const policy = this.modulePolicies[moduleId];
+            const level = (policy?.level) || globalLevel;
+            const snapEnabled = (policy?.snapshotEnabled !== undefined) ? policy?.snapshotEnabled : true;
+            if (!snapEnabled || level !== 'verbose')
+                return;
+            // 构建快照路径
+            const snapshotPath = this.buildSnapshotPath(context, stage);
+            // 构建快照数据
+            const snapshotData = {
+                context,
+                inputData: data,
+                outputData: hookResult.data,
+                hookResults: hookResult.results,
+                metadata: {
+                    stage,
+                    timestamp: Date.now(),
+                    executionTime: Date.now() - context.startTime,
+                    endpoint: context.endpoint,
+                    protocol: `${context.originalProtocol}->${context.targetProtocol}`
+                }
+            };
+            // 保存快照
+            await this.snapshotService.saveSnapshot(snapshotPath, snapshotData);
+        }
+        catch (error) {
+            console.warn('Failed to save snapshot:', error);
+            // 快照失败不应该影响主要流程
+        }
+    }
+    /**
+     * 构建快照路径
+     */
+    buildSnapshotPath(context, stage) {
+        const reqIdRaw = String(context.requestId || context.pathIdentifier || `req_${Date.now()}`);
+        const reqId = reqIdRaw.startsWith('req_') ? reqIdRaw : `req_${reqIdRaw}`;
+        const stageStr = String(stage).toLowerCase();
+        const mapEndpointDir = (ep) => {
+            const e = String(ep || '').toLowerCase();
+            if (e.includes('responses'))
+                return 'openai-responses';
+            if (e.includes('messages'))
+                return 'anthropic-messages';
+            return 'openai-chat';
+        };
+        const endpointDir = mapEndpointDir(String(context.endpoint || 'chat'));
+        // finalize 专用命名，严格对齐系统其它快照
+        if (stage === LLMSwitchHookStage.RESPONSE_6_SNAPSHOT_PRE) {
+            return `${endpointDir}/${reqId}_finalize-pre`;
+        }
+        if (stage === LLMSwitchHookStage.RESPONSE_6_SNAPSHOT_POST) {
+            return `${endpointDir}/${reqId}_finalize-post`;
+        }
+        // 其它阶段：保留 endpoint/requestId_stage 命名
+        return `${endpointDir}/${reqId}_${stageStr}`;
+    }
+    // 从环境变量加载模块级策略（JSON字符串）
+    static loadModulePoliciesFromEnv(seed) {
+        let out = { ...(seed || {}) };
+        try {
+            const raw = process.env.ROUTECODEX_HOOKS_POLICY || process.env.RCC_HOOKS_POLICY;
+            if (raw && raw.trim().length) {
+                const obj = JSON.parse(raw);
+                if (obj && typeof obj === 'object')
+                    out = { ...out, ...obj };
+            }
+        }
+        catch { /* ignore */ }
+        return out;
+    }
+    /**
+     * 启动适配器
+     */
+    async start() {
+        if (this.config.snapshot.enabled) {
+            await this.snapshotService.start();
+        }
+    }
+    /**
+     * 停止适配器
+     */
+    async stop() {
+        if (this.config.snapshot.enabled) {
+            await this.snapshotService.stop();
+        }
+    }
+    /**
+     * 销毁适配器
+     */
+    async destroy() {
+        await this.stop();
+        this.hookManager.clear();
+    }
+}
+/**
+ * 创建Hook适配器的工厂函数
+ */
+export function createHooksIntegration(config = {}) {
+    const globalEnable = String(process.env.ROUTECODEX_SNAPSHOT_ENABLE || process.env.RCC_SNAPSHOT_ENABLE || '1') !== '0';
+    const defaultConfig = {
+        enabled: true,
+        timeout: 5000,
+        retryAttempts: 2,
+        parallel: false,
+        snapshot: {
+            enabled: globalEnable,
+            level: (() => {
+                const v = String(process.env.RCC_HOOKS_VERBOSITY || process.env.ROUTECODEX_HOOKS_VERBOSITY || 'verbose').toLowerCase();
+                return v === 'verbose' ? 'verbose' : 'normal';
+            })(),
+            basePath: resolveSnapshotBasePath(),
+            endpointIsolation: {
+                enabled: true,
+                pathStructure: 'endpoint/request'
+            }
+        }
+    };
+    return new HooksIntegration({ ...defaultConfig, ...config });
+}
+/**
+ * Lightweight helper: write a snapshot using the same SnapshotService and
+ * path conventions as HooksIntegration, without requiring a live hooks
+ * pipeline. Intended for external callers (server/provider/compat) that
+ * want to unify snapshot emission through the core hooks system.
+ */
+export async function writeSnapshotViaHooks(options) {
+    try {
+        const globalEnable = String(process.env.ROUTECODEX_SNAPSHOT_ENABLE || process.env.RCC_SNAPSHOT_ENABLE || '1') !== '0';
+        if (!globalEnable)
+            return; // 全局关
+        // 端点过滤（可选）：ROUTECODEX_SNAPSHOT_ENDPOINTS=messages,responses,chat
+        try {
+            const allow = String(process.env.ROUTECODEX_SNAPSHOT_ENDPOINTS || process.env.RCC_SNAPSHOT_ENDPOINTS || '').trim();
+            if (allow.length) {
+                const allowed = new Set(allow.split(',').map(s => s.trim().toLowerCase()));
+                const key = options.endpoint.includes('responses') ? 'responses' : options.endpoint.includes('messages') ? 'messages' : 'chat';
+                if (!allowed.has(key))
+                    return;
+            }
+        }
+        catch { /* ignore */ }
+        const cfg = {
+            enabled: true,
+            timeout: 1000,
+            retryAttempts: 0,
+            parallel: false,
+            snapshot: {
+                enabled: globalEnable,
+                level: options.verbosity || (String(process.env.RCC_HOOKS_VERBOSITY || 'verbose').toLowerCase() === 'verbose' ? 'verbose' : 'normal'),
+                basePath: resolveSnapshotBasePath(),
+                endpointIsolation: { enabled: true, pathStructure: 'endpoint/request' }
+            }
+        };
+        const snap = new SnapshotService(cfg.snapshot);
+        await snap.start();
+        // Build endpoint dir mapping (align with HooksIntegration.buildSnapshotPath)
+        const ep = String(options.endpoint || '').toLowerCase();
+        const endpointDir = ep.includes('responses') ? 'openai-responses' : ep.includes('messages') ? 'anthropic-messages' : 'openai-chat';
+        const reqId = options.requestId.startsWith('req_') ? options.requestId : `req_${options.requestId}`;
+        let fileStem;
+        if (options.stage === 'finalize-pre')
+            fileStem = `${endpointDir}/${reqId}_finalize-pre`;
+        else if (options.stage === 'finalize-post')
+            fileStem = `${endpointDir}/${reqId}_finalize-post`;
+        else
+            fileStem = `${endpointDir}/${reqId}_${String(options.stage).toLowerCase()}`;
+        await snap.saveSnapshot(fileStem, {
+            endpoint: options.endpoint,
+            stage: options.stage,
+            requestId: options.requestId,
+            timestamp: Date.now(),
+            data: options.data
+        });
+    }
+    catch {
+        // Non-blocking by design
+    }
+}
+const snapshotLogTruthy = new Set(['1', 'true', 'yes']);
+const snapshotLogFalsy = new Set(['0', 'false', 'no']);
+function isSnapshotLogEnabled() {
+    const raw = String(process.env.ROUTECODEX_SNAPSHOT_LOG ||
+        process.env.RCC_SNAPSHOT_LOG ||
+        '').trim().toLowerCase();
+    if (snapshotLogTruthy.has(raw)) {
+        return true;
+    }
+    if (snapshotLogFalsy.has(raw)) {
+        return false;
+    }
+    return false;
+}
+const SNAPSHOT_LOG_ENABLED = isSnapshotLogEnabled();

package/dist/hooks/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hooks系统模块导出
+ */
+export { HooksIntegration } from './hooks-integration.js';
+export type { HooksIntegrationConfig, HookExecutionResult } from './hooks-integration.js';
+export { HookContextBuilder } from './hooks-integration.js';
+export { SnapshotService } from './hooks-integration.js';
+export type { SnapshotServiceConfig } from './hooks-integration.js';
+export { HookManager } from './hooks-integration.js';
+export { createHooksIntegration } from './hooks-integration.js';

package/dist/hooks/index.js

@@ -0,0 +1,13 @@
+/**
+ * Hooks系统模块导出
+ */
+// Hooks集成器
+export { HooksIntegration } from './hooks-integration.js';
+// Hook上下文构建器
+export { HookContextBuilder } from './hooks-integration.js';
+// 快照服务
+export { SnapshotService } from './hooks-integration.js';
+// Hook管理器
+export { HookManager } from './hooks-integration.js';
+// 工厂函数
+export { createHooksIntegration } from './hooks-integration.js';

package/dist/html-to-markdown.d.ts

@@ -0,0 +1,5 @@
+export declare function htmlToMarkdown(html: string): string;
+declare const _default: {
+    htmlToMarkdown: typeof htmlToMarkdown;
+};
+export default _default;

package/dist/html-to-markdown.js

@@ -0,0 +1,66 @@
+// Minimal HTML → Markdown converter, dependency-free.
+// Goal: remove scripts/styles, strip tags, keep basic structure as Markdown.
+function stripScriptsAndStyles(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[\s\S]*?<\/style>/gi, '');
+}
+function decodeEntities(s) {
+    // very small subset
+    const map = {
+        '&nbsp;': ' ', '&lt;': '<', '&gt;': '>', '&amp;': '&', '&quot;': '"', '&#39;': '\''
+    };
+    return s.replace(/&(nbsp|lt|gt|amp|quot|#39);/g, (m) => map[m] || m);
+}
+function convertHeadings(s) {
+    return s
+        .replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, (_, t) => `\n# ${t}\n`)
+        .replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, (_, t) => `\n## ${t}\n`)
+        .replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, (_, t) => `\n### ${t}\n`)
+        .replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, (_, t) => `\n#### ${t}\n`)
+        .replace(/<h5[^>]*>([\s\S]*?)<\/h5>/gi, (_, t) => `\n##### ${t}\n`)
+        .replace(/<h6[^>]*>([\s\S]*?)<\/h6>/gi, (_, t) => `\n###### ${t}\n`);
+}
+function convertLists(s) {
+    // li
+    s = s.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, (_, t) => `\n- ${t}`);
+    // ul/ol newlines
+    s = s.replace(/<(ul|ol)[^>]*>/gi, '\n');
+    s = s.replace(/<\/(ul|ol)>/gi, '\n');
+    return s;
+}
+function convertLinks(s) {
+    // <a href="url">text</a> → [text](url)
+    return s.replace(/<a[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, (_, href, text) => `[$ {text}](${href})`.replace('$ ', ''));
+}
+function convertBreaksAndParas(s) {
+    s = s.replace(/<br\s*\/?\s*>/gi, '\n');
+    s = s.replace(/<p[^>]*>/gi, '\n');
+    s = s.replace(/<\/p>/gi, '\n');
+    s = s.replace(/<div[^>]*>/gi, '\n');
+    s = s.replace(/<\/div>/gi, '\n');
+    return s;
+}
+function stripRemainingTags(s) {
+    return s.replace(/<[^>]+>/g, '');
+}
+function collapseWhitespace(s) {
+    return s
+        .replace(/\r/g, '')
+        .replace(/[\t ]+/g, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function htmlToMarkdown(html) {
+    let s = String(html || '');
+    s = stripScriptsAndStyles(s);
+    s = convertHeadings(s);
+    s = convertLists(s);
+    s = convertLinks(s);
+    s = convertBreaksAndParas(s);
+    s = stripRemainingTags(s);
+    s = decodeEntities(s);
+    s = collapseWhitespace(s);
+    return s;
+}
+export default { htmlToMarkdown };

package/dist/http/sse-response.d.ts

@@ -0,0 +1,22 @@
+import type { ServerResponse } from 'node:http';
+import type { Readable } from 'node:stream';
+type AnyObj = Record<string, unknown>;
+/**
+ * Pipe an SSE Readable to Node http.ServerResponse
+ */
+export declare function sendNodeSSE(res: ServerResponse, stream: Readable): void;
+/**
+ * Express response variant (duck-typed): res.set, res.write, res.end
+ */
+export declare function sendExpressSSE(res: AnyObj, stream: Readable): void;
+/**
+ * Fastify reply variant: reply.raw is ServerResponse
+ */
+export declare function sendFastifySSE(reply: AnyObj, stream: Readable): void;
+/**
+ * If the given payload contains __sse_responses or sseStream, stream it via the provided response object.
+ * Otherwise, send JSON.
+ * - Supported responders: Node ServerResponse, Express res, Fastify reply
+ */
+export declare function sendSSEOrJSON(resOrReply: AnyObj, payload: AnyObj): any;
+export {};