将 Godot 原生引导迁移到官方 C++ 绑定

使用固定版本 godot-cpp 替换手写 C ABI 引导并保留执行协议
采用 MSVC 与 CMake 构建，校验依赖归档和源码缓存
修复动态卸载时的实例绑定与单例包装生命周期
补充构建缓存测试、实机验收结果及分发文档

docs/project-memory/shared-memory/decision-log.md

@@ -6,6 +6,8 @@
 
 ## 2026-09-20 Godot 编辑器执行接入
 
+原生引导采用固定版本的官方 `godot-cpp` 和 MSVC x64 构建，绑定及 C++ runtime 静态链接。依赖归档和缓存源码须核验，安装目录仍只分发原生载荷及许可。EDITOR 阶段动态加载/卸载时显式清理 C++ 实例绑定与单例包装，保留纯 GDScript 的异步执行和原有协议；执行权限、项目身份与缓存归属继续由现有宿主处理。
+
 可用性边界按引擎区分：Cocos/Unity 保持不按工程类型过滤，Godot 仍绑定当前 Godot 项目，切项目撤销旧插件上下文；前端统一根据宿主投影启动插件。Runtime 工具目录只对 Godot 追加项目条件，编辑器说明沿用外置提示词及审核 Skill 参考。
 
 Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和不确定执行回执合同，编辑器实现留在 `plugins/agc-godot-editor`。用户选择 DLL 原件随 AGC 安装资源分发，并确认按编辑器实例在 AGC 私有缓存准备临时加载副本，以满足 Godot Windows 加载器的同目录 `~DLL` 写入要求；项目内不复制 DLL，只用受管 `.gdextension` 引导。Godot 自动 UID 伴生文件必须记录归属并在确认卸载后按内容匹配清理。工作区根不迁移到 Godot 子目录，原始项目配置与场景只通过明确编辑操作修改。完整合同及验证范围见 [Godot 编辑器插件接入](<../../technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md>)。

docs/project-memory/shared-memory/pitfalls.md

@@ -1,9 +1,9 @@
 # 踩坑与排障记录
 
-## Godot 原生插件在 MSVC C 模式下的对齐声明
+## Godot C++ 扩展构建与对象生命周期
 
-- `native.c` 若首先报 `max_align_t` 语法错误，后面的 `Storage`、`retained_script` 等未声明通常是连带错误。MSVC C 模式不提供该类型；ABI 存储使用 C11 `_Alignas(16)` 显式对齐并保持 128 字节容量，通过实际 MSVC DLL 构建验证，不逐条修补连带错误。
-- `No C compiler found` 则属于开发环境问题：先初始化 Visual Studio x64 开发环境，同时设置 PATH、INCLUDE 与 LIB，再运行构建。只把 `cl.exe` 所在目录加到 PATH 不足以提供头文件和链接库。
+- 原生引导通过官方 `godot-cpp` 管理 Variant、String 和 Ref，不自行维护 ABI 存储。Godot 类型必须在扩展终止回调内释放，不能依赖 DLL 静态对象析构；桥节点可能已经退出，应按实例 ID 核验存活再回调。
+- 正式 Windows 构建使用 CMake 的 Visual Studio x64 generator，并实际验证 MSVC 编译；不能用 GCC 成功替代 MSVC 验收。固定官方归档按 SHA256 校验，缓存源码被修改时拒绝构建并保留证据。
 
 ## Rust 同步回调的测试记录按线程隔离
 

docs/technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md

@@ -33,7 +33,10 @@ DLL 原件随 AGC 安装包放在插件资源目录中；Godot Windows 加载器
 
 ## 分发与描述文件
 
-- Windows 原生构建使用 x64 C11 编译器；MSVC 需先初始化 Visual Studio 的 x64 开发环境，以同时提供 PATH、INCLUDE 与 LIB。ABI 临时存储使用 128 字节、C11 `_Alignas(16)` 显式对齐，不依赖 MSVC C 模式未提供的 `max_align_t`；定向验证运行 `plugins/agc-godot-editor/native/gdextension/build.ps1 -Compiler cl.exe`。
+- 原生引导使用官方 `godot-cpp` 的 C++ 类型和初始化接口，不自行声明 Variant 存储或直接装配 ABI 函数指针。绑定源码固定到 `godot-4.5-stable` 的 `e83fd0904c13356ed1d4c3d09f8bb9132bdc6b77`，以该版本的稳定 API 构建并在 Godot 4.7.2 验证；产品最低版本仍为 4.7，因为嵌入脚本使用该版本能力。Windows x64 构建使用 Visual Studio C++、CMake 和 Python，静态链接绑定及 C++ runtime，用户无需这些构建工具。
+- 构建仅从已固定的官方归档获取绑定源码，并核对 SHA256；下载和生成内容只进入 `.build/`。CMake 构建包含引导源码、嵌入脚本、绑定版本/归档摘要和构建配置的身份指纹。许可证与来源继续随 DLL 分发，安装包不包含 SDK、源码缓存、生成绑定或构建工具。
+- C++ 状态仅在扩展有效期间持有 GDScript 引用和桥节点身份；终止回调先停用仍存活的桥，再释放绑定对象，不能让静态 Godot 对象析构晚于绑定退出。延迟 bootstrap、原生卸载、Node 已退出及同 PID 重连均须实测。受管文件、会话身份、协议、执行回执与不确定阻断沿用现有合同。
+- EDITOR 阶段晚加载不会取得 CORE 阶段终止回调；引导终止时须通过官方绑定接口解除 Node/GDScript 的实例包装回调，并完成单例包装清理。只移除 C++ 包装，不同步销毁仍在 GDScript 调用栈或等待 `queue_free` 的引擎对象；先用 Variant 保活脚本，再解除 Ref 和绑定，避免卸载 DLL 后跳到失效回调。
 
 - 安装资源布局为 `plugins/agc-godot-editor/native/gdextension/bin/win-x64/agc_godot_editor.dll`，邻接元数据记录协议、构建身份和 DLL SHA256。开发模式允许宿主提供仓库插件目录中的同结构产物；RPC 不接受自定义 DLL 候选。
 - 缓存根仅由宿主提供，为其私有配置目录下的 `godot-editor-runtime`；按 `PID + startedFileTime + buildId` 隔离，所有路径分量受控且拒绝链接/reparse point。复制前验证安装原件及元数据，缓存已有文件必须匹配来源、归属及 SHA，不能加载被替换的同名文件。受管描述同时保留原件与加载副本身份，重启恢复不得把工程给出的任意 DLL 路径当作受信任来源。
@@ -107,11 +110,13 @@ Windows x64、Godot 4.7.2 标准编辑器的本地实现验收通过。证据保
 
 ### 复验入口
 
-从仓库根运行，原生构建要求 Windows x64 C 编译器。先把 `AGC_GODOT_TEST_EXECUTABLE` 设置为待验证的标准 Godot 编辑器绝对路径；未设置时 headless 测试会跳过，不能视为实机通过。
+从仓库根运行，原生构建要求 Visual Studio 2022 C++ x64、CMake 3.25 及以上和 Python 3；通过 Visual Studio generator 自动选择完整编译环境。首次构建需访问固定的官方归档，校验后的依赖缓存支持离线复用；`build.ps1` 可用 `-CMake`、`-Python` 指定构建工具。先把 `AGC_GODOT_TEST_EXECUTABLE` 设置为待验证的标准 Godot 编辑器绝对路径；未设置时 headless 测试会跳过，不能视为实机通过。
 
 ```powershell
 powershell -NoProfile -File plugins/agc-godot-editor/native/gdextension/build.ps1
+python -X utf8 -B plugins/agc-godot-editor/native/gdextension/tests/test_dependencies.py
 node --test plugins/agc-godot-editor/native/gdextension/tests/native-smoke.test.mjs
+node --test plugins/agc-godot-editor/native/gdextension/tests/guide-examples.test.mjs
 cargo test --locked --manifest-path plugins/agc-godot-editor/native/godot-editor-bridge/Cargo.toml
 npm run agc:plugins:test
 cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --features cocos-editor-execute,unity-editor-execute,godot-editor-execute godot
@@ -124,3 +129,9 @@ git diff --check
 ```
 
 真实 GUI 使用 `native/godot-editor-bridge/examples/live_smoke.rs`；安装位置变更使用同目录的 `install_location_smoke.rs`。二者要求显式传入自有可丢弃工程、已打开编辑器 PID、可信安装 DLL、工程外私有缓存及 `--allow-fixture-mutations`，具体参数见源码用法。多实例验证分别传入两个工程和 PID，通过 `live_smoke` 的 `--hold-ms` 让加载时间重叠，同时核验原生模块路径。Runner 复验须经正式长度前缀 RPC、完整 ACK 和私有配置恢复路径，不能用原生示例替代 Runner 证据。
+
+### C++ 引导验收边界
+
+官方 C++ 绑定版已通过实际 MSVC 构建、原生/指南 headless 回归、Rust 缓存与连接回归、受管资源 staging 校验，以及同一 Godot 4.7.2 GUI 进程中的首次加载、执行、卸载和重新聚焦后的重连。DLL 的导入依赖只有 KERNEL32，生成 SDK/编译缓存不进入 staging；重复构建命中同一载荷身份，损坏归档和改动过的依赖缓存拒绝构建。验证中首次创建的空工程由 Godot 补写版本特征，按编辑器初始化后的基线确认插件运行不修改原有工程文件。
+
+GUI 自动聚焦若未触发扫描，会按原合同返回未派发错误；重新聚焦后再连接，不重放未知执行。此次 C++ 替换未重新运行完整 AGC 发布构建、真实 Provider 或安装包 UI 验证，前述旧版本证据不代替这些验收。