# 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 摘要层面，需要尽快回收偏差。