@changw98ic/cli 1.0.0

package/dist/utils/entity-linker.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 实体链接器 - 实体消歧辅助模块
+ *
+ * 迁移自 Python entity_linker.py
+ * 为 Data Agent 提供实体消歧的辅助功能：
+ * - 置信度判断
+ * - 别名索引管理
+ * - 消歧结果记录
+ */
+import { IndexManager } from '@changw98ic/data';
+import type { EntityType } from '@changw98ic/core';
+/** 消歧结果 */
+export interface DisambiguationResult {
+    mention: string;
+    entityId: string | null;
+    confidence: number;
+    candidates: string[];
+    adopted: boolean;
+    warning?: string;
+}
+/** 不确定项 */
+export interface UncertainItem {
+    mention: string;
+    candidates: string[];
+    suggested?: string;
+    confidence: number;
+    context?: string;
+}
+/** 新实体 */
+export interface NewEntity {
+    id?: string;
+    suggested_id?: string;
+    name: string;
+    type: EntityType;
+    aliases?: string[];
+}
+export declare class EntityLinker {
+    private indexManager;
+    constructor(indexManager: IndexManager);
+    /**
+     * 注册新别名
+     */
+    registerAlias(entityId: string, alias: string, entityType: EntityType): boolean;
+    /**
+     * 查找别名对应的实体ID
+     */
+    lookupAlias(mention: string, entityType?: EntityType): string | null;
+    /**
+     * 查找别名对应的所有实体
+     */
+    lookupAliasAll(mention: string): Array<{
+        id: string;
+        type: string;
+    }>;
+    /**
+     * 获取实体的所有别名
+     */
+    getAllAliases(entityId: string, entityType?: EntityType): string[];
+    /**
+     * 处理 AI 提取结果中的 uncertain 项
+     */
+    processUncertainItems(uncertainItems: UncertainItem[]): {
+        results: DisambiguationResult[];
+        warnings: string[];
+    };
+    private processUncertain;
+    private isSuggestionReasonable;
+    private levenshteinDistance;
+    /**
+     * 注册新实体的别名
+     */
+    registerNewEntities(newEntities: NewEntity[]): string[];
+}
+//# sourceMappingURL=entity-linker.d.ts.map

package/dist/utils/entity-linker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-linker.d.ts","sourceRoot":"","sources":["../../src/utils/entity-linker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,WAAW;AACX,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,WAAW;AACX,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU;AACV,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD,qBAAa,YAAY;IACvB,OAAO,CAAC,YAAY,CAAe;gBAEvB,YAAY,EAAE,YAAY;IAMtC;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO;IAa/E;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;IAcpE;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAUpE;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,MAAM,EAAE;IAclE;;OAEG;IACH,qBAAqB,CACnB,cAAc,EAAE,aAAa,EAAE,GAC9B;QAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE;IAuB1D,OAAO,CAAC,gBAAgB;IA8ExB,OAAO,CAAC,sBAAsB;IA0B9B,OAAO,CAAC,mBAAmB;IA8B3B;;OAEG;IACH,mBAAmB,CAAC,WAAW,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE;CAyBxD"}

package/dist/utils/entity-linker.js

@@ -0,0 +1,208 @@
+// ============================================================================
+// Entity Linker
+// ============================================================================
+export class EntityLinker {
+    indexManager;
+    constructor(indexManager) {
+        this.indexManager = indexManager;
+    }
+    // ==================== 别名管理 ====================
+    /**
+     * 注册新别名
+     */
+    registerAlias(entityId, alias, entityType) {
+        if (!alias || !entityId) {
+            return false;
+        }
+        try {
+            this.indexManager.registerAlias(alias, entityId, entityType);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 查找别名对应的实体ID
+     */
+    lookupAlias(mention, entityType) {
+        const entity = this.indexManager.getEntityByAlias(mention);
+        if (!entity) {
+            return null;
+        }
+        if (entityType && entity.type !== entityType) {
+            return null;
+        }
+        return entity.id;
+    }
+    /**
+     * 查找别名对应的所有实体
+     */
+    lookupAliasAll(mention) {
+        // IndexManager doesn't have a method to get all entities by alias,
+        // so we use getEntityByAlias which returns the first match
+        const entity = this.indexManager.getEntityByAlias(mention);
+        if (!entity) {
+            return [];
+        }
+        return [{ id: entity.id, type: entity.type }];
+    }
+    /**
+     * 获取实体的所有别名
+     */
+    getAllAliases(entityId, entityType) {
+        const aliases = this.indexManager.getAliasesForEntity(entityId);
+        if (entityType) {
+            // Filter by type if needed - but IndexManager doesn't support this directly
+            // For now, return all aliases
+            return aliases.map(a => a.alias);
+        }
+        return aliases.map(a => a.alias);
+    }
+    // ==================== 消歧处理 ====================
+    /**
+     * 处理 AI 提取结果中的 uncertain 项
+     */
+    processUncertainItems(uncertainItems) {
+        const results = [];
+        const warnings = [];
+        for (const item of uncertainItems) {
+            const result = this.processUncertain(item.mention, item.candidates, item.suggested, item.confidence, item.context);
+            results.push(result);
+            if (result.warning) {
+                warnings.push(`${result.mention} → ${result.entityId}: ${result.warning}`);
+            }
+        }
+        return { results, warnings };
+    }
+    processUncertain(mention, candidates, suggested, _confidence = 0, _context) {
+        // 1. 首先检查别名表
+        const aliasMatch = this.lookupAlias(mention);
+        if (aliasMatch) {
+            return {
+                mention,
+                entityId: aliasMatch,
+                confidence: 1.0,
+                candidates: [aliasMatch],
+                adopted: true,
+            };
+        }
+        // 2. 检查建议的实体
+        if (suggested && suggested !== 'NEW') {
+            const entity = this.indexManager.getEntityById(suggested);
+            if (entity) {
+                // 检查建议是否合理
+                const isReasonable = this.isSuggestionReasonable(mention, entity.canonical_name);
+                return {
+                    mention,
+                    entityId: suggested,
+                    confidence: isReasonable ? 0.8 : 0.5,
+                    candidates: [suggested],
+                    adopted: isReasonable,
+                    warning: isReasonable ? undefined : `建议的实体 "${entity.canonical_name}" 与提及 "${mention}" 相似度较低`,
+                };
+            }
+        }
+        // 3. 在候选中查找
+        const matchedCandidates = [];
+        for (const candidate of candidates) {
+            const entity = this.indexManager.getEntityById(candidate);
+            if (entity) {
+                matchedCandidates.push(candidate);
+            }
+        }
+        if (matchedCandidates.length === 1) {
+            return {
+                mention,
+                entityId: matchedCandidates[0],
+                confidence: 0.7,
+                candidates: matchedCandidates,
+                adopted: true,
+            };
+        }
+        if (matchedCandidates.length > 1) {
+            return {
+                mention,
+                entityId: null,
+                confidence: 0.3,
+                candidates: matchedCandidates,
+                adopted: false,
+                warning: `多个候选实体: ${matchedCandidates.join(', ')}`,
+            };
+        }
+        // 4. 无匹配，可能是新实体
+        return {
+            mention,
+            entityId: null,
+            confidence: 0,
+            candidates: [],
+            adopted: false,
+            warning: '未找到匹配的实体，可能是新实体',
+        };
+    }
+    isSuggestionReasonable(mention, canonicalName) {
+        // 简单的相似度检查
+        const mentionLower = mention.toLowerCase();
+        const nameLower = canonicalName.toLowerCase();
+        // 完全匹配
+        if (mentionLower === nameLower) {
+            return true;
+        }
+        // 包含关系
+        if (mentionLower.includes(nameLower) || nameLower.includes(mentionLower)) {
+            return true;
+        }
+        // 首字符相同（中文名）
+        if (mention[0] === canonicalName[0]) {
+            return true;
+        }
+        // 编辑距离检查（简化版）
+        const distance = this.levenshteinDistance(mentionLower, nameLower);
+        const maxLen = Math.max(mention.length, canonicalName.length);
+        return distance / maxLen < 0.5; // 相似度 > 50%
+    }
+    levenshteinDistance(a, b) {
+        const matrix = [];
+        for (let i = 0; i <= b.length; i++) {
+            matrix[i] = [i];
+        }
+        for (let j = 0; j <= a.length; j++) {
+            matrix[0][j] = j;
+        }
+        for (let i = 1; i <= b.length; i++) {
+            for (let j = 1; j <= a.length; j++) {
+                if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                    matrix[i][j] = matrix[i - 1][j - 1];
+                }
+                else {
+                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+                }
+            }
+        }
+        return matrix[b.length][a.length];
+    }
+    // ==================== 新实体注册 ====================
+    /**
+     * 注册新实体的别名
+     */
+    registerNewEntities(newEntities) {
+        const registered = [];
+        for (const entity of newEntities) {
+            const entityId = entity.suggested_id ?? entity.id;
+            if (!entityId || entityId === 'NEW') {
+                continue;
+            }
+            // 注册主名称作为别名
+            this.registerAlias(entityId, entity.name, entity.type);
+            // 注册额外别名
+            if (entity.aliases) {
+                for (const alias of entity.aliases) {
+                    this.registerAlias(entityId, alias, entity.type);
+                }
+            }
+            registered.push(entityId);
+        }
+        return registered;
+    }
+}
+//# sourceMappingURL=entity-linker.js.map

package/dist/utils/entity-linker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-linker.js","sourceRoot":"","sources":["../../src/utils/entity-linker.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Utils Index - 统一导出
+ */
+export * from './output.js';
+export * from './path-compat.js';
+export * from './project-locator.js';
+export * from './runtime-compat.js';
+export * from './security.js';
+export * from './api-client.js';
+export * from './api-client.types.js';
+export * from './style-sampler.js';
+export * from './entity-linker.js';
+export * from './workflow-manager.js';
+export * from './backup-manager.js';
+export * from './chapter-context.js';
+export * from './status-reporter.js';
+export * from './archive-manager.js';
+export * from './observability.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,oBAAoB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,22 @@
+/**
+ * Utils Index - 统一导出
+ */
+export * from './output.js';
+export * from './path-compat.js';
+export * from './project-locator.js';
+// P1: Core utilities
+export * from './runtime-compat.js';
+export * from './security.js';
+export * from './api-client.js';
+export * from './api-client.types.js';
+export * from './style-sampler.js';
+export * from './entity-linker.js';
+// P2: Workflow utilities
+export * from './workflow-manager.js';
+export * from './backup-manager.js';
+export * from './chapter-context.js';
+export * from './status-reporter.js';
+export * from './archive-manager.js';
+// P3: Observability utilities
+export * from './observability.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AAErC,qBAAqB;AACrB,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AAEnC,yBAAyB;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AAErC,8BAA8B;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/utils/observability.d.ts

@@ -0,0 +1,145 @@
+export interface ToolCallLog {
+    timestamp: string;
+    toolName: string;
+    success: boolean;
+    retryCount: number;
+    errorCode?: string;
+    errorMessage?: string;
+    chapter?: number;
+}
+export interface PerfTimingLog {
+    timestamp: string;
+    toolName: string;
+    success: boolean;
+    elapsedMs: number;
+    chapter?: number;
+    errorCode?: string;
+    errorMessage?: string;
+    meta?: Record<string, unknown>;
+}
+export interface ToolLogger {
+    logToolCall(toolName: string, success: boolean, options?: {
+        retryCount?: number;
+        errorCode?: string;
+        errorMessage?: string;
+        chapter?: number;
+    }): void;
+}
+/**
+ * 文件工具日志记录器
+ *
+ * 将工具调用日志写入 JSONL 文件， 用于后续分析
+ */
+export declare class FileToolLogger implements ToolLogger {
+    private logPath;
+    constructor(projectRoot: string);
+    logToolCall(toolName: string, success: boolean, options?: {
+        retryCount?: number;
+        errorCode?: string;
+        errorMessage?: string;
+        chapter?: number;
+    }): void;
+}
+/**
+ * 可观测性管理器
+ *
+ * 提供统一的工具调用日志和 性能计时功能
+ */
+export declare class ObservabilityManager {
+    private projectRoot;
+    private toolLogger;
+    private timingLogPath;
+    constructor(projectRoot: string, toolLogger?: ToolLogger);
+    /**
+     * 安全记录工具调用
+     */
+    safeLogToolCall(toolName: string, success: boolean, options?: {
+        retryCount?: number;
+        errorCode?: string;
+        errorMessage?: string;
+        chapter?: number;
+    }): void;
+    /**
+     * 记录性能计时
+     */
+    appendPerfTiming(params: {
+        toolName: string;
+        success: boolean;
+        elapsedMs: number;
+        chapter?: number;
+        errorCode?: string;
+        errorMessage?: string;
+        meta?: Record<string, unknown>;
+    }): void;
+    /**
+     * 测量异步操作执行时间
+     */
+    measureAsync<T>(toolName: string, fn: () => Promise<T>, options?: {
+        chapter?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<T>;
+    /**
+     * 测量同步操作执行时间
+     */
+    measureSync<T>(toolName: string, fn: () => T, options?: {
+        chapter?: number;
+        meta?: Record<string, unknown>;
+    }): T;
+    /**
+     * 获取性能统计
+     */
+    getPerfStats(options?: {
+        toolName?: string;
+        since?: Date;
+        limit?: number;
+    }): PerfTimingLog[];
+    /**
+     * 获取工具调用统计
+     */
+    getToolCallStats(options?: {
+        toolName?: string;
+        since?: Date;
+        limit?: number;
+    }): ToolCallLog[];
+    /**
+     * 生成可观测性摘要报告
+     */
+    generateSummary(): {
+        totalToolCalls: number;
+        successfulCalls: number;
+        failedCalls: number;
+        avgElapsedMs: number | null;
+        slowestTools: Array<{
+            toolName: string;
+            avgMs: number;
+            count: number;
+        }>;
+        recentErrors: Array<{
+            toolName: string;
+            errorMessage: string;
+            timestamp: string;
+        }>;
+    };
+}
+/**
+ * 安全记录工具调用（独立函数）
+ */
+export declare function safeLogToolCall(projectRoot: string, toolName: string, success: boolean, options?: {
+    retryCount?: number;
+    errorCode?: string;
+    errorMessage?: string;
+    chapter?: number;
+}): void;
+/**
+ * 安全追加性能计时（独立函数）
+ */
+export declare function safeAppendPerfTiming(projectRoot: string, params: {
+    toolName: string;
+    success: boolean;
+    elapsedMs: number;
+    chapter?: number;
+    errorCode?: string;
+    errorMessage?: string;
+    meta?: Record<string, unknown>;
+}): void;
+//# sourceMappingURL=observability.d.ts.map

package/dist/utils/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/utils/observability.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,IAAI,CAAC;CACT;AAMD;;;;GAIG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,OAAO,CAAS;gBAEZ,WAAW,EAAE,MAAM;IAQ/B,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,IAAI;CAiBR;AAMD;;;;GAIG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,aAAa,CAAS;gBAElB,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU;IAaxD;;OAEG;IACH,eAAe,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,IAAI;IAWP;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,GAAG,IAAI;IAmBR;;OAEG;IACG,YAAY,CAAC,CAAC,EAClB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,GACA,OAAO,CAAC,CAAC,CAAC;IA4Bb;;OAEG;IACH,WAAW,CAAC,CAAC,EACX,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,GACA,CAAC;IA8BJ;;OAEG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,IAAI,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,aAAa,EAAE;IAmCnB;;OAEG;IACH,gBAAgB,CAAC,OAAO,CAAC,EAAE;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,IAAI,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,WAAW,EAAE;IAqCjB;;OAEG;IACH,eAAe,IAAI;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,YAAY,EAAE,KAAK,CAAC;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACxE,YAAY,EAAE,KAAK,CAAC;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACpF;CAiDF;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,IAAI,CAON;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE;IACN,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GACA,IAAI,CAGN"}