@morehao/dsh-skills-console 0.2.4 → 0.3.1

package/lib/core/lock.js

@@ -0,0 +1,310 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * v3 skill lock（`~/.agents/.skill-lock.json`，或 XDG_STATE_HOME 下）的**唯一写入者**。
+ *
+ * 兼容目标（与 `skills` CLI 落盘格式一致）：
+ * - `version` 必须恰好是 3；>3 视为不认识的新版本，只读并抛 `lock-unsupported`，绝不覆盖。
+ * - JSON 损坏同样抛错；宁可写失败，也不拿空账覆盖用户的 lock。
+ * - 顶层未知字段、每个技能条目的未知字段、`dismissed` 全部原样保留，只动调用方明确要动的键。
+ * - 写入：同目录临时文件 → fsync → rename；写前留 `.bak`；rename 失败时原文件不会被截断。
+ * - `expectedDigest` 用来防止覆盖外部 CLI 刚写入的内容：写前重算，不一致就报冲突。
+ *
+ * 语义边界：只负责文件一致性，不判断技能是否该装、不碰 canonical；事务边界由 installer 负责。
+ */
+
+export const LOCK_VERSION = 3;
+
+const SOURCE_TYPES = new Set(['github', 'local', 'download']);
+const TREE_SHA_RE = /^[0-9a-f]{40}$/;
+const CONTENT_SHA_RE = /^[0-9a-f]{64}$/;
+
+export class LockError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'LockError';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function lockDigest(text) {
+  return crypto.createHash('sha256').update(text).digest('hex');
+}
+
+/**
+ * 读 lock 用于写。返回 `{ present, raw, digest, data }`；
+ * 文件不存在返回 `present:false`（调用方创建空账）；其余异常一律抛 LockError。
+ */
+export function readLockFile(lockPath) {
+  if (typeof lockPath !== 'string' || lockPath.length === 0) {
+    throw new LockError('lock-invalid', 'readLockFile 需要 lock 路径');
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(lockPath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return { present: false, raw: null, digest: null, data: null };
+    }
+    throw new LockError('lock-unreadable', `无法读取 lock: ${error.message}`, { cause: error });
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    throw new LockError('lock-corrupt', `lock 不是合法 JSON: ${error.message}`, { cause: error });
+  }
+  if (!isPlainObject(data)) throw new LockError('lock-corrupt', 'lock 顶层不是对象');
+  if (typeof data.version !== 'number' || !Number.isInteger(data.version)) {
+    throw new LockError('lock-corrupt', 'lock.version 缺失或不是整数');
+  }
+  if (data.version !== LOCK_VERSION) {
+    throw new LockError(
+      'lock-unsupported',
+      `lock.version ${data.version} 不是可写的 v${LOCK_VERSION}，拒绝覆盖`,
+      { version: data.version },
+    );
+  }
+  if (!isPlainObject(data.skills)) throw new LockError('lock-corrupt', 'lock.skills 缺失或不是对象');
+  if (data.dismissed !== undefined && !isPlainObject(data.dismissed)) {
+    throw new LockError('lock-corrupt', 'lock.dismissed 不是对象');
+  }
+  return { present: true, raw, digest: lockDigest(raw), data };
+}
+
+function emptyLock() {
+  return { version: LOCK_VERSION, skills: {}, dismissed: {} };
+}
+
+function assertLockShape(data) {
+  if (!isPlainObject(data)) throw new LockError('lock-invalid', '写回的 lock 不是对象');
+  if (data.version !== LOCK_VERSION) {
+    throw new LockError('lock-invalid', `写回的 lock.version 必须是 ${LOCK_VERSION}`);
+  }
+  if (!isPlainObject(data.skills)) throw new LockError('lock-invalid', '写回的 lock.skills 不是对象');
+  if (data.dismissed !== undefined && !isPlainObject(data.dismissed)) {
+    throw new LockError('lock-invalid', '写回的 lock.dismissed 不是对象');
+  }
+}
+
+function atomicWrite(target, text) {
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(
+    dir,
+    `.${path.basename(target)}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}.tmp`,
+  );
+  let fd = null;
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o644);
+    fs.writeFileSync(fd, text, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tmp, target);
+  } catch (error) {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // 已经关掉就算了，别覆盖原始错误
+      }
+    }
+    fs.rmSync(tmp, { force: true });
+    throw new LockError('lock-write-failed', `写 lock 失败: ${error.message}`, { cause: error });
+  }
+}
+
+/**
+ * 读改写 lock。`mutate(draft)` 直接改 draft（同步）；返回 `{ data, digest, changed, backup }`。
+ *
+ * - `expectedDigest` 传 `null` 表示“写之前必须不存在”；传字符串表示必须等于当前内容摘要；
+ *   不传则不校验。
+ * - 内容没变化时不落盘（不产生 `.bak`、不更新时间戳）。
+ */
+export function updateLock({ lockPath, mutate, expectedDigest } = {}) {
+  if (typeof mutate !== 'function') {
+    throw new LockError('lock-invalid', 'updateLock 需要 mutate 函数');
+  }
+  const current = readLockFile(lockPath);
+  if (expectedDigest !== undefined && current.digest !== expectedDigest) {
+    throw new LockError('lock-conflict', 'lock 在本次操作期间被其他进程修改，拒绝覆盖', {
+      expectedDigest,
+      actualDigest: current.digest,
+    });
+  }
+
+  const draft = current.present ? structuredClone(current.data) : emptyLock();
+  const result = mutate(draft);
+  const next = result === undefined ? draft : result;
+  assertLockShape(next);
+
+  const text = `${JSON.stringify(next, null, 2)}\n`;
+  if (current.present && text === current.raw) {
+    return { data: next, digest: current.digest, changed: false, backup: null };
+  }
+
+  let backup = null;
+  if (current.present) {
+    backup = `${lockPath}.bak`;
+    try {
+      fs.writeFileSync(backup, current.raw, { encoding: 'utf8', mode: 0o644 });
+    } catch (error) {
+      throw new LockError('lock-write-failed', `备份 lock 失败: ${error.message}`, { cause: error });
+    }
+  }
+  atomicWrite(lockPath, text);
+  return { data: next, digest: lockDigest(text), changed: true, backup };
+}
+
+const KNOWN_ENTRY_KEYS = new Set([
+  'source',
+  'sourceType',
+  'sourceUrl',
+  'ref',
+  'skillPath',
+  'skillFolderHash',
+  'installedAt',
+  'updatedAt',
+]);
+
+/**
+ * 新旧条目合并：已知字段以新条目为准（新条目没有 `ref` 就删掉旧的），
+ * 未知字段原样保留 —— 与 CLI 的“不重建整个对象”语义一致，未来 CLI 加字段不会被我们抹掉。
+ */
+function mergeLockEntry(previous, entry) {
+  if (!isPlainObject(previous)) return entry;
+  const merged = {};
+  for (const [key, value] of Object.entries(previous)) {
+    if (!KNOWN_ENTRY_KEYS.has(key)) merged[key] = value;
+  }
+  return { ...merged, ...entry };
+}
+
+/** 安装/更新后写入一个技能条目；`entry` 由 makeLockEntry 或调用方按 CLI 形状构造。 */
+export function upsertSkill({ lockPath, name, entry, expectedDigest } = {}) {
+  assertSkillName(name);
+  assertLockEntry(name, entry);
+  return updateLock({
+    lockPath,
+    expectedDigest,
+    mutate: (draft) => {
+      draft.skills[name] = mergeLockEntry(draft.skills[name], entry);
+    },
+  });
+}
+
+/** 删除一个技能条目；条目本就不存在时视为成功（changed:false）。 */
+export function removeSkill({ lockPath, name, expectedDigest } = {}) {
+  assertSkillName(name);
+  return updateLock({
+    lockPath,
+    expectedDigest,
+    mutate: (draft) => {
+      delete draft.skills[name];
+    },
+  });
+}
+
+function assertSkillName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new LockError('lock-invalid', '技能名必须是非空字符串');
+  }
+  if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+    throw new LockError('lock-invalid', `技能名不能含路径分隔符: ${name}`);
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(name)) {
+    throw new LockError('lock-invalid', `技能名不能含控制字符: ${JSON.stringify(name)}`);
+  }
+}
+
+function isIsoDate(value) {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  const time = Date.parse(value);
+  return Number.isFinite(time);
+}
+
+/**
+ * 校验一条 lock 条目。允许 40 位 tree SHA 或旧数据的 64 位内容 hash，
+ * 但 `makeLockEntry` 只产出 40 位 —— 新安装绝不用内容 hash 冒充 tree SHA。
+ */
+export function assertLockEntry(name, entry) {
+  const fail = (message) => {
+    throw new LockError('lock-invalid', `${name}: ${message}`);
+  };
+  if (!isPlainObject(entry)) fail('条目不是对象');
+  if (typeof entry.source !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(entry.source)) {
+    fail('source 不是 owner/repo');
+  }
+  if (!SOURCE_TYPES.has(entry.sourceType)) fail(`sourceType 不认识: ${entry.sourceType}`);
+  if (typeof entry.sourceUrl !== 'string' || !entry.sourceUrl.startsWith('https://')) {
+    fail('sourceUrl 必须是 https URL');
+  }
+  if (typeof entry.skillPath !== 'string' || entry.skillPath.length === 0) fail('skillPath 缺失');
+  if (
+    entry.skillPath.startsWith('/') ||
+    entry.skillPath.includes('\\') ||
+    entry.skillPath.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+  ) {
+    fail(`skillPath 不是安全的 POSIX 相对路径: ${entry.skillPath}`);
+  }
+  if (!entry.skillPath.endsWith('.md')) fail('skillPath 应指向 .md 文件');
+  if (typeof entry.skillFolderHash !== 'string') fail('skillFolderHash 缺失');
+  if (!TREE_SHA_RE.test(entry.skillFolderHash) && !CONTENT_SHA_RE.test(entry.skillFolderHash)) {
+    fail('skillFolderHash 既不是 40 位 tree SHA 也不是 64 位内容 hash');
+  }
+  if (!isIsoDate(entry.installedAt)) fail('installedAt 不是 ISO 时间');
+  if (!isIsoDate(entry.updatedAt)) fail('updatedAt 不是 ISO 时间');
+  if (entry.ref !== undefined && entry.ref !== null) {
+    if (typeof entry.ref !== 'string' || entry.ref.length === 0 || entry.ref.length > 200) {
+      fail('ref 不是合法字符串');
+    }
+    if (!/^[A-Za-z0-9._/-]+$/.test(entry.ref) || entry.ref.includes('..')) fail(`ref 含非法字符: ${entry.ref}`);
+  }
+  return entry;
+}
+
+/**
+ * 按 CLI 落盘形状构造条目（键顺序照 skills@1.7.4：source / sourceType / sourceUrl /
+ * [ref] / skillPath / skillFolderHash / installedAt / updatedAt）。
+ * `ref` 为空时直接省略（CLI 对默认分支安装就是这么写的）。
+ */
+export function makeLockEntry({
+  source,
+  ref = null,
+  skillPath,
+  treeSha,
+  installedAt,
+  updatedAt,
+  now = new Date(),
+} = {}) {
+  const normalized = typeof source === 'string' ? source.trim().replace(/\.git$/, '') : source;
+  if (typeof normalized !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(normalized)) {
+    throw new LockError('lock-invalid', `source 必须是 owner/repo: ${source}`);
+  }
+  if (typeof treeSha !== 'string' || !TREE_SHA_RE.test(treeSha)) {
+    throw new LockError('lock-invalid', `treeSha 必须是 40 位小写 hex: ${treeSha}`);
+  }
+  const stamp = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
+  const entry = {
+    source: normalized,
+    sourceType: 'github',
+    sourceUrl: `https://github.com/${normalized}.git`,
+  };
+  if (ref !== null && ref !== undefined) entry.ref = ref;
+  entry.skillPath = skillPath;
+  entry.skillFolderHash = treeSha;
+  entry.installedAt = installedAt === undefined ? stamp : installedAt;
+  entry.updatedAt = updatedAt === undefined ? stamp : updatedAt;
+  assertLockEntry(source, entry);
+  return entry;
+}

package/lib/core/remote.js

@@ -0,0 +1,332 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { extractTarball } from './archive.js';
+import { discoverSkills } from './discovery.js';
+import { gitTreeSha } from './git-tree.js';
+import { parseSource } from './updates.js';
+
+/**
+ * 远端通道：codeload tarball、Atom commit feed、限流时的快照扫描。
+ *
+ * 安全边界（与设计文档 §安全一致）：
+ * - 只接受 HTTPS，只允许 GitHub 的 host；重定向手动跟随，跨 host 一律拒绝并剥离 Authorization。
+ * - token 只进 header，绝不拼进 URL、错误消息或日志。
+ * - 响应 `content-length` 与流式累计双重限额，超限立即中止并删掉半截文件。
+ * - 默认 60s 超时；超时/中止都抛 RemoteError，不留下半写文件。
+ */
+
+export const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+export const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_REDIRECTS = 5;
+const ALLOWED_HOSTS = new Set([
+  'codeload.github.com',
+  'github.com',
+  'objects.githubusercontent.com',
+  'raw.githubusercontent.com',
+]);
+
+export class RemoteError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'RemoteError';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+/** commit（40 位）或分支/tag；分支里的 `/` 是合法的，但 `..`/空白/反斜杠不行。 */
+export function assertRef(ref) {
+  if (typeof ref !== 'string' || ref.length === 0 || ref.length > 200) {
+    throw new RemoteError('invalid-ref', 'ref 必须是非空字符串');
+  }
+  if (!/^[A-Za-z0-9._/-]+$/.test(ref) || ref.includes('..') || ref.startsWith('/') || ref.endsWith('/')) {
+    throw new RemoteError('invalid-ref', `ref 含非法字符: ${ref}`);
+  }
+  return ref;
+}
+
+export function codeloadUrl({ source, ref }) {
+  const parsed = parseSource(source);
+  if (!parsed) throw new RemoteError('invalid-source', `不是 GitHub 来源: ${source}`);
+  assertRef(ref);
+  return `https://codeload.github.com/${parsed.owner}/${parsed.repo}/tar.gz/${ref}`;
+}
+
+function assertAllowedUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new RemoteError('redirect-rejected', `重定向目标不是合法 URL: ${url}`);
+  }
+  if (parsed.protocol !== 'https:') {
+    throw new RemoteError('redirect-rejected', `只允许 HTTPS: ${url}`);
+  }
+  if (!ALLOWED_HOSTS.has(parsed.hostname)) {
+    throw new RemoteError('redirect-rejected', `不允许的 host: ${parsed.hostname}`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new RemoteError('redirect-rejected', '重定向目标不能带 userinfo');
+  }
+  return parsed;
+}
+
+function tooLarge(maxBytes, bytes) {
+  return new RemoteError('tarball-too-large', `tarball 超过 ${maxBytes} 字节上限（已收到 ${bytes}）`, {
+    maxBytes,
+    bytes,
+  });
+}
+
+const ATOM_ID_RE = /<id>tag:github\.com,2008:Grit::Commit\/([0-9a-f]{40})<\/id>/i;
+const ATOM_LINK_RE = /https:\/\/github\.com\/[^"<\s]+\/commit\/([0-9a-f]{40})/i;
+
+/** 从 GitHub 的 commits Atom feed 里取第一条 commit（feed 按时间倒序）。 */
+export function parseAtomCommit(text) {
+  const body = String(text || '');
+  const match = ATOM_ID_RE.exec(body) || ATOM_LINK_RE.exec(body);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Atom commit feed：`/commits/<ref>.atom`（不带 ref 即默认分支）。
+ * 不占 REST 配额，也不需要 `--json` / git；失败抛 RemoteError，由调用方决定是否降级。
+ */
+export async function fetchAtomCommit({
+  source,
+  ref = null,
+  token = null,
+  fetchImpl = fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const parsed = parseSource(source);
+  if (!parsed) throw new RemoteError('bad-source', `只接受 owner/repo 或 GitHub URL: ${source}`);
+  if (ref !== null) assertRef(ref);
+  const refPath = ref ? `/${ref.split('/').map(encodeURIComponent).join('/')}` : '';
+  const url = `https://github.com/${parsed.owner}/${parsed.repo}/commits${refPath}.atom`;
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  timer.unref?.();
+  try {
+    const headers = { accept: 'application/atom+xml', 'user-agent': 'dsh-skills-console' };
+    if (token) headers.authorization = `Bearer ${token}`;
+    let response;
+    try {
+      response = await fetchImpl(url, { headers, signal: controller.signal });
+    } catch (error) {
+      if (timedOut) throw new RemoteError('timeout', `读取 Atom 超时（${timeoutMs}ms）`, { cause: error });
+      throw new RemoteError('network', `读取 Atom 失败: ${error.message}`, { cause: error });
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      throw new RemoteError('http-error', `HTTP ${response.status}: ${text.slice(0, 200)}`, {
+        status: response.status,
+      });
+    }
+    const commit = parseAtomCommit(await response.text());
+    if (!commit) throw new RemoteError('atom-empty', 'Atom feed 里没有 commit');
+    return { commit, url, status: response.status };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function skillDirOf(skillPath) {
+  const index = skillPath.lastIndexOf('/');
+  return index < 0 ? '' : skillPath.slice(0, index);
+}
+
+/**
+ * 用 codeload tarball 组装一份与 REST 同形的快照（限流兜底）。
+ * 只在临时目录里解压/扫描；rootSha 与每个 skill 的 treeSha 都在本地算。
+ */
+export async function snapshotFromTarball({
+  source,
+  commit,
+  ref = null,
+  subpath = null,
+  token = null,
+  fetchImpl = fetch,
+  maxBytes = DEFAULT_MAX_BYTES,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const parsed = parseSource(source);
+  if (!parsed) throw new RemoteError('bad-source', `只接受 owner/repo 或 GitHub URL: ${source}`);
+  if (typeof commit !== 'string' || !/^[0-9a-f]{40}$/i.test(commit)) {
+    throw new RemoteError('missing-commit', 'codeload 快照需要 40 位 commit');
+  }
+  const repo = `${parsed.owner}/${parsed.repo}`;
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'dshsc-scan-'));
+  try {
+    const tarball = path.join(work, 'repo.tar.gz');
+    await downloadTarball({ source: repo, ref: commit, dest: tarball, token, fetchImpl, maxBytes, timeoutMs });
+    const extracted = await extractTarball({ tarball, dest: path.join(work, 'stage') });
+    let skills;
+    try {
+      skills = discoverSkills({ dir: extracted.dir, subpath, repoName: parsed.repo });
+    } catch (error) {
+      throw new RemoteError('scan-failed', `扫描快照失败: ${error.message}`, { cause: error, code: error.code });
+    }
+    let rootSha;
+    try {
+      rootSha = gitTreeSha(extracted.dir);
+    } catch (error) {
+      throw new RemoteError('scan-failed', `计算 root tree 失败: ${error.message}`, { cause: error });
+    }
+    const entries = [];
+    const tree = [];
+    const seenDirs = new Set();
+    for (const skill of skills) {
+      let treeSha;
+      try {
+        treeSha = gitTreeSha(skill.dirPath);
+      } catch (error) {
+        throw new RemoteError('scan-failed', `计算 ${skill.name} tree 失败: ${error.message}`, { cause: error });
+      }
+      entries.push({ name: skill.name, skillPath: skill.skillPath, treeSha });
+      const dir = skillDirOf(skill.skillPath);
+      if (dir && !seenDirs.has(dir)) {
+        seenDirs.add(dir);
+        tree.push({ path: dir, type: 'tree', sha: treeSha });
+      }
+      // blob 条目只用于判定「skillPath 是否还在」；真正比对用目录 treeSha
+      tree.push({ path: skill.skillPath, type: 'blob' });
+    }
+    return {
+      branch: ref || null,
+      via: 'codeload',
+      tree,
+      rootSha,
+      snapshot: {
+        commit: commit.toLowerCase(),
+        rootSha,
+        entries,
+        fetchedAt: new Date().toISOString(),
+        etag: null,
+      },
+    };
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/**
+ * 把 codeload tarball 下载到 `dest`。`dest` 的父目录必须已存在。
+ * 成功返回 `{ file, bytes, url }`；任何失败都会删除 `dest` 并抛 RemoteError。
+ */
+export async function downloadTarball({
+  source,
+  ref,
+  token,
+  dest,
+  fetchImpl = fetch,
+  maxBytes = DEFAULT_MAX_BYTES,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  signal: externalSignal,
+} = {}) {
+  if (typeof dest !== 'string' || dest.length === 0) {
+    throw new RemoteError('invalid-dest', 'downloadTarball 需要 dest 文件路径');
+  }
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+    throw new RemoteError('invalid-limit', 'maxBytes 必须是正数');
+  }
+
+  const initialUrl = codeloadUrl({ source, ref });
+
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer =
+    Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          controller.abort();
+        }, timeoutMs)
+      : null;
+  const signal = externalSignal ? AbortSignal.any([controller.signal, externalSignal]) : controller.signal;
+
+  let url = initialUrl;
+  const authHost = new URL(initialUrl).hostname;
+  let handle = null;
+  let declared = null;
+  try {
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+      const headers = {
+        accept: 'application/x-gzip',
+        'user-agent': 'dsh-skills-console',
+      };
+      // token 只发给最初那个 host；跨 host 重定向一律剥离，避免泄漏到 CDN/第三方。
+      const currentHost = new URL(url).hostname;
+      if (token && currentHost === authHost) headers.authorization = `Bearer ${token}`;
+
+      let response;
+      try {
+        response = await fetchImpl(url, { headers, redirect: 'manual', signal });
+      } catch (error) {
+        if (timedOut) throw new RemoteError('timeout', `下载超时（${timeoutMs}ms）`, { cause: error });
+        if (signal.aborted) throw new RemoteError('aborted', '下载已中止', { cause: error });
+        throw new RemoteError('download-failed', `下载失败: ${error.message}`, { cause: error });
+      }
+
+      if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get('location');
+        await response.body?.cancel().catch(() => {});
+        if (!location) throw new RemoteError('redirect-rejected', `HTTP ${response.status} 缺少 Location`);
+        if (hop === MAX_REDIRECTS) {
+          throw new RemoteError('redirect-rejected', `重定向超过 ${MAX_REDIRECTS} 次`);
+        }
+        const next = assertAllowedUrl(new URL(location, url).toString());
+        // 跨 host 时不沿用上一跳的 Authorization：下一轮按新 host 重新决定。
+        url = next.toString();
+        continue;
+      }
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new RemoteError('http-error', `HTTP ${response.status}: ${text.slice(0, 200)}`, {
+          status: response.status,
+        });
+      }
+
+      const lengthHeader = response.headers.get('content-length');
+      declared = lengthHeader === null ? null : Number(lengthHeader);
+      if (declared !== null && Number.isFinite(declared) && declared > maxBytes) {
+        throw tooLarge(maxBytes, declared);
+      }
+      if (!response.body) throw new RemoteError('download-failed', '响应没有 body');
+
+      handle = await fs.promises.open(dest, 'w');
+      let bytes = 0;
+      for await (const chunk of response.body) {
+        bytes += chunk.byteLength;
+        if (bytes > maxBytes) throw tooLarge(maxBytes, bytes);
+        let offset = 0;
+        while (offset < chunk.byteLength) {
+          const { bytesWritten } = await handle.write(chunk, offset, chunk.byteLength - offset);
+          offset += bytesWritten;
+        }
+      }
+      if (bytes === 0) throw new RemoteError('download-failed', '响应为空');
+      if (declared !== null && Number.isFinite(declared) && bytes !== declared) {
+        throw new RemoteError('truncated-download', `下载不完整：声明 ${declared} 字节，实际 ${bytes} 字节`);
+      }
+      await handle.close();
+      handle = null;
+      return { file: dest, bytes, url };
+    }
+    // 循环正常结束只可能是重定向用尽，上面的 hop 判断已抛错。
+    throw new RemoteError('redirect-rejected', '重定向次数过多');
+  } catch (error) {
+    if (handle) await handle.close().catch(() => {});
+    await fs.promises.unlink(dest).catch(() => {});
+    if (error instanceof RemoteError) throw error;
+    if (timedOut) throw new RemoteError('timeout', `下载超时（${timeoutMs}ms）`, { cause: error });
+    throw new RemoteError('download-failed', `下载失败: ${error.message}`, { cause: error });
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}