docs(提案): 测试术语与层级重构方案落盘——名实分离/频率冲突/金字塔倒挂证据与行号、2026-10-22 Q1–Q5 裁决记录、标准四级测试架构（冒烟/单元/集成/系统＋UI 探针）、三条频率规则、批A批B执行方案与闸键映射、四项待裁点（批B载体/冒烟判据/探针目录新名/过渡态）待用户安排

reports/提案-测试术语与层级重构方案-2026-10-22.md

@@ -0,0 +1,99 @@
+# 测试术语与层级重构方案
+
+> 状态：提案（设计讨论段过程稿）· 2026-10-22 · 用户已裁 Q1–Q5，待安排执行
+> 死期：结论落进权威文档后即删（吸收即死，doc-conventions §11；删它不需要再裁）
+> 本文档是后续改动的合同与账本骨架；终态规则只进权威文档，本文只记「怎么改过去」
+
+## 一、背景与问题（证据附行号）
+
+**① 名实分离**：`game/tests/README.md:137–148` 术语表定义冒烟＝秒级存活检查（能否启动、能否加载表、能否进主屏），但名叫 smoke 的载体 `tools/run_smoke.py` 跑的是 `res://smoke/smoke_all.gd`——7151 行、140 个函数、1211 项检查、90–110 秒（2026-10-22 实测）。它断言的是逻辑正确性：随机数流具体数值（`derive_at(0)==8672514112661456564`，:53–60）、格子尺寸公式（:1691）、奖励恒等式（`_smoke_reward_identity_unit`，:1977）、封印耗尽行动点进第 2 轮（:2027）。README:146–148 靠一段「别被字面骗了」的警告维持名实分离——需要警告才能防误读的命名，就是失败的命名。
+
+**② 频率三处冲突**：迭代技能写每轮跑 `run_smoke.py`＋`probe_gate.sh`；`roadmap.md` 批次 loop 规范第 4 条写每轮跑 `--quick`；`process-conventions.md` §3 第 5 条写 T0 开工三查含冒烟全绿数目。而 `--quick` 档内含 01（冒烟全量）与 02（单元）两道分钟级闸——「每轮轻闸」实际是每轮全量。一次 2 卡×3 轮的迭代，分钟级套件要跑 6–8 次。
+
+**③ 金字塔倒挂**：按标准测试层级，单元测试应最多（每个函数细节有对应单测），系统测试按功能面组织、相对最少。现状：单元测试 39 套 367 项，系统级杂烩 1211 项，本该承接跨系统用例的 `tests/integration/` 只有 1 件。成因是历史：`run_smoke.py` 是历届迭代每轮必跑的闸，哪个文件被跑得最勤，验收断言就往哪个文件堆；`unit/` 目录成型晚，早期断言一直没搬。证据在函数名里：`_smoke_reward_identity_unit`（名字自带 unit）、`_smoke_layout_cell_formula`（纯公式验算）、`_smoke_adventure_table`（表结构校验）。
+
+**④ 词汇自造**：讨论过程中出现「系统级断言套件」「单元套件」「启动探针」「L0–L3」「轻闸/重闸」等自造词，与通用工程用语不符。
+
+## 二、用户裁决记录（2026-10-22）
+
+早前三项：① 系统级断言面只在批末质量门跑一次；② 新增专用秒级冒烟测试作为「冒烟」这个名字的实体；③ 正名到文档文本＋工具文件名＋日志输出行。
+
+当日 Q1–Q5 答复（覆盖前述冲突处，以此为准）：
+
+- **Q1**：T0 检出工作区零测试。master 经合回闸保证可用，谁检出谁直接开工，不重复验证。三查整条删除。
+- **Q2**：那个实体不叫探针，它的标准名字就是冒烟测试，一词一义，不再造第二个词。
+- **Q3**：卡内只测自己改的东西，没改的不测。全量测试只有两个时机：迭代批次结束＋合回 master。
+- **Q4**：`smoke_all.gd` 同属命名错位，按层级重构方案拆解。**此答复覆盖裁决③中「smoke_all.gd 文件名与 `game/smoke/` 目录名保留不动」一条**——拆空后删文件，目录随内容改名。
+- **Q5**：命名用标准工程用语，名称定为**系统测试**；废弃一切自造词，本会话词汇已逐个对权威出处自查（见 §三）。
+
+## 三、词汇修正对照
+
+| 处置 | 词 | 依据 |
+|---|---|---|
+| 保留 | 冒烟测试（smoke test） | Wikipedia／微软构建验证测试口径 |
+| 保留 | 单元测试、集成测试、系统测试、验收测试 | 软件工程标准测试层级（ISTQB 及通用教材） |
+| 保留 | 回归测试、质量门（gate）、探针（probe）、golden 基线 | CI 通用；k8s liveness/readiness probe；golden master |
+| 废弃→系统测试 | 系统级断言套件、冒烟全量 | 自造词 |
+| 废弃→单元测试 | 单元套件 | 「套件」单独成词拗口且非必要 |
+| 废弃→冒烟测试 | 启动探针、秒级冒烟探针、L0–L3 | 自造词；那东西的标准名就是冒烟测试 |
+| 废弃→消灭 | 轻闸、重闸、三查 | 随新频率规则失去指称对象（见 §五） |
+
+## 四、目标架构
+
+| 层级 | 载体 | 职责 | 规模 | 单次耗时 |
+|---|---|---|---|---|
+| 冒烟测试 | `tools/run_smoke.py`（名字改配给新冒烟）＋ 新文件 `game/tests/smoke_test.gd` | 这版活着吗：启动、载表、进主屏，零逻辑判定 | 新建 10–20 项 | 10–15 秒 |
+| 单元测试 | `game/tests/unit/`（现役不动）＋ 迁入 | 函数/公式/状态机，隔离断言 | 现役 39 套 367 项＋迁入 | 76 秒 |
+| 集成测试 | `game/tests/integration/`（现役不动）＋ 迁入 | 跨系统：存档⇄RNG 往返、回放确定性 | 现役 1 件＋迁入 | 秒级 |
+| 系统测试 | 新 `tools/run_system_test.py` ＋ 系统测试宿主 | 启动真实工程走真实玩法路径 | smoke_all 拆余部分 | 拆后变短 |
+| UI 探针＋渲染 golden | `probe_gate.sh`、`render_gate.sh`（名字含标准词，不动） | 真实 UI 走查（含模拟点击）、画面基线 | 14 个探针场景 | 现状不变 |
+
+关键命名决定：`run_smoke.py` 这个名字不废弃，改配给新冒烟测试——名字与内容终于一致；旧杂烩搬空后 `smoke_all.gd` 删除，`game/smoke/` 目录只剩探针场景，改名 `game/probe/`。
+
+## 五、频率规则（三条，无例外）
+
+1. **检出工作区：零测试**。建 worktree、拷素材与导入缓存、`git status` 归属核对，然后直接开工。
+2. **卡内：只测自己改的东西**。本卡新增/改动的验收测试自己跑绿即收口；没改的东西不测。既有「验收测试随卡落地」「调试期只重跑红件最小单元」两条纪律与此一致，保留。
+3. **全量只有两个时机：迭代批次结束＋合回 master**。跑 `tools/run_all_gates.sh` 按改动域选档，回执机制不变。
+
+「轻闸/重闸」两个词随第三条失去对象，从全部文档消失。
+
+## 六、执行方案（一个设计，两批落地，批 B 依赖批 A）
+
+### 批 A：命名＋频率＋新冒烟测试（估半天到一天）
+
+- 工具：重写 `tools/run_smoke.py`（跑新冒烟）；新建 `tools/run_system_test.py`（过渡期暂指向现有 `smoke_all.gd`）；新建 `game/tests/smoke_test.gd`。
+- 闸机 `run_all_gates.sh` 闸键映射（其余 11 键不动，零 churn）：
+
+| 旧键 | 新键 | 说明 |
+|---|---|---|
+| 01 冒烟全量 | 01 系统测试 | 同一道闸换内容指向 |
+| （新增） | 01a 冒烟测试 | 秒级，排最前 |
+| 02 单元套件 | 02 单元测试 | 仅改名 |
+
+- `baseline.json` 同步改键，照 08c 先例人工确认一次（全部闸现绿，重生成低风险）。
+- 文档与规则：`AGENTS.md`（单件直跑行、验收行）、`process-conventions.md`（删三查、删轻闸重闸表述、§3.4 环境准备保留）、`roadmap.md` loop 规范第 2/3/4 条、`game/tests/README.md`（术语表改标准四级；删除「别被字面骗了」警告节——名字对了警告就死了）、`architecture.md` 测试架构节、迭代技能现行两副本（`.workbuddy`＋`.qoder-cn`）改写并覆盖同步过期两副本（`.zcode`→`.qoder`），改技能重启会话生效。
+- 实现期核对项：`tests/run_all.gd` 对 `integration/` 的扫描归属——若已并入 02 一起跑，闸名用「02 单元与集成测试」或增设独立键，按最简处理。
+- 验证：全量域 `tools/run_all_gates.sh`（不带参数，本批混触 game/＋tools/＋文档）跑绿；新冒烟测试变异验证（改坏启动→冒烟红→还原→复绿）；闸机改动按 test-conventions §6 做变异验证。
+
+### 批 B：断言迁移（估 2–4 天）
+
+- `smoke_all.gd` 的 1211 项按性质三向分流：纯逻辑→单元测试；跨系统→集成测试；真实系统路径→新系统测试宿主。
+- 迁移以套为单位：每迁一套，在新宿主做一次变异验证（改坏对应被测件→新宿主红→还原→复绿），不做 1211 次逐条证明——test-conventions §6 的合规读法，按套证明。
+- 拆完删 `smoke_all.gd`，`game/smoke/`→`game/probe/` 连同全部路径引用（`probe_gate.sh`、`error_scan.py`、golden 脚本、闸机注释）。
+- 收益：金字塔摆正（单元最多、系统测试变薄）、失败定位变准、7151 行单文件消失。
+
+### 执行注意事项
+
+- 两批均走独立 worktree；主区禁直改直提。
+- 并行跑闸会假红：`user://save.json` 全 worktree 共用，闸机串行跑。
+- 本批测试执行依据＝用户点名（两入口铁规第二入口）。
+- MC/模拟：无数值改动，零跑。
+- 跨会话记忆文件（`.qoder-cn` memory 的 smoke-terminology 条目）在用户批准本方案后更新为最终裁决。
+
+## 七、待裁点（全案并列，禁代裁）
+
+1. **批 B 开工载体**：案 1＝本方案当合同直接开工（迁移是等价搬移非行为改动，账本＋逐套变异证明即对照表；建议）；案 2＝走正式写卡段（req-card），多一道工序换标准对照表结构。
+2. **新冒烟测试判据面**：引擎能起、autoload 全在位、配置表全载零错、主屏场景实例化、无 SCRIPT ERROR，约 10–20 项。已按最简定，批 A 开工前可推翻。
+3. **探针目录新名**：`game/probe/`。已定，批 B 开工前可推翻。
+4. **过渡态接受**：批 A 落地后到批 B 之间，闸键已叫「01 系统测试」但内容还是未拆的 smoke_all.gd 全量——名字先到位、内容批 B 拆纯。已定可接受，不设临时名。