Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

12.1 KB
Raw Blame
/**
 * fetch-with-timeout — 给 agent 二进制下载链路的上游请求加超时控制。
 *
 * 背景:claude/codex/ripgrep 二进制移出 LFS 后改为从上游(downloads.claude.ai / api.github.com)
 * 按需下载,国内网络常出现"连不上 / 卡死 / 持续低速拖很久"三类慢。裸 `fetch` 没有超时,
 * 慢的时候会一直挂住,既不报错也不回退。本模块把这几类慢都转成可识别的 TimeoutError,
 * 让上层(ensure-agent-binaries)据此回退到国内 CDN 兜底。
 *
 * 四类超时(均可经 env 覆盖,无需改代码即可按个人网络实测调):
 *   - connectTimeoutMs (XDT_AGENTBIN_CONNECT_TIMEOUT_MS, 默认 10s): 拿到响应头的超时(连不上)
 *   - stallTimeoutMs   (XDT_AGENTBIN_STALL_TIMEOUT_MS,   默认 15s): 下载中连续无字节进展(卡死)
 *   - totalTimeoutMs   (XDT_AGENTBIN_TOTAL_TIMEOUT_MS,   默认 30min): 整段下载总时长上限(无限拖兜底)
 *     (二进制体量已到百 MB 级,国内直连官方源实测 ~1MB/s,旧的 60s 上限会掐断正常慢速下载;
 *      "连不上/卡死"仍由 connect/stall 快速兜底,total 只防"无限拖",故放宽到 30min。
 *      注意 30min 默认只用于大文件下载;JSON 元数据小请求默认仍 60s,见 fetchJsonWithTimeout)
 *   - minThroughputBytesPerSec (XDT_AGENTBIN_MIN_THROUGHPUT_BPS, 默认 200KB/s,0 = 禁用):
 *     滚动窗口平均吞吐下限(持续低速)。窗口 throughputWindowMs
 *     (XDT_AGENTBIN_THROUGHPUT_WINDOW_MS, 默认 30s) 内平均速度低于下限即放弃——
 *     这是"龟速但一直有进展"场景的主判定:stall 只认零字节抓不到它,等 total 30min 又太久。
 *     窗口攒满一整段才开始评估(下载起步/瞬时抖动不计),阈值按"上游正常 ~1MB/s、CDN 兜底
 *     可用"标定。⚠️ 只有"放弃后有别处可去"的调用方才应启用:install 链路
 *     (ensure-agent-binaries → ensurePlatform,有 CDN 兜底)开启;update CLI 直连上游
 *     无兜底、CDN 兜底自身是最后一道,均显式传 0 禁用——没有退路时掐断只会把
 *     "慢但能成"变成失败。
 *
 * 纯 node(被 tools/<kind>/update.mjs 与 scripts/agent-binary-cdn-fallback.mjs 复用)——
 * 不能依赖 Electron 的 main 进程 downloader(那个 import 了 electron 的 net)。
 */

import fs from 'node:fs';
import path from 'node:path';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

/** 可识别的超时错误;kind 区分是哪类超时,便于日志与上层判断。 */
export class TimeoutError extends Error {
  constructor(message, kind) {
    super(message);
    this.name = 'TimeoutError';
    this.code = 'TIMEOUT';
    this.kind = kind; // 'connect' | 'stall' | 'total' | 'throughput'
  }
}

const DEFAULTS = {
  connectTimeoutMs: 10_000,
  stallTimeoutMs: 15_000,
  totalTimeoutMs: 1_800_000,
  minThroughputBytesPerSec: 200_000,
  throughputWindowMs: 30_000,
};

function envInt(name, fallback) {
  const raw = process.env[name];
  if (!raw) return fallback;
  const n = Number.parseInt(raw, 10);
  return Number.isFinite(n) && n > 0 ? n : fallback;
}

/** 同 envInt,但 0 是合法值(吞吐下限的 0 = 禁用检查)。 */
function envIntAllowZero(name, fallback) {
  const raw = process.env[name];
  if (!raw) return fallback;
  const n = Number.parseInt(raw, 10);
  return Number.isFinite(n) && n >= 0 ? n : fallback;
}

/** 解析各超时/吞吐阈值:显式入参 > env 覆盖 > 默认值。 */
export function resolveTimeouts(overrides = {}) {
  return {
    connectTimeoutMs: overrides.connectTimeoutMs ?? envInt('XDT_AGENTBIN_CONNECT_TIMEOUT_MS', DEFAULTS.connectTimeoutMs),
    stallTimeoutMs: overrides.stallTimeoutMs ?? envInt('XDT_AGENTBIN_STALL_TIMEOUT_MS', DEFAULTS.stallTimeoutMs),
    totalTimeoutMs: overrides.totalTimeoutMs ?? envInt('XDT_AGENTBIN_TOTAL_TIMEOUT_MS', DEFAULTS.totalTimeoutMs),
    minThroughputBytesPerSec:
      overrides.minThroughputBytesPerSec ?? envIntAllowZero('XDT_AGENTBIN_MIN_THROUGHPUT_BPS', DEFAULTS.minThroughputBytesPerSec),
    throughputWindowMs: overrides.throughputWindowMs ?? envInt('XDT_AGENTBIN_THROUGHPUT_WINDOW_MS', DEFAULTS.throughputWindowMs),
  };
}

/** fetch 因我方 abort 而失败时,把 reason(TimeoutError)取回;否则原样 rethrow。 */
function rethrowAbort(err, controller) {
  const reason = controller.signal.reason;
  if (reason instanceof TimeoutError) return reason;
  if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
    return new TimeoutError(`aborted: ${err.message}`, 'connect');
  }
  return err;
}

/** JSON 元数据请求的默认 deadline——小请求不适用下载的 30min 默认,挂住 60s 就该报错。 */
const JSON_TOTAL_TIMEOUT_MS = 60_000;

/** 进度行渲染(纯函数,便于测试):`42% 84.0/200.0MB @ 1.2MB/s`;总大小未知时省略百分比。 */
export function formatProgressLine({ receivedBytes, totalBytes, bytesPerSec }) {
  const mb = (n) => (n / 1024 / 1024).toFixed(1);
  const speed = `${mb(bytesPerSec)}MB/s`;
  if (totalBytes) {
    const pct = Math.min(100, Math.floor((receivedBytes / totalBytes) * 100));
    return `${pct}% ${mb(receivedBytes)}/${mb(totalBytes)}MB @ ${speed}`;
  }
  return `${mb(receivedBytes)}MB @ ${speed}`;
}

/**
 * 下载进度渲染器:返回 { onProgress, finish },onProgress 接给 downloadToFileWithTimeout,
 * finish 在下载结束(无论成败)后调用收尾。
 * - TTY:单行 \r 原地刷新(默认每 500ms),finish 补换行,不留半行残迹。
 * - 非 TTY(agent / CI / 重定向日志):降频整行输出(默认每 5s),避免进度刷屏。
 * options.writeLine 可注入输出通道(测试用);注入后 finish 不再补换行。
 */
export function createDownloadProgressLogger(label, options = {}) {
  const isTTY = options.isTTY ?? Boolean(process.stdout.isTTY);
  const intervalMs = options.intervalMs ?? (isTTY ? 500 : 5_000);
  const writeLine = options.writeLine ?? null;
  let lastPrintAt = 0;
  let lastBytes = 0;
  let lastAt = Date.now();
  let printedInPlace = false;

  const onProgress = ({ receivedBytes, totalBytes }) => {
    const now = Date.now();
    if (now - lastPrintAt < intervalMs) return;
    const bytesPerSec = ((receivedBytes - lastBytes) * 1000) / Math.max(1, now - lastAt);
    lastPrintAt = now;
    lastBytes = receivedBytes;
    lastAt = now;
    const line = `  [${label}] ${formatProgressLine({ receivedBytes, totalBytes, bytesPerSec })}`;
    if (writeLine) {
      writeLine(line);
    } else if (isTTY) {
      process.stdout.write(`\r${line.padEnd(64)}`);
      printedInPlace = true;
    } else {
      console.log(line);
    }
  };

  const finish = () => {
    if (printedInPlace) {
      process.stdout.write('\n');
      printedInPlace = false;
    }
  };

  return { onProgress, finish };
}

/**
 * 小请求(JSON 元数据):fetch + 读取 JSON,单一 deadline 覆盖整段。
 * deadline 取值:显式入参 > XDT_AGENTBIN_TOTAL_TIMEOUT_MS > 60s(不是下载的 30min 默认)。
 * 失败(非 2xx / 超时 / 网络错)抛错;成功返回已解析的 JSON。
 */
export async function fetchJsonWithTimeout(url, init = {}, overrides = {}) {
  const totalTimeoutMs = overrides.totalTimeoutMs ?? envInt('XDT_AGENTBIN_TOTAL_TIMEOUT_MS', JSON_TOTAL_TIMEOUT_MS);
  const controller = new AbortController();
  const timer = setTimeout(
    () => controller.abort(new TimeoutError(`timeout ${totalTimeoutMs}ms fetching ${url}`, 'total')),
    totalTimeoutMs,
  );
  try {
    const res = await fetch(url, { ...init, signal: controller.signal });
    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}: ${url}`);
    return await res.json();
  } catch (err) {
    throw rethrowAbort(err, controller);
  } finally {
    clearTimeout(timer);
  }
}

/**
 * 大文件流式下载到 destPath,带 connect / stall / total / throughput 四类超时。
 * 经 `${destPath}.part` 中转后原子 rename,失败清理残留。
 * overrides.onProgress?: ({ receivedBytes, totalBytes }) => void —— body 每收到一块数据回调一次,
 * totalBytes 来自 Content-Length(chunked 响应拿不到时为 null);回调抛错不影响下载。
 * 返回 { size }。非 2xx / 超时 / 网络错均抛错(TimeoutError 或带 status 的 Error)。
 */
export async function downloadToFileWithTimeout(url, destPath, init = {}, overrides = {}) {
  const { connectTimeoutMs, stallTimeoutMs, totalTimeoutMs, minThroughputBytesPerSec, throughputWindowMs } =
    resolveTimeouts(overrides);
  const onProgress = typeof overrides.onProgress === 'function' ? overrides.onProgress : null;
  const controller = new AbortController();
  let lastProgress = Date.now();
  let totalBytes = 0;
  let bodyStarted = false;

  const connectTimer = setTimeout(
    () => controller.abort(new TimeoutError(`connect timeout ${connectTimeoutMs}ms: ${url}`, 'connect')),
    connectTimeoutMs,
  );
  const totalTimer = setTimeout(
    () => controller.abort(new TimeoutError(`total timeout ${totalTimeoutMs}ms: ${url}`, 'total')),
    totalTimeoutMs,
  );
  // stall:周期性检查"距上次收到字节"是否超过 stallTimeoutMs。
  const stallTimer = setInterval(() => {
    if (Date.now() - lastProgress > stallTimeoutMs) {
      controller.abort(new TimeoutError(`stall timeout ${stallTimeoutMs}ms (no bytes): ${url}`, 'stall'));
    }
  }, Math.min(stallTimeoutMs, 5_000));
  if (typeof stallTimer.unref === 'function') stallTimer.unref();

  // throughput:body 阶段每 tick 采样累计字节数,窗口攒满一整段后按
  // "窗口内平均速度 < 下限"判定持续低速——stall 抓不到"有进展但龟速",这里补上。
  // 采样保留一个落在窗口起点之前的 baseline,保证评估跨度 ≥ 完整窗口。
  const samples = [];
  let throughputTimer = null;
  if (minThroughputBytesPerSec > 0) {
    const tickMs = Math.max(100, Math.min(Math.floor(throughputWindowMs / 4), 5_000));
    throughputTimer = setInterval(() => {
      if (!bodyStarted) return;
      const now = Date.now();
      samples.push({ t: now, bytes: totalBytes });
      while (samples.length > 1 && samples[1].t <= now - throughputWindowMs) samples.shift();
      const baseline = samples[0];
      if (now - baseline.t < throughputWindowMs) return; // 窗口未攒满,不评估
      const bps = ((totalBytes - baseline.bytes) * 1000) / (now - baseline.t);
      if (bps < minThroughputBytesPerSec) {
        controller.abort(new TimeoutError(
          `throughput below ${minThroughputBytesPerSec}B/s over ${throughputWindowMs}ms (avg ${Math.round(bps)}B/s): ${url}`,
          'throughput',
        ));
      }
    }, tickMs);
    if (typeof throughputTimer.unref === 'function') throughputTimer.unref();
  }

  const partPath = `${destPath}.part`;
  try {
    const res = await fetch(url, { ...init, signal: controller.signal });
    clearTimeout(connectTimer); // 响应头已到,连接超时解除(stall + total + throughput 接管 body 阶段)
    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}: ${url}`);
    if (!res.body) throw new Error(`Empty response body: ${url}`);

    fs.mkdirSync(path.dirname(destPath), { recursive: true });
    bodyStarted = true;
    const contentLength = Number(res.headers.get('content-length'));
    const expectedTotal = Number.isFinite(contentLength) && contentLength > 0 ? contentLength : null;
    const body = Readable.fromWeb(res.body);
    body.on('data', (chunk) => {
      lastProgress = Date.now();
      totalBytes += chunk.length;
      if (onProgress) {
        try { onProgress({ receivedBytes: totalBytes, totalBytes: expectedTotal }); } catch { /* 进度回调不影响下载 */ }
      }
    });
    await pipeline(body, fs.createWriteStream(partPath));

    fs.renameSync(partPath, destPath);
    return { size: fs.statSync(destPath).size };
  } catch (err) {
    try { fs.rmSync(partPath, { force: true }); } catch { /* ignore */ }
    throw rethrowAbort(err, controller);
  } finally {
    clearTimeout(connectTimer);
    clearTimeout(totalTimer);
    clearInterval(stallTimer);
    if (throughputTimer) clearInterval(throughputTimer);
  }
}