tanmi-dock 1.0.5 → 1.0.6-beta2

package/dist/commands/link.js

@@ -3,7 +3,6 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
-import crypto from 'crypto';
 import { Command } from 'commander';
 import { ensureInitialized } from '../core/guard.js';
 import * as config from '../core/config.js';
@@ -14,10 +13,12 @@ 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, resolveSparseConfig, getBaseKeyForCodepac, } from '../core/platform.js';
+import { getPlatformHelpText, GENERAL_PLATFORM, SHARED_PLATFORM, pathsEqual, isSparseOnlyCommon, KNOWN_PLATFORM_VALUES, getRequestedPlatformTargets, resolveSparseConfig, getBaseKeyForCodepac, getRegistryPath, } from '../core/platform.js';
 import { Transaction } from '../core/transaction.js';
+import { syncCodepacCache } from '../core/codepac-cache.js';
+import { StoreImportService } from '../core/store-import.js';
 import { formatSize, checkDiskSpace } from '../utils/disk.js';
-import { getDirSize } from '../utils/fs-utils.js';
+import { getDirSize, isPathMissingError } from '../utils/fs-utils.js';
 import { ProgressTracker, DownloadMonitor, MultiBarManager } from '../utils/progress.js';
 import { success, warn, error, info, hint, blank, separator, debug } from '../utils/logger.js';
 import { verifyLocalCommit, findSubmoduleConfigs } from '../utils/git.js';
@@ -65,6 +66,181 @@ export function createLinkCommand() {
         }
     });
 }
+/** 下载产物完成导入后仅清理临时目录；清理失败不会撤销已经验证并登记的 Store。 */
+export async function cleanupDownloadTempDir(tempDir, context) {
+    debug(`[link-download] 临时目录清理开始: stage=${context.stage}, lib=${context.libName}, commit=${context.commit}, temp=${tempDir}`);
+    try {
+        await fs.rm(tempDir, { recursive: true, force: true });
+        debug(`[link-download] 临时目录清理完成: stage=${context.stage}, lib=${context.libName}, commit=${context.commit}, temp=${tempDir}, output=removed`);
+    }
+    catch (err) {
+        warn(`[link-download] 临时目录清理失败，Store 缓存保持有效: stage=${context.stage}, lib=${context.libName}, commit=${context.commit}, temp=${tempDir}, message=${err.message}`);
+    }
+}
+function dependencyIdentityKey(dependency, localPath) {
+    return JSON.stringify([dependency.libName, dependency.commit, path.resolve(localPath)]);
+}
+function implicitReferenceOwner(dependency, projectRoot, localPath, scope) {
+    return {
+        libName: dependency.libName,
+        commit: dependency.commit,
+        linkedPath: path.relative(projectRoot, localPath),
+        scope,
+    };
+}
+function implicitReferenceOwnerKey(owner) {
+    return JSON.stringify([
+        owner.libName,
+        owner.commit,
+        owner.linkedPath,
+        owner.scope ?? '',
+    ]);
+}
+function serializeImplicitStoreReferences(references) {
+    return [...references.values()].map(({ owner, storeKeys }) => ({
+        owner,
+        storeKeys: [...storeKeys],
+    }));
+}
+function addImplicitStoreReference(references, owner, storeKey) {
+    const ownerKey = implicitReferenceOwnerKey(owner);
+    let entry = references.get(ownerKey);
+    if (!entry) {
+        entry = { owner, storeKeys: new Set() };
+        references.set(ownerKey, entry);
+    }
+    entry.storeKeys.add(storeKey);
+}
+function errorCauseHasCode(errorValue, codes) {
+    let current = errorValue;
+    while (current instanceof Error) {
+        const code = current.code;
+        if (code && codes.has(code))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+async function retainExistingLinkedDependencies(project, currentDependencies, projectRoot, storePath) {
+    if (!project)
+        return [];
+    const currentOwners = new Set(currentDependencies.map((dependency) => implicitReferenceOwnerKey({
+        libName: dependency.libName,
+        commit: dependency.commit,
+        linkedPath: dependency.linkedPath,
+        scope: dependency.scope,
+    })));
+    const groups = new Map();
+    for (const dependency of project.dependencies) {
+        const ownerKey = implicitReferenceOwnerKey({
+            libName: dependency.libName,
+            commit: dependency.commit,
+            linkedPath: dependency.linkedPath,
+            scope: dependency.scope,
+        });
+        if (currentOwners.has(ownerKey))
+            continue;
+        const group = groups.get(ownerKey) ?? [];
+        group.push(dependency);
+        groups.set(ownerKey, group);
+    }
+    const retained = [];
+    for (const dependencies of groups.values()) {
+        const template = dependencies[0];
+        const localPath = path.resolve(projectRoot, template.linkedPath);
+        const storeCommitPath = path.join(storePath, template.libName, template.commit);
+        const isGeneral = dependencies.some((dependency) => dependency.platform === GENERAL_PLATFORM) &&
+            dependencies.every((dependency) => dependency.platform === GENERAL_PLATFORM);
+        try {
+            await recordLinkedDependency(retained, template, localPath, storeCommitPath, projectRoot, isGeneral, template.scope);
+            debug(`[link-registry] 保留现有真实链接: lib=${template.libName}, commit=${template.commit}, ` +
+                `local=${localPath}, source=previous-project`);
+        }
+        catch (err) {
+            if (errorCauseHasCode(err, new Set(['EACCES', 'EPERM', 'EIO'])))
+                throw err;
+            debug(`[link-registry] 现有依赖不再指向当前 Store，移除登记: lib=${template.libName}, ` +
+                `commit=${template.commit}, local=${localPath}, detail=${err.message}`);
+        }
+    }
+    return retained;
+}
+function mergeProjectImplicitStoreReferences(project, projectHash, activeDependencies, discovered, registry) {
+    const activeOwners = new Set(activeDependencies.map((dependency) => implicitReferenceOwnerKey({
+        libName: dependency.libName,
+        commit: dependency.commit,
+        linkedPath: dependency.linkedPath,
+        scope: dependency.scope,
+    })));
+    const merged = new Map();
+    const legacyStoreKeys = new Set();
+    const knownPreviousImplicitKeys = new Set((project?.implicitStoreReferences ?? []).flatMap((reference) => reference.storeKeys));
+    const previousDependencyKeys = new Set((project?.dependencies ?? []).map((dependency) => registry.getStoreKey(dependency.libName, dependency.commit, dependency.platform)));
+    if (project) {
+        for (const storeKey of registry.getProjectStoreKeys(projectHash)) {
+            if (!previousDependencyKeys.has(storeKey) && !knownPreviousImplicitKeys.has(storeKey)) {
+                legacyStoreKeys.add(storeKey);
+            }
+        }
+    }
+    for (const reference of project?.implicitStoreReferences ?? []) {
+        if (!reference.owner) {
+            for (const storeKey of reference.storeKeys)
+                legacyStoreKeys.add(storeKey);
+            continue;
+        }
+        if (!activeOwners.has(implicitReferenceOwnerKey(reference.owner)))
+            continue;
+        for (const storeKey of reference.storeKeys) {
+            if (registry.getStore(storeKey))
+                addImplicitStoreReference(merged, reference.owner, storeKey);
+        }
+    }
+    for (const reference of discovered) {
+        if (!reference.owner || !activeOwners.has(implicitReferenceOwnerKey(reference.owner)))
+            continue;
+        for (const storeKey of reference.storeKeys) {
+            if (registry.getStore(storeKey))
+                addImplicitStoreReference(merged, reference.owner, storeKey);
+        }
+    }
+    const result = serializeImplicitStoreReferences(merged);
+    const validLegacyKeys = [...legacyStoreKeys].filter((storeKey) => registry.getStore(storeKey));
+    if (validLegacyKeys.length > 0)
+        result.push({ storeKeys: validLegacyKeys });
+    debug(`[link-registry] 隐式引用合并完成: project=${projectHash}, activeOwners=${activeOwners.size}, ` +
+        `discovered=${discovered.length}, previous=${project?.implicitStoreReferences?.length ?? 0}, ` +
+        `legacy=${validLegacyKeys.length}, groups=${result.length}`);
+    return result;
+}
+function buildDependencyRefs(dependency, platforms) {
+    return [...new Set(platforms)].map((platform) => ({ ...dependency, platform }));
+}
+function deduplicateDependencyRefs(dependencies) {
+    const seen = new Set();
+    return dependencies.filter((dependency) => {
+        const key = JSON.stringify([
+            dependency.libName,
+            dependency.commit,
+            dependency.platform,
+            dependency.linkedPath,
+            dependency.scope ?? '',
+        ]);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** 并行下载批次统一管理进度组件生命周期，任务创建或汇总失败时同样恢复终端状态。 */
+export async function runParallelDownloadBatch(createTasks, manager) {
+    try {
+        return await Promise.all(createTasks());
+    }
+    finally {
+        manager?.stop();
+    }
+}
 function resolveRequestedPlatformsByActual(requestedPlatforms, sparse, actualPlatforms, vars) {
     const actualExisting = [...new Set(actualPlatforms)];
     const actualPlatformSet = new Set(actualExisting);
@@ -130,8 +306,12 @@ async function prepareSharedStoreRepair(dependency, requestedPlatforms, repairRe
     try {
         await fs.access(sharedPath);
     }
-    catch {
-        return [];
+    catch (err) {
+        if (isPathMissingError(err))
+            return [];
+        error(`[link-store] shared 目录访问失败: lib=${dependency.libName}, commit=${dependency.commit}, ` +
+            `path=${sharedPath}, code=${err.code ?? 'unknown'}, message=${err.message}`);
+        throw err;
     }
     const result = await verifyExistingPlatforms(dependency.libName, dependency.commit, [SHARED_PLATFORM]);
     if (result.valid.length > 0 && result.corrupted.length === 0 && result.repairRequired.length === 0) {
@@ -167,8 +347,12 @@ async function hasRequestedPlatformContent(dependency, requestedPlatforms, vars)
             }
         }
     }
-    catch {
-        // Store 目录不存在时继续使用历史记录或后续 General 检测
+    catch (err) {
+        if (!isPathMissingError(err)) {
+            error(`[link-store] 请求平台目录读取失败: lib=${dependency.libName}, commit=${dependency.commit}, ` +
+                `path=${commitPath}, code=${err.code ?? 'unknown'}, message=${err.message}`);
+            throw err;
+        }
     }
     return false;
 }
@@ -489,18 +673,29 @@ function buildSubmoduleOptionalConfigState(submodules) {
     }
     return Object.keys(state).length > 0 ? state : undefined;
 }
+async function linkPlatformDirectory(tx, localPath, storeCommitPath, platforms) {
+    await tx.preparePathReplacement(localPath, storeCommitPath);
+    await linker.linkLib(localPath, storeCommitPath, platforms);
+}
+async function linkGeneralDirectory(tx, localPath, storeSharedPath) {
+    await tx.preparePathReplacement(localPath, storeSharedPath);
+    await linker.linkGeneral(localPath, storeSharedPath);
+}
 /**
  * 单个 scope（主项目或 submodule）的链接处理
  *
  * 包含：解析依赖、分类、预扫描平台、下载确认、逐个处理、并行下载、嵌套 actions
  */
 async function linkScope(params) {
-    const { scopeName, configPath, platforms, scanExtraPlatforms, registry, tx, projectHash, projectRoot, storePath, download, dryRun, yes, concurrency, gitLightweightDownload, optionalConfigs, scope, } = params;
+    const { scopeName, configPath, platforms, scanExtraPlatforms, registry, tx, 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();
+    // General 身份包含版本和项目位置，避免同名的其他依赖被误判为 General。
+    const generalDependencyKeys = new Set();
+    // 吸收过程中发现、但项目配置没有显式 dependency 的嵌套库仍需保留项目引用。
+    const implicitStoreReferences = new Map();
     const downloadedLibs = [];
+    const linkedMissingDependencyKeys = new Set();
     let savedBytes = 0;
     // 1. 解析依赖
     info(`分析 ${scopeName}: ${configPath}`);
@@ -559,7 +754,7 @@ async function linkScope(params) {
     if (dryRun) {
         showDryRunInfo(classified, stats);
         return {
-            linkedDeps: [], nestedLinkedDeps: [], generalLibs, downloadedLibs,
+            linkedDeps: [], nestedLinkedDeps: [], implicitStoreReferences: [], downloadedLibs,
             savedBytes: 0, finalLinkPlatforms, stats,
         };
     }
@@ -606,8 +801,12 @@ async function linkScope(params) {
                     .filter(e => e.isDirectory() && KNOWN_PLATFORM_VALUES.includes(e.name))
                     .forEach(e => allLocalPlatforms.add(e.name));
             }
-            catch {
-                // 读取失败，跳过
+            catch (err) {
+                if (isPathMissingError(err))
+                    continue;
+                error(`[link] 本地平台预扫描失败: lib=${item.dependency.libName}, commit=${item.dependency.commit}, ` +
+                    `path=${item.localPath}, code=${err.code ?? 'unknown'}, message=${err.message}`);
+                throw err;
             }
         }
         const extraPlatforms = [...allLocalPlatforms].filter(p => !platforms.includes(p));
@@ -625,7 +824,7 @@ async function linkScope(params) {
             if (selectedPlatforms === PROMPT_CANCELLED) {
                 info('已取消');
                 return {
-                    linkedDeps: [], nestedLinkedDeps: [], generalLibs, downloadedLibs,
+                    linkedDeps: [], nestedLinkedDeps: [], implicitStoreReferences: [], downloadedLibs,
                     savedBytes: 0, finalLinkPlatforms, stats,
                 };
             }
@@ -704,6 +903,7 @@ async function linkScope(params) {
     // 7. 逐个处理依赖（LINKED/RELINK/REPLACE/ABSORB/LINK_NEW）
     for (const item of classified) {
         const { dependency, status, localPath, repairRequiredPlatforms } = item;
+        const implicitOwner = implicitReferenceOwner(dependency, projectRoot, localPath, scope);
         await store.ensureCompatibleStore(storePath, dependency.libName, dependency.commit);
         switch (status) {
             case DependencyStatus.LINKED: {
@@ -716,22 +916,21 @@ async function linkScope(params) {
                         useGitLightweightDownload: gitLightweightDownload,
                         repairRequiredPlatforms,
                     });
-                    await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
+                    await registerNestedLibraries(supplementResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                     if (supplementResult.downloaded.length > 0) {
                         const linkedCommitPath = path.join(storePath, dependency.libName, dependency.commit);
                         const { actualExisting: allExisting, satisfiedRequested } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                         clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
-                        await tx.recordOp('link', localPath, linkedCommitPath);
-                        await linker.linkLib(localPath, linkedCommitPath, allExisting);
-                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, allExisting, projectHash, false);
+                        await linkPlatformDirectory(tx, localPath, linkedCommitPath, allExisting);
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, allExisting, false);
                         success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 已补充平台 [${supplementResult.downloaded.join(', ')}]`);
                     }
                 }
                 const { actualExisting: linkedExisting, satisfiedRequested } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                 clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
-                await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, isLinkedGeneral ? [GENERAL_PLATFORM] : linkedExisting, projectHash, isLinkedGeneral);
+                await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, isLinkedGeneral ? [GENERAL_PLATFORM] : linkedExisting, isLinkedGeneral);
                 if (isLinkedGeneral) {
-                    generalLibs.add(dependency.libName);
+                    generalDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                 }
                 break;
             }
@@ -741,13 +940,10 @@ async function linkScope(params) {
                 const relinkCommitPath = path.join(storePath, dependency.libName, dependency.commit);
                 const isRelinkGeneral = await resolveLibraryGeneralState(dependency, requestedPlatforms, configVars);
                 if (isRelinkGeneral) {
-                    await tx.recordOp('unlink', localPath);
-                    await linker.unlink(localPath);
                     const sharedPath = path.join(relinkCommitPath, '_shared');
-                    await 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);
+                    await linkGeneralDirectory(tx, localPath, sharedPath);
+                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], true);
+                    generalDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                     success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，重建链接`);
                 }
                 else {
@@ -756,7 +952,7 @@ async function linkScope(params) {
                         useGitLightweightDownload: gitLightweightDownload,
                         repairRequiredPlatforms,
                     });
-                    await registerNestedLibraries(relinkSupplementResult.nestedLibraries, projectHash);
+                    await registerNestedLibraries(relinkSupplementResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                     const { actualExisting: relinkExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                     clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
                     if (relinkExisting.length === 0) {
@@ -779,11 +975,8 @@ async function linkScope(params) {
                         }
                         break;
                     }
-                    await tx.recordOp('unlink', localPath);
-                    await linker.unlink(localPath);
-                    await tx.recordOp('link', localPath, relinkCommitPath);
-                    await linker.linkLib(localPath, relinkCommitPath, relinkExisting);
-                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, relinkExisting, projectHash, false);
+                    await linkPlatformDirectory(tx, localPath, relinkCommitPath, relinkExisting);
+                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, relinkExisting, false);
                     if (relinkSupplementResult.downloaded.length > 0) {
                         success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 重建链接并补充平台 [${relinkExisting.join(', ')}]`);
                     }
@@ -801,11 +994,10 @@ async function linkScope(params) {
                 const isReplaceGeneral = await resolveLibraryGeneralState(dependency, requestedPlatforms, configVars);
                 if (isReplaceGeneral) {
                     const sharedPath = path.join(replaceCommitPath, '_shared');
-                    await tx.recordOp('replace', localPath, sharedPath);
-                    await linker.linkGeneral(localPath, sharedPath);
+                    await linkGeneralDirectory(tx, localPath, sharedPath);
                     savedBytes += replaceSize;
-                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], projectHash, true);
-                    generalLibs.add(dependency.libName);
+                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], true);
+                    generalDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                     success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，创建链接`);
                 }
                 else {
@@ -814,7 +1006,7 @@ async function linkScope(params) {
                         useGitLightweightDownload: gitLightweightDownload,
                         repairRequiredPlatforms,
                     });
-                    await registerNestedLibraries(replaceSupplementResult.nestedLibraries, projectHash);
+                    await registerNestedLibraries(replaceSupplementResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                     const { actualExisting: replaceExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                     clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
                     if (replaceExisting.length === 0) {
@@ -837,10 +1029,9 @@ async function linkScope(params) {
                         }
                         break;
                     }
-                    await tx.recordOp('replace', localPath, replaceCommitPath);
-                    await linker.linkLib(localPath, replaceCommitPath, replaceExisting);
+                    await linkPlatformDirectory(tx, localPath, replaceCommitPath, replaceExisting);
                     savedBytes += replaceSize;
-                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, replaceExisting, projectHash, false);
+                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, replaceExisting, false);
                     if (replaceSupplementResult.downloaded.length > 0) {
                         success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - Store 已有，创建链接并补充平台 [${replaceExisting.join(', ')}]`);
                     }
@@ -881,20 +1072,31 @@ async function linkScope(params) {
                 const progressTracker = new ProgressTracker({
                     name: `  移入 Store`, total: absorbSize, showSpeed: true,
                 });
-                await tx.recordOp('absorb', storeCommitPath, localPath);
                 let progressStarted = false;
-                const absorbResult = await store.absorbLib(localPath, finalPlatforms, dependency.libName, dependency.commit, {
-                    totalSize: absorbSize,
-                    onProgress: (copied, _total) => {
-                        if (!progressStarted) {
-                            progressStarted = true;
-                            progressTracker.start();
-                        }
-                        progressTracker.update(copied);
-                    },
-                });
-                if (progressStarted)
-                    progressTracker.stop();
+                let absorbResult;
+                try {
+                    absorbResult = await new StoreImportService(registry, storePath).importLibrary({
+                        libDir: localPath,
+                        platforms: finalPlatforms,
+                        libName: dependency.libName,
+                        commit: dependency.commit,
+                        branch: dependency.branch,
+                        url: dependency.url,
+                        sourceKind: 'local',
+                        totalSize: absorbSize,
+                        onProgress: (copied, _total) => {
+                            if (!progressStarted) {
+                                progressStarted = true;
+                                progressTracker.start();
+                            }
+                            progressTracker.update(copied);
+                        },
+                    });
+                }
+                finally {
+                    if (progressStarted)
+                        progressTracker.stop();
+                }
                 let absorbLinkPlatforms = [...Object.keys(absorbResult.platformPaths), ...absorbResult.skippedPlatforms];
                 const absorbLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
                 if (!registry.getLibrary(absorbLibKey)) {
@@ -918,22 +1120,17 @@ async function linkScope(params) {
                         }
                     }
                     await registerSharedStore(dependency.libName, dependency.commit, dependency.branch, dependency.url);
-                    await registerNestedLibraries(absorbResult.nestedLibraries, projectHash);
+                    await registerNestedLibraries(absorbResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                     const absorbSupplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, {
                         vars: configVars,
                         useGitLightweightDownload: gitLightweightDownload,
                         repairRequiredPlatforms,
                     });
-                    await registerNestedLibraries(absorbSupplementResult.nestedLibraries, projectHash);
+                    await registerNestedLibraries(absorbSupplementResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                     if (absorbSupplementResult.downloaded.length > 0) {
                         absorbLinkPlatforms = [...absorbLinkPlatforms, ...absorbSupplementResult.downloaded];
                     }
-                    await tx.recordOp('link', localPath, storeCommitPath);
-                    await linker.linkLib(localPath, storeCommitPath, absorbLinkPlatforms);
-                    for (const platform of absorbLinkPlatforms) {
-                        const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
-                        registry.addStoreReference(storeKey, projectHash);
-                    }
+                    await linkPlatformDirectory(tx, localPath, storeCommitPath, absorbLinkPlatforms);
                     if (absorbSupplementResult.downloaded.length > 0) {
                         hint(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 本地已有，移入 Store 并补充平台 [${absorbLinkPlatforms.join(', ')}]`);
                     }
@@ -951,8 +1148,7 @@ async function linkScope(params) {
                             break;
                         }
                         const { GENERAL_PLATFORM } = await import('../core/platform.js');
-                        await tx.recordOp('link', localPath, sharedPath);
-                        await linker.linkGeneral(localPath, sharedPath);
+                        await linkGeneralDirectory(tx, localPath, sharedPath);
                         const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, GENERAL_PLATFORM);
                         if (!registry.getStore(storeKey)) {
                             const integrity = await store.captureIntegrity(dependency.libName, dependency.commit, GENERAL_PLATFORM);
@@ -962,7 +1158,6 @@ async function linkScope(params) {
                                 usedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
                             });
                         }
-                        registry.addStoreReference(storeKey, projectHash);
                         const libKeyGen = registry.getLibraryKey(dependency.libName, dependency.commit);
                         if (!registry.getLibrary(libKeyGen)) {
                             const sharedSize = await getDirSize(sharedPath);
@@ -973,7 +1168,7 @@ async function linkScope(params) {
                                 referencedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
                             });
                         }
-                        generalLibs.add(dependency.libName);
+                        generalDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                         hint(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，整目录链接`);
                     }
                     catch {
@@ -1040,9 +1235,16 @@ async function linkScope(params) {
                         clearSatisfiedAutoUnavailablePlatforms(registry, dependency, assessment.satisfiedRequested);
                         const filteredDownloaded = assessment.downloadedRequested;
                         if (filteredDownloaded.length > 0) {
-                            await tx.recordOp('absorb', linkNewCommitPath, downloadResult.libDir);
-                            const linkNewAbsorbResult = await store.absorbLib(downloadResult.libDir, filteredDownloaded, dependency.libName, dependency.commit);
-                            await registerNestedLibraries(linkNewAbsorbResult.nestedLibraries, projectHash);
+                            const linkNewAbsorbResult = await new StoreImportService(registry, storePath).importLibrary({
+                                libDir: downloadResult.libDir,
+                                platforms: filteredDownloaded,
+                                libName: dependency.libName,
+                                commit: dependency.commit,
+                                branch: dependency.branch,
+                                url: dependency.url,
+                                sourceKind: 'download',
+                            });
+                            await registerNestedLibraries(linkNewAbsorbResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                             const repaired = filteredDownloaded.filter((platform) => repairRequiredSet.has(platform));
                             if (repaired.length > 0) {
                                 warn(`${dependency.libName} ${repaired.join(', ')} 本地缓存不完整，已重新下载`);
@@ -1050,7 +1252,11 @@ async function linkScope(params) {
                         }
                     }
                     finally {
-                        await fs.rm(downloadResult.tempDir, { recursive: true, force: true }).catch(() => { });
+                        await cleanupDownloadTempDir(downloadResult.tempDir, {
+                            libName: dependency.libName,
+                            commit: dependency.commit,
+                            stage: 'link-new-import',
+                        });
                     }
                 }
                 const { actualExisting: linkNewExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
@@ -1058,10 +1264,9 @@ async function linkScope(params) {
                 const isLinkNewGeneral = await resolveLibraryGeneralState(dependency, requestedPlatforms, configVars);
                 if (isLinkNewGeneral) {
                     const sharedPath = path.join(linkNewCommitPath, '_shared');
-                    await 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);
+                    await linkGeneralDirectory(tx, localPath, sharedPath);
+                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], true);
+                    generalDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                     if (isRepairingGeneral) {
                         warn(`${dependency.libName} ${GENERAL_PLATFORM} 本地缓存不完整，已重新下载`);
                     }
@@ -1090,17 +1295,18 @@ async function linkScope(params) {
                     break;
                 }
                 else {
-                    await tx.recordOp('link', localPath, linkNewCommitPath);
-                    await linker.linkLib(localPath, linkNewCommitPath, linkNewExisting);
-                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, linkNewExisting, projectHash, false);
+                    await linkPlatformDirectory(tx, localPath, linkNewCommitPath, linkNewExisting);
+                    await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, linkNewExisting, false);
                     success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 创建链接 [${linkNewExisting.join(', ')}]`);
                 }
                 break;
             }
         }
-        // 无论当前是跳过、补平台还是重建链接，都要把本地残留的平台目录清理到最终平台集合
-        const desiredLocalPlatforms = await resolveStoredPlatforms(dependency.libName, dependency.commit, finalLinkPlatforms);
-        await linker.cleanupLocalExtraPlatforms(localPath, desiredLocalPlatforms);
+        // 本地链接集合由本次请求及 sparse 映射决定，不能使用 Store 中全部可用平台。
+        const { actualExisting: desiredLocalPlatforms } = await resolveRequestedStoreState(dependency, finalLinkPlatforms, configVars);
+        debug(`[link-registry] 本地平台清理准备: lib=${dependency.libName}, commit=${dependency.commit}, ` +
+            `requested=${finalLinkPlatforms.join(',')}, desired=${desiredLocalPlatforms.join(',')}, local=${localPath}`);
+        await linker.cleanupLocalExtraPlatforms(localPath, desiredLocalPlatforms, (entryPath) => tx.preparePathReplacement(entryPath, 'extra-platform-cleanup'));
         await tx.save();
     }
     // 8. 并行处理 MISSING 依赖
@@ -1116,8 +1322,9 @@ async function linkScope(params) {
             const isTTY = process.stdout.isTTY ?? false;
             const multiBarManager = isTTY ? new MultiBarManager() : null;
             const downloadLimit = pLimit(concurrency);
-            const downloadTasks = toDownload.map((item) => downloadLimit(async () => {
+            const results = await runParallelDownloadBatch(() => toDownload.map((item) => downloadLimit(async () => {
                 const { dependency, localPath, repairRequiredPlatforms = [] } = item;
+                const implicitOwner = implicitReferenceOwner(dependency, projectRoot, localPath, scope);
                 const repairRequiredSet = new Set(repairRequiredPlatforms);
                 const pLog = {
                     info: (msg) => multiBarManager ? multiBarManager.log(`[info] ${msg}`) : info(msg),
@@ -1126,6 +1333,7 @@ async function linkScope(params) {
                     warn: (msg) => multiBarManager ? multiBarManager.log(`[warn] ${msg}`) : warn(msg),
                     error: (msg) => multiBarManager ? multiBarManager.log(`[err] ${msg}`) : error(msg),
                 };
+                let downloadCompleted = false;
                 try {
                     const storeCommitPath = path.join(storePath, dependency.libName, dependency.commit);
                     const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
@@ -1159,10 +1367,10 @@ async function linkScope(params) {
                             };
                         }
                         pLog.info(`${dependency.libName} 所有平台已存在，直接链接...`);
-                        await tx.recordOp('link', localPath, storeCommitPath);
-                        await linker.linkLib(localPath, storeCommitPath, existing);
-                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, existing, projectHash, false);
+                        await linkPlatformDirectory(tx, localPath, storeCommitPath, existing);
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, existing, false);
                         pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 链接完成 [${existing.join(', ')}]`);
+                        linkedMissingDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                         return { success: true, name: dependency.libName, downloadedPlatforms: existing, skippedPlatforms: [] };
                     }
                     const dlLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
@@ -1209,6 +1417,7 @@ async function linkScope(params) {
                     finally {
                         await downloadMonitor.stop();
                     }
+                    downloadCompleted = true;
                     if (downloadResult.cleanedPlatforms.length > 0) {
                         pLog.hint(`  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
                     }
@@ -1220,13 +1429,18 @@ async function linkScope(params) {
                                 platforms: [GENERAL_PLATFORM],
                                 isGeneral: true,
                             });
-                            await tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                            await store.absorbGeneral(downloadResult.libDir, dependency.libName, dependency.commit);
+                            await new StoreImportService(registry, storePath).importGeneral({
+                                libDir: downloadResult.libDir,
+                                libName: dependency.libName,
+                                commit: dependency.commit,
+                                branch: dependency.branch,
+                                url: dependency.url,
+                                sourceKind: 'download',
+                            });
                             const sharedPath = path.join(storeCommitPath, '_shared');
-                            await 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);
+                            await linkGeneralDirectory(tx, localPath, sharedPath);
+                            await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], true);
+                            generalDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                             if (isRepairingGeneral) {
                                 pLog.warn(`${dependency.libName} ${GENERAL_PLATFORM} 本地缓存不完整，已重新下载`);
                             }
@@ -1236,6 +1450,7 @@ async function linkScope(params) {
                             else {
                                 pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，下载完成`);
                             }
+                            linkedMissingDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                             return { success: true, name: dependency.libName, downloadedPlatforms: [GENERAL_PLATFORM], skippedPlatforms: [], isGeneral: true };
                         }
                         const filteredDownloaded = assessment.downloadedRequested;
@@ -1249,9 +1464,16 @@ async function linkScope(params) {
                             pLog.warn(`${dependency.libName} 平台 [${newUnavailable.join(', ')}] 远程不存在，已记录`);
                         }
                         if (filteredDownloaded.length > 0) {
-                            await tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                            const downloadAbsorbResult = await store.absorbLib(downloadResult.libDir, filteredDownloaded, dependency.libName, dependency.commit);
-                            await registerNestedLibraries(downloadAbsorbResult.nestedLibraries, projectHash);
+                            const downloadAbsorbResult = await new StoreImportService(registry, storePath).importLibrary({
+                                libDir: downloadResult.libDir,
+                                platforms: filteredDownloaded,
+                                libName: dependency.libName,
+                                commit: dependency.commit,
+                                branch: dependency.branch,
+                                url: dependency.url,
+                                sourceKind: 'download',
+                            });
+                            await registerNestedLibraries(downloadAbsorbResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                         }
                         const linkPlatforms = [...existing, ...filteredDownloaded];
                         if (linkPlatforms.length === 0) {
@@ -1266,9 +1488,8 @@ async function linkScope(params) {
                                 skippedPlatforms: requestedPlatforms,
                             };
                         }
-                        await tx.recordOp('link', localPath, storeCommitPath);
-                        await linker.linkLib(localPath, storeCommitPath, linkPlatforms);
-                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, linkPlatforms, projectHash, false);
+                        await linkPlatformDirectory(tx, localPath, storeCommitPath, linkPlatforms);
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, linkPlatforms, false);
                         const notLinkedPlatforms = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, linkPlatforms, configVars).missingRequested;
                         const repaired = filteredDownloaded.filter((platform) => repairRequiredSet.has(platform));
                         if (repaired.length > 0) {
@@ -1277,13 +1498,27 @@ async function linkScope(params) {
                         else {
                             pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 下载完成 [${linkPlatforms.join(', ')}]`);
                         }
+                        linkedMissingDependencyKeys.add(dependencyIdentityKey(dependency, localPath));
                         return { success: true, name: dependency.libName, downloadedPlatforms: linkPlatforms, skippedPlatforms: notLinkedPlatforms };
                     }
                     finally {
-                        await fs.rm(downloadResult.tempDir, { recursive: true, force: true }).catch(() => { });
+                        await cleanupDownloadTempDir(downloadResult.tempDir, {
+                            libName: dependency.libName,
+                            commit: dependency.commit,
+                            stage: 'parallel-download-import',
+                        });
                     }
                 }
                 catch (err) {
+                    if (downloadCompleted) {
+                        pLog.error(`${dependency.libName} Store 导入或项目处理失败: ${err.message}`);
+                        return {
+                            success: false,
+                            name: dependency.libName,
+                            error: err.message,
+                            fatal: true,
+                        };
+                    }
                     const repairTargets = repairRequiredPlatforms.filter((platform) => platforms.includes(platform) || platform === GENERAL_PLATFORM);
                     const repairFailure = repairTargets.length > 0;
                     if (repairTargets.length > 0) {
@@ -1301,9 +1536,15 @@ async function linkScope(params) {
                         repairFailure,
                     };
                 }
-            }));
-            const results = await Promise.all(downloadTasks);
-            multiBarManager?.stop();
+            })), multiBarManager);
+            const fatalResults = results.filter((result) => 'fatal' in result && result.fatal);
+            if (fatalResults.length > 0) {
+                const details = fatalResults
+                    .map((result) => `${result.name}: ${'error' in result ? result.error : '未知错误'}`)
+                    .join(' | ');
+                debug(`[link] 并行任务全部结束后中止项目事务: failures=${details}`);
+                throw new Error(`Store 导入或项目处理失败: ${details}`);
+            }
             const succeeded = results.filter((r) => r.success);
             const failed = results.filter((r) => !r.success && !('skipped' in r && r.skipped));
             blank();
@@ -1355,35 +1596,40 @@ async function linkScope(params) {
         const thirdPartyDir = path.dirname(configPath);
         for (const action of actions) {
             await processAction(action, nestedContext, configPath, thirdPartyDir, {
-                tx, registry, projectHash, projectRoot, storePath, dryRun, download, yes,
+                tx, registry, projectRoot, storePath, dryRun, download, yes,
                 gitLightweightDownload, skipActions: new Set(params.skipActions ?? []),
-                generalLibs, downloadedLibs, nestedLinkedDeps,
+                scope, generalDependencyKeys, implicitStoreReferences, downloadedLibs, nestedLinkedDeps,
             });
         }
     }
     // 10. 同步 cache 文件
     for (const cacheConfigPath of cacheConfigPaths) {
-        await syncCacheFile(cacheConfigPath, storePath, dryRun);
+        await syncCodepacCache(cacheConfigPath, {
+            projectRoot,
+            storePath,
+            transaction: tx,
+            reason: `scope-cache:${scopeName}:${path.basename(cacheConfigPath)}`,
+            dryRun,
+        });
     }
     // 11. 构建返回结果
     const linkedDeps = [];
     for (const item of classified) {
-        if (item.status === DependencyStatus.MISSING && !downloadedLibs.includes(item.dependency.libName)) {
+        if (item.status === DependencyStatus.MISSING &&
+            !linkedMissingDependencyKeys.has(dependencyIdentityKey(item.dependency, item.localPath))) {
             continue;
         }
-        const actualPlatforms = generalLibs.has(item.dependency.libName)
-            ? [GENERAL_PLATFORM]
-            : await resolveStoredPlatforms(item.dependency.libName, item.dependency.commit, platforms);
-        linkedDeps.push({
-            libName: item.dependency.libName,
-            commit: item.dependency.commit,
-            platform: actualPlatforms[0] ?? platforms[0],
-            linkedPath: path.relative(projectRoot, item.localPath),
-            scope,
-        });
+        const storeCommitPath = path.join(storePath, item.dependency.libName, item.dependency.commit);
+        await recordLinkedDependency(linkedDeps, item.dependency, item.localPath, storeCommitPath, projectRoot, generalDependencyKeys.has(dependencyIdentityKey(item.dependency, item.localPath)), scope);
     }
     return {
-        linkedDeps, nestedLinkedDeps, generalLibs, downloadedLibs, savedBytes, finalLinkPlatforms, stats,
+        linkedDeps,
+        nestedLinkedDeps,
+        implicitStoreReferences: serializeImplicitStoreReferences(implicitStoreReferences),
+        downloadedLibs,
+        savedBytes,
+        finalLinkPlatforms,
+        stats,
     };
 }
 /**
@@ -1402,6 +1648,39 @@ export async function linkProject(projectPath, options) {
         setProxyConfig(cfg.proxy);
     const concurrency = cfg?.concurrency ?? 5;
     const gitLightweightDownload = cfg?.gitLightweightDownload ?? true;
+    // 必须先恢复 Registry 文件和项目目录，再加载内存登记并据此选择平台与配置。
+    if (!options.dryRun) {
+        let recoveryInProgress = false;
+        try {
+            await Transaction.recoverPendingTransactions({
+                onRecoveryStart: (transaction) => {
+                    recoveryInProgress = true;
+                    warn(`发现未完成的事务 (${transaction.id.slice(0, 8)})`);
+                    info('正在尝试回滚...');
+                },
+                onRecoveryComplete: () => {
+                    recoveryInProgress = false;
+                    success('事务回滚完成');
+                },
+                onRecoveryFailure: (transaction, rollbackErrors) => {
+                    for (const rollbackError of rollbackErrors) {
+                        error(`[transaction] 历史事务恢复失败: transaction=${transaction.id}, detail=${rollbackError}`);
+                    }
+                },
+            });
+        }
+        catch (err) {
+            if (recoveryInProgress) {
+                error(`回滚失败: ${err.message}`);
+                hint('请手动检查 Store 和项目目录状态');
+            }
+            throw err;
+        }
+    }
+    else {
+        const pendingTransactions = await Transaction.getPendingTransactions();
+        debug(`[link] dry-run 跳过事务恢复与事务日志创建: pending=${pendingTransactions.length}`);
+    }
     const registry = getRegistry();
     await registry.load({ migrate: !options.dryRun });
     const existingProject = registry.getProjectByPath(normalizedPath);
@@ -1436,8 +1715,13 @@ export async function linkProject(projectPath, options) {
             process.exit(EXIT_CODES.NOINPUT);
         }
     }
-    catch {
-        error(`路径不存在: ${absolutePath}`);
+    catch (err) {
+        if (isPathMissingError(err))
+            error(`路径不存在: ${absolutePath}`);
+        else {
+            error(`项目路径无法访问: path=${absolutePath}, code=${err.code ?? 'unknown'}, ` +
+                `message=${err.message}`);
+        }
         process.exit(EXIT_CODES.NOINPUT);
     }
     // 发现可选配置文件，扫描位置跟随实际主配置所在目录。
@@ -1536,26 +1820,6 @@ export async function linkProject(projectPath, options) {
         }
     }
     const finalPath = normalizedRoot;
-    // 预演模式只读取现状，不恢复历史事务，也不创建新的持久事务日志。
-    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)
@@ -1564,9 +1828,12 @@ export async function linkProject(projectPath, options) {
         debug(`[link] 清理日志恢复完成: recovered=${recovered}, store=${storePath}`);
     }
     const projectHash = registry.hashPath(finalPath);
-    const tx = new Transaction(`link:${finalPath}`);
+    const tx = new Transaction(finalPath, storePath);
     if (!options.dryRun)
         await tx.begin();
+    let transactionCommitted = false;
+    let projectRegistrySnapshot;
+    let projectRegistryStage = 'linking';
     // === 阶段 4: 依次执行 linkScope ===
     try {
         // 主项目
@@ -1576,7 +1843,7 @@ export async function linkProject(projectPath, options) {
             platforms,
             finalLinkPlatforms: platforms,
             scanExtraPlatforms: true,
-            registry, tx, projectHash,
+            registry, tx,
             projectRoot: finalPath,
             storePath,
             download: options.download,
@@ -1601,7 +1868,7 @@ export async function linkProject(projectPath, options) {
                     platforms,
                     finalLinkPlatforms,
                     scanExtraPlatforms: false,
-                    registry, tx, projectHash,
+                    registry, tx,
                     projectRoot: finalPath,
                     storePath,
                     download: options.download,
@@ -1628,7 +1895,7 @@ export async function linkProject(projectPath, options) {
                 platforms,
                 finalLinkPlatforms,
                 scanExtraPlatforms: false,
-                registry, tx, projectHash,
+                registry, tx,
                 projectRoot: finalPath,
                 storePath,
                 download: options.download,
@@ -1643,14 +1910,23 @@ export async function linkProject(projectPath, options) {
             subResults.push(subResult);
         }
         // === 阶段 5: 合并结果、注册项目 ===
+        projectRegistrySnapshot = registry.snapshotState();
+        projectRegistryStage = 'assembling-project-references';
         // 合并所有依赖
-        const allLinkedDeps = [
+        const currentLinkedDeps = deduplicateDependencyRefs([
             ...mainResult.linkedDeps,
             ...mainResult.nestedLinkedDeps,
             ...subResults.flatMap(r => [...r.linkedDeps, ...r.nestedLinkedDeps]),
-        ];
-        // 获取旧引用
-        const oldStoreKeys = registry.getProjectStoreKeys(projectHash);
+        ]);
+        const retainedLinkedDeps = await retainExistingLinkedDependencies(existingProject, currentLinkedDeps, finalPath, storePath);
+        const allLinkedDeps = deduplicateDependencyRefs([
+            ...currentLinkedDeps,
+            ...retainedLinkedDeps,
+        ]);
+        const implicitStoreReferences = mergeProjectImplicitStoreReferences(existingProject, projectHash, allLinkedDeps, [
+            ...mainResult.implicitStoreReferences,
+            ...subResults.flatMap((result) => result.implicitStoreReferences),
+        ], registry);
         // 更新项目信息
         const relConfigPath = getRelativeConfigPath(finalPath, mainConfigPath);
         registry.addProject({
@@ -1664,19 +1940,26 @@ export async function linkProject(projectPath, options) {
             submodules: selectedSubmodules.length > 0
                 ? selectedSubmodules.map(s => s.relativePath) : undefined,
             submoduleOptionalConfigs: buildSubmoduleOptionalConfigState(selectedSubmodules),
+            implicitStoreReferences: implicitStoreReferences.length > 0 ? implicitStoreReferences : undefined,
         });
-        // 更新 Store 引用关系
-        const newStoreKeys = allLinkedDeps.map((d) => registry.getStoreKey(d.libName, d.commit, d.platform));
-        for (const key of oldStoreKeys) {
-            if (!newStoreKeys.includes(key)) {
-                registry.removeStoreReference(key, projectHash);
-            }
-        }
-        for (const key of newStoreKeys) {
-            registry.addStoreReference(key, projectHash);
-        }
+        // dependency 和 usedBy 使用同一份真实链接结果；隐式嵌套库由吸收结果补充。
+        const newStoreKeys = new Set([
+            ...allLinkedDeps.map((dependency) => registry.getStoreKey(dependency.libName, dependency.commit, dependency.platform)),
+            ...implicitStoreReferences.flatMap((reference) => reference.storeKeys),
+        ]);
+        debug(`[link-registry] 项目引用提交准备: project=${projectHash}, dependencies=${allLinkedDeps.length}, ` +
+            `retainedDependencies=${retainedLinkedDeps.length}, implicit=${implicitStoreReferences.length}, ` +
+            `storeKeys=${[...newStoreKeys].join(',') || 'none'}`);
+        const referenceUpdate = registry.replaceProjectReferences(projectHash, newStoreKeys);
+        debug(`[link-registry] 项目引用提交结果: project=${projectHash}, ` +
+            `added=${referenceUpdate.added.length}, removed=${referenceUpdate.removed.length}, ` +
+            `retained=${referenceUpdate.retained.length}`);
+        await tx.prepareFileReplacement(getRegistryPath(), 'registry-save');
+        projectRegistryStage = 'saving-registry';
         await registry.save();
+        projectRegistryStage = 'committing-project-transaction';
         await tx.commit();
+        transactionCommitted = true;
         // === 阶段 6: 统计报告 ===
         const allSavedBytes = mainResult.savedBytes + subResults.reduce((sum, r) => sum + r.savedBytes, 0);
         blank();
@@ -1767,20 +2050,43 @@ export async function linkProject(projectPath, options) {
         await checkForUpdates();
     }
     catch (err) {
+        if (transactionCommitted) {
+            error(`[link] 链接事务提交后的处理失败: transaction=${tx.id}, state=committed, message=${err.message}`);
+            hint('依赖链接和项目登记已经完成，本次不会回滚；后续运行会继续清理事务产物');
+            process.exit(1);
+        }
         // 链接过程出错，回滚事务
         error(`链接失败: ${err.message}`);
+        if (projectRegistrySnapshot) {
+            error(`[link-registry] 项目登记失败: transaction=${tx.id}, stage=${projectRegistryStage}, ` +
+                `project=${projectHash}, message=${err.message}`);
+        }
         hintStoreRepairCommand(err);
         if (!options.dryRun) {
             warn('正在回滚事务...');
             try {
-                await tx.rollback();
-                success('事务已回滚');
+                const rollbackErrors = await tx.rollback();
+                if (rollbackErrors.length === 0) {
+                    success('事务已回滚');
+                }
+                else {
+                    error(`事务回滚未完成: transaction=${tx.id}, failedOperations=${rollbackErrors.length}`);
+                    for (const rollbackError of rollbackErrors) {
+                        error(`[transaction] 当前事务恢复失败: transaction=${tx.id}, detail=${rollbackError}`);
+                    }
+                    hint('事务日志已保留，请停止修改项目并重新运行 td link 触发恢复');
+                }
             }
             catch (rollbackErr) {
                 error(`回滚失败: ${rollbackErr.message}`);
                 hint('请手动检查 Store 和项目目录状态');
             }
         }
+        if (projectRegistrySnapshot) {
+            registry.restoreState(projectRegistrySnapshot);
+            debug(`[link-registry] 项目登记内存恢复完成: transaction=${tx.id}, project=${projectHash}, ` +
+                `stage=${projectRegistryStage}`);
+        }
         process.exit(1);
     }
 }
@@ -1821,8 +2127,12 @@ async function registerSharedStore(libName, commit, branch = '', url = '') {
             return false; // 空目录不注册
         }
     }
-    catch {
-        return false; // 目录不存在
+    catch (err) {
+        if (isPathMissingError(err))
+            return false;
+        error(`[link-registry] shared 登记读取失败: lib=${libName}, commit=${commit}, path=${sharedPath}, ` +
+            `code=${err.code ?? 'unknown'}, message=${err.message}`);
+        throw err;
     }
     // 计算 _shared 完整性信息并注册
     const integrity = await store.captureIntegrity(libName, commit, SHARED_PLATFORM);
@@ -1850,7 +2160,7 @@ async function registerSharedStore(libName, commit, branch = '', url = '') {
     debug(`注册 _shared: ${libName}:${commit.slice(0, 8)} (${formatSize(integrity.size)})`);
     return true;
 }
-async function ensureStoreInfo(libName, commit, platform, branch, url, projectHash) {
+async function ensureStoreInfo(libName, commit, platform, branch, url) {
     const registry = getRegistry();
     const storeKey = registry.getStoreKey(libName, commit, platform);
     const existingEntry = registry.getStore(storeKey);
@@ -1876,9 +2186,6 @@ async function ensureStoreInfo(libName, commit, platform, branch, url, projectHa
             lastAccess: new Date().toISOString(),
         });
     }
-    if (projectHash) {
-        registry.addStoreReference(storeKey, projectHash);
-    }
 }
 async function syncLibraryInfo(libName, commit, branch, url, platforms, isGeneral) {
     const registry = getRegistry();
@@ -1926,17 +2233,101 @@ async function resolveStoredPlatforms(libName, commit, fallbackPlatforms) {
             .map(entry => entry.name);
         return storedPlatforms.length > 0 ? storedPlatforms : [...new Set(fallbackPlatforms)];
     }
-    catch {
-        return [...new Set(fallbackPlatforms)];
+    catch (err) {
+        if (isPathMissingError(err))
+            return [...new Set(fallbackPlatforms)];
+        error(`[link-registry] Store 平台枚举失败: lib=${libName}, commit=${commit}, path=${commitPath}, ` +
+            `code=${err.code ?? 'unknown'}, message=${err.message}`);
+        throw err;
     }
 }
-async function ensureLinkedRegistryState(libName, commit, branch, url, platforms, projectHash, isGeneral) {
+/**
+ * 项目引用登记以当前项目中的真实链接为准。任何无法证明的目录形态都会终止项目事务，
+ * 避免根据请求平台写入推测的 dependency 和 Store usedBy。
+ */
+export async function resolveLinkedPlatforms(input) {
+    const { libName, commit, localPath, storeCommitPath } = input;
+    debug(`[link-registry] 真实平台核对开始: lib=${libName}, commit=${commit}, local=${localPath}, store=${storeCommitPath}`);
+    try {
+        const stat = await fs.lstat(localPath);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`项目库应为包含平台链接的物理目录: isDirectory=${stat.isDirectory()}, isSymbolicLink=${stat.isSymbolicLink()}`);
+        }
+        const entries = await fs.readdir(localPath, { withFileTypes: true });
+        const linkedPlatforms = [];
+        for (const entry of entries) {
+            if (!KNOWN_PLATFORM_VALUES.includes(entry.name))
+                continue;
+            const entryPath = path.join(localPath, entry.name);
+            if (!entry.isSymbolicLink()) {
+                throw new Error(`平台项不是符号链接: platform=${entry.name}, path=${entryPath}`);
+            }
+            const rawTarget = await fs.readlink(entryPath);
+            const target = path.resolve(localPath, rawTarget);
+            const expectedTarget = path.join(storeCommitPath, entry.name);
+            if (!pathsEqual(target, expectedTarget)) {
+                throw new Error(`平台链接目标不属于当前 Store 版本: platform=${entry.name}, path=${entryPath}, target=${target}, expected=${expectedTarget}`);
+            }
+            linkedPlatforms.push(entry.name);
+            debug(`[link-registry] 真实平台链接确认: lib=${libName}, commit=${commit}, platform=${entry.name}, path=${entryPath}, target=${target}`);
+        }
+        if (linkedPlatforms.length === 0) {
+            throw new Error('项目目录中没有指向当前 Store 版本的平台链接');
+        }
+        const resolved = [...new Set(linkedPlatforms)];
+        debug(`[link-registry] 真实平台核对完成: lib=${libName}, commit=${commit}, platforms=${resolved.join(',')}`);
+        return resolved;
+    }
+    catch (err) {
+        const message = `无法确认项目真实平台: lib=${libName}, commit=${commit}, local=${localPath}, ` +
+            `store=${storeCommitPath}, detail=${err.message}`;
+        error(`[link-registry] 真实平台核对失败: ${message}`);
+        throw new Error(message, { cause: err });
+    }
+}
+async function resolveLinkedDependencyPlatforms(input) {
+    if (!input.isGeneral)
+        return resolveLinkedPlatforms(input);
+    const expectedTarget = path.join(input.storeCommitPath, SHARED_PLATFORM);
+    debug(`[link-registry] General 链接核对开始: lib=${input.libName}, commit=${input.commit}, ` +
+        `local=${input.localPath}, expected=${expectedTarget}`);
+    const status = await linker.getPathStatus(input.localPath, expectedTarget);
+    const materialized = status === 'directory' &&
+        (await isMaterializedStoreDirectory(input.localPath, expectedTarget));
+    if (status !== 'linked' && !materialized) {
+        const message = `无法确认项目 General 引用: lib=${input.libName}, commit=${input.commit}, ` +
+            `local=${input.localPath}, expected=${expectedTarget}, status=${status}`;
+        error(`[link-registry] General 链接核对失败: ${message}`);
+        throw new Error(message);
+    }
+    debug(`[link-registry] General 链接核对完成: lib=${input.libName}, commit=${input.commit}, ` +
+        `local=${input.localPath}, status=${status}, materialized=${materialized}, platform=${GENERAL_PLATFORM}`);
+    return [GENERAL_PLATFORM];
+}
+async function recordLinkedDependency(dependencies, dependency, localPath, storeCommitPath, projectRoot, isGeneral, scope) {
+    const actualPlatforms = await resolveLinkedDependencyPlatforms({
+        libName: dependency.libName,
+        commit: dependency.commit,
+        localPath,
+        storeCommitPath,
+        isGeneral,
+    });
+    dependencies.push(...buildDependencyRefs({
+        libName: dependency.libName,
+        commit: dependency.commit,
+        linkedPath: path.relative(projectRoot, localPath),
+        scope,
+    }, actualPlatforms));
+    debug(`[link-registry] dependency 登记完成: lib=${dependency.libName}, commit=${dependency.commit}, ` +
+        `local=${localPath}, scope=${scope ?? 'main'}, platforms=${actualPlatforms.join(',')}`);
+}
+async function ensureLinkedRegistryState(libName, commit, branch, url, platforms, isGeneral) {
     const linkedPlatforms = isGeneral ? [GENERAL_PLATFORM] : [...new Set(platforms)];
     const libraryPlatforms = isGeneral
         ? [GENERAL_PLATFORM]
         : await resolveStoredPlatforms(libName, commit, linkedPlatforms);
     for (const platform of linkedPlatforms) {
-        await ensureStoreInfo(libName, commit, platform, branch, url, projectHash);
+        await ensureStoreInfo(libName, commit, platform, branch, url);
     }
     if (!isGeneral) {
         await registerSharedStore(libName, commit, branch, url);
@@ -1947,7 +2338,7 @@ async function ensureLinkedRegistryState(libName, commit, branch, url, platforms
  * 注册嵌套依赖到 Registry
  * absorbLib 递归吸收嵌套依赖时只做文件操作，此函数负责 Registry 注册
  */
-async function registerNestedLibraries(nestedLibraries, projectHash) {
+async function registerNestedLibraries(nestedLibraries, references, owner) {
     if (nestedLibraries.length === 0)
         return;
     debug(`注册 ${nestedLibraries.length} 个嵌套依赖: ${nestedLibraries.map(n => n.libName).join(', ')}`);
@@ -1972,7 +2363,7 @@ async function registerNestedLibraries(nestedLibraries, projectHash) {
                     lastAccess: new Date().toISOString(),
                 });
             }
-            registry.addStoreReference(storeKey, projectHash);
+            addImplicitStoreReference(references, owner, storeKey);
             // 兼容旧结构：LibraryInfo
             const libKey = registry.getLibraryKey(nested.libName, nested.commit);
             if (!registry.getLibrary(libKey)) {
@@ -2008,7 +2399,7 @@ async function registerNestedLibraries(nestedLibraries, projectHash) {
                         lastAccess: new Date().toISOString(),
                     });
                 }
-                registry.addStoreReference(storeKey, projectHash);
+                addImplicitStoreReference(references, owner, storeKey);
             }
             // 注册 _shared 目录（如果存在）
             await registerSharedStore(nested.libName, nested.commit, '', '');
@@ -2030,6 +2421,11 @@ async function registerNestedLibraries(nestedLibraries, projectHash) {
             }
         }
     }
+    debug(`[link-registry] 隐式嵌套库登记完成: libraries=${nestedLibraries.length}, ` +
+        `owner=${implicitReferenceOwnerKey(owner)}, ` +
+        `storeKeys=${serializeImplicitStoreReferences(references)
+            .flatMap((reference) => reference.storeKeys)
+            .join(',') || 'none'}`);
 }
 /**
  * 分类依赖的链接状态
@@ -2079,8 +2475,10 @@ export async function classifyLinkStatus(localPath, storeCommitPath, isGeneral,
         await fs.lstat(localPath);
         return 'replace';
     }
-    catch {
-        return 'link_new';
+    catch (err) {
+        if (isPathMissingError(err))
+            return 'link_new';
+        throw err;
     }
 }
 /**
@@ -2247,6 +2645,7 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
     else {
         info(`${dependency.libName} 缺少平台 [${toDownload.join(', ')}]，尝试下载...`);
     }
+    let downloadCompleted = false;
     try {
         const downloadResult = await codepac.downloadToTemp({
             url: dependency.url,
@@ -2258,6 +2657,7 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
             vars: options.vars,
             useGitLightweightDownload: options.useGitLightweightDownload,
         });
+        downloadCompleted = true;
         // 提示清理的平台（如果有）
         if (downloadResult.cleanedPlatforms.length > 0) {
             hint(`  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
@@ -2286,9 +2686,15 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
             // 7. 吸收下载的内容到 Store（不做链接，由调用者负责）
             if (downloaded.length > 0) {
                 const storePath = await store.getStorePath();
-                const storeCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                await tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                const supplementAbsorbResult = await store.absorbLib(downloadResult.libDir, downloaded, dependency.libName, dependency.commit);
+                const supplementAbsorbResult = await new StoreImportService(registry, storePath).importLibrary({
+                    libDir: downloadResult.libDir,
+                    platforms: downloaded,
+                    libName: dependency.libName,
+                    commit: dependency.commit,
+                    branch: dependency.branch,
+                    url: dependency.url,
+                    sourceKind: 'download',
+                });
                 // 收集嵌套依赖（由调用者负责注册）
                 result.nestedLibraries.push(...supplementAbsorbResult.nestedLibraries);
                 // 8. 更新 Registry StoreEntry
@@ -2317,11 +2723,17 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
             }
         }
         finally {
-            // 清理临时目录
-            await fs.rm(downloadResult.tempDir, { recursive: true, force: true }).catch(() => { });
+            await cleanupDownloadTempDir(downloadResult.tempDir, {
+                libName: dependency.libName,
+                commit: dependency.commit,
+                stage: 'supplement-import',
+            });
         }
     }
     catch (err) {
+        if (downloadCompleted) {
+            throw err;
+        }
         const repairTargets = toDownload.filter((platform) => repairRequiredPlatforms.has(platform));
         if (repairTargets.length > 0) {
             error(`${dependency.libName} ${repairTargets.join(', ')} 本地缓存不完整，自动重新下载失败`);
@@ -2381,74 +2793,6 @@ function getStatusKey(status) {
     };
     return map[status];
 }
-/**
- * 同步配置文件到 cache 目录
- * 使 cmake 的 checkValid.js 检测能够通过
- */
-async function syncCacheFile(configPath, storePath, dryRun = false) {
-    const configDir = path.dirname(configPath);
-    const cacheDir = path.join(configDir, '.cache');
-    const configFileName = path.basename(configPath);
-    const cachePath = path.join(cacheDir, configFileName);
-    const tempCachePath = path.join(cacheDir, `.${configFileName}.tanmi-dock-${process.pid}-${crypto.randomBytes(4).toString('hex')}.tmp`);
-    let tempCacheCreated = false;
-    debug(`[link-cache] 同步检查: config=${configPath}, cache=${cachePath}, store=${storePath}, dryRun=${dryRun}`);
-    if (dryRun) {
-        debug(`[link-cache] 预演跳过写入: config=${configPath}, cache=${cachePath}`);
-        return;
-    }
-    try {
-        await assertPathOutsideStore(cacheDir, storePath, 'sync-action-cache-directory');
-        // 确保 .cache 目录存在
-        await fs.mkdir(cacheDir, { recursive: true });
-        // 文件级符号链接必须先删除链接本身，避免 copyFile 跟随链接覆盖 Store。
-        try {
-            const cacheStat = await fs.lstat(cachePath);
-            if (cacheStat.isDirectory()) {
-                throw new Error(`cache 目标是目录: ${cachePath}`);
-            }
-            if (cacheStat.isSymbolicLink()) {
-                const previousTarget = await fs.readlink(cachePath).catch(() => '(unreadable)');
-                await fs.unlink(cachePath);
-                debug(`[link-cache] 已移除旧 cache 符号链接: cache=${cachePath}, previousTarget=${previousTarget}`);
-            }
-        }
-        catch (err) {
-            if (err.code !== 'ENOENT')
-                throw err;
-        }
-        await assertPathOutsideStore(cachePath, storePath, 'sync-action-cache-file');
-        const tempHandle = await fs.open(tempCachePath, 'wx');
-        await tempHandle.close();
-        tempCacheCreated = true;
-        await fs.copyFile(configPath, tempCachePath);
-        try {
-            await fs.rename(tempCachePath, cachePath);
-        }
-        catch (err) {
-            const code = err.code;
-            if (code !== 'EEXIST' && code !== 'EPERM')
-                throw err;
-            await fs.rm(cachePath, { force: true });
-            await fs.rename(tempCachePath, cachePath);
-        }
-        if (process.env.VERBOSE) {
-            info(`已同步 cache: ${configFileName} -> ${path.relative(configDir, cachePath)}`);
-        }
-        debug(`[link-cache] 同步完成: config=${configPath}, cache=${cachePath}, state=written`);
-    }
-    catch (err) {
-        // cache 同步失败不应阻塞主流程，仅警告
-        warn(`cache 同步失败: ${configFileName} -> ${path.relative(configDir, cachePath)}: ${err.message}`);
-    }
-    finally {
-        if (tempCacheCreated) {
-            await fs.rm(tempCachePath, { force: true }).catch((err) => {
-                debug(`[link-cache] 临时文件清理失败: temp=${tempCachePath}, message=${err.message}`);
-            });
-        }
-    }
-}
 /**
  * 处理单个 action（嵌套依赖）
  * @param action action 配置
@@ -2491,10 +2835,16 @@ async function processAction(action, context, parentConfigPath, parentTargetDir,
     try {
         await fs.access(plan.nestedConfigPath);
     }
-    catch {
-        warn(`${indent}  跳过嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=配置不存在, config=${plan.nestedConfigPath}`);
-        hint(`${indent}  请确保 ${plan.configDir} 库已被下载`);
-        return;
+    catch (err) {
+        if (isPathMissingError(err)) {
+            warn(`${indent}  跳过嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=配置不存在, config=${plan.nestedConfigPath}`);
+            hint(`${indent}  请确保 ${plan.configDir} 库已被下载`);
+            return;
+        }
+        error(`${indent}嵌套 action 配置访问失败: name=${plan.actionName ?? '(未命名)'}, ` +
+            `config=${plan.nestedConfigPath}, code=${err.code ?? 'unknown'}, ` +
+            `message=${err.message}`);
+        throw err;
     }
     // 4. 提取指定库的依赖
     let nestedResult;
@@ -2539,7 +2889,13 @@ async function processAction(action, context, parentConfigPath, parentTargetDir,
         indent,
     });
     // 同步嵌套配置文件的 cache（兼容 checkValid.js 检测）
-    await syncCacheFile(plan.nestedConfigPath, options.storePath, options.dryRun);
+    const cacheSync = await syncCodepacCache(plan.nestedConfigPath, {
+        projectRoot: options.projectRoot,
+        storePath: options.storePath,
+        transaction: options.tx,
+        reason: `action-cache:${plan.actionName ?? 'unnamed'}:depth-${context.depth}`,
+        dryRun: options.dryRun,
+    });
     // 7. 递归处理嵌套 actions（如果没有 disable_action）
     if (!plan.parsed.disableAction && nestedActions.length > 0) {
         const nestedContext = {
@@ -2557,7 +2913,11 @@ async function processAction(action, context, parentConfigPath, parentTargetDir,
         info(`${indent}  跳过后续嵌套 action: name=${plan.actionName ?? '(未命名)'}, 原因=disable_action`);
     }
     const materializedPaths = [
-        ...new Set([...configPreparation.materializedPaths, ...targetPreparation.materializedPaths]),
+        ...new Set([
+            ...configPreparation.materializedPaths,
+            ...targetPreparation.materializedPaths,
+            ...cacheSync.directoryPreparation.materializedPaths,
+        ]),
     ];
     debug(`${indent}CodePac action 完成: name=${plan.actionName ?? '(未命名)'}, dependencies=${dependencies.length}, nestedActions=${nestedActions.length}, materialized=${materializedPaths.join(',') || 'none'}, output=${plan.nestedTargetDir}`);
 }
@@ -2585,8 +2945,14 @@ async function resolveLocalAndAbsorb(localPath, libName, commit, options) {
         case 'match': {
             info(`${indent}  ${libName} - 本地 commit 匹配，吸收到 Store`);
             if (!dryRun) {
-                await options.onMatch?.();
-                const absorbResult = await store.absorbLocalLib(localPath, libName, commit);
+                const absorbResult = await options.storeImporter.importLocalLibrary({
+                    libDir: localPath,
+                    libName,
+                    commit,
+                    branch: options.branch,
+                    url: options.url,
+                    sourceKind: 'local',
+                });
                 return { action: 'absorbed', isGeneral: absorbResult.isGeneral, absorbResult };
             }
             return { action: 'absorbed' };
@@ -2595,6 +2961,7 @@ async function resolveLocalAndAbsorb(localPath, libName, commit, options) {
             warn(`${indent}  ${libName}: 本地 commit (${verifyResult.actualCommit?.slice(0, 7)}) 与预期 (${commit.slice(0, 7)}) 不匹配，将重新下载`);
             if (!dryRun) {
                 await options.onMismatch?.(verifyResult.actualCommit);
+                await options.onDelete?.();
                 await fs.rm(localPath, { recursive: true, force: true });
             }
             return { action: 'deleted' };
@@ -2603,8 +2970,14 @@ async function resolveLocalAndAbsorb(localPath, libName, commit, options) {
             if (unverifiedStrategy === 'absorb') {
                 info(`${indent}  ${libName}: 本地无 .git 目录，按配置直接吸收`);
                 if (!dryRun) {
-                    await options.onNoGit?.();
-                    const absorbResult = await store.absorbLocalLib(localPath, libName, commit);
+                    const absorbResult = await options.storeImporter.importLocalLibrary({
+                        libDir: localPath,
+                        libName,
+                        commit,
+                        branch: options.branch,
+                        url: options.url,
+                        sourceKind: 'local',
+                    });
                     return { action: 'absorbed', isGeneral: absorbResult.isGeneral, absorbResult };
                 }
                 return { action: 'absorbed' };
@@ -2612,6 +2985,7 @@ async function resolveLocalAndAbsorb(localPath, libName, commit, options) {
             else {
                 warn(`${indent}  ${libName}: 本地无 .git 目录，无法验证 commit，将重新下载`);
                 if (!dryRun) {
+                    await options.onDelete?.();
                     await fs.rm(localPath, { recursive: true, force: true });
                 }
                 return { action: 'deleted' };
@@ -2624,7 +2998,7 @@ async function resolveLocalAndAbsorb(localPath, libName, commit, options) {
  */
 async function linkNestedDependencies(dependencies, params) {
     const { targetDir: nestedTargetDir, context, options, indent } = params;
-    const { tx, registry, projectHash, projectRoot, dryRun, download, generalLibs, downloadedLibs, nestedLinkedDeps } = options;
+    const { tx, registry, projectRoot, dryRun, download, generalDependencyKeys, implicitStoreReferences, downloadedLibs, nestedLinkedDeps, } = options;
     const { platforms, vars } = context;
     if (!dryRun) {
         await assertPathOutsideStore(nestedTargetDir, options.storePath, 'link-nested-dependencies');
@@ -2633,6 +3007,7 @@ async function linkNestedDependencies(dependencies, params) {
         const localPath = path.join(nestedTargetDir, dep.libName);
         const storePath = await store.getStorePath();
         const storeCommitPath = path.join(storePath, dep.libName, dep.commit);
+        const implicitOwner = implicitReferenceOwner(dep, projectRoot, localPath, options.scope);
         // 检查本地状态
         let localExists = false;
         let localIsSymlink = false;
@@ -2641,8 +3016,12 @@ async function linkNestedDependencies(dependencies, params) {
             localExists = true;
             localIsSymlink = stat.isSymbolicLink();
         }
-        catch {
-            // 不存在
+        catch (err) {
+            if (!isPathMissingError(err)) {
+                error(`[link-action] 本地依赖状态读取失败: lib=${dep.libName}, commit=${dep.commit}, ` +
+                    `path=${localPath}, code=${err.code ?? 'unknown'}, message=${err.message}`);
+                throw err;
+            }
         }
         // 检查 Store 状态和历史记录
         const unavailablePlatforms = getBlockedRequestedPlatforms(registry, dep, platforms, vars);
@@ -2698,8 +3077,10 @@ async function linkNestedDependencies(dependencies, params) {
                 unverifiedStrategy: strategy,
                 dryRun,
                 indent,
-                onMatch: () => tx.recordOp('absorb', storeCommitPath, localPath),
-                onNoGit: () => tx.recordOp('absorb', storeCommitPath, localPath),
+                storeImporter: new StoreImportService(registry, storePath),
+                branch: dep.branch,
+                url: dep.url,
+                onDelete: () => tx.preparePathReplacement(localPath, storeCommitPath),
             });
             if (resolveResult.action === 'absorbed' && !dryRun) {
                 if (resolveResult.isGeneral) {
@@ -2717,7 +3098,7 @@ async function linkNestedDependencies(dependencies, params) {
                     debug(`${indent}  ${dep.libName} - 本地吸收后平台回填: requested=${availablePlatforms.join(', ') || '无'}, absorbed=${absorbedPlatforms.join(', ') || '无'}, linkable=${existingPlatforms.join(', ') || '无'}`);
                 }
                 if (resolveResult.absorbResult?.nestedLibraries.length) {
-                    await registerNestedLibraries(resolveResult.absorbResult.nestedLibraries, projectHash);
+                    await registerNestedLibraries(resolveResult.absorbResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                 }
                 storeHas = isGeneral || existingPlatforms.length > 0;
                 // 吸收为 General 后，检查是否实际需要平台内容
@@ -2725,8 +3106,9 @@ async function linkNestedDependencies(dependencies, params) {
                 if (resolveResult.isGeneral && download) {
                     const hasPlatformSparse = dep.sparse && !isSparseOnlyCommon(dep.sparse);
                     if (hasPlatformSparse && availablePlatforms.length > 0) {
+                        let platformDownload;
                         try {
-                            const downloadResult = await codepac.downloadToTemp({
+                            platformDownload = await codepac.downloadToTemp({
                                 url: dep.url,
                                 commit: dep.commit,
                                 branch: dep.branch,
@@ -2736,25 +3118,43 @@ async function linkNestedDependencies(dependencies, params) {
                                 vars,
                                 useGitLightweightDownload: options.gitLightweightDownload,
                             });
-                            const assessment = assessDownloadResult(availablePlatforms, dep.sparse, downloadResult, vars);
+                            const assessment = assessDownloadResult(availablePlatforms, dep.sparse, platformDownload, vars);
                             clearSatisfiedAutoUnavailablePlatforms(registry, dep, assessment.satisfiedRequested);
                             if (assessment.downloadedRequested.length > 0) {
                                 // 有平台内容 → 吸收平台目录，重新分类为平台库
-                                await tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                                const nestedAbsorbResult = await store.absorbLib(downloadResult.libDir, assessment.downloadedRequested, dep.libName, dep.commit);
-                                await registerNestedLibraries(nestedAbsorbResult.nestedLibraries, projectHash);
+                                const nestedAbsorbResult = await new StoreImportService(registry, storePath).importLibrary({
+                                    libDir: platformDownload.libDir,
+                                    platforms: assessment.downloadedRequested,
+                                    libName: dep.libName,
+                                    commit: dep.commit,
+                                    branch: dep.branch,
+                                    url: dep.url,
+                                    sourceKind: 'download',
+                                });
+                                await registerNestedLibraries(nestedAbsorbResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                                 existingPlatforms.push(...assessment.downloadedRequested);
                                 isGeneral = false;
                                 info(`${indent}  ${dep.libName} - 补充平台内容 [${assessment.downloadedRequested.join(', ')}]`);
                             }
-                            if (downloadResult.cleanedPlatforms.length > 0) {
-                                hint(`${indent}  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
+                            if (platformDownload.cleanedPlatforms.length > 0) {
+                                hint(`${indent}  已过滤: ${platformDownload.cleanedPlatforms.join(', ')}`);
                             }
                         }
-                        catch {
+                        catch (err) {
+                            if (platformDownload)
+                                throw err;
                             // 下载失败，保持 General 分类
                             warn(`${indent}  ${dep.libName} - 平台内容下载失败，保持 General 分类`);
                         }
+                        finally {
+                            if (platformDownload) {
+                                await cleanupDownloadTempDir(platformDownload.tempDir, {
+                                    libName: dep.libName,
+                                    commit: dep.commit,
+                                    stage: 'nested-general-platform-import',
+                                });
+                            }
+                        }
                     }
                 }
             }
@@ -2763,7 +3163,12 @@ async function linkNestedDependencies(dependencies, params) {
                 await fs.lstat(localPath);
                 localExists = true;
             }
-            catch {
+            catch (err) {
+                if (!isPathMissingError(err)) {
+                    error(`[link-action] 本地依赖更新后状态读取失败: lib=${dep.libName}, commit=${dep.commit}, ` +
+                        `path=${localPath}, code=${err.code ?? 'unknown'}, message=${err.message}`);
+                    throw err;
+                }
                 localExists = false;
             }
         }
@@ -2777,32 +3182,32 @@ async function linkNestedDependencies(dependencies, params) {
                     const supplementResult = await supplementMissingPlatforms(dep, platforms, registry, tx, { vars, useGitLightweightDownload: options.gitLightweightDownload, repairRequiredPlatforms });
                     // 注册嵌套依赖
                     if (supplementResult.nestedLibraries.length > 0) {
-                        await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
+                        await registerNestedLibraries(supplementResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                     }
                     // 如果补充了新平台，需要重新链接
                     if (supplementResult.downloaded.length > 0) {
                         success(`${indent}  ${dep.libName} - 补充平台 [${supplementResult.downloaded.join(', ')}]`);
-                        // 删除现有链接
-                        if (!dryRun) {
-                            await fs.rm(localPath, { recursive: true, force: true });
-                        }
                         // 合并所有平台并重新链接
                         const allPlatforms = [...existingPlatforms, ...supplementResult.downloaded];
                         linkedPlatforms = allPlatforms;
                         if (!dryRun) {
-                            await tx.recordOp('link', localPath, storeCommitPath);
-                            await linker.linkLib(localPath, storeCommitPath, allPlatforms);
+                            await linkPlatformDirectory(tx, localPath, storeCommitPath, allPlatforms);
                         }
                         success(`${indent}  ${dep.libName} - 重新链接完成 [${allPlatforms.join(', ')}]`);
                     }
                 }
-                await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, linkedPlatforms, projectHash, isGeneral);
-                nestedLinkedDeps.push({
-                    libName: dep.libName,
-                    commit: dep.commit,
-                    platform: isGeneral ? GENERAL_PLATFORM : (linkedPlatforms[0] ?? availablePlatforms[0]),
-                    linkedPath: path.relative(projectRoot, localPath),
-                });
+                await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, linkedPlatforms, isGeneral);
+                if (!isGeneral) {
+                    const { actualExisting: desiredNestedPlatforms } = await resolveRequestedStoreState(dep, platforms, vars);
+                    debug(`[link-registry] 嵌套平台清理准备: lib=${dep.libName}, commit=${dep.commit}, ` +
+                        `requested=${platforms.join(',')}, desired=${desiredNestedPlatforms.join(',')}, local=${localPath}`);
+                    await linker.cleanupLocalExtraPlatforms(localPath, desiredNestedPlatforms, (entryPath) => tx.preparePathReplacement(entryPath, 'nested-extra-platform-cleanup'));
+                    await tx.save();
+                }
+                if (isGeneral) {
+                    generalDependencyKeys.add(dependencyIdentityKey(dep, localPath));
+                }
+                await recordLinkedDependency(nestedLinkedDeps, dep, localPath, storeCommitPath, projectRoot, isGeneral);
                 if (!isGeneral) {
                     success(`${indent}  ${dep.libName} - 已链接`);
                 }
@@ -2810,9 +3215,6 @@ async function linkNestedDependencies(dependencies, params) {
             }
             if (linkStatus === 'relink') {
                 warn(`${indent}  ${dep.libName} - 链接异常（断链或指向错误），将重新链接`);
-                if (!dryRun) {
-                    await fs.rm(localPath, { recursive: true, force: true });
-                }
                 localExists = false;
                 localIsSymlink = false;
             }
@@ -2824,23 +3226,12 @@ async function linkNestedDependencies(dependencies, params) {
                 info(`${indent}  ${dep.libName} - 将链接到 Store`);
                 continue;
             }
-            if (localExists && !localIsSymlink) {
-                // 本地是目录，先删除
-                await fs.rm(localPath, { recursive: true, force: true });
-            }
             if (isGeneral) {
                 const sharedPath = path.join(storeCommitPath, '_shared');
-                await tx.recordOp('link', localPath, sharedPath);
-                await linker.linkGeneral(localPath, sharedPath);
-                await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, [GENERAL_PLATFORM], projectHash, true);
-                generalLibs.add(dep.libName);
-                // 记录到 nestedLinkedDeps
-                nestedLinkedDeps.push({
-                    libName: dep.libName,
-                    commit: dep.commit,
-                    platform: GENERAL_PLATFORM,
-                    linkedPath: path.relative(projectRoot, localPath),
-                });
+                await linkGeneralDirectory(tx, localPath, sharedPath);
+                await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, [GENERAL_PLATFORM], true);
+                generalDependencyKeys.add(dependencyIdentityKey(dep, localPath));
+                await recordLinkedDependency(nestedLinkedDeps, dep, localPath, storeCommitPath, projectRoot, true);
                 success(`${indent}  ${dep.libName} - 链接完成 (General)`);
             }
             else {
@@ -2848,7 +3239,7 @@ async function linkNestedDependencies(dependencies, params) {
                 const supplementResult = await supplementMissingPlatforms(dep, platforms, registry, tx, { vars, useGitLightweightDownload: options.gitLightweightDownload, repairRequiredPlatforms });
                 // 注册嵌套依赖
                 if (supplementResult.nestedLibraries.length > 0) {
-                    await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
+                    await registerNestedLibraries(supplementResult.nestedLibraries, implicitStoreReferences, implicitOwner);
                 }
                 // 合并所有可链接的平台（已有 + 新下载）
                 const allPlatforms = [...existingPlatforms, ...supplementResult.downloaded];
@@ -2856,16 +3247,9 @@ async function linkNestedDependencies(dependencies, params) {
                 if (supplementResult.downloaded.length > 0) {
                     success(`${indent}  ${dep.libName} - 补充平台 [${supplementResult.downloaded.join(', ')}]`);
                 }
-                await tx.recordOp('link', localPath, storeCommitPath);
-                await linker.linkLib(localPath, storeCommitPath, allPlatforms);
-                await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, allPlatforms, projectHash, false);
-                // 记录到 nestedLinkedDeps
-                nestedLinkedDeps.push({
-                    libName: dep.libName,
-                    commit: dep.commit,
-                    platform: allPlatforms[0],
-                    linkedPath: path.relative(projectRoot, localPath),
-                });
+                await linkPlatformDirectory(tx, localPath, storeCommitPath, allPlatforms);
+                await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, allPlatforms, false);
+                await recordLinkedDependency(nestedLinkedDeps, dep, localPath, storeCommitPath, projectRoot, false);
                 success(`${indent}  ${dep.libName} - 链接完成 [${allPlatforms.join(', ')}]`);
             }
         }
@@ -2882,6 +3266,8 @@ async function linkNestedDependencies(dependencies, params) {
                 info(`${indent}  ${dep.libName} - 将下载`);
                 continue;
             }
+            let downloadResult;
+            let downloadTempDir;
             try {
                 const nestedLibKey = registry.getLibraryKey(dep.libName, dep.commit);
                 const nestedHistoryLib = registry.getLibrary(nestedLibKey);
@@ -2890,7 +3276,6 @@ async function linkNestedDependencies(dependencies, params) {
                     estimatedSize: nestedHistoryLib?.size,
                     getDirSize,
                 });
-                let downloadResult;
                 try {
                     downloadResult = await codepac.downloadToTemp({
                         url: dep.url,
@@ -2901,13 +3286,18 @@ async function linkNestedDependencies(dependencies, params) {
                         sparse: dep.sparse,
                         vars,
                         useGitLightweightDownload: options.gitLightweightDownload,
-                        onTempDirCreated: (_tempDir, libDir) => { downloadMonitor.start(libDir); },
+                        onTempDirCreated: (tempDir, libDir) => {
+                            downloadTempDir = tempDir;
+                            downloadMonitor.start(libDir);
+                        },
                         onHeartbeat: (message) => { downloadMonitor.heartbeat(message); },
                     });
                 }
                 finally {
                     await downloadMonitor.stop();
                 }
+                if (!downloadResult)
+                    throw new Error(`${dep.libName} 下载未返回结果`);
                 // 提示清理的平台（如果有）
                 if (downloadResult.cleanedPlatforms.length > 0) {
                     hint(`${indent}  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
@@ -2920,21 +3310,20 @@ async function linkNestedDependencies(dependencies, params) {
                         platforms: [GENERAL_PLATFORM],
                         isGeneral: true,
                     });
-                    await tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                    await store.absorbGeneral(downloadResult.libDir, dep.libName, dep.commit);
-                    const sharedPath = path.join(storeCommitPath, '_shared');
-                    await tx.recordOp('link', localPath, sharedPath);
-                    await linker.linkGeneral(localPath, sharedPath);
-                    await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, [GENERAL_PLATFORM], projectHash, true);
-                    generalLibs.add(dep.libName);
-                    downloadedLibs.push(dep.libName);
-                    // 记录到 nestedLinkedDeps
-                    nestedLinkedDeps.push({
+                    await new StoreImportService(registry, storePath).importGeneral({
+                        libDir: downloadResult.libDir,
                         libName: dep.libName,
                         commit: dep.commit,
-                        platform: GENERAL_PLATFORM,
-                        linkedPath: path.relative(projectRoot, localPath),
+                        branch: dep.branch,
+                        url: dep.url,
+                        sourceKind: 'download',
                     });
+                    const sharedPath = path.join(storeCommitPath, '_shared');
+                    await linkGeneralDirectory(tx, localPath, sharedPath);
+                    await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, [GENERAL_PLATFORM], true);
+                    generalDependencyKeys.add(dependencyIdentityKey(dep, localPath));
+                    downloadedLibs.push(dep.libName);
+                    await recordLinkedDependency(nestedLinkedDeps, dep, localPath, storeCommitPath, projectRoot, true);
                     if (repairTargets.includes(GENERAL_PLATFORM)) {
                         warn(`${indent}  ${dep.libName} ${GENERAL_PLATFORM} 本地缓存不完整，已重新下载`);
                     }
@@ -2944,20 +3333,20 @@ async function linkNestedDependencies(dependencies, params) {
                 }
                 else if (assessment.downloadedRequested.length > 0) {
                     // 平台库处理
-                    await tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                    const nestedAbsorbResult = await store.absorbLib(downloadResult.libDir, assessment.downloadedRequested, dep.libName, dep.commit);
-                    await registerNestedLibraries(nestedAbsorbResult.nestedLibraries, projectHash);
-                    await tx.recordOp('link', localPath, storeCommitPath);
-                    await linker.linkLib(localPath, storeCommitPath, assessment.downloadedRequested);
-                    await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, assessment.downloadedRequested, projectHash, false);
-                    downloadedLibs.push(dep.libName);
-                    // 记录到 nestedLinkedDeps
-                    nestedLinkedDeps.push({
+                    const nestedAbsorbResult = await new StoreImportService(registry, storePath).importLibrary({
+                        libDir: downloadResult.libDir,
+                        platforms: assessment.downloadedRequested,
                         libName: dep.libName,
                         commit: dep.commit,
-                        platform: assessment.downloadedRequested[0],
-                        linkedPath: path.relative(projectRoot, localPath),
+                        branch: dep.branch,
+                        url: dep.url,
+                        sourceKind: 'download',
                     });
+                    await registerNestedLibraries(nestedAbsorbResult.nestedLibraries, implicitStoreReferences, implicitOwner);
+                    await linkPlatformDirectory(tx, localPath, storeCommitPath, assessment.downloadedRequested);
+                    await ensureLinkedRegistryState(dep.libName, dep.commit, dep.branch, dep.url, assessment.downloadedRequested, false);
+                    downloadedLibs.push(dep.libName);
+                    await recordLinkedDependency(nestedLinkedDeps, dep, localPath, storeCommitPath, projectRoot, false);
                     // 检查并记录新发现的不可用平台
                     const newUnavailable = assessment.unavailableRequested;
                     if (newUnavailable.length > 0) {
@@ -2986,15 +3375,11 @@ async function linkNestedDependencies(dependencies, params) {
                     });
                     warn(`${indent}  ${dep.libName} - 下载成功但平台 [${availablePlatforms.join(', ')}] 不可用，已记录`);
                 }
-                // 清理临时目录
-                try {
-                    await fs.rm(downloadResult.tempDir, { recursive: true, force: true });
-                }
-                catch {
-                    // 忽略清理错误
-                }
             }
             catch (err) {
+                if (downloadResult) {
+                    throw err;
+                }
                 if (repairTargets.length > 0) {
                     error(`${indent}  ${dep.libName} ${repairTargets.join(', ')} 本地缓存不完整，自动重新下载失败`);
                     hint(`${indent}  可运行 td reset ${dep.libName} 后重试`);
@@ -3005,6 +3390,16 @@ async function linkNestedDependencies(dependencies, params) {
                     warn(`${indent}  ${dep.libName} - 下载失败: ${err.message}`);
                 }
             }
+            finally {
+                const tempDir = downloadResult?.tempDir ?? downloadTempDir;
+                if (tempDir) {
+                    await cleanupDownloadTempDir(tempDir, {
+                        libName: dep.libName,
+                        commit: dep.commit,
+                        stage: 'nested-download-import',
+                    });
+                }
+            }
         }
         else {
             warn(`${indent}  ${dep.libName} - 缺失 (跳过下载)`);