@jsonstudio/llms 0.4.2

package/dist/conversion/conversion-v3/standards/context-adapter.js

@@ -0,0 +1,438 @@
+import { createPipelineContext } from './pipeline-context.js';
+import { createSnapshotHandles } from './snapshot-handles.js';
+/**
+ * 存放在 PipelineContext.extra 内部的字段
+ */
+const SOURCE_NODE_KEY = '__sourceNodeContext';
+export class ContextAdapter {
+    /**
+     * 将 V3 NodeContext 适配为标准 PipelineContext
+     */
+    static fromNodeContext(nodeContext, options = {}) {
+        const requestId = nodeContext.request.id ?? `req_${Date.now()}`;
+        const entryEndpoint = ContextAdapter.resolveEntryEndpoint(nodeContext) ?? nodeContext.request.endpoint ?? '/unknown';
+        const providerProtocol = ContextAdapter.resolveProviderProtocol(nodeContext, options);
+        const standardizedRequest = ContextAdapter.extractStandardizedRequest(nodeContext);
+        const baseMetadata = ContextAdapter.buildMetadata(nodeContext, options);
+        const pipelineContext = standardizedRequest
+            ? createPipelineContext(requestId, entryEndpoint, providerProtocol, standardizedRequest, baseMetadata)
+            : createPipelineContext(requestId, entryEndpoint, providerProtocol, baseMetadata);
+        pipelineContext.response = ContextAdapter.extractStandardizedResponse(nodeContext);
+        pipelineContext.debug = ContextAdapter.buildDebugContext(nodeContext);
+        pipelineContext.snapshots = createSnapshotHandles(nodeContext, pipelineContext.metadata);
+        pipelineContext.callbacks = nodeContext.callbacks ?? null;
+        pipelineContext.nodeContracts = ContextAdapter.buildNodeContracts(nodeContext);
+        pipelineContext.extra = {
+            ...pipelineContext.extra,
+            nodeConfig: nodeContext.nodeConfig,
+            hybridStream: ContextAdapter.extractHybridPayload(nodeContext.data),
+            [SOURCE_NODE_KEY]: ContextAdapter.createNodeContextSnapshot(nodeContext)
+        };
+        return pipelineContext;
+    }
+    /**
+     * 将 PipelineContext 还原为 V3 NodeContext
+     */
+    static toNodeContext(pipelineContext, seed) {
+        const snapshot = ContextAdapter.getSnapshotFromContext(pipelineContext) ?? seed;
+        if (!snapshot) {
+            throw new Error('ContextAdapter.toNodeContext requires either stored snapshot or seed');
+        }
+        const request = ContextAdapter.mergeRequestSnapshot(snapshot.request, pipelineContext);
+        const pipelineState = ContextAdapter.mergePipelineState(snapshot.pipeline, pipelineContext);
+        const data = ContextAdapter.mergeNodeData(snapshot.data ?? {}, pipelineContext);
+        return {
+            request,
+            pipeline: pipelineState,
+            nodeConfig: snapshot.nodeConfig,
+            data,
+            callbacks: pipelineContext.callbacks ?? snapshot.callbacks ?? null
+        };
+    }
+    /**
+     * 在 PipelineContext 上合并 NodeResult
+     */
+    static mergeNodeResult(pipelineContext, nodeContext, result, options = {}) {
+        if (result.data?.standardizedRequest) {
+            pipelineContext.request = result.data.standardizedRequest;
+        }
+        const response = ContextAdapter.extractResponseFromResult(result);
+        if (response) {
+            pipelineContext.response = response;
+        }
+        if (result.error) {
+            pipelineContext.metadata.errorContext = ContextAdapter.buildErrorContext(nodeContext, result, options.hookPhase ?? pipelineContext.metadata.hookPhase);
+        }
+        const streamingContext = ContextAdapter.updateStreamingContext(pipelineContext.debug.streamingContext, result.data);
+        if (streamingContext) {
+            pipelineContext.debug.streamingContext = streamingContext;
+        }
+        pipelineContext.metadata.hookPhase = options.hookPhase ?? pipelineContext.metadata.hookPhase;
+        pipelineContext.extra = {
+            ...pipelineContext.extra,
+            hybridStream: ContextAdapter.extractHybridPayload(result.data) ?? pipelineContext.extra?.hybridStream,
+            lastNodeResult: result,
+            [SOURCE_NODE_KEY]: ContextAdapter.createNodeContextSnapshot({
+                ...nodeContext,
+                data: result.data ?? nodeContext.data
+            })
+        };
+        return pipelineContext;
+    }
+    /**
+     * 构造 PipelineContext.metadata
+     */
+    static buildMetadata(nodeContext, options) {
+        const metadata = ContextAdapter.getRequestMetadata(nodeContext);
+        const processMode = nodeContext.pipeline.isPassthrough || metadata.processMode === 'passthrough'
+            ? 'passthrough'
+            : metadata.processMode ?? 'chat';
+        const streaming = ContextAdapter.resolveStreamingPreference(nodeContext);
+        return {
+            processMode,
+            streaming,
+            routeName: options.routeName ?? metadata.routeName ?? nodeContext.nodeConfig?.name ?? 'default',
+            pipelineId: options.pipelineId ?? metadata.pipelineId ?? 'pipeline-default',
+            providerId: metadata.providerId,
+            providerType: metadata.providerType,
+            hookPhase: (options.hookPhase ?? metadata.hookPhase),
+            toolGovernanceApplied: metadata.toolGovernanceApplied,
+            toolGovernanceTimestamp: metadata.toolGovernanceTimestamp,
+            errorContext: metadata.errorContext
+        };
+    }
+    /**
+     * 构造调试上下文
+     */
+    static buildDebugContext(nodeContext) {
+        const metadata = ContextAdapter.getRequestMetadata(nodeContext);
+        const traceEnabled = Boolean(metadata.traceEnabled ?? metadata.debug);
+        const stages = metadata.debugStages ?? {};
+        const streamingContext = ContextAdapter.buildStreamingContext(nodeContext);
+        return {
+            traceEnabled,
+            stages,
+            streamingContext
+        };
+    }
+    /**
+     * 构造节点契约
+     */
+    static buildNodeContracts(nodeContext) {
+        const capabilities = nodeContext.nodeConfig.options?.capabilities;
+        const requirements = nodeContext.nodeConfig.options?.requirements;
+        const permissions = nodeContext.nodeConfig.options?.permissions;
+        return {
+            [nodeContext.nodeConfig.id]: {
+                capabilities: Array.isArray(capabilities) ? capabilities : [],
+                requirements: Array.isArray(requirements) ? requirements : [],
+                permissions: Array.isArray(permissions) ? permissions : []
+            }
+        };
+    }
+    /**
+     * 推断 providerProtocol
+     */
+    static resolveProviderProtocol(nodeContext, options) {
+        if (options.providerProtocol)
+            return options.providerProtocol;
+        const metadata = ContextAdapter.getRequestMetadata(nodeContext);
+        if (typeof metadata.providerProtocol === 'string') {
+            return metadata.providerProtocol;
+        }
+        const fromContext = nodeContext.request.context?.providerProtocol;
+        if (typeof fromContext === 'string') {
+            return fromContext;
+        }
+        if (typeof nodeContext.request.endpoint === 'string') {
+            if (nodeContext.request.endpoint.includes('responses'))
+                return 'openai-responses';
+            if (nodeContext.request.endpoint.includes('messages'))
+                return 'anthropic-messages';
+        }
+        return 'openai-chat';
+    }
+    /**
+     * 解析请求附加 metadata
+     */
+    static getRequestMetadata(nodeContext) {
+        const context = nodeContext.request.context;
+        if (!context || typeof context !== 'object') {
+            return {};
+        }
+        if (context.metadata && typeof context.metadata === 'object') {
+            return context.metadata;
+        }
+        return context;
+    }
+    /**
+     * 解析入口端点
+     */
+    static resolveEntryEndpoint(nodeContext) {
+        const metadata = ContextAdapter.getRequestMetadata(nodeContext);
+        if (typeof metadata.entryEndpoint === 'string') {
+            return metadata.entryEndpoint;
+        }
+        const ctx = nodeContext.request.context;
+        if (ctx && typeof ctx === 'object' && typeof ctx.entryEndpoint === 'string') {
+            return ctx.entryEndpoint;
+        }
+        return undefined;
+    }
+    /**
+     * 解析流式偏好
+     */
+    static resolveStreamingPreference(nodeContext) {
+        const metadata = ContextAdapter.getRequestMetadata(nodeContext);
+        if (metadata.stream === true)
+            return 'always';
+        if (metadata.stream === false)
+            return 'never';
+        const options = nodeContext.request.options;
+        if (options?.streamingFormat === 'sse')
+            return 'always';
+        if (options?.streamingFormat === 'json')
+            return 'never';
+        const payload = nodeContext.request.payload;
+        if (payload && typeof payload.stream === 'boolean') {
+            return payload.stream ? 'always' : 'never';
+        }
+        return 'auto';
+    }
+    /**
+     * 判断请求是否包含流式语义
+     */
+    static hasStreamingIntent(nodeContext) {
+        const metadata = ContextAdapter.getRequestMetadata(nodeContext);
+        if (metadata.stream === true)
+            return true;
+        const payload = nodeContext.request.payload;
+        if (payload && typeof payload.stream === 'boolean') {
+            return payload.stream;
+        }
+        if (nodeContext.request.options?.streamingFormat === 'sse') {
+            return true;
+        }
+        const hybridPayload = ContextAdapter.extractHybridPayload(nodeContext.data);
+        if (hybridPayload?.stream)
+            return true;
+        return ContextAdapter.isReadable(nodeContext.request.payload);
+    }
+    /**
+     * 构建 StreamingContext
+     */
+    static buildStreamingContext(nodeContext) {
+        const mode = ContextAdapter.resolveStreamingMode(nodeContext);
+        return {
+            mode,
+            buffer: [],
+            eventId: `${mode}_${nodeContext.request.id}_${Date.now()}`,
+            stats: {
+                eventsProcessed: 0,
+                totalBytes: 0,
+                averageLatency: 0
+            }
+        };
+    }
+    /**
+     * 根据端点 + 流式意图推断模式
+     */
+    static resolveStreamingMode(nodeContext) {
+        const hasStreaming = ContextAdapter.hasStreamingIntent(nodeContext);
+        const isResponsesEndpoint = nodeContext.request.endpoint?.includes('responses');
+        if (isResponsesEndpoint && hasStreaming) {
+            return 'sse';
+        }
+        if (hasStreaming) {
+            return 'hybrid';
+        }
+        return 'json';
+    }
+    /**
+     * 更新 StreamingContext（基于节点输出）
+     */
+    static updateStreamingContext(streamingContext, data) {
+        if (!streamingContext)
+            return streamingContext;
+        if (!data)
+            return streamingContext;
+        const hybridPayload = ContextAdapter.extractHybridPayload(data);
+        if (hybridPayload?.mode) {
+            return {
+                ...streamingContext,
+                mode: hybridPayload.mode
+            };
+        }
+        return streamingContext;
+    }
+    /**
+     * 提取标准化请求
+     */
+    static extractStandardizedRequest(nodeContext) {
+        const data = nodeContext.data ?? {};
+        if (data.standardizedRequest) {
+            return data.standardizedRequest;
+        }
+        if (data.request && typeof data.request === 'object' && 'model' in data.request) {
+            return data.request;
+        }
+        const payload = nodeContext.request.payload;
+        if (payload && payload.standardizedRequest && typeof payload.standardizedRequest === 'object') {
+            return payload.standardizedRequest;
+        }
+        return undefined;
+    }
+    /**
+     * 提取标准化响应
+     */
+    static extractStandardizedResponse(nodeContext) {
+        const data = nodeContext.data ?? {};
+        if (data.response && typeof data.response === 'object') {
+            return data.response;
+        }
+        const conversionResponse = data.conversionResponse;
+        if (conversionResponse?.data && typeof conversionResponse.data === 'object') {
+            return conversionResponse.data;
+        }
+        return undefined;
+    }
+    /**
+     * 从 NodeResult 中提取响应
+     */
+    static extractResponseFromResult(result) {
+        if (result.data?.response && typeof result.data.response === 'object') {
+            return result.data.response;
+        }
+        const conversionResponse = result.data?.conversionResponse;
+        if (conversionResponse?.data && typeof conversionResponse.data === 'object') {
+            return conversionResponse.data;
+        }
+        return undefined;
+    }
+    /**
+     * 记录 NodeContext 快照以供 round-trip
+     */
+    static createNodeContextSnapshot(nodeContext) {
+        return {
+            request: nodeContext.request,
+            pipeline: nodeContext.pipeline,
+            nodeConfig: nodeContext.nodeConfig,
+            data: { ...nodeContext.data },
+            callbacks: nodeContext.callbacks ?? null
+        };
+    }
+    /**
+     * 从 PipelineContext.extra 获取快照
+     */
+    static getSnapshotFromContext(pipelineContext) {
+        const extra = pipelineContext.extra ?? {};
+        const snapshot = extra[SOURCE_NODE_KEY];
+        if (snapshot && typeof snapshot === 'object') {
+            const candidate = snapshot;
+            if (candidate.request && candidate.pipeline && candidate.nodeConfig) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 合并请求快照和 PipelineContext 元数据
+     */
+    static mergeRequestSnapshot(request, pipelineContext) {
+        const mergedContext = {
+            ...(request.context ?? {}),
+            metadata: {
+                ...(ContextAdapter.getRequestMetadata({ request })),
+                ...pipelineContext.metadata
+            },
+            entryEndpoint: pipelineContext.metadata.entryEndpoint
+        };
+        return {
+            ...request,
+            context: mergedContext,
+            endpoint: pipelineContext.metadata.entryEndpoint
+        };
+    }
+    /**
+     * 合并 pipelineState
+     */
+    static mergePipelineState(pipeline, pipelineContext) {
+        return {
+            ...pipeline,
+            currentNode: pipelineContext.metadata.routeName ?? pipeline.currentNode
+        };
+    }
+    /**
+     * 合并 nodeContext data
+     */
+    static mergeNodeData(data, pipelineContext) {
+        const merged = {
+            ...data
+        };
+        if (pipelineContext.request) {
+            merged.standardizedRequest = pipelineContext.request;
+        }
+        if (pipelineContext.response) {
+            merged.response = pipelineContext.response;
+        }
+        if (pipelineContext.extra?.hybridStream) {
+            merged.hybridStream = pipelineContext.extra.hybridStream;
+        }
+        return merged;
+    }
+    /**
+     * 判断对象是否是 Readable
+     */
+    static isReadable(input) {
+        return Boolean(input &&
+            typeof input === 'object' &&
+            typeof input.read === 'function' &&
+            typeof input.pipe === 'function');
+    }
+    /**
+     * 提取 HybridStreamPayload
+     */
+    static extractHybridPayload(source) {
+        if (!source || typeof source !== 'object')
+            return null;
+        const payload = source;
+        if (payload.__sse_responses) {
+            return {
+                mode: 'sse',
+                stream: payload.__sse_responses,
+                metadata: payload.responseMetadata
+            };
+        }
+        if (payload.sseStream) {
+            return {
+                mode: 'hybrid',
+                stream: payload.sseStream,
+                snapshot: payload.response
+            };
+        }
+        if (payload.hybridStream && typeof payload.hybridStream === 'object') {
+            const inner = payload.hybridStream;
+            return {
+                mode: inner.mode ?? 'hybrid',
+                stream: inner.stream,
+                snapshot: inner.snapshot,
+                metadata: inner.metadata
+            };
+        }
+        return null;
+    }
+    /**
+     * 构建错误上下文
+     */
+    static buildErrorContext(nodeContext, result, hookPhase) {
+        return {
+            originalError: result.error?.cause ?? new Error(result.error?.message ?? 'Unknown error'),
+            stage: hookPhase ?? 'process',
+            nodeId: nodeContext.nodeConfig.id,
+            timestamp: Date.now(),
+            severity: 'high',
+            shouldTerminate: true,
+            tags: [result.error?.code ?? 'unknown']
+        };
+    }
+}

package/dist/conversion/conversion-v3/standards/errors.d.ts

@@ -0,0 +1,38 @@
+import type { ErrorPropagationContext } from './pipeline-context.js';
+export interface PipelineNodeError extends Error {
+    nodeId: string;
+    implementation: string;
+    pipelineId: string;
+    requestId: string;
+    phase: 'request' | 'response';
+    stage: string;
+    metadata?: Record<string, unknown>;
+    cause?: unknown;
+    originalError?: unknown;
+}
+export interface PipelineWarningContext {
+    nodeId: string;
+    pipelineId: string;
+    requestId: string;
+    phase: 'request' | 'response';
+    message: string;
+    detail?: unknown;
+}
+export type PipelineErrorCallback = (error: PipelineNodeError) => Promise<void> | void;
+export type PipelineWarningCallback = (warning: PipelineWarningContext) => Promise<void> | void;
+export interface PipelineErrorCallbacks {
+    onError?: PipelineErrorCallback;
+    onWarning?: PipelineWarningCallback;
+}
+export declare function createPipelineNodeError(params: {
+    nodeId: string;
+    implementation: string;
+    pipelineId: string;
+    requestId: string;
+    phase: 'request' | 'response';
+    stage: string;
+    error?: unknown;
+    metadata?: Record<string, unknown>;
+}): PipelineNodeError;
+export declare function createWarningContext(params: PipelineWarningContext): PipelineWarningContext;
+export declare function attachErrorContext(err: PipelineNodeError, context: ErrorPropagationContext): PipelineNodeError;

package/dist/conversion/conversion-v3/standards/errors.js

@@ -0,0 +1,27 @@
+export function createPipelineNodeError(params) {
+    const baseError = params.error instanceof Error ? params.error : undefined;
+    const errorMessage = baseError?.message || 'Pipeline node execution failed';
+    const err = Object.assign(new Error(errorMessage), {
+        name: 'PipelineNodeError',
+        nodeId: params.nodeId,
+        implementation: params.implementation,
+        pipelineId: params.pipelineId,
+        requestId: params.requestId,
+        phase: params.phase,
+        stage: params.stage,
+        metadata: params.metadata,
+        cause: baseError,
+        originalError: params.error
+    });
+    return err;
+}
+export function createWarningContext(params) {
+    return { ...params };
+}
+export function attachErrorContext(err, context) {
+    err.metadata = {
+        ...(err.metadata || {}),
+        errorContext: context
+    };
+    return err;
+}

package/dist/conversion/conversion-v3/standards/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * RouteCodex V2 标准接口导出
+ * Phase 1a: 完整 PipelineContext 接口 + 验证机制
+ */
+export * from './pipeline-context.js';
+export * from './node-capabilities.js';
+export * from './pipeline-node.js';
+export * from './context-adapter.js';
+export * from './snapshot-handles.js';
+export * from './errors.js';
+export type { CanonicalRequest, CanonicalResponse, SnapshotHandles, PipelineContext, NodeCapabilities, PipelineNodeKind, ErrorPropagationContext, StreamingContext } from './pipeline-context.js';
+export type { PipelineNode, NodeImplementation, NodeHealthStatus, NodeMetrics, ValidationResult } from './pipeline-node.js';
+export type { HybridStreamPayload, ContextAdapterOptions, NodeContextSeed, MergeOptions as ContextMergeOptions } from './context-adapter.js';
+export type { SnapshotWriter, SnapshotWriterOptions, SnapshotMetadata, SnapshotFactoryOptions } from './snapshot-handles.js';
+export type { PipelineNodeError, PipelineWarningContext, PipelineErrorCallback, PipelineWarningCallback, PipelineErrorCallbacks } from './errors.js';

package/dist/conversion/conversion-v3/standards/index.js

@@ -0,0 +1,11 @@
+/**
+ * RouteCodex V2 标准接口导出
+ * Phase 1a: 完整 PipelineContext 接口 + 验证机制
+ */
+// 核心接口
+export * from './pipeline-context.js';
+export * from './node-capabilities.js';
+export * from './pipeline-node.js';
+export * from './context-adapter.js';
+export * from './snapshot-handles.js';
+export * from './errors.js';

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

@@ -0,0 +1,123 @@
+/**
+ * 节点能力契约系统
+ * 用于定义和验证节点权限、能力和职责边界
+ */
+import type { NodeCapabilities, PipelineNodeKind } from './pipeline-context.js';
+/**
+ * 预定义的节点能力集合
+ */
+export declare const PREDEFINED_CAPABILITIES: {
+    readonly BASIC: NodeCapabilities;
+    readonly TOOL_GOVERNANCE: NodeCapabilities;
+    readonly PROVIDER_ACCESS: NodeCapabilities;
+    readonly STREAMING: NodeCapabilities;
+    readonly SNAPSHOT_ACCESS: NodeCapabilities;
+    readonly METADATA_MODIFY: NodeCapabilities;
+    readonly FULL: NodeCapabilities;
+};
+/**
+ * 节点类型与默认能力映射
+ */
+export declare const NODE_TYPE_DEFAULT_CAPABILITIES: Record<PipelineNodeKind, NodeCapabilities>;
+/**
+ * 特殊节点的能力映射
+ */
+export declare const SPECIAL_NODE_CAPABILITIES: Record<string, NodeCapabilities>;
+/**
+ * 能力验证规则
+ */
+export interface CapabilityRule {
+    /** 规则名称 */
+    name: string;
+    /** 规则描述 */
+    description: string;
+    /** 验证函数 */
+    validator: (capabilities: NodeCapabilities, nodeId: string, nodeKind: PipelineNodeKind) => boolean;
+    /** 错误消息 */
+    errorMessage: string;
+    /** 规则优先级 */
+    priority: number;
+}
+/**
+ * 预定义的能力验证规则
+ */
+export declare const CAPABILITY_VALIDATION_RULES: CapabilityRule[];
+/**
+ * 能力验证器
+ */
+export declare class CapabilityValidator {
+    /**
+     * 验证节点能力
+     */
+    static validateNodeCapabilities(nodeId: string, nodeKind: PipelineNodeKind, capabilities: NodeCapabilities): CapabilityValidationResult;
+    /**
+     * 检测能力冲突
+     */
+    private static detectCapabilityConflicts;
+    /**
+     * 获取节点的推荐能力
+     */
+    static getRecommendedCapabilities(nodeId: string, nodeKind: PipelineNodeKind): NodeCapabilities;
+    /**
+     * 验证能力组合的合理性
+     */
+    static validateCapabilityCombination(capabilities: NodeCapabilities): CapabilityValidationResult;
+}
+/**
+ * 能力验证结果接口
+ */
+export interface CapabilityValidationResult {
+    /** 是否验证通过 */
+    valid: boolean;
+    /** 错误列表 */
+    errors: CapabilityValidationError[];
+    /** 警告列表 */
+    warnings: CapabilityValidationWarning[];
+}
+/**
+ * 能力验证错误接口
+ */
+export interface CapabilityValidationError {
+    /** 规则名称 */
+    rule: string;
+    /** 错误消息 */
+    message: string;
+    /** 错误严重程度 */
+    severity: 'error' | 'warning';
+    /** 详细信息 */
+    details?: Record<string, unknown>;
+}
+/**
+ * 能力验证警告接口
+ */
+export interface CapabilityValidationWarning {
+    /** 规则名称 */
+    rule: string;
+    /** 警告消息 */
+    message: string;
+    /** 警告严重程度 */
+    severity: 'error' | 'warning';
+    /** 详细信息 */
+    details?: Record<string, unknown>;
+}
+/**
+ * 能力描述符
+ */
+export interface CapabilityDescriptor {
+    /** 能力名称 */
+    name: string;
+    /** 能力描述 */
+    description: string;
+    /** 风险级别 */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** 是否需要特殊权限 */
+    requiresSpecialPermission: boolean;
+    /** 相关的节点类型 */
+    relatedNodeTypes: PipelineNodeKind[];
+    /** 使用示例 */
+    usageExample?: string;
+}
+/**
+ * 所有能力的描述符
+ */
+export declare const CAPABILITY_DESCRIPTORS: Record<keyof NodeCapabilities, CapabilityDescriptor>;