docs(enemy): Boss AI 单轨落地——新增作者指南，清理描述已删除系统的长期文档
新增 Docs/Guides/09_BossAi_Authoring_Guide.md： 定制路径写法（[AiDefinition] + AiScript）、建态原语（AiStateFragments + BossFragments + IBossControl）、阶段=换招池、一招怎么配（EnemyAbilitySO + EnemyAttackSO + 动画事件）、开战触发、死亡归物理层， 以已落地的 ChaoFengAi 为逐段范例，附 Boss 专属陷阱与已知缺口。 08 号指南加交叉引用。 删除两份整份描述已删除且从未实现的体系的文档： Docs/Architecture/23_BossSkillModule.md、Docs/Design/47_BossSkillSystem.md。 删前已确认全库无 Markdown 链接残留，索引行与关联文档行改指新指南或 spec。 修订：25_CharacterArchitectureOverview §4 Boss 章节按实际代码重写； 07_EnemyModule 加过时提示、§11 改重定向；02_EventSystem 修正 Boss 事件发送方； 19_BossPatternLibrary 加废止提示（设计意图仍有效，类型名已废）； AssetFolderSpec 删旧 Boss 技能编辑器条目；三处 README/索引同步。 Docs_Dev/ 历史记录保留不动。 spec 标记为已实施，并记录实施期偏差（无 Boss 骨架、Telegraph 枚举保留、 阶段直查不走黑板、BossSkillEvent 一并删除）与八项已知未完成项， 其中 EnemyHurtState 无受击动画永久卡死为最高优先级、且与 Boss 轨无关。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -1,6 +1,7 @@
|
||||
# Boss AI 双轨统一：决策层与执行层一并归并到小怪轨
|
||||
|
||||
> 日期：2026-07-30 状态：设计已确认，待实施
|
||||
> 日期：2026-07-30 状态：**已实施**（阶段一 Task 1–15、阶段二 Task 16–21）
|
||||
> 实施期偏差与仍为待办的项见 [§13 注记](#13-注记)。作者指南：`Docs/Guides/09_BossAi_Authoring_Guide.md`
|
||||
> 背景：小怪走 `EnemyAiBrain`（BrainGraph）+ 组合式模块 + `EnemyAbilityBase`/`EnemyAbilitySO`；
|
||||
> Boss 走 `BossBase` + `BossSkillExecutor` + `BossSkillSO`。2026-07-27 的抽取决策记录把终态定为
|
||||
> 「决策层统一 BrainGraph + 执行层按复杂度分层（Boss 保留 `BossSkillExecutor` 富编排）」。
|
||||
@@ -567,3 +568,75 @@ C# 单继承直接堵死。
|
||||
本次确认 E004 归精英怪，`ApproachAttackEngagement` 的投入不作废，反而被 Boss 图复用（§4.2）。
|
||||
- 竞品调研于 2026-07-30 完成，调研对象与来源链接见对应会话记录；本文档按 CLAUDE.md 第 4 条
|
||||
只保留功能性描述，不写入具体作品与角色名。
|
||||
|
||||
---
|
||||
|
||||
### 13.1 实施期偏差（Task 21 收尾时记录）
|
||||
|
||||
按实际落地情况修正设计文档中与最终代码不一致之处：
|
||||
|
||||
| 设计原文 | 实际落地 | 原因 |
|
||||
|---|---|---|
|
||||
| Boss 图共享一个「Boss 骨架」 | **没有骨架，每个 Boss 手写整张 `AiScript` 图**；重复形状抽成 `BossFragments` 的静态建态原语 | Boss 只有个位数且形状差异大，骨架会退化成只服务单个 Boss 的一堆参数 |
|
||||
| `AbilityRunState.Telegraph` 随预警系统一并删除 | **保留**。它现在是 `BlinkStrikeAbility` 的一个执行阶段（现身前的闪光），与已删除的 `TelegraphSystem` 无关 | 该枚举值描述的是能力自身的执行阶段，不是旧预警组件的一部分 |
|
||||
| 阶段信息写入黑板供图读取 | 未引入黑板写入，阶段经 `IAiContext.Boss`（`IBossControl`）**直接查询** | 少一层同步，且非 Boss 访问 `x.Boss` 抛异常这条显式失败更有价值 |
|
||||
| `BossSkillEvent` 事件频道保留 | **随旧轨一并删除**（`BossSkillEventChannelSO` + `BossEvents.BossSkillEvent` + `EVT_BossSkill.asset`） | Task 21 复核确认：全项目零发送方、零订阅方、无任何场景/预制体/Addressables 引用 |
|
||||
|
||||
### 13.2 已知未完成项（本计划范围内确认，但**未做**）
|
||||
|
||||
按严重度排列。这些不是遗漏，是明确记录下来的缺口。
|
||||
|
||||
1. **⚠️ `EnemyHurtState.Enter` 无受击动画时永久卡死（最严重，且与 Boss 轨无关）。**
|
||||
`AnimConfig.Hurt` 为空时提前返回，且**不安排回到 `Controlled`**。任何没有受击动画的敌人被打一次
|
||||
就永久停在 `Hurt` 态：`IsControllable` 恒假、`AiRuntime` 永久挂起、AI 完全停摆。
|
||||
当前美术未接入 ⇒ **大部分敌人一挨打就废**。典型的 CLAUDE.md 第 6 条静默提前返回。
|
||||
Task 15 进 Play 验证时发现。应尽快单独立项。
|
||||
|
||||
2. **战斗本身未经验证。** 动画 clip 尚未接入，`EnemyAttackSO.clip` 留空则该段瞬间完成。
|
||||
已验证的是「能开战、能追击、能选招、能跑完招式、50% 血能换阶段、能悬停、零报错」这条**流程**；
|
||||
**判定时机、伤害数值、手感一律未验证**。clip 到位后必须重新校时序与预警节奏。
|
||||
|
||||
3. **`EnemyBase.ReceiveParry` 无调用方。** 方法本身正确，但 `DamageInfo` 不携带攻击者引用，
|
||||
"谁被弹反谁硬直"接不上。旧的 Boss 侧弹反反制已在 Task 16 删除——它的实际行为是
|
||||
"玩家弹反**任意**敌人都会让 Boss 硬直"，是错的，所以这是**有意的移除且暂无替代**。
|
||||
接线需要在 Combat 层补攻击者引用（见 §6.2）。
|
||||
|
||||
4. **池化敌人复活时带着上一条命的能力冷却。** `EnemyBase.OnSpawn` 里
|
||||
`_abilities.InterruptAll(InterruptReason.Dead)` 的注释写着「重置能力冷却」，但
|
||||
`EnemyAbilityBase.Interrupt` 在 `!_isRunning` 时提前返回，真跑到时又是**设置**
|
||||
`_cooldownEndTime = Time.time + cooldown * 0.5f` 而非清零。冷却从未被重置。
|
||||
修法：加 `EnemyAbilityBase.ResetCooldown()`，`OnSpawn` 遍历调用。影响全体池化敌人。
|
||||
|
||||
5. **`BrainBuilder.Build()` 不校验「非终态是否有出边」。** 只校验正向（边指向的态是否已声明）。
|
||||
一个已声明却没有任何出边的非终态会让敌人永久卡住且**零报错**。
|
||||
`BossFragments.PhaseTransition` 按设计不自带出边，正是这类风险的头号候选
|
||||
（`ChaoFengAi` 的 `txDone` 边就是它唯一出口，删了 Boss 永久锁死）。
|
||||
做法：给 `AiStateFragments.Terminal` 加显式终态标记，`Build()` 对「非终态且无出边」抛异常。
|
||||
|
||||
6. **`EnemyAbilityModule` 编辑器总览未写。** 旧的 `BossSkillModule` 编辑器视图随旧轨删除，
|
||||
能力资产目前没有编辑器总览。
|
||||
|
||||
7. **`AiDefinitionValidator` 未写。** 能力引用漏配 / id 拼错目前只能在 Play Mode 里靠肉眼排查。
|
||||
优先级高于第 6 项。
|
||||
|
||||
8. **`BossFragments.MoveToAnchor` 只在 `OnEnter` 采样锚点。** 锚点 Transform 若会移动则不重新取点。
|
||||
与「锚点是固定点」的设定一致，但这是个隐含假设。
|
||||
|
||||
### 13.3 文档处理与残留（Task 21）
|
||||
|
||||
- **删除**：`Docs/Architecture/23_BossSkillModule.md`、`Docs/Design/47_BossSkillSystem.md`
|
||||
（整份描述已删除且从未实现的体系）。删除前已确认全库无 Markdown 链接残留，
|
||||
索引行与关联文档行均已改指本 spec 或新的作者指南。
|
||||
- **修订**：`Docs/Architecture/00_CoverageIndex.md`、`README.md`、`02_EventSystem.md`、
|
||||
`07_EnemyModule.md`（加过时提示 + §11 改为重定向）、`25_CharacterArchitectureOverview.md`
|
||||
（§4 Boss 章节按实际代码重写）、`Docs/Design/README.md`、`19_BossPatternLibrary.md`（加废止提示）、
|
||||
`69_BossDesignBible.md`、`Docs/Standards/AssetFolderSpec.md`（删旧 Boss 技能编辑器条目）。
|
||||
- **保留不动**：`Docs_Dev/` 下的历史计划与验证清单——那是开发过程记录，反映当时状态，改了反而失真。
|
||||
- **仍有残留、超出本次范围**：`Docs/` 里还有约十余处提到 `BossOrchestrator` / `AttackPatternSO` /
|
||||
`TelegraphSystem` 的单行残留（`03_CoreModule` / `10_UIModule` / `11_AudioModule` /
|
||||
`14_NarrativeModule` / `16_SupportingModules` / `01_ProjectStructure` / `Design/00_Overview` /
|
||||
`Design/54_PoiseSystem` / `DesignSpec/07_EnemySystem` / `EditorTools/00_EditorToolsPlan`
|
||||
/ `Architecture_Review.md`）。这些多是跨模块事件表与目录树里的顺带提及，
|
||||
属于更大范围的「文档与代码一致性」清理，应单独立项，不在本计划内假装做完。
|
||||
最关键的两份入口文档（`07_EnemyModule` / `25_CharacterArchitectureOverview`）已加显式过时提示，
|
||||
不会把读者引向不存在的类型。
|
||||
|
||||
Reference in New Issue
Block a user