backtrace-console 0.0.1

package/README.md

@@ -0,0 +1,22 @@
+# backtrace-console
+
+CLI for querying Backtrace fingerprints, collecting artifacts, and generating repair plans.
+
+## Install
+
+```bash
+npm install -g backtrace-console
+```
+
+## Commands
+
+```bash
+backtrace list
+backtrace fingerprint --fingerprint <value>
+backtrace collect --fingerprint <value>
+backtrace summarize-errors --fingerprint <value>
+backtrace fix-plan --fingerprint <value>
+backtrace apply-fix --fingerprint <value>
+```
+
+Run `backtrace --help` for the full option list.

package/app.js

@@ -0,0 +1,22 @@
+var express = require('express');
+var path = require('path');
+var cookieParser = require('cookie-parser');
+var logger = require('morgan');
+
+var indexRouter = require('./routes/index');
+var usersRouter = require('./routes/users');
+var backtraceRouter = require('./routes/backtrace');
+
+var app = express();
+
+app.use(logger('dev'));
+app.use(express.json());
+app.use(express.urlencoded({ extended: false }));
+app.use(cookieParser());
+app.use(express.static(path.join(__dirname, 'public')));
+
+app.use('/', indexRouter);
+app.use('/users', usersRouter);
+app.use('/api/backtrace', backtraceRouter);
+
+module.exports = app;

package/bin/backtrace-cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+require("dotenv").config();
+
+const { parseCliArgs, printCliUsage } = require("../lib/cli/args");
+const { runCliCommand } = require("../lib/cli/run");
+
+async function main() {
+  const parsed = parseCliArgs(process.argv.slice(2));
+  if (parsed.help) {
+    printCliUsage();
+    return;
+  }
+  await runCliCommand(parsed.options);
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error("backtrace-cli failed:");
+  console.error(error instanceof Error ? error.stack || error.message : error);
+  process.exit(1);
+});

package/bin/www

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+/**
+ * Module dependencies.
+ */
+
+var app = require('../app');
+var debug = require('debug')('backtrace-console:server');
+var http = require('http');
+
+/**
+ * Get port from environment and store in Express.
+ */
+
+var port = normalizePort(process.env.PORT || '3000');
+app.set('port', port);
+
+/**
+ * Create HTTP server.
+ */
+
+var server = http.createServer(app);
+
+/**
+ * Listen on provided port, on all network interfaces.
+ */
+
+server.listen(port);
+server.on('error', onError);
+server.on('listening', onListening);
+
+/**
+ * Normalize a port into a number, string, or false.
+ */
+
+function normalizePort(val) {
+  var port = parseInt(val, 10);
+
+  if (isNaN(port)) {
+    // named pipe
+    return val;
+  }
+
+  if (port >= 0) {
+    // port number
+    return port;
+  }
+
+  return false;
+}
+
+/**
+ * Event listener for HTTP server "error" event.
+ */
+
+function onError(error) {
+  if (error.syscall !== 'listen') {
+    throw error;
+  }
+
+  var bind = typeof port === 'string'
+    ? 'Pipe ' + port
+    : 'Port ' + port;
+
+  // handle specific listen errors with friendly messages
+  switch (error.code) {
+    case 'EACCES':
+      console.error(bind + ' requires elevated privileges');
+      process.exit(1);
+      break;
+    case 'EADDRINUSE':
+      console.error(bind + ' is already in use');
+      process.exit(1);
+      break;
+    default:
+      throw error;
+  }
+}
+
+/**
+ * Event listener for HTTP server "listening" event.
+ */
+
+function onListening() {
+  var addr = server.address();
+  var bind = typeof addr === 'string'
+    ? 'pipe ' + addr
+    : 'port ' + addr.port;
+  debug('Listening on ' + bind);
+}

package/lib/BacktraceCodexTool.js

@@ -0,0 +1,32 @@
+// 保留历史导入入口，实际能力全部委托给
+// lib/backtrace 和 lib/analysis 下的新模块实现。
+const {
+  DEFAULT_QUERY_URL,
+  DEFAULT_WORKDIR,
+  DEFAULT_PROXY,
+  DEFAULT_SELECT,
+  DEFAULT_LIMIT,
+  DEFAULT_DOWNLOAD_CONCURRENCY,
+  DEFAULT_RETRIES,
+  DEFAULT_STORAGE_DIR,
+} = require("./backtrace/constants");
+const { printUsage, parseArgs, createOptions } = require("./backtrace/options");
+const { printList } = require("./backtrace/analysis");
+const { BacktraceCodexTool, runBacktraceCommand } = require("./backtrace/tool");
+
+module.exports = {
+  BacktraceCodexTool,
+  runBacktraceCommand,
+  createOptions,
+  parseArgs,
+  printUsage,
+  printList,
+  DEFAULT_QUERY_URL,
+  DEFAULT_WORKDIR,
+  DEFAULT_PROXY,
+  DEFAULT_SELECT,
+  DEFAULT_LIMIT,
+  DEFAULT_DOWNLOAD_CONCURRENCY,
+  DEFAULT_RETRIES,
+  DEFAULT_STORAGE_DIR,
+};

package/lib/backtrace/analysis.js

@@ -0,0 +1,356 @@
+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

@@ -0,0 +1,23 @@
+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,
+};