@citeark/agent 0.3.20

package/src/research/source-discovery.mjs

@@ -0,0 +1,646 @@
+import { captureProcess } from "../process.mjs";
+import { externalRequestObservation } from "../observability/event-contract.mjs";
+
+const GITHUB_API = "https://api.github.com";
+const MAX_DOCUMENT_BYTES = 2 * 1024 * 1024;
+const RESERVED_GITHUB_OWNERS = new Set([
+  "collections",
+  "features",
+  "login",
+  "marketplace",
+  "orgs",
+  "search",
+  "settings",
+  "topics",
+]);
+
+export class SourceDiscoveryError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "SourceDiscoveryError";
+    this.details = details;
+    this.reasonCode = details.reasonCode;
+    this.retryable = details.retryable === true;
+  }
+}
+
+/**
+ * 在 Research Compiler 克隆仓库之前验证论文原文声明的 GitHub 仓库。
+ * 多链接论文先使用链接附近的“代码发布/复现材料”角色语义排除引用实现、
+ * 基线和依赖；只有角色唯一且分差充足时才采用。论文没有直链时，GitHub
+ * 搜索只用于发现候选，必须再由固定论文中的完整标题、arXiv ID 和作者身份
+ * 等相互独立证据完成归属验证；不会仅凭标题搜索结果或 README 自述采用仓库。
+ */
+export async function discoverRepository({
+  paperPath,
+  paperUri,
+  title,
+  fetchImpl = fetch,
+  extractPaperText = extractPdfText,
+  sleep = defaultSleep,
+  now = () => new Date(),
+  observe = () => {},
+}) {
+  const diagnostics = [];
+  const externalRequests = [];
+  const recordExternalRequest = (observation) => {
+    if (externalRequests.length < 50) externalRequests.push(observation);
+    try {
+      observe(observation);
+    } catch {
+      // 可观测性回调不能改变来源发现本身的科学或安全决策。
+    }
+  };
+  let paperText = "";
+  if (paperPath) {
+    try {
+      paperText = await extractPaperText(paperPath);
+    } catch (error) {
+      diagnostics.push(`paper-text: ${errorMessage(error)}`);
+      throw new SourceDiscoveryError("无法解析固定论文文本，暂不能判断作者仓库", {
+        reasonCode: "paper_text_extraction_failed",
+        retryable: true,
+        diagnostics,
+        externalRequests,
+      });
+    }
+  }
+
+  let paperCandidates = extractGitHubRepositoryCandidates(paperText);
+  let resolutionMethod = "paper-link";
+  if (paperCandidates.length === 0) {
+    let evidenceResolved;
+    try {
+      evidenceResolved = await discoverAuthorOwnedRepository({
+        paperText,
+        paperUri,
+        title,
+        fetchImpl,
+        sleep,
+        now,
+        diagnostics,
+        observe: recordExternalRequest,
+      });
+    } catch (error) {
+      if (error?.retryable !== true) throw error;
+      throw new SourceDiscoveryError("作者仓库证据查询暂时不可用", {
+        reasonCode: "repository_identity_resolution_unavailable",
+        retryable: true,
+        diagnostics,
+        externalRequests,
+      });
+    }
+    if (evidenceResolved) {
+      paperCandidates = [evidenceResolved];
+      resolutionMethod = "author-owned-paper-matched";
+    }
+  }
+  const directUrls = paperCandidates.map((candidate) => candidate.url);
+  const resolvedCandidate = resolvePaperDeclaredRepositoryCandidate(paperCandidates);
+  if (!resolvedCandidate) {
+    throw new SourceDiscoveryError(
+      directUrls.length
+        ? "论文原文包含多个 GitHub 仓库链接，无法在不猜测的前提下确定官方实现"
+        : "论文原文未明确声明 GitHub 代码仓库",
+      {
+        reasonCode: directUrls.length
+          ? "ambiguous_paper_repository_links"
+          : "repository_identity_not_resolved",
+        directUrlCount: directUrls.length,
+        directUrls: directUrls.slice(0, 20),
+        diagnostics,
+        externalRequests,
+      },
+    );
+  }
+
+  const identity = githubIdentity(resolvedCandidate.url);
+  let selected;
+  let accessVerification = "github-api";
+  try {
+    selected = await requestJson(
+      fetchImpl,
+      `${GITHUB_API}/repos/${identity.owner}/${identity.repo}`,
+      {
+        sleep,
+        now,
+        observe: recordExternalRequest,
+        service: "github",
+        operation: "repository_metadata",
+      },
+    );
+  } catch (error) {
+    diagnostics.push(`${identity.owner}/${identity.repo}: ${errorMessage(error)}`);
+    try {
+      await request(
+        fetchImpl,
+        `${resolvedCandidate.url}.git/info/refs?service=git-upload-pack`,
+        {
+          sleep,
+          now,
+          observe: recordExternalRequest,
+          service: "github",
+          operation: "git_smart_http_probe",
+          headers: { accept: "application/x-git-upload-pack-advertisement" },
+        },
+      );
+      selected = {
+        html_url: resolvedCandidate.url,
+        full_name: `${identity.owner}/${identity.repo}`,
+        private: false,
+        disabled: false,
+      };
+      accessVerification = "git-smart-http";
+      diagnostics.push(`${identity.owner}/${identity.repo}: Git smart HTTP access verified after API metadata failure`);
+    } catch (gitError) {
+      diagnostics.push(`${identity.owner}/${identity.repo} git-smart-http: ${errorMessage(gitError)}`);
+      throw new SourceDiscoveryError(
+        "论文原文声明的 GitHub 仓库暂时无法完成公开可访问性验证",
+        {
+          reasonCode: "paper_declared_repository_verification_unavailable",
+          retryable: error?.retryable === true || gitError?.retryable === true,
+          directUrlCount: directUrls.length,
+          directUrls,
+          diagnostics,
+          externalRequests,
+        },
+      );
+    }
+  }
+  if (selected.private || selected.disabled) {
+    throw new SourceDiscoveryError(
+      "论文原文声明的 GitHub 仓库不是可执行的公开仓库",
+      {
+        reasonCode: "paper_declared_repository_not_public",
+        directUrlCount: directUrls.length,
+        directUrls,
+        diagnostics,
+        externalRequests,
+      },
+    );
+  }
+  const htmlUrl = canonicalGitHubRepositoryUrl(selected.html_url) ?? resolvedCandidate.url;
+  return {
+    url: `${htmlUrl}.git`,
+    htmlUrl,
+    fullName: selected.full_name ?? `${identity.owner}/${identity.repo}`,
+    defaultBranch: selected.default_branch ?? null,
+    licenseSpdx:
+      selected.license?.spdx_id &&
+      selected.license.spdx_id !== "NOASSERTION"
+        ? selected.license.spdx_id
+        : null,
+    archived: Boolean(selected.archived),
+    method: `${resolutionMethod === "author-owned-paper-matched"
+      ? "author-owned-paper-matched"
+      : directUrls.length === 1
+        ? "paper-declared"
+        : "paper-declared-role-resolved"}+${accessVerification === "github-api"
+      ? "github-verification"
+      : "git-smart-http-verification"}`,
+    confidence: resolutionMethod === "author-owned-paper-matched"
+      ? "evidence-resolved"
+      : directUrls.length === 1
+        ? "paper-declared"
+        : "paper-declared-role-resolved",
+    evidence: {
+      directPaperLink: resolutionMethod === "paper-link",
+      source: "fixed-paper-text",
+      accessVerification,
+      directPaperLinkCount: resolutionMethod === "paper-link" ? directUrls.length : 0,
+      ...(resolutionMethod === "author-owned-paper-matched" ? {
+        identityResolution: {
+          score: resolvedCandidate.score,
+          signals: resolvedCandidate.signals,
+        },
+      } : {}),
+      ...(directUrls.length > 1 ? {
+        roleResolution: {
+          score: resolvedCandidate.score,
+          signals: resolvedCandidate.signals,
+        },
+      } : {}),
+    },
+    diagnostics,
+    externalRequests,
+  };
+}
+
+async function discoverAuthorOwnedRepository({
+  paperText,
+  paperUri,
+  title,
+  fetchImpl,
+  sleep,
+  now,
+  diagnostics,
+  observe,
+}) {
+  const query = githubEvidenceSearchQuery(title, paperText);
+  if (!query) return null;
+  let search;
+  try {
+    search = await requestJson(
+      fetchImpl,
+      `${GITHUB_API}/search/repositories?q=${encodeURIComponent(query)}&per_page=5`,
+      { sleep, now, observe, service: "github", operation: "repository_search" },
+    );
+  } catch (error) {
+    diagnostics.push(`github-evidence-search: ${errorMessage(error)}`);
+    if (error?.retryable === true) throw error;
+    return null;
+  }
+  const fixedPaper = normalizeIdentityText(paperText.slice(0, 30_000));
+  const fixedTitleCandidates = paperTitleCandidates(title, paperText);
+  const fixedArxivId = arxivId(paperUri) ?? arxivId(paperText);
+  const evaluated = [];
+  let retryableCandidateFailure = false;
+  for (const candidate of Array.isArray(search?.items) ? search.items.slice(0, 5) : []) {
+    if (candidate?.private || candidate?.disabled || !candidate?.full_name) continue;
+    try {
+      const [readme, owner] = await Promise.all([
+        requestJson(fetchImpl, `${GITHUB_API}/repos/${candidate.full_name}/readme`, {
+          sleep, now, observe, service: "github", operation: "repository_readme",
+        }),
+        candidate.owner?.url
+          ? requestJson(fetchImpl, candidate.owner.url, {
+              sleep, now, observe, service: "github", operation: "repository_owner",
+            })
+          : Promise.resolve(null),
+      ]);
+      const readmeText = decodeGitHubContent(readme);
+      const heading = readmeText.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? candidate.name ?? "";
+      const normalizedHeading = normalizeIdentityText(heading);
+      const ownerName = typeof owner?.name === "string" ? owner.name.trim() : "";
+      const normalizedOwnerName = normalizeIdentityText(ownerName);
+      const readmeArxivId = arxivId(readmeText);
+      let score = 0;
+      const signals = [];
+      if (normalizedHeading.length >= 24 && fixedPaper.includes(normalizedHeading)) {
+        score += 10;
+        signals.push("exact-title-in-fixed-paper");
+      } else if (fixedTitleCandidates.some((candidateTitle) => titleIdentitySimilarity(heading, candidateTitle) >= 0.9)) {
+        score += 10;
+        signals.push("equivalent-title-in-fixed-paper");
+      }
+      if (fixedArxivId && readmeArxivId === fixedArxivId) {
+        score += 10;
+        signals.push("matching-arxiv-id");
+      }
+      if (normalizedOwnerName.length >= 8 && fixedPaper.includes(normalizedOwnerName)) {
+        score += 7;
+        signals.push("repository-owner-is-paper-author");
+      }
+      if (/\b(?:official implementation|code for|implementation of)\b/i.test(readmeText)) {
+        score += 2;
+        signals.push("readme-implementation-claim");
+      }
+      evaluated.push({
+        url: canonicalGitHubRepositoryUrl(candidate.html_url),
+        score,
+        signals,
+      });
+    } catch (error) {
+      diagnostics.push(`${candidate.full_name}: ${errorMessage(error)}`);
+      retryableCandidateFailure ||= error?.retryable === true;
+    }
+  }
+  const ranked = evaluated
+    .filter((candidate) => candidate.url)
+    .sort((left, right) => right.score - left.score);
+  const [first, second] = ranked;
+  const resolved = first && first.score >= 17 && first.score - (second?.score ?? 0) >= 5
+    ? first
+    : null;
+  if (!resolved && retryableCandidateFailure) {
+    const error = new Error("GitHub 候选仓库证据查询暂时不可用");
+    error.retryable = true;
+    throw error;
+  }
+  return resolved;
+}
+
+export function extractGitHubRepositoryUrls(value) {
+  return extractGitHubRepositoryCandidates(value).map((candidate) => candidate.url);
+}
+
+export function extractGitHubRepositoryCandidates(value) {
+  if (typeof value !== "string" || !value) return [];
+  const candidates = new Map();
+  // pdftotext commonly wraps a printed repository URL immediately after the
+  // host or slash. Accept whitespace at path boundaries, then remove it before
+  // URL parsing. This stays deliberately narrower than joining arbitrary PDF
+  // lines so unrelated two-column text cannot be mistaken for a repository.
+  const expression = /https?:\/\/(?:www\.)?github\.com\/\s*[a-zA-Z0-9_.-]+\s*\/\s*[a-zA-Z0-9_.-]+/g;
+  for (const match of value.matchAll(expression)) {
+    const canonical = canonicalGitHubRepositoryUrl(match[0].replaceAll(/\s+/g, ""));
+    if (!canonical) continue;
+    // Repository-role language normally precedes the link. Keep the look-ahead
+    // deliberately short so one later release statement cannot lend its role
+    // to an earlier citation on the same page.
+    const start = Math.max(0, (match.index ?? 0) - 260);
+    const end = Math.min(value.length, (match.index ?? 0) + match[0].length + 40);
+    const localContext = value.slice(start, end);
+    const footnoteContext = repositoryFootnoteContext(value, match.index ?? 0);
+    const role = repositoryRoleEvidence(
+      footnoteContext ? `${footnoteContext}\n${localContext}` : localContext,
+    );
+    const immediatePrefix = value
+      .slice(Math.max(0, (match.index ?? 0) - 140), match.index ?? 0)
+      .replaceAll(/\s+/g, " ")
+      .toLowerCase();
+    if (/[a-z0-9][a-z0-9_.+ -]{1,100}\s+is\s+(?:publicly\s+)?available\s+at\s*$/.test(immediatePrefix)) {
+      role.score += 8;
+      role.signals.push("named-artifact-availability");
+    }
+    const current = candidates.get(canonical);
+    if (!current || role.score > current.score) {
+      candidates.set(canonical, { url: canonical, ...role });
+    }
+  }
+  return [...candidates.values()];
+}
+
+function repositoryFootnoteContext(value, linkIndex) {
+  const lineStart = value.lastIndexOf("\n", linkIndex - 1) + 1;
+  const marker = value.slice(lineStart, linkIndex).trim().match(/^(\d{1,2})$/)?.[1];
+  if (!marker) return "";
+  const priorStart = Math.max(0, lineStart - 8_000);
+  const prior = value.slice(priorStart, lineStart);
+  const reference = new RegExp(`(?:[a-zA-Z)\\]])\\.?${marker}(?=\\s|$)`, "g");
+  let best = "";
+  let bestScore = Number.NEGATIVE_INFINITY;
+  for (const match of prior.matchAll(reference)) {
+    const context = prior.slice(
+      Math.max(0, (match.index ?? 0) - 650),
+      Math.min(prior.length, (match.index ?? 0) + match[0].length + 80),
+    );
+    const score = repositoryRoleEvidence(context).score;
+    if (score > bestScore) {
+      best = context;
+      bestScore = score;
+    }
+  }
+  return bestScore > 0 ? best : "";
+}
+
+export function canonicalGitHubRepositoryUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || !new Set(["github.com", "www.github.com"]).has(url.hostname.toLowerCase())) {
+      return null;
+    }
+    const [owner, rawRepo] = url.pathname.split("/").filter(Boolean);
+    const repo = rawRepo
+      ?.replace(/[.,;:!?]+$/g, "")
+      .replace(/\.git$/i, "");
+    if (!owner || !repo || RESERVED_GITHUB_OWNERS.has(owner.toLowerCase())) return null;
+    if (!/^[a-zA-Z0-9_.-]+$/.test(owner) || !/^[a-zA-Z0-9_.-]+$/.test(repo)) return null;
+    return `https://github.com/${owner}/${repo}`;
+  } catch {
+    return null;
+  }
+}
+
+function githubIdentity(value) {
+  const canonical = canonicalGitHubRepositoryUrl(value);
+  if (!canonical) return null;
+  const [owner, repo] = new URL(canonical).pathname.split("/").filter(Boolean);
+  return { owner, repo, key: `${owner}/${repo}`.toLowerCase() };
+}
+
+function resolvePaperDeclaredRepositoryCandidate(candidates) {
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length === 0) return null;
+  const ranked = [...candidates].sort((left, right) => right.score - left.score);
+  const [first, second] = ranked;
+  return first.score >= 6 && first.score - second.score >= 4 ? first : null;
+}
+
+function repositoryRoleEvidence(context) {
+  const normalized = context.replaceAll(/\s+/g, " ").toLowerCase();
+  let score = 0;
+  const signals = [];
+  const apply = (pattern, weight, signal) => {
+    if (!pattern.test(normalized)) return;
+    score += weight;
+    signals.push(signal);
+  };
+  apply(/reproducibility.{0,120}(?:public release|release|files|code|weights|scripts)/, 8, "reproducibility-release");
+  apply(/(?:we|authors?)\s+(?:publicly\s+)?release.{0,160}(?:files|code|weights|scripts|implementation)/, 8, "author-release");
+  apply(/scripts?\s+(?:needed|required)\s+to\s+reproduce/, 8, "reproduction-scripts");
+  apply(/(?:official|our)\s+(?:code|implementation|repository)/, 7, "official-code");
+  apply(/(?:source\s+code|code|implementation)\s+(?:is\s+)?(?:available|released|at|:)/, 6, "code-availability");
+  apply(/(?:complete|full)\s+experiment\s+log/, 4, "experiment-log-release");
+  apply(/(?:following|based\s+on|adopt(?:ing)?|uses?|using)\s+\[[^\]]*\]?[^.]{0,80}/, -5, "referenced-method");
+  apply(/(?:baseline|prior\s+work|dependency|third[- ]party|library|reference\s+implementation)\s+(?:code|repository|implementation)|(?:code|repository|implementation)\s+(?:for|from)\s+(?:the\s+)?(?:baseline|prior\s+work|dependency|third[- ]party)/, -5, "non-primary-code");
+  return { score, signals };
+}
+
+function githubEvidenceSearchQuery(title, paperText) {
+  const seed = typeof title === "string" && title.trim()
+    ? title
+    : paperText.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length >= 30);
+  if (!seed) return null;
+  const words = seed
+    .replaceAll(/[^a-zA-Z0-9]+/g, " ")
+    .split(/\s+/)
+    .filter((word) => word.length >= 4)
+    .slice(0, 7);
+  if (words.length < 4) return null;
+  return `"${words.slice(0, 4).join(" ")}" ${words.slice(4).join(" ")} in:readme`;
+}
+
+function normalizeIdentityText(value) {
+  return typeof value === "string"
+    ? value.normalize("NFKD").toLowerCase().replaceAll(/[^a-z0-9]+/g, "")
+    : "";
+}
+
+function paperTitleCandidates(title, paperText) {
+  const lines = paperText
+    .slice(0, 12_000)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length >= 12 && line.length <= 220)
+    .slice(0, 40);
+  const candidates = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    for (let width = 1; width <= 3 && index + width <= lines.length; width += 1) {
+      candidates.push(lines.slice(index, index + width).join(" "));
+    }
+  }
+  if (
+    typeof title === "string" &&
+    title.trim() &&
+    candidates.some((candidate) => titleIdentitySimilarity(title, candidate) >= 0.9)
+  ) {
+    candidates.push(title);
+  }
+  return candidates;
+}
+
+function titleIdentitySimilarity(left, right) {
+  const leftTokens = titleIdentityTokens(left);
+  const rightTokens = titleIdentityTokens(right);
+  if (leftTokens.size < 7 || rightTokens.size < 7) return 0;
+  let shared = 0;
+  for (const token of leftTokens) {
+    if (rightTokens.has(token)) shared += 1;
+  }
+  return (2 * shared) / (leftTokens.size + rightTokens.size);
+}
+
+function titleIdentityTokens(value) {
+  const expanded = String(value ?? "")
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/\br\s+wks?\b/g, " random walk kernel ")
+    .replace(/\brwks?\b/g, " random walk kernel ");
+  const stopWords = new Set(["a", "an", "and", "for", "of", "on", "the", "to"]);
+  return new Set(
+    expanded
+      .split(/[^a-z0-9]+/)
+      .filter((token) => token.length >= 3 && !stopWords.has(token))
+      .map((token) => token.length > 4 && token.endsWith("s") ? token.slice(0, -1) : token),
+  );
+}
+
+function arxivId(value) {
+  if (typeof value !== "string") return null;
+  return value.match(/(?:arxiv(?:\.org\/(?:abs|pdf)\/|\s*[:=]\s*)?)(\d{4}\.\d{4,5})(?:v\d+)?/i)?.[1]
+    ?? value.match(/\b(\d{4}\.\d{4,5})(?:v\d+)?\b/)?.[1]
+    ?? null;
+}
+
+function decodeGitHubContent(value) {
+  if (typeof value?.content !== "string" || value.encoding !== "base64") return "";
+  return Buffer.from(value.content.replaceAll(/\s+/g, ""), "base64").toString("utf8");
+}
+
+async function extractPdfText(paperPath) {
+  // Reading-order extraction keeps wrapped links adjacent. Layout mode can
+  // interleave the other column between `github.com/` and `owner/repo`, which
+  // makes an explicit paper-declared repository impossible to recover safely.
+  const result = await captureProcess("pdftotext", ["-nopgbrk", paperPath, "-"]);
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || `pdftotext exited with ${result.code}`);
+  }
+  return result.stdout.slice(0, MAX_DOCUMENT_BYTES);
+}
+
+async function requestJson(fetchImpl, url, options) {
+  const response = await request(fetchImpl, url, options);
+  return response.json();
+}
+
+async function request(fetchImpl, url, {
+  sleep,
+  now = () => new Date(),
+  observe = () => {},
+  service = "external",
+  operation = "request",
+  headers = {},
+}) {
+  let lastError;
+  const maxAttempts = 3;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const startedAt = now().toISOString();
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        headers: {
+          accept: "application/vnd.github+json, text/html;q=0.9",
+          "user-agent": "CiteArk-Source-Discovery/0.1",
+          "x-github-api-version": "2022-11-28",
+          ...headers,
+        },
+        redirect: "follow",
+        signal: AbortSignal.timeout(20_000),
+      });
+    } catch (error) {
+      lastError = error;
+      recordObservation(observe, externalRequestObservation({
+        component: "source_discovery",
+        service,
+        operation,
+        method: "GET",
+        url,
+        attempt,
+        maxAttempts,
+        startedAt,
+        finishedAt: now().toISOString(),
+        error,
+        retryable: true,
+      }));
+      if (attempt < maxAttempts) await sleep(250 * 2 ** (attempt - 1));
+      continue;
+    }
+    const retryable = retryableResponse(response, service);
+    const responseError = response.ok ? null : requestError(response, retryable);
+    recordObservation(observe, externalRequestObservation({
+      component: "source_discovery",
+      service,
+      operation,
+      method: "GET",
+      url,
+      attempt,
+      maxAttempts,
+      startedAt,
+      finishedAt: now().toISOString(),
+      response,
+      error: responseError,
+      retryable,
+    }));
+    if (response.ok) return response;
+    lastError = responseError;
+    if (!retryable || attempt >= maxAttempts) break;
+    await sleep(retryDelayMilliseconds(response, attempt));
+  }
+  throw lastError ?? new Error("联网请求失败");
+}
+
+function requestError(response, retryable) {
+  const error = new Error(`HTTP ${response.status}`);
+  error.name = "ExternalRequestError";
+  error.status = response.status;
+  error.retryable = retryable;
+  return error;
+}
+
+function retryableResponse(response, service) {
+  if (new Set([408, 425, 429]).has(response.status) || response.status >= 500) return true;
+  // 对公开 GitHub 资源而言，403 既可能是主限额，也可能是未携带标准
+  // 限流头的次级限流/滥用保护。两类都属于暂时性基础设施失败，不能据此
+  // 降级成“论文没有官方仓库”。
+  return service === "github" && response.status === 403;
+}
+
+function retryDelayMilliseconds(response, attempt) {
+  const retryAfter = response.headers.get("retry-after");
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(30_000, seconds * 1_000);
+  }
+  const resetSeconds = Number(response.headers.get("x-ratelimit-reset"));
+  if (Number.isFinite(resetSeconds) && resetSeconds > 0) {
+    return Math.max(0, Math.min(30_000, resetSeconds * 1_000 - Date.now()));
+  }
+  return 250 * 2 ** (attempt - 1);
+}
+
+function recordObservation(observe, observation) {
+  try {
+    observe(observation);
+  } catch {
+    // 日志写入失败不得伪装成上游请求失败。
+  }
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function defaultSleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}