@avantf/dsh-plugin-base 0.3.1 → 0.4.0

package/dist/net.d.ts

@@ -3,15 +3,118 @@ import type { ProgressEvent, ProviderContext } from './types.js';
 export declare function fetchImplOf(ctx: ProviderContext): typeof fetch;
 /** Default hard byte cap for one downloaded body. */
 export declare const DEFAULT_MAX_BYTES: number;
+/**
+ * Hard byte cap for a METADATA body: an npm packument, a model revision response, a siblings list.
+ *
+ * Metadata is a small JSON document that is then `JSON.parse`d (`providers/npm.ts`,
+ * `providers/model.ts`), and parsing amplifies it several-fold in heap. The 256 MiB archive cap only
+ * stops the extreme; it still lets a "KB-scale document, GB-scale heap" through.
+ *
+ * 16 MiB is MEASURED, not guessed. The npm provider asks for `accept: application/json`, i.e. the
+ * FULL packument, so the real sizes are the full ones (registry.npmjs.org, 2026-10-02):
+ * `lodash` 0.2 MB, `react` 6.7 MB, `aws-sdk` 10.1 MB, `@types/node` 11.2 MB, `typescript` 15.7 MB.
+ * 16 MiB keeps every ordinary package installable with headroom while bounding the parse to a
+ * four-digit number of MB. The largest packuments on the registry (`npm`, 25.8 MB) now fail
+ * terminally as `fetch/too-large` — the intended fail-closed answer for a document that would
+ * otherwise be parsed into a multi-GB heap. Anything in that range wants a streamed download with a
+ * real cap, not `JSON.parse`. (The abbreviated form — `accept: application/vnd.npm.install-v1+json`
+ * — measured 2–10× smaller on the same packages, e.g. `npm` 25.8 MB → 2.5 MB and `typescript`
+ * 15.7 MB → 8.7 MB; switching to it would be a separate, observable change to what the provider
+ * reads, so it is recorded here as an option rather than done silently.)
+ */
+export declare const METADATA_MAX_BYTES: number;
 /** Default per-request timeout in milliseconds. */
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 300000;
-/** Combine the caller's `AbortSignal` with a timeout signal. */
+/**
+ * Combine the caller's `AbortSignal` with a timeout signal.
+ *
+ * `timeoutMs` (or, when omitted, the item's `policy.timeoutMs`) is the item's per-request budget;
+ * an undeclared value keeps the 300 s default. `0` means NO timeout — the escape hatch a 2 GiB model
+ * needs on a link slower than ~7 MB/s, which the fixed default could never finish. `ctx.signal`
+ * (shutdown/caller abort) still applies in every case.
+ */
 export declare function signalFor(ctx: ProviderContext, timeoutMs?: number): AbortSignal;
-/** Read a response body with a hard byte cap; throws `fetch/failed` when the cap is crossed. */
+/**
+ * Bodies at or below this size are assembled in memory exactly as before; a larger body is handed to
+ * a caller-supplied {@link BodySpill} instead, so the peak cost of a download stops tracking the file
+ * size. The threshold is the ONLY switch, which keeps the common path (a packument, a tarball, a small
+ * model file) on the untouched, simplest code while a multi-GB model — the case measured at roughly 2×
+ * its size in RSS — streams one chunk at a time.
+ *
+ * 64 MiB is a deliberate middle: every ordinary body stays in memory, and when one does not, the
+ * in-memory cost is already bounded by `2 × spillAtBytes` (the chunks plus the joined copy) regardless
+ * of how large the body turns out to be.
+ */
+export declare const SPILL_THRESHOLD_BYTES: number;
+/**
+ * Where a body that outgrew the in-memory budget goes instead of a `Uint8Array`.
+ *
+ * `readCappedOrSpill` writes each chunk in arrival order (the prefix that was already buffered is
+ * replayed first) and then calls EXACTLY ONE of `finish` (the body ended and its length checked out) or
+ * `abort` (any failure, including the cap being crossed or a declared/actual mismatch). A sink must
+ * therefore never assume `finish` follows `write`: the reader can reject mid-body.
+ */
+export interface BodySpill<T> {
+    /** Append one chunk; awaiting it may apply backpressure. */
+    write(chunk: Uint8Array): Promise<void>;
+    /** The body is complete and length-checked; flush it and produce the caller's result. */
+    finish(total: number): Promise<T>;
+    /** Discard everything written so far. Must be safe to call after `finish` failed, and must not throw. */
+    abort(): Promise<void>;
+}
+/** Options of {@link readCappedOrSpill}. */
+export interface CappedReadOptions<T> {
+    /** Hard cap; defaults to {@link DEFAULT_MAX_BYTES}. */
+    readonly maxBytes?: number;
+    /** Defaults to {@link SPILL_THRESHOLD_BYTES}. */
+    readonly spillAtBytes?: number;
+    /** Absent ⇒ the whole body is assembled in memory, whatever its size (the historical path). */
+    readonly spill?: () => Promise<BodySpill<T>>;
+}
+/**
+ * Read a response body with a hard byte cap, optionally spilling a large body to a caller's sink.
+ *
+ * Two failures that used to share `fetch/failed` are deliberately DIFFERENT codes, because a caller
+ * has to treat them differently:
+ *
+ *   - the cap is crossed (declared `content-length`, or bytes actually read) → `fetch/too-large`, a
+ *     TERMINAL failure: another mirror serves the same oversized object, so falling through cannot
+ *     help;
+ *   - the declared length does not match what was read → `fetch/failed`, a TRANSPORT failure: that is
+ *     a truncated download, exactly the shape that should try the next candidate source.
+ *
+ * Without a `spill` this is exactly the historical `readCapped`: same codes, same messages, same
+ * single up-front `Uint8Array`. With one, the body crosses `spillAtBytes` and from then on every chunk
+ * goes straight to the sink — the buffered prefix is replayed once and dropped — so peak memory is one
+ * chunk, not the whole file. `docs/DESIGN.md` §6 states the same invariant; `providers/model.ts` and
+ * `downloadBytes` below are the two places that branch on it.
+ */
+export declare function readCappedOrSpill(response: Response, options?: {
+    readonly maxBytes?: number;
+}): Promise<Uint8Array>;
+export declare function readCappedOrSpill<T>(response: Response, options: CappedReadOptions<T> & {
+    readonly spill: () => Promise<BodySpill<T>>;
+}): Promise<Uint8Array | T>;
+/**
+ * {@link readCappedOrSpill} without a sink: the entire body is assembled in memory.
+ *
+ * This is the frozen historical behavior — used by everything that NEEDS the bytes in hand (a
+ * `JSON.parse`, an archive digest, an in-memory extract). A caller that lands a file on disk should
+ * pass a `spill` so a large body never becomes two copies of itself in the heap.
+ */
 export declare function readCapped(response: Response, maxBytes?: number): Promise<Uint8Array>;
 /** `{url}` templates → concrete URLs, official source first. */
 export declare function candidateUrls(url: string, mirrors: readonly string[] | undefined): readonly string[];
-/** Download the first candidate that answers 2xx; throws `fetch/failed` when none does. */
+/**
+ * Download the first candidate that answers 2xx; throws `fetch/failed` when none does (and
+ * `fetch/too-large` immediately when a body crosses the hard cap — see {@link readCapped}).
+ *
+ * DOWNLOADING IS THE SLOWEST THING THIS FRAMEWORK DOES and it used to be completely silent: a 223 MB
+ * archive on a mirror that eventually times out looked like eight minutes of nothing, and the first
+ * evidence of trouble was the final `fetch/failed` after every candidate had been tried (measured on
+ * DSH Desktop — GitHub plus three mirrors, all aborted). One line per attempt, one when a candidate
+ * is passed over with its reason, and one on success makes the wait legible while it is happening.
+ */
 export declare function downloadBytes(ctx: ProviderContext, urls: readonly string[], key: string, onProgress?: (event: ProgressEvent) => void): Promise<{
     readonly bytes: Uint8Array;
     readonly url: string;

package/dist/net.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEhE,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,KAAK,CAI9D;AAED,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,QAAoB,CAAA;AAElD,mDAAmD;AACnD,eAAO,MAAM,0BAA0B,SAAU,CAAA;AAEjD,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,GAAG,EAAE,eAAe,EAAE,SAAS,GAAE,MAAmC,GAAG,WAAW,CAG3G;AAED,gGAAgG;AAChG,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,UAAU,CAAC,CAwCrB;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,CAOpG;AAED,2FAA2F;AAC3F,wBAAsB,aAAa,CACjC,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,OAAO,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB/D;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKtE;AAED,yFAAyF;AACzF,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEhE,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,KAAK,CAI9D;AAED,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,QAAoB,CAAA;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,QAAmB,CAAA;AAElD,mDAAmD;AACnD,eAAO,MAAM,0BAA0B,SAAU,CAAA;AAEjD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAQ/E;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAAmB,CAAA;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,4DAA4D;IAC5D,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,yFAAyF;IACzF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACjC,yGAAyG;IACzG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AACpH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;CAAE,GAC9E,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;AA+D1B;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,CAOpG;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,OAAO,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAiC/D;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKtE;AAED,yFAAyF;AACzF,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/net.js

@@ -13,24 +13,69 @@ export function fetchImplOf(ctx) {
 }
 /** Default hard byte cap for one downloaded body. */
 export const DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+/**
+ * Hard byte cap for a METADATA body: an npm packument, a model revision response, a siblings list.
+ *
+ * Metadata is a small JSON document that is then `JSON.parse`d (`providers/npm.ts`,
+ * `providers/model.ts`), and parsing amplifies it several-fold in heap. The 256 MiB archive cap only
+ * stops the extreme; it still lets a "KB-scale document, GB-scale heap" through.
+ *
+ * 16 MiB is MEASURED, not guessed. The npm provider asks for `accept: application/json`, i.e. the
+ * FULL packument, so the real sizes are the full ones (registry.npmjs.org, 2026-10-02):
+ * `lodash` 0.2 MB, `react` 6.7 MB, `aws-sdk` 10.1 MB, `@types/node` 11.2 MB, `typescript` 15.7 MB.
+ * 16 MiB keeps every ordinary package installable with headroom while bounding the parse to a
+ * four-digit number of MB. The largest packuments on the registry (`npm`, 25.8 MB) now fail
+ * terminally as `fetch/too-large` — the intended fail-closed answer for a document that would
+ * otherwise be parsed into a multi-GB heap. Anything in that range wants a streamed download with a
+ * real cap, not `JSON.parse`. (The abbreviated form — `accept: application/vnd.npm.install-v1+json`
+ * — measured 2–10× smaller on the same packages, e.g. `npm` 25.8 MB → 2.5 MB and `typescript`
+ * 15.7 MB → 8.7 MB; switching to it would be a separate, observable change to what the provider
+ * reads, so it is recorded here as an option rather than done silently.)
+ */
+export const METADATA_MAX_BYTES = 16 * 1024 * 1024;
 /** Default per-request timeout in milliseconds. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 300_000;
-/** Combine the caller's `AbortSignal` with a timeout signal. */
-export function signalFor(ctx, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
-    const timeout = AbortSignal.timeout(timeoutMs);
+/**
+ * Combine the caller's `AbortSignal` with a timeout signal.
+ *
+ * `timeoutMs` (or, when omitted, the item's `policy.timeoutMs`) is the item's per-request budget;
+ * an undeclared value keeps the 300 s default. `0` means NO timeout — the escape hatch a 2 GiB model
+ * needs on a link slower than ~7 MB/s, which the fixed default could never finish. `ctx.signal`
+ * (shutdown/caller abort) still applies in every case.
+ */
+export function signalFor(ctx, timeoutMs) {
+    const configured = timeoutMs ?? ctx.policy.timeoutMs;
+    if (configured === 0) {
+        return ctx.signal ?? new AbortController().signal;
+    }
+    const effective = configured === undefined || !Number.isFinite(configured) || configured < 0 ? DEFAULT_REQUEST_TIMEOUT_MS : configured;
+    const timeout = AbortSignal.timeout(effective);
     return ctx.signal === undefined ? timeout : AbortSignal.any([ctx.signal, timeout]);
 }
-/** Read a response body with a hard byte cap; throws `fetch/failed` when the cap is crossed. */
-export async function readCapped(response, maxBytes = DEFAULT_MAX_BYTES) {
+/**
+ * Bodies at or below this size are assembled in memory exactly as before; a larger body is handed to
+ * a caller-supplied {@link BodySpill} instead, so the peak cost of a download stops tracking the file
+ * size. The threshold is the ONLY switch, which keeps the common path (a packument, a tarball, a small
+ * model file) on the untouched, simplest code while a multi-GB model — the case measured at roughly 2×
+ * its size in RSS — streams one chunk at a time.
+ *
+ * 64 MiB is a deliberate middle: every ordinary body stays in memory, and when one does not, the
+ * in-memory cost is already bounded by `2 × spillAtBytes` (the chunks plus the joined copy) regardless
+ * of how large the body turns out to be.
+ */
+export const SPILL_THRESHOLD_BYTES = 64 * 1024 * 1024;
+export async function readCappedOrSpill(response, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const spillAtBytes = options.spillAtBytes ?? SPILL_THRESHOLD_BYTES;
     const declared = Number(response.headers.get('content-length') ?? Number.NaN);
     if (Number.isFinite(declared) && declared > maxBytes) {
-        throw new ProvisionError('fetch/failed', `响应声明 ${String(declared)} 字节，超过上限 ${String(maxBytes)}`);
+        throw new ProvisionError('fetch/too-large', `响应声明 ${String(declared)} 字节，超过上限 ${String(maxBytes)}`);
     }
     const body = response.body;
     if (body === null) {
         const bytes = new Uint8Array(await response.arrayBuffer());
         if (bytes.byteLength > maxBytes) {
-            throw new ProvisionError('fetch/failed', `响应 ${String(bytes.byteLength)} 字节，超过上限 ${String(maxBytes)}`);
+            throw new ProvisionError('fetch/too-large', `响应 ${String(bytes.byteLength)} 字节，超过上限 ${String(maxBytes)}`);
         }
         if (Number.isFinite(declared) && declared !== bytes.byteLength) {
             throw new ProvisionError('fetch/failed', `响应声明 ${String(declared)} 字节，实际收到 ${String(bytes.byteLength)} 字节`);
@@ -40,29 +85,60 @@ export async function readCapped(response, maxBytes = DEFAULT_MAX_BYTES) {
     const reader = body.getReader();
     const chunks = [];
     let total = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        if (value === undefined)
-            continue;
-        total += value.byteLength;
-        if (total > maxBytes) {
-            await reader.cancel().catch(() => undefined);
-            throw new ProvisionError('fetch/failed', `响应超过上限 ${String(maxBytes)} 字节（已读 ${String(total)}）`);
+    let spill;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value === undefined)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                throw new ProvisionError('fetch/too-large', `响应超过上限 ${String(maxBytes)} 字节（已读 ${String(total)}）`);
+            }
+            // The body has outgrown the in-memory budget: hand the buffered prefix to the sink and never
+            // assemble the whole thing again.
+            if (spill === undefined && options.spill !== undefined && total > spillAtBytes) {
+                spill = await options.spill();
+                for (const buffered of chunks)
+                    await spill.write(buffered);
+                chunks.length = 0;
+            }
+            if (spill === undefined)
+                chunks.push(value);
+            else
+                await spill.write(value);
         }
-        chunks.push(value);
-    }
-    if (Number.isFinite(declared) && declared !== total) {
-        throw new ProvisionError('fetch/failed', `响应声明 ${String(declared)} 字节，实际收到 ${String(total)} 字节`);
+        if (Number.isFinite(declared) && declared !== total) {
+            throw new ProvisionError('fetch/failed', `响应声明 ${String(declared)} 字节，实际收到 ${String(total)} 字节`);
+        }
+        if (spill !== undefined)
+            return await spill.finish(total);
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return bytes;
     }
-    const bytes = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        bytes.set(chunk, offset);
-        offset += chunk.byteLength;
+    catch (error) {
+        await reader.cancel().catch(() => undefined);
+        if (spill !== undefined)
+            await spill.abort().catch(() => undefined);
+        throw error;
     }
-    return bytes;
+}
+/**
+ * {@link readCappedOrSpill} without a sink: the entire body is assembled in memory.
+ *
+ * This is the frozen historical behavior — used by everything that NEEDS the bytes in hand (a
+ * `JSON.parse`, an archive digest, an in-memory extract). A caller that lands a file on disk should
+ * pass a `spill` so a large body never becomes two copies of itself in the heap.
+ */
+export async function readCapped(response, maxBytes = DEFAULT_MAX_BYTES) {
+    return readCappedOrSpill(response, { maxBytes });
 }
 /** `{url}` templates → concrete URLs, official source first. */
 export function candidateUrls(url, mirrors) {
@@ -74,14 +150,28 @@ export function candidateUrls(url, mirrors) {
     }
     return candidates;
 }
-/** Download the first candidate that answers 2xx; throws `fetch/failed` when none does. */
+/**
+ * Download the first candidate that answers 2xx; throws `fetch/failed` when none does (and
+ * `fetch/too-large` immediately when a body crosses the hard cap — see {@link readCapped}).
+ *
+ * DOWNLOADING IS THE SLOWEST THING THIS FRAMEWORK DOES and it used to be completely silent: a 223 MB
+ * archive on a mirror that eventually times out looked like eight minutes of nothing, and the first
+ * evidence of trouble was the final `fetch/failed` after every candidate had been tried (measured on
+ * DSH Desktop — GitHub plus three mirrors, all aborted). One line per attempt, one when a candidate
+ * is passed over with its reason, and one on success makes the wait legible while it is happening.
+ */
 export async function downloadBytes(ctx, urls, key, onProgress) {
     const problems = [];
-    for (const url of urls) {
+    for (const [index, url] of urls.entries()) {
+        const position = `${String(index + 1)}/${String(urls.length)}`;
+        // The last candidate gets no "trying the next one" promise: there is none.
+        const next = index + 1 < urls.length ? '，改用下一个候选源' : '，没有更多候选源';
+        ctx.logger.info(`${key}：尝试候选源 ${position} ${url}`);
         try {
             const response = await fetchImplOf(ctx)(url, { signal: signalFor(ctx) });
             if (!response.ok) {
                 problems.push(`${url} → HTTP ${String(response.status)}`);
+                ctx.logger.warn(`${key}：${url} 返回 HTTP ${String(response.status)}${next}`);
                 continue;
             }
             // A short body is a TRANSPORT failure and retries the next mirror, like a bad status or a
@@ -90,10 +180,18 @@ export async function downloadBytes(ctx, urls, key, onProgress) {
             // distinction IS the invariant; `docs/DESIGN.md` §6 states it in the same words.
             const bytes = await readCapped(response);
             onProgress?.({ key, phase: 'download', loaded: bytes.byteLength, total: bytes.byteLength });
+            ctx.logger.info(`${key}：下载完成 ${String(bytes.byteLength)} 字节（${url}）`);
             return { bytes, url };
         }
         catch (error) {
-            problems.push(`${url} → ${error instanceof Error ? error.message : String(error)}`);
+            // The byte cap is the one fetch failure that is TERMINAL: every mirror serves the same
+            // oversized object, so retrying just burns the remaining candidates. `readCapped` separates it
+            // from a truncated body (`fetch/failed`) for exactly this branch.
+            if (error instanceof ProvisionError && error.code === 'fetch/too-large')
+                throw error;
+            const reason = error instanceof Error ? error.message : String(error);
+            problems.push(`${url} → ${reason}`);
+            ctx.logger.warn(`${key}：${url} 失败（${reason}）${next}`);
         }
     }
     throw new ProvisionError('fetch/failed', `所有候选源都失败：${problems.join('; ')}`);

package/dist/providers/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/providers/archive.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAA+B,QAAQ,EAAuE,MAAM,aAAa,CAAA;AAG7I,eAAO,MAAM,mBAAmB,mBAAmB,CAAA;AAOnD,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACnC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;IACrD,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AA2FD,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,QAAQ,CAqJtF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/providers/archive.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAA+B,QAAQ,EAAuE,MAAM,aAAa,CAAA;AAG7I,eAAO,MAAM,mBAAmB,mBAAmB,CAAA;AAOnD,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACnC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;IACrD,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAmJD,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,QAAQ,CAyLtF"}

package/dist/providers/archive.js

@@ -2,11 +2,12 @@
  * The built-in `binary-archive` provider.
  * @module providers/archive
  */
-import { delimiter, dirname, join } from 'node:path';
+import { basename, delimiter, dirname, join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { ProvisionError } from '../errors.js';
 import { exists } from '../fs.js';
 import { sriOfSha256 } from '../integrity.js';
+import { assertSafeRelativePath } from '../layout.js';
 import { decodeJson, readInstallManifest } from '../manifest.js';
 import { candidateUrls, downloadBytes, platformKey, verifySha256 } from '../net.js';
 import { extractTarGz } from '../tar.js';
@@ -88,16 +89,65 @@ function runVersionProbe(path, args, options = {}) {
         execFile(path, [...args], {
             timeout: options.timeoutMs ?? VERIFY_TIMEOUT_MS,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
-        }, error => {
+        }, (error, stdout) => {
+            const text = typeof stdout === 'string' ? stdout : '';
             if (error === null) {
-                resolve('ok');
+                resolve({ outcome: 'ok', stdout: text });
                 return;
             }
             const killed = error.killed === true || error.code === 'ETIMEDOUT';
-            resolve(killed ? 'timeout' : 'failed');
+            resolve({ outcome: killed ? 'timeout' : 'failed', stdout: text });
         });
     });
 }
+/**
+ * Version-shaped tokens in a probe's output (a leading `v` is part of the decoration, not the number).
+ *
+ * A version is confirmed by an EQUAL token, never by the exit code: any same-named binary on PATH
+ * answers `--version` with 0. An exact-token rule can only produce a false NEGATIVE (a tool that
+ * prints more precision than the spec pins, e.g. `1.0.0.1` for `1.0.0`), which degrades to "present,
+ * version unknown" — the same safe shape as a timeout.
+ */
+const VERSION_TOKEN = /(?:^|[^0-9A-Za-z])v?(\d+(?:\.\d+)*(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)/g;
+/** The bare numeric core of a version: `4.4.2-0ubuntu0.22.04.1` → `4.4.2`. */
+const VERSION_CORE = /^\d+(?:\.\d+)*/;
+/** A pin that is itself nothing but the numeric core (no distro/prerelease/build decoration). */
+const PLAIN_NUMERIC = /^\d+(?:\.\d+)*$/;
+/**
+ * Does the probe output report `expected`?
+ *
+ * The observed token may carry a DISTRO/BUILD decoration that is not part of the version identity —
+ * measured: `ffmpeg version 4.4.2-0ubuntu0.22.04.1` against a pin of `4.4.2`. That produced a MISS,
+ * which is fail-closed (the caller re-downloads a tool it already has) but wrong: the decorated
+ * token IS the pinned version. So a PLAIN NUMERIC pin is compared against each token's numeric core;
+ * a pin that is not plain numeric (a prerelease/build pin such as `1.2.3-rc.1`) keeps the exact-token
+ * rule, because there the suffix is exactly what is being pinned. A genuinely different version still
+ * misses: the core is compared whole (`4.5.0` and `1.0.0.1` are not `4.4.2`/`1.0.0`), never as a
+ * string prefix, so `4.4` cannot match `4.4.2` and `1.0.0` cannot match `1.0.0.1`.
+ */
+function reportsVersion(stdout, expected) {
+    const wanted = expected.replace(/^v/, '');
+    const compareCore = PLAIN_NUMERIC.test(wanted);
+    for (const match of stdout.matchAll(VERSION_TOKEN)) {
+        const token = match[1];
+        if (token === undefined)
+            continue;
+        if (token === wanted)
+            return true;
+        if (!compareCore)
+            continue;
+        // `VERSION_CORE` is anchored, so this is the token's numeric head, not a substring search.
+        const core = VERSION_CORE.exec(token)?.[0];
+        if (core === wanted)
+            return true;
+    }
+    return false;
+}
+/** One line of probe output, for a warning that stays readable. */
+function firstLine(stdout) {
+    const line = stdout.split('\n').find(candidate => candidate.trim() !== '');
+    return (line ?? '').trim().slice(0, 120);
+}
 /** Build the built-in binary-archive provider. */
 export function binaryArchiveProvider(options = {}) {
     const id = options.id ?? '@avantf/dsh-plugin-base/binary-archive';
@@ -123,14 +173,24 @@ export function binaryArchiveProvider(options = {}) {
             const spec = parseSpec(item);
             const binary = binaryOf(spec);
             const args = spec.versionArgs ?? ['--version'];
-            // A PATH/explicit hit is confirmed with the same `--version` probe as verify.
+            // A PATH/explicit hit is confirmed by the `--version` probe's OUTPUT, not its exit code: any
+            // same-named binary exits 0, and trusting that made an arbitrary `pandoc` on PATH masquerade as
+            // the pinned version (its directory then went into PATH and status.json). A mismatch is a miss.
             const check = async (path) => {
-                if (args.length === 0)
-                    return { version: spec.version };
-                const outcome = await runVersionProbe(path, args, { timeoutMs: PROBE_TIMEOUT_MS, ...(ctx.signal === undefined ? {} : { signal: ctx.signal }) });
-                if (outcome === 'ok')
-                    return { version: spec.version };
-                if (outcome === 'timeout') {
+                // No probe command ⇒ the binary may exist, but there is no way to know its version. Say so
+                // (the same shape as a timeout) instead of copying the assertion in the spec.
+                if (args.length === 0) {
+                    ctx.logger.warn(`${path} 未配置版本探针（versionArgs 为空）；按"存在但版本未知"处理`);
+                    return {};
+                }
+                const probed = await runVersionProbe(path, args, { timeoutMs: PROBE_TIMEOUT_MS, ...(ctx.signal === undefined ? {} : { signal: ctx.signal }) });
+                if (probed.outcome === 'ok') {
+                    if (reportsVersion(probed.stdout, spec.version))
+                        return { version: spec.version };
+                    ctx.logger.warn(`${path} 的 ${args.join(' ')} 未报告 ${spec.version}（输出：${firstLine(probed.stdout)}）；按未命中处理`);
+                    return undefined;
+                }
+                if (probed.outcome === 'timeout') {
                     ctx.logger.warn(`${path} 的 ${args.join(' ')} 探针超时；按"存在但版本未知"处理`);
                     return {};
                 }
@@ -153,12 +213,21 @@ export function binaryArchiveProvider(options = {}) {
                     const manifest = readInstallManifest(decodeJson(await ctx.fs.readFile(manifestPath)), BINARY_ARCHIVE_KIND);
                     if (manifest === undefined || manifest.version !== spec.version)
                         continue;
-                    // The manifest's entry is authoritative.
+                    // The manifest's entry is authoritative — and the read-back side still validates it, so a
+                    // hand-edited/corrupt install.json cannot point the join outside the version directory.
                     const relative = manifest.entry ?? `bin/${binaryOf(spec, spec.packs[platformKey()])}`;
-                    const executable = join(root, entry, ...relative.split('/'));
+                    let executable;
+                    try {
+                        assertSafeRelativePath(relative);
+                        executable = join(root, entry, ...relative.split('/'));
+                    }
+                    catch {
+                        ctx.logger.warn(`install.json 的 entry 不安全，已跳过：${relative}（${join(root, entry)}）`);
+                        continue;
+                    }
                     if (await exists(ctx.fs, executable)) {
                         const dir = dirname(executable);
-                        return { found: true, version: spec.version, dir, source: 'managed', env: pathEnvOf(dir) };
+                        return { found: true, version: manifest.version, dir, source: 'managed', env: pathEnvOf(dir) };
                     }
                 }
             }
@@ -205,7 +274,14 @@ export function binaryArchiveProvider(options = {}) {
             }
             const binDir = join(staging, 'bin');
             await ctx.fs.mkdir(binDir);
-            const target = join(binDir, binary);
+            // The name the archive ACTUALLY carries, not the declared one. A pack names its executable
+            // (`pandoc`) while a Windows archive ships `pandoc.exe`, and Windows cannot execute a PE image
+            // under a name without the extension: installing it as `bin/pandoc` made the mandatory
+            // `--version` probe fail and quarantined a freshly downloaded 223 MB tool (measured on DSH
+            // Desktop). The manifest records the real name, and `probe`/`verify` read the entry from there,
+            // so resolution follows it without a second rule.
+            const installed = basename(found);
+            const target = join(binDir, installed);
             await ctx.fs.copyFile(found, target);
             await ctx.fs.chmod(target, 0o755);
             await ctx.fs.rm(unpack, { recursive: true });
@@ -215,7 +291,7 @@ export function binaryArchiveProvider(options = {}) {
                 integrity: sriOfSha256(pack.sha256),
                 tarball: pack.url,
                 source: 'installed',
-                entry: `bin/${binary}`,
+                entry: `bin/${installed}`,
                 entryDir: 'bin',
             };
             return ctx.publish(staging, meta);
@@ -225,7 +301,19 @@ export function binaryArchiveProvider(options = {}) {
             // The published entry is the manifest's.
             const manifest = readInstallManifest(decodeJson(await ctx.fs.readFile(join(resolved.dir, 'install.json'))), BINARY_ARCHIVE_KIND);
             const entry = manifest?.entry;
-            const path = entry === undefined ? join(resolved.entryDir, binaryOf(spec)) : join(resolved.dir, ...entry.split('/'));
+            let path;
+            if (entry === undefined) {
+                path = join(resolved.entryDir, binaryOf(spec));
+            }
+            else {
+                try {
+                    assertSafeRelativePath(entry);
+                    path = join(resolved.dir, ...entry.split('/'));
+                }
+                catch {
+                    throw new ProvisionError('verify/failed', `install.json 的 entry 不安全：${entry}`);
+                }
+            }
             if (!(await exists(ctx.fs, path))) {
                 throw new ProvisionError('verify/failed', `归档可执行物不存在：${path}`);
             }
@@ -233,13 +321,13 @@ export function binaryArchiveProvider(options = {}) {
             const args = spec.versionArgs ?? ['--version'];
             if (args.length === 0)
                 return;
-            const outcome = await runVersionProbe(path, args, { ...(ctx.signal === undefined ? {} : { signal: ctx.signal }) });
-            if (outcome === 'timeout') {
+            const probed = await runVersionProbe(path, args, { ...(ctx.signal === undefined ? {} : { signal: ctx.signal }) });
+            if (probed.outcome === 'timeout') {
                 // A timeout leaves the binary usable; only a failed probe fails verification.
                 ctx.logger.warn(`${path} 的 ${args.join(' ')} 探针超时；按可用处理`);
                 return;
             }
-            if (outcome === 'failed') {
+            if (probed.outcome === 'failed') {
                 throw new ProvisionError('verify/failed', `${path} 的 ${args.join(' ')} 探针失败`);
             }
         },

package/dist/providers/model.d.ts

@@ -1,5 +1,21 @@
 import type { Provider } from '../types.js';
 export declare const MODEL_CACHE_KIND = "model-cache";
+/**
+ * Maximum bytes read for a single model file.
+ *
+ * 2 GiB, not the old 4 GiB. The cap is the number of bytes the MEMORY path would have to hold TWICE
+ * (the received chunks plus the joined copy), so it bounds the worst-case spike directly; the measured
+ * ~2× peak for a body of this size is ~4 GiB, which a 16 GB machine survives and a 4 GiB cap does not.
+ * 2 GiB is also still far above what the framework is for: a real `bge-small` is ~90 MB and even a
+ * multi-billion-parameter checkpoint is a handful of files well under this. Anything larger wants a
+ * different transport, not a bigger heap.
+ *
+ * (The review's "4 GiB is exactly Node's `kMaxLength`" does NOT reproduce on the target runtime:
+ * Node 22.23.2 / linux-x64 reports `buffer.constants.MAX_LENGTH` 2^53−1 and allocates a 4 GiB
+ * `Uint8Array` fine. The rejection boundary is a legitimate design choice here, not a crash we are
+ * ducking — see the report accompanying this change.)
+ */
+export declare const MAX_MODEL_BYTES: number;
 /** How an item's files are placed under `target.root`.
  *  @stable */
 export type ModelCacheLayout = 'hub' | 'flat';
@@ -18,8 +34,15 @@ export interface ModelCacheSpec {
     /** Extra files that must exist for `verify` to pass. */
     readonly requiredFiles?: readonly string[];
 }
-/** Build the built-in model-cache provider. */
-export declare function modelCacheProvider(options?: {
+/** The options of {@link modelCacheProvider}; the byte limits are injectable so tests can exercise the
+ *  spill boundary without multi-hundred-MB bodies. `@experimental` */
+export interface ModelCacheProviderOptions {
     readonly id?: string;
-}): Provider;
+    /** Hard per-file byte cap; default {@link MAX_MODEL_BYTES} (2 GiB). */
+    readonly maxBytes?: number;
+    /** Body size above which a file streams to disk; default {@link SPILL_THRESHOLD_BYTES} (64 MiB). */
+    readonly spillAtBytes?: number;
+}
+/** Build the built-in model-cache provider. */
+export declare function modelCacheProvider(options?: ModelCacheProviderOptions): Provider;
 //# sourceMappingURL=model.d.ts.map

package/dist/providers/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/providers/model.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAGV,QAAQ,EAOT,MAAM,aAAa,CAAA;AAEpB,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAoB7C;cACc;AACd,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAA;AAY7C,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AA8ZD,+CAA+C;AAC/C,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,QAAQ,CAgHnF"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/providers/model.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAGV,QAAQ,EAOT,MAAM,aAAa,CAAA;AAEpB,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAG7C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAuBrD;cACc;AACd,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAA;AAY7C,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AA4gBD;sEACsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,oGAAoG;IACpG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,+CAA+C;AAC/C,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,QAAQ,CA8GpF"}