SoulHarvest Codex 协作规范

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

一、工作原则

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

二、多人模式的权威链路

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

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

遵守以下约束：

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

三、战斗与动画时序

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

四、代码修改边界

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

六、验收清单

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

七、向用户交付时的说明

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

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

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