SCE 编辑器包修复工具

SCE 编辑器的更新器会根据本地 Update\\editor-*.spark.xd.com\\VERSION.JSON 判断某个依赖包是否已经安装。版本记录存在、但包目录不完整、下载成了错误变体或落入了客户端下载源时，编辑器可能出现模板、官方 API、GameSystemUI 控件或地形图标缺失。包修复工具用于在本机安全地检查并重置这些受控包。

工具有两个入口：

WinUI 独立工具：适合用户查看安装根目录、渠道、版本记录、缓存大小和异常提示。
CLI（SCEPackageRepair.Cli.exe）：适合 AI 工具、远程排查脚本和自动化流程。CLI 与 WinUI 共用同一套包白名单和路径计算逻辑。

在编辑器发布包中，这两个程序和 SCE.exe、TriggerMcpHost.exe、SCECrashHandler.exe 一样放在 version-<api> 目录中；它们属于与编辑器二进制/API 版本绑定的工具。启动分析工具仍放在安装根目录的 diagnostics 下，因为 Launcher 会从那里发现并启动它。

实际发布包中的可执行文件名以安装包为准；当前构建名称为 SCEPackageRepair.exe 和 SCEPackageRepair.Cli.exe。使用前可运行 --help 查看该版本支持的参数。

更新渠道边界

包检查、重置和历史缓存清理只接受名称匹配 editor-*.spark.xd.com 的编辑器通道。Update 下以 e. 开头的目录属于错误的客户端/旧下载源，不得作为编辑器包来源，也不会出现在正常渠道列表中。

WinUI 工具会把检测到的 e.* 目录单独列为异常下载源，并在用户确认后提供删除选项。CLI 可先只读检查，再显式删除：

powershell

SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" sources --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" remove-sources --all --json
SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" remove-sources --all --apply --json

remove-sources 默认仍是 dry-run。它只允许删除 Update 的直属 e.* 子目录，拒绝任意路径、重解析目录和非 e. 开头的目录；执行前同样要求关闭编辑器、更新器和下载子进程。

支持的包

包 ID	版本记录	可清理的物理缓存	特别说明
`editor_bcd`	是	首版不删除物理目录	只删除版本记录，保留当前渠道 `res\\editor`；重新下载时由更新器覆盖同名文件
`global_default`	是	当前编辑器渠道 `Update\\editor-*.spark.xd.com\\res\\_m\\maps\\global_default\\`（含各版本子目录）	触发器官方 API 和全局定义依赖此包
`gamesparkcore`	是	当前编辑器渠道 `Update\\editor-*.spark.xd.com\\res\\_m\\maps\\gamesparkcore\\`（含各版本子目录）	GameData 模板、基础 GameData 类型和场景列表相关资源
`gamesystemui`	是	当前编辑器渠道 `Update\\editor-*.spark.xd.com\\res\\_m\\maps\\gamesystemui\\`（含各版本子目录）	官方移动摇杆、技能摇杆、背包等 UI 数据
`lib_game_options`	是	当前编辑器渠道 `Update\\editor-*.spark.xd.com\\res\\_m\\maps\\script_libs\\lib_game_options\\`（含各版本子目录）	编辑器配置依赖；必须使用编辑器变体
`wasicoresdk`	是	当前编辑器渠道 `Update\\editor-*.spark.xd.com\\res\\_m\\wasm\\wasicoresdk\\`（含各版本子目录）	SDK 文档、Skill、模板和 AI 上下文等随版本发布的包内容

路径表是常见安装布局。工具应以当前渠道的版本记录和包清单计算实际路径，不要让调用者传入任意目录。

editor_bcd 暂时只重置版本记录，不要直接删除当前渠道的 res\\editor。该目录包含模型、材质、笔刷、预制件等编辑器资源；RenderPath 由独立的 engineres 包提供，也不应因为一次包修复被误删。重新下载是覆盖同名文件，不会自动移除包中已经不存在的旧文件。

操作语义

检查

list 为只读操作。它应报告：

编辑器安装根目录、更新渠道和 API 版本；
VERSION.JSON 的实际路径以及每个受控包的版本、variation 和包变体；
版本记录对应的物理目录、是否存在 editor 子目录、是否为 .pak 而不是散文件；
_m 下各历史版本目录及其占用空间；
“版本记录存在但目录缺失”“编辑器包没有 editor 目录”等异常。

重置并强制重下

reset 针对一个或多个受控包执行：

读取并校验版本记录，拒绝未知包 ID；
先生成 dry-run 计划，列出将修改的记录和将删除的受控缓存；
在真正修改前备份 VERSION.JSON；
对允许清理缓存的包删除其 _m 包缓存根目录及其中的历史版本；editor_bcd 只删除本地版本项；
成功后从 VERSION.JSON 移除对应本地版本项，让下一次更新流程重新下载。

默认应是 dry-run；只有用户明确要求应用时才传入 --apply。任何物理删除失败都不能继续写入版本记录。操作前必须关闭编辑器、更新器和下载子进程，否则应拒绝执行并报告占用进程。

示例（具体参数以 --help 为准）：

powershell

SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" list --json

SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" reset `
  --package lib_game_options `
  --package gamesparkcore `
  --package gamesystemui `
  --dry-run --json

SCEPackageRepair.Cli.exe --root "E:\\WasmSCE" reset `
  --package lib_game_options `
  --package gamesparkcore `
  --package gamesystemui `
  --package global_default `
  --package wasicoresdk `
  --apply --json

清理历史缓存

prune 只清理受控包在 _m 下不再被当前版本记录使用的旧版本，保留当前版本。它适合定期回收更新累积的硬盘空间；不会修改项目自己的 editor/data、ScopeData、AppBundle 或 ui 文件。若用户要解决当前包损坏，应使用 reset，不要只使用 prune。

操作日志与卡顿排查

WinUI 工具和 CLI 都会把包操作写成逐行 JSON 日志。优先查看安装根目录下的：

text

<安装根目录>\package-repair.log

如果安装根目录不可写，会回退到：

text

%LOCALAPPDATA%\SCE\PackageRepair\package-repair.log

日志会记录操作开始、每个包或异常下载源开始处理、处理结果、完成/失败、删除路径、释放字节数、VERSION.JSON 备份路径和异常信息。即使递归扫描或删除过程中进程提前退出，最后一条 package_started 或 source_started 也能帮助判断卡在哪个对象。

WinUI 的目录统计和删除已经放到后台任务执行；窗口会暂时禁用操作按钮，完成后再刷新状态，不应因为大缓存目录而长时间阻塞界面。若仍然崩溃，除该日志外还要保留 Windows 事件查看器中的 Application Error、.NET Runtime 和 Windows Error Reporting 记录，以及 C:\ProgramData\Microsoft\Windows\WER\ReportArchive\AppCrash_scepackagerepair_* 下的 Report.wer。

常见症状排查

这些判断是高概率线索，不是对自定义依赖库或项目数据的绝对结论。清理前先用 list --json 保存 JSON 报告。

A. 项目名称 `[nil]` 与配置名称 `[lib_game_options]` 不符

通常是 lib_game_options 错误下载成了客户端变体，而不是编辑器变体。检查更新目录中当前包的实际内容：

编辑器包应有 editor 文件夹；
客户端专用包没有 editor 文件夹；
如果当前包只是一个 .pak，而编辑器包应为散文件，也属于错误变体。

重置 lib_game_options 后重新启动更新流程。不要修改项目配置来掩盖包变体错误。

B. 数据编辑器报告项目没有正确的模板，或地形编辑器没有场景列表

先检查 gamesparkcore 包的 editor 目录中是否存在对应的模板 JSON。若模板来自自定义依赖库或项目自身，不能直接把问题归因于 gamesparkcore；沿着 JSON 的 $inherit 路径检查它实际继承的模板来源。地形编辑器没有场景列表、但数据编辑器能看到对应场景 JSON 时，gamesparkcore 是高概率嫌疑包。

同时检查 global_default 和 gamesystemui，因为类型/声明、生成的 UI 数据或依赖链问题可能让表面症状落在相邻包上。

C. 触发编辑器找不到任何官方 API

优先检查 global_default 的版本记录、包目录和变体。该包异常时，官方触发 API 的全局声明或 UI 元数据可能整体缺失。

D. 官方技能摇杆、物品栏或移动摇杆丢失

优先检查 gamesystemui。确认包不是空目录、错误渠道或不完整变体；必要时重置后再检查对应 GameSystemUI Page/控件。

E. 编译时找不到 `GameDataScene`、`GameDataUnit` 或其命名空间

当错误是“类型不存在”而不是“类型二义性”，优先检查 gamesparkcore 和 gamesystemui。不使用图形化编辑器、只用命令行和 AI 开发的项目，往往会把包问题延迟到编译或 patch 这些库的数据时才暴露。仍需排除项目引用、自定义依赖库和生成文件本身的问题。

F. 地形编辑器场景视图中的镜头、灯光指示器图标丢失

优先检查 editor_bcd。首版修复只清理该包在 VERSION.JSON 中的版本记录，保留 Res\\editor；更新器重新下载后再观察图标是否恢复。不要为此删除整个 Res\\editor，也不要把独立 engineres 的 RenderPath 当作 editor_bcd 缓存处理。

安全边界

包操作只允许预置包 ID，并且只处理 editor-*.spark.xd.com；不接受任意路径或通配符。
异常下载源删除只接受工具在 Update 直属目录中检测到的 e.* 名称，并再次校验完整路径和重解析属性。
默认 dry-run；真正删除必须显式 --apply，并输出结构化 JSON 结果。
修改前备份版本记录；建议保留最近几次备份。
编辑器、更新器或下载进程运行时拒绝操作。
不删除项目工作区中的 editor/data、ScopeData、AppBundle、ui 或 user_files。
不修改远端版本清单、服务器包或项目依赖声明。
editor_bcd 仅清版本记录；其他包的缓存删除也必须限制在工具计算出的 _m 子树内。

修复完成后，确认版本记录已移除、预期缓存已清理、Res\\editor 仍在，并在下一次启动更新器后检查新版本是否下载成功。若问题仍存在，再检查自定义依赖库、项目模板和对应日志，不要反复删除所有资源目录。

SCE 编辑器包修复工具 ​

更新渠道边界 ​

支持的包 ​

操作语义 ​

检查 ​

重置并强制重下 ​

清理历史缓存 ​

操作日志与卡顿排查 ​

常见症状排查 ​

A. 项目名称 [nil] 与配置名称 [lib_game_options] 不符 ​

B. 数据编辑器报告项目没有正确的模板，或地形编辑器没有场景列表 ​

C. 触发编辑器找不到任何官方 API ​

D. 官方技能摇杆、物品栏或移动摇杆丢失 ​

E. 编译时找不到 GameDataScene、GameDataUnit 或其命名空间 ​

F. 地形编辑器场景视图中的镜头、灯光指示器图标丢失 ​

安全边界 ​