196 lines
23 KiB
Markdown
196 lines
23 KiB
Markdown
# 文档 vs 代码 交叉审计报告
|
||
|
||
> **审计日期**：2026-07-20 · **复核日期**：2026-07-20
|
||
> **方法**：按子系统拆分为 6 个审计域并行核对，每条结论均带 `file:line` 证据。
|
||
> ✅ **已经对抗性复核**（6 个独立验证 agent 逐条重验，约 65 条主张零证伪）——结论与"代码 vs 文档 更优"判定见 **G 节**。正文中标 ⚠️**复核修正** 处为复核后订正。
|
||
> **范围**：`docs/` 下全部设计/技术/机制文档，对照 `scripts/`、`csharp/`、`data/`、`scenes/`、`addons/` 实际代码。
|
||
> **分类图例**：🟢 更优 IMPROVEMENT（开发中做了更好的选择）· 🔴 偏离 DRIFT（与文档不符）· 🟠 未实现 UNIMPLEMENTED（设计了但代码没有）· 📄 文档过期 DOC-STALE。
|
||
|
||
---
|
||
|
||
## A. 结论先行：当前**真实**运行的架构
|
||
|
||
文档描述的是设计蓝图；代码在开发中做了大量简化与技术转向。当前实际系统：
|
||
|
||
- **纯 GDScript 运行**。`csharp/` 下三个 C# 内核（`BulletManagerCs` / `EnemyManagerCs` / `SpatialGridCs`）**从未被实例化、从未进入场景树**——战斗热路径 100% 跑 GDScript 回退路径。文档 §4.5 / §6.1 描述的 C# 驱动 `_physics_process` + `AsSpan()` 零拷贝在代码中不存在。
|
||
- 证据：`project.godot:19-59` autoload 仅 `.gd`；`bullet_manager.gd:24`、`enemy_manager.gd:28`、`spatial_grid.gd:11` 的 `_cs_node` 恒为 `null`；全库无 `Cs.new()`。
|
||
- **纯 JSON 数据驱动 + 自建可视化编辑器**。全项目**零** `.tres` 数据资源（仅 `assets/ui/ui_theme.tres`），无 `resources/` 目录。内容集中在 `data/*.json`（7 个：spells / cores / enemies / waves / resonance / status_effects / balance），每个 Manager 各自 `FileAccess` 直读。文档反复出现的 `res://resources/**/*.tres` 与 `ConfigMgr` 数据层入口——**`ConfigMgr` 已注册为 autoload 但零调用，是死代码**。
|
||
- **全部 UI 程序化构建**。仅 4 个**游戏** `.tscn`（splash / main_menu / combat_s2 / combat_test）+ 1 个编辑器插件场景（`addons/godot_mcp/ui/status_panel.tscn`，非游戏 UI）。HUD、商店、背包、结算、暂停、设置 6 套面板全部在 `combat_s2.gd`（约 792 行）内 `Label.new()` / `Button.new()` 现建。文档的 `UIManager` / `GameCycleManager` / `TutorialManager` 三个 Autoload **全部不存在**。
|
||
- **战斗模型是"能打通的最小闭环"**，深度维度多为字段占位。Boss 是 SoA 里一个会召唤援军的厚血杂鱼；归航 / 弹跳 / 连锁 / 轨迹修正 / 元素催化 / 抗性 大多是**有字段无行为**；**Mana 魔力系统完全不存在**（而它是设计文档声称的核心平衡阀）。
|
||
|
||
---
|
||
|
||
## B. 三大结构性分歧（最需要决策）
|
||
|
||
| # | 分歧 | 文档 | 代码现实 | 判定 |
|
||
|---|---|---|---|---|
|
||
| 1 | **数据载体** | `.tres` Resource + `ConfigMgr` 统一数据层入口 | 纯 `data/*.json` + 7 页签"游戏设计器"插件，各 Manager 自读 | 🟢 更优（策划零代码可视化编辑），但文档系统性过期 |
|
||
| 2 | **热路径语言** | C# 内核驱动 `_physics_process` + 零拷贝 `AsSpan()` | 100% GDScript，C# 为死骨架 | 🔴/顺延（R-08）；实测 500 敌 1500 弹 ≈0.6ms，GDScript 够用 |
|
||
| 3 | **UI 架构** | 场景化 `.tscn` + `UIManager` 协调者 | 单文件程序化构建，无协调器 | 🔴 偏离（技术债：不可视化编辑、魔数坐标、单文件耦合） |
|
||
|
||
---
|
||
|
||
## C. 分类清单
|
||
|
||
### 🟢 更优 — 建议"追认"，改文档以对齐代码
|
||
|
||
| 项 | 说明 | 证据 |
|
||
|---|---|---|
|
||
| JSON + 编辑器插件 | 放弃 `.tres`，7 页签设计器（法术/敌人/波次/Core/共鸣/状态/平衡）全落地，与 handbook 07 吻合 | `addons/game_designer/`, `designer_panel.gd:11-18` |
|
||
| 存档 A/B 选最新 | 用 `saved_at` 时间戳选最新未损坏槽，比 ADR-A2 伪代码"固定顺序取第一个"更健壮；链式迁移 v0→v1→v2 | `profile_manager.gd:46-60,110-118` |
|
||
| 永远 MultiMesh 渲染 | 砍掉三档 Area2D→NodePool→MultiMesh 切换，单档 MultiMesh + per-instance 颜色 | `combat_s2.gd:149-177`, `enemy_manager.gd:288` |
|
||
| SpatialGrid-only 碰撞 | 无 Area2D、无 `_collision_mode` 阈值切换。⚠️**复核修正**：这与 §4.3/§4.4（描述 Area2D 优先 + 三档切换）**相反**；真正锁定 SpatialGrid-only 的 R-04 决议在 `implementation_plan.md:385` / `development_plan.md`。属**文档自相矛盾**，代码站在更新的 R-04 一侧 | `bullet_manager.gd:55-105` |
|
||
| `is_combo_tracker` 提前落地 | 文档标 P2，代码已实现，COMBO_MARK 不误触发 DoT | `status_manager.gd:25`, `status_effects.json:4` |
|
||
| MinionManager 用 Array[Dictionary] | 文档 §8 ADR-R4-N4 要 SoA，但 §5.12 允许 Array（≤20 数量），代码选了更简单且文档内部允许的方案 | `minion_manager.gd:6-7,15` |
|
||
|
||
### 🔴 偏离 — 与文档不符（需决策：改文档 or 改代码）
|
||
|
||
| 项 | 文档 | 代码 | 影响 |
|
||
|---|---|---|---|
|
||
| `execute_compiled` 签名 | `(compiled, ctx, core)` 且**禁止**快照 feature_tags | `(compiled, caster_id, spawn_pos)`，改从 `CompiledDeck.feature_tags`（编译期快照） | 接口契约与"禁止快照"约束双违背，但自洽 · `spell_evaluator.gd:321,324` |
|
||
| `compile_wand` 第 2 参 | `SpellDeck`（P6-N65 禁止 Array） | `Array` | 与硬约束相反 · `spell_evaluator.gd:36` |
|
||
| MAX_OPS 公式 | `MAX_OPS_PER_CPU×cpu_limit`（`implementation_plan`/`numerical` 用 40；`architecture §3.4` 用 8——文档内部亦不一致） | `MAX_OPS_PER_CPU=40`（值对），但 `40×5` 硬编码 **不读 cpu_limit** | 升级 CPU 词条对施法预算无影响（真实功能缺口，文档更优）· `spell_evaluator.gd:8,328` |
|
||
| Boss 阶段阈值 | 50% / 10%（§4.5 schema） | 66% / 33% | 数值不符 · `wave_manager.gd:99-102` |
|
||
| Endless 膨胀 | 每 5 波难度 +10% | 每波 ×1.12 HP（更陡） | 曲线形态不同 · `wave_manager.gd:153-159` |
|
||
| XP 曲线 | `⌊10×1.4^(n-1)⌋`（floor，P6-N16） | `roundi(...)`（四舍五入） | ⚠️**复核**：可忽略——`numerical §1` 的示例数值表本身用的是四舍五入值（5→6=54，floor 应为 53），`roundi` 反而更贴合文档表格 · `player_stats.gd:30-31` |
|
||
| 排行榜记录 Schema | `{wave, elapsed, build_snapshot, timestamp}`，留 20 条 | `{wave, elapsed, kills, score}`，留 50 条，无 snapshot | 文档所述"反作弊审核"无法实现 · `endless_records.gd:28-40` |
|
||
| 存档字段 | ADR-A2 含 `elapsed_sec / active_core_idx / unlocked_upgrades / 多Core` | 只存 `wave / shop_seed / stats / 单wand` | 缺 `elapsed_sec` 影响无尽续玩计时 · `profile_manager.gd:88-96` |
|
||
| COMBO_MARK 增伤 | ⚠️**复核修正**：文档 +5% 是 **VULNERABILITY** 状态的公式（`consecutive_hits_stacking.md:80`），非 COMBO_MARK | COMBO_MARK 每层 +2%；VULNERABILITY 未实现 | 审计原文把两个机制混为一谈；数值本身 +2% 确认 · `enemy_manager.gd:245` |
|
||
| CastStats/SpellContext/ProjectileDef 字段集 | 文档伪代码列出大量字段（pierce/bounce/homing/payloads/on_kill…） | 精简字段集，逻辑层实际用的更少 | 文档伪代码严重过期 · `cast_stats.gd:6-13`, `spell_context.gd:7-11`, `projectile_def.gd` |
|
||
| ProjectileDef 管线 | ACTION 填 ProjectileDef → 批量生成，`SpellContext.payloads` 队列 | `_push_projectile` 直接调 `spawn_bullet(裸参数)`，ProjectileDef 类未实例化（死代码） | 模板→池设计被绕过 · `spell_evaluator.gd:431-436` |
|
||
| ENEMY SoA +6/+7 语义 | `+6 faction_and_type` 打包、`+7 status_bits` 位掩码 | `+6` 仅存 type、`+7` 当存活标志 | 友军 faction 与内联状态位未落地 · `enemy_manager.gd:129-130` |
|
||
| MinionManager 结构 | ADR-R4-N4 SoA stride=8 | Array[Dictionary] | 见 C 节更优（文档内部矛盾，选了 §5.12） |
|
||
| SCOPE_CLOSE 作用域机制 | 预编译注入 SCOPE_CLOSE 虚节点 + label_table | 用"扫描到下一 TRIGGER 即停"直接分包，SCOPE_CLOSE 未使用 | 残留脚手架，实际方案更简单 · `spell_evaluator.gd:63-96` |
|
||
|
||
### 🟠 未实现 — 设计了但代码没有（或仅字段占位）
|
||
|
||
**整块缺失的系统：**
|
||
|
||
- **元进展全套** —— 以太碎片、局外解锁树、图鉴 Codex、成就、炼金日志。`scripts/` 下仅 1 个孤立的 `ACHIEVEMENT_UNLOCKED=18` 事件常量（无订阅方、无系统），其余 `aether/fragment/codex/unlock` 零命中。（`game_design §7`；无对应 autoload/字段）
|
||
- **Boss 系统架构** —— `BossManager` Autoload、`BossPhaseDef` / 攻击模式注册表、场地机制（冰墙 / 场地收缩）、多阶段弹幕全部 0% 实现。Boss 是 `EnemyManager` SoA 里 `type=4/5` 的普通敌人，唯一"阶段行为"是进阶时召唤一批 FAST 杂兵。（整个 `boss_design.md`；`wave_manager.gd:85,94-117`）
|
||
- **Mana 魔力系统** ✅ 已实现 MVP (2026-07-20) —— 原：核心平衡资源，`player_stats.gd` 无 mana 变量。（`game_design §4.1`）现已落地蓝池/蓝耗/回蓝/蓝空停施/HUD 蓝条，详见 `docs_dev/specs/2026-07-20-mana-system-mvp-design.md`。
|
||
- **里程碑 W5/W10/W15 / 练习模式 / Boss Rush / Endless 全局词条 / NG+ Phase4 / W20 通关演出 / GAME_CLEARED** —— 均未实现；游戏只能靠死亡结束。（`game_design §8`）
|
||
- **TutorialManager + 情境提示 + 渐进解锁（局1-5）+ 靶场慢放 DPS 演示** —— 实际只有首启难度三选一弹窗。（`tutorial_design.md` 全文；`main_menu.gd:277-353`）
|
||
- **战前 "The Lab" 独立准备界面 + 拖拽式背包** —— 改为商店内点击选中式插槽编辑器（功能等价，交互与入口偏离）。（`game_design §5.1`；`combat_s2.gd:532-662`）
|
||
- **伤害飘字 DamageNumber** —— 全无。（`architecture_design.md:2534,3359`）
|
||
|
||
**字段占位但无行为：**
|
||
|
||
- **归航子弹** —— `_enemy_pos_snapshot` 每帧填充（P6-N25 预分配满足）但 `_gd_integrate` 无 homing 计算，快照无人消费。`bullet_manager.gd:31,36-51`
|
||
- **连锁 / 弹跳** —— `bounce_remaining` 字段存在但从不消费；无 `visited_targets`、无 `pow(0.9, bounce)` 衰减。`bullet_manager.gd:97-104`, `enemy_manager.gd:240-257`
|
||
- **轨迹修正**（正弦 / 回旋镖 / 环绕）—— 全库无相关字段或分支。（`weapon_system_expansion.md §1`）
|
||
- **元素抗性 `(1-Res)`** —— `calc_damage(armor, resistance)` 公式正确，但实战路径恒传 `resistance=0`，抗性维度是死代码。`damage_context.gd:26-28`, `enemy_manager.gd:236-237`
|
||
- **催化 / 环境反应 / 状态交互矩阵** —— `can_catalyze` 是死字段，`StatusRegistry` 不解析该键；无 overwrite/immunity/反应地表。`status_registry.gd:20-30`
|
||
- **硬控与增幅状态** —— `FREEZE/WET/OILY/STUN/VULNERABILITY` 有 StatusID 常量但 `status_effects.json` 只定义了 Burn/Poison/Combo 三条；VULNERABILITY 叠层增伤未接线。`status_effects.json:2-4`, `enemy_manager.gd:244-245`
|
||
- **Core 特性标签** —— 5 个里只有 `PERSISTENT_MEMORY` 生效；`dual_stream / shuffle_deck / infinite_spells / always_cast_last` 除定义处无任何引用。`core_feature_tag.gd:6`
|
||
- **MATRIX 邻接表** —— P6-N13 的 6 行表中 4 个"加成行"只实现 3 个，缺 `ACTION+TRIGGER`（增压触发 proc_rate ×1.5）。`spell_evaluator.gd:232-244`
|
||
- **共鸣 `anywhere_in_deck`** —— 仅 stub，非 `adjacent` 直接跳过。`spell_evaluator.gd:272-273`
|
||
- **召唤物多形态** —— 只实现 Stationary（炮台）；随从/卫星/镜像无 hp/behavior_state/移动/碰撞。`minion_manager.gd:29-42`
|
||
- **敌人 LOD 屏内剔除** —— `_visible_flags` 声明却从不置 1，屏外低频分离力未实现。`enemy_manager.gd:25,312-316`
|
||
- **商店货架 B（核心）/ C（属性）/ 出售退款 G5** —— 只实现货架 A（法术抽取）。`shop_manager.gd:33-46`
|
||
- **玩家属性池** —— §4.3 的 5 条 MVP 属性只实现 CPU 一条；无 cast_speed/mana_leech/accuracy/attunement。`player_stats.gd:9-23`
|
||
- **掉落表** —— 所有敌人固定 `XP=5 / GOLD=2`，无按类型掉落表、无地面拾取物。`drop_manager.gd:7-15`
|
||
|
||
---
|
||
|
||
## D. ⚠️ 潜在 Bug / 风险（审计附带发现，建议单独修）
|
||
|
||
> ✅ **修复状态 (2026-07-20)**：**D1 / D2 / D5 已在分支 `fix/audit-latent-bugs`（commit `dc05eea`）实现修复，并经 Godot 运行时验收通过**（godot-mcp-pro，Godot 4.6.2，0 编译错误）：
|
||
> - **D1**：`feature_tags=1` 持久内存 `every_n_shots` 四连发 = `[0,0,1,0]`（正常）；碰撞值 `feature_tags=3` = `[0,0,0,0]`（正确判为非持久；旧 `&` bug 会误得 `[0,0,1,0]`）。
|
||
> - **D2**：`[pierce+2, spark_bolt]` 发射的子弹冷数据 = `{ pierce_remaining: 2 }`；无修正器的对照组为空（无误加）。
|
||
> - **D5**：`has_castable_action()` 对 纯 Modifier / 空槽 / 空 Deck 均返回 `false`，含 ACTION 返回 `true`；`SHOP_NEED_ACTION` 四语键正常解析。**端到端实测**（商店内点『出发下一波』）：纯 Modifier 卡组被拦截、显示红字警告、波次不推进（W1→W1）；含 ACTION 则正常进入下一波（W1→W2）。顺带修正警告 Label 位置（`(120,448)`→`(250,502)`）避免遮挡背包/语言/设置按钮行。
|
||
>
|
||
> D3（SpatialGridCs 参数分叉）与 D4（LOD `_visible_flags` 从不置 1）暂未处理——二者分别依赖尚未接线的 C# 与尚未启用的 LOD，风险潜伏、非当前活跃路径。
|
||
|
||
1. **`CoreFeatureTag` 位运算冲突（真实 latent bug）**：常量是 `1,2,3,4,5`（非 2 的幂），却用位与 `&` 判断持久内存。`ALWAYS_CAST_LAST(3) & PERSISTENT_MEMORY(1) = 1` → 若某 Core 设 `feature_tags=3` 会被误判为持久内存。当前仅 `wand_memory=1` 未触发。类型上也与文档 ADR-R5-N2（`architecture_design.md:2929` 示例为 `String` 常量 + `in core.feature_tags` 判定）相反——注：`core_feature_tag.gd:2` 自身头注把 ADR-R5-N2 解读为"禁止裸字符串"，与文档正文的 String 方案存在张力。✅ **已修复** (`dc05eea`)：复核发现 `feature_tags` 实为**单选枚举**——游戏设计器 `core_tab.gd` 以 OptionButton 下标 0..5 写入，下标即等于常量值。故修法是把判定从 `&` 改为 **`==`**、常量保持 1..5（未改 2 的幂位标志，以免与设计器下标 desync）；串扰消除。若将来要一个 Core 同时带多个特性，再改为位标志 + 设计器多选。待运行时验收。`core_feature_tag.gd:5-9`, `spell_evaluator.gd:41,324`
|
||
2. **`modifier_pierce_plus` 是空操作**：玩家能在商店买到，但 `_apply_modifier` 不识别 `pierce`，`CastStats` 无该字段 → **买了没效果**。`spell_evaluator.gd:488-501`, `cast_stats.gd:6-13` ✅ **已修复** (`dc05eea`)：新增 `CastStats.pierce_add`，`_apply_modifier` 累加、`_push_projectile` 叠加到 ACTION 自带 pierce。
|
||
3. **`SpatialGridCs` 与 GDScript 版参数分叉**：C# 版 `GridWidth=64` 无 offset，负坐标全 clamp 到 0；GDScript 版 128 + offset 4096 支持负坐标。C# 一旦接线，负坐标实体会塌到边缘格且覆盖减半。`SpatialGridCs.cs:42-43,64-67`
|
||
4. **敌人 LOD 剔除失效**：`_visible_flags` 从不置 1 → `sync_node_positions` 永不同步；屏外低频分离力（`_offscreen_sep_counter` 自增后丢弃）未实现。`enemy_manager.gd:25,76-79,312-316`
|
||
5. **战前无 Deck 防呆校验**：可携带空 / 纯 Modifier 卡组进战斗（`game_design §5.1` 要求拦截并提示"法术塔无法开火"）。`combat_manager.gd:220-228` ✅ **已修复** (`dc05eea`)：新增 `CombatManager.has_castable_action()`，商店"下一波"按钮校验，无 ACTION 时显示 `SHOP_NEED_ACTION`（四语）并阻止进入。
|
||
|
||
---
|
||
|
||
## E. 文档**自身**的内部矛盾（改代码前先修文档）
|
||
|
||
| 矛盾点 | 冲突来源 | 代码事实 |
|
||
|---|---|---|
|
||
| Boss 波次 W8 vs W10 | `game_design §4.5`(W10) vs `§8.3`(W8) vs `boss_design`(W8) | W8 miniboss / W20 final（`waves.json:9,21`） |
|
||
| Boss 血量 | `numerical §3.2`=50000 vs `boss_design §5`=10000 vs balance=1800 | 1800（`balance.json:8-11`）——数值策划 DPS 门槛基于错误血量 |
|
||
| Boss 阶段阈值 | 三处不一：`§4.5` schema=50%/10%、`boss_design` mini=60%/30% & final=70%/40%/15% | 代码 66%/33% | 文档需先自洽再对齐 |
|
||
| Boss EventID | `boss_design §6` 称 15/16/17 "已登记勿改" | 15/16/17 被 SPELL_EQUIPPED/LEVEL_UP/SHOP_OPENED 占用；三个 Boss 事件常量不存在（`event_ids.gd:25-32`） |
|
||
| MinionManager 结构 | `§8 ADR-R4-N4`(SoA) vs `§5.12`(Array) | 代码选 Array（`minion_manager.gd`） |
|
||
| 内容创作教程 | handbook 02（教改硬编码 `wand_preset.gd`/`WAVE_CONFIG`）vs handbook 07（JSON 编辑器） | 早已 JSON 化，handbook 02 会误导人改不存在的代码 |
|
||
|
||
---
|
||
|
||
## F. 建议的后续动作（按风险/价值排序）
|
||
|
||
1. **改文档以追认更优实现**（低风险，先做）：`architecture_design.md` 的 `.tres`/`ConfigMgr` 段、handbook 02、E 节全部文档矛盾、ADR-A2 存档伪代码 —— 对齐代码现状。
|
||
2. **修潜在 bug**（小改动高价值）：CoreFeatureTag 改真·位标志（或改回 String + `in` 判断）、pierce 修正器接线、战前 Deck 防呆校验。
|
||
3. **补关键玩法缺口**（按优先级排期）：Mana 系统 → 元进展 → Boss 阶段/抗性 → 属性词条。这些是"设计核心但未实现"，属真正的功能待办，非文档问题。
|
||
|
||
---
|
||
|
||
## G. 复核（对抗性验证）结论与"代码 vs 文档 更优"判定
|
||
|
||
> **复核方法**：2026-07-20 就地复核，6 个独立验证 agent 分域对本报告逐条**对抗性重验**（默认怀疑、行号全部从当前代码重新推导、代码不支持则证伪）。共复核约 65 条主张。
|
||
|
||
### G.1 准确性结论
|
||
|
||
- **零条被证伪（REFUTED）**。全部实质结论成立，关键 `file:line` 抽查无漂移。
|
||
- **两个 latent bug（D1 CoreFeatureTag 位运算、D2 pierce 空操作）经完整数据流追踪，均确认为真。**
|
||
- 少数措辞修正（已并入正文，不影响结论）：
|
||
1. 碰撞 SpatialGrid-only 的功劳被错记到"§4.3 自身 R-04"——实为**文档自相矛盾**（§4.3/§4.4 描述 Area2D 优先，R-04 锁定决议在 `implementation_plan.md`）。
|
||
2. MAX_OPS：`MAX_OPS_PER_CPU=40` 其实与多数文档一致，真正缺陷是硬编码 `×5` 不读 cpu_limit；且文档自身 8 vs 40 不一致。
|
||
3. COMBO_MARK +2% 属实，但文档"+5%"是 **VULNERABILITY**（未实现）的公式，被审计混为一谈。
|
||
4. MATRIX"五行只实现三行"应为"6 行表中 4 个加成行实现 3 个"。
|
||
5. 元进展"grep 零命中"实为"1 个孤立 `ACHIEVEMENT_UNLOCKED` 事件常量"。
|
||
6. UI"仅 4 个 .tscn"应为"4 个游戏场景 + 1 个编辑器插件场景"。
|
||
7. XP `roundi` 分歧可忽略（反而更贴合文档数值表）。
|
||
8. Boss 阶段阈值实为**三处**互相矛盾（50/10、60/30、70/40/15），不止两处。
|
||
|
||
### G.2 "代码 vs 文档 更优"判定汇总
|
||
|
||
**🟢 代码更优 —— 建议改文档追认（低风险，先做）**
|
||
|
||
| 分歧 | 为何代码更优 |
|
||
|---|---|
|
||
| JSON + 7 页签编辑器（弃 `.tres`/`ConfigMgr`） | 策划零代码可视化编辑；Godot Inspector 路线对本项目内容量无优势 |
|
||
| 存档 A/B 按 `saved_at` 选最新槽 | 正确处理"两槽都有效但一旧"场景，文档"固定顺序取第一个"会错取旧槽 |
|
||
| MultiMesh 单档常开（弃三档切换） | 碰撞已 SpatialGrid-only，子弹无法挂 Area2D，Node 池档位无意义；消除切换卡顿 |
|
||
| `execute_compiled(compiled, caster_id, pos)` | VM 内部自管 ctx，执行期无需 live `core`；快照随每次 compile 失效，自洽 |
|
||
| `compile_wand(core, Array)` | flatten 直接索引 Array，包成 SpellDeck 纯属仪式；P6-N65 所述崩溃不会发生 |
|
||
| `is_combo_tracker` 提前落地 | 文档标 P2，代码已实现且正确守卫 DoT |
|
||
| `_flatten_linear` 扫描到下个 TRIGGER（弃 SCOPE_CLOSE/label_table） | 更简单且功能等价；SCOPE_CLOSE 是应删的死脚手架 |
|
||
| `spawn_bullet` 扁平参数 + cold_data（绕过 ProjectileDef） | 避免热路径每发 RefCounted 分配；ProjectileDef 类应删 |
|
||
| ZoneManager 调 `StatusManager.apply(5 参)` | 代码签名/调用正确，文档 §8 内联伪代码是错的 4 参 |
|
||
|
||
**🔴 文档更优 / 真实缺陷 —— 建议改代码（补功能或修 bug）**
|
||
|
||
| 分歧 | 类型 |
|
||
|---|---|
|
||
| `CoreFeatureTag` 位运算冲突（1..5 非 2 的幂）| **Bug** ✅已修复(dc05eea)：判定改 `==`（单选枚举）|
|
||
| `modifier_pierce_plus` 空操作（可购买无效果）| **Bug** ✅已修复(dc05eea)：接线 pierce 到 CastStats/_apply_modifier |
|
||
| MAX_OPS 硬编码 `×5` 不读 cpu_limit | **Bug/缺口**：CPU 词条对施法预算无影响（未修）|
|
||
| 战前无 Deck 防呆校验 | **缺口** ✅已修复(dc05eea)：has_castable_action() + 商店校验 |
|
||
| Mana 系统 ✅ 已实现 MVP (2026-07-20) / 元进展 / 属性词条(4/5) / Boss 阶段·抗性 / 商店 B·C 货架 / 5 个 Core 特性标签(4/5) / MATRIX 增压触发 / 连锁弹跳 / 轨迹修正 / 元素催化 / 里程碑·NG+·通关 / TutorialManager·渐进解锁·靶场 / 归航 / DamageNumber / LOD 剔除 | **功能待实现**（设计核心，非文档错误）|
|
||
|
||
**🟡 中性 —— 纯陈旧或文档自相矛盾，改文档即可（不改代码）**
|
||
|
||
`.tres`/`ConfigMgr` 段、handbook 02 硬编码教程、CastStats/SpellContext 字段伪代码、collision §4.3/§4.4、boss 血量(50000/10000/1800)、boss 阶段阈值(三处不一)、W8 vs W10、boss EventID 15/16/17、MinionManager §5.12 vs ADR-R4-N4、tutorial_design EventID、存档 ADR-A2 伪代码、排行榜 Schema、COMBO/VULN 混淆、Endless 膨胀曲线、XP roundi、charge 进度环→文字（占位）、i18n 债务。
|
||
|
||
> **一句话**：本审计报告经独立对抗性复核**准确可信**；分歧中约 9 项代码更优（改文档追认）、3 个真实 bug + 一批未实现功能属文档更优（改代码），其余为文档陈旧/自相矛盾（仅改文档）。
|
||
|
||
---
|
||
|
||
## 附：审计覆盖的域与主要文件
|
||
|
||
| 审计域 | 主要代码 | 对照文档 |
|
||
|---|---|---|
|
||
| Spell VM / Wand·Core | `spell_evaluator.gd`, `sub_payload_registry.gd`, `wand_preset.gd`, `spell_registry.gd`, `scripts/core/*` | `core_wand_design.md`, `architecture_design.md §3`, `weapon_system_expansion.md` |
|
||
| 战斗 SoA 核心 | `bullet_manager.gd`, `enemy_manager.gd`, `spatial_grid.gd`, `csharp/**`, `combat_s2.gd` | `architecture_design.md §4/§6`, `implementation_plan.md §2.3` |
|
||
| 波次/Boss/难度 | `wave_manager.gd`, `enemy_manager.gd`, `settings_manager.gd`, `data/{waves,enemies,balance}.json` | `boss_design.md`, `game_design.md §4/§8`, `numerical_design.md` |
|
||
| 状态/区域/召唤/VFX/DPS | `status_manager.gd`, `status_registry.gd`, `zone_manager.gd`, `minion_manager.gd`, `vfx_manager.gd`, `dps_tracker.gd` | `advanced_mechanics_*.md`, `combat_mechanics_*.md`, `consecutive_hits_stacking.md`, `architecture_design.md §8` |
|
||
| 数据驱动/存档/经济/元进展 | `config_mgr.gd`, `shop_manager.gd`, `drop_manager.gd`, `profile_manager.gd`, `endless_records.gd`, `player_stats.gd`, `addons/**` | `architecture_design.md §2`, `game_design.md §5/§7/§8`, handbook 02/07 |
|
||
| UI/流程/FTUE/i18n/设置/音频 | `combat_s2.gd`, `combat_manager.gd`, `scene_manager.gd`, `locale_manager.gd`, `settings_manager.gd`, `audio_manager.gd`, `scenes/ui/*` | `game_design.md §5/§6`, `tutorial_design.md`, `architecture_design.md §5`, handbook 04 |
|