mtgodot-poc/audit/remediation-roadmap.md

40250 客户端差异修复路线

本文件记录当前修复顺序和调度规则。它是给人和其他 AI 工具读取的当前路线，不替代机器可读的 audit/manifest.json；合同状态、剩余分支和证据以账本为准。

当前基线

统计快照：2026-09-21。

项目	数量
总合同	45
已排除	1
未完全闭合合同	44
未闭合分支条目	224
P0 分支条目	93
P1 分支条目	118
P2 分支条目	13
P3 分支条目	0

这些数量是快照，不是手工修改的真相。每次修复前后都要运行账本刷新和报告脚本，以 audit/manifest.json 的当前内容为准。

修复阶段

阶段 0：账本和调度卫生

• 读取本文件、audit/manifest.json、相关合同和最近的 audit/history.jsonl。
• 先运行 audit_ledger.py refresh --write、report --write 和 validate。
• 将一个合同中的每个剩余分支作为独立的修复目标；修复后必须同步合同、账本和历史。
• 问题/分支 ID 使用稳定格式 <contract-id>/<branch-slug>；历史中只有合同 ID 的旧记录不能证明该合同的所有分支都已完成，首次处理某个分支时要补建具体 ID。
• 如果只是缺少真实服务端、Windows 客户端或视觉运行证据，不要伪装成代码已完成，记录为验证阻塞。

阶段 1：P0 在线核心链路

按完整的用户可玩链路推进：

1. 登录、认证、选人、Loading、进入地图和失败重试：network.login.phase_flow、network.character_select.create_delete。
2. WASD、停止、转向、远程同步、传送和地图切换：movement.keyboard.motion、movement.remote_sync_state、world.map_load_transition、world.reset_cleanup。
3. 攻击、受击、死亡、经验、掉落和拾取：combat.attack_combo_damage、combat.death.exp_drop、item.drop_pickup。
4. 技能释放、动作事件、特效和服务端结果：skill.cast.effect_timing、skill.player_ui_cooldown。
5. 协议分派、重连、安全分支和资源/协议加载：network.packet_dispatch_protocol、network.reconnect_warp、network.security_encoding、resource.pack_locale_proto。

阶段 1 未完成前，不主动扩大 P1 的视觉或外围功能修复范围。

阶段 2：P1 游戏功能

依次处理背包/装备、NPC/任务、社交、目标选择、状态、模型和效果资源。combat.flying_projectile 在这一阶段处理；除非它直接阻塞 P0 或引入回归，否则不提前插队。

阶段 3：P2/P3 平台和表现

处理音频、天气、平台发布、移动端细节和其他不阻塞核心游戏流程的差异。

防止重复修复规则

• 每一轮只设置一个主合同，并为本轮选定一个明确的问题/分支 ID；可以同时修复被它直接调用的跨合同根因，但必须在历史中列出关联 ID。
• 同一个问题/分支 ID 不得重复修复或重复审计，除非出现新的回归、实现文件发生实质变化，或新增证据证明原结论不成立。
• 同一合同可以在后续轮次继续处理，但必须选择不同的 remaining 分支；合同是功能分组，不是问题去重单位。
• 一个合同仍为 PARTIAL 不代表此前修改无效；只处理其 remaining 中尚未闭合的分支，不能重新审计已通过的测试路径。
• 每轮开始前必须检查 audit/history.jsonl，确认本轮问题/分支 ID 没有已完成记录；如果历史记录不够细，先补充问题 ID，再开始修改。
• 每轮结束必须记录：参考调用链、当前调用链、修改的分支、修复前失败证据、修复后测试、剩余阻塞和下一轮候选。
• 下一轮候选按 P0 → P1 → P2 → P3 排序；同优先级按用户可玩链路和阻塞关系排序，不按“最容易修改”排序。

完成门槛

单个分支只有同时满足以下条件才可关闭：

1. 40250 完整调用链和当前实现调用链已对齐。
2. 前置条件、分支、算法、状态顺序、单位、时序、资源、协议副作用和清理行为均有等价证据。
3. 有修复前失败、修复后通过的自动测试；必要时覆盖拒绝、打断、重复包、死亡、重连和地图切换。
4. 需要真实服务端、Windows 客户端或视觉证据时，已完成对应验证；否则保持 PARTIAL 并记录阻塞原因。

合同只有在全部剩余分支关闭后，才能从 PARTIAL 提升为 STATIC_VERIFIED 或 TEST_VERIFIED。

下一轮

下一轮主合同固定为 network.login.phase_flow，具体处理其尚未闭合的问题/分支。除非发现新的 P0 回归或登录链路被其他合同阻塞，否则不切回已处理过的问题。

上一轮已闭合分支：network.login.phase_flow/auth-game-phase-matrix/peer-close-login-owner。 真实 /logout 已证明建立连接后的 peer close，AppFlow 现在按 40250 回到唯一 LoginPhase owner； 不得重复修改“保留 GameScene/自动重连遮罩”这一已闭合分支。

上一轮已闭合分支：network.login.phase_flow/auth-game-phase-matrix/phase-close-server-fixture。 本地等价 fixture 已证明显式 PHASE_CLOSE 不再伪造 disconnected；真实服务端主动 PHASE_CLOSE 包序仍是证据阻塞，后续只在获得新 live fixture 时验证，不重复修改 native owner。

上一轮已处理分支：network.login.phase_flow/auth-game-phase-matrix/empty-role-live-fixture。 已补充 net_classic_e2e 的 MT_CLASSIC_EXPECT_EMPTY=1 只读探针；当前账号仅有部分空槽， 不能将其当作全空角色证据，也不要通过删号制造 fixture。全空角色的正向 live 证据仍保持在 remaining，后续只在获得安全 fixture 时验证，不重复修改本地 SELECT owner。

上一轮已处理分支：network.login.phase_flow/login-failure-retry-cleanup/login-form-retry-owner。 已按 40250 LoginWindow.Connect -> AccountConnector.Connect 增加 LoginPhase retry owner；登录失败后 只替换认证 transport，不再由 AppFlow 重试触发全局 disconnect_from_server/world_reset。本地 UI/source 断言和 native loopback 包序已通过；真实 Windows 可视化重试和服务器“失败->重新输入->成功”仍是证据阻塞， 不得重复修改该 owner。

前一阶段首选分支：network.login.phase_flow/auth-game-phase-matrix/cross-phase-retry-order。 下一步只处理跨阶段失败/重复进入的真实或等价包序：失败后旧 auth/game stream 的迟到包、重复 PHASE_LOGIN/PHASE_AUTH 的替换顺序、以及完整 UI retry 的真实服务端证据；优先补测试和 fixture， 不要重新审计已经由 direct-enter-loading-select-packet、gc-warp-live-package-order、peer-close-login-owner 或 phase-close-server-fixture 闭合的成功进入、peer-close owner 和显式 PHASE_CLOSE transport-owner 分离链路。

本轮已处理该分支中的认证成功尾包子路径：GC_AUTH_SUCCESS 后的旧 PHASE_AUTH 会随旧 AccountConnector 接收缓冲一起丢弃，不重复发送 CG_LOGIN3。后续必须使用新的稳定子分支 network.login.phase_flow/auth-game-phase-matrix/cross-phase-retry-order-game-login-stale-tail 处理游戏登录失败后的迟到 phase；不得重复修改认证成功的清理边界。

本轮已处理 cross-phase-retry-order-game-login-stale-tail：游戏 LoginPhase/SelectPhase/ Loading 自有包在当前应用帧完成后按 40250 phase-local return 停止，迟到 receive tail 延后到 下一次处理周期；Loading 转交 GamePhase 的包仍保留游戏批处理语义。后续应选择新的稳定子分支 处理真实失败后重新输入成功、重复进入包序或服务器主动 PHASE_CLOSE live 证据，不得重复修改 本轮 return_after_current_packet 机制。

本轮已处理 network.login.phase_flow/auth-game-phase-matrix/auth-connect-immediate-failure-owner： 认证地址解析/socket 同步失败与异步 OnConnectFailure 统一回到 40250 的 Offline owner，并保留 登录重试资格。不得重复修改本轮 handle_auth_connect_failure() 的认证清理边界。

本轮已处理 network.login.phase_flow/auth-game-phase-matrix/game-connect-immediate-failure-owner： 普通认证成功后的游戏连接失败现在走独立 OnConnectFailure -> LoginWindow owner，DirectEnter 和 GC_WARP 失败走 ClosePhase -> SetLoginPhase，不再触发凭据 OnLoginFailure 或伪造 disconnected。修复前 DirectEnter/普通 game-connect fixture 均有失败断言，修复后 native、 Godot bridge、CTest、ASAN 和阶段/包结构审计通过；不得重复修改本轮 handle_game_connect_failure()、connect_failed signal 或 GC_WARP owner 分离。

本轮已处理 network.login.phase_flow/auth-game-phase-matrix/auth-connect-bridge-owner：按 40250 AccountConnector::OnConnectFailure -> Offline -> LoginWindow 修复初始认证同步/异步 连接失败的 M2Client bridge，新增独立 connect_failed 回调、保留认证 session 和 retry_login owner；修复前专项桥接测试失败，修复后 native/CTest/ASAN/Godot 与阶段/包结构 审计通过。不得重复修改本轮 on_auth_connect_failure、classic_auth_connect_failure_pending 或认证 session 保留逻辑。

本轮已处理 network.login.phase_flow/auth-game-phase-matrix/auth-peer-close-bridge-owner：按 40250 CAccountConnector::OnRemoteDisconnect -> __OfflineState_Set 增加认证 peer-close 独立 callback；M2Client 不再把认证 socket 被动关闭伪造成 login_failed 或 connect_failed， 并保留非终态 LoginPhase owner。修复前后均由真实本地 TCP 接受/关闭/再次替换 transport 的 Godot 回归固定；不得重复修改本轮 on_auth_remote_disconnect 或 classic_auth_remote_disconnect_pending。

本轮已处理 network.login.phase_flow/auth-game-phase-matrix/phase-close-disconnect-login-owner： 重新拆分 40250 的 PHASE_LOGIN -> CPythonNetworkStream::SetLoginPhase 与 PHASE_CLOSE/OnRemoteDisconnect -> Python networkmodule.SetLoginPhase -> net.Disconnect 两种 语义；只有真正的 PHASE_LOGIN 会在当前 transport 上发送 CG_LOGIN/CG_LOGIN2，显式关闭、peer close 和 DirectEnter 失败会清理旧 transport 并回到 LoginWindow owner。net_classic_session_test 的修复前 失败、修复后无旧连接登录包/旧 transport Offline、CTest/ASAN/Godot 回归均已固定；不得重复修改 enter_login_phase 的发送分支或本地 PHASE_CLOSE owner。真实服务器主动 PHASE_CLOSE 包序仍需 live 证据。

本轮已处理 network.login.phase_flow/login-failure-retry-cleanup/game-peer-close-retry-owner： 按 40250 OnRemoteDisconnect -> SetLoginPhase -> LoginWindow 与后续 LoginWindow.Connect -> ConnectToAccountServer 的 owner 边界，游戏态 peer close 现在保留同一 ClassicSession 的显式重试资格；重试只替换认证 transport，新的 PHASE_AUTH 只发送一份使用新密码的 CG_LOGIN3，不再回退到全局 session/world teardown。修复前失败和 loopback 替换 transport 回归已记录； 不得重复修改 m_login_retry_pending 的游戏 peer-close owner。真实 Windows LoginWindow 时序、真实服务端 失败后重试成功包序和完整跨阶段 retry 仍需 live 证据。

下一主候选：network.login.phase_flow/auth-game-phase-matrix/live-package-order/server-initiated-phase-close。 本地结构和 owner 分支已覆盖，下一轮只取真实 Windows/40250 服务端证据：失败后重新输入成功、 服务器主动 PHASE_CLOSE、完整跨阶段 retry 和 DirectEnter/GC_WARP 失败回退包序；不要回到已关闭 的认证或游戏连接失败 owner。

本轮已执行该候选的真实 /logout 探针并登记为 network.login.phase_flow/auth-game-phase-matrix/live-package-order/server-initiated-phase-close： 登录到 PHASE_GAME、执行命令、peer close、world reset 和 LoginPhase owner 均通过，但 MT_NET_TRACE=1 没有出现 phase -> 0。服务端 DESC::SetPhase(PHASE_CLOSE) 的源码状态链已 确认，当前 build 因 close 后的 DESC::Packet guard 没有提供客户端可观察的 PHASE_CLOSE 包， 因此不能用客户端改动伪造这个证据。外层 wrapper 的失败仅来自既有 4 个 ParticlesShaderRD/RID 泄漏门禁。除非更换服务端 build/fixture，否则不要重复 /logout 探针；下一步改为获取真实 PHASE_CLOSE fixture，并在同一 fixture 上完成失败重试和跨阶段包序审计。

本轮新增并闭合本地分支： network.login.phase_flow/auth-game-phase-matrix/auth-success-game-before-auth-clear。 对照 40250 __AuthState_RecvAuthSuccess -> SetLoginKey -> MainStream.Connect -> AccountConnector.Disconnect 发现当前 ClassicSession::pump() 曾反向执行 auth disconnect 再 game connect；修复后使用 loopback 双 transport 状态回调固定为 game:connecting -> auth:offline。该分支不得重复修改。下一主候选仍是 新的真实失败后重试/跨阶段包序 fixture；如服务端 fixture 没有变化，不重复 /logout。

本轮新增并闭合本地分支： network.login.phase_flow/auth-game-phase-matrix/game-login-retry-process-boundary。 对照 40250 CPythonApplication::Process -> CPythonNetworkStream::Process -> CAccountConnector::Process 发现认证成功后当前端在同一 pump 再次处理新游戏流；修复后重试期间保留旧主流的处理机会， 认证成功建立替换流后延迟到下一 pump 才处理新流。该分支不得重复修改；真实服务端失败后重试 成功包序和 Windows LoginWindow 仍是未验证证据，下一候选继续选择新的 live/跨阶段分支。

本轮新增并闭合本地分支： network.login.phase_flow/legacy-text-wire-encoding/ui-gb2312-input-capacity。 发现 native 已按 UTF-8 -> GB2312 转换后的 wire 字节校验，但 CharSelectScreen 仍按 UTF-8 字节限制角色名输入，导致“龙驹简体中文免费版”在 UI 层被提前拒绝。现改为 UI 只做 Unicode 字符/控制字符校验，实际 24-byte GB2312 容量由 native 发包边界统一判断，并加入 UI/native 回归；不得重复把角色名 UI 改回 UTF-8 字节限制，也不得把地图名、任务名、系统提示套用该 24-byte 字段限制。

本轮新增并处理分支： network.login.phase_flow/ticket-slot-warp-order/direct-enter-failure-login-owner-reset。 对照 40250 OnConnectFailure -> ClosePhase -> net.Disconnect -> SetOffLinePhase，修复 DirectEnter/GC_WARP 失败回到 LoginPhase 时残留 m_direct_enter、导致替换 PHASE_LOGIN 跳过普通角色列表清理的问题；修复前失败测试和修复后通过证据已登记。真实 Windows/服务端 失败回退包序仍是 PARTIAL，下一轮继续获取新的 live fixture，不重复修改本地 ClosePhase owner。

本轮新增并处理分支： network.login.phase_flow/auth-game-phase-matrix/phase-close-login-retry-owner。 对照 40250 PHASE_CLOSE -> networkmodule.SetLoginPhase -> net.Disconnect -> LoginWindow.Connect 补齐显式关闭后的 retry owner；同一 ClassicSession 现在可替换认证 transport，收到新的 PHASE_AUTH 时只发送一份 CG_LOGIN3。真实服务端 PHASE_CLOSE 包序和完整跨阶段 retry 仍是 live 证据阻塞，不能据此关闭整个登录合同。

本轮新增并处理分支： network.login.phase_flow/auth-game-phase-matrix/phase-handshake-reentry-owner。 对照 40250 RecvPhasePacket(PHASE_HANDSHAKE) -> SetHandShakePhase 和 CAccountConnector::__AuthState_RecvPhase -> __HandshakeState_Set，补齐认证/游戏 HandShake owner 重入；从 Loading/Game 重入时先执行旧 phase-leave world 清理，后续只有新的 PHASE_LOGIN/PHASE_AUTH 才能继续登录。真实 Windows/服务端重试包序仍未闭合；不得重复修改 本轮的 PHASE_HANDSHAKE owner 和 world-leave 边界。

本轮新增并处理分支： network.login.phase_flow/auth-game-phase-matrix/auth-success-result-authority。 对照 40250 __AuthState_RecvAuthSuccess 的 bResult 分支，修复当前端把 login_key == 0 额外解释为凭据失败的问题；成功/失败现在只由 result 决定，票据值仍交给后续游戏连接。 真实服务端不会主动构造成功零票据包，不能用该本地边界测试替代完整 live retry 或安全模块证据； 不得重复修改本轮的认证结果判定条件。

本轮新增并处理分支： network.login.phase_flow/auth-game-phase-matrix/auth-phase-close-silent-owner。 对照 40250 CAccountConnector::__AuthState_RecvPhase 只处理 PHASE_HANDSHAKE/PHASE_AUTH 的分支表，修复当前端把认证 PHASE_CLOSE 错误转成游戏侧 phase_closed 和 auth server closed phase。认证 close 现在保持 AUTH owner，直到真实认证 socket disconnect/failure；不得重复修改本轮的认证 close 静默语义。服务器主动 PHASE_CLOSE 的 live 包序仍需外部 fixture，不能用本地 phase 注入替代。

本轮新增并处理分支： network.login.phase_flow/auth-game-phase-matrix/phase-select-reentry-owner。 对照 40250 RecvPhasePacket(PHASE_SELECT) -> SetSelectPhase -> m_phaseLeaveFunc.Run()， 修复当前端从 Game 返回 Select 时未清理旧地图 world、未通知宿主 phase-leave 的差异；现在先执行 Game owner 的 reset_for_map_change() 和 on_phase_leave，再安装 Select/DirectEnter owner。 该分支不得重复修改；真实 Windows/服务端跨阶段 retry、服务器主动 PHASE_CLOSE 和 GC_WARP 失败回退包序仍需 live fixture。

本轮新增并处理分支： network.login.phase_flow/auth-game-phase-matrix/phase-dead-noop-time-sync。 对照 40250 RecvPhasePacket(PHASE_DEAD) 的显式空分支，修复当前端先打开 time-sync mode、 导致后续重复握手错误发出 CG_TIME_SYNC，以及清除显式 PHASE_CLOSE owner 标记的差异；现在 PHASE_DEAD 不改变阶段 owner 或 time-sync 状态。该分支不得重复修改；完整跨阶段 retry、 服务器主动 PHASE_CLOSE、空角色 live 和 GC_WARP 失败回退包序仍需独立证据。

2026-09-22：本轮临时切换主合同到 movement.keyboard.motion

network.login.phase_flow 的剩余分支目前全部卡在真实 Windows 客户端/服务端主动 PHASE_CLOSE 包序证据或第三方闭源安全 SDK（Matrix/Passpod/Panama/HybridCrypt/HS/XTrap）， 本地代码层面已无可继续推进的动作。按阶段 1 的可玩链路顺序（登录 → 移动 → 战斗 → 技能 → 网络），本轮改为处理 movement.keyboard.motion。

本轮新增并闭合分支：movement.keyboard.motion/camera-auto-follow-rotation。 对照 40250 CPythonPlayer::NEW_MoveToDirection 的 m_isCmrRot 相机跟随分支（每帧对按住 的方向键，把相对相机的方位角折算到 fRotRat∈[-90,90] 并按 m_fCmrRotSpd=20.0 的速率用 CCamera::Roll 持续转动相机），当前端此前完全没有实现这个副作用。已在 player_controller.gd 新增 _camera_auto_rotate()，用同样的折叠/缩放公式驱动 GameCamera.yaw；D3D Roll 与 Godot yaw 转向手性相反，增量符号作为显式记录的平台适配 取反，用『按住方向时相机朝该方向收敛、正前后不转、从不越界』的不变式在 keyboard_motion_timeline_test.gd 中核验（因为没有真实 Windows 客户端可供逐位对照）。 详见 audit/contracts/movement.keyboard-motion.md 的 Implementation fix round 2026-09-22 小节。不得重复修改本轮的 _camera_auto_rotate() 折叠公式或符号约定，除非 出现新的 live 证据推翻当前的收敛不变式假设。

本轮过程中额外发现但未修复（已记录进合同 Remaining 与本文件供下一轮参考）： CActorInstance::CanAct() 的 Paralysis/Faint/Sleep 三个移动门当前端完全没有接入 （net_play.gd::_can_process_network_state() 只挡 dead/stunned/knock_down）。这三个 状态的触发源分别在萨满技能、Python 侧角色模块和效果可见性绑定，尚未定位到当前端对应的 服务端 affect 管线，属于比相机分支更大的独立子项，不要在没有先做好触发源映射的情况下 仓促接线。

movement.keyboard.motion 合同仍为 PARTIAL：根运动/AccumulationMovement、 OnMove/OnMoving/OnWaiting/OnStop 资源事件源、同步/受击/死亡/传送门叠加顺序、上述 Paralysis/Faint/Sleep 移动门和真实模型姿态测试仍未闭合，下一轮可以在这些分支中任选一个 继续（AccumulationMovement 根运动差异或 Paralysis/Faint/Sleep 移动门是其中两个具体、 无需真实服务端/客户端证据即可推进的候选）。

network.login.phase_flow 的下一主候选仍保持文件前面记录的 network.login.phase_flow/auth-game-phase-matrix/live-package-order/server-initiated-phase-close： 本地结构和 owner 分支均已覆盖，只等新的真实服务端/Windows fixture；在没有新 fixture 前不要 重复 /logout 探针或重复修改已闭合的 owner 分支。