DKChan
cb548776e0
代码修复（垂直切片，冒烟 193/193 · 三探针全绿）： - 遭遇流盐值修正（旧值超 int64 被截断，与 registry 黄金向量不符）+ 黄金向量断言入冒烟 - 完美排雷第二份按身份类型真实兑付；零兑付不发高光行；失败记"奖励未生效"行 - 轮内刷新图 provenance 守卫：刷新图清图不发清图奖励 - 可推理率求解器禁读雷位真值（no-peek）——L1/L2 实测 0.953/0.951、一次生成即达标 - 清图分类改传真实旗集（空旗集捷径会误判批次优先级） - 达标判定回归单一判据（可推理率 ≥ 及格线） - 等待期（Waiting）刷新通道整体拆除——非清图轮恒同图 顺手修：清图轮剩余 AP 当场清零 + 耗尽轮断言；degraded_product 降级标记；产物雷数 ≤N 断言； 明细流水"无来源即炸"及两层豁免成文；主角零值伤害行；窗口段三锚行（13→15 类行协议）； 图标键 fail-fast + 补齐暴走/失衡两键。 文档：可选类注入递减基准改"按实际获取件数"、首件保证改"必注入"口径（+未挖到不补发待办）； 教学位掷骰口径自洽；标错反噬三池收编（状态表四行→六行）；行协议 13→15 与豁免清单回写 《战斗结算》与 registry，下游引用同步收敛。 另含：全仓旧代号→语义命名清理（注释/标识符，81 文件）；CLAUDE.md 登记 Godot 路径与验证命令。
55 lines
6.1 KiB
Markdown
55 lines
6.1 KiB
Markdown
# Dungeon Sweeper（扫雷 × 自动战斗 闯关 Roguelike）
|
||
|
||
扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发，MVP 优先管线。
|
||
设计入口：`design/gdd/02-系统清单.md`（循环式新骨架根索引）· 概念：`design/gdd/00-游戏概念.md` · 旧版 GDD 归档（只读参考）：`design/archive/gdd-2026-09-14/`
|
||
|
||
## Technology Stack
|
||
|
||
- **Engine**: Godot 4.7.2
|
||
- **Godot 可执行文件（本机固定路径，2026-09-15 登记）**：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe`（headless / 命令行一律用 console 版；编辑器版为同目录 `Godot_v4.7.2-stable_win64.exe`）
|
||
- **Language**: GDScript
|
||
- **Build System**: SCons (engine), Godot Export Templates
|
||
- **Asset Pipeline**: Godot Import System + custom resource pipeline
|
||
|
||
## 运行与验证（垂直切片）
|
||
|
||
工作目录 = 切片目录本身（含 `project.godot` 的那一层）：
|
||
|
||
- 冒烟（全量 headless 断言）：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe --headless --path . --script res://smoke/smoke_all.gd`
|
||
- 场景级探针（呈现层回归）：`…console.exe --headless --path . res://smoke/ui_probe.tscn`；另有 `ui_tune_probe.tscn`（数值调整板）与 `ui_click_probe.tscn`（合成鼠标事件行为探针）
|
||
- 调参期批量工具：`--script res://smoke/level_monte_carlo.gd`（关卡期望扫描）· `--script res://smoke/reward_expectation.gd`（奖励获取期望）
|
||
- 交付前纪律：smoke + 全部场景探针全绿（见下方代码规范·测试条）
|
||
|
||
## Engine Version Reference
|
||
|
||
@docs/engine-reference/godot/VERSION.md
|
||
|
||
## Project Layout
|
||
|
||
- `design/gdd/` — 现行设计文档（2026-09-14 重建的循环式新骨架）：6 份顶层文档（`00-游戏概念` / `01-核心循环` / `02-系统清单`〔根索引〕 / `03-内容规模` / `04-美术音频方向` / `05-不做清单`）+ `systems/` 按四个循环组织子系统文档（排雷循环 / 战斗循环 / 冒险循环 / 表现与支撑），子系统一律中文见名知意命名、不带编号前缀；文档增删必须同步 `02-系统清单.md`
|
||
- `design/archive/gdd-2026-09-14/` — 旧版 GDD 体系归档（只读参考，不再维护，不作事实引用）
|
||
- `design/registry/entities.yaml` — 跨系统事实登记表（已锁数值；仅 owner 文档可修订，冲突须显式提出）
|
||
- `production/` — stage、session-state、gate-checks
|
||
- `prototypes/` — `dungeon-sweeper-vertical-slice/` 垂直切片（概念 demo 已删除，验证报告留档 `docs/prototype-report-minesweeper-battle-concept.md`）
|
||
- `docs/` — 代码规范（`code-conventions.md`）· **文档写作规范（`doc-conventions.md`，写文档前必读）** · 架构与 ADR（`architecture/`）· 引擎参考（`engine-reference/`）
|
||
|
||
## Conventions（评审确立，勿违反）
|
||
|
||
- **数值单一事实源**：全部玩法数值存 `data/tables/`（.tres），经 `ConfigDB` autoload 类型化单点读取；玩法代码禁止数值字面量与自建 `load()` 表路径（D2 Rule 1/2）
|
||
- **RNG 单点**：禁止 `randomize()`/自建 RandomNumberGenerator——随机只经 `RngService` 封闭命名流（D2 Rule 5）
|
||
- **Core 层零 UI 依赖**：完整战斗必须可 `godot --headless --script` 运行（D2 Rule 7）
|
||
- **fail-fast**：数据校验错误一律致命中止，无软回退（D2 Rule 6）
|
||
- **spec-AC 一致性**：规约与验收标准不得在同一输入上给出不同答案——D2 两轮评审确立的阻塞标准，所有 GDD 同尺度
|
||
- GDD 评审纪律：`/design-review` 必须在独立会话跑（与 `/design-system` 隔离）
|
||
- **文档写作规范（2026-09-14 成文，写任何文档前必读）**：在编写、修改任何设计文档之前，必须先通读 `docs/doc-conventions.md`（全文权威——整合原用语纪律〔2026-09-09〕、文档形态纪律〔2026-09-13〕、两件套与树形文档体系纪律〔2026-09-14〕、新骨架过渡口径〔2026-09-14〕，并新增可读性第一纪律）。要点：**可读性第一**——读者测试三问（管的是谁/什么？什么情况下？会发生什么？）答不出就重写该节；白话完整句、散文讲道理、表格放数据；禁自造黑话（唯一例外 = 玩家可见专属名词）；树形文档体系，文档增删必须同步根索引 `design/gdd/02-系统清单.md`；节点一页纸以内；每个子系统一份设计文档、不建 analysis 推演件；正文只写现行规则，修订只进文末「版本历史」表；跨文档引用纪律（单点定义 / 规范名唯一 / 引用不转述 / 反向边登记 / 删除概念 SOP）见该文第 7 节；已锁数值事实源 = `design/registry/entities.yaml` 与 `data/tables/`。旧体系 lean 格式与 `gdd_lint` 门禁仅用于解读归档（`design/archive/gdd-2026-09-14/`），不约束现行文档。
|
||
|
||
## 代码规范（写代码前必读，2026-09-11 用户拍板成文）
|
||
|
||
**在编写、修改任何代码之前，必须先通读 `docs/code-conventions.md`**——该文档由用户指出的真实陋习与缺陷逐条成文，含结构/契约/测试/语言/数值/流程六类硬性纪律与本项目反面案例对照表。摘要（全文以文档为准）：
|
||
|
||
- **结构**：禁止上帝对象；功能以类封装；views →(信号)→ 组合根 →(写调用)→ core 依赖单向；核心写调用只在组合根发生
|
||
- **命名**：领域命名，禁止系统 ID 前缀（a1_/b1_/c1_）进入文件名与类名（子系统中文规范名 ↔ 英文代号对照表见 `design/gdd/02-系统清单.md`）；核心文件头注必须带「实现 GDD」溯源行；禁止事实约定——未成文的约定当场补条文
|
||
- **契约**：信号/事件契约成文，状态机每条迁移路径都必须发事件（缺事件 = 软锁）；跨层标识符语义单一（位置 ≠ 句柄）；模态覆盖层打开必须隐藏遮挡物
|
||
- **测试**：每个可交互 UI 区域必须配套场景级探针（只有 core AC 不算有测试）；缺陷修复必须沉淀回归断言；提交前 smoke + 全部场景探针全绿
|
||
- **数值**：期望值必须标明尺度（每格/每板/每战/每关）；调参先测量后复测；单尺度校准必须跨尺度推演；用户拍板外的细节零发挥，列"待拍板"等裁决
|