@szc-ft/mcp-szcd-client 0.24.0 → 0.26.0

package/qwen-extension/skills/local-api-tool/scripts/extract-swagger.mjs

@@ -0,0 +1,625 @@
+#!/usr/bin/env node
+/**
+ * extract-swagger.mjs — 本地 Swagger 文档提取与解析（与服务端 parseApiDocs 一比一对齐）
+ *
+ * 同目录 extract_swagger.py 的 Node.js 等价版本。
+ * 选 Node 是因为 mcp 客户端用户 100% 已装 Node，跨平台零安装；
+ * .mjs 扩展名强制 ESM，避开宿主 package.json "type":"module" 冲突。
+ *
+ * 用法：
+ *   node extract-swagger.mjs --url http://10.x.x.x/svc/v2/api-docs [--cookie 'JSESSIONID=xxx']
+ *   node extract-swagger.mjs --url ... --no-cache         # 强制重新下载
+ *   node extract-swagger.mjs --url ... --cache-ttl 3600   # 自定义 TTL（秒），0 关闭
+ *
+ *   node extract-swagger.mjs --file /tmp/swagger.json
+ *   node extract-swagger.mjs --file /tmp/swagger.json --filter tag --filter user
+ *   node extract-swagger.mjs --file /tmp/swagger.json --definition KnowledgeOperLogVO
+ *   node extract-swagger.mjs --file /tmp/swagger.json --filter tag --out /tmp/parsed.json
+ *
+ * 容错：自动修复八进制字面量 `[011,015]` → `[11,15]`；JSON 解析失败给出 ±80 字符上下文 + 常见原因。
+ * 网络：优先用 Node ≥18 内置 fetch；不可用时降级 spawnSync('curl')。
+ * 退出码：0 成功；1 参数错误；2 网络/IO 错误；3 解析错误
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+const MAX_DEPTH = 5;
+const METHOD_KEYS = ["post", "get", "put", "delete", "patch"];
+
+// 缓存配置（与 Python 版完全一致：同 key 可共享缓存）
+const CACHE_DIR = path.join(os.tmpdir(), "swagger-cache");
+const DEFAULT_CACHE_TTL = 600;
+
+// 八进制字面量：JSON 标准不允许数字以 0 开头（除 0 本身或小数），
+// 但部分 Java/旧网关序列化会产出 [011,015,022]。
+const OCTAL_LITERAL_RE = /(?<=[\s,\[:])0(\d+)(?=[\s,\]}])/g;
+
+// ==================== 工具函数 ====================
+
+function refName(prop) {
+    if (!prop || typeof prop !== "object") return null;
+    if (prop.originalRef) return prop.originalRef;
+    if (prop.$ref) return prop.$ref.split("/").pop();
+    return null;
+}
+
+function refNameWithItems(prop) {
+    if (!prop || typeof prop !== "object") return null;
+    const name = refName(prop);
+    if (name) return name;
+    if (prop.items && typeof prop.items === "object") return refName(prop.items);
+    return null;
+}
+
+function resolvePropertyType(prop) {
+    if (!prop || typeof prop !== "object") return "string";
+    if (prop.type === "array") {
+        const items = prop.items || {};
+        const itemType =
+            items.type ||
+            items.originalRef ||
+            (items.$ref ? items.$ref.split("/").pop() : null) ||
+            "object";
+        return `array<${itemType}>`;
+    }
+    if (prop.type) return prop.type;
+    if (prop.originalRef) return prop.originalRef;
+    if (prop.$ref) return prop.$ref.split("/").pop();
+    return "object";
+}
+
+// ==================== 递归展开（对齐 expandProperties，深度 5） ====================
+
+function expandProperties(properties, definitions, depth = 0, maxDepth = MAX_DEPTH) {
+    if (!properties) return [];
+    const out = [];
+    for (const [name, rawProp] of Object.entries(properties)) {
+        const prop = (rawProp && typeof rawProp === "object") ? rawProp : {};
+        const entry = {
+            name,
+            type: resolvePropertyType(prop),
+            description: prop.description || "",
+        };
+        if (prop.format !== undefined) entry.format = prop.format;
+        if (prop.example !== undefined) entry.example = prop.example;
+        if (prop.enum !== undefined) entry.enum = prop.enum;
+
+        const rName = refNameWithItems(prop);
+        if (rName) entry.refName = rName;
+
+        if (prop.type === "array" && rName && depth < maxDepth) {
+            const itemDef = (definitions || {})[rName];
+            if (itemDef && typeof itemDef === "object" && itemDef.properties) {
+                entry.itemProperties = expandProperties(itemDef.properties, definitions, depth + 1, maxDepth);
+            }
+        }
+
+        if (prop.type === "object" && rName && depth < maxDepth) {
+            const nested = (definitions || {})[rName];
+            if (nested && typeof nested === "object" && nested.properties) {
+                entry.nestedProperties = expandProperties(nested.properties, definitions, depth + 1, maxDepth);
+            }
+        }
+
+        if (prop.type === "object" && !rName && prop.properties && depth < maxDepth) {
+            entry.nestedProperties = expandProperties(prop.properties, definitions, depth + 1, maxDepth);
+        }
+
+        out.push(entry);
+    }
+    return out;
+}
+
+// ==================== 主解析（对齐 parseApiDocs） ====================
+
+function parseApiDocs(apiDocs, referencedDefs = null) {
+    const paths = apiDocs.paths || {};
+    const tags = apiDocs.tags || [];
+    const definitions = apiDocs.definitions || {};
+    const info = apiDocs.info || null;
+    const apiBasePath = apiDocs.basePath || "";
+
+    const parsedTags = tags.map((t) => ({ name: t.name, description: t.description || "" }));
+    const parsedApis = [];
+    const autoReferencedDefs = new Set();
+
+    for (const [url, pathValue] of Object.entries(paths)) {
+        if (!pathValue || typeof pathValue !== "object") continue;
+        for (const method of METHOD_KEYS) {
+            const apiDef = pathValue[method];
+            if (!apiDef || typeof apiDef !== "object") continue;
+            const tag = (apiDef.tags && apiDef.tags[0]) || "default";
+            const parameters = apiDef.parameters || [];
+
+            const params = parameters.map((p) => {
+                const schema = p.schema || {};
+                const paramInfo = {
+                    name: p.name,
+                    in: p.in,
+                    required: p.required || false,
+                    type: p.type || schema.type || "string",
+                    description: p.description || "",
+                };
+                const rName = schema.originalRef || (schema.$ref ? schema.$ref.split("/").pop() : null);
+                if (rName) {
+                    paramInfo.dtoRef = rName;
+                    autoReferencedDefs.add(rName);
+                    const dto = definitions[rName];
+                    if (dto && typeof dto === "object" && dto.properties) {
+                        const dtoProps = expandProperties(dto.properties, definitions, 0, MAX_DEPTH);
+                        const requiredFields = dto.required || [];
+                        for (const prop of dtoProps) {
+                            if (requiredFields.includes(prop.name)) prop.required = true;
+                        }
+                        paramInfo.dtoProperties = dtoProps;
+                    }
+                }
+                return paramInfo;
+            });
+
+            // 响应（递归展开嵌套 VO）
+            let responseInfo = null;
+            const responses = apiDef.responses || {};
+            const r200 = responses["200"] || {};
+            const rSchema = (r200 && typeof r200 === "object") ? r200.schema : null;
+            if (rSchema && typeof rSchema === "object") {
+                const rName = rSchema.originalRef || (rSchema.$ref ? rSchema.$ref.split("/").pop() : null);
+                if (rName) {
+                    autoReferencedDefs.add(rName);
+                    const vo = definitions[rName];
+                    if (vo && typeof vo === "object" && vo.properties) {
+                        responseInfo = {
+                            voName: rName,
+                            properties: expandProperties(vo.properties, definitions, 0, MAX_DEPTH),
+                        };
+                    } else {
+                        responseInfo = { voName: rName };
+                    }
+                }
+            }
+
+            parsedApis.push({
+                url,
+                method: method.toUpperCase(),
+                tag,
+                summary: apiDef.summary || "",
+                description: apiDef.description || "",
+                deprecated: apiDef.deprecated || false,
+                parameters: params,
+                response: responseInfo,
+                operationId: apiDef.operationId || null,
+            });
+        }
+    }
+
+    // 收集被引用 definitions 的传递闭包
+    const collectedRefs = new Set(autoReferencedDefs);
+    const queue = [...autoReferencedDefs];
+    while (queue.length > 0) {
+        const name = queue.shift();
+        const def = definitions[name];
+        if (!def || typeof def !== "object" || !def.properties) continue;
+        for (const prop of Object.values(def.properties)) {
+            const rName = refNameWithItems(prop);
+            if (rName && definitions[rName] && !collectedRefs.has(rName)) {
+                collectedRefs.add(rName);
+                queue.push(rName);
+            }
+        }
+    }
+
+    // definitions 摘要层
+    const definitionsSummary = Object.entries(definitions).map(([name, def]) => ({
+        name,
+        type: (def && typeof def === "object" && def.type) ? def.type : "object",
+        description: (def && typeof def === "object" && (def.description || def.title)) || "",
+    }));
+
+    // definitionsDetail 详情层
+    const effectiveRefs = referencedDefs !== null ? referencedDefs : collectedRefs;
+    const definitionsDetail = [];
+    for (const name of effectiveRefs) {
+        const def = definitions[name];
+        if (def && typeof def === "object") {
+            definitionsDetail.push({
+                name,
+                type: def.type || "object",
+                description: def.description || def.title || "",
+                properties: expandProperties(def.properties || {}, definitions, 0, MAX_DEPTH),
+            });
+        }
+    }
+
+    return {
+        info: info ? { title: info.title, version: info.version, description: info.description } : null,
+        basePath: apiBasePath,
+        tags: parsedTags,
+        apis: parsedApis,
+        definitions: definitionsSummary,
+        definitionsDetail,
+    };
+}
+
+// ==================== 过滤（对齐 filterApis + trim_definitions_detail） ====================
+
+function filterApis(apis, keywords) {
+    if (!keywords || keywords.length === 0 || !apis || apis.length === 0) return apis;
+    const lower = keywords.map((k) => k.toLowerCase());
+    return apis.filter((api) => {
+        const dtoRefs = (api.parameters || [])
+            .map((p) => p.dtoRef || "")
+            .filter(Boolean)
+            .join(" ");
+        const responseVo = (api.response && api.response.voName) || "";
+        const searchable = [
+            api.url || "",
+            api.summary || "",
+            api.operationId || "",
+            api.tag || "",
+            api.description || "",
+            dtoRefs,
+            responseVo,
+        ].join(" ").toLowerCase();
+        return lower.some((kw) => searchable.includes(kw));
+    });
+}
+
+function trimDefinitionsDetail(result, keywords) {
+    const apis = result.apis || [];
+    const matchedRefs = new Set();
+    for (const api of apis) {
+        for (const p of api.parameters || []) {
+            if (p.dtoRef) matchedRefs.add(p.dtoRef);
+        }
+        if (api.response && api.response.voName) matchedRefs.add(api.response.voName);
+    }
+
+    const detailIndex = new Map();
+    for (const d of result.definitionsDetail || []) detailIndex.set(d.name, d);
+
+    const detailNames = new Set(matchedRefs);
+    const queue = [...matchedRefs];
+    while (queue.length > 0) {
+        const name = queue.shift();
+        const detail = detailIndex.get(name);
+        if (!detail || !detail.properties) continue;
+        for (const prop of detail.properties) {
+            const ref = prop.refName;
+            if (ref && !detailNames.has(ref)) {
+                detailNames.add(ref);
+                queue.push(ref);
+            }
+        }
+    }
+
+    result.definitionsDetail = (result.definitionsDetail || []).filter((d) => detailNames.has(d.name));
+    result._filter = { keywords, matched: apis.length };
+    return result;
+}
+
+// ==================== get_definition（单 VO 兜底） ====================
+
+function getDefinition(apiDocs, definitionName) {
+    const definitions = apiDocs.definitions || {};
+    if (definitions[definitionName]) {
+        const result = parseApiDocs(apiDocs, new Set([definitionName]));
+        const target = result.definitionsDetail.find((d) => d.name === definitionName) || null;
+        return { found: true, definition: target };
+    }
+    const lower = definitionName.toLowerCase();
+    const suggestions = Object.keys(definitions).filter((n) => n.toLowerCase().includes(lower)).slice(0, 10);
+    return {
+        found: false,
+        definitionName,
+        suggestions,
+        message: `未找到 definition '${definitionName}'。` + (
+            suggestions.length > 0 ? `相近建议：${suggestions.join(", ")}` : "无相近匹配。"
+        ),
+    };
+}
+
+// ==================== JSON 解析 + 容错 ====================
+
+function fixOctalLiterals(text) {
+    return text.replace(OCTAL_LITERAL_RE, (_, digits) => digits);
+}
+
+function diagnoseJsonError(text, err) {
+    // 从错误消息中提取 position
+    let pos = -1;
+    const m = /position\s+(\d+)/i.exec(err.message);
+    if (m) pos = parseInt(m[1], 10);
+    if (pos < 0) {
+        // 兜底：用 line/column（部分实现）
+        const lm = /line\s+(\d+)\s+column\s+(\d+)/i.exec(err.message);
+        if (lm) {
+            const line = parseInt(lm[1], 10), col = parseInt(lm[2], 10);
+            const lines = text.split("\n");
+            pos = 0;
+            for (let i = 0; i < line - 1 && i < lines.length; i++) pos += lines[i].length + 1;
+            pos += col - 1;
+        }
+    }
+    if (pos < 0) pos = 0;
+
+    const start = Math.max(0, pos - 80);
+    const end = Math.min(text.length, pos + 80);
+    const snippet = text.slice(start, end).replace(/\n/g, "\\n");
+    const marker = " ".repeat(pos - start) + "^";
+
+    // 反推 line/col 给提示
+    const before = text.slice(0, pos);
+    const beforeLines = before.split("\n");
+    const lineno = beforeLines.length;
+    const colno = beforeLines[beforeLines.length - 1].length + 1;
+
+    const hints = [];
+    const head = text.slice(0, 500).trimStart();
+    if (head.startsWith("<")) {
+        hints.push("响应以 '<' 开头，可能是 HTML 错误页/登录跳转页，而非 JSON。检查 cookie/auth 是否过期");
+    }
+    if (OCTAL_LITERAL_RE.test(text)) {
+        OCTAL_LITERAL_RE.lastIndex = 0;  // 重置 stateful regex
+        hints.push("检测到八进制字面量（如 [011,015]），脚本应已自动修复——若仍报错请提交 issue");
+    }
+    OCTAL_LITERAL_RE.lastIndex = 0;
+    const trimmedEnd = text.trimEnd();
+    if (text.length < 1024 && !trimmedEnd.endsWith("}") && !trimmedEnd.endsWith("]")) {
+        hints.push("响应可能被截断（curl 管道/终端缓冲），建议改用 --file 模式直接读本地文件");
+    }
+
+    let msg = `JSON 解析失败 at line ${lineno} col ${colno}: ${err.message}\n`;
+    msg += `  上下文: ...${snippet}...\n`;
+    msg += `          ${" ".repeat(11)}${marker}\n`;
+    if (hints.length > 0) {
+        msg += "  可能原因:\n" + hints.map((h) => `    - ${h}`).join("\n");
+    }
+    return msg;
+}
+
+function loadJsonText(text) {
+    try {
+        return JSON.parse(text);
+    } catch (e) {
+        // Fallback: 八进制修复
+        OCTAL_LITERAL_RE.lastIndex = 0;
+        if (OCTAL_LITERAL_RE.test(text)) {
+            OCTAL_LITERAL_RE.lastIndex = 0;
+            const fixed = fixOctalLiterals(text);
+            if (fixed !== text) {
+                try {
+                    const parsed = JSON.parse(fixed);
+                    process.stderr.write("[INFO] 自动修复八进制字面量后解析成功\n");
+                    return parsed;
+                } catch (e2) {
+                    throw new Error(diagnoseJsonError(fixed, e2));
+                }
+            }
+        }
+        throw new Error(diagnoseJsonError(text, e));
+    }
+}
+
+// ==================== 下载（fetch 优先，降级 curl） ====================
+
+async function fetchViaFetch(url, { cookie, auth, timeout } = {}) {
+    const controller = new AbortController();
+    const tid = setTimeout(() => controller.abort(), timeout * 1000);
+    try {
+        const headers = { Accept: "application/json" };
+        if (cookie) headers["Cookie"] = cookie;
+        if (auth) headers["Authorization"] = `Basic ${auth}`;
+        const res = await fetch(url, { headers, signal: controller.signal });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`HTTP ${res.status} ${res.statusText}${text ? ": " + text.slice(0, 200) : ""}`);
+        }
+        return await res.text();
+    } finally {
+        clearTimeout(tid);
+    }
+}
+
+function fetchViaCurl(url, { cookie, auth, timeout } = {}) {
+    const args = ["-sS", "--connect-timeout", "10", "--max-time", String(timeout), "-H", "Accept: application/json"];
+    if (cookie) args.push("-H", `Cookie: ${cookie}`);
+    if (auth) args.push("-H", `Authorization: Basic ${auth}`);
+    args.push(url);
+    const r = spawnSync("curl", args, { encoding: "utf-8" });
+    if (r.error) {
+        if (r.error.code === "ENOENT") throw new Error("找不到 curl 命令；且 Node 内置 fetch 也不可用（需 Node ≥ 18）");
+        throw new Error(`curl spawn 失败: ${r.error.message}`);
+    }
+    if (r.status !== 0) {
+        throw new Error(`curl 失败 (exit ${r.status}): ${(r.stderr || "").trim() || "无错误输出"}`);
+    }
+    if (!r.stdout || !r.stdout.trim()) throw new Error("curl 返回空响应");
+    return r.stdout;
+}
+
+async function fetchRaw(url, opts) {
+    if (typeof fetch === "function") {
+        try {
+            return await fetchViaFetch(url, opts);
+        } catch (e) {
+            // 网络错误/超时直接抛；HTTP 错误也直接抛（不应回退到 curl 掩盖问题）
+            throw new Error(`fetch 失败: ${e.message}`);
+        }
+    }
+    return fetchViaCurl(url, opts);
+}
+
+function cacheKey(url, cookie, auth) {
+    const h = crypto.createHash("sha256");
+    h.update(url, "utf-8");
+    if (cookie) h.update(Buffer.from("\x00" + cookie, "utf-8"));
+    if (auth) h.update(Buffer.from("\x00" + auth, "utf-8"));
+    return h.digest("hex").slice(0, 16);
+}
+
+async function fetchWithCache(url, { cookie, auth, timeout, ttl, noCache } = {}) {
+    if (noCache || ttl <= 0) {
+        return fetchRaw(url, { cookie, auth, timeout });
+    }
+    const key = cacheKey(url, cookie, auth);
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    const cacheFile = path.join(CACHE_DIR, `${key}.json`);
+    const metaFile = path.join(CACHE_DIR, `${key}.meta.json`);
+
+    if (fs.existsSync(cacheFile) && fs.existsSync(metaFile)) {
+        try {
+            const meta = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+            const age = Date.now() / 1000 - (meta.cached_at || 0);
+            if (age < ttl) {
+                process.stderr.write(`[CACHE] 命中 ${key} (age=${Math.floor(age)}s, ttl=${ttl}s)\n`);
+                return fs.readFileSync(cacheFile, "utf-8");
+            }
+        } catch { /* 缓存损坏，重新拉 */ }
+    }
+
+    const raw = await fetchRaw(url, { cookie, auth, timeout });
+    try {
+        fs.writeFileSync(cacheFile, raw, "utf-8");
+        fs.writeFileSync(metaFile, JSON.stringify({
+            url, cached_at: Date.now() / 1000, ttl, size: raw.length,
+        }), "utf-8");
+        process.stderr.write(`[CACHE] 已写入 ${key} (${raw.length} bytes)\n`);
+    } catch (e) {
+        process.stderr.write(`[WARN] 缓存写入失败: ${e.message}\n`);
+    }
+    return raw;
+}
+
+// ==================== CLI 参数 ====================
+
+function parseArgs(argv) {
+    const opts = {
+        url: null, file: null, cookie: null, auth: null,
+        timeout: 30, cacheTtl: DEFAULT_CACHE_TTL, noCache: false,
+        filter: [], definition: null, out: null, indent: 2,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => argv[++i];
+        switch (a) {
+            case "--url": opts.url = next(); break;
+            case "--file": opts.file = next(); break;
+            case "--cookie": opts.cookie = next(); break;
+            case "--auth": opts.auth = next(); break;
+            case "--timeout": opts.timeout = parseInt(next(), 10); break;
+            case "--cache-ttl": opts.cacheTtl = parseInt(next(), 10); break;
+            case "--no-cache": opts.noCache = true; break;
+            case "--filter": opts.filter.push(next()); break;
+            case "--definition": opts.definition = next(); break;
+            case "--out": opts.out = next(); break;
+            case "--indent": opts.indent = parseInt(next(), 10); break;
+            case "-h": case "--help": opts.help = true; break;
+            default:
+                process.stderr.write(`[ERROR] 未知参数: ${a}\n`);
+                process.exit(1);
+        }
+    }
+    return opts;
+}
+
+function printHelp() {
+    process.stdout.write(`extract-swagger.mjs — Swagger 文档提取（Node ≥18）
+
+必选（互斥）：
+  --url <api-docs URL>     从 URL 下载（内置 TTL 缓存）
+  --file <path>            读本地 JSON 文件
+
+可选：
+  --cookie '<JSESSIONID=xxx>'  鉴权 Cookie
+  --auth <base64(user:pass)>   Basic 鉴权
+  --timeout <秒>           网络超时，默认 30
+  --cache-ttl <秒>         缓存 TTL，默认 ${DEFAULT_CACHE_TTL}（10 分钟），0 关闭
+  --no-cache               强制重新下载
+  --filter <关键词>        过滤 api（可多次，匹配 url/summary/operationId/tag/description/dtoRef/voName）
+  --definition <名称>      仅查询单个 VO/DTO
+  --out <path>             输出到文件（默认 stdout）
+  --indent <数字>          JSON 缩进，默认 2，0 = 紧凑
+
+退出码：0 成功；1 参数错误；2 网络/IO；3 解析
+`);
+}
+
+// ==================== 主入口 ====================
+
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) { printHelp(); process.exit(0); }
+    if (!opts.url && !opts.file) {
+        process.stderr.write("[ERROR] 必须指定 --url 或 --file\n");
+        process.exit(1);
+    }
+    if (opts.url && opts.file) {
+        process.stderr.write("[ERROR] --url 与 --file 互斥\n");
+        process.exit(1);
+    }
+
+    // 1. 读 raw
+    let rawText;
+    try {
+        if (opts.url) {
+            rawText = await fetchWithCache(opts.url, {
+                cookie: opts.cookie, auth: opts.auth, timeout: opts.timeout,
+                ttl: opts.cacheTtl, noCache: opts.noCache,
+            });
+        } else {
+            rawText = fs.readFileSync(opts.file, "utf-8");
+        }
+    } catch (e) {
+        process.stderr.write(`[ERROR] 读取 Swagger 失败: ${e.message}\n`);
+        process.exit(2);
+    }
+
+    // 2. 解析 JSON
+    let apiDocs;
+    try {
+        apiDocs = loadJsonText(rawText);
+    } catch (e) {
+        process.stderr.write(`[ERROR] ${e.message}\n`);
+        process.exit(3);
+    }
+
+    // 3. 分支
+    let result;
+    try {
+        if (opts.definition) {
+            result = getDefinition(apiDocs, opts.definition);
+        } else {
+            result = parseApiDocs(apiDocs);
+            if (opts.filter.length > 0) {
+                const total = result.apis.length;
+                result.apis = filterApis(result.apis, opts.filter);
+                result = trimDefinitionsDetail(result, opts.filter);
+                result._filter.total = total;
+            }
+        }
+    } catch (e) {
+        process.stderr.write(`[ERROR] 解析失败: ${e.message}\n${e.stack || ""}\n`);
+        process.exit(3);
+    }
+
+    // 4. 输出
+    const indent = opts.indent > 0 ? opts.indent : 0;
+    const outText = indent > 0 ? JSON.stringify(result, null, indent) : JSON.stringify(result);
+    if (opts.out) {
+        fs.writeFileSync(opts.out, outText, "utf-8");
+        process.stderr.write(`[OK] 已输出到 ${opts.out} (${outText.length} bytes)\n`);
+    } else {
+        process.stdout.write(outText);
+        process.stdout.write("\n");
+    }
+}
+
+main().catch((e) => {
+    process.stderr.write(`[FATAL] ${e.message}\n${e.stack || ""}\n`);
+    process.exit(2);
+});