tanmi-dock 1.0.3 → 1.0.4

package/dist/commands/link.js

@@ -21,6 +21,7 @@ import { ProgressTracker, DownloadMonitor, MultiBarManager } from '../utils/prog
 import { success, warn, error, info, hint, blank, separator, debug } from '../utils/logger.js';
 import { verifyLocalCommit, findSubmoduleConfigs } from '../utils/git.js';
 import { DependencyStatus } from '../types/index.js';
+import { SpaceService, buildHalfCleanupSelectionSummary, buildUnreferencedSelectionSummary, estimateDownloadSpace, } from '../core/space/service.js';
 import { withGlobalLock } from '../utils/global-lock.js';
 import { selectPlatforms, parsePlatformArgs, selectOption, selectOptionalConfigs, PROMPT_CANCELLED } from '../utils/prompt.js';
 import pLimit from 'p-limit';
@@ -75,6 +76,100 @@ function resolveRequestedPlatformsByActual(requestedPlatforms, sparse, actualPla
         missingRequested: requestedPlatforms.filter((platform) => !satisfiedRequested.includes(platform)),
     };
 }
+async function verifyGeneralStoreState(dependency) {
+    const result = await verifyExistingPlatforms(dependency.libName, dependency.commit, [GENERAL_PLATFORM]);
+    return {
+        valid: result.valid.length > 0,
+        repairRequired: result.repairRequired.length > 0,
+        corrupted: result.corrupted.length > 0,
+    };
+}
+async function executeLinkStoreRepair(dependency, platforms, options) {
+    const registry = getRegistry();
+    const storePath = await store.getStorePath();
+    const spaceService = new SpaceService(registry, storePath);
+    const plan = await spaceService.buildCleanupPlan({
+        reason: 'repair',
+        selections: [{
+                id: { libName: dependency.libName, commit: dependency.commit },
+                platforms,
+                includeShared: options.includeShared,
+            }],
+        requireUnreferenced: false,
+        allowUnknownContent: false,
+    });
+    for (const warningMessage of plan.warnings)
+        warn(`[space] ${warningMessage}`);
+    debug(`[link] 调用统一清理执行器: category=${options.category}, plan=${plan.id}, lib=${dependency.libName}, commit=${dependency.commit}, platforms=${platforms === 'all' ? 'all' : platforms.join(',')}, includeShared=${Boolean(options.includeShared)}, groups=${plan.groups.length}, expected=${plan.expectedRelease.bytes}`);
+    if (plan.groups.length === 0)
+        return;
+    const result = await spaceService.createCleanupExecutor().execute(plan);
+    debug(`[link] 清理执行返回: category=${options.category}, plan=${plan.id}, status=${result.status}, succeeded=${result.succeeded.length}, failed=${result.failed.length}, released=${result.released.bytes}`);
+    if (result.status !== 'completed') {
+        throw new Error(`${dependency.libName}@${dependency.commit.slice(0, 8)} 缓存修复未完整完成: ${result.failed.map((item) => item.message).join('; ')}`);
+    }
+}
+async function prepareGeneralStoreRepair(dependency, repairRequiredPlatforms) {
+    const generalState = await verifyGeneralStoreState(dependency);
+    if (!generalState.valid && (generalState.corrupted || generalState.repairRequired)) {
+        await executeLinkStoreRepair(dependency, 'all', { category: 'general-corruption' });
+        if (!repairRequiredPlatforms.includes(GENERAL_PLATFORM)) {
+            repairRequiredPlatforms.push(GENERAL_PLATFORM);
+        }
+        return true;
+    }
+    return false;
+}
+async function prepareSharedStoreRepair(dependency, requestedPlatforms, repairRequiredPlatforms) {
+    const storePath = await config.getStorePath();
+    if (!storePath)
+        return [];
+    const sharedPath = path.join(storePath, dependency.libName, dependency.commit, '_shared');
+    try {
+        await fs.access(sharedPath);
+    }
+    catch {
+        return [];
+    }
+    const result = await verifyExistingPlatforms(dependency.libName, dependency.commit, [SHARED_PLATFORM]);
+    if (result.valid.length > 0 && result.corrupted.length === 0 && result.repairRequired.length === 0) {
+        return [];
+    }
+    const removedPlatforms = [];
+    for (const platform of requestedPlatforms) {
+        if (!repairRequiredPlatforms.includes(platform)) {
+            repairRequiredPlatforms.push(platform);
+        }
+        removedPlatforms.push(platform);
+    }
+    await executeLinkStoreRepair(dependency, 'all', {
+        includeShared: true,
+        category: 'shared-corruption',
+    });
+    debug(`${dependency.libName} _shared 本地缓存不完整，准备随平台 [${requestedPlatforms.join(', ') || '无'}] 重新下载`);
+    return removedPlatforms;
+}
+async function hasRequestedPlatformContent(dependency, requestedPlatforms, vars) {
+    if (requestedPlatforms.length === 0)
+        return false;
+    const requestedTargets = [...new Set(requestedPlatforms.flatMap((platform) => getRequestedPlatformTargets(platform, dependency.sparse, vars)))];
+    const storePath = await store.getStorePath();
+    const commitPath = path.join(storePath, dependency.libName, dependency.commit);
+    try {
+        const entries = await fs.readdir(commitPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !requestedTargets.includes(entry.name))
+                continue;
+            if (await store.exists(dependency.libName, dependency.commit, entry.name)) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // Store 目录不存在时继续使用历史记录或后续 General 检测
+    }
+    return false;
+}
 export function assessDownloadResult(requestedPlatforms, sparse, downloadResult, vars) {
     const downloadedActual = new Set(downloadResult.platformDirs);
     const { satisfiedRequested, missingRequested, } = resolveRequestedPlatformsByActual(requestedPlatforms, sparse, downloadResult.platformDirs, vars);
@@ -92,8 +187,9 @@ export function assessDownloadResult(requestedPlatforms, sparse, downloadResult,
         isPureGeneral,
     };
 }
-async function resolveRequestedStoreState(dependency, requestedPlatforms, vars) {
+async function resolveRequestedStoreState(dependency, requestedPlatforms, vars, repairMissingRecords = true) {
     const resolvedExisting = [];
+    const stalePlatforms = [];
     const candidatePlatforms = [...new Set(requestedPlatforms.flatMap((platform) => getRequestedPlatformTargets(platform, dependency.sparse, vars)))];
     for (const platform of candidatePlatforms) {
         if (await store.exists(dependency.libName, dependency.commit, platform)) {
@@ -103,13 +199,13 @@ async function resolveRequestedStoreState(dependency, requestedPlatforms, vars)
             const registry = getRegistry();
             const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
             if (registry.getStore(storeKey)) {
-                registry.removeStore(storeKey);
-                const storePath = await store.getStorePath();
-                const platformPath = store.getLibraryPath(storePath, dependency.libName, dependency.commit, platform);
-                await fs.rm(platformPath, { recursive: true, force: true }).catch(() => { });
+                stalePlatforms.push(platform);
             }
         }
     }
+    if (repairMissingRecords && stalePlatforms.length > 0) {
+        await executeLinkStoreRepair(dependency, stalePlatforms, { category: 'missing-platform-path' });
+    }
     const result = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, resolvedExisting, vars);
     debug(`[link-store-state] ${dependency.libName}@${dependency.commit.slice(0, 7)} 请求平台=${requestedPlatforms.join(', ') || '空'}, Store候选=${candidatePlatforms.join(', ') || '空'}, 实际存在=${result.actualExisting.join(', ') || '无'}, 满足请求=${result.satisfiedRequested.join(', ') || '无'}, 缺失请求=${result.missingRequested.join(', ') || '无'}`);
     return result;
@@ -170,7 +266,7 @@ function upsertLibraryAvailability(dependency, updates) {
         lastAccess: new Date().toISOString(),
     });
 }
-export async function resolveLibraryGeneralState(dependency, requestedPlatforms = [], vars) {
+export async function resolveLibraryGeneralState(dependency, requestedPlatforms = [], vars, updateRegistry = true) {
     const registry = getRegistry();
     const libKey = registry.getLibraryKey(dependency.libName, dependency.commit);
     const library = registry.getLibrary(libKey);
@@ -182,9 +278,9 @@ export async function resolveLibraryGeneralState(dependency, requestedPlatforms
         && library?.isGeneral === false
         && library.platforms.some((platform) => platform !== GENERAL_PLATFORM);
     if (requestedPlatforms.length > 0) {
-        const requestedState = await resolveRequestedStoreState(dependency, requestedPlatforms, vars);
+        const requestedState = await resolveRequestedStoreState(dependency, requestedPlatforms, vars, updateRegistry);
         if (requestedState.actualExisting.length > 0) {
-            if (library?.isGeneral === true) {
+            if (updateRegistry && library?.isGeneral === true) {
                 registry.updateLibrary(libKey, {
                     platforms: requestedState.actualExisting,
                     isGeneral: false,
@@ -195,30 +291,12 @@ export async function resolveLibraryGeneralState(dependency, requestedPlatforms
         }
     }
     if (requestedPlatforms.length > 0 && library?.isGeneral === true) {
-        const requestedTargets = [...new Set(requestedPlatforms.flatMap((platform) => getRequestedPlatformTargets(platform, dependency.sparse, vars)))];
-        const storePath = await store.getStorePath();
-        const commitPath = path.join(storePath, dependency.libName, dependency.commit);
-        try {
-            const entries = await fs.readdir(commitPath, { withFileTypes: true });
-            let hasRequestedPlatformDir = false;
-            for (const entry of entries) {
-                if (!entry.isDirectory() || !requestedTargets.includes(entry.name))
-                    continue;
-                if (await store.exists(dependency.libName, dependency.commit, entry.name)) {
-                    hasRequestedPlatformDir = true;
-                    break;
-                }
-            }
-            if (hasRequestedPlatformDir) {
-                return false;
-            }
-        }
-        catch {
-            // Store 目录不存在时继续使用历史记录或后续 General 检测
+        if (await hasRequestedPlatformContent(dependency, requestedPlatforms, vars)) {
+            return false;
         }
     }
     if (requestedPlatforms.length > 0 && hasPlatformSparse) {
-        if (library?.isGeneral === true) {
+        if (updateRegistry && library?.isGeneral === true) {
             registry.updateLibrary(libKey, {
                 isGeneral: false,
                 lastAccess: new Date().toISOString(),
@@ -231,16 +309,21 @@ export async function resolveLibraryGeneralState(dependency, requestedPlatforms
     }
     if (typeof library?.isGeneral === 'boolean') {
         if (library.isGeneral) {
-            const hasGeneralContent = await store.exists(dependency.libName, dependency.commit, GENERAL_PLATFORM);
-            if (!hasGeneralContent) {
-                registry.updateLibrary(libKey, {
-                    isGeneral: false,
-                    lastAccess: new Date().toISOString(),
-                });
+            const generalState = await verifyGeneralStoreState(dependency);
+            if (!generalState.valid) {
+                if (updateRegistry && (generalState.corrupted || generalState.repairRequired)) {
+                    await executeLinkStoreRepair(dependency, 'all', { category: 'general-state-repair' });
+                }
+                if (updateRegistry) {
+                    registry.updateLibrary(libKey, {
+                        isGeneral: false,
+                        lastAccess: new Date().toISOString(),
+                    });
+                }
                 return false;
             }
             const actualGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
-            if (!actualGeneral) {
+            if (updateRegistry && !actualGeneral) {
                 registry.updateLibrary(libKey, {
                     isGeneral: false,
                     lastAccess: new Date().toISOString(),
@@ -249,7 +332,7 @@ export async function resolveLibraryGeneralState(dependency, requestedPlatforms
             return actualGeneral;
         }
         const actualGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
-        if (actualGeneral) {
+        if (updateRegistry && actualGeneral) {
             registry.updateLibrary(libKey, {
                 platforms: [GENERAL_PLATFORM],
                 isGeneral: true,
@@ -463,7 +546,7 @@ async function linkScope(params) {
     blank();
     // 2. 分类依赖
     const scopePath = path.dirname(path.dirname(configPath));
-    const classified = await classifyDependencies(dependencies, scopePath, configPath, platforms, configVars);
+    const classified = await classifyDependencies(dependencies, scopePath, configPath, platforms, configVars, !dryRun);
     const stats = {
         linked: 0, relink: 0, replace: 0, absorb: 0, missing: 0, linkNew: 0,
     };
@@ -480,14 +563,31 @@ async function linkScope(params) {
     }
     // 4. 磁盘空间预检
     if (stats.missing > 0 && download) {
-        const estimatedSize = stats.missing * 500 * 1024 * 1024;
-        const spaceCheck = await checkDiskSpace(storePath, estimatedSize);
-        if (!spaceCheck.sufficient) {
-            error(`磁盘空间不足: 预计需要 ${formatSize(spaceCheck.required)}，可用 ${formatSize(spaceCheck.available)}（含 1GB 安全余量）`);
-            process.exit(EXIT_CODES.IOERR);
+        const downloadRequests = classified
+            .filter((item) => item.status === DependencyStatus.MISSING)
+            .map((item) => ({
+            libName: item.dependency.libName,
+            commit: item.dependency.commit,
+            platforms: platforms.filter((platform) => !getBlockedRequestedPlatforms(registry, item.dependency, platforms, configVars).includes(platform)),
+        }))
+            .filter((request) => request.platforms.length > 0);
+        const estimate = estimateDownloadSpace(registry, downloadRequests);
+        for (const evidence of estimate.evidence)
+            debug(`[space] 下载容量依据: ${evidence}`);
+        if (estimate.status === 'unknown' || !estimate.amount) {
+            warn(`下载容量未知: ${estimate.warnings.join('; ')}`);
+            debug(`[space] 下载容量预检跳过: requests=${downloadRequests.length}, status=${estimate.status}, warnings=${estimate.warnings.length}`);
         }
-        if (spaceCheck.available === 0) {
-            warn('无法获取磁盘空间信息，继续执行');
+        else if (downloadRequests.length > 0) {
+            const spaceCheck = await checkDiskSpace(storePath, estimate.amount.bytes);
+            debug(`[space] 下载容量预检: requests=${downloadRequests.length}, estimated=${estimate.amount.bytes}, available=${spaceCheck.available}, required=${spaceCheck.required}, sufficient=${spaceCheck.sufficient}`);
+            if (!spaceCheck.sufficient) {
+                error(`磁盘空间不足: 预计需要 ${formatSize(spaceCheck.required)}，可用 ${formatSize(spaceCheck.available)}（含 1GB 安全余量）`);
+                process.exit(EXIT_CODES.IOERR);
+            }
+            if (spaceCheck.available === 0) {
+                warn('无法获取磁盘空间信息，继续执行');
+            }
         }
     }
     // 5. 预扫描额外平台（仅主项目 scope）
@@ -601,7 +701,7 @@ async function linkScope(params) {
     }
     // 7. 逐个处理依赖（LINKED/RELINK/REPLACE/ABSORB/LINK_NEW）
     for (const item of classified) {
-        const { dependency, status, localPath } = item;
+        const { dependency, status, localPath, repairRequiredPlatforms } = item;
         await store.ensureCompatibleStore(storePath, dependency.libName, dependency.commit);
         switch (status) {
             case DependencyStatus.LINKED: {
@@ -612,6 +712,7 @@ async function linkScope(params) {
                     const supplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, {
                         vars: configVars,
                         useGitLightweightDownload: gitLightweightDownload,
+                        repairRequiredPlatforms,
                     });
                     await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
                     if (supplementResult.downloaded.length > 0) {
@@ -648,6 +749,7 @@ async function linkScope(params) {
                     const relinkSupplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, {
                         vars: configVars,
                         useGitLightweightDownload: gitLightweightDownload,
+                        repairRequiredPlatforms,
                     });
                     await registerNestedLibraries(relinkSupplementResult.nestedLibraries, projectHash);
                     const { actualExisting: relinkExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
@@ -705,6 +807,7 @@ async function linkScope(params) {
                     const replaceSupplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, {
                         vars: configVars,
                         useGitLightweightDownload: gitLightweightDownload,
+                        repairRequiredPlatforms,
                     });
                     await registerNestedLibraries(replaceSupplementResult.nestedLibraries, projectHash);
                     const { actualExisting: replaceExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
@@ -814,6 +917,7 @@ async function linkScope(params) {
                     const absorbSupplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, {
                         vars: configVars,
                         useGitLightweightDownload: gitLightweightDownload,
+                        repairRequiredPlatforms,
                     });
                     await registerNestedLibraries(absorbSupplementResult.nestedLibraries, projectHash);
                     if (absorbSupplementResult.downloaded.length > 0) {
@@ -880,9 +984,20 @@ async function linkScope(params) {
                 const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
                 const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
                 const { missingRequested: missing } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
+                const repairRequiredSet = new Set(repairRequiredPlatforms ?? []);
+                const repairDownloadTargets = missing.filter((platform) => repairRequiredSet.has(platform));
+                const isRepairingGeneral = repairRequiredSet.has(GENERAL_PLATFORM);
                 const linkNewLibId = `${dependency.libName}@${dependency.commit}`;
                 if (missing.length > 0 && !skipAllDownloads && downloadConfirmedLibs.has(linkNewLibId)) {
-                    info(`${dependency.libName} 缺少平台 [${missing.join(', ')}]，开始下载...`);
+                    if (repairDownloadTargets.length > 0 || isRepairingGeneral) {
+                        const repairTargetText = repairDownloadTargets.length > 0
+                            ? repairDownloadTargets.join(', ')
+                            : GENERAL_PLATFORM;
+                        debug(`${dependency.libName} ${repairTargetText} 本地缓存不完整，开始重新下载`);
+                    }
+                    else {
+                        info(`${dependency.libName} 缺少平台 [${missing.join(', ')}]，开始下载...`);
+                    }
                     const linkNewLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
                     const linkNewHistoryLib = registry.getLibrary(linkNewLibKey);
                     const linkNewMonitor = new DownloadMonitor({
@@ -898,6 +1013,17 @@ async function linkScope(params) {
                             onHeartbeat: (message) => { linkNewMonitor.heartbeat(message); },
                         });
                     }
+                    catch (err) {
+                        if (repairDownloadTargets.length > 0 || isRepairingGeneral) {
+                            const repairTargetText = repairDownloadTargets.length > 0
+                                ? repairDownloadTargets.join(', ')
+                                : GENERAL_PLATFORM;
+                            error(`${dependency.libName} ${repairTargetText} 本地缓存不完整，自动重新下载失败`);
+                            hint(`可运行 td reset ${dependency.libName} 后重试`);
+                            debug(`${dependency.libName} 下载失败: ${err.message}`);
+                        }
+                        throw err;
+                    }
                     finally {
                         await linkNewMonitor.stop();
                     }
@@ -912,6 +1038,10 @@ async function linkScope(params) {
                             tx.recordOp('absorb', linkNewCommitPath, downloadResult.libDir);
                             const linkNewAbsorbResult = await store.absorbLib(downloadResult.libDir, filteredDownloaded, dependency.libName, dependency.commit);
                             await registerNestedLibraries(linkNewAbsorbResult.nestedLibraries, projectHash);
+                            const repaired = filteredDownloaded.filter((platform) => repairRequiredSet.has(platform));
+                            if (repaired.length > 0) {
+                                warn(`${dependency.libName} ${repaired.join(', ')} 本地缓存不完整，已重新下载`);
+                            }
                         }
                     }
                     finally {
@@ -927,7 +1057,12 @@ async function linkScope(params) {
                     await linker.linkGeneral(localPath, sharedPath);
                     await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], projectHash, true);
                     generalLibs.add(dependency.libName);
-                    success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，创建链接`);
+                    if (isRepairingGeneral) {
+                        warn(`${dependency.libName} ${GENERAL_PLATFORM} 本地缓存不完整，已重新下载`);
+                    }
+                    else {
+                        success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，创建链接`);
+                    }
                 }
                 else if (linkNewExisting.length === 0) {
                     const { KNOWN_PLATFORM_VALUES } = await import('../core/platform.js');
@@ -977,13 +1112,14 @@ async function linkScope(params) {
             const multiBarManager = isTTY ? new MultiBarManager() : null;
             const downloadLimit = pLimit(concurrency);
             const downloadTasks = toDownload.map((item) => downloadLimit(async () => {
-                const { dependency, localPath } = item;
+                const { dependency, localPath, repairRequiredPlatforms = [] } = item;
+                const repairRequiredSet = new Set(repairRequiredPlatforms);
                 const pLog = {
                     info: (msg) => multiBarManager ? multiBarManager.log(`[info] ${msg}`) : info(msg),
                     success: (msg) => multiBarManager ? multiBarManager.log(`[ok] ${msg}`) : success(msg),
                     hint: (msg) => multiBarManager ? multiBarManager.log(`[hint] ${msg}`) : hint(msg),
                     warn: (msg) => multiBarManager ? multiBarManager.log(`[warn] ${msg}`) : warn(msg),
-                    error: (msg) => multiBarManager ? multiBarManager.log(`[error] ${msg}`) : error(msg),
+                    error: (msg) => multiBarManager ? multiBarManager.log(`[err] ${msg}`) : error(msg),
                 };
                 try {
                     const storeCommitPath = path.join(storePath, dependency.libName, dependency.commit);
@@ -1038,7 +1174,17 @@ async function linkScope(params) {
                         }
                         return { success: false, name: dependency.libName, skipped: true, skippedPlatforms: missing, unsupported: true };
                     }
-                    pLog.info(`下载 ${dependency.libName} [${dlToDownload.join(', ')}]...`);
+                    const repairDownloadTargets = dlToDownload.filter((platform) => repairRequiredSet.has(platform));
+                    const isRepairingGeneral = repairRequiredSet.has(GENERAL_PLATFORM);
+                    if (repairDownloadTargets.length === 0 && !isRepairingGeneral) {
+                        pLog.info(`下载 ${dependency.libName} [${dlToDownload.join(', ')}]...`);
+                    }
+                    else {
+                        const repairTargetText = repairDownloadTargets.length > 0
+                            ? repairDownloadTargets.join(', ')
+                            : GENERAL_PLATFORM;
+                        debug(`${dependency.libName} ${repairTargetText} 本地缓存不完整，开始重新下载`);
+                    }
                     const estimatedSize = historyLib?.size;
                     const downloadMonitor = new DownloadMonitor({
                         name: `  ${dependency.libName}`, estimatedSize, getDirSize,
@@ -1076,7 +1222,15 @@ async function linkScope(params) {
                             await linker.linkGeneral(localPath, sharedPath);
                             await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], projectHash, true);
                             generalLibs.add(dependency.libName);
-                            pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，下载完成`);
+                            if (isRepairingGeneral) {
+                                pLog.warn(`${dependency.libName} ${GENERAL_PLATFORM} 本地缓存不完整，已重新下载`);
+                            }
+                            else if (repairDownloadTargets.length > 0) {
+                                pLog.warn(`${dependency.libName} ${repairDownloadTargets.join(', ')} 本地缓存不完整，已重新下载`);
+                            }
+                            else {
+                                pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，下载完成`);
+                            }
                             return { success: true, name: dependency.libName, downloadedPlatforms: [GENERAL_PLATFORM], skippedPlatforms: [], isGeneral: true };
                         }
                         const filteredDownloaded = assessment.downloadedRequested;
@@ -1111,7 +1265,13 @@ async function linkScope(params) {
                         await linker.linkLib(localPath, storeCommitPath, linkPlatforms);
                         await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, linkPlatforms, projectHash, false);
                         const notLinkedPlatforms = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, linkPlatforms, configVars).missingRequested;
-                        pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 下载完成 [${linkPlatforms.join(', ')}]`);
+                        const repaired = filteredDownloaded.filter((platform) => repairRequiredSet.has(platform));
+                        if (repaired.length > 0) {
+                            pLog.warn(`${dependency.libName} ${repaired.join(', ')} 本地缓存不完整，已重新下载`);
+                        }
+                        else {
+                            pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 下载完成 [${linkPlatforms.join(', ')}]`);
+                        }
                         return { success: true, name: dependency.libName, downloadedPlatforms: linkPlatforms, skippedPlatforms: notLinkedPlatforms };
                     }
                     finally {
@@ -1119,8 +1279,22 @@ async function linkScope(params) {
                     }
                 }
                 catch (err) {
-                    pLog.error(`${dependency.libName} 下载失败: ${err.message}`);
-                    return { success: false, name: dependency.libName, error: err.message };
+                    const repairTargets = repairRequiredPlatforms.filter((platform) => platforms.includes(platform) || platform === GENERAL_PLATFORM);
+                    const repairFailure = repairTargets.length > 0;
+                    if (repairTargets.length > 0) {
+                        pLog.error(`${dependency.libName} ${repairTargets.join(', ')} 本地缓存不完整，自动重新下载失败`);
+                        pLog.hint(`可运行 td reset ${dependency.libName} 后重试`);
+                        debug(`${dependency.libName} 下载失败: ${err.message}`);
+                    }
+                    else {
+                        pLog.error(`${dependency.libName} 下载失败: ${err.message}`);
+                    }
+                    return {
+                        success: false,
+                        name: dependency.libName,
+                        error: err.message,
+                        repairFailure,
+                    };
                 }
             }));
             const results = await Promise.all(downloadTasks);
@@ -1131,6 +1305,12 @@ async function linkScope(params) {
             info(`下载完成: ${succeeded.length}/${toDownload.length} 个库`);
             if (failed.length > 0)
                 warn(`${failed.length} 个库下载失败`);
+            const failedRepairs = failed.filter((result) => 'repairFailure' in result && result.repairFailure);
+            if (failedRepairs.length > 0) {
+                const names = failedRepairs.map((result) => result.name).join(', ');
+                debug(`[link] 缓存修复下载失败，终止链接: libraries=${names}`);
+                throw new Error(`缓存修复下载失败: ${names}`);
+            }
             const allSkipped = [];
             for (const r of results) {
                 if ('skippedPlatforms' in r && r.skippedPlatforms && r.skippedPlatforms.length > 0) {
@@ -1207,7 +1387,10 @@ async function linkScope(params) {
 export async function linkProject(projectPath, options) {
     const { absolutePath, normalizedPath, configPath: discoveredConfigPath, } = await resolveProjectRootPath(projectPath);
     // === 阶段 1: 初始化 ===
-    const cfg = await config.load();
+    const cfg = await config.load({ migrate: !options.dryRun });
+    if (options.dryRun && cfg && config.checkConfigVersion(cfg) === 'migrate') {
+        throw new Error('配置需要迁移；dry-run 不会修改配置，请先运行一次普通命令完成迁移');
+    }
     if (cfg?.logLevel)
         setLogLevel(cfg.logLevel);
     if (cfg?.proxy)
@@ -1215,7 +1398,7 @@ export async function linkProject(projectPath, options) {
     const concurrency = cfg?.concurrency ?? 5;
     const gitLightweightDownload = cfg?.gitLightweightDownload ?? true;
     const registry = getRegistry();
-    await registry.load();
+    await registry.load({ migrate: !options.dryRun });
     const existingProject = registry.getProjectByPath(normalizedPath);
     const rememberedPlatforms = existingProject?.platforms;
     // 确定平台列表
@@ -1348,24 +1531,37 @@ export async function linkProject(projectPath, options) {
         }
     }
     const finalPath = normalizedRoot;
-    // 检查是否有未完成的事务需要恢复
-    const pendingTx = await Transaction.findPending();
-    if (pendingTx) {
-        warn(`发现未完成的事务 (${pendingTx.id.slice(0, 8)})`);
-        info('正在尝试回滚...');
-        try {
-            await pendingTx.rollback();
-            success('事务回滚完成');
-        }
-        catch (err) {
-            error(`回滚失败: ${err.message}`);
-            hint('请手动检查 Store 和项目目录状态');
+    // 预演模式只读取现状，不恢复历史事务，也不创建新的持久事务日志。
+    if (!options.dryRun) {
+        const pendingTx = await Transaction.findPending();
+        if (pendingTx) {
+            warn(`发现未完成的事务 (${pendingTx.id.slice(0, 8)})`);
+            info('正在尝试回滚...');
+            try {
+                await pendingTx.rollback();
+                success('事务回滚完成');
+            }
+            catch (err) {
+                error(`回滚失败: ${err.message}`);
+                hint('请手动检查 Store 和项目目录状态');
+            }
         }
     }
+    else {
+        const pendingTransactions = await Transaction.getPendingTransactions();
+        debug(`[link] dry-run 跳过事务恢复与事务日志创建: pending=${pendingTransactions.length}`);
+    }
     const storePath = await store.getStorePath();
+    if (!options.dryRun) {
+        const recovered = await new SpaceService(registry, storePath)
+            .createCleanupExecutor()
+            .recoverPending();
+        debug(`[link] 清理日志恢复完成: recovered=${recovered}, store=${storePath}`);
+    }
     const projectHash = registry.hashPath(finalPath);
     const tx = new Transaction(`link:${finalPath}`);
-    await tx.begin();
+    if (!options.dryRun)
+        await tx.begin();
     // === 阶段 4: 依次执行 linkScope ===
     try {
         // 主项目
@@ -1514,52 +1710,44 @@ export async function linkProject(projectPath, options) {
         if (allSavedBytes > 0) {
             info(`本次节省: ${formatSize(allSavedBytes)}`);
         }
-        const totalSize = await store.getTotalSize();
-        info(`Store 总计: ${formatSize(totalSize)}`);
-        const unreferencedStores = registry.getUnreferencedStores();
-        if (unreferencedStores.length > 0) {
-            const unreferencedSize = unreferencedStores.reduce((sum, entry) => sum + entry.size, 0);
-            hint(`无引用: ${unreferencedStores.length} 个 (${formatSize(unreferencedSize)}) - 可用 td clean 清理`);
+        const spaceService = new SpaceService(registry, storePath);
+        const spaceSnapshot = await spaceService.buildSnapshot('summary');
+        info(`Store 总计: ${formatSize(spaceSnapshot.totals.physical.bytes)}`);
+        const cleanupCandidates = spaceService.getCleanupCandidates(spaceSnapshot);
+        const allCleanup = buildUnreferencedSelectionSummary(cleanupCandidates);
+        if (allCleanup.platformCount > 0) {
+            hint(`无引用: ${allCleanup.platformCount} 个 (约 ${formatSize(allCleanup.registeredBytes)}) - 可用 td clean 清理`);
             // capacity 策略：检查是否超过阈值
             const cleanStrategy = await config.get('cleanStrategy');
             if (cleanStrategy === 'capacity') {
                 const threshold = (await config.get('unreferencedThreshold')) ?? 10 * 1024 * 1024 * 1024;
-                if (unreferencedSize > threshold) {
+                if (allCleanup.registeredBytes > threshold) {
                     blank();
-                    warn(`无引用库容量 (${formatSize(unreferencedSize)}) 已超过阈值 (${formatSize(threshold)})`);
+                    warn(`无引用库容量 (约 ${formatSize(allCleanup.registeredBytes)}) 已超过阈值 (${formatSize(threshold)})`);
                     if (!options.yes && process.stdout.isTTY) {
-                        // 交互模式：提供选项
-                        const halfCleanStores = registry.getStoresForHalfClean();
-                        const halfCleanSize = halfCleanStores.reduce((sum, e) => sum + e.size, 0);
+                        const halfCleanup = buildHalfCleanupSelectionSummary(cleanupCandidates);
                         const action = await selectOption('选择清理方式:', [
                             { name: '跳过本次', value: 'skip' },
                             {
-                                name: `清理最久未引用的 (释放约 ${formatSize(halfCleanSize)})`,
+                                name: `清理最久未引用的 (释放约 ${formatSize(halfCleanup.registeredBytes)})`,
                                 value: 'half',
                             },
-                            { name: `全部清理 (释放 ${formatSize(unreferencedSize)})`, value: 'all' },
+                            { name: `全部清理 (释放约 ${formatSize(allCleanup.registeredBytes)})`, value: 'all' },
                         ]);
                         // ESC 取消视为跳过
                         if (action !== PROMPT_CANCELLED && action !== 'skip') {
-                            const toClean = action === 'half' ? halfCleanStores : unreferencedStores;
+                            const cleanup = action === 'half' ? halfCleanup : allCleanup;
+                            const plan = await spaceService.buildCleanupPlan({
+                                reason: 'capacity',
+                                selections: cleanup.selections,
+                                requireUnreferenced: true,
+                            });
+                            for (const planWarning of plan.warnings)
+                                warn(`[space] ${planWarning}`);
                             blank();
-                            info('正在清理...');
-                            let cleaned = 0;
-                            let freedSize = 0;
-                            for (const entry of toClean) {
-                                try {
-                                    await store.remove(entry.libName, entry.commit, entry.platform);
-                                    const storeKey = registry.getStoreKey(entry.libName, entry.commit, entry.platform);
-                                    registry.removeStore(storeKey);
-                                    freedSize += entry.size;
-                                    cleaned++;
-                                }
-                                catch (cleanErr) {
-                                    warn(`清理 ${entry.libName}/${entry.platform} 失败: ${cleanErr.message}`);
-                                }
-                            }
-                            await registry.save();
-                            success(`清理完成: 删除 ${cleaned} 个库，释放 ${formatSize(freedSize)}`);
+                            info(`正在执行清理计划 ${plan.id}...`);
+                            const cleanupResult = await spaceService.createCleanupExecutor().execute(plan);
+                            success(`清理完成: 删除 ${cleanupResult.succeeded.length} 项，释放 ${formatSize(cleanupResult.released.bytes)}`);
                         }
                     }
                     else {
@@ -1577,14 +1765,16 @@ export async function linkProject(projectPath, options) {
         // 链接过程出错，回滚事务
         error(`链接失败: ${err.message}`);
         hintStoreRepairCommand(err);
-        warn('正在回滚事务...');
-        try {
-            await tx.rollback();
-            success('事务已回滚');
-        }
-        catch (rollbackErr) {
-            error(`回滚失败: ${rollbackErr.message}`);
-            hint('请手动检查 Store 和项目目录状态');
+        if (!options.dryRun) {
+            warn('正在回滚事务...');
+            try {
+                await tx.rollback();
+                success('事务已回滚');
+            }
+            catch (rollbackErr) {
+                error(`回滚失败: ${rollbackErr.message}`);
+                hint('请手动检查 Store 和项目目录状态');
+            }
         }
         process.exit(1);
     }
@@ -1673,14 +1863,11 @@ async function ensureStoreInfo(libName, commit, platform, branch, url, projectHa
             lastAccess: new Date().toISOString(),
         });
     }
-    else if (existingEntry.fileCount == null) {
-        const integrity = await store.captureIntegrity(libName, commit, platform);
-        registry.updateStore(storeKey, integrity);
-    }
-    if (existingEntry && ((!existingEntry.branch && branch) || (!existingEntry.url && url))) {
+    const currentEntry = registry.getStore(storeKey);
+    if (currentEntry && ((!currentEntry.branch && branch) || (!currentEntry.url && url))) {
         registry.updateStore(storeKey, {
-            branch: existingEntry.branch || branch,
-            url: existingEntry.url || url,
+            branch: currentEntry.branch || branch,
+            url: currentEntry.url || url,
             lastAccess: new Date().toISOString(),
         });
     }
@@ -1895,7 +2082,7 @@ export async function classifyLinkStatus(localPath, storeCommitPath, isGeneral,
  * @param configPath 配置文件路径
  * @param platforms 请求的平台列表
  */
-async function classifyDependencies(dependencies, projectPath, configPath, platforms, vars) {
+async function classifyDependencies(dependencies, projectPath, configPath, platforms, vars, repairStore = true) {
     const result = [];
     const thirdPartyDir = path.dirname(configPath);
     const storePath = await store.getStorePath();
@@ -1909,24 +2096,33 @@ async function classifyDependencies(dependencies, projectPath, configPath, platf
         const blockedPlatforms = getBlockedRequestedPlatforms(getRegistry(), dep, platforms, vars);
         const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
         // 检查 Store 中是否有任意请求的平台（支持 sparse 承载目录）
-        const { actualExisting: rawExisting, satisfiedRequested, } = await resolveRequestedStoreState(dep, requestedPlatforms, vars);
+        const { actualExisting: rawExisting, satisfiedRequested, } = await resolveRequestedStoreState(dep, requestedPlatforms, vars, repairStore);
+        const registry = getRegistry();
+        const libKey = registry.getLibraryKey(dep.libName, dep.commit);
+        const library = registry.getLibrary(libKey);
         // 完整性校验：验证 existing 平台的文件完整性
-        const { valid: verifiedExisting, corrupted } = await verifyExistingPlatforms(dep.libName, dep.commit, rawExisting);
+        const { valid: verifiedExisting, corrupted, repairRequired } = await verifyExistingPlatforms(dep.libName, dep.commit, rawExisting);
         // 清除损坏的平台数据
-        if (corrupted.length > 0) {
-            const registry = getRegistry();
-            for (const platform of corrupted) {
-                const storeKey = registry.getStoreKey(dep.libName, dep.commit, platform);
-                registry.removeStore(storeKey);
-                const platformPath = store.getLibraryPath(storePath, dep.libName, dep.commit, platform);
-                await fs.rm(platformPath, { recursive: true, force: true }).catch(() => { });
+        if (repairStore && (corrupted.length > 0 || repairRequired.length > 0)) {
+            await executeLinkStoreRepair(dep, [...new Set([...corrupted, ...repairRequired])], { category: 'classified-platform-corruption' });
+        }
+        let existing = verifiedExisting;
+        const repairRequiredPlatforms = [...repairRequired];
+        if (library?.isGeneral === true &&
+            !(await hasRequestedPlatformContent(dep, requestedPlatforms, vars))) {
+            if (repairStore)
+                await prepareGeneralStoreRepair(dep, repairRequiredPlatforms);
+        }
+        if (repairStore && existing.length > 0) {
+            const sharedRepairPlatforms = await prepareSharedStoreRepair(dep, existing, repairRequiredPlatforms);
+            if (sharedRepairPlatforms.length > 0) {
+                existing = existing.filter((platform) => !sharedRepairPlatforms.includes(platform));
             }
         }
-        const existing = verifiedExisting;
         // 也检查是否为 General 库（有 _shared 且有内容）
-        const isGeneral = await resolveLibraryGeneralState(dep, requestedPlatforms, vars);
+        const isGeneral = await resolveLibraryGeneralState(dep, requestedPlatforms, vars, repairStore);
         const inStore = existing.length > 0 || isGeneral;
-        if (satisfiedRequested.length > 0) {
+        if (repairStore && satisfiedRequested.length > 0) {
             clearSatisfiedAutoUnavailablePlatforms(getRegistry(), dep, satisfiedRequested);
         }
         // 用于非 inStore 情况的本地路径状态检查
@@ -2004,6 +2200,7 @@ async function classifyDependencies(dependencies, projectPath, configPath, platf
             status,
             localPath,
             storePath: storeLibPath,
+            repairRequiredPlatforms,
         });
     }
     return result;
@@ -2012,6 +2209,7 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
     const result = { downloaded: [], unavailable: [], nestedLibraries: [] };
     const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, options.vars);
     const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
+    const repairRequiredPlatforms = new Set(options.repairRequiredPlatforms ?? []);
     // 1. 检查平台完整性
     const { missingRequested, satisfiedRequested } = await resolveRequestedStoreState(dependency, requestedPlatforms, options.vars);
     const missing = missingRequested;
@@ -2025,6 +2223,7 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
     const toDownload = options.forceDownload
         ? missing
         : missing.filter((p) => !unavailablePlatforms.includes(p));
+    const repairDownloadTargets = toDownload.filter((platform) => repairRequiredPlatforms.has(platform));
     if (toDownload.length === 0) {
         // 所有缺失平台都是已知不可用的
         if (missing.length > 0) {
@@ -2034,7 +2233,12 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
         return result;
     }
     // 4. 尝试下载
-    info(`${dependency.libName} 缺少平台 [${toDownload.join(', ')}]，尝试下载...`);
+    if (repairDownloadTargets.length > 0) {
+        debug(`${dependency.libName} ${repairDownloadTargets.join(', ')} 本地缓存不完整，开始重新下载`);
+    }
+    else {
+        info(`${dependency.libName} 缺少平台 [${toDownload.join(', ')}]，尝试下载...`);
+    }
     try {
         const downloadResult = await codepac.downloadToTemp({
             url: dependency.url,
@@ -2056,6 +2260,10 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
             const downloaded = assessment.downloadedRequested;
             result.downloaded = downloaded;
             clearSatisfiedAutoUnavailablePlatforms(registry, dependency, assessment.satisfiedRequested);
+            const repaired = downloaded.filter((platform) => repairRequiredPlatforms.has(platform));
+            if (repaired.length > 0) {
+                warn(`${dependency.libName} ${repaired.join(', ')} 本地缓存不完整，已重新下载`);
+            }
             // 6. 记录新发现的不可用平台
             const notFound = assessment.unavailableRequested;
             if (notFound.length > 0) {
@@ -2095,7 +2303,9 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
                 }
                 // 注册 _shared 目录（如果存在）
                 await registerSharedStore(dependency.libName, dependency.commit, dependency.branch, dependency.url);
-                success(`${dependency.libName} 已补充平台 [${downloaded.join(', ')}]`);
+                if (repaired.length === 0) {
+                    success(`${dependency.libName} 已补充平台 [${downloaded.join(', ')}]`);
+                }
             }
         }
         finally {
@@ -2104,7 +2314,16 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
         }
     }
     catch (err) {
-        warn(`${dependency.libName} 下载失败: ${err.message}`);
+        const repairTargets = toDownload.filter((platform) => repairRequiredPlatforms.has(platform));
+        if (repairTargets.length > 0) {
+            error(`${dependency.libName} ${repairTargets.join(', ')} 本地缓存不完整，自动重新下载失败`);
+            hint(`可运行 td reset ${dependency.libName} 后重试`);
+            debug(`${dependency.libName} 下载失败: ${err.message}`);
+            throw err;
+        }
+        else {
+            warn(`${dependency.libName} 下载失败: ${err.message}`);
+        }
     }
     return result;
 }
@@ -2358,6 +2577,7 @@ async function linkNestedDependencies(dependencies, params) {
         const knownUnavailable = platforms.filter(p => unavailablePlatforms.includes(p));
         let storeHas = false;
         let existingPlatforms = [];
+        let repairRequiredPlatforms = [];
         const initialStoreState = await resolveRequestedStoreState(dep, availablePlatforms, vars);
         existingPlatforms.push(...initialStoreState.actualExisting);
         if (initialStoreState.satisfiedRequested.length > 0) {
@@ -2366,15 +2586,27 @@ async function linkNestedDependencies(dependencies, params) {
         storeHas = existingPlatforms.length > 0;
         // 完整性校验：验证 existing 平台的文件完整性（与 classifyDependencies 同逻辑）
         if (existingPlatforms.length > 0) {
-            const { valid: verifiedPlatforms, corrupted } = await verifyExistingPlatforms(dep.libName, dep.commit, existingPlatforms);
+            const { valid: verifiedPlatforms, corrupted, repairRequired } = await verifyExistingPlatforms(dep.libName, dep.commit, existingPlatforms);
             existingPlatforms = verifiedPlatforms;
-            if (corrupted.length > 0) {
-                for (const p of corrupted) {
-                    const storeKey = registry.getStoreKey(dep.libName, dep.commit, p);
-                    registry.removeStore(storeKey);
-                    const platformPath = store.getLibraryPath(await store.getStorePath(), dep.libName, dep.commit, p);
-                    await fs.rm(platformPath, { recursive: true, force: true }).catch(() => { });
-                }
+            repairRequiredPlatforms = repairRequired;
+            if (corrupted.length > 0 || repairRequired.length > 0) {
+                await executeLinkStoreRepair(dep, [...new Set([...corrupted, ...repairRequired])], { category: 'nested-platform-corruption' });
+            }
+            storeHas = existingPlatforms.length > 0;
+        }
+        const nestedLibKey = registry.getLibraryKey(dep.libName, dep.commit);
+        const nestedLibrary = registry.getLibrary(nestedLibKey);
+        if (nestedLibrary?.isGeneral === true &&
+            !(await hasRequestedPlatformContent(dep, availablePlatforms, vars))) {
+            const generalNeedsRepair = await prepareGeneralStoreRepair(dep, repairRequiredPlatforms);
+            if (generalNeedsRepair) {
+                storeHas = existingPlatforms.length > 0;
+            }
+        }
+        if (existingPlatforms.length > 0) {
+            const sharedRepairPlatforms = await prepareSharedStoreRepair(dep, existingPlatforms, repairRequiredPlatforms);
+            if (sharedRepairPlatforms.length > 0) {
+                existingPlatforms = existingPlatforms.filter((platform) => !sharedRepairPlatforms.includes(platform));
             }
             storeHas = existingPlatforms.length > 0;
         }
@@ -2468,7 +2700,7 @@ async function linkNestedDependencies(dependencies, params) {
                 let linkedPlatforms = isGeneral ? [GENERAL_PLATFORM] : [...existingPlatforms];
                 // 已链接，但需要检查是否需要补充缺失平台（与顶层依赖逻辑一致）
                 if (!isGeneral) {
-                    const supplementResult = await supplementMissingPlatforms(dep, platforms, registry, tx, { vars, useGitLightweightDownload: options.gitLightweightDownload });
+                    const supplementResult = await supplementMissingPlatforms(dep, platforms, registry, tx, { vars, useGitLightweightDownload: options.gitLightweightDownload, repairRequiredPlatforms });
                     // 注册嵌套依赖
                     if (supplementResult.nestedLibraries.length > 0) {
                         await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
@@ -2539,7 +2771,7 @@ async function linkNestedDependencies(dependencies, params) {
             }
             else {
                 // 平台库：先补充缺失平台（与顶层依赖逻辑一致）
-                const supplementResult = await supplementMissingPlatforms(dep, platforms, registry, tx, { vars, useGitLightweightDownload: options.gitLightweightDownload });
+                const supplementResult = await supplementMissingPlatforms(dep, platforms, registry, tx, { vars, useGitLightweightDownload: options.gitLightweightDownload, repairRequiredPlatforms });
                 // 注册嵌套依赖
                 if (supplementResult.nestedLibraries.length > 0) {
                     await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
@@ -2565,7 +2797,13 @@ async function linkNestedDependencies(dependencies, params) {
         }
         else if (download) {
             // Store 没有，需要下载
-            info(`${indent}  ${dep.libName} - 下载中...`);
+            const repairTargets = repairRequiredPlatforms.filter((platform) => availablePlatforms.includes(platform) || platform === GENERAL_PLATFORM);
+            if (repairTargets.length > 0) {
+                debug(`${indent}  ${dep.libName} ${repairTargets.join(', ')} 本地缓存不完整，开始重新下载`);
+            }
+            else {
+                info(`${indent}  ${dep.libName} - 下载中...`);
+            }
             if (dryRun) {
                 info(`${indent}  ${dep.libName} - 将下载`);
                 continue;
@@ -2623,7 +2861,12 @@ async function linkNestedDependencies(dependencies, params) {
                         platform: GENERAL_PLATFORM,
                         linkedPath: path.relative(projectRoot, localPath),
                     });
-                    success(`${indent}  ${dep.libName} - 下载完成 (General)`);
+                    if (repairTargets.includes(GENERAL_PLATFORM)) {
+                        warn(`${indent}  ${dep.libName} ${GENERAL_PLATFORM} 本地缓存不完整，已重新下载`);
+                    }
+                    else {
+                        success(`${indent}  ${dep.libName} - 下载完成 (General)`);
+                    }
                 }
                 else if (assessment.downloadedRequested.length > 0) {
                     // 平台库处理
@@ -2652,7 +2895,13 @@ async function linkNestedDependencies(dependencies, params) {
                         });
                         warn(`${indent}  ${dep.libName} 平台 [${newUnavailable.join(', ')}] 远程不存在，已记录`);
                     }
-                    success(`${indent}  ${dep.libName} - 下载完成 [${assessment.downloadedRequested.join(', ')}]`);
+                    const repaired = assessment.downloadedRequested.filter((platform) => repairRequiredPlatforms.includes(platform));
+                    if (repaired.length > 0) {
+                        warn(`${indent}  ${dep.libName} ${repaired.join(', ')} 本地缓存不完整，已重新下载`);
+                    }
+                    else {
+                        success(`${indent}  ${dep.libName} - 下载完成 [${assessment.downloadedRequested.join(', ')}]`);
+                    }
                 }
                 else {
                     // 所有请求的平台都不可用，记录到 registry
@@ -2672,7 +2921,15 @@ async function linkNestedDependencies(dependencies, params) {
                 }
             }
             catch (err) {
-                warn(`${indent}  ${dep.libName} - 下载失败: ${err.message}`);
+                if (repairTargets.length > 0) {
+                    error(`${indent}  ${dep.libName} ${repairTargets.join(', ')} 本地缓存不完整，自动重新下载失败`);
+                    hint(`${indent}  可运行 td reset ${dep.libName} 后重试`);
+                    debug(`${indent}  ${dep.libName} 下载失败: ${err.message}`);
+                    throw err;
+                }
+                else {
+                    warn(`${indent}  ${dep.libName} - 下载失败: ${err.message}`);
+                }
             }
         }
         else {
@@ -2703,73 +2960,37 @@ function mergeDepLists(main, optional) {
     return Array.from(depMap.values());
 }
 /**
- * 校验已有平台的完整性
- * 遍历 existing 平台列表，查询 Registry 中的 StoreEntry，
- * 如果有 fileCount，调用 quickVerify 校验；匹配则保留，不匹配则标记为 corrupted。
- * 没有 fileCount 的条目跳过校验（视为合法）。
+ * 校验已有平台的完整性。
+ * 只有带 fileCount 和 contentHash 的 StoreEntry 才被视为可验证缓存。
+ * 缺失完整性记录的旧缓存不能证明自身完整，会被标记为需要重新下载。
  *
  * @param libName 库名
  * @param commit commit hash
  * @param existingPlatforms Store 中已有的平台列表
- * @returns { valid: string[]; corrupted: string[] } 合法和损坏的平台列表
+ * @returns { valid: string[]; corrupted: string[]; repairRequired: string[] } 合法、损坏和需要重下的平台列表
  */
 export async function verifyExistingPlatforms(libName, commit, existingPlatforms) {
     const valid = [];
     const corrupted = [];
+    const repairRequired = [];
     const registry = getRegistry();
     for (const platform of existingPlatforms) {
         const storeKey = registry.getStoreKey(libName, commit, platform);
         const entry = registry.getStore(storeKey);
+        const visiblePlatform = platform === GENERAL_PLATFORM ? '_shared' : platform;
         if (!entry) {
-            try {
-                const integrity = await store.captureIntegrity(libName, commit, platform);
-                if (integrity.fileCount === 0) {
-                    corrupted.push(platform);
-                    warn(`${libName} (${commit.slice(0, 7)}) ${platform}: Store 目录为空`);
-                    continue;
-                }
-                registry.addStore({
-                    libName,
-                    commit,
-                    platform,
-                    branch: '',
-                    url: '',
-                    ...integrity,
-                    usedBy: [],
-                    createdAt: new Date().toISOString(),
-                    lastAccess: new Date().toISOString(),
-                });
-            }
-            catch {
-                corrupted.push(platform);
-                warn(`${libName} (${commit.slice(0, 7)}) ${platform}: Store 完整性回填失败`);
-                continue;
-            }
-            valid.push(platform);
+            repairRequired.push(platform);
+            debug(`${libName} (${commit.slice(0, 7)}) ${visiblePlatform}: Store 缺少 Registry 记录，准备重新下载`);
             continue;
         }
         if (entry.fileCount === 0) {
             corrupted.push(platform);
-            warn(`${libName} (${commit.slice(0, 7)}) ${platform}: Store 记录为空`);
+            warn(`${libName} (${commit.slice(0, 7)}) ${visiblePlatform}: Store 记录为空`);
             continue;
         }
-        // 旧数据回填：升级后首次遇到无 fileCount 的条目，顺便记录完整性数据
-        if (entry.fileCount == null) {
-            try {
-                const integrity = await store.captureIntegrity(libName, commit, platform);
-                registry.updateStore(storeKey, integrity);
-                if (integrity.fileCount === 0) {
-                    corrupted.push(platform);
-                    warn(`${libName} (${commit.slice(0, 7)}) ${platform}: Store 目录为空`);
-                    continue;
-                }
-            }
-            catch {
-                corrupted.push(platform);
-                warn(`${libName} (${commit.slice(0, 7)}) ${platform}: Store 完整性回填失败`);
-                continue;
-            }
-            valid.push(platform);
+        if (entry.fileCount == null || !entry.contentHash) {
+            repairRequired.push(platform);
+            debug(`${libName} (${commit.slice(0, 7)}) ${visiblePlatform}: Store 缺少完整性记录，准备重新下载`);
             continue;
         }
         const result = await store.fullVerify(libName, commit, platform, {
@@ -2782,10 +3003,10 @@ export async function verifyExistingPlatforms(libName, commit, existingPlatforms
         }
         else {
             corrupted.push(platform);
-            warn(`${libName} (${commit.slice(0, 7)}) ${platform}: 完整性校验失败 - ${result.reason}`);
+            warn(`${libName} (${commit.slice(0, 7)}) ${visiblePlatform}: 完整性校验失败 - ${result.reason}`);
         }
     }
-    return { valid, corrupted };
+    return { valid, corrupted, repairRequired };
 }
 /**
  * 创建带完整性信息的 StoreEntry