25 KiB
25 KiB
gdstyle 存量债清点与清偿方案(2026-10-26)
- 性质:设计讨论段过程稿(登记支撑件)——待办清单条目「gdstyle 存量债全量清偿」的裁决源;结论被需求卡片吸收后本件按「吸收即死」退役。
- 清点时点:2026-10-26,master 分支 f3b148ce;工具 gdstyle v0.4.0(版本钉定),配置
tools/gdstyle.toml,扫描面 game/core/game/data/game/presentation 共 109 个 .gd。 - 优先级:P0(紧急)——2026-10-26 用户裁。
- 范围裁定:2026-10-26 用户裁——撤销「一条总账」与「按病根拆多条」两案,并入待办清单单条总账事项(存量债全部清除),细则落本报告;adventure_runner/level_runner/board_view 三宿主已编迭代 39,规避不重复整改。
一、口径与账目
S13 闸=「当前扫描 vs 基线对账」:判红仅两种——基线外新违规(NEW)、同键数值较登记值恶化(WORSENED);存量登记在案不判红(判据与键形态见 tools/gdstyle_gate.py 头注)。因此「债存在」与「闸绿」并行不悖:闸的职责是冻结债务不增长,清偿走迭代批。
账目(键=文件|规则|函数名 稳定身份键;同文件同规则多条命中合并取较大值):
- 基线登记 234 键 = 实存 216 + 陈旧 18(迭代 37 重构已消、键未清——原「gdstyle 基线陈旧键待人工清理」条目,本方案并入波 0)。
- 实存 216 键分布 60 个文件;阈值型 10 规则与缺陷型 4 规则有命中,其余 8 个在跑规则零命中。
- 阈值全部取 gdstyle 默认值(改阈值=基线口径变,须随批人工重生成基线):
| 规则 | 查什么 | 阈值 | 实存 |
|---|---|---|---|
| quality/max-function-length | 单个函数体行数 | ≤50 行 | 49 |
| quality/max-local-variables | 单函数局部变量数 | ≤10 | 46 |
| quality/max-branches | 单函数分支数 | ≤8 | 32 |
| quality/max-parameters | 函数参数个数 | ≤5 | 22 |
| quality/max-class-variables | 类成员变量数 | ≤15 | 18 |
| quality/max-returns | 函数 return 语句数 | ≤6 | 16 |
| quality/max-nesting-depth | 嵌套深度 | ≤4 层 | 12 |
| quality/max-public-methods | 类公开方法数 | ≤20 | 7 |
| quality/max-file-length | 文件总行数 | ≤1000 行 | 1 |
| quality/max-inner-classes | 文件内 inner class 数 | ≤5 | 0 |
| 缺陷型 4 条 | allocation-in-loop(循环内 .new())/no-debug-print(残留 print)/no-else-return/await-in-loop | 无阈值,命中即记 | 9 文件/2/1/1 |
二、规避清单(已处理事项,不在本事项范围)
- adventure_runner/level_runner/board_view 三宿主:已编迭代 39 主副卡(
reports/需求卡片-冒险域拆件与账本实体化批-2026-10-26.mdv1.2+reports/需求卡片-同调配装充能域封装批-2026-10-26.mdv1.2),类变量改善目标 42→约20/38→约30/45→32 已写死卡内(三宿主实存债 14 键:adventure_runner 4/level_runner 4/board_view 6)。本事项全部波次禁触三宿主文件,防与迭代 39 批次冲突。 - 尾波回收:迭代 39 合回后三宿主必有残留债(拆件目标是职责拆分与计数改善,非清零),届时重新清点并入尾波处理。
三、清偿波次
原则:一波=一个病根=一张需求卡;每波独立走写卡→编排五段推进(工作量限制属迭代层非卡片层);波内文件即该卡改动面边界。键数为 2026-10-26 实测。
| 波 | 范围 | 键数 | 病根与做法方向 | 前置与注意 |
|---|---|---|---|---|
| 波0 | 基线对账刷新(tools/gdstyle_baseline.txt) |
18 陈旧键 | 人工 --refresh 一次清理陈旧键(原「gdstyle 基线陈旧键待人工清理」条目并入本波)。iter38 两条恶化的处置已结(2026-10-26 用户特批带红合并 8ea7cfba:恶化记入闸机基线存量红 c4c69701,还债义务归波 1/波 6)——本波余量=纯陈旧键清理,可与波 1/波 6 还债后的归绿 refresh 合并一次执行 |
iter38 已合回,前置已满足;骤降守卫 18/234≈7.7% 低于 10% 线,无需 --force |
| 波1 | battle_orchestrator | 22 | 22 条全库单文件最大户(iter38 合回后 1314 行/类变量 50/begin_battle 141 行 17 分支等);按变化原因拆协作件(先例=AdventureRunner 真拆分 architecture v1.16 流程) | 前置=文档设计段闭合;文件在 PARITY_TOUCH_FACES——实跑对拍须经用户批准、不得借机重锚;扛 iter38 特批带红合并的恶化债一条(行数 1314>1302,c4c69701)——本波还债或随批批准 refresh 归绿 |
| 波2 | meta_tree_table+treasure_item_table+board_gen_table+enemy_table+forge_table+level_gen_params+meta_table+reward_table+skill_table+variation_table+status_effect_table+config_db_cross_validator+config_db_resolver | 40 | 数据校验族同病根:validate()/cross_validate() 过长过分支(treasure_item 147 行 44 分支、enemy 116 行 32 分支、cross_validate 107 行 21 分支);方向=各文件内部拆校验域私有函数族(2026-10-26 用户裁,不抽共享骨架) | fail-fast 契约与校验覆盖面零变化;断言面=现有 validate 系单测逐字保留 |
| 波3 | grant_segment+combat_segment+settlement_table | 12 | 结算管线:grant_segment run() 211 行/36 局部/33 分支(全库最大单函数)+_judge_seal 84 行;combat_segment run() 83 行 | settlement/ 在 PARITY_TOUCH_FACES——对拍须用户批准;结算数值与行型协议零触碰(iter38 卡④刚收敛) |
| 波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.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 合回 |
合计核对:波 1–6+波 8=202 键+三宿主规避 14 键=216 键(断言在生成脚本内)。
四、纪律与额外要求
- 五段流水线逐波走:每波独立需求卡(零待裁点)、独立编排;本条目只做登记与波次总账,不代替写卡段。
- 验收铁规:每波行为零变化(结构整改不改游戏行为)+真实入口断言+撤销证明;禁删断言、禁放宽阈值换绿。
- 基线纪律:禁为过闸改基线或 refresh 换绿;还债=数值下降自然绿;出现恶化=停卡呈报。波 0 是唯一一次经用户批准的 refresh。
- MC/对拍:数值与 RNG 零触碰则 11 对拍不补跑;波 1/波 3 触 PARITY_TOUCH_FACES,实跑对拍须经用户批准、不得借机重锚。
- 呈现零变化:波 6 触视图面,改前建 golden 基线(先例=iter38 卡① level_map.png),对拍差异非零即红。
- 读数漂移:本清点基于 master f3b148ce;iter38 合回与后续批次会漂移读数——每波写卡前以当时 master 重新实测,禁按本附录行号直接施工。
五、附录:216 键全量清单(按文件,2026-10-26 实测)
读法:现值/阈值;「文件级」=类或文件维度超标,其余点名到函数。规避三宿主照列并标注,供尾波清点对账。
game/core/battle_orchestrator.gd(22 条)
- 文件级 文件行数 1314/1000
- 文件级 类变量 50/15
_fx_fact()return数 7/6begin_battle()函数长度 141/50begin_battle()return数 7/6begin_battle()分支 17/8begin_battle()局部变量 16/10_place_variants()函数长度 52/50_place_variants()局部变量 14/10_place_variants()嵌套 6/4use_treasure()函数长度 62/50use_treasure()return数 8/6use_treasure()分支 18/8use_treasure()局部变量 11/10_grant_routed()参数 8/5_dispatch_row()参数 6/5_apply_percent_row()参数 6/5_apply_gp_row()参数 6/5_apply_flat_row()参数 7/5_apply_flat_row()return数 9/6_submit_flat_hero()参数 7/5_emit_row()参数 8/5
game/presentation/views/camp_overlay_view.gd(10 条)
- 文件级 类变量 19/15
- 文件级 循环内new
_init()函数长度 149/50_init()局部变量 28/10_rebuild_tree()函数长度 61/50_rebuild_tree()局部变量 21/10_rebuild_forge()函数长度 72/50_rebuild_forge()局部变量 20/10refresh_camp()函数长度 61/50refresh_camp()局部变量 17/10
game/core/damage_controller.gd(9 条)
- 文件级 类变量 19/15
open_ticket()参数 12/5_hero_attack_ctx()函数长度 61/50_hero_attack_ctx()分支 9/8_hero_attack_ctx()局部变量 16/10_hero_attack_redeem()函数长度 54/50_hero_attack_redeem()分支 10/8_hero_attack_redeem()局部变量 12/10_resolve_enemy_skill()局部变量 13/10
game/core/node_map_generator.gd(9 条)
check_params()分支 12/8validate_output()函数长度 132/50validate_output()return数 7/6validate_output()分支 34/8validate_output()局部变量 22/10_build()局部变量 15/10_add_forks()局部变量 12/10_assign_types()分支 11/8_check_fork_rules()嵌套 5/4
game/core/board_generator.gd(8 条)
generate()函数长度 62/50generate()局部变量 14/10_attempt()函数长度 51/50measure_inferability()函数长度 64/50measure_inferability()分支 12/8measure_inferability()局部变量 13/10measure_inferability()嵌套 5/4_finalize()参数 6/5
game/core/effect_engine.gd(8 条)
- 文件级 多余else
rebuild()函数长度 55/50rebuild()嵌套 5/4_cond_ok()函数长度 52/50_cond_ok()return数 19/6_cond_ok()嵌套 5/4validate_trigger_row()分支 14/8validate_trigger_row()局部变量 11/10
game/core/settlement/grant_segment.gd(8 条)
run()函数长度 211/50run()分支 33/8run()局部变量 36/10run()嵌套 6/4_judge_seal()函数长度 84/50_judge_seal()分支 14/8_judge_seal()局部变量 11/10_judge_seal()嵌套 6/4
game/presentation/views/board_view.gd(6 条)〔规避:迭代 39 三宿主〕
- 文件级 类变量 45/15
- 文件级 公开方法 27/20
- 文件级 循环内new
_paint_cell()函数长度 139/50_paint_cell()分支 24/8_paint_cell()局部变量 22/10
game/presentation/views/level_map_screen.gd(6 条)
- 文件级 类变量 22/15
_init()函数长度 135/50_init()局部变量 21/10_draw_graph()函数长度 78/50_draw_graph()分支 9/8_draw_graph()局部变量 27/10
game/core/config_db_cross_validator.gd(5 条)
cross_validate()函数长度 107/50cross_validate()分支 21/8cross_validate()局部变量 24/10cross_validate()嵌套 5/4validate_skill_pool_links()局部变量 11/10
game/presentation/views/ui_kit.gd(5 条)
- 文件级 公开方法 26/20
beams_rect()局部变量 13/10modal_shell()参数 6/5_init()参数 6/5bcard()参数 6/5
game/core/adventure_runner.gd(4 条)〔规避:迭代 39 三宿主〕
- 文件级 类变量 42/15
- 文件级 公开方法 23/20
_apply_curio_pick()return数 9/6_apply_curio_pick()分支 10/8
game/core/config_db_resolver.gd(4 条)
resolve_enemy_rowset()分支 12/8_resolve_progress()函数长度 52/50_resolve_progress()分支 16/8_resolve_progress()局部变量 11/10
game/core/level_runner.gd(4 条)〔规避:迭代 39 三宿主〕
- 文件级 类变量 38/15
- 文件级 公开方法 54/20
start_level_external()参数 7/5_enter_node()return数 7/6
game/data/schemas/meta_tree_table.gd(4 条)
validate()函数长度 86/50validate()分支 26/8validate()局部变量 13/10validate()嵌套 5/4
game/data/schemas/treasure_item_table.gd(4 条)
validate()函数长度 147/50validate()分支 44/8validate()局部变量 26/10validate()嵌套 6/4
game/presentation/views/battle_end_overlay.gd(4 条)
- 文件级 类变量 20/15
- 文件级 循环内new
_init()函数长度 81/50open_victory()参数 8/5
game/presentation/views/battle_log_view.gd(4 条)
_format_row()函数长度 68/50_format_row()return数 13/6_format_row()分支 9/8_format_row()局部变量 21/10
game/presentation/views/board_cell_unit.gd(4 条)
- 文件级 类变量 31/15
_draw()函数长度 147/50_draw()分支 29/8_draw()局部变量 19/10
game/presentation/views/hero_info_panel_view.gd(4 条)
- 文件级 循环内new
_init()函数长度 74/50set_treasure_inventory()函数长度 57/50set_treasure_inventory()局部变量 13/10
game/presentation/views/standee_body.gd(4 条)
- 文件级 类变量 29/15
- 文件级 循环内new
_draw()函数长度 84/50_draw()局部变量 26/10
game/core/reward_economy.gd(3 条)
roll_board()函数长度 54/50roll_board()局部变量 11/10_skewed_cell_rows()局部变量 13/10
game/core/save_manager.gd(3 条)
- 文件级 公开方法 52/20
_peek_summary_at()return数 7/6load_from_disk()return数 8/6
game/core/status_container.gd(3 条)
apply_effect()return数 9/6apply_effect()嵌套 5/4_new_instance()参数 7/5
game/core/unit_container.gd(3 条)
spawn()函数长度 81/50spawn()参数 10/5spawn()局部变量 17/10
game/data/schemas/board_gen_table.gd(3 条)
validate()函数长度 67/50validate()分支 20/8validate()局部变量 16/10
game/data/schemas/enemy_table.gd(3 条)
validate()函数长度 116/50validate()分支 32/8validate()局部变量 29/10
game/data/schemas/forge_table.gd(3 条)
validate()函数长度 95/50validate()分支 30/8validate()局部变量 20/10
game/data/schemas/level_gen_params.gd(3 条)
validate()函数长度 59/50validate()分支 15/8validate()局部变量 18/10
game/data/schemas/meta_table.gd(3 条)
validate()函数长度 60/50validate()分支 14/8validate()局部变量 14/10
game/data/schemas/reward_table.gd(3 条)
validate()函数长度 99/50validate()分支 30/8validate()局部变量 20/10
game/presentation/hud_presenter.gd(3 条)
refresh()参数 8/5_refresh_out_of_battle()参数 6/5tune_sim_report()参数 10/5
game/presentation/tune_sim_controller.gd(3 条)
- 文件级 print残留
- 文件级 循环内await
run()局部变量 11/10
game/presentation/ui_assembler.gd(3 条)
- 文件级 循环内new
build_start_overlay()函数长度 83/50build_start_overlay()局部变量 16/10
game/presentation/views/battle_stage_view.gd(3 条)
- 文件级 循环内new
_init()函数长度 97/50_enemy_portrait_tex()return数 9/6
game/presentation/views/debug_overlay.gd(3 条)
- 文件级 类变量 17/15
_build()函数长度 124/50_build()局部变量 22/10
game/core/config_db.gd(2 条)
- 文件级 类变量 25/15
- 文件级 公开方法 44/20
game/core/meta_progression.gd(2 条)
- 文件级 公开方法 31/20
tree_can_buy()return数 8/6
game/core/settlement/combat_segment.gd(2 条)
run()函数长度 83/50run()局部变量 13/10
game/core/treasure_items.gd(2 条)
validate_use()分支 11/8validate_use()嵌套 5/4
game/data/schemas/settlement_table.gd(2 条)
- 文件级 类变量 18/15
validate()分支 16/8
game/data/schemas/skill_table.gd(2 条)
validate()函数长度 80/50validate()分支 29/8
game/data/schemas/variation_table.gd(2 条)
validate()函数长度 58/50validate()分支 20/8
game/presentation/curio_flow_context.gd(2 条)
- 文件级 类变量 16/15
_init()参数 16/5
game/presentation/treasure_interact_controller.gd(2 条)
_init()参数 7/5inventory_projection()局部变量 11/10
game/presentation/views/curio_pick_overlay.gd(2 条)
_init()函数长度 52/50_icon_for_id()return数 7/6
game/presentation/views/settings_overlay.gd(2 条)
_build()函数长度 77/50_build()局部变量 13/10
game/core/action_economy.gd(1 条)
- 文件级 类变量 18/15
game/core/minesweeper_rules.gd(1 条)
_do_dig()函数长度 53/50
game/data/schemas/adventure_table.gd(1 条)
- 文件级 类变量 44/15
game/data/schemas/status_effect_table.gd(1 条)
validate()分支 12/8
game/presentation/battle_narrator.gd(1 条)
bonus_card_text()return数 9/6
game/presentation/camp_flow_context.gd(1 条)
_init()参数 12/5
game/presentation/curio_interact_controller.gd(1 条)
- 文件级 类变量 18/15
game/presentation/main.gd(1 条)
- 文件级 类变量 49/15
game/presentation/playtest_logger.gd(1 条)
- 文件级 print残留
game/presentation/views/ap_bar_view.gd(1 条)
_init()函数长度 69/50
game/presentation/views/board_fx_view.gd(1 条)
- 文件级 循环内new
game/presentation/views/board_zone_view.gd(1 条)
_init()函数长度 59/50
game/presentation/views/legend_overlay.gd(1 条)
- 文件级 循环内new
六、文档设计段裁定记录(2026-10-26,用户裁)
依据=architecture.md v1.16 与 code-conventions/test-conventions 交叉校验后的设计段首轮裁定:
- 段组织=逐波开设计段:每波写卡前过一遍设计确认——纯代码波确认零设计改动+按当时 master 重测读数即可写卡;波 1 拆件设计讨论单开(唯一硬设计前置,产出=architecture.md 模块归属表新行登记)。
- 波 2 形态=各文件内部拆校验域私有函数族,不抽共享校验骨架(13 文件结构各异,强行归一有抽象层风险;零新概念零架构登记)。
- 波 6 形态=视图内部拆私有函数,不拆构建步件(main_ui_build 先例的动机是组合根超限,普通视图不类比)。
- 波 8 config_db 公开方法收敛=纯代码(删冗余、私有化内部方法,不动对外语义;架构表「对外暴露」列属现状登记,实现批后随动改写)。
- 判定口径:全部波不改游戏规则与玩家可见行为——design/gdd/systems/ 零修订预期;唯一设计改动面=波 1 的 architecture.md;owner 契约若被触碰走迭代批反哺点通道(正常机制)。波 5 已实查落定:open_ticket 12 参全是单据声明形态,「九栏目」只在架构模块描述层、GDD 无此契约,参数收束不改单据栏目与明细行发射协议,纯代码。
- 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 流随件迁移取号序不变。
- 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(均为常规区间)。