diff --git a/design/gdd/06-待办清单.md b/design/gdd/06-待办清单.md index 8c77f208..9088664d 100644 --- a/design/gdd/06-待办清单.md +++ b/design/gdd/06-待办清单.md @@ -26,7 +26,23 @@ **归属**：缺陷修复 mini-loop（复验+修复待用户令） -**状态**：待办（疑似缺陷，未实机复验） +**状态**：**缺陷确认成立（2026-10-07 本会话静态考证）**——传参面 main.gd:510（开局）/:470（继续上局）均 4 键，接收面 adventure_runner.gd:129-138/215-217 缺省空集，全仓无补偿路径（runner 不读 save/呈现层无二次装配/营地钩子仅刷新投影七条候选逐一排除），真实局同调/X/Y 恒空、仅冒烟夹具 level_autoplay.gd:160-169 喂值，冒烟零覆盖。**已编入迭代 19 卡⓪**（原迭代 20 头卡：2026-10-07 立为迭代 20 头卡，同日曾短暂编入迭代 19 又随其清空撤出，2026-10-08 用户令终并入迭代 19 为卡⓪、执行序第一；含开场行生效值+传参断言+重复行清理）。 + +#### 关卡开场行攻血显示初始表值——缺陷确认（2026-10-07 本会话考证登记） + +**现状**：`main.gd:519-521` 关卡开场行传 `int(db.hero.atk)/int(db.hero.max_hp)` 初始表值，战斗面板用 `level_runner.gd:480` 生效值（含锻造/树加成）——两处数字对不上；「（含面板加成）」后缀（battle_narrator.gd:37-40）只认调试浮窗 pct，局外加成不触发注记。用户 2026-10-07 确认=应显示当前生效值，缺陷成立。 + +**归属**：迭代 19 卡⓪②号项（原迭代 20 头卡②号项，2026-10-08 随卡并迁） + +**状态**：已编入迭代 19 卡⓪，待开工 + +#### 刷新双源 X/Y 语义倒置——待用户裁（2026-10-07 本会话考证登记） + +**现状**：实现语义与用户口径镜像互换——代码：X（装配刷新件源）每碰三选一重置不结转（adventure_runner.gd:658-659，调用点 :568/:984）、Y（营地升档源）整局持久不重置（:77/:130/:216，全文件无重置点）、消费先扣 X 后扣 Y（:706-709）；用户口径：X 持久、Y 每节点重置、先扣 Y。合并显示（X+Y 合计，curio_pick_overlay.set_refresh_display 链路）与穷尽转 GP 两点两侧一致。真实局因主菜单传参缺陷 X/Y 恒 0，语义从未实机暴露。 + +**归属**：迭代 19 卡⓪范围外单列（原记迭代 20，2026-10-08 随卡并迁）——裁甲（按用户口径改实现，几行换位）/裁乙（认代码现状，用户口径更新）后随批落 GDD 机制定义；未裁不动 + +**状态**：待用户裁定 #### 双层 BD 延期与备选内容总登记（2026-10-03 立项——任务书退役保险） @@ -261,11 +277,19 @@ #### 调参批数值点评登记（八型批随批登记） -**现状**：格面资源八型批后随批登记的数值点评——① 增伤型奖励/惩罚幅度 50/25 不对称是否有意；② 削弱型 65/25 同问（且 percent 套个位数取整偏粗——主角攻击 2 点时 ±25% 常取整无感）；③ 回血奖励过薄（值 1、权重全池最低 2）；④ 警觉/行动点修正两新词数值全部 provisional；⑤ 行动经济"满停一轮 = 一刷"节拍在 AP±1 修正下的对账。 +**现状**：格面资源八型批后随批登记的数值点评——① 增伤型奖励/惩罚幅度 50/25 不对称是否有意；② 削弱型 65/25 同问（且 percent 套个位数取整偏粗——主角攻击 2 点时 ±25% 常取整无感）；③ 回血奖励过薄（值 1、权重全池最低 2）；④ 警觉/行动点修正两新词数值全部 provisional；⑤ 行动经济"满停一轮 = 一刷"节拍在 AP±1 修正下的对账；⑥ **格面资源正负兑付倍率差回调（2026-10-07 用户裁）**——2026-10-01「踩雷必须痛」抬档（heal +2/−6、pierce/magic +2/−8 等，负向 3-4 倍于正向）系错误的加难杠杆：难度提升应走怪物性能路线而非抬地图惩罚，下一迭代数值批回调负向倍率；标错/开雷同档同罚维持不动（同批裁）。 **归属**：[难度曲线与Boss](systems/冒险循环/难度曲线与Boss.md)难度曲线调参批 -**状态**：待办（随调参批一并裁决）——**已编入 Alpha 收官 M4 数值批〔未排期，2026-10-07 用户令移出迭代 18 暂不启动〕〔2026-10-06 用户令自迭代 17 卡②移出——不影响 17 在飞开发〕（2026-10-05——裁点已全裁〔2026-10-06 用户令：P1甲/P2甲/P3甲/P4甲〕待 U0：design/research/任务书-M4数值批-2026-10-05.md；五条点评逐条裁决 = 件②）** +**状态**：待办（随调参批一并裁决）——**已编入 Alpha 收官 M4 数值批〔未排期，2026-10-07 用户令移出迭代 18 暂不启动〕〔2026-10-06 用户令自迭代 17 卡②移出——不影响 17 在飞开发〕（2026-10-05——裁点已全裁〔2026-10-06 用户令：P1甲/P2甲/P3甲/P4甲〕待 U0：design/research/任务书-M4数值批-2026-10-05.md；六条点评逐条裁决 = 件②）** + +#### 袋装摇号（格面资源池结构备选——保底型增多后的重构方向）（2026-10-07 登记） + +**现状**：地图战斗资源池保底结构（四档概率 + 按型保底 + 档位保底上限，正主=[地图战斗资源](systems/战斗循环/地图战斗资源.md)候选集合节）以「摇完整板校验补签」的补丁式实现起步——简单够用。备选正规形态 = **袋装摇号**：装板时按各档配额数好牌再洗开发放，保底天然成立、分布精确；代价 = 摇号结构重写 + 偏运硬币/board_skew 两路权重投影须改为袋面投影。启用条件 = 保底登记型增多、补签逻辑复杂化时。来源 = 2026-10-07 地图层题四讨论，用户裁「先挂在 06」。 + +**归属**：[地图战斗资源](systems/战斗循环/地图战斗资源.md)（重评归该层内容批或数值批窗口） + +**状态**：待办（挂号备查，未排期） #### 基线通关率越带，加难杠杆扫描未执行 @@ -290,21 +314,13 @@ **归属**：HUD 批（M-4，批未立项）——已随迭代 17 卡③实施 **状态**：✅ 代码面已交付待实机目检（2026-10-06，迭代 17 卡③暂停层只读入口批——worktree g-plan2-iter17-pause 分支 iter17-pause-20261006，提交 c08a901/fc9eb1e/d44fdd5+收口笔；P1丁常驻角标/P2甲设置层同档 dim 遮罩/P3甲余额+三柜台进度/P4甲零动效直开直关全落；badge 已按 Q10 甲工厂化入 ui_kit 并同步迁营地钥石徽；机检=冒烟 788/0+run_all 17 套+四探针全绿〔含输入锁 case⑯/只读巡检/零动效契约/钥石徽对比度对〕+doc 三闸零新增；**人闸=用户实机目检** design/qa/iter17-pause-human-gate-checklist-2026-10-06.md——过闸后本条销号；Esc 快捷通道维持本清单键盘/手柄条登记随键盘批办理） -#### 第一关亮墨数字直画观感优化（2026-10-01 T17 目检体感登记） +#### 第一关亮墨数字直画观感优化（2026-10-01 T17 目检体感登记——2026-10-07 用户令删除） -**现状**：迭代 9 T4 数字承载切换后第一关=亮墨三档直画（白亮字直接印棕色地板、无色牌垫底），机制可读性过闸（用户实机确认三档冷暖可分、凑近与离屏均可读）；同日 T17 目检体感「表现和描述一样，但非常难看」——直画字与地板的组合观感待优化。第二/三关米色小牌形态未获同类反馈。 +**处置**：2026-10-07 用户令——本条不成立，直接删除（观感类优化归 UI 相关线，逻辑批不做；相关优化实践已做过）。两目检体感（直画字难看/墙底黑线难看）随条目一并销去。 -**归属**：呈现优化批（与高墙墙底阴线观感同批裁量；排 M-4 后排，不卡迭代 9 出口） +#### 高墙墙底细阴线观感优化（2026-10-01 T17 目检体感登记——2026-10-07 用户令删除） -**状态**：待办（2026-10-01 登记；机制/可读轴零触碰，纯观感轴）。**2026-10-05 注**：迭代 16「UI 设计对齐批」任务书已起草（`design/research/任务书-UI设计对齐批-2026-10-05.md`）——棋盘数字墨三档与色牌垫底属本批 §3-N1 对比度收项面（实查 `board_cell_unit.gd:238/262` 字号公式已合规、`:229-234` 垫牌在位），裁点裁决后随批一并呈报。本条维持待办。**2026-10-07 注**：前日迭代 18 编入已由用户令撤回——探讨阶段，待办维持。 - -#### 高墙墙底细阴线观感优化（2026-10-01 T17 目检体感登记） - -**现状**：迭代 9 T3 棋盘渲染落码后高墙承接机制过闸（墙顶原亮度直贴/交界无边框/墙底一条细阴线压格线）；2026-10-01 用户 T17 目检实机体感「有，但是现在放个黑线很难看」——墙底阴线的颜色/粗细/有无待优化。 - -**归属**：呈现优化批（与数字直画观感同批；排 M-4 后排，不卡迭代 9 出口） - -**状态**：待办（2026-10-01 登记；机制轴零触碰，纯观感轴）。**2026-10-05 注**：墙脚阴线色 `E_FACADE_FOOT_COL #342A20` 已列为迭代 16「UI 设计对齐批」§3-N4a 五处漏网裸色之一（`board_cell_unit.gd:79`），收进 `ui_kit.gd` 时原值搬运、零观感变化；任务书=`design/research/任务书-UI设计对齐批-2026-10-05.md`。本条维持待办。**2026-10-07 注**：前日迭代 18 编入已由用户令撤回——探讨阶段，待办维持。 +**处置**：同上条，2026-10-07 用户令删除（原登记内容：迭代 9 T3 高墙机制过闸后墙底阴线颜色/粗细/有无待优化——不再保留待办）。 #### 未开格类型徽章呈现时机（2026-09-18 方向已拍板，待实施批） @@ -312,7 +328,7 @@ **归属**：[地图战斗资源](systems/战斗循环/地图战斗资源.md)极性提案实施批与HUD框架共裁 -**状态**：待办。**2026-10-05 注**：类型色五族已由迭代 16「UI 设计对齐批」§3-N4c 立项 `TG_*` 常量（实查 `ui_kit.gd` 现无 tg 常量，五族以裸 `Color8` 内联于 `bonus_pick_overlay.gd:96-102` / `shop_overlay_view.gd:189`，且缺第五族 aoe `#E25676`）；本条（**格面**未开格类型徽章）与卡顶色带同族不同落点，**不并入本批**，维持待办。 +**状态**：待办。**2026-10-05 注**：类型色五族已由迭代 16「UI 设计对齐批」§3-N4c 立项 `TG_*` 常量（实查 `ui_kit.gd` 现无 tg 常量，五族以裸 `Color8` 内联于 `bonus_pick_overlay.gd:96-102` / `shop_overlay_view.gd:189`，且缺第五族 aoe `#E25676`）；本条（**格面**未开格类型徽章）与卡顶色带同族不同落点，**不并入本批**，维持待办。**2026-10-07 注**：呈现规格简化为组粒度——组间五色相、组内不细分（通用增益组五族不再承诺组内分型；art-bible v3.12）；实施批按组粒度执行。 #### 呈现层残余 <4.5:1 文字位（迭代 16 批外邻接发现，2026-10-06 登记） @@ -320,7 +336,7 @@ **归属**：呈现优化后续批（或 UI 设计对齐批第二轮）；开工 = 用户点名 -**状态**：待办（2026-10-06 曾编入迭代 18 卡②，2026-10-07 用户令撤回——探讨阶段未排批） +**状态**：待办（2026-10-06 曾编入迭代 18 卡②，2026-10-07 用户令撤回——探讨阶段未排批；同日短暂编入迭代 19，随迭代 19 清空一并撤出，是否再排批待用户确认） #### 棋盘格边长三方取值不一致——待扩板定档处置（2026-10-06 登记） diff --git a/design/research/任务书-CI预接线批-2026-10-07.md b/design/research/任务书-CI预接线批-2026-10-07.md new file mode 100644 index 00000000..9526c381 --- /dev/null +++ b/design/research/任务书-CI预接线批-2026-10-07.md @@ -0,0 +1,107 @@ +# 任务书——CI 预接线批（迭代 19 卡③） + +> 版本 v1.2（2026-10-08 远端裁点闭环换代；v1.1=2026-10-07 grilling 全裁定稿）。立项依据=2026-10-07 用户令——自动化验收补齐批 §一 明示不收的 **B6（CI 预接线）** 移交另会话讨论后，本会话拍板立项，约 0.25d。 +> 开工门=**goal 迭代级开工令（一次覆盖五卡）**；worktree=`iter19-ciwire`。**裁点①远端仓库=✅ 2026-10-08 用户裁：暂不建、维持待命**（哪天要 push 再议，届时首跑盯梢清单激活）；裁点② ui_layout 入 CI=候卡①断言交付后裁（不阻塞本批）。 + +## 一、立项背景 + +`.github/workflows/tests.yml` 在库且结构完整：头注释自述「仓库已初始化 git（尚无远端）——本 workflow 在首次 push 到 GitHub 后自动生效」；`on: push/PR → main`；static-scan 段（`game/tests/static_scan.sh`，实存）+ headless smoke 段（`res://tests/run_all.gd`，实存）均在位。但两处欠账： + +1. **场景探针段整块注释**（tests.yml:41-45，示例形态引用 `res://smoke/ui_probe.tscn`、`res://smoke/ui_click_probe.tscn`）——自 2026-10-05 路径修正批（9446302e）后未再动，示例选型已滞后于 probe_gate 现行默认段（input/struct/contrast 三探针，其中 ui_contrast_probe 2026-10-06 才注册）。 +2. **远端仓库计划不在案**：`git remote -v` 为空（本会话实测），CI 从未真正运行；roadmap.md 与 design/gdd/06-待办清单.md 均无「远端仓库计划」登记（grep 实测零命中）——建不建、何时建、公开私有，无一处裁决记录。 + +本批只做**预接线**：把注释段解封成与现行轻闸口径一致的正式 CI 段，并补齐新生探针条目；远端仓库本身是另一个决策，只作呈报项挂出（§九）。 + +## 二、现状考证（file:line 级，开工复核） + +| 事实 | 出处 | +|---|---| +| 探针段整块注释（示例 ui_probe/ui_click_probe） | .github/workflows/tests.yml:41-45 | +| 头注释自述「尚无远端，首次 push 后自动生效」 | tests.yml:3 | +| git 无远端 | `git remote -v` 空（2026-10-07 实测） | +| tests.yml 末次改动=2026-10-05 文档对齐批（9446302e，路径 game/ 化修正） | git log tests.yml | +| 注释段两示例路径实存未漂移 | game/smoke/ui_probe.tscn、ui_click_probe.tscn 逐一 ls 核过 | +| probe_gate 默认段三探针 .tscn 实存：ui_input/ui_struct/ui_contrast | game/smoke/ 逐一 ls 核过 | +| ui_struct_probe=2026-10-05 注册（mini-loop）；ui_contrast_probe=2026-10-06 注册（UI 设计对齐批 T2） | 两 .gd 头注 | +| ui_audit_probe=2026-10-06 用户令新生，**必须窗口化**（headless 守卫同 shot_probe） | game/smoke/ui_audit_probe.gd:1-4 | +| probe_gate 是 Windows 专用（PowerShell+taskkill+cygpath），CI ubuntu-latest 不能调用 | tools/probe_gate.sh:11,28-34 | +| probe_gate 对三默认探针的判定=exit code 超时判 + **grep PASS**（退出码单凭不足恃） | tools/probe_gate.sh:50-74 | +| 冷检出需刷导入（.godot 不入 git）——probe_gate 用 `--editor --quit` 一次性付 | tools/probe_gate.sh:36-41 | +| 渲染闸批（同迭代兄弟卡）触碰文件=worktree/tools/render_gate.sh(新)/game/tests/golden//probe_gate.sh/CLAUDE.md/tests/README/roadmap——**T0-T6 逐条核过，不含 tests.yml**，无直接撞车 | design/research/任务书-自动化验收补齐批-2026-10-07.md §四 | +| 远端仓库计划零登记 | roadmap.md、06-待办清单.md grep「远端/remote」零命中 | +| ⚠ **触发分支死角（v1.1 并入）**：tests.yml 触发=[main]，实际分支=master 且 main 分支不存在（git branch 实查 2026-10-07）——不修则远端建好后 CI 仍永不触发 | tests.yml on: 段；git branch | + +### 探针分拣清单（CI 段选型的依据，开工复核用） + +| 归属 | 探针 | 理由 | +|---|---|---| +| **进 CI 探针段（轻段）** | ui_input_probe / ui_struct_probe / ui_contrast_probe | headless 安全+带断言=probe_gate 默认段同款；ui_contrast 系 tests.yml 末次改动后新生，必须补入 | +| **不入轻 CI，归 --full 重闸**（兄弟卡 T3 收编层位，P5 已裁） | ui_probe / ui_tune_probe / t17_defer_probe / fx_probe（+ui_click 随 --click） | 时长 17-63s×4，挂重闸不拖轻 CI；示例句里的 ui_probe/ui_click 据此**不进 CI 段**——注释段选型滞后处 | +| **禁入 headless CI** | shot_probe / fx_shot_probe / board_shot_probe / ui_audit_probe | 必须窗口化，headless 无渲染面且探针内 fail-fast | +| **不入任何闸** | ui_layout_probe（兄弟卡 T5 补断言，归属见待裁 P2）、skill_rhythm_probe / board_stat_probe（零断言分析工具，且无 .tscn）、damage_probe / config_fatal_probe（兄弟卡 T4 退役件） | — | + +## 三、范围 + +**收**：tests.yml 注释段解封改写为正式探针段（三默认探针+冷检出导入步+timeout/PASS 双判定外壳）；**触发分支修正 push+pull_request 两处 main→master**（2026-10-07 用户裁 Q1/Q11.3）；头注释「远端就绪即生效」明示；账务登记两处；远端仓库计划呈报项成文。 +**不收**：远端仓库建不建/何时建/公开私有（呈报项，用户裁）；static-scan 步骤与 run_all 冒烟步骤**本体**零改动（job 级基础设施步=冷检出导入步允许插在 checkout 之后——2026-10-07 用户裁 Q9 甲）；probe_gate.sh 任何改动（归兄弟卡 T3）；游戏运行时代码与探针件任何 diff。 + +## 四、任务卡 + +- **T0（0.05d）开工复核**：tests.yml 现行行号复读；§二分拣清单所列 .tscn 逐一存在性重核；兄弟卡 worktree 状态核对（若在飞，登记避让位）；**PASS 判定串取样**——本机实跑三探针取输出格式样本钉死 grep 判据（白名单项）。 +- **T1（0.10d）注释段解封改写**：tests.yml:41-45 注释块换成正式步骤——①冷检出导入步（`godot --headless --path game --import` 或 `--editor --quit` 形态，代拍板白名单），插在 smoke job **checkout 之后、run_all 冒烟步骤之前**（job 级基础设施步，同时覆盖冒烟与探针的 .godot 依赖）；②三探针逐条登记（ui_input/ui_struct/ui_contrast，每步 `timeout` 外壳 + 退出码超时判 + PASS 判定，镜像 probe_gate 判定逻辑的 Linux 形态；**探针步骤留在 smoke job 内原注释位**，复用同 job setup-godot 不另开 job）；③头注释「尚无远端」句保留并追加「远端仓库建好后**无需改本文件即自动生效**」明示；④触发分支 `push.branches` 与 `pull_request.branches` 两处 `[main]`→`[master]`。**CI 段为 Linux 独立命令形态，禁止调用 probe_gate.sh**（PowerShell/taskkill 依赖）。 +- **T2（0.05d）静态核验**：pyyaml 解析 tests.yml（本机在库，actionlint 不要求）；CI 段引用的每个 res:// 路径存在性脚本核对；timeout 外壳齐备清单逐条打勾；与兄弟卡新三闸术语（headless 轻闸/render_gate 渲染闸/--full 重闸）口径对齐检查。 +- **T3（0.05d）账务+移交项成文**：roadmap 迭代 19 行邻行并入本卡登记（避撞兄弟卡在飞行）；B6 出处（自动化验收补齐批 §一）闭环注记；「首次 push 后人工盯首跑」移交清单落本任务书 §七。 + +**合计≈0.25d**，与用户拍板一致。 + +## 五、🔴 设计契约（违反=返工；触碰=L3 停机） + +1. **本批 diff 面=tests.yml 单文件**（+roadmap 账务行）：游戏代码、探针件、probe_gate.sh、CLAUDE.md 零 diff。 +2. **CI 轻段选型锁死**：只进 input/struct/contrast 三件；ui_probe/ui_click/ui_tune/t17_defer/fx 禁入轻 CI（兄弟卡 P5 裁决归 --full）；窗口化四件（shot/fx_shot/board_shot/ui_audit）禁入 headless CI——违者与探针 fail-fast 护栏冲突=必红。 +3. **无远端红线**：禁止为「端到端验证 CI」擅自建远端或 push——远端是独立决策（§九）；本批验收只能是静态核验，谁也不许绕。 +4. **在飞避让**：主区脏文件与兄弟卡 worktree 勿碰；roadmap 迭代 19 行四卡换代按**落籍顺序串行重放**、后合者 worktree 内 rebase（2026-10-07 用户裁 Q13）。 +5. **判定外壳不降级**：每个探针步骤必须 timeout 外壳+PASS 判定双在位（ADR-0004 硬性要求；只跑不判=返工）。 + +## 六、停机点 + +- **S1**：静态核验若发现 tests.yml 结构性问题（setup-godot action 版本漂移/失效、upload-artifact 路径口径变动等），呈报后再动，不顺手代修范围外段。 +- **S2**：兄弟卡若先行合并且三闸术语已换代，本批文案与旧口径冲突时停机对表再落笔。 + +## 七、验收闸与移交项 + +**验收（全部静态判据——本地无远端，端到端不可验，此为本批红线边界）**： + +1. tests.yml 无整块注释探针段残留（41-45 行区域已成正式步骤）。 +2. CI 探针段引用的每个 res://smoke/*.tscn 在 game/smoke/ 实存（逐一路径核对记录随出口注记）。 +3. 每个探针步骤 timeout 外壳+PASS 判定齐备；头注释含「远端就绪即自动生效」句。 +4. pyyaml 解析通过。 +5. roadmap 邻行并入登记+B6 闭环注记落籍；git status 本批 diff 仅 tests.yml+账务行。 + +**移交项（首次 push 后人工盯首跑清单，本批不履行只移交）**： + +- 首跑三查：static-scan 绿 / smoke 段绿 / 新探针段绿。 +- Linux 环境差异预判：ui_contrast_probe 依赖字体渲染实测值，ubuntu runner 字体环境与 Windows 本机不同，首跑若红属环境差异非回归，逐条呈报处置。 +- 冷检出导入步首跑耗时观察（probe_gate 本机经验=一次性 1-2 分钟，CI 上未实测；导入步已按 Q9 甲前置插入 smoke 步骤之前，smoke 段冷检出红灯风险已预消，首跑仍需实证）。 + +## 八、裁点留痕（0 项阻塞——全裁/后置） + +- **裁点①远端仓库计划**：✅ 2026-10-08 用户裁=**暂不建、维持待命**（建否/何时/公私三问一并裁为「暂不建、不定期、届时再定」）；预接线待命态=本批终态，§七首跑盯梢清单待远端立项之日激活。 +- **裁点② ui_layout_probe 入 CI 归属**：候卡①（渲染闸批）为其补 1280/1920 断言交付后再裁，不阻塞本批。 + +## 九、远端仓库——已裁留痕（2026-10-08） + +现状：`git remote -v` 为空；roadmap.md 与 06-待办清单.md 零登记；tests.yml 头注释是全仓唯一「远端」陈述。**✅ 已裁（2026-10-08）=暂不建、维持待命**——本批交付的预接线配置即为终态，哪天用户决定 push 远端时：建仓库与首次 push 由用户亲手做，届时另呈首跑盯梢（§七移交项随之激活）；再往后若改主意要建，另编卡。 + +## 十、代拍板白名单 + +CI 步骤命名与注释措辞；冷检出导入步形态（`--import` vs `--editor --quit`）；timeout 数值（默认沿用 probe_gate 同款 120s/探针）；PASS 判定串（随探针实际输出格式，T0 本机实跑取样钉死）；探针步骤落位=smoke job 内原注释位（复用同 job setup-godot，不另开 job）；探针日志是否并入现有 upload-artifact 段；roadmap 邻行并入的具体措辞。 + +## 十一、呈报摘要 + +- **B6 CI 预接线已立项为本卡**（迭代 19 第二卡，兄弟卡=自动化验收补齐批；其 T0-T6 触碰文件逐条核过，不含 tests.yml，无直接撞车）。 +- tests.yml 场景探针段（41-45 行）整块注释且选型滞后：示例的 ui_probe/ui_click 按兄弟卡 P5 裁决归 --full 重闸、**不进轻 CI**；轻 CI 应进=input/struct/contrast 三件（ui_contrast 系 2026-10-06 新生，必须补入）。 +- 注释段引用的两探针路径实存未漂移；窗口化四件（shot/fx_shot/board_shot/ui_audit）禁入 headless CI。 +- probe_gate.sh 是 Windows 专用，CI 段须 Linux 独立命令形态（timeout+grep PASS 双判定+冷检出导入步）。 +- **本地无远端，端到端验证不可能**——验收全静态（pyyaml/路径存在性/timeout 外壳），「首次 push 后人工盯首跑」成移交清单；首跑预判 Linux 字体环境或致 contrast 红属环境差异。 +- **远端仓库计划不在案**（remote 空+两文档零登记）：建不建/何时建/公开私有，三项呈请用户裁决，本批不代决。 +- 步骤 T0-T3，估时合计 **≈0.25d**；待裁点 **2 项**（P1 远端计划、P2 ui_layout 入 CI 归属）。 diff --git a/design/research/任务书-提灯载体道具批-2026-10-07.md b/design/research/任务书-提灯载体道具批-2026-10-07.md new file mode 100644 index 00000000..2aa1bcfc --- /dev/null +++ b/design/research/任务书-提灯载体道具批-2026-10-07.md @@ -0,0 +1,184 @@ +# 任务书——提灯载体道具批（迭代 19） + +> 版本 v1.2（2026-10-08 裁点全裁换代；v1.1=2026-10-07 grilling 三轮全裁定稿）。 +> 立项依据=用户拍板（2026-10-07）：**提灯死接口缺口作为独立卡立项、编入迭代 19**——原登记去向「Alpha 信息件重定批」就此改道（改道留痕见 §一）。 +> **✅ 裁点全裁（2026-10-08 用户令）：①载体选型=案A（秘宝·同调位新行，按推荐）②缺陷处置=另卡先行（=迭代 20「主菜单开局缺陷修复批」，确认随同一 goal 先行跑，其落籍=本卡 T1 前置门）③商店分类条件点随案C 落选自然消解**。开工门=**goal 迭代级开工令（一次覆盖五卡=迭代 20 卡A+本迭代四卡）**；唯一残留交互=T0 行字段推荐值呈报（名称/文案/稀有度等）秒答「按推荐」即全收。worktree=`iter19-lantern`。 + +## 一、立项背景与改道留痕 + +**缺口现状**：视野迷雾机制（HUD框架「视野迷雾」节，正主定义）已实装，提灯视野外扩 +2 的**接线面**已就位（迭代 14⑤），但**全游戏无任何道具/途径能让玩家拿到提灯——功能不可达，完成度 0**。`board_view.gd:139` 注释自述「+2 预留不接效果——效果载体归 Alpha 信息件批」。 + +**改道留痕（本批立项即登记，执行批 T4 落文刷新指路句）**：提灯载体自 2026-09-30 迷雾立项配套拍板起，登记去向一直为「aux_items 新行，随 Alpha 信息件重定批一并登记」（HUD框架 v0.13 配套拍板 / board_view.gd:139·:145 注释 / art-bible.md:387 / qa 出口报告 m4iter14 §⑤ 四处在案）。2026-10-07 用户令：**改道为独立卡编入迭代 19**，不再等 Alpha 信息件重定批。连带口径：①原「Alpha 信息件重定批」中显影尘/地穴全图卷的能力封存重定义务**仍留在原批、不随本批代行**（两件事分卡，避免"两个变量一批"读数纪律冲突——先例=初始展开收窄批 §6.3 与提灯批分开归因）；②迭代 19 自动化验收补齐批 §一「明示不进本批：B4 提灯死接口……归 Alpha 信息件重定批」一句随本批立项自然失效，该文为历史成文不改，本节即留痕。 + +**消歧（防混淆，主控已核实）**：仓库名字带"灯"的唯一现役物件 `greedy_lantern`（feats.tres:291「贪婪矿灯」）是 dig_reveal yield_mult 专长——开格产出放大，**与视野无关**，本批不碰该行；提灯点亮视觉（人设腰灯/棋盘光晕）挂「资产升档重产批」与「提灯点亮解禁候选」（06 立绘升档条挂起项）既有挂账，本批不接。 + +## 二、在册裁决检索结果（口头裁决检索在先义务履行记录） + +动手前已检索 design/gdd/06-待办清单.md、roadmap.md、design/gdd/systems/ 全目录，结论： + +| 检索对象 | 结果 | +|---|---| +| 06-待办清单 | **无「魔法提灯 / 提灯载体 / 视野限制」在册条目**（唯一沾边=立绘升档条内挂起项「提灯点亮解禁候选」，纯视觉、与本批无关；研究文档曾引用的 06「视野限制 / 初始展开收窄 / 魔法提灯」条目已随收窄批立项收口移除——roadmap 迭代 14 行「06 视野条目已于 745b92ea 清账批退役」在案）。**无已裁未录事项，本批不是重复立项** | +| roadmap.md | 迭代 14⑤=提灯 +2 接线小卡**已落地**（接线面+断言，载体明示不造）；初始展开收窄批迭代 14① **已实装**（2026-10-05，出生 5×5）——收窄抬难在前、提灯减难在后，§6.3「相邻序位分开出口读数」的归因条件天然满足 | +| design/gdd/systems/ | HUD框架「视野迷雾」节=唯一正主定义（v0.13 配套拍板=灯甲形态 +2 flat、**类型微光不随视野扩**、载体归 aux_items 新行）；秘宝.md v1.2 三层职责分界（操作包络加强类语义契合本效果）；奇物.md ⚠ **专长体系推倒重设计中**冻结横幅（影响备选案 B） | +| 关联调研 | 调研-全局作用域变异设计空间-2026-10-04.md §3 案E **冻结**——「灯光收缩形与提灯撞车：同一杠杆第三家抢用」；案E 解封条件三件之一=「提灯接线落位」，本批落地即推进该解封条件。研究-初始展开收窄可行性-2026-10-04.md §4：Dredge 灯笼升级=视野外扩作为可成长信息件的成熟先例 | + +## 三、现状考证（file:line 级，开工复核） + +| 事实 | 出处 | +|---|---| +| 死接口本体：`FOG_LANTERN_BONUS=2` 常量在位；`_fog_lantern` 缺省 0=无提灯基线零扰动；半径算式已消费 | game/presentation/views/board_view.gd:138-141 | +| 公共接线面：`set_fog_lantern(enabled)`（true=半径 8+2、false=复原 0；写入即 refresh 全板重算雾态） | game/presentation/views/board_view.gd:146-148；半径算式 :818-823（`fogged := fdist > FOG_RADIUS + _fog_lantern`） | +| 断言防腐层：case⑮ 直接调 setter 断言开=dist R+1 格转可见+lantern=2／关=复原——**与载体无关，载体级断言须扩展** | game/smoke/ui_input_probe.gd:395-418 | +| 全仓 `set_fog_lantern` 调用面：仅 board_view 定义处 + ui_input_probe——**生产路径零调用**=死接口实锤 | 全仓 grep 2026-10-07 | +| BoardView 实例化组合根：`board_zone_view.gd:39`（战斗屏装配链）；探针/单测另有三处直构 | game/presentation/views/board_zone_view.gd:39 | +| **载体通道①秘宝·同调位**：表=treasure_items.tres（registry 键 `aux_items`）；九件现役（被动六+主动三），获渠=营地道具工坊同调装配，slot_cost 恒 1、位硬上限 3（attunement_growth.tres 里程碑求值）；被动件走效果引擎订阅行（on/when/do 三字段，16 效果类型封闭词表） | game/data/tables/treasure_items.tres；game/core/treasure_items.gd；秘宝.md「现行形态速览」 | +| 同调存档面现成：save v4 三新域 boss_kill_count/attunement_equipped/attune_refresh_level，断点充能随档 | game/core/save_manager.gd:42·:80·:124·:314-322 | +| 同调入战斗通路：runner `set_attunement` → enc 携带 → `begin_battle` 注入 `attunement` 数组+`_attune_has(item_id)` 判定在位（private）；`_fx.rebuild(feat_ids, attunement, tree_rules)` | game/core/adventure_runner.gd:937·:1079；game/core/battle_orchestrator.gd:75-77·:124-131·:225-250 | +| ⚠ 同调传参缺陷**已实查定案**（2026-10-07 另会话取证，非疑似）：`_start_adventure` 是唯一开局漏斗（main.gd :421/:430 两入口全走 :510），参数面只传 hero_override/first_script/treasure_unlocked/shop_mode 四键，**未传 attunement/attune_refresh_level/tree_rules 三键**，补偿路径七条全无——**全部开局入口均丢同调**，非仅菜单开局 | design/gdd/06-待办清单.md「菜单开局未传同调装配与局外树规则」条+另一会话取证报告；game/presentation/main.gd:510 | +| **载体通道②专长**：表=feats.tres（27 行，archetype/rarity/triggers 订阅行）；获渠=关底 Boss 击败专长三选一 + 专长门票（商店 feat_ticket 行/奖励节点罕见门票，拿到即开不进持有集）；当局持有集 `_feats` 跨关携带、收束清零、断点 relics_seed 恢复现成 | game/data/tables/feats.tres；game/core/adventure_runner.gd:85·:137-142·:289-298·:379-396 | +| ⚠ 专长冻结横幅：奇物.md 头注「专长体系推倒重设计中……落笔完成前专长相关章节只作历史参照，不作新建依据」——往专长加新件须先获用户豁免 | design/gdd/systems/冒险循环/奇物.md:16 | +| **载体通道③商店货架**：shop.tres pool_shelf 六行封闭词表（attack/max_hp/armor/ap/feat_ticket/heal）；价公式 `ceil(base_price × b^(关序−1) × A^(本次进店已购))`；账本=冒险结构 `_bonus_taken` 单点共享 | game/data/tables/shop.tres:68-94·:103-109 | +| **载体通道④合并案素材**：显影尘 probe_dust 行 deferred「能力封存」在表（effect_kinds 空行先例——表允许无效果行在位）；探巢摆钟/爆破工兵包=active_charged 语义（使用期生效，与视野持续态冲突）；工兵晨令=轮限被动 | game/data/tables/treasure_items.tres:9-19·:40-72·:151-173 | +| 奇物分类判据（商店/奇物渠道牵连）：「给规则的是专长，给数字的是属性值提升，给余量的是资源」——视野外扩三类都不贴，走该渠道须新裁分类判据 | design/gdd/systems/冒险循环/奇物.md §1.4 | +| 提灯效果语义正主：灯甲形态（光照圈外扩 +2 格，flat 整数档）；类型微光不随视野扩（微光锚=可挖域贴身 8 邻） | design/gdd/systems/表现与支撑/HUD框架.md:168·:170 | +| 效果语义出处链（+2 的定位）：迷雾立项配套拍板④裁「灯甲视野外扩 +2、类型微光不随视野扩」；FOG_RADIUS 常量改动=非白名单须用户 | board_view.gd:138-139 注释；HUD框架 v0.13 | +| 体验验证联动信号在册：「迷雾联动信号（记忆态使用率）：视野外扩道具（魔法提灯 +2）与记忆态的使用频率变化」 | design/gdd/07-体验验证清单.md:138 | +| 形象候选池正主：铲/旗/背包/提灯四件随身件=秘宝形象候选池（用户 2026-09-23 提案登记，彩蛋闭环=玩家在道具栏认出主角腰间同款）——提灯作为秘宝件有形象登记先例 | design/art/character-design.md:48 | + +## 四、范围 + +**收**：提灯载体道具的载体选型落定后的——数据行落表（依裁决案）、载体到 `set_fog_lantern` 的生产路径接线（组合根/呈现桥）、存档面（依案，多数现成）、测试扩展（case⑮ 载体级断言+集成）、文档落籍与改道留痕刷新（§一）。 +**不收**：+2 数值本身的重议（FOG_LANTERN_BONUS=2 为 2026-09-30 拍板值，载体只决定"怎么拿到"，不决定"给多少"）；类型微光任何改动（拍板④钉死不随视野扩）；提灯点亮视觉（挂账不动）；显影尘/地穴全图卷能力封存重定（留原 Alpha 信息件重定批）；全局变异案E 解封重议（本批只是推进其解封条件之一）；贪婪矿灯 feats 行（消歧见 §一）。 + +## 五、载体备选案全列（裁决呈报面——设计权归用户，本节不代定案） + +### 5.1 现役通道盘点 + +| 通道 | 数据表 | 获取通路 | 生效周期 | 存档面 | +|---|---|---|---|---| +| 秘宝·同调位 | treasure_items.tres | 营地道具工坊同调装配 | 永久持有、每局装配生效 | save v4 attunement_equipped（现成） | +| 专长 | feats.tres | Boss 击败三选一／专长门票 | 当局（收束清零） | 断点 relics_seed/_feats（现成） | +| 商店货架 | shop.tres pool_shelf | 商店房 GP 购买 | 当局 | `_bonus_taken` 账本（视野件需扩） | +| 奖励节点三选一 | adventure.tres 候选令牌 | 奖励节点（道具件令牌池现行空集休眠） | 当局 | 同专长/资源令牌面 | +| 元进度树 | meta_tree.tres | 账号级购点 | 跨局永久 | tree_nodes（现成） | + +### 5.2 备选案 + +**案 A——秘宝·同调位新行（HUD框架配套拍板的原登记指向；推荐）** +- **获取渠道**：营地道具工坊「同调装配」段装配入位，slot_cost 1（与九件同规）；同调位经 attunement_growth.tres 里程碑解锁（0 起步硬上限 3）——获取成本=占一个稀缺同调位的机会成本，零新机制。 +- **稀有度定位**：与探巢摆钟/爆破工兵包并列的工兵系功能件；「魔法提灯」名号与九件气质（工兵/工程向）同族；**形象候选池有正主**（character-design.md:48 提灯四随身件=秘宝形象候选池，彩蛋闭环）。 +- **与其他视野机制的叠加关系**：灯光区 8+2=10 与微光两圈分立（微光不扩，拍板④零触碰）；与真视 3×3 护栏无涉（视野是呈现边界不是格面信息——不进叠加层、不触「真视窄域≤3×3」加载校验）；与已实装的初始展开收窄（出生 5×5）构成减难补偿对，收窄在前本批在后、归因已分开。 +- **接线与存档工作量**：treasure_items.tres 新行（form=passive、**triggers 空**——视野是纯呈现层不订阅任何结算事件，不走效果引擎，规避 16 效果类型封闭词表扩表）；呈现桥=呈现侧（board_zone_view 装配链）从 orchestrator **公共只读访问器**（`_attune_has` 契约化出口，save v6 只读访问器先例——2026-10-07 用户裁 Q6，enc 透传案弃）判「装配集含提灯」→ `set_fog_lantern(true)`；复原语义=**每次 begin_battle 装配链按装配集显式重算 set_fog_lantern(含否)**，禁依赖战斗结束隐式复原（断点续玩/跨关天然正确——Q8.1）；存档零新增（attunement_equipped 现成）。 +- **测试面**：case⑮ 增载体级段——装配含提灯的 enc 起战斗→`fog_params_probe()["lantern"]==2` 且 dist R+1 格转可见；空装配基线 lantern==0 零扰动；单测补 treasure_items 行加载校验。集成断言挂 smoke。 +- **风险**：①⚠ **同调传参缺陷已实查定案且影响全部开局入口**——不修则营地装配的提灯在任何开局路径下都不生效，案 A 功能目标破产；**已裁（2026-10-07，2026-10-08 确认）=缺陷另卡先行（迭代 20 缺陷批随同一 goal 先跑），其落籍=本卡 T1 前置门（§八 S1）**；②同调位竞争（3 位上限内九选 N+1，数值面=玩家侧取舍，不算风险）；③「三层职责分界」新契约核对——秘宝=操作包络加强（视野/行动点/刷新/挖掘距离），视野外扩恰属操作包络，**语义契合正向**。 + +**案 B——专长新行（feats.tres，archetype=dig）** +- **获取渠道**：关底 Boss 击败专长三选一（每关一次兑付）或专长门票（商店 feat_ticket/奖励节点罕见门票）。 +- **稀有度定位**：feats.rarity 三档（common/rare/rarest）自选一档呈报；dig 流派已有贪婪矿灯/矿脉直觉等先例，「灯」字面易与贪婪矿灯混淆（§一消歧须落文案）。 +- **叠加关系**：同案 A（视野呈现边界机制面一致，与载体无关）；当局清零=每局重新掷取，视野保障不稳定——三关可能一件都拿不到，**功能可达性不保证**。 +- **接线与存档工作量**：feats.tres 新行（订阅行三字段——但视野不在 17 事件/16 效果类型词表内，**须扩封闭词表或旁路效果引擎**，两者都是内容数据驱动批的词表修订级改动）；持有集/断点现成；呈现桥同案 A（读 `_feats`）。 +- **测试面**：同案 A 形态，判据改持有集含提灯 feat。 +- **风险**：⚠ **专长体系推倒重设计中（奇物.md 冻结横幅）**——27 件全数待重设、重设计主权归用户，本批往冻结区加新件须先获豁免，且重设计落地时本件随批重设=返工敞口；词表扩表牵动内容数据驱动批架构纪律。**不推荐**，除非用户有意把提灯归入"当局构筑变强"轴。 + +**案 C——商店货架商品（shop.tres pool_shelf 新 kind_id 行）** +- **获取渠道**：商店房 GP 购买（价公式现成：`ceil(base × b^(关序−1) × A^已购次数)`）。 +- **稀有度定位**：与 feat_ticket/heal 并列的货架新 kind；base_price 与 GP 期望账联动（L2 商店前期望 ≈35-40 的既有账须复核加一货架后的取舍空间）。 +- **叠加关系**：同案 A；商店可重复购买→须裁「买第二件是否叠加半径」（推荐=不叠加，flat +2 单次生效——**这是新增裁决面**）；当局生效、跨关携带（商店购买写在冒险账本）。 +- **接线与存档工作量**：shop.tres pool_shelf 新行（六行封闭词表扩一行）；**奇物分类判据须新裁**——视野外扩不进属性数值（非 ASI）、不改规则（非专长）、按「给余量」勉强归资源但资源四项枚举（行动点上限/刷新/GP/回复）也无此形（§十 W3）；视野件不进加算区，需当局持有账本新挂点；呈现桥同案 A。 +- **测试面**：同案 A 形态+商店购买链路集成断言（买→下一场战斗 lantern==2）。 +- **风险**：分类轴新裁+叠加规则新裁两处框架级裁决；货架经济账复核义务；「买视野」与秘宝「操作包络件」的职责分界重叠——同一效果两处可放，用户须裁谁让位。 + +**案 D——合并案：显影尘行激活重定（不开新载体）** +- **获取渠道**：同调位装配（显影尘行已在表，deferred→激活换装）。 +- **稀有度定位**：复用既有行位；「魔法提灯」与「显影尘」二名取一或一名双效果，命名归用户。 +- **叠加关系**：同案 A。 +- **接线与存档工作量**：最省——一行改 deferred=false+定效果字段，接线同案 A；但显影尘原语义=「恢复推理原料（显影/信息）」与「灯光区呈现边界外扩」是两类效果，若定成双效果（显影+视野）则一行两义。 +- **测试面**：同案 A。 +- **风险**：⚠ **用户已拍板本缺口独立卡立项、与显影件重定分道**——本案实质是把两条线重新并轨，违背改道裁决的原意（改道理由=不等信息件批）；显影尘/地穴全图卷的其余重定面（能力封存的全图信息定位）会被本批部分代行，读数归因混杂。**仅在用户明示"顺便把显影尘一起定了"时成立**，否则列为淘汰向。 + +**案 E——元进度树节点（meta_tree.tres，跨局永久视野 +2）** +- **获取渠道**：账号级天赋树购点（tree_nodes 已购等级现成）。 +- **稀有度定位**：树节点一档，永久生效。 +- **叠加关系**：同案 A；但永久 +2=**全玩家恒定灯光区 10**，等价于改 FOG_RADIUS 基线——迷雾「移动逐步照亮」的探索感常驻弱化，收窄批四带读数基准漂移（每局恒 +2 无对照组）。 +- **接线与存档工作量**：tree_rules 已进 `begin_battle`（orchestrator `_fx.rebuild` 第三参），呈现桥读 tree_rules 同案 A；存档现成。 +- **测试面**：同案 A，判据改 tree_rules 含节点。 +- **风险**：与立项本意（"载体**道具**"）偏差最大——没有"拿到"的过程与取舍；难度读数无法归因（永久变量混入全部后续带）；FOG_RADIUS 基线语义被旁路改写（常量改动=非白名单须用户的纪律被实质绕开）。**不推荐**，列出供完整性。 + +### 5.3 淘汰案与依据 + +| 淘汰案 | 依据 | +|---|---| +| 宝箱保底／掉落投放复活 | 「挖格不掉道具」2026-10-01 已退役、过渡投放池现行零行、奖励节点道具件令牌池空集休眠（秘宝.md 投放态注记）——复活退役渠道违反渠道退役裁决，且保底=无供给稀缺性，载体价值感消失 | +| 提灯专用关卡／专用节点 | 渠道轴无此形态（奇物渠道三枚举+商店+同调位）；为单件道具重造关卡类型与关卡节点图生成器语义冲突，成本收益倒挂 | +| 常驻基线（FOG_RADIUS 8→10，不开道具） | 功能可达但「载体道具」立项本意落空——无获取过程、无取舍；FOG_RADIUS 改动=非白名单须用户且实质作废收窄批「初始展开恰等」验收原样主张；**不是道具方案，是改迷雾机制方案**，另案不混 | +| 全局变异行（variation.tres scope=global） | 调研-全局作用域变异 §3 案E 已冻结——「灯光收缩形与提灯撞车：同一杠杆第三家抢用」，解封条件三件在案且解封后归全局变异批 Own，不在本批 | +| 地形变异反制件挂靠 | 反制契约 2026-10-03 用户终裁作废（层级错配失败设计），counter_items 恒空合法 | +| 纯视觉点亮（人设腰灯亮起，无效果） | 不解决功能可达（雾半径不变）；点亮视觉本身另挂「提灯点亮解禁候选」（06 挂起项）与整屏样张闸 | + +### 5.4 推荐排序 + +**案 A > 案 D（条件）> 案 C > 案 B > 案 E**。案 A 是配套拍板的原登记指向、形象候选池有正主、三层职责语义契合、存档接线全现成。**✅ 已裁（2026-10-08 用户令）=案 A**；案 B/C/D/E 落选留档备查。行字段推荐值清单（display_name/desc 文案/rarity/行 id/slot_cost/门槛位——2026-10-07 用户裁 Q7）=T0 呈报、秒答「按推荐」即全收（provisional 投值，出口追认），**不留二次裁量停机**。 + +## 六、任务卡（T0 末 S0 停机；T1-T5 前提=S0 已裁，裁决前不执行） + +- **T0（0.25d）**：worktree `iter19-lantern`；§三 现状考证逐条开工复核（file:line 漂移核对）；**行字段推荐值呈报**（载体已裁案A——呈报=display_name/desc 文案/rarity/行 id/slot_cost/门槛位推荐值清单）→ 停机等秒答「按推荐」（goal 中唯一预期交互点）。 +- **T1（0.5d，案A 定值）** 〔前提=迭代 20 缺陷卡已落籍+行字段秒答〕：treasure_items.tres 新行（form=passive、triggers 空，空 triggers 行合法性随显影尘先例）；schema 校验面核对。 +- **T2（0.5d）**：呈现桥接线——orchestrator 装配集只读出口契约化（或 enc 透传，方式归代拍板）→ board_zone_view 装配链判含提灯→ `set_fog_lantern(true)`，战斗结束/卸装复原 false；缺省零扰动基线保持（不装配=lantern 0=现行为逐位不变）。 +- **T3（0.5d）**：测试扩展（三形态钉死，2026-10-07 用户裁 Q8.2/8.3）——probe=**case⑮ 内**加载体级段（装配含提灯→自动生效断言，不开新 case；迭代 14⑤ 接线段并进 case⑮ 先例）；呈现桥判定=**注入装配集 stub 的单测**（game/tests/ 惯例位）+行加载单测；smoke=**现有套件加断言不新开套件文件**（装配→战斗→雾参数贯通）；存档回归（装配→停点→回局 lantern 态一致）。 +- **T4（0.5d）**：文档落籍——HUD框架 视野迷雾节「实施状态」注记换代（载体到位+接线闭环）；秘宝.md 目录九件→十件（裁案 A/D）；board_view.gd:139·:145 注释「归 Alpha 信息件批」改「迭代 19 提灯载体批落籍」；art-bible.md:387 同句刷新；06 登记（若案 A 则顺带核对「菜单开局同调传参」条与 W2 裁决的一致性）；改道留痕以本任务书 §一 为准。 +- **T5（0.25d）**：收口——重闸全绿（轻闸+run_all）；MC 对拍=**静态论证不实跑**（提灯纯呈现层、off 态零生产路径变化，逐点推演落出口报告；渲染闸卡「MC 零跑静态论证」先例——2026-10-07 用户裁 Q3，实跑须走跑批批准制故弃）；出口报告落 design/qa/；roadmap 迭代 19 行补本卡落地注记（§十一 避让）。 + +## 七、🔴 设计契约（违反=返工；触碰=L3 停机） + +1. **效果语义零新增**：+2 flat=FOG_LANTERN_BONUS=2 既有拍板值，禁改数值、禁改半径算式、禁动 FOG_RADIUS 基线（常量改动=非白名单须用户，board_view.gd:138 纪律句沿用）。 +2. **纯呈现边界**：排雷玩法/minesweeper_rules 零 diff；同板同动作序列无提灯/有提灯（不装配）两态结算逐位一致——case⑮ 既有断言面是回归底线，禁删减。 +3. **类型微光不随视野扩**（拍板④）：微光锚=可挖域贴身 8 邻，本批零触碰。 +4. **设计权归用户**：载体选型已裁案A（2026-10-08）；获取渠道随案A=同调装配；行字段（稀有度/文案/门槛数值）=T0 呈报秒答落定；执行批不得以"实现便利"代行任何一项；provisional 投值随出口报告追认。 +5. **改道留痕与指路句同步**：「归 Alpha 信息件重定批」活性指路文本随 T4 刷新（§一记「四处」、本节原记「HUD框架两处」系口径矛盾——**以 T0 实查计数为准、逐处列清单**，禁新旧口径并存）；历史成文（qa 报告、research 旧文档）原样保留不改。 +6. **在飞避让**：迭代 19 渲染闸卡在飞（其触碰面见 §十一）；worktree 隔离，主区脏文件勿碰勿代提交，roadmap 迭代 19 行四卡换代按**落籍顺序串行重放**、后合者 worktree 内 rebase（2026-10-07 用户裁 Q13）。 +7. **复原语义**（Q8.1 钉死）：每次 begin_battle 装配链按装配集显式重算 `set_fog_lantern(含否)`，禁依赖战斗结束隐式复原。 +8. **营地与槽位视觉**：新行沿用现役程序化回退，零新素材（提灯点亮视觉挂账边界同 §一）。 +9. **测试三形态钉死**（Q8.2/8.3）：probe=case⑮ 内扩展不开新 case；呈现桥判定=装配集 stub 单测；smoke=现有套件加断言不新开套件文件。 + +## 八、停机点 + +- **S0**：T0 末**行字段推荐值呈报停机**——载体已裁案A，呈报面=行字段推荐值清单（唯一停机问询点）；不秒答不进 T1。 +- **S1**（前置门，2026-10-07 裁+2026-10-08 确认随同 goal 先行）：**同调传参缺陷修复卡（=迭代 20「主菜单开局缺陷修复批」）落籍=T1 前置门**——缺陷已实查定案、影响全部开局入口，不修则案 A 功能目标破产；缺陷卡未落籍则 T1 不开工，本批不代修（缺陷卡随同一 goal 先跑、天然满足）。 +- **S2**：用户若要求随批产出提灯点亮视觉资产——超出本批范围（挂账面见 §一），停机重议扩范围或维持挂账。 + +## 九、验收断言清单（本批完成定义） + +1. 裁决案的数据行在表且加载校验通过（schema 白名单零违例）。 +2. 生产路径贯通：裁决载体在位→战斗内 `fog_params_probe()["lantern"]==2`、dist==R+1 环带转可见；载体缺位→lantern==0 且现行为逐位不变。 +3. ui_input_probe 载体级断言全绿且既有 case⑮ 断言零删减（实查计数 17，T0 复核为准）；smoke 集成与存档回归全绿。 +4. 重闸全绿+MC 对拍零扰动（off 态逐位一致基线保持）。 +5. §七.5 四处活性指路句全部换代、零旧口径残留（历史成文除外）。 +6. 出口报告落 design/qa/（含 provisional 追认单+行字段秒答记录）；roadmap 迭代 19 行换代。 + +## 十、裁点留痕（0 项未裁——全裁，编号仅存档用） + +- **裁点①载体选型**：✅ 2026-10-08 用户裁=**案A**（秘宝·同调位新行，按推荐）；案 B/C/D/E 落选留档 §五。 +- **裁点②缺陷处置**：✅ 2026-10-07 裁=另卡先行（=迭代 20「主菜单开局缺陷修复批」）；2026-10-08 确认随同一 goal 先跑，其落籍=本卡 T1 前置门（§八 S1）。 +- **裁点③商店分类+重复购买叠加**：随案C 落选自然消解，无裁点。 +- 唯一残留交互=T0 行字段推荐值秒答（「按推荐」机制，非裁点）。 + +## 十一、与兄弟卡避让（迭代 19 渲染闸卡=自动化验收补齐批） + +| 维度 | 结论 | +|---|---| +| 代码文件交集 | **零**——渲染闸卡触碰 tools/、game/tests/golden/、probe_gate/render_gate 脚本、tests/README、CLAUDE.md、数据配置.md:205 指路句；本批触碰 game/data/tables/、game/core/（出口契约化视案）、game/presentation/views/、game/smoke/ui_input_probe.gd。game/smoke/ 目录级同域但文件级不相交（渲染闸卡只收编探针进闸不改探针文件本体，实查其任务卡 T3 确认） | +| 文档交集 | roadmap.md 迭代 19 行两卡都要换代（渲染闸卡 T6 换主行、本批 T5 补卡注记）——按「邻行冲突分支内并入」先例处理；HUD框架 本批独改（渲染闸卡不碰 gdd） | +| 时序 | 五卡同批（迭代 20 卡A 先行+本迭代四卡）、独立 worktree 各自合并，roadmap 行换代按落籍顺序串行重放（Q13）；本批 T1 硬等缺陷卡落籍+T0 行字段秒答，天然错峰 | + +## 十二、估时与切分 + +T0-T5≈**2.5d**（载体已裁案A：T1 取 0.5d 定值，词表扩表案 B/C 落选）。天然切分点 **T0 末行字段秒答**——段一 T0（考证+呈报，0.25d）可与缺陷卡并行先行；段二 T1-T5（实装+收口，2.25d）等缺陷卡落籍+秒答后一次合并。 + +## 十三、呈报摘要 + +- **在册裁决检索结果**：06-待办清单无提灯载体条目、无已裁未录事项；提灯载体自迷雾立项（2026-09-30）登记去向为「aux_items 新行、随 Alpha 信息件重定批」，接线面与 case⑮ 断言已于迭代 14⑤ 就位（2026-10-05），载体始终未造=功能不可达完成度 0。2026-10-07 用户拍板独立卡编入迭代 19、与信息件批改道分卡，留痕见 §一。 +- **备选案概览**：现役通道五案——案 A 秘宝同调位新行（原登记指向，形象候选池有正主，推荐）、案 B 专长新行（撞专长重设计冻结横幅，不推荐）、案 C 商店货架（分类判据需新裁）、案 D 显影尘行激活合并（与改道裁决相逆，条件成立才用）、案 E 元进度树（永久变量破坏读数归因，不推荐）；淘汰案六件（掉落保底/专用关卡/常驻基线/全局变异/反制挂靠/纯视觉）各附依据（§5.3）。 +- **估时**：T0-T5≈2.5d（案A 定值），切分点 T0 末行字段秒答（考证呈报 0.25d／实装收口 2.25d）。 +- **裁点**：0 项未裁——裁点①载体=案A（2026-10-08）/裁点②缺陷另卡先行=迭代 20 缺陷批随同 goal 先跑/裁点③随案C 消解；残留交互仅 T0 行字段秒答。 +- **契约要点**：+2 数值与半径算式零改动；纯呈现边界+类型微光不扩钉死；设计权全归用户；与迭代 19 渲染闸卡代码文件零交集、roadmap 邻行并入。 diff --git a/design/research/任务书-旧界面呈现断言回补批-2026-10-07.md b/design/research/任务书-旧界面呈现断言回补批-2026-10-07.md new file mode 100644 index 00000000..a0330cb9 --- /dev/null +++ b/design/research/任务书-旧界面呈现断言回补批-2026-10-07.md @@ -0,0 +1,114 @@ +# 任务书——旧界面呈现断言回补批（迭代 19 卡②） + +> 版本 v1.1（2026-10-07 grilling 三轮全裁定稿；v1.0 成文同日）。立项依据=主控 2026-10-07 拍板：迭代 16 之前落地的 UI 屏没有对比度/结构机检（旧屏只靠当时人工目检背书），值得追溯补测，估 0.5-1d。**待裁点 0 项**（全裁理由见 §八）。开工门=**迭代 19 迭代级 U0（一次覆盖卡①②③，卡④另受 S0 独立门）**；worktree=`iter19-uibackfill`。 + +## 一、立项背景 + +- ui_contrast_probe（对比度机检）2026-10-06 迭代 16ui T2 出生（b38ae07，初版 11 对），迭代 18 卡④随批 +3 对成现役 15 对（dc2d514）；ui_struct_probe（结构机检）2026-10-05 ui-struct-probe mini-loop 出生（d77a245），后随迭代 17 卡③（pause 契约 d44fdd5）、迭代 18 卡④（career 四契约 dc2d514）、卡⑦（resume 专项 c32bb6c/5b3a8fd）增补。 +- 两探针虽已进 probe_gate 默认段，但**测点对与专项契约是「随批登记」制**——谁落地谁登记。旧屏（营地/商店/设置/结算框等）落地时两探针尚未出生，出生后也无人回补：对比度测点对至今零覆盖旧屏文字位；结构侧专项契约（只读/零动效/登记序等）仅 pause/career 两屏有。 +- 迭代 18 有先例证明此缺口会漏真违例：career 页初版深墨族 token 压深棕亮底 ~1.3:1（「深墨跨壳误用」），加测点对首跑即抓，批内返工落闸（dc2d514）。 +- 本批性质=**测试覆盖回补，非缺陷修复批**：实现代码本身无已知问题，回补断言后若暴露存量违例，登记呈报、处置权归用户。 + +## 二、现状考证（file:line 级，开工复核） + +| 事实 | 出处 | +|---|---| +| 测点表现役 15 对，**登记地=探针文件自身 `_pairs()` 表**（惯例：名称+UiKit 常量实时求值+α 混成参数；「测点表随批维护」） | game/smoke/ui_contrast_probe.gd:17-35（头注 :2-5） | +| 15 对构成：战斗 HUD 7 对（血数垫牌/意图四墨/C区槽两态/RAP）+全站锚 3 对（INK/PANEL_DATA、WARM/BG_ROOT、WARM_FAINT/STAGE_BG）+徽章工厂 1 对（营地徽+暂停层余额行）+生涯页 3 对 | ui_contrast_probe.gd:20-34 | +| 静态段（裸 Color8 白名单=空表+素材 preload=0）全 presentation 目录扫描，与测点对互补 | ui_contrast_probe.gd:11-14,77-105 | +| struct 采样根现役 13 个：start（+双列契约⑤）/settings/camp/career（+四契约⑩-⑬）/confirm/debug/level_map/battle_hud（board_zone[含 ap_bar]+info_panel+stage[含 battle_log]）/pause（+契约⑧⑨）/battle_end/curio_pick/shop（+resume 专项⑦） | ui_struct_probe.gd:29-135,506,329 | +| **struct 从未采样**：legend_overlay、node_overlay（两枚真模态，有真实开合路径）、toast_stack（瞬态）、settlement_review_overlay（遗留件未接线，全仓零引用） | main.gd:254-265,1245-1248；rg 全仓核验 | +| 视野迷雾记忆墨：手算在册 ≈6.7:1 合规（记忆板 α.66 压 floor avg #453020 合成底），但**无机检对** | views/board_cell_unit.gd:258-264；ui_kit.gd:81-82 | +| 商店货架 iter16 换过分族带（TG_* 五族）——换色发生在对比度探针出生当批，货架牌底组合从未入测点表 | af5f317（2026-10-06）；ui_kit.gd:49-53 | +| 营地打开=全量重建三柜台行+同调装配段+天赋树段+最近冒险（天赋树行板在开屏态即可见→已被 struct 采样面含） | views/camp_overlay_view.gd:224,120,177 | +| battle_log_view 并入 B 区舞台（struct 经 stage 根覆盖）；settlement_review_overlay 遗留件（M9 退役后遗留） | views/battle_stage_view.gd:34,121；roadmap 迭代 17 行 | +| 背景事实一处订正：struct 探针出生 2026-10-05（mini-loop d77a245），非迭代 16；且其通用断言族（overlap/等宽/出屏/零尺寸）**已回溯覆盖** camp/shop/settings/battle_end 等旧屏——真缺口在①对比度测点对零覆盖②专项契约只有 pause/career③legend/node 屏从未过结构族。本批范围据此校正 | git log --follow ui_struct_probe.gd；ui_struct_probe.gd:29-135 | +| 迭代 18「深墨跨壳误用」先例：新测点对首跑暴露存量违例→批内返工（本批红线改为登记不修） | dc2d514 提交说明 | +| 旧屏出生批：09-24 垂直切片转正批 18 件（camp/shop/battle_end/board 族/legend/node/toast/ap_bar 等）、level_map 09-28、settings+confirm 09-29、curio+debug 10-05——全部早于两探针出生 | git log --diff-filter=A 逐件核验 | + +## 三、普查表（迭代 16 前落地屏 × 两探针覆盖现状） + +| 屏 | 落地 | 对比度测点对 | struct 覆盖 | 备注 | +|---|---|---|---|---| +| 战斗 HUD（board_zone/info_panel/stage/ap_bar） | 09-24 | 7 对+锚 3 对（覆盖最全） | ✔ battle_hud 根 | 基准 cohort | +| 战斗结算框 battle_end | 09-24 | **0 对** | ✔（battle_end 根+resume ⑦） | 每场必经 | +| 商店 shop | 09-24 | **0 对**（TG_* 分族带未测） | ✔ | 换色后未机检 | +| 营地柜台+天赋树 camp | 09-24/重构 10-04 | **0 对**（仅徽章 1 对间接） | ✔（开屏全量态） | 停留最长 | +| 设置面 settings | 09-29 | **0 对** | ✔ | 警示文 INK_HINT 未测 | +| 三选一 curio | 10-05 | **0 对** | ✔ | 人工目检较新 | +| 图例 legend / 节点结算 node | 09-24 | 0 对 | **✘ 从未采样** | 结构真缺口 | +| 视野迷雾（board_cell_unit _draw） | 09-24 | 0 对（手算在册 ≈6.7:1） | 不适用（非控件） | 便宜的锚定对 | +| 战斗日志 battle_log | 09-24 | 0 对（归 HUD 族间接） | ✔（stage 根） | M9 后单行摘要态 | +| toast / debug / confirm / start / level_map | 09-24~10-05 | 0 对（start/level_map 有全站锚+样张冻结记录 GOLD_DONE） | toast ✘（瞬态）其余 ✔ | 定性豁免为主 | +| settlement_review | 遗留件 | — | ✘ 未接线 | **出批**，归退役处置另议 | + +## 四、范围 + +**收**：①选中屏（§五前五名+迷雾锚定对）ui_contrast 测点对回补入 `_pairs()` 表；②ui_struct 补采样 legend_overlay+node_overlay（真实开合路径驱动）+按需 WL 豁免登记。 +**不收**：旧屏代码任何改动（含断言暴露的存量违例——登记呈报不修）；settlement_review_overlay 处置（遗留件另议）；toast/debug 等瞬态与调试面的测点对；probe_gate.sh 任何改动（两探针已在默认段）；07 清单改排。 + +## 五、补测优先级排序（独立核证，可推翻主控初步倾向） + +排序轴=玩家停留时长+文字密度+历史目检遗留风险（落地越早、此后换色越多风险越高）： + +1. **战斗结算框**——每场战斗必经+读数停留（GP 合计/统计行/按钮），09-24 最老 cohort，0 对。**与主控倾向一致**。 +2. **商店**——商品名/价格/属性描述/已购态文字密度高，iter16 当天换过 TG_* 分族带却从未机检（换色后无哨兵=最真实的遗留风险），0 对。**与主控倾向一致**。 +3. **营地柜台+天赋树**——单次停留最长的屏（购买/同调/树行 33 节点文本），文字密度全场最高之一；iter12 重构（10-04）大改后仅人工目检。**此处推翻主控倾向：settings 降位、camp 升 3**——settings 停留短/文字少/09-29 落地较新，camp 三项轴全面占优。settings 保留在收测名单（第 4 位），不做取舍争议。 +4. **设置面**——警示文 INK_HINT 与选项标签，1-2 对低成本收掉。 +5. **三选一 curio**——选项名/描述/价签，停留短但 0 对，顺路收。 +6. **迷雾记忆墨锚定对**——手算已合规，入表仅为把手算读数变机检哨兵（α 混成机制现成），近零成本。 +7. **legend/node**——缺口在结构侧不在对比度侧（文字少）：struct 补采样即可，对比度不加对。 + +## 六、任务卡 + +- **T0（0.1d）**：建 worktree；基线复读记档（probe_gate 全绿+contrast 15 对/struct 13 根现状）；复核 §二表 file:line（漂移即停记）。 +- **T1（0.25d）高优先双屏测点对**：battle_end（标题墨/正文墨/按钮墨对结算底）+shop（商品名/价格/属性描述五族 TG_* 对货架牌底/已购态）候选对入 `_pairs()` 表——一律 UiKit 常量实时求值；代拍板白名单=①具体取点位选择②每屏对数在验收带内微调③测点命名措辞（2026-10-07 用户裁 Q5.2）。验收=probe_gate 默认段绿；若红→§十 S1。 +- **T2（0.25d）中优先三屏+迷雾**：camp（等级章字 INK_ON_DEEP/树行名/价格墨/最近冒险条目）+settings（警示文/选项标签）+curio（选项名/描述）+迷雾记忆墨合成对（FOG_MEMORY_INK 对 α.66 记忆板混成 floor 底）。验收=同 T1。 +- **T3（0.25d）struct 补采样**：legend_overlay（ap_bar legend_toggled 真路径开→closed 关）+node_overlay（show_rest 合成喂入→continue_pressed 关）两根入 `_audit` 流，通用五族断言即生效；首跑红→WL 豁免逐条核注理由或 §十 S2 呈报。验收=struct 13 根→15 根全绿。 +- **T4（0.15d）收口**：轻闸全绿+冒烟基线复跑（T0 记档基线持平）+**出口报告落 `design/qa/iter19-uibackfill-exit-report-<日期>.md`**（批次标准清单义务；违例呈报清单若有随附）；settlement_review_overlay 遗留件在 **06 登记退役处置条目**（「另议」落位不留悬空）；roadmap 本卡行换代（§九 ②）。验收=全绿+零旧屏 diff（git 核验=仅两探针文件+roadmap+06 登记行）。 + +**估时合计 ≈1.0d**（上限贴用户预估；违例呈报清单整理时间另计不扩批）。 + +## 七、🔴 设计契约（违反=返工；触碰=L3 停机） + +1. **旧屏代码零 diff**：本批只许动 game/smoke/ui_contrast_probe.gd、ui_struct_probe.gd 与 roadmap 本卡行。断言暴露的存量对比度违例一律登记呈报不当场改——处置权归用户（与迭代 18 career 先例的「批内返工」不同，本批是回补批非修复批）。 +2. **测点对惯例**：一律 UiKit 常量实时求值（禁硬编码 hex——代码换色即闸红）；α<1 走现有混成参数；豁免条目须行尾注理由。 +3. **struct 零删减**：现有 13 根采样段/五族断言/pause-career 契约族/resume 专项原样保留；WL 豁免新增须注理由，零理由登记=返工。 +4. **探针纪律**：种子钉死惯例沿用（struct 显式填 42，迭代 18 卡⑦五探针审计条款在册）。 +5. **在飞避让**：主区脏文件、迭代 19 渲染闸卡全部触碰面（§九）勿碰勿代提交。 +6. **WL 豁免边界**（2026-10-07 用户裁 Q10.2）：仅「断言语义与该屏设计意图冲突」类可豁免（如瞬态动画中采样）；疑似真违例一律 S2 呈报，**禁止自行 WL 消音**。 +7. **迷雾记忆墨合成对底色**（2026-10-07 用户裁 Q10.1）：三关底色取**最亮者**求合成（最坏情况判据）；T0 实查三关同底则单对。 + +## 八、待裁点（0 项） + +全裁理由：①屏清单=普查表全量核证产物，主玩家面（前 6 项）无一有取舍争议，仅优先级排序调整（settings→camp 换位）属主控明示授权「可推翻」范围；②违例处置权红线已定（登记呈报归用户），非开工前裁点；③与迭代 19 渲染闸卡文件交集为零（§九），无协调裁决需求；④编卡位（迭代 19 邻卡）归主控例行编排权，本任务书只给建议不裁。开工后仅 §九两停机点可能升级呈报。 + +## 九、与迭代 19 渲染闸卡的文件交集与避让条款 + +渲染闸卡（roadmap.md:75）触碰面：tools/render_gate.sh（新）、tools/probe_gate.sh（头注释纪律句改写+--full 段）、tools/shot_checker.py、game/tests/golden/（新）、game/smoke/四渲染探针、tests/README.md、CLAUDE.md、roadmap 迭代 19 行。 +本批触碰面：game/smoke/ui_contrast_probe.gd、ui_struct_probe.gd、roadmap 本卡行。 +**交集=roadmap.md 邻行换代一处**——避让条款：①本批零触碰 probe_gate.sh（contrast/struct 已在默认段，头注释「测点表随批维护」句对本批语义自洽，无需改写）；②roadmap 迭代 19 行四卡（①渲染闸/②本卡/③CI 预接线/④提灯载体）都要换代——默认序卡①最先，实际按**落籍顺序串行重放**、后合者在 worktree 内 rebase 解行冲突（2026-10-07 用户裁 Q13）；③渲染闸卡的 shot_checker B 类（截图文字对比度）与本批测点对是**互补非重复**（前者整屏像素判定、后者 token 实时求值）——若渲染闸先落地且其 B 类首跑报出与本批重叠的违例，两边呈报清单合并去重后统一呈用户，避免双通道同案双报。 + +## 十、停机点与验收闸 + +**停机点**： +- **S1**：新测点对首跑若暴露存量对比度违例（≥1 对 <4.5:1）——逐条全量清单呈报，处置权归用户（登记存量 vs 另立修复批）。首跑判定是本批最大不确定性：旧屏文字位从未机检过。 +- **S2**：legend/node 首跑结构断言若红（两屏从未过结构族）——同 S1 呈报；合法豁免入 WL 注理由，缺陷呈报不修。 + +**验收闸（本批完成定义）**： +1. `_pairs()` 表 15 对→约 25-32 对（**预期带非闸值**），闸=新增对覆盖 §五前 6 项每屏 ≥1 直接测点对，probe_gate 默认段全绿。 +2. struct 采样根 13→15（+legend/node）全绿；WL 新增条目均有理由注。 +3. git diff 范围核验=仅两探针文件+roadmap 本卡行，旧屏代码零 diff。 +4. 若有违例：呈报清单落出口登记（不修）。 +5. 冒烟基线持平（T0 记档值为准）+**probe_gate 默认段总时长增幅 ≤2s**（闸值；本批为静态求值+两屏采样，预期远低于此）。 + +--- + +## 呈报摘要（给主控） + +1. **普查结论**：旧屏 11+ 枚中，struct 通用族已回溯覆盖绝大多数（出生 2026-10-05 非 10-06，背景事实订正）；真缺口=①对比度测点对旧屏 **0 对**（15 对现役全属 HUD/锚点/徽章/生涯）②专项契约仅 pause/career 有③legend/node 两屏从未过结构族④迷雾记忆墨只有手算无机检⑤settlement_review 系未接线遗留件，出批归退役另议。 +2. **优先级（独立核证，部分推翻主控倾向）**：战斗结算框 > 商店 > **营地柜台+天赋树** > 设置面 > 三选一 > 迷雾锚定对；legend/node 只补结构不补对比度。推翻点：camp（停留最长+文字最密+iter12 重构后仅目检）升 3，settings（停留短/落地较新）降 4 但保留在收测名单。 +3. **估时**：T0-T4 ≈1.0d（贴预估上限；违例呈报整理另计）。 +4. **红线**：只加断言零改旧屏；违例登记呈报不修（处置权归用户；与迭代 18 career 批内返工先例区分）。 +5. **避让**：与迭代 19 渲染闸卡文件交集仅 roadmap 邻行一处；probe_gate 零触碰；shot_checker B 类与本批互补非重复，呈报合并去重。 +6. **待裁点 0 项**（§八全裁理由）；停机点 2 处（S1 对比度首跑存量违例/S2 legend-node 结构首跑）。 diff --git a/design/research/任务书-自动化验收补齐批-2026-10-07.md b/design/research/任务书-自动化验收补齐批-2026-10-07.md new file mode 100644 index 00000000..36cb1f8a --- /dev/null +++ b/design/research/任务书-自动化验收补齐批-2026-10-07.md @@ -0,0 +1,97 @@ +# 任务书——自动化验收补齐批（迭代 19） + +> 版本 v1.1（2026-10-07 成文；同日**拷打轮一 Q1-Q8 全裁「按推荐」后升版**，裁决记录见 §九；低争议组五项一并落文）。 +> 立项依据=2026-10-07 全迭代两阶段验收盘点报告（仅自动化口径：功能性验收=单元/冒烟/行为探针/MC 对拍；展示性验收=结构/对比度/布局/截图/像素机检，**不含人工目检**）。 +> 开工门=U0（用户发令）。**待裁点 0 项**——P1-P5 与拷打轮一 Q1-Q8 均已裁（§九）。 + +## 一、立项背景（盘点结论摘要） + +全迭代自动化验收的缺口集中在三处（此处只收 A 级+C 级）： + +1. **渲染像素闸长期缺位**：`tools/probe_gate.sh` 头注释明文「shot_probe 禁入本闸（headless 无渲染面）……归真人目检」——窗口化截图族（shot_probe/fx_shot_probe/board_shot_probe）从未进任何自动闸；迭代 15③ 起五件渲染闸（golden_compare/shot_probe/fx_probe/ui_layout_probe/board_shot）明示屏蔽，补跑挂 07⑮ 至今无履行记录。`tools/golden_compare.py` 工具在库但**黄金图基线零在库**。 +2. **探针游离在闸外**：ui_probe / ui_tune_probe / t17_defer_probe / fx_probe 四件带断言探针不在 probe_gate/run_all/CI 任何自动链，只能手动敲命令——回归无哨兵。 +3. **账务漂移**：tests/README.md 写「752+ 断言/十五套件」，实测 smoke_all.gd 静态 746 处 check、run_all.gd manifest 17 条；冒烟「834/0」系运行时计数——两种口径无对照说明。tests/integration/ 仅 README 无实体。 + +**迭代 15③ 挂账「渲染五闸」逐件归宿对账**（本批后五闸全部有归属，07⑮ 机器补跑半随之核销）： + +| 五闸成员 | 本批归宿 | +|---|---| +| shot_probe | T1 render_gate（扩屏后）→ shot_checker A-D 判定 | +| golden_compare | T2 基线入库+接线进 render_gate | +| board_shot | T1 render_gate 取证段（Q7：失败=红）+ T2 golden 判定 | +| fx_probe | T3 probe_gate `--full`（headless 逻辑层断言，非渲染件） | +| ui_layout_probe | T5 补 1280/1920 两档最小断言（ui_struct_probe 实查仅当前视口单档跑——分辨率维度无重复建设） | + +**明示不进本批**：B4 提灯死接口（验收已在位=ui_input_probe case⑮，缺的是载体道具本体，归 Alpha 信息件重定批）；B5 旧界面呈现断言回补、B6 CI 预接线——移交另会话讨论，裁后若立项另行编卡。 + +## 二、现状考证（file:line 级，开工复核） + +| 事实 | 出处 | +|---|---| +| probe_gate 默认段=input/struct/contrast 三探针，`--click` 可选加跑；头注释含「shot_probe 禁入本闸……归真人目检」纪律句 | tools/probe_gate.sh:5-9 | +| 四探针实跑现状全绿（2026-10-07 本机 headless 实测）：ui_probe 17.4s / ui_tune_probe 49.6s / t17_defer_probe 63.0s / fx_probe 21.9s，合计≈152s | game/smoke/ 对应 .tscn 入口 | +| shot_probe 现仅四屏（menu/camp/level/battle），输出缺省 `user://qa-screens`，最小自检=存在且非零字节，像素断言归 shot_checker；headless 有 fail-fast 护栏 | game/smoke/shot_probe.gd:2-27 | +| **board_shot_probe 截整屏视口**（`get_viewport().get_texture()`），非棋盘区裁剪——golden 对比前须加裁剪步骤 | game/smoke/board_shot_probe.gd:55-57 | +| shot_checker.py 断言面 A-D 机检可判（A 屏级骨架/B 文字对比度 ≥4.5:1/C 明度三档带/D 文字禁压纹理；E 焦点预算=语义面归人闸），取样坐标源=shot_meta.json | tools/shot_checker.py 头注 | +| golden_compare.py 在库、黄金图基线零在库；.gitignore 仅挡 `artwork/`，game/tests/golden/ 入库无阻 | tools/golden_compare.py；.gitignore:49-50 | +| ui_struct_probe 仅当前视口单档跑，无 1920 证据——ui_layout 两档断言有真增量 | game/smoke/ui_struct_probe.gd:430 | +| config_fatal_probe 与 run_all 已登记 config_db_fatal_oob_test 断言面重复；**且 2026-10-02 代码质量修复批已呈报其退役待裁（未裁，本批还账）** | game/smoke/config_fatal_probe.gd；active.md 台账 312 | +| **数据配置.md:205 引用 config_fatal_probe 为 Fatal 语义验证载体**——退役必须连带改指路句 | design/gdd/systems/表现与支撑/数据配置.md:205 | +| damage_probe A1 红灯=改前既有（诊断件非验收件）；**M4 数值批 roadmap 行引用其修复义务——出闸留盘不影响该引用** | design/qa/m4iter14-mineq-exit-report §四.7 | +| registry 无测试闸登记处（仅 architecture/entities 两 yaml）——收口账面只落 roadmap/07 | design/registry/ 实查 | +| 主区在飞脏文件 15+（含 roadmap.md 迭代 19/20 改行）未提交 | git status 2026-10-07 | + +## 三、范围 + +**收**：A 级全量（渲染闸自动化+扩屏+黄金图基线入库+四探针收编+重闸纪律扩容+退役件处置）+C 级账务（README 漂移/integration 目录/诊断件标注）。 +**不收**：B4/B5/B6（§一）；游戏运行时代码任何改动；轻闸默认段断言面任何删减；1920 档独立跑（Q4 裁：单档 1280，留注记）。 + +## 四、任务卡 + +- **T0（0.25d）**：建 worktree `iter19-verify`；基线复读记档（轻闸+run_all+四探针时长复测）；git status 归属核对（在飞脏文件只标旗不碰）。 +- **T1（1.25d）渲染闸脚本**：新增 `tools/render_gate.sh`——窗口化自动闸，骨架复用 probe_gate（timeout 守卫/孤儿 Godot 预清后清/退出码闸/残留清点）。段组成：①**shot_probe 扩屏后**（Q3：新纳生涯页/暂停层/设置面；商店房可达性考证后定，不可达则注记留 B 批）四屏+N 屏截图 → shot_checker.py A-D 断言自动判定；②fx_shot_probe 三时刻抓帧、board_shot_probe L1-L3 棋盘抓帧——**取证段失败语义=闸红**（Q7：超时/零字节/文件缺失任一即 FAIL，不做像素判定但「渲染真实发生」必须成立）；③基准档 1280 单档（Q4），1920 留注记；④过程截图落 `user://qa-screens` 用后即弃（Q2），**任何过程 PNG 禁入 git**。 +- **T2（0.75d）黄金图基线入库**：board_shot L1-L3 整屏帧先按 **shot_meta.json 取样坐标裁剪棋盘区**（禁硬编码像素）再生成基线入 `game/tests/golden/`（测试资产入库先例，.gitignore 已核不挡）；golden_compare.py 接线进 render_gate（容差 provisional）；**基线生成前置条件=素材齐盘，素材缺位即 L3 停机（S3）——基线严禁锚在字形回退态**（Q5）；基线换代权限=呈现类改动批内 agent 自行换代+提交说明强制写明触发原因，数值/逻辑批禁碰（Q6）。 +- **T3（0.5d）探针收编+纪律改写+重闸扩容**：probe_gate.sh 增 `--full` 段=ui_probe+ui_tune_probe+t17_defer_probe+fx_probe（轻闸默认段不变）；头注释「渲染闸归真人目检」纪律句删除改写为新三闸口径；**CLAUDE.md loop 规范 §5 重闸定义正式扩容**（Q1）：重闸=轻闸+doc 三闸+熵增+MC+**render_gate+probe_gate --full**——不写入规范=新闸继续游离。 +- **T4（0.25d）退役件**：config_fatal_probe 删除（.gd+.uid）+**连带改数据配置.md:205 指路句改指 config_db_fatal_oob_test**（2026-10-02 代码质量批呈报退役的还账；active.md 台账历史记录不动）；damage_probe 保留在盘、头注标注「诊断工具·非验收件」，出一切闸清单（M4 行引用其修复义务不受影响）；全仓引用清查（CLAUDE.md/tests README/smoke README）。 +- **T5（0.5d）零断言件与账务**：ui_layout_probe 补 1280/1920 两档最小断言（四区矩形不越界/不重叠；有真增量见 §二）；skill_rhythm_probe/board_stat_probe 头注标注「分析工具·非验收件」；tests/README.md 漂移修正（套件数 17、断言双口径说明）+**integration 空壳目录删除、章程句并入 tests/README**（Q8，吸收即死）。 +- **T6（0.5d）收口**：重闸全绿（轻闸+`--full`+render_gate+run_all+doc 三闸/熵增）+主区合并复跑（含 render_gate）+出口报告+账面两处：07⑮ 机器补跑半核销注记（目检半仍归用户不销号）、roadmap 迭代 19 行换代（registry 无闸登记处，已实证，无登记动作）。 + +## 五、🔴 设计契约（违反=返工；触碰=L3 停机） + +1. **游戏运行时代码零 diff**：本批只许动 tools/、game/tests/、game/smoke/ 探针件与文档。探针断言暴露的存量呈现缺陷一律登记不修（S1），修复另立项。 +2. **轻闸默认段零删减**：probe_gate 现行 input/struct/contrast 断言面与 `--click` 语义原样保留；`--full` 只增不改。 +3. **golden 基线边界**：只入 `game/tests/golden/`；**基线严禁在素材缺位（字形回退态）下生成**（S3）；基线换代须提交说明写明触发原因；数值/逻辑类批禁止动基线。 +4. **过程产物即弃**：golden 基线之外的一切截图 PNG 落临时区用后即弃、禁入 git（Q2）。 +5. **在飞避让**：主区 15+ 脏文件（含 roadmap.md）勿碰勿代提交；本批 worktree 隔离，合并 roadmap 撞行按「邻行冲突分支内并入」先例。 +6. **改纪律落文**：probe_gate 头注释改写与 CLAUDE.md 重闸扩容须在 T3 内同步完成，禁止新旧两套口径并存（Q1）。 + +## 六、停机点 + +- **S1**：render_gate 首跑若出现存量 FAIL（对比度/明度/骨架任一），逐条呈报全量清单，**登记 06 条目级**，处置权归用户——首跑判定是本批最大不确定性（shot_checker 四类断言从未在现行构建上全量跑过）。 +- **S2**：golden 逐像素若因字体渲染/平台差异误红，容差调整呈报后定值。 +- **S3**：T2 生成基线时素材缺位→L3 停机呈报（基线禁锚回退态，Q5）。 + +## 七、验收断言清单（本批完成定义） + +1. `tools/render_gate.sh` 存在且退出码闸生效（人为制造一处断言失败可验红；取证段失败同样验红=Q7）。 +2. `game/tests/golden/` 三张棋盘基线在库（素材齐盘态生成）且 golden_compare 在 render_gate 内自动执行。 +3. shot_probe 屏清单含生涯页/暂停层/设置面，shot_meta.json 对应取样键齐。 +4. `probe_gate.sh --full` 四探针全绿且被重闸流程引用；probe_gate 头注释无「归真人目检」残留句；**CLAUDE.md loop §5 含 render_gate 与 --full**（Q1）。 +5. config_fatal_probe 不存在；数据配置.md:205 指路句改指 config_db_fatal_oob_test；damage_probe 头注含「非验收件」；引用零残留。 +6. tests/integration/ 目录不存在，章程句在 tests/README.md（Q8）。 +7. tests/README.md 数字与实测一致且含双口径说明。 +8. 重闸全绿+主区合并复跑全绿（含 render_gate）+出口报告落 design/qa/。 + +## 八、代拍板白名单 + +golden 容差参数 provisional 定值（S2 呈报后落定）；render_gate 实现细节（截图清理执行方式/段序）；商店房可达性考证结论（不可达即注记留 B 批）；退役件引用句措辞。 + +## 九、裁决记录 + +**P1-P5（2026-10-07 用户令，v1.0）**：P1 范围=A+C 全收、B4 不收、B5/B6 移交另会话；P2 渲染闸=本机窗口化自动闸；P3 golden=语义断言为主+逐像素限棋盘 L1-L3+基线测试资产入库；P4 编号=迭代 19 本卡、M4 已顺延迭代 20；P5 收编挂重闸+退役两件+零断言三件标注+ui_layout 两档断言；纪律改写授权（「渲染闸归真人目检」=历史偷懒标记，删除）。 + +**拷打轮一（2026-10-07 用户令「全按推荐」，v1.1）**：Q1 重闸定义正式扩容写 CLAUDE.md loop §5；Q2 过程截图落临时区用后即弃禁入 git；Q3 shot_probe 扩屏（生涯页/暂停层/设置面+商店考证）；Q4 单档 1280、1920 留注记；Q5 运行时素材缺位=SKIP、基线生成素材缺位=L3 停机（基线禁锚回退态）；Q6 呈现批 agent 可换代基线+提交说明强制、数值/逻辑批禁碰；Q7 取证段失败=闸红；Q8 integration 删空壳章程并入 tests/README。**低争议组照落**：S1 登记 06 条目级；golden 前置裁剪坐标取 shot_meta.json 禁硬编码；config_fatal_probe 退役连带数据配置.md:205 指路句；五闸归宿对账表入 §一；T6 删 registry 空炮句（实证无闸登记处）。 + +## 十、估时与切分 + +T0-T6≈4.25d（拷打轮一扩屏+重闸扩容后自 3.75 上调），超软盒 3d 预挂；天然切分点 T2 末——段一 T0-T2（渲染闸，核心）≈2.25d / 段二 T3-T6（收编+退役+账务+收口）≈2d，两段同属一迭代、一次合并。 diff --git a/roadmap.md b/roadmap.md index 8f1f6176..010936c6 100644 --- a/roadmap.md +++ b/roadmap.md @@ -72,7 +72,9 @@ | 迭代 18 | **④生涯界面实装批（2026-10-06 用户令入迭代 18）**：按迭代 17 卡④设计提纲（design/gdd/systems/跨局循环/生涯.md v0.1，master 44328b1）实装「生涯」界面——跨局汇总/历史冒险回看/图鉴承接；提纲在册要点=recent_summaries 现役 cap10 扩容+用时埋点/总局数与通关局数（涉存档 schema）/营地最近冒险清单去留（P6 必答项随评审定）；分期建议随提纲。任务书=`design/research/任务书-生涯界面实装批-2026-10-07.md`（v1.0——范围=提纲期一〔汇总页+主菜单入口+终身计数域存档 v6〕，期二/期三零触碰；裁点 P1 通关局数口径/P2 汇总条目集/P3 模态登记序待裁；提纲评审若改期一范围则任务书升版） | **✅ 已落地（2026-10-07 worktree iter18-career：提纲期一追认+裁点全裁〔2026-10-07 用户令代解/全甲；P6 随期二〕后 T0-T5 全落——生涯页六类九项+主菜单入口+终身计数域存档 v6；批末重闸全绿=冒烟 834/0〔基线 814/0，+20〕+run_all 17 套+四探针+ui_contrast 15 对+doc 三闸/熵增闸零新增；MC 零跑；实机人闸挂账待用户〔⑲目检条目随 07〕；出口报告=[iter18-career-exit-report](design/qa/iter18-career-exit-report-2026-10-07.md)）** | T0-T5≈2.5d | | 迭代 18 | **⑤混编遭遇首批投放批（2026-10-06 用户令入迭代 18；纯内容批——机制前置=迭代 17 卡①敌人表行集多行批）**：07「后续内容批义务」落地——首个混编遭遇行+Boss 多行内容投放（敌种候选与坐标=本批裁点）；首遇教学位纪律与 expect_pools 断言面逐项复核（巨蜘蛛首遇位「固定 2 不加骰」等表注释为准）；难度带读数义务随批登记 07，MC 取证跑批**顺延 Alpha 收官 M4 数值批统一执行**〔未排期，届时另令——2026-10-06 用户令：数值统一调整殿后；投放本身不阻塞〕。任务书=`design/research/任务书-混编遭遇首批投放批-2026-10-07.md`（v1.0——纯内容批零代码，机制面全由卡①承载，机制缺口=L3 停机；裁点 P1 首批投放方案〔荐甲=L2 单点试水〕/P2 Boss 多行不入首批/P3 教学界保护待裁） | 迭代 17 卡①落籍（✅ 已满足 9cc4b8b）+**✅ 裁点全裁（P1-P4 甲，2026-10-07）**——开工=U0 | T0-T5≈1.75d（MC 取证顺延另计）——**✅ 已全批落表（2026-10-07，worktree g-plan2-iter18-mixenc 分支 iter18-mixenc 基点 adadf56，批内提交 ad36e35(T1 设计稿)/6272fc8(T3 落表)/43b1306(T4 断言)/⑤T5 收口批；出口报告=[iter18-mixenc-exit-report](design/qa/iter18-mixenc-exit-report-2026-10-07.md)）**：(2,5) 双行混编落表〔重击手+巨蜘蛛巢群（行值复制 (2,6)，P4 甲零数值新增），R6 行序=重击手在前〕；d5/d7 候选与行值来源全案留痕（d5 案选定）；断言面随迁（expect_pools 三元键新池模板+行集构成/行序/Σ≤4 断言）；首遇教学位 (2,4)/(3,0)/(3,1) 零触碰；07 ⑱ 目检与读数义务登记+:174 逐行骰措辞订正；闸=冒烟 814/0（基线 811/0，+3）+run_all+doc 三闸/熵增零新增（批末重闸数字见出口报告）；实机目检三项归用户（同场两敌种/行序/总数 ≤4）；MC 零跑（顺延 Alpha 收官 M4 数值批在案） | | 迭代 18 | **⑦新冒险种子随机化+调试浮窗升级（2026-10-07 用户令入迭代 18，同日两裁点全裁+浮窗目标态已定）**：**(a) 种子随机化**——现状考证 main.gd:1210 `_seed_value()` 调试种子框为空时硬编码返回 42=每次新冒险同一种子全程可复现；改法=玩家界面入口（主菜单开新冒险）默认分支随机生成；**✅ 裁点全裁（2026-10-07 用户令）：①首次冒险维持固定种子（教学态可复现）/②测试脚本与调试接口维持显式指定种子（冒烟·MC·探针全链显式传种子零影响，锚零作废）/③种子不进玩家 UI**；断点续玩零影响（存档已载 master_seed 回填，main.gd:447 现役）；与⑥收官批零耦合、排序自由。**(b) 调试浮窗升级**（承载「调试浮窗可查当局数据」裁点=种子的唯一查看位；**本项修订迭代 15 卡① P3 甲「仅开始菜单可开·对局不可达」裁决**）——目标态三件：独立于整体界面的**最高层浮窗**（对局中也可开）/DS_DEBUG=1 调试态下**默认打开**/新增**当局数据只读区块**（当前局种子/关卡/节点/HP/GP/钥石等——玩家 UI 不展示、调试浮窗可查）。考证在册（2026-10-07 实查）：现行=开始覆盖层角标入口〔main.gd:292-293，DS_DEBUG=1 点亮〕+main.gd:1189 门禁「仅开始菜单可开」+Dialog 形态走 ModalStack 模态栈登记〔非最高层〕+visible=false 初始非默认开+五区块（胜利演出/种子输入/数值滑条/批量模拟/两层调试）无当局数据面。任务书待裁点：最高层与模态栈登记制的关系〔置顶/登记序末+move_child 或独立层〕/输入吞噬边界〔浮窗矩形外透传游戏输入〕/对局发起「随开随收」逻辑改向/ui_tune_probe 断言面换代/入口形态（角标宿主迁移或热键）。任务书=`design/research/任务书-种子随机化与调试浮窗升级批-2026-10-07.md`（v1.0——实装级裁点 P1 遮挡语义〔荐甲=维持登记制〕/P2 入口形态〔荐甲=角标迁宿主〕/P3 默认打开范围〔荐甲=启动即开〕/P4 当局数据字段集〔荐甲=六项〕/P5 首局种子值〔荐甲=沿用 42〕待裁；估时勘误 1d→2.0d 含探针换代与收口） | **✅ 已落地（2026-10-07 worktree iter18-seed：C1 种子三分+浮窗升级 P1-P6 甲全落；批末重闸全绿=冒烟 811/0+四探针+run_all 17 套+doc 三闸/熵增闸零新增；MC 零跑；实机人闸挂账待用户〔不阻塞落籍与后续卡④〕）** | T0-T5≈2.0d | -| 迭代 19+ | **M4 数值批（**Alpha 收官位·未排期**——2026-10-05 用户令编入迭代 17 卡②；2026-10-06 用户令移出独立成批并定序「Alpha 阶段最后——内容补全先行、统一数值调整殿后」〔当日曾被编入迭代 18 为收官卡，2026-10-07 用户令撤回〕；2026-10-07 用户令：**暂不启动**，移出迭代 18，保持 Alpha 收官位待用户发令）**：四件数值欠账合一批——①削弱档位终值（weaken 现值 −65/duration 2/refresh 考证在册；叠层改续时语义已定案，差 duration 终值+当量锚复算）②调参批数值点评（06 条目现行登记五条——任务口径「八条」与条目五条不符，任务书 §2.2 已呈报差异以条目为准）③迭代 10 奖励重构联动欠账①②（钥石产出重标 boss_keystone 首杀 3/3/3·复杀 2/2/3 provisional + 通关率带重扫〔通关回血 20%+AP 件首轮 +1〕）④元进度定价剩余面（forge base 20/比 150 考证在册——06 条目文本「base 10」滞后于 2026-09-22 对齿批已呈报；Boss 两档终值）。读数义务随批=迭代 14 两件后置复算（T6 MC 四带复算+T7 技能池节奏重测，均挂 07）；顺路修复 damage_probe A1 改前既有红灯（判式换代批出口报告 §四.7 在册）。**硬约束：一切 MC/verifier 跑批发起前须用户批准；调参联动禁独立调参网络（β 带 [1.2,2.5] 逐 u 检算）**。任务书=`design/research/任务书-M4数值批-2026-10-05.md`（**v1.2 2026-10-06 案C 增补+联审修订**：v1.1 三事实与第五推算件照旧；联审=P3 转正顺延至重扫读数后/检算工具 WEAKEN_PCT 入同步面/F11 两句死文本全刷/T3·T5 四带复算并账一次跑批双认账/R5 改前锚=本批新立案C 锚/估时段一勘误 4.25d；案C 增补内容照旧=§2.6 三事实〔行为换代/锚全作废/难度预判〕+T0 推算稿第五件=对拍锚按新序重推导+T6 四带复算按案C 新行为首采；T0-T8≈6.25d，天然切分点 T4 末；🔴 契约 5 条含跑批批准制；**✅ 裁点全裁（2026-10-06 用户令：P1甲=维持 2 场·magnitude [60,85] 带内当量锚复算、具体值随出口 provisional 追认/P2甲 不对称有意/P3甲 3-3-3·2-2-3 维持、转正顺延至重扫读数到账且带内（Q4 二裁）/P4甲 不立直购价）；开工=U0**） | 迭代 18 全部内容卡（③④⑤⑦）出口+全部内容批行为变更落定+**用户发令（未排期）**——重锚窗口须收尽全部内容批行为变更 | T0-T8≈6.25d（超软盒预挂，段一 T0-T4≈4.25d〔v1.2 勘误，原 4.5 系加总错误〕/段二 T5-T8≈2.0d） | +| 迭代 19 | **卡⓪主菜单开局缺陷修复批（原迭代 20 头卡A；2026-10-08 用户令并入本迭代、执行序第一）**：①**主菜单开新冒险+继续上局两入口补传同调三键**（attunement/attune_refresh_y/tree_rules——main.gd:510/:470，接收面 adventure_runner.gd:129-138/215-217 现成；静态考证缺陷成立：全仓无补偿路径、真实入口同调/X/Y 恒空、仅冒烟夹具喂值）；②**关卡开场行攻血改传当前生效值**（main.gd:519-521 现传初始表值，与战斗面板不一致=用户确认缺陷；「含面板加成」后缀判断同步改为认局外加成）；③冒烟补主菜单入口传参断言；④顺手删 adventure_runner.gd:129-134 三行重复赋值（零行为变化）。范围外=被动同调件呈现（用户令不动）、Fork 规则归因行（呈现层）、X/Y 刷新双源语义倒置（实现与用户口径镜像互换——X=刷新件源每节点重置不结转/Y=营地源整局持久/先扣 X，见 adventure_runner.gd:658-659/:706-709；用户口径=X 持久·Y 每节点重置·先扣 Y；真实局因①此前恒 0 未暴露——待用户裁定甲改实现/乙认现状，裁定落 GDD）。**卡①自动化验收补齐批（2026-10-07 用户令立项——全迭代两阶段验收盘点〔功能性+展示性，均自动化口径，不含人工目检〕的落地批）**：三件主内容——①**渲染闸自动化**：新增 `tools/render_gate.sh` 窗口化自动闸（shot_probe 四屏→shot_checker.py A-D 语义断言自动判定+fx_shot/board_shot 抓帧取证），棋盘 L1-L3 golden 逐像素基线入库 `game/tests/golden/`（测试资产入库先例，.gitignore 已核只挡 artwork/）；**probe_gate 头注释「渲染闸归真人目检」纪律句删除改写**（用户 2026-10-07 明示授权=历史偷懒标记），迭代 15③ 屏蔽挂账的机器补跑半随批核销〔07⑮ 目检半仍归用户不销号〕；②**探针收编**：ui_probe/ui_tune_probe/t17_defer_probe/fx_probe 四件游离探针（实测 17.4s/49.6s/63.0s/21.9s 全绿）收进 probe_gate `--full` 段挂重闸，轻闸默认段零改；damage_probe 出闸留盘标注诊断件、config_fatal_probe 删除（与 run_all 致命类单测重复）、零断言三件标注分析工具+ui_layout 补 1280/1920 最小断言；③**账务修正**：tests/README 套件数/断言数漂移（十五→17、752+→双口径说明）+integration 空目录处置（代拍板）。〔2026-10-07 范围改道：原「明示不收」的 B4/B5/B6 三缺口经用户令各立任务书并入本迭代，本卡改称卡①，新增卡②③④见后〕。任务书=`design/research/任务书-自动化验收补齐批-2026-10-07.md`（v1.1——**待裁点 0 项**，P1-P5+拷打轮一 Q1-Q8 全裁 2026-10-07〔重闸定义正式扩容 CLAUDE.md/过程截图即弃/shot_probe 扩屏三新屏/1280 单档/素材缺位 SKIP 而基线禁锚回退态/基线换代权限呈现批 agent/取证失败=闸红/integration 删空壳〕；🔴 契约 6 条含运行时代码零 diff/轻闸零删减/在飞避让；停机点 S1 首跑存量 FAIL 全量呈报登记 06+S3 基线生成素材缺位停机；代拍板白名单四项）。**卡②旧界面呈现断言回补批（B5，2026-10-07 用户令立项）**：迭代 16 前落地旧屏追溯补 ui_contrast 测点对+ui_struct 契约——普查结论=对比度测点对旧屏 0 对（15 对现役全属 HUD/锚点/徽章/生涯）、专项契约仅 pause/career、legend/node 两屏从未过结构族；优先级=战斗结算框>商店>营地柜台+天赋树>设置面>三选一>迷雾锚定对；红线=只加断言零改旧屏、违例登记呈报不修（处置权归用户）；任务书=`design/research/任务书-旧界面呈现断言回补批-2026-10-07.md`（v1.1 grilling 三轮全裁——待裁点 0 项，WL 豁免边界/迷雾合成对最坏判据/时长闸 ≤2s/出口报告/06 遗留件登记全钉死；停机点 2〔对比度首跑存量违例/legend-node 结构首跑〕，T0-T4≈1.0d，worktree iter19-uibackfill）。**卡③CI 预接线批（B6，2026-10-07 用户令立项）**：tests.yml 场景探针段解封——轻 CI 段=input/struct/contrast 三探针（示例引用的 ui_probe/ui_click 归 --full 重闸不进轻 CI）、Linux 独立命令形态（probe_gate.sh 系 Windows 专用）、窗口化四件禁入 headless CI；本地无远端端到端验证不可能=验收全静态核验，「首次 push 后人工盯首跑」入移交清单；远端仓库计划两文档零登记=待裁呈报项；任务书=`design/research/任务书-CI预接线批-2026-10-07.md`（v1.2——**触发分支死角已并入修正范围=tests.yml push/pull_request 两处 [main]→[master]**〔实查：实际分支 master、main 不存在，不修则远端建好后 CI 仍永不触发〕+冷检出导入步前置 smoke 步骤之前；裁点①远端仓库=✅ 2026-10-08 裁暂不建维持待命〔预接线待命=终态〕/裁点② ui_layout 入 CI 候卡①后裁；T0-T3≈0.25d，worktree iter19-ciwire）。**卡④提灯载体道具批（B4，2026-10-07 用户令立项；原登记去向「Alpha 信息件重定批」就此改道入本迭代）**：board_view.set_fog_lantern 死接口（迭代 14⑤ 接线+case⑮ 断言在位，载体始终未造=完成度 0）补载体道具；备选案五件全列（案 A 秘宝同调位新行=原登记指向·推荐/案 B 专长新行·撞重设计冻结不推荐/案 C 商店货架·分类判据需新裁/案 D 显影尘行激活合并·与改道相逆/案 E 元进度树·破坏读数归因不推荐）+淘汰案六件各附依据，设计权全归用户；任务书=`design/research/任务书-提灯载体道具批-2026-10-07.md`（v1.2——**✅ 裁点全裁：2026-10-08 载体=案A秘宝同调位新行**〔行字段推荐值=执行中一次秒答，「按推荐」即全收〕；缺陷处置=卡⓪随同 goal 先行落籍=本卡 T1 前置门〔缺陷实查定案影响全部开局入口；原记迭代 20 缺陷批，2026-10-08 并入本迭代为卡⓪〕；呈现桥=只读访问器/复原语义=begin_battle 显式重算/MC=静态论证/测试三形态等工程面全钉死，T0-T5≈2.5d，worktree iter19-lantern） | 迭代 18 出口（✅ 已解——2026-10-07 四卡总收口落籍）——**开工=goal 一次跑完（2026-10-08 裁：卡⓪缺陷卡先行+卡①-④打包，全绿前禁停；subagent 并发 ≤3；唯一预期交互=卡④行字段推荐值秒答；卡⓪原迭代 20 头卡A 同日用户令并入本迭代）** | 卡⓪≈1.0-1.5d（随计划书定稿）+卡①T0-T6≈4.25d（超软盒预挂；天然切分点 T2 末——段一 T0-T2 渲染闸≈2.25d / 段二 T3-T6 收编退役账务≈2d，两段同属一迭代一次合并）+卡②T0-T4≈1.0d+卡③T0-T3≈0.25d+卡④T0-T5≈2.5-3.0d（切分点 S0：考证呈报 0.25d/实装收口 2.25-2.75d）——五卡合计≈9.0-10.0d | +| 迭代 20 | （**空位待编**——原头卡A 主菜单开局缺陷修复批已并入迭代 19 卡⓪〔2026-10-08 用户令：其为迭代 19 卡④的 T1 前置门且随同 goal 执行，归属随执行落位〕；候选 B-F 留档〔奇物改名/商店刷新收尾/C 三件/D 敌系/E 生涯/F 典检〕编入待用户点名） | —— | —— | +| 迭代 21+ | **M4 数值批（**Alpha 收官位·未排期**——2026-10-05 用户令编入迭代 17 卡②；2026-10-06 用户令移出独立成批并定序「Alpha 阶段最后——内容补全先行、统一数值调整殿后」〔当日曾被编入迭代 18 为收官卡，2026-10-07 用户令撤回〕；**2026-10-07 用户令二次后移：后续新迭代（迭代 20 起）一律不先做 M4，除非用户明确要求启动 M4 批次**）**：四件数值欠账合一批——①削弱档位终值（weaken 现值 −65/duration 2/refresh 考证在册；叠层改续时语义已定案，差 duration 终值+当量锚复算）②调参批数值点评（06 条目现行登记五条——任务口径「八条」与条目五条不符，任务书 §2.2 已呈报差异以条目为准）③迭代 10 奖励重构联动欠账①②（钥石产出重标 boss_keystone 首杀 3/3/3·复杀 2/2/3 provisional + 通关率带重扫〔通关回血 20%+AP 件首轮 +1〕）④元进度定价剩余面（forge base 20/比 150 考证在册——06 条目文本「base 10」滞后于 2026-09-22 对齿批已呈报；Boss 两档终值）。读数义务随批=迭代 14 两件后置复算（T6 MC 四带复算+T7 技能池节奏重测，均挂 07）；顺路修复 damage_probe A1 改前既有红灯（判式换代批出口报告 §四.7 在册）。**硬约束：一切 MC/verifier 跑批发起前须用户批准；调参联动禁独立调参网络（β 带 [1.2,2.5] 逐 u 检算）**。任务书=`design/research/任务书-M4数值批-2026-10-05.md`（**v1.2 2026-10-06 案C 增补+联审修订**：v1.1 三事实与第五推算件照旧；联审=P3 转正顺延至重扫读数后/检算工具 WEAKEN_PCT 入同步面/F11 两句死文本全刷/T3·T5 四带复算并账一次跑批双认账/R5 改前锚=本批新立案C 锚/估时段一勘误 4.25d；案C 增补内容照旧=§2.6 三事实〔行为换代/锚全作废/难度预判〕+T0 推算稿第五件=对拍锚按新序重推导+T6 四带复算按案C 新行为首采；T0-T8≈6.25d，天然切分点 T4 末；🔴 契约 5 条含跑批批准制；**✅ 裁点全裁（2026-10-06 用户令：P1甲=维持 2 场·magnitude [60,85] 带内当量锚复算、具体值随出口 provisional 追认/P2甲 不对称有意/P3甲 3-3-3·2-2-3 维持、转正顺延至重扫读数到账且带内（Q4 二裁）/P4甲 不立直购价）；开工=U0**） | 迭代 18 全部内容卡（③④⑤⑦）出口+全部内容批行为变更落定+**用户发令（未排期）**——重锚窗口须收尽全部内容批行为变更 | T0-T8≈6.25d（超软盒预挂，段一 T0-T4≈4.25d〔v1.2 勘误，原 4.5 系加总错误〕/段二 T5-T8≈2.0d） | ## 执行纪律（2026-09-27 用户立规）