docs: update scripting API docs

docs/api/XCEngine/Scripting/ScriptComponent/ClearScriptClass.md

@@ -0,0 +1,32 @@
+# ScriptComponent::ClearScriptClass
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+void ClearScriptClass();
+```
+
+## 作用
+
+清空当前脚本组件的命名空间和类名绑定。
+
+## 当前实现行为
+
+- 内部等价于调用 `SetScriptClass(m_assemblyName, "", "")`。
+- 当前 `assemblyName` 会被保留。
+- 如果运行时正在运行且该组件原本已有脚本类，`ScriptEngine` 会收到类变化通知，并销毁旧跟踪实例。
+
+## 设计含义
+
+“清空绑定”不是单纯改两个字符串。对运行时来说，它意味着这个组件不再有可执行脚本类，应该停止继续调度生命周期。
+
+## 相关文档
+
+- [SetScriptClass](SetScriptClass.md)
+- [ScriptEngine::OnScriptComponentClassChanged](../ScriptEngine/OnScriptComponentClassChanged.md)

docs/api/XCEngine/Scripting/ScriptComponent/ScriptComponent.md

@@ -6,22 +6,25 @@
 
 **头文件**: `XCEngine/Scripting/ScriptComponent.h`
 
-**描述**: 挂在 `GameObject` 上的脚本绑定组件，负责保存脚本类标识、组件 UUID 和字段存储。
+**描述**: 挂在 `GameObject` 上的脚本绑定组件，负责保存脚本类标识、组件 UUID 和字段覆盖存储。
 
 ## 概览
 
-`ScriptComponent` 是脚本系统的数据入口。它本身不执行脚本逻辑，而是保存三类信息：
+`ScriptComponent` 是脚本系统的数据入口。它本身不执行托管代码，而是保存三类关键信息：
 
 - 这个组件绑定的是哪个程序集、命名空间和类。
 - 这个脚本组件自己的稳定 UUID。
 - 这份脚本实例的可持久化字段缓存 `ScriptFieldStorage`。
 
-这和 Unity 场景里挂着的 `MonoBehaviour` 序列化槽位很接近，但当前实现更明确地把“数据层”和“运行时实例层”拆开了。
+这和 Unity 场景里挂着的 `MonoBehaviour` 槽位很接近，但当前实现更明确地区分了“原生数据层”和“运行时实例层”。
 
 ## 生命周期
 
 - 构造时会生成一个非零随机 `scriptComponentUUID`。
 - 默认程序集名是 `GameScripts`。
+- 首次绑定脚本类时，会通知 `ScriptEngine::OnScriptComponentEnabled()`。
+- 已绑定脚本类发生变化时，会通知 `ScriptEngine::OnScriptComponentClassChanged()`，触发当前运行时实例停机并按新类重建。
+- `ClearScriptClass()` 会保留当前 `assemblyName`，只清空命名空间和类名。
 - 启用、禁用、销毁回调会直接转发给 `ScriptEngine`。
 - 序列化/反序列化会持久化 UUID、脚本类绑定和字段存储内容。
 
@@ -32,9 +35,9 @@
 
 ## 当前实现边界
 
-- `SetScriptClass()` 只有在“之前没有脚本类，现在有了”这个转换点，才会主动通知 `ScriptEngine::OnScriptComponentEnabled()`。
-- 单纯修改已有脚本类名，不会自动触发一轮完整的重绑定流程。
+- 只有 `SetScriptClass()` / `ClearScriptClass()` 会通知 `ScriptEngine`；`SetAssemblyName()`、`SetNamespaceName()`、`SetClassName()` 是纯字段写入，不会自动触发重绑定。
 - 反序列化使用引擎私有的分号分隔文本格式，不是通用 JSON/YAML。
+- `SetFieldStorage()` 直接整体覆盖本地字段缓存，不会自动把活体托管实例同步到同一状态。
 
 ## 常用访问器
 
@@ -43,7 +46,7 @@
 - `GetClassName()` / `SetClassName()`
 - `GetScriptComponentUUID()`
 
-这些访问器大多是简单内联函数，因此当前文档重点放在会改变生命周期或序列化语义的核心方法上。
+这些访问器大多是简单内联函数，因此文档重点放在会影响运行时重建、字段语义或序列化行为的方法上。
 
 ## 公开方法
 
@@ -51,6 +54,7 @@
 |------|------|
 | [Constructor](Constructor.md) | 创建组件并生成 UUID。 |
 | [SetScriptClass](SetScriptClass.md) | 设置脚本类绑定。 |
+| [ClearScriptClass](ClearScriptClass.md) | 清空脚本类绑定。 |
 | [HasScriptClass](HasScriptClass.md) | 判断当前是否已经绑定脚本类。 |
 | [GetFullClassName](GetFullClassName.md) | 返回带命名空间的完整类名。 |
 | [GetFieldStorage](GetFieldStorage.md) | 访问持久化字段缓存。 |
@@ -64,6 +68,7 @@
 
 - `engine/src/Scripting/ScriptComponent.cpp`
 - `tests/scripting/test_script_component.cpp`
+- `tests/scripting/test_script_engine.cpp`
 
 ## 相关文档
 

docs/api/XCEngine/Scripting/ScriptComponent/SetScriptClass.md

@@ -27,13 +27,17 @@ void SetScriptClass(
 
 - 两个重载都会先记录“之前是否已经有脚本类”。
 - 然后覆盖程序集名、命名空间和类名。
-- 只有在“之前没有脚本类，设置后有脚本类”时，才会主动调用 `ScriptEngine::Get().OnScriptComponentEnabled(this)`。
+- 如果“之前没有脚本类，设置后有脚本类”，会调用 `ScriptEngine::Get().OnScriptComponentEnabled(this)`。
+- 如果之前已经绑定脚本类，并且程序集名 / 命名空间 / 类名发生变化，会调用 `ScriptEngine::Get().OnScriptComponentClassChanged(this)`。
 
 ## 设计含义
 
-当前实现把“首次绑定脚本类”视作一个启用事件，但并没有把“换到另一个脚本类”也当成完整重建流程。这是一个当前版本的真实边界，用户不应该误以为修改类名会自动完成热切换。
+- 当前实现把“首次绑定脚本类”视作启用事件。
+- 已绑定类发生变化时，`ScriptEngine` 会停掉旧实例并按新类重新跟踪，这已经是当前实现的一部分。
+- 但 `SetAssemblyName()` / `SetNamespaceName()` / `SetClassName()` 这些原始 setter 不会触发同样的流程；需要真正重绑定时应走 `SetScriptClass()`。
 
 ## 相关文档
 
+- [ClearScriptClass](ClearScriptClass.md)
 - [HasScriptClass](HasScriptClass.md)
-- [OnEnable](OnEnable.md)
+- [ScriptEngine::OnScriptComponentClassChanged](../ScriptEngine/OnScriptComponentClassChanged.md)