# 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/engineering/engine-reference/godot/VERSION.md

## 运行与验证（工作目录 = 含 project.godot 的切片目录）

- **合回验证 = 前置检查 ＋ 远端 CI（前置检查 2026-11-06 用户裁）**：主区 `git merge --no-ff` 落合并提交前，pre-merge-commit 钩子（`tools/hooks/pre-merge-commit`）自动跑 `tools/run_all_gates.sh --premerge`——冒烟测试＋单元测试全套件（4 分片），热导入缓存约 2 分钟；红＝合并提交不落（修红后 git commit 续合，或 git merge --abort 放弃），快进合并不触发钩子，`--no-verify` 可跳过且仅属用户。git merge 合回 master 落地后，post-merge 钩子（`tools/hooks/post-merge`）自动 `git push origin master` 触发远端 CI（Gitea Actions，runner＝Mac 本机 host 模式，环境自举件＝`tools/ci/mac_setup.sh`），工作流（`.gitea/workflows/ci.yml`）按改动域分流（分流算法单点＝`tools/ci/domain_route.sh`）：游戏码批＝两域全量含渲染闸，文档批＝文档域秒级闸，纯闸件/管线批＝零触发。远端结果**按需现查**：`tools/ci_check.sh <合并提交>` 读该提交任务的 run `status`/`conclusion`，只呈报、不落盘（2026-11-04 用户裁：合回不等待、不唤醒；判据＝run 落定后的终局态，且绿须坐实跑闸步真跑过——零触发批呈报「未验」不作绿证，细则=process-conventions §1 第 3 条）。**合回落地即向用户呈报本批总结并止回合**，禁前台 sleep／轮询等 CI。CI 红态不回滚合并——红项在案、修复批合回即再推再验追绿；开工先跑现查件读 CI 状态，红未修不开新批。同一份字节禁止第二次人手跑。`tools/run_all_gates.sh` 仍是全部验证闸的**唯一入口与唯一清单，域划分与选闸算法只写在它这一个地方**，文档禁另列清单；`--code`／`--docs`／`--quick` 是开发期改完即测的选档入口（细则见 process-conventions §4），全量档不替代它。**runner 依赖**：Mac 需开机在线（关机＝远端任务排队延后）；换机/重装按 `tools/ci/mac_setup.sh` 自举
- 单件直跑（＝改完即测的最窄确认，其读数就是那一步的凭据；跨改动面的漏网由合回后远端全量档兜）：冒烟测试 `python tools/run_smoke.py`（`game/tests/smoke_boot.tscn` 极小启动场景）· 系统测试 `python tools/run_system_test.py`（宿主 `game/tests/system_test.gd`）· 场景探针 `…console.exe --headless --path . res://probe/ui_probe.tscn` · 单元测试 `… --script res://tests/run_all.gd`
- 调参批量：`--script res://sim/adventure_monte_carlo.gd`（全冒险期望）· `res://sim/reward_expectation.gd`（奖励期望）；关卡完成率/难度类测量一律走全冒险
- 数值验证：`python tools/balance_verifier.py`（采集端 `res://sim/verifier_batch.gd`，报告与原始数据落 `sim-data/`）
- 熵增闸（新类别 = 同批修订 Project Layout + 白名单）：`python tools/repo_structure_audit.py`

## Project Layout

- `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`，文档增删必须同步；`gdd/ux/` 战斗画面与交互规格）
- `design/art/` — 美术文档（圣经/角色设计/两份清单/路径图/提示词库与生图操作单）；只放 .md 与 `references/` 参考图，审计报告与调研归 `reports/`
- `design/engineering/` — 工程规范（五份规约 + architecture + engine-reference）
- `design/content-archive/` — 退役内容留底（活文档，2026-10-20 用户裁新立：内容已退役、留底供日后重新过准入；落内文件头部写明所属线）
- `design/research/` **已退役（2026-10-21 用户裁）**——`design/` 全目录只放持久化设计文档与规范，调研/提案/评估/历史验收一律落 `reports/`（熵增闸退役路径清单已收该目录，再现即判红）；`design/qa/` 已退役，验证截图不进 `design/`（判据见 doc-conventions §11）
- `artwork/` — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 `archive/`
- `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/probe/` — 场景探针的场景与宿主＋探针共用面（probe_gate/render_gate 在闸＋人工取证探针）；`game/sim/` — 测量/诊断/模拟驱动件（autoplay 策略、MC 批量、数值验证采集端）；`game/` — 游戏工程本体（代码 + tests/ 冒烟/单元/系统测试面）
- `sim-data/` — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑
- `tools/` — python 工具脚本（含 `hooks/`＝版本化 git 钩子，经 `core.hooksPath` 挂载）；`archive/` — 批次完结归档 zip（gitignored）
- `reports/` — 过程件容器：**需求卡片**（写卡段产出，实现批的输入合同）＋迭代批产出物（实现报告/GDD 反哺点清单）＋设计讨论段过程稿（提案/审计/需求澄清/评估）；**实现批唯一可写目录**，中间文档唯一容器（`design/research/` 已退役），不是事实源（细则见 `reports/README.md`）
- 根目录：`README.md`（纯指路牌：设计/流程/当前位/待办四个链接，零规则重述）、`roadmap.md`（里程碑＋迭代总表六列＋顶部「当前位」节＝现在做什么）、`待办清单.md`（流水线唯一登记处，条目级待办与状态）、`体验验证清单.md`（需真人试玩才能下结论的验证项）、`stage.txt`/`review-mode.txt`（运行开关）、`playnote.md`（用户本人试玩随手记，只由用户增删，不属任何文档族）；仓库根禁止再设会话状态文件（细则见 doc-conventions 第 10 节）

## 规范导航（定方案前先查表——确认写什么内容之前读规则，不是动手前才读）

| 时机 | 权威文档 |
|---|---|
| 批次开工 / 流程纪律 | `design/engineering/process-conventions.md`——车道铁律（一切改动走独立 worktree，主区只作合并落点）、合回后远端 CI、五段流水线、批次清单、改完即测与 MC/闸机细则、像素纪律 |
| 流水线段入口 | 技能对照——doc-design=文档设计（兼任反哺点落文）／asset-ingest=美术录入／req-card=写卡／iter-plan=迭代编排／iter=实现（五者均装于项目 `.zcode/skills/`）；登记不立技能；批后收尾与中间文档退役=batch-closure（同一目录）；格式与状态机权威=`design/engineering/doc-conventions.md` §12 |
| 定代码方案 / 写代码 / 改代码前 | `design/engineering/code-conventions.md`——结构/契约/语言/数值/流程五类硬纪律（反例库 = 同目录 code-conventions-cases.md） |
| 定测试方案 / 写测试 / 改测试前 | `design/engineering/test-conventions.md`——探针标配 / 回归断言 / 提交前验证 / 验收清单落码 |
| 定文档方案 / 写文档 / 改文档前 | `design/engineering/doc-conventions.md`——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期 |
| 概念切分与互链 | `design/engineering/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 |
| 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 |
| 架构（唯一事实源） | `design/engineering/architecture/architecture.md`——历史决策沿革查 git commit log，不另设决策文档 |
| 术语与已锁数值 | 规范名与定义 = `design/gdd/术语表.md`（全库唯一对照表，仅 owner 文档可修订）；现行数值 = `game/data/tables/*.tres`；规则（概念面）= 各系统 owner 文档；取值域与字段契约 = `game/data/schemas/*.gd`。冲突须显式提出，禁默默改值 |
| 现在做什么 / 待办与待裁 | 根 `roadmap.md` 顶部「当前位」节＋迭代总表六列 · 待办唯一登记处 `待办清单.md` · 批次过程与结论查 git 提交信息与 `reports/` |

## 回答风格规则（只管对话输出；文档写作归 doc-conventions §2–§4）

### 核心原则（按优先级）

1. **用词封闭**：对话里可用的词＝日常汉语＋用户先用过的＋当场展开过的。展开＝先完整描述再给短说法，描述交代三样：指什么对象、怎么运作、带来什么后果。短说法只认两个来源：用户用过的直接跟用；自己提议的必须等用户回话里用过一次才成立。项目文档定过名的词不豁免，对话里首次出现照样先展开。同物同名：同一东西从头到尾一个叫法，不换词；一个词不指两个东西。起名的固定顺序＝先描述、再命名、后沿用，禁止颠倒。
2. **判断挂依据**：判断＝「X 是／不是／造成了／应该」类陈述；每个判断后面必须跟依据。依据只认三种：仓库文件＋行号或逐字引用（给行号就必须真读过那几行）；本对话的消息号或原话；外部链接。三种都拿不出的判断必须当场标「这是推测」；说不出依据就答「不知道／没查过」，禁止编造。答复形状＝结论行→依据清单→细节。
3. **简洁**：同一意思只说一遍；能用一句不说两句。硬约束、数字、前提条件不参与压缩；信息完整与简洁冲突时保信息。
4. **多角度**：介绍一个物体、一个概念、一个问题，多角度讲清楚；每角度信息点 ≤3 个，禁止违背第 3 条。
5. **闸况呈报用闸名**：对话里报验证闸的跑批结果一律用闸名（冒烟测试／系统测试／单元测试／场景探针／渲染闸等），不裸报编号。

### 简洁细则

- 禁换说法重复：同一判断换个措辞再说一遍＝违规。依据与展开不算重复——依据是支撑判断的材料，展开是第一次给出来历，都是新信息。
- 禁铺垫、过渡句、客套话、总结句。认领责任的一句（如「是我的失误」）不算客套；所禁是铺垫与重复道歉。
- 禁填充句式：其实／说白了／本质上来说——直接给结论。
- 短句为主，一行一个意思；一句只说一件事。装不下拆成短句，不算啰嗦。
- 答完即止。所禁是无新信息的客套邀约；回答含待用户决断的分叉或待授权动作时，末尾一句决策请求不受限。

### 多角度细则

- 触发：解释概念、评估方案、回答「X 好不好」。事实型问题判据＝答案能否一句装下：装得下一句直答；装不下按格式优先级上清单，不算硬凑角度。
- 评估与呈报类第一行＝结论行：判断＋一句主理由；结论行之后必须紧跟依据清单（核心原则第 2 条），依据不齐不出结论；角度列表随后。
- 角度池（示例集非封闭集，按问题选 2～5 个；机制与流程题可自造稳定轴命名）：现状（现在是什么、缺什么）· 本质（是什么、解决什么）· 代价（要什么前提）· 边界（何时不成立）· 对比（与替代方案差异）· 风险（最常见失败方式）。
- 每个角度＝关键词＋一个判断＋至多一句理由；角度里的判断按核心原则第 2 条挂依据。
- 角度之间用编号，不用「另外、此外、同时」串联。

### 交出前自检

长答复（三段以上或含多个判断）交出前过一遍清单：一、每个判断都挂依据了吗？二、每个非日常汉语的词都先展开了吗？三、有没有只有自己知道来路的内容？哪项不过改哪项，改完再交。自检不产出一节文字，产出是改过的答复本身；用户质疑时必须能复述自检过程。

### 重讲与改写工具

- 把一个主题讲成零基础图解：/eli5。
- 简明技术中文（STC）技能：限定用词与句式的中文写法规范，含词表与检查脚本；写或改写中文技术说明、把回答改写得更清楚时调用（/simplified-technical-chinese）。核心原则第 1 条是它的对话面最小集。

### 格式优先级

能画图的内容一律画图说明，图是第一优先载体；枚举用列表，二维对照用表格；散文是最后手段。

### 图优先

**判据**：描述含多个实体、实体间有明确关系（先后顺序、包含、依赖、状态转移、布局对比）的内容时，直接画图说明，不写长段文字；单点事实（一句装得下）不画，纯数据对照用表格。

**载体**：用 diagram-design 技能出 HTML/SVG 内联交付（流程/状态/结构/实体关系与空间对比、像素级示意、界面草图同一通道），大图精修与导出用 archify 技能；查看端不支持内联渲染时用字符画。

**边界**：硬数值与前提条件留在文字里，图不承载唯一数值依据；图与文禁重复说同一件事，文字只留图说不清的部分。

## 主动检索提醒

- 训练记忆缺失或可能过时的问题，先搜最新主流的答案再回答。

## 硬性红线（勿违反；操作细则在 process-conventions.md 与各规约）

- 车道铁律（2026-10-31 用户裁恢复）——主工作区只作合并落点，一切开发/设计改动走独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`（建区即跑 `tools/setup_worktree_userdir.sh`），收口＝冻结→件核→并 master→重塑→主区 `git merge --no-ff`→删区（合回即删，2026-09-19 原裁），CI 红不回滚合并——新开修复 worktree（`fix-<任务名>` 分支，免重塑免数卡）修复合回追绿；会话单区（2026-11-04 用户裁）——同一时刻每会话至多一个 worktree 在役，同会话追加事项并入在役区、只做一次合入（一次 CI），合回后用户再发令＝新回合另开区，迭代实现批独占回合（细则见 process-conventions §1 第 5 条）；主区唯一合法写动作＝合并，agent 侧由 worktree-guard 拦主区 Edit/Write 与非 merge 提交；豁免面仅 `.zcode/`、`.qoder/`（不入 git，主区直改）；commit 点零钩子检查（pre-commit 直改闸已退役）；合回 merge 点另有前置检查钩子（pre-merge-commit，2026-11-06 用户裁，见「运行与验证」首条）；全量验证归合回后远端 CI（post-merge 钩子推送触发，见「运行与验证」首条）；`--no-verify` 仅属用户，agent 禁用（细则见 process-conventions §1）
- **仓库根禁止设会话状态文件**（`active.md` 已废除）——现状看 roadmap「当前位」，待办看待办清单，过程看 git 提交信息，产出物看 `reports/`；任何文档禁止另设「当前状态快照」节，两处记同一件事必然漂移（细则见 doc-conventions 第 10 节）
- **改完即测铁规（2026-11-05 用户裁，取代原「测试执行两入口铁规」）**——任何会话里的任何改动，落笔之后立刻跑一遍覆盖该改动面的验证并跑绿、读数写进这一步的提交信息，这一步才算完成；验证载体一律按 `tools/run_all_gates.sh` 的域划分与该件自身的直跑方式，不扩出改动面、不请示、不等点名，未改动的面不测，合回后远端 CI 的全量跑批不替代本条。读数类采集（MC/verifier）不在该域划分内，不属本条义务
- **红账不清不开新批**——上一批远端跑批有真红未闭合不开新批；假红（导入缓存、user 目录未隔离那类在册环境坑）走异常分级处置，不算未闭合
- 合回后验证 = 远端 CI 闸全绿（唯一强制**全量**验证点；唯一入口、唯一闸清单、唯一域划分与选闸算法仍只在 `tools/run_all_gates.sh`，禁在文档另列；触发与追绿语义见「运行与验证」首条与 process-conventions §1）。它兜的是跨改动面的漏网，不替代改完即测铁规；主动发起的跨域全量回归归用户。分流算法单点＝`tools/ci/domain_route.sh`
- **改动四类**——**需求改动**（游戏代码，含随逻辑写/改的测试代码）：唯一走「写需求卡片＋编入迭代批次」通道；迭代实现批禁写 `design/` 整个目录、两份根流程清单（`待办清单.md`/`体验验证清单.md`）与 `game/tests/README.md`（能力清单，归写卡段维护）（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批禁止顺手改；产出物只准写 `reports/`；合回后由远端 CI 验证（红项修复合回追绿，process-conventions §1）。**工程改动**（tools/、闸件、模拟测量工具、纯测试维护——不改变游戏行为的配套代码）、**文档设计改动**、**美术素材改动**：不写需求卡片、不编迭代批次，由用户发令走独立 worktree 直改＋合回（车道铁律，commit 点零钩子检查）；大体量改动（含触及代码面的工程改动如纯测试维护）同车道无特殊通道；文档设计类写入走 doc-design 技能（登记条目格式由流水线闸强制）
- 五段流水线铁律——**需求改动**（游戏代码）按「登记 → 文档设计／美术设计 → 写需求卡片 → 迭代编排 → 实现」五段推进，段间不自动流转、每段转进由用户发令；编入迭代的卡片必须设计闭合＋零待裁点＋卡内复核记录在位（2026-11-05 用户立规：复核发现按四类去向处置——自判／补写／待裁／退回上游，只有后两类归用户；复核没跑完禁对用户称完成，细则=req-card 技能「复核发现四类分流」与「写卡段的完成判据与呈报口径」）——需求卡片任何工作量皆可写、皆可编入迭代，工作量限制只属迭代层（迭代估时总量 <5 个工作日＝「冻结待凑批」、不可开工）；流水线闸 `tools/pipeline_gate.py` 强制（已注册进 run_all_gates.sh 文档域）；实现段零裁断——卡片没写清=上游缺陷，停该卡退回上游，禁内联求裁（process-conventions §2，格式与状态机=doc-conventions §12）。工程／文档设计／美术素材三类改动不走写卡与编排段：（如需设计讨论）→ 用户发令 → 独立 worktree 直改 → 合回 CI（车道细则=process-conventions §1）
- MC/模拟：无数值改动零跑；档位硬闸见 `sim-data/README.md`「MC 采集档位表」，一档只能由用户发起
- 闸机轮次纪律：新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册（process-conventions §6）
- **验收闭合**——每个需求点与每个行为改动都要有从真实入口进入的验收断言，可 grep 定位、在当轮真实跑批中执行并通过，判据绑被测改动特有的可观测提交面；**禁变异类测试与撤销类取证**（2026-10-24／2026-10-28 用户裁——人为制造红属伪造证据），证明做不出＝停卡呈报；禁删断言/放宽阈值换绿；合回前独立验收审计未过则禁止合并（细则=test-conventions §8＋iter 技能第 5 步）
- 规则评估——没在真实任务上评估过的规则修订，不算完成。
- 中间产物吸收即死——结论先吸收进权威文档、未决先迁待办清单，文件即删且永不提交（doc-conventions 第 11 节）
- **禁写变更记录**——文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁写「本版改了哪些条款」式逐版本叙述与 `# 2026-xx-xx 缺陷修批——` 式行内修订注记；沿革只进 git commit log。版本号可作文档现行身份标记留在文首状态行与正文引用中（doc-conventions 第 5 节，机检闸 gdd_lint R4 反转拦截）
- 真人检测只登记不阻塞——登记进体验验证清单/实现报告即完成义务，禁以等目检为停工理由或当作合回的前置条件
- 文件头 = `##` 文档注释，介绍本模块是什么；禁写变更叙事（改动史查 git log）；禁文档反向链接（code-conventions §1.4.1）
- 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径
- RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流
- 架构事实唯一源——架构事实只认 `design/engineering/architecture/architecture.md`；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log
- Core 层零 UI 依赖——完整战斗必须可 `--headless --script` 跑通；fail-fast——数据校验错误一律致命中止，无软回退
- spec-AC 一致性——规约与验收标准禁止在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离）
- 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节）