docs(card): 需求卡片 v1.1——新增 N7 归因锚判据修正,T2 对外文案改概念驱动两态写法

grilling 复核门查出概念冲突,按用户 2026-10-20 裁定(Q5=A)并入本批:

**新增 §0 概念定义节**:明确「完美封印」=一张图的**清图奖励加倍条件**——
判据=零有效误标 且 至少一次封印标中;有效误标=误标总数 − 豁免数;
成立效果=清图奖励追加第二份同身份兑付;被破之后=只发一份不加倍。
出处:战斗结算.md:161 本体/:108 当量公式/:116 乘数字义/:321 调参表。

**新增 N7(真缺陷)**:`grant_segment.gd:300` 用 RAW 计数
`_perfect_hit_false == 1` 判「已破」,而 `battle_orchestrator.gd:1299`
`perfect_sweep_earned()` 用有效误标;豁免累加(:314)又排在 `_emit_row`
(:302)之后。⇒ 装备「完美保险」时日志打印「已破」,实际加倍照发,
日志断言了与真值相反的状态。修法:判据改 `_perfect_hit_false -
_perfect_forgiven == 1`,豁免累加上移到 `_emit_row` 之前。

**T2 措辞订正**:对外文案不再作机械换词,改为按 §0 概念的两态改写——
未豁免态 `(本图完美封印已破——清图奖励不再加倍)`;
已豁免态 `(首次封印落空已豁免——不计入完美封印判定)`
(后者与 feats.tres:861 desc 口径一致)。
原三候选(机械换词)作废。

**契约增两条**:语义先行禁纯词面替换;完美封印判据单点(只允许由
perfect_sweep_earned() 派生,两处不一致即缺陷)。

**验收清单增 A10/A11**(未豁免态应「已破」、豁免态应无「已破」),
变异验证增两条(N7 判据正/反)。

估时由 ≈6.5–7.5h 上调为 ≈8.5–10.0h,切分预案同步。
流水线闸 PASS:卡片口径 22 张全过。
This commit is contained in:
DKChan committed 2026-10-20 02:04:42 +08:00
1 parent bf5c379b32
commit 8575e1b16c
2 files changed
+158 -60

No files matched your search

+3 -1
View File
@@ -678,7 +678,7 @@
---
#### 代码注释禁用词清扫批——退役词换代+完美排雷统一为完美封印(2026-10-20 登记,来源=会话提及,设计面=工程直入)
#### 代码注释禁用词清扫批——退役词换代+完美封印统一+归因锚判据修正(2026-10-20 登记,来源=会话提及,设计面=工程直入)
**现状**:2026-10-19 全量扫描 `game/`(195 个文件:.gd/.tres/.md/.json/.sh/.txt)的可复核实测读数,口径=剔除含对照性/历史信号的行后计「疑似现行残留」。
**确定违规**(术语表「退役词对照」在册,落于代码注释面)=`板级` 26 处/`门票` 38 处/`正主` 12 处(含 `tests/unit/battle_settlement/damage_math_test.gd:36`「正主角池」误报 1 处)/`落籍` 10 处(含 `data/tables/enemy.tres:653` 带 commit 号的历史注记 1 处,不追改)。
@@ -686,6 +686,8 @@
**根因**:迭代 31 卡① 完成判据 V4 只覆盖「金币/插旗/雷格/惩罚格」四词(+旗族),`排雷`/`雷`族未入完成判据;且机检闸 `tools/doc_term_audit.py` 的 `DEFAULT_DIRS = ["design/gdd"]`,**代码注释面从未进闸**——不清根则同类残留持续复发。
**裁定(2026-10-19 用户)**:完美排雷**全库统一**换代为「完美封印」,含代码内部注释。本裁**推翻** `需求卡片-凭证件裁削批`:108「内部开发用语按 v3.15 纪律保留」半句,该卡片条款订正归**文档轨批**,代码批照本裁执行。
**移交(不属本批)**:`game/data/tables/shop.tres:86` display_name「奇物门票」、`game/presentation/curio_interact_controller.gd:165-166`「开一次奇物三选一」——两处属 奇物/专长 归类表述,与 06「2026-10-18 冒记案遗留待裁两项」第①项同源,交文档侧先定性,定后另走传导批。
**扫描中查出的真缺陷(N7)**:`core/settlement/grant_segment.gd:300` 用 RAW 误标计数判「完美封印已破」,而 `core/battle_orchestrator.gd:1299` 的真正谓词用**有效误标**(总数 − 豁免数);且豁免累加(:314)排在 `_emit_row`(:302)之后。⇒ 装备「完美保险」时日志打印「已破」,实际加倍奖励仍发,日志与真值矛盾。2026-10-20 用户裁=并入本批修(判据改有效误标+豁免上移+文案两态)。
**不做(待用户另裁)**:术语表 A 表词(`不得` 14/`报错` 18/`对标` 1/`若干` 1/`buff` 22——后者绝大多数是标识符与数据键)、doc-conventions 第 4 节流程动词(`收口` 128/`随批` 20/`台账` 17/`对拍` 16/`在飞` 10/`落文` 2)、简明技术中文(STC)通用禁用词(`缺省` 105/`情况` 26/`入参|出参` 23/`比较|较为|相对` 22 等)。
**归属**:game/ 代码与数据表(代码域,走独立 worktree 批;并行避让——`changelog-retire-20261019` 在盘未合回且正在改 `AGENTS.md` 与 `design/dev/code-conventions.md`,本批禁碰这两个文件,S11 规则说明自持于 `game/tests/static_scan.sh` 头注与 `game/tests/README.md`)
@@ -1,38 +1,70 @@
# 需求卡片·代码注释禁用词清扫批(退役词换代+完美排雷统一为完美封印)
# 需求卡片·代码注释禁用词清扫批(退役词换代+完美封印统一+归因锚判据修正)
- **批次名**:代码注释禁用词清扫批
- **日期**:2026-10-20
- **批次性质**:工程债/重构(凭 06 在册条目直接写卡;工程直入四类,无设计前置要求)
- **设计事实源**(唯一事实源:`design/gdd/术语表.md`「退役词对照」+「用语规范 A 表」+「对外命名纪律」节;req-card 三选一之③工程直入证据指认):扫描读数=`game/` 下 195 个文件(.gd/.tres/.md/.json/.sh/.txt)逐处实测,落点带 file:line(见 §2);复现命令见 §2 末。
- **版本**:v1.0
- **批次性质**:工程债/重构 + 缺陷修复(两类均属工程直入四类,凭 06 在册条目与代码级证据直接写卡)
- **设计事实源**(唯一事实源:`design/gdd/术语表.md`「退役词对照」+「用语规范 A 表」+「对外命名纪律」节;`design/gdd/systems/战斗循环/战斗结算.md`「完美排雷」规则节;req-card 三选一之③工程直入证据指认):扫描读数=`game/` 下 195 个文件(.gd/.tres/.md/.json/.sh/.txt)逐处实测,落点带 file:line(见 §2);复现命令见 §2 末。
- **版本**:**v1.1**(2026-10-20:grilling 复核门查出 N7 概念冲突,新增需求点与 T7 卡;T2 的对外文案由「机械换词」改为「按概念两态改写」)
- **迭代归属**:待编入 roadmap 迭代 32(本卡不自行编入;编排归 iter-plan 段)
- **上游依据**:2026-10-19 用户裁——「完美排雷」**全库统一**换代为「完美封印」,含代码内部注释
## 1. 目标与完成定义
---
**目标**:把术语表已在册的退役词从 `game/` 的代码注释里清干净,并把「完美排雷」统一为对外正式名「完美封印」;同时在**代码域自己的静态扫描闸**里补一条规则,让这类残留以后自动见红。
## 0 · 概念定义(动笔前必读,本卡所有措辞以此为准)
**完美封印**(玩家面正式名;机制文档旧称「完美排雷」)= **一张图的清图奖励加倍条件**。
| 项 | 内容 |
|---|---|
| 成立判据 | 一张图「零有效误标」**且**「至少一次封印标中」 |
| 有效误标 | = 误标总数 − 豁免数(迭代 31 卡② T4 落的两账相减口径) |
| 计数纯净 | `_perfect_hit_false` 全程不被任何效果改写;豁免只累加 `_perfect_forgiven` |
| 成立效果 | 清图奖励对象追加**第二份同身份**兑付(乘数 `p_perfect`,现行值读 `settlement.tres`) |
| **被破之后** | 不再满足零有效误标 ⇒ 完美封印不成立 ⇒ **清图奖励只发一份,不加倍** |
| 计数起算 | 从装板起算;换图重置 |
| 高光行 | 成立时发一行;首份即零兑付则高光行不发 |
**出处**:
- 规则本体 — `design/gdd/systems/战斗循环/战斗结算.md:161`
- 当量公式 — 同文件 :108(`完美排雷的清图奖励: E = 奖励表值 × 完美乘数 ÷ 100`)
- 乘数字义 — 同文件 :116
- 调参表 — 同文件 :321(`完美乘数 | percent {100, 200} | 100 为仅高光、无第二份`)
- 清图批 — 同文件 :139;刷新图重置 — :259
- 兑付结构 — `design/gdd/systems/战斗循环/地图战斗资源.md:155`/:194
**玩家面命名纪律**:术语表「对外命名纪律」禁「雷」字面进对外命名,适用范围**含 UI 文案**;该概念的玩家面正式名=「完美封印」,现由 `design/gdd/systems/冒险循环/奇物.md` v3.18 与 `game/data/tables/feats.tres:861` desc 在用。
---
## 1 · 目标与完成定义
**目标**:把术语表已在册的退役词从 `game/` 的代码注释里清干净,把「完美排雷」统一为玩家面正式名「完美封印」,修掉扫描中查出的归因锚判据矛盾;同时在**代码域自己的静态扫描闸**里补一条规则,让这类残留以后自动见红。
| 需求点 | 一句话 |
|---|---|
| **N1** | 「完美排雷」全库统一为「完美封印」(含对外文案 3 处、代码注释 13 处) |
| **N1** | 「完美排雷」全库统一为「完美封印」(对外文案 3 处 / 代码注释与内部文档 13 处) |
| **N2** | 注释里「板级」换代为「整图」 |
| **N3** | 注释里「门票」换代为「专长凭证」(标识符与数据键零改动) |
| **N4** | 注释里「正主」换代为「现行事实源」 |
| **N5** | 注释里「落籍」换代为「已入库」 |
| **N6** | 代码域静态扫描闸新增 S11「代码注释禁用词」规则,先落规则再见红 |
| **N7** | 封印未中行的「完美封印已破」归因锚改用**有效误标**判据,文案按「未豁免/已豁免」两态改写 |
**完成定义**(全部满足才算完):
1. `game/` 内 `完美排雷`/`板级`/`门票`(注释面)/`正主`/`落籍` 五词,**疑似现行计数全部为 0**(豁免=含对照/历史信号的行)。
2. 对外文案三处不含「雷」字面,读作「完美封印」。
3. 冒烟绿数与改前基线一致(现行 1151 项 0 失败)、单元测试 34 套全绿、探针段绿。
4. S11 规则在位:注入一次禁用词 → `game/tests/static_scan.sh` 判红;还原后绿;变异验证记录进实现报告。
5. 代码域闸按域选档跑通,回执 `game/tests/.gates/receipt.json` 的 commit = 分支 tip 且 `all_green=true`。
6. `reports/` 三份产出物写齐(实现报告/代拍板追认单/反哺点清单)。
3. **N7**:装备「完美保险」专长时本战首次标错 → 日志**不**出现「已破」字样,改出现豁免态文案;未装备时首次标错 → 出现「已破」态文案。两态各有正向断言。
4. 冒烟绿数与改前基线一致(现行 1151 项 0 失败)、单元测试 34 套全绿、探针段绿。
5. S11 规则在位:注入一次禁用词 → `game/tests/static_scan.sh` 判红;还原后绿;变异验证记录进实现报告。
6. 代码域闸按域选档跑通,回执 `game/tests/.gates/receipt.json` 的 commit = 分支 tip 且 `all_green=true`。
7. `reports/` 三份产出物写齐(实现报告/代拍板追认单/反哺点清单)。
**文档面不在本卡完成定义内**——迭代批禁写 `design/` 整目录与根规则文件,唯一可写目录=`reports/`(process-conventions §3 第 13 条)。
## 2. 现状事实(2026-10-19 实测,开工自行复核)
---
## 2 · 现状事实(2026-10-19 实测,开工自行复核)
扫描范围:`game/` 下 195 个文件(.gd/.tres/.md/.json/.sh/.txt)。
口径:命中行若含对照性/历史信号(`退役`/`作废`/`换装`/`继任`/`留档`/`历史`/`已删`/`不再`/`禁用`/`禁「`/`字面`/`原「`/`旧称`/`更名`/`换代`/`改为`/`→`/`禁令`/`引举`/`对照`/`豁免`/`待裁`/`已入库`/`登记`/`风味`)则不计入。
@@ -51,11 +83,10 @@
| `presentation/views/board_fx_view.gd` | **102** | **对外文案**(`_show_banner("完美排雷 ×2")`) |
| `presentation/views/settlement_fx_view.gd` | 14 | 注释 |
| `game/README.md` | 146 | 文档正文 |
| `smoke/smoke_all.gd` | 3512、3516、4076、6201 | 注释/断言描述 |
| `smoke/smoke_all.gd` | 3512、3516、4076 | 注释/断言描述 |
| `smoke/smoke_all.gd` | **6201** | **冒烟夹具期望字面量**(断言比对用,非注释) |
| `tests/smoke/critical-paths.md` | 20 | 文档正文 |
注:`battle_log_view.gd:194` 的病句已由 `design/qa/文案审查报告-2026-10-18.md:150` 点名,本批一并修掉。
### N2 · 板级(26 处 / 13 文件)
`core/battle_orchestrator.gd`(67、265、470、482、506、507、928、1213)· `core/board_data.gd`(17、53)· `core/treasure_items.gd`(2、41)· `core/minesweeper_rules.gd`(126)· `data/schemas/variation_table.gd`(20、79)· `presentation/main.gd`(914)· `presentation/treasure_interact_controller.gd`(101)· `presentation/views/board_view.gd`(149、511)· `presentation/views/board_cell_unit.gd`(97)· `presentation/views/hero_info_panel_view.gd`(122、162)· `presentation/views/settlement_fx_view.gd`(146)· `smoke/smoke_all.gd`(2588、2630)· `tests/unit/core/feat_vouchers_test.gd`(174)
@@ -74,22 +105,48 @@
`core/config_db.gd`(22、23、42、45、280、337、390)· `data/tables/enemy.tres:653`(**历史注记**——「已落籍 9cc4b8b」带 commit 号,属留档文本,不追改)· `presentation/views/board_view.gd:35` · `tests/unit/data_config/config_db_test.gd:133`
**已核实清零(迭代 31 成果,本批不重复动)**:`金币`/`插旗`/`标旗`/`雷格`/`惩罚格`/`旗` 在 `game/` 内疑似现行计数**均为 0**。残留 3 处「旗」全在闸门逻辑(`smoke/smoke_all.gd:1319` 禁字面检查)与字形检查夹具(`tests/unit/presentation/ui_font_asset_test.gd:18`/`:19`),属对照性文本。
### N7 · 归因锚判据与概念定义矛盾(真缺陷,本批一并修)
三个落点构成一条矛盾链:
| # | 落点 | 现状 |
|---|---|---|
| 1 | `core/settlement/grant_segment.gd:295` | `oc._perfect_hit_false += 1` —— 累加的是 **RAW 误标总数** |
| 2 | `core/settlement/grant_segment.gd:300-301` | `if oc._perfect_hit_false == 1: hl = "perfect_broken"` —— 判据**只看 RAW 计数** |
| 3 | `core/battle_orchestrator.gd:1298-1299` | `perfect_sweep_earned()` 用的却是**有效误标**=`_perfect_hit_false − _perfect_forgiven <= 0` |
**矛盾实证**:`grant_segment.gd:308-315` 里 `_fx_emit("seal_missed")` 与 `_perfect_forgiven += 1`(:314)都排在 `_emit_row`(:302)**之后**。装备「完美保险」专长时:
- 第 300 行 RAW 计数 `== 1` 成立 ⇒ 打印「完美封印已破」
- 但第 314 行随后把 `_perfect_forgiven` 加到 1 ⇒ 有效误标 = 0 ⇒ `perfect_sweep_earned()` 仍为 **true**,加倍奖励照发
⇒ **日志告诉玩家"加倍没了",实际加倍还在。** 这不是病句,是断言了与真值相反的状态。
引用口径:`奇物.md` v3.18 已改用「完美封印」;`feats.tres:861` desc =「本场首次封印落空,不计入完美封印判定」。
### 已核实清零(迭代 31 成果,本批不重复动)
`金币`/`插旗`/`标旗`/`雷格`/`惩罚格`/`旗` 在 `game/` 内疑似现行计数**均为 0**。残留 3 处「旗」全在闸门逻辑(`smoke/smoke_all.gd:1319` 禁字面检查)与字形检查夹具(`tests/unit/presentation/ui_font_asset_test.gd:18`/`:19`),属对照性文本。
**复现命令**(仓库根):`grep -rn "完美排雷\|板级\|门票\|正主\|落籍" game/ --include=*.gd --include=*.tres --include=*.md --include=*.json --include=*.sh`
## 3. 设计契约(🔴 违反=L3 停机呈报)
---
## 3 · 设计契约(🔴 违反=L3 停机呈报)
1. 🔴 **标识符零改动**——`feat_ticket_*`(`_feat_ticket_pity`/`_feat_ticket_sold`/`_feat_ticket_appeared`/`_redeem_feat_ticket()`/`_pool_ticket`/`feat_ticket_chance`/`feat_ticket_quota`)、`SHELF_KINDS` 的 `"feat_ticket"`、断点存档键 `"feat_ticket_pity"`/`"feat_ticket_sold"`(持久化在 `save.json` 的 `breakpoint.adventure_counters`)**一律不动**。改名会断旧存档与跨文件契约,且上游 `需求卡片-凭证件裁削批`:109 明列「feat_ticket 体系|与本批无关,不碰」。
2. 🔴 **游戏行为零变化**——本批是纯中文文本替换,禁止改动任何逻辑、数值、权重、条件判断。唯一例外=对外文案三处的**文本内容**变更(改前「完美排雷」→改后「完美封印」),这是玩家可见文本变化,须登记实机目检项。
3. 🔴 **对外文案只动三处**——`battle_orchestrator.gd:925`/`board_fx_view.gd:102`/`battle_log_view.gd:194`;其余对外文案(含 `shop.tres:86`、`curio_interact_controller.gd:165-166`)零改动。
4. 🔴 **S11 规则先落、后修码**——先把规则写进 `game/tests/static_scan.sh` 并跑出红,再动注释(code-conventions 缺陷-规范对照表纪律)。
5. 🔴 **S11 词表不内联第二份**——规则脚本从 `design/gdd/术语表.md`(「退役词对照」+「用语规范 A 表」两节)解析词面;禁止在脚本里另抄一份词表(单一事实源红线,ADR 漂移教训同类)。
6. 🔴 **S11 必须带扫描面零命中自检**——先数一遍扫描面文件数,为零即判红(沿 S3 教训:路径写歪时自检一起歪、一起红,不会静默恒绿)。
7. 🔴 **禁碰并行会话在改的文件**——`AGENTS.md` 与 `design/dev/code-conventions.md`(分支 `changelog-retire-20261019` 在盘未合回)。S11 规则说明自持于 `game/tests/static_scan.sh` 头注与 `game/tests/README.md`。
8. 🔴 **对照性文本豁免**——含退役/更名/禁令等信号的行不改写(术语表用语规范 B 类豁免条款)。
2. 🔴 **对外文案只动三处**——`battle_orchestrator.gd:925`/`board_fx_view.gd:102`/`battle_log_view.gd:194`;其余对外文案(含 `shop.tres:86`、`curio_interact_controller.gd:165-166`)零改动。
3. 🔴 **语义先行,禁纯词面替换**(grilling 复核门查出后立)——改写玩家可见文案前,必须先读 §0 概念定义并确认这句在讲什么;机检只能判字面,判不了语义对错。
4. 🔴 **完美封印判据单点**——「是否已破」只允许由 `battle_orchestrator.perfect_sweep_earned()` 的有效误标口径派生,禁在 `grant_segment.gd` 另立 RAW 计数判据;两处口径不一致即为缺陷。
5. 🔴 **游戏行为零变化**(N1–N5、N7 判据修正前)——纯中文文本替换,禁止改动逻辑、数值、权重、条件判断。N7 判据修正是**本批唯一允许的逻辑改动**,其验收为「日志文案与真值一致」,不改奖励兑付结果。
6. 🔴 **S11 规则先落、后修码**——先把规则写进 `game/tests/static_scan.sh` 并跑出红,再动注释(code-conventions 缺陷-规范对照表纪律)。
7. 🔴 **S11 词表不内联第二份**——规则脚本从 `design/gdd/术语表.md`(「退役词对照」+「用语规范 A 表」两节)解析词面;禁止在脚本里另抄一份词表(单一事实源红线,ADR 漂移教训同类)。
8. 🔴 **S11 必须带扫描面零命中自检**——先数一遍扫描面文件数,为零即判红(沿 S3 教训:路径写歪时自检一起歪、一起红,不会静默恒绿)。
9. 🔴 **禁碰并行会话在改的文件**——`AGENTS.md` 与 `design/dev/code-conventions.md`(分支 `changelog-retire-20261019` 在盘未合回)。S11 规则说明自持于 `game/tests/static_scan.sh` 头注与 `game/tests/README.md`。
10. 🔴 **对照性文本豁免**——含退役/更名/禁令等信号的行不改写(术语表用语规范 B 类豁免条款)。
## 4. 范围边界
---
## 4 · 范围边界
**做**:
@@ -98,9 +155,11 @@
3. `game/` 内注释面 `门票`→`专长凭证`(35 处,剔除移交 3 处)
4. `game/` 内注释面 `正主`→`现行事实源`(11 处,剔除误报 1 处)
5. `game/` 内注释面 `落籍`→`已入库`(9 处,剔除历史注记 1 处)
6. 代码域静态扫描闸新增 S11 规则(含零命中自检)
7. `game/README.md`/`game/tests/README.md` 同步
8. 全量冒烟+单元+探针验证,绿数与基线一致
6. `game/` 内 `完美排雷`→`完美封印`(16 处)
7. **N7**:封印未中行归因锚改用有效误标判据,文案按两态改写
8. 代码域静态扫描闸新增 S11 规则(含零命中自检)
9. `game/README.md`/`game/tests/README.md` 同步
10. 全量冒烟+单元+探针验证,绿数与基线一致
**不做**(去向):
@@ -113,13 +172,15 @@
| 术语表 A 表词(不得 14/报错 18/对标 1/若干 1/buff 22) | 待用户另裁;裁入则新立 06 条目与卡片 |
| doc-conventions 第 4 节流程动词(收口 128/随批 20/台账 17/对拍 16/在飞 10/落文 2) | 同上 |
| 简明技术中文(STC)通用禁用词(缺省 105/情况 26/入参·出参 23/比较·较为·相对 22 等) | 同上 |
| 任何游戏逻辑/数值改动 | 禁止(本批纯文本替换) |
| 任何游戏逻辑/数值改动(N7 判据修正除外) | 禁止 |
## 5. 关联文档同步面(必填)
---
## 5 · 关联文档同步面(必填)
| 文档 | 关联点(本批实现会改变它的哪条陈述) | 同步义务 |
|---|---|---|
| `design/gdd/术语表.md`「退役词对照」节 | 「门票→专长凭证」行现指在册,代码侧换代后该行应保留(对照行合法);「完美排雷」未入表,玩家面正式名=「完美封印」应由文档侧登记 | **反哺点** |
| `design/gdd/术语表.md` | 「退役词对照」节有「门票→专长凭证」行,代码侧换代后该对照行应保留(对照行合法);「完美封印」尚未入表,玩家面正式名应由文档侧登记 | **反哺点** |
| `design/gdd/systems/战斗循环/战斗结算.md`(:85/:108/:116/:139/:141/:161/:259/:342) | 全篇称「完美排雷」,与 `奇物.md` v3.18+ 的「完美封印」同名异称 | **反哺点** |
| `design/gdd/systems/战斗循环/地图战斗资源.md`(:155/:194) | 同上 | **反哺点** |
| `design/gdd/systems/冒险循环/难度曲线与Boss.md`(:224/:227/:313) | 同上 | **反哺点** |
@@ -133,7 +194,9 @@
| `game/tests/README.md` | S11 规则说明与扫描面登记 | **本批直改** |
| `game/tests/static_scan.sh` | S11 规则承载 | **本批直改** |
## 6. 任务卡
---
## 6 · 任务卡
### 卡前·文件结构图
@@ -143,9 +206,10 @@
| `game/tests/README.md` | 测试分层与闸口径登记 | 增 S11 说明 |
| `game/README.md` | 切片架构说明 | 措辞换代 |
| `game/core/battle_orchestrator.gd` | 战斗编排器 | 注释+对外文案换代 |
| `game/core/minesweeper_rules.gd` 等 12 个 .gd | 注释承载 | 注释换代 |
| `game/core/settlement/grant_segment.gd` | 授予段 | 注释换代 + **N7 判据修正** |
| `game/core/minesweeper_rules.gd` 等 11 个 .gd | 注释承载 | 注释换代 |
| `game/data/tables/*.tres` | 数据表注释 | 注释换代 |
| `game/smoke/smoke_all.gd` | 冒烟断言 | 注释与断言描述换代 |
| `game/smoke/smoke_all.gd` | 冒烟断言 | 注释、断言描述与夹具期望字面量换代 |
| `game/tests/unit/**` | 单元测试 | 注释与断言描述换代 |
### T0 · 基线记录(≈15 min)
@@ -154,15 +218,17 @@
- [ ] 跑单元测试,记录套数与绿数(现行基线 34 套全绿)
- [ ] 跑 `bash game/tests/static_scan.sh`,记录现行退出码 0
- [ ] 跑 §2 末复现命令,存改前命中清单(五词逐处),作为改后零残留的对照
- [ ] 取证「豁免态下日志仍打印已破」:装 `perfect_insurance` 专长 → 首次标错 → 打印日志行原文
**取用**:无(首卡)。
**产出**:`reports/iter32-实现报告-<日期>.md` 的「改前基线」三数——`baseline_smoke_green:int`/`baseline_unit_suites:int`/`baseline_scan_exit:int`。
**产出**:`reports/iter32-实现报告-<日期>.md` 的「改前基线」四数——`baseline_smoke_green:int`/`baseline_unit_suites:int`/`baseline_scan_exit:int`/`baseline_forgiven_log_line:String`。
### T1 · S11 规则落闸并见红(≈1.0–1.5h)
- [ ] 在 `game/tests/static_scan.sh` 头部注释的第 1–3 行补 S11 一行说明(规则名+权威出处+扫描面)
- [ ] 新增 S11 段:扫描面=`game/` 全域(.gd/.tres/.md/.json),与迭代 31 V4 判据同口径;逐行取注释文本段(`#`/`;` 前缀),剔除含对照/历史信号的行
- [ ] 词表面从 `design/gdd/术语表.md` 解析:取「退役词对照」表第一列全部词面(去括号注)+「用语规范」A 表「禁用」列全部词面
- [ ] 在 `game/tests/static_scan.sh` 头部注释补 S11 一行说明(规则名+权威出处+扫描面)
- [ ] 新增 S11 段:扫描面=`game/` 全域(.gd/.tres/.md/.json),与迭代 31 V4 判据同口径
- [ ] 逐行取注释文本段(`#`/`;` 前缀),剔除含对照/历史信号的行
- [ ] 词表面从 `design/gdd/术语表.md` 解析:「退役词对照」表第一列全部词面(去括号注)+「用语规范」A 表「禁用」列全部词面
- [ ] 规则先数扫描面文件数,为零即 `echo "[static_scan] S11 FAIL: 扫描面为空"` 并 `fail=1`
- [ ] 命中即打印 `file:line + 命中词`,段末 `fail=1`
- [ ] 注入验证:在 `game/core/battle_orchestrator.gd` 某注释里临时写回「板级」一词 → 跑 `bash game/tests/static_scan.sh` 见红并记输出摘要 → `git checkout -- game/core/battle_orchestrator.gd` 精确还原 → 记录进实现报告变异验证表
@@ -170,12 +236,14 @@
**取用**:无。
**产出**:`game/tests/static_scan.sh` 的 `S11` 段(退出码语义=任一硬失败规则命中即 `exit 1`,与现役同段同规)。
### T2 · 完美排雷 → 完美封印(≈1.0h)
### T2 · 完美排雷 → 完美封印(≈1.5h)
- [ ] `game/core/battle_orchestrator.gd:925` 行内字符串 `"完美排雷!清图奖励 ×2"` 改为 `"完美封印!清图奖励 ×2"`
- [ ] `game/presentation/views/board_fx_view.gd:102` `_show_banner("完美排雷 ×2")` 改为 `_show_banner("完美封印 ×2")`
- [ ] `game/presentation/views/battle_log_view.gd:194` 病句改写:现 `"(本板完美排雷已破——归因此封印)"` → `"(本图完美封印已破——归因此次封印)"`
- [ ] 其余 13 处(11 处代码注释/文档注释 + 4 处冒烟断言描述文本与夹具期望字面量)逐处换代(清单见 §2 N1 表)
**判据(先立后改,§0 为准)**:这句日志在讲「本图的完美封印资格被这次标错打破 ⇒ 清图奖励不再加倍」。
- [ ] `game/core/battle_orchestrator.gd:925` 行内字符串 `"完美排雷!清图奖励 ×2"` → `"完美封印!清图奖励 ×2"`
- [ ] `game/presentation/views/board_fx_view.gd:102` `_show_banner("完美排雷 ×2")` → `_show_banner("完美封印 ×2")`
- [ ] `game/presentation/views/battle_log_view.gd:194` 按两态改写(见 T7,判据修正后语义才成立;此处只落文本占位,不留「已破」字样在豁免态)
- [ ] 其余 13 处(11 处代码注释/文档注释 + smoke_all.gd:3512/3516/4076 断言描述 + :6201 夹具期望字面量)逐处换代(清单见 §2 N1 表)
- [ ] 跑 §2 末复现命令确认 `完美排雷` 零命中
**取用**:无。
@@ -193,12 +261,12 @@
### T4 · 门票 → 专长凭证(注释面,≈1.0h)
- [ ] `game/core/adventure_runner.gd` 11 处注释换代(67/68/69/477/664/751/771/788/796/1033/1034)
- [ ] `game/core/adventure_runner.gd` 11 处注释换代(67/68/69/477/664/751/788/796/1033/1034)
- [ ] `game/core/level_runner.gd` 4 处(51/781/826/831)
- [ ] `game/data/schemas/adventure_table.gd` 3 处(92/96/97)+ `shop_table.gd:18`
- [ ] `game/data/tables/shop.tres:104` 注释换代
- [ ] `game/presentation/curio_interact_controller.gd` 3 处(89/217/237)+ `curio_pick_overlay.gd:110`
- [ ] `game/smoke/level_autoplay.gd:226`+`smoke_all.gd` 8 处+`tests/**` 2 处换代
- [ ] `smoke/level_autoplay.gd:226`+`smoke_all.gd` 8 处+`tests/**` 2 处换代
- [ ] 复核标识符与数据键零改动(`feat_ticket` 族、`"feat_ticket"` 行族键、存档键)
**取用**:无。
@@ -218,7 +286,17 @@
**取用**:无。
**产出**:`game/` 内「落籍」零命中。
### T7 · 全量验证与产出物落位(≈1.0h)
### T7 · N7 归因锚判据修正(≈1.5h)
- [ ] 把 `core/settlement/grant_segment.gd:300` 的判据由 RAW 计数 `oc._perfect_hit_false == 1` 改为**有效误标**口径 `_perfect_hit_false - _perfect_forgiven == 1`
- [ ] 把豁免累加 `_perfect_forgiven += 1`(:314)上移到 `_emit_row`(:302)**之前**,使归因锚与谓词口径同源
- [ ] 文案两态:未豁免 → `(本图完美封印已破——清图奖励不再加倍)`;已豁免 → `(首次封印落空已豁免——不计入完美封印判定)`
- [ ] 正向断言 A10/A11(见 §7)
**取用**:T2 的对外文案换代结果。
**产出**:日志文案与 `perfect_sweep_earned()` 真值一致(装备专长时豁免态不再出现「已破」)。
### T8 · 全量验证与产出物落位(≈1.0h)
- [ ] 跑代码域档验收(按本批改动域选档),确认所选域全绿
- [ ] 确认回执 `game/tests/.gates/receipt.json` 的 commit = 分支 tip 且 `all_green=true`
@@ -226,28 +304,32 @@
- [ ] 写 `reports/iter32-代拍板-<日期>.md`
- [ ] 写 `reports/iter32-反哺点-<日期>.md`(§5 每条都要有落点)
**取用**:T1–T6 全部产出。
**取用**:T1–T7 全部产出。
**产出**:`reports/` 三份产出物 + 可合回的分支 tip。
**估时合计 ≈6.5–7.5h**(不含并行会话等待)。超 8h 切分预案:T3/T4 各拆「核心层」与「呈现+测试」两卡串行施工,其余不动。
**估时合计 ≈8.5–10.0h**。切分预案(超 8h 即生效):T3/T4 各拆「核心层」与「呈现+测试」两卡串行施工;T7 独立成卡可单独验收,必要时可拆出本批另立缺陷批。
## 7. 验证闸
---
## 7 · 验证闸
### 逐需求点验收清单
| # | 需求点 | 测什么(断言/行为) | 怎么测(落点) | 谁验 |
|---|---|---|---|---|
| A1 | N1 | `game/` 内 `完美排雷` 疑似现行计数 == 0 | grep 复现命令+同脚本口径 | 自动(S11+收尾 grep) |
| A2 | N1 | 对外文案三处文本恰为「完美封印…」,且不含「雷」字面 | 新冒烟断言:取清图高光行 `display_name`,断言 `find("雷") == -1` 且 `find("完美封印") >= 0`;落点 `game/smoke/smoke_all.gd` 清图段 | 自动(闸 01) |
| A2 | N1 | 对外文案三处文本恰为「完美封印…」,且不含「雷」字面 | 新冒烟断言:取清图高光行 `display_name`,断言 `find("雷") == -1` 且 `find("完美封印") >= 0`;落点 `game/smoke/smoke_all.gd` 清图段 |
| A3 | N2 | `game/` 内 `板级` 计数 == 0 | 同 A1 | 自动 |
| A4 | N3 | `game/` 注释面 `门票` 计数 == 0;且 `feat_ticket` 标识符与存档键**保持原样** | 同 A1 + 新增断言:`grep -c "feat_ticket"` 计数 == 改前值 | 自动 |
| A4 | N3 | `game/` 注释面 `门票` 计数 == 0;且 `feat_ticket` 标识符与存档键**保持原样** | 同 A1 + 断言:`_feat_ticket_pity` 等标识符仍在位 | 自动 |
| A5 | N4 | `game/` 内 `正主` 计数 == 0 | 同 A1 | 自动 |
| A6 | N5 | `game/` 内 `落籍` 计数 == 0(历史注记行豁免) | 同 A1 | 自动 |
| A7 | N6 | S11 规则在位:注入禁用词 → 退出码 1 且输出含 `S11 FAIL`/命中行 | 注入实验(变异验证),落点 `game/tests/static_scan.sh` | 自动(人工执行一次取证) |
| A7 | N6 | S11 规则在位:注入禁用词 → 退出码 1 且输出含 `S11 FAIL`/命中行 | 注入实验,落点 `game/tests/static_scan.sh` | 自动(人工执行一次取证) |
| A8 | 全域 | 冒烟绿数 == 基线 1151、单元 34 套全绿、探针段绿 | 跑所选域档 | 自动 |
| A9 | 全域 | 回执 commit == 分支 tip 且 `all_green=true`,零新增红 | 跑闸后读 `game/tests/.gates/receipt.json` | 自动(合回闸) |
| **A10** | **N7** | **未装备完美保险:首次标错 → 日志出现「完美封印已破」,且 `perfect_sweep_earned() == false`** | 新增断言,落点 `tests/unit/core/feat_vouchers_test.gd`(现有专长套件) | 自动 |
| **A11** | **N7** | **装备完美保险:首次标错 → 日志出现豁免态文案,且不出现「已破」;`perfect_sweep_earned() == true`(加倍仍发)** | 同上 | 自动 |
**测试方式两分法**:A1–A7 属能力验证(静态扫描/断言直取数据)与取证实验;A8–A9 为运行期验证。玩家可见文案的最终观感归**用户目检**(登记不阻塞):商店/图例/HUD 与结算高光行读作「完美封印/封印印记」。
**测试方式两分法**:A1–A7、A10–A11 属能力验证(静态扫描/断言直取数据)与取证实验;A8–A9 为运行期验证。玩家可见文案的最终观感归**用户目检**(登记不阻塞):结算明细中封印未中行的两态文案可读性。
**闸口径**:按本批改动域选档跑 `tools/run_all_gates.sh`(本批只触 `game/` 与 `reports/` → 代码域档);跑完写回执。
@@ -260,10 +342,14 @@
| `game/core/battle_orchestrator.gd:265` 注释 | 写回「板级完美排雷」原措辞 | `bash game/tests/static_scan.sh` | `S11 FAIL` + 命中行输出 |
| 同上对外文案 | `game/core/battle_orchestrator.gd:925` 写回「完美排雷!…」 | 冒烟清图段 | 断言 A2 红 |
| S11 扫描面 | 临时把 `DIR_CORE` 改成不存在目录 | `bash game/tests/static_scan.sh` | `S11 FAIL: 扫描面为空` |
| **N7 判据(反)** | 把 `grant_segment.gd:300` 改回 `_perfect_hit_false == 1`(RAW) | `tests/unit/core/feat_vouchers_test.gd` | 断言 A11 红(豁免态应无「已破」却出现) |
| **N7 判据(正)** | 把 :300 改成 `_perfect_hit_false - _perfect_forgiven <= 0`(恒真) | 同上 | 断言 A10 红(未豁免态应「已破」却缺失) |
注入后一律 `git checkout -- <file>` 精确还原,四件(变异点 file:行/跑的闸/红输出摘要/还原结论)记进实现报告变异验证记录表。
## 8. 异常分级
---
## 8 · 异常分级
- **L1(自救)**:单文件漏改致 grep 未过 → 补改重跑该段,不改批结构。
- **L2(记录继续)**:冒烟绿数与基线偏差 ≤2 且已归因到断言描述文本替换 → 记录偏差原因后继续。
@@ -272,25 +358,35 @@
2. `.tres` 加载失败或 schema 不同步;
3. 改前改后同种子读数不一致;
4. S11 注入后不变红(判据无效);
5. 触碰并行会话在改文件(`AGENTS.md`/`design/dev/code-conventions.md`)。
5. 触碰并行会话在改文件(`AGENTS.md`/`design/dev/code-conventions.md`);
6. **N7 上移 `_perfect_forgiven` 累加后,奖励兑付结果与改前不一致**(说明改到了兑付行为,而非只改文案判据)。
## 9. 代拍板白名单
---
## 9 · 代拍板白名单
1. 注释换代时的措辞微调(如「板级变异」→「整图变异」vs「整图作用域变异」),语义等价即可。
2. `落籍`→`已入库` 在带 commit 号的历史注记行**不改**(留档文本)。
3. `正主` 误报处(`damage_math_test.gd:36`「正主角池」)不改。
4. 测试断言描述文本的替换措辞,语义等价即可。
5. S11 规则段的 shell 写法(grep 组合、计数方式),与现役 S 段同构即可。
6. **N7 两态文案的末字微调**(保持「未豁免=已破、已豁免=不计入」这一因果不变成立即可)。
超清单必呈报。
## 10. 待裁点
---
## 10 · 待裁点
**零待裁点,开工门=U0(`/iter 32` 发令)。**
已落裁决两条,卡片据以成文:
已落裁决四条,卡片据以成文:
| 裁定 | 结论 |
|---|---|
| 完美排雷 | 全库统一换代为「完美封印」(含代码内部注释)——2026-10-19 用户裁;据此推翻 `需求卡片-凭证件裁削批`:108「内部开发用语按 v3.15 纪律保留」半句,卡片条款订正归文档轨批 |
| 完美排雷 | 全库统一换代为「完美封印」,含代码内部注释——2026-10-19 用户裁;据此推翻 `需求卡片-凭证件裁削批`:108「内部开发用语按 v3.15 纪律保留」半句,卡片条款订正归文档轨批 |
| 排雷(模块名) | **不扩大禁词面**。「排雷玩法/排雷规则」是内部机制名(=扫雷推理层的玩法动作总称,见 `00-游戏概念.md:5`),GDD 目录即 `systems/排雷循环/`,术语表正文在用,26 个文件保持原样 |
| 门票 | 仅换代注释措辞;标识符与数据键零改动;玩家可见两处(`shop.tres:86`/`curio_interact_controller.gd:165-166`)移交文档侧定性 |
| 归因锚判据(N7) | 并入本批:`grant_segment.gd:300` 改用有效误标口径(总数 − 豁免数),豁免累加上移到 `_emit_row` 之前;文案按两态改写——2026-10-20 用户裁 |
**禁用词机检闸不扩到 `game/`**(用户裁:代码与文档分开管理);代码侧改用代码域自己的静态扫描闸 S11,词表从 `design/gdd/术语表.md` 解析,不内联第二份。