backtrace-console 0.0.1

package/lib/backtrace/query.js

@@ -0,0 +1,940 @@
+const fs = require("node:fs/promises");
+const fsNative = require("node:fs");
+const path = require("node:path");
+const {
+  logStep,
+  retry,
+  ensureDirectory,
+  normalizeFingerprint,
+  getFingerprintLogsRoot,
+} = require("./utils");
+
+let undiciModule = null;
+
+const FINGERPRINT_GROUP_FIELDS = ["fingerprint"];
+const FINGERPRINT_GROUP_FOLD = {
+  "error.message": [["head"]],
+  classifiers: [["head"]],
+  "fingerprint;first_seen": [["head"]],
+  "fingerprint;issues;state": [["head"]],
+};
+const FINGERPRINT_GROUP_ORDER = [{ name: "fingerprint;first_seen;0", ordering: "descending" }];
+
+function getUndici() {
+  if (!undiciModule) {
+    undiciModule = require("undici");
+  }
+  return undiciModule;
+}
+
+function createProxyDispatcher(proxyUrl) {
+  const normalizedProxy = String(proxyUrl || "").trim();
+  if (!normalizedProxy) {
+    return null;
+  }
+  try {
+    const { ProxyAgent } = getUndici();
+    return new ProxyAgent(normalizedProxy);
+  } catch (error) {
+    throw new Error(`Proxy support requires dependency "undici": ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function withDispatcher(options, dispatcher) {
+  if (!dispatcher) {
+    return options || {};
+  }
+  return { ...(options || {}), dispatcher };
+}
+
+function shouldUseFingerprintGroupQuery(options) {
+  return options.command === "fingerprint";
+}
+
+function getRequestedFingerprints(options) {
+  return String(options?.fingerprint || "")
+    .split(",")
+    .map((item) => String(item || "").trim())
+    .filter(Boolean);
+}
+
+// Backtrace 查询与下载辅助函数，
+// 负责把本地选项转换成 HTTP 请求和磁盘文件产物。
+function buildQueryBody(options, offset, limit) {
+  // 时间范围过滤始终生效；fingerprint 过滤只有在用户显式传入时才附加。
+  const filter = {
+    timestamp: [["at-most", String(options.to)], ["at-least", String(options.from)]],
+  };
+  if (options.fingerprint) {
+    filter.fingerprint = [["contains", String(options.fingerprint)]];
+  }
+  if (shouldUseFingerprintGroupQuery(options)) {
+    return {
+      group: FINGERPRINT_GROUP_FIELDS,
+      fold: FINGERPRINT_GROUP_FOLD,
+      order: FINGERPRINT_GROUP_ORDER,
+      offset,
+      limit,
+      filter: [filter],
+    };
+  }
+  return {
+    select: options.select,
+    order: [{ name: "timestamp", ordering: "descending" }],
+    offset,
+    limit,
+    filter: [filter],
+  };
+}
+
+function buildFingerprintGroupQueryBody(options, offset, limit, fingerprintFilter) {
+  const filter = {
+    timestamp: [["at-most", String(options.to)], ["at-least", String(options.from)]],
+  };
+  if (fingerprintFilter) {
+    filter.fingerprint = [["contains", String(fingerprintFilter)]];
+  }
+  return {
+    group: FINGERPRINT_GROUP_FIELDS,
+    fold: FINGERPRINT_GROUP_FOLD,
+    order: FINGERPRINT_GROUP_ORDER,
+    offset,
+    limit,
+    filter: [filter],
+  };
+}
+
+function buildCompressedFingerprintQueryBody(options, fingerprint) {
+  return {
+    select: ["_compressed"],
+    order: [{ name: "timestamp", ordering: "descending" }],
+    offset: 0,
+    limit: 1,
+    filter: [{
+      fingerprint: [["contains", String(fingerprint)]],
+      timestamp: [["at-most", String(options.to)], ["at-least", String(options.from)]],
+    }],
+  };
+}
+
+function buildFingerprintObjectsQueryBody(options, fingerprint, offset, limit) {
+  return {
+    select: ["timestamp"],
+    order: [{ name: "timestamp", ordering: "descending" }],
+    offset,
+    limit,
+    filter: [{
+      fingerprint: [["contains", String(fingerprint)]],
+      timestamp: [["at-most", String(options.to)], ["at-least", String(options.from)]],
+    }],
+  };
+}
+
+// 复用原始主机地址，只切换到相邻的 API 路径。
+function buildSiblingUrl(sourceUrl, pathname) {
+  const url = new URL(sourceUrl);
+  url.pathname = pathname;
+  return url;
+}
+
+// 登录接口与查询接口共用同一个 Backtrace 主机。
+function buildLoginUrl(queryUrl) {
+  const url = new URL(queryUrl);
+  url.pathname = "/api/login";
+  url.search = "";
+  return url.toString();
+}
+
+// 登录后的请求会把静态 token 替换成会话 token。
+function withSessionToken(urlString, sessionToken) {
+  const url = new URL(urlString);
+  url.searchParams.set("token", sessionToken);
+  return url;
+}
+
+// 把 object id 统一规范成小写十六进制字符串。
+function toHexObjectId(value) {
+  if (typeof value === "string" && /^[0-9a-f]+$/i.test(value)) {
+    return value.toLowerCase();
+  }
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return String(value);
+  }
+  return numeric.toString(16);
+}
+
+// 从 Backtrace 查询结果中提取 object id 列表。
+function extractObjectIds(objects) {
+  if (!Array.isArray(objects) || objects.length === 0) {
+    return [];
+  }
+  const values = [];
+  objects.forEach((group) => {
+    const [, rows] = group || [];
+    if (!Array.isArray(rows)) {
+      return;
+    }
+    rows.forEach((row) => {
+      const value = Array.isArray(row) ? row[0] : null;
+      if (value !== null && value !== undefined) {
+        values.push(value);
+      }
+    });
+  });
+  return values;
+}
+
+// 把 Backtrace 按列组织的值数组转换成按行组织的对象值。
+function extractSelectedValues(values, selectFields) {
+  if (!Array.isArray(values) || values.length === 0) {
+    return [];
+  }
+  const [, ...entries] = values[0];
+  return entries.map((entry) => {
+    const row = {};
+    selectFields.forEach((field, index) => {
+      row[field] = Array.isArray(entry) ? entry[index] : undefined;
+    });
+    if (Array.isArray(entry) && entry.length > selectFields.length) {
+      row._count = entry[entry.length - 1];
+    }
+    return row;
+  });
+}
+
+// 把 object id 和选中字段拼成更易用的单条对象结构。
+function mapResultsToItems(objectIds, selectedValues) {
+  return objectIds.map((objectId, index) => ({
+    index: index + 1,
+    objectIdDecimal: objectId,
+    objectIdHex: toHexObjectId(objectId),
+    values: selectedValues[index] || {},
+  }));
+}
+
+// 对较大的结果集使用更大的分页大小，减少请求往返次数。
+function optimizeLimit(totalRows, baseLimit) {
+  if (totalRows <= baseLimit) return baseLimit;
+  if (totalRows <= 100) return 50;
+  if (totalRows <= 500) return 100;
+  return 200;
+}
+
+function formatBytes(bytes) {
+  const value = Number(bytes || 0);
+  if (value >= 1024 * 1024) {
+    return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+  }
+  if (value >= 1024) {
+    return `${(value / 1024).toFixed(1)} KB`;
+  }
+  return `${value} B`;
+}
+
+function formatAttachmentSpeed(bytes, elapsedMs) {
+  if (!elapsedMs || elapsedMs <= 0 || !bytes) {
+    return "0 B/s";
+  }
+  const bytesPerSecond = bytes / (elapsedMs / 1000);
+  if (bytesPerSecond >= 1024 * 1024) {
+    return `${(bytesPerSecond / (1024 * 1024)).toFixed(1)} MB/s`;
+  }
+  if (bytesPerSecond >= 1024) {
+    return `${(bytesPerSecond / 1024).toFixed(1)} KB/s`;
+  }
+  return `${Math.max(0, Math.round(bytesPerSecond))} B/s`;
+}
+
+function formatAttachmentProgress(downloadedBytes, totalBytes) {
+  if (!totalBytes || totalBytes <= 0) {
+    return "";
+  }
+  return `${Math.min(100, Math.round((downloadedBytes / totalBytes) * 100))}%`;
+}
+
+function formatAttachmentStatus(downloadedBytes, totalBytes, elapsedMs) {
+  const progress = formatAttachmentProgress(downloadedBytes, totalBytes);
+  const transferred = totalBytes > 0
+    ? `${formatBytes(downloadedBytes)}/${formatBytes(totalBytes)}`
+    : formatBytes(downloadedBytes);
+  return [progress, transferred, formatAttachmentSpeed(downloadedBytes, elapsedMs)]
+    .filter(Boolean)
+    .join(" ");
+}
+
+function unwrapValueCell(value) {
+  if (Array.isArray(value) && value.length === 1) {
+    return unwrapValueCell(value[0]);
+  }
+  return value;
+}
+
+function normalizeFieldName(value) {
+  return String(value || "")
+    .replace(/^head\((.+)\)$/i, "$1")
+    .replace(/;0$/i, "");
+}
+
+function extractGroupedFingerprintItems(response) {
+  const values = response?.values;
+  if (!Array.isArray(values) || values.length === 0) {
+    return [];
+  }
+  const rows = values;
+
+  const valueHeaders = Array.isArray(response?.columns_desc) && response.columns_desc.length > 0
+    ? response.columns_desc.map((entry) => normalizeFieldName(entry?.name))
+    : Array.isArray(response?.columns)
+      ? response.columns.map((entry) => normalizeFieldName(Array.isArray(entry) ? entry[0] : entry))
+      : [];
+
+  return rows.map((entry, index) => {
+    const rowValues = Array.isArray(entry) ? entry : [];
+    const fingerprint = unwrapValueCell(rowValues[0]);
+    const groupedColumns = Array.isArray(rowValues[1]) ? rowValues[1] : [];
+    const count = rowValues[2];
+    const mappedValues = {};
+    mappedValues.fingerprint = String(fingerprint || "").trim();
+    valueHeaders.forEach((field, fieldIndex) => {
+      mappedValues[field] = unwrapValueCell(groupedColumns[fieldIndex]);
+    });
+    if (count !== undefined) {
+      mappedValues._count = unwrapValueCell(count);
+    }
+    return {
+      index: index + 1,
+      objectIdDecimal: "",
+      objectIdHex: "",
+      fingerprint: mappedValues.fingerprint,
+      values: mappedValues,
+    };
+  });
+}
+
+class AuthenticationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+}
+
+class BacktraceSession {
+  constructor(options) {
+    this.queryUrl = options.queryUrl;
+    this.username = options.username;
+    this.password = options.password;
+    this.retries = options.retries;
+    this.proxy = String(options.proxy || "").trim();
+    this.dispatcher = createProxyDispatcher(this.proxy);
+    this.token = "";
+    this.loginUrl = buildLoginUrl(options.queryUrl);
+  }
+
+  async login() {
+    const form = new URLSearchParams();
+    form.set("username", this.username);
+    form.set("password", this.password);
+    logStep("auth", "logging in", { loginUrl: this.loginUrl, username: this.username });
+
+    const payload = await retry("backtrace login", this.retries, async () => {
+      const response = await fetch(this.loginUrl, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: form.toString(),
+        ...(this.dispatcher ? { dispatcher: this.dispatcher } : {}),
+      });
+      const text = await response.text();
+      let data = null;
+      try {
+        data = text ? JSON.parse(text) : null;
+      } catch (error) {
+        data = null;
+      }
+      if (!response.ok) {
+        throw new Error(`Login failed: ${response.status} ${response.statusText}`);
+      }
+      if (!data || !data.token) {
+        throw new Error("Login response did not contain a token");
+      }
+      return data;
+    });
+
+    this.token = payload.token;
+    logStep("auth", "login succeeded");
+    return this.token;
+  }
+
+  async getToken() {
+    if (!this.token) {
+      await this.login();
+    }
+    return this.token;
+  }
+
+  async refreshToken() {
+    logStep("auth", "refreshing session token");
+    this.token = "";
+    return this.login();
+  }
+
+  buildHeaders(extraHeaders, token) {
+    return { ...(extraHeaders || {}), Cookie: `token=${token}` };
+  }
+
+  parseResponseBody(text) {
+    try {
+      return text ? JSON.parse(text) : null;
+    } catch (error) {
+      return text;
+    }
+  }
+
+  isAuthFailure(response, parsedBody) {
+    const normalizedBody = typeof parsedBody === "string"
+      ? parsedBody.toLowerCase()
+      : JSON.stringify(parsedBody || {}).toLowerCase();
+    return response.status === 401
+      || response.status === 403
+      || normalizedBody.includes("invalid token")
+      || normalizedBody.includes("authentication")
+      || normalizedBody.includes("not authorized");
+  }
+
+  async request(urlString, options, label, mode) {
+    return retry(label, this.retries, async () => {
+      let token = await this.getToken();
+      let authAttempt = 0;
+      while (authAttempt < 2) {
+        const url = withSessionToken(urlString, token);
+        const response = await fetch(
+          url.toString(),
+          withDispatcher({ ...options, headers: this.buildHeaders(options?.headers, token) }, this.dispatcher),
+        );
+
+        if (mode === "buffer") {
+          if (response.ok) {
+            return Buffer.from(await response.arrayBuffer());
+          }
+          const text = await response.text();
+          const parsed = this.parseResponseBody(text);
+          if (this.isAuthFailure(response, parsed) && authAttempt === 0) {
+            await this.refreshToken();
+            token = await this.getToken();
+            authAttempt += 1;
+            continue;
+          }
+          throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+        }
+
+        const text = await response.text();
+        const parsed = this.parseResponseBody(text);
+        if (response.ok) {
+          return parsed;
+        }
+        if (this.isAuthFailure(response, parsed) && authAttempt === 0) {
+          await this.refreshToken();
+          token = await this.getToken();
+          authAttempt += 1;
+          continue;
+        }
+        throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+      }
+      throw new AuthenticationError("Authentication failed after token refresh");
+    });
+  }
+
+  async requestJson(urlString, options, label) {
+    return this.request(urlString, options, label, "json");
+  }
+
+  async requestBuffer(urlString, options, label) {
+    return this.request(urlString, options, label, "buffer");
+  }
+
+  async requestStream(urlString, options, label) {
+    return retry(label, this.retries, async () => {
+      let token = await this.getToken();
+      let authAttempt = 0;
+      while (authAttempt < 2) {
+        const url = withSessionToken(urlString, token);
+        const response = await fetch(
+          url.toString(),
+          withDispatcher({ ...options, headers: this.buildHeaders(options?.headers, token) }, this.dispatcher),
+        );
+        if (response.ok) {
+          return response;
+        }
+        const text = await response.text();
+        const parsed = this.parseResponseBody(text);
+        if (this.isAuthFailure(response, parsed) && authAttempt === 0) {
+          await this.refreshToken();
+          token = await this.getToken();
+          authAttempt += 1;
+          continue;
+        }
+        throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+      }
+      throw new AuthenticationError("Authentication failed after token refresh");
+    });
+  }
+}
+
+// 拉取一页查询结果，并记录请求体方便排查问题。
+async function fetchBacktracePage(session, queryUrl, queryBody) {
+  logStep("query", "sending query page", queryBody);
+  return session.requestJson(
+    queryUrl,
+    { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(queryBody) },
+    `query offset=${queryBody.offset} limit=${queryBody.limit}`,
+  );
+}
+
+async function fetchFingerprintProbe(session, options, fingerprint) {
+  const queryBody = buildCompressedFingerprintQueryBody(options, fingerprint);
+  const result = await fetchBacktracePage(session, options.queryUrl, queryBody);
+  return {
+    fingerprint,
+    totalRows: result?._?.runtime?.filter?.rows ?? 0,
+    payload: result,
+  };
+}
+
+async function queryFingerprintGroups(session, options, fingerprintFilter = "") {
+  const probeBody = buildFingerprintGroupQueryBody(options, options.offset, options.limit, fingerprintFilter);
+  const probeResult = await fetchBacktracePage(session, options.queryUrl, probeBody);
+  const totalRows = probeResult?.response?.cardinalities?.pagination?.groups
+    ?? probeResult?.response?.cardinalities?.having?.groups
+    ?? probeResult?.response?.cardinalities?.initial?.groups
+    ?? 0;
+  const pageLimit = optimizeLimit(totalRows, options.limit);
+
+  logStep("query", "fingerprint pagination decided", {
+    totalRows,
+    initialLimit: options.limit,
+    optimizedLimit: pageLimit,
+    fingerprint: fingerprintFilter || "all",
+  });
+
+  const items = [];
+  for (let offset = options.offset; offset < totalRows + options.offset || (offset === options.offset && totalRows === 0); offset += pageLimit) {
+    /* eslint-disable no-await-in-loop */
+    const result = await fetchBacktracePage(
+      session,
+      options.queryUrl,
+      buildFingerprintGroupQueryBody(options, offset, pageLimit, fingerprintFilter),
+    );
+    /* eslint-enable no-await-in-loop */
+    items.push(...extractGroupedFingerprintItems(result?.response));
+    if (totalRows === 0) {
+      break;
+    }
+  }
+
+  return {
+    totalRows,
+    pageLimit,
+    listedCount: items.length,
+    objectIds: items.map((item) => item.fingerprint || ""),
+    selectedValues: items.map((item) => item.values || {}),
+    items,
+  };
+}
+
+async function fetchFingerprintObjects(session, options, fingerprint, knownTotalRows) {
+  const totalRows = Number.isFinite(knownTotalRows)
+    ? knownTotalRows
+    : (() => {
+      throw new Error("fetchFingerprintObjects requires a known total row count");
+    })();
+  const pageLimit = optimizeLimit(totalRows, options.limit);
+  const objects = [];
+
+  for (let offset = options.offset; offset < totalRows + options.offset || (offset === options.offset && totalRows === 0); offset += pageLimit) {
+    /* eslint-disable no-await-in-loop */
+    const result = await fetchBacktracePage(
+      session,
+      options.queryUrl,
+      buildFingerprintObjectsQueryBody(options, fingerprint, offset, pageLimit),
+    );
+    /* eslint-enable no-await-in-loop */
+    const objectIds = extractObjectIds(result?.response?.objects);
+    const selectedValues = extractSelectedValues(result?.response?.values, ["timestamp"]);
+    objectIds.forEach((objectId, index) => {
+      objects.push({
+        objectIdDecimal: objectId,
+        objectIdHex: toHexObjectId(objectId),
+        timestamp: selectedValues[index]?.timestamp || "",
+      });
+    });
+    if (totalRows === 0) {
+      break;
+    }
+  }
+
+  return {
+    fingerprint,
+    totalRows,
+    pageLimit,
+    objects,
+  };
+}
+
+async function queryFingerprintDetail(session, options) {
+  const requestedFingerprints = getRequestedFingerprints(options);
+  const fingerprint = requestedFingerprints[0];
+  const groupResult = await queryFingerprintGroups(session, options, fingerprint);
+  const summary = groupResult.items[0] || {
+    fingerprint,
+    values: {
+      fingerprint,
+      "error.message": "",
+      classifiers: "",
+      "fingerprint;first_seen": "",
+      "fingerprint;issues;state": "",
+      _count: 0,
+    },
+  };
+  const probe = await fetchFingerprintProbe(session, options, fingerprint);
+  const objectsResult = await fetchFingerprintObjects(session, options, fingerprint, probe.totalRows);
+
+  return {
+    fingerprint,
+    summary,
+    objects: objectsResult.objects,
+    querySummary: {
+      totalRows: objectsResult.totalRows,
+      fetchedRows: objectsResult.objects.length,
+      objectCount: objectsResult.objects.length,
+      pageLimit: objectsResult.pageLimit,
+      objectIds: objectsResult.objects.map((item) => item.objectIdHex),
+      selectedValues: objectsResult.objects.map((item) => ({ timestamp: item.timestamp })),
+    },
+  };
+}
+
+// 先探测总行数，再用优化后的分页大小拉取全部结果页。
+async function fetchAllResults(session, options) {
+  // 先做一次探测请求，拿到总行数后再决定真正的分页大小。
+  const probeBody = buildQueryBody(options, options.offset, options.limit);
+  const probeResult = await fetchBacktracePage(session, options.queryUrl, probeBody);
+  const totalRows = shouldUseFingerprintGroupQuery(options)
+    ? probeResult?.response?.cardinalities?.pagination?.groups
+      ?? probeResult?.response?.cardinalities?.having?.groups
+      ?? probeResult?.response?.cardinalities?.initial?.groups
+      ?? 0
+    : probeResult?._?.runtime?.filter?.rows ?? 0;
+  const pageLimit = optimizeLimit(totalRows, options.limit);
+
+  logStep("query", "query pagination decided", { totalRows, initialLimit: options.limit, optimizedLimit: pageLimit });
+
+  const pages = [];
+  // 即使结果为空，也保留一页请求，保持空结果场景的行为一致。
+  for (let offset = options.offset; offset < totalRows + options.offset || (offset === options.offset && totalRows === 0); offset += pageLimit) {
+    pages.push({ offset, limit: pageLimit });
+    if (totalRows === 0) break;
+  }
+  if (pages.length === 0) {
+    pages.push({ offset: options.offset, limit: pageLimit });
+  }
+
+  const allObjectIds = [];
+  const allSelectedValues = [];
+  // 顺序拉取每一页，避免一次性并发查询过多导致远端接口不稳定。
+  for (const page of pages) {
+    /* eslint-disable no-await-in-loop */
+    const result = await fetchBacktracePage(session, options.queryUrl, buildQueryBody(options, page.offset, page.limit));
+    /* eslint-enable no-await-in-loop */
+    if (shouldUseFingerprintGroupQuery(options)) {
+      // 指纹聚合查询不依赖 object id，后续直接从 values 中还原每一行。
+      const groupedItems = extractGroupedFingerprintItems(result?.response);
+      allObjectIds.push(...groupedItems.map((item) => item.fingerprint || ""));
+      allSelectedValues.push(...groupedItems.map((item) => item.values));
+    } else {
+      allObjectIds.push(...extractObjectIds(result?.response?.objects));
+      allSelectedValues.push(...extractSelectedValues(result?.response?.values, options.select));
+    }
+  }
+
+  return { totalRows, pageLimit, listedCount: allObjectIds.length, objectIds: allObjectIds, selectedValues: allSelectedValues };
+}
+
+// 列出某个 Backtrace 对象可下载的附件。
+async function fetchAttachmentList(session, queryUrl, objectHexId) {
+  const url = buildSiblingUrl(queryUrl, "/api/list");
+  url.searchParams.set("object", objectHexId);
+  logStep("attachments", "requesting attachment list", url.toString());
+  return session.requestJson(url.toString(), { method: "GET" }, `attachment list ${objectHexId}`);
+}
+
+// 下载单个附件到本地；如果本地已存在则直接复用。
+async function downloadAttachment(session, queryUrl, objectHexId, targetDir, attachment) {
+  const savedPath = path.join(targetDir, attachment.name);
+  const existing = await fs.stat(savedPath).catch(() => null);
+  if (existing && existing.isFile()) {
+    logStep("download", "attachment already exists, skipping", savedPath);
+    return { ...attachment, savedPath, skipped: true, sizeBytes: existing.size || 0 };
+  }
+
+  const url = buildSiblingUrl(queryUrl, "/api/get");
+  // 下载接口需要同时带上 object 和 attachment_id 才能定位到具体附件。
+  url.searchParams.set("object", objectHexId);
+  url.searchParams.set("attachment_id", attachment.id);
+  url.searchParams.set("attachment_inline", "false");
+  logStep("download", "downloading attachment", { objectId: objectHexId, attachment: attachment.name });
+  const response = await session.requestStream(url.toString(), {}, `download ${objectHexId}/${attachment.name}`);
+  const totalBytes = Number(response.headers.get("content-length") || attachment.size || 0);
+  const fileStream = fsNative.createWriteStream(savedPath);
+  const startedAt = Date.now();
+  let downloadedBytes = 0;
+  let progressTimer = null;
+  const printProgress = () => {
+    const elapsedMs = Math.max(1, Date.now() - startedAt);
+    logStep("download", `file ${formatAttachmentStatus(downloadedBytes, totalBytes, elapsedMs)}`, {
+      objectId: objectHexId,
+      attachment: attachment.name,
+    });
+  };
+  try {
+    printProgress();
+    progressTimer = setInterval(() => {
+      printProgress();
+    }, 1000);
+
+    for await (const chunk of response.body) {
+      downloadedBytes += chunk.length;
+      if (!fileStream.write(chunk)) {
+        /* eslint-disable no-await-in-loop */
+        await new Promise((resolve) => {
+          fileStream.once("drain", resolve);
+        });
+        /* eslint-enable no-await-in-loop */
+      }
+    }
+    await new Promise((resolve, reject) => {
+      fileStream.end((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  } catch (error) {
+    if (progressTimer) {
+      clearInterval(progressTimer);
+      progressTimer = null;
+    }
+    fileStream.destroy();
+    await fs.unlink(savedPath).catch(() => {});
+    throw error;
+  }
+  if (progressTimer) {
+    clearInterval(progressTimer);
+    progressTimer = null;
+  }
+  printProgress();
+  logStep("download", "attachment saved", savedPath);
+  return { ...attachment, savedPath, sizeBytes: downloadedBytes };
+}
+
+async function downloadAttachmentWithRetry(session, queryUrl, objectHexId, targetDir, attachment, maxAttempts = 5) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      /* eslint-disable no-await-in-loop */
+      return await downloadAttachment(session, queryUrl, objectHexId, targetDir, attachment);
+      /* eslint-enable no-await-in-loop */
+    } catch (error) {
+      lastError = error;
+      logStep("download", "attachment download failed", {
+        objectId: objectHexId,
+        attachment: attachment.name,
+        attempt,
+        maxAttempts,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  logStep("download", "attachment skipped after retries", {
+    objectId: objectHexId,
+    attachment: attachment.name,
+    maxAttempts,
+    message: lastError instanceof Error ? lastError.message : String(lastError || ""),
+  });
+  return { ...attachment, savedPath: "", skipped: true, failed: true };
+}
+
+// 查询所有匹配对象，并同时返回原始查询摘要和映射后的对象列表。
+async function queryAllItems(session, options) {
+  if (options.command === "collect-all") {
+    const requestedFingerprints = getRequestedFingerprints(options);
+    const fingerprintItems = [];
+    let fingerprintPageLimit = 0;
+
+    if (requestedFingerprints.length === 0) {
+      const fingerprintResult = await queryFingerprintGroups(session, options);
+      fingerprintItems.push(...fingerprintResult.items);
+      fingerprintPageLimit = fingerprintResult.pageLimit;
+    } else {
+      for (const requestedFingerprint of requestedFingerprints) {
+        /* eslint-disable no-await-in-loop */
+        const fingerprintResult = await queryFingerprintGroups(session, options, requestedFingerprint);
+        fingerprintItems.push(...fingerprintResult.items);
+        fingerprintPageLimit = Math.max(fingerprintPageLimit, fingerprintResult.pageLimit);
+        /* eslint-enable no-await-in-loop */
+      }
+    }
+
+    const uniqueFingerprintItems = Array.from(
+      new Map(fingerprintItems.map((item) => [String(item.fingerprint || item.values.fingerprint || "").trim(), item])).values(),
+    ).filter((item) => String(item.fingerprint || item.values.fingerprint || "").trim());
+    const items = [];
+    let totalRows = 0;
+    let pageLimit = fingerprintPageLimit;
+
+    for (const fingerprintItem of uniqueFingerprintItems) {
+      const fingerprint = String(fingerprintItem.fingerprint || fingerprintItem.values.fingerprint || "").trim();
+      if (!fingerprint) {
+        continue;
+      }
+
+      /* eslint-disable no-await-in-loop */
+      const probe = await fetchFingerprintProbe(session, options, fingerprint);
+      if (probe.totalRows === 0) {
+        logStep("query", "fingerprint probe returned no rows", { fingerprint });
+        continue;
+      }
+
+      const objectResult = await fetchFingerprintObjects(session, options, fingerprint, probe.totalRows);
+      totalRows += objectResult.totalRows;
+      pageLimit = Math.max(pageLimit, objectResult.pageLimit);
+      objectResult.objects.forEach((objectItem) => {
+        items.push({
+          index: items.length + 1,
+          objectIdDecimal: objectItem.objectIdDecimal,
+          objectIdHex: objectItem.objectIdHex,
+          fingerprint,
+          values: {
+            fingerprint,
+            timestamp: objectItem.timestamp,
+            "error.message": fingerprintItem.values["error.message"] || "",
+            classifiers: fingerprintItem.values.classifiers || "",
+            "fingerprint;first_seen": fingerprintItem.values["fingerprint;first_seen"] || "",
+            "fingerprint;issues;state": fingerprintItem.values["fingerprint;issues;state"] || "",
+            _count: fingerprintItem.values._count || 0,
+          },
+        });
+      });
+      /* eslint-enable no-await-in-loop */
+    }
+
+    logStep("query", "loaded query results", {
+      fingerprintCount: uniqueFingerprintItems.length,
+      fetchedRows: totalRows,
+      objectCount: items.length,
+    });
+
+    return {
+      totalRows,
+      pageLimit,
+      listedCount: items.length,
+      objectIds: items.map((item) => item.objectIdHex),
+      selectedValues: items.map((item) => item.values),
+      items,
+      fingerprints: uniqueFingerprintItems,
+    };
+  }
+
+  const result = await fetchAllResults(session, options);
+  const items = result.selectedValues.map((values, index) => ({
+    index: index + 1,
+    objectIdDecimal: "",
+    objectIdHex: "",
+    fingerprint: String(values?.fingerprint || "").trim(),
+    values: values || {},
+  }));
+  logStep("query", "loaded query results", { fetchedRows: result.listedCount, objectCount: items.length });
+  return { ...result, items };
+}
+
+// 把单个崩溃对象的全部附件下载到对应 fingerprint/object 目录下。
+async function downloadItemLogs(session, item, options) {
+  const objectHexId = item.objectIdHex;
+  const fingerprint = normalizeFingerprint(item.fingerprint || item.values.fingerprint || options.fingerprint);
+  logStep("download", "preparing object download", { objectId: objectHexId, from: options.from, to: options.to, fingerprint });
+  let attachmentList = null;
+  let attachmentListError = null;
+  for (let attempt = 1; attempt <= 5; attempt += 1) {
+    try {
+      /* eslint-disable no-await-in-loop */
+      attachmentList = await fetchAttachmentList(session, options.queryUrl, objectHexId);
+      /* eslint-enable no-await-in-loop */
+      attachmentListError = null;
+      break;
+    } catch (error) {
+      attachmentListError = error;
+      logStep("attachments", "attachment list failed", {
+        objectId: objectHexId,
+        attempt,
+        maxAttempts: 5,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  if (!attachmentList) {
+    logStep("download", "object skipped after attachment list retries", {
+      objectId: objectHexId,
+      fingerprint,
+      message: attachmentListError instanceof Error ? attachmentListError.message : String(attachmentListError || ""),
+    });
+    return { ...item, values: { ...item.values, fingerprint }, fingerprint, targetDir: "", downloadedFiles: [], skipped: true, failed: true };
+  }
+  const attachments = Array.isArray(attachmentList.attachments) ? attachmentList.attachments : [];
+  const targetDir = path.join(getFingerprintLogsRoot(options.storageDir, fingerprint), objectHexId);
+  await ensureDirectory(targetDir);
+
+  const downloadedFiles = [];
+  // 单对象内部仍按顺序下载，便于日志追踪，也避免附件下载把会话压垮。
+  for (const attachment of attachments) {
+    /* eslint-disable no-await-in-loop */
+    const downloadedFile = await downloadAttachmentWithRetry(session, options.queryUrl, objectHexId, targetDir, attachment, 5);
+    downloadedFiles.push(downloadedFile);
+    if (typeof options.onAttachmentDownloaded === "function") {
+      options.onAttachmentDownloaded({
+        item,
+        objectId: objectHexId,
+        fingerprint,
+        attachmentName: attachment.name,
+        downloadedFile,
+      });
+    }
+    /* eslint-enable no-await-in-loop */
+  }
+
+  logStep("download", "object download completed", { objectId: objectHexId, fileCount: downloadedFiles.length, targetDir, fingerprint });
+  return { ...item, values: { ...item.values, fingerprint }, fingerprint, targetDir, downloadedFiles };
+}
+
+module.exports = {
+  AuthenticationError,
+  BacktraceSession,
+  buildQueryBody,
+  buildSiblingUrl,
+  buildLoginUrl,
+  withSessionToken,
+  toHexObjectId,
+  extractObjectIds,
+  extractSelectedValues,
+  mapResultsToItems,
+  optimizeLimit,
+  fetchBacktracePage,
+  fetchAllResults,
+  queryFingerprintGroups,
+  queryFingerprintDetail,
+  fetchAttachmentList,
+  downloadAttachment,
+  queryAllItems,
+  downloadItemLogs,
+};