tanmi-dock 0.10.0-beta → 1.0.4

package/dist/commands/link.js

@@ -7,13 +7,13 @@ import { Command } from 'commander';
 import { ensureInitialized } from '../core/guard.js';
 import * as config from '../core/config.js';
 import { setLogLevel } from '../utils/logger.js';
-import { parseProjectDependencies, getRelativeConfigPath, parseCodepacDep, extractActions, parseActionCommand, extractNestedDependencies, findAllCodepacConfigs, extractDependencies, resolveProjectRootPath, } from '../core/parser.js';
+import { parseProjectDependencies, getRelativeConfigPath, parseCodepacDep, extractActions, buildActionExecutionPlan, extractNestedDependencies, findAllCodepacConfigs, extractDependencies, resolveProjectRootPath, } from '../core/parser.js';
 import { getRegistry } from '../core/registry.js';
 import * as store from '../core/store.js';
 import * as linker from '../core/linker.js';
 import * as codepac from '../core/codepac.js';
 import { setProxyConfig } from '../core/codepac.js';
-import { getPlatformHelpText, GENERAL_PLATFORM, SHARED_PLATFORM, pathsEqual, isSparseOnlyCommon, KNOWN_PLATFORM_VALUES, getRequestedPlatformTargets, } from '../core/platform.js';
+import { getPlatformHelpText, GENERAL_PLATFORM, SHARED_PLATFORM, pathsEqual, isSparseOnlyCommon, KNOWN_PLATFORM_VALUES, getRequestedPlatformTargets, resolveSparseConfig, getBaseKeyForCodepac, } from '../core/platform.js';
 import { Transaction } from '../core/transaction.js';
 import { formatSize, checkDiskSpace } from '../utils/disk.js';
 import { getDirSize } from '../utils/fs-utils.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';
@@ -37,6 +38,7 @@ export function createLinkCommand() {
         .option('--no-download', '不自动下载缺失库')
         .option('--dry-run', '只显示将要执行的操作')
         .option('--config <configs...>', '指定可选配置文件 (如 codepac-dep-inner.json)')
+        .option('--skip-action, --skip_action, -sa <names...>', '按 action.name 跳过指定嵌套 action')
         .option('--no-submodules', '不检测 git submodule 依赖')
         .addHelpText('after', `${getPlatformHelpText()}
 
@@ -48,6 +50,7 @@ export function createLinkCommand() {
   td link --dry-run             预览操作，不实际执行
   td link -y                    跳过确认，自动执行
   td link --config codepac-dep-inner.json   使用指定的可选配置
+  td link --skip-action prepareNested       跳过指定 action.name
   td link --no-submodules       跳过 git submodule 检测`)
         .action(async (projectPath, options) => {
         await ensureInitialized();
@@ -73,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);
@@ -90,15 +187,28 @@ 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)) {
             resolvedExisting.push(platform);
         }
+        else {
+            const registry = getRegistry();
+            const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
+            if (registry.getStore(storeKey)) {
+                stalePlatforms.push(platform);
+            }
+        }
     }
-    return resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, resolvedExisting, vars);
+    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;
 }
 function getBlockedRequestedPlatforms(registry, dependency, requestedPlatforms, vars) {
     const { manualPlatforms, autoPlatforms } = resolveUnavailablePlatforms(registry, dependency);
@@ -109,7 +219,9 @@ function getBlockedRequestedPlatforms(registry, dependency, requestedPlatforms,
         const targets = getRequestedPlatformTargets(platform, dependency.sparse, vars);
         return targets.length === 1 && targets[0] === platform;
     });
-    return [...new Set([...manualBlocked, ...autoBlocked])];
+    const blocked = [...new Set([...manualBlocked, ...autoBlocked])];
+    debug(`[link-platforms] ${dependency.libName}@${dependency.commit.slice(0, 7)} 请求平台=${requestedPlatforms.join(', ') || '空'}, 手动跳过=${manualBlocked.join(', ') || '无'}, 自动跳过=${autoBlocked.join(', ') || '无'}, 最终跳过=${blocked.join(', ') || '无'}`);
+    return blocked;
 }
 function clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested) {
     if (satisfiedRequested.length === 0)
@@ -154,12 +266,80 @@ function upsertLibraryAvailability(dependency, updates) {
         lastAccess: new Date().toISOString(),
     });
 }
-export async function resolveLibraryGeneralState(dependency) {
+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);
+    const sparseConfig = resolveSparseConfig(dependency.sparse, vars);
+    const hasPlatformSparse = sparseConfig
+        ? Object.keys(sparseConfig).some((key) => key !== 'common')
+        : Boolean(dependency.sparse && !isSparseOnlyCommon(dependency.sparse));
+    const hasPlatformLibraryHistory = requestedPlatforms.length > 0
+        && library?.isGeneral === false
+        && library.platforms.some((platform) => platform !== GENERAL_PLATFORM);
+    if (requestedPlatforms.length > 0) {
+        const requestedState = await resolveRequestedStoreState(dependency, requestedPlatforms, vars, updateRegistry);
+        if (requestedState.actualExisting.length > 0) {
+            if (updateRegistry && library?.isGeneral === true) {
+                registry.updateLibrary(libKey, {
+                    platforms: requestedState.actualExisting,
+                    isGeneral: false,
+                    lastAccess: new Date().toISOString(),
+                });
+            }
+            return false;
+        }
+    }
+    if (requestedPlatforms.length > 0 && library?.isGeneral === true) {
+        if (await hasRequestedPlatformContent(dependency, requestedPlatforms, vars)) {
+            return false;
+        }
+    }
+    if (requestedPlatforms.length > 0 && hasPlatformSparse) {
+        if (updateRegistry && library?.isGeneral === true) {
+            registry.updateLibrary(libKey, {
+                isGeneral: false,
+                lastAccess: new Date().toISOString(),
+            });
+        }
+        return false;
+    }
+    if (hasPlatformLibraryHistory) {
+        return false;
+    }
     if (typeof library?.isGeneral === 'boolean') {
-        return library.isGeneral;
+        if (library.isGeneral) {
+            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 (updateRegistry && !actualGeneral) {
+                registry.updateLibrary(libKey, {
+                    isGeneral: false,
+                    lastAccess: new Date().toISOString(),
+                });
+            }
+            return actualGeneral;
+        }
+        const actualGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
+        if (updateRegistry && actualGeneral) {
+            registry.updateLibrary(libKey, {
+                platforms: [GENERAL_PLATFORM],
+                isGeneral: true,
+                lastAccess: new Date().toISOString(),
+            });
+        }
+        return actualGeneral;
     }
     return store.isGeneralLib(dependency.libName, dependency.commit);
 }
@@ -173,7 +353,7 @@ export function resolveUnavailablePlatforms(registry, dependency) {
         autoPlatforms,
     };
 }
-export async function collectProjectDependencyGraph(projectRoot) {
+export async function collectProjectDependencyGraph(projectRoot, codepacPlatforms = []) {
     const { normalizedPath, configPath } = await resolveProjectRootPath(projectRoot);
     if (!configPath) {
         throw new Error('只能在项目目录下使用');
@@ -182,11 +362,17 @@ export async function collectProjectDependencyGraph(projectRoot) {
     const seenDeps = new Set();
     const visitedConfigs = new Set();
     const queue = [
-        { configPath, source: 'direct' },
+        { configPath, targetDir: path.dirname(configPath), codepacPlatforms, source: 'direct' },
     ];
-    const submodules = await findSubmoduleConfigs(normalizedPath);
+    const submodules = await findSubmoduleConfigs(normalizedPath, '', 0, codepacPlatforms);
     for (const submodule of submodules) {
-        queue.push({ configPath: submodule.configPath, scope: submodule.relativePath, source: 'submodule' });
+        queue.push({
+            configPath: submodule.configPath,
+            targetDir: path.dirname(submodule.configPath),
+            codepacPlatforms,
+            scope: submodule.relativePath,
+            source: 'submodule',
+        });
     }
     while (queue.length > 0) {
         const current = queue.shift();
@@ -200,25 +386,32 @@ export async function collectProjectDependencyGraph(projectRoot) {
         catch {
             continue;
         }
-        for (const dependency of extractDependencies(parsedConfig)) {
+        const extractOptions = { platforms: current.codepacPlatforms, configPath: current.configPath };
+        for (const dependency of extractDependencies(parsedConfig, extractOptions)) {
             const key = `${dependency.libName}:${dependency.commit}:${current.scope ?? ''}`;
             if (!seenDeps.has(key)) {
                 seenDeps.add(key);
                 results.push({ ...dependency, scope: current.scope, source: current.source });
             }
         }
-        for (const action of extractActions(parsedConfig)) {
-            let parsedAction;
+        for (const action of extractActions(parsedConfig, extractOptions)) {
+            let plan;
             try {
-                parsedAction = parseActionCommand(action.command);
+                plan = buildActionExecutionPlan(action, {
+                    parentConfigPath: current.configPath,
+                    parentTargetDir: current.targetDir,
+                    inheritedCodepacPlatforms: current.codepacPlatforms,
+                });
             }
             catch {
                 continue;
             }
-            const nestedConfigPath = path.resolve(path.dirname(current.configPath), parsedAction.configDir, 'codepac-dep.json');
             let nested;
             try {
-                nested = await extractNestedDependencies(nestedConfigPath, parsedAction.libraries);
+                nested = await extractNestedDependencies(plan.nestedConfigPath, plan.libraries, {
+                    platforms: plan.effectiveCodepacPlatforms,
+                    configPath: plan.nestedConfigPath,
+                });
             }
             catch {
                 continue;
@@ -230,7 +423,15 @@ export async function collectProjectDependencyGraph(projectRoot) {
                     results.push({ ...dependency, scope: current.scope, source: 'nested' });
                 }
             }
-            queue.push({ configPath: nestedConfigPath, scope: current.scope, source: 'nested' });
+            if (!plan.parsed.disableAction) {
+                queue.push({
+                    configPath: plan.nestedConfigPath,
+                    targetDir: plan.nestedTargetDir,
+                    codepacPlatforms: plan.effectiveCodepacPlatforms,
+                    scope: current.scope,
+                    source: 'nested',
+                });
+            }
         }
     }
     return results;
@@ -276,6 +477,16 @@ async function selectSubmodules(configs, options, remembered) {
     }
     return selected.map(s => ({ ...s }));
 }
+function buildSubmoduleOptionalConfigState(submodules) {
+    const state = {};
+    for (const submodule of submodules) {
+        const names = submodule.selectedOptionalConfigs?.map((config) => config.name) ?? [];
+        if (names.length > 0) {
+            state[submodule.relativePath] = names;
+        }
+    }
+    return Object.keys(state).length > 0 ? state : undefined;
+}
 /**
  * 单个 scope（主项目或 submodule）的链接处理
  *
@@ -284,6 +495,7 @@ async function selectSubmodules(configs, options, remembered) {
 async function linkScope(params) {
     const { scopeName, configPath, platforms, scanExtraPlatforms, registry, tx, projectHash, projectRoot, storePath, download, dryRun, yes, concurrency, gitLightweightDownload, optionalConfigs, scope, } = params;
     let finalLinkPlatforms = [...params.finalLinkPlatforms];
+    const codepacPlatforms = [...new Set(platforms.map((platform) => getBaseKeyForCodepac(platform)))];
     // 记录 General 类型库
     const generalLibs = new Set();
     const downloadedLibs = [];
@@ -292,17 +504,32 @@ async function linkScope(params) {
     info(`分析 ${scopeName}: ${configPath}`);
     let dependencies;
     let configVars;
+    const selectedActions = [];
+    const cacheConfigPaths = [configPath];
     try {
-        const result = await parseProjectDependencies(path.dirname(path.dirname(configPath)));
+        const result = await parseProjectDependencies(path.dirname(path.dirname(configPath)), {
+            platforms: codepacPlatforms,
+        });
         dependencies = result.dependencies;
         configVars = result.vars;
+        const topLevelConfig = await parseCodepacDep(configPath);
+        selectedActions.push(...extractActions(topLevelConfig, { platforms: codepacPlatforms, configPath }));
         // 合并可选配置依赖
         if (optionalConfigs && optionalConfigs.length > 0) {
             for (const optionalConfig of optionalConfigs) {
                 try {
                     const optionalResult = await parseCodepacDep(optionalConfig.path);
-                    const optionalDeps = extractDependencies(optionalResult);
+                    const optionalDeps = extractDependencies(optionalResult, {
+                        platforms: codepacPlatforms,
+                        configPath: optionalConfig.path,
+                    });
                     dependencies = mergeDepLists(dependencies, optionalDeps);
+                    configVars = { ...configVars, ...optionalResult.vars };
+                    selectedActions.push(...extractActions(optionalResult, {
+                        platforms: codepacPlatforms,
+                        configPath: optionalConfig.path,
+                    }));
+                    cacheConfigPaths.push(optionalConfig.path);
                     info(`  + ${optionalConfig.name}: ${optionalDeps.length} 个依赖`);
                 }
                 catch (optErr) {
@@ -319,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,
     };
@@ -336,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);
-        }
-        if (spaceCheck.available === 0) {
-            warn('无法获取磁盘空间信息，继续执行');
+        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}`);
+        }
+        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）
@@ -457,17 +701,18 @@ 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: {
                 const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
                 const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
-                const isLinkedGeneral = await resolveLibraryGeneralState(dependency);
+                const isLinkedGeneral = await resolveLibraryGeneralState(dependency, requestedPlatforms, configVars);
                 if (!isLinkedGeneral) {
                     const supplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, {
                         vars: configVars,
                         useGitLightweightDownload: gitLightweightDownload,
+                        repairRequiredPlatforms,
                     });
                     await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
                     if (supplementResult.downloaded.length > 0) {
@@ -489,7 +734,7 @@ async function linkScope(params) {
                 const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
                 const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
                 const relinkCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                const isRelinkGeneral = await resolveLibraryGeneralState(dependency);
+                const isRelinkGeneral = await resolveLibraryGeneralState(dependency, requestedPlatforms, configVars);
                 if (isRelinkGeneral) {
                     tx.recordOp('unlink', localPath);
                     await linker.unlink(localPath);
@@ -504,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);
@@ -547,7 +793,7 @@ async function linkScope(params) {
                 const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
                 const replaceSize = await getDirSize(localPath);
                 const replaceCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                const isReplaceGeneral = await resolveLibraryGeneralState(dependency);
+                const isReplaceGeneral = await resolveLibraryGeneralState(dependency, requestedPlatforms, configVars);
                 if (isReplaceGeneral) {
                     const sharedPath = path.join(replaceCommitPath, '_shared');
                     tx.recordOp('replace', localPath, sharedPath);
@@ -561,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);
@@ -670,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) {
@@ -736,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({
@@ -754,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();
                     }
@@ -768,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 {
@@ -776,14 +1050,19 @@ async function linkScope(params) {
                 }
                 const { actualExisting: linkNewExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                 clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
-                const isLinkNewGeneral = await resolveLibraryGeneralState(dependency);
+                const isLinkNewGeneral = await resolveLibraryGeneralState(dependency, requestedPlatforms, configVars);
                 if (isLinkNewGeneral) {
                     const sharedPath = path.join(linkNewCommitPath, '_shared');
                     tx.recordOp('link', localPath, sharedPath);
                     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');
@@ -833,21 +1112,47 @@ 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);
                     const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
                     const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
+                    if (requestedPlatforms.length === 0) {
+                        pLog.warn(`${dependency.libName} 请求平台 [${platforms.join(', ')}] 均已按规则跳过，没有可链接产物`);
+                        if (await linker.cleanupEmptyLocalDirectory(localPath)) {
+                            pLog.warn(`${dependency.libName} 已清理历史遗留的空本地目录`);
+                        }
+                        return {
+                            success: false,
+                            name: dependency.libName,
+                            skipped: true,
+                            skippedPlatforms: blockedPlatforms,
+                            unsupported: true,
+                        };
+                    }
                     const { actualExisting: existing, missingRequested: missing, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                     clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
                     if (missing.length === 0) {
+                        if (existing.length === 0) {
+                            pLog.warn(`${dependency.libName} 请求平台 [${requestedPlatforms.join(', ')}] 在 Store 中没有可链接产物，已拒绝创建空目录`);
+                            if (await linker.cleanupEmptyLocalDirectory(localPath)) {
+                                pLog.warn(`${dependency.libName} 已清理历史遗留的空本地目录`);
+                            }
+                            return {
+                                success: false,
+                                name: dependency.libName,
+                                skipped: true,
+                                skippedPlatforms: requestedPlatforms,
+                            };
+                        }
                         pLog.info(`${dependency.libName} 所有平台已存在，直接链接...`);
                         tx.recordOp('link', localPath, storeCommitPath);
                         await linker.linkLib(localPath, storeCommitPath, existing);
@@ -864,9 +1169,22 @@ async function linkScope(params) {
                         if (knownUnavailable.length > 0) {
                             pLog.warn(`${dependency.libName} 平台 [${knownUnavailable.join(', ')}] 已按规则跳过`);
                         }
+                        if (await linker.cleanupEmptyLocalDirectory(localPath)) {
+                            pLog.warn(`${dependency.libName} 已清理历史遗留的空本地目录`);
+                        }
                         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,
@@ -904,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;
@@ -924,6 +1250,10 @@ async function linkScope(params) {
                         }
                         const linkPlatforms = [...existing, ...filteredDownloaded];
                         if (linkPlatforms.length === 0) {
+                            pLog.warn(`${dependency.libName} 下载后没有生成请求平台 [${requestedPlatforms.join(', ')}] 的可链接产物，已拒绝创建空目录`);
+                            if (await linker.cleanupEmptyLocalDirectory(localPath)) {
+                                pLog.warn(`${dependency.libName} 已清理历史遗留的空本地目录`);
+                            }
                             return {
                                 success: false,
                                 name: dependency.libName,
@@ -935,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 {
@@ -943,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);
@@ -955,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) {
@@ -978,26 +1334,32 @@ async function linkScope(params) {
         }
     }
     // 9. 处理嵌套依赖 (actions)
-    const topLevelConfig = await parseCodepacDep(configPath);
-    const actions = extractActions(topLevelConfig);
+    const actions = selectedActions;
     const nestedLinkedDeps = [];
     if (actions.length > 0) {
         blank();
         separator();
         info(`发现 ${actions.length} 个嵌套依赖配置`);
         const nestedContext = {
-            depth: 0, processedConfigs: new Set([configPath]), platforms, vars: configVars,
+            depth: 0,
+            processedConfigs: new Set([buildActionVisitKey(configPath, path.dirname(configPath))]),
+            platforms,
+            codepacPlatforms,
+            vars: configVars,
         };
         const thirdPartyDir = path.dirname(configPath);
         for (const action of actions) {
-            await processAction(action, nestedContext, thirdPartyDir, {
+            await processAction(action, nestedContext, configPath, thirdPartyDir, {
                 tx, registry, projectHash, projectRoot, dryRun, download, yes,
-                gitLightweightDownload, generalLibs, downloadedLibs, nestedLinkedDeps,
+                gitLightweightDownload, skipActions: new Set(params.skipActions ?? []),
+                generalLibs, downloadedLibs, nestedLinkedDeps,
             });
         }
     }
     // 10. 同步 cache 文件
-    await syncCacheFile(configPath);
+    for (const cacheConfigPath of cacheConfigPaths) {
+        await syncCacheFile(cacheConfigPath);
+    }
     // 11. 构建返回结果
     const linkedDeps = [];
     for (const item of classified) {
@@ -1025,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)
@@ -1033,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;
     // 确定平台列表
@@ -1070,9 +1435,10 @@ export async function linkProject(projectPath, options) {
         error(`路径不存在: ${absolutePath}`);
         process.exit(EXIT_CODES.NOINPUT);
     }
-    // 发现可选配置文件
-    const thirdpartyDir = path.join(normalizedPath, '3rdparty');
-    const configDiscovery = await findAllCodepacConfigs(thirdpartyDir);
+    // 发现可选配置文件，扫描位置跟随实际主配置所在目录。
+    const configDiscovery = discoveredConfigPath
+        ? await findAllCodepacConfigs(path.dirname(discoveredConfigPath))
+        : null;
     let selectedOptionalConfigs = [];
     if (configDiscovery && configDiscovery.optionalConfigs.length > 0) {
         if (options.config && options.config.length > 0) {
@@ -1119,14 +1485,21 @@ export async function linkProject(projectPath, options) {
     // === 阶段 2: Submodule 检测 ===
     let selectedSubmodules = [];
     if (options.submodules !== false) {
-        const submoduleConfigs = await findSubmoduleConfigs(normalizedPath);
+        const codepacPlatforms = [...new Set(platforms.map((platform) => getBaseKeyForCodepac(platform)))];
+        const submoduleConfigs = await findSubmoduleConfigs(normalizedPath, '', 0, codepacPlatforms);
         if (submoduleConfigs.length > 0) {
             selectedSubmodules = await selectSubmodules(submoduleConfigs, options, existingProject?.submodules);
             // 为选中的 submodule 处理可选配置
             for (const sub of selectedSubmodules) {
-                if (sub.optionalConfigs.length > 0 && !options.yes && process.stdout.isTTY) {
+                if (sub.optionalConfigs.length === 0)
+                    continue;
+                const rememberedConfigs = existingProject?.submoduleOptionalConfigs?.[sub.relativePath] ?? [];
+                if (options.yes) {
+                    sub.selectedOptionalConfigs = sub.optionalConfigs.filter((configInfo) => rememberedConfigs.includes(configInfo.name));
+                }
+                else if (process.stdout.isTTY) {
                     info(`${sub.name} 发现可选配置:`);
-                    const selected = await selectOptionalConfigs(sub.optionalConfigs, { isTTY: true, specifiedConfigs: [] });
+                    const selected = await selectOptionalConfigs(sub.optionalConfigs, { isTTY: true, specifiedConfigs: rememberedConfigs });
                     if (selected !== PROMPT_CANCELLED) {
                         sub.selectedOptionalConfigs = selected;
                     }
@@ -1158,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 {
         // 主项目
@@ -1194,6 +1580,7 @@ export async function linkProject(projectPath, options) {
             concurrency,
             gitLightweightDownload,
             optionalConfigs: selectedOptionalConfigs,
+            skipActions: options.skipAction ?? [],
         });
         const finalLinkPlatforms = mainResult.finalLinkPlatforms;
         // 如果 dry-run 模式，linkScope 内已显示信息
@@ -1219,6 +1606,7 @@ export async function linkProject(projectPath, options) {
                     gitLightweightDownload,
                     optionalConfigs: sub.selectedOptionalConfigs,
                     scope: sub.relativePath,
+                    skipActions: options.skipAction ?? [],
                 });
             }
             return;
@@ -1245,6 +1633,7 @@ export async function linkProject(projectPath, options) {
                 gitLightweightDownload,
                 optionalConfigs: sub.selectedOptionalConfigs,
                 scope: sub.relativePath,
+                skipActions: options.skipAction ?? [],
             });
             subResults.push(subResult);
         }
@@ -1269,6 +1658,7 @@ export async function linkProject(projectPath, options) {
                 ? selectedOptionalConfigs.map(c => c.name) : undefined,
             submodules: selectedSubmodules.length > 0
                 ? selectedSubmodules.map(s => s.relativePath) : undefined,
+            submoduleOptionalConfigs: buildSubmoduleOptionalConfigState(selectedSubmodules),
         });
         // 更新 Store 引用关系
         const newStoreKeys = allLinkedDeps.map((d) => registry.getStoreKey(d.libName, d.commit, d.platform));
@@ -1320,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 {
@@ -1383,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);
     }
@@ -1419,10 +1803,7 @@ function hintStoreRepairCommand(err) {
 async function registerSharedStore(libName, commit, branch = '', url = '') {
     const registry = getRegistry();
     const storeKey = registry.getStoreKey(libName, commit, SHARED_PLATFORM);
-    // 如果已存在，不重复注册
-    if (registry.getStore(storeKey)) {
-        return true;
-    }
+    const existingEntry = registry.getStore(storeKey);
     // 检查 _shared 目录是否存在
     const storePath = await config.getStorePath();
     if (!storePath)
@@ -1440,17 +1821,27 @@ async function registerSharedStore(libName, commit, branch = '', url = '') {
     }
     // 计算 _shared 完整性信息并注册
     const integrity = await store.captureIntegrity(libName, commit, SHARED_PLATFORM);
-    registry.addStore({
-        libName,
-        commit,
-        platform: SHARED_PLATFORM,
-        branch,
-        url,
-        ...integrity,
-        usedBy: [], // _shared 不追踪引用，生命周期跟随平台
-        createdAt: new Date().toISOString(),
-        lastAccess: new Date().toISOString(),
-    });
+    if (existingEntry) {
+        registry.updateStore(storeKey, {
+            branch: existingEntry.branch || branch,
+            url: existingEntry.url || url,
+            ...integrity,
+            lastAccess: new Date().toISOString(),
+        });
+    }
+    else {
+        registry.addStore({
+            libName,
+            commit,
+            platform: SHARED_PLATFORM,
+            branch,
+            url,
+            ...integrity,
+            usedBy: [], // _shared 不追踪引用，生命周期跟随平台
+            createdAt: new Date().toISOString(),
+            lastAccess: new Date().toISOString(),
+        });
+    }
     debug(`注册 _shared: ${libName}:${commit.slice(0, 8)} (${formatSize(integrity.size)})`);
     return true;
 }
@@ -1472,9 +1863,13 @@ 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);
+    const currentEntry = registry.getStore(storeKey);
+    if (currentEntry && ((!currentEntry.branch && branch) || (!currentEntry.url && url))) {
+        registry.updateStore(storeKey, {
+            branch: currentEntry.branch || branch,
+            url: currentEntry.url || url,
+            lastAccess: new Date().toISOString(),
+        });
     }
     if (projectHash) {
         registry.addStoreReference(storeKey, projectHash);
@@ -1687,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();
@@ -1701,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);
+        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 情况的本地路径状态检查
@@ -1796,6 +2200,7 @@ async function classifyDependencies(dependencies, projectPath, configPath, platf
             status,
             localPath,
             storePath: storeLibPath,
+            repairRequiredPlatforms,
         });
     }
     return result;
@@ -1804,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;
@@ -1817,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) {
@@ -1826,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,
@@ -1848,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) {
@@ -1887,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 {
@@ -1896,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;
 }
@@ -1953,19 +2380,20 @@ function getStatusKey(status) {
 async function syncCacheFile(configPath) {
     const configDir = path.dirname(configPath);
     const cacheDir = path.join(configDir, '.cache');
-    const cachePath = path.join(cacheDir, 'codepac-dep.json');
+    const configFileName = path.basename(configPath);
+    const cachePath = path.join(cacheDir, configFileName);
     try {
         // 确保 .cache 目录存在
         await fs.mkdir(cacheDir, { recursive: true });
         // 复制配置文件到 cache
         await fs.copyFile(configPath, cachePath);
         if (process.env.VERBOSE) {
-            info(`已同步 cache: ${path.basename(configPath)}`);
+            info(`已同步 cache: ${configFileName} -> ${path.relative(configDir, cachePath)}`);
         }
     }
     catch (err) {
         // cache 同步失败不应阻塞主流程，仅警告
-        warn(`cache 同步失败: ${err.message}`);
+        warn(`cache 同步失败: ${configFileName} -> ${path.relative(configDir, cachePath)}: ${err.message}`);
     }
 }
 /**
@@ -1975,78 +2403,98 @@ async function syncCacheFile(configPath) {
  * @param thirdPartyDir 3rdparty 目录路径
  * @param options 处理选项
  */
-async function processAction(action, context, thirdPartyDir, options) {
+async function processAction(action, context, parentConfigPath, parentTargetDir, options) {
     const indent = '  '.repeat(context.depth);
-    // 1. 解析 action 命令
-    let parsed;
+    if (action.name && options.skipActions.has(action.name)) {
+        info(`${indent}跳过嵌套 action: name=${action.name}, 原因=skip-action`);
+        debug(`${indent}CodePac action 跳过: name=${action.name}, command=${action.command}, skipActions=${Array.from(options.skipActions).join(',')}`);
+        return;
+    }
+    // 1. 解析 action 命令和执行计划
+    let plan;
     try {
-        parsed = parseActionCommand(action.command);
+        plan = buildActionExecutionPlan(action, {
+            parentConfigPath,
+            parentTargetDir,
+            inheritedCodepacPlatforms: context.codepacPlatforms ?? context.platforms,
+        });
     }
     catch (err) {
-        warn(`${indent}无法解析 action: ${err.message}`);
+        warn(`${indent}跳过嵌套 action: name=${action.name ?? '(未命名)'}, 原因=无法解析命令, message=${err.message}`);
+        debug(`${indent}CodePac action 解析失败: command=${action.command}`);
         return;
     }
-    const libsDisplay = parsed.libraries.length > 0 ? parsed.libraries.join(', ') : '全部依赖';
-    info(`${indent}处理嵌套依赖: ${parsed.configDir} → [${libsDisplay}]`);
-    // 2. 构建嵌套配置路径
-    const nestedConfigPath = path.join(thirdPartyDir, parsed.configDir, 'codepac-dep.json');
-    // 3. 循环检测
-    if (context.processedConfigs.has(nestedConfigPath)) {
-        warn(`${indent}  检测到循环依赖，跳过: ${parsed.configDir}`);
+    const libsDisplay = plan.libraries.length > 0 ? plan.libraries.join(', ') : '全部依赖';
+    info(`${indent}处理嵌套 action: name=${plan.actionName ?? '(未命名)'}, config=${plan.nestedConfigPath}, target=${plan.nestedTargetDir}, libs=[${libsDisplay}]`);
+    debug(`${indent}CodePac action 执行计划: command=${plan.command}, parentConfig=${parentConfigPath}, parentTarget=${parentTargetDir}, parsedConfigDir=${plan.configDir}, parsedTargetDir=${plan.targetDir}, resolvedConfig=${plan.nestedConfigPath}, resolvedTarget=${plan.nestedTargetDir}, inheritedPlatforms=${formatActionPlatforms(plan.inheritedPlatforms)}, effectivePlatforms=${formatActionPlatforms(plan.effectiveCodepacPlatforms)}, explicitPlatform=${plan.parsed.hasExplicitPlatform}, fullgit=${plan.parsed.hasExplicitFullGit}, unshallow=${plan.parsed.hasExplicitUnshallow}, disable_sparse=${plan.parsed.hasExplicitDisableSparse}`);
+    // 2. 循环检测
+    const visitKey = buildActionVisitKey(plan.nestedConfigPath, plan.nestedTargetDir);
+    if (context.processedConfigs.has(visitKey)) {
+        warn(`${indent}  跳过嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=循环配置, config=${plan.nestedConfigPath}, target=${plan.nestedTargetDir}`);
         return;
     }
-    context.processedConfigs.add(nestedConfigPath);
-    // 4. 检查配置文件是否存在
+    context.processedConfigs.add(visitKey);
+    // 3. 检查配置文件是否存在
     try {
-        await fs.access(nestedConfigPath);
+        await fs.access(plan.nestedConfigPath);
     }
     catch {
-        warn(`${indent}  嵌套配置文件不存在: ${nestedConfigPath}`);
-        hint(`${indent}  请确保 ${parsed.configDir} 库已被下载`);
+        warn(`${indent}  跳过嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=配置不存在, config=${plan.nestedConfigPath}`);
+        hint(`${indent}  请确保 ${plan.configDir} 库已被下载`);
         return;
     }
-    // 5. 提取指定库的依赖
+    // 4. 提取指定库的依赖
     let nestedResult;
     try {
-        nestedResult = await extractNestedDependencies(nestedConfigPath, parsed.libraries);
+        nestedResult = await extractNestedDependencies(plan.nestedConfigPath, plan.libraries, {
+            platforms: plan.effectiveCodepacPlatforms,
+            configPath: plan.nestedConfigPath,
+        });
     }
     catch (err) {
-        warn(`${indent}  解析嵌套配置失败: ${err.message}`);
+        warn(`${indent}  跳过嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=解析配置失败, message=${err.message}`);
         return;
     }
     const { dependencies, vars, nestedActions } = nestedResult;
     if (dependencies.length === 0) {
-        warn(`${indent}  在 ${parsed.configDir} 中未找到指定的库`);
+        warn(`${indent}  跳过嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=未找到依赖, libs=[${libsDisplay}], config=${plan.nestedConfigPath}`);
         return;
     }
-    info(`${indent}  找到 ${dependencies.length} 个嵌套依赖`);
-    // 6. 合并变量
+    info(`${indent}  嵌套 action 命中 ${dependencies.length} 个依赖，继承平台: ${formatActionPlatforms(plan.inheritedPlatforms)}, 生效平台: ${formatActionPlatforms(plan.effectiveCodepacPlatforms)}`);
+    // 5. 合并变量
     const mergedVars = { ...context.vars, ...vars };
-    // 7. 处理这些依赖（targetDir 指定嵌套依赖的目标目录）
+    // 6. 处理这些依赖（targetDir 指定嵌套依赖的目标目录）
     await linkNestedDependencies(dependencies, {
-        thirdPartyDir,
-        targetDir: parsed.targetDir,
-        nestedConfigPath,
-        context: { ...context, vars: mergedVars },
+        targetDir: plan.nestedTargetDir,
+        nestedConfigPath: plan.nestedConfigPath,
+        context: { ...context, codepacPlatforms: plan.effectiveCodepacPlatforms, vars: mergedVars },
         options,
         indent,
     });
     // 同步嵌套配置文件的 cache（兼容 checkValid.js 检测）
-    await syncCacheFile(nestedConfigPath);
-    // 8. 递归处理嵌套 actions（如果没有 disable_action）
-    // 注意：递归时 thirdPartyDir 应该更新为当前嵌套依赖的目标目录
-    if (!parsed.disableAction && nestedActions.length > 0) {
+    await syncCacheFile(plan.nestedConfigPath);
+    // 7. 递归处理嵌套 actions（如果没有 disable_action）
+    if (!plan.parsed.disableAction && nestedActions.length > 0) {
         const nestedContext = {
             depth: context.depth + 1,
             processedConfigs: context.processedConfigs,
             platforms: context.platforms,
+            codepacPlatforms: plan.effectiveCodepacPlatforms,
             vars: mergedVars,
         };
-        const nestedThirdPartyDir = path.join(thirdPartyDir, parsed.targetDir);
         for (const nestedAction of nestedActions) {
-            await processAction(nestedAction, nestedContext, nestedThirdPartyDir, options);
+            await processAction(nestedAction, nestedContext, plan.nestedConfigPath, plan.nestedTargetDir, options);
         }
     }
+    else if (plan.parsed.disableAction && nestedActions.length > 0) {
+        info(`${indent}  跳过后续嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=disable_action`);
+    }
+}
+function formatActionPlatforms(platforms) {
+    return platforms && platforms.length > 0 ? platforms.join(',') : 'all';
+}
+function buildActionVisitKey(configPath, targetDir) {
+    return `${configPath}::${targetDir}`;
 }
 /**
  * 统一的本地目录验证+吸收流程
@@ -2104,9 +2552,7 @@ async function resolveLocalAndAbsorb(localPath, libName, commit, options) {
  * 链接嵌套依赖
  */
 async function linkNestedDependencies(dependencies, params) {
-    const { thirdPartyDir, targetDir, context, options, indent } = params;
-    // 计算嵌套依赖的实际目标目录
-    const nestedTargetDir = path.join(thirdPartyDir, targetDir);
+    const { targetDir: nestedTargetDir, context, options, indent } = params;
     const { tx, registry, projectHash, projectRoot, dryRun, download, generalLibs, downloadedLibs, nestedLinkedDeps } = options;
     const { platforms, vars } = context;
     for (const dep of dependencies) {
@@ -2130,7 +2576,8 @@ async function linkNestedDependencies(dependencies, params) {
         const availablePlatforms = platforms.filter(p => !unavailablePlatforms.includes(p));
         const knownUnavailable = platforms.filter(p => unavailablePlatforms.includes(p));
         let storeHas = false;
-        const existingPlatforms = [];
+        let existingPlatforms = [];
+        let repairRequiredPlatforms = [];
         const initialStoreState = await resolveRequestedStoreState(dep, availablePlatforms, vars);
         existingPlatforms.push(...initialStoreState.actualExisting);
         if (initialStoreState.satisfiedRequested.length > 0) {
@@ -2139,18 +2586,31 @@ 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);
-            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(() => { });
-                }
-                storeHas = verifiedPlatforms.length > 0;
+            const { valid: verifiedPlatforms, corrupted, repairRequired } = await verifyExistingPlatforms(dep.libName, dep.commit, existingPlatforms);
+            existingPlatforms = verifiedPlatforms;
+            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;
             }
         }
-        let isGeneral = await resolveLibraryGeneralState(dep);
+        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;
+        }
+        let isGeneral = await resolveLibraryGeneralState(dep, availablePlatforms, vars);
         // 如果所有平台都已知不可用，跳过
         if (availablePlatforms.length === 0 && knownUnavailable.length > 0 && !isGeneral) {
             warn(`${indent}  ${dep.libName} - 平台 [${knownUnavailable.join(', ')}] 已按规则跳过`);
@@ -2171,10 +2631,21 @@ async function linkNestedDependencies(dependencies, params) {
                 if (resolveResult.isGeneral) {
                     isGeneral = true;
                 }
+                else if (resolveResult.absorbResult) {
+                    const absorbedPlatforms = resolveResult.absorbResult.platforms;
+                    const absorbedPlatformSet = new Set(absorbedPlatforms);
+                    const linkableAbsorbedPlatforms = [...new Set(availablePlatforms.flatMap((platform) => getRequestedPlatformTargets(platform, dep.sparse, vars)
+                            .filter((target) => absorbedPlatformSet.has(target))))];
+                    existingPlatforms = [...new Set([
+                            ...existingPlatforms,
+                            ...linkableAbsorbedPlatforms,
+                        ])];
+                    debug(`${indent}  ${dep.libName} - 本地吸收后平台回填: requested=${availablePlatforms.join(', ') || '无'}, absorbed=${absorbedPlatforms.join(', ') || '无'}, linkable=${existingPlatforms.join(', ') || '无'}`);
+                }
                 if (resolveResult.absorbResult?.nestedLibraries.length) {
                     await registerNestedLibraries(resolveResult.absorbResult.nestedLibraries, projectHash);
                 }
-                storeHas = true;
+                storeHas = isGeneral || existingPlatforms.length > 0;
                 // 吸收为 General 后，检查是否实际需要平台内容
                 // 本地可能只有部分文件（如只有 _shared 内容），被误分类为 General
                 if (resolveResult.isGeneral && download) {
@@ -2229,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);
@@ -2300,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);
@@ -2326,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;
@@ -2384,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) {
                     // 平台库处理
@@ -2413,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
@@ -2433,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 {
@@ -2464,53 +2960,53 @@ 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);
-        // 没有 StoreEntry，跳过校验视为合法
+        const visiblePlatform = platform === GENERAL_PLATFORM ? '_shared' : platform;
         if (!entry) {
-            valid.push(platform);
+            repairRequired.push(platform);
+            debug(`${libName} (${commit.slice(0, 7)}) ${visiblePlatform}: Store 缺少 Registry 记录，准备重新下载`);
             continue;
         }
-        // 旧数据回填：升级后首次遇到无 fileCount 的条目，顺便记录完整性数据
-        if (entry.fileCount == null) {
-            try {
-                const integrity = await store.captureIntegrity(libName, commit, platform);
-                registry.updateStore(storeKey, integrity);
-            }
-            catch {
-                // 回填失败不影响正常流程
-            }
-            valid.push(platform);
+        if (entry.fileCount === 0) {
+            corrupted.push(platform);
+            warn(`${libName} (${commit.slice(0, 7)}) ${visiblePlatform}: Store 记录为空`);
+            continue;
+        }
+        if (entry.fileCount == null || !entry.contentHash) {
+            repairRequired.push(platform);
+            debug(`${libName} (${commit.slice(0, 7)}) ${visiblePlatform}: Store 缺少完整性记录，准备重新下载`);
             continue;
         }
-        const result = await store.quickVerify(libName, commit, platform, {
+        const result = await store.fullVerify(libName, commit, platform, {
             size: entry.size,
             fileCount: entry.fileCount,
+            contentHash: entry.contentHash,
         });
         if (result.valid) {
             valid.push(platform);
         }
         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