tanmi-dock 0.10.0-beta → 1.0.4

package/dist/commands/check.js

@@ -4,12 +4,16 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { Command } from 'commander';
-import { isCodepacInstalled } from '../core/codepac.js';
+import { checkCodepacEnvironment } from '../core/codepac.js';
 import { getDiskInfo, formatSize } from '../utils/disk.js';
 import * as config from '../core/config.js';
 import { getRegistry } from '../core/registry.js';
 import * as store from '../core/store.js';
-import { KNOWN_PLATFORM_VALUES } from '../core/platform.js';
+import { KNOWN_PLATFORM_VALUES, SHARED_PLATFORM } from '../core/platform.js';
+import { SpaceService } from '../core/space/service.js';
+import { CleanupJournal } from '../core/space/cleanup-journal.js';
+import { MigrationJournal } from '../core/space/migration-journal.js';
+import { withGlobalLock } from '../utils/global-lock.js';
 import { info, warn, success, error, hint, blank, title, separator, colorize, debug, } from '../utils/logger.js';
 import { selectWithCancel, checkboxWithCancel, confirmWithCancel, PROMPT_CANCELLED, } from '../utils/prompt.js';
 // ============ 命令创建 ============
@@ -27,7 +31,17 @@ export function createCheckCommand() {
 }
 // ============ 主流程 ============
 async function runCheck(options) {
-    const result = await collectAllIssues({ integrity: options.integrity });
+    if (options.dryRun) {
+        const cfg = await config.load({ migrate: false });
+        if (cfg && config.checkConfigVersion(cfg) === 'migrate') {
+            error('配置需要迁移；dry-run 不会修改配置，请先运行一次普通命令完成迁移');
+            return;
+        }
+    }
+    const result = await collectAllIssues({
+        integrity: options.integrity,
+        readOnly: options.dryRun,
+    });
     // JSON 输出
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -35,7 +49,8 @@ async function runCheck(options) {
     }
     // 渲染报告
     renderReport(result);
-    const hasIssues = result.summary.integrityIssues > 0;
+    const hasIntegrityIssues = result.summary.integrityIssues > 0;
+    const hasIssues = hasIntegrityIssues || result.summary.spaceIssues > 0;
     const hasEnvErrors = result.summary.envErrors > 0;
     // dry-run 模式
     if (options.dryRun) {
@@ -55,6 +70,10 @@ async function runCheck(options) {
     if (!hasIssues) {
         return;
     }
+    if (!hasIntegrityIssues) {
+        hint('空间差异需要通过详细检查确认，本次没有自动修改注册记录');
+        return;
+    }
     // --fix 模式：直接修复
     if (options.fix) {
         await fixAllIssues(result.integrity, { force: options.force });
@@ -65,12 +84,67 @@ async function runCheck(options) {
 }
 // ============ 数据收集 ============
 async function collectAllIssues(options) {
-    const environment = await checkEnvironment();
+    const environment = await checkEnvironment(options?.readOnly);
     const integrity = await checkIntegrity(options);
+    const space = { issues: [] };
+    try {
+        const registry = getRegistry();
+        await registry.load({ migrate: !options?.readOnly });
+        const storePath = await store.getStorePath();
+        debug(`[space] audit 开始: store=${storePath}, source=td-check`);
+        const snapshot = await new SpaceService(registry, storePath).buildSnapshot('audit');
+        space.snapshotId = snapshot.id;
+        space.totals = snapshot.totals;
+        space.issues = snapshot.issues;
+        const cleanupLogs = await CleanupJournal.inspectPending();
+        for (const journal of cleanupLogs.journals) {
+            const data = journal.getData();
+            space.issues.push({
+                kind: 'recovery-log',
+                id: { libName: 'cleanup-journal', commit: data.planId },
+                message: `存在待恢复清理日志，组状态: ${data.groups.map((group) => `${group.index}:${group.state}`).join(', ')}`,
+            });
+        }
+        for (const filePath of cleanupLogs.corruptedFiles) {
+            space.issues.push({
+                kind: 'recovery-log',
+                id: { libName: 'cleanup-journal', commit: path.basename(filePath) },
+                message: `清理日志损坏，已保留原文件: ${filePath}`,
+            });
+        }
+        try {
+            const migrations = await MigrationJournal.listPending();
+            for (const migration of migrations) {
+                const data = migration.getData();
+                space.issues.push({
+                    kind: 'recovery-log',
+                    id: { libName: 'migration-journal', commit: data.id },
+                    message: `存在待恢复迁移: ${data.sourcePath} -> ${data.destinationPath}，阶段 ${data.phase}`,
+                });
+            }
+        }
+        catch (migrationError) {
+            space.issues.push({
+                kind: 'recovery-log',
+                id: { libName: 'migration-journal', commit: 'corrupted' },
+                message: migrationError.message,
+            });
+        }
+        debug(`[space] audit 完成: snapshot=${snapshot.id}, physical=${snapshot.totals.physical.bytes}, registered=${snapshot.totals.registered.bytes}, difference=${snapshot.totals.differenceBytes}, issues=${space.issues.length}, pendingCleanupLogs=${cleanupLogs.journals.length}, corruptedCleanupLogs=${cleanupLogs.corruptedFiles.length}`);
+    }
+    catch (err) {
+        space.error = err.message;
+        debug(`[space] audit 失败: error=${space.error}`);
+    }
     // 计算汇总
     // 错误：检查项失败（ok === false），排除仅作为警告的项
     // 警告：目前只有 disk 有 warn 字段（空间 < 5GB 但不影响功能）
-    const envErrors = Object.values(environment).filter((c) => !c.ok).length;
+    const envErrors = [
+        environment.codepac,
+        environment.config,
+        environment.store,
+        environment.disk,
+    ].filter((c) => !c.ok).length;
     const envWarnings = environment.disk.warn ? 1 : 0;
     const integrityIssues = integrity.invalidProjects.length +
         integrity.danglingLinks.length +
@@ -78,33 +152,38 @@ async function collectAllIssues(options) {
         integrity.missingLibraries.length +
         integrity.staleReferences.length +
         integrity.corruptedStores.length;
-    const reclaimableSize = integrity.orphanLibraries.reduce((sum, lib) => sum + lib.size, 0);
+    const reclaimableSize = space.totals?.reclaimable.bytes
+        ?? integrity.orphanLibraries.reduce((sum, lib) => sum + lib.size, 0);
     return {
         environment,
         integrity,
+        space,
         summary: {
             envErrors,
             envWarnings,
             integrityIssues,
             reclaimableSize,
+            spaceIssues: space.issues.length,
         },
     };
 }
-async function checkEnvironment() {
+async function checkEnvironment(readOnly = false) {
+    const codepacEnvironment = await checkCodepacEnvironment();
     const result = {
-        codepac: { ok: false, message: '' },
+        codepac: { ok: false, message: '', details: codepacEnvironment },
         config: { ok: false, message: '' },
         store: { ok: false, path: '', message: '' },
         disk: { ok: false, free: 0, warn: false, message: '' },
     };
-    // 1. codepac
-    const hasCodepac = await isCodepacInstalled();
+    debug(`[check] 环境检测开始: cwd=${process.cwd()}, codepac=${codepacEnvironment.codepacCommand.ok}, git=${codepacEnvironment.git.ok}, gitLfs=${codepacEnvironment.gitLfs.ok}, version=${codepacEnvironment.codepacVersion.ok}`);
+    // 1. codepac / Git / Git LFS
     result.codepac = {
-        ok: hasCodepac,
-        message: hasCodepac ? '已安装' : '未安装，无法下载库',
+        ok: codepacEnvironment.ok,
+        message: formatCodepacEnvironmentMessage(codepacEnvironment),
+        details: codepacEnvironment,
     };
     // 2. 配置
-    const cfg = await config.load();
+    const cfg = await config.load({ migrate: !readOnly });
     result.config = {
         ok: !!cfg,
         message: cfg ? '已初始化' : '未初始化，运行 td init',
@@ -155,6 +234,7 @@ async function checkEnvironment() {
             message: '无法获取磁盘信息',
         };
     }
+    debug(`[check] 环境检测完成: codepacOk=${result.codepac.ok}, configOk=${result.config.ok}, storeOk=${result.store.ok}, diskOk=${result.disk.ok}, diskWarn=${result.disk.warn}`);
     return result;
 }
 async function checkIntegrity(options) {
@@ -171,7 +251,7 @@ async function checkIntegrity(options) {
     let storePath;
     try {
         registry = getRegistry();
-        await registry.load();
+        await registry.load({ migrate: !options?.readOnly });
         storePath = await store.getStorePath();
     }
     catch (err) {
@@ -340,7 +420,7 @@ async function checkIntegrity(options) {
     if (options?.integrity) {
         const stores = registry.listStores();
         for (const entry of stores) {
-            if (entry.fileCount != null) {
+            if (entry.fileCount != null && entry.contentHash) {
                 // 有 fileCount 的做 fullVerify
                 const expectedData = {
                     size: entry.size,
@@ -360,23 +440,17 @@ async function checkIntegrity(options) {
                 }
             }
             else {
-                // 无 fileCount 的做回填（captureIntegrity）
-                try {
-                    const integrity = await store.captureIntegrity(entry.libName, entry.commit, entry.platform);
-                    const storeKey = registry.getStoreKey(entry.libName, entry.commit, entry.platform);
-                    registry.updateStore(storeKey, {
-                        size: integrity.size,
-                        fileCount: integrity.fileCount,
-                        contentHash: integrity.contentHash,
-                    });
-                }
-                catch {
-                    debug(`[check] 回填完整性数据失败: ${entry.libName}:${entry.commit}:${entry.platform}`);
-                }
+                result.corruptedStores.push({
+                    libName: entry.libName,
+                    commit: entry.commit,
+                    platform: entry.platform,
+                    kind: 'missing_integrity_record',
+                    reason: 'missing integrity record',
+                    expected: { size: entry.size },
+                    actual: { fileCount: 0, size: 0 },
+                });
             }
         }
-        // 保存回填的数据
-        await registry.save();
     }
     return result;
 }
@@ -389,6 +463,7 @@ function renderReport(result) {
     separator();
     const env = result.environment;
     renderCheck('codepac', env.codepac.ok, env.codepac.message, false);
+    renderCodepacEnvironmentDetails(env.codepac.details);
     renderCheck('配置文件', env.config.ok, env.config.message, false);
     renderCheck('Store 目录', env.store.ok, env.store.message, false);
     renderCheck('磁盘空间', env.disk.ok, env.disk.message, env.disk.warn);
@@ -417,10 +492,28 @@ function renderReport(result) {
         ? '完整'
         : `${integ.corruptedStores.length} 个损坏的 Store 条目`, false);
     blank();
+    info('空间一致性');
+    separator();
+    if (result.space.error) {
+        renderCheck('空间审计', false, result.space.error, false);
+    }
+    else if (result.space.totals) {
+        const totals = result.space.totals;
+        renderCheck('空间审计', result.space.issues.length === 0, result.space.issues.length === 0
+            ? `实际占用 ${formatSize(totals.physical.bytes)}，登记容量一致`
+            : `${result.space.issues.length} 个差异，实际 ${formatSize(totals.physical.bytes)}，登记 ${formatSize(totals.registered.bytes)}`, false);
+        for (const issue of result.space.issues.slice(0, 20)) {
+            debug(`[space] audit 差异: kind=${issue.kind}, lib=${issue.id.libName}, commit=${issue.id.commit}, platform=${issue.platform ?? 'all'}, registered=${issue.registeredBytes ?? 'unknown'}, measured=${issue.measuredBytes ?? 'unknown'}, message=${issue.message}`);
+        }
+        if (result.space.issues.length > 20) {
+            debug(`[space] audit 差异省略: remaining=${result.space.issues.length - 20}`);
+        }
+    }
+    blank();
     separator();
     // 汇总
-    const { envErrors, envWarnings, integrityIssues, reclaimableSize } = result.summary;
-    if (envErrors === 0 && envWarnings === 0 && integrityIssues === 0) {
+    const { envErrors, envWarnings, integrityIssues, reclaimableSize, spaceIssues } = result.summary;
+    if (envErrors === 0 && envWarnings === 0 && integrityIssues === 0 && spaceIssues === 0) {
         success('系统健康，无问题');
     }
     else {
@@ -431,11 +524,55 @@ function renderReport(result) {
             parts.push(`${envWarnings} 个警告`);
         if (integrityIssues > 0)
             parts.push(`${integrityIssues} 个数据问题`);
+        if (spaceIssues > 0)
+            parts.push(`${spaceIssues} 个空间差异`);
         if (reclaimableSize > 0)
             parts.push(`可回收 ${formatSize(reclaimableSize)}`);
         warn(`发现问题: ${parts.join(', ')}`);
     }
 }
+function formatCodepacEnvironmentMessage(environment) {
+    if (environment.ok) {
+        return environment.codepacVersion.version || 'CodePac、Git、Git LFS 可用';
+    }
+    const failures = [];
+    if (!environment.codepacCommand.ok) {
+        failures.push('CodePac 命令缺失');
+    }
+    if (!environment.git.ok) {
+        failures.push(environment.git.version
+            ? `Git 版本不足(${environment.git.version} < ${environment.git.minimumVersion})`
+            : 'Git 不可用');
+    }
+    if (!environment.gitLfs.ok) {
+        failures.push('Git LFS 不可用');
+    }
+    if (environment.codepacCommand.ok && !environment.codepacVersion.ok) {
+        failures.push('codepac --version 执行失败');
+    }
+    return failures.join('；') || 'CodePac 环境不可用';
+}
+function renderCodepacEnvironmentDetails(environment) {
+    debug(`[check] CodePac 环境详情: commandOk=${environment.codepacCommand.ok}, gitVersion=${environment.git.version ?? 'unknown'}, gitOk=${environment.git.ok}, gitLfsOk=${environment.gitLfs.ok}, versionOk=${environment.codepacVersion.ok}`);
+    if (environment.ok) {
+        return;
+    }
+    if (!environment.codepacCommand.ok) {
+        warn(`  - CodePac 命令: ${environment.codepacCommand.message}`);
+    }
+    if (!environment.git.ok) {
+        warn(`  - Git: ${environment.git.message}`);
+    }
+    if (!environment.gitLfs.ok) {
+        warn(`  - Git LFS: ${environment.gitLfs.message}`);
+    }
+    if (environment.codepacCommand.ok && !environment.codepacVersion.ok) {
+        warn(`  - CodePac 版本命令: ${environment.codepacVersion.message}`);
+        if (environment.codepacVersion.error) {
+            debug(`[check] codepac --version 错误: ${environment.codepacVersion.error}`);
+        }
+    }
+}
 function renderCheck(name, ok, message, isWarning) {
     if (ok && !isWarning) {
         success(`[✓] ${name.padEnd(10)} ${message}`);
@@ -645,15 +782,68 @@ async function fixAllIssues(issues, options) {
     separator();
     info('正在修复...');
     blank();
+    await withGlobalLock(() => applyAllIssueFixes(issues));
+}
+function commitKey(libName, commit) {
+    return JSON.stringify([libName, commit]);
+}
+function buildCorruptedSelections(corrupted, includeShared) {
+    const grouped = new Map();
+    for (const item of corrupted) {
+        const key = commitKey(item.libName, item.commit);
+        const group = grouped.get(key) ?? {
+            id: { libName: item.libName, commit: item.commit },
+            platforms: new Set(),
+        };
+        if (!includeShared)
+            group.platforms.add(item.platform);
+        grouped.set(key, group);
+    }
+    return [...grouped.values()].map((group) => ({
+        id: group.id,
+        platforms: includeShared ? 'all' : [...group.platforms],
+        ...(includeShared ? { includeShared: true } : {}),
+    }));
+}
+async function executeRepairPlan(spaceService, executor, selections, options) {
+    if (selections.length === 0)
+        return null;
+    const plan = await spaceService.buildCleanupPlan({
+        reason: 'repair',
+        selections,
+        requireUnreferenced: options.requireUnreferenced,
+        allowUnknownContent: options.allowUnknownContent,
+    });
+    for (const warningMessage of plan.warnings)
+        warn(`[space] ${warningMessage}`);
+    debug(`[check] 调用统一清理执行器: category=${options.category}, plan=${plan.id}, selections=${selections.length}, groups=${plan.groups.length}, expected=${plan.expectedRelease.bytes}`);
+    if (plan.groups.length === 0)
+        return null;
+    const result = await executor.execute(plan);
+    debug(`[check] 清理执行返回: category=${options.category}, plan=${plan.id}, status=${result.status}, succeeded=${result.succeeded.length}, failed=${result.failed.length}, released=${result.released.bytes}`);
+    return result;
+}
+function resolvedIssueCount(result, issues) {
+    if (!result)
+        return 0;
+    return issues.filter((issue) => result.succeeded.some((group) => group.id.libName === issue.libName
+        && group.id.commit === issue.commit
+        && (group.platform == null || issue.platform == null || group.platform === issue.platform))).length;
+}
+async function applyAllIssueFixes(issues) {
     const registry = getRegistry();
     await registry.load();
     const storePath = await store.getStorePath();
+    const spaceService = new SpaceService(registry, storePath);
+    const executor = spaceService.createCleanupExecutor();
+    const recovered = await executor.recoverPending();
+    debug(`[check] 修复开始: invalidProjects=${issues.invalidProjects.length}, danglingLinks=${issues.danglingLinks.length}, orphanLibraries=${issues.orphanLibraries.length}, staleReferences=${issues.staleReferences.length}, corruptedStores=${issues.corruptedStores.length}, recovered=${recovered}`);
     let fixed = 0;
     // 1. 清理无效项目
     for (const p of issues.invalidProjects) {
         try {
             registry.removeProject(p.hash);
-            success(`[ok] 清理项目: ${p.path}`);
+            success(`清理项目: ${p.path}`);
             fixed++;
         }
         catch (err) {
@@ -678,23 +868,28 @@ async function fixAllIssues(issues, options) {
             error(`[err] 移除链接失败: ${link.path} - ${err.message}`);
         }
     }
-    // 3. 删除孤立库
-    for (const lib of issues.orphanLibraries) {
-        try {
-            await fs.rm(lib.path, { recursive: true, force: true });
-            // 如果删除后 libName 目录为空，也一并删除
-            const libDir = path.dirname(lib.path);
-            const remaining = await fs.readdir(libDir).catch(() => ['placeholder']);
-            if (remaining.length === 0) {
-                await fs.rm(libDir, { recursive: true, force: true }).catch(() => { });
-            }
-            success(`[ok] 删除孤立库: ${lib.libName}/${lib.commit.slice(0, 7)}`);
-            fixed++;
+    // 3. 删除孤立库。显式修复允许清理该版本中的未登记内容。
+    const orphanSelections = [...new Map(issues.orphanLibraries.map((lib) => [
+            commitKey(lib.libName, lib.commit),
+            { id: { libName: lib.libName, commit: lib.commit }, platforms: 'all' },
+        ])).values()];
+    try {
+        const result = await executeRepairPlan(spaceService, executor, orphanSelections, {
+            requireUnreferenced: true,
+            allowUnknownContent: true,
+            category: 'orphan-library',
+        });
+        fixed += resolvedIssueCount(result, issues.orphanLibraries);
+        for (const group of result?.succeeded ?? []) {
+            success(`[ok] 删除孤立库: ${group.id.libName}/${group.id.commit.slice(0, 7)}`);
         }
-        catch (err) {
-            error(`[err] 删除孤立库失败: ${lib.libName}/${lib.commit.slice(0, 7)} - ${err.message}`);
+        for (const failure of result?.failed ?? []) {
+            error(`[err] 删除孤立库失败: ${failure.id.libName}/${failure.id.commit.slice(0, 7)} - ${failure.message}`);
         }
     }
+    catch (err) {
+        error(`[err] 删除孤立库失败: ${err.message}`);
+    }
     // 4. 移除失效引用
     for (const ref of issues.staleReferences) {
         try {
@@ -718,35 +913,51 @@ async function fixAllIssues(issues, options) {
             error(`[err] 移除引用失败: ${ref.libKey} - ${err.message}`);
         }
     }
-    // 5. 清理损坏的 Store 条目
-    for (const item of issues.corruptedStores) {
+    // 5. 清理损坏的 Store 条目。共享冲突整版本处理，其他问题按平台处理。
+    const orphanKeys = new Set(issues.orphanLibraries.map((item) => commitKey(item.libName, item.commit)));
+    const sharedCorruptions = issues.corruptedStores.filter((item) => (item.kind === 'shared_platform_conflict' || item.platform === SHARED_PLATFORM)
+        && !orphanKeys.has(commitKey(item.libName, item.commit)));
+    const sharedCorruptionKeys = new Set(sharedCorruptions.map((item) => commitKey(item.libName, item.commit)));
+    const platformCorruptions = issues.corruptedStores.filter((item) => !orphanKeys.has(commitKey(item.libName, item.commit))
+        && !sharedCorruptionKeys.has(commitKey(item.libName, item.commit)));
+    for (const cleanup of [
+        {
+            items: issues.corruptedStores.filter((item) => sharedCorruptionKeys.has(commitKey(item.libName, item.commit))),
+            selections: buildCorruptedSelections(sharedCorruptions, true),
+            allowUnknownContent: false,
+            category: 'shared-corruption',
+        },
+        {
+            items: platformCorruptions,
+            selections: buildCorruptedSelections(platformCorruptions, false),
+            allowUnknownContent: false,
+            category: 'corrupted-platform',
+        },
+    ]) {
         try {
-            if (item.kind === 'shared_platform_conflict') {
-                const storeKeys = registry.getLibraryStoreKeys(item.libName, item.commit);
-                for (const storeKey of storeKeys) {
-                    registry.removeStore(storeKey);
-                }
-                const commitPath = path.join(storePath, item.libName, item.commit);
-                await fs.rm(commitPath, { recursive: true, force: true });
-                success(`[ok] 清理损坏 Store: ${item.libName}/${item.commit.slice(0, 7)} (移除整个 commit 缓存)`);
+            const result = await executeRepairPlan(spaceService, executor, cleanup.selections, {
+                requireUnreferenced: false,
+                allowUnknownContent: cleanup.allowUnknownContent,
+                category: cleanup.category,
+            });
+            fixed += resolvedIssueCount(result, cleanup.items);
+            for (const group of result?.succeeded ?? []) {
+                const suffix = group.platform ? `/${group.platform}` : ' (移除整个 commit 缓存)';
+                success(`清理损坏 Store: ${group.id.libName}/${group.id.commit.slice(0, 7)}${suffix}`);
             }
-            else {
-                const storeKey = registry.getStoreKey(item.libName, item.commit, item.platform);
-                registry.removeStore(storeKey);
-                const platformPath = path.join(storePath, item.libName, item.commit, item.platform);
-                await fs.rm(platformPath, { recursive: true, force: true });
-                success(`[ok] 清理损坏 Store: ${item.libName}/${item.commit.slice(0, 7)}/${item.platform}`);
+            for (const failure of result?.failed ?? []) {
+                error(`清理损坏 Store 失败: ${failure.id.libName}/${failure.id.commit.slice(0, 7)}/${failure.platform ?? 'all'} - ${failure.message}`);
             }
-            fixed++;
         }
         catch (err) {
-            error(`[err] 清理损坏 Store 失败: ${item.libName}/${item.commit.slice(0, 7)}/${item.platform} - ${err.message}`);
+            error(`清理损坏 Store 失败: category=${cleanup.category} - ${err.message}`);
         }
     }
     await registry.save();
     blank();
     separator();
     success(`修复完成: ${fixed} 个问题已解决`);
+    debug(`[check] 修复完成: fixed=${fixed}`);
 }
 // ============ 工具函数 ============
 async function getDirSizeRecursive(dirPath) {
@@ -791,6 +1002,9 @@ export async function verifyIntegrity() {
     const result = await collectAllIssues();
     renderReport(result);
 }
+export async function collectCheckResultForTest(options) {
+    return collectAllIssues(options);
+}
 /**
  * 修复问题（兼容旧 repair 命令）
  */
@@ -848,7 +1062,7 @@ export async function checkStoreIntegrity() {
                 });
             }
         }
-        if (entry.fileCount != null) {
+        if (entry.fileCount != null && entry.contentHash) {
             const expectedData = {
                 size: entry.size,
                 fileCount: entry.fileCount,
@@ -867,22 +1081,17 @@ export async function checkStoreIntegrity() {
             }
         }
         else {
-            // 无 fileCount 的做回填
-            try {
-                const integrity = await store.captureIntegrity(entry.libName, entry.commit, entry.platform);
-                const storeKey = registry.getStoreKey(entry.libName, entry.commit, entry.platform);
-                registry.updateStore(storeKey, {
-                    size: integrity.size,
-                    fileCount: integrity.fileCount,
-                    contentHash: integrity.contentHash,
-                });
-            }
-            catch {
-                debug(`[check] 回填完整性数据失败: ${entry.libName}:${entry.commit}:${entry.platform}`);
-            }
+            corrupted.push({
+                libName: entry.libName,
+                commit: entry.commit,
+                platform: entry.platform,
+                kind: 'missing_integrity_record',
+                reason: 'missing integrity record',
+                expected: { size: entry.size },
+                actual: { fileCount: 0, size: 0 },
+            });
         }
     }
-    await registry.save();
     return corrupted;
 }
 /**
@@ -894,30 +1103,42 @@ export async function checkStoreIntegrity() {
 export async function fixCorruptedStores(corrupted) {
     if (corrupted.length === 0)
         return;
+    await withGlobalLock(() => applyCorruptedStoreFixes(corrupted));
+}
+async function applyCorruptedStoreFixes(corrupted) {
     const registry = getRegistry();
     await registry.load();
     const storePath = await store.getStorePath();
-    for (const item of corrupted) {
-        try {
-            if (item.kind === 'shared_platform_conflict') {
-                const storeKeys = registry.getLibraryStoreKeys(item.libName, item.commit);
-                for (const storeKey of storeKeys) {
-                    registry.removeStore(storeKey);
-                }
-                const commitPath = path.join(storePath, item.libName, item.commit);
-                await fs.rm(commitPath, { recursive: true, force: true });
-                success(`[ok] 清理损坏 Store: ${item.libName}/${item.commit.slice(0, 7)} (移除整个 commit 缓存)`);
-            }
-            else {
-                const storeKey = registry.getStoreKey(item.libName, item.commit, item.platform);
-                registry.removeStore(storeKey);
-                const platformPath = path.join(storePath, item.libName, item.commit, item.platform);
-                await fs.rm(platformPath, { recursive: true, force: true });
-                success(`[ok] 清理损坏 Store: ${item.libName}/${item.commit.slice(0, 7)}/${item.platform}`);
-            }
+    const spaceService = new SpaceService(registry, storePath);
+    const executor = spaceService.createCleanupExecutor();
+    const recovered = await executor.recoverPending();
+    debug(`[check] 兼容修复入口开始: corruptedStores=${corrupted.length}, recovered=${recovered}`);
+    const sharedCorruptions = corrupted.filter((item) => item.kind === 'shared_platform_conflict' || item.platform === SHARED_PLATFORM);
+    const sharedCorruptionKeys = new Set(sharedCorruptions.map((item) => commitKey(item.libName, item.commit)));
+    const platformCorruptions = corrupted.filter((item) => !sharedCorruptionKeys.has(commitKey(item.libName, item.commit)));
+    for (const cleanup of [
+        {
+            selections: buildCorruptedSelections(sharedCorruptions, true),
+            allowUnknownContent: false,
+            category: 'shared-corruption',
+        },
+        {
+            selections: buildCorruptedSelections(platformCorruptions, false),
+            allowUnknownContent: false,
+            category: 'corrupted-platform',
+        },
+    ]) {
+        const result = await executeRepairPlan(spaceService, executor, cleanup.selections, {
+            requireUnreferenced: false,
+            allowUnknownContent: cleanup.allowUnknownContent,
+            category: cleanup.category,
+        });
+        for (const group of result?.succeeded ?? []) {
+            const suffix = group.platform ? `/${group.platform}` : ' (移除整个 commit 缓存)';
+            success(`清理损坏 Store: ${group.id.libName}/${group.id.commit.slice(0, 7)}${suffix}`);
         }
-        catch (err) {
-            error(`[err] 清理损坏 Store 失败: ${item.libName}/${item.commit.slice(0, 7)}/${item.platform} - ${err.message}`);
+        for (const failure of result?.failed ?? []) {
+            error(`清理损坏 Store 失败: ${failure.id.libName}/${failure.id.commit.slice(0, 7)}/${failure.platform ?? 'all'} - ${failure.message}`);
         }
     }
     await registry.save();