tanmi-dock 0.9.0 → 0.9.3

package/dist/commands/link.js

@@ -7,13 +7,13 @@ import { Command } from 'commander';
 import { ensureInitialized } from '../core/guard.js';
 import * as config from '../core/config.js';
 import { setLogLevel } from '../utils/logger.js';
-import { parseProjectDependencies, getRelativeConfigPath, parseCodepacDep, extractActions, parseActionCommand, extractNestedDependencies, normalizeProjectRoot, findAllCodepacConfigs, extractDependencies, } from '../core/parser.js';
+import { parseProjectDependencies, getRelativeConfigPath, parseCodepacDep, extractActions, parseActionCommand, extractNestedDependencies, findAllCodepacConfigs, extractDependencies, resolveProjectRootPath, } from '../core/parser.js';
 import { getRegistry } from '../core/registry.js';
 import * as store from '../core/store.js';
 import * as linker from '../core/linker.js';
 import * as codepac from '../core/codepac.js';
 import { setProxyConfig } from '../core/codepac.js';
-import { resolvePath, getPlatformHelpText, GENERAL_PLATFORM, SHARED_PLATFORM, pathsEqual, isSparseOnlyCommon, KNOWN_PLATFORM_VALUES } from '../core/platform.js';
+import { getPlatformHelpText, GENERAL_PLATFORM, SHARED_PLATFORM, pathsEqual, isSparseOnlyCommon, KNOWN_PLATFORM_VALUES, getRequestedPlatformTargets, } from '../core/platform.js';
 import { Transaction } from '../core/transaction.js';
 import { formatSize, checkDiskSpace } from '../utils/disk.js';
 import { getDirSize } from '../utils/fs-utils.js';
@@ -60,6 +60,181 @@ export function createLinkCommand() {
         }
     });
 }
+function resolveRequestedPlatformsByActual(requestedPlatforms, sparse, actualPlatforms, vars) {
+    const actualExisting = [...new Set(actualPlatforms)];
+    const actualPlatformSet = new Set(actualExisting);
+    const satisfiedRequested = requestedPlatforms.filter((requestedPlatform) => {
+        const targets = getRequestedPlatformTargets(requestedPlatform, sparse, vars);
+        return targets.some((target) => actualPlatformSet.has(target));
+    });
+    return {
+        actualExisting,
+        satisfiedRequested,
+        missingRequested: requestedPlatforms.filter((platform) => !satisfiedRequested.includes(platform)),
+    };
+}
+export function assessDownloadResult(requestedPlatforms, sparse, downloadResult, vars) {
+    const downloadedActual = new Set(downloadResult.platformDirs);
+    const { satisfiedRequested, missingRequested, } = resolveRequestedPlatformsByActual(requestedPlatforms, sparse, downloadResult.platformDirs, vars);
+    const downloadedRequested = [...new Set(satisfiedRequested.flatMap((requestedPlatform) => getRequestedPlatformTargets(requestedPlatform, sparse, vars)
+            .filter((target) => downloadedActual.has(target))))];
+    const unavailableRequested = missingRequested;
+    const hasAnyPlatformArtifacts = downloadResult.allPlatformDirs.length > 0;
+    const isPureGeneral = Boolean((!sparse || isSparseOnlyCommon(sparse)) &&
+        !hasAnyPlatformArtifacts);
+    return {
+        downloadedRequested,
+        satisfiedRequested,
+        unavailableRequested,
+        hasAnyPlatformArtifacts,
+        isPureGeneral,
+    };
+}
+async function resolveRequestedStoreState(dependency, requestedPlatforms, vars) {
+    const resolvedExisting = [];
+    const candidatePlatforms = [...new Set(requestedPlatforms.flatMap((platform) => getRequestedPlatformTargets(platform, dependency.sparse, vars)))];
+    for (const platform of candidatePlatforms) {
+        if (await store.exists(dependency.libName, dependency.commit, platform)) {
+            resolvedExisting.push(platform);
+        }
+    }
+    return resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, resolvedExisting, vars);
+}
+function getBlockedRequestedPlatforms(registry, dependency, requestedPlatforms, vars) {
+    const { manualPlatforms, autoPlatforms } = resolveUnavailablePlatforms(registry, dependency);
+    const manualBlocked = requestedPlatforms.filter((platform) => manualPlatforms.includes(platform));
+    const autoBlocked = requestedPlatforms.filter((platform) => {
+        if (!autoPlatforms.includes(platform))
+            return false;
+        const targets = getRequestedPlatformTargets(platform, dependency.sparse, vars);
+        return targets.length === 1 && targets[0] === platform;
+    });
+    return [...new Set([...manualBlocked, ...autoBlocked])];
+}
+function clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested) {
+    if (satisfiedRequested.length === 0)
+        return;
+    const libKey = registry.getLibraryKey(dependency.libName, dependency.commit);
+    const library = registry.getLibrary(libKey);
+    if (!library?.unavailablePlatforms || library.unavailablePlatforms.length === 0)
+        return;
+    const nextUnavailable = library.unavailablePlatforms.filter((platform) => !satisfiedRequested.includes(platform));
+    if (nextUnavailable.length === library.unavailablePlatforms.length) {
+        return;
+    }
+    registry.updateLibrary(libKey, {
+        unavailablePlatforms: nextUnavailable,
+        lastAccess: new Date().toISOString(),
+    });
+}
+function upsertLibraryAvailability(dependency, updates) {
+    const registry = getRegistry();
+    const libKey = registry.getLibraryKey(dependency.libName, dependency.commit);
+    const existing = registry.getLibrary(libKey);
+    if (existing) {
+        registry.updateLibrary(libKey, {
+            unavailablePlatforms: updates.unavailablePlatforms ?? existing.unavailablePlatforms,
+            platforms: updates.platforms ?? existing.platforms,
+            isGeneral: updates.isGeneral ?? existing.isGeneral,
+            lastAccess: new Date().toISOString(),
+        });
+        return;
+    }
+    registry.addLibrary({
+        libName: dependency.libName,
+        commit: dependency.commit,
+        branch: dependency.branch,
+        url: dependency.url,
+        platforms: updates.platforms ?? [],
+        size: 0,
+        isGeneral: updates.isGeneral,
+        referencedBy: [],
+        unavailablePlatforms: updates.unavailablePlatforms,
+        createdAt: new Date().toISOString(),
+        lastAccess: new Date().toISOString(),
+    });
+}
+export async function resolveLibraryGeneralState(dependency) {
+    const registry = getRegistry();
+    const libKey = registry.getLibraryKey(dependency.libName, dependency.commit);
+    const library = registry.getLibrary(libKey);
+    if (typeof library?.isGeneral === 'boolean') {
+        return library.isGeneral;
+    }
+    return store.isGeneralLib(dependency.libName, dependency.commit);
+}
+export function resolveUnavailablePlatforms(registry, dependency) {
+    const libKey = registry.getLibraryKey(dependency.libName, dependency.commit);
+    const autoPlatforms = registry.getLibrary(libKey)?.unavailablePlatforms || [];
+    const manualPlatforms = registry.getManualUnavailablePlatforms(dependency.libName, dependency.commit);
+    return {
+        platforms: [...new Set([...manualPlatforms, ...autoPlatforms])],
+        manualPlatforms,
+        autoPlatforms,
+    };
+}
+export async function collectProjectDependencyGraph(projectRoot) {
+    const { normalizedPath, configPath } = await resolveProjectRootPath(projectRoot);
+    if (!configPath) {
+        throw new Error('只能在项目目录下使用');
+    }
+    const results = [];
+    const seenDeps = new Set();
+    const visitedConfigs = new Set();
+    const queue = [
+        { configPath, source: 'direct' },
+    ];
+    const submodules = await findSubmoduleConfigs(normalizedPath);
+    for (const submodule of submodules) {
+        queue.push({ configPath: submodule.configPath, scope: submodule.relativePath, source: 'submodule' });
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visitedConfigs.has(current.configPath))
+            continue;
+        visitedConfigs.add(current.configPath);
+        let parsedConfig;
+        try {
+            parsedConfig = await parseCodepacDep(current.configPath);
+        }
+        catch {
+            continue;
+        }
+        for (const dependency of extractDependencies(parsedConfig)) {
+            const key = `${dependency.libName}:${dependency.commit}:${current.scope ?? ''}`;
+            if (!seenDeps.has(key)) {
+                seenDeps.add(key);
+                results.push({ ...dependency, scope: current.scope, source: current.source });
+            }
+        }
+        for (const action of extractActions(parsedConfig)) {
+            let parsedAction;
+            try {
+                parsedAction = parseActionCommand(action.command);
+            }
+            catch {
+                continue;
+            }
+            const nestedConfigPath = path.resolve(path.dirname(current.configPath), parsedAction.configDir, 'codepac-dep.json');
+            let nested;
+            try {
+                nested = await extractNestedDependencies(nestedConfigPath, parsedAction.libraries);
+            }
+            catch {
+                continue;
+            }
+            for (const dependency of nested.dependencies) {
+                const key = `${dependency.libName}:${dependency.commit}:${current.scope ?? ''}`;
+                if (!seenDeps.has(key)) {
+                    seenDeps.add(key);
+                    results.push({ ...dependency, scope: current.scope, source: 'nested' });
+                }
+            }
+            queue.push({ configPath: nestedConfigPath, scope: current.scope, source: 'nested' });
+        }
+    }
+    return results;
+}
 /**
  * 选择要链接的 submodule
  */
@@ -144,7 +319,7 @@ async function linkScope(params) {
     blank();
     // 2. 分类依赖
     const scopePath = path.dirname(path.dirname(configPath));
-    const classified = await classifyDependencies(dependencies, scopePath, configPath, platforms);
+    const classified = await classifyDependencies(dependencies, scopePath, configPath, platforms, configVars);
     const stats = {
         linked: 0, relink: 0, replace: 0, absorb: 0, missing: 0, linkNew: 0,
     };
@@ -223,13 +398,21 @@ async function linkScope(params) {
         const needDownloadItems = [];
         for (const item of classified) {
             const { dependency, status } = item;
+            const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
+            const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
             if (status === DependencyStatus.MISSING) {
-                needDownloadItems.push({
-                    libName: dependency.libName, commit: dependency.commit, reason: '缺失',
-                });
+                if (requestedPlatforms.length > 0) {
+                    const { missingRequested } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
+                    if (missingRequested.length === 0) {
+                        continue;
+                    }
+                    needDownloadItems.push({
+                        libName: dependency.libName, commit: dependency.commit, reason: '缺失',
+                    });
+                }
             }
             else if (status === DependencyStatus.ABSORB) {
-                const { missing } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+                const { missingRequested: missing } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                 if (missing.length > 0) {
                     needDownloadItems.push({
                         libName: dependency.libName, commit: dependency.commit,
@@ -238,7 +421,7 @@ async function linkScope(params) {
                 }
             }
             else if (status === DependencyStatus.LINK_NEW) {
-                const { missing } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+                const { missingRequested: missing } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                 if (missing.length > 0) {
                     needDownloadItems.push({
                         libName: dependency.libName, commit: dependency.commit,
@@ -280,54 +463,62 @@ async function linkScope(params) {
             await store.ensureCompatibleStore(storePath, dependency.libName, dependency.commit);
             switch (status) {
                 case DependencyStatus.LINKED: {
-                    const isLinkedGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
+                    const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
+                    const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
+                    const isLinkedGeneral = await resolveLibraryGeneralState(dependency);
                     if (!isLinkedGeneral) {
                         const supplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, { vars: configVars });
                         await registerNestedLibraries(supplementResult.nestedLibraries, projectHash);
                         if (supplementResult.downloaded.length > 0) {
                             const linkedCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                            const { existing: allExisting } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+                            const { actualExisting: allExisting, satisfiedRequested } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
+                            clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
                             tx.recordOp('link', localPath, linkedCommitPath);
                             await linker.linkLib(localPath, linkedCommitPath, allExisting);
-                            for (const platform of allExisting) {
-                                const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
-                                registry.addStoreReference(storeKey, projectHash);
-                            }
+                            await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, allExisting, projectHash, 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);
                     break;
                 }
                 case DependencyStatus.RELINK: {
+                    const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
+                    const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
                     const relinkCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                    const isRelinkGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
+                    const isRelinkGeneral = await resolveLibraryGeneralState(dependency);
                     if (isRelinkGeneral) {
                         tx.recordOp('unlink', localPath);
                         await linker.unlink(localPath);
                         const sharedPath = path.join(relinkCommitPath, '_shared');
                         tx.recordOp('link', localPath, sharedPath);
                         await linker.linkGeneral(localPath, sharedPath);
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], projectHash, true);
                         generalLibs.add(dependency.libName);
                         success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，重建链接`);
                     }
                     else {
                         const relinkSupplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, { vars: configVars });
                         await registerNestedLibraries(relinkSupplementResult.nestedLibraries, projectHash);
-                        const { existing: relinkExisting } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+                        const { actualExisting: relinkExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
+                        clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
                         if (relinkExisting.length === 0) {
                             const { KNOWN_PLATFORM_VALUES } = await import('../core/platform.js');
                             const relinkCommitEntries = await fs.readdir(relinkCommitPath, { withFileTypes: true });
                             const relinkAvailablePlatforms = relinkCommitEntries
                                 .filter(e => e.isDirectory() && e.name !== '_shared' && KNOWN_PLATFORM_VALUES.includes(e.name))
                                 .map(e => e.name);
-                            warn(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 不支持 ${platforms.join('/')} 平台 [可用: ${relinkAvailablePlatforms.join(', ')}]`);
+                            warn(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 已按规则跳过平台 [${platforms.join('/')}], 可用平台 [${relinkAvailablePlatforms.join(', ')}]`);
                             const relinkLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
                             const relinkLib = registry.getLibrary(relinkLibKey);
                             if (relinkLib) {
                                 const unavailable = relinkLib.unavailablePlatforms || [];
-                                for (const p of platforms) {
-                                    if (!unavailable.includes(p) && !relinkAvailablePlatforms.includes(p))
-                                        unavailable.push(p);
+                                const missingRequested = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, relinkAvailablePlatforms, configVars).missingRequested;
+                                for (const requestedPlatform of missingRequested) {
+                                    if (!unavailable.includes(requestedPlatform))
+                                        unavailable.push(requestedPlatform);
                                 }
                                 registry.updateLibrary(relinkLibKey, { unavailablePlatforms: unavailable });
                             }
@@ -337,10 +528,7 @@ async function linkScope(params) {
                         await linker.unlink(localPath);
                         tx.recordOp('link', localPath, relinkCommitPath);
                         await linker.linkLib(localPath, relinkCommitPath, relinkExisting);
-                        for (const platform of relinkExisting) {
-                            const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
-                            registry.addStoreReference(storeKey, projectHash);
-                        }
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, relinkExisting, projectHash, false);
                         if (relinkSupplementResult.downloaded.length > 0) {
                             success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 重建链接并补充平台 [${relinkExisting.join(', ')}]`);
                         }
@@ -351,35 +539,40 @@ async function linkScope(params) {
                     break;
                 }
                 case DependencyStatus.REPLACE: {
+                    const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
+                    const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
                     const replaceSize = await getDirSize(localPath);
                     const replaceCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                    const isReplaceGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
+                    const isReplaceGeneral = await resolveLibraryGeneralState(dependency);
                     if (isReplaceGeneral) {
                         const sharedPath = path.join(replaceCommitPath, '_shared');
                         tx.recordOp('replace', localPath, sharedPath);
                         await linker.linkGeneral(localPath, sharedPath);
                         savedBytes += replaceSize;
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], projectHash, true);
                         generalLibs.add(dependency.libName);
                         success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，创建链接`);
                     }
                     else {
                         const replaceSupplementResult = await supplementMissingPlatforms(dependency, platforms, registry, tx, { vars: configVars });
                         await registerNestedLibraries(replaceSupplementResult.nestedLibraries, projectHash);
-                        const { existing: replaceExisting } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+                        const { actualExisting: replaceExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
+                        clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
                         if (replaceExisting.length === 0) {
                             const { KNOWN_PLATFORM_VALUES } = await import('../core/platform.js');
                             const replaceCommitEntries = await fs.readdir(replaceCommitPath, { withFileTypes: true });
                             const replaceAvailablePlatforms = replaceCommitEntries
                                 .filter(e => e.isDirectory() && e.name !== '_shared' && KNOWN_PLATFORM_VALUES.includes(e.name))
                                 .map(e => e.name);
-                            warn(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 不支持 ${platforms.join('/')} 平台 [可用: ${replaceAvailablePlatforms.join(', ')}]`);
+                            warn(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 已按规则跳过平台 [${platforms.join('/')}], 可用平台 [${replaceAvailablePlatforms.join(', ')}]`);
                             const replaceLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
                             const replaceLib = registry.getLibrary(replaceLibKey);
                             if (replaceLib) {
                                 const unavailable = replaceLib.unavailablePlatforms || [];
-                                for (const p of platforms) {
-                                    if (!unavailable.includes(p) && !replaceAvailablePlatforms.includes(p))
-                                        unavailable.push(p);
+                                const missingRequested = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, replaceAvailablePlatforms, configVars).missingRequested;
+                                for (const requestedPlatform of missingRequested) {
+                                    if (!unavailable.includes(requestedPlatform))
+                                        unavailable.push(requestedPlatform);
                                 }
                                 registry.updateLibrary(replaceLibKey, { unavailablePlatforms: unavailable });
                             }
@@ -388,10 +581,7 @@ async function linkScope(params) {
                         tx.recordOp('replace', localPath, replaceCommitPath);
                         await linker.linkLib(localPath, replaceCommitPath, replaceExisting);
                         savedBytes += replaceSize;
-                        for (const platform of replaceExisting) {
-                            const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
-                            registry.addStoreReference(storeKey, projectHash);
-                        }
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, replaceExisting, projectHash, false);
                         if (replaceSupplementResult.downloaded.length > 0) {
                             success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - Store 已有，创建链接并补充平台 [${replaceExisting.join(', ')}]`);
                         }
@@ -402,22 +592,26 @@ async function linkScope(params) {
                     break;
                 }
                 case DependencyStatus.ABSORB: {
+                    const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
+                    const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
                     const storeCommitPath = path.join(storePath, dependency.libName, dependency.commit);
                     const { KNOWN_PLATFORM_VALUES } = await import('../core/platform.js');
                     const localDirEntries = await fs.readdir(localPath, { withFileTypes: true });
                     const localPlatforms = localDirEntries
                         .filter(entry => entry.isDirectory() && KNOWN_PLATFORM_VALUES.includes(entry.name))
                         .map(entry => entry.name);
-                    const finalPlatforms = localPlatforms.filter(p => finalLinkPlatforms.includes(p));
+                    const requestedTargets = [...new Set(requestedPlatforms.flatMap((platform) => getRequestedPlatformTargets(platform, dependency.sparse, configVars)))];
+                    const finalPlatforms = localPlatforms.filter((platform) => requestedTargets.includes(platform));
                     if (finalPlatforms.length === 0 && localPlatforms.length > 0) {
-                        warn(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 不支持 ${platforms.join('/')} 平台 [本地有: ${localPlatforms.join(', ')}]`);
+                        warn(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 已按规则跳过平台 [${platforms.join('/')}], 本地有 [${localPlatforms.join(', ')}]`);
                         const absorbLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
                         const absorbLib = registry.getLibrary(absorbLibKey);
                         if (absorbLib) {
                             const unavailable = absorbLib.unavailablePlatforms || [];
-                            for (const p of platforms) {
-                                if (!unavailable.includes(p) && !localPlatforms.includes(p))
-                                    unavailable.push(p);
+                            const missingRequested = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, localPlatforms, configVars).missingRequested;
+                            for (const requestedPlatform of missingRequested) {
+                                if (!unavailable.includes(requestedPlatform))
+                                    unavailable.push(requestedPlatform);
                             }
                             registry.updateLibrary(absorbLibKey, { unavailablePlatforms: unavailable });
                         }
@@ -448,6 +642,7 @@ async function linkScope(params) {
                         registry.addLibrary({
                             libName: dependency.libName, commit: dependency.commit, branch: dependency.branch,
                             url: dependency.url, platforms: absorbLinkPlatforms, size: absorbSize,
+                            isGeneral: false,
                             referencedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
                         });
                     }
@@ -511,6 +706,7 @@ async function linkScope(params) {
                                 registry.addLibrary({
                                     libName: dependency.libName, commit: dependency.commit, branch: dependency.branch,
                                     url: dependency.url, platforms: [GENERAL_PLATFORM], size: sharedSize,
+                                    isGeneral: true,
                                     referencedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
                                 });
                             }
@@ -527,7 +723,9 @@ async function linkScope(params) {
                     break;
                 case DependencyStatus.LINK_NEW: {
                     const linkNewCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                    const { missing } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+                    const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
+                    const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
+                    const { missingRequested: missing } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
                     const linkNewLibId = `${dependency.libName}@${dependency.commit}`;
                     if (missing.length > 0 && !skipAllDownloads && downloadConfirmedLibs.has(linkNewLibId)) {
                         info(`${dependency.libName} 缺少平台 [${missing.join(', ')}]，开始下载...`);
@@ -552,7 +750,9 @@ async function linkScope(params) {
                             hint(`  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
                         }
                         try {
-                            const filteredDownloaded = downloadResult.platformDirs.filter(p => missing.includes(p));
+                            const assessment = assessDownloadResult(missing, dependency.sparse, downloadResult, configVars);
+                            clearSatisfiedAutoUnavailablePlatforms(registry, dependency, assessment.satisfiedRequested);
+                            const filteredDownloaded = assessment.downloadedRequested;
                             if (filteredDownloaded.length > 0) {
                                 tx.recordOp('absorb', linkNewCommitPath, downloadResult.libDir);
                                 const linkNewAbsorbResult = await store.absorbLib(downloadResult.libDir, filteredDownloaded, dependency.libName, dependency.commit);
@@ -563,27 +763,14 @@ async function linkScope(params) {
                             await fs.rm(downloadResult.tempDir, { recursive: true, force: true }).catch(() => { });
                         }
                     }
-                    const { existing: linkNewExisting } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
-                    const isLinkNewGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
+                    const { actualExisting: linkNewExisting, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
+                    clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
+                    const isLinkNewGeneral = await resolveLibraryGeneralState(dependency);
                     if (isLinkNewGeneral) {
                         const sharedPath = path.join(linkNewCommitPath, '_shared');
                         tx.recordOp('link', localPath, sharedPath);
                         await linker.linkGeneral(localPath, sharedPath);
-                        const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, GENERAL_PLATFORM);
-                        const existingEntry = registry.getStore(storeKey);
-                        if (!existingEntry) {
-                            const integrity = await store.captureIntegrity(dependency.libName, dependency.commit, GENERAL_PLATFORM);
-                            registry.addStore({
-                                libName: dependency.libName, commit: dependency.commit, platform: GENERAL_PLATFORM,
-                                branch: dependency.branch, url: dependency.url, ...integrity,
-                                usedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                            });
-                        }
-                        else if (existingEntry.fileCount == null) {
-                            const integrity = await store.captureIntegrity(dependency.libName, dependency.commit, GENERAL_PLATFORM);
-                            registry.updateStore(storeKey, integrity);
-                        }
-                        registry.addStoreReference(storeKey, projectHash);
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], projectHash, true);
                         generalLibs.add(dependency.libName);
                         success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，创建链接`);
                     }
@@ -598,9 +785,10 @@ async function linkScope(params) {
                         const lnLib = registry.getLibrary(lnLibKey);
                         if (lnLib) {
                             const unavailable = lnLib.unavailablePlatforms || [];
-                            for (const p of platforms) {
-                                if (!unavailable.includes(p) && !availablePlatforms.includes(p))
-                                    unavailable.push(p);
+                            const missingRequested = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, availablePlatforms, configVars).missingRequested;
+                            for (const requestedPlatform of missingRequested) {
+                                if (!unavailable.includes(requestedPlatform))
+                                    unavailable.push(requestedPlatform);
                             }
                             registry.updateLibrary(lnLibKey, { unavailablePlatforms: unavailable });
                         }
@@ -609,29 +797,15 @@ async function linkScope(params) {
                     else {
                         tx.recordOp('link', localPath, linkNewCommitPath);
                         await linker.linkLib(localPath, linkNewCommitPath, linkNewExisting);
-                        for (const platform of linkNewExisting) {
-                            const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
-                            const existingPlatformEntry = registry.getStore(storeKey);
-                            if (!existingPlatformEntry) {
-                                const integrity = await store.captureIntegrity(dependency.libName, dependency.commit, platform);
-                                registry.addStore({
-                                    libName: dependency.libName, commit: dependency.commit, platform,
-                                    branch: dependency.branch, url: dependency.url, ...integrity,
-                                    usedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                });
-                            }
-                            else if (existingPlatformEntry.fileCount == null) {
-                                const integrity = await store.captureIntegrity(dependency.libName, dependency.commit, platform);
-                                registry.updateStore(storeKey, integrity);
-                            }
-                            registry.addStoreReference(storeKey, projectHash);
-                        }
-                        await registerSharedStore(dependency.libName, dependency.commit, dependency.branch, dependency.url);
+                        await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, linkNewExisting, projectHash, 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);
             await tx.save();
         }
         // 8. 并行处理 MISSING 依赖
@@ -658,47 +832,26 @@ async function linkScope(params) {
                     };
                     try {
                         const storeCommitPath = path.join(storePath, dependency.libName, dependency.commit);
-                        const { existing, missing } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+                        const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, configVars);
+                        const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
+                        const { actualExisting: existing, missingRequested: missing, satisfiedRequested, } = await resolveRequestedStoreState(dependency, requestedPlatforms, configVars);
+                        clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
                         if (missing.length === 0) {
                             pLog.info(`${dependency.libName} 所有平台已存在，直接链接...`);
                             tx.recordOp('link', localPath, storeCommitPath);
-                            await linker.linkLib(localPath, storeCommitPath, platforms);
-                            for (const platform of platforms) {
-                                const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
-                                if (!registry.getStore(storeKey)) {
-                                    const integrity = await store.captureIntegrity(dependency.libName, dependency.commit, platform);
-                                    registry.addStore({
-                                        libName: dependency.libName, commit: dependency.commit, platform,
-                                        branch: dependency.branch, url: dependency.url, ...integrity,
-                                        usedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                    });
-                                }
-                                registry.addStoreReference(storeKey, projectHash);
-                            }
-                            await registerSharedStore(dependency.libName, dependency.commit, dependency.branch, dependency.url);
-                            const dlLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
-                            if (!registry.getLibrary(dlLibKey)) {
-                                let totalSize = 0;
-                                for (const platform of platforms) {
-                                    totalSize += await store.getSize(dependency.libName, dependency.commit, platform);
-                                }
-                                registry.addLibrary({
-                                    libName: dependency.libName, commit: dependency.commit, branch: dependency.branch,
-                                    url: dependency.url, platforms, size: totalSize, referencedBy: [],
-                                    createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                });
-                            }
-                            pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 链接完成 [${platforms.join(', ')}]`);
-                            return { success: true, name: dependency.libName, downloadedPlatforms: platforms, skippedPlatforms: [] };
+                            await linker.linkLib(localPath, storeCommitPath, existing);
+                            await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, existing, projectHash, false);
+                            pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 链接完成 [${existing.join(', ')}]`);
+                            return { success: true, name: dependency.libName, downloadedPlatforms: existing, skippedPlatforms: [] };
                         }
                         const dlLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
                         const historyLib = registry.getLibrary(dlLibKey);
-                        const unavailablePlatforms = historyLib?.unavailablePlatforms || [];
+                        const unavailablePlatforms = blockedPlatforms;
                         const dlToDownload = missing.filter(p => !unavailablePlatforms.includes(p));
                         const knownUnavailable = missing.filter(p => unavailablePlatforms.includes(p));
                         if (dlToDownload.length === 0) {
                             if (knownUnavailable.length > 0) {
-                                pLog.warn(`${dependency.libName} 平台 [${knownUnavailable.join(', ')}] 不支持（远程不存在）`);
+                                pLog.warn(`${dependency.libName} 平台 [${knownUnavailable.join(', ')}] 已按规则跳过`);
                             }
                             return { success: false, name: dependency.libName, skipped: true, skippedPlatforms: missing, unsupported: true };
                         }
@@ -725,52 +878,31 @@ async function linkScope(params) {
                             pLog.hint(`  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
                         }
                         try {
-                            const isNewGeneral = (!dependency.sparse || isSparseOnlyCommon(dependency.sparse)) && downloadResult.platformDirs.length === 0;
-                            if (isNewGeneral) {
+                            const assessment = assessDownloadResult(dlToDownload, dependency.sparse, downloadResult, configVars);
+                            clearSatisfiedAutoUnavailablePlatforms(registry, dependency, assessment.satisfiedRequested);
+                            if (assessment.isPureGeneral) {
+                                upsertLibraryAvailability(dependency, {
+                                    platforms: [GENERAL_PLATFORM],
+                                    isGeneral: true,
+                                });
                                 tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
                                 await store.absorbGeneral(downloadResult.libDir, dependency.libName, dependency.commit);
                                 const sharedPath = path.join(storeCommitPath, '_shared');
                                 tx.recordOp('link', localPath, sharedPath);
                                 await linker.linkGeneral(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);
-                                    registry.addStore({
-                                        libName: dependency.libName, commit: dependency.commit, platform: GENERAL_PLATFORM,
-                                        branch: dependency.branch, url: dependency.url, ...integrity,
-                                        usedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                    });
-                                }
-                                registry.addStoreReference(storeKey, projectHash);
-                                const genLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
-                                if (!registry.getLibrary(genLibKey)) {
-                                    const sharedSize = await getDirSize(sharedPath);
-                                    registry.addLibrary({
-                                        libName: dependency.libName, commit: dependency.commit, branch: dependency.branch,
-                                        url: dependency.url, platforms: [GENERAL_PLATFORM], size: sharedSize,
-                                        referencedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                    });
-                                }
+                                await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, [GENERAL_PLATFORM], projectHash, true);
                                 generalLibs.add(dependency.libName);
                                 pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，下载完成`);
                                 return { success: true, name: dependency.libName, downloadedPlatforms: [GENERAL_PLATFORM], skippedPlatforms: [], isGeneral: true };
                             }
-                            const filteredDownloaded = downloadResult.platformDirs.filter(p => dlToDownload.includes(p));
-                            const newUnavailable = dlToDownload.filter(p => !filteredDownloaded.includes(p));
+                            const filteredDownloaded = assessment.downloadedRequested;
+                            const newUnavailable = assessment.unavailableRequested;
                             if (newUnavailable.length > 0) {
-                                const updateLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
-                                if (historyLib) {
-                                    const updatedUnavailable = [...new Set([...unavailablePlatforms, ...newUnavailable])];
-                                    registry.updateLibrary(updateLibKey, { unavailablePlatforms: updatedUnavailable });
-                                }
-                                else {
-                                    registry.addLibrary({
-                                        libName: dependency.libName, commit: dependency.commit, branch: dependency.branch,
-                                        url: dependency.url, platforms: [], size: 0, referencedBy: [],
-                                        unavailablePlatforms: newUnavailable,
-                                        createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                    });
-                                }
+                                const updatedUnavailable = [...new Set([...unavailablePlatforms, ...newUnavailable])];
+                                upsertLibraryAvailability(dependency, {
+                                    unavailablePlatforms: updatedUnavailable,
+                                    isGeneral: false,
+                                });
                                 pLog.warn(`${dependency.libName} 平台 [${newUnavailable.join(', ')}] 远程不存在，已记录`);
                             }
                             if (filteredDownloaded.length > 0) {
@@ -779,65 +911,18 @@ async function linkScope(params) {
                                 await registerNestedLibraries(downloadAbsorbResult.nestedLibraries, projectHash);
                             }
                             const linkPlatforms = [...existing, ...filteredDownloaded];
-                            const isDownloadGeneral = await store.isGeneralLib(dependency.libName, dependency.commit);
-                            if (isDownloadGeneral) {
-                                const sharedPath = path.join(storeCommitPath, '_shared');
-                                tx.recordOp('link', localPath, sharedPath);
-                                await linker.linkGeneral(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);
-                                    registry.addStore({
-                                        libName: dependency.libName, commit: dependency.commit, platform: GENERAL_PLATFORM,
-                                        branch: dependency.branch, url: dependency.url, ...integrity,
-                                        usedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                    });
-                                }
-                                registry.addStoreReference(storeKey, projectHash);
-                                const genLibKey2 = registry.getLibraryKey(dependency.libName, dependency.commit);
-                                if (!registry.getLibrary(genLibKey2)) {
-                                    const sharedSize = await getDirSize(sharedPath);
-                                    registry.addLibrary({
-                                        libName: dependency.libName, commit: dependency.commit, branch: dependency.branch,
-                                        url: dependency.url, platforms: [GENERAL_PLATFORM], size: sharedSize,
-                                        referencedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                    });
-                                }
-                                generalLibs.add(dependency.libName);
-                                pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - General 库，下载完成`);
-                                return { success: true, name: dependency.libName, downloadedPlatforms: [GENERAL_PLATFORM], skippedPlatforms: [], isGeneral: true };
-                            }
                             if (linkPlatforms.length === 0) {
-                                return { success: false, name: dependency.libName, skipped: true, skippedPlatforms: platforms };
+                                return {
+                                    success: false,
+                                    name: dependency.libName,
+                                    skipped: true,
+                                    skippedPlatforms: requestedPlatforms,
+                                };
                             }
                             tx.recordOp('link', localPath, storeCommitPath);
                             await linker.linkLib(localPath, storeCommitPath, linkPlatforms);
-                            for (const platform of linkPlatforms) {
-                                const storeKey = registry.getStoreKey(dependency.libName, dependency.commit, platform);
-                                if (!registry.getStore(storeKey)) {
-                                    const integrity = await store.captureIntegrity(dependency.libName, dependency.commit, platform);
-                                    registry.addStore({
-                                        libName: dependency.libName, commit: dependency.commit, platform,
-                                        branch: dependency.branch, url: dependency.url, ...integrity,
-                                        usedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                    });
-                                }
-                                registry.addStoreReference(storeKey, projectHash);
-                            }
-                            await registerSharedStore(dependency.libName, dependency.commit, dependency.branch, dependency.url);
-                            const finalLibKey = registry.getLibraryKey(dependency.libName, dependency.commit);
-                            if (!registry.getLibrary(finalLibKey)) {
-                                let totalSize = 0;
-                                for (const platform of linkPlatforms) {
-                                    totalSize += await store.getSize(dependency.libName, dependency.commit, platform);
-                                }
-                                registry.addLibrary({
-                                    libName: dependency.libName, commit: dependency.commit, branch: dependency.branch,
-                                    url: dependency.url, platforms: linkPlatforms, size: totalSize,
-                                    referencedBy: [], createdAt: new Date().toISOString(), lastAccess: new Date().toISOString(),
-                                });
-                            }
-                            const notLinkedPlatforms = platforms.filter((p) => !linkPlatforms.includes(p));
+                            await ensureLinkedRegistryState(dependency.libName, dependency.commit, dependency.branch, dependency.url, linkPlatforms, projectHash, false);
+                            const notLinkedPlatforms = resolveRequestedPlatformsByActual(requestedPlatforms, dependency.sparse, linkPlatforms, configVars).missingRequested;
                             pLog.success(`${dependency.libName} (${dependency.commit.slice(0, 7)}) - 下载完成 [${linkPlatforms.join(', ')}]`);
                             return { success: true, name: dependency.libName, downloadedPlatforms: linkPlatforms, skippedPlatforms: notLinkedPlatforms };
                         }
@@ -902,20 +987,22 @@ async function linkScope(params) {
         // 10. 同步 cache 文件
         await syncCacheFile(configPath);
         // 11. 构建返回结果
-        const primaryPlatform = platforms[0];
-        const linkedDeps = classified
-            .filter((c) => {
-            if (c.status === DependencyStatus.MISSING)
-                return downloadedLibs.includes(c.dependency.libName);
-            return true;
-        })
-            .map((c) => ({
-            libName: c.dependency.libName,
-            commit: c.dependency.commit,
-            platform: generalLibs.has(c.dependency.libName) ? GENERAL_PLATFORM : primaryPlatform,
-            linkedPath: path.relative(projectRoot, c.localPath),
-            scope,
-        }));
+        const linkedDeps = [];
+        for (const item of classified) {
+            if (item.status === DependencyStatus.MISSING && !downloadedLibs.includes(item.dependency.libName)) {
+                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,
+            });
+        }
         return {
             linkedDeps, nestedLinkedDeps, generalLibs, downloadedLibs, savedBytes, finalLinkPlatforms, stats,
         };
@@ -929,7 +1016,7 @@ async function linkScope(params) {
  * 执行链接操作
  */
 export async function linkProject(projectPath, options) {
-    const absolutePath = resolvePath(projectPath);
+    const { absolutePath, normalizedPath, configPath: discoveredConfigPath, } = await resolveProjectRootPath(projectPath);
     // === 阶段 1: 初始化 ===
     const cfg = await config.load();
     if (cfg?.logLevel)
@@ -939,7 +1026,7 @@ export async function linkProject(projectPath, options) {
     const concurrency = cfg?.concurrency ?? 5;
     const registry = getRegistry();
     await registry.load();
-    const existingProject = registry.getProjectByPath(absolutePath);
+    const existingProject = registry.getProjectByPath(normalizedPath);
     const rememberedPlatforms = existingProject?.platforms;
     // 确定平台列表
     let platforms;
@@ -976,7 +1063,7 @@ export async function linkProject(projectPath, options) {
         process.exit(EXIT_CODES.NOINPUT);
     }
     // 发现可选配置文件
-    const thirdpartyDir = path.join(absolutePath, '3rdparty');
+    const thirdpartyDir = path.join(normalizedPath, '3rdparty');
     const configDiscovery = await findAllCodepacConfigs(thirdpartyDir);
     let selectedOptionalConfigs = [];
     if (configDiscovery && configDiscovery.optionalConfigs.length > 0) {
@@ -1016,8 +1103,7 @@ export async function linkProject(projectPath, options) {
         }
     }
     // 查找主配置文件
-    const { findCodepacConfig } = await import('../core/parser.js');
-    const mainConfigPath = await findCodepacConfig(absolutePath);
+    const mainConfigPath = discoveredConfigPath;
     if (!mainConfigPath) {
         error(`找不到 codepac-dep.json 配置文件，已搜索: 3rdparty, .`);
         process.exit(EXIT_CODES.DATAERR);
@@ -1025,7 +1111,7 @@ export async function linkProject(projectPath, options) {
     // === 阶段 2: Submodule 检测 ===
     let selectedSubmodules = [];
     if (options.submodules !== false) {
-        const submoduleConfigs = await findSubmoduleConfigs(absolutePath);
+        const submoduleConfigs = await findSubmoduleConfigs(normalizedPath);
         if (submoduleConfigs.length > 0) {
             selectedSubmodules = await selectSubmodules(submoduleConfigs, options, existingProject?.submodules);
             // 为选中的 submodule 处理可选配置
@@ -1041,7 +1127,7 @@ export async function linkProject(projectPath, options) {
         }
     }
     // === 阶段 3: 规范化 + 事务准备 ===
-    const normalizedRoot = normalizeProjectRoot(absolutePath, mainConfigPath);
+    const normalizedRoot = normalizedPath;
     const wasNormalized = normalizedRoot !== absolutePath;
     if (wasNormalized) {
         info(`项目根目录规范化: ${absolutePath} → ${normalizedRoot}`);
@@ -1365,6 +1451,95 @@ 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) {
+    const registry = getRegistry();
+    const storeKey = registry.getStoreKey(libName, commit, platform);
+    const existingEntry = registry.getStore(storeKey);
+    if (!existingEntry) {
+        const integrity = await store.captureIntegrity(libName, commit, platform);
+        registry.addStore({
+            libName,
+            commit,
+            platform,
+            branch,
+            url,
+            ...integrity,
+            usedBy: [],
+            createdAt: new Date().toISOString(),
+            lastAccess: new Date().toISOString(),
+        });
+    }
+    else if (existingEntry.fileCount == null) {
+        const integrity = await store.captureIntegrity(libName, commit, platform);
+        registry.updateStore(storeKey, integrity);
+    }
+    if (projectHash) {
+        registry.addStoreReference(storeKey, projectHash);
+    }
+}
+async function syncLibraryInfo(libName, commit, branch, url, platforms, isGeneral) {
+    const registry = getRegistry();
+    const libKey = registry.getLibraryKey(libName, commit);
+    const existingLibrary = registry.getLibrary(libKey);
+    const normalizedPlatforms = [...new Set(platforms)];
+    let totalSize = 0;
+    for (const platform of normalizedPlatforms) {
+        totalSize += await store.getSize(libName, commit, platform);
+    }
+    if (!existingLibrary) {
+        registry.addLibrary({
+            libName,
+            commit,
+            branch,
+            url,
+            platforms: normalizedPlatforms,
+            size: totalSize,
+            isGeneral,
+            referencedBy: [],
+            createdAt: new Date().toISOString(),
+            lastAccess: new Date().toISOString(),
+        });
+        return;
+    }
+    registry.updateLibrary(libKey, {
+        branch: branch || existingLibrary.branch,
+        url: url || existingLibrary.url,
+        platforms: normalizedPlatforms,
+        size: totalSize,
+        isGeneral,
+        lastAccess: new Date().toISOString(),
+    });
+}
+async function resolveStoredPlatforms(libName, commit, fallbackPlatforms) {
+    const storePath = await config.getStorePath();
+    if (!storePath) {
+        return [...new Set(fallbackPlatforms)];
+    }
+    const commitPath = path.join(storePath, libName, commit);
+    try {
+        const entries = await fs.readdir(commitPath, { withFileTypes: true });
+        const storedPlatforms = entries
+            .filter(entry => entry.isDirectory() && KNOWN_PLATFORM_VALUES.includes(entry.name))
+            .map(entry => entry.name);
+        return storedPlatforms.length > 0 ? storedPlatforms : [...new Set(fallbackPlatforms)];
+    }
+    catch {
+        return [...new Set(fallbackPlatforms)];
+    }
+}
+async function ensureLinkedRegistryState(libName, commit, branch, url, platforms, projectHash, 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);
+    }
+    if (!isGeneral) {
+        await registerSharedStore(libName, commit, branch, url);
+    }
+    await syncLibraryInfo(libName, commit, branch, url, libraryPlatforms, isGeneral);
+}
 /**
  * 注册嵌套依赖到 Registry
  * absorbLib 递归吸收嵌套依赖时只做文件操作，此函数负责 Registry 注册
@@ -1405,6 +1580,7 @@ async function registerNestedLibraries(nestedLibraries, projectHash) {
                     url: '',
                     platforms: [GENERAL_PLATFORM],
                     size: nested.size,
+                    isGeneral: true,
                     referencedBy: [],
                     createdAt: new Date().toISOString(),
                     lastAccess: new Date().toISOString(),
@@ -1443,6 +1619,7 @@ async function registerNestedLibraries(nestedLibraries, projectHash) {
                     url: '',
                     platforms: nested.platforms,
                     size: nested.size,
+                    isGeneral: false,
                     referencedBy: [],
                     createdAt: new Date().toISOString(),
                     lastAccess: new Date().toISOString(),
@@ -1507,7 +1684,7 @@ export async function classifyLinkStatus(localPath, storeCommitPath, isGeneral,
  * @param configPath 配置文件路径
  * @param platforms 请求的平台列表
  */
-async function classifyDependencies(dependencies, projectPath, configPath, platforms) {
+async function classifyDependencies(dependencies, projectPath, configPath, platforms, vars) {
     const result = [];
     const thirdPartyDir = path.dirname(configPath);
     const storePath = await store.getStorePath();
@@ -1518,8 +1695,10 @@ async function classifyDependencies(dependencies, projectPath, configPath, platf
     for (const dep of dependencies) {
         const localPath = path.join(thirdPartyDir, dep.libName);
         const storeLibPath = store.getLibraryPath(storePath, dep.libName, dep.commit, primaryPlatform);
-        // 检查 Store 中是否有任意请求的平台（而非只检查主平台）
-        const { existing: rawExisting } = await store.checkPlatformCompleteness(dep.libName, dep.commit, platforms);
+        const blockedPlatforms = getBlockedRequestedPlatforms(getRegistry(), dep, platforms, vars);
+        const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
+        // 检查 Store 中是否有任意请求的平台（支持 sparse 承载目录）
+        const { actualExisting: rawExisting, satisfiedRequested, } = await resolveRequestedStoreState(dep, requestedPlatforms, vars);
         // 完整性校验：验证 existing 平台的文件完整性
         const { valid: verifiedExisting, corrupted } = await verifyExistingPlatforms(dep.libName, dep.commit, rawExisting);
         // 清除损坏的平台数据
@@ -1534,8 +1713,11 @@ async function classifyDependencies(dependencies, projectPath, configPath, platf
         }
         const existing = verifiedExisting;
         // 也检查是否为 General 库（有 _shared 且有内容）
-        const isGeneral = await store.isGeneralLib(dep.libName, dep.commit);
+        const isGeneral = await resolveLibraryGeneralState(dep);
         const inStore = existing.length > 0 || isGeneral;
+        if (satisfiedRequested.length > 0) {
+            clearSatisfiedAutoUnavailablePlatforms(getRegistry(), dep, satisfiedRequested);
+        }
         // 用于非 inStore 情况的本地路径状态检查
         const expectedTarget = isGeneral
             ? path.join(storePath, dep.libName, dep.commit, '_shared')
@@ -1617,15 +1799,17 @@ async function classifyDependencies(dependencies, projectPath, configPath, platf
 }
 async function supplementMissingPlatforms(dependency, platforms, registry, tx, options = {}) {
     const result = { downloaded: [], unavailable: [], nestedLibraries: [] };
+    const blockedPlatforms = getBlockedRequestedPlatforms(registry, dependency, platforms, options.vars);
+    const requestedPlatforms = platforms.filter((platform) => !blockedPlatforms.includes(platform));
     // 1. 检查平台完整性
-    const { missing } = await store.checkPlatformCompleteness(dependency.libName, dependency.commit, platforms);
+    const { missingRequested, satisfiedRequested } = await resolveRequestedStoreState(dependency, requestedPlatforms, options.vars);
+    const missing = missingRequested;
     if (missing.length === 0) {
+        clearSatisfiedAutoUnavailablePlatforms(registry, dependency, satisfiedRequested);
         return result;
     }
     // 2. 获取已知不可用平台
-    const libKey = registry.getLibraryKey(dependency.libName, dependency.commit);
-    const libInfo = registry.getLibrary(libKey);
-    const unavailablePlatforms = libInfo?.unavailablePlatforms || [];
+    const unavailablePlatforms = blockedPlatforms;
     // 3. 计算需要下载的平台（排除已知不可用的，除非强制下载）
     const toDownload = options.forceDownload
         ? missing
@@ -1633,7 +1817,7 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
     if (toDownload.length === 0) {
         // 所有缺失平台都是已知不可用的
         if (missing.length > 0) {
-            hint(`${dependency.libName} 平台 [${missing.join(', ')}] 远程不存在（已记录）`);
+            hint(`${dependency.libName} 平台 [${missing.join(', ')}] 已按规则跳过`);
         }
         result.unavailable = missing.filter((p) => unavailablePlatforms.includes(p));
         return result;
@@ -1655,18 +1839,20 @@ async function supplementMissingPlatforms(dependency, platforms, registry, tx, o
             hint(`  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
         }
         try {
-            // 5. 检查实际下载了什么
-            const downloaded = downloadResult.platformDirs.filter((p) => toDownload.includes(p));
+            // 5. 解释下载结果
+            const assessment = assessDownloadResult(toDownload, dependency.sparse, downloadResult, options.vars);
+            const downloaded = assessment.downloadedRequested;
             result.downloaded = downloaded;
+            clearSatisfiedAutoUnavailablePlatforms(registry, dependency, assessment.satisfiedRequested);
             // 6. 记录新发现的不可用平台
-            const notFound = toDownload.filter((p) => !downloaded.includes(p));
+            const notFound = assessment.unavailableRequested;
             if (notFound.length > 0) {
                 result.unavailable = notFound;
-                // 更新 LibraryInfo（如果存在）
-                if (libInfo) {
-                    const newUnavailable = [...new Set([...unavailablePlatforms, ...notFound])];
-                    registry.updateLibrary(libKey, { unavailablePlatforms: newUnavailable });
-                }
+                const newUnavailable = [...new Set([...unavailablePlatforms, ...notFound])];
+                upsertLibraryAvailability(dependency, {
+                    unavailablePlatforms: newUnavailable,
+                    isGeneral: false,
+                });
                 warn(`${dependency.libName} 平台 [${notFound.join(', ')}] 远程不存在，已记录`);
             }
             // 7. 吸收下载的内容到 Store（不做链接，由调用者负责）
@@ -1919,7 +2105,6 @@ async function linkNestedDependencies(dependencies, params) {
     const nestedTargetDir = path.join(thirdPartyDir, targetDir);
     const { tx, registry, projectHash, projectRoot, dryRun, download, generalLibs, downloadedLibs, nestedLinkedDeps } = options;
     const { platforms, vars } = context;
-    const primaryPlatform = platforms[0];
     for (const dep of dependencies) {
         const localPath = path.join(nestedTargetDir, dep.libName);
         const storePath = await store.getStorePath();
@@ -1938,18 +2123,18 @@ async function linkNestedDependencies(dependencies, params) {
         // 检查 Store 状态和历史记录
         const libKey = registry.getLibraryKey(dep.libName, dep.commit);
         const historyLib = registry.getLibrary(libKey);
-        const unavailablePlatforms = historyLib?.unavailablePlatforms || [];
+        const unavailablePlatforms = getBlockedRequestedPlatforms(registry, dep, platforms, vars);
         // 过滤掉已知不可用的平台
         const availablePlatforms = platforms.filter(p => !unavailablePlatforms.includes(p));
         const knownUnavailable = platforms.filter(p => unavailablePlatforms.includes(p));
         let storeHas = false;
         const existingPlatforms = [];
-        for (const p of availablePlatforms) {
-            if (await store.exists(dep.libName, dep.commit, p)) {
-                existingPlatforms.push(p);
-                storeHas = true;
-            }
+        const initialStoreState = await resolveRequestedStoreState(dep, availablePlatforms, vars);
+        existingPlatforms.push(...initialStoreState.actualExisting);
+        if (initialStoreState.satisfiedRequested.length > 0) {
+            clearSatisfiedAutoUnavailablePlatforms(registry, dep, initialStoreState.satisfiedRequested);
         }
+        storeHas = existingPlatforms.length > 0;
         // 完整性校验：验证 existing 平台的文件完整性（与 classifyDependencies 同逻辑）
         if (existingPlatforms.length > 0) {
             const { valid: verifiedPlatforms, corrupted } = await verifyExistingPlatforms(dep.libName, dep.commit, existingPlatforms);
@@ -1963,10 +2148,10 @@ async function linkNestedDependencies(dependencies, params) {
                 storeHas = verifiedPlatforms.length > 0;
             }
         }
-        let isGeneral = await store.isGeneralLib(dep.libName, dep.commit);
+        let isGeneral = await resolveLibraryGeneralState(dep);
         // 如果所有平台都已知不可用，跳过
         if (availablePlatforms.length === 0 && knownUnavailable.length > 0 && !isGeneral) {
-            warn(`${indent}  ${dep.libName} - 平台 [${knownUnavailable.join(', ')}] 不支持（远程不存在）`);
+            warn(`${indent}  ${dep.libName} - 平台 [${knownUnavailable.join(', ')}] 已按规则跳过`);
             continue;
         }
         // Store 没有，但本地是目录时，验证 commit 并尝试 absorb
@@ -2003,14 +2188,16 @@ async function linkNestedDependencies(dependencies, params) {
                                 sparse: dep.sparse,
                                 vars,
                             });
-                            if (downloadResult.platformDirs.length > 0) {
+                            const assessment = assessDownloadResult(availablePlatforms, dep.sparse, downloadResult, vars);
+                            clearSatisfiedAutoUnavailablePlatforms(registry, dep, assessment.satisfiedRequested);
+                            if (assessment.downloadedRequested.length > 0) {
                                 // 有平台内容 → 吸收平台目录，重新分类为平台库
                                 tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                                const nestedAbsorbResult = await store.absorbLib(downloadResult.libDir, downloadResult.platformDirs, dep.libName, dep.commit);
+                                const nestedAbsorbResult = await store.absorbLib(downloadResult.libDir, assessment.downloadedRequested, dep.libName, dep.commit);
                                 await registerNestedLibraries(nestedAbsorbResult.nestedLibraries, projectHash);
-                                existingPlatforms.push(...downloadResult.platformDirs);
+                                existingPlatforms.push(...assessment.downloadedRequested);
                                 isGeneral = false;
-                                info(`${indent}  ${dep.libName} - 补充平台内容 [${downloadResult.platformDirs.join(', ')}]`);
+                                info(`${indent}  ${dep.libName} - 补充平台内容 [${assessment.downloadedRequested.join(', ')}]`);
                             }
                             if (downloadResult.cleanedPlatforms.length > 0) {
                                 hint(`${indent}  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
@@ -2036,6 +2223,7 @@ async function linkNestedDependencies(dependencies, params) {
         if (localExists && (storeHas || isGeneral)) {
             const linkStatus = await classifyLinkStatus(localPath, storeCommitPath, isGeneral, existingPlatforms);
             if (linkStatus === 'linked') {
+                let linkedPlatforms = isGeneral ? [GENERAL_PLATFORM] : [...existingPlatforms];
                 // 已链接，但需要检查是否需要补充缺失平台（与顶层依赖逻辑一致）
                 if (!isGeneral) {
                     const supplementResult = await supplementMissingPlatforms(dep, platforms, registry, tx, { vars });
@@ -2052,6 +2240,7 @@ async function linkNestedDependencies(dependencies, params) {
                         }
                         // 合并所有平台并重新链接
                         const allPlatforms = [...existingPlatforms, ...supplementResult.downloaded];
+                        linkedPlatforms = allPlatforms;
                         if (!dryRun) {
                             tx.recordOp('link', localPath, storeCommitPath);
                             await linker.linkLib(localPath, storeCommitPath, allPlatforms);
@@ -2059,10 +2248,11 @@ async function linkNestedDependencies(dependencies, params) {
                         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 : primaryPlatform,
+                    platform: isGeneral ? GENERAL_PLATFORM : (linkedPlatforms[0] ?? availablePlatforms[0]),
                     linkedPath: path.relative(projectRoot, localPath),
                 });
                 if (!isGeneral) {
@@ -2094,6 +2284,7 @@ async function linkNestedDependencies(dependencies, params) {
                 const sharedPath = path.join(storeCommitPath, '_shared');
                 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({
@@ -2119,11 +2310,12 @@ async function linkNestedDependencies(dependencies, params) {
                 }
                 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: primaryPlatform,
+                    platform: allPlatforms[0],
                     linkedPath: path.relative(projectRoot, localPath),
                 });
                 success(`${indent}  ${dep.libName} - 链接完成 [${allPlatforms.join(', ')}]`);
@@ -2165,15 +2357,20 @@ async function linkNestedDependencies(dependencies, params) {
                 if (downloadResult.cleanedPlatforms.length > 0) {
                     hint(`${indent}  已过滤: ${downloadResult.cleanedPlatforms.join(', ')}`);
                 }
-                // 检测是否为 General 库（没有 sparse 配置，或 sparse 只有 common，且没有平台目录）
-                const isNewGeneral = (!dep.sparse || isSparseOnlyCommon(dep.sparse)) && downloadResult.platformDirs.length === 0;
-                if (isNewGeneral) {
+                const assessment = assessDownloadResult(availablePlatforms, dep.sparse, downloadResult, vars);
+                clearSatisfiedAutoUnavailablePlatforms(registry, dep, assessment.satisfiedRequested);
+                if (assessment.isPureGeneral) {
                     // General 库处理
+                    upsertLibraryAvailability(dep, {
+                        platforms: [GENERAL_PLATFORM],
+                        isGeneral: true,
+                    });
                     tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
                     await store.absorbGeneral(downloadResult.libDir, dep.libName, dep.commit);
                     const sharedPath = path.join(storeCommitPath, '_shared');
                     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
@@ -2185,66 +2382,42 @@ async function linkNestedDependencies(dependencies, params) {
                     });
                     success(`${indent}  ${dep.libName} - 下载完成 (General)`);
                 }
-                else if (downloadResult.platformDirs.length > 0) {
+                else if (assessment.downloadedRequested.length > 0) {
                     // 平台库处理
                     tx.recordOp('absorb', storeCommitPath, downloadResult.libDir);
-                    const nestedAbsorbResult = await store.absorbLib(downloadResult.libDir, downloadResult.platformDirs, dep.libName, dep.commit);
+                    const nestedAbsorbResult = await store.absorbLib(downloadResult.libDir, assessment.downloadedRequested, dep.libName, dep.commit);
                     await registerNestedLibraries(nestedAbsorbResult.nestedLibraries, projectHash);
                     tx.recordOp('link', localPath, storeCommitPath);
-                    await linker.linkLib(localPath, storeCommitPath, downloadResult.platformDirs);
+                    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({
                         libName: dep.libName,
                         commit: dep.commit,
-                        platform: primaryPlatform,
+                        platform: assessment.downloadedRequested[0],
                         linkedPath: path.relative(projectRoot, localPath),
                     });
                     // 检查并记录新发现的不可用平台
-                    const newUnavailable = availablePlatforms.filter(p => !downloadResult.platformDirs.includes(p));
+                    const newUnavailable = assessment.unavailableRequested;
                     if (newUnavailable.length > 0) {
                         const updatedUnavailable = [...new Set([...unavailablePlatforms, ...newUnavailable])];
-                        if (historyLib) {
-                            registry.updateLibrary(libKey, { unavailablePlatforms: updatedUnavailable });
-                        }
-                        else {
-                            registry.addLibrary({
-                                libName: dep.libName,
-                                commit: dep.commit,
-                                branch: dep.branch,
-                                url: dep.url,
-                                platforms: downloadResult.platformDirs,
-                                size: 0,
-                                referencedBy: [],
-                                unavailablePlatforms: newUnavailable,
-                                createdAt: new Date().toISOString(),
-                                lastAccess: new Date().toISOString(),
-                            });
-                        }
+                        upsertLibraryAvailability(dep, {
+                            unavailablePlatforms: updatedUnavailable,
+                            platforms: assessment.downloadedRequested,
+                            isGeneral: false,
+                        });
                         warn(`${indent}  ${dep.libName} 平台 [${newUnavailable.join(', ')}] 远程不存在，已记录`);
                     }
-                    success(`${indent}  ${dep.libName} - 下载完成 [${downloadResult.platformDirs.join(', ')}]`);
+                    success(`${indent}  ${dep.libName} - 下载完成 [${assessment.downloadedRequested.join(', ')}]`);
                 }
                 else {
                     // 所有请求的平台都不可用，记录到 registry
                     const newUnavailable = [...new Set([...unavailablePlatforms, ...availablePlatforms])];
-                    if (historyLib) {
-                        registry.updateLibrary(libKey, { unavailablePlatforms: newUnavailable });
-                    }
-                    else {
-                        registry.addLibrary({
-                            libName: dep.libName,
-                            commit: dep.commit,
-                            branch: dep.branch,
-                            url: dep.url,
-                            platforms: [],
-                            size: 0,
-                            referencedBy: [],
-                            unavailablePlatforms: newUnavailable,
-                            createdAt: new Date().toISOString(),
-                            lastAccess: new Date().toISOString(),
-                        });
-                    }
+                    upsertLibraryAvailability(dep, {
+                        unavailablePlatforms: newUnavailable,
+                        isGeneral: false,
+                    });
                     warn(`${indent}  ${dep.libName} - 下载成功但平台 [${availablePlatforms.join(', ')}] 不可用，已记录`);
                 }
                 // 清理临时目录