@yun520-1/heartflow 0.15.2

package/dist/agent/tools/BashTool.js

@@ -0,0 +1,355 @@
+/**
+ * BashTool — Shell 命令执行工具
+ * @version v0.13.60
+ *
+ * 在本地 shell 中执行命令，返回 stdout/stderr/exitCode。
+ *
+ * 安全特性：
+ *   - 命令白名单模式（只允许预定义的安全操作）
+ *   - 执行超时控制（默认 30s，可配置）
+ *   - 不支持交互式命令（防止阻塞）
+ *
+ * 使用示例：
+ *   const tool = new BashTool();
+ *   const result = await tool.execute({ command: 'ls -la ~/', timeout: 10 });
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_COMMANDS = exports.BASH_TOOL_METADATA = exports.BashTool = void 0;
+const Tool_1 = require("./Tool");
+const METADATA = {
+    name: 'bash',
+    description: '在本地 shell 中执行命令，返回 stdout/stderr/exitCode。',
+    category: 'shell',
+    params: [
+        {
+            name: 'command',
+            description: '要执行的 shell 命令',
+            type: 'string',
+            required: true,
+        },
+        {
+            name: 'timeout',
+            description: '超时秒数（默认 30）',
+            type: 'number',
+            required: false,
+            default: 30,
+        },
+        {
+            name: 'cwd',
+            description: '执行目录（默认进程当前目录）',
+            type: 'string',
+            required: false,
+        },
+        {
+            name: 'env',
+            description: '额外的环境变量（key: value 对象）',
+            type: 'object',
+            required: false,
+        },
+    ],
+    examples: [
+        {
+            input: { command: 'echo "Hello World"', timeout: 5 },
+            output: { success: true, output: { stdout: 'Hello World\n', stderr: '', exitCode: 0 } },
+        },
+    ],
+    version: '0.13.60',
+};
+exports.BASH_TOOL_METADATA = METADATA;
+const PATH_PATTERN = /^(\/[\w\.\-]+)+$/;
+const ALLOWED_COMMANDS = {
+    // 文件查看
+    ls: {
+        description: '列出目录内容',
+        params: {
+            '-a': { type: 'flag' },
+            '-l': { type: 'flag' },
+            '-R': { type: 'flag' },
+            '-t': { type: 'flag' },
+            '-h': { type: 'flag' },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+    },
+    cat: {
+        description: '查看文件内容',
+        params: {
+            '-n': { type: 'flag' },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+    },
+    head: {
+        description: '查看文件开头',
+        params: {
+            '-n': { type: 'number', max: 1000 },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+    },
+    tail: {
+        description: '查看文件结尾',
+        params: {
+            '-n': { type: 'number', max: 1000 },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+    },
+    wc: {
+        description: '统计行数/词数/字符数',
+        params: {
+            '-l': { type: 'flag' },
+            '-w': { type: 'flag' },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+    },
+    grep: {
+        description: '文本搜索',
+        params: {
+            '-r': { type: 'flag' },
+            '-i': { type: 'flag' },
+            '-n': { type: 'flag' },
+            '-l': { type: 'flag' },
+            pattern: { type: 'string', pattern: /^[^\"\';|&`$]+$/ },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+    },
+    find: {
+        description: '查找文件',
+        params: {
+            path: { type: 'string', pattern: PATH_PATTERN },
+            '-name': { type: 'string', pattern: /^[^\;\|\`]+$/ },
+            '-type': { type: 'literal', values: ['f', 'd', 'l'] },
+        },
+        validator: (args) => {
+            // find 禁止使用 -delete、-exec、| 等危险操作
+            return !args.some(a => ['-delete', '-exec', '-ok', '|', ';', '`'].includes(a));
+        },
+    },
+    // Git 命令
+    git: {
+        description: 'Git 版本控制',
+        params: {
+            'status': { type: 'literal' },
+            'log': { type: 'literal' },
+            'diff': { type: 'literal' },
+            '--oneline': { type: 'flag' },
+            '--graph': { type: 'flag' },
+            '-n': { type: 'number', max: 100 },
+        },
+        validator: (args) => {
+            // 禁止危险 git 操作
+            const dangerous = ['filter-branch', 'push', '--force', '-f', 'rebase'];
+            return !dangerous.some(d => args.includes(d));
+        },
+    },
+    // Node/npm
+    node: {
+        description: '执行 Node.js 脚本',
+        params: {
+            path: { type: 'string', pattern: /^\// }, // Only absolute paths, no -e/-p
+        },
+        validator: (args) => {
+            // Disallow -e, -p, -r flags that allow arbitrary code execution
+            return !args.some(a => a === '-e' || a === '-p' || a === '-r' || a === '--eval');
+        }
+    },
+    npm: {
+        description: 'npm 包管理',
+        params: {
+            'install': { type: 'literal' },
+            'run': { type: 'literal' },
+            '-y': { type: 'flag' },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+        validator: (args) => {
+            // 禁止全局安装、危险脚本
+            // Disallow dangerous flags that allow code execution
+            // Disallow dangerous flags that allow code execution
+            const dangerous = ['-e', '-p', '-r', '--eval', '--check', '-c'];
+            return !args.some(a => dangerous.some(d => a === d || a.startsWith(d + '=')));
+        },
+    },
+    // 文件操作（安全限制下）
+    mkdir: {
+        description: '创建目录',
+        params: {
+            '-p': { type: 'flag' },
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+        validator: (args) => {
+            // 禁止在 /etc、/var 等系统目录创建
+            return !args.some(a => /^\/(etc|var|usr|bin|sbin|sys|proc|dev)/.test(a));
+        },
+    },
+    touch: {
+        description: '创建空文件',
+        params: {
+            path: { type: 'string', pattern: PATH_PATTERN },
+        },
+    },
+    // 进程/系统信息
+    ps: {
+        description: '进程状态',
+        params: {
+            'aux': { type: 'literal' },
+        },
+    },
+    env: {
+        description: '查看环境变量',
+        params: {},
+    },
+    whoami: {
+        description: '当前用户',
+        params: {},
+    },
+    pwd: {
+        description: '当前目录',
+        params: {},
+    },
+    date: {
+        description: '当前日期',
+        params: {},
+    },
+    // 简单输出
+    echo: {
+        description: '输出文本',
+        params: {
+            '-n': { type: 'flag' },
+            text: { type: 'string', pattern: /^[^\;\|\`\$\\]{0,500}$/ },
+        },
+    },
+};
+exports.ALLOWED_COMMANDS = ALLOWED_COMMANDS;
+class BashTool extends Tool_1.Tool {
+    metadata = METADATA;
+    async execute(args, ctx) {
+        try {
+            this.validateArgs(args);
+            const command = this.getArg(args, 'command');
+            const timeout = this.getArg(args, 'timeout', 30) ?? 30;
+            const cwd = this.getArg(args, 'cwd', process.cwd()) ?? process.cwd();
+            const extraEnv = this.getArg(args, 'env', {}) ?? {};
+            // 解析 workspacePath
+            const workspacePath = ctx?.workspacePath;
+            // 安全校验：白名单模式
+            const validation = this._validateCommand(command.trim());
+            if (!validation.valid) {
+                return {
+                    success: false,
+                    error: `Command not allowed: ${validation.reason}`,
+                };
+            }
+            // 执行命令
+            const { execSync } = await import('child_process');
+            const env = { ...process.env, ...extraEnv };
+            let stdout;
+            let stderr;
+            let exitCode;
+            try {
+                stdout = execSync(command, {
+                    cwd: workspacePath ?? cwd,
+                    env,
+                    encoding: 'utf8',
+                    timeout: timeout * 1000,
+                    maxBuffer: 10 * 1024 * 1024,
+                });
+                stderr = '';
+                exitCode = 0;
+            }
+            catch (err) {
+                const execError = err;
+                stdout = execError.stdout ?? '';
+                stderr = execError.stderr ?? '';
+                exitCode = execError.status ?? 1;
+            }
+            return {
+                success: exitCode === 0,
+                output: { stdout, stderr, exitCode },
+                metadata: { command, timeout, cwd },
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /**
+     * 白名单命令验证
+     * @returns { valid: boolean, reason?: string }
+     */
+    _validateCommand(command) {
+        // 第一道门：检查 shell 元字符（黑名单防止绕过白名单）
+        // 注意：不在字符类中放空格（会误杀 "ls -la" 等合法带空格命令）
+        // 只匹配真正的 shell 操作符和危险构造
+        const shellMetachars = /[;&|`$\x00{}\[\]!<>~#%^*\n\\]|&&|\|\||;;|<<|>>|<>|&\||\(|\\\(|\\\)/;
+        if (shellMetachars.test(command)) {
+            return { valid: false, reason: `Forbidden shell metacharacter in command` };
+        }
+        // 解析命令和参数
+        const parts = this._parseCommand(command);
+        if (parts.length === 0) {
+            return { valid: false, reason: 'Empty command' };
+        }
+        const cmdName = parts[0];
+        const cmdArgs = parts.slice(1);
+        // 检查命令是否在白名单中
+        const allowed = ALLOWED_COMMANDS[cmdName];
+        if (!allowed) {
+            return { valid: false, reason: `Command "${cmdName}" is not in whitelist` };
+        }
+        // 验证每个参数
+        const unknownArgs = cmdArgs.filter(arg => {
+            return !arg.startsWith('-') && !Object.keys(allowed.params).includes(arg);
+        });
+        if (unknownArgs.length > 0 && allowed.params.text) {
+            // echo/text 类型允许任意字符串参数
+        }
+        else if (unknownArgs.length > 0) {
+            return { valid: false, reason: `Unknown argument(s): ${unknownArgs.join(', ')}` };
+        }
+        // 运行命令特定的验证器
+        if (allowed.validator && !allowed.validator(cmdArgs)) {
+            return { valid: false, reason: `Command "${cmdName}" has forbidden operation` };
+        }
+        return { valid: true };
+    }
+    /**
+     * 简单命令解析（处理引号和转义）
+     */
+    _parseCommand(command) {
+        const parts = [];
+        let current = '';
+        let inQuote = false;
+        let quoteChar = '';
+        for (let i = 0; i < command.length; i++) {
+            const c = command[i];
+            if (inQuote) {
+                if (c === quoteChar) {
+                    inQuote = false;
+                }
+                else {
+                    current += c;
+                }
+            }
+            else if (c === '"' || c === "'") {
+                inQuote = true;
+                quoteChar = c;
+            }
+            else if (c === ' ' || c === '\t') {
+                if (current.length > 0) {
+                    parts.push(current);
+                    current = '';
+                }
+            }
+            else {
+                current += c;
+            }
+        }
+        if (current.length > 0) {
+            parts.push(current);
+        }
+        return parts;
+    }
+}
+exports.BashTool = BashTool;
+//# sourceMappingURL=BashTool.js.map

package/dist/agent/tools/BashTool.js.map

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

package/dist/agent/tools/FileReadTool.d.ts

@@ -0,0 +1,29 @@
+/**
+ * FileReadTool — 文件读取工具
+ * @version v0.12.50
+ *
+ * 读取本地文件内容，支持路径规范化和安全校验。
+ * 默认工作目录为 workspacePath（ToolContext 提供）。
+ *
+ * 使用示例：
+ *   const tool = new FileReadTool();
+ *   const result = await tool.execute({ path: '~/project/README.md', offset: 1, limit: 100 });
+ */
+import { Tool, ToolMetadata, ToolResult } from './Tool';
+declare const METADATA: ToolMetadata;
+/** 允许读取的根目录白名单（收紧：不允许整个 home，只允许特定子目录） */
+declare const ALLOWED_ROOTS: string[];
+export declare class FileReadTool extends Tool {
+    protected readonly metadata: ToolMetadata;
+    execute(args: Record<string, unknown>, ctx?: Record<string, unknown>): Promise<ToolResult>;
+    /** 展开 ~ 并解析为绝对路径 */
+    private _resolvePath;
+    /** 检查路径是否在白名单目录内 */
+    private _isAllowed;
+    /** 分页读取文件指定行范围 */
+    private _readPaginated;
+    /** 快速统计总行数（对大文件使用 wc -l 避免加载全部内容到内存） */
+    private _countLines;
+}
+export { METADATA as FILE_READ_TOOL_METADATA, ALLOWED_ROOTS };
+//# sourceMappingURL=FileReadTool.d.ts.map

package/dist/agent/tools/FileReadTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileReadTool.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/FileReadTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAExD,QAAA,MAAM,QAAQ,EAAE,YAwCf,CAAC;AAEF,0CAA0C;AAC1C,QAAA,MAAM,aAAa,UAQlB,CAAC;AAEF,qBAAa,YAAa,SAAQ,IAAI;IACpC,SAAS,CAAC,QAAQ,CAAC,QAAQ,eAAY;IAEjC,OAAO,CACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;IAsDtB,oBAAoB;IACpB,OAAO,CAAC,YAAY;IAOpB,oBAAoB;IACpB,OAAO,CAAC,UAAU;IAOlB,kBAAkB;IAClB,OAAO,CAAC,cAAc;IAQtB,wCAAwC;IACxC,OAAO,CAAC,WAAW;CAcpB;AAED,OAAO,EAAE,QAAQ,IAAI,uBAAuB,EAAE,aAAa,EAAE,CAAC"}

package/dist/agent/tools/FileReadTool.js

@@ -0,0 +1,196 @@
+/**
+ * FileReadTool — 文件读取工具
+ * @version v0.12.50
+ *
+ * 读取本地文件内容，支持路径规范化和安全校验。
+ * 默认工作目录为 workspacePath（ToolContext 提供）。
+ *
+ * 使用示例：
+ *   const tool = new FileReadTool();
+ *   const result = await tool.execute({ path: '~/project/README.md', offset: 1, limit: 100 });
+ */
+'use strict';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_ROOTS = exports.FILE_READ_TOOL_METADATA = exports.FileReadTool = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os_1 = require("os");
+const child_process_1 = require("child_process");
+const Tool_1 = require("./Tool");
+const METADATA = {
+    name: 'file_read',
+    description: '读取本地文件内容，支持分页（offset/limit）和编码指定。',
+    category: 'file',
+    params: [
+        {
+            name: 'path',
+            description: '文件绝对路径（支持 ~/ 展开）',
+            type: 'string',
+            required: true,
+        },
+        {
+            name: 'offset',
+            description: '起始行号（1-indexed，默认 1）',
+            type: 'number',
+            required: false,
+            default: 1,
+        },
+        {
+            name: 'limit',
+            description: '最多读取行数（默认 500，max 2000）',
+            type: 'number',
+            required: false,
+            default: 500,
+        },
+        {
+            name: 'encoding',
+            description: '文件编码（默认 utf8）',
+            type: 'string',
+            required: false,
+            default: 'utf8',
+        },
+    ],
+    examples: [
+        {
+            input: { path: '~/README.md', limit: 50 },
+            output: { success: true, output: { content: '# Hello\n...', linesRead: 50 } },
+        },
+    ],
+    version: '0.12.50',
+};
+exports.FILE_READ_TOOL_METADATA = METADATA;
+/** 允许读取的根目录白名单（收紧：不允许整个 home，只允许特定子目录） */
+const ALLOWED_ROOTS = [
+    path.join((0, os_1.homedir)(), '.hermes', 'skills'),
+    path.join((0, os_1.homedir)(), '.hermes', 'cron'),
+    path.join((0, os_1.homedir)(), '.hermes', 'memory'),
+    path.join((0, os_1.homedir)(), '.hermes', 'config'),
+    path.join((0, os_1.homedir)(), '.hermes', 'data'),
+    '/tmp',
+    '/var/folders', // macOS temporary directories
+];
+exports.ALLOWED_ROOTS = ALLOWED_ROOTS;
+class FileReadTool extends Tool_1.Tool {
+    metadata = METADATA;
+    async execute(args, ctx) {
+        try {
+            this.validateArgs(args);
+            const rawPath = this.getArg(args, 'path');
+            const offset = this.getArg(args, 'offset', 1) ?? 1;
+            const limit = Math.min(this.getArg(args, 'limit', 500) ?? 500, 2000);
+            const encoding = this.getArg(args, 'encoding', 'utf8') ?? 'utf8';
+            // 解析路径（展开 ~）
+            const filePath = this._resolvePath(rawPath);
+            // 安全校验：确保文件在白名单目录下
+            if (!this._isAllowed(filePath)) {
+                return {
+                    success: false,
+                    error: `Access denied: path "${filePath}" is outside allowed directories`,
+                };
+            }
+            // 检查文件是否存在
+            if (!fs.existsSync(filePath)) {
+                return { success: false, error: `File not found: ${filePath}` };
+            }
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                return { success: false, error: `Path is a directory, not a file: ${filePath}` };
+            }
+            // 分页读取
+            const content = this._readPaginated(filePath, offset, limit, encoding);
+            return {
+                success: true,
+                output: {
+                    path: filePath,
+                    content,
+                    linesRead: content.split('\n').length,
+                    totalLines: this._countLines(filePath, encoding),
+                    offset,
+                    limit,
+                    encoding,
+                },
+                metadata: { sizeBytes: stat.size },
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /** 展开 ~ 并解析为绝对路径 */
+    _resolvePath(rawPath) {
+        if (rawPath.startsWith('~/')) {
+            return path.join((0, os_1.homedir)(), rawPath.slice(2));
+        }
+        return path.isAbsolute(rawPath) ? rawPath : path.resolve(rawPath);
+    }
+    /** 检查路径是否在白名单目录内 */
+    _isAllowed(filePath) {
+        // Reject path segments containing .. before normalization to prevent traversal bypass
+        if (filePath.includes('..'))
+            return false;
+        const normalized = path.normalize(filePath);
+        return ALLOWED_ROOTS.some(root => normalized.startsWith(root + path.sep) || normalized === root);
+    }
+    /** 分页读取文件指定行范围 */
+    _readPaginated(filePath, offset, limit, encoding) {
+        const content = fs.readFileSync(filePath, encoding);
+        const lines = content.split('\n');
+        const start = Math.max(0, offset - 1);
+        const end = Math.min(start + limit, lines.length);
+        return lines.slice(start, end).join('\n');
+    }
+    /** 快速统计总行数（对大文件使用 wc -l 避免加载全部内容到内存） */
+    _countLines(filePath, encoding) {
+        const stat = fs.statSync(filePath);
+        // 对大于 1MB 的文件使用 wc -l 子进程来计数
+        if (stat.size > 1024 * 1024 && encoding === 'utf8') {
+            try {
+                const output = (0, child_process_1.execFileSync)('wc', ['-l', filePath], { encoding: 'utf8', shell: false });
+                return parseInt(output.trim().split(/\s+/)[0], 10) || 0;
+            }
+            catch {
+                // 回退到内存读取方式
+            }
+        }
+        const content = fs.readFileSync(filePath, encoding);
+        return content.split('\n').length;
+    }
+}
+exports.FileReadTool = FileReadTool;
+//# sourceMappingURL=FileReadTool.js.map

package/dist/agent/tools/FileReadTool.js.map

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

package/dist/agent/tools/FileWriteTool.d.ts

@@ -0,0 +1,35 @@
+/**
+ * FileWriteTool — 文件写入工具
+ * @version v0.12.50
+ *
+ * 创建或覆盖写入本地文件，支持自动创建父目录。
+ * 默认工作目录为 workspacePath（ToolContext 提供）。
+ *
+ * 安全特性：
+ *   - 路径白名单校验（防止写入 /etc、/usr 等敏感目录）
+ *   - 不允许覆盖已存在文件（除非显式指定 force）
+ *   - 不允许写入二进制文件
+ *
+ * 使用示例：
+ *   const tool = new FileWriteTool();
+ *   const result = await tool.execute({
+ *     path: '~/project/new-file.ts',
+ *     content: 'export const version = "1.0";',
+ *   });
+ */
+import { Tool, ToolMetadata, ToolResult } from './Tool';
+declare const METADATA: ToolMetadata;
+/** 禁止写入的路径前缀（扩展安全边界） */
+declare const BLOCKED_PREFIXES: string[];
+export declare class FileWriteTool extends Tool {
+    protected readonly metadata: ToolMetadata;
+    execute(args: Record<string, unknown>, _ctx?: Record<string, unknown>): Promise<ToolResult>;
+    /** 展开 ~ 并解析为绝对路径 */
+    private _resolvePath;
+    /** 检查是否在黑名单前缀内（带路径分隔符边界检查） */
+    private _isBlocked;
+    /** 检测是否为二进制内容 */
+    private _isBinary;
+}
+export { METADATA as FILE_WRITE_TOOL_METADATA, BLOCKED_PREFIXES };
+//# sourceMappingURL=FileWriteTool.d.ts.map

package/dist/agent/tools/FileWriteTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileWriteTool.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/FileWriteTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAExD,QAAA,MAAM,QAAQ,EAAE,YAuCf,CAAC;AAEF,wBAAwB;AACxB,QAAA,MAAM,gBAAgB,UAQrB,CAAC;AAEF,qBAAa,aAAc,SAAQ,IAAI;IACrC,SAAS,CAAC,QAAQ,CAAC,QAAQ,eAAY;IAEjC,OAAO,CACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAE7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,UAAU,CAAC;IAsEtB,oBAAoB;IACpB,OAAO,CAAC,YAAY;IAOpB,8BAA8B;IAC9B,OAAO,CAAC,UAAU;IASlB,iBAAiB;IACjB,OAAO,CAAC,SAAS;CAIlB;AAED,OAAO,EAAE,QAAQ,IAAI,wBAAwB,EAAE,gBAAgB,EAAE,CAAC"}