@jsonstudio/llms 0.4.2

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

@@ -0,0 +1,330 @@
+/**
+ * 节点能力契约系统
+ * 用于定义和验证节点权限、能力和职责边界
+ */
+/**
+ * 预定义的节点能力集合
+ */
+export const PREDEFINED_CAPABILITIES = {
+    // 基础能力
+    BASIC: {
+        canModifyTools: false,
+        canAccessProvider: false,
+        canModifyMetadata: false,
+        canHandleStreaming: false,
+        canAccessSnapshots: false
+    },
+    // 工具治理能力
+    TOOL_GOVERNANCE: {
+        canModifyTools: true,
+        canAccessProvider: false,
+        canModifyMetadata: false,
+        canHandleStreaming: false,
+        canAccessSnapshots: false
+    },
+    // Provider 访问能力
+    PROVIDER_ACCESS: {
+        canModifyTools: false,
+        canAccessProvider: true,
+        canModifyMetadata: true,
+        canHandleStreaming: true,
+        canAccessSnapshots: true
+    },
+    // 流式处理能力
+    STREAMING: {
+        canModifyTools: false,
+        canAccessProvider: false,
+        canModifyMetadata: false,
+        canHandleStreaming: true,
+        canAccessSnapshots: false
+    },
+    // 快照访问能力
+    SNAPSHOT_ACCESS: {
+        canModifyTools: false,
+        canAccessProvider: false,
+        canModifyMetadata: false,
+        canHandleStreaming: false,
+        canAccessSnapshots: true
+    },
+    // 元数据修改能力
+    METADATA_MODIFY: {
+        canModifyTools: false,
+        canAccessProvider: false,
+        canModifyMetadata: true,
+        canHandleStreaming: false,
+        canAccessSnapshots: false
+    },
+    // 全能力（仅限特殊节点）
+    FULL: {
+        canModifyTools: true,
+        canAccessProvider: true,
+        canModifyMetadata: true,
+        canHandleStreaming: true,
+        canAccessSnapshots: true
+    }
+};
+/**
+ * 节点类型与默认能力映射
+ */
+export const NODE_TYPE_DEFAULT_CAPABILITIES = {
+    'sse-input': PREDEFINED_CAPABILITIES.STREAMING,
+    'input': PREDEFINED_CAPABILITIES.BASIC,
+    'process': PREDEFINED_CAPABILITIES.BASIC, // process 节点需要单独配置
+    'workflow': PREDEFINED_CAPABILITIES.METADATA_MODIFY,
+    'compatibility': PREDEFINED_CAPABILITIES.METADATA_MODIFY,
+    'provider': PREDEFINED_CAPABILITIES.PROVIDER_ACCESS,
+    'output': PREDEFINED_CAPABILITIES.BASIC,
+    'sse-output': PREDEFINED_CAPABILITIES.STREAMING
+};
+/**
+ * 特殊节点的能力映射
+ */
+export const SPECIAL_NODE_CAPABILITIES = {
+    'tool-governance': PREDEFINED_CAPABILITIES.TOOL_GOVERNANCE,
+    'chat-process': PREDEFINED_CAPABILITIES.TOOL_GOVERNANCE,
+    'passthrough-process': PREDEFINED_CAPABILITIES.BASIC,
+    'response-process': PREDEFINED_CAPABILITIES.BASIC,
+    'compatibility-process': PREDEFINED_CAPABILITIES.METADATA_MODIFY,
+    'streaming-control': PREDEFINED_CAPABILITIES.STREAMING,
+    'workflow-monitoring': PREDEFINED_CAPABILITIES.SNAPSHOT_ACCESS
+};
+/**
+ * 预定义的能力验证规则
+ */
+export const CAPABILITY_VALIDATION_RULES = [
+    {
+        name: 'tool-modification-restriction',
+        description: '只有 process 类型的特定节点可以修改工具',
+        priority: 100,
+        validator: (capabilities, nodeId, nodeKind) => {
+            if (capabilities.canModifyTools) {
+                return nodeKind === 'process' && (nodeId === 'tool-governance' ||
+                    nodeId === 'chat-process' ||
+                    nodeId.includes('tool'));
+            }
+            return true;
+        },
+        errorMessage: 'Only authorized process nodes can modify tools'
+    },
+    {
+        name: 'provider-access-restriction',
+        description: '只有 provider 节点可以直接访问外部 Provider',
+        priority: 90,
+        validator: (capabilities, nodeId, nodeKind) => {
+            if (capabilities.canAccessProvider) {
+                return nodeKind === 'provider';
+            }
+            return true;
+        },
+        errorMessage: 'Only provider nodes can directly access external providers'
+    },
+    {
+        name: 'streaming-handler-restriction',
+        description: '只有 SSE 节点和专门的流式控制节点可以处理流式数据',
+        priority: 80,
+        validator: (capabilities, nodeId, nodeKind) => {
+            if (capabilities.canHandleStreaming) {
+                return nodeKind === 'sse-input' ||
+                    nodeKind === 'sse-output' ||
+                    nodeId === 'streaming-control' ||
+                    nodeId.includes('streaming');
+            }
+            return true;
+        },
+        errorMessage: 'Only SSE nodes and streaming control nodes can handle streaming data'
+    },
+    {
+        name: 'metadata-modification-scope',
+        description: '元数据修改权限应该合理分配',
+        priority: 70,
+        validator: (capabilities, nodeId, nodeKind) => {
+            if (capabilities.canModifyMetadata) {
+                return ['workflow', 'compatibility', 'provider'].includes(nodeKind) ||
+                    nodeId.includes('metadata') ||
+                    nodeId.includes('monitoring');
+            }
+            return true;
+        },
+        errorMessage: 'Metadata modification should be limited to workflow, compatibility and provider nodes'
+    },
+    {
+        name: 'snapshot-access-control',
+        description: '快照访问权限应该合理分配',
+        priority: 60,
+        validator: (capabilities, nodeId, nodeKind) => {
+            if (capabilities.canAccessSnapshots) {
+                return nodeKind === 'provider' ||
+                    nodeId.includes('monitoring') ||
+                    nodeId.includes('snapshot');
+            }
+            return true;
+        },
+        errorMessage: 'Snapshot access should be limited to provider and monitoring nodes'
+    }
+];
+/**
+ * 能力验证器
+ */
+export class CapabilityValidator {
+    /**
+     * 验证节点能力
+     */
+    static validateNodeCapabilities(nodeId, nodeKind, capabilities) {
+        const errors = [];
+        const warnings = [];
+        // 按优先级排序验证规则
+        const sortedRules = [...CAPABILITY_VALIDATION_RULES].sort((a, b) => b.priority - a.priority);
+        for (const rule of sortedRules) {
+            try {
+                if (!rule.validator(capabilities, nodeId, nodeKind)) {
+                    errors.push({
+                        rule: rule.name,
+                        message: rule.errorMessage,
+                        severity: 'error',
+                        details: {
+                            nodeId,
+                            nodeKind,
+                            capabilities
+                        }
+                    });
+                }
+            }
+            catch (error) {
+                errors.push({
+                    rule: rule.name,
+                    message: `Validation rule execution failed: ${error instanceof Error ? error.message : String(error)}`,
+                    severity: 'error',
+                    details: {
+                        nodeId,
+                        nodeKind,
+                        capabilities,
+                        ruleError: error instanceof Error ? error.stack : String(error)
+                    }
+                });
+            }
+        }
+        // 检查能力冲突
+        const conflictWarnings = this.detectCapabilityConflicts(nodeId, capabilities);
+        warnings.push(...conflictWarnings);
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * 检测能力冲突
+     */
+    static detectCapabilityConflicts(nodeId, capabilities) {
+        const warnings = [];
+        // 检查是否有不合理的权限组合
+        if (capabilities.canModifyTools && !capabilities.canModifyMetadata) {
+            warnings.push({
+                rule: 'capability-conflict',
+                message: 'Tool modification capability without metadata modification might be incomplete',
+                severity: 'warning',
+                details: {
+                    nodeId,
+                    conflictingCapabilities: ['canModifyTools', 'canModifyMetadata']
+                }
+            });
+        }
+        if (capabilities.canAccessProvider && !capabilities.canHandleStreaming) {
+            warnings.push({
+                rule: 'capability-conflict',
+                message: 'Provider access without streaming capability might limit functionality',
+                severity: 'warning',
+                details: {
+                    nodeId,
+                    conflictingCapabilities: ['canAccessProvider', 'canHandleStreaming']
+                }
+            });
+        }
+        return warnings;
+    }
+    /**
+     * 获取节点的推荐能力
+     */
+    static getRecommendedCapabilities(nodeId, nodeKind) {
+        // 优先使用特殊节点能力
+        if (SPECIAL_NODE_CAPABILITIES[nodeId]) {
+            return { ...SPECIAL_NODE_CAPABILITIES[nodeId] };
+        }
+        // 使用类型默认能力
+        return { ...NODE_TYPE_DEFAULT_CAPABILITIES[nodeKind] };
+    }
+    /**
+     * 验证能力组合的合理性
+     */
+    static validateCapabilityCombination(capabilities) {
+        const errors = [];
+        const warnings = [];
+        // 检查逻辑一致性
+        if (capabilities.canAccessProvider && !capabilities.canModifyMetadata) {
+            warnings.push({
+                rule: 'logical-consistency',
+                message: 'Provider access typically requires metadata modification',
+                severity: 'warning',
+                details: { capabilities }
+            });
+        }
+        if (capabilities.canHandleStreaming && !capabilities.canAccessSnapshots) {
+            warnings.push({
+                rule: 'debugging-support',
+                message: 'Streaming handlers should have snapshot access for debugging',
+                severity: 'warning',
+                details: { capabilities }
+            });
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+}
+/**
+ * 所有能力的描述符
+ */
+export const CAPABILITY_DESCRIPTORS = {
+    canModifyTools: {
+        name: '工具修改',
+        description: '允许节点修改工具定义、工具调用和工具参数',
+        riskLevel: 'high',
+        requiresSpecialPermission: true,
+        relatedNodeTypes: ['process'],
+        usageExample: 'tool-governance, chat-process'
+    },
+    canAccessProvider: {
+        name: 'Provider 访问',
+        description: '允许节点直接访问外部 AI 服务提供商',
+        riskLevel: 'medium',
+        requiresSpecialPermission: false,
+        relatedNodeTypes: ['provider'],
+        usageExample: 'provider-http, provider-openai'
+    },
+    canModifyMetadata: {
+        name: '元数据修改',
+        description: '允许节点修改请求/响应的元数据',
+        riskLevel: 'low',
+        requiresSpecialPermission: false,
+        relatedNodeTypes: ['workflow', 'compatibility', 'provider'],
+        usageExample: 'compatibility-process, workflow-monitoring'
+    },
+    canHandleStreaming: {
+        name: '流式处理',
+        description: '允许节点处理 SSE 流式数据',
+        riskLevel: 'medium',
+        requiresSpecialPermission: false,
+        relatedNodeTypes: ['sse-input', 'sse-output'],
+        usageExample: 'sse-input, sse-output, streaming-control'
+    },
+    canAccessSnapshots: {
+        name: '快照访问',
+        description: '允许节点读写调试快照数据',
+        riskLevel: 'low',
+        requiresSpecialPermission: false,
+        relatedNodeTypes: ['provider', 'workflow'],
+        usageExample: 'workflow-monitoring, provider-http'
+    }
+};

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

@@ -0,0 +1,237 @@
+/**
+ * RouteCodex V2 标准 PipelineContext 接口
+ * 严格对齐 pipeline-node-interface.md 规范
+ */
+import type { StandardizedRequest, ToolCall } from '../types/request-types.js';
+import type { PipelineErrorCallbacks } from './errors.js';
+import type { TargetMetadata } from '../../../router/virtual-router/types.js';
+/**
+ * 标准化响应接口
+ * 与 StandardizedRequest 对应的响应格式
+ */
+export interface StandardizedResponse {
+    /** 响应消息 */
+    message: {
+        role: 'assistant';
+        content: string | null;
+        tool_calls?: ToolCall[];
+    };
+    /** 是否完成 */
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call';
+    /** 使用量统计 */
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    /** 响应模型 */
+    model: string;
+    /** 创建时间戳 */
+    created?: number;
+    /** 请求ID */
+    id?: string;
+    /** 额外元数据 */
+    metadata?: Record<string, unknown>;
+}
+export type CanonicalRequest = StandardizedRequest;
+export type CanonicalResponse = StandardizedResponse;
+/**
+ * 快照句柄接口
+ */
+export interface SnapshotHandles {
+    /** 写入请求快照 */
+    writeRequestSnapshot?(data: CanonicalRequest, metadata?: Record<string, unknown>): Promise<void>;
+    /** 写入响应快照 */
+    writeResponseSnapshot?(data: CanonicalResponse, metadata?: Record<string, unknown>): Promise<void>;
+    /** 写入调试快照 */
+    writeDebugSnapshot?(stage: string, data: unknown, metadata?: Record<string, unknown>): Promise<void>;
+    /** 快照配置 */
+    config?: {
+        enabled: boolean;
+        channel?: string;
+        baseDir?: string;
+    };
+}
+/**
+ * 标准 PipelineContext 接口
+ * 严格对齐 pipeline-node-interface.md 规范
+ */
+export interface PipelineContext {
+    /** 请求对象（由 llmswitch inbound 节点生产） */
+    request?: CanonicalRequest;
+    /** 响应对象（由 llmswitch response inbound 节点生产） */
+    response?: CanonicalResponse;
+    /** 元数据 */
+    metadata: {
+        /** 请求ID */
+        requestId: string;
+        /** 入口端点 */
+        entryEndpoint: string;
+        /** Provider 协议 */
+        providerProtocol: 'openai-chat' | 'openai-responses' | 'anthropic-messages' | 'gemini-chat' | string;
+        /** 处理模式 */
+        processMode: 'chat' | 'passthrough';
+        /** 流式策略 */
+        streaming: 'always' | 'never' | 'auto';
+        /** 路由名称 */
+        routeName: string;
+        /** 流水线ID */
+        pipelineId: string;
+        /** Provider ID（可选） */
+        providerId?: string;
+        /** 模型ID（可选） */
+        modelId?: string;
+        /** Provider 类型（可选） */
+        providerType?: string;
+        /** 目标 Provider 元数据 */
+        target?: TargetMetadata;
+        /** 生命周期钩子阶段 */
+        hookPhase?: 'inbound' | 'outbound' | 'pre-process' | 'post-process';
+        /** 错误传播上下文 */
+        errorContext?: {
+            originalError: Error;
+            stage: string;
+            nodeId: string;
+            timestamp: number;
+        };
+        /** 工具治理状态 */
+        toolGovernanceApplied?: boolean;
+        /** 工具治理执行时间戳 */
+        toolGovernanceTimestamp?: number;
+    };
+    /** 调试信息 */
+    debug: {
+        /** 是否启用追踪 */
+        traceEnabled: boolean;
+        /** 各阶段调试数据 */
+        stages: Record<string, unknown>;
+        /** 流式语义追踪 */
+        streamingContext?: {
+            mode: 'sse' | 'json' | 'hybrid';
+            buffer: unknown[];
+            eventId: string;
+        };
+    };
+    /** 快照句柄 */
+    snapshots: SnapshotHandles | null;
+    /** 错误/告警回调 */
+    callbacks?: PipelineErrorCallbacks | null;
+    /** 额外数据 */
+    extra: Record<string, unknown>;
+    /** 节点间通信契约 */
+    nodeContracts: {
+        [nodeId: string]: {
+            /** 节点能力列表 */
+            capabilities: string[];
+            /** 节点需求列表 */
+            requirements: string[];
+            /** 节点权限列表 */
+            permissions: string[];
+        };
+    };
+}
+/**
+ * 节点能力契约接口
+ */
+export interface NodeCapabilities {
+    /** 是否可以修改工具 */
+    canModifyTools: boolean;
+    /** 是否可以访问 Provider */
+    canAccessProvider: boolean;
+    /** 是否可以修改元数据 */
+    canModifyMetadata: boolean;
+    /** 是否可以处理流式 */
+    canHandleStreaming: boolean;
+    /** 是否可以访问快照 */
+    canAccessSnapshots: boolean;
+}
+/**
+ * 节点类型枚举（对齐标准规范）
+ */
+export type PipelineNodeKind = 'sse-input' | 'input' | 'process' | 'workflow' | 'compatibility' | 'provider' | 'output' | 'sse-output';
+/**
+ * 错误传播上下文接口
+ */
+export interface ErrorPropagationContext {
+    /** 原始错误 */
+    originalError: Error;
+    /** 错误发生的阶段 */
+    stage: string;
+    /** 发生错误的节点ID */
+    nodeId: string;
+    /** 错误时间戳 */
+    timestamp: number;
+    /** 错误严重程度 */
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    /** 是否应该中断流水线 */
+    shouldTerminate: boolean;
+    /** 错误标签 */
+    tags: string[];
+}
+/**
+ * 流式语义上下文接口
+ */
+export interface StreamingContext {
+    /** 流式模式 */
+    mode: 'sse' | 'json' | 'hybrid';
+    /** 事件缓冲区 */
+    buffer: unknown[];
+    /** 事件ID */
+    eventId: string;
+    /** 流式配置 */
+    config?: {
+        /** 缓冲区大小限制 */
+        bufferSize?: number;
+        /** 刷新间隔（毫秒） */
+        flushInterval?: number;
+        /** 是否启用压缩 */
+        compression?: boolean;
+    };
+    /** 流式统计 */
+    stats?: {
+        /** 已处理事件数 */
+        eventsProcessed: number;
+        /** 总数据大小 */
+        totalBytes: number;
+        /** 平均延迟 */
+        averageLatency: number;
+    };
+}
+/**
+ * 创建新的 PipelineContext
+ */
+export declare function createPipelineContext(requestId: string, entryEndpoint: string, providerProtocol: string, initialMetadata?: Partial<PipelineContext['metadata']>): PipelineContext;
+/**
+ * 从 StandardizedRequest 创建 PipelineContext
+ */
+export declare function createPipelineContext(requestId: string, entryEndpoint: string, providerProtocol: string, request: StandardizedRequest, initialMetadata?: Partial<PipelineContext['metadata']>): PipelineContext;
+/**
+ * 验证 PipelineContext 的完整性
+ */
+export declare function validatePipelineContext(context: PipelineContext): ValidationResult;
+/**
+ * 错误验证接口
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+    value?: unknown;
+}
+/**
+ * 警告验证接口
+ */
+export interface ValidationWarning {
+    field: string;
+    message: string;
+    code: string;
+    value?: unknown;
+}
+/**
+ * 验证结果接口
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}

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

@@ -0,0 +1,84 @@
+/**
+ * RouteCodex V2 标准 PipelineContext 接口
+ * 严格对齐 pipeline-node-interface.md 规范
+ */
+export function createPipelineContext(requestId, entryEndpoint, providerProtocol, requestOrMetadata, initialMetadata) {
+    // 检测第三个参数是请求对象还是元数据
+    const isRequestObject = requestOrMetadata && 'model' in requestOrMetadata && 'messages' in requestOrMetadata;
+    const request = isRequestObject ? requestOrMetadata : undefined;
+    const metadata = isRequestObject ? initialMetadata : requestOrMetadata;
+    const context = {
+        request,
+        metadata: {
+            requestId,
+            entryEndpoint,
+            providerProtocol,
+            processMode: 'chat',
+            streaming: 'auto',
+            routeName: 'default',
+            pipelineId: 'default',
+            // 从请求中提取模型ID
+            modelId: request?.model,
+            ...metadata
+        },
+        debug: {
+            traceEnabled: false,
+            stages: {}
+        },
+        snapshots: null,
+        callbacks: null,
+        extra: {},
+        nodeContracts: {}
+    };
+    return context;
+}
+/**
+ * 验证 PipelineContext 的完整性
+ */
+export function validatePipelineContext(context) {
+    const errors = [];
+    const warnings = [];
+    // 检查必需字段
+    if (!context.metadata.requestId) {
+        errors.push({
+            field: 'metadata.requestId',
+            message: 'Request ID is required',
+            code: 'MISSING_REQUEST_ID'
+        });
+    }
+    if (!context.metadata.entryEndpoint) {
+        errors.push({
+            field: 'metadata.entryEndpoint',
+            message: 'Entry endpoint is required',
+            code: 'MISSING_ENTRY_ENDPOINT'
+        });
+    }
+    if (!context.metadata.providerProtocol) {
+        errors.push({
+            field: 'metadata.providerProtocol',
+            message: 'Provider protocol is required',
+            code: 'MISSING_PROVIDER_PROTOCOL'
+        });
+    }
+    // 检查数据一致性
+    if (context.request && context.response) {
+        warnings.push({
+            field: 'data_consistency',
+            message: 'Both request and response present in context',
+            code: 'BOTH_REQUEST_AND_RESPONSE'
+        });
+    }
+    // 检查错误上下文
+    if (context.metadata.errorContext && !context.debug.traceEnabled) {
+        warnings.push({
+            field: 'error_context',
+            message: 'Error context present but trace is disabled',
+            code: 'ERROR_CONTEXT_NO_TRACE'
+        });
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+    };
+}