# SoulHarvest Codex 协作规范

本文件适用于整个 `SoulHarvest` 仓库。目标不是“让代码通过编译”就结束，而是把用户描述的游戏行为完整实现，并在相应的单人或多人环境中验证后再交付。

## 一、工作原则

1. 先确认用户要求的具体行为，再定位代码。不要顺手调整用户未要求的伤害数字位置、UI、数值、贴图、攻击范围或其他表现。
2. 修复或开发请求默认包含实现与验证。不要只分析原因，也不要在存在安全、明确的推进路径时停下来等待确认。
3. 先检查 `git status --short`。工作区中的既有改动均视为用户或其他任务所有；只修改本任务必需的文件，不覆盖、不回退、不格式化无关文件。
4. 优先用 `rg` 搜索文件和调用链，用小而明确的补丁完成修改。避免大范围机械重构，除非用户明确要求重构。
5. 每次修改都要回答三个问题：
   - 真正的游戏逻辑由哪一端执行？
   - 状态如何同步到其他客户端？
   - 如何证明实际效果发生了，而不只是字段发生了变化？
6. 用户要求“验证后交付”时，没有实际运行证据不得宣称通过。无法完成某项运行验证时，必须明确说明缺少的验证，不得用“理论上没问题”代替。

## 二、多人模式的权威链路

涉及攻击、伤害、Buff、灵魂、能量、冷却、位移和掉落时，优先梳理完整链路：

`客户端输入意图 -> 服务端校验 -> 服务端创建/授权攻击 -> 服务端命中结算 -> 服务端修改状态 -> 同步客户端 -> 客户端播放表现`

遵守以下约束：

1. 伤害、Buff、灵魂奖励、能量、冷却与掉落必须以服务端为权威。客户端数据包只能表达输入意图，不能提供可信伤害、进度、Buff 结果或角色数值。
2. 服务端应从服务器持有的玩家、装备和人物进度重新生成 `SickleCombatSnapshot`，不能接受客户端快照覆盖权威状态。
3. `ReceiveExtraAI` 在服务端仍需完整读取网络数据以消费数据包，但不得用客户端内容替换已授权的服务端战斗状态。
4. 服务端生成的重要弹幕应完成配置、授权与同步。优先复用仓库现有的 `ReaperProjectileHelper.SyncNewProjectile`、`ConfigureReaperProjectile` 和服务器授权模式。
5. `Main.dedServ` 下不得访问贴图、SpriteBatch、声音、粒子或图形设备。视觉代码必须与服务端结算分离。
6. 不要在服务端命中回调中，于 Buff、资源或归属结算之前提前 `return`。如果多个钩子可能负责同一效果，应把权威结算集中到可幂等调用的方法中。
7. 对训练假人单独检查。泰拉瑞亚的假人命中在多人模式下可能不完整触发常规弹幕回调；若使用服务器几何补偿，补偿必须执行与真实命中相同的 Buff、能量和领域效果，并防止重复结算。
8. NPC 的灵魂归属要在伤害发生前或最迟在权威命中时登记，以免一击击杀先于 `OnHit`。击杀测试必须检查玩家灵魂余额确实增加并已同步。
9. 修改 `MyPlayer.Souls` 等人物绑定状态前，确认 `ServerCharacterStateReady`。如果状态尚未就绪，不要静默丢失奖励；应修复初始化或延迟结算链路，而不是绕过服务端权威。
10. 所有新增同步字段都要同时检查初始化、发送、接收、晚到包、重复包、断线和专服路径。

## 三、战斗与动画时序

1. 玩法判定和视觉动画使用同一个可同步时钟，避免客户端已经攻击而服务端仍在前摇，或视觉尚未完成但伤害已经发生。
2. 前摇阶段必须显式关闭伤害、派生弹幕、位移攻击和命中副作用；前摇结束后才进入原攻击时间线。
3. 若玩家在前摇期间松开蓄力键，应保留合理的输入意图，但不能让整次攻击无效果。至少保证动画完成后执行设计要求的最小攻击段。
4. 攻击持续时间、连段阻塞条件、物品复用时间和服务器授权间隔必须一起检查。不能只延长视觉计时而让下一次点击提前创建另一把武器。
5. 视觉随机应由可重现的种子驱动，例如弹幕 identity、动作 ID 和阶段。多人客户端应看到一致的主要构图；纯装饰粒子可以本地随机。
6. 新视觉只能改变用户要求的形态和动作。不要让死神形态的特效泄漏到其他镰刀、终极技或非战斗物品展示中。
7. 使用现有贴图制作碎片、遮罩或裁切时，优先在客户端运行时生成并缓存；卸载模组时释放运行时纹理。不得在专服创建纹理。
8. “有特效”不等于“功能完成”。每个动作都分别验证：前摇、完整武器凝聚、实际命中、伤害、Buff、能量、派生弹幕、结束与再次使用。

## 四、代码修改边界

1. 修 Bug 时优先修根因和权威边界，不用增加客户端补丁来掩盖服务端缺失。
2. 共用逻辑应抽成小型、命名明确的方法；需要重复调用时确保幂等，例如同一动作对同一 NPC 根实体只结算一次。
3. 不改变现有公开存档格式、人物进度或网络协议顺序，除非任务确实需要。若必须改变，发送端和接收端应在同一补丁中完成，并验证旧状态的安全默认值。
4. 新增调试测试放在 `#if DEBUG` 或现有自测框架内，不得让测试命令、测试 NPC 或遥测进入 Release 行为。
5. 注释解释“为什么必须这样做”，尤其是专服例外、网络时序和引擎钩子差异；不要用注释重复代码表面含义。
6. 不使用破坏性 Git 命令，不删除未知文件，不回退用户改动。只终止本任务明确启动的测试进程，绝不批量结束用户正在运行的 tModLoader。

## 五、验证顺序

按风险由低到高执行；出现失败先修复，再继续下一层。

### 1. 静态检查与编译

- 检查修改文件的 diff，确认没有无关变化、重复分支、调试残留或客户端 API 泄漏到专服。
- 先执行不打包编译，例如：
  `dotnet build SoulHarvest.csproj -c Debug -p:BuildMod=false`
- 编译警告若由本次修改引入，也应处理。

### 2. 专服自动验证

- 优先扩展 `Common/ReaperDedicatedServerSelfTest.cs` 中的现有测试，而不是创建孤立脚本。
- 自测必须同时覆盖正向结果与禁止时序，例如：
  - 前摇期间不能造成伤害或生成攻击弹幕；
  - 前摇结束后必须产生权威攻击；
  - 命中后目标实际拥有对应 Buff；
  - 击杀后玩家灵魂余额按预期增加；
  - 客户端伪造或未授权弹幕不能在服务端存活；
  - 同一动作不能重复奖励能量或灵魂。
- 断言实际 NPC、玩家和弹幕状态，不要只断言私有布尔值。

### 3. 真实单人验证

- 检查视觉中心、武器锚点、碎片重组、左右翻转、攻击中心和伤害中心是否一致。
- 检查不同攻击速度、连段阶段、按住与轻点、松开和连续使用。
- 确认修改没有影响伤害数字位置、HUD、其他镰刀或终极技。

### 4. 真实多人验证

至少用一个专服和一个客户端完成实际攻击，不仅运行服务端空玩家单元测试。根据任务检查：

- 服务端接受正确输入并拒绝未授权输入；
- 房主、远端玩家和旁观客户端看到一致的主要动画；
- 普通敌人和训练假人均能正确触发对应效果；
- Buff 图标/状态、伤害、灵魂、能量和冷却在服务器与客户端一致；
- 高延迟或晚到同步包不会导致无攻击、卡住、重复攻击或 180 帧等待；
- 玩家松开按键、死亡、切换物品或断线后，控制器和 held projectile 能正确清理。

### 5. Release 构建与交付

- Debug 与运行验证通过后再构建 Release `.tmod`。
- 若用户正在运行游戏导致已安装模组被锁定，使用独立 `-tmlsavedirectory` 构建验证；不要结束用户进程。只在目标文件可安全替换时更新正式 Mods 目录。
- 最后再次检查 `git diff --stat` 和关键 diff，确认交付内容只包含本任务及已存在的用户改动。

## 六、验收清单

一个战斗修复只有同时满足下列条件才算完成：

- [ ] 单人逻辑正确；
- [ ] 专服权威逻辑正确；
- [ ] 客户端只负责输入与表现，没有决定伤害或资源；
- [ ] 普通敌人与训练假人路径都已检查；
- [ ] Buff、灵魂、能量、伤害和冷却均验证实际结果；
- [ ] 前摇期间无攻击，完成后攻击正常；
- [ ] 视觉中心、伤害中心和同步时钟一致；
- [ ] 其他形态、UI、伤害数字位置和既有素材未被误改；
- [ ] Debug 编译和适用的自动测试通过；
- [ ] 真实单人/多人运行证据已记录；
- [ ] Release 模组成功构建并放到明确的交付位置。

## 七、向用户交付时的说明

使用简洁中文，先给结果，再给验证证据。至少说明：

1. 修复或实现了哪些可观察行为；
2. 关键修改文件；
3. 实际执行了哪些编译、专服、单人和多人测试，以及结果；
4. Release `.tmod` 的路径或当前无法覆盖的原因；
5. 若仍有未验证项，明确列出，不能写成“全部通过”。

不要把实现过程堆给用户，也不要用“应该、理论上、大概”代替验收结果。