@zooique/memora 0.1.0

package/dist/memory/userProfile.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 用户画像管理 — 实时归档 + SQLite 持久化
+ *
+ * 职责：
+ *   - 每轮对话结束后扫描是否产生新画像条目
+ *   - 5 个子分类：identity / preference / expertise / habit / history
+ *   - 实时归档（用户前脚说"我叫张三"→ 后脚就写入 SQLite）
+ *   - 启动时从 SQLite 全量加载（source = 'profile'）
+ *   - confidence 机制：高置信度（≥0.8）直接归档，低置信度首次召回时确认
+ *
+ * 设计原则（architecture_philosophy_rules.md §2 永久性分级）：
+ *   - 用户画像属于助手记忆，source = 'profile'，每轮必召回
+ *   - 实时归档解决"重启进程短期身份丢失"的核心 bug
+ *   - 确认机制防止正则误归档污染画像
+ *   - identity / preference / expertise 实时归档，habit / history 每天归档时提炼
+ */
+import type { IMemoryStorage } from '../memory/storageInterface.js';
+/** 用户画像子分类 */
+export type ProfileCategory = 'identity' | 'preference' | 'expertise' | 'habit' | 'history';
+/** 用户画像条目 */
+export interface UserProfileEntry {
+    /** 画像唯一 ID（格式：profile:user-profile-{category}-{slug}） */
+    id: string;
+    /** 子分类 */
+    category: ProfileCategory;
+    /** 事实值（如 "姓名: 张三"） */
+    value: string;
+    /** 来源（哪一轮对话提到） */
+    source: string;
+    /** 权重（0-1） */
+    weight: number;
+    /** 是否已确认（false 表示首次召回时需用户确认） */
+    confirmed: boolean;
+    /** 最后更新时间（ISO 8601） */
+    updatedAt: string;
+}
+/** extractUserFacts 的原始提取结果 */
+export interface ExtractedFact {
+    category: ProfileCategory;
+    value: string;
+    sourceTurn: string;
+    /** 置信度 0-1（≥0.8 直接归档，否则标记待确认） */
+    confidence: number;
+}
+/**
+ * 用户画像管理器
+ */
+export declare class UserProfile {
+    private readonly index;
+    /** 内存缓存：启动时从 SQLite 全量加载 */
+    private cache;
+    constructor(index: IMemoryStorage);
+    /**
+     * 启动时从 SQLite 加载所有已确认的画像条目
+     *
+     * 存储中只保存已确认的条目（confirmed = true），
+     * 待确认条目仅存内存缓存，不写入存储。
+     *
+     * P2-5 content 字段使用 JSON 编码存储 category + value 元数据，
+     * 兼容旧格式（name 字段 "${category}: ${value}"）作为降级路径。
+     */
+    load(): Promise<UserProfileEntry[]>;
+    /**
+     * 实时归档：将提取的用户事实写入存储
+     *
+     * 每轮 chat() 结束后，由 Agent 调用 extractUserFacts() 提取事实后传入。
+     * 高置信度（≥0.8）→ 直接归档为 confirmed
+     * 低置信度 → 标记 confirmed = false，首次召回时 Agent 向用户确认
+     *
+     * @param facts 由 extractUserFacts() 提取的事实列表
+     */
+    archiveFacts(facts: ExtractedFact[]): Promise<number>;
+    /**
+     * 获取所有已确认的画像条目（system prompt 注入用）
+     */
+    getConfirmed(): UserProfileEntry[];
+    /**
+     * 获取所有待确认的画像条目（供宿主 UI 展示确认/拒绝操作）
+     *
+     * 待确认条目仅存内存缓存（未写入存储），进程重启后丢失。
+     * 宿主应定期或在新对话后查询此方法，展示给用户确认。
+     */
+    getPending(): UserProfileEntry[];
+    /**
+     * 构建 system prompt 中的用户画像段
+     *
+     * 格式：
+     *   【用户画像】
+     *   - 身份：张三，男，25岁，住北京
+     *   - 偏好：TypeScript, Python, VS Code
+     *   - 专长：后端开发，系统架构
+     *   - 习惯：上午工作，下午思考
+     */
+    buildSystemPrompt(): string;
+    /**
+     * 确认待确认条目（用户在对话中确认了）
+     *
+     * 确认后写入存储（此前仅存内存缓存）
+     *
+     * @param id 条目 ID
+     */
+    confirm(id: string): Promise<void>;
+    /**
+     * 拒绝待确认条目（用户在对话中否认了）
+     *
+     * @param id 条目 ID
+     */
+    reject(id: string): Promise<void>;
+    /**
+     * 写入单条事实到 SQLite
+     *
+     * 冲突解决策略：
+     *   同分类（identity/preference/expertise/habit/history）的新事实
+     *   会替换旧事实。因为用户画像是"当前状态"而非"历史记录"。
+     *   例："我叫张三" → 后续说"我叫李四" → 只保留"李四"，张三被移除。
+     *
+     * @returns 成功写入的条目，或 null（写入失败）
+     */
+    private upsertFact;
+    /**
+     * 删除同分类的旧条目（用户更新了信息）
+     *
+     * 当用户说"我叫李四"替换之前的"我叫张三"时，移除旧的 identity 条目。
+     * 策略：同分类（category）下，新值替换旧值。判断标准是旧条目的 value 前缀。
+     *
+     * P2-5 从 content JSON 解码 category，替代 name 字段隐式解析。
+     * P2-3 构建 contentPrefix → entry 的 Map 索引，冲突检测从 O(n*m) 降为 O(m)。
+     *
+     * @param fact 当前提取到的新事实
+     */
+    private removeConflictingEntries;
+    /**
+     * 将 UserProfileEntry 转为 Memory（用于写入 SQLite）
+     *
+     * P2-5 content 字段使用 JSON 编码存储 category + value 元数据，
+     * name 字段为固定可读标签，category 通过 content 的 JSON 元数据显式编码。
+     * 确认状态：仅已确认条目调用此方法（待确认条目不写入存储）
+     */
+    private toMemory;
+    /**
+     * 从 content 字段解析 category 和 value
+     *
+     * P2-5 优先从 content JSON 解码元数据，降级到旧格式 name 字段解析，
+     * 确保已有 SQLite 数据（旧格式 name="${category}: ${value}"）兼容加载。
+     *
+     * @param content Memory 的 content 字段（新格式为 JSON，旧格式为纯 value）
+     * @param name Memory 的 name 字段（旧格式为 "${category}: ${value}"）
+     * @returns 解析出的 category 和 value
+     */
+    private parseContentField;
+    /**
+     * 分类标签
+     */
+    private categoryLabel;
+}
+//# sourceMappingURL=userProfile.d.ts.map

package/dist/memory/userProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userProfile.d.ts","sourceRoot":"","sources":["../../src/memory/userProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnE,cAAc;AACd,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5F,aAAa;AACb,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,UAAU;IACV,QAAQ,EAAE,eAAe,CAAC;IAC1B,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC,4BAA4B;IAC5B,OAAO,CAAC,KAAK,CAA4C;gBAE5B,KAAK,EAAE,cAAc;IAElD;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgCzC;;;;;;;;OAQG;IACG,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAW3D;;OAEG;IACH,YAAY,IAAI,gBAAgB,EAAE;IAIlC;;;;;OAKG;IACH,UAAU,IAAI,gBAAgB,EAAE;IAIhC;;;;;;;;;OASG;IACH,iBAAiB,IAAI,MAAM;IA0B3B;;;;;;OAMG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAavC;;;;;;;;;OASG;YACW,UAAU;IA2CxB;;;;;;;;;;OAUG;YACW,wBAAwB;IA4CtC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAahB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAgCzB;;OAEG;IACH,OAAO,CAAC,aAAa;CAUtB"}

package/dist/memory/userProfile.js

@@ -0,0 +1,315 @@
+import { SOURCE_LABELS } from '../memory/types.js';
+import { logger } from '../logging/logger.js';
+import { slugify } from '../utils/strings.js';
+import { toError } from '../utils/errors.js';
+/**
+ * 用户画像管理器
+ */
+export class UserProfile {
+    index;
+    /** 内存缓存：启动时从 SQLite 全量加载 */
+    cache = new Map();
+    constructor(index) {
+        this.index = index;
+    }
+    /**
+     * 启动时从 SQLite 加载所有已确认的画像条目
+     *
+     * 存储中只保存已确认的条目（confirmed = true），
+     * 待确认条目仅存内存缓存，不写入存储。
+     *
+     * P2-5 content 字段使用 JSON 编码存储 category + value 元数据，
+     * 兼容旧格式（name 字段 "${category}: ${value}"）作为降级路径。
+     */
+    async load() {
+        const memories = this.index.getBySource(SOURCE_LABELS.PROFILE);
+        const entries = [];
+        for (const m of memories) {
+            // P2-5 优先从 content JSON 解码，降级到旧格式 name 解析
+            const parsed = this.parseContentField(m.content, m.name);
+            const entry = {
+                id: m.id,
+                category: parsed.category,
+                value: parsed.value,
+                source: '',
+                weight: m.score,
+                confirmed: true, // 存储中只保存已确认条目
+                updatedAt: m.accessedAt,
+            };
+            this.cache.set(entry.id, entry);
+            entries.push(entry);
+        }
+        logger.info({
+            total: entries.length,
+            confirmed: entries.filter((e) => e.confirmed).length,
+            pending: entries.filter((e) => !e.confirmed).length,
+        }, '用户画像加载完成');
+        return entries;
+    }
+    /**
+     * 实时归档：将提取的用户事实写入存储
+     *
+     * 每轮 chat() 结束后，由 Agent 调用 extractUserFacts() 提取事实后传入。
+     * 高置信度（≥0.8）→ 直接归档为 confirmed
+     * 低置信度 → 标记 confirmed = false，首次召回时 Agent 向用户确认
+     *
+     * @param facts 由 extractUserFacts() 提取的事实列表
+     */
+    async archiveFacts(facts) {
+        if (facts.length === 0)
+            return 0;
+        let archived = 0;
+        for (const fact of facts) {
+            const entry = await this.upsertFact(fact);
+            if (entry)
+                archived++;
+        }
+        return archived;
+    }
+    /**
+     * 获取所有已确认的画像条目（system prompt 注入用）
+     */
+    getConfirmed() {
+        return Array.from(this.cache.values()).filter((e) => e.confirmed);
+    }
+    /**
+     * 获取所有待确认的画像条目（供宿主 UI 展示确认/拒绝操作）
+     *
+     * 待确认条目仅存内存缓存（未写入存储），进程重启后丢失。
+     * 宿主应定期或在新对话后查询此方法，展示给用户确认。
+     */
+    getPending() {
+        return Array.from(this.cache.values()).filter((e) => !e.confirmed);
+    }
+    /**
+     * 构建 system prompt 中的用户画像段
+     *
+     * 格式：
+     *   【用户画像】
+     *   - 身份：张三，男，25岁，住北京
+     *   - 偏好：TypeScript, Python, VS Code
+     *   - 专长：后端开发，系统架构
+     *   - 习惯：上午工作，下午思考
+     */
+    buildSystemPrompt() {
+        const confirmed = this.getConfirmed();
+        if (confirmed.length === 0)
+            return '';
+        // 按分类聚合
+        const grouped = new Map();
+        for (const e of confirmed) {
+            const list = grouped.get(e.category) ?? [];
+            list.push(e.value
+                // "姓名: 张三" → "张三"
+                .replace(/^[^:]+:\s*/, ''));
+            grouped.set(e.category, list);
+        }
+        const lines = ['【用户画像】'];
+        for (const [cat, vals] of grouped) {
+            const label = this.categoryLabel(cat);
+            lines.push(`- ${label}：${vals.join('，')}`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * 确认待确认条目（用户在对话中确认了）
+     *
+     * 确认后写入存储（此前仅存内存缓存）
+     *
+     * @param id 条目 ID
+     */
+    async confirm(id) {
+        const entry = this.cache.get(id);
+        if (!entry)
+            return;
+        entry.confirmed = true;
+        // 确认后写入存储（此前仅存内存缓存）
+        const memory = this.toMemory(entry);
+        this.index.upsert(memory);
+        logger.info({ id, category: entry.category, value: entry.value }, '用户画像条目已确认');
+    }
+    /**
+     * 拒绝待确认条目（用户在对话中否认了）
+     *
+     * @param id 条目 ID
+     */
+    async reject(id) {
+        this.cache.delete(id);
+        try {
+            this.index.delete(id);
+        }
+        catch (err) {
+            // 索引中可能不存在（低置信度条目可能未写入）：记录 debug 日志便于排查
+            logger.debug({ id, err: toError(err).message }, '索引删除失败（条目可能未写入索引）');
+        }
+        logger.info({ id }, '用户画像条目已删除（用户否认）');
+    }
+    // ── 私有方法 ──────────────────────────────────────
+    /**
+     * 写入单条事实到 SQLite
+     *
+     * 冲突解决策略：
+     *   同分类（identity/preference/expertise/habit/history）的新事实
+     *   会替换旧事实。因为用户画像是"当前状态"而非"历史记录"。
+     *   例："我叫张三" → 后续说"我叫李四" → 只保留"李四"，张三被移除。
+     *
+     * @returns 成功写入的条目，或 null（写入失败）
+     */
+    async upsertFact(fact) {
+        // 构造稳定 ID（profile: 前缀 + 分类 + slug）
+        const id = `profile:user-profile-${fact.category}-${slugify(fact.value)}`;
+        // 同分类冲突解决 — 删除旧条目（相同子分类 + 不同值 = 用户更新了信息）
+        await this.removeConflictingEntries(fact);
+        const entry = {
+            id,
+            category: fact.category,
+            value: fact.value,
+            source: fact.sourceTurn,
+            weight: 1.0,
+            confirmed: fact.confidence >= 0.8, // 高置信度直接确认
+            updatedAt: new Date().toISOString(),
+        };
+        try {
+            // 仅已确认条目写入存储（待确认条目仅存内存缓存）
+            if (entry.confirmed) {
+                const memory = this.toMemory(entry);
+                this.index.upsert(memory);
+            }
+            this.cache.set(id, entry);
+            if (entry.confirmed) {
+                logger.info({ id, category: fact.category, value: fact.value, confidence: fact.confidence }, '用户画像实时归档（已确认）');
+            }
+            else {
+                logger.info({ id, category: fact.category, value: fact.value, confidence: fact.confidence }, '用户画像待确认');
+            }
+            return entry;
+        }
+        catch (err) {
+            logger.warn({ err, id, category: fact.category }, '用户画像归档失败');
+            return null;
+        }
+    }
+    /**
+     * 删除同分类的旧条目（用户更新了信息）
+     *
+     * 当用户说"我叫李四"替换之前的"我叫张三"时，移除旧的 identity 条目。
+     * 策略：同分类（category）下，新值替换旧值。判断标准是旧条目的 value 前缀。
+     *
+     * P2-5 从 content JSON 解码 category，替代 name 字段隐式解析。
+     * P2-3 构建 contentPrefix → entry 的 Map 索引，冲突检测从 O(n*m) 降为 O(m)。
+     *
+     * @param fact 当前提取到的新事实
+     */
+    async removeConflictingEntries(fact) {
+        try {
+            const existing = this.index.getBySource(SOURCE_LABELS.PROFILE);
+            // 提取新事实的核心模式（如 "姓名: 李四" → 前缀 "姓名"）
+            const newPrefix = (fact.value.split(':')[0] ?? '').trim();
+            // P2-3 构建 contentPrefix → Memory 的 Map 索引，冲突检测降为 O(m)
+            const prefixIndex = new Map();
+            for (const m of existing) {
+                // P2-5 从 content JSON 解码 category，替代 parseNameField
+                const parsed = this.parseContentField(m.content, m.name);
+                if (parsed.category !== fact.category)
+                    continue;
+                const oldPrefix = (parsed.value.split(':')[0] ?? '').trim();
+                if (!oldPrefix)
+                    continue;
+                const key = `${parsed.category}:${oldPrefix}`;
+                const list = prefixIndex.get(key);
+                if (list) {
+                    list.push(m);
+                }
+                else {
+                    prefixIndex.set(key, [m]);
+                }
+            }
+            // 在索引中查找冲突条目
+            const conflictKey = `${fact.category}:${newPrefix}`;
+            const conflicts = prefixIndex.get(conflictKey);
+            if (conflicts) {
+                for (const m of conflicts) {
+                    const parsed = this.parseContentField(m.content, m.name);
+                    if (parsed.value !== fact.value) {
+                        this.index.delete(m.id);
+                        logger.info({ oldId: m.id, oldValue: parsed.value, newValue: fact.value }, '用户画像冲突已解决');
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // 冲突解决失败不阻塞写入
+            logger.debug({ err: toError(err).message }, '用户画像冲突解决失败');
+        }
+    }
+    /**
+     * 将 UserProfileEntry 转为 Memory（用于写入 SQLite）
+     *
+     * P2-5 content 字段使用 JSON 编码存储 category + value 元数据，
+     * name 字段为固定可读标签，category 通过 content 的 JSON 元数据显式编码。
+     * 确认状态：仅已确认条目调用此方法（待确认条目不写入存储）
+     */
+    toMemory(entry) {
+        const now = new Date().toISOString();
+        return {
+            id: entry.id,
+            content: JSON.stringify({ category: entry.category, value: entry.value }),
+            source: SOURCE_LABELS.PROFILE,
+            name: `用户画像-${entry.category}`,
+            createdAt: now,
+            accessedAt: entry.updatedAt || now,
+            score: entry.weight,
+        };
+    }
+    /**
+     * 从 content 字段解析 category 和 value
+     *
+     * P2-5 优先从 content JSON 解码元数据，降级到旧格式 name 字段解析，
+     * 确保已有 SQLite 数据（旧格式 name="${category}: ${value}"）兼容加载。
+     *
+     * @param content Memory 的 content 字段（新格式为 JSON，旧格式为纯 value）
+     * @param name Memory 的 name 字段（旧格式为 "${category}: ${value}"）
+     * @returns 解析出的 category 和 value
+     */
+    parseContentField(content, name) {
+        // 优先尝试 JSON 解码（新格式）
+        try {
+            const parsed = JSON.parse(content);
+            if (parsed.category && parsed.value) {
+                const validCategories = ['identity', 'preference', 'expertise', 'habit', 'history'];
+                if (validCategories.includes(parsed.category)) {
+                    return { category: parsed.category, value: parsed.value };
+                }
+            }
+        }
+        catch {
+            // content 不是 JSON，降级到旧格式
+        }
+        // 降级：从 name 字段解析（旧格式 "${category}: ${value}"）
+        const idx = name.indexOf(':');
+        if (idx >= 0) {
+            const category = name.slice(0, idx).trim();
+            const validCategories = ['identity', 'preference', 'expertise', 'habit', 'history'];
+            if (validCategories.includes(category)) {
+                const value = name.slice(idx + 1).trim();
+                return { category, value: value || content };
+            }
+        }
+        // 最终降级：默认 identity 分类
+        return { category: 'identity', value: content };
+    }
+    /**
+     * 分类标签
+     */
+    categoryLabel(cat) {
+        const labels = {
+            identity: '身份',
+            preference: '偏好',
+            expertise: '专长',
+            habit: '习惯',
+            history: '历史',
+        };
+        return labels[cat];
+    }
+}
+//# sourceMappingURL=userProfile.js.map

package/dist/memory/userProfile.js.map

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

package/dist/memory/vectorStore.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 嵌入服务接口
+ * 向量存储依赖此接口生成文本嵌入向量
+ *
+ * batchEmbed 返回向量数组，顺序与输入一致。
+ * EmbeddingProvider（llm/embedding.ts）满足此接口（结构子类型）。
+ */
+export interface EmbeddingService {
+    embed(text: string): Promise<number[]>;
+    batchEmbed(texts: string[]): Promise<Array<{
+        text: string;
+        vector: number[];
+    }>>;
+}
+/**
+ * 向量存储
+ *
+ * 纯 JS 实现，内存中维护向量索引，定期持久化到 JSON 文件
+ * 适用于单用户本地场景（5k 条记录以内）
+ *
+ * 依赖 EmbeddingService 接口（依赖倒置，与 llm/ 层解耦）
+ */
+export declare class VectorStore {
+    private readonly storePath;
+    private readonly embeddingProvider;
+    /** 内存中的向量索引 */
+    private entries;
+    /** 向量维度（由第一个插入的向量决定） */
+    private dimension;
+    /** 是否有未持久化的变更 */
+    private dirty;
+    constructor(storePath: string, embeddingProvider: EmbeddingService);
+    /**
+     * 从 JSON 文件加载向量索引（冷启动）
+     */
+    load(): Promise<void>;
+    /**
+     * 持久化向量索引到 JSON 文件
+     */
+    save(): Promise<void>;
+    /**
+     * 为文本生成向量并存储
+     * @param id 记忆 ID
+     * @param text 待嵌入的文本
+     */
+    upsert(id: string, text: string): Promise<void>;
+    /**
+     * 批量嵌入并存储
+     * @param items ID + 文本对
+     */
+    batchUpsert(items: Array<{
+        id: string;
+        text: string;
+    }>): Promise<void>;
+    /**
+     * 删除向量
+     */
+    delete(id: string): void;
+    /**
+     * 语义搜索：基于查询文本的向量，返回 topK 最相似的 ID
+     * @param query 查询文本
+     * @param topK 返回数量上限
+     * @param minSimilarity 最低相似度阈值（0~1）
+     * @returns ID + 相似度 对的数组，按相似度降序排列
+     */
+    search(query: string, topK?: number, minSimilarity?: number): Promise<Array<{
+        id: string;
+        similarity: number;
+    }>>;
+    /**
+     * 获取存储的向量数量
+     */
+    get size(): number;
+}
+//# sourceMappingURL=vectorStore.d.ts.map

package/dist/memory/vectorStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectorStore.d.ts","sourceRoot":"","sources":["../../src/memory/vectorStore.ts"],"names":[],"mappings":"AAqBA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC9B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC,CAAC;CAClF;AAsBD;;;;;;;GAOG;AACH,qBAAa,WAAW;IAWpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAXpC,eAAe;IACf,OAAO,CAAC,OAAO,CAA+B;IAE9C,wBAAwB;IACxB,OAAO,CAAC,SAAS,CAAK;IAEtB,iBAAiB;IACjB,OAAO,CAAC,KAAK,CAAS;gBAGH,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,gBAAgB;IAGtD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAe3B;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASrD;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5E;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxB;;;;;;OAMG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,IAAI,SAAI,EACR,aAAa,SAAM,GAClB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAgBrD;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}