gplan-2/game/tests/README.md

Test Manual — Dungeon Sweeper（测试工具手册）

Engine: Godot 4.7.2-stable（GDScript 单语言） Test Framework: 标准测试层（冒烟／单元／系统）＋ headless 场景探针与渲染 golden——层识别三元组（职责×触发时间点×覆盖面积）的权威表＝test-conventions「测试层三元组」节，层级名只是代称；gdUnit4 deferred（D2 OQ1 关闭形态——本仓库不引第三方测试框架，需求见下「门禁」节） 门禁: 本地闸——tools/run_all_gates.sh（收口唯一验收入口，按改动域选档 --code／--docs，跨两域或改闸件本身不带参数＝全量；代码域 02 按关联档选套件，算法与套件族映射表只在脚本内定义）。本仓库无远端、无 CI（.github/workflows/ 已删除，不建不留不参考）；闸清单与域划分只在本脚本定义，文档不另列 Setup date: 2026-09-12 参考实现: game/probe/（场景探针族）· game/sim/（测量/诊断/模拟驱动件）（场景探针族——正式工程的活样板；系统测试断言面过渡宿主 smoke_all.gd 亦在此，迁移归断言迁移批）

本手册是测试面每件工具的介绍处：它是什么、判什么、怎么单独跑、结果由谁判、什么时候会用它。 分工三线——介绍归本文；规则与时机（什么时候必须跑哪些测试、测试怎么写、怎么算合格）归 design/engineering/test-conventions.md；收口验收跑哪几道闸（闸清单与改动域划分）只在 tools/run_all_gates.sh 脚本内定义一处，本手册不另列闸清单。

Directory Layout

tests/
  unit/              # 单元测试（公式/状态机/纯逻辑隔离断言＋跨系统真实路径闭环，同一环境同一协议）——extends SceneTree + quit(code)
  smoke_boot.tscn/.gd  # 冒烟测试——极小启动场景（真实开机路径存活检查）
  system_test.gd     # 系统测试宿主薄壳（SceneTree＋构造注入）
  smoke/             # critical-paths.md——人工 gate 清单（/smoke-check 读取）
  evidence/          # 截图与人工签核记录
  run_all.gd         # 单元测试统一入口（套件 manifest 协议，D2 AC-2b）
  static_scan.sh     # 静态扫描域 S1–S12 可执行子集

测试层级（标准三级＋UI 探针；识别三元组见 test-conventions「测试层三元组」节）

层	判什么	承载	入闸方式
冒烟测试	这版活着吗——能否启动、能否加载表、能否进主屏。零逻辑判定	tests/smoke_boot.tscn/.gd（以项目运行目标拉起＝真实开机路径）	run_smoke.py（冒烟测试闸）
单元测试	受控裸环境断言面——单机制契约（公式/状态机/纯逻辑，从对外方法进、断言钉对外可观测面，写法判据见 test-conventions §8.2）＋跨系统真实路径闭环（两以上真实系统手工装配×落盘/落库往返）	tests/unit/	run_all.gd manifest（单元测试闸）
系统测试	启动真实工程走真实玩法路径	tests/system_test.gd	run_system_test.py（系统测试闸）
UI 探针＋渲染 golden	跑起来之后 UI 与场景切换对不对；画面基线	game/probe/*.tscn 探针	probe_gate.sh（场景探针闸）、render_gate.sh（渲染闸）

分层判据（2026-11-07 用户裁层级合并）：能不能在 --script 模式下不加载开机装配（autoload）就验完？ 能 = 单元测试——单机制契约（一个领域类＋注入依赖）与跨系统真实路径闭环（两以上真实系统手工装配×落盘/落库 往返，如存档⇄RNG 快照往返、旧档迁移续玩、同种子重开图）都在这层；需要完整项目引导与场景树 = 冒烟／系统／UI 探针。 闭环套件的性质归属（跨系统面＝哪几件协同）由各套件头注「跨系统面」句承载，不再靠层级名区分。

能力清单（能力义务清单：一行＝一个玩家或系统可观测的能力，只宣布「要验证什么」，不记「是否已验证／是否跑过」；定位＝实现指导＋阅读导航＋义务声明，代表用例只给指针、不复制断言细节。七段＝核心四域＋排雷循环＋表现与支撑＋数据配置与跨系统契约，行数随清单生长不在此记账；系统文档逐篇对照见下方「覆盖域表」）：

本表地位：本表是唯一能力义务清单（维护锚＝test-conventions §8.3 清单归属＋§8.9 三层模型）。本表不是闸，不替代改动—验收对照表、体验验证清单与静态纪律；已落地行的唯一事实源是 game/tests/ 下的测试代码，计划中的行由需求卡片锚定（见维护规则）。

代表用例口径：写 文件:函数，每行 1–3 个；函数内可含 Kit.check_quiet 静默通道（逐断言提取器口径外，test-conventions §5.2 已备案）——本表以函数为锚，不受该工具局限影响。计划中的用例＝卡内定死的测试名，实现落地后转为代码实锚（机检双通道：代码在或卡在，test-conventions §8.9）。

维护规则（写卡段维护，实现批禁写本表）：写需求卡片时当场入表——本批新增能力当场增行（真实入口取自设计文档已定的入口；代表用例＝卡内定死的计划测试 文件:函数，实现照单落名，名实不符＝卡片没写清＝停卡退回）；受影响存量行（入口／用例名变更）同批更新；能力退役删行。批末收尾只核对表上名字与实际落地一致（改名则回表），不刷任何批次字段（test-conventions §8.3／§8.9）。

旅程补录方法：新旅程＝加一行，「系统」列写涉及边界；源＝architecture「API 边界」表＋「数据流」存档/读档路径＋各 GDD 登记的 deferral 跨系统用例。

旅程段一：开机与存档

能力	系统	真实入口	代表用例（文件:函数）
存档写盘⇄读回往返保真	存档序列化	SaveManagerCore.write_to_disk()／load_from_disk()	save_manager_domain_test.gd:_smoke_save
三槽位隔离与激活失败回滚	存档序列化	SaveManagerCore.activate_slot()／create_slot()／delete_slot()	save_slot_isolation_test.gd:_test_three_slot_roundtrip_and_isolation；save_slot_isolation_test.gd:_test_activate_failure_restores_previous_slot
槽位摘要窥视与坏槽三态	存档序列化	SaveManagerCore.peek_slot_summary()	save_slot_summary_test.gd:_test_peek_three_slots_distinct_values；save_slot_summary_test.gd:_test_peek_empty_and_unreadable_states；save_slot_summary_test.gd:_test_peek_zero_side_effect
启动态无激活不写盘	存档序列化	SaveManagerCore.has_write_target()／write_to_disk()	save_boot_no_activate_test.gd:_test_write_rejected_without_target；save_boot_no_activate_test.gd:_test_out_of_range_slots_rejected
旧档迁移链与断点续玩零跳号	存档序列化×冒险结构	SaveManagerCore.load_from_disk()（内置迁移链）× AdventureRunner.resume_adventure()	save_rng_roundtrip_test.gd:_test_old_version_save_migrates_and_resumes
存档⇄RNG 快照往返保真	存档序列化×RNG 服务×冒险结构	AdventureRunner.start_adventure() → SaveManagerCore.write_to_disk()／load_from_disk()	save_rng_roundtrip_test.gd:_test_disk_roundtrip_preserves_breakpoint
RNG 统一流派生与取号账本	RNG 服务	RngServiceCore.derive_at()／open_stream()／counter()	rng_service_test.gd:_test_derive_determinism；rng_service_test.gd:_test_stream_draw_determinism；rng_stream_boot_test.gd:_smoke_initialize
断点片段往返与续玩幂等	冒险结构×关卡节点地图	LevelRunner.breakpoint_fragment()／restore_fragment()；AdventureRunner.resume_adventure()	breakpoint_resume_test.gd:_init
跨系统附随面：事件日志落盘与断点附随件	RNG 服务×存档序列化×冒险结构	RngServiceCore.new_adventure()（开事件日志会话）；SaveManagerCore.breakpoint_snapshot()（断点附随键）	cross_system_flow_test.gd:_rng_event_log_session；cross_system_flow_test.gd:_feats_breakpoint_roundtrip

旅程段二：冒险开局与选路

能力	系统	真实入口	代表用例（文件:函数）
冒险生命周期：开局受理／三关序列／败北线	冒险结构	AdventureRunner.start_adventure()／continue_to_next_level()	adventure_feats_test.gd:_smoke_adventure_api；adventure_feats_test.gd:_smoke_adventure；hero_ledger_test.gd:_init
专长（奇物）授予与凭证保底	奇物	AdventureRunner.present_node_curio()／feats_held() × 效果引擎兑付	adventure_feats_test.gd:_smoke_feats；feat_vouchers_test.gd:_init
节点图生成合法性与同种子复现	关卡节点图生成	NodeMapGenerator.generate()／validate_output()	node_map_generator_test.gd:_test_output_ok；node_map_generator_test.gd:_test_reproducible；node_map_generator_test.gd:_test_exit_structure
节点图生长递增与无解 fail-fast	关卡节点图生成	NodeMapGenerator.generate()／is_fatal()	node_map_growth_test.gd:_test_growth；node_map_growth_test.gd:_test_fatal_subprocess
节点图参数读表与域单点（三参数驱动产物／生成器侧可行性保留）	关卡节点图生成	NodeMapGenerator.generate()／LevelGenParams.validate()	node_map_generator_test.gd:_test_gen_params_table_driven；table_structure_guard_test.gd:_test_level_gen_new_fields；level_gen_params_test.gd:_init；encapsulation_p2_sweep_test.gd:_init
起关／选路／断点重生成同图	关卡节点地图×关卡节点图生成×冒险结构	LevelRunner.start_level()／start_level_external()／pick_next_node()；AdventureRunner.resume_adventure()	node_map_determinism_test.gd:_smoke_generated_map_determinism
信息迷雾类型可见性	关卡节点地图	LevelRunner.type_visible_ids()	level_map_type_vis_test.gd:_test_layer_distance；level_map_type_vis_test.gd:_test_boss_exempt；level_map_type_vis_test.gd:_test_resume_rebuild；level_map_info_fog_test.gd:_initialize
关卡表消费侧校验与关卡推进	关卡节点地图×数据配置	LevelTable.validate_graph()；LevelRunner.start_level()	level_table_validate_test.gd:_test_positive；level_table_validate_test.gd:_test_negative；level_shop_economy_test.gd:_smoke_level

旅程段三：战斗结算

能力	系统	真实入口	代表用例（文件:函数）
伤害公式与掷点乘区	战斗结算	DamageMath.pool_damage()／roll_discount_percent()／rolled_component()	damage_math_test.gd:_test_pool_damage；damage_math_test.gd:_test_roll_discount_percent；roll_multiplier_test.gd:_smoke_armor_roll
伤害单据编排与回放	战斗结算	DamageController.submit()／open_ticket()／flush()	damage_controller_test.gd:_run_recipe_sequence；damage_controller_test.gd:_test_five_recipes_and_replay
效果发射端口单点	战斗结算	BattleOrchestrator.begin_battle()（真实装配链端口接线＋合成行闭面守卫经 DamageController.flush_submit() 承伤路径）	effect_port_test.gd:_smoke_effect_port_wiring；effect_port_test.gd:_test_business_classes_engine_free；effect_port_test.gd:_test_biz_fact_face_closed
轮内流与结算五段全序	战斗结算	BattleOrchestrator.begin_battle()	round_flow_skill_pool_test.gd:_smoke_full_battle；round_flow_skill_pool_test.gd:_smoke_settlement_segments；settle_segments_test.gd:_init；settlement_wiring_snapshot_test.gd:_init；encapsulation_sweep_test.gd:_init
技能池数据面与回放独立	敌人系统	BattleOrchestrator.begin_battle()（技能池抽号／校验）	round_flow_skill_pool_test.gd:_smoke_skill_pool_data；round_flow_skill_pool_test.gd:_smoke_skill_pool_replay_independence；trigger_cond_test.gd:_init；pool_case_d_test.gd:_init
Boss 半血解锁技门控	敌人系统	BattleOrchestrator.begin_battle()（Boss 行）	skill_unlock_test.gd:_test_gate_predicate；skill_unlock_test.gd:_test_latch_irreversible
封印与极性路由／不可逆	地图战斗资源×战斗结算	效果引擎 × BattleOrchestrator.begin_battle()	seal_polarity_test.gd:_smoke_seal_ap_exhausted；seal_polarity_test.gd:_smoke_seal_irreversible_quadrants；seal_polarity_test.gd:_smoke_polarity_routing
变异布置门控	地形变异	BattleOrchestrator.begin_battle()（变异布置段）	variant_placement_test.gd:_smoke_variant_placement；variant_placement_test.gd:_smoke_global_variant；variant_placement_test.gd:_test_pack_min_from_table

旅程段四：奖励、经济与局外成长

能力	系统	真实入口	代表用例（文件:函数）
清图奖励双份与零路径	地图战斗资源	BattleOrchestrator.begin_battle() → 步骤流行（source_class=clear_reward）	seal_polarity_test.gd:_smoke_clear_reward_chain；seal_polarity_test.gd:_smoke_clear_reward_zero_paths
奖励三选一候选／刷新付费／呈现	奇物×节点奖励屏	AdventureRunner.present_node_curio()（数据面）；奖励节点覆盖层场景（呈现面）	curio_refresh_paid_test.gd:_init；reward_overlay_test.gd:_run
GP 钱包／escrow／商店收口／共享池	地图战斗资源×商店	LevelRunner.shop.buy_product()／shop.player_request_refresh()／LevelRunner.close_wallet()／shop.set_shop_pool()	level_shop_economy_test.gd:_smoke_gp_wallet；level_shop_economy_test.gd:_smoke_shop_room；level_shop_economy_test.gd:_smoke_shop_pool；level_shop_economy_test.gd:_test_spend_discount_from_rule_key
货架位数读表（进店与重抽同源）	商店	ShopSession.shop_shelf()（货架构建与重抽同源面）	level_shop_economy_test.gd:_test_shelf_size_from_table
元进度入账与锻造两轴	元进度×锻造工坊	MetaStateStore.apply_adventure_summary()／MetaStateStore.spend_keystone()／MetaStateStore.set_forge_route_level()	meta_progression_forge_test.gd:_meta_pricing_and_buy；meta_progression_forge_test.gd:_smoke_forge_axes
锻造定价与购买闭环（全路线价格梯/多级购买扣款/拒购零副作用）	锻造工坊	ForgeTable.level_price()／MetaProgression.forge_buy_level()	forge_table_test.gd:_test_price_ladder；meta_progression_forge_test.gd:_meta_pricing_and_buy；meta_progression_forge_test.gd:_test_forge_buy_reject
锻造与相邻通道隔离（祝福件购买锻造零变化/默认轴与钥匙解耦/甲型切换双轴可感）	锻造工坊×元进度	MetaProgression.forge_select()／hero_type_axes()／商店购买口	meta_progression_forge_test.gd:_test_blessing_no_forge_leak；meta_progression_forge_test.gd:_test_default_axes_pre_key；meta_progression_forge_test.gd:_test_armor_switch_dual_axes
天赋树购买与六键合成	天赋树	MetaProgression.tree_buy()／MetaStateStore.tree_state()／MetaStateStore.set_tree_level()	meta_progression_forge_test.gd:_smoke_tree；meta_progression_forge_test.gd:_smoke_tree_rules；tree_rules_v11_test.gd:_init；tree_requires_level_test.gd:_init
规则键参数读表（六键参数字典校验与激活侧透传）	天赋树	MetaTreeTable.validate()／EffectEngine.rebuild()／MetaProgression.tree_rules()	tree_rules_v11_test.gd:_test_rule_key_params
秘宝结构冻结与 12 件效果	秘宝	TreasureItems.add_item()／query_inventory()／validate_use()	treasure_items_test.gd:_init；treasure_effects_test.gd:_init

旅程段五：排雷循环

能力	系统	真实入口	代表用例（文件:函数）
棋盘按参数行出图、数字恒真	棋盘生成	BoardGenerator.generate()	board_generator_test.gd:_test_generate_shape_and_mines；board_generator_test.gd:_test_digits_equal_neighbor_mine_count；board_generator_test.gd:_test_spawn_edge_from_table
出生区边长表单点（布雷域基／R₀ 下限／剃雷域半径全由 spawn_edge 导出）	棋盘生成	BoardGenerator.generate()／BoardGenTable.validate()	board_generator_test.gd:_test_spawn_edge_from_table
同参数同种子逐位复现、异种子不退化	棋盘生成	BoardGenerator.generate()	board_generator_test.gd:_test_same_seed_bit_identical；board_gen_reward_test.gd:_smoke_board_generator
可推理率与清图可达（合法性先于质量分）、重试有界、降级诚实	棋盘生成	BoardGenerator.measure_inferability()／BoardGenerator.is_clearable()	board_generator_test.gd:_test_clearable_and_inferability_selfconsistent；board_generator_test.gd:_test_target_mine_count_single_source；board_gen_reward_test.gd:_smoke_board_generator
装板与开局免费展开（封锁格无资源、计入清图）	排雷玩法	MinesweeperRules.install_board()	minesweeper_rules_test.gd:_test_install_invariants；seal_polarity_test.gd:_smoke_resource_surface
挖／封印合法性与可辨拒绝（拒绝零副作用）	排雷玩法	MinesweeperRules.settle_batch()	minesweeper_rules_test.gd:_test_dig_face_rules；minesweeper_rules_test.gd:_test_seal_place；minesweeper_rules_test.gd:_test_reject_out_of_catalog
棋盘揭示预览只读口（零状态写入／与实挖揭示集同口径）	排雷玩法	MinesweeperRules.preview_reveal()	minesweeper_rules_test.gd:_test_preview_reveal_readonly
封印不可逆与挖开封印格放行（兑付改判四情况）	排雷玩法	MinesweeperRules.settle_batch()	seal_polarity_test.gd:_smoke_seal_irreversible_quadrants；minesweeper_rules_test.gd:_test_seal_place
棋盘封印印记呈现	排雷玩法	BoardCellUnit.edge → SealMarkLayer.setup()	seal_mark_params_test.gd:_test_param_values；seal_mark_params_test.gd:_test_fog_gate
AP 扣费、末点耗尽即收轮与战斗收束清零	行动经济	MinesweeperRules.settle_batch()（→ActionEconomy.try_spend()／ActionEconomy.notify_combat_end()）	seal_polarity_test.gd:_smoke_seal_ap_exhausted；round_flow_skill_pool_test.gd:_smoke_full_battle；round_flow_skill_pool_test.gd:_smoke_active_refresh
停手转存储备与轮内刷新（上限／AP 不重置／刷新图零清图奖励）	行动经济	BattleOrchestrator.player_request_refresh()／MinesweeperRules.settle_batch()	round_flow_skill_pool_test.gd:_smoke_active_refresh；seal_polarity_test.gd:_smoke_refresh_provenance_guard；refresh_feats_test.gd:test_no_feats_baseline
换图系刷新链路与效果词表接线	行动经济×战斗结算×奇物	MinesweeperRules.settle_batch()／BattleOrchestrator.player_request_refresh()	effect_words_t1_test.gd:_init；forge_table_test.gd:_test_effect_kinds_closed；refresh_feats_test.gd:test_board_refresh_fact_only_on_success
换图基座：挖格产 RAP 与刷新折扣	行动经济×奇物	MinesweeperRules.settle_batch()／BattleOrchestrator.player_request_refresh()	refresh_feats_test.gd:test_reserve_on_accepted_dig；refresh_feats_test.gd:test_refresh_discount_gate_and_charge；refresh_feats_test.gd:test_double_base_stack
换图输出：刷新群伤与蓄力攻击	战斗结算×奇物	BattleOrchestrator.player_request_refresh()→轮末 MinesweeperRules.settle_batch(stop)	refresh_feats_test.gd:test_blast_defers_to_combat_segment；refresh_feats_test.gd:test_charge_layers_consumed_same_round；run_time_fatal_test.gd:_init
换图生存：全局固定减伤与轮末恢复	战斗结算×奇物	BattleOrchestrator.player_request_refresh()→敌方攻击／危险格／错误封印／地形真实受伤入口	refresh_feats_test.gd:test_all_hero_damage_paths_emit_once；refresh_feats_test.gd:test_stone_mitigation_all_damage；refresh_feats_test.gd:test_rest_rotation_cap_and_clear
换图资源：刷新固定 GP 收益	战斗结算×奇物	BattleOrchestrator.player_request_refresh()	refresh_feats_test.gd:test_mine_profit_gp
下轮行动点修正排队与兑现	行动经济	ActionEconomy.pending_ap_delta()（排队经 ActionEconomy.queue_ap_delta()，写入方为效果引擎）	seal_polarity_test.gd:_smoke_negative_dictionary；feat_vouchers_test.gd:_init

旅程段六：表现与支撑

能力	系统	真实入口	代表用例（文件:函数）
拒绝反馈分面可辨与未知兜底文案	HUD框架	HudPresenter.outcome_text()	hud_presenter_test.gd:_test_reject_text_by_reason；hud_presenter_test.gd:_test_unknown_reason_fallback；hud_presenter_test.gd:_test_accepted_text
结算明细带逐行呈现与排播节奏	HUD框架	BattleLogView.append_row()／RowPacer.pace_delay_for()	theme_projection_test.gd:_smoke_battle_log_view；player_copy_sweep_test.gd:_sweep_source_names；pacing_queue_test.gd:_init
模态覆盖层编排与输入锁	HUD框架	ModalFlow.locks_input()／ModalFlow.open_after_playback()	modal_flow_test.gd:_init；reward_overlay_test.gd:_run
模态句柄分域寻址面	HUD框架	局内／菜单／营地三子容器句柄经注册面合同寻址（UiRegistry.node() 逐键取层）＋模态编排口开合（ModalFlow.open()／ModalFlow.close()）	ui_struct_probe.gd:_modal_registry_contract（registry 合同序段＋分域句柄段）
未开格类型微光（8 邻作用集／五组色相／零玩法写入）	HUD框架	BoardView.type_glow_probe()／UiKit.glow_group_for_cell_type()	theme_projection_test.gd:_smoke_type_glow；type_glow_test.gd:_test_grouping_closed；type_glow_test.gd:_test_frozen_hue_face
棋盘悬停反馈（三语义光标／目标格边框／路径预览点迹）	HUD框架	ui_input_probe 合成鼠标事件→BoardView._gui_input()；读面 BoardView.hover_probe()	ui_input_probe.gd:_ready（case①到达②禁入③路径预览三语义）
UI 全局主题与按钮五态（含对比度锚）	HUD框架	UiKit.button()／UiKit.primary_button()	theme_projection_test.gd:_smoke_global_theme；theme_projection_test.gd:_smoke_button_five_states；theme_projection_test.gd:_smoke_contrast_inks；palette_token_pairwise_test.gd:_test_pairwise（色板近色纪律存量面）
中文字体随包与字形覆盖	HUD框架	UiKit.load_font()	ui_font_asset_test.gd:_init；theme_projection_test.gd:_smoke_global_theme
地形瓦片套与格面数字可读	HUD框架	TilePalette.digit_ink_mode()／TilePalette.normalize_floor_luma()	terrain_tile_sets_test.gd:_test_set_completeness；terrain_tile_sets_test.gd:_test_hue_domains；terrain_tile_sets_test.gd:_test_digit_ink_modes
站桩敌人呈现与结算演出落点	战斗表现	BattleStageView.enemy_standee_center()／BattleEndOverlay.open_victory()	standee_fx_sweep_test.gd:_init；pacing_queue_test.gd:_init
站桩呈现定值与素材绑定	战斗表现	UiKit.load_tex()／StandeeBody.name_line_probe()	standee_present_values_test.gd:_init
站桩显示档与素材分辨率绑定	战斗表现	StandeeBody.portrait_probe()／StandeeMotion.PORTRAIT_DISPLAY_H	standee_present_values_test.gd:_check_display_tier
B 区舞台背景三关变体与连续地面层（按 board_type 选图／地面层高度读布局表／四柱光柱退役）	HUD框架	BattleStageView.set_board_type()	stage_background_test.gd:_test_background_selection；stage_background_test.gd:_test_ground_layer_geometry；stage_background_test.gd:_test_beams_retired
动画帧数规格（待机/攻击/受击；现役单帧形制锚定）	战斗表现	UiKit.load_tex()（TEX_HERO_* 四态件装载链——棋盘站立/行走与舞台三态同源）	animation_frame_spec_test.gd:_test_spec_table；animation_frame_spec_test.gd:_test_current_form
战斗屏三区几何与棋盘格边长（分辨率两档×四档板型）	HUD框架	BoardView.set_cell_area()（D 区可用面积 → 格边长）；读面 BoardView.cell_size	layout_probe.gd:_ready；board_gen_reward_test.gd:_smoke_layout_cell_formula
调参测速批量模拟（逐帧步进与统计读数）	调参测量	TuneSimController.run()（调试浮窗批量模拟入口）	tune_sim_batch_parity_test.gd:_init（配对对拍套件）
sim 驱动循环单点（缺省零变化与策略/日志回调形态）	调参测量	BattleDriver.drive_round()（两参缺省与五参回调两形态）	battle_driver_drive_test.gd:_smoke_drive_round_contract
模拟玩家 0 格连锁算子（经真实闭包，零盲挖语义保持）	调参测量×排雷玩法	AutoPlayer._deduce()（经 perfect_action() 装配链）	auto_player_deduce_test.gd:_smoke_zero_chain_rule
刷新提示文案读表拼接（RAP 不足／轮上限两 toast 零字面量）	HUD框架	Main._on_refresh_confirmed()（两 toast 装配面）＋player_copy_sweep 源扫描	player_copy_sweep_test.gd:_sweep_refresh_toast_no_literals
试玩日志器 ap_per_round 必填注入守卫（未注入拒绝开会话）	表现与支撑	PlaytestLogger.start_session()	playtest_logger_guard_test.gd:_smoke_required_injection
战斗叙述与终局文案（数值带入／胜负互异）	HUD框架	BattleNarrator.battle_end_text()／BattleNarrator.boss_name()	battle_narrator_test.gd:_test_numeric_lines_carry_values；battle_narrator_test.gd:_test_end_text_differs_by_result；battle_narrator_test.gd:_test_boss_name_uses_boss_rowset
玩家面文案与危险格格面字形	HUD框架	BoardView.rebuild()／StatusSlotRow.set_effects()	player_copy_sweep_test.gd:_sweep_board_glyph；player_copy_sweep_test.gd:_sweep_legend；player_copy_sweep_test.gd:_sweep_hero_panel
营地场景图十层铺底与门洞留空呈现	营地场景视图	进入存档→选档→进档→营地场景屏（CampSceneView.setup_layers() 驱动）；单元测试载入 camp_scene_layout.tres	shot_probe.gd:_ready（camp 截图段）；camp_scene_layout_test.gd:_test_layout_hotspot_geometry
营地七物件命中区点选与分界面可达	营地场景视图	七物件命中区 → 合成鼠标事件经 push_input 真点（ProbeUiUtil.push_click_at 热点中心）→ CampSceneView._gui_input()（命中发 object_pressed 信号） → 组合根开界面（2026-11-06 真输入化，残险登记撤）	ui_click_probe.gd:_ready（七物件合成点击段——真输入驱动）
营地大门两分支确认与断点续玩接线	营地交互流	大门命中区 → 合成鼠标事件经 push_input 真点（ProbeUiUtil.push_click_at）→ ConfirmDialog 真钮（三出口）→ main._on_confirm_accepted()（新冒险确认）／main._resume_from_menu()（断点续玩）	ui_click_probe.gd:_ready（大门两分支段／断点确认段——真输入 push_click 驱动，2026-11-05 真输入化）；presentation_encapsulation_sweep_test.gd:_init（迭代52卡③组合根交接面结构性主证——pres封装 V1–V4 四组私取零命中＋新公开面正锚，2026-11-05 补链锚）
四柜台拆解后五界面入口改挂与写口零回归	营地五界面	五界面意图信号 → CampShopPresenter → MetaProgression.tree_buy() 写口	forge_workbench_test.gd:_run（承载类同迁断言十二项）；ui_click_probe.gd:_ready（写口链段）
营地篝火回主菜单与笔记本改挂动线	营地交互流	笔记本命中区真点（push_click_at）→ CareerOverlay.open()；篝火命中区真点 → ConfirmDialog 真钮二次确认 → 主菜单（2026-11-06 真输入化）	ui_struct_probe.gd:_ready（career 段）；screen_flow_probe.gd:_ready（篝火／开合段——真输入驱动）
确认弹窗按钮位次与语义同钉	HUD框架	ConfirmDialog.open()／ConfirmDialog.open_three() 开态读按钮行子节点序（定值＝推进钮在左／次推进居中／维持钮在右，四处共用件同一序）；探针在弹窗开态取按钮行 child(0) 的全局矩形中心经 ProbeUiUtil.push_click_at 真点	confirm_dialog_test.gd:_test_two_button_row_order；confirm_dialog_test.gd:_test_three_button_row_order；ui_click_probe.gd:_ready（大门无断点段推进钮坐标真点）
营地顶栏栏体定值与落座	营地场景视图	真实工程 boot 后经装配链 MainUiBuild→CampSceneView.set_hud_band() 读 ui.modals.camp.scene.hud_band（定值＝CAMP_HUD_BAND×α0.80、48px 全宽浮层、徽章右位顶格）；单元经 camp_scene_layout_table.gd 的 hud_band_h 出口读背景贴图落位带像素算对比 ≥3:1	camp_scene_layout_test.gd:_test_hud_band_contrast_over_bg（对比度算式，几何五钉定值承载＝系统测试宿主 _smoke_camp_hud_band）
关卡画面视口跟随	关卡画面（选路枢纽）	停点切换与兑付回图经真实屏流程；读面 LevelMapViewport.viewport_center_canvas_pos()	level_map_viewport_probe.gd:_probe_follow_anchor；level_map_viewport_probe.gd:_probe_smooth_scroll_reduced_motion
关卡画面视口平移	关卡画面（选路枢纽）	合成拖拽沿与滚轮沿经 push_input（ProbeUiUtil.push_drag_at()／push_wheel_at()）	level_map_viewport_probe.gd:_probe_drag_pan；level_map_viewport_probe.gd:_probe_wheel_pan；level_map_viewport_probe.gd:_probe_clamp_bounds_and_columns；level_map_viewport_probe.gd:_probe_drag_no_submit
关卡画面视口指引	关卡画面（选路枢纽）	深图经 LevelMapScreen.open_choices() 真实停点	level_map_viewport_probe.gd:_probe_guidance_chrome
营地图鉴占位挂起态与反参照结构纪律	营地场景视图	布告板命中区真点（push_click_at）→ CampSceneView._gui_input()（object_pressed 信号） → 图鉴占位视图；营地根态场景树审计（2026-11-06 真输入化）	ui_struct_probe.gd:_ready（占位禁词／禁行段）；ui_struct_probe.gd:_ready（结构禁词段）
营地刷新单口与场景根 HUD 同步	营地刷新总线	写口尾 → CampRefreshBus.refresh() → 现开界面刷新＋场景根 HUD 刷新	ui_struct_probe.gd:_ready（顶栏位段）；ui_click_probe.gd:_ready（写口尾刷新段）
Esc 浮窗唤起与三出口动线	营地 Esc 流	营地场景根态合成 Esc 键事件→ main_esc_flow.on_esc_input() → ui.flow.open/close；浮窗三钮 pressed → 三出口	screen_flow_probe.gd:_ready（Esc 唤起／子界面开态不唤起／再按关窗／非营地不唤起段）；screen_flow_probe.gd:_ready（返回动线／设置双路径段）
减动效开关存储契约（持久化回读/缺省值/引擎动效档应用）	设置与本地化	SettingsStore.load_settings()／save_settings()／apply()	settings_store_test.gd:_test_settings_roundtrip；settings_store_test.gd:_test_settings_default；settings_store_test.gd:_test_settings_apply_chain
营地顶栏 HUD 钥石读数与刷新单口同步	营地 HUD 栏	隔离存档实例 meta_state._add_keystone()→ 显式触发 CampRefreshBus.refresh(camp_data) → camp_hud_band.refresh() → keystone_badge 读数	screen_flow_probe.gd:_ready（HUD 余额读数／刷新段）；ui_struct_probe.gd:_ready（顶栏位结构段）
营地五窗统一窗壳形态	营地五界面	七物件命中区/笔记本真点（push_click_at，2026-11-06 真输入化）→ CampSceneView._gui_input()（object_pressed 信号）→ 组合根分派开窗；窗板几何（居中定尺寸 720×640 起点）/遮罩/窗内滚动面为呈现提交面	screen_flow_probe.gd:_step_camp_window_shell（窗壳形态段）
终局结算框关闭动线零引擎报错	战斗表现	fx_probe／screen_flow_probe 真实败走关闭动线（BattleEndOverlay.open_defeat() → BattleEndOverlay.close()）孤立直跑，日志零报错行读数	fx_probe.gd:_ready（计划测试——需求卡片「QA harness 缺陷与覆盖遗漏收口批」2026-11-06 锚定）
停手钮真输入命中与停手收轮落效	行动经济	ui_click_probe 使能窗真输入点击（AP 条停手钮经 ProbeUiUtil.push_click()）＋journey_player 全线跑批（sim）	ui_click_probe.gd:_stoptest_tick（计划测试——需求卡片「QA harness 缺陷与覆盖遗漏收口批」2026-11-06 锚定）
停点链与控件级真输入命中	HUD框架	探针与测试宿主真输入驱动（节点继续／三选一选卡·确认／弃图刷新确认／奖励刷新／地图候选矩形中心／调试浮窗钮，一律经 ProbeUiUtil.push_click()／push_click_at() 进 push_input）	ui_click_probe.gd:_ready（停点链段——计划测试，需求卡片「QA harness 缺陷与覆盖遗漏收口批」2026-11-06 锚定）

旅程段七：数据配置与跨系统契约

能力	系统	真实入口	代表用例（文件:函数）
全表装载、就绪态与表清单目录对账	数据配置	ConfigDB.load_tables()／ConfigDB.diagnostics_count()	config_db_test.gd:_test_manifest_dir_sync；rng_stream_boot_test.gd:_smoke_initialize
进度坐标查行：精确命中／向上取整／封顶／警告去重	数据配置	BoardGenTable.resolve_row()／ConfigDbResolver.resolve_enemy_rowset()	config_db_test.gd:_test_progress_resolution；config_db_resolver_test.gd:_test_band_hit；config_db_resolver_test.gd:_test_top_band_clamp
行集寻址、行序保序与难度乘数 clamp	数据配置×难度曲线与Boss	ConfigDbResolver.resolve_enemy_rowset()／ConfigDbResolver.resolve_difficulty_modifiers()	config_db_resolver_test.gd:_test_rowset_order_preserved；config_db_resolver_test.gd:_test_row_kind_routing；config_db_resolver_test.gd:_test_difficulty_clamp
运行期越域致命与进程非 0 退出	数据配置	BoardGenTable.resolve_row()／ConfigDbResolver.resolve_enemy_rowset()	config_db_fatal_oob_test.gd:_trigger_oob；config_db_resolver_test.gd:_test_request_oob
加载期违规表拒绝：跨表悬空／计数器前缀／真视窄域／效果类型出域	数据配置×秘宝×奇物	ConfigDB.load_tables()	reward_dangling_treasure_test.gd:_init；counter_prefix_fatal_test.gd:_assert_rejected；treasure_target_violation_test.gd:_init；effect_kind_retired_test.gd:_assert_rejected；extended_row_violation_test.gd:_init
表结构守卫：域校验／行序键／跨字段互锁／配额锚	数据配置×敌人系统×地形变异×冒险结构	EnemyTable.validate()／VariationTable.variant_pool()／AdventureTable.validate()	table_structure_guard_test.gd:_smoke_enemy_bands；table_structure_guard_test.gd:_smoke_variation_framework；table_structure_guard_test.gd:_smoke_adventure_table；table_structure_guard_test.gd:_test_feat_cap_required
变异表头域校验（地形变异）	地形变异	VariationTable.validate()	table_structure_guard_test.gd:_test_variation_header_domains
难度修饰套乘：空表零行为／套乘生效／越域 clamp	难度曲线与Boss	UnitContainer.spawn()／ConfigDbResolver.resolve_difficulty_modifiers()	table_structure_guard_test.gd:_smoke_difficulty_table；config_db_resolver_test.gd:_test_difficulty_clamp
Boss 出场门控（每区域恰一 Boss 终点/Boss 节点开战必选 Boss 行集）	难度曲线与Boss	NodeMapGenerator.generate()／BattleOrchestrator.begin_battle()	node_map_generator_test.gd:_test_boss_exit_per_region；boss_gate_test.gd:_test_boss_node_spawns_boss_rowset
锻造表 schema 正反与几何价格梯	锻造工坊	ForgeTable.level_price()／ForgeTable.route_rows()	forge_table_test.gd:_test_production_rows；forge_table_test.gd:_test_price_ladder；forge_table_test.gd:_test_negative_cases
系统间契约词表与受理口径：五配方互异／掷点标签成员性／增益布尔受理	战斗结算×数据配置×增益状态	DamageController.open_ticket()／StatusContainer.apply_effect()	system_contracts_test.gd:_test_damage_controller_vocabularies；system_contracts_test.gd:_test_rng_tag_closure；system_contracts_test.gd:_test_status_boolean_acceptance；source_guard_test.gd:_init
同名状态合并策略（叠加/累加/并存）与剩余次数语义	战斗循环×增益状态	StatusContainer.apply_effect()（编排宿主 begin_battle 链）	roll_multiplier_test.gd:_smoke_armor_roll
状态效果结算链（逐值衰减/到期移除/战斗结束全清/满层拒绝/独立并存/首授快照）	增益状态	StatusContainer.apply_effect()／decay_round()／notify_battle_end()	system_contracts_test.gd:_test_status_decay_and_clear；system_contracts_test.gd:_test_status_stack_full_reject；system_contracts_test.gd:_test_status_independent_branch；system_contracts_test.gd:_test_status_snapshot_first_grant
状态实例按个体归属：个体隔离／全体授予逐体发／死亡即清／同体合并照旧	增益状态	StatusContainer.apply_effect()（个体键）／purge_owner()	system_contracts_test.gd:_test_status_individual_isolation；system_contracts_test.gd:_test_status_grant_all_per_unit；system_contracts_test.gd:_test_status_death_clears；system_contracts_test.gd:_test_status_merge_per_unit
敌方增益自体落点与乘区池按个体	敌人系统×战斗结算×增益状态	技能兑付编排链／DamageController.clamped_pool()	round_flow_skill_pool_test.gd:_smoke_enemy_buff_targets_self；damage_controller_test.gd:_test_pool_consumption_per_unit；damage_controller_test.gd:_test_defender_ac_per_unit；battle_narrator_test.gd:_test_snapshot_effects_per_unit
敌人技能池跨表链接校验	数据配置×敌人系统	ConfigDbCrossValidator.validate_skill_pool_links()	config_db_cross_validator_test.gd:_test_all_links_valid；config_db_cross_validator_test.gd:_test_dangling_skill_id；config_db_cross_validator_test.gd:_test_cast_side_mismatch
精英行：池继承合并、加载期校验与暂不接线	敌人系统×数据配置	ConfigDB.load_tables()／EnemyTable.validate()／EnemyTable.effective_pool()／ConfigDbCrossValidator.validate_skill_pool_links()／EnemyTable.resolve_rowset()	elite_row_test.gd:_test_elite_validation_rejects；elite_row_test.gd:_test_effective_pool_merge；elite_row_test.gd:_test_base_pool_change_propagates；elite_row_test.gd:_test_merged_pool_composition；elite_row_test.gd:_test_elite_unreachable_by_encounter；elite_row_test.gd:_test_production_goblin_elite

覆盖域表（design/gdd/systems/ 逐篇对照——状态三档：已覆盖／部分覆盖／未覆盖；部分与未覆盖行的缺口指待办清单条目，覆盖面提升时同批改本表）：

域	系统文档	能力行	状态	缺口
冒险循环	冒险结构.md	冒险生命周期：开局受理／三关序列／败北线；断点片段往返与续玩幂等；起关／选路／断点重生成同图	已覆盖	—
冒险循环	关卡节点图生成.md	节点图生成合法性与同种子复现；节点图生长递增与无解 fail-fast	已覆盖	—
冒险循环	关卡节点地图.md	起关／选路／断点重生成同图；信息迷雾类型可见性；关卡表消费侧校验与关卡推进	已覆盖	—
冒险循环	奇物.md	专长（奇物）授予与凭证保底；奖励三选一候选／刷新付费／呈现	已覆盖	—
冒险循环	难度曲线与Boss.md	Boss 半血解锁技门控；行集寻址、行序保序与难度乘数 clamp；难度修饰套乘：空表零行为／套乘生效／越域 clamp；Boss 出场门控（每区域恰一 Boss 终点/Boss 节点开战必选 Boss 行集）	部分覆盖	机制面剩余缺口由「断言补齐批」承接；数值落带断言归 M4 数值批；见待办清单「能力清单覆盖缺口补齐」条
战斗循环	地图战斗资源.md	清图奖励双份与零路径；GP 钱包／escrow／商店收口／共享池；封印与极性路由／不可逆	已覆盖	—
战斗循环	增益状态.md	系统间契约词表与受理口径：五配方互异／掷点标签成员性／增益布尔受理；同名状态合并策略（叠加/累加/并存）与剩余次数语义；状态效果结算链（逐值衰减/到期移除/战斗结束全清/满层拒绝/独立并存/首授快照）；状态实例按个体归属：个体隔离／全体授予逐体发／死亡即清／同体合并照旧；敌方增益自体落点与乘区池按个体；封印与极性路由／不可逆	部分覆盖	结算链剩余缺口由「断言补齐批」承接；见待办清单「能力清单覆盖缺口补齐」条
战斗循环	战斗结算.md	伤害公式与掷点乘区；伤害单据编排与回放；轮内流与结算五段全序	已覆盖	—
战斗循环	战斗表现.md	站桩敌人呈现与结算演出落点；站桩呈现定值与素材绑定；站桩显示档与素材分辨率绑定	已覆盖	死亡灰化与减动效演出档以探针＋人工目检为终态（2026-11-02 用户裁除名，不再补自动断言）
战斗循环	敌人系统.md	技能池数据面与回放独立；Boss 半血解锁技门控；敌人技能池跨表链接校验；精英行：池继承合并、加载期校验与暂不接线	部分覆盖	精英行「开战快照拿到合并后池」随接线批验收；见待办清单「战斗节点遭遇编排方式」条
排雷循环	地形变异.md	变异布置门控；表结构守卫：域校验／行序键／跨字段互锁／配额锚	已覆盖	—
排雷循环	排雷玩法.md	装板与开局免费展开（封锁格无资源、计入清图）；挖／封印合法性与可辨拒绝（拒绝零副作用）；封印不可逆与挖开封印格放行（兑付改判四情况）	已覆盖	—
排雷循环	棋盘生成.md	棋盘按参数行出图、数字恒真；同参数同种子逐位复现、异种子不退化；可推理率与清图可达（合法性先于质量分）、重试有界、降级诚实	已覆盖	—
排雷循环	行动经济.md	AP 扣费、末点耗尽即收轮与战斗收束清零；停手转存储备与轮内刷新（上限／AP 不重置／刷新图零清图奖励）；下轮行动点修正排队与兑现	已覆盖	—
表现与支撑	HUD框架.md	拒绝反馈分面可辨与未知兜底文案；结算明细带逐行呈现与排播节奏；模态覆盖层编排与输入锁；未开格类型微光（8 邻作用集／五组色相／零玩法写入）；UI 全局主题与按钮五态（含对比度锚）；中文字体随包与字形覆盖；地形瓦片套与格面数字可读；战斗叙述与终局文案（数值带入／胜负互异）；玩家面文案与危险格格面字形；战斗屏三区几何与棋盘格边长（分辨率两档×四档板型）；B 区舞台背景三关变体与连续地面层（按 board_type 选图／地面层高度读布局表／四柱光柱退役）；模态句柄分域寻址面	已覆盖	—
表现与支撑	存档序列化.md	存档写盘⇄读回往返保真；三槽位隔离与激活失败回滚；槽位摘要窥视与坏槽三态；启动态无激活不写盘；旧档迁移链与断点续玩零跳号；存档⇄RNG 快照往返保真	已覆盖	—
表现与支撑	教学引导.md	—	未覆盖	教学形态与首遇时机待设计；见待办清单「教学形态未定」条
表现与支撑	数据配置.md	全表装载、就绪态与表清单目录对账；进度坐标查行：精确命中／向上取整／封顶／警告去重；运行期越域致命与进程非 0 退出；加载期违规表拒绝：跨表悬空／计数器前缀／真视窄域；表结构守卫：域校验／行序键／跨字段互锁／配额锚	已覆盖	—
表现与支撑	设置与本地化.md	减动效开关存储契约（持久化回读/缺省值/引擎动效档应用）	已覆盖	存储契约三断言已落地；多语言切换面未建（P1，归设置与本地化待设计问题清单）
表现与支撑	音频.md	—	未覆盖	MVP 无音频（P1 后置，无断言面）；见待办清单「能力清单覆盖缺口补齐」条
跨局循环	元进度.md	元进度入账与锻造两轴	已覆盖	—
跨局循环	天赋树.md	天赋树购买与六键合成	已覆盖	—
跨局循环	生涯.md	—	未覆盖	P6 后置未实装；见待办清单「「生涯」界面——冒险中数据回看的唯一承接处」条
跨局循环	秘宝.md	秘宝结构冻结与 12 件效果；加载期违规表拒绝：跨表悬空／计数器前缀／真视窄域	已覆盖	—
跨局循环	锻造工坊.md	锻造表 schema 正反与几何价格梯；元进度入账与锻造两轴；锻造定价与购买闭环（全路线价格梯/多级购买扣款/拒购零副作用）；锻造与相邻通道隔离（祝福件购买锻造零变化/默认轴与钥匙解耦/甲型切换双轴可感）	部分覆盖	六缺口（全路线价格梯／多级购买扣款／拒购零副作用／祝福件零泄漏／默认值解耦／甲型双轴）由「断言补齐批」承接；见待办清单「能力清单覆盖缺口补齐」条

断言计数双口径

断言计数不写死总数（写死必然漂移），取两种口径并注明语义：

• 运行时口径：系统测试运行器（tools/run_system_test.py）打印的通过项数——循环内断言按执行次数计，随断言面增减浮动，以当次跑测打印为准。
• 静态口径：断言面源码 check( 调用点计数——按源码位置计，一处在循环内即多次执行。

两口径数值不同且各自浮动，禁互相换算或写死。

工具速查（逐件：判什么 / 结果谁判 / 什么时候用）

工具	判什么	结果谁判	什么时候会用它
tools/run_smoke.py（冒烟测试）	这版能否启动、能否加载表、能否进主屏——零逻辑判定	退出码＋脚本错误扫描	开机路径／表加载改动后的快速自检；收口由闸编排
tools/run_system_test.py（系统测试）	真实玩法路径的行为断言面（推理→战斗→结算→进度推进）	退出码＋脚本错误扫描	玩法链路改动的调试期确认
tests/run_all.gd（单元测试）	公式／状态机／契约／跨系统闭环（65 套件 manifest）	退出码＋三硬闸（见下）；每套件子进程带截止时间守护——超时先 taskkill /T 整树回收再判该套件 FAIL、批继续（默认 120s，环境变量 RUN_ALL_SUITE_TIMEOUT_SEC 可覆盖）；连续 3 个套件超时＝红树整批挂死，第 3 个即中止整轮、汇总已见失败与超时清单后非 0 退出（阈值＝可调常量，不连续的超时照旧逐个回收）	新套件单跑调试；逻辑改动的最小单元复跑；开发期选跑——追加 -- --only=<词[,词…]> 只跑路径命中词的套件（零命中＝用法错 exit 2；此形态仅供开发期最窄确认，不产闸回执、不作验收凭据）；闸机关联档选跑——同一过滤机制加 -- --only-source=gates，由 tools/run_all_gates.sh 在 02 闸传入（回执 scope=related，是验收跑批本体）
tools/probe_gate.sh（场景探针，单一形态十件恒跑）	UI 可达性、可见性、状态——真实实例化场景＋真实输入路径	探针自检＋退出码	新增 UI 区域的配套探针直跑与断言复核
tools/render_gate.sh（渲染 golden）	画面基线——截图与基线图逐像素容差比对	golden 比对脚本（依赖 PIL）＋退出码／取证双检／三段探针日志脚本错误扫描（error_scan.py）	主题／素材／排版类改动；窗口化运行，需开显示器
game/tests/static_scan.sh（S 域）	项目纪律＋第三方质量规则：RNG 单点／core 纯度／类型标注／文件头／注释禁词／旧符号残留；S13＝gdstyle 质量规则（重复 load、循环内 await、循环内分配、不可达代码等真缺陷类；基线键＝文件	规则	函数名（类/文件级＝文件
测量件（game/sim/，逐件见下「游离脚本台账」）	期望／分布读数——只给读数，不判对错	人工读 stdout 或配套工具脚本	调参与归因；MC 类一律用户发起（档位表见 sim-data/README.md「MC 采集档位表」）

单件直跑是调试期最窄确认手段，不构成验收——验收只有 tools/run_all_gates.sh 一个入口（判定三硬闸见下「本地闸」节）。

Running Tests

# 冒烟测试——极小启动场景，秒级
python tools/run_smoke.py

# 单元测试——Windows 须用 console 版 exe 取 stdout；工作目录 = game/（含 project.godot 那一层）
godot --headless --script tests/run_all.gd          # 统一入口（本地单元测试闸调用点）
godot --headless --script tests/run_all.gd -- --only=battle_settlement   # 选跑态——只跑路径含该词的套件（开发期最窄确认；零命中＝用法错 exit 2，不产闸回执）
godot --headless --script tests/unit/example_test.gd

# 系统测试——过渡期宿主 smoke_all.gd；分钟级
python tools/run_system_test.py

# 场景探针（UI 探针层）——以探针场景为运行目标，走完整项目引导（autoload 在位）
godot --headless --path . res://probe/<probe>.tscn

# 挂死防护内建于 run_all.gd（引擎无死锁探测，超时靠外部判）：每套件子进程带截止时间——
# 默认 120s，环境变量 RUN_ALL_SUITE_TIMEOUT_SEC 可覆盖；超时先 taskkill /T 整树回收
#（cmd wrapper 连引擎孙进程一起杀，不留孤儿），该套件判 FAIL、批继续——单套件挂死不拖死整闸；
# 连续 3 个套件超时＝红树整批挂死，第 3 个即中止整轮（汇总已见失败与超时清单、退出码非 0），
# 不连续的超时照旧逐个回收；阈值是 run_all.gd 内可调常量

套件 manifest 现况：_suites() 登记 65 条（口径＝manifest 条目数， 随套件增减浮动）——data_config（ConfigDB 加载/进度坐标 ceil 解析/fatal 退出码/统一随机流）、core（秘宝结构冻结/断点续玩/存档槽位/结算五段等）、battle_settlement（DamageMath 纯函数/DamageController 伤害单据五配方）、contracts（系统间接口契约断言）、presentation（节奏队列/奖励浮层/字体资产/地形瓦片集/模态编排等）；跨系统真实路径闭环 3 条同住 tests/unit/（与单机制契约套件同环境同协议，见「测试层级」节分层判据）。致命类独立进程 expect=1；负面套件 negative=true 只豁免错误扫描一闸。期望值一律由表读值推导（零玩法数值字面量）、随机只经 RngService 统一流。

协议要点（D2 冒烟协议）：

• --script 载体 extends SceneTree 以获得 quit(code)；成功 quit(0)、失败 quit(1)
• --script 模式不加载 autoload 且不注册全局标识符（裸引用 ConfigDB = parse error）——ConfigDB/RngService 由脚本显式实例化，core 一律构造注入
• 冒烟测试走项目运行目标（场景拉起），autoload 全在位——与 --script 载体互补
• 致命类用例独立进程，runner manifest 登记"调用 → 期望退出码"
• 每用例先 reset_diagnostics()（诊断收集器协议）
• 期望值由表读值推导，不写死玩法数值

Test Naming

• Files: [system]_[feature]_test.gd（领域命名，禁 ID 前缀——design/engineering/code-conventions.md）
• Functions: test_[scenario]_[expected]
• Example: reward_roll_test.gd → test_power_interval_rolls_within_bounds()

Story Type → Test Evidence

Story Type	Required Evidence	Location
Logic	Automated unit test — must pass	tests/unit/[system]/
Integration	跨系统闭环套件 OR playtest doc	落地批当场入 tests/unit/（跨系统真实路径闭环套件，章程见「测试层级」节）
Visual/Feel	Screenshot + lead sign-off	tests/evidence/
UI	Manual walkthrough OR interaction test（场景探针为首选）	tests/evidence/
Config/Data	Smoke test pass	跑批回执 game/tests/.gates/receipt.json（不入库）＋结论随批记 reports/

game/probe/ 游离脚本台账

game/probe/ 里的脚本两分：在闸件（探针有 .tscn 宿主、被 probe_gate.sh／render_gate.sh 调用； smoke_all.gd 被系统测试运行器调用——过渡期宿主）与不入闸的手动测量/诊断件（下表）。 判据 = 头注自陈用途 + 有无外部引用（工具脚本/产品码/文档）。存疑一律按在役登记并标注（不退役）。

脚本	定性	用途与触发方式	结果由谁判
adventure_monte_carlo.gd	在役（AGENTS.md 在册入口）	全冒险期望 MC	人工读 stdout
verifier_batch.gd	在役（AGENTS.md 在册入口）	tools/balance_verifier.py 的采集端（数值验证）	报告与原始数据落 sim-data/
reward_expectation.gd	在役（AGENTS.md 在册入口）	奖励期望测量（非封锁格分布/资源类型频次）	人工读 stdout
monte_carlo.gd	在役	战斗期望 MC（胜轮数/承伤/清图/开格分布）	人工读 stdout
auto_player.gd	在役（库件）	自动玩家策略单一实现——被 battle_driver preload	宿主脚本
battle_driver.gd	在役（库件）	战斗驱动；被 damage_probe preload	宿主脚本
level_autoplay.gd	在役（库件）	被 presentation/tune_sim_controller.gd load	宿主脚本
probe_ui_util.gd	在役（库件）	探针公共工具（存档隔离/句柄解析）——被各探针 preload	宿主探针
board_stat_probe.gd	在役	tools/clear_dominance_audit.py 的取数端	工具脚本
calibrate_boards.gd	在役	生成器真值分母；sim-data/analyze.py 引用	工具脚本
damage_probe.gd	在役（诊断件）	零承伤根因分割探针（头注自陈：非验收件·不入闸）	人工读 stdout
defense_scan.gd	在役（诊断件）	AC 叠层减伤读数分割（高 AC 轮 vs 基线轮）	人工读 stdout
skill_rhythm_probe.gd	在役（分析工具）	技能池节奏定位（表侧池快照 + 摇号份额）	人工读 stdout
rhythm_batch.gd	在役（批量采集）	技能池节奏批量读数（06 在册项的机器半边）	人工/工具
dump_battle.gd	在役·一次性	打印一场完整战斗的步骤流与棋盘摘要（肉眼验收归因质量）	人工（用完即止）

纪律：本表是这些件的唯一在册处。新增手动测量脚本必须同批登记（用途 + 触发方式 + 结果由谁判）； 退役走 design/engineering/doc-conventions.md 第 10 节退役规则，禁止「没看见＝死件」式清理。 测量类批量的发起规则（档位与批准）见 sim-data/README.md「MC 采集档位表」——无数值改动禁重跑。

Static Scan（提交前本地跑）

tests/static_scan.sh 实现静态扫描域 S1–S12 的可执行子集；S1–S10 的规则全集与动机见 design/engineering/architecture/architecture.md「测试与质量域」节，S11／S12 两段的规则说明自持于本文件与 tests/static_scan.sh 头注，这两段不另进架构文档。 新违规案例必须先补扫描规则再修码。

S11 代码注释禁用词：扫描 game/ 全域 .gd/.tres/.md/.json/.sh 的注释面；禁词全部由 design/gdd/术语表.md「退役词对照」第一列解析供给（脚本内不内联任何词面——单一事实源）；解析结果再按「巢穴」「旗」「flag_*」三条整行排除，另设同形异义豁免「去重闸」（封印重判去重的机制判别器，与某闸档退役词后二字同形——行内含「去重闸」整行跳过）；三层豁免（闸门自指／显式留档 20 处〔契约原名引述与带日期历史读数注释，清单见 tests/static_scan.sh 头注〕／非注释面天然不取）；两道自检（扫描面文件数非空＋词表解析非空）。

S12 效果引擎无状态化旧件零残留：扫描 game/ 全域 .gd 与 game/data/tables/*.tres，禁已删符号（counters_export／counters_seed／_reset_tree_limited_counters 等）与带引号的旧计数器 id 字面（引号锚定，不误伤 adv_／round_ 前缀新名）；扫描面文件数为零即判红。

本地闸（唯一验收门禁）

验收＝合回后远端 CI 闸全绿（2026-11-03 用户裁，取代本地的合回验收；游戏码批＝两域全量、02 全套件）；tools/run_all_gates.sh 仍是全部验证闸的唯一入口与唯一清单，本地按改动域选档跑批（--code／--docs／跨两域或改闸件本身＝不带参数全量；代码域 02 按关联档选套件，回执 scope 字段记 full｜related）只服务开发期窄测，不构成验收， 跑完写回执 game/tests/.gates/receipt.json（含 domain 与 scope 字段），合回 master 由 worktree-guard 按 diff 文件性质推域校验回执（game/ 内 .md 归文档域）。 闸清单与域划分（含选闸算法与套件族映射表）的唯一定义处就是那个脚本，本文档不另列清单（清单散落多份文档正是历史漏跑闸的成因）。

判定三硬闸（各闸一律适用，缺一即判定有洞）： ①退出码为唯一权威判据——日志里的 PASS 串只是日志，不作判据； ②脚本错误扫描命中即红——GDScript 的 SCRIPT ERROR / Parse Error 不改进程退出码、 不计失败数，且会静默中断所在函数的剩余断言，只能由外部扫输出（闸件 tools/error_scan.py， 错误标记与 tools/run_smoke.py 同源）； ③断言数为零即红——test_kit.gd 的 finish() 在零断言时返回专用退出码 2（与「断言失败=1」 区分，避免致命类套件的 expect 协议把它当成预期结果放过）。

gdUnit4 维持 deferred：不引入第三方测试框架，本仓库在既有载体（--script 套件＋场景运行目标）内解决。

闸门耗时基线（超时对比依据）

各闸在本机（Windows 基准档）的预期耗时区间与耗时模型。单次跑批实测显著超出区间上限（约 2× 中值）时，先核对环境因素（导入缓存重建、杀毒扫描、显示器休眠）再判性能回归。区间为单机粗测值；闸回执后续若记录实际耗时，以其积累值替换本表。

闸	耗时模型	预期区间	备注
00 冒烟	O(1)——引擎启动一次＋存活检查	~10–20 秒
01 系统测试	O(屏壳装配数 × 断言面规模)	~2–3 分钟	断言计数随面浮动（口径见「断言计数双口径」节）
02 单元	O(套件 manifest 条目数 × 单套件冷启动)	~3–6 分钟	每套件独立子进程；单套件挂死守卫 120 秒
03 场景探针	O(探针段数 × 引擎冷启动)	~3–5 分钟（--full／--click 各计一次）	耗时大头＝每段一次引擎冷启动
05 渲染	O(截图段数 × 窗口化冷启动 ＋ golden 比对)	~8–15 分钟	五段串行，需显示器在位
远端 CI 全量	上列各闸串联（两域全量）	~30–35 分钟	2026-11-04 远端 run 实测 ≈33 分钟（单点样本）

术语（本项目内的唯一语义）

标准测试层（2026-10-22 用户裁立；2026-11-07 用户裁层级合并——跨系统真实路径闭环套件归单元层，识别三元组见 test-conventions「测试层三元组」节；权威对照=design/gdd/术语表.md「退役词对照」）：

词	语义	载体
冒烟测试	秒级存活检查——能否启动、能否加载表、能否进主屏。判断「这版还活着吗」，不判断「这版对不对」	tests/smoke_boot.tscn/.gd、tools/run_smoke.py
单元测试	受控裸环境断言面（不加载开机装配、手工构造注入实跑，逐套件独立进程）——单机制契约与跨系统真实路径闭环（存档⇄RNG 往返、回放确定性等）都在内	game/tests/unit/、run_all.gd
系统测试	启动真实工程走真实玩法路径的断言面	tests/system_test.gd＋tools/run_system_test.py
场景探针	以探针场景为运行目标、走完整项目引导（autoload 在位）的 UI/场景断言	game/probe/*.tscn、probe_gate.sh
渲染 golden	窗口化截图与基线图的逐像素容差比对	render_gate.sh、tests/golden/