game-group/gplan-2
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

收尾(迭代44批后收尾): 反馈点六条处置闭合——①architecture落文六条: ui_registry/RoundCycle/BattleFacts三行现状化(已建件-迭代44,四件类变量3/9/5/14与ModalFlow随容器构造实况,两新件构造句按实态=三参直构/零参直构,实测值8·3/15·4换代)+装配节两句实况(ModalFlow先在座/shot与fx_shot取证探针随批改址)+main_ui_build行层序事实源句改指ui_registry.LAYER_CONTRACT+ui.apply_layer_contract+S13测量面注销句现状化(收尾现行形态=run()尾每批一次,申报剥离凭据215da315/v1.1重裁在案)+S13豁免第三条注销句转已实施(宿主实测15);附带main_overlay_flow行模态口指址刷新(root.ui.modals.flow.open/close——与头注词面修复合拍,验收审计缺漏2同族);②gdstyle基线refresh收账(--refresh --force,16→5键): 消失=main.gd49/orchestrator38+文件长1035/tune_sim await/board_cell_unit30/standee_body19五键清偿+iter42归绿6键离账(board_view allocation+_paint_cell三键/level_runner _enter_node),重登记=留债三键按实测28→23/32→31/50→33,零新增键(布局批新码gdstyle全净);③目检两项登记体验验证清单㊷(三屏切换与模态开合/战斗一局全流程观感);④产出物退役十件(吸收即死+证据只留最新): iter44实现报告/反哺点/验收审计+组合根注册面/战斗编排归约/测速循环三卡+组合根注册面/战斗编排类变量归约/测速循环去await三设计过程稿+grilling五卡复核——全部判据核过: 反馈点11条全处置(1-6落文/7 refresh本笔执行/8条件性观察无未决随本笔备案/9净零/10被条目删除覆盖/11迁待办新条),遗留义务全迁移(目检㊷/refresh基线/头注已修/死preload登记),引用面=roadmap行保留字+战斗域条目改git提交号;⑤账面: 零豁免五键清偿批条目整条删除(五键全清+两迭代合回+refresh收账,状态机出口),战斗域结构深拆批条目净零重立(宿主瘦身子项完成记实况引bee73db5,原卡片引用随退役改git提交号——多子项条目与卡片死期规则的闸机结构冲突按net-zero先例解),main.gd死preload八条新登记(直改类待执行),roadmap迭代44行卡片/报告两列退役保留字+当前位换代(迭代1-44全完成,下一步=iter45收尾)

Browse Source
This commit is contained in:
DKChan committed 2026-10-31 05:12:31 +08:00
1 parent 4b174877be
commit 9eedf8965d
16 files changed
+42 -1747
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

design/engineering/architecture/architecture.md
+8 -8
View File
@@ -121,8 +121,8 @@
| **RewardGrant**（`core/reward_grant.gd`，B1 域·奖励授予件，2026-10-26 编排域拆件设计定稿——实现批建件） | 奖励授予唯一兑付管线（自 battle_orchestrator 收编 grant 族）：极性字典路由与封印溢价兑付（_grant_routed）、三种行应用（flat/percent/gp）、伤害单据提交面（_submit 族）、清图奖励与身份授予、秘宝使用编排（use_treasure 四步）、战斗域 GP 缓冲 escrow 与授予段暂存伤害闸（_defer_board_damage/_deferred_board） | use_treasure 编排入口（treasure_interact_controller 经组合根现值回调直连）；授予入口（结算段类直调）；只读投影（escrow 读与 GP 掉落合计——宿主呈现快照与 _roll_gp_drop 消费） | B4 RewardEconomy（polarity_row/grant）；B1 域 DamageController（开单）；BattleFxHost 引用（treasure_used 事件发射与计数器消耗）；A2 minesweeper（校验回调/fx_reveal/remove_mines_in）；A3 action_economy（相位闸/grant_ap/queue_ap_delta）；B3 status_container（apply_effect/池读）；B2 unit_container（hero_unit/heal）；ConfigDB；注入 emit Callable、宿主 fatal Callable（battle_result 状态机唯一写点留宿主）、宿主 attune 读投影（_attune_safe_seen）、encounter 账本引用；TreasureItems 经宿主 setter 转发注入（库存注入时序在宿主构造之后） | 无（零随机零 await——授予期零随机口径，roll 值授予前已定） |
| **damage_controller**（B1 域·伤害单据管线） | 伤害单据唯一兑现管线（单据九栏目声明→分量掷点/克制修正/伤害下限归一→明细行发射；双方同规） | 兑付入口（编排侧开单）＋ fx 揭示回调注入位 | B2 单位实例（单据目标传入）；B1 注入（EffectContext 引用束与编排回调） | 无 |
| **BoardInstaller**（`core/board_installer.gd`，B1 域·装板域件，2026-10-29 尾波清偿批设计闭合——实现批建件，细则见「战斗编排域拆件定稿」节轴丙） | 棋盘安装与变异布置域唯一承载（自 battle_orchestrator 收编装板族六函数）：生成受理、全局作用域变异决议、资源摇号资格域组装（roll_board 恰一次）、region 变异决议与连通片布置；BoardGenerator 实例随件自建自接线（宿主成员退役）——宿主侧装板后状态复位（封印/完美计数清零、板序推进、board_changed 发射、秘宝叠加层退役）留宿主薄壳，时序逐字保持 | `install(during_round) -> bool` 单入口；构造＝引用束注入（rng/db/minesweeper/reward_economy/encounter 只读引用＋宿主 fatal Callable——防 _init max-parameters 新键） | A1 board_generator（件内持有）；A2 install_board；B4 roll_board/board_skew 写；A4 变异决议行集经 ConfigDB；board_gen／variant_place 两封闭流随件、流名与开流时点零漂移 | 无（零 await——装板全同步） |
| **RoundCycle**（`core/round_cycle.gd`，B1 域·轮循环驱动件，2026-10-29 设计闭合——实现批建件） | 轮循环驱动域唯一承载（自宿主收编 7 成员）：结算五段段件持有与驱动、重入门闸、开轮摇号、踩雷账 | 构造＝引用束注入；段驱动入口由宿主接线调用 | B1 宿主；settlement/ 五段段类；A3 相位读 | 无 |
| **BattleFacts**（`core/battle_facts.gd`，B1 域·战斗事实件，2026-10-29 设计闭合——实现批建件） | 战斗事实域唯一承载（自宿主收编 14 成员）：受理事实（encounter）、轮 facts 缓冲（reveals/seals/path）、封印判定账、事实溯源、同调快照读面；attune 状态两成员随件（行为函数留宿主） | 构造＝引用束注入；宿主与段类经注入引用读写 | B1 宿主；A2/A3 只读 | 无 |
| **RoundCycle**（`core/round_cycle.gd`，B1 域·轮循环驱动件，已建件——迭代 44） | 轮循环驱动域唯一承载（自宿主收编 7 成员）：结算五段段件持有与驱动、重入门闸、开轮摇号、踩雷账 | 三参直构（host/fx_host_ref/reward_grant_ref——五段构造透传不落成员）；段驱动入口由宿主接线调用；实测类变量 8／公开方法 3 | B1 宿主；settlement/ 五段段类；A3 相位读 | 无 |
| **BattleFacts**（`core/battle_facts.gd`，B1 域·战斗事实件，已建件——迭代 44） | 战斗事实域唯一承载（自宿主收编 14 成员）：受理事实（encounter）、轮 facts 缓冲（reveals/seals/path）、封印判定账、事实溯源、同调快照读面；attune 状态两成员随件（行为函数留宿主） | 零参直构；宿主与段类经注入引用读写；实测类变量 15（贴顶）／公开方法 4（reset_round＋三 mark 写口） | B1 宿主；A2/A3 只读 | 无 |
| **settlement/ 五段段类**（B1 域·结算段件） | B1 每轮结算序列的五段逻辑件（授予/增益减益/战斗/衰减/判定——细则见下「战斗域装配现状」节） | 段处理入口（B1 接线调用）；可直接 `new()` 单测 | B2/B3/B4 兑付面与 B1 轮 facts 缓冲（各段按职责） | 无 |
| **level_runner**（C1-lite，切片已建） | 关卡域生命周期（节点链推进、共享 B4 + HP 携带、关卡末 level_clear） | 节点推进接口；LevelTable（`level.tres`——节点 enum {battle,reward,rest,boss}、末节点必须 Boss、ConfigDB 跨表校验⑧） | B1（直构 BattleOrchestrator 接线战斗）、ConfigDB LevelTable | 无 |
| **run_structure**（C2） | 冒险/关卡序列、失败重开、**master_seed 唯一接线方** | （契约规范源：`../../gdd/systems/冒险循环/冒险结构.md`） | RngService.set_master_seed、C3/D2 | 无 |
@@ -164,15 +164,15 @@
|---|---|---|---|---|
| **D1 HUD**（呈现面拆分持续换代：组合根 main.gd + 三屏壳（MenuScreen/CampScreen/AdventureScreen）+ views/ 视图单元（现行承载面见「呈现层装配与会话生命周期」节；早期 9 单元清单与 LevelStripView 已随场景换代退役）；营地覆盖层=四柜台并排〔树淬炼主界面/锻造工坊·秘宝匣钥匙门/图鉴常开——迭代 21 T6 程序占位重排〕） | 全部 Control/CanvasLayer（例外：BoardView 棋盘本体与 BattleStageView 站桩本体 = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界〔BoardWorld/CellUnit；StageWorld/StandeeBody——B 区 slot_row 伴随件留壳层〕，探针契约面不变——棋盘 Node2D 迁移批 Phase A 2026-09-23 / 战斗舞台 Phase B 2026-09-26）、输入→意图翻译（**唯一提交路径 = settle_batch，不直调 A3**）、呈现义务状态记录（A2×6 / B2×4 / B3×4 / B4×5 / B1×3） | 视图单元接口（信号外发、setter 只读注入） | A2 compute_move_path / ActionOutcome；A3 ap/rap；B1 步骤流行协议（数据源）；ConfigDB display_name | **MEDIUM**：Control / CanvasLayer / draw_* / InputEvent / RichTextLabel——对照 breaking-changes.md 4.5–4.7 条目（CanvasItem 线条无抗锯齿羽化、设备 ID 常量、RichTextLabel 图片参数两轮变化） |
| **组合根拆件**（呈现侧写口子件：curio_interact_controller / camp_shop_presenter / treasure_interact_controller） | 代组合根执行核心写调用（冒险节点后续推进／营地购买与刷新／道具使用——依赖与回调由 main 构造注入） | 各拆件的写入口（仅组合根装配面可达；视图零直连） | 构造注入的核心写引用（推进／商店／道具各域——详见各拆件头注） | 无 |
| **ui_registry**（`presentation/ui_registry.gd`，界面注册面，2026-10-29 零豁免裁设计闭合——实现批建件） | 呈现层接口面唯一承载：层序合同（LAYER_CONTRACT）迁驻与合同寻址、三域句柄容器 ui_screens（9 屏壳与覆盖层句柄）／ui_battle（5 战区句柄）／ui_modals（13 模态句柄＋ModalFlow）；组合根经其一级寻址接线，探针挂载假设迁移为 `main.ui.<域容器>.<句柄>`；七个探针别名/转发成员随批消灭 | 三容器属性＋合同寻址口（RefCounted 门面，不挂树、零会话期引用） | 构造注入：三屏壳、覆盖层、战区句柄、ModalFlow（main_ui_build 交付随之改型） | 无（RefCounted） |
| **ui_registry**（`presentation/ui_registry.gd`，界面注册面，已建件——迭代 44） | 呈现层接口面唯一承载：层序合同（LAYER_CONTRACT）迁驻与合同寻址、三域句柄容器 ui_screens（9 屏壳与覆盖层句柄）／ui_battle（5 战区句柄）／ui_modals（13 模态句柄＋ModalFlow）；组合根经其一级寻址接线，探针挂载假设迁移为 `main.ui.<域容器>.<句柄>`；七个探针别名/转发成员随批消灭 | 三容器属性＋合同寻址口（RefCounted 门面，不挂树、零会话期引用）；四件（UiRegistry/UiScreens/UiBattle/UiModals）类变量 3/9/5/14，ModalFlow 随 UiModals 容器构造即建 | 构造注入：三屏壳、覆盖层、战区句柄、ModalFlow（main_ui_build 交付随之改型） | 无（RefCounted） |
| **board_hover**（`views/board_hover.gd`，悬停预承诺呈现域件，尾波清偿批 D2 设计闭合——实现批建件） | 悬停反馈域唯一承载（自 board_view 收编 11 函数族＋_hover/_last_click 两成员）：三语义光标、目标格边框、BFS 路径预览、chord 双击首遇锚；_r0 出生展开区成员留宿主 | 构造＝引用束注入（cells/minesweeper/diggable 引用＋光标写入与 hover_forbidden 注入回调）；三入站口留宿主委托；hover_probe 读面留宿主 | board_view（宿主）；输入事件经宿主入站口 | 无（RefCounted） |
| **cell_base_layer／cell_mark_overlay**（`views/`，单格两绘制域件，2026-10-29 设计闭合——实现批建件） | 单格绘制域拆分（自 board_cell_unit 状态件 `_CellPaintState` 收编，入参与该层绘制命令同件）：基座层（底面/描边/立面/投影/接触带/倒角，12 成员）与标识叠加层（标记/字形/徽章/封印/点迹/高亮/退色，13 成员）；宿主 _draw 退为六步时序器，类变量 30→10 | 构造注入；绘制命令由宿主 _draw 按层序调用 | board_cell_unit（宿主）；gdstyle 键各文件独立计数（12/13 均 ≤15） | 无（RefCounted） |
| **standee_vitals／standee_motion**（`views/`，站桩两状态件，2026-10-29 设计闭合——实现批建件） | 站桩状态域拆分（自 `_StandeeState` 真实 25 成员收编）：身份命值（hp/atk/状态值族，12 成员）与资产演出（动作/姿态/位移演出族，11 成员）；三个演出探针计数器留宿主，宿主类变量 19→10 | 构造注入；st（沿用）／mo 两实例由宿主持有 | standee_body（宿主）；battle_stage_view 写入面逐字保持 | 无（RefCounted） |
| **HudPresenter**（`presentation/hud_presenter.gd`，迭代 37 加注） | 战斗屏**数据投影＋文案拼装静态族**——核心状态→呈现文案的全部翻译集中于此（B/C/D 区文案与投影），静态无状态 | `refresh(…)` 全量重查装配（组合根每次动作/结算返回后调用，漏调即陈旧呈现）＋只读静态投影族 | 核心读取只走 `settlement.presentation_snapshot()` 成文快照面（禁链式穿透结算内部）；ConfigDB display_name | 无（RefCounted 静态） |
| **board_resolvers**（`presentation/board_resolvers.gd`，迭代 37 拆出） | 棋盘每格渲染数据的只读解析回调四函数（奖励徽章身份——挖掘期 Active 相位内、地形变异数字遮蔽与角标、调试加成生效值）——有态绑定件，与无态静态投影族 HudPresenter 职责互斥 | 构造注入 db、调试浮窗与结算活态取值，产出绑定 Callable 供组合根接线 | ConfigDB / DebugOverlay / 结算活态取值 Callable | 无（纯投影） |
| **main_ui_build**（`presentation/main_ui_build.gd`，迭代 37 拆出） | `_build_ui` 八步拆分件——组合根 UI 装配分步承接（三屏壳实例化、视图句柄接线、覆盖层装配与模态编排注入按步拆开）；main 侧留同名薄委托，装配序与 z 序零改动 | 分步静态函数（成员访问经 root 显式传入） | 层序逻辑不在此件——唯一事实源仍是 `main.LAYER_CONTRACT` + `_apply_layer_contract()` | 同 D1（Control 装配面） |
| **main_ui_build**（`presentation/main_ui_build.gd`，迭代 37 拆出） | `_build_ui` 八步拆分件——组合根 UI 装配分步承接（三屏壳实例化、视图句柄接线、覆盖层装配与模态编排注入按步拆开）；main 侧留同名薄委托，装配序与 z 序零改动 | 分步静态函数（成员访问经 root 显式传入） | 层序逻辑不在此件——唯一事实源＝`ui_registry.LAYER_CONTRACT`＋`ui.apply_layer_contract(root)`（迭代 44 迁驻注册面） | 同 D1（Control 装配面） |
| **main_adventure_flow**（`presentation/main_adventure_flow.gd`，迭代 37 拆出） | main 冒险流程族——菜单开局/续玩后的冒险编排接线、节点事件分发、终局面与选路屏开合；逐字搬运，main 侧留同名薄委托（探针 `main.X` 路径零迁移） | 流程静态函数（root 显式） | 局态全局住 run_scope 节点——本件零成员态、零新增信号连接（连接语句随原段搬运） | 无 |
| **main_overlay_flow**（`presentation/main_overlay_flow.gd`，迭代 37 拆出） | main 浮层流程族——设置/状态面板/生涯页/选档界面/图例/钱包事件的开合与数据投喂；逐字搬运，main 侧留同名薄委托 | 流程静态函数（root 显式） | 全部开合走组合根模态单口（`root._open_modal/_close_modal`）——本件零成员态 | 同 D1 |
| **main_overlay_flow**（`presentation/main_overlay_flow.gd`，迭代 37 拆出） | main 浮层流程族——设置/状态面板/生涯页/选档界面/图例/钱包事件的开合与数据投喂；逐字搬运，main 侧留同名薄委托 | 流程静态函数（root 显式） | 全部开合走组合根模态编排口（`root.ui.modals.flow.open/close`）——本件零成员态 | 同 D1 |
| **main_debug_flow**（`presentation/main_debug_flow.gd`，迭代 37 拆出） | main 调试流程族——调试浮窗开合与上下文同步、批量模拟入口、两层调试对局起手、诊断转储；逐字搬运，main 侧留同名薄委托 | 流程静态函数（root 显式） | 调试会话状态机归 debug_session.gd——本件只接线与出 UI，零成员态 | 同 D1 |
| **TilePalette**（`presentation/views/tile_palette.gd`，迭代 37 拆出） | 瓦片排版/装载：高墙/地面瓦片整批装载与运行时镜像合成、地板明度归一、数字墨族按板自适应判据、格坐标确定性散列与十六正交情形墙瓦片查表 | 查表族（读件持棋盘引用——棋盘视图 rebuild 经 `bind_board` 同步）；装载缓存七成员持于件内（同板型零重载、换板重载时序同源） | 零绘制面、零玩法数据写入（绘制调用面留棋盘视图）；纹理路径单点在件内 | Resource 纹理加载——LOW |
| **HeroSprite**（`presentation/views/hero_sprite.gd`，迭代 37 拆出） | 英雄精灵四态与落位装配（落位与位移演出、撞墙帧闪、挖掘弹跳、脚底锚与持握手位出口） | 由棋盘视图 `_init` 建为子件（注入世界根与壳层容器引用）——精灵本体经世界根 ensure_hero 建于 SubViewport 世界内，本件只驱动其状态 | BoardWorld 世界根；素材缺位=零精灵（棋盘视图字形「人」回退路径在役） | Node2D / create_tween（Tween 系 Node 方法——MEDIUM 域对照 breaking-changes.md） |
@@ -190,7 +190,7 @@
### 三屏壳与组合根句柄面
- 呈现场景拆为三屏壳：MenuScreen（开始菜单屏）／CampScreen（营地屏）／AdventureScreen（冒险屏——内含关卡地图与战斗两容器）。
- 屏成员寻址自实现批起迁经界面注册面（**2026-10-29 零豁免裁＋注册面设计闭合——实现批建件**）：探针挂载假设 `main.X` 迁移为 `main.ui.<域容器>.<句柄>`（ui_screens／ui_battle／ui_modals 三域容器，约 867 处探针与系统测试引用随批改址）；原 S13 豁免登记〔2026-10-27「组合根类变量面即探针契约面」〕注销；main.gd 类变量 49→15，注册面形态见「模块归属·呈现层」表 ui_registry 行；局态一律住 RunScope 节点，禁在屏/视图侧持有局态引用。
- 屏成员寻址自实现批起迁经界面注册面（**已建件——迭代 44**）：探针挂载假设 `main.X` 迁移为 `main.ui.<域容器>.<句柄>`（ui_screens／ui_battle／ui_modals 三域容器，约 867 处探针与系统测试引用随批改址）；原 S13 豁免登记〔2026-10-27「组合根类变量面即探针契约面」〕注销；main.gd 类变量 49→15，注册面形态见「模块归属·呈现层」表 ui_registry 行；ModalFlow 实例随 UiModals 容器构造建立（装配早期注入点依赖其先在座）；取证探针 shot_probe／fx_shot_probe 随批改址；局态一律住 RunScope 节点，禁在屏/视图侧持有局态引用。
- **组合根拆件**＝组合根构造注入、代组合根执行核心写调用的呈现侧子件（现行三件：curio_interact_controller／camp_shop_presenter／treasure_interact_controller——冒险节点后续推进、营地购买与刷新、道具使用）。视图禁直连拆件；核心写调用的可达路径仍是「视图→信号→组合根（含拆件）→核心」，依赖规则与组合根单点装配不变。成员见「模块归属·呈现层」表。
### 视觉层装配合同
@@ -318,9 +318,9 @@
本节为测试域（测试载体、判定口径、静态扫描域）的事实源。新增违规案例仍须先补 static_scan 规则再修码（code-conventions 缺陷-规范对照表纪律）。
**S13 测量面豁免注销（2026-10-29 零豁免裁）**：原循环内 `await` 豁免〔2026-10-27〕注销——tune_sim_controller 改 process_frame 信号常驻连接＋步进状态机（每帧一局、帧相位逐点对齐，设计闭合、实现批建件）；随批申报行为改动一处：运行态收尾由「每局置假」还原为「整批收尾单次置假」（消除与 wd8/ui_tune_probe 断言面的静态矛盾）。
**S13 测量面豁免注销（2026-10-29 零豁免裁）**：原循环内 `await` 豁免〔2026-10-27〕注销——tune_sim_controller 改 process_frame 信号常驻连接＋步进状态机（每帧一局、帧相位逐点对齐，已建件——迭代 44 卡③）；运行态收尾现行形态＝run() 尾每批一次执行（卡③ v1.0 申报的「每局置假还原」前提已被迭代 41 测试债批 215da315 先行消化，行为改动申报随 v1.1 停卡重裁剥离）。
**S13 豁免第三条注销（2026-10-29 零豁免裁）**：原 battle_orchestrator max-class-variables 豁免〔2026-10-28 迭代 40 卡①〕注销——RoundCycle/BattleFacts 两新件设计闭合（宿主 38→15，实现批建件，见「战斗编排域拆件定稿」节轴丁）。
**S13 豁免第三条注销（2026-10-29 零豁免裁）**：原 battle_orchestrator max-class-variables 豁免〔2026-10-28 迭代 40 卡①〕注销——RoundCycle/BattleFacts 两新件设计闭合（宿主实测 15，已建件——迭代 44 卡② 合回，见「战斗编排域拆件定稿」节轴丁）。
**gdstyle 计数截断缺陷登记（2026-10-29 两设计批独立实证）**：gdstyle v0.4.0 对文件内 inner class 的成员计数存在截断——内嵌类中带行尾注释的属性声明截断其后续成员计数（standee_body 实测 31 声明仅记 19、board_cell_unit 33 仅记 30）。基线登记值属欠估；闸机扫描与基线同源、判定口径自洽不误报，债的真值以实查为准——零豁免各批按真实口径设计（实数低于阈值，不依赖解析缺陷）。登记待办：向 gdstyle 上游报 issue。
game/presentation/main_overlay_flow.gd
+1 -1
View File
@@ -1,7 +1,7 @@
## VERTICAL SLICE - NOT FOR PRODUCTION
## 组合根覆盖层流程承接件：设置/状态面板/生涯页/选档界面/图例/钱包事件的开合与数据投喂。
## 本件是 main.gd 同名函数的逐字搬运（成员访问改 root 前缀）——main 侧留同名薄委托，探针 main.X 路径零改动。
## 全部开合走组合根模态单口（root._open_modal/_close_modal）；本件零成员态。
## 全部开合走组合根模态编排口（root.ui.modals.flow.open/close）；本件零成员态。
extends RefCounted
static func _open_settings(root: Variant) -> void:
reports/iter44-反哺点-2026-10-30.md
-26
View File
@@ -1,26 +0,0 @@
# 迭代 44 反哺点清单——2026-10-30
要写进权威文档的点逐条列落点（改哪一节、改成什么、依据）；用户在会话中裁决后归文档批落文。实现批禁写 `design/` 与根规则文件，本清单是唯一移交通道。
## 架构文档（design/engineering/architecture/architecture.md）
1. **「模块归属·呈现层」ui_registry 行现状化**——现登记「实现批建件」态；实现后改现状陈述：UiRegistry/UiScreens/UiBattle/UiModals 四件已建（全 RefCounted、类变量 3/9/5/14、UiModals.flow 随容器构造即建）。
2. **同表 main_ui_build 行「层序逻辑不在此件——唯一事实源仍是 main.LAYER_CONTRACT + _apply_layer_contract()」句失效**——唯一事实源已迁 `ui_registry.LAYER_CONTRACT`＋`ui.apply_layer_contract(root)`；该句改指 ui_registry（依据＝设计文档 §3.3 建议句＋实现实况）。
3. **「呈现层装配与会话生命周期」节屏成员寻址迁注册面句核对**——v1.25 已预写「探针挂载假设＝main.ui.<域>.<句柄>」；实现实况与其一致，但需补两句实况细节：①ModalFlow 实例随 UiModals 容器构造建立（装配早期注入点依赖其先在座）；②探针契约面新增两件取证探针（shot_probe/fx_shot_probe）随批改址。
4. **「战斗编排域拆件定稿」节轴丁两行「构造＝引用束注入」句与实态口径差**——实态＝RoundCycle 三参直构（host/fx_host_ref/reward_grant_ref，五段构造透传不落成员）、BattleFacts 零参直构；句按设计文档 §8 预判「三参直构无需束」现状化。
5. **「模块归属·功能层」RoundCycle/BattleFacts 两行实测值换代**——RoundCycle 类变量 8／公开方法 3；BattleFacts 类变量 15（贴顶）/公开方法 4（reset_round＋三 mark）；宿主 battle_orchestrator 实测 15 成员/811 行（文件长键 1035 已远超实况——基线 refresh 后自然消失）。
6. **「测试与质量域」S13 豁免第三条注销句现状化**——v1.25 预写「设计闭合、实现批注销」；键账已达成（宿主实测 15），注销句转已实施事实。**同节 tune_sim 测量面豁免注销句现状化随卡③ v1.1 恢复**：裸键已消除（实测命中消失、全文件零循环）；注销句保持（注销对象是 await 豁免、不依赖行为改动申报），句内「随批申报行为改动一处（收尾置假还原）」半句已失效（前提被迭代 41 测试债批 215da315 消化、申报已剥离）——现状化时一并修正为收尾现行陈述（「运行态收尾在 run() 尾每批一次执行」）。
## gdstyle 基线与闸面（tools/）
7. **基线 refresh 义务（用户人工，非落文）**——`python tools/gdstyle_gate.py --refresh`：预期消失键＝main.gd max-class-variables=49（实测 15）＋battle_orchestrator max-class-variables=38（实测 15）＋battle_orchestrator max-file-length=1035（实测 811）＋轴丙遗留归绿键；合计消失 ≥2 条触发骤降守卫，须 `--force`。与待办清单「零豁免五键清偿批」批末一次人工 refresh 合并执行。
8. **S13 no-self-assign 检查的误报形态观察**（登记不阻塞）——`X.y.z = y` 形态（赋值链尾名与右侧成员同名）被判自赋值；本批以 self 前缀消解（level_runner:520）。若后续批次再现此巧合，可考虑工程批把检查器改为比较完整接收链（登记归「迭代 42 批末移交小件」同类工具小件）。
## 待办清单（根流程清单——状态回退拟稿，落笔归上游段/用户）
9. **「零豁免五键清偿批」条目测速循环批子项状态（净零处理——原回退拟稿作废）**：卡③ 停卡呈报→用户裁重裁→写卡会话重写 v1.1（零待裁点，重裁时订正 S8 十文件与两处行号注记）→本会话恢复施工收口——条目状态直推「文档设计已闭合＋已写卡＋已编迭代 44」无回退中间态；重裁经过实况记录于实现报告 §5/§5.1，本条不再承载状态回退义务。
10. **「零豁免五键清偿批」条目键账进度换代**——五键中两键已真实清偿（main.gd 49→15、battle_orchestrator 37→15），待基线 refresh 收账；呈现层状态件批（迭代 45 在册）两键不受影响。
## 其他
11. **main.gd 死 preload 存量**（工程小件登记建议）——拆件遗留的零使用 preload 常量 8 条（UiAssembler/TuneSimController/DebugSessionScript/TreasureInteractController/CurioInteractController/CampShopPresenter/BoardResolversScript/三场景 preload 中 main 零使用者）；本批仅清理与迁移直接相关的 ModalStack/RowPacer 两条，其余属存量债不扩范围；归工程改动直改批顺路清理。
reports/iter44-实现报告-2026-10-30.md
-118
View File
@@ -1,118 +0,0 @@
# 迭代 44 实现报告（组合根注册面批＋战斗编排归约批＋测速循环批）——2026-10-30
状态：三卡全部施工收口（卡③ 按停卡呈报建议案重裁为 v1.1 后施工）；迭代总收口（批末闸/审计/合并）进行中。
## 0. 各卡状态
| 卡 | 状态 | 提交（worktree iter44，基点 c8f5091d） |
|---|---|---|
| 卡① 组合根注册面批 | **收口**——main.gd 49→15、四新件建件、全消费面改址 | bee0682f（T1 建件）／b89ee850（T2 改形）／784d581b（T3 改址）／1929516a（T4 消灭收口） |
| 卡② 战斗编排归约批 | **收口**——battle_orchestrator 38→15（实测 37 轴丙基数起算）、RoundCycle/BattleFacts 两新件 | 24f3ca51（T1 BattleFacts）／a832965a（T2 RoundCycle）／15c833e0（T3 宿主收束）／3e9d3afa（T4 键账） |
| 卡③ 测速循环批 | **收口（v1.1 重裁后施工）**——v1.0 停卡呈报→用户裁重裁→v1.1 剥离行为改动申报面后 T0–T3 全落 | c82ef23f（T1 步进状态机）／04783fae（T2 对拍套件） |
## 1. 卡① 实际对照表（卡片 §8 十一行 → 实况）
| # | 需求点 | 改动实况 | 验收测试实况 | 结果 |
|---|---|---|---|---|
| 1 | 注册面建件＋合同机器迁驻 | ui_registry.gd（LAYER_CONTRACT 逐字迁入＋node(key) 19 键 match＋apply_layer_contract 唯一落位口）＋ui_screens/ui_battle/ui_modals 三容器 | 系统测试 V1c（system_test.gd:94-106 改址 main.ui.LAYER_CONTRACT／main.ui.node，尾缀〔装配生命批 V1〕保留）——树序逐对保序 | 绿 |
| 2 | main.gd 改形回归（49→15） | 28 迁出＋7 消灭＋1 新增＝22（T2 中间态）→15（T4 终态）；六转发方法＋_flush_row_queue 退役 | run_smoke 15 项 0 失败＋run_system_test 69 项 0 失败；S13 静态判据＝gdstyle 实测 15（基线键 49 已不命中、成死键） | 绿 |
| 3 | 装配与流程件改址 | main_ui_build 八步赋值目标 root.ui.*（八步顺序/add_child 序/连接语句逐条不变）；三流程件同表映射；smoke_boot get() 4 改 2 留 | 冒烟主屏存活面六断言＋系统测试 V2 句柄等价五连比（system_test.gd:108-109 改址） | 绿 |
| 4 | 探针面批量改址 | 探针九件＋probe_ui_util＋shot_probe/fx_shot_probe（决定记录 2）共约 460 行机械改写 | probe_gate --click --full 全段退出码 0（九件 PASS） | 绿 |
| 5 | 系统测试面改址＋RunScope 生命周期 | system_test V1a/V1c/V2/V3 矩阵取址改指 | V1–V9 全绿（V3a–V3i 存活性矩阵第五引用面逐面同源） | 绿 |
| 6 | 别名/接缝成员消灭（7 个） | _seed_edit/board_view/ap_bar/_row_queue/_modals/_settlement_stop_pending/_deferred_modal 全删；消费方改址（pacing_queue 4 处＋接缝探针三件＋main 自身） | pacing_queue 绿＋ui_struct_probe 登记序断言（改 flow.stack）＋t17_defer_probe 挂起态断言（改 flow._deferred） | 绿 |
| 7 | 六转发模态方法退役 | _open_modal/_close_modal/_on_modal_closed/_input_locked/_open_modal_after_playback/_on_pump_ended 退役；调用方改指 ui.modals.flow 五真方法＋pump_ended 注入改 flow 方法 | modal_flow 绿＋系统测试 V3g 模态开合段＋ui_click_probe 模态开合路径 | 绿 |
| 8 | V1d 源码断言重锚 | source_guard_test.gd 重锚全 presentation 目录扫描（move_child 只许 ui_registry.apply_layer_contract 体内），尾缀〔注册面 V1〕 | source_guard 绿（8 checks） | 绿 |
| 9 | V6 源码断言改串 | theme_projection_test.gd V6 改断言 ui.modals.debug_overlay.diagnose_requested.connect(_on_diagnose_pressed)，尾缀〔注册面 V2〕 | theme_projection 绿（164 checks） | 绿 |
| 10 | 视觉零变化主证 | 全批呈现层改址零像素改动 | render_gate golden 零差异（shot_probe 七屏＋golden 全过） | 绿 |
| 11 | 改址完整性收口 | 49 名逐名 grep 残留=0（词形态＋字符串键形态两轮全量扫描，T3 提交信息留档） | 批末代码域闸归迭代总收口（待跑）；grep 自检静态判据已留档 | 静态部分绿 |
静态判据申报执行实况（卡片 §8 域口径）：S13 键账对账＝gdstyle 实测 main.gd 15、四新件零新键（T1/T4 两轮 static_scan 确认）；基线 refresh 留用户人工（见 §4 遗留义务）。
## 2. 卡② 实际对照表（卡片 §11 V0–V6 行 → 实况）
| 行 | 需求点 | 改动实况 | 验收测试实况 | 结果 |
|---|---|---|---|---|
| V0 | 行为零变化（总判据） | 成员迁移与改指；RNG 五流零触碰（behavior_roll 随件迁移取号序逐字）；五信号留宿主；两快照签名载荷逐字 | 关联套件全绿零改址应红项（round_flow/settle_segments/skill_unlock/trigger_cond/seal_polarity/feat_vouchers/variant_placement/meta_forge/adventure_feats/treasure_effects/roll_multiplier/breakpoint_resume/level_shop_economy/table_structure_guard） | 绿 |
| V1 | 两新件建件接线 | battle_facts.gd（15 成员贴顶＋reset_round 逐字＋三 mark 写口）＋round_cycle.gd（8 成员＋三参直构＋五段构造逐字迁入） | settle_segments_test V1 断言（_rounds 在座且 oc 回指＋_facts 在座＋五段段件齐 _rounds）〔编排归约 V1〕 | 绿 |
| V2 | reset_round 复位边界 | reset_round 只清 reveals/seals/path 三项 | round_flow_skill_pool_test 内嵌断言：终局后 presentation_snapshot()["refresh_used"] == 末轮结算快照 economy.refresh_used〔编排归约 V2〕 | 绿 |
| V3 | 段驱动与摇号迁移 | 三函数迁出；宿主调用点五处改址；trigger_cond 3 处改指 | round_flow 全套＋settle_segments V4-3＋skill_unlock＋trigger_cond（改指后绿）——同种子回放断言零改址钉住 | 绿 |
| V4 | _hero_atk 派生读 | 成员删→私有函数；combat_segment :56 改调 | roll_multiplier_test 内嵌：override 贯通 spawn＋缺省回退表值〔编排归约 V4〕；攻击单 base_value 贯通由既有 hero_atk_val=100 全链路夹具承载 | 绿 |
| V5 | treasure_inventory 注入改址 | 宿主成员与 setter 删、五处读改指、level_runner:520 改经 reward_grant() 出口直注 | treasure_effects_test 内嵌引用同一性断言〔编排归约 V5〕＋ob8/ob11/ob13 既有 use_treasure 受理链改址后全绿 | 绿 |
| V6 | 封印判定账/装板溯源/受理事实迁移 | 事实族改指（grant_segment 18 处＋宿主全量）；三 mark 写口升级；attune 读源改 _facts | seal_polarity／feat_vouchers（契约 2 计数纯净 R2）／variant_placement／meta_forge／adventure_feats／table_structure_guard（attune 外部面零改址应绿——最硬的外部面零变化证）全绿 | 绿 |
行为改动申报核对：diff 中行为改动零条（全部非行为改动——成员迁移与改指；完美写口升级＝同一时点同一增量改经方法单点）。测试削弱申报：零申报兑现（测试改指只动成员寻址；新增断言 V1/V2/V4/V5 四条＋V1d/V6 重锚两条＝卡片 §8 申报全集）。
## 3. 实现决定记录（代拍板白名单外事项备案）
卡①：
1. **ModalFlow 实例随 UiModals 容器构造即建**（ui_modals._init）——装配第二步 row_pacer.pump_ended 注入早于第八步 flow 建立，转发壳退役后需 flow 先行在座；查询/钩子 Callable 注入时点不变（_build_modal_flow 内语句序不变），八步顺序零变化。
2. **shot_probe/fx_shot_probe 纳入改址**——两件是 render_gate 取证探针、不在卡片「探针九件」清单（probe_gate 段构成），但同为 main.X 一级地址消费方；T3 改址完整性 grep 自检抓漏后纳入（render_gate 对照表行 10 的承载件，属消费面全量改址义务）。
3. **ui_tune_probe 零连接巡检白名单登记 flow.close**——表 D 申报「closed bind 目标改 flow.close.bind」的机检联动：巡检白名单原钉 main._on_modal_closed（组合根转发壳），改钉 main.ui.modals.flow.close（同一连接的新宿主）；判据面「closed 外发消费目标是模态编排口」语义不变，conn_count=11 断言零变化。
4. **layout_probe 三区 get() 字符串键改容器字段键**——卡片表 D 字符串键清单只列 smoke_boot 6 处；layout_probe:60 `main.get(key)`（key="stage"/"info_panel"/"board_zone"）为漏网字符串键，改 `main.get("ui").battle.get(key)`（战区域容器字段名与三区合同键同名）。
5. **curio_overlay/confirm_dialog 两词在装配/流程件替换表漏列**——main.gd 表有、main_ui_build 与三流程件表漏，冒烟（Invalid assignment on main.gd）与 ui_click_probe sl7（开窗调用静默失效）抓漏后补改；教训＝机械改写必须逐词对照 T0 名单全量扫描（T3 终检已按 49 名逐词复查全域归零）。
卡②：
1. **grant_segment._seal_preview_area 的 oc.treasure_inventory 读为 T3 盘点漏项第五处**（卡片 T3 列宿主四处读）——SCRIPT ERROR 抓漏后改指 reward_grant.treasure_inventory。
2. **treasure_effects_test 五处直构注入 obX.treasure_inventory**（ob8/ob11/ob13 注入与读、ob14 段）——设计文档 §11 盘点「1 处」漏项；同属「成员寻址改指、断言零变化」改经 reward_grant() 出口。
3. **level_runner 注入行加 self 前缀**消 S13 no-self-assign 文本巧合（`X.treasure_inventory = treasure_inventory` 左侧链尾名与右侧成员同名）；语义零变化。
4. **_hero_atk 派生读落位**：受理段写点删除、spawn 读点改调、combat_segment 消费改调——「读面即引用、无第二账」先例同款。
5. 宿主内 encounter/attunement 词替换以占位符保护三处字符串键（behavior_roll 前置流名 "encounter"／BoardInstaller bundle 键 "encounter"／enc.get("attunement") 键）——键字面零变化。
## 4. 遗留读数义务与登记项
- **gdstyle 基线 refresh（用户人工，批末总收口后）**：`python tools/gdstyle_gate.py --refresh`——卡① 死键 1 条（main.gd max-class-variables=49）＋卡② 预期死键 1 条（battle_orchestrator max-class-variables=38；文件长键 1035 已由轴丙归绿基线在册需一并核对）＋轴丙遗留归绿键，合计消失 ≥2 条触发骤降守卫须 `--force`（与待办清单「零豁免五键清偿批」批末一次人工 refresh 合并执行口径一致）。
- **实机目检总清单（登记不阻塞）**：①三屏切换与模态开合实机过一遍（卡① T4 义务——冒烟/探针/golden 已机检承载，真人观感复核登记）；②战斗一局全流程观感（卡② 结构迁移零行为变化的一般性目检）。
- **能力清单核对（收尾核对义务）**：本批卡① 零新增能力（改址只换地址）、卡② 零新增能力（新增断言全部内嵌既有函数）——game/tests/README.md 零增删改，批末核对表上代表用例名与实际落地一致（未改名，核对通过）。
- **批末代码域闸**（run_all_gates.sh --code）归迭代总收口——卡③ 裁决后与 reshape 串联执行。
## 5. 卡③ 停卡呈报（缺陷移交——按卡片 §13 L3 条款①预设停机点）
**分歧点**：卡③ §3 断言「`_run_one_level` 尾部两行 :67 `panel.set_sim_running(false)`／:68 `_running = false` 每局执行一次（潜伏红本体）」与现行代码不符——实测两行在 `run()` 尾 :53-54（for 循环外、每批恰一次），`_run_one_level` 尾部 :67-68 实为败局节点记账。
**定谳证据**（三重）：
1. git 历史：迭代 41 测试债批提交 215da315（2026-10-29 合回）提交信息明载「两个产品回归随批修（……**tune_sim 运行态收尾归还 run**）」——潜伏红已由该批先修复。
2. T0 实跑面一：`--only=standee_fx_sweep` 全绿（18 checks）——wd8 三断言（`drv.seen == [true, true]`／收尾双运行态假／报告非空，现位 :145-147）现行全 PASS。
3. T0 实跑面二：ui_tune_probe 全链路 PASS——⑤ 守卫环 1800 帧预算内退出、输出四串在（模拟 N=10 完整输出）。
**两种读法**：
- 读法 A（证据支持）：卡片成文（2026-10-29 v1.0 定稿）时点潜伏红确实在（u23 卷入形态），同日合回的迭代 41 测试债批把收尾归还 run() 尾——卡片「现状考证」被上游批施工消化变质。215da315 提交信息与代码现状一致。
- 读法 B：卡片考证当时即误读（:67-68 为败局记账非置假）。与 215da315 提交信息矛盾，不采。
**影响面**：
- 已申报行为改动 V3（收尾置假还原）**无对象**——还原动作已由迭代 41 测试债批完成并申报。
- 目标 2「wd8 三断言与 ui_tune_probe ⑤ 零改动**转绿**」变「零改动**保持绿**」。
- 核心义务仍有效：S13 await-in-loop 裸键消除（tools/gdstyle_baseline.txt:15 在册、基线 16 键之一）与双实现对拍套件（帧相位等价执行化证据）——对拍夹具与产品码的申报差异由两处减为一处（收尾还原差异消失，仅余 stats 暴露成员）。
- T0「实跑定谳」义务已完成（上列三重证据），实现段零施工（停摆卡不提交）。
**建议案**（供写卡段/用户裁决）：
1. 卡③ 退回写卡段重裁：剥离行为改动申报（对照表 V3 行删、§1 目标 2/3 措辞改「保持绿」）、T0 判读出口改「两面全绿＝前提已由迭代 41 测试债批消化，直接按无行为改动形态开工」；保留裸键消除＋双实现对拍义务（夹具＝现行产品码 await 形态逐字副本——收尾在 run() 尾形态——与产品码唯一申报差异＝夹具暴露 stats 供对拍）。
2. 若用户不愿重写卡：裁「卡③ 剥离出迭代 44」（roadmap 行拆批），裸键消除与对拍随下一迭代重编。
**待办清单条目状态回退拟稿**（落笔归上游段/用户，本批禁写根流程清单）：「零豁免五键清偿批」条目的测速循环批子项状态由「文档设计已闭合＋已写卡＋已编迭代 44」回退为「文档设计已闭合＋待写卡（现状考证已被迭代 41 测试债批消化——行为改动申报面失效，卡片重裁后重编）」。
## 6. 批末全量域闸与闸红修复（收口实况）
**闸况**：reshape 后第三次全量域闸（--code）全绿——00 冒烟/01 系统测试/03 场景探针/05 渲染闸/10 熵增闸绿；**02 单元与集成、09 静态扫描从基线红改善归绿**（基线记的迭代 41 时代存量红指纹已在册待换代——现真绿）；回执 commit 对齐分支尖（b27db010）。
**闸红修复三笔（新红必修，均孤跑复绿）**：
1. S9 R1：tune_sim_controller `_sim_stats` 裸 Dictionary 注解改 `Dictionary[Variant, Variant]`（Variant 参数化现行口径）——本批新码写法违规。
2. ui_input_probe :482/:488 case⑮ 装配直构注入 `settlement.attunement` → `_facts.attunement`——卡② 成员迁移的探针消费漏网（T0 映射谱系只扫 main./root./self. 前缀，直构注入形态不在谱系）；SCRIPT ERROR 中断 _ready 致探针挂死超时。
3. run_time_fatal_test :75 BoardInstaller 束键值 `oc.encounter` → `oc._facts.encounter`＋meta_progression_forge_test 三处编排器 encounter 直读改指（:340/:749/:758）——同型漏网（负面套件名与触面无字面关联＝关联档选测盲区；meta_forge 分片复现、单进程未现的夹具路径差异）。
**实现决定记录补（白名单外备案）**：跨卡触面（卡② 迁移成员被卡① 已改址的探针/未申报套件消费）只有全量闸能抓——关联档选测的盲区实证；全域终扫（encounter/attunement 直读形态）后同类漏网清零。
## 7. 独立验收审计结论与记录级缺漏补记
审计报告：reports/iter44-验收审计-2026-10-30.md——**结论=通过（可合并）**。21 行对照表逐行通过、判据绑定面自跑全绿、测试削弱零发现（37 条被删断言逐条有配对新行）、非行为改动成立、证据链在案。
记录级缺漏三项（不阻塞，随本节补记）：
1. 卡③ 对拍串行驱动为白名单外决定——已在 §5.1 卡③ 实现决定记录 1 备案（审计方读的是早期版本）；提交 04783fae 信息同载。
2. main_overlay_flow.gd:4 头注仍写已退役的 root._open_modal/_close_modal 转发方法名——词面遗留（卡面头注义务只列 main.gd 与 main_ui_build 两处）；闸后代码面禁改（改则回执作废），留反哺点通道随文档批或下一代码批顺路改写。
3. 卡② grant_segment 事实族改指实测 18 处 vs 卡面「约 23」估计偏差——记录偏轻，本节补记（T0 点名清单实数为准）。
例外备案：V1d 扫描面为 presentation 平铺 27 文件口径（与卡面 glob 一致、只扩不缩；递归口径下批前既有 ui_kit.gd:819 即红——非本批引入）。
## 8. 停机状态与收口（进行中）
- 迭代总收口（冻结→并 master→reshape→批末全量域闸→独立验收审计→合并）**未启动**——按停机规则「迭代收口合并须等停摆卡闭合、或用户裁拆批后整体进行」。
- 卡① 卡② 全部收口提交在 worktree iter44 分支（9 笔提交），冻结待收口。
reports/iter44-验收审计-2026-10-30.md
-99
View File
@@ -1,99 +0,0 @@
# 迭代 44 独立验收审计报告——2026-10-30
审计方：未参与实现的独立会话（只读审计＋自跑最窄抽查）。对象＝worktree D:\code\g-plan2-iter44 分支 iter44 尖 9f1dda40，对照基线 master 尖 ab3b4a9d；材料＝三张需求卡片（组合根注册面批／战斗编排归约批／测速循环批 v1.1）＋实现报告＋闸回执与日志。本报告不修改任何代码与测试，缺漏如实记录不代修。
**结论行：通过（可合并）**——三卡 21 行对照表逐行核到落点、判据绑定面自跑全绿、测试削弱零发现（断言计数 22 文件零减少）、非行为改动判定成立、证据链在案；2 项记录级缺漏＋1 处注释级陈旧指址＋4 项例外备案，均不动行为、判据与验收闭合（见 §6），不构成合并阻塞。
## 1. 逐行核对——卡①（§8 十一行）
| # | 判定 | 凭据（文件:行／自跑） |
|---|---|---|
| 1 | 通过 | V1c 改址 `main.ui.LAYER_CONTRACT`／`main.ui.node`（system_test.gd:90/:94，尾缀〔装配生命批 V1〕保留）；自跑 run_system_test 69 项 0 失败；LAYER_CONTRACT 与基线逐字一致（git show ab3b4a9d 对读，唯一差异=注释指址 `_apply_layer_contract`→`apply_layer_contract`，白名单 3） |
| 2 | 通过 | main.gd `^var` 计数 49（基线）→15（尖）；自跑 run_smoke 15 项 0 失败＋run_system_test 69 项 0 失败；gdstyle 零基线外新键 |
| 3 | 通过 | main_ui_build.gd `build()` 八步名序与基线逐字同；`_build_screens` 赋值序/add_child 序不变；42 条 connect 一一对应（仅 :97/:206 两处 closed bind 改 `flow.close.bind`=表 D 申报）；smoke_boot get() 4 改 2 留（settings_store/run_scope 留）；冒烟六断言＋V2 五连比（system_test.gd:108-109）自跑绿 |
| 4 | 通过 | 探针面 diff 归一化对账 88 处非平凡行全部落表 A/C/D＋实现决定 2/3/4；probe_gate 日志全绿（.gates/probe.log 06:53，全段）；ui_tune_probe 审计自跑 PASS |
| 5 | 通过 | system_test 改址全对账（V1a/V1b/V1c/V2/V3 矩阵 `_face_snapshot` mf→`main.ui.modals.flow`、rp→`main.ui.screens.row_pacer`）；V3a–V3i 存活性矩阵自跑全绿（69 项含） |
| 6 | 通过 | 七别名消费方改址逐处对上（pacing_queue 4 处、ui_struct_probe `flow.stack`、t17_defer_probe `flow._deferred`、ui_click_probe `settlement_stop_timer.is_armed()`）；自跑 `--only=pacing_queue --only=modal_flow` 双绿；改后断言判据零变化（归一化对账） |
| 7 | 通过 | 六转发方法＋_flush_row_queue 全库零残留（grep 只余 1 处陈旧头注，见 §6 缺漏 2）；modal_flow 24 checks 绿＋系统测试 V3g 段绿 |
| 8 | 通过 | source_guard_test.gd:69-92 重锚——尾缀〔注册面 V1〕；自跑输出「V1d 层序落位单口（presentation 27 文件——apply_layer_contract 之外 move_child 调用点=0）」；扫描面较改前（单文件）只扩不缩；口径例外见 §6 例外 1 |
| 9 | 通过 | theme_projection_test.gd:725-726 改断言新串 `ui.modals.debug_overlay.diagnose_requested.connect(_on_diagnose_pressed)`，尾缀〔注册面 V2〕；自跑 164 checks 绿 |
| 10 | 通过 | render_gate 日志全绿（.gates/render.log 06:54，shot_probe 七屏＋golden）；diff 零像素面改动（改址只动地址词） |
| 11 | 通过 | 审计独立 grep：49 名旧一级地址 `main./root./self.` 代码级残留=0（仅 3 处注释级命中）；代码域闸日志六件全绿（§5）；留档偏薄见 §6 例外 5 |
## 2. 逐行核对——卡②（§11 V0–V6）
| 行 | 判定 | 凭据 |
|---|---|---|
| V0 | 通过 | 关联套件全绿：审计自跑 8 套件（settle_segments/round_flow_skill_pool/roll_multiplier/treasure_effects/pacing_queue/modal_flow/source_guard/theme_projection）＋批末闸 unit.log 分片全绿（15 suites shard 4/4）；behavior_roll 随件迁移取号序逐字（§4 核对）；五信号留宿主（battle_orchestrator.gd:12-16）；两快照出口在宿主（:677/:739） |
| V1 | 通过 | settle_segments_test.gd:28-29 两断言〔编排归约 V1〕：`oc._rounds != null and oc._rounds.oc == oc`＋`oc._facts != null`（check_quiet 静默通过＝套件 18 checks 零失败）；五段段件齐在 _rounds 由 :30-34 五条既有接线断言改指 `oc._rounds._X_seg` 承载（尾缀〔迭代27 T2〕保留，纯改址） |
| V2 | 通过 | round_flow_skill_pool_test.gd:112-115〔编排归约 V2〕：终局后 `presentation_snapshot()["refresh_used"]` == 末轮结算快照 `economy.refresh_used`（经 settlement_snapshot 末次发射承接）；自跑实跑输出 5 实例（L1·D0×3＋L2·D0×2）全 PASS；reset_round 只清三项（battle_facts.gd:32-35） |
| V3 | 通过 | roll_round_actions 与基线 `_roll_round_actions` 逐行对读一致（仅成员改指；`oc.rng.open_stream("behavior_roll")` 流名与开流时点不变，round_cycle.gd:102）；settle_if_due 闸序 settling→battle_result→phase 逐字、终局早退不回置；trigger_cond_test 3 处改指（:119/:126/:131）；自跑 round_flow 134 checks＋settle_segments＋trigger_cond 全绿 |
| V4 | 通过 | roll_multiplier_test.gd:45-59 四断言〔编排归约 V4〕：override 100→spawn hero_unit atk==100；缺省→hero 表值（check_quiet 静默通过）；攻击单 base_value 贯通由既有 `_hero_attack_row_with`（:343，hero_atk_val=100 全链路停手结算行）承载——两消费点（spawn＋base_value）闭合；combat_segment.gd:56 改调 `oc._hero_atk()`，宿主派生读 :69/:282 |
| V5 | 通过 | treasure_effects_test.gd:311-315〔编排归约 V5〕：`ob14.reward_grant().treasure_inventory == adr14.runner().treasure_inventory` 引用同一性；use_treasure 受理链由 ob8/ob11/ob13 既有段承载（:311 ob8 直写改指后绿）；level_runner.gd:520 注入改经 `reward_grant()` 出口（`self.` 前缀＝实现决定 3） |
| V6 | 通过 | seal_polarity（_perfect 直写→_facts 8 处对读）／feat_vouchers（契约 2 计数纯净段改指后全绿）／variant_placement／meta_forge／adventure_feats／table_structure_guard——批末闸 unit 分片全绿；三 mark 写口（grant_segment.gd:311/:379/:394 与基线直写同点同增量）；attune 三外部消费面零改址（main.gd/treasure_interact_controller/table_structure_guard 均不在改址 diff） |
## 3. 逐行核对——卡③ v1.1（§12 V1–V3）
| 行 | 判定 | 凭据 |
|---|---|---|
| V1 | 通过 | tune_sim_batch_parity_test.gd 五面断言〔测速 V4/V5〕自跑绿（n=3 stats 六键逐键重算＋报告逐字含四关键串；n=0 六键零计）；run 可等待契约由 wd8 `await ctrl.run(2)`（standee_fx_sweep_test.gd:144，零改动）承载；全文件零循环（grep -c "for \|while " = 0）、代码 await 仅 :69 一处 `await _batch_finished` |
| V2 | 通过 | 五面对拍断言〔测速 V1–V3〕自跑绿：帧序列相对偏移逐位＋相邻差恒一（每步恰一帧）、运行态序列逐位＋收尾双假、进度串逐位；n=3＋n=0 两案各 5 断言全 PASS；manifest 增行（run_all.gd:189）；拓扑例外见 §6 缺漏 1 |
| V3 | 通过 | wd8 三断言〔wd8〕自跑 PASS（18 checks：`drv.seen == [true, true]`／收尾双运行态假／报告非空——standee_fx_sweep_test.gd 不在本批 diff＝零改动）；ui_tune_probe 审计自跑 PASS（⑤ 守卫环 1800 帧预算内退出＋输出四串）；收尾四语句迁入 `_finish_batch()`（:87-92）与基线 run() 尾次序逐句同（close→报告→置假→_running），`_run_one_level` 零触碰（不在 diff） |
| 静态 | 通过 | gdstyle_gate.py 审计自跑 exit 0：命中 7 全基线内、基线外新违规 0；基线 :15 `tune_sim await-in-loop` 裸键不命中＝死键（消失键不参与红判定） |
## 4. 测试削弱检查（对照三卡申报全集）
- **断言计数对账**：22 个改动测试/探针文件 `Kit.check|check(|check_quiet` 计数基线→尖逐一比较——零文件减少；仅 5 增（roll_multiplier 36→40＝V4 四断言、round_flow 100→101＝V2、settle_segments 16→18＝V1 两条、treasure_effects 58→59＝V5、tune_sim_batch_parity 0→10＝新套件）。与申报新增面（卡② V1/V2/V4/V5 四条＋卡① V1d/V6 重锚＋卡③对拍五断言）完全一致。
- **删除断言逐条对账**：全 diff 被删 check/断言行 37 条逐条找到配对新行——语义不变只换地址（含 smoke_boot 三 get、system_test V2 五连比、pacing 四断言、V1d/V6 两条）；无任何断言删除后无配对。
- **阈值/扫描面**：零阈值放宽；扫描面唯一改动＝V1d 单文件→27 文件（申报为强化，成立）；static_scan.sh S8/S7 两清单增行 round_cycle.gd（卡② T2 申报；battle_facts.gd 未增行＝卡片明示「零协作调用不入清单」，成立）。
- **换下层直调**：零发现——探针仍走真实按钮/输入路径（pressed.emit/push_input 等既有形态未动）。
- **wd8 三断言**：文件不在 diff＝零改动，自跑保持绿。**ui_tune_probe 巡检白名单**（实现决定 3）：`host == main and m == "_on_modal_closed"` → `host == flow_host and m == "close"`（ui_tune_probe.gd:214-216）——属卡①表 D「closed bind 目标改 flow.close.bind」的机检联动，同一连接新宿主登记；conn_count=11 断言与消息逐字不变（:223-224 与基线 :221-222 对读）；判据面「closed 外发消费目标＝模态编排口」语义保持。**判定：不属削弱**。
- 卡② §15 零申报、卡③ §16 零申报——兑现成立（超出申报的删改零处）。
## 5. 非行为改动判定与证据链
**卡①**：装配序（八步名序、add_child 序、赋值序）逐字不变；42 条连接语句一一对应；LAYER_CONTRACT 19 项逐字迁驻；move_child 单口由 V1d 27 文件扫描绿＋grep 复证（全 presentation 仅 ui_registry :84/:98 两处调用，views/ui_kit.gd:819 为批前既有、不在 diff）；main._ready 仅插入 `ui = UiRegistry.new()` 一行于 _build_ui 之前；`_build_modal_flow` 注入语句序与基线逐字同（flow 实例改随 UiModals._init 构造＝实现决定 1，注入时点不变）。
**卡②**：成员迁移与改指——roll_round_actions/settle_if_due 逐字迁移对读成立；grant_segment 三 mark＝同点同增量；encounter/attunement 词替换的三处字符串键保护（实现决定 5）grep 复证（behavior_roll 前置流名 "encounter" 字面在位）；treasure_inventory 注入时序（宿主构造后 :520）不变。
**卡③**：收尾四语句迁移＝同帧同相位（对拍 V2 运行态序列＋V5 报告逐字承载，自跑绿）；`_run_one_level` 零触碰。
**证据链**：
1. 卡③ T0 三重证据在实现报告 §5 在案：215da315 提交信息明载「tune_sim 运行态收尾归还 run」（审计直读提交信息复证）＋两面实跑读数；审计自跑两面（wd8 套件＋ui_tune_probe）复证现行全绿——前提消化链条完整。
2. 卡③ v1.1 重裁凭据：卡 v1.1 状态行＋§15 裁决记录（2026-10-30 停卡重裁三点）在案。
3. 卡①卡②实现决定记录（报告 §3 共 5+5 条）对照卡① §10 七条、卡② §17 五条白名单——白名单外事项（shot/fx_shot 纳入、layout_probe get 键、curio/confirm 漏列补改、flow 随容器构造、grant 第五处读、treasure_effects 五处直构、self 前缀、占位符保护）均有备案，无遗漏。
4. 闸凭据：receipt.json 现为 docs 域回执（9f1dda40 提交时 pre-commit 钩子生成，b27db010 时代，全绿）；代码域末跑凭据＝.gates 六件日志（smoke 15/0、system_test 69/0、static_scan ok、probe_gate 全绿、render_gate 全绿、unit 分片全绿），时间戳 06:49–06:54 恰落 b27db010（06:49:41 提交）与 9f1dda40（06:57:19 提交）之间——绑定终态代码（9f1dda40 只含报告文件）。
5. 红线：diff 只触 `game/`＋`reports/` 两目录；零 `randomize()`/自建 RandomNumberGenerator；零触及 `design/`、`game/tests/README.md`、两份根流程清单。
## 6. 缺漏与例外（如实记录，不修）
**缺漏（记录级，不动判据）**：
1. **卡③实现决定记录缺位**：对拍驱动由卡 T2 的「先启动两形态、后分别 await」并行拓扑改为**串行驱动＋相对帧偏移归一**（tune_sim_batch_parity_test.gd:145-162）——卡 §14 白名单六条不覆盖，应在实现报告「实现决定记录」节备案；实际只在提交 04783fae 信息中有案（理由＝GDScript 协程动态调用强制 await、无并行启动形态＋_init 时点 root 未挂树实测）。报告 §3 无卡③条目。实质判据未损（相对偏移＋相邻差恒一仍承载「每步恰一帧＋相位同点」，审计自跑绿）。
2. **main_overlay_flow.gd:4 头注陈旧指址**：注释仍写「全部开合走组合根模态单口（root._open_modal/_close_modal）」，两转发方法已退役、实际调用全改 `root.ui.modals.flow.open/close`——「指址须真」词面违例，行为无涉，批内漏改。
3. **卡②改指处数偏差记录偏轻**：grant_segment 实改 18 处与卡片「约 23」的 L2 偏差，实况数在报告 §2 V6 行在案但未入「实现决定记录」节（卡 §14 L2 要求记入该节）。
**例外（依据在案，不判红）**：
1. **V1d 扫描面口径**：实现为 DirAccess 平铺（res://presentation 顶层 27 个 .gd），不含 views/、scenes/ 子目录——与卡片字面 glob（`game/presentation/*.gd`）一致、较改前单文件只扩不缩；但「全 presentation 目录零第二落位点」按递归读法不成立：批前既有 `views/ui_kit.gd:819` 有一处 `body.move_child(...)`（视图内行排序、非层序落位；ui_kit.gd 不在本批 diff、归迭代 42 尾波清偿批在册债）。ui_registry.gd:3 头注「全仓唯一 move_child 点」沿袭旧 main.gd 注释口径、与该既有事实并存。若日后递归化扫描面，须先处置该行。
2. **回执被覆盖**：receipt.json 为 docs 域回执（报告提交钩子生成）；代码域末跑以六件日志为凭（§5 第 4 条），与报告 §6「第三次全量域闸全绿、02/05/09 从基线红改善归绿」叙述吻合。
3. **`_finished` 成员写而不读仍保留**（tune_sim_controller.gd:26/:64/:88）——卡 §14 白名单 3 明示「零读者确认后可删」，保留属白名单内两可选择，键账只升 1（11/15 在阈内）。
4. **报告 row4 计数口径差**：「约 460 行机械改写」（报告 §1）与 784d581b「422 行」——统计口径差，不影响判据。
## 7. 审计自跑记录（独立复证清单）
| 项 | 结果 |
|---|---|
| `python tools/run_smoke.py` | PASS——15 项 0 失败 |
| `python tools/run_system_test.py` | PASS——69 项 0 失败（V1a/V1c/V2/V3a–V3i 全过） |
| `--only=source_guard --only=theme_projection` | 绿——V1d「presentation 27 文件…调用点=0」〔注册面 V1〕＋V6 新串〔注册面 V2〕＋theme 164 checks |
| `--only=settle_segments --only=round_flow_skill_pool --only=roll_multiplier --only=treasure_effects` | 4 套件绿——V1 两断言、V2 五实例、V4 四断言、V5 一断言（check_quiet 静默通过＝零失败） |
| `--only=pacing_queue --only=modal_flow` | 双绿 |
| `--only=tune_sim_batch_parity --only=standee_fx_sweep` | 双绿——对拍 10 断言〔测速 V1–V5〕＋wd8 三断言 |
| `res://probe/ui_tune_probe.tscn`（headless） | PASS——⑤ 守卫环预算内退出＋输出四串＋全链路通过 |
| `python tools/gdstyle_gate.py` | exit 0——命中 7 全基线内、零新违规；tune_sim 裸键不命中 |
| grep：tune_sim 循环／await | 循环 0；代码 await 仅 run() :69 一处 |
| grep：49 名旧一级地址残留 | 代码级 0（仅注释级 3 处） |
| 成员数 | main.gd 49→15；battle_orchestrator 37→15；容器 3/9/5/14 |
| 断言计数对账 | 22 文件零减少、5 增（+4/+1/+2/+1/+10） |
| diff 归一化对账 | 88 处非平凡行对全部落表 A/C/D＋已记录决定 |
## 8. 总结论
**通过（可合并）。** 三卡对照表 21 行全部核到落点且判据绑定面当轮实跑成立；测试削弱零发现；三卡「非行为改动」判定在代码级对读与实跑两面成立；证据链（卡③ T0 三重证据、v1.1 重裁、卡①卡②决定记录、闸日志）在案。缺漏三项（卡③决定记录缺位、main_overlay_flow.gd:4 陈旧头注、卡②计数记录偏轻）与例外四项均属记录/注释级，不触行为零变化、判据绑定与验收闭合；建议随批末收口由实现侧补记（补记动作归收口段，不由本审计代作）。gdstyle 基线 refresh（--force）仍属用户人工遗留义务（反哺点 7 在案）。
reports/复核-grilling-零豁免五卡-2026-10-29.md
-85
View File
@@ -1,85 +0,0 @@
# grilling 复核报告——零豁免五卡（2026-10-29，主会话委派）
状态行：对抗式复核完成。方法＝逐卡过审点 A–J（验收三问／对照表两端／静态判据形态／能力行锚定／预算实数／拆分纪律／编队碰撞／行为改动完备性／裁决一致性／可施工性），判据＝req-card 必备结构 15 节＋code-conventions §1.1＋test-conventions §8；证据＝五卡 file:line 抽验约 90 处（命中率高，个别 1 行漂移属 T0 兜住范围）＋五份设计文档口径核对＋architecture v1.25＋能力清单逐行核对＋gdstyle_baseline.txt 键账清点＋迭代 42 在飞两卡触面比对＋pipeline_gate 全绿。只读复核，未改任何卡与既有文件。
## 卡一：gdstyle 尾波补件批（board_hover＋breakpoint_store）
**裁决：有条件成立**（四项编入前须补，均为编辑级补丁，不动拆件方案本身）。
逐条发现：
1. 【应修】卡面 §7 编队注记——「与呈现层状态件批同代时**推荐**其先行」，而呈现层状态件批 §3 已把同一约束写死为「已裁……本批先于其 board_hover 半边合回」的硬义务。同一约束两卡一软一硬，编排段按弱措辞排卡会让 hover 拆件落在旧 u.st 写入面上、board_view 改址对账表（单格篇 §5.1）随之失配。改法：board_hover 半边改成硬前置句「呈现层状态件批合回后施工」；breakpoint_store 半边明示不受此限、可独立先行。
2. 【应修】§8 V1 判据绑定面写「格件 **st** 边框/点迹字段」——本卡自认编排在状态件批之后，届时该读面已改 u.face.*（ui_input_probe 四处改址为状态件批 V4 行），判据面描述按施工时点必陈旧。改法：改写为「格件状态件边框/点迹字段（状态件批合回后＝u.face.*）」。
3. 【应修】§3 现状事实「公开入口 `resume_adventure`（:94）」行号错——实查 :94 是 start_adventure，resume_adventure 在 adventure_runner.gd:141。改法：改 :141（T0 重锚虽会兜住，现状事实按规约须代码级准确）。
4. 【应修】§13 预算节「预算 2（_hover/_last_click）**＋引用束成员**」「预算 6……**＋引用束**」未给引用束成员数，复核门无法对账 ≤15。按 §7/T2 构造面推算 board_hover 约 7（2＋cells/minesweeper/diggable＋2 Callable）、breakpoint_store 约 14（6＋db/rng/主角账三件/curio/stop/bank/loadout）——均达标但后者贴顶。改法：把引用束成员逐一列名计数写进预算表。
5. 【可接受申报】V1 零漂移证明全压既有断言面；悬停 11 函数族中 chord 双击首遇锚（board_view.gd:475 _detect_chord）在「棋盘悬停反馈」三语义行与 ui_click_probe 之外无显式断言，属既有覆盖缺口。零行为改动批不为既有缺口补测不违规，实现报告宜记一句该缺口。
6. 核验通过项：A 两行对照表三问可答（真实入口/判据面/能力行齐）；C 对照表零静态行；E 键账全对（board_view 32 实数清点吻合、−2=约30；adventure_runner 28 清点吻合、−6=约22；断点域 6 成员与 9 函数族 file:line 全命中；BREAKPOINT_FIELDS :539 起、breakpoint_resume_test.gd:185 命中）；F 拆分职责语句在位、_r0 留宿主防凑计数袋论证成立（board_view.gd:238/:296/:563 三消费方实查）；G 与迭代 42 的 board_view 触面已声明、编入待其合回；I 与裁决①②⑤一致（D5 留债、禁落豁免登记、_r0 留宿主）；J 一步一动作、无 TBD 类句式。
## 卡二：组合根注册面批（main 49→15）
**裁决：有条件成立**（一项 blocker 级必改＋两项应修；机检与数字面全过，方案本身成立）。
逐条发现：
1. 【blocker】§1 编队注记「与迭代 42……**无文件交叠（main.gd 与探针不在其触面）**」与盘面矛盾——在飞并排卡 `reports/需求卡片-level_runner商店委托层拆除-2026-10-29.md` 文件清单明确含 game/presentation/main.gd（改址 1 处）、main_adventure_flow.gd（6 处）、main_overlay_flow.gd（2 处），三者全在本卡触面集（main.gd＋三流程件）。用户裁决④要求五卡编队碰撞约束与迭代 42 自洽，此句是失实声明，编排段靠它排卡。改法：改为「与迭代 42 商店委托层拆除卡在 main.gd／main_adventure_flow／main_overlay_flow 三文件有改址点交叠——待其合回后开工，T0 映射表生成时并核其改址点」；T0 步骤同步补一句。
2. 【应修】§8 对照表第 2 行与第 11 行内含静态判据（S13 键账对账「main.gd 实测 15」、grep 残留=0）——姊妹卡三/四/五均已把静态键账判据按 test-conventions §8.4 出口移出对照表（在域口径段申报），本卡两行在表内带静态成分，形态不一致。改法：静态部分移入 §8 域口径静态申报段，行内只留行为主证（双宿主摘要/全量闸回执）。
3. 【应修】转发壳清点漏一件：main.gd:516 `main._flush_row_queue()`（纯转发 `_row_pacer.flush()`，消费方 pacing_queue_test.gd:103＋main 内部两处注记）不在「七别名＋六转发方法」清单——_row_pacer 迁 ui.screens 后该 Middle Man 壳归宿未声明，与本批净消灭转发壳的方向不一致。改法：表 C/表 D 补一行（退役并改址消费方，或写明保留理由）。
4. 【可接受申报】V4（探针批量改址）与 V10（render_gate）的能力行锚取九探针中单点代表行（棋盘悬停反馈／站桩敌人呈现），语义为最小可得锚且未逐行披露该局限。建议 §8 域口径补一句「探针/渲染行能力锚取代表行」。
5. 核验通过项：A 十一行全齐；E 数字全对平——main.gd 49 个 var 实数清点吻合（grep ^var 恰 49）、49=28 迁（表 A 9+5+14）＋14 留（表 B）＋7 消灭（表 C）＋1 新增=15；四新件预算（2/0/0/1 公开方法、3/9/5/14 成员）与 §7.2 接口块逐名一致；LAYER_CONTRACT :39 起、六转发方法 :156/:161/:282/:285/:288/:292、别名七件行号全命中；smoke_boot 六处 get()＝4 改 2 留逐字吻合；pacing_queue_test :108/:132/:147/:149、source_guard V1d :69-77、theme_projection V6 :724-725、system_test V1c/V2 :94-109 全命中；D 能力行六名全在 game/tests/README.md 且受影响行核对成立；F §12 复用排除论证（ModalFlow/ModalStack/ui_assembler/run_scope 逐一否决＋ConfigDB 三容器先例）充分；唯一面实查成立（game/presentation/ 下四名未建、仅 ui_assembler 在册）；I 与裁决①③一致（零豁免、注销句、净消灭）；J 估时 3–4 日在冻结线内、步骤全部可核查。pipeline_gate 机检 13 卡全过。
## 卡三：战斗编排归约批（RoundCycle＋BattleFacts，38→15）
**裁决：有条件成立**（一项应修算术错；其余全过，是五卡中证据密度最高的一张）。
逐条发现：
1. 【应修】§4 红线句内部算术矛盾：「已迁 **22** 成员声明随迁即删（**21** 迁两件＋treasure_inventory 退役＋_hero_atk 退役）」——21+2=23≠22。实数＝迁两件 22（BattleFacts 15＋RoundCycle 7）＋退役 2＝删声明 24 项；轴丙后宿主 37→13 旧留＋2 新＝15，账平。architecture v1.25 两行写「收编 7＋14＝21」与本卡 BattleFacts 15 名单的 1 名口径差，已由 §6 反哺点通道（「批末成员数实测值与在册数字出入」）覆盖，但本句数字须改正以免实现期对账混乱。改法：改「22 迁两件＋2 退役」。
2. 【可接受申报】encounter 归 BattleFacts 最弱格标注诚实：设计文档 §6 白纸黑字「它也是本方案最弱的一格」＋两条备选砍路（nest_preview_count 解冻／_reward_economy 经授予件中转）均判更差；卡内 L3② 给出实现期证伪的停卡出口、§4 给出 15/15 贴顶与 SealLedger 扩容阀、设计 §8 险点 8 处理了 BoardInstaller bundle 键 encounter 传 _facts.encounter 的同引用零冲突——无隐瞒。
3. 核验通过项：A V0–V6 七行齐（V2 复位边界险点单独配断言、判据绑两快照同键值恒等）；E 类变量 38 实数清点吻合（:37-85＋:223-227 逐名）、基线两条类级键与「零函数级键」实查一致、保留 15 名单/两新件 8+15 成员账全平；file:line 抽验约 20 处全命中（treasure_inventory setter :48-52、外部注入 level_runner.gd:520、宿主四读 :111/:203/:450/:858、grant_segment :370-371、combat_segment :56、settle_segments_test :27 接线断言原文、static_scan S8 :317/S7 :359 九文件清单、run_all_gates PARITY 清量 battle_orchestrator :169、五段构造/三闸/摇号/复位块/完美谓词行号）；C 静态判据（键账收敛、S7/S8 增行）已按 §8.4 出口移出对照表在域口径段申报；D 十三处能力行全部在 README 在场且语义对题（V0 锚「回放确定性」为精确锚）；F 两新件职责语句＋集体身份在位（「持段件者不能是被持者」「事实账不是授予物」）、已否决切法留档；G 编队前置「迭代 42 合回之前禁开工」覆盖与在飞两卡在 battle_orchestrator/level_runner/static_scan.sh/treasure_effects_test 等的全部触面交叠；I 与裁决①③⑤一致；J 估时 2.5–3.75 对设计 §12 的 2–3 日给了上探理由，PARITY 批内实跑须用户点头不占估时。
## 卡四：呈现层状态件批（单格两域件＋站桩两件，30→10／19→10）
**裁决：有条件成立**（一项应修编队漏声明；潜伏红处置路径成立，成员拆分账五卡中最难算、已全对平）。
逐条发现：
1. 【应修】与卡二在 game/probe/ui_input_probe.gd 的**同文件交叠两卡均未声明**：组合根注册面批改该探针的 main.X 地址面（:34-43 等约 867 处散布之一），本批改四处 u.face.* 直读（:234-235/:243-244/:250/:374-379）——行位不相交但同文件，两卡又是同一条目（零豁免五键清偿批四卡）的同代候选，编排段靠编队声明排卡，此漏会制造二次 T0 重锚。改法：两卡编队注记互写一句（本卡补「与组合根注册面批在 ui_input_probe.gd 有触面交叠，先后施工各自 T0 重锚」，卡二同步）。
2. 【可接受申报】潜伏红 T0 定谳路径诚实：四处直读实查确在探针源码、迭代 41 已把 hl_visible/hl_color/dot_visible/mutation_mark 迁入内嵌类 _CellPaintState（board_cell_unit.gd:27 起），宿主 Node2D 无同名属性，「Invalid get index」推演成立；卡内预设 L3③「实跑全绿＝证伪设计前提＝停卡」的出口——未把推断当已证事实写死，定谳义务落在 T0 实跑。
3. 【可接受申报】V4 能力行锚「棋盘悬停反馈」含 case⑭ 变异角标（非悬停三语义）的最小拉伸；同一探针同一入口，可接受。
4. 核验通过项：A 四行齐（V1/V2 golden 主证、V3 演出链、V4 悬停金框/禁入红框/路径点迹/变异角标四处断言面）；E 成员账全对平——内嵌类 27 名实数清点吻合、基座 12（11＋_owner）＋叠加 13（12＋_owner）＋宿主上收 edge/cell/glow_group＋原位 glyph/glyph_color/plate/fog_state/_glow_layer＋base/face＝宿主 10；站桩真实 25＝vitals 11 名＋motion 10 名＋原 _owner＋3 计数器、宿主 10＝5 冻结 var＋st＋mo＋3 计数器；31/33 全文件声明数与 :26-122/:125-143、:23-59/:62-68 分区实查一致；九常量 :12-23 逐字命中；C 静态键账判据已按出口移出对照表（§9 域口径段申报，五卡中形态最规范）；D 六处能力行全在场且语义对题；F 四新件职责语句＋逐件排除论证（TilePalette/HeroSprite/BoardWorld/battle_stage_view/StatusSlotRow）在位，迷雾留宿主的「唯一不产生跨件回引」论证成立；G 与迭代 42 的 board_view 五段改型耦合声明完整（T0 前置＋「先于尾波补件批 board_hover 半边合回」反向义务）；gdstyle 截断缺陷红线（禁利用截断口径降数、禁把 _portrait_tex 当削减目标）与裁决一致；golden 三张禁换锚禁重制。
## 卡五：测速循环批（信号步进状态机＋双实现对拍）
**裁决：有条件成立**（一项应修能力行悬置；对拍方案与申报形态是五卡中最完整的）。
逐条发现：
1. 【应修】能力行锚语义错位且专属行悬置无主：三行对照表能力列锚「站桩敌人呈现与结算演出落点」，该行语义是站桩呈现与终局演出（README 旅程段六，系统列＝战斗表现），与本批测量面（批量模拟逐帧步进/运行态贯穿/报告注入）不同域；卡内自承「测量面专属能力行＝写卡段后续处理」——但写本卡的会话**就是**写卡段，2026-10-29「当场入表」规则下该行应随本卡增行（真实入口＝debug_overlay press_simulate_for_probe() 按钮 pressed 信号链→run(n)；代表用例＝standee_fx_sweep_test.gd:_init〔wd8〕＋tune_sim_batch_parity_test.gd:_init），增行后本列改锚。悬置写法让义务无承载主体、批末无人对账。
2. 【可接受申报】行为改动申报完备性成立：全件 68 行实读核对——:67-68 确为每局置假（潜伏红本体），静态矛盾推演（drv.seen=[true,false]、探针守卫环同段退出四串全红）与源码逐句吻合；改形其余面（常驻连接/is_connected 守卫/首步同步/n=0 同步收尾/_step_frame else 先断连）核为非行为改动；「_finished 若零读者可删」方向是删不是留，不违禁为机检保留成员条款。
3. 【可接受申报】脚本错误中断路径差异按 §8.4 出口声明缺口（协程死亡静默停摆 vs 确定性错误逐帧重试），T3 文档化义务在位，未伪装成可证判据；两形态测量批遇错都整批作废、同级不同形的论证成立。
4. 核验通过项：A 三行齐且真实入口真实（wd8 假驱动回调内读 is_running()、探针真实按钮信号链）；E 键账预算表逐规则落卡、成员 5＋6＝11（信号计入则 12）账与 T1 名单吻合、_run_one_level 5 参临界持平声明在位、改造后全文件零循环键消除逻辑成立（结构性免疫）；file:line 全量命中（run :36-52、循环 await :50、FakePanel/FakeDriver、wd8 三断言与〔wd8〕尾缀、ui_tune_probe SIM_GUARD_FRAMES=1800 :16 与 :63-83 四串断言、debug_overlay is_running :77/set_sim_running :81/_sync_sim_button :107、main_debug_flow :72-77 不 await 形态与 :84 互查守卫、hud_presenter 空守卫与 maxi(1,n)）；C 静态判据与声明缺口均不入对照表；F 零拆出单元的「不拆理由」在位（步进机是私有运行机制、拆出命不出职责语句＝凑计数袋，§8 引 code-conventions ②④）；遗留 await 形态副本全仓唯一性＋夹具不入四扫描面的声明经实查成立（基线 :15 唯一键、S8 九文件不含本件）；G 与其余四卡及迭代 42 无产品码触面交集声明成立（run_all.gd manifest 潜在交叠已交编排段）；I 与裁决③④⑤逐条一致（双实现对拍入批、收尾还原作为已申报行为改动、错误路径接受并文档化）；J 估时 1–1.5 日合理，T0 定谳证据列为审计第③项必查项。
## 总表
| 卡 | 裁决 | blocker | 应修 | 可接受申报 |
|---|---|---|---|---|
| 卡一 尾波补件批 | 有条件成立 | 0 | 4 | 1 |
| 卡二 组合根注册面批 | 有条件成立 | 1 | 2 | 1 |
| 卡三 战斗编排归约批 | 有条件成立 | 0 | 1 | 1 |
| 卡四 呈现层状态件批 | 有条件成立 | 0 | 1（与卡二共担） | 2 |
| 卡五 测速循环批 | 有条件成立 | 0 | 1 | 2 |
全库 blocker 与应修清单（编排段放行前置）：
- **blocker（卡二 §1）**：编队声明失实——「与迭代 42 无文件交叠（main.gd 不在其触面）」被在飞商店委托层拆除卡的文件清单（main.gd/main_adventure_flow/main_overlay_flow）直接证伪，须改写为如实交叠声明＋开工前置。
- **应修（卡二＋卡四，跨卡）**：ui_input_probe.gd 同文件触面交叠两卡编队注记均未声明，互写一句补齐。
- **应修（卡一 §7）**：board_hover 半边的状态件批先行约束从「推荐」升为硬前置，与卡四侧已裁义务对齐；breakpoint_store 半边明示可独立先行。
- **应修（卡一 §8）**：V1 判据绑定面「格件 st 边框/点迹字段」按施工时点改 u.face.* 口径。
- **应修（卡一 §3）**：resume_adventure 行号 :94 改 :141。
- **应修（卡一 §13）**：预算节引用束成员列名计数（board_hover 约 7、breakpoint_store 约 14）。
- **应修（卡二 §8）**：对照表第 2/11 行静态判据移入域口径申报段，与卡三/四/五形态统一。
- **应修（卡二 表 C/D）**：main._flush_row_queue（:516）转发壳归宿补声明（退役改址或保留理由）。
- **应修（卡三 §4）**：「已迁 22 成员（21 迁两件＋2 退役）」算术改正为「22 迁两件＋2 退役」。
- **应修（卡五 §6/§12）**：测量面专属能力行随本卡当场增入 game/tests/README.md 并改锚三行能力列，废「写卡段后续处理」悬置表述。
总体判断：五卡可以进编排段，但须先落上表一项 blocker 与九项应修——全部是编辑级补丁与声明修正，无一张需要推翻拆件方案或重做设计。证据面结论：五卡 file:line 抽验约 90 处命中（唯一硬伤＝卡一处行号），键账与成员迁移账全部数平（含卡四最难的 27/25 内嵌类双 _owner 拆分），两处静态矛盾推演（卡四潜伏红、卡五每局置假）经源码逐句复核成立，与五项用户裁决无一冲突，机检 pipeline_gate 全绿。最大的真实风险不在卡内而在编队声明层：卡二对迭代 42 的无交叠声明失实、卡二与卡四未声明探针同文件交叠——这两处修正后，编排段才有可信的排卡依据。
reports/设计-战斗编排类变量归约-2026-10-29.md
-183
View File
@@ -1,183 +0,0 @@
# 设计——战斗编排类变量归约（S13 真修复方案）
> 设计讨论段过程稿 v1.0——待主会话汇总裁决（2026-10-29）。输入＝用户裁定「不允许任何豁免：battle_orchestrator.gd 的 max-class-variables 必须真实修复到阈值 15 内，architecture S13 豁免登记第三条注销」。读者＝主会话（裁决）与后续写卡段（转需求卡片）。
## 结论
宿主 38 个类变量经「BoardInstaller 已定稿退役 1 ＋ 两枚新件收编 19 ＋ 库存注入改址 1 ＋ 攻基线快照转派生读 1」收敛到 **15（＝阈值，合规）**。两枚新件：RoundCycle（轮循环驱动件——五段段件持有、段序执行、结算重入门闸、开轮摇号、踩雷计数账）与 BattleFacts（战斗事实件——受理事实、轮 facts 缓冲、封印判定账、装板溯源、条件计数、同调装配快照）。已实装两拆件 BattleFxHost／RewardGrant 与五段段类构造、呈现层、A2 订阅面、封闭流全部零触碰或仅改指。
---
## 1. 目标形态——battle_orchestrator 改后保留什么
宿主保留的是「编排」本身，全部在 architecture「战斗编排域拆件定稿」第 1 款的在册职责面内（attune 一款按本文件第 5 节重裁决为「状态归事实件、行为留宿主」）：
1. **状态机与生命周期**：`begin_battle` 受理四段序列（受理/装板/运行态/预告经济）、`_exit_distribution` 轮间转移、`_battle_over` 终局序列、`battle_result` 与 `_fatal` 唯一写点、`round_index` 轮时钟。
2. **A2 三事件订阅与事件处理**：三条 connect 留 `_init`（订阅面逐字）；`_on_cell_revealed`（旁路守卫→积点自动兑付触发→身份快照捕获→缓冲追加）、`_on_seal_judged`、`_on_round_end` 三个处理器留宿主——它们是多件协作的编排判断点，不是纯缓冲。
3. **行发射基建**：`_emit_row`／`_assert_row_source`／`_fatal`＋SOURCE_EXEMPT 两常量词表——协议面单点，零迁移。
4. **呈现投影**：`presentation_snapshot`／`diagnostic_snapshot`／`_emit_settlement_snapshot` 三出口——签名与载荷逐字不变，内部读数改指两件投影。
5. **刷新面**：`can_refresh`／`player_request_refresh`。
6. **attune 编排读数与触发面**（重裁决后）：`attune_has`／`attune_param_sum`／`attune_convert_state`／`_attune_charge_safe_row`／`_reseed_attune_charges`／`_hook_attune_consume`／`_attune_safe_seen_read`／积点自动兑付体——读数出口与外部面零改址（见第 5 节）。
7. **账本读面**：`_journal`／`_attune_loadout`／`_battle_hooks` 三派生读与回调束。
8. **装板薄壳**：`_install_and_reset`（轴丙定稿形态——五处计数清零、板序推进、board_changed 发射、叠加层退役，时序逐字）。
9. **B2/B3/B4 协作者持有**：S7「唯一调用方＝B1 域文件集」的承载面。
搬出去的只有两类东西：**轮结算周期的推进机构**（谁持有段件、按什么顺序跑、开轮怎么摇号、重入怎么挡——归 RoundCycle）与**发生过什么与本战是什么的记录**（事实账——归 BattleFacts）。两件的职责语句与单一变化原因见第 3、4 节。
## 2. 逐成员去向对账表（38 项）
| # | 成员 | 去向 | 依据（一句话） |
|---|---|---|---|
| 1 | db | 留宿主 | B1 跨系统调用权的表读取面，宿主级协作者 |
| 2 | rng | 留宿主 | encounter/gp_drop 两封闭流在宿主函数体内，behavior_roll 随摇号件经 oc 取用 |
| 3 | _board_generator | **随 BoardInstaller 退役** | 轴丙已定稿（v1.24）：实例随件自建自接线 |
| 4 | minesweeper | 留宿主 | A2 订阅面＋HUD 公有消费面（API Boundaries 在册）双锁定 |
| 5 | action_economy | 留宿主 | A3 回发面＋HUD 公有消费面双锁定 |
| 6 | _enemy_system | 留宿主 | B2 生命周期（spawn/despawn）与三快照读源 |
| 7 | _status_effects | 留宿主 | B3 开域/闭域与三快照读源 |
| 8 | _reward_economy | 留宿主 | B4 恰一次 roll/retire 编排＋set_treasure_unlocked/query_reward_identity 两外部代理 |
| 9 | treasure_inventory | **退役改址** | 唯一外部注入点 level_runner:520 改经 `reward_grant()` 出口直注（RewardGrant 在册成员）；宿主与授予段读面改指 grant |
| 10 | _damage | 留宿主 | 单据管线接线（fx_calls/inject）与 AC 基线注入时序锁定在受理段内 |
| 11 | _fx_host | 留宿主 | 组件出口 `fx_host()`——定稿在册取件面 |
| 12 | _reward_grant | 留宿主 | 组件出口 `reward_grant()`＋库存持有者＋escrow 读源 |
| 13 | encounter | **BattleFacts** | 本战受理事实（打什么、带什么进来）——与过程事实同一记录口径 |
| 14 | round_index | 留宿主 | 轮时钟；system_test 等四套件约 15 处 `settlement.round_index` 公有直读面，零改址 |
| 15 | battle_result | 留宿主 | 状态机终局态；_fatal/_battle_over 唯一写点归属不变 |
| 16 | _facts_reveals | **BattleFacts.reveals** | 轮 facts 缓冲 |
| 17 | _facts_seals | **BattleFacts.seals** | 封印判定批缓冲 |
| 18 | _facts_path | **BattleFacts.path** | 轮末路径事实 |
| 19 | _settling | **RoundCycle._settling** | 结算重入门闸——与段序执行同一单元 |
| 20 | _grant_seg | **RoundCycle** | 五段段件持有归驱动件（定稿「段序编排+接线」的代码承载） |
| 21 | _aura_seg | **RoundCycle** | 同上 |
| 22 | _combat_seg | **RoundCycle** | 同上 |
| 23 | _decay_seg | **RoundCycle** | 同上 |
| 24 | _verdict_seg | **RoundCycle** | 同上 |
| 25 | _refresh_used_this_round | **BattleFacts.refresh_used** | 本轮刷新计数＝过程事实（复位点＝出口分发，语句随迁） |
| 26 | _board_seq | **BattleFacts.board_seq** | 装板溯源事实 |
| 27 | _board_from_midround_refresh | **BattleFacts.board_from_midround** | 装板 provenance（清图奖励守卫读源） |
| 28 | _seal_consumed | **BattleFacts.seal_consumed** | 封印兑付资格账（install 重置） |
| 29 | attunement | **BattleFacts.attunement** | 本战装配集快照＝受理事实（enc.attunement 携带） |
| 30 | _mines_hits | **RoundCycle.mines_hits** | 摇号条件账——转存语句本就在 `_roll_round_actions` 轮末，随摇号件走 |
| 31 | _attune_safe_seen | **BattleFacts.attune_safe_seen** | 积点计数＝过程事实 |
| 32 | nest_preview_count | 留宿主 | 冻结外部直读面（main.gd×2＋treasure_effects_test×1）零变化 |
| 33 | _feat_first_dig_used | **BattleFacts.feat_first_dig_used** | 条件事实计数（魔矢每战首次） |
| 34 | _seal_miss_seen | **BattleFacts.seal_miss_seen** | 标错去重账 |
| 35 | _perfect_hit_true | **BattleFacts.perfect_hit_true** | 完美封印三账（契约 2 写口归件，见第 4 节） |
| 36 | _perfect_hit_false | **BattleFacts.perfect_hit_false** | 同上 |
| 37 | _perfect_forgiven | **BattleFacts.perfect_forgiven** | 同上 |
| 38 | _hero_atk | **退役→派生读函数** | `_hero_atk()` 派生读（`encounter.get("hero_atk", 表值)`）——`_journal()`「读面即引用、无第二账」同款先例；E4 收口语义不变（encounter 受理后只读，派生值恒等） |
**宿主改后 15 项**：db、rng、minesweeper、action_economy、_enemy_system、_status_effects、_reward_economy、_damage、_fx_host、_reward_grant、round_index、battle_result、nest_preview_count、_rounds、_facts。
## 3. 新件一：RoundCycle（轮循环驱动件）
- **文件落点**：`game/core/settlement/round_cycle.gd`（与五段段件同目录——它是段件的序主人）。
- **extends**：RefCounted（fx_host/reward_grant/段类同款；随编排器每战新建同灭）。
- **职责语句**：每轮结算周期的唯一驱动——结算重入门闸（settling）、五段段序执行（段序骨架冻结于 SettlementTable.segment_order）、开轮摇号（共识点 B：技能选择前置到轮次开始，摇定即本拍结算的选技）、踩雷计数账（转存时点＝摇号轮末）。
- **单一变化原因**：轮结算周期的推进结构（段序、重入闸、摇号时序）。
- **类变量（8 ≤ 15）**：`oc`（宿主，段类同款直调形态）、`_grant_seg`、`_aura_seg`、`_combat_seg`、`_decay_seg`、`_verdict_seg`、`_settling`、`mines_hits`（{"total","last","round"} 三读数合一账）。
- **公开方法（3 ≤ 20）**：`settle_if_due()`（＝原 `_maybe_settle` 三闸＋`_settle` 段序体合体）、`roll_round_actions()`（原函数逐字迁入）、`is_settling()`（diagnostic_snapshot 读投影）。
- **行数估算**：约 120 行（头注＋成员＋四函数）。
- **耦合边界**：
- `_init(host, fx_host, reward_grant)`——3 参不触发 max-parameters，无需引用束；五段构造五行从宿主 `_init` 逐字搬入。
- 段类对宿主的直调形态不变（定稿在册：「段类经宿主引用直调，现状形态」）；驱动件经 `oc` 取 facts/协作件/行发射/出口分发，与段类同款。
- **VerdictSegment 零改动**：`_exit_distribution` 留宿主（轮间转移＝宿主生命周期域：换图编排、notify、轮始发射），判定段仍直调 `oc._exit_distribution()`——不产生段类对驱动件的新引用，不新增 RefCounted 引用环。
- 随机只经 `oc.rng` 的 behavior_roll 封闭流（流名、开流时点、取号序逐字）；零 await。
- **宿主侧变化**：`_on_round_end` 末行改调 `_rounds.settle_if_due()`；`begin_battle` 与 `_exit_distribution` 的 `_roll_round_actions()` 改调 `_rounds.roll_round_actions()`；`_maybe_settle`/`_settle`/`_roll_round_actions` 三函数从宿主删除。
## 4. 新件二：BattleFacts（战斗事实件）
- **文件落点**：`game/core/battle_facts.gd`。
- **extends**：RefCounted。
- **职责语句**：战斗事实的唯一记录面——本战受理事实（encounter：打什么、带什么进来）、同调装配事实（attunement）、轮 facts 缓冲（reveals/seals/path）、封印判定账（去重两集＋完美三账）、装板溯源（seq/provenance）、条件事实计数（refresh_used、feat_first_dig_used）；自带轮复位与完美账写口。
- **单一变化原因**：战斗事实的记录与查询口径——内容批新增触发条件事实/判定账只落此一处。实证：`_feat_first_dig_used`（魔能共鸣）、`_seal_miss_seen`（危险直觉）、`_mines_hits`（触发条件面）、enc 的 feats/tree_rules/voucher 携带键，全部由内容批按同一节奏累加。
- **类变量（15 ≤ 15，贴顶）**：`encounter`、`reveals`、`seals`、`path`、`refresh_used`、`board_seq`、`board_from_midround`、`seal_consumed`、`seal_miss_seen`、`perfect_hit_true`、`perfect_hit_false`、`perfect_forgiven`、`feat_first_dig_used`、`attunement`、`attune_safe_seen`。
- **公开方法（5 ≤ 20）**：`reset_round()`（原 `_reset_round_facts` 逐字——只清 reveals/seals/path 三项，**不碰 refresh_used**：_battle_over 后快照读到的 refresh_used 必须保持末轮值）、`mark_perfect_hit()`／`mark_perfect_miss()`／`mark_perfect_forgiven()`（契约 2 写口：`_perfect_hit_false` 纯净禁回退改写的执行点从段类纪律升级为账本单点）。其余一律公有成员直读写（段类/快照/宿主经 `oc._facts.X` 改指——fx_host._fx_bonus_delta 跨件直读写同款现状形态）。
- **行数估算**：约 80 行。
- **耦合边界**：**零注入引用、零信号、零协作对象调用**——纯数据＋谓词＋写口；缓冲写入点在宿主 A2 处理器（订阅面锁宿主），身份快照捕获（query_full_snapshot）留宿主 `_on_cell_revealed`（fact 件不持 B4 引用，防它变成第二编排面）。
- **成员冻结义务**：15/15 贴顶——实现期禁增员，增员即停卡。预留扩容阀：下一张要加事实成员的卡，先把封印判定账五成员二次拆出（SealLedger，−5）再落新账，禁硬挤。
## 5. attune 族重新裁决（architecture「原位保留」句的废止建议）
**建议：部分改裁——状态两成员归 BattleFacts，行为函数留宿主。** 理由四条：
1. **原位裁的前提已消失**：该句是迭代 39/40 两批的防冲突临时裁，原文自认「本波残留债归尾波」；两批均已合回，本波即尾波，且用户已裁「不允许任何豁免」打开重裁通道。
2. **状态是事实，行为是编排**：`attunement`＝本战装配了什么（enc.attunement 受理携带的快照，受理后只读）、`attune_safe_seen`＝本战安全开格积点——两者都是战斗事实，归账本件名正言顺。而参数合计（装配集行扫描）、积点自动兑付（何时 grant_ap＝编排决策）、充能重置触发、呈现进度读数——这些是 B1 编排面的读数与触发，与 `_fx_host_fact` 同位的宿主读数形态，留在宿主不违职责语句。
3. **外部面零改址**：`attune_has`（断点续玩测试×2＋表结构守卫×2）、`attune_param_sum`（main.gd 授予段两处＋treasure_effects_test）、`attune_convert_state`（treasure_interact_controller 取值回调）全部留宿主公有面——main.gd 与 treasure_interact_controller 本批零改动。若整体拆成 BattleAttune 新件，这三面约 10 处消费点全要改址（组件出口或转发壳），收益只是把 8 个读数函数换个文件——判据③（阈值动机）嫌疑大于内聚收益。
4. **不并进 AttuneLoadout**：那是营地/冒险域的充能与装备集物化单源（迭代 39 已闭合契约）；把战斗域读数插进去会重开已闭合边界。BattleFacts 持有的只是快照与计数，充能物化仍全归 AttuneLoadout（`_reseed_attune_charges`/`_hook_attune_consume` 经调用点传 loadout/treasure 委派，宿主侧单点不变）。
## 6. 已否决的方向（为什么不是别的切法）
1. **协作者引用束归袋**（任务提示①的直译形态）：db/rng/units/statuses/reward_economy 等 11 个协作者句柄若收进一个「引用束」对象，宿主 150＋ 处 `db.`/`oc._enemy_system.` 全部换名——零内聚收益的纯改名，命不出领域名字＝凑计数袋（拆分判据②红）。引用束先例只用于新件 `_init` 防参（本批两新件参数均 ≤3，未触发）。
2. **attune 整体拆件（BattleAttune）**：宿主 14 基数＋3 句柄＝16 不可达；且如第 5 节理由 3，外部三面 10 处改址换不来职责改善。
3. **encounter 留宿主**：宿主 16 超阈。备选砍口只剩两处——nest_preview_count 解冻迁 facts（违背任务给定冻结面）或 _reward_economy 经 RewardGrant 中转（B4 mapping 生命周期与代理面挂到授予件名下＝所有权失真）。encounter 归事实件是唯一不破冻结面、不失真的砍口；它也是本方案最弱的一格，见待裁点 1。
4. **四件以上碎片化**：每多一件付一个宿主句柄；封印判定账、装板溯源单独成件都撑不起独立变化原因，且把宿主推向 16+。
5. **_exit_distribution 迁入驱动件**：判定段须改持驱动件引用（RefCounted 环＋段类构造变化），换图编排又是宿主生命周期语义——收益不抵风险，否。
## 7. 随迁键收敛义务
**基线实证**：`tools/gdstyle_baseline.txt` 中 battle_orchestrator.gd 现仅两条类级键（max-class-variables=38、max-file-length=1035），**零函数级键**——59 个函数全部在默认阈值内（长度≤50/分支≤8/局部≤10/返回≤6/参数≤5）。函数级指标是函数体内在属性，逐字迁移（仅引用改指）不产生新键。据此：
- **随迁键清单：预计零条**。义务改为「迁移函数逐字纪律」：`roll_round_actions`（45 行/分支≈8 贴线）、`settle_if_due`、`reset_round`、三个 mark 方法——迁移与改指**禁顺手增分支/局部**；确需增条件即停手核对 gdstyle，超线在卡内拆助手函数收敛（先例＝迭代 40 卡①的 12 随迁键收敛）。
- 新增小函数全部远在阈值内（最长 `roll_round_actions` 45 行；新件 `_init` 参≤3）。
- 两新件与改址后的宿主、段类落地后跑 `python tools/gdstyle_gate.py` 预检一次再进批末闸。
## 8. 行为零变化风险点与对策
1. **RNG 取号序**：宿主三封闭流——encounter（`_begin_battle_dice`，留宿主）、gp_drop（`_roll_gp_drop`，留宿主）、behavior_roll（随 `roll_round_actions` 迁 RoundCycle——流名与开流时点逐字，只经 `oc.rng`）。fx_reveal（fx_host 内零触碰）、board_gen/variant_place（BoardInstaller 已定稿随件）。对策＝同种子完整局对拍（见第 9 节 PARITY）。
2. **信号契约**：五信号（step_row/battle_finished/round_started/board_changed/settlement_snapshot）全留宿主；发射语句零迁移——`round_started.emit` 在 begin_battle/`_exit_distribution` 内原位，仅 round_index 读源不变；A2 三 connect 逐字。发射时序零变化。
3. **段类接线**：五段构造参数与持有形态不变（grant/combat 三引用、aura/decay/verdict 单引用）；verdict 段零改动（`_exit_distribution` 留宿主）。段内约 25 处 `oc._X` 改指 `oc._facts.X`／`reward_grant.treasure_inventory`——调用点改指、禁转发壳（定稿同款纪律）。
4. **_fatal 与 battle_result 唯一写点**：留宿主；BoardInstaller（已定稿 fatal Callable）、RoundCycle/段类（经 oc 直调）零改形。
5. **结算时序**：`settle_if_due` 三闸顺序（settling→battle_result→phase）与「终局不回置 _settling、_battle_over 接管」早退语义逐字；判定段内 `_exit_distribution`→回置 `_settling` 的先后不变（出口留宿主保证）；`reset_round` 不碰 refresh_used（_battle_over 后快照的 refresh_used 必须保持末轮值——这是本轮盘点抓出的一处险点）。
6. **重入语义**：`_on_cell_revealed` 不设 settling 守卫（现状——flush_pending_reveals 的 fx_reveal 事件依赖 reveal_busy 旁路闸而非 settling），处理器体零改形；install 初始展开事件「先缓冲后清除」路径（begin/exit 两处 reset_round）保持。
7. **快照逐字**：三快照字段名、嵌套结构、值口径逐字——读数改指投影后值恒等（round_index/attune_safe_seen/perfect 三账/hero_atk 派生读均受理后不变量）。
8. **装板薄壳时序**：轴丙定稿五处清零→板序推进→board_changed 发射→叠加层退役的顺序逐字（成员改指 facts 不改序）；BoardInstaller 闭合设计的 bundle 键「encounter」传 `_facts.encounter`——同一字典引用，零冲突。
## 9. 验收载体与判据
改动—验收对照表（卡内落六列）建议主行：
| 需求点 | 真实入口 | 载体 | 判据绑定面 |
|---|---|---|---|
| 行为零变化（本批总判据） | 真实局 begin_battle→挖掘→结算→终局 | **PARITY 同种子完整局对拍**（parity_anchor/parity_compare） | step_row/settlement_snapshot 逐位一致；**实跑须用户批准、禁重锚**（battle_orchestrator.gd 触 PARITY_TOUCH_FACES） |
| 段序与重入门 | stop→WAITING→settle_if_due | round_flow_skill_pool_test、settle_segments_test（真实一轮走段序，零改址应绿） | 五段裁定行序、settling 闸、终局早退 |
| 开轮摇号迁移 | begin_battle/出口分发→roll_round_actions | round_flow_skill_pool_test（技能池/保底/冷却）＋trigger_cond_test（mines_hits 账——3 处读改指 _rounds） | 同种子摇定结果逐位、转存读数 |
| 封印判定账迁移 | 封印动作→结算 | seal_polarity_test（4 处 perfect 直写改指）、feat_vouchers_test（8 处＋_grant_seg 改指）、meta_progression_forge_test（契约 12 守侧） | 完美三账读数、去重闸、契约 2 计数纯净 |
| 装板 shell/溯源 | begin/refresh/exit 装板 | variant_placement_test（零改址应绿）＋seal_polarity_test provenance 守卫 | 刷新图不发清图奖励、board_seq |
| attune 面零改址 | 装配起战→读数/兑付 | treasure_effects_test、breakpoint_resume_test、table_structure_guard_test（**应零改址全绿**——本批最硬的「外部面零变化」证） | attune_has/param_sum/convert_state/积点兑付 |
| 受理事实迁移 | begin_battle(enc) | adventure_feats_test、meta_progression_forge_test（encounter 4 处改指） | enc 携带键贯通 |
| 快照逐字 | presentation/diagnostic 出口 | system_test＋对拍 | 载荷 schema 与值逐字 |
| 库存注入改址 | level_runner 建战注入 | treasure_effects_test 秘宝使用链 | use_treasure 受理面 |
配套义务：①三件保险恒跑（冒烟/系统测试/静态扫描）＋上表关联套件（02 关联档）；②静态扫描随批增行——RoundCycle 进 S7 B1 域文件集与 S8 await 文件集（经 oc 调 B2/B3/B4 符号落在该文件），BattleFacts 零协作调用不入两清单；③新文件全类型标注（S9）、头注按 §1.4.1；④本批零数值改动，MC 零跑。
## 10. gdstyle 键账预期
| 文件 | 类变量 | 公开方法 | 长度 | 预期键 |
|---|---|---|---|---|
| battle_orchestrator.gd | **15**（38→15） | 14 | ~830 | **两条基线键全消失**（类变量/文件长双双回落阈值内），零新键 |
| settlement/round_cycle.gd | 8 | 3 | ~120 | 零键 |
| battle_facts.gd | 15（贴顶） | 5 | ~80 | 零键（15＝阈值内合法，fx_host「14≤15」同口径） |
| settlement/grant_segment.gd | 3（不变） | — | +~2 行改指 | 零键 |
| 其余段类／fx_host／reward_grant | 不变 | 不变 | 不变 | 零键、零 diff |
基线处理：`--refresh` 人工重生成；全基线 16 条消失 2 条（−12.5%＞10% 骤降守卫）→ 须 `--force` 显式确认，属正常还债缩基线。architecture S13 豁免登记第三条随批注销（反哺点，实现批禁写 design/）。
## 11. 改址盘点（触面清单）
- **产品码**：battle_orchestrator.gd（主改——成员改指＋三函数迁出＋hero_atk 派生化＋头注指址改写）；settlement/round_cycle.gd、battle_facts.gd（新建）；grant_segment.gd（~25 处改指）；combat_segment.gd（2 处）；level_runner.gd（1 行——库存注入改经 `reward_grant()` 出口）；aura/decay/verdict、battle_fx_host、reward_grant、damage_controller、main.gd、treasure_interact_controller、board_installer（**零改动**）。
- **测试**：feat_vouchers_test（~13）、meta_progression_forge_test（~8）、seal_polarity_test（~8）、trigger_cond_test（3）、round_flow_skill_pool_test（1）、adventure_feats_test（1）、treasure_effects_test（1——`ob14.attunement` 改指）；settle_segments_test、roll_multiplier_test、system_test、breakpoint_resume_test、table_structure_guard_test（零改址——attune 面与 round_index 面不动的直接受益者）。
- **probes/sim**：零触碰（盘点无命中）。
- **闸件数据**：gdstyle_baseline.txt（--refresh --force）。
## 12. 估时
**2–3 个工作日**：实现（两新件＋宿主改址＋段类改址＋测试改址）1.5–2 日；验收（关联档回归＋PARITY 批跑＋对照表与审计配合）0.5–1 日。PARITY 实跑须用户在场批准（不占卡估时）；基线 refresh 属批内闸步骤。
## 13. 待裁点清单
1. **encounter 归战斗事实件**（本方案最弱一格）：受理参数与过程记录同件，变化理由按「战斗事实面扩展」归一（第 4 节实证），但确与事实缓冲不同复位节奏（encounter 随战、facts 随轮）。若否决：宿主 16，只剩两条砍路——nest_preview_count 冻结面解锁（外部读面 3 处改址）或 _reward_economy 经授予件中转（所有权失真），两者都更差，届时按判据④停卡呈报。
2. **treasure_inventory 注入面改址**：唯一外部产品码触面（level_runner 一行改经组件出口直注），拆件定稿「外部赋值路径零改址」句随本批失效，需追认。
3. **attune 重裁决幅度**：推荐「状态归 facts、行为留宿主」（第 5 节）；备选「整体拆 BattleAttune」因宿主 16 不可达已被排除——即本条实际是确认推荐案或否决整个方向。
4. **完美账写口升级**：grant_segment 三处直写改经 facts 三方法（契约 2 单点执行）——推荐采纳；若求最小 diff 可退直写（现状纪律同款），卡内裁量。
5. **PARITY 对拍批准**：battle_orchestrator.gd 触 PARITY_TOUCH_FACES，实跑对拍须用户点头、不重锚。
reports/设计-测速循环去await-2026-10-29.md
-210
View File
@@ -1,210 +0,0 @@
# 设计——测速循环去 await（S13 `tune_sim_controller` await-in-loop 键真实消除）
状态行：设计讨论段过程稿 v1.0——待主会话汇总裁决（2026-10-29）。
## 1. 背景与目标
用户 2026-10-29 裁定「不允许任何豁免」：S13 静态质量闸（gdstyle）的裸键 `game/presentation/tune_sim_controller.gd|quality/await-in-loop|'await' used inside a loop` 必须真实消除；architecture「测试与质量域」S13 测量面豁免登记（2026-10-27，理由=「循环内 await 是调参测量的 wall-clock 步进承载语义——重构即测量口径漂移」）随之注销（注销落文走反哺点通道，实现批禁直改 architecture）。
本设计回答一件事：**把「循环内 await 逐帧让出」换成信号驱动形态后，测量语义是否逐点等价**——每步恰占一帧、每步执行相位不变、终止与读数不变、输出逐字不变。结论先行：**可行，推荐 process_frame 信号连接＋步进状态机形态**；等价性四判据三条可严格证明并可用双实现对拍执行化验证，一条（脚本错误中断路径）无法严格证明、列为已声明缺口。
## 2. 现状全解
### 2.1 测速循环逐句流程
现码 `run(n)`（`game/presentation/tune_sim_controller.gd:36-52`）：
| 步 | 语句 | 做什么 |
|---|---|---|
| 1 | `_running = true` | 控制器运行态（组合根 `_start_debug_levels` 互查守卫的判据） |
| 2 | `PlaytestLogger.new()`＋`start_session(SEED_BASE)` | 开共享 JSONL 会话（一文件多局，`log_run` 行带种子切分局次） |
| 3 | `panel.set_sim_running(true)` | 浮窗运行态（`DebugOverlay.st._sim_running`——模拟钮置灰＋探针守卫环判据） |
| 4 | `set_sim_progress("模拟中：0/n …")` | 进度串 |
| 5 | 建 `stats` 六键束、取 autoplay 驱动 | 测量桶与策略驱动 |
| 6 | 循环体：`_run_one_level(...)` | 单局全量模拟（`level_autoplay.run_level` 静态同步函数——自建 RngService、种子=SEED_BASE+i，逐局确定可回放）→ 四桶记账 |
| 7 | `set_sim_progress("i+1/n")` | 进度串 |
| 8 | `await panel.get_tree().process_frame` | 每局恰让出一帧（命中键的语句） |
| 9 | 循环尽：`close_session()`＋`set_sim_report(...)` | JSONL 收口＋报告注入（文案归 `HudPresenter.tune_sim_report`，零触碰） |
读数本质：`stats` 六键与报告是 **(种子, atk_pct, hp_pct) 的纯函数**——帧时点不进测量值（`run_level` 不读 wall-clock）。豁免登记所保护的「测量语义」是运行姿态：每局之间恰隔一帧 process_frame 发射（进度可见、窗口不僵死），以及 run 全程的运行态语义。本设计保的就是这个姿态。
### 2.2 读数消费链
- 报告文案：`tune_sim_report(stats)` → 浮窗 RichTextLabel（`set_sim_report`）；探针 ⑤ 断言「关卡完成率／关卡完成剩余 HP 均／败北节点／N=10」四串。
- JSONL：`user://logs/playtest_*.jsonl`，由未触碰的 `level_autoplay` 逐行写；`close_session` 时点随收尾帧。
- 运行态：`panel.set_sim_running` → 浮窗模拟钮置灰；`_running` → 组合根两层调试入口守卫。
### 2.3 断言面盘点与一处静态矛盾（潜伏红——本设计的关键发现）
两个在库断言面钉死了 run 生命周期的语义：
1. **单元套件 `standee_fx_sweep_test.gd`〔wd8〕**（`game/tests/unit/presentation/standee_fx_sweep_test.gd:126-134`）：假驱动在**每一局** `run_level` 回调内读 `ctrl.is_running()`，断言 `drv.seen == [true, true]`（两局读数都真）；收尾断言 `is_running()` 假＋`panel.running` 假＋报告非空；且用 `await ctrl.run(2)` 驱动——**run 必须保持可等待（协程），await 它须挂起到整批完成**。
2. **探针 `ui_tune_probe.gd` ⑤**（`game/probe/ui_tune_probe.gd:67-83`）：按下模拟钮后以 `while debug_overlay.is_running()` 守卫环逐帧等——**语义=浮窗运行态贯穿整批**，环退出后断言输出含报告四串。
静态推演现码：`_run_one_level` 尾部两行（`panel.set_sim_running(false)`／`_running = false`，:67-68）**每局执行一次**——首局完成即把两个运行态置假。后果：
- wd8 首断言实测必得 `[true, false]` → 红；
- 探针 ⑤ 守卫环在按下返回后立即退出（首局在按下同一同步段内已跑完）→ 输出停在进度串 → 四条输出断言全红。
推断：这两行原本在循环**之后**（run 收尾单次执行），是「循环体提函数」（run() 局部变量 11→10 清偿批，2026-10-26 审计在案该键）搬运时被卷入提取体——wd8 写于 d8 批且当时必绿，可反证。两断言面均不在近期批次的关联档选测覆盖内（套件名与文件名无字面关联、probe_gate --full 非恒跑三保险），潜伏红未暴露。**T0 义务：实跑 standee_fx_sweep 单套件＋probe_gate --full 复核现状**（本设计零测试执行，此判断待实跑确认）。
推论：本批若逐字保留现行为，wd8 与探针 ⑤ 必红、批不可绿。**本设计按「run 收尾单次置 false」的还原语义设计**（两断言面共同钉住的语义），该还原作为已申报行为改动进卡（待裁点 1）。
## 3. 方案形态评估
判定轴：帧相位（步进体在帧循环中的执行时点是否与 await 恢复点相同）、步进节律（相邻两步之间是否恰隔一次 process_frame 发射）、run 可等待性（wd8 契约）、键风险（S13 新键）。
Godot 4 帧循环 process 段的迭代序（engine-reference 口径）：**① `emit process_frame`**（所有连接的 Callable 同步依次调用；`await process_frame` 的恢复点=此刻挂在信号上的临时连接被调用）→ **② 节点 `_process`**（Timer 节点在此段）→ **③ 帧末**（SceneTreeTimer 超时、延迟删除等）。官方文档：process_frame「Emitted immediately before Node._process is called on every node」。await 恢复点与显式 connect 回调**同处①、同一相位**——这是全部等价性论证的支点。
| 形态 | 帧相位 | 步进节律 | run 可等待 | 键风险 | 裁决 |
|---|---|---|---|---|---|
| **process_frame 信号连接＋步进状态机** | 与 await 恢复点同相位（同一 emit 内） | 恒等（常驻连接，每发射恰走一步） | 保留（函数级单次 await 完成信号，见 §4） | 零新键 | **采纳** |
| SceneTreeTimer 链 | timeout 在③帧末——相位不同 | `create_timer(0)` 同帧即燃→节律塌缩；加时长→漂移 | 须循环内 await→键不消 | await-in-loop 残留＋每步分配 | 否 |
| Timer 节点 | timeout 在②节点 process 段——相位不同 | wait_time 按秒计，一帧节律不精确 | 须 await timeout 链→键不消 | 键残留＋须建 Node 入树（RefCounted 控制器破形、生命周期管理新增） | 否 |
| 递归协程代循环 | 同相位（恢复点内即调下一步） | 恒等 | 天然（await 协程链） | 零键 | 备选否决——n 个并发函数状态链、错误中断语义更浑、可读性差 |
| 线程 / WorkerThreadPool | 脱离主循环 | — | — | 测量确定性破坏＋面板 setter 跨线程 | 否（一句话排除） |
godot-master 惯用法对齐：异步操作移出循环、改由信号触发的独立方法承载（其 NEVER-list 第 7 条同款）；动态连接用毕即断（第 27 条）；逻辑件保持 RefCounted 不引入 Node（When-NOT-to-use-Node）；连接前 `is_connected` 守卫（迭代 39「恰好连接一次」先例）。
## 4. 推荐案：process_frame 信号步进状态机
### 4.1 代码结构草图（伪代码级）
```gdscript
signal _batch_finished ## 批量模拟整批收尾完成（无参数；发射时点=报告注入与运行态复位之后；
## 消费方=run() 自身收尾放行——外部 `await 控制器.run(n)` 经此放行）
# run 期活成员（批末失效，下次 run 重写——非无效成员）
var _sim_n := 0
var _sim_i := 0
var _sim_stats := {}
var _sim_autoplay = null
var _sim_logger = null
var _finished := false
func run(n: int) -> void:
_running = true
# …logger 建会话／set_sim_running(true)／进度 0/n／stats 六键束／_autoplay()——逐字保持现码…
_sim_n = n; _sim_i = 0; _sim_stats = …; _sim_autoplay = …; _sim_logger = logger
_finished = false
if n > 0:
var tree: SceneTree = panel.get_tree()
if not tree.process_frame.is_connected(_step_frame):
tree.process_frame.connect(_step_frame) # 恰连接一次守卫（迭代 39 先例）
_step_frame() # 首步同步执行——与 await 形态「第 0 局在调用栈内跑完」对齐
await _batch_finished # 函数级单次 await——不在任何循环体内（键消除的落点）
else:
_finish_batch() # n=0：与 await 形态一致——循环零进，同步收尾零帧
# 每帧恰执行一步（process_frame 发射点回调）；步尽次帧收尾
func _step_frame() -> void:
if _sim_i < _sim_n:
_run_one_level(_sim_autoplay, _sim_stats, _sim_i, panel, _sim_logger) # 逐字保持
panel.set_sim_progress("模拟中：%d/%d …" % [_sim_i + 1, _sim_n]) # 逐字保持
_sim_i += 1
else:
panel.get_tree().process_frame.disconnect(_step_frame) # 先断连（防再入）
_finish_batch()
_batch_finished.emit() # 放行 run() 的 await 与外部 await run(n) 的调用方
# 收尾单点（运行态复位还原为「run 收尾单次执行」——待裁点 1 的申报改动落点）
func _finish_batch() -> void:
_finished = true
_sim_logger.close_session()
panel.set_sim_running(false)
_running = false
panel.set_sim_report(HudPresenter.tune_sim_report(_sim_n, panel.atk_pct(), panel.hp_pct(), _sim_stats, _base_hp))
```
要点：
- **await 只剩一处、在函数级**（`await _batch_finished`），文件内不再有任何 for/while——await-in-loop 键从文本形态上根除，且该文件此后对键**结构性免疫**（无循环即无循环内 await）。
- **run 保持协程身份**：含 await 即仍是协程——`_on_tune_simulate` 不 await 调用（返回函数态、丢弃，与现行为逐字一致）；wd8 的 `await ctrl.run(2)` 挂起到 `_batch_finished` 发射、恢复时整批已完成——**契约零变化、wd8 断言零改动**。
- `_run_one_level` 除删去尾部两行（回归还原，见 §2.3）外逐字保持（含 5 参签名，参数≤5 临界不恶化）。
- 头注按 code-conventions §2.1 增 `_batch_finished` 契约一行（现 4 行→5 行，S10 ≤8 行内）。
- 收尾段内四语句的相对次序（close／两运行态复位／报告）对两个断言面均不可观测（wd8 在整批完成后检查、探针在帧边界检查）——按草图次序落码即可，实现期查 git 历史原序可进一步对齐。
### 4.2 帧相位等价性论证（逐步对齐表）
以 n=3 为例，旧（await）新（状态机）两形态逐帧对齐：
| 时点 | 旧形态 | 新形态 | 等价 |
|---|---|---|---|
| 调用点同步段（按钮信号链内） | setup→第 0 局→进度 1/n→await 挂起 | setup→connect→`_step_frame()` 跑第 0 局→进度 1/n→`await _batch_finished` 挂起 | 同一调用栈、同一同步段、语句同序 |
| 第 1 帧 ①（emit process_frame） | 恢复→第 1 局→进度 2/n→再 await | `_step_frame` 回调→第 1 局→进度 2/n | **同一 emit、同一相位**（帧首、节点 _process 之前） |
| 第 k 帧（1≤k≤n−1） | 第 k 局 | 第 k 局 | 步进体=同一函数 `_run_one_level`＋同一进度语句 |
| 第 n 帧 ① | 恢复（循环自然尽）→close→报告→返回 | `_step_frame` else 分支→断连→close→复位→报告→emit→run 返回 | 终止语句同帧同相位，恰多等的一帧来自旧形态末次 await——草图 else 分支精确复刻 |
| n=0 | 循环零进，同步收尾，不挂起 | else 直调 `_finish_batch`，同步收尾，不挂起 | 一致（含 run 返回形态：均非挂起返回） |
连接次序论证（与同信号其他订阅者的相对序）：产品码内 process_frame 订阅面仅两处——本件与 `settlement_fx_view.gd:94` 的一次性 await（等文本度量，战斗结算呈现期，与模拟批不并存；T0 实查复核）。探针 ⑤ 守卫环的 await 连接时点恒晚于本件（按下返回后才首轮 await）→ 每帧步进先于探针复查，两种形态一致。旧形态每次恢复后重新挂尾连接、新形态常驻连接——对「连接时点早于 run()」的订阅者，两形态中本件都排其后；差异仅在「run 途中新增订阅者」的假想场景，现库为零（已列风险 3）。
## 5. 等价性证明清单（四判据）
| 判据 | 结论 | 依据 |
|---|---|---|
| ① 步数与帧数一一对应不变 | **严格成立** | §4.2 对齐表：第 i 局恒在（调用点 i=0／第 i 帧发射点 i≥1），收尾恒在第 n 帧发射点，n=0 退化路径一致 |
| ② 每步工作量与执行时点不变（同相位） | **严格成立** | 步进体逐字同一函数；执行点同为 emit process_frame（①段，帧首）——await 恢复点与信号回调在引擎内同处一列连接、同一 emit 内被同步调用 |
| ③ 终止条件与终止时读数不变 | **严格成立** | 终止=i 走满 n（else 分支↔循环自然尽）；终止时语句（close/复位/报告）同帧执行 |
| ④ 输出逐字不变 | **成立＋执行化验证** | 报告=未触碰的 `tune_sim_report(stats)`；stats 为种子纯函数（帧时点不进值）；JSONL 由未触碰的 autoplay 写、close 时点同帧——逐位一致由双实现对拍执行证明（见下） |
执行化验证＝**双实现对拍**（test-conventions §5.3「重放：改前改后配对」词汇，非变异类）：新增配对套件——`game/tests/` 面置**遗留形态夹具**（现 run() 的 await 形态逐字副本，尾部两行按还原语义置收尾；tests/ 不在 S13/S8 扫描面，夹具内循环 await 合法在册）；同一假面板＋确定性假驱动分别驱动两形态，断言五行全等：每局调用时记录的**帧索引序列**（直接证明「每步恰一帧、相位同点」——把 §4.2 的论证变成当轮真实执行证据）、驱动读到的运行态序列、进度串序列、stats 六键逐位、报告全文逐字。
**已声明缺口（不能严格证明的点）**：
1. **脚本错误中断路径**：GDScript 无错误陷阱 API。旧形态：步进体内脚本错误→协程死亡→静默停摆（运行态永真、报告永不落）。新形态：错误中断 `_step_frame`→计数未推进→次帧重试同一步（确定性错误→逐帧重试，探针 1800 帧守卫可抓；生产态=持续重试的可见坏，与旧「静默卡死」同级不同形）。此差异不可消除，接受并文档化（待裁点 3）；测量批遇错本就整批作废，两形态都不产出可用读数。
2. **微观连接序对未来订阅者**：若未来有人在 run 途中向 process_frame 新增连接，常驻连接与挂尾连接的相对序会分叉——现库零此场景，登记为实现期 T0 实查项＋代码评审注记。
## 6. gdstyle 键账预期（逐规则核对）
| 规则 | 预期 | 依据 |
|---|---|---|
| quality/await-in-loop（裸键，本案标的） | **消除** | 全文件零 for/while，await 仅函数级一处 |
| quality/allocation-in-loop | 不命中 | 文件零循环；`PlaytestLogger.new()` 在 run 顶层（现状即如此，非循环内） |
| max-function-length ≤50 | 达标 | run 约 22 行、`_step_frame` 约 12 行、`_run_one_level` 删两行后约 10 行 |
| max-branches ≤8 | 达标 | `_step_frame` 一个 if/else；run 一个 if/else |
| max-local-variables ≤10 | 达标 | run 局部 3（logger/stats/autoplay——余者转成员）；`_step_frame` 局部 1 |
| max-returns ≤6 | 达标 | 全 void |
| max-parameters ≤5 | 达标（临界持平） | `_run_one_level` 5 参逐字保持；新函数 0 参 |
| max-class-variables ≤15 | 达标 | 现 5＋新增 6 成员＝11（`_batch_finished` 信号若计入则 12）——成员皆 run 期活承载，非凑数袋 |
键账流程：键消失后闸判定即绿（消失键不参与红判定）；基线死键由批末用户人工 `--refresh` 自然清去（16→15，降幅 <10%，不需 `--force`）。
## 7. 行为零变化风险点
1. **测量读数分布**：stats/JSONL/报告是 (种子, atk, hp) 纯函数、帧时点不进值——结构上零漂移；执行证据=双实现对拍逐位＋探针 ⑤ 输出四串断言。
2. **探针断言面**：⑤ 守卫环语义依赖浮窗运行态贯穿整批——本设计还原该语义（§2.3）→ 探针由「静态推演红」转绿；探针其余段（①–④、⑥–⑩）零触碰。
3. **发布态零影响**：浮窗角标 `_debug_entry` 门控（`main.gd:200`，发布态恒隐、浮窗无 UI 开启口——系统测试与冒烟既有断言面在役）；tune_sim 全链路发布态不可达，本改动不触任何发布路径。
4. **生命周期**：控制器由 `main._tune_sim` 应用期持有（RefCounted 不因帧回调悬挂）；`is_connected` 守卫防信号绕过 disabled 的二次 run 造成双连接双步进；收尾先断连防再入；`_batch_finished` 发射时 run 自身的 await 连接恒在位（不存在零听众发射——n=0 路径不经 emit）。
5. **并发暴露面**：`_on_tune_simulate` 无 is_running 早退（现状即无，本设计不新增——守卫=按钮置灰〔还原后贯穿整批〕＋两层调试入口 is_running 互查）；与还原前相比，运行态中途置假的再入洞被顺手封死（还原语义的附带收益，申报面见待裁点 1）。
## 8. 验收载体
| # | 载体 | 判什么 | 入闸 |
|---|---|---|---|
| 1 | T0 实跑复核：standee_fx_sweep 单套件＋probe_gate --full | 确认 §2.3 潜伏红现状（改动前读数） | 开工首步 |
| 2 | wd8 三断言〔wd8〕（既有，零改动） | 每局运行态真／收尾运行态假＋报告注入／run 可等待——**卡内须显式申报该套件**（套件名与涉案文件无字面关联，diff 推导可能漏选） | run_all 关联档 |
| 3 | 双实现对拍配对套件（新增，§5） | 帧索引序列／运行态序列／进度串／stats 逐位／报告逐字——五面对拍 | run_all 关联档 |
| 4 | ui_tune_probe ⑤（既有，零改动） | 真实 UI 全链路 N=10：守卫环完成＋报告四串＋运行期钮禁用 | probe_gate --full |
| 5 | 批末 `run_all_gates.sh --code` | 所选域全绿；static_scan S13 对账确认 await 键消失、无新键 | 批末 |
## 9. 估时
| 项 | 估时 |
|---|---|
| T0 现状复核（两断言面实跑） | 0.25 工作日 |
| 控制器重构（§4.1 草图落码＋头注契约行） | 0.25–0.5 工作日 |
| 双实现对拍（夹具＋配对套件） | 0.25–0.5 工作日 |
| 孤立验证＋批末代码域闸＋键账对账 | 0.25 工作日 |
| **合计** | **1–1.5 工作日** |
## 10. 待裁点清单
1. **潜伏红处置（必裁）**：现码 `_run_one_level` 尾部两行与 wd8／探针 ⑤ 静态矛盾（§2.3）。推荐：随批还原「run 收尾单次置 false」，作为已申报行为改动进卡（T0 实跑确认现状后施工）；该还原同时封死运行中途的模拟再入洞。若用户掌握「每局置 false 系有意行为」的背景，请指出——但该选择下 wd8 与探针 ⑤ 必红、批不可绿，需另行裁决断言面处置。
2. **双实现对拍是否入批**：推荐入（把帧相位等价从纸面论证变成当轮执行证据；tests/ 面不入 S13 扫描面、夹具内循环 await 合法）。备选：仅靠 wd8＋探针 ⑤（省一测试件，相位等价无执行化证据）。
3. **错误路径差异接受度**：脚本错误下「逐帧重试」对「静默停摆」的差异（§5 缺口 1）不可消除。推荐：接受并文档化。备选：`_on_tune_simulate` 加 is_running 早退守卫兜底——+1 行为面、system_test〔wd7〕前置断言随之需复核，代价大于收益。
## 11. 关联文档同步面（随批义务备查，经反哺点通道落文）
- `design/engineering/architecture/architecture.md`「测试与质量域」：S13 测量面豁免登记首条（2026-10-27 tune_sim await）**注销**；同段其余条目（battle_orchestrator 第三条等）不在本案范围。
- `tools/gdstyle_baseline.txt`：await 裸键随批末人工 `--refresh` 消失（禁实现批中途 refresh）。
- `game/tests/README.md` 能力清单：配对套件入表归写卡段（实现批禁写该文件）。
reports/设计-组合根注册面-2026-10-29.md
-236
View File
@@ -1,236 +0,0 @@
# 设计——组合根注册面（S13 真修复：main.gd 类变量归 15）
状态行：设计讨论段过程稿 v1.0——待主会话汇总裁决（2026-10-29）
## 0. 背景与判据来源
用户 2026-10-29 裁「不允许任何豁免」：main.gd 的 S13 键（`game/presentation/main.gd|quality/max-class-variables = 49`，阈值 15）必须真实修复，architecture 在册的 S13 豁免登记（「组合根类变量面即探针契约面」）随批注销。主会话已点头的主方向：把屏壳＋覆盖层一级句柄收进一个「注册面／接口层门面」件，探针从 `main.X` 改走注册面地址。
本设计的判据来源：
- code-conventions §1.1 拆分边界纪律五条（职责轴拆分、集体身份、过阈值只作发现信号、拆不出即停卡、禁无效成员别名）与 §1.3 依赖单向（组合根＝main.gd＋其构造注入的组合根拆件）。
- architecture「呈现层装配与会话生命周期」「模块归属·呈现层」「测试与质量域」三节。
- godot-master 的 Node 取舍判据（"Use RefCounted for logic objects and data containers. Reserve Node for things that must exist in the scene tree"）与信号卫生条款；本仓既有先例：ConfigDB 迭代 41 用「三张域容器」解决同构的成员数超标问题，ModalFlow／各交互控制器均为持引用的 RefCounted。
- 源码实查：main.gd 915 行 49 var（实数复核）；探针＋system_test 的 `main.X` 成员引用 867 处（机械统计，扣除 main.tscn/get_node/get_viewport 等非成员形态）；四个流程承接件 `root.X` 引用约 350 处。
## 1. 注册件形态
### 1.1 推荐形态：一个门面＋三个域容器（四文件，全 RefCounted，不挂树）
| 新件 | 文件 | extends | 类变量数 | 职责一句话 |
|---|---|---|---|---|
| **界面注册面** | `game/presentation/ui_registry.gd` | RefCounted | **3** | 呈现层界面元素清单：持有三域容器、LAYER_CONTRACT 合同表、`node(key)` 合同寻址、`apply_layer_contract(root)` 唯一落位口 |
| **屏壳与全屏容器域** | `game/presentation/ui_screens.gd` | RefCounted | **9** | 三屏壳、屏内一级子层、全屏态、浮层角标、排播泵节点的句柄册 |
| **战区视图域** | `game/presentation/ui_battle.gd` | RefCounted | **5** | 战斗屏 A–D 区视图与结算演出句柄册 |
| **模态层域** | `game/presentation/ui_modals.gd` | RefCounted | **14** | 十三个模态覆盖层句柄＋ModalFlow 栈编排（登记、开合、锁谓词） |
main.gd 新增一个成员 `ui`（类型 UiRegistry），探针与流程件的新地址形如 `main.ui.modals.level_screen`、`main.ui.battle.board_zone`、`main.ui.screens.menu_screen`。
**为什么是三容器而不是一件**： gdstyle 阈值 15 是按文件的，句柄 27 个＋flow/row_pacer 共 29 个进一个文件必然超阈、又要开新基线键＝留债，违用户裁决出口。 分组轴不是拍脑袋切的——它就是 LAYER_CONTRACT 的 kind 轴（modal／shell／state／float／node）加上 battle.md 的战区轴，三组身份先于本批存在（详见 §2），是「按既有领域轴收拢」，不是「为凑 15 而切」。
**为什么是 RefCounted 不是 Node**： 注册面是纯句柄容器＋合同数据，零 `_process`、零绘制、零树位需求——按 godot-master 判据「Node 只留给必须在场景树里存在的东西」应取 RefCounted。 它持有的节点（屏壳/覆盖层/视图）都是 `_build_ui` 一次装配、随 main 同生死的常驻件，不含任何会话期 `queue_free` 对象（局态在 run_scope，留 main），RefCounted 持 Node 引用无悬挂风险；本仓先例充分：ModalFlow、TreasureInteractController、CampShopPresenter、DebugSession、SettingsStore 全是持引用 RefCounted。 若做成 Node 挂树，反而要回答「它占哪个树位」「进不进 LAYER_CONTRACT」「冒烟 V1d 怎么看它」三个新问题，纯增噪声。
**class_name**： 四件均给 class_name（UiRegistry/UiScreens/UiBattle/UiModals），main 里 `var ui: UiRegistry` 类型化；随批跑一次编辑器扫描刷新全局类缓存＋同步 .uid（code-conventions 语言纪律 5）。
### 1.2 逐成员去向对账表（main.gd 现有 49 var，三档：进注册面／留 main／消灭）
**进注册面（28）**——成员名在容器内去下划线（变为公共地址面，与 LAYER_CONTRACT 键名对齐）：
| # | 现 main 成员 | 去向 | 依据 |
|---|---|---|---|
| 1 | `_menu_screen` | `ui.screens.menu_screen` | 屏壳（kind=shell） |
| 2 | `_camp_screen` | `ui.screens.camp_screen` | 屏壳 |
| 3 | `_adventure_screen` | `ui.screens.adventure_screen` | 屏壳 |
| 4 | `_start_overlay` | `ui.screens.start_overlay` | 菜单屏内一级子层 |
| 5 | `_battle_root` | `ui.screens.battle_root` | 冒险屏内一级子层 |
| 6 | `_inter_overlay` | `ui.screens.inter_overlay` | 全屏态（kind=state） |
| 7 | `_inter_label` | `ui.screens.inter_label` | 过场层附随标签 |
| 8 | `debug_badge` | `ui.screens.debug_badge` | 全局浮层（kind=float） |
| 9 | `_row_pacer` | `ui.screens.row_pacer` | LAYER_CONTRACT kind=node 注册层（节点本体仍 add_child 到 main，注册面只持引用，树位零变化） |
| 10 | `stage` | `ui.battle.stage` | 战斗屏 B 区 |
| 11 | `log_view` | `ui.battle.log_view` | B 区明细带 |
| 12 | `info_panel` | `ui.battle.info_panel` | C 区 |
| 13 | `board_zone` | `ui.battle.board_zone` | D 区（含 toast/fx/board_view/ap_bar） |
| 14 | `settlement_fx` | `ui.battle.settlement_fx` | 结算演出覆盖层 |
| 15 | `legend_overlay` | `ui.modals.legend_overlay` | 模态层（kind=modal，13 件全集） |
| 16 | `node_overlay` | `ui.modals.node_overlay` | 模态层 |
| 17 | `level_screen` | `ui.modals.level_screen` | 模态层（host=adventure_screen，TAG_SCREEN_STATE） |
| 18 | `curio_overlay` | `ui.modals.curio_overlay` | 模态层 |
| 19 | `_end_overlay` | `ui.modals.end_overlay` | 模态层 |
| 20 | `shop_overlay` | `ui.modals.shop_overlay` | 模态层 |
| 21 | `camp_overlay` | `ui.modals.camp_overlay` | 模态层（shell=camp_screen） |
| 22 | `settings_overlay` | `ui.modals.settings_overlay` | 模态层 |
| 23 | `status_panel` | `ui.modals.status_panel` | 模态层 |
| 24 | `career_overlay` | `ui.modals.career_overlay` | 模态层 |
| 25 | `save_select_overlay` | `ui.modals.save_select_overlay` | 模态层 |
| 26 | `confirm_dialog` | `ui.modals.confirm_dialog` | 模态层 |
| 27 | `debug_overlay` | `ui.modals.debug_overlay` | 模态层（TAG_NON_LOCKING） |
| 28 | `_modal_flow` | `ui.modals.flow` | 模态编排与模态层同域（登记/开合/锁谓词的宿主） |
**留 main（14）＋新增（1）＝改后 15**：
| # | 成员 | 保留理由 |
|---|---|---|
| 1 | `db` | 核心配置读视图——组合根唯一加载单点读取入口（`_ready` 装配） |
| 2 | `run_scope` | 会话承载节点——架构在册「局态一律住 RunScope，组合根经 run_scope.X 读写」；173 处探针引用零迁移 |
| 3 | `save_manager` | autoload 读视图——architecture 在册「main.save_manager 语义零迁移」 |
| 4 | `meta` | autoload 读视图（同上） |
| 5 | `settings_store` | 系统级设置存储——非界面元素（无视觉面），`_ready` 装配、`_quit_game` 落盘、SettingsOverlay 构造注入 |
| 6 | `logger` | 试玩日志器——组合根埋点面（非界面元素） |
| 7 | `_debug_entry` | 调试会话门控（组合根启动态布尔） |
| 8 | `_confirm_consumer` | 确认弹窗分派状态量（组合根自身状态） |
| 9 | `_confirm_consumer_slot` | 分派附随槽号（与 8 同一关注点成对读写） |
| 10 | `_debug` | DebugSession——调试会话状态机持有（逻辑件非界面件） |
| 11 | `_treasure_ui` | TreasureInteractController——组合根拆件（核心写调用代执行） |
| 12 | `_bonus` | CurioInteractController——组合根拆件 |
| 13 | `_camp_pres` | CampShopPresenter——组合根拆件 |
| 14 | `_tune_sim` | TuneSimController——调参测量控制器（逻辑件） |
| 15 | `ui`（新增） | 界面注册面——本设计的唯一新成员 |
这 14+1 全部是「组合根自身状态＋拆件引用＋autoload 读视图」，正是 §1.1 拆分纪律下组合根该留的最小内聚面；没有一件是因为「计数不够了才留下」的。
**消灭（7）**——全部是别名或一行转发，属拆分纪律⑤明令禁止保留的无效成员：
| # | 成员 | 本体 | 消灭后地址 |
|---|---|---|---|
| 1 | `board_view` | = board_zone.board_view | `ui.battle.board_zone.board_view`（探针惯用 `var bv = ...` 局部承接，每文件 1–2 处） |
| 2 | `ap_bar` | = board_zone.ap_bar | `ui.battle.board_zone.ap_bar` |
| 3 | `_modals` | = _modal_flow.stack | `ui.modals.flow.stack`（ui_struct 登记序断言） |
| 4 | `_row_queue` | 委托属性 = _row_pacer.pending_rows() | `ui.screens.row_pacer.pending_rows()`（main 自身 3 处＋pacing_queue_test 1 处；同一 Array 引用，语义不变） |
| 5 | `_seed_edit` | = debug_overlay.seed_edit | `ui.modals.debug_overlay.seed_edit.text`（仅 main._seed_value 内部消费，探针零引用） |
| 6 | `_settlement_stop_pending` | 委托属性（读=timer.is_armed()，写=arm()/disarm()） | `run_scope.settlement_stop_timer` 直呼（ui_click_probe 2 处读＋main_adventure_flow 3 处写） |
| 7 | `_deferred_modal` | 委托属性 = _modal_flow._deferred | `ui.modals.flow._deferred`（t17_defer_probe 1 处） |
对账：14（留）＋28（进注册面）＋7（消灭）＝49 ✓；main 改后 = 14＋1（ui）＝**15，恰在阈值内**。
### 1.3 main.gd 改后类变量实数
**15**（14 留＋ui）。gdstyle 的 max-class-variables 语义是「超过 15 才红」，15＝绿。此后 main 每想加成员就是过阈红——这正是拆分纪律③的合规用法：过阈值作发现信号，新句柄该进注册面、新职责该拆新件。
## 2. 职责语句＋单一变化原因
| 件 | 职责语句 | 单一变化原因 | 集体身份判据 |
|---|---|---|---|
| ui_registry | 「呈现层界面元素清单的唯一事实源——哪些层、什么序、地址在哪」 | 界面元素集合或层序变化（加屏/加覆盖层/改层序） | 它就是今天散在 main 的 LAYER_CONTRACT＋_layer_node＋一级句柄三样东西的合体；合同键、登记序、句柄址本是同一份清单的三个投影 |
| ui_screens | 「不进模态栈的树位层册——三屏壳与其一级子层、全屏态、浮层角标、排播泵节点」 | 屏壳/全屏态/浮层集合变化 | 集体身份＝LAYER_CONTRACT 里 kind≠modal 的项（shell/state/float/node）＋屏内一级子层句柄 |
| ui_battle | 「战斗屏四区（A 状态/B 明细/C 数据/D 棋盘）视图与结算演出句柄册」 | 战斗区视图构成变化（battle.md 三区面） | battle.md 三区＋演出，是架构文档反复引用的既有概念，非本批发明 |
| ui_modals | 「模态层域——十三个模态覆盖层句柄＋模态栈编排（登记/开合/输入锁谓词）」 | 模态层集合或模态编排语义变化 | 集体身份＝「被 ModalStack 登记的层」——遮挡互斥、开合同步、锁谓词是这 13 件共享的行为面 |
**禁凑计数袋自检（拆分判据①–⑤逐条）**：
1. 拆分沿职责轴：三容器的轴＝LAYER_CONTRACT kind 轴＋战区轴，两者都是本批之前就存在的领域轴；过阈值（49→15）只是**发现信号**，不是切分依据。
2. 集体身份：每件命得出名字、说得清「共同表达什么」（见上表），没有一个容器是「剩下的成员」。
3. 过阈值只作动机＝违规：本设计若只把 30 个句柄原样搬进一件，那才是凑计数；按领域轴分三域＋把合同机器（今天在 main 里同样占职责面的 LAYER_CONTRACT/_layer_node）一并归位，是职责收拢。
4. 拆不出内聚单元须停卡：本设计拆得出（见上），不停卡。
5. 禁无效成员/别名：本批**净消灭 7 个别名/转发成员**（§1.2 第三表）＋退役 main 侧六个纯转发方法（§4.2），方向是减不是留。
依赖方向自检（§1.3）：注册面只持视图引用、零核心写调用、零信号连接——它不是新的写调用出口，组合根单点装配不变；视图仍经信号到 main（或 main 拆件）再到 core，依赖单向零触碰。
## 3. 探针契约迁移
### 3.1 新地址形态
**推荐**：`main.ui.<域>.<句柄>`（例：`main.ui.modals.level_screen`、`main.ui.battle.board_zone`、`main.ui.screens.menu_screen`）。三段式地址每段都有领域含义（组合根→注册面→域→元素），与 ConfigDB 的 `db.<域容器>.<成员>` 两段式同构——本仓已验证的容器寻址形态。
**备选一（双容器直挂，`main.modals.X` 两段式）**：少一跳，但 main 要放 3 个容器成员，改后 main＝16 过阈，只能再靠合并 `_confirm_consumer_slot` 之类凑减员——凑计数味，淘汰。
**备选二（单件＋字典存储＋方法访问器 `main.ui.layer("legend_overlay")`）**：丢了类型化字段，且约 30 个访问器方法有撞 max-public-methods 默认阈值的风险（board_view 现值 27 已在基线，默认阈值必然更低）＝新基线键＝留债，淘汰。
### 3.2 改址策略（约 867 处探针/系统测试引用＋约 200 处流程件 root.X 引用＋main 自身）
**机械映射表**（实现批以脚本生成＋对账，人工复核语义位）：映射表条目形如 `旧路径 → 新路径`，来源即 §1.2 对账表。三类引用分别处理：
1. **属性读/写（约 750 处）**：`main.<名>` → `main.ui.<域>.<名′>`（`名′`＝去下划线后的名）。前缀链式读写在 GDScript 天然支持（`main.ui.modals.debug_overlay.seed_edit.text = "42"` 与现形态同构）；探针里 `var bv = main.board_view` 的局部承接习惯使别名消灭的实际改动收敛到每文件 1–2 处。
2. **方法调用（约 110 处，其中绝大多数零迁移）**：组合根流程方法（`_start_adventure_from_menu` 16、`_open_save_select` 7、`_on_save_select_closed` 9、`_on_camp_closed` 6、`_on_battle_end_continue` 4、`_show_debug_overlay` 4、`_resume_from_menu` 3、`_flush_row_queue` 3、`_seed_value` 3 等）**留 main，零迁移**——它们是模式流转与流程入口，本就是组合根职责。真正改址的方法引用只有四条：`main._input_locked()`（18 处）→ `main.ui.modals.flow.locks_input()`；`main._layer_node(key)`（3 处，system_test）→ `main.ui.node(key)`；`main._open_modal/_close_modal`（探针各 1 处＋流程件 root. 共约 23 处）→ `main.ui.modals.flow.open/close`；`root._open_modal_after_playback`（2 处）→ `root.ui.modals.flow.open_after_playback`。
3. **字符串键取值（smoke_boot 的 `main.get("<名>")` 6 处）**：`main.get("run_scope")`/`main.get("settings_store")` 零迁移（留 main）；其余改 `main.get("ui").<域>.<名′>`（get 只解析一层，后续走公共字段）。
**流程承接件随批同规改址**：main_ui_build 的赋值目标改 `root.ui.<域>.<名′> = ...`；main_adventure_flow/main_overlay_flow/main_debug_flow 的 `root.<名>` 同表映射。构造注入的 context 束（CurioFlowContext/CampFlowContext 的 overlay/toast/start_overlay 等键值）改址取值，注入时点与值不变。
**源码级断言随批重锚（易漏项，实查全量在案）**：
- `source_guard_test.gd` V1d「层序落位单口」：现扫描 main.gd 源码中 `_apply_layer_contract` 之外零 `move_child(`。合同机器迁入 ui_registry 后，重锚为「扫全 `game/presentation/*.gd`：`move_child(` 只允许出现在 ui_registry.gd 的 `apply_layer_contract` 函数体内」（判据同步强化：从扫单文件变扫全目录，比原判据更严）。
- `theme_projection_test.gd` V6：`main_src.contains("debug_overlay.diagnose_requested.connect(_on_diagnose_pressed)")` 字符串断言 → 改为 ui.modals.debug_overlay 新串。
- 其余 main.gd 源码断言（V8 GP 影子账残留检查）为「禁止出现」型，不受影响；`meta_progression_forge_test` 经 `load("res://presentation/main.gd")` 直呼 static `build_adventure_params`——留 main，零迁移。
**改址完整性自检**（验收辅证）：映射表驱动的全仓 grep——`game/` 下（探针/tests/flow 四件/main 自身）旧一级路径 `main.<旧名>`／`root.<旧名>`／`self.<旧名>` 残留必须为 0（按 49 名逐名 grep，报告留档）。
### 3.3 architecture 登记句改写建议
「呈现层装配与会话生命周期 §三屏壳与组合根句柄面」现句（含 S13 豁免登记）整句退役，建议改写为：
> 屏成员与覆盖层句柄经**界面注册面**（main.ui，`ui_registry.gd`＋三域容器 ui_screens/ui_battle/ui_modals，全 RefCounted）统一暴露；探针挂载假设＝`main.ui.<域>.<句柄>` 路径（2026-10-29 用户裁「不允许任何豁免」——原「组合根 main.gd 一级句柄（main.X 路径零迁移）」挂载假设与 S13 豁免登记同批注销，探针面全量改址，行为零变化由 probe_gate／render_gate／冒烟／系统测试四闸主证）。组合根 main.gd 成员面收口为组合根自身状态＋拆件引用＋autoload 读视图（类变量 15，阈内）。层序唯一事实源＝`ui_registry.LAYER_CONTRACT`＋`ui.apply_layer_contract()`；模态登记/开合/锁谓词单口＝`ui.modals`（ModalFlow 语义零变化）。
「模块归属·呈现层」表同步增四行（四新件），main_ui_build 行的「层序逻辑不在此件——唯一事实源仍是 main.LAYER_CONTRACT」句改指 ui_registry。
## 4. main.gd 改后形态
### 4.1 剩余成员清单
见 §1.2 第二表（14 留＋ui，逐个理由在表内，不重复）。文件头注同步改写：组合根职责语句追加一句「界面句柄与层清单在 ui 注册面（ui_registry.gd）」。
### 4.2 接线流程变化
1. **装配入口**：`_ready` 在 `_build_ui()` 之前 `ui = UiRegistry.new()`（容器随门面构造）；`MainUiBuild.build(self)` 八步内部赋值目标全部改 `root.ui.<域>.<名′>`，八步顺序、add_child 顺序、连接语句逐条不变。
2. **MainUiBuild 交付物改型**：build 签名不变（仍 `build(root)`），改的是写入目标——从「给 root 造 30 个一级成员」变「往 root.ui 三容器登记」。装配序与 z 序零改动（合同落位仍最后一步）。
3. **合同机器搬家**：`LAYER_CONTRACT` 常量（内容逐字不动）、`_apply_layer_contract()`（root 作参传入）、`_layer_node(key)`（改为 ui_registry.`node(key)` 的 19 键 match）、`_register_modal`（改入 ui_modals 为 `register_layer(m, tags)`，anchors preset＋flow.register 语义逐字）四样整体迁入注册面；main 侧不留转发壳。
4. **模态口收口**：main 的六个纯转发方法退役——`_open_modal`/`_close_modal`/`_on_modal_closed`/`_input_locked`/`_open_modal_after_playback`/`_on_pump_ended`。调用方（三个流程件、context 注入束、row_pacer.pump_ended 注入点、信号 connect 的 bind 目标、探针）一律改指 `ui.modals.flow` 真方法；`_replay_locked_click` **留 main**（读 run_scope.locked_click＋调 _on_board_action，是组合根行为，作为回调注入 flow 不变）。
5. **`_seed_value()`**：种子框读取改 `ui.modals.debug_overlay.seed_edit.text`（全工程唯一种子框读取处纪律不变）。
### 4.3 LAYER_CONTRACT 与 _apply_layer_contract
合同表条目、顺序、tags、host/shell 标注**逐字零变化**，只换宿主文件；落位算法逐字搬运（move_child 单口语义不变，冒烟 V1d 判据按 §3.2 重锚后仍覆盖「全 presentation 无第二落位点」）。改层序仍只改合同表。
### 4.4 RunScope 生命周期零变化声明
`_begin_session`/闲时会话/整节点 `queue_free` 机制**一字不动**；run_scope 留 main，注册面与三容器**零会话期引用**（不持 adventure/runner/settlement，控制器仍走现值回调），会话更替对注册面完全透明。存活性矩阵第五引用面的四持句柄件＋_row_pacer 逐面同源比对断言（system_test V3a–V3i）逻辑零变化，仅 `_modal_flow`→`main.ui.modals.flow`、`_row_pacer`→`main.ui.screens.row_pacer` 两处取址随批改。
## 5. 行为零变化风险点
1. **装配与接线时序**：容器在 `_ready` 建闲时会话之前创建并装配完毕，八步 build 顺序、`_apply_layer_contract` 末位调用点、信号连接顺序逐条不变。风险形态＝漏改一处地址→运行期 null 实例 SCRIPT ERROR→被冒烟闸③与探针 error_scan 抓住（不静默）。
2. **模态开合**：ModalFlow 的八个查询/钩子 Callable（start_visible_get/inter_visible_get/settlement_get/rows_empty_get/flush_rows/on_open_sync/on_close_sync/replay_click）注入值不变，仅 `root._start_overlay.visible` 这类 lambda 体内取址改 `root.ui.screens.start_overlay.visible`；开合编排、挂起兜底、点击重放语义零触碰。
3. **会话更替**：注册面零局态引用（§4.4），queue_free 不触及；row_pacer 节点本体仍 add_child 到 main、树位由合同落位，注册面只持引用——第五引用面断言改址后逐面同源比对仍成立。
4. **别名消灭的断言等价性**：board_view/ap_bar/_modals/_row_queue 四件消灭后，探针断言经多一跳取到**同一对象引用**（属性链与别名同指），断言语义逐条等价；system_test V1 的句柄等价断言（`main.board_view == main._adventure_screen.board_view` 型）改址为 `ui.battle.board_zone.board_view == ui.screens.adventure_screen.board_view` 后仍是有效的装配结构断言。
5. **接缝属性消灭的读/写映射**：`_settlement_stop_pending` 读=armed→`is_armed()`、写=arm/disarm→同名方法直呼，映射一一对应且 run_scope 在探针用时点恒非空（_ready 即建，永非 null 契约）；`_deferred_modal`→`flow._deferred` 同字段直读。
6. **演出链**：settlement_fx/row_pacer 的 play/enqueue 调用点改址不改序——结算行排播、轮横幅、锁期点击重放的时序敏感面（T17）零触碰；t17_defer_probe 挂起态断言改读 `flow._deferred`，判据不变。
7. **源码级断言漏改**：V1d/V6 两处实查在案（§3.2），随批重锚；若存在未登记的字符串匹配型断言，run_all 关联档跑批暴露——本设计已全量 grep `presentation/main.gd` 引用面确认只有上列两件。
RNG 消费序零触碰（本批不涉任何随机面）；PARITY 触面（battle_orchestrator.gd）不在 diff；呈现层订阅禁令、核心写调用唯一出口纪律零触碰。
## 6. 验收载体建议
| 闸 | 载体与判据 |
|---|---|
| probe_gate | **默认段＋`--click`＋`--full` 全跑**——探针是本批改址的第一消费方（ui_click_probe 1079 行是最大户），只跑默认段会漏最深的改址面；判据＝全段退出码 0 |
| render_gate | golden 零差异（shot_probe 七屏＋菜单 golden＋棋盘 golden）——视觉零变化的主证 |
| run_smoke | V1 装配句柄在位（get() 键改址后）＋V2 启动态六条——boot 侧证明注册面装配完整 |
| run_system_test | V1–V9 全绿：LAYER_CONTRACT 寻址（改 ui.LAYER_CONTRACT/ui.node）、句柄等价、存活性矩阵、模态互斥、两连局+续玩 |
| run_all（关联档） | 申报套件：source_guard_test（V1d 重锚）、theme_projection_test（V6 字符串）、pacing_queue_test（_row_queue 改址）、meta_progression_forge_test（static 入口零变化）；main.gd 是否按横切面回落全量套件见 §8 待裁点 |
| static_scan | S9 过（四新文件全类型标注）；S13 键账：main.gd 键从基线消失、四新文件零新键（§7） |
| 改址完整性自检 | §3.2 的 49 名逐名 grep 残留＝0，报告留档（实现报告对照表挂行） |
验收闭合口径（test-conventions §8）：判据绑定面＝「探针经新地址取到同一节点并驱动真实输入路径」——probe_gate 全绿＋系统测试全绿＋golden 零差异三件齐，即「改址不改变行为」的真实入口主证；grep 自检只作完整性辅证，不作行为判据。
## 7. gdstyle 键账预期
| 文件 | 改后类变量 | 键账 |
|---|---|---|
| main.gd | **15**（14＋ui） | 基线键 `main.gd|quality/max-class-variables = 49` 消失——还债方向下降，注销合法 |
| ui_registry.gd | 3 | 零新键 |
| ui_screens.gd | 9 | 零新键 |
| ui_battle.gd | 5 | 零新键 |
| ui_modals.gd | 14 | 零新键（阈内，余量 1） |
基线 refresh 人工跑（`--refresh`）：净减 1 键（约 15 键的 6.7%），低于 10% 骤降守卫，无需 `--force`。四新文件其余质量键（max-public-methods/max-file-length 等）预期零命中——容器纯字段无长函数，match 键数（19）在 max-branches 默认内，若实现批实测出新键按基线外 NEW 红处理、不得开豁免（用户裁决口径统一适用）。
§3.3 的登记句改写即豁免注销文案；「S13 豁免登记第二/三条」（tune_sim_controller、battle_orchestrator）不在本批范围、原文不动。
## 8. 估时与待裁点
**估时：3–4 个工作日**。构成：映射表脚本生成＋四文件建件＋main/流程件改址 1–1.5 天；探针/系统测试/冒烟改址＋源码级断言重锚 1 天；闸循环（probe_gate --click --full／render golden／smoke／system_test／run_all 关联档／static_scan）修复余量 0.5–1 天；architecture 登记句＋模块归属表＋卡片改动—验收对照表 0.5 天。低于迭代冻结线（5 工作日），可编批。
**待裁点（呈用户裁决）**：
1. **注册面拓扑**：推荐「一门面＋三域容器」（§1.1，main=15）；备选「双容器直挂」因 main 会过阈 16、需再凑减员而淘汰。是否照推荐案执行。
2. **合同机器是否随批迁入注册面**：推荐迁（LAYER_CONTRACT＋_apply_layer_contract＋_layer_node＋_register_modal → ui_registry/ui_modals，职责闭合）；不迁则注册面只管址不管序，main 留合同——两案都可达 15，迁是内聚更优解但多动 V1d/system_test 约 8 处。
3. **消灭与改名清单**：七个别名/转发成员消灭＋六个 main 纯转发模态方法退役＋容器内成员去下划线（对齐合同键名）——涉及探针断言面写法（`main._input_locked()`→`ui.modals.flow.locks_input()` 等），请整体确认或逐项裁。
4. **run_all 关联档口径**：main.gd 是全探针宿主，保守口径＝按横切面回落全量套件；精确口径＝只跑 §6 申报四件。请裁跑批档位。
5. **编批**：估时 3–4 天在冻结线内，编入哪个迭代由迭代编排段定。
reports/需求卡片-战斗编排归约批-2026-10-29.md
-208
View File
@@ -1,208 +0,0 @@
# 需求卡片——战斗编排归约批（battle_orchestrator 类变量 38→15）
> **版本状态**：v1.0 定稿——零待裁点（2026-10-29 用户裁：RoundCycle/BattleFacts 两件形态、encounter 归 BattleFacts、attune 改判、treasure_inventory 改址追认、完美账写口升级可裁量）。
> **接收方**：待办清单条目「战斗域结构深拆批——效果发射端口＋宿主瘦身＋掷格/受理分件（2026-10-27 登记，来源=批次移交）」——本卡承接其中 battle_orchestrator 瘦身面（architecture 轴丁）；该条目的效果发射端口与 reward_economy 分件两子项不在本卡。
> **来源**：`reports/设计-战斗编排类变量归约-2026-10-29.md`（设计讨论段定稿，五待裁点 2026-10-29 用户裁全闭合）。**唯一事实源**：该设计文档全文 ＋ `design/engineering/architecture/architecture.md` v1.25「战斗编排域拆件定稿」节轴丁与「模块归属·功能层」RoundCycle/BattleFacts 两行。
## 1. 目标与完成定义
这批做什么：把战斗结算编排宿主 `game/core/battle_orchestrator.gd` 的 38 个类变量收敛到 15（＝gdstyle 阈值，合规）。手段＝按变化原因拆两枚新件收编 22 个成员——**RoundCycle**（轮循环驱动件：五段段件持有、段序执行、结算重入门闸、开轮摇号、踩雷计数账）与 **BattleFacts**（战斗事实件：受理事实 encounter、轮 facts 缓冲、封印判定账、装板溯源、条件计数、同调快照；attune 状态两成员随件、行为函数留宿主）——外加两项单点处置：treasure_inventory 注入改址（level_runner 经 RewardGrant 出口直注，原「外部赋值路径零改址」句经用户追认失效）与 _hero_atk 转派生读。
什么状态算完：
1. 宿主类变量实测 15、两新件零 gdstyle 键、battle_orchestrator 全文件零超标键（第 9 节键账）。
2. 游戏行为零变化：同种子完整局步骤流、事件流、两快照载荷逐位一致（第 4 节红线；第 11 节 V0 行）。
3. 批末代码域闸全绿（冒烟＋系统测试＋单元集成关联档＋探针＋静态扫描），键账对账完成（第 12 节）。
4. 实现报告与反哺点清单落 `reports/`（T4 产出物落位卡）。
## 2. 设计事实源
- `reports/设计-战斗编排类变量归约-2026-10-29.md`——设计讨论段定稿全文。逐成员去向（38 项五去向）、两新件形态与耦合边界、attune 重裁决、已否决切法、随迁键义务、行为零变化风险点、键账预期、改址盘点，全部以该文档对应节为唯一合同；本卡不复制其表格，T0 逐名对账时引用。
- `design/engineering/architecture/architecture.md` v1.25——「战斗编排域拆件定稿」节轴丁两件（RoundCycle/BattleFacts，跨件单向接线、段类随动、attune 改判、S13 键账收敛义务、验收红线）与「模块归属·功能层」两行、「测试与质量域」S13 豁免第三条注销句——实现照册施工。
- 五待裁点裁决（2026-10-29 用户裁，对应设计文档 §13）：①encounter 归战斗事实件＝采纳；②treasure_inventory 注入改址＝追认（「外部赋值路径零改址」句失效）；③attune 重裁决＝采纳「状态归 facts、行为留宿主」；④完美账写口升级＝采纳（grant_segment 三处直写改经 facts 三方法）；⑤对拍闸已随 2026-10-30 工程批退役（用户裁：整局重放对拍不再作验收载体）——原 PARITY 批准待裁点就此注销。
## 3. 现状事实（代码级，2026-10-29 实查；开工 T0 按当轮 master 重测复核）
- `tools/gdstyle_baseline.txt:9-10`——battle_orchestrator.gd 现登记两条类级键：`quality/max-class-variables = 38`、`quality/max-file-length = 1035`；**该文件零函数级键**（59 个函数全部在默认阈值内——设计文档 §7 前提成立，T0 复核）。
- 宿主 38 类变量声明区＝`battle_orchestrator.gd:37-85` 与 `:223-227`（逐名清单见设计文档 §2 表）。宿主改后保留 15：db、rng、minesweeper、action_economy、_enemy_system、_status_effects、_reward_economy、_damage、_fx_host、_reward_grant、round_index、battle_result、nest_preview_count、_rounds、_facts。
- **编队前置实态**：迭代 42（gdstyle 尾波清偿批，roadmap 在册）合回后轴丙 BoardInstaller 已建——`_board_generator` 成员随件退役（38→37）、装板域六函数迁出、宿主复位块留薄壳 `_install_and_reset`、文件长键归绿；届时宿主约 890 行/37 成员，本卡叠加其上。**本卡在迭代 42 合回之前禁开工**；T0 按当轮 master 重测对账。
- 段驱动现态：五段构造 `battle_orchestrator.gd:256-260`（授予/战斗两段三引用形，aura/decay/verdict 单引用形）；三闸 `_maybe_settle` :592-597；段序体 `_settle` :602-613（终局早退不回置 _settling）；开轮摇号 `_roll_round_actions` :677-721（behavior_roll 流 :717，mines_hits 转存 :720-721）；`_on_round_end` 末行 :589 调 `_maybe_settle`。
- 事实族写读点：缓冲追加 `_on_cell_revealed` :554-580（身份快照捕获 :576 留宿主）；`_on_seal_judged` :583；`_facts_path` 写 `_on_round_end` :588；轮复位 `_reset_round_facts` :976-979（三调用点 :273/:810/:862）；封印/完美/标错/板序/溯源清零在装板复位块 :442-446（迭代 42 后归宿主薄壳）；`_refresh_used_this_round` 复位点 `_exit_distribution` :811；完美谓词 `perfect_sweep_earned` :1033-1035。
- treasure_inventory：宿主声明＋setter 转发块 `battle_orchestrator.gd:48-52`；唯一外部注入点 `level_runner.gd:520`；宿主读 :111/:203/:450/:858；`grant_segment.gd:370-371` 读 `oc.treasure_inventory`。
- _hero_atk：声明 `battle_orchestrator.gd:227`、受理写入 :304、spawn 消费 :305、`combat_segment.gd:56` 消费 `oc._hero_atk`。
- attune 外部三面（零改址标的）：`attune_has` 公有面消费＝table_structure_guard_test 起战断言（:162/:166）与 breakpoint_resume_test；`attune_param_sum`＝main.gd:567 与 treasure_effects_test；`attune_convert_state`＝treasure_interact_controller.gd:125。三面全部留宿主公有面。
- 冻结面：`nest_preview_count` 外部直读＝main.gd:536-537＋treasure_effects_test:153；`round_index` 公有直读＝system_test.gd:447-462（st.round_index）等四套件约 15 处。
- **设计文档 §11 漏列一处（T0 实查补入）**：`settle_segments_test.gd:27` 接线断言 `oc._grant_seg != null and oc._grant_seg.oc == oc`——段件迁 RoundCycle 后必红，须改指 `oc._rounds._grant_seg`。
- 对拍闸（原闸 11 与 PARITY_TOUCH_FACES 触面判定）已随 2026-10-30 工程批退役——本批无触面批准事项；T0 复核以此为准。
- `game/tests/static_scan.sh`——S8 await 文件集（:317，9 文件）与 S7 B1 域文件集（:359，9 文件）均未含两新件路径；round_cycle.gd 经 oc 调 B2 符号（`_enemy_system` 族）须随批增行，battle_facts.gd 零协作调用不入清单。
## 4. 设计契约（违反即返工的红线条款）
- 🔴 **行为零变化（本批总判据）**：同种子下事件流/步骤流/两快照载荷/存档往返逐位一致；玩家可见面零变化；`design/gdd/systems/` 零修订预期。
- 🔴 **RNG 取号序零漂移（封闭流随件迁移先例句）**：behavior_roll 随 `roll_round_actions` 迁 RoundCycle——流名、开流时点、取号序逐字（先例句＝「fx_reveal 封闭流随件迁移取号序不变」同款）；encounter/gp_drop/board_gen/variant_place/fx_reveal 五流留原地零触碰；零 `randomize()`/自建随机。
- 🔴 **信号顺序契约冻结**：五信号（step_row/battle_finished/round_started/board_changed/settlement_snapshot）留宿主；发射语句零迁移、发射时序零变化；A2 三 connect（:251-254）逐字。
- 🔴 **两快照出口签名与载荷逐字不变**：presentation_snapshot/diagnostic_snapshot 字段名、嵌套结构、值口径逐字——内部读数改指两件投影后值恒等（round_index/attune_safe_seen/完美三账/hero_atk 派生读均受理后不变量）。
- 🔴 **明细行协议词表零触碰**：基础 9 类＋扩展行词表、SOURCE_EXEMPT_TYPES/SOURCE_EXEMPT_CLASSES 两常量、`_emit_row`/`_assert_row_source` 行发射基建留宿主零迁移。
- 🔴 **行为零变化承载（对拍闸退役后）**：同种子逐位一致由关联套件的既有回放断言与两快照恒等断言承载；对拍闸（原闸 11）已随 2026-10-30 工程批退役，无闸级对拍批准事项。
- 🔴 **拆分边界纪律**（判据权威＝code-conventions §1.1，此处立卡内执行条款）：①每个拆出单元须有可陈述的职责语句与单一变化原因（实现报告逐件一行承载）；②拆出单元须有集体身份——命不出名字、只能说「剩下的成员」的打包＝凑计数袋，禁；③「过阈值」只许作为发现信号，作为拆分或收拢的动机即违规；④按纪律拆不出内聚单元 → 停卡呈报走豁免/还债通道，禁硬拆凑绿；⑤拆分沿职责轴不沿阈值轴。两新件职责语句见第 8 节（RoundCycle＝轮结算周期的推进结构；BattleFacts＝战斗事实的记录与查询口径）。
- 🔴 **禁为机检文本保留无效成员**：22 成员随件迁出＋treasure_inventory／_hero_atk 两成员退役＝宿主删 24 项（37−22−2＋RoundCycle/BattleFacts 两新件接线引用＝宿主 15，账平——grilling 复核订正原算术），禁保留别名、别名转发属性或空壳；机检键与卡片契约互斥时，实现段一律停卡呈报，不得自造第三条路。
- 🔴 **随迁键收敛义务**：迁移函数逐字纪律——`roll_round_actions`（45 行/分支≈8 贴线）、`settle_if_due`、`reset_round`、三 mark 方法迁移与改指**禁顺手增分支/局部**；函数迁入新文件若出超标键＝卡内同步收敛（拆助手函数，拆分不改语义；先例＝迭代 40 卡① 12 随迁键收敛），禁带新键进批末闸。
- 🔴 **段类接线改形守 Middle Man 禁壳**：段类对宿主的直调形态不变（段类经宿主引用直调，现状形态）；段内改指一律调用点改指（`oc._X` → `oc._facts.X`／`reward_grant.treasure_inventory`），宿主与新件禁留转发壳。
- 🔴 **_fatal 与 battle_result 状态机唯一写点留宿主**：RoundCycle/段类经 oc 直调 fatal 面零改形；BoardInstaller（迭代 42 建件）fatal Callable 零触碰。
- 🔴 **BattleFacts 成员冻结**：15/15 贴顶——实现期禁增员，增员即停卡；扩容阀＝下一张要加事实成员的卡先把封印判定账五成员二次拆出（SealLedger，−5）再落新账，禁硬挤。
- 🔴 **reset_round 复位边界**：只清 reveals/seals/path 三项、**不碰 refresh_used**——_battle_over 后快照读到的 refresh_used 必须保持末轮值（设计文档 §8.5 险点，对照表 V2 行断言钉住）。
## 5. 范围边界
做什么：设计文档 §2 逐成员去向表的全部迁移与改址、两新件建件、treasure_inventory 改址、_hero_atk 派生读、随迁键收敛、S7/S8 静态扫描随动、对照表新增断言四条。
不做什么：
- 轴丙 BoardInstaller 建件——迭代 42 在册卡执行，本卡前置、不重复。
- 五段段类职责与段序语义零改写（只改指）；`_exit_distribution` 留宿主（设计文档 §6.5 已否决迁驱动件——判定段直调宿主，零新引用环）。
- attune 行为函数留宿主（attune_has/attune_param_sum/attune_convert_state/积点自动兑付体/充能重置零迁——设计文档 §5 重裁决）；AttuneLoadout 零触碰。
- nest_preview_count 冻结面、round_index 公有直读面、A2 三事件订阅面——零变化。
- 数值表、RNG 流词表、信号载荷 schema、明细行词表——零触碰；本批零数值改动，MC 零跑（第 13 节）。
- `game/tests/README.md`、`design/` 全目录、根规则文件——实现批禁写（反哺点通道，第 6 节）。
- 效果发射端口定形与 reward_economy 分件——归接收方条目其余子项，另行设计讨论。
## 6. 关联文档同步面
| 文档 | 关联点（本批实现会改变它的哪条陈述） | 同步义务 |
|---|---|---|
| design/engineering/architecture/architecture.md | 轴丁两行与功能层 RoundCycle/BattleFacts 行——设计已闭合落文 v1.25，实现照册施工；「测试与质量域」S13 豁免第三条注销句已预写注销（本批键账达成即生效，未达成＝停卡非落文）；两行「构造＝引用束注入」句与本卡三参直构/零参直构实态的口径差；批末成员数/行数/公开方法数实测值与在册数字出入 | 设计权威文档——实现批禁直改；出入逐条列进 `reports/iter<N>-反哺点-<日期>.md`，用户裁决后归文档批落文 |
| game/tests/README.md | 本批零新增能力、零入口与代表用例名变更（测试改指只动成员寻址；新增断言四条全部内嵌既有函数）；能力清单零增删改 | 机械面文档——实现批禁写；批末收尾核对表上名字与实际落地一致（改名则回表） |
| design/gdd/systems/（全树） | 无关联文档——结构整改不改游戏规则与玩家可见行为 | 无修订预期；若实现中发现契约句被触碰，停卡呈报走反哺点通道 |
## 7. 卡前文件结构图
| 文件 | 职责 | 改动性质 |
|---|---|---|
| game/core/battle_facts.gd | 战斗事实件（新增，architecture v1.25 功能层在册）——受理事实/轮 facts 缓冲/封印判定账/溯源/条件计数/同调快照，自带轮复位与完美账写口 | 新增（非行为改动——成员迁移；验收=对照表 V1/V2/V6 行） |
| game/core/settlement/round_cycle.gd | 轮循环驱动件（新增，同在册）——五段段件持有与段序执行、结算重入门闸、开轮摇号、踩雷计数账 | 新增（非行为改动；验收=V1/V3 行） |
| game/core/battle_orchestrator.gd | 战斗结算编排中枢——宿主 15 成员定着、行发射基建、状态机、两快照出口、attune 行为读数与触发面 | 修改（非行为改动——成员改指、三函数迁出、派生读、注入改址；验收=V0–V5 行） |
| game/core/settlement/grant_segment.gd | 授予段——事实族改指约 23 处＋完美三处直写改经三 mark 方法 | 修改（非行为改动） |
| game/core/settlement/combat_segment.gd | 战斗段——2 处改指（oc._facts_reveals 扫描、oc._hero_atk 派生调） | 修改（非行为改动） |
| game/core/level_runner.gd | 关卡域生命周期——库存注入 1 行改经 `reward_grant()` 出口直注 | 修改（非行为改动——注入路径改址，注入时序与消费面零变化；验收=V5） |
| game/tests/static_scan.sh | 静态扫描域承载——S7 B1 域文件集与 S8 await 文件集增行 round_cycle.gd | 修改（工程随动，architecture 拆件定稿节 S7/S8 随动条在册） |
| game/tests/unit/battle_settlement/seal_polarity_test.gd · unit/core/feat_vouchers_test.gd · unit/battle_settlement/trigger_cond_test.gd · unit/battle_settlement/round_flow_skill_pool_test.gd · unit/core/settle_segments_test.gd · unit/core/treasure_effects_test.gd · unit/core/adventure_feats_test.gd · unit/core/meta_progression_forge_test.gd · unit/battle_settlement/roll_multiplier_test.gd | 成员寻址改指（断言条件与期望值零变化）＋新增断言内嵌既有函数（V1/V2/V4/V5） | 修改（改指＝非行为改动；新增断言行=对照表对应行） |
aura/decay/verdict 三段、battle_fx_host、reward_grant、damage_controller、main.gd、treasure_interact_controller、board_installer——零改动（设计文档 §11 盘点）。新增件「为什么不能复用」理由与唯一落点核查见第 8 节；对不上即卡片不成立。
## 8. 落位与可复用性预检
- **battle_facts.gd（新增）**：复用面核查——战斗事实记录面现行只摊在 battle_orchestrator 成员区（全仓 grep 同名与同义标识符：`_facts_reveals`/`_seal_consumed`/`_perfect_*` 等无第二实现），无既有件可复用。不能并入 BattleFxHost（效果引擎宿主域——变化原因是效果发射与施加，不是事实记录）、不能并入 RewardGrant（授予管线域——事实账不是授予物）、不能并入五段段类（段类只搬运时序零持有账——缓冲写读跨段跨界，归宿主编排面）、不能并入 AttuneLoadout（营地/冒险域充能物化单源，迭代 39 已闭合契约——重开已闭合边界＝设计文档 §5 理由 4 否决）。落点唯一：`game/core/battle_facts.gd`。分层：core 层 RefCounted，零注入引用、零信号、零协作对象调用——纯数据＋谓词＋写口；身份快照捕获（query_full_snapshot）留宿主 `_on_cell_revealed`，防它变成第二编排面。
- **round_cycle.gd（新增）**：复用面核查——轮结算周期推进机构（段件持有/重入闸/摇号/踩雷账）现行只存在于宿主三函数＋五成员，无第二实现。不能并入 BattleFxHost/RewardGrant（变化原因不同，同上）、不能并入任一段类（它是段件的序主人——持段件者不能是被持者）。落点唯一：`game/core/settlement/round_cycle.gd`（与五段段件同目录）。分层：core 层 RefCounted、零 await；随机只经 `oc.rng` 的 behavior_roll 封闭流。
- **引用束注入构成**：引用束先例（BattleFxHost/RewardGrant 的字典束）防的是 `_init` max-parameters 新键——本批两新件参数均未触发：RoundCycle `_init(host, fx_host, reward_grant)` 三参直构（fx_host/reward_grant 仅作段构造透传，不落成员）；BattleFacts 零参直构。architecture 两行「构造＝引用束注入」句按设计文档 §3/§4 实态执行（三参直构无需束），出入随反哺点申报。
- **依赖方向**：宿主→两新件单向（宿主 `_init` 建件并接线，每战新建同灭）；RoundCycle 持 `oc`＝五段段类既定同款形态（段类已持宿主引用直调——非新增反向引用），除 `oc` 外禁持宿主其他成员、禁回调宿主私有族；BattleFacts 不持任何对象引用——宿主与段类经注入引用直读写（fx_host._fx_bonus_delta 跨件直读写同款现状形态）。新件之间零互引。
- **新增函数**：宿主 `_hero_atk()` 派生读＝`_journal()`「读面即引用、无第二账」同款先例（encounter 受理后只读，派生值恒等）；`reset_round`＝原 `_reset_round_facts` 逐字；三 mark 方法＝新写口（升级采纳案）。零新增数据件、零新增常量表。
## 9. 实现规范预算（新件对照 gdstyle 默认阈值；写码前对账，超预算面=停卡退回写卡段）
| 新件 | 公开方法 ≤20 | 类变量 ≤15 | 迁移函数对账（基线源函数键） |
|---|---|---|---|
| battle_facts.gd | 预算 4（reset_round＋mark 三方法；设计文档 §10 表载 5 属含 `_init` 宽口径计数差，两口径均 ≤20 零键风险） | 15（贴顶——实现期禁增员，增员即停卡；扩容阀＝SealLedger 二次拆出） | `reset_round`＝原 `_reset_round_facts` 逐字（基线无其函数级键）；三 mark 新增小函数远在阈值内 |
| round_cycle.gd | 预算 3（settle_if_due/roll_round_actions/is_settling） | 8（oc＋五段段件＋_settling＋mines_hits） | `settle_if_due`＝`_maybe_settle`＋`_settle` 合体（两源函数基线零键；闸序与段序逐字）；`roll_round_actions` 45 行/分支≈8 贴线——迁移禁增分支/局部，确需增条件即停手核对 gdstyle；`is_settling` 新增小函数 |
存量触面一查：battle_orchestrator 类变量 37（轴丙后实测）→15 只降、文件长约 890→约 830 只降（均阈值内，S13 键较登记值只降不升——达成手段＝本卡迁移，无豁免申报）；grant_segment/combat_segment 改指零新增键（`_judge_seal` 等函数体只换成员寻址）；level_runner 改 1 行零新增键。两新件与改址后宿主、段类落地后先跑 `python tools/gdstyle_gate.py` 预检一次再进批末闸（T4 步骤）。`_init` 形态：RoundCycle 三参/BattleFacts 零参（max-parameters 阈值 5 未触发）。新增文件全类型标注（S9——容器参数化走 `Dictionary[Variant, Variant]` 现行口径）；头注按 code-conventions §1.4.1（职责语句＋封闭面声明，禁变更叙事、禁文档反链）。
## 10. 任务卡 T0..T4（估时为区间；工作量限制只属迭代层）
**T0 重测对账（0.25–0.5 工作日）**（前置：迭代 42 合回——BoardInstaller 在库；产出：逐成员对账结论与改址点名清单，后续各卡取用）
- [ ] 以当轮 master 重测 battle_orchestrator.gd 类变量逐名清单，对账设计文档 §2 表五去向（留宿主/RoundCycle/BattleFacts/退役改址/派生读；轴丙后实态 37 项，`_board_generator` 行应已消失）——对不上即停卡呈报
- [ ] 复核 gdstyle 基线：battle_orchestrator 函数级键数（预期零——漂移即停卡呈报）；类变量键现值与文件长键现状（应已随轴丙归绿或基线已 refresh）
- [ ] 复核第 3/7/9 节全部 file:line 引用与设计文档 §11 改址盘点实数（grant_segment 约 23–25 处、测试各套件逐处点名——含 settle_segments_test:27 补入项）；漂移处就地改卡并记录
**T1 BattleFacts 建件与事实成员迁移（0.75–1 工作日）**（取用：T0 对账清单；产出：`_facts` 在座、事实族 15 成员归件——T2/T3 引用其成员名）
- [ ] 建 `game/core/battle_facts.gd`：class_name BattleFacts，extends RefCounted；15 类变量初值逐字承原宿主声明（encounter/reveals/seals/path/refresh_used/board_seq/board_from_midround/seal_consumed/seal_miss_seen/perfect_hit_true/perfect_hit_false/perfect_forgiven/feat_first_dig_used/attunement/attune_safe_seen）；公开方法 4：`reset_round()`（原 `_reset_round_facts` 逐字——只清 reveals/seals/path 三项，不碰 refresh_used）、`mark_perfect_hit()`、`mark_perfect_miss()`、`mark_perfect_forgiven()`；头注写职责语句＋成员封闭面＋零注入零信号零协作调用
- [ ] 宿主 `_init` 建 `_facts = BattleFacts.new()`；事实族成员全量改指：宿主声明删 15 项、读写点改 `_facts.X`（encounter 全部读点——_journal/_attune_loadout/_fx_host_fact/受理段/fx_state/两快照/gp_drop，按 T0 点名清单逐处；缓冲追加/复位/装板清零/perfect 谓词同批）；`_reset_round_facts` 函数删除，三调用点改调 `_facts.reset_round()`（时序位置逐字）
- [ ] grant_segment 事实族改指（`oc._facts_reveals/_facts_seals/_facts_path/_seal_consumed/_seal_miss_seen/_feat_first_dig_used/_perfect_*` → `oc._facts.X`）；完美三处直写改经三 mark 方法（:311/:379/:394——写口升级采纳案；:397 forgiven 读数直读 `_facts.perfect_forgiven` 零变化）
- [ ] 测试改指：seal_polarity_test 8 处（_perfect 直写→_facts.perfect_*）、feat_vouchers_test facts 族、treasure_effects_test:309（ob14.attunement→ob14._facts.attunement）、adventure_feats_test 1 处（encounter 读→_facts.encounter）——断言条件与期望值零变化
- [ ] 新增断言 round_flow_skill_pool_test.gd:_smoke_full_battle 内嵌〔编排归约 V2〕：终局后 `presentation_snapshot()["refresh_used"]` 等于末轮结算 snapshot 的 economy.refresh_used（复位边界险点，规格见对照表）
- [ ] 孤立验证：`godot --headless --script res://tests/run_all.gd -- --only=seal_polarity,feat_vouchers,treasure_effects,adventure_feats,table_structure_guard,round_flow_skill_pool,variant_placement` 全绿＋`python tools/run_smoke.py`（出红只跑红件最小单元）
**T2 RoundCycle 建件与段驱动迁移（0.75–1 工作日）**（取用：T1 的 `_facts`；产出：`_rounds` 在座、段驱动三入口——T3 引用其方法名）
- [ ] 建 `game/core/settlement/round_cycle.gd`：class_name RoundCycle，extends RefCounted；类变量 8（oc/mines_hits 公有＋_grant_seg/_aura_seg/_combat_seg/_decay_seg/_verdict_seg/_settling 私有）；`_init(host, fx_host_ref, reward_grant_ref)` 三参——五段构造五行从宿主 `_init` 逐字搬入（构造参数与持有形态不变）；公开方法 3：`settle_if_due()`（原 `_maybe_settle` 三闸＋`_settle` 段序体合体——闸序 settling→battle_result→phase 逐字，终局早退不回置 _settling）、`roll_round_actions()`（原函数逐字迁入——behavior_roll 流名/开流时点/取号序逐字，宿主引用经 oc 改指，禁增分支/局部）、`is_settling()`；头注写职责语句与单一变化原因
- [ ] 宿主 `_init`：五段构造五行迁出，改 `_rounds = RoundCycle.new(self, _fx_host, _reward_grant)`（置于两件建齐与 bind 接线之后——构造序禁环不变）；五段成员声明删除；`_maybe_settle`/`_settle`/`_roll_round_actions` 三函数删除
- [ ] 宿主调用点改址：`_on_round_end` 末行→`_rounds.settle_if_due()`；begin_battle 与 `_exit_distribution` 的 `_roll_round_actions()`→`_rounds.roll_round_actions()`；diagnostic_snapshot settling 读→`_rounds.is_settling()`；`_begin_battle_fx_state` 踩雷清零→`_rounds.mines_hits = {"total": 0, "last": 0, "round": 0}`（赋值复位——语句时点逐字）；`_book_negative_blast` 两写→`_rounds.mines_hits`
- [ ] 测试改指：trigger_cond_test :119/:126/:131（orch._mines_hits→orch._rounds.mines_hits）；settle_segments_test :27（→oc._rounds._grant_seg）；round_flow_skill_pool_test:1022 与 feat_vouchers_test 5 处（_grant_seg→_rounds._grant_seg）
- [ ] 新增断言 settle_segments_test.gd（接线检查段内嵌）〔编排归约 V1〕：oc._rounds 非空且 `_rounds.oc == oc`、五段段件齐在 _rounds、oc._facts 非空（规格见对照表）
- [ ] `game/tests/static_scan.sh` S8_FILES（:317）与 S7_B1_SET（:359）增行 `game/core/settlement/round_cycle.gd`（battle_facts.gd 零协作调用不入两清单）
- [ ] 孤立验证：`-- --only=round_flow_skill_pool,settle_segments,trigger_cond,seal_polarity,skill_unlock,roll_multiplier,variant_placement` 全绿＋冒烟
**T3 宿主改形收束（0.5–0.75 工作日）**（取用：T1/T2 两件与成员名；产出：宿主 15 成员定着）
- [ ] 宿主 `_rounds`/`_facts` 成员声明落位；已迁成员声明复核清零——类变量实测 15（第 3 节名单），禁无效成员
- [ ] treasure_inventory 改址：宿主成员与 setter 转发块（:48-52）删除；四处读改指 `_reward_grant.treasure_inventory`（_hook_attune_consume/_reseed_attune_charges/装板薄壳叠加层退役/_battle_over 叠加层退役）；`level_runner.gd:520` 改 `_settlement.reward_grant().treasure_inventory = treasure_inventory`（注入时序在宿主构造之后不变）
- [ ] _hero_atk 派生读：宿主新增私有函数 `_hero_atk() -> int`（返回 `int(_facts.encounter.get("hero_atk", int(db.combat.hero.atk)))`）；受理段写入与 spawn override 改调；`combat_segment.gd:56` oc._hero_atk→oc._hero_atk()；_hero_atk 成员删除
- [ ] attune 读数出口核验：attune_has/attune_param_sum/attune_convert_state/_attune_charge_safe_row/_attune_safe_seen_read 读源改 `_facts.attunement`/`_facts.attune_safe_seen`——三个外部消费面（main.gd:567、treasure_interact_controller.gd:125、table_structure_guard_test/breakpoint_resume_test 起战断言）零改址零触碰
- [ ] 新增断言 roll_multiplier_test〔编排归约 V4〕与 treasure_effects_test〔编排归约 V5〕（规格见对照表）
- [ ] 孤立验证：`-- --only=roll_multiplier,treasure_effects,breakpoint_resume,level_shop_economy,round_flow_skill_pool` 全绿＋`python tools/run_system_test.py`
**T4 键账对账与收口（0.25–0.5 工作日）**（取用：T0–T3 全部产出；产出：本批交付物）
- [ ] `python tools/gdstyle_gate.py` 预检一次——宿主类变量 15、round_cycle 8、battle_facts 15、文件长 ≤1000（预期约 830）、零基线外新键；出超标键→按第 4 节随迁键收敛义务卡内拆助手后复检
- [ ] 里程碑步出口跑全套闸：`bash tools/run_all_gates.sh --code` 全绿（改动全为代码面）；闸 11 PARITY 触面按第 4 节条款——实跑对拍须用户批准发起、不得借机重锚，NEED-APPROVAL 时停步呈用户裁决
- [ ] 键账对账：第 9 节预期逐键核；基线 refresh 由用户发令人工 `python tools/gdstyle_gate.py --refresh`（须 --force——全基线 16 键消失 ≥2 条触发骤降守卫；与姊妹卡同批编队时一次 refresh 合并执行）
- [ ] 产出物落位卡：`reports/iter<N>-实现报告-<日期>.md`（各卡状态＋实机目检总清单＋实现决定记录＋逐拆出单元职责语句一行）与 `reports/iter<N>-反哺点-<日期>.md`（第 6 节同步面逐条落点）写齐方算收口
合计估时约 2.5–3.75 工作日（设计文档 §12 载 2–3 日；上探余量＝测试改址逐处点名与 PARITY 批跑配合；PARITY 实跑须用户在场批准，不占卡估时）。切分预案：T1/T2 迁移函数出超标键需卡内拆助手时，超软盒预挂改由 T3 并 T4 吸收。
## 11. 验证闸——改动—验收对照表
域口径：本批改动全为 `game/` 下非 .md 行为载体——批末跑代码域闸（`tools/run_all_gates.sh --code`）；里程碑步（T 段）出口跑一次全套闸，波内修复只做出红最小单元的最窄确认，新增测试先行孤立验证再并入全套。测试执行两入口铁规不破。三件保险（冒烟/系统测试/静态扫描）恒跑；02 单元与集成按关联档选套件（上表落点套件并集）。能力清单：本批零新增能力、零入口与代表用例名变更——能力行全部为既有名，零增删改（第 6 节）。**静态判据申报（不入对照表）**：键账收敛与静态随动（宿主 38→15、round_cycle 8/battle_facts 15、零基线外新键、static_scan.sh S7/S8 两清单增行）无运行时可观测提交面——判据＝`python tools/gdstyle_gate.py` 与 `game/tests/static_scan.sh` 退出码（T4 执行），属静态判据＋评审注记申报观测面局限（test-conventions §8.4 出口）。
| 行 | 需求点 | 改动（文件:行/行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|---|---|---|---|---|---|---|---|
| V0 | 行为零变化（本批总判据） | 全部结构改动（第 7 节清单） | 关联套件零改址应绿（对拍闸已随 2026-10-30 工程批退役——总判据由 V1–V5 各行能力行并集承载）；静态判据申报同上（键账收敛与 S7/S8 两清单增行） | 集成 | 真实局 begin_battle→挖掘→结算→终局 | 关联套件全绿且改址面零失败——出红且无改址归因即停机呈报 | 既有：轮内流与结算五段全序；既有：技能池数据面与回放独立；既有：伤害公式与掷点乘区；既有：秘宝结构冻结与 12 件效果 |
| V1 | 两新件建件接线（T1/T2） | battle_facts.gd/round_cycle.gd 新建；宿主 _init 建件接线；五段构造迁 round_cycle | 新增 settle_segments_test.gd 接线检查段内嵌〔编排归约 V1〕：`oc._rounds` 非空且 `_rounds.oc == oc`；五段段件齐在 `_rounds`；`oc._facts` 非空 | 单元 | BattleOrchestrator 直构（settle_segments_test 现行夹具同款） | 编排器接线面（新件在座与宿主回指——接线断言本体） | 既有：轮内流与结算五段全序 |
| V2 | reset_round 复位边界（险点） | battle_facts.reset_round 只清三缓冲；宿主三调用点改调 | 新增 round_flow_skill_pool_test.gd:_smoke_full_battle 内嵌〔编排归约 V2〕：终局后 `presentation_snapshot()["refresh_used"]` == 末轮结算 snapshot `economy.refresh_used` | 单元 | begin_battle→轮内刷新→停手→结算→终局 | 两快照同键值恒等（复位不碰 refresh_used 的可观测提交面） | 既有：轮内流与结算五段全序；既有：停手转存储备与轮内刷新（上限／AP 不重置／刷新图零清图奖励） |
| V3 | 段驱动与摇号迁移（重入门闸/settle_if_due/roll_round_actions/mines_hits 账） | 三函数迁出宿主；宿主调用点改址；trigger_cond_test 3 处改指 | 复用 round_flow_skill_pool_test 全套（_smoke_full_battle/_smoke_settlement_segments/_smoke_skill_pool_replay_independence）、settle_segments_test V4-3 真实一轮、skill_unlock_test、trigger_cond_test（改指后应绿）——零新增断言 | 单元 | begin_battle；stop→WAITING→settle_if_due | 五段裁定行序＋settling 闸＋终局早退＋同种子摇定逐位（behavior_roll 流随件零漂移由既有回放断言钉住）＋mines_hits 转存读数 | 既有：轮内流与结算五段全序；既有：技能池数据面与回放独立；既有：Boss 半血解锁技门控 |
| V4 | _hero_atk 派生读 | 成员删→私有函数；combat_segment.gd:56 改调 | 新增 roll_multiplier_test.gd（既有主角攻击链函数内嵌）〔编排归约 V4〕：enc 携 `hero_atk` override 起战→主角攻击单 base_value==override；缺省→base_value==hero 表值 | 单元 | begin_battle(enc)→战斗段主角先手 | 主角攻击单基值（受理后派生值恒等的判据本体） | 既有：伤害公式与掷点乘区 |
| V5 | treasure_inventory 注入改址 | level_runner.gd:520 改经 reward_grant() 出口；宿主四处读改指；宿主 setter 转发块删 | 新增 treasure_effects_test.gd（秘宝使用链内嵌）〔编排归约 V5〕：注入后 `current_battle().reward_grant().treasure_inventory` 与关卡库存同一引用，且 use_treasure 受理走通 | 单元 | LevelRunner 建战注入→use_treasure 四步 | 注入引用同一性＋受理面走通（改址后消费面不断链） | 既有：秘宝结构冻结与 12 件效果 |
| V6 | 封印判定账/装板溯源/受理事实迁移（完美写口升级、attune 状态随件） | 事实族改指（grant_segment 约 23 处＋测试）；三 mark 写口；attune 读源改 _facts | 复用 seal_polarity_test 全套、feat_vouchers_test（契约 2 计数纯净 R2）、variant_placement_test、meta_progression_forge_test、adventure_feats_test、table_structure_guard_test（attune 面零改址应绿——本批最硬的外部面零变化证）——零新增断言 | 单元 | 封印动作→结算；begin/refresh/exit 装板；begin_battle(enc) | 完美三账读数＋去重闸＋契约 2 计数纯净；刷新图零清图奖励＋board_seq；enc 携带键贯通；attune_has/param_sum/convert_state 外部面零变化 | 既有：封印与极性路由／不可逆；既有：清图奖励双份与零路径；既有：变异布置门控；既有：专长（奇物）授予与凭证保底；既有：元进度入账与锻造两轴；既有：装板与开局免费展开（封锁格无资源、计入清图） |
反向核对：diff 中每个行为载体改动均有行——本批申报**行为改动零条**（全部为非行为改动：成员迁移与调用点改指，判断依据＝V0 同种子逐位一致证明＋既有断言面零改址应绿；完美写口升级＝同一时点同一增量改经方法单点，语义逐字）。新增断言四条（V1/V2/V4/V5）全部挂行；孤儿断言零条。测试削弱申报见第 15 节。
## 12. 基线纪律（S13 键账）
1. 本卡键账目标＝battle_orchestrator 类变量键归绿（实测 15 后随 refresh 消失）；文件长键已由轴丙（迭代 42）归绿，本卡保持文件长 ≤1000（预期约 830）。
2. 禁为过闸 refresh 换绿：基线重生成只由用户发令，批末键账对账后人工 `python tools/gdstyle_gate.py --refresh` 一次执行（禁闸内自动重生成、禁实现批中途 refresh）。
3. 重锚守卫：新基线键数较旧基线少逾 10% 须 `--force` 显式确认——本批与轴丙预期合计消失 ≥2 条（16 键基线），须带 `--force` 由用户执行。
4. 还债＝数值下降自然绿：迁移后同键数值下降不判红；出现恶化（同键数值较登记值上升、基线外新键）＝停卡呈报，禁自行消化。
5. S13 豁免第三条（battle_orchestrator max-class-variables，architecture v1.25 已预写注销句）随本批达成生效——未达成＝停卡呈报，非落文事项。
## 13. MC／数值与 RNG 零触碰声明
本批零数值改动、零数据表改动、零 RNG 流词表改动、零玩法字面量引入——结构整改不改数值与 RNG 消费序。behavior_roll 封闭流随件迁移取号序不变（流名、开流时点、取号序逐字）。数值与 RNG 零触碰则 MC 零跑；对拍闸已随 2026-10-30 工程批退役，无闸级对拍事项。
## 14. 异常分级
- **L1 自救**：改指漏改编译错、测试寻址漏改——就地修复重跑最窄确认。
- **L2 记录继续**：实测行数/改指处数与设计文档「约」值区间偏离、头注指址微调——记入实现报告「实现决定记录」。
- **L3 停机写报告等用户**：①机检预算互斥——两新件实数超第 9 节预算、BattleFacts 需增员、或迁移函数现出超标键＝上游缺陷停卡退回写卡段（禁自造第三条路）；②encounter 归属被实现期证伪——受理事实与轮 facts 复位节奏冲突实锤、且设计文档 §6.3 两条砍路均破冻结面（宿主 16 不可达）＝停卡呈报走判据④通道；③T0 对账不符（成员去向对不上、基线出现函数级键、file:line 漂移过大）；④V0 行为零变化被证伪（关联套件出红且无改址归因）；⑤断言面被下游兜底吸收致判据绑不上（按 test-conventions §8.4 出口呈报）；⑥S13 键恶化或基线外新键。
## 15. 测试削弱申报（允许改动的旧断言及理由）
零申报——本批不删任何断言、不改判据阈值、不缩扫描面、不把真实入口换成下层直调；测试改指只动成员寻址（断言条件与期望值零变化）；新增断言四条（V1/V2/V4/V5，全部内嵌既有函数）。未申报的削弱由独立验收审计判红。
## 16. 独立验收审计
合并前由未参与实现的会话或子代理执行；报告落 `reports/iter<N>-验收审计-<日期>.md`。审计至少做四件事（test-conventions §8.7）：逐行核对第 11 节对照表（测试存在、真执行、尾缀可 grep、真实入口未绕过改动点）；抽查判据绑定面（V2 两快照同键、V4 攻击单基值、V5 引用同一性——当轮真实跑批执行过）；检查测试削弱（对照第 15 节零申报）；核对全部「非行为改动」判定依据（零漂移证明是否在当轮真实跑批中成立）。未过不得合并。
## 17. 代拍板白名单（允许 agent 自行拍板的微决策）
1. 迁移函数与改指处头注/行注的指址微调（词表与语义不动——「指址须真」纪律）。
2. 调用面改指的机械改写（排版、注释同步、行内换行）。
3. 断言失败消息尾缀编号分配与措辞（〔编排归约 Vn〕系列）。
4. 新件私有成员与小函数命名微调（职责语义不变、公有面契约名逐字不动）。
5. 宿主 _init 内两新件建件语句的次序微调（约束不变：_facts 无依赖先建、_rounds 在两件建齐与 bind 接线之后）。
超清单决策记入实现报告「实现决定记录」节。
## 18. 待裁点
零待裁点——五项待裁点（设计文档 §13）已由用户 2026-10-29 全裁闭合（第 2 节裁决记录），完美账写口升级已按推荐案采纳落卡。**零待裁点，开工门=U0**。编队前置：迭代 42（gdstyle 尾波清偿批，含轴丙 BoardInstaller）合回之后开工；T0 按当轮 master 重测对账。
reports/需求卡片-测速循环批-2026-10-29.md
-195
View File
@@ -1,195 +0,0 @@
# 需求卡片——测速循环批（tune_sim_controller 循环内 await 真实消除）
> **版本状态**：v1.1 定稿——零待裁点（2026-10-30 停卡重裁：实现段 T0 三重证据定谳 v1.0 的「潜伏红」前提已被迭代 41 测试债批消化〔215da315——运行态收尾归还 run〕，按停卡呈报建议案剥离已申报行为改动 V3、T0 义务改现状复核、夹具申报差异两处减一处；2026-10-29 原四点裁决中②作废，①③④仍有效——裁决记录见第 15 节）。
> **接收方**：待办清单条目「零豁免五键清偿批——S13 余量五键真修四卡（2026-10-29 登记，来源=会话提及）」——本卡为其四卡中的测速循环批卡。
> **来源**：reports/设计-测速循环去await-2026-10-29.md（2026-10-29 设计闭合；§2.3 潜伏红推演与 §10 待裁点 1 的「还原」申报已随停卡重裁作废，§3–§7 形态与等价性论证仍有效）。**唯一事实源**：`reports/设计-测速循环去await-2026-10-29.md` ＋ `design/engineering/architecture/architecture.md` v1.25「测试与质量域」S13 测量面豁免注销句（2026-10-29 零豁免裁：原循环内 `await` 豁免〔2026-10-27〕注销——tune_sim_controller 改 process_frame 信号常驻连接＋步进状态机，每帧一局、帧相位逐点对齐；注销对象是 await 豁免、不依赖行为改动申报，句保持；句内「随批申报行为改动一处」半句已失效，随实现批现状化时一并修正——见第 6 节）＋ 停卡呈报三重证据（iter44 worktree 分支 `reports/iter44-实现报告-2026-10-30.md` §5——重裁依据）。
## 1. 目标与完成定义
这批做什么：把 S13 静态质量闸（gdstyle）在册裸键 `game/presentation/tune_sim_controller.gd|quality/await-in-loop` 真实消除——`run(n)` 的 for 循环内 `await process_frame` 改为 process_frame 信号常驻连接＋步进状态机（每帧回调执行一局、步尽次帧收尾断连），`run()` 只留函数级一次 `await _batch_finished` 保持协程身份；改后全文件零 for/while，该键从文本形态根除、此文件对这个键结构性免疫。随批执行一项已裁事项：新增双实现对拍套件，把帧相位等价论证变成当轮真实执行证据。**本批零行为改动**——收尾置假已在 run() 尾每批一次执行（迭代 41 测试债批 215da315 归还后的现行形态），本批收尾四语句同帧同相位迁入 `_finish_batch()`，语句集与语义零变化（第 3、4 节）。
什么状态算完：
1. `tune_sim_controller.gd` 全文件零循环、`await` 仅 `run()` 函数级一处；`python tools/gdstyle_gate.py` 对账该裸键消失（消失键不参与红判定）、无基线外新键。
2. 测量语义逐点等价（第 4 节四判据）经双实现对拍在当轮真实跑批中证明——五面对拍全等；wd8 三断言与 ui_tune_probe ⑤ 零改动保持绿。
3. diff 中行为改动零处——收尾四语句迁移为非行为改动（同帧同相位、语义零变化，对照表 V3 行），无任何行为漂移。
4. 脚本错误中断路径差异作为声明缺口写入实现报告（禁静默）。
5. 批末代码域闸全绿；实现报告与反哺点清单写齐方算收口。
## 2. 设计事实源
设计依据唯一出处＝`reports/设计-测速循环去await-2026-10-29.md`（2026-10-29 设计闭合，零待裁点）：§3 形态评估（process_frame 信号步进状态机采纳）、§4 推荐案（伪代码结构）、§5 等价性证明清单（四判据＋已声明缺口）、§6 键账预期——以上各节不受前提消化影响、仍是本卡依据；该文档 §2.3 潜伏红推演与 §10 待裁点 1「还原」申报已作废（前提消化证据见停卡呈报）。架构面凭据＝`design/engineering/architecture/architecture.md` v1.25「测试与质量域」S13 测量面豁免注销句（2026-10-29 零豁免裁落文）——豁免注销句保持，句内行为改动申报半句随实现批现状化修正（第 6 节同步面）。前提消化与重裁凭据＝iter44 worktree 分支 `reports/iter44-实现报告-2026-10-30.md` §5 停卡呈报（git 历史证据 215da315＋T0 两面实跑绿）。待办清单条目「零豁免五键清偿批」状态=已写卡＋已编迭代 44（本卡 v1.1 重裁段产出）。
## 3. 现状事实（代码级，2026-10-30 实查；开工 T0 按当轮施工基面重锚——行号基线为本日 master）
- `game/presentation/tune_sim_controller.gd`（全件 68 行）：`run(n)` 在 :36-54——:37 置运行态真、:40-42 开共享 JSONL 日志会话、:43 `panel.set_sim_running(true)`、:44 进度 0/n、:45 建 stats 六键束、:46 取自动策略驱动、:47-50 for 循环体（`_run_one_level` → 进度串 → :50 `await panel.get_tree().process_frame`——命中键的语句）、:51-54 收尾四语句（`close_session()` :51 → 报告注入 :52 → `panel.set_sim_running(false)` :53 → `_running = false` :54）——**收尾置假在 run() 尾、for 循环外、每批恰一次**。`_run_one_level` 在 :57 注释／:58-68（5 参），尾部 :66-68 为败局节点记账（defeat 分支）——非置假。类成员 5（db／panel／_base_hp／_driver／_running）＋常量 2（:7 SEED_BASE=4200、:8 PlaytestLogger preload）；头注 4 行。
- 前提消化定谳（v1.0「静态矛盾推演」作废依据）：git 历史——迭代 41 测试债批提交 215da315（2026-10-29 合回）提交信息明载「两个产品回归随批修（……tune_sim 运行态收尾归还 run）」，收尾置假两行由该批归还 run() 尾并随该批申报；v1.0 成文（2026-10-29）与该批合回同日，其「现状考证」被上游批施工消化变质（读法 A；读法 B「考证当时即误读」与 215da315 提交信息矛盾，停卡呈报 §5 不采）。T0 实跑三重证据（iter44 worktree，停卡呈报 §5）：wd8 三断言（现位 :145-147）全 PASS（套件 18 checks 全绿）；ui_tune_probe 全链路 PASS（⑤ 守卫环 1800 帧预算内退出＋输出四串在）。**潜伏红不存在**——两面现行全绿，「零改动转绿」改「零改动保持绿」。
- 断言面一〔wd8〕`game/tests/unit/presentation/standee_fx_sweep_test.gd:139-147`：FakePanel（内类 Node，:20-40——setter 面并入树供 get_tree）＋FakeDriver（:44-55——`run_level` 回调内读 `ctrl.is_running()` 逐局记 `seen`）；:142 直构控制器（字典夹具 db）、:144 `await ctrl.run(2)`（run 必须可等待、挂起至整批完成的契约）、:145-147 三断言——`drv.seen == [true, true]`／收尾 `not ctrl.is_running() and not panel.running`／报告非空。套件在 run_all.gd manifest 在册（res://tests/unit/presentation/standee_fx_sweep_test.gd，expect 0，manifest :188）。
- 断言面二〔探针 ⑤〕`game/probe/ui_tune_probe.gd:63-83`：:65-66 设滑条与 N=10、:67 `press_simulate_for_probe()`（真实按钮 pressed 信号链）、:68-71 守卫环（`while main.ui.modals.debug_overlay.is_running()` 逐帧等——SIM_GUARD_FRAMES=1800 在 :16）、:72-73 预算内未完成判红、:74-83 输出四串断言（关卡完成率／关卡完成剩余 HP 均〔口径换代 V7〕／败北节点／N=10）。面板语义面 `debug_overlay.gd`：`set_sim_running` :81-83 → `_sync_sim_button` :107-110（模拟与两层调试两钮禁用＋「模拟中…」文案——浮窗运行态贯穿整批的可见面）、`is_running` :77-79。
- 调用面 `game/presentation/main_debug_flow.gd`：`_on_tune_simulate` :72-77——守卫（活跃结算/冒险早退）后 :77 `root._tune_sim.run(n)` **不 await 调用**（返回的协程态丢弃——新形态必须保持此调用形态可用、零改动）；`_start_debug_levels` :84 守卫读 `root._tune_sim.is_running()`（两层调试入口互查守卫）。
- 键账：`tools/gdstyle_baseline.txt:15` ＝ 该文件唯一在册键（await-in-loop 裸键，基线 16 键之一）。S13 扫描面＝产品码三目录（game/core＋data＋presentation——probe/sim/tests 不在面，`game/tests/static_scan.sh` S13 头注在案）；S8 文件集＝**十文件**显式清单（static_scan.sh :317 现行实查——不含本件）；S9/S10 扫描面同不含 game/tests/。
- 产品码 process_frame 订阅面（T0 实查项）：本件 :50（循环内 await）＋`settlement_fx_view.gd:94`（play_damage_number 内一次性 await 等文本度量——战斗结算呈现期，与模拟批不并存）。现库无「run 途中新增订阅者」场景。
- 报告渲染面 `game/presentation/hud_presenter.gd` :197-218 `tune_sim_report`（静态函数，零触碰计划）：空数组 `_mean`/`_p90` 双守卫（:221-227／:230-235）、完成率分母 `maxi(1, n)`（:206）——n=0 退化路径渲染安全（本批对拍 n=0 案的前提，实查在案）。
- 能力表现状：`game/tests/README.md` 能力表「调参测速批量模拟（逐帧步进与统计读数）」行已入表（:131——写卡段 v1.0 同批义务，真实入口＝批量模拟入口，代表用例＝对拍套件）；断言宿主 wd8 套件锚既有行「站桩敌人呈现与结算演出落点」（:130）。
## 4. 设计契约（违反即返工的红线条款，标 🔴 触碰＝L3 停机呈报）
- 🔴 **测量语义逐点等价**（设计文档 §5 四判据逐条落卡，双实现对拍为当轮执行证据）：
① 步数与帧数一一对应不变——每局恰占一帧：第 i 局恒在调用点同步段（i=0）或第 i 帧信号发射点（i≥1），收尾恒在第 n 帧发射点，n=0 退化路径两形态同为同步收尾零帧；
② 每步工作量与执行相位不变——步进体＝同一 `_run_one_level`＋同一进度语句；执行点同为 emit process_frame 帧首段（await 恢复点与 connect 回调在引擎内同处一列连接、同一 emit 内被同步调用——设计文档 §4.2 逐步对齐表）；
③ 终止条件与终止时读数不变——终止＝计数走满 n；close_session／运行态复位／报告注入在同帧执行；
④ 输出逐字不变——报告＝未触碰的 `HudPresenter.tune_sim_report`；stats 是 (种子, atk_pct, hp_pct) 的纯函数、帧时点不进测量值；JSONL 由未触碰的自动策略逐行写、close 时点同帧。
违反即返工；等价性对拍失败＝L3 停机呈报。
- 🔴 **行为改动零处（收尾语义零变化）**：收尾置假已在 run() 尾每批一次执行（:53-54，215da315 归还后的现行形态）——本批 `_run_one_level`（:58-68）零触碰、运行态复位语义零变化；收尾四语句（:51-54）迁入 `_finish_batch()` 为同帧同相位语句迁移（判据③承载——非行为改动，对照表 V3 行）。禁任何行为漂移——`_on_tune_simulate` 不加运行态早退守卫（设计文档待裁点 3 备选否决）、发布态零触碰、探针①–④⑥–⑩ 段零触碰、`HudPresenter`／`PlaytestLogger`／`sim/level_autoplay.gd`／`debug_overlay.gd` 零触碰。
- 🔴 **脚本错误中断路径差异＝声明缺口**（设计文档 §5 缺口 1，接受并文档化）：GDScript 无错误陷阱 API、差异不可消除——旧形态步进体内脚本错误＝协程死亡静默停摆（运行态永真、报告永不落）；新形态＝计数未推进、次帧重试同一步（确定性错误逐帧重试，探针 1800 帧守卫可抓；生产态＝持续重试的可见坏，与旧「静默卡死」同级不同形）。实现报告文档化义务（T3），禁静默、禁造第三条路（错误陷阱/守卫兜底均已否决）；测量批遇错本就整批作废，两形态都不产出可用读数。
- 🔴 **S8 结算路径 await 零命中面不触碰**：本件不在 S8 文件集（十文件显式清单实查不含本件）；本批零触碰 S8 文件集与一切闸件。
- 🔴 **拆分边界纪律**（判据权威＝code-conventions §1.1，卡内执行条款）：本批零拆出单元——步进状态机收编本件（职责语句与不拆理由见第 8 节）；①拆出单元须有可陈述职责语句与单一变化原因；②命不出名字、只能说「剩下的成员」的打包＝凑计数袋，禁；③「过阈值」只作发现信号——本批键消除靠形态根除、不靠拆件凑数；④按纪律拆不出内聚单元→停卡呈报；⑤禁沿阈值轴拆。
- 🔴 **RNG 与种子零触碰**：SEED_BASE=4200 与逐局种子切分（SEED_BASE+i）零变化——stats 是种子纯函数是等价性论证的前提。
- 🔴 **注释纪律**：新增头注/注释零变更叙事（「由 await 改为信号」类句禁——沿革归 git）；S11 注释禁词由术语表解析供给，新增注释用白话描述现行形态与信号契约。
## 5. 范围边界
做什么：第 3 节四件事——T0 现状复核（两面实跑应绿）、`tune_sim_controller.gd` 步进状态机改造（收尾语义零变化）、双实现对拍套件、键账对账与收口。
不做什么（明示去向）：
- 零豁免其余四键（main.gd 类变量 49、battle_orchestrator 类变量 38、board_cell_unit 30、standee_body 19）——各归组合根注册面批／战斗编排归约批／呈现层状态件批（同条目四卡，待办清单在册）。
- `tools/gdstyle_baseline.txt` 禁实现批中途刷新——批末由用户人工重生成（第 6 节）。
- `_on_tune_simulate` 运行态早退守卫——不收件（+1 行为面、system_test 前置断言随之需复核，代价大于收益，设计文档待裁点 3 否决）。
- `design/` 整个目录、两份根流程清单——实现批禁写；该改的点列反哺点清单。`game/tests/README.md`：测量面专属能力行已随本卡 v1.0 写卡段同批入表（「调参测速批量模拟」行），实现批禁写红线不变。
- 探针其余段与套件其余断言族（standee_fx_sweep 的 wd2/wd4/wd5/wd12 面）零触碰；`architecture.md` 其余豁免条目（battle_orchestrator 第三条注销句现状化归战斗编排归约批反哺点）零触碰。
## 6. 关联文档同步面
| 文档 | 关联点（本批实现会改变它的哪条陈述） | 同步义务 |
|---|---|---|
| design/engineering/architecture/architecture.md | 「测试与质量域」S13 测量面豁免注销句（v1.25——「设计闭合、实现批建件」批后现状化；句保持——注销对象是 await 豁免、不依赖行为改动申报；句内「随批申报行为改动一处（收尾置假还原）」半句已失效〔前提被迭代 41 消化、申报已剥离〕，现状化时一并修正为收尾现行陈述） | 设计权威文档——实现批禁直改；逐条列进 `reports/iter44-反哺点-2026-10-30.md`（豁免注销句现状化，该清单 #6 已登记暂停点、随本卡 v1.1 恢复），用户裁决后归文档批落文 |
| game/tests/README.md | 能力表——测量面专属能力行「调参测速批量模拟（逐帧步进与统计读数）」已随本卡写卡段同批入表（真实入口＝批量模拟入口，代表用例＝本卡对拍套件）；manifest 计数行随套件增减浮动（自助声明，零义务） | 机械面文档——实现批禁写；入表已完成于写卡段（本卡 v1.0 同批），实现期零改动 |
| tools/gdstyle_baseline.txt | tune_sim await-in-loop 裸键（:15，该文件唯一在册键）随键消失成死键 | 重生成为人工专用——批末由用户执行 `python tools/gdstyle_gate.py --refresh`（键数 16→15，降幅 <10% 不需 --force）；禁实现批中途刷新 |
| design/gdd/（全目录） | 无关联文档——测量工具私有机制改造，不改游戏规则与玩家可见行为（tune_sim 全链路发布态不可达，设计文档 §7.3） | 无修订预期；契约句被触碰＝停卡呈报走反哺点通道 |
## 7. 卡前文件结构图（本批新建/修改文件全列）
| 文件 | 新增/复用 | 职责 | 行为改动 |
|---|---|---|---|
| game/presentation/tune_sim_controller.gd | 复用（改造） | 批量模拟控制器——process_frame 信号常驻连接＋步进状态机；收尾单点 `_finish_batch`（四语句同帧同相位迁入）；全文件零循环 | 非行为改动（结构改形——收尾语义零变化，零漂移由对拍证；回归锚面＝对照表 V3 行） |
| game/tests/unit/presentation/tune_sim_batch_parity_test.gd | 新增 | 双实现对拍配对套件——现行 await 形态夹具（内类，收尾在 run() 尾的现行形态）＋五面对拍断言 | 非行为改动（测试面） |
| game/tests/run_all.gd | 复用（改造） | manifest 增一行（新套件注册，expect 0） | 非行为改动（测试基建） |
结构图与第 8 节互指：新增件一件（对拍套件），其「为什么不能复用/落点唯一」理由见第 8 节；其余两行均为既有文件改造。行为改动列全为零——每行的验收落点见对照表 V1/V2/V3 行。
## 8. 落位与可复用性预检
- **步进状态机不引入新文件（本件内改造）——为什么不拆新件**：单一职责已在件内——`tune_sim_controller` 的职责就是批量模拟控制，步进机制（每帧一局的节律与帧相位承载）是它的私有运行机制，随批生灭（run 期活成员，批末失效下次 run 重写），没有独立于批量模拟的存在意义；拆出「步进机」件命不出独立职责语句＝凑计数袋（code-conventions §1.1 判据②④禁）。复用面核查：全仓 grep 无信号步进机同职责实现可复用；其余四形态（SceneTreeTimer 链／Timer 节点／递归协程／线程）已被设计文档 §3 逐一否决（相位不同或键不消）。
- **对拍套件落 `game/tests/unit/presentation/` 的唯一性与命名**：落点唯一——与断言宿主 wd8 同目录同协议（extends SceneTree＋Kit 收尾），单元层承载；命名 `tune_sim_batch_parity_test.gd`（领域命名、无 ID 前缀）；grep 同名与同义标识符实查无第二处。**遗留 await 形态副本全仓只许此一份**——产品码禁留第二实现（旧形态只活在测试夹具内）；tests/ 不在 S13/S8/S9/S10 扫描面（扫描面＝产品码三目录与 S8 文件集，实查在案），夹具内循环 await 合法在册。
- **复用面**：夹具的假面板/假驱动复用 wd8 的形态先例（FakePanel/FakeDriver 同形——代码在各套件内自建，不跨套件共享 helper，禁散落）；收尾复用 `test_kit.gd` 的 Kit.finish（零断言专用退出码协议）。
- **分层与交互**：控制器保持 RefCounted、零 Node 入树；process_frame 连接经 `panel.get_tree()` 取树（与现状同一出口）；对拍套件 `--script` 模式零 autoload 依赖（db 用字典夹具，同 wd8 :142 先例）；零新增跨层出口、零数值表读取、零随机。
## 9. 实现规范预算（gdstyle 默认阈值对账：公开方法 ≤20、类变量 ≤15、单函数分支 ≤8、返回 ≤6、参数 ≤5、局部 ≤10、函数 ≤50 行）
本批零新增产品码文件（改造 `tune_sim_controller.gd` 本件）——改造后该文件键账预期（设计文档 §6 逐规则落卡）：
| 规则 | 预期 | 依据 |
|---|---|---|
| quality/await-in-loop（裸键，本案标的） | **消除** | 全文件零 for/while；await 仅 `run()` 函数级一处（`await _batch_finished`）——结构性免疫 |
| quality/allocation-in-loop | 不命中 | 文件零循环；`PlaytestLogger.new()` 在 run 顶层（现状即如此） |
| max-function-length ≤50 | 达标 | run 约 22 行、`_step_frame` 约 12 行、`_finish_batch` 约 6 行、`_run_one_level` 现行 11 行零触碰 |
| max-branches ≤8 | 达标 | `_step_frame` 一个 if/else；run 一个 if/else |
| max-local-variables ≤10 | 达标 | run 局部 3（logger/stats/autoplay——余者转成员）；`_step_frame` 局部 1 |
| max-returns ≤6 | 达标 | 全 void |
| max-parameters ≤5 | 临界持平 | `_run_one_level` 5 参逐字保持；两个新函数 0 参 |
| max-class-variables ≤15 | 达标 | 现 5＋新增 6＝11（`_batch_finished` 信号若被工具计入成员则 12——两值均达标；成员皆 run 期活承载，非凑数袋） |
存量触面一查：基线实查该文件唯一在册键＝await-in-loop 裸键（`tools/gdstyle_baseline.txt:15`）——S13 键较登记值只降不升，裸键消失即清偿；死键由批末用户人工 `--refresh` 自然清去（16→15，降幅 <10% 不需 --force）。新增测试件不在 S13/S9/S10/S8 扫描面（第 3 节实查在案）；仍按 test-conventions §6 全类型标注自律（参数/返回值/容器全带标注）。
## 10. 禁为机检文本保留无效成员（重构类卡必填条款）
禁止为迎合 S13 机检消息文本（含计数）保留或新增无效成员/别名；本批新增 6 个 run 期活成员皆为 `_step_frame`/`_finish_batch` 读写的承载（`_finished` 若实现期确认零读者，可删——见第 14 节白名单 3，成员 11→10 键账只降不升）；机检键与卡片契约互斥时，实现段一律停卡呈报，不得自造第三条路。
## 11. 任务卡 T0..T3（估时为区间；工作量限制只属迭代层——合计 1–1.5 工作日）
**T0 现状复核与读数重锚（0.25 工作日）**
- [ ] 实跑 wd8 单套件（开发期最窄确认，不作验收凭据）：`godot --headless --path game --script res://tests/run_all.gd -- --only=standee_fx_sweep`——记录 :145-147 三断言实况，**应绿**（绿＝前提已被迭代 41 测试债批消化，按无行为改动形态开工）。套件若因在册无关债先红于 wd8 断言，先核该债修复状态、不得借本批顺手修非申报面——读数以「wd8 断言可达性」为准呈报（L2 记录）
- [ ] 实跑 ui_tune_probe 单探针：`…console.exe --headless --path game res://probe/ui_tune_probe.tscn`——记录 ⑤ 守卫环与输出四串实况，**应在**
- [ ] 判读：两面实跑全绿＝重裁前提成立开工；任一面红＝现状与重裁前提失配（迭代 41 修复被回退或新潜伏红）——L3 停卡呈报（第 13 节）
- [ ] 按当轮施工基面重锚第 3 节全部 file:line 与成员计数；漂移处就地改卡并记录（本卡行号基线＝2026-10-30 master；同迭代卡①改址过 main_debug_flow/ui_tune_probe——两件相关行实测未漂移，仍以 T0 重锚为准）
- [ ] 实查产品码 process_frame 订阅面——预期两处（本件 :50＋settlement_fx_view.gd:94）；出现 run 途中新增订阅者场景＝L2 记录＋代码评审注记（设计文档 §5 缺口 2）
产出：现状复核读数（两面绿——前提消化链条的当轮证据，独立验收审计要核对）；重锚后行号。
**T1 步进状态机改造（0.25–0.5 工作日）**
- [ ] `tune_sim_controller.gd` 头注增 `_batch_finished` 信号契约一行（code-conventions §2.1——每信号一行：发射时点＝报告注入与运行态复位之后；消费方＝run() 自身收尾放行，外部 `await run(n)` 经此放行；现 4 行→5 行；禁变更叙事句）
- [ ] 增 `signal _batch_finished` 与 6 个 run 期活成员（名字按设计文档 §4.1 逐字：`_sim_n: int`／`_sim_i: int`／`_sim_stats: Dictionary`／`_sim_autoplay`／`_sim_logger`／`_finished: bool`）
- [ ] `run(n)` 改形：setup 段（:37-46 语句逐字保持）；n>0 分支——`is_connected` 守卫 connect `panel.get_tree().process_frame`（恰好连接一次，迭代 39 先例）→ `_step_frame()` 首步同步执行（与 await 形态「第 0 局在调用栈内跑完」对齐）→ `await _batch_finished`（函数级单次 await——键消除落点）；n=0 分支直调 `_finish_batch()`（循环零进同步收尾，与 await 形态一致不挂起）
- [ ] 新增 `_step_frame() -> void`（0 参）：`_sim_i < _sim_n` 分支——`_run_one_level(_sim_autoplay, _sim_stats, _sim_i, panel, _sim_logger)`＋`panel.set_sim_progress("模拟中：%d/%d …" % [_sim_i + 1, _sim_n])`（串逐字保持现码 :49）＋`_sim_i += 1`；else 分支——先 disconnect（防再入）→ `_finish_batch()` → `_batch_finished.emit()`
- [ ] 新增 `_finish_batch() -> void`（0 参）：收尾四语句由 run() 尾 :51-54 迁入（`close_session()`→报告注入→`panel.set_sim_running(false)`→`_running = false`，同帧同相位——判据③；`_finished = true` 置位为新增首句，对两断言面不可观测——白名单 5）
- [ ] `_run_one_level` **零触碰**（:58-68 逐字保持——败局节点记账非置假；本批行为零改动的锚面）
- [ ] 孤立验证：`--only=standee_fx_sweep` 全绿（wd8 三断言零改动保持绿＝收尾语义零变化实证）＋ui_tune_probe 单探针绿（probe_gate --full 段承载）
- [ ] 自检：新增头注/注释零变更叙事、S11 禁词零命中
取用：T0 重锚行号。产出：`_batch_finished` 信号与 `_step_frame`/`_finish_batch` 签名（T2 对拍新形态即产品码本体）；wd8 保持绿读数。
**T2 双实现对拍夹具（0.25–0.5 工作日）**
- [ ] 建 `game/tests/unit/presentation/tune_sim_batch_parity_test.gd`（extends SceneTree，Kit 收尾，全类型标注）：内类 FakePanel（Node——wd8 同形 setter 面，另带进度串/报告记录数组）＋FakeDriver（RefCounted——固定返回值两档〔victory/defeat，同 wd8 :53-55 取值〕，零随机；逐局记录帧索引与运行态读数，帧索引经宿主注入的计数 Callable 读取）＋AwaitLoopRunner（RefCounted——现 `run()` await 形态逐字副本，含循环内 await 与收尾四语句在 run() 尾的现行形态（:47-54 语句逐字），含自身 `is_running()` 镜像；**与产品码新形态的申报差异仅一处**：批末把 stats 六键束存夹具成员供对拍读取——产品码 stats 经报告公开面观测，第 17 节直查受控例外申报）
- [ ] 对拍驱动：两形态各经 `run(n)` 真实入口驱动（新形态＝真 TuneSimScript 直构，旧形态＝夹具直构；同参假面板/假驱动各自实例）；拓扑钉死——测试宿主先连 process_frame 帧计数、后启动两形态（两形态下「计数先于步进体」相对次序同构，序列可比）；n=3 常规＋n=0 退化两案
- [ ] 五面对拍断言（落点 `_init`，尾缀〔测速 V1〕..〔测速 V5〕）：V1 帧索引序列——两形态逐局记录序列逐位相等（每步恰一帧＋相位同点的执行证据）；V2 运行态序列——驱动内 `is_running()` 读数序列逐位相等＋收尾双运行态假相等；V3 进度串序列——面板记录的 set_sim_progress 串序列逐位相等；V4 stats 六键逐位——夹具暴露 stats 与测试内按假驱动固定返回值重算的六键期望（wins/dmg_all/hp_left_win/hp_boss/rounds_all/death_nodes）逐键相等；V5 报告全文逐字——两形态面板记录的 set_sim_report 串逐字相等，n=3 案含「关卡完成率／关卡完成剩余 HP 均／败北节点／N=」渲染面（n=0 案只断逐字相等——空 stats 渲染无剩余 HP 行，`_mean`/`_p90` 空守卫实查在案）
- [ ] `run_all.gd` manifest 增行 `{"path": "res://tests/unit/presentation/tune_sim_batch_parity_test.gd", "expect": 0}`
- [ ] 孤立验证：`--only=tune_sim_batch_parity` 绿＋`--only=standee_fx_sweep` 复跑绿
取用：T1 的产品码新形态与 `_batch_finished` 放行语义。产出：五面对拍断言面（对照表 V1/V2 行验收主体）。
**T3 键账对账与收口（0.25 工作日）**
- [ ] S13 对账：`python tools/gdstyle_gate.py` 输出确认 tune_sim await-in-loop 裸键消失（消失键不参与红判定）、无基线外新键
- [ ] 关联档复跑：`--only=standee_fx_sweep,tune_sim_batch_parity`＋ui_tune_probe（probe_gate --full 段）全绿
- [ ] 批末代码域闸全绿：`tools/run_all_gates.sh --code`（改动含 game/ 下非 .md 行为载体——`--code` 档）
- [ ] 错误路径声明缺口写入实现报告（第 4 节 🔴 条全文迁入——禁静默）
- [ ] 产出物落位卡：`reports/iter44-实现报告-2026-10-30.md`（各卡状态＋实机目检总清单〔本批零目检项〕＋遗留读数义务＋实现决定记录）与 `reports/iter44-反哺点清单-2026-10-30.md`（第 6 节同步面逐条落点）写齐，方算收口
编队注记：本卡与零豁免其余三卡无产品码触面交集（本卡触面＝tune_sim_controller.gd＋game/tests/ 两件）；run_all.gd manifest 行与并行批可能交叠——编队归编排段。本卡在 iter44 worktree 施工（卡①卡② 已收口冻结在分支），T0 重锚以 worktree 基面为准。
## 12. 验证闸——改动—验收对照表
域口径：本批改动全为 `game/` 下非 .md 行为载体——批末跑代码域闸；里程碑步（T 段）出口跑一次全套闸，波内修复只做出红最小单元的最窄确认，新增测试先行孤立验证再并入全套（测试执行两入口铁规不破）。三件保险（冒烟/系统测试/静态扫描）恒跑；02 单元与集成按关联档选套件——**本卡显式申报套件：standee_fx_sweep_test（wd8——套件名与涉案文件无字面关联，diff 推导可能漏选，特此申报）＋tune_sim_batch_parity_test（新增）**。测试方式两分法：本批全部调试接口自动化（假驱动/假面板直构＋真实按钮信号链探针），零用户目检项（tune_sim 全链路发布态不可达——登记不阻塞条款零登记项）。**静态判据申报（不入对照表，test-conventions §8.4 出口）**：S13 await-in-loop 裸键消除无独立运行期提交面——判据＝`python tools/gdstyle_gate.py` 与 `game/tests/static_scan.sh` 退出码（T3 执行），属静态判据＋评审注记申报观测面局限；对拍夹具不在 S13/S8/S9/S10 扫描面的声明同此口径（扫描面＝产品码三目录与 S8 文件集，static_scan.sh 实查在案）。**声明缺口（不入对照表——证明做不出出口）**：脚本错误中断路径差异不可消除，见第 4 节 🔴 条，实现报告文档化（T3）。**能力清单**：本批新增能力一行「调参测速批量模拟（逐帧步进与统计读数）」已随本卡 v1.0 写卡段同批入表（README :131）——对照表三行能力列锚该行；manifest 计数行随套件增减浮动。
| 行 | 需求点 | 改动（文件:行/行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|---|---|---|---|---|---|---|---|
| V1 | 步进状态机改造（循环内 await 消除的落码面） | tune_sim_controller.gd :36-54 改形（run 函数级单次 `await _batch_finished`，全文件零循环；收尾四语句 :51-54 迁入 `_finish_batch`）＋:58 起新增 `_step_frame`/`_finish_batch` | 复用 wd8 驱动形态 `await ctrl.run(2)`（:144——run 协程身份契约，零改动）；新增对拍 V4/V5（stats 六键逐位＋报告逐字，落点 tune_sim_batch_parity_test.gd:_init，尾缀〔测速 V4/V5〕） | 单元 | TuneSimScript 直构（字典夹具 db＋假面板＋假驱动，wd8 :142 同款）经 `run(n)` 真实入口；对拍两形态同入口 | run 可等待（await 挂起＝整批完成放行）＋stats 六键逐位＋报告全文逐字 | 新增：调参测速批量模拟（逐帧步进与统计读数） |
| V2 | 双实现对拍（帧相位等价的执行化证据） | tune_sim_batch_parity_test.gd 新建＋run_all.gd manifest 增行 | 新增五面对拍断言〔测速 V1–V3〕：帧索引序列／运行态序列／进度串序列逐位相等（落点 tune_sim_batch_parity_test.gd:_init） | 单元 | 两形态各经 `run(n)` 真实入口（n=3 常规＋n=0 退化）；帧索引经测试宿主 process_frame 计数 | 两形态五面记录序列逐位相等（每步恰一帧＋相位同点的当轮执行证据——判据本体） | 新增：调参测速批量模拟（逐帧步进与统计读数） |
| V3 | 运行态语义零变化（收尾迁移的回归锚面——非行为改动行） | 收尾四语句（:51-54）迁入 `_finish_batch` 同帧同相位——非行为改动判断依据：语句集与语义零变化、对两断言面不可观测，等价证据由对拍 V2/V5 承载；`_run_one_level` :58-68 零触碰 | 复用 wd8 三断言〔wd8〕（:145-147——`drv.seen == [true, true]`／收尾双运行态假／报告非空——零改动**保持绿**）＋ui_tune_probe ⑤ 守卫环与输出四串（:63-83——零改动保持绿） | 单元＋探针 | wd8 假驱动回调读 `is_running()`（`await ctrl.run(2)`）；探针 `press_simulate_for_probe()` → 按钮 pressed 信号链 → `run(10)` → 守卫环逐帧复查 | 驱动逐局运行态读数序列 [true, true]＋收尾双运行态假＋守卫环 1800 帧预算内退出＋`output_text()` 四关键串（浮窗运行态贯穿整批的可观测提交面——绿＝保持绿，非转绿） | 新增：调参测速批量模拟（逐帧步进与统计读数） |
反向核对：diff 中行为改动共零处；其余为非行为改动——V1 结构改形（零漂移判据＝对拍五面全等＋wd8/probe 零改动保持绿）、V2 测试面新增、V3 回归锚面行（非行为改动）、manifest 增行（测试基建）。孤儿断言：对拍五断言挂 V1/V2 两行，wd8/probe 既有断言挂 V3 行，无孤儿。
## 13. 异常分级
- **L1 自救**：编译错、断言尾缀措辞、夹具记录数组名笔误——就地修复，重跑最窄单元确认。
- **L2 记录继续**：T0 套件因在册无关债先红于 wd8 断言（记录可达性事实，不借批顺手修）；行号重锚漂移（就地改卡记录）；产品码 process_frame 订阅面发现第三处（记录＋评审注记——非 run 途中新增场景不红）。
- **L3 停机写报告等用户**：①T0 两面任一红＝现状与重裁前提失配（迭代 41 修复被回退或新潜伏红），停卡呈报；②等价性对拍失败——五面任一不等＝测量语义漂移，设计前提崩塌；③机检预算互斥——改造后实测键超第 9 节预算或基线外新键＝上游缺陷停卡退回写卡段（含禁为机检保留无效成员条款冲突）；④S13 对账 await 键未消或冒新键；⑤判据绑不上可观测提交面（证明做不出＝停卡呈报，禁自造注入破坏或回退取证）。
## 14. 代拍板白名单（逐条列，超清单记实现报告「实现决定记录」）
1. 断言失败消息尾缀〔测速 V1–V5〕的分配与措辞。
2. 头注 `_batch_finished` 契约行措辞（信号语义与发射时点不变）。
3. `_finished` 成员零读者确认后删去（成员 11→10——键账只降不升，行为与断言面零变化）。
4. 夹具假面板/假驱动成员命名微调（记录语义不变；与 wd8 同形自建、不跨套件共享）。
5. 收尾段语句相对次序——现行 run() 尾次序（close→报告→置假→_running）与设计草图次序（close→置假→_running→报告）对两个断言面均不可观测，两种皆可落码（实现期查 git 历史原序可进一步对齐）；`_finished = true` 置位为新增首句（成员写，不可观测）。
6. 排版机械改写（空行、preload 顺序、注释换行）。
## 15. 待裁点
零待裁点，开工门=U0。（裁决记录：2026-10-29 用户裁四点——①信号步进状态机形态采纳〔SceneTreeTimer 链/Timer 节点/递归协程/线程四形态淘汰依据见设计文档 §3〕；②收尾置假还原作为已申报行为改动随批实施【已作废——前提被迭代 41 测试债批 215da315 消化，v1.1 剥离】；③双实现对拍入批；④脚本错误中断路径差异接受并文档化。2026-10-30 停卡重裁（用户裁，按停卡呈报建议案逐条落卡）：剥离行为改动申报 V3、T0 义务改现状复核、夹具申报差异两处减一处；重裁沿用 2026-10-29 grilling 复核门结论（reports/复核-grilling-零豁免五卡-2026-10-29.md，修正全落），重裁差异面未新增设计裁决。）
## 16. 测试削弱申报
无申报项——wd8 三断言与 ui_tune_probe ⑤ 零改动零削弱（保持绿）；对拍五断言为新增非改判；夹具与产品码新形态的申报差异仅一处（夹具暴露 stats 供对拍读取）系新增件自身设计、设计文档 §5 在案，非既有断言削弱。禁删断言、禁放宽阈值、禁缩小扫描面、禁把真实入口换成下层直调；未申报的削弱由独立验收审计判红。
## 17. 独立验收审计
合并前由未参与实现的会话或子代理执行；报告落 `reports/iter44-验收审计-2026-10-30.md`，未过不得合并。审计至少做五件事：①逐行核对第 12 节对照表（测试存在、真的执行、尾缀可 grep、真实入口未绕过改动点）；②抽查判据绑定面——帧索引序列是否真从 process_frame 发射点记录、对拍拓扑两形态是否同构可比、V3 行判据是否钉在运行态提交面（保持绿证据，非终态兜底）；③核对现状复核证据在案（T0 两面实跑绿读数＋停卡呈报三重证据引注〔215da315 提交信息〕——前提消化链条完整，缺 T0 复核读数＝审计不过）；④核对行为改动零处——diff 中任何行为改动（含收尾四语句语义漂移）＝审计不过，收尾迁移的等价性由对拍 V2 运行态序列＋V5 报告逐字承载；⑤检查测试削弱（对照第 16 节零申报）与内部字段直查受控例外（本批零直查——新形态 stats 经报告公开面观测）。
## 18. MC／数值与 RNG 零触碰声明
本批零数值改动、零数据表改动、零 RNG 流变化：SEED_BASE=4200 与逐局种子切分零变化（stats 种子纯函数前提）；对拍夹具零随机（假驱动固定返回值）。MC 对拍不跑、零跑批义务（无数值改动——`sim-data/README.md` 档位硬闸：无数值改动零跑）。
reports/需求卡片-组合根注册面批-2026-10-29.md
-337
View File
@@ -1,337 +0,0 @@
# 需求卡片——组合根注册面批（main.gd 类变量归 15：界面注册面＋三域句柄容器）
状态行：v1.0 定稿——零待裁点（2026-10-29 用户裁：注册面拓扑一门面＋三域容器、合同机器迁入、别名消灭清单整体确认；实现层细目授权 agent 按设计文档执行）
接收方：待办清单条目「零豁免五键清偿批——S13 余量五键真修四卡（2026-10-29 登记，来源=会话提及）」——本卡为其四卡之首（组合根注册面批）。
来源：reports/设计-组合根注册面-2026-10-29.md（2026-10-29 设计闭合，**唯一事实源**）；architecture 权威＝design/engineering/architecture/architecture.md v1.25（2026-10-29——「模块归属·呈现层」表 ui_registry 行、「呈现层装配与会话生命周期」节屏成员寻址迁注册面句＝原 S13 豁免登记注销、RunScope 节）。
## 1. 目标与完成定义
这批做什么：把 main.gd（组合根）里散着的屏壳、覆盖层一级句柄与视觉层合同表收进一个「界面注册面」——一个不挂树的 RefCounted 门面件（ui_registry.gd）加三个按领域分的句柄容器（ui_screens／ui_battle／ui_modals），探针和系统测试对界面元素的引用从 `main.X` 一级地址改成 `main.ui.<域容器>.<句柄>` 三段式地址。同时消灭 7 个探针兼容别名/转发成员、退役 6 个 main 纯转发模态方法。main.gd 类变量从 49 降到 15，S13 基线键真实还债，architecture 在册的 S13 豁免登记随批注销。
**行为零变化**：装配序、信号接线、层序（树序＝登记序＝z 序）、RunScope 会话生命周期、RNG 消费序全部零变化；探针断言只换地址、不换判据。
完成定义（全部满足才算完）：
1. 五闸主证全绿——probe_gate 默认段＋`--click`＋`--full`、render_gate golden 零差异、run_smoke、run_system_test、run_all 02 单元与集成（main.gd 触组合根＝横切面，按 AGENTS.md 关联档口径回落全部套件）。
2. static_scan 过——四新文件零新基线键（S9 全类型标注、S10 头注）；main.gd 类变量实测 15（键账对账批末申报，基线 refresh 由用户发令）。
3. 改址完整性自检——按 49 名逐名 grep，`game/` 下旧一级路径 `main.<旧名>`／`root.<旧名>`／`self.<旧名>` 残留＝0，报告留档。
4. 产出物落 `reports/`——实现报告、反哺点清单、验收审计报告（独立审计未过不合并）。
**编队注记与估时**：本卡与「战斗编排归约批」（battle_orchestrator 拆 RoundCycle/BattleFacts 两件——architecture v1.25 轴丁设计闭合、待写卡）和「测速循环批」（tune_sim_controller 步进状态机——architecture v1.25 S13 测量面豁免注销设计闭合、待写卡）同代待编排；三批无同文件交叠（本批触面＝main.gd＋main_ui_build＋三流程件＋探针/测试面）。与迭代 42（在飞：gdstyle 尾波清偿批＋level_runner 商店委托层拆除）**存在文件交叠**——并排卡「level_runner 商店委托层拆除」触面含 main.gd（1 处）、main_adventure_flow（6 处）、main_overlay_flow（2 处），全在本批触面集内（grilling 复核证伪原「无交叠」声明，订正）；**本批开工前置＝迭代 42 合回 master**，T0 按合回点重测改址计数。另与「呈现层状态件批」共享 ui_input_probe.gd 触面（本批改 main.X 地址面、该批改四处 u.face.* 读面）——同代编排时禁并行、先后皆可。估时区间 **3–4 个工作日**（设计文档 §8），低于迭代冻结线（5 个工作日），可编批；编入哪个迭代由迭代编排段定。
## 2. 现状事实
全部行号为 **2026-10-29 实查——本批编入在 gdstyle 尾波补件批相关迭代之前/之后均须 T0 按 T0 时点 master 重测重锚**。
1. `game/presentation/main.gd`（915 行）共 **49 个类变量**（逐名清点 main.gd:61–148，含 3 个委托属性）；S13 基线键 `game/presentation/main.gd|quality/max-class-variables = 49`（阈值 15）在 tools/gdstyle_baseline.txt 在册，architecture v1.25 在册 S13 豁免登记〔2026-10-27「组合根类变量面即探针契约面」〕已随 v1.25 注销、待本批真实还债。
2. 视觉层合同机器四样全在 main.gd：`LAYER_CONTRACT` 常量（main.gd:39–59，19 项含 host/shell/tags 标注）、`_apply_layer_contract()`（main.gd:254–279，全仓唯一 move_child 落位点）、`_layer_node(key)`（main.gd:227–248，19 键 match）、`_register_modal(m, tags)`（main.gd:218–224，anchors preset＋flow.register）。
3. 探针兼容别名/接缝成员 7 个：`board_view`（main.gd:95）、`ap_bar`（main.gd:96）——赋值点 main_ui_build.gd:48–49；`_modals`（main.gd:129，赋值 main_ui_build.gd:245）；`_row_queue`（main.gd:111–113，委托属性读 `_row_pacer.pending_rows()`）；`_seed_edit`（main.gd:74，赋值 main_ui_build.gd:208）；`_settlement_stop_pending`（main.gd:134–143，读＝is_armed()／写＝arm()/disarm()）；`_deferred_modal`（main.gd:148–150，读 `_modal_flow._deferred`）。
4. main 纯转发模态方法 6 个：`_open_modal_after_playback`（main.gd:156–158）、`_on_pump_ended`（main.gd:161–163）、`_open_modal`（main.gd:282–284）、`_close_modal`（main.gd:285–287）、`_on_modal_closed`（main.gd:288–290）、`_input_locked`（main.gd:292–295）——各自一行转呼 `_modal_flow` 真方法。另有一个纯转发方法同批退役：`_flush_row_queue`（main.gd:516，一行转呼 `_row_pacer.flush`）——`_row_pacer` 句柄迁 ui.screens 后调用方 `pacing_queue_test.gd:103` 改调 `main.ui.screens.row_pacer.flush()`（表 D 归宿行）。
5. 装配承接件 main_ui_build.gd：`build(root)` 八步（main_ui_build.gd:21–29），赋值目标全走 `root.X` 一级成员（main_ui_build.gd:38–51 等）；`pump_ended` 注入点 main_ui_build.gd:62；context 束注入 `open_modal/close_modal`（main_ui_build.gd:144、168）；`_apply_layer_contract()` 末位调用 main_ui_build.gd:247。
6. 消费面引用量（设计文档 §0 机械统计，T0 实跑重计）：探针＋系统测试 `main.X` 成员引用约 **867 处**；四个流程承接件（main_adventure_flow／main_overlay_flow／main_debug_flow／main_ui_build）`root.X` 引用约 200–350 处（设计文档 §0 与 §3.2 两处统计口径不一，以 T0 映射表脚本实跑计数为准）。抽查实证：ui_input_probe.gd:34–43（seed_edit／level_screen）、system_test.gd:94–109（LAYER_CONTRACT、_layer_node、V2 句柄等价五连比）、smoke_boot.gd:68–75（`main.get()` 6 处）、pacing_queue_test.gd:108/132/147/149（`_row_queue` 3 处＋`board_view` 1 处）、source_guard_test.gd:69–77（V1d 层序单口断言，现扫 main.gd 单文件）、theme_projection_test.gd:724–725（V6 断言 main.gd 含 `debug_overlay.diagnose_requested.connect(_on_diagnose_pressed)` 串）。
7. 留 main 的 14 成员（对账见表 B）全部是组合根自身状态、组合根拆件引用、autoload 读视图；`run_scope` 引用（探针约 173 处）零迁移。
8. 探针段构成（architecture「测试与质量域」probe_gate 行）：默认段 ui_input_probe／ui_struct_probe／layout_probe／ui_contrast_probe／screen_flow_probe，`--click` 加 ui_click_probe，`--full` 加 ui_probe／ui_tune_probe／t17_defer_probe／fx_probe。
9. meta_progression_forge_test 经 `load("res://presentation/main.gd")` 直呼 static `build_adventure_params`——留 main，零迁移（main.gd:366–376）。
10. 本批不涉 RNG／数值／存档触面；PARITY 触面（battle_orchestrator.gd）不在 diff，无 MC 义务。
## 3. 设计契约（违反即返工，标 🔴 触碰＝L3 停机呈报）
- 🔴 **行为零变化**：装配序与 add_child 顺序、信号连接语句逐条不变；层序合同表条目、顺序、tags、host/shell 标注**逐字零变化**只换宿主文件；`_begin_session`／闲时会话／整节点 queue_free 机制一字不动；RNG 消费序零触碰；呈现层订阅禁令与核心写调用唯一出口纪律零触碰。
- 🔴 **探针断言语义零变化**：改址只换地址不换判据——断言条件、尾缀（既有〔装配生命批 V1〕〔装配生命批 V3〕等保留）、消息语义不动；禁借改址删断言、放宽阈值、缩小扫描面。
- 🔴 **拆分边界纪律五条**（判据权威＝code-conventions §1.1，此处写红线不复制定义）：①每个拆出单元须有可陈述的职责语句与单一变化原因（四件各一句，见 §12 表，实现报告逐件一行承载）；②拆出单元须有集体身份——命不出名字、只能说「剩下的成员」的打包＝凑计数袋，禁；③「过阈值（49→15）」只许作发现信号，作拆分或收拢动机即违规；④按纪律拆不出内聚单元→停卡呈报走豁免通道，禁硬拆凑绿；⑤禁保留/新增无效成员与别名凑数——本批方向是净消灭（7 成员＋6 方法），实现期发现任何「为保地址兼容」新增的转发壳即违契约。
- 🔴 **禁为机检文本保留无效成员**：禁止为迎合机检消息文本（含计数）而保留或新增无效成员/别名；机检键与本卡契约互斥时（如实测出新基线键 NEW 红）一律停卡呈报，不得自造第三条路（详见 §13 条款节）。
- 🔴 **测试削弱申报制**：允许改动的旧断言全集见 §8「测试削弱申报」，未申报的删改由独立验收审计判红。
## 4. 范围边界
做：ui_registry＋三域容器建件；合同机器四样迁驻；main.gd 49→15 改形；main_ui_build 与三流程件改址；探针九件＋probe_ui_util＋smoke_boot＋system_test＋pacing_queue_test 改址；V1d/V6 源码断言重锚；七别名与六转发方法消灭。
不做（明示去向）：
1. architecture.md 直改——实现批禁写 `design/`，ui_registry 行现状化与 main_ui_build 行层序句改指走反哺点通道（§6）。
2. game/tests/README.md 改动——实现批禁写；写卡段义务已核＝零增删零改行（§6）。
3. modal_stack.gd／modal_flow.gd 语义改动——两件零触碰，本批只改它们的消费方地址。
4. RunScope／会话生命周期机制、row_pacer 排播时序、T17 挂起编排——零触碰。
5. S13 豁免登记第二/三条（tune_sim_controller、battle_orchestrator）——原文不动，归「战斗编排归约批」「测速循环批」。
6. board_cell_unit／standee_body／board_view 悬停域等结构债——归迭代 42 尾波清偿批，不收件。
7. 基线 refresh——`python tools/gdstyle_gate.py --refresh` 由用户发令人工跑（净减 1 键，低于 10% 骤降守卫，无需 --force）；实现批只做键账对账申报。
8. MC／数值验证——无数值改动零跑。
## 5. 关联文档同步面
| 文档 | 关联点（本批实现会改变它的哪条陈述） | 同步义务 |
|---|---|---|
| design/engineering/architecture/architecture.md（设计权威——实现批禁直改） | ①「模块归属·呈现层」ui_registry 行现登记「实现批建件」态，实现后应现状化；②同表 main_ui_build 行「层序逻辑不在此件——唯一事实源仍是 `main.LAYER_CONTRACT` + `_apply_layer_contract()`」句在实现后失效（唯一事实源迁 ui_registry.LAYER_CONTRACT＋ui.apply_layer_contract()）；③「呈现层装配与会话生命周期」节屏成员寻址迁注册面句 v1.25 已落、实现后核对措辞与实况一致 | 反哺点通道：把上列 ①②③ 逐条列进 `reports/iter<N>-反哺点-<日期>.md`（改哪一节、改成什么、依据＝设计文档 §3.3 建议句），用户在会话中裁决后归文档批落文 |
| game/tests/README.md（机械面——实现批禁写） | 本批零新增能力（改址只换地址，能力集不变）；受影响存量行核对：「模态覆盖层编排与输入锁」行真实入口（ModalFlow 两个公开方法）与代表用例（modal_flow_test.gd:_init 等）不变；「结算明细带逐行呈现与排播节奏」行代表用例 pacing_queue_test.gd:_init 不变（`文件:函数` 锚不受成员改址影响） | 写卡段义务已当场核完＝**零增行、零删行、零改行**；批末收尾只核对表上名字与实际落地一致（改名则回表） |
| design/gdd/ 无关联文档 | 行为零变化，任何系统文档陈述不受影响；层序唯一事实源属 architecture 不属 GDD | 无（本行占位——按规约查不出也要写明） |
## 6. 卡前文件结构图（本批新建/修改文件全列）
| 文件 | 职责 | 新增/复用 | 行为改动? |
|---|---|---|---|
| game/presentation/ui_registry.gd | 界面注册面门面：三容器属性＋LAYER_CONTRACT＋node(key) 合同寻址＋apply_layer_contract(root) 唯一落位口 | 新增（预检 §12） | 非行为改动（新建件承载既有合同——落点变化，对照表行 1/2） |
| game/presentation/ui_screens.gd | 屏壳与全屏容器域句柄册（9 成员） | 新增（预检 §12） | 非行为改动（对照表行 3） |
| game/presentation/ui_battle.gd | 战区视图域句柄册（5 成员） | 新增（预检 §12） | 非行为改动（对照表行 3/4） |
| game/presentation/ui_modals.gd | 模态层域句柄册＋ModalFlow 持有＋register_layer（14 成员） | 新增（预检 §12） | 非行为改动（对照表行 3/7） |
| game/presentation/main.gd | 组合根改形：49→15；合同机器与转发方法迁出；内部取址改 ui.*；头注追加注册面句 | 修改 | 非行为改动（纯结构——装配/接线/层序/RNG 零变化，四闸主证；对照表行 2/6/7） |
| game/presentation/main_ui_build.gd | 八步赋值目标改 root.ui.*；context 束与 pump_ended 注入改址；_seed_edit/_modals 赋值行退役 | 修改 | 非行为改动（八步顺序/add_child 序/连接语句逐条不变；对照表行 3） |
| game/presentation/main_adventure_flow.gd／main_overlay_flow.gd／main_debug_flow.gd | root.X 同表映射（模态口改指 root.ui.modals.flow；句柄读改 root.ui.*） | 修改 | 非行为改动（对照表行 3/7） |
| game/probe/ 九探针＋probe_ui_util.gd（凡 T0 映射表命中的 main.X 引用件） | 旧地址→main.ui.* 机械改写 | 修改 | 非行为改动（断言语义零变化；对照表行 4/6） |
| game/tests/smoke_boot.gd | get() 键改址（4 改 2 留） | 修改 | 非行为改动（对照表行 3） |
| game/tests/system_test.gd | main.X 改址（V1a/V1c/V2 句柄等价/V3 矩阵取址两处） | 修改 | 非行为改动（判据零变化；对照表行 1/5） |
| game/tests/unit/contracts/source_guard_test.gd | V1d 重锚（单文件扫描→全目录扫描，判据强化） | 修改 | 非行为改动（断言改写已申报；对照表行 8） |
| game/tests/unit/presentation/theme_projection_test.gd | V6 断言串改新连接串 | 修改 | 非行为改动（断言改写已申报；对照表行 9） |
| game/tests/unit/presentation/pacing_queue_test.gd | board_view／_row_queue 改址（3＋1 处） | 修改 | 非行为改动（对照表行 6） |
不触碰：modal_flow.gd／modal_stack.gd／row_pacer.gd／ui_assembler.gd／run_scope.gd／meta_progression_forge_test.gd（static 入口零迁移）／全部 core 与 data。
## 7. 任务卡 T0..T4
### 7.1 地址契约（全批唯一映射依据——表 A/B/C/D 与设计文档 §1.2 对账表同源）
**表 A：迁入注册面的 28 个 main 成员**（容器内成员名去下划线＝公共地址面）：
| 现成员（2026-10-29 行号） | 新地址 | 现成员 | 新地址 |
|---|---|---|---|
| `_menu_screen`(:100) | ui.screens.menu_screen | `legend_overlay`(:116) | ui.modals.legend_overlay |
| `_camp_screen`(:101) | ui.screens.camp_screen | `node_overlay`(:117) | ui.modals.node_overlay |
| `_adventure_screen`(:102) | ui.screens.adventure_screen | `level_screen`(:83) | ui.modals.level_screen |
| `_start_overlay`(:79) | ui.screens.start_overlay | `curio_overlay`(:78) | ui.modals.curio_overlay |
| `_battle_root`(:84) | ui.screens.battle_root | `_end_overlay`(:80) | ui.modals.end_overlay |
| `_inter_overlay`(:81) | ui.screens.inter_overlay | `shop_overlay`(:118) | ui.modals.shop_overlay |
| `_inter_label`(:82) | ui.screens.inter_label | `camp_overlay`(:119) | ui.modals.camp_overlay |
| `debug_badge`(:126) | ui.screens.debug_badge | `settings_overlay`(:121) | ui.modals.settings_overlay |
| `_row_pacer`(:105) | ui.screens.row_pacer | `status_panel`(:122) | ui.modals.status_panel |
| `stage`(:91) | ui.battle.stage | `career_overlay`(:123) | ui.modals.career_overlay |
| `log_view`(:92) | ui.battle.log_view | `save_select_overlay`(:124) | ui.modals.save_select_overlay |
| `info_panel`(:93) | ui.battle.info_panel | `confirm_dialog`(:75) | ui.modals.confirm_dialog |
| `board_zone`(:94) | ui.battle.board_zone | `debug_overlay`(:125) | ui.modals.debug_overlay |
| `settlement_fx`(:97) | ui.battle.settlement_fx | `_modal_flow`(:128) | ui.modals.flow |
**表 B：留 main 的 14＋1**：db、run_scope、save_manager、meta、settings_store、logger、_debug_entry、_confirm_consumer、_confirm_consumer_slot、_debug、_treasure_ui、_bonus、_camp_pres、_tune_sim（保留理由逐个＝组合根自身状态/拆件引用/autoload 读视图，见设计文档 §1.2 第二表）＋新增 `ui: UiRegistry`。改后 15，恰在阈内。
**表 C：消灭的 7 个别名/接缝成员**：
| 成员 | 本体 | 消灭后地址 |
|---|---|---|
| board_view(:95) | ＝board_zone.board_view | ui.battle.board_zone.board_view |
| ap_bar(:96) | ＝board_zone.ap_bar | ui.battle.board_zone.ap_bar |
| _modals(:129) | ＝_modal_flow.stack | ui.modals.flow.stack |
| _row_queue(:111) | 委托属性＝_row_pacer.pending_rows() | ui.screens.row_pacer.pending_rows()（同一 Array 引用，语义不变） |
| _seed_edit(:74) | ＝debug_overlay.seed_edit | ui.modals.debug_overlay.seed_edit.text（main._seed_value 唯一消费点） |
| _settlement_stop_pending(:134) | 委托属性读＝is_armed()写＝arm()/disarm() | run_scope.settlement_stop_timer 直呼同名面 |
| _deferred_modal(:148) | 委托属性＝_modal_flow._deferred | ui.modals.flow._deferred |
**表 D：方法/函数级改址**：
| 旧地址 | 新地址 | 消费方 |
|---|---|---|
| main._layer_node(key) | main.ui.node(key) | system_test V1c（实查 source 点 system_test.gd:97；设计文档记 3 处——T0 重计） |
| main._register_modal(m, tags) | ui_modals.register_layer(m, tags)（逐字迁入：anchors preset＋flow.register） | 仅 _apply_layer_contract 内部消费，随迁 |
| main._apply_layer_contract() | main.ui.apply_layer_contract(root)（root 作参传入，main_ui_build.gd:247 调用点改） | 装配尾唯一调用点 |
| main._open_modal(m) | main.ui.modals.flow.open(m) | 探针各 1 处＋流程件 root. 共约 23 处（T0 重计）；main 内部调用点（_on_confirm_accepted 等）同改 |
| main._close_modal(m)／main._on_modal_closed(m) | main.ui.modals.flow.close(m)（信号 bind 目标 main_ui_build.gd:99/209 改 flow.close.bind） | 同上 |
| main._input_locked() | main.ui.modals.flow.locks_input() | 探针 18 处（T0 重计）＋main._on_board_action/_on_stop_pressed/_on_refresh_confirmed 内部 |
| main._open_modal_after_playback(m) | main.ui.modals.flow.open_after_playback(m) | 流程件 root. 2 处＋探针（T0 重计） |
| main._on_pump_ended | main.ui.modals.flow.pump_ended | row_pacer.pump_ended 注入点 main_ui_build.gd:62 |
| smoke_boot `main.get("_start_overlay"/"debug_badge"/"legend_overlay"/"status_panel")` | `main.get("ui").<域>.<名′>`（get 只解析一层，后续走公共字段） | smoke_boot.gd:70/73/74/75；`get("run_scope")`/`get("settings_store")` 零迁移 |
| source_guard V1d 串 | 重锚：扫全 `game/presentation/*.gd`，`move_child(` 只允许出现在 ui_registry.gd 的 apply_layer_contract 函数体内（从扫单文件变扫全目录——判据强化） | source_guard_test.gd:69–77 |
| main._flush_row_queue() | main.ui.screens.row_pacer.flush()（转发壳随 `_row_pacer` 迁移退役） | pacing_queue_test.gd:103 |
| theme_projection V6 串 | 改断言新串 `ui.modals.debug_overlay.diagnose_requested.connect(_on_diagnose_pressed)`（连接语句本体随 T2 改写 main.gd:209） | theme_projection_test.gd:724–725 |
### 7.2 新件接口块（T1 定义，T2 起逐字取用；类型标注义务＝S9 过）
```
# game/presentation/ui_registry.gd —— 界面注册面（RefCounted，不挂树，零信号连接，零会话期引用）
class_name UiRegistry
extends RefCounted
const ModalStack := preload("res://presentation/modal_stack.gd")
const LAYER_CONTRACT: Array[Dictionary] = [ …main.gd:39-59 内容逐字迁入，一项不增不减不改… ]
var screens: UiScreens
var battle: UiBattle
var modals: UiModals
func node(key: String) -> Node # 合同寻址：_layer_node 的 19 键 match 逐字迁入
func apply_layer_contract(root: Control) -> void # 落位算法逐字搬运（move_child 单口；登记经 modals.register_layer）
# game/presentation/ui_screens.gd —— 屏壳与全屏容器域（RefCounted，纯字段无方法）
class_name UiScreens
extends RefCounted
var menu_screen: Control
var camp_screen: Control
var adventure_screen: Control
var start_overlay: Control
var battle_root: Control
var inter_overlay: Control
var inter_label: Label
var debug_badge: Button
var row_pacer: RowPacer # 经 preload 常量取型（res://presentation/row_pacer.gd 非 class_name 全局）
# game/presentation/ui_battle.gd —— 战区视图域（RefCounted，纯字段无方法）
class_name UiBattle
extends RefCounted
var stage: BattleStageView
var log_view: BattleLogView
var info_panel: HeroInfoPanelView
var board_zone: BoardZoneView
var settlement_fx: SettlementFxView
# game/presentation/ui_modals.gd —— 模态层域（RefCounted）
class_name UiModals
extends RefCounted
var flow: ModalFlow
var legend_overlay: LegendOverlay
var node_overlay: NodeOverlay
var level_screen: LevelMapScreen
var curio_overlay: CurioPickOverlay
var end_overlay: BattleEndOverlay
var shop_overlay: ShopOverlay
var camp_overlay: CampOverlay
var settings_overlay: SettingsOverlay
var status_panel: StatusPanel
var career_overlay: CareerOverlay
var save_select_overlay: SaveSelectOverlay
var confirm_dialog: ConfirmDialog
var debug_overlay: DebugOverlay
func register_layer(m: Control, tags: Array = []) -> void # _register_modal 逐字迁入
```
（main.gd 现有类型标注逐字沿用：ui_battle/ui_modals 十八句柄的类型名＝main.gd:78–125 在用全局类名；ui_screens 三屏壳标 Control，若 T1 实测场景根基类不符，按代拍板白名单第 6 条取实际基类。）
### 7.3 T0——读数重锚与对账（估时 0.5 个工作日）
- [ ] 按 T0 时点 master 重测重锚本卡全部行号与计数：main.gd 类变量实数（gdstyle 读数）、合同机器四样行位、七别名与六转发方法行位、六转发方法的全部调用点清单（main 内部＋流程件＋探针＋system_test 分文件计数）。
- [ ] 49 成员逐一对账：对照本卡表 A/B/C 逐名核对仍在位、仍归该档（迁移 28／留 14／消灭 7）——任何一名对不上＝L3 停卡呈报（设计文档 §1.2 对账表为第二依据）。
- [ ] 映射表脚本生成＋对账：探针九件＋probe_ui_util＋smoke_boot＋system_test＋四流程件的 `main.X`／`root.X` 全量计数与旧→新映射（机械生成＋人工复核语义位——属性读写约 750 处、方法调用四类、字符串键 6 处、源码断言 2 条）；设计文档 867/350/200 三处统计口径以本次实跑为准并在实现报告记数。
- [ ] 未登记源码断言排查：grep `presentation/main.gd` 于 game/tests＋game/probe 全部源码断言面——只许 V1d/V6 两条命中；新发现＝L3 停卡补申报，禁自行改判。
- [ ] 迁移函数对账：查 tools/gdstyle_baseline.txt 中 main.gd 的 `_apply_layer_contract`／`_layer_node`／`_register_modal` 源函数键——branches/returns/函数长有超默认登记值的，迁移即拆函数（拆分不改语义）。
- [ ] 孤立验证（改前基线读数）：`python tools/gdstyle_gate.py`（采集 main.gd＝49 读数）＋`godot --headless --path game --script res://tests/run_all.gd -- --only=source_guard`（绿）。
- 取用：本卡 §7.1 四表。产出：重锚后的映射表与对账表（实现报告附件节，T2/T3/T4 消费）。
### 7.4 T1——注册面与三域容器建件（估时 1 个工作日）
- [ ] 按 §7.2 接口块建 ui_registry.gd：LAYER_CONTRACT 自 main.gd:39–59 逐字迁入（ModalStack 常量引用随迁）；`node(key)` 19 键 match 逐字；`apply_layer_contract(root)` 落位算法逐字搬运（move_child 单口语义不变）。
- [ ] 建 ui_screens／ui_battle／ui_modals（成员与类型按 §7.2；ui_modals.register_layer 自 main.gd:218–224 逐字迁入）；四件全类型标注、`_init` 不收参（容器由门面构造）。
- [ ] 四件 class_name（UiRegistry/UiScreens/UiBattle/UiModals）＋跑一次编辑器扫描刷新全局类缓存＋同步 .uid（code-conventions 语言纪律 5——T2 main.gd 类型标注 UiRegistry 在 --script 模式可解析的前置）；文件头 `##` 注释介绍模块（禁变更叙事、禁文档反向链接）。
- [ ] 孤立验证：`game/tests/static_scan.sh`（S9 四新件零红＋S10 头注过＋S13 四新件零新键）＋`godot --headless --path game --script res://tests/run_all.gd -- --only=source_guard`（V8 全库扫描仍绿——新件零字符串 Callable）。
- 取用：T0 映射表。产出：四件公开面（UiRegistry.new()／.screens／.battle／.modals／.node(key)／.apply_layer_contract(root)／modals.register_layer(m, tags)——T2 逐字消费）。
### 7.5 T2——main.gd 改形与装配/流程件改址（估时 1–1.5 个工作日）
- [ ] main.gd 新增 `var ui: UiRegistry`；`_ready` 在 `_build_ui()` 之前 `ui = UiRegistry.new()`（容器随门面构造；装配在 _ready 建闲时会话之前完成——时序零变化）。
- [ ] 表 A 28 成员迁出：main 内部全部取址同步改 `ui.*`（含 main.gd:199–200 启动态两行、_seed_value:911、_on_confirm_accepted/_start_adventure/_resume_from_menu/_replay_locked_click 等内部调用点改指 ui.modals.flow.*／ui.screens.row_pacer.pending_rows()）；合同机器四样自 main 删除（随 T1 迁驻）。
- [ ] main_ui_build.gd：八步赋值目标改 `root.ui.<域>.<名′>`（八步顺序、add_child 顺序、连接语句逐条不变）；`root._seed_edit` 赋值行（:208）删除；`pump_ended` 注入改 `root.ui.modals.flow.pump_ended`（:62）；`root._modals` 赋值行（:245）保留至 T4；context 束 overlay/toast/start_overlay/board_view 键值改址（:137–147、:163–169，注入时点与值不变）；`_apply_layer_contract` 调用改 `root.ui.apply_layer_contract(root)`（:247）。
- [ ] 三流程件 root.X 按表 A/D 同表映射（root._open_modal/_close_modal/_open_modal_after_playback/_input_locked → root.ui.modals.flow.*；`_settlement_stop_pending` 写点改 `run_scope.settlement_stop_timer.arm()/disarm()`——写点计数 T0 对账）。
- [ ] smoke_boot.gd get() 改址（4 改 2 留，§7.1 表 D）。
- [ ] source_guard_test.gd V1d 重锚为全目录扫描（尾缀〔注册面 V1〕）；theme_projection_test.gd V6 改断言新串（尾缀〔注册面 V2〕）——两条改写即 §8 申报的测试改动全集。
- [ ] 孤立验证：`python tools/run_smoke.py`（冒烟绿＝装配链完整）＋`godot --headless --path game --script res://tests/run_all.gd -- --only=source_guard,theme_projection,meta_progression_forge`（三套件绿——V1d/V6 重锚后绿、static 入口零变化）＋`python tools/gdstyle_gate.py`（main.gd 类变量读数记录——此轮含 7 别名＝22，基线键 49 内不红，读数进实现报告）。系统测试与探针此轮预期红（消费面未改址——T3 收口），不构成本卡验证面。
- 取用：T1 四件公开面。产出：main.ui.* 地址面全量生效的组合根（T3 消费）。
### 7.6 T3——探针/系统测试/单元批量改址（估时 1 个工作日）
- [ ] 探针九件＋probe_ui_util 按 T0 映射表机械改写：属性读/写改 `main.ui.<域>.<名′>`；四类方法调用按表 D；`var bv = main.board_view` 型局部承接改 `var bv = main.ui.battle.board_zone.board_view`（每文件 1–2 处）。
- [ ] 接缝三件：ui_struct_probe 的 `main._modals` → `main.ui.modals.flow.stack`（登记序断言）；t17_defer_probe 的 `main._deferred_modal` → `main.ui.modals.flow._deferred`（挂起态断言）；ui_click_probe 的 `_settlement_stop_pending` 读点 → `main.run_scope.settlement_stop_timer.is_armed()`。
- [ ] system_test.gd 改址：V1c 的 `main.LAYER_CONTRACT`→`main.ui.LAYER_CONTRACT`、`main._layer_node`→`main.ui.node`；V2 句柄等价断言（:107–109）改 ui 地址（等价语义不变：ui.battle.board_zone.board_view == ui.screens.adventure_screen.board_view 型）；V1a 候选清单与全件 main.X 逐表映射；V3 矩阵 `_face_snapshot` 的 `main._modal_flow`→`main.ui.modals.flow`、`main._row_pacer`→`main.ui.screens.row_pacer`（其余四持件取址不变）。
- [ ] pacing_queue_test.gd：`main.board_view`→`main.ui.battle.board_zone.board_view`（:132）；`main._row_queue`→`main.ui.screens.row_pacer.pending_rows()`（:108/:147/:149，实查 3 处）。
- [ ] 改址完整性自检：映射表驱动 49 名逐名 grep——`game/` 下（探针/tests/流程件/main 自身）旧一级路径 `main.<旧名>`／`root.<旧名>`／`self.<旧名>` 残留＝0，报告留档（实现报告对照表挂行）。
- [ ] 孤立验证：`tools/probe_gate.sh --click --full`（全段退出码 0）＋`python tools/run_system_test.py`（V1–V9 摘要 0 失败）＋`python tools/run_smoke.py`＋`godot --headless --path game --script res://tests/run_all.gd -- --only=pacing_queue,source_guard`。
- 取用：T2 地址面。产出：全部消费面新地址（T4 前提——别名/转发方法零消费方）。
### 7.7 T4——别名与转发方法消灭＋批末收口（估时 0.5–1 个工作日）
- [ ] 删 main.gd 七别名/接缝成员（表 C——此点已零消费方）与六转发方法（§2 第 4 条清单）；删 main_ui_build.gd:245 `root._modals` 赋值行；main.gd 类变量终态 **15**。
- [ ] 文件头注随迁改写：main.gd 头注追加一句「界面句柄与层清单在 ui 注册面（ui_registry.gd）」；main_ui_build.gd 头注「层序唯一事实源」句改指 ui_registry（指址改写、词面语义不变）。
- [ ] 逐卡扫尾孤立验证：`tools/render_gate.sh`（golden 零差异）＋`tools/probe_gate.sh --click --full`＋`python tools/run_smoke.py`＋`python tools/run_system_test.py`＋`godot --headless --path game --script res://tests/run_all.gd -- --only=pacing_queue,modal_flow,source_guard,theme_projection,meta_progression_forge`。
- [ ] 批末全量：`tools/run_all_gates.sh --code` 全绿（main.gd 触组合根＝横切面——02 单元与集成按 AGENTS.md 横切面口径回落全部套件；冒烟/系统测试/静态扫描三件保险恒跑）。里程碑步出口跑一次全套闸；波内修复只做出红最小单元的最窄确认；新增测试先行孤立验证再并入全套。
- [ ] S13 键账对账申报：main.gd 键 49→15 只降不升、四新件零新键；基线 refresh 由用户发令人工跑（--refresh，净减 1 键低于骤降守卫）。
- [ ] **产出物落位卡**（轻闸全绿后、合并前写齐，方算收口）：`reports/iter<N>-实现报告-<日期>.md`——各卡状态＋实机目检总清单（登记不阻塞：注册面改址后实机过一遍三屏切换与模态开合）＋遗留读数义务（基线 refresh）＋实现决定记录＋改址计数与 grep 自检留档；`reports/iter<N>-反哺点-<日期>.md`——§5 同步面所列 architecture 三条逐条有落点；`reports/iter<N>-验收审计-<日期>.md`——独立验收审计（未参与实现的会话或子代理执行，未过不得合并）。
- 取用：T3 零消费方清单。产出：终态 main.gd（15 var）＋三份 reports/ 产出物。
## 8. 验证闸（改动—验收对照表）
本批全部改动为**非行为改动**（结构与地址重构）：每行判断依据＝改前改后在同一输入上行为一致，由探针／系统测试／冒烟／渲染 golden 四闸主证（真实入口全绿），静态 grep 只作完整性辅证。调试接口/目检两分法：本批无新玩法能力，验证全走自动化载体；用户目检仅一条登记项（T4 实机过三屏与模态开合），登记不阻塞。**静态判据申报（不入对照表，test-conventions §8.4 出口——grilling 复核订正）**：S13 键账对账（main.gd 实测 15、四新件零新键、基线 refresh 由用户发令）与映射表驱动 grep 残留＝0 自检无独立运行期提交面——判据＝`python tools/gdstyle_gate.py`/`game/tests/static_scan.sh` 退出码与 T3 grep 自检留档，属静态判据＋评审注记申报观测面局限；对照表行 2/11 只承载其运行面回归与全量闸半边。
| # | 需求点 | 改动（文件:行/行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|---|---|---|---|---|---|---|---|
| 1 | 注册面建件＋合同机器迁驻（层序零变化） | 新建 ui_registry.gd（LAYER_CONTRACT main.gd:39–59 逐字迁入）；ui_screens/ui_battle/ui_modals 建件 | 系统测试 V1c「合同树序链逐对保序」（system_test.gd:94–106 改址 main.ui.LAYER_CONTRACT／main.ui.node，尾缀〔装配生命批 V1〕保留） | 系统测试 | `python tools/run_system_test.py` | 运行期树序逐对保序＝LAYER_CONTRACT 序（get_index 链——层序零变化的运行期提交面） | 既有：模态覆盖层编排与输入锁 |
| 2 | main.gd 改形回归（49→15 结构改形） | main.gd:61–148 改形（28 迁出＋7 消灭＋1 新增）；六转发方法退役 | 批末 run_smoke＋run_system_test 双宿主摘要 0 失败（改形回归主证；S13 键账静态判据见域口径申报） | 冒烟＋系统测试 | `python tools/run_smoke.py`；`python tools/run_system_test.py` | 双宿主摘要 0 失败（改形后全链路回归面） | 既有：模态覆盖层编排与输入锁 |
| 3 | 装配与流程件改址（root.ui.*） | main_ui_build.gd 八步赋值目标；三流程件＋context 束＋pump_ended 注入点；smoke_boot.gd:70/73/74/75 | 冒烟主屏存活面六断言（smoke_boot.gd:64–75 改址后全绿）＋系统测试 V2「组合根句柄指向屏壳成员」等价断言（system_test.gd:107–109 改址，五连比同指） | 冒烟＋系统测试 | `python tools/run_smoke.py`；`python tools/run_system_test.py` | 启动态装配句柄在座且等价断言两侧同指一对象（多一跳取到同一引用） | 既有：模态覆盖层编排与输入锁 |
| 4 | 探针面批量改址（约 867 处） | 探针九件＋probe_ui_util 旧地址→main.ui.*（只换地址不换判据） | probe_gate 全段退出码 0（ui_input_probe 全 case／ui_struct_probe／layout_probe／ui_contrast_probe／screen_flow_probe＋--click ui_click_probe＋--full ui_probe/ui_tune_probe/t17_defer_probe/fx_probe） | 探针 | `tools/probe_gate.sh --click --full`（单件形态：`godot --headless --path game res://probe/ui_input_probe.tscn` 等） | 探针经新地址取到同一节点并驱动真实输入路径（改址完整性的第一消费方主证） | 既有：棋盘悬停反馈（三语义光标／目标格边框／路径预览点迹） |
| 5 | 系统测试面改址＋RunScope 生命周期零变化 | system_test.gd main.X 改址；V3 矩阵取址两处（_modal_flow→main.ui.modals.flow、_row_pacer→main.ui.screens.row_pacer） | 系统测试 V1–V9 全绿（含 V3a–V3i 九阶段×五引用面矩阵，尾缀〔装配生命批 V3〕保留） | 系统测试 | `python tools/run_system_test.py` | 第五引用面逐面同源比对（回调悬挂＝红——存活性矩阵判据零变化） | 既有：模态覆盖层编排与输入锁 |
| 6 | 别名/接缝成员消灭（7 个） | main.gd:74/95/96/111/129/134/148 消灭；消费方改址（pacing_queue_test.gd:108/132/147/149、ui_struct_probe、t17_defer_probe、ui_click_probe、main 自身 4 处 _row_queue） | run_all 选跑 pacing_queue 绿（排空零分叉/零丢行/延迟双态/会话清队断言改址后判据不变）＋ui_struct_probe 登记序断言＋t17_defer_probe 挂起态断言 | 单元＋探针 | `godot --headless --path game --script res://tests/run_all.gd -- --only=pacing_queue`；`tools/probe_gate.sh --full` | 属性链与别名取到同一对象引用（断言逐条等价——同一 Array/同一节点的可观测面） | 既有：结算明细带逐行呈现与排播节奏 |
| 7 | 六个 main 纯转发模态方法退役 | main.gd:156/161/282/285/288/292 退役；调用方改指 ui.modals.flow 五个真方法＋注入点 main_ui_build.gd:62 | modal_flow 单元套件绿＋系统测试 V3g 模态开合段＋ui_click_probe 模态开合路径 | 单元＋系统测试＋探针 | `godot --headless --path game --script res://tests/run_all.gd -- --only=modal_flow`；`python tools/run_system_test.py`；`tools/probe_gate.sh --click` | 经真方法开合编排（遮挡互斥/锁谓词/挂起兜底行为面零变化——开合后可见性与锁态提交面） | 既有：模态覆盖层编排与输入锁 |
| 8 | V1d 源码断言重锚 | source_guard_test.gd:69–77 重锚为全目录扫描（move_child 只许在 ui_registry.gd apply_layer_contract 体内） | 「V1d 层序落位单口」重锚断言，尾缀〔注册面 V1〕 | 单元 | `godot --headless --path game --script res://tests/run_all.gd -- --only=source_guard` | 源码契约扫描面（扫描面>0 前置——全 presentation 目录零第二落位点） | 既有：模态覆盖层编排与输入锁 |
| 9 | V6 源码断言改串 | theme_projection_test.gd:724–725 改断言新连接串 | 「V6 转储入口连接随迁」新串断言，尾缀〔注册面 V2〕 | 单元 | `godot --headless --path game --script res://tests/run_all.gd -- --only=theme_projection` | main.gd 源码含新连接串（同一连接的宿主面改写） | 既有：UI 全局主题与按钮五态（含对比度锚） |
| 10 | 视觉零变化主证 | 全批呈现层地址重构（像素面零改动） | render_gate golden 零差异（shot_probe 七屏＋菜单 golden＋棋盘 golden） | 探针/golden | `tools/render_gate.sh` | 截图与基线图逐像素容差零差异（视觉零变化的独立主证——出现任何此前不存在的差异即 L3） | 既有：站桩敌人呈现与结算演出落点 |
| 11 | 改址完整性收口 | 全批改址面（49 名逐名） | 批末代码域闸全绿（`tools/run_all_gates.sh --code`，02 横切面回落全量套件）；映射表驱动 grep 自检＝T3 步骤义务（静态判据，见域口径申报） | 全量闸 | `tools/run_all_gates.sh --code` | 所选域全绿回执 | 既有：模态覆盖层编排与输入锁 |
**测试削弱申报**（实现期允许的旧断言改动全集，超出即审计判红）：
1. V1d：扫描面从「main.gd 单文件」扩为「全 game/presentation/*.gd」——判据强化，非削弱。
2. V6：断言串从 main.gd 旧连接串改为新连接串——同一连接的宿主面改写，断言不删除。
3. 冒烟/系统测试/探针/pacing 各断言：只改地址字面，判据与既有尾缀不动——零删除、零放宽、零换下层直调。
4. 七别名＋六转发方法随批退役＝test-conventions §5.5 同生死条款的执行：消费方断言已全部改指新地址，旧地址无断言残留（T3 grep 自检为证）。
**独立验收审计**：入口与报告＝`reports/iter<N>-验收审计-<日期>.md`；审计方＝未参与实现的会话或子代理，逐行核对对照表、抽查判据绑定面、检查测试削弱、核对静态判据行的观测面局限注记；未过不得合并。
## 9. 异常分级
- **L1 自救**：单点漏改址→grep 定位补改后重跑该闸段；`--only` 选跑零命中（用法错 exit 2）→修正选词重跑；探针段超时→孤立复跑该段定位。
- **L2 记录继续**：同一红闸连续 3 次同因→升级记录并在实现报告「实现决定记录」节记因后继续最窄确认。
- **L3 停机写报告等用户**：
1. **行为零变化契约触探**——任一闸出现改前不存在的红且定位为层序/时序/接线行为变化；render golden 出现任何此前不存在的差异。
2. **机检预算互斥＝上游缺陷停卡退回写卡段**——四新件或 main 终态实测超 §14 预算、或 static_scan 出基线外 NEW 红键；禁开豁免、禁自造第三条路。
3. T0 对账失败——49 名逐一对账与表 A/B/C 任一名对不上，或发现未登记的 main.gd 源码字符串断言。
4. 拆分边界④触发——按纪律拆不出内聚单元（本设计已拆出，若实现期发现表 A 归档错误的成员强行迁入会破集体身份时适用）。
## 10. 代拍板白名单（逐条列，超清单记实现报告「实现决定记录」）
1. 改址机械改写：映射表内旧→新地址的行内改写、被改行注释内旧地址字面同步更新（判据不动）。
2. 重锚断言的消息文字措辞（V1d/V6 两条——尾缀〔注册面 V1〕〔注册面 V2〕与判据不变）。
3. 迁移函数/成员头注按新宿主改写指址（词面随迁、语义不改）。
4. 探针内局部承接变量名保留或内联（`var bv` 型——判据不变）。
5. grep 自检留档在实现报告内的节名与格式。
6. ui_screens 三屏壳句柄静态类型在 Control 与实测场景根实际基类之间取（判据＝S9 过＋赋值编译过；成员名与地址面不变）。
7. main 内部调用点在 T2 先改真方法、转发方法留至 T4 删除的批内中间态时序（终态零转发壳）。
## 11. 待裁点
**零待裁点，开工门＝U0。** 设计文档 §8 五项待裁点已于 2026-10-29 用户全裁：①注册面拓扑＝一门面＋三域容器；②合同机器随批迁入注册面；③七别名消灭＋六转发方法退役＋容器内成员去下划线——清单整体确认；④run_all 关联档口径＝main.gd 触组合根按横切面回落全部套件；⑤编批归迭代编排段定（本卡估时 3–4 个工作日在冻结线内）。
## 12. 落位与可复用性预检
**复用面**（逐个排除既有件——为什么不能复用）：
- **modal_flow.gd（ModalFlow）**：模态编排纯逻辑——开合编排、输入锁谓词、T17 挂起。它管行为不管地址；注册面管「元素清单、层序、寻址」，是它的宿主容器（flow 挂在 ui_modals 里）。职责语句不同，不能拿它当注册面。
- **modal_stack.gd（ModalStack）**：登记册数据结构（遮挡记账），被 ModalFlow 持有；层序合同表与三域寻址不归它。非候选。
- **ui_assembler.gd**：无态静态装配工厂——装配期造控件用完即弃，不持任何句柄；注册面是随 main 常驻的句柄容器。把「造」和「持」并进一件会让静态工厂变有态，破坏现行职责。
- **run_scope.gd**：局态节点——装的是会话状态不是界面元素清单；173 处探针引用零迁移义务已核。非候选。
- 形态先例（非复用对象）：ConfigDB 迭代 41 三张域容器（config_domain_combat/run/crossrun.gd）解决过同构的成员数超标问题——本批三容器即同一形态在呈现层的落法。
**唯一面**：层序合同唯一事实源随迁 ui_registry.LAYER_CONTRACT（main.gd 侧删除，不双写）；合同寻址唯一口＝ui_registry.node()；模态登记唯一口＝ui_modals.register_layer()。2026-10-29 实查 game/presentation/ 下无 ui_registry/ui_screens/ui_battle/ui_modals 同名或同义件（architecture v1.25 登记「实现批建件」即此四名，盘上未建）——新增无第二落点。
**分层与交互面**（调用路径显式）：
- 读地址路径：views／探针／流程件 → `main.ui.<域容器>.<句柄>` → 容器字段 → 节点。三段式每段有领域含义（组合根→注册面→域→元素），与 ConfigDB 的 `db.<域容器>.<成员>` 两段式同构。
- 注册面禁反向持有：不持 main、不持 run_scope、零信号连接、零核心写调用、零 `_process`——依赖单向（views→信号→组合根→core）零触碰；组合根单点装配不变（信号连接仍在组合根与 main_ui_build）。
- 构造路径：main._ready 建 `ui = UiRegistry.new()`（门面自建三容器），main_ui_build 八步向容器登记；四件全 RefCounted 不挂树（节点本体树位与 add_child 归属零变化——row_pacer 仍 add_child 到 main，注册面只持引用）。
- Core 零 UI 红线零触碰：本批改动全部在 game/presentation/ 与测试面。
## 13. 禁为机检文本保留无效成员（重构类卡必填条款）
禁止为迎合机检消息文本（含计数）而保留或新增无效成员/别名：main.gd 终态 15 个类变量必须个个有 §7.1 表 B 的职责理由，禁留空占位或替身成员凑计数；四新件的字段必须个个是表 A 在册句柄或 flow，禁加「以防万一」的空槽。机检键与本卡契约互斥时（如实测出新基线键 NEW 红、或键账与申报不符），实现段一律停卡呈报走 L3，不得自造第三条路。判据权威＝code-conventions §1.1⑤。
## 14. 实现规范预算（gdstyle 默认阈值：公开方法 ≤20、类变量 ≤15、单函数分支 ≤8、返回 ≤6）
| 新件 | 公开方法 | 类变量 | 阈值判定 |
|---|---|---|---|
| ui_registry.gd | 2（node／apply_layer_contract） | 3（三容器属性；LAYER_CONTRACT 为常量不占 var） | 双达 |
| ui_screens.gd | 0 | 9 | 双达 |
| ui_battle.gd | 0 | 5 | 双达 |
| ui_modals.gd | 1（register_layer） | 14（13 句柄＋flow） | 双达（余量 1——第 14 个模态句柄出现即触发拆分审视，作发现信号用） |
- 迁移函数对账：`_apply_layer_contract`／`_layer_node`／`_register_modal` 自 main.gd 迁入，T0 查 gdstyle_baseline.txt 源函数键——超默认登记值的迁移即拆函数（拆分不改语义）；node(key) 的 19 键 match 与合同落位循环预期在默认分支阈内（设计文档 §7 同判断），实测出新键＝基线外 NEW 红＝L3 停卡（禁开豁免）。
- 存量触面一查：本批触碰的 presentation 存量件（main.gd／main_ui_build.gd／三流程件）预期「S13 键较登记值只降不升」——main.gd 49→15；main_ui_build 与三流程件零成员变化（仅语句内地址改写）；达成手段＝表 A/C 全量迁移＋别名净消灭。
- 指标例外申报：无（本批不需要任何超默认面；main.gd 改后 15 在阈内，S13 豁免登记注销后不留新例外）。
## 15. 源码级断言与探针契约面的随批义务（防漏项清单）
1. V1d（source_guard_test.gd:69–77）与 V6（theme_projection_test.gd:724–725）随批重锚——本卡已全量排查 main.gd 源码断言面仅此两条（T0 复核义务不豁免）。
2. 探针段覆盖义务：probe_gate 必须 `--click`＋`--full` 全跑——ui_click_probe 是最大改址户，只跑默认段会漏最深的改址面。
3. 冒烟 V1 族 get() 键、系统测试 V1c/V2/V3 取址、pacing `_row_queue` 三处——都在 §7.1 表 D 与 T3 清单内，T0 映射表生成后逐条打钩对账。
roadmap.md
+3 -3
View File
@@ -5,8 +5,8 @@
## 当前位（只回答「现在该做什么」；三行内随批次换代，禁止在此扩写成状态快照）
- **阶段**：M3——Alpha 版本的完整实现（2026-10-09 立规：未明令宣布完成前停留 M3，迭代只排 M3 需求，M4 不排期；根目录 stage.txt 为旧阶段开关仅存档）。
- **迭代位**：迭代 1–43 全部已完成——迭代 43（战斗一屏样张批）2026-10-30 合回（合并提交 3b66d1a6），同日完成批后收尾（反哺点 13 条处置闭合：落文四处 art-bible v3.23／art-prompts v2.10／战斗表现 v1.2／test-conventions 旧句清偿，消解三条，移交待办清单两条目；产出物与两卡需求卡片退役；方向稿目检登记体验验证清单 ㊶）。迭代 42 收尾记录见 git 提交 7ec2af58。
- **下一步**：迭代 44 待开工（组合根注册面＋战斗编排归约＋测速循环三卡，编队前置＝迭代 42 合回已满足）——开工前宜裁 PARITY 对拍漂移查因/重锚（闸 11 触面）与迭代 43 批后待裁三点（待办清单在册）。待编池：营地交互重做卡⑤（排卡④之后）、卡④（已退回美术设计段，美术设计闭合后重立卡）、冒险前资源配比预设（冻结备选）、迭代 30 原卡②③（2026-10-17 已剔出迭代 30 规划、退回待设计，待美术／设计定稿后重新立卡）。批后可裁事项：gdstyle 基线 refresh 收账随零豁免各批合回一次人工 `--refresh --force`（待办清单在册）。
- **迭代位**：迭代 1–44 全部已完成——迭代 44（零豁免三卡：组合根注册面＋战斗编排归约＋测速循环 v1.1）2026-10-30 合回（合并提交 bee73db5，独立验收审计通过，行为零变化），批后收尾闭合（2026-10-31）：反哺点六条落文 architecture（四件现状化＋构造句/实测值换代＋两注销句修正）、gdstyle 基线 refresh 收账（16→5 键：五键清偿消失＋iter42 归绿键离账＋留债三键按实测重登记 28→23/32→31/50→33，零新增键）、目检两项登记体验验证清单 ㊷、产出物退役（三报告＋三卡＋三设计文档＋grilling 复核）。迭代 45（呈现层状态件＋gdstyle 尾波补件两卡）2026-10-31 已合回（合并提交 f817ab2d）未收尾。迭代 42 收尾记录见 git 提交 7ec2af58。
- **下一步**：迭代 45 收尾——反哺点七条落文（architecture 六条现状化＋run_all_gates 02 关联档多套件词传参工具登记）、产出物五件退役（两报告/反哺点/审计/两停机呈报＋两卡＋两设计文档）、roadmap 迭代 45 行与当前位换代、worktree 两件清理（iter45＋assert-slim-b2，均已合并）；随后棋盘格边长口径收口卡（已写卡零待裁点）与换图系双基座七件卡（2026-10-31 已写卡）入编排。待编池：营地交互重做卡⑤（排卡④之后）、卡④（美术设计已闭合＝样张过审 2026-10-31＋art-bible v3.24 §6.2，待用户发令重立卡）、冒险前资源配比预设（冻结备选）、迭代 30 原卡②③（2026-10-17 已剔出迭代 30 规划、退回待设计，待美术／设计定稿后重新立卡）。
## 里程碑时间线
@@ -77,7 +77,7 @@
| 迭代 41 | 已完成（2026-10-29） | 已退役（git 历史可考） | 2026-10-27 | ≈13.15 个工作日〔用户特批 2026-10-27 超 10 个工作日〕 | 已退役（git 历史可考） |
| 迭代 42 | 已完成（2026-10-29） | 已退役（git 历史可考） | 2026-10-29 | ≈5.375 个工作日 | 已退役（git 历史可考） |
| 迭代 43 | 已完成（2026-10-30） | 已退役（git 历史可考） | 2026-10-29 | ≈6.5 个工作日 | 已退役（git 历史可考） |
| 迭代 44 | 待开工 | reports/需求卡片-组合根注册面批-2026-10-29.md<br>reports/需求卡片-战斗编排归约批-2026-10-29.md<br>reports/需求卡片-测速循环批-2026-10-29.md | 2026-10-29 | ≈7.875 个工作日 | — |
| 迭代 44 | 已完成（2026-10-30） | 已退役（git 历史可考） | 2026-10-29 | ≈7.875 个工作日 | 已退役（git 历史可考） |
| 迭代 45 | 待开工 | reports/需求卡片-呈现层状态件批-2026-10-29.md<br>reports/需求卡片-gdstyle尾波补件批-2026-10-29.md | 2026-10-29 | ≈7 个工作日 | — |
- 迭代 38 收口为带红合并〔用户特批 2026-10-26〕：09 静态扫描 S13 gdstyle 恶化 2 条经批准记入基线存量红（git 提交 c4c69701），卡② 停卡退上游，处方已于 2026-10-26 修订定稿 v1.3（git 提交 b3ea7532），随「gdstyle 存量债全量清偿」条目波 7 待编排。
tools/gdstyle_baseline.txt
+3 -14
View File
@@ -5,19 +5,8 @@
# 判定＝键不在基线红（NEW）、同键数值较登记值恶化红（WORSENED）、改小/持平不红。
# 重生成＝人工专用：python tools/gdstyle_gate.py --refresh（禁清基线换绿；改规则口径/工具升级须随批
# 重生成；新键数较旧基线少逾 10% 须加 --force 显式确认）。
game/core/adventure_runner.gd|quality/max-class-variables = 28
game/core/battle_orchestrator.gd|quality/max-class-variables = 38
game/core/battle_orchestrator.gd|quality/max-file-length = 1035
game/core/adventure_runner.gd|quality/max-class-variables = 23
game/core/level_runner.gd|quality/max-class-variables = 30
game/core/level_runner.gd|quality/max-public-methods = 50
game/core/level_runner.gd|quality/max-returns|_enter_node = 7
game/presentation/main.gd|quality/max-class-variables = 49
game/presentation/tune_sim_controller.gd|quality/await-in-loop|'await' used inside a loop
game/presentation/views/board_cell_unit.gd|quality/max-class-variables = 30
game/presentation/views/board_view.gd|quality/allocation-in-loop|object allocation '.new()' inside a loop
game/presentation/views/board_view.gd|quality/max-branches|_paint_cell = 24
game/presentation/views/board_view.gd|quality/max-class-variables = 32
game/presentation/views/board_view.gd|quality/max-function-length|_paint_cell = 139
game/presentation/views/board_view.gd|quality/max-local-variables|_paint_cell = 22
game/core/level_runner.gd|quality/max-public-methods = 33
game/presentation/views/board_view.gd|quality/max-class-variables = 31
game/presentation/views/board_view.gd|quality/max-public-methods = 27
game/presentation/views/standee_body.gd|quality/max-class-variables = 19
体验验证清单.md
+12
View File
@@ -492,3 +492,15 @@
- **红灯信号**：气质否决（压抑/抢焦/看台感不成立）、任一定值前后不可辨或微光混读即报缺陷回炉。
- **结论回流**：呈现缺陷归待办清单登记新条目；目检通过＝样张整体过闸，art-bible §1.4 与战斗表现.md 的过闸状态随之换代。
## ㊷ 迭代 44——组合根注册面＋战斗编排归约＋测速循环三卡实机目检（2026-10-31 随批后收尾登记）
> 三卡合回（2026-10-30，git 提交 bee73db5）：卡① 组合根注册面批（ui_registry＋三域容器建件，main.gd 类变量 49→15，全消费面改址 main.ui.*）＋卡② 战斗编排归约批（RoundCycle/BattleFacts 两新件，宿主 38→15）＋卡③ 测速循环批 v1.1（信号步进状态机消循环内 await）。三卡均为行为零变化批，独立验收审计通过（可合并）；判读口径全部＝「与改前一致」。登记不阻塞（2026-10-12 真人检测立规）；机检读数与论证详见实现报告（git 提交 bee73db5 一线可考）。
| # | 目检项 | 判据 |
|---|---|---|
| 1 | 三屏切换与模态开合实机过一遍（卡① 验收闭合义务——冒烟/探针/golden 已机检承载，真人观感复核） | 主菜单/营地/战斗三屏切换与各模态开合正常、遮挡关系正确，与改前一致 |
| 2 | 战斗一局全流程观感（卡② 结构迁移零行为变化的一般性目检） | 一整局战斗各段（挖掘/战斗/结算/三选一/奖励）演出与读数与改前一致 |
- **红灯信号**：任一屏/浮层错位、交互无响应或演出读数与改前不一致即报缺陷。
- **结论回流**：呈现缺陷归待办清单登记新条目。
待办清单.md
+15 -24
View File
@@ -77,21 +77,26 @@
**状态**：文档设计已闭合＋已写卡＋已编迭代 45
#### 零豁免五键清偿批——S13 余量五键真修四卡（2026-10-29 登记，来源=会话提及）
#### 战斗域结构深拆批——效果发射端口＋掷格/受理分件（2026-10-31 重立，来源=批次移交）
**实况**：用户 2026-10-29 裁「不允许任何豁免」——S13 三条豁免注销（architecture.md v1.25 落文），五键真实修复至阈值内：main.gd 类变量 49→15（组合根注册面：ui_registry 一门面＋三域容器，约 867 处探针/系统测试引用改址 `main.ui.<域>.<句柄>`，7 别名/转发成员消灭）／battle_orchestrator 类变量 38→15（RoundCycle＋BattleFacts 两件，叠加迭代 42 轴丙 BoardInstaller；encounter 归 BattleFacts、attune 改判状态两成员随件）／board_cell_unit 类变量 30→10＋standee_body 类变量 19→10（各拆两独立文件，gdstyle inner-class 展平计数口径）／tune_sim 循环内 await 消除（process_frame 信号步进状态机；**零行为改动**——v1.0 申报的收尾置假还原已被迭代 41 测试债批 215da315 先行完成并申报，2026-10-30 实现段按卡片预设停机点停卡、三重证据定谳前提已消化，按停卡呈报建议案重裁剥离行为改动申报：iter44 worktree 分支 reports/iter44-实现报告-2026-10-30.md §5）。设计闭合凭据＝architecture.md v1.25＋五份设计文档（reports/ 下五件 设计-组合根注册面-2026-10-29.md／设计-战斗编排类变量归约-2026-10-29.md／设计-单格绘制状态件-2026-10-29.md／设计-站桩状态件-2026-10-29.md／设计-测速循环去await-2026-10-29.md）。四卡已成文（均零待裁点开工门 U0；测速循环批卡 2026-10-30 停卡重裁 v1.1——前提消化后剥离行为改动申报、T0 改现状复核、夹具申报差异两处减一处，仍零待裁点）：
**实况**：本条为 2026-10-27 原条目的重立版（原条目含宿主瘦身子项，该子项完成后随净零重立一并出清，git 历史可考）。三条同病根的结构债，需先一次设计讨论定端口形态，再谈切卡；`RewardEconomy` 的最小缝拆样本已由迭代 40 卡② 落卡。**宿主瘦身子项已完成（2026-10-30 随迭代 44 卡② 战斗编排归约批合回，合并提交 bee73db5——RoundCycle/BattleFacts 两新件建件，宿主实测 15 类变量/811 行，验收审计通过；原需求卡片与设计过程稿已按吸收即死退役，git 历史可考）。**
- 效果发射端口（设计题本体）：`game/core/damage_controller.gd:46/47/71` 与 `game/core/action_economy.gd:44/45/50` 仍直持 `EffectEngine`＋`EffectContext`——前者用 attack_commit/armor_roll/clamp_check/kill/damage_taken 五枚事件并带计数器读写回写（:348/:354），后者用 dig_paid/dig_stop/charge_full 三枚事件。`RewardEconomy` 同款直连已由迭代 40 卡② p5 缝拆实装合回（单枚查询口 `luck_bias_query`——成员 −2＋2、类变量净 15、判定归 `BattleFxHost.luck_bias_for`），最小样本在库可考；另两处事件多且带计数器回写，缝拆不成立，必须先设计「业务类只持一个回调、取回命中批」的端口形态。
- reward_economy 分件：`RewardEconomy` 现 15 类变量恰在阈值线上（加第 16 枚即出闸 09 新增红——迭代 40 卡② 施工实测撞见，正是本条登记起因），掷格面（install 期 roll／池行装配／权重合成）与受理账面（grant／身份查询／快照／retire）两职责同居一件。
- 相关文档：design/engineering/architecture/architecture.md（系统分层图与功能层 B1/B4 行、「战斗编排域拆件定稿」节须随端口定稿改写）· reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md（216 键波次方案与残留债口径；在册「尾波」只覆盖迭代 39 三宿主，不含本条）· 结构小件定点修批卡已随迭代 40 合回退役（git 历史可考，合并提交 514457d1；缝拆样本与 2026-10-27 用户裁史见该卡 git 版本）
关联文档清单：
- 组合根注册面批 reports/需求卡片-组合根注册面批-2026-10-29.md
- 呈现层状态件批 reports/需求卡片-呈现层状态件批-2026-10-29.md（单格＋站桩两设计并一卡）
- 测速循环批 reports/需求卡片-测速循环批-2026-10-29.md（v1.1，2026-10-30 停卡重裁）
- 战斗编排归约批 reports/需求卡片-战斗编排归约批-2026-10-29.md（接收方＝在册条目「战斗域结构深拆批」宿主瘦身子项，不在本条目记账）
编队待迭代 42 合回（battle_orchestrator／board_view 触面碰撞约束），具体迭代归属归编排段；编入前置＝各卡过 grilling 复核门。gdstyle inner-class 计数截断缺陷已在册（architecture v1.25）——基线登记值欠估，各批按真实口径施工；各批全部合回后一次人工 --refresh --force 收账（一并清迭代 42 归绿 6 键离账——批末实测已归绿而基线仍记 16 键：board_view 四键＋level_runner `_enter_node`＋battle_orchestrator 文件长；各留债键按重锚时实测重登记，冻结禁恶化口径不变）。2026-10-29 编排（用户裁编法）：卡 A 组合根注册面批＋卡 B 战斗编排归约批＋卡 D 测速循环批编入**迭代 44**（≈7.875 个工作日，中值合计）；卡 C 呈现层状态件批编入**迭代 45**（与补件批同批，卡 C 先于其 board_hover 半边施工）。grilling 复核门已过（reports/复核-grilling-零豁免五卡-2026-10-29.md，五卡有条件成立、修正全落，提交 9855bf0a）。
**缺口**：效果发射端口形态未定稿（一枚回调的束形与返回值、计数器读写回写与 facts 取值的归属面、`bias_rewards` 等域词汇是否留在宿主层、是否与 `BattleFxHost` 同件承载）；宿主保留面与掷格件的职责边界（哪些成员随件迁出、件怎么切）未裁定——需一次设计讨论并落 architecture.md 后才能写卡。
**改动面**：游戏代码
**状态**：文档设计已闭合＋已写卡＋已编迭代 44＋已编迭代 45
**状态**：待文档设计
#### main.gd 拆件遗留死 preload 清理（2026-10-31 登记，来源=批次移交）
**实况**：证据＝iter44 反哺点 11（已按吸收即死退役，git 历史可考；实现报告实现决定记录同载）——迭代 44 卡① 组合根注册面批拆件后，main.gd 遗留零使用 preload 常量 8 条（UiAssembler／TuneSimController／DebugSessionScript／TreasureInteractController／CurioInteractController／CampShopPresenter／BoardResolversScript／三场景 preload 中 main 零使用者三件）；卡① 施工时仅清理与迁移直接相关的 ModalStack/RowPacer 两条，其余属存量债不扩范围，归工程改动直改批顺路清理。清理前须逐条 grep 复核零使用（布局批与 iter45 合回后消费面或有变化）。
**改动面**：游戏代码
**状态**：待执行
#### 数值标定窗口总挂账——原九条数值类条目合并（2026-10-28 登记，来源=会话提及）
@@ -107,20 +112,6 @@
**状态**：待文档设计
#### 战斗域结构深拆批——效果发射端口＋宿主瘦身＋掷格/受理分件（2026-10-27 登记，来源=批次移交）
**实况**：三条同病根的结构债，需先一次设计讨论定端口形态，再谈切卡；`RewardEconomy` 的最小缝拆样本已由迭代 40 卡② 落卡。
- 效果发射端口（设计题本体）：`game/core/damage_controller.gd:46/47/71` 与 `game/core/action_economy.gd:44/45/50` 仍直持 `EffectEngine`＋`EffectContext`——前者用 attack_commit/armor_roll/clamp_check/kill/damage_taken 五枚事件并带计数器读写回写（:348/:354），后者用 dig_paid/dig_stop/charge_full 三枚事件。`RewardEconomy` 同款直连已由迭代 40 卡② p5 缝拆实装合回（单枚查询口 `luck_bias_query`——成员 −2＋2、类变量净 15、判定归 `BattleFxHost.luck_bias_for`），最小样本在库可考；另两处事件多且带计数器回写，缝拆不成立，必须先设计「业务类只持一个回调、取回命中批」的端口形态。
- battle_orchestrator 瘦身：迭代 40 卡① 拆出 `BattleFxHost`／`RewardGrant` 后宿主实测 38 类变量（阈值 15；豁免第三条已顺带落 architecture v1.22 S13 豁免登记——豁免不等于了结），`tools/gdstyle_baseline.txt` 在册 `game/core/battle_orchestrator.gd|quality/max-class-variables = 38` 与 `|quality/max-file-length = 1037` 两键（已随 2026-10-28 波 0 刷新按实测重锚）。**2026-10-29 承接更新（本子项已写卡并编入迭代 44）**：设计闭合＝architecture.md v1.25 轴丁（RoundCycle/BattleFacts 两新件，S13 豁免第三条注销——零豁免裁）＋reports/设计-战斗编排类变量归约-2026-10-29.md；需求卡片：reports/需求卡片-战斗编排归约批-2026-10-29.md（v1.0 定稿零待裁点，grilling 复核过，编队前置＝迭代 42 合回）；本子项子目标＝38→15，文件长键已由轴丙归绿。本条目其余两子项（效果发射端口／reward_economy 分件）仍待文档设计——下方状态行的「已写卡＋已编迭代 44」两段专指本子项。
- reward_economy 分件：`RewardEconomy` 现 15 类变量恰在阈值线上（加第 16 枚即出闸 09 新增红——迭代 40 卡② 施工实测撞见，正是本条登记起因），掷格面（install 期 roll／池行装配／权重合成）与受理账面（grant／身份查询／快照／retire）两职责同居一件。
- 相关文档：design/engineering/architecture/architecture.md（系统分层图与功能层 B1/B4 行、「战斗编排域拆件定稿」节须随端口定稿改写）· reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md（216 键波次方案与残留债口径；在册「尾波」只覆盖迭代 39 三宿主，不含本条）· 结构小件定点修批卡已随迭代 40 合回退役（git 历史可考，合并提交 514457d1；缝拆样本与 2026-10-27 用户裁史见该卡 git 版本）
**缺口**：效果发射端口形态未定稿（一枚回调的束形与返回值、计数器读写回写与 facts 取值的归属面、`bias_rewards` 等域词汇是否留在宿主层、是否与 `BattleFxHost` 同件承载）；宿主保留面与掷格件的职责边界（哪些成员随件迁出、件怎么切）未裁定——需一次设计讨论并落 architecture.md 后才能写卡。
**改动面**：游戏代码
**状态**：待文档设计＋已写卡＋已编迭代 44
#### 超预算图策略升级路径——等比缩放与滚动视口两案待裁（2026-10-24 登记，来源=批次移交）
**实况**：迭代 34 卡④（信息迷雾可见性批，已合回 master，提交 16a7ec80）按「参数限图」交付，图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图，两条升级路径都要动冻结件，均未设计：①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值；②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13，已超出该上限（level-map 已登记随动缺口，本批不裁方案）。