DKChan
b27e4710b6
用户裁定（2026-10-17）五条：①代码批只跑代码闸、文档批只跑文档闸；②迭代批是代码实现批，
禁写 design/，文档只读、是实现批写测试与代码的输入依据；③迭代实现报告不写在 design/ 内；
④不设文档编写 skill——文档由用户在会话中讨论后落地；⑤本批属工具/规则面，不占迭代号。
一、tools/run_all_gates.sh（域划分唯一出处）
- 新增 `--code`（01 冒烟/02 单元/03 探针 --click/04 探针 --full/05 渲染闸/09 静态扫描/11 回放对拍）
与 `--docs`（06 gdd_lint/07 doc_link/08 doc_term/08b active.md 体量）；10 熵增闸两域都含
（文档批新增或挪动 .md 同样会绊它，且纯文本秒级）；不带参数＝全量，改闸件本身或跨两域时用。
- 域外闸不入 NAMES，不产生假变化；同时修「基线绿 → 现 SKIP」被误判为闸况变化（--quick 回执
此前永远自带三条假红）。
- 回执增 domain 与 not_run 字段。
- 导出 PYTHONIOENCODING=utf-8：GBK 控制台下 06/10 两闸打印 ✅/✗ 直接崩（假红）、09 的 FAIL 行
写成乱码字节致指纹漂移（假「红项清单变化」）、末尾汇总自身崩打不出结论——2026-10-16 实踩。
- 新增代码域素材齐盘预检：game/assets/art/** 与一切 *.import 边车都不入 git（2026-09-29 裁定），
worktree 冷检出必空盘 → main_theme.tres 解析失败 → 冒烟 V1 七项假红。缺位即拒跑并列缺哪件，
附处置命令（cp 主区素材 + --editor --quit 刷导入；--import 不生成新素材边车）。
二、tools/render_gate.sh（空跑判绿改判红）
- 棋盘/菜单两段 golden 在素材缺位时原为 SKIP，而闸末照样打印「全绿」exit 0——一个像素都没比
却报通过。2026-10-16 菜单废基线事故正是靠这个信号盲区混过 worktree 自检的。现改判红。
三、reports/ 新顶层目录（实现批唯一可写目录）
- 收迭代实现报告/代拍板追认单/GDD 反哺点清单；repo_structure_audit.py TOP_DIRS 与 CLAUDE.md
Project Layout 两处白名单同批改齐（熵增闸自陈的强制口径）；reports/README.md 立范围与生命周期。
四、规则文本五处同步
- CLAUDE.md：验收口径改按域；硬性红线新增「两类批」条（迭代批禁写 design/ 与根规则文件、
产出只落 reports/、只跑代码域闸；非迭代批不占迭代号）；Project Layout 登记 reports/。
- process-conventions：§3.10 批末按域验收；§3.12 补 active.md 例外（会话状态唯一源，钩子本就
豁免）；§3.13 重写为「实现批禁写文档、产出物落 reports/、反哺点由文档批裁决后写入」；
§4 分级周期口径改三档；§2 三段流程「三·实现」行加禁写面。
- doc-conventions 载体分工表：迭代实现报告落位由 design/qa/ 改 reports/。
- architecture.md「测试与质量域」：新增「改动域划分」节（域表＋唯一出处声明＋素材预检缘由），
本表是现状登记非第二份清单。
- 06-待办清单：登记本批两处代拍板（active.md 例外读法、reports/ 新顶层目录）与旧实现报告
iter27/iter28 两份仍在 design/qa/ 未迁位的欠账。
五、连带（不在本仓库，gitignored 本地 harness 配置）
- .zcode/hooks/worktree-guard.sh：合回校验由「不碰 game/ 即全免」改为按 diff 路径推定所需域、
要求回执 domain 覆盖之；未登记路径按最严处理，禁默认放行。旧豁免的漏洞：改闸件本身反而零验证。
- ~/.zcode/skills/iter/SKILL.md：顶部加批性质与闸域两条强制声明；批末重闸移出 doc 三闸；
总收口产出物改落 reports/、roadmap 换代移出本批；定义面入库注明是搬运非撰写。
验证：--docs 域全绿（06 由基线红改善为绿，因 fcb8c3f8 已补 01 篇流程图）；素材预检反例实测
（移走 button_stone.png → 拒跑 exit 1，还原后正常）；渲染闸缺盘反例实测（exit 1 并报 FAIL）；
--code --docs 互斥与非法参数 exit 2；guard 内嵌 python 编译通过并按 docs 域回执放行 docs 批。
73 lines
8.5 KiB
Markdown
73 lines
8.5 KiB
Markdown
# Dungeon Sweeper（扫雷 × 自动战斗 闯关 Roguelike）
|
||
|
||
扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发，MVP 优先管线。
|
||
设计入口：`design/gdd/02-系统清单.md`（根索引）· 概念：`design/gdd/00-游戏概念.md`
|
||
|
||
> 本文件只保留全局元信息与硬性红线索引；领域细则在子文档，动手前先查「规范导航」。
|
||
|
||
## Technology Stack
|
||
|
||
- **Engine**: Godot 4.7.2 · **Language**: GDScript · **Build**: SCons（engine）+ Export Templates · **资源管线**: Godot Import System + 自定义 resource pipeline
|
||
- **Godot 本机固定路径**：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe`（headless/命令行一律 console 版；编辑器版同目录）
|
||
|
||
## Engine Version Reference
|
||
|
||
@design/dev/engine-reference/godot/VERSION.md
|
||
|
||
## 运行与验证（工作目录 = 含 project.godot 的切片目录）
|
||
|
||
- **交付前验收 = 跑 `tools/run_all_gates.sh`，按本批改动域选档（`--code` 只跑代码域／`--docs` 只跑文档域／不带参数＝两域全量），所选域全绿才合回 master**——它是全部验证闸的唯一入口与唯一清单，**域划分也只写在它这一个地方**，闸件增减与分域调整都只改它，文档禁另列清单。改闸件本身、或一次改动同时跨两域时跑全量档（§6.2 共享件例外）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 字段），合回时由 worktree-guard 按 diff 路径推出该验哪个域再校验回执（缺回执／quick 模式／回执 commit ≠ HEAD／域不覆盖本次改动／含新增红，五况一律拦截）
|
||
- 单件直跑（调试期最窄确认用，**不构成验收**）：系统级断言面 `python tools/run_smoke.py`（名带 smoke 但不止存活检查，术语见 `game/tests/README.md`）· 场景探针 `…console.exe --headless --path . res://smoke/ui_probe.tscn` · 单元 `… --script res://tests/run_all.gd`
|
||
- 调参批量：`--script res://smoke/adventure_monte_carlo.gd`（全冒险期望）· `res://smoke/reward_expectation.gd`（奖励期望）；通关率/难度类测量一律走全冒险
|
||
- 数值验证：`python tools/balance_verifier.py`（采集端 `res://smoke/verifier_batch.gd`，报告落 `design/qa/`）
|
||
- 熵增闸（新类别 = 同批修订 Project Layout + 白名单）：`python tools/repo_structure_audit.py`
|
||
|
||
## Project Layout
|
||
|
||
- `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`，文档增删必须同步；`gdd/ux/` 战斗画面与交互规格）
|
||
- `design/registry/` — 跨系统事实登记（entities.yaml 术语与已锁数值、architecture.yaml 架构登记）
|
||
- `design/art/` — 美术纯文档（圣经/清单/提示词卡 + references/）；评估调研归 `design/research/`；不放图片
|
||
- `design/dev/` — 工程规范（五份规约 + architecture + engine-reference）
|
||
- `design/qa/` — 验证报告 + QA 呈现产物图；`design/research/` — 调研/提案/评估/历史验收
|
||
- `artwork/` — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 `archive/`
|
||
- `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/` — 游戏工程本体（代码 + smoke/ 冒烟 + tests/ 单元集成）
|
||
- `sim-data/` — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑
|
||
- `tools/` — python 工具脚本；`archive/` — 收口归档 zip（gitignored）
|
||
- `reports/` — 迭代批产出物（实现报告/代拍板追认单/GDD 反哺点清单）；**实现批唯一可写目录**，只放 .md，不是事实源（细则见 `reports/README.md`）
|
||
- 根目录：`active.md`（会话状态唯一状态源，退役规则见 doc-conventions 第 10 节）、`roadmap.md`（里程碑）、`stage.txt`/`review-mode.txt`（运行开关）
|
||
|
||
## 规范导航（动手前先查表）
|
||
|
||
| 时机 | 权威文档 |
|
||
|---|---|
|
||
| 批次开工 / 流程纪律 | `design/dev/process-conventions.md`——worktree 铁律、三段开发流程、批次清单、测试两入口与 MC/闸机细则、像素纪律 |
|
||
| 写代码 / 改代码前 | `design/dev/code-conventions.md`——结构/契约/语言/数值/流程五类硬纪律（反例库 = 同目录 code-conventions-cases.md） |
|
||
| 写测试 / 改测试前 | `design/dev/test-conventions.md`——探针标配 / 回归断言 / 全量验证 / 验收清单落码 / 变异验证 |
|
||
| 写文档 / 改文档前 | `design/dev/doc-conventions.md`——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期 |
|
||
| 概念切分与互链 | `design/dev/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 |
|
||
| 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 |
|
||
| 架构（唯一事实源） | `design/dev/architecture/architecture.md`——历史决策沿革查 git commit log，不另设决策文档 |
|
||
| 术语、已锁数值 | `design/registry/entities.yaml`——仅 owner 文档可修订，冲突须显式提出 |
|
||
| 会话进度 / 路线图 | 根 `active.md`（状态文件：只记现在，每行当下为真；快照+未决面+滚动条目）· 根 `roadmap.md` |
|
||
|
||
## 硬性红线（勿违反；操作细则在 process-conventions.md 与各规约）
|
||
|
||
- 主工作区禁止直接改动与提交——一切改动走独立 worktree（豁免：active.md 会话收口、.zcode 钩子配置）
|
||
- 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测
|
||
- 交付前验收 = 跑 `tools/run_all_gates.sh` **按改动域**全绿（唯一入口、唯一闸清单、唯一域划分，禁在文档另列）；合回 master 由 worktree-guard 按 diff 推域校验回执强制（process-conventions §3）
|
||
- **两类批**——**迭代批**（代码实现，`/iter` 发射）：**禁写 `design/` 整个目录**（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；产出物只准写 `reports/`；批末只跑代码域闸。**非迭代批**（工具/规则/文档改动）：不占 roadmap 迭代号，按改动域跑闸。文档内容的落地由用户在会话中讨论后进行，**无专用的文档编写入口/skill**
|
||
- MC/模拟：无数值改动零跑；档位硬闸见 `sim-data/README.md`「MC 采集档位表」，一档只能由用户发起
|
||
- 闸机轮次纪律：新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册（process-conventions §6）
|
||
- 变异验证——新增/改写验收函数必须变异变红才算验收成立；无变异红记录只写「已实现，拦截能力未证」（test-conventions §6）
|
||
- 中间产物吸收即死——结论先吸收进权威文档、未决先迁 06，文件即删且永不提交（doc-conventions 第 11 节）
|
||
- 用语红线——一切对用户输出禁自造黑话，需要作者解释的词必须展开成完整白话句（doc-conventions 第 4 节三形态表）
|
||
- 呈报六问——What 现状差异 / Why 动机与不做代价 / How 方案与全部备选 / Where 影响面 / 验收判据 / 不确定点单列收尾；Who/When 不进正文；仅首次描述需求/bug/方案适用
|
||
- 真人检测只登记不阻塞——登记进 07 清单/实现报告即完成义务，禁以等目检为停工理由或收口前置
|
||
- 文件头 = `##` 文档注释，介绍本模块，≤8 行两类白名单（①职责摘要 ②使用约束；禁一切文档反向链接；code-conventions §1.4.1，规范权威 = Google pyguide §3.8 + PEP 257；机器闸 tools/audit_file_headers.py）
|
||
- 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径
|
||
- RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流
|
||
- 架构事实唯一源——架构事实只认 `design/dev/architecture/architecture.md`；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log
|
||
- Core 层零 UI 依赖——完整战斗必须可 `--headless --script` 跑通；fail-fast——数据校验错误一律致命中止，无软回退
|
||
- spec-AC 一致性——规约与验收标准不得在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离）
|
||
- 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节）
|