docs(卡片): 需求卡片落位迁至 reports/——路径依赖、规则说明、流水线闸、工作流技能全量同步

用户裁:需求卡片属过程件,不留在 design/;统一落 reports/(不新设目录,卡片靠「需求卡片-」文件名前缀与报告区分)。

搬移:
- 10 张在役卡片 design/research/ → reports/(git mv,历史保留)
- 卡内相对链接全部重基准:../gdd→../design/gdd、../art→../design/art、../../→../、
  同目录 research 引用→../design/research/(营地澄清、playnote、资源配比提案);
  链接解析校验 BROKEN=0

路径依赖(全库 48 处):
- 06 待办清单 10 条卡片路径、roadmap 迭代 31 行 2 条、reports/iter31 报告与反哺点各 1 条
- 代码术语审计报告 2 处、会话提示 1 处、资源配比提案 1 处

规则说明:
- AGENTS.md Project Layout:design/research 行注明「需求卡片不在此」;reports 行扩为「过程件容器」
- doc-conventions §11 暂存地表拆为两处;§12.1 状态机示例改 reports/
- reports/README.md:定位由「迭代批产出物」扩为「过程件容器」并新增需求卡片行

流水线闸:
- pipeline_gate.py CARD_DIR / RESEARCH_RE / 报错文案三处改 reports/(闸 PASS,卡片口径 10 张全过)

工作流技能(.zcode/skills,不入 git):
- req-card :8 落位 / :27 三份已退役范本改指现行卡片 / :92 06 回写口径
- iter :19、iter-plan :28/:66、batch-closure :3/:63/:65
- 用户级副本 C:/Users/DK/.workbuddy/skills/req-card/SKILL.md 同步三处(技能列表启动时加载,需重开会话生效)

未动:design/art、design/qa、提案、playnote、道具退役素材库、会话交接件(归其它会话)。
闸:run_all_gates.sh --docs 验收通过。
This commit is contained in:
DKChan committed 2026-10-20 05:28:42 +08:00
1 parent a2d446d9e0
commit 0616af94fb
21 files changed
+81 -81

No files matched your search

+3 -3
View File
@@ -1,12 +1,12 @@
# reports/ — 迭代批的产出物存放处
# reports/ — 过程件容器
迭代(代码实现)批**禁写 `design/` 整个目录**——那里是设计权威文档与规范,对实现批只读。
实现批自己要往外交代的东西,一律落在本目录。
`design/` 只放持久化设计文档与规范,过程件一律不放。过程件落本目录,**按「吸收即死」到期即死**。
## 放什么
| 文件 | 内容 | 谁写 |
|---|---|---|
| `需求卡片-<批名>-<日期>.md` | 一个需求单位的实施文档(roadmap 迭代行里的「卡①②③」是需求单位,需求卡片是它的展开):目标与完成定义/设计事实源/现状事实/契约/范围边界/任务卡/验收闸/代拍板白名单/待裁点 | 写卡段(`req-card` 技能) |
| `iter<N>-实现报告-<日期>.md` | 各任务卡状态、实机目检总清单、遗留读数义务 | 迭代批 |
| `iter<N>-代拍板-<日期>.md` | 批内 agent 替你拍的决定清单,等你追认或推翻 | 迭代批 |
| `iter<N>-反哺点-<日期>.md` | 需要写进 `design/` 权威文档的点,逐条列清"哪个文件哪一节、改成什么、依据是什么" | 迭代批 |
+1 -1
View File
@@ -1,7 +1,7 @@
# 迭代 31 反哺点清单(2026-10-19)
- 口径:本批是代码实现批,禁写 `design/` 与根规则文件。下列每条写清「哪个文件哪一节/改成什么/依据」,由你在会话中裁决后归**文档批**落笔;落笔后本条即可删(`reports/README.md` 生命周期同口径)。
- 依据批次:卡①「代码术语刷新批」v1.4(`design/research/需求卡片-代码术语刷新批-2026-10-18.md`)+卡②「凭证件裁削批·代码侧」v1.1。
- 依据批次:卡①「代码术语刷新批」v1.4(`reports/需求卡片-代码术语刷新批-2026-10-18.md`)+卡②「凭证件裁削批·代码侧」v1.1。
## 一、06-待办清单(`design/gdd/06-待办清单.md`)
+1 -1
View File
@@ -1,6 +1,6 @@
# 迭代 31 实现报告(卡① 代码术语刷新批 + 卡② 凭证件裁削批·代码侧)
- 卡片:`design/research/需求卡片-代码术语刷新批-2026-10-18.md` **v1.4**、`design/research/需求卡片-凭证件裁削批-2026-10-18.md` **v1.1**(roadmap 迭代 31 行两卡,串行:卡①→卡②)
- 卡片:`reports/需求卡片-代码术语刷新批-2026-10-18.md` **v1.4**、`reports/需求卡片-凭证件裁削批-2026-10-18.md` **v1.1**(roadmap 迭代 31 行两卡,串行:卡①→卡②)
- 分支/worktree:卡① `iter31-c1-term-20261019`/`g-plan2-iter31-c1-term`;卡② `iter31-c2-curio-20261019`/`g-plan2-iter31-c2-curio`;取证专用临时区 `g-plan2-iter31-oldface`(检出 ed2dfaf6,跑完即删,不入库)
- 闸口径:两卡均触 `game/` → 代码域;卡① 另触 `tools/` 四处(素材名随批,你裁甲案授权)→ 合回前跑**全量档**(代码+文档两域),卡② 触 `game/`+`reports/` → 同按两域
- 开工门:U0=本会话 `/iter 31`;开工检查的自洽扫描核出两处卡片缺口,均由你当场裁(见代拍板单 §一 R-1/R-2),零待裁点前提下才动工
@@ -0,0 +1,209 @@
# 需求卡片:Esc 浮窗与营地顶栏批(营地顶部小 HUD 栏 · Esc 三钮浮窗)· 营地交互重做卡⑤
- 版本:**v1.2**(2026-10-18 grilling 轮次裁定回写——Q1 裁定甲(只营地根态响应,代拍板留痕)、Q2 裁定甲(再按 Esc 关浮窗,推荐案)、Q3 裁定甲(确认 Esc 只在营地语境,推荐案,用户的从严收窄升格为已确认);契约 2 随 Q3 升格;卡④回设计段→本卡排期随④重新立卡后,卡片保留有效)
- 来源:[需求澄清-营地交互重做-2026-10-18.md](../design/research/需求澄清-营地交互重做-2026-10-18.md)(唯一事实源:⑤裁决 9/10、④结构树语境、⑦切批原则⑤)
- 归属:呈现层/组合根(`game/presentation/`)——营地交互重做五卡之五
- 排期:未编入(2026-10-18 用户令:需求卡片不预占迭代号,批次归属按工作量另裁)
- 开工门:U0(用户 `/iter` 发令)+ 待裁点已裁(Q1/Q2/Q3 均裁定,见 §10)+ grilling 复核门过+ **卡④重新立卡并落地后**(本卡浮窗与 HUD 落在卡④新建的场景屏上——卡④ 2026-10-18 回设计段,本卡排期随④之后,卡片本身有效)
## 0. 前置依赖与并行性
- 前置卡④(营地场景图):Esc 浮窗的「返回主菜单」与顶栏 HUD 都落在营地场景屏上;**卡④ 2026-10-18 已回设计段**(美术设计定稿未过设计前置闸)——本卡不可先于卡④重新立卡落地,排期随④之后;本卡自身零美术依赖(零新素材、裁决 9/10 已给全),设计前置检查通过,卡片有效。
- **跨卡接口(v1.1 补全)**:①场景屏顶栏位(卡④ T2 预留);②**营地刷新单口**(卡④ T3 定义:各写口尾→现开界面刷新+场景根 HUD 刷新一闸完成)——本卡 HUD 刷新挂该单口,**非已退役的 `refresh_camp`**;③子界面返回钮承诺(卡④ T3——Q1 甲案前提);④卡④终局落点不变量(T0 互证)。
- 卡②的退出游戏钮、现役设置面——本批只复用不重做(契约 3)。
- 与卡④同批或随后(两卡触碰同一新屏)。**探针入口路径还依赖卡②③链**(v1.1 补明): restructuring 后营地只能经「菜单三钮→进入存档→选档→进档」到达——本卡 V1/V3 探针段隐含依赖该全链在位;若本卡先于卡②③合入,探针段挂起或走中间态断言(仿卡② §9 第 4 条先例)。
- **camp 截图/golden 联动(v1.1 补)**:HUD 栏落营地场景屏会改 camp 截图内容——若本批晚于卡④单跑,卡④ 刚重制的 camp 断言基线必再漂移;若同批,卡④ T5 迁移时点须晚于本卡 T2 HUD 落位(排序约束)。本卡 T2 含「HUD 落位后核漂移热区→限 HUD 区显式更新+呈报」条。
## 1. 目标与完成定义
**目标(澄清⑤裁决 9/10 照录)**:
- 裁决 9「**Esc 键**唤起浮窗:返回主菜单 / 设置 / 退出游戏 三项」(用户原话「ESC键可以唤起一个浮窗,里面有返回主菜单,设置,退出游戏三项」);
- 裁决 10「钥石余额:场景**顶部小 HUD 栏**」(用户原话「先按顶部小HUD栏设计」——provisional 措辞留痕)。
**相对现状,新增了什么**:
1. Esc 浮窗(全仓现无任何键盘快捷键处理——从零新建);
2. 营地场景顶部小 HUD 栏(钥石余额常驻——现营地钥石徽在 CampOverlay 顶栏,随卡④拆解后由新 HUD 栏承接)。
**完成定义**:
1. 营地语境按 Esc 唤起浮窗,浮窗有且仅有返回主菜单/设置/退出游戏三项;浮窗的关闭/取消路径按 Q2 裁定落地;
2. 「返回主菜单」回主菜单(营地场景屏隐藏+选档层同收+主菜单可见);「设置」开现役设置面(语境分支见契约 3);「退出游戏」接现役退出路径;
3. 营地场景顶部小 HUD 栏在位,钥石余额读数=存档单口现值,刷新时机=购买后(挂卡④营地刷新单口)/进档或回营地进入时重读/夹具直写后探针显式触发(v1.1 清单化);
4. 浮窗零动效直开直关(生涯页同款契约);新层入 `LAYER_CONTRACT`;
5. 批末重闸按改动域选档全绿;三份 `reports/` 产出物写齐(T4)。
## 2. 现状事实(2026-10-18 实查;开工日 T0 复核行号)
| # | 事实 | 出处 |
|---|---|---|
| F1 | **全仓零键盘快捷键处理**:`KEY_ESCAPE`/`ui_cancel`/`ui_accept` 在 `game/` 全目录 grep 零命中(2026-10-18 实查)——Esc 浮窗是从零新建,无旧路径可迁;现成输入合成先例只有鼠标 `Viewport.push_input`(ui_input_probe.gd:51-63/:657-680,headless 实证),键盘合成须 T0 spike | 全仓 grep 实证;`game/smoke/ui_input_probe.gd:51-63` |
| F2 | 设置面在役:`settings_overlay` 构建+`closed` 接线;开=`_open_settings`(:1055-1057),关=`_on_settings_closed`(:1060-1063,关后**带 `_start_overlay.visible = true` 硬副作用**——营地语境照抄会在关设置后弹主菜单,须语境分支,见契约 3);`_open_settings`/`_quit_game` 现唯二调用点都是菜单钮 | `main.gd:277-279`/:1055-1057/:1060-1063/:333-334(v1.1 行号订正) |
| F3 | 退出游戏在役:`_quit_game`(设置即时落盘后 `get_tree().quit()`;无语义副作用,可原样复用) | `main.gd:500-503` |
| F4 | 钥石徽工厂件在役:`UiKit.keystone_badge`(三处消费先例——营地顶栏/生涯页/状态面板;迭代 17 卡③ Q10 甲工厂化)——HUD 栏复用该件,零新素材 | `camp_overlay_view.gd:82`;`career_overlay.gd:54` |
| F5 | art-bible §6.2 现载「钥石余额常驻顶栏」——与裁决 10 同向,本批是把该呈现位从 CampOverlay 顶栏迁场景屏 HUD | `design/art/art-bible.md:369` |
| F6 | 层序唯一事实源=`main.gd` `LAYER_CONTRACT`;`_apply_layer_contract` 全仓唯一落位口;冒烟 V1d 源码断言判红散落 `move_child` | `main.gd:34-53`/:430-455 |
| F7 | 零动效契约先例:生涯页/状态面板「直开直关」——ui_struct_probe 载 `_career_zero_motion_contract`(子树 AnimationPlayer 零命中+视图源码禁动效令牌扫描) | `game/smoke/ui_struct_probe.gd:313-328` |
| F8 | 08「六 · Alpha 不含」载「键盘 / 手柄输入(排 Beta)」行(**:192**——:191 是反雪球机制行)——Esc 属用户明示裁决(澄清⑤裁决 9),与该行的关系须同步注记(反哺点),本批不自扩其余键盘面 | `design/gdd/08-Alpha版本标准.md:192`(v1.1 行号订正) |
| F9 | **刷新链路实况(v1.1 订正,原结论失实)**:营地侧刷新腿=`camp_overlay.refresh_camp(camp_data())`(CampShopPresenter 各购买口尾与 `_refresh_presentations` 成对调用)——`refresh_camp` 是 CampOverlay 方法,**随卡④拆解退役**;`_refresh_presentations`(main.gd:1293-1298)刷的是战斗侧 HudPresenter+秘宝槽+结算视觉,**营地语境零营地视图触碰**;钥石入账发生在冒险收束、不在营地(存档序列化.md:116)——营地语境无现行入账触发源 | `camp_shop_presenter.gd:85-86`/:93-94 等;`main.gd:1293-1298`;`存档序列化.md:116` |
| F10 | 调试入口全局浮层角标在役(LAYER_CONTRACT 末位 float 类,不注册 ModalStack,任何 UI 不遮挡);ModalStack.open 只隐藏登记层 | `main.gd:51-53`/:312-314;`modal_stack.gd:21-30` |
## 3. 设计契约(红线,违反 = L3 停机呈报)
🔴 **契约 1 · 浮窗三项且仅三项**:返回主菜单/设置/退出游戏(裁决 9)。禁加项(禁「继续冒险」类——营地无冒险可继续)、禁减项。浮窗的关闭路径=Q2 裁定项(再按 Esc 关/关闭钮/无关闭三选一),不属「加项」争议。
🔴 **契约 2 · Esc 范围=营地语境(Q3 已确认,2026-10-18)**:浮窗只在营地场景图语境唤起(含其子界面开态——行为按 Q1 裁定的甲案:只根态响应)。**禁扩展到战斗/地图/其他屏**(用户 2026-10-18 确认「只在营地语境」;08:192 键盘面仍排 Beta,本批只落 Esc 一项)。
🔴 **契约 3 · 设置与退出本体零重做、接线允许语境分支(v1.1 放宽)**:设置面本体与退出行为零改(F2/F3);**开合接线允许按语境分支**——现役 `_on_settings_closed` 带「回开始层」硬副作用,营地语境须分支为「关设置回浮窗不回主菜单」;正解=浮窗登记于设置层之下,`_open_modal(settings_overlay)` 自动隐藏浮窗、关闭自动恢复(既有栈语义);`_quit_game` 无语义副作用,原样复用。
🔴 **契约 4 · 返回主菜单动线**:营地场景屏隐藏+**选档层同收**(卡④ T3 口径)+开始层恢复;营地语境⇔闲时会话(无冒险会话——卡④ 契约 6「冒险进行中不开营地」+现役终局回菜单并 `_begin_session(false)` 收束推得,v1.1 前提成文),故动线本身不含会话收束;**回主菜单后菜单=卡②三钮、断点在档不在菜单露面**(禁实现者自作主张加「继续冒险」钮——那正是契约 1 在浮窗侧禁的);营地每笔消费即时写盘(存档序列化.md:121),回主菜单不写档也无损。
🔴 **契约 5 · 顶栏 HUD 单口读数+刷新挂卡④单口(v1.1 订正)**:钥石余额只经 MetaProgression/SaveManager 访问器单口读(禁第二账本、禁视图自算);**刷新挂卡④定义的营地刷新单口**(非已退役 `refresh_camp`——F9);刷新时机清单=购买后/进档或回营地进入时重读/夹具直写后探针显式触发(T2 落定)。
🔴 **契约 6 · 零动效**:浮窗直开直关,子树零 AnimationPlayer、源码禁动效令牌(生涯页同款契约,F7);减动效设置项不新增(在役项沿用)。
🔴 **契约 7 · 层序纪律+遮挡结论(v1.1 落结论)**:浮窗入 `LAYER_CONTRACT`(改层序只改合同表);禁散落 `move_child`。**与调试角标遮挡的结论(v1.1 补,既有纪律已定论、无需用户裁)**:debug_badge 是末位 float 类不注册 ModalStack,ModalStack.open 只隐藏登记层⇒角标**恒压浮窗且保持可点**(树序末位=最顶绘制序,全仓无 `debug_badge.disabled` 赋值)——合同内照此表达。另写明一条栈语义防误触 L3:浮窗开会隐藏登记序在其上的已开层(如调试浮窗体 debug_overlay),关闭恢复——属既有栈语义非新决策。
🔴 **契约 8 · provisional 口径留痕**:裁决 10「先按顶部小HUD栏设计」的「先」字留痕——HUD 栏形态按最小集落地(只承载钥石余额),扩项=新裁点。
## 4. 范围边界
**做**:Esc 输入接线+浮窗视图(三项钮+Q2 关闭路径)+层序登记;营地场景屏顶栏小 HUD 栏(钥石余额);断言批(探针合成键盘事件+零动效契约+HUD 读数一致性);反哺点清单。
**不做**(明示去向):
- 营地场景图本体 → 卡④(本批只在其顶栏位落 HUD+挂刷新单口);
- 选档界面/主菜单/数据层 → 卡③/卡②/卡①;
- 其余键盘快捷键(任意键关闭浮窗/手柄/战斗内 Esc) → 用户未裁,禁自扩(契约 2);
- 设置面/退出路径本体改动 → 无(契约 3);
- HUD 栏扩项(冒险天数/种子等) → 契约 8,扩项另裁。
## 5. 关联文档同步面
> **v1.3 口径**:本批禁写 `design/` 整目录与根规则文件,唯一可写目录 = `reports/`;下表一律执行为列进反哺点清单。
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| `design/gdd/08-Alpha版本标准.md` | :192「键盘 / 手柄输入(排 Beta)」行——Esc 营地浮窗已落地(用户明示裁决,澄清⑤裁决 9),须加注防「Beta 行=本批违例」误读 | 反哺点 · 行内加注(v1.1 行号订正 :192) |
| `design/art/art-bible.md` | §6.2「钥石余额常驻顶栏」呈现位从 CampOverlay 顶栏迁场景屏 HUD(:369 述) | 反哺点 · 随卡④ §6.2 改版一并落 |
| `design/gdd/ux/camp.md` | 顶栏铭牌/钥石徽记述(:14-20)随 HUD 栏改挂 | 反哺点 · 随 camp.md 改版落 |
| `design/gdd/06-待办清单.md` | 本卡登记条 | 反哺点 · 列清单 |
| `design/gdd/07-体验验证清单.md` | 新增目检条(Esc 浮窗三动线/HUD 余额观感)——登记不阻塞 | 反哺点 · 列清单 |
| `roadmap.md` | 迭代行编入/状态刷新 | 反哺点 · 列清单 |
| `game/presentation/*`(浮窗视图+接线)、`game/smoke/*` | 实现与断言本体 | 实施本体(可写) |
## 6. 任务卡
> 估时按 Claude 工作日口径;每卡出口自跑轻闸;开工日 T0 复核全部行号。
### T0 事实坐实与跨卡对齐(≈0.5–1d)
- 复核 §2 行号;确认卡④场景屏顶栏预留位接口+营地刷新单口签名(跨卡);
- **Esc 输入合成 spike**(v1.1 补):headless 下键盘事件合成机制验证(现成先例只有鼠标 `Viewport.push_input`——F1);与 §9 第 1 条接线方式选型联动(InputMap action+轮询路线与合成探针不兼容,选型时一并定);
- Q1 子界面行为、Q2 关闭路径、Q3 范围确认裁定执行;
- 与卡④ T0 互证终局落点不变量(契约 4 前提);探针入口路径依赖卡②③链的时点确认(§0)。
### T1 Esc 浮窗(≈1–1.5d)
- 浮窗视图:模态壳(`UiKit.modal_shell` 先例——该工厂只产 dim+center+panel+VBox、无内置关闭件,关闭件按 Q2 裁定)+三钮(返回主菜单/设置/退出游戏);危险钮形制用于退出(`UiKit.danger_button` 先例);零新素材零新色值;
- 接线:返回主菜单→营地场景屏隐藏+选档层同收+开始层恢复(卡④动线同口);设置→`_open_settings`(**语境分支**:浮窗登记于设置层之下,关设置回浮窗——契约 3);退出→`_quit_game`;
- **营地语境判据(v1.1 补)**:判据=营地场景屏 visible(根态与子界面开态下皆真——子界面是模态叠加非熄屏;screen_flow_probe 营地旗标先例 :53 可迁移复用);Q1 裁甲则判据加「无营地子模态开态」;调试浮窗开态不影响判据(全局浮层、营地屏仍可见);Q1 裁后回写契约 2 消歧;
- 层序入 `LAYER_CONTRACT`(与调试角标遮挡按契约 7 结论表达);零动效(契约 6);
- Q2 关闭路径接线(再按 Esc 关/关闭钮/无关闭,按裁定)。
### T2 营地顶栏小 HUD 栏(≈0.5–1d)
- 顶栏位落 `UiKit.keystone_badge` 工厂件(余额单口读数,契约 5);
- **刷新挂卡④营地刷新单口**(契约 5);**刷新时机清单落定(v1.1 补)**:①购买后(挂单口)②进档/回营地进入时重读③夹具直写后由探针显式触发——断言前须显式触发,禁依赖「自动重读」假设;
- HUD 栏形态按最小集(契约 8):只承载钥石余额;
- **camp 截图/golden 联动条(v1.1 补)**:HUD 落位后核 camp 截图漂移热区→限 HUD 区显式更新+呈报(仿卡④ T5/卡② 契约 6 口径;现无 camp 逐像素 golden——卡④ 契约 10)。
### T3 断言批(≈0.5–1d)
- 探针(**宿主选 screen_flow_probe——v1.1 定:轻闸默认段且「菜单⇄营地屏壳切换」正是其职域,零闸登记成本;若另起新文件须改 tools/probe_gate.sh 登记=§5 可写面外,禁**):合成 Esc 键事件→浮窗可见+三项在位;非营地语境(boot 菜单)不唤起;返回主菜单动线(营地隐+选档层收+菜单显);设置项开合(**含营地浮窗→设置→关闭回浮窗高危路径+「关闭设置后禁弹主菜单」反向断言——v1.1 补**);退出项接线断言(headless 不可真退);
- HUD:余额读数=存档单口(夹具经**隔离存档实例直写** `add_keystone` 或等效写口——smoke 既有先例 smoke_all.gd:5440;**不经 DebugOverlay 界面——其钥石项是只读投影,debug_overlay.gd:173-189,v1.1 订正**);直写后显式触发刷新断言;
- 契约断言:浮窗零动效(career 同款段复用/仿写);层序登记(冒烟 V1d);**浮窗开态 `debug_badge.visible==true`**(仿 ui_click_probe.gd:174-177 设置面开中角标可见先例——v1.1 补);
- **变异验证伴生**:Esc 接线漏营地隐(预期动线断言红)、HUD 读缓存旧值(预期刷新断言红)、浮窗加第四钮(预期三项断言红)、**设置关闭后误回主菜单**(预期语境断言红——v1.1 补)、**Esc 再按不关窗**(预期关窗断言红,若 Q2 裁甲——v1.1 补);注入→最窄闸见红→精确还原→记录。
### T4 产出物落位卡(≈0.5d,末卡)
三份 `reports/` 写齐。
**估时合计 ≈3–4.5d**(v1.1 订正:分项和=3.0–4.5d,原「2.5–3.5d」算术少算)。切分预案:T1/T2 后可切(浮窗先落、HUD 后落)——切分价值低,建议与卡④同批单跑。
## 7. 验证闸(逐需求点验收清单)
| # | 需求点 | 测什么 | 落点/判定手段 |
|---|---|---|---|
| V1 | Esc 唤起(按 Q1 分拆) | **根态**合成 Esc→浮窗可见;**子界面开态按 Q1 案**(甲=不现/乙=先关子界面再现);boot 菜单语境不唤起(其余非营地语境由契约 2 红线+源码断言兜底——可达性单一,登记原因) | screen_flow_probe 合成键盘事件段(T0 spike 机制) |
| V2 | 浮窗三项 | 返回主菜单/设置/退出游戏三钮在位且仅三 | ui_struct_probe 结构断言 |
| V3 | 返回主菜单 | 营地场景屏隐藏+选档层同收+主菜单可见 | screen_flow_probe 型断言 |
| V4 | 设置项(双路径) | 菜单路径(冒烟 V3g settings 段复跑)+**营地浮窗→设置→关闭回浮窗**(含禁弹主菜单反向断言) | 冒烟复跑+探针新路径段 |
| V5 | 退出项 | 接线到 `_quit_game`(headless 不可真退——接线断言代偿) | 源码/结构断言 |
| V6 | HUD 余额 | 读数=存档单口(隔离实例直写);直写后显式触发刷新;购买后刷新(挂卡④单口——跨卡联验) | 探针数据断言(smoke_all.gd:5440 同型先例) |
| V7 | 零动效 | 浮窗子树零 AnimationPlayer+源码禁动效令牌 | ui_struct_probe 零动效契约段(career 同款) |
| V8 | 层序与遮挡 | 浮窗入 LAYER_CONTRACT(冒烟 V1d);浮窗开态 debug_badge 可见 | 冒烟 V1d+探针 badge 断言 |
| V9 | 目检项登记 | Esc 三动线+HUD 观感+浮窗视觉面(文字 WCAG 若入 shot_checker 取样,否则显式登记归目检并写明理由)入 07 | 件核(登记不阻塞) |
| V10 | 反哺点清单 | §5 每条有落点 | 件核对表 |
**测试方式两分法**:V1–V8 机检自动化(能力验证经隔离存档实例直写钥石/开态——v1.1 订正:不经 DebugOverlay 界面);V9 归用户目检(生命周期末步统一进行,不阻塞迭代,澄清⑥口径)。
**闸口径**:轻闸每卡出口自跑;批末重闸按改动域选档(本批碰 `game/` 代码与断言面 → `--code`)全绿才合并;MC 零跑(零数值零行为)。
## 8. 异常分级
- **L1(自救)**:断言写法、探针合成键事件写法、命名。
- **L2(记录继续)**:Esc 接线方式选型(§9 域内)、浮窗壳尺寸/位次(UiKit 现行件域内)、HUD 栏位微调。
- **L3(停机呈报)**:卡④ 场景屏未到位又需合并;Q1/Q2/Q3 未裁即开工;发现需扩展到非营地语境才能成立(触契约 2=用户裁面);Esc 键盘合成 spike 失败且无替代验收手段(真实路径纪律不让直呼处理函数代偿);浮窗开会隐藏其上登记层的栈语义被误判为缺陷(契约 7 已写明,勿误停机)。
## 9. 代拍板白名单(超清单必呈报)
1. Esc 输入接线方式(`_unhandled_input` vs InputMap 新 action vs 专用控制器)——约束:不吞他处输入、探针可合成(与 T0 spike 结论兼容;InputMap action+轮Polling 路线禁——与合成探针不兼容)。
2. 浮窗模态壳尺寸与位次(UiKit `modal_shell` 现行件域内)。
3. HUD 栏在顶栏的左右位次与间距(卡④场景屏顶栏域内)。
4. 「返回主菜单」复用卡④篝火同一处理函数(建议复用——动线同口;实现期定)。
5. 浮窗视觉面是否入 shot_checker 取样(T3 定:入=补截图段;不入=显式登记归目检并写明理由)。
6. 提交切分与 worktree 分支命名。
## 10. 待裁点
### Q1 · Esc 在子界面开态下的行为(必裁,未裁不开 T1)
**背景**:营地语境含「场景根态」与「子界面开态」(锻造/秘宝/生涯/天赋树/图鉴开着时)。澄清⑤裁决 9 未覆盖此分支。两案并列,**无推荐(用户令:不代裁)**:
| 案 | 内容 | 代价 |
|---|---|---|
| 甲 | 只营地根态响应 Esc;子界面开着时 Esc 不唤浮窗(**前提=各子界面自带返回钮闭环——待卡④ T3 承诺,v1.1 括注**) | 语义最简;子界面里按 Esc 无反馈 |
| 乙 | 营地语境任意态响应 Esc:子界面开着时先关子界面回根态,再按才唤浮窗(单义化) | 多一层输入编排;与既有「子界面返回钮」形成双关闭路径 |
连带:判据形态随案(T1 已列);V1 按案分拆断言;契约 2 措辞裁后回写。裁决方式:随卡片评审定案;裁定落 T0 执行+实现报告留痕。
**裁定(2026-10-18)**:**甲**——只营地根态响应 Esc;子界面开着时 Esc 不唤浮窗。代拍板留痕(用户令「事项按推荐的来」,本项无推荐案,取默认甲=语义最简;前提=卡④ T3 承诺各子界面自带返回钮闭环,卡④重新立卡时该承诺已在内;追认单可 veto)。T1 判据=营地场景屏 visible 且无营地子模态开态。
### Q2 · 浮窗的关闭/取消路径(必裁,未裁 T1 视图定不了稿——v1.1 新增)
**背景**:`UiKit.modal_shell`(ui_kit.gd:456-475)只产 dim+center+panel+VBox、**无内置关闭件**;契约 1 禁加项⇒浮窗只有三钮,无一「关闭」。而 §4 不做清单把「任意键关闭浮窗」划为用户未裁禁自扩——**Esc 自身再按的行为恰好落在被 punt 的缝隙里**:Q1 两案都不覆盖「浮窗已开时按 Esc」。若不裁且无关闭钮,玩家误开浮窗后离开营地只有「回主菜单/开设置/退游戏」三条路——体感陷阱,且与卡④子界面(生涯有返回钮)的可用性水准倒挂。
| 案 | 内容 | 代价 |
|---|---|---|
| 甲(推荐) | 再按 Esc 关浮窗(同键唤起/关闭单义切换) | 与 Q1 裁甲并存时 Esc 语义三态分枝(关浮窗/唤浮窗/子界面无反馈),探针断言须分拆(V1 已按案分拆) |
| 乙 | 浮窗加关闭钮 | 触契约 1「禁加项」——须重新解释「三项」仅指功能项 |
| 丙 | 维持无关闭(三钮即全部出口,「返回主菜单」充当默认离开) | 误开浮窗后成本高;与子界面可用性水准倒挂 |
裁决方式:随卡片评审定案;裁定落 T1 视图与接线+V 表。
**裁定(2026-10-18)**:**甲**——再按 Esc 关浮窗(同键唤起/关闭单义切换)。推荐案,用户令按推荐执行。T1 接线含「浮窗已开时再按 Esc=关浮窗」;V1 断言按「根态唤起/再按关闭」两态分拆。
### Q3 · Esc 范围确认(顺带确认项,低成本高保险——v1.1 新增)
**背景**:契约 2「Esc 只在营地语境」是卡的从严收窄(澄清文档只裁「Esc 唤浮窗三项」、未裁范围——S1)。收窄方向保守且已自标「用户未裁」,但若用户本意是全局 Esc 菜单,范围锁死即返工。
| 案 | 内容 | 代价 |
|---|---|---|
| 甲(推荐) | 确认「Esc 浮窗只在营地语境」——契约 2 现文成立 | 无(一句话确认) |
| 乙 | 用户本意为全局(或更宽范围) | 本卡范围重开=契约 2/T1/V1 大改,且触 08:192 Beta 行口径 |
裁决方式:随卡片评审顺带确认。
**裁定(2026-10-18)**:**甲**——确认「Esc 浮窗只在营地语境」(推荐案,用户令按推荐执行)。契约 2 从「卡的从严收窄」升格为已确认口径;S1 保留意见关闭。
---
**修订记录**:v1.0→v1.1(2026-10-18 grilling 子 Agent 对抗审查回写)——事实订正 5 处:F9 刷新链路失实(营地刷新腿随 CampOverlay 退役、`_refresh_presentations` 是战斗侧腿)→契约 5 改挂卡④营地刷新单口+T2 刷新时机清单;E2「调试接口直改钥石」能力不存在(DebugOverlay 钥石只读)→改隔离存档实例直写(smoke 先例);F2 行号拆分(_open_settings :1055-1057);F8 :191→:192;估时算术 2.5–3.5d→3–4.5d。自扩订正:契约 2 标卡的从严收窄+Q3 请用户确认。卡内可收 8 项:契约 3 放宽语境分支、契约 7 遮挡结论+栈语义、契约 4 前提成文、T1 语境判据、T2 刷新时机+golden 联动、T3 探针宿主定 screen_flow_probe+badge 断言+变异补二条、V1 按 Q1 分拆、V4/V6/V8/V9 订补。跨卡对齐:HUD 刷新单口(§0 接口+卡④ T3 定义)、子界面返回钮承诺(Q1 甲案前提=卡④ T3)、终局落点不变量(T0 互证)、探针路径依赖卡②③链(§0)。新增待裁点 Q2 浮窗关闭路径、Q3 Esc 范围确认。用户面裁决(裁决 9/10)零改动。
@@ -0,0 +1,189 @@
# 需求卡片:主菜单三入口化批(6 钮 → 3 钮)· 营地交互重做卡②
- 版本:**v1.2**(2026-10-18 grilling 轮次回写——§0 补卡④回设计段注记(契约 5 中间态延长为工程批交付后稳态);本卡零待裁点不变,无其他裁定事项)
- 来源:[需求澄清-营地交互重做-2026-10-18.md](../design/research/需求澄清-营地交互重做-2026-10-18.md)(唯一事实源:④结构树「主菜单(需改动:6 钮 → 3 钮)」、⑤裁决 1、②反参照、⑦切批原则②)
- 归属:呈现层/组合根(`game/presentation/`)——营地交互重做五卡之二
- 排期:未编入(2026-10-18 用户令:需求卡片不预占迭代号,批次归属按工作量另裁)
- 开工门:U0(用户 `/iter` 发令);**零待裁点**;硬依赖卡③、中间态依赖卡④(见 §0/契约 5)
## 0. 前置依赖与并行性
- **硬依赖卡③(选档界面)**:「进入存档」钮的落点=选档界面。**本卡与卡③必须同批交付或卡③在先**(卡内推导,防死钮——澄清⑦只定切批原则,「同批或在先」是本卡的防死钮推导,非用户裁决)——禁以死钮/占位钮形态合并(违契)。
- **卡④(营地场景图)依赖(v1.1 补明;v1.2 注:卡④已回设计段)**:冒险入口探针段的新路径是「进入存档→选档→进档→营地→大门两分支→开局」——卡③同批到位也解决不了这批探针(卡④未到位时无路可走)。中间态处置见契约 5。**卡④ 2026-10-18 回设计段(美术设计定稿未过前置闸)**——契约 5 的中间态将从「批内临时」延长为「工程批交付后的稳态」,直至卡④重新立卡落地;实现报告「已知中间态」节按此登记。
- 卡④(营地场景图)承接本卡撤出的「开始冒险/继续上局/营地/生涯」四功能入口;本卡只负责主菜单侧撤出与接线,不负责落点实现。
- 卡①(存档制数据层)是卡③的前置,间接构成本批链的数据面底。
## 1. 目标与完成定义
**目标(澄清④照录)**:主菜单 6 钮 → 3 钮——**进入存档 / 设置 / 退出游戏**(裁决 1:用户原话「主菜单界面应该只有 3 个入口:①进入一个存档 ②游戏的设置 ③退出游戏。开始冒险,和营地相关的都应该是一个存档内的东西」)。
**相对现状,新增了什么**:
1. 主菜单按钮组从 6 钮(继续上局/开始冒险/营地/生涯/设置/退出游戏)砍到 3 钮;
2. 「进入存档」新钮接线到卡③选档界面;
3. 撤出钮的功能去向显式化:开始冒险/继续上局 → 营地大门(卡④,裁决 5 两分支);营地 → 存档内场景图(卡④);生涯 → 营地床铺旁笔记本(卡④);
4. 主菜单侧断点互斥确认路径(现居开始冒险)整体移交卡④大门,主菜单禁残留。
**完成定义**:
1. 主菜单有且仅有三钮:进入存档/设置/退出游戏;四旧钮与两组组帽的处理按 §9 落定;
2. 「进入存档」可点到选档界面(卡③交付物);
3. 设置/退出游戏两钮行为零变化(澄清④:「设置(已实现 · 不动)」「退出游戏(已实现 · 不动)」);
4. 冒烟/探针/golden 随批迁移完毕(§2 F10 全量位点表逐点过),批末重闸按改动域选档全绿;
5. 三份 `reports/` 产出物写齐(T3)。
## 2. 现状事实(2026-10-18 实查;开工日 T0 复核行号)
| # | 事实 | 出处 |
|---|---|---|
| F1 | 开始覆盖层构建=六钮+两组组帽:「── 冒 险 ──」组(继续上局/开始冒险)、「── 营地与系统 ──」组(营地/生涯/设置/退出游戏);续玩钮初始 `visible=false`(有断点才亮,可见性与文案归组合根刷新) | `game/presentation/ui_assembler.gd:128`/:130-138/:141-153 |
| F2 | 菜单屏壳持有六句柄(`lvbtn/resumebtn/campbtn/careerbtn/settingsbtn/quitbtn`),取值在 `_ready` | `game/presentation/scenes/menu_screen.gd:9-16`/:27-31 |
| F3 | 组合根接线:lvbtn→`_start_adventure_from_menu`;resumebtn→`_resume_from_menu`;campbtn→`_camp_pres.open_camp`;careerbtn→`_open_career`;settingsbtn→`_open_settings`;quitbtn→`_quit_game` | `game/presentation/main.gd:307-309`/:331-334 |
| F4 | 开始冒险的断点互斥确认:有断点先出 ConfirmDialog(「已有未完冒险(第 N 关)——开新冒险将覆盖旧断点」),确认才弃旧断点写盘开局——该路径整体移交卡④大门(澄清④:「断点弹窗保留移位」) | `main.gd:475-497` |
| F5 | 续玩钮可见性刷新=断点在档态(`_refresh_resume_button`)。**消费面(v1.1 补全)**:main.gd:194(boot)/:319(注入 CampShopPresenter ctx)/:704/:1063/:1101;camp_shop_presenter.gd:19/36/55(ctx 字段+on_camp_closed 调用);probe_ui_util.gd:117-120(isolate_save 的 refresh_resume 参数,多探针传 true);pacing_queue_test.gd:30 及 F10 表全部探针位点 | `main.gd:507-514` 及上列各处 |
| F6 | 冒烟 V2 断言六钮非空(`menu.start_overlay != null and menu.lvbtn != null and …`) | `game/smoke/smoke_all.gd:163` |
| F7 | 生涯.md 信息架构记载现行六钮组(「冒险」组+「营地与系统」组)与生涯入口=开始层生涯钮 | `design/gdd/systems/跨局循环/生涯.md:9`/:11-23 |
| F8 | camp.md 定位句载「主菜单营地独立入口进入」 | `design/gdd/ux/camp.md:10` |
| F9 | 08「三 · 界面」表载主菜单/开始覆盖层/营地/生涯页四行(均在役);08 头注纪律=增删条目须用户裁,状态列可改 | `design/gdd/08-Alpha版本标准.md:102-105`/:5 |
| F10 | **探针/单测/闸机影响面全量清单(v1.1 重列——初查「五探针」严重不全)**:见下表 | 全仓 grep 实证 |
| F11 | menu golden 基线在役:`game/tests/golden/menu_boot.png`(迭代 28 新增);对比段=render_gate.sh「菜单 golden 逐像素」节;重制入口=`tools/golden_baseline_refresh.sh --menu`(该脚本守卫素材齐盘,缺位拒跑) | `game/tests/golden/` 实查;`tools/render_gate.sh`(菜单 golden 节);`tools/golden_baseline_refresh.sh` 头注 |
| F12 | art-bible §7.4 小字号豁免为**一条合并条款**(条带内读数+装饰 caption 两类,:433),主菜单分组 overline×2(「── 冒 险 ──」「── 营地与系统 ──」)只是枚举中两个片段——禁整行删,只能 excision 片段;注销以 §9 第 1 条裁定为条件。另有两处代码注释引述组帽名(main.gd:287、career_overlay.gd:3,实施本体内可自理) | `design/art/art-bible.md:433`;`main.gd:287`;`career_overlay.gd:3` |
| F13 | 07-体验验证清单有两处引述主菜单形态(:170「左操作列(冒险/营地与系统两组)」、:192「营地与系统组出现生涯钮」)——随本批入口拓扑改 | `design/gdd/07-体验验证清单.md:170`/:192 |
### F10 全量影响位点表(20+ 位点,按闸归类)
| 位点 | 依赖内容 | 所属闸 | 本批处置 |
|---|---|---|---|
| `ui_probe.gd:28-55` | 营地钮驱动+余额+秘宝匣 12 行断言 | probe_gate | 改走「进入存档→选档→进档→营地」新路径 |
| `ui_click_probe.gd:59-127` | 营地购买合成点击全链(campbtn 驱动) | probe_gate --click | 同上 |
| `ui_click_probe.gd:224-228`、:462-518 | resumebtn 断言+整条「断点段」(中断→续玩全链+互斥确认两分支,约 80 行) | probe_gate --click | **断点确认段随弹窗移交卡④**(契约 4);卡② T1 只摘钮后保留函数直调中间态(契约 5) |
| `ui_struct_probe.gd:41-45` | camp 结构审计(营地钮驱动) | probe_gate 默认 | 改新路径 |
| `ui_struct_probe.gd:54-56/:69` | careerbtn 生涯入口链 | probe_gate 默认 | 改走卡④笔记本路径 |
| `ui_struct_probe.gd:86`、:163-183 | `_start_adventure_from_menu`+resume 专项(:168 刷钮、:170 续玩) | probe_gate 默认 | resume 专项随钮退役改写;冒险段见契约 5 |
| `screen_flow_probe.gd:53`、:109-123 | 营地可见态+营地开合段 | probe_gate 默认 | 入口段归卡②;营地键语义/开合/篝火段归卡④(分界写入两卡 T 卡) |
| `screen_flow_probe.gd:130-136` | ④菜单→冒险 lvbtn 步 | probe_gate 默认 | 契约 5 中间态;终态归卡④ |
| `shot_probe.gd:103-119`、:138-145、:193 | careerbtn 生涯截图段+lvbtn 关卡截图段(render_gate 七屏链三段的入口在本批被拆) | render_gate | 生涯段归卡④;关卡段契约 5 中间态、终态归卡④ |
| `shot_probe.gd:126-133` | camp 截图+关闭钮查找 | render_gate | 归卡④(营地键/收闭改缆) |
| `fx_shot_probe.gd:36-40`、:47 | lvbtn 查找+点击,零命中即 `_fail` | render_gate | 契约 5 中间态 |
| `t17_defer_probe.gd:29-33` | lvbtn 查找+点击 | probe_gate --full | 契约 5 中间态 |
| `ui_tune_probe.gd:96` | `main._start_adventure_from_menu()` 直调 | probe_gate --full | 契约 5 中间态 |
| `ui_input_probe.gd:35` | 同上 | probe_gate **默认必跑** | 契约 5 中间态 |
| `layout_probe.gd:27` | 同上 | probe_gate **默认必跑** | 契约 5 中间态 |
| `smoke_all.gd:163` | V2 六钮非空断言 | smoke_all | 改三钮断言 |
| `smoke_all.gd:266-290` | V2d 续玩钮六断言(boot/回菜单态) | smoke_all | 随钮退役改写/注销 |
| `smoke_all.gd:322/:326`、:411-415 | V3g campbtn 直呼驱动营地模态开合 | smoke_all | 改新路径 |
| `smoke_all.gd:470-478`、:565-567 | V3i 生命周期阶段⑨(`_resume_from_menu` 全链)+`_stage_faces` 的 `resume_vis` 键 | smoke_all | 随续玩入口迁卡④改写 |
| `smoke_all.gd:328/:439/:598/:628` | `_start_adventure_from_menu` 直调 ×4 | smoke_all | 契约 5 中间态 |
| `pacing_queue_test.gd:30/:33` | `_refresh_resume_button`+`_start_adventure_from_menu` | 单测(33 套之一) | 函数去留按 §9 第 2 条 |
| `probe_ui_util.gd:117-120` | `isolate_save` 的 `refresh_resume` 参数→`main._refresh_resume_button()`,多探针传 true | 全部探针共用 | 函数去留按 §9 第 2 条连带 |
**T0 清点口径(v1.1 定死)**:全仓 grep `lvbtn|campbtn|careerbtn|resumebtn|_start_adventure_from_menu|_resume_from_menu|_refresh_resume_button|start_overlay`,零意外命中才收口;清点结果写成文(T0 产物),作为 T2 迁移清单的基线。
## 3. 设计契约(红线,违反 = L3 停机呈报)
🔴 **契约 1 · 三钮且仅三钮**:进入存档/设置/退出游戏(裁决 1)。主菜单禁留任何存档内功能入口——开始冒险/继续上局/营地/生涯四钮彻底撤出(禁隐藏态残留、禁置灰态残留)。
🔴 **契约 2 · 设置与退出零行为变化**:两钮已实现不动(澄清④结构树原文);本批只保留其接线,禁借机改设置面或退出路径。
🔴 **契约 3 · 「进入存档」落点唯一**:只接卡③选档界面;禁直连营地/冒险(存档语境选择先行——澄清④结构树层级)。
🔴 **契约 4 · 断点确认路径整体移交**:主菜单侧禁残留「开新冒险覆盖旧断点」确认逻辑(main.gd:475-497 段随迁卡④大门,裁决 5 两分支);移交后主菜单无任何写档路径。断点确认探针段(ui_click_probe:462-518 等)随弹窗移交卡④ T5 接收,本卡 T2 明列移交项。
🔴 **契约 5 · 硬依赖卡③+卡④中间态条款(v1.1 补)**:本卡与卡③同批或卡③在先,禁死钮合并。**卡④未到位批内**:`_start_adventure_from_menu`/`_resume_from_menu` 两函数保留在 main.gd、仅摘菜单接线(T1 现文「只摘除主菜单侧调用」即此路),冒险段探针暂维直调旧函数、卡④到位再迁——该中间态是合法交付态,须在实现报告「已知中间态」节登记;禁为凑绿而把探针断言弱化成假路径。
🔴 **契约 6 · 探针/golden 契约**(属仓库既有测试纪律的卡内成文,非用户裁决):入口路径迁徒的探针段随批显式改写并留痕;menu golden 漂移按「核热区限预期面→显式重制+呈报→复闸」流程执行,超预期=L3。
🔴 **契约 7 · 不做形态重设计**:本卡只砍钮不重排菜单形态(双列布局/立绘看台不动——砍钮后的布局适配属 §9 代拍板微调圈)。反参照纪律(澄清②:拒「各种框框」)的兑现归卡④营地场景图,本卡不借尸还魂。
## 4. 范围边界
**做**:`build_start_overlay` 钮集砍到 3(含组帽与左列布局适配);`menu_screen` 句柄面;组合根接线(撤 4 接 1,含 camp_shop_presenter.gd 的 `_refresh_resume_button` ctx 摘除——v1.1 补列实施本体);冒烟 V2 断言改写;F10 全量位点表逐点迁移;menu golden 重制+呈报;反哺点清单。
**不做**(明示去向):
- 选档界面本体 → 卡③;
- 营地场景图/大门动线/生涯改挂 → 卡④;
- ESC 浮窗与营地顶栏 → 卡⑤;
- 设置面/退出路径的行为改动 → 无(契约 2);
- 主菜单视觉形态重设计(换底/新素材/布局重构)→ 不在本批;如用户要形态级重做,另立裁点。
## 5. 关联文档同步面
> **v1.3 口径**:本批禁写 `design/` 整目录与根规则文件,唯一可写目录 = `reports/`;下表一律执行为列进反哺点清单。08 写入权限三卡统一口径(v1.1 对齐):**状态列可改;注记改写列反哺点随清单呈报;增删行须用户裁**。
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| `design/gdd/systems/跨局循环/生涯.md` | :9 信息架构「现行主菜单按钮组……『冒险』组……『营地与系统』组」+:11-23 结构树——六钮组记述整体失义;生涯入口从开始层迁营地笔记本 | 反哺点 · 信息架构节改三钮组+生涯入口位改挂 |
| `design/gdd/ux/camp.md` | :10「主菜单营地独立入口进入」——营地入口改挂存档内场景图 | 反哺点 · 定位句改挂 |
| `design/gdd/08-Alpha版本标准.md` | :102-105 三·界面表四行——状态列可改;入口拓扑注记列反哺点 | 反哺点 · 列清单(统一口径见上) |
| `design/gdd/07-体验验证清单.md` | :170/:192 两处引述主菜单形态(左操作列两组/营地与系统组生涯钮) | 反哺点 · 列清单(v1.1 补列) |
| `design/art/art-bible.md` | :433 小字号豁免合并条款中「主菜单分组 overline×2」枚举片段——组帽撤后 excision(禁整行删),以 §9 第 1 条裁定为条件 | 反哺点 · 列清单 |
| `design/gdd/06-待办清单.md` | 本卡登记条 | 反哺点 · 列清单 |
| `roadmap.md` | 迭代行编入/状态刷新 | 反哺点 · 列清单 |
| `game/presentation/ui_assembler.gd`、`scenes/menu_screen.gd`、`main.gd`、`camp_shop_presenter.gd`(v1.1 补)、`game/smoke/*`、`game/tests/golden/*`、`tools/golden_baseline_refresh.sh`(重制入口,只跑不改) | 实现与断言/基线本体 | 实施本体(可写) |
## 6. 任务卡
> 估时按 Claude 工作日口径;每卡出口自跑轻闸;开工日 T0 复核全部行号。
### T0 事实坐实(≈0.5–1d)
- 复核 §2 全部行号;按 F10 表尾清点口径全仓 grep,清点结果写成文(T0 产物);
- 与卡③对齐:「进入存档」钮的目标句柄与选档界面开层函数名先定(跨卡接口);与卡④对齐断点确认探针段的移交/接收分界(契约 4)。
### T1 钮集砍伐与接线(≈0.5–1d)
- `build_start_overlay`:六钮→三钮;组帽去留与左列布局适配按 §9 拍板(冒险组帽必撤——组内零钮;见 §9 第 1 条);
- `menu_screen` 句柄面随裁(撤 4 留 3+新增进入存档钮句柄);
- 组合根:撤 lvbtn/resumebtn/campbtn/careerbtn 四线,接「进入存档」→选档界面;`_start_adventure_from_menu`/`_resume_from_menu` 按契约 5 保留(摘接线不删函数);
- `_refresh_resume_button` 去留按 §9 第 2 条:**卡④大门不复用该函数**(卡④ T4 已明示——两分支直读 `has_breakpoint`,无钮可刷),故只剩删除一路;删函数同批清全部消费点(main.gd 五处+camp_shop_presenter.gd ctx 字段与 on_camp_closed 调用+probe_ui_util 参数+pacing_queue_test+各探针传 true 位点);
- 断点确认段(main.gd:475-497)的移交:本批只摘除主菜单侧调用,弹窗本体与两分支逻辑落卡④大门。
### T2 断言、探针与 golden 迁移批(≈1.5–2d)
- smoke V2 六钮断言→三钮断言(进入存档/设置/退出游戏非空;四旧钮句柄零命中);
- F10 全量位点表逐点迁移:入口路径段本卡改;断点确认段/生涯截图段按契约 4 移交卡④(本卡 T2 明列移交项,卡④ T5 接收);冒险段探针按契约 5 中间态处理(卡④到位再迁);
- menu golden:核漂移热区限钮集区→显式重制 `menu_boot.png`+呈报→复闸;
- **变异验证伴生**:新断言段定注入实验——例:把四旧钮之一接回(预期三钮断言红)、进入存档钮接错层(预期探针路径红);注入→最窄闸见红→精确还原→记录。
### T3 产出物落位卡(≈0.5d,末卡)
三份 `reports/` 写齐(实现报告含 golden 重制呈报记录、变异记录表、「已知中间态」节〔契约 5〕/代拍板追认单/反哺点清单)。
**估时合计 ≈2.5–4d**(v1.1 上调:探针面从「五探针」扩到 20+ 位点,T2 清点后重估)。切分预案:T1 出口可切(砍钮先落、断言迁移后落)——但契约 5 硬依赖卡③,实际切分价值低,建议与卡③同批单跑。
## 7. 验证闸(逐需求点验收清单)
| # | 需求点 | 测什么 | 落点/判定手段 |
|---|---|---|---|
| V1 | 三钮在位+既有断言族改写 | 进入存档/设置/退出游戏三钮非空且可点;四旧钮(开始冒险/继续上局/营地/生涯)在主菜单零命中;被本批废止/改写的既有断言族(smoke V2d 续玩钮态、V3g campbtn 驱动、V3i 阶段⑨续玩全链、`_stage_faces` 的 `resume_vis` 键)逐族有改写后断言承接 | 冒烟 V2 改写段+V2d/V3g/V3i 改写段+ui_struct_probe 结构断言 |
| V2 | 设置零行为变化 | 设置钮开合路径与既有断言一致 | 冒烟 V3g settings 模态段复跑 |
| V3 | 退出接线正确 | quitbtn → `_quit_game` 连接存在(headless 不可真退——接线断言代偿) | 源码/结构断言 |
| V4 | 进入存档可达选档 | 点击链路通到卡③选档界面(层可见+菜单隐藏) | ui_click_probe/screen_flow_probe 新路径段(依赖卡③) |
| V5 | 断点确认零残留 | 「开新冒险覆盖断点」确认路径仅存于卡④大门;ConfirmDialog 允许多消费方(卡③删档确认在役——切换机制见卡③ 契约 3) | 源码断言+ui_struct_probe 既有采样复跑 |
| V6 | golden 与七屏链 | menu golden 漂移限钮集区、重制有呈报、复闸绿;shot_probe 七屏截图链存在性自检全绿(career/camp/level 三入口迁移后仍七件非空) | render_gate golden 段+shot_probe 自检段复跑 |
| V7 | 左列布局几何不破 | 砍钮后双列不相交合同与按钮几何族(互压/等宽/出屏/零尺寸)复跑 | ui_struct_probe `_start_columns_contract`+`_audit("start")` 段复跑(v1.1 补机检项) |
| V8 | 反哺点清单 | §5 每条有落点 | 件核对表 |
**测试方式两分法**:V1–V7 机检自动化;**用户目检项=主菜单三钮观感(钮集砍伐后左列布局是否失衡)**——登记 07(实机目检=生命周期最后一步统一进行,不阻塞迭代,澄清⑥口径)。
**闸口径**:轻闸每卡出口自跑;批末重闸按改动域选档(本批碰 `game/` 代码/断言/golden → `--code`)全绿才合并;MC 零跑(零数值零行为)。
## 8. 异常分级
- **L1(自救)**:断言写法、探针路径选择、布局微调。
- **L2(记录继续)**:组帽去留与左列布局适配(§9 域内)、`_refresh_resume_button` 删除的消费点清理顺序、探针迁移中的中间态处理(契约 5 登记)、T2 估时随清点重估。
- **L3(停机呈报)**:卡③ 未同批到位导致「进入存档」无落点(停线等批,禁死钮合并);menu golden 漂移越出钮集区(形态面被波及=超出本批契约 7);发现设置/退出路径被意外触碰;F10 清点出现表外新位点且无法随批迁移。
## 9. 代拍板白名单(超清单必呈报)
1. 组帽与左列布局适配:**「── 冒 险 ──」帽必撤(组内零钮——退化态不留);「营地与系统」帽去留/改文案属代拍板,改名须追认单留痕**(v1.1 明写——保留原样=留一句指称不可达地点的文案,禁)。
2. `_refresh_resume_button` 去留:卡④不复用(卡④ T4 已证),默认删;删时同批清全部消费点(T1 列明)。
3. 「进入存档」钮的动词化命名与 tooltip 文案(对齐现役动词钮先例)。
4. 探针迁移中的中间态写法(路径分段断言 vs 端到端)+卡④未到位批内冒险段探针维直调(契约 5)。
5. 提交切分与 worktree 分支命名。
## 10. 待裁点
**零待裁点**(裁决 1 三钮结构、四功能去向均由澄清④结构树锁定;布局适配与组帽文案归 §9 代拍板+追认单留痕)。开工门 = U0(用户 `/iter` 发令)+ 卡③同批到位+ 契约 5 中间态条款随卡④排期一并确认。
---
**修订记录**:v1.0→v1.1(2026-10-18 grilling 子 Agent 对抗审查回写)——事实订正:F10 探针影响面从「五探针」重列为 20+ 位点全量表(漏列 fx_shot/t17_defer/ui_tune/ui_input/layout/ui_click 断点段/ui_struct resume 专项/shot_probe career+level 段/smoke V2d/V3g/V3i 等);F5 `_refresh_resume_button` 消费面补全并补列 camp_shop_presenter.gd 实施本体;F12 art-bible :433 合并条款 excision 表述订正;F11 补 render_gate 菜单 golden 段与 golden_baseline_refresh.sh --menu;新增 F13(07 两处引述)。自扩标注:契约 5「同批或在先」标卡内推导、契约 6 标仓库纪律成文。卡内可收:契约 5 补卡④中间态条款、§9 第 1 条组帽必撤明写、§9 第 2 条删除面订正(卡④不复用)、V5 ConfirmDialog 多消费方表述、V 表补既有断言族/左列几何/七屏链三项。用户面裁决(裁决 1)零改动。
@@ -0,0 +1,292 @@
# 需求卡片:第二 / 三关棋盘观感——亮度与对比度批(T1 定性人闸 · T2 按轴修法 · 验收三件套 · 文档面全走反哺点)
- 版本:**v1.4(2026-10-17 开工前预授权 U1〔用户于开工前一次性决断,防开发中反复打断〕——①Q2 甲/乙由「延裁·T1 出口现场裁」改**判据自动裁**:甲案候选样张读数达标即直接走甲不停机,仅当读数证伪「纹理太碎」假说时才呈报裁乙;②V2 定向目标带数值授权批内按 T1 实测读数自定并随定性报告呈报,T1 出口人闸只确认轴归因与修法方向;③详见 §10 Q2 条与开工门 U1 预授权条);v1.3(2026-10-17 文档同步闸 v3 口径修订,纯文档批〔分支 carddoc-20261017〕按用户六条裁定执行——①本批(代码实现批)禁写 `design/` 整目录与根规则文件,§5 同步面的同步义务一律执行为「列进 `reports/iter30-反哺点-<完成日>.md`(哪个文件哪一节、改成什么、依据),用户会话裁决后归文档批落文」;②产出物落位换代:实现报告/代拍板追认单/反哺点清单三份落 `reports/`,不再 `design/qa/`;③T5 末卡改「产出物落位卡」(三份 reports/ 文件写齐才算收口);④闸口径按域选档:重闸 = `tools/run_all_gates.sh` 按改动域选档(本批 → `--code`),卡内不再写死闸件名单与「全量档」类字样;⑤实机目检项写进 `reports/iter30-实现报告-<完成日>.md` 实机目检总清单,「登记 07」转反哺点;§10 裁决留痕原文不动);v1.2(2026-10-16 裁决留痕版:三卡待裁项按用户令定案——Q3 已裁甲·同批、Q2 延裁留痕并将裁点挂至 T1 出口呈报硬流程步骤、排期栏定实「已编入迭代 30」与三卡串行序位、§4B 跨卡依赖按已裁事实改实、全卡零悬空待裁点;v1.1 同日 grilling 审查修订见 §11;v1.0 同日成文)**
- **指路订正(2026-10-20)**:徽章卡(迭代 30 卡①)已按 doc-conventions §11「吸收即死」退役,本卡对其三处指路句改为结论内联+提交号 `7ffd1dc0`,裁决内容零变更。
- 来源:[06-待办清单](../design/gdd/06-待办清单.md)「第二 / 三关棋盘观感——亮度与对比度」小节(2026-10-13 用户裁定条)+ [playnote](../design/research/playnote.md) 用户试玩原始记录:「UI优化,第二第三关的棋盘看着太累了;不知道是因为亮度还是对比度的原因,看着非常费劲,非常不舒服」
- 归属:**表现层美术修批**(06 在册条目直接写卡;两轴归属 = [HUD框架](../design/gdd/systems/表现与支撑/HUD框架.md)(UI 轴)+ [美术圣经](../design/art/art-bible.md)(素材轴),定性前两方共裁——沿用 06 条裁决)
- 排期:**已编入迭代 30(2026-10-16 用户令编入,roadmap 行已在案;批内状态刷新列反哺点)**。同迭代三卡串行序位第 3:未开格类型徽章批卡(迭代 30 卡①,已入库合并 7ffd1dc0,卡片已退役)→[战斗一屏样张批卡](需求卡片-战斗一屏样张批-2026-10-16.md)→本卡(徽章→样张→观感)。**并行例外**:本卡 T1/T1b 采样与定性读数允许与前两卡并行穿插——依据=采样是只读动作(出帧/读数/样张均不触碰 golden 三张、样张主板、§5 同步面文档等汇聚文件),落码修改(T2 起)仍按上述序位串行。开工门 = U0,须用户 `/iter` 发令;且 T1 出口定性人闸未过之前禁止动码——该闸 = [06 本条](../design/gdd/06-待办清单.md)既有裁决硬步骤(「开工前先过『素材轴 / UI 轴』定性人闸」,2026-10-13 用户裁定;[08 版本历史](../design/gdd/08-Alpha版本标准.md) v0.3 同款注),**不是待裁点**(v1.1 撤销原 Q1,见 §10)。
- **立场前提(用户原话,本卡设计的第一约束)**:此条立项原因就是用户实机觉得现在的画面累眼、且对「纯程序化重产现状」明确不满——「如果还是用原有方式弄出来的东西,有没有可能还是我不满意的?」。本卡对此的正面回应 = ①第一步定性用**可量化的读数归因**(明度直方图 / 相邻格对比 / 高频能量 / WCAG 对),禁止凭感觉猜轴;②两条修法各自的产出物写清**相对现状新增什么**(§6 T2 两案效果上限表);③**诚实的效果声明**:观感是主观项,机检只能证伪(读数红 = 必有问题)不能证真(读数绿 ≠ 用户满意),**阻塞性人闸全部前置**(T1 定性闸 + 契约 4 方向闸),入库后实机目检按 2026-10-12 用户令口径**登记不阻塞**——目检项登记进 `reports/iter30-实现报告-<完成日>.md` 实机目检总清单(「入册 07」列反哺点;[AGENTS.md](../AGENTS.md) 红线「真人检测只登记不阻塞——禁以等目检为停工理由」口径不变),用户复判否决走 §7 V4 回补机制(行回待做 + 06 立残留条,落文按 v3 口径归文档批)。防「改一轮还是不满意」的机制 = **先出改前/改后并排对比读数样张给用户定性确认方向,方向过了人闸才落码**(🔴 契约 4)——方向若被否决,返工停在样张层,不烧落码与基线。
---
### 0. 前置依赖与既有裁决
| # | 前置 | 内容 |
|---|---|---|
| P1 | **定性人闸(06 条既有裁决——流程硬步骤,非待裁点)** | 06 原文(445 节内):「开工前须先定性(沿用既有裁决)……两轴修法完全不同,定性错了等于白改一轮」+ 状态行「开工前先过『素材轴 / UI 轴』定性人闸」(2026-10-13 用户裁定条;该要求最早载于 06「奇物呈现优化探讨备忘两孤儿点」(e),本条承接转正)。本卡 T1 即该闸承载,结论过用户确认才进 T2——v1.0 曾把此闸再列 Q1 待裁,v1.1 撤销(禁再问已裁项) |
| P2 | **与「呈现层残余 <4.5:1 文字位」条的分工(06 条既有注记)** | 06:451 分工句原文:「本条管**棋盘区域整体的观感**(亮度/对比度/费劲感),是体感问题;『呈现层残余 <4.5:1 文字位』管**具体文字位的对比度读数不达标**(B 区站桩名行/敌顺位徽标/RAP 反馈行三处),是机检可判的硬指标。两条不同面,不互相替代,各自保留」;该文字位条已随迭代 26 T3 完成(06:443)。本卡管棋盘区域整体观感(体感问题),**禁吞并该条**(🔴 契约 2);T1 读数若发现新的文字位红点,另行登记,不并入本卡 |
| P3 | **08 标准覆盖行** | [08-Alpha版本标准](../design/gdd/08-Alpha版本标准.md)「五 · 表现」表「棋盘观感(第二/三关亮度与对比度)」行(08:145)现为**待做**(事实源指向本 06 条);Alpha 完成判据 = 全部条目在役 ⇒ 本卡完成时该行 待做→在役 改写列反哺点(§6 T5;时机=本批入库,落文归文档批,目检复判否决的回补机制见 V4) |
| P4 | **08 未决项关联(按名指路;v1.1 按实查改写)** | 08「七 · 未决项」现行表含「**素材升档重产进不进 Alpha**」行(2026-10-16 实查为该表第 6 行,另有「**立绘清晰度回退评估**」行——未决项表 2026-10-16 v1.6 重编号过,**行号不作指路依据,一律按名找**);「素材升档重产」在「五 · 表现」表现为**待裁**(08:154)。06「资产升档重产批」条现行状态注记 = 2026-10-04 用户令「暂不做、先忽略,重启=用户点名」+ 2026-10-06「优先级再降」+ 2026-10-06 方案二注记(原升档路线已被八敌逐键定档实质走完、剩余挂起项=提灯点亮解禁候选)。划界:该批面向**立绘/小人帧尺寸升档**,本卡素材轴乙案 = **L2/L3 棋盘瓦片色板/纹理方案重做**——对象、管线、闸面均不同面,**裁本卡乙案 ≠ 放开升档重产**,呈报时须带此划界(§6 T2 乙案行) |
| P5 | **渲染闸与基线现状** | 棋盘三关 golden 基线冻结于 2026-09-30(`tools/golden_compare.py:11`),改瓦片/改常量**必然**破 Δ≤16/changed≤2% 容差 ⇒ 基线换代是本卡的确定义务而非例外处理(§7 V3) |
---
## 1. 目标与完成定义
**目标**:把 L2/L3 棋盘「看着太累」的观感问题**归因到轴**(素材轴 / UI 轴 / 两轴共因),按轴修复,并经用户实机复核确认体感改善。
**完成定义**(五件齐才算完成,缺一即该条在 06 保持待办):
1. T1 定性报告交付:逐关三测面(棋盘瓦片区 / 舞台底与屏根 / 叠加层)读数表 + 归因结论(轴判定,引用具体数值);**T1 出口定性人闸过**(06 已裁硬步骤,P1);
2. T2 修法按裁定轴别落码/落素材,既有样张口径闸全部保持绿(A6 梯度均值 ≥4.70、F6 立面双明度带 Δ≥18、格底明度档 §4.1、图底分离——见 §2.4;**注**:该组断言现行落点=样张主板(dungeon 拼板,`render_sample_sheet_v3.py:130-131`),L2/L3 分关实测属本批新建读数件(T1b),见 §11 攻击面 2);
3. 验收三件套走完:机检读数达标 + 渲染闸 golden 基线显式重制并呈报换代面 + 用户实机目检轮**登记**(目检项登记进 `reports/iter30-实现报告-<完成日>.md` 实机目检总清单,「入册 07」列反哺点;2026-10-12 用户令=登记不阻塞入库,否决走 V4 回补);
4. 08「五 · 表现」棋盘观感行 待做→在役 改写列反哺点(含 07 目检登记注;落文归文档批);
5. §5 同步面每条在 `reports/iter30-反哺点-<完成日>.md` 有落点(06 对应条目状态更新条在内);权威文档与根规则文件零直改。
**效果不确定性的诚实声明**:观感是主观项。机检读数能证伪(超带 = 必有问题)不能证真(达标 ≠ 满意)。证真面由**前置人闸**承担(T1 定性闸 + 契约 4 方向样张闸——方向不过不落码);入库后的实机目检轮按 2026-10-12 用户令「真人检测只登记不阻塞」执行,用户复判若仍不满意 = V4 回补机制触发(08 行回待做 + 06 记残留、下批重开),不算本批未入库。
---
## 2. 现状事实(2026-10-16 实查;开工日自行复核行号)
### 2.1 关级与瓦片(素材轴现状)
| # | 事实 | 出处 |
|---|---|---|
| F1 | 三关板型与图类型:L2 12×12 underdark / L3 13×13 deep_underdark;**L1 行群主体 10×10 dungeon、但含 12×12 dungeon 行**(2026-10-16 逐行实查 `board_gen.tres`——level_index 1 段内有一行 12×12),故 T1 的 L1 参照位读数面须覆盖两种板型(词表 v1.1) | `game/data/tables/board_gen.tres` 各行;`game/data/schemas/board_gen_table.gd:13` |
| F2 | 每关瓦片 = **墙 16 件 + 地面 5 变体,合计 21 件**(v1.0 误写「墙类 21 件」,v1.1 订正:16 唯一墙名单单点在 `TILE_WALL_NAMES` 常量数组,件名数=16;21 为总数)按 `terrain_%s_%s.png` / `terrain_floor_%s_%d.png` 格式装载;源 dungeon 套为 v9.3 定稿,underdark/deep_underdark 套由程序换色产出;另有**不参与换色的板面相关件**:`flag_seal.png`(封印旗,三关共用独立可选件) | `game/presentation/views/board_view.gd:80-89`;`tools/recolor_terrain_tiles.py` 头注;素材实盘 `game/assets/art/board/`(underdark/deep_underdark 各 21 件与 dungeon 套同构;素材不入 git,用户裁定) |
| F3 | 换色方法 = 槽位家族重映射(wall/facade/floor/crater 四族),**亮度秩序逐像素保持**、确定性零随机、唯一色数与源一致;目标色表在脚本 `PALETTES` 内 | `tools/recolor_terrain_tiles.py:10-12`(方法注)+ `:40-60`(色表) |
| F4 | 现行换色色表读值:underdark 地面 `G_BASE (62,66,80)`、crater 最深 `P_DEEP (9,10,15)`;deep_underdark 地面 `G_BASE (46,48,64)`、crater 最深 `P_DEEP (5,5,9)`——**冷蓝紫、低明度、crater 近纯黑**;对照 dungeon 源 `G_BASE (88,66,50)` 暖中明度 | 同上 `PALETTES` |
| F5 | 色相域方向(机检在案):underdark ≈180°–260° 灰白蓝紫 / deep_underdark ≈200°–280° 蓝黑紫黑;断言「deep 墙顶明度恒暗于 underdark」 | `game/tests/unit/presentation/terrain_tile_sets_test.gd:61-64, :82`;方向权威 = art-bible §4.3 |
| F6 | 图类型换皮四槽(`tile_closed`/`tile_open`/`wall_ambient`/`variant_tint`)与恒定不变槽(信息语义色全图型恒定、格底两档明度关系恒定);格底硬指标:未开墙顶 L≥0.30、已开底走世界底层档候选 L 0.08–0.14、饱和 ≤0.55、避 300°–345° 禁入带 | [art-bible](../design/art/art-bible.md) §4.3 / §4.1「对比硬指标」/ §4.2 紫赤条 |
### 2.2 UI 轴现状(舞台底与叠加层常量位点)
| # | 事实 | 出处 |
|---|---|---|
| F7 | 舞台底 `STAGE_BG #3E342A`(62,52,42)= B 区舞台面板暗底;屏根 `BG_ROOT #3A2E22`;暖亮档 `BG_BRIGHT #453723`(提暖提亮禁近黑配色总纲在册) | `game/presentation/views/ui_kit.gd:111-113, :121`;`battle_stage_view.gd:44-47` |
| F8 | 视野迷雾叠加层:灯光区半径 `FOG_RADIUS 8`(基准值改动 = 非白名单须用户);**区外未开格 = 全黑不渲染(不透明纯黑盖全部叠层)**;区外已开格 = 记忆态灰显;雾轮廓 `UiKit.FOG_OUTLINE` | `board_view.gd:137, :817-822`;`board_cell_unit.gd:111-117, :252-256`;规格 = art-bible §6.5 + HUD框架「视野迷雾」节 |
| F9 | 数字墨三态管线(v3.4 定案):双峰纹理板(underdark/deep_underdark 系)= 色牌垫底 `DIGIT_PLATE + 深墨 #33261B`;亮族判据 p90 ≥4.5:1 / 均值 ≥2.5:1 | `board_view.gd:987-989`;art-bible §4.1 数字墨条 |
| F10 | 类型微光 v2 呈现**规格** = 内缘带状泛光 α170 / 带宽 cell÷8,亮度不压格底明度档(§2 微光例外);五组色带样张 v2 定稿。**v1.1 注**:类型微光游戏内**尚无独立实装**(呈现层仅接触带微光在跑;实施归同迭代 30 的未开格徽章批,见 §4A)——本卡 T1 的微光测面读数源=样张 v2 静态定稿图,实机渲染帧里没有该层 | art-bible §4.2「类型微光色带」条;HUD框架「未开格类型微光」节实装状态行(:130-142) |
### 2.3 L2/L3 差异面(同批与否的判据)
- 板型不同(12×12 vs 13×13)、色板不同(F4/F5 两套槽值,deep 系整体再暗一档)、格边长换算随板型变(06 在册「格边长三方取值不一致」条为已知偏差,本卡不动);数字墨模式两关同属双峰板色牌态(F9)。⇒ L2、L3 观感读数**必须分开设点**,修法同批——Q3 已裁甲·同批(2026-10-16 用户令,§10),两关槽值差异由 T1 分关读数(T1b)承载。
### 2.4 既有量化口径(样张 v3 与机检链,验收判据引用面)
| # | 口径 | 定值 | 出处 |
|---|---|---|---|
| C1 | **A6 观感密度:明度梯度均值**(相邻像素相对亮度差均值——高频细节能量;低频双峰由 A3 承载) | ≥4.70(v1 同口径实测 4.09 上调 15%) | `tools/render_sample_sheet_v3.py:26, :338, :1007-1022`(历史脚本注释含 v1 实测值)。**v1.1 核注**:该组断言(A3/A6/F6)现行作用面 = 样张主板(`terrain_*_dungeon` 拼板,脚本 `:130-131`)——L2/L3 瓦片改动**既不会触动这组闸、也测不到它们**;「分关实测」属本批新建读数件(T1b),非现成能力 |
| C2 | **F6 立面双明度带** | Δ≥18(现行执法定值 `FACADE_MIN`) | 同上 `:339`、`:996` 消费点与 v3.5 冻结口径注(`:1154`) |
| C3 | **A3 图底分离**(墙/地) | **现行执法 = v3.5 冻结定值 A3b Δ≥30**(方向稿实测 38);旧 Δ≥55 系色牌制地板 L0.036 时代校定,与格底分档带数学冲突已退役 | 同上 `:975-979`(退役注+现行 check)、`:1154`;`:23, :340` 之 55 为历史注释残迹 |
| C4 | 格底明度档 | §4.1:世界底层档候选 L 0.08–0.14 / 墙顶 L≥0.30 / 饱和 ≤0.55(48 色上限与 RGB 三通道差 ≥8/255 双门在 §4.1 增量纪律在案;「待定现用」态释义同节) | art-bible §4.1 |
| C5 | 渲染闸现行链 | `tools/render_gate.sh` 四段:shot_probe 七屏→`shot_checker.py` A–D+F 语义断言(B 文字对比 ≥4.5:1 / C 明度三档带 / D 文字禁压纹理 / F 文字在判据〔2026-10-15 补〕;E 焦点预算归人闸)→ fx/board 取证 → 棋盘三张 golden(差 ≤16、changed ≤2%)→ 菜单 golden;基线重制工具 `tools/golden_baseline_refresh.sh`(缺省模式=棋盘三张;`--menu`=菜单全屏;素材缺位拒跑;呈现批 agent 自行换代+提交说明强制写明触发原因——权限口径在其头注) | `render_gate.sh:8-25, :109-155`;`shot_checker.py:8-19`;`golden_baseline_refresh.sh:2-14` |
| C6 | 三关棋盘抓帧承载(读数采样源) | `board_shot_probe` targets = L1_dungeon / L2_underdark / L3_deep_underdark,随 render_gate 周期跑;同关驱动确定性=种子 420000+关号 + novice 18 步 + 1.2s 动画完结等待(可复现)。**v1.1 边界注**:帧面 = 空视口上裸挂 BoardView(900×900)——棋盘瓦片区与迷雾遮罩层**在帧内**,**舞台底/屏根像素不在帧内**(battle_stage_view/BG_ROOT 未实例化);「舞台底/叠加层只在渲染帧里存在」系 v1.0 不准确表述,舞台底为常量平铺(UiKit 可读值)。且 render_gate 过程帧落 mktemp 即弃禁入 git——T1 用帧须自行留档于库外目录 | `game/smoke/board_shot_probe.gd:34, :38-66`;`render_gate.sh:22`(过程产物纪律) |
---
## 3. 设计契约(红线,违反 = L3 停机呈报)
🔴 **契约 1 · 零玩法逻辑变更**:只动呈现(瓦片素材/色表、舞台底与叠加层常量、样张脚本判据)。板生成、数字真值、迷雾判定逻辑、`FOG_RADIUS` 基准值(改动须用户,`board_view.gd:137` 注)零触碰。
🔴 **契约 2 · 禁吞并文字位条**:「呈现层残余 <4.5:1 文字位」是另一面(该条已随迭代 26 完成,本卡不复活、不并账);本卡发现的任何文字位新红点 = 新登记条目,另批处理。
🔴 **契约 3 · 色板纪律不破**:任何换色/重产色板须过 art-bible §4.1 增量纪律双门(48 色上限、与既有任一色 RGB 三通道差 ≥8/255)+ §4.2 语义检查与信息面禁入带 300°–345°;素材轴甲案并须保持 recolor 脚本的亮度秩序逐像素保持方法学(改了方法 = 换案,须重述本契约)。
🔴 **契约 4 · 样张先行、方向人闸后落码**:T2 任一修法落码前,必先出**改前/改后并排对比样张 + 读数表**给用户定性;用户未确认方向 = 停在样张层,禁先行改素材改常量。此条是「防改一轮还是不满意」的机制本体。**v1.2 注**:素材轴甲/乙裁决呈报件(§6 T1 呈报硬步骤)与本闸是同批产物——用户呈报现场裁甲后,裁甲案时本闸即已过关、不重复呈报;裁乙案时乙方向样张另走本闸。
🔴 **契约 5 · 机检 ≠ 观感,前置人闸承担方向证真**:读数达标只构成必要条件,机检不能证明满意——「证真」面由**前置**人闸承担(T1 定性闸〔06 已裁〕+ 契约 4 方向样张闸)。入库后的实机目检轮按 2026-10-12 用户令口径执行(AGENTS.md 红线「真人检测只登记不阻塞」):目检项登记进 `reports/iter30-实现报告-<完成日>.md` 实机目检总清单即完成义务、不卡入库(「入册 07」列反哺点);**禁把「机检全绿」写成「用户满意」的等价表述**——用户复判否决时按 V4 回补(08 行回待做 + 06 记残留、下批重开,落文按 v3 口径归文档批)。(v1.1 改写注:v1.0 本条「完成判定必须含用户实机目检轮、目检未过禁宣布在役」与 2026-10-12 用户令冲突,已对齐。)
🔴 **契约 6 · golden 基线换代显式化**:改图必破基线——重制走 `tools/golden_baseline_refresh.sh` 显式流程(缺省模式重制棋盘三张:board_shot_probe 抓帧→`golden_board_crop.py` 按 meta 坐标裁剪→覆盖 `game/tests/golden/` 三张;触及菜单态加跑 `--menu`),并逐屏呈报换代面(新旧基线并排,沿 render_gate S2 停机点口径);权限与义务=呈现批 agent 自行换代、**提交说明强制写明触发原因**(refresh 脚本头注 Q6 在册);前置=素材齐盘(脚本逐项守卫,缺位拒跑)。**禁先刷基线后改图**(基线是判据不是障碍物)。
---
## 4. 范围边界
**做**:L2/L3 棋盘区域观感的定性归因(T1)、按轴修复落码(T2)、同批策略(T3)、验收三件套与基线换代(T4)、产出物落位(T5)。
**不做**(明示去向):
- 不动 L1 dungeon 套外观——除非 T1 读数显示问题为系统性共因(如迷雾档/舞台底全关同因,则 UI 轴修法天然全关生效,素材轴仍只动 L2/L3 色表);
- 不动数字墨三态管线本身(`_digit_ink_mode` 选模逻辑维持),只动其消费的板面;改后三模式断言 `terrain_tile_sets_test` 必仍绿;
- 不做「格边长三方取值不一致」条的处置(06 在册待扩板定档,另批);
- 不做「立绘清晰度回退评估」/「素材升档重产」两未决项的代裁(本卡甲/乙裁点仅覆盖棋盘瓦片重产路线,且已挂至 T1 出口呈报硬流程步骤——裁决留痕见 §10,未决项不代裁、禁重开);
- 不动未开格类型微光的呈现规格(§4.2 单通道纪律维持;**该层引擎尚未实装,实施归未开格徽章批——§4B**;T1 会把微光层列为读数额外测面〔证据级别=样张 v2 静态图,F10〕,T2 无「动参数」可言——若归因指向它,处置为联裁或走 art-bible §4.2 修订登记)。
---
## 4B. 跨卡依赖(同迭代 30 的两张同板面批——v1.1 新增;v1.2 按 2026-10-16 三卡已裁定案改实)
本卡与**未开格类型徽章批**(迭代 30 卡①,已入库合并 7ffd1dc0,卡片已退役)、**战斗一屏样张批**(`需求卡片-战斗一屏样张批-2026-10-16.md`)共用 L2/L3 板面,事实与已裁结果如下(只列事实与裁决留痕,他批未裁项仍不代裁):
| # | 交叠面 | 事实 | 本卡处置 |
|---|---|---|---|
| X1 | **徽章批微光层 × 本卡格底/墙顶瓦片改色,同一张未开格面** | 徽章批把五组类型微光实装进未开格(其 T0-② 五组明度档以 art-bible §4.1「未开格底 L≥0.30 不被压破」为约束基线);本卡素材轴改的正是 `tile_closed`(墙顶/未开底)明度——**两批改同一板面、先后互为约束**:本卡若抬/压墙顶档,徽章批五组明度档取值基线随之移动。art-bible §4.3 共同纪律已册:「三套候选色相均须与五组类型微光色带(§4.2)抽测互辨(格底与微光同在未开格面,邻近色相有吞没风险)」(:379) | 色板/微光互辨复测两批并档一次跑;本卡新色表呈报件须含「对五组微光色带吞没风险」逐项比对;**v1.2 定实(2026-10-16 用户令)**:三卡串行序位徽章→样张→观感(排期栏),golden 棋盘三张换代次数=先落者(徽章批)刷一次、本卡作为后落者再刷一次,不再挂呈报定序;徽章批微光**明度档 provisional 值**(其 Q2 已裁甲=本批定档)与本卡**格底明度档同基线**(art-bible §4.1 格底档 L 0.08–0.14、墙顶/未开格底 L≥0.30)——两卡改格底/叠光时须逐位比对 golden 防互踩,该约束已同步写入 §6 T2 修法约束 |
| X2 | **战斗一屏样张批 Q1(素材输入级别)/Q3(渲染手段)与本卡乙案(瓦片重产)** | 样张批 Q1 丙案语义 =「样张反向给素材重产提规格」;样张批明示「本批不重产任何正式素材」——**重产的产出义务全在本卡(若裁乙)**,样张的规格输入义务也在本卡上游对齐;若样张批先以占位板面冻结,本卡乙案重产后整屏样张的板面内容过期 | **v1.2 定实(2026-10-16 用户令)**:样张批已裁 **Q1 丙**(样张反提素材规格)/**Q3 乙**(引擎实拍+shader)——本卡乙案(远程生图重产)**若**在 T1 出口呈报后被裁,瓦片规格**必须与样张卡已冻结的目标规格清单对齐,先后次序=样张规格先行、本卡乙案在后**;甲案 recolor 换色不触样张主板(dungeon 拼板,C1 核注),对样张批零连带、不受该次序约束 |
| X3 | **徽章批「不动格底明度档、棋盘瓦片素材、图类型换皮四槽」红线(其 §4 不做条)** | 徽章批单向避撞本卡面;反向不成立——本卡改瓦片会动其微光绘制基面(其 F5:微光画在 CellUnit `_draw` 瓦片层上) | 本卡任何改图产物过 V5 时须同时跑徽章批既有断言面(若其已入库);串行序位已定实(徽章→样张→观感,排期栏)——徽章批先落,本卡 T1 报告按该序位复核 X1/X3 承接项,不再挂定序呈报 |
**结论笔**:两依赖均为**次序与规格联动**问题,不是范围冲突;2026-10-16 用户令已定案——串行序位徽章→样张→观感(排期栏)、Q3 已裁甲(同批)、Q2 甲/乙裁点挂 T1 出口呈报硬流程步骤(§6 T1/§10);本卡无悬空待裁点。
---
## 5. 关联文档同步面
> **v1.3 执行口径(2026-10-17 文档同步闸 v3)**:本批(代码实现批)**禁写 `design/` 整目录与根规则文件**,唯一可写目录 = `reports/`(`active.md` 唯一例外)。下表「同步义务」列一律执行为「列进 `reports/iter30-反哺点-<完成日>.md`:哪个文件哪一节、改成什么、依据,用户会话裁决后归文档批落文」——下表保留原关联点事实供写反哺点条目时对表。
| 文档 | 关联点 | 同步义务(v1.3 全部=反哺点列清单,另注者除外) |
|---|---|---|
| [06-待办清单](../design/gdd/06-待办清单.md) 本条 | 状态行改写(定性报告交付/完成注记);T1 发现的新红点若立新条则同批登记 | 反哺点 · 列清单待裁 |
| [08-Alpha版本标准](../design/gdd/08-Alpha版本标准.md) 「五 · 表现」棋盘观感行 | 待做→在役(完成定义第 4 件;批入库时改写并顺带 07 目检登记注;用户复判否决走 V4 回补——行回待做+06 记残留) | 反哺点 · 完成时列清单 |
| [art-bible](../design/art/art-bible.md) §4.1/§4.3(素材轴改色表值)或 §6.5/§7(UI 轴改常量方向) | 数值定值单点纪律:改值 = 走该节修订并登记(「待定现用」态),禁只改代码不改文档 | 反哺点 · 列清单待裁(条目写明改值与修订登记要求) |
| [HUD框架](../design/gdd/systems/表现与支撑/HUD框架.md) 视野迷雾节 | 仅当 T2 裁到迷雾灰显档参数时 | 反哺点 · 条件列清单 |
| [07-体验验证清单](../design/gdd/07-体验验证清单.md) | T4 登记实机目检条目(L1/L2/L3 并排看后问卷式回报) | 反哺点 · 列清单待裁(目检项另进 reports/ 实现报告目检总清单) |
| [roadmap](../roadmap.md) | 迭代 30 行已编入(2026-10-16 用户令,行已在案);余留义务=估时刷新(T5) | 反哺点 · 列清单待裁 |
| `active.md` 状态记录 | 本批条目进度刷新 | **本批更新(唯一例外 · 会话状态源)** |
| `tools/recolor_terrain_tiles.py` / `game/tests/golden/` | 甲案色表修订 = 脚本内定值换代;golden 基线三张重制 | 工程面 · 随修法落地(可写) |
| [playnote](../design/research/playnote.md) | 历史试玩记录不回改(沿革留档),本卡即其正式承接 | 无义务 |
---
## 6. 任务卡
> 估时按工作日口径;每卡出口自跑轻闸;批末重闸 = `tools/run_all_gates.sh` 按改动域选档(本批 → `--code`)全绿才合入(脚本即唯一闸清单,卡内不另列名单)。
### T1 定性步骤(人闸前置;含 T1b 新建采样件合计 ≈2–2.5d,**必先做,产出物 = 定性报告 + 对比样张**)
逐关(L1 参照位·注意含 10×10 与 12×12 两板型〔F1〕 / L2 / L3)三测面采样。**采样源按测面分治(v1.1 修正)**:
- 测面一(棋盘瓦片区)与测面三(迷雾遮罩部分)= `board_shot_probe` 实机渲染帧(确定性可复现,C6;过程帧 render_gate 即弃——本批帧自行留档于库外目录,读数表进 `reports/iter30-实现报告-<完成日>.md`);**禁拿素材文件代替渲染帧**(迷雾遮罩/揭示态只在渲染帧里存在);
- 测面二(舞台底与屏根)= **现有探针拿不到**(board_shot_probe 帧内无舞台底/屏根像素;shot_probe 战斗屏只到 L1 首战)⇒ 由 **T1b 新建采样件**补齐,见下;退而求其次可用 UiKit 常量×帧内实测值合成 WCAG 对(可算,但板缘对比带需几何语境,合成判据只能佐证不能实证);
- 测面三中的类型微光贡献 = 读数源仅样张 v2 静态定稿图(引擎未实装,F10),T1 报告如实标注该测面的证据级别。
输出读数表:
| 测面 | 指标(全部数值化,禁裸形容词) |
|---|---|
| 棋盘瓦片区 | 整板明度直方图 p10/p50/p90;A6 同口径**明度梯度均值**(相邻格/相邻像素亮度差——高频能量);唯一色数与色域跨度 |
| 舞台底与屏根 | `STAGE_BG`/`BG_ROOT` 对棋盘墙顶、米白装饰族的两两 **WCAG 对比对**;三档带序(shot_checker C 断言口径的层带思想,按帧实测复算——其现行取样面是 L1 战斗屏,不直接复用)实测值——**取样依赖 T1b 全框帧** |
| 叠加层 | 迷雾**全黑档面积占比**(区外未开格 = 不透明纯黑)与记忆档灰显值;色牌占板面像素占比;微光带宽与泛光 α 的观感贡献(**证据级别=样张 v2 静态图,引擎未实装——F10**;若徽章批同迭代先行实装则可升级为帧内实测,见 §4B) |
**T1b 新建采样件(批内任务,≈0.5–1d;v1.1 补——v1.0 默认现成件够用,实查不成立)**:给测面二供帧、并承载 **L2/L3 分关读数**(直方图/A6 同口径梯度按关出值——样张 v3 断言现只跑主板,C1 核注)。落点取一(白名单 1 域内):① 扩 `board_shot_probe` 加全框模式(BoardView 挂进 battle_stage_view/屏根底之上出 L2/L3 全框帧,与既有三张 golden 取样帧互不污染);② 新建 L2/L3 战斗整屏取证探针(shot_probe 真实路径口径只达 L1 首战,扩关需确定性到达方案)。出口判据:帧面含棋盘+舞台底+屏根三层且逐跑可复现。
**归因判据(写死在报告模板里)**:
- 素材轴信号 = L2/L3 板区读数与 L1 参照位在 明度带(对照 §4.1 档)/ 梯度均值 / 色域 上的偏离为主因(例:crater `P_DEEP (5,5,9)` 近纯黑叠加迷雾纯黑 ⇒ 大面积死黑;亮部墙顶跨度过大 ⇒ 闪烁感;「纹理太碎」假说在案最强证据 = 2026-10-14 美术审计结论条「第二 / 三关地面是近黑斑加亮筋的双峰纹理——数字无论亮墨还是垫牌,盯久了都会累。这不是再叠一层界面能救的」〔`design/art/美术审计-cursor会话存档-2026-10-14.md` 结论区〕);
- UI 轴信号 = 舞台底/叠加层贡献为主因(例:全黑面积占比 × 边缘对比产生的频闪感;`STAGE_BG` 对板缘对比带过宽);
- 两轴共因 = 两类偏离同时显著(报告须给出各自量级占比,修法按主次分配工作量)。
出口 = 定性报告 + **改前基准样张**提交用户,过 **T1 出口定性人闸**——06 已裁硬步骤(P1:「开工前先过『素材轴 / UI 轴』定性人闸」),闸上同时冻结轴归因结论与 §7 V2 定向目标带数值;v1.0 曾误把该闸本身列为待裁点 Q1,v1.1 撤销(禁再问已裁项)。
**T1 出口素材轴甲/乙裁决呈报点(v1.2 新增硬流程步骤——Q2 延裁所挂裁点的具名呈报动作,裁决留痕见 §10)**:
- **触发条件**:T1 归因结论产出即触发,随定性报告一并呈报(无论归因指向哪条轴,呈报不可省略);
- **动作**:开工默认先做**甲案(recolor 换色)候选样张**——按甲案试算槽值出改前/改后并排样张,用 T1b 分关读数证伪「纹理太碎」假说(甲样张读数达标而用户方向仍否决 = 指向乙);
- **产物与落点**:改前/改后并排样张 + 分关读数表(含甲案试算槽值清单)随定性报告呈报用户。**v1.4 预授权(2026-10-17 用户裁)**:甲案样张读数达标即按 §10 Q2 判据**自动走甲**、不停机等现场裁;仅当读数证伪「纹理太碎」假说时才呈报裁乙(呈报内容照旧:改前/改后并排样张+分关读数表)。结论按 §10 格式补记留痕后即成 T2 执行依据——裁点由该具名动作承载,全卡不留悬空待裁点。
### T2 修法(按轴分支;≈1.5–2.5d,落码前须过契约 4 对比样张人闸)
**素材轴——甲/乙裁点已由 2026-10-16 用户令定为「延至 T1 定性读数出具后再裁;开工默认先做甲案候选样张以证伪纹理说」(裁决留痕 §10;呈报硬流程步骤见 §6 T1 末)**:
| 案 | 产出物**相对现状新增什么** | 效果上限 | 成本与风险 |
|---|---|---|---|
| **甲 · recolor 程序换色重校** | 新色表(`PALETTES` 两族槽值修订:抬地面明度地板、压 crater 近黑与墙顶亮端跨度、家族间 Δ 重排)+ 改前/改后并排样张 + 基线换代。输入面(v1.1 实查):脚本只重映射 wall/facade/floor/crater 四族颜色的 `terrain_*_dungeon.png`→underdark/deep_underdark 两套,**L2/L3 板面瓦片 2×21 件全在其输入面内**;不在输入面的板面相关件=`flag_seal.png`(三关共用,若归因触它另行呈报) | 确定性、可复现、逐项可机检比对;**明度水平与色相可调,纹理高频结构逐像素保持**——若 T1 归因指向「亮度秩序/对比带」,本案直达;若指向「纹理本身太碎/太 busy」,本案调不动(方法学上限——脚本头注定死「亮度秩序逐像素保持」,高频结构不改;在案佐证=2026-10-14 美术审计「双峰纹理…不是再叠一层界面能救的」) | 低;零新素材;不破 §4.3 三关方向需在修订登记中说明偏转幅度 |
| **乙 · 瓦片重产(远程生图管线)** | 按新规格重出 L2/L3 瓦片([remote-gen-prompts](../design/art/remote-gen-prompts.md) 对话操作单 + [comfyui-prompts](../design/art/comfyui-prompts.md) 词库),纹理本体可重设计 | 上限高——高频细节/材质/装饰密度均可换;代价 = 非确定性、过闸周期长、需重锁色板与重跑 `terrain_tile_sets_test`+样张全套 | 高;与 08「五 · 表现」**待裁**行「素材升档重产」及 06「资产升档重产批」条(按名指路,08 未决项表行号以实查为准)方向相邻不同面——该批=立绘/小人帧尺寸升档(2026-10-04 用户令暂不做、重启=用户点名),本卡=棋盘瓦片色板/纹理方案重做,**裁本案不等于放开升档**,呈报须带划界;样张批 Q1 已裁丙案(样张反提素材规格,2026-10-16 用户令)——本案规格以其已冻结目标规格清单为上游,次序=样张规格先行(§4B X2) |
**T2 修法约束(v1.2 新增,承载 §4B X1/X2 已裁事实)**:①本卡改格底明度档与徽章批叠微光同基线(art-bible §4.1 格底档 L 0.08–0.14)——落码后两卡逐位比对 golden 棋盘三张防互踩;②串行序位徽章→样张→观感(排期栏),本卡落码在两批落码之后,基线换代走契约 6 显式流程;③若 T1 出口裁乙,瓦片规格与样张卡已冻结目标规格清单对齐,次序=样张规格先行(§4B X2);裁甲则对样张批零连带。
**UI 轴——参数重校(现读常量与候选方向,全部走样张人闸后定值)**:
- 迷雾全黑档:现值 = 不透明纯黑盖全部叠层(HUD框架/art-bible §6.5 三档信息阶梯的既有裁决,改它 = 改概念定义,须回 HUD框架 修订);候选方向 = 保持三档结构下调不透明度或对纯黑加主题 tint——**列为 T2 内二级裁点,报告须呈报不动定义的纯参数位有哪些先穷尽**;
- 舞台底:`STAGE_BG #3E342A` 对板缘对比带宽——候选 = 向 `BG_BRIGHT #453723` 方向提一档或收窄棋盘外缘留白;
- 色牌/微光占用:色牌垫底是 v3.4 定案(改板纹理高频结构才谈撤牌);**类型微光引擎未实装(F10),本卡对该层无可动参数——读数若显示微光规格(α170/带宽 cell÷8)贡献显著,处置=与未开格徽章批联裁实施参数或走 art-bible §4.2 修订登记,呈报为 L3 停机点(触既定裁决面),不在本卡单方改动**。
### T3 L2/L3 同批与否(≈0.25d 结论笔)
事实:两关色板两套槽值、板型 12×12 vs 13×13、数字墨同模式(§2.3)。两案成本对照(v1.1 中立化留档;v1.2 已裁,见下):**同批** = 一次基线换代、一轮目检登记,色表两套槽值各改各的、互不连带;**分两批** = golden 链换代两次、目检登记两轮,单批体量更小、L3 可在 L2 复判后单独叫停。**Q3 已裁(2026-10-16 用户令,§10):甲·同批**——理由=基线换代与目检各只走一轮;两关槽值差异由 T1 分关读数(T1b)承载,不需以拆批消化。
### T4 验收三件套与换代(≈1–1.5d)
1. 机检读数达标:见 §7 V2 判据表;
2. **渲染闸基线换代**:跑 `tools/golden_baseline_refresh.sh`(缺省模式=棋盘三张;触及菜单态加 `--menu`)显式重制基线,呈报换代面与新旧读数差、提交说明写明触发原因(契约 6 实操步骤);
3. 用户实机目检轮:目检项(玩法:L1/L2/L3 各开一局,并排回报「费劲感」相对改善)登记进 `reports/iter30-实现报告-<完成日>.md` 实机目检总清单——登记即完成本批义务、不阻塞入库(2026-10-12 用户令;「入册 07」列反哺点);用户复判否决走 V4 回补。方向级否决(样张层)已在契约 4 前置拦截,本步只剩终验。
### T5 产出物落位卡(≈0.5d,末卡——三份 reports/ 文件写齐才算收口)
轻闸全绿后、合并前,把本批三份 `reports/` 产出物写齐(权威文档与根规则文件零直改;`active.md` 状态记录照常更新):
1. `reports/iter30-实现报告-<完成日>.md`——各卡状态+**实机目检总清单**(T4-3 目检条目)+遗留读数义务+T1 定性报告读数表归档指引+变异验证记录表(新建断言/读数件的注入实验记录);
2. `reports/iter30-代拍板追认单-<完成日>.md`——§9 白名单内代拍板逐项留痕(含 Q2 甲/乙现场裁决的留痕补记);
3. `reports/iter30-反哺点-<完成日>.md`——§5 同步面每条一落点(哪个文件哪一节、改成什么、依据):06 本条状态行、08「五 · 表现」棋盘观感行(含 07 目检登记注与 V4 回补条款)、art-bible §4.1/§4.3 或 §6.5/§7 修订登记条(色值/常量若动)、HUD框架迷雾节(迷雾参数若动)、07 入册条、roadmap 估时刷新。
**原 §5 机械面直改义务零执行(v3 口径),落文归文档批。**
**估时合计 ≈ 5–7d**(v1.1 上调:T1 新增 T1b 采样件 0.5–1d;v1.0 为 4–6d——彼时漏了采样件,批内各卡加总实为 4.25–6.25d);**v1.2 估时不动**:Q2 延裁的甲案候选样张与契约 4/T2 样张同源产出,仅时点前移至 T1 出口呈报点,批内不新增总量;T1b 职责不变(全框帧+分关读数与甲/乙裁决无涉),不因本批裁决再调;天然切分点:**T1 末**(定性报告+甲/乙裁决呈报即交付物,人闸天然停点)、**T2+T3 末**(修法落地)。
---
## 7. 验证闸(逐需求点验收清单)
| # | 需求点 | 测什么 | 判据 |
|---|---|---|---|
| V1 | T1 定性报告 | 读数表覆盖 3 关 × 3 测面 × 各指标(§6 T1 表全列,测面二经 T1b 全框帧);L1 参照位在场(含两板型,F1);归因结论引用数值;**v1.2 增**:甲/乙裁决呈报件(甲案候选样张+分关读数表)随报告同出、用户当场裁决记录在案(§6 T1 呈报硬步骤) | 报告模板齐件 + 用户过闸记录在案(**T1 出口定性人闸=06 已裁硬步骤,P1**;**v1.4 预授权:人闸只确认轴归因与修法方向,V2 定向目标带数值由批内按 T1 实测读数自定并随定性报告呈报,禁拍脑袋现编**)+ 裁决留痕补记 §10 |
| V2 | 修法后机检达标 | **既有口径不破坏**:样张主板断言 A6 ≥4.70 / F6 Δ≥18 / A3b Δ≥30 / 格底明度档(已开 L 0.08–0.14 / 墙顶 ≥0.30 / 饱和 ≤0.55)保持绿(v1.1 注:该组现行只跑 dungeon 拼板主板,对 L2/L3 属「不动即可」约束而非覆盖,C1 核注);**L2/L3 分关实测 = T1b 新建读数件出值**;shot_checker A–D+F 零新增红;`terrain_tile_sets_test`/`ui_contrast_probe` 全绿。**定向判据**(针对「累眼」的归因侧):若 T1 判「死黑面积」→ 全黑档面积占比与明度直方图 p10 改善入目标带;若判「对比带过宽」→ 墙顶/地面 Δ 与板/舞台底对值入 T1 定标带——目标带数值由 T1 报告给出、**T1 出口定性人闸冻结**,禁拍脑袋现编。**目标带自设的合法性注(v1.1)**:art-bible §4.1「待定现用」态只管圣经在册数值(现行即执法、调整=修订登记,:207 释义);本卡自设目标带**首先只是批次验收判据**,过闸即合法生效于本批;若某带值要长期执法,须写入 art-bible 相应节修订登记转「待定现用」态,禁以批次判据身份直接成为执法值 | 读数表(改前/改后并排)进 `reports/iter30-实现报告-<完成日>.md`;**v1.4 预授权:目标带数值由批内按 T1 实测读数自定、随定性报告呈报即生效**(原「人闸冻结目标带」改为「人闸确认方向与量级」,数值仍禁拍脑袋现编) |
| V3 | 渲染闸换代 | 先跑 `render_gate.sh` 见棋盘 golden 段红(确认破的是预期面)→ 跑 `golden_baseline_refresh.sh`(缺省=棋盘三张,菜单态触及加 `--menu`;素材齐盘前置)→ 复跑 `render_gate.sh` 全绿;三张新旧基线并排呈报,changed 面 = 预期面,零超预期漂移 | 闸日志 + 呈报件;提交说明含触发原因(契约 6) |
| V4 | 用户实机目检 | 目检项登记(实现报告目检总清单;「入册 07」列反哺点)+ 用户回报「费劲感」相对改善且 L1 无退化——**登记不阻塞入库(2026-10-12 用户令)**;用户复判否决 = 回补机制触发:08 行回待做、06 本条记残留重开(落文按 v3 口径经反哺点归文档批)、返工起点=T1/T2 重议(不回滚已入库码面,按新条处置) | 主观判据的唯一权威=用户回报;入库前方向由契约 4 样张闸把关 |
| V5 | 邻接零回归 | 冒烟全套 + 单元 + 探针链零新增红(呈现面触碰加跑 ui_contrast);同迭代徽章批断言面零回归(§4B X3) | 重闸 = `tools/run_all_gates.sh --code`(脚本即唯一闸清单) |
| V6 | 反哺点清单 | §5 所列各条(08 行改写要求+目检登记注、06 状态刷新、art-bible 修订登记〔色值若动〕、HUD框架〔迷雾参数若动〕、07 入册、roadmap 估时)在 `reports/iter30-反哺点-<完成日>.md` 逐条有落点(文件/节/改成什么/依据) | 件核:§5 反哺点行数=清单条数 |
**闸口径**:机检(V2/V3/V5)自动判;V1 = 人闸停点(T1 出口定性闸,06 已裁);V4 = 登记后回补机制(非停点,2026-10-12 用户令);契约 5——机检绿 ≠ 用户满意,禁作等价表述写入 06/08。
---
## 8. 异常分级
- **L1(自救)**:采样脚本参数笔误、读数表排版缺件、文档行号漂移——立红即修。
- **L2(记录继续)**:色表具体槽值、候选样张的构图取舍、07 目检条目的问法措辞——批内消化并登记。
- **L3(停机呈报)**:①T1 读数显示 L1 同病(范围外溢,重划批次);②归因指向三态墨管线/迷雾概念定义本体(触既有裁决面);③用户否决对比样张方向两次以上(说明读数口径与体感脱节,须重议 T1 指标本身);④golden 重制后 changed 面超出预期(隐性回归);⑤色板增量纪律双门过不了且无合并方案;⑥跨卡同板面次序破裂——与徽章批/样张批的 §4B 联动被裁决成互相破坏已冻结断言面的顺序(§4B 呈报件被否即停,禁单方推进)。
---
## 9. 代拍板白名单(超清单必呈报)
1. 采样读数脚本的实现落点(新工具件 vs 扩 `shot_checker.py`,禁动其现有 A–D+F 断言语义)。**v1.1 注**:T1b 全框帧件(扩 board_shot_probe 或新建 L2/L3 整屏探针)即落在本条授权域内。
2. 明度直方图/梯度均值在「整板」与「灯光区内」两口径的取舍(以 T1 报告说明为准)。
3. 甲案色表的具体槽值设计(参数域内自由,出域即 L3)。
4. 对比样张的排版形式(并排同屏 vs 逐关两帧)。
5. 目检轮的注册话术与回报表格式(07 口径内)。
6. 基线重制的执行时机(T2 出口 vs T4 出口,取一)。
7. 提交切分与 worktree 分支命名(走既有纪律)。
---
## 10. 裁决留痕(v1.2 换代:原 Q1 撤销结论保留——已裁项禁再问;Q3 已裁甲·同批;Q2 延裁留痕;全卡零悬空待裁点)
**统一来源(逐条留痕均引此令)**:「2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)」。以下 Q2/Q3 各行引该令留痕;两案选项原文照录,供后续复看。
**已裁移除项(原 Q1「定性报告要不要用户过目才进 T2」)——撤销结论不动(2026-10-16 用户令未触及,维持 grilling 结论)**:06 本条条内已明文裁决——「开工前须先定性(沿用既有裁决)……**开工前先过『素材轴 / UI 轴』定性人闸**」(06:449/:453,2026-10-13 用户裁定条;08 版本历史 v0.3 同款注「P2 棋盘观感标『Alpha 阶段需完成 · 开工前过素材轴/UI 轴定性人闸』」)。「要不要过闸」不成立为问句,本卡处置 = 落为 T1 出口**流程硬步骤**(P1/V1),闸上同时冻结轴归因与 V2 目标带数值——**既裁人闸,不占裁点**。
### Q2 · 素材轴修法走哪案:程序换色重校(甲)还是瓦片重产(乙)?——**延裁留痕**
- **裁决(2026-10-16 用户令,来源句见本节顶)**:「待 T1 定性读数出来后再裁甲/乙;开工默认先做甲案(recolor 换色)候选样张以证伪纹理说」。
- **v1.4 预授权(2026-10-17 用户裁):延裁改判据自动裁,不再停机等现场裁**——甲案候选样张读数达标(进入 §7 V2 定向目标带)→ **直接走甲**;仅当读数**证伪**「纹理太碎」假说(甲样张读数不达标、方向仍不成立)时才呈报裁乙。乙案分支的代价与划界(P4/§6 乙案行:本卡重产 ≠ 放开升档、规格与样张卡已冻结目标规格清单对齐)全部不变。
- **延裁≠回避**:裁点挂到 T1 出口的**具名呈报动作**——硬流程步骤(触发条件/动作/产物)已成文于 §6 T1「素材轴甲/乙裁决呈报点」:产物=改前/改后并排样张+分关读数表,呈报后**用户当场裁**。本节不留悬空 Q。
- **判据(原文照录)**:判据 = T1 归因指向:亮度秩序/对比带问题 → 甲可直达;纹理本身太碎太 busy → 甲调不动(recolor 头注定死「亮度秩序逐像素保持」,方法学上限;碎纹理假说在案证据 = 2026-10-14 美术审计双峰纹理结论条),须乙。乙与 08/06「素材升档重产」的关系已划界(P4/§6 乙案行):本卡重产 ≠ 放开升档,裁乙不重开该未决项。
- **选项原文(保留)**:甲=recolor 换色重校(确定性、可复现、逐项可机检比对、零新素材;效果上限 = 参数域内明度/色相重排);乙=远程生图重产(可重设计纹理与高频细节,上限高;周期长、非确定性、全套闸重跑;若裁,规格与样张卡已冻结目标规格清单对齐、样张规格先行——§4B X2)。
- **换向处置**:呈报点甲样张被当场否决→裁乙,属裁决规则本身(即「证伪纹理说」动作的出口分岔),不计入 §8 L3③「否决两次以上重议 T1 指标」计数;裁乙即为批次正式进入 T2 乙案行执行。
### Q3 · L2 与 L3 同批修还是分两批?——**已裁·甲(同批)**
- **裁决(2026-10-16 用户令,来源句见本节顶)**:**甲·同批**。理由 = 基线换代与目检登记各只走一轮;两关槽值差异(两套色板槽值、12×12 vs 13×13)由 T1 分关读数(§2.3 分关设点 / T1b)承载,无需拆批消化。
- **事实(原文保留)**:两关色板两套槽值、板型 12×12 vs 13×13、数字墨同属双峰板色牌态;06 以单条覆盖两关。
- **选项原文(保留)**:甲=同批(一次基线换代、一轮目检登记,色表各改各的);乙=分两批先 L2 后 L3(单批更小、L3 可在 L2 复判后单独叫停;基线换代两次、目检登记两轮)。
**开工门(v1.2 定实)**:Q3 已裁甲·同批;Q2 裁点由 T1 出口呈报硬流程步骤承载(§6 T1)——开工门 = U0,用户 `/iter` 发令即开(已编入迭代 30,2026-10-16 用户令,排期栏);原「Q2/Q3 裁决落」前置表述不再成立。本卡全卡无悬空待裁点(§10 之外各处 Q 指涉均已改为裁决留痕/流程步骤引用)。
**U1 预授权(2026-10-17 用户于开工前一次性决断,防开发中反复打断)**:
1. **Q2 判据自动裁**——甲案候选样张读数达标即走甲,不停机等现场裁;仅读数证伪「纹理太碎」才呈报裁乙(§10 Q2、§6 T1 出口呈报点)。
2. **V2 定向目标带授权批内自定**——按 T1 实测读数定并随定性报告呈报;T1 出口定性人闸(06 已裁硬步骤,不可跳过)只确认轴归因与修法方向。
3. 其余 L3 停机点维持不变:触既有裁决面类(L1 同病外溢/迷雾概念定义本体/方向被否决两次以上/golden changed 超预期/色板双门/跨卡次序破裂)一律停机呈报。三卡串行序位不变(徽章→样张→观感),本卡位第 3。
---
## 11. grilling 审查记录(v1.0→v1.1,2026-10-16 对抗性审查;逐攻击面:结论/证据/处置)
| # | 攻击面 | 结论 | 证据(2026-10-16 实查) | v1.1 处置 |
|---|---|---|---|---|
| 1 | 工具实存性 | `board_shot_probe` **实存非臆名**(三关 targets 名/行号 :34 全对,且自带确定性驱动可复现);render_gate/golden_compare/shot_checker 能力与 C5 描述相符。**翻案**:board_shot_probe 帧 = 空视口裸挂 BoardView,**不含舞台底/屏根像素**(探针只实例化 BoardView,battle_stage_view/BG_ROOT 未挂载);shot_probe 战斗屏真实路径只达 **L1 首战**(其头注商店房不纳屏段自证)⇒ T1「舞台底与屏根」测面与「L2/L3 分关实测」均**无现成采样件**,v1.0「采样源=board_shot_probe 渲染帧」对该测面不成立 | `game/smoke/board_shot_probe.gd:34, :55-61`;`game/smoke/shot_probe.gd:12-14, :159-164`;`tools/render_gate.sh:9, :55-68, :95-107` | 新增 **T1b 新建采样件任务**(≈0.5–1d,白名单 1 域内);T1 估时上调、合计 4–6d→**5–7d**;C6 加帧面边界注 + 过程帧即弃纪律注 |
| 2 | 量化判据出处 | A6 ≥4.70(`:26/:338/:1021-1022`,v1 4.09×1.15)、F6 Δ≥18(`:339/:996`)、格底档 L 0.08–0.14/墙顶 ≥0.30/饱和 ≤0.55(art-bible :194/:205/:225-227)、48 色+三通道差 ≥8/255(art-bible :207)**全部实值相符**。**翻案两件**:①A3 现行执法 = **v3.5 冻结定值 Δ≥30**(实测 38),Δ≥55 已数学冲突退役(`:975-979`),v1.0 C3「开工时以当期为准复核」含糊化——已写死;②样张 v3 断言(A3/A6/F6)只跑 **dungeon 拼板主板**(`:130-131`),S3 underdark 仅为 HSV 示意不参断言——「分关实测」非现成能力。自设目标带合法性:「待定现用」态释义(:207)只覆盖**圣经在册数值**的执法态,不自动覆盖批次自设判据——二者不冲突但须写明边界 | 如上各行号 | C1–C3 加核注重写;V2 增「批次判据身份≠执法值,转执法须 art-bible 修订登记」条款;T1b 承载分关读数 |
| 3 | 「重产≠放开升档」划界 | 划界**成立但引据须换代**:08 未决项表 2026-10-16 v1.6 已重编号(八项减七项)——行号指路不可靠,按名「素材升档重产进不进 Alpha」「立绘清晰度回退评估」现行确在第 6/7 行(实查);06「资产升档重产批」现行状态 = 2026-10-04 令暂不做 + 2026-10-06 优先级再降 + **2026-10-06 方案二注记:原 64/96/128 升档路线已被八敌逐键定档实质走完,剩余挂起=提灯点亮解禁候选**——v1.0 P4「该条方向=帧尺寸升档」表述滞后 | 08:154, :209-210, v1.6 行(:226);06 升档批条状态行全文 | P4 重写(按名指路+行号注明以实查为准+方案二注记现状);T2 乙案行同改 |
| 4 | recolor 能力边界 | 头注方法=仅对 `terrain_*_dungeon.png` 按 wall/facade/floor/crater 四族槽重映射、输出 underdark/deep_underdark 两套;实盘 board/ 目录两套各 21 件(**墙 16+地 5**)与脚本输入面完全对齐,`flag_seal.png` 不在输入面。v1.0 F2「墙类 21 件」**件数错**(21 为总数,16 唯一墙名单单点 `TILE_WALL_NAMES`)。「纹理太碎调不动」有实证:recolor 头注定死亮度秩序逐像素保持(方法学上限)+ 2026-10-14 美术审计结论区「第二/三关地面=近黑斑加亮筋双峰纹理,盯久了累,不是再叠一层界面能救的」(该审计 md 在盘;同日另存 2026-10-06 旧审计 HTML,其棋盘相关结论未涉 L2L3 瓦片碎度) | `tools/recolor_terrain_tiles.py:1-12`;`game/presentation/views/board_view.gd:81-88`(16 件名数组+头注「16 唯一墙瓦片名单」);`design/art/美术审计-cursor会话存档-2026-10-14.md` 结论区;Glob `game/assets/art/board/` 两套件名清点 | F2 订正件数+flag_seal 例外注;甲案行写明输入面全覆盖;T1 归因判据与 Q2 引审计实证 |
| 5 | 文字位条分工句 | 06:451 原文在册:「两条不同面,不互相替代,各自保留」;三处文字位=站桩名行/敌顺位徽标/RAP 反馈行,06:443 已随迭代 26 T3 完成——v1.0 P2 语义与原文一致 | 06:451, :437-443 | P2 补原文引述 |
| 6 | V 条判具 | V2=样张 v3(主板)+T1b 分关读数+shot_checker A–D**+F**(v1.0 漏 F 判据,2026-10-15 已入闸)+`terrain_tile_sets_test`/`ui_contrast_probe`(两探针实存);V3=`golden_baseline_refresh.sh` **实存**且用法查明:缺省模式=棋盘三张(probe 抓帧→crop→覆盖 `game/tests/golden/`),`--menu`=菜单全屏,素材缺位拒跑,呈现批 agent 自换代+提交说明强制写触发原因(其头注 Q5/Q6/S3 在册) | `tools/golden_baseline_refresh.sh:2-14, :52-76`;`tools/shot_checker.py:8-19` | C5/契约 6/T4/V2/V3 补齐实操步骤与 F 断言 |
| 7 | Q1/Q3 已裁检索 | **Q1 属已裁项**:06:449 条内明文「开工前须先定性(沿用既有裁决)」+ 状态行「开工前先过定性人闸」(2026-10-13 用户裁定)+ 08 版本历史 v0.3 同款注——v1.0 一边在 P1 引该裁决、一边把同一闸列为 Q1 待裁,自相矛盾,触用户红线。Q3(同批与否)与 Q2(甲/乙)全库检索**无既裁**(06 单条覆盖两关但未裁批次数;playnote 无;git log 无)——保留为待裁 | 06:445-453;08:220(v0.3);playnote.md:5;git log 2026-10 检索 | Q1 从 §10 删除、改 P1/T1 出口/V1 流程硬步骤引用(§10 载明移除理由);Q2/Q3 保留 |
| 8 | 中立性 | v1.0 四处「推荐」:Q1(已裁项附裁决,撤销后消失)、T1 出口句(撤销)、T3「推荐=同批」与 §10 Q3「推荐 甲」(**无既裁依据→中立化**)、Q2 立场句「开工默认先做甲案候选样张」(改写为白名单内样张层探针动作,非路线裁决) | 全文 grep 推荐=0 残留(仅剩「已删字样」自述与列名注) | 列头改「卡片立场(不代裁)」;§10/§6 T3 中立化 |
| 9 | 跨卡依赖 | 两卡同抢 L2/L3 板面:徽章批(类型微光实装者,其 T0-② 五组明度档以未开格底 L≥0.30 为基线——本卡改的正是该基线;art-bible :379 已册「格底与微光同在未开格面,邻近色相有吞没风险」互辨复测义务;其 §4「不动格底/瓦片/四槽」系单向避撞);样张批(Q1 丙案语义=样张反提素材规格、Q3 路线选型——本卡乙案重产与其冻结次序互锁) | `徽章卡(迭代 30 卡①,合并 7ffd1dc0,卡片已退役):13/82/109`;`需求卡片-战斗一屏样张批:33/59/70-71/168/170`;art-bible:379 | 新增 **§4B 跨卡依赖**(X1/X2/X3 三行+结论笔:次序与规格联动问题,不新增裁点,随 Q2/Q3 呈报交用户定序);§8 L3 增⑥跨卡次序破裂停机型 |
| 10 | 外加翻案(非清单内,敌意自查所得) | **契约 5/完成定义 3/V4/T5「目检未过禁宣布完成/在役」与 2026-10-12 用户令红线冲突**:AGENTS.md「真人检测只登记不阻塞——禁以等目检为停工理由」(入库先例:迭代 25/26/28 均入库翻行、07 目检留残,git 提交 d337c9e5 立规)。另:F1「L1 10×10」不全——`board_gen.tres` level_index 1 段含一行 **12×12 dungeon**;F10/C6:类型微光引擎未实装(徽章批 F2 引 HUD框架实装状态行佐证),v1.0 把它当实机可测层不成立 | AGENTS.md:68;git log d337c9e5;roadmap 迭代 25/28 行「残留人闸=目检」先例;`game/data/tables/board_gen.tres` 行段实查 | 契约 5 重写(阻塞闸全前置:T1 定性闸+契约 4;V4 改登记不阻塞+回补机制:否决→08 行回待做+06 记残留重开);F1 补两板型注;F10/T1 微光测面降为样张 v2 证据级别并注升级路径 |
**词面合规自查**:v1.1 全部新增/改写文本已按仓库现行用语规范禁词表逐词 grep 复扫,命中 0(他文档引文原貌除外);本次修订同时把卡片里 v1.0 残留的两处旧措辞换代为规范词。**v1.2 增补**:本次裁决留痕新增/改写文本同口径 grep 复扫,禁词命中 0。**v1.2 留档注**:下表 §11 中「Q2/Q3 保留待裁」「随 Q2/Q3 呈报交用户定序」「无既裁→中立化」均为 v1.1 时点的审查动作实录,不作现行状态读——2026-10-16 用户令已定案(Q3=甲·同批;Q2=延裁挂 T1 出口呈报硬步骤),现行裁决状态一律以 §10 为准。
@@ -0,0 +1,330 @@
# 需求卡片:代码术语刷新批(flag→seal+中文禁用词清扫)
- 版本:**v1.4**(2026-10-18 卡片正确性复核批:§2 现状事实的命中数改为**可复现实测读数**——v1.x 沿用审计报告的计数在现行代码上无法复现,且总量低估约一倍、文件数少记 24 个;历史:v1.3 冲突修订批、v1.2 grilling Q4–Q8、v1.1 Q1–Q3)
- 来源:
- [06-待办清单](../design/gdd/06-待办清单.md)「代码术语刷新批——禁用词全库清扫+flag→seal 标识符重命名」(2026-10-18 登记,工程直入)
- 用户裁定(2026-10-18,记忆 `project-terminology-rulings-20261018.md`)
- 审计报告:[代码术语审计报告-2026-10-18](../design/research/代码术语审计报告-2026-10-18.md)
- 归属:全工程(排雷循环/战斗循环/冒险循环/呈现层/数据表/冒烟测试);术语权威=[术语表](../design/gdd/术语表.md)
- 排期:**已编入 roadmap 迭代 31**(2026-10-18 用户确认;卡片状态=已编入,开工门=U0)
- **设计前置声明**:本卡属**重构/工程债**类,凭 2026-10-18 用户裁定与审计报告代码级证据直接写卡,跳过设计轨。
- **设计事实源**(req-card §2 三选一之③工程直入证据指认,2026-10-18 立规;v1.3 补声明):[代码术语审计报告-2026-10-18](../design/research/代码术语审计报告-2026-10-18.md)(已入库 HEAD)逐条 file:line + 06 条目「代码术语刷新批——禁用词全库清扫+flag→seal 标识符重命名(设计面=工程直入)」现状段。两处读数一致:`game/` 命中约 757 处(flag_ 270 处/29 个 .gd + 22 处 .tres;金币 116/插旗 210/雷格 109)。
## 1. 目标与完成定义
| 需求点 | 一句话 |
|---|---|
| **N1** | 代码标识符 flag_* 全族重命名为 seal_*(变量名、函数名、字典键、事件名、数据表字段、字符串值) |
| **N2** | .gd 注释与 UI 字符串中中文禁用词清扫:金币→GP、插旗→封印、雷格→危险格、惩罚格→危险格、旗(游戏概念)→封印印记 |
| **N3** | .tres 数据文件中中文禁用词清扫(display_name、desc、注释) |
| **N4** | game/README.md 同步 |
**完成定义**:game/ 目录内全局搜索 `flag`(排除非游戏语境如 git flag)零命中;全局搜索「金币」「插旗」「雷格」「惩罚格」零命中(术语表对照行不在本卡范围);全量冒烟(smoke_all.gd)+单元测试(tests/run_all.gd)全绿,绿数与改前基线一致;`reports/` 三份产出物写齐(实现报告/代拍板追认单/反哺点清单)。
**文档面不在本卡完成定义内**(2026-10-17 req-card §6 改口径:代码实现批禁写 `design/` 整目录与根规则文件,唯一可写目录=`reports/`)——06 条目状态推进、术语表、entities.yaml、07 目检项一律列进 `reports/iter31-反哺点-<日期>.md`,由用户在会话中裁决后归文档批落文。
## 2. 现状事实(2026-10-18 代码级实查)
### N1 · flag_* 标识符分布
**总量(v1.4 实测,2026-10-18,口径见下)**:`game/` 内含 `flag` 的文件 **57 个**(.gd 53 个 595 处 + .tres 4 个 22 处,合计 617 处);剔除假阳性 `size_flags_*` 70 处(19 个文件)与 `_fatal_flag` 4 处(1 个文件)后,**净待改 543 处、42 个文件**。
复现命令(在 `game/` 目录):`grep -ro 'flag' --include=*.gd --include=*.tres . | wc -l`(总处数);净处数=逐文件 `grep -o 'flag'` 减 `grep -o 'size_flags[a-z_]*'` 减 `grep -o '_fatal_flag'` 再求和。
> **v1.x 读数不可复现的订正说明**:原记载「~314 处(270 处 .gd + 22 处 .tres + 22 独立 flag 词)/29 个 .gd 文件」来自审计报告,其计数口径(疑为 `flag_` 前缀且不含注释内英文词)在现行代码上两种口径都对不上——单文件抽样:`minesweeper_rules.gd` 原记 18、`flag_` 前缀口径 18、`flag` 全口径 59;`smoke_all.gd` 原记 105、两种口径分别 136/157。**低估面约为实测的 1.9 倍,文件数少记 24 个**。§6 估时 ≈3.75d 是按旧读数定的,是否上调归编排段/用户(本卡不改估时)。完成判据不受影响——V1 本来就是「grep 零命中」,与计数无关。
**核心逻辑文件(v1.4 实测:净命中=`flag` 处数 − `size_flags_*` − `_fatal_flag`;降序,2026-10-18)**:
| 文件 | 净命中 | 关键标识符 |
|---|---|---|
| smoke/smoke_all.gd | 156 | flag_place, flag_hit, flag_miss, flag_placed, _flag_consumed + 注释断言文本 |
| core/minesweeper_rules.gd | 59 | flag_place, has_flag, flag_range_free, _flag_miss_seen, was_flagged, dug_under_flag 载荷键(:300/:306/:313/:348) |
| smoke/ui_input_probe.gd | 40 | flag_place, flag_cell |
| core/settlement/grant_segment.gd | 38 | flag_hit, flag_miss, _flag_consumed, flag_settle, dug_under_flag(:30/:93) |
| core/battle_orchestrator.gd | 33 | flag_hit, flag_hit_premium, _flag_consumed |
| smoke/level_autoplay.gd | 30 | flag_placed, flag_hit, flag_miss |
| presentation/views/board_view.gd | 23 | tex_flag, has_flag, flag_cell |
| smoke/ui_click_probe.gd | 21 | **_flags_placed**(:22 声明+:263/:279/:287/:309/:330 等清空点)——v1.3 的 T5.4 只记了「注释插旗 3 处」,漏了 18 处标识符 |
| data/tables/feats.tres | 15 | "flag_hit"(on 触发), "echo_flags", "smith_flags", "flag_burst"(feat_id), "dug_under_flag"(fact) |
| core/effect_engine.gd | 15 | `EVENTS` 含 flag_hit(:13)、flag_missed(:15);`MINE_EVENTS` 含 flag_hit、flag_settle(:20);**`FACTS` 含 flags_count(:51)与 dug_under_flag(:52)**——v1.3 的 T3.1 漏了 FACTS 两键;天赋树合成行 `{"on": "flag_missed"}`(:149、:152) |
| smoke/adventure_monte_carlo.gd | 14 | flag_placed, flag_hit, flag_miss(MC 输出键源) |
| smoke/auto_player.gd | 13 | flag_place 调用+注释「雷格」 |
| presentation/views/battle_end_overlay.gd | 11 | flag_hit, flag_miss 统计显示 |
**净命中 >0 的文件共 42 个**(其余 15 个含 `flag` 的文件只有 `size_flags_*`/`_fatal_flag` 假阳性)。上表列 13 个,余 29 个净 1–8 处,其中 **v1.3 任务卡完全未列的 5 个**(v1.4 已补进 T5.20–T5.24):`smoke/screen_flow_probe.gd` 8(`_screen_flags`/`_flags_text`/`_expect_adventure_flag`)、`tests/unit/core/effect_words_t1_test.gd` 2(**断言 `FACTS.has("dug_under_flag")`——不改必红**)、`smoke/ui_probe.gd` 2、`smoke/type_glow_shot_probe.gd` 2(`kind == "flag"`/`op = "flag_place"`)、`smoke/fx_probe.gd` 2(`flag_dots` 键)。
**数据表字段(.tres 键名,改动必须与 schema .gd 同步)**:
| 文件 | 字段 | 改后 |
|---|---|---|
| action_economy.tres:9 | `flag_place_ap_cost = 1` | `seal_place_ap_cost = 1` |
| settlement.tres:9 | `flag_hit_premium = 125` | `seal_hit_premium = 125` |
| settlement.tres:13 | `"flag_hit": "标中旗"` | `"seal_hit": "封印命中"` |
| settlement.tres:18 | `"flag_miss": "标旗未中"` | `"seal_miss": "封印未中"` |
| feats.tres:257,305,320,328,352,806,844 | `"on": "flag_hit"` | `"on": "seal_hit"` |
| feats.tres:260,269,285,292 | `"echo_flags"` | `"echo_seals"` |
| feats.tres:323,332 | `"smith_flags"` | `"smith_seals"` |
| feats.tres:838 | `"feat_id": "flag_burst"` | `"feat_id": "seal_burst"` |
| feats.tres:615 | `"fact": "dug_under_flag"` | `"fact": "dug_under_seal"` |
| treasure_items.tres:223 | `"flag_range_free"` | `"seal_range_free"` |
**Schema 校验文件(.gd 中读 .tres 键名的代码)**:
| 文件 | 涉及 |
|---|---|
| data/schemas/action_economy_table.gd | 读 flag_place_ap_cost(4 处) |
| data/schemas/settlement_table.gd | 读 flag_hit_premium(3 处) |
| data/schemas/treasure_item_table.gd | 读 flag_range_free(3 处) |
| core/action_economy.gd | "flag_place" 事件名(2 处) |
| core/config_db_cross_validator.gd | required_sources 含 "flag_hit", "flag_miss"(2 处) |
**Godot 信号声明(API 契约,连接方必须同名)**:
| 文件 | 声明/连接 | 改后 |
|---|---|---|
| core/minesweeper_rules.gd:9 | `signal flag_judged(evt: Dictionary)` | `signal seal_judged(evt: Dictionary)` |
| core/battle_orchestrator.gd:287 | `minesweeper.flag_judged.connect(_on_flag_judged)` | `minesweeper.seal_judged.connect(_on_seal_judged)` |
**已知假阳性(显式排除,不改)**:
| 文件 | 标识符 | 原因 |
|---|---|---|
| **`game/` 内 19 个 .gd 文件全体**(v1.4 订正:v1.3 只写了 ui_assembler.gd 一个,漏 18 个) | `size_flags_*`(含 `size_flags_vertical`/`size_flags_horizontal`/`size_flags_stretch_ratio`,共 70 处) | Godot 引擎 Control 内置属性与布局写法,禁改 |
| core/config_db.gd | `_fatal_flag`(4 处) | 无关变量(致命错误标记),禁改 |
| presentation/views/ui_assembler.gd:203 | 注释里的「min/flags」字样 1 处 | **不是豁免项,须改写注释**(v1.4 订正)——V1 判据是「grep `flag` 零命中减两类假阳性」,这处注释既非 `size_flags_*` 也非 `_fatal_flag`,不改写则 V1 永远红一项。改法:把「0=不设 min/flags」写成「0=不设最小宽度」 |
**存档影响面(Alpha 阶段可接受作废,不做迁移)**:
| 持久化路径 | 涉及键 | 影响 |
|---|---|---|
| save.json → breakpoint.adventure_counters | `"echo_flags"`, `"smith_flags"` | 旧档计数器失效,Alpha 阶段可接受(2026-10-18 用户裁定) |
### N2 · 中文禁用词分布(v1.4 实测,`game/` 内 .gd+.tres,2026-10-18)
| 禁用词 | 实测处数/行数/文件数 | 主要落点(实测 top 3 文件) |
|---|---|---|
| 金币 | 39 / 36 / 16 | smoke_all 10、shop_overlay_view 5、camp_shop_presenter 3(+battle_narrator 2、curio_pick_overlay 2、legend_overlay 1 等 UI 字符串) |
| 插旗 | 62 / 60 / 23 | smoke_all 14、grant_segment 6、**tests/unit/core/minesweeper_rules_test.gd 4**(v1.3 误记为 minesweeper_rules.gd 4) |
| 雷格 | 75 / 70 / 19 | smoke_all 31、battle_orchestrator 11、minesweeper_rules 5(+grant_segment、board_generator、测试断言文本) |
| 惩罚格 | 1 / 1 / 1 | treasure_items.gd 注释(v1.3 记 ~2 处,实为 1) |
| 旗(含复合词) | **376 / 285 / 50** | 内已含 插旗 62、标中旗 21、标旗 20;其余为注释里的「旗格/旗判定/旗溢价/旧板旗/无旗/拔旗/旗经济」等散句,v1.3 记 ~15 处严重低估——但落点几乎全是注释与断言描述文本,按 §9 代拍板白名单第 1、3 条语义等价改写即可,不需逐条请示 |
### N3 · .tres 中文禁用词
| 文件 | 命中 |
|---|---|
| reward.tres:188 | `"display_name": "金币袋"` |
| reward.tres 注释 | 金币袋、雷格(~5 处) |
| feats.tres:10-11 | 注释含「插旗=封印」「禁『雷/插旗』字面」 |
| treasure_items.tres:212 | `"desc": "插旗不限相邻(可对任何未开格插旗)"` |
| settlement.tres:13,18 | `"标中旗"` / `"标旗未中"` |
| action_economy.tres:18 | 注释含「雷格」 |
| status_effects.tres:96 | 注释含「雷格」 |
### N4 · game/README.md
雷格 8 处、插旗 1 处,均为架构说明注释。
### 关联面(本卡不动)
- design/ 目录文档面(另批委派处理)
- tools/*.py 中的「雷格」(analyze_playtest.py 1 处、render_sample_sheet*.py 6 处)——归文档批或工具批
- sim-data/analyze.py(1 处雷格)——同上
- 术语表自身修正——归文档批
## 3. 设计契约(红线,违反=L3 停机呈报)
- 🔴 **游戏行为零变化**:本批是纯重命名/文本替换,禁止改动任何游戏逻辑、数值、权重、条件判断。改前改后同种子冒烟读数必须逐位一致。
- 🔴 **.tres 键名与 schema .gd 必须同批同步**:改 settlement.tres 的 `flag_hit_premium` 必须同批改 settlement_table.gd 里读它的代码,否则数据加载失败。
- 🔴 **事件名字符串全链一致**:`"flag_hit"` 作为事件名贯穿 effect_engine.gd EVENTS 常量 → grant_segment.gd 发射 → feats.tres `"on"` 触发 → config_db_cross_validator.gd 校验 → battle_log_view.gd 呈现。改一处必须全链同步。
- 🔴 **Godot 信号声明与连接同名**:`signal flag_judged`(minesweeper_rules.gd:9)→ `seal_judged`;连接方 `battle_orchestrator.gd:287` 的 `.connect(_on_flag_judged)` → `.connect(_on_seal_judged)`;回调函数名同步。
- 🔴 **冒烟断言文本同步**:smoke_all.gd 中 check() 的描述字符串含「雷格」「插旗」「金币」的,随批替换;断言逻辑(数值、条件)零改动。
- 🔴 **显式排除清单(假阳性)**:`size_flags_vertical` / `size_flags_horizontal` / `size_flags_stretch_ratio`(Godot 引擎 Control 属性,ui_assembler.gd)与 `_fatal_flag`(config_db.gd 无关变量)**不在重命名范围**,盲替换命中即 L3。
- 🔴 **本批不保证旧存档兼容**:`echo_flags` / `smith_flags` 等 counter_id 持久化在 save.json 的 `breakpoint.adventure_counters` 中,重命名后旧档该键失效。Alpha 阶段可接受存档作废,不做迁移逻辑(2026-10-18 用户裁定)。
- 🔴 **不改 design/ 目录**:实现批禁写 design/(process-conventions §3 第 13 条)。
- 🔴 **不改 tools/*.py**:工具脚本归文档批。
- 🔴 **FACTS 两键全链同步(v1.4 补,v1.3 完全漏列)**:`flags_count`→`seals_count` 三处落点(`core/effect_engine.gd:51` 词表、`core/battle_orchestrator.gd:180` 载荷、`core/settlement/grant_segment.gd:179` 发射);`dug_under_flag`→`dug_under_seal` 十一处落点(`effect_engine.gd:47/:52`、`minesweeper_rules.gd:300/:306/:313/:348`、`grant_segment.gd:30/:88/:93`、`data/tables/feats.tres:615`、`smoke/smoke_all.gd:1559/:1560`、`tests/unit/core/effect_words_t1_test.gd:18/:21`)。改词表不改消费者=运行期取不到事实值;改消费者不改词表=加载期四词表校验致命。两名现行代码零占用(实测 `seals_count`/`dug_under_seal` 各 0 命中),无重名风险。
- 🔴 **非游戏语境的 flag 不动**:如 `git flag`、编译标志等(实查 game/ 内无此情况,但作为纪律登记)。
- 🔴 **与卡② 的命名接续(2026-10-18 用户补裁,v1.3 新增)**:本卡合回后,卡②(凭证件裁削批)新写的标识符一律 `seal_` 族——其效果类型名 `forgive_flag_miss` 已由同日补裁换代为 **`forgive_seal_miss`**,事件订阅写 `on: "seal_missed"`。故本卡的 V1「`flag` 零命中」在迭代 31 出口仍成立,不需要为卡② 打排除补丁。本卡执行时 `flag_missed` 必须一并改名为 `seal_missed`(原 v1.2 映射表漏列,v1.3 补入 T3.1)。
## 4. 范围边界
**做**:
- game/ 目录内全部 .gd、.tres、.md 文件的 flag→seal 重命名与中文禁用词替换
- 替换后全量冒烟+单元测试验证
**不做(去向)**:
| 不做的 | 去向 |
|---|---|
| design/ 全部文档 | 文档批(用户委派另会话) |
| tools/*.py | 文档批或工具批 |
| sim-data/ | 同上 |
| 术语表自身修正 | 文档批 |
| 游戏逻辑/数值改动 | 禁止(本批纯重命名) |
| doc_term_audit.py 词表扩充与扫描域扩展 | 文档批(T5) |
## 5. 关联文档同步面
> **口径(v1.3,2026-10-17 起生效)**:本批禁写 `design/` 整目录与根规则文件,唯一可写目录=`reports/`。下表凡标「反哺点」者=把「哪个文件哪一节、改成什么、依据是什么」写进 `reports/iter31-反哺点-<日期>.md`,由用户裁决后归文档批落文;本批一律不落笔 `design/`。v1.2 及以前的「机械面随批」措辞作废。
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| [06-待办清单](../design/gdd/06-待办清单.md) | 「代码术语刷新批」条目状态推进为「已完成(迭代 31 卡①,合并 `<commit>`,2026-10-XX)」 | **反哺点**(`design/` 内,本批禁写):推进句写进 `reports/iter31-反哺点清单`,文档批落笔后本条清掉 |
| [术语表](../design/gdd/术语表.md) | flag→seal 重命名后,术语表「旗/控制」条目需同步改为「封印/控制」 | **反哺点**:文档批处理,本卡不改 design/ |
| [entities.yaml](../design/registry/entities.yaml) | 第 268 行「机制键与规则(flag_place/flag_rules/标中旗三向效果)全不变,纯呈现层命名」+source_label_map 键集标注「结构冻结」——代码批执行后此条款失效,需解冻并换代为 seal_* | **反哺点**:文档批需显式废止「结构冻结」条款、将 flag_* 契约键全部换代为 seal_*。窗口期(代码已改、registry 未改)可接受——registry 非运行时依赖(2026-10-18 grilling Q4 裁定) |
| game/README.md | 架构说明中雷格/插旗 | **本批直改**(文件在 `game/` 内,不属 `design/` 禁写面)——随批替换 |
| game/tests/evidence/parity/anchor.json | MC 输出基线含 ~600 处 flag_* 键(flag_hit/flag_hit_gain/flag_miss/flag_miss_penalty/flag_placed/flag_burst) | **本批直改**(在 `game/` 内):手动替换键名(行为零变化故不重跑 MC),替换后跑 parity 闸确认绿 |
| [07-体验验证清单](../design/gdd/07-体验验证清单.md) | UI 文本换代后目检项 | **反哺点**:登记「商店/图例/HUD 文本是否显示 GP/封印而非金币/插旗」目检项,文档批落 |
## 6. 任务卡
### T0 · 基线记录(≈10min)
1. 跑全量冒烟(smoke_all.gd),记录绿数基线。
2. 跑单元测试(tests/run_all.gd),记录套数与绿数。
3. 记录当前 game/ 内 `flag` 总命中数(grep 计数,作为改后零残留的对照)。
### T1 · .tres 数据文件重命名(≈0.5d)
先改数据层(被 .gd 读取的源头),再改 .gd 消费侧,避免中间态加载失败。
1. action_economy.tres:`flag_place_ap_cost` → `seal_place_ap_cost`;注释中「雷格」→「危险格」
2. settlement.tres:`flag_hit_premium` → `seal_hit_premium`;`"flag_hit": "标中旗"` → `"seal_hit": "封印命中"`;`"flag_miss": "标旗未中"` → `"seal_miss": "封印未中"`;注释中「雷格」→「危险格」
3. feats.tres:全部 `"on": "flag_hit"` → `"on": "seal_hit"`;`echo_flags` → `echo_seals`;`smith_flags` → `smith_seals`;`flag_burst` → `seal_burst`;`dug_under_flag` → `dug_under_seal`;注释中「插旗」→「封印」
4. treasure_items.tres:`flag_range_free` → `seal_range_free`;desc「插旗不限相邻(可对任何未开格插旗)」→「封印不限相邻(可对任何未开格封印)」
5. reward.tres:`"display_name": "金币袋"` → `"display_name": "GP 袋"`;注释中「金币袋」「雷格」替换
6. status_effects.tres:注释中「雷格」→「危险格」
### T2 · Schema .gd 同步(≈0.25d)
与 T1 同批完成(.tres 键名改了,读它的 schema 必须同步):
1. action_economy_table.gd:flag_place_ap_cost → seal_place_ap_cost(4 处)
2. settlement_table.gd:flag_hit_premium → seal_hit_premium(3 处)
3. treasure_item_table.gd:flag_range_free → seal_range_free(3 处)
4. reward_table.gd:注释中「雷格」→「危险格」
### T3 · 核心逻辑 .gd 重命名(≈1d)
按依赖序改(底层→上层):
1. core/effect_engine.gd:EVENTS/MINE_EVENTS 常量 "flag_hit"→"seal_hit", "flag_settle"→"seal_settle", **"flag_missed"→"seal_missed"**;**FACTS 两键:"flags_count"→"seals_count"(:51)、"dug_under_flag"→"dug_under_seal"(:52)**(v1.4 补——v1.3 的 T3.1 漏了 FACTS,改了 .tres 的 fact 值而词表不放行=加载期校验致命);天赋树合成行 :149/:152 的 `{"on": "flag_missed"}` 同步改名;头注 :9 文本随批(净 15 处,以 V1 grep 零命中为准)
2. core/minesweeper_rules.gd:flag_place→seal_place, has_flag→has_seal, flag_range_free→seal_range_free, _flag_miss_seen→_seal_miss_seen(18 处)+注释中「插旗」「雷格」替换
3. core/action_economy.gd:"flag_place"→"seal_place"(2 处)
4. core/battle_orchestrator.gd:flag_hit→seal_hit, flag_hit_premium→seal_hit_premium, _flag_consumed→_seal_consumed(17 处)+注释替换
5. core/settlement/grant_segment.gd:flag_hit→seal_hit, flag_miss→seal_miss, _flag_consumed→_seal_consumed(23 处)+注释中「插旗」「雷格」替换
6. core/config_db_cross_validator.gd:required_sources 中 "flag_hit"→"seal_hit", "flag_miss"→"seal_miss"(2 处)+注释「雷格」
7. core/reward_economy.gd:注释「雷格」→「危险格」
8. core/board_generator.gd:注释「雷格」→「危险格」
9. core/treasure_items.gd:注释「插旗」「惩罚格」替换
### T4 · 呈现层 .gd 重命名+UI 字符串(≈0.5d)
1. presentation/views/board_view.gd:tex_flag→tex_seal, has_flag→has_seal, flag_cell→seal_cell(7 处)+注释
2. presentation/views/board_cell_unit.gd:tex_flag→tex_seal(2 处)+注释「插旗」「雷格」
3. presentation/views/shop_overlay_view.gd:UI 字符串「金币」→「GP」(5 处)
4. presentation/camp_shop_presenter.gd:「金币不足」→「GP 不足」(3 处)
5. presentation/curio_interact_controller.gd:「金币不足」→「GP 不足」(1 处)
6. presentation/battle_narrator.gd:「金币」→「GP」(2 处)
7. presentation/views/curio_pick_overlay.gd:「金币」→「GP」(2 处)
8. presentation/views/legend_overlay.gd:「金=金币」→「金=GP」;「右键插旗」→「右键封印」;「旗」→「封印印记」(3 处)
9. presentation/hud_presenter.gd:「不能插旗:此格已有旗」→「不能封印:此格已有封印印记」(1 处)
10. presentation/main.gd:「插旗后轮末自动判定标中」→「封印后轮末自动判定」(2 处)+注释
11. presentation/views/battle_log_view.gd:"flag_miss"→"seal_miss"(1 处)+注释「金币」
12. presentation/views/battle_end_overlay.gd:flag_hit/flag_miss 统计键(9 处)
13. presentation/views/ui_kit.gd:注释「金币」「插旗」「雷格」+TEX_ICON_COINBAG 注释
14. presentation/views/level_map_screen.gd:注释「金币」
15. presentation/views/board_fx_view.gd:flag 相关(1 处)
16. presentation/views/standee_body.gd:flag 相关(1 处)
17. presentation/row_pacer.gd:"flag_hit"→"seal_hit"(2 处)
18. presentation/views/status_slot_row.gd:flag 相关(1 处)
### T5 · 冒烟与测试 .gd 重命名(≈1d)
1. smoke/smoke_all.gd:105 处 flag_ 替换+注释/断言文本中「金币」「插旗」「雷格」替换(~50 处)
2. smoke/level_autoplay.gd:16 处 flag_ +注释「插旗」
3. smoke/ui_input_probe.gd:23 处 flag_ +注释「插旗」
4. smoke/ui_click_probe.gd:净 21 处——`_flags_placed` 声明(:22)+各清空点(:263/:279/:287/:309/:330 等)改名 `_seals_placed` +注释「插旗」3 处(v1.4 订正:v1.3 只记了注释,漏 18 处标识符)
5. smoke/adventure_monte_carlo.gd:5 处 flag_ +注释
6. smoke/auto_player.gd:注释「雷格」(4 处)
7. smoke/fx_shot_probe.gd:注释「插旗」(1 处)
8. smoke/board_shot_probe.gd:"flag_place"→"seal_place"(1 处)
9. smoke/ui_contrast_probe.gd:注释「金币」(1 处)
10. tests/unit/core/minesweeper_rules_test.gd:flag 相关(5 处)+「插旗」
11. tests/unit/core/board_generator_test.gd:「雷格」(1 处)
12. tests/unit/core/treasure_effects_test.gd:flag 相关(3 处)+「插旗」
13. tests/unit/core/feat_vouchers_test.gd:「金币」(1 处)
14. tests/unit/presentation/hud_presenter_test.gd:「插旗」(1 处)
15. tests/unit/presentation/reward_overlay_test.gd:「金币」(2 处)
16. tests/unit/core/tree_rules_v11_test.gd:flag 相关(2 处)
17. tests/unit/core/treasure_items_test.gd:flag 相关(1 处)
18. tests/run_all.gd:注释「插旗」(1 处)
19. tests/smoke/critical-paths.md:「雷格」「插旗」(2 处)
20. **smoke/screen_flow_probe.gd:净 8 处(v1.4 补列,v1.3 全漏)**——`_screen_flags()`(:50)、`_flags_text()`(:59)、`_expect_adventure_flag()`(:68)三函数改名 + 调用点(:75/:83/:91 等)。注意:本件是 L3 屏壳探针,受 `user://save.json` 断点污染的在册已知项,跑红先按该条排查再判归因
21. **tests/unit/core/effect_words_t1_test.gd:净 2 处(v1.4 补列)**——断言 `FACTS.has("dug_under_flag")`(:18)与描述文本(:21)须随 FACTS 词表改 `dug_under_seal`,**不改即红**(与 §3 FACTS 全链契约同批)
22. **smoke/ui_probe.gd:净 2 处(v1.4 补列)**——数据行里的 flag 族键/字符串(:179 附近),逐处改名
23. **smoke/type_glow_shot_probe.gd:净 2 处(v1.4 补列)**——`kind == "flag"`(:60)与 `op = "flag_place"`(:61)
24. **smoke/fx_probe.gd:净 2 处(v1.4 补列)**——`flag_dots` 键(:64/:65)须与发射端同名改
**余下 29 个净 1–8 处的文件不逐列**(净处数总和 543,V1 的 grep 零命中判据即兜网):施工期每轮以「净命中文件数递减、终态 42→0」为进度读数,发现卡片未列的落点属正常,按 §3 契约同步即可,不属卡片缺陷。
### T6 · game/README.md+anchor.json+全量验证(≈0.5d)
1. game/README.md:雷格(8 处)→危险格、插旗(1 处)→封印
2. game/tests/evidence/parity/anchor.json:手动替换全部 flag_* 键名为 seal_*(~600 处:flag_hit→seal_hit, flag_hit_gain→seal_hit_gain, flag_miss→seal_miss, flag_miss_penalty→seal_miss_penalty, flag_placed→seal_placed, flag_burst→seal_burst)
3. 全量冒烟+单元测试,绿数与 T0 基线一致
4. parity 闸跑通(anchor.json 键名替换后与 MC 新输出一致)
5. 全局搜索验证:game/ 内 `flag`(排除 size_flags_* 和 _fatal_flag)零命中;「金币」「插旗」「雷格」「惩罚格」零命中
6. **产出物落位卡**(req-card §7:末卡必含):`reports/` 三份写齐——`iter31-实现报告-<日期>.md`(含 V1–V7 读数+改前改后同种子读数对照+实机目检总清单)、`iter31-代拍板-<日期>.md`、`iter31-反哺点-<日期>.md`(§5 每条反哺点都要有落点:06 推进句/术语表/entities.yaml/07 目检项)。**禁改 `design/` 与 `roadmap.md`**
**估时合计 ≈3.75d**(v1.4 注:实测面约为 v1.3 旧读数的 1.9 倍(净 543 处/42 文件 vs 原记 ~314 处/29 文件),但落点高度集中在 `smoke_all.gd`(净 156 处=全集 29%),改动是机械替换+grep 兜网。**2026-10-18 用户裁:不上调**,估时保持 ≈3.75d;roadmap 迭代 31 行预计周期同步维持「≈1.5 周」不变)。
## 7. 验证闸(逐需求点验收清单)
**能力验证(自动化,随批)**:
- **V1(N1)**:改后全局 grep `flag` game/ 目录,排除 `size_flags_*` 和 `_fatal_flag` 后零命中。
- **V2(N1)**:全量冒烟绿数 == T0 基线(行为零变化证词)。
- **V3(N1)**:单元测试绿数 == T0 基线。
- **V4(N2/N3)**:改后全局 grep「金币」「插旗」「雷格」「惩罚格」game/ 目录零命中。
- **V5(N2)**:settlement.tres 的 source_class 显示名不含「旗」字(「封印命中」「封印未中」)。
- **V6(回归)**:同种子冒烟读数逐位一致(纯重命名不改行为的最强证词)。
- **V7(parity)**:anchor.json 键名替换后 parity 闸绿(MC 输出与基线逐位一致)。
**正常流程体验(用户目检,登记 07 不阻塞)**:
1. 商店界面显示「GP」而非「金币」。
2. 图例/HUD 显示「封印」而非「插旗」「旗」。
3. 结算明细来源显示「封印命中」而非「标中旗」。
## 8. 异常分级
- **L1(自救)**:单个文件漏改导致 grep 验证未过——补改即修,不改批结构。
- **L2(记录继续)**:冒烟绿数与基线偏差 ≤2(断言文本替换引起的描述性变化,非逻辑变化)——记录偏差原因,确认非逻辑回归后继续。
- **L3(停机呈报)**:冒烟绿数下降 >2 或出现逻辑断言红(说明重命名触及了行为);.tres 加载失败(schema 不同步);同种子读数不一致(行为变化)。
## 9. 代拍板白名单(超清单必呈报)
1. 注释替换时的措辞微调(如「挖雷格」→「挖危险格」vs「挖掘危险格」)——语义等价即可,不必逐条请示。
2. seal_* 的具体拼写形态(如 `_seal_consumed` vs `_consumed_seals`)——与 flag_* 原形态保持同构即可。
3. 测试断言描述文本的替换措辞——语义等价即可。
4. settlement.tres 显示名「封印命中」「封印未中」的具体措辞——若用户有异议呈报。
## 10. 待裁点
**零待裁点,开工门=U0。** Q1–Q3 于 2026-10-18 用户令「按推荐来」全裁;Q4–Q8 于同日 grilling 复核后用户裁定落定:
| # | 裁定 | 落定结论 |
|---|---|---|
| Q1 | reward.tres display_name | **GP 袋**(金币袋→GP 袋) |
| Q2 | settlement.tres 显示名 | **封印命中 / 封印未中**(标中旗→封印命中、标旗未中→封印未中) |
| Q3 | feats.tres feat_id | **seal_burst**(flag_burst→seal_burst) |
| Q4 | 存档兼容 | **不做迁移,Alpha 阶段旧存档可作废**(echo_flags/smith_flags 计数器失效可接受) |
| Q5 | anchor.json 处理 | **手动替换键名**(行为零变化不重跑 MC),替换后跑 parity 闸确认绿 |
| Q6 | 假阳性排除 | **显式排除清单入红线**:size_flags_*(Godot 引擎属性)、_fatal_flag(config_db 无关变量) |
| Q7 | registry 契约窗口期 | **可接受**(registry 非运行时依赖;文档批紧随其后;entities.yaml「结构冻结」条款标注为反哺点,文档批需显式废止并换代) |
| Q8 | 信号声明补全 | **signal flag_judged → seal_judged 显式入映射表**(Godot 信号=API 契约,连接方必须同名) |
---
**卡片成立前置**:~~grilling 复核门~~(2026-10-18 已过,Q4–Q8 全裁)+~~用户卡审~~(2026-10-18 已过,用户确认编入迭代 31)。
@@ -0,0 +1,99 @@
# 需求卡片:冒险前资源配比预设批(迭代 14 ⑥号卡)
> 日期:2026-10-04
> 性质:实施批需求卡片(零拍板点——八裁全落,本批只做实现;provisional 数值随出口人闸追认)
> 裁决事实源:[提案-冒险前资源配比预设-2026-10-04](../design/research/提案-冒险前资源配比预设-2026-10-04.md)(已退役存档,2026-10-18 用户令入库——只作推导与淘汰依据的历史档;裁决结论已录 [06-待办清单](../design/gdd/06-待办清单.md)「冒险前资源配比预设(构筑提案)」条)§八备选全列 + §九立项五裁 + §十盘问四裁与自答六件(**唯一裁决源,本需求卡片不复述推导、只引用结论**)
> 排位:roadmap 迭代 14 ⑥号卡(2026-10-04 用户令编入);06-待办清单「冒险前资源配比预设(构筑提案)」条(已裁待实施)
> **开工门 = ②号卡(判式换代)与③号卡(全局变异首发)出口已合并进 master**——理由见 §三
> 估时:T0-T8 ≈ **6.0 日**(两段切分预案见 §十)
> **⚠ 已冻结挂起(2026-10-05 用户令)**:本批移出 roadmap 迭代 14(⑥号卡撤销)——暂不实施,需求卡片冻结保留;06-待办清单同条目转挂起。重启须用户另行发令;届时按届时 master 态重校 §三开工门(②判式换代与③全局变异若已入库则自动解)。
---
## 一、批任务一句话
玩家在**开始冒险前**预设格面九型资源的类型分布(预设分布、不预设落位——装板摇号仍定落位),配比经差值向量在摇号前注入权重合成层;容量(可调型/包络宽度/预设档)走营地奖励格图鉴柜台逐型解锁。机制件 + 构筑界面(程序占位)+ 柜台商品 + 存档 v6 + 验收闸一批交付。
## 二、裁决基座速览(全文见提案 §九§十)
| # | 裁决 | 结论一行 |
|---|---|---|
| P1 | 预算机制 | 组合制:总量挪点(九型正向权重总和恒 77,ΣΔ=0)+ 每型上下限包络 + 容量解锁渐进;gp 首发不可调〔包络 (2,2)〕/预设档 3 套/下限 >0 |
| P2 | 主权与验收 | 设计者定包络与默认、玩家包络内分配;验收 = 默认分布锚(现行四带权威读数不动)+ 极端构筑护栏带 |
| P3 | 容量柜台 | 奖励格图鉴承接,**逐型商品**(每型可调权一件、玩家自选解锁顺序) |
| P4 | 注入语义 | 差值向量(存相对默认偏移 ΣΔ=0;集合操作只保留在解锁层——可调型集扩容用追加语义) |
| P5 | 渠道边界 | 清图槽差异化先行 + 三句不混池口径随批入文(板图分工/配比域封闭/格型无差) |
| Q1 | 合成序 | 表值 → 玩家配比差值 → 包络钳制 → 图级变异偏斜(③号卡产物)→ 同调硬币偏置;**包络只管玩家差值**,设计者侧两投影后叠互不钳 |
| Q3 | 换档时点 | 冒险开始选档、中途锁死(关间换档后置评估,本批不做) |
| Q4 | 包络分级 | 包络宽度随容量分级放宽(只放宽不收窄,存档差值零迁移) |
## 三、序位与开工门
- **开工门 = ②③号卡出口**。理由两条:① Q1 合成序的插入位 = ③号卡扩参后的同一摇号投影点(`reward_economy._biased_cell_rows()` 一带,偏运硬币先例)——②③先行入库使本批只做一次合成层改造,不做二次返工;② 包络数值的定值锚 = ②号新判式当量账(提案 §十自答①)——不在旧账上投值。
- 出口读数与②③**分开归因**(roadmap 在册口径);本批 MC off 态对拍锚以②③入库后的现行锚为基线。
## 四、红线(批内零触碰面)
1. **结构冻结四件零 diff**:危险格与安全格同池(同池同分布——配比是整体平移,安全格与危险格仍同一分布)/ 九型封闭枚举 / 装板期一次摇定无重摇 / 负向恒即时无库存。配比只动正向池权重的合成,冻结面零触碰。
2. **确定性契约**:`reward_roll` 专属随机流取号次数只随非封锁格数、不随权重;**off 态(全零差值 + 无解锁)逐位等于现行结果**——本批第一断言。
3. **结算零改**:DamageController、兑付编排、极性矩阵、percent 行效果引用零 diff;配比不改任何单次兑付的语义,只改触发频率。
4. **流程红线**:worktree 铁律(`../g-plan2-a4ratio-<日期>`);主区在飞脏文件不碰不代提交;两入口铁规(冒烟挂批末闸,短会话零测试)。
## 五、任务卡
### T0 开工三查 + 基线锚确认(0.25d)
查前序出口(②③号卡已入库(master log 与 06 状态吻合));查主区脏文件(在飞件标旗不碰);查 ②③ 入库后的现行 MC off 对拍锚(本批 off 对拍权威锚,只测不判口径沿用)。**出**:开工闸记录。
### T1 配比参数表 schema + registry + provisional 投值(0.5d)
新建 `ratio_preset_table`(配比参数表,`data/tables/`):每容量档一行(可调型集合 / 每型包络 [下限,上限] / 预设档位数);九型默认分布引用(=现行 `reward.tres` 正向行权重,**不复制值、引用表**);gp 白名单行(包络 (2,2) 恒定,不上柜台)。数值全部 provisional:包络按②号新判式当量账复算起步(pierce/magic 代价轴最贵 → 包络上界收紧方向),下限统一 2 起步,容量三档排布(一档 2 型可调+窄包络 → 二档 5 型+中包络 → 三档 8 型+全包络,具体归 T7 读数后调)。registry 新条目 + save_file 域登记(配比三档 + 逐型解锁位 + 容量档 + 上次使用档)。**验收**:加载校验(词表成员/包络下限>0/ΣΔ=0 格式校验)通过;白板存档(无解锁无配比)逐位等于现行。
### T2 摇号前合成层扩参(1d)
`reward_economy` 合成层改多生产者单点:**表值 → 玩家配比差值 → 包络钳制(按当前容量档)→ 图级变异偏斜(③号卡投影,原样保留)→ 同调硬币偏置(原样保留)→ 加权抽取**。包络只钳玩家差值(Q1 甲);luck_bias=0 且 Δ=0 时逐位返回原行集(现行为)。**验收**:单元断言——off 零扰动逐位 / 钳制上下边界 / ΣΔ≠0 输入拒绝 / 包络放宽后老差值合法(Q4)/ 变异与硬币不受玩家包络钳制(Q1)/ 同种子同预设同身份表。
### T3 存档 v6(0.5d)
配比域入档:三预设档(各 = 九型 Δw 整数向量 + 命名)+ 逐型解锁位图 + 容量档 + 上次使用档引用。迁移幂等(v5 → v6 无配比域 = 全零向量 + 零解锁,白板成立)。**验收**:v5 存档升级后冒烟全绿 + off 态逐位;断点存取往返逐位。
### T4 图鉴柜台逐型商品(0.5d)
奖励格图鉴柜台改写「格面构筑」:八件可调权商品(八型各一件;gp 不上架)+ 容量档推进商品三件(或与可调权合并触发——按参数表排布行执行,二择一在 T1 定)。购买 = 钥石直购、几何递增定价(provisional)。柜台语义改写连带:原「特殊奖励格」悬置内容保持悬置(独立问题不销号,呈现「筹备中」态)。**验收**:未解锁型在构筑面不可编辑(灰态);解锁后差值可存;定价读表。
### T5 构筑界面程序占位(1.5d)
主菜单入口「配比预设」管理面:三档页签,每档 = 八可调型 +/− 步进(显示当前权重/默认权重/包络区间/剩余可挪池)、ΣΔ=0 实时校验(非法态禁存)、gp 行只读灰态;开始冒险时选档确认(默认 = 上次使用档;不选 = 默认分布)。冒险开始后锁档(Q3)。程序占位质量,视觉终稿归 HUD 协作批(与营地三柜台同路径,不设样张闸)。**验收**:ui_input_probe 新增构筑面用例(编辑/存档/选档/锁档四态);零差值编辑路径不触碰任何摇号(off 纪律)。
### T6 注入通道(0.25d)
`start_adventure` params 扩 `ratio_delta`(九型 Δ 向量)+ 档引用;LevelRunner 透传至战斗初始化(偏运硬币 luck_bias 同路先例)。**验收**:参数面字段与元进度「属性=数值覆盖、池=集合操作」分工注记一致(配比差值 = 数值域新生产者);off 态逐位。
### T7 验收闸(1d)
冒烟断言批:off 逐位 / 钳制边界 / 锁档 / 解锁门控 / 柜台满购 / ΣΔ 校验拒非法。MC:off 态与 T0 锚逐位对拍;on 态极端构筑代表组(最大化直伤 / 最大化续航 / 最大化经济三组 + 默认对照,N 按现行 MC 纪律二档)——**极端角与默认分布的带差 = 护栏带首批读数**(带值判定归出口人闸,本批只测不判)。行动经济对账按包络复算(总量恒 77,只余分布位移变量)。**停机点 S1**:极端角把现行带打穿且包络收窄不能救 → 停机呈报(见 §七)。
### T8 文档六现行事实源 + registry + 06 + 出口包(0.5d)
[地图战斗资源](../design/gdd/systems/战斗循环/地图战斗资源.md)(候选集合节:权重来源 = 表值 × 玩家覆盖合成,Q1 序落文;三句不混池口径入纪律表);[元进度](../design/gdd/systems/跨局循环/元进度.md)(图鉴柜台职责改写 + 容量商品 + 存档第五件);[冒险结构](../design/gdd/systems/冒险循环/冒险结构.md)(参数面字段);[难度曲线与Boss](../design/gdd/systems/冒险循环/难度曲线与Boss.md)(护栏带 + 包络 provisional 行);[HUD 框架](../design/gdd/systems/表现与支撑/HUD框架.md)(构筑界面槽位 + 视觉终稿后置登记);[行动经济](../design/gdd/systems/排雷循环/行动经济.md)(对账窗口注记)。registry 全条目。06 状态推进(已裁待实施 → 随批落地状态)。出口包 = 人工检查清单 + provisional 追认清单 + off/on 读数对照。
## 六、provisional 清单(出口人闸逐项追认)
包络数值表(含②新判式复算依据)/ 下限值(2 起步)/ 容量三档排布 / 柜台定价起步价与公比 / MC 代表角集合与护栏带首批读数。
## 七、停机点
- **S1**:T7 极端角把现行带打穿(带 A/B 越界)且包络收窄两档内救不回 → 停机呈报包络重定案(拍板归用户)。
- **S2**:③号卡变异投影的实现形态与 Q1 序在代码层冲突(投影点不可插位)→ 停机对齐,不得自行改③已落语义。
- **S3**:批内任一时点冒烟基线漂移 >2% 且归因不在本批改动面 → 停机呈报(并行会话竞态排查)。
## 八、批末闸与出口
冒烟全量 + run_all 15 套 + 探针五绿(ui_input/ui/ui_layout/fx/t17_defer)+ doc 三闸基线同款零新增 + 熵增 PASS + MC off 逐位 + **主区合并后冒烟复跑**;出口包交付后待人闸(与迭代 14 全迭代出口合并过闸,序位口径在册)。
## 九、红线复核清单(合并前自查)
- [ ] 危险格与安全格同池/九型封闭/一次摇定/负向恒即时四冻结零 diff
- [ ] reward_roll 取号次数与权重无关(断言在)
- [ ] DamageController/极性矩阵零 diff
- [ ] off 态逐位 = 现行(T0 锚对拍 PASS)
- [ ] ②③号卡已落语义零改写(变异投影/判式工具常量只读)
## 十、估时汇总与切分预案
| 卡 | T0 | T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8 | 合计 |
|---|---|---|---|---|---|---|---|---|---|---|
| 估时 | 0.25 | 0.5 | 1 | 0.5 | 0.5 | 1.5 | 0.25 | 1 | 0.5 | **≈6.0d** |
**切分预案**(迭代 14 尾部余量不足时启用,代排待追认):段一机制批 = T0-T4 + T6 ≈ 3d(合成层/存档/柜台/通道全落,构筑面暂用最小命令行式编辑);段二界面闸批 = T5 + T7 + T8 ≈ 3d。两段各自独立 worktree 合并、各自过批末闸。
@@ -0,0 +1,216 @@
# 需求卡片·凭证件裁削批(代码侧迁移)
- **批次名**:凭证件裁削批(代码侧)
- **日期**:2026-10-18
- **批次性质**:工程债/错置修正(凭 06 在册条目直接写卡;设计已于同日文档批在奇物.md v3.18 定稿)
- **设计事实源**(req-card §2 三选一之①GDD 文档节+版本号,2026-10-18 立规;v1.1 补声明):`design/gdd/systems/冒险循环/奇物.md` **v3.18**(删件/迁出/配额净删三段定稿)。**前置门见 §10**。
- **标识符形态通则(v1.1,2026-10-18 用户补裁)**:本卡成文于卡① 之前。凡卡① 改名范围内的标识符(`flag_hit`/`flag_miss`/`flag_missed`/`flag_settle`/`flag_judged`),本卡 §2 现状事实的旧名与行号**按卡① 合回后的 `seal_` 形态**复核执行,不逐处更新旧名;本卡新写的标识符一律 `seal_` 族——效果类型名取 **`forgive_seal_miss`**(取代 D1 原裁 `forgive_flag_miss`),feats.tres 触发行写 `on: "seal_missed"`。
- **版本**:**v1.1**(2026-10-18 卡片冲突修订批:补设计事实源与标识符形态通则;D1 换代为 `forgive_seal_miss`;契约 3/8 订正;§5/§6 文档同步义务改为 `reports/` 反哺点清单;§10 补前置门。原 v1.0=2026-10-18 立卡)
- **迭代归属**:迭代 31 第二张卡(与卡①「代码术语刷新批」串行)
- **上游依据**:用户 2026-10-18 逐裁四项——①同调电池**删除**;②完美保险**改归专长**、语义档=**甲(每战首次封印落空豁免)**;③desc 用 A「本场首次封印落空,不计入完美封印判定」;④寿命域**本批不动**、完美保险按现役 `domain=battle` 落地;配额处置=**净删**(rare 9→7/总量 104→102)
---
## 1. 目标与完成定义
**目标**:把用户 10-18 两项裁断落到代码与数据表——同调电池自奇物体系整体删除、完美保险自资源类迁入专长表并按订阅式重写——同时完成 `TIER_QUOTAS` 结构锚的重裁落地。
**完成定义**(全部满足才算完):
1. `CURIO_KINDS` 不再含 `attune_battery`/`perfect_insurance`,两件在三选一池不可再出现;
2. 同调电池的 runner 侧全部入口(待分配账、玩家点选函数、getter、断点键)清零,无孤儿引用;
3. `feats.tres` 增完美保险专长行,四词表校验通过,效果引擎装载并可派发;
4. 完美排雷判定改为「误标总数 − 豁免数」两账相减式,`_perfect_hit_false` 保持纯净、不被任何效果改写;
5. `TIER_QUOTAS` rare 9→7、总量 104→102,`validate()` 硬断言通过;
6. 代码域闸全绿(冒烟+单元测试+场景探针+改前改后读数对拍)+`reports/` 三份产出物写齐(实现报告/代拍板追认单/反哺点清单)。**文档面(奇物.md 指针销号、entities.yaml 104→102、07 观测项、roadmap 行)不在本条完成定义内**——实现批禁写 `design/` 与根规则文件,一律列进反哺点清单归文档批落笔(v1.1 订正,原句「机械面文档同步完毕」属 2026-10-17 改口径前的旧措辞)。
---
## 2. 现状事实(代码级,开工自行复核)
### 2.1 同调电池(待删)
| 位置 | 事实 |
|---|---|
| `game/data/schemas/adventure_table.gd:21-22` | `CURIO_KINDS` 含 `"attune_battery"` |
| `adventure_table.gd:59` | `curio_quota_attune_battery_rare = 1`(rare 档投放) |
| `adventure_table.gd:76` | `curio_value_attune_battery_rare = 1`(充能 +N) |
| `adventure_table.gd:91` | `curio_cap_attune_battery = 99` |
| `adventure_table.gd:138` | 配额分发表分支 `["attune_battery", TIER_RARE]` |
| `adventure_table.gd:159` | 件值分发表分支 |
| `adventure_table.gd:176` | cap 分发表分支 |
| `game/core/adventure_runner.gd:55` | `_battery_pending`(冒险级待分配充能) |
| `adventure_runner.gd:213` | 断点回填 `battery_pending` 键 |
| `adventure_runner.gd:261` | 冒险开局重置 |
| `adventure_runner.gd:415-417` | `_apply_curio_pick` 路由分支 |
| `adventure_runner.gd:598-610` | `choose_battery_target(item_id)`——玩家点选分配 |
| `adventure_runner.gd:615-616` | `battery_pending()` getter |
| `adventure_runner.gd:1076` | 断点存档键 `"battery_pending"` |
| `game/tests/unit/core/feat_vouchers_test.gd:56-64` | V9-5 断言组(兑付受理/待分配 1/禁自动替选反例/跨层写账) |
**关键事实**:`choose_battery_target` 的调用方只有定义自身、getter、单元测试与断点键——**呈现层零接线**(全库检索 `battery`/电池在 presentation 层零命中)。玩家拿到电池后 `_battery_pending` 挂着花不出去,且随断点一直挂下去。它不是「零途径所以撤」,而是「有 API 有账本有测试、唯独没有玩家入口」。
### 2.2 完美保险(待迁专长)
| 位置 | 事实 |
|---|---|
| `adventure_table.gd:21-22` | `CURIO_KINDS` 含 `"perfect_insurance"` |
| `adventure_table.gd:61` | `curio_quota_perfect_insurance_rare = 1` |
| `adventure_table.gd:78` | `curio_value_perfect_insurance_rare = 1` |
| `adventure_table.gd:93` | `curio_cap_perfect_insurance = 99` |
| `adventure_table.gd:140`/`:161`/`:178` | 配额/件值/cap 三处分发表分支 |
| `adventure_runner.gd:57` | `_pending_insurance`(节点级,下一战标错豁免 N 次) |
| `adventure_runner.gd:263` | 冒险开局重置 |
| `adventure_runner.gd:423-425` | `_apply_curio_pick` 路由分支 |
| `adventure_runner.gd:920-923` | 战首 `set_voucher_grants(...)` 注入后清零 |
| `game/core/battle_orchestrator.gd:81` | `_fx_insurance`(本战标错豁免余量) |
| `battle_orchestrator.gd:422` | `_fx_insurance = enc.get("voucher_insurance", 0)` |
| `battle_orchestrator.gd:266-267` | `_perfect_hit_true`/`_perfect_hit_false`(板级计数,install 重置) |
| `battle_orchestrator.gd:471-472` | install 重置点 |
| `game/core/settlement/grant_segment.gd:295-308` | 标错时 `_perfect_hit_false += 1`;`_fx_insurance > 0` 则 `-=1` 且 `_perfect_hit_false -= 1`(回退)+归因行 |
| `grant_segment.gd:314` | `flag_missed` 事件发射(**晚于计分**) |
| `feat_vouchers_test.gd:52-53` | V9-4 断言(兑付受理/豁免待注入 1) |
**判定式现状**:`_perfect_hit_false == 0 && _perfect_hit_true >= 1` → 完美成立(权威定义 `entities.yaml:254`:板级零误标 ∧ ≥1 标中 → 清图奖励当量 ×P_perfect,默认 ×2)。
### 2.3 配额结构锚
`adventure_table.gd:34`:`TIER_QUOTAS := {"common": 70, "excellent": 25, "rare": 9, "legendary": 0}`(总量 104)。现行分配:rare=ap 3+rap 2+attune_battery 1+time_sand 2+perfect_insurance 1=9。`:4`/`:30-33` 明载「改投放总量=重裁非调参,`validate()` 硬断言」。
### 2.4 效果引擎词表
`game/core/effect_engine.gd`:`EVENTS`(:13-16,已含 `flag_missed`,迭代 21 T3 扩签)/`EFFECT_KINDS`(:25-41,**现 31 项**,v1.1 订正——原记 30 项,无豁免型;本卡 T4 加 `forgive_seal_miss` 后为 32)/`FACTS`(:50-54,含 `counter`)/`OPS`(:61-62,含 `lt`)/`DO_KEYS`(:72-75,含 `domain`=battle/adventure)。四词表出域=加载期校验致命。
---
## 3. 设计契约(🔴 触碰=L3 停机呈报)
1. 🔴 **`attune_charges` 账本与 `_seed_attune_charges` 禁删**(`adventure_runner.gd:29/:109/:201/:243/:559-564`)——迭代 11 秘宝基础设施(主动件充能每冒险重置)。本批只删奇物侧写它的入口,不碰账本本体。
2. 🔴 **`_perfect_hit_false` 保持纯净**:任何效果不得改写该值。豁免必须走「自有累加计数 + 判定时相减」,即新增 `_perfect_forgiven` 单向累加,判定取 `effective_miss = _perfect_hit_false - _perfect_forgiven`。**禁止回退式(改别人的值)与拦截式(吞事件)**——两者均已由用户否决。
3. 🔴 **`seal_missed` 事件照常发射**(卡① 合回前名 `flag_missed`——见顶部标识符形态通则),不得因本件改动改变发射时机或吞并事件,其它订阅方(危险直觉·守等)零感知。
4. 🔴 **玩家面禁「雷」字**(奇物.md v3.15 命名纪律:插旗=封印、危险格风味=地下城陷阱/怪物巢穴)。本批新增的 `feats.tres` 行 desc 与任何 UI 字符串不得含「雷」。
5. 🔴 **四词表封闭**:新增 effect kind 必须同步进 `EFFECT_KINDS` 并在解释器 switch 加分支,否则行校验致命。
6. 🔴 **`domain=battle` 显式写出**:该行将是 `feats.tres` 首例 battle 域(现役 29 行全为 adventure 或不写),须在数据行与代码注释双处留痕,防止后来者误读为缺省。
7. 🔴 **改总量=重裁**:`TIER_QUOTAS` 总量变动是结构锚。用户已裁「净删」(rare 9→7/总量 104→102),本批不得自行把令牌转给别件来保住总量。
8. 🔴 **本批与迭代 31 卡①串行同迭代**(v1.1 订正实证陈述):卡① 改标识符与玩家面字符串。**字段集不重叠**(卡① 不动 `CURIO_KINDS`/`TIER_QUOTAS`/`curio_*`),但**文件集重叠**——`core/effect_engine.gd`(卡① 改 EVENTS/本卡 T4 加 EFFECT_KINDS+switch)、`core/settlement/grant_segment.gd`(卡① 改名/本卡 T4 改判定式)、`core/battle_orchestrator.gd`(卡① 改名/本卡 T3 删 `_fx_insurance`)。故**禁两卡并行开 worktree**;本卡必须在卡① 合回 master 后开工,开工前 `git merge master` 取卡① 成果并按顶部通则复核标识符名与行号。
---
## 4. 范围边界
**做**:上列 6 项完成定义内的全部代码与数据表改动、测试更新、`reports/` 三份产出物(实现报告/代拍板追认单/反哺点清单)。
**不做**(去向明确):
| 不做的事 | 去向 |
|---|---|
| 计数器寿命域统一(三套机制并存问题) | 已在 06 登记「计数器寿命域未统一」,本批不动 |
| `entities.yaml:254`「完美排雷」内部术语改名 | 内部开发用语按 v3.15 纪律保留;仅玩家面用「完美封印」 |
| 冒记遗留两项(凭证归专长/资源=转换源判据句)的正式裁定与重写 | 06 已登记「冒记案遗留待裁两项」,等用户裁 |
| `shop.tres` 货架行、`feat_ticket` 体系 | 与本批无关,不碰 |
| 旧 27 件素材库表 | 不碰 |
---
## 5. 关联文档同步面
> **口径(v1.1,2026-10-17 起生效)**:本批禁写 `design/` 整目录与根规则文件,唯一可写目录=`reports/`。凡标「反哺点」者=把「哪个文件哪一节、改成什么、依据是什么」写进 `reports/iter31-反哺点-<日期>.md`,由用户裁决后归文档批落笔。v1.0 的「机械面随批」措辞作废(属 2026-10-17 改口径前的旧口径)。
| 文档 | 关联点(本批实现会改变它的哪条陈述) | 同步义务 |
|---|---|---|
| `design/gdd/systems/冒险循环/奇物.md` | v3.18 已定稿删件/迁出;本批代码落地后,件表注与迁入登记段中「归独立批」的指针可销号 | **反哺点**·列清单(`design/` 内,本批禁写) |
| `design/registry/entities.yaml:633` | 「104 总量」读数须改为 102(当前注记明写"仍为代码现值,改数随独立代码批同步");:254 完美排雷判据句须补「有效误标=误标数−豁免数」口径 | **反哺点**·列清单(含两处:104→102 读数换代+判据句补写) |
| `design/gdd/07-体验验证清单.md` | 两件退出后相关观测项注销;本卡新增 R5/R6 目检项(专长卡面文案/三选一池面观感)入册 | **反哺点**·列清单(本批禁写 07;R5/R6 目检项先记 `reports/` 实现报告总清单) |
| `roadmap.md` | 迭代 31 行状态由「待开工」改「已完成」;顶部「当前位」三行换代 | **反哺点**·列清单(根规则文件,本批禁写;第 3 步搬运定义面除外——那是提交既有文件,不是本批撰写) |
| `game/README.md` | 若载有两件名或配额读数 | **本批直改**(文件在 `game/` 内,不属 `design/` 禁写面)——随批核对更新 |
| `design/gdd/06-待办清单.md` | 「凭证件裁削批·代码侧迁移」条目状态推进为已完成 | **反哺点**·列清单(本批禁写;§10 前置门 2 的推进归用户/文档批) |
| GDD 设计结论 | **零新增**——设计侧已在 v3.18 定稿,本批无新设计决策需反哺 | 无(上述五行是既有陈述的换代,不是新设计) |
---
## 6. 任务卡
| 卡 | 内容 | 估时 |
|---|---|---|
| **T0 开工基线** | 建 worktree+分支;`git status` 归属核对(并行遗留只标旗不碰);跑冒烟/单元/探针/三闸基线并记档;确认卡①是否已合回(若未合回,本批基于当前 master 开工并登记) | 0.25–0.5d |
| **T1 同调电池·表侧删除** | `CURIO_KINDS` 移除 kind;删 `curio_quota_attune_battery_rare`/`curio_value_attune_battery_rare`/`curio_cap_attune_battery` 三字段及分发表三处分支(:138/:159/:176);同步 schema 头注(:19-20 五件入池表述) | 0.25–0.5d |
| **T2 同调电池·runner 侧删除** | 删 `_battery_pending`、断点回填(:213)、重置(:261)、路由分支(:415-417)、`choose_battery_target`(:598-610)、`battery_pending()`(:615-616)、断点键(:1076);`feat_vouchers_test.gd` V9-5 断言组整组删 | 0.25–0.5d |
| **T3 完美保险·出池** | `CURIO_KINDS` 移除 kind;删配额/件值/cap 三字段与分发表三处分支;删 runner 侧 `_pending_insurance`、重置、路由分支、战首注入链(:920-923)中该件分量;删 `battle_orchestrator._fx_insurance` 与 `:422` 注入;`feat_vouchers_test.gd` V9-4 断言组整组删 | 0.5–1d |
| **T4 引擎扩签+两账相减** | `EFFECT_KINDS` 增 **`forgive_seal_miss`**(v1.1 换代,原 `forgive_flag_miss`);解释器 switch 加分支;`battle_orchestrator` 增 `_perfect_forgiven`(install 重置同 :471-472);`grant_segment` 判定改 `effective_miss = _perfect_hit_false - _perfect_forgiven`,删硬编码 if;`seal_missed` 发射位置与时机不动(卡① 合回前该事件名仍为 `flag_missed`) | 0.5–1d |
| **T5 专长行落表** | `feats.tres` 增完美保险行(规格=§10 D2,已裁:rarity rare/cap 省略/desc「本场首次封印落空,不计入完美封印判定」/feat_id 取 `perfect_insurance`);**触发行 `on` 取 `"seal_missed"`**(卡① 合回前该名仍为 `flag_missed`)、`kind` 取 `forgive_seal_miss`、`domain=battle` 显式写出;`feat_table` 校验通过;确认 rebuild 装载并在 `_triggers` 出现 | 0.25–0.5d |
| **T6 配额重裁落地** | `TIER_QUOTAS` rare 9→7、总量 104→102;`validate()` 硬断言通过;`adventure.tres` 实例值同步;核对 rare 档剩余品种=ap/rap/time_sand 三种 | 0.25d |
| **T7 测试补齐** | 新增专长侧验收(见验证闸);变异验证逐条执行并记录 | 0.5–1d |
| **T8 产出物落位卡+代码域闸** | 轻闸全绿后:`reports/` 三份写齐——实现报告(各 T 卡状态+改前改后读数对拍+实机目检总清单含 R5/R6+变异验证记录表)、代拍板追认单、**反哺点清单**(§5 每条都要有落点:奇物.md 指针销号句、entities.yaml 104→102 与 :254 判据句、07 观测项换代、roadmap 迭代 31 行与「当前位」换代、06 本条状态推进句、术语表 `forgive_seal_miss`/`seal_missed` 换代);`game/README.md` 属 `game/` 内文件、本批直改核对;跑代码域闸全绿。**禁改 `design/` 与 `roadmap.md`** | 0.25–0.5d |
**合计**:≈2.75–4.75d(超软盒预案:T3/T4 若撞断点兼容问题,先落 T1/T2/T6 的可独立验证部分,T3–T5 转下一批并登记 06)。
---
## 7. 验证闸(逐需求点验收)
### 7.1 逐需求点验收清单
| 需求点 | 测什么 | 测试落点 | 归谁验 |
|---|---|---|---|
| R1 电池出池 | `_apply_curio_pick("attune_battery", ...)` 不再被受理;三选一候选集不含该令牌;`CURIO_KINDS` 无该值 | 单元:`adventure_table` 词表断言+`feat_vouchers_test` 反例断言(改后应变红→改为断言"不再受理") | 调试接口 |
| R1 电池无孤儿 | `choose_battery_target`/`battery_pending()` 符号不存在(编译级);断点存档结构无 `battery_pending` 键;旧断点档缺键不报错 | 单元:断点 roundtrip 测试(save_rng_roundtrip 或既有断点套)加缺键兼容断言 | 调试接口 |
| R1 账本保留 | `_seed_attune_charges` 仍每冒险重置主动件充能;`run_ledger.attune_charges` 语义不变 | 单元:既有冒烟断言复核+补一条"删件后充能账本仍按装备重置" | 调试接口 |
| R2 专长行合法 | `feats.tres` 新行通过 `FeatTable.validate`;`EffectEngine.rebuild` 装载后 `_triggers` 含该行两段 | 单元:`effect_words` 类测试加行断言 | 调试接口 |
| R2 豁免一次 | 同战两次标错:首次 `effective_miss` 不增、第二次增;跨战后首次标错又豁免一次(domain=battle 每战清零) | 单元:直构引擎+编排 rig(参照 `smoke_all.gd:6091` 守侧五场景的 rig 法) | 调试接口 |
| R2 计数纯净 | 触发豁免后 `_perfect_hit_false` **值不变**(仍是误标原值);`_perfect_forgiven` 单向 +1 | 单元:同上 rig,双值对拍断言 | 调试接口 |
| R2 判定正确 | `_perfect_hit_false=2 / _perfect_forgiven=1` → effective 1 → 不完美;`1/1` → 完美成立;`_perfect_hit_true=0` 时不成立 | 单元:真值表断言 | 调试接口 |
| R2 事件不吞 | 触发豁免的同一标错,`seal_missed`(卡① 合回前名 `flag_missed`)仍被其它订阅方收到(以危险直觉·守的 AP 返还为观测点) | 冒烟:复用既有守侧场景 | 调试接口 |
| R3 配额锚 | `validate()` 通过;rare 合计 7;总量合计 102;rare 品种集={ap, rap, time_sand} | 单元:`adventure_table` validate 断言 | 调试接口 |
| R4 词表合法 | 新 kind 在 `EFFECT_KINDS`;数据行 do.kind 出域即加载致命(反例实证) | 单元:词表成员断言 | 调试接口 |
| R5 玩家面文案 | 新行 desc 不含「雷」;卡面显示正常 | 用户目检(登记 07) | 用户目检 |
| R6 池面观感 | 三选一再不出现两件;稀有档仅剩三种 | 用户目检(登记 07) | 用户目检 |
### 7.2 变异验证伴生(新增/改写断言必配)
| 变异点 | 注入形态 | 跑哪道最窄闸 | 期望红 |
|---|---|---|---|
| 两账相减判定 | 把 `effective_miss` 改回 `_perfect_hit_false`(漏减豁免) | 单元:真值表那条 | 「1/1 → 完美成立」变红 |
| 计数纯净 | 把豁免实现改回退式(`_perfect_hit_false -= 1`) | 单元:计数纯净断言 | 「_perfect_hit_false 值不变」变红 |
| 限次 | 把 `when` 的 `lt 1` 改成 `lt 99` | 单元:豁免一次断言 | 「第二次标错不豁免」变红 |
| domain=battle | 把 `domain` 改成 `adventure` | 单元:跨战豁免断言 | 「跨战不再豁免」变红 |
| 配额锚 | 把 rare 合计改回 9(漏删一张) | 单元:validate 断言 | 「rare 合计 7」变红 |
| 电池出池 | 把 kind 加回 `CURIO_KINDS` | 单元:词表断言 | 「CURIO_KINDS 无该值」变红 |
### 7.3 闸口径
轻闸(每轮):`tools/run_all_gates.sh --quick`。重闸(批末):`tools/run_all_gates.sh --code`(本批只碰 `game/` 与 `tools/`)。批末四闸=冒烟+单元测试+场景探针+改前改后读数对拍,全绿才合并。
---
## 8. 异常分级
- **L1 自救**:字段删除后编译报错(漏改引用)——按报错定位补齐,属本批范围。
- **L2 记录继续**:旧断点档含 `battery_pending` 键(缺键兼容路径已验证不报错);`adventure.tres` 实例字段与 schema 不同步导致加载警告——记录后继续,批末统一核对。
- **L3 停机写报告**:①删 `attune_charges` 账本被误触(契约 1);②四词表校验出现非预期致命(说明扩签方式与引擎假设冲突);③T3/T4 触断点版本兼容须迁移(本批无迁移授权);④卡①未合回且其改动与本卡文件集出现意外重叠。
---
## 9. 代拍板白名单
1. `feat_id` 取 `perfect_insurance`(与旧 kind 同名,便于追溯旧讨论);display_name 取「完美保险」。
2. 豁免计数 `counter_id` 命名取 `insurance_used`(与 `tree_*_used` 同族)。
3. 若核出 `DO_KEYS.cap` 语义适用于"本 effect 累计上限",则省掉第二条 `counter_add` 触发行(外部行为等价,单行更简);核不出则维持双行。**须在实现报告注明最终选型与依据**。
4. 测试文件落点:能并进 `feat_vouchers_test.gd` 就并,不新建套件(避免套件数膨胀)。
5. `_perfect_forgiven` 的 install 重置点紧随 `:471-472` 既有重置,不新设重置钩子。
超清单必呈报。
---
## 10. 待裁点(2026-10-18 已裁毕;开工门=U0)
- ✅ **D1 效果类型命名**=`forgive_flag_miss`(用户裁「合动宾惯例的」)→ **v1.1 换代为 `forgive_seal_miss`**(2026-10-18 用户补裁)。原裁定管的是命名形状(动词+宾语,与 EFFECT_KINDS 现役 `add_ticket_rider`/`modify_ticket`/`damage_mult` 同族),不是 flag/seal 之争;卡① 要求 `game/` 内 `flag` 零命中,故新名取 seal 族。
- ✅ **D2 专长行规格**=`rarity` 取 `rare`/`cap` 省略(承 twin_pick/geologist 惯例)/`desc`=「本场首次封印落空,不计入完美封印判定」(用户确认,沿用 A 案)。
- ✅ **D3 roadmap 目标句措辞**=维持现落地的「两卡串行:卡①代码术语刷新批+卡②凭证件裁削批·代码侧」事实式表述(用户裁「没有问题」)。
**开工门**:用户发开工令(U0)+**两项前置门(v1.1 补列,2026-10-18 卡片冲突修订批核出)**——
1. **卡① 已合回 master**(本卡所有 flag_ 旧名要按 seal_ 形态复核,且 T3/T4 与卡① 同改三文件,见契约 8);
2. **设计事实源已进 HEAD**(2026-10-18 本会话复核:本门**已满足**):`design/gdd/systems/冒险循环/奇物.md` v3.18 已随提交 `39523dd4` 进 master,`HEAD:奇物.md` 含 v3.18,worktree 从 HEAD 检出读得到本卡事实源。06「凭证件裁削批·代码侧迁移」状态列也已由「待写卡」推进为「文档设计已闭合(奇物.md v3.18)+已写卡(本卡路径)+已编迭代 31」。
本卡不等冒记遗留两项(凭证归专长/资源=转换源判据句)的裁定——那两项不阻塞本卡。
@@ -0,0 +1,195 @@
# 需求卡片:存档制数据层改造批(隐式单档 → 3 存档位)· 营地交互重做卡①
- 版本:**v1.2**(2026-10-18 grilling 轮次裁定回写——Q1 旧档归属裁定甲〔迁 1 号位,代拍板留痕〕、Q2 交付序列裁定甲〔推荐案,用户令按推荐执行〕;卡④回设计段不影响本卡链路——卡③在工程批内;v1.1 审查回写内容见文末修订记录)
- 来源:[需求澄清-营地交互重做-2026-10-18.md](../design/research/需求澄清-营地交互重做-2026-10-18.md)(唯一事实源:④结构树「选档界面:3 存档位,新档/进档/删档」、⑤裁决 2/3/4、⑦切批原则①)+ [存档序列化](../design/gdd/systems/表现与支撑/存档序列化.md) P2 后置条
- 归属:数据层承载面(`game/core/save_manager.gd`)——营地交互重做五卡之一;用户可见面由卡③(选档界面)承载
- 排期:未编入(2026-10-18 用户令:需求卡片不预占迭代号,批次归属按工作量另裁)
- 开工门:U0(用户 `/iter` 发令)+ 待裁点已裁(Q1/Q2 均裁定,见 §10)+ grilling 复核门过
## 0. 前置依赖与并行性
- 卡③(选档界面)依赖本卡数据层;卡②(主菜单三入口化)的「进入存档」钮经卡③落到本卡的激活态。
- **交付序列待裁(Q2)**:卡③未到位前,全游戏无任何生产激活路径(卡③ 契约 8「进档即激活」是唯一激活入口)——旧入口在无激活态下写盘全被拒,且 `settle_adventure`(meta_progression.gd:284)忽略写盘返回值→进度静默丢失。冒烟探针走 attach_path 隔离不会红,机检放控不住。本卡「可先行」以 Q2 裁甲(与卡③同批或卡③在先)为前提;裁乙/丙须按 Q2 表执行过渡态。
- 与在役结构的关系:SaveManager/MetaProgression 已是 autoload(迭代 27 T1 裁点①),本批只改承载面(文件组织与激活态),不改升格结构、不改 autoload 链。
## 1. 目标与完成定义
**目标(澄清④照录)**:存档制数据层改造——隐式单档 → 3 存档位(save_manager + 存档格式)。裁决 2「多存档制,**3 个存档位**」;裁决 3「删档:**要**,且必须**二次确认**」;裁决 4「档槽摘要=**钥石余额、通关次数、冒险次数(总局数)**三项,不含未完冒险进度」。
**相对现状,新增了什么**:
1. 三存档位承载与当前激活位(现=单路径单实例,`user://save.json` 一档到底);
2. 新档/进档/删档三个数据层原语(删档=档案文件删除+盘面即时生效〔卡内工程规定,非澄清裁决语〕;二次确认弹窗归卡③承载);
3. 档槽摘要窥视读器(三项——只读、不激活、不写盘、零副作用);
4. 旧档 `user://save.json` 的显式处置(待裁 Q1)。
**完成定义**(全部满足才算本批完成):
1. SaveManagerCore 承载 3 存档位;位间互隔离(读写/删除/坏档兜底均按位);
2. 新档/进档/删档原语齐备且断言全绿;摘要三项读器按位正确;
3. 启动态钉死:`_ready` 不读任何槽(内存=默认合法空态)、无激活态一切写盘路径拒绝并返回 false、`_path` 不留 `user://save.json` 为隐式写目标;
4. 存档格式版本迁移链零破坏(v1→v7 照旧);本批不升 schema 版本——执行中确需新键时按「v6 域后扩列不升版」先例(vision_used,存档序列化.md:108)处理并登记;
5. 探针/冒烟隔离面(`attach_path` 与 smoke 注入路径)保留且行为零变化;
6. Q1 旧档归属按裁定执行并留痕;
7. 批末重闸按改动域选档全绿;三份 `reports/` 产出物写齐(T4)。
## 2. 现状事实(2026-10-18 实查;开工日 T0 复核行号)
| # | 事实 | 出处 |
|---|---|---|
| F1 | 存档唯一实现=JSON 单档:`_path` 默认 `user://save.json`;`_init(path)` 可注入路径(冒烟隔离用);类头注自述「Core 层零 UI 零玩法依赖……禁 preload/import 任何玩法脚本」 | `game/core/save_manager.gd:15`/:21/:1-5 |
| F2 | 读写原语齐备:`load_from_disk`(新档/损坏兜底/迁移链/高版本拒读四路)、`write_to_disk`(tmp+rename 原子写;拒读禁写态拒绝)、`_corrupt_fallback`(坏档改名 `.corrupt.bak`)、`attach_path`(换路径+回默认数据+重读盘——迭代 27 T1 探针隔离面;注释明载「对象引用恒定,MetaProgression 持有的 save 引用零失效」) | `save_manager.gd:150-183`/:188-202/:443-450/:42-46/:40-41 |
| F3 | 版本与迁移:`SAVE_FORMAT_VERSION := 7`(v7=锻造工坊域 forge_routes);生产迁移链 v1→v7 六件自注册;`_normalize` 缺键补齐+退役域清退 | `save_manager.gd:9`/:25-30/:458-471 |
| F4 | 摘要三项的读取源已在役(单档):`keystone_balance()`、`adventure_cleared()`(三关全通才计 1)、`adventure_total()`(开局即计含放弃与失败)——按槽窥视读器=本批 T2 交付物 | `save_manager.gd:214`/:264/:258 |
| F5 | SaveManager 为 autoload(工程序 ConfigDB→RngService→SaveManager→MetaProgression);MetaProgression 持有 `var save: SaveManagerCore`,`_ready` 取 `/root/SaveManager` 一次——消费面对存档的引用是单实例单引用;全部访问器为 `save.xxx()` 动态分发、无缓存 | `game/project.godot:21`;`game/core/meta_progression.gd:9`/:21-25/:54 |
| F6 | 探针/冒烟隔离机制在役且面比初查大:`_META_SMOKE_PATHS` 注入清单 **18 条**(smoke_all.gd:5701-5708);另有 `user://smoke_save_*` 15 条(:6499-6511)、boot/lifecycle/lifecycle_resume/run_lifecycle 段(:277/:321/:463/:594)、`test_pacing_queue_save`(pacing_queue_test.gd:28)、`smoke_tune_probe_*`(ui_tune_probe.gd:167/:171)、probe tag 族(probe_ui_util.gd:98-121,10 探针 15 处调用);`attach_path` 直接消费 8 处+isolate_save 间接 15 处 | `game/smoke/smoke_all.gd:5701-5708`/:6499-6511 等;`game/smoke/probe_ui_util.gd:98-121` |
| F7 | 文档侧早已预写多档去向:存档序列化.md P2 后置表载「多存档槽位|单档 MVP(2026-09-21 裁决);多档等有真实需求再立项」——本批即该条预写的「真实需求」落地;同文 :61 现行口径=「存档是单文件 JSON(user://save.json)」;:20 系统范围负责表载「单档 JSON 存档的域划分与读写约定」 | `design/gdd/systems/表现与支撑/存档序列化.md:165`/:61/:20/:16 |
| F8 | 近期闸基线:冒烟 1151/0、单测 51/51(34 套件),载于 iter30 实现报告——开工日 T0 重测取当期值 | `reports/iter30-实现报告-2026-10-17.md:23`/:46-47 |
## 3. 设计契约(红线,违反 = L3 停机呈报)
🔴 **契约 1 · 三存档位且仅三位**:用户原话「多存档可以让它有三个存档位」——位数写死 3;批内禁以「将来扩位」名义参数化,扩位=新裁点另立。
🔴 **契约 2 · 位间互隔离**:任一槽位的新建/进入/删除/损坏兜底不得波及其他槽位文件字节;删档只删该槽文件;坏档 `.corrupt.bak` 按槽生成。
🔴 **契约 3 · 迁移链与版本号零破坏**:`SAVE_FORMAT_VERSION=7` 与 v1→v7 链不动。槽位改造是承载面(文件组织+激活态)改造,不是 schema 改造;每槽档案结构与现行 v7 逐键同构。
🔴 **契约 4 · 旧档不静默丢失**:现行 `user://save.json` 必须按 Q1 裁定显式处置(迁 1 号位/保留不载/废弃三选一,用户裁);禁无声忽略、禁默认行为。
🔴 **契约 5 · 摘要三项且仅三项**:钥石余额/通关次数/冒险总局数;禁在摘要面露出未完冒险进度(裁决 4 明示「不需要显示有无未完成的冒险;只要我提到的那三个就够了」)。
🔴 **契约 6 · 消费面纪律不破**:其他系统只经 SaveManager 类型化访问器操作存档(存档序列化.md 消费面纪律);切槽=**同一 autoload 实例内 `_data` 与路径整体替换**(attach_path 先例:对象引用恒定,`save_manager.gd:40-41`)——禁每槽实例化+换 `MetaProgression.save` 引用(`_ready` 一次捕获会静默过期),禁 SaveManager 回写 MetaProgression.save;写盘目标=当前激活槽文件,无激活态时一切写盘路径拒绝并返回 false;「凡钥石发生变动的时刻都要落盘」纪律按位保持(存档序列化.md:121)。
🔴 **契约 7 · 测试隔离面保留**:`attach_path` 与 smoke 注入路径机制原样保留——槽位化后探针仍能隔离到单槽;单路径语义定义为「注入路径=激活槽文件(无激活态时注入即激活并重读)」,既有调用面零改;测试执行两入口铁规不破。若 §9 第 1 条选定单文件三键致该语义不可守,本契约显式降格为「最小改+探针修改清单留痕」并呈报(L3)。
🔴 **契约 8 · 删档原语正确性**:删除后该槽回合法空态(新档合法态=全零可玩,`_default_data` 纪律)、文件不在盘、无 `.tmp` 残留;删档的玩家侧必经二次确认(裁决 3,弹窗归卡③),本卡只保证原语正确;删激活槽时激活指针连清除(该槽不再可写)。
🔴 **契约 9 · 窥视读器三态**:可读槽=摘要三项零副作用;**不可读槽(损坏/高版本/缺版本字段)=显式损坏标记返回,禁触发 `_corrupt_fallback` 改名副作用**(窥视只读零副作用——.corrupt.bak 改名只发生在正式进档路径);`.tmp` 残留按空槽处理。坏档/高版本槽在选档面的呈现与操作集=卡③ Q2(第三态),两卡接口在各自 T0 对齐。
## 4. 范围边界
**做**:三槽承载(路径派生/当前激活位/激活与切位 API);新档/进档/删档原语;摘要三项窥视读器;旧档按 Q1 处置;断言批(冒烟+单测);反哺点清单。
**不做**(明示去向):
- 选档界面 UI、删档二次确认弹窗 → 卡③;
- 主菜单砍钮 → 卡②;营地场景图 → 卡④;ESC 浮窗与营地顶栏 → 卡⑤;
- 存档内容域口径(钥石怎么得、摘要记什么)→ 各 owner 文档(元进度/冒险结构/生涯),本批只承载不定义(存档序列化.md 系统范围纪律);
- schema 升版(确需新键时按先例登记,不主动升);
- 重裁多档策略本身(裁决 2 已裁三位)。
## 5. 关联文档同步面
> **v1.3 口径(2026-10-17 文档同步闸 v3)**:本批是代码实现批,禁写 `design/` 整目录与根规则文件,唯一可写目录 = `reports/`。下表「同步义务」一律执行为「列进 `reports/iter<N>-反哺点-<完成日>.md`:哪个文件哪一节、改成什么、依据,用户会话裁决后归文档批落文」。
| 文档 | 关联点(本批实现会改变它的哪条陈述) | 同步义务 |
|---|---|---|
| `design/gdd/systems/表现与支撑/存档序列化.md` | :61「存档是单文件 JSON(user://save.json)」→ 三槽承载;:20/:16 系统范围「单档 JSON 存档」;:165 P2 后置「多存档槽位|单档 MVP……多档等有真实需求再立项」——本批即该真实需求 | 反哺点 · 单文件→三槽口径改写+P2 条注销(去向=本批) |
| `design/gdd/06-待办清单.md` | 本卡登记条(卡片名/文件指针/状态) | 反哺点 · 列清单 |
| `roadmap.md` | 迭代行编入笔与批内状态刷新 | 反哺点 · 列清单 |
| `game/core/save_manager.gd`、`game/core/meta_progression.gd` | 承载面改造本体 | 实施本体(可写) |
| `game/smoke/*`、`game/tests/*` | 断言与隔离面 | 实施本体(可写) |
## 6. 任务卡
> 估时按 Claude 工作日口径;每卡出口自跑轻闸;开工日 T0 复核本卡全部行号。
### T0 事实坐实与裁点执行(≈0.5–1d)
- 复核 §2 全部行号与读数,漂移即订正本卡;
- Q1 旧档归属裁定执行(迁/留/废弃的动作落地,实现报告留痕);执行前置检查逐项过(见 §10 Q1 表「执行前置」行);
- 槽位存储机制与启动激活态按 §9 代拍板拍板(启动激活态的玩家侧行为以卡③ Q1 裁定为约束);
- **隔离面全清单清点**(v1.1 补):`_META_SMOKE_PATHS` 18 条+`smoke_save_*` 15 条+boot/lifecycle 四段+pacing_queue/tune_probe 两条+probe tag 族 15 处+`attach_path` 8 处直接消费+presenter lambda 注入面(main.gd:317)——逐点确认三槽化后仍可隔离到单槽,判定准则=契约 7 单路径语义;清点结果写成文(T0 产物),漏口恰是卡④要迁的探针面;
- 与卡③ T0 互列对齐:窥视读器签名/命名/返回结构/空槽与坏槽表示法(契约 9 三态)。
### T1 三槽位承载(≈1–1.5d)
- 槽位路径派生与三槽枚举(存储机制按 §9:三文件 vs 单文件三键——硬约束=每槽档案结构与现行 v7 同构、迁移链按槽独立成立、坏档兜底按槽;**槽 1 文件名禁复用 `user://save.json`**(Q1 乙案前提,防旧档被新流程误读));
- 当前激活位:设置/读取/清除;激活切换=同一实例内 `_data` 与路径整体替换(契约 6,attach_path 先例);
- **启动态钉死**(v1.1 补):`_ready` 不读任何槽(`_data`=默认合法空态);无激活态一切写盘路径拒绝并返回 false;`_path` 不留 `user://save.json` 为隐式写目标。启动行为「不隐式激活」的条件表述=卡③ Q1 裁甲/乙-预选时的默认实现;**裁乙-一键直入则本段随裁定改写**(卡③ Q1 连带,本卡不自定);
- 无激活态时访问器 fail-safe(返回合法空态/拒绝写,禁崩禁误写——同未知计数键先例,meta_progression.gd:54)。
### T2 档操作原语(≈1d)
- 新档:空槽创建=合法白板态(`_default_data` 全零可玩纪律);
- 进档:激活+读盘(复用 `load_from_disk` 迁移/兜底链,按槽成立);
- 删档:文件删除+该槽回合法空态+无 `.tmp` 残留+激活指针连清除(契约 8);「盘面即时生效」为卡内工程规定(挪用现役断点覆盖流注释语义,非澄清裁决语);
- 摘要三项窥视读器:钥石余额/通关次数/冒险总局数——只读、不激活、不写盘;空槽摘要=零值合法态;坏槽按契约 9 返回显式损坏标记;
- 写盘目标=当前激活槽文件(契约 6);激活标记自身落盘时机与 §9 第 2 条同一拍板(切槽即时写 or 进档时写)。
### T3 断言批(≈1.5–2d)
- 冒烟:三槽各自写入非默认值→写盘→新实例按位读回逐域相等(往返一致×3);删档后文件不在盘+该槽空态+激活指针清除;坏档按槽兜底;高版本拒读禁写按槽;迁移链 v1→v7 **各槽**成立(三槽各喂旧版本档→各读回相等——既有段只证单实例,本批补各槽断言);窥视三态(可读/坏/高版本)零副作用(窥视前后坏槽文件字节与 mtime 不变);
- 单测(`game/tests/`):摘要三读器跨槽读数正确;位间隔离(改 A 槽、B 槽字节不动);`attach_path` 隔离到单槽的行为保持;
- **启动态断言**(v1.1 补,原缺):boot 后无激活态(无激活访问器返回合法空态、写盘被拒);既有 boot 链 V2d-1(续玩钮恒隐)在新启动态下的处置显式化(改写为「boot 态续玩钮恒隐」或注明由卡② V2 改写时注销——禁判据空转);
- **旧档处置机检**(v1.1 补,原仅件核):按 Q1 裁定案补——甲=迁移前后逐域相等+槽 2/3 空+旧档处置字节留痕;乙=旧文件字节不动;丙=旧文件按定处置;
- **变异验证伴生**(新断言段逐条定注入实验):切槽写成只换路径不换数据(预期位间串味断言红)、删档漏删文件(预期在盘断言红)、摘要读激活位代替窥视位(预期跨槽摘要红)、`_ready` 偷复激活(预期 boot 断言红)、切槽后写盘落错槽(预期位间隔离断言红);实现期逐条执行「注入→最窄闸见红→`git checkout` 精确还原→记录」,记录表进实现报告。
### T4 产出物落位卡(≈0.5d,末卡——三份 `reports/` 文件写齐才算收口)
轻闸全绿后、合并前:`reports/iter<N>-实现报告-<完成日>.md`(各卡状态+变异验证记录表)/`reports/iter<N>-代拍板追认单-<完成日>.md`(§9 白名单内代拍项留痕)/`reports/iter<N>-反哺点-<完成日>.md`(§5 每条一落点)。
**估时合计 ≈4.5–5.5d**(v1.1 上调:隔离面全清单+启动态/窥视三态断言增量)。切分预案:T1/T2 后可切(承载层先落、操作原语后落)——但本卡零用户可见面,切分价值低,建议单批跑完。
## 7. 验证闸(逐需求点验收清单)
| # | 需求点 | 测什么 | 落点/判定手段 |
|---|---|---|---|
| V1 | 三存档位+启动态 | 三槽独立承载、位间零串扰;boot 后无激活态、无激活写盘被拒 | 冒烟往返一致×3+启动态断言+单测位间隔离 |
| V2 | 新档 | 空槽创建=全零可玩合法态 | 冒烟(`_default_data` 纪律同款) |
| V3 | 进档 | 激活+读回=该槽内容 | 冒烟 |
| V4 | 删档 | 删后文件不在盘+槽回空态+激活指针清除+他槽零影响 | 冒烟+文件系统断言 |
| V5 | 摘要三项 | 钥石余额/通关次数/冒险总局数按位正确;空槽零值;坏槽损坏标记;窥视前后文件字节/mtime 不变 | 单测+冒烟(判定手段写死:字节+mtime 双比对) |
| V6 | 迁移链零破坏 | v1→v7 链在各槽成立(三槽各喂旧版本档);既有断言不破 | 冒烟既有迁移段复跑+各槽新断言 |
| V7 | 隔离面保留 | `attach_path`/注入路径机制行为不变(18+15+族清单逐点) | 既有冒烟/探针复跑+T0 清点件核 |
| V8 | 旧档处置 | Q1 裁定执行+机检(甲=逐域相等留痕/乙=字节不动/丙=按定处置) | 冒烟/单测按裁定案+件核 |
| V9 | 反哺点清单 | §5 每条有落点 | 件核对表 |
**测试方式两分法(2026-10-11 用户定)**:V1–V8 机检自动化;能力验证可经调试接口直改槽位/钥石状态(沿用现役 DebugOverlay/DS_DEBUG 门控,不走正常资源积累流程)。**本卡零用户目检项**(无用户可见面)——选档界面目检归卡③ V 表。
**闸口径**:轻闸每任务卡出口自跑;批末重闸 = `tools/run_all_gates.sh` 按改动域选档(本批只碰 `game/` 代码与断言面 → `--code`)全绿才合并;MC 零跑(零数值零行为——纯承载改造,同板同序列结算逐位一致由既有 parity 面承接)。
## 8. 异常分级
- **L1(自救)**:断言写法、命名、文件落点。
- **L2(记录继续)**:存储机制细节(三文件 vs 单文件三键,§9 域内)、激活态内存换栈写法、摘要窥视读器的缓存细节、激活标记落盘时机。
- **L3(停机呈报)**:槽位化与现行 autoload 生命周期不可兼容且修复超出承载面;Q1 执行中发现旧档结构意外(损坏+高版本叠加等)需用户裁;任何触碰 `SAVE_FORMAT_VERSION`/迁移链的诉求;§9 第 1 条选单文件三键致契约 7 不可守(隔离面须改)。
## 9. 代拍板白名单(超清单必呈报)
1. 槽位存储机制与文件命名(三文件 `user://save_slot_N.json` vs 单文件三键+激活索引)——约束:每槽结构与现行 v7 同构、迁移链按槽成立、坏档兜底按槽、**槽 1 文件名禁复用 `user://save.json`**。
2. 启动激活态的数据层机制(激活位持久化位置)——约束:玩家侧行为以卡③ Q1 裁定为准;**仅卡③ Q1 裁乙才需持久化,裁甲则作废**(连同卡③ 契约 8 父注一并按裁定回写)。
3. 类 API 命名(槽位/激活/窥视词族)与文件落点。
4. 删档边界(激活态槽可删性)——约束:禁崩禁误写,删后回合法空态+激活指针连清除;激活态生命周期终点=持续至显式清除/进程结束/该槽被删,**回主菜单不清除**(卡③ Q1 乙案「记忆上次激活槽」读持久化点而非内存态)。
5. 提交切分与 worktree 分支命名。
## 10. 待裁点
### Q1 · 旧档 `user://save.json` 的归属(必裁,未裁不开工)
**背景**:现行单档在开发机可能已有进度(钥石/天赋树/锻造/断点等)。槽位化后旧档必须有明确去向。三案并列,**无推荐**(用户令:不代裁):
| 案 | 内容 | 代价 | 执行前置检查 |
|---|---|---|---|
| 甲 | 迁为 1 号存档位:首次启动一次性迁移,v7 结构原样落入槽 1,槽 2/3 空 | 一次性迁移代码+迁移失败兜底面 | 旧档不存在=无操作(陈明);旧档损坏/高版本=「原样落入槽 1」承诺失效,路由 §8 L3 呈报;迁移后 `user://save.json` 处置(删/改名留痕)+幂等判据(槽 1 已存在不重迁)须在实现报告写明 |
| 乙 | 原样保留、不自动加载:旧文件留盘但新流程不读,自行处置 | 旧档成孤儿文件——盘面出现「看得见拿不到」的档 | 槽 1 文件名禁复用 `user://save.json`(否则「不自动加载」落空);.tmp 残留清理或陈明 |
| 丙 | 开发阶段破坏性废弃:按迭代 21 T5 树域废弃先例(禁迁移禁折算)弃旧档,从空三槽开始 | 开发机现有进度全清 | 旧文件按定处置(删/归档)写明 |
裁决方式:随卡片评审一并定案;裁定落 T0 执行+实现报告留痕。
**裁定(2026-10-18)**:**甲**——迁 1 号存档位。代拍板留痕(用户令「事项按推荐的来」,本项无推荐案,取默认甲=不丢开发机进度;追认单可 veto)。执行按「执行前置检查」列逐项过,迁移后旧档处置与幂等判据写实现报告。
### Q2 · 交付序列:本卡可否先于卡③落地(必裁,未裁不定排期)
**背景**:见 §0。卡③未到位前无生产激活入口;旧入口在无激活态下写盘全被拒且 `settle_adventure` 忽略写盘返回值(meta_progression.gd:284)→进度静默丢失;冒烟探针走隔离路径不会红,机检放控不住。
| 案 | 内容 | 代价 |
|---|---|---|
| 甲(推荐) | 与卡③同批交付或卡③在先(改 §0「可先行」表述,仿卡② 契约 5 硬依赖先例) | 排期自由度下降 |
| 乙 | 批内留临时隐式激活:旧入口首次触达存档时激活槽 1,卡③到位后摘除留痕 | 临时代码+摘除时的二次验证面 |
| 丙 | 接受中间态:登记 L2 已知缺口(激活入口真空),合入前呈报用户知晓 | 中间态进度丢失风险靠用户知情兜底 |
裁决方式:随卡片评审定案;裁甲则 §0 改写,裁乙/丙则按表执行并在实现报告「已知缺口」节登记。
**裁定(2026-10-18)**:**甲**——与卡③同批交付或卡③在先(推荐案,用户令按推荐执行)。§0「可先行」表述按裁甲维持;卡④(2026-10-18 回设计段)不影响本链路——卡③在工程批内,激活入口不真空。
---
**修订记录**:v1.0→v1.1(2026-10-18 grilling 子 Agent 对抗审查回写)——事实订正:F6 注入路径 6→18 条并补全清单面、F8 出处改引 iter30 实现报告、F7 行号 :16→:20;启动激活态闭环:_ready 初态钉死(T1/完成定义 3)、切槽实例同一性(契约 6)、写盘目标与无激活拒绝(契约 6/T2);新增契约 9 窥视三态;S-1「启动不隐式激活」降格条件化、S-2「盘面即时生效」标卡内工程规定;隔离面清点扩为全清单(T0);Q1 补执行前置检查列;验收补启动态/各槽迁移/旧档机检三类断言与两类变异注入;新增待裁点 Q2 交付序列。用户面裁决(裁决 2/3/4)零改动。
@@ -0,0 +1,336 @@
# 需求卡片:战斗一屏样张批(整屏样张判定物首跑 · 四屏样张排程 · 防不满意工序重排)
- 版本:**v1.4**(2026-10-17 开工前预授权复查:本卡**不适用** U1 预授权——两处人闸(T1 方向稿选划/T3 气质终审)是防不满意机制本体,取消即拆机制;四项 L3 经分类**全部属「触既有裁决面/超出本批面」类,维持停机呈报**,详见 §6 分类结论注);**v1.3**(2026-10-17 文档同步闸 v3 口径修订,纯文档批〔分支 carddoc-20261017〕按用户六条裁定执行——①本批(代码实现批,此处含样张工具面)禁写 `design/` 整目录与根规则文件,§8 同步面的同步义务一律执行为「列进 `reports/iter30-反哺点-<完成日>.md`(哪个文件哪一节、写成什么、依据),用户会话裁决后归文档批落文」;冻结记录段全文、目标规格清单、H1–H11 逐项处置、徽章明度档复核转正记录等**成文内容本体随反哺点条目交付**;②产出物落位换代:实现报告/代拍板追认单/反哺点清单三份落 `reports/`,不再 `design/qa/`;③T5 末卡改「产出物落位卡」(三份 reports/ 文件写齐才算收口);④闸口径按域选档:重闸 = `tools/run_all_gates.sh` 按改动域选档(本批触碰 `tools/` 样张面 → `--code`),卡内不再用「全量档全绿」类字样;⑤实机目检项写进 `reports/iter30-实现报告-<完成日>.md` 目检总清单,「入册 07」转反哺点;§7 裁决留痕原文不动,其落文类表述的执行口径随本版换代);**v1.2**(2026-10-16 用户裁决回写:Q1–Q6 六项全部已裁——裁决来源统一措辞「2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)」,§7 逐条留痕;本版改动:§7 由「待裁点」改为「裁决记录」(选项原文保留+裁定案+一句理由),排期改实(迭代 30 已编入、roadmap 同步在批;三卡串行位第 2=徽章→样张→观感),§0/§1/§2/§3/§6/§7.5/§8 按裁定口径改实,T0 承接 Q5 甲案死指涉处置(指代稿候选 v31/v32/v33-draft 实查拍板),T1 新增 Q3 乙案试验件前闸(半天,不过闸退甲案预设退路),T2/T3 承接徽章卡 Q2 甲案之明度档复核转正义务(§7.5 D1 改实),T4 随 Q2 甲案退役为登记行(06 三屏排队行=本批交付义务,写入文档时点=批次出口),估时随 Q3 乙案重算为 **≈5–6d** 并改软盒拆批线,全卡不留已裁 Q 项的「待裁」字样)。v1.1(2026-10-16 grilling 对抗审查修订;v1.0 同日成文)v1.0→v1.1 改动八项,逐条证据见文末「grilling 审查记录」:①**事实面订正七处**——整屏四项的机检代码并非「从无」(`tools/shot_checker.py` 头注自述承载 §1.4 整屏闸机检,迭代 9 T8 已首跑实测 PASS,git 053baeee;缺的是样张判定物与③焦点预算);死指涉行号 527→**562**;v1 四否决原因补全四条(②封印色冲突、④微光格只留微光此前漏列);playnote 引文改逐字;P5「worktree 不可直接跑」证伪(两级回退+自动建目录);旧锚 §5.1 另存于 06:41(此前只登记看板一处);战斗表现内容清单仍写「四区」(现行三区 B/C/D)。②新增 **P10**(关卡屏样张 v1 已冻结 2026-09-28,系立闸前产物)与 **P11**(§1.4 的执行时机已被屏级落码批越过,本批性质=闸后补跑)。③新增 **§0.5 样张批继承的既有待裁义务清单**(全库检索「待样张批冻结/终审/追认」得十项,本批禁止静默丢弃)。④新增 **§0.6 已裁项核收表**(Q 清单据此收敛,已裁面不复问;同时关闭本卡三处隐性重问)。⑤Q1 补乙案连带(A4 尺寸基线须显式解冻重校)、Q2 补关卡屏既有件、目标句与完成定义去掉「并集单闸」预设(合体方式归 Q6 未裁)。⑥新增 **§7.5 跨卡依赖**(与迭代 30 并行两卡的次序耦合+触碰面重叠禁三线并行)。⑦估时加总订正(T4 上限与合计重算)+补先例出处。⑧验收 V 条逐条改挂实存工具,判不了项降级并注明手段。
- **指路订正(2026-10-20)**:徽章卡(迭代 30 卡①)与测试分层卡(迭代 29)已按 doc-conventions §11「吸收即死」退役,本卡对两卡的三处指路句改为结论内联+提交号(`7ffd1dc0`/`fff4f120`),裁决内容零变更。
- 来源:[06-待办清单](../design/gdd/06-待办清单.md)「战斗一屏样张 P0 未开工——界面成品是否过审的那把尺子还没建(2026-10-13 登记,UI 美化三层诊断 · 第二层)」条(:37-43;注:该条「尺子到现在还没造出来」的措辞与 P1 读数有差——机检代码在位,缺的是样张判定物,T0 订正面连带此句);依赖素材取自同清单相邻条「UI 贴图重构批」(:21-27)「UI 字体补完」(:29-35)「资产升档重产批」(:465-471)「立绘清晰度回退评估」(:473 起)「迭代 26 反哺点④」(:78)「美术资产链路审计两项 P0」(:609-615)
- 归属:**美术线**(06 原条归属栏:战斗屏样张的验收标准归[战斗表现](../design/gdd/systems/战斗循环/战斗表现.md)与[美术圣经](../design/art/art-bible.md)共裁);样张生产脚本与机检面归呈现层工具面(工程)
- 排期:**迭代 30 已编入**(2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕),[roadmap](../roadmap.md) 编入行已在案、批内状态刷新列反哺点);三卡串行序位第 2(徽章→样张→观感,§7.5 D3 改实);开工门 = U0〔用户 `/iter` 发令——Q1–Q6 已全部裁决(见 §7),无遗留待裁项〕;v1.1 之「Q1 必须先裁」前提随其裁决(丙案)关闭,本批依赖链与任务顺序已按丙案口径改实(见 §0/§3)
- **立场前提(用户原话,本卡每环节据此设计)**:「现在做优化就是因为它丑;如果还是用原有方式产出,很可能还是不满意。」⇒ 本卡对现状的改动不是「再跑一次程序化产图」,而是**工序重排 + 选型交用户裁决 + 否决成本前移**;每张任务卡自带「相对现状新增什么」与「防重蹈不满意怎么防」两栏。
---
## 0. 前置依赖与并行性
**串行位**:按 roadmap 执行纪律「一迭代一 loop、单迭代串行」(roadmap.md:93),本批**已编入迭代 30**(2026-10-16 用户令,roadmap 编入行已在案、状态刷新列反哺点),前置=迭代 29(需求卡片-测试分层与门禁语义修正批(迭代 29,已入库合并 fff4f120,卡片已退役))完成后开工;三卡串行序位第 2(徽章→样张→观感,2026-10-16 用户令裁定,§7.5 D3 改实)。**两处限定(v1.1 补)**:①迭代 29 已于 2026-10-16 合入 master(合并提交 fff4f120,roadmap.md:88 状态=✅ 已入库;本卡原「迭代 29 U0 未解」读数随之作废,见 §7.5 D4),该前置已满足;本批开工时点仍取决于用户 `/iter` 发令,禁把「迭代 29 完成后」读成排期承诺;②触碰面重叠除 iter29(`tools/`、06、08、07、roadmap、active.md)外,**还包括另两张迭代 30 卡**(徽章卡动 `presentation/views`+06/08/07+art-bible 修订行;棋盘观感卡动 `tools/recolor_terrain_tiles.py`+golden 基线+art-bible §4.1/§4.3+08 表现行)——三卡各写 06/08/07/art-bible/roadmap/active.md,序位既裁则「禁三线并行」转为逐批串行执行,详见 §7.5。**v1.3 注**:三卡文档直写义务已按 2026-10-17 文档同步闸 v3 全部转为反哺点(落 `reports/`,见 §8),上列汇聚文件重叠随之消解,但 2026-10-16 串行序位裁定不因此失效——序内仍有 golden 基线先后(§4B/§7.5 D2)与 art-bible 冻结内容先后(D1)依赖,禁三线并行维持。
**闸已立、机检面已跑过实机帧、样张判定物从未出**:整屏样张闸条款已于 art-bible v3.0(2026-09-29)写入 §1.4(L64)——四屏各出一张整屏样张、验收四项、闸形「方向稿目检先行」、执行时机 = 屏级视觉落码开工前;§7.1 占位完成条款同步在位(L411,程序化占位 = 临时态,终稿闸 = §1.4 整屏样张过闸,占位态禁止跨里程碑)。**机检面并非空白**:`tools/shot_checker.py` 头注自述「整屏样张闸机检(迭代 9 卡⑤/T8 2026-09-30)」,四项中 ①文字对比 ②明度三档带 ④文字禁压纹理 已有实现(B/C/D 段,另 F 段补「文字在判据」),③整屏焦点预算明文「语义面无法机检 → 归实机目检人闸」(E 段);该断言集 2026-09-30 已对**实机渲染帧**首跑实测 PASS(git 提交 053baeee:「实测 PASS——WCAG 5.79-13.14/三档 204>79>55/骨架四屏过;焦点预算=目检项归段闸人闸」),随闸三裁决亦已裁毕(见 §0.6;呈报单原文件 design/qa/m3-iter9-t8-rulings-2026-09-30.md 已按吸收即死纪律在提交 8e02dcf0 删除,结论以各权威文档现行为准),现挂在 `tools/render_gate.sh` ①段周期跑。**本批要补的是剩下的半截**:出 §1.4 意义上的整屏**样张判定物**(目标图,非现状截图)、走「方向稿目检先行→精制→冻结」的闸形、补 ③焦点预算的判定、按屏扩取样点位、立四屏冻结记录(**v1.2 按已裁范围收窄:Q2 裁甲案,本批只出战斗屏判定物与其冻结记录,余三屏登记 06 排队行归后续批**)。**不新立闸条款。**
**前置事实(2026-10-16 实读)**:
| # | 事实 | 出处 |
|---|---|---|
| P1 | 格子样张 v3 已冻结(2026-09-30,机检 17/17 全绿,四冻结①④重冻生效)。整屏四项的**机检代码在位且已对实机渲染帧跑过**(B 文字对比/C 明度三档带/D 文字禁压纹理+F 文字在判据),**唯 ③整屏焦点预算明文不可机检(E 段归人闸)**;§1.4 意义上的「整屏样张判定物」与四屏冻结记录两件从未产出 | [art-bible](../design/art/art-bible.md) §1.4(L64 闸条款/L68 v3 冻结记录);[shot_checker.py](../tools/shot_checker.py) 头注 L1-25;git 提交 053baeee(iter9-T8 卡⑤ 首跑实测 PASS);[render_gate.sh](../tools/render_gate.sh) ①段 L11-13 |
| P2 | 现行 v3 脚本头注自称「战斗一屏样张方向稿生成脚本 v3-draft」,实际出的是 B/C/D 三区 1280×800 全内容合成图 + S2/S3/S4 附录 + A1–A6 程序化审计——但**冻结记录登记在格子样张闸名下**(圣经 §1.4 v3 段),且它验的是「格+一张合成 mockup」,不是「屏级气质判定物 + 四项逐项断言 + 冻结记录」三件齐 | [render_sample_sheet_v3.py](../tools/render_sample_sheet_v3.py) 头注 L2、L28「一屏样张 = B/C/D 三区全内容(1280×800 1:1 实比)」、L1100-1144 版式与断言清单;art-bible §1.4 L68 |
| P3 | 看板十五件:✅4 / ◐8 / ⬜3(实点计数核过);「战斗一屏样张」行 = ⬜ 未开始,需求文档指针为战斗表现 + art-bible §5.1。**注:§5 已抽离至 [character-design.md](../design/art/character-design.md)(v1.7 批),指针系旧锚;同型旧锚另有 06:41「归属」栏一处**(写作「验收标准归战斗表现与美术圣经 §5.1 共裁」——正确锚应为 §1.4 整屏闸+§7.2 文字硬指标,§5.1 只管剪影轮廓),T0 两处一并订正 | [art-status-checklist.md](../design/art/art-status-checklist.md) L5/L13-14;06:41 |
| P4 | 旧冻结样张产物 `sample-batch-v3-final-2026-09-30.png` 磁盘实测不在盘(`artwork/mockups/` 现存 v0/v2/v31/v32/v33/v34/v35-draft 等同系列图与 level-map-sheet-v1),06 在册 P0①(死指涉条,其原记状态至 2026-10-16 前悬而未决)**已由 Q5 裁甲案(2026-10-16 用户令),处置落 T0**(2026-10-14 审计会话存档 :290/:316 仍记「未读到」)。**订正:06:611 原文写「art-bible 第 68/527 行」,现行为 68 与 562**(527 行实为 §9.1 正面参考表,不含该指涉;562=v3.2 版本历史行)——T0 订正面对 art-bible:68/:562 与 06:611 的行号自身一并核。**同类死指涉另检出一处(v1.1 新增)**:art-bible §8.2 L490 指路 `design/qa/m3-iter9-t8-rulings-2026-09-30.md`(迭代 9 三裁决呈报单)该文件已在提交 8e02dcf0「存量超期清理批」删除,盘上不存在——裁决结论本身已由 art-bible §8.2/§8.4 与 06:465-471 承载,指路须改指现行文档或改「描述性出处」 | 2026-10-16 目录实查;06:609-615;design/art/美术审计-cursor会话存档-2026-10-14.md:290,:316;git 只读查询(053baeee 建件/8e02dcf0 删件) |
| P5 | 素材不入 git(归档纪律 art-bible §8.3 L500),v3 脚本 `asset_root()` 做「本仓库→主检出 D:/code/g-plan2」两级回退,且 OUT_PNG 落笔前 `os.makedirs(..., exist_ok=True)`——**故 worktree 分支内可直接跑(v1.0 的「不可直接跑」判断证伪)**;真实约束是**产物落进该 worktree 的 `artwork/mockups/`,而 `artwork/` 整目录不入库**,冻结件不随合并进 master,须按 §8.3 归档纪律打包(这亦是 P4 丢件的成因)。素材在盘实测:board 瓦片 64 件、character 立绘/小人、`game/assets/ui/icons` 状态图标 18 件、fusion-pixel 字体齐 | 脚本头注 L31 + `asset_root` L50-56 + L62/L1147-1149;art-bible §8.3 L500;2026-10-16 目录实查 |
| P6 | 样张 v1 曾被用户**四原因整体否决**(2026-09-28),四条已全部断言化。**权威映射表在脚本写报告的那段代码里(L1156-1160),不在头注**——头注只逐条标了 ①③ 的编号,②④ 需从映射表补:①**显示太丑(总纲)**→ A6 观感密度+装饰变体 ≥2 种;②**封印色冲突**→ 封印黑 #000000(A1a 色板对表自动覆盖);③**立体感不够**→ A3 图底分离阈值上调+F6 顶面/立面双明度带 Δ≥18+F7 整板悬崖 DEPTH_PX 与游戏渲染常量同源;④**微光格只留微光**→ F5c 微光段零 draw_inlay(另见 art-bible v2.12 角嵌退役批)。注:脚本头注 L23 仍写 A3 Δ≥55、L1157 仍写「整板明度 std ≥50.9」,两处均是**旧口径残留文本**,现行定值以圣经 §1.4 v3 记录为准(A3b Δ≥30、A6 明度梯度均值 ≥4.70) | 脚本 L12-26(F1–F7/A1–A6 头注)+L1156-1160(四否决映射表);art-bible L68(Δ≥30 定值)/L570(v2.13「v1 四否决原因断言化收官」)/L569(v2.12 ④) |
| P7 | 用户气质否决另有两例点名先例:①站桩排版旧格式「盒顶固定 y 与盒内居中在高盒下拉开血条-立绘空洞」2026-10-06 用户点名否决,由 art-bible §8.2「站桩立绘排版 = 方案二」代替(L496);②playnote 立绘批评,**逐字原文**:「现在的立绘太丑了,像素化的粒度太低了,导致根本看不清立绘;看是否可以改回用较为高清的图片?」(playnote.md:9,文件本身无日期;日期系 06「资产升档重产批」条 2026-10-06 注所记「同日 playnote 立绘批评」,裁定日为 2026-10-13 归美术线) | [playnote.md](../design/research/playnote.md):9;art-bible §8.2 L496;06:465-471/06「立绘清晰度回退评估」条 |
| P8 | 氛围层两派并存(平滑渐变件 vs Bayer 有序抖动)——**已裁半**:vignette/gradient_base/beams 三件保平滑连续 alpha(2026-10-13 grilling Q5 裁,已入 §7.6(三)+§8.2 LINEAR 豁免清单);**未裁半** = 两派是否统一,明文「留整屏样张批统一裁决」——本批承接的正是这未裁半(**Q3 已裁乙为主**:统一结论在引擎实拍图上呈报、落 T3 裁决记录,见 §7) | art-bible §7.6(三) L465、§8.2 L486;06:78(迭代 26 反哺点④)/06:82(用户裁「全部按呈报写入文档」) |
| P9 | 渲染手段现状:**全仓 `.gdshader` 实测仅一枚**(`game/presentation/views/desaturation.gdshader`,结算去饱和),`ShaderMaterial` 消费面实测仅 `board_view.gd` 一处(:111 声明/:170-172 创建/:194 tween 参数),`.tscn` 内无 shader 节点;样张面全部为 PIL 代码绘制;「Godot shader 能否胜任特效」是用户已提出的未验证疑问(已由 Q3 裁定乙案承接:开工先半天试验件坐实,见 §7;另卡亦载,见 §7.5) | 2026-10-16 全仓检索(`find *.gdshader`+grep `ShaderMaterial`);徽章卡(迭代 30 卡①,已入库合并 7ffd1dc0,卡片已退役)F5/用户立场前提行 |
| P10 | **关卡屏并非零样张**:关卡画面样张 v1 已于 2026-09-28 冻结(机检 11/11 全绿,闸形 A=机检全绿即冻结,气质终审走 M-2 出口闸真人目检八项过),产物 `artwork/mockups/level-map-sheet-v1-2026-09-28.png` **在盘**。它立闸于整屏样张闸条款(v3.0,2026-09-29)之前,**从未按整屏四项判定过**——Q2 若裁含关卡屏,动作是「按四项补判既有样张」而非从零出图 | art-bible v2.14 L565、§7.2 L418;[level-map.md](../design/gdd/ux/level-map.md):3/:222/:244;roadmap.md:21(M-2 出口闸目检通过);2026-10-16 目录实查 |
| P11 | **闸的执行时机已被越过,本批性质=闸后补跑**:§1.4 明文执行时机 =「屏级视觉落码开工前」,而屏级落码已发生四轮(迭代 9 视觉落码段、迭代 16 UI 设计对齐、迭代 25 全局主题、迭代 26 交互与观感),Alpha 亦已于 2026-10-03 到手(M-3 关闭);08「三 · 界面」多行已标在役、五 · 表现仍载「战斗一屏样张=待做」——即 §7.1「占位态禁止跨里程碑」在事实上已被跨。此定性直接影响完成定义第 1/3 条的语义(过闸≠事前定方向,而是对已在役形态出目标图判定物)与 T3 回炉半径 | art-bible §1.4 L64、§7.1 L411;roadmap.md:53/:68/:84-85;08:100-118/:158;美术审计-cursor会话存档-2026-10-14.md:168 |
**与相邻 06 条的依赖关系(Q1 已裁丙案——样张即设计目标图,本节按丙案口径改实,Q1 原文见 §7)**:
- 「UI 贴图重构批」(营地与元进度件出终稿,08 标待做 08:156,06:21-27 状态待办)——判例前置件;**Q1 丙案裁定下不构成本批前置**:样张不待其终稿,反之本卡目标规格清单(尺寸档/色板/明度档逐件成文)反向给其重产/终稿提要求;
- 「资产升档重产批」(06:465-471:**已裁案乙**〔2026-09-30 迭代 9 三裁决,本迭代不升档〕+2026-10-04 用户令暂不做、重启=用户点名+2026-10-06 优先级再降;v1.0 的「档位上调方向候选」已被 v3.7 八敌逐键定档实质完成,剩余挂起项仅「提灯点亮解禁候选」)与「立绘清晰度回退评估」(08「五 · 表现」L146 待裁+08 §7 未决项第 7 行 L210,方向待裁)——素材线两个闸口,**性质不同**:前者=已裁且挂起(本批禁代裁、禁重开),后者=真未裁;**Q1 丙案裁定下两者均不再是样张前置**,本卡反提规格反而是其重启时的输入;
- 「UI 字体补完」(08:157 标待做,06:29-35 归属栏载明须先裁「补不补拉丁专件、要不要上第二个字重」)——**Q4 已裁丙案**:样张按「目标字重效果」示意出图、本批按样张补真件;「补不补拉丁专件、上不上第二字重」仍归该条自身未裁点,本卡不代裁(见 §7)。
### 0.5 样张批继承的既有待裁义务清单(v1.1 新增——全库检索「待样张批冻结/终审/追认/重议」所得)
**为什么要这一节**:这些事项不是本卡新造的议题,而是各权威文档**明文把裁决动作挂名到「样张批」**的既有欠账——本卡若不受理,就会在「本批做完了」的读数里静默丢掉十件在册义务;若受理,就必须逐项写清「本批冻结/本批不冻结并说明去向」。**受理方式已随 §7 已裁 Q 项改实(v1.2)**:Q1 丙案——H1–H4 的尺寸欠账由「目标规格清单随样张冻结产出」承接;Q2 甲案——本批只判战斗屏;Q3 乙案——H10 之氛围统一结论在实拍图上呈报;Q6 乙案——两闸分跑。**本表对 H 项内容本身仍不预设结论——逐项最终处置(冻结/不冻结+去向批次)按契约 7 落 T3 冻结记录。**
| # | 欠账项 | 现行状态与出处 | 与本批的关系 |
|---|---|---|---|
| H1 | 19 枚格面奖励徽章**尺寸**(源 40×40;显示 20/40 双档候选) | art-bible §4.6.2 L309「尺寸候选,样张批冻结」 | 整屏样张要放徽章位即触到该尺寸;未放则显式写「本批不冻结,归贴图批」 |
| H2 | 地形变异纹带族**尺寸**(源 64×64 无缝) | art-bible §4.6.3 L328 同口径 | 同上 |
| H3 | B 区舞台背景 `stage_bg.png` **尺寸**(源 1280×270 基准一张) | art-bible §6.1 L364 同口径;§6.1 L361 地窟看台「规格与终值归整屏样张闸冻结」 | 战斗屏样张的 B 区背景件,正面触到 |
| H4 | 护甲类型(light/ward/heavy)视觉区分方案 | art-bible §4.6.4 L335/§5 存根 L350/[character-design.md](../design/art/character-design.md) §5.3 L27「候选方案,样张批冻结」 | 站桩名行/徽标呈现触到;是否本批裁归用户 |
| H5 | 类型微光**组间互辨抽测**义务(含明度档) | 06:431 裁决④「样张批保留组间互辨抽测义务」;§4.2 L218 组间明度档值从未定义 | **与徽章卡 Q2 直接耦合**(见 §7.5 跨卡 D1) |
| H6 | 面板间距/内边距 4px 步进档**终值** | art-bible §7.3 L426「终值归样张批」 | 整屏构图量取即触到 |
| H7 | 棋盘小人源档与格边长占比摩擦终值(36px 板 × 32px 源超 ≤0.75 红线) | art-bible §8.2 L494、v1.9 待决注记 L581 | 格边长三方取值不一致另条在册(06「棋盘格边长三方取值不一致」),本批禁代裁,只登记 |
| H8 | 镜像与「旗面恒画右」纪律相容口径(代拟待追认) | art-bible §8.4 L508「代拟口径,样张批追认」 | 冻结记录逐条写明已追认/未追认 |
| H9 | 钩爪恐魔「宽≥高」豁免(待样张批终审) | character-design L71 | 站桩样张含该敌种即触到终审位 |
| H10 | 记忆态/明度带随深度微移/提灯点亮形制/滑轨两段可辨 等 provisional 读数 | art-bible §6.5 L392(「样张/实机自检锚」)、§2.7 L129(「候选,整屏样张冻结」)、§7.6(二) L456(滑轨归样张目检)、character-design L45(提灯点亮形制归整屏样张批重议) | 整屏样张即其判定物;本批须逐项在冻结记录写「裁了/留哪一批」 |
| H11 | 「圣经口号型条款机检化批」前置整备(约 55% 条款属口号型无可机检值,分章推进) | 06:513-515「随整屏样张闸前整备批启动」;Alpha未完成事项梳理-2026-10-13.md:133 | 跨卡次序已改实(§7.5 D3 已裁三卡串行序位=徽章→样张→观感,本卡位第 2);本整备批是否纳入本批开工门仍属排期题,归用户呈报,本卡不自裁 |
### 0.6 已裁项核收表(v1.1 新增——铁律「禁再问已裁项」的检索留档)
下列事项**已被用户明文裁决**,本卡全部 Q 项一律**禁止重开**;表中同时是本卡相关表述的执法依据。
| 事项 | 现行裁决 | 出处 |
|---|---|---|
| 格子样张 v2 四冻结(砖面/色板/动画/数字形制) | v2 冻结(2026-09-28)→ v3.0 解冻①④ → **v3 重冻生效(2026-09-30,机检 17/17)**;②色板③动画全程未动 | art-bible §1.4 L66/L68、v3.2 L562 |
| 类型微光五组**色相** | **样张 v2 定稿(2026-09-28)**;HUD框架:140 同记「五组色相经样张 v2 冻结」——06:431「候选值,样张批冻结」系滞后措辞,**冻结为真实现状**;本批不重裁色相值 | art-bible §4.2 L218;[HUD框架](../design/gdd/systems/表现与支撑/HUD框架.md)「未开格类型微光」节实装状态行;详见 §7.5 D1 |
| 微光组粒度 | v3.12 批已裁:组间五色相、组内不细分 | art-bible v3.12 L551、§4.2 L218 |
| 未开格类型微光作用圈 | 英雄周围 8 格(非全板常显),2026-09-30 用户裁;不随灯光区扩 | 06:431 口径校正;HUD框架同节;art-bible §6.5 L390 两圈分立注 |
| 站桩形态(卡片式退役) | 2026-09-20 用户裁决全站桩式,对照义务解除 | [战斗表现](../design/gdd/systems/战斗循环/战斗表现.md):77/:83/:93;[battle.md](../design/gdd/ux/battle.md):395/:437 |
| 站桩排版 | 2026-10-06 用户拍板方案二(旧「盒顶固定 y+盒内居中」点名否决退役) | art-bible §8.2 L496 |
| 八敌立绘源档 | 2026-10-06 逐键定档批完成(36–94,显示 ×2);「48/64/96 三档候选」一并完成 | art-bible §8.2 L495、v3.7 L556 |
| 资产升档重产 | 已裁案乙(本迭代不升档)+2026-10-04 令暂不做+2026-10-06 优先级再降;重启=用户点名 | 06:465-471 |
| 1920 档缩放策略/动画帧数规格/资产升档与否(迭代 9「随闸三裁决」) | **三件全部已裁**:1920=案甲全局等比(v3.2);帧数=样张 v2 ③冻结(§8.4 L505-507);升档=案乙 Alpha 后(06 已裁) | art-bible §8.2 L490、v3.2 L562、§8.4 L505;git 提交 053baeee(呈报单原文件已按吸收即死纪律删除,见 P4 附注);本卡禁以「随样张裁」名义重列 |
| 氛围层三件保平滑 | 2026-10-13 grilling Q5 已裁(统一与否另裁,见 P8) | art-bible §7.6(三) L465、§8.2 L486 |
| 封印色 | 封印黑 #000000(2026-09-28 用户拍板;紫→黑因色相冲突) | art-bible §4.1 L196、v2.11 L568 |
| 角嵌/微光格附加图形 | 2026-09-28 用户裁「微光格只留微光」,角嵌彻底退役 | art-bible v2.12 L569、§3.2 L168 |
| 关卡屏视觉终稿 | 样张 v1 机检 11/11 冻结(2026-09-28)+M-2 出口闸真人目检八项过 | art-bible v2.14 L565;level-map.md:3/:222;roadmap.md:21 |
| 按钮五态/全局 Nearest/主题资源 | 迭代 25/26 入库并经用户 2026-10-14 裁「全部按呈报写入文档」 | art-bible §7.6、v3.14 L549;08:117-118/:155 |
---
## 1. 目标与完成定义
**目标(一句话)**:把「判定界面美术算不算过关的那把尺子」补齐并按它跑通战斗屏——**尺子 = art-bible §1.4 整屏闸四项 + [战斗表现](../design/gdd/systems/战斗循环/战斗表现.md)「一屏样张的验收标准」节五项(:79-93)构成的断言集,两套口径的合体方式已由 Q6 裁定乙案——两闸分跑(见 §7);跑通 = 方向稿目检先行 → 精制 → 机检 → 用户终审 → 冻结记录写入文档**。
**相对现状,新增了什么(批次级;v1.1 按 P1 读数重写第 1/4 条)**:
1. 现状:**格子闸执行并冻结过;整屏闸的四项机检代码也已存在并对实机渲染帧跑过**(迭代 9 T8,shot_checker B/C/D+F),但**从未产出「整屏样张判定物」、从未立整屏冻结记录、③焦点预算从未判定**——本批新增=样张判定物本体+整屏冻结记录首条(战斗屏;四屏全套随 Q2 甲案余三屏登记 06 排队行归后续批)+③焦点项的目检判定+取样点位按屏扩面(T2);
2. 现状产图工序 = 脚本一次合成单路线成品直接呈报——本批新增**方向稿先行**硬工序(本批战斗屏先出 2–3 张低成本方向稿供用户选划,方向判完才准精制,T1;后续各屏各自立此闸);
3. 现状渲染手段默认锁死「PIL 程序化代码绘制」——本批把代码绘制 / shader / 新素材三路线的选型呈用户裁决(Q3),**已裁乙为主、预设甲案退路(2026-10-16 用户令)**:Godot 引擎实拍+shader 为目标路线,开工先半天试验件坐实,不过闸即退甲案纯代码管线(退路预裁定,见 §7);
4. 现状两套标准并存未合体(§1.4 整屏四项 / 战斗表现专项五项)——本批合成一张逐项比对表(T2),合体方式**已由 Q6 裁定乙案:两闸分跑**(专项第 5 项只产裁决记录)。
**防产出重蹈不满意(批次级,三道防线)**:
- **防线一(工序)**:否决成本前移——方向稿阶段否决只损失半天,精制阶段否决按战斗表现判定回退条款只回炉不过项(继承既有口径「已过项结果保留」,战斗表现:93);禁止跳过方向稿直接出精制版(V1:无目检记录即开工精制 = 违红线)。
- **防线二(判据)**:P6 四条否决原因(①显示太丑/②封印色冲突/③立体感不够/④微光格只留微光)+P7 两例(站桩排版空洞、立绘像素粒度)逐条映射为整屏断言集内的具名项;断言不过不出图(「生成即验,不过闸不出图」纪律沿 v3 脚本原文 L12)。
- **防线三(终审)**:气质终审权恒归用户目检,机检全绿不等于过闸。先例:v3 冻结时气质终审走的是「验收豁免」(art-bible L68,2026-09-29 用户验收豁免,状态记录 281),本批**不申请豁免**——此为**本批自我从严的执行纪律,不是对用户裁决的改动**;用户若主动以豁免方式判定本批完成,从其裁决。
**完成定义**(全部满足才算本批完成):
1. 战斗屏样张过闸:方向稿用户选划记录在案 + **按 Q6 已裁乙案两闸分跑、两闸全绿**(含 ③焦点预算的目检判定记录;专项第 5 项只产裁决记录不产过/不过) + 用户终审「过」记录;
2. 冻结记录**成文**(内容 = art-bible §1.4 新增整屏样张冻结记录段全文——设计权威文档零直改,**仅过闸后成文**):同段逐条写明「本样张冻结了什么、没冻结什么」,并对 §0.5 的 H1–H11 **逐项给出处置**(本批冻结/本批不冻结并写明去向批次),禁留空;**同段另须产出两件交付物:① 目标规格清单(Q1 已裁丙案:尺寸档/色板/明度档逐件成文,反向给素材重产批提要求,承接 H1–H4 尺寸欠账);② 徽章卡 Q2 甲案 provisional 明度档之复核转正记录(H5 组间明度档复核+组间互辨抽测,复核转正义务按 §7.5 D1 落本卡冻结件,为本卡交付义务)**——全文随 `reports/iter30-反哺点-<完成日>.md` 对应条目交付(「改成什么」栏即全文),「写入 art-bible §1.4」列反哺点,落文归文档批;
3. 状态回写义务列反哺点(判据语义不变;**条款在 art-bible §7.1 L411**;08 侧的行是「五 · 表现」表「战斗一屏样张」行 L158,08 无 §7.1 小节——v1.0 此处指路写错已订正):
- 反哺点条目:08「五 · 表现」表「战斗一屏样张(界面美术的终稿闸)」行:待做 → 在役;
- 反哺点条目:[art-status-checklist](../design/art/art-status-checklist.md)「战斗一屏样张」行:⬜ → ✅;
- **边界条款**(写进反哺点条目本身):样张过闸只是**判据生效**,不是各屏占位素材的转正条件——看板其余 ◐ 行(营地件、格面徽章、演出类等)仍须各自素材交付后才可改 ✅,禁止把「样张过闸」扩解为「全部占位转在役」;样张同时按**已裁 Q1 丙案**冻结目标规格清单、反向给素材重产批提规格要求(尺寸档/色板/明度档逐件成文),转正仍逐件走闸;
- **P11 定性连带**(写进反哺点条目本身):本批属闸后补跑,回写禁写成「落码前定方向」口径,须如实注记「屏级落码已先行四轮,本样张为对已在役形态的目标图判定与冻结」;
4. **Q2 已裁甲案**:本批仅出战斗屏;关卡/菜单/营地三屏的 **06 排队行登记内容属本批交付义务**(排队行措辞含 P10 注记与营地屏「待目标规格清单反提要求」注记),随反哺点清单交付、落文归文档批;关卡屏既有 v1 冻结样张保留为注记(**其后续批是「对既有 v1 冻结样张补判整屏四项」,不是从零出图**,P10);
5. §8 同步面清单每条在反哺点清单有落点;权威文档与 06/08/看板零直改(v3 口径)。
---
## 2. 范围边界
**做**:战斗屏样张全流程(方向稿→精制→双口径机检→终审→冻结);四屏排程落地按 **Q2 已裁甲案**(本批仅战斗屏+余三屏 06 排队行登记内容,随反哺点清单交付);整屏断言集的**承载与扩面**——**优先复用 `tools/shot_checker.py`(已有 B/C/D/F)+ `game/smoke/shot_probe.gd` 的 shot_meta.json 坐标源**,缺口(③焦点判定、逐点位覆盖、色数上限计数)才新建,禁另起一套并行判据;§0.5 H1–H11 继承义务的**逐项受理与处置登记**(冻结或写明去向,不自裁内容);氛围层两派统一裁决的**裁决与登记**(**Q3 已裁乙为主**:统一结论在引擎实拍图上呈报、落 T3 裁决记录,写入文档列反哺点,落码归后续呈现批);P3 看板与 06:41 两处旧锚订正、P4 死指涉处置(**Q5 已裁甲案**:改指在盘最近稿 v31/v32/v33-draft 之一并注「指代稿」,具体指哪份 T0 实查盘面后定)+ 06:611 行号读数自身订正、战斗表现内容清单「四区」旧措辞订正——以上文档订正一律以反哺点条目交付(写清文件/节/改成什么/依据),零直改。
**不做**(明示去向):
- **不重产任何正式素材**——终稿素材出图归 UI 贴图重构批 / 资产升档批各自立项;
- **不改游戏运行时渲染代码**——样张是判定物不是实现物;**Q3 已裁乙案(shader/实拍路线)**,样张侧 shader 试验件与实拍管线只进样张管线,游戏侧落码另批;
- **不执行格子闸重跑**——格底明度档、数字承载面已随 v3 冻结(art-bible §1.4 L68),整屏样张直接在其上合成;
- **不重裁 §0.6 表内任何已裁项**——尤其微光五组色相(v2 已定稿)、1920 档策略(案甲)、动画帧数(v2 ③冻结)、资产升档(案乙+挂起)、站桩形态与排版(2026-09-20/2026-10-06 两裁);
- **不代裁 08 未决项**——「站桩帧动画进不进 Alpha」(08 §7 第 5 行 L208)、「素材升档重产进不进 Alpha」(第 6 行 L209)、「立绘清晰度回退评估」(第 7 行 L210)三行归各自条,本卡只登记连带,禁以「样张过闸时顺带」名义吃掉(v1.0 把站桩帧动画写成「Beta/后批事项」属定性失实,已订正:它是 08 在册待裁,不是已排 Beta);
- **不动玩法规则与数值**——纯呈现层判定批,MC 零跑(零数值零行为);
- 键盘输入/手柄(08:191 已明列「六 · Alpha 不含」,排 Beta)不涉。
---
## 3. 任务分解
> 估时按 Claude 工作日口径;每卡自带两栏:**相对现状新增什么 / 怎么防重蹈不满意**。**Q1–Q6 已全部裁决(2026-10-16 用户令,见 §7),开工门 U0(用户 `/iter` 发令)后即可按任务序开工;T0 事实坐实段零路线依赖,可先行**。
### T0 事实坐实与旧账处置(≈0.5d)
- 实跑现行 [render_sample_sheet_v3.py](../tools/render_sample_sheet_v3.py) 与 `tools/render_gate.sh`(worktree 内可直接跑,见 P5 两级回退+自动建目录;跑前须防**覆盖在盘产物与机检报告**——OUT_PNG/OUT_REPORT 是硬编码旧文件名 L62-63,开工日一律改出到临时区或加日期后缀,禁写回 `sample-batch-v3-final-2026-09-30.png` 与 `sample-v3-final-机检报告-2026-09-30.md`),确认管线今天仍可出图、A1–A6+F1–F7 全绿基线读数冻结进开工记录(A4 尺寸基线硬等在盘实测成立:立绘 46×48、棋盘小人 32×32);
- P4 死指涉按 **Q5 已裁甲案**处置:T0 实查盘面**定稿具体指哪份代稿**(v31/v32/v33-draft 择一,该实查拍板为本批动作);其落文动作——art-bible:68/:562 与看板:13 三处死指涉改指代稿并注「指代稿」、同族死指涉(§8.2 L490 呈报单死路径)按同案口径一并处置、P3 两处旧锚(art-status-checklist:14 与 06:41 的 §5.1 → 正确锚 art-bible §1.4/§7.2 或 character-design)订正、06:611 行号读数(68/527 → 68/562)订正、战斗表现:83/:116「四区」→「三区 B/C/D」措辞订正(事实源 battle.md:126/:184)——逐条列进 `reports/iter30-反哺点-<完成日>.md`(v3 口径零直改,归文档批落文);新冻结记录按 art-bible §8.3 描述性出处纪律成文;
- §0.5 H1–H11 继承义务清单**逐条复核是否仍然在册**(漂移即订正本表);Q 项已全部裁决(§7),不再随 Q 呈报,清单逐项处置落 T3 冻结记录(契约 7);
- 复核本卡 §0 全部行号与事实,漂移即订正卡片。
- **新增**:开工日可跑性证据+现有机检面读数基线(现状:shot_checker 周期在跑,样张脚本自 2026-09-30 后无跑动记录)。**防不满意**:先验证旧管线还活着、先量出现有机检代码到底判到哪一项,再决定它在新工序里的角色——避免「新工序设计了,旧工具已哑火」或「重复造一套已存在的判据」两种空转。
### T1 方向稿(战斗屏 2–3 张,目检先行)(≈1.5–2d 含 Q3 乙案试验件前闸 0.5d)
- **Q3 乙案前闸(开工第一个动作,半天)**:Godot 引擎实拍+shader 试验件坐实发光类特效能力边界(光带/泛光/呼吸感)——过闸即走实拍目标路线;**试验件不过闸即按 §7 Q3 预设退路退甲案纯代码管线重出(退路预裁定已写入,不回炉问用户,仅留痕)**;
- 战斗屏方向稿 2–3 张:内容骨架按 [battle.md](../design/gdd/ux/battle.md) 现行 B/C/D 三区布局(:126/:184;**战斗表现:83/:116 仍写「四区」系旧措辞,T0 订正**)与 [战斗表现](../design/gdd/systems/战斗循环/战斗表现.md) 一屏样张内容清单(:83——站桩单版〔卡片式已 2026-09-20 裁退,§0.6〕、三语境剪影同图、受击/退场/高光三组动画关键帧条、敌层遮挡对照组),**气质方向分岔**(Q3 已裁乙为主:A 引擎实拍目标形态〔主线〕/ B 实拍+氛围层统一后形态(两派差异在实拍图上直接可见,统一结论呈报落 T3)/ C 代码绘制甲案基线对照张〔试验件不过闸时 C 升主线〕);
- 方向稿张数与气质分岔在 2–3 内自定(2026-10-16 用户令已把三卡各 Q 项全数裁定,方向稿层无待裁项遗留);
- 方向稿允许低成本形态(构图级即可,细节参数不必全冻结),每张附「本方向解决了哪条否决先例」标注(P6/P7 逐条);
- **用户选划 = 人闸**:判完方向才准进 T2;选划记录(哪张、为什么、否决了哪张)登记开工单。
- **新增**:现状无此工序(v1–v3 均为单路线成品一次呈报)。**防不满意**:把「不满意」拦在最便宜的阶段;多路线并呈使用户从「验收者」变「选择者」,气质分歧在方向稿层解决而不是精制品层返工。
### T2 战斗屏精制版 + 双口径断言集(≈2–2.5d,含实拍静态定格工序新建:shot_probe 现出「现状图」,目标构图定格工序为本批新建——§7 Q3 乙案真实成本)
- 按选划方向精制战斗屏 1280×800 整屏样张(1:1 实比);
- 断言集扩展(**先复用后新建**:`tools/shot_checker.py` 的 B/C/D/F 段已承载整屏 ①②④,`game/smoke/shot_probe.gd` 已产 shot_meta.json 坐标源;本批缺口=①的逐点位覆盖(现行 B 段只判 meta 登记的已知文字框三处,禁把「三处」报成「全部文字」)、②的非战斗屏取样(现行 C 段只算战斗屏 C 区/棋盘/舞台三点——**Q2 已裁甲案,本批不动非战斗屏,取样面仅扩战斗屏逐点位**)、③焦点预算(明文归人闸,**禁伪装成机检**)、色板 48 色上限计数(现行 A1a 是「对表圣经冻结色值+禁入带零命中」,**不是 48 色计数**;全仓无 48 色工具,`tools/` 实查零命中,须本批新建,且与 art-bible §8.3 计划的入包色板检查器分工不同——本批只做全图色数计数,不建入包闸);落点扩旧脚本 vs 建新脚本按工程就近原则批内自定):
- **整屏四项**(art-bible §1.4 L64 闸条款,与 §7.2 L416 同源):①全部文字(含菜单/说明/tooltip/按钮)对直接背景 WCAG ≥4.5:1,大字〔≥18px 或加粗档〕底线 3:1、目标 4.5:1;②明度三档带成立(信息面层 > 世界中层 > 世界底层,层间灰度可分);③整屏焦点预算(§3.4 首焦唯一,无第二焦点竞争);④文字禁直接压纹理底(须垫容器或罩层);
- **A1–A6 口径上屏**(脚本 L21-26+L925-1031 现行义,**逐项按实义引,禁改名义**):A1 色板对表冻结色值+禁入带 300°–345° 全图扫描、**A2 拼缝周界闭合(墙↔地墨线带亮度)**、A3/A3b 图底分离 Δ≥30(L23 头注的 Δ≥55 与 L1157 的「std ≥50.9」是旧文本,现行以圣经 §1.4 L68 定值为准)、A4 混排相融(语义色 == ui_kit 常量+在库原件可载+**尺寸基线硬等 立绘 46×48/小人源 32×32**)、A5 画布四缘净空、A6 观感密度梯度均值 ≥4.70;
- **战斗屏专项五项**([战斗表现](../design/gdd/systems/战斗循环/战斗表现.md):85-93:棋盘区零打扰/剪影三语境灰度可辨/三组动画关键帧可读/双舞台战斗空间/敌层插入位置对照组可裁)——与整屏四项的**合体方式已裁乙案:两闸分跑**(专项闸与整屏闸各跑各退,:93 已成文);battle.md:152 另载一条挂在样张上的验收项「徽章不进数字区」,一并入表;
- **H5 复核项(v1.2 新增,承接 §7.5 D1 已裁义务)**:徽章卡 Q2 甲案 provisional 明度档的复核转正+组间互辨抽测(06:431 裁决④保留给样张批的义务),结论随 T3 终审一并呈报、写入冻结记录;
- 生成即验,不过闸不出图(沿用 v3 脚本纪律原文)。
- **新增**:整屏样张判定物本体+③焦点项的判定+逐点位取样覆盖(跨屏取样随 Q2 甲案归后续批)(v1.0 所称「该四项只存在于条款文字、无对应代码」经 v1.1 实查证伪,见 P1)。**防不满意**:机检只拦「可量化的丑」(对比度、抢焦、色板越限),拦不住的部分强制留给 T3 目检——机检绿不豁免终审。
### T3 气质终审(用户目检,闸形 A)(≈0.5d 含往返)
- 精制版 + 断言报告一并呈用户终审;「过」→ 冻结;「不过」→ 按战斗表现判定回退条款分面回炉(演出/构图面回 T1 或 T2 对应项,已过项保留);
- 过闸同时产出三笔裁决记录:①敌人层绘制优先级插入位置(战斗表现:75 登记原句「随美术测试一并裁决,不在本文提前定」保留,清偿时点经 Q6 裁定随本样张一并——T3 即其清偿点);②氛围层两派统一结论(Q3 已裁乙为主:在实拍图上呈报;若方向稿层未完成,此层完成即为最迟期限);③徽章明度档 provisional 复核转正结论(H5,承接 §7.5 D1 已裁义务)。**三笔记录本体写进 `reports/`(实现报告+追认单),其文档落位(战斗表现:75 登记、art-bible §7.6(三) 改写、冻结记录段)列反哺点**。
- **新增**:明确不申请验收豁免(v3 先例有豁免,本批关闭该通道)。**防不满意**:终审语义 = 用户说不过就是不过,无「机检全绿应视为过」的反向论证空间。
### T4 后续三屏排程(Q2 已裁甲案:本卡退役为登记行)(≈0d,06 排队行登记动作并入 T5)
- **执行 Q2 甲案裁定案**:本批仅出战斗屏;关卡/菜单/营地三屏的 **06 排队行登记内容属本批交付义务**(动作列入同步面 T5/§8,随反哺点清单交付、落文归文档批);
- 关卡屏既有件保留为注记(P10):v1 冻结样张已在盘(2026-09-28,机检 11/11),排队行措辞须注明「其后续批=对既有 v1 冻结样张按整屏四项补判,非从零出图」;
- 营地屏连带改实:Q1 已裁丙案(非乙案),「等贴图批终稿」串行分支不发生;营地排队行注明「待本卡目标规格清单反提要求,终稿后再出样」;
- **跨卡次序改实(§7.5 D2/D3)**:三卡串行序位已随 2026-10-16 用户令裁定=徽章→样张→观感,本卡位第 2——观感卡排本卡之后,其 L2/L3 落地对本卡冻结读数的复核归该卡义务,本批不为其预留参数域、不被其阻塞。
- **新增**:现状四屏闸只立了条款、机检面跑过实机帧,但四屏**样张**零张(唯关卡屏有立闸前的 v1 一张)。**防不满意**:逐屏目检逐屏冻结,禁止「一套断言四处套用」把首屏过闸经验未经验证直接外推(本批只判战斗屏,余屏按排队行各自立闸)。
### T5 产出物落位卡(≈0.5d,末卡——三份 reports/ 文件写齐才算收口)
轻闸全绿后、合并前,把本批三份 `reports/` 产出物写齐(权威文档与 06/08/看板零直改;`active.md` 状态记录照常更新):
1. `reports/iter30-实现报告-<完成日>.md`——各卡状态+**实机目检总清单**(T3 终审轮次记录、V1 方向稿三段记录表〔方向稿→选划→精制〕随附)+遗留读数义务(本批冻结基线读数供观感卡对表,§7.5 D2)+变异验证记录表(新建断言段的注入实验记录);
2. `reports/iter30-代拍板追认单-<完成日>.md`——冻结记录段系列编号口径等白名单内代拍项逐条留痕;
3. `reports/iter30-反哺点-<完成日>.md`——§8 同步面每条一落点(哪个文件哪一节、写成什么、依据),其中:
- **art-bible §1.4 冻结记录段全文**(新段,沿 v2/v3 记录格式;**段内系列编号口径属批内代拍**——格子样张序列已用到 v3,整屏样张是否续称 v4 还是自成一列〔关卡屏已用「样张 v1」名〕在冻结记录里一次说清,禁两处各按一种叫法);§0.5 H1–H11 逐项处置写入该段;**随段两件交付物(v1.2 新增):目标规格清单(Q1 丙案,尺寸档/色板/明度档逐件成文)+徽章明度档复核转正记录(H5/§7.5 D1)**——三件全文即反哺点条目的「写成什么」栏;
- art-bible §7.6(三) 氛围层并存条改写为已裁决口径(经 T3 记录);
- [art-status-checklist](../design/art/art-status-checklist.md) 战斗屏行 ✅+余三屏行刷新为「入 06 排队」态;08「五 · 表现」行待做→在役;06 对应条注销(去向登记当批状态记录);**06 为关卡/菜单/营地三屏新立排队行(Q2 甲案交付义务;措辞含 P10 注记「后续批=对既有 v1 冻结样张补判整屏四项,非从零出图」与营地屏「待目标规格清单反提要求」注记)**;
- roadmap 迭代 30 行状态刷新(编入笔已在案,只刷状态);完成定义第 3 条「转正边界条款」与 P11 定性连带注记随 08 行条目交付(防「样张过闸」被误读为占位素材全体转正)。
- **防不满意**:冻结记录段全文逐条写明「本样张冻结了什么、没冻结什么」,后续批对表施工,杜绝各自解释。
**估时合计 ≈5–6d(v1.2 按已裁口径重算)**:Q2 甲案 → T4 退役为登记行(0d);Q3 乙案 → 新增试验件 0.5d(T1 前闸)+实拍静态定格工序新建 ≈0.5d(T2 增量)。T0 0.5 + T1 1.5–2(含试验件 0.5)+ T2 2–2.5 + T3 0.5 + T4 0 + T5 0.5 = **下限 5d、上限 6d**;**若试验件不过闸退预设甲案退路,回退 ≈4.5–5.5d**(扣实拍新建增量,已耗 0.5d 试验件保留)。**软盒拆批线改实**:v1.1 的「四屏全推超 7d 拆两批」分支随 Q2 甲案不再发生——本批 5–6d 在 7d 软盒内单批跑完;若实拍路线超支逼近 7d,仍在 T3 末截断(战斗屏已过闸可单独交付见效),余三屏已列 06 排队行无批内拆分需求。
**估时构成依据(先例出处,v1.1 补、v1.2 沿用)**:整屏四项机检的建造+三裁决呈报=迭代 9 T8 实测 3–4h 量级(.zcode/plans/m3-iter9-loop-plan-2026-09-30.md:65)——故 T2 走「复用+扩面」而非重建,增量只花在实拍定格工序新建;同窗格子样张机检冻结=迭代 9 批 A T1 估 2–3h(同计划书:58);方向稿多轮呈报的先例工时见迭代 26(估 2–2.5d 实际单会话)、迭代 16(估 6.9d 实际单会话)、迭代 13(估 4.8–5.3d)、迭代 29(估 5.5–7d);本批估时主要吃在「方向稿+用户往返目检+实拍管线新建」,roadmap 迭代粒度界定已裁「迭代周期 ≈ 一周左右」(2026-10-11 用户裁定,roadmap.md:101),本批单屏口径恰在一迭代盒内。
天然切分点:T3 末(战斗屏已过闸可单独交付见效)。
---
## 4. 验收(逐任务对应,全绿 + 记录齐备才走 T5)
| # | 需求点 | 测什么 | 落点/判定手段(实存工具,2026-10-16 核) |
|---|---|---|---|
| V1 | 方向稿先行工序 | 每张精制样张有对应「方向稿 + 用户选划记录」在案;无记录直接精制 = 违红线 L3 呈报 | **人闸留痕,无工具可判**(降级为件核:开工单/实现报告附「方向稿 → 选划 → 精制」三段记录表;禁称机检化) |
| V2 | 整屏四项 | ①文字对底 ≥4.5:1 逐点位(大字档 3:1 底线)②三档明度带层间灰度可分 ③首焦唯一 ④无文字裸压纹理 | ①②④=`tools/shot_checker.py` B/C/D 段(+F 段),坐标源 `game/smoke/shot_probe.gd` 产的 shot_meta.json,**须先按屏扩取样点位**;**③=人闸**(shot_checker E 段明文「语义面无法机检」),本批以目检记录判定并留档 |
| V3 | A1–A6 上屏 | A1 色板对表+禁入带全图扫描、A2 拼缝周界闭合、A3b Δ≥30、A4 混排相融(含尺寸基线硬等)、A5 四缘净空、A6 密度 ≥4.70;**另新建 48 色计数**(现行无此工具,art-bible §8.3 入包色板检查器另属他批) | 同上脚本机检段(`render_sample_sheet_v3.py` L925-1031 复用扩展),生成即验 |
| V4 | 战斗屏专项五项 | 按 Q6 已裁乙案**两闸分跑**执行(专项第 5 项只产裁决记录);敌层插入位置随本样张一并清偿,产出裁决记录一条 | 第 1 项借 V2/V3 断言(数字占位区零侵入沿 F5 族);第 2 项三语境灰度可辨**须新建**(可仿 §1.4 验收 2 灰度分类法);第 3/4/5 项=图上元素存在性+判读,**归 T3 目检**;裁决记录(含 H5 徽章明度档复核转正结论)落 T3 |
| V5 | 否决先例映射表 | P6 四条 + P7 两例逐条对到具名断言项(映射底表=脚本 L1156-1160),表格随样张一并归档 | 人工产物,实现报告附件(T2 出表、T3 随终审一并呈) |
| V6 | 用户终审 | 「过」字记录;不过则回炉轮次计数留痕 | T3 人闸(active.md 开工单/状态记录留痕) |
| V7 | 产出物落位 | `reports/` 三份写齐且互一致:反哺点清单 §8 每条有落点(08 行/看板行/06 注销/art-bible 冻结段全文四处对应),边界条款与 §0.5 处置表、06 三屏排队行(Q2 甲案)与目标规格清单(Q1 丙案)内容在册;文档落文与链接/废止词复核归文档批(不进本批域) | 件核:反哺点清单逐条对表 §8;闸面由 `tools/run_all_gates.sh` 按改动域选档承载(唯一闸入口与唯一闸清单,卡内不另列名单) |
**闸口径**:本批零玩法零数值——MC 零跑;批末重闸 = `tools/run_all_gates.sh` 按本批改动域选档(本批触碰 `tools/` 样张面与断言扩面、零 `game/` 运行时改动 → `--code`)全绿才合并;**样张脚本不入门禁常设闸表**(周期件属性,本批零闸件增删),跑动记录留档。卡内不另列闸件名单(脚本即唯一清单)。
---
## 5. 设计契约(红线)
🔴 **契约 1 · 零游戏运行时改动**:本批只产图、只动样张工具面与文档;任何「要改 game/ 代码才能让样张成立」的发现 = L3 停机呈报,改动另批。
🔴 **契约 2 · 方向稿不可跳**:目检先行是闸形(art-bible §1.4 原文),跳过方向稿直接精制 = 本批最高级违例。
🔴 **契约 3 · 卡片不代拍路线**:渲染手段、素材输入级别、四屏范围、字重前提——全部以 Q 项呈用户,批内任何任务禁止预设某路线已成立。**v1.2 闭合**:六项已全部经用户令裁定(2026-10-16 用户令:三卡全部待裁项按推荐方案裁决〔用户将裁权授出,由主线会话代拍板留痕〕,见 §7),本契约转为执法面——各卡按已裁口径执行,批内禁止自行升档、改线或另开路线。
🔴 **契约 4 · 机检不豁免目检**:断言全绿不构成过闸;终审权恒归用户;本批不申请验收豁免。
🔴 **契约 5 · 权威文档零直改(v1.3 换代)**:art-bible §1.4 冻结段、08、06 等一切文档回写义务一律转为反哺点清单条目——**过闸后成文**(未过闸状态下清单内对应条目只许注记「进行中」),用户会话裁决后归文档批落文;实现批唯一可写目录 = `reports/`(`active.md` 唯一例外)。
🔴 **契约 6 · 已裁项不可重开(v1.1 新增,用户红线)**:§0.6 核收表所列事项一律禁止以「样张冻结须总览」「再确认一遍」名义重列备选或再出推荐;本批 Q 项若与 §0.6 任一行相撞,以 §0.6 为准,该 Q 项当场收缩或删除并登记删除依据。
🔴 **契约 7 · 继承义务禁静默丢弃(v1.1 新增)**:§0.5 H1–H11 必须在冻结记录里逐项给「冻结/不冻结+去向批次」;留空即视为本批未完成,禁止以「不在本批范围」一句带过。
---
## 6. 异常分级
- **L1(自救)**:脚本路径/字体回退(素材两级回退失效时改主检出跑)、断言阈值取数笔误、图片命名不合归档纪律、样张产物误写回旧硬编码文件名(T0 已禁)。
- **L2(记录继续)**:方向稿张数在 2–3 内自选、断言实现落点(扩 shot_checker/旧脚本 vs 建新脚本)、精制版像素级微调不触发重目检的边界(构图级 = 需重目检,参数级 = 免)、冻结记录段的样张系列编号口径(见 T5 代拍注记)、**Q3 试验件不过闸 → 按 §7 预设退路退甲案纯代码管线重出(预裁定已成立,留痕即可,禁回炉问用户)**。
- **L3(停机呈报)**:T0 实跑发现 v3 管线或 shot_checker 链已不可跑通且修复超出样张面;方向稿全部被否决(触发 Q1 口径复核呈报——Q1 已裁丙案,改动须重新裁决留痕,禁批内自开重裁);发现整屏断言与格子 v3 冻结参数数学冲突(先例:v3.0 时代 Δ≥55 与明度分档带数学冲突退役);**本卡目标规格清单(Q1 已裁丙案)反提后,素材重产批若发生档位换代,触 A4 尺寸基线(立绘 46×48/小人源 32×32 硬等)变更——圣经 §1.4 L68 明文「资产升档批换代须显式解冻重校」,解冻须走 §1.4 修订,禁批内自改,本批样张侧亦禁预先解冻**;(v1.2 修订:原「Q1 裁乙案但前置批逾期未出终稿」等待场景随丙案裁定不发生,条目删除);**§7.5 跨卡前提冲突**(任一后续卡的前提在执行中被否定——三卡串行序位已裁=徽章→样张→观感,本条保留为序内冲突兜底)。
- **L3 分类结论注(2026-10-17 用户裁 U1 预授权时一并复查,留痕防重复呈报)**:本卡四项 L3 **全部归入「触既有裁决面/超出本批面」类,一律维持停机呈报**——①v3 管线不可跑通且修复超样张面=超出本批面;②方向稿全否=回 Q1 口径复核(Q1 已裁丙案,重裁须用户);③A4 尺寸基线解冻=圣经 §1.4 L68 明文须走修订;④跨卡前提冲突=序位裁定面。本卡无一属于「可自动处置类」,故 U1 预授权对本卡零改动。**两处人闸(T1 方向稿选划/T3 气质终审)同属不可取消项**:契约 2「跳过方向稿=本批最高级违例」、契约 4「机检全绿不构成过闸且本批关闭豁免通道」,取消即拆掉防不满意机制本体。
---
## 7. 裁决记录(v1.2 改实:本卡 Q1–Q6 全部已裁。裁决来源统一措辞逐条留痕:「2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)」;本节保留选项原文+裁定案+一句理由,v1.1 的「不带推荐案、逐条亲裁」呈报框架随用户授出裁权关闭,备选案文字仅存档供对表)
> **v1.3 执行口径注(2026-10-17 文档同步闸 v3)**:本节裁定文中「目标规格清单…落 §1 完成定义 2/T5/§8」「三屏登记 06 排队条的动作列入同步面,写入文档时点=批次出口(T5/§8)」等落文类表述,一律执行为「成文内容随 `reports/iter30-反哺点-<完成日>.md` 交付,用户会话裁决后归文档批落文」——裁定内容(做什么)不变,落文方式随 v3 换代。
| # | 事项 | 备选案与影响 |
|---|---|---|
| **Q1** | **素材输入级别(本卡核心裁点)**:样张用什么料出? | **甲 · 纯现有占位资产合成**:最快(T1 可直接开跑),零前置依赖;代价 = 量的是占位态的屏——素材重产后样张作废须重跑,且「丑」的一半源头恰是占位素材本身,用户不满可能原样复现。**乙 · 等贴图重构批与素材终稿出件后再出样张**:样张一次到位量真料;代价 = 串行依赖两批(UI 贴图重构批 06:21-27 待办;立绘清晰度回退评估 08 §7 第 7 行待裁——**注意:「资产升档重产」不是未裁方向,而是 2026-09-30 已裁案乙+2026-10-04 令暂不做、重启=用户点名,本案只能等其被点名,**禁止代裁****),周期以周计起步,期间「判定尺子没造出来」状态持续;**连带硬账**:素材换代即触 art-bible §1.4 L68「A4 尺寸基线…资产升档批换代须显式解冻重校」,样张的 A4 硬等断言(立绘 46×48/小人源 32×32)须先解冻(走 §1.4 修订),不是零成本串行。**丙 · 样张即设计目标图**:样张承担定稿目标职能,冻结的规格反向给素材重产批提要求(尺寸档/色板/明度档逐件成文,正对 §0.5 H1–H4 的尺寸欠账);代价 = 要求方向稿本身已接近目标气质,用户对既有程序化气质不满时,方向稿的路线选型(Q3)权重陡增;素材批按样张规格返工的工程量未估,**且本案出的「规格建议单」不改变 08 未决项 6/7 的待裁性质(升档与否、回退高清与否仍归各条用户裁)**。**三案可混合**(如战斗屏走甲/丙、营地屏走乙)——混合粒度亦请一并裁定 **〔已裁:丙——2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)〕裁定案:样张即设计目标图,样张承担定稿目标职能,冻结规格反向给素材重产批提要求。理由:唯丙案直接服务立场前提(因丑而改),且消除对已挂起素材闸口的串行等待。任务面同步(v1.2):① 新增交付物「目标规格清单随样张冻结产出(尺寸档/色板/明度档逐件成文)」,落 §1 完成定义 2/T5/§8;② 「三案可混」语义关闭——战斗屏适用丙案,其余三屏按 Q2 裁定(甲案)不在本批,无混合对象;③ 乙案「A4 尺寸基线须显式解冻重校」连带仅于规格清单引发后续素材档位换代时在另批触发(§6 L3 留兜底)** |
| **Q2** | **四屏范围与次序**:本批做几屏? | 战斗屏第一优先的依据已成文(06:37-43「最高优先级」+ 战斗表现:73「一屏样张是硬前置」+ 看板 ⬜ 现状),不复议;剩余 = 关卡/菜单/营地三屏:**甲 · 本批仅战斗屏**,余三屏 06 立排队行;**乙 · 战斗+营地**(营地是全作最暖屏、贴图债最重,Q1 裁乙案时此组合依赖最重);**丙 · 四屏全本批**(按 v1.1 重算估时 ≈8.5–11d,超 7d 软盒,按 T4 拆分点强制拆两批)。**次序连带(v1.1 补,与 §7.5 D2 同读)**:关卡屏已有立闸前的 v1 冻结样张(P10),若排在本批之后且其 L2/L3 换色/重产落地,本批冻结的明度三档带与观感密度读数即作废须重跑——四屏的先后不是纯排期题,是作废范围题 **〔已裁:甲——2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)〕裁定案:本批仅战斗屏;关卡/菜单/营地三屏登记 06 排队条的动作列入同步面,写入文档时点=批次出口(T5/§8)。理由:单批 5–6d 在迭代盒内跑透一屏一闸,胜过四屏平摊超盒。关卡屏已有 v1 冻结样张(P10)事实保留为注记;乙/丙案及其作废范围连带段仅存档不执行** |
| **Q3** | **渲染手段选型**:样张怎么画出来?(用户已质疑 Godot shader 做特效的能力边界——选项、影响、代价列全,已裁见右栏) | **甲 · 纯代码绘制(PIL,现行管线)**:零新依赖、A1–A6 断言体系现成;已知上限 = v1 四否决原因全部产自该路线,氛围类效果(光带/泛光/呼吸感)只能静态模拟。**乙 · Godot 引擎实拍 + shader**:样张=引擎真实渲染(截屏管线先例 **`game/smoke/shot_probe.gd`+`tools/shot_checker.py`**——v1.0 误写为 `tools/shot_probe.gd`,已按实存路径订正;`tools/render_gate.sh` ①段即为该通路),发光/抖动/去饱和与实机逐位一致,氛围层两派并存(§7.6(三) L465)可在实拍层直接看出统一效果;代价 = 全仓 shader 仅 desaturation.gdshader 一枚先例(P9 实测),发光类特效能力边界未验证,须先半天试验件坐实「能不能」再谈「好不好」,且实机依赖动画与光照时序、静态定格取样工序需新建(shot_probe 现按「真实按钮信号路径驱动+双帧抓视口纹理」出帧,无「目标构图」概念——它出的是现状图,样张要的是目标图,这层差距即本案的真实成本)。**丙 · 新素材合成**(贴图批/远程生图件入样张画布):质感上限最高;代价 = 即 Q1 乙案语义,本选项在 Q1 裁甲/丙时不可用。**丁 · 混合**(底板引擎实拍 + 标注层脚本,或方向稿用甲精制版换乙):灵活;代价 = 两套管线双份维护与断言口径分岔。〔氛围层两派统一(平滑 vs 抖动)随本案一并裁:选了乙,两派差异在实拍图上直接可见,裁决成本最低〕 **〔已裁:乙为主、预设甲案退路——2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)〕裁定案:Godot 引擎实拍+shader 为目标路线;开工先半天试验件坐实发光类特效能力——试验件不过闸即退甲案纯代码管线重出。理由:目标图须与实机渲染同语系,而退路预裁定已写入本栏,失败面不再回炉问用户(留痕即可,见 §6 L2)。连带:氛围层两派统一结论在实拍图上呈报、落 T3 裁决记录;丙案即 Q1 乙案语义,随 Q1 裁丙不可用;估时已按本案重算(§3)** |
| **Q4** | **字重与拉丁专件是否入样张前提**:06:29-35「UI 字体补完」条载明现行单字重、层级只能靠字号档差一个手段(art-bible §7.4 L434 字重纪律定的口径是**字号档差〔相邻层级 ≥1.25×〕+墨色深浅+字重两档**三件齐用)——样张用现行单字重出,还是先补字重再出? | 甲 · 现行单字重出样张:零前置;风险 = 样张冻结的层级观感建立在缺一个手段的基座上,字重补齐后层级重排可能追改样张;**另一处连带读数**:§1.4/§7.2 的大字档判据写作「≥18px **或加粗档**」,现行单字重下「加粗档」这一腿在实机上不存在(FS_TITLE 24/FS_H1 34 只吃字号档,§7.4 L432 六档),故本案直接决定整屏①项能不能按原文全判。乙 · 字体补完先行:样张一次到位;代价 = 又添一条串行前置(字体条本身含「补不补拉丁专件、上不上第二字重」未裁点——该未裁点归字体条 06:33,本 Q 只裁先后次序,禁在本卡代裁)。丙 · 样张按「目标字重效果」示意出图(方向稿级),字体批按样张补真件(即 Q1 丙案语义在字体面的特化) **〔已裁:丙——2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)〕裁定案:样张按「目标字重效果」示意出图,字体补完批按样张补真件——即 Q1 丙案语义在字体面的特化,两案口径一致。理由:样张即目标图口径下层级观感不必建在缺手段的基座上,且零串行前置。「补不补拉丁专件、上不上第二字重」仍归字体条自身裁点(06:33),本卡不代裁;甲/乙案文字仅存档** |
| **Q5** | **旧样张死指涉处置**(06:609-615 在册 P0①,本 Q5 已裁,处置落 T0):art-bible **L68 与 L562**(06 原文写「68/527 行」,527 行现为 §9.1 参考表——**行号读数已过期,T0 连 06 该行一并订正**)与看板 L13 仍引用磁盘已不在盘的 `sample-batch-v3-final-2026-09-30.png`;同系列 v0/v2/v31/v32/v33/v34/v35-draft 在盘。 | 甲 · 死指涉改指在盘最近稿并加注「冻结原件失管,指代稿」;乙 · 判过期——旧引用随本批整屏样张冻结记录一并换代重写;丙 · 随本批重跑后新产物自然替代(不做单独修复动作)。〔登记纪律注:art-bible §8.3 L500 归档纪律本就规定主文档禁引用 artwork/ 散文件路径——无论何案,新冻结记录按「描述性出处」写,不再挂散路径;**同条 P0②(主角棋盘小人未走像素管线,重产未在册)属 06 同条另一未裁事项,本卡禁把 P0② 一并吃掉**〕 **〔已裁:甲——2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)〕裁定案:art-bible 68/562 行与看板 13 行三处死指涉改指在盘最近稿 v31/v32/v33-draft 之一并注「指代稿」,具体指哪份由 T0 实查盘面后定;新冻结记录按 §8.3 描述性出处纪律。理由:指代稿保留判定物演进链可追溯,优于判过期换代重写。P0② 与本裁分离,仍归 06 条;乙/丙案文字仅存档** |
| **Q6** | **双口径断言集合体方式**:整屏四项(art-bible §1.4 L64)与战斗屏专项五项([战斗表现](../design/gdd/systems/战斗循环/战斗表现.md):85-93)合并为一张断言集一次判定,还是两闸分跑(先专项后整屏,各自回退语义不同——专项第 5 项只产裁决记录不产过/不过,:93 已成文)? | 甲 · 并集单闸:一次出图一次判定,报告最简;乙 · 两闸分跑:与两文档各自 owner 语义对齐,回退定位更准;代价 = 双份跑批记录。**注(v1.1):本案只裁「两套既有口径怎么合体」,不重裁两套口径本身的内容——四项与五项均是既有条款。** 另附裁:敌层插入位置裁决义务是否随本样张一并清偿(战斗表现:75 登记「随美术测试一并裁决,不在本文提前定」——该义务本就挂在本样张上,本 Q 只裁清偿时点,不裁是否要做) **〔已裁:乙——2026-10-16 用户令:三卡全部待裁项按推荐方案裁决(用户将裁权授出,由主线会话代拍板留痕)〕裁定案:整屏四项与战斗表现专项五项两闸分跑,各自回退语义独立;专项第 5 项(敌层插入位置对照组可裁)只产裁决记录、不产过/不过。理由:两口径各有 owner 文档,分闸回退定位更准。敌层绘制优先级插入位置「随本样张一并清偿」的原句保留(战斗表现:75),清偿点=T3;甲案文字仅存档** |
**开工门(v1.2 改实)**:Q1–Q6 已全部裁决(2026-10-16 用户令:三卡全部待裁项按推荐方案裁决〔用户将裁权授出,由主线会话代拍板留痕〕;v1.1 检索结论——六项当时均未被既有条款裁过、且关闭三处隐性重问(①「微光五组色相是否重冻」归 §0.6/徽章卡 Q2,②「1920 档/帧数规格/资产升档」随闸三裁决已闭,③「敌层插入位置要不要裁」已登记为样张义务)——保留为本次裁决的对表依据)。U0 剩余条件 = 用户 `/iter` 发令。Q3 已裁乙为主:半天试验件置于 T1 最前作前闸,试验件不过闸即按 §7 预设退路退甲案,**不再回炉请裁**(v1.1 原文「复核亦归用户裁」随退路预裁定关闭)。T0 事实坐实段(含 Q5 指代稿的实查拍板)凭本卡即可先行(零路线依赖)。**排期状态**:本卡已编入迭代 30(2026-10-16 用户令,[roadmap](../roadmap.md) 编入行已在案、状态刷新列反哺点);迭代 29 已于 2026-10-16 合入 master(fff4f120,roadmap.md:88 状态=✅ 已入库,见 §7.5 D4),「迭代 29 完成后开工」的前置已满足,但仍不构成排期承诺(见 §0)。
### 7.5 跨卡依赖(v1.1 新增——三卡次序耦合;v1.2 改实:三卡已编入迭代 30,串行序位已随 2026-10-16 用户令裁定=徽章→样张→观感,禁各自假设对方状态)
| # | 耦合点 | 谁的前提 | 次序与理由 |
|---|---|---|---|
| D1 | **类型微光色值与明度档的冻结口径** | 徽章卡(迭代 30 卡①,已入库合并 7ffd1dc0,卡片已退役)Q2 与其 S6 行 | **已改实(2026-10-16 用户令:三卡全部待裁项按推荐方案裁决〔用户将裁权授出,由主线会话代拍板留痕〕——徽章卡 Q2 已裁甲案:明度档取 provisional 值)**:「徽章卡 Q2 先裁」义务随其裁定关闭;**其复核转正义务落本卡样张冻结件**——本卡 T2 新增 H5 组间明度档复核+组间互辨抽测、T3 呈转正结论、写入完成定义第 2 条交付义务(见 §1/§3)。事实核对保留为对表依据:五组**色相**确已随样张 v2 定稿(art-bible §4.2 L218「样张 v2 定稿(2026-09-28)」+HUD框架:140 同记——「样张 v2 已冻结」与 08「战斗一屏样张=待做」并不矛盾:前者是**格子样张**序列(§1.4 L66/L68),后者是**整屏样张**序列(§1.4 L64),两条序列各有其闸),本卡不承接色相重冻义务;「徽章卡若裁乙(等本卡总闸)」分支不再发生。**本卡禁把色相值列进 Q 项**(已按契约 6 关闭) |
| D2 | **棋盘瓦片重产 vs 换色**(素材线同一入口) | [二三关棋盘观感卡](需求卡片-二三关棋盘观感批-2026-10-16.md) Q2(甲 recolor 换色 / 乙 远程生图重产) | **已改实(2026-10-16 用户令)**:序位裁定=徽章→样张→观感、本卡位第 2——观感卡排本卡之后,「同窗呈报两案代价」义务关闭;该卡 L2/L3 落地对本卡整屏②明度三档带与 A6 观感密度读数的复核,属该卡开工时按其 V2(A6 ≥4.70 保持)自跑的复验项,本卡冻结记录注明本样张基线读数供其对表即可;本卡 Q1 已裁丙案(非乙案),与其 Q2 各案不再有工期串行耦合 |
| D3 | **触碰面重叠与合入次序** | 三张卡共同 | 三卡都写 06/08/07/art-bible 版本历史/roadmap/active.md,徽章卡另动 `presentation/views`+冒烟,本卡另动 `tools/` 样张面。按 roadmap.md:93「单迭代串行」与 roadmap.md:101「一迭代 = 一次合并登记」⇒ 三卡禁止三线并行。**已改实(2026-10-16 用户令):三卡串行序位=徽章→样张→观感,本卡位第 2**;「一次合并、批内分波」组织方式随序位裁定确定,v1.1「不预设结论、归用户排期令」呈报框架关闭。**v1.3 注**:三卡文档直写义务已按文档同步闸 v3 全部转反哺点(落 `reports/`),汇聚文件重叠消解,但串行序位裁定不失效——golden 基线与冻结内容的先后依赖仍在(D1/D2) |
| D4 | **门禁语义改动的先后** | 迭代 29 测试分层与门禁语义修正批 | **已结案(2026-10-16 合入 master,合并提交 fff4f120;roadmap.md:88 状态=✅ 已入库)**:该批改的 `tools/run_all_gates.sh`/探针判定/退出码权威语义(其契约 2「三硬闸不可绕过」)已在现行闸内生效,本卡 V7 的闸口径直接按当期语义执行(本批 → `--code`)并按其当期读数采基线;原「该批先行/本卡先行」两种分支随之消解,本卡仍不改写任何判定脚本。(原两分支表述留档供沿革查 git log) |
| D5 | **08 表现表同一表的多行改写** | 三卡+08 v1.6 定稿纪律 | 08 头注 L5 明文「Alpha 内容范围冻结,增删条目须经用户裁决」——三卡都只有**改状态列**的权限,**无一行可新增/删除**;本卡 T5 回写仅动「战斗一屏样张」一行,若需要为新条目动集合,一律 L3 呈报。**v1.3 注**:该「回写」执行为反哺点条目(仅动该行的改写要求照录进清单),零直改 |
---
## 8. 关联文档同步面
> **v1.3 执行口径(2026-10-17 文档同步闸 v3)**:本批**禁写 `design/` 整目录与根规则文件**,唯一可写目录 = `reports/`(`active.md` 唯一例外)。下表「同步义务」列一律执行为「列进 `reports/iter30-反哺点-<完成日>.md`:哪个文件哪一节、写成什么、依据,用户会话裁决后归文档批落文」;成文内容本体(冻结记录段全文、目标规格清单、处置表等)随对应反哺点条目交付。
| 文档 | 关联点 | 同步义务(v1.3 全部=反哺点列清单,另注者除外) |
|---|---|---|
| [art-bible.md](../design/art/art-bible.md) §1.4 | 新增**整屏样张冻结记录段**(编号口径见 T5 代拍注记——格子序列已用 v2/v3、关卡屏自成一列,禁两处各叫各的);段内随附**目标规格清单(Q1 已裁丙案:尺寸档/色板/明度档逐件成文)+徽章明度档复核转正记录(H5/§7.5 D1)**两件交付物;§7.6(三) 氛围层并存条改写为已裁决口径(经 T3 实拍图记录,Q3 乙案);§0.5 H1–H11 逐项处置写进该段;死指涉三处按 Q5 甲案改指「指代稿」(T0) | 反哺点 · 仅 T3 过闸后成文(契约 5) |
| [art-status-checklist.md](../design/art/art-status-checklist.md) | 战斗一屏样张行 ⬜→✅;:14 指针旧锚 §5.1 订正;余屏行按 Q2 刷新 | 反哺点 · 过闸后列清单 |
| [06-待办清单.md](../design/gdd/06-待办清单.md) | 战斗一屏样张条(:37-43)注销(去向登记当批状态记录)+:41 归属栏旧锚订正+:39「尺子还没造出来」措辞按 P1 读数订正;**关卡/菜单/营地三屏新立排队行(Q2 已裁甲案之本批交付义务)**;P0① 死指涉条(:609-615)按 **Q5 已裁甲案**处置(改指指代稿并注)+该行「68/527」行号读数订正 | 反哺点 · 列清单待裁 |
| [08-Alpha版本标准.md](../design/gdd/08-Alpha版本标准.md) | 「五 · 表现」战斗一屏样张行(:158)待做→在役(过闸后);完成定义边界条款注记(样张过闸 ≠ 占位素材全体转正)。**禁动项**:头注 :5 已定稿、增删条目须用户裁;「七 · 未决项」:208-210 三行(站桩帧动画/素材升档/立绘回退)本批一律不改 | 反哺点 · 过闸后列清单 |
| [战斗表现.md](../design/gdd/systems/战斗循环/战斗表现.md) | 敌层插入位置裁决记录登记(Q6 附带,:75/:93 既有义务);「一屏样张的验收标准」节(:79-93)状态刷新;**:83/:116「四区」旧措辞订正为三区 B/C/D** | 反哺点 · 随裁决列清单 |
| [character-design.md](../design/art/character-design.md) | **Q1 已裁丙案**:样张反提的立绘/小人规格(目标规格清单)回写其档位节;H4(§5.3 护甲三档视觉区分)与 H9(钩爪恐魔宽≥高豁免)处置登记 | 反哺点 · 随冻结记录列清单 |
| [HUD框架.md](../design/gdd/systems/表现与支撑/HUD框架.md) | **D1 已改实(徽章卡 Q2 裁甲案)**:本卡承接微光组间明度档复核转正/互辨抽测(H5)义务,按其「唯一事实源」纪律回报结论,定义与口径零复述 | 反哺点 · 义务已成立,结论列清单 |
| `tools/shot_checker.py`/`tools/render_sample_sheet_v3.py`/`game/smoke/shot_probe.gd` | 取样点位与断言扩面(T2);**闸件集合本身不改**(增减只走 `tools/run_all_gates.sh`);样张脚本仍不入常设闸表 | 工程面 · 批内更新(可写) |
| [roadmap.md](../roadmap.md) | 迭代 30 行编入笔已发(2026-10-16 用户令,行已在案);批内状态刷新 | 反哺点 · 列清单待裁 |
| active.md | 状态快照与批次记录 | **本批更新(唯一例外 · 会话状态源)** |
| [07-体验验证清单.md](../design/gdd/07-体验验证清单.md) | T3 目检轮次与后续实机目检衔接项登记(**现行 07 无样张类条目,实查 2026-10-16 零命中——本批为首次登记,属新增条目须走 07 自身纪律**) | 反哺点 · 列清单待裁(目检项另进 reports/ 实现报告目检总清单) |
---
## 9. grilling 审查记录(v1.1,2026-10-16,对抗审查员;逐攻击面给结论/证据/处置)
**审查方法**:卡片每一处引用逐一开文件核行号与措辞;Q1–Q6 逐条全库检索既有条款与裁决(design/gdd/06、08 及其版本历史、design/art/art-bible.md、character-design.md、art-status-checklist.md、systems/战斗循环/战斗表现.md、systems/表现与支撑/HUD框架.md、ux/battle.md、design/research/playnote.md、roadmap.md、active 侧状态记录残留、`tools/` 与 `game/` 实码、git 只读历史);与迭代 30 另两张并行卡逐 Q 比对互斥面。**只编辑本卡,未动任何其他文件;git 仅只读查询。**
### G1 事实引用核实(攻击面 1)
| 引用 | 核实结论 | 证据 | v1.1 处置 |
|---|---|---|---|
| art-bible §1.4 整屏样张闸 | **真** | §1.4 L64 全文(四屏/四项/闸形方向稿先行/执行时机=屏级视觉落码开工前) | 保留并补 L64 行号 |
| art-bible §7.1 占位完成条款 | **真** | §7.1 L411 | 完成定义 3 原写「08 §7.1 指路」**错**(08 无 §7.1),已改指 art-bible §7.1 L411 + 08:158 行 |
| art-bible §7.4 字重三件口径 | **真** | §7.4 L434(字号档差 ≥1.25×+墨色深浅+字重两档)、L432 六档表 | 保留,补 L434;并新增连带读数:「加粗档」在单字重下不存在,直接决定整屏①项可判面(Q4) |
| v3 脚本 A1–A6 | **半真** | 头注 L21-26 确有 A1–A6;**A2 拼缝周界闭合被 v1.0 漏列**;A1 实义=色板对表冻结值+禁入带(L928-930),**不是 48 色计数**;A4 含尺寸基线硬等(L1029-1031);L23「Δ≥55」与 L1157「std ≥50.9」是旧文本(现行定值 A3b Δ≥30,L35 与圣经 L68) | V3 与 T2 逐名义重写,48 色单列为新建项 |
| 「v1 四否决原因」 | **v1.0 只列两条编号,漏 ②④** | 脚本 L1156-1160 映射表:①显示太丑→A6;②封印色冲突→封印黑(A1a);③立体感→A3/F6/F7;④微光格只留微光→F5c;头注 L12-26 仅标 ①③ | P6 补全四条+标注权威表位置;V5 底表指到 L1156-1160 |
| 08 当前行状态 | **真** | 08:158「战斗一屏样张=待做」;:156 UI 贴图重构批待做;:157 UI 字体补完待做;:146 立绘清晰度回退待裁;:154 素材升档待裁;§7 未决项 :208-210 | 保留;「站桩帧动画」原被本卡写作「Beta/后批事项」**定性失实**(实为 08 未决项第 5 行待裁),已订正并入「不做」禁代裁清单 |
| 看板 13 行/§5.1 旧锚 | **真,但 v1.0 漏了 06:41 同型旧锚** | art-status-checklist:14;06:41 | P3 补记;T0 订正面扩为两处 |
| 死指涉行号 | **v1.0 沿用 06:611 的过期读数** | 06:611 写「68/527」;art-bible grep 实测指涉在 **L68 与 L562**,L527 现为 §9.1 参考表 | P4/Q5 改为 68/562,并把 06:611 自身列入 T0 订正面 |
| 2026-10-06 playnote 引文 | **原文被压缩改写** | playnote.md:9 逐字:「现在的立绘太丑了,像素化的粒度太低了,导致根本看不清立绘;看是否可以改回用较为高清的图片?」;日期出处=06:465-471「同日 playnote 立绘批评」 | P7 改逐字引+注明文件本身无日期 |
### G2 「v2 已冻结/样张批冻结候选值/08 待做」三者是否矛盾(攻击面 2)
**结论:不矛盾,v1.0 与并行徽章卡都需把两条序列分开。**
- 格子样张序列:v2 冻结(2026-09-28,圣经 §1.4 L66,四冻结含②色板)→ v3.0 解冻①④ → **v3 重冻生效(2026-09-30,L68,机检 17/17)**;类型微光五组**色相**属②色板面,§4.2 L218 明文「样张 v2 定稿(2026-09-28)」,HUD框架:140 同记「五组色相经样张 v2 冻结」——**冻结为真实现状**。
- 整屏样张序列:条款 2026-09-29 v3.0 才立(L64),**从未出过一张整屏样张判定物,四屏冻结记录零条**——08:158「待做」与看板 ⬜ 因此为真。
- 「候选值,样张批冻结」的出处是 06:431 里 **2026-09-22 那次更新的历史文本**,滞后于 v2/v3 两次冻结;06:431 同时**明文保留**「样张批组间互辨抽测义务」,且**组间明度档值从未定义**——这才是真挂在样张批上的东西。
- **v1.1 处置**:①新增 §0.6 关闭「重裁色相」的可能;②新增 §0.5 H5 承接互辨抽测与明度档;③新增 §7.5 D1 写明徽章卡 Q2 与本卡的先后与理由。
- **另两处状态读数订正(本攻击面的真发现)**:(a) 整屏四项的**机检代码已存在并跑过实机渲染帧**——shot_checker.py 头注自述「整屏样张闸机检(迭代 9 卡⑤/T8 2026-09-30)」,git 053baeee 记「实测 PASS(WCAG 5.79-13.14/三档 204>79>55/骨架四屏过)」,现挂 render_gate.sh ①段周期跑;**③焦点预算 E 段明文「无法机检→人闸」**。v1.0 的「四项从未作为断言集执行」「只存在于条款文字、无对应代码」「本批=该闸首次执行」三句按此改写为「判定物与冻结记录从未出、③从未判」。(b) 新增 P11:§1.4 的执行时机(屏级落码开工前)已被迭代 9/16/25/26 四轮落码越过、Alpha 已于 2026-10-03 到手,§7.1「占位禁止跨里程碑」事实上已被跨——本批定性=**闸后补跑**,冻结语义随之注明,禁写成事前定方向。(c) 新增 P10:关卡屏已有立闸前的 v1 冻结样张(2026-09-28,11/11,产物在盘),Q2/T4/估时三处按「补判四项」而非从零改写。
### G3 「全仓 shader 仅一枚先例」(攻击面 3)
**结论:真。** `find -name *.gdshader` 全仓命中 1 件(`game/presentation/views/desaturation.gdshader`);`ShaderMaterial` 消费面仅 `board_view.gd`(:111 声明/:170-172 创建/:194 参数 tween),`.tscn` 内无 shader 节点;样张与机检面全为 PIL 代码绘制。**处置**:P9 补实测细节;Q3 乙案的「能力边界未验证」措辞保留,另补 shot_probe 出的是「现状图」不是「目标图」这一真实成本(防把「实拍管线已有」误读为「样张管线已有」)。
### G4 Q1 三案依赖链与「混合粒度」(攻击面 4)
- 「UI 贴图重构批」= 06:21-27 待办(Alpha 需完成)+08:156 待做 → **v1.0 读数真**。
- 「资产升档重产批」= **不是未裁**:06:465-471 载明已裁案乙(2026-09-30 迭代 9 三裁决)+2026-10-04 令暂不做(重启=用户点名)+2026-10-06 优先级再降,且 v3.0「档位上调方向候选」已被 v3.7 八敌逐键定档实质完成;08:154/§7 第 6 行的「待裁」只问**进不进 Alpha**。v1.0 把它与「立绘清晰度回退评估」并列为「两个未裁闸口」**不准确** → Q1 乙案改写为「一已裁挂起+一真未裁」,并补 A4 尺寸基线须显式解冻重校的连带硬账(圣经 L68)。
- 「立绘清晰度回退评估」= 08:146 待裁+§7 第 7 行真未裁 → **v1.0 读数真**。
- 「三案可混合」的粒度:全库无既裁边界(样张序列只做整屏闸,从未有文档规定四屏可用不同素材级别),**故保留为请裁项**,不属再问已裁。
- **处置**:Q1 文字改写;新增契约 6/7;「不做」新增禁代裁 08 未决项三条。
### G5 估时 4–7d 的构成依据(攻击面 5)
**结论:v1.0 无出处且加总错误。** T4 自述「逐屏 1.5–2d × 三屏」= 4.5–6d,却把 T4 上限定为 3d;六卡相加实为下限 4d/上限 11d。**处置**:T4 上限改 0–6d,合计改「≈4–11d(单跑战斗屏 4–5d,四屏全推超盒拆两批)」,并补先例出处:迭代 9 T8 整屏机检建造=3–4h(`.zcode/plans/m3-iter9-loop-plan-2026-09-30.md:65`,故 T2 走复用不重建)、迭代 9 批 A T1 样张机检冻结=2–3h(同计划书:58)、迭代 13 4.8–5.3d/迭代 16 6.9d/迭代 26 2–2.5d/迭代 29 5.5–7d(roadmap.md:63/:68/:85/:88),周期上限口径=「迭代周期 ≈ 一周左右」(2026-10-11 用户裁,roadmap.md:101)。
### G6 与另两张并行卡的互斥面(攻击面 6)
**结论:存在三处「一张卡裁了另一张卡前提」的次序耦合,v1.0 完全未写。** 已新增 §7.5 D1–D5:D1 徽章卡 Q2(色值冻结口径)须先于本卡(它决定本卡是否继承色相重冻义务——核查结论:不继承,但继承 H5 明度档与互辨抽测);D2 棋盘观感卡 Q2(重产 vs 换色)与本卡 Q1 指同一条素材线、且其落地会使本卡冻结的明度带/密度读数作废(**双向作废关系,须同窗呈报**);D3 三卡共写 06/08/07/art-bible/roadmap/active ⇒ 单迭代串行纪律下禁三线并行;D4 迭代 29 改的正是本卡 V7 依赖的门禁语义;D5 08 定稿纪律下三卡都只有改状态列权限、无增删条目权限。
### G7 验收 V 条可执行性(攻击面 7)
逐条对 `tools/` 实存脚本核:**V1 无工具**(方向稿留痕不可机检)→ 从「机检化」降级为件核;**V2 ①②④ = shot_checker B/C/D(+F)**,但 B 段只判 meta 登记的已知文字框、C 段只有战斗屏三点 → 标「须先扩取样点位」,**③焦点 = 人闸**(E 段明文);**V3 = 样张脚本机检段复用扩展+48 色新建**(全仓无 48 色工具,grep 零命中);**V4 五项中第 1 项可借既有断言、第 2 项须新建、第 3/4/5 项目检**;**V7 原写「跑 doc 三闸+熵增对基线」违反 AGENTS.md:19/59「run_all_gates.sh 是唯一闸入口与唯一闸清单,文档禁另列清单」** → 改为指路该脚本,并声明本批零闸件增删。附带核实:`game/smoke/shot_probe.gd`、`tools/golden_compare.py`、`tools/golden_baseline_refresh.sh`、`tools/repo_structure_audit.py`、`tools/doc_link_audit.py` 均实存(07 无样张条目为实查所得,已注明本批首登)。
### G8 红线自检:卡片有没有替用户拍板(攻击面 8)
- **发现两处预设**:①目标句把尺子写成「§1.4 + 战斗表现五项的**并集**断言集」,完成定义第 1 条同样预设并集——而合体方式正是 Q6 未裁项 → 改为「两套口径的合体方式归 Q6 裁决(本卡不预设并集或分闸)」。②完成定义第 2 条写死「新增 **v4** 冻结记录段」——v4 这一编号预设了「整屏续用格子序列编号」,而关卡屏已自成一列(「样张 v1」)→ 改为「编号口径属批内代拍,在冻结记录一次说清」。
- **一处定性失实而非拍板**:「站桩帧动画」被写成 Beta/后批事项(实为 08 待裁)→ 已改,并列入「不做」的禁代裁清单。
- **审过判为保留(不属代拍)**:防线三「本批不申请验收豁免」= 本批自我从严的执行纪律,非改动用户裁决;Q2「战斗屏第一优先不复议」= 引用既成文依据(06:37-43/战斗表现:73);§0.5 各 H 项与 §7.5 只呈代价与次序、不给推荐案;Q1–Q6 全条无推荐语(历批「推荐案被推翻」纪律维持)。
- 本批 Q 项清单净变动(v1.1 记录;**六项已全部经 2026-10-16 用户令裁定,见 §7,本节当时呈报的六项全保留口径现为裁决对表依据**):**Q1–Q6 六项全保留**(无一被既有条款裁过,逐条检索见 §0.6 与本节 G2/G4),另关闭本卡内三处隐性重问(色相重冻/随闸三裁决/敌层义务存废),依据已写入开工门。
- 词面规范扫描:v1.1 全文按本次审查指定的十项废止词逐一扫描,初稿命中五处(否定副词一项四处、完成动词一项一处)已全部换代,复扫零命中。
### G9 审查中判定为「本卡无权处置、已登记呈报」的文档面
`tools/render_sample_sheet_v3.py` 头注 L23/L1157 旧口径残留文本;06:39「尺子还没造出来」与 shot_checker 现状有差;06:41/checklist:14 的 §5.1 旧锚;06:611 行号读数(68/527 应为 68/562);**art-bible §8.2 L490 指路 m3-iter9-t8-rulings 文件已在 8e02dcf0 删除(死指涉第二例,属 Q5 同族,处置口径与 Q5 同案在本批一并呈报)**;战斗表现:83/:116「四区」旧措辞;art-bible 头注 L3 仍写「现行为 v3.11」而版本历史已到 v3.14。**以上均为他文件文本,本审查一律未改**,只作为本批 T0 订正面对表登记;其中头注版本号与他文档措辞是否订正,归各文档自身纪律与用户裁决。
> **v1.3 口径换代注(2026-10-17 文档同步闸 v3)**:本节为 v1.1 时点的审查实录,原文不重写;其中「doc 三闸」一类闸件枚举字样与「写入文档/登记 06」类落文表述,按 v3 口径只读为历史记录——闸清单与域划分的唯一出处恒为 `tools/run_all_gates.sh`(本批按改动域跑 `--code` 档),文档落文一律列进 `reports/iter30-反哺点-<完成日>.md` 归文档批。
@@ -0,0 +1,308 @@
# 需求卡片:营地场景图新建批(交互式营地 · 七物件绑定 · 四柜台拆解)· 营地交互重做卡④
- 版本:**v2.2**(2026-10-18 用户令再订正——**本卡留在营地交互重做批次内,不踢出**;前置条件转为批内登记事项逐项销号;🔴 归属纪律:卡只登记缺口与已有裁断,前置由谁解决/何时解决/设计稿与素材由谁产出**由用户定**(美术/设计线=用户自立批,铁律 2),Agent 不代跑不代产——v2.1 曾越权起草点选反馈设计稿,已撤回删除;设计前置闸纪律不变:设计定稿前不进代码实现)
- 来源:[需求澄清-营地交互重做-2026-10-18.md](../design/research/需求澄清-营地交互重做-2026-10-18.md)(唯一事实源:①目标体验原话、②参照与反参照、③非目标、④目标结构树+纵深稿、⑤裁决 5/6/7/8/10、⑥验收方式、⑦切批原则④、⑧遗留)+ [camp.md](../design/gdd/ux/camp.md) v1.5 + [art-bible](../design/art/art-bible.md) §6.2/§7.5
- 归属:呈现层+美术线(`game/presentation/` + 场景素材)——营地交互重做五卡之四,**最大件**
- 排期:未编入(2026-10-18 用户令:需求卡片不预占迭代号,批次归属按工作量另裁)
- 开工门:**前置条件销号后进代码实现**(设计前置闸纪律不变:设计定稿前禁 `/iter` 开本卡代码段——美术素材线按铁律 2 走自立批并行推进,不占迭代位);前置解决清单见下方
## 🔧 状态:在批内 · 前置条件登记待解(2026-10-18 用户令:留在批次里,不踢出)
**背景**:本卡是新内容+新美术件需求,按 2026-10-10 用户立规(req-card 设计前置检查),设计定稿前不进代码实现。v1.x 曾用「待裁点」覆盖设计缺项(渠道/规格/设计稿/参照物),违立规;v2.0 一度按「回设计段」移出序列;v2.1 一度把「批内解决」执行成「Agent 代跑设计稿」——**v2.2 用户令终订:本卡是批内成员,前置条件在批内登记、逐项销号;但由谁解决、何时解决由用户定,美术/设计线是用户自立批(铁律 2),Agent 不代跑不代产**。设计前置闸纪律不变(设计定稿前禁 `/iter` 开本卡代码段),执行方式是「批内销号」而非剔除,也非 Agent 代劳。
**前置条件销号清单**(五项重启条件转为批内登记项):
| # | 前置条件 | 归属 | 状态(2026-10-18) | 解决路径 |
| -- | ------------------------- | -------------------------- | -------------- | ----------------------------------------------------------------------------------- |
| P1 | Q1 美术渠道裁定(A/B) | **用户**(一句话裁) | ⬜ 待裁 | 阻塞场景方向稿与规格路径分支;裁后由用户定推进方式 |
| P2 | 像素规格有着落 | 用户线(裁断已在卡:Q6 甲) | 🟨 半消 | Q6 甲已裁:Q1 裁 A 时用过渡规格(1280 工程档+烛光黄 #F6C667/木色 #8A5A34);终档归样张批冻结清单后置换(反哺点登记)——执行由用户线定 |
| P3 | 点选反馈设计稿(悬停高亮/提示文案/可点区域判定) | **用户线**(美术/设计归用户自立批——铁律 2) | ⬜ 未启动 | 澄清⑧3 已登记缺口;产出方式有备(Q8 甲=出稿呈裁)但**未受命开工**——2026-10-18 曾越权起草 v0.1,已按用户令撤回;待用户方向 |
| P4 | 参照物 | **用户**后续找 | ⬜ 待补 | 找到后与纵深稿对表;结构性冲突=呈报订正构图,禁批内私改 |
| P5 | GDD/art-bible 营地条款落文 | 文档批(P1–P4 定稿后,用户发令) | ⬜ 未启动 | camp.md 整体改版+art-bible §6.2/§7.5/§2.8 改版 |
**批内批次次序(铁律 2:美术素材走自立批、不占迭代位;先产图后改代码)**:P1–P4 销号(设计定稿)→ 场景图美术产出(自立批,素材线并行推进,产物归档 artwork/→game/assets/art/)→ P5 文档落文 → 本卡代码段 `/iter`(与 ⑤ 同波)。工程面 ①②③ 代码在美术线推进期间并行开发、先行交付(③ 进档落点按 Q3 裁定乙暂行接现役 CampOverlay,本卡落地时改挂)——**四卡同在批内,分波收口,不是剔除**。
**归属纪律(2026-10-18 用户令订正,v2.2)**:本卡只负责**登记前置缺口与已有裁断**;前置条件由谁来解决、何时解决、设计稿/素材由谁产出,**由用户定**——美术/设计线是用户自立批(铁律 2),Agent 不代跑、不代产、不自行开工设计稿。本卡曾越权起草点选反馈设计稿 v0.1(2026-10-18),已按用户令撤回删除;Q8(出稿呈裁)仅是「若用户发令出稿时的产出方式」预裁,非开工授权。
**已裁事项(2026-10-18 grilling 轮次)**:
- Q4=甲:最近冒险条带随四柜台拆解撤下,生涯.md P6 同批注销(代拍板留痕);
- Q5=甲:ConfirmDialog 扩第三钮(继续上一段冒险/开始新冒险/取消,cancelled 恒=无变更退回营地);
- Q6=甲:Q1 裁 A 时过渡尺寸档=现役 1280 工程档+烛光黄 #F6C667/木色 #8A5A34 既有规格,终档归样张批冻结后置换(反哺点登记);
- Q8=甲:设计稿产出方式=批内出稿呈裁(方向稿先行纪律照旧——2~3 张低成本方向稿供选划,判完方向才精制);
- Q3 设计稿只覆盖根态点选反馈;进界面后的叠层规则随承载形态裁定派生(独立全屏页=场景根隐藏/单一内页切换=场景根留底)。
**仍待用户裁**:Q1 美术渠道 A/B(我的推荐:**A · CC0 改色**——06:23 已有配色规格、成本低、方向稿不受「从零构图」拖累;B 依赖规格清单输入且周期长。你说过不替你选,但我把推荐摊开了,等你一句 A 或 B,方向稿当天就能出);Q2 参照物(你后续找)。
## 0. 前置依赖与并行性(批内视角,v2.1)
> 本卡在批内,前置条件解决中(见卡头销号清单)——本节描述批内并行关系,非排期承诺。
- 卡③(选档界面)Q3 已裁乙:随①②③工程波先行时进档/新档暂行接现役 CampOverlay——**本卡代码波落地后,营地入口从现役 CampOverlay 改挂场景图,现役 CampOverlay 随之拆解退役**(卡③暂行接线与本次改挂的二次验证面在卡③ T2/实现报告登记)。
- 卡⑤(ESC 浮窗与营地顶栏)落在本批新建的场景屏顶栏位——两卡触碰同一新屏,建议同批或卡⑤随后。**跨卡接口(v1.1 补全)**:①场景屏顶栏位(T2 预留);②**营地刷新单口**(T3 定义:各写口尾→现开界面刷新+场景根 HUD 刷新一闸完成)——卡⑤ HUD 刷新挂该单口,非已退役的 `refresh_camp`;③ConfirmDialog 三钮化与消费方编排(T4,卡③ 契约 3 同款互指);④子界面返回钮承诺(T3)。
- 美术线与代码线的批次关系:T1(素材产出)与 T2–T4(代码)可分批——素材先归档齐、代码后挂(用户批次归属裁,本卡不预占)。
- 样张线关系:**营地屏的整屏样张是 art-bible §1.4 四屏之一,现列 06「待设计」排队行**(样张批 Q2 甲案:本批只判战斗屏,余三屏排队)——本卡**不跑整屏样张闸、不替代样张批**,只按既有约束(§3 契约 7/9)生产与自检;营地屏样张义务留原排队行(反哺点注记)。文档既定序列(排队行措辞「终稿后再出样」)本就终稿先于营地样张,故 T1 终稿落盘不构成违背 art-bible §7.5「前置」条(§5 反哺点已注)。
## 1. 目标与完成定义
**目标(澄清①一句提炼照录)**:营地首页从「文字按钮菜单 + 列表式覆盖层」改为「**一张可点击的营地场景图**」——点场景中的具体物件进入对应功能界面。用户原话照录:「我是希望有一个营地地图的游戏画面;或者是一张营地的图片,跟 UI 的交互是点击图片中的某一处地方,然后再进入界面。不是完全普通的那种 UI 设计,不是各种框框的……我点击某些具体的东西之后,就可以进入对应的操作界面。」(称呼订正:「它就是一个营地的画面;并不是一张地图。」)
**七物件绑定(澄清④结构树照录,逐一落地)**:
| 物件 | 绑定目标 | 现状定性 |
| ------- | -------------------------- | ------------ |
| 营地大门 | 冒险(选路屏/战斗屏已实现,不动;断点弹窗保留移位) | 入口新建+动线迁徒 |
| 锻炉·铁砧 | 锻造工坊 | 界面已实现 · 入口改挂 |
| 宝箱 | 秘宝匣 | 界面已实现 · 入口改挂 |
| 床铺旁笔记本 | 生涯记录 | 界面已实现 · 入口改挂 |
| 木桩 | 树淬炼天赋树 | 界面已实现 · 入口改挂 |
| 布告板/悬赏板 | 奖励格图鉴 | 界面已实现 · 入口改挂 |
| 篝火 | 离开营地/回主菜单 | 新建小动线 |
**纵深稿(用户原话照录)**:「远景是天空;中景是一个围栏,还有营地大门;近景中间是一个篝火;左边是锻炉铁砧;右边是我们的床铺,宝箱等。」
**大门两分支(裁决 5 照录)**:有未完冒险 → 弹「继续上一段冒险 / 开始新冒险」;无未完冒险 → 弹「是否开始新冒险:是/否」。**点大门永远先出确认,不直接进冒险**(「断点续玩也是开始冒险的两个分支之一……它算是开始冒险的一个子节点」)。**「有断点」分支的三出口弹窗形态待裁(Q5)**——现役 ConfirmDialog 双钮表达不了两个肯定性动作。
**钥石余额(裁决 10 照录)**:场景**顶部小 HUD 栏**(用户原话「先按顶部小HUD栏设计」——provisional 措辞留痕;承载落卡⑤)。
**相对现状,新增了什么**:
1. 交互式营地场景图(场景素材+场景屏+七物件命中区与点选交互)——从零新建;
2. 现四柜台覆盖层(CampOverlay)拆解:锻造工坊/秘宝匣/天赋树/奖励格图鉴四界面抽为独立可开界面,入口改挂场景物件;生涯页入口自主菜单改挂笔记本;
3. 大门动线(开始冒险/继续上局两分支+断点确认弹窗从主菜单移位);
4. 篝火回主菜单小动线;场景屏顶栏预留位(卡⑤ HUD);
5. camp 截图断言段与六探针营地段的迁移(**现无 camp 逐像素 golden 基线**——v1.1 订正,见契约 10)。
**完成定义**:
1. 营地首页=可点击场景图;七物件绑定逐一在役,点各物件进对应界面;
2. 四柜台拆解完毕:CampOverlay 覆盖层形态退役,五界面(锻造/秘宝/生涯/天赋树/图鉴)经新入口可达且**功能与写口链路零回归**(presenter 改造=承载面迁移的一部分——见契约 4);
3. 大门两分支确认弹窗在役;点大门不直接进冒险;
4. 篝火可回主菜单;场景屏顶栏预留位就绪(卡⑤联验);
5. camp 截图=场景图形态(迭代内验收=截图对比,澄清⑥);探针断言迁移完毕;
6. 美术约束(48 色板/禁入带/语义色/WCAG)入闸或登记缺口;**用户目检项登记 07**(生命周期末步,不阻塞);
7. 批末重闸按改动域选档全绿;三份 `reports/` 产出物写齐(T6)。
## 2. 现状事实(2026-10-18 实查;开工日 T0 复核行号)
| # | 事实 | 出处 |
| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| F1 | 营地场景图完全不存在(澄清④判定「完全没有 · 新建」);现营地=CampOverlay 四柜台覆盖层(树淬炼/锻造工坊/秘宝匣/奖励格图鉴并排,迭代 21 T6 程序占位重排——代码注释原文「视觉终稿归 HUD 营地视觉批」) | `需求澄清-营地交互重做-2026-10-18.md` §④;`game/presentation/views/camp_overlay_view.gd:86-87` |
| F2 | 营地屏壳(CampScreen)持 CampOverlay 成员;组合根 `main.camp_overlay` 句柄指向屏壳成员(探针挂载假设) | `game/presentation/scenes/camp_screen.gd:8-14`;`main.gd:112` |
| F3 | CampOverlay 结构:顶栏铭牌+钥石徽(:64-84);四柜台并排横滚(树淬炼 :99-109/锻造工坊 :111-137/秘宝匣 :139-159/奖励格图鉴 :161-172);底栏关闭钮+最近冒险条带(:174-189);钥匙门判据读树投影(:287-296);图鉴柜台=结构位预留(:168「内容排 Alpha」) | `camp_overlay_view.gd` 各处 |
| F4 | 五目标界面现状:锻造工坊=CampOverlay 内工作间(`_forge_workbench` 两区六路线);秘宝匣=`_ws_scroll`/`_workshop_holder`(12 件+同调装配段+Y 升级行);天赋树=`_tree_holder`(脉分组行板+Fork 双态钮);图鉴=占位;生涯=**已独立全屏页**(CareerOverlay,入口现居主菜单生涯钮,自带返回钮) | `camp_overlay_view.gd:116-137`/:144-159/:99-109/:161-172;`views/career_overlay.gd`;`main.gd:332` |
| F5 | 营地购买写口链路:视图只发意图信号(`buy_requested`/`tree_buy_requested`/`forge_*` 等),组合根经 CampShopPresenter 转 MetaProgression 写口;投影数据=`camp_shop_presenter.gd:62-72` `camp_data()` 单点 | `camp_overlay_view.gd:8-15`;`camp_shop_presenter.gd:62-72` |
| F6 | 断点确认弹窗现居主菜单开始冒险路径(有断点先出 ConfirmDialog 再开局)——随卡②撤钮整体移交本卡大门 | `main.gd:475-497` |
| F7 | 冒险屏已实现不动:选路屏(LevelMapScreen,`route_chosen` 前进唯一通道)与战斗屏宿住 AdventureScreen;组合根侧:`_start_adventure_from_menu`(:475-484)/`_on_confirm_new_adventure`(:487-492)/`_resume_from_menu`(:518-536)/`_start_adventure`(:579-597)/`build_adventure_params`(:564-574) | `views/level_map_screen.gd:7`;`scenes/adventure_screen.gd:36-37`;`main.gd` 各处(v1.1 行号订正) |
| F8 | 探针面营地段(全部随本批迁移,v1.1 补列):ui_probe(营地入口+余额+秘宝匣 12 行断言 :28-55,深员 `_balance_label`/`_tree_buy_btns`/`_workshop_rows` :39-52)、ui_click_probe(营地购买全链 :53-127;**断点确认段 :500-528**〔经 lvbtn 驱动 ConfirmDialog 取消/开新冒险——被卡②撤钮+本批弹窗移位双杀,v1.1 补列〕)、screen_flow_probe(营地可见态键 :53 直读 `main.camp_overlay.visible`;营地开合 :109-125 回退段直呼 `main.camp_overlay.closed.emit()`;菜单→冒险 lvbtn 步 :130-136)、shot_probe(camp 截图+「关闭营地」钮收闭 :126-133)、ui_struct_probe(camp 结构审计 :41-49;同槽特例断言 :331/:373)、smoke_all(V2 营地屏壳实例化 :170-171;V3g 营地模态开合 :405-435;**camp_overlay_view.gd 源码断言段 :6469-6475**〔三条锁四柜台等高形态本身——`Vector2(0,336)`×3/`SIZE_FILL`×4/`SIZE_SHRINK_CENTER`≥3,随形态退役〕)、ui_contrast_probe(营地令牌段 :48-55〔UiKit 令牌恒等式,不随拆解红;新界面若不再消费 `CAMP_HEADER_BAND`/`CAMP_ROW_PLATE` 则段标签虚挂,须核签〕)、**forge_workbench_test.gd 单测**(:33 直载 camp_overlay_view.gd 并消费 `_forge_rows`/`_forge_workbench`/`open_camp`/`refresh_camp`/三 forge 信号——CampOverlay 一删即红) | `game/smoke/` 各处+`game/tests/unit/presentation/forge_workbench_test.gd:33` |
| F9 | camp UX spec 形态记述将整体退役:三柜台列/顶栏铭牌钥石徽/底栏关闭钮+最近冒险条带(v1.5,事实源声明= camp_overlay_view.gd 实态;条带实述于 :19-20) | `design/gdd/ux/camp.md:14-20` |
| F10 | art-bible 营地条款将失义:§6.2 营地场景「三柜台在烛光下一字排开,钥石余额常驻顶栏」;§7.5 营地界面「三柜台界面画法……视觉终稿以表现层样张过审为前置」;§2.8 承载元素同述 | `design/art/art-bible.md:366-369`/:436-438`/:136-140` |
| F11 | 图鉴内容在册挂起:奖励格图鉴柜台已随配比预设批整体挂起冻结(2026-10-05 用户令,06 在册),重启须用户另行发令——本批只改入口不激活内容 | `design/gdd/systems/跨局循环/生涯.md:63` |
| F12 | 贴图重构批搁置未废:营地与元进度件终稿置换(06:21-27)等交互重做定形后再议(澄清③1/§⑧5)——本批不清偿该债;四柜台拆解后原「柜台场景贴图」债对象变化,随该批重新评估 | `design/gdd/06-待办清单.md:21-27`;`需求澄清-营地交互重做-2026-10-18.md` §③1/§⑧5 |
| F13 | 营地底栏「最近冒险」条带与生涯历史回看同源(同一份 `recent_summaries`),其去留=生涯.md P6 待裁点(期二必答)——CampOverlay 拆解后该条带无处挂,P6 被迫提前面对(本卡 Q4) | `camp_overlay_view.gd:186-189`/:536-549;`生涯.md:69`/:91-101\` |
| F14 | 素材线纪律:`artwork/` 不入 git(`.gitignore:51` 忽略行)——批次 worktree 内无该目录、主工作区 D:/code/g-plan2 实体存在(在途工作区);涉素材脚本须传主区绝对路径否则静默 0 张;素材替换前先归档旧档;终稿归 `game/assets/art/` | `AGENTS.md:32`;`.gitignore:51`;art-bible §8.3 归档纪律(v1.1 行号与表述订正) |
| F15 | 美术硬约束继续有效(澄清③4):明亮轻快像素风、**48 色板、HSV 300°–345° 禁入带、语义色纪律、WCAG ≥4.5:1**——全局约束,不在本讨论范围翻案 | `需求澄清-营地交互重做-2026-10-18.md` §③4 |
| F16 | 像素级规格不在本卡硬定(澄清③5):尺寸档/色板/明度档归「战斗一屏样张批」冻结的规格清单——该批现列 06「待设计」未排期(2026-10-17 用户令自迭代 30 剔除),本卡只写指针并登记依赖(缺口连带裁=Q6) | `需求澄清-营地交互重做-2026-10-18.md` §③5;`design/gdd/06-待办清单.md`(迭代 30 剔除卡②③ 条) |
| F17 | 机检工具面(v1.1 订正):**截屏级 48 色计数不在役**;在役=`tools/palette_check.py`(art-bible §8.3①挂点——48 设计色板令牌+新增色双门)+`tools/standee_asset_check.py`(像素画单张 32 色冻结执法);`tools/render_gate.sh`(shot_probe 七屏→shot_checker 语义断言;golden 段=棋盘三张+menu_boot 四张,**无 camp golden**——shot_checker.py:143 明载「camp/level 走骨架+目检清单」);shot_checker 段=屏级骨架/文字 WCAG/明度三档带/文字禁压纹理/文字在判据 | `tools/palette_check.py`;`tools/standee_asset_check.py`;`tools/render_gate.sh`;`tools/shot_checker.py:143` |
## 3. 设计契约(红线,违反 = L3 停机呈报)
🔴 **契约 1 · 交互式场景图形态**:营地首页=一张可点击的营地场景图,点物件进界面(澄清①)。**禁退回文字按钮列表+面板覆盖层形态**(澄清②反参照:「完全普通的那种 UI 设计」「各种框框」——用户判现状「交互流程完全错误」)。
🔴 **契约 2 · 七物件绑定逐一落地**:大门/锻炉铁砧/宝箱/笔记本/木桩/布告板/篝火七个绑定(§1 表)缺一不可;禁合并、禁以「其他入口」替代(如顶栏文字钮)。
🔴 **契约 3 · 大门两分支**(裁决 5):有未完冒险→「继续上一段冒险/开始新冒险」二选一弹窗(**三出口形态=Q5 待裁**);无→「是否开始新冒险:是/否」弹窗。**点大门永远先出确认,不直接进冒险**;弹窗类=ConfirmDialog(三钮化+消费方编排=T4,卡③ 契约 3 同款互指)。
🔴 **契约 4 · 已实现界面只改挂不重做+presenter 承接面(v1.1 精确化)**:锻造工坊/秘宝匣/天赋树/图鉴/生涯五界面「界面已实现 · 入口改挂」——功能、行板、写口链路零重设计(拆解=承载面迁移)。**presenter 改造=承载面迁移的一部分**:`camp_shop_presenter.gd` 持 `camp_overlay` 句柄(:10)、七条写口尾全部 `camp_overlay.refresh_camp(camp_data())`(:85/93/105/117/129/142/154/168)、`CampFlowContext` 持类型化字段(camp_flow_context.gd:10/22/29)、open/close 编排(:41-56)——**写口语义零改≠presenter 文件零改**:投影目标改线(五界面/场景根)、写口尾刷新改路由、open/close 编排随入口从 campbtn 迁位到卡③进档动作、ctx 字段语义订正、探针缝保缝(main.gd:1163-1171)。改造纪律:`on_camp_attune_toggle`(:98-106)尾只 refresh_camp、不调 `_refresh_presentations`(与其余六口不一致)——**保持原样,禁「顺手统一」防行为漂移**。
🔴 **契约 5 · 图鉴内容保持挂起**:只改入口(布告板),不激活图鉴内容(F11:2026-10-05 用户令冻结,重启须用户发令);布告板点开的图鉴=现行占位态(T3 定义占位壳)。
🔴 **契约 6 · 冒险进行中不开营地**(澄清③6):营地是存档语境(局外)枢纽,现状口径延续;局内只读面=状态面板(在役,本批零改动——其「营地三柜台进度」文案若因拆解失义,列反哺点归文档批订正)。
🔴 **契约 7 · 美术硬约束**:48 色板、HSV 300°–345° 禁入带、语义色纪律、WCAG ≥4.5:1(F15);场景素材全局纹理过滤=Nearest(project.godot 现行默认,像素纪律)。
🔴 **契约 8 · 像素规格不硬定**:尺寸档/色板/明度档只写指针(战斗一屏样张批冻结的规格清单,F16);卡内禁自定像素规格数值;规格清单未产出时的输入缺口=Q6 裁定(禁批内自补、禁 T0 现场发挥)。
🔴 **契约 9 · 迭代内验收=截图对比+终稿落盘口径(v1.1 补)**(澄清⑥):camp 截图须为场景图形态;用户实机目检=生命周期最后一步、统一进行、**不阻塞迭代**——目检项登记 07 清单即完成义务。**T1 终稿落 `game/assets/art/` 的「验收」口径=迭代内验收**(截图对比+shot_checker 机检+方向稿用户选划)——营地屏整屏样张按既定排队行延后(§0),不构成对 art-bible §7.5「前置」条的违背(§5 反哺点注)。
🔴 **契约 10 · 探针断言迁移契约(v1.1 订正,属仓库既有测试纪律的卡内成文,非用户裁决)**:F8 全量位点逐点显式迁移并留痕;**现无 camp 逐像素 golden 基线**(F17:golden 现役仅棋盘三张+menu_boot)——本批不建 camp golden(「把不存在的东西列进迁移清单」禁),camp 截图验收=shot_probe 出图+shot_checker 语义断言段;若要新建 camp golden 须另裁登记(L3)。
## 4. 范围边界
**做**:场景素材产出(渠道按 Q1 裁定);场景屏+七物件命中区与点选交互(反馈细节按 Q3 设计稿);四柜台拆解与五界面入口改挂(含 presenter 承接面改造);大门动线两分支+断点弹窗移位;篝火回主菜单;场景屏顶栏预留位;断言/探针迁移;反哺点清单。
**不做**(明示去向):
- **不做贴图重构批**(澄清③1):柜台场景贴图/钥石顶栏图标/永久强化条目图标的达标化置换——搁置未废,待交互重做完形后重新评估立项(F12);
- 不激活图鉴内容(契约 5);
- 不改五界面功能与写口链路(契约 4);
- 不改冒险屏/选路屏/战斗屏本体(F7 已实现不动);
- 不做整屏样张闸、不替代样张批、不新建 camp golden(§0/契约 10);
- 局内状态面板零改动(契约 6);
- ESC 浮窗与顶栏 HUD 实现 → 卡⑤(本卡只留顶栏位+定义刷新单口);
- 选档界面/主菜单/数据层 → 卡③/卡②/卡①。
## 5. 关联文档同步面
> **v1.3 口径**:本批禁写 `design/` 整目录与根规则文件,唯一可写目录 = `reports/`;下表一律执行为列进反哺点清单。美术素材产物按素材线纪律落 `artwork/`(在途)→ `game/assets/art/`(终稿),不随 git 合并(F14)。
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| `design/gdd/ux/camp.md` | :14-20 布局与交互节(三柜台列/顶栏/底栏)+:10 定位句(主菜单入口)+头注事实源声明(=camp_overlay_view.gd 实态)——四柜台形态整体退役、入口改挂场景物件 | 反哺点 · spec 整体改版重写(形态节退役+新形态成文) |
| `design/art/art-bible.md` | §6.2 营地场景(三柜台一字排开→交互式场景纵深稿);§7.5 营地界面(三柜台画法→五界面画法+场景图画法);§2.8 承载元素;营地屏整屏样张排队行注记(本批不跑闸);**§7.5「视觉终稿以表现层样张过审为前置」条与本批的关系=样张排队行既定延后(终稿后再出样),防文档批误判违例**(v1.1 补注) | 反哺点 · 列清单(权威面零直改,过用户裁决后归文档批) |
| `design/gdd/systems/跨局循环/生涯.md` | :69 与营地边界表(条带 `_rebuild_recent` 随 CampOverlay 拆解去向=Q4);:63 图鉴挂起条(入口改挂注记) | 反哺点 · 列清单(P6 去留随 Q4 裁定) |
| `design/gdd/08-Alpha版本标准.md` | 「三 · 界面」营地行(:104)形态注记改写——状态列可改;注记改写列反哺点;增删行须用户裁(三卡统一口径) | 反哺点 · 列清单 |
| `design/gdd/06-待办清单.md` | 本卡登记条;UI 贴图重构批条(:21-27)注记「四柜台对象变化、重评待交互重做完形」;图鉴挂起条注记 | 反哺点 · 列清单 |
| `design/gdd/07-体验验证清单.md` | 新增实机目检条(场景观感/七物件辨识与点选反馈/大门两分支/篝火动线)——登记不阻塞 | 反哺点 · 列清单 |
| `roadmap.md` | 迭代行编入/状态刷新 | 反哺点 · 列清单 |
| `game/presentation/*`、`game/smoke/*`、`game/tests/**`(v1.1 补——forge_workbench_test 迁移面)、`game/tests/golden/*`(仅棋盘/menu 既有基线复跑)、`game/assets/art/*` | 实现/断言/终稿素材本体 | 实施本体(可写) |
## 6. 任务卡
> 估时按 Claude 工作日口径;每卡出口自跑轻闸;开工日 T0 复核全部行号。**估时主变量=美术渠道(Q1 待裁)、点选反馈设计稿往返(Q3)与规格输入(Q6)**。
### T0 事实坐实与设计输入齐备检查(≈0.5d)
- 复核 §2 全部行号;四柜台界面清单与探针面清单(F8)逐点过;
- 设计输入齐备检查:Q1(美术渠道)/Q2(参照物)/Q3(点选反馈细节)/Q4(条带去留)/Q5(三出口弹窗)/Q6(规格缺口)状态逐项核——**未裁项对应的任务段禁开工**(缺输入=呈报,禁批内自补);
- 规格清单依赖核检:战斗一屏样张批(06 待设计)产出时点 vs 本批排期——按 Q6 裁定执行(禁 T0 现场发挥);
- 与卡③对齐 ConfirmDialog 消费方编排机制(T4 互指)、与卡⑤对齐顶栏位与刷新单口(§0 跨卡接口)。
### T1 场景美术产出(≈2–4d,渠道 A/B 待裁 Q1)
- 按纵深稿构图(远景天空/中景围栏+大门/近景篝火居中/左锻炉铁砧/右床铺+宝箱)出场景图;七物件可辨性=第一合格线(玩家一眼找到点哪);
- 美术硬约束入产线(契约 7):48 色板/禁入带/语义色/WCAG/Nearest;**色板机检二器复用**(palette_check.py 48 令牌+新增色双门/standee_asset_check.py 像素 32 色冻结——v1.1 订正:非「全仓无工具」);
- 尺寸档=样张批规格清单指针(契约 8);按 Q6 裁定执行过渡口径或挂起;
- 产物按素材线纪律落盘(F14):在途 `artwork/`(主区绝对路径)→ 验收后终稿 `game/assets/art/`;替换先归档旧档;**命名纪律**:art-bible §8.3:503(`<域>_<对象键>_<状态|变体>.png`)+doc-conventions §12 三段式「终稿文件名=代码消费名——先定资源路径常量,素材名跟它走,防断链」(v1.1 补指针);
- 终稿落盘「验收」口径=契约 9(迭代内验收三件套);
- **防不满意工序**:场景图先出 2–3 张低成本方向稿供用户选划,判完方向才精制(样张卡「方向稿先行」同型纪律;选划记录三段表进开工单)。⚠ 本条为**本卡自我从严的执行纪律**,非用户新裁决——用户若要以单路线直接精制,从其裁。
### T2 场景视图与点选交互(≈1.5–2d)
- 场景屏承载(camp_screen 屏壳改造 vs 新屏壳——§9 拍板):场景图铺底+七物件命中区;
- 点选交互:命中区判定+反馈形态按 Q3 设计稿(悬停高亮/提示文案/可点区域判定三项);
- **场景屏顶栏预留位(v1.1 注明)**:卡⑤ HUD 落位;**刷新入口=本卡 T3 定义的营地刷新单口**(卡⑤同口挂接);
- **叠层规则显式派生(v1.1 补)**:随 §9 第 2 条承载形态裁定派生并写入 V2 断言——独立全屏页=场景根隐藏(生涯先例);单一内页切换=场景根留底;「缩放虚化」是两选项之外的第三形态(涉新演出面+素材),禁批内自选(若设计稿/用户想要,升格裁点);
- 键盘焦点/手柄不涉(08:191-192 排 Beta;ESC 属卡⑤用户明示裁决面)。
### T3 四柜台拆解与入口改挂(≈2–2.5d)
- 锻造工坊/秘宝匣/天赋树/图鉴四界面自 CampOverlay 抽出为独立可开界面(承载形态=§9 拍板:各自独立全屏页〔生涯先例〕vs 单一营地内页切换——约束=写口链路零改、零新素材);**五界面各带返回/关闭钮**(v1.1 补承诺——现四者共用 CampOverlay 底栏关闭钮随拆解消失,卡⑤ Q1 甲案前提即此);
- 生涯页入口自主菜单生涯钮改挂床铺旁笔记本(CareerOverlay 本体零改);**生涯页返回钮文案禁含「营地」字样**(ui_struct_probe.gd:382 nojump 禁词表含「营地」——career_overlay.gd:27 现「返回」安全,改文案时避坑,v1.1 补坑注);
- 入口改挂后各界面开合走模态栈单口;层序入 `LAYER_CONTRACT`;
- **CampShopPresenter 承接面改造(v1.1 补条,契约 4)**:投影目标改线(五界面/场景根)、七写口尾刷新改路由(经营地刷新单口——**各写口尾→现开界面刷新+场景根 HUD 刷新一闸完成**)、open/close 编排从 campbtn 迁位到卡③进档动作、CampFlowContext 字段语义订正、探针缝保缝(main.gd:1163-1171);改造纪律见契约 4(attune 尾不一致口保持原样);
- **图鉴占位态(v1.1 补条)**:独立界面壳=§9 第 2 条承载形态;文案照录 camp_overlay_view.gd:168 现行锁文,「柜台结构位预留」中『柜台』称谓随形态订正(L2 记录,零新文案);V6 断言锚定新视图占位标签;
- **开层互斥与关层收闭(v1.1 补条)**:营地开层时选档层被模态栈遮挡隐藏(卡③ T2 同口径);篝火/ESC 回主菜单=营地层与选档层同收+开始层恢复(现役 on_camp_closed 模式只视野开始层,选档层不在其视野——须显式);
- CampOverlay 类退役处理(拆解后无消费面即删——吸收即死纪律);`main.camp_overlay` 探针句柄迁移留痕;
- 最近冒险条带去向按 Q4 裁定执行。
### T4 大门动线(≈1–1.5d)
- 大门点击→两分支确认弹窗(裁决 5):有断点=「继续上一段冒险/开始新冒险」二选一;无断点=「是否开始新冒险:是/否」;
- **三出口弹窗形态(Q5 已裁=甲)**:ConfirmDialog 三钮化+**消费方编排**(组合根单实例+待确认消费方状态量:open 前设、confirmed/cancelled 后分派;禁每次 connect/disconnect 漂移、禁双常驻静态接线——卡③ 契约 3 同款互指);
- 断点弹窗自主菜单移位(main.gd:475-497 逻辑整体迁来,卡②已摘除原调用);
- 「继续上一段冒险」接现役续玩编排(`_resume_from_menu` 同源);「开始新冒险」接现役开局编排(`_start_adventure` 同源)——冒险屏/选路屏/战斗屏零改(F7);
- 冒险发起后营地场景屏隐藏;**终局落点不变量(v1.1 补)**:现役口径=终局 continue 回主菜单(main.gd:703)——若后续改落点为营地,营地语境可能出现未收束会话,卡⑤「返回主菜单」动线须补 `_begin_session(false)`,两卡 T0 互证;
- `_refresh_resume_button` **不复用**(大门两分支直读 `has_breakpoint`,无钮可刷——v1.1 明示,函数随卡②删,防两卡互以为对方在处理)。
### T5 断言、探针与 golden 迁移批(≈2–2.5d)
- shot_probe:camp 截图路径改(进入存档→选档→进档→营地场景图);截图自检存在且非空;**camp 段收闭改缆(v1.1 补)**:现经「关闭营地」钮收闭(:133)——营地根态无关闭钮(出口=篝火/ESC),改篝火动线或调试直改 visible;
- **无 camp golden**(契约 10):camp 验收=shot_probe 出图+shot_checker 语义断言段(文字 WCAG/明度三档带/文字禁压纹理/文字在判据扩 camp 取样面);棋盘/menu 既有 golden 复跑;
- F8 全量位点逐点迁移(v1.1 补列项):
- **探针深员改指表**:ui_probe `_balance_label`/`_tree_buy_btns`/`_workshop_rows`(:39-52)、ui_click_probe `_tree_buy_btns`/`_tree_fork_btns`+三处 `main.camp_overlay.refresh_camp(main._camp_data())` 直呼(:72/99/110)、ui_struct_probe audit 根(:45)——「改挂新入口」不够,这些是成员级耦合;七命中区与笔记本命中区的探针寻址名随 T2 命名稳定化一并定;
- **smoke_all:6469-6475 源码断言段**:三条锁四柜台等高形态本身——按新形态重写或注销(四栏等高纪律是否迁入新界面=§9 第 2 条裁后定);
- **ui_click_probe:500-528 断点确认段**:改走大门路径断言(与 V3 合并或互指;卡② T2 明列移交、本卡 T5 接收);
- **ui_contrast_probe:48-55 营地令牌段**:核签(新界面仍消费 `CAMP_HEADER_BAND`/`CAMP_ROW_PLATE`=段留;不再消费=段随注销);
- **forge_workbench_test.gd 单测**:随锻造视图抽出同迁(断言零改、只换承载类);V4 复跑清单补该单测;
- **生涯段驱动改缆**:ui_struct_probe:54-69 与 shot_probe:103-124 现经 `_start_overlay`「生涯」钮驱动——改挂后须合成点击场景笔记本命中区;命中区若为 TextureRect/Area2D 而非 Button,`ProbeUiUtil.find_button` 失效,寻址面随 T2 扩展;
- **screen_flow_probe 营地键新语义**::53 改指新场景根句柄;子界面开态时键真值按 T2 叠层规则派生;:119-125 回退段改新场景根 closed 信号或篝火动线;
- **多卡共改文件分界**:screen_flow_probe(入口路径段归卡②、键语义/开合/篝火段归本卡)、ui_click_probe(入口路径归卡②、槽操作路径归卡③、营地段+断点确认段归本卡)——每条探针注分界;
- 新增断言段:七物件逐一可达对应界面;大门两分支;点大门不直接进冒险;**点大门→开局后营地场景屏隐藏(v1.1 补)**;图鉴=占位挂起态;场景根态无文字按钮列表/无四柜台面板(反参照纪律断言);
- 美术约束机检:shot_checker 现役段扩 camp 取样;截屏级 48 色计数是否新建=§9 第 5 条拍板(依赖样张批规格清单,随 Q6 一并裁);
- **变异验证伴生**:某物件命中区漏绑(预期可达性断言红)、大门直连开局绕过确认(预期分支断言红)、图鉴内容激活(预期挂起态断言红)、**presenter 某写口尾漏挂新界面刷新**(预期余额/HUD 不同步红——v1.1 补)、**三钮弹窗取消被接成写档动作**(预期无变更退回红——v1.1 补);注入→最窄闸见红→精确还原→记录。
### T6 产出物落位卡(≈0.5d,末卡)
三份 `reports/` 写齐(实现报告含方向稿选划记录三段表、探针迁移留痕表、变异记录表、目检总清单/代拍板追认单/反哺点清单)。
**估时合计 ≈9–12d**(v1.1 上调:presenter 承接面+三钮弹窗+坏槽态联动+探针深员面增量)。**天然切分点=T1 出口**(场景素材归档齐)——美术线与代码线可分批交付(用户批次归属裁);若单批跑超迭代盒,T3 末(四柜台拆解完)为次切分点。
## 7. 验证闸(逐需求点验收清单)
| # | 需求点 | 测什么 | 落点/判定手段 |
|---|---|---|---|
| V1 | 场景图形态(机检半) | camp 截图=场景图形态(非四柜台覆盖层) | shot_probe camp 截图+shot_checker 结构禁词(与 V9 同)——**「七要素可辨(构图)」归 V11 目检**(v1.1 拆半:shot_checker 不判构图) |
| V2 | 七物件可达性 | 点每物件→对应界面可见+营地场景按 T2 叠层规则退避 | ui_click_probe 七段合成点击(新断言;命中区寻址面随 T2) |
| V3 | 大门两分支+开局收闭 | 有断点=弹二选一;无断点=弹是否开始;点大门不直接进冒险;点确认开局后营地场景屏隐藏 | 探针合成点击+状态断言(夹具经调试接口直写/清断点) |
| V4 | 五界面功能+写口链零回归 | 树购买/Fork 切换/锻造三意图/秘宝购买/同调装配/图鉴占位——既有断言全链复跑绿;presenter 各写口尾的 MetaProgression 原语调用序列不变(v1.1 扩) | ui_click_probe 迁移段+smoke `_face_snapshot` 段+forge_workbench_test 迁移复跑 |
| V5 | 生涯只读契约保持 | 生涯页经笔记本可达;页内零跳转零动效契约不破(三契约只约束页子树、不依赖入口位置——v1.1 证实原样成立) | ui_struct_probe career 段迁移复跑 |
| V6 | 图鉴挂起态 | 布告板→图鉴=占位态;内容零激活 | 探针禁词/禁行断言(锚定新视图占位标签) |
| V7 | 篝火动线 | 点篝火→营地隐藏+选档层同收+主菜单可见 | screen_flow_probe 型断言 |
| V8 | 顶栏预留位 | 场景屏顶栏 HUD 位存在(卡⑤联验填值+刷新单口挂接) | 结构断言+跨卡联验 |
| V9 | 反参照纪律 | 营地根态无文字按钮列表、无四柜台面板 | ui_struct_probe 结构禁词断言 |
| V10 | 美术约束 | 文字 WCAG/明度三档带/文字禁压纹理底;素材色板(palette_check/standee 二器或截屏计数若建) | shot_checker 段扩 camp 取样+§9 第 5 条拍板面 |
| V11 | 目检项登记 | 场景观感/七物件辨识(纵深稿构图可辨)/点选反馈/大门两分支/篝火动线入 07 | 件核(登记不阻塞,澄清⑥) |
| V12 | 探针迁移留痕核验 | F8 全量位点逐点有「改前→改后」记录(契约 10 留痕义务) | 件核对表(T6 追认单) |
| V13 | 反哺点清单 | §5 每条有落点 | 件核对表 |
**测试方式两分法**:V1–V10、V12 机检自动化(能力验证经调试接口直改断点/钥石/解锁状态,沿用 DebugOverlay/DS_DEBUG 门控);V11 归用户目检(生命周期末步统一进行,不阻塞迭代)。
**闸口径**:轻闸每卡出口自跑;批末重闸按改动域选档(本批碰 `game/` 代码/断言/终稿素材 → `--code`)全绿才合并;MC 零跑(零数值零行为——纯呈现+承载迁移)。
## 8. 异常分级
- **L1(自救)**:断言写法、探针路径、命中区微调、命名。
- **L2(记录继续)**:场景屏承载形态选择(§9 域内)、点选反馈参数(Q3 设计稿域内)、四界面承载形态(§9 域内)、方向稿张数在 2–3 内自选、图鉴占位文案称谓订正。
- **L3(停机呈报)**:Q1–Q6 未裁即需开工对应任务段;规格清单(样张批)晚于本批且 Q6 未裁;golden 漂移越出预期面(若涉及既有棋盘/menu 基线);发现五界面任一功能/写口链路被意外触碰(契约 4 破);参照物到手后与纵深稿结构性冲突(呈报,禁批内自行改构图);美术渠道 A/B 执行中撞墙(如 CC0 改色达不到七物件可辨性);提议新建 camp golden(契约 10——须另裁)。
## 9. 代拍板白名单(超清单必呈报)
1. 场景屏承载形态(camp_screen 屏壳改造 vs 新屏壳)——约束:`LAYER_CONTRACT` 更新+探针挂载面迁移留痕。
2. 五界面拆出后的承载形态(独立全屏页 vs 单一内页切换)+**叠层规则派生**(v1.1:独立全屏页=场景根隐藏/单一内页切换=场景根留底;写入 V2 断言;「缩放虚化」禁自选)。
3. 七物件命中区实现(TextureRect 分区 vs 其他)与点选反馈参数(Q3 裁定域内)。
4. 篝火是否需二次确认——默认直回(营地每笔消费即时写盘,无未保存风险——存档序列化.md:121);如判需确认,走 ConfirmDialog 先例。
5. 截屏级 48 色计数工具是否新建及落点(现役=素材级二器,F17;截屏级依赖样张批规格清单,随 Q6 一并裁)。
6. CampOverlay 类退役范围(整类删 vs 留片段)——约束:吸收即死,禁留死代码。
7. 提交切分与 worktree 分支命名。
## 10. 裁点与设计议程(v2.1:本卡在批内,以下为前置解决议程)
> Q4/Q5/Q6/Q8 已裁(裁定见卡头);Q1/Q2 仍待用户。本节约等于批内设计段的工作清单。
### Q1 · 营地场景图的美术渠道(**仍待用户裁——批内第一议程,阻塞 P2 规格分支与方向稿**)
**背景**:澄清⑧2——「美术渠道 A/B 未裁:CC0 改色 vs 插画级新产——原贴图批的渠道问题对营地场景图同样成立,本讨论未裁决」。
**我的推荐:A · CC0 改色**(理由:06:23 已有配色规格〔烛光黄 #F6C667 配木色 #8A5A34〕与渠道合法性记载、零新绘成本、方向稿不受「从零构图」拖累;B 依赖尚未冻结的规格清单且周期长)。用户此前令不代裁——推荐已摊开,等你一句 A 或 B,方向稿(T1 防不满意工序)当天可出。
| 案 | 内容 | 代价 |
|---|---|---|
| A · CC0 改色 | 通用场景素材改色复用(06:23 载明该渠道对营地件合法:烛光黄 #F6C667 配木色 #8A5A34 已有规格) | 快、零新绘成本;上限=改色件构图不完全贴合七物件+纵深稿,可能要容忍「近似构图」 |
| B · 插画级新产 | 按纵深稿全新绘制(像素级) | 七物件与构图完全受控;成本高、周期长,且依赖规格清单输入(F16)——须走「等样张批规格清单」或用户另裁过渡规格 |
连带:渠道裁定影响 T1 估时(A 趋下限、B 趋上限)与切分点位置;「归建卡时或样张批规格语境下裁」(澄清⑧2 原文)。
### Q2 · 参照物(**待补输入**)
澄清②/§⑧1:用户原话「目前还没有一个参照,我可以后续找一下」——参照物找到后补充进本卡(与纵深稿对表,结构性冲突=呈报,禁批内自行改构图)。
### Q3 · 物件点选反馈细节(设计稿产出方式已裁=批内出稿呈裁)
澄清⑧3:「悬停高亮/提示文案/可点区域判定」未谈。三项形态归设计稿阶段——**产出方式已裁(Q8=批内出稿呈裁,方向稿先行纪律照旧)**;设计稿只覆盖根态点选反馈,不覆盖进界面后的叠层规则(叠层=随承载形态裁定派生:独立全屏页=场景根隐藏/单一内页切换=场景根留底;「缩放虚化」是第三形态,涉新演出面+素材,禁批内自选)。
### Q4 · 营地底栏「最近冒险」条带去留(**已裁=甲**)
**裁定(2026-10-18)**:甲——随四柜台拆解一并撤下,逐局历史回看整体归生涯(期二承接);生涯.md P6 同批注销(反哺点)。代拍板留痕(用户令「事项按推荐的来」,本项无推荐案,取默认甲=分工矩阵干净、逐局历史只剩一个权威呈现面;追认单可 veto)。
### Q5 · 大门「有断点」分支的三出口弹窗形态(**已裁=甲**)
**裁定(2026-10-18)**:甲——ConfirmDialog 扩第三钮(继续上一段冒险/开始新冒险/取消,cancelled 恒=无变更退回营地)。推荐案,用户令按推荐执行。连带:卡③ 契约 3 已按三钮化落定(删档确认只用取消/确认);类签名变更随本卡重新立卡时的实现落地,卡③ T0 对齐。
### Q6 · Q1 与规格清单缺口的连带裁(**已裁=甲**)
**裁定(2026-10-18)**:甲——Q1 裁 A 同时订过渡口径:「过渡尺寸档=现役 1280 工程档+烛光黄 #F6C667/木色 #8A5A34 既有规格;终档归样张批冻结后置换(反哺点登记)」。推荐案,用户令按推荐执行。若 Q1 裁 B(插画级新产),过渡口径不成立——B 依赖规格清单,须走乙案「T1 等样张批规格清单产出才开」或用户另行裁定过渡规格。
---
**修订记录**:v1.0→v1.1(2026-10-18 grilling 子 Agent 对抗审查回写)——事实订正 6 处:E1「48 色工具全仓不在役」→截屏级不在役/素材级二器在役(F17/§9-5/V10/T5 连带);E2「camp golden」五处不存在→删并立契约 10 不建;E3 F7 行号(_start_adventure :579-597 等);E4 F14 .gitignore:51+「恒无」表述订正;E5 存档序列化 :122→:121(卡⑤同订);E6 行号微漂(ui_struct_probe :41-49、smoke_all :170-171、camp.md :19-20)。自扩订正:契约 10 标仓库纪律成文。卡内可收 15 项:presenter 承接面(T3/契约 4)、叠层规则派生(T2/§9-2)、ConfirmDialog 消费方编排(T4)、生涯探针驱动改缆+返回钮文案坑(T3/T5)、图鉴占位态(T3)、screen_flow 键新语义(T5)、HUD 刷新单口(T2/T3)、深员改指表(T5)、源码断言段重写(T5)、shot_probe 收闭改缆(T5)、forge_workbench_test 迁移+§5 补 tests 可写面(T5/§5)、断点确认段补列(F8/T5)、contrast 段核签(T5)、素材命名指针(T1)、终稿落盘口径(T1/契约 9/§5)。跨卡对齐:HUD 刷新挂点(§0 接口+卡⑤订正)、ConfirmDialog 类事实双向失效(Q5)、开层互斥/关层收闭(T3+卡③ T2)、探针文件分界(T5)、`_refresh_resume_button` 不复用(T4)。验收补:V1 拆半、V3 扩、V4 扩、V12 留痕行、变异补二条。新增待裁点 Q5 三出口弹窗、Q6 规格缺口连带;估时 8.5–11.5d→9–12d。用户面裁决(①④⑤裁决 5/10)零改动。
@@ -0,0 +1,202 @@
# 需求卡片:选档界面新建批(3 存档位 · 新档/进档/删档)· 营地交互重做卡③
- 版本:**v1.2**(2026-10-18 grilling 轮次裁定回写——Q1 裁定甲(每轮回选档,代拍板留痕)、Q2 裁定甲(坏槽按空槽,推荐案)、Q3 裁定乙(进档暂行接现役 CampOverlay——卡④同日回设计段迫使);契约 3 落 ConfirmDialog 三钮化定局(卡④ Q5 裁定甲);用户面裁决照录澄清文档不变)
- 来源:[需求澄清-营地交互重做-2026-10-18.md](../design/research/需求澄清-营地交互重做-2026-10-18.md)(唯一事实源:④结构树「选档界面(完全没有 · 新建):3 存档位,新档/进档/删档」、⑤裁决 2/3/4、⑦切批原则③)
- 归属:呈现层/组合根(`game/presentation/`)——营地交互重做五卡之三
- 排期:未编入(2026-10-18 用户令:需求卡片不预占迭代号,批次归属按工作量另裁)
- 开工门:U0(用户 `/iter` 发令)+ 待裁点已裁(Q1/Q2/Q3 均裁定,见 §10)+ grilling 复核门过
## 0. 前置依赖与并行性
- 前置卡①(存档制数据层改造批):三槽承载、新档/进档/删档原语、摘要三项窥视读器——本卡只做界面与接线,不碰数据层实现。
- 后接卡④(营地场景图):进档/新档的落点。**卡④已于 2026-10-18 回设计段(美术设计定稿未过 2026-10-10 设计前置闸——见卡④ 卡头回退声明)**,故 Q3 裁定乙:本卡随①②③工程批先行时,进档/新档**暂行接现役 CampOverlay**(现役在役面,复用合法,非「发明占位」),卡④设计定稿重新立卡后改挂场景图(卡④ T3 承载)。
- 卡②(主菜单三入口化)的「进入存档」钮以本卡为落点,两卡硬耦合(卡② 契约 5:同批或卡③在先)。
- 卡⑤(ESC 浮窗)在本卡语境不响应(卡⑤ 契约 2:ESC 范围=营地语境)——选档语境的键盘行为零裁定、零实现。
## 1. 目标与完成定义
**目标(澄清④照录)**:新建选档界面——3 存档位,新档/进档/删档。裁决 2「多存档制,3 个存档位」;裁决 3「删档:要,且必须二次确认」;裁决 4「档槽摘要=钥石余额、通关次数、冒险次数(总局数)三项,不含未完冒险进度」。
**相对现状,新增了什么**:选档界面整体(澄清④判定「完全没有 · 新建」)——三槽呈现+摘要三项+空/有档操作集+删档二次确认链+进档激活接线。
**完成定义**:
1. 选档界面经「进入存档」钮可达,呈现 3 个存档位;
2. 每槽摘要=钥石余额/通关次数/冒险总局数三项;空槽=合法零值态;坏槽/高版本槽按 Q2 裁定呈现;**摘要面无未完冒险进度**(裁决 4);
3. 空槽可新档(创建=激活=**暂行接现役 CampOverlay**——卡④回设计段,Q3 裁定乙);有档槽可进档(激活该档=暂行接现役 CampOverlay);
4. 删档必经二次确认(裁决 3):第一次点击只出确认窗,确认才删、取消不删;删后该槽回空态;
5. 新屏/新层入 `LAYER_CONTRACT`(层序纪律),冒烟合同断言绿;
6. 批末重闸按改动域选档全绿;三份 `reports/` 产出物写齐(T4)。
## 2. 现状事实(2026-10-18 实查;开工日 T0 复核行号)
| # | 事实 | 出处 |
|---|---|---|
| F1 | 选档界面完全不存在(澄清④判定);现主菜单直接进营地/生涯/冒险,无存档语境选择面 | `需求澄清-营地交互重做-2026-10-18.md` §④ |
| F2 | 通用确认弹窗在役:`ConfirmDialog.open(text, confirm_label, cancel_label)` 双钮外发 `confirmed/cancelled`(**信号零 payload、无调用方标识**),零业务触碰;现役唯一生产消费=组合根静态常驻接线;打开走 `confirm_dialog.open()` **直开,不经 `_open_modal`**(全仓唯一绕栈模态) | `game/presentation/views/confirm_dialog.gd:36-38`/:7-8/:55-60;`main.gd:347-348`/:480 |
| F3 | 全屏页壳先例在役:`UiKit.page_shell`(暖亮底+石纹+暗角+56px 通栏顶条+内容列),生涯页即此形制(直开直关零动效;页壳自带「返回」钮) | `game/presentation/views/career_overlay.gd:18-31`/:62-72 |
| F4 | 钥石徽工厂件在役:`UiKit.keystone_badge`(状态面板/生涯页/营地三处消费先例;迭代 17 卡③ Q10 甲工厂化) | `career_overlay.gd:54`;`camp_overlay_view.gd:82`;`status_panel` 同族 |
| F5 | 层序唯一事实源=`main.gd` `LAYER_CONTRACT`(16 层+float 类),`_apply_layer_contract` 为全仓唯一落位口;冒烟 V1d 源码断言判红散落 `move_child` | `main.gd:34-53`/:430-455;`smoke_all.gd:146-154` |
| F6 | 模态栈单口在役:`_open_modal`/`_close_modal`(登记层开合一律走栈;T3 收口批纪律) | `main.gd:458-462` |
| F7 | 摘要三项读源:现役单档访问器(`keystone_balance`/`adventure_total`/`adventure_cleared`,save_manager.gd:214/258/264)+**按槽窥视读器=卡① T2 交付物(未实现)**;「通关次数」口径=**通关局数 `adventure_cleared`**(同生涯页行,卡① F4 已锁——禁与「各关通关次数 clear_count」混义) | `save_manager.gd:214`/:258/:264;卡① §6 T2 |
| F8 | UI 公共件纪律先例(迭代 17 卡③):「复用现行公共件与色板,零新素材零新色值」——本卡同类批,照此执行 | `roadmap.md` 迭代 17 ③行 |
## 3. 设计契约(红线,违反 = L3 停机呈报)
🔴 **契约 1 · 三存档位且仅三位**:界面呈现 3 槽(裁决 2);禁参数化槽位列表、禁滚动长列表形态。
🔴 **契约 2 · 摘要三项且仅三项**:钥石余额/通关次数(=通关局数 `adventure_cleared`)/冒险总局数(裁决 4)。**禁显示有无未完冒险**(用户原话「不需要显示有无未完成的冒险;只要我提到的那三个就够了」)——断点相关读数(关数/种子/停点)零露出。
🔴 **契约 3 · 删档必经二次确认+ConfirmDialog 消费方机制(v1.2 落定:类将三钮化)**:第一次点击只出确认窗(复用 ConfirmDialog 类),确认才删、取消不删;禁长按删、禁一次点击即删、禁撤销式软删。**该类现为双钮零 payload 单实例,将有三个消费方**(现役新冒险确认〔随卡②退役〕、卡③删档确认、卡④大门两分支确认)——组合根须实现「打开时指定消费方」机制(待确认消费方状态量:open 前设、confirmed/cancelled 后分派;或信号带用途载荷),**禁双常驻静态接线**(现役 main.gd:347 形态禁复制——双线必致删档确认误触发开局)。**三钮化已定局(2026-10-18 卡④ Q5 裁定甲)**:类将扩为「确认/取消/第三钮」形态(第三钮语义随卡④大门裁后落),本卡删档确认只用取消/确认两钮;类签名随卡④重新立卡时的实现落地,本卡 T0 对齐。
🔴 **契约 4 · 空/有档操作集二分**:空槽只有「新档」;有档槽有「进档」+「删档」(澄清④语义)。**禁给空槽配删档**(含置灰残留——置灰=配删档);「想在这个位开新局」的玩家路径=先删档(二次确认)→槽回空→新档,两步即达,卡内记载备查(实现期禁自发加「覆盖」钮——覆盖式新档用户未裁);坏槽/高版本槽的操作集=Q2 裁定,不属本二分。
🔴 **契约 5 · 选档面零存档内功能**:选档界面只做存档语境选择——禁从此面进营地/冒险/生涯(结构树层级:选档 → 进档 → 营地);禁在选档面放任何购买/查看入口。
🔴 **契约 6 · 层序与模态纪律**:新层入 `LAYER_CONTRACT`(改层序只改合同表);开合走模态栈单口。**豁免(v1.1 补)**:ConfirmDialog 沿用现役直开先例(main.gd:480——登记在册:输入锁与树序顶位已由 LAYER_CONTRACT 表达),不强制改走 `_open_modal`。
🔴 **契约 7 · 公共件复用**:UiKit 工厂件+现行色板,零新素材零新色值(迭代 17 卡③ 先例同款);场景图归卡④,本卡不碰美术产出。
🔴 **契约 8 · 进档即激活**:进档/新档动作=卡①激活位设置+落点卡④营地;激活态是否持久化以 Q1 裁定为准(裁乙才需,裁甲无「当前档选择」可持久——v1.1 条件化,原「拔电源不丢当前档选择」父注删除);写盘时机由卡①在 T0 对齐时定义。
## 4. 范围边界
**做**:选档界面视图(三槽卡+摘要+操作钮+空/有档/坏槽态);组合根接线(进入存档→选档;新档/进档→激活+营地;删档→确认→卡①删除原语→刷新);层序登记;断言批;反哺点清单。
**不做**(明示去向):
- 三槽承载/删档原语/摘要读器实现 → 卡①;
- 「进入存档」钮与主菜单砍钮 → 卡②;
- 营地场景图(进档落点) → 卡④;
- 档位自定义命名/备注/排序 → 用户未裁,批内禁加(澄清④只给三槽+三项摘要);
- 存档导入/导出/云同步 → 不在澄清范围,禁自扩。
## 5. 关联文档同步面
> **v1.3 口径**:本批禁写 `design/` 整目录与根规则文件,唯一可写目录 = `reports/`;下表一律执行为列进反哺点清单。08 写入权限统一口径:**状态列可改;注记改写列反哺点随清单呈报;增删行须用户裁**。
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| `design/gdd/06-待办清单.md` | 本卡登记条;存档序列化 P2 多档条(卡①反哺)与本条的交叉注记 | 反哺点 · 列清单 |
| `design/gdd/systems/跨局循环/生涯.md` | :11-23 信息架构结构树——新增「进入存档→选档界面」一级层级(生涯入口随卡④改挂笔记本) | 反哺点 · 结构树补层 |
| `design/gdd/08-Alpha版本标准.md` | 「三 · 界面」表新增「选档界面」行(在役)——增行须用户裁(08 头注纪律) | 反哺点 · 增行请求随清单呈报 |
| `roadmap.md` | 迭代行编入/状态刷新 | 反哺点 · 列清单 |
| `game/presentation/views/*`(新建选档视图)、`main.gd`、`game/smoke/*` | 实现与断言本体 | 实施本体(可写) |
## 6. 任务卡
> 估时按 Claude 工作日口径;每卡出口自跑轻闸;开工日 T0 复核全部行号。
### T0 事实坐实与接口对齐(≈0.5–1d)
- 复核 §2 行号;与卡①对齐窥视读器签名/命名/返回结构/空槽与坏槽表示法(卡① 契约 9 三态——对齐结论写成文附 §2,消 L3 落空项);
- 与卡②对齐「进入存档」钮句柄;与卡④对齐进档落点开层函数+**ConfirmDialog 消费方编排机制**(契约 3——卡④同款契约互指);
- 清点既有 confirm_dialog 断言面(ui_struct_probe.gd:71 结构采样、smoke_all.gd:226 最顶层候选、ui_click_probe:508-527、ui_tune_probe.gd:52 树序断言)——机制或实例数若变,这些点受影响;
- Q1 重启初始态与 Q2 坏档第三态裁定执行。
### T1 选档界面视图(≈1.5–2d)
- 全屏页壳(`UiKit.page_shell` 先例):标题+三槽卡横列+**页壳返回钮(生涯先例)→ `_close_modal`+开始层恢复**(v1.1 补——原只写「标题+三槽卡」漏了可退路径);
- 槽卡内容:槽位编号+摘要三项(钥石余额/通关局数/冒险总局数)+操作钮;空槽=「空存档位·新档」态;有档槽=摘要+「进档」+「删档」;坏槽/高版本槽按 Q2 裁定态;
- 钥石徽用工厂件;零新素材零新色值(契约 7);
- 删除钮形态:危险钮先例;**空槽禁渲染删档钮、禁置灰残留**(v1.1 订正原「禁用态纪律」——与契约 4 字面冲突);
- Q1 裁乙时补「预选」高亮态(选中槽卡视觉态——v1.1 补,原 T1 未含)。
### T2 组合根接线(≈1d)
- 「进入存档」→开选档界面(模态栈单口;与开始层互斥仿设置面先例);
- 新档:卡①空槽创建→激活→**暂行接现役 CampOverlay 开层**(Q3 裁定乙;卡④重新立卡后改挂场景图);
- 进档:卡①激活→**暂行接现役 CampOverlay 开层**(同上);
- 删档:ConfirmDialog 消费方编排(契约 3:open 前设消费方=删档、confirmed 后删、cancelled 后只关窗)→卡①删除原语→选档界面就地刷新(该槽回空态);
- 开层时摘要三读器按槽窥视(不激活不写盘);
- **动线序(v1.1 补)**:进档/新档时「先落点开层/开始层保持隐藏,再关选档」——禁先关后开(`_close_modal` 会恢复被遮挡的开始层=回闪一帧);营地开层后选档层被模态栈遮挡隐藏、不关闭(卡④ T3 同口径)。
### T3 断言批(≈1–1.5d)
- 探针:三槽呈现+摘要三项读数(**夹具按槽直写**——经卡①槽位 API/隔离面实现同会话三槽异值注入,v1.1 补任务落点);空/有档操作集断言(空槽零删档钮/有档槽零新档钮);坏槽按 Q2 态断言;删档确认链(第一次点击只开窗、取消后文件仍在、确认后槽回空);
- 冒烟:层序登记(`LAYER_CONTRACT` 合同断言);选档面零存档内功能入口(结构禁词断言);选档面返回钮开合(screen_flow_probe 型);
- **变异验证伴生**:删档钮直连删除(预期确认链断言红)、摘要读激活位(预期跨槽摘要红)、空槽渲染删档钮(预期操作集断言红)、**ConfirmDialog 双常驻接线**(注入后预期「删档确认误触发开局」断言红——新契约伴生,v1.1 补);注入→最窄闸见红→精确还原→记录。
### T4 产出物落位卡(≈0.5d,末卡)
三份 `reports/` 写齐。
**估时合计 ≈4.5–5.5d**(v1.1 上调:ConfirmDialog 机制+坏槽态+返回路径+夹具注入增量)。切分预案:T1/T2 后可切(视图先落、接线后落)——切分价值低,建议与卡②同批单跑。
## 7. 验证闸(逐需求点验收清单)
| # | 需求点 | 测什么 | 落点/判定手段 |
|---|---|---|---|
| V1 | 三槽呈现 | 3 槽卡在位且编号稳定;无滚动长列表 | ui_struct_probe 结构断言 |
| V2 | 摘要三项 | 钥石余额/通关局数/冒险总局数逐槽读数正确(夹具按槽直写三槽不同值);空槽零值;坏槽按 Q2 态 | ui_probe 型探针段(夹具经卡①槽位 API 直写,能力验证口径) |
| V3 | 摘要禁项 | 摘要区无断点/未完冒险相关读数(关数/种子/「继续」字样零命中) | 探针禁词断言 |
| V4 | 操作集二分 | 空槽零删档钮(含置灰);有档槽零新档钮 | 探针结构断言 |
| V5 | 空槽新档 | 空槽点新档→创建+激活+落点营地 | ui_click_probe 合成点击路径 |
| V6 | 有档槽进档 | 点进档→激活该槽(摘要=该槽值)→落点营地 | 同上 |
| V7 | 删档二次确认 | 一击只开确认窗;取消=文件仍在;确认=删+槽回空 | ui_click_probe 双路径段 |
| V8 | Q1 重启初始态 | 甲=重启回主菜单不预选;乙=预选/直入均可机检 | 探针重启链段(按 Q1 裁定案) |
| V9 | 返回路径 | 页壳返回钮→选档隐藏+开始层恢复;选档语境 ESC 不响应 | screen_flow_probe 型断言 |
| V10 | 层序纪律 | 新层入 LAYER_CONTRACT;登记序=树序=z 序 | 冒烟 V1d 合同断言 |
| V11 | 反哺点清单 | §5 每条有落点 | 件核对表 |
**测试方式两分法**:V1–V10 机检自动化(能力验证经夹具直写槽位/钥石/计数状态——经卡①槽位 API 或隔离存档实例,不走正常资源积累流程);**用户目检项=三槽观感与删档确认文案**——登记 07(生命周期末步统一目检,不阻塞迭代,澄清⑥口径)。
**闸口径**:轻闸每卡出口自跑;批末重闸按改动域选档(本批碰 `game/` 代码与断言面 → `--code`)全绿才合并;MC 零跑。
## 8. 异常分级
- **L1(自救)**:断言写法、槽卡布局微调、命名。
- **L2(记录继续)**:槽卡横列/纵列布局取舍(契约 1 内)、确认文案措辞、空态呈现细节。
- **L3(停机呈报)**:进档落点在卡④重新立卡前被要求改挂场景图(Q3 裁定乙=暂行现役 CampOverlay,提前改挂=越批);卡① 交付签名与 T0 对齐结论不符(v1.1 订正原「与本节假设不符」——本节无签名假设);删档确认链被要求简化(触裁决 3);ConfirmDialog 消费方机制与卡④无法对齐。
## 9. 代拍板白名单(超清单必呈报)
1. 槽卡布局(横列三卡 vs 纵列三行)与尺寸档取值(UiKit 现行件域内)。
2. 槽位编号呈现(「存档位 1/2/3」vs 其他措辞)。
3. 新档/进档/删档三钮的文案与动词化命名(对齐现役动词钮先例)。
4. 选档界面与开始层的互斥方式(仿设置面先例内的参数选择)。
5. 提交切分与 worktree 分支命名。
## 10. 待裁点
### Q1 · 重启后选档界面的初始态(必裁,未裁不开工)
**背景**:澄清④结构树只到「选档界面 → 营地场景图」,未覆盖退出游戏再启动后的行为。两案并列,**无推荐**(用户令:不代裁):
| 案 | 内容 | 代价 |
|---|---|---|
| 甲 | 每次启动都回主菜单→进入存档→选档界面,不自动进档、不预选 | 每轮开局多两次点击;语义最简(无「上次档」隐含状态) |
| 乙 | 记忆上次激活槽:重启后选档界面预选该槽(或一键直入) | 多一个激活位持久化状态(卡①承载);「默认进哪档」成为隐含决策;**「一键直入」变体绕选档层,与澄清④「选档=必经层」存在张力,若裁须一并确认层级关系**(v1.1 补注);「预选」需槽卡高亮态(T1 已列);持久化指针指向已删槽的重启语义须注明 |
连带:卡① §9 第 2 条激活位持久化仅裁乙才需;卡① T1 启动行为条件化同源。裁决方式:随卡片评审定案;裁定落 T0 执行+实现报告留痕。
**裁定(2026-10-18)**:**甲**——每次启动回主菜单→进入存档→选档界面,不自动进档、不预选。代拍板留痕(用户令「事项按推荐的来」,本项无推荐案,取默认甲=语义最简、无「上次档」隐含状态;追认单可 veto)。连带:卡① §9 第 2 条激活位持久化**作废**(无「当前档选择」需持久);T1 预选高亮态条目不做。
### Q2 · 坏档/高版本槽在选档面的呈现与操作集(必裁,未裁不开 T1 坏槽态)
**背景**:盘上任一槽文件可损坏或高版本;卡①窥视读器对不可读槽返回显式损坏标记(契约 9,peek 禁触发 `.corrupt.bak` 改名)——坏槽既非空亦非正常有档,契约 4 二分无第三态。两案并列:
| 案 | 内容 | 代价 |
|---|---|---|
| 甲(推荐) | 窥视对坏档/高版本槽返回零值,UI 按空槽呈现(新档/进档均经卡①兜底链接管——进档时走正式 load 触发兜底/拒读) | 坏档在选档面「看不见」,用户可能不知哪槽坏 |
| 乙 | 显式第三态(坏档标记+仅允许删档/进档) | 多一套 UI 态与断言 |
裁决方式:随卡片评审定案;裁定落 T0+T1 坏槽态实现。
**裁定(2026-10-18)**:**甲**——窥视对坏档/高版本槽返回零值,UI 按空槽呈现(推荐案,用户令按推荐执行);新档/进档均经卡①兜底链接管(进档时走正式 load 触发兜底/拒读)。T1 坏槽态=空槽态,无独立第三态 UI。
### Q3 · 卡③先行交付时,进档/新档的过渡落点(必裁,未裁不定排期)
**背景**:v1.0「建议本卡与卡②同批、卡④随后」与完成定义 3(进档落点=卡④)+§8 L3(落点未到位停线呈报)三句互斥——按 L3,「②③先合批、④随后」这条建议路径不可合并。三案并列:
| 案 | 内容 | 代价 |
|---|---|---|
| 甲(推荐) | 卡③与卡④同批(完成定义原样成立) | 两卡合并工作量大,单批周期长 |
| 乙 | 卡③先行,进档/新档暂行接**现役 CampOverlay**(卡④到位改挂——复用现役面,非「发明占位」) | 临时代码+卡④改挂时的二次验证面;CampOverlay 在卡④前仍是在役面,复用合法 |
| 丙 | 进档/新档暂行置灰,完成定义 3 拆两阶段 | 交付面砍残,选档界面半成品 |
裁决方式:随卡片评审定案;裁定落 §0/完成定义/§8 三处同步改写。
**裁定(2026-10-18)**:**乙**——本卡随①②③工程批先行,进档/新档暂行接现役 CampOverlay,卡④设计定稿重新立卡后改挂。**迫使原因**:卡④于同日回设计段(美术设计定稿未过设计前置闸),甲案(③④同批)失去对象;丙案(置灰)砍残交付面不取。暂行接线与后续改挂的二次验证面在 T2 明列、实现报告「已知中间态」节登记。
---
**修订记录**:v1.0→v1.1(2026-10-18 grilling 子 Agent 对抗审查回写)——事实订正:F6 行号 :458-461→:458-462;F2 补 ConfirmDialog 形态实证(零 payload/直开绕栈/静态常驻接线);F7 窥视读器标卡①未实现交付物+「通关次数」口径锁定;自扩订正:契约 8「拔电源不丢」父注按 Q1 条件化、Q1 乙案「一键直入」补层级张力注。卡内可收:契约 3 立 ConfirmDialog 消费方机制(禁双常驻接线)、契约 6 补直开豁免、契约 4 补两步路径记载、T1 补返回钮/禁置灰残留/预选高亮态、T2 补动线序与开层互斥、T3 补夹具注入与 ConfirmDialog 变异注入、T0 补既有断言面清点、V 表补三行、§8 L3 落空项订正。跨卡对齐:ConfirmDialog 机制卡③立卡④守、营地开层互斥与卡④ T3 同口径、断点确认探针段归卡④ T5 接收(卡② T2 明列移交)。新增待裁点 Q2 坏档第三态、Q3 先行落点过渡态。用户面裁决(裁决 2/3/4)零改动。