From 8575e1b16c06c50bebf569e35dd5c4a56102e662 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Tue, 20 Oct 2026 02:04:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(card):=20=E9=9C=80=E6=B1=82=E5=8D=A1?= =?UTF-8?q?=E7=89=87=20v1.1=E2=80=94=E2=80=94=E6=96=B0=E5=A2=9E=20N7=20?= =?UTF-8?q?=E5=BD=92=E5=9B=A0=E9=94=9A=E5=88=A4=E6=8D=AE=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=EF=BC=8CT2=20=E5=AF=B9=E5=A4=96=E6=96=87=E6=A1=88=E6=94=B9?= =?UTF-8?q?=E6=A6=82=E5=BF=B5=E9=A9=B1=E5=8A=A8=E4=B8=A4=E6=80=81=E5=86=99?= =?UTF-8?q?=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 张全过。 --- design/gdd/06-待办清单.md | 4 +- ...求卡片-代码注释禁用词清扫批-2026-10-20.md | 214 +++++++++++++----- 2 files changed, 158 insertions(+), 60 deletions(-) diff --git a/design/gdd/06-待办清单.md b/design/gdd/06-待办清单.md index 47e1c995..daf71dbb 100644 --- a/design/gdd/06-待办清单.md +++ b/design/gdd/06-待办清单.md @@ -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`） diff --git a/design/research/需求卡片-代码注释禁用词清扫批-2026-10-20.md b/design/research/需求卡片-代码注释禁用词清扫批-2026-10-20.md index 451930a8..5ea88db3 100644 --- a/design/research/需求卡片-代码注释禁用词清扫批-2026-10-20.md +++ b/design/research/需求卡片-代码注释禁用词清扫批-2026-10-20.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:行／跑的闸／红输出摘要／还原结论）记进实现报告变异验证记录表。 -## 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` 解析，不内联第二份。