diff --git a/.gitignore b/.gitignore index cbbe51f1..ef6a5961 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,9 @@ # 导入元数据 *.import +# 代码面 worktree 的 Godot user 目录隔离件（tools/setup_worktree_userdir.sh 生成；主区不生成） +game/override.cfg + # 导出构建产物 builds/ exports/ diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index 005cdb3c..b283a23b 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,8 +2,8 @@ ## 文档状态 -- 版本：1.16 -- 最近更新：2026-10-26（AdventureRunner 真拆分设计定稿——核心层三新件行（HeroLedger/AttuneLoadout/CurioStop）＋「冒险域拆分定稿」节） +- 版本：1.19 +- 最近更新：2026-10-27（gdstyle 存量债全清设计补课——ConfigDB 访问器归位与域容器持有＋SlotStore/MetaStateStore 拆件＋组合根句柄面与测量面两处 S13 豁免登记） - 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定） - 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调） - 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准） @@ -85,7 +85,9 @@ | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| -| **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机 | 类型化属性读取；`load_tables(root, collect_only)`；`resolve()`（R1 floor）；debug override；`set_reload_gate()`；诊断收集器 | 无（基础层顶点） | Resource/.tres 加载、autoload 生命周期——LOW | +| **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机。**2026-10-27 全清设计定稿：行族访问器归位各 schema 表类（表管自己的行查询），本类只留加载/校验/override/诊断门面（≤20）；表持有成员按域收进域容器 Resource（分组建档于实现卡，消费方改址随该批）**——红线不变：本类仍是唯一加载与持有单点，"经 ConfigDB 单点读取"＝经其持有的表对象 | 类型化域容器属性（每域一张容器）；`load_tables(root, collect_only)`；诊断门面；`set_reload_gate()`；`reload` | 无（基础层顶点） | Resource/.tres 加载、autoload 生命周期——LOW | +| **SlotStore**（`core/slot_store.gd`，D3 存档槽位域件，2026-10-27 全清设计定稿——实现批建件） | 存档三槽位文件域唯一所有者（自 save_manager 收编槽位族）：槽位挂载与模板、激活与建删、槽位摘要窥视（peek 族） | 槽位读写原语族＋摘要投影（SaveManager 与菜单消费方直连） | save_manager（注入路径与模板配置）；FileAccess——LOW | +| **MetaStateStore**（`core/meta_state_store.gd`，D3 存档内元进度数据件，2026-10-27 全清设计定稿——实现批建件） | 存档内元进度数据的读写唯一层（自 save_manager 收编 accessor 族：钥石/道具解锁/树节点与叉侧/锻造路线/同调/真视/计数器/摘要——数据读写原语，不含业务规则）；save_manager 与 meta_progression 双 God Class 的共同病根＝该数据域摊在两文件，本件即其归一 | 数据读写原语族＋只读投影（MetaProgression 业务层与营地/锻造 UI 消费方直连；meta 的纯转发读方法随件退役） | save_manager（序列化接线）；FileAccess——LOW | | **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流词表现值以 `RngServiceCore.PURPOSE_TAGS` 为准；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 | | **action_economy**（A3） | AP/RAP 账本、last_round_end、轮次相位机 {Idle, Active, Waiting}、结束仲裁 | 意图与通知布尔面：notify_round_start / request_dig / request_stop / request_refresh / notify_settlement_done / notify_combat_end；预授权通道：grant_reserve_ap / finish_round_stop；ap/rap/phase 只读 | ConfigDB（ActionEconomyTable）；effect_engine（事件发射 dispatch——基础层内同层引用）；B1 回发 next_round_mode/battle_over | 无 | | **variation 定义**（A4） | VariationTable schema（现行 6 行：六 region——贫矿脉 global 行 2026-10-16 用户令屏蔽删行，global 型机制代码保留）与 F1 候选池门控谓词 | `variant_pool(level_index, board_type, node_type="")`（门控三维：unlock+board_types+节点身份——global 行仅 boss/elite 入池，缺省跳过零扰动）；`global_variant_row(level_index, board_type, node_type)`（全局型单行决议访问器） | ConfigDB（VariationTable） | 无 | @@ -113,19 +115,32 @@ | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| -| **battle_orchestrator**（B1） | 段序骨架（七段结构冻结）、轮 facts 缓冲、可回放步骤流、[明细行协议](../../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)（基础行型＋扩展行两层 + 字段分层，词表以 owner「明细流水」节为准）、条款③⑤闭合对账、**战斗域全部跨系统调用权**、效果引擎宿主（每战 rebuild；round/battle 桶为编排器自有字典、经 EffectContext 引用挂载）+ 树规则挂点施加面（posture 窗/sense 限次/守侧 seal_missed 发射/聚乘算入账前） | `begin_battle(encounter)`；窗口/刷新意图提交面（扮演 D1）；`level_clear()`；步骤流（输出契约） | B2/B3/B4 全调用面（**唯一调用方＝B1 域文件集：battle_orchestrator.gd ＋ settlement/ 五段段类 ＋ damage_controller**）；A3 request_refresh 代理 + 回发；A2 install/retire + 三事件订阅；A1 generate（attempt 非 scope 事件）；D2 SettlementTable + set_reload_gate | 无（零随机、禁 await——切片 88 冒烟实证可回放） | +| **battle_orchestrator**（B1） | 段序骨架（七段结构冻结）、轮 facts 缓冲、可回放步骤流、[明细行协议](../../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)（基础行型＋扩展行两层 + 字段分层，词表以 owner「明细流水」节为准）、条款③⑤闭合对账、**战斗域全部跨系统调用权**、效果引擎宿主面与树规则挂点施加面（**已定稿拆出 BattleFxHost——本行此段实现批后改写为现状，过渡期以「战斗编排域拆件定稿」节为准**） | `begin_battle(encounter)`；窗口/刷新意图提交面（扮演 D1）；`level_clear()`；步骤流（输出契约） | B2/B3/B4 全调用面（**唯一调用方＝B1 域文件集：battle_orchestrator.gd ＋ settlement/ 五段段类 ＋ damage_controller ＋ 拆件后两新件**）；A3 request_refresh 代理 + 回发；A2 install/retire + 三事件订阅；A1 generate（attempt 非 scope 事件）；D2 SettlementTable + set_reload_gate | 无（零随机、禁 await——切片 88 冒烟实证可回放） | +| **BattleFxHost**（`core/battle_fx_host.gd`，B1 域·效果引擎宿主件，2026-10-26 编排域拆件设计定稿——实现批建件） | 效果引擎挂点施加面唯一承载（自 battle_orchestrator 收编 fx 族）：事件发射与事实判定（_fx_emit/_fx_fact）、主角 AC 基线与本轮/本战 AC 累积、bonus_delta 四轴累积（战末宿主 drain 汇入账本）、揭示待兑队列与兑付（含 _fx_revealing 再入闸——同步信号回环防二次缓冲二次兑付）、树规则合成订阅的 round/battle 桶计数器持有（桶随编排器生灭语义不变） | 构造＝引用束注入（防 _init max-parameters 新键）；bind 时注入 emit Callable（行发射经宿主协议面单点）与兑付 Callable（RewardGrant 授予面——揭示队列 flush 回调）；只读投影分两类消费方：AC 累积/bonus_delta 供宿主呈现快照与战末 drain，揭示态供宿主 A2 订阅旁路判定 | EffectEngine（EffectContext 引用束）；RngServiceCore（fx_reveal 封闭流——除该流外零随机）；A2 minesweeper（板读与 fx_reveal 调用）；A3 action_economy（queue_ap_delta/charge_layers 读）；B3 status_container 读；B2 unit_container 读（hp_ratio）；DamageController（set_hero_ac_override）；ConfigDB；encounter 引用 | 无（零 await——效果引擎全同步解释器） | +| **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 引用束与编排回调） | 无 | | **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 | 无 | | **difficulty**（C3） | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表（切片 monte_carlo 为工具原型） | 调参输出（经 D2 R1 解析/编排器传递，禁反向调用生成） | ConfigDB、B1 对账输出（调参约束清单）、A1 报告 C | 无 | -| **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEYS 六键/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编） | tree_can_buy/tree_buy/tree_buy_fork/tree_toggle_fork（写口唯一）、hero_override 注入（树淬炼 flat+锻造路线加值位预留 0）、tree_rule_keys | D3、C2、ConfigDB | 无 | +| **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEYS 六键/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编）。**2026-10-27 全清设计定稿：存档内元进度数据读写原语归 MetaStateStore（新件），本类纯转发读方法随件退役（消费方直连 store），业务规则与写口编排留本类（≤20）** | tree_can_buy/tree_buy/tree_buy_fork/tree_toggle_fork（写口唯一）、hero_override 注入（树淬炼 flat+锻造路线加值位预留 0）、tree_rule_keys | D3、C2、ConfigDB | 无 | ### 战斗域装配现状（迭代 27——2026-10-17 用户裁写入） - **结算五段**：B1 编排器的每轮结算序列拆为 `game/core/settlement/` 五个段类——GrantSegment（①授予段，含封印判定与 counter/grant 助手单点）→ AuraSegment（②增益/减益段）→ CombatSegment（③战斗段）→ DecaySegment（④衰减段）→ VerdictSegment（⑤判定段，返回裁定，终局早退语义留 B1）。段序骨架冻结于 `SettlementTable.segment_order` 语义，B1 退为段序编排+接线；段类可直接 `new()` 单测（`settle_segments_test` 在役）。 - **RunLedger 四账**：`game/core/run_ledger.gd` 单类持四本共享账——同调充能账／真视使用计数／冒险域计数器／统一冒险加算区。所有权：AdventureRunner 开局构造、全程唯一宿主；LevelRunner 经 `set_run_ledger` 下传装配 encounter；战斗侧（B1）经 `encounter["ledger"]` 拿引用、只走 read/append 原语族。审计 P1-4「共享可变字典跨三层三处可写」由「函数签名上不可见的共享引用」换成签名可见的显式类。冒险桶计数器无导出/灌入时点：EffectContext 持 `run_ledger.adventure_counters` 的同一字典引用，引擎静态计数口就地直写，跨战持久随 RunLedger 生灭（2026-10-21 迭代 32 卡②无状态化写入）。 +### 战斗编排域拆件定稿（2026-10-26 用户裁写入——gdstyle 存量债波 1 设计闭合；同日独立审查（grilling＋godot-master 双子代理）阻断 8 条去重 6 组全折入本节，v1.18；实现批完成后改写为现状登记） + +- **轴甲两件**：battle_orchestrator（1313 行／50 成员，S13 全库单文件最大户）按变化原因拆出 BattleFxHost（效果引擎宿主域）与 RewardGrant（奖励授予域）两协作件；宿主保留架构在册职责全部——战斗状态机与生命周期、轮 facts 缓冲（_facts_reveals/seals/path）、A2 三事件订阅、结算五段驱动、attune 族原位、行发射基建（_emit_row/_assert_row_source/_fatal）、呈现投影（presentation/diagnostic_snapshot 唯一出口不变）、刷新面、nest_preview_count（巢穴预告读数口——外部直读面 main.gd 与 treasure_effects_test 随批点名冻结）。拆件动机与残留债口径见待办清单「gdstyle 存量债全量清偿」条目。 +- **跨件单向接线**：RewardGrant 持 BattleFxHost 引用（treasure_used 事件发射与计数器消耗）；BattleFxHost 对授予面走 bind 时注入的兑付 Callable（揭示队列 flush 回调）——禁双向强引用（两件均 RefCounted，环引用随每战新建泄漏）。行发射经 bind 时注入的 emit Callable（协议面单点留宿主——CurioDeck bind_handlers 同款先例，禁件回调宿主私有族）；轮 facts 缓冲留宿主、fx 件经注入取值；_seal_consumed 留宿主（与 A2 seal_judged 订阅同域）；fatal 经注入 Callable 转宿主 _fatal（battle_result 状态机唯一写点不变）。 +- **settlement/ 段类随动**：段类构造注入直持宿主＋两新件三引用（Middle Man 禁令封转发壳——调用点改指），授予段读写面点名：_grant_routed×5／_submit×6／escrow 写／_fx_new_resource_types／_feat_first_dig_used／_fx_bonus_delta 写／_apply_ac_bonus／_fx_enqueue_reveal／_flush_pending_reveals／_grant_clear_reward／counters_ctx；战斗段 _defer_board_damage 复位与 _deferred_board 结账改指 RewardGrant。四个授予段 helper（_feat_yield_adjust/_harmful_variants/_harmful_adjacent/_hits_of）与 _pool_effective/perfect_sweep_earned 留宿主（段类经宿主引用直调，现状形态）。 +- **attune 族原位保留**：同调配装 8 成员不进新件——迭代 39 副卡（AttuneLoadout 充能单源化）语义领地，两批零冲突；本波残留债归尾波。RewardGrant 经宿主 attune 读投影取 _attune_safe_seen。 +- **呈现零变化**：两快照出口签名与载荷逐字不变，内部改读两件只读投影（快照本体不读揭示态——揭示态投影消费方＝宿主 A2 订阅旁路判定）；treasure_interact_controller 三触点分家——use_treasure 经组合根现值回调改注 RewardGrant（每战新建编排器，禁一次性直引防悬挂），minesweeper 读与 attune_convert_state 仍走宿主取值回调（双取值面）；nest_preview_count 直读面零变化。 +- **S13 键账收敛义务**：12 个超标键随函数迁入新文件＝基线外 NEW（use_treasure 长度/分支/局部/返回×4、_grant_routed 参数 8、_dispatch_row 参数 6、_apply_percent_row 参数 6、_apply_gp_row 参数 6、_apply_flat_row 参数 7＋返回 9、_submit_flat_hero 参数 7、_fx_fact 返回 7）——卡内同步收敛为本波义务（_grant_routed 等签名随引用束注入改形、use_treasure 体拆分），禁波 0 合并 refresh 吸收新文件未还键；新件 _init 引用束注入防 max-parameters 新键。 +- **验收红线**：游戏行为零变化（RNG 消费序零漂移——fx_reveal 封闭流随件迁移取号序不变、信号顺序契约冻结、明细行协议词表零触碰、同种子逐位一致）；battle_orchestrator 头注发射点指址随拆件改写（词表不动，指址须真）；行数恶化债清偿义务（迭代 38 特批带红合并挂账 c4c69701——本波还债归绿）；PARITY 触面（battle_orchestrator.gd 被改）实跑对拍须经用户批准、不得借机重锚；S13 改善非清零口径（宿主残留 8–10 键＋随迁键卡内收敛后新件零残留为达标线）。 +- **S7/S8 随动**：RewardGrant 调 B4 API，两新件一并登记进 S7 B1 域文件集与 S8 结算路径 await 文件集（static_scan.sh 两清单独立、同批更新——防 await 面漏闸）。 + ### 冒险域拆分定稿（2026-10-26 用户裁写入——AdventureRunner 真拆分设计闭合；实现批完成后本节改写为现状登记） - **应用层形态**：adventure_runner 退出上帝对象、转薄应用层（DDD 应用层形态）——只留冒险状态机、关序推进、结算受理、建件接线、效果引擎冒险桶字典持有（桶＝效果引擎域数据，应用层只锚定生命周期）；零领域决策。核心层表三新件行（HeroLedger／AttuneLoadout／CurioStop）即本拆分目标。 @@ -165,7 +180,7 @@ ### 三屏壳与组合根句柄面 - 呈现场景拆为三屏壳：MenuScreen（开始菜单屏）／CampScreen（营地屏）／AdventureScreen（冒险屏——内含关卡地图与战斗两容器）。 -- 屏成员经组合根 main.gd 一级句柄暴露（探针挂载假设 `main.X` 路径零迁移）；局态一律住 RunScope 节点，禁在屏/视图侧持有局态引用。 +- 屏成员经组合根 main.gd 一级句柄暴露（探针挂载假设 `main.X` 路径零迁移；**S13 豁免登记 2026-10-27：组合根类变量面即探针契约面——约 46 个句柄成员被探针挂载假设钉死，max-class-variables 对本件按架构契约豁免（键永久基线内、禁再恶化），豁免理由在册本节，禁为清键改写探针挂载契约**）；局态一律住 RunScope 节点，禁在屏/视图侧持有局态引用。 - **组合根拆件**＝组合根构造注入、代组合根执行核心写调用的呈现侧子件（现行三件：curio_interact_controller／camp_shop_presenter／treasure_interact_controller——冒险节点后续推进、营地购买与刷新、道具使用）。视图禁直连拆件；核心写调用的可达路径仍是「视图→信号→组合根（含拆件）→核心」，依赖规则与组合根单点装配不变。成员见「模块归属·呈现层」表。 ### 视觉层装配合同 @@ -293,6 +308,8 @@ 本节为测试域（测试载体、判定口径、静态扫描域）的事实源。新增违规案例仍须先补 static_scan 规则再修码（code-conventions 缺陷-规范对照表纪律）。 +**S13 测量面豁免登记（2026-10-27）**：`game/presentation/tune_sim_controller.gd` 的循环内 `await`（测速循环逐帧让出）是调参测量的 wall-clock 步进承载语义——重构即测量口径漂移，违行为零变化红线。该键按架构豁免（键永久基线内），豁免理由在册本段；同件 `print` 残留不豁免（信息已由 toast/JSONL 承载，随全清批删除）。 + --- ## 数据流 diff --git a/design/engineering/process-conventions.md b/design/engineering/process-conventions.md index fae1a3b2..06bb9523 100644 --- a/design/engineering/process-conventions.md +++ b/design/engineering/process-conventions.md @@ -9,7 +9,7 @@ 改动按文件性质分两车道（2026-10-26 用户裁，取代 2026-09-19 立的「一切改动走 worktree」铁律；判据与 §3 第 8 条改动域划分同一）： -1. **worktree 批车道（唯一强制面＝代码面）**：一切触及代码面（`game/` 下非 `.md` 的行为载体：代码、测试脚本、探针、场景、数据表、素材）的改动——迭代实现批与触及代码面的工程改动（如纯测试维护）——先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）。迭代批开工细则见 §3 与 iter 技能 +1. **worktree 批车道（唯一强制面＝代码面）**：一切触及代码面（`game/` 下非 `.md` 的行为载体：代码、测试脚本、探针、场景、数据表、素材）的改动——迭代实现批与触及代码面的工程改动（如纯测试维护）——先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）；建区后立刻跑 `tools/setup_worktree_userdir.sh`——给该区独立 Godot user 目录（测试夹具、试玩日志、截图产物不与其他区共用；主区不生成，真实档保持原位）。迭代批开工细则见 §3 与 iter 技能 2. **worktree 批收尾**：批次收口顺序固定为**冻结 → 件核 → 并 master → 跑一次域闸 → 合回**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先 `git merge master` 解冲突（必须在跑闸之前，闸跑完再并＝那次闸白跑），然后按本批改动域跑**一次** `tools/run_all_gates.sh`（见 §3.9），全绿后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支。闸后代码面不得再改一个字节（回执作废须重跑），只允许追加 `reports/`、`design/` 等文档件提交。游戏类测试（冒烟/单测/MC/探针）批内默认零执行（两入口铁规，见 §4），用户点名或当场问才跑 3. **直改车道（代码面之外的一切面）**：`design/`、`reports/`、`tools/`、根规则与清单文件、`game/` 内 `.md`、`.zcode/`、`.qoder/`——主工作区直接改、直接提交，无 worktree、无冻结/件核/合并仪式。验收＝commit 点 git pre-commit 钩子（`tools/hooks/pre-commit`，经 `core.hooksPath` 挂载，在位性由 run_all_gates.sh 跑批自检）现场跑 `tools/run_all_gates.sh --docs`（秒级文本扫描）：绿即落地，红即拦下，修红后重新 commit 钩子自动重跑；跑完把闸输出呈报对话即完成义务。预期大体量改动（跨文档结构重构等）时由用户开工点名自愿开 worktree，非规则强制 4. **执法分层（全机械，零自觉依赖）**：①git pre-commit 钩子——直改车道的闸机检，并对主工作区直提代码面的提交一律拦（代码面唯一合法路径＝worktree 批合回）；任务 worktree 内的代码面提交跳过（归批末闸＋合回闸管，不打扰迭代批中间提交）。②`.zcode/hooks/worktree-guard.sh`（PreToolUse，本机件不入 git）——agent 侧：主工作区代码面的 Edit/Write 与 staged 含代码面的 commit 拦截、`git commit --no-verify` 拦截（该旗标仅属用户）、合回闸回执六况校验（§3.9）。git 层钩子对一切提交者生效（含用户手工提交，紧急出口 `--no-verify`）；ZCode 层只约束 agent @@ -40,7 +40,7 @@ 3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工 **环境与基线** -4. **代码面批独立 worktree＋拷导入缓存**——触及代码面的批次按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则）；直改车道（非代码面）无此项 +4. **代码面批独立 worktree＋拷导入缓存**——触及代码面的批次按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则）；闸壳每次跑批先自检/自愈本区 user 目录隔离（§1 第 1 条），建不起来即拒跑；直改车道（非代码面）无此项 5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟 **实施** diff --git a/game/tests/.gates/baseline.json b/game/tests/.gates/baseline.json index 6ec1962d..ee6cfbe8 100644 --- a/game/tests/.gates/baseline.json +++ b/game/tests/.gates/baseline.json @@ -1,5 +1,5 @@ { - "note": "存量基线·首次自动生成；闸况变化时本脚本会判红，需人工确认后重生成；2026-10-17 人工确认重生成 06 条目：af94ce97 把 gdd_lint 记为存量红（01 篇 R5），该红已由 fcb8c3f8 补流程图消除，实测 --docs 域 06 exit=0，故基线改回绿。2026-10-18 新增闸件 08c 流水线闸（tools/pipeline_gate.py 注册上电），手工加入绿记录（roadmap 压缩批实测 --docs 域 exit=0），其余条目原样保留。2026-10-22 测试术语与层级重构批 A 改键：01 冒烟全量→01 系统测试（同一断言面 smoke_all.gd，运行器换 tools/run_system_test.py，过渡期判定口径不变）、02 单元套件→02 单元与集成测试（同一 run_all.gd 入口，名从实）、新增 00 冒烟测试（tools/run_smoke.py＋game/tests/smoke_boot.tscn，重写后单跑实测 17 项 0 失败 PASS）；09 静态扫描基线 exit=1（fp=4354b2aa72a7）系滞后红，本批单跑实测 exit=0（与 2026-10-22 16:20 回执一致），基线改回绿；其余条目原样保留。；2026-10-23 主会话记 07 doc_link 为存量红（用户令忽略：锻造工坊.md 死链的修复在另一会话未合入，合回闸豁免；外部修复合入后应重生成基线归绿）；2026-10-26 用户特批带红合并（迭代 38 收口）：09 静态扫描记存量红——gdstyle 恶化 2 条（battle_orchestrator.gd max-file-length 1314>1302＝卡④头注必载内容、level_map_screen.gd max-class-variables 22>21＝卡①缓存成员，均为卡片义务的记账漂移非缺陷，压缩还债经计算不可行），用户裁「不管引入的恶化直接提交、特许免测试重跑」；后续批次若触及两文件可顺带还债或经批准重生成基线归绿", + "note": "存量基线·首次自动生成；闸况变化时本脚本会判红，需人工确认后重生成；2026-10-17 人工确认重生成 06 条目：af94ce97 把 gdd_lint 记为存量红（01 篇 R5），该红已由 fcb8c3f8 补流程图消除，实测 --docs 域 06 exit=0，故基线改回绿。2026-10-18 新增闸件 08c 流水线闸（tools/pipeline_gate.py 注册上电），手工加入绿记录（roadmap 压缩批实测 --docs 域 exit=0），其余条目原样保留。2026-10-22 测试术语与层级重构批 A 改键：01 冒烟全量→01 系统测试（同一断言面 smoke_all.gd，运行器换 tools/run_system_test.py，过渡期判定口径不变）、02 单元套件→02 单元与集成测试（同一 run_all.gd 入口，名从实）、新增 00 冒烟测试（tools/run_smoke.py＋game/tests/smoke_boot.tscn，重写后单跑实测 17 项 0 失败 PASS）；09 静态扫描基线 exit=1（fp=4354b2aa72a7）系滞后红，本批单跑实测 exit=0（与 2026-10-22 16:20 回执一致），基线改回绿；其余条目原样保留。；2026-10-23 主会话记 07 doc_link 为存量红（用户令忽略：锻造工坊.md 死链的修复在另一会话未合入，合回闸豁免；外部修复合入后应重生成基线归绿）；2026-10-26 用户特批带红合并（迭代 38 收口）：09 静态扫描记存量红——gdstyle 恶化 2 条（battle_orchestrator.gd max-file-length 1314>1302＝卡④头注必载内容、level_map_screen.gd max-class-variables 22>21＝卡①缓存成员，均为卡片义务的记账漂移非缺陷，压缩还债经计算不可行），用户裁「不管引入的恶化直接提交、特许免测试重跑」；后续批次若触及两文件可顺带还债或经批准重生成基线归绿；2026-10-27 用户裁「标准是尺、不以现状为尺」：09 存量红照实记（exit=1＋现行红项指纹，两条恶化各自点名可核），gdstyle 基线登记值回退 1302/21（波 0 的 18 条陈旧键清理保留），gdstyle_gate 逐条违规行加 FAIL 前缀并加「refresh 禁抬高登记值」守卫——存量红期间任何新增违规或进一步恶化都会改指纹被拦；阈值口径不变＝gdstyle 默认值（文件 1000 行／类变量 15 等），还债归迭代 40 卡①（battle_orchestrator 1314→≤1000）与迭代 41 卡③（level_map_screen 22→≤15），还清后重新生成基线归绿", "gates": { "00 冒烟测试": { "exit": "0", @@ -47,7 +47,7 @@ }, "09 静态扫描": { "exit": "1", - "fp": "user-approved-iter38" + "fp": "91d45583cf6d" }, "10 熵增闸": { "exit": "0", diff --git a/game/tests/static_scan.sh b/game/tests/static_scan.sh index 76c5ce99..3897a193 100644 --- a/game/tests/static_scan.sh +++ b/game/tests/static_scan.sh @@ -291,8 +291,10 @@ fi # probe/sim/tests 测量面直构惯例不在面）。存量基线 tools/gdstyle_baseline.txt 用稳定身份键（函数级带数 # 条目＝文件|规则|函数名，类级/文件级带数条目＝文件|规则，均带登记数值；无数字条目＝文件|规则|消息全文 # 裸键）——消息里的行数/分支数等计数漂移不假红；判定＝基线外新违规红（NEW）＋同键指标较登记值恶化红 -# （WORSENED），改小/持平不红。基线重生成＝人工专用（python tools/gdstyle_gate.py --refresh，附对账； -# 键数骤降逾 10% 须 --force），禁清基线换绿。二进制本机固定路径 +# （WORSENED），改小/持平不红；逐条违规行带 FAIL 前缀，使存量红期间的红项清单（哪几条、恶化到多少） +# 进 gate 09 指纹，新增或进一步恶化不会被「同款存量红」放过。阈值口径＝gdstyle 默认值；基线只是欠账 +# 簿，登记值只准随还债下降，禁抬高到现状。基线重生成＝人工专用（python tools/gdstyle_gate.py +# --refresh，附对账；键数骤降逾 10% 或登记值被抬高均拒写，须 --force），禁清基线换绿。二进制本机固定路径 # D:/code/gdstyle/gdstyle.exe（不入库），GDSTYLE_BIN 环境变量覆盖；版本与钉定版不符即红（升级须重测）。 if python tools/gdstyle_gate.py; then echo "[static_scan] S13 ok" diff --git a/game/tests/system_test.gd b/game/tests/system_test.gd index 11b0f568..e61fd894 100644 --- a/game/tests/system_test.gd +++ b/game/tests/system_test.gd @@ -466,6 +466,7 @@ func _smoke_lifecycle_matrix() -> void: guard += 1 check(main.run_scope.settlement == null or not main.run_scope.settlement.is_battle_live(), "V3d 活战斗驱动完毕（战斗已收场——%d 轮，finished=%s）〔装配生命批 V3〕" % [guard, str(finished.done)]) + await process_frame main._flush_row_queue() for i in range(12): if main._end_overlay.is_open(): diff --git a/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md b/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md index 154cccc5..9ab45728 100644 --- a/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md +++ b/reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md @@ -47,7 +47,7 @@ S13 闸＝「当前扫描 vs 基线对账」：判红仅两种——基线外新 | 波4 | board_generator＋node_map_generator | 17 | 生成器族：board_generator（measure_inferability 64 行 12 分支）＋node_map_generator（validate_output 132 行 34 分支 22 局部） | 推理层生成正确性断言面在册；生成结果逐位零变化 | | 波5 | damage_controller＋effect_engine | 17 | 伤害与效果管线：damage_controller（_hero_attack_ctx/redeem 双超长、open_ticket 参数 12/5）＋effect_engine（_cond_ok return 19/6、多余 else 一条） | 伤害数值与效果语义零触碰；effect_engine.validate_trigger_row 的文案计数修正随 iter38 卡③，写卡时核现行 | | 波6 | camp_overlay_view＋level_map_screen＋board_cell_unit＋standee_body＋hero_info_panel_view＋battle_end_overlay＋debug_overlay＋ui_assembler＋battle_stage_view＋curio_pick_overlay＋settings_overlay＋battle_log_view＋curio_interact_controller＋ap_bar_view＋board_zone_view＋board_fx_view＋legend_overlay | 54 | 呈现层构建函数族同病根：_init／_build／_paint_cell／_draw 超长（camp_overlay _init 149 行 28 局部、board_cell_unit _draw 147 行 29 分支、_paint_cell 139 行 24 分支）；循环内 new 多在本波；2026-10-26 用户裁＝视图内部拆私有函数，不拆构建步件（main_ui_build 先例动机是组合根超限，普通视图不类比） | 改前建 golden 基线或对拍 0.00%（先例=iter38 卡① level_map.png）；对拍差异非零即红；扛 iter38 特批带红合并的恶化债一条（level_map_screen 类变量 22>21，c4c69701）——本波还债或随批批准 refresh 归绿 | -| 波7 | 结构小件定点修（吸收原「结构审查未立项小件候审」条目） | —（审计来源，无 S13 计数） | 卡已写：`reports/需求卡片-结构小件定点修批-2026-10-26.md` v1.2（main 死变量与 confirm 旁路／settle_batch 空判／row_pacer 常驻 flush／_fatal assert 剥离／rng_service early-return 五件）；iter38 卡②施工中途停卡呈报（wr5/wr6 验收载体与闸机错误扫描结构性互斥），改动已还原零提交 | 随本事项重裁验收载体后续用；卡内行号按合回后 master 重核 | +| 波7 | 结构小件定点修（吸收原「结构审查未立项小件候审」条目） | —（审计来源，无 S13 计数） | 卡已写：`reports/需求卡片-结构小件定点修批-2026-10-26.md` **v1.3**（六件＝main 死变量与 confirm 旁路／settle_batch 空判／row_pacer 常驻 flush／_fatal assert 剥离／rng_service 未知标签 early-return／rng_service 未播种分支 early-return）；iter38 卡②施工中途停卡呈报（wr5/wr6 验收载体与闸机错误扫描结构性互斥），改动已还原零提交；2026-10-26 经用户裁修订定稿＝违约取证改落独立负面套件＋并修未播种分支（git 提交 b3ea7532） | 可直接编排；卡内行号已按迭代 38 合回点重锚，后批合回仍须按其 T0 重核 | | 波8 | 散条兜底（19 文件） | 40 | 散条兜底：类级超标大户（config_db 公开方法 44、main 类变量 49、adventure_table 类变量 44、save_manager 公开方法 52）＋参数族（curio_flow_context _init 16/5、hud_presenter 三件、unit_container spawn 10/5）＋测量面（print 残留×2、循环内 await）；config_db 公开方法收敛定性纯代码（2026-10-26 用户裁：删冗余、私有化内部方法，不动对外语义，架构表对外暴露列实现批后随动改写） | 测量面两件 print 是否留档豁免随批裁；散条可并卡也可零星随其他波搭车 | | 尾波 | 三宿主残留 | 待清点 | iter39 合回后 adventure_runner／level_runner／board_view 残留债重新清点并入 | 前置=迭代 39 合回 | @@ -411,4 +411,6 @@ S13 闸＝「当前扫描 vs 基线对账」：判红仅两种——基线外新 3. **波 6 形态＝视图内部拆私有函数**，不拆构建步件（main_ui_build 先例的动机是组合根超限，普通视图不类比）。 4. **波 8 config_db 公开方法收敛＝纯代码**（删冗余、私有化内部方法，不动对外语义；架构表「对外暴露」列属现状登记，实现批后随动改写）。 5. **判定口径**：全部波不改游戏规则与玩家可见行为——design/gdd/systems/ 零修订预期；唯一设计改动面＝波 1 的 architecture.md；owner 契约若被触碰走迭代批反哺点通道（正常机制）。波 5 已实查落定：open_ticket 12 参全是单据声明形态，「九栏目」只在架构模块描述层、GDD 无此契约，参数收束不改单据栏目与明细行发射协议，纯代码。 +6. **2026-10-26 独立审查折入（grilling＋godot-master 双子代理并行审查，双判「回炉补裁级」——骨架成立、接线未闭合）**：阻断 8 条去重 6 组全折入 architecture.md v1.18——①S13 键账：12 随迁键（use_treasure×4／_grant_routed 参数 8／_dispatch_row／_apply_percent_row／_apply_gp_row／_apply_flat_row 参数＋返回／_submit_flat_hero／_fx_fact 返回）随函数入新文件＝基线外 NEW，卡内同步收敛定为本波义务、禁波 0 合并 refresh 吸收；②跨件单向接线裁死（RewardGrant 持 fx 件引用、fx 件对授予面走注入兑付 Callable——禁 RefCounted 双向环）；③settlement/ 段类随动（段类直持三引用，Middle Man 禁壳，读写面点名）；④两新件消费依赖列补全＋引用束注入防 _init 参数新键＋TreasureItems 经宿主 setter 转发（注入时序）；⑤treasure_interact_controller 三触点分家（现值回调＋双取值面，防每战新建悬挂）；⑥_fx_revealing 再入闸归 fx 件、揭示态投影消费方订正为宿主订阅旁路判定。建议 5 条全折入：S8_FILES 与 S7_B1_SET 同批随动、battle_orchestrator 行旧述过渡指路、头注发射点指址随动许可、nest_preview_count 留宿主＋两外部直读面冻结、fx_reveal 流随件迁移取号序不变。 +7. **2026-10-27 写卡整合裁定（用户裁「太分散，整合」——波次归并为 3 张需求卡，消除文件交叠）**：卡 1「B1 战斗域拆件批」＝波 1＋波 3＋damage_controller 9 键（B1 域件，拆件已触其调用面）＋treasure_interact_controller 2 键（三触点分家必触）＝45 键，设计事实源＝architecture.md v1.18；卡 2「核心数据面结构收敛批」＝波 2（40）＋波 4（17）＋effect_engine（8，归 core/data 面防与卡 1 文件交叠）＋波 8 core/data 侧 10 文件 21 键＝86 键；卡 3「呈现层结构收敛批」＝波 6（54）＋波 8 呈现侧 8 文件 17 键＝71 键。合计 45＋86＋71＝202 键＋三宿主规避 14＝216（账目闭合）。波 7 复用现成卡不重写；波 0 直改不写卡。归并收益＝写卡/审计/闸批开销降、文件交叠冲突归零（grant_segment 一卡内先随动再拆 run）、PARITY 对拍与 golden 锚各一次；代价＝卡 2 覆盖约 20 文件最厚、审计抽检面变大。编排预测：迭代 A＝卡 1＋卡 3、迭代 B＝卡 2＋波 7（均为常规区间）。 diff --git a/reports/需求卡片-B1战斗域拆件批-2026-10-27.md b/reports/需求卡片-B1战斗域拆件批-2026-10-27.md new file mode 100644 index 00000000..60d9998f --- /dev/null +++ b/reports/需求卡片-B1战斗域拆件批-2026-10-27.md @@ -0,0 +1,393 @@ +# 需求卡片：B1 战斗域拆件批（gdstyle 存量债·波 1＋波 3＋damage/treasure 收编） + +- 版本：**v1.1**（2026-10-27 用户四项裁决落死——零待裁点；自审六查＋grilling 自检一轮全折入，记录见 §12） +- 来源：[待办清单](../待办清单.md)「gdstyle 存量债全量清偿——216 键按病根分波整改」条目（2026-10-26 登记，P0，状态=文档设计已闭合＋已写卡）（唯一事实源：[architecture](../design/engineering/architecture/architecture.md) **v1.19**「战斗编排域拆件定稿」节全文＋功能层表 BattleFxHost／RewardGrant 两行） +- 归并与账目：[审计报告](./审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 7 条（2026-10-27 写卡整合裁定）——本卡收编波 1（22 键）＋波 3（12 键）＋damage_controller（9 键）＋treasure_interact_controller（2 键）＝**45 键**；v1.1 全清口径＝44 键卡内清零义务＋1 键豁免登记归账（§11 裁决记录④） +- 归属：`game/core/` 新二件＋battle_orchestrator／settlement/ 两段／damage_controller／settlement_table 拆段＋treasure_interact_controller 三触点分家＋`game/data/schemas/` 新两段件＋测试与装配面改址＋static_scan 两清单随动 +- 排期：未编入（迭代批卡片；估时 ≈5.25 个工作日，区间 5.0–5.75） +- 开工门：U0＋复核门过（§12）；**零待裁点（§11 2026-10-27 用户裁决记录）——可编入迭代** +- 同日姊妹卡：核心数据面结构收敛批（卡 2）、呈现层结构收敛批（卡 3）——整合裁定后三卡文件交叠为零 + +## 0. 前置依赖与并行性 + +- **第〇步核对（2026-10-27 写卡会话；v1.1 修订会话复核）**：来源条目＝设计线条目（gdstyle 存量债清偿，逐波设计段闭合），波 1 闭合凭据＝architecture v1.19（「战斗编排域拆件定稿」节＋功能层两新件行；v1.19＝2026-10-27 全清设计补课——组合根句柄面与测量面两处 S13 豁免登记，为本卡全清口径豁免支臂的同族先例），状态已到「已写卡」，放行。波 3／damage／treasure 三收编件按 §六第 5 条定性纯代码（零设计改动）＋重测读数写卡。 +- **attune 族领地隔离**：同调配装 8 成员原位保留（拆件定稿节第 4 款）——语义领地归迭代 39 副卡（AttuneLoadout 充能单源化）。本卡禁触 attune 族与 adventure_runner／level_runner／board_view 三宿主（迭代 39 在册规避）；level_runner 对本卡零改动（其 treasure_inventory 注入 `level_runner.gd:502` 与 set_treasure_unlocked `:640` 走宿主公有面不变）。 +- **并行冲突注记**：与卡 2（波 2/4/8 core/data 面＋effect_engine）、卡 3（波 6/8 呈现面）文件交叠零（整合裁定消除）；与波 7 现成卡（结构小件定点修批 v1.3，2026-10-26 修订定稿）文件交叠零。同迭代排波先后自便（本卡自持 worktree 批）。 +- **PARITY 触面注记**：本卡改动面命中 `run_all_gates.sh:227` PARITY_TOUCH_FACES 四路径（battle_orchestrator.gd／settlement/／damage_controller.gd＋game/data/tables/〔settlement.tres 重建〕）——对拍发起已裁停（§11 裁决记录①），触面判定仍在每次跑批显式呈报；若用户改裁实跑按契约 4 保留机制。 + +## 1. 目标与完成定义 + +**目标**：battle_orchestrator（1313 行／50 类变量／S13 全库单文件最大户）按变化原因拆出 **BattleFxHost**（效果引擎宿主件）与 **RewardGrant**（奖励授予件）两协作件；settlement/ 授予段与战斗段随动改指；grant/combat 两段 run() 与 settlement_table.validate() 段内拆私有函数族；settlement_table schema 拆两个子 Resource 嵌套段（类变量 18→3）＋.tres 单文件嵌套重建＋消费方改址；宿主超标函数 begin_battle／_place_variants 函数级拆分与 _emit_row 参数束改形全清（§11 裁决记录③）；damage_controller 函数级拆分＋open_ticket 参数束；treasure_interact_controller 三触点分家＋ctx 束构造。**游戏行为零变化**（契约 1），iter38 行数恶化债（c4c69701）本批还债归绿。 + +**改动单元清单**（与 §7 文件结构图同源）： + +| # | 单元 | 内容 | +|---|---|---| +| u1 | BattleFxHost 建件＋fx 族迁移 | 事件发射面（_fx_emit）、事实判定（_fx_fact）、AC 基线与本轮/本战累积、bonus_delta 四轴累积（战末宿主 drain）、揭示待兑队列与兑付（含 _fx_revealing 再入闸）、round/battle 桶计数器持有（桶随编排器生灭）、round_start 发射、订阅重建 | +| u2 | RewardGrant 建件＋grant 族迁移 | 极性路由兑付（grant_routed）、三种行应用（flat/percent/gp）、伤害单据提交面（submit 族）、清图奖励与身份授予、GP 缓冲 escrow、案C 暂存闸（defer） | +| u3 | use_treasure 拆分＋三触点分家 | use_treasure 四步编排迁 RewardGrant＋体拆分；treasure_interact_controller 经组合根现值回调改注 RewardGrant，minesweeper 读与 attune_convert_state 仍走宿主取值回调（双取值面） | +| u4 | 段类随动 | GrantSegment／CombatSegment 构造注入直持宿主＋两新件三引用（Middle Man 禁壳，调用点改指；读写面=拆件定稿节第 3 款点名清单） | +| u5 | run() 族拆分＋宿主超标函数拆分全清 | grant_segment.run()＋_judge_seal、combat_segment.run()、settlement_table.validate() 段内拆私有函数族；begin_battle（141 行/17 分支/16 局部/7 return 四键）与 _place_variants（52 行/14 局部/6 嵌套三键）分段拆族、_emit_row 参数束改形（8→5）——三函数键全清 | +| u6 | damage_controller 拆分 | open_ticket 参数束（4 参 spec 形态）、_hero_attack_ctx／_hero_attack_redeem／_resolve_enemy_skill 拆分、类变量 19→15 收敛（inject 束＋fx_calls 束） | +| u7 | 改址＋随动 | 测试/探针/装配面改址 123 处（§3 G11 清单）＋settlement 列消费改址 97 处（§3 G15 清单）；static_scan.sh S7_B1_SET／S8_FILES 登记两新件 | +| u8 | 撤销证明＋产出物 | 逐 wr 撤销证明；三份产出物落位 | +| u9 | settlement 拆段 | schema 拆两子 Resource 段件（「结算结构与封印溢价」7 列／「伤害掷点与护甲」10 列，segment_order 留主表——主表三列形）＋settlement.tres 单文件嵌套重建＋消费方改址 97 处＋validate 校验随动（契约 10） | + +**完成定义**： +1. u1–u9 落地；代码域闸全绿；行数恶化债归绿——拆件后宿主与两新件文件行数全部 ≤1000（宿主实测预估 ≈950，T3 分段函数壳与束形改形开销已计）。 +2. 45 键账逐键核对（读数表进实现报告）：44 键零超标命中逐键落地（机制清单见 §11 裁决记录②③）＋battle_orchestrator 类变量键 50→38 豁免登记归账（§11 裁决记录④——登记义务随批走反哺点清单）；**零「残留申报/改善非清零」形态**（该两形态已废）。 +3. 行为零变化验收落地（§11 裁决记录①替代验收）：批末 dump_battle 六组逐行 diff 非空即红＋现役同种子断言面全绿。 +4. 撤销证明逐 wr 行落地；三份产出物写齐（T7）；独立验收审计过。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | [architecture](../design/engineering/architecture/architecture.md) **v1.19** | 「战斗编排域拆件定稿」节八款全文（轴甲两件／跨件单向接线／段类随动读写面点名／attune 原位／呈现零变化／S13 键账收敛义务／验收红线／S7-S8 随动——其中验收红线款「S13 改善非清零口径」句被 2026-10-27 用户裁决取代，卡内执行全清口径、该句改写义务入反哺点清单）＋功能层表 BattleFxHost 行（消费依赖 9 类）与 RewardGrant 行（消费依赖 12 类）＋battle_orchestrator 行过渡注记 | +| D2 | [审计报告](./审计-gdstyle存量债清点与清偿方案-2026-10-26.md) | §三波次表（波 1/3/5 病根与注意）、§六第 5 条（open_ticket 12 参单据声明形态定性）、第 6 条（独立审查 6 组折入）、第 7 条（三卡整合裁定与 45 键账目） | +| D3 | [战斗结算](../design/gdd/systems/战斗循环/战斗结算.md)（只读引用） | :175「单据九个栏目」＝单据字典语义面契约（兑付配方／来源三件／显示名／通道／攻击类型／威力基数／目标规则／必中附加分量），未绑定函数签名——本卡零修订（同步面见 §6） | + +## 3. 现状事实（2026-10-27 写卡会话实查于 master 8b146321；开工日 T0 复核行号） + +| # | 事实 | 出处 | +|---|---|---| +| G1 | battle_orchestrator.gd 实测 1313 行（gdstyle 读数 1314，口径差 1 以闸为准；基线登记 1302——**恶化债在案**）；类变量 50（逐员对账一致）；信号 4／const 2。键 22 条＝行数＋类变量＋begin_battle×4＋_place_variants×3＋use_treasure×4＋_grant_routed 参数＋_dispatch_row/_apply_percent_row/_apply_gp_row 参数×3＋_apply_flat_row 参数＋返回＋_submit_flat_hero 参数＋_fx_fact 返回＋_emit_row 参数 | `game/core/battle_orchestrator.gd` 全读＋`python tools/gdstyle_gate.py` 实跑（216 命中／恶化 2）＋`tools/gdstyle_baseline.txt` | +| G2 | fx 族成员 11：_fx_hero_ac_base:78／_fx_ac_round:79／_fx_ac_battle:81／_fx_bonus_delta:82／_fx_new_resource_types:83／_fx_pending_reveals:84／_fx_revealing:85／_fx:91／fx_counters_round:92／fx_counters_battle:93／counters_ctx:94；fx 族函数 9：_fx_emit:98／_emit_round_start:107／_sync_hero_ac:118／_apply_ac_bonus:126／_fx_enqueue_reveal:138／_flush_pending_reveals:145（fx_reveal 流 :158 随件迁移点）／_fx_fact:173。fx_counters_round/battle 两成员在 _init:283-284 挂入 counters_ctx 后全库零读者（「同物异名同字典」自注）——迁入后可删 | 实读＋grep 全库（tests 命中均为行键文本/ctx 读） | +| G3 | grant 族成员 3：escrow:53／_defer_board_damage:59／_deferred_board:60；grant 族函数 11：use_treasure:710（62 行／8 返回／18 分支／11 局部）／_grant_routed:778（8 参）／_dispatch_row:810（6 参）／_apply_percent_row:820（6 参）／_apply_gp_row:844（6 参）／_apply_flat_row:859（7 参/9 返回）／_submit:900／_outcome_of:909／_submit_flat_hero:914（7 参）／_grant_clear_reward:924／_grant_clear_identity:943。_pool_effective:1016／perfect_sweep_earned:1312／四 helper（_feat_yield_adjust:654／_harmful_variants:668／_harmful_adjacent:680／_hits_of:691）留宿主（拆件定稿节第 3 款点名） | 实读 | +| G4 | 宿主保留面（拆件定稿节第 1 款）：状态机与生命周期（begin_battle:310-449／_install_new_board:452／_battle_over:1121）、轮 facts 缓冲（_facts_reveals/seals/path:55-57）、A2 三事件订阅（_on_cell_revealed:586／_on_seal_judged:615／_on_round_end:619）、五段驱动（_settle:634）、attune 族 8 成员原位（attune_has/attune_param_sum/_attune_charge_safe_row/_reseed_attune_charges/attune_convert_state/_attune_safe_seen 等 :74-76/:199-265）、行发射基建（_emit_row:1269／_assert_row_source:1294／_fatal:1304）、呈现投影（presentation_snapshot:1179／diagnostic_snapshot:1241——两出口均不读迁移态，实查载荷字段全宿主成员）、刷新面（can_refresh:1100／player_request_refresh:1110）、nest_preview_count:80 | 实读 | +| G5 | grant_segment.gd 329 行：run() :18-229（211 行/36 局部/33 分支/6 嵌套——全库最大单函数）、_judge_seal :234-316（84 行/14 分支/11 局部/6 嵌套）、_apply_counter_hit:320／_apply_material_hit:326。对迁移面引用实测：oc._grant_routed×5（:59/:122/:290/:316/:329）／oc._submit×6（:79/:114/:127/:156/:195/:209）／escrow 写 :217／_fx_new_resource_types :42-44／_feat_first_dig_used :46/:74-75／_fx_bonus_delta 写 :108-109/:266-267／_apply_ac_bonus :151/:263／_fx_enqueue_reveal :67/:121／_flush_pending_reveals :228／_grant_clear_reward :227／counters_ctx :100/:202/:322／oc._fx（engine 判定）:224；另有 oc._emit_row 直调 5 处（:33/:218/:271/:281/:309——经宿主行发射单点，留守不改指、随 T3 束形改参） | `game/core/settlement/grant_segment.gd` 全读 | +| G6 | combat_segment.gd 100 行：run() :17-100（83 行/13 局部）。对迁移面引用实测：_defer_board_damage 复位 :18、_deferred_board 结账 :92-99、_damage.dig_streak/charge_layers 注入 :29/:32、_hits_of :50（宿主 helper 留守）；_emit_row 零直调（伤害行经 damage_controller emit_row_cb） | `game/core/settlement/combat_segment.gd` 全读 | +| G7 | aura/decay/verdict 三段对迁移面引用 **零命中**（grep 实测）——维持 _init(host) 单引用，不入三引用随动面 | grep 实测 | +| G8 | settlement_table.gd 89 行：@export 18 列（=类变量键 18/15 的全部构成——表 schema 数据列）、validate() :44-89（16 分支）、结构冻结 const 4（ARMOR_KEYS/ATTACK_TYPE_KEYS/FROZEN_SEGMENT_ORDER/P_PERFECT_DOMAIN——const 不计类变量）。18 列全集＝equivalence_ref_damage/p_perfect/seal_hit_premium/segment_order/source_label_map/effect_pool_map/pool_clamp_lo/pool_clamp_hi/round_direction/armor_effectiveness/roll_faces/attack_bonus/roll_tier_bounds/roll_tier_discounts/crit_roll/crit_multiplier/damage_floor/armor_roll_stream | `game/data/schemas/settlement_table.gd` 全读 | +| G9 | damage_controller.gd 629 行／类变量 19（逐员对账一致）：open_ticket :144-173（12 参——单据声明形态，返回单据字典含九栏目+requires/source_unit）、_hero_attack_ctx :266-325（61 行/9 分支/16 局部）、_hero_attack_base_value :330-360（达标）、_hero_attack_redeem :365-417（54 行/10 分支/12 局部）、_resolve_enemy_skill :440-482（13 局部）、fx_reveal_request/fx_ac_request :99-100（begin_battle :393-394 同点注入）、dig_streak/charge_layers/rider_tier×2 :51-54（combat_segment 与 begin_battle 注入） | `game/core/damage_controller.gd` 实读 | +| G10 | treasure_interact_controller.gd 159 行：_init :20-28（7 参）、inventory_projection :102-146（11 局部）；三触点实测——use_treasure 经 _settlement_get :85-89、minesweeper 读 :107-111、attune_convert_state :113。构造点唯一＝main_ui_build.gd:66-67（两 lambda 现值回调） | `game/presentation/treasure_interact_controller.gd` 全读＋grep | +| G11 | 测试/探针/装配面改址清单（grep 实测，非注释直引）：**counters_ctx 80 处**（adventure_feats_test 71／treasure_effects_test 5／round_flow_skill_pool_test 3〔:653/:673/:711/:1019 等〕／settle_segments_test 1）；**_fx_emit 4**（adventure_feats :751-754）；**_fx_enqueue_reveal 2＋_flush_pending_reveals 2**（round_flow :1040-1041/:1057-1058）；**_grant_routed 8**（seal_polarity :724/:732/:743/:752/:754、level_shop_economy :902/:924、meta_progression_forge :676）；**_grant_clear_reward 2**（seal_polarity :380/:395）；**use_treasure 3**（treasure_effects :167/:236/:285）；**.escrow 成员直读 3**（level_shop :892/:894/:904——:810-850 系行载荷键零改址）；**open_ticket 直调 16**（damage_controller_test 15＋system_contracts_test :74）；**构造点 1**（main_ui_build :66-67）；**段构造 2 行**（settle_segments_test :20/:22）。合计 **123 处**。零改址面：nest_preview_count（main.gd:531-532／treasure_effects:151——留宿主）、attune_convert_state 2／attune_param_sum 3（treasure_effects——留宿主）、query_reward_identity/presentation_snapshot/diagnostic_snapshot（board_resolvers:34/:32、hud_presenter:41/:329、main_debug_flow:14、ui_tune_probe:112、ui_click_probe:890、damage_probe:338/:421、auto_player——留宿主）、行协议 escrow 键（battle_log_view:160／level_shop _escrow_sum_of）、cross_system_flow:70 与 adventure_feats:496/:746 的 open_ticket 均为 triggers 载荷字符串非函数调用 | grep 全库实测 | +| G12 | static_scan.sh 两清单各 7 文件：S8_FILES :315、S7_B1_SET :357（battle_orchestrator＋settlement/ 五段＋damage_controller）；PARITY_TOUCH_FACES＝`tools/run_all_gates.sh:227-236`（含 game/data/tables/ 面——settlement.tres 重建命中） | 实读 | +| G13 | GDD 定性：`design/gdd/systems/战斗循环/战斗结算.md:175` 描述单据九栏目（语义面），全节无函数签名契约——open_ticket 参数收束定性纯代码（与审计 §六第 5 条一致） | 实查 | +| G14 | 事件总线现状：minesweeper 三信号连接宿主方法（_init:296-298）；damage/action_economy/reward_economy 三 set_fx 注入（_init:293-295）；_damage.emit_row_cb = _emit_row（_init:292）——拆件后经 fx_host.engine/counters_ctx 转注，形态不变 | 实读 | +| G15 | settlement 表 18 数据列全库消费实测：`db.settlement.<列>`／`_db.settlement.<列>` 链式访问 96 处／87 行／15 文件（产品面 28 行 6 文件＝damage_controller 21＋battle_orchestrator 2＋effect_engine 1＋grant_segment 1＋combat_segment 1＋battle_log_view 2；测试与 sim 面 59 行 9 文件＝table_structure_guard 12＋damage_controller_test 12＋damage_probe 10＋roll_multiplier 9＋damage_math 7＋round_flow 5＋seal_polarity 2＋system_contracts 1＋player_copy_sweep 1）＋局部表引用形态 2 处（config_db_cross_validator :46/:52——st_tab.effect_pool_map/source_label_map）；segment_order 直读 1 处（round_flow :381——留主表零改址）；p_perfect/equivalence_ref_damage 零外部读者（纯表值）。**改址合计＝97 处**（core 段 35＝链式 33＋cross_validator 2；damage_roll 段 62） | grep 全库实测（2026-10-27 修订会话） | +| G16 | 全库 `.tres` 零嵌套 sub_resource、`game/data/schemas/` 零段类 Resource 先例（grep 实测）——settlement 拆段为全库首个子 Resource 嵌套 schema（Godot 标准 .tres 能力，engine-reference 破坏性变更表仅 duplicate 语义注意） | grep 实测＋engine-reference 查核 | + +## 4. 设计契约（红线，违反 = L3 停机呈报） + +🔴 **契约 1 · 行为零变化**：RNG 消费序零漂移——fx_reveal 封闭流随件迁移**取号序不变**（_flush_pending_reveals 掷格时机/候选序/流名逐字，G2 迁移点 :158）；信号顺序契约冻结（step_row/battle_finished/round_started/board_changed/settlement_snapshot 发射点与时序零改动）；明细行协议词表零触碰（基础 9 类＋扩展行 effect_id 词表与头注清单不动——_emit_row 参数束改形只动函数形参、行字典字段与 step_row 载荷逐字不变）；同种子逐位一致（§11 裁决记录①替代验收：dump_battle JSONL 六组逐行 diff 非空即红＋现役同种子断言面全绿）。 + +🔴 **契约 2 · 行数恶化债还债归绿**：iter38 特批带红合并挂账（commit c4c69701，battle_orchestrator 行数 1314＞基线 1302）本批还债——拆件后宿主与两新件文件行数全部 ≤1000；禁以 refresh 换绿、禁删注释凑行数。 + +🔴 **契约 3 · S13 键账纪律**：`tools/gdstyle_baseline.txt` 禁改禁 refresh；还债＝数值下降自然绿；**12 个随迁键卡内收敛为本批义务**（use_treasure×4／_grant_routed 参数 8／_dispatch_row/_apply_percent_row/_apply_gp_row 参数×3／_apply_flat_row 参数＋返回／_submit_flat_hero 参数／_fx_fact 返回——随函数迁入新文件即基线外 NEW，禁波 0 合并 refresh 吸收）；宿主超标函数键（begin_battle×4＋_place_variants×3＋_emit_row×1）随 T3 全清（§11 裁决记录③）；battle_orchestrator 类变量键按豁免登记归账（§11 裁决记录④——键永久基线内、禁再恶化）；机检键与卡内契约互斥时实现段一律停卡呈报；禁为迎合机检消息文本保留或新增无效成员/别名（§13）。 + +🔴 **契约 4 · PARITY 触面（对拍已裁停——§11 裁决记录①）**：battle_orchestrator.gd／settlement/／damage_controller.gd／game/data/tables/（settlement.tres 重建）四面被改即触对拍触面表——本批对拍**不发起**，替代验收＝既有 `sim/dump_battle.gd` 改前改后 JSONL 逐行 diff（种子矩阵 {42, 779401, 779501}×关卡 {1, 2} 六组，零新码）＋现役同种子断言面（§8.1 wr10）；若用户改裁实跑，按 PARITY_APPROVED=1 机制执行（批末设变量跑全套闸即实跑、对拍非零差异即红、**不得借机重锚**——机制指引保留防未来翻案无据）。 + +🔴 **契约 5 · 跨件单向接线（禁 RefCounted 双向环）**：RewardGrant 持 BattleFxHost 引用（treasure_used 发射与 counter_spend 消费）；BattleFxHost 对授予面走 bind 时注入的兑付 Callable（揭示队列 flush 回调）——禁反向强引用。行发射经注入 emit Callable（协议面单点留宿主，CurioDeck bind_handlers 同款先例）；fatal 经注入 Callable 转宿主 _fatal（battle_result 状态机唯一写点留宿主）；facts 缓冲留宿主、fx 件经注入 facts Callable 取值；_seal_consumed 留宿主（与 A2 seal_judged 订阅同域）。禁件回调宿主私有族、禁转发壳（Middle Man）。 + +🔴 **契约 6 · 呈现零变化**：presentation_snapshot／diagnostic_snapshot 两出口签名与载荷逐字不变（G4 实查不读迁移态，零改写压力）；treasure_interact_controller 三触点分家——use_treasure 经组合根现值回调改注 RewardGrant（**每战新建编排器，禁一次性直引防悬挂**），minesweeper 读与 attune_convert_state 仍走宿主取值回调（双取值面）；nest_preview_count 直读面零变化（main.gd:531-532 与 treasure_effects_test:151 冻结零改址）。 + +🔴 **契约 7 · attune 族原位**：同调配装 8 成员不进新件（迭代 39 副卡语义领地）；RewardGrant 经宿主 attune 读投影 Callable 取 _attune_safe_seen（use_treasure 拒绝文案读数）；attune_convert_state/attune_param_sum 留宿主。 + +🔴 **契约 8 · open_ticket 参数束不改单据栏目**：参数收束为 spec 束形态（4 参），返回单据字典九栏目与 requires/source_unit 键逐字不变（GDD :175 九栏目为语义面契约、无签名绑定——G13）；spec 必载键（channel/base_value/target_rule/ri）缺载即 assert（fail-fast 同现行缺省纪律）；禁改单据字段名、禁改明细行发射协议。 + +🔴 **契约 9 · 测试改址非削弱**：≈220 处改址（G11 123 处＋G15 97 处）＝访问路径改写与 spec/head 束键值搬运，断言语义与判据逐条保持；实现期不得借改址删断言/放宽判据（测试削弱申报＝零，§8.2）。 + +🔴 **契约 10 · settlement 拆表数值零变化**：18 数据列值迁两段**逐字不变**（settlement.tres 表值与尾注批注史逐字保留——只挪结构不挪值）；settlement.tres **单文件保持**（子 Resource 嵌套序列化＝Godot 标准 .tres 能力，G16）；ConfigDB 加载面不变（`db.settlement` 仍 SettlementTable 实例，load_tables 与 `config_db.gd:19/:40` 无改）；segment_order 留主表（段序骨架列——round_flow :380-382 `SettlementTable.FROZEN_SEGMENT_ORDER` 断言引用面零变化，const 四枚随主表）；消费方改址 97 处＝访问路径改写，值语义零变化；validate() 错误载荷逐字同构。 + +## 5. 范围边界 + +**做**：u1–u9（§7 全部任务卡）；§8 全部验收；撤销证明；产出物。 + +**不做**（去向明示）： +- attune 族迁移／AttuneLoadout 建件 → 迭代 39 副卡（在册）； +- aura/decay/verdict 三段（迁移面零触及，G7）→ 零改动； +- effect_engine 数据面改造／其余数据面 schema 文件 → 卡 2（核心数据面结构收敛批）——本卡 schema 新建面仅 settlement 两段件（G16 落点唯一）； +- 呈现层视图面（golden 锚批）→ 卡 3（呈现层结构收敛批）； +- 波 0 基线对账 refresh（陈旧键清理）→ 直改批不写卡，本卡只保证不新增恶化； +- MC 调参与数值表任何值改动 → 零数值改动（契约 10 拆段只挪结构），MC 不跑（无数值改动零跑铁规）； +- design/ 与根规则文件任何编辑 → 反哺点清单（§6）。 + +## 6. 关联文档同步面 + +| 文档 | 关联点（本批实现会改变它的哪条陈述） | 同步义务 | +|---|---|---| +| `design/engineering/architecture/architecture.md` | 功能层 battle_orchestrator 行「已定稿拆出 BattleFxHost」过渡注记改写为现状；BattleFxHost／RewardGrant 两行「设计定稿——实现批建件」标注换代为现状；「战斗编排域拆件定稿」节头注转现状登记；验收红线款「S13 改善非清零口径」句随全清裁决改写为全清义务（§11 裁决记录③）；S13 豁免登记节补第三条——battle_orchestrator 类变量键（宿主保留面承载面豁免，§11 裁决记录④） | 反哺点 · 列清单 | +| `game/tests/验证集清单.md` | ≈220 处改址与四新件断言登记的清单同步（机器提取重生成） | 批内机械同步（game 内 .md，非禁写面） | +| `design/gdd/systems/战斗循环/战斗结算.md` | **零修订预期**——单据九栏目与行协议词表零触碰（契约 8）；settlement 拆段为纯结构（契约 10 表值零变化）；若实现期发现冲突即停卡呈报 | 无（零修订预期） | +| `待办清单.md` | 来源条目状态推进（实现批收尾由 batch-closure 承接） | 反哺点 · 列清单 | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/core/battle_fx_host.gd`（**新增**） | 效果引擎宿主件：fx_emit 发射面／fx_fact 事实判定／AC 三值累积与同步／bonus_delta 累积与 drain／揭示队列与兑付（再入闸）／两桶＋ctx 持有／round_start 发射／订阅重建（结构图与预检互指：标「新增」，理由见 §7 预检） | 新件（承载迁移态，行为不变）→ wr1 | +| `game/core/reward_grant.gd`（**新增**） | 奖励授予件：grant_routed 极性路由／三种行应用（flat 拆四）/submit 案C 闸／清图奖励／escrow／use_treasure 四步（拆 _apply_use_kinds） | 新件（承载迁移态＋12 随迁键收敛）→ wr2/wr3 | +| `game/core/battle_orchestrator.gd`（修改） | 宿主保留面（G4）＋建件接线（_init 建两件并注入引用束/bind_grant 接线）＋begin_battle 各调用点改指＋_on_cell_revealed 旁路读改 reveal_busy＋_battle_over bonus drain＋新增 _fx_host_fact 方法＋组件出口两枚：`fx_host() -> BattleFxHost`／`reward_grant() -> RewardGrant`（取件方法非委托壳——姊妹卡 hero()/stop() 同款先例，呈现与测试经此取件，禁链式穿透）＋begin_battle/_place_variants 分段拆族＋_emit_row 束形（T3） | 结构改动，行为不变 → wr1/wr2/wr5 | +| `game/core/settlement/grant_segment.gd`（修改） | 三引用构造＋读写面改指（G5 清单）＋run() 拆私有函数族＋_judge_seal 两分＋oc._emit_row 5 调用点随 T3 束形改参 | 结构改动 → wr4/wr5 | +| `game/core/settlement/combat_segment.gd`（修改） | 三引用构造＋defer/dig_streak/charge_layers 改指＋run() 拆三私有 | 结构改动 → wr4/wr5 | +| `game/data/schemas/settlement_core_table.gd`（**新增**） | 「结算结构与封印溢价」段 Resource（纯数据载体）：source_label_map/effect_pool_map/pool_clamp_lo/pool_clamp_hi/round_direction/p_perfect/seal_hit_premium 七列，值逐字迁入 | 新件（纯数据载体，行为不变）→ wr9 | +| `game/data/schemas/damage_roll_table.gd`（**新增**） | 「伤害掷点与护甲」段 Resource（纯数据载体）：equivalence_ref_damage/armor_effectiveness/roll_faces/attack_bonus/roll_tier_bounds/roll_tier_discounts/crit_roll/crit_multiplier/damage_floor/armor_roll_stream 十列，值逐字迁入 | 新件（纯数据载体，行为不变）→ wr9 | +| `game/data/schemas/settlement_table.gd`（修改） | 主表三列形（segment_order 留主表＋core＋damage_roll——类变量 18→3）＋validate() 拆四私有校验器（错误载荷逐字，列读改段地址） | 结构改动 → wr5/wr9 | +| `game/data/tables/settlement.tres`（修改） | 单文件嵌套重建（sub_resource 两段嵌入；18 列值与尾注批注史逐字保留——契约 10） | 数据件结构重建，值零变化 → wr9 | +| `game/core/damage_controller.gd`（修改） | open_ticket spec 束＋_hero_attack_ctx/_hero_attack_redeem/_resolve_enemy_skill 拆分＋类变量收敛（inject 束＋fx_calls 束）＋emit_row_cb 注释与 6 调用点随 T3 束形改参 | 结构改动 → wr6 | +| `game/presentation/treasure_interact_controller.gd`（修改） | _init(ctx 束)＋attempt_use 改注 grant_get＋inventory_projection 拆两私有（三触点分家） | 结构改动 → wr3 | +| `game/presentation/main_ui_build.gd`（修改） | 秘宝交互构造改 ctx 束形态（:66-67 一处） | 装配面改址 → wr3 | +| `game/tests/static_scan.sh`（修改，工具面随动） | S7_B1_SET／S8_FILES 各增两新件路径＋头注计数 7→9 | 工具面随动（非行为）→ wr7 | +| `game/tests/` 改址 9 文件（修改） | G11 清单：adventure_feats 75／treasure_effects 8／round_flow 7／seal_polarity 7＋2〔G15〕／level_shop 5／forge 1／damage_controller_test 15＋12〔G15〕／system_contracts 1＋1〔G15〕／settle_segments 3；另 G15 清单：table_structure_guard 12／damage_probe 10／roll_multiplier 9／damage_math 7／round_flow 5／player_copy_sweep 1；core/presentation 面改址：damage_controller 21／battle_orchestrator 2／effect_engine 1／两段各 1／battle_log_view 2／config_db_cross_validator 2 | 测量面改址 → wr1/wr2/wr3/wr6/wr9 | +| `game/tests/unit/core/settle_segments_test.gd`（修改） | 两新件直构断言＋grant/combat 段三引用构造改形 | 新增断言（随 T2/T4）→ wr4 | + +（两新件、两段 schema 件与新增束的复用/唯一性核查见「落位与可复用性预检」；settlement.tres 仍单文件——嵌套重建非新增 .tres。） + +### 接口块 + +**BattleFxHost（`game/core/battle_fx_host.gd`）** + +```gdscript +class_name BattleFxHost extends RefCounted # 生命周期＝随编排器（编排器 _init 同建同灭；桶随编排器生灭语义不变） +func _init(bundle: Dictionary) -> void +# bundle 封闭键集（缺一键 assert——引用束注入防 _init max-parameters 新键；两新件消费依赖列）： +# db:ConfigDb／rng:RngServiceCore（fx_reveal 封闭流）／minesweeper:MinesweeperRules（板读与 fx_reveal）／ +# action_economy:ActionEconomy（queue_ap_delta/charge_layers/ap_exhausted_last_round）／ +# damage:DamageController（set_hero_ac_override）／ +# emit_cb:Callable（宿主 _emit_row——行协议面单点；T3 改 5 参束形后随束形）／ +# facts_cb:Callable（宿主 _fx_host_fact——round_index/battle_index/seals_count/nest_count/hp_ratio 五事实宿主侧单点） +func bind_grant(cb: Callable) -> void # 揭示兑付回调＝RewardGrant.grant_routed（宿主 _init 建两件后接线—— + # 构造序解法：RewardGrant bundle 持 fx_host、fx_host 对授予面走注入 Callable，禁双向强引用） +var engine: EffectEngine # 效果引擎（原 _fx；宿主 _init 经此转注 damage/action_economy/reward_economy 三 set_fx） +var counters_ctx: EffectContext # 四桶引用束（round/battle 两桶本件自有；adventure/level 桶 begin_battle mount_buckets 挂引用） +func fx_emit(event: String, payload: Dictionary) -> Array # 原 _fx_emit——18 发射点统一入口 +func emit_round_start() -> void # 原 _emit_round_start（含 ac_round 清零与同步） +func apply_ac_bonus(h: Dictionary) -> void # 原 _apply_ac_bonus +func enqueue_reveal() -> void # 原 _fx_enqueue_reveal +func flush_pending_reveals(ri: int) -> void # 原 _flush_pending_reveals（fx_reveal 流随件迁移取号序不变） +func rebuild_subscriptions(feats: Array, attunement: Array, tree_rules: Array) -> void # 原 _fx.rebuild 调用点（装载序 feats→treasure→树规则写死） +func mount_buckets(adv_bucket: Dictionary, level_bucket: Variant) -> void # begin_battle 桶挂引用（level 非 Dictionary 即不挂——现 :390-392 语义） +func reset_battle_state(ac_base: int) -> void # begin_battle 运行态清零（ac 三值/bonus_delta 四轴/new_resource_types/揭示队列+闸——现 :381-386 原序） +func bonus_delta_drain() -> Dictionary # 战末 drain（读后清零；宿主 _battle_over 单消费——现 :1132-1135 读改清三拍合一，时序等价） +func reveal_busy() -> bool # 揭示兑付中读投影（宿主 _on_cell_revealed 旁路判定——拆件定稿节第 6 款揭示态消费方） +# 内部：fx_fact(fact)（charge_layers 自答、余五事实转 facts_cb——2 返回）；_sync_hero_ac（经 damage 注入引用） +# 类变量封闭面（14≤15）：bundle 7 项＋grant_cb＋engine＋counters_ctx＋ac{base,round,battle}＋_fx_bonus_delta＋ +# _fx_new_resource_types＋reveal{queue,busy}——ac/reveal 两束键集封闭、头注声明（原 fx_counters_round/battle +# 两成员迁入即删——同物异名零读者，G2） +``` + +**RewardGrant（`game/core/reward_grant.gd`）** + +```gdscript +class_name RewardGrant extends RefCounted # 生命周期＝随编排器 +func _init(bundle: Dictionary) -> void +# bundle 封闭键集（12 项）：db:ConfigDb／reward_economy:RewardEconomy（polarity_row/grant/grant_clear/query_full_snapshot）／ +# damage:DamageController（open_ticket/submit）／fx_host:BattleFxHost（treasure_used 发射与 counters_ctx 消费）／ +# minesweeper:MinesweeperRules（校验回调/fx_reveal/remove_mines_in/hero_pos）／action_economy:ActionEconomy（相位闸/grant_ap/queue_ap_delta）／ +# status_effects:StatusContainer（apply_effect）／units:UnitContainer（hero_unit/heal）／ +# emit_cb:Callable／fatal_cb:Callable（宿主 _fatal——battle_result 唯一写点留宿主）／ +# attune_safe_seen_cb:Callable（宿主 attune 读投影——use_treasure 拒绝文案）／pool_effective_cb:Callable（宿主 _pool_effective——percent 行池值读） +var escrow := 0 # 战斗内 GP 缓冲（原宿主成员语义逐字；宿主 _roll_gp_drop 读投影） +var defer := {"on": false, "queue": []} # 案C 暂存闸（原 _defer_board_damage/_deferred_board 二合一；键集封闭） +var treasure_inventory: TreasureItems = null # 经宿主 setter 转发注入（库存注入时序在宿主构造之后） +func bind_battle(ledger_ref: RunLedger) -> void # begin_battle 账本引用挂接（attune_charge_consume/vision_count_add 消费） +func reset_battle() -> void # begin_battle 现 :315 语义（escrow 清零＋defer 复位） +func use_treasure(handle: int, target: Vector2i) -> Dictionary # 原 use_treasure 四步（拆 _apply_use_kinds——12 随迁键收敛） +func grant_routed(snap: Dictionary, polarity: String, att: Dictionary) -> bool # 原 _grant_routed +func submit(t: Dictionary, sync: bool) -> int # 原 _submit（案C 闸承载：defer.on 即入 defer.queue） +func outcome_of(ticket_id: int) -> String # 原 _outcome_of +func grant_clear_reward(ri: int, skip_on_refresh: bool, perfect: bool) -> void # 原 _grant_clear_reward（宿主态读经参传入） +# att 归因束封闭键集（全 grant 族共用）：source_class:String／cell:Vector2i／ri:int／ +# highlight:String（缺省""）／label_suffix:String（缺省""）／halve_pct:int（缺省 0） +# 内部族（签名随 att 束改形，全部 ≤5 参）：_apply_use_kinds(v, target) -> Dictionary（拒收字典/空字典=受理）／ +# _dispatch_row(row, att)／_apply_percent_row(row, att)／_apply_gp_row(row, att)／ +# _apply_flat_row(row, att, sync) -> String（按 ctype 分派 _flat_action/_flat_blast/_flat_typed/_flat_heal 四私有， +# 返回 ≤6）／_submit_flat_hero(display, power, att, sync)／_grant_clear_identity(snap, ri, suffix) +# 类变量封闭面（15≤15）：bundle 12 项＋escrow＋defer＋treasure_inventory +``` + +**damage_controller 改形（`game/core/damage_controller.gd`）** + +```gdscript +var inject := {"dig_streak": 0, "charge_layers": 0, "rider_tier_bonus": 0, "rider_tier_crit": false} + # 每轮/每战注入运行态（原四散成员收敛；键集封闭——combat_segment 写前两键、begin_battle 写后两键、 + # _fx_fact/管线读同键；19→15 收敛之一） +var fx_calls := {"reveal": Callable(), "ac": Callable()} + # 效果引擎入站回调（原 fx_reveal_request/fx_ac_request；begin_battle 同点注入 fx_host 两方法 Callable） +func open_ticket(kind: String, source_class: String, display: String, spec: Dictionary = {}) -> Dictionary + # spec 必载键：channel/base_value/target_rule/ri（缺载 assert——fail-fast）；可选键缺省=现签名缺省： + # origin_cell=(-1,-1)/attack_type=""/rider=0/highlight=""/context={} + # 返回单据字典九栏目+requires/source_unit 逐字不变（契约 8） +# 拆分族：_ctx_rewrites(t, target, matchup, ar_hits) -> Dictionary（按序改写族四拍——threshold/crit/discount/ +# spike_ready/roll_read 穿线）／_ctx_clamp_delta(atk_type, armor, matchup) -> int（克制点数读值+订阅改写）／ +# _kill_overflow(t, target, landed) -> void（kill 发射+贯穿弹射）／ +# _enemy_roll(t) -> Dictionary（掷点/折扣/克制/池乘/下限）／_enemy_shield_apply(hits, total) -> Dictionary（damage_taken 施加面——{total,shield} 穿线） +``` + +**treasure_interact_controller 改形（`game/presentation/treasure_interact_controller.gd`）** + +```gdscript +func _init(ctx: Dictionary) -> void +# ctx 封闭键集（8 项）：db／meta／info_panel:HeroInfoPanelView／toast:ToastStack／board_view:BoardView／ +# settlement_get:Callable（宿主取值回调——minesweeper 读与 attune_convert_state 双取值面之一）／ +# runner_get:Callable／grant_get:Callable（现值回调——use_treasure 直注 RewardGrant，每战取现值防悬挂） +# attempt_use/on_slot_clicked 空值守卫升级：settlement/runner/grant 三现值同查（null 即静默 return——现 settlement null 同语义） +# inventory_projection 拆两私有：_projection_row(rec, cs) -> Dictionary＋_auto_row(cs) -> Dictionary（自动兑付件展示行） +``` + +**段类随动（`game/core/settlement/grant_segment.gd`／`combat_segment.gd`）** + +```gdscript +func _init(host, fx_host: BattleFxHost, reward_grant: RewardGrant) -> void # 三引用构造注入（两段同形） +# 读写面改指（拆件定稿节第 3 款点名＋G5/G6 实测）： +# grant 段：oc._grant_routed×5→reward_grant.grant_routed（att 束拼装）／oc._submit×6→reward_grant.submit／ +# escrow 写→reward_grant.escrow／_fx_new_resource_types→fx_host._fx_new_resource_types／ +# _apply_ac_bonus→fx_host.apply_ac_bonus／_fx_enqueue_reveal→fx_host.enqueue_reveal／ +# _flush_pending_reveals→fx_host.flush_pending_reveals／_grant_clear_reward→reward_grant.grant_clear_reward +# （skip_on_refresh/perfect 两实参经宿主引用现读：oc._board_from_midround_refresh／oc.perfect_sweep_earned()）／ +# counters_ctx→fx_host.counters_ctx；_feat_first_dig_used 与四 helper 仍经宿主（留守面）； +# oc._emit_row×5 直调留守（经宿主行发射单点，随 T3 束形改参——不改指） +# combat 段：_defer_board_damage 复位→reward_grant.defer["on"]=false／_deferred_board 结账→reward_grant.defer["queue"]／ +# _damage.dig_streak/charge_layers→_damage.inject 同键／oc._fx→fx_host.engine（:224 finish_round_stop 判定，G5） +# aura/decay/verdict 三段维持 _init(host) 单引用（G7 迁移面零触及） +``` + +**settlement 拆段（`game/data/schemas/settlement_table.gd`＋两段新件）** + +```gdscript +# 主表三列形（类变量 18→3；const 四枚随主表）： +@export var segment_order: PackedStringArray = [] # 结构冻结段序骨架——留主表（round_flow :380-382 SettlementTable.FROZEN_SEGMENT_ORDER 断言引用面零变化） +@export var core: SettlementCoreTable # 「结算结构与封印溢价」段（game/data/schemas/settlement_core_table.gd 新件，7 列） +@export var damage_roll: DamageRollTable # 「伤害掷点与护甲」段（game/data/schemas/damage_roll_table.gd 新件，10 列） +# SettlementCoreTable 7 列（值逐字迁入）：source_label_map／effect_pool_map／pool_clamp_lo／pool_clamp_hi／ +# round_direction／p_perfect／seal_hit_premium +# DamageRollTable 10 列（值逐字迁入）：equivalence_ref_damage／armor_effectiveness／roll_faces／attack_bonus／ +# roll_tier_bounds／roll_tier_discounts／crit_roll／crit_multiplier／damage_floor／armor_roll_stream +func validate() -> Array # 编排骨架：errs 建账＋四私有校验＋return（分支 ≤8） +# 私有族（errs: Array[Dictionary] 追加式，与现 fail-fast 载荷逐字同构；列读改段地址 core.／damage_roll.）： +# _validate_scalars(errs) # 标量域（damage_roll: roll_faces/crit_roll/crit_multiplier/damage_floor/attack_bonus/armor_roll_stream；core: p_perfect/seal_hit_premium） +# _validate_frozen(errs) # 结构冻结（segment_order 恒等〔主表〕；round_direction/pool_clamp〔core 段〕） +# _validate_tier_table(errs)# 档位表形状（damage_roll 段：bounds 升序/discounts 降序/档数=边界数+1） +# _validate_armor_matrix(errs) # 克制矩阵 3×3 域 [-3,+3]（damage_roll.armor_effectiveness） +# 两段件＝纯数据载体（零函数零随机零 await；各 7/10 类变量 ≤15）；.tres 单文件嵌套重建（契约 10——18 列值与尾注批注史逐字保留） +``` + +**T 卡间接口**：T1 产出 BattleFxHost 全 API 与 fx 族改址完成态（T2/T4 取用 fx_host.engine/counters_ctx/三回调）；T2 产出 RewardGrant 全 API、att 束键集、use_treasure 迁移完成态与 grant_get 回调（T3/T4 取用）；T3 产出 _emit_row 束形与宿主超标函数拆分完成态（T4 段迁移直用新形）；T4 产出段三引用构造形＋settlement 三列主表面（T6 收尾对账取用）；T5 产出 open_ticket spec 束形态（damage 测试改址——T5 卡内自取）；各卡验收断言随卡落地。 + +### 落位与可复用性预检 + +| 新增件 | 复用面（为何不能复用既有） | 唯一面 | 分层与交互 | +|---|---|---|---| +| battle_fx_host.gd | 效果引擎宿主职责现散在 battle_orchestrator（本批迁出）——无同职责既有件；grep `BattleFxHost`/`battle_fx_host` 零命中；EffectEngine 是解释器本体非宿主（宿主=施加面+计数器桶+揭示队列），不可互代 | fx 族状态与施加面唯一所有者；桶随编排器生灭语义唯一落点 | Core 纯逻辑（RefCounted）；由 battle_orchestrator _init 建并注入引用束；对宿主单向（兑付/发射/事实走注入 Callable——契约 5）；随机只经注入 rng 的 fx_reveal 封闭流 | +| reward_grant.gd | 授予管线现散在 battle_orchestrator（本批迁出）；grep 零同名类；B4 RewardEconomy 是资源身份/字典查询件（路由执行归 B1 授予段——architecture 功能层表明文），不可互代 | 奖励授予唯一兑付管线；escrow 与案C 闸唯一落点 | Core 纯逻辑；持 fx_host 引用（单向）；宿主态（perfect/装板 provenance/attune/pool 值）全经参传或注入 Callable，不持宿主引用——禁环 | +| settlement_core_table.gd＋damage_roll_table.gd（两段 schema 件） | 18 列全集实查**无既有等价结构**：全库 .tres 零嵌套 sub_resource、schemas/ 目录零段类 Resource 先例（G16 grep 实测）——复用既有扁平表即违「拆段只挪 settlement 结构」边界，复用其他表结构更无对应列语义；EffectContext 等引用束是运行期字典非 Resource schema，不可互代 | settlement 两段列的唯一承载；.tres 单文件嵌套重建唯一落点 | game/data/schemas/（表 schema 目录惯例：class_name <名>Table extends Resource、<名>_table.gd 文件名）；SettlementTable 主表持两段字段；段件零函数零随机零 await | +| att 归因束／spec 束／ctx 束／inject/fx_calls 束／emit head 束（数据面约定，非新文件） | 项目 Dictionary 载荷惯例（行协议 extra/单据 context/encounter 装配同法）；CurioFlowContext 先例同法（curio_interact_controller 装配 ctx）——不另立类型文件 | 每束键集封闭并头注声明（缺一 assert 或缺省显式）；单一声明处=各件头注 | 随所属件生灭；键名在接口块定死，禁实现期增删 | + +### T0 事实坐实＋改前基线采集（≈0.25d） + +- [ ] 复核 G1–G16 行号与读数（吸收并行批漂移）；记录改前读数表：S13 六文件键读数（gdstyle_gate 实跑输出）＋行数/类变量计数——进实现报告素材。可核查结果：改前读数表在案。 +- [ ] 改前确定性基线采集：`…console.exe --headless --path . --script res://sim/dump_battle.gd -- <关卡> <种子>`（既有 dump 载体——step_row 逐行 JSON，关卡/种子两参数，零新码）跑种子矩阵 {42, 779401, 779501}×关卡 {1, 2}，stdout 重定向落 `reports/` 实现报告素材目录（六文件）。可核查结果：改前 JSONL 六份在案（替代验收本体——§11 裁决记录①；批末 T6 按同参复跑逐行 diff）。 + +### T1 BattleFxHost 建件＋fx 族迁移＋S7/S8 登记（≈0.75d） + +- [ ] 实装 battle_fx_host.gd（接口块全签名；fx 族 11 成员＋9 函数自 battle_orchestrator :77-94/:97-196 语义逐字迁入；_fx_fact 改形两返回、charge_layers 自答余五事实转 facts_cb；ac/reveal 两束键集封闭）。可核查结果：件可 `new()` 直构单测。 +- [ ] battle_orchestrator 接线：_init 建 _fx_host（引用束 7 键）→建 _reward_grant→`_fx_host.bind_grant(_reward_grant.grant_routed)`（构造序禁环）＋组件出口 `fx_host()`/`reward_grant()` 两取件方法＋`_damage.set_fx(_fx_host.engine, _fx_host.counters_ctx)` 等三处转注（G14）＋新增 `_fx_host_fact(fact) -> Variant` 五事实方法（:173-196 五分支搬运）；begin_battle 各调用点改指（reset_battle_state/mount_buckets/rebuild_subscriptions/board_installed emit/emit_round_start 原位替换）＋fx_calls 注入；_on_cell_revealed 旁路改 `not _fx_host.reveal_busy()`（:592）；_battle_over 改 bonus_delta_drain（:1132-1135）；宿主 fx 族 11 成员删除（fx_counters 两零读者成员一并删——G2）。 +- [ ] fx 族测试改址（G11，经组件出口）：adventure_feats 75 处（counters_ctx 71＋_fx_emit 4→`orch.fx_host().` 前缀）；round_flow 7 处（counters_ctx 3＋enqueue/flush 4→`o_fx.fx_host().`）；treasure_effects 5 处（counters_ctx）；settle_segments 1 处。 +- [ ] static_scan.sh 两清单登记：S8_FILES :315 与 S7_B1_SET :357 各追加 `game/core/battle_fx_host.gd game/core/reward_grant.gd`＋头注计数 7→9（:309）。可核查结果：S7/S8 段扫描含两新件且零命中。 +- [ ] 验收步骤：〔fx1〕现役揭示管线断言改址后全绿（round_flow 扩展行收敛 V6：`o_fx._fx_host.enqueue_reveal()`→`flush_pending_reveals(1)`→兑付行/落空行同判据）；〔fx2〕battle 桶隔离断言（round_flow :1019 改 `oB._fx_host.counters_ctx` 读 insurance_used=0）；〔fx3〕空订阅零命中断言（adventure_feats :751-754 改 `_fx_host.fx_emit` 同判据）。撤销证明见 wr1。 + +### T2 RewardGrant 建件＋grant 族迁移＋use_treasure 拆分＋三触点分家（≈1.0d） + +- [ ] 实装 reward_grant.gd（接口块全签名；grant 族 3 成员＋11 函数自 battle_orchestrator :698-957 语义逐字迁入；use_treasure 拆 `_apply_use_kinds(v, target) -> Dictionary`——③步逐 kind 应用迁出，四步编排骨架留守；_apply_flat_row 按 ctype 分派 _flat_action/_flat_blast/_flat_typed/_flat_heal；grant 族签名随 att 束改形）。可核查结果：12 随迁键在迁入形下逐键过阈值（T0 gdstyle 复跑两新件零基线外 NEW）。 +- [ ] battle_orchestrator 接线：_init 建 _reward_grant（引用束 12 键）＋`treasure_inventory` 改带 setter 转发（`set(v)` 同步写 _reward_grant.treasure_inventory——外部赋值路径零改址，G11 treasure_effects 三处直赋保持）；begin_battle :315 改 `_reward_grant.reset_battle()`、:388 后加 `_reward_grant.bind_battle(_ledger)`；宿主 grant 族 3 成员删除；_roll_gp_drop 读 `_reward_grant.escrow`（:1169）。 +- [ ] 三触点分家：treasure_interact_controller._init 改 ctx 束（8 键）＋attempt_use 改 `grant_get.call().use_treasure(handle, target)`＋inventory_projection 拆 _projection_row/_auto_row 两私有＋守卫三现值同查；main_ui_build :66-67 构造改 ctx 束（新增 grant_get＝经 `root.run_scope.settlement.reward_grant()` 现值取件、null 即 null——每战取现值防悬挂）。 +- [ ] grant 族测试改址（G11，经组件出口）：seal_polarity 7 处（_grant_routed 5 直调改 `settlement.reward_grant().grant_routed(snap, 极性, {source_class, cell, ri}` att 束＋_grant_clear_reward 2 直调改三参形）；level_shop 5 处（_grant_routed 2＋.escrow 直读 3→`.reward_grant().escrow`）；forge 1 处（_grant_routed att 束）；treasure_effects 3 处（use_treasure→`obX.reward_grant().use_treasure`）。 +- [ ] 验收步骤：〔rg1〕负向字典直验断言改址后全绿（seal_polarity :720-754 五型逐型同判据）；〔rg2〕escrow 隔离断言（level_shop :892/:894/:904 改址后同值判据）；〔rg3〕use_treasure 真链三例（treasure_effects :167/:236/:285——overlay/AP/拒绝零消耗同判据）；〔rg4〕use_treasure 拆分后同种子受理序列逐位一致（T0 JSONL 批末复跑 diff 承载——§11 裁决记录①）。撤销证明见 wr2/wr3。 + +### T3 宿主超标函数拆分全清（≈0.5d） + +- [ ] begin_battle 函数级拆分全清（141 行/17 分支/16 局部/7 return 四键清零）：按现行执行序拆编排骨架＋分段私有族（命名=`_begin_<段>` 形态——受理与账本挂接／装板与板态落值／桶挂接与订阅重建／运行态清零与轮始发射；拆后逐函数过 gdstyle 阈值，仍超者按同规则续分；段序/发射序/取号序逐字——以 T1/T2 改指后的现形为基准）。可核查结果：gdstyle 对 battle_orchestrator 四 begin_battle 键零命中。 +- [ ] _place_variants 拆分（52 行/14 局部/6 嵌套三键清零）：嵌套施加面拆私有（命名=`<名>_apply` 形态），主函数留编排序；拆后逐键过阈值。可核查结果：三键零命中。 +- [ ] _emit_row 参数束改形（8 参→5 参，键清零）：`_emit_row(head: Dictionary, ri: int, display: String, value: int, extra: Dictionary)`——head 封闭键集 {type, source_class, origin_cell, highlight（缺省""）} 头注声明；行字典字段与 step_row 载荷逐字不变（契约 1/6）；调用点全量改形：host 14 处＋damage_controller emit_row_cb 注释 :36 与 6 调用点＋grant 段 oc._emit_row 5 调用点（combat 段零直调，G5/G6）＋BattleFxHost/RewardGrant 接口块 emit_cb 注记随动。可核查结果：params 键零命中＋现役断言面全绿（行载荷逐字）。撤销证明见 wr5。 + +### T4 段类随动＋run() 族拆分＋settlement 拆段（≈1.25d） + +- [ ] 授予/战斗两段三引用构造（接口块签名）；读写面改指按接口块清单逐条（G5 ×12 面＋G6 ×3 面）；aura/decay/verdict 三段零改动（G7）；settle_segments_test :20/:22 两行构造改三参形（实例经 `oc.fx_host()`/`oc.reward_grant()` 取件）。 +- [ ] grant_segment run() 拆私有函数族：`run(ri)` 编排骨架＋`_reveal_batch(ri)`＋`_reveal_safe(evt, snap, ri)`（施加面拆 `_reveal_safe_apply(dr_hits, evt, snap, ri)`）＋`_reveal_mine(evt, snap, ri)`（施加面拆 `_reveal_mine_apply(mh_hits, snap, ri)`）＋`_terrain_batch(ri)`＋`_seal_batch(ri)`＋`_round_end_apply(ri)`；_judge_seal 两分 `_judge_seal_hit(evt, ri)`（施加面拆 `_seal_hit_effects(fh_hits, cell, ri)`）＋`_judge_seal_miss(evt, ri)`。段序/发射序逐字（run 内调用序=现行 :22-229 执行序）。 +- [ ] combat_segment run() 拆：`run(ri)` 骨架＋`_hero_strike(ri)`＋`_enemy_actions(ri)`＋`_board_deferred_settle(ri)`。 +- [ ] settlement_table.validate() 拆四私有校验器（接口块签名；错误载荷逐字——列读经 core./damage_roll. 段地址，随本卡拆段项同批落地）。 +- [ ] settlement 拆段（契约 10；§11 裁决记录②）：实查 18 列分组在案（G8/G16——segment_order 留主表＋两段 7+10 列）→新建 settlement_core_table.gd/damage_roll_table.gd（接口块全列）→settlement_table.gd 主表改三列形＋validate 四私有校验器列读改址（错误载荷逐字）→settlement.tres 单文件嵌套重建（sub_resource 两段嵌入；18 列值与尾注批注史逐字保留）→消费方改址 97 处（G15 清单：core 段 35＝`db.settlement.core.`／`st_tab.core.` 改写；damage_roll 段 62；segment_order 直读 1 处零改址；产品面 6 文件＋tests/sim 面 9 文件＋config_db_cross_validator）。可核查结果：〔st1〕表值逐字断言＋〔st2〕validate 绿＋〔st3〕消费改址断言（下条验收步骤）。 +- [ ] 验收步骤：〔sg1〕同种子完整局 step_row 逐位一致（现役断言面全绿——round_flow/seal_polarity/level_shop 全套）；〔sg2〕五段段直构断言（settle_segments_test 改形后绿）；〔sg3〕validate 拆分后错误载荷逐字断言（现役 validate 单测继承）；〔st1〕settlement.tres 重建前后 18 列值逐字断言（table_structure_guard_test 改址后全绿）；〔st2〕validate 拆段后全绿（加载期校验真链）；〔st3〕damage_math/roll_multiplier/damage_controller_test 改址后全绿（段地址读值同值判据）。撤销证明见 wr4/wr5/wr9。 + +### T5 damage_controller 拆分＋参数束（≈0.75d） + +- [ ] open_ticket 改 spec 束（接口块签名；必载四键 assert）；core 调用点 13 处改形（RewardGrant 内 grant 族 3 处〔T2 已迁入〕、grant_segment 6 处 :76/:112/:125/:154/:192/:206、combat_segment 3 处 :44/:54/:84、控制器内部 overflow 1 处 :410；KIND_HERO_ATTACK 分支内构造逻辑不动）。 +- [ ] 类变量收敛：inject 束（4→1）＋fx_calls 束（2→1）——combat_segment :29/:32 与 begin_battle :393-394/:398-399 注入点随动改键写；_fx_fact/管线读改键读；19→15。 +- [ ] 拆分族落地（接口块签名）：_ctx_rewrites＋_ctx_clamp_delta（自 _hero_attack_ctx 拆出）；_kill_overflow（自 _hero_attack_redeem 拆出）；_enemy_roll＋_enemy_shield_apply（自 _resolve_enemy_skill 拆出）。拆后逐函数过 gdstyle 阈值；仍超者按施加面/兑付面继续两分，命名=`<名>_apply`/`<名>_roll` 形态。 +- [ ] damage 测试改址（G11＋G15）：damage_controller_test 15 处直调改 spec 束（键值搬运，断言逐字）＋12 处 db.settlement 段地址改写；system_contracts :74 一处＋1 处段地址；combat/grant 段内 open_ticket 调用随 T4 已改指处套 spec 形。 +- [ ] 验收步骤：〔dc1〕damage_controller_test 全套改址后全绿（A/B 两模式、死亡作废、requires 门、flush_submit 同批契约逐条同判据）；〔dc2〕九栏目契约断言（system_contracts :74 改址后——单据字典九键+requires/source_unit 逐键同值）；〔dc3〕伤害真链断言继承（round_flow 主角先手/敌方还手/地图账殿后现役断言）。撤销证明见 wr6。 + +### T6 改址收尾＋键账逐键复测＋替代验收（≈0.5d） + +- [ ] 改址扫尾：grep 旧符号全库零残留（`_grant_routed\|_flush_pending_reveals\|_fx_enqueue_reveal\|\.escrow\b` 于 tests/probe 的成员访问形态；open_ticket 12 参位置形态；`db.settlement.<17 列裸列名>` 平铺地址逐列零残留——segment_order 除外〔G15〕；_emit_row 8 参位置形态零残留）——G11/G15 清单逐条对账（≈220 处）。 +- [ ] 键账复测：`python tools/gdstyle_gate.py`——预期基线外新违规 0、恶化 0；六文件 45 键逐键读数记录进实现报告（44 键零超标命中逐键＋battle_orchestrator 类变量键 50→38 豁免登记归账核对——§11 裁决记录④）。可核查结果：键账对照表在案。 +- [ ] 替代验收执行：批末按 T0 同参复跑 dump_battle 六组（种子矩阵 {42, 779401, 779501}×关卡 {1, 2}），与改前 JSONL 逐行 diff——非空即红（L3）；现役同种子逐位断言面全绿（round_flow/seal_polarity/level_shop 全套）。可核查结果：六组 diff 空记录在案（wr10）。 +- [ ] 验证步骤：全套闸按本批改动域选档跑一次全绿（里程碑出口；波内修复只做出红最小单元最窄确认）。撤销证明见 wr7。 + +### T7 撤销证明＋产出物落位卡（≈0.25d，末卡） + +- [ ] 逐 wr 行撤销证明（§8.1 末列——回退对应 hunk→最窄闸红→还原复绿，记录进实现报告）。 +- [ ] 写齐三份产出物（实现报告〔45 键账对照＋改前改后读数＋实机目检总清单〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）。 +- [ ] 合并前置：独立验收审计（§8.3）逐行「通过」。 + +**估时合计 ≈5.25d**（区间 5.0–5.75：T4 settlement 拆段与 97 处改址、T3 宿主全清拆分为 v1.0 基础上的增量来源）。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动（文件:行/行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 fx 族迁移建件 | battle_fx_host 新件＋宿主接线＋counters_ctx/_fx_emit/enqueue/flush 改址 86 处 | 〔fx1〕揭示管线〔fx2〕桶隔离〔fx3〕空订阅零命中〔T1，round_flow/adventure_feats/settle_segments 改址后〕 | 单元＋集成 | 编排器 begin_battle 真链→挖掘→揭示兑付 | 回退 fx 接线 hunk→fx1 红（`_fx_host` 路径不存在） | +| wr2 grant 族迁移＋12 随迁键收敛 | reward_grant 新件＋att 束改形＋escrow 直读改址 5 处 | 〔rg1〕负向字典直验〔rg2〕escrow 隔离〔T2〕＋T6 gdstyle 键账（12 键清零） | 单元＋集成＋静态 | grant_routed 直调（seal_polarity）＋完整战斗真链（level_shop） | 回退 grant 接线 hunk→rg1 红 | +| wr3 use_treasure 拆分＋三触点分家 | use_treasure 迁 RewardGrant＋_apply_use_kinds 拆分＋treasure_interact ctx 束＋main_ui_build 构造 | 〔rg3〕use_treasure 真链三例〔T2〕＋ui_click_probe 秘宝使用流直跑绿 | 单元＋探针 | C 区槽选→点格使用真链（探针/单测装配） | 回退三触点 hunk→rg3 红（use_treasure 旧路径失配） | +| wr4 段类随动 | 两段三引用＋读写面改指 14 面 | 〔sg1〕同种子逐位一致〔sg2〕段直构〔T4〕 | 集成＋单元 | 完整战斗真链（现役结算断言面） | 回退段构造 hunk→sg2 红 | +| wr5 run() 族＋宿主超标函数拆分全清 | grant/combat run 拆族＋_judge_seal 两分＋validate 四拆＋begin_battle/_place_variants 分段拆族＋_emit_row 束形 | 〔sg1〕同种子逐位一致〔sg3〕validate 载荷逐字〔T4〕＋T6 gdstyle 键账（run/_judge_seal/validate/begin_battle/_place_variants/_emit_row 键清零） | 集成＋单元＋静态 | 完整战斗真链＋表加载期校验 | 回退拆分 hunk→行为断言恒绿＋gdstyle 对应键读数回升（键账断言红）；回退束形 hunk→行发射调用点形失配红 | +| wr6 damage_controller 拆分＋参数束 | open_ticket spec 束＋拆分族＋inject/fx_calls 束＋改址 16 处 | 〔dc1〕控制器全套〔dc2〕九栏目契约〔dc3〕伤害真链〔T5〕 | 单元＋契约＋集成 | open_ticket→submit→flush 真链（damage_controller_test 装配） | 回退 spec 束 hunk→dc2 红（构造形态缺失） | +| wr7 S7/S8 随动＋改址收尾 | static_scan 两清单＋改址扫尾 | S7/S8 段扫描含两新件零命中＋T6 全套闸按域选档全绿＋键账对照表 | 静态＋全套 | 闸机（工具面） | 回退清单 hunk→S7/S8 红（新文件越集命中/缺位） | +| wr8 产出物 | T7 三份 | 件核〔wr8〕 | — | — | 缺项红 | +| wr9 settlement 拆段 | 两段 schema 新件＋主表三列形＋settlement.tres 嵌套重建＋消费改址 97 处 | 〔st1〕表值逐字断言〔st2〕validate 绿〔st3〕消费改址断言〔T4，table_structure_guard/damage_math/roll_multiplier/damage_controller_test 改址后〕 | 单元＋集成 | ConfigDB 加载真链（db.load_tables→`db.settlement.core.`/`db.settlement.damage_roll.` 读值） | 回退拆段 hunk→主表三列形缺失→ConfigDB 加载期致命红 | +| wr10 同种子逐位替代验收（契约 1 总断言） | 全批结构改动总和（总断言行，无独立改动） | 批末 dump_battle 六组复跑与 T0 改前 JSONL 逐行 diff 非空即红＋现役同种子断言面全绿〔T6〕 | 集成＋全套 | `sim/dump_battle.gd --script` 直跑（关卡×种子矩阵六组） | 回退任一拆件 hunk→复跑 diff 出差异→还原复绿 | + +### 8.2 测试削弱申报 + +零（改址≈220 处＝访问路径改写与 spec/head 束键值搬运，断言语义与判据逐条保持——契约 9；无任何断言删除/阈值放宽/扫描面缩小）。 + +### 8.3 独立验收审计 + +入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`；抽查重点＝12 随迁键清零逐键核对、44 键零超标命中逐键复核＋battle_orchestrator 类变量键豁免登记义务在反哺点清单在案（§11 裁决记录④）、S13 基线未改（git diff 查 `tools/gdstyle_baseline.txt` 零变化）、改址断言语义等价抽检（adventure_feats/seal_polarity/damage_controller_test/table_structure_guard 各 ≥3 处）、两快照出口载荷逐字比对、同种子 JSONL 基线（六组 diff 空在案）、settlement.tres 重建前后表值逐字比对、撤销证明复现。未过不得合并。 + +## 9. 异常分级 + +- **L1（自救）**：行号漂移（T0 基线对照自核）；测试改址等价写法微调；拆分族仍超阈值时的续拆（按 §7 T5 命名规则与 T3 `_begin_<段>` 形态）。 +- **L2（记录继续）**：迁移代码注释随迁措辞（语义不变）；spec/att/ctx/inject/head 束键拼装顺序（键集不变）。 +- **L3（停机呈报）**：同种子逐位断言红（JSONL diff 非空/现役断言面红）；settlement 拆段后表值与重建前不一致或 validate 载荷漂移（契约 10）；信号顺序或行协议词表漂移；机检键与卡内契约互斥（契约 3）；跨件接线需求与契约 5 冲突（如发现新件必须回调宿主私有族）；S7/S8 与架构文档冲突；attune 族被牵连触碰。 + +## 10. 代拍板白名单（超清单必呈报） + +1. 提交切分与 worktree 分支命名。 +2. 测试改址的等价访问写法（语义不变前提下）。 +3. 迁入代码的注释随迁措辞（语义不变前提下）。 +4. att/spec/ctx/inject/head 束键拼装的写法细节（键集与缺省不变前提下）。 +5. 拆分族续拆的函数内局部组织（签名与命名规则不变前提下）。 +6. settlement 两段的 .tres 嵌套序列化组织细节（段字段名与键集、18 列值逐字不变前提下）。 + +## 11. 待裁点（零待裁点——2026-10-27 用户裁决记录，全部落死） + +1. **PARITY 对拍＝停止**：不发起对拍；验收改用既有 `sim/dump_battle.gd` 改前改后 JSONL 逐行 diff（种子矩阵 {42, 779401, 779501}×关卡 {1, 2} 六组，零新码）＋现役同种子逐位断言面（round_flow/seal_polarity/level_shop 全套）全绿。执行步＝T0 采集改前基线＋T6 批末复跑 diff（§8.1 wr10）；若用户改裁实跑按契约 4 保留的 PARITY_APPROVED 机制执行（不得借机重锚）。 +2. **settlement_table 类变量 18/15＝清零拆段**：schema 拆两个子 Resource 嵌套段——「结算结构与封印溢价」段（7 列：source_label_map/effect_pool_map/pool_clamp_lo/pool_clamp_hi/round_direction/p_perfect/seal_hit_premium）＋「伤害掷点与护甲」段（10 列：equivalence_ref_damage/armor_effectiveness/roll_faces/attack_bonus/roll_tier_bounds/roll_tier_discounts/crit_roll/crit_multiplier/damage_floor/armor_roll_stream），segment_order 留主表（段序骨架列）——18 列全集实查分组在案（G8/G16），主表类变量 18→3。单 .tres 单文件保持，ConfigDB 加载面不变，消费方改址 97 处任务入卡（T4/wr9）；数值零变化（契约 10）。 +3. **宿主残留键＝全清**：v1.0「改善非清零口径（宿主残留 8–10 键）」废除——begin_battle（141 行/17 分支/16 局部/7 return）、_place_variants（52 行/14 局部/6 嵌套）、_emit_row（8 参）随拆件后函数级拆分与参数束改形全部清零（T3，wr5 承载）；12 随迁键卡内收敛义务不变（契约 3）。 +4. **全清口径落点核算**（grilling 自检折入——非新裁决，上三项裁决的算术落地）：45 键逐键归零＝44 键卡内清零义务逐键有机制（T1–T6：迁移收敛/函数拆分/参数束/schema 拆段）＋唯一清零算术不可达键＝battle_orchestrator 类变量（50：迁移 14＋新引用 2→实测落点 38，阈值 15 不可达——宿主保留面为拆件定稿节第 1 款锁定职责承载面＋attune 原位，禁为清键拆散保留面），按用户全清口径「要么清零、要么属在册豁免」第二支臂随批登记 S13 豁免第三条（main.gd 探针契约面同形先例：键永久基线内、禁再恶化），登记落文走反哺点清单（§6），键账对照表如实记 50→38——零「残留申报/改善非清零」形态（两形态已废，不再作为任何键的处置出口）。 + +## 12. 自审六查与复核记录 + +**自审六查（2026-10-27 v1.1 修订会话）**：①规格覆盖——u1→T1/wr1、u2→T2/wr2、u3→T2/wr3、u4→T4/wr4、u5→T3＋T4/wr5、u6→T5/wr6、u7→T1/T6/wr7、u8→T7/wr8、u9→T4/wr9、契约 1 总断言→wr10，完成定义四条各有落点；②步骤扫描——每步一动作一可核查结果，无「TBD/酌情」行（续拆规则=T5 命名规则、begin_battle 分段命名=`_begin_<段>` 形态，均非待定）；③类型一致性——接口块与 T 卡引用逐字：两段字段名 core/damage_roll 与类名 SettlementCoreTable/DamageRollTable 在结构图/接口块/T4/wr9 同形；_emit_row 五参束形（head/ri/display/value/extra）在接口块注记/T3/wr5 同形；前版笔误「T4 产出 spec 束（T5 damage 测试改址取用）」随重编号订正为 T5 卡内自取；G1 键清单补 _emit_row 参数（前版漏列，22 条对账补齐）；④审查焦点＋改动覆盖——最可能坑玩家面＝RNG 取号序（fx_reveal 迁移点）与 begin_battle 拆分执行序：fx1/sg1 双断言＋T3「段序/发射序/取号序逐字」判据＋wr10 六组 diff；settlement 拆段坑＝表值漂移：st1 表值逐字断言＋L3 红线；文件结构图新增行均指 wr 行；⑤篇幅比例——接口块为签名非实现体，无函数体抄写；⑥落位预检——两新 core 件、两段 schema 件、新增 head 束各有不能复用理由与唯一落点（G15/G16/预检表），与结构图「新增」标记对上。 + +**grilling 自检一轮（2026-10-27 v1.1，写卡会话对抗视角逐款过）**——阻断与折入七条全折入本版：①对拍停止后的验收可执行性——dump_battle 既有零新码、种子矩阵六组 T0 采齐、批末同参复跑 diff（T6 执行步＋wr10 行），判据非空即红；②settlement「18→3」算术核验——18 列全集实查＝两段 7+10＋segment_order 留主表，主表三列形自洽（§11 裁决记录②）；③全清口径对 battle_orchestrator 类变量键的算术核验——宿主保留面锁定下阈值 15 不可达（50−迁移 14＋新引用 2＝38）：按全清口径第二支臂随批登记 S13 豁免第三条（main.gd 同形），义务入反哺点清单、键账如实记 50→38（§11 裁决记录④）——杜绝以「改善达标」名目复活残留申报形态；④_emit_row 清零机制——函数级拆分不降参数数，唯参数束改形可达（8→5）：束形定义＋调用点全量改形（host 14＋damage_controller 注释与 6 调用点＋grant 段 5 调用点随 T3 改形、combat 段零直调）入 T3，行字典字段与 step_row 载荷逐字不变（契约 1 不受损）；⑤前版键账算术缺陷订正——「44 键清零」与「宿主残留 8 键达标线」并存自相矛盾，本版改逐键机制列清（§11 裁决记录③④＋T6 复测判据），并补 G5 漏列的 grant 段 oc._emit_row×5 直调与 G6 combat 零直调实测；⑥settlement.tres 重建回滚安全性——回退拆段 hunk＝主表三列形缺失→ConfigDB 加载期致命（fail-fast 即红），wr9 撤销证明按此写；⑦PARITY 触面清单补全——settlement.tres 重建命中 `run_all_gates.sh:227` `game/data/tables/` 面（前版三路径外），触面判定仍每次跑批呈报（契约 4）。前版已折入的七项阻断约束沿用核验通过：随迁键先收敛后迁移时序、fx host 类变量封闭面 14/15、grant_clear_reward 三参形、dump 复用零新码、bind_grant 构造序解法、组件出口取件、计数与行号订正——本版改址增量后合计复核在案（G11 123 处＋G15 97 处＝220 处）。 + +## 13. 禁为机检文本保留无效成员（重构类必填条款） + +禁止为迎合机检消息文本（含计数）而保留或新增无效成员/别名：本批迁移面中 fx_counters_round/fx_counters_battle 两零读者成员随迁即删（G2）、12 随迁键以真实拆分/签名改形收敛、_emit_row 束形以真实改形收敛（非别名转发）、settlement 拆段以真实 schema 重建落段（禁主表留平铺列的同名转发或别名）；禁以「基线计数」「测试便利」等理由在宿主保留任何迁移成员的同名转发或别名；机检键与卡片契约互斥时实现段一律停卡呈报，不得自造第三条路（code-conventions §1.1 同款）。 diff --git a/reports/需求卡片-呈现层结构收敛批-2026-10-27.md b/reports/需求卡片-呈现层结构收敛批-2026-10-27.md new file mode 100644 index 00000000..ba1113ce --- /dev/null +++ b/reports/需求卡片-呈现层结构收敛批-2026-10-27.md @@ -0,0 +1,378 @@ +# 需求卡片：呈现层结构收敛批（gdstyle 存量债清偿·波 6＋波 8 呈现侧——视图内部拆私有函数＋工厂/参数面收敛＋类变量全清） + +- 版本：**v1.1**（v1.0 自审六查＋grilling 一轮记录见 §12；v1.1 = 2026-10-27 用户裁决四条款折入——全清口径取代残留申报＋print 删除落死＋main/await 两键架构豁免，自审与 grilling 二轮记录同 §12 末段） +- 来源：[待办清单](../待办清单.md)「gdstyle 存量债全量清偿——216 键按病根分波整改」条目（2026-10-26 登记，P0，状态=文档设计已闭合＋待写卡）——**需求性工程条目，证据指认形态**（唯一事实源：[审计-gdstyle存量债清点与清偿方案-2026-10-26.md](审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 3 条〔波 6 视图内部拆私有函数、不拆构建步件〕＋第 7 条〔归并裁定：本卡＝波 6（54 键/17 文件）＋波 8 呈现侧 8 文件（17 键）＝71 键〕）；设计段裁定＝纯代码内部收敛、**零设计改动** +- 归属：`game/presentation/` 25 文件（波 6 十七件＋波 8 呈现侧八件）＋消费面随动改址（§7 结构图注记；v1.1 增 board_view 写入行随动，见 §0）；treasure_interact_controller 已移卡 1（B1 战斗域拆件批），不在本卡 +- 排期：未编入（迭代批卡片；估时 ≈5.0–5.5 个工作日，估 ≈5.3d） +- 开工门：U0＋复核门过（§12）；**零待裁点**（2026-10-27 用户裁决记录：print 删除；await 按 v1.19 测量面豁免——§11） + +## 0. 前置依赖与并行性 + +- **第〇步核对（2026-10-27 写卡会话）**：来源条目＝需求性工程条目（状态行含「文档设计已闭合＋待写卡」；证据指认＝清点报告 §六逐波裁定＋本卡 §3 逐文件实查），放行。设计段闭合凭据（2026-10-26 用户裁）＝①纯代码波写卡前确认零设计改动＋按当时 master 重测读数（已做，见 §3）；②波 6 形态＝视图内部拆私有函数、不拆构建步件；③波 8 呈现侧散条随本卡收编（§六第 7 条归并裁定）。**v1.1 补核对（同日用户裁决四条款）**：全清口径取代残留申报（71＝69 清＋2 豁免）、print 删除落死、main/await 两键按 architecture v1.19 豁免登记、其余类变量大户收拢内部状态件——四条款为类变量键清偿的设计闭合凭据，已落 §1/§4/§7/§8.4/§11。 +- **与迭代 39 卡组的文件交叠（串行义务，呈编排段裁先后）**：iter 39 主卡（冒险域拆件批）触 `level_map_screen.gd`（:334-343 bonus 读面改指 hero）、`hud_presenter.gd`（:20/313 同面）、`curio_interact_controller.gd`（16 处调用改指 stop()）、`main.gd`（装配面）——与本卡四文件重叠。两批无论先后，后开工批 T0 自吸收行号漂移；**禁编入同迭代同波并行**。姊妹副卡（同调配装）触 core 域零叠；技能池触发器卡触 core/data 零叠。**v1.1 交叠集扩展：board_view.gd 加入错波集**（u3 收拢随动其写入行约 40 行，见 u3 行）——交叠义务同四文件（后开工批 T0 吸收漂移；board_view 结构拆件仍归 iter 39 领地，本卡只做写入行机械改址，见 §5 不做清单）。 +- 与同事项卡 1（B1 战斗域拆件批：battle_orchestrator/settlement/damage_controller/treasure_interact_controller）、卡 2（核心数据面：core/data 侧）**零文件交叠**。 +- 本卡禁触 adventure_runner/level_runner（iter 39 规避清单）；禁触 battle_orchestrator（其行数恶化债 c4c69701 归卡 1 还债）。~~board_view 禁触~~（v1.1 收窄：board_view 结构拆件仍禁触，写入行机械改址随动允许——u3 全清口径的必要执行面，2026-10-27 裁决第 5 条）。 + +## 1. 目标与完成定义 + +**目标**：呈现层 25 文件 71 键结构收敛——超长构建/绘制/格式化函数拆私有函数族（波 6 形态裁定）、工厂件公开面与参数族收敛（波 8）、类变量大户收拢内部状态件全清（v1.1：2026-10-27 裁决，残留申报废除）、测量面 print 残留删除（信息已由 toast/JSONL 承载）、main/await 两键按 v1.19 架构豁免申报。**游戏行为与玩家可见呈现零变化**（契约 1）：本批零行为改动、零新文件、零新公开概念。 + +**改动单元清单**（需求点，逐单元验收行见 §8 对照表；键数＝2026-10-27 实测，与清点报告 §五逐条吻合；v1.1 收拢清单＝逐件成员构成实查产出，冻结成员与收拢面逐条见 §3 S17）： + +| # | 单元（文件） | 现行键（值/阈值） | 改法 | +|---|---|---|---| +| u1 | camp_overlay_view.gd | 类变量 19/15；循环内 new×7；_init 149 行 28 局部（:42）；_rebuild_tree 61 行 21 局部（:222）；_rebuild_forge 72 行 20 局部（:301）；refresh_camp 61 行 17 局部（:386） | _init 拆四柜台构建私有族；_rebuild_*/refresh_camp 拆行板构建私有族；循环体提行板构建私有函数；**类变量收拢（v1.1）**：探针冻结 5 成员（S17）保持宿主，其余 14 个（_tree_holder/_forge_lock_l/_forge_workbench/_forge_zone_weapon/_forge_zone_armor/_forge_rows/_ws_scroll/_ws_lock_l/_attune_header_l/_attune_btns/_attune_nodes/_refresh_l/_refresh_btn/_recent_list）收进内部状态件 → 宿主 6 | +| u2 | level_map_screen.gd | **类变量 22/15（基线登记 21——iter38 恶化债 c4c69701，本卡归绿义务）**；_init 135 行 21 局部（:58）；_draw_graph 78 行 9 分支 27 局部（:423） | _init 拆构建私有族；_draw_graph 拆绘制私有族（节点/通道/底栏）；**类变量收拢（v1.1）**：探针冻结 6 成员（S17：_cand_ids/_hover_id/_content_size/_layout_cache/abandon_btn/status_badge）保持宿主，其余 16 个收进内部状态件（_node_icons/_noise_rect/_tint_level 三件在状态件内持 `_layer_decor` 域字典，装饰域归并形态随迁）→ 宿主 7；恶化债归绿被 ≤15 吸收（键消失） | +| u3 | board_cell_unit.gd | 类变量 31/15；_draw 147 行 29 分支 19 局部（:135） | _draw 拆绘制私有族（底面/接触带/数字徽标/封印/高亮/点迹各域）；**类变量收拢（v1.1）**：探针直读 4 成员（glyph/fog_state/plate/glyph_color）保持宿主，board_view 直写 26 成员收进内部状态件、board_view 写入行随动改址（约 40 行 `u.X =` → `u.st.X =`，机械改址零语义——S17 实查：31 成员中 30 个被 board_view 直写 47 行，本件为被动绘制壳，全清唯一路径＝写入行随动）→ 宿主 6（4 冻结＋_glow_layer＋状态件） | +| u4 | standee_body.gd | 类变量 29/15；循环内 new×2（:268/:296）；_draw 84 行 26 局部（:414） | _draw 拆绘制私有族（立绘/血条/意图/护甲徽标/顺位徽标）；循环体提私有构建函数；**类变量收拢（v1.1）**：外部直访 4 成员（box/font/slot_row/has_world_hp_bar——battle_stage_view 直写 :122/:180/:214/:268、fx_probe/ui_probe 直读，S17）保持宿主，其余 25 个收进内部状态件（含 _death_shards/_hit_sparks/_flash_count 三探针出口计数——经 fx_probe() 方法出口，随迁方法读点）→ 宿主 5 | +| u5 | hero_info_panel_view.gd | 循环内 new×2（:55/:189）；_init 74 行（:24）；set_treasure_inventory 57 行 13 局部（:162） | _init 拆段构建私有族；槽位循环体提私有构建函数 | +| u6 | battle_end_overlay.gd | 类变量 20/15；循环内 new×4（:222/:251/:271/:303）；_init 81 行（:31）；open_victory 参数 8/5（:116） | _init 拆行板构建私有族；循环体提私有构建函数；open_victory 可选尾参收拢 opts 字典（4 参）；**类变量收拢（v1.1）**：探针直读 4 成员（_btn/_gp_name/_gp_row/_gp_val，S17）保持宿主，其余 16 个收进内部状态件 → 宿主 5 | +| u7 | debug_overlay.gd | 类变量 17/15；_build 124 行 22 局部（:153） | _build 拆五区块构建私有族（探针直引公开面逐字保留）；**类变量收拢（v1.1）**：探针直读 3 成员（seed_edit/_sim_btn/_dbg_btn，S17）保持宿主，其余 14 个收进内部状态件（_run_data/_run_labels 经 run_data_probe()/update_run_data() 方法出口，随迁方法读点）→ 宿主 4 | +| u8 | ui_assembler.gd | 循环内 new（:156）；build_start_overlay 83 行 16 局部（:97） | build_start_overlay 拆列/行构建私有族；立绘循环体提私有构建函数 | +| u9 | battle_stage_view.gd | 循环内 new（:266）；_init 97 行（:27）；_enemy_portrait_tex return 9/6（:233） | _init 拆子视口/世界/壳层构建私有族；_enemy_portrait_tex 改查表＋回退（映射语义零变化） | +| u10 | curio_pick_overlay.gd | _init 52 行（:27）；_icon_for_id return 7/6（:192） | _init 拆构建私有族；_icon_for_id 改查表＋回退 | +| u11 | settings_overlay.gd | _build 77 行 13 局部（:31） | _build 拆行构建私有族 | +| u12 | battle_log_view.gd | _format_row 68 行 21 局部 13 return 9 分支（:144） | _format_row 按行型拆私有格式化函数族（iter38 卡⑥类型修复后现行形态为准） | +| u13 | curio_interact_controller.gd | 类变量 18/15 | **引用束注入（v1.1）**：16 个注入成员（db/4 视图/11 Callable）全部来自 _init(ctx) 逐成员抄写（:32-48）＝CurioFlowContext 冗余面——删除 16 成员、正文读点改址 ctx 束（u20 三束键名，S12）；_pending_curio/_curio_context 纯内部态保持 → 宿主 3（ctx＋2）。探针零成员直读（S17——press_candidate 等全走方法面），零冻结面 | +| u14 | ap_bar_view.gd | _init 69 行（:34） | _init 拆构建私有族（源码锚句逐字保留） | +| u15 | board_zone_view.gd | _init 59 行（:21） | _init 拆构建私有族 | +| u16 | board_fx_view.gd | 循环内 new（:93） | play_perfect_sweep 循环体提私有 band 构建函数 | +| u17 | legend_overlay.gd | 循环内 new×2（:35/:37） | ENTRIES 循环体提私有行构建函数 | +| u18 | ui_kit.gd | 公开方法 26/20；beams_rect 13 局部（:333）；modal_shell 参数 6（:453）；BCard._init 参数 6（:752）；bcard 参数 6（:812） | ①删零消费 frame_skinned（:566）/verb_button（:662）②私有化 modal_dim/beams_rect/gradient_base/switch_toggle（消费方全在本卡触面文件或单条测试行随动；load_font 保留公开——探针三行直引，收敛算术不需要它）→26→20 ③modal_shell 尾参哨兵收拢（6→5）④BCard._init/bcard 可选尾参收拢 opts（6→5）⑤beams_rect 像素循环拆私有函数 | +| u19 | hud_presenter.gd | refresh 参数 8（:14）；_refresh_out_of_battle 参数 6（:147）；tune_sim_report 参数 10（:188） | refresh/_refresh_out_of_battle 运行态尾参收拢 ctx 字典（4 参）；tune_sim_report 统计束收拢（5 参）；文案逐字不变 | +| u20 | curio_flow_context.gd | 类变量 16/15；_init 参数 16/5（:25） | 参数与成员按域收拢三束（views/getters/flow 字典）→ 4 参 4 成员 | +| u21 | camp_flow_context.gd | _init 参数 12/5（:21） | 同 u20 三束收拢 → 4 参 | +| u22 | battle_narrator.gd | bonus_card_text return 9/6（:100） | match 分支拆私有文案函数/查表（文案逐字不变，现役单测断言零改动） | +| u23 | tune_sim_controller.gd | print 残留（:43）；循环内 await（:65）；run 11 局部（:36） | 统计六成员收拢一 stats 字典（与 u19 束同构）→≤10 局部；**print 一行删除（v1.1 落死）**：日志路径信息由 logger 会话产物与落盘 JSONL 承载（禁改 set_sim_report 文本——契约 1 文案逐字不变）；**循环内 await 架构豁免（v1.19 §「S13 测量面豁免登记」在册）**：禁重构测速循环，豁免状态进实现报告申报 | +| u24 | playtest_logger.gd | print 残留×2（:160/:161） | **两行删除（v1.1 落死）**：路径信息已由 toast 承载（main_debug_flow.gd:16 `show_toast("已转储诊断: "+path)`）、上下文 JSON 已落转储文件——stdout 重复输出零独有信息 | +| u25 | main.gd | 类变量 49/15 | **架构豁免（v1.1）**：组合根类变量面＝探针契约面（约 46 句柄被探针挂载假设钉死），v1.19「呈现层装配与会话生命周期」节 S13 豁免登记在册——**键永久基线内、禁再恶化；禁收拢 main 句柄、禁为清键改写探针挂载契约**。卡内任务＝核对注记在位（v1.19 :183）＋实现报告申报豁免状态（依据指针 v1.19）；死成员清点删除任务随豁免取消（类变量面冻结） | + +**完成定义**： +1. u1–u25 落地；`python tools/gdstyle_gate.py` 读数：**基线外新违规（NEW）＝0**；**恶化（WORSENED）＝1 条且仅为 battle_orchestrator 行数（卡 1 义务，不归本卡）**；**71 键＝69 键清零＋2 键豁免**（main 类变量、tune_sim 循环内 await——v1.19 两处豁免登记段在册，键永久基线内；§8.4 账目）。 +2. 呈现逐像素零变化：§7 T0 建锚面（甲/乙/丙三组）改后对拍全 0.00%。 +3. 现役全套断言面绿：探针面（含源码锚字面量契约）与单元/集成套件零红、零删改（契约 5）。 +4. 撤销证明逐行落地（§8 对照表末列）；三份产出物写齐（T5，含豁免两键申报件）；独立验收审计过。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | [审计-gdstyle存量债清点与清偿方案-2026-10-26.md](审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 3 条 | 波 6 形态＝视图内部拆私有函数、**不拆构建步件**（main_ui_build 先例动机是组合根超限，普通视图不类比——2026-10-26 用户裁） | +| D2 | 同上 §六第 7 条 | 归并裁定：本卡＝波 6＋波 8 呈现侧 8 文件＝71 键；treasure_interact_controller 归卡 1 | +| D3 | 同上 §三波次表＋§四纪律 | 改前建 golden 基线或对拍 0.00%；基线禁改禁 refresh；还债＝数值下降自然绿；呈现零变化 | +| D4 | [architecture](../design/engineering/architecture/architecture.md) **v1.19**「三屏壳与组合根句柄面」节（:183） | 探针挂载假设 `main.X` 路径零迁移；**S13 豁免登记在册：组合根类变量面即探针契约面（约 46 句柄被探针挂载假设钉死），max-class-variables 对本件按架构契约豁免（键永久基线内、禁再恶化），豁免理由在册本节，禁为清键改写探针挂载契约** | +| D5 | 本卡 §3 逐文件实查（2026-10-27，master 8b146321） | 现状行号与键值；**逐文件实查确认不触碰任何 owner 契约（GDD 零修订预期）——实现段查到触碰点立即停笔呈报，禁内联求裁** | +| D6 | architecture **v1.19**「测试与质量域·S13 测量面豁免登记」段（:311） | tune_sim_controller 循环内 await（测速循环逐帧让出）是调参测量的 wall-clock 步进承载语义——重构即测量口径漂移，违行为零变化红线；**该键按架构豁免（键永久基线内），禁重构测速循环**；同件 print 残留不豁免（随全清批删除） | + +## 3. 现状事实（2026-10-27 写卡会话实测于 master 8b146321；开工日 T0 复核行号） + +**S13 读数**（`python tools/gdstyle_gate.py`）：命中 216 条／基线内 216／基线外新违规 0／恶化 2（battle_orchestrator 文件行数 1314>1302＝卡 1 义务；level_map_screen 类变量 22>21＝**本卡还债义务**，iter38 卡① _layout_cache 缓存成员特批带红挂账 c4c69701）。25 文件逐文件读数见 §1 改动单元清单（gdstyle v0.4.0 实测，与清点报告 §五 2026-10-26 读数逐条吻合、行号为本次实测）。 + +**探针与测试直引面**（重构冻结面，逐条实测；v1.1 补全收拢件冻结成员——S17）： + +| # | 事实 | 出处 | +|---|---|---| +| S1 | debug_overlay 公开面被 8 探针＋系统测试直引：set_sliders/effect_text/press_apply_for_probe/press_reset_for_probe/press_simulate_for_probe/set_sim_count/visible/get_index/seed_edit；ui_tune_probe 另有**源码契约**：debug_overlay.gd 源码禁含 "create_t"/"UiKit.motion" token（零动效契约）＋子树零 AnimationPlayer | `game/probe/ui_tune_probe.gd:46-67/225-239`；`game/tests/system_test.gd:204/228/258` | +| S2 | camp_overlay_view **双重源码契约**：ui_struct_probe 源扫描 `count("UiKit.STONE") == count("UiKit.STONE_DEEP")`（裸 STONE 禁令）；theme_projection_test 源锚 `custom_minimum_size = Vector2(0, 336)` 恰 3 处、`size_flags_vertical = Control.SIZE_FILL` 恰 4 处、`SIZE_SHRINK_CENTER` ≥3 处 | `game/probe/ui_struct_probe.gd:46-50`；`game/tests/unit/presentation/theme_projection_test.gd:722-730` | +| S3 | camp_overlay 探针直引成员：_balance_label/**_tree_buy_btns/_tree_fork_btns/_workshop_holder/_workshop_rows**＋refresh_camp/closed/visible（v1.1 实查补 _balance_label——ui_probe 直读 .text 判余额文案，原 S3 漏记） | `game/probe/ui_click_probe.gd`、`ui_probe.gd:36-42`、`screen_flow_probe.gd`（grep 实测） | +| S4 | settings_overlay 探针直引：retarget/_motion_btn/_volume/find_button 面；legend_overlay：visible/close/get_index＋player_copy_sweep_test 直构 `.new()`＋`ENTRIES` 常量消费＋smoke_boot `main.get("legend_overlay")` | `game/probe/ui_click_probe.gd:286-343`；`game/tests/unit/presentation/player_copy_sweep_test.gd:69-71`；`game/tests/smoke_boot.gd:76` | +| S5 | ap_bar/log_view/info_panel/level_screen/stage/_end_overlay/board_zone/curio_overlay 探针直引成员与方法面（含私有成员 _cand_ids/_hover_id/_btn_stop/_log/_summary/_curio_section/_gp_val 等）逐条在案：press_candidate/status_badge/route_chosen/abandon_btn/press_card/press_confirm/press_continue/open_pick/is_open/verdict_text/continue_pressed/_btn_legend/_btn_stop/_dots/is_refresh_ready/confirm_visible/press_refresh_for_probe/press_confirm_for_probe/refresh_remaining_text/parsed_text/mode/armor_text/attack_text/item_slots/hero_standee/enemy_body_at/enemy_box/round_label/status_badge/legend_toggled/toast；**v1.1 补：battle_end 四句柄直读＝_btn（5 处）/_gp_name/_gp_row/_gp_val（3 处）** | `game/probe/` 八探针 grep 实测（深访问清单已录实现报告素材口径，T0 复核） | +| S6 | standee_body 直构面：fx_probe `new("enemy")`/box/set_data/set_pending/intent_probe()；standee_fx_sweep_test preload 直构＋`s2.box` 读；theme_projection 源锚四句（GOLD_BRIGHT 顺位行/HERO_BLUE_BRIGHT/GOLD_BRIGHT 护甲/`_intent_charge = pid in CHARGE_SKILL_IDS`＋GOLD_DEEP 旧判据禁句） | `game/probe/fx_probe.gd:15-30`；`game/tests/unit/presentation/standee_fx_sweep_test.gd:87-90`；`game/tests/unit/presentation/theme_projection_test.gd:689-696` | +| S7 | ap_bar_view 源锚：`UiKit.label("",UiKit.FS_CAPTION, false, UiKit.STONE_DEEP)` 逐字在位＋"STONE_FAINT" 全文零命中 | `game/tests/unit/presentation/theme_projection_test.gd:696-700` | +| S8 | ui_kit 工厂消费方普查（逐方法 grep 产品码＋probe/sim/tests，2026-10-27 实测）：**零消费＝frame_skinned/verb_button**（仅注释提及）；消费方全在本卡触面＝modal_dim（camp:45）/beams_rect（ui_assembler:104＋theme:639）/gradient_base（level_map:65＋theme:664）/switch_toggle（settings_overlay:76/:91）；测量面直引（保留公开）＝load_font＋FONT_UI（board_shot_probe:49/type_glow_shot_probe:71/ui_font_asset_test:15）；跨面消费（保留公开）＝label 137/motion 96/panel_flat 35/load_tex 35/button 44/modal_shell 9/panel_skinned 9/primary_button 7/glow 族 7/keystone_badge 5/page_shell 5/scaled 5/vignette_rect 4/tg_band 3/backdrop_tile 3/danger_button 3/icon_rect 2/bcard 2＋static var motion_scale（探针 15 处直引）/victory_fx_style | `game/presentation/views/ui_kit.gd:566/662/333/453/752/812`；grep 普查表（T0 存档） | +| S9 | ui_kit **扫描契约**：ui_contrast_probe 全 presentation 递归扫描——裸 `Color8(` 计数逐文件对空白名单（ui_kit 本体为合法定义面）、素材 preload 红线＝0；theme T5② 源锚 `UiKit.panel_flat(SLOT_BACKDROP_SOFT, PANEL_BORDER, 0, 1)`；V4 四文件（ui_kit/ui_assembler/settings_overlay/debug_overlay）源码零 "styled_slider/tooltip_theme/_tip_theme/overlay.theme" token；theme V1-V3 直接调用 button()/vignette_rect()/beams_rect()/gradient_base() 做 Linear 白名单断言 | `game/probe/ui_contrast_probe.gd:164-195`；`game/tests/unit/presentation/theme_projection_test.gd:524-535/584-668` | +| S10 | main.gd 类变量 49 个（:61-148 实数）；探针 `main.X` 一级句柄直引 46 名（run_scope/level_screen/debug_overlay/camp_overlay/settings_overlay/legend_overlay/ap_bar/log_view/info_panel/board_zone/stage/curio_overlay/_end_overlay/_start_overlay/save_select_overlay/career_overlay/status_panel/shop_overlay/node_overlay/board_view/db/meta/save_manager/settings_store/debug_badge/LAYER_CONTRACT/_modals/_deferred_modal/_confirm_consumer/_row_queue/_row_pacer/_settlement_stop_pending/_inter_overlay/_battle_root/_menu_screen/_camp_screen/_adventure_screen/_treasure_ui/_bonus/_camp_pres/_modal_flow/_tune_sim/_debug/_debug_entry/_seed_edit/confirm_dialog 等——46 名全量清单 T0 存档）；装配拆件经 root 显式传参消费 main 成员（main_ui_build/main_*_flow 五件）；**v1.1：该键按 v1.19 :183 豁免登记（组合根类变量面＝探针契约面）——面冻结，u25 任务改申报件** | `game/presentation/main.gd:61-148`；`game/probe/` 12 探针 grep 实测 | +| S11 | hud_presenter 单调用面：refresh 唯一产品消费方＝main.gd:810；tune_sim_report 唯一消费方＝tune_sim_controller.gd:67；hud_presenter_test 直测静态族（feat_holdings_lines 等）不经 refresh；**核心读取只走 settlement.presentation_snapshot() 成文快照面（头注纪律）** | `game/presentation/main.gd:810`；`game/presentation/tune_sim_controller.gd:67`；`game/presentation/hud_presenter.gd:1-14` | +| S12 | flow context 单装配面：CurioFlowContext 构造＝main_ui_build.gd:132（16 参 lambda 束，**curio_interact_controller 同行构造 `new(CurioFlowContext.new(...))`——v1.1 持 ctx 方案的装配单点**）；CampFlowContext 构造＝main_ui_build.gd:152（12 参）；成员消费＝curio_interact_controller（v1.1 改形后＝ctx 束直读，正文 16 成员读点改址）/camp_shop_presenter（:23-34 读 12 处） | `game/presentation/main_ui_build.gd:130-153`；`game/presentation/curio_interact_controller.gd:31-48`；`game/presentation/camp_shop_presenter.gd:21-34` | +| S13 | open_victory 现行 8 参（:116-117）；消费方 8 处——传可选参者 5 处须随动（main.gd:454/:459 八参、main_adventure_flow.gd:100/:166 四参、ui_struct_probe 四参），三参调用 3 处（fx_probe:53/standee_fx_sweep_test×2/curio_interact:107）缺省兼容零改动；open_defeat 不在收编账目零触碰 | grep 实测（§8 wr 行） | +| S14 | 测量面：playtest_logger print 两行（:160/:161——诊断转储路径与上下文 JSON）；同路径信息已由 toast 承载（main_debug_flow.gd:16 `show_toast("已转储诊断: "+path)`）且转储 JSONL 文件本身落盘；tune_sim_controller print 一行（:43 日志路径）＋循环内 await（:65 逐帧让出驱动浮窗进度刷新）；playtest_logger 被 4 个 sim 驱动件构造消费（adventure_monte_carlo:104/rhythm_batch:21/level_autoplay:40,118/verifier_batch:41）；**v1.1 处置定案＝print×3 删除、await 豁免（D6）** | `game/presentation/playtest_logger.gd:160-161`；`game/presentation/tune_sim_controller.gd:43/65`；`game/presentation/main_debug_flow.gd:15-16` | +| S15 | golden 现行基线集五张：棋盘三图（900×760 裁剪区）/menu_boot（全屏）/level_map（全屏，iter38 卡①改前建锚先例——对拍经 golden_compare 直跑，render_gate 现行只对拍棋盘三图＋menu_boot）；shot_probe 七屏帧（menu/settings/career/camp/level/battle/status）；加严口径＝棋盘三图裁剪区内差异一律判失效 | `game/tests/golden/README.md`；`tools/render_gate.sh` | +| S16 | level_map_screen 探针冻结成员：_cand_ids（ui_struct/ui_click 3 处）/ _hover_id（ui_input_probe:109）、_content_size（S16 公式同源锚 :152）、_layout_cache（iter38 特批债成员——layout_probe() 判同实例断言 V1/V2，本体不经成员直读）、display_probe()→_drawn_disp（绘制记录唯一读出——经方法出口）、abandon_btn/status_badge（探针直引 5+1 处） | `game/probe/ui_struct_probe.gd:157/289`、`ui_input_probe.gd:109/152`、`ui_click_probe.gd:491-492`；`game/tests/unit/presentation/level_map_info_fog_test.gd:199-230` | +| S17 | **收拢件冻结与外部契约面全集（v1.1 逐件实查，2026-10-27）**：①camp_overlay_view 探针直读 5＝_balance_label/_tree_buy_btns/_tree_fork_btns/_workshop_holder/_workshop_rows（ui_probe:36-42/ui_click_probe:70-116）；②level_map_screen 探针直读 6＝_cand_ids/_hover_id/_content_size/_layout_cache/abandon_btn/status_badge（S16＋ui_click_probe）；_runner 装配注入无直读（组合根零成员直写 grep 实测）；③board_cell_unit＝被动绘制壳：31 成员中 30 个被 board_view 直写（`u.edge = _cell` :248/:295、`u.bg_sb = sb` :710、`u.glyph = glyph` :711、`u.plate = …` :719、`u.fog_state = …` :778/:780 等 47 行实测），探针/测试直读 4＝glyph（ui_input_probe:271/:363-366）/fog_state（:400-:492 多处）/plate＋glyph_color（player_copy_sweep_test:139-142）；board_view 外产品码零直写；④standee_body 外部直访 4＝box（battle_stage_view:180/:190 直写、:367 直读、fx_probe:17/:41/:109 直写、standee_fx_sweep_test:87/:90 读）/font（:214/:217）/slot_row（:122/:204/:268）/has_world_hp_bar（ui_probe:141 直读）；⑤battle_end_overlay 探针直读 4＝_btn/_gp_name/_gp_row/_gp_val（S5 补）；组合根零成员直写；⑥debug_overlay 探针直读 3＝seed_edit（15 处）/_sim_btn/_dbg_btn（ui_tune_probe:132＋standee_fx_sweep_test:119/:121）；_run_data/_run_labels 经 run_data_probe()/update_run_data() 方法出口；⑦curio_interact_controller 探针零成员直读（_bonus 面全走方法——press_card/_curio_card_texts() 等，grep 实测） | `game/probe/` 全目录＋`game/tests/` grep 实测（逐条出处随行）；T0 复核存档 | + +## 4. 设计契约（红线，违反 = L3 停机呈报） + +🔴 **契约 1 · 呈现零变化**：一切视图/工厂/投影改动像素级零变化——§7 T0 建锚面改后对拍差异非零即红（golden 逐像素）；文案拼装逐字不变（battle_narrator_test 等现役断言零改动）；信号面、`main.LAYER_CONTRACT` 层序合同、模态编排（ModalFlow/ModalStack）、装配序零触碰；print 删除三行＝stdout 诊断文本移除（页面/toast/落盘信息零变化），禁顺手改任何 set_sim_report/报告文案。 + +🔴 **契约 2 · 探针断言面禁削弱**：S1–S7/S9/S10/S16/S17 所列探针直引公开面（方法/成员/常量/信号）逐字保留——**私有化、改名、搬文件均不进口径**；收拢件冻结成员（S17 ①–⑥）住宿主类不变不进状态件；源码锚字面量契约（camp STONE 等式与三组计数锚、ap_bar 锚句、standee 四句、debug 三句、V4 token 禁令、ui_contrast Color8/preload 扫描）随拆分逐字保持——拆分只许把锚句整行原样留在文件内，禁改写措辞、禁换行重排锚句。测试与探针随动仅限消费面迁移（访问路径改写），断言语义与判据逐条保持。 + +🔴 **契约 3 · main.X 句柄面冻结（架构豁免）**（architecture v1.19 :183 豁免登记在册）：main.gd 类变量面＝探针契约面，按架构契约豁免（键永久基线内、禁再恶化）——**禁收拢 main 句柄、禁删除成员、禁改名、禁为清键改写探针挂载契约**；`main.LAYER_CONTRACT` 常量零触碰。u25＝注记核对＋申报件（§1）。 + +🔴 **契约 4 · S13 纪律**：`tools/gdstyle_baseline.txt` 禁改禁 refresh（还债＝数值下降自然归绿；豁免键＝键留基线内绿，豁免依据在 architecture v1.19 在册，非基线注记）；本批不得引入基线外新违规——**拆出的每个私有函数与内部状态件自身在阈值内**（≤50 行/≤10 局部/≤8 分支/≤6 return/≤5 参数），批末 gate NEW=0 是验收判据；机检键与本卡契约互斥时一律停卡呈报，禁自造第三条路。 + +🔴 **契约 5 · 测试削弱申报＝零**：现役断言（单元/集成/探针/源码锚）零删除、零放宽、零缩小扫描面；测试直构面的随动改址只改访问路径；实现期任何「顺手简化断言」判红。 + +🔴 **契约 6 · 波 6 形态裁定**：视图内部拆私有函数，**不拆构建步件**——禁新建任何 .gd 文件（D1）；v1.1 内部状态件一律**宿主文件内 inner class**（`class XxxState extends RefCounted` 嵌套声明，裁决两形态〔inner class/独立小状态类〕中与零新文件相容的唯一形态）；拆分零行为变化、零新信号、零新公开成员（ui_kit 净 −6 公开方法是唯一减面）；私有函数命名与归属属代拍板白名单（§10）。 + +🔴 **契约 7 · 类变量全清与豁免边界（v1.1）**：七收拢件宿主类变量收拢后 ≤15（键消失＝S13 对账绿；u2 恶化债归绿被吸收）；main/await 两键豁免在册（D4/D6）不参与清偿；收拢只收纯状态数据与无外部直访成员，**禁为计数造转发属性/别名/空壳成员**（§13）；board_view 随动只许写入行机械改址（`u.X =` → `u.st.X =` 等价形），发现非机械改址点即停呈。 + +🔴 **契约 8 · 豁免键零重构**：tune_sim 测速循环（:65 逐帧 await）**禁重构**（D6——wall-clock 步进承载语义，重构即测量口径漂移）；main 句柄面禁收拢（契约 3）。豁免键在实现报告各申报一行（键值/依据指针 v1.19 段名/禁再恶化注记）。 + +## 5. 范围边界 + +**做**：u1–u25；消费面随动改址（§7 结构图注记行；含 board_view 写入行机械随动——u3 全清必要执行面）；T0 锚面采集；撤销证明；产出物（含豁免申报件）。 + +**不做**（去向明示）： +- 三宿主拆件（adventure_runner/level_runner/board_view 结构拆件）→ iter 39 主卡（本卡对 board_view 只做 u3 随动的写入行机械改址，禁结构触碰）；battle_orchestrator/settlement/damage_controller/treasure_interact_controller → 卡 1；core/data 侧 86 键 → 卡 2；波 7 现成卡与波 0 基线 refresh → 各自通道（本批禁自行 refresh，契约 4）； +- **不拆构建步件**（main_ui_build 分步形态不类比到普通视图——D1）；不新建任何文件（内部状态件＝宿主内 inner class——契约 6）；不动 open_defeat 与任何清单外公开方法语义； +- **main 句柄面零收拢零删除（契约 3）；tune_sim 测速循环零重构（契约 8）**——两豁免键只核对申报、不做任何键清偿动作； +- design/ 与根规则文件任何编辑 → 反哺点清单（§6）；MC/对拍锚零触碰（数值与 RNG 零改动＝零 MC，纪律 §四.4）； +- user 目检项登记不阻塞（§8.2）。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `game/tests/golden/README.md` | 乙组新建基线（camp/settings/battle 帧）判定记录＋甲组判读记录 | 批内机械同步（game 内 .md，非禁写面） | +| `game/tests/验证集清单.md` | 测试直构面随动改址不改断言语义与数量——预期零变化；若实现期补静态判据则机器提取重生成（tools/extract_checks.py） | 批内机械同步（game 内 .md，非禁写面） | +| `design/engineering/architecture/architecture.md` | 预期零修订——v1.19 两处豁免登记段在册（D4/D6 依据）；零新件、模块归属表零行变化、组合根句柄面条款不受影响；ui_kit 公开面收敛不动模块表（无 ui_kit 独立行） | 反哺点 · 列清单（预期零改动注记；实现中若发现表述漂移逐条列） | +| `待办清单.md` | 来源条目状态推进（写卡段回写归主会话；实现批收尾归 batch-closure） | 反哺点 · 列清单 | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/presentation/views/camp_overlay_view.gd` | u1 拆私有函数族＋类变量收拢内部状态件（复用既有·修改） | 非行为 → wr1 | +| `game/presentation/views/level_map_screen.gd` | u2 拆私有函数族＋类变量收拢（装饰域字典随迁状态件）（复用既有·修改） | 非行为；**恶化债归绿＋键清** → wr2 | +| `game/presentation/views/board_cell_unit.gd` | u3 拆绘制私有族＋类变量收拢（复用既有·修改） | 非行为 → wr3 | +| **随动·`game/presentation/views/board_view.gd`** | **u3 写入行机械改址约 40 行（`u.X =` → `u.st.X =`，v1.1 新增随动件——S17 ③）** | 非行为（机械改址零语义）→ wr3 | +| `game/presentation/views/standee_body.gd` | u4 拆绘制私有族＋类变量收拢（复用既有·修改） | 非行为 → wr4 | +| `game/presentation/views/hero_info_panel_view.gd` | u5（复用既有·修改） | 非行为 → wr5 | +| `game/presentation/views/battle_end_overlay.gd` | u6 拆私有＋open_victory 4 参化＋类变量收拢（复用既有·修改） | 非行为（签名收拢缺省兼容）→ wr6 | +| `game/presentation/views/debug_overlay.gd` | u7 拆五区块＋类变量收拢（复用既有·修改） | 非行为 → wr7 | +| `game/presentation/ui_assembler.gd` | u8（复用既有·修改） | 非行为 → wr8 | +| `game/presentation/views/battle_stage_view.gd` | u9（复用既有·修改） | 非行为 → wr9 | +| `game/presentation/views/curio_pick_overlay.gd` | u10（复用既有·修改） | 非行为 → wr10 | +| `game/presentation/views/settings_overlay.gd` | u11（复用既有·修改） | 非行为 → wr11 | +| `game/presentation/views/battle_log_view.gd` | u12（复用既有·修改） | 非行为 → wr12 | +| `game/presentation/curio_interact_controller.gd` | u13 引用束注入（删 16 冗余成员持 ctx）（复用既有·修改） | 非行为 → wr13 | +| `game/presentation/views/ap_bar_view.gd` | u14（复用既有·修改） | 非行为 → wr14 | +| `game/presentation/views/board_zone_view.gd` | u15（复用既有·修改） | 非行为 → wr15 | +| `game/presentation/views/board_fx_view.gd` | u16（复用既有·修改） | 非行为 → wr16 | +| `game/presentation/views/legend_overlay.gd` | u17（复用既有·修改） | 非行为 → wr17 | +| `game/presentation/views/ui_kit.gd` | u18 公开面收敛＋参数收拢（复用既有·修改） | 非行为（消费面随动改址承载撤销证明）→ wr18 | +| `game/presentation/hud_presenter.gd` | u19 参数束收拢（复用既有·修改） | 非行为 → wr19 | +| `game/presentation/curio_flow_context.gd` | u20 三束收拢（复用既有·修改） | 非行为 → wr20 | +| `game/presentation/camp_flow_context.gd` | u21 三束收拢（复用既有·修改） | 非行为 → wr21 | +| `game/presentation/battle_narrator.gd` | u22（复用既有·修改） | 非行为 → wr22 | +| `game/presentation/tune_sim_controller.gd` | u23 stats 束＋print 删除＋await 豁免申报（复用既有·修改） | 非行为（print 删除＝stdout 诊断文本）→ wr23 | +| `game/presentation/playtest_logger.gd` | u24 print×2 删除（复用既有·修改） | 非行为 → wr24 | +| `game/presentation/main.gd` | u25 豁免申报件（零改动——v1.19 :183 豁免在册，面冻结）（复用既有·零修改） | 非行为（申报）→ wr25 | +| 随动·`game/presentation/main_ui_build.gd` | u20/u21 两构造行改束传参（清单外单行随动） | 非行为 → wr20/21 | +| 随动·`game/presentation/camp_shop_presenter.gd` | u21 ctx 束读改址 12 处（清单外随动） | 非行为 → wr21 | +| 随动·`game/presentation/main_adventure_flow.gd` | u6 open_victory 四参调用改址 2 处（清单外随动） | 非行为 → wr6 | +| 随动·`game/presentation/shop_overlay_view.gd` | u18 bcard 五参调用改址 1 处（清单外随动） | 非行为 → wr18 | +| 随动·`game/presentation/views/node_overlay.gd`／`status_panel.gd`／`confirm_dialog.gd`／`settlement_review_overlay.gd` | u18 modal_shell 尾参改址各 1 处（清单外随动） | 非行为 → wr18 | +| 随动·`game/probe/fx_probe.gd` | u6 open_victory 四参改址 1 处（测量面随动） | 非行为 → wr6 | +| 随动·`game/probe/ui_struct_probe.gd` | u6 open_victory 四参改址 1 处（测量面随动） | 非行为 → wr6 | +| 随动·`game/tests/unit/presentation/theme_projection_test.gd` | u18 beams/gradient 私有化改址 2 处（断言语义不变） | 断言面随动 → wr18 | + +（零新增文件；私有函数族与内部状态件随各宿主文件内新增——落位预检见下节。） + +### 接口块 + +**T0 产出（T1–T5 取用）**：①改前 S13 读数表（25 文件 71 键现行值 `文件|规则|函数 = 值`，实现报告素材）；②golden 锚三组（甲组在库基线判读记录；乙组 camp/settings/battle 三帧基线入 `game/tests/golden/`＋README 判定记录；丙组 battle_end/curio_pick/legend/debug 直构改前帧——落临时区，批末退役）；③**S17 冻结面复核清单**（七收拢件冻结成员逐名＋board_view 直写 47 行清单——u3 随动改址的行级依据）。 + +**内部状态件形态（v1.1 收拢件统一形，u1/u2/u3/u4/u6/u7 取用）**： + +```gdscript +# 宿主文件内嵌套声明（零新文件——契约 6）；探针/外部直访冻结成员（S17）住宿主，不进状态件 +class _DrawState extends RefCounted: + var glyph_col := UiKit.INK # 纯状态数据成员逐个迁入（命名随宿主原成员） +# 宿主侧： +var st := _DrawState.new() # 状态件单成员（宿主类变量 −N+1） +# 内部读点改址：self.X → st.X（宿主私有函数族与 _draw 一并落）； +# 经方法出口的状态（fx_probe()/run_data_probe()/update_run_data()）读点随迁方法体，方法签名与返回值零变化 +``` + +**u18 ui_kit 新形态**（T3 落地，wr18 断言取用）： + +```gdscript +# 删除：frame_skinned / verb_button（全库零消费，S8 普查凭据） +# 私有化（改名加下划线，消费方随动）：_modal_dim / _beams_rect / _gradient_base / _switch_toggle +# （load_font 保留公开——board_shot/type_glow 探针与 ui_font_asset_test 三行直引，收敛算术不需要它） +# 公开方法 26→20（≤阈值，键清偿） +const PANEL_DEFAULT := true # modal_shell 面板哨兵（非 StyleBox 实例） +static func modal_shell(parent: Control, dim_color: Color, min_size := Vector2.ZERO, + separation := 12, panel_sb = null) -> Dictionary +# panel_sb == null → 无面板（原 with_panel=false） +# panel_sb == PANEL_DEFAULT → 默认样式盒面板（原 with_panel=true+panel_sb=null——settlement_review 形态） +# panel_sb is StyleBox → 自定义样式盒面板（原双参形态） +static func bcard(title: String, desc: String, band: Color, icon_path: String, opts := {}) -> BCard +# opts 键 {price: String = "", footnote: String = ""}——BCard._init 同形收拢（6→5 参） +``` + +**u19 hud_presenter 新签名**（T3/T4 取用）： + +```gdscript +static func refresh(stage: BattleStageView, info: HeroInfoPanelView, ap_bar: ApBarView, ctx: Dictionary) -> void +# ctx 五键：{settlement, runner, level_active: bool, db, refresh_remaining: int}（原 :14 尾五参收拢） +static func _refresh_out_of_battle(stage: BattleStageView, info: HeroInfoPanelView, ap_bar: ApBarView, ctx: Dictionary) -> void +static func tune_sim_report(n: int, atk_pct: int, hp_pct: int, stats: Dictionary, base_hp: int) -> String +# stats 六键：{wins: int, dmg_all: Array, hp_left_win: Array, hp_boss: Array, rounds_all: Array, death_nodes: Dictionary} +``` + +**u20/u21 flow context 新形态**（T4 取用；u13 改址同取键名）： + +```gdscript +# CurioFlowContext / CampFlowContext 同形： +func _init(db_ref, views: Dictionary, getters: Dictionary, flow: Dictionary) -> void +# views = {curio_overlay, end_overlay, board_view, toast}／camp 侧 {camp_overlay, shop_overlay, toast, start_overlay, logger} +# getters = {meta_get, save_get, adventure_get, runner_get, adventure_mode_get}／camp 侧 {meta_get, save_get, runner_get}（Callable 活引用——禁快照语义不变） +# flow = {open_modal, open_modal_after_playback, close_modal, refresh_presentations, fatal_screen, gp_summary}／camp 侧 {open_modal, close_modal, refresh_presentations} +``` + +**u13 curio_interact_controller 新形态**（T4 取用）：`_init(ctx: CurioFlowContext)` 保持——16 抄写成员删除（:32-48 赋值块），正文 `db`/`_meta_get`/`curio_overlay`/…/`_gp_summary` 读点改址 `ctx.db`/`ctx.getters.meta_get`/`ctx.views.curio_overlay`/…/`ctx.flow.gp_summary`（键名按上表）；`_pending_curio`/`_curio_context` 保持宿主。装配行 main_ui_build.gd:132 零改动（仍 `CurioInteractController.new(CurioFlowContext.new(...))`，构造参数随 u20 改束传参）。 + +**u6 battle_end 新签名**：`open_victory(verdict_line: String, continue_label: String, board_rect: Rect2, opts := {}) -> void`，opts 键 `{gp_summary: String = "", ks_summary: String = "", bonus_summary: String = "", gp_gain: int = -1, gp_total: int = -1}`。 + +**u23/u24 测量面定案（v1.1）**：playtest_logger :160/:161 两行删、tune_sim_controller :43 一行删（grep 残留＝撤销证明）；tune_sim :65 await 零触碰（D6 豁免——实现报告申报行：`tune_sim_controller 循环内 await＝v1.19 测试与质量域·S13 测量面豁免登记段在册，键永久基线内`）。 + +**u25 豁免申报件（v1.1）**：零代码改动；实现报告申报行：`main 类变量 49/15＝v1.19 呈现层装配节 S13 豁免登记在册（组合根类变量面＝探针契约面），键永久基线内、禁再恶化`；T0 核对注记在位（v1.19 :183）。 + +**T 卡间接口**：T0 产出锚面与读数表＋冻结面复核清单（全部卡取用）；T1 产出 level_map/board_cell 收拢后读数（T5 复核取用）；T3 产出 ui_kit/hud_presenter 新签名（T4 tune_sim stats 束按 u19 stats 六键构造）；各卡验收随卡落地。 + +### 落位与可复用性预检 + +| 新增件 | 复用面（为何不能复用既有） | 唯一面 | 分层与交互 | +|---|---|---|---| +| 各宿主文件内私有函数族（约 60–80 个私有函数，随拆分产生） | **零新增文件、零新增公开件**——全部落既有宿主文件内（契约 6）；私有函数非「新增件」意义上可复用单元：它们是被拆函数的原文分段，禁抽共享骨架（波 2 同款裁定精神：13 文件结构各异，强行归一有抽象层风险） | 每个私有函数唯一归属其宿主视图；禁把 helper 散落到别的文件（波 6 形态裁定） | 视图内部自调用，零跨层交互新增；Core 零 UI 不破（本批零触 core/）；随机零消费、ConfigDB 读面零新增 | +| **各收拢件宿主内 inner class 状态件（_DrawState 形，u1/u2/u3/u4/u6/u7 六件各一，新增）** | **不能复用既有件也不能跨视图共用一个状态类**：各视图绘制态/运行态彼此独立、零共用结构（camp 柜台行板登记、cell 绘制输入、standee 演出态、battle_end 行板与 fx 计数、debug 表值态各成一套，字段集无交集）——强归一共用类＝跨视图耦合＋字段冗余；也不能复用 flow context 束（那是对组合根回调的活引用束，非视图绘制态） | 每件唯一归属其宿主文件（inner class 随宿主），禁散落到别的文件（契约 6 零新文件） | 宿主内部自持有（RefCounted 值件，不进场景树、零信号），冻结成员（S17）住宿主不进件；零跨层交互新增 | +| golden 三帧基线（乙组 camp/settings/battle） | 复用 shot_probe 现成七屏帧采集面与 golden_compare.py 判据（iter38 卡① 手法）——不扩 golden_baseline_refresh.sh（工具改动超本批面） | 三帧各一，落 `game/tests/golden/`＋README 判定记录 | 采集＝探针隔离档（无断点＋出厂设置 1280）；对拍判据复用现行容差 | +| u18 `PANEL_DEFAULT` 哨兵常量 | modal_shell 六参收拢的最小形态——拆分两个函数会 +1 公开方法破 20 收敛（S8 收敛算术），哨兵是唯一不加方法的收拢形态 | 常量唯一，定义于 ui_kit | 纯 ui_kit 内部判别语义，消费方仅改传参形态 | + +### T0 事实坐实＋改前锚面采集（≈0.45d，**时点铁序：本卡全部锚面采集先于一切生产码改动**） + +- [ ] 复核 S1–S17 行号与直引清单（吸收 iter39 批漂移——若 iter39 已合回，u2/u13/u19/u25 相关行号重定位）；产出探针直引 46 名全量清单、ui_kit 消费方普查表、**S17 七收拢件冻结成员复核清单＋board_view 直写 47 行清单（u3 随动改址行级依据）**存档实现报告素材。可核查结果：复核清单在案。 +- [ ] 产出改前 S13 读数表（71 键现行值逐键）。可核查结果：读数表进实现报告素材。 +- [ ] **甲组判读**（在库 golden 五张）：跑渲染闸对拍段＋golden_compare 直跑 level_map——棋盘三图/level_map/menu_boot changed 全 0.00% 方可动码（棋盘三图按加严口径裁剪区内差异一律停机呈报）。可核查结果：判读记录进 golden/README 判定记录节。 +- [ ] **乙组建锚**（无在库基线三屏）：改前采集 shot_probe 的 camp/settings/battle 三帧→各自连采两轮逐像素比对实测跨跑次一致性＝0.00%→直拷落盘 `game/tests/golden/`（文件命名属代拍板白名单 §10.3，随 README 判定记录登记）＋README 判定记录（改前建锚、触发原因＝呈现层结构收敛批对拍锚）。**battle 帧若两轮比对非 0.00%（动效相位不确定）→ 该屏锚降级丙组直构对拍**，判定记录写明。可核查结果：三帧基线或降级注记在案。 +- [ ] **丙组改前帧**（模态/覆盖层四件）：临时抓帧脚本（--script 或临时场景，直构 battle_end_overlay.open_victory/curio_pick_overlay.open_pick/legend_overlay.open/debug_overlay 构建态，落 mktemp 临时区，禁入 git、批末退役）；同法采集改前帧存档。可核查结果：四件改前帧与采集脚本在案（脚本禁入 git）。 +- [ ] **豁免注记核对（v1.1）**：architecture v1.19 :183（组合根豁免段）与 :311（测量面豁免段）两处注记在位核对，段名与键指针抄录实现报告（u25/u23 申报件素材）。可核查结果：两段在位核对记录在案（缺位＝停卡呈报）。 + +### T1 营地与地图面拆分（≈1.6d） + +- [ ] u1 camp_overlay_view：_init 拆四柜台构建私有族、_rebuild_tree/_rebuild_forge/refresh_camp 拆行板构建私有族、七处循环体提私有构建函数；**类变量收拢**——冻结 5 成员保持（S17 ①），其余 14 个迁 `_CampState` inner class、宿主读点改 st.X；源码锚句（S2 两组）整行原样保留。可核查结果：gdstyle 单文件复扫该文件键全清（类变量 6/15 键消失）；ui_struct camp 源扫描绿；theme camp 三锚绿；camp 乙组帧对拍 0.00%。 +- [ ] u2 level_map_screen：_init/_draw_graph 拆私有族；**类变量收拢**——冻结 6 成员＋状态件保持（S17 ②），其余 16 个迁 `_MapState`（_node_icons/_noise_rect/_tint_level 在状态件内持 `_layer_decor` 域字典）；S16 冻结成员与 layout_probe/display_probe 行为逐字不变。可核查结果：单文件复扫类变量 ≤15（键消失，恶化债归绿被吸收）；level_map_info_fog_test 全绿（V1/V2 缓存断言继承）；level_map golden 对拍 0.00%。 +- [ ] u3 board_cell_unit：_draw 拆绘制私有族；**类变量收拢**——探针直读 4 成员＋_glow_layer＋状态件保持（S17 ③），board_view 直写 26 成员迁 `_CellPaintState`、board_view 写入行机械改址约 40 行（`u.X =` → `u.st.X =`，逐行对照 T0 直写清单，等价形禁改语义）。可核查结果：单文件复扫类变量 6/15 键消失＋函数级键全清；board_view 随动行 grep 对账（改址行数＝清单行数）；棋盘三图 golden 0.00%（甲组）；ui_input/player_copy 直读面回归绿。 +- [ ] u4 standee_body：_draw 拆绘制私有族、循环体提私有构建函数；**类变量收拢**——外部直访 4 成员保持（S17 ④），其余 25 个迁 `_StandeeState`（fx 出口三计数随迁，fx_probe() 方法体读点改 st.X、返回键名零变化）；standee 源锚四句（S6）逐字保留。可核查结果：单文件复扫键全清（类变量 5/15 键消失）；standee_fx_sweep_test＋fx_probe＋theme 源锚段绿。 +- [ ] 验证步骤：甲/乙组对应锚复拍（board 三图＋level_map＋camp＋battle 帧）全 0.00%；波内出红只跑红件最小单元。 + +### T2 战斗屏与覆盖层拆分（≈1.25d） + +- [ ] u5/u6/u7：hero_info_panel（段构建私有族＋槽位循环提函数）、battle_end_overlay（行板私有族＋open_victory 四参化——S13 五处传参消费点按接口块改址；**类变量收拢**——探针直读 4 句柄保持（S17 ⑤），其余 16 个迁 `_EndOverlayState`）、debug_overlay（五区块私有族——S1 全部公开面与源码契约零触碰；**类变量收拢**——直读 3 成员保持（S17 ⑥），其余 14 个迁 `_DebugState`，run_data_probe()/update_run_data() 方法体读点随迁、签名与返回零变化）。可核查结果：三文件函数级键全清＋类变量键全清（5/4/4 均键消失）；ui_tune/debug 系探针直跑绿；ui_struct/丙组 battle_end 对拍 0.00%。 +- [ ] u8–u12：ui_assembler（build_start_overlay 拆列/行私有族＋立绘循环提函数）、battle_stage_view（拆构建私有族＋_enemy_portrait_tex 查表化）、curio_pick_overlay（拆构建＋_icon_for_id 查表化）、settings_overlay（拆行私有族）、battle_log_view（_format_row 按行型拆私有格式化族）。可核查结果：五文件函数级键全清；ui_struct/丙组 curio_pick/settings 帧对拍 0.00%；reward_overlay_test/player_copy_sweep_test/theme 源锚段绿。 +- [ ] u14–u17：ap_bar（拆构建私有族，S7 锚句逐字保留）、board_zone（拆构建私有族）、board_fx（循环体提 band 构建函数）、legend（ENTRIES 循环提行构建函数）。可核查结果：四文件键清；ui_probe/ui_click ap_bar 直引面回归绿；fx_probe 直构面绿。 +- [ ] 验证步骤：乙组 battle/settings 帧＋丙组四件对拍全 0.00%；波内出红只跑红件最小单元。 + +### T3 装配与工厂件收敛（≈0.75d） + +- [ ] u18 ui_kit 按接口块落地五步：删 frame_skinned/verb_button→私有化四件（消费方改址：camp:45/ui_assembler:104/level_map:65/settings:76/:91＋theme:639/:664）→modal_shell 哨兵收拢（八消费点改址）→BCard._init/bcard opts 收拢（curio_pick:99/shop_overlay:212 改址）→beams_rect 像素循环拆私有函数。可核查结果：单文件复扫公开方法 ≤20（键清偿）、参数键全清；theme V1–V3/T5② 段绿；ui_contrast 扫描段绿（ui_kit 素材 preload=0、Color8 面零外溢）。 +- [ ] u19 hud_presenter 按接口块三签名收拢；消费方改址＝main.gd:810（ctx 五键）＋tune_sim_controller:67（stats 六键）。可核查结果：参数键三键清；hud_presenter_test＋system_test 呈现段绿；refresh 后呈现与改前逐帧同像（battle golden 帧 0.00%）。 +- [ ] u25 main.gd **豁免申报件（零改动）**：核对 T0 豁免注记核对记录；实现报告申报行落位（键值 49/15＋依据指针 v1.19 :183＋禁再恶化注记）；对 main.gd 的 diff 零行（面冻结实证）。可核查结果：git diff main.gd 为空＋申报行在案；12 探针＋system_test 全绿。 +- [ ] 验证步骤：全套闸按改动域选档跑一次全绿（里程碑步出口）。 + +### T4 交互与上下文件＋测量面定案执行（≈0.85d） + +- [ ] u20/u21 flow context 三束收拢（接口块形态）；消费方改址＝main_ui_build 两构造行＋camp_shop_presenter 12 处 ctx 读（束键访问改写，零语义变化）。可核查结果：curio_flow_context 类变量 16→4、_init 4 参（两键清偿）；camp_flow_context _init 4 参（键清偿）；ui_click/ui_struct 三选一与营地段回归绿。 +- [ ] u13 curio_interact_controller 引用束注入：16 抄写成员删除、正文读点按接口块键名改址 ctx 束；_pending_curio/_curio_context 保持（S17 ⑦——探针零成员直读实证）。可核查结果：单文件复扫类变量 3/15 键消失；ui_click/ui_struct 三选一真链段绿（press_candidate/press_confirm/press_refresh 面零变化）。 +- [ ] u22 battle_narrator bonus_card_text 拆私有文案族（battle_narrator_test 零改动全绿）。可核查结果：读数改善在案（键清）；battle_narrator_test 绿。 +- [ ] u23/u24 测量面定案执行：playtest_logger :160/:161 两行删、tune_sim :43 一行删（禁改 set_sim_report 文本）、u23 stats 束收拢（≤10 局部）；**:65 await 零触碰**（D6——禁重构测速循环）；tune_sim 链路回归＝ui_tune_probe 批量模拟段直跑绿（wall-clock/进度语义保持）。可核查结果：三行 print grep 零命中（撤销证明载体）；tune_sim 键读数＝stats/局部两键清＋await 豁免在册；u23 await 豁免申报行（依据 v1.19 :311）落实现报告。 +- [ ] 验证步骤：全套闸按改动域选档跑一次全绿。 + +### T5 撤销证明＋产出物落位卡（≈0.45d，末卡） + +- [ ] 逐 wr 行撤销证明（§8.1 末列——读数对拍类：回退该文件 hunk→对照 T0 读数表该文件键读数回升＝红→还原复绿；消费面迁移类：回退生产 hunk→随动消费方调用断红＝更强证明；print 类：回退→源码 grep 命中＝红；随动改址类〔board_view〕：回退改址 hunk→board_view 写入行对迁出成员断红）。记录进实现报告。 +- [ ] S13 批末读数对拍：gate 输出 NEW=0、WORSENED 仅 battle_orchestrator 一条、**71 键账目对账（§8.4）逐键核对＝69 键消失＋2 键豁免在册**（main 49/15、tune_sim await——两申报行落位）。可核查结果：读数对拍表＋豁免申报对账进实现报告。 +- [ ] 写齐三份产出物（实现报告〔各卡状态＋读数对照＋豁免两键申报行＋实机目检总清单——乙组三屏与丙组四态实机开合目检登记（登记不阻塞）〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）；临时抓帧脚本与丙组过程帧按中间产物纪律退役。 +- [ ] 合并前置：独立验收审计（§8.3）逐行「通过」。 + +**估时合计 ≈5.3d**（区间 5.0–5.5；v1.0 ≈4.0d 上调 ≈1.3d——收拢增量明细：u1/u2/u4 各 ≈0.15d＋u3 收拢与 board_view 随动改址 ≈0.25d＋u6/u7 各 ≈0.12d＋u13 束注入改址 ≈0.2d＋print 删除与豁免申报 ≈0.1d；超软盒预挂＝iter39 先行合回致行号重定位面扩大时 T0 +0.2d）。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +撤销证明三型：**读数型**＝回退该文件 hunk → 对照 T0 改前读数表该文件键读数回升＝红 → 还原复绿（结构拆分与收拢单元的断言载体）；**迁移型**＝回退生产 hunk → 随动消费方调用断红（签名/改名/束注入单元的更强证明，迁移不对称作断言）；**grep 型**＝print 删除类，回退 → 源码 grep 命中＝红。对拍锚＝T0 三组（甲：棋盘三图/level_map/menu_boot；乙：camp/settings/battle 帧；丙：battle_end/curio_pick/legend/debug 直构帧）。**收拢件断言三件套（v1.1）＝S13 键消失（类变量计数对账绿）＋golden 逐像素 0.00%＋探针冻结面断言零变化（S17 冻结成员直引面回归绿）**。 + +| 需求点 | 改动（文件） | 验收测试（名称＋落点） | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 u1 营地覆盖层拆分＋收拢 | camp_overlay_view | S13 键消失（10 键清：函数级 9＋类变量）；S17 ① 冻结 5 成员断言零变化；ui_struct camp 源扫描＋theme camp 三锚；乙组 camp 帧对拍 0.00% | 静态＋探针＋golden | ui_struct_probe 真实驱动＋shot_probe 帧 | 读数型＋锚句 grep | +| wr2 u2 关卡地图拆分＋收拢 | level_map_screen | S13 键消失（6 键清：函数级 5＋类变量≤15）；S16/S17 ② 冻结成员断言零变化；level_map_info_fog_test（V1/V2 继承）；level_map golden 0.00% | 静态＋单元＋golden | open_choices 真实入口（测试白盒夹具） | 读数型 | +| wr3 u3 棋盘格单元拆分＋收拢＋board_view 随动 | board_cell_unit（＋随动 board_view 写入行约 40 行） | S13 键消失（4 键清：函数级 3＋类变量）；S17 ③ 探针直读 4 成员断言零变化；board_view 改址行 grep 对账；迁移型断言（回退随动 hunk→写入行断红）；棋盘三图 golden 0.00%（甲组） | 静态＋探针＋golden | board_shot_probe 真实抓帧＋ui_input/player_copy 直读面 | 读数型＋迁移型 | +| wr4 u4 站桩拆分＋收拢 | standee_body | S13 键消失（4 键清）；S17 ④ 外部直访 4 成员断言零变化（box/font/slot_row/has_world_hp_bar）；fx_probe＋standee_fx_sweep_test；theme 源锚四句 | 静态＋单元＋探针 | fx_probe 直构真链 | 读数型＋锚句 grep | +| wr5 u5 信息面板拆分 | hero_info_panel_view | S13 读数（4 键清）；player_copy_sweep_test；ui_probe info_panel 直引面 | 静态＋单元＋探针 | 直构＋探针真链 | 读数型 | +| wr6 u6 战末覆盖层＋open_victory 收拢＋类变量收拢 | battle_end_overlay（＋随动 5 消费点） | S13 键消失（4 键清：函数级 3＋类变量）；S17 ⑤ 四句柄断言零变化；迁移型断言（回退→五消费点断红）；丙组对拍 0.00%；t17_defer/ui_struct/ui_probe _end_overlay 面绿 | 静态＋探针＋golden | ui_struct_probe open_victory 真链 | 迁移型 | +| wr7 u7 调试浮窗拆分＋收拢 | debug_overlay | S13 键消失（3 键清：函数级 2＋类变量）；S17 ⑥ 三成员断言零变化（seed_edit/_sim_btn/_dbg_btn）；ui_tune_probe 全段（公开面＋零动效源码契约）；system_test 调试段；theme V4/debug 源锚 | 静态＋探针＋系统 | ui_tune_probe 真实驱动 | 读数型＋契约 grep | +| wr8 u8 装配器拆分 | ui_assembler | S13 读数（3 键清）；theme V4/退役判据段；ui_probe 启动态 | 静态＋单元＋探针 | shot_probe 启动态真链 | 读数型 | +| wr9 u9 战斗舞台拆分 | battle_stage_view | S13 读数（3 键清）；ui_probe stage 直引面；乙组 battle 帧对拍 | 静态＋探针＋golden | 探针真链 | 读数型 | +| wr10 u10 三选一覆盖层拆分 | curio_pick_overlay | S13 读数（2 键清）；reward_overlay_test；丙组对拍 0.00%；ui_struct/ui_click curio 段 | 静态＋单元＋探针＋golden | 直构＋探针真链 | 读数型 | +| wr11 u11 设置覆盖层拆分 | settings_overlay | S13 读数（2 键清）；乙组 settings 帧对拍；ui_click 设置段＋theme V4 | 静态＋探针＋golden | 探针真链 | 读数型 | +| wr12 u12 结算日志拆分 | battle_log_view | S13 读数（4 键清）；theme_projection :386 直构断言＋player_copy :100 | 静态＋单元 | 直构真链 | 读数型 | +| wr13 u13 三选一交互件引用束注入 | curio_interact_controller（＋main_ui_build:132 构造行随 u20 束形态） | S13 键消失（类变量 3/15）；迁移型断言（回退→ctx 束读点断红）；S17 ⑦ 探针方法面零变化；ui_click/ui_struct 三选一真链段 | 静态＋探针 | 装配真实构造链＋探针真链 | 迁移型 | +| wr14 u14 AP 条拆分 | ap_bar_view | S13 读数（1 键清）；S7 源锚逐字；ui_probe/ui_click ap_bar 直引面 | 静态＋探针 | 探针真链 | 读数型＋锚句 grep | +| wr15 u15 棋盘区容器拆分 | board_zone_view | S13 读数（1 键清）；board_zone 直引面（status_badge/legend_toggled/toast） | 静态＋探针 | 探针真链 | 读数型 | +| wr16 u16 棋盘动效循环提函数 | board_fx_view | S13 读数（1 键清）；fx_probe 逻辑层＋棋盘三图 golden（fx 不入静止帧对拍） | 静态＋探针＋golden | fx_probe 真链 | 读数型 | +| wr17 u17 图例循环提函数 | legend_overlay | S13 读数（1 键清）；player_copy_sweep 直构＋ui_struct legend 段；丙组对拍 | 静态＋单元＋探针＋golden | 直构＋探针真链 | 读数型 | +| wr18 u18 ui_kit 公开面收敛 | ui_kit（＋随动 6 文件：theme/shop_overlay/node_overlay/status_panel/confirm_dialog/settlement_review_overlay） | S13 读数（5 键清）；迁移型断言（回退→随动消费点断红）；theme V1–V3/T5②＋ui_contrast 扫描；menu_boot/camp/battle 帧对拍 | 静态＋单元＋探针＋golden | theme 直构真链＋探针 | 迁移型 | +| wr19 u19 HUD 投影参数收拢 | hud_presenter（＋main:810/tune_sim:67） | S13 读数（3 键清）；迁移型断言；hud_presenter_test＋battle golden 帧 | 静态＋单元＋golden | 真实 refresh 调用链 | 迁移型 | +| wr20 u20 三选一流上下文收束 | curio_flow_context（＋main_ui_build:132） | S13 读数（2 键清）；迁移型断言；ui_click 三选一段 | 静态＋探针 | 装配真实构造链 | 迁移型 | +| wr21 u21 营地流上下文收束 | camp_flow_context（＋main_ui_build:152/camp_shop_presenter） | S13 读数（1 键清）；迁移型断言；ui_click 营地段 | 静态＋探针 | 装配真实构造链 | 迁移型 | +| wr22 u22 叙述件拆分 | battle_narrator | S13 读数（1 键清）；battle_narrator_test 零改动全绿 | 静态＋单元 | 直构真链 | 读数型 | +| wr23 u23 批量模拟控制器＋测量面定案 | tune_sim_controller | S13 读数（print＋局部两键清；await 豁免在册）；print grep 零命中；**await 豁免申报行**（非行为改动＋依据指针 v1.19 :311）；ui_tune_probe 批量模拟段（进度/报告语义零变化） | 静态＋探针 | ui_tune_probe 真实驱动 | 读数型＋print grep | +| wr24 u24 试玩日志器 print 删除 | playtest_logger | S13 读数（1 键清）；print grep 零命中；sim 四驱动件直构回归＋诊断转储 toast 链 | 静态＋集成 | main_debug_flow 转储真链 | grep 型 | +| wr25 u25 组合根豁免申报 | main.gd（零改动） | **豁免申报行**（非行为改动＋依据指针 v1.19 :183）；git diff main.gd 为空（面冻结实证）；S10 46 名直引面断言零变化；12 探针＋system_test 全绿 | 静态＋探针＋系统 | 探针 main.X 真链 | 零改动实证（diff 空）＋申报件核 | +| wr26 产出物 | T5 三份（含豁免两键申报行） | 件核（wr26） | — | — | 缺项红 | + +### 8.2 测试方式两分法与目检登记 + +本批零行为改动＝无调试接口验证项；能力面（debug_overlay/批量模拟）经 ui_tune_probe 真链回归即闭环。用户目检项（登记不阻塞，入实现报告实机目检总清单）：乙组三屏（camp/settings/battle）开合观感、丙组四态（战末/三选一/图例/调试浮窗）开合观感、营地三柜台与锻造工坊交互回归——全部为「与改前一致」判读。 + +### 8.3 独立验收审计 + +入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`；抽查重点＝①T0 时点铁序（锚面采集先于码改——git 提交序核）②golden 对拍读数复现（抽 3 锚直跑）③S13 读数对拍表逐键复核＋基线文件 git diff 零变化＋**71＝69 清＋2 豁免账目复核（豁免两键依据指针 v1.19 段名在册）**④源码锚字面量契约抽检（S2/S6/S7/S9）⑤撤销证明抽两条复现⑥探针直引 46 名＋S17 冻结成员零迁移抽检⑦**board_view 随动改址抽 5 行复核（等价机械形、零语义漂移）**⑧main.gd git diff 为空＋await 行零触碰复核。未过不得合并。 + +### 8.4 S13 账目（71 键＝69 清＋2 豁免，v1.1 全清口径） + +**清偿 69 键（键消失）**：u1×10／u2×6／u3×4／u4×4／u5×4／u6×4／u7×3／u8×3／u9×3／u10×2／u11×2／u12×4／u13×1／u14×1／u15×1／u16×1／u17×1／u18×5／u19×3／u20×2／u21×1／u22×1／u23×2（print＋run 局部）／u24×1。（69＝10+6+4+4+4+4+3+3+3+2+2+4+1+1+1+1+1+5+3+2+1+1+2+1，逐项与 §1 改动单元清单一一对应。） + +**豁免 2 键（键留基线内绿、永久在册、禁再恶化——非残留，架构契约豁免）**：main 类变量 49/15（v1.19 :183——组合根类变量面＝探针契约面，禁收拢禁改写）＋tune_sim_controller 循环内 await :65（v1.19 :311——测速循环 wall-clock 步进承载语义，禁重构）。两键各落实现报告申报行（wr23/wr25）。 + +回归措辞：里程碑步（T 卡段）出口跑一次全套闸；波内修复只做出红最小单元的最窄确认；新增测试/工具先行孤立验证再并入全套。 + +## 9. 异常分级 + +- **L1（自救）**：行号漂移（T0 复核自吸收）；私有函数命名、inner class 状态件命名与注释措辞；对拍帧采集的等价实现形态（探针帧直拷 vs 临时脚本）。 +- **L2（记录继续）**：乙组 battle 帧跨跑次非 0.00% 降级丙组（判定记录写明）；消费面随动改址的单行等价写法（含 board_view 写入行 `u.st.X =` 等价形）；读数改善幅度与预估偏差（非清键义务单元）；u4 fx 出口计数随迁后 fx_probe() 返回键序变化（键名零变化前提下）。 +- **L3（停机呈报）**：任何 golden 对拍差异非零（契约 1）；探针直引面/源码锚契约与拆分或收拢互斥（契约 2——S17 冻结成员被误迁状态件即属此）；board_view 改址遇非机械点（写入行与读取交织/条件内联——契约 7）；main 句柄面出现任何改动企图、测速循环重构企图（契约 3/8）；机检键与契约互斥（契约 4）；拆分或收拢产生基线外新违规且不可在阈值内消化（契约 4）；发现收编清单外同病根新键（禁扩面——呈报由用户裁）；**逐文件实查发现触碰 owner 契约/GDD 陈述**（D5——停笔呈报，禁内联求裁）；豁免注记（v1.19 两段）缺位或段名漂移（T0 核对不通过）。 + +## 10. 代拍板白名单（超清单必呈报） + +1. 各宿主内私有函数命名、分组与注释随迁措辞（语义不变前提下）。 +2. 各收拢件 inner class 状态件命名（`_XxxState` 形）与件内成员命名（随宿主原成员名迁入）。 +3. 乙组基线帧文件命名（随 golden/README 现行命名规则）与丙组临时采集脚本的实现形态。 +4. wr 断言挂点与读数表格式。 +5. 提交切分与 worktree 分支命名。 +6. u23/u25 豁免申报行的行文措辞（键值/依据指针/禁再恶化三要素在案前提下）。 + +## 11. 待裁点 + +**零待裁点（2026-10-27 用户裁决记录：print 删除；await 按 v1.19 测量面豁免）**。 + +（原 W1 测量面卫生键处置已按裁决落死——print×3 删除〔信息已由 toast/JSONL 承载，见 S14/D6〕、循环内 await 按 v1.19「测试与质量域·S13 测量面豁免登记」段豁免〔键永久基线内、禁重构测速循环〕；main 类变量按 v1.19「三屏壳与组合根句柄面」节豁免登记。三项处置全部进 §1 单元清单与 §8.1 对照表，无需实现段再裁。） + +## 12. 自审六查与复核记录 + +**自审六查（2026-10-27 写卡会话）**：①规格覆盖——u1–u25→wr1–wr25 逐条对上、T0–T5 各卡可指认、恶化债/锚面/裁点各有落点；②步骤扫描——每步一动作一可核查结果，接口块给签名不给实现体，无「TBD/酌情」行（T0 乙组降级分支为带判据的条件路径非酌情）；③类型一致性——接口块签名与 §3 实查、wr 行、T3/T4 取用关系逐字一致（refresh ctx 五键＝main:810 现八参尾五；stats 六键＝tune_sim:67 现十参中六；S17 冻结成员清单与 §1 收拢列逐件对上）；④审查焦点——呈现零变化（三组锚）与探针直引面（S1–S17）为最可能坑点，已逐文件挂 wr 行与契约 2；行为改动覆盖：本批零行为改动，print 删除（stdout 文本——wr23/24 以 grep 与 ui_tune 真链承载）；⑤篇幅比例——零实现体抄写，接口块全为签名与键清单；⑥落位预检——零新增文件原则下四件新增面（私有函数族/inner class 状态件/golden 基线/PANEL_DEFAULT 哨兵）各有不能复用理由与唯一落点，与结构图对上。 + +**grilling 自检一轮（2026-10-27，写卡会话内对抗复核）折入记录**：①收敛算术复核——ui_kit 26−2−4＝20 成立（modal_shell 哨兵收拢不增方法；拆分方案会 21 超阈，已弃）；②open_victory 三参消费点缺省兼容免改址（fx_probe/standee_fx_sweep/curio_interact）——S13 改为「传参者 5 处随动」；③level_map 恶化债归绿判据写死 ≤21（gdstyle 判红线＝登记值 21，「回到登记值以下」歧义消除）；④撤装置教训回扣——u2 换层装饰域归并禁计数迎合（契约 7 显式禁转发/别名，_cand_ids/_hover_id/_content_size/_drawn_disp 四探针直引成员排除出归并候选）；⑤撤销证明两型分层（读数型/迁移型）补强——纯拆分文件回退后现役套件仍绿，读数对拍表是唯一断言载体，已在对照表末列写死；⑥补 S16（level_map 探针冻结成员清单）与 §8.4 残留键账目——完成定义第 1 条账目闭合；⑦**load_font 私有化撤换（实查翻案）**——初稿拟私有化 load_font，逐消费方复核发现其直引含两处渲染闸探针（board_shot_probe:49/type_glow_shot_probe:71）＋ui_font_asset_test:15，私有化须动渲染闸探针；换选 switch_toggle（消费方 settings_overlay:76/:91 全在本卡触面、零探针测试面），收敛算术不变、随动面缩 3 行且零探针触碰——S8/接口块/T3/wr18/结构图五处随改；⑧W1 案① tune_sim print 处置收紧为「删除」并禁改 set_sim_report 文本（并入报告文本属文案变化，违契约 1 文案逐字不变）；⑨乙组基线帧命名改挂代拍板白名单（初稿行内命名自造，禁行句式剔除）。 + +**v1.1 修订自审六查（2026-10-27 裁决折入会话）**：①裁决覆盖——四条款逐条落位：全清口径→§1 目标/§8.4 账目（69＝62＋7 类变量键，逐件累加核过）；print 删除→u23/u24 改法列＋T4＋wr23/wr24；main/await 豁免→D4/D6＋契约 3/8＋u23/u25 任务改写＋wr23/wr25 申报行；大户收拢→u1/u2/u3/u4/u6/u7/u13 改法列＋接口块状态件形态＋T1/T2/T4 任务行；②步骤扫描——收拢任务每件带「冻结成员保持＋迁件清单＋可核查结果（键消失＋冻结面断言零变化＋对拍 0.00%）」三段，无酌情行；u3 随动带 T0 行级清单前置；③类型一致性——S17 冻结清单与 §1 收拢列、契约 2、wr 行三处逐名一致（camp 5/level_map 6/board_cell 4/standee 4/battle_end 4/debug 3/curio_interact 0）；u13 改址键名与 u20 接口块束键逐字同源；④审查焦点——冻结面补全是本轮最大坑点：原卡 S3/S5 漏记直读成员（camp _balance_label、battle_end _btn/_gp_name/_gp_row/_gp_val、debug _sim_btn/_dbg_btn、standee has_world_hp_bar），若按原清单收拢即探针断红——v1.1 已补全 S17 并挂契约 2；board_view 禁触冲突为第二坑点（board_cell 30/31 成员被其直写），按裁决全清口径的唯一路径落机械随动＋错波扩展＋L3 兜底（§0/§5/契约 7/§9 四处闭环）；⑤篇幅比例——收拢清单以成员名列举进 §1/S17，零实现体；⑥落位预检——inner class 状态件六件各填「为什么不能复用」（各视图绘制态彼此独立无共用结构；与 flow context 束异质），零新文件保持。 + +**v1.1 grilling 自检一轮（同会话对抗复核）折入记录**：①**board_cell_unit 被动壳定性（实查翻案）**——31 成员逐名核外部直访：30 个被 board_view 直写 47 行＋探针直读 4 个皆在写入集内，纯内部仅 _glow_layer；按「句柄成员不收」判据本无收拢面，但裁决全清口径下唯一路径＝写入行随动改址（约 40 行机械形）——落 u3＋§0 禁触条目收窄（board_view 结构拆件仍禁、错波集扩五文件）＋契约 7 非机械点停呈＋§8.3 抽 5 行复核；②**探针直读成员非全部冻结（出口判据补强）**——fx 出口三计数（_death_shards/_hit_sparks/_flash_count 经 fx_probe() 方法）与 _run_data/_run_labels（经 run_data_probe()/update_run_data() 方法）不被字段直访，判可收拢、方法体读点随迁——判据句（字段直访冻结/方法出口可收）写进接口块状态件形态注记；③**curio_interact 冗余面发现（实查翻案）**——16 个注入成员＝_init(ctx) 逐成员抄写件（:32-48 实读），与 ctx 完全同源；u20 三束后直接持 ctx＝3 成员，比原「域归并改善非清零」方案更彻底且零新概念（构造注入先例形态），S12/u13/wr13 三处随改，装配行零随动；④**u25 死成员清点任务随豁免取消**——豁免语义＝类变量面冻结（契约 3），清点删除动机（键清偿）消失；wr25 改零改动实证（git diff 空）＋申报行，避免豁免与清点并存的面语义打架；⑤**69 清账目复核**——v1.0 清偿 62 键构成重算（u23×2＝print＋run 局部，await 另计残留）＋七件类变量键（u1/u2/u3/u4/u6/u7/u13 各＋1）＝69，与豁免 2 键合计 71 对平；u13 原在清偿列 0 键（改善非清零），v1.1 转 +1——清单逐项累加在 §8.4 留痕；⑥**估时逐件落账**——上调 ≈1.3d 拆到八笔（u1/u2/u4 各 0.15＋u3 0.25＋u6/u7 各 0.12＋u13 0.2＋print/申报 0.1），防整段模糊上调；T0 冻结面复核扩容（S17 七件＋board_view 47 行清单）计 +0.05d；⑦**契约 6 与裁决两形态冲突收口**——「独立小状态类」需新 .gd 文件违 D1，inner class 相容——卡内定死 inner class 单形态（裁决给的是形态自由、契约 6 是硬红线，取交集）；⑧**冻结成员补全反推（原卡 S 清单缺陷）**——S3 原记 camp 四成员漏 _balance_label（ui_probe:36 直读 .text），若按原清单收拢即探针断红；S5 原为方法面汇总未展开 battle_end 四句柄直读（_btn 5 处/_gp_val 3 处）；debug _sim_btn/_dbg_btn（ui_tune:132＋standee_fx_sweep_test:119/121）、standee has_world_hp_bar（ui_probe:141）、level_map abandon_btn/status_badge（ui_click 直引）同为实查新增——八处全部补进 S3/S5/S6/S16/S17，冻结面口径由「探针公开方法面」扩为「字段直访全集」。 + +## 13. 禁为机检文本保留无效成员（重构类必填条款） + +禁止为迎合机检消息文本（含计数）而保留或新增无效成员/别名/转发属性；本批收敛（拆分＋收拢）不得以「探针便利」「基线计数」为由保留任何清单外死成员或新增同种装置；u1–u7/u13 收拢与 u2 归并、u25 申报的每一笔处置必须以 S17 实查冻结面或真实零消费为凭据（对账表在案）；禁以转发属性形态「保住」被收拢成员的外部写法（字段直访契约面一律随动改址或冻结保持，二选一，无第三态）；机检键与本卡契约互斥时实现段一律停卡呈报，不得自造第三条路（code-conventions §1.1 同款）。 diff --git a/reports/需求卡片-核心数据面结构收敛批-2026-10-27.md b/reports/需求卡片-核心数据面结构收敛批-2026-10-27.md new file mode 100644 index 00000000..374ddbed --- /dev/null +++ b/reports/需求卡片-核心数据面结构收敛批-2026-10-27.md @@ -0,0 +1,354 @@ +# 需求卡片：核心数据面结构收敛批（gdstyle 存量债清偿·卡 2——数据校验族／生成器族／效果引擎／core-data 散条 86 键） + +- 版本：**v1.1**（写卡段修订成文——2026-10-27 用户全清裁决四项折入＋拆件面实查补全；自审六查与 grilling 自检一轮记录见 §12） +- 来源：[待办清单](../待办清单.md)「gdstyle 存量债全量清偿——216 键按病根分波整改」条目（2026-10-26 登记，P0，状态=文档设计已闭合＋已写卡）（唯一事实源：清点报告 [审计-gdstyle存量债清点与清偿方案-2026-10-26](审计-gdstyle存量债清点与清偿方案-2026-10-26.md) §六第 2／3／4／7 条裁定——证据指认形态，见 §2） +- 归并账目（清点报告 §六第 7 条）：本卡收编＝**波 2（40 键／13 文件）＋波 4（17 键／2 文件）＋effect_engine（8 键）＋波 8 core/data 侧 10 文件（21 键）＝86 键／26 文件**；与卡 1（B1 战斗域拆件批 45 键）、卡 3（呈现层结构收敛批 71 键）账目闭合 45＋86＋71＝202＋三宿主规避 14＝216。**2026-10-27 用户全清裁决：86 键全部清零**——v1.19 在册豁免仅两处（组合根 main 句柄面／测量面 tune_sim await），均不在本卡文件集，本卡零豁免零残留 +- 归属：`game/data/schemas/` 12 文件＋`game/core/` 14 文件＋`game/data/tables/adventure.tres`（等值迁移）＋**新件 8**（`game/core/config_domain_combat.gd`／`config_domain_run.gd`／`config_domain_crossrun.gd`／`slot_store.gd`／`meta_state_store.gd`＋`game/data/schemas/adventure_quota_segment.gd`／`adventure_value_segment.gd`／`adventure_cap_segment.gd`）＋消费方改址（`game/core/`、`game/presentation/`、`game/tests/`、`game/probe/`、`game/sim/` 约 60 文件，实查合计 ≈1330 处——§3.5 分面计数） +- 排期：未编入（迭代批卡片；预配迭代 41——卡①与波 7 迭代 40 先行合回，串行序见 §0；估时 **≈7.9 个工作日，区间 7.4–8.4**，逐 T 卡实估见 §7；超迭代冻结线 5 个工作日——编入时循迭代 39 特批先例由用户裁） +- 开工门：U0＋复核门过（§12）——零待裁点（2026-10-27 用户裁决落定，§11） + +## 0. 前置依赖与并行性 + +- **第〇步核对（2026-10-27 写卡会话）**：来源条目＝需求性工程条目（整行无设计线段、首段落「文档设计已闭合＋已写卡」）——逐波裁定（清点报告 §六第 1–6 条）＋2026-10-27 整合裁定（§六第 7 条）＋2026-10-27 全清设计补课（架构 v1.19）即证据指认，放行。 +- **全清裁决（2026-10-27 用户，本卡修订依据，实现段零裁断）**：①config_db 双键（公开方法 44／类变量 25）彻底清零＝行族访问器归位各 schema 表类＋表持有成员按域收进域容器 Resource；②save_manager 52／meta_progression 31 彻底清零＝SlotStore／MetaStateStore 拆件（架构 v1.19 :89/:90 行已登记）；③adventure_table 类变量 44 拆子 Resource 段（形态同 settlement_table 拆段——嵌套段单 .tres 保持）；④unit_container spawn 参数 10 签名引用束化。红线不变：ConfigDB 仍是唯一加载与持有单点（架构 :88 定稿注记口径）。 +- **卡间串行（迭代 40 先行合回）**：卡①文件集（battle_orchestrator／grant_segment／combat_segment／settlement_table／damage_controller／treasure_interact_controller＋BattleFxHost／RewardGrant 两新件）与波 7 现成卡（结构小件定点修批 v1.3，同触 board_generator.gd／reward_economy.gd 两 `_fatal`）在迭代 40 先行合回——本卡改址 battle_orchestrator 的 spawn 调用点按**卡①合回后形态**（行号 T0 重锚）；本卡对 board_generator／reward_economy 两文件的拆分行号**禁照搬 §3 锚**，一律 T0 重核（后行者吸收漂移义务，波 7 卡自带同款）。 +- **spawn 参数键入本卡（K6′）**：签名束化必改全部调用方——battle_orchestrator 调用点经卡①（迭代 40）先行收敛，本卡（迭代 41）改址顺路；v1.0 的「卡间零交叠留残」义务随串行序解除。 +- **与卡③（呈现层结构收敛批）触碰＝呈现侧改址行**：hud_presenter／camp_shop_presenter／main／save_select_overlay／treasure_interact_controller 等文件的访问点换址（纯改址、无结构改动）——编排错波，后行者 T0 吸收漂移（迭代 39 副卡同款先例）。 +- **与迭代 39 两卡（已编）的文件触碰**：副卡（同调配装充能域封装批）触 effect_engine.gd（仅 :94 注释面 RunLedger 表述清）与 meta_progression_forge_test.gd（:290-291 直构改址）——本卡重构 effect_engine.gd 本体并改址同一测试文件的其他行；同文件异行域，编排错波（39 先于 41），后行者 T0 吸收行号漂移。 +- **PARITY／MC 纪律**：本批零数值改动、零 RNG 流改动、零 PARITY 触面（S8_FILES／PARITY_TOUCH_FACES 零命中）→ 零 MC、零对拍补跑。存档面等价由现役 save 断言面＋读写逐位断言承载（wr6），不属对拍补跑。 + +## 1. 目标与完成定义 + +**目标**：86 键收编文件的结构债**全数清偿**——①数据校验族 13 文件 validate()／cross_validate() 按校验域拆私有函数族（2026-10-26 用户裁：各文件内部拆、不抽共享骨架）；②生成器族两件拆私有阶段函数（RNG 消费序冻结）；③effect_engine 拆解释器与校验私有域（全同步语义、装载声明序、四词表封闭零变化）；④**config_db 归位＋域容器**：35 个行族/resolve/门控访问器归位各 schema 表类（表管自己的行查询）、19 个表持有成员按域收进 3 个域容器 Resource，ConfigDB 只剩加载/校验/override/诊断门面；⑤**存档域拆件**：SlotStore（槽位文件域）＋MetaStateStore（存档内元进度数据读写唯一层）建件收编，save_manager 瘦身剩磁盘 IO＋版本迁移链＋断点族＋门面，meta_progression 纯转发读退役、业务规则与写口编排留置（封闭面 20）；⑥波 8 core/data 散条按 K 清单收敛（adventure_table 拆段、action_economy 删并、spawn 束化、其余拆分/私有化）。**游戏行为零变化**（契约 1）。 + +**清偿账目**：86 键全清——校验族 40＋生成器族 17＋效果引擎 8＝65 键由文件内私有拆分清偿（gdstyle 直扫键消失，闸读数下降自然绿）；波 8 core/data 侧 21 键由结构收敛清偿：config_db 44＋25 两键＝归位＋容器（44→8／25→9）、save_manager 52＝拆件（52→7）、meta_progression 31＝瘦身（31→20）、adventure_table 44＝拆段（44→12）、action_economy 18＝删并（18→15）、unit_container spawn 参数＝束化（10→1）、save_manager `_peek_summary_at`／load_from_disk 返回键与 meta_progression tree_can_buy 返回键＝留置函数原位拆分清偿。新件 8 封闭面全部在阈（§7 预检逐件核验），零基线外 NEW。 + +**完成定义**： +1. §7 结构图全部行落地（含 8 新件）；`tools/gdstyle_gate.py` 改前改后读数对拍：**基线外 NEW＝0（含新件）、恶化＝0、在案键计数较 216 下降 86**（86 键消失清单＋新件键账表进实现报告）； +2. 行为等价证据齐：数据校验族断言面（data_config 八套件＋core 直引 12 文件）全绿；生成器同种子逐位一致（现役 determinism 断言继承）；效果引擎现役四套件全绿；**存档读写逐位等价**（save 现役断言面改址保持全绿——原子写/兜底/拒读/迁移链语义零变化）； +3. 撤销证明逐 wr 行落地（§8.1 末列）；三份产出物写齐（T10）；独立验收审计过。 + +## 2. 设计事实源 + +| # | 出处 | 取用条款 | +|---|---|---| +| D1 | 待办清单条目「gdstyle 存量债全量清偿」（需求性工程条目证据指认） | 波次框架、纪律、本卡放行凭据 | +| D2 | 清点报告 §六**第 2 条**（波 2 形态＝各文件内部拆校验域私有函数族、不抽共享骨架、零新概念零架构登记） | 校验族拆分形态 | +| D3 | 清点报告 §六**第 3 条**（全部波不改游戏规则与玩家可见行为；design/gdd/systems/ 零修订预期） | 行为零变化总纲 | +| D4 | 清点报告 §六**第 4 条**（波 8 config_db 公开方法收敛＝纯代码删冗余/私有化） | **已被 D7 取代**——方法集由「删冗余/私有化」扩为「归位＋域容器」（2026-10-27 全清裁决），本行仅存账目沿革 | +| D5 | 清点报告 §六**第 7 条**（2026-10-27 整合裁定：本卡＝波 2＋波 4＋effect_engine＋波 8 core/data 侧＝86 键；文件交叠冲突归零） | 收编范围与卡间边界 | +| D6 | 2026-10-27 写卡会话**逐文件实查声明**：26 收编文件全数实读＋gdstyle 0.4.0 直扫复测（读数与 2026-10-26 基线零漂移）；公开面消费方 grep 全域核验；未发现触碰任何 owner 契约／GDD 陈述的病根——三处文档机械指址漂移（§6 反哺点承载，陈述本体不变） | 本卡写法③证据基座 | +| D7 | **2026-10-27 用户全清裁决四项**（§0 抄录；待裁点 1 案 B 变体＝归位＋域容器 Resource〔非词典化〕、待裁点 2 案 B＝域对象拆件经设计段先行定稿） | config_db／save／meta／adventure／spawn 五面的清偿深度与形态 | +| D8 | `design/engineering/architecture/architecture.md` **v1.19**：:88 ConfigDB 行定稿注记（行族访问器归位＋域容器持有＋「经 ConfigDB 单点读取＝经其持有的表对象」口径）；:89 SlotStore 行；:90 MetaStateStore 行（「数据读写原语族＋只读投影」——本卡 K2′ 读投影设计的直接依据）；:126 meta_progression 行定稿注记（纯转发读退役＋业务规则与写口编排留本类 ≤20＋tree_can_buy 留公开对外暴露列）；:183 组合根 S13 豁免在册（本卡改址经 `main.save_manager` 既有句柄、零新增句柄成员——豁免面不扩大） | 拆件设计与红线口径的唯一架构凭据 | + +## 3. 现状事实（2026-10-27 写卡会话实查于 master 8b146321，gdstyle 0.4.0 直扫——与基线零漂移；修订会话复测于 be2f6ca6，两次提交均为写卡文档面、代码零漂移。开工日 T0 复核行号——迭代 40 卡①/波 7 合回后全表重锚） + +### 3.1 数据校验族（波 2，40 键／13 文件） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/data/schemas/meta_tree_table.gd` | validate 长度 86/50·分支 26/8·局部 13/10·嵌套 5/4 | :27-111（单循环体＋requires/requires_level/彩蛋三尾段） | +| `game/data/schemas/treasure_item_table.gd` | validate 长度 147/50·分支 44/8·局部 26/10·嵌套 6/4 | :61-206（行头校验／活行校验／同调行校验三段可分，:104 调 EffectEngine.validate_trigger_row） | +| `game/data/schemas/board_gen_table.gd` | validate 长度 67/50·分支 20/8·局部 16/10 | :14-81 | +| `game/data/schemas/enemy_table.gd` | validate 长度 116/50·分支 32/8·局部 29/10 | :36-150（行核心／池模板／行序纪律／锚行四段） | +| `game/data/schemas/forge_table.gd` | validate 长度 95/50·分支 30/8·局部 20/10 | :31-126（行校验＋初始持有覆盖尾段＋默认轴交叉尾段） | +| `game/data/schemas/level_gen_params.gd` | validate 长度 59/50·分支 15/8·局部 18/10 | :15-72（行校验＋层深递进尾段） | +| `game/data/schemas/meta_table.gd` | validate 长度 60/50·分支 14/8·局部 14/10 | :15-74（boss_keystone／conversion／attune_refresh 三行族天然分段） | +| `game/data/schemas/reward_table.gd` | validate 长度 99/50·分支 30/8·局部 20/10 | :16-113（行校验＋字典完整性／池护栏／clear_default 三尾段） | +| `game/data/schemas/skill_table.gd` | validate 长度 80/50·分支 29/8 | :19-97（按 type=basic/damage/buff/debuff 四段类型校验） | +| `game/data/schemas/variation_table.gd` | validate 长度 58/50·分支 20/8 | :24-80（行校验＋互锁段） | +| `game/data/schemas/status_effect_table.gd` | validate 分支 12/8 | :14-51（按 unit=percent/flat/ac 三段量纲域） | +| `game/core/config_db_cross_validator.gd` | cross_validate 长度 107/50·分支 21/8·局部 24/10·嵌套 5/4；validate_skill_pool_links 局部 11/10 | :8-113（①①b②③⑤⑥⑦编号块天然分段）；:121-159 | +| `game/core/config_db_resolver.gd` | resolve_enemy_rowset 分支 12/8；_resolve_progress 长度 52/50·分支 16/8·局部 11/10 | :33-81（行集寻址）；:107-157（缺位标注 if 链＋告警去重块） | + +### 3.2 生成器族（波 4，17 键／2 文件） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/core/board_generator.gd` | generate 长度 62/50·局部 14/10；_attempt 长度 51/50；measure_inferability 长度 64/50·分支 12/8·局部 13/10·嵌套 5/4；_finalize 参数 6/5 | :20-80（params 快照段 :26-39 可提）；:85-134（布雷＋剃雷段可提）；:151-213（single／subset 两算子与派生约束段可提）；:336（`_db` 形参全函数零消费——删即 5 参） | +| `game/core/node_map_generator.gd` | check_params 分支 12/8；validate_output 长度 132/50·返回 7/6·分支 34/8·局部 22/10；_build 局部 15/10；_add_forks 局部 12/10；_assign_types 分支 11/8；_check_fork_rules 嵌套 5/4 | :68-106（域校验段／结构可行性段两分）；:111-241（六阶段早退结构天然分拆）；:246-286；:292-334（锚收集段无 RNG 可提）；:359-402（配比填余段／岔口修型段两分——后者零 RNG）；:468-514（支路签名比较嵌套） | + +### 3.3 effect_engine（8 键） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/core/effect_engine.gd` | rebuild 长度 55/50·嵌套 5/4；_cond_ok 长度 52/50·返回 19/6·嵌套 5/4；validate_trigger_row 分支 14/8·局部 11/10；多余 else（no-else-return） | :95-148（feats装载／同调装载／树规则合成三段，装载序 feats→treasure→tree）；:259-309（13 算子 match——比较族／ends_with／has／计数器族四组）；:341-388（when 键校验段／do 键校验段）；:210/:212＝bucket_of 的 elif-after-return（:207-214） | + +### 3.4 波 8 core/data 散条（21 键／10 文件） + +| 文件 | 键（现值/阈值） | 实查 | +|---|---|---| +| `game/core/config_db.gd` | 公开方法 44/20；类变量 25/15 | 公开方法实测 44 个（修订会话逐方法构成核验见 §3.5）；类变量＝19 类型化表持有＋is_ready＋5 私有。类变量外部直读核验：19 持有变量全部有生产直读（db.hero 159 处／db.settlement 177 处／db.adventure 137 处等） | +| `game/core/save_manager.gd` | 公开方法 52/20；_peek_summary_at 返回 7/6；load_from_disk 返回 8/6 | 公开方法实测 52 个，构成核验见 §3.5（槽位族 10＋元进度族 35＋断点族 4＋IO/迁移 3） | +| `game/core/status_container.gd` | apply_effect 返回 9/6·嵌套 5/4；_new_instance 参数 7/5 | :28-66（三臂 match 公共尾部都是 `_instances.append(_new_instance(...)); return true`）；:69-80 | +| `game/core/unit_container.gd` | spawn 长度 81/50·参数 10/5·局部 17/10 | :36-118（英雄段 :55-63／行集段 :69-112 两分）；签名 10 参，调用方＝battle_orchestrator（迭代 40 卡①合回后 T0 重锚）＋测试 6 文件 10 处（damage_controller_test 1／roll_multiplier_test 3／round_flow_skill_pool_test 2／skill_unlock_test 1／level_shop_economy_test 2——修订会话 grep 实查；部分调用省略尾部缺省参） | +| `game/core/reward_economy.gd` | roll_board 长度 54/50·局部 11/10；_skewed_cell_rows 局部 13/10 | :37-88（资格清单规范化段 :42-52 在开流前，可无虞提取）；:220-259（分摊量计算段／权重装配段两分） | +| `game/core/meta_progression.gd` | 公开方法 31/20；tree_can_buy 返回 8/6 | 构成核验见 §3.5（纯转发 2／hero_override 单调用点内联 3／内部自用私 2／并组 3 组／零生产私 1／留置 20）；:320-350（requires／requires_level 两循环段可提） | +| `game/core/treasure_items.gd` | validate_use 分支 11/8·嵌套 5/4 | :88-131（空间解析段／预读窗口段两分） | +| `game/core/action_economy.gd` | 类变量 18/15 | 18 变量逐个核验：**`_next_round_mode` 只写零读（死存储，:36 声明／:219 写入，全库无第三处）**；**`_ap_exhausted_last` 可派生**（:275 在 _finish_round 内由 path_tag 派生，与 :274 `_last_round_end` 同源同刻——ap_exhausted_last_round() :280-282 改派生读语义逐字）；**`last_round_end` 属性对外仅 minesweeper_rules.gd:495 一处消费**（architecture.md :102 该行只列「last_round_end」于消费依赖列，未钉属性形态；「ap/rap/phase 只读」三属性在架构对外暴露列——不动） | +| `game/core/minesweeper_rules.gd` | _do_dig 长度 53/50 | :280-332（连锁揭示循环段 :301-329 可提——cell_revealed 发射序即链序，整体搬迁零漂移） | +| `game/data/schemas/adventure_table.gd` | 类变量 44/15 | 44 变量＝44 个 @export 标量槽（修订会话逐列复核：配额 13＋件值 13＋cap 9＋knob 9——v1.0 行「37 个 @export」计法有误随本版订正，账目 44 不变）。**列族分组**：curio_quota_*（13，"kind/tier" 13 组合）／curio_value_*（13）／curio_cap_*（9）／knob 9（clear_heal_pct、curio_candidate_count、shop_refresh_*3、feat_ticket_*4）。外部直读核验：36 个配额/件值/cap 槽生产直读为零（仅 2 处测试例外：pool_case_d_test.gd:164/165/190 直写 curio_cap_gp 模拟满层、adventure_feats_test.gd:206 直读 curio_value_max_hp_common）；生产消费全走 curio_quota()/curio_value()/curio_cap() 三个访问器与 9 个 knob 槽。adventure.tres 在册 36 个标量属性（等值迁移载体） | + +### 3.5 拆件面实查（2026-10-27 修订会话消费方 grep 全域——改址计数与封闭面设计依据） + +- **config_db.gd 44 公开方法构成**（留置 8＋归位 33＋删 2＋私 1＝44 闭合）：留置＝门面/诊断/加载/override 8（push_diag/is_fatal/reset_diagnostics/diagnostics/diagnostics_count/load_tables/set_reload_gate/reload）；归位＝**溶解 16**（feat_row/feat_rows/tree_node/tree_rows/status_effect_row/level_row/level_gen_params_row/level_count/treasure_item_row/treasure_transitional_rows/treasure_attunement_rows/skill_row/shop_price_a/shop_price_b/forge_default_attack_type/forge_default_armor_type——底层表方法或属性现成，访问点改直连）＋**迁移 14**（shop_gp_drop_row/shop_level_gp_bonus/shop_price_level_bonus/shop_products/shop_product_row/shop_pool_rows/shop_pool_row 7＋meta_boss_keystone_row/meta_attune_refresh_row 2＋forge_routes/forge_route/forge_armor_route_by_type 3＋variant_pool/global_variant_row 2——实扫逻辑随方法入表类）＋**委托 3**（resolve_board_gen/resolve_enemy_rowset/resolve_difficulty_modifiers——resolver 协作件经装配段注入三表，resolver 文件与键零搬移）；删 2（meta_conversion_row/forge_weapon_route_by_type——生产零消费，K1′）；私 1（validate_skill_pool_links——测试 2 文件 9 处改 _ 前缀，K1′）。成员直读 `db.<表>` 537 处（core 99／呈现 24／测量面 414）＋访问器调用 264 处＝**改址 ≈800 处**。 +- **save_manager.gd 52 公开方法构成**：槽位族 10（attach_path/attach_slot_template/slot_path/active_slot/has_write_target/activate_slot/create_slot/delete_slot/peek_slot_summary/peek_summary_at→SlotStore；消费面 main/save_select_overlay/hud/main_overlay_flow/main_ui_build ≈12 处＋探针 ≈17 处＋测试 ≈77 处）＋元进度族 35（钥石 3〔keystone_balance/add_keystone/spend_keystone〕/道具 2/树 3/叉侧 3/锻造 9/同调 2/Y 账本 2/真视 2/计数 5/摘要 2/首冒险 2→MetaStateStore；消费面 meta_progression 内部＋attunement.gd＋adventure_runner.gd＋hud/camp 呈现＋sim/探针/测试，grep 实查 ≈340 处）＋断点族 4（set_breakpoint/clear_breakpoint/has_breakpoint/breakpoint_snapshot——留置 save_manager）＋IO/迁移 3（load_from_disk/write_to_disk/register_migration——留置）。**改址 ≈450 处**。 +- **meta_progression.gd 31 公开方法构成**（瘦身 −11＋并组回加 +3＝留置 20）：纯转发读退役 2（keystone_balance〔grep 实查 67 处接收者混布——生产 3：hud 2/camp 1，测量面 64 按接收者实例机械区分：meta 实例随本项退役改 `meta_state.` 直连、save 实例随 K2′ 族改址〕、is_item_unlocked〔treasure_interact_controller 1 处〕——消费方直连 meta_state）；hero_override 单调用点内联 3（forge_weapon_atk_bonus/forge_armor_ac_bonus/tree_stat_flat——v1.0 行「内部零调用」实查笔误随本版订正：三件均由 hero_override :303-305 调用，内联后输出逐字等价）；内部自用私 2（tree_spent_total/tree_gate_text——测试 1 文件 2 处改 _ 前缀）；并组 3 组（tree_camp_rows＋tree_fork_groups→tree_camp_status〔消费方 camp_shop_presenter 各 1 处〕、hero_attack_type＋hero_armor_type→hero_type_axes〔main.build_adventure_params 2 处＋测试 2 处〕、forge_select_weapon＋forge_select_armor→forge_select(kind, route_id)〔camp 2 处＋测试 4 处〕）；零生产私 1（forge_route_unlocked——生产零、测试 7 处改 _ 前缀）；留置 20（封闭面定稿＝架构 v1.19 :126 对外暴露列 6 件＋UI 投影/写口编排——§7-K3′ 列全）。 +- **新件封闭面预演**（gdstyle 阈值实测：max-public-methods 21 即红／max-class-variables 含私有成员 16 即红）：SlotStore 公开 10／类变量 4 ✓；MetaStateStore 公开 19（写口原语 13＋读投影 6）／类变量 1 ✓；域容器×3 类变量 7/7/5、零方法 ✓；adventure 段件×3 类变量 13/13/9、零方法 ✓——全部 ≤阈零 NEW。 + +## 4. 设计契约（红线，违反 = L3 停机呈报） + +🔴 **契约 1 · 行为零变化**：①fail-fast 契约与校验覆盖面零变化——全部 validate／cross_validate 对同一输入的错误清单**逐字等价**（类别、文案、追加顺序）；②生成结果逐位零变化——board_generator／node_map_generator 同种子同参产出与改前逐位一致，**RNG 消费序冻结**（拆分只许整段搬迁取数代码，禁重排任何 rng_stream／纯流取号调用）；③伤害数值与效果语义零触碰；④效果引擎**装载声明序**（feats→treasure→树规则，行内数组序）与**四词表封闭**（EVENTS／EFFECT_KINDS／FACTS／OPS 常量零改动）零变化；⑤玩家可见呈现零变化；⑥**存档序列化语义零变化**——tmp+rename 原子写、无激活态拒写、高版本拒读禁写、损坏兜底改名、迁移链幂等、旧单档一次性迁移判据，对同一输入的盘面结果与返回值逐字等价（现役 save 断言面为载体）。 + +🔴 **契约 2 · 断言面逐字保留**：现有 validate 系单测（data_config 八套件＋core 直引 12 文件）、生成器断言面（board_generator_test／node_map_generator_test／node_map_determinism_test 等）与 save/meta 断言面（save_manager_domain／save_slot_isolation／save_slot_summary／save_boot_no_activate／breakpoint_resume／meta_progression_forge／tree_requires_level 等）**禁删禁改判据**；确需改判据＝测试削弱申报节逐条列明理由。测量面改址（§7-K 列明的调用点换址）＝访问路径改写，断言语义与判据逐条保持。 + +🔴 **契约 3 · S13 纪律**：`tools/gdstyle_baseline.txt` 禁改禁 refresh；还债＝数值下降自然绿；**在案键的函数禁搬移文件**（基线函数级键逐一核对：save_manager 两函数键与 meta_progression tree_can_buy 返回键全部原位留置——本卡搬移面均为无键方法，§3.5 已核对）；新件封闭面按 §3.5 预演值落地、禁超阈；机检键与卡片契约互斥时停卡呈报。 + +🔴 **契约 4 · 禁为机检文本保留无效成员**（req-card 第 13 条，本卡属重构类）：禁为迎合机检消息文本（含计数）保留或新增无效成员／别名／死存储／**转发壳**（action_economy `_next_round_mode` 删除即本契约的执行例；K1′ 删除的两访问器禁以兼容名留转发、K3′ 退役的两纯转发禁在 meta_progression 留同名委托）；机检键与本卡契约互斥时实现段一律停卡呈报，不得自造第三条路。 + +🔴 **契约 5 · 公开面收敛边界（全清口径）**：文件内拆分只准动私有函数体与私有签名；公开签名／公开方法数／类变量数的改动**逐项按 §7-K1′–K6′ 清单执行**（每项已列改法、归位映射与消费方影响面），清单外公开面禁动；新件公开面＝清单列明的封闭面，禁超禁缩（缩＝消费面断裂，超＝NEW 键）。 + +🔴 **契约 6 · 核心层纪律不破**：Core 层零 UI 依赖（拆分后完整战斗仍可 `--headless --script` 跑通）；数值单一事实源（adventure_table 拆段后玩法数值仍只存 `data/tables/*.tres` 经 ConfigDB 单点读取——口径按架构 v1.19 :88：「经 ConfigDB 单点读取」＝经其持有的表对象，访问器语义不变）；RNG 单点（零新增随机）；**新件零 autoload**（SlotStore/MetaStateStore 由 save_manager 组装持有、经 `save.slots`／`save.meta_state` 直连——组合根句柄面与 autoload 链零新增，架构 :89/:90 消费依赖单向）。 + +## 5. 范围边界 + +**做**：§3 所列 26 文件的结构拆分与 §7-K1′–K6′ 公开面收敛（含 8 新件建件与 ≈1330 处消费方改址）；adventure.tres 等值迁移；撤销证明；产出物。 + +**不做**（去向明示）： +- config_db 类变量词典化（域容器 Resource 为既裁形态，词典化不采——D7）；save/meta 的第三种拆法（SlotStore/MetaStateStore 为架构 v1.19 定稿件，禁另起形态）； +- 卡①文件集的结构改动（本卡对其仅 spawn 调用点一行改址）与卡③呈现层结构收敛（本卡对其仅访问点改址行）→ 各归其卡，编排错波； +- 波 7 五小件（现成卡 v1.3，迭代 40）、三宿主残留债（迭代 39）、波 0 基线 refresh（直改）→ 各归其位； +- design/ 与根规则文件任何编辑 → 反哺点清单（§6）； +- MC／对拍锚重跑 → 用户发起（本批零触发）。 + +## 6. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| `design/gdd/systems/战斗循环/地图战斗资源.md` | :83 引 `reward_economy.gd#roll_board` 内部行号（「循环第 65-67 行」）——roll_board 提取规范化段后行号漂移；`_rollable_rows()` 207-213 指址不变 | 反哺点 · 列清单（①：行号随动，陈述本体——收 pool 全集与资格一视同仁语义——零变化） | +| `design/gdd/systems/冒险循环/冒险结构.md` | :267「adventure_table curio_value_*（…列族）」——拆段后标量槽随段件嵌套（段路径），值域陈述（int [0,999]／kind×tier）不变 | 反哺点 · 列清单（②：落点列改指段路径） | +| `design/engineering/architecture/architecture.md` | v1.19 定稿注记四行的实现批后现状改写：:88 ConfigDB 行（「实现卡随批改址」→改写为容器三件现状＋公开面 8 实数）；:89/:90 两新件行（「实现批建件」→现状登记）；:126 meta_progression 行（「随件退役」→改写为公开面 20 现状）；另 :102 minesweeper 行消费依赖列「A3 last_round_end」属性→方法注记；:90 action_economy 行与 :92/:93/:103/:104 四行（公开 API 零变化——T0 核后记「零改动」注记） | 反哺点 · 列清单（③：v1.19 定稿注记的现状改写由文档批执行，本卡只列落点） | +| `game/tests/验证集清单.md` | 测量面改址涉及测试文件的调用点地址（机器提取重生成） | 批内机械同步（game 内 .md，非禁写面） | +| `待办清单.md` | 来源条目状态推进（主会话统一回写——本卡代理禁改） | 反哺点 · 列清单（④：状态核对注记） | + +## 7. 任务卡 + +### 卡前 · 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| `game/data/schemas/meta_tree_table.gd` | validate 拆行校验域＋requires/requires_level 尾段（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/treasure_item_table.gd` | validate 拆行头／活行／同调行三域（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/enemy_table.gd` | validate 拆行核心／池模板／行序域＋resolve_rowset 委托收编（复用既有·修改） | 非行为 → wr1/wr8 | +| `game/data/schemas/forge_table.gd` | validate 拆行校验＋两尾段＋forge 族 3 方法归位（复用既有·修改） | 非行为 → wr1/wr8 | +| `game/data/schemas/reward_table.gd` | validate 拆行校验＋三尾段（复用既有·修改） | 非行为 → wr1 | +| `game/data/schemas/board_gen_table.gd` | validate 拆行校验域＋resolve_row 委托收编（复用既有·修改） | 非行为 → wr2/wr8 | +| `game/data/schemas/level_gen_params.gd` | validate 拆行校验＋层深递进尾段（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/meta_table.gd` | validate 拆三行族域＋meta 族 2 方法归位（复用既有·修改） | 非行为 → wr2/wr8 | +| `game/data/schemas/skill_table.gd` | validate 拆四类型域（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/variation_table.gd` | validate 拆行校验＋互锁域＋variant_pool/global_variant_row 归位（复用既有·修改） | 非行为 → wr2/wr8 | +| `game/data/schemas/status_effect_table.gd` | validate 拆量纲域（复用既有·修改） | 非行为 → wr2 | +| `game/data/schemas/difficulty_table.gd` | resolve_modifiers 委托收编（复用既有·修改） | 非行为 → wr8 | +| `game/data/schemas/level_table.gd` | level_count 归位（复用既有·修改） | 非行为 → wr8 | +| `game/data/schemas/shop_table.gd` | shop 族 7 方法归位（复用既有·修改） | 非行为 → wr8 | +| `game/core/config_domain_combat.gd` | **新增**——战斗域容器（board_gen/variation/status_effects/enemy/skill/hero/settlement 7 类型化成员） | 非行为 → wr8 | +| `game/core/config_domain_run.gd` | **新增**——冒险域容器（level/difficulty/level_gen_params/reward/adventure/action_economy/shop 7 成员） | 非行为 → wr8 | +| `game/core/config_domain_crossrun.gd` | **新增**——跨局域容器（meta/meta_tree/treasure_items/feats/forge 5 成员；跨局循环＝单局之外的长线进度域） | 非行为 → wr8 | +| `game/core/config_db.gd` | 19 表成员→3 容器＋33 访问器归位＋删 2 私 1＋resolver 装配注入三表（K1′） | 非行为 → wr8 | +| `game/core/config_db_cross_validator.gd` | cross_validate 拆七编号块域＋_check_cast_side（复用既有·修改） | 非行为 → wr2 | +| `game/core/config_db_resolver.gd` | 拆键收集／缺位标注／告警发射域（复用既有·修改——文件零搬移，键原位） | 非行为 → wr2 | +| `game/core/slot_store.gd` | **新增**——存档槽位文件域件（槽位挂载与模板/激活与建删/摘要窥视 10 公开，架构 :89） | 非行为 → wr6 | +| `game/core/meta_state_store.gd` | **新增**——存档内元进度数据读写唯一层（写口原语 13＋读投影 6＝19 公开，架构 :90） | 非行为 → wr6 | +| `game/core/save_manager.gd` | 槽位族/元进度族 45 方法收编出户＋断点族/IO/迁移链留置＋读盘域提取＋状态分家（K2′） | 非行为 → wr6 | +| `game/core/meta_progression.gd` | 纯转发退役 2＋内联 3＋并组 3＋私 3＋留置 20＋meta_state 成员（K3′） | 非行为 → wr7 | +| `game/core/board_generator.gd` | 拆 params 快照／布雷／single-subset 算子域＋_finalize 删 _db 参（复用既有·修改） | 非行为 → wr3 | +| `game/core/node_map_generator.gd` | validate_output 拆六阶段＋check_params 两分＋构建域拆分（复用既有·修改） | 非行为 → wr3 | +| `game/core/effect_engine.gd` | rebuild 三装载域＋_cond_ok 四算子域＋validate_trigger_row 两键域＋bucket_of elif 收口（复用既有·修改） | 非行为 → wr4 | +| `game/core/status_container.gd` | apply_effect 公共尾部收口＋_new_instance 打包 5 参（复用既有·修改） | 非行为 → wr5 | +| `game/core/treasure_items.gd` | validate_use 拆空间解析／预读窗口域（复用既有·修改） | 非行为 → wr5 | +| `game/data/schemas/adventure_quota_segment.gd` | **新增**——令牌配额段（curio_quota_* 13 @export；嵌套段单 .tres 保持） | 非行为 → wr9 | +| `game/data/schemas/adventure_value_segment.gd` | **新增**——令牌件值段（curio_value_* 13 @export） | 非行为 → wr9 | +| `game/data/schemas/adventure_cap_segment.gd` | **新增**——已拿上限段（curio_cap_* 9 @export） | 非行为 → wr9 | +| `game/data/schemas/adventure_table.gd`＋`game/data/tables/adventure.tres` | 36 列族槽拆 3 段件＋.tres 等值迁移＋访问器改读段＋knob 9 留置（K4′） | 非行为 → wr9 | +| `game/core/action_economy.gd` | 删死存储＋派生合并＋last_round_end 属性→方法（K5） | 非行为 → wr10 | +| `game/core/reward_economy.gd` | roll_board 拆规范化域＋_skewed_cell_rows 两域（复用既有·修改） | 非行为 → wr10 | +| `game/core/minesweeper_rules.gd` | _do_dig 拆连锁揭示域（复用既有·修改） | 非行为 → wr10 | +| `game/core/unit_container.gd` | spawn 签名束化（10→1 参 req 束）＋体内拆英雄/行集两域（K6′） | 非行为 → wr11 | +| `game/core/attunement.gd`／`adventure_runner.gd` 等 core 消费面 | save 族/`db.<表>` 访问点改址（复用既有·修改） | 非行为 → wr6/wr7/wr8 | +| `game/presentation/`（main／hud_presenter／camp_shop_presenter／save_select_overlay／treasure_interact_controller 等） | 纯转发退役直连＋槽位族/`db.<表>` 改址（复用既有·修改） | 非行为 → wr6/wr7/wr8 | +| `game/tests/`…＋`game/probe/`…＋`game/sim/`…（约 50 文件） | 五组改址与测量面随动（复用既有·修改） | 断言面（改址非削弱）→ wr6/wr7/wr8/wr9/wr11 | + +### 落位与可复用性预检 + +- **新件 8 逐件「为什么不能复用既有」**： + - 域容器×3（`config_domain_*.gd`）：config_db 本体即 God Class 本体（44 方法／25 成员）——「按域分组的类型化表持有」是新职责所有者，复用 config_db 内部结构＝延续 God Class（D7 裁决的整管对象正是它）；架构 v1.19 :88「类型化域容器属性（每域一张容器）」。落位 `game/core/`（持有结构与 owner ConfigDB 同层同域）。 + - `slot_store.gd`：save_manager 本体 God Class（52 方法）——槽位文件域唯一所有者是新职责切面，架构 :89 行登记；落位 `core/`（D3 存档域）。 + - `meta_state_store.gd`：save 与 meta 双 God Class 的共同病根＝同一「存档内元进度数据域」摊在两文件——归一件即新职责本体，架构 :90 行登记；落位 `core/`。 + - adventure 段件×3：adventure_table 44 成员超阈本体——列族分组是新持有结构，复用＝维持 44 列平铺；形态同 settlement_table 拆段既裁（嵌套段单 .tres 保持）；落位 `game/data/schemas/`（表 schema 同层）。 +- **唯一面**：新件类名全库 grep 零同名（ConfigDomainCombat/Run/Crossrun、SlotStore、MetaStateStore、AdventureQuota/Value/CapSegment——修订会话 grep 确认零命中）；既有文件内新增私有函数只落其所属文件，不抽共享骨架为既裁（D2）；跨文件同名私有方法（多个 schema 各自的 `_validate_row`）属 GDScript 类作用域私有，互不冲突，grep 全库名确认盘上无第二处同职责实现。 +- **分层与交互面**：新件全部构造注入/组装持有，零裸引用 autoload（S5 不触）；域容器/段件不 load 不 preload（S3 不触）；新件零随机（S1/S2 不触）；SlotStore/MetaStateStore→save_manager 单向依赖（S6 反向引用面不触——零信号零订阅）；resolve 委托经装配段注入（resolver 文件与键零搬移——契约 3）。Core 零 UI 不破（全套件 headless 可跑）。 +- **改址五组计数**（§3.5 实查，T0 复核）：①`db.<表>` 成员直读 537 处→`db.<容器>.<表>`；②config_db 访问器调用 264 处→表类直连/归位新名（映射表见 K1′）；③save 槽位族 ≈110 处→`save.slots.`；④save/meta 元进度族 ≈340 处→`save.meta_state.`（读面部分随投影改形）；⑤meta 纯转发退役/并组 ≈60 处＋spawn 调用点 10 处＋K5 一处。合计 ≈1330 处——改址一律符号级 grep 全域后机械替换＋逐文件复核（残余人工核），断言语义逐条保持（契约 2）。 +- **K1′–K6′ 逐项**（公开面收敛清单，契约 5 载体——每项改法、映射与消费方影响面）： + - **K1′ config_db（44→8、25→9）**：①19 表成员收进三容器——`combat`（board_gen/variation/status_effects/enemy/skill/hero/settlement）／`run`（level/difficulty/level_gen_params/reward/adventure/action_economy/shop）／`crossrun`（meta/meta_tree/treasure_items/feats/forge），分组判据＝消费方域归属（战斗编排域 7／冒险 runner 域 7／跨局元进度域 5）；ConfigDB 类变量余 is_ready＋_diagnostics＋_resolver＋_validator＋_reload_gate＋_fatal_flag＋3 容器＝9。②33 访问器归位映射（改址映射表，命名避开表类既有成员名——routes 属性在册故 forge_routes()→ForgeTable.route_rows()、shop_products()→product_rows() 等）：溶解 16（db.feat_row→db.crossrun.feats.row_by_id、db.tree_node→db.crossrun.meta_tree.row_by_id、db.status_effect_row→db.combat.status_effects.row_by_id、db.level_row→db.run.level.row_by_level_index、db.level_gen_params_row→db.run.level_gen_params.row_by_level_index、db.level_count→db.run.level.level_count、db.treasure_item_row→db.crossrun.treasure_items.row_by_id、db.treasure_transitional_rows/attunement_rows→同名表方法、db.skill_row→db.combat.skill.row_by_id、db.shop_price_a/price_b→db.run.shop.price_a/price_b 属性、db.forge_default_attack_type/armor_type→db.crossrun.forge.default_attack_type/armor_type 属性）；迁移 14（db.shop_gp_drop_row→db.run.shop.gp_drop_row、shop_level_gp_bonus→level_gp_bonus_at、shop_price_level_bonus→price_level_bonus_at、shop_product_row→product_row、shop_pool_row→pool_row、shop_pool_rows→pool_rows、db.meta_boss_keystone_row→db.crossrun.meta.boss_keystone_row、db.meta_attune_refresh_row→db.crossrun.meta.attune_refresh_row、db.forge_route→db.crossrun.forge.route、db.forge_armor_route_by_type→db.crossrun.forge.armor_route_by_type、db.variant_pool→db.combat.variation.variant_pool、db.global_variant_row→db.combat.variation.global_variant_row）；委托 3（db.resolve_board_gen→db.combat.board_gen.resolve_row、db.resolve_enemy_rowset→db.combat.enemy.resolve_rowset、db.resolve_difficulty_modifiers→db.run.difficulty.resolve_modifiers——resolver 实例由 load_tables 装配段注入三表）。③删 meta_conversion_row（生产零；测试 3 处改直扫 `db.crossrun.meta.conversion` 行集同判据）＋删 forge_weapon_route_by_type（生产零；forge_table_test 2 处改扫 route_rows() 同判据）。④私 validate_skill_pool_links→_validate_skill_pool_links（测试 2 文件 9 处改 _ 前缀；cross_validator 自有公开同名方法不动）。⑤空表护栏语义：溶解面原 null-guard 仅覆盖「表未加载」态——生产消费全部在 load_tables 成功后（D6 实查），加载期护栏由 is_ready 门承担， ForgeTable 缺省轴语义与 schema 字段默认值同口径（normal/light）零行为变化。 + - **K2′ save_manager 拆件（52→7）**：①SlotStore 收编槽位族 10（attach_path/attach_slot_template/slot_path/active_slot/has_write_target/activate_slot/create_slot/delete_slot/peek_slot_summary/peek_summary_at），槽位态随迁（_slot_template/_path/_active_slot），save_manager 留 _data/_migrations/_read_only＋slots/meta_state 两组装成员＝类变量 5；peek 的只读推演内核 _peek_summary_at（键在案）留 save_manager 原位，SlotStore 两 peek 方法经槽路径派生委托（迁移链/规整归 IO 域）。②MetaStateStore 收编元进度族 35——**公开面 19＝写口原语 13**（spend_keystone/unlock_item/set_tree_level/set_fork_side/set_forge_route_level/add_forge_unlock/set_forge_weapon/set_forge_armor/set_attunement_equipped/set_attune_refresh_level/add_vision_used/apply_adventure_summary/mark_first_adventure_done）**＋读投影 6**（keystone_balance()、item_unlocked(id)、tree_state()→{nodes, fork_sides}、forge_state()→{levels, unlocked, weapon, armor}、attune_state()→{equipped, refresh_level}、career_state()→{clear_counts, boss_first_kill, boss_kill_count, adventure_total, adventure_cleared, vision_used, recent_summaries, first_adventure_done}——读投影即架构 :90「只读投影」形态，值拷贝出户 duplicate 纪律随迁）；add_keystone 私有化 _add_keystone（生产零、测量 21 处改 _ 前缀——K2 同法）。③save_manager 留置 7 公开：load_from_disk/write_to_disk/register_migration＋断点族 4；读盘域提取 `func _load_parsed(f: FileAccess) -> bool`＋`func _peek_migrated(parsed: Variant) -> Variant`（:320-355/:175-209 两函数与迁移循环同构可提——corrupt_fallback 调用点随段迁移，副作用序逐字）。④跨件协作：两 store 持 save 注入引用，建/删/激活的数据重置与读写盘经 save 内部 _ 前缀协作家族（_reset_to_default/_load_parsed/_rename_overwrite 等），store 零 _data 副本零缓存（load 整体换新不陈旧）；激活失败回退四态（路径/激活号/禁写位/数据）跨件原子性由现役 save_slot_isolation 断言面承载。⑤消费方直连：`save.slots.`／`save.meta_state.`（存档 UI/营地树 UI/锻造 UI/调试面）；组合根句柄面零新增（契约 6）。 + - **K3′ meta_progression（31→20，封闭面定稿）**：纯转发退役 2（keystone_balance/is_item_unlocked——消费方改 `meta.meta_state.` 直连）；内联 3（forge_weapon_atk_bonus/forge_armor_ac_bonus/tree_stat_flat 收编进 hero_override 单调用点——输出逐字等价）；私 3（tree_spent_total/tree_gate_text〔测试 1 文件 2 处〕/forge_route_unlocked〔测试 1 文件 7 处〕改 _ 前缀）；并组 3 组（tree_camp_status()→{rows, fork_groups}、hero_type_axes()→{attack, armor}、forge_select(kind, route_id)——camp/main 与测试改址 ≈10 处）；留置公开 20＝buy_treasure_unlock/refresh_treasure_unlocks/treasure_shop_status/forge_buy_level/forge_buy_unlock/forge_select/hero_type_axes/forge_shop_status/settle_adventure/hero_override/tree_can_buy〔v1.19 :126 对外暴露列在册——留公开，测试零改址〕/tree_buy/tree_toggle_fork/tree_buy_fork/tree_rule_keys/tree_camp_status/toggle_attunement/attune_camp_status/attune_refresh_charges/buy_attune_refresh；补公开成员 `meta_state`（_ready 装配）。写口唯一性保持：全部购买/切换/装配写路径仍只经本类编排（扣币 spend_keystone＋域写原语＋write_to_disk 时序归本类门面）。 + - **K4′ adventure_table 拆段（44→12）**：36 个列族标量槽拆 3 段件——`AdventureQuotaSegment`（curio_quota_* 13）／`AdventureValueSegment`（curio_value_* 13）／`AdventureCapSegment`（curio_cap_* 9），段内 @export 槽名逐字不动；宿主留 3 段成员＋9 knob＝12 ≤ 15 ✓（knob 留置＝生产直读零改址）；curio_quota(kind, tier)／curio_value(kind, tier)／curio_cap(kind) 三访问器签名与返回语义逐字不变（内部改读段成员；未列组合 = 0／缺省 99 语义保持）；validate() 域判据经访问器读数不变（现役文案逐字）；`adventure.tres` 等值迁移（36 在册值逐槽照抄入嵌套段 sub_resource、单 .tres 保持、缺省槽保持缺省语义）；测试改址 4 处（pool_case_d_test.gd:164/165/190 直读写→段路径、adventure_feats_test.gd:206 直读→段路径——断言语义不变）。改后宿主类变量 12＋段件 13/13/9 全在阈。 + - **K5 action_economy（18→15）**：删 `_next_round_mode` 死存储（:36 声明＋:219 死写；`notify_settlement_done` 形参保留签名不变）；`_ap_exhausted_last` 删除、`ap_exhausted_last_round()` 改派生读 `_last_round_end.get("path_tag", "") == "ap_exhausted"`（同源同刻等值——:274/:275 实查依据）；`last_round_end` 属性→方法 `func last_round_end() -> Dictionary`（消费方仅 minesweeper_rules.gd:495 一处改方法调用）。 + - **K6′ unit_container（spawn 参数 10→1）**：签名改 `func spawn(req: Dictionary) -> bool`——束键封闭词表：必载 level_index/node_depth/hero_hp，可选 unit_count_overrides=[]/enemy_atk_overrides=[]/hero_atk_override=-1/hero_max_hp_override=-1/hero_attack_type=""/hero_armor_type=""/row_kind="battle"（缺省语义与现行形参缺省逐字同值）；体内拆分照旧（`_spawn_hero_unit`/`_spawn_rowset` 两私有域）。调用点改址 11 处 7 文件（battle_orchestrator 1〔按卡①合回后形态〕＋测试 10——束字面量构造，断言语义不变）。 + +### T0 事实坐实＋改前读数采集（≈0.3d） + +- [ ] 复核 §3 全部 file:line（**按迭代 40 卡①/波 7 合回后 master 重锚**——spawn 调用点、board_generator/reward_economy 两 `_fatal`、卡③/迭代 39 触碰行）；跑 `python tools/gdstyle_gate.py` 记录改前读数（在案键计数、NEW/WORSENED 判定）。可核查结果：改前读数表进实现报告素材。 +- [ ] 留档行为等价对拍基线：data_config 八套件与生成器 determinism 断言记录改前全绿读数；坏表夹具错误清单留档；**save 断言面套件名与断言数留档**（save_manager_domain/save_slot_isolation/save_slot_summary/save_boot_no_activate/breakpoint_resume/save_rng_roundtrip 等——wr6 逐位等价载体）。可核查结果：改前基线读数在案。 +- [ ] 五组改址计数复核（§3.5 五组 grep 读数逐组重跑留档——机械替换的完备性依据）。可核查结果：改址计数表在案。 +- [ ] 核实窄确认载体：单元面直跑形态（`--headless --path . --script res://tests/run_all.gd`）与单套件过滤机制。可核查结果：T1–T9 验证步骤的命令形态定稿。 + +### T1 数据校验族·大表组（5 文件 17 键，≈0.7d） + +- [ ] meta_tree_table：validate 拆 `func _validate_row(row: Dictionary, seen: Dictionary, fork_seen: Dictionary) -> Array`（行内全判据，fork_seen 引用传递）＋`func _validate_requires_dangling(rows: Array, seen: Dictionary) -> Array`＋`func _validate_requires_level(rows: Array, seen: Dictionary) -> Array`（requires 与 requires_level 两尾段分离）；validate 本体留空表护栏＋行循环 append_array＋彩蛋计数尾段。可核查结果：错误追加序与改前逐字等价（现役 meta_progression_forge_test／table_structure_guard 断言绿）。 +- [ ] treasure_item_table：validate 拆 `func _validate_row_head(row: Dictionary, iid: String) -> Array`（:76-107 display_name→form 段）＋`func _validate_row_active(row: Dictionary, iid: String) -> Array`（:111-141 活行段，kind_seen 内建）＋`func _validate_row_attunement(row: Dictionary, iid: String, kind_seen: Dictionary) -> Array`（:142-205 同调段）；validate 本体留空表护栏＋seen/dup＋三域顺序调用（retired/deferred continue 位置逐字）。可核查结果：treasure_target_violation_test／table_structure_guard／config_db_test 秘宝段全绿，EffectEngine.validate_trigger_row 调用点零变化。 +- [ ] enemy_table：validate 拆 `func _validate_row_core(row: Dictionary) -> Array`（:52-88 进度键/枚举/值域段）＋`func _validate_row_pool(row: Dictionary, eid: String) -> Array`（:90-116 池模板段）＋`func _validate_rowset_order(rowset_key: String, last_rowset_key: String, closed_rowset: Dictionary, L: int, rk: String, band: int) -> Array`（:129-138 行序纪律段）；validate 本体留 seen/dup、行序状态机、锚行尾段。可核查结果：现役敌人表断言面（config_db_test／round_flow_skill_pool_test 前置）全绿。 +- [ ] forge_table：validate 拆 `func _validate_route_row(row: Dictionary, kind_by_id: Dictionary) -> Array`（:47-106 行段）＋`func _validate_initial_coverage(routes: Array) -> Array`（:107-125 初始持有覆盖＋默认轴交叉尾段）。可核查结果：forge_table_test 全绿（含 13 处行级判据）。 +- [ ] reward_table：validate 拆 `func _validate_row(row: Dictionary, cell_dict: Dictionary, tallies: Dictionary) -> Array`（:25-101 行段；tallies＝{cell_positive_live, clear_value_ok} 引用传递）＋validate 本体留三尾段（字典完整性/池护栏/clear_default）。可核查结果：reward_dangling_treasure_test／table_structure_guard／seal_polarity_test 前置全绿。 +- [ ] 验证步骤：数据面窄确认（data_config＋受涉 core 套件直跑全绿）＋`D:/code/gdstyle/gdstyle.exe` 直扫五文件——17 键全部消失。 + +### T2 数据校验族·小表组＋跨表校验器＋解析器（8 文件 23 键，≈0.7d） + +- [ ] board_gen_table：validate 拆 `func _validate_row(row: Dictionary, levels: Dictionary, anchor_ok: Dictionary) -> Array`；validate 本体留空表护栏＋锚行尾段。 +- [ ] level_gen_params：validate 拆 `func _validate_row(row: Dictionary, seen: Dictionary, layers_by_level: Dictionary) -> Array`；本体留层深递进尾段。 +- [ ] meta_table：validate 拆 `func _validate_boss_keystone() -> Array`＋`func _validate_conversion() -> Array`＋`func _validate_attune_refresh() -> Array`；本体留三行族空护栏＋顺序拼接。 +- [ ] skill_table：validate 拆 `func _validate_basic_row(sid: String, row: Dictionary, cd: int) -> Array`／`func _validate_damage_row(...)`／`func _validate_buff_row(...)`／`func _validate_debuff_row(...)`（同签名形态）；本体留 seen/type 分派＋普攻存在性＋pity 尾段。 +- [ ] variation_table：validate 拆 `func _validate_row(row: Dictionary, seen: Dictionary) -> Array`；本体留互锁段（或并入 _validate_row——以分支 ≤8 为准）。 +- [ ] status_effect_table：validate 拆 `func _validate_magnitude_domain(row: Dictionary, eid: String) -> Array`（percent/flat/ac 三段量纲域）。 +- [ ] config_db_cross_validator：cross_validate 拆七编号块域——`func _cv_reward_dangling(st, rt, push_diag: Callable) -> void`／`func _cv_reward_treasure(st, rt, loaded: Dictionary, push_diag: Callable) -> void`／`func _cv_poolmap(st_tab, effect_ids: Dictionary, push_diag: Callable) -> void`／`func _cv_source_labels(st_tab, push_diag: Callable) -> void`／`func _cv_counter_closure(loaded: Dictionary, treasure_tab, feats_tab, push_diag: Callable) -> void`（①①b②③⑤⑥⑦对应；货架块 ⑥ 并入 _cv_reward_treasure 或独立 `_cv_shelf_pool`——以各件 ≤50 行/≤8 分支为准）；validate_skill_pool_links 拆 `func _check_cast_side(skill_table: SkillTable, status_table: StatusEffectTable) -> Array`。 +- [ ] config_db_resolver：resolve_enemy_rowset 拆 `func _level_keys_of(rows: Array) -> Array[int]`＋`func _band_keys_of(rows: Array, l_star: int, row_kind: String) -> Array[int]`＋`func _band_rows(rows: Array, l_star: int, row_kind: String, d_star: int) -> Array[Dictionary]`（纯行扫描，告警发射序不变）；_resolve_progress 拆 `func _depth_keys_of(rows: Array, l_star: int) -> Array[int]`＋`func _missing_label(l_clamped: bool, d_clamped: bool, l_star: int, L: int, d_star: int, D: int) -> String`＋`func _emit_missing_warning(table_id: String, missing: String, l_star: int, d_star: int, L: int, D: int) -> void`（去重注册表语义逐字）。 +- [ ] 验证步骤：数据面窄确认全绿（config_db_fatal_oob／counter_prefix_fatal／level_gen_params_test／config_db_resolver_test／config_db_cross_validator_test 等）＋直扫八文件——23 键全部消失。 + +### T3 生成器族（2 文件 17 键，≈0.7d） + +- [ ] board_generator：拆 `func _board_params(row: Dictionary, L: int, D: int) -> Dictionary`（:26-39 快照段——零 RNG）；`func _populate_mines(b: BoardData, params: Dictionary, rng_stream: RandomNumberGenerator) -> int`（:93-127 布雷＋剃雷段——Fisher-Yates 取号段整体搬迁，返回 ring_removed）；`func _apply_single_rules(constraints: Array, r: Dictionary, known_mines: Dictionary) -> bool`＋`func _derived_constraints(constraints: Array) -> Array`＋`func _apply_derived_rules(derived: Array, r: Dictionary, known_mines: Dictionary) -> bool`（measure_inferability 的 single／subset 算子域——返回 changed，主循环序不变）；`_finalize` 删 `_db` 形参（:336，调用点 :79 一处随动）。可核查结果：board_generator_test／board_gen_reward_test 全绿＋同种子改前改后逐位一致断言绿（RNG 消费序冻结——契约 1②）。 +- [ ] node_map_generator：validate_output 拆六阶段域——`func _vo_node_fields(nodes: Array, errs: Array) -> Dictionary`（字段/dup/类型/深度，返回 {by_id, indeg, ok}）＋`func _vo_edges(nodes: Array, by_id: Dictionary, indeg: Dictionary, errs: Array) -> bool`＋`func _vo_flow_facts(nodes: Array, indeg: Dictionary, errs: Array) -> Dictionary`（entries/terminals/Boss 终点判据）＋`func _vo_depth_reach(nodes: Array, by_id: Dictionary, entries: Array, terminals: Array, errs: Array) -> bool`（最长路径＋可达性）＋`func _vo_shop_rules(nodes: Array, by_id: Dictionary, entries: Array, terminals: Array, errs: Array) -> bool`（摆放约束①＋_all_paths_one_shop＋_check_fork_rules）＋`func _vo_count_rules(nodes: Array, params: Dictionary, by_id: Dictionary, entries: Array, terminals: Array, errs: Array) -> void`（多终点深度互异＋宽度上限＋参数档对照）——validate_output 本体＝空图护栏＋六阶段顺序调用＋阶段间早退合并（返回 ≤6）；check_params 拆 `func _cp_domain(params: Dictionary) -> Array`＋`func _cp_structural(params: Dictionary) -> Array`；_build 拆 `func _build_region(rg: RandomNumberGenerator, r: int, e: int, t: int, prevs: Array) -> void`（区域段——_build 本体零 RNG，拆分自由）；_add_forks 拆 `func _collect_fork_anchors(L: int, t: int, e: int) -> Array`（锚收集——零 RNG，shuffle 与扩岔循环留本体保取号序）；_assign_types 拆 `func _fill_ratios(rg: RandomNumberGenerator) -> void`（e==1 配比填余段——shuffle+randf 取号序整体搬迁）＋`func _fix_detour_heads() -> void`（岔口修型段——零 RNG）；_check_fork_rules 拆 `func _fork_signature(outs: Array, by_id: Dictionary) -> Array`＋`func _fork_has_unique(comps: Array, i: int) -> bool`（嵌套 5→≤4）。可核查结果：node_map_generator_test／node_map_growth_test／node_map_determinism_test 全绿＋同参数同种子逐位一致（纯流取号序冻结）。 +- [ ] 验证步骤：核心面窄确认全绿＋直扫两文件——17 键全部消失。 + +### T4 效果引擎（8 键，≈0.35d） + +- [ ] rebuild 拆 `func _load_feat_triggers(feat_ids: Array) -> void`＋`func _load_attune_triggers(item_ids: Array) -> void`＋`func _push_tree_rules(tree_rules: Array) -> void`——**调用序＝装载声明序 feats→treasure→tree 逐字**（契约 1④），sense_sharp/guard 双行 push 序随段整体搬迁。 +- [ ] _cond_ok 拆四算子域：`func _cmp_ok(op: String, actual: Variant, val: Variant) -> bool`（eq..lte 六比较）＋`func _ends_with_ok(actual: Variant, val: Variant) -> bool`＋`func _has_ok(c: Dictionary, actual: Variant) -> bool`＋`func _counter_op_ok(ctx: EffectContext, c: Dictionary, op: String, actual: Variant) -> bool`（mod_zero/mod_eq/advantageous/gte_ref/lt_ref）；_cond_ok 本体＝fact/op/val 取值＋分派＋未知算子 assert(false)+return false（返回 ≤6、嵌套 ≤4）。语义逐字：判定结果与 unknown-op 致命路径零变化。 +- [ ] bucket_of 的 elif-after-return 收口（:207-214）→ 独立 if 序或 match——前缀判定序 round→lvl→adv→battle 缺省逐字（no-else-return 键消失）。 +- [ ] validate_trigger_row 拆 `func _vtr_when_keys(rid: String, tr: Dictionary, errs: Array) -> void`＋`func _vtr_do_keys(rid: String, tr: Dictionary, row: Dictionary, errs: Array) -> void`——错误追加序逐字（:341-388 现序＝trigger 键→on→when→do 键→kind→counter_id→value_from 双侧）。 +- [ ] 验证步骤：效果面窄确认全绿（effect_words_t1_test／tree_rules_v11_test／counter_prefix_fatal_test／adventure_feats_test／round_flow_skill_pool_test）＋直扫——8 键全部消失。 + +### T5 存档域拆件——SlotStore／MetaStateStore 建件收编＋save_manager 瘦身（≈1.5d） + +- [ ] SlotStore 建件（K2′①）：槽位族 10 方法＋槽位态三成员随迁；`attach_path`／`attach_slot_template`／`activate_slot`／`create_slot` 的数据侧协作经 save 内部 _ 前缀协作家族（重置默认态/加载/写盘/回退四态），`delete_slot` 的 _remove_file 与 `_migrate_legacy_save` 的 `_copy_file` 随迁（槽文件域原语），`_rename_overwrite` 留 save_manager（IO 原语单点）经注入引用调用；save_manager._ready 旧单档迁移改调 slots 侧入口（幂等判据逐字）。可核查结果：save_boot_no_activate/save_slot_isolation/save_slot_summary 直跑全绿＋grep 槽位族 10 名在 save_manager 零命中。 +- [ ] MetaStateStore 建件（K2′②）：元进度族 35 收编为公开 19（写口原语 13＋读投影 6）＋_add_keystone 私有——投影按 K2′② 键构成逐字落地，值拷贝出户随迁；零 _data 副本零缓存。可核查结果：save_manager_domain/save_rng_roundtrip 直跑全绿＋gdstyle 直扫两新件公开方法/类变量零 NEW。 +- [ ] save_manager 瘦身：断点族 4＋load_from_disk/write_to_disk/register_migration 留置；读盘域提取 `func _load_parsed(f: FileAccess) -> bool`（:320-355 解析/版本/迁移/规整段——corrupt_fallback 调用点随段迁移，副作用序逐字）＋`func _peek_migrated(parsed: Variant) -> Variant`（迁移循环提取，失败返回 null＝现「返回未填充 out」逐字）；load_from_disk 本体留文件存在分支＋corrupt 委托（返回 ≤6）；_init 组装 slots/meta_state 两成员。可核查结果：直扫 save_manager 公开方法 52→7、_peek_summary_at 返回 7→≤6、load_from_disk 返回 8→≤6。 +- [ ] 存档族改址（≈450 处）：槽位族 →`save.slots.`（≈110 处——呈现 ≈12/探针 ≈17/测试 ≈77）；元进度族 →`save.meta_state.`（≈340 处——读面 tree_level/forge_route_level/clear_count 等随投影改形为 `.tree_state().nodes.get(...)` 等同值读）；断点族零改址。可核查结果：改址后 save 断言面全套直跑全绿（T0 留档套件清单）＋grep 五组前缀零漏改。 +- [ ] 验证步骤：存档面窄确认全绿（save_manager_domain／save_slot_isolation／save_slot_summary／save_boot_no_activate／breakpoint_resume／save_rng_roundtrip＋integration 三件＋probe 直跑）＋直扫三文件——save_manager 52→7、新件零 NEW。 + +### T6 meta_progression 瘦身＋status_container／treasure_items 拆分（≈0.7d） + +- [ ] meta_progression 瘦身（K3′）：纯转发退役 2＋内联 3（hero_override 输出逐字）＋私 3（含 forge_route_unlocked）＋并组 3 组＋`meta_state` 成员装配；本类数据读写全部改经 meta_state（读投影同值改形）。可核查结果：tree_requires_level_test/meta_progression_forge_test 改址后全绿＋grep 纯转发零残留（`save.keystone_balance`/`save.item_unlocked` 在本文件零命中）＋直扫公开方法 31→20、tree_can_buy 返回键 ≤6。 +- [ ] 树购买真链验证：tree_buy→meta_state.set_tree_level→write_to_disk→重读读回的真链断言改址保持（tree_requires_level_test 购买/cap/门槛判据逐字）。可核查结果：真链断言绿。 +- [ ] status_container：apply_effect 按「三臂语义逐字＋公共尾部收口」重构——守卫两 return 保留，independent/refresh/stack 三臂与未知 policy 告警保持现行为（independent 恒追加／refresh 命中改 R 未命中追加／stack 满层拒零写入·未满加层·未命中追加／未知 policy 告警拒），追加尾部收口单点；`_new_instance` 签名改 `func _new_instance(effect_id: String, layers: int, dur: int, source: Dictionary, snap: Dictionary) -> Dictionary`（7→5 参，snap＝{m, unit, display}）。可核查结果：seal_polarity／roll_multiplier／damage_controller／system_contracts 四套件全绿（满层拒绝/空刷新/快照语义现役断言面）。 +- [ ] treasure_items：validate_use 拆 `func _spatial_reject_reason(row: Dictionary, kinds: Array, target: Vector2i, board_size: Vector2i) -> String`＋`func _window_cells(target: Vector2i, board_size: Vector2i) -> Array`＋`func _preview_window_dead(resolved: Array, cell_unrevealed_cb: Callable) -> bool`。可核查结果：treasure_items_test 全绿。 +- [ ] 验证步骤：受涉套件窄确认全绿＋直扫三文件——8 键消失＋meta_progression 公开方法 31→20 读数记录。 + +### T7 config_db 归位＋域容器（≈1.4d） + +- [ ] 三容器建件（K1′①）：ConfigDomainCombat/Run/Crossrun（Resource、类型化成员、零方法）＋config_db 三容器成员替换 19 表成员＋load_tables 装配段改写（loaded→容器成员）。可核查结果：三新件直扫类变量 7/7/5 零 NEW。 +- [ ] 访问器归位（K1′②）：溶解 16＋迁移 14＋委托 3——迁移面按映射表入 shop_table（7 方法）/meta_table（2）/forge_table（3）/variation_table（2）；三表收 resolver 注入成员（类变量 1→2）；命名避开表类既有成员名（K1′② 映射表——routes 属性在册故 route_rows() 等）。可核查结果：受涉表类直扫公开方法/类变量零 NEW＋resolver 文件零 diff（键原位核验）。 +- [ ] 删 2＋私 1（K1′③④）：meta_conversion_row/forge_weapon_route_by_type 删除＋validate_skill_pool_links 私有化。可核查结果：grep 两删除名零命中。 +- [ ] 全域改址（≈800 处）：`db.<表>`→`db.<容器>.<表>`（537）＋访问器→表类直连/归位新名（264）——按映射表机械替换＋逐文件复核；诊断/门控保留核验：push_diag/is_fatal/diagnostics 族/reset_diagnostics/set_reload_gate/reload 与 EC8 门语义逐字（reload_gated 拒绝路径现役断言）。可核查结果：data_config 八套件＋core 直引 12 文件改址后全绿（行数据逐字断言＝表值等价载体）＋config_db_fatal_oob/level_shop_economy/forge_table_test/table_structure_guard/config_db_test 全绿＋直扫 config_db 44→8、25→9。 +- [ ] 验证步骤：数据面＋核心面窄确认全绿＋`db.combat.`／`db.run.`／`db.crossrun.` 前缀 grep 抽检（每容器 ≥5 文件零旧形态残留）。 + +### T8 adventure_table 拆段＋.tres 等值迁移（≈0.4d） + +- [ ] 三段件建件（K4′）：AdventureQuotaSegment/Value/CapSegment（段内槽名逐字）＋宿主 3 段成员＋访问器改读段（签名与返回语义逐字）＋validate() 判据经访问器读数不变。可核查结果：段件直扫类变量 13/13/9 零 NEW＋宿主 44→12。 +- [ ] adventure.tres 等值迁移：36 在册标量值逐槽照抄入嵌套段 sub_resource（单 .tres 保持）；缺省槽不写入＝缺省语义保持。可核查结果：deck_total()=102 结构锚断言绿＋adventure_feats/pool_case_d/feat_vouchers/table_structure_guard 全绿＋表值逐字对拍（改前改后 curio_quota/curio_value/curio_cap 全 13×4+13×4+9 组合读数零差异——T0 留档读数）。 +- [ ] 测试改址 4 处（pool_case_d_test :164/:165/:190 段路径读写、adventure_feats_test :206 段路径读）。可核查结果：改址断言绿。 + +### T9 散条组——action_economy／reward_economy／minesweeper_rules／unit_container spawn 束（≈0.6d） + +- [ ] action_economy：K5 三件（删 _next_round_mode 死存储＋_ap_exhausted_last 派生合并＋last_round_end 属性→方法）＋minesweeper_rules.gd:495 改址一处。可核查结果：minesweeper_rules_test／round_flow_skill_pool_test 的 round_end 载荷断言全绿（ap_exhausted_last_round 派生读等值——一滴不剩 when 面现役断言）＋直扫类变量 18→15。 +- [ ] reward_economy：拆 `func _normalize_eligible(eligible: Array) -> Array`（:42-52 去重/排序段——开流前，零 RNG 风险）＋`func _skew_amounts(down: Array, up: Array) -> Array`（两次 _largest_remainder_split 调用段）＋`func _apply_skew(base: Array, down: Array, up: Array, drops: Array, gains: Array) -> Array`（权重装配段——守恒 assert 随段迁移）。可核查结果：board_gen_reward_test／seal_polarity_test 前置全绿＋roll_board 取号序冻结（同种子身份批/清图批尾/区间行逐位一致——现役 reward_roll 流断言）。 +- [ ] minesweeper_rules：拆 `func _reveal_chain(c: Vector2i, reveal_order: Array, was_sealed: bool) -> void`（:301-329 揭示循环段——cell_revealed 发射序即链序，整体搬迁）。可核查结果：minesweeper_rules_test 全绿（cell_revealed 事件序现役断言）。 +- [ ] unit_container spawn 束化（K6′）：签名改 `func spawn(req: Dictionary) -> bool`（束键封闭词表逐字）＋体内拆 `func _spawn_hero_unit(hero_hp: int, atk_override: int, max_hp_override: int, hero_attack_type: String, hero_armor_type: String) -> bool`＋`func _spawn_rowset(rowset: Array, unit_count_overrides: Array, enemy_atk_overrides: Array, hp_mult: float, atk_mult: float) -> bool`（英雄段/行集段随分；束键解包留本体）。调用点改址 11 处 7 文件（battle_orchestrator 调用点按卡①合回后形态＋测试 10 处束字面量构造）。可核查结果：damage_controller／roll_multiplier／round_flow_skill_pool／skill_unlock／level_shop_economy 前置全绿＋grep `\.spawn(` 调用点全束形零旧签名残留＋直扫 spawn 参数键消失（长度/局部两键随体内拆分消失）。 +- [ ] 验证步骤：受涉套件窄确认全绿＋直扫四文件——上述键全部消失。 + +### T10 读数对拍＋撤销证明＋产出物落位卡（≈0.55d，末卡） + +- [ ] 改后 `python tools/gdstyle_gate.py` 对拍：基线外 NEW＝0（含 8 新件——新件键账表逐件核验）、恶化＝0、在案键计数较改前下降 86（86 键消失清单写进实现报告，零残留申报）。可核查结果：读数对拍表在案。 +- [ ] 逐 wr 行撤销证明（§8.1 末列——回退对应文件 hunk→gdstyle 直扫该键重现或改址断言红→还原复绿），记录进实现报告。 +- [ ] 写齐三份产出物（实现报告〔86 键清偿清单＋新件键账表＋五组改址计数实绩＋读数对拍表＋实机目检总清单——启动冒烟实机一屏登记（行为零变化批，登记不阻塞）〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）。 +- [ ] 合并前置：独立验收审计（§8.3）逐行「通过」。 + +**估时合计 ≈7.9d**（区间 7.4–8.4：T0 0.3／T1 0.7／T2 0.7／T3 0.7／T4 0.35／T5 1.5／T6 0.7／T7 1.4／T8 0.4／T9 0.6／T10 0.55；扩容主因＝K1′ 改址 ≈800 处〔T7〕、K2′ 拆件与改址 ≈450 处〔T5〕、K3′ 瘦身与投影改形〔T6〕、K4′ 拆段与 .tres 迁移〔T8〕、K6′ 束化〔T9〕——五组改址合计 ≈1330 处，机械替换＋逐文件复核计价）。 + +### T 卡间接口 + +- **取用与先后**：T5 先于 T6（meta 瘦身的读写面以 MetaStateStore 在位为前件）；T1–T4／T7／T8／T9 各自文件域独立、零相互取用（T7 与 T9 同触 minesweeper_rules.gd :495 仅 K5 改址一处——同卡内先 T7 后 T9 或一次性完成）；T10 取用各卡读数记录。 +- **产出**：T5 产出 SlotStore/MetaStateStore 公开面与投影键构成（K3′/反哺点③改写依据）；T6 产出 meta 封闭面 20 清单与 tree_can_buy 公开在位凭据；T7 产出三容器成员分组与 K1′ 归位映射落地形（反哺点③依据）；T8 产出段路径形态（反哺点②依据）；T9 产出 spawn 束键词表（卡①/卡③ T0 对齐依据）。 + +## 8. 验证闸 + +### 8.1 改动—验收对照表 + +| 需求点 | 改动（文件:行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---| +| wr1 校验族大表组 17 键 | 五 schema validate 拆分 | data_config＋core 受涉套件直跑全绿〔现役错误清单断言面＝逐字等价载体〕＋gdstyle 直扫五文件键消失 | 单元 | ConfigDb.load_tables 真实加载入口（套件经 _ready/load_tables 驱动） | 回退该文件 hunk→gdstyle 直扫该键重现→还原复绿 | +| wr2 校验族小表组＋跨表＋解析 23 键 | 八文件拆分 | 同上形态（八文件受涉套件）＋直扫键消失 | 单元 | 同上 | 同上 | +| wr3 生成器族 17 键 | board 四域拆＋_finalize 5 参＋node 六阶段拆 | board_generator_test／board_gen_reward_test＋node_map 三件全绿＋同种子逐位一致（T0 基线对拍） | 单元＋集成 | generate 真实调用（表驱动+rng_stream 注入）／generate(参数档， 种子) 纯函数入口 | 回退 hunk→同种子对拍失配或直扫键重现 | +| wr4 effect_engine 8 键 | 三装载域＋四算子域＋两键域＋elif 收口 | effect_words_t1／tree_rules_v11／counter_prefix_fatal／adventure_feats／round_flow_skill_pool 全绿（装载序/词表/计数器面现役断言） | 单元 | rebuild→dispatch 真实战斗链 | 回退 hunk→直扫键重现 | +| wr5 save 读盘域＋status/treasure 拆分 | _load_parsed/_peek_migrated 提取＋apply_effect 收口＋validate_use 拆三 | save_manager_domain／save_slot_summary／seal_polarity／roll_multiplier／damage_controller／system_contracts／treasure_items_test 全绿 | 单元 | autoload _ready＋套件真实驱动 | 回退 hunk→直扫键重现 | +| wr6 存档域拆件 K2′ | SlotStore/MetaStateStore 建件＋save 52→7＋状态分家＋改址 ≈450 | save 断言面全套直跑全绿（**存档读写逐位断言**＝save_rng_roundtrip roundtrip 键集逐位＋save_manager_domain 写读回等价，改址后判据逐字）＋**原子写/无激活态拒写/高版本拒读/激活回退四态**现役断言改址保持＋grep 槽位族/元进度族方法名在 save_manager 零命中＋直扫新件零 NEW | 单元＋探针 | SaveManagerCore autoload _ready 真实装配＋套件直构实例经 save.slots/save.meta_state 真链驱动 | 回退 hunk→改址断言红（save.slots 成员不存在＝脚本错误被闸③捕获）或直扫键重现 | +| wr7 meta_progression 瘦身 K3′ | 纯转发退役 2＋内联 3＋并组 3＋私 3＋留置 20 | tree_requires_level/meta_progression_forge 改址后全绿（**树购买真链断言**＝tree_buy→set_tree_level→write_to_disk→重读读回真链）＋hero_override 输出逐字断言绿＋grep **纯转发零残留**（save.keystone_balance/save.item_unlocked 在本文件零命中）＋直扫 31→20、tree_can_buy 返回键 ≤6 | 单元 | meta.tree_buy/forge_buy_level 真实购买链（camp 投影数据源同链） | 回退 hunk→改址断言红或直扫公开方法键回 31 | +| wr8 config_db 归位＋域容器 K1′ | 3 容器建件＋33 归位＋删 2 私 1＋改址 ≈800 | data_config 八套件＋core 直引 12 文件改址后全绿（**行数据逐字断言**＝表值读数等价载体）＋**消费改址断言**（config_db_test/forge_table_test/level_shop_economy/table_structure_guard/config_db_resolver_test 全绿）＋grep 两删除名零命中＋reload/EC8 门保留断言绿＋直扫 44→8、25→9、新件零 NEW | 静态＋单元 | load_tables 真实加载入口＋resolve_rowset 消费链（unit_container spawn 前置） | 回退 hunk→改址断言红（db.combat 成员不存在）或直扫键回 44/25 | +| wr9 adventure_table 拆段 K4′ | 3 段件＋.tres 等值迁移＋访问器改读段＋4 处改址 | adventure_feats/pool_case_d/feat_vouchers/table_structure_guard 全绿＋**deck_total()=102 结构锚＋表值逐字**（T0 留档全组合读数零差异）＋validate 绿＋直扫 44→12、段件零 NEW | 单元 | 表加载→访问器读数真实链 | 回退 hunk（含 .tres）→改址断言红（段路径不存在）或直扫键回 44 | +| wr10 散条组 K5＋reward/minesweeper 拆分 | action 删并＋两文件域拆 | minesweeper_rules_test／round_flow_skill_pool round_end 载荷／reward_roll 流序全绿 | 单元 | 各系统真实调用链 | 回退 hunk→对应断言红（last_round_end() 方法不存在/取号序失配/事件序失配）或直扫键重现 | +| wr11 spawn 束化 K6′ | 签名 10→1＋体内两域拆＋调用点 11 处改址 | 前置五套件全绿＋**调用点断言**（grep `\.spawn(` 全束形零旧签名残留）＋直扫参数键消失 | 单元 | battle_orchestrator begin_battle 真实遭遇链 | 回退 hunk→调用点 grep 现旧形（断言红）或直扫键重现 | +| wr12 读数对拍＋产出物 | T10 | 读数对拍表＋三份产出物件核〔wr12〕 | — | — | 缺项红 | + +回归措辞：里程碑步（T 卡）出口跑一次全套闸（按本批改动域选档 `--code`）；卡内修复只做出红最小单元的最窄确认；新增测试先行孤立验证再并入全套。本批零新增测试断言（现役断言面即验收载体；grep 形判据为静态在位核验，非新运行时断言）。 + +### 8.2 测试削弱申报 + +零（无断言删除、无阈值放宽、无扫描面缩小；全部测试改动＝K1′–K6′ 列明的调用点改址与投影同值改形，断言语义与判据逐条保持——契约 2）。 + +### 8.3 独立验收审计 + +入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`；抽查重点＝①错误清单逐字等价（任选三 schema 改前改后坏表对拍读数）②生成器同种子逐位一致记录③效果引擎装载序与词表零 diff（git diff 查 EVENTS/EFFECT_KINDS/FACTS/OPS 四常量）④归位映射抽检（每容器 ≥3 处行数据逐字＋K1′ 溶解/迁移/委托三形态各 ≥2 处）⑤拆件抽检（save roundtrip 逐位读数＋激活回退四态断言＋纯转发零残留 grep 复跑）⑥拆段表值逐字（全组合读数对拍）⑦新件键账零 NEW（gdstyle 直扫 8 新件）⑧S13 基线未改（git diff 查 `tools/gdstyle_baseline.txt` 零变化）⑨改址抽检（五组各 ≥3 处断言语义等价）⑩撤销证明复现。未过不得合并。 + +## 9. 异常分级 + +- **L1（自救）**：行号漂移（T0 重锚自核）；私有 helper 与投影内部实现的命名与注释措辞（投影键构成与公开签名不属此列）；拆分域边界微调（各件 ≤阈值前提下）。 +- **L2（记录继续）**：五组改址中发现清单外调用点（同法改址＋计数记录进实现报告）；束键解包的等价实现细节；段件/容器成员的 @export 形态细节（类型化成员语义不变前提下）。 +- **L3（停机呈报）**：任何断言红且非测试问题；拆分后错误清单与改前不等价；RNG 取号序失配；存档读写逐位不等价或原子性语义漂移；归位后表读取语义漂移（空表护栏/缺省兜底）；发现触碰 GDD/owner 契约的病根（停卡呈报，禁内联求裁）；新件或留置面超阈（封闭面破坏——契约 3）；K 清单外须动公开面的场景（实现段零裁断——退回上游）。 + +## 10. 代拍板白名单（超清单必呈报） + +1. 私有 helper 的命名与注释措辞（语义不变前提下）。 +2. 拆分域边界的等价微调（各件 ≤阈值、错误序/RNG 序不变前提下）。 +3. 五组改址的等价调用写法（访问路径等价、断言语义不变前提下）。 +4. 归位方法在表类侧的等价命名微调（避开既有成员名、映射语义不变前提下）。 +5. 提交切分与 worktree 分支命名。 + +## 11. 待裁点（零待裁点） + +**零待裁点（2026-10-27 用户裁决记录：①config_db 彻底清零=归位+域容器 ②save/meta 彻底清零=SlotStore/MetaStateStore 拆件）**。随裁记录全四项：③adventure_table 类变量 44 拆子 Resource 段（形态同 settlement_table 拆段）；④unit_container spawn 参数签名引用束化。裁决落点：v1.0 裁点 1 的案 B 走向＝归位＋域容器 Resource（非词典化形态，D7）；v1.0 裁点 2 的案 B 走向＝域对象拆件经设计段先行定稿（架构 v1.19 :88/:89/:90/:126 四行登记）后扩入本卡。开工门＝U0＋复核门（§12）。 + +## 12. 自审六查与复核记录 + +**自审六查（2026-10-27 修订会话，grilling 自检一轮合并执行——对抗审点逐条过并就地折入）**： +- ①规格覆盖：86 键逐文件→T1–T9（大表组/小表组/生成器/效果引擎/存档拆件/meta 瘦身/config_db 归位/拆段/散条与 spawn）→wr1–wr11，读数与产出物→T10/wr12；全清账目闭合（86＝65 拆分＋21 结构收敛；留置 8＋归位 33＋删 2＋私 1＝44、槽位 10＋元进度 35＋断点 4＋IO 3＝52、31−11＋3＝20）；K1′–K6′ 公开面改动逐项有改法＋映射＋消费方影响面＋封闭面预演值。**折入**：修订会话实查订正 v1.0 两处实查笔误——meta_progression 三件「内部零调用」实为 hero_override 单调用点（处置由删改内联、输出逐字）、adventure_table「37 个 @export」计法订正为 44（账目不变）。 +- ②步骤扫描：每步一动作一可核查结果（拆分步挂「受涉套件绿＋直扫键消失」双结果；建件步挂「键账零 NEW＋断言改址绿」双结果）；无 TBD/酌情行；实现体零抄写（helper 只给签名与域边界）。 +- ③类型一致性：K1′ 归位映射表与 T7 步骤逐字一致；K2′ 两 store 公开面清单（13 写＋6 投影／10 槽位）与 §3.5 预演值、T5 步骤逐字一致；K3′ 封闭面 20 清单与 T6 步骤逐字一致；K4′ 段件键名与宿主访问器签名逐字一致；K6′ 束键词表与 T9 步骤逐字一致；wr 行与 T 卡引用对得上；投影返回键构成在 K2′②/K3′ 两处表述同文。 +- ④审查焦点＋改动覆盖：最可能坑到玩家的失败模式＝①错误清单不等价（fail-fast 面变形）→ 现役 data_config 断言面逐字保留＋审计①对拍；②RNG 取号序漂移 → 契约 1②＋T3/T9 同种子对拍；③效果引擎装载序漂移 → 契约 1④＋T4 调用序钉死＋审计③四常量零 diff；④存档盘面语义漂移（原子写/回退/迁移链）→ 契约 1⑥＋wr6 逐位与四态断言＋审计⑤；⑤拆段 .tres 迁移值错位 → 等值迁移＋deck_total=102＋全组合读数对拍＋审计⑥；⑥归位后空表护栏/缺省兜底漂移 → 契约 6 口径＋K1′⑤ 注记＋审计④。结构图中全部行为改动行＝「非行为」并指到 wr 行——**查毕确认零行为改动、无未覆盖失败模式**。 +- ⑤篇幅比例：全文无函数体，helper 为签名＋域边界；§3 现状表为键账载体非抄写；映射表为改址合同非代码罗列。 +- ⑥落位与复用：新件 8 逐件「为什么不能复用既有」有答（God Class 本体不可复用其内部结构——§7 预检）＋架构 v1.19 行指针（:88/:89/:90＋段件形态既裁）；唯一面（新件类名 grep 零同名＋跨文件同名私有方法类作用域不冲突）与分层面（零新跨层路径、零 autoload、S1–S6 逐项过）已答；K1′–K6′ 每项公开面改动可指到预检节条目；新件封闭面逐件给出与阈值的余量（19/20、10/20、7·7·5/15、13·13·9/15、留置 20/20——20/20 与 15/15 均循卡①「封闭面 15≤15」先例，架构 :126 对外暴露列即封闭依据）。 + +**grilling 自检一轮结论（写卡段内自检，独立复核门仍须在开工前由用户/独立会话执行）**：骨架成立——全清账目闭合、零待裁点、新件封闭面全部可达阈内、行为零变化契约族完备（含存档序列化第六款）。对抗审点七条全折入：①MetaStateStore 35 原语直收将出 NEW 键（35>20）→ 读投影 6＋写原语 13＝19 收敛（架构 :90「数据读写原语族＋只读投影」即此形态，K2′②）；②meta_progression 按 v1.0 K3 算法只到 24/25，到不了 20 → 并组 3 组＋forge_route_unlocked 私有化补齐 20（消费面 grep 逐方法核验——生产零者才私）；③tree_can_buy 按 v1.0 应私有、但 v1.19 :126 对外暴露列在册 → 留公开、测试 8 处零改址（随 K3′ 记录）；④resolver 文件键函数禁搬移 → resolve 委托注入形态（文件零搬移、T2 照旧）；⑤shop_table/forge_table 归位方法与既有属性同名冲突（routes/products 等）→ 映射表改名（gp_drop_row/route_rows/product_rows 等）；⑥db.adventure 表与容器命名的双层同名风险 → 容器名 combat/run/crossrun 三名全避让（成员名零碰撞——grep 零命中）；⑦改址量重估：v1.0 口径 139 处 → 实查五组 ≈1330 处（估时 4.9→7.9d 如实上调）。遗留提示三件随卡在案：①估时超迭代冻结线——编入时循迭代 39 特批先例由用户裁；②本卡与卡③呈现侧改址行同文件触碰——编排错波；③main.save_manager 句柄面改址不新增句柄成员——:183 豁免面不扩大（审计⑧随核）。 + +## 13. 禁为机检文本保留无效成员（重构类必填条款） + +禁止为迎合机检消息文本（含计数）而保留或新增无效成员／别名／死存储／转发壳：本批删除的 `_next_round_mode` 死存储与 K1′ 两访问器、K3′ 两纯转发即该契约的执行例——不得以「基线计数」「兼容过渡」「调试便利」等理由保留任何在删清单成员、新增同种件或在退役点留同名转发；新件公开面＝K 清单封闭面（MetaStateStore 19／SlotStore 10／meta_progression 20／config_db 8），禁为凑数或过渡加别名与委托壳；机检键与卡片契约互斥时实现段一律停卡呈报，不得自造第三条路（code-conventions §1.1 同款）。 diff --git a/reports/需求卡片-结构小件定点修批-2026-10-26.md b/reports/需求卡片-结构小件定点修批-2026-10-26.md index 4415c69b..824830bb 100644 --- a/reports/需求卡片-结构小件定点修批-2026-10-26.md +++ b/reports/需求卡片-结构小件定点修批-2026-10-26.md @@ -1,62 +1,72 @@ -# 需求卡片：结构小件定点修批（审计 §三 其余小件五件：死变量/confirm 收口/空判/常驻 flush/fatal 违约回调） +# 需求卡片：结构小件定点修批（审计 §三 其余小件六件：死变量/confirm 收口/空判/常驻 flush/fatal 违约回调/未播种取数通道） -- 版本：**v1.2**（v1.0→一轮「通过（附四应修＋一建议）」→v1.1→二轮闭合复检「通过（附三应修）」→v1.2 定稿，复核记录见 §12） -- 来源：[待办清单](../待办清单.md)「结构审查未立项小件候审」条目（2026-10-25 登记，状态=待裁决）——**2026-10-26 用户裁「全六件立项」**；本卡收五件（①③④⑤⑥，审计原编号），件②（level_map 越界/BFS）独立成卡（结构改动量独立、审查单元分立）（唯一事实源：工程证据指认＝审计报告 [§三 其余小件](审计-game代码结构审查-2026-10-24.md) §90-95 逐件行号＋本卡 §3 行号级实查〔迭代 37 拆件后行号重定位〕） -- 归属：`game/presentation/main_overlay_flow.gd`＋`game/presentation/main.gd`＋`game/presentation/row_pacer.gd`（消费一行）＋`game/core/board_generator.gd`＋`game/core/reward_economy.gd`＋`game/core/rng_service.gd`＋`game/core/battle_orchestrator.gd`（组装接线两行）＋测试面（探针回归＋新断言） -- 排期：未编入（迭代批卡片；估时 ≈0.75 工作日） +- 版本：**v1.3**（2026-10-26 定稿——含迭代 38 停卡后的载体修订与复核轮收紧；逐轮 grilling 与停卡呈报记录见 §12） +- 来源：[待办清单](../待办清单.md)「结构审查未立项小件候审」条目（2026-10-25 登记，状态=待裁决）——**2026-10-26 用户裁「全六件立项」**；本卡收六件（①③④⑤⑥ 审计原编号＋p7 同函数第二处，2026-10-26 用户裁「并修」随 v1.3 入卡），件②（level_map 越界/BFS）独立成卡、已随迭代 38 卡① 合回退役（git 提交 b85b3b45／8ea7cfba）（唯一事实源：工程证据指认＝审计报告 [§三 其余小件](审计-game代码结构审查-2026-10-24.md) §90-95 逐件行号＋本卡 §3 行号级实查〔迭代 37 拆件后行号重定位〕） +- 归属：`game/presentation/main_overlay_flow.gd`＋`game/presentation/main.gd`＋`game/presentation/row_pacer.gd`（消费一行）＋`game/core/board_generator.gd`＋`game/core/reward_economy.gd`＋`game/core/rng_service.gd`＋`game/core/battle_orchestrator.gd`（组装接线两行）＋测试面（新增负面套件一件＋其 `.uid` 边车＋`game/tests/run_all.gd` manifest 登记一行＋探针回归） +- 排期：未编入（迭代批卡片；估时 ≈0.85 工作日——含负面套件新件、manifest 登记与清单对账 ≈0.1d；归属车道随「gdstyle 存量债全量清偿」条目波 7 或另编迭代，由编排段定） - 开工门：U0＋复核门过（§12）；零待裁点 ## 0. 前置依赖与并行性 - **第〇步核对（2026-10-26 写卡会话）**：来源条目＝需求性工程条目（审计行号证据），用户 2026-10-26 点名全六件立项——放行。 -- 审计行号基线＝2026-10-24（迭代 37 拆件前）；本卡 §3 已按现行 master（eb04313b）重定位（①main→main_overlay_flow 拆件迁移、③行号漂移），T0 复核。 -- 与 2026-10-25 两批卡零文件交叠（卡 A 触 battle_orchestrator 的发射点/头注/校验段——本卡 p5 只动组装点 :278/:283 两行接线与两协作件 _fatal，不同面；rng_service p6 与其零叠）。同波无冲突。 +- 审计行号基线＝2026-10-24（迭代 37 拆件前）；本卡 §3 已按现行 master 重定位（①main→main_overlay_flow 拆件迁移、③行号漂移），**v1.3 复核轮再按迭代 38 合回点 8ea7cfba 重锚一遍**（`battle_orchestrator.gd` 组装点与 `_fatal`、`main.gd` 各址均漂移），开工日 T0 仍须复核。 +- 与 2026-10-25 两批卡零文件交叠（卡 A 触 battle_orchestrator 的发射点/头注/校验段——本卡 p5 只动组装点的两行接线与两协作件 `_fatal` 成员，**按语义面判交叠、不按行号**：行号随合回漂移，「发射与校验段」对「组装点接线行」的面不相交在换代后仍成立；rng_service p6/p7 与其零叠）。同波无冲突。 +- p6/p7 同触 `rng_service.gd:100-112` 同一函数的两条分支——v1.3 并修后两处改动面相邻，禁拆成两波同文件互踩（一条波次内完成）。 +- **与「核心数据面结构收敛批」（2026-10-27 v1.0，在册同条目）文件交叠**：同触 `board_generator.gd`（本卡改 `_fatal` :396-398）与 `reward_economy.gd`（本卡改 `_fatal` :366-368）——该卡 §0 已记此交叠并裁「编排串行、后行者 T0 吸收行号漂移」。本卡体量最小（六件皆行级），**宜先行**；若被排在该卡之后，§1/§3/S5 的行号锚一律按其 T0 重核，禁照搬本卡现值。 - p5 触结算域（core 件 _fatal 形态）——parity 触面按 MC 纪律：零数值改动＝零 MC（_fatal 是违约路径，合法路径零触碰）。 ## 1. 目标与完成定义 -**目标**：五件审计定点小件落地——①_ sync_status_entry 死变量与重复四句清除；③settle_batch 两入口显式 null 防护；④row_pacer 会话更替机制化 flush；⑤两 core 协作件 _fatal 的 release 软回退补真中止通道（经 orchestrator 既有封印传导）；⑥rng_service open_stream 未知标签补 return＋可测违约回调。合法路径行为逐位不变（p2 confirm 收口是唯一行为改动＝锁域归位，对照表专行）。 +**目标**：六件审计定点小件落地——①_ sync_status_entry 死变量与重复四句清除；③settle_batch 两入口显式 null 防护；④row_pacer 会话更替机制化 flush；⑤两 core 协作件 _fatal 的 release 软回退补真中止通道（经 orchestrator 既有封印传导）；⑥rng_service open_stream 未知标签补 return＋可测违约回调；⑦同函数未播种取数分支（`_master_seed < 0`）同款补 return＋违约回调（p6 同病根第二处，v1.3 用户裁并修）。合法路径行为逐位不变（p2 confirm 收口是唯一行为改动＝锁域归位，对照表专行）。 + +**验收载体口径**（v1.3 停卡修订立此，实装段禁改回落位）：违约路径取证（wr5/wr6/wr7）**一律落独立负面套件**并按 manifest 登记 `expect=1, negative=true`，禁落现役非负面套件——headless 下 `assert` 失败必产 `SCRIPT ERROR` 行、不可捕获，非负面套件的输出被闸 02 扫描命中即判 FAIL（规则出处＝test-conventions §5「负面套件仅可豁免第 2 闸，且须在 manifest 显式标记」；在册先例三件＝`reward_dangling_treasure_test`／`counter_prefix_fatal_test`／`extended_row_violation_test`）。 **改动单元清单**（🔴 契约 1）： | # | 单元（实查·现行行号） | 改法 | 依据 | |---|---|---|---| | p1 | `main_overlay_flow.gd:107-124` `_sync_status_entry`：:111 `var battle_live` 赋值后零消费（死变量）＋首组四句 :112-116（:114 置灰注释行夹中）与重复四句 :119-122 逐字相同（:117-118「重复语句在案」注释两句自认） | 删 :111 死变量行＋删 :117-122（自认注释两句＋重复四句）；保留首组与 :123-124 调试角标注释段（非重复组——grilling 订正 v1.0 误圈） | 审计 ①；死代码与重复句清除 | -| p2 | confirm 旁路单口违约：`main_overlay_flow.gd:88` `root.confirm_dialog.open(...)` 与 `main.gd:312/:321` `confirm_dialog.close()` 直开直关——绕过 `_open_modal/_close_modal`（main.gd:282-286 → ModalFlow.open/close 挂起兜底/遮挡记账/开侧同步），违 main.gd 自身头注单口纪律；confirm_dialog.gd:40-41「树序由构建序保证」注释失真 | 三处收口：open 前经 `root._open_modal(root.confirm_dialog)`（ModalFlow.open 承载显示编排，T0 核其与 confirm_dialog.open 设文案的先后序）；close 经 `root._close_modal(...)`；:40-41 失真注释随修。**行为改动＝confirm 开合进 ModalFlow 栈（输入锁/互斥域归位）**——对照表专行＋探针回归 | 审计 ①后半；架构单口纪律 | -| p3 | `main.gd:722/:749` settle_batch 两入口直取 `run_scope.settlement.minesweeper.settle_batch(...)`——前置空判隐式依赖 `_input_locked` 第三例外（锁谓词保证只在局内可达） | 两入口各加显式防护：`if run_scope.settlement == null: return`（零成本双保险——锁谓词异常时不再崩于空引用） | 审计 ③「入口显式 null 防护零成本双保险」 | +| p2 | confirm 旁路单口违约：`main_overlay_flow.gd:88` `root.confirm_dialog.open(...)` 与 `main.gd:311/:320` `confirm_dialog.close()` 直开直关——绕过 `_open_modal/_close_modal`（main.gd:281-285 → ModalFlow.open/close 挂起兜底/遮挡记账/开侧同步），违 main.gd 自身头注单口纪律；confirm_dialog.gd:40-41「树序由构建序保证」注释失真 | 三处收口：open 前经 `root._open_modal(root.confirm_dialog)`（ModalFlow.open 承载显示编排，T0 核其与 confirm_dialog.open 设文案的先后序）；close 经 `root._close_modal(...)`；:40-41 失真注释随修。**行为改动＝confirm 开合进 ModalFlow 栈（输入锁/互斥域归位）**——对照表专行＋探针回归 | 审计 ①后半；架构单口纪律 | +| p3 | `main.gd:721/:748` settle_batch 两入口直取 `run_scope.settlement.minesweeper.settle_batch(...)`——前置空判隐式依赖 `_input_locked` 第三例外（锁谓词保证只在局内可达） | 两入口各加显式防护：`if run_scope.settlement == null: return`（零成本双保险——锁谓词异常时不再崩于空引用） | 审计 ③「入口显式 null 防护零成本双保险」 | | p4 | `row_pacer.gd:11` `_rows` 待播队列住 main 级常驻节点（违架构「局态一律住 RunScope」）——会话更替零残留靠时序约定兜底 | `main.gd:175` `_begin_session` 内加 `_row_pacer.flush()` 一行（:49 现成公开面——机制保证会话更替即清队） | 审计 ④「_begin_session 内 flush 一行变机制保证」 | -| p5 | `board_generator.gd:396-398` 与 `reward_economy.gd:366-368` 两处 `_fatal`＝push_error＋assert(false)——release 模板剥离 assert 后退化为软回退（无 orchestrator 的 battle_result 封印兜底） | 两件 `_fatal` 各加可注入违约回调：`var fatal_handler: Callable`（缺省 `Callable()`＝现行为逐字保持）＋`_fatal` 体内 handler 有效则调用；组装点 `battle_orchestrator.gd:278/:283` 各接一行 `fatal_handler = _fatal`（orchestrator 自身 _fatal :1292 已带 battle_result 封印——协作件违约即传导封印＝战斗中止，release 真中止成立） | 审计 ⑤「出包前需换真中止（可经宿主注入 fatal 回调）」——经组装层传导，零穿透三层、复用既有封印 | +| p5 | `board_generator.gd:396-398` 与 `reward_economy.gd:366-368` 两处 `_fatal`＝push_error＋assert(false)——release 模板剥离 assert 后退化为软回退（无 orchestrator 的 battle_result 封印兜底） | 两件 `_fatal` 各加可注入违约回调：`var fatal_handler: Callable`（缺省 `Callable()`＝现行为逐字保持）＋`_fatal` 体内 handler 有效则调用；组装点 `battle_orchestrator.gd:285/:290` 各接一行 `fatal_handler = _fatal`（orchestrator 自身 _fatal :1304 已带 battle_result 封印——协作件违约即传导封印＝战斗中止，release 真中止成立） | 审计 ⑤「出包前需换真中止（可经宿主注入 fatal 回调）」——经组装层传导，零穿透三层、复用既有封印 | | p6 | `rng_service.gd:100-103` `open_stream` 未知标签 push_error＋assert 后**无 return**——release 剥 assert 后静默继续发号（违随机流纪律） | 补违约通道：`var violation_handler: Callable`（缺省现行为）＋未知标签分支 handler 有效则调用＋**`return null`**（合法路径零变化；release 下返回 null 使调用方即刻崩＝fail-fast 传导）；handler 注入使负路径 debug 可测（见 wr6） | 审计 ⑥「补 return 即闭合」＋可测性（撤销证明口径） | +| p7 | `rng_service.gd:104-106` `open_stream` 的 `_master_seed < 0` 分支＝push_error＋assert 后**同样无 return**（p6 同病根第二处，grilling 一轮点名、v1.3 用户裁并修）——未播种即取数在 release 剥 assert 后静默继续发号（违 EC7 与随机流纪律） | 未知标签通道同款：该分支复用 p6 的 `violation_handler`（handler 有效则调用，传用途标签）＋**`return null`**（合法路径零变化；release 下调用方即刻崩＝fail-fast 传导）；违约取证落负面套件第 ③ 测试点（见 wr7） | 审计 ⑥同函数第二处；卡面 §9 L3 原停卡条款经用户裁转并修 | + **完成定义**： -1. p1–p6 落地；合法路径全套闸按域选档全绿； -2. wr 断言绿（p5 封印传导/p6 违约回调两条新断言＋p2 锁域回归）； -3. 撤销证明三条（p1/p5/p6 各一——§8）；三份产出物写齐（T2）。 +1. p1–p7 落地；合法路径闸按域选档处置闭合——本批属代码面（`game/` 下非 `.md`），验收＝`tools/run_all_gates.sh --code`；**闸 09 现状不是绿**：09 静态扫描基线为迭代 38 带红合并时用户特批登记的存量红（`game/tests/.gates/baseline.json` 闸 09 `exit=1`、标记 `user-approved-iter38`），p5 接线两行加在 `battle_orchestrator.gd`（现 1313 行，基线 `max-file-length` 登记 1302）＝同键继续恶化，p6/p7 给 `rng_service.gd` 加成员与两行是否出 NEW 键须实测（`gdstyle_gate.py` 的 SCAN_DIRS＝core/data/presentation，不含 `game/tests/`，故新测试文件本身零影响）——**实现段开工前由用户二选一处置：随批还债（压缩该文件行数）或经批准刷新基线，禁以「闸 09 全绿」为完成定义**；其余闸段全绿； +2. wr 断言绿（负面套件三点＝wr5 封印传导＋缺省、wr6 未知标签违约通道、wr7 未播种违约通道；加 p2 锁域回归与 wr4 夹具断言）； +3. 撤销证明四条（p1/p5/p6/p7 各一——§8.1，负面套件那三条按退出码口径判红）；三份产出物写齐（T2）。 ## 2. 设计事实源 | # | 出处 | 取用条款 | |---|---|---| -| D1 | 工程证据指认＝审计报告 §三「其余小件」段（§90-95 逐件）＋本卡 §3 实查重定位 | 五件清单与判据 | +| D1 | 工程证据指认＝审计报告 §三「其余小件」段（§90-95 逐件）＋本卡 §3 实查重定位 | 六件清单与判据 | | D2 | [architecture](../design/engineering/architecture/architecture.md)「局态一律住 RunScope」＋单口纪律 | p2/p4 依据 | | D3 | [code-conventions](../design/engineering/code-conventions.md) §1（死代码/重复语句）＋fail-fast 红线 | p1/p3/p5/p6 依据 | | D4 | 2026-10-26 用户令「全六件立项」 | 立项凭据 | +| D5 | 2026-10-26 用户裁「把需求变更给修正确」（迭代 38 卡② 停卡呈报后）——批准 v1.3 两处载体修订＝wr5/wr6/wr7 落独立负面套件＋p7 并修 | 停卡修订凭据 | -## 3. 现状事实（2026-10-26 写卡会话实查于 master eb04313b——审计 2026-10-24 行号已按拆件后重定位；开工日 T0 复核行号） +## 3. 现状事实（2026-10-26 写卡会话实查，v1.3 复核轮按迭代 38 合回点 8ea7cfba 重锚行号——审计 2026-10-24 行号已按拆件后重定位；开工日 T0 复核行号） | # | 事实 | 出处 | |---|---|---| | S1 | `_sync_status_entry` 现住拆出件：:111 死变量 battle_live（赋值零消费）；首组四句 :112-116 与重复四句 :119-122 逐字相同（:117-118 注释自认「重复语句在案」；:123-124 调试角标注释独立保留） | `game/presentation/main_overlay_flow.gd:107-124` | -| S2 | confirm 旁路三处：main_overlay_flow.gd:88 open（选档删除确认流）＋main.gd:312/:321 close（确认/取消两分支）；单口 `_open_modal`→`_modal_flow.open(m)`（挂起兜底/排播排空/遮挡记账/开侧同步——main.gd:282-283 注释）；confirm_dialog：open(:36 设文案)/close(:46)/is_open(:50)，:40-41 注释「树序由构建序保证」与 ModalFlow 登记序口径不符 | `game/presentation/main_overlay_flow.gd:88`；`game/presentation/main.gd:312/321/282-286`；`game/presentation/views/confirm_dialog.gd:36-50` | -| S3 | settle_batch 两入口：:722（棋盘动作批次——treasure 劫持检查后直取）与 :749（stop 批次——:746 有 `_input_locked` 守卫）均无 settlement null 防护 | `game/presentation/main.gd:722/749` | +| S2 | confirm 旁路三处：main_overlay_flow.gd:88 open（选档删除确认流）＋main.gd:311/:320 close（确认/取消两分支）；单口 `_open_modal`→`_modal_flow.open(m)`（挂起兜底/排播排空/遮挡记账/开侧同步——main.gd:281-282 注释）；confirm_dialog：open(:36 设文案)/close(:46)/is_open(:50)，:40-41 注释「树序由构建序保证」与 ModalFlow 登记序口径不符 | `game/presentation/main_overlay_flow.gd:88`；`game/presentation/main.gd:311/320/281-285`；`game/presentation/views/confirm_dialog.gd:36-50` | +| S3 | settle_batch 两入口：:721（棋盘动作批次——treasure 劫持检查后直取）与 :748（stop 批次——:743 有 `_input_locked` 守卫）均无 settlement null 防护 | `game/presentation/main.gd:721/748` | | S4 | row_pacer 常驻队列 `_rows: Array[Variant]`（:11）＋现成公开 `flush()`（:49）；`_begin_session`（main.gd:175）现不 flush | `game/presentation/row_pacer.gd:11/49`；`game/presentation/main.gd:175` | -| S5 | 两协作件 `_fatal`＝push_error＋assert(false) 两行（无兜底——board_generator 实址 :396-398，grilling 订正 v1.0 的 :391-393；reward_economy :366-368 准确）；组装点在 orchestrator（:278 `BoardGenerator.new()`、:283 `RewardEconomy.new(db, rng)`）；orchestrator 自身 `_fatal`（:1292）＝push_error＋`battle_result = "fatal_error"` 封印＋assert（release 剥 assert 后封印仍在＝唯一阻断面） | `game/core/board_generator.gd:396-398`；`game/core/reward_economy.gd:366-368`；`game/core/battle_orchestrator.gd:278/283/1292-1295` | +| S5 | 两协作件 `_fatal`＝push_error＋assert(false) 两行（无兜底——board_generator 实址 :396-398，grilling 订正 v1.0 的 :391-393；reward_economy :366-368 准确）；组装点在 orchestrator（:285 `BoardGenerator.new()`、:290 `RewardEconomy.new(db, rng)`）；orchestrator 自身 `_fatal`（:1304）＝push_error＋`battle_result = "fatal_error"` 封印＋assert（release 剥 assert 后封印仍在＝唯一阻断面） | `game/core/board_generator.gd:396-398`；`game/core/reward_economy.gd:366-368`；`game/core/battle_orchestrator.gd:285/290/1304-1307` | | S6 | `open_stream` 未知标签分支（:101-103）push_error＋assert 后直落 `_master_seed` 检查与发号——无 return；PURPOSE_TAGS 封闭词表（头注 EC12） | `game/core/rng_service.gd:100-112` | +| S7 | 同函数 `_master_seed < 0` 分支（:104-106，2026-10-26 v1.3 复核码面仍在）＝push_error＋`assert(false, "未播种取数致命（EC7）")` 后同样无 return，直落 :107 起的取号与发号段——debug 下 assert 只中断当前函数、控制流回调用方，release 下剥 assert 后静默发号 | `game/core/rng_service.gd:104-112` | ## 4. 设计契约（红线，违反 = L3 停机呈报） -🔴 **契约 1 · 改动面封闭**：p1–p6 只动 §1 所列行；合法路径（无违约输入）行为逐位不变——结算、随机发号、排播时序、角标同步零变化；p2 是唯一申报的行为改动（锁域归位）。 +🔴 **契约 1 · 改动面封闭**：p1–p7 只动 §1 所列行；合法路径（无违约输入）行为逐位不变——结算、随机发号、排播时序、角标同步零变化；p2 是唯一申报的行为改动（锁域归位）。 + +🔴 **契约 6 · 负面载体不得回落现役套件**（v1.3 停卡修订立）：违约取证若被写回现役非负面套件，闸 02 必红且违 test-conventions §5 的显式标记要求——实装段禁自行「复用既有套件省事」。三测试点的回归态判据**只能取「改前改后真有差异」的可观测面**＝handler 成员与调用点是否存在（记录位）、封印是否落；`return` 位与计数器读数在 debug 下两态不可判别（assert 先中断函数本体，控制流回调用方，`:107-108` 的推计数段谁也到不了），把它当运行期判据＝假绿——p6/p7 的 `return` 走静态判据＋grep 在位＋评审注记（同 wr3 手法）。 🔴 **契约 2 · 缺省零变化**：p5/p6 的 handler 缺省（`Callable()`）时两件 `_fatal` 与 `open_stream` 行为逐字等于现状——禁顺手改 push_error 文案与 assert 条件。 @@ -68,7 +78,7 @@ ## 5. 范围边界 -**做**：p1–p6；新断言两条；探针回归；撤销证明；产出物。 +**做**：p1–p7；一个负面套件新件（三测试点）＋`run_all.gd` manifest 登记一行；wr2 锁域回归与 wr4 夹具断言；探针回归；撤销证明；产出物。 **不做**： - 件②level_map 三段（独立卡：独立卡已随迭代 38 卡① 实现合回并按「吸收即死」退役（git 提交 b85b3b45／8ea7cfba 可考））； @@ -80,7 +90,8 @@ | 文档 | 关联点 | 同步义务 | |---|---|---| -| `待办清单.md` | 来源条目（六件候审）状态推进：五件归本卡＋件②归独立卡＋用户点名记录 | 反哺点 · 列清单（①：状态核对注记） | +| `待办清单.md` | 来源条目状态：原「结构审查未立项小件候审」六件候审条目 2026-10-26 已并入「gdstyle 存量债全量清偿」条目波 7（本卡为其登记在册的现成卡），本卡出账随该条目波 7 推进，禁另立重复条目 | 反哺点 · 列清单（①：状态归属注记） | +| `design/engineering/test-conventions.md` §5 | 负面套件豁免第 2 闸的规则**已在册、零修订预期**——本卡只是首次把「运行期违约通道取证」这条落位规则用满（先例三件在册）；如复核认为该规则该升级为「违约通道类需求点必须落负面套件」的显式条款，列反哺点由文档批裁 | 反哺点 · 列清单（③：预期零改动注记） | | [architecture](../design/engineering/architecture/architecture.md) 模块归属表 | p2/p4 若涉契约表述（单口纪律/RunScope 条款现行表述已覆盖——预期零改动；T0 核） | 反哺点 · 列清单（②：预期零改动注记） | ## 7. 任务卡 @@ -95,48 +106,56 @@ | `game/presentation/row_pacer.gd` | 零改动（flush :49 现成被消费） | — | | `game/core/board_generator.gd` | p5 handler 注入面（复用既有·修改） | 非行为（缺省零变化）→ wr5 | | `game/core/reward_economy.gd` | p5 同上（复用既有·修改） | 非行为 → wr5 | -| `game/core/battle_orchestrator.gd` | p5 组装接线两行（:278/:283 后各一行）（复用既有·修改） | 非行为（接线）→ wr5 | -| `game/core/rng_service.gd` | p6 handler＋return（复用既有·修改） | 非行为（缺省零变化）→ wr6 | -| `game/tests/unit/battle_settlement/round_flow_skill_pool_test.gd` | wr5 断言（封印传导）（复用既有·增断言） | 断言面 | -| `game/tests/unit/core/`（rng 现役套件，T0 定名） | wr6 断言（违约回调＋返回 null）（复用既有·增断言） | 断言面 | +| `game/core/battle_orchestrator.gd` | p5 组装接线两行（:285/:290 后各一行）（复用既有·修改） | 非行为（接线）→ wr5 | +| `game/core/rng_service.gd` | p6 handler＋return（未知标签分支）＋p7 同款（未播种分支）（复用既有·修改） | 非行为（缺省零变化）→ wr6/wr7 | +| `game/tests/unit/core/run_time_fatal_test.gd` | **新增负面套件**（wr5＋wr6＋wr7 三测试点；名系提案，终名属白名单 2 代拍板范围）（新增文件） | 断言面（退出码判据） | +| `game/tests/run_all.gd` | manifest 登记一行 `expect=1, negative=true`（:73 先例同款） | 闸登记面 | +| `game/tests/unit/battle_settlement/round_flow_skill_pool_test.gd` | **零改动**（v1.2 曾把 wr5 写进本件，v1.3 迁出——现役非负面套件禁承载违约取证） | — | -（零新增文件、零新增函数——p5/p6 是成员变量＋分支段。） +（新增一处＝运行期违约通道负面套件＋manifest 登记一行；其余为既有件内成员/分支/行级改动，p5/p6/p7 是成员变量＋分支段。） ### 接口块 - **p5 形态**（两件同款）：`var fatal_handler: Callable = Callable()`（成员声明，注释「违约中止通道——缺省退化 push_error+assert；组装层注入 orchestrator._fatal 经封印真中止」）；`_fatal` 体内 assert 前 `if fatal_handler.is_valid(): fatal_handler.call(msg)`。 -- **p5 接线**：orchestrator 组装点 `:278` 后 `_board_generator.fatal_handler = _fatal`、`:283` 后 `_reward_economy.fatal_handler = _fatal`。 +- **p5 接线**：orchestrator 组装点 `:285`（`_board_generator = BoardGenerator.new()`）后 `_board_generator.fatal_handler = _fatal`、`:290`（`_reward_economy = RewardEconomy.new(db, rng)`）后 `_reward_economy.fatal_handler = _fatal`（行号＝v1.3 按迭代 38 合回后 master 重锚；orchestrator 自身 `_fatal` 现址 :1304）。 - **p6 形态**：`var violation_handler: Callable = Callable()`；未知标签分支＝push_error ＋ `if violation_handler.is_valid(): violation_handler.call(purpose)` ＋ `assert(false, …)`（handler 有效时调用在 assert 前——debug 注入测试面可断言）＋ `return null`。 -- **wr5 断言**（round_flow_skill_pool_test 增，V6 装配形态同卡 A）：构造 orchestrator → 直调 `_board_generator._fatal("测试违约")` → 断言 `oc.battle_result == "fatal_error"`（封印传导成立）；缺省形态断言（新构造件不接线 → 直调 → battle_result 不受影响——契约 2）。 -- **wr6 断言**（rng 现役套件增，T0 定名——rng_service 现役单测所在套件）：注入 `violation_handler`（记录型 Callable）→ `open_stream("bogus_purpose")` → 断言 handler 被调（记录位真）且返回值为 null。 +- **p7 形态**（v1.3 新增）：`_master_seed < 0` 分支同款——push_error ＋ 复用 p6 的 `violation_handler`（有效则调用，传 purpose 标签）＋ `assert(false, …)` ＋ `return null`；缺省（不注入）时行为逐字等于现状（契约 2 同样约束 p7）。分支次序事实：未知标签检查（:101-103）在播种检查（:104-106）之前，故 p7 通道只能用**在册合法标签**触达。 +- **wr5／wr6／wr7 三点**：全部落**一个新增负面套件** `game/tests/unit/core/run_time_fatal_test.gd`（extends SceneTree，退出码判据：全绿尾行 `quit(1)`、回归态 `quit(2)`——`extended_row_violation_test` 同款形态），manifest 登记 `{"path": …, "expect": 1, "negative": true}`。 + - **载体三纪律**（v1.3 复核轮钉死，违此即 L3 停呈）：① **注入只经编排器组装点**（:285/:290 两行接线），**禁在测试体内手工 `bg.fatal_handler = oc._fatal`**——手工接线会让撤销证明②（回退组装点）空转；② 三测试点**各用新建 `RngServiceCore` 实例**，禁跨点复用、禁跑过取号后再播种（`set_master_seed` 自带 `assert(_counter == 0)`，:60——复用实例必炸在播种步）；③ **回归态判据只能取「改前改后真有差异」的可观测面**——可差异的面只有两处：handler **成员与调用点是否存在**（记录位真假）与**封印是否落**。`return` 位与计数器读数在 debug 下不可判别：assert 已先中断 `open_stream` 本体，「装了 return」与「删掉 return」两态同样到不了 `:107-108` 的推计数段、同样表现为「拿不到可用 RNG」——**拿这两面当撤销证明＝必假绿**；故 p6/p7 的 `return` 位按 wr3 同款「静态判据＋代码评审注记（＋grep 该分支 return 行在位）」承接，**禁写「违约行照发号／未播种照取号」式运行期判据**（照实装必触发 §9 L3 再停卡）。 + - ① wr5 封印传导（p5）：装配构造真实编排器（V6 形态，`round_flow_skill_pool_test` 现成装配链可照抄）→ 违约经**组装点注入的** handler 传导 → 直调 `_board_generator._fatal("测试违约")` → 验 `oc.battle_result == "fatal_error"`（`_fatal` :1304 先落封印再 assert）；**回归态**＝组装点接线被移除 → 协作件违约不落封印 → `quit(2)`。 + - ② wr6 未知标签违约通道（p6）：新建实例 → 注入记录型 `violation_handler` → `open_stream("bogus_purpose")`（出词表）→ 验 handler **记录位为真**（判据主体）＋拿不到可用 RNG；**对照**＝新实例播种后取在册合法标签（`board_gen`）返回可用 RNG 且 `counter()` +1；**回归态判据**＝handler 成员与调用点不存在（未实装 p6 形态）时注入无处可注 → 记录位守不住 → `quit(2)`；`return` 位本体不可观测，走 grep 在位＋评审注记。 + - ③ wr7 未播种取数通道（p7）：新建实例**不播种**（`_master_seed` 缺省 -1，:23）→ 注入 handler → `open_stream("board_gen")`——**必须用在册合法标签**：`PURPOSE_TAGS`（:9）不含 `adventure`，且未知标签检查排在播种检查之前，出错标签会让本点退化成测试点②（撤销证明④空转）；验 handler **记录位为真**＋拿不到可用 RNG；**对照**＝同标签播种后照常取号；**回归态判据**＝该分支 handler 调用点缺失 → 记录位守不住 → `quit(2)`；`return` 位同走静态面。 + - **缺省形态断言**（契约 2）：新构造件不接线 → 直调 `_fatal` → `battle_result` 不受影响；不注入 handler 的 rng 件在合法标签与已播种路径逐位不变（本段在**违约注入之前**跑完，验完再触发违约——否则 SCRIPT ERROR 混入正向判定）。 - **wr2 回归**：save_select/confirm 流现役探针（ui_click_probe 选档删除确认段——T0 定位）直跑绿＋锁域断言（confirm 开时输入锁生效——若现役断言未覆盖则增一条）。 -- **取用**：无。**最窄闸**：round_flow_skill_pool_test＋rng 套件＋ui_click_probe 直跑；全套闸按本批改动域选档。 +- **取用**：无。**最窄闸**：新负面套件直跑（期望退出码 1）＋`run_all.gd` 登记行核在位＋pacing/round_flow 现役套件直跑绿＋ui_click_probe 直跑；全套闸按本批改动域选档。 ### 落位与可复用性预检 -- **零新增件**：全部为既有件内成员/分支/行级改动；flush/pending_rows 复用 row_pacer 现成公开面。 -- **复用面**：p5 复用 orchestrator 既有 `_fatal` 封印（不造第二中止机制——审计「可经宿主注入」的最小实现）；p4 复用 flush()；p2 复用 ModalFlow 单口既有编排。 -- **唯一面**：违约通道各件唯一（fatal_handler/violation_handler 各一处、组装接线单点）；confirm 开合收口后单口唯一。 +- **新增件一处**：`game/tests/unit/core/run_time_fatal_test.gd`（运行期违约通道负面套件）——**为什么必须新增**＝违约取证必产不可捕获的 SCRIPT ERROR 行，现役非负面套件被闸 02 扫描覆盖，落位无处可复用（req-card 第 13 条落位预检的答题；闸侧 `negative=true` 豁免机制与 `extended_row_violation_test` 形态照抄，闸件本身零改动）。其余全部为既有件内成员/分支/行级改动；flush/pending_rows 复用 row_pacer 现成公开面。 +- **复用面**：p5 复用 orchestrator 既有 `_fatal` 封印（不造第二中止机制——审计「可经宿主注入」的最小实现）；p4 复用 flush()；p2 复用 ModalFlow 单口既有编排；p7 复用 p6 的 `violation_handler` 成员（不新开第二回调面）；负面套件复用 run_all 的 `negative` 豁免通道。 +- **唯一面**：违约通道各件唯一（`fatal_handler` 两件各一处；`violation_handler` rng_service 单件一处、覆盖未知标签与未播种两条分支；组装接线单点）；confirm 开合收口后单口唯一。 - **分层**：core 件零 UI 依赖不破（Callable 注入非 UI 引用；组装接线在 core 内层间）；presentation 收口经既有 ModalFlow。 ### T0 事实坐实（≈0.1d） -- [ ] 复核 S1–S6（重点：S2 ModalFlow.open 与 confirm_dialog.open 先后序、wr6 落点套件名、wr2 探针段定位）；确认 rng 套件与 pacing 回归面。可核查结果：定位清单进实现报告素材。 +- [ ] 复核 S1–S7（重点：S2 ModalFlow.open 与 confirm_dialog.open 先后序、S6/S7 两分支现行行号、wr2 探针段定位）；确认 pacing 回归面与 `round_flow_skill_pool_test` 装配链（wr5 ① 照抄用）。可核查结果：定位清单进实现报告素材。 -### T1 定点修五件＋断言（≈0.5d） +### T1 定点修六件＋负面套件（≈0.5d） - [ ] 实装 p1/p3/p4（删句/防护/flush）＋wr4 带夹具断言。可核查结果：grep 死变量与重复组零命中（:123-124 保留段除外）；pacing_queue_test 直跑绿；wr4 断言绿。 -- [ ] 实装 p5/p6（handler 面＋接线＋return）。可核查结果：wr5/wr6 断言绿；缺省形态断言绿（契约 2）。 +- [ ] 实装 p5/p6/p7（handler 面＋接线＋两分支 return）。可核查结果：缺省形态断言绿（契约 2）；负面套件三测试点尚未建时先直跑 rng/board_generator 相关现役套件确认合法路径零红。 +- [ ] 建负面套件 `run_time_fatal_test.gd` 三测试点＋`run_all.gd` manifest 登记一行（`expect=1, negative=true`）＋**新件的 `.gd.uid` 边车随批入库**（`.gitignore:6`「.uid 必须提交」——迭代 38 卡④ 曾漏带边车留未跟踪态）。可核查结果：本件直跑退出码恰 1；闸 02 对本件不判红（负面豁免生效）；登记行与 `:73` 先例形态逐字段一致；`git status` 无残留 `?? *.uid`。 - [ ] 实装 p2（confirm 三处收口＋注释）。可核查结果：wr2 回归绿；grep `confirm_dialog.open(`/`.close()` 直调仅剩方法定义与收口内调用。 - [ ] 验证步骤：全套闸按域选档跑一次全绿。 ### T2 撤销证明＋产出物落位卡（≈0.15d，末卡） -- [ ] 撤销证明三条：①回退 p1 hunk（死变量还原）→ grep battle_live 命中即红（或静态扫描面）；②回退 p5 接线两行 → wr5 封印传导断言红（battle_result 不变）→ 还原复绿；③回退 p6 hunk（return 与 handler 还原）→ wr6 断言红（返回非 null）→ 还原复绿。记录进实现报告。 -- [ ] 写齐三份产出物（实现报告〔五件逐件核对表＋wr 断言读数＋实机目检总清单——选档删除确认流目检一项（p2 锁域归位后行为目检）〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）。 +- [ ] 撤销证明四条：①回退 p1 hunk（死变量还原）→ grep `battle_live` 命中即红；②回退 p5 组装点接线两行 → 协作件违约不落封印 → 本件退出码 0 ≠ expect 1（wr5 测试点① `quit(2)`）→ 还原复绿；③回退 p6 hunk（handler 成员与调用点整体不存在→注入无处落）→ wr6 记录位守不住 → 退出码非 1 → 还原复绿；④回退 p7 hunk（同上，针对未播种分支调用点）→ wr7 记录位守不住 → 退出码非 1 → 还原复绿。**三条负面套件套一律以退出码为判据，禁写「断言变红」式口径**（assert 不改进程退出码，红只落在 `quit(2)`）；p6/p7 的 `return` 位不作运行期判据（debug 下两态不可判别，见契约 6），以「grep 该分支 return 行在位＋代码评审注记」出证并在实现报告如实标注观测面局限。记录进实现报告。 +- [ ] 清单同步：`python tools/extract_checks.py --extract --force` 重生成 `game/tests/验证集清单.md`（清单已存在时无 `--force` 拒写并返 2），再 `--diff` 对账零差异。**预期零新增行**：提取器只认 `check(` 形态，负面套件以 `quit()` 承载、`extended_row_violation_test` 在册先例即零 check 行；新件仍会进清单头部的源文件列表——该变化不算断言新增，禁为凑行去补 `Kit.check`。 +- [ ] 写齐三份产出物（实现报告〔六件逐件核对表＋wr 断言读数＋实机目检总清单——选档删除确认流目检一项（p2 锁域归位后行为目检）〕／代拍板追认单／反哺点清单〔§6 逐条落点〕）。 - [ ] 合并前置：独立验收审计（§8.3）逐行「通过」。 -**估时合计 ≈0.75d**。编排注记：五件皆小而独立——与件②卡（levelmap）、卡 A 同迭代分波无冲突；p2 有锁域行为面（wr2 回归是合并前置）。 +**估时合计 ≈0.85d**（v1.3 停卡修订随增 ≈0.1d＝负面套件新件＋manifest 登记＋清单对账；p7 并修增量落在同一 handler 形态内，随增 0）。编排注记：六件皆小而独立——与卡 A 同迭代分波无冲突；p2 有锁域行为面（wr2 回归是合并前置）；**v1.3 起验收载体已定死为负面套件，编排段与实现段禁再把 wr5/wr6/wr7 挪回现役套件**。 ## 8. 验证闸 @@ -145,42 +164,49 @@ | 需求点 | 改动（文件:行/行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 撤销证明 | |---|---|---|---|---|---| | wr1 死代码与重复句清除（p1） | main_overlay_flow.gd:111＋:117-122 | grep 判据零命中（:123-124 保留段除外）〔wr1〕＋现役角标同步探针绿 | 静态＋探针 | grep 真实跑批＋ui 探针 | 回退 p1 hunk → grep 命中即红（T2①） | -| wr2 confirm 收口锁域归位（p2） | main_overlay_flow.gd:88＋main.gd:312/321 | save_select/confirm 回归探针段〔wr2〕＋锁域断言 | 探针 | 选档删除确认真实流（探针驱动） | 回退 p2 hunk → 收口判据 grep 命中即红＋锁域断言红 | -| wr3 入口 null 防护（p3） | main.gd:722/749 前置防护 | 防护分支单测/静态判据〔wr3〕（防护态构造经探针锁谓词异常态不可达——静态面+代码评审注记申报） | 静态 | — | 回退 p3 hunk → grep 防护行零命中红 | +| wr2 confirm 收口锁域归位（p2） | main_overlay_flow.gd:88＋main.gd:311/320 | save_select/confirm 回归探针段〔wr2〕＋锁域断言 | 探针 | 选档删除确认真实流（探针驱动） | 回退 p2 hunk → 收口判据 grep 命中即红＋锁域断言红 | +| wr3 入口 null 防护（p3） | main.gd:721/748 前置防护 | 防护分支单测/静态判据〔wr3〕（防护态构造经探针锁谓词异常态不可达——静态面+代码评审注记申报） | 静态 | — | 回退 p3 hunk → grep 防护行零命中红 | | wr4 会话 flush（p4） | main.gd:175 一行 | pacing_queue_test＋会话更替断言〔wr4〕（新增：**前置夹具入队若干行再调 begin_session**，断言其后 pending_rows()==0——无夹具则改前改后皆绿钉不住〔grilling 订正〕） | 单元 | _begin_session 真实调用路径＋enqueue 真实入队面 | 回退 p4 hunk → 带夹具断言红（残留非零） | -| wr5 fatal 封印传导（p5） | 两件 handler＋orchestrator 接线 | wr5 断言两条（传导＋缺省）〔wr5〕 | 单元 | V6 装配构造真实编排器路径 | 回退接线 → 传导断言红（T2②） | -| wr6 违约回调与 return（p6） | rng_service handler＋return | wr6 断言〔wr6〕（handler 被调＋返回 null） | 单元 | open_stream 真实调用路径 | 回退 p6 hunk → 返回值断言红（T2③） | -| wr7 产出物 | T2 三份 | 件核〔wr7〕 | — | — | 缺项红 | +| wr5 fatal 封印传导（p5） | 两件 handler＋orchestrator 组装点接线（:285/:290） | 负面套件测试点①（含缺省形态断言；注入只经组装点，禁测试内手工接线）〔wr5〕 | 单元（负面） | V6 装配构造真实编排器路径 | 回退接线两行 → 本件退出码 0 ≠ expect 1（T2②） | +| wr6 未知标签违约通道（p6） | rng_service 未知标签分支 handler＋return | 负面套件测试点②（handler 记录位为判据主体＋拿不到可用 RNG＋在册标签对照）〔wr6〕 | 单元（负面） | open_stream 真实调用路径 | 回退 p6 hunk（成员与调用点整体消失→注入无处落）→ 记录位守不住 → 退出码非 1（T2③）；`return` 位＝grep 在位＋评审注记（debug 下两态不可判别，禁当运行期判据） | +| wr7 未播种取数通道（p7） | rng_service 未播种分支 handler＋return | 负面套件测试点③（在册合法标签＋不播种实例；handler 记录位＋拿不到可用 RNG＋播种对照）〔wr7〕 | 单元（负面） | 未播种的 open_stream 真实路径 | 回退 p7 hunk（该分支调用点缺失）→ 记录位守不住 → 退出码非 1（T2④）；`return` 位同走静态面 | +| wr8 负面载体登记 | 新件＋`run_all.gd` manifest 一行 | 登记行在位判据〔wr8〕（`expect=1` 与 `negative=true` 两字段齐备，静态 grep＋评审注记——全仓无闸对账盘上测试文件与 manifest，禁写「删登记行即红」的不存在判据）＋闸 02 对本件不判红＋验证集清单 --diff 零差异 | 闸登记 | run_all 真实批跑路径 | 删 `negative=true` 标记而保留登记行 → 本件输出被闸 02 捕获判 FAIL | +| wr9 产出物 | T2 三份 | 件核〔wr9〕 | — | — | 缺项红 | ### 8.2 测试削弱申报 -零（既有断言零改动；新增断言四条；wr3 防护分支不可达性以静态判据＋申报承载——不虚构不可达态的运行期断言）。 +零（既有断言零改动；新增断言四条＝wr4 夹具断言＋wr2 锁域断言（若现役未覆盖）＋负面套件内两处缺省形态断言，其中违约三点以退出码承载、非 `Kit.check` 形态；wr5/wr6/wr7 由现役套件迁至独立文件属**载体迁移**，被迁走的断言在 v1.2 从未合回 master，不存在削弱既有验证面；wr3 防护分支不可达性以静态判据＋申报承载——不虚构不可达态的运行期断言）。 ### 8.3 独立验收审计 -入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`；抽查重点＝契约 1/2（合法路径逐位不变——缺省形态断言在案）、p2 锁域回归读数、p5 接线单点、p6 return 位置（assert 语义保持）。未过不得合并。 +入口＝未参与实现的会话或子代理；报告落 `reports/iter-验收审计-<日期>.md`（多卡同批须带卡号位防撞名）；抽查重点＝契约 1/2（合法路径逐位不变——缺省形态断言在案）、p2 锁域回归读数、p5 接线单点、p6/p7 两分支 return 位置（assert 语义保持）、**契约 6 与载体三纪律四判据**＝① manifest 的 `negative=true`＋`expect=1` 在册；② 三测试点回归态判据真能变红且**只取有差异面**（变异注入实测：抹掉 handler 成员与调用点/拆掉组装接线 → 退出码非 1；若审计发现判据落在 `return` 位或计数器这类 debug 下两态不可辨的面＝阻断，防假绿）；③ 注入面只在编排器组装点（`grep fatal_handler` 在测试文件内零命中——防撤销证明②空转）；④ 三测试点各用新建实例（复用实例会撞 `assert(_counter == 0)`，撞即证纪律失效）。未过不得合并。 ## 9. 异常分级 -- **L1（自救）**：p2 收口先后序形态；p5/p6 注释措辞；断言挂点。 -- **L2（记录继续）**：行号漂移；wr6 落点套件名变化。 -- **L3（停机呈报）**：ModalFlow.open 与 confirm_dialog.open 语义冲突（双显示/挂起兜底破坏确认流——收口形态失配停呈）；p4 flush 引入排播节奏变化（契约 4 破）；p5 接线后协作件违约不落封印（传导断链）；发现第三处 `_fatal` 同型软回退（审计清单外）；p6 同函数 master_seed<0 分支（:104-106）同款 assert 后无 return——grilling 点名属同病根第二处：**单通道停卡呈报**（不并修——扩点违契约 1 改动面封闭与实现段零裁断；呈报后由用户裁另立或并批）。 +- **L1（自救）**：p2 收口先后序形态；p5/p6/p7 注释措辞；断言挂点与负面套件事件命名（在 `*_violation_test`／`*_fatal_test` 既有约定内）。 +- **L2（记录继续）**：行号漂移；manifest 登记行的注释尾缀现位变化。 +- **L3（停机呈报）**：ModalFlow.open 与 confirm_dialog.open 语义冲突（双显示/挂起兜底破坏确认流——收口形态失配停呈）；p4 flush 引入排播节奏变化（契约 4 破）；p5 接线后协作件违约不落封印（传导断链）；发现第三处 `_fatal` 同型软回退（审计清单外）；负面套件三测试点的回归态判据不变红（抹掉 handler 成员与调用点、或拆掉组装接线后本件仍出 1——说明判据取到了 debug 下两态不可辨的面，停呈禁改落位自救）；出现测试体内手工接线（违载体纪律①，撤销证明②会空转）；跨测试点复用同一 rng 实例致播种撞 `assert(_counter == 0)`（违纪律②——改正方向是每点新建实例，禁动播种断言）。 + - v1.2 曾列的「p6 同函数 master_seed<0 分支（:104-106）单通道停卡呈报」条款**已由用户裁并修，随 v1.3 出账**（转 §1 p7＋wr7）；同型第四处仍走本条停呈通道。 ## 10. 代拍板白名单（超清单必呈报） -1. p5/p6 成员命名与注释措辞。 -2. wr 断言挂点与消息文本。 +1. p5/p6/p7 成员命名与注释措辞（p7 复用 p6 的 `violation_handler`，禁另开第二成员）。 +2. wr 断言挂点与消息文本、负面套件文件名终名（提案名 `run_time_fatal_test.gd`，须落 `*_violation_test`／`*_fatal_test` 既有约定内）。 3. p2 收口的先后序实现形态（ModalFlow.open 语义 T0 核后定形）。 4. 提交切分与 worktree 分支命名。 ## 11. 待裁点 -**零待裁点，开工门=U0。** 灰色推导两处（呈报可否决，随 T2 反哺点）：①p5 走「组装层传导 orchestrator 封印」而非回调穿透到 presentation——依据＝core 件零 UI 依赖红线＋复用既有封印零新中止机制；②wr3 防护分支验收用静态判据不造运行期断言——依据＝分支在锁谓词正常态不可达，虚构异常态夹具违背「真实入口」口径。 +**零待裁点，开工门=U0。** 灰色推导四处（呈报可否决，随 T2 反哺点）：①p5 走「组装层传导 orchestrator 封印」而非回调穿透到 presentation——依据＝core 件零 UI 依赖红线＋复用既有封印零新中止机制；②wr3 防护分支验收用静态判据不造运行期断言——依据＝分支在锁谓词正常态不可达，虚构异常态夹具违背「真实入口」口径；③wr5/wr6/wr7 载体取独立负面套件而非改造闸 02 扫描规则——依据＝闸豁免机制本为此设且已在册三件先例，改扫描规则属动闸件（工程改动面）且会削弱「断言不终止进程」的防假绿能力（test-conventions §5 三硬闸的存在理由）；④p7 并修而非另立——依据＝用户 2026-10-26 裁（实现报告 §三建议案），且 p7 与 p6 同函数同形态、复用同一 handler 成员，改动面仍封闭在 §1 所列行内（违不违契约 1 的答案＝不违，因契约 1 的名单随 v1.3 扩到 p7）。 ## 12. 自审六查与复核记录 -**自审六查（2026-10-26 写卡会话）**：①规格覆盖——p1–p6→T1/wr1–wr6、撤销/产出物→T2/wr7；②步骤扫描——T1 三步各挂可核查结果；③类型一致性——接口块形态与 S1–S6 实查一致；④审查焦点——缺省零变化（契约 2＋缺省断言）、锁域回归（wr2）、封印传导链（契约 3）、排播节奏护栏（契约 4）；⑤篇幅比例——零实现体；⑥落位预检——零新增件、复用面（flush/ModalFlow/封印）已答。 +**自审六查（v1.3 复核轮，2026-10-26）**：①规格覆盖——p1–p7→T1、wr1–wr9→§8.1 逐行有承接（wr7 承 p7、wr8 承登记面、wr9 承产出物）、撤销证明四条与清单同步→T2；②步骤扫描——T0 一步＋T1 四步＋T2 四步各挂可核查结果；③类型一致性——接口块三测试点与 S5/S6/S7 实查一致，退出码判据与 `run_all.gd` 的 `expect`/`negative` 字段类型一致，wr7 所用标签在册（`PURPOSE_TAGS` 无 `adventure`，取 `board_gen`）；④审查焦点——缺省零变化（契约 2 覆盖 p5/p6/p7）、锁域回归（wr2）、封印传导链（契约 3）、排播节奏护栏（契约 4）、**违约取证落位与闸 02 互斥＋回归态判据只取可观测面（契约 6 与载体三纪律——本轮主判点）**；⑤篇幅比例——零实现体；⑥落位预检——新增一处（负面套件）已答「为什么不能复用」，复用面（flush/ModalFlow/封印/negative 豁免通道）齐备。 **grilling 一轮复核记录（2026-10-26，独立子代理对抗复核，判「通过（附四应修＋一建议）」）**：①wr4 撤销证明不可执行（无夹具时改前改后皆绿）——v1.1 折入前置夹具断言；②p1 删除边界误圈（:123 调试角标注释非重复组；首组实为 :112-116、重复组 :119-122）——订正；③S5 board_generator _fatal 实址 :396-398——订正；④缺 req-card 第 13 条——立契约 5；⑤建议＝p6 同函数 master_seed<0 分支（:104-106）同款 assert 后无 return——L3 点名（二轮收紧为单通道停卡呈报）。复核确认项：S2-S4 行号逐条命中、wr3 静态判据申报诚实、p5 载体成立（round_flow_skill_pool_test 现有装配形态）、handler-before-assert 排序与 headless 实测语义相容。 **二轮闭合复检（2026-10-26，判「通过（附三应修））**：四应修核闭合（wr4 夹具/p1 边界/S5 实址/契约 5）；残留三处随本轮一并处理——wr1 行与 S5 出处列的旧行号订正、master_seed 条款由「并修或停卡」收紧为单通道「停卡呈报」（并修路线违契约 1 与实现段零裁断）。 + +**迭代 38 实现段停卡呈报（2026-10-26，非复核件·上游缺陷移交）**：p1–p6 实装完成后，wr5/wr6 落位核查发现 v1.2 处方不成立——headless 下 `assert` 失败必产 `SCRIPT ERROR`、不可捕获且只中断当前函数，而 `run_all.gd` 对非负面套件的判定是「输出含该标记即 FAIL」（闸 02，test-conventions §5 三硬闸之二），故「wr5/wr6 绿＋全套闸全绿」在同一跑次内互斥。改动全数还原、零提交（WIP 补丁 172 行留 `C:/Users/DK/AppData/Local/Temp/iter38_card2_wip.patch`；重启按合回后 master 重核行号重做，禁直接 apply）。同款缺陷卡④ 在 grilling 一轮已撞见并以独立负面套件承载（`extended_row_violation_test`，manifest `expect=1, negative=true`）——卡② 两轮复核未复现该判点，因直跑单套件不经过闸 02 扫描，只有批末全量闸才暴露。 + +**v1.3 裁定与判据（2026-10-26，用户裁「把需求变更给修正确」）**：①违约取证（wr5/wr6/wr7）只落**一个新增负面套件**＋manifest 显式登记 `expect=1, negative=true`，现役非负面套件零改动；②`master_seed < 0` 分支经用户裁并修，立为 p7＋wr7；③p7 触达前提是播种检查排在未知标签检查之后，故测试点③必须在册合法标签；④回归态判据只取 debug 可观测面，release 独有位走静态判据＋评审注记；⑤载体三纪律（组装点注入／每点新建实例／禁手工接线）与撤销证明四条（①grep 面，②③④退出码面）为完成定义；⑥估时 ≈0.85d；⑦闸 09 现为迭代 38 特批存量红，本批开工前须由用户裁「还债或刷新基线」，禁以「闸 09 绿」为完成条件；⑧件②独立卡已随迭代 38 卡① 合回退役，来源指址改 git 提交号；⑨条目归属随「gdstyle 存量债全量清偿」波 7。 diff --git a/roadmap.md b/roadmap.md index a37858b6..ecd6f58a 100644 --- a/roadmap.md +++ b/roadmap.md @@ -6,7 +6,7 @@ - **阶段**：M3——Alpha 版本的完整实现（2026-10-09 立规：未明令宣布完成前停留 M3，迭代只排 M3 需求，M4 不排期；根目录 stage.txt 为旧阶段开关仅存档）。 - **迭代位**：迭代 1–38 全部已完成——迭代 38 六卡 2026-10-26 合回并完成批后收尾。 -- **下一步**：迭代 39 已编三卡（2026-10-26 编入，≈10.15 个工作日——P0「AdventureRunner 职责真拆分」主副卡，副卡硬前置主卡＋技能池情境条件触发器卡排末位），待开工，实现段由用户以 /iter 39 发令。迭代 38 卡②（结构小件定点修批）停卡退回上游，验收载体处方随「gdstyle 存量债全量清偿」条目波 7 重裁。待编池：营地交互重做卡⑤（排卡④之后）、卡④（已退回美术设计段，美术设计闭合后重立卡）、冒险前资源配比预设（冻结备选）、迭代 30 原卡②③（2026-10-17 已剔出迭代 30 规划、退回待设计，待美术／设计定稿后重新立卡）。 +- **下一步**：迭代 39 已编三卡（2026-10-26 编入，≈10.15 个工作日——P0「AdventureRunner 职责真拆分」主副卡，副卡硬前置主卡＋技能池情境条件触发器卡排末位），待开工，实现段由用户以 /iter 39 发令。迭代 38 卡②（结构小件定点修批）已随用户裁出上游修订定稿 v1.3（验收载体改独立负面套件＋并修未播种分支），挂在「gdstyle 存量债全量清偿」条目波 7 待编排。待编池：营地交互重做卡⑤（排卡④之后）、卡④（已退回美术设计段，美术设计闭合后重立卡）、冒险前资源配比预设（冻结备选）、迭代 30 原卡②③（2026-10-17 已剔出迭代 30 规划、退回待设计，待美术／设计定稿后重新立卡）。 ## 里程碑时间线 @@ -73,8 +73,10 @@ | 迭代 37 | 已完成（2026-10-25） | 已退役（git 历史可考） | 2026-10-25 | ≈8.25 个工作日 | 已退役（git 历史可考） | | 迭代 38 | 已完成（2026-10-26） | 已退役（git 历史可考） | 2026-10-26 | ≈5.225 个工作日 | 已退役（git 历史可考） | | 迭代 39 | 待开工 | reports/需求卡片-冒险域拆件与账本实体化批-2026-10-26.md
reports/需求卡片-同调配装充能域封装批-2026-10-26.md
reports/需求卡片-技能池情境条件触发器批-2026-10-26.md | 2026-10-26 | ≈10.15 个工作日〔用户特批 2026-10-26 超 10 个工作日〕 | — | +| 迭代 40 | 待开工 | reports/需求卡片-B1战斗域拆件批-2026-10-27.md
reports/需求卡片-结构小件定点修批-2026-10-26.md | 2026-10-27 | ≈6.225 个工作日 | — | +| 迭代 41 | 待开工 | reports/需求卡片-核心数据面结构收敛批-2026-10-27.md
reports/需求卡片-呈现层结构收敛批-2026-10-27.md | 2026-10-27 | ≈13.15 个工作日〔用户特批 2026-10-27 超 10 个工作日〕 | — | -- 迭代 38 收口为带红合并〔用户特批 2026-10-26〕：09 静态扫描 S13 gdstyle 恶化 2 条经批准记入基线存量红（git 提交 c4c69701），卡② 停卡退上游待「gdstyle 存量债全量清偿」条目波 7 重裁。 +- 迭代 38 收口为带红合并〔用户特批 2026-10-26〕：09 静态扫描 S13 gdstyle 恶化 2 条经批准记入基线存量红（git 提交 c4c69701），卡② 停卡退上游，处方已于 2026-10-26 修订定稿 v1.3（git 提交 b3ea7532），随「gdstyle 存量债全量清偿」条目波 7 待编排。 - 历史行的「—」= 该列事实不可考：迭代 1~8 早于需求卡片制；编排时点与预计周期不再回溯，细节查 git 提交史。 - 「已退役（git 历史可考）」= 需求卡片或实现报告曾存在，已按「证据只留最新」退役；已完成迭代的实现报告列只填 reports/ 现存路径或本保留字，不填「—」。 - 新迭代行的编排与各列判据见 doc-conventions §12.2 与 iter-plan 技能，由流水线闸（`tools/pipeline_gate.py`）机检。 diff --git a/tools/analyze_playtest.py b/tools/analyze_playtest.py index 94752ed0..524c8e47 100644 --- a/tools/analyze_playtest.py +++ b/tools/analyze_playtest.py @@ -30,6 +30,9 @@ import glob import json import os import sys +from pathlib import Path + +from godot_user_dir import resolve_user_dir # ---- 表值区（溯源见文件头） ---- POOL_CLAMP = (-100, 100) @@ -613,8 +616,7 @@ def print_report(label, per_battle, t, exact_mode): def main(): - log_dir = os.path.join(os.environ.get("APPDATA", ""), "Godot", "app_userdata", - "DungeonSweeperVerticalSlice", "logs") + log_dir = str(resolve_user_dir(Path(__file__).resolve().parent.parent) / "logs") path = None args = sys.argv[1:] if args and not args[0].startswith("-"): diff --git a/tools/gdstyle_baseline.txt b/tools/gdstyle_baseline.txt index 512e5f4e..0a4cda6e 100644 --- a/tools/gdstyle_baseline.txt +++ b/tools/gdstyle_baseline.txt @@ -3,19 +3,13 @@ # （class variables／public methods／file length）＝文件|规则；无数字条目＝文件|规则|消息全文（裸键）。 # 带数条目行格式「键 = 数值」，数值＝消息剥掉 (max N) 段后首个整数；无数字条目裸键。 # 判定＝键不在基线红（NEW）、同键数值较登记值恶化红（WORSENED）、改小/持平不红。 +# 阈值口径＝gdstyle 默认值（tools/gdstyle.toml 不设数值阈值）；本文件只是欠账簿，登记值只准随 +# 还债下降，禁抬高到现状（抬高＝把既有代码当尺子，默认恶化）。 # 重生成＝人工专用：python tools/gdstyle_gate.py --refresh（禁清基线换绿；改规则口径/工具升级须随批 -# 重生成；新键数较旧基线少逾 10% 须加 --force 显式确认）。 +# 重生成；新键数较旧基线少逾 10% 或登记值被抬高均拒写，须加 --force 显式确认）。 game/core/action_economy.gd|quality/max-class-variables = 18 game/core/adventure_runner.gd|quality/max-branches|_apply_curio_pick = 10 -game/core/adventure_runner.gd|quality/max-branches|_draw_curio_candidates = 11 -game/core/adventure_runner.gd|quality/max-branches|resume_adventure = 11 game/core/adventure_runner.gd|quality/max-class-variables = 42 -game/core/adventure_runner.gd|quality/max-file-length = 1051 -game/core/adventure_runner.gd|quality/max-function-length|_draw_curio_candidates = 85 -game/core/adventure_runner.gd|quality/max-function-length|_start_current_level = 53 -game/core/adventure_runner.gd|quality/max-function-length|resume_adventure = 108 -game/core/adventure_runner.gd|quality/max-local-variables|_draw_curio_candidates = 26 -game/core/adventure_runner.gd|quality/max-local-variables|resume_adventure = 13 game/core/adventure_runner.gd|quality/max-public-methods = 23 game/core/adventure_runner.gd|quality/max-returns|_apply_curio_pick = 9 game/core/battle_orchestrator.gd|quality/max-branches|begin_battle = 17 @@ -141,9 +135,6 @@ game/data/schemas/reward_table.gd|quality/max-function-length|validate = 99 game/data/schemas/reward_table.gd|quality/max-local-variables|validate = 20 game/data/schemas/settlement_table.gd|quality/max-branches|validate = 16 game/data/schemas/settlement_table.gd|quality/max-class-variables = 18 -game/data/schemas/shop_table.gd|quality/max-branches|validate = 22 -game/data/schemas/shop_table.gd|quality/max-function-length|validate = 84 -game/data/schemas/shop_table.gd|quality/max-local-variables|validate = 20 game/data/schemas/skill_table.gd|quality/max-branches|validate = 29 game/data/schemas/skill_table.gd|quality/max-function-length|validate = 80 game/data/schemas/status_effect_table.gd|quality/max-branches|validate = 12 @@ -162,8 +153,6 @@ game/presentation/hud_presenter.gd|quality/max-parameters|_refresh_out_of_battle game/presentation/hud_presenter.gd|quality/max-parameters|refresh = 8 game/presentation/hud_presenter.gd|quality/max-parameters|tune_sim_report = 10 game/presentation/main.gd|quality/max-class-variables = 49 -game/presentation/main.gd|quality/max-file-length = 1507 -game/presentation/main.gd|quality/max-function-length|_build_ui = 189 game/presentation/playtest_logger.gd|quality/no-debug-print|debug 'print()' call found game/presentation/treasure_interact_controller.gd|quality/max-local-variables|inventory_projection = 11 game/presentation/treasure_interact_controller.gd|quality/max-parameters|_init = 7 @@ -192,15 +181,10 @@ game/presentation/views/board_cell_unit.gd|quality/max-local-variables|_draw = 1 game/presentation/views/board_fx_view.gd|quality/allocation-in-loop|object allocation '.new()' inside a loop 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-branches|_wall_tile_for = 14 game/presentation/views/board_view.gd|quality/max-class-variables = 45 -game/presentation/views/board_view.gd|quality/max-file-length = 1220 game/presentation/views/board_view.gd|quality/max-function-length|_paint_cell = 139 -game/presentation/views/board_view.gd|quality/max-local-variables|_digit_ink_mode = 12 game/presentation/views/board_view.gd|quality/max-local-variables|_paint_cell = 22 game/presentation/views/board_view.gd|quality/max-public-methods = 27 -game/presentation/views/board_view.gd|quality/max-returns|_wall_center_tile = 7 -game/presentation/views/board_view.gd|quality/max-returns|_wall_tile_for = 15 game/presentation/views/board_zone_view.gd|quality/max-function-length|_init = 59 game/presentation/views/camp_overlay_view.gd|quality/allocation-in-loop|object allocation '.new()' inside a loop game/presentation/views/camp_overlay_view.gd|quality/max-class-variables = 19 diff --git a/tools/gdstyle_gate.py b/tools/gdstyle_gate.py index 70c4e922..b93d54cb 100644 --- a/tools/gdstyle_gate.py +++ b/tools/gdstyle_gate.py @@ -16,19 +16,25 @@ quality/*＋syntax/reserved-identifier，format/naming/order 全关）。扫描 带数条目行格式「键 = 数值」，数值＝消息剥掉 (max N) 段后首个整数；无数字条目裸键无数值。 判定：①键不在基线＝新违规（NEW）红；②键在基线且双方有数值、当前数值 > 基线登记值＝ 恶化（WORSENED）红——独立于差集，防稳定键吞掉 104→300 行式恶化；③其余绿（改小/持平不红）。 +逐条违规行带 FAIL 前缀——gate 09 的存量红指纹只取含 FAIL 的行，带前缀才能让「红项清单」 +（哪几条、恶化到多少）进指纹：否则存量红期间的任何新增/进一步恶化都算同款红被放行。 -基线重生成＝人工专用（--refresh，附新旧对账与骤降守卫），禁在闸内自动重生成（防清基线换绿）； -新键数较旧基线少逾 10% 时拒绝写入，须加 --force 显式确认（防扫面断裂静默缩基线换绿）， ---force 只在 refresh 路径有效。 +阈值口径＝gdstyle 默认值（tools/gdstyle.toml 不设数值阈值）；基线只是欠账簿，登记值只准因 +还债下降，禁抬高到现状（抬高＝把既有代码当尺子，默认恶化）。 + +基线重生成＝人工专用（--refresh，附新旧对账、骤降守卫与抬升守卫），禁在闸内自动重生成 +（防清基线换绿）；新键数较旧基线少逾 10% 拒绝写入（防扫面断裂静默缩基线换绿）；任一键登记 +值被抬高同样拒绝（防以现状为尺吞掉恶化）。两条守卫都须 --force 显式确认，--force 只在 +refresh 路径有效。 二进制：本机固定路径 D:/code/gdstyle/gdstyle.exe（不入库不入包），GDSTYLE_BIN 环境变量覆盖； 版本与钉定版不符即红——升级工具须重测语法兼容性并人工重生成基线。 退出码：0＝无基线外新违规且无恶化；1＝有新违规／有恶化／二进制缺失或版本不符／扫描面为空／ -输出不可解析／refresh 骤降拒写；2＝用法错。 +输出不可解析／refresh 骤降或抬升拒写；2＝用法错。 用法：python tools/gdstyle_gate.py # 闸判定 python tools/gdstyle_gate.py --refresh # 人工重生成基线（覆盖旧文件，附对账） - python tools/gdstyle_gate.py --refresh --force # 骤降守卫触发时显式确认写入 + python tools/gdstyle_gate.py --refresh --force # 骤降/抬升守卫触发时显式确认写入 """ import json import os @@ -171,6 +177,17 @@ def run_gate() -> int: if len(current) < len(old) * SHRINK_GUARD and not force: return fail("新键数 %d 较旧基线 %d 少逾 10%%——疑扫面断裂静默缩基线换绿，拒绝写入；" "确认缩基线正当（如删规则/缩扫描面）须加 --force 显式确认" % (len(current), len(old))) + raised = sorted( + (k, old[k], current[k]) for k in current + if k in old and old[k] is not None and current[k] is not None and current[k] > old[k] + ) + if raised and not force: + for k, was, now in raised[:MAX_REPORT]: + print(" FAIL 抬高 %s = %d（登记 %d）" % (k, now, was)) + if len(raised) > MAX_REPORT: + print(" ...（截断，共 %d 条）" % len(raised)) + return fail("重生成会抬高 %d 条登记值——基线只准因还债下降，抬高＝以现状为尺默认恶化；" + "确属阈值口径变更或经用户批准须加 --force 显式确认" % len(raised)) else: print("[gdstyle_gate] 旧基线不存在，跳过对账（首次落位）") write_baseline(current) @@ -191,15 +208,15 @@ def run_gate() -> int: red = False if new: for k in new[:MAX_REPORT]: - print(" NEW " + k) + print(" FAIL 新增 " + k) if len(new) > MAX_REPORT: - print(" ...（截断，共 %d 条）" % len(new)) + print(" FAIL ...（截断，共 %d 条）" % len(new)) red = True if worsened: for k in worsened[:MAX_REPORT]: - print(" WORSENED %s = %d（基线登记 %d）" % (k, current[k], base[k])) + print(" FAIL 恶化 %s = %d（基线登记 %d）" % (k, current[k], base[k])) if len(worsened) > MAX_REPORT: - print(" ...（截断，共 %d 条）" % len(worsened)) + print(" FAIL ...（截断，共 %d 条）" % len(worsened)) red = True if red: return fail("基线外新违规 %d 条／恶化 %d 条——新码须修到基线口径内，恶化须还债或经用户批准随批重生成基线" diff --git a/tools/godot_user_dir.py b/tools/godot_user_dir.py new file mode 100644 index 00000000..f2833788 --- /dev/null +++ b/tools/godot_user_dir.py @@ -0,0 +1,26 @@ +"""解析 Godot 的 user:// 根目录——与 game/override.cfg 的隔离口径同一份。 + +无 override.cfg（主工作区）→ %APPDATA%/Godot/app_userdata/； +有 override.cfg（代码面 worktree，由 tools/setup_worktree_userdir.sh 生成）→ %APPDATA%/。 +""" +import os +import re +from pathlib import Path + + +def _project_name(repo_root: Path) -> str: + text = (Path(repo_root) / "game" / "project.godot").read_text(encoding="utf-8", errors="replace") + m = re.search(r'^config/name="([^"]*)"', text, re.M) + return m.group(1) if m else "DungeonSweeperVerticalSlice" + + +def resolve_user_dir(repo_root: Path) -> Path: + base = Path(os.environ.get("APPDATA") or (Path.home() / "AppData" / "Roaming")) + override = Path(repo_root) / "game" / "override.cfg" + if override.is_file(): + text = override.read_text(encoding="utf-8", errors="replace") + custom = re.search(r'^config/use_custom_user_dir=true\s*$', text, re.M) + name = re.search(r'^config/custom_user_dir_name="([^"]*)"', text, re.M) + if custom and name and name.group(1): + return base / name.group(1) + return base / "Godot" / "app_userdata" / _project_name(Path(repo_root)) diff --git a/tools/parity_anchor.py b/tools/parity_anchor.py index 80948c61..122bf360 100644 --- a/tools/parity_anchor.py +++ b/tools/parity_anchor.py @@ -24,18 +24,19 @@ import argparse import hashlib import json -import os import re import subprocess import sys import time from pathlib import Path +from godot_user_dir import resolve_user_dir + ROOT = Path(__file__).resolve().parent.parent GODOT = r"D:\code\godot\Godot_v4.7.2-stable_win64_console.exe" GAME_DIR = ROOT / "game" ANCHOR_PATH = ROOT / "game" / "tests" / "evidence" / "parity" / "anchor.json" -USER_LOGS = Path(os.environ.get("APPDATA", "")) / "Godot" / "app_userdata" / "DungeonSweeperVerticalSlice" / "logs" +USER_LOGS = resolve_user_dir(ROOT) / "logs" # 变体表：名字 → (seed0, attune, shop)。（N=20/策略 both/route min/feat off 全变体钉死。） VARIANTS = { diff --git a/tools/pipeline_gate.py b/tools/pipeline_gate.py index d6ee448b..fe707606 100644 --- a/tools/pipeline_gate.py +++ b/tools/pipeline_gate.py @@ -148,7 +148,7 @@ def check_segment(word, line, issues, where): def check_status(raw, line, issues, where): - """判据 3＋状态段累积制（§12.1）＋特批/备选。返回 (状态词列表, 已编迭代号|None)。 + """判据 3＋状态段累积制（§12.1）＋特批/备选。返回 (状态词列表, 已编迭代号列表|[])。 累积制：按＋切段后段数不限，逐段各自合法；再查一条结构约束——下游段 （待写卡/已写卡/已编迭代）在场时禁残留未闭合设计段（带日期特批可豁免）。 @@ -177,13 +177,13 @@ def check_status(raw, line, issues, where): if not segs: issues.append((where, line, "状态词非法", "状态行内容为空")) return [], None - words, iter_no = [], None + words, iter_nos = [], [] for seg in segs: w, it = check_segment(seg, line, issues, where) if w: words.append(w) if it is not None: - iter_no = it + iter_nos.append(it) # 同一设计线只留最新一段：并现两段说明推进时忘了收旧段，或把另一条线的段 # 误写进本线条目；跨条设计线的未闭合依赖（如文档线已闭合写卡、美术线仍待设计）合法。 for track, name in ((DOC_DESIGN_WORDS, "文档线"), (ART_DESIGN_WORDS, "美术线")): @@ -191,7 +191,7 @@ def check_status(raw, line, issues, where): if len(hit) > 1: issues.append((where, line, "设计线段并现", "%s同时出现 %s（同线只留最新一段，§12.1）" % (name, "、".join(hit)))) - return words, iter_no + return words, iter_nos def check_todo(text, issues, where, root): @@ -228,7 +228,7 @@ def check_todo(text, issues, where, root): issues.append((where, line, "属性缺失", "条目缺「**%s**」属性" % req)) if "状态" not in attrs: continue - words, iter_no = check_status(attrs["状态"], attr_line["状态"], issues, where) + words, iter_nos = check_status(attrs["状态"], attr_line["状态"], issues, where) # 改动面：四档取多，＋连接，禁重复、禁自造词 if "改动面" in attrs: parts = [p.strip() for p in SURFACE_SEP_RE.split(attrs["改动面"]) if p.strip()] @@ -297,8 +297,9 @@ def check_todo(text, issues, where, root): if not need_gap and words and "缺口" in attrs: issues.append((where, line, "缺口属性", "状态为 %s，设计已闭合/后段不得残留「**缺口**」属性" % "、".join(words))) - if iter_no is not None: - links.append((line, iter_no, cards[0] if cards else None)) + if iter_nos: + for no in iter_nos: + links.append((line, no, cards)) return links @@ -423,17 +424,23 @@ def check_roadmap(text, issues, where, root): def cross_check(links, index, issues, where): - """唯一一处交叉核：已编迭代 N ↔ 总表迭代 N 行的需求卡片列。""" - for line, no, card in links: + """唯一一处交叉核：已编迭代 N ↔ 总表迭代 N 行的需求卡片列。 + + 一条目可有多张已写卡分编多个迭代（状态段累积「已编迭代 40＋已编迭代 41」）： + 对每个已编迭代号核两件——总表该行存在；该行卡片列含本条目至少一张已写卡路径。 + 哪张卡编哪个迭代的卡级映射由编排四查与人工核验，闸不猜卡级映射。 + """ + for line, no, cards in links: row = index.get(no) if row is None: issues.append((where, line, "交叉核", "迭代总表无迭代 %d 行" % no)) - elif card is None: + elif not cards: issues.append((where, line, "交叉核", "已编迭代 %d 但条目无可引的已写卡路径（须先已写卡）" % no)) - elif card not in row[1]: + elif not any(c in row[1] for c in cards): issues.append((where, line, "交叉核", - "迭代 %d 行卡片列不含本条目已写卡路径 %s" % (no, card))) + "迭代 %d 行卡片列不含本条目任何已写卡路径（%s）" + % (no, "／".join(cards[:3])))) def card_date(path): diff --git a/tools/run_all_gates.sh b/tools/run_all_gates.sh index 129af25a..9171e07c 100644 --- a/tools/run_all_gates.sh +++ b/tools/run_all_gates.sh @@ -41,6 +41,7 @@ GAME="$REPO/game" STAMP_DIR="$GAME/tests/.gates" RECEIPT="$STAMP_DIR/receipt.json" BASELINE="$STAMP_DIR/baseline.json" + QUICK=0 DOMAIN="full" for _a in "$@"; do @@ -53,6 +54,13 @@ for _a in "$@"; do esac done +# 每个代码面 worktree 用独立 Godot user 目录（game/override.cfg 由 setup 脚本自愈生成；主区 no-op）。 +# 并行批共用一套夹具、日志与截图目录会互相踩盘造成假红——隔离建不起来就拒跑（fail-closed）。 +"$REPO/tools/setup_worktree_userdir.sh" "$REPO" || { + echo "[gates] FAIL — user 目录隔离未建立，拒绝在共享目录上跑闸。" + exit 1 +} + # 控制台编码：本仓库闸件输出中文与 ✅/✗ 符号。Windows GBK 控制台下 python 打印这些字符会抛 # UnicodeEncodeError——待办清单/10 两闸直接崩（假红）、09 的 FAIL 行被写成乱码字节（指纹漂移， # 与基线比必判「红项清单变化」假红）、末尾汇总自身崩掉打不出结论。 diff --git a/tools/setup_worktree_userdir.sh b/tools/setup_worktree_userdir.sh new file mode 100644 index 00000000..58d5ef44 --- /dev/null +++ b/tools/setup_worktree_userdir.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +# 代码面 worktree 的 Godot user 目录隔离：给每个 worktree 生成 game/override.cfg， +# 让该区的 user:// 落到独立目录（夹具、日志、截图产物不再与其他区共用）。 +# 主工作区不生成——真实存档与试玩进度保持原位。 +# +# 用法：tools/setup_worktree_userdir.sh [仓库根]（缺省＝本脚本所在仓库） +# 幂等：内容一致即不重写；退出码 0＝已隔离或主区免隔离，1＝生成失败（闸壳据此拒跑） +set -u +ROOT="$(cd "${1:-$(dirname "$0")/..}" && pwd)" + +MAIN_WT="$(git -C "$ROOT" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | head -1)" +if [ -z "$MAIN_WT" ]; then + echo "[userdir] 取不到主工作区路径（git worktree list 为空）" >&2 + exit 1 +fi +if [ "$(cd "$ROOT" && pwd -P)" = "$(cd "$MAIN_WT" && pwd -P)" ]; then + echo "[userdir] 主工作区：不隔离（真实档保持原位）" + exit 0 +fi + +BASE="$(basename "$ROOT" | tr -d '\n' | tr -c 'A-Za-z0-9_-' '_')" +ABS="$(cd "$ROOT" && pwd -P)" +if command -v sha1sum >/dev/null 2>&1; then + FP="$(printf '%s' "$ABS" | sha1sum | cut -c1-8)" +else + FP="$(printf '%s' "$ABS" | cksum | tr -d ' ' | cut -c1-8)" +fi +NAME="DungeonSweeper_${BASE}_${FP}" +CFG="$ROOT/game/override.cfg" + +CONTENT="[application] + +config/use_custom_user_dir=true +config/custom_user_dir_name=\"$NAME\" +" +if [ -f "$CFG" ] && printf '%s' "$CONTENT" | cmp -s - "$CFG"; then + echo "[userdir] 已隔离：$NAME" + exit 0 +fi +mkdir -p "$ROOT/game" 2>/dev/null +if ! printf '%s' "$CONTENT" >"$CFG"; then + echo "[userdir] 写 $CFG 失败" >&2 + exit 1 +fi +echo "[userdir] 已隔离：$NAME" diff --git a/待办清单.md b/待办清单.md index 34324139..6942a0c7 100644 --- a/待办清单.md +++ b/待办清单.md @@ -4,19 +4,29 @@ #### gdstyle 存量债全量清偿——216 键按病根分波整改（2026-10-26 登记，来源=会话提及，优先级＝P0） -**实况**：S13 闸实测存量债 216 键／60 文件（2026-10-26，master f3b148ce，gdstyle v0.4.0 默认阈值；基线登记 234 键＝实存 216＋陈旧 18）。全量清单、波次方案与纪律见清点报告（本条目裁决源）。2026-10-26 用户裁：撤销「一条总账」与「按病根拆多条」两案，并为本条单账（存量债全部清除，紧急优先级）；原「gdstyle 基线陈旧键待人工清理」条目并入波 0（基线对账刷新），原「结构审查未立项小件候审」条目并入波 7（卡已写、停卡待裁）。**2026-10-26 设计段首轮裁定**：段组织＝逐波开设计段；波 2 各文件内部拆、波 6 视图内部拆私有函数、波 8 config_db 纯代码收敛——三处定性零设计改动；全部波不改游戏规则与玩家可见行为，design/gdd/systems/ 零修订预期，唯一设计改动面＝波 1 的 architecture.md 模块归属表（裁定全文见清点报告 §六）。 +**实况**：S13 闸实测存量债 216 键／60 文件（2026-10-26，master f3b148ce，gdstyle v0.4.0 默认阈值；基线登记 234 键＝实存 216＋陈旧 18）。全量清单、波次方案与纪律见清点报告（本条目裁决源）。2026-10-26 用户裁：撤销「一条总账」与「按病根拆多条」两案，并为本条单账（存量债全部清除，紧急优先级）；原「gdstyle 基线陈旧键待人工清理」条目并入波 0（基线对账刷新），原「结构审查未立项小件候审」条目并入波 7（卡已写；iter38 施工停卡后经用户裁于 2026-10-26 修订定稿 v1.3，待编排）。**2026-10-26 设计段闭合（逐波裁定全数落定）**：①段组织＝逐波开设计段，纯代码波（波 0/2/3/4/5/6/8）写卡前确认零设计改动＋按当时 master 重测读数即可写卡；②波 2 各文件内部拆、波 6 视图内部拆私有函数、波 8 config_db 纯代码收敛（三处零设计改动）；③波 1 拆件定稿＝轴甲两件——battle_orchestrator 拆出 BattleFxHost（效果引擎宿主域）＋RewardGrant（奖励授予域），宿主保留状态机/facts 缓冲/订阅/段驱动/行发射基建/呈现投影，attune 族原位保留（迭代 39 副卡语义领地），emit 经 bind 注入 Callable，行数恶化债（c4c69701 挂账）本波还债归绿，残留债「改善非清零」口径预计 8–10 键；定稿落文 architecture.md v1.18（功能层两新件行＋「战斗编排域拆件定稿」节）；**同日独立审查折入**（grilling＋godot-master 双子代理并行、双判回炉补裁级——骨架成立、接线未闭合）：阻断 8 条去重 6 组＋建议 5 条全数折入 v1.18——跨件单向接线裁死（RewardGrant 持 fx 件引用/fx 兑付走注入 Callable，禁 RefCounted 环）、settlement/ 段类随动（直持三引用封转发壳）、12 随迁键卡内收敛义务（禁波 0 refresh 吸收）、两新件消费依赖列补全＋引用束注入、treasure_interact_controller 三触点分家（现值回调双取值面）、_fx_revealing 再入闸归 fx 件（裁定全文见清点报告 §六第 6 条）；④全部波不改游戏规则与玩家可见行为，design/gdd/systems/ 零修订预期；波 5 已实查落定纯代码（open_ticket 12 参＝单据声明形态）。波 7 的 wr5/wr6 验收载体重裁为写卡段用户裁点（卡 v1.2 在册，写卡补呈报）。裁定全文见清点报告 §六。 关联文档清单： -- 清点报告 reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md（2026-10-26，216 键全量清单＋波次方案＋纪律＋设计段裁定记录 §六） +- 清点报告 reports/审计-gdstyle存量债清点与清偿方案-2026-10-26.md（2026-10-26，216 键全量清单＋波次方案＋纪律＋设计段裁定记录 §六含整合裁定第 7 条） +- 设计定稿 design/engineering/architecture/architecture.md v1.19（2026-10-27：波 1 拆件定稿 v1.18 节＋全清设计补课——ConfigDB 访问器归位与域容器持有＋SlotStore/MetaStateStore 两新件行＋组合根句柄面/测量面两处 S13 豁免登记） +- 需求卡片 reports/需求卡片-B1战斗域拆件批-2026-10-27.md（2026-10-27 v1.1 全清口径修订：对拍停止改 dump_battle 替代验收＋settlement_table 拆两个子 Resource 段＋宿主超标函数全清；估时 ≈5.25d；零待裁点） +- 需求卡片 reports/需求卡片-核心数据面结构收敛批-2026-10-27.md（2026-10-27 v1.1 全清口径修订：config_db 访问器归位＋三域容器＋SlotStore/MetaStateStore 拆件＋adventure_table 拆段＋spawn 束化；估时 ≈7.9d；零待裁点） +- 需求卡片 reports/需求卡片-呈现层结构收敛批-2026-10-27.md（2026-10-27 v1.1 全清口径修订：print 删除＋七件绘制态内部收拢＋main/await 两键按 v1.19 豁免申报；估时 ≈5.3d；零待裁点） - 需求卡片 reports/需求卡片-冒险域拆件与账本实体化批-2026-10-26.md v1.2（规避指向：三宿主债归此卡与姊妹副卡，本事项禁触，残留归尾波） - 需求卡片 reports/需求卡片-同调配装充能域封装批-2026-10-26.md v1.2（同上规避指向） -- 需求卡片 reports/需求卡片-结构小件定点修批-2026-10-26.md v1.2（波 7 现成卡：iter38 卡②停卡退回上游，随本事项重裁验收载体） - -**缺口**：逐波设计确认制——纯代码波（波 0/2/3/4/5/6/8）写卡前确认零设计改动＋重测读数；波 1 须先完成 battle_orchestrator 拆件设计讨论并登记 architecture.md 新模块行；波 7 随本事项重裁 wr5/wr6 验收载体。 +- 需求卡片 reports/需求卡片-结构小件定点修批-2026-10-26.md v1.3（波 7 现成卡：iter38 卡②停卡退回上游后，2026-10-26 用户裁定验收载体改独立负面套件＋并修未播种分支，卡面已修订定稿待编排） **改动面**：游戏代码＋工具代码 -**状态**：文档设计中 +**状态**：文档设计已闭合＋已写卡＋已编迭代 40＋已编迭代 41 + +#### 波 0：gdstyle 基线刷新——清 18 陈旧键＋登记迭代 40 还债水位（2026-10-27 登记，来源=会话提及） + +**实况**：证据＝`tools/gdstyle_baseline.txt` 存量登记 234 键中有 18 条陈旧键不命中当前盘面（迭代 37 重构已消、键未清）＋迭代 38 特批带红合并的恶化债（git 提交 c4c69701）待迭代 40 还债归绿——刷新后账本对齐现实。人工 `python tools/gdstyle_gate.py --refresh` 一次，清陈旧键 18 条（骤降 18/234≈7.7% 低于 10% 守卫线无需 --force）＋登记迭代 40 还债后的新水位（卡① battle_orchestrator 行数归绿、卡① settlement_table 拆段后的键账变化）。**执行时点＝迭代 40 合回 master 之后、用户发令**（「gdstyle 存量债全量清偿」条目清点报告波 0 行同源）；处迭代 40 与 41 之间的固定动作，完成即删本条目。 + +**改动面**：工具代码 + +**状态**：待执行 #### AdventureRunner 职责真拆分——三宿主共 25 条转发属性属 S13 计数迎合装置，须按变化原因重立协作件（2026-10-25 登记，来源=批次移交，优先级＝P0）