docs: add editor scripting workflow docs

2026-04-03 16:19:06 +08:00
parent 0e04217662
commit d4d825e1b1
8 changed files with 536 additions and 0 deletions
--- a/docs/api/XCEngine/Editor/Application/GetScriptRuntimeStatus.md
+++ b/docs/api/XCEngine/Editor/Application/GetScriptRuntimeStatus.md
@@ -0,0 +1,68 @@
+# Application::GetScriptRuntimeStatus
+
+返回当前脚本运行时状态结构的只读引用。
+
+```cpp
+const EditorScriptRuntimeStatus& GetScriptRuntimeStatus() const;
+```
+
+## 返回内容
+
+返回值指向 `Application` 内部持有的 `m_scriptRuntimeStatus`，不会复制状态结构。
+
+当前结构体包括：
+
+- `backendEnabled`
+- `assembliesFound`
+- `runtimeLoaded`
+- `assemblyDirectory`
+- `statusMessage`
+
+字段的详细语义见 [EditorScriptRuntimeStatus](../Scripting/EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)。
+
+## 生命周期语义
+
+因为返回的是引用而不是快照，所以调用方需要把它当成“当前帧状态视图”而不是稳定持久对象。
+
+当前这些操作都会刷新或重置这份状态：
+
+- `InitializeScriptingRuntime(...)`
+- [ReloadScriptingRuntime](ReloadScriptingRuntime.md)
+- [RebuildScriptingAssemblies](RebuildScriptingAssemblies.md)
+- `SwitchProject(...)`
+- `ShutdownScriptingRuntime()`
+
+因此上层 UI 更适合“读取后立即渲染”，而不是长期缓存这份引用。
+
+## 当前使用方式
+
+这份状态当前最主要的用途不是给底层脚本系统消费，而是给编辑器 UI 做降级和提示判断，例如：
+
+- 当前是否应显示 `Reload Scripts`
+- 当前是否应显示 `Rebuild Scripts`
+- 当前没有脚本类可选时应提示“后端禁用”“程序集缺失”还是“运行时初始化失败”
+
+相关判断主要封装在 `ScriptComponentEditorUtils` 中。
+
+## 设计含义
+
+把脚本运行时状态作为一个轻量只读结构暴露出来，有两个直接好处：
+
+1. `Application` 仍然掌握真正的生命周期控制权
+2. Inspector / 菜单 / 按钮逻辑不需要了解 `MonoScriptRuntime` 的细节
+
+这让上层 UI 可以基于状态做产品化反馈，而不是直接探查底层脚本后端对象。
+
+## 当前限制
+
+- 这不是线程安全快照，应按主线程 / UI 线程读。
+- 状态里只保存“当前 editor 观察到的脚本可用性”，不是完整诊断报告。
+- 构建失败文本和 runtime 初始化失败文本都会复用 `statusMessage` 这一条字符串通道。
+
+## 相关文档
+
+- [Application](Application.md)
+- [ReloadScriptingRuntime](ReloadScriptingRuntime.md)
+- [RebuildScriptingAssemblies](RebuildScriptingAssemblies.md)
+- [EditorScriptRuntimeStatus](../Scripting/EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)
+- [ScriptComponentEditorUtils](../ComponentEditors/ScriptComponentEditorUtils/ScriptComponentEditorUtils.md)
--- a/docs/api/XCEngine/Editor/Application/RebuildScriptingAssemblies.md
+++ b/docs/api/XCEngine/Editor/Application/RebuildScriptingAssemblies.md
@@ -0,0 +1,98 @@
+# Application::RebuildScriptingAssemblies
+
+重建当前项目的 managed 脚本程序集，并在构建成功后立即重载脚本运行时。
+
+```cpp
+bool RebuildScriptingAssemblies();
+```
+
+## 前置条件
+
+- `Application` 已经持有有效 `EditorContext`
+- 当前项目路径非空
+
+如果这两个条件不满足，当前实现直接返回 `false`。
+
+## 当前行为
+
+当前实现的顺序是：
+
+1. 读取当前 project path
+2. 在启用 Mono scripting 的构建里，先调用 `ShutdownScriptingRuntime()`
+3. 调用 `EditorScriptAssemblyBuilder::RebuildProjectAssemblies(projectPath)`
+4. 如果构建失败，写入 `m_scriptRuntimeStatus.statusMessage` 并返回 `false`
+5. 如果构建成功，继续调用 [ReloadScriptingRuntime](ReloadScriptingRuntime.md)
+
+这意味着它的真实语义是：
+
+- 不是“只生成 dll”
+- 而是“先卸载当前 runtime 释放程序集锁，再构建，最后尝试切换到新 runtime”
+
+## 返回值语义
+
+返回值并不只代表“编译是否成功”。
+
+当前它表示的是：
+
+- 构建成功，且随后 `ReloadScriptingRuntime()` 也成功时，返回 `true`
+- 只要构建失败，或构建成功但 runtime 仍未成功装载，返回 `false`
+
+这一点很关键。比如：
+
+- `dotnet/csc` 构建成功了
+- 但生成后的程序集初始化 Mono runtime 失败了
+
+这种情况下该方法仍会返回 `false`。
+
+## 失败路径
+
+### 构建失败
+
+如果 `EditorScriptAssemblyBuilder::RebuildProjectAssemblies(...)` 返回失败：
+
+- 会把构建器返回的 `message` 写入 `m_scriptRuntimeStatus.statusMessage`
+- 会记录 scripting error 日志
+- 不会调用 `ReloadScriptingRuntime()`
+
+但这里要注意一个和旧文档不同的点：
+
+- 进入构建前已经执行过 `ShutdownScriptingRuntime()`
+- 因此失败后 editor 会处于“没有活动脚本 runtime，只保留失败状态消息”的状态
+- 它不会继续保留旧 runtime
+
+### Mono 后端未启用
+
+如果当前构建没有启用 `XCENGINE_ENABLE_MONO_SCRIPTING`：
+
+- 会写入“不包含 Mono scripting support”的状态消息
+- 直接返回 `false`
+
+## 与 `ReloadScriptingRuntime()` 的区别
+
+- `ReloadScriptingRuntime()` 只重扫并装载当前 `Library/ScriptAssemblies`
+- `RebuildScriptingAssemblies()` 会先卸载当前 runtime 以释放 `GameScripts.dll` 这类项目本地程序集的锁，再尝试重新生成这些程序集，最后进入 reload
+
+所以当 UI 上出现：
+
+- `Reload Scripts`
+- `Rebuild Scripts`
+
+它们并不是两个名字不同的同义按钮，而是两条不同的恢复链路。
+
+## 当前调用方
+
+当前这条 API 的直接上层主要是脚本相关 UI，例如：
+
+- `ScriptComponentEditor`
+- `ProjectCommands`
+- `MainMenuActionRouter`
+
+它们通常会在“当前没有成功加载脚本程序集，但后端可用”时开放这个入口。
+
+## 相关文档
+
+- [Application](Application.md)
+- [ReloadScriptingRuntime](ReloadScriptingRuntime.md)
+- [GetScriptRuntimeStatus](GetScriptRuntimeStatus.md)
+- [EditorScriptAssemblyBuilder](../Scripting/EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md)
+- [EditorScriptRuntimeStatus](../Scripting/EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)
--- a/docs/api/XCEngine/Editor/Application/ReloadScriptingRuntime.md
+++ b/docs/api/XCEngine/Editor/Application/ReloadScriptingRuntime.md
@@ -0,0 +1,92 @@
+# Application::ReloadScriptingRuntime
+
+重新从当前项目的 `Library/ScriptAssemblies` 装载 Editor 脚本运行时。
+
+```cpp
+bool ReloadScriptingRuntime();
+```
+
+## 前置条件
+
+- `Application` 已经持有有效 `EditorContext`
+- `EditorContext::GetProjectPath()` 非空
+
+如果当前还没有完成初始化，或者项目路径为空，当前实现会直接返回 `false`。
+
+## 当前行为
+
+`ReloadScriptingRuntime()` 本身很薄，它做的事情只有两步：
+
+1. 读取当前 project path
+2. 调用内部 `InitializeScriptingRuntime(projectPath)`
+
+真正的工作都在 `InitializeScriptingRuntime(...)` 里完成，而那个内部流程会先执行一次 `ShutdownScriptingRuntime()`。因此这不是“在旧 runtime 上增量刷新”，而是一次完整的“先卸下，再重新探测和装载”的重建过程。
+
+## 返回值语义
+
+当前返回值直接等于：
+
+```cpp
+m_scriptRuntimeStatus.runtimeLoaded
+```
+
+也就是说：
+
+- 成功装载 `MonoScriptRuntime` 并注册到 `ScriptEngine` 时返回 `true`
+- 只要最终没有可用 runtime，就返回 `false`
+
+## 失败路径
+
+### 程序集缺失
+
+如果当前项目的以下文件缺少任意一个：
+
+- `Library/ScriptAssemblies/XCEngine.ScriptCore.dll`
+- `Library/ScriptAssemblies/GameScripts.dll`
+- `Library/ScriptAssemblies/mscorlib.dll`
+
+当前实现会：
+
+1. 清掉旧 runtime
+2. 把 `assemblyDirectory` 写入状态
+3. 置 `backendEnabled = true`
+4. 置 `assembliesFound = false`
+5. 写入“程序集未找到”提示消息
+6. 把 `ScriptEngine` runtime 设为 `nullptr`
+
+结果是编辑器继续可用，但脚本类发现与脚本字段编辑会退化。
+
+### Mono 后端未启用
+
+如果当前构建没有启用 `XCENGINE_ENABLE_MONO_SCRIPTING`：
+
+- `backendEnabled = false`
+- `runtimeLoaded = false`
+- `statusMessage` 会说明该 editor build 不包含 Mono scripting support
+- 返回 `false`
+
+### runtime 初始化失败
+
+如果程序集存在，但 `MonoScriptRuntime::Initialize()` 失败：
+
+- 旧 runtime 已经被清掉
+- `statusMessage` 会保存底层错误文本
+- `ScriptEngine` 仍然保持 `nullptr`
+- 返回 `false`
+
+## 调用方影响
+
+这个方法的结果不会直接弹出错误框，而是通过 `EditorScriptRuntimeStatus` 暴露给上层 UI。当前主要消费方包括：
+
+- `ScriptComponentEditor`
+- `ScriptComponentEditorUtils`
+
+它们会据此决定是否显示 `Reload Scripts` / `Rebuild Scripts` 按钮，以及当前应展示什么提示文本。
+
+## 相关文档
+
+- [Application](Application.md)
+- [RebuildScriptingAssemblies](RebuildScriptingAssemblies.md)
+- [GetScriptRuntimeStatus](GetScriptRuntimeStatus.md)
+- [EditorScriptRuntimeStatus](../Scripting/EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)
+- [ScriptEngine](../../Scripting/ScriptEngine/ScriptEngine.md)
--- a/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md
+++ b/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md
@@ -0,0 +1,72 @@
+# EditorScriptAssemblyBuilder
+
+**命名空间**: `XCEngine::Editor::Scripting`
+
+**类型**: `class`
+
+**源文件**: `editor/src/Scripting/EditorScriptAssemblyBuilder.h`
+
+**描述**: 负责把 Editor 项目里的 C# 源码编译成 `Library/ScriptAssemblies` 下的脚本程序集。
+
+## 概述
+
+`EditorScriptAssemblyBuilder` 是当前 Editor 脚本工作流里真正执行“编译”的那一层。
+
+它会把两类源码分别编成：
+
+- `XCEngine.ScriptCore.dll`
+- `GameScripts.dll`
+
+并把结果统一落到：
+
+- `<project>/Library/ScriptAssemblies/`
+
+## 公开方法
+
+| 方法 | 说明 |
+|------|------|
+| [RebuildProjectAssemblies](RebuildProjectAssemblies.md) | 全量重建项目脚本程序集并返回结果消息。 |
+
+这是当前唯一入口。返回 `EditorScriptAssemblyBuildResult`：
+
+- `succeeded`
+- `message`
+
+## 当前重建流程
+
+按 `EditorScriptAssemblyBuilder.cpp` 当前实现，主流程大致是：
+
+1. 校验项目路径非空。
+2. 解析仓库根与 Mono 根目录。
+3. 创建 `<project>/Library/ScriptAssemblies`。
+4. 在 `PATH` 上查找 `dotnet.exe`。
+5. 运行 `dotnet --list-sdks`，取最后一条 SDK 版本。
+6. 定位该 SDK 下的 `Roslyn/bincore/csc.dll`。
+7. 校验 `.NET Framework 4.7.2` 参考程序集存在。
+8. 收集 `managed/XCEngine.ScriptCore/**/*.cs`。
+9. 收集 `<project>/Assets/**/*.cs`。
+10. 若项目脚本为空，则生成 `Generated/EmptyProjectGameScripts.cs` 占位文件。
+11. 先编译 `XCEngine.ScriptCore.dll`。
+12. 仅当输出目录里还没有项目本地 `mscorlib.dll` 时，才从 Mono 目录复制一份；如果已经存在，则直接复用旧文件，避免在增量重建时覆盖仍可能被 Mono 映射的 corlib。
+13. 再引用 `XCEngine.ScriptCore.dll` 编译 `GameScripts.dll`。
+
+## 真实使用位置
+
+- `Application.cpp` 会在重建脚本程序集时调用它。
+- `tests/editor/test_editor_script_assembly_builder.cpp` 当前覆盖了两类关键语义：
+  - 成功路径：`XCEngine.ScriptCore.dll`、`GameScripts.dll` 与项目本地 `mscorlib.dll` 都会落到 `Library/ScriptAssemblies`
+  - 锁语义：如果活动 Mono runtime 仍持有已加载的 `GameScripts.dll`，直接重建会失败；释放 runtime 后再重建则可以成功并看到新增脚本类型
+
+## 当前实现边界
+
+- 当前是全量重建，不是增量编译。
+- 编译链明显依赖 Windows 路径和本机安装的 `dotnet` SDK。
+- 参考程序集路径当前写死在 `.NET Framework 4.7.2` 目录。
+- 构建器本身不会主动卸载当前脚本运行时；如果调用方没有先释放 Mono app domain，`GameScripts.dll` 仍可能因为文件锁而构建失败。
+- 若外部环境缺少 `dotnet.exe`、Roslyn 或参考程序集，返回的只是一条失败消息，而不是更复杂的恢复策略。
+
+## 相关文档
+
+- [Scripting](../Scripting.md)
+- [EditorScriptAssemblyBuilderUtils](../EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md)
+- [EditorScriptRuntimeStatus](../EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)
--- a/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/RebuildProjectAssemblies.md
+++ b/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/RebuildProjectAssemblies.md
@@ -0,0 +1,68 @@
+# EditorScriptAssemblyBuilder::RebuildProjectAssemblies
+
+**命名空间**: `XCEngine::Editor::Scripting`
+
+**类型**: `method`
+
+**源文件**: `editor/src/Scripting/EditorScriptAssemblyBuilder.h`
+
+## 签名
+
+```cpp
+static EditorScriptAssemblyBuildResult RebuildProjectAssemblies(const std::string& projectPath);
+```
+
+## 作用
+
+把指定项目下的托管脚本源码全量编译到 `Library/ScriptAssemblies` 目录，并返回成功/失败消息。
+
+## 当前实现行为
+
+### 1. 解析路径与外部工具
+
+- 要求 `projectPath` 非空，否则直接返回失败结果。
+- 会解析：
+  - 仓库根目录
+  - Mono 根目录
+  - `managed/XCEngine.ScriptCore`
+  - `<project>/Library/ScriptAssemblies`
+- 当前依赖系统 `PATH` 上可找到 `dotnet.exe`，并通过 `dotnet --list-sdks` 解析最新 SDK 版本，再定位对应 `Roslyn/bincore/csc.dll`。
+
+### 2. 校验引用与源文件
+
+- 校验 `.NET Framework 4.7.2` 参考程序集存在：
+  - `mscorlib.dll`
+  - `System.dll`
+  - `System.Core.dll`
+- 校验 Mono 自带 `binary/mscorlib.dll` 存在。
+- 收集两组 C# 源文件：
+  - `managed/XCEngine.ScriptCore/**/*.cs`
+  - `<project>/Assets/**/*.cs`
+- 若项目脚本为空，会生成 `Generated/EmptyProjectGameScripts.cs` 占位源码。
+
+### 3. 编译输出
+
+- 先编译 `XCEngine.ScriptCore.dll`。
+- 仅当输出目录里还没有项目本地 `mscorlib.dll` 时，才从 Mono 目录复制一份；如果已经存在，则直接复用旧文件。
+- 然后引用 `XCEngine.ScriptCore.dll` 编译 `GameScripts.dll`。
+- 成功时返回：
+  - `succeeded = true`
+  - `message = "Rebuilt script assemblies in ..."`
+
+### 4. 失败语义
+
+- 任意路径校验、进程启动、编译失败、首次 `mscorlib.dll` 复制失败，或目标程序集仍被活动 Mono runtime 持有时，都会返回 `succeeded = false`。
+- 这个函数本身不负责关闭现有脚本运行时；如果调用方在同一进程里仍持有已加载的 `GameScripts.dll`，重建可能因为文件锁失败。
+- 函数内部还包了一层 `try/catch`，用于把标准异常和未知异常转成失败消息。
+
+## 当前实现边界
+
+- 当前是全量重建，不做增量分析。
+- 平台和工具链路径明显偏向 Windows + 本机安装 `.NET SDK`。
+- 参考程序集版本当前固定为 `.NET Framework 4.7.2`。
+- 输出目录里的 `mscorlib.dll` 当前采用“首次复制、后续复用”的策略，不会在每次重建时强制覆盖。
+
+## 相关文档
+
+- [EditorScriptAssemblyBuilder](EditorScriptAssemblyBuilder.md)
+- [EditorScriptAssemblyBuilderUtils](../EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md)
--- a/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md
+++ b/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md
@@ -0,0 +1,48 @@
+# EditorScriptAssemblyBuilderUtils
+
+**命名空间**: `XCEngine::Editor::Scripting`
+
+**类型**: `utility header`
+
+**源文件**: `editor/src/Scripting/EditorScriptAssemblyBuilderUtils.h`
+
+**描述**: 提供脚本程序集构建流程使用的路径转换、源码收集、SDK 版本解析和空项目占位源码 helper。
+
+## 概述
+
+`EditorScriptAssemblyBuilderUtils.h` 是 [EditorScriptAssemblyBuilder](../EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md) 的一组纯 helper。
+
+它主要做四类小事：
+
+- 路径转 UTF-8
+- 递归收集 `.cs` 源码
+- 从 `dotnet --list-sdks` 输出里取最新 SDK 版本
+- 在项目没有脚本时生成一个可编译的占位源码文件
+
+## 公开函数
+
+| 函数 | 当前行为 |
+|------|------|
+| `ScriptBuilderPathToUtf8()` | 把 `filesystem::path` 转成 UTF-8 字符串。 |
+| `CollectCSharpSourceFiles()` | 递归收集指定根目录下所有 `.cs` 文件，并按路径排序。 |
+| `ParseLatestDotnetSdkVersion()` | 逐行扫描 `dotnet --list-sdks` 输出，返回最后一条版本号。 |
+| `EnsurePlaceholderProjectScriptSource()` | 当项目没有任何脚本时，创建 `EmptyProjectGameScriptsMarker` 占位源码。 |
+
+## 测试覆盖
+
+`tests/editor/test_editor_script_assembly_builder_utils.cpp` 当前已覆盖：
+
+- `.cs` 文件递归收集与排序
+- SDK 版本解析
+- 占位源码创建与幂等行为
+
+## 当前实现边界
+
+- `ParseLatestDotnetSdkVersion()` 默认把最后一条有效行视为最新 SDK，没有做语义化版本比较。
+- 占位脚本只服务于“项目没有任何脚本但仍需要产出 GameScripts.dll”这一特例。
+- 这组 helper 明显偏向当前构建器实现，并不是通用 C# 项目扫描库。
+
+## 相关文档
+
+- [Scripting](../Scripting.md)
+- [EditorScriptAssemblyBuilder](../EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md)
--- a/docs/api/XCEngine/Editor/Scripting/EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md
+++ b/docs/api/XCEngine/Editor/Scripting/EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md
@@ -0,0 +1,47 @@
+# EditorScriptRuntimeStatus
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `struct`
+
+**源文件**: `editor/src/Scripting/EditorScriptRuntimeStatus.h`
+
+**描述**: 汇总编辑器当前脚本后端、程序集发现和运行时加载状态的轻量状态对象。
+
+## 概述
+
+`EditorScriptRuntimeStatus` 是脚本相关 UI 和应用层之间的最小状态契约。它不负责构建程序集，也不负责执行脚本，只负责把当前脚本子系统是否可用描述清楚。
+
+## 字段
+
+| 字段 | 说明 |
+|------|------|
+| `backendEnabled` | 当前构建是否启用了脚本后端。 |
+| `assembliesFound` | 预期程序集目录里是否已经找到了脚本程序集。 |
+| `runtimeLoaded` | 运行时后端是否已经成功载入。 |
+| `assemblyDirectory` | 当前脚本程序集目录。 |
+| `statusMessage` | 面向 UI 的状态提示文本。 |
+
+## 真实使用位置
+
+- `Application` 持有一份当前状态并通过 `GetScriptRuntimeStatus()` 暴露出去。
+- `ScriptComponentEditor` 和 `ScriptComponentEditorUtils` 用它决定：
+  - 是否显示脚本不可用提示
+  - 是否允许 `Reload Scripts`
+  - 是否允许 `Rebuild Scripts`
+
+## 当前设计取向
+
+它刻意保持很轻：
+
+- 没有复杂错误码
+- 没有后端枚举
+- 没有状态机方法
+
+因为当前目的只是给 Inspector 和菜单层提供足够稳定、足够可展示的一份脚本状态快照。
+
+## 相关文档
+
+- [Scripting](../Scripting.md)
+- [Application](../../Application/Application.md)
+- [ScriptComponentEditorUtils](../../ComponentEditors/ScriptComponentEditorUtils/ScriptComponentEditorUtils.md)
--- a/docs/api/XCEngine/Editor/Scripting/Scripting.md
+++ b/docs/api/XCEngine/Editor/Scripting/Scripting.md
@@ -0,0 +1,43 @@
+# Scripting
+
+**命名空间**: `XCEngine::Editor::Scripting`
+
+**类型**: `submodule`
+
+**描述**: 编辑器侧脚本程序集构建与脚本运行时状态子模块，负责项目 C# 程序集重建和相关状态反馈。
+
+## 概述
+
+`editor/src/Scripting` 当前不是游戏运行时脚本系统本身，而是 Editor 为脚本工作流补的那一层工具能力。
+
+它主要回答两类问题：
+
+- 当前脚本后端和程序集是否可用
+- 项目 `Assets/**/*.cs` 如何重建成 `Library/ScriptAssemblies/*.dll`
+
+## 当前链路
+
+1. [EditorScriptAssemblyBuilder](EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md)
+   负责真正调用 `dotnet + csc.dll` 生成 `XCEngine.ScriptCore.dll` 与 `GameScripts.dll`
+2. [EditorScriptAssemblyBuilderUtils](EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md)
+   负责收集源码、解析 SDK 版本和兜底生成空脚本占位文件
+3. [EditorScriptRuntimeStatus](EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)
+   负责把“后端启用、程序集是否找到、运行时是否已加载、当前提示文本”等状态传给 UI
+
+## 真实调用关系
+
+- `Application.cpp` 在切项目和重载脚本运行时时更新 `EditorScriptRuntimeStatus`
+- `Application.cpp` 也会通过 `EditorScriptAssemblyBuilder` 触发脚本程序集重建
+- `ScriptComponentEditor` 与 `ScriptComponentEditorUtils` 会读取 runtime status，决定显示 `Rebuild Scripts` / `Reload Scripts` 按钮和提示文案
+
+## 当前实现边界
+
+- 这组代码明显面向 Windows 桌面开发环境，依赖 `dotnet.exe` 和本机参考程序集路径。
+- 它只管 Editor 侧程序集构建与状态反馈，不直接承载运行时脚本执行。
+
+## 相关文档
+
+- [Editor](../Editor.md)
+- [Application](../Application/Application.md)
+- [ScriptComponentEditor](../ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md)
+- [Scripting](../../Scripting/Scripting.md)