DKChan
fd6cf968dc
- C1 level_gen_params 逐类负向 11→1（消息带期望/实际与违例明细）；C2 rng_stream_boot 黄金向量 8→1；C3 player_copy 禁词族 3→1、2→1；C4 standee_fx 蓄力判据 4→1；C5 ui_font 字形集 3→1（缺字明细进消息）；C6 forge_workbench 持有行 2→1（两行取谓词并集，轻甲行补两子句，只增不减） - 个案标签字面量全部保留在表内，失败定位不降级；冻结清单不动（对账基准 1587），extract_checks --diff＝消失 33／新增 7，逐条对应删并申报表 - 用户裁决 2026-10-28：六组全批
Test Manual — Dungeon Sweeper（测试工具手册）
Engine: Godot 4.7.2-stable（GDScript 单语言）
Test Framework: 标准四级测试层（冒烟／单元／集成／系统）＋ headless 场景探针与渲染 golden；gdUnit4 deferred（D2 OQ1 关闭形态——本仓库不引第三方测试框架，需求见下「门禁」节）
门禁: 本地闸——tools/run_all_gates.sh（收口唯一验收入口，按改动域选档 --code／--docs，跨两域或改闸件本身不带参数＝全量）。本仓库无远端、无 CI（.github/workflows/ 已删除，不建不留不参考）；闸清单与域划分只在本脚本定义，文档不另列
Setup date: 2026-09-12（2026-09-27 7f24b640 三层收敛：根 tests/ 并入 game/tests/、docs 并入 design/engineering/、production 解散）
参考实现: 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)
integration/ # 集成测试（跨系统闭环——与 unit/ 同一入口同一协议，见下「测试层级」节）
smoke_boot.tscn/.gd # 冒烟测试——极小启动场景（真实开机路径存活检查，闸 00）
system_test.gd # 系统测试宿主薄壳（SceneTree＋构造注入；断言迁移批后承接 smoke_all.gd，闸 01）
smoke/ # critical-paths.md——人工 gate 清单（/smoke-check 读取）
evidence/ # 截图与人工签核记录
run_all.gd # 单元与集成测试统一入口（套件 manifest 协议，D2 AC-2b）
static_scan.sh # 静态扫描域 S1–S12 可执行子集
测试层级（标准四级＋UI 探针）
| 层 | 判什么 | 承载 | 入闸方式 |
|---|---|---|---|
| 冒烟测试 | 这版活着吗——能否启动、能否加载表、能否进主屏。零逻辑判定 | tests/smoke_boot.tscn/.gd（以项目运行目标拉起＝真实开机路径） |
run_smoke.py（闸 00） |
| 单元测试 | 领域类的原子行为对不对（公式/状态机/纯逻辑）——从对外方法进、断言钉对外可观测面（写法判据见 test-conventions §8.2） | tests/unit/ |
run_all.gd manifest（闸 02） |
| 集成测试 | 跨系统的闭环对不对 | tests/integration/ |
同上（与单元测试同一入口、同一协议） |
| 系统测试 | 启动真实工程走真实玩法路径 | 过渡期 game/probe/smoke_all.gd（断言迁移批后＝tests/system_test.gd） |
run_system_test.py（闸 01） |
| UI 探针＋渲染 golden | 跑起来之后 UI 与场景切换对不对；画面基线 | game/probe/*.tscn 探针 |
probe_gate.sh（闸 03/04）、render_gate.sh（闸 05） |
integration/ 已建承载（迭代 29 T3——此前只有章程句无实体，空壳曾于迭代 19 卡① T4 删过一次）。 首个集成用例 =
save_rng_roundtrip_test.gd（存档⇄RNG 快照往返）。章程登记的四类集成用例里， 回放确定性已由tools/parity_anchor.py承担并收编为全量域闸 11 号条件闸件； Core-Core 与 A1×A2 端到端仍随属主批增量登记；各 GDD 登记的 deferral 集成用例以对侧登记为生效条件。分层判据：能不能在
--script模式下不加载 autoload 就验完？能 = 单元测试； 需要两个以上真实系统协同并走落盘/落库 = 集成测试；需要完整项目引导与场景树 = 冒烟／系统／UI 探针。
能力清单 v1（2026-10-28 立——验证与清单体系整改阶段 1 的覆盖索引：一行＝一个玩家或系统可观测的能力，代表用例只给指针、不复制断言细节；原「集成旅程清单」五条跨系统旅程已并入本表。首期覆盖核心四域（29 行）＋跨域条件闸 1 行，共 30 行；其余域按同一形态扩面）：
与验证集清单的关系：
tests/验证集清单.md已于 2026-10-28 整册冻结——不再随断言新增/删除/改判同步，只作阶段 2「存量断言精简」的对账基准（基点b9260138／1587 条），阶段 2 精简完成后删除。覆盖索引职能改由本表承担（维护锚＝test-conventions §8.3）。本表不是闸，不替代改动—验收对照表、体验验证清单与静态纪律；每行的唯一事实源仍是game/tests/下的测试代码。代表用例口径：写
文件:函数，每行 2–3 个；函数内可含Kit.check_quiet静默通道（逐断言提取器口径外，test-conventions §5.2 已备案）——本表以函数为锚，不受该工具局限影响。维护规则（每批收口核对本批受影响行）：本批改到哪个能力，收口时核对该行代表用例可 grep、在本批真实跑批中执行、真实入口未绕过改动点，并把「最后验证批次」刷新为本批回执；新增能力加行，能力退役删行。全表核对频率与抽样规则归阶段 3。首期未覆盖：排雷循环（棋盘生成／排雷玩法／行动经济）、表现与支撑（HUD／主题／字体／地形瓦片／模态）、数据配置与跨系统契约——按同一形态后续扩面。
旅程补录方法：新旅程＝加一行，「系统」列写涉及边界；源＝architecture「API 边界」表＋「数据流」存档/读档路径＋各 GDD 登记的 deferral 集成用例。
「最后验证批次」列记回执 commit；初值
20c13c3a＝2026-10-28 存量断言精简 A+B 首批的全量域闸回执。
旅程段一：开机与存档
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） | 最后验证批次 | 缺口 |
|---|---|---|---|---|---|
| 存档写盘⇄读回往返保真 | 存档序列化 | SaveManagerCore.write_to_disk()／load_from_disk() |
save_manager_domain_test.gd:_smoke_save |
20c13c3a |
— |
| 三槽位隔离与激活失败回滚 | 存档序列化 | 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 |
20c13c3a |
— |
| 槽位摘要窥视与坏槽三态 | 存档序列化 | 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 |
20c13c3a |
— |
| 启动态无激活不写盘 | 存档序列化 | 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 |
20c13c3a |
— |
| 旧档迁移链与断点续玩零跳号（集成） | 存档序列化×冒险结构 | SaveManagerCore.load_from_disk()（内置迁移链）× AdventureRunner.resume_adventure() |
save_rng_roundtrip_test.gd:_test_old_version_save_migrates_and_resumes |
20c13c3a |
— |
| 存档⇄RNG 快照往返保真（集成） | 存档序列化×RNG 服务×冒险结构 | AdventureRunner.start_adventure() → SaveManagerCore.write_to_disk()／load_from_disk() |
save_rng_roundtrip_test.gd:_test_disk_roundtrip_preserves_breakpoint |
20c13c3a |
— |
| 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 |
20c13c3a |
— |
| 断点片段往返与续玩幂等 | 冒险结构×关卡节点地图 | LevelRunner.breakpoint_fragment()／restore_fragment()；AdventureRunner.resume_adventure() |
breakpoint_resume_test.gd:_init |
20c13c3a |
— |
| 跨系统附随面：事件日志落盘与断点附随件（集成） | RNG 服务×存档序列化×冒险结构 | RngServiceCore.new_adventure()（开事件日志会话）；SaveManagerCore.breakpoint_snapshot()（断点附随键） |
cross_system_flow_test.gd:_rng_event_log_session；cross_system_flow_test.gd:_feats_breakpoint_roundtrip |
20c13c3a |
日志面仅此一条会话覆盖 |
旅程段二：冒险开局与选路
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） | 最后验证批次 | 缺口 |
|---|---|---|---|---|---|
| 冒险生命周期：开局受理／三关序列／败北线 | 冒险结构 | AdventureRunner.start_adventure()／continue_to_next_level() |
adventure_feats_test.gd:_smoke_adventure_api；adventure_feats_test.gd:_smoke_adventure |
20c13c3a |
— |
| 专长（奇物）授予与凭证保底 | 奇物 | AdventureRunner.present_node_curio()／feats_held() × 效果引擎兑付 |
adventure_feats_test.gd:_smoke_feats；feat_vouchers_test.gd:_init |
20c13c3a |
— |
| 节点图生成合法性与同种子复现 | 关卡节点图生成 | 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 |
20c13c3a |
— |
| 节点图生长递增与无解 fail-fast | 关卡节点图生成 | NodeMapGenerator.generate()／is_fatal() |
node_map_growth_test.gd:_test_growth；node_map_growth_test.gd:_test_fatal_subprocess |
20c13c3a |
— |
| 起关／选路／断点重生成同图（集成） | 关卡节点地图×关卡节点图生成×冒险结构 | LevelRunner.start_level()／start_level_external()／pick_next_node()；AdventureRunner.resume_adventure() |
node_map_determinism_test.gd:_smoke_generated_map_determinism |
20c13c3a |
— |
| 信息迷雾类型可见性 | 关卡节点地图 | 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 |
20c13c3a |
— |
| 关卡表消费侧校验与关卡推进 | 关卡节点地图×数据配置 | 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 |
20c13c3a |
— |
旅程段三：战斗结算
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） | 最后验证批次 | 缺口 |
|---|---|---|---|---|---|
| 伤害公式与掷点乘区 | 战斗结算 | 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 |
20c13c3a |
— |
| 伤害单据编排与回放 | 战斗结算 | DamageController.submit()／open_ticket()／flush() |
damage_controller_test.gd:_run_recipe_sequence；damage_controller_test.gd:_test_five_recipes_and_replay |
20c13c3a |
— |
| 轮内流与结算五段全序 | 战斗结算 | BattleOrchestrator.begin_battle() |
round_flow_skill_pool_test.gd:_smoke_full_battle；round_flow_skill_pool_test.gd:_smoke_settlement_segments |
20c13c3a |
— |
| 技能池数据面与回放独立 | 敌人系统 | BattleOrchestrator.begin_battle()（技能池抽号／校验） |
round_flow_skill_pool_test.gd:_smoke_skill_pool_data；round_flow_skill_pool_test.gd:_smoke_skill_pool_replay_independence |
20c13c3a |
— |
| Boss 半血解锁技门控 | 敌人系统 | BattleOrchestrator.begin_battle()（Boss 行） |
skill_unlock_test.gd:_test_gate_predicate；skill_unlock_test.gd:_test_latch_irreversible |
20c13c3a |
— |
| 封印与极性路由／不可逆 | 地图战斗资源×战斗结算 | 效果引擎 × 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 |
20c13c3a |
— |
| 变异布置门控 | 地形变异 | BattleOrchestrator.begin_battle()（变异布置段） |
variant_placement_test.gd:_smoke_variant_placement；variant_placement_test.gd:_smoke_global_variant |
20c13c3a |
— |
旅程段四：奖励、经济与局外成长
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） | 最后验证批次 | 缺口 |
|---|---|---|---|---|---|
| 清图奖励双份与零路径 | 地图战斗资源 | BattleOrchestrator.begin_battle() → 步骤流行（source_class=clear_reward） |
seal_polarity_test.gd:_smoke_clear_reward_chain；seal_polarity_test.gd:_smoke_clear_reward_zero_paths |
20c13c3a |
— |
| 奖励三选一候选／刷新付费／呈现 | 奇物×节点奖励屏 | AdventureRunner.present_node_curio()（数据面）；奖励节点覆盖层场景（呈现面） |
curio_refresh_paid_test.gd:_init；reward_overlay_test.gd:_run |
20c13c3a |
— |
| GP 钱包／escrow／商店收口／共享池 | 地图战斗资源×商店 | LevelRunner.buy_product()／player_request_refresh()／close_wallet()／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 |
20c13c3a |
— |
| 元进度入账与锻造两轴 | 元进度×锻造工坊 | SaveManagerCore.add_keystone()／spend_keystone()／set_forge_route_level() |
meta_progression_forge_test.gd:_meta_pricing_and_buy；meta_progression_forge_test.gd:_smoke_forge_axes |
20c13c3a |
— |
| 天赋树购买与六键合成 | 天赋树 | SaveManagerCore.tree_nodes()／set_tree_level() |
meta_progression_forge_test.gd:_smoke_tree；meta_progression_forge_test.gd:_smoke_tree_rules；tree_rules_v11_test.gd:_init |
20c13c3a |
— |
| 秘宝结构冻结与 12 件效果 | 秘宝 | TreasureItems.add_item()／query_inventory()／validate_use() |
treasure_items_test.gd:_init；treasure_effects_test.gd:_init |
20c13c3a |
— |
跨域条件闸
| 能力 | 系统 | 真实入口 | 代表用例 | 最后验证批次 | 缺口 |
|---|---|---|---|---|---|
| 回放确定性（同种子三变体逐位） | 全玩法链 | tools/parity_anchor.py（闸 11 条件闸，按批发起） |
tools/parity_anchor.py（整件为条件闸） |
—（条件闸） | 条件闸未随本批执行 |
断言计数双口径（2026-10-08 迭代 19 卡① T4 订正）
历史 README 写死「752+ 断言/十五套件」必然漂移，改为两种口径并注明语义：
- 运行时口径：系统测试运行器（
tools/run_system_test.py）打印的通过项数——循环内断言按执行次数计，随断言面增减浮动，以当次跑测打印为准。 - 静态口径：断言面源码
check(调用点计数——按源码位置计，一处在循环内即多次执行。
两口径数值不同且各自浮动，禁互相换算或写死。
工具速查（逐件：判什么 / 结果谁判 / 什么时候用）
| 工具 | 判什么 | 结果谁判 | 什么时候会用它 |
|---|---|---|---|
tools/run_smoke.py（冒烟测试） |
这版能否启动、能否加载表、能否进主屏——零逻辑判定 | 退出码＋脚本错误扫描 | 开机路径／表加载改动后的快速自检；收口由闸编排 |
tools/run_system_test.py（系统测试） |
真实玩法路径的行为断言面（推理→战斗→结算→进度推进） | 退出码＋脚本错误扫描 | 玩法链路改动的调试期确认 |
tests/run_all.gd（单元与集成） |
公式／状态机／契约／跨系统闭环（64 套件 manifest） | 退出码＋三硬闸（见下）；每套件子进程带截止时间守护——超时先 taskkill /T 整树回收再判该套件 FAIL、批继续（默认 120s，环境变量 RUN_ALL_SUITE_TIMEOUT_SEC 可覆盖） |
新套件单跑调试；逻辑改动的最小单元复跑；开发期选跑——追加 -- --only=<词[,词…]> 只跑路径命中词的套件（零命中＝用法错 exit 2；选跑态仅供开发期最窄确认，不产闸回执、不作验收凭据） |
tools/probe_gate.sh（场景探针，--click／--full 两模式） |
UI 可达性、可见性、状态——真实实例化场景＋真实输入路径 | 探针自检＋退出码 | 新增 UI 区域的配套探针直跑与断言复核 |
tools/render_gate.sh（渲染 golden） |
画面基线——截图与基线图逐像素容差比对 | golden 比对脚本（依赖 PIL） | 主题／素材／排版类改动；窗口化运行，需开显示器 |
game/tests/static_scan.sh（S 域） |
项目纪律＋第三方质量规则：RNG 单点／core 纯度／类型标注／文件头／注释禁词／旧符号残留；S13＝gdstyle 质量规则（重复 load、循环内 await、循环内分配、不可达代码等真缺陷类；基线键＝文件 | 规则 | 函数名（类/文件级＝文件 |
tools/parity_anchor.py（回放对拍） |
同种子下三变体逐位确定性 | 工具脚本逐位比对 | 本批触及数值／存档／RNG／结算面时；须用户批准发起 |
测量件（game/sim/，逐件见下「游离脚本台账」） |
期望／分布读数——只给读数，不判对错 | 人工读 stdout 或配套工具脚本 | 调参与归因；MC 类一律用户发起（档位表见 sim-data/README.md「MC 采集档位表」） |
单件直跑是调试期最窄确认手段，不构成验收——验收只有
tools/run_all_gates.sh一个入口（判定三硬闸见下「本地闸」节）。
Running Tests
# 冒烟测试（闸 00）——极小启动场景，秒级
python tools/run_smoke.py
# 单元与集成测试（闸 02）——Windows 须用 console 版 exe 取 stdout；工作目录 = game/（含 project.godot 那一层）
godot --headless --script tests/run_all.gd # 统一入口（本地闸 02 闸调用点）
godot --headless --script tests/run_all.gd -- --only=battle_settlement # 选跑态——只跑路径含该词的套件（开发期最窄确认；零命中＝用法错 exit 2，不产闸回执）
godot --headless --script tests/unit/example_test.gd
# 系统测试（闸 01）——过渡期宿主 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、批继续——单套件挂死不拖死整闸
套件 manifest 现况：
_suites()登记 64 条（61 单元＋3 集成，2026-10-28 实数；口径＝manifest 条目数， 随套件增减浮动）——data_config（ConfigDB 加载/进度坐标 ceil 解析/fatal 退出码/统一随机流）、core（秘宝结构冻结/断点续玩/存档槽位/结算五段等）、battle_settlement（DamageMath 纯函数/DamageController 伤害单据五配方）、contracts（系统间接口契约断言）、presentation（节奏队列/奖励浮层/字体资产/地形瓦片集/模态编排等）；集成 3 条存tests/integration/。致命类独立进程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 | Integration test OR playtest doc | 落地时随批建 tests/integration/[system]/（目录已删空壳，章程见上） |
| 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/ 游离脚本台账（迭代 29 T7 逐个定性）
game/probe/ 里的脚本两分：在闸件（探针有 .tscn 宿主、被 probe_gate.sh／render_gate.sh 调用；
smoke_all.gd 被系统测试运行器调用——过渡期宿主）与不入闸的手动测量/诊断件（下表）。
判据 = 头注自陈用途 + 有无外部引用（工具脚本/产品码/文档）。存疑一律按在役登记并标注（不退役）。
| 脚本 | 定性 | 用途与触发方式 | 结果由谁判 |
|---|---|---|---|
adventure_monte_carlo.gd |
在役（AGENTS.md 在册入口） |
全冒险期望 MC；tools/parity_anchor.py 的比对载体 |
工具脚本逐位比对 |
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 |
在役·一次性 | 打印一场完整战斗的步骤流与棋盘摘要（肉眼验收归因质量） | 人工（用完即止） |
experiment_density.gd |
在役·一次性 | 不同 mine_density 下的推理率/残余挖掘量取数（历史调参用） | 人工（用完即止） |
纪律：本表是这些件的唯一在册处。新增手动测量脚本必须同批登记（用途 + 触发方式 + 结果由谁判）； 退役走
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 头注——迭代 32 两卡是代码实现批，按流水线红线禁写 design/，故这两段未进架构文档。
新违规案例必须先补扫描规则再修码。
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——验收只在本地发生，跑 tools/run_all_gates.sh 是收口唯一入口，按本批改动域选档（--code／--docs／跨两域或改闸件本身＝不带参数全量），
跑完写回执 game/tests/.gates/receipt.json（含 domain 字段），合回 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 套件＋场景运行目标）内解决。
术语（本项目内的唯一语义）
标准四级测试层（2026-10-22 用户裁，权威对照=design/gdd/术语表.md「退役词对照」）：
| 词 | 语义 | 载体 |
|---|---|---|
| 冒烟测试 | 秒级存活检查——能否启动、能否加载表、能否进主屏。判断「这版还活着吗」，不判断「这版对不对」 | tests/smoke_boot.tscn/.gd、tools/run_smoke.py |
| 单元测试 | 隔离的公式/状态机/纯逻辑断言面，逐套件独立进程实跑 | game/tests/unit/、run_all.gd |
| 集成测试 | 跨系统闭环断言面（存档⇄RNG 往返、回放确定性等） | game/tests/integration/、run_all.gd |
| 系统测试 | 启动真实工程走真实玩法路径的断言面 | 过渡期 game/probe/smoke_all.gd＋tools/run_system_test.py；迁移后 tests/system_test.gd |
| 场景探针 | 以探针场景为运行目标、走完整项目引导（autoload 在位）的 UI/场景断言 | game/probe/*.tscn、probe_gate.sh |
| 渲染 golden | 窗口化截图与基线图的逐像素容差比对 | render_gate.sh、tests/golden/ |