chore: initial commit

docs/engine-reference/godot/VERSION.md

@@ -0,0 +1,46 @@
+# Godot — Version Reference
+
+| Field | Value |
+|-------|-------|
+| **Engine Version** | 4.7.2-stable（2026-08-18 发布） |
+| **Project Pinned** | 2026-09-07 |
+| **LLM Knowledge Cutoff** | May 2025（训练数据覆盖 ~4.3/4.4） |
+| **Risk Level** | **MEDIUM**（2026-09-12 降级）——4.5→4.7 API 级破坏性变更已逐条核实（源：官方迁移指南），无一条破坏本项目架构契约；残余风险 = 4.8（dev 阶段）未来升级 + 未覆盖的运行期边角行为，代理写码规则不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 或 WebSearch 核实后再用 |
+| **Last Docs Verified** | 2026-09-12（4.5/4.6/4.7 迁移指南逐条核实 + 版本检查：4.7.2 仍为最新稳定版，4.8 仅 dev 快照） |
+
+## Post-Cutoff Version Timeline
+
+| Version | 发布 | 与本项目相关要点 |
+|---|---|---|
+| 4.4 | 2025-03（训练覆盖边缘） | — |
+| 4.5-stable | 2025-09-15 | stencil 效果、无障碍改进；4.5.2（2026-03-19）为末版维护；**逐条变更已核实（2026-09-12）** |
+| 4.6-stable | 2026-02 起（4.6.1 2026-02） | Modern 主题、flexible docks、编辑器 QoL；4.6.3 维护；**逐条变更已核实（2026-09-12）** |
+| **4.7-stable** | 2026-06（**4.7.2 = 2026-08-18，本项目锁定**） | 见下；**逐条变更已核实（2026-09-12）** |
+| 4.8 | dev 快照 1–4（开发中） | 无稳定版发布日期；稳定版发布后跑 `/setup-engine refresh` |
+
+## 4.7 与本项目相关的变更（已核实）
+
+- `Tween.tween_await()`（信号等待）——**不影响** B1"结算逻辑禁 await"约束（那是设计约束，非引擎限制）
+- Control `offset_transform_*`（平移/旋转/缩放 Control 而不影响容器布局）——D1 HUD 可用
+- DrawableTexture2D、AreaLight3D、HDR 输出、新 Asset Store——本项目暂不依赖
+- 2D：CollisionShape2D 单向碰撞方向属性、conic gradient、AtlasTexture 进 TextureRect
+- **GDScript 两条语义变化**（打包数组元素赋值不触发属性 setter；类型化返回覆盖必须显式 return）——详见 `current-best-practices.md`
+- **新项目默认值已变**（stretch mode `canvas_items`、aspect `expand`；4.6 起 Windows 驱动 D3D12）——详见 `current-best-practices.md`
+- Android/iOS/XR 增强——本项目 PC 先行，无关
+
+## Migration Guides（升级/写码前必读）
+
+- 4.7: https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html
+- 4.6 / 4.5 同路径模式：`.../tutorials/migrating/upgrading_to_godot_4.6.html`、`..._4.5.html`
+- 三份指南的逐条中文对照与项目相关性标注见 `breaking-changes.md`（2026-09-12 版）
+
+## Note
+
+**MEDIUM 风险处置（2026-09-12 更新）**：4.5→4.7 的 API 级破坏性变更清单已逐条核实并入 `breaking-changes.md`，deprecated → replacement 对照已并入 `deprecated-apis.md`；对本项目的结论 = **无一破坏 GDD 已锁架构契约**。残余风险两项：① 4.8 未来升级（dev 阶段，稳定版后 refresh）；② 运行期边角行为（迁移指南未覆盖的引擎内部行为差异）——代理写码规则保持不变：**不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 或 WebSearch 核实后再用**。
+
+## Verification History
+
+| 日期 | 动作 |
+|---|---|
+| 2026-09-07 | 初次锁定 4.7.2；核实版本时间线与 4.7 特性清单 |
+| 2026-09-12 | `/setup-engine refresh`：4.5/4.6/4.7 官方迁移指南逐条核实（breaking-changes.md 逐条清单 + deprecated-apis.md 对照表 + 新建 current-best-practices.md）；版本检查确认 4.7.2 仍为最新稳定版（4.8 仅 dev）；风险等级 HIGH → MEDIUM |

docs/engine-reference/godot/breaking-changes.md

@@ -0,0 +1,115 @@
+# Godot Breaking Changes（4.4 → 4.7）
+
+> **Last verified: 2026-09-12**（官方迁移指南三份逐条核实——4.5/4.6/4.7 API 级清单已补全，原 2026-09-07"待 refresh"状态解除）
+> 训练数据覆盖至 ~4.4：4.4 及以前的变更视为"已知基线"，4.5+ 为超出截止的增量。
+> 官方迁移指南（升级/写码前必读）：
+> - 4.5：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.5.html
+> - 4.6：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.6.html
+> - 4.7：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html
+>
+> 项目相关性图例：🔵 需要留意（本项目域内）/ ⚪ 本项目不用（3D/XR/网络/移动/GLTF/编辑器插件）。
+> 本项目形态：2D 回合制、GDScript 单语言、Control 重 UI、autoload + .tres、无 3D/物理/网络。
+
+## 4.5（2025-09-15）
+
+### API 级变更
+
+| 类/方法 | 变更 | GDScript 兼容 | 项目相关性 |
+|---|---|---|---|
+| `Resource.duplicate(true)` | 深复制**不再覆盖外部子资源**；旧行为需 `duplicate_deep(DEEP_DUPLICATE_ALL)` | 行为变更 | 🔵 D2 schema/表资源复制语义注意 |
+| `Node.set_name` | 参数 `String` → `StringName` | 兼容 | 🔵 |
+| `JSONRPC.set_scope` | 更名 `set_method` | ❌ | ⚪ |
+| `Node.get_rpc_config` | 更名 `get_node_rpc_config` | ❌ | ⚪（RPC 不用） |
+| `RenderingServer.instance_reset_physics_interpolation` | **移除** | ❌ | ⚪（3D 插值） |
+| `RenderingServer.instance_set_interpolated` | **移除** | ❌ | ⚪ |
+| TextServer/Font/CanvasItem/TextLine/TextParagraph 全部 draw 方法 | 新增可选 `oversampling` 参数 | 兼容 | 🔵 D1 自绘文字 |
+| `TextServerExtension` 四个 draw 虚方法 | 同上签名变化 | ❌（全不兼容） | ⚪（不实现 TextServer 扩展） |
+| `RichTextLabel.add_image`/`update_image` | `size_in_percent` → `width_in_percent` + `height_in_percent` | 兼容 | 🔵（低——富文本用图时） |
+| C# `RenderingDevice.Features.Address` | 更名 `BufferDeviceAddress` | 仅 C# | ⚪（C# 不用） |
+| GLTF Accessor/BufferView 十字段 | int32 → int64 / 枚举化 | 仅 C# | ⚪（GLTF 不用） |
+
+### 行为变更
+
+- **TileMapLayer 物理分块默认开启**；`get_coords_for_body_rid()` 返回值变化；需 4.4 精确行为设 `physics_quadrant_size=1` —— 🔵 若棋盘实现走 TileMapLayer（当前设计倾向自绘，未定）
+- 3D 模型导入 skeleton 行为修复（新文件新行为；旧文件需改 Import Naming Version）—— ⚪
+- Navigation 区域默认异步线程更新；navmesh 合并次序变化 —— ⚪（A2 用自研 BFS，不用 NavigationServer）
+- Jolt：`areas_detect_static_bodies` 设置移除 —— ⚪
+- `ProjectSettings.add_property_info()` 对缺失/非法键（含 `usage`）告警 —— 🔵（若程序化注册设置项）
+
+## 4.6（2026-02）
+
+### API 级变更
+
+| 类/方法 | 变更 | GDScript 兼容 | 项目相关性 |
+|---|---|---|---|
+| `FileAccess.get_as_text` | `skip_cr` 参数**移除** | ❌ | 🔵 文本读取路径 |
+| `FileAccess.create_temp` | `mode_flags` int → `ModeFlags` 枚举 | 兼容性检查变化 | 🔵 |
+| AnimationPlayer `assigned_animation`/`autoplay`/`current_animation` | `String` → `StringName`（`get_queue()`、`current_animation_changed` 信号参数同步） | ❌（类型不兼容） | 🔵 B5 期 |
+| SpringBoneSimulator3D 三个枚举 | 移至 `SkeletonModifier3D` | ❌ | ⚪ |
+| StreamPeerTCP / TCPServer | `disconnect_from_host`/`get_status`/`poll`、`is_connection_available`/`is_listening`/`stop` 上移至 `StreamPeerSocket`/`SocketServer` 基类 | 兼容（继承） | ⚪（网络不用） |
+| `Control.grab_focus`/`has_focus`、`LineEdit.edit`、`SplitContainer.clamp_split_offset`、`FileDialog.add_filter` | 新增可选参数 | 兼容 | 🔵 D1 |
+| EditorFileDialog | `add_side_menu` **移除**；17 方法 / 8 属性 / 4 信号并入 `FileDialog` 基类 | 兼容（继承） | ⚪（编辑器） |
+| `Performance.add_custom_monitor` | 新增可选 `type` 参数 | 兼容 | 🔵（调试遥测可选） |
+
+### 行为 / 格式变更
+
+- **TSCN 格式**：`load_steps` 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 变大（可 Project > Tools > Upgrade Project Files 预升级）—— 🔵
+- **Glow 默认值大改**（blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排）；Mobile 渲染器 glow 重写 —— 🔵 D1/B5 用 2D Glow 时注意视觉基底已变
+- AStar2D/AStar3D/AStarGrid2D：`from_id` 被禁用/固体时返回空路径 —— ⚪（自研 BFS）
+- **新项目默认值**：Windows 渲染驱动 D3D12；3D 物理引擎 Jolt —— 🔵 创建 project.godot 时须知（本项目 2D、无 3D 物理，渲染驱动选择归实现期 ADR）
+
+## 4.7（2026-06；4.7.2 = 本项目锁定版本）
+
+### API 级变更
+
+| 类/方法 | 变更 | GDScript 兼容 | 项目相关性 |
+|---|---|---|---|
+| **GDScript 语义 ①** | 打包数组元素赋值不再触发整属性 setter（GH-113228） | 语义变化 | 🔵 全部 .gd 代码 |
+| **GDScript 语义 ②** | 覆盖类型化返回方法：返回类型自动继承，必须显式 `return`（GH-115763） | 语义变化 | 🔵 全部 .gd 代码 |
+| `Object.is_class()` | 参数 `String` → `StringName` | 兼容 | 🔵 |
+| `PhysicsServer2D.body_set_shape_as_one_way_collision` | 新增可选 `direction`（= CollisionShape2D 单向碰撞方向属性的 server 层） | 兼容 | 🔵（已核实特性的 API 面） |
+| `PhysicsServer2DExtension._body_set_shape_as_one_way_collision` | 新增**必填** `direction` | ❌ | ⚪（不写 PhysicsServer 扩展） |
+| `CanvasItem` 线条绘制 | 不再自动加抗锯齿羽化；粗线需手动绘制（GH-105122） | 行为变更 | 🔵 D1 自绘 |
+| Input 设备 ID | 鼠标/键盘设备 ID `0` → `InputEvent.DEVICE_ID_MOUSE` / `DEVICE_ID_KEYBOARD` 常量 | 行为变更 | 🔵 D1 输入 |
+| `Control.accessibility_live` | 枚举类型 `DisplayServer.` → `AccessibilityServer.AccessibilityLiveMode` | 仅 C# 不兼容 | 🔵（低） |
+| RichTextLabel 图片参数 | `add_image`/`update_image` width/height int→float；`width_in_percent/height_in_percent` → `width_unit/height_unit`；常量 `UPDATE_WIDTH_IN_PERCENT` → `UPDATE_WIDTH_UNIT` | ❌（常量更名） | 🔵（低） |
+| `Animation.length` | 元数据 float → double | 仅 C# 不兼容 | 🔵（低，B5 期） |
+| AnimationNodeBlendSpace1D/2D | 布尔 `sync` 属性 → `SyncMode` 枚举（`sync_mode`） | 行为变更 | ⚪（3D 动画树） |
+| `Font.find_variation` / `TreeItem.select` / `ZIPPacker.start_file` / `Image.save_exr`×2 | 新增可选参数 | 兼容 | ⚪/🔵 |
+| `AudioEffectSpectrumAnalyzer.tap_back_pos` | **移除** | ❌ | ⚪（D4 Alpha 期若用频谱分析注意） |
+| `EditorSceneFormatImporter` 七常量 | 并入 `ImportFlags` 枚举 | 仅 C# 源不兼容 | ⚪ |
+| `EditorVCSInterface._commit` | 新增 `amend` 参数 | ❌ | ⚪ |
+| `OptimizedTranslation.generate` | 返回 void → bool | 仅 C# 二进制 | ⚪ |
+| `AudioStreamPlayer.area_mask` | 默认 1 → 0 | 行为变更 | ⚪（D4 Alpha 期注意） |
+
+### 行为 / 默认值变更
+
+- `LinearToSRGB` visual shader 不再 clamp 到 [0,1]（Mobile/Forward+）—— 🔵（若写 shader）
+- **新项目默认值**：stretch mode `disabled` → `canvas_items`、stretch aspect `keep` → `expand` —— 🔵 **创建 project.godot 时须知（训练数据默认值已过时）**
+- macOS 最低版本 10.13 → 11 —— ⚪
+- `LookAtModifier3D.relative` 默认 true → false —— ⚪
+- `ResourceImporterDynamicFont.hinting` 默认 1 → 3 —— 🔵（字体导入）
+- `rendering/reflections/sky_reflections/roughness_layers` 默认 7 → 8 —— ⚪（3D）
+
+## 已知基线（≤4.4，训练数据内，低风险）
+
+- 4.x 系列：Tween 一律经 `create_tween()` 获取（Tween 节点已废）；信号连接用 `Callable` 语法；`@onready`/`@export` 注解体系；int 恒 64 位（D2 R2 规约依赖此语义，4.x 内稳定）
+
+## 本项目影响评估（2026-09-12 复核）
+
+| 变更 | 影响 |
+|---|---|
+| 4.7 全部已核实特性 | 均为增量，无破坏 D2/A3 已批准规约的项 |
+| **4.5–4.7 逐条 API 变更** | **无一破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响） |
+| 需入编码规范的项 | GDScript 两条新语义（打包数组 setter / 显式 return）→ `current-best-practices.md` |
+| 需项目设置留意的项 | 新项目默认值已变（stretch mode / aspect / D3D12）→ `current-best-practices.md` |
+| `Resource.duplicate(true)` 语义收窄 | D2 表资源含外部子资源时的复制语义注意 |
+
+## Pending
+
+- [x] 4.4→4.5 breaking changes 逐条清单（2026-09-12 官方迁移指南）
+- [x] 4.5→4.6 breaking changes 逐条清单（2026-09-12 官方迁移指南）
+- [x] 4.6→4.7 breaking changes 逐条清单（2026-09-12 官方迁移指南）
+- [x] 各版本 deprecated → replacement 对照表（见 `deprecated-apis.md`，2026-09-12）
+- [ ] 4.8 逐条清单（当前仅 dev 快照；稳定版发布后跑 `/setup-engine refresh`）
+- [ ] modules/ 分域参考（按实现期需要建，非阻塞）

docs/engine-reference/godot/current-best-practices.md

@@ -0,0 +1,49 @@
+# Godot 当前最佳实践（4.7 视角，post-cutoff）
+
+> **Last verified: 2026-09-12**（源：官方迁移指南 4.5/4.6/4.7 逐条核实 + 4.7 release 页）
+> 用途：训练数据（~4.4）之后的实践差异速查。写码代理在以下事项上**不要**按训练数据默认值行事。
+
+## 1. 新建 project.godot 的默认值差异（最易踩坑）
+
+| 设置 | 训练数据默认（≤4.4） | 4.7 实际新项目默认 | 生效版本 |
+|---|---|---|---|
+| `display/window/stretch/mode` | `disabled` | `canvas_items` | 4.7（新项目） |
+| `display/window/stretch/aspect` | `keep` | `expand` | 4.7（新项目） |
+| `rendering/rendering_device/driver.windows` | Vulkan（Forward+） | D3D12 | 4.6（新项目） |
+| `physics/3d/physics_engine` | GodotPhysics3D | Jolt | 4.6（新项目；本项目 2D、无 3D 物理，无关） |
+
+本项目为 2D 棋盘 UI：stretch mode / aspect 的最终选择归渲染器实现期 ADR，但须知道**引擎新项目默认值已不是训练数据里的那个**——新建工程后检查这三项。
+
+## 2. GDScript 4.7 两条语义变化（建议入编码规范）
+
+1. **打包数组元素赋值不再触发属性 setter**（4.7，GH-113228）：`my_packed_array[i] = v` 不再调用所在对象的 property setter——依赖 setter 副作用的写法必须改为显式赋回 + 显式调用 setter。D2 schema 类若以 setter 做校验，注意此差异。
+2. **类型化返回的方法覆盖必须显式 `return`**（4.7，GH-115763）：覆盖带返回类型的方法时返回类型自动继承，缺少 return 直接报错（旧版隐式返回 null）——虚方法覆盖一律显式写 return。
+
+## 3. 资源与文件
+
+- `Resource.duplicate(true)`（4.5 起）：深复制**只覆盖内部子资源**，不再覆盖外部子资源；需旧行为用 `duplicate_deep(DEEP_DUPLICATE_ALL)`。D2 表资源含外部子资源时注意复制语义。
+- `FileAccess.get_as_text()` 的 `skip_cr` 参数已移除（4.6）——换行处理如需自定义须自行实现。
+- TSCN 格式（4.6）：`load_steps` 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 会变大（可 Project > Tools > Upgrade Project Files 预升级，减少一次性大 diff）。
+- `ProjectSettings.add_property_info()`（4.5）：对缺失/非法键（含 `usage`）告警；改用 `set_as_basic()` / `set_restart_if_changed()` / `set_as_internal()`。
+
+## 4. 2D / UI / 文本
+
+- `CanvasItem` 线条绘制**不再自动加抗锯齿羽化**（4.7）——粗线/描边需手动方案（D1 自绘棋盘格边框时注意）。
+- 输入设备 ID：比较输入来源时用 `InputEvent.DEVICE_ID_MOUSE` / `DEVICE_ID_KEYBOARD` 常量，**不要硬编码 0**（4.7）——D1 输入路由。
+- 字体导入 `hinting` 默认 1 → 3（4.7）；TextServer/Font/CanvasItem 全部 draw 方法新增可选 `oversampling` 参数（4.5）——自绘文字（数字标签）可显式控制过采样。
+- RichTextLabel 图片参数两轮变化：4.5 `size_in_percent` → `width_in_percent`+`height_in_percent`；4.7 → `width_unit`/`height_unit`（bool → `ImageUnit`），常量 `UPDATE_WIDTH_IN_PERCENT` → `UPDATE_WIDTH_UNIT`。
+- **Glow 默认值大改**（4.6）：blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排——2D 后处理发光的视觉基底已变，调参以 4.7 默认为起点。
+- `Control.grab_focus` / `has_focus` 新增可选参数（4.6，`hide_focus` / `ignore_hidden_focus`）——焦点可视化管理更细。
+
+## 5. 4.7 已核实新特性（本项目可用的增量）
+
+- `Tween.tween_await()`：信号等待语法糖——**注意** B1 结算逻辑禁 await 是设计约束（可回放步骤流），该 API 不改变该约束
+- Control `offset_transform_*`：平移/旋转/缩放 Control 不影响容器布局——D1 HUD 局部动效可用
+- CollisionShape2D 单向碰撞方向属性（+ `PhysicsServer2D.body_set_shape_as_one_way_collision` 的 `direction` 参数）——本项目棋盘非物理驱动，暂不依赖
+- conic gradient、AtlasTexture 进 TextureRect——D1 贴图/着色可选
+- DrawableTexture2D、AreaLight3D、HDR 输出、内置 VirtualJoystick、新 Asset Store——本项目暂不依赖
+- `Font.find_variation` 扩展（palette_index / custom_colors）、`TreeItem.select` 扩展——低相关
+
+## 6. 本项目不消费的域（相关变更可忽略）
+
+3D 渲染与物理（Jolt 行为变化 / SoftBody / WorldBoundary / SpringBone / LookAtModifier）、XR/OpenXR、网络（StreamPeerTCP/TCPServer 方法上移、RPC 更名）、GLTF 导入（int64 字段）、移动端导出（Android 模板结构变化、.NET 9）、编辑器插件 API（ImportFlags / VCS / ExportPlatform）。

docs/engine-reference/godot/deprecated-apis.md

@@ -0,0 +1,51 @@
+# Godot Deprecated APIs（Don't use X → Use Y）
+
+> **Last verified: 2026-09-12**
+> 4.5–4.7 移除/更名/签名变化对照已补全（源 = 官方迁移指南，2026-09-12 逐条核实）。仍不含 4.8（dev 阶段）。**不要向本表添加未经验证的条目。**
+
+## 4.7 release 页核实
+
+- 4.7 release 页未列出新的 API 弃用；完整清单以其迁移指南为准（已逐条核实，见下节）
+
+## 4.5–4.7 移除 / 更名 / 签名变化对照（源 = 官方迁移指南）
+
+| Don't use | Use | Since | GDScript 影响 | 项目相关性 |
+|---|---|---|---|---|
+| `RenderingServer.instance_reset_physics_interpolation()` | （无替代——API 移除） | 4.5 | ❌ 移除 | ⚪ |
+| `RenderingServer.instance_set_interpolated()` | （无替代——API 移除） | 4.5 | ❌ 移除 | ⚪ |
+| `JSONRPC.set_scope()` | `set_method()` | 4.5 | ❌ 更名 | ⚪ |
+| `Node.get_rpc_config()` | `get_node_rpc_config()` | 4.5 | ❌ 更名 | ⚪ |
+| `Node.set_name(name: String)` | `set_name(name: StringName)` | 4.5 | 兼容（自动转换） | 🔵 |
+| `TextServerExtension` 四个 draw 虚方法 | 签名新增 `oversampling` | 4.5 | ❌（虚方法覆盖不兼容） | ⚪ |
+| RichTextLabel `size_in_percent` 参数 | `width_in_percent` + `height_in_percent` | 4.5 | 兼容（参数拆分） | 🔵（低） |
+| `FileAccess.get_as_text(skip_cr)` | `get_as_text()`（**skip_cr 参数移除**） | 4.6 | ❌ 参数移除 | 🔵 |
+| `EditorFileDialog.add_side_menu()` | （无替代；EditorFileDialog 17 方法/8 属性/4 信号并入 `FileDialog`） | 4.6 | ❌ 移除 | ⚪ |
+| AnimationPlayer `assigned_animation` / `autoplay` / `current_animation`（String） | `StringName`（含 `get_queue()`、`current_animation_changed` 参数） | 4.6 | ❌ 类型不兼容 | 🔵（B5 期） |
+| SpringBoneSimulator3D 三个枚举 | `SkeletonModifier3D.BoneDirection` / `.RotationAxis` | 4.6 | ❌ | ⚪ |
+| `AudioEffectSpectrumAnalyzer.tap_back_pos` | （无替代——属性移除） | 4.7 | ❌ 移除 | ⚪（D4 期注意） |
+| AnimationNodeBlendSpace1D/2D `sync: bool` 属性 | `sync_mode: SyncMode` 枚举 | 4.7 | ❌ 属性类型变化 | ⚪ |
+| RichTextLabel `ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT` | `UPDATE_WIDTH_UNIT`；`width/height_in_percent` 参数 → `width/height_unit`（bool → `ImageUnit`） | 4.7 | ❌ 常量/参数更名 | 🔵（低） |
+| `Object.is_class("X")`（String 字面量） | `is_class(&"X")`（StringName） | 4.7 | 兼容 | 🔵 |
+| `EditorVCSInterface._commit()` | 签名新增 `amend` | 4.7 | ❌（虚方法覆盖不兼容） | ⚪ |
+| `PhysicsServer2DExtension._body_set_shape_as_one_way_collision()` | 签名新增必填 `direction` | 4.7 | ❌（虚方法覆盖不兼容） | ⚪ |
+| C# `RenderingDevice.Features.Address` | `BufferDeviceAddress` | 4.5 | 仅 C# | ⚪ |
+| GLTF Accessor/BufferView 十字段（int） | int64 / 强类型枚举 | 4.5 | 仅 C# | ⚪ |
+
+## 训练数据内基线（≤4.4，高置信，本项目相关）
+
+| Don't use | Use | Since | 备注 |
+|---|---|---|---|
+| `Tween` 节点 / `create_tween()` 以外的补间获取 | `create_tween()` / `tween_property()` | 4.0 | Tween 节点已移除 |
+| 旧式 `connect("sig", instance, "method")` | `signal.connect(callable)` | 4.0 | Callable 语法 |
+| `onready var` | `@onready var` | 4.0 | 注解体系 |
+| `export var` | `@export var` | 4.0 | |
+| `RandomNumberGenerator` 自建实例（玩法侧） | `RngService.open_stream(stream)` | 本项目 | D2 Rule 5（项目级禁令，非引擎弃用） |
+| `randomize()`（玩法代码） | 禁止——种子归 `RngService.set_master_seed()`（C2 调用） | 本项目 | D2 Rule 5 |
+| `yield` | `await` | 4.0 | 4.7 新增 `Tween.tween_await()`；但 B1 结算逻辑禁 await（设计约束） |
+
+## Pending
+
+- [x] 4.5 deprecated → replacement 对照（2026-09-12）
+- [x] 4.6 deprecated → replacement 对照（2026-09-12）
+- [x] 4.7 deprecated → replacement 对照（2026-09-12）
+- [ ] 4.8 对照（dev 阶段；稳定版发布后 `/setup-engine refresh`）