From becd300391db8fa38b8f7b2474bec864176f94a5 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 07:50:49 +0800 Subject: [PATCH] =?UTF-8?q?fix(=E6=A0=BC=E5=BC=8F=E6=8D=A2=E4=BB=A3):=20?= =?UTF-8?q?=E6=8D=A2=E8=A1=8C=E7=AC=A6=E5=BD=92=E4=B8=80=E6=B8=85=E5=81=BF?= =?UTF-8?q?=E5=90=88=E5=B9=B6=E8=84=9A=E6=9C=AC=E5=8F=8C=E9=87=8D=E8=BD=AC?= =?UTF-8?q?=E6=8D=A2=EF=BC=88=E4=B8=89=E6=96=87=E4=BB=B6=E6=9B=BE=E6=88=90?= =?UTF-8?q?=20CR=20CR=20LF=EF=BC=89=EF=BC=8B=C2=A712.1=20=E4=B8=80?= =?UTF-8?q?=E5=A4=84=E6=97=A7=E6=8E=AA=E8=BE=9E=E6=94=B9=E9=BD=90=EF=BC=88?= =?UTF-8?q?=E6=97=A0=E8=AE=BE=E8=AE=A1=E7=BA=BF=E6=AE=B5=E7=9A=84=E6=9D=A1?= =?UTF-8?q?=E7=9B=AE=E9=A1=BB=E5=9C=A8=E5=AE=9E=E5=86=B5=E6=8C=87=E8=AE=A4?= =?UTF-8?q?=E8=AF=81=E6=8D=AE=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/engineering/doc-conventions.md | 482 +++---- design/engineering/process-conventions.md | 184 +-- reports/审核-待办清单属性面-2026-10-25.md | 192 +++ 待办清单.md | 1506 ++++++++++----------- 4 files changed, 1278 insertions(+), 1086 deletions(-) create mode 100644 reports/审核-待办清单属性面-2026-10-25.md diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index f47e67b9..fc2d36bb 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -1,241 +1,241 @@ -# 文档写作规范（写文档前必读） - -> **地位**：本文是文档写作的规范权威，与 `design/engineering/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。 -> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。 - -## 0. 总纲 - -默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。 - -## 1. 可读性第一（最高纪律） - -**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。 - -`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性是第一内容质量门，lint 是格式机检面，两者并行。 - -## 2. 白话写作规则 - -写文档像向朋友当面解释你的游戏： - -1. **完整句子优先**：一段只说一件事，长句拆短句。 -2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。 -3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。 -4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。 -5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。 -6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。 - -## 3. 表达分工：散文、表格、字符画、公式 - -| 内容 | 载体 | 纪律 | -|---|---|---| -| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 | -| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 | -| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 | -| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 | -| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 | - -节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。 - -## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话） - -**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。 - -文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语： - -- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。 -- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记进 `design/gdd/术语表.md`。 -- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。 - -**自造词的三种固定形态（全部禁止）**： - -| 形态 | 反例 | 正确写法 | -|---|---|---| -| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 | -| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+登记进 术语表） | -| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 | - -**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。 - -**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由工程/文档设计改动批写入，禁 agent 自行增词。 - -## 5. 结构纪律 - -| 规则 | 内容 | -|---|---| -| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` | -| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log | -| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 | -| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | -| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | -| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | -| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | - -**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。 - -**登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款： - -1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。 -2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。 -3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。 -4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。 -5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。 - -## 6. 文档类型与骨架 - -**顶层文档**： - -| 文档 | 管什么 | -|---|---| -| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 | -| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 | -| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 | -| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 | -| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 | -| `05-不做清单.md` | 明确写：这些我不要 | -| `待办清单.md`（仓库根） | 流水线唯一登记处：条目=登记元数据标题＋四属性正文，状态随流水线段推进（格式与状态机见第 12.1 节）；各系统文档「待办」节只留指路存根 | -| `roadmap.md`（根目录） | 里程碑表＋迭代总表，一行一迭代，记录编排与实现进度（六列格式见第 12.2 节） | - -**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／调参表（取值域+provisional 标注）／验收标准（可验证判据）／待办（指路存根）。 - -**命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `02-系统清单.md`，旧代号（a1–d6）仅限解读归档。 - -## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/engineering/concept-conventions.md` - -## 10. 会话状态——仓库根不设状态文件 - -**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。 - -废除后的分工：**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节；**待办与待裁**看 [待办清单](../../待办清单.md)（唯一登记处）；**批次过程与结论**看 git 提交信息与 `reports/`；**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件，也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移，这正是本次统计查出七条失实陈述的成因。 - -## 11. 文档生命周期：吸收即死 - -**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/engineering/architecture/architecture.md`）、退役内容留底（`design/content-archive/`，2026-10-20 用户裁新立：只装「内容已退役、留底供日后重新过准入」的档案，落内文件须在文档头写明所属线）、本规范、待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片（死期=所属迭代实现批合回 master 那一刻；roadmap 对应行的卡片/报告列改填「已退役（git 历史可考）」保留字，凭据语义从文件指针换代为状态标记）、机检/验收过程报告、调研/审计/提案/需求澄清过程稿、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。 - -| 规则 | 内容 | -|---|---| -| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/术语表）那一刻，文件即删 | -| 未决先迁再死 | 未决内容先迁现行事实源（待办清单/roadmap 卡/GDD 对应节），然后文档即死 | -| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 | -| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删 | -| 删除不留死链 | 中间文档删除后，任何现行文档禁止再留指向它的文件路径；改指结论或提交号 | -| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 | -| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 | -| 暂存地非档案库 | 中间文档唯一暂存地＝`reports/`（需求卡片＋迭代产出物＋调研/审计/提案/需求澄清过程稿）。**`design/research/` 已退役（2026-10-21 用户裁）**：`design/` 全目录只放持久化设计文档与规范，过程件一律不进，禁止再在 `design/` 下另设过程件目录（熵增闸退役路径清单已收 `design/research`，目录再现即判红）。禁止文件在自身页眉自称「常驻／已追认／不受吸收即死约束」之类的豁免——豁免只写进规约正文，本条就是不给；确实要长期留用的退役内容走 `design/content-archive/`（活文档身份，落内文件头部写明所属线）。跨会话交接文件（会话提示/handoff/任务书/试运行报告）禁止入库——给另一个会话的开工输入在会话里交付即可（与仓库根禁设会话状态文件同族判据，见第 10 节）。根目录 `playnote.md`=用户本人试玩随手记，只由用户本人增删，不属于任何文档族、不受吸收即死管辖，不进 §11 任何一格。图像载体不进 `design/` 各子目录、也不进 `reports/`——图一律留 `artwork/`（2026-09-27 用户裁「审图只看一处」），结论写进待办清单或需求卡片后图像即弃；`.html`／`.json` 这类报告渲染件允许作为报告的一种（2026-10-21 用户裁）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` | -| 落档必写接收方 | 新报告落档时头部必须写明接收方——`待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 | -| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 | -| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 | - -**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。 - -## 12. 流程文档格式 - -五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）靠流程文档运转：待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查待办清单与 roadmap 两文件格式及互相引用的机检闸）的判据依据。 - -### 12.1 待办清单条目格式与状态机 - -待办清单是流水线的唯一登记处：要做的事先登记一条，随流水线段推进改状态，做完整条删除。一条条目分两层——**标题=登记元数据**（何时登记、从哪来、紧急度，登记后不再变），**正文=四个属性**（随进程演进）。四个属性各管一件事：`实况` 管凭据，`缺口` 管这条的**输入**（还缺哪一次设计），`改动面` 管这条的**产出**（要动哪些面），`状态` 管这条走到流水线哪一段。 - -标题格式（尖括号处按实际填写，方括号内为可选段）： - -``` -#### <条目名>（登记，来源=[，优先级＝]） -``` - -`优先级` 是紧急度标记，可选，规则三条：不写＝默认档 P2；只有用户明示才写，会话不得自行给任何条目定档；P0 最高、P2 最低。它只服务阅读时的排序，不参与开工门、编排四查与状态机。`P0/P1/P2` 这组记号在本仓库只指待办紧急度，新文档禁另立别义。 - -正文四属性模板： - -``` -**实况**＝关联文档清单，一行一件：它是什么（设计定稿／需求卡片／相关文档）＋文件路径＋版本号与日期（闭合类文件必带）；必要时在清单前配一句实际情况说明。机制解释与论证过程不写在这里，归权威文档。路径用普通文本或行内代码书写，机器可搜索。工程形态条目必须在实况里指认证据（bug 证据或工程债条目）。 -**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合设计段时此属性必须存在；设计线全部闭合后删除。 -**改动面**＝文档／美术素材／游戏代码／工具代码 四档取多，多档用＋连接、禁重复、按上表次序排列。登记时即写，随进程若产出面变宽要补档。 -**状态**：按状态机取词。 -``` - -`改动面` 四档的划线判据（按被改对象的路径归属，与闸的分域同口径）： - -| 档 | 覆盖范围 | -|---|---| -| 文档 | 本仓库的 .md 权威文档：`design/` 设计文档与 `design/engineering/` 规约、`design/art/art-bible`、根流程件（roadmap／待办清单／体验验证清单） | -| 美术素材 | 本条目要出的图：`artwork/` 在途样张与 `game/assets/art/` 终稿 | -| 游戏代码 | `game/` 全部：脚本与场景、`data/tables/*.tres` 数值表、`tests/`、`probe/`、`sim/`——表值直接改变游戏运行结果，归本档 | -| 工具代码 | `tools/` 与仓库根 python 脚本（含各验证闸件）＋流水线技能件 `.zcode/skills/`、`.qoder/skills/`（技能改的是流水线行为，与闸件同类） | - -只写本条目自己交付的产出面，不预写下游实现批要动的面。`reports/` 下的需求卡片与批次产出物属过程件（第 11 节管辖），不计入 `文档` 档。四档与 AGENTS.md 硬红线的「改动四类」对应关系：`游戏代码`＝需求改动（走写卡与编排段）、`工具代码`／`文档`／`美术素材` 三档各自对应工程改动／文档设计改动／美术素材改动三类直改通道；一条条目可以同时含多档。 - -状态段用词自带所属设计线——`待文档设计`／`文档设计中`／`文档设计已闭合` 是文档线，`待美术设计`／`美术设计中`／`美术设计已闭合` 是美术线，不需要在标题另行声明走哪条线。状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；跨线的段一律保留、禁删（同一设计线内只留最新一段），下游段一旦写下不回收——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验，＋号只作状态段连接符。 - -``` -各设计线推进序列（同条目两条线并列推进时，两段各写各的）： -文档线：待文档设计 → 文档设计中 → 文档设计已闭合 -美术线：待美术设计 → 美术设计中 → 美术设计已闭合 -下游共用序列（需求改动）：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除 -直改序列（工程改动／文档设计改动／美术素材改动）：登记 → 待执行 → 完成即整条删除（经设计讨论的可前置闭合段，如「文档设计已闭合＋待执行」） -累积示例：文档设计已闭合＋待美术设计＋已写卡 -``` - -设计线段与下游段同条并存是合法形态：状态行里出现过的**每条设计线各自留最新一段**，跨线依赖不阻塞本条推进（文档线闭合后写卡、美术线仍未出图，就把 `文档设计已闭合` 与 `待美术设计` 并写）。「写卡前本条要落的那条设计线必须已闭合」是实现侧的执行义务，由编排段查卡片凭据核对，不靠标题声明——闸只查同线并现多段。 - -状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。 - -三种条目形态与一种后缀： - -| 形态 | 规则 | -|---|---| -| 需求性工程条目（需求改动） | 缺陷修复／重构等改游戏行为的条目：状态首段直接落「待写卡」、整行不含设计段，凭实况里指认的证据跳过设计线；改动面必含 `游戏代码` | -| 直改类条目（工程改动／文档设计改动／美术素材改动） | 不动游戏行为的配套改动：登记即「待执行」，用户发令直改，不走写卡与编排段；改动面取 `工具代码`／`文档`／`美术素材` 三档 | -| 反哺点专条 | 状态取 待裁决 → 已写入 → 删除，不走设计线也不走下游序列 | -| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 | - -特批标记见 12.4。 - -### 12.2 roadmap 迭代行格式 - -roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝冻结不可开工。迭代行六列： - -``` -| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 | -``` - -| 列 | 规则 | -|---|---| -| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 | -| 状态 | 待开工 ／ 冻结待凑批 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） | -| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」；历史迭代不可考填「—」（早期无卡片制的迭代） | -| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期）；历史迭代不可考填「—」 | -| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 的迭代行状态必须为「冻结待凑批」（2026-10-25 两层模型：小卡可编入，迭代总量不足即冻结、禁止处待开工/进行中）；超过 20 判红（硬上限，特批标记也不放行）；历史迭代不可考填「—」 | -| 实现报告 | `reports/iterN-实现报告-YYYY-MM-DD.md`；未完成=「—」；退役=「已退役（git 历史可考）」；已完成迭代只许存在路径或退役保留字、禁「—」 | - -迭代行禁入内容：事项说明、卡序叙述、T 段明细、读数、闸数字、裁点记录、门依赖。卡间依赖写在卡片自身，行内只放上表六列的事实。特批标记同样可用于 roadmap 格（须带日期，见 12.4）。 - -### 12.3 美术工作区目录与命名 - -美术素材走两条目录线：在途工作在 `artwork/`（整目录不入 git），定稿进 `game/assets/art/`（入包被游戏加载）。图片永不进 `design/`。 - -| 位置 | 规则 | -|---|---| -| `artwork//` | 批次工作区，一次美术批一个目录，整目录不入 git | -| `artwork/<批次工作区>/samples/` | 样张子目录 | -| `artwork/archive/<主题>-<日期>/` | 批次完结归档 | -| `game/assets/art/<用途子目录>/` | 终稿，入包被游戏加载 | - -命名总则：全小写英文＋下划线，禁中文／空格／大写。 - -| 对象 | 文件名规则 | -|---|---| -| 终稿 | 三段式 `<对象>_<部位或状态>_<规格>.png`；终稿文件名=代码消费名——先定 ui_kit／资源路径常量，素材名跟它走，防断链 | -| 样张 | `sample_<屏名>_<版本>.png` | -| 同名迭代 | 直接覆盖，不留 v2 副本 | - -美术内容不做机检，只保留命名与目录检查。 - -### 12.4 特批标记 - -特批标记是流程格式例外的唯一放行凭证：`〔用户特批 YYYY-MM-DD 跳过××〕`。只有用户明示才能给，用于待办清单条目状态与 roadmap 格（见 12.1、12.2）。 - -执行技能一律两段式： - -1. 对象已有内容 → 直接写入标记。 -2. 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。 - -标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。 +# 文档写作规范（写文档前必读） + +> **地位**：本文是文档写作的规范权威，与 `design/engineering/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。 +> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。 + +## 0. 总纲 + +默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。 + +## 1. 可读性第一（最高纪律） + +**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。 + +`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性是第一内容质量门，lint 是格式机检面，两者并行。 + +## 2. 白话写作规则 + +写文档像向朋友当面解释你的游戏： + +1. **完整句子优先**：一段只说一件事，长句拆短句。 +2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。 +3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。 +4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。 +5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。 +6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。 + +## 3. 表达分工：散文、表格、字符画、公式 + +| 内容 | 载体 | 纪律 | +|---|---|---| +| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 | +| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 | +| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 | +| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 | +| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 | + +节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。 + +## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话） + +**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。 + +文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语： + +- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。 +- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记进 `design/gdd/术语表.md`。 +- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。 + +**自造词的三种固定形态（全部禁止）**： + +| 形态 | 反例 | 正确写法 | +|---|---|---| +| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 | +| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+登记进 术语表） | +| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 | + +**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。 + +**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由工程/文档设计改动批写入，禁 agent 自行增词。 + +## 5. 结构纪律 + +| 规则 | 内容 | +|---|---| +| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` | +| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log | +| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 | +| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | +| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | +| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | +| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | + +**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。 + +**登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款： + +1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。 +2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。 +3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。 +4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。 +5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。 + +## 6. 文档类型与骨架 + +**顶层文档**： + +| 文档 | 管什么 | +|---|---| +| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 | +| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 | +| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 | +| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 | +| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 | +| `05-不做清单.md` | 明确写：这些我不要 | +| `待办清单.md`（仓库根） | 流水线唯一登记处：条目=登记元数据标题＋四属性正文，状态随流水线段推进（格式与状态机见第 12.1 节）；各系统文档「待办」节只留指路存根 | +| `roadmap.md`（根目录） | 里程碑表＋迭代总表，一行一迭代，记录编排与实现进度（六列格式见第 12.2 节） | + +**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／调参表（取值域+provisional 标注）／验收标准（可验证判据）／待办（指路存根）。 + +**命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `02-系统清单.md`，旧代号（a1–d6）仅限解读归档。 + +## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/engineering/concept-conventions.md` + +## 10. 会话状态——仓库根不设状态文件 + +**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。 + +废除后的分工：**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节；**待办与待裁**看 [待办清单](../../待办清单.md)（唯一登记处）；**批次过程与结论**看 git 提交信息与 `reports/`；**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件，也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移，这正是本次统计查出七条失实陈述的成因。 + +## 11. 文档生命周期：吸收即死 + +**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/engineering/architecture/architecture.md`）、退役内容留底（`design/content-archive/`，2026-10-20 用户裁新立：只装「内容已退役、留底供日后重新过准入」的档案，落内文件须在文档头写明所属线）、本规范、待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片（死期=所属迭代实现批合回 master 那一刻；roadmap 对应行的卡片/报告列改填「已退役（git 历史可考）」保留字，凭据语义从文件指针换代为状态标记）、机检/验收过程报告、调研/审计/提案/需求澄清过程稿、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。 + +| 规则 | 内容 | +|---|---| +| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/术语表）那一刻，文件即删 | +| 未决先迁再死 | 未决内容先迁现行事实源（待办清单/roadmap 卡/GDD 对应节），然后文档即死 | +| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 | +| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删 | +| 删除不留死链 | 中间文档删除后，任何现行文档禁止再留指向它的文件路径；改指结论或提交号 | +| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 | +| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 | +| 暂存地非档案库 | 中间文档唯一暂存地＝`reports/`（需求卡片＋迭代产出物＋调研/审计/提案/需求澄清过程稿）。**`design/research/` 已退役（2026-10-21 用户裁）**：`design/` 全目录只放持久化设计文档与规范，过程件一律不进，禁止再在 `design/` 下另设过程件目录（熵增闸退役路径清单已收 `design/research`，目录再现即判红）。禁止文件在自身页眉自称「常驻／已追认／不受吸收即死约束」之类的豁免——豁免只写进规约正文，本条就是不给；确实要长期留用的退役内容走 `design/content-archive/`（活文档身份，落内文件头部写明所属线）。跨会话交接文件（会话提示/handoff/任务书/试运行报告）禁止入库——给另一个会话的开工输入在会话里交付即可（与仓库根禁设会话状态文件同族判据，见第 10 节）。根目录 `playnote.md`=用户本人试玩随手记，只由用户本人增删，不属于任何文档族、不受吸收即死管辖，不进 §11 任何一格。图像载体不进 `design/` 各子目录、也不进 `reports/`——图一律留 `artwork/`（2026-09-27 用户裁「审图只看一处」），结论写进待办清单或需求卡片后图像即弃；`.html`／`.json` 这类报告渲染件允许作为报告的一种（2026-10-21 用户裁）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` | +| 落档必写接收方 | 新报告落档时头部必须写明接收方——`待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 | +| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 | +| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 | + +**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。 + +## 12. 流程文档格式 + +五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）靠流程文档运转：待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查待办清单与 roadmap 两文件格式及互相引用的机检闸）的判据依据。 + +### 12.1 待办清单条目格式与状态机 + +待办清单是流水线的唯一登记处：要做的事先登记一条，随流水线段推进改状态，做完整条删除。一条条目分两层——**标题=登记元数据**（何时登记、从哪来、紧急度，登记后不再变），**正文=四个属性**（随进程演进）。四个属性各管一件事：`实况` 管凭据，`缺口` 管这条的**输入**（还缺哪一次设计），`改动面` 管这条的**产出**（要动哪些面），`状态` 管这条走到流水线哪一段。 + +标题格式（尖括号处按实际填写，方括号内为可选段）： + +``` +#### <条目名>（登记，来源=[，优先级＝]） +``` + +`优先级` 是紧急度标记，可选，规则三条：不写＝默认档 P2；只有用户明示才写，会话不得自行给任何条目定档；P0 最高、P2 最低。它只服务阅读时的排序，不参与开工门、编排四查与状态机。`P0/P1/P2` 这组记号在本仓库只指待办紧急度，新文档禁另立别义。 + +正文四属性模板： + +``` +**实况**＝关联文档清单，一行一件：它是什么（设计定稿／需求卡片／相关文档）＋文件路径＋版本号与日期（闭合类文件必带）；必要时在清单前配一句实际情况说明。机制解释与论证过程不写在这里，归权威文档。路径用普通文本或行内代码书写，机器可搜索。无设计线段的条目（需求性工程条目与直改类条目）必须在实况里指认证据（bug 证据或工程债条目）。 +**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合设计段时此属性必须存在；设计线全部闭合后删除。 +**改动面**＝文档／美术素材／游戏代码／工具代码 四档取多，多档用＋连接、禁重复、按上表次序排列。登记时即写，随进程若产出面变宽要补档。 +**状态**：按状态机取词。 +``` + +`改动面` 四档的划线判据（按被改对象的路径归属，与闸的分域同口径）： + +| 档 | 覆盖范围 | +|---|---| +| 文档 | 本仓库的 .md 权威文档：`design/` 设计文档与 `design/engineering/` 规约、`design/art/art-bible`、根流程件（roadmap／待办清单／体验验证清单） | +| 美术素材 | 本条目要出的图：`artwork/` 在途样张与 `game/assets/art/` 终稿 | +| 游戏代码 | `game/` 全部：脚本与场景、`data/tables/*.tres` 数值表、`tests/`、`probe/`、`sim/`——表值直接改变游戏运行结果，归本档 | +| 工具代码 | `tools/` 与仓库根 python 脚本（含各验证闸件）＋流水线技能件 `.zcode/skills/`、`.qoder/skills/`（技能改的是流水线行为，与闸件同类） | + +只写本条目自己交付的产出面，不预写下游实现批要动的面。`reports/` 下的需求卡片与批次产出物属过程件（第 11 节管辖），不计入 `文档` 档。四档与 AGENTS.md 硬红线的「改动四类」对应关系：`游戏代码`＝需求改动（走写卡与编排段）、`工具代码`／`文档`／`美术素材` 三档各自对应工程改动／文档设计改动／美术素材改动三类直改通道；一条条目可以同时含多档。 + +状态段用词自带所属设计线——`待文档设计`／`文档设计中`／`文档设计已闭合` 是文档线，`待美术设计`／`美术设计中`／`美术设计已闭合` 是美术线，不需要在标题另行声明走哪条线。状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；跨线的段一律保留、禁删（同一设计线内只留最新一段），下游段一旦写下不回收——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验，＋号只作状态段连接符。 + +``` +各设计线推进序列（同条目两条线并列推进时，两段各写各的）： +文档线：待文档设计 → 文档设计中 → 文档设计已闭合 +美术线：待美术设计 → 美术设计中 → 美术设计已闭合 +下游共用序列（需求改动）：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除 +直改序列（工程改动／文档设计改动／美术素材改动）：登记 → 待执行 → 完成即整条删除（经设计讨论的可前置闭合段，如「文档设计已闭合＋待执行」） +累积示例：文档设计已闭合＋待美术设计＋已写卡 +``` + +设计线段与下游段同条并存是合法形态：状态行里出现过的**每条设计线各自留最新一段**，跨线依赖不阻塞本条推进（文档线闭合后写卡、美术线仍未出图，就把 `文档设计已闭合` 与 `待美术设计` 并写）。「写卡前本条要落的那条设计线必须已闭合」是实现侧的执行义务，由编排段查卡片凭据核对，不靠标题声明——闸只查同线并现多段。 + +状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。 + +三种条目形态与一种后缀： + +| 形态 | 规则 | +|---|---| +| 需求性工程条目（需求改动） | 缺陷修复／重构等改游戏行为的条目：状态首段直接落「待写卡」、整行不含设计段，凭实况里指认的证据跳过设计线；改动面必含 `游戏代码` | +| 直改类条目（工程改动／文档设计改动／美术素材改动） | 不动游戏行为的配套改动：登记即「待执行」，用户发令直改，不走写卡与编排段；改动面取 `工具代码`／`文档`／`美术素材` 三档 | +| 反哺点专条 | 状态取 待裁决 → 已写入 → 删除，不走设计线也不走下游序列 | +| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 | + +特批标记见 12.4。 + +### 12.2 roadmap 迭代行格式 + +roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝冻结不可开工。迭代行六列： + +``` +| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 | +``` + +| 列 | 规则 | +|---|---| +| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 | +| 状态 | 待开工 ／ 冻结待凑批 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） | +| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」；历史迭代不可考填「—」（早期无卡片制的迭代） | +| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期）；历史迭代不可考填「—」 | +| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 的迭代行状态必须为「冻结待凑批」（2026-10-25 两层模型：小卡可编入，迭代总量不足即冻结、禁止处待开工/进行中）；超过 20 判红（硬上限，特批标记也不放行）；历史迭代不可考填「—」 | +| 实现报告 | `reports/iterN-实现报告-YYYY-MM-DD.md`；未完成=「—」；退役=「已退役（git 历史可考）」；已完成迭代只许存在路径或退役保留字、禁「—」 | + +迭代行禁入内容：事项说明、卡序叙述、T 段明细、读数、闸数字、裁点记录、门依赖。卡间依赖写在卡片自身，行内只放上表六列的事实。特批标记同样可用于 roadmap 格（须带日期，见 12.4）。 + +### 12.3 美术工作区目录与命名 + +美术素材走两条目录线：在途工作在 `artwork/`（整目录不入 git），定稿进 `game/assets/art/`（入包被游戏加载）。图片永不进 `design/`。 + +| 位置 | 规则 | +|---|---| +| `artwork//` | 批次工作区，一次美术批一个目录，整目录不入 git | +| `artwork/<批次工作区>/samples/` | 样张子目录 | +| `artwork/archive/<主题>-<日期>/` | 批次完结归档 | +| `game/assets/art/<用途子目录>/` | 终稿，入包被游戏加载 | + +命名总则：全小写英文＋下划线，禁中文／空格／大写。 + +| 对象 | 文件名规则 | +|---|---| +| 终稿 | 三段式 `<对象>_<部位或状态>_<规格>.png`；终稿文件名=代码消费名——先定 ui_kit／资源路径常量，素材名跟它走，防断链 | +| 样张 | `sample_<屏名>_<版本>.png` | +| 同名迭代 | 直接覆盖，不留 v2 副本 | + +美术内容不做机检，只保留命名与目录检查。 + +### 12.4 特批标记 + +特批标记是流程格式例外的唯一放行凭证：`〔用户特批 YYYY-MM-DD 跳过××〕`。只有用户明示才能给，用于待办清单条目状态与 roadmap 格（见 12.1、12.2）。 + +执行技能一律两段式： + +1. 对象已有内容 → 直接写入标记。 +2. 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。 + +标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。 diff --git a/design/engineering/process-conventions.md b/design/engineering/process-conventions.md index 42408e34..2ca5ffe8 100644 --- a/design/engineering/process-conventions.md +++ b/design/engineering/process-conventions.md @@ -1,92 +1,92 @@ -# 流程规范（Dungeon Sweeper） - -> 约束范围：一切批次的流程纪律——分支与 worktree、五段流水线、批次工作流、测试执行细则、像素件工作纪律。 -> 分工：硬性红线的一句话索引在 AGENTS.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。 - -**开工任何批次前必须通读本文。** - -## 1. 分支纪律（worktree 铁律） - -主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区： - -1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运） -2. **收尾**：批次收口顺序固定为**冻结 → 件核 → 并 master → 跑一次域闸 → 合回**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先 `git merge master` 解冲突（必须在跑闸之前，闸跑完再并＝那次闸白跑），然后按本批改动域跑**一次** `tools/run_all_gates.sh`（见 §3.9：纯文档批跑 `--docs`），全绿后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支。闸后 `game/` 面不得再改一个字节（回执作废须重跑），只允许追加 `reports/`、`design/` 等非 `game/` 提交。非 loop 批次同此顺序；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑 -3. **豁免面**：仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截 -4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限 - -## 2. 五段流水线 - -**需求改动**（游戏代码，含随逻辑写/改的测试）按五段流水线走：**登记 → 文档设计／美术设计（两条设计线）→ 写需求卡片 → 迭代编排 → 实现**；工程／文档设计／美术素材三类改动不走写卡与编排段，走「登记 →（如需设计讨论）→ 用户发令直改 → 按改动域跑闸 → 完成删条目」。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝「冻结待凑批」，不可开工。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 `.zcode/skills/`：doc-design／asset-ingest／req-card／iter-plan／iter），登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。 - -| 段 | 入口技能 | 产出 | 出入口铁律 | -|---|---|---|---| -| 一·登记 | 无（闸管格式） | 待办清单条目 | 条目=标题登记元数据（日期/来源/可选优先级）＋正文四属性（实况/缺口/改动面/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 | -| 二·文档设计／美术设计 | doc-design（文档线，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从待办清单取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；设计线闭合凭据记入待办清单实况清单（文档线=文档路径+版本号，美术线=art-bible 条款版本）；缺哪条线写在缺口属性，闭合与否写在状态段 | -| 三·写需求卡片 | req-card | 需求卡片 | 设计线闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=需求性工程条目（缺陷修复／重构等改游戏行为）凭实况里的证据指认跳过设计线；配套维护类（工程债/测试基建/工具维护，不动游戏行为）＝工程改动直改类，不走本段，登记后「待执行」由用户发令直改；卡片必经 grilling 多轮复核、零待裁点才成立；写完在待办清单状态记「已写卡」，卡片路径记入实况清单（防遗忘） | -| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或需求性工程条目的证据指认）③估时与冻结线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：**卡片任何工作量均可编入**（2026-10-25 用户立：工作量限制属迭代层、非卡片层）；编入后迭代总量 <5 个工作日＝迭代行状态「冻结待凑批」、不可开工，凑批 ≥5 后由编排段改「待开工」（迭代体量偏好，2026-10-21 用户立、2026-10-25 改冻结制）；5–10 个工作日为常规区间；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日禁止编（硬上限，用户确认也不放行，必须拆批）④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 | -| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 | - -**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。 - -**流水线闸**：`tools/pipeline_gate.py` 机检待办清单与 roadmap 两文件的格式与互相引用；已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。 - -## 3. 批次工作流标准清单 - -每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）： - -**开工前** -1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑 -2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺 -3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工 - -**环境与基线** -4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则） -5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟 - -**实施** -6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并 -7. **验收改动先行声明**——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补 - -**完成** -8. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 与 `dirty_game` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验（六况拦截：缺回执／quick 模式／回执未覆盖分支尖＝回执 commit 之后 `game/` 又有改动、或跑闸时 `game/` 带着未提交改动（`dirty_game`）／域不覆盖本次改动／含新增红／master HEAD 非回执 commit 祖先＝合并将产出未测内容）。回执与分支尖的对齐判据是**代码面**不是 commit 号：回执之后只追加 `reports/`、`design/` 等非 `game/` 提交，回执照样有效，不构成复跑理由。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变，闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底 -9. **合并后主区零复跑**（2026-10-24 用户裁：合回重跑验的是与回执同一份字节，零信息）——合回落地后 code 批只做两件秒级事：`--editor --quit` 重刷类名缓存（在册坑：.godot 缓存不入 git，与合并后代码失配会假红假绿）＋冒烟启动确认可开机（合计约 1 分钟）；docs 批零动作。全量验证**每批跑一次**＝worktree 批末按域闸，顺序是「先并入 master、再跑闸」（§1 第 2 条）；只有两种情形允许把这次跑作废重来——① 闸红且修法动了 `game/`，② 闸已开跑后 master 又被推进（合并将产出未测内容，由合回闸祖先判定拦下，§3.9 第六况）。「跑都跑了再跑一遍保险」「闸后顺手改点 `game/` 再补一跑」都不构成复跑理由；master 上永不跑全量 -10. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`/`待办清单.md`/`体验验证清单.md`）实现批禁写，见 §12 -11. **文档同步闸（实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由工程/文档设计改动批（直改类）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注 -12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置 -13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节 -14. **改动级验收闭合**——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §8 - -## 4. 测试执行两入口铁规（细则） - -测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。 - -**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。 - -**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**，用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿，回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。 - -## 5. MC 采集档位细则 - -四档硬闸（全表与统计精度见 `sim-data/README.md`「MC 采集档位表」）： - -| 档 | 用途 | 上限 | 触发权 | -|---|---|---|---| -| 一档·调研 | 调研/数值分析 | 总量 >40 | **只能由用户发起**——需求卡片/计划书/agent 均无权授权 | -| 二档·数值修改验证 | 改数值前后取证 | 总量 ≤40、每档 ≤20 | 数值验证场景 | -| 三档·小调 | 只测不判 | 总量 ≤20、每档 ≤10 | 数值验证场景 | -| 四档·微量 | sanity 门，零统计判读 | 总量 ≤5 | 数值验证场景 | - -配套纪律：超档=停机呈报，窗口不足如实挂起，禁在二/三/四档下带值结论；改前/改后锚同 seed0 配对、改前锚留盘禁补跑；逐项比对断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC；四档仅承接数值验证场景，两入口铁规不变。 - -## 6. 闸机轮次纪律 - -1. **孤立验证先行**——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验 -2. **调试期最窄确认**——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可 -3. **长批试车**——≥2 分钟的跑批（逐位逐项比对冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批 -4. **开工坑册扫描**——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等） - -## 7. 像素结构件工作纪律 - -1. **先抄后造**——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径） -2. **验完成径写成像素级视觉判据**——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感 -3. **±1px 一律坐标推导**——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错 -4. **修复默认附前后对比图+像素审计**，不等用户索要 +# 流程规范（Dungeon Sweeper） + +> 约束范围：一切批次的流程纪律——分支与 worktree、五段流水线、批次工作流、测试执行细则、像素件工作纪律。 +> 分工：硬性红线的一句话索引在 AGENTS.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。 + +**开工任何批次前必须通读本文。** + +## 1. 分支纪律（worktree 铁律） + +主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区： + +1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运） +2. **收尾**：批次收口顺序固定为**冻结 → 件核 → 并 master → 跑一次域闸 → 合回**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先 `git merge master` 解冲突（必须在跑闸之前，闸跑完再并＝那次闸白跑），然后按本批改动域跑**一次** `tools/run_all_gates.sh`（见 §3.9：纯文档批跑 `--docs`），全绿后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支。闸后 `game/` 面不得再改一个字节（回执作废须重跑），只允许追加 `reports/`、`design/` 等非 `game/` 提交。非 loop 批次同此顺序；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑 +3. **豁免面**：仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截 +4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限 + +## 2. 五段流水线 + +**需求改动**（游戏代码，含随逻辑写/改的测试）按五段流水线走：**登记 → 文档设计／美术设计（两条设计线）→ 写需求卡片 → 迭代编排 → 实现**；工程／文档设计／美术素材三类改动不走写卡与编排段，走「登记 →（如需设计讨论）→ 用户发令直改 → 按改动域跑闸 → 完成删条目」。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝「冻结待凑批」，不可开工。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 `.zcode/skills/`：doc-design／asset-ingest／req-card／iter-plan／iter），登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。 + +| 段 | 入口技能 | 产出 | 出入口铁律 | +|---|---|---|---| +| 一·登记 | 无（闸管格式） | 待办清单条目 | 条目=标题登记元数据（日期/来源/可选优先级）＋正文四属性（实况/缺口/改动面/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 | +| 二·文档设计／美术设计 | doc-design（文档线，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从待办清单取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；设计线闭合凭据记入待办清单实况清单（文档线=文档路径+版本号，美术线=art-bible 条款版本）；缺哪条线写在缺口属性，闭合与否写在状态段 | +| 三·写需求卡片 | req-card | 需求卡片 | 设计线闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=需求性工程条目（缺陷修复／重构等改游戏行为）凭实况里的证据指认跳过设计线；配套维护类（工程债/测试基建/工具维护，不动游戏行为）＝工程改动直改类，不走本段，登记后「待执行」由用户发令直改；卡片必经 grilling 多轮复核、零待裁点才成立；写完在待办清单状态记「已写卡」，卡片路径记入实况清单（防遗忘） | +| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或需求性工程条目的证据指认）③估时与冻结线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：**卡片任何工作量均可编入**（2026-10-25 用户立：工作量限制属迭代层、非卡片层）；编入后迭代总量 <5 个工作日＝迭代行状态「冻结待凑批」、不可开工，凑批 ≥5 后由编排段改「待开工」（迭代体量偏好，2026-10-21 用户立、2026-10-25 改冻结制）；5–10 个工作日为常规区间；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日禁止编（硬上限，用户确认也不放行，必须拆批）④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 | +| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 | + +**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。 + +**流水线闸**：`tools/pipeline_gate.py` 机检待办清单与 roadmap 两文件的格式与互相引用；已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。 + +## 3. 批次工作流标准清单 + +每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）： + +**开工前** +1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑 +2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺 +3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工 + +**环境与基线** +4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则） +5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟 + +**实施** +6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并 +7. **验收改动先行声明**——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补 + +**完成** +8. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 与 `dirty_game` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验（六况拦截：缺回执／quick 模式／回执未覆盖分支尖＝回执 commit 之后 `game/` 又有改动、或跑闸时 `game/` 带着未提交改动（`dirty_game`）／域不覆盖本次改动／含新增红／master HEAD 非回执 commit 祖先＝合并将产出未测内容）。回执与分支尖的对齐判据是**代码面**不是 commit 号：回执之后只追加 `reports/`、`design/` 等非 `game/` 提交，回执照样有效，不构成复跑理由。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变，闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底 +9. **合并后主区零复跑**（2026-10-24 用户裁：合回重跑验的是与回执同一份字节，零信息）——合回落地后 code 批只做两件秒级事：`--editor --quit` 重刷类名缓存（在册坑：.godot 缓存不入 git，与合并后代码失配会假红假绿）＋冒烟启动确认可开机（合计约 1 分钟）；docs 批零动作。全量验证**每批跑一次**＝worktree 批末按域闸，顺序是「先并入 master、再跑闸」（§1 第 2 条）；只有两种情形允许把这次跑作废重来——① 闸红且修法动了 `game/`，② 闸已开跑后 master 又被推进（合并将产出未测内容，由合回闸祖先判定拦下，§3.9 第六况）。「跑都跑了再跑一遍保险」「闸后顺手改点 `game/` 再补一跑」都不构成复跑理由；master 上永不跑全量 +10. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`/`待办清单.md`/`体验验证清单.md`）实现批禁写，见 §12 +11. **文档同步闸（实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由工程/文档设计改动批（直改类）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注 +12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置 +13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节 +14. **改动级验收闭合**——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §8 + +## 4. 测试执行两入口铁规（细则） + +测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。 + +**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。 + +**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**，用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿，回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。 + +## 5. MC 采集档位细则 + +四档硬闸（全表与统计精度见 `sim-data/README.md`「MC 采集档位表」）： + +| 档 | 用途 | 上限 | 触发权 | +|---|---|---|---| +| 一档·调研 | 调研/数值分析 | 总量 >40 | **只能由用户发起**——需求卡片/计划书/agent 均无权授权 | +| 二档·数值修改验证 | 改数值前后取证 | 总量 ≤40、每档 ≤20 | 数值验证场景 | +| 三档·小调 | 只测不判 | 总量 ≤20、每档 ≤10 | 数值验证场景 | +| 四档·微量 | sanity 门，零统计判读 | 总量 ≤5 | 数值验证场景 | + +配套纪律：超档=停机呈报，窗口不足如实挂起，禁在二/三/四档下带值结论；改前/改后锚同 seed0 配对、改前锚留盘禁补跑；逐项比对断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC；四档仅承接数值验证场景，两入口铁规不变。 + +## 6. 闸机轮次纪律 + +1. **孤立验证先行**——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验 +2. **调试期最窄确认**——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可 +3. **长批试车**——≥2 分钟的跑批（逐位逐项比对冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批 +4. **开工坑册扫描**——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等） + +## 7. 像素结构件工作纪律 + +1. **先抄后造**——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径） +2. **验完成径写成像素级视觉判据**——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感 +3. **±1px 一律坐标推导**——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错 +4. **修复默认附前后对比图+像素审计**，不等用户索要 diff --git a/reports/审核-待办清单属性面-2026-10-25.md b/reports/审核-待办清单属性面-2026-10-25.md new file mode 100644 index 00000000..7de015d8 --- /dev/null +++ b/reports/审核-待办清单属性面-2026-10-25.md @@ -0,0 +1,192 @@ +# 审核-待办清单属性面-2026-10-25 + +**接收方**：`待办清单.md` 条目格式审核（多轮进行）→ 结论落 `design/engineering/doc-conventions.md` §12.1 ＋ `tools/pipeline_gate.py` ＋ 技能 `req-card`（三处同改，待用户逐条发令） + +**用途**：逐属性审核待办清单条目格式。每轮审一个属性，结论只写本文件一张表；全部审完再一次性落规约与闸件，本文件届时按吸收即死退役。 + +**权威口径**：格式与状态机 = `design/engineering/doc-conventions.md` §12.1；机检 = `tools/pipeline_gate.py`（文档域闸件）。 + +## 一、属性全集与实际含义（2026-10-25 实测盘面） + +盘面规模：`待办清单.md` 共 69 条 `#### 条目`。 + +### 标题层（登记元数据，登记后禁改） + +| # | 属性 | 规约定义 | 实际作用 | 机检 | +|---|---|---|---|---| +| 1 | 条目名 | 尖括号处按实际填写 | 人读的标题 | 不检内容 | +| 2 | 登记日期 `登记` | 标题必填元数据 | 条目年龄；写卡段与反哺点按日期筛 | 检格式 | +| 3 | 来源＝四选一 | playnote／会话提及／审计发现／批次移交 | 这条从哪来，决定要不要指认证据 | 硬枚举（pipeline_gate.py:109-124） | +| 4 | 设计面＝五选一 | 文档轨／美术轨／双轨／工程直入／反哺点 | **选状态词表**：走哪条设计轨、闭合凭据核什么 | 硬枚举＋驱动状态校验（:119-124、:192-205） | +| 5 | 优先级＝（盘面出现 1 处） | **规约无此字段** | 待办清单.md:102 手写 `优先级＝**绝对**` | 不检，属越界写法 | + +### 正文层（规约称「四属性」，随进程演进） + +| # | 属性 | 规约定义 | 实际作用 | 机检 | +|---|---|---|---|---| +| 6 | 现状 | 关联文档清单，一行一件：类型＋路径＋版本号日期 | 证据落点：设计定稿／需求卡片／art-bible 条款／工程债证据，全写这里 | 检存在性；文档轨闭合与反哺已写入要在此核到「带版本号的文档路径」；工程直入要核证据 | +| 7 | 缺口 | 还差哪一次设计讨论／哪份设计产物才能写卡 | 未闭合设计轨的唯一可见标志 | 条件必填：未闭合态必须有，闭合后禁残留（:277-282） | +| 8 | 归属 | 主责系统文档或线别 | **盘面三种写法混杂**：文档名（:13）／目录线别＋批类型（:38）／文件路径（:72） | 只检行存在，内容不检 | +| 9 | 状态 | 按状态机取词，状态段累积制用＋连接 | 流水线走到哪一段；履历供编排四查与开工核验比对 | 白名单逐段校验＋按设计面核前置与段数 | + +### 标记与容器（不算属性，同属条目格式） + +| # | 名称 | 定义 | 机检 | +|---|---|---|---| +| 10 | 〔用户特批 YYYY-MM-DD 跳过××〕 | §12.4 流程格式例外的唯一放行凭证，必带日期 | 见合法标记放行对应判据 | +| 11 | 状态词后缀（备选） | 备选库条目，暂不排期 | 去后缀后校验状态词 | +| 12 | 节头注记 `> **节头注记（日期 用户拍板）**` | 分组级拍板记录，服务整节条目 | 不检 | + +### 盘面自造字段（规约外） + +| # | 名称 | 情况 | +|---|---|---| +| 13 | `**预计改动面（两档…）**` | 待办清单.md:46 一处，等于第五属性名。规约无、闸不认、其余 68 条无同款 | + +## 二、待改内容登记 + +### 条目 1：新增「改动面」属性（2026-10-25 用户提出，待裁决） + +**用户诉求**：登记一条待办时就要能看出这条要动哪几个面——**文档／美术素材／游戏代码／工具代码** 的不同组合。 + +**现状差在哪**：现有属性没有一个表达这件事。 +- `设计面` 是「走哪条设计轨」，不是「动什么」：游戏代码与工具代码在它这里合成一个词 `工程直入`（真实对照：待办清单.md:68 测试宿主改名＝游戏代码、:31 S9 类型闸修复＝工具代码、:76 level.tres 表尾注释＝数据文件，三条同写 `设计面=工程直入`）；`双轨` 一词已被「文档轨＋美术轨」占用，写不出「美术＋游戏代码」这种组合。词面也误导——「设计面」读起来像「设计范围／画面」，与实际语义「设计条线」无关。 +- `归属` 定义是主责文档/线别，写不写路径全凭会话顺手，无词表无机检。 +- 真正机检代码域/文档域的地方在批末：按 diff 路径推域决定 `run_all_gates.sh` 跑 `--code`／`--docs`／全量（process-conventions §3.9），登记时不声明。 +- 四面组合第一次成文是在需求卡片的「关联文档同步面」节＋「改动—验收对照表」，比登记晚两段。 + +**建议做法**：正文加第五属性 `**改动面**`，词表四选多、用＋连接（文档／美术素材／游戏代码／工具代码），登记即必填；闸检词表合法性。 + +**会动到的面**：① `doc-conventions.md` §12.1 四属性模板与段落；② `tools/pipeline_gate.py`（`ATTR_LINE_RE` :66、必填属性表 :232、新增词表校验）；③ 技能 `req-card`＋`doc-design` 的登记格式（`.zcode` 原件与 `.qoder` 副本两处）；④ 存量 69 条回填。 + +**未决点（裁决后才开工）**： +1. 词表要不要第五位「数据文件」——`.tres` 表在 `game/data/tables/`，按现行域划分属代码域，但玩法数值不是代码；待办清单.md:76 那条动的就是它。 +2. 存量 69 条是全量回填、还是只回填「已写卡及之后」的条目、旧条目按登记日期豁免。 +3. `改动面` 与 `设计面` 要不要建立约束关系（例：`设计面=美术轨` 的条目 `改动面` 必须含「美术素材」），还是两者完全正交、各写各的。 + +**验证方式**：改闸件后按撤销证明口径——把某条 `改动面` 写成词表外自造词、删掉某条 `改动面`，两项都必须见红；还原复绿。闸件自身改动不占合回全量（人工确认闸可跑通＋口径未变）。 + +**估时**：规约＋闸件＋技能约 0.5 个工作日；69 条回填另计，取决于未决点 2。 + +### 条目 2：`优先级` 转正为登记元数据（2026-10-25 用户裁决保留） + +**用户诉求**：有些事项就是非常紧急，优先级要保留；但**不设默认值差异**——没写就是统一默认级；优先级的设定来源只有用户本人，其余一律默认。 + +**现状差在哪**：优先级现在是规约外写法。`doc-conventions` §12.1 标题模板无此字段，`pipeline_gate.py` 不认；盘面仅 [待办清单.md:102](../../g-plan2/待办清单.md) 一条手写 `优先级＝**绝对**`，词表没人定过（「绝对」是哪来的、还有没有别的档，全部无据）。缺的是一句来源约束：谁有权写。 + +**建议做法**：标题模板加可选元数据 `优先级＝<档名>`，规则三条——① 不写＝默认档，条目之间不排序；② 只有用户明示才写，会话禁自行给任何条目升档；③ 档名走白名单，禁自造。词表待定（未决点 4）。 + +**会动到的面**：`doc-conventions.md` §12.1 标题模板＋新增一句来源约束；`tools/pipeline_gate.py` `check_title`（:109-124）加「写了才校验、且须在白名单内」；概念说明同步——`design/engineering/concept-conventions.md` 或 §12 引言需有一句「优先级＝用户对紧急度的单方面标记，与流水线状态机无关，不参与开工门与编排判据」，否则下游会把「绝对」读成排期依据。 + +**估时**：与条目 1 同批改，闸件＋规约约 0.5 个工作日内。 + +### 条目 3：正文属性 `现状` 改名（2026-10-25 用户裁决） + +**用户诉求**：`现状` 与 `状态` 两词撞，读者以为是同一件事的两面；而这格实际写的是具体内容（关联文档清单、证据指认、推进收口记录），名字对不上内容，要换。 + +**实况复核**：该格承载四类东西——① 关联文档清单（类型＋路径＋版本号，闭合凭据唯一落点）；② 工程直入条目的 bug/工程债证据指认；③ 必要时一句实际情况说明；④ 推进过程的收口叙述（如 [待办清单.md:25](../../g-plan2/待办清单.md) 的「2026-10-24 写卡会话收口：用户裁五件重构候选全部立项」）。机检只在这一格内核证据（`pipeline_gate.py` :241 起 `xian_lines`），其他属性不算数。 + +**改名候选（待用户选词）**：① 「实况」——与「状态」不撞，读起来涵盖①③④，闸在里面核证据也顺；② 「依据」——最贴①②但读起来不像能装叙述句；③ 「事实」——最短，但项目已有「事实源」术语（架构事实唯一源），易混。推荐 ①。 + +**会动到的面**：§12.1 模板与「四属性」称法；`pipeline_gate.py` `ATTR_LINE_RE`（:66）＋必填表（:232）＋变量名与报错文案；`待办清单.md` 69 条逐条改标签；技能 `req-card`／`doc-design`／`iter-plan` 里引用该属性名的句子；术语表若收此词。 + +### 条目 4：删除正文属性 `归属`（2026-10-25 用户裁决） + +**用户裁决依据**：当年定 `归属` 就只是想知道「这条改什么地方」；新属性 `改动面` 表达产出物范围后，`归属` 与之重复，不必存在。 + +**随删随办的残留问题（必须给落点，否则信息丢失）**：盘面 `归属` 实际写有三种内容——① 主责系统文档名（[待办清单.md:13](../../g-plan2/待办清单.md) `[关卡节点图生成]＋[level-map]`）：这类文档路径本来就要求写在 `现状` 的关联清单里，删 `归属` 不丢信息，但要确认每条都真的在 `现状` 出现过；② 目录/线别＋批类型（:38 `tools/ 静态扫描域（闸件批，非迭代批）`）：批类型（迭代批/非迭代批）现在只在归属里说，删除后需要确认它是否由 `改动面`＋roadmap 是否占迭代号承担；③ 流程去向（:110 `卡④ §9 代拍板域 → 独立成批`）：这类是叙述，删除时要就近并进 `现状` 或 `缺口`，禁直接丢。 + +**估时**：69 条逐条判定②③有无信息缺口，是本批最耗时的一段，约 0.5–1 个工作日。 + +### 条目 5：删除标题元数据 `设计面`（2026-10-25 用户裁决） + +**用户裁决依据**：输入侧（还缺哪条设计线）已经由状态段的用词本身说明——`待文档设计`／`待美术设计` 就是缺什么设计；输出侧由 `改动面` 说明。`设计面` 夹在中间既不提供新信息，词面又误导（读成「设计范围／画面」）。 + +**删词后没有任何功能需要替代**（2026-10-25 用户纠正后重写本节；先前版本把这四件事写成「必须保住的功能」并造出 A/B 两个「通道识别」方案，属错——详见末尾《我的错误记录》）： +1. **选状态词表**——不需要选。每个状态段按自己的词校验即可：`待文档设计`／`文档设计中`／`文档设计已闭合`／`待美术设计`／`美术设计中`／`美术设计已闭合`／`待写卡`／`已写卡`／`已编迭代 N`／`待裁决`／`已写入` 这些词本身互不重叠、自带所属线。 +2. **进下游段的前置**——改判据：状态行含 `待写卡` 及以后段时，禁残留任何 `待*设计`／`*设计中` 段。这条不依赖任何声明，且比原判据强。 +3. **闭合凭据核对**——按闭合段自身的词选核对对象（`文档设计已闭合`→`实况` 里要有带版本号的 .md 路径；`美术设计已闭合`→要有 art-bible 条款版本）。键在状态词上，不在标题上。 +4. **「工程直入」与「反哺点」不 needing 识别**——它们不是需要判定的类别，只是状态段的既有形态：工程条目状态首段落在 `待写卡` 及以后、整行无设计段；反哺条目状态用 `待裁决`／`已写入`。闸要加的判据只有一条、且本来就该有：状态首段直接进 `待写卡` 的条目，`实况` 必须指认证据（bug 证据或工程债条目），缺即红。这条判据原先挂在 face 值下，现改挂在状态形态下，覆盖面不变。 +5. **新增可用性**：`改动面` 让闸能查「声明要出美术素材的条目，状态里有没有 `美术设计已闭合`」——即产出面与设计闭合之间的一致性，是 face 声明时代查不到的方向。 + +**连带面**：`doc-conventions` §12.1 标题模板＋状态机引言＋特殊通道表；`pipeline_gate.py` `FACE_WORDS`/`PRESENCE_FACES`（:27、:37）、`check_title`（:119-124）、`check_status` 的 face 参数（:157-205）、证据核对（:264-272）；69 条标题；技能 `doc-design`／`req-card`／`iter-plan`／`iter` 凡按设计面判断流程的句子（这几条技能正文里「设计面」是分支条件，属第五层指令面，必须连技能一起改）。 + +## 三、审核进度 + +| 轮 | 对象 | 结论 | +|---|---|---| +| 1 | 新增 `改动面`（#13/#4 关联） | 已登记，三项未决待裁 | +| 2 | `优先级` | 用户裁保留并转正，档名词表待定（未决点 4） | +| 3 | `现状` | 用户裁改名，选词待定（候选三，推荐「实况」） | +| 4 | `归属` | 用户裁删除，删除后的三类残留内容落点待办 | +| 5 | `设计面` | 用户裁删除，四项功能改由状态段自身承担；通道识别待裁（未决点 5） | +| 6 | 未决点 1／2／4 回文（2026-10-25 用户裁决） | 见下 | +| 7 | 未决点 5 撤案（2026-10-25 用户纠正） | 伪问题：删 `设计面` 后不需要任何替代识别机制；A/B 两案作废，条目 5 已重写 | + +## 四、定稿属性集（2026-10-25 全部裁决合完） + +标题层：`#### <条目名>（登记，来源=，优先级＝）` +— 优先级可选，不写＝P2，只有用户明示才写。 + +正文层四属性： + +| 属性 | 作用 | 必填 | 闸判据 | +|---|---|---|---| +| `实况`（原「现状」） | 这条的事实与凭据：关联文档清单（类型＋路径＋版本号）、证据指认、推进收口叙述 | 必填 | 存在性＋按状态段的闭合词在**这一格内**核凭据；首段直入 `待写卡` 的条目必须指认证据 | +| `缺口` | **输入侧**：还缺哪一次设计讨论或哪份产物才能写卡 | 条件必填 | 状态含未闭合设计段时必须有；闭合后禁残留 | +| `改动面` | **产出侧**：这条要动哪些面——文档／美术素材／游戏代码／工具代码，多选＋连接 | 必填、登记即写 | 词表白名单，多选合法，禁自造词 | +| `状态` | 流水线走到哪一段，累积制＋连接；设计线信息由状态词自身承载（`待文档设计`／`待美术设计` 即所属线） | 必填 | 段词白名单逐段校验＋顺序＋「进下游段禁残留未闭合设计段」 | + +删除：`设计面`（标题）、`归属`（正文）。保留不动：条目名、登记日期、来源、特批标记、`（备选）` 后缀、节头注记。 + +## 五、我的错误记录（本轮两条，用户纠正） + +1. **给已经定论的单点事实补了一句不相干的「佐证」**。用户问「数据文件折进游戏代码你有没有不同意见」，我答「不冲突」后又加一句「双写失同步规则会强制数值批带上文档面，所以折叠不撒谎」。那句话既不是用户问的，也说错了规则——数值的事实源在 `data/tables/`，GDD 表格只留取值域与指针，本来就不装值；两者是同一条「数值单一事实源」的两面，不是互相担保的两件事。错误性质：为一个不需要论证的结论编造支撑，把读者绕进「文档里有值」的错觉。**该答的就一句：不加第五档。** +2. **把要删的字段包装成「有功能必须替代」，据此造出一个伪问题**。我在条目 5 写「删词不等于删功能」，列出四项功能，然后把其中一项写成「两条特殊通道需要识别方式」，还给出 A（另立标记）／B（状态推导）两个方案让用户选。真相：`设计面` 没有独立消费者，它只是把状态词里已经写着的信息又在标题抄了一遍；状态词白名单本就分轨自带所属线，`待裁决`／`已写入` 也是白名单内的独立词。删掉它，四项功能里有三项是「同一判据换个键」，第四项（通道识别）根本不存在需要识别的东西——工程条目和反哺条目在状态行上就是两种不同形态。A/B 两案是在给一个不存在的缺口提供选项。**该问的只有：新属性集够不够表达输入侧与产出侧——够。** + +**判据教训（写给自己）**：用户删字段的理由是「它表达的信息已由别的属性表达」。审这类问题时只问一句「这个字段的信息，除了把它自己读一遍，还有谁消费」；答不出消费者就不许立「功能保留」，也不许提替代方案。 + +**已裁定的未决点**： + +- **未决点 1（改动面词表第五位）＝不加**。用户裁定：`game/data/tables/*.tres` 属游戏代码改动——表值直接改变游戏运行结果。词表定四档：文档／美术素材／游戏代码／工具代码。闸件路径口径与本裁定一致（process-conventions §3.9：触及 `game/` 即代码域）。 +- **未决点 2（存量回填范围）＝全面重写**。规则改完后 69 条按新格式整篇重写，不做豁免、不做增量注记。重写含四件：删 `归属` 行并把其三类内容就近安置、`现状` 标签换名、每条补 `改动面` 多选值、`设计面` 从全部标题中删除。 +- **未决点 3**：设计面已裁删除，本条自动消解。 +- **未决点 4（优先级档名）＝ P0／P1／P2 三档**。默认档：标题不写＝P2；白名单允许 P0/P1/P2，显式写 P2 与不写同义，编排与开工门不因此分档。来源约束：只有用户明示才升档，会话禁自行给条目定优先级。记号冲突处理（用户裁）：既有用法不撞名、不改——「美术资产链路审计两项 P0」这类审计报告里的 P0 指缺陷严重度，原样留底不重写；**后续任何新文档禁另立与待办紧急度无关的 P 档含义**，与本枚举冲突即违规。§12.1 仍须成文一句「P0 最高」，理由不是消歧而是枚举本身的取值方向必须写死。 + +**仍未决**（仅剩 `改动面` 词表的定义边界两件）： + +- 词表口径：技能件（`.zcode/skills/`、`.qoder/skills/` 的 SKILL.md）改动算哪一档，四档词表今天没盖住。推荐归 `工具代码`（技能是流水线的执行行为，与闸件同类，改它须连闸一起改），备选归 `文档`。 +- `文档` 一词的定义要在 §12.1 写清：一切 .md，含 `design/engineering/` 规约与根流程件 roadmap／待办清单／体验验证清单。 + +## 六、并行批撞面（本批第一遍做完后实测，2026-10-25） + +本批分支 `todo-audit-20261025` 基线＝`e5d3f212`；开工后 master 被另一会话推进两笔并合回（`9fdacdeb`＋`d67b7dad`，改动四类与两层模型全量落库，全量域闸绿）。与本批重叠的四个受版本管理文件全部被对方改过： + +| 文件 | 对方新增 | 与本批关系 | +|---|---|---| +| doc-conventions §12.1 | 直改类序列「登记 → 待执行 → 删除」；通道表拆「工程直入（需求性）＝待写卡」与「工程直入（工程性）＝待执行」；仍保留 `设计面`／`归属`／`现状` | 语义交叠＋逐行冲突：对方用「改动四类」分通道，本批用 `改动面` 四档分产出面，两表几乎一一对应（游戏代码＝需求改动／工具代码＝工程改动／文档＝文档设计改动／美术素材＝美术素材改动） | +| process-conventions §2 | 首句改造＋两层口径＋工程直入拆分 | 与本批改同一张表，逐行冲突 | +| tools/pipeline_gate.py | 状态词表加 `待执行`、状态五形态、周期校验新规 | 本批重写了状态校验段，逐行冲突 | +| 待办清单.md | 五条目状态改「待执行」、三张违形卡删除、行号位移 | 本批迁移脚本按行号索引档位，须在新盘面重跑 | +| 六份技能（不入 git） | 同批换代为改动四类 | 本批三轮技能编辑做在对方新版之上，旧词已清零；措辞「工程形态」待与最终规约统一 | + +**两案待用户点**：甲＝`git merge master` 后手工揉合两套模型（风险：揉的过程无语义机检，易两边各留一半）；乙＝在本分支上 rebase 重做（丢弃四文件文本改动，在 master 新文本上重跑同一套改动——迁移脚本与撤销证明脚本仍在 `reports/_tmp_*.py`，成本主要在 69 条档位重新点名＋闸判据重落）。推荐乙。 + +**第一遍产物**：提交 `9093ba00`（未合回、可弃）＝四文件改动＋闸七项新判据＋十项撤销证明全红＋69 条迁移全绿。 + +## 七、甲案执行记录（2026-10-25，用户否掉全量重跑后改手工合并） + +真实冲撞面实测：四文件合计 +35/−36 行、14 处 hunk（不是「全部重来」的量级）。做法＝`git merge master` 后逐处手工合，不重跑第一遍。 + +| 文件 | 合并取向 | +|---|---| +| doc-conventions §12.1 | 以本批新格式为骨干，折入对方的 `待执行` 直改序列与「需求性工程条目／直改类条目」两行形态表；§12.2 对方的冻结待凑批与周期新规原样在场 | +| process-conventions §2 | 以对方新版（改动四类＋两层口径＋估时冻结线）为骨干，属性名与设计线措辞换成本批口径 | +| pipeline_gate.py | 以 master 版为骨干（状态五形态、周期新规原样保留），再套本批的属性常量、check_title/check_status/check_todo 与 C2 文案 | +| 待办清单.md | 69 条留本批新格式；master 侧改过文的 7 条取新版正文再套新格式（三张违形卡的引用随之清出，卡片口径由 12 张降到 9 张） | + +合并后新增判据一处：证据指认的触发条件从「已进下游段且无设计段」扩为「状态整行无设计线段且非反哺点用词」，覆盖 `待写卡` 族与 `待执行` 族两类跳线条目。撤销证明 11 项全红、未注入盘面绿；文档域全量闸 `验收通过·无新增红`（07 doc_link 由红转绿），回执 commit=`5ff0d578`。 + +两处顺手清偿：条目内自造的第五属性名 `预计改动面（两档…）` 并回叙述；两处退役词（`运行期报错`→`运行期错误`、`落文`→`写入文档`）按现行规范改写。 + +一项发现（未修，供后续批处置）：`doc_term` 的「上两行留档标记继承」判读依赖行相邻关系——删归属行与插改动面行会打断继承，使旧词从留档类浮出为疑似现行。本批改的是词面而非判据；判据本身对行位敏感，属可再议的脆弱点。 diff --git a/待办清单.md b/待办清单.md index 5d94fea8..0727a7ff 100644 --- a/待办清单.md +++ b/待办清单.md @@ -1,753 +1,753 @@ -# 待办清单 - -本清单是流水线的唯一登记处：要做的事先在此登记一条，随流水线段推进改状态，做完整条删除；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据含可选优先级，正文＝实况/缺口/改动面/状态四属性）与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 - -#### 超预算图策略升级路径——等比缩放与滚动视口两案待裁（2026-10-24 登记，来源=批次移交） - -**实况**：迭代 34 卡④（信息迷雾可见性批，已合回 master，提交 16a7ec80）按「参数限图」交付，图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图，两条升级路径都要动冻结件，均未设计：①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值；②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13，已超出该上限（level-map 已登记随动缺口，本批不裁方案）。 -- 相关文档 design/gdd/systems/冒险循环/关卡节点图生成.md v1.3（调参表「图包络」行） -- 相关文档 design/gdd/ux/level-map.md（画布冻结公式） - -**缺口**：两案需用户裁决后再走设计讨论；未裁前禁改画布冻结件。 - -**改动面**：文档 - -**状态**：待文档设计 - -#### game 代码结构审查批——行为缺陷定点修＋结构重构候选（2026-10-24 登记，来源=审计发现） - -**实况**：审计报告＝reports/审计-game代码结构审查-2026-10-24.md（2026-10-24，全目录只读审查，零测试执行、结论全部静态阅读）。缺陷证据（报告 §二 Critical 行为缺陷段＋定点清单，含行号）九件：①core/damage_controller.gd:215 用 `==` 比较单位字典（Godot 4 语义＝逐键内容比较）——内容全同双敌其一死亡误作废对方单据，应 `is_same()`；②presentation/views/standee_body.gd:172/188 蓄力意图档常量错配（GOLD_INK vs GOLD_DEEP）死代码，三档运动签名设计失效且无测试覆盖；③presentation/views/battle_end_overlay.gd:281-287 庆祝 tween set_loops 无限叠加泄漏（close 只隐藏不 kill）；④批量模拟×两层调试并发互斥缺口（presentation/views/debug_overlay.gd:84＋presentation/main.gd:712-715/1489＋presentation/tune_sim_controller.gd:46-58——用户两击可并触发，演出扭曲＋测量作废）；⑤presentation/modal_stack.gd:23-29 未登记层/重复开层静默降级（违 fail-fast，当前调用面无违规者属埋雷）；⑥core/minesweeper_rules.gd:8-9 两条核心信号零契约成文（违 code-conventions §2.1）＋全库信号注释载体普遍 `#` 非 `##`；⑦明细行类型封闭枚举漂移（core 实发 13 类 vs battle_orchestrator.gd 头注 9 类）；⑧core/level_runner.gd:895/779 玩法数值字面量（relic 基价 15.0、散折 0.8，自注 provisional）；⑨presentation/views/battle_stage_view.gd:332-338 以 display_name 子串匹配解析受击目标（同名敌错位，应携带 enemy_id）。另有定点小件与结构重构候选（报告 §三）：main.gd 1508 行可判离块 ~440 行／board_view.gd 1219 行瓦片算法＋英雄精灵可拆／adventure_runner 令牌池子系统 ~500 行可拆 CurioDeck／level_runner 商店子系统 ~260 行可拆／断点 schema 三处重复登记可单点化——重构候选非缺陷，是否立项由写卡段呈报用户裁决。**2026-10-24 写卡会话收口**：用户裁五件重构候选全部立项（卡①缺陷修先行落地后重构再动）；缺陷⑦明细行枚举漂移划归「架构与规范对齐批」条目（词表 13/15 归该批裁决，缺陷卡不碰头注）；报告 §三「其余小件」（level_map 视图直读/BFS、main 死变量与 confirm 旁路、settle_batch 空判、row_pacer 常驻 flush、_fatal assert 剥离、rng_service early-return）未立项，留审计报告在册待后续点名。切卡输入＝审计报告 §二/§三，四卡均零待裁点。 - -关联文档清单： -- 需求卡片 reports/需求卡片-game行为缺陷定点修批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），缺陷修主卡·迭代批，八件缺陷＋定点小件七件，零待裁点） -- 需求卡片 reports/需求卡片-重构main判离批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），重构卡 R1·迭代批，零待裁点） -- 需求卡片 reports/需求卡片-重构boardview拆件批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），重构卡 R2·迭代批，零待裁点） -- 需求卡片 reports/需求卡片-重构runner拆件与断点schema单点批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），重构卡 R3·迭代批，零待裁点） - -**改动面**：游戏代码 - -**状态**：待写卡＋已写卡＋已编迭代 37 - -#### S9 类型闸正则失灵修复——R2 恒零命中＋static 函数漏网（2026-10-24 登记，来源=审计发现） - -**实况**：工程债证据＝reports/审计-game代码结构审查-2026-10-24.md §二 C1（已独立复现）：tools/audit_type_hints.py:29 的 FUNC_DECL 正则两洞——①无返回类型声明按 GDScript 语法必然以 `:` 结尾，正则要求 `)` 后只跟 `->`/注释/行尾，R2 目标形态 100% 失配（R2 从上线起恒零命中恒绿）；②`^(\s*)func` 不认 `static ` 前缀，static 函数对 R2/R3 整体漏网。实证存量（闸当前退出码 0）：core/level_runner.gd:632、core/attunement.gd:10、presentation/main.gd:565、presentation/views/hud_presenter.gd:10-11、core/reward_economy.gd:104/119/131/146、core/unit_container.gd:275（写卡会话路径订正：hud_presenter 实址 game/presentation/hud_presenter.gd，非 views/）。属架构文档测试域自警的「规则扫描面为空＝恒绿」静默失效模式（零命中自检因 R1/R3 仍有命中能力未拦住）。2026-10-25 规则修订（改动四类）：本件属工程改动（闸件修复，直改类）。执行口径＝修 `tools/audit_type_hints.py:29` FUNC_DECL 正则两洞（①无返回类型声明的声明形态恒失配；②`^(\s*)func` 不认 `static ` 前缀），存量以开工时盘面清点（实证九址为已知下限），验收走撤销证明。原需求卡片按违形退役：结论已回写本条目，卡片删除，全稿查 git 历史（提交 546e5113）。 - -**改动面**：工具代码 - -**状态**：待执行 - -#### S13 gdstyle 免名单把数字当身份——存量债改小也报「基线外新违规」（2026-10-25 登记，来源=批次移交） - -**实况**：工程债证据＝迭代 35 卡② 合回前后实测（master 合回笔 `5499eb9c`）。闸件 `tools/gdstyle_gate.py:82` 把每条违规登记成三元组「文件|规则|消息全文」，而 gdstyle 的消息文本里带具体数字（如 `function 'resume_adventure' is 104 lines long (max 50)`），基线 `tools/gdstyle_baseline.txt`（241 行）按整句逐字比对——**只要某函数的行数/分支数/变量数发生变化，老违规就匹配不上，被判「基线外新违规」并判红，改小也算新增**。卡② 一批即因此冒出 12 项假新增，逐条对基线旧值核实全是存量债的计数漂移：`config_db_cross_validator.cross_validate` 159→107 行／31→21 分支／39→24 局部／嵌套 6→5（本批按卡片删除跨表校验④整段所致，债变小）、`level_runner` 类变量 40→38 且其「文件 1013 行超长」违规已消失（债被还掉）、`start_level_external` 参数 8→7、`main.gd` 1509→1507、`adventure_runner` 类变量 43→42／文件 1050→1051／`resume_adventure` 104→108 行（本批加断点代差标记键拒绝检查多 4 行）。本批真正新写的超标仅 1 处（新函数 `validate_graph` 72 行／20 分支），已当场拆成四段修掉。**盘面后果**：卡② 按用户令零复跑合回，master 尖 5499eb9c 从未整套跑绿过代码域闸；下一次任何批跑代码域闸都会看到 S13 红这 12 项（不处理则每批重复一次「要么重生成基线、要么被红挡在合回前」）。卡片裁决留档（卡片已违形退役，git 历史可考）：四待裁点已拍板——稳定身份键／恶化判据超登记值即红／本批治本＋批内刷新基线／refresh 加对账自检与骤降守卫；验收按 2026-10-24 撤销证明口径执行。2026-10-25 规则修订（改动四类）：本件属工程改动（闸件修复，直改类）——原卡片按违形退役，结论已回写本条目，卡片删除，全稿查 git 历史（提交 36b444eb）；执行口径＝治本档（四待裁点已拍板项照录上文），用户发令直改。 - -两档方案（第一条只治标）：① 治标＝人工跑一次 `python tools/gdstyle_gate.py --refresh` 重生成基线＋一笔提交，约 5 分钟，但键形态未改，下一批再动这些文件还会重演；② 治本＝改 `tools/gdstyle_gate.py` 的键构造段（:77-90，约 10–20 行）为「文件|规则|函数名」——函数名从消息里正则提取 `function 'x'`，无函数名的条目（类变量数/文件长度）退化为「文件|规则」，并**另加一条恶化判据**防新键吞掉真问题（同一函数当前指标较基线登记值恶化超阈值即判红，纯规范化数字会把 104→300 行的恶化也放过去，不可只靠数字抹平）；随动＝重生成 `tools/gdstyle_baseline.txt`（241 行按新键重排）、`tools/run_all_gates.sh` 头注与 `game/tests/README.md` 工具速查表的 S13 描述各一行、撤销证明四项（新增一处真超标必红／同函数改小改大的数字漂移禁止再冒新／恶化超阈值必红／禁闸内自动重生成清基线换绿的自检仍绿——各配撤销该判据见红＋还原复绿）。合计约 **0.5 个工作日**，工程改动（tools/ 闸机面）直改类。 - -**改动面**：文档＋工具代码 - -**状态**：待执行 - -#### S6/S7/S8 静态规则落地——编排唯一性/禁 await/信号纪律三闸（2026-10-24 登记，来源=审计发现） - -**实况**：工程债证据＝reports/审计-game代码结构审查-2026-10-24.md §二 C2：三规则 static_scan.sh TODO 在案（架构文档静态扫描表自认未落地）——S6 core↔core 信号禁 lambda 捕获 self、S7 B2/B3/B4 API 符号命中文件 ⊆ B1 文件集、S8 结算路径 await 零命中。2026-10-24 审查人工 grep 结论干净（core 零 await、A2/B3/B4 零相互直调），但防线缺位＝回归无闸。S7 前置：须先在架构文档成文 B1 文件集边界（含 core/settlement/ 五段类与 damage_controller——现归属表零条目，见「架构与规范对齐批」条目①）。**2026-10-24 用户裁：条目整条冻结待④（「架构与规范对齐批」）裁决后再写卡**——写卡会话核对结论：S6（core 信号禁 lambda）与 S8（结算路径禁 await，文件集可按现行结算文件直接枚举）与④零依赖、技术上可先行，但按「先裁④再动③」整条冻结不先行。 - -**改动面**：工具代码 - -**状态**：待写卡 - -#### 验证集清单快照重生成——断言索引含退役措辞与旧行号（2026-10-25 登记，来源=审计发现） - -**实况**：工程债证据＝迭代 35 卡② 验收审计申报（git 历史可考：合回提交 5499eb9c 内的 reports/iter35-卡②-验收审计-2026-10-24.md，该产出物已按吸收即死退役）：game/tests/验证集清单.md 是批 B 迁移时的断言文本快照索引，只由 tools/extract_checks.py 手工重生成、不进任何闸；卡② 断言面换代后十余行仍含 first_script／template_pick 等退役措辞与过期行号（实测 first_script 8 处、template_pick 2 处），与宿主现文不符。2026-10-25 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝走重生成：tools/extract_checks.py 两小改（头注模板数据驱动化＋新增 --carry-from 按同指纹承接「白话释义／处置」两列、承接文本内旧宿主文件名映射为新名）后 --extract --force 重生成（缺省三宿主全量口径；实测漂移＝清单 1067 条 vs 现提取 1544 条〔消失 67／新增 539／字面变更 14 对〕，template_pick 实测 3 处——登记句「2 处」少数一行），--diff 须 PASS；重生成后 grep node_map_templates／first_script／template_pick 预期零命中（若命中须全为反向断言）。原需求卡片按违形退役：结论已回写本条目，卡片删除，全稿查 git 历史（提交 1fb44cf4）。 - -**改动面**：游戏代码＋工具代码 - -**状态**：待执行 - -#### 测试宿主改名——node_map_templates_test.gd 已承载生成图确定性断言（2026-10-25 登记，来源=审计发现） - -**实况**：工程债证据＝迭代 35 卡② 反哺点⑧：game/tests/integration/node_map_templates_test.gd 现承载「生成图确定性断言套」，文件名中的 templates 是模板时代遗留；manifest 登记行＝game/tests/run_all.gd:90。改名为 node_map_determinism_test.gd 须同批改 manifest 路径行。2026-10-25 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝git mv 宿主两件（.gd＋.uid）＋改 run_all.gd:90 路径行＋文件内 4 处自引用字面量（:1/:10/:26/:31），断言判据零改动，直跑新名退出码 0 为验收。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。 - -**改动面**：游戏代码 - -**状态**：待执行 - -#### level.tres 表尾注释含迭代叙事（2026-10-25 登记，来源=审计发现） - -**实况**：工程债证据＝迭代 35 卡② 反哺点⑨：game/data/tables/level.tres 表尾注释写「旧 15 张模板池（3 关 × 5）随迭代 35 卡② 清出」，与 doc-conventions §5 禁写变更叙事有张力；卡② 卡片 T3 明令表尾写模板去向注记，故处置面限于叙事形态（删迭代号、保留图源换代事实句），不删去向事实。2026-10-25 规则修订（改动四类）：本件属工程改动（数据表注释维护，直改类），执行口径＝条目原裁（删迭代号、保留去向事实句、表内零改动）。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。 - -**改动面**：游戏代码 - -**状态**：待执行 - -#### 架构与规范对齐批——代码结构审查发现的文档-实现漂移（2026-10-24 登记，来源=审计发现） - -**实况**：审计报告＝reports/审计-game代码结构审查-2026-10-24.md（§二 C3/C4/C5＋§三 漂移清单）。漂移与待裁件七件：①架构文档「模块归属」多行 API 清单与实现不符（A2 try_* 便捷形/B2 ambush_grant_plan/B4 equivalence_supply 不存在；实有 grant_reserve_ap/finish_round_stop/check_skill_unlocks 未登记；damage_controller 与 settlement/ 五段类零条目——S7 落地的前置）；②code-conventions §1.3 核心写调用位置——三拆件控制器（presentation/curio_interact_controller.gd、camp_shop_presenter.gd、treasure_interact_controller.gd）持写调用 vs 规范「只允许在组合根出现」的 spec-AC 冲突，须裁「改规范成文组合根家族」vs「调用收回 main」；③A3→EffectEngine 反向依赖（core/action_economy.gd:43-49）——真违约或事实源失真二选一（effect_engine 降层登记基础层 vs B1 代发 vs 仅补登记）；④架构文档 :149/151 层合同计数写死 17 项 vs LAYER_CONTRACT 实 18 项；⑤明细行协议三处三个数（头注 9/实发 13/架构文档 15）；⑥§1.3 例举 submit_window_selection 符号已退役；⑦core/effect_engine.gd:360 校验文案「9 项」实为 18 项。 - -**缺口**：一次 doc-design 会话逐点裁决（②③有方案取舍须用户拍板，①④⑤⑥⑦为机械对齐）；裁决后走文档设计改动直改写入 design/engineering/。 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 死断言候选三条处置——照迁禁删断言的退役或改判待裁（2026-10-25 登记，来源=批次移交） - -**实况**：批 B 断言迁移施工验出三条死断言候选（照迁禁删，宿主在座、结构复核通过、拦截能力未证——执行序遮断或执行前提在本机不可达）：① V2-s4 旧单档迁移不变式 `game/tests/system_test.gd:185`（本机磁盘态已固化，可红面「旧档在而槽 1 缺」在生产码变异下不可达；补审 A-2 已补结构例外标签——迁移逻辑本体由 save_manager_domain v0 迁移链断言覆盖）；② V3g 营地入口缺失 `game/tests/system_test.gd:481`（menu campbtn 置 null 后 boot 信号接线先崩，护栏在执行序上被遮断不可达，拦截语义由 boot 崩与前置断言代偿）；③ 区间行上下阶实际流动 `game/tests/unit/core/board_gen_reward_test.gd:297`（守面 `samples` 与 `seen[rid].size()` 为同一字典同引用恒假，系源码自带的测试侧死逻辑、非生产缺陷）。证据＝批B迁移账本 :238/:241/:273（账本已退役，考古＝git 历史——删除批 53075baa，删除前全稿见历史版本 5644d30c）＋冻结基点 `game/tests/验证集清单.md` 头注（commit 1aea9397）。另：核代码补审 C-2～C-6 五件测试增强候选原登记备查于账本 §十五，随账本退役并入本条备查——C-2 计数闸残缝（visible 标志位≠渲染面，隐藏匿名旧钮接回双闸漏过）、C-3 _stage_faces extra 静默吞键（match 无默认臂）、C-4 顺序耦合无守卫（boot_chain 须先于驱动执行；lifecycle_matrix 永久改写槽模板不还原）、C-5 camp 残留档使 V3g 红的原因标注误导（不静默）、C-6 V1a 候选表与 LAYER_CONTRACT 双维护（新增层忘登则漏检盖顶回归）。 - -**改动面**：游戏代码 - -**状态**：待写卡 - -#### 营地五界面窗口化批——营地功能页点开后的呈现形态（2026-10-22 登记，来源=会话提及） - -**实况**：营地场景图（卡④）把旧四柜台换成「一张可点击的场景图」，从场景图点进去的**五个功能界面**——锻造工坊／秘宝匣／天赋树（树淬炼）／奖励格图鉴／生涯记录——其**呈现形态尚未定稿**：是各开独立全屏页（生涯先例），还是作为**窗口**打开（场景根留底）。**作者 2026-10-22 明示意图＝窗口打开，不是全屏页**。该形态原属卡④ §9 代拍板白名单第 2 条（非用户裁、且「缩放虚化」第三形态禁批内自选），故单独立批，不在美术设计段定值。 - -**依赖（单向）**：**强依赖卡④**（场景图素材定稿 + 五界面入口改挂）完成；卡④不依赖本条 ⇒ 排序在卡④之后。**与「营地美术素材怎么生成」无关联**（不影响出图／分层／提示词）。 - -**缺口**：① 窗口形态与叠层规则定稿（独立全屏页＝场景根隐藏／单一内页切换＝场景根留底）；② **窗口化＝场景根留底 ⇒ 会引出「背景要不要压暗／虚化」**，而该点撞上 art-bible §2（2026-10-22 缩窄后**仍禁情绪表达**，背景压暗属氛围表达仍在禁区）与卡④「缩放虚化禁批内自选」——**须在该批开工前一并裁掉**；③ 五界面各自的返回／关闭钮（卡④ v1.1 已承诺各带一个）。 -- 相关文档：卡④ §9 代拍板域 → 独立成批（呈现层＋文档线）；窗口形态与叠层规则写入 `LAYER_CONTRACT` 与 [camp](design/gdd/ux/camp.md)「叠层与开合」节 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 验收闭合规则——下一次迭代实测评估（2026-10-21 登记，来源=审计发现） - -**实况**：2026-10-21 已改工作流技能与规约——[测试规范](design/engineering/test-conventions.md) 新增 §9（改动—验收对照表、真实入口、撤销证明、禁削弱、独立验收审计），[AGENTS.md](AGENTS.md) 硬性红线新增「验收闭合」，`req-card`／`iter`／`batch-closure` 三份技能同步，[流水线闸](tools/pipeline_gate.py) 新增 C3 卡片结构检查。规则文本已落地，还没在真实迭代上跑过。 - -**改动面**：文档 - -**状态**：待裁决 - -#### UI 贴图重构批——元进度件仍是程序化占位（2026-10-13 登记，来源=审计发现） - -**实况**：营地的柜台场景贴图与元进度图标目前都是程序化画出来的临时形态，没有上贴图。这条债原先只写在美术侧的资产清单里（[美术资产清单](design/art/art-assets-checklist.md) 第 134 行与第 175 行，原文注明"营地现为程序化占位，状态记录 121⑧ 口径，排期归 UI 贴图重构批"），2026-10-13 由 UI 美化三层诊断转立本清单专条。规格其实已经定了——烛光黄 `#F6C667` 配木色 `#8A5A34`（见 [美术圣经](design/art/art-bible.md) §4.4），素材来源允许走"通用图标改色复用"这条低成本渠道。2026-10-21 用户裁营地交互重做五卡整体列入 Alpha：营地柜台贴图随之转入卡④营地场景图新建批（新场景取代现四柜台覆盖层），本条只余元进度件贴图终稿，排 Beta。 - -**缺口**：还差一次「自己画 vs 找 CC0 素材改色」的美术裁决（见 [美术资产清单](design/art/art-assets-checklist.md) §0 的复用渠道闸），裁决后才能定素材工单写卡。 - -**改动面**：美术素材＋游戏代码 - -**状态**：待美术设计（备选） - -#### 战斗一屏样张 P0 未开工——界面成品是否过审的那把尺子还没建（2026-10-13 登记，来源=审计发现） - -**实况**：[美术圣经](design/art/art-bible.md) §7.1 明文写着"程序化占位＝临时态，任何屏的终稿闸＝§1.4 整屏样张过闸；占位态禁止跨里程碑"。而 [美术素材状态清单](design/art/art-status-checklist.md) 把「战斗一屏样张」这件最高优先级的素材标的是**未开始**——也就是说，**判定界面美术算不算过关的那把尺子到现在还没造出来**。2026-10-16 曾编入迭代 30 卡②（UI 呈现三卡批序位②），2026-10-17 用户裁定不满足「迭代＝代码实现批」的开发条件、剔除回待设计（理由＝样张交付物本身就是设计规格，正式字体与素材均未定稿；同日样张批开工已被用户终止）。v1.4 旧卡留 reports/需求卡片-战斗一屏样张批-2026-10-16.md 作素材，非已写卡状态，重启不得直接开工。Alpha 出口裁决：列入 Alpha 硬前置——站桩帧动画的定版前置与主角＋三 Boss 重产都依赖它。 - -**缺口**：还差「设计讨论→需求澄清→美术定稿」一轮设计（样张即设计目标图，产出尺寸档/色板/明度档清单反向给素材批），定稿后重新立卡方可开发。旧卡 v1.4（reports/需求卡片-战斗一屏样张批-2026-10-16.md）在册但非已写卡状态，其前置未完成三件：①这一轮设计未做，样张的目标规格清单没有来源；②战斗一屏所需素材未定稿（前置里的正式字体半边已定稿——2026-10-24 用户裁 Fusion Pixel 单套即终稿，见 [美术圣经](design/art/art-bible.md) §7.4）；③2026-10-17 用户已终止该批开工，重启须重新立卡。 -- 相关文档：美术线（战斗一屏样张的验收标准归 [战斗表现](design/gdd/systems/战斗循环/战斗表现.md) 与 [美术圣经](design/art/art-bible.md) §5.1 共裁） - -**改动面**：美术素材 - -**状态**：待美术设计 - -#### UI 氛围层与九宫格切片观感修——光柱硬边与面板切片错位（2026-10-13 登记，来源=审计发现） - -**实况**：原两处，一处已修一处存续。①光柱硬边**已修**（2026-10-14 迭代 26 T4：`ui_kit.gd` 第 263 行起的光柱贴片改带内 alpha 0→0.05→0 三角过渡＋纵向衰减上亮下暗，grilling Q7 裁连续 alpha 方案；LINEAR 白名单已随反哺入册 art-bible v3.14 §8.2）。②九宫格切片错位**存续**——结算屏与图例屏的面板边缘可见错位小方块，成因是九宫格切片参数与素材尺寸不匹配（仪式石框 258 字节小图按 12 像素切片、石板亮面板 314 字节按 16 像素切片，铺到四百多像素宽面板中段拉出错位），须先核素材尺寸能否撑住新切片值（border_stone/panel_stone 均 48×48），可能要重出素材，归「UI 贴图重构批」后续贴图批次。 - -**缺口**：还差「UI 贴图重构批」里的素材尺寸核对与「是否重出素材」裁决，才能定切片修法。 - -**改动面**：美术素材＋游戏代码 - -**状态**：待美术设计 - -#### 旧行为 MC 行为锚全数作废——重锚归数值批（2026-10-06 登记，来源=批次移交） - -**实况**：案C 地图伤害账殿后批（git 7ef18ac，状态记录 371）改变每轮结算行为序——授予段不再兑付任何伤害（伤害形态单据暂存至战斗段末，段内序＝主角先手→逐敌还手→地图账），既有全部 MC 行为锚与基线逐项比对锚所锚行为已不存在，**全数作废**；新段内序断言已入冒烟闸。按 sim-data MC 缓存层规则（无数值调整禁重跑），重锚不在改动批执行；重锚前一切 MC 旧读数只作历史存档，禁止与新行为逐项比对。M4 数值批卡 v1.2 已收该义务（F19：对拍锚按案C 新序重推导、T6 四带复算按新行为首采立新锚）。 - -**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 - -**改动面**：文档＋游戏代码 - -**状态**：待文档设计 - -#### 双层 BD 延期与备选内容总登记（2026-10-03 登记，来源=批次移交） - -**实况**：需求卡片/整合定稿系中间文档，落地完成后按吸收即死退役——用户令「只删除已完成落地的内容」，本条自承载全部**未落地**内容防丢失（每项自包含，不依赖指针）。 - -**二期件组**（触发＝迭代 12 出口读数+用户点名立项；各件机制形态已定，数值 provisional）： -- **战斗→扫雷跨阶段回流**（穿刺流）：击杀轻甲敌人返还 1 AP——战斗收益反哺开格动机；AP 经济新管道，谨慎件（威胁红线③边缘，立项须专项论证） -- **穿甲锥**（穿刺×封印协同桥）：对被控制危险格的敌人穿刺伤害再提升 -- **孤注一掷**（普攻流二期锚点件）：每轮攻击次数减至 1、该次伤害大幅倍增——攻击频率规则改写 -- **悬浮魔法球**（魔法流二期）：轮末召唤物环绕，每轮自动对最强敌人造成魔法伤害——需战斗单位系统新增实体类型（召唤物/持续伤害源） -- **商店置换服务「符文重铸」**：攻击类型族后期流派转换（花 GP 重掷攻击类型相关件）——商店新交互 -- **件派生动词白名单（非信息类）**：移除封印印记回收返 AP/定向熄灭伤害型地形格/重掷 RAP 等第三盘面动作——**触发条件＝件池 ≥30 种后玩家仍反馈操作重复且定位在操作层（非决策层）**；信息类派生动词维持全禁（R4 甲，见下备选组） -- **三期：合成进化**：两件同名/同标签件合成升品（Ball x Pit 式）——池深不足时的解药，三期再议 - -**淘金流立派缓议**（定位＝支撑引擎非胜利条件；触发＝先作件族挂配套池观察、数据支持后再立派）：吝啬鬼账本/金脉共鸣（每持有 ~N GP 攻击 +~X——GP 进伤害公式新缩放源）/贪婪契约（商店折扣+GP 掉落增税，正负双修）/消费回馈（商店购买附赠同类临时增益）/战利品鉴定（三选一必含 1 件高稀有度）。 - -**R4 乙备选案（2026-10-03 用户裁甲＝信息型永不对冲，本组冻结）**： -- 信息型清除工具件族（「除尘风箱」类：限价限量清除藤蔓/烬覆/矿尘遮蔽、恢复数字） -- 深挖钻头原案（开出深层资源、代价＝「危险格位置信息 −1」主动吃信息税——现行已改设计为非信息税形态：代价候选＝额外 ~1 AP 或踩雷惩罚加重） -- 「概率收窄」类派生动词（花 AP 把某格是雷的概率收窄，非确定信息） -- **重启条件＝R4 复查闸读数支持（信息型挫败信号，T10 呈报）+用户显式放宽红线①边界**——本组重启属红线变更，须用户发起 - -**设计知识存续口径**：七流派完整件表/逐项反例条件表/天赋树后备语言（哈迪斯 2 预算制扩容/邻接树改型/GP 价格通胀防线）存整合定稿，随实施批文档吸收迁入各 GDD 权威文档（元进度/node-reward/战斗结算/地形变异/行动经济/秘宝边界句/商店 spec）——**吸收完成前定稿不删**；喂雷流待办见「旧行为 MC 行为锚」条所在批次的历史登记。 - -**缺口**：全组为备选库：各件启用须用户发令立项，届时按件走设计讨论定机制形态与数值（二期件组机制形态已定、数值 provisional；R4 乙组重启属红线变更须用户发起）。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 扩展节点类型——危险/精英节点与特殊地形节点（2026-10-21 登记，来源=会话提及） - -**实况**：用户 2026-10-21 会话定方向：Alpha 版只留现行四类（战斗/奖励/恢复/商店），以下两类留到以后再做——①危险/精英节点（怪物与普通战斗不同、奖励肥）；②特殊地形节点（效果修饰：地图战斗资源、敌我伤害、金币比例等）。内容未设计。 - -关联文档清单： -- 相关文档 design/gdd/systems/冒险循环/关卡节点图生成.md v1.1（2026-10-21，扩展节点类型位概念） - -**缺口**：两类扩展节点的机制形态与数值未设计（用户明示暂不进 Alpha）。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 天赋树实装批登记欠账余两件——AP 上限 clamp 与三选一刷新软上限（2026-10-12 登记，来源=批次移交） - -**实况**：迭代 21 天赋树实装批顺带入册欠账三条，2026-10-13 三件终态：① **AP 上限 clamp 缺位（缺陷）**——树「开局姿态」（每关首轮 AP+1）、AP 件、时沙同走 `action_economy.gd:239 _pending_ap_delta` 排队，轮始兑现仅下限钳制（`:254 maxi(0, …)`，无上限）；**用户裁暂不设上限**——provisional 天花板亦不投，随未来数值标定窗口连同全部 AP 数值统一标定（M4 数值批已废）。② **三选一刷新软上限（设计问）**——停点内 GP 付费刷新倍率增长（×1.8/次曲线）×停点间基础价随进度递增，全程无软上限；**定性确认＝设计问非缺陷，用户裁维持现状**，归未来数值标定窗口处理，不提前单开讨论。③ **Y（_attune_refresh_y）不入断点存档（可利用漏洞）**——已修复注销（2026-10-13 用户令提前单独开修：断点快照扩列 `attune_refresh_y`＋续玩 `resume_adventure` 优先读断点〔缺键回退参数面＝旧档行为零变化〕＋单测两断言；冒烟 938/0+单测 24 套全绿）。①②留待办清单待未来数值标定窗口（M4 数值批已废；2026-10-18 用户裁＝不另行归属、未设计未启动）。 - -**缺口**：还差未来数值标定窗口的标定执行（M4 数值批已废；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属）。 -- 相关文档：① [行动经济](design/gdd/systems/排雷循环/行动经济.md)；② 行动经济+三选一/商店刷新经济（数值归未来数值标定窗口——M4 数值批已废）；③ [存档序列化](design/gdd/systems/表现与支撑/存档序列化.md)（断点域）+ [冒险结构](design/gdd/systems/冒险循环/冒险结构.md)（续玩参数面）——③已修复注销 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 棋盘战斗键盘/手柄输入（2026-10-04 登记，来源=会话提及） - -**实况**：战斗棋盘操作现行唯一输入＝鼠标——左键已开格＝移动/未开格＝挖掘，右键＝封印（封印印记一次性承诺，无移除手段），悬停承载合法性反馈（可挖域微光 + BFS 路径点迹）；全仓无 InputEventKey/JoypadButton 处理，project.godot 无自定义 InputMap 动作。**可行性已核（2026-10-04）：可做**——分发接缝现成，board_view `action_requested(cell, kind)`（kind ∈ {dig, move, flag_place, flag_pull}）是唯一出口，键盘/手柄作第二输入前端产出同款信号即可，规则引擎合法性校验零改动；Godot InputMap 原生支持键盘与手柄绑定同一动作，与鼠标并存不冲突。用户期望操作形态：十字方向移动；挖掘/封印各一独立键；方向控制选定 8 向挖掘或封印目标（8 向恰与现行可挖域同集，十字移动与立绘 4 向既有裁决一致）；键盘移动语义＝逐格步进。连带设计点四条（实施批先裁）：① 键盘模式需屏上光标格承载现行悬停反馈；② 键盘默认键位与手柄键位映射待定；③ 弹层界面（结算/三选一/商店/设置等）现行全鼠标，手柄全覆盖需焦点导航——是否同批待裁（2026-10-06 增补：暂停层〔现状态面板〕Esc 快捷通道并入本条随键盘批统一实施，弹层清单 +1 项）；④ 键位自定义是否进设置面待裁。排期 Beta（2026-10-04 登记；可行性已核毕，立项时按 roadmap 开卡）。 - -**缺口**：还差 Beta 立项时的输入方案设计讨论——四个连带裁决点（光标反馈承载/键位映射/弹层焦点导航范围/键位自定义）先裁再开卡。 -- 相关文档：[排雷玩法](design/gdd/systems/排雷循环/排雷玩法.md)（动作语义与 8 向目标规则主责）+ [HUD 框架](design/gdd/systems/表现与支撑/HUD框架.md)（键盘光标与合法性反馈呈现）+ [设置与本地化](design/gdd/systems/表现与支撑/设置与本地化.md)（键位自定义，可选面） - -**改动面**：文档 - -**状态**：待文档设计 - -#### 技能池情境条件触发器（2026-10-18 登记，来源=会话提及） - -**实况**：低血触发防御、玩家停手时的偷袭技等情境出招——载体＝技能行触发条件字段（P1 字段位已预留）；启用是敌人系统修订，不是调参。（原条目无登记日期，按本批格式整改补登 2026-10-18。） - -**缺口**：还差敌人系统修订的设计讨论——情境触发器的条件形态、字段语义与首批触发器清单。 -- 相关文档：[敌人系统](design/gdd/systems/战斗循环/敌人系统.md)（P1） - -**改动面**：文档 - -**状态**：待文档设计 - -#### 个体化变体池（2026-10-18 登记，来源=会话提及） - -**实况**：A 型好斗/ B 型守势、精英专属池（技能池共识点 A 的 A2 案）；现行同敌种同池模板，实例分歧只来自摇号涌现。（原条目无登记日期，按本批格式整改补登 2026-10-18。） - -**缺口**：还差敌人系统的变体池设计讨论——A2 案的池构成方案与精英专属池边界。 -- 相关文档：[敌人系统](design/gdd/systems/战斗循环/敌人系统.md)（P1） - -**改动面**：文档 - -**状态**：待文档设计 - -#### 全局特殊间隔旋钮（2026-10-18 登记，来源=会话提及） - -**实况**：异名特殊技背靠背现行概率低（是变化不是失控）；若实测仍嫌，备用闸＝全局「特殊技后至少隔 N 拍」——登记备用，未实测不启用。（原条目无登记日期，按本批格式整改补登 2026-10-18。） - -**缺口**：还差备用闸的条款设计（N 值与作用域）——仅当实测读数支持时才启动讨论。 -- 相关文档：[敌人系统](design/gdd/systems/战斗循环/敌人系统.md) 与[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md)（P1） - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 敌方技能图鉴 / 学习呈现（2026-10-18 登记，来源=会话提及） - -**实况**：池与权重不公开（D4/D5）口径下的进阶信息面——玩家侧技能知识系统（见过 → 认得 → 记谱）；首发三池学习成本低，后置（P2）。（原条目无登记日期，按本批格式整改补登 2026-10-18。） - -**缺口**：还差玩家侧技能知识系统的呈现设计讨论（HUD 承载形态与记谱口径），P2 后置面。 -- 相关文档：[HUD 框架](design/gdd/systems/表现与支撑/HUD框架.md) 与[敌人系统](design/gdd/systems/战斗循环/敌人系统.md)（P2） - -**改动面**：文档 - -**状态**：待文档设计 - -#### 削弱档位的最终数值（2026-09-18 登记，来源=会话提及） - -**实况**：削弱取值域 [60,85] 与投值 −65 来自旧体系裁决；"封印标中必须比随便挖一格更值"的当量终值由[战斗结算](design/gdd/systems/战斗循环/战斗结算.md)与[地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)共裁。**语义侧已定案（2026-09-18 盘问会话，结构修复批落地）**：削弱叠层改续时——同名重复授予只刷新剩余结算数、层数恒 1（结构性消饱和）；现行表值为临时值（provisional）。已入 M4 数值批卡 v1.2 件①（duration 终值投定＋当量锚复算落文；含 β 带 [1.2,2.5] 可行子区间推算、flag_hit_premium=125 纳入同窗检算、`clear_dominance_audit.py` WEAKEN_PCT 常量随投值同步）；2026-10-05 裁点已全裁并经同日联审二裁修订（P1甲/P2甲/P3甲/P4甲），跑批待 U0 用户发令、发起前须用户批准。 - -**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 - -**改动面**：文档＋游戏代码 - -**状态**：待文档设计 - -#### 单体寻址的接口扩展位（2026-10-18 登记，来源=会话提及） - -**实况**：对敌效果现行一律全体存活敌人共享一份层数；将来若要"只削弱其中一个"，需要给实例加目标寻址字段——扩展位已预留，首个单体效果上线时补列，并随之裁决归集与呈现语义。（原条目无登记日期，按本批格式整改补登 2026-10-18。） - -**缺口**：还差首个单体效果上线时的归集与呈现语义设计讨论与字段补列方案。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 空刷新的可见性（2026-10-18 登记，来源=会话提及） - -**实况**：刷新类策略在剩余次数已满时再授予是合法空操作（返回成功、无任何变化），与"溢出不静默吞"的诚实原则存在张力；MVP 无刷新类内容行，首批刷新行上线时顺带裁决。（原条目无登记日期，按本批格式整改补登 2026-10-18。） - -**缺口**：还差首批刷新行上线时的空刷新语义裁决（提示形态与诚实原则的平衡）。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 冒险前资源配比预设（构筑提案）（2026-09-18 登记，来源=会话提及） - -**实况**：构筑提案 2026-09-18 立项、八项裁决全裁（2026-10-04），设计闭合机制＝[元进度](design/gdd/systems/跨局循环/元进度.md)「冒险开始参数面与覆盖值通道」（零新机制）；2026-10-05 挂起——移出 roadmap 迭代 14，八项裁决与需求卡片冻结保留，重启须用户另行发令；全案与淘汰依据原载已退役提案（git 历史可考），裁决细节冻结在卡片。关联文档：[元进度](design/gdd/systems/跨局循环/元进度.md) v1.0（闭合凭据；现行 v1.21 已复核在役，2026-10-18 文档体检第 10 项）；需求卡片 reports/需求卡片-冒险前资源配比预设批-2026-10-04.md（文件头挂冻结横幅）。 -- 相关文档：[地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)修订批（基础配比的权重覆盖语义 + GDD 修订）与[元进度](design/gdd/systems/跨局循环/元进度.md)（解锁容量与注入生产者）共裁；呈现面归[HUD 框架](design/gdd/systems/表现与支撑/HUD框架.md)与[教学引导](design/gdd/systems/表现与支撑/教学引导.md)顺带。 - -**改动面**：文档 - -**状态**：文档设计已闭合＋已写卡（备选） - -#### GP 经济换算失衡——GP 袋面值与商店价格的换算关系复查（2026-10-07 登记，来源=审计发现） - -**实况**：道具三层审查的换算发现——小 GP 袋 20 ≈ 商店两三次首购（首购基价 4-5、A 链爬升前）≈ +2~4 点属性，而小攻击件只值 +1——「拿钱」在三选一面里经常比「拿数值」划算，且 GP 袋是池内最大户（23/98 张）进一步放大倾向。用户判「太离谱」。复查范围＝GP 袋面值（20/50）× 商店基价（4/4/4/5）× 价格曲线（A=1.8 / b=1.1）× 战斗 GP 掉落（普通 3 / 精英 5 / Boss 8，关级加值 0/1/2）四处联动；目标＝钱与属性件的换算效率回到设计意图（拿钱 vs 拿数值的取舍成立；GP 袋最大户地位要么有理由要么让位）。连带前提：L1 无商店节点使 GP 在第一关无消费口——「L1 商店编排」不另立条目、归本条复查范围（按 L1 是否补商店分两种情形各算一遍）。留待办清单待未来数值标定窗口（M4 数值批已废；2026-10-18 用户裁＝不另行归属、未设计未启动）。 - -**缺口**：还差四处联动的换算复查设计（含 L1 商店编排两种情形）——随未来数值标定窗口执行（M4 数值批已废，留待办清单未设计未启动）。 -- 相关文档：[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md)调参批（未来数值标定窗口）+ 奇物池结构顺带 - -**改动面**：文档＋游戏代码 - -**状态**：待文档设计 - -#### 迭代 10 奖励重构联动欠账（2026-10-01 登记，来源=批次移交） - -**实况**：迭代 10 奖励重构批（worktree 分支 m3-iter10-20261001）落地面产生三条后续义务——①钥石产出重标：渠道改「Boss/精英击杀掉落」（大奖励 keystone_per_level 退役、boss_keystone 重锚 provisional），现行元进度产出结构作废，标定义务重开；②通关率带重扫：通关回血 20%（血回满→部分回血，难度上压方向）+ 三选一件值/权重/次数上限 knob（AP 件＝每场战斗首轮 +1 AP 强度敏感轴）；③同调位读数源切换——**已清偿（2026-10-03 迭代 11 第①批 T7**：过渡键表/schema/断言三处退役，读取点归零，现行事实源＝Attunement.slots 谓词表实时求值）。①②已入 M4 数值批卡 v1.2 件③（F7/F8；通关率带重扫与 T6 四带复算并账、一次跑批双认账），跑批待 U0 用户发令、发起前须用户批准。 - -**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 调参批数值点评登记（2026-10-01 登记，来源=批次移交） - -**实况**：格面资源八型批后顺带登记的数值点评——① 增伤型奖励/惩罚幅度 50/25 不对称是否有意；② 削弱型 65/25 同问（且 percent 套个位数取整偏粗）；③ 回血奖励过薄（值 1、权重全池最低 2）；④ 警觉/行动点修正两新词数值全部 provisional；⑤ 行动经济"满停一轮＝一刷"节拍在 AP±1 修正下的对账——①-⑤五条已入 M4 数值批卡 v1.2 件②（F5，逐条裁决落文）；⑥ **格面资源正负兑付倍率差回调（2026-10-07 用户裁）**——2026-10-01「踩雷必须痛」抬档（heal +2/−6、pierce/magic +2/−8 等，负向 3-4 倍于正向）系错误的加难杠杆：难度提升应走怪物性能路线而非抬地图惩罚，回调归未来数值标定窗口（M4 数值批已废），标错/开雷同档同罚维持不动（同批裁）；⑥连同本条整体留待办清单未设计未启动（2026-10-18 用户裁）。里程碑立规（2026-10-09）：M4＝Beta 阶段、M3 未由用户明令关闭前不排期。 - -**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 -- 相关文档：[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md)难度曲线调参批 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 成长系数与关卡怪物难度提升的节奏（2026-10-16 登记，来源=playnote） - -**实况**：来源＝playnote 用户反馈「一开始不能让角色的成长系数太高。比如在没经过升级之前，你的成长系数是跟不上关卡怪物难度提升的；但是后续能力解锁之后，成长系数才能匹配得上」。语义两读：**读法甲＝节奏缺陷呈报**（前期成长跟不上怪物难度提升＝要修的数值节奏问题，归属难度曲线与Boss＋元进度解锁节奏的数值面）；**读法乙＝设计哲学陈述**（前期成长刻意克制、后期靠能力解锁追平＝既定设计，应反哺难度曲线的设计语义）。2026-10-16 用户定性＝数值校准类、与数值欠账同类任务，甲/乙两读随定性消解（无论现行节奏好坏，调它都是数值校准面的事）；不进 [08-Alpha版本标准](design/gdd/08-Alpha版本标准.md)（数值调优义务 2026-10-16 v1.6 起不入版本标准）；按里程碑立规属 Beta 阶段面，Alpha 不排期；留待办清单数值欠账组，未设计未启动（2026-10-18 用户裁＝不另行归属）。 - -**缺口**：还差并入数值欠账组的归属落位（Beta 阶段数值校准窗口处理）。 -- 相关文档：[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md) + [元进度](design/gdd/systems/跨局循环/元进度.md)（成长系数语义面） - -**改动面**：文档 - -**状态**：待文档设计 - -#### 「封锁-蓄力」combo 设计素材（2026-10-07 登记，来源=会话提及） - -**实况**：用户想法（暂不立件，素材登记）——两件套：件一＝抬高刷新雷图代价（储备池 RAP 成本飙高）+ 刷新时解锁所有格子（全板开）；件二＝本回合留着 AP 没有刷新 → 获得减伤。联动＝抬价逼留 AP、留 AP 给减伤、憋够一发全板解锁。我方补充登记五点：①形态骨架＝「封锁-蓄力」combo 结构（抬高某动作代价封路 + 不做给补偿 + 憋到后的爆发）；②件一＝风险契约句式的扫雷侧版——碰撞点待裁：刷新开全板与清图判定/清图奖励/连锁展开的关系（算不算清图、发不发清图奖励）；③件二词表可承载（on round_end when 本轮未刷新且余 AP≥X → 减伤/护盾），「本轮未刷新」事实＝扩签候选；④归层按判定尺逐件裁（两件偏机制改写→专长域；但「刷新代价」是扫雷侧经济参数→秘宝域亦可）；⑤防躺赢注记：憋的收益须小于正常挖格期望（否则最优解＝永远不挖，玩法塌缩）。 - -**缺口**：还差立项裁决（暂不立件）——若立项，先裁碰撞点与归层，再走机制设计讨论。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 袋装摇号（格面资源池结构备选——保底型增多后的重构方向）（2026-10-07 登记，来源=会话提及） - -**实况**：地图战斗资源池保底结构（四档概率 + 按型保底 + 档位保底上限，现行事实源＝[地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)候选集合节）以「摇完整板校验补签」的补丁式实现起步——简单够用。备选正规形态＝**袋装摇号**：装板时按各档配额数好牌再洗开发放，保底天然成立、分布精确；代价＝摇号结构重写 + 偏运硬币/board_skew 两路权重投影须改为袋面投影。启用条件＝保底登记型增多、补签逻辑复杂化时。来源＝2026-10-07 地图层题四讨论，用户裁「先挂在待办清单」。 - -**缺口**：还差启用条件触发后的摇号结构重写设计讨论（含两路权重投影改袋面投影的方案）。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 战斗节点地图类型差异化——更多地图主题（2026-10-13 登记，来源=playnote） - -**实况**：来源＝playnote 用户试玩记录「修改地图的奖励类型：战斗节点增加不同的地图类型，比如有些图踩雷受到更多的伤害，有些图标雷可以造成更多的伤害，有些图伤害会减半需要凑更多清图奖励（这些都是暂时的设定）」。**已实装的部分**：首发形态整图变异「贫矿脉」已于 2026-10-16 用户令屏蔽删行（Boss 图回落 region 变异，原体验验证清单⑪ 目检项随之转记失效）——本条剩余面不变：在此之上再做**更多地图主题**（踩雷伤害更高/标雷伤害更高/伤害减半需凑更多清图奖励）。**2026-10-13 用户裁定：排 Beta 版本，Alpha 不做**——已移入 [08-Alpha版本标准](design/gdd/08-Alpha版本标准.md)「六 · Alpha 不含」节。 - -**缺口**：还差 Beta 立项时的地图主题设计讨论——按本条原始想法重新评估（用户标注「这些都是暂时的设定」，到时需重订而非照抄）。 -- 相关文档：[棋盘生成](design/gdd/systems/排雷循环/棋盘生成.md)（board_biome 图主题词表）+ [地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)（图主题差异化插槽）+ [地形变异](design/gdd/systems/排雷循环/地形变异.md)（整图变异承载面） - -**改动面**：文档 - -**状态**：待文档设计 - -#### 基线通关率越带，加难杠杆扫描未执行（2026-09-18 登记，来源=审计发现） - -**实况**：原登记＝现行扫描读数 60% 越 [30%, 50%] 上界；其后目标带两度换代（2026-09-17 带 [10,25]；2026-09-20 重投基线批后分带修正为 L1 [35,55] / L2 [25,45]，旧带失锚作废）——**新带下普通档双关落带、完美档 56%/40% 亦落带，加难紧迫性解除**。C1 终态已落表（2026-09-29 返工批：占比回退 5+plb 0+岩浆 1；U2 裁断 b 项推翻 C3 四件组合裁 **C1 两刀**〔岩浆 effect_value 2→1+逐层变异基数 2→0；变异占比维持 5%、卓尔血维持 130〕，a 项甲＝新杠杆授权〔完美 L1 89% 挂账废止，归难度曲线与Boss.md 带换代节承接〕；U2 裁断全录见 git 提交 f9c1a8a）。剩余面＝调参批的行值 provisional→正式扫描义务（门＝真人批 k 系数）；新增调参杠杆位＝变异 effect_value（荆棘丛 1 / 岩浆 2）与 percent_of_cells（5%）/ per_level_bonus（+2/关），扫描时与既有三类杠杆（血量锚走廊 r_boss [1.1, 1.35]〔2026-09-17 注：数值压缩批后 Boss 生命已 ÷3 缩水，180–207 为压缩前基线锚，复算随调参批〕、群战上探、注入衰减 0.5 → 0.6）合并比较；落带前全部现行行值维持 provisional-pending-scan。 - -**缺口**：还差真人批 k 系数到账后的加难紧迫性重判，再定正式扫描与杠杆标定设计。 -- 相关文档：难度曲线与Boss调参批，扫描执行与[棋盘生成](design/gdd/systems/排雷循环/棋盘生成.md)工具交付联动 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 三方向各自的解锁清单与定价（2026-09-21 登记，来源=审计发现） - -**实况**：三方向（属性、遭遇、道具池）各自的解锁清单与定价：多少钥石换什么，各自怎么铺。来源＝元进度 待设计问题清单第 2 条。部分完成（2026-09-21 元进度实现批再收窄；2026-09-23 换算率标定批再收窄）——**三柜台结构与 provisional 定价已落地**（属性锻造三档血+3/攻+1/甲+1、Boss 两档、工坊六件阈值 1/1/2/2/3/3 按总通关次数——全部读 `data/tables/meta.tres`）；换算率三行已投值 6/9/1（冒险条件口径实测，护甲行强条目重测履行）。剩余面＝定价数字与 Boss 两档终值——已入 M4 数值批卡 v1.2 件④（F11/F12；含待办清单死文本两句全刷义务：「base 10 公比 150」滞后〔meta.tres 现行 forge base_price=20，2026-09-22 数值设计批对齿〕与「Boss 两档 L1 5/1·L2 8/2·L3 12/3」死数字句〔现值首杀 3/3/3 · 复杀 2/2/3〕，T4 判据按两句全刷执行）。 - -**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 第二 / 三关棋盘观感——亮度与对比度（2026-10-13 登记，来源=playnote） - -**实况**：来源＝playnote 用户试玩记录「UI 优化，第二第三关的棋盘看着太累了；不知道是因为亮度还是对比度的原因，看着非常费劲，非常不舒服」。2026-10-13 用户裁定：**这是需要做的**，且本就属版本标准的覆盖范围——[08-Alpha版本标准](design/gdd/08-Alpha版本标准.md)「五 · 表现」已新增「棋盘观感（第二 / 三关亮度与对比度）」行，标待做。**开工前须先定性（沿用既有裁决）**：是**素材轴**问题（棋盘瓦片与格面图标本身的明度与色相），还是 **UI 轴**问题（舞台底色与叠加层的对比关系）——两轴修法完全不同，定性错了等于白改一轮；该定性要求（原备忘 (e) 项）是本条的开工前置。2026-10-16 曾编入迭代 30 卡③（UI 呈现三卡批序位③），2026-10-17 用户裁定剔除回待设计（自身挂「素材轴/UI 轴」定性人闸＋甲/乙〔recolor/远程生图重产〕素材裁点；若裁乙，其瓦片规格依赖战斗一屏样张批的目标规格清单产出）。v1.4 旧卡留 reports/需求卡片-二三关棋盘观感批-2026-10-16.md 作素材，非已写卡状态。与已完成注销的「呈现层残余 <4.5:1 文字位」分工：本条管**棋盘区域整体的观感**（亮度/对比度/费劲感，体感问题），彼条管**具体文字位的对比度读数**（机检可判硬指标），两条不同面不互相替代。Alpha 出口裁决：Alpha 必须，先做素材轴／UI 轴对照定性；出口＝用户实机目检不再判「看着费劲」。 - -**缺口**：还差「素材轴 / UI 轴」定性设计讨论与甲/乙素材裁点裁决；素材轴若走重产，还依赖战斗一屏样张批的目标规格清单产出。旧卡 v1.4（reports/需求卡片-二三关棋盘观感批-2026-10-16.md）在册但非已写卡状态，其前置未完成三件：①「素材轴 / UI 轴」定性未做，这是既有条款规定的开工前置；②甲（recolor 现瓦片）／乙（远程生图重产）素材裁点未裁；③若裁乙，瓦片规格压在样张批的目标规格清单上，而那份清单的前置正是上一条未完成的样张设计轮——本条第三项压在卡②身上。 -- 相关文档：[HUD框架](design/gdd/systems/表现与支撑/HUD框架.md)（UI 轴：舞台底与叠加层）+ [美术圣经](design/art/art-bible.md)（素材轴：瓦片与格面图标的明度色相）——定性前两方共裁 - -**改动面**：美术素材＋游戏代码 - -**状态**：待文档设计＋待美术设计 - -#### 棋盘格边长三方取值不一致——待扩板定档处置（2026-10-06 登记，来源=批次移交） - -**实况**：迭代 16「UI 设计对齐批」P2 已裁「棋盘格边长零改动」（本次不动棋盘游戏画面），由此三方取值不一致作为**已知偏差**登记：①代码＝`board_view.gd:251` 动态公式 `clampi(cell, 26, 46)` + `:114` 默认 46.0；②art-bible §8.1(:433) 冻结锚点＝45px（10×10）/ 36px（12×12）；③demo 原型＝44px（`src/ui-prototype.html:288`）；另有 HUD框架:72 装板校验区间 [30,45]。**当前未被任何断言触发**（属潜在不一致，不是缺陷）。按需求卡片契约 R7「禁单侧改完留漂移」，本批**代码与文档均不改**；处置时机＝扩板（13×13/14×14）定档时随格边长专项一并处理（§8.1 亦注明扩板换算值未定稿）。来源＝UI对齐批需求卡片（已退役，git 历史可查）§2.1「已知偏差」行。 - -**缺口**：还差扩板定档时的格边长专项裁决（三方取值归一＋§8.1 扩板换算值定稿）。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -#### 资产升档重产批（art-bible v3.0 中修挂账③，2026-09-29 登记，来源=批次移交） - -**实况**：v3.0 §8.2 档位上调方向候选（主角立绘 48×72→64×96 档、敌立绘三档上调评估）**已实质完成**——2026-10-06 art-bible v3.7 八敌逐键定档（源档 36–94、显示 ×2 整数；派生管线＝pixel-1 紧裁→等比缩至档高→dom_block_resize）取代 64/96/128 升档路线；存在感问题改经方案二（B 区 270 / 立绘显示上限 188 / 血条状态落底排）解决，不再走升档路线。裁决史：2026-09-30 迭代 9 三裁决案乙（本迭代不升档，先收 Alpha 真人读数再定；A4 尺寸基线冻结〔立绘 46×48/小人源 32×32〕维持有效）；2026-10-04 用户令暂不做、先忽略；2026-10-06 用户令优先级再降（维持挂起；同日 playnote 立绘批评已由「立绘逐键定档批」承接兑现）。**剩余挂起项＝提灯点亮解禁候选**（character-design 提灯，v3.0 明度分层允许空间光照），重启＝用户点名或 M-4 升档批。Alpha 出口裁决：不进 Alpha，排 Beta；提灯候选随 Beta 资产批重议。 - -**缺口**：还差提灯点亮解禁候选的重议设计（升档批或用户点名触发时一并裁）。 -- 相关文档：[art-bible](design/art/art-bible.md) §8.2 · 资产管线批 - -**改动面**：美术素材 - -**状态**：待美术设计（备选） - -#### 立绘清晰度回退评估——是否改用高清图（2026-10-13 登记，来源=playnote） - -**实况**：来源＝playnote 用户试玩记录「现在的立绘太丑了，像素化的粒度太低了，导致根本看不清立绘；看是否可以改回用较为高清的图片？还有一个问题是大小的问题……现在地精的图片看起来比熊地精还要大，这并不合理」。2026-10-13 用户裁定：与「第二 / 三关棋盘观感」同属**美术线更新**。**两个子问题现状不同**：子问题一＝怪物大小比例不合理——**已兑现**（体量语义改生物体型〔character-design §5.2，弃强度线性映射〕＋八敌逐键定档〔art-bible §8.2〕），剩余面＝用户是否复核验收；子问题二＝像素粒度过低/是否改回高清图——**方向已裁（2026-10-14 用户裁）**：「还是像素风格立绘，但是不需要像现在太过于像素」，定性为**精细手绘像素**（不是插画、不是 HD-2D、不回退高清图；裁决录＝[美术审计-cursor会话存档](reports/美术审计-cursor会话存档-2026-10-14.md) §2.2；权威面 art-bible/character-design 口径节反哺另批），粒度问题已改派生管线（八敌源档 36–94 全过可读门槛：24 糊/32 可读/48 清楚）。[08-Alpha版本标准](design/gdd/08-Alpha版本标准.md) 未决项已随裁删除（2026-10-16 状态刷新批）。Alpha 出口裁决：Alpha 范围＝主角＋三个 Boss 按新口径重产，其余敌种当前可读则保留到 Beta。 - -**缺口**：还差立绘按「精细手绘像素」新口径重产的设计——整屏方向稿与地面/立绘密度同批锁（与战斗一屏样张批联动）后才可出重产工单。 -- 相关文档：[角色设计](design/art/character-design.md)（立绘规格与体量语义）+ [美术圣经](design/art/art-bible.md)（像素管线与档位） - -**改动面**：美术素材 - -**状态**：待美术设计 - -#### 站桩帧动画——Alpha 定版闸前完成（2026-10-06 登记，来源=审计发现） - -**实况**：审计报告 P0-3——定稿立绘零帧动画；现行动画全部程序化（死亡碎裂/受击闪白/意图徽标弹入＝程序 tween，非帧资产）。用户裁定**动画是较往后的优化，Alpha 版本定版时间点之前完成即可**——当前 Alpha 开发期达成「看上去可游玩」即可。路线未拍板，审计报告三路线供重启时裁决：①**拆件驱动**（报告推荐：定稿立绘切部件〔头/躯干/臂/腿/武器〕+ 节点层级 tween 驱动——零身份漂移、帧数无限、内存小；项目已有先例＝shovel_swing 三帧 + 程序化死亡碎裂）②AI 关键姿势 + 人工修 + 程序补帧 ③全 AI 逐帧（不推荐：身份漂移/像素抖动）。前置依赖＝「立绘→派生形态」管线（等比整数缩放 + 降色 ≤32 + 脚底基线对齐 + 命名合规）——该管线同时是棋盘小人重出与八敌档位重算的前提。Alpha 出口裁决：列入 Alpha 定版前置清单——定版前完成最小版，路线预选拆件驱动；未完成则顺延 Beta，不占功能迭代。 - -**缺口**：还差 Alpha 定版批的路线正式拍板（预选拆件驱动）——拍板后立帧数规格与资产工单。 -- 相关文档：[art-bible](design/art/art-bible.md) §8.4 帧数规格 · 战斗表现批 - -**改动面**：美术素材 - -**状态**：待美术设计 - -#### 主角描边素材侧复核（2026-10-06 登记，来源=会话提及） - -**实况**：待决项 B 已按用户拍板走**文档例外条款**（character-design.md §5.1 v1.9：主角四态硬描边＝深褐 `(40,19,13)` 显式例外，浅砖面对比更高；**素材不顺带修改**）。本条仅为复核钩子：样张批（圣经 §1.4）终审时若发现深描边例外不成立（对比优势不实/与敌方同屏割裂感可感），素材侧修订（描边统一暖白族）**须先经本条重启**再开工，禁止直接动图。 - -**缺口**：还差样张批终审触发的深描边例外复核——复核成立即注销，不成立则重启素材修订设计。 -- 相关文档：[character-design](design/art/character-design.md) §5.1 · 样张批 - -**改动面**：美术素材 - -**状态**：待美术设计（备选） - -#### 在途草稿整理批——3349 个失管草稿（2026-10-06 登记，来源=审计发现） - -**实况**：审计 P2-1——`artwork/ui-reuse-2026-09-23/` 独占 3043 个草稿（91%），vN 命名率 0%，冗余 41 文件，残留非素材文件（.url ×8 / .ogg ×6 / .ai ×2 / .swf ×1）；根因＝脚本链覆盖「生成→验证」但**缺「草稿整理」段**。整理涉及**批量文件移动/删除**，按用户惯例须先 dry-run 呈报清单、经确认再分批执行。执行窗口随实现批；开工＝用户点名。 -- 相关文档：[art-bible](design/art/art-bible.md) §8.3 归档纪律（原则已写入）· 资产管线批（工具+文件操作） - -**改动面**：美术素材＋工具代码 - -**状态**：待写卡 - -#### 圣经口号型条款机检化批（2026-10-06 登记，来源=审计发现） - -**实况**：审计 P2-4——圣经约 55% 条款属口号型（如「暖倾向无压抑」「同一圆角率」无值），与可机检条款混排。目标＝逐条审查标注「可机检/目检/口号」三档分行，口号型逐步改写为带值或带判据条款。工程量＝全文级（541 行逐条），非一轮能毕。**2026-10-06 三档标注格式已拍板**（←机检/←目检/←方向性，规范见 art-bible 头注「条款验收标注纪律」；数值类推荐「待定现用」态）——本批执行＝按此格式分章补标，每章交付用户抽验。挂账：随整屏样张闸前整备批启动，分章推进。 - -**缺口**：还差整屏样张闸前整备批的启动——格式已定，差启动时点与分章执行。 -- 相关文档：[art-bible](design/art/art-bible.md) 全文 · 样张批前置整备 - -**改动面**：文档＋工具代码 - -**状态**：待文档设计（备选） - -#### 战斗区背景图替换——B 区舞台插画 + 临时光柱退役（2026-10-07 登记，来源=会话提及） - -**实况**：B 区舞台现行＝程序化平色底（`UiKit.STAGE_BG`，`battle_stage_view.gd:47`）+ **顶光柱氛围层**（`:55-63` 四柱，x 基准 110/900/1055/1210@1280，60 段叠层矩形自顶向下渐宽窄渐隐〔顶 α26→0〕，层序＝bg < 光柱 < 世界）——二者均系 §6.1 方向稿的**临时占位**，用户口径「光柱只是临时方案，换正式战斗背景后效果更好」。正式件已立资产契约：`stage/stage_bg.png`（源 1280×270，B 区全高含明细带底；三关换挡走 §4.3 `wall_ambient` tint 槽，不按板出三张），属审计 P1-2 查得的「B 区舞台背景插画 0 张」缺口。**光柱在背景到位后顺带退役或吸收进背景绘制**（不再作为独立程序层）。**与立绘探顶解耦**：大体档「允许向上溢出盒顶 N px」的判定（2026-10-07 用户裁甲案）**不依赖光柱是否存在**，换背景零返工。 - -**缺口**：还差出图前置条件的达成——立绘定档与站桩重排实装批的 **C0 盒高账定案后再出图**（避免 B 区高度/构图二次返工）；开工＝用户点名。 -- 相关文档：[art-bible](design/art/art-bible.md) §6.1（资产契约）+ §8.3 归档纪律 · 资产管线批；出图工单归 [art-assets-checklist](design/art/art-assets-checklist.md) / 实装批任务书 - -**改动面**：美术素材＋游戏代码 - -**状态**：待美术设计 - -### 教学引导 - -> **节头注记（2026-10-04 用户拍板）**：教学引导定稿批整体改排 **Beta 阶段**——当前 Alpha 版不做教学相关工作，本节五条全部随之改排（2026-09-19 的 Alpha 排期拍板被本拍板取代）。同日五问讨论已形成初裁与设计提案，提案已归档 `archive/` 目录（磁盘留存、不入 git，Beta 批立项底稿，引用以其「归档状态与初裁记录」节为准）。初裁摘要：①教学形态＝丙1 混合（首次冒险编排式首遇提示〔挂 first_script 锚、不锁操作〕+其余全程情景触发）；②「因果教学顺序」问题**注销**——只教扫雷操作，结算读法不设教学（用户裁：结算只是表达、展现、演出，无策略内容；展示层每行带来源标注已自带归因；教学引导.md 旧前提〔设计目的句/P0 候选归因提示/验收第 2 条〕随 Beta 批文档定稿清除）；③图例面板按循环段落分组、无结算段；④不做「再教一次」——改走独立「帮助」手册面（全部内容放一个文档）；⑤教学文案内容权归设置与本地化（两文档负责表对齐随 Beta 批）。**未裁三疑点**（Beta 立项时先裁）：增益叠层节奏条目去留／帮助入口位置（设置面为推荐）／图例面板与帮助手册的内容分工。 - -#### 教学形态未定（2026-10-04 登记，来源=审计发现） - -**实况**：教学的具体形态未定：线性开局教程，还是全部走情景触发式提示？来源＝待设计问题清单第 1 条。2026-10-04 用户拍板本节整体改排 Beta（Alpha 不做教学）；同日五问讨论初裁＝丙1 混合（见本节头注记），定稿归 Beta 批。 - -**缺口**：还差 Beta 立项后的教学形态定稿讨论（初裁丙1 混合待定稿，见本节头注记）。 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 因果教学顺序（2026-10-04 登记，来源=审计发现） - -**实况**：因果教学顺序未定：先教扫雷操作，还是先教读结算明细？两者如何衔接？来源＝待设计问题清单第 2 条。2026-10-04 五问讨论初裁＝**该问题注销**——只教扫雷操作，结算读法不设教学（用户裁：结算只是表达、展现、演出，无策略内容）；教学引导.md 旧前提随 Beta 批文档定稿清除。 - -**缺口**：还差 Beta 批文档定稿时对初裁结论的写入文档清算（教学引导.md 旧前提清除）。 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 图例面板的条目全集与分组方式（2026-10-04 登记，来源=审计发现） - -**实况**：图例面板的条目全集与分组方式待定。来源＝待设计问题清单第 3 条。2026-10-04 五问讨论初裁＝图例面板按循环段落分组、无结算段（见本节头注记）；图例面板与帮助手册的内容分工属未裁三疑点之一（Beta 立项时先裁）。 - -**缺口**：还差 Beta 立项后的图例面板定稿讨论（分组初裁待定稿＋与帮助手册内容分工裁决）。 - -**改动面**：文档 - -**状态**：待文档设计 - -#### 教学文案定稿权与本地化流程的分工（2026-10-04 登记，来源=审计发现） - -**实况**：教学文案的定稿权归属，以及与本地化流程的分工——两边共担，裁决时须对齐（设置与本地化原登记「文案定稿权与翻译流程的分工」；教学引导「待设计问题清单」第 4 条同事项，合并于此）。来源＝待设计问题清单 + 设置与本地化原登记。2026-10-04 五问讨论初裁＝教学文案内容权归设置与本地化，两文档负责表对齐随 Beta 批（见本节头注记）。 - -**缺口**：还差 Beta 批的两文档负责表对齐定稿。 -- 相关文档：教学引导与[设置与本地化](design/gdd/systems/表现与支撑/设置与本地化.md)共裁 - -**改动面**：文档 - -**状态**：待文档设计 - -#### "再教一次"入口与图例面板兼任手册（2026-10-04 登记，来源=审计发现） - -**实况**：是否提供"再教一次"的入口（图例面板是否兼任手册）待定。来源＝待设计问题清单第 5 条。2026-10-04 五问讨论初裁＝不做「再教一次」，改走独立「帮助」手册面（全部内容放一个文档；见本节头注记）；帮助入口位置属未裁三疑点之一（设置面为推荐，Beta 立项时先裁）。 - -**缺口**：还差 Beta 立项后的帮助手册面定稿讨论（初裁待定稿＋帮助入口位置裁决）。 - -**改动面**：文档 - -**状态**：待文档设计 - -### 生涯（跨局汇总与历史回看承接面） - -#### 「生涯」界面——冒险中数据回看的唯一承接处（2026-10-04 登记，来源=会话提及） - -**实况**：2026-10-04 用户裁决（UI 落码计划 P-C7）——冒险中不给数据回看：settlement_review_overlay（结算明细回看）与结算框「明细回看」钮在冒险中退役，战报带只留单行「上轮」；历史战报/结算明细的查看去向＝新「生涯」界面（跨局汇总/历史冒险回看/图鉴承接）。来源＝UI 重设计原型 v2 落码计划裁决记录（已退役，git 历史可查 §七）。**设计提纲已成文**：[systems/跨局循环/生涯.md](design/gdd/systems/跨局循环/生涯.md) v0.1 范围草案五节成文〔信息架构/承载内容清单/与既有界面关系/分期实装建议/待裁点〕，P0-P5 六裁点已全裁并写入文档〔P0甲 提纲落现行事实源 / P1甲 主菜单一级入口 / P2甲 每局一行摘要+cap 扩容 N+补用时埋点 / P3甲 敌人图鉴优先 / P4甲 局内不放入口+生涯零跳转 / P5甲 settlement_review 复活承接〕。**期一已落地**（2026-10-07 迭代 18 卡④实装批：生涯页六类九项+主菜单入口+终身计数域存档 v6，批末全量域闸全绿；实机人闸＝体验验证清单⑲ 生涯页目检节）。剩余面＝期二（历史回看/图鉴）与期三实装＋P6 营地最近冒险条带去留（新发现待裁点，随提纲评审一并裁）。**迭代 19 卡②遗留件（2026-10-08 登记）**：settlement_review_overlay.gd 现态考证＝未接线遗留件（全仓零引用，M9 结算框改版「明细回看」钮退役后遗留）——处置两途：①随生涯实装批按 P5 甲复活承接（重接线入生涯）；②确认不再需要则正式退役删除文件；二选一归生涯实装批/用户裁。Alpha 出口裁决：期二、期三全部排 Beta——Alpha 只保留期一，不在 Alpha 内做生涯新内容。 - -**缺口**：还差提纲用户评审收尾与 P6 营地最近冒险条带去留裁决——裁完才能立期二/期三实装卡（期一已交付，期二/三未预占排期）。本条排 Beta，不阻塞 Alpha；重启时再补 P6 与 N 终值。 - -**改动面**：文档 - -**状态**：待文档设计（备选） - -### GP 经济 - -#### 商店独立刷新机制——两参数待调参 + 机制文档回写（2026-10-04 登记，来源=会话提及） - -**实况**：2026-10-04 用户裁决（P-C2+Q2 二次裁）推翻关卡节点地图 v1.5「无独立刷新、重抽绑购买」口径，定案＝**基础免费 0 次 + GP 刷新（ceil(20×1.8^已付费刷) provisional）+ 池源同源（共享池，与三选一同一账本）**；**天赋/营地侧「刷新次数」增益＝用户既有意向（口头裁决，曾因未写入文档丢失——Q2 追认），后续由用户调整添加，实现面预留 free_count=天赋增益位**。未定：天赋增益的具体形态与数值。**机制已落码**（SR-1 随 UI 落码批收官，2026-10-04/05）；**三选一同款付费刷新已落码**（2026-10-06 用户令——「三选一对齐商店，得有刷新」：免费双源〔刷新件 X/冒险池 Y〕用尽后 GP 付费刷新，同旋钮同曲线同钱包；机制登记归[秘宝](design/gdd/systems/跨局循环/秘宝.md)「三选一刷新双源」节）。剩余待办：①调参（shop_refresh_free/曲线两参数 provisional，归未来数值标定窗口顺带——M4 数值批已废）；②天赋增益形态与数值（设计未定）；③机制文档回写核对（冒险结构共享池账本节/关卡节点地图商店行 v1.6 已记，本条完成时核对三处同步）。 - -**缺口**：还差天赋增益形态与数值的设计讨论（用户调整时裁）与 M4 窗口的两参数标定；③回写核对随完成时点履行。 - -**改动面**：文档＋游戏代码 - -**状态**：待文档设计 - -### 文档与结构 - -#### qa/ 实现报告收尾·孤儿遗留七项余三项（2026-10-14 登记，来源=批次移交） - -**实况**：qa 收尾批核查 iter19 系列出口报告遗留移交项时发现**不在待办清单在册**的七项（acceptance-package §三.2/card0 §5.3/followup §七.3/uibackfill §6.2-4/verify §6.1/3/7）。已结案的（tree_rules 受理闭环、X/Y 双源、S1 七项违例修复、提灯目检项、tests.yml 休眠等）已在各报告标注结案证据，不入本条。2026-10-24 处置：第②③④项随迭代 36 卡C 落地销号（营地 STONE 深档六处、迷雾三关派生行、开场后缀条件加算区），第⑥项按用户 2026-10-24 裁整条注销（TG_* 装饰带非文字，不另立探针）。余三项均为挂号备查/顺路件，无排期承诺： - -1. **design/diagrams 越界**（熵增闸存量红，archify 架构图批 00712d5 旧债）：脚本自文「新分类先过用户拍板再改两处白名单」。修案二选一——甲＝用户拍板 `design/diagrams` 入 DESIGN_SUBDIRS 白名单（archify 总图批产物归位）；乙＝迁出 design/ 归位合法区。落点＝熵增闸白名单（AGENTS.md Project Layout+脚本白名单两处） -5. **字面量墨收测前置**（iter19 卡②遗留）：bcard 属性描述/类型脚注/✓章/primary_button 字四处内联 Color8 无常量形态，收测需先在 ui_kit 立常量（呈现批顺路件，改 ui_kit 越当批面）。落点＝呈现优化批（ui_kit 常量面） -7. **商店房截图纳屏**（iter19 卡①遗留）：商店房截图纳屏留后续呈现批（考证结论在 shot_probe 头注）。本项原并列的「`数据配置.md:223` 历史行死指」半句已于 2026-10-21 实查核销——禁写变更记录规约生效后该文件的版本史行整段已不存在（现全文 212 行，文内零版本史行），被指对象随之消亡。落点＝呈现批 - -**改动面**：游戏代码＋工具代码 - -**状态**：待写卡（备选） - -#### 奖励节点三选一实装（2026-10-25 登记，来源=批次移交） - -**实况**：局内奖励节点现为零兑付直通占位——`game/core/level_runner.gd:462-466` `"reward"` 分支注记「奖励点内容未定…节点保留占位、零兑付直通」，实跑选路直接跳过；L1 全部模板零商店节点（`game/data/tables/level.tres` L1 行＝20 battle/5 boss/5 rest/5 reward，零 shop），现行局内 bonus 唯一可达来源＝L2 商店货架。而规格已定：[node-reward](design/gdd/ux/node-reward.md) v2.8＝奖励节点从冒险牌库抽三选一（属性值提升与补给；与通关专长三选一同库分流），池与库存口径归[冒险结构](design/gdd/systems/冒险循环/冒险结构.md)「奖励节点三选一池」节（共享令牌库、消耗即上限）。连带影响：迭代 36 卡C 路径②原设计「奖励节点拿属性卡→下一关开场行带后缀」不可驱动，已改快照喂入形态通过；wa4 探针半（三选一停点弹层头部断言）保留为条件断言、**拦截能力未证**（test-conventions §6 口径），本条实装后须重跑该断言。 - -**改动面**：游戏代码 - -**状态**：待写卡 - -#### 闸与探针存量噪声两件——_round_rows 类型错与批上下文挂死（2026-10-25 登记，来源=批次移交） - -**实况**：证据＝迭代 36 批末闸机观测（非本批引入）。两件存量噪声：①`ui_click_probe` 与 `battle_log_view` 绿跑亦复现 `_round_rows`（Array[Dictionary]）append String 的运行期 TypedArray 错误——日志失真但断言仍绿；②`level_shop_economy_test` 在闸批量上下文存在挂死形态（直跑恒绿），`tools/probe_gate.sh` 的 per-suite timeout 只杀 wrapper 不杀引擎子进程，孤儿泄漏会殃及后续全部 Godot 启动（批末四次闸跑批中断的根源，处置＝清杀泄漏进程＋删重建 `game/.godot`）。两件均登记待后续测试基建批处置。 -- 相关文档：`game/presentation/views/battle_log_view.gd` 与 `game/probe/ui_click_probe.gd`（类型面）；`tools/probe_gate.sh`（进程树回收面）——测试基建 - -**改动面**：游戏代码＋工具代码 - -**状态**：待写卡（备选） - -#### 美术资产链路审计两项 P0 — 待用户裁决（2026-10-09 登记，来源=审计发现） - -**实况**：**P0①（文档面）**：`design/art/art-bible.md` 第 68/527 行与 art-status-checklist 第 13 行至今仍引用已丢失的冻结样张 sample-batch-v3-final-2026-09-30.png（磁盘实测零命中），死指涉待修复。**P0②（美术面）**：主角棋盘小人未走像素管线（插值糊图），重产事项未在任何登记处在册。审计报告 HTML 件从未进版本库、现已删除，两项 P0 的现状以本条正文为准。裁＝修复死指涉+登记重产，或判过期随旧管线退役。2026-10-13 用户令随「UI 美化三层诊断」登记：本条属第三层「观感提升」，Alpha 阶段需完成。 - -**缺口**：还差用户的路线裁决（修复死指涉＋登记重产，还是判过期随旧管线退役）——裁决后文档面修复与美术重产登记各按轨推进。 - -**改动面**：文档＋美术素材 - -**状态**：待文档设计＋待美术设计 - -#### 技术债观察登记——长函数余量与 lambda 连接防回归（2026-10-15 登记，来源=批次移交） - -**实况**：证据＝迭代 27 需求卡片两项「登记待办清单观察」义务批内漏登、卡片核对时补登——①**长函数 17 个**中非结算段的装配/校验函数（`level_map_screen.gd` 选路装配 155 行/`camp_overlay_view.gd` 152 行/`debug_overlay.gd` 114 行/`treasure_item_table.gd` schema 校验群等；`main._build_ui` 已随场景拆分自然解体、`_settle`/`_resolve_hero_attack` 已随波二拆段＝17 中 3 件已消解，余 14 件）；②**lambda 连接 76 处**（presentation 6/smoke 62/tests 8——实读无泄漏，登记防回归）。长函数拆分无独立需求驱动不动；lambda 连接数若有审计工具化需求归类型闸后续。 - -**改动面**：游戏代码 - -**状态**：待写卡（备选） - -#### 测试域遗留（2026-10-16 登记，来源=批次移交） - -**实况**：证据＝迭代 29 批内未收余量（交付报告与验收审计申报，报告已按吸收即死退役、git 历史可考）。迭代 29 把验收语义从「跑一遍没崩＝通过」扭到「三层完备＋判定可靠」，三硬闸（退出码／脚本错误扫描／断言数下限）已落地，L2/L3 从零建起承载。本批未收的余量集中登记在此，均不阻塞、不排期： - -| # | 事项 | 落点与要点 | -|---|---|---| -| 1 | **余下 3 个 core 模块仍零指名单测**：`board_data`／`reward_economy`／`skill_lottery` | 测试基建批。本批补了 minesweeper_rules／board_generator／config_db_resolver／config_db_cross_validator 四件；余三件按同一手法补（判据＝能否在 `--script` 模式不加载 autoload 验完） | -| 2 | **render_gate 的 SCRIPT ERROR 扫描仍缺失** | 测试基建批。判定主体是 golden 容差与取证文件存在性，脚本错误不改退出码时无扫描面；本批只把矩阵状态如实记为「缺失」，收它的写法待裁 | -| 3 | **静态扫描域 S7／S8 仍未落地** | 工程债批。S7＝B1 编排唯一性（B2/B3/B4 API 符号命中文件 ⊆ B1 文件集）；S8＝结算路径 `await` 零命中。本批补的是 S3 路径与 S5，S6 亦仍在 TODO | -| 4 | **E 级卫生件**（test_kit static var 串台风险、4 套件自建断言出口、157 处 untyped 容器、76 处 lambda） | 工程债批。本批只统一了**新写**断言的出口，存量未动；test_kit 的 static var 是「并发跑批」的前置障碍（并发分层方案的前提） | -| 5 | **行覆盖率度量缺失** | 基建评估项。Godot 无内建、第三方属新基建；现行补洞靠「零指名清单 + 人工判定」，是否引入度量待裁 | -| 6 | **`smoke_all.gd` 拆分**（单文件承载 1127 项检查） | 工程债批。本批按契约只做入闸与改名裁点，不拆不重构；拆分登记在册 | -| 7 | **parity 逐位一致比对的触面判定为粗粒度路径匹配** | 测试基建批。触面表含 `battle_orchestrator.gd`，改该文件即要求批准发起 MC；若嫌过重可精化到「是否改动取数/结算数值」的语义面 | - -**改动面**：游戏代码 - -**状态**：待写卡（备选） - -#### 营地交互重做·五张需求卡片（2026-10-18 登记，来源=会话提及） - -**实况**：2026-10-17~18 需求讨论澄清会话产出结论文档，用户令按工作内容维度拆卡、卡片不预占迭代号。五卡已写（顺序＝执行顺序）：①存档制数据层改造批 ②主菜单三入口化批 ③选档界面新建批 ④营地场景图新建批 ⑤Esc 浮窗与营地顶栏批（各卡估时与内容见卡片自身）。三道复核：grilling 子 Agent 对抗审查（五卡各一）→v1.1；用户裁定「事项按推荐的来」→v1.2；用户两次订正（**卡④留在批内不踢出**；前置归用户自立批，Agent 不代跑不代产——曾越权起草的点选反馈设计稿 v0.1 已撤回删除）→卡④ v2.2；**卡④ 2026-10-21 用户令退回美术设计段（v2.3，非有效卡，美术设计闭合后重立卡）**。①②③⑤ 零待裁点可编工程波次：②③ 硬耦合同波（「进入存档」钮落点＝选档界面），① 是 ③ 前置；⑤ 随 ④ 代码波同行。Alpha 出口裁决（2026-10-21 用户裁）：五卡整体列入 Alpha——08「三 · 界面」已开条目，Alpha 出口依赖五卡完工与卡④三个用户侧前置销号。**工程波次一已落地（2026-10-22）**：卡①②③ 随迭代 33 实现批合回 master（合并提交 ebf40947／5c2a7bcf／508f190b，总收口 6e8f72b2），三卡需求卡片与批次产出物已按「吸收即死」退役（设计口径已吸收进 存档序列化.md／生涯.md／camp.md／08-Alpha版本标准.md v1.13／art-bible.md v3.18，反哺落文凭据=文档批 git 提交 1864f157＋9f7b3e8a）；卡④（营地场景图）退回美术设计段待重立卡、卡⑤（Esc 浮窗）随卡④ 代码波同行，两卡未编排——编入哪一迭代由用户经迭代编排段发令。关联文档： -- 设计澄清定稿：reports/需求澄清-营地交互重做-2026-10-18.md（v1.0：目标体验原话／目标结构树＋纵深稿／10 条交互裁决／验收口径／切批原则／遗留待裁） -- 卡④：reports/需求卡片-营地场景图新建批-2026-10-18.md（v2.3，**2026-10-21 用户令退回美术设计段，非有效卡**，美术设计闭合后重立卡，见缺口） -- 卡⑤：reports/需求卡片-ESC浮窗与营地顶栏批-2026-10-18.md - -**缺口**：卡④（营地场景图）**已退回美术设计段**（2026-10-21 用户令）——美术线未闭合，按 req-card 第〇步不具写卡资格，现卡 v2.3 为非有效卡，五项前置销号后方可重立卡：P1 美术渠道（**2026-10-22 已裁＝B 插画级新产**，✦ 渠道作者自跑远程生图管线；规格沿用 art-bible §8.1/§8.2 既有裁决）；P2 像素规格（Q6 甲过渡口径已裁，执行归用户线）；P3 点选反馈设计稿（用户线，未受命开工；Agent 曾越权起草 v0.1，已按用户令撤回删除）；P4 参照物（用户后续找）；P5 GDD/art-bible 落文（定稿后用户发令）。销号完毕且美术定稿（样张过审＋art-bible 条款版本）后卡④方可进代码实现波次。 - -**改动面**：文档＋游戏代码＋美术素材 - -**状态**：文档设计已闭合＋待美术设计＋已写卡＋已写卡 - -#### 需求卡片入库纪律未登记——502 批遗留的悬空待办（2026-10-18 登记，来源=批次移交） - -**实况**：2026-10-16 迭代 29 编入批（提交 `21c83f5`）认定「需求卡片写进了 roadmap 却没在待办清单登记」属流程漏洞，需要补一条卡片入库纪律。该条至今在待办清单清单内查无（2026-10-17 与 2026-10-18 两次全文检索零命中）。唯一记过它的地方是根目录状态文件未决面第 31 行，该文件已于 2026-10-18 用户裁废除，故改记本条防遗忘。待裁：这条纪律要不要立；立则写进归属所指的 process-conventions。 -- 相关文档：design/engineering/process-conventions.md 五段流水线的登记段 - -**改动面**：文档 - -**状态**：待裁决 - ---- - -#### req-card 技能的 WorkBuddy 与 ZCode 两份副本内容不一致——取齐待裁（2026-10-18 登记，来源=批次移交） - -**实况**：用户级技能 req-card 在本机有两份副本，分别位于 WorkBuddy 与 ZCode 两个 harness 的用户目录 skills/req-card/SKILL.md（都在仓库之外，仓内没有任何登记处）。2026-10-18 逐字节比对：两份内容不同——迭代 28 那批只补了 ZCode 一份，WorkBuddy 那份没跟着改。这条欠账此前只记在根目录会话状态文件的未决面第 32 行，该文件已于 2026-10-18 用户裁废除，故改记本条。待裁：以哪一份为权威取齐，或两份各自演化。 - -**改动面**：工具代码 - -**状态**：待裁决 - ---- - -#### 「魔法道具」与「罕见」两个旧叫法的残留未扫——扫不扫待裁（2026-10-18 登记，来源=批次移交） - -**实况**：「魔法道具」随 2026-09-15 可选类道具删除而失效，「罕见」随 2026-09-14 分辨率档位批换装而失效，正文里仍有残留。2026-10-18 实数（全仓 markdown 检索）：魔法道具 23 处、罕见 17 处；此前根目录状态文件记的「约 30 处／约 18 处」系旧读数。两词都不在 `tools/doc_term_audit.py` 的退役词表里，机器闸抓不到，只能人工裁。待裁：扫或不扫；扫则把两词追加进 doc_term_audit 退役词表防再犯。 -- 相关文档：design/gdd/ 正文用语（权威对照=design/gdd/术语表.md） - -**改动面**：文档 - -**状态**：待裁决 - ---- - -#### 「通关」与「通过第 N 关」两种口径混用——统一与否待裁（2026-10-18 登记，来源=批次移交） - -**实况**：「通关」一词既被用来指「打完一整局冒险」，也被用来指「通过第 N 关」，2026-10-18 实测 design/gdd 内 188 处（此前状态文件记 273 处，口径是全仓）。歧义直接影响难度曲线读数与验收判据的表述——同一个「通关率」两种读法差一个数量级。待裁：是否定单一口径并逐处改写。 -- 相关文档：design/gdd/01-核心循环.md 与难度曲线、验收类文档的措辞口径 - -**改动面**：文档 - -**状态**：待裁决 - ---- - -#### 流程动词族黑话的第二波清扫待发令——GDD 正文约三千处（2026-10-18 登记，来源=批次移交） - -**实况**：2026-10-15 用语规范批只按 A 表替换了词面约 250 处（十二行），流程动词族——需要作者额外解释才看得懂的一类说法——在 GDD 正文仍有约三千处未处理。第二波至今未发令。待裁：第二波的范围与发令时点。 -- 相关文档：design/gdd 全树正文用语（权威词表=design/gdd/术语表.md 用语规范节） - -**改动面**：文档 - -**状态**：待裁决 - ---- - -#### 调试入口写死行必须在发布前删除——game/presentation/main.gd:196（2026-10-18 登记，来源=批次移交） - -**实况**：2026-10-16 用户令把调试入口改为恒开，`game/presentation/main.gd:196` 的 `_debug_entry` 现恒为 true、不再读环境变量（2026-10-18 实查该行仍为 `_debug_entry = true` 并带「发布前清」注释；:197 是最顶层浮层角标的可见性赋值）。发布前删掉 :196 这一行即可——角标可见性随门控失效自动隐藏，无第二处改动点。不删的后果：正式包里调试浮层与角标常显。证据=该行代码注释与 2026-10-16 调试入口批的实装记录。 - -**改动面**：游戏代码 - -**状态**：待写卡 - - ---- - -#### L3 屏壳切换探针的判定被仓库外存档状态污染，跑批绿红不可复现（2026-10-18 登记，来源=审计发现） - -**实况**：2026-10-18 卫生批跑全量档时 03 探针 --click 与 04 探针 --full 双双「基线绿→现红」，唯一失效单元是 `game/probe/screen_flow_probe.gd` 的第④步（菜单开新冒险进不去，⑤⑥⑦三条随之因前置不满足连带红）。根因已钉死且与本批及任何代码改动无关：`user://save.json`（主区与所有 worktree 共用同一份、不入 git）里现存一个 `breakpoint` 断点，而 `game/presentation/main.gd:476-482` 按「二轮修改批 A」的用户目检裁决，在 `save_manager.has_breakpoint()` 时弹实底确认框「已有未完冒险（第 N 关）——开新冒险将覆盖旧断点」并直接返回、不开冒险；探针第④步只用前缀匹配找「▶ 开始冒险」并按下、等 3 帧就断言进冒险屏，它隐含假设「存档里没有断点」。三条判据：主区那份未受本批影响的 master（`ea69670c`）单跑同一探针复现完全一样的 7 处；同一 worktree 同一代码把 save.json 临时移开再跑立刻 `PASS — 六步主流程＋回退路径全绿`（跑完存档逐字节还原，sha1 `dd67444c35be` 与移开前一致）；`game/**/*.gd` 自 10-17 那次绿回执 `7ffd1dc0` 之后零改动。断点来源＝上一轮 `ui_click_probe` 或任一会话跑到中途留下的未完冒险（存档账目已累积到 `adventure_total=6`、`level_clear_counts={1:18,2:7,3:4}`）。后果是验证闸的绿红取决于「这台机器上谁最后跑过」，正是 test-conventions §8「判定可靠性优先于覆盖率」所管的同一类缺陷。修复方向两条，均待写卡时定：探针侧自救（第④步前先走弃断点通道，或在确认框上按「开新冒险」再断言）＝改 `game/`；跑批侧隔离（给探针配独立 user 目录）＝改 `tools/probe_gate.sh`，⚠ 此路有一条未验障碍——本日用 `--user-dir` 指到空目录跑该探针，Godot 挂住零输出、超时未出结论，走这条要先查明成因。证据已指认，按 §12.1 属需求性工程条目，跳过设计线。 - -**改动面**：游戏代码＋工具代码 - -**状态**：待写卡 - - ---- - -#### 效果引擎「系统无状态」原则缺架构文档条目（2026-10-20 登记，来源=会话提及） - -**实况**：用户 2026-10-19 会话裁定的 ECS 架构依据（系统无状态——效果引擎这类系统零运行时可变状态、数据由宿主对象持有并随宿主生灭、状态按参数传入系统、系统只做判定）是「效果引擎无状态化」重构批的立项判据（上游＝迭代 31 卡② 移交的计数器寿命域判据线——该登记条目已在本条闭合时整条删除，判据现由 architecture.md v1.9 条 8 承载；提案=reports/提案-效果引擎无状态化-2026-10-19.md v1.3 §7.9 #1），但 `design/engineering/architecture/architecture.md`「架构原则」节（原 7 条）无「系统无状态」条目——立项判据暂无权威文档出处（2026-10-19 全仓检索「无状态／纯计算」零命中，提案 §10.3 实查；原 `design/registry/` 两 yaml 已随 2026-10-19 用户裁注销删除，无可迁凭据）。重构批是代码批、禁写 `design/`，文档级补条只能另立文档批。 - -**现状换代（2026-10-21 文档批写入完成）**：architecture.md「架构原则」节已补第 8 条「系统无状态」（条文序位=呈现层契约成文条之后，与条 1 核心层纯逻辑、条 5 fail-fast 交叉核过无冲突），effect_engine 模块行与战斗域装配节同步改写为 ctx 形态描述——design/engineering/architecture/architecture.md v1.9（2026-10-21 用户裁写入）。 - -**改动面**：文档 - -**状态**：文档设计已闭合 - ---- - -#### 结算明细日志行序重锚批（2026-10-21 登记，来源=批次移交） - -**实况**：迭代 32 卡① N7 改动互换 `seal_miss`／`insurance_used` 两行日志顺序并改写豁免态 highlight（豁免态＝insurance_used 行先行且 highlight 置空；未豁免态＝两行相对序不变但 `seal_miss` 发射时点后移——完整对照见 git 提交 d00f24a8 批内实现报告，报告已退役）；`playtest_logger._on_step_row` 逐行落盘含 highlight 字段，与基线数据逐项比对的 JSONL sha256 校验必红，实现批按规未发起、11 号闸落 skip。**用户 2026-10-21 裁＝批准另立重锚批，发起时点另定**（重锚批只能由用户发起）。 -- 相关文档：`sim-data/` 锚与 `tools/parity_anchor.py`（重锚执行归用户发令批） - -**改动面**：工具代码 - -**状态**：待裁决 +# 待办清单 + +本清单是流水线的唯一登记处：要做的事先在此登记一条，随流水线段推进改状态，做完整条删除；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据含可选优先级，正文＝实况/缺口/改动面/状态四属性）与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 + +#### 超预算图策略升级路径——等比缩放与滚动视口两案待裁（2026-10-24 登记，来源=批次移交） + +**实况**：迭代 34 卡④（信息迷雾可见性批，已合回 master，提交 16a7ec80）按「参数限图」交付，图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图，两条升级路径都要动冻结件，均未设计：①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值；②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13，已超出该上限（level-map 已登记随动缺口，本批不裁方案）。 +- 相关文档 design/gdd/systems/冒险循环/关卡节点图生成.md v1.3（调参表「图包络」行） +- 相关文档 design/gdd/ux/level-map.md（画布冻结公式） + +**缺口**：两案需用户裁决后再走设计讨论；未裁前禁改画布冻结件。 + +**改动面**：文档 + +**状态**：待文档设计 + +#### game 代码结构审查批——行为缺陷定点修＋结构重构候选（2026-10-24 登记，来源=审计发现） + +**实况**：审计报告＝reports/审计-game代码结构审查-2026-10-24.md（2026-10-24，全目录只读审查，零测试执行、结论全部静态阅读）。缺陷证据（报告 §二 Critical 行为缺陷段＋定点清单，含行号）九件：①core/damage_controller.gd:215 用 `==` 比较单位字典（Godot 4 语义＝逐键内容比较）——内容全同双敌其一死亡误作废对方单据，应 `is_same()`；②presentation/views/standee_body.gd:172/188 蓄力意图档常量错配（GOLD_INK vs GOLD_DEEP）死代码，三档运动签名设计失效且无测试覆盖；③presentation/views/battle_end_overlay.gd:281-287 庆祝 tween set_loops 无限叠加泄漏（close 只隐藏不 kill）；④批量模拟×两层调试并发互斥缺口（presentation/views/debug_overlay.gd:84＋presentation/main.gd:712-715/1489＋presentation/tune_sim_controller.gd:46-58——用户两击可并触发，演出扭曲＋测量作废）；⑤presentation/modal_stack.gd:23-29 未登记层/重复开层静默降级（违 fail-fast，当前调用面无违规者属埋雷）；⑥core/minesweeper_rules.gd:8-9 两条核心信号零契约成文（违 code-conventions §2.1）＋全库信号注释载体普遍 `#` 非 `##`；⑦明细行类型封闭枚举漂移（core 实发 13 类 vs battle_orchestrator.gd 头注 9 类）；⑧core/level_runner.gd:895/779 玩法数值字面量（relic 基价 15.0、散折 0.8，自注 provisional）；⑨presentation/views/battle_stage_view.gd:332-338 以 display_name 子串匹配解析受击目标（同名敌错位，应携带 enemy_id）。另有定点小件与结构重构候选（报告 §三）：main.gd 1508 行可判离块 ~440 行／board_view.gd 1219 行瓦片算法＋英雄精灵可拆／adventure_runner 令牌池子系统 ~500 行可拆 CurioDeck／level_runner 商店子系统 ~260 行可拆／断点 schema 三处重复登记可单点化——重构候选非缺陷，是否立项由写卡段呈报用户裁决。**2026-10-24 写卡会话收口**：用户裁五件重构候选全部立项（卡①缺陷修先行落地后重构再动）；缺陷⑦明细行枚举漂移划归「架构与规范对齐批」条目（词表 13/15 归该批裁决，缺陷卡不碰头注）；报告 §三「其余小件」（level_map 视图直读/BFS、main 死变量与 confirm 旁路、settle_batch 空判、row_pacer 常驻 flush、_fatal assert 剥离、rng_service early-return）未立项，留审计报告在册待后续点名。切卡输入＝审计报告 §二/§三，四卡均零待裁点。 + +关联文档清单： +- 需求卡片 reports/需求卡片-game行为缺陷定点修批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），缺陷修主卡·迭代批，八件缺陷＋定点小件七件，零待裁点） +- 需求卡片 reports/需求卡片-重构main判离批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），重构卡 R1·迭代批，零待裁点） +- 需求卡片 reports/需求卡片-重构boardview拆件批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），重构卡 R2·迭代批，零待裁点） +- 需求卡片 reports/需求卡片-重构runner拆件与断点schema单点批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），重构卡 R3·迭代批，零待裁点） + +**改动面**：游戏代码 + +**状态**：待写卡＋已写卡＋已编迭代 37 + +#### S9 类型闸正则失灵修复——R2 恒零命中＋static 函数漏网（2026-10-24 登记，来源=审计发现） + +**实况**：工程债证据＝reports/审计-game代码结构审查-2026-10-24.md §二 C1（已独立复现）：tools/audit_type_hints.py:29 的 FUNC_DECL 正则两洞——①无返回类型声明按 GDScript 语法必然以 `:` 结尾，正则要求 `)` 后只跟 `->`/注释/行尾，R2 目标形态 100% 失配（R2 从上线起恒零命中恒绿）；②`^(\s*)func` 不认 `static ` 前缀，static 函数对 R2/R3 整体漏网。实证存量（闸当前退出码 0）：core/level_runner.gd:632、core/attunement.gd:10、presentation/main.gd:565、presentation/views/hud_presenter.gd:10-11、core/reward_economy.gd:104/119/131/146、core/unit_container.gd:275（写卡会话路径订正：hud_presenter 实址 game/presentation/hud_presenter.gd，非 views/）。属架构文档测试域自警的「规则扫描面为空＝恒绿」静默失效模式（零命中自检因 R1/R3 仍有命中能力未拦住）。2026-10-25 规则修订（改动四类）：本件属工程改动（闸件修复，直改类）。执行口径＝修 `tools/audit_type_hints.py:29` FUNC_DECL 正则两洞（①无返回类型声明的声明形态恒失配；②`^(\s*)func` 不认 `static ` 前缀），存量以开工时盘面清点（实证九址为已知下限），验收走撤销证明。原需求卡片按违形退役：结论已回写本条目，卡片删除，全稿查 git 历史（提交 546e5113）。 + +**改动面**：工具代码 + +**状态**：待执行 + +#### S13 gdstyle 免名单把数字当身份——存量债改小也报「基线外新违规」（2026-10-25 登记，来源=批次移交） + +**实况**：工程债证据＝迭代 35 卡② 合回前后实测（master 合回笔 `5499eb9c`）。闸件 `tools/gdstyle_gate.py:82` 把每条违规登记成三元组「文件|规则|消息全文」，而 gdstyle 的消息文本里带具体数字（如 `function 'resume_adventure' is 104 lines long (max 50)`），基线 `tools/gdstyle_baseline.txt`（241 行）按整句逐字比对——**只要某函数的行数/分支数/变量数发生变化，老违规就匹配不上，被判「基线外新违规」并判红，改小也算新增**。卡② 一批即因此冒出 12 项假新增，逐条对基线旧值核实全是存量债的计数漂移：`config_db_cross_validator.cross_validate` 159→107 行／31→21 分支／39→24 局部／嵌套 6→5（本批按卡片删除跨表校验④整段所致，债变小）、`level_runner` 类变量 40→38 且其「文件 1013 行超长」违规已消失（债被还掉）、`start_level_external` 参数 8→7、`main.gd` 1509→1507、`adventure_runner` 类变量 43→42／文件 1050→1051／`resume_adventure` 104→108 行（本批加断点代差标记键拒绝检查多 4 行）。本批真正新写的超标仅 1 处（新函数 `validate_graph` 72 行／20 分支），已当场拆成四段修掉。**盘面后果**：卡② 按用户令零复跑合回，master 尖 5499eb9c 从未整套跑绿过代码域闸；下一次任何批跑代码域闸都会看到 S13 红这 12 项（不处理则每批重复一次「要么重生成基线、要么被红挡在合回前」）。卡片裁决留档（卡片已违形退役，git 历史可考）：四待裁点已拍板——稳定身份键／恶化判据超登记值即红／本批治本＋批内刷新基线／refresh 加对账自检与骤降守卫；验收按 2026-10-24 撤销证明口径执行。2026-10-25 规则修订（改动四类）：本件属工程改动（闸件修复，直改类）——原卡片按违形退役，结论已回写本条目，卡片删除，全稿查 git 历史（提交 36b444eb）；执行口径＝治本档（四待裁点已拍板项照录上文），用户发令直改。 + +两档方案（第一条只治标）：① 治标＝人工跑一次 `python tools/gdstyle_gate.py --refresh` 重生成基线＋一笔提交，约 5 分钟，但键形态未改，下一批再动这些文件还会重演；② 治本＝改 `tools/gdstyle_gate.py` 的键构造段（:77-90，约 10–20 行）为「文件|规则|函数名」——函数名从消息里正则提取 `function 'x'`，无函数名的条目（类变量数/文件长度）退化为「文件|规则」，并**另加一条恶化判据**防新键吞掉真问题（同一函数当前指标较基线登记值恶化超阈值即判红，纯规范化数字会把 104→300 行的恶化也放过去，不可只靠数字抹平）；随动＝重生成 `tools/gdstyle_baseline.txt`（241 行按新键重排）、`tools/run_all_gates.sh` 头注与 `game/tests/README.md` 工具速查表的 S13 描述各一行、撤销证明四项（新增一处真超标必红／同函数改小改大的数字漂移禁止再冒新／恶化超阈值必红／禁闸内自动重生成清基线换绿的自检仍绿——各配撤销该判据见红＋还原复绿）。合计约 **0.5 个工作日**，工程改动（tools/ 闸机面）直改类。 + +**改动面**：文档＋工具代码 + +**状态**：待执行 + +#### S6/S7/S8 静态规则落地——编排唯一性/禁 await/信号纪律三闸（2026-10-24 登记，来源=审计发现） + +**实况**：工程债证据＝reports/审计-game代码结构审查-2026-10-24.md §二 C2：三规则 static_scan.sh TODO 在案（架构文档静态扫描表自认未落地）——S6 core↔core 信号禁 lambda 捕获 self、S7 B2/B3/B4 API 符号命中文件 ⊆ B1 文件集、S8 结算路径 await 零命中。2026-10-24 审查人工 grep 结论干净（core 零 await、A2/B3/B4 零相互直调），但防线缺位＝回归无闸。S7 前置：须先在架构文档成文 B1 文件集边界（含 core/settlement/ 五段类与 damage_controller——现归属表零条目，见「架构与规范对齐批」条目①）。**2026-10-24 用户裁：条目整条冻结待④（「架构与规范对齐批」）裁决后再写卡**——写卡会话核对结论：S6（core 信号禁 lambda）与 S8（结算路径禁 await，文件集可按现行结算文件直接枚举）与④零依赖、技术上可先行，但按「先裁④再动③」整条冻结不先行。 + +**改动面**：工具代码 + +**状态**：待写卡 + +#### 验证集清单快照重生成——断言索引含退役措辞与旧行号（2026-10-25 登记，来源=审计发现） + +**实况**：工程债证据＝迭代 35 卡② 验收审计申报（git 历史可考：合回提交 5499eb9c 内的 reports/iter35-卡②-验收审计-2026-10-24.md，该产出物已按吸收即死退役）：game/tests/验证集清单.md 是批 B 迁移时的断言文本快照索引，只由 tools/extract_checks.py 手工重生成、不进任何闸；卡② 断言面换代后十余行仍含 first_script／template_pick 等退役措辞与过期行号（实测 first_script 8 处、template_pick 2 处），与宿主现文不符。2026-10-25 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝走重生成：tools/extract_checks.py 两小改（头注模板数据驱动化＋新增 --carry-from 按同指纹承接「白话释义／处置」两列、承接文本内旧宿主文件名映射为新名）后 --extract --force 重生成（缺省三宿主全量口径；实测漂移＝清单 1067 条 vs 现提取 1544 条〔消失 67／新增 539／字面变更 14 对〕，template_pick 实测 3 处——登记句「2 处」少数一行），--diff 须 PASS；重生成后 grep node_map_templates／first_script／template_pick 预期零命中（若命中须全为反向断言）。原需求卡片按违形退役：结论已回写本条目，卡片删除，全稿查 git 历史（提交 1fb44cf4）。 + +**改动面**：游戏代码＋工具代码 + +**状态**：待执行 + +#### 测试宿主改名——node_map_templates_test.gd 已承载生成图确定性断言（2026-10-25 登记，来源=审计发现） + +**实况**：工程债证据＝迭代 35 卡② 反哺点⑧：game/tests/integration/node_map_templates_test.gd 现承载「生成图确定性断言套」，文件名中的 templates 是模板时代遗留；manifest 登记行＝game/tests/run_all.gd:90。改名为 node_map_determinism_test.gd 须同批改 manifest 路径行。2026-10-25 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝git mv 宿主两件（.gd＋.uid）＋改 run_all.gd:90 路径行＋文件内 4 处自引用字面量（:1/:10/:26/:31），断言判据零改动，直跑新名退出码 0 为验收。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。 + +**改动面**：游戏代码 + +**状态**：待执行 + +#### level.tres 表尾注释含迭代叙事（2026-10-25 登记，来源=审计发现） + +**实况**：工程债证据＝迭代 35 卡② 反哺点⑨：game/data/tables/level.tres 表尾注释写「旧 15 张模板池（3 关 × 5）随迭代 35 卡② 清出」，与 doc-conventions §5 禁写变更叙事有张力；卡② 卡片 T3 明令表尾写模板去向注记，故处置面限于叙事形态（删迭代号、保留图源换代事实句），不删去向事实。2026-10-25 规则修订（改动四类）：本件属工程改动（数据表注释维护，直改类），执行口径＝条目原裁（删迭代号、保留去向事实句、表内零改动）。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。 + +**改动面**：游戏代码 + +**状态**：待执行 + +#### 架构与规范对齐批——代码结构审查发现的文档-实现漂移（2026-10-24 登记，来源=审计发现） + +**实况**：审计报告＝reports/审计-game代码结构审查-2026-10-24.md（§二 C3/C4/C5＋§三 漂移清单）。漂移与待裁件七件：①架构文档「模块归属」多行 API 清单与实现不符（A2 try_* 便捷形/B2 ambush_grant_plan/B4 equivalence_supply 不存在；实有 grant_reserve_ap/finish_round_stop/check_skill_unlocks 未登记；damage_controller 与 settlement/ 五段类零条目——S7 落地的前置）；②code-conventions §1.3 核心写调用位置——三拆件控制器（presentation/curio_interact_controller.gd、camp_shop_presenter.gd、treasure_interact_controller.gd）持写调用 vs 规范「只允许在组合根出现」的 spec-AC 冲突，须裁「改规范成文组合根家族」vs「调用收回 main」；③A3→EffectEngine 反向依赖（core/action_economy.gd:43-49）——真违约或事实源失真二选一（effect_engine 降层登记基础层 vs B1 代发 vs 仅补登记）；④架构文档 :149/151 层合同计数写死 17 项 vs LAYER_CONTRACT 实 18 项；⑤明细行协议三处三个数（头注 9/实发 13/架构文档 15）；⑥§1.3 例举 submit_window_selection 符号已退役；⑦core/effect_engine.gd:360 校验文案「9 项」实为 18 项。 + +**缺口**：一次 doc-design 会话逐点裁决（②③有方案取舍须用户拍板，①④⑤⑥⑦为机械对齐）；裁决后走文档设计改动直改写入 design/engineering/。 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 死断言候选三条处置——照迁禁删断言的退役或改判待裁（2026-10-25 登记，来源=批次移交） + +**实况**：批 B 断言迁移施工验出三条死断言候选（照迁禁删，宿主在座、结构复核通过、拦截能力未证——执行序遮断或执行前提在本机不可达）：① V2-s4 旧单档迁移不变式 `game/tests/system_test.gd:185`（本机磁盘态已固化，可红面「旧档在而槽 1 缺」在生产码变异下不可达；补审 A-2 已补结构例外标签——迁移逻辑本体由 save_manager_domain v0 迁移链断言覆盖）；② V3g 营地入口缺失 `game/tests/system_test.gd:481`（menu campbtn 置 null 后 boot 信号接线先崩，护栏在执行序上被遮断不可达，拦截语义由 boot 崩与前置断言代偿）；③ 区间行上下阶实际流动 `game/tests/unit/core/board_gen_reward_test.gd:297`（守面 `samples` 与 `seen[rid].size()` 为同一字典同引用恒假，系源码自带的测试侧死逻辑、非生产缺陷）。证据＝批B迁移账本 :238/:241/:273（账本已退役，考古＝git 历史——删除批 53075baa，删除前全稿见历史版本 5644d30c）＋冻结基点 `game/tests/验证集清单.md` 头注（commit 1aea9397）。另：核代码补审 C-2～C-6 五件测试增强候选原登记备查于账本 §十五，随账本退役并入本条备查——C-2 计数闸残缝（visible 标志位≠渲染面，隐藏匿名旧钮接回双闸漏过）、C-3 _stage_faces extra 静默吞键（match 无默认臂）、C-4 顺序耦合无守卫（boot_chain 须先于驱动执行；lifecycle_matrix 永久改写槽模板不还原）、C-5 camp 残留档使 V3g 红的原因标注误导（不静默）、C-6 V1a 候选表与 LAYER_CONTRACT 双维护（新增层忘登则漏检盖顶回归）。 + +**改动面**：游戏代码 + +**状态**：待写卡 + +#### 营地五界面窗口化批——营地功能页点开后的呈现形态（2026-10-22 登记，来源=会话提及） + +**实况**：营地场景图（卡④）把旧四柜台换成「一张可点击的场景图」，从场景图点进去的**五个功能界面**——锻造工坊／秘宝匣／天赋树（树淬炼）／奖励格图鉴／生涯记录——其**呈现形态尚未定稿**：是各开独立全屏页（生涯先例），还是作为**窗口**打开（场景根留底）。**作者 2026-10-22 明示意图＝窗口打开，不是全屏页**。该形态原属卡④ §9 代拍板白名单第 2 条（非用户裁、且「缩放虚化」第三形态禁批内自选），故单独立批，不在美术设计段定值。 + +**依赖（单向）**：**强依赖卡④**（场景图素材定稿 + 五界面入口改挂）完成；卡④不依赖本条 ⇒ 排序在卡④之后。**与「营地美术素材怎么生成」无关联**（不影响出图／分层／提示词）。 + +**缺口**：① 窗口形态与叠层规则定稿（独立全屏页＝场景根隐藏／单一内页切换＝场景根留底）；② **窗口化＝场景根留底 ⇒ 会引出「背景要不要压暗／虚化」**，而该点撞上 art-bible §2（2026-10-22 缩窄后**仍禁情绪表达**，背景压暗属氛围表达仍在禁区）与卡④「缩放虚化禁批内自选」——**须在该批开工前一并裁掉**；③ 五界面各自的返回／关闭钮（卡④ v1.1 已承诺各带一个）。 +- 相关文档：卡④ §9 代拍板域 → 独立成批（呈现层＋文档线）；窗口形态与叠层规则写入 `LAYER_CONTRACT` 与 [camp](design/gdd/ux/camp.md)「叠层与开合」节 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 验收闭合规则——下一次迭代实测评估（2026-10-21 登记，来源=审计发现） + +**实况**：2026-10-21 已改工作流技能与规约——[测试规范](design/engineering/test-conventions.md) 新增 §9（改动—验收对照表、真实入口、撤销证明、禁削弱、独立验收审计），[AGENTS.md](AGENTS.md) 硬性红线新增「验收闭合」，`req-card`／`iter`／`batch-closure` 三份技能同步，[流水线闸](tools/pipeline_gate.py) 新增 C3 卡片结构检查。规则文本已落地，还没在真实迭代上跑过。 + +**改动面**：文档 + +**状态**：待裁决 + +#### UI 贴图重构批——元进度件仍是程序化占位（2026-10-13 登记，来源=审计发现） + +**实况**：营地的柜台场景贴图与元进度图标目前都是程序化画出来的临时形态，没有上贴图。这条债原先只写在美术侧的资产清单里（[美术资产清单](design/art/art-assets-checklist.md) 第 134 行与第 175 行，原文注明"营地现为程序化占位，状态记录 121⑧ 口径，排期归 UI 贴图重构批"），2026-10-13 由 UI 美化三层诊断转立本清单专条。规格其实已经定了——烛光黄 `#F6C667` 配木色 `#8A5A34`（见 [美术圣经](design/art/art-bible.md) §4.4），素材来源允许走"通用图标改色复用"这条低成本渠道。2026-10-21 用户裁营地交互重做五卡整体列入 Alpha：营地柜台贴图随之转入卡④营地场景图新建批（新场景取代现四柜台覆盖层），本条只余元进度件贴图终稿，排 Beta。 + +**缺口**：还差一次「自己画 vs 找 CC0 素材改色」的美术裁决（见 [美术资产清单](design/art/art-assets-checklist.md) §0 的复用渠道闸），裁决后才能定素材工单写卡。 + +**改动面**：美术素材＋游戏代码 + +**状态**：待美术设计（备选） + +#### 战斗一屏样张 P0 未开工——界面成品是否过审的那把尺子还没建（2026-10-13 登记，来源=审计发现） + +**实况**：[美术圣经](design/art/art-bible.md) §7.1 明文写着"程序化占位＝临时态，任何屏的终稿闸＝§1.4 整屏样张过闸；占位态禁止跨里程碑"。而 [美术素材状态清单](design/art/art-status-checklist.md) 把「战斗一屏样张」这件最高优先级的素材标的是**未开始**——也就是说，**判定界面美术算不算过关的那把尺子到现在还没造出来**。2026-10-16 曾编入迭代 30 卡②（UI 呈现三卡批序位②），2026-10-17 用户裁定不满足「迭代＝代码实现批」的开发条件、剔除回待设计（理由＝样张交付物本身就是设计规格，正式字体与素材均未定稿；同日样张批开工已被用户终止）。v1.4 旧卡留 reports/需求卡片-战斗一屏样张批-2026-10-16.md 作素材，非已写卡状态，重启不得直接开工。Alpha 出口裁决：列入 Alpha 硬前置——站桩帧动画的定版前置与主角＋三 Boss 重产都依赖它。 + +**缺口**：还差「设计讨论→需求澄清→美术定稿」一轮设计（样张即设计目标图，产出尺寸档/色板/明度档清单反向给素材批），定稿后重新立卡方可开发。旧卡 v1.4（reports/需求卡片-战斗一屏样张批-2026-10-16.md）在册但非已写卡状态，其前置未完成三件：①这一轮设计未做，样张的目标规格清单没有来源；②战斗一屏所需素材未定稿（前置里的正式字体半边已定稿——2026-10-24 用户裁 Fusion Pixel 单套即终稿，见 [美术圣经](design/art/art-bible.md) §7.4）；③2026-10-17 用户已终止该批开工，重启须重新立卡。 +- 相关文档：美术线（战斗一屏样张的验收标准归 [战斗表现](design/gdd/systems/战斗循环/战斗表现.md) 与 [美术圣经](design/art/art-bible.md) §5.1 共裁） + +**改动面**：美术素材 + +**状态**：待美术设计 + +#### UI 氛围层与九宫格切片观感修——光柱硬边与面板切片错位（2026-10-13 登记，来源=审计发现） + +**实况**：原两处，一处已修一处存续。①光柱硬边**已修**（2026-10-14 迭代 26 T4：`ui_kit.gd` 第 263 行起的光柱贴片改带内 alpha 0→0.05→0 三角过渡＋纵向衰减上亮下暗，grilling Q7 裁连续 alpha 方案；LINEAR 白名单已随反哺入册 art-bible v3.14 §8.2）。②九宫格切片错位**存续**——结算屏与图例屏的面板边缘可见错位小方块，成因是九宫格切片参数与素材尺寸不匹配（仪式石框 258 字节小图按 12 像素切片、石板亮面板 314 字节按 16 像素切片，铺到四百多像素宽面板中段拉出错位），须先核素材尺寸能否撑住新切片值（border_stone/panel_stone 均 48×48），可能要重出素材，归「UI 贴图重构批」后续贴图批次。 + +**缺口**：还差「UI 贴图重构批」里的素材尺寸核对与「是否重出素材」裁决，才能定切片修法。 + +**改动面**：美术素材＋游戏代码 + +**状态**：待美术设计 + +#### 旧行为 MC 行为锚全数作废——重锚归数值批（2026-10-06 登记，来源=批次移交） + +**实况**：案C 地图伤害账殿后批（git 7ef18ac，状态记录 371）改变每轮结算行为序——授予段不再兑付任何伤害（伤害形态单据暂存至战斗段末，段内序＝主角先手→逐敌还手→地图账），既有全部 MC 行为锚与基线逐项比对锚所锚行为已不存在，**全数作废**；新段内序断言已入冒烟闸。按 sim-data MC 缓存层规则（无数值调整禁重跑），重锚不在改动批执行；重锚前一切 MC 旧读数只作历史存档，禁止与新行为逐项比对。M4 数值批卡 v1.2 已收该义务（F19：对拍锚按案C 新序重推导、T6 四带复算按新行为首采立新锚）。 + +**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 + +**改动面**：文档＋游戏代码 + +**状态**：待文档设计 + +#### 双层 BD 延期与备选内容总登记（2026-10-03 登记，来源=批次移交） + +**实况**：需求卡片/整合定稿系中间文档，落地完成后按吸收即死退役——用户令「只删除已完成落地的内容」，本条自承载全部**未落地**内容防丢失（每项自包含，不依赖指针）。 + +**二期件组**（触发＝迭代 12 出口读数+用户点名立项；各件机制形态已定，数值 provisional）： +- **战斗→扫雷跨阶段回流**（穿刺流）：击杀轻甲敌人返还 1 AP——战斗收益反哺开格动机；AP 经济新管道，谨慎件（威胁红线③边缘，立项须专项论证） +- **穿甲锥**（穿刺×封印协同桥）：对被控制危险格的敌人穿刺伤害再提升 +- **孤注一掷**（普攻流二期锚点件）：每轮攻击次数减至 1、该次伤害大幅倍增——攻击频率规则改写 +- **悬浮魔法球**（魔法流二期）：轮末召唤物环绕，每轮自动对最强敌人造成魔法伤害——需战斗单位系统新增实体类型（召唤物/持续伤害源） +- **商店置换服务「符文重铸」**：攻击类型族后期流派转换（花 GP 重掷攻击类型相关件）——商店新交互 +- **件派生动词白名单（非信息类）**：移除封印印记回收返 AP/定向熄灭伤害型地形格/重掷 RAP 等第三盘面动作——**触发条件＝件池 ≥30 种后玩家仍反馈操作重复且定位在操作层（非决策层）**；信息类派生动词维持全禁（R4 甲，见下备选组） +- **三期：合成进化**：两件同名/同标签件合成升品（Ball x Pit 式）——池深不足时的解药，三期再议 + +**淘金流立派缓议**（定位＝支撑引擎非胜利条件；触发＝先作件族挂配套池观察、数据支持后再立派）：吝啬鬼账本/金脉共鸣（每持有 ~N GP 攻击 +~X——GP 进伤害公式新缩放源）/贪婪契约（商店折扣+GP 掉落增税，正负双修）/消费回馈（商店购买附赠同类临时增益）/战利品鉴定（三选一必含 1 件高稀有度）。 + +**R4 乙备选案（2026-10-03 用户裁甲＝信息型永不对冲，本组冻结）**： +- 信息型清除工具件族（「除尘风箱」类：限价限量清除藤蔓/烬覆/矿尘遮蔽、恢复数字） +- 深挖钻头原案（开出深层资源、代价＝「危险格位置信息 −1」主动吃信息税——现行已改设计为非信息税形态：代价候选＝额外 ~1 AP 或踩雷惩罚加重） +- 「概率收窄」类派生动词（花 AP 把某格是雷的概率收窄，非确定信息） +- **重启条件＝R4 复查闸读数支持（信息型挫败信号，T10 呈报）+用户显式放宽红线①边界**——本组重启属红线变更，须用户发起 + +**设计知识存续口径**：七流派完整件表/逐项反例条件表/天赋树后备语言（哈迪斯 2 预算制扩容/邻接树改型/GP 价格通胀防线）存整合定稿，随实施批文档吸收迁入各 GDD 权威文档（元进度/node-reward/战斗结算/地形变异/行动经济/秘宝边界句/商店 spec）——**吸收完成前定稿不删**；喂雷流待办见「旧行为 MC 行为锚」条所在批次的历史登记。 + +**缺口**：全组为备选库：各件启用须用户发令立项，届时按件走设计讨论定机制形态与数值（二期件组机制形态已定、数值 provisional；R4 乙组重启属红线变更须用户发起）。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 扩展节点类型——危险/精英节点与特殊地形节点（2026-10-21 登记，来源=会话提及） + +**实况**：用户 2026-10-21 会话定方向：Alpha 版只留现行四类（战斗/奖励/恢复/商店），以下两类留到以后再做——①危险/精英节点（怪物与普通战斗不同、奖励肥）；②特殊地形节点（效果修饰：地图战斗资源、敌我伤害、金币比例等）。内容未设计。 + +关联文档清单： +- 相关文档 design/gdd/systems/冒险循环/关卡节点图生成.md v1.1（2026-10-21，扩展节点类型位概念） + +**缺口**：两类扩展节点的机制形态与数值未设计（用户明示暂不进 Alpha）。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 天赋树实装批登记欠账余两件——AP 上限 clamp 与三选一刷新软上限（2026-10-12 登记，来源=批次移交） + +**实况**：迭代 21 天赋树实装批顺带入册欠账三条，2026-10-13 三件终态：① **AP 上限 clamp 缺位（缺陷）**——树「开局姿态」（每关首轮 AP+1）、AP 件、时沙同走 `action_economy.gd:239 _pending_ap_delta` 排队，轮始兑现仅下限钳制（`:254 maxi(0, …)`，无上限）；**用户裁暂不设上限**——provisional 天花板亦不投，随未来数值标定窗口连同全部 AP 数值统一标定（M4 数值批已废）。② **三选一刷新软上限（设计问）**——停点内 GP 付费刷新倍率增长（×1.8/次曲线）×停点间基础价随进度递增，全程无软上限；**定性确认＝设计问非缺陷，用户裁维持现状**，归未来数值标定窗口处理，不提前单开讨论。③ **Y（_attune_refresh_y）不入断点存档（可利用漏洞）**——已修复注销（2026-10-13 用户令提前单独开修：断点快照扩列 `attune_refresh_y`＋续玩 `resume_adventure` 优先读断点〔缺键回退参数面＝旧档行为零变化〕＋单测两断言；冒烟 938/0+单测 24 套全绿）。①②留待办清单待未来数值标定窗口（M4 数值批已废；2026-10-18 用户裁＝不另行归属、未设计未启动）。 + +**缺口**：还差未来数值标定窗口的标定执行（M4 数值批已废；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属）。 +- 相关文档：① [行动经济](design/gdd/systems/排雷循环/行动经济.md)；② 行动经济+三选一/商店刷新经济（数值归未来数值标定窗口——M4 数值批已废）；③ [存档序列化](design/gdd/systems/表现与支撑/存档序列化.md)（断点域）+ [冒险结构](design/gdd/systems/冒险循环/冒险结构.md)（续玩参数面）——③已修复注销 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 棋盘战斗键盘/手柄输入（2026-10-04 登记，来源=会话提及） + +**实况**：战斗棋盘操作现行唯一输入＝鼠标——左键已开格＝移动/未开格＝挖掘，右键＝封印（封印印记一次性承诺，无移除手段），悬停承载合法性反馈（可挖域微光 + BFS 路径点迹）；全仓无 InputEventKey/JoypadButton 处理，project.godot 无自定义 InputMap 动作。**可行性已核（2026-10-04）：可做**——分发接缝现成，board_view `action_requested(cell, kind)`（kind ∈ {dig, move, flag_place, flag_pull}）是唯一出口，键盘/手柄作第二输入前端产出同款信号即可，规则引擎合法性校验零改动；Godot InputMap 原生支持键盘与手柄绑定同一动作，与鼠标并存不冲突。用户期望操作形态：十字方向移动；挖掘/封印各一独立键；方向控制选定 8 向挖掘或封印目标（8 向恰与现行可挖域同集，十字移动与立绘 4 向既有裁决一致）；键盘移动语义＝逐格步进。连带设计点四条（实施批先裁）：① 键盘模式需屏上光标格承载现行悬停反馈；② 键盘默认键位与手柄键位映射待定；③ 弹层界面（结算/三选一/商店/设置等）现行全鼠标，手柄全覆盖需焦点导航——是否同批待裁（2026-10-06 增补：暂停层〔现状态面板〕Esc 快捷通道并入本条随键盘批统一实施，弹层清单 +1 项）；④ 键位自定义是否进设置面待裁。排期 Beta（2026-10-04 登记；可行性已核毕，立项时按 roadmap 开卡）。 + +**缺口**：还差 Beta 立项时的输入方案设计讨论——四个连带裁决点（光标反馈承载/键位映射/弹层焦点导航范围/键位自定义）先裁再开卡。 +- 相关文档：[排雷玩法](design/gdd/systems/排雷循环/排雷玩法.md)（动作语义与 8 向目标规则主责）+ [HUD 框架](design/gdd/systems/表现与支撑/HUD框架.md)（键盘光标与合法性反馈呈现）+ [设置与本地化](design/gdd/systems/表现与支撑/设置与本地化.md)（键位自定义，可选面） + +**改动面**：文档 + +**状态**：待文档设计 + +#### 技能池情境条件触发器（2026-10-18 登记，来源=会话提及） + +**实况**：低血触发防御、玩家停手时的偷袭技等情境出招——载体＝技能行触发条件字段（P1 字段位已预留）；启用是敌人系统修订，不是调参。（原条目无登记日期，按本批格式整改补登 2026-10-18。） + +**缺口**：还差敌人系统修订的设计讨论——情境触发器的条件形态、字段语义与首批触发器清单。 +- 相关文档：[敌人系统](design/gdd/systems/战斗循环/敌人系统.md)（P1） + +**改动面**：文档 + +**状态**：待文档设计 + +#### 个体化变体池（2026-10-18 登记，来源=会话提及） + +**实况**：A 型好斗/ B 型守势、精英专属池（技能池共识点 A 的 A2 案）；现行同敌种同池模板，实例分歧只来自摇号涌现。（原条目无登记日期，按本批格式整改补登 2026-10-18。） + +**缺口**：还差敌人系统的变体池设计讨论——A2 案的池构成方案与精英专属池边界。 +- 相关文档：[敌人系统](design/gdd/systems/战斗循环/敌人系统.md)（P1） + +**改动面**：文档 + +**状态**：待文档设计 + +#### 全局特殊间隔旋钮（2026-10-18 登记，来源=会话提及） + +**实况**：异名特殊技背靠背现行概率低（是变化不是失控）；若实测仍嫌，备用闸＝全局「特殊技后至少隔 N 拍」——登记备用，未实测不启用。（原条目无登记日期，按本批格式整改补登 2026-10-18。） + +**缺口**：还差备用闸的条款设计（N 值与作用域）——仅当实测读数支持时才启动讨论。 +- 相关文档：[敌人系统](design/gdd/systems/战斗循环/敌人系统.md) 与[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md)（P1） + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 敌方技能图鉴 / 学习呈现（2026-10-18 登记，来源=会话提及） + +**实况**：池与权重不公开（D4/D5）口径下的进阶信息面——玩家侧技能知识系统（见过 → 认得 → 记谱）；首发三池学习成本低，后置（P2）。（原条目无登记日期，按本批格式整改补登 2026-10-18。） + +**缺口**：还差玩家侧技能知识系统的呈现设计讨论（HUD 承载形态与记谱口径），P2 后置面。 +- 相关文档：[HUD 框架](design/gdd/systems/表现与支撑/HUD框架.md) 与[敌人系统](design/gdd/systems/战斗循环/敌人系统.md)（P2） + +**改动面**：文档 + +**状态**：待文档设计 + +#### 削弱档位的最终数值（2026-09-18 登记，来源=会话提及） + +**实况**：削弱取值域 [60,85] 与投值 −65 来自旧体系裁决；"封印标中必须比随便挖一格更值"的当量终值由[战斗结算](design/gdd/systems/战斗循环/战斗结算.md)与[地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)共裁。**语义侧已定案（2026-09-18 盘问会话，结构修复批落地）**：削弱叠层改续时——同名重复授予只刷新剩余结算数、层数恒 1（结构性消饱和）；现行表值为临时值（provisional）。已入 M4 数值批卡 v1.2 件①（duration 终值投定＋当量锚复算落文；含 β 带 [1.2,2.5] 可行子区间推算、flag_hit_premium=125 纳入同窗检算、`clear_dominance_audit.py` WEAKEN_PCT 常量随投值同步）；2026-10-05 裁点已全裁并经同日联审二裁修订（P1甲/P2甲/P3甲/P4甲），跑批待 U0 用户发令、发起前须用户批准。 + +**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 + +**改动面**：文档＋游戏代码 + +**状态**：待文档设计 + +#### 单体寻址的接口扩展位（2026-10-18 登记，来源=会话提及） + +**实况**：对敌效果现行一律全体存活敌人共享一份层数；将来若要"只削弱其中一个"，需要给实例加目标寻址字段——扩展位已预留，首个单体效果上线时补列，并随之裁决归集与呈现语义。（原条目无登记日期，按本批格式整改补登 2026-10-18。） + +**缺口**：还差首个单体效果上线时的归集与呈现语义设计讨论与字段补列方案。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 空刷新的可见性（2026-10-18 登记，来源=会话提及） + +**实况**：刷新类策略在剩余次数已满时再授予是合法空操作（返回成功、无任何变化），与"溢出不静默吞"的诚实原则存在张力；MVP 无刷新类内容行，首批刷新行上线时顺带裁决。（原条目无登记日期，按本批格式整改补登 2026-10-18。） + +**缺口**：还差首批刷新行上线时的空刷新语义裁决（提示形态与诚实原则的平衡）。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 冒险前资源配比预设（构筑提案）（2026-09-18 登记，来源=会话提及） + +**实况**：构筑提案 2026-09-18 立项、八项裁决全裁（2026-10-04），设计闭合机制＝[元进度](design/gdd/systems/跨局循环/元进度.md)「冒险开始参数面与覆盖值通道」（零新机制）；2026-10-05 挂起——移出 roadmap 迭代 14，八项裁决与需求卡片冻结保留，重启须用户另行发令；全案与淘汰依据原载已退役提案（git 历史可考），裁决细节冻结在卡片。关联文档：[元进度](design/gdd/systems/跨局循环/元进度.md) v1.0（闭合凭据；现行 v1.21 已复核在役，2026-10-18 文档体检第 10 项）；需求卡片 reports/需求卡片-冒险前资源配比预设批-2026-10-04.md（文件头挂冻结横幅）。 +- 相关文档：[地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)修订批（基础配比的权重覆盖语义 + GDD 修订）与[元进度](design/gdd/systems/跨局循环/元进度.md)（解锁容量与注入生产者）共裁；呈现面归[HUD 框架](design/gdd/systems/表现与支撑/HUD框架.md)与[教学引导](design/gdd/systems/表现与支撑/教学引导.md)顺带。 + +**改动面**：文档 + +**状态**：文档设计已闭合＋已写卡（备选） + +#### GP 经济换算失衡——GP 袋面值与商店价格的换算关系复查（2026-10-07 登记，来源=审计发现） + +**实况**：道具三层审查的换算发现——小 GP 袋 20 ≈ 商店两三次首购（首购基价 4-5、A 链爬升前）≈ +2~4 点属性，而小攻击件只值 +1——「拿钱」在三选一面里经常比「拿数值」划算，且 GP 袋是池内最大户（23/98 张）进一步放大倾向。用户判「太离谱」。复查范围＝GP 袋面值（20/50）× 商店基价（4/4/4/5）× 价格曲线（A=1.8 / b=1.1）× 战斗 GP 掉落（普通 3 / 精英 5 / Boss 8，关级加值 0/1/2）四处联动；目标＝钱与属性件的换算效率回到设计意图（拿钱 vs 拿数值的取舍成立；GP 袋最大户地位要么有理由要么让位）。连带前提：L1 无商店节点使 GP 在第一关无消费口——「L1 商店编排」不另立条目、归本条复查范围（按 L1 是否补商店分两种情形各算一遍）。留待办清单待未来数值标定窗口（M4 数值批已废；2026-10-18 用户裁＝不另行归属、未设计未启动）。 + +**缺口**：还差四处联动的换算复查设计（含 L1 商店编排两种情形）——随未来数值标定窗口执行（M4 数值批已废，留待办清单未设计未启动）。 +- 相关文档：[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md)调参批（未来数值标定窗口）+ 奇物池结构顺带 + +**改动面**：文档＋游戏代码 + +**状态**：待文档设计 + +#### 迭代 10 奖励重构联动欠账（2026-10-01 登记，来源=批次移交） + +**实况**：迭代 10 奖励重构批（worktree 分支 m3-iter10-20261001）落地面产生三条后续义务——①钥石产出重标：渠道改「Boss/精英击杀掉落」（大奖励 keystone_per_level 退役、boss_keystone 重锚 provisional），现行元进度产出结构作废，标定义务重开；②通关率带重扫：通关回血 20%（血回满→部分回血，难度上压方向）+ 三选一件值/权重/次数上限 knob（AP 件＝每场战斗首轮 +1 AP 强度敏感轴）；③同调位读数源切换——**已清偿（2026-10-03 迭代 11 第①批 T7**：过渡键表/schema/断言三处退役，读取点归零，现行事实源＝Attunement.slots 谓词表实时求值）。①②已入 M4 数值批卡 v1.2 件③（F7/F8；通关率带重扫与 T6 四带复算并账、一次跑批双认账），跑批待 U0 用户发令、发起前须用户批准。 + +**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 调参批数值点评登记（2026-10-01 登记，来源=批次移交） + +**实况**：格面资源八型批后顺带登记的数值点评——① 增伤型奖励/惩罚幅度 50/25 不对称是否有意；② 削弱型 65/25 同问（且 percent 套个位数取整偏粗）；③ 回血奖励过薄（值 1、权重全池最低 2）；④ 警觉/行动点修正两新词数值全部 provisional；⑤ 行动经济"满停一轮＝一刷"节拍在 AP±1 修正下的对账——①-⑤五条已入 M4 数值批卡 v1.2 件②（F5，逐条裁决落文）；⑥ **格面资源正负兑付倍率差回调（2026-10-07 用户裁）**——2026-10-01「踩雷必须痛」抬档（heal +2/−6、pierce/magic +2/−8 等，负向 3-4 倍于正向）系错误的加难杠杆：难度提升应走怪物性能路线而非抬地图惩罚，回调归未来数值标定窗口（M4 数值批已废），标错/开雷同档同罚维持不动（同批裁）；⑥连同本条整体留待办清单未设计未启动（2026-10-18 用户裁）。里程碑立规（2026-10-09）：M4＝Beta 阶段、M3 未由用户明令关闭前不排期。 + +**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 +- 相关文档：[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md)难度曲线调参批 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 成长系数与关卡怪物难度提升的节奏（2026-10-16 登记，来源=playnote） + +**实况**：来源＝playnote 用户反馈「一开始不能让角色的成长系数太高。比如在没经过升级之前，你的成长系数是跟不上关卡怪物难度提升的；但是后续能力解锁之后，成长系数才能匹配得上」。语义两读：**读法甲＝节奏缺陷呈报**（前期成长跟不上怪物难度提升＝要修的数值节奏问题，归属难度曲线与Boss＋元进度解锁节奏的数值面）；**读法乙＝设计哲学陈述**（前期成长刻意克制、后期靠能力解锁追平＝既定设计，应反哺难度曲线的设计语义）。2026-10-16 用户定性＝数值校准类、与数值欠账同类任务，甲/乙两读随定性消解（无论现行节奏好坏，调它都是数值校准面的事）；不进 [08-Alpha版本标准](design/gdd/08-Alpha版本标准.md)（数值调优义务 2026-10-16 v1.6 起不入版本标准）；按里程碑立规属 Beta 阶段面，Alpha 不排期；留待办清单数值欠账组，未设计未启动（2026-10-18 用户裁＝不另行归属）。 + +**缺口**：还差并入数值欠账组的归属落位（Beta 阶段数值校准窗口处理）。 +- 相关文档：[难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md) + [元进度](design/gdd/systems/跨局循环/元进度.md)（成长系数语义面） + +**改动面**：文档 + +**状态**：待文档设计 + +#### 「封锁-蓄力」combo 设计素材（2026-10-07 登记，来源=会话提及） + +**实况**：用户想法（暂不立件，素材登记）——两件套：件一＝抬高刷新雷图代价（储备池 RAP 成本飙高）+ 刷新时解锁所有格子（全板开）；件二＝本回合留着 AP 没有刷新 → 获得减伤。联动＝抬价逼留 AP、留 AP 给减伤、憋够一发全板解锁。我方补充登记五点：①形态骨架＝「封锁-蓄力」combo 结构（抬高某动作代价封路 + 不做给补偿 + 憋到后的爆发）；②件一＝风险契约句式的扫雷侧版——碰撞点待裁：刷新开全板与清图判定/清图奖励/连锁展开的关系（算不算清图、发不发清图奖励）；③件二词表可承载（on round_end when 本轮未刷新且余 AP≥X → 减伤/护盾），「本轮未刷新」事实＝扩签候选；④归层按判定尺逐件裁（两件偏机制改写→专长域；但「刷新代价」是扫雷侧经济参数→秘宝域亦可）；⑤防躺赢注记：憋的收益须小于正常挖格期望（否则最优解＝永远不挖，玩法塌缩）。 + +**缺口**：还差立项裁决（暂不立件）——若立项，先裁碰撞点与归层，再走机制设计讨论。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 袋装摇号（格面资源池结构备选——保底型增多后的重构方向）（2026-10-07 登记，来源=会话提及） + +**实况**：地图战斗资源池保底结构（四档概率 + 按型保底 + 档位保底上限，现行事实源＝[地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)候选集合节）以「摇完整板校验补签」的补丁式实现起步——简单够用。备选正规形态＝**袋装摇号**：装板时按各档配额数好牌再洗开发放，保底天然成立、分布精确；代价＝摇号结构重写 + 偏运硬币/board_skew 两路权重投影须改为袋面投影。启用条件＝保底登记型增多、补签逻辑复杂化时。来源＝2026-10-07 地图层题四讨论，用户裁「先挂在待办清单」。 + +**缺口**：还差启用条件触发后的摇号结构重写设计讨论（含两路权重投影改袋面投影的方案）。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 战斗节点地图类型差异化——更多地图主题（2026-10-13 登记，来源=playnote） + +**实况**：来源＝playnote 用户试玩记录「修改地图的奖励类型：战斗节点增加不同的地图类型，比如有些图踩雷受到更多的伤害，有些图标雷可以造成更多的伤害，有些图伤害会减半需要凑更多清图奖励（这些都是暂时的设定）」。**已实装的部分**：首发形态整图变异「贫矿脉」已于 2026-10-16 用户令屏蔽删行（Boss 图回落 region 变异，原体验验证清单⑪ 目检项随之转记失效）——本条剩余面不变：在此之上再做**更多地图主题**（踩雷伤害更高/标雷伤害更高/伤害减半需凑更多清图奖励）。**2026-10-13 用户裁定：排 Beta 版本，Alpha 不做**——已移入 [08-Alpha版本标准](design/gdd/08-Alpha版本标准.md)「六 · Alpha 不含」节。 + +**缺口**：还差 Beta 立项时的地图主题设计讨论——按本条原始想法重新评估（用户标注「这些都是暂时的设定」，到时需重订而非照抄）。 +- 相关文档：[棋盘生成](design/gdd/systems/排雷循环/棋盘生成.md)（board_biome 图主题词表）+ [地图战斗资源](design/gdd/systems/战斗循环/地图战斗资源.md)（图主题差异化插槽）+ [地形变异](design/gdd/systems/排雷循环/地形变异.md)（整图变异承载面） + +**改动面**：文档 + +**状态**：待文档设计 + +#### 基线通关率越带，加难杠杆扫描未执行（2026-09-18 登记，来源=审计发现） + +**实况**：原登记＝现行扫描读数 60% 越 [30%, 50%] 上界；其后目标带两度换代（2026-09-17 带 [10,25]；2026-09-20 重投基线批后分带修正为 L1 [35,55] / L2 [25,45]，旧带失锚作废）——**新带下普通档双关落带、完美档 56%/40% 亦落带，加难紧迫性解除**。C1 终态已落表（2026-09-29 返工批：占比回退 5+plb 0+岩浆 1；U2 裁断 b 项推翻 C3 四件组合裁 **C1 两刀**〔岩浆 effect_value 2→1+逐层变异基数 2→0；变异占比维持 5%、卓尔血维持 130〕，a 项甲＝新杠杆授权〔完美 L1 89% 挂账废止，归难度曲线与Boss.md 带换代节承接〕；U2 裁断全录见 git 提交 f9c1a8a）。剩余面＝调参批的行值 provisional→正式扫描义务（门＝真人批 k 系数）；新增调参杠杆位＝变异 effect_value（荆棘丛 1 / 岩浆 2）与 percent_of_cells（5%）/ per_level_bonus（+2/关），扫描时与既有三类杠杆（血量锚走廊 r_boss [1.1, 1.35]〔2026-09-17 注：数值压缩批后 Boss 生命已 ÷3 缩水，180–207 为压缩前基线锚，复算随调参批〕、群战上探、注入衰减 0.5 → 0.6）合并比较；落带前全部现行行值维持 provisional-pending-scan。 + +**缺口**：还差真人批 k 系数到账后的加难紧迫性重判，再定正式扫描与杠杆标定设计。 +- 相关文档：难度曲线与Boss调参批，扫描执行与[棋盘生成](design/gdd/systems/排雷循环/棋盘生成.md)工具交付联动 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 三方向各自的解锁清单与定价（2026-09-21 登记，来源=审计发现） + +**实况**：三方向（属性、遭遇、道具池）各自的解锁清单与定价：多少钥石换什么，各自怎么铺。来源＝元进度 待设计问题清单第 2 条。部分完成（2026-09-21 元进度实现批再收窄；2026-09-23 换算率标定批再收窄）——**三柜台结构与 provisional 定价已落地**（属性锻造三档血+3/攻+1/甲+1、Boss 两档、工坊六件阈值 1/1/2/2/3/3 按总通关次数——全部读 `data/tables/meta.tres`）；换算率三行已投值 6/9/1（冒险条件口径实测，护甲行强条目重测履行）。剩余面＝定价数字与 Boss 两档终值——已入 M4 数值批卡 v1.2 件④（F11/F12；含待办清单死文本两句全刷义务：「base 10 公比 150」滞后〔meta.tres 现行 forge base_price=20，2026-09-22 数值设计批对齿〕与「Boss 两档 L1 5/1·L2 8/2·L3 12/3」死数字句〔现值首杀 3/3/3 · 复杀 2/2/3〕，T4 判据按两句全刷执行）。 + +**缺口**：M4 数值批卡片已随 2026-10-16 删卡令退役；2026-10-18 用户裁＝本条留待办清单、未设计未启动、不另行归属，未来数值标定窗口重开时重走设计段再写卡。 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 第二 / 三关棋盘观感——亮度与对比度（2026-10-13 登记，来源=playnote） + +**实况**：来源＝playnote 用户试玩记录「UI 优化，第二第三关的棋盘看着太累了；不知道是因为亮度还是对比度的原因，看着非常费劲，非常不舒服」。2026-10-13 用户裁定：**这是需要做的**，且本就属版本标准的覆盖范围——[08-Alpha版本标准](design/gdd/08-Alpha版本标准.md)「五 · 表现」已新增「棋盘观感（第二 / 三关亮度与对比度）」行，标待做。**开工前须先定性（沿用既有裁决）**：是**素材轴**问题（棋盘瓦片与格面图标本身的明度与色相），还是 **UI 轴**问题（舞台底色与叠加层的对比关系）——两轴修法完全不同，定性错了等于白改一轮；该定性要求（原备忘 (e) 项）是本条的开工前置。2026-10-16 曾编入迭代 30 卡③（UI 呈现三卡批序位③），2026-10-17 用户裁定剔除回待设计（自身挂「素材轴/UI 轴」定性人闸＋甲/乙〔recolor/远程生图重产〕素材裁点；若裁乙，其瓦片规格依赖战斗一屏样张批的目标规格清单产出）。v1.4 旧卡留 reports/需求卡片-二三关棋盘观感批-2026-10-16.md 作素材，非已写卡状态。与已完成注销的「呈现层残余 <4.5:1 文字位」分工：本条管**棋盘区域整体的观感**（亮度/对比度/费劲感，体感问题），彼条管**具体文字位的对比度读数**（机检可判硬指标），两条不同面不互相替代。Alpha 出口裁决：Alpha 必须，先做素材轴／UI 轴对照定性；出口＝用户实机目检不再判「看着费劲」。 + +**缺口**：还差「素材轴 / UI 轴」定性设计讨论与甲/乙素材裁点裁决；素材轴若走重产，还依赖战斗一屏样张批的目标规格清单产出。旧卡 v1.4（reports/需求卡片-二三关棋盘观感批-2026-10-16.md）在册但非已写卡状态，其前置未完成三件：①「素材轴 / UI 轴」定性未做，这是既有条款规定的开工前置；②甲（recolor 现瓦片）／乙（远程生图重产）素材裁点未裁；③若裁乙，瓦片规格压在样张批的目标规格清单上，而那份清单的前置正是上一条未完成的样张设计轮——本条第三项压在卡②身上。 +- 相关文档：[HUD框架](design/gdd/systems/表现与支撑/HUD框架.md)（UI 轴：舞台底与叠加层）+ [美术圣经](design/art/art-bible.md)（素材轴：瓦片与格面图标的明度色相）——定性前两方共裁 + +**改动面**：美术素材＋游戏代码 + +**状态**：待文档设计＋待美术设计 + +#### 棋盘格边长三方取值不一致——待扩板定档处置（2026-10-06 登记，来源=批次移交） + +**实况**：迭代 16「UI 设计对齐批」P2 已裁「棋盘格边长零改动」（本次不动棋盘游戏画面），由此三方取值不一致作为**已知偏差**登记：①代码＝`board_view.gd:251` 动态公式 `clampi(cell, 26, 46)` + `:114` 默认 46.0；②art-bible §8.1(:433) 冻结锚点＝45px（10×10）/ 36px（12×12）；③demo 原型＝44px（`src/ui-prototype.html:288`）；另有 HUD框架:72 装板校验区间 [30,45]。**当前未被任何断言触发**（属潜在不一致，不是缺陷）。按需求卡片契约 R7「禁单侧改完留漂移」，本批**代码与文档均不改**；处置时机＝扩板（13×13/14×14）定档时随格边长专项一并处理（§8.1 亦注明扩板换算值未定稿）。来源＝UI对齐批需求卡片（已退役，git 历史可查）§2.1「已知偏差」行。 + +**缺口**：还差扩板定档时的格边长专项裁决（三方取值归一＋§8.1 扩板换算值定稿）。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +#### 资产升档重产批（art-bible v3.0 中修挂账③，2026-09-29 登记，来源=批次移交） + +**实况**：v3.0 §8.2 档位上调方向候选（主角立绘 48×72→64×96 档、敌立绘三档上调评估）**已实质完成**——2026-10-06 art-bible v3.7 八敌逐键定档（源档 36–94、显示 ×2 整数；派生管线＝pixel-1 紧裁→等比缩至档高→dom_block_resize）取代 64/96/128 升档路线；存在感问题改经方案二（B 区 270 / 立绘显示上限 188 / 血条状态落底排）解决，不再走升档路线。裁决史：2026-09-30 迭代 9 三裁决案乙（本迭代不升档，先收 Alpha 真人读数再定；A4 尺寸基线冻结〔立绘 46×48/小人源 32×32〕维持有效）；2026-10-04 用户令暂不做、先忽略；2026-10-06 用户令优先级再降（维持挂起；同日 playnote 立绘批评已由「立绘逐键定档批」承接兑现）。**剩余挂起项＝提灯点亮解禁候选**（character-design 提灯，v3.0 明度分层允许空间光照），重启＝用户点名或 M-4 升档批。Alpha 出口裁决：不进 Alpha，排 Beta；提灯候选随 Beta 资产批重议。 + +**缺口**：还差提灯点亮解禁候选的重议设计（升档批或用户点名触发时一并裁）。 +- 相关文档：[art-bible](design/art/art-bible.md) §8.2 · 资产管线批 + +**改动面**：美术素材 + +**状态**：待美术设计（备选） + +#### 立绘清晰度回退评估——是否改用高清图（2026-10-13 登记，来源=playnote） + +**实况**：来源＝playnote 用户试玩记录「现在的立绘太丑了，像素化的粒度太低了，导致根本看不清立绘；看是否可以改回用较为高清的图片？还有一个问题是大小的问题……现在地精的图片看起来比熊地精还要大，这并不合理」。2026-10-13 用户裁定：与「第二 / 三关棋盘观感」同属**美术线更新**。**两个子问题现状不同**：子问题一＝怪物大小比例不合理——**已兑现**（体量语义改生物体型〔character-design §5.2，弃强度线性映射〕＋八敌逐键定档〔art-bible §8.2〕），剩余面＝用户是否复核验收；子问题二＝像素粒度过低/是否改回高清图——**方向已裁（2026-10-14 用户裁）**：「还是像素风格立绘，但是不需要像现在太过于像素」，定性为**精细手绘像素**（不是插画、不是 HD-2D、不回退高清图；裁决录＝[美术审计-cursor会话存档](reports/美术审计-cursor会话存档-2026-10-14.md) §2.2；权威面 art-bible/character-design 口径节反哺另批），粒度问题已改派生管线（八敌源档 36–94 全过可读门槛：24 糊/32 可读/48 清楚）。[08-Alpha版本标准](design/gdd/08-Alpha版本标准.md) 未决项已随裁删除（2026-10-16 状态刷新批）。Alpha 出口裁决：Alpha 范围＝主角＋三个 Boss 按新口径重产，其余敌种当前可读则保留到 Beta。 + +**缺口**：还差立绘按「精细手绘像素」新口径重产的设计——整屏方向稿与地面/立绘密度同批锁（与战斗一屏样张批联动）后才可出重产工单。 +- 相关文档：[角色设计](design/art/character-design.md)（立绘规格与体量语义）+ [美术圣经](design/art/art-bible.md)（像素管线与档位） + +**改动面**：美术素材 + +**状态**：待美术设计 + +#### 站桩帧动画——Alpha 定版闸前完成（2026-10-06 登记，来源=审计发现） + +**实况**：审计报告 P0-3——定稿立绘零帧动画；现行动画全部程序化（死亡碎裂/受击闪白/意图徽标弹入＝程序 tween，非帧资产）。用户裁定**动画是较往后的优化，Alpha 版本定版时间点之前完成即可**——当前 Alpha 开发期达成「看上去可游玩」即可。路线未拍板，审计报告三路线供重启时裁决：①**拆件驱动**（报告推荐：定稿立绘切部件〔头/躯干/臂/腿/武器〕+ 节点层级 tween 驱动——零身份漂移、帧数无限、内存小；项目已有先例＝shovel_swing 三帧 + 程序化死亡碎裂）②AI 关键姿势 + 人工修 + 程序补帧 ③全 AI 逐帧（不推荐：身份漂移/像素抖动）。前置依赖＝「立绘→派生形态」管线（等比整数缩放 + 降色 ≤32 + 脚底基线对齐 + 命名合规）——该管线同时是棋盘小人重出与八敌档位重算的前提。Alpha 出口裁决：列入 Alpha 定版前置清单——定版前完成最小版，路线预选拆件驱动；未完成则顺延 Beta，不占功能迭代。 + +**缺口**：还差 Alpha 定版批的路线正式拍板（预选拆件驱动）——拍板后立帧数规格与资产工单。 +- 相关文档：[art-bible](design/art/art-bible.md) §8.4 帧数规格 · 战斗表现批 + +**改动面**：美术素材 + +**状态**：待美术设计 + +#### 主角描边素材侧复核（2026-10-06 登记，来源=会话提及） + +**实况**：待决项 B 已按用户拍板走**文档例外条款**（character-design.md §5.1 v1.9：主角四态硬描边＝深褐 `(40,19,13)` 显式例外，浅砖面对比更高；**素材不顺带修改**）。本条仅为复核钩子：样张批（圣经 §1.4）终审时若发现深描边例外不成立（对比优势不实/与敌方同屏割裂感可感），素材侧修订（描边统一暖白族）**须先经本条重启**再开工，禁止直接动图。 + +**缺口**：还差样张批终审触发的深描边例外复核——复核成立即注销，不成立则重启素材修订设计。 +- 相关文档：[character-design](design/art/character-design.md) §5.1 · 样张批 + +**改动面**：美术素材 + +**状态**：待美术设计（备选） + +#### 在途草稿整理批——3349 个失管草稿（2026-10-06 登记，来源=审计发现） + +**实况**：审计 P2-1——`artwork/ui-reuse-2026-09-23/` 独占 3043 个草稿（91%），vN 命名率 0%，冗余 41 文件，残留非素材文件（.url ×8 / .ogg ×6 / .ai ×2 / .swf ×1）；根因＝脚本链覆盖「生成→验证」但**缺「草稿整理」段**。整理涉及**批量文件移动/删除**，按用户惯例须先 dry-run 呈报清单、经确认再分批执行。执行窗口随实现批；开工＝用户点名。 +- 相关文档：[art-bible](design/art/art-bible.md) §8.3 归档纪律（原则已写入）· 资产管线批（工具+文件操作） + +**改动面**：美术素材＋工具代码 + +**状态**：待写卡 + +#### 圣经口号型条款机检化批（2026-10-06 登记，来源=审计发现） + +**实况**：审计 P2-4——圣经约 55% 条款属口号型（如「暖倾向无压抑」「同一圆角率」无值），与可机检条款混排。目标＝逐条审查标注「可机检/目检/口号」三档分行，口号型逐步改写为带值或带判据条款。工程量＝全文级（541 行逐条），非一轮能毕。**2026-10-06 三档标注格式已拍板**（←机检/←目检/←方向性，规范见 art-bible 头注「条款验收标注纪律」；数值类推荐「待定现用」态）——本批执行＝按此格式分章补标，每章交付用户抽验。挂账：随整屏样张闸前整备批启动，分章推进。 + +**缺口**：还差整屏样张闸前整备批的启动——格式已定，差启动时点与分章执行。 +- 相关文档：[art-bible](design/art/art-bible.md) 全文 · 样张批前置整备 + +**改动面**：文档＋工具代码 + +**状态**：待文档设计（备选） + +#### 战斗区背景图替换——B 区舞台插画 + 临时光柱退役（2026-10-07 登记，来源=会话提及） + +**实况**：B 区舞台现行＝程序化平色底（`UiKit.STAGE_BG`，`battle_stage_view.gd:47`）+ **顶光柱氛围层**（`:55-63` 四柱，x 基准 110/900/1055/1210@1280，60 段叠层矩形自顶向下渐宽窄渐隐〔顶 α26→0〕，层序＝bg < 光柱 < 世界）——二者均系 §6.1 方向稿的**临时占位**，用户口径「光柱只是临时方案，换正式战斗背景后效果更好」。正式件已立资产契约：`stage/stage_bg.png`（源 1280×270，B 区全高含明细带底；三关换挡走 §4.3 `wall_ambient` tint 槽，不按板出三张），属审计 P1-2 查得的「B 区舞台背景插画 0 张」缺口。**光柱在背景到位后顺带退役或吸收进背景绘制**（不再作为独立程序层）。**与立绘探顶解耦**：大体档「允许向上溢出盒顶 N px」的判定（2026-10-07 用户裁甲案）**不依赖光柱是否存在**，换背景零返工。 + +**缺口**：还差出图前置条件的达成——立绘定档与站桩重排实装批的 **C0 盒高账定案后再出图**（避免 B 区高度/构图二次返工）；开工＝用户点名。 +- 相关文档：[art-bible](design/art/art-bible.md) §6.1（资产契约）+ §8.3 归档纪律 · 资产管线批；出图工单归 [art-assets-checklist](design/art/art-assets-checklist.md) / 实装批任务书 + +**改动面**：美术素材＋游戏代码 + +**状态**：待美术设计 + +### 教学引导 + +> **节头注记（2026-10-04 用户拍板）**：教学引导定稿批整体改排 **Beta 阶段**——当前 Alpha 版不做教学相关工作，本节五条全部随之改排（2026-09-19 的 Alpha 排期拍板被本拍板取代）。同日五问讨论已形成初裁与设计提案，提案已归档 `archive/` 目录（磁盘留存、不入 git，Beta 批立项底稿，引用以其「归档状态与初裁记录」节为准）。初裁摘要：①教学形态＝丙1 混合（首次冒险编排式首遇提示〔挂 first_script 锚、不锁操作〕+其余全程情景触发）；②「因果教学顺序」问题**注销**——只教扫雷操作，结算读法不设教学（用户裁：结算只是表达、展现、演出，无策略内容；展示层每行带来源标注已自带归因；教学引导.md 旧前提〔设计目的句/P0 候选归因提示/验收第 2 条〕随 Beta 批文档定稿清除）；③图例面板按循环段落分组、无结算段；④不做「再教一次」——改走独立「帮助」手册面（全部内容放一个文档）；⑤教学文案内容权归设置与本地化（两文档负责表对齐随 Beta 批）。**未裁三疑点**（Beta 立项时先裁）：增益叠层节奏条目去留／帮助入口位置（设置面为推荐）／图例面板与帮助手册的内容分工。 + +#### 教学形态未定（2026-10-04 登记，来源=审计发现） + +**实况**：教学的具体形态未定：线性开局教程，还是全部走情景触发式提示？来源＝待设计问题清单第 1 条。2026-10-04 用户拍板本节整体改排 Beta（Alpha 不做教学）；同日五问讨论初裁＝丙1 混合（见本节头注记），定稿归 Beta 批。 + +**缺口**：还差 Beta 立项后的教学形态定稿讨论（初裁丙1 混合待定稿，见本节头注记）。 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 因果教学顺序（2026-10-04 登记，来源=审计发现） + +**实况**：因果教学顺序未定：先教扫雷操作，还是先教读结算明细？两者如何衔接？来源＝待设计问题清单第 2 条。2026-10-04 五问讨论初裁＝**该问题注销**——只教扫雷操作，结算读法不设教学（用户裁：结算只是表达、展现、演出，无策略内容）；教学引导.md 旧前提随 Beta 批文档定稿清除。 + +**缺口**：还差 Beta 批文档定稿时对初裁结论的写入文档清算（教学引导.md 旧前提清除）。 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 图例面板的条目全集与分组方式（2026-10-04 登记，来源=审计发现） + +**实况**：图例面板的条目全集与分组方式待定。来源＝待设计问题清单第 3 条。2026-10-04 五问讨论初裁＝图例面板按循环段落分组、无结算段（见本节头注记）；图例面板与帮助手册的内容分工属未裁三疑点之一（Beta 立项时先裁）。 + +**缺口**：还差 Beta 立项后的图例面板定稿讨论（分组初裁待定稿＋与帮助手册内容分工裁决）。 + +**改动面**：文档 + +**状态**：待文档设计 + +#### 教学文案定稿权与本地化流程的分工（2026-10-04 登记，来源=审计发现） + +**实况**：教学文案的定稿权归属，以及与本地化流程的分工——两边共担，裁决时须对齐（设置与本地化原登记「文案定稿权与翻译流程的分工」；教学引导「待设计问题清单」第 4 条同事项，合并于此）。来源＝待设计问题清单 + 设置与本地化原登记。2026-10-04 五问讨论初裁＝教学文案内容权归设置与本地化，两文档负责表对齐随 Beta 批（见本节头注记）。 + +**缺口**：还差 Beta 批的两文档负责表对齐定稿。 +- 相关文档：教学引导与[设置与本地化](design/gdd/systems/表现与支撑/设置与本地化.md)共裁 + +**改动面**：文档 + +**状态**：待文档设计 + +#### "再教一次"入口与图例面板兼任手册（2026-10-04 登记，来源=审计发现） + +**实况**：是否提供"再教一次"的入口（图例面板是否兼任手册）待定。来源＝待设计问题清单第 5 条。2026-10-04 五问讨论初裁＝不做「再教一次」，改走独立「帮助」手册面（全部内容放一个文档；见本节头注记）；帮助入口位置属未裁三疑点之一（设置面为推荐，Beta 立项时先裁）。 + +**缺口**：还差 Beta 立项后的帮助手册面定稿讨论（初裁待定稿＋帮助入口位置裁决）。 + +**改动面**：文档 + +**状态**：待文档设计 + +### 生涯（跨局汇总与历史回看承接面） + +#### 「生涯」界面——冒险中数据回看的唯一承接处（2026-10-04 登记，来源=会话提及） + +**实况**：2026-10-04 用户裁决（UI 落码计划 P-C7）——冒险中不给数据回看：settlement_review_overlay（结算明细回看）与结算框「明细回看」钮在冒险中退役，战报带只留单行「上轮」；历史战报/结算明细的查看去向＝新「生涯」界面（跨局汇总/历史冒险回看/图鉴承接）。来源＝UI 重设计原型 v2 落码计划裁决记录（已退役，git 历史可查 §七）。**设计提纲已成文**：[systems/跨局循环/生涯.md](design/gdd/systems/跨局循环/生涯.md) v0.1 范围草案五节成文〔信息架构/承载内容清单/与既有界面关系/分期实装建议/待裁点〕，P0-P5 六裁点已全裁并写入文档〔P0甲 提纲落现行事实源 / P1甲 主菜单一级入口 / P2甲 每局一行摘要+cap 扩容 N+补用时埋点 / P3甲 敌人图鉴优先 / P4甲 局内不放入口+生涯零跳转 / P5甲 settlement_review 复活承接〕。**期一已落地**（2026-10-07 迭代 18 卡④实装批：生涯页六类九项+主菜单入口+终身计数域存档 v6，批末全量域闸全绿；实机人闸＝体验验证清单⑲ 生涯页目检节）。剩余面＝期二（历史回看/图鉴）与期三实装＋P6 营地最近冒险条带去留（新发现待裁点，随提纲评审一并裁）。**迭代 19 卡②遗留件（2026-10-08 登记）**：settlement_review_overlay.gd 现态考证＝未接线遗留件（全仓零引用，M9 结算框改版「明细回看」钮退役后遗留）——处置两途：①随生涯实装批按 P5 甲复活承接（重接线入生涯）；②确认不再需要则正式退役删除文件；二选一归生涯实装批/用户裁。Alpha 出口裁决：期二、期三全部排 Beta——Alpha 只保留期一，不在 Alpha 内做生涯新内容。 + +**缺口**：还差提纲用户评审收尾与 P6 营地最近冒险条带去留裁决——裁完才能立期二/期三实装卡（期一已交付，期二/三未预占排期）。本条排 Beta，不阻塞 Alpha；重启时再补 P6 与 N 终值。 + +**改动面**：文档 + +**状态**：待文档设计（备选） + +### GP 经济 + +#### 商店独立刷新机制——两参数待调参 + 机制文档回写（2026-10-04 登记，来源=会话提及） + +**实况**：2026-10-04 用户裁决（P-C2+Q2 二次裁）推翻关卡节点地图 v1.5「无独立刷新、重抽绑购买」口径，定案＝**基础免费 0 次 + GP 刷新（ceil(20×1.8^已付费刷) provisional）+ 池源同源（共享池，与三选一同一账本）**；**天赋/营地侧「刷新次数」增益＝用户既有意向（口头裁决，曾因未写入文档丢失——Q2 追认），后续由用户调整添加，实现面预留 free_count=天赋增益位**。未定：天赋增益的具体形态与数值。**机制已落码**（SR-1 随 UI 落码批收官，2026-10-04/05）；**三选一同款付费刷新已落码**（2026-10-06 用户令——「三选一对齐商店，得有刷新」：免费双源〔刷新件 X/冒险池 Y〕用尽后 GP 付费刷新，同旋钮同曲线同钱包；机制登记归[秘宝](design/gdd/systems/跨局循环/秘宝.md)「三选一刷新双源」节）。剩余待办：①调参（shop_refresh_free/曲线两参数 provisional，归未来数值标定窗口顺带——M4 数值批已废）；②天赋增益形态与数值（设计未定）；③机制文档回写核对（冒险结构共享池账本节/关卡节点地图商店行 v1.6 已记，本条完成时核对三处同步）。 + +**缺口**：还差天赋增益形态与数值的设计讨论（用户调整时裁）与 M4 窗口的两参数标定；③回写核对随完成时点履行。 + +**改动面**：文档＋游戏代码 + +**状态**：待文档设计 + +### 文档与结构 + +#### qa/ 实现报告收尾·孤儿遗留七项余三项（2026-10-14 登记，来源=批次移交） + +**实况**：qa 收尾批核查 iter19 系列出口报告遗留移交项时发现**不在待办清单在册**的七项（acceptance-package §三.2/card0 §5.3/followup §七.3/uibackfill §6.2-4/verify §6.1/3/7）。已结案的（tree_rules 受理闭环、X/Y 双源、S1 七项违例修复、提灯目检项、tests.yml 休眠等）已在各报告标注结案证据，不入本条。2026-10-24 处置：第②③④项随迭代 36 卡C 落地销号（营地 STONE 深档六处、迷雾三关派生行、开场后缀条件加算区），第⑥项按用户 2026-10-24 裁整条注销（TG_* 装饰带非文字，不另立探针）。余三项均为挂号备查/顺路件，无排期承诺： + +1. **design/diagrams 越界**（熵增闸存量红，archify 架构图批 00712d5 旧债）：脚本自文「新分类先过用户拍板再改两处白名单」。修案二选一——甲＝用户拍板 `design/diagrams` 入 DESIGN_SUBDIRS 白名单（archify 总图批产物归位）；乙＝迁出 design/ 归位合法区。落点＝熵增闸白名单（AGENTS.md Project Layout+脚本白名单两处） +5. **字面量墨收测前置**（iter19 卡②遗留）：bcard 属性描述/类型脚注/✓章/primary_button 字四处内联 Color8 无常量形态，收测需先在 ui_kit 立常量（呈现批顺路件，改 ui_kit 越当批面）。落点＝呈现优化批（ui_kit 常量面） +7. **商店房截图纳屏**（iter19 卡①遗留）：商店房截图纳屏留后续呈现批（考证结论在 shot_probe 头注）。本项原并列的「`数据配置.md:223` 历史行死指」半句已于 2026-10-21 实查核销——禁写变更记录规约生效后该文件的版本史行整段已不存在（现全文 212 行，文内零版本史行），被指对象随之消亡。落点＝呈现批 + +**改动面**：游戏代码＋工具代码 + +**状态**：待写卡（备选） + +#### 奖励节点三选一实装（2026-10-25 登记，来源=批次移交） + +**实况**：局内奖励节点现为零兑付直通占位——`game/core/level_runner.gd:462-466` `"reward"` 分支注记「奖励点内容未定…节点保留占位、零兑付直通」，实跑选路直接跳过；L1 全部模板零商店节点（`game/data/tables/level.tres` L1 行＝20 battle/5 boss/5 rest/5 reward，零 shop），现行局内 bonus 唯一可达来源＝L2 商店货架。而规格已定：[node-reward](design/gdd/ux/node-reward.md) v2.8＝奖励节点从冒险牌库抽三选一（属性值提升与补给；与通关专长三选一同库分流），池与库存口径归[冒险结构](design/gdd/systems/冒险循环/冒险结构.md)「奖励节点三选一池」节（共享令牌库、消耗即上限）。连带影响：迭代 36 卡C 路径②原设计「奖励节点拿属性卡→下一关开场行带后缀」不可驱动，已改快照喂入形态通过；wa4 探针半（三选一停点弹层头部断言）保留为条件断言、**拦截能力未证**（test-conventions §6 口径），本条实装后须重跑该断言。 + +**改动面**：游戏代码 + +**状态**：待写卡 + +#### 闸与探针存量噪声两件——_round_rows 类型错与批上下文挂死（2026-10-25 登记，来源=批次移交） + +**实况**：证据＝迭代 36 批末闸机观测（非本批引入）。两件存量噪声：①`ui_click_probe` 与 `battle_log_view` 绿跑亦复现 `_round_rows`（Array[Dictionary]）append String 的运行期 TypedArray 错误——日志失真但断言仍绿；②`level_shop_economy_test` 在闸批量上下文存在挂死形态（直跑恒绿），`tools/probe_gate.sh` 的 per-suite timeout 只杀 wrapper 不杀引擎子进程，孤儿泄漏会殃及后续全部 Godot 启动（批末四次闸跑批中断的根源，处置＝清杀泄漏进程＋删重建 `game/.godot`）。两件均登记待后续测试基建批处置。 +- 相关文档：`game/presentation/views/battle_log_view.gd` 与 `game/probe/ui_click_probe.gd`（类型面）；`tools/probe_gate.sh`（进程树回收面）——测试基建 + +**改动面**：游戏代码＋工具代码 + +**状态**：待写卡（备选） + +#### 美术资产链路审计两项 P0 — 待用户裁决（2026-10-09 登记，来源=审计发现） + +**实况**：**P0①（文档面）**：`design/art/art-bible.md` 第 68/527 行与 art-status-checklist 第 13 行至今仍引用已丢失的冻结样张 sample-batch-v3-final-2026-09-30.png（磁盘实测零命中），死指涉待修复。**P0②（美术面）**：主角棋盘小人未走像素管线（插值糊图），重产事项未在任何登记处在册。审计报告 HTML 件从未进版本库、现已删除，两项 P0 的现状以本条正文为准。裁＝修复死指涉+登记重产，或判过期随旧管线退役。2026-10-13 用户令随「UI 美化三层诊断」登记：本条属第三层「观感提升」，Alpha 阶段需完成。 + +**缺口**：还差用户的路线裁决（修复死指涉＋登记重产，还是判过期随旧管线退役）——裁决后文档面修复与美术重产登记各按轨推进。 + +**改动面**：文档＋美术素材 + +**状态**：待文档设计＋待美术设计 + +#### 技术债观察登记——长函数余量与 lambda 连接防回归（2026-10-15 登记，来源=批次移交） + +**实况**：证据＝迭代 27 需求卡片两项「登记待办清单观察」义务批内漏登、卡片核对时补登——①**长函数 17 个**中非结算段的装配/校验函数（`level_map_screen.gd` 选路装配 155 行/`camp_overlay_view.gd` 152 行/`debug_overlay.gd` 114 行/`treasure_item_table.gd` schema 校验群等；`main._build_ui` 已随场景拆分自然解体、`_settle`/`_resolve_hero_attack` 已随波二拆段＝17 中 3 件已消解，余 14 件）；②**lambda 连接 76 处**（presentation 6/smoke 62/tests 8——实读无泄漏，登记防回归）。长函数拆分无独立需求驱动不动；lambda 连接数若有审计工具化需求归类型闸后续。 + +**改动面**：游戏代码 + +**状态**：待写卡（备选） + +#### 测试域遗留（2026-10-16 登记，来源=批次移交） + +**实况**：证据＝迭代 29 批内未收余量（交付报告与验收审计申报，报告已按吸收即死退役、git 历史可考）。迭代 29 把验收语义从「跑一遍没崩＝通过」扭到「三层完备＋判定可靠」，三硬闸（退出码／脚本错误扫描／断言数下限）已落地，L2/L3 从零建起承载。本批未收的余量集中登记在此，均不阻塞、不排期： + +| # | 事项 | 落点与要点 | +|---|---|---| +| 1 | **余下 3 个 core 模块仍零指名单测**：`board_data`／`reward_economy`／`skill_lottery` | 测试基建批。本批补了 minesweeper_rules／board_generator／config_db_resolver／config_db_cross_validator 四件；余三件按同一手法补（判据＝能否在 `--script` 模式不加载 autoload 验完） | +| 2 | **render_gate 的 SCRIPT ERROR 扫描仍缺失** | 测试基建批。判定主体是 golden 容差与取证文件存在性，脚本错误不改退出码时无扫描面；本批只把矩阵状态如实记为「缺失」，收它的写法待裁 | +| 3 | **静态扫描域 S7／S8 仍未落地** | 工程债批。S7＝B1 编排唯一性（B2/B3/B4 API 符号命中文件 ⊆ B1 文件集）；S8＝结算路径 `await` 零命中。本批补的是 S3 路径与 S5，S6 亦仍在 TODO | +| 4 | **E 级卫生件**（test_kit static var 串台风险、4 套件自建断言出口、157 处 untyped 容器、76 处 lambda） | 工程债批。本批只统一了**新写**断言的出口，存量未动；test_kit 的 static var 是「并发跑批」的前置障碍（并发分层方案的前提） | +| 5 | **行覆盖率度量缺失** | 基建评估项。Godot 无内建、第三方属新基建；现行补洞靠「零指名清单 + 人工判定」，是否引入度量待裁 | +| 6 | **`smoke_all.gd` 拆分**（单文件承载 1127 项检查） | 工程债批。本批按契约只做入闸与改名裁点，不拆不重构；拆分登记在册 | +| 7 | **parity 逐位一致比对的触面判定为粗粒度路径匹配** | 测试基建批。触面表含 `battle_orchestrator.gd`，改该文件即要求批准发起 MC；若嫌过重可精化到「是否改动取数/结算数值」的语义面 | + +**改动面**：游戏代码 + +**状态**：待写卡（备选） + +#### 营地交互重做·五张需求卡片（2026-10-18 登记，来源=会话提及） + +**实况**：2026-10-17~18 需求讨论澄清会话产出结论文档，用户令按工作内容维度拆卡、卡片不预占迭代号。五卡已写（顺序＝执行顺序）：①存档制数据层改造批 ②主菜单三入口化批 ③选档界面新建批 ④营地场景图新建批 ⑤Esc 浮窗与营地顶栏批（各卡估时与内容见卡片自身）。三道复核：grilling 子 Agent 对抗审查（五卡各一）→v1.1；用户裁定「事项按推荐的来」→v1.2；用户两次订正（**卡④留在批内不踢出**；前置归用户自立批，Agent 不代跑不代产——曾越权起草的点选反馈设计稿 v0.1 已撤回删除）→卡④ v2.2；**卡④ 2026-10-21 用户令退回美术设计段（v2.3，非有效卡，美术设计闭合后重立卡）**。①②③⑤ 零待裁点可编工程波次：②③ 硬耦合同波（「进入存档」钮落点＝选档界面），① 是 ③ 前置；⑤ 随 ④ 代码波同行。Alpha 出口裁决（2026-10-21 用户裁）：五卡整体列入 Alpha——08「三 · 界面」已开条目，Alpha 出口依赖五卡完工与卡④三个用户侧前置销号。**工程波次一已落地（2026-10-22）**：卡①②③ 随迭代 33 实现批合回 master（合并提交 ebf40947／5c2a7bcf／508f190b，总收口 6e8f72b2），三卡需求卡片与批次产出物已按「吸收即死」退役（设计口径已吸收进 存档序列化.md／生涯.md／camp.md／08-Alpha版本标准.md v1.13／art-bible.md v3.18，反哺落文凭据=文档批 git 提交 1864f157＋9f7b3e8a）；卡④（营地场景图）退回美术设计段待重立卡、卡⑤（Esc 浮窗）随卡④ 代码波同行，两卡未编排——编入哪一迭代由用户经迭代编排段发令。关联文档： +- 设计澄清定稿：reports/需求澄清-营地交互重做-2026-10-18.md（v1.0：目标体验原话／目标结构树＋纵深稿／10 条交互裁决／验收口径／切批原则／遗留待裁） +- 卡④：reports/需求卡片-营地场景图新建批-2026-10-18.md（v2.3，**2026-10-21 用户令退回美术设计段，非有效卡**，美术设计闭合后重立卡，见缺口） +- 卡⑤：reports/需求卡片-ESC浮窗与营地顶栏批-2026-10-18.md + +**缺口**：卡④（营地场景图）**已退回美术设计段**（2026-10-21 用户令）——美术线未闭合，按 req-card 第〇步不具写卡资格，现卡 v2.3 为非有效卡，五项前置销号后方可重立卡：P1 美术渠道（**2026-10-22 已裁＝B 插画级新产**，✦ 渠道作者自跑远程生图管线；规格沿用 art-bible §8.1/§8.2 既有裁决）；P2 像素规格（Q6 甲过渡口径已裁，执行归用户线）；P3 点选反馈设计稿（用户线，未受命开工；Agent 曾越权起草 v0.1，已按用户令撤回删除）；P4 参照物（用户后续找）；P5 GDD/art-bible 落文（定稿后用户发令）。销号完毕且美术定稿（样张过审＋art-bible 条款版本）后卡④方可进代码实现波次。 + +**改动面**：文档＋游戏代码＋美术素材 + +**状态**：文档设计已闭合＋待美术设计＋已写卡＋已写卡 + +#### 需求卡片入库纪律未登记——502 批遗留的悬空待办（2026-10-18 登记，来源=批次移交） + +**实况**：2026-10-16 迭代 29 编入批（提交 `21c83f5`）认定「需求卡片写进了 roadmap 却没在待办清单登记」属流程漏洞，需要补一条卡片入库纪律。该条至今在待办清单清单内查无（2026-10-17 与 2026-10-18 两次全文检索零命中）。唯一记过它的地方是根目录状态文件未决面第 31 行，该文件已于 2026-10-18 用户裁废除，故改记本条防遗忘。待裁：这条纪律要不要立；立则写进归属所指的 process-conventions。 +- 相关文档：design/engineering/process-conventions.md 五段流水线的登记段 + +**改动面**：文档 + +**状态**：待裁决 + +--- + +#### req-card 技能的 WorkBuddy 与 ZCode 两份副本内容不一致——取齐待裁（2026-10-18 登记，来源=批次移交） + +**实况**：用户级技能 req-card 在本机有两份副本，分别位于 WorkBuddy 与 ZCode 两个 harness 的用户目录 skills/req-card/SKILL.md（都在仓库之外，仓内没有任何登记处）。2026-10-18 逐字节比对：两份内容不同——迭代 28 那批只补了 ZCode 一份，WorkBuddy 那份没跟着改。这条欠账此前只记在根目录会话状态文件的未决面第 32 行，该文件已于 2026-10-18 用户裁废除，故改记本条。待裁：以哪一份为权威取齐，或两份各自演化。 + +**改动面**：工具代码 + +**状态**：待裁决 + +--- + +#### 「魔法道具」与「罕见」两个旧叫法的残留未扫——扫不扫待裁（2026-10-18 登记，来源=批次移交） + +**实况**：「魔法道具」随 2026-09-15 可选类道具删除而失效，「罕见」随 2026-09-14 分辨率档位批换装而失效，正文里仍有残留。2026-10-18 实数（全仓 markdown 检索）：魔法道具 23 处、罕见 17 处；此前根目录状态文件记的「约 30 处／约 18 处」系旧读数。两词都不在 `tools/doc_term_audit.py` 的退役词表里，机器闸抓不到，只能人工裁。待裁：扫或不扫；扫则把两词追加进 doc_term_audit 退役词表防再犯。 +- 相关文档：design/gdd/ 正文用语（权威对照=design/gdd/术语表.md） + +**改动面**：文档 + +**状态**：待裁决 + +--- + +#### 「通关」与「通过第 N 关」两种口径混用——统一与否待裁（2026-10-18 登记，来源=批次移交） + +**实况**：「通关」一词既被用来指「打完一整局冒险」，也被用来指「通过第 N 关」，2026-10-18 实测 design/gdd 内 188 处（此前状态文件记 273 处，口径是全仓）。歧义直接影响难度曲线读数与验收判据的表述——同一个「通关率」两种读法差一个数量级。待裁：是否定单一口径并逐处改写。 +- 相关文档：design/gdd/01-核心循环.md 与难度曲线、验收类文档的措辞口径 + +**改动面**：文档 + +**状态**：待裁决 + +--- + +#### 流程动词族黑话的第二波清扫待发令——GDD 正文约三千处（2026-10-18 登记，来源=批次移交） + +**实况**：2026-10-15 用语规范批只按 A 表替换了词面约 250 处（十二行），流程动词族——需要作者额外解释才看得懂的一类说法——在 GDD 正文仍有约三千处未处理。第二波至今未发令。待裁：第二波的范围与发令时点。 +- 相关文档：design/gdd 全树正文用语（权威词表=design/gdd/术语表.md 用语规范节） + +**改动面**：文档 + +**状态**：待裁决 + +--- + +#### 调试入口写死行必须在发布前删除——game/presentation/main.gd:196（2026-10-18 登记，来源=批次移交） + +**实况**：2026-10-16 用户令把调试入口改为恒开，`game/presentation/main.gd:196` 的 `_debug_entry` 现恒为 true、不再读环境变量（2026-10-18 实查该行仍为 `_debug_entry = true` 并带「发布前清」注释；:197 是最顶层浮层角标的可见性赋值）。发布前删掉 :196 这一行即可——角标可见性随门控失效自动隐藏，无第二处改动点。不删的后果：正式包里调试浮层与角标常显。证据=该行代码注释与 2026-10-16 调试入口批的实装记录。 + +**改动面**：游戏代码 + +**状态**：待写卡 + + +--- + +#### L3 屏壳切换探针的判定被仓库外存档状态污染，跑批绿红不可复现（2026-10-18 登记，来源=审计发现） + +**实况**：2026-10-18 卫生批跑全量档时 03 探针 --click 与 04 探针 --full 双双「基线绿→现红」，唯一失效单元是 `game/probe/screen_flow_probe.gd` 的第④步（菜单开新冒险进不去，⑤⑥⑦三条随之因前置不满足连带红）。根因已钉死且与本批及任何代码改动无关：`user://save.json`（主区与所有 worktree 共用同一份、不入 git）里现存一个 `breakpoint` 断点，而 `game/presentation/main.gd:476-482` 按「二轮修改批 A」的用户目检裁决，在 `save_manager.has_breakpoint()` 时弹实底确认框「已有未完冒险（第 N 关）——开新冒险将覆盖旧断点」并直接返回、不开冒险；探针第④步只用前缀匹配找「▶ 开始冒险」并按下、等 3 帧就断言进冒险屏，它隐含假设「存档里没有断点」。三条判据：主区那份未受本批影响的 master（`ea69670c`）单跑同一探针复现完全一样的 7 处；同一 worktree 同一代码把 save.json 临时移开再跑立刻 `PASS — 六步主流程＋回退路径全绿`（跑完存档逐字节还原，sha1 `dd67444c35be` 与移开前一致）；`game/**/*.gd` 自 10-17 那次绿回执 `7ffd1dc0` 之后零改动。断点来源＝上一轮 `ui_click_probe` 或任一会话跑到中途留下的未完冒险（存档账目已累积到 `adventure_total=6`、`level_clear_counts={1:18,2:7,3:4}`）。后果是验证闸的绿红取决于「这台机器上谁最后跑过」，正是 test-conventions §8「判定可靠性优先于覆盖率」所管的同一类缺陷。修复方向两条，均待写卡时定：探针侧自救（第④步前先走弃断点通道，或在确认框上按「开新冒险」再断言）＝改 `game/`；跑批侧隔离（给探针配独立 user 目录）＝改 `tools/probe_gate.sh`，⚠ 此路有一条未验障碍——本日用 `--user-dir` 指到空目录跑该探针，Godot 挂住零输出、超时未出结论，走这条要先查明成因。证据已指认，按 §12.1 属需求性工程条目，跳过设计线。 + +**改动面**：游戏代码＋工具代码 + +**状态**：待写卡 + + +--- + +#### 效果引擎「系统无状态」原则缺架构文档条目（2026-10-20 登记，来源=会话提及） + +**实况**：用户 2026-10-19 会话裁定的 ECS 架构依据（系统无状态——效果引擎这类系统零运行时可变状态、数据由宿主对象持有并随宿主生灭、状态按参数传入系统、系统只做判定）是「效果引擎无状态化」重构批的立项判据（上游＝迭代 31 卡② 移交的计数器寿命域判据线——该登记条目已在本条闭合时整条删除，判据现由 architecture.md v1.9 条 8 承载；提案=reports/提案-效果引擎无状态化-2026-10-19.md v1.3 §7.9 #1），但 `design/engineering/architecture/architecture.md`「架构原则」节（原 7 条）无「系统无状态」条目——立项判据暂无权威文档出处（2026-10-19 全仓检索「无状态／纯计算」零命中，提案 §10.3 实查；原 `design/registry/` 两 yaml 已随 2026-10-19 用户裁注销删除，无可迁凭据）。重构批是代码批、禁写 `design/`，文档级补条只能另立文档批。 + +**现状换代（2026-10-21 文档批写入完成）**：architecture.md「架构原则」节已补第 8 条「系统无状态」（条文序位=呈现层契约成文条之后，与条 1 核心层纯逻辑、条 5 fail-fast 交叉核过无冲突），effect_engine 模块行与战斗域装配节同步改写为 ctx 形态描述——design/engineering/architecture/architecture.md v1.9（2026-10-21 用户裁写入）。 + +**改动面**：文档 + +**状态**：文档设计已闭合 + +--- + +#### 结算明细日志行序重锚批（2026-10-21 登记，来源=批次移交） + +**实况**：迭代 32 卡① N7 改动互换 `seal_miss`／`insurance_used` 两行日志顺序并改写豁免态 highlight（豁免态＝insurance_used 行先行且 highlight 置空；未豁免态＝两行相对序不变但 `seal_miss` 发射时点后移——完整对照见 git 提交 d00f24a8 批内实现报告，报告已退役）；`playtest_logger._on_step_row` 逐行落盘含 highlight 字段，与基线数据逐项比对的 JSONL sha256 校验必红，实现批按规未发起、11 号闸落 skip。**用户 2026-10-21 裁＝批准另立重锚批，发起时点另定**（重锚批只能由用户发起）。 +- 相关文档：`sim-data/` 锚与 `tools/parity_anchor.py`（重锚执行归用户发令批） + +**改动面**：工具代码 + +**状态**：待裁决