88 lines
13 KiB
Markdown
88 lines
13 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 · **Language**: GDScript · **Build**: SCons（engine）+ Godot Export Templates · **资源管线**: Godot Import System + 自定义 resource pipeline
|
||
- **Godot 可执行文件（本机固定路径）**：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe`——headless / 命令行一律用 console 版；编辑器版为同目录 `Godot_v4.7.2-stable_win64.exe`
|
||
|
||
## Engine Version Reference
|
||
|
||
@design/dev/engine-reference/godot/VERSION.md
|
||
|
||
## 运行与验证（垂直切片）
|
||
|
||
工作目录 = 切片目录本身（含 `project.godot` 的那一层）：
|
||
|
||
- 冒烟（全量 headless 断言）：`python tools/run_smoke.py`（包装器三闸：退出码＋摘要失败数＋SCRIPT ERROR 扫描——脚本错误不计冒烟失败数且静默中断所在函数剩余断言，2026-09-19 台账 84 立闸）。底层命令 = `…console.exe --headless --path . --script res://smoke/smoke_all.gd`
|
||
- 场景级探针（呈现层回归）：`…console.exe --headless --path . res://smoke/ui_probe.tscn`；另有 `ui_tune_probe.tscn`（调试浮窗——2026-10-04 迭代 14.5 起原数值调整板收进 debug_overlay）、`ui_click_probe.tscn`（合成鼠标事件行为探针）
|
||
- 调参期批量工具：`--script res://smoke/adventure_monte_carlo.gd`（全冒险期望扫描）· `--script res://smoke/reward_expectation.gd`（奖励获取期望）——单关直入口口径已退役（2026-09-23 用户拍板），通关率/难度类测量一律走全冒险（原 level_monte_carlo/level_debug 已删）
|
||
- 数值验证工具：`python tools/balance_verifier.py`（零强化冒险逐关条件通关率＋止步节点归因＋营地循环爬升战役——采集端 `--script res://smoke/verifier_batch.gd`，报告落 `design/qa/`；元进度换算率标定与曲线调参的自动化评判面，2026-09-22 数值验证工具批；直入口带判定随口径退役暂停，带重锚归曲线调参批）
|
||
- 交付前验收 = smoke + 全部场景探针全绿（测试细则见 `design/dev/code-conventions.md`）
|
||
- 结构审计闸（熵增闸）：`python tools/repo_structure_audit.py`——顶层目录/根文件/图像白名单/退役路径四查，违例 FAIL；新类别 = 同批修订 CLAUDE.md Project Layout + 脚本白名单，commit 留痕（2026-09-27 立闸）
|
||
|
||
## Project Layout
|
||
|
||
- `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`；文档增删必须同步它；`gdd/ux/` 战斗画面与交互规格）
|
||
- `design/archive/gdd-2026-09-14/` — 旧版 GDD 归档（只读参考，不作事实引用）
|
||
- `design/registry/` — 跨系统事实登记（entities.yaml 术语与已锁数值、architecture.yaml 架构登记）
|
||
- `design/art/` — 美术**纯文档**：定稿规范 md（圣经/清单/提示词卡）+ `references/` 参考池；评估/调研 md 一律 `design/research/`；**不放任何图片**
|
||
- `design/dev/` — 工程规范：code-conventions / doc-conventions / architecture(ADR) / engine-reference
|
||
- `design/qa/` — 验证报告 md（balance-verifier/playtest/等价证明；raw 数据归 `sim-data/`）＋QA 呈现产物图（目检预览拼图等——2026-09-29 迭代 5 返工批收编图像白名单）
|
||
- `design/research/` — 调研/提案/评估记录/历史验收/执行工单
|
||
- `artwork/` — **在途图像素材唯一工作区**（2026-09-27 用户三层裁定：文档归文档/在途图归一处/终稿归游戏）：生图候选批次（每批一目录+每资产一目录+vN 命名）、像素稿、样张渲染、实机截图全在这里；**整目录不入 git——2026-10-02 用户裁：内容永久保留本地、永不提交（md 例外一并取消，.gitignore `artwork/` 强制）**；收口归档 `archive/`
|
||
- `game/assets/art/` — 已验收终稿（入包被游戏加载）
|
||
- `game/` — 游戏工程本体：代码三件套+`smoke/` 冒烟套件+`tests/` 单元/集成测试（2026-09-27 根 tests/ 并入）
|
||
- `sim-data/` — 机器读数据产物：模拟试玩 CSV/JSON、verifier raw 基线、日志样例输出。**数据件不入 git（2026-10-03 用户立规：.gitignore 强制）——语义=MC 缓存层：最新一份 MC 锚+读数常驻留盘供分析直读，无数值调整禁重跑（细则见「测试执行两入口铁规」MC 触发细则）；`iteration_log.md` 模拟批日志同目录留盘不入库。入库例外三件（2026-10-03 二裁）=`README.md`+`analyze.py`+`growth_model.py`（分析工具本体随 git）**
|
||
- `tools/` — python 工具脚本本体（验证/审计/像素化/仪表盘/日志分析）
|
||
- 根目录运行文件：`active.md`（会话快照+台账）、`roadmap.md`（里程碑）、`stage.txt`/`review-mode.txt`（运行开关）
|
||
- `archive/` — 收口归档 zip（gitignored）
|
||
|
||
## 规范导航（动手前先查表）
|
||
|
||
| 时机 | 权威文档 |
|
||
|---|---|
|
||
| **写代码 / 改代码前** | `design/dev/code-conventions.md`——结构 / 契约 / 测试 / 语言 / 数值 / 流程六类硬纪律 + 反面案例对照表 |
|
||
| **写文档 / 改文档前** | `design/dev/doc-conventions.md`——可读性第一、白话写作、概念封装、引用纪律、文档骨架、文档生命周期（吸收即死） |
|
||
| 查系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照表 |
|
||
| 架构与决策记录 | `design/dev/architecture/architecture.md` + 同目录 `adr-*.md` |
|
||
| 引擎版本与参考 | `design/dev/engine-reference/godot/`（版本表已在上方 @ 引入） |
|
||
| 术语、已锁数值 | `design/registry/entities.yaml`——仅 owner 文档可修订，冲突须显式提出 |
|
||
| 会话进度记录 | 根目录 `active.md`——顶部「当前状态快照」节 + 批次台账；收口先改快照再记账；条目用完整白话句子写清结论，能看懂比短重要（2026-10-04 用户立规），详情归正主文档 |
|
||
| 工程路线图 | 根目录 `roadmap.md`——里程碑时间线与下一步顺序（批级视图；实时状态看快照节） |
|
||
|
||
## 分支纪律（worktree 铁律，2026-09-19 用户立规）
|
||
|
||
主工作区（本目录，`master` 检出）只作**合并落点与共享状态载体**，一切开发/设计改动不得直接发生在主工作区：
|
||
|
||
1. **开工**：每个任务批次先建独立 worktree 分支再动手：`git worktree add ../g-plan2-<任务名> -b <任务分支>`。所有代码/文档/数值改动与验证跑测都在 worktree 内进行（注意：未跟踪文件不会出现在新 worktree，需手工搬运）
|
||
2. **收尾**：迭代 loop 批次在验证全绿（冒烟 + 场景探针；冒烟挂迭代开发完成后的出口/落籍闸）后，在主工作区 `git merge --no-ff <任务分支>` 落回 master，然后 `git worktree remove` + 删分支；合并前先看 active.md 尾部台账，避免与并行会话撞号/漏捎带。非 loop 批次收口跑闸与否按「测试执行两入口铁规」（见硬性红线）：默认不跑，用户点名或当场问
|
||
3. **豁免面（仅这两处允许主工作区直改）**：根目录 `active.md`（会话收口）与 `.zcode/`（钩子配置）——其余一律走 worktree；主工作区 `git commit` 会被钩子直接拦截
|
||
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent 侧，用户本人手工改动不受限
|
||
|
||
## 硬性红线（勿违反）
|
||
|
||
- **worktree 铁律**：主工作区禁止直接改动与提交（细则见上节；并行会话各占 worktree 互不踩踏）
|
||
- **测试执行两入口铁规（2026-10-02 用户立规）**：测试类执行——冒烟测试、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证调用——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代开发完成后的出口/落籍闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。除此之外（问答/调研/文档/审查/零散小改等短小会话）一律零测试，不得擅自调用任何测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。**MC/模拟验证触发细则（2026-10-02 用户确认，2026-10-03 补落文——出处：迭代 9 出口批 81000 锚误跑质询）**：MC/verifier 仅在**数值验证场景**触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**——结构位移类「存档锚」须先向用户请示定性再跑；任务书预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。**分级周期口径（2026-09-26 用户裁定，2026-10-03 自 06-待办清单收编）**：轻闸（run_smoke 全量+ui_input_probe；触碰 presentation 加跑 ui_click_probe+ui_layout_probe）可随变更执行；重闸（B 档视口截图像素断言〔game/smoke/shot_probe.gd〕、C 档黄金图对比〔tools/golden_compare.py〕、真人实机目检、MC 大扫描）属**周期执行**——统一在表现批收口或固定周检跑，不进每次变更
|
||
- **MC 采集档位细则（2026-10-03 用户四档立规，承接 MC 触发细则）**：MC 局数按用途四档硬闸（表见 `sim-data/README.md`「MC 采集档位表」）：**一档·调研**=总量 >40（100+ 为常用锚量级；60/档=结构回归、100=95% CI ±9.8pp、170=±7.5pp=15pp 带半宽、400 满档=±4.9pp 贴边裁决；normal 独立满档 ~8 分钟同属一档）**只能由用户发起**——任务书/计划书/agent 均无权发起，非用户发起一律不构成一档授权；**二档·数值修改验证**=总量 ≤40、每档 ≤20（仅 ≥~40pp 结构位移可判，同种子配对下 ~30pp）；**三档·小调**=总量 ≤20、每档 ≤10（只测不判）；**四档·微量**=总量 ≤5（sanity 门，零统计判读）。四档仅承接 MC 触发细则的数值验证场景，两入口铁规不变；超档=停机呈报，禁在二/三/四档下带值结论（窗口不足如实挂起）。改前/改后锚同 seed0 配对、改前锚留盘禁补跑；对拍断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC
|
||
- **中间产物吸收即死（2026-10-01 立规）**：中间文档（批任务书/机检报告/调研审计报告/模拟读数/迭代计划书/目检清单）寿命=迭代寿命——结论先吸收进正主文档、未决项先迁 `design/gdd/06-待办清单.md` 或 roadmap，然后文件即删，且永不提交 git；活文档=唯一事实源，git=变更记录。细则见 `design/dev/doc-conventions.md` 第 11 节
|
||
- **用语红线（2026-10-04 用户立规，黑话审计后落文）**：面向用户的一切输出——文档、工作日志（active.md）、报告、清单、对话——禁止自造黑话与代号式命名；判据 = 业内读者没读过项目历史也能一遍看懂，需要作者解释才能懂的词必须展开成完整白话句（三种固定形态、本仓反例全表与正确写法见 `design/dev/doc-conventions.md` 第 4 节）
|
||
|
||
- **数值单一事实源**：玩法数值只存 `data/tables/`（.tres），经 `ConfigDB` autoload 类型化单点读取；禁止数值字面量与自建 `load()` 表路径
|
||
- **RNG 单点**：禁止 `randomize()` / 自建 RandomNumberGenerator——随机只经 `RngService` 统一流（单盐单计数器+用途标签+全事件日志，ADR-0007 裁丙 2026-09-27）
|
||
- **Core 层零 UI 依赖**：完整战斗必须可 `--headless --script` 跑通
|
||
- **fail-fast**：数据校验错误一律致命中止，无软回退
|
||
- **spec-AC 一致性**：规约与验收标准不得在同一输入上给出不同答案（所有 GDD 同尺度）
|
||
- **评审隔离**：`/design-review` 必须在独立会话跑（与 `/design-system` 隔离）
|
||
|
||
## 像素结构件工作纪律(2026-09-26,高墙批转角三返工复盘用户令落档)
|
||
|
||
1. **先抄后造**:画任何像素结构件前,先从参考素材裁同类结构放大逐像素描述,再实现同款;禁止凭印象/第一性原理发明像素结构(圣经 §8.5 参考核验的执行口径)。
|
||
2. **验收口径写成像素级视觉判据**:开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子;自检放大最差交界处逐行核像素,不只看整板观感。
|
||
3. **±1px 一律坐标推导**:单像素级结构先写坐标推导(哪条线在哪列、谁与谁齐平)留档再写码;禁蒙数试错。
|
||
4. **修复默认附前后对比图+像素审计**,不等用户索要。
|