backtrace-console 0.0.1 → 0.0.2

package/lib/backtrace/query.js

@@ -1,32 +1,18 @@
 const fs = require("node:fs/promises");
-const fsNative = require("node:fs");
 const path = require("node:path");
-const {
-  logStep,
-  retry,
-  ensureDirectory,
-  normalizeFingerprint,
-  getFingerprintLogsRoot,
-} = require("./utils");
-
+const { AuthenticationError, BacktraceSession, buildSiblingUrl, buildLoginUrl, withSessionToken } = require("./query-session");
+const { downloadAttachment, downloadAttachmentWithRetry } = require("./query-download");
+const { logStep, 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_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) {
@@ -39,29 +25,20 @@ function createProxyDispatcher(proxyUrl) {
     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 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)]],
   };
@@ -86,7 +63,6 @@ function buildQueryBody(options, offset, limit) {
     filter: [filter],
   };
 }
-
 function buildFingerprintGroupQueryBody(options, offset, limit, fingerprintFilter) {
   const filter = {
     timestamp: [["at-most", String(options.to)], ["at-least", String(options.from)]],
@@ -103,7 +79,6 @@ function buildFingerprintGroupQueryBody(options, offset, limit, fingerprintFilte
     filter: [filter],
   };
 }
-
 function buildCompressedFingerprintQueryBody(options, fingerprint) {
   return {
     select: ["_compressed"],
@@ -116,7 +91,6 @@ function buildCompressedFingerprintQueryBody(options, fingerprint) {
     }],
   };
 }
-
 function buildFingerprintObjectsQueryBody(options, fingerprint, offset, limit) {
   return {
     select: ["timestamp"],
@@ -129,30 +103,6 @@ function buildFingerprintObjectsQueryBody(options, fingerprint, offset, limit) {
     }],
   };
 }
-
-// 复用原始主机地址，只切换到相邻的 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();
@@ -163,8 +113,6 @@ function toHexObjectId(value) {
   }
   return numeric.toString(16);
 }
-
-// 从 Backtrace 查询结果中提取 object id 列表。
 function extractObjectIds(objects) {
   if (!Array.isArray(objects) || objects.length === 0) {
     return [];
@@ -184,8 +132,6 @@ function extractObjectIds(objects) {
   });
   return values;
 }
-
-// 把 Backtrace 按列组织的值数组转换成按行组织的对象值。
 function extractSelectedValues(values, selectFields) {
   if (!Array.isArray(values) || values.length === 0) {
     return [];
@@ -202,8 +148,6 @@ function extractSelectedValues(values, selectFields) {
     return row;
   });
 }
-
-// 把 object id 和选中字段拼成更易用的单条对象结构。
 function mapResultsToItems(objectIds, selectedValues) {
   return objectIds.map((objectId, index) => ({
     index: index + 1,
@@ -212,83 +156,29 @@ function mapResultsToItems(objectIds, selectedValues) {
     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 optimizeLimit(totalRows, baseLimit) { if (totalRows <= baseLimit) return baseLimit; if (totalRows <= 100) return 50; if (totalRows <= 500) return 100; return 200; }
 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]);
@@ -311,176 +201,6 @@ function extractGroupedFingerprintItems(response) {
     };
   });
 }
-
-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(
@@ -489,7 +209,6 @@ async function fetchBacktracePage(session, queryUrl, 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);
@@ -499,7 +218,6 @@ async function fetchFingerprintProbe(session, options, fingerprint) {
     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);
@@ -508,14 +226,12 @@ async function queryFingerprintGroups(session, options, fingerprintFilter = "")
     ?? 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 */
@@ -530,7 +246,6 @@ async function queryFingerprintGroups(session, options, fingerprintFilter = "")
       break;
     }
   }
-
   return {
     totalRows,
     pageLimit,
@@ -540,7 +255,6 @@ async function queryFingerprintGroups(session, options, fingerprintFilter = "")
     items,
   };
 }
-
 async function fetchFingerprintObjects(session, options, fingerprint, knownTotalRows) {
   const totalRows = Number.isFinite(knownTotalRows)
     ? knownTotalRows
@@ -549,7 +263,6 @@ async function fetchFingerprintObjects(session, options, fingerprint, knownTotal
     })();
   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(
@@ -571,7 +284,6 @@ async function fetchFingerprintObjects(session, options, fingerprint, knownTotal
       break;
     }
   }
-
   return {
     fingerprint,
     totalRows,
@@ -579,7 +291,6 @@ async function fetchFingerprintObjects(session, options, fingerprint, knownTotal
     objects,
   };
 }
-
 async function queryFingerprintDetail(session, options) {
   const requestedFingerprints = getRequestedFingerprints(options);
   const fingerprint = requestedFingerprints[0];
@@ -597,7 +308,6 @@ async function queryFingerprintDetail(session, options) {
   };
   const probe = await fetchFingerprintProbe(session, options, fingerprint);
   const objectsResult = await fetchFingerprintObjects(session, options, fingerprint, probe.totalRows);
-
   return {
     fingerprint,
     summary,
@@ -612,10 +322,7 @@ async function queryFingerprintDetail(session, options) {
     },
   };
 }
-
-// 先探测总行数，再用优化后的分页大小拉取全部结果页。
 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)
@@ -625,11 +332,8 @@ async function fetchAllResults(session, options) {
       ?? 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;
@@ -637,16 +341,13 @@ async function fetchAllResults(session, options) {
   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));
@@ -655,124 +356,22 @@ async function fetchAllResults(session, options) {
       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 source = new URL(queryUrl);
   const url = buildSiblingUrl(queryUrl, "/api/list");
+  const project = source.searchParams.get("project");
+  if (project) url.searchParams.set("project", project);
   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);
@@ -786,27 +385,23 @@ async function queryAllItems(session, options) {
         /* 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);
@@ -829,13 +424,11 @@ async function queryAllItems(session, options) {
       });
       /* eslint-enable no-await-in-loop */
     }
-
     logStep("query", "loaded query results", {
       fingerprintCount: uniqueFingerprintItems.length,
       fetchedRows: totalRows,
       objectCount: items.length,
     });
-
     return {
       totalRows,
       pageLimit,
@@ -846,7 +439,6 @@ async function queryAllItems(session, options) {
       fingerprints: uniqueFingerprintItems,
     };
   }
-
   const result = await fetchAllResults(session, options);
   const items = result.selectedValues.map((values, index) => ({
     index: index + 1,
@@ -858,8 +450,6 @@ async function queryAllItems(session, options) {
   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);
@@ -894,12 +484,10 @@ async function downloadItemLogs(session, item, options) {
   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);
+    const downloadedFile = await downloadAttachmentWithRetry(session, options.queryUrl, objectHexId, targetDir, attachment, buildSiblingUrl, 5);
     downloadedFiles.push(downloadedFile);
     if (typeof options.onAttachmentDownloaded === "function") {
       options.onAttachmentDownloaded({
@@ -912,29 +500,7 @@ async function downloadItemLogs(session, item, options) {
     }
     /* 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,
-};
+module.exports = { AuthenticationError, BacktraceSession, buildQueryBody, buildSiblingUrl, buildLoginUrl, withSessionToken, toHexObjectId, extractObjectIds, extractSelectedValues, mapResultsToItems, optimizeLimit, fetchBacktracePage, fetchAllResults, queryFingerprintGroups, queryFingerprintDetail, fetchAttachmentList, downloadAttachment, queryAllItems, downloadItemLogs };