@jsonstudio/llms 0.4.2

package/dist/conversion/conversion-v3/standards/pipeline-node.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 标准 PipelineNode 接口定义
+ * 严格对齐 pipeline-node-interface.md 规范
+ */
+import type { PipelineContext, NodeCapabilities, PipelineNodeKind } from './pipeline-context.js';
+/**
+ * 标准 PipelineNode 接口
+ * 对齐 pipeline-node-interface.md 规范
+ */
+export interface PipelineNode {
+    /** 节点唯一标识（对应 pipeline-config 中的 id） */
+    readonly id: string;
+    /** 节点类型（8种标准类型） */
+    readonly kind: PipelineNodeKind;
+    /** 实现名称（对应 pipeline-config 中的 implementation） */
+    readonly implementation: string;
+    /** 节点配置选项 */
+    readonly options?: Record<string, unknown>;
+    /** 节点能力 */
+    readonly capabilities?: NodeCapabilities;
+    /** 节点描述 */
+    readonly description?: string;
+    /**
+     * 执行节点逻辑
+     * @param ctx 流水线上下文
+     * @returns 更新后的流水线上下文
+     */
+    execute(ctx: PipelineContext): Promise<PipelineContext>;
+    /**
+     * 验证节点配置
+     * @param config 配置数据
+     * @returns 验证结果
+     */
+    validate?(config: Record<string, unknown>): Promise<boolean>;
+    /**
+     * 清理资源
+     */
+    cleanup?(): Promise<void>;
+    /**
+     * 获取节点健康状态
+     */
+    getHealth?(): Promise<NodeHealthStatus>;
+    /**
+     * 获取节点指标
+     */
+    getMetrics?(): Promise<NodeMetrics>;
+}
+/**
+ * 节点健康状态
+ */
+export interface NodeHealthStatus {
+    /** 是否健康 */
+    healthy: boolean;
+    /** 状态消息 */
+    message?: string;
+    /** 最后检查时间 */
+    lastCheck: number;
+    /** 详细状态 */
+    details?: {
+        memoryUsage?: number;
+        cpuUsage?: number;
+        activeRequests?: number;
+        errorRate?: number;
+    };
+}
+/**
+ * 节点性能指标
+ */
+export interface NodeMetrics {
+    /** 总执行次数 */
+    totalExecutions: number;
+    /** 成功执行次数 */
+    successfulExecutions: number;
+    /** 失败执行次数 */
+    failedExecutions: number;
+    /** 平均执行时间（毫秒） */
+    averageExecutionTime: number;
+    /** 最小执行时间（毫秒） */
+    minExecutionTime: number;
+    /** 最大执行时间（毫秒） */
+    maxExecutionTime: number;
+    /** 最后执行时间 */
+    lastExecutionTime?: number;
+    /** 当前并发请求数 */
+    currentConcurrency: number;
+    /** 错误率 */
+    errorRate: number;
+    /** 吞吐量（每秒请求数） */
+    throughput: number;
+}
+/**
+ * 节点实现接口
+ */
+export interface NodeImplementation {
+    /** 实现ID */
+    id: string;
+    /** 节点类型 */
+    kind: PipelineNodeKind;
+    /** 工厂函数 */
+    factory: (config?: Record<string, unknown>) => PipelineNode;
+    /** 实现描述 */
+    description?: string;
+    /** 默认能力 */
+    defaultCapabilities?: NodeCapabilities;
+    /** 依赖的其他节点实现 */
+    dependencies?: string[];
+    /** 配置验证函数 */
+    validateConfig?: (config: Record<string, unknown>) => ValidationResult;
+}
+/**
+ * 验证结果接口
+ */
+export interface ValidationResult {
+    /** 是否验证通过 */
+    valid: boolean;
+    /** 错误信息 */
+    errors: string[];
+    /** 警告信息 */
+    warnings: string[];
+}
+/**
+ * 基础 PipelineNode 实现
+ */
+export declare abstract class BasePipelineNode implements PipelineNode {
+    readonly id: string;
+    readonly kind: PipelineNodeKind;
+    readonly implementation: string;
+    readonly options: Record<string, unknown>;
+    readonly capabilities?: NodeCapabilities;
+    readonly description?: string;
+    protected readonly _metrics: NodeMetrics;
+    protected lastError?: Error;
+    constructor(id: string, kind: PipelineNodeKind, implementation: string, options?: Record<string, unknown>, capabilities?: NodeCapabilities, description?: string);
+    /**
+     * 确保基础的元数据存在
+     */
+    protected ensureMetadata(ctx: PipelineContext): void;
+    /**
+     * 确保基础的元数据（构造时调用）
+     */
+    private ensureBasicMetadata;
+    /**
+     * 调试日志记录
+     */
+    protected debugLog(stage: string, data: unknown, ctx: PipelineContext): void;
+    /**
+     * 错误处理和传播
+     */
+    protected handleError(error: Error, ctx: PipelineContext, stage: string): Promise<never>;
+    /**
+     * 确定错误严重程度
+     */
+    private determineErrorSeverity;
+    /**
+     * 生成错误标签
+     */
+    private generateErrorTags;
+    /**
+     * 更新执行指标
+     */
+    protected updateMetrics(executionTime: number, success: boolean): void;
+    /**
+     * 执行节点并记录指标
+     */
+    protected executeWithMetrics(ctx: PipelineContext): Promise<PipelineContext>;
+    /**
+     * 子类需要实现的执行逻辑
+     */
+    protected abstract executeLogic(ctx: PipelineContext): Promise<PipelineContext>;
+    /**
+     * 获取节点需求
+     */
+    protected getRequirements(): string[];
+    /**
+     * 获取节点权限
+     */
+    protected getPermissions(): string[];
+    execute(ctx: PipelineContext): Promise<PipelineContext>;
+    validate(config: Record<string, unknown>): Promise<boolean>;
+    cleanup(): Promise<void>;
+    getHealth(): Promise<NodeHealthStatus>;
+    getMetrics(): Promise<NodeMetrics>;
+    private isPipelineNodeError;
+    private wrapPipelineNodeError;
+    private getExecutionPhase;
+    private getExecutionStage;
+    private invokeErrorCallback;
+}
+/**
+ * 节点包装器 - 为现有 V3 节点提供适配
+ */
+export declare class NodeWrapper extends BasePipelineNode {
+    private readonly wrappedNode;
+    constructor(wrappedNode: any, id: string, kind: PipelineNodeKind, implementation: string, options?: Record<string, unknown>, capabilities?: NodeCapabilities);
+    protected executeLogic(ctx: PipelineContext): Promise<PipelineContext>;
+}

package/dist/conversion/conversion-v3/standards/pipeline-node.js

@@ -0,0 +1,316 @@
+/**
+ * 标准 PipelineNode 接口定义
+ * 严格对齐 pipeline-node-interface.md 规范
+ */
+import { createPipelineNodeError } from './errors.js';
+/**
+ * 基础 PipelineNode 实现
+ */
+export class BasePipelineNode {
+    id;
+    kind;
+    implementation;
+    options;
+    capabilities;
+    description;
+    _metrics = {
+        totalExecutions: 0,
+        successfulExecutions: 0,
+        failedExecutions: 0,
+        averageExecutionTime: 0,
+        minExecutionTime: Infinity,
+        maxExecutionTime: 0,
+        currentConcurrency: 0,
+        errorRate: 0,
+        throughput: 0
+    };
+    lastError;
+    constructor(id, kind, implementation, options = {}, capabilities, description) {
+        this.id = id;
+        this.kind = kind;
+        this.implementation = implementation;
+        this.options = options;
+        this.capabilities = capabilities;
+        this.description = description;
+        // 确保基础的元数据
+        this.ensureBasicMetadata();
+    }
+    /**
+     * 确保基础的元数据存在
+     */
+    ensureMetadata(ctx) {
+        if (!ctx.metadata.requestId) {
+            ctx.metadata.requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        }
+        if (!ctx.nodeContracts[this.id]) {
+            ctx.nodeContracts[this.id] = {
+                capabilities: this.capabilities ? Object.keys(this.capabilities).filter(key => this.capabilities[key]) : [],
+                requirements: this.getRequirements(),
+                permissions: this.getPermissions()
+            };
+        }
+    }
+    /**
+     * 确保基础的元数据（构造时调用）
+     */
+    ensureBasicMetadata() {
+        // 基础元数据设置可以在这里实现
+    }
+    /**
+     * 调试日志记录
+     */
+    debugLog(stage, data, ctx) {
+        if (ctx.debug.traceEnabled) {
+            ctx.debug.stages[`${this.id}:${stage}`] = {
+                timestamp: Date.now(),
+                data,
+                nodeId: this.id,
+                stage
+            };
+        }
+    }
+    /**
+     * 错误处理和传播
+     */
+    async handleError(error, ctx, stage) {
+        this.lastError = error;
+        const errorContext = {
+            originalError: error,
+            stage,
+            nodeId: this.id,
+            timestamp: Date.now(),
+            severity: this.determineErrorSeverity(error),
+            shouldTerminate: true,
+            tags: this.generateErrorTags(error)
+        };
+        ctx.metadata.errorContext = errorContext;
+        this.debugLog('error', {
+            message: error.message,
+            stack: error.stack,
+            stage
+        }, ctx);
+        const pipelineError = this.wrapPipelineNodeError(ctx, error, stage, errorContext);
+        throw pipelineError;
+    }
+    /**
+     * 确定错误严重程度
+     */
+    determineErrorSeverity(error) {
+        if (error.name === 'ValidationError')
+            return 'medium';
+        if (error.name === 'TimeoutError')
+            return 'high';
+        if (error.name === 'SystemError')
+            return 'critical';
+        return 'low';
+    }
+    /**
+     * 生成错误标签
+     */
+    generateErrorTags(error) {
+        const tags = [error.name, this.kind, this.implementation];
+        if (error.message.includes('timeout'))
+            tags.push('timeout');
+        if (error.message.includes('permission'))
+            tags.push('permission');
+        if (error.message.includes('validation'))
+            tags.push('validation');
+        return tags;
+    }
+    /**
+     * 更新执行指标
+     */
+    updateMetrics(executionTime, success) {
+        this._metrics.totalExecutions++;
+        if (success) {
+            this._metrics.successfulExecutions++;
+        }
+        else {
+            this._metrics.failedExecutions++;
+        }
+        // 更新执行时间统计
+        this._metrics.minExecutionTime = Math.min(this._metrics.minExecutionTime, executionTime);
+        this._metrics.maxExecutionTime = Math.max(this._metrics.maxExecutionTime, executionTime);
+        // 计算平均执行时间
+        const totalTime = this._metrics.averageExecutionTime * (this._metrics.totalExecutions - 1) + executionTime;
+        this._metrics.averageExecutionTime = totalTime / this._metrics.totalExecutions;
+        // 更新错误率
+        this._metrics.errorRate = this._metrics.failedExecutions / this._metrics.totalExecutions;
+        // 更新最后执行时间
+        this._metrics.lastExecutionTime = Date.now();
+    }
+    /**
+     * 执行节点并记录指标
+     */
+    async executeWithMetrics(ctx) {
+        const startTime = Date.now();
+        this._metrics.currentConcurrency++;
+        try {
+            this.debugLog('start', {
+                nodeId: this.id,
+                kind: this.kind,
+                timestamp: startTime
+            }, ctx);
+            const result = await this.executeLogic(ctx);
+            const executionTime = Date.now() - startTime;
+            this.updateMetrics(executionTime, true);
+            this.debugLog('complete', {
+                executionTime,
+                success: true
+            }, ctx);
+            return result;
+        }
+        catch (error) {
+            const executionTime = Date.now() - startTime;
+            this.updateMetrics(executionTime, false);
+            this.debugLog('failed', {
+                executionTime,
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            }, ctx);
+            throw error;
+        }
+        finally {
+            this._metrics.currentConcurrency--;
+        }
+    }
+    /**
+     * 获取节点需求
+     */
+    getRequirements() {
+        const requirements = [];
+        if (this.capabilities?.canModifyTools) {
+            requirements.push('tool-governance');
+        }
+        if (this.capabilities?.canAccessProvider) {
+            requirements.push('provider-access');
+        }
+        if (this.capabilities?.canHandleStreaming) {
+            requirements.push('streaming-support');
+        }
+        return requirements;
+    }
+    /**
+     * 获取节点权限
+     */
+    getPermissions() {
+        const permissions = ['read-context', 'write-debug'];
+        if (this.capabilities?.canModifyTools) {
+            permissions.push('modify-tools');
+        }
+        if (this.capabilities?.canAccessProvider) {
+            permissions.push('access-provider');
+        }
+        if (this.capabilities?.canModifyMetadata) {
+            permissions.push('modify-metadata');
+        }
+        if (this.capabilities?.canAccessSnapshots) {
+            permissions.push('access-snapshots');
+        }
+        if (this.capabilities?.canHandleStreaming) {
+            permissions.push('handle-streaming');
+        }
+        return permissions;
+    }
+    // 接口实现
+    async execute(ctx) {
+        this.ensureMetadata(ctx);
+        try {
+            return await this.executeWithMetrics(ctx);
+        }
+        catch (error) {
+            if (this.isPipelineNodeError(error)) {
+                await this.invokeErrorCallback(ctx, error);
+                throw error;
+            }
+            await this.handleError(error instanceof Error ? error : new Error(String(error)), ctx, 'execute');
+        }
+    }
+    async validate(config) {
+        // 默认验证逻辑
+        return true;
+    }
+    async cleanup() {
+        // 默认清理逻辑
+    }
+    async getHealth() {
+        return {
+            healthy: !this.lastError,
+            message: this.lastError ? this.lastError.message : 'Node is healthy',
+            lastCheck: Date.now(),
+            details: {
+                activeRequests: this._metrics.currentConcurrency,
+                errorRate: this._metrics.errorRate
+            }
+        };
+    }
+    async getMetrics() {
+        return { ...this._metrics };
+    }
+    isPipelineNodeError(error) {
+        return error instanceof Error && typeof error.nodeId === 'string' && typeof error.pipelineId === 'string';
+    }
+    wrapPipelineNodeError(ctx, error, stage, propagation) {
+        if (this.isPipelineNodeError(error)) {
+            error.metadata = {
+                ...(error.metadata || {}),
+                errorContext: propagation
+            };
+            return error;
+        }
+        const pipelineId = ctx.metadata.pipelineId || 'pipeline-default';
+        const requestId = ctx.metadata.requestId || 'unknown-request';
+        const nodeStage = this.getExecutionStage(ctx, stage);
+        return createPipelineNodeError({
+            nodeId: this.id,
+            implementation: this.implementation,
+            pipelineId,
+            requestId,
+            phase: this.getExecutionPhase(ctx),
+            stage: nodeStage,
+            error,
+            metadata: {
+                errorContext: propagation
+            }
+        });
+    }
+    getExecutionPhase(ctx) {
+        const metadata = ctx.metadata;
+        const direction = typeof metadata.direction === 'string' ? metadata.direction.toLowerCase() : undefined;
+        if (direction === 'response')
+            return 'response';
+        if (ctx.metadata.hookPhase === 'outbound')
+            return 'response';
+        return 'request';
+    }
+    getExecutionStage(ctx, stage) {
+        const hook = ctx.metadata.hookPhase ? `pipeline:${ctx.metadata.hookPhase}` : 'pipeline:execute';
+        return `${hook}:${stage}`;
+    }
+    async invokeErrorCallback(ctx, error) {
+        const callback = ctx.callbacks?.onError;
+        if (!callback)
+            return;
+        try {
+            await callback(error);
+        }
+        catch (callbackError) {
+            console.error('[PipelineNode] error callback failed', callbackError);
+        }
+    }
+}
+/**
+ * 节点包装器 - 为现有 V3 节点提供适配
+ */
+export class NodeWrapper extends BasePipelineNode {
+    wrappedNode;
+    constructor(wrappedNode, id, kind, implementation, options, capabilities) {
+        super(id, kind, implementation, options, capabilities);
+        this.wrappedNode = wrappedNode;
+    }
+    async executeLogic(ctx) {
+        // 这里应该调用适配器来转换 V3 节点
+        // 暂时返回原始上下文
+        return ctx;
+    }
+}

package/dist/conversion/conversion-v3/standards/snapshot-handles.d.ts

@@ -0,0 +1,24 @@
+import type { SnapshotHandles, PipelineContext } from './pipeline-context.js';
+import type { NodeContext } from '../types/index.js';
+import type { FilterStage } from '../../../filters/types.js';
+export type SnapshotWriter = (options: SnapshotWriterOptions) => Promise<void>;
+export interface SnapshotWriterOptions {
+    requestId?: string;
+    endpoint?: string;
+    profile?: string;
+    stage: FilterStage;
+    name?: string;
+    tag?: string;
+    data: unknown;
+}
+export interface SnapshotFactoryOptions {
+    writer?: SnapshotWriter;
+}
+export interface SnapshotMetadata {
+    requestId?: string;
+    entryEndpoint?: string;
+    profile?: string;
+    tag?: string;
+    nodeName?: string;
+}
+export declare function createSnapshotHandles(nodeContext: NodeContext, metadata: PipelineContext['metadata'], options?: SnapshotFactoryOptions): SnapshotHandles | null;

package/dist/conversion/conversion-v3/standards/snapshot-handles.js

@@ -0,0 +1,49 @@
+import { writeFilterSnapshot } from '../../../filters/utils/snapshot-writer.js';
+class SnapshotHandlesImpl {
+    meta;
+    writer;
+    config;
+    constructor(meta, writer) {
+        this.meta = meta;
+        this.writer = writer;
+        this.config = {
+            enabled: true,
+            channel: meta.channel
+        };
+    }
+    async writeRequestSnapshot(data, metadata) {
+        await this.writeSnapshot('request_post', data, metadata, 'pipeline_request');
+    }
+    async writeResponseSnapshot(data, metadata) {
+        await this.writeSnapshot('response_post', data, metadata, 'pipeline_response');
+    }
+    async writeDebugSnapshot(stage, data, metadata) {
+        await this.writeSnapshot('response_finalize', data, metadata, stage);
+    }
+    async writeSnapshot(stage, data, metadata = {}, defaultTag) {
+        await this.writer({
+            requestId: metadata.requestId ?? this.meta.requestId,
+            endpoint: metadata.entryEndpoint ?? this.meta.entryEndpoint,
+            profile: metadata.profile ?? this.meta.profile,
+            stage,
+            name: metadata.nodeName ?? this.meta.nodeId,
+            tag: metadata.tag ?? defaultTag,
+            data
+        });
+    }
+}
+export function createSnapshotHandles(nodeContext, metadata, options = {}) {
+    const snapshotConfig = nodeContext.nodeConfig.snapshot;
+    if (!snapshotConfig?.enabled) {
+        return null;
+    }
+    const meta = {
+        requestId: metadata.requestId,
+        entryEndpoint: metadata.entryEndpoint,
+        profile: metadata.providerProtocol,
+        nodeId: nodeContext.nodeConfig.id,
+        channel: snapshotConfig.channel,
+        pipelineId: metadata.pipelineId
+    };
+    return new SnapshotHandlesImpl(meta, options.writer ?? writeFilterSnapshot);
+}