dsh-layered-memory 0.6.1 → 0.7.0

package/dist/pipeline/runner.js

@@ -32,6 +32,8 @@ export class MemoryRunner {
     live;
     tasks = [];
     draining = false;
+    /** 停止标志（dispose 序置位）：不再取新任务；进行中任务自然收尾，其 DB 写入失败由各层兜底捕获。 */
+    stopped = false;
     pending = emptyPending();
     pendingFile;
     background = [];
@@ -104,7 +106,13 @@ export class MemoryRunner {
     runRebuildTurn(sessionId, messages) {
         return this.runTurn(sessionId, messages, 'auto', { noBufferCap: true });
     }
+    /** 停止取新任务（插件 dispose 序调用；进行中任务照常跑完但不 await——LLM 慢调用不拖住宿主卸载）。 */
+    stop() {
+        this.stopped = true;
+    }
     pushTask(task) {
+        if (this.stopped)
+            return;
         this.tasks.push(task);
         void this.drain();
     }
@@ -113,7 +121,7 @@ export class MemoryRunner {
             return;
         this.draining = true;
         try {
-            while (this.tasks.length > 0) {
+            while (!this.stopped && this.tasks.length > 0) {
                 const [task] = this.tasks.splice(pickNextTaskIndex(this.tasks), 1);
                 try {
                     await task.run();
@@ -127,9 +135,18 @@ export class MemoryRunner {
             this.draining = false;
         }
     }
-    /** 缓冲落盘（每次蒸馏尝试后调用；失败只告警不阻断管线）。 */
-    async persistPending() {
+    /** 缓冲落盘（每次蒸馏尝试后调用；失败只告警不阻断管线）。
+     *  非重建轮持久化前按桶截断到上限：重建取消后的大桶不至于在后续每次
+     *  蒸馏尝试时反复整量序列化落盘（多 MB 级 IO）；重建轮豁免维持。 */
+    async persistPending(noBufferCap = false) {
         try {
+            if (!noBufferCap) {
+                for (const key of PENDING_MODES) {
+                    const bucket = this.pending[key];
+                    if (bucket.length > PENDING_BUCKET_CAP)
+                        this.pending[key] = bucket.slice(-PENDING_BUCKET_CAP);
+                }
+            }
             await savePending(this.pendingFile, this.pending);
         }
         catch (err) {
@@ -161,13 +178,11 @@ export class MemoryRunner {
                 this.logger.info(`[memory] L1 阶段完成（${Date.now() - t}ms）`);
             }
             catch (err) {
-                // 保留 pending，下次重试；但防止无限堆积（重建轮不限，量被会话规模天然约束）
-                if (!opts?.noBufferCap && this.pending[mode].length > PENDING_BUCKET_CAP)
-                    this.pending[mode] = [];
+                // 保留 pending 下次重试（runTurn 入口已裁到 ≤200，防无限堆积；重建轮不裁，量被会话规模约束）
                 this.logger.warn(`[memory] L1 抽取失败（mode=${mode}，pending=${this.pending[mode].length}）: ${errDetail(err)}`);
             }
             // 缓冲每次尝试后立即落盘：进程中途退出不丢待重试/攒阈值状态
-            await this.persistPending();
+            await this.persistPending(opts?.noBufferCap);
             // L1 计数推进后立即落盘：L2/L3 失败或进程中途退出不得回滚阈值进度
             // （记录已入库但计数丢失会让该族 L2 永远差一截，state 与 DB 脱节）
             try {

package/dist/settings.js

@@ -2,6 +2,23 @@ import Schema from '@deepseek-ai/schemastery';
 import { settingsNamespace } from '@deepseek-ai/dsh-settings';
 const NS = settingsNamespace('dsh-memory');
 const ALWAYS_ON = { enabled: true, capture: true, distill: true, recall: true, reasoningEffort: '' };
+/**
+ * 进程内 scope 复用（fiber 重启重挂）。
+ * dsh-settings 的 register 把注册挂在其**服务自身 ctx** 的 effect 上
+ * （node_modules/@deepseek-ai/dsh-settings/lib/index.js：`this.ctx.effect(...)`），
+ * 不随本插件 fiber 销毁——fiber 重启后二次 register 会抛
+ * `settings namespace "dsh-memory" is already registered`。模块级状态在
+ * fiber 重启间存活：复用上次注册的 scope 并重挂 watcher，否则开关读写停在
+ * stub、用户已存开关被静默忽略直到重启进程。
+ *
+ * 同时按服务实例（cachedSvc）判活：settings 服务自身重启时其注册随服务 ctx
+ * 销毁，旧 scope 变死引用（get 返回冻结旧值、update 抛 not registered、
+ * watcher 永不触发）——internal/service 携带的新实例与缓存不符时作废缓存、
+ * 向新实例重新注册（用户层由服务从磁盘重解析，已存开关不丢）。
+ */
+let cachedScope;
+let cachedUnwatch;
+let cachedSvc;
 export function liveSettingsSchema() {
     return Schema.object({
         enabled: Schema.boolean().default(true),
@@ -18,28 +35,56 @@ export function registerLiveSettings(ctx, logger) {
         get: () => ALWAYS_ON,
         update: () => Promise.reject(new Error('settings 服务不可用')),
     };
+    /** 挂接一个（新注册或复用的）scope：重挂前先摘旧 watcher，防跨重启累积。 */
+    const wireScope = (scope) => {
+        cachedUnwatch?.();
+        let current = resolveSettings(scope.get());
+        cachedUnwatch = scope.watch((next) => {
+            const prev = current;
+            current = resolveSettings(next);
+            logger.info(`[memory] 记忆模式开关更新：总=${current.enabled} 捕获=${current.capture} 蒸馏=${current.distill} 召回=${current.recall}` +
+                `，蒸馏思考=${current.reasoningEffort || '跟随配置'}（此前 总=${prev.enabled}）`);
+        });
+        return {
+            supported: true,
+            get: () => current,
+            update: async (patch) => {
+                await scope.update(patch);
+            },
+        };
+    };
+    /** 作废进程内缓存（服务下线/实例替换时旧注册已随服务销毁）。 */
+    const invalidateCache = () => {
+        cachedScope = undefined;
+        cachedSvc = undefined;
+        cachedUnwatch?.();
+        cachedUnwatch = undefined;
+    };
     const tryAttach = () => {
         const settings = ctx.get('settings');
         if (!settings)
             return false;
+        // 仅当缓存来自同一服务实例时才可复用——换了实例（服务重启/替换）就重新注册
+        if (cachedScope && cachedSvc === settings) {
+            try {
+                inner = wireScope(cachedScope);
+                const c = inner.get();
+                logger.info(`[memory] 记忆模式开关重挂（复用进程内注册，当前：总=${c.enabled} 捕获=${c.capture} 蒸馏=${c.distill} 召回=${c.recall}` +
+                    `，蒸馏思考=${c.reasoningEffort || '跟随配置'}）`);
+                return true;
+            }
+            catch (err) {
+                logger.warn(`[memory] 记忆模式开关缓存复用失败，改为重新注册: ${err instanceof Error ? err.message : String(err)}`);
+                invalidateCache();
+            }
+        }
         try {
             const scope = settings.register(NS, liveSettingsSchema(), { applies: 'live' });
-            let current = resolveSettings(scope.get());
-            scope.watch((next) => {
-                const prev = current;
-                current = resolveSettings(next);
-                logger.info(`[memory] 记忆模式开关更新：总=${current.enabled} 捕获=${current.capture} 蒸馏=${current.distill} 召回=${current.recall}` +
-                    `，蒸馏思考=${current.reasoningEffort || '跟随配置'}（此前 总=${prev.enabled}）`);
-            });
-            inner = {
-                supported: true,
-                get: () => current,
-                update: async (patch) => {
-                    await scope.update(patch);
-                },
-            };
-            logger.info(`[memory] 记忆模式开关就绪（settings 命名空间 dsh-memory，当前：总=${current.enabled} 捕获=${current.capture} 蒸馏=${current.distill} 召回=${current.recall}` +
-                `，蒸馏思考=${current.reasoningEffort || '跟随配置'}）`);
+            cachedScope = scope;
+            cachedSvc = settings;
+            inner = wireScope(scope);
+            logger.info(`[memory] 记忆模式开关就绪（settings 命名空间 dsh-memory，当前：总=${inner.get().enabled} 捕获=${inner.get().capture} 蒸馏=${inner.get().distill} 召回=${inner.get().recall}` +
+                `，蒸馏思考=${inner.get().reasoningEffort || '跟随配置'}）`);
             return true;
         }
         catch (err) {
@@ -49,11 +94,25 @@ export function registerLiveSettings(ctx, logger) {
     };
     if (!tryAttach()) {
         logger.warn('[memory] settings 服务未就绪，记忆模式开关暂不可用（保持全开，等待服务上线）');
-        ctx.on('internal/service', (name) => {
-            if (name === 'settings' && !inner.supported)
-                tryAttach();
-        });
     }
+    // 无论初始是否成功都监听服务迁移：下线 → 作废缓存；换实例 → 作废后立即重挂
+    // （此前监听仅在初始失败时注册，服务替换场景下没有任何自愈路径）
+    ctx.on('internal/service', (name, impl) => {
+        if (name !== 'settings')
+            return;
+        if (!impl) {
+            if (cachedSvc !== undefined) {
+                invalidateCache();
+                logger.warn('[memory] settings 服务下线，开关缓存已作废（期间读数为冻结值，恢复后自动重挂）');
+            }
+            return;
+        }
+        // 实例变了才作废缓存；但 tryAttach 无条件执行（幂等）——同一事件会广播到
+        // 所有存活 fiber 的监听器，后跑的那个也必须修好自己闭包里的 inner
+        if (impl !== cachedSvc)
+            invalidateCache();
+        tryAttach();
+    });
     return {
         get supported() {
             return inner.supported;

package/dist/stats.d.ts

@@ -7,6 +7,7 @@ import type { L1Store } from './store/l1.js';
 import type { PersonaStore } from './store/persona.js';
 import type { SceneStore } from './store/scenes.js';
 import type { SessionModeStore } from './store/session-modes.js';
+import type { EmbeddingManager } from './store/embedding-source.js';
 import type { StateStore } from './store/state.js';
 import type { MemoryFamily, MemoryLogger } from './types.js';
 export declare const PLUGIN_VERSION: string;
@@ -36,6 +37,11 @@ export interface MemoryStats {
     memoriesSinceL3: number;
     pendingExtract: number;
     message: string;
+    /** 实际生效的阈值（概览进度分母用，避免 UI 硬编码与部署配置脱节）。 */
+    thresholds: {
+        l2MinNewMemories: number;
+        l3Interval: number;
+    };
 }
 /** 注册状态 RPC（web 侧 connection 服务可选，缺失时跳过，不影响插件主体）。 */
 export declare function registerMemoryRpc(ctx: Context, cfg: MemoryConfig, stores: {
@@ -44,4 +50,4 @@ export declare function registerMemoryRpc(ctx: Context, cfg: MemoryConfig, store
     scenes: Record<MemoryFamily, SceneStore>;
     persona: Record<MemoryFamily, PersonaStore>;
     state: StateStore;
-}, logger: MemoryLogger, status?: MemoryStatusSource, live?: LiveSettingsHandle, modes?: SessionModeStore, dataDir?: string, rebuild?: RebuildController): void;
+}, logger: MemoryLogger, status?: MemoryStatusSource, live?: LiveSettingsHandle, modes?: SessionModeStore, dataDir?: string, rebuild?: RebuildController, embedManager?: EmbeddingManager): void;

package/dist/stats.js

@@ -3,18 +3,21 @@
  * Client 设置页通过 ctx.connection.rpc.call('/rpc', 'dsh-memory/stats') 拉取。
  *
  * connection 是可选服务且可能晚于本插件就绪：先探测一次，未就绪则监听
- * internal/service，服务上线时再注册（服务消失又回来时也能重注册）。
+ * internal/service（事件携带 (name, impl)，impl=undefined 即下线），服务
+ * 上线、下线、替换实例三种迁移都会正确释放/重挂 RPC 注册。
  */
 import { createRequire } from 'node:module';
-import { readFileSync, statSync } from 'node:fs';
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveDataDir } from './config.js';
 const require = createRequire(import.meta.url);
 export const PLUGIN_VERSION = require('../package.json').version;
 /** 注册状态 RPC（web 侧 connection 服务可选，缺失时跳过，不影响插件主体）。 */
-export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes, dataDir, rebuild) {
+export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes, dataDir, rebuild, embedManager) {
     /** 当前是否持有一段有效注册（dispose 完成后清空，允许服务重上线时重注册）。 */
     let holding = false;
+    /** 当前 handle 绑定的 connection 实例（internal/service 第二参；用于识别实例替换）。 */
+    let registeredImpl;
     const tryRegister = () => {
         if (holding)
             return;
@@ -35,6 +38,7 @@ export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes,
                     dataDir: dataDir ?? resolveDataDir(cfg),
                     logger,
                     rebuild,
+                    embedManager,
                 });
                 return { ok: true, value };
             }
@@ -45,6 +49,7 @@ export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes,
                 };
             }
         }, { authority: 'loopback' });
+        registeredImpl = connection;
         if (!active) {
             void dispose();
             return;
@@ -56,17 +61,35 @@ export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes,
             void dispose();
         });
     };
+    /** 释放全部持有注册（handle 随旧服务实例失效，holding 复位以允许重挂）。 */
+    const release = () => {
+        for (const dispose of disposers.splice(0))
+            dispose();
+    };
     const disposers = [];
     ctx.effect(() => {
         tryRegister();
-        const off = ctx.on('internal/service', (name) => {
-            if (name === 'connection')
-                tryRegister();
+        const off = ctx.on('internal/service', (name, impl) => {
+            if (name !== 'connection')
+                return;
+            if (!impl) {
+                // 服务下线：旧 handle 已随旧服务实例失效——主动释放并复位，
+                // 服务恢复时本事件再触发即可重挂（否则 holding 恒真 → RPC 永久失联）
+                release();
+                registeredImpl = undefined;
+                logger.debug?.('[memory] connection 服务下线，RPC 注册已释放（待恢复重挂）');
+                return;
+            }
+            if (impl !== registeredImpl) {
+                // 实例替换：旧 handle 失效，换新实例重挂
+                release();
+                registeredImpl = undefined;
+            }
+            tryRegister();
         });
         return () => {
             off();
-            for (const dispose of disposers.splice(0))
-                dispose();
+            release();
         };
     });
 }
@@ -102,10 +125,11 @@ async function buildStats(cfg, stores, status) {
         memoriesSinceL3: chat.memoriesSinceL3 + work.memoriesSinceL3,
         pendingExtract: status?.pending() ?? 0,
         message: degraded ? 'degraded：存储不可用，记忆功能已停用' : 'running',
+        thresholds: { l2MinNewMemories: cfg.l2.minNewMemories, l3Interval: cfg.l3.interval },
     };
 }
 async function handleEndpoint(endpoint, payload, deps) {
-    const { cfg, stores, status, live, modes, dataDir, rebuild } = deps;
+    const { cfg, stores, status, live, modes, dataDir, rebuild, embedManager } = deps;
     switch (endpoint) {
         case 'dsh-memory/stats':
             return buildStats(cfg, stores, status);
@@ -172,14 +196,19 @@ async function handleEndpoint(endpoint, payload, deps) {
             const p = (payload ?? {});
             const limit = Math.min(Math.max(Number(p.limit) || 50, 1), 200);
             const offset = Math.max(Number(p.offset) || 0, 0);
-            // 关键词路径：复用检索唯一缝（与召回同源），取回后做场景过滤 + 手工分页
+            // 关键词路径：复用检索唯一缝（与召回同源），取回后做场景过滤 + 手工分页。
+            // 检索侧单次上限 200：分页窗口触达上限时显式标记 truncated（结果可能不完整），
+            // 不再静默返回空结果让用户误以为"没有更多"等于"不存在更多"。
             if (p.query && p.query.trim()) {
-                const hits = await stores.l1.search(p.query, Math.min(offset + limit + 1, 200), { type: p.type || undefined });
+                const SEARCH_CAP = 200;
+                const wanted = offset + limit + 1;
+                const hits = await stores.l1.search(p.query, Math.min(wanted, SEARCH_CAP), { type: p.type || undefined });
                 const filtered = p.scene ? hits.filter((h) => h.scene_name === p.scene) : hits;
                 return {
                     items: filtered.slice(offset, offset + limit).map(hitToUiRecord),
                     hasMore: filtered.length > offset + limit,
                     total: null,
+                    truncated: wanted > SEARCH_CAP,
                     scenes: offset === 0 ? stores.l1.distinctScenes() : undefined,
                 };
             }
@@ -188,6 +217,7 @@ async function handleEndpoint(endpoint, payload, deps) {
                 items: items.map(hitToUiRecord),
                 hasMore: offset + items.length < total,
                 total,
+                truncated: false,
                 scenes: offset === 0 ? stores.l1.distinctScenes() : undefined,
             };
         }
@@ -240,6 +270,60 @@ async function handleEndpoint(endpoint, payload, deps) {
                 throw new Error('重建控制器未初始化');
             return rebuild.requestCancel();
         }
+        // ── 嵌入源（远程/本地/关闭 三态）与模型管理 ──
+        case 'dsh-memory/embedding-state-get': {
+            if (!embedManager)
+                return { supported: false };
+            return { supported: true, ...(await embedManager.snapshot()) };
+        }
+        case 'dsh-memory/embedding-source-set': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化（存储不可用）');
+            const p = (payload ?? {});
+            if (p.source !== 'remote' && p.source !== 'local' && p.source !== 'off') {
+                throw new Error('source 必须是 remote | local | off');
+            }
+            const r = embedManager.requestSource({ source: p.source, activeModel: p.activeModel ?? null });
+            if (!r.accepted)
+                throw new Error(r.error ?? '切换请求被拒绝');
+            deps.logger.info(`[memory] 收到嵌入源切换指令（source=${p.source}${p.activeModel ? '，model=' + p.activeModel : ''}）`);
+            return { accepted: true };
+        }
+        case 'dsh-memory/embedding-download-start': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化（存储不可用）');
+            const p = (payload ?? {});
+            if (typeof p.modelId !== 'string' || !p.modelId)
+                throw new Error('modelId 缺失');
+            const r = embedManager.startDownload(p.modelId);
+            if (!r.ok)
+                throw new Error(r.error ?? '下载请求被拒绝');
+            deps.logger.info(`[memory] 收到模型下载指令（${p.modelId}）`);
+            return { accepted: true };
+        }
+        case 'dsh-memory/embedding-download-cancel': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            return { cancelled: embedManager.cancelDownload() };
+        }
+        case 'dsh-memory/embedding-model-delete': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            const p = (payload ?? {});
+            if (typeof p.modelId !== 'string' || !p.modelId)
+                throw new Error('modelId 缺失');
+            return embedManager.deleteModel(p.modelId);
+        }
+        case 'dsh-memory/embedding-runtime-cancel': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            return { cancelled: embedManager.cancelRuntimeInstall() };
+        }
+        case 'dsh-memory/embedding-reindex-cancel': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            return { cancelled: embedManager.cancelReindex() };
+        }
         default:
             throw new Error(`unknown endpoint: ${endpoint}`);
     }
@@ -261,14 +345,47 @@ function hitToUiRecord(r) {
         score: r.score ?? null,
     };
 }
-/** 读日志尾部（文件有 2MB 轮转上限，全量读后取尾部即可）。 */
+/**
+ * 从文件尾反向分块读取最后 N 行：不整读全文件（轮转上限 2MB，整读会
+ * 阻塞事件循环数毫秒）。原始 Buffer 拼接后再解码——分块边界可能切在
+ * UTF-8 多字节字符中间，先 toString 再拼接会产生乱码替换符。
+ */
 function readLogTail(logPath, maxLines) {
+    let fd;
     try {
-        void statSync(logPath);
-        const lines = readFileSync(logPath, 'utf8').split('\n').filter((l) => l.length > 0);
+        fd = openSync(logPath, 'r');
+        const { size } = statSync(logPath);
+        const CHUNK = 64 * 1024;
+        const bufs = [];
+        let newlines = 0;
+        let pos = size;
+        while (pos > 0) {
+            const read = Math.min(CHUNK, pos);
+            pos -= read;
+            const buf = Buffer.alloc(read);
+            readSync(fd, buf, 0, read, pos);
+            bufs.unshift(buf);
+            // \n 是完整单字节，绝不会出现在 UTF-8 续字节里——按字节计数跨块安全
+            for (let i = 0; i < buf.length; i++)
+                if (buf[i] === 0x0a)
+                    newlines++;
+            if (newlines > maxLines)
+                break;
+        }
+        const lines = Buffer.concat(bufs).toString('utf8').split('\n').filter((l) => l.length > 0);
         return lines.slice(-maxLines);
     }
     catch {
         return [];
     }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
 }

package/dist/store/download-queue.d.ts

@@ -0,0 +1,71 @@
+import type { MemoryLogger } from '../types.js';
+import { type CatalogEntry } from './model-catalog.js';
+export type DownloadPhase = 'downloading' | 'verifying' | 'done' | 'cancelled' | 'error';
+export interface DownloadProgress {
+    modelId: string;
+    phase: DownloadPhase;
+    /** 当前文件序号（1-based）。 */
+    fileIndex: number;
+    fileCount: number;
+    /** 当前文件已收字节（含续传基线）。 */
+    fileReceived: number;
+    fileTotal: number;
+    /** 整模型累计字节（含已完成文件；分母 = 目录总大小）。 */
+    overallReceived: number;
+    overallTotal: number;
+    /** EMA 平滑速度（字节/秒）。 */
+    speedBps: number;
+    startedAt: number;
+    /** phase=error 时的原因。 */
+    error?: string;
+}
+export interface ModelStatus {
+    id: string;
+    /** none=未下载；partial=有断点/不完整；downloaded=全部文件就位且尺寸吻合。 */
+    state: 'none' | 'partial' | 'downloaded';
+    bytesOnDisk: number;
+    totalBytes: number;
+}
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export interface DownloaderOptions {
+    /** 下载镜像根（默认 https://hf-mirror.com，可配回 https://huggingface.co）。 */
+    mirror: string;
+    logger?: MemoryLogger;
+    /** 测试注入；默认全局 fetch。 */
+    fetchImpl?: FetchLike;
+    /** 测试注入磁盘剩余字节；默认 statfs。 */
+    freeBytes?: () => Promise<number | null>;
+}
+export declare class ModelDownloadQueue {
+    private readonly dataDir;
+    private readonly opts;
+    private progress;
+    private busy;
+    private abort;
+    constructor(dataDir: string, opts: DownloaderOptions);
+    /** 当前进度快照（无任务时 null）。 */
+    getProgress(): DownloadProgress | null;
+    /** 是否有任务在跑（含校验阶段）。 */
+    isBusy(): boolean;
+    modelsDir(id: string): string;
+    /** 全目录状态扫描（设置页模型卡数据源）。 */
+    listStatus(): Promise<ModelStatus[]>;
+    /** 单模型是否已完整下载（尺寸口径，不做哈希复验——下载完成时已验过）。 */
+    isDownloaded(id: string): Promise<boolean>;
+    /** 删除已下载模型（切走后释放磁盘；正在使用/下载中的拒绝）。 */
+    deleteModel(id: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** 启动下载（串行队列：忙时直接拒绝）。resolve 在任务终态（done/error/cancelled）。 */
+    start(id: string): Promise<DownloadProgress>;
+    /** 按给定目录项启动（测试缝：合成目录项驱动状态机，不触网）。 */
+    startEntry(entry: CatalogEntry): Promise<DownloadProgress>;
+    /** 取消当前任务：中断 fetch，保留 .part 断点。 */
+    cancel(): boolean;
+    private run;
+    /** 下载单文件到最终路径（含续传与校验），返回该文件贡献的字节数。 */
+    private downloadFile;
+    private freeBytes;
+}
+export {};