diff --git a/reports/需求卡片-节点图换代收尾批-2026-10-25.md b/reports/需求卡片-节点图换代收尾批-2026-10-25.md new file mode 100644 index 00000000..da1aea91 --- /dev/null +++ b/reports/需求卡片-节点图换代收尾批-2026-10-25.md @@ -0,0 +1,171 @@ +# 需求卡片——节点图换代收尾批(宿主改名+验证集清单重生成+表尾叙事清偿) + +- 批名:节点图换代收尾批|日期:2026-10-25|批次性质:非迭代批(测试基建+数据表注释面;改动面=game/tests/+game/data/+tools/,批末含待办清单条目删除——域档判定按 run_all_gates.sh 自身规则执行) +- 估时:0.25–0.4 工作日(T0 0.1/T1 0.05/T2 0.1/T3 0.05;软盒上限 0.4,超出按异常分级 L3 停机呈报) +- 来源:待办清单三条工程直入条目(均 2026-10-25 登记,来源=审计发现,设计面=工程直入)——「验证集清单快照重生成」「测试宿主改名 node_map_templates_test.gd」「level.tres 表尾注释含迭代叙事」。三件同源(迭代 35 卡② 断言面换代的收尾欠账)且第①件依赖第②件先行(清单重生成自动带新宿主路径),合一张卡执行 +- 验收证明口径:按 2026-10-24 用户裁定,一切验收走撤销证明,不做变异类测试 + +## 1 目标与完成定义 + +**做什么**:四件——① 集成宿主改名 `game/tests/integration/node_map_templates_test.gd` → `node_map_determinism_test.gd`(manifest 登记行与文件内自引用字面量同批改,断言判据零改动);② `tools/extract_checks.py` 两处小改(清单头注模板数据驱动化+新增 `--carry-from` 回填列承接);③ 用工具重生成 `game/tests/验证集清单.md`(缺省三宿主全量口径,同指纹行承接旧清单「白话释义/处置」两列);④ `game/data/tables/level.tres:16` 表尾注释删迭代叙事词、保留去向事实句。 + +**完成定义**:验收对照表 R1–R7 全过+按改动域选档跑闸全绿+`reports/` 三份产出物(实现报告/代拍板追认单/反哺点清单)齐+待办清单三条目整条删除(做完即删)。 + +## 2 设计事实源 + +工程直入证据指认(与三条待办条目一致,写卡会话 2026-10-25 在 master 尖实查复核): + +- `game/tests/run_all.gd:90`——manifest 登记行 `res://tests/integration/node_map_templates_test.gd`;宿主文件在位,文件内 4 处文件名自引用(:1 头注、:10 运行说明、:26 push_error 前缀、:31 finish 标签) +- `game/tests/验证集清单.md`——`PYTHONIOENCODING=utf-8 python tools/extract_checks.py --diff`(缺省三宿主源)2026-10-25 实测:现提取 63 个源文件、清单 1067 条 vs 现提取 1544 条、消失 67/新增 539/标签字面变更 10 对/cond 字面变更 4 对,退出码 1;退役措辞实测 first_script 8 行(177/215/233/237/242/254/263/1168)、template_pick 3 行(138/882/1406) +- `game/data/tables/level.tres:16`——表尾注释「旧 15 张模板池(3 关 × 5)随迭代 35 卡② 清出,历史查 git 提交史与 tools/t5_build_templates.py、t17_fanout2_rebuild.py 留档。」(两个留档工具实查在位) +- `game/tests/验证集清单.md:147/148`——#84/#85 两行(收束置位与幂等)指纹与现宿主 `node_map_templates_test.gd:110/112` 逐字一致,其「处置」列文本含旧宿主路径——承接不做映射则旧名随回填列进入新清单(grilling 复核 2026-10-25 指认) + +## 3 现状事实 + +(全部实查,开工自行复核) + +- 宿主与引用面:node_map_templates_test.gd 在 `game/tests/integration/`(.gd+.uid 两件);全仓引用=`run_all.gd:90` 一处+文件内自引用 4 处+验证集清单行文 15 处(冻结列随 R3 重生成清偿;其中 #84/#85 两行的「处置」列文本会经承接进入新清单,须映射改名——见 T0/T2);design/ 与 game/tests/README.md 零提及(grep 实证);`tools/gdstyle_baseline.txt` 零条目(S13 扫描面只含产品码三目录,改名无基线耦合) +- 清单机制:`tools/extract_checks.py` 缺省源=`game/tests/unit/**`+`game/tests/integration/**`+`game/tests/system_test.gd` 三宿主遍历;`--extract --force` 重生成(已存在拒写防误覆);`render_list`(:329-369)头注模板写死批 B 叙事(标题「迁移参照物」与「批 B 基点实测 smoke_all.gd 调用点 1065 处」等句),直接重生成会把全部回填列抹成(待填)——实测当前清单 1067 行、0 行待填、白话释义/处置全部已回填 +- 漂移构成:清单基点=批 B 迁移对象(smoke_all 1065 处,提案 §五.7 明示「unit/integration 现役断言收录为后续可选项」);新增 539=批 B 未收录的既有套件断言+迭代 35 卡② 换代新增(player_copy_sweep_test 等新宿主与 level_shop_economy 扩段等);消失 67+字面变更 14=卡② 退役/改判的迁移面断言(first_script/template_pick 措辞行在其中)。承接理论值=1067−67−14≈986 行,承接不上的新行≈558 行落(待填) +- level.tres 表尾::14-15 两行为现行图源事实句(不动);:16 一行含「随迭代 35 卡② 清出」迭代叙事。处置口径待办条目已裁:删迭代号、保留「旧 15 张模板池」「git 提交史与 tools/t5_build_templates.py、t17_fanout2_rebuild.py 留档」去向事实、表内数值零改动 + +## 4 设计契约(违反即返工) + +- 🔴 宿主改名零判据改动:断言内容、检查条数、quiet 档位一律不动;只改文件名(.gd+.uid 同迁)、manifest 路径行、文件内 4 处自引用字面量 +- 🔴 清单冻结列只由机器提取:标签/cond/quiet/行号/序号禁手写改行;「白话释义/处置」两列=同指纹承接旧行(指纹与 `entry_key` 同构:cond 折叠+标签字面量+后缀折叠),承接文本内的旧宿主文件名一律映射为新名(node_map_templates_test.gd→node_map_determinism_test.gd),承接不上的新行落(待填),禁止手工编造释义;重生成后 grep 清单 node_map_templates/first_script/template_pick 预期零命中(template_pick 若命中须全为反向断言) +- 🔴 头注模板数据驱动:标题与口径行由当次提取数据生成(基点 commit、源文件数、实测条数),禁止出现批次专名与写死计数 +- 🔴 清单重生成后对账必须 PASS:`--diff`(缺省源)标签/cond/计数三对齐零差异 +- 🔴 level.tres 只动 :16 注释文字,表内数值零改动(MC 零跑) +- 🔴 本批不删不改任何宿主断言判据(清单 67 行消失=宿主侧已不存在断言的账面同步,非断言删除——测试削弱申报见 §9) + +## 5 范围边界 + +做:上列四件+工具与注释随动+批末三条目删除。 + +不做(去向): + +- 不回填新行白话释义(≈558 行;既有套件断言释义回填=提案 §五.7 既定「后续可选项」,清单头注注明回填属后续维护即可;如需立项另登待办) +- 不动 `design/engineering/test-conventions.md` §8.3 维护锚的「迁移断言全体」描述句(清单改全量口径后该句失准——列反哺点呈报用户裁决,归文档批落文;本批保持不触 design/) +- 不动 game/tests/README.md(实测对本批三件零提及) +- 不动 run_all.gd:90 行尾注释的「批 B 自 smoke_all 迁入」字样(已知留存量,行级注释清偿如需另登待办) +- 不处理 game/.godot 编辑器缓存(改名后自刷新,不入 git) +- 不清偿 gdstyle/S6/S7/S8 等其他闸件族欠账(另有条目在册) + +## 6 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| design/engineering/test-conventions.md §8.3(:98) | 「验证集清单…迁移断言全体的冻结参照清单」描述句——清单改三宿主全量口径后「迁移断言全体」失准 | 反哺点清单呈报用户裁决,归文档批落文(本批不触 design/) | +| 待办清单.md 三条来源条目 | 状态推进+批完结整条删除 | 写卡段回写「已写卡」;批完结由执行批整条删除(非迭代批可写根清单,做完即删) | + +## 7 文件结构图与落位预检 + +### 7.1 文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| tools/extract_checks.py | 头注模板数据驱动(render_list :329-369 区域)+`--carry-from` 承接(复用 parse_list 读旧清单,按 entry_key 同构指纹承接回填两列) | 行为改动——R4/R5/R6 | +| game/tests/integration/node_map_templates_test.gd → node_map_determinism_test.gd(+.uid) | 模板时代遗留名退役;内容零改动 | 行为改动(装载路径)——R1/R2 | +| game/tests/run_all.gd:90 | manifest 路径行改指新名(行尾注释不动) | 行为改动——R1 | +| game/tests/验证集清单.md | 冻结列重生成+回填列承接(数据件) | 非行为改动——R3/R4 | +| game/data/tables/level.tres:16 | 表尾注释叙事词清偿 | 非行为改动——R7 | + +### 7.2 落位与可复用性预检 + +- 复用面:零新增文件;工具改造复用自身 `parse_list`/`entry_key`/`fold`(承接逻辑不另立解析);改名复用既有宿主与 manifest 机制。工具新增一个 argparse 参数与一个承接函数,落点唯一=extract_checks.py(grep 全仓无同职责第二实现) +- 唯一面:断言静态提取与清单生成/对账唯一落点=extract_checks.py;宿主 manifest 唯一登记处=run_all.gd;level 表尾注释唯一落点=level.tres;清单头注口径唯一出处=工具模板(README 禁复写) +- 分层与交互面:纯测试基建与数据件,零游戏层交互;装载链=run_all_gates 02 段 → run_all.gd(manifest)→ 宿主;extract_checks.py 独立运行、不进任何闸(清单「不进任何闸」现状维持) + +## 8 任务卡 + +### T0 工具两小改(估时 0.1 工作日) + +- 取用:无(首卡) +- 产出:`render_list` 数据驱动头注(标题、基点 commit、源文件数、实测条数由当次数据生成);`--carry-from <旧清单>`(--extract 模式参数;承接函数 `carry_cells(frozen_rows) -> dict[指纹, (白话释义, 处置)]`,指纹与 entry_key 同构;承接文本旧宿主文件名映射为新名) + +步骤: + +- [ ] 头注模板改数据驱动:删「批 B 基点实测 smoke_all.gd…1065 处」「迁移参照物」等批次专名与写死计数(模板存量「test-conventions §9.3 锚」错号一并改指 §8.3),标题改「验证集清单(断言快照·冻结)」语义;口径说明保留通用部分(双口径解释、单元格转义规则、维护义务指 test-conventions §8.3、「白话释义/处置」新行(待填)属后续维护——固定模板文案,生成后零手改) +- [ ] 落 `--carry-from`:按指纹承接旧清单行「白话释义/处置」两列(quiet 不承接,以现提取为准);承接不上的行落(待填) +- [ ] 窄确认(不动正式清单):`PYTHONIOENCODING=utf-8 python tools/extract_checks.py --extract --out <临时件> --carry-from game/tests/验证集清单.md` → 头注含当前 `git rev-parse --short HEAD` 短哈希与实测 1544 条;抽 3 条未漂移行核对释义承接;`python tools/extract_checks.py --diff <临时件>` PASS +- [ ] 撤销证明 R5/R6 留档:回退头注模板段重试生成→批次专名句复现;回退承接段重试生成→承接计数 0(记录后还原,临时件禁止入库) + +### T1 宿主改名(估时 0.05 工作日) + +- 取用:无 +- 产出:`res://tests/integration/node_map_determinism_test.gd`(.gd+.uid 同迁,内容零改动) + +步骤: + +- [ ] 改名前基线:`"D:/code/godot/Godot_v4.7.2-stable_win64_console.exe" --headless --path game --script res://tests/integration/node_map_templates_test.gd` 直跑旧名 → 记录摘要行检查条数与 0 失败(R2 对拍基线) +- [ ] `git mv` 两件到 node_map_determinism_test.gd(.gd+.uid);文件内 4 处自引用字面量(:1/:10/:26/:31)换新名,其余零改动 +- [ ] run_all.gd:90 路径改 `res://tests/integration/node_map_determinism_test.gd`(行尾注释不动) +- [ ] 孤立验证:同命令直跑新名 → 退出码 0、摘要行 0 失败、检查条数=基线条数 +- [ ] 撤销证明 R1 留档:仅回退 run_all.gd:90 一行 → 直跑 `--script res://tests/run_all.gd` 退出码非 0(宿主路径不存在;若引擎对缺路径宿主退 0 且输出无错误标记致不红=L3 停机呈报);还原复绿 + +### T2 清单重生成(估时 0.1 工作日) + +- 取用:T0 工具(头注模板+承接);T1 新宿主名(重生成自动带新路径) +- 产出:现行口径验证集清单(1544 条、承接≈986 行回填列) + +步骤: + +- [ ] 备份旧清单到仓库外临时件 → `PYTHONIOENCODING=utf-8 python tools/extract_checks.py --extract --force --carry-from <临时备份>` 重生成 +- [ ] 对账:`PYTHONIOENCODING=utf-8 python tools/extract_checks.py --diff game/tests/验证集清单.md`(缺省源)→ PASS 零差异、清单条数 1544 +- [ ] 退役措辞与旧名核点:grep 清单 node_map_templates/first_script/template_pick → 预期零命中;template_pick 若命中须逐条判读为反向断言(断言旧键缺位类;现宿主唯一键名引用在 breakpoint_resume_test.gd:159 的 check_quiet 通道,提取器不收),非反向命中=L3 停机;判读结果落实现报告 +- [ ] 撤销证明 R3 留档:`git checkout game/tests/验证集清单.md` → `--diff` 复现 FAIL(消失 67/新增 539)→ 重生成还原复绿 + +### T3 表尾注释+批末收尾(估时 0.05 工作日) + +- 取用:T2 完成(批面定格) +- 产出:level.tres 表尾新注释;三份产出物;三条目删除 + +步骤: + +- [ ] level.tres:16 改「旧 15 张模板池(3 关 × 5)已清出,历史查 git 提交史与 tools/t5_build_templates.py、t17_fanout2_rebuild.py 留档。」(删「随迭代 35 卡②」叙事段;表内零改动) +- [ ] 里程碑步:按改动域选档跑全套闸——本批 diff 将混触 game/、tools/ 与根清单(批末三条目删除),按 run_all_gates.sh 用法说明的混触规则定档,禁止误选单域档跳过流水线闸;全绿 +- [ ] 验收对照表 R1–R7 逐条执行,撤销证明记录(变更点/命令/红输出摘要/还原结论)落实现报告 +- [ ] 产出物落位:`reports/节点图换代收尾批-实现报告-<日期>.md`(含承接计数、退役措辞枚举、直跑条数对拍)、`reports/节点图换代收尾批-代拍板追认单-<日期>.md`、`reports/节点图换代收尾批-反哺点清单-<日期>.md`(≥1 条:test-conventions §8.3 描述句随清单全量化失准)——三份齐方算本卡完结 +- [ ] 待办清单三条目(验证集清单快照重生成/测试宿主改名/level.tres 表尾注释)整条删除 + +## 9 验证闸(改动—验收对照表) + +证明口径=撤销证明(2026-10-24 用户裁定):撤销该改动(回退对应 hunk)→ 跑最窄验证 → 对应断言必须红 → 还原复绿。 + +| # | 需求点 | 改动(文件/行为) | 验收测试 | 层级 | 真实入口 | 撤销证明 | +|---|---|---|---|---|---|---| +| R1 | 改名后 manifest 装载新宿主 | run_all.gd:90+git mv | run_all 全宿主跑绿(全套闸 02 段) | 集成 | run_all.gd manifest 装载 | 仅回退 :90 一行→run_all 直跑红(路径不存在);还原复绿 | +| R2 | 宿主内容零改动 | git mv 本体 | 直跑新名退出码 0、0 失败、条数=改名前基线条数 | 集成 | `--script` 直跑宿主 | 结构性(git diff 仅文件名与 4 处字面量+条数同值双证) | +| R3 | 清单与宿主同口径 | 验证集清单重生成 | `--diff`(缺省源)PASS 零差异、条数 1544 | 工具 | extract_checks.py --diff | `git checkout` 旧清单→`--diff` 复现 FAIL(消失 67/新增 539)→重生成还原 | +| R4 | 退役措辞与旧宿主名清偿 | 重生成+承接映射 | grep 新清单 node_map_templates/first_script/template_pick 预期零命中;template_pick 若命中须全为反向断言并逐条枚举 | 文档面 | grep+判读 | 回退 T0 承接映射段重生成→node_map_templates 2 格复现(#84/#85 处置列)→红→还原;判读部分人工核对兜底 | +| R5 | 头注数据驱动 | render_list 模板段 | 试生成头注含当前短哈希+实测条数,零批次专名 | 工具 | `--out` 试生成+grep | 回退模板段→重试生成→批次专名句复现 | +| R6 | 回填列承接 | --carry-from 段 | 承接计数≈986(以改前 `--diff` 读数 1067−67−14 为理论值)+抽 3 行释义一致 | 工具 | 试生成+抽查 | 回退承接段→重试生成→承接计数 0(全量待填) | +| R7 | 表尾叙事清偿 | level.tres:16 | 注释零「迭代」字样+保留「15 张模板池」「留档」去向句;表加载随全套闸绿 | 文档面 | 人工核对+闸兜底 | 非行为改动,人工核对兜底 | + +测试削弱申报:本批不删不改任何宿主断言判据;清单消失 67 行=宿主侧已不存在断言的账面同步,非断言删除。 + +独立验收审计:审计入口=未参与实现的会话按本表逐条抽查撤销证明记录;报告落 `reports/节点图换代收尾批-验收审计-<日期>.md`,未过禁合并。 + +## 10 异常分级 + +- L1 自救:头注/注释措辞、表格排序、打印格式 +- L2 记录继续:承接计数略低于理论值 986(字面变更 14 对按设计不承接;同指纹重复行折叠);未知新行待填 +- L3 停机呈报:重生成后 `--diff` 不 PASS/退役措辞命中含非反向断言/run_all 因改名红且非 manifest 行所致/直跑条数与基线不一致/任何撤销步未见红(含 R1 缺路径宿主不红) + +## 11 代拍板白名单 + +- 新头注与标题具体措辞(语义=断言快照·冻结·数据驱动) +- 承接指纹实现形态(与 entry_key 同构即可)与承接计数打印格式 +- (待填)行头注说明句措辞 +- level.tres 新注释句读法(语义钉死:删叙事保去向) +- 自引用字面量改写形式(保持既有注释风格) +- 旧清单备份临时件位置(仓库外,禁止入库) + +超出以上范围=呈报,禁自行拍板。 + +## 12 待裁点 + +零待裁点,开工门=U0。两处路线选择依据留档(全案并列与淘汰依据): + +1. 清单路线=**重生成**(淘汰「清单头注记」——test-conventions §8.3 维护锚〔2026-10-22 用户裁〕要求断言改动必须同步清单、清单没跟上的断言改动视同未完成;头注记等于宣告永久不同步,须先改该规则才能走,非本卡可裁) +2. 重生成口径=**缺省三宿主全量**(淘汰迁移面显式 `--src` 清单——迁移宿主集合随断言重排漂移〔迭代 35 卡② 已在迁移宿主内整段重写并新落宿主〕,显式清单需人工维护且与缺省对账口径分叉;清单基点本就缺既有套件面〔提案 §五.7「后续可选项」〕,全量化一次到位;test-conventions §8.3「迁移断言全体」描述句随动列反哺点呈报) diff --git a/待办清单.md b/待办清单.md index fe55f349..009ffbd5 100644 --- a/待办清单.md +++ b/待办清单.md @@ -59,27 +59,27 @@ #### 验证集清单快照重生成——断言索引含退役措辞与旧行号(2026-10-25 登记,来源=审计发现,设计面=工程直入) -**现状**:工程债证据=迭代 35 卡② 验收审计申报(git 历史可考:合回提交 5499eb9c 内的 reports/iter35-卡②-验收审计-2026-10-24.md,该产出物已按吸收即死退役):game/tests/验证集清单.md 是批 B 迁移时的断言文本快照索引,只由 tools/extract_checks.py 手工重生成、不进任何闸;卡② 断言面换代后十余行仍含 first_script/template_pick 等退役措辞与过期行号(实测 first_script 8 处、template_pick 2 处),与宿主现文不符。 +**现状**:工程债证据=迭代 35 卡② 验收审计申报(git 历史可考:合回提交 5499eb9c 内的 reports/iter35-卡②-验收审计-2026-10-24.md,该产出物已按吸收即死退役):game/tests/验证集清单.md 是批 B 迁移时的断言文本快照索引,只由 tools/extract_checks.py 手工重生成、不进任何闸;卡② 断言面换代后十余行仍含 first_script/template_pick 等退役措辞与过期行号(实测 first_script 8 处、template_pick 2 处),与宿主现文不符。已写卡(2026-10-25,卡片=reports/需求卡片-节点图换代收尾批-2026-10-25.md,与「测试宿主改名」「level.tres 表尾注释」两件合卡;写卡实测漂移=清单 1067 条 vs 现提取 1544 条〔消失 67/新增 539/字面变更 14 对〕,template_pick 实测 3 处——登记句「2 处」少数一行;路线裁重生成+缺省三宿主全量口径,依据见卡 §12)。 **归属**:game/tests/验证集清单.md+tools/extract_checks.py(重生成或清单头注记两路,写卡时定) -**状态**:待写卡 +**状态**:待写卡+已写卡 #### 测试宿主改名——node_map_templates_test.gd 已承载生成图确定性断言(2026-10-25 登记,来源=审计发现,设计面=工程直入) -**现状**:工程债证据=迭代 35 卡② 反哺点⑧:game/tests/integration/node_map_templates_test.gd 现承载「生成图确定性断言套」,文件名中的 templates 是模板时代遗留;manifest 登记行=game/tests/run_all.gd:90。改名为 node_map_determinism_test.gd 须同批改 manifest 路径行。 +**现状**:工程债证据=迭代 35 卡② 反哺点⑧:game/tests/integration/node_map_templates_test.gd 现承载「生成图确定性断言套」,文件名中的 templates 是模板时代遗留;manifest 登记行=game/tests/run_all.gd:90。改名为 node_map_determinism_test.gd 须同批改 manifest 路径行。已写卡(2026-10-25,卡片=reports/需求卡片-节点图换代收尾批-2026-10-25.md,与「验证集清单快照重生成」「level.tres 表尾注释」两件合卡)。 **归属**:game/tests/integration/+game/tests/run_all.gd manifest -**状态**:待写卡 +**状态**:待写卡+已写卡 #### level.tres 表尾注释含迭代叙事(2026-10-25 登记,来源=审计发现,设计面=工程直入) -**现状**:工程债证据=迭代 35 卡② 反哺点⑨:game/data/tables/level.tres 表尾注释写「旧 15 张模板池(3 关 × 5)随迭代 35 卡② 清出」,与 doc-conventions §5 禁写变更叙事有张力;卡② 卡片 T3 明令表尾写模板去向注记,故处置面限于叙事形态(删迭代号、保留图源换代事实句),不删去向事实。 +**现状**:工程债证据=迭代 35 卡② 反哺点⑨:game/data/tables/level.tres 表尾注释写「旧 15 张模板池(3 关 × 5)随迭代 35 卡② 清出」,与 doc-conventions §5 禁写变更叙事有张力;卡② 卡片 T3 明令表尾写模板去向注记,故处置面限于叙事形态(删迭代号、保留图源换代事实句),不删去向事实。已写卡(2026-10-25,卡片=reports/需求卡片-节点图换代收尾批-2026-10-25.md,与「验证集清单快照重生成」「测试宿主改名」两件合卡)。 **归属**:game/data/tables/level.tres -**状态**:待写卡 +**状态**:待写卡+已写卡 #### 架构与规范对齐批——代码结构审查发现的文档-实现漂移(2026-10-24 登记,来源=审计发现,设计面=文档轨)