From e425ef1be0fd8f4949fb2b4dfae42d786e0a0831 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Wed, 21 Oct 2026 15:53:52 +0800 Subject: [PATCH] =?UTF-8?q?chore(=E5=BC=95=E7=94=A8=E5=8F=AF=E6=A0=B8?= =?UTF-8?q?=E9=97=B8=E5=BB=BA=E6=A1=A3=E6=B3=A8=E5=86=8C):=2008d=20?= =?UTF-8?q?=E5=85=A5=E6=96=87=E6=A1=A3=E5=9F=9F=E9=97=B8=E5=BA=8F=EF=BC=8B?= =?UTF-8?q?=E4=B8=89=E5=A4=84=20game/=20=E7=BA=AF=E6=96=87=E5=AD=97?= =?UTF-8?q?=E6=AC=A0=E8=B4=A6=E6=B8=85=E5=87=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - tools/run_all_gates.sh：文档域闸序加「08d 引用可核」并补头注 --docs 清单（闸清单唯一事实源只写这一处） - game/tests/.gates/baseline.json：手工加 08d 绿记录一条（13→14，其余条目原样保留），照 8f66ae15 之 08c 与 e8b6751b 之 06b 先例 - game/tests/static_scan.sh:100：S11 词表来源注释订正——「完美排雷」已于 2026-10-21 入退役词对照表，:122 追加行成冗余（sort -u 去重后行为不变，删它属改闸件词表本体，留待代码批，注释已写明） - game/tests/README.md：:58 套件数 26→35（按 _suites() manifest 实数）；:81 Config/Data 证据落点 design/qa/ → 跑批回执＋reports/；:92 verifier_batch 报告落点 design/qa/ → sim-data/（依 AGENTS 在册口径） - doc_ref_audit.py：路径解析补「尾段匹配」一档，tests/run_all.gd／views/level_map_screen.gd 这类相对 game/ 工程的简写不再误判为路径不存在（实测纳入 reports/ 的红项 17→12，余下为历史件真实漂移，佐证排除面划法） - 待办清单：引用可核注册欠账与 README 分级表 design/qa 两条完成即整条删除；game/ 域欠账条目收窄为 :122 冗余行一项，状态处记用户特批标记 零行为改动：无一行 GDScript、无表数值、无场景资源。验证：bash -n 两闸件语法 OK／baseline 合法 JSON／闸壳 --docs 自身退出码 0（含新注册 08d 与建档记录一致）／引用可核 64 件 84 处红项 0／流水线闸 PASS 69 条目。 --- game/tests/.gates/baseline.json | 112 +++++++++++++++++--------------- game/tests/README.md | 6 +- game/tests/static_scan.sh | 2 +- tools/doc_ref_audit.py | 12 +++- tools/run_all_gates.sh | 7 +- 待办清单.md | 22 ++----- 6 files changed, 80 insertions(+), 81 deletions(-) diff --git a/game/tests/.gates/baseline.json b/game/tests/.gates/baseline.json index 8adb2d9d..3d529c84 100644 --- a/game/tests/.gates/baseline.json +++ b/game/tests/.gates/baseline.json @@ -1,57 +1,61 @@ { - "note": "存量基线·首次自动生成；闸况变化时本脚本会判红，需人工确认后重生成；2026-10-17 人工确认重生成 06 条目：af94ce97 把 gdd_lint 记为存量红（01 篇 R5），该红已由 fcb8c3f8 补流程图消除，实测 --docs 域 06 exit=0，故基线改回绿。2026-10-18 新增闸件 08c 流水线闸（tools/pipeline_gate.py 注册上电），手工加入绿记录（roadmap 压缩批实测 --docs 域 exit=0），其余条目原样保留。", - "gates": { - "01 冒烟全量": { - "exit": "0", - "fp": "green" - }, - "02 单元套件": { - "exit": "0", - "fp": "green" - }, - "03 探针 --click": { - "exit": "0", - "fp": "green" - }, - "04 探针 --full": { - "exit": "0", - "fp": "green" - }, - "05 渲染闸": { - "exit": "0", - "fp": "green" - }, - "06 gdd_lint": { - "exit": "0", - "fp": "green" - }, - "06b 变更记录节": { - "exit": "0", - "fp": "green" - }, - "07 doc_link": { - "exit": "0", - "fp": "green" - }, - "08 doc_term": { - "exit": "0", - "fp": "green" - }, - "08c 流水线闸": { - "exit": "0", - "fp": "green" - }, - "09 静态扫描": { - "exit": "1", - "fp": "4354b2aa72a7" - }, - "10 熵增闸": { - "exit": "0", - "fp": "green" - }, - "11 回放确定性对拍": { - "exit": "SKIP", - "fp": "skip" - } + "note": "存量基线·首次自动生成；闸况变化时本脚本会判红，需人工确认后重生成；2026-10-17 人工确认重生成 06 条目：af94ce97 把 gdd_lint 记为存量红（01 篇 R5），该红已由 fcb8c3f8 补流程图消除，实测 --docs 域 06 exit=0，故基线改回绿。2026-10-18 新增闸件 08c 流水线闸（tools/pipeline_gate.py 注册上电），手工加入绿记录（roadmap 压缩批实测 --docs 域 exit=0），其余条目原样保留。", + "gates": { + "01 冒烟全量": { + "exit": "0", + "fp": "green" + }, + "02 单元套件": { + "exit": "0", + "fp": "green" + }, + "03 探针 --click": { + "exit": "0", + "fp": "green" + }, + "04 探针 --full": { + "exit": "0", + "fp": "green" + }, + "05 渲染闸": { + "exit": "0", + "fp": "green" + }, + "06 gdd_lint": { + "exit": "0", + "fp": "green" + }, + "06b 变更记录节": { + "exit": "0", + "fp": "green" + }, + "07 doc_link": { + "exit": "0", + "fp": "green" + }, + "08 doc_term": { + "exit": "0", + "fp": "green" + }, + "08c 流水线闸": { + "exit": "0", + "fp": "green" + }, + "09 静态扫描": { + "exit": "1", + "fp": "4354b2aa72a7" + }, + "10 熵增闸": { + "exit": "0", + "fp": "green" + }, + "11 回放确定性对拍": { + "exit": "SKIP", + "fp": "skip" + }, + "08d 引用可核": { + "exit": "0", + "fp": "green" } + } } \ No newline at end of file diff --git a/game/tests/README.md b/game/tests/README.md index b91827bc..d8b03037 100644 --- a/game/tests/README.md +++ b/game/tests/README.md @@ -55,7 +55,7 @@ godot --headless --path . res://smoke/.tscn timeout 120s godot --headless --script tests/run_all.gd ``` -> 单元/契约套件状态（单元测试与契约层批 2026-09-28 立基，后随迭代 7/8 增补）：`_suites()` manifest 已登记实跑 **26 套件**（2026-10-16 迭代 29 T1：样板件 `example_test.gd` 退出生产 manifest，27 → 26；`fog_lantern_wiring_test` 随提灯载体退役摘除在前）——data_config（ConfigDB 加载/进度坐标 ceil 解析/fatal 退出码/统一随机流）、core（秘宝结构冻结/断点续玩/提灯装配链）、battle_settlement（DamageMath 纯函数/DamageController 伤害单据五配方）、contracts（系统间接口契约断言）、presentation（节奏队列/奖励浮层/字体资产/地形瓦片集）；致命类独立进程 `expect=1`。期望值一律由表读值推导（零玩法数值字面量）、随机只经 RngService 统一流。 +> 单元/契约套件状态（单元测试与契约层批 2026-09-28 立基，后随迭代 7/8 增补）：`_suites()` manifest 已登记实跑 **35 套件**（2026-10-21 迭代 32 卡② 后现况，含 `counter_prefix_fatal_test` 负面套件；上一次计数变动为 2026-10-16 迭代 29 T1：样板件 `example_test.gd` 退出生产 manifest，27 → 26；`fog_lantern_wiring_test` 随提灯载体退役摘除在前）——data_config（ConfigDB 加载/进度坐标 ceil 解析/fatal 退出码/统一随机流）、core（秘宝结构冻结/断点续玩/提灯装配链）、battle_settlement（DamageMath 纯函数/DamageController 伤害单据五配方）、contracts（系统间接口契约断言）、presentation（节奏队列/奖励浮层/字体资产/地形瓦片集）；致命类独立进程 `expect=1`。期望值一律由表读值推导（零玩法数值字面量）、随机只经 RngService 统一流。 **协议要点**（D2 冒烟协议）： - 冒烟脚本 `extends SceneTree` 以获得 `quit(code)`；成功 `quit(0)`、失败 `quit(1)` @@ -78,7 +78,7 @@ timeout 120s godot --headless --script tests/run_all.gd | 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 check pass | `design/qa/` | +| Config/Data | Smoke check pass | 跑批回执 `game/tests/.gates/receipt.json`（不入库）＋结论随批记 `reports/` | ## game/smoke/ 游离脚本台账（迭代 29 T7 逐个定性） @@ -89,7 +89,7 @@ timeout 120s godot --headless --script tests/run_all.gd | 脚本 | 定性 | 用途与触发方式 | 结果由谁判 | |---|---|---|---| | `adventure_monte_carlo.gd` | **在役**（`AGENTS.md` 在册入口） | 全冒险期望 MC；`tools/parity_anchor.py` 的对拍载体 | 工具脚本逐位比对 | -| `verifier_batch.gd` | **在役**（`AGENTS.md` 在册入口） | `tools/balance_verifier.py` 的采集端（数值验证） | 报告落 `design/qa/` | +| `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 | 宿主脚本 | diff --git a/game/tests/static_scan.sh b/game/tests/static_scan.sh index 42bbdb91..fc5709c0 100644 --- a/game/tests/static_scan.sh +++ b/game/tests/static_scan.sh @@ -97,7 +97,7 @@ fi # 禁「板级」「门票」「正主」「落籍」「完美排雷」等退役词进注释面（完整词表见术语表解析） # 权威出处：design/gdd/术语表.md「退役词对照」节＋「对外命名纪律」节 # 扫描面：game/ 全域 .gd/.tres/.md/.json/.sh（.txt 不收＝第三方许可证非本仓库文本） -# 词表来源：解析「退役词对照」第一列（去括号注、斜杠拆分）＋显式追加禁「完美排雷」（受对外命名纪律约束，不在退役词对照表里）；显式排除「巢穴」（玩家专名/风味层，术语表自带除外注）、「旗」（单字误报率高，doc_term_audit 判例） +# 词表来源：以解析「退役词对照」第一列（去括号注、斜杠拆分）为准；该词自 2026-10-21 已入表（术语表在册行），故 `:122` 的显式追加行成为冗余——`sort -u` 去重后行为不变，暂保留待下个代码批一并删；显式排除「巢穴」（玩家专名/风味层，术语表自带除外注）、「旗」（单字误报率高，doc_term_audit 判例） # 注释文本提取：.gd/.sh 取 # 后文本；.tres 取 ; 后文本；.md 取整行；.json 无注释语法（保留扩展名但不产生注释段） # 三层豁免依序：①闸门自指（行内含检查/禁令形态即跳过）②显式留档豁免单 4 处 ③非注释面天然不取 diff --git a/tools/doc_ref_audit.py b/tools/doc_ref_audit.py index 2e4891ad..1a89c947 100644 --- a/tools/doc_ref_audit.py +++ b/tools/doc_ref_audit.py @@ -10,6 +10,8 @@ r"""doc_ref_audit.py — 文档内代码引用可核检查（机检） 扫描面：`design/` 现行文档树 ＋ 四份根文件（`待办清单.md`／`体验验证清单.md`／`roadmap.md`／`AGENTS.md`）。 排除面：`reports/`——中间文档唯一暂存地（doc-conventions 第 11 节；`design/research/` 已于 2026-10-21 退役）， 入内文件按「吸收即死」退役，历史件不回溯改，故不入本闸判据。 +（2026-10-21 实测：把 reports/ 纳进来出 17 条红项／538 处引用，多为历史件里的行号漂移与当时合法的旧路径写法—— +要收紧到「现行件才受指针核对」得先立分界，暂不扩。） 自检二道（防假绿）：扫描文件数为零 ⇒ FAIL；抽取到的引用数为零 ⇒ FAIL。 （正则被改写失手或路径写错时，检查会静默空转并报绿——与 static_scan 各段同规。） @@ -85,7 +87,9 @@ def collect_docs(explicit): def resolve(name, doc_rel, index, bybase): - """返回 (命中路径列表, 解析方式)。方式=exact / ambiguous / none。""" + """返回 (命中路径列表, 解析方式)。方式=exact / ambiguous / none。 + 依序试：文档同目录相对路径 → 仓库根路径 → 按「尾段匹配」全库找（`tests/run_all.gd` + 这类相对 game/ 工程的简写靠这一步命中，否则会被误判成路径不存在）。""" name = name.strip("./") if "/" in name: for cand in ( @@ -94,6 +98,12 @@ def resolve(name, doc_rel, index, bybase): ): if cand in index: return [cand], "exact" + suffix = "/" + name + hits = sorted(p for p in index if p.endswith(suffix)) + if len(hits) == 1: + return hits, "exact" + if len(hits) > 1: + return hits, "ambiguous" return [], "none" cands = sorted(bybase.get(name, [])) if not cands: diff --git a/tools/run_all_gates.sh b/tools/run_all_gates.sh index f094ab44..b6b60164 100644 --- a/tools/run_all_gates.sh +++ b/tools/run_all_gates.sh @@ -9,7 +9,7 @@ # 用法：tools/run_all_gates.sh [--code|--docs|--quick] # --code 只跑代码域闸（01 冒烟／02 单元／03 探针 --click／04 探针 --full／05 渲染闸／09 静态扫描 # ／11 回放确定性对拍＋10 熵增闸）——本批改动触及 game/ 时用（游戏工程的唯一代码验收域）。 -# --docs 只跑文档域闸（06 gdd_lint／07 doc_link／08 doc_term／08c 流水线闸 +# --docs 只跑文档域闸（06 gdd_lint／07 doc_link／08 doc_term／08c 流水线闸／08d 引用可核 # ＋10 熵增闸） # ——本批改动不触及 game/ 时用：design/、根规则文件、tools/ 工具脚本、.zcode/ 配置等 # 一切非 game 改动的本域验收。 @@ -185,9 +185,8 @@ gate "07 doc_link" "doc_link.log" "$PY" "$REPO/tools/doc_link_audit.py" --strict gate "08 doc_term" "doc_term.log" "$PY" "$REPO/tools/doc_term_audit.py" --strict # ── 8c. 流水线闸（待办清单条目状态机＋roadmap 迭代总表＋一次交叉核，判据=doc-conventions §12）── gate "08c 流水线闸" "pipeline.log" "$PY" "$REPO/tools/pipeline_gate.py" -# 8d 引用可核（tools/doc_ref_audit.py，2026-10-21 交付）暂不注册：新闸件无基线记录必判「闸况变化」拦回执， -# 而建档要改 game/tests/.gates/baseline.json——触 game/ 即要求代码域全量测试（process-conventions §3.10 推域口径）， -# 文档域批按测试两入口铁规零跑游戏测试。注册与建档随下一个触 game/ 的批次一并做（待办清单在册）。 +# ── 8d. 引用可核（现行文档里「文件:行号」指针的目标存在性与行界，判据=件头注）── +gate "08d 引用可核" "doc_ref.log" "$PY" "$REPO/tools/doc_ref_audit.py" --strict fi # ── 6c. 回放确定性对拍（条件闸件；属代码域）── if in_domain code; then diff --git a/待办清单.md b/待办清单.md index 07f5d96d..a0eff9b8 100644 --- a/待办清单.md +++ b/待办清单.md @@ -514,12 +514,6 @@ ### 文档与结构 -#### game/tests/README 分级表证据落点行仍指 design/qa/（2026-10-20 登记，来源=批次移交，设计面=工程直入） - -**现状**：qa/ 目录退役批（分支 `qa-retire-20261020`，提交 897a0742）已把 13 处活指针改判到 `reports/`、`sim-data/`（`reports/` 已于 2026-10-21 退役，中间文档唯一暂存地只剩 `reports/`），唯 `game/tests/README.md:81` 测试分级表 Config/Data 行的证据落点仍写 `design/qa/`（该目录本批已退役），正解＝`sim-data/`——该行是机器读数出口，与 `tools/balance_verifier.py` 的报告落点改动属同一口径。本批未顺手改：改动路径一旦落在 `game/` 前缀内，合回闸即按路径推定本批需代码域验收，而本批零代码改动（见 `.zcode/hooks/worktree-guard.sh` 推域段）；死链闸也判不出——`tools/doc_link_audit.py` 只扫 `design/gdd/`。故列为已知欠账，等下一批真改 `game/` 时一并纠正。 -**归属**：`game/tests/README.md` 测试分级表 -**状态**：待写卡（备选） - #### qa/ 实现报告收尾·孤儿遗留七项（2026-10-14 登记，来源=批次移交，设计面=工程直入） **现状**：qa 收尾批核查 iter19 系列出口报告遗留移交项时发现**不在待办清单在册**的七项（acceptance-package §三.2/card0 §5.3/followup §七.3/uibackfill §6.2-4/verify §6.1/3/7）。已结案的（tree_rules 受理闭环、X/Y 双源、S1 七项违例修复、提灯目检项、tests.yml 休眠等）已在各报告标注结案证据，不入本条。七项均为挂号备查/顺路件，无排期承诺： @@ -730,23 +724,15 @@ #### `game/` 域文档两处措辞订正欠账（2026-10-21 登记，来源=批次移交，设计面=工程直入） -**现状**：两处 `game/` 内文本与现实不符，改 `game/` 任何路径都会触发代码域全量测试（2026-10-20 用户裁「零代码批不改该行、登记欠账」），故不入本写入批：①`game/tests/static_scan.sh:100` S11 注释仍称「完美排雷」不在退役词对照表里——2026-10-21 起该词已入表（术语表退役词对照行在册），注释与 `:122` 追加行按「S11 权威=术语表解析」口径可一并订正；②`game/tests/README.md:58` 记「manifest 已登记实跑 26 套件」——迭代 32 卡② 后现况为 35 套件（含 counter_prefix_fatal 负面套件），以 `run_all.gd` 现况为准更新。同文件另两处 `design/qa/` 死指已另有在册条目（本清单「game/tests/README 分级表证据落点行仍指 design/qa/」），本条不重复登记。 +**现状**：标题里的「两处」是 2026-10-21 登记时的原述（标题属登记元数据不改）。当日用户手工提交批已清三处纯文字面——`game/tests/static_scan.sh:100` S11 词表来源注释、`game/tests/README.md:58` 套件数（26 → 35，按 `_suites()` manifest 实数）、`game/tests/README.md:81`／`:92` 两处 `design/qa/` 死指（分别改指跑批回执＋`reports/` 与 `sim-data/`）。**本条唯一未净项**＝`game/tests/static_scan.sh:122` 的 `printf `'完美排雷' +' >> "$S11_WFILE" 追加行：该词自 2026-10-21 已入术语表「退役词对照」，追加行成为冗余（`sort -u` 去重后行为不变）。删它属改闸件词表本体、非纯文字订正，留待下一个触 `game/` 的代码批一并清；注释行已写明这个状态。 -**归属**：`game/tests/`（代码域，随下一个触碰 game/ 的批次顺带清） +**归属**：`game/tests/`（代码域，剩余项随下一个触碰 game/ 的批次顺带清） -**状态**：待写卡 +**状态**：待写卡〔用户特批 2026-10-21 跳过代码域闸〕 --- -#### 引用可核闸注册与建档欠账（2026-10-21 登记，来源=会话提及，设计面=工程直入） - -**现状**：新机检件 `tools/doc_ref_audit.py`（文档内「文件:行号」指针的存在性与行界核对，件头注即判据）已于 2026-10-21 交付并双向验证——注入不存在路径 EXIT=1、注入超界行号 EXIT=1、扫描面为空自判 FAIL、还原 EXIT=0（当日实测：63 件文档／81 处引用／红项 0／建议 6）。它**尚未注册进 `tools/run_all_gates.sh` 文档域**，原因＝注册要把绿记录写进 `game/tests/.gates/baseline.json`（先例见 8f66ae15 之 08c 与 e8b6751b 之 06b），而改 `game/` 下任何路径都要求代码域回执、即跑全量游戏测试，文档域批按测试两入口铁规零跑（2026-10-20 用户裁「不为边际正确性付跑测成本」）。同批附带交付：`tools/doc_term_audit.py` 扫描面已扩到四份根文件（待办清单／体验验证清单／roadmap／AGENTS），扩面实测「疑似现行」0 处、变异注入见红 EXIT=1 还原 EXIT=0。内容锚核对（`--anchors`）实测 81 处引用出 58 条未命中，噪声约七成，按建议级交付不判红，待真实批次积累后再定是否收紧。 - -**归属**：`tools/run_all_gates.sh` 注册行＋`game/tests/.gates/baseline.json` 建档（代码域批次顺带） - -**状态**：待写卡 - ---- #### 迭代 32 移交项一——奇物门票三处玩家文案待定性后传导（2026-10-21 登记，来源=批次移交，设计面=文档轨）