backtrace-console 0.0.1 → 0.0.3

package/lib/backtrace/analysis.js

@@ -1,356 +0,0 @@
-const fs = require("node:fs/promises");
-const path = require("node:path");
-const {
-  logStep,
-  normalizeFingerprint,
-  getFingerprintLogsRoot,
-  getFingerprintReportsRoot,
-  inferContentType,
-  ensureDirectory,
-} = require("./utils");
-
-// 分析辅助函数负责把下载后的崩溃附件整理成结构化提示词、
-// 汇总结果和 markdown 报告。
-function decodeXmlEntities(value) {
-  return String(value || "")
-    .replace(/"/g, "\"")
-    .replace(/'/g, "'")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&amp;/g, "&");
-}
-
-// 使用一组候选 key 名，从 runtime XML 里提取一个值。
-function extractXmlValue(xmlText, keys) {
-  for (const key of keys) {
-    // 兼容 pair/item/entry 这种键值结构。
-    const pairRegex = new RegExp(`<(?:pair|item|entry)[^>]*key="${key}"[^>]*>([\\s\\S]*?)<\\/(?:pair|item|entry)>`, "i");
-    const pairMatch = xmlText.match(pairRegex);
-    if (pairMatch?.[1]) {
-      return decodeXmlEntities(pairMatch[1].replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim());
-    }
-    // 也兼容直接以标签名承载值的 XML 结构。
-    const directRegex = new RegExp(`<${key}[^>]*>([\\s\\S]*?)<\\/${key}>`, "i");
-    const directMatch = xmlText.match(directRegex);
-    if (directMatch?.[1]) {
-      return decodeXmlEntities(directMatch[1].replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim());
-    }
-  }
-  return "";
-}
-
-// 提取 LLM 提示词和 markdown 报告真正会用到的运行时字段。
-function parseRuntimeXml(xmlText) {
-  return {
-    cpu: extractXmlValue(xmlText, ["CPU", "cpu", "processor", "Processor"]),
-    gpu: extractXmlValue(xmlText, ["GPU", "gpu", "graphics_adapter", "GraphicsAdapter", "gfx"]),
-    memory: extractXmlValue(xmlText, ["Memory", "memory", "ram", "RAM", "physical_memory"]),
-    buildVersion: extractXmlValue(xmlText, ["BuildVersion", "build_version", "version", "GameVersion"]),
-    systemModel: extractXmlValue(xmlText, ["SystemModel", "system_model", "device_model", "model"]),
-    osVersion: extractXmlValue(xmlText, ["OSVersion", "os_version", "operating_system", "platform"]),
-  };
-}
-
-// 对日志做粗粒度严重级分类，便于快速排查。
-function detectSeverity(logText) {
-  if (!logText) return "普通严重级";
-  if (/\berror\b/i.test(logText)) return "高严重级";
-  if (/\bwarning\b/i.test(logText) || /\bwarn\b/i.test(logText)) return "中严重级";
-  return "普通严重级";
-}
-
-// 限制日志摘录和 markdown 内容长度，避免报告过大。
-function truncateText(value, maxLength) {
-  const text = String(value || "");
-  if (text.length <= maxLength) return text;
-  return `${text.slice(0, maxLength)}\n\n[truncated]`;
-}
-
-// 在去重和比对前先清洗噪声日志行。
-function normalizeLogLineForComparison(line) {
-  return String(line || "")
-    .replace(/\0/g, "")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-// 识别更像真实错误的日志行，过滤掉泛化噪声。
-function isErrorLikeLogLine(line) {
-  const text = normalizeLogLineForComparison(line);
-  if (!text) {
-    return false;
-  }
-  return /\b(error|fatal|exception|assert|ensure|crash|fail(?:ed|ure)?)\b/i.test(text);
-}
-
-// 对一个 fingerprint 家族下所有对象的疑似错误行做聚合和去重。
-function buildErrorLineDigest(downloadedItems, contexts) {
-  const lineMap = new Map();
-
-  contexts.forEach((context, index) => {
-    const objectId = downloadedItems[index]?.objectIdHex || "";
-    const lines = String(context?.logText || "").split(/\r?\n/);
-    lines.forEach((rawLine, lineIndex) => {
-      // 先过滤掉不具备错误特征的日志行，避免摘要被普通日志淹没。
-      if (!isErrorLikeLogLine(rawLine)) {
-        return;
-      }
-      const normalizedLine = normalizeLogLineForComparison(rawLine);
-      if (!normalizedLine) {
-        return;
-      }
-      if (!lineMap.has(normalizedLine)) {
-        // 同一条归一化后的错误行只保留一份聚合记录。
-        lineMap.set(normalizedLine, {
-          line: normalizedLine,
-          count: 0,
-          objectIds: new Set(),
-          samples: [],
-          firstSeenAt: {
-            objectId,
-            lineNumber: lineIndex + 1,
-          },
-        });
-      }
-      const entry = lineMap.get(normalizedLine);
-      entry.count += 1;
-      if (objectId) {
-        entry.objectIds.add(objectId);
-      }
-      // 样本行只保留少量原始文本，方便摘要里展示代表性原文。
-      const sampleLine = String(rawLine || "").trim();
-      if (sampleLine && entry.samples.length < 3 && !entry.samples.includes(sampleLine)) {
-        entry.samples.push(sampleLine);
-      }
-    });
-  });
-
-  const entries = Array.from(lineMap.values())
-    .map((entry) => ({
-      line: entry.line,
-      count: entry.count,
-      objectCount: entry.objectIds.size,
-      objectIds: Array.from(entry.objectIds).sort((a, b) => a.localeCompare(b)),
-      samples: entry.samples,
-      firstSeenAt: entry.firstSeenAt,
-    }))
-    // 先按出现次数排序，再按覆盖对象数排序，最后按文本稳定排序。
-    .sort((left, right) => right.count - left.count || right.objectCount - left.objectCount || left.line.localeCompare(right.line));
-
-  return {
-    totalUniqueLines: entries.length,
-    totalMatchedLines: entries.reduce((sum, entry) => sum + entry.count, 0),
-    entries,
-  };
-}
-
-// 把聚合后的错误行摘要渲染成 markdown 文件内容。
-function formatErrorLineDigestMarkdown(fingerprint, digest) {
-  const lines = [
-    `# Fingerprint Error Line Summary ${fingerprint}`,
-    "",
-    `- Generated At: ${new Date().toISOString()}`,
-    `- Unique Error Lines: ${digest.totalUniqueLines}`,
-    `- Total Matched Error Lines: ${digest.totalMatchedLines}`,
-    "",
-    "## Deduplicated Error Lines",
-    "",
-  ];
-
-  if (digest.entries.length === 0) {
-    lines.push("No error-like log lines found.");
-    lines.push("");
-    return lines.join("\n");
-  }
-
-  digest.entries.forEach((entry, index) => {
-    lines.push(`${index + 1}. Count: ${entry.count} | Objects: ${entry.objectCount}`);
-    lines.push(`   Line: ${entry.line}`);
-    if (entry.objectIds.length > 0) {
-      lines.push(`   Object IDs: ${entry.objectIds.join(", ")}`);
-    }
-    if (entry.firstSeenAt?.objectId) {
-      lines.push(`   First Seen: ${entry.firstSeenAt.objectId}:${entry.firstSeenAt.lineNumber}`);
-    }
-    lines.push("");
-  });
-
-  return lines.join("\n");
-}
-
-
-// 给 CLI 用户输出简洁列表视图，只展示匹配对象的关键信息。
-function printList(items, meta) {
-  console.log(`Time range: ${meta.from} ~ ${meta.to}`);
-  console.log(`Total rows: ${meta.totalRows}`);
-  console.log(`Fetched rows: ${meta.totalListed}`);
-  console.log(`Objects: ${meta.objectCount}`);
-  console.log(`Optimized page limit: ${meta.pageLimit}`);
-  console.log("");
-
-  if (items.length === 0) {
-    console.log("No results found.");
-    return;
-  }
-
-  const rows = items.map((item, idx) => {
-    const hasObjectId = Boolean(item.objectIdHex);
-    if (!hasObjectId) {
-      return {
-        "#": idx + 1,
-        fingerprint: item.values.fingerprint || "",
-        firstSeen: item.values["fingerprint;first_seen"] || "",
-        issueState: item.values["fingerprint;issues;state"] || "",
-        errorMessage: item.values["error.message"] || "",
-        classifiers: item.values.classifiers || "",
-      };
-    }
-    return {
-      "#": idx + 1,
-      objectId: item.objectIdHex,
-      fingerprint: item.values.fingerprint || "",
-      count: item.values._count ?? "",
-    };
-  });
-  console.table(rows);
-}
-
-// 读取分析所需的本地文件，并提取 runtime 和日志片段。
-async function collectAnalysisContext(downloadedItem) {
-  // 运行时 XML 和主日志文件是后续分析最关键的两类输入。
-  const runtimeXmlFile = downloadedItem.downloadedFiles.find((file) => file.name.toLowerCase() === "crashcontext.runtime-xml");
-  const logFile = downloadedItem.downloadedFiles.find((file) => file.name.toLowerCase().endsWith(".log") || file.content_type === "text/plain" || file.contentType === "text/plain");
-
-  const runtimeXmlText = runtimeXmlFile ? await fs.readFile(runtimeXmlFile.savedPath, "utf8") : "";
-  const logText = logFile ? await fs.readFile(logFile.savedPath, "utf8") : "";
-  const environmentInfo = runtimeXmlText ? parseRuntimeXml(runtimeXmlText) : {};
-  const severity = detectSeverity(logText);
-
-  logStep("analysis", "local context prepared", {
-    objectId: downloadedItem.objectIdHex,
-    runtimeXmlFile: runtimeXmlFile?.savedPath || null,
-    logFile: logFile?.savedPath || null,
-    severity,
-  });
-
-  return { runtimeXmlText, logText, environmentInfo, severity };
-}
-
-// 持久化 fingerprint 级错误摘要，供后续查看和批量提示词使用。
-async function writeErrorLineDigestReport(fingerprint, options, errorLineDigest) {
-  const reportDir = getFingerprintReportsRoot(options.storageDir, fingerprint);
-  await ensureDirectory(reportDir);
-  const summaryPath = path.join(reportDir, "error-line-summary.md");
-  const jsonPath = path.join(reportDir, "error-line-summary.json");
-  await fs.writeFile(summaryPath, formatErrorLineDigestMarkdown(fingerprint, errorLineDigest), "utf8");
-  await fs.writeFile(jsonPath, JSON.stringify(errorLineDigest, null, 2), "utf8");
-  logStep("report", "error line digest written", { summaryPath, jsonPath });
-  return { summaryPath, jsonPath };
-}
-
-// 枚举某个 fingerprint 家族下本地已下载的对象目录。
-async function listLocalDownloadedItems(storageDir, fingerprint) {
-  const logsDir = getFingerprintLogsRoot(storageDir, fingerprint);
-  const entries = await fs.readdir(logsDir, { withFileTypes: true }).catch(() => []);
-  const directories = entries
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort((a, b) => a.localeCompare(b));
-
-  const items = [];
-  for (const objectIdHex of directories) {
-    /* eslint-disable no-await-in-loop */
-    const targetDir = path.join(logsDir, objectIdHex);
-    const files = await fs.readdir(targetDir, { withFileTypes: true }).catch(() => []);
-    const downloadedFiles = [];
-    for (const entry of files) {
-      if (!entry.isFile()) {
-        continue;
-      }
-      // 从本地磁盘重建与在线下载阶段相同的 downloadedFiles 结构。
-      const savedPath = path.join(targetDir, entry.name);
-      const stats = await fs.stat(savedPath).catch(() => null);
-      const contentType = inferContentType(entry.name);
-      downloadedFiles.push({
-        name: entry.name,
-        savedPath,
-        size: stats?.size || 0,
-        contentType,
-        content_type: contentType,
-      });
-    }
-    items.push({
-      objectIdHex,
-      fingerprint,
-      values: { fingerprint },
-      targetDir,
-      downloadedFiles,
-    });
-    /* eslint-enable no-await-in-loop */
-  }
-
-  return items;
-}
-
-// 重新加载本地崩溃上下文，使分析可以脱离 Backtrace 远端查询单独运行。
-async function loadFingerprintContexts(options) {
-  const fingerprint = normalizeFingerprint(options.fingerprint);
-  const downloadedItems = await listLocalDownloadedItems(options.storageDir, fingerprint);
-  if (downloadedItems.length === 0) {
-    throw new Error(`No downloaded logs found for fingerprint: ${fingerprint}`);
-  }
-
-  const contexts = [];
-  // 逐个恢复上下文，保证后续本地分析复用和远端流程同样的数据结构。
-  for (const downloadedItem of downloadedItems) {
-    /* eslint-disable no-await-in-loop */
-    contexts.push(await collectAnalysisContext(downloadedItem));
-    /* eslint-enable no-await-in-loop */
-  }
-
-  const sharedQuerySummary = {
-    totalRows: downloadedItems.length,
-    fetchedRows: downloadedItems.length,
-    objectCount: downloadedItems.length,
-    pageLimit: downloadedItems.length,
-    objectIds: downloadedItems.map((item) => item.objectIdHex),
-    selectedValues: downloadedItems.map((item) => item.values),
-  };
-
-  return { fingerprint, downloadedItems, contexts, sharedQuerySummary };
-}
-
-// 只基于本地存储重新计算 fingerprint 级错误行摘要。
-async function summarizeFingerprintErrorLines(options) {
-  const loaded = await loadFingerprintContexts(options);
-  const errorLineDigest = buildErrorLineDigest(loaded.downloadedItems, loaded.contexts);
-  const errorLineDigestPaths = await writeErrorLineDigestReport(loaded.fingerprint, options, errorLineDigest);
-  return {
-    command: options.command,
-    options,
-    fingerprint: loaded.fingerprint,
-    querySummary: loaded.sharedQuerySummary,
-    downloadedItems: loaded.downloadedItems,
-    contexts: loaded.contexts,
-    errorLineDigest,
-    errorLineDigestPaths,
-  };
-}
-
-module.exports = {
-  decodeXmlEntities,
-  extractXmlValue,
-  parseRuntimeXml,
-  detectSeverity,
-  truncateText,
-  normalizeLogLineForComparison,
-  isErrorLikeLogLine,
-  buildErrorLineDigest,
-  formatErrorLineDigestMarkdown,
-  printList,
-  collectAnalysisContext,
-  writeErrorLineDigestReport,
-  listLocalDownloadedItems,
-  loadFingerprintContexts,
-  summarizeFingerprintErrorLines,
-};

package/lib/backtrace/constants.js

@@ -1,23 +0,0 @@
-const DEFAULT_QUERY_URL = process.env.BACKTRACE_QUERY_URL || process.env.BACKTRACE_BASE_URL || "https://apesquared.sp.backtrace.io";
-const DEFAULT_BACKTRACE_PROJECT = process.env.BACKTRACE_PROJECT || "AboveLand";
-const DEFAULT_BACKTRACE_FORMAT = process.env.BACKTRACE_FORMAT || "json";
-const DEFAULT_WORKDIR = process.env.BACKTRACE_WORKDIR || process.cwd();
-const DEFAULT_PROXY = process.env.BACKTRACE_PROXY || "";
-const DEFAULT_SELECT = ["fingerprint"];
-const DEFAULT_LIMIT = Number(process.env.BACKTRACE_LIMIT || 20);
-const DEFAULT_DOWNLOAD_CONCURRENCY = Number(process.env.BACKTRACE_DOWNLOAD_CONCURRENCY || 4);
-const DEFAULT_RETRIES = Number(process.env.BACKTRACE_RETRIES || 0);
-const DEFAULT_STORAGE_DIR = process.env.BACKTRACE_STORAGE_DIR || "fingerprints";
-
-module.exports = {
-  DEFAULT_QUERY_URL,
-  DEFAULT_BACKTRACE_PROJECT,
-  DEFAULT_BACKTRACE_FORMAT,
-  DEFAULT_WORKDIR,
-  DEFAULT_PROXY,
-  DEFAULT_SELECT,
-  DEFAULT_LIMIT,
-  DEFAULT_DOWNLOAD_CONCURRENCY,
-  DEFAULT_RETRIES,
-  DEFAULT_STORAGE_DIR,
-};

package/lib/backtrace/options.js

@@ -1,278 +0,0 @@
-const path = require("node:path");
-const {
-  DEFAULT_QUERY_URL,
-  DEFAULT_BACKTRACE_PROJECT,
-  DEFAULT_BACKTRACE_FORMAT,
-  DEFAULT_WORKDIR,
-  DEFAULT_PROXY,
-  DEFAULT_SELECT,
-  DEFAULT_LIMIT,
-  DEFAULT_DOWNLOAD_CONCURRENCY,
-  DEFAULT_RETRIES,
-  DEFAULT_STORAGE_DIR,
-} = require("./constants");
-const { nowRange, formatBatchName } = require("./utils");
-
-function normalizeBacktraceQueryUrl(value) {
-  const rawValue = String(value || "").trim();
-  const fallbackUrl = new URL(DEFAULT_QUERY_URL);
-  const url = rawValue ? new URL(rawValue) : new URL(DEFAULT_QUERY_URL);
-  if (!url.pathname || url.pathname === "/") {
-    url.pathname = "/api/query";
-  }
-  if (!url.searchParams.get("project")) {
-    url.searchParams.set("project", process.env.BACKTRACE_PROJECT || DEFAULT_BACKTRACE_PROJECT);
-  }
-  if (!url.searchParams.get("format")) {
-    url.searchParams.set("format", process.env.BACKTRACE_FORMAT || DEFAULT_BACKTRACE_FORMAT);
-  }
-  if (!url.searchParams.get("token") && fallbackUrl.searchParams.get("token")) {
-    url.searchParams.set("token", fallbackUrl.searchParams.get("token"));
-  }
-  return url.toString();
-}
-
-function normalizeOptionalInteger(value, fallback) {
-  if (value === undefined || value === null || value === "") {
-    return fallback;
-  }
-  return Number(value);
-}
-
-// 顶层工具只暴露固定命令集合，便于尽早做参数校验。
-const SUPPORTED_COMMANDS = ["list", "fingerprint", "collect-all", "summarize-fingerprint-errors"];
-
-// 输出旧入口 codex_demo.js 和库调用共用的帮助信息。
-function printUsage() {
-  console.log(
-    [
-      "Usage:",
-      "  backtrace <command> [options]",
-      "",
-      "Commands:",
-      "  list                          list local fingerprint directories and meta information",
-      "  fingerprint                   query all grouped fingerprints and print them",
-      "  collect-all                   download all objects only, do not generate reports",
-      "  summarize-fingerprint-errors  summarize and deduplicate error lines for one local fingerprint directory",
-      "  fix-plan                      generate a repair plan from the smallest AboveLand.LOG under one fingerprint",
-      "",
-      "Environment:",
-      "  BACKTRACE_USERNAME     required Backtrace console login username",
-      "  BACKTRACE_PASSWORD     required Backtrace console login password",
-      `  BACKTRACE_PROJECT      default: ${DEFAULT_BACKTRACE_PROJECT}`,
-      `  BACKTRACE_FORMAT       default: ${DEFAULT_BACKTRACE_FORMAT}`,
-      "",
-      "Options:",
-      `  --query-url <url>      default base url: ${DEFAULT_QUERY_URL}`,
-      `  --workdir <dir>        default: ${DEFAULT_WORKDIR}`,
-      "  --fingerprint <value[,value2,...]>  optional query filter; collect supports multiple values",
-      "  --from <unixTs>        default: 1",
-      "  --to <unixTs>          default: now",
-      `  --limit <n>            default: ${DEFAULT_LIMIT}`,
-      "  --offset <n>           default: 0",
-      `  --select <a,b,c>       default: ${DEFAULT_SELECT.join(",")}`,
-      `  --proxy <url>          default: ${DEFAULT_PROXY}`,
-      `  --retries <n>          default: ${DEFAULT_RETRIES} (0 means infinite retry)`,
-      `  --download-concurrency <n> default: ${DEFAULT_DOWNLOAD_CONCURRENCY}`,
-      "  --storage-dir <dir>    default: ./fingerprints",
-      "  --report-dir <dir>     deprecated alias of --storage-dir",
-      "  --logs-dir <dir>       deprecated alias of --storage-dir",
-      "  --help                 show this message",
-    ].join("\n"),
-  );
-}
-
-// 对标准化选项做一次集中校验，
-// 后续流程就可以默认命令前置条件和数值范围都已成立。
-function validateOptions(options) {
-  if (!SUPPORTED_COMMANDS.includes(options.command)) {
-    throw new Error(`Command must be one of: ${SUPPORTED_COMMANDS.join(", ")}`);
-  }
-  if (options.command === "summarize-fingerprint-errors" && !options.fingerprint) {
-    throw new Error("--fingerprint is required for summarize-fingerprint-errors");
-  }
-  if (!["list", "summarize-fingerprint-errors"].includes(options.command) && (!options.username || !options.password)) {
-    throw new Error("BACKTRACE_USERNAME and BACKTRACE_PASSWORD are required");
-  }
-  if (!Number.isInteger(options.limit) || options.limit <= 0) {
-    throw new Error("--limit must be a positive integer");
-  }
-  if (!Number.isInteger(options.offset) || options.offset < 0) {
-    throw new Error("--offset must be a non-negative integer");
-  }
-  if (!Number.isInteger(options.retries) || options.retries < 0) {
-    throw new Error("--retries must be a non-negative integer; use 0 for infinite retry");
-  }
-  if (!Number.isInteger(options.downloadConcurrency) || options.downloadConcurrency <= 0) {
-    throw new Error("--download-concurrency must be a positive integer");
-  }
-  if (options.select.length === 0) {
-    throw new Error("--select must contain at least one field");
-  }
-  return options;
-}
-
-// 把旧版 Node 入口传入的 argv 解析为已校验的运行时选项。
-function parseArgs(argv) {
-  const range = nowRange();
-  const batchName = formatBatchName(new Date());
-  // 这里先填满默认值，后续只覆盖用户显式传入的字段。
-  const options = {
-    command: "",
-    queryUrl: normalizeBacktraceQueryUrl(DEFAULT_QUERY_URL),
-    workdir: DEFAULT_WORKDIR,
-    objectId: "",
-    fingerprint: "",
-    from: range.from,
-    to: range.to,
-    limit: DEFAULT_LIMIT,
-    offset: 0,
-    select: [...DEFAULT_SELECT],
-    proxy: DEFAULT_PROXY,
-    retries: DEFAULT_RETRIES,
-    downloadConcurrency: DEFAULT_DOWNLOAD_CONCURRENCY,
-    batchName,
-    storageDir: path.resolve(DEFAULT_STORAGE_DIR),
-    reportDir: path.resolve(DEFAULT_STORAGE_DIR),
-    logsDir: path.resolve(DEFAULT_STORAGE_DIR),
-    username: process.env.BACKTRACE_USERNAME || "",
-    password: process.env.BACKTRACE_PASSWORD || "",
-  };
-
-  let index = 0;
-  if (argv[0] && !argv[0].startsWith("-")) {
-    // 第一个非 flag 参数视为主命令。
-    options.command = argv[0];
-    index = 1;
-  }
-
-  // 按顺序解析参数，因为这里采用的是简单的成对参数约定。
-  for (; index < argv.length; index += 1) {
-    const arg = argv[index];
-
-    if (arg === "--query-url") {
-      options.queryUrl = argv[index + 1] || "";
-      index += 1;
-      continue;
-    }
-    if (arg === "--workdir") {
-      options.workdir = argv[index + 1] || "";
-      index += 1;
-      continue;
-    }
-    if (arg === "--object-id") {
-      options.objectId = argv[index + 1] || "";
-      index += 1;
-      continue;
-    }
-    if (arg === "--fingerprint") {
-      options.fingerprint = argv[index + 1] || "";
-      index += 1;
-      continue;
-    }
-    if (arg === "--from") {
-      options.from = argv[index + 1] || options.from;
-      index += 1;
-      continue;
-    }
-    if (arg === "--to") {
-      options.to = argv[index + 1] || options.to;
-      index += 1;
-      continue;
-    }
-    if (arg === "--limit") {
-      options.limit = Number(argv[index + 1] || String(DEFAULT_LIMIT));
-      index += 1;
-      continue;
-    }
-    if (arg === "--offset") {
-      options.offset = Number(argv[index + 1] || "0");
-      index += 1;
-      continue;
-    }
-    if (arg === "--select") {
-      options.select = (argv[index + 1] || DEFAULT_SELECT.join(","))
-        .split(",")
-        .map((item) => item.trim())
-        .filter(Boolean);
-      index += 1;
-      continue;
-    }
-    if (arg === "--proxy") {
-      options.proxy = argv[index + 1] || "";
-      index += 1;
-      continue;
-    }
-    if (arg === "--retries") {
-      options.retries = Number(argv[index + 1] || String(DEFAULT_RETRIES));
-      index += 1;
-      continue;
-    }
-    if (arg === "--download-concurrency") {
-      options.downloadConcurrency = Number(argv[index + 1] || String(DEFAULT_DOWNLOAD_CONCURRENCY));
-      index += 1;
-      continue;
-    }
-    if (arg === "--storage-dir" || arg === "--report-dir" || arg === "--logs-dir") {
-      options.storageDir = path.resolve(argv[index + 1] || DEFAULT_STORAGE_DIR);
-      options.reportDir = options.storageDir;
-      options.logsDir = options.storageDir;
-      index += 1;
-      continue;
-    }
-    if (arg === "--help" || arg === "-h") {
-      printUsage();
-      process.exit(0);
-    }
-  }
-
-  options.queryUrl = normalizeBacktraceQueryUrl(options.queryUrl || DEFAULT_QUERY_URL);
-  options.proxy = String(options.proxy || DEFAULT_PROXY || "").trim();
-
-  return validateOptions(options);
-}
-
-// 给直接调用库的场景构造选项，跳过原始 argv 解析。
-function createOptions(overrides = {}) {
-  const range = nowRange();
-  const batchName = overrides.batchName || formatBatchName(new Date());
-  // 支持调用方直接传数组，也支持传逗号分隔字符串。
-  const selectValue = Array.isArray(overrides.select)
-    ? overrides.select
-    : String(overrides.select || DEFAULT_SELECT.join(","))
-      .split(",")
-      .map((item) => item.trim())
-      .filter(Boolean);
-
-  const options = {
-    command: overrides.command || "",
-    queryUrl: normalizeBacktraceQueryUrl(overrides.queryUrl || DEFAULT_QUERY_URL),
-    workdir: overrides.workdir || DEFAULT_WORKDIR,
-    objectId: overrides.objectId ? String(overrides.objectId) : "",
-    fingerprint: overrides.fingerprint ? String(overrides.fingerprint) : "",
-    from: String(overrides.from || range.from),
-    to: String(overrides.to || range.to),
-    limit: normalizeOptionalInteger(overrides.limit, DEFAULT_LIMIT),
-    offset: normalizeOptionalInteger(overrides.offset, 0),
-    select: selectValue.length > 0 ? selectValue : [...DEFAULT_SELECT],
-    proxy: String(overrides.proxy || DEFAULT_PROXY || "").trim(),
-    retries: normalizeOptionalInteger(overrides.retries, DEFAULT_RETRIES),
-    downloadConcurrency: normalizeOptionalInteger(overrides.downloadConcurrency, DEFAULT_DOWNLOAD_CONCURRENCY),
-    batchName,
-    storageDir: path.resolve(overrides.storageDir || overrides.reportDir || overrides.logsDir || DEFAULT_STORAGE_DIR),
-    reportDir: path.resolve(overrides.storageDir || overrides.reportDir || overrides.logsDir || DEFAULT_STORAGE_DIR),
-    logsDir: path.resolve(overrides.storageDir || overrides.reportDir || overrides.logsDir || DEFAULT_STORAGE_DIR),
-    username: overrides.username || process.env.BACKTRACE_USERNAME || "",
-    password: overrides.password || process.env.BACKTRACE_PASSWORD || "",
-  };
-
-  return validateOptions(options);
-}
-
-module.exports = {
-  SUPPORTED_COMMANDS,
-  printUsage,
-  parseArgs,
-  createOptions,
-  validateOptions,
-};