codex-skills-mcp 1.0.0

package/README.md

@@ -0,0 +1,221 @@
+# codex-skills-mcp
+
+> 🧠 Codex-Skills 技能库的 MCP (Model Context Protocol) Server — 让任意 AI 编程工具都能检索、阅读和使用 170+ 专业技能。
+
+## 这是什么
+
+一个独立的 MCP Server，为 [codex-skills](https://github.com/Zhan-ZhangZ/codex-skills) 技能库提供标准化的 AI 工具接入协议。
+
+| 特性 | 说明 |
+|------|------|
+| **6 个 MCP Tools** | search_skills, read_skill, load_skill_file, list_skill_files, list_categories, plan_workflow |
+| **三层渐进加载** | 检索(~500 tokens) → 阅读(~5K tokens) → 深入(按需) |
+| **中文搜索优化** | CJK bigram 分词 + Leading Words 权重 |
+| **零外部 AI 依赖** | 纯关键词搜索，不需要 embedding 模型 |
+| **双传输模式** | stdio（本地）+ HTTP（远程，适配 ChatGPT 桌面端） |
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+cd codex-skills-mcp
+npm install
+npm run build
+```
+
+### 2. 配置客户端
+
+---
+
+#### ⭐ ChatGPT 桌面端（主要推荐）
+
+ChatGPT 桌面端仅支持远程 HTTP 连接，不支持本地 stdio。需要以 HTTP 模式启动 MCP Server，再通过 ngrok 等隧道工具暴露为公网地址。
+
+**Step 1：启动 HTTP 模式**
+
+```bash
+node dist/index.js --skills-dir /path/to/codex-skills --http --port 3456
+```
+
+启动后会看到：
+```
+[codex-skills-mcp] HTTP server running at http://localhost:3456/mcp
+[codex-skills-mcp] Health check: http://localhost:3456/health
+```
+
+**Step 2：用 ngrok 暴露到公网**
+
+```bash
+ngrok http 3456
+```
+
+会得到一个公网地址，如 `https://xxxx-xxxx.ngrok-free.app`
+
+**Step 3：在 ChatGPT 桌面端添加 MCP Server**
+
+1. 打开 ChatGPT 桌面端 → **Settings** → **Advanced** 或 **Connectors**
+2. 找到 **MCP Servers** / **Apps** 区域
+3. 点击 **Add Server**
+4. 填入 URL：`https://xxxx-xxxx.ngrok-free.app/mcp`
+5. 保存，完成
+
+> **💡 提示**：ngrok 免费版每次重启会更换地址。如果需要固定地址，可以使用 ngrok 付费版或其他隧道工具（如 Cloudflare Tunnel）。
+
+**验证是否正常运行：**
+
+```bash
+# 健康检查
+curl http://localhost:3456/health
+
+# 预期输出
+{"status":"ok","name":"codex-skills-mcp","version":"1.0.0","skills":181}
+```
+
+---
+
+#### Claude Desktop
+
+编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "codex-skills": {
+      "command": "node",
+      "args": [
+        "/path/to/codex-skills-mcp/dist/index.js",
+        "--skills-dir",
+        "/path/to/codex-skills"
+      ]
+    }
+  }
+}
+```
+
+---
+
+#### Cursor
+
+编辑项目根目录 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "codex-skills": {
+      "command": "node",
+      "args": [
+        "/path/to/codex-skills-mcp/dist/index.js",
+        "--skills-dir",
+        "/path/to/codex-skills"
+      ]
+    }
+  }
+}
+```
+
+---
+
+#### Windsurf / VS Code + Copilot
+
+在 MCP 配置中添加同样的 command + args（stdio 模式）。
+
+---
+
+#### 环境变量方式
+
+也可以通过环境变量指定技能库路径：
+
+```bash
+export CODEX_SKILLS_DIR=/path/to/codex-skills
+# stdio 模式
+node /path/to/codex-skills-mcp/dist/index.js
+# HTTP 模式
+node /path/to/codex-skills-mcp/dist/index.js --http --port 3456
+```
+
+## 两种运行模式
+
+| 模式 | 启动方式 | 适用客户端 |
+|------|---------|-----------|
+| **stdio**（默认） | `node dist/index.js --skills-dir ...` | Claude Desktop, Cursor, Windsurf, VS Code |
+| **HTTP** | `node dist/index.js --skills-dir ... --http --port 3456` | ChatGPT 桌面端, 远程客户端 |
+
+## MCP Tools
+
+### 🔍 search_skills
+搜索技能库。Agent 的主入口。
+
+```
+input:  { query: "前端性能优化", category?: "01_代码工程与架构", limit?: 8 }
+output: 按相关度排序的技能列表
+```
+
+### 📖 read_skill
+读取技能的完整指令（SKILL.md）+ 文件结构 + 环境依赖。
+
+```
+input:  { name: "MediaCrawler" }
+output: { instructions, structure, dependencies }
+```
+
+### 📂 load_skill_file
+按需读取技能内的任意文件。
+
+```
+input:  { skill_name: "KrillinAI", file_path: "README.md" }
+output: { content, size_bytes }
+```
+
+### 🗂️ list_skill_files
+浏览技能的文件树（不读内容）。
+
+```
+input:  { skill_name: "remotion-skills", path?: "src", max_depth?: 3 }
+output: 目录树
+```
+
+### 📋 list_categories
+列出所有技能分类和数量。
+
+```
+input:  {}
+output: 14 个分类 + 各自的技能数量
+```
+
+### 🔗 plan_workflow
+给定任务描述，推荐可组合使用的技能。
+
+```
+input:  { task_description: "把技术博客做成小红书图文" }
+output: 推荐技能列表 + 分类分组
+```
+
+## 使用流程
+
+```
+用户: "帮我把这个视频翻译成中文字幕"
+
+Agent → search_skills("视频字幕翻译")
+     → 命中: KrillinAI, videocut-skills, VideoClaw
+
+Agent → read_skill("KrillinAI")
+     → 获取 SKILL.md 指令，了解怎么用
+
+Agent → load_skill_file("KrillinAI", "README.md")
+     → 获取详细配置参数
+
+Agent → 按 SKILL.md 指令执行任务
+```
+
+## 技术栈
+
+- TypeScript + ESM
+- `@modelcontextprotocol/sdk` v1.12+
+- `express` (仅 HTTP 模式)
+- `zod` 运行时 schema 验证
+- Node.js 18+
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+export interface Config {
+    skillsDir: string;
+    manifestPath: string;
+    isRemote: boolean;
+    githubRepo?: string;
+    githubBranch?: string;
+    githubPath?: string;
+    githubToken?: string;
+}
+/**
+ * Parse config from CLI args and env vars.
+ */
+export declare function parseConfig(args: string[]): Config;
+export interface ManifestEntry {
+    name: string;
+    description: string;
+    category: string;
+    folder: string;
+    relative_path: string;
+}
+export declare function loadManifest(manifestPath: string): ManifestEntry[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CA4ElD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,EAAE,CAGlE"}

package/dist/config.js

@@ -0,0 +1,95 @@
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { execSync } from "node:child_process";
+/**
+ * Helper to extract GitHub token from Git credentials
+ */
+function getGitGithubToken() {
+    try {
+        const output = execSync('echo "protocol=https\\nhost=github.com\\n" | git credential fill', {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "ignore"]
+        });
+        const match = output.match(/^password=(.+)$/m);
+        if (match && match[1]) {
+            // Don't log the full token
+            console.error("[codex-skills-mcp] Auto-detected GitHub token from Git credentials");
+            return match[1].trim();
+        }
+    }
+    catch (err) {
+        // Ignore errors (git not installed or no credentials)
+    }
+    return undefined;
+}
+/**
+ * Parse config from CLI args and env vars.
+ */
+export function parseConfig(args) {
+    let skillsDir;
+    // Parse github arguments
+    const getArg = (flag) => {
+        const idx = args.indexOf(flag);
+        return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+    };
+    const githubRepo = getArg("--github-repo");
+    const githubBranch = getArg("--github-branch") || "main-lite";
+    const githubPath = getArg("--github-path") || "codex-skills";
+    let githubToken = getArg("--github-token");
+    // Fallback to valid ENV token
+    if (!githubToken && process.env.GITHUB_TOKEN && process.env.GITHUB_TOKEN !== "github_pat_antigravitydummytoken") {
+        githubToken = process.env.GITHUB_TOKEN;
+    }
+    // Fallback to Git credentials
+    if (!githubToken) {
+        githubToken = getGitGithubToken();
+    }
+    const isRemote = !!githubRepo;
+    if (isRemote) {
+        skillsDir = resolve(process.cwd(), ".codex-skills-cache");
+        if (!existsSync(skillsDir)) {
+            mkdirSync(skillsDir, { recursive: true });
+        }
+    }
+    else {
+        // Local mode logic
+        const dirIdx = args.indexOf("--skills-dir");
+        if (dirIdx !== -1 && args[dirIdx + 1]) {
+            skillsDir = resolve(args[dirIdx + 1]);
+        }
+        if (!skillsDir && process.env.CODEX_SKILLS_DIR) {
+            skillsDir = resolve(process.env.CODEX_SKILLS_DIR);
+        }
+        if (!skillsDir) {
+            const cwd = process.cwd();
+            if (existsSync(resolve(cwd, "skills_manifest.json"))) {
+                skillsDir = cwd;
+            }
+        }
+        if (!skillsDir) {
+            console.error("Error: Skills directory not found.\n" +
+                "Specify via --skills-dir <path> or CODEX_SKILLS_DIR env var.\n" +
+                "The directory must contain skills_manifest.json.");
+            process.exit(1);
+        }
+    }
+    const manifestPath = resolve(skillsDir, "skills_manifest.json");
+    if (!isRemote && !existsSync(manifestPath)) {
+        console.error(`Error: skills_manifest.json not found in ${skillsDir}`);
+        process.exit(1);
+    }
+    return {
+        skillsDir,
+        manifestPath,
+        isRemote,
+        githubRepo,
+        githubBranch,
+        githubPath,
+        githubToken
+    };
+}
+export function loadManifest(manifestPath) {
+    const raw = readFileSync(manifestPath, "utf-8");
+    return JSON.parse(raw);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Codex-Skills MCP Server
+ *
+ * Provides intelligent search, read, and orchestration of the codex-skills
+ * library via the Model Context Protocol (MCP).
+ *
+ * Supports two transport modes:
+ *   1. stdio (default) — for Claude Desktop, Cursor, Windsurf etc.
+ *   2. HTTP  (--http)  — for ChatGPT desktop app and other remote clients
+ *
+ * Usage:
+ *   # stdio mode (default)
+ *   node dist/index.js --skills-dir /path/to/codex-skills
+ *
+ *   # HTTP mode (for ChatGPT desktop)
+ *   node dist/index.js --skills-dir /path/to/codex-skills --http --port 3456
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Codex-Skills MCP Server
+ *
+ * Provides intelligent search, read, and orchestration of the codex-skills
+ * library via the Model Context Protocol (MCP).
+ *
+ * Supports two transport modes:
+ *   1. stdio (default) — for Claude Desktop, Cursor, Windsurf etc.
+ *   2. HTTP  (--http)  — for ChatGPT desktop app and other remote clients
+ *
+ * Usage:
+ *   # stdio mode (default)
+ *   node dist/index.js --skills-dir /path/to/codex-skills
+ *
+ *   # HTTP mode (for ChatGPT desktop)
+ *   node dist/index.js --skills-dir /path/to/codex-skills --http --port 3456
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { parseConfig, loadManifest } from "./config.js";
+import { SkillSearchEngine } from "./search/index.js";
+import { SkillLoader } from "./loader/index.js";
+import { registerSearchSkills } from "./tools/search-skills.js";
+import { registerListCategories } from "./tools/list-categories.js";
+import { registerReadSkill } from "./tools/read-skill.js";
+import { registerLoadSkillFile } from "./tools/load-skill-file.js";
+import { registerListSkillFiles } from "./tools/list-skill-files.js";
+import { registerPlanWorkflow } from "./tools/plan-workflow.js";
+function createServer(searchEngine, loader) {
+    const server = new McpServer({
+        name: "codex-skills",
+        version: "1.0.0",
+    });
+    registerSearchSkills(server, searchEngine);
+    registerListCategories(server, searchEngine);
+    registerReadSkill(server, searchEngine, loader);
+    registerLoadSkillFile(server, searchEngine, loader);
+    registerListSkillFiles(server, searchEngine, loader);
+    registerPlanWorkflow(server, searchEngine);
+    return server;
+}
+async function startStdio(searchEngine, loader) {
+    const server = createServer(searchEngine, loader);
+    console.error("[codex-skills-mcp] 6 tools registered, starting stdio server...");
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[codex-skills-mcp] Server running on stdio");
+}
+async function startHTTP(searchEngine, loader, port) {
+    // Dynamic import to avoid loading express in stdio mode
+    const { default: express } = await import("express");
+    const app = express();
+    app.use(express.json());
+    // Store transports for session management
+    const transports = new Map();
+    // MCP endpoint — handles POST (messages) and GET (SSE stream) and DELETE (session close)
+    app.post("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        let transport;
+        if (sessionId && transports.has(sessionId)) {
+            transport = transports.get(sessionId);
+        }
+        else {
+            // New session
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => crypto.randomUUID(),
+                onsessioninitialized: (sid) => {
+                    transports.set(sid, transport);
+                    console.error(`[codex-skills-mcp] New session: ${sid}`);
+                },
+            });
+            transport.onclose = () => {
+                const sid = transport.sessionId;
+                if (sid)
+                    transports.delete(sid);
+            };
+            // Each session gets its own server instance
+            const server = createServer(searchEngine, loader);
+            await server.connect(transport);
+        }
+        await transport.handleRequest(req, res, req.body);
+    });
+    // GET endpoint for SSE stream (needed by some clients)
+    app.get("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !transports.has(sessionId)) {
+            res.status(400).json({ error: "Invalid or missing session ID" });
+            return;
+        }
+        const transport = transports.get(sessionId);
+        await transport.handleRequest(req, res);
+    });
+    // DELETE endpoint for session cleanup
+    app.delete("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (sessionId && transports.has(sessionId)) {
+            const transport = transports.get(sessionId);
+            await transport.handleRequest(req, res);
+            transports.delete(sessionId);
+        }
+        else {
+            res.status(200).end();
+        }
+    });
+    // Health check
+    app.get("/health", (_req, res) => {
+        res.json({
+            status: "ok",
+            name: "codex-skills-mcp",
+            version: "1.0.0",
+            skills: searchEngine.getCategories().reduce((s, c) => s + c.skill_count, 0),
+        });
+    });
+    console.error("[codex-skills-mcp] 6 tools registered, starting HTTP server...");
+    app.listen(port, () => {
+        console.error(`[codex-skills-mcp] HTTP server running at http://localhost:${port}/mcp`);
+        console.error(`[codex-skills-mcp] Health check: http://localhost:${port}/health`);
+        console.error(`[codex-skills-mcp] For ChatGPT desktop: use ngrok or similar to expose this endpoint`);
+    });
+}
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse configuration
+    const config = parseConfig(args);
+    if (config.isRemote) {
+        const { initRemote, fetchManifest } = await import("./remote/github.js");
+        console.error("[codex-skills-mcp] Initializing remote GitHub fetching...");
+        await initRemote(config);
+        await fetchManifest(config);
+    }
+    // Load manifest
+    console.error(`[codex-skills-mcp] Loading manifest from: ${config.manifestPath}`);
+    const manifest = loadManifest(config.manifestPath);
+    console.error(`[codex-skills-mcp] Loaded ${manifest.length} skills`);
+    // Build search index
+    const searchEngine = new SkillSearchEngine(manifest);
+    const categories = searchEngine.getCategories();
+    console.error(`[codex-skills-mcp] Index built: ${categories.length} categories, ` +
+        `${categories.reduce((s, c) => s + c.skill_count, 0)} indexed skills`);
+    // Create skill loader
+    const loader = new SkillLoader(config, manifest);
+    // Determine transport mode
+    const useHTTP = args.includes("--http");
+    if (useHTTP) {
+        // Parse port
+        const portIdx = args.indexOf("--port");
+        const port = portIdx !== -1 && args[portIdx + 1] ? parseInt(args[portIdx + 1], 10) : 3456;
+        await startHTTP(searchEngine, loader, port);
+    }
+    else {
+        await startStdio(searchEngine, loader);
+    }
+}
+main().catch((err) => {
+    console.error("[codex-skills-mcp] Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/loader/index.d.ts

@@ -0,0 +1,68 @@
+import type { ManifestEntry, Config } from "../config.js";
+export interface SkillStructure {
+    files: FileNode[];
+    sub_skills: SubSkillInfo[];
+}
+export interface FileNode {
+    name: string;
+    type: "file" | "directory";
+    size_bytes?: number;
+    children?: FileNode[];
+}
+export interface SubSkillInfo {
+    name: string;
+    path: string;
+    description: string;
+}
+export interface SkillDependencies {
+    language: string;
+    package_manager?: string;
+    setup_command?: string;
+}
+export interface ReadSkillResult {
+    instructions: string;
+    structure: SkillStructure;
+    dependencies: SkillDependencies;
+}
+/**
+ * Skill loader — reads SKILL.md, scans structure, detects dependencies.
+ */
+export declare class SkillLoader {
+    private config;
+    private manifest;
+    private skillsDir;
+    constructor(config: Config, manifest: ManifestEntry[]);
+    /**
+     * Resolve the absolute filesystem path for a skill.
+     */
+    resolveSkillPath(entry: ManifestEntry): string;
+    /**
+     * Read a skill's SKILL.md + structure + dependencies.
+     */
+    readSkill(entry: ManifestEntry): Promise<ReadSkillResult>;
+    /**
+     * Scan the file tree of a skill (max depth 2 by default).
+     */
+    scanStructure(dirPath: string, entry: ManifestEntry, maxDepth?: number): SkillStructure;
+    private scanDirectory;
+    /**
+     * Recursively find sub-skill SKILL.md files (not the root one).
+     */
+    private findSubSkills;
+    /**
+     * Detect language and package manager from project files.
+     */
+    private detectDependencies;
+    /**
+     * Load a specific file from within a skill directory.
+     */
+    loadSkillFile(entry: ManifestEntry, filePath: string): Promise<{
+        content: string;
+        size_bytes: number;
+    }>;
+    /**
+     * List files in a subdirectory of a skill.
+     */
+    listSkillFiles(entry: ManifestEntry, subPath?: string, maxDepth?: number): Promise<FileNode[]>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loader/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG1D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,cAAc,CAAC;IAC1B,YAAY,EAAE,iBAAiB,CAAC;CACjC;AAYD;;GAEG;AACH,qBAAa,WAAW;IAIpB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IAJlB,OAAO,CAAC,SAAS,CAAS;gBAGhB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,EAAE;IAKnC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM;IAM9C;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;IAyB/D;;OAEG;IACH,aAAa,CACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,aAAa,EACpB,QAAQ,GAAE,MAAU,GACnB,cAAc;IAUjB,OAAO,CAAC,aAAa;IA+CrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAuCrB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8C1B;;OAEG;IACG,aAAa,CACjB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAiDnD;;OAEG;IACG,cAAc,CAClB,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,MAAW,EACpB,QAAQ,GAAE,MAAU,GACnB,OAAO,CAAC,QAAQ,EAAE,CAAC;CAmBvB"}