多轮审查和修复

2026-05-12 15:34:08 +08:00
parent f55d2a57c3
commit ebbbb7332e
805 changed files with 838724 additions and 1905 deletions
--- a/Docs/Verification/Architecture_Code_Consistency_Assessment_2026-05-11.md
+++ b/Docs/Verification/Architecture_Code_Consistency_Assessment_2026-05-11.md
@@ -0,0 +1,743 @@
+# Architecture 与 Assets/Scripts 一致性评估
+
+> 评估日期：2026-05-11  
+> 评估范围：Docs/Architecture 与 Assets/Scripts  
+> 评估目标：验证架构设计文档、覆盖矩阵与当前代码实现的一致性，识别已落地能力、命名或落点漂移、以及文档声明但尚未实现的项。
+
+---
+
+## 1. 结论摘要
+
+本次核对结果显示：项目的“模块边界”层面整体一致性较高，但“文档完成度声明”与“具体类型级实现”之间存在明显偏差。
+
+综合判断如下：
+
+- 结构层一致性：高
+- 核心运行时模块落地度：高
+- 文档与代码的命名同步度：中
+- 覆盖矩阵可信度：中偏低
+- 类型级细节一致性：中
+
+总体结论：
+
+1. Docs/Architecture 对项目的分层、模块切分、程序集边界和主要通信模式描述，和 Assets/Scripts 的实际结构高度吻合。
+2. Core、Combat、Enemy、World、Narrative、Camera、QuestChallenge 等模块的“主干设计”已经明显落地。
+3. 但 00_CoverageIndex 中“架构完整度 100%”的表述，和当前代码状态并不完全一致；至少存在若干文档明确声明、且被标为完成，但代码库中未找到对应类型的情况。
+4. 部分文档摘要仍保留旧命名或旧组件名，导致 README/索引文档与模块正文、模块正文与代码之间出现双重漂移。
+
+如果按工程可执行性而不是文档完整性来评估，当前状态更适合定义为：
+
+- 主体架构已成形
+- 多数核心模块已落地
+- 文档细节需要一轮“去过时化”和“完成度回标”
+
+---
+
+## 2. 评估方法
+
+本次评估采用以下方法进行交叉核对：
+
+1. 以 Docs/Architecture/README.md 作为总索引，提取架构模块列表与模块职责。
+2. 以各模块文档中的“路径 + 类型名 + 代码片段”作为声明依据。
+3. 到 Assets/Scripts 中查找对应 C# 文件、命名空间、目录位置和注释中的架构锚点。
+4. 将发现分为四类：
+   - 强一致：文档声明与代码实现基本一致
+   - 部分一致：实现存在，但路径、命名或职责边界有漂移
+   - 文档有、代码未见：文档明确声明且索引视为完成，但代码库未找到
+   - 代码有、文档弱覆盖：代码中存在明确实现，但未在架构文档中得到足够表达
+
+说明：
+
+- 本评估基于仓库静态内容，不包含 Unity 场景对象、Prefab 绑定、Inspector 序列化引用以及 Addressables 资产配置的运行时验证。
+- 因此本报告评估的是“代码结构与架构文档一致性”，不是“游戏功能是否可玩”。
+
+---
+
+## 3. 总体观察
+
+### 3.1 高一致区域
+
+以下区域表现出较强的一致性：
+
+- Core
+- Combat
+- Enemy
+- World
+- Narrative
+- Camera
+- QuestChallenge
+
+这些模块通常同时满足以下特征：
+
+- Docs/Architecture 中存在独立模块文档
+- Assets/Scripts 中存在对应目录或子目录
+- 关键类型名可在代码中直接找到
+- 代码注释中有反向引用具体架构章节
+
+### 3.2 主要不一致模式
+
+当前不一致主要不是“完全没实现”，而是以下几种更常见的偏差：
+
+1. 文档摘要仍使用旧名字，代码已演进为新实现。
+2. 模块正文给出的路径与真实目录落点不同，但职责本身存在。
+3. 覆盖矩阵将某些能力标记为“完整”，但同名类型在代码库中未找到。
+4. 架构文档偏重“框架基类”，对具体敌种、具体业务脚本、独立子系统的覆盖不足。
+
+### 3.3 风险判断
+
+最主要风险不在代码本身，而在文档对研发协作的误导：
+
+- 新成员可能误以为某些接口或工具已经存在
+- 代码审查时可能参考到过时路径或旧组件名
+- 后续迭代可能在已有实现外再造重复 abstraction
+- 覆盖矩阵的“100% 完整”会掩盖实际缺口
+
+---
+
+## 4. 逐模块评估
+
+### 4.1 Core 模块
+
+文档依据：
+
+- Docs/Architecture/03_CoreModule.md
+- Docs/Architecture/README.md
+
+关键声明：
+
+- GameManager
+- SceneLoader
+- GlobalObjectPool
+- SettingsManager
+- ServiceLocator
+
+代码核对结果：
+
+- Assets/Scripts/Core/GameManager.cs
+- Assets/Scripts/Core/SceneLoader.cs
+- Assets/Scripts/Core/Pool/GlobalObjectPool.cs
+- Assets/Scripts/Core/SettingsManager.cs
+- Assets/Scripts/Core/ServiceLocator.cs
+
+评估：强一致。
+
+说明：
+
+- 核心入口、场景加载、对象池、设置管理和服务定位器均已落地。
+- 代码注释与文档术语基本保持一致。
+
+### 4.2 Combat 模块
+
+文档依据：
+
+- Docs/Architecture/06_CombatModule.md
+
+关键声明：
+
+- DamageInfo
+- HitBox
+- HurtBox
+- Projectile
+- StatusEffectManager
+- Parry 相关能力
+
+代码核对结果：
+
+- Assets/Scripts/Combat/DamageInfo.cs
+- Assets/Scripts/Combat/HitBox.cs
+- Assets/Scripts/Combat/HurtBox.cs
+- Assets/Scripts/Combat/Projectile.cs
+- Assets/Scripts/Combat/LinearProjectile.cs
+- Assets/Scripts/Combat/ParryableProjectile.cs
+- Assets/Scripts/Combat/StatusEffects/StatusEffectManager.cs
+- Assets/Scripts/Parry/ParrySystem.cs
+
+评估：强一致。
+
+说明：
+
+- 战斗主干类型已形成完整骨架。
+- 状态效果和投射物已经细分到独立实现层。
+- Combat 与 Parry 的跨模块拆分也与项目整体程序集边界匹配。
+
+### 4.3 Enemy 模块
+
+文档依据：
+
+- Docs/Architecture/07_EnemyModule.md
+
+关键声明：
+
+- EnemyBase
+- EnemyStats
+- EnemyMovement
+- EnemyCombat
+- EnemyNavAgent
+- BossBase
+- AttackPatternSO
+- TelegraphSystem
+- LootTableSO
+- LootResolver
+- BatchLOSSystem
+
+代码核对结果：
+
+- Assets/Scripts/Enemies/EnemyBase.cs
+- Assets/Scripts/Enemies/EnemyStats.cs
+- Assets/Scripts/Enemies/EnemyMovement.cs
+- Assets/Scripts/Enemies/EnemyCombat.cs
+- Assets/Scripts/Enemies/Navigation/EnemyNavAgent.cs
+- Assets/Scripts/Enemies/Boss/BossBase.cs
+- Assets/Scripts/Enemies/Boss/AttackPatternSO.cs
+- Assets/Scripts/Enemies/Boss/Patterns/TelegraphSystem.cs
+- Assets/Scripts/Enemies/LootTableSO.cs
+- Assets/Scripts/Enemies/LootResolver.cs
+- Assets/Scripts/Enemies/AI/BatchLOSSystem.cs
+
+评估：强一致。
+
+补充观察：
+
+- Assets/Scripts/Enemies/FlyingEnemy.cs 之类具体敌种实现存在，但架构文档对具体敌种覆盖较弱，更偏向于描述框架层而非实例层。
+
+### 4.4 World 模块
+
+文档依据：
+
+- Docs/Architecture/08_WorldModule.md
+
+关键声明：
+
+- RoomTransition
+- SavePoint
+- HazardZone
+- Collectible
+- AbilityUnlock
+- InteractableDetector
+- WorldStateRegistry
+- CollectibleSpawner
+
+代码核对结果：
+
+- Assets/Scripts/World/RoomTransition.cs
+- Assets/Scripts/World/SavePoint.cs
+- Assets/Scripts/World/HazardZone.cs
+- Assets/Scripts/World/Collectible.cs
+- Assets/Scripts/World/AbilityUnlock.cs
+- Assets/Scripts/World/InteractableDetector.cs
+- Assets/Scripts/World/WorldStateRegistry.cs
+- Assets/Scripts/World/CollectibleSpawner.cs
+
+评估：强一致。
+
+说明：
+
+- 世界交互、场景切换、收集物、存档点等核心能力均可找到直接实现。
+
+### 4.5 Narrative 模块
+
+文档依据：
+
+- Docs/Architecture/14_NarrativeModule.md
+
+关键声明：
+
+- IInteractable
+- InteractionPromptController
+- DialogueManager
+- InteractableNPC
+- NarrativeNPC
+- EventChainManager
+- CutsceneManager
+
+代码核对结果：
+
+- Assets/Scripts/World/IInteractable.cs
+- Assets/Scripts/Dialogue/InteractionPromptController.cs
+- Assets/Scripts/Dialogue/DialogueManager.cs
+- Assets/Scripts/Dialogue/InteractableNPC.cs
+- Assets/Scripts/Dialogue/NarrativeNPC.cs
+- Assets/Scripts/EventChain/EventChainManager.cs
+- Assets/Scripts/Cutscene/CutsceneManager.cs
+
+评估：强一致，但存在模块拆分补充说明不足。
+
+说明：
+
+- 叙事实现实际横跨 Dialogue、Cutscene、EventChain、World 四个位置。
+- 文档虽有描述，但从目录组织上看，EventChain 已经是独立程序集级实现面，建议在 Architecture 入口层明确强调这一点。
+
+### 4.6 Camera 模块
+
+文档依据：
+
+- Docs/Architecture/17_CameraModule.md
+
+关键声明：
+
+- CameraStateController
+- RoomVisibleArea
+- CameraTriggerZone
+- RoomCamera
+- CameraConfigSO
+- CameraBlendProfileSO
+
+代码核对结果：
+
+- Assets/Scripts/Camera/CameraStateController.cs
+- Assets/Scripts/Camera/RoomVisibleArea.cs
+- Assets/Scripts/Camera/CameraTriggerZone.cs
+- Assets/Scripts/Camera/RoomCamera.cs
+- Assets/Scripts/Camera/CameraConfigSO.cs
+- Assets/Scripts/Camera/CameraBlendProfileSO.cs
+
+评估：强一致。
+
+### 4.7 Save 模块
+
+文档依据：
+
+- Docs/Architecture/12_SaveModule.md
+- Docs/Architecture/00_CoverageIndex.md
+
+关键声明：
+
+- SaveData
+- ISaveStorage
+- SaveManager
+- SaveMigrator
+- EmergencySaveService
+- CrashReporter
+- SaveValidator
+- IDlcSaveExtension
+
+代码核对结果：
+
+- 已找到：
+  - Assets/Scripts/Core/Save/SaveData.cs
+  - Assets/Scripts/Core/Save/ISaveStorage.cs
+  - Assets/Scripts/Core/Save/SaveManager.cs
+  - Assets/Scripts/Core/Save/SaveMigrator.cs
+  - Assets/Scripts/Core/Save/EmergencySaveService.cs
+  - Assets/Scripts/Core/Save/CrashReporter.cs
+- 未找到同名实现：
+  - SaveValidator
+  - IDlcSaveExtension
+
+评估：部分一致，且存在高优先级文档失真。
+
+说明：
+
+- 存档主骨架已实现。
+- 但文档中对 SaveValidator 与 IDlcSaveExtension 给出了明确路径、接口/类定义和调用方式，覆盖矩阵也将其视为已完成。
+- 代码库内未检出这两个同名类型，因此这部分不能视为“已实现”，最多只能视为“设计方案已写入文档”。
+
+### 4.8 Input 模块
+
+文档依据：
+
+- Docs/Architecture/04_InputModule.md
+
+关键声明：
+
+- InputReaderSO
+- InputBuffer
+- RebindPanel
+- ConflictDetector
+- RebindPersistence
+
+代码核对结果：
+
+- Assets/Scripts/Input/InputReaderSO.cs
+- Assets/Scripts/Input/InputBuffer.cs
+- Assets/Scripts/UI/Settings/RebindPanel.cs
+- Assets/Scripts/Input/ConflictDetector.cs
+- 未找到独立类型：RebindPersistence
+
+评估：部分一致。
+
+说明：
+
+- RebindPanel 与 ConflictDetector 已存在。
+- 文档对 RebindPersistence 的表述更像“InputReaderSO 内部持久化能力的抽象命名”，而不是仓库中真实存在的独立 C# 类型。
+- 这里的问题不一定是缺功能，更可能是文档层把“能力”写成了“类名”。
+
+### 4.9 Player 模块
+
+文档依据：
+
+- Docs/Architecture/05_PlayerModule.md
+
+关键声明：
+
+- PlayerController
+- PlayerMovement
+- PlayerStats
+- PlayerCombat
+- FormController
+- WeaponManager
+- SkillManager
+- SpringSystem
+- FSM States
+
+代码核对结果：
+
+- Assets/Scripts/Player/States/PlayerController.cs
+- Assets/Scripts/Player/PlayerMovement.cs
+- Assets/Scripts/Player/PlayerStats.cs
+- Assets/Scripts/Player/PlayerCombat.cs
+- Assets/Scripts/Player/FormController.cs
+- Assets/Scripts/Player/WeaponManager.cs
+- Assets/Scripts/Skills/SkillManager.cs
+- Assets/Scripts/Player/SpringSystem.cs
+
+评估：部分一致。
+
+说明：
+
+- 核心能力都存在。
+- 但 PlayerController 并不在 Player 根目录，而是在 Player/States 下。
+- SkillManager 也被拆分到独立的 Skills 模块，而不是完全留在 Player 模块目录中。
+- 这类偏差对运行时影响不大，但会误导按文档定位代码的开发者。
+
+### 4.10 Progression 模块
+
+文档依据：
+
+- Docs/Architecture/09_ProgressionModule.md
+
+关键声明：
+
+- AbilityType
+- AbilityGate
+- Equipment/Charm/Tool/Skill 等能力与成长系统
+
+代码核对结果：
+
+- Assets/Scripts/Player/AbilityType.cs
+- Assets/Scripts/World/AbilityGate.cs
+- Assets/Scripts/Equipment/...
+- Assets/Scripts/Skills/...
+
+评估：主体一致，但 AbilityType 定义存在明显漂移。
+
+关键差异：
+
+- 文档枚举项包含：AerialDash、InvincibleDash、ClimbVines、UseTools、ReadShrine、UseGrapple 等
+- 代码枚举项包含：AirDash、SuperJump、Dive、Spell1、Spell2、Spell3、SpiritForm、SpiritDash、FastTravel 等
+
+判断：
+
+- 这不是简单命名差异，而是能力模型本身发生了演进。
+- 当前文档中 AbilityType 的示例和真实代码已不属于同一版本。
+
+影响：高。
+
+- AbilityType 直接影响存档兼容、关卡门禁和能力查询语义。
+- 如果开发者依据文档新增位标志，存在破坏现有位序或存档含义的风险。
+
+### 4.11 UI 模块
+
+文档依据：
+
+- Docs/Architecture/10_UIModule.md
+
+关键声明：
+
+- UIManager
+- HUDController
+- BossHPBar
+- PauseMenuController
+- DeathScreenController
+- SettingsPanelController
+- SaveSlotController
+- SaveIndicator
+- LoadingOverlay
+- IBossHPProvider
+
+代码核对结果：
+
+- 多数 UI 控制器可在 Assets/Scripts/UI 中找到
+- BossHPBar 存在：Assets/Scripts/UI/HUD/BossHPBar.cs
+- 未找到独立接口：IBossHPProvider
+
+评估：部分一致。
+
+说明：
+
+- UI 模块大多数实体存在。
+- 但文档明确给出 IBossHPProvider 路径和接口定义，仓库内未发现同名接口。
+- 这意味着 BossHPBar 的依赖抽象层与文档不一致，或者文档记录了一个尚未落地的重构目标。
+
+### 4.12 VFX / Feedback 模块
+
+文档依据：
+
+- Docs/Architecture/18_VFXFeedbackModule.md
+- Docs/Architecture/README.md
+
+关键声明：
+
+- IFeedbackPlayer
+- PlayerFeedback
+- EnemyFeedback
+- FeedbackConfigSO
+- VFXPool
+- HitFXSpawner
+- HurtFlashController
+- PaletteSwapSystem
+- PostProcessManager
+- RegionLightController
+
+代码核对结果：
+
+- VFXPool、HitFXSpawner 等主干命名可在 Assets/Scripts/VFX 中找到
+- 但 README 层摘要与模块正文、代码之间存在术语漂移
+
+评估：部分一致。
+
+说明：
+
+- 模块正文比 README 更接近现状。
+- README 的摘要更像较旧版本的名称集合，不适合作为准确索引。
+
+### 4.13 Liquid / Puzzle 模块
+
+文档依据：
+
+- Docs/Architecture/21_LiquidPuzzleModule.md
+- Docs/Architecture/README.md
+
+关键声明：
+
+- README 摘要中可见旧名称：LiquidSimulator、LiquidTile、LiquidTriggerZone、HazardLiquid
+- 模块正文与代码更接近的名称：LiquidZone、SwimState 等
+
+代码核对结果：
+
+- Assets/Scripts/World/Liquid/LiquidZone.cs
+- Assets/Scripts/Player/States/SwimState.cs
+- Assets/Scripts/World/Liquid/LiquidPhysicsConfigSO.cs
+- Assets/Scripts/World/Liquid/UnderwaterPostProcessingController.cs
+
+评估：部分一致。
+
+说明：
+
+- 模块真实实现明显采用了 LiquidZone 体系。
+- README 摘要没有同步更新，保留了旧名，造成总览页与真实实现不一致。
+
+### 4.14 Supporting 模块
+
+文档依据：
+
+- Docs/Architecture/16_SupportingModules.md
+
+关键声明：
+
+- LocalizationManager
+- AchievementManager
+- PlatformManager
+- DebugCheatSystem
+- AntiSoftlockSystem
+- AccessibilityManager
+- AnalyticsManager
+
+代码核对结果：
+
+- AchievementManager 实际位于 Assets/Scripts/Progression/AchievementManager.cs
+- Accessibility 相关实现位于 Support 子层
+- 平台相关实现位于 Platform / Support 交叉区域
+
+评估：部分一致。
+
+说明：
+
+- 功能存在，但“支撑模块”更像是文档维度的归类，而不总是对应单一物理目录。
+- 其中 AchievementManager 被放在 Progression 下更符合运行时职责，但与 SupportingModules 的组织口径不完全一致。
+
+### 4.15 BossSkill 模块
+
+文档依据：
+
+- Docs/Architecture/23_BossSkillModule.md
+- Docs/Architecture/README.md
+
+关键声明：
+
+- BossSkillSO
+- BossSkillExecutor
+- SkillSequenceSO
+- VulnerabilityWindow
+- BossOrchestrator 集成
+- README 摘要中还提到 BossPhaseController
+
+代码核对结果：
+
+- Assets/Scripts/Enemies/Boss/BossSkillSO.cs
+- Assets/Scripts/Enemies/Boss/BossSkillExecutor.cs
+- Assets/Scripts/Enemies/Boss/SkillSequenceSO.cs
+- BossPhaseController 未找到同名实现
+
+评估：部分一致。
+
+说明：
+
+- 模块正文和代码大体对齐。
+- 但 README 摘要中的 BossPhaseController 未在代码中体现，说明入口摘要比正文更过时。
+
+---
+
+## 5. 重点问题清单
+
+以下问题按优先级排序。
+
+### P1. 覆盖矩阵“100% 完整”结论失真
+
+证据：
+
+- Docs/Architecture/00_CoverageIndex.md 声称架构完整度 100%
+- 但 SaveValidator、IDlcSaveExtension、IBossHPProvider、BossPhaseController 等同名类型在代码库中未找到
+
+影响：高。
+
+- 会导致文档被高估为“可直接实施现状说明”，而实际上其中一部分仍属于“设计稿状态”。
+
+建议：
+
+- 将 CoverageIndex 的状态从“完整”改为“已定义 / 已实现 / 部分实现 / 待实现”四态。
+
+### P2. Progression 的 AbilityType 文档与代码版本明显脱节
+
+证据：
+
+- Docs/Architecture/09_ProgressionModule.md 中的枚举值与 Assets/Scripts/Player/AbilityType.cs 不一致
+
+影响：高。
+
+- 该枚举是 bitmask，错误文档会直接影响存档位定义和门禁逻辑。
+
+建议：
+
+- 以代码为准回写文档，或在文档中明确“当前实现版本”和“设计目标版本”的差别。
+
+### P3. README 摘要层存在多处旧名称残留
+
+典型例子：
+
+- Liquid 模块摘要中的 LiquidSimulator / LiquidTile / LiquidTriggerZone
+- Boss 模块摘要中的 BossPhaseController
+- VFX 摘要的旧术语
+
+影响：中高。
+
+- README 是入口文档，过时摘要会比模块正文更容易误导。
+
+建议：
+
+- 优先更新 README，使其只承担“导航”和“当前真实入口”职责，不再保留历史名词。
+
+### P4. 文档将“能力描述”写成“独立类型”，造成查找失败
+
+典型例子：
+
+- RebindPersistence
+
+影响：中。
+
+- 读者会误以为仓库中应存在该类。
+
+建议：
+
+- 将这类条目重写为“由 InputReaderSO 提供的持久化能力”，避免伪类型名。
+
+### P5. 物理目录与文档逻辑目录存在合理但未解释的偏移
+
+典型例子：
+
+- PlayerController 位于 Player/States
+- SkillManager 位于 Skills
+- AchievementManager 位于 Progression
+- EventChain 独立成模块级目录
+
+影响：中。
+
+- 偏移本身不是 bug，但若文档不解释，会增加代码定位成本。
+
+建议：
+
+- 在 README 或对应模块文档中增加“实现落点说明”小节。
+
+---
+
+## 6. 一致性评级
+
+本报告给出如下评级：
+
+| 维度 | 评级 | 说明 |
+|---|---|---|
+| 模块划分一致性 | A | 目录结构、程序集边界、模块切分与架构文档高度一致 |
+| 核心系统落地度 | A- | Core、Combat、Enemy、World、Narrative、Camera 等主干已经落地 |
+| 文档摘要准确性 | B- | README 与 CoverageIndex 含明显过时内容 |
+| 类型级一致性 | B- | 若干文档中的明确类型在代码中不存在 |
+| 文档可作为“当前事实来源”的可靠性 | B | 可用于理解架构，但不能无条件视为当前实现真相 |
+
+综合评级：B+
+
+解释：
+
+- 从工程结构看，这是一套已经较成熟的模块化代码库。
+- 从文档治理看，Architecture 文档更接近“设计与实现混合体”，部分章节已经演变为前瞻设计，不再完全等于当前代码状态。
+
+---
+
+## 7. 修正建议
+
+建议按以下顺序处理文档治理问题。
+
+### 第一优先级
+
+1. 修正 Docs/Architecture/00_CoverageIndex.md 的完成度口径。
+2. 修正 Docs/Architecture/09_ProgressionModule.md 中 AbilityType 的当前实现定义。
+3. 修正 Docs/Architecture/README.md 中已过时的模块摘要名称。
+
+### 第二优先级
+
+1. 在 Save、UI、BossSkill、Input 等模块文档中，将“已实现”与“设计建议”明确分栏。
+2. 对未在代码中找到的类型增加状态标记：
+   - 设计中
+   - 计划实现
+   - 已被内联到其他类
+   - 已废弃
+
+### 第三优先级
+
+1. 在 Player、Progression、Narrative、Supporting 等文档中补充“真实代码落点说明”。
+2. 对具体敌种、EventChain、Support 下功能子系统增加简短架构附录，避免只有框架文档、没有实现面索引。
+
+---
+
+## 8. 建议的文档治理规则
+
+为避免文档再次与实现脱节，建议建立以下规则：
+
+1. Architecture README 只保留当前已存在的模块入口和当前术语，不承载历史命名。
+2. CoverageIndex 不再使用单一“完整/不完整”，改为多状态矩阵。
+3. 模块文档中的代码块若为“目标方案”，必须明确标记为“设计草案”；若为“当前实现”，路径和类型名必须可在仓库直接检索。
+4. 所有 bitmask、事件频道、序列化结构等高风险契约，优先以代码为准回写文档。
+5. 每次较大重构后，至少同步更新 README、CoverageIndex 和对应模块文档三处入口。
+
+---
+
+## 9. 最终判断
+
+这套架构文档并不是“失真严重”，相反，它对项目的整体模块化设计、程序集边界、职责拆分和通信方式提供了很强的指导价值；问题主要出在：部分文档已经领先于当前实现，另一些文档仍停留在旧版本命名上，而覆盖矩阵又把这些差异全部抹平成了“100% 完整”。
+
+因此，更准确的表述应当是：
+
+- 架构主线与代码实现整体一致
+- 核心模块普遍已落地
+- 文档细节存在中等强度漂移
+- 覆盖矩阵结论高估了当前一致性
+
+如果只从“是否还能指导开发”来看，答案是可以；如果从“是否能作为当前实现的严格事实来源”来看，答案是否定的，尤其在 Save、Progression、UI 抽象接口和 README 摘要层面，需要尽快回收偏差。
--- a/Docs/Verification/Phase1_Verification_Guide.md
+++ b/Docs/Verification/Phase1_Verification_Guide.md
@@ -84,17 +84,102 @@

 > HitBox / HurtBox 依赖 Layer 碰撞矩阵，未配置时攻击不触发伤害。

-**步骤**：
-1. 菜单 `Edit → Project Settings → Physics 2D`
-2. 滚动到底部 **Layer Collision Matrix** 区域
-3. 确认以下组合已勾选（绿色）：
+**详细配置步骤**：

-| 行 Layer | 列 Layer | 说明 |
+1. 打开菜单 `Edit → Project Settings → Tags and Layers`
+2. 在 User Layer 中创建以下 Layer（名称必须完全一致，区分大小写）：
+
+| Layer 名称 | 用途 |
+|-----------|------|
+| `Player` | 玩家主物体（Rigidbody2D 所在） |
+| `Enemy` | 敌人主物体（Rigidbody2D/导航代理所在） |
+| `Ground` | 地面、墙体、平台等场景碰撞体 |
+| `PlayerHitBox` | 玩家攻击判定触发器 |
+| `PlayerHurtBox` | 玩家受击判定触发器 |
+| `EnemyHitBox` | 敌人攻击判定触发器 |
+| `EnemyHurtBox` | 敌人受击判定触发器 |
+| `TriggerZone` | 存档点、相机区、剧情触发区 |
+
+3. 给对象分配 Layer（Scene 中逐个核对）：
+
+| 对象 | Layer |
+|------|-------|
+| Player 根节点（含 Rigidbody2D） | `Player` |
+| Player/HitBox 子节点 | `PlayerHitBox` |
+| Player/HurtBox 子节点 | `PlayerHurtBox` |
+| Enemy 根节点（含 Rigidbody2D 或 NavAgent） | `Enemy` |
+| Enemy/HitBox 子节点（如果有） | `EnemyHitBox` |
+| Enemy/HurtBox 子节点 | `EnemyHurtBox` |
+| Tilemap Ground、静态障碍 | `Ground` |
+| SavePoint、CameraTrigger、RoomTrigger | `TriggerZone` |
+
+4. 打开菜单 `Edit → Project Settings → Physics 2D`
+5. 滚动到底部 `Layer Collision Matrix`
+6. 按 Unity `Layer Collision Matrix` 逐格设置（与你截图中的排列一致）：
+
+当前矩阵显示顺序（从上到下/从左到右）为：
+
+| 序号 | Layer |
+|------|-------|
+| 0 | `Default` |
+| 1 | `TransparentFX` |
+| 2 | `Ignore Raycast` |
+| 3 | `Player` |
+| 4 | `Water` |
+| 5 | `UI` |
+| 6 | `Enemy` |
+| 7 | `Ground` |
+| 8 | `PlayerHitBox` |
+| 9 | `PlayerHurtBox` |
+| 10 | `EnemyHitBox` |
+| 11 | `EnemyHurtBox` |
+| 12 | `TriggerZone` |
+
+在该排列下，只需要重点修改以下交叉格（其余保持默认即可）：
+
+| 行 Layer | 列 Layer | 设置 |
 |---------|---------|------|
-| `PlayerHitBox` | `EnemyHurtBox` | 玩家攻击打敌人 |
-| `EnemyHitBox` | `PlayerHurtBox` | 敌人攻击打玩家 |
-| `Player` | `Ground` | 玩家落地检测 |
-| `Enemy` | `Ground` | 敌人落地检测 |
+| `Player` | `Ground` | ✅ |
+| `Enemy` | `Ground` | ✅ |
+| `Player` | `Enemy` | ✅ |
+| `PlayerHitBox` | `EnemyHurtBox` | ✅ |
+| `EnemyHitBox` | `PlayerHurtBox` | ✅ |
+| `TriggerZone` | `Player` | ✅ |
+| `PlayerHitBox` | `Ground` | ❌ |
+| `EnemyHitBox` | `Ground` | ❌ |
+| `PlayerHurtBox` | `Ground` | ❌ |
+| `EnemyHurtBox` | `Ground` | ❌ |
+| `PlayerHitBox` | `PlayerHurtBox` | ❌ |
+| `EnemyHitBox` | `EnemyHurtBox` | ❌ |
+| `PlayerHitBox` | `Player` | ❌ |
+| `EnemyHitBox` | `Enemy` | ❌ |
+| `TriggerZone` | `Enemy` | ❌ |
+
+定位技巧（与 Unity 面板一致）：
+- Unity 只显示下三角矩阵，`A × B` 与 `B × A` 是同一个格
+- 找不到某一格时，优先在“行名较靠下”的那一行里找对应列
+- 先设置 5 个核心开启项：`Player-Ground`、`Enemy-Ground`、`PlayerHitBox-EnemyHurtBox`、`EnemyHitBox-PlayerHurtBox`、`TriggerZone-Player`
+
+7. 组件级别补充设置（和矩阵一起生效）：
+   - HitBox 与 HurtBox 的 Collider2D 必须 `Is Trigger = true`
+   - Player/Enemy 主体 Collider2D 必须 `Is Trigger = false`
+   - 至少一方需要 Rigidbody2D 才会触发 Trigger 回调（本项目通常在主体根节点）
+
+8. 快速验证：
+   - 玩家攻击敌人：应触发 `EVT_HitConfirmed`
+   - 敌人攻击玩家：玩家 HP 下降且 HUD 刷新
+   - 玩家接触 SavePoint：应触发 `EVT_SavePointActivated`
+
+### 1.6 本文统一测试场景与加载方式（必须按此执行）
+
+为避免“服务层未加载”或“房间场景缺对象”的误判，本文所有验证默认使用以下场景组合：
+
+1. 打开 `Assets/Scenes/Persistent.unity`
+2. 使用 Additive 方式再打开 `Assets/Scenes/TestRoom.unity`
+3. 在 Hierarchy 中确认 `Persistent` 与 `TestRoom` 两个场景同时处于已加载状态
+4. 若当前只开了 `TestRoom.unity`，请先停止测试并改为上述双场景组合后再执行
+
+> 例外：仅测试单纯美术或单房间静态内容时可只开 `TestRoom.unity`。但凡涉及输入、服务注册、事件总线、存档、死亡复活，必须使用双场景组合。

 ---

@@ -148,7 +233,7 @@
          _deathScreenController → DeathScreenController GameObject 引用
 ```

-### 2.2 测试房间场景 —— `Assets/Scenes/Rooms/TestRoom.unity`
+### 2.2 测试房间场景 —— `Assets/Scenes/TestRoom.unity`

 ```
 [TestRoom]
@@ -222,12 +307,21 @@

 ## 3. 编辑器扩展工具一览

-Phase 0/1 实现了以下 Editor-only 工具，验证过程中会频繁用到：
+当前验证会用到两类入口：
+
+1. **BaseGames 自定义菜单工具**：会出现在 `BaseGames` 菜单下
+2. **Unity / 第三方现成窗口**：仍然在各自原生菜单里，不会出现在 `BaseGames` 菜单下

 | 工具 | 菜单路径 | 快捷键 | 用途 |
 |------|---------|--------|------|
 | **Event Bus Monitor** | `BaseGames → Tools → Event Bus Monitor` | `Ctrl+Shift+E` | Play 模式下实时查看所有 SO 事件触发记录 |
-| **Validate AddressKeys** | `Tools → Validate AddressKeys` | — | 手动校验 AddressKeys 常量与 Addressable 分组一致性 |
+| **Create Event Channel Assets** | `BaseGames → Tools → Create Event Channel Assets` | — | 一键生成全局事件频道资产 |
+| **Reimport Event Channel Assets** | `BaseGames → Tools → Reimport Event Channel Assets` | — | 批量重导入 `Assets/Data/Events` 下的事件资产 |
+| **Validate Address Keys** | `BaseGames → Tools → Validate Address Keys` | — | 手动校验 AddressKeys 常量与 Addressable 分组一致性 |
+| **Scaffold Persistent Scene** | `BaseGames → Tools → Scaffold Persistent Scene` | — | 一键生成 Persistent 场景基础层级与核心组件骨架 |
+| **Scaffold Test Room** | `BaseGames → Tools → Scaffold Test Room` | — | 一键生成 TestRoom 基础层级、Player/Enemy/Camera/SavePoint 骨架 |
+| **Apply Script Execution Order Preset** | `BaseGames → Tools → Apply Script Execution Order Preset` | — | 一键写入推荐的脚本执行顺序 |
+| **Validate Script Execution Order Preset** | `BaseGames → Tools → Validate Script Execution Order Preset` | — | 校验当前执行顺序是否符合推荐值 |
 | **Animancer Window** | `Window → Animation → Animancer` | — | 查看当前播放的动画状态和混合树 |
 | **Behavior Designer** | 选中敌人 → Inspector → Open | — | 实时观察 BT 节点执行路径 |
 | **Audio Mixer** | `Window → Audio → Audio Mixer` | — | 查看实时音频电平 |
@@ -246,8 +340,10 @@ Phase 0/1 实现了以下 Editor-only 工具，验证过程中会频繁用到：

 #### 步骤 1：确认执行顺序配置

-1. 菜单 `Edit → Project Settings → Script Execution Order`
-2. 确认以下顺序存在（数字越小越先执行）：
+1. 优先使用一键菜单：`BaseGames → Tools → Apply Script Execution Order Preset`
+2. （可选）执行校验菜单：`BaseGames → Tools → Validate Script Execution Order Preset`
+3. 若需人工复核，打开 `Edit → Project Settings → Script Execution Order`
+4. 确认以下顺序存在（数字越小越先执行）：

 | 脚本 | ExecutionOrder |
 |------|---------------|
@@ -260,7 +356,7 @@ Phase 0/1 实现了以下 Editor-only 工具，验证过程中会频繁用到：

 #### 步骤 2：Play 模式验证

-1. 打开包含 `Persistent.unity` 的场景
+1. 按 [1.6 本文统一测试场景与加载方式](#16-本文统一测试场景与加载方式必须按此执行) 加载 `Persistent.unity + TestRoom.unity`
 2. 按 **Play**
 3. 查看 Console，预期输出（顺序）：
 ```
@@ -381,7 +477,21 @@ ISceneService:         SceneService

 **验证目标**：物理按键正确映射到 InputReaderSO 事件，InputBuffer 缓冲窗口生效。

-#### 步骤 1：Inspector 字段核查
+#### 步骤 0：先进入正确场景（必做）
+
+1. 按 [1.6 本文统一测试场景与加载方式](#16-本文统一测试场景与加载方式必须按此执行) 加载场景
+2. 打开 `BaseGames → Tools → Event Bus Monitor`
+3. 在 EventBusMonitorWindow 点击 **Clear** 清空历史记录
+4. 在 Filter 输入框输入 `Pause`
+
+#### 步骤 1：InputReader 挂载与引用核查
+
+1. 在 `Persistent` 场景中选中 `InputReaderHolder`
+2. 检查 `InputReaderBootstrap._inputReader`：必须已拖拽 `Assets/Data/Input/InputReader.asset`
+3. 检查 `InputReader.asset`（ScriptableObject）中的 `_inputActions`：必须指向 `Assets/Settings/PlayerInputActions.inputactions`
+4. 检查 `_onPauseRequested`：必须指向 `Assets/Data/Events/EVT_PauseRequested.asset`
+
+#### 步骤 2：Inspector 字段核查

 选中 `InputBuffer` 组件（挂在 Player 上）：

@@ -392,18 +502,40 @@ ISceneService:         SceneService
 | `_attackBufferDuration` | **0.12** |
 | `_dashBufferDuration` | **0.10** |

-#### 步骤 2：InputActions 配置验证
+#### 步骤 3：InputActions 配置验证

 1. 双击 `Assets/Settings/PlayerInputActions.inputactions` 打开 Input System 编辑器
 2. 确认以下 **Action Maps** 存在：
-   - `Gameplay`（含 Move / Jump / Attack / Dash / Parry 等 Actions）
-   - `UI`（含 Navigate / Submit / Cancel 等）
-   - `Cutscene`（含 Skip 等）
-3. 检查 `Jump` Action 的 Binding：
+   - `Gameplay`（含 Move / Jump / Attack / DownAttack / UpAttack / Parry / Dash / UseSpring / Switch* / SoulSkill / SpiritSkill* / Interact / Pause）
+   - `UI`（含 Navigate / Submit / Cancel / Pause / Point）
+3. 检查 `Pause` Action 的 Binding（Gameplay 与 UI 均需存在）：
+   - `Keyboard` → `Escape`
+   - `Gamepad` → `Start`
+4. 检查 `Jump` Action 的 Binding：
   - `Keyboard` → `Space`
   - `Gamepad` → `Button South`（南键）

-#### 步骤 3：缓冲窗口验证（跳跃缓冲）
+#### 步骤 4：Escape 事件链验证（本阶段主验证项）
+
+1. 按 **Play**
+2. 按一次 `Escape`
+3. 观察 Console，必须出现一次链路日志：
+
+```
+[InputReaderSO.HandlePause] PAUSE INPUT DETECTED!
+[InputReaderSO.HandlePause] Invoking PauseEvent...
+[InputReaderSO.HandlePause] Raising _onPauseRequested channel...
+```
+
+4. 观察 EventBusMonitorWindow（Filter=Pause）：
+   - 应新增 1 条 `EVT_PauseRequested`
+   - `Subs` 应大于 0（通常为 2）
+5. 再按一次 `Escape`
+6. 再次确认仅新增 1 条 `EVT_PauseRequested`
+
+> 通过标准：按 2 次 Escape，新增 2 条 `EVT_PauseRequested`。若出现 4 条，表示重复绑定回归，需要排查 InputReaderSO 的重复 Bind。
+
+#### 步骤 5：缓冲窗口验证（跳跃缓冲）

 1. 让玩家跳跃到空中
 2. **在落地前约 100–150ms**（目测约 3–5 帧前）按下跳跃键