@jsonstudio/llms 0.4.2

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

@@ -0,0 +1,8 @@
+/**
+ * RouteCodex V2 验证模块导出
+ * Phase 1a: 完整验证机制
+ */
+export * from './tool-governance-enforcer.js';
+export * from './node-graph-validator.js';
+export type { PipelineConfig, PipelineConfigEntry, PipelineNodeConfig, ToolGovernanceViolation, ToolGovernanceValidationResult, ToolGovernanceMonitorResult } from './tool-governance-enforcer.js';
+export type { ValidationError, ValidationResult as NodeGraphValidationResult } from './node-graph-validator.js';

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

@@ -0,0 +1,7 @@
+/**
+ * RouteCodex V2 验证模块导出
+ * Phase 1a: 完整验证机制
+ */
+// 验证器
+export * from './tool-governance-enforcer.js';
+export * from './node-graph-validator.js';

package/dist/conversion/conversion-v3/validations/node-graph-validator.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 节点图验证器
+ * 验证 pipeline-config 中的节点图的完整性和正确性
+ */
+import type { PipelineNodeKind } from '../standards/pipeline-context.js';
+import type { NodeImplementation } from '../standards/pipeline-node.js';
+/**
+ * 流水线配置接口
+ */
+export interface PipelineConfig {
+    pipelineConfigVersion: string;
+    generatedAt: string;
+    pipelines: PipelineConfigEntry[];
+}
+export interface PipelineConfigEntry {
+    id: string;
+    name?: string;
+    entryEndpoints: string[];
+    providerProtocols: string[];
+    processMode: 'chat' | 'passthrough';
+    streaming: 'always' | 'never' | 'auto';
+    mode?: 'passthrough';
+    nodes: PipelineNodeConfig[];
+}
+export interface PipelineNodeConfig {
+    id: string;
+    kind: PipelineNodeKind;
+    implementation: string;
+    options?: Record<string, unknown>;
+}
+/**
+ * 验证错误接口
+ */
+export interface ValidationError {
+    code: string;
+    message: string;
+    severity: 'error' | 'warning';
+    pipelineId?: string;
+    nodeId?: string;
+    suggestion?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * 验证结果接口
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    summary: {
+        totalPipelines: number;
+        totalNodes: number;
+        errorsByType: Record<string, number>;
+        warningsByType: Record<string, number>;
+    };
+}
+/**
+ * 节点图验证器
+ */
+export declare class NodeGraphValidator {
+    private static readonly VALID_NODE_KINDS;
+    private static readonly REQUIRED_NODE_SEQUENCES;
+    private static readonly ENTRYPOINT_MAPPINGS;
+    /**
+     * 验证完整的流水线配置
+     */
+    static validatePipelineConfig(config: PipelineConfig, nodeRegistry?: Map<string, NodeImplementation>): Promise<ValidationResult>;
+    /**
+     * 验证配置结构
+     */
+    private static validateConfigStructure;
+    /**
+     * 验证单个流水线
+     */
+    private static validateSinglePipeline;
+    /**
+     * 验证流水线基础字段
+     */
+    private static validatePipelineBasics;
+    /**
+     * 验证单个节点
+     */
+    private static validateSingleNode;
+    /**
+     * 验证节点特定配置
+     */
+    private static validateNodeSpecificConfig;
+    /**
+     * 验证节点序列
+     */
+    private static validateNodeSequence;
+    /**
+     * 验证节点顺序
+     */
+    private static validateNodeOrder;
+    /**
+     * 验证端点一致性
+     */
+    private static validateEndpointConsistency;
+    /**
+     * 验证流水线间的引用一致性
+     */
+    private static validatePipelineReferences;
+    /**
+     * 转换工具治理违规为验证错误
+     */
+    private static convertGovernanceViolation;
+    /**
+     * 构建验证结果
+     */
+    private static buildValidationResult;
+    /**
+     * 生成验证报告
+     */
+    static generateValidationReport(result: ValidationResult): string;
+}

package/dist/conversion/conversion-v3/validations/node-graph-validator.js

@@ -0,0 +1,505 @@
+/**
+ * 节点图验证器
+ * 验证 pipeline-config 中的节点图的完整性和正确性
+ */
+import { ToolGovernanceEnforcer } from './tool-governance-enforcer.js';
+/**
+ * 节点图验证器
+ */
+export class NodeGraphValidator {
+    static VALID_NODE_KINDS = new Set([
+        'sse-input',
+        'input',
+        'process',
+        'workflow',
+        'compatibility',
+        'provider',
+        'output',
+        'sse-output'
+    ]);
+    static REQUIRED_NODE_SEQUENCES = {
+        'request': ['sse-input', 'input', 'process', 'output', 'sse-output'],
+        'response': ['input', 'process', 'output', 'sse-output']
+    };
+    static ENTRYPOINT_MAPPINGS = {
+        '/v1/chat/completions': ['openai-chat'],
+        '/v1/responses': ['responses'],
+        '/v1/messages': ['anthropic-messages'],
+        '/responses': ['responses']
+    };
+    /**
+     * 验证完整的流水线配置
+     */
+    static async validatePipelineConfig(config, nodeRegistry) {
+        const errors = [];
+        const warnings = [];
+        // 验证配置结构
+        this.validateConfigStructure(config, errors, warnings);
+        // 验证每个流水线
+        for (const pipeline of config.pipelines) {
+            await this.validateSinglePipeline(pipeline, nodeRegistry, errors, warnings);
+        }
+        // 验证流水线间的引用一致性
+        this.validatePipelineReferences(config, errors, warnings);
+        // 工具治理验证
+        const governanceResult = ToolGovernanceEnforcer.validateNodeGraph(config);
+        for (const violation of governanceResult.violations) {
+            errors.push(this.convertGovernanceViolation(violation, 'error'));
+        }
+        for (const violation of governanceResult.warnings) {
+            warnings.push(this.convertGovernanceViolation(violation, 'warning'));
+        }
+        return this.buildValidationResult(config, errors, warnings);
+    }
+    /**
+     * 验证配置结构
+     */
+    static validateConfigStructure(config, errors, warnings) {
+        // 检查版本
+        if (!config.pipelineConfigVersion) {
+            errors.push({
+                code: 'MISSING_VERSION',
+                message: 'Pipeline config version is required',
+                severity: 'error',
+                suggestion: 'Add pipelineConfigVersion field'
+            });
+        }
+        // 检查生成时间
+        if (!config.generatedAt) {
+            warnings.push({
+                code: 'MISSING_TIMESTAMP',
+                message: 'Generated timestamp is missing',
+                severity: 'warning',
+                suggestion: 'Add generatedAt field for better debugging'
+            });
+        }
+        // 检查流水线列表
+        if (!Array.isArray(config.pipelines) || config.pipelines.length === 0) {
+            errors.push({
+                code: 'EMPTY_PIPELINES',
+                message: 'Pipeline config must contain at least one pipeline',
+                severity: 'error',
+                suggestion: 'Add at least one pipeline configuration'
+            });
+        }
+    }
+    /**
+     * 验证单个流水线
+     */
+    static async validateSinglePipeline(pipeline, nodeRegistry, errors, warnings) {
+        const pipelineId = pipeline.id;
+        // 验证基础字段
+        this.validatePipelineBasics(pipeline, errors, warnings);
+        // 验证节点列表
+        if (!Array.isArray(pipeline.nodes) || pipeline.nodes.length === 0) {
+            errors.push({
+                code: 'EMPTY_NODES',
+                message: `Pipeline '${pipelineId}' must contain at least one node`,
+                severity: 'error',
+                pipelineId,
+                suggestion: 'Add nodes to the pipeline configuration'
+            });
+            return;
+        }
+        // 验证每个节点
+        for (const node of pipeline.nodes) {
+            await this.validateSingleNode(node, pipeline, nodeRegistry, errors, warnings);
+        }
+        // 验证节点序列
+        this.validateNodeSequence(pipeline, errors, warnings);
+        // 验证端点一致性
+        this.validateEndpointConsistency(pipeline, errors, warnings);
+    }
+    /**
+     * 验证流水线基础字段
+     */
+    static validatePipelineBasics(pipeline, errors, warnings) {
+        const { id } = pipeline;
+        // 检查ID
+        if (!id || typeof id !== 'string') {
+            errors.push({
+                code: 'INVALID_PIPELINE_ID',
+                message: 'Pipeline ID is required and must be a string',
+                severity: 'error',
+                suggestion: 'Add a valid pipeline ID'
+            });
+        }
+        // 检查入口端点
+        if (!Array.isArray(pipeline.entryEndpoints) || pipeline.entryEndpoints.length === 0) {
+            errors.push({
+                code: 'MISSING_ENTRY_ENDPOINTS',
+                message: `Pipeline '${id}' must have at least one entry endpoint`,
+                severity: 'error',
+                pipelineId: id,
+                suggestion: 'Add entryEndpoints array with valid endpoints'
+            });
+        }
+        // 检查Provider协议
+        if (!Array.isArray(pipeline.providerProtocols) || pipeline.providerProtocols.length === 0) {
+            errors.push({
+                code: 'MISSING_PROVIDER_PROTOCOLS',
+                message: `Pipeline '${id}' must specify provider protocols`,
+                severity: 'error',
+                pipelineId: id,
+                suggestion: 'Add providerProtocols array'
+            });
+        }
+        // 检查处理模式
+        if (!['chat', 'passthrough'].includes(pipeline.processMode)) {
+            errors.push({
+                code: 'INVALID_PROCESS_MODE',
+                message: `Invalid processMode '${pipeline.processMode}' in pipeline '${id}'`,
+                severity: 'error',
+                pipelineId: id,
+                suggestion: 'Use either "chat" or "passthrough"'
+            });
+        }
+        // 检查流式策略
+        if (!['always', 'never', 'auto'].includes(pipeline.streaming)) {
+            errors.push({
+                code: 'INVALID_STREAMING',
+                message: `Invalid streaming mode '${pipeline.streaming}' in pipeline '${id}'`,
+                severity: 'error',
+                pipelineId: id,
+                suggestion: 'Use either "always", "never", or "auto"'
+            });
+        }
+    }
+    /**
+     * 验证单个节点
+     */
+    static async validateSingleNode(node, pipeline, nodeRegistry, errors, warnings) {
+        const pipelineId = pipeline.id;
+        // 验证节点ID
+        if (!node.id || typeof node.id !== 'string') {
+            errors.push({
+                code: 'INVALID_NODE_ID',
+                message: 'Node ID is required and must be a string',
+                severity: 'error',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: 'Add a valid node ID'
+            });
+        }
+        // 验证节点类型
+        if (!this.VALID_NODE_KINDS.has(node.kind)) {
+            errors.push({
+                code: 'INVALID_NODE_KIND',
+                message: `Invalid node kind '${node.kind}' in node '${node.id}'`,
+                severity: 'error',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: `Use one of: ${Array.from(this.VALID_NODE_KINDS).join(', ')}`,
+                details: { validKinds: Array.from(this.VALID_NODE_KINDS) }
+            });
+        }
+        // 验证实现名称
+        if (!node.implementation || typeof node.implementation !== 'string') {
+            errors.push({
+                code: 'INVALID_IMPLEMENTATION',
+                message: `Node implementation is required for node '${node.id}'`,
+                severity: 'error',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: 'Add a valid implementation name'
+            });
+        }
+        // 验证节点注册表中是否存在
+        if (nodeRegistry && !nodeRegistry.has(node.implementation)) {
+            errors.push({
+                code: 'UNREGISTERED_IMPLEMENTATION',
+                message: `Node implementation '${node.implementation}' not found in registry`,
+                severity: 'error',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: `Register implementation '${node.implementation}' or check for typos`,
+                details: { availableImplementations: Array.from(nodeRegistry.keys()) }
+            });
+        }
+        // 验证选项
+        if (node.options && typeof node.options !== 'object') {
+            errors.push({
+                code: 'INVALID_OPTIONS',
+                message: `Node options must be an object for node '${node.id}'`,
+                severity: 'error',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: 'Ensure options is a valid JSON object'
+            });
+        }
+        // 验证节点特定配置
+        this.validateNodeSpecificConfig(node, pipeline, errors, warnings);
+    }
+    /**
+     * 验证节点特定配置
+     */
+    static validateNodeSpecificConfig(node, pipeline, errors, warnings) {
+        const pipelineId = pipeline.id;
+        // SSE 输入节点应该在开头
+        if (node.kind === 'sse-input' && node.id !== pipeline.nodes[0]?.id) {
+            warnings.push({
+                code: 'SSE_INPUT_POSITION',
+                message: `SSE input node '${node.id}' should be positioned first in the pipeline`,
+                severity: 'warning',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: 'Move SSE input node to the beginning of the node list'
+            });
+        }
+        // SSE 输出节点应该在结尾
+        if (node.kind === 'sse-output' && node.id !== pipeline.nodes[pipeline.nodes.length - 1]?.id) {
+            warnings.push({
+                code: 'SSE_OUTPUT_POSITION',
+                message: `SSE output node '${node.id}' should be positioned last in the pipeline`,
+                severity: 'warning',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: 'Move SSE output node to the end of the node list'
+            });
+        }
+        // Provider 节点的特殊验证
+        if (node.kind === 'provider' && !node.options?.providerId) {
+            warnings.push({
+                code: 'MISSING_PROVIDER_ID',
+                message: `Provider node '${node.id}' should specify providerId in options`,
+                severity: 'warning',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: 'Add providerId to node options for better identification'
+            });
+        }
+        // Compatibility 节点的特殊验证
+        if (node.kind === 'compatibility' && !node.options?.compatibility) {
+            errors.push({
+                code: 'MISSING_COMPATIBILITY_CONFIG',
+                message: `Compatibility node '${node.id}' must specify compatibility configuration`,
+                severity: 'error',
+                pipelineId,
+                nodeId: node.id,
+                suggestion: 'Add compatibility configuration with profile and direction'
+            });
+        }
+    }
+    /**
+     * 验证节点序列
+     */
+    static validateNodeSequence(pipeline, errors, warnings) {
+        const { id: pipelineId, nodes } = pipeline;
+        // 检查节点ID唯一性
+        const nodeIds = nodes.map(n => n.id);
+        const duplicateIds = nodeIds.filter((id, index) => nodeIds.indexOf(id) !== index);
+        if (duplicateIds.length > 0) {
+            errors.push({
+                code: 'DUPLICATE_NODE_IDS',
+                message: `Duplicate node IDs found: ${duplicateIds.join(', ')}`,
+                severity: 'error',
+                pipelineId,
+                suggestion: 'Ensure all node IDs are unique within the pipeline',
+                details: { duplicateIds }
+            });
+        }
+        // 检查必需的节点类型序列
+        const nodeKinds = nodes.map(n => n.kind);
+        const hasInput = nodeKinds.includes('input') || nodeKinds.includes('sse-input');
+        const hasOutput = nodeKinds.includes('output') || nodeKinds.includes('sse-output');
+        const hasProcess = nodeKinds.includes('process');
+        if (!hasInput) {
+            errors.push({
+                code: 'MISSING_INPUT_NODE',
+                message: `Pipeline '${pipelineId}' must have an input node`,
+                severity: 'error',
+                pipelineId,
+                suggestion: 'Add an input or sse-input node'
+            });
+        }
+        if (!hasOutput) {
+            errors.push({
+                code: 'MISSING_OUTPUT_NODE',
+                message: `Pipeline '${pipelineId}' must have an output node`,
+                severity: 'error',
+                pipelineId,
+                suggestion: 'Add an output or sse-output node'
+            });
+        }
+        if (!hasProcess && pipeline.processMode === 'chat') {
+            warnings.push({
+                code: 'MISSING_PROCESS_NODE',
+                message: `Chat mode pipeline '${pipelineId}' should have a process node`,
+                severity: 'warning',
+                pipelineId,
+                suggestion: 'Add a process node for proper chat processing'
+            });
+        }
+        // 验证节点类型顺序合理性
+        this.validateNodeOrder(nodes, pipelineId, errors, warnings);
+    }
+    /**
+     * 验证节点顺序
+     */
+    static validateNodeOrder(nodes, pipelineId, errors, warnings) {
+        const kindOrder = nodes.map(n => n.kind);
+        // Provider 节点应该在使用后端服务之前
+        const providerIndex = kindOrder.indexOf('provider');
+        const outputIndex = kindOrder.indexOf('output');
+        if (providerIndex > 0 && outputIndex > -1 && providerIndex > outputIndex) {
+            errors.push({
+                code: 'INVALID_PROVIDER_ORDER',
+                message: 'Provider node should come before output node',
+                severity: 'error',
+                pipelineId,
+                suggestion: 'Reorder nodes to place provider before output'
+            });
+        }
+        // Process 节点应该在 input 和 output 之间
+        const inputIndex = Math.max(kindOrder.indexOf('input'), kindOrder.indexOf('sse-input'));
+        const processIndex = kindOrder.indexOf('process');
+        if (processIndex > -1 && (processIndex <= inputIndex || processIndex >= outputIndex)) {
+            warnings.push({
+                code: 'PROCESS_NODE_POSITION',
+                message: 'Process node should be positioned between input and output nodes',
+                severity: 'warning',
+                pipelineId,
+                suggestion: 'Move process node to a more logical position in the sequence'
+            });
+        }
+    }
+    /**
+     * 验证端点一致性
+     */
+    static validateEndpointConsistency(pipeline, errors, warnings) {
+        const { id: pipelineId, entryEndpoints, providerProtocols, nodes } = pipeline;
+        // 检查端点与实现名称的一致性
+        for (const endpoint of entryEndpoints) {
+            const expectedImplementations = this.ENTRYPOINT_MAPPINGS[endpoint];
+            if (expectedImplementations) {
+                const hasMatchingImplementation = nodes.some(node => expectedImplementations.some(impl => node.implementation.includes(impl)));
+                if (!hasMatchingImplementation) {
+                    warnings.push({
+                        code: 'ENDPOINT_MISMATCH',
+                        message: `No matching implementation found for endpoint '${endpoint}'`,
+                        severity: 'warning',
+                        pipelineId,
+                        suggestion: `Add node with implementation containing: ${expectedImplementations.join(' or ')}`
+                    });
+                }
+            }
+        }
+        // 检查协议与流式配置的一致性
+        const hasResponsesProtocol = providerProtocols.includes('openai-responses');
+        const isStreamingAlways = pipeline.streaming === 'always';
+        if (hasResponsesProtocol && !isStreamingAlways) {
+            warnings.push({
+                code: 'RESPONSES_STREAMING',
+                message: 'Responses protocol typically works with streaming',
+                severity: 'warning',
+                pipelineId,
+                suggestion: 'Consider setting streaming to "always" for responses protocol'
+            });
+        }
+    }
+    /**
+     * 验证流水线间的引用一致性
+     */
+    static validatePipelineReferences(config, errors, warnings) {
+        // 检查流水线ID唯一性
+        const pipelineIds = config.pipelines.map(p => p.id);
+        const duplicateIds = pipelineIds.filter((id, index) => pipelineIds.indexOf(id) !== index);
+        if (duplicateIds.length > 0) {
+            errors.push({
+                code: 'DUPLICATE_PIPELINE_IDS',
+                message: `Duplicate pipeline IDs found: ${duplicateIds.join(', ')}`,
+                severity: 'error',
+                suggestion: 'Ensure all pipeline IDs are unique',
+                details: { duplicateIds }
+            });
+        }
+    }
+    /**
+     * 转换工具治理违规为验证错误
+     */
+    static convertGovernanceViolation(violation, severity) {
+        return {
+            code: `TOOL_GOVERNANCE_${violation.type.toUpperCase().replace(/-/g, '_')}`,
+            message: violation.description,
+            severity,
+            nodeId: violation.nodeId,
+            suggestion: violation.suggestion,
+            details: { violation }
+        };
+    }
+    /**
+     * 构建验证结果
+     */
+    static buildValidationResult(config, errors, warnings) {
+        const errorsByType = {};
+        const warningsByType = {};
+        // 统计错误和警告
+        errors.forEach(error => {
+            errorsByType[error.code] = (errorsByType[error.code] || 0) + 1;
+        });
+        warnings.forEach(warning => {
+            warningsByType[warning.code] = (warningsByType[warning.code] || 0) + 1;
+        });
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            summary: {
+                totalPipelines: config.pipelines.length,
+                totalNodes: config.pipelines.reduce((sum, p) => sum + (p.nodes?.length || 0), 0),
+                errorsByType,
+                warningsByType
+            }
+        };
+    }
+    /**
+     * 生成验证报告
+     */
+    static generateValidationReport(result) {
+        const lines = [];
+        lines.push('# Pipeline Configuration Validation Report');
+        lines.push('');
+        lines.push(`**Status**: ${result.valid ? '✅ PASSED' : '❌ FAILED'}`);
+        lines.push(`**Total Pipelines**: ${result.summary.totalPipelines}`);
+        lines.push(`**Total Nodes**: ${result.summary.totalNodes}`);
+        lines.push('');
+        if (result.errors.length > 0) {
+            lines.push('## Errors 🚨');
+            lines.push('');
+            for (const error of result.errors) {
+                lines.push(`- **${error.code}**: ${error.message}`);
+                if (error.pipelineId)
+                    lines.push(`  - Pipeline: ${error.pipelineId}`);
+                if (error.nodeId)
+                    lines.push(`  - Node: ${error.nodeId}`);
+                if (error.suggestion)
+                    lines.push(`  - Suggestion: ${error.suggestion}`);
+                lines.push('');
+            }
+        }
+        if (result.warnings.length > 0) {
+            lines.push('## Warnings ⚠️');
+            lines.push('');
+            for (const warning of result.warnings) {
+                lines.push(`- **${warning.code}**: ${warning.message}`);
+                if (warning.pipelineId)
+                    lines.push(`  - Pipeline: ${warning.pipelineId}`);
+                if (warning.nodeId)
+                    lines.push(`  - Node: ${warning.nodeId}`);
+                if (warning.suggestion)
+                    lines.push(`  - Suggestion: ${warning.suggestion}`);
+                lines.push('');
+            }
+        }
+        if (result.valid) {
+            lines.push('## Summary ✅');
+            lines.push('All validations passed successfully!');
+        }
+        else {
+            lines.push('## Summary ❌');
+            lines.push(`Found ${result.errors.length} errors and ${result.warnings.length} warnings.`);
+            lines.push('Please fix the errors before deploying the configuration.');
+        }
+        return lines.join('\n');
+    }
+}