DKChan
f958a03f51
八件受版文件 git mv 进 reports/（一律先迁不删，删除归后续批或用户点名）：提案三件（冒险前资源配比预设／效果引擎无状态化／武器锻造系统）、审计两件（代码术语审计／单测与验收门禁标准测试审计）、美术审计两件（cursor 会话存档 md ＋ canvas 转 HTML 渲染件）、需求澄清-营地交互重做；未入库的 UI预览demo 三路对照件只搬盘不入库。 GDD 落文：锻造工坊.md「满级特效扩展位」节收下七条候选池（长剑破甲／长剑暴击面扩大／长枪先手连击／法杖开局魔法矢／轻甲灵巧／重甲反震／魔法护甲护盾），按现役 EFFECT_KINDS 与 settlement.tres:51/52 逐条复核实现代价分档，效果类型闭集口径取正文现行 31 种、不抄过程稿旧记 24 种；候选池定性为备用清单非承诺清单。 引用面换代 08（playnote 之外两处 ../research/ 改 ../../reports/）、待办清单四处、reports 八张卡片（跨目录前缀改同目录）、art-assets-checklist 与 sim-data/README 两处既存死指改「沿革查 git 提交史」、content-archive 出处句标注该目录已退役。迁入件内部相对链接随迁移重基准（../gdd/ → ../design/gdd/，playnote 与待办清单改回仓库根），并订正上一批遗留错误：两张迭代 30 卡片的 playnote 链接原写 ../../playnote.md（从 reports/ 出发指到仓库外），现改 ../playnote.md。 规则与机检：doc-conventions §11「暂存地非档案库」行改为单暂存地＋禁在 design/ 下设过程件目录＋图像载体与报告渲染件口径分列（禁图留 artwork/ 沿用 2026-09-27 用户裁；.html/.json 允许作为报告的一种＝2026-10-21 用户裁，原「只放 .md」句系 10-17 建目录时顺带照搬、无单独点头记录）；AGENTS Project Layout 两行同步；reports/README 补「设计讨论段过程稿」命名行。repo_structure_audit：DESIGN_SUBDIRS 去 research、RETIRED 加 design/research；doc_ref_audit 排除面清空（design 全树入扫描面）；doc_term/doc_link 扫描域注释换代；三件样张脚本 OUT_REPORT 改落 reports/ 并补 os.makedirs（改前只对 OUT_PNG 建目录，目录缺失即 FileNotFoundError）。 变异验证：重建 design/research 并放文件 → 结构闸退出码 1、同时报「退役路径再现」与「子目录越界」两条；design/ 内放两条指向不存在文件的引用 → 引用可核机检报「路径不存在」红项 2（该闸暂未注册进闸壳，无基线记录必判变化）；清场后结构闸 PASS。
12 KiB
12 KiB
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 的切片目录）
- 交付前验收 = 跑
tools/run_all_gates.sh，按本批改动域选档（--code只跑代码域／--docs只跑文档域／不带参数＝两域全量），所选域全绿才合回 master——它是全部验证闸的唯一入口与唯一清单，域划分也只写在它这一个地方，闸件增减与分域调整都只改它，文档禁另列清单。一次改动同批混触game/与文档面时跑全量档。跑完写回执game/tests/.gates/receipt.json（含domain字段），合回时由 worktree-guard 按 diff 路径推出该验哪个域再校验回执（五况拦截细则见 process-conventions §3.10） - 单件直跑（调试期最窄确认用，不构成验收）：系统级断言面
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，报告与原始数据落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/— 游戏工程本体（代码 + smoke/ 冒烟 + tests/ 单元集成）sim-data/— 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑tools/— python 工具脚本；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 铁律、五段流水线、批次清单、测试两入口与 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 文档。冲突须显式提出，禁默默改值 |
| 现在做什么 / 待办与待裁 | 根 roadmap.md 顶部「当前位」节＋迭代总表六列 · 待办唯一登记处 待办清单.md · 批次过程与结论查 git 提交信息与 reports/ |
硬性红线（勿违反；操作细则在 process-conventions.md 与各规约）
- 主工作区禁止直接改动与提交——一切改动走独立 worktree（豁免：
.zcode/与.qoder/两份本机 harness 配置，实测均不入 git） - 仓库根禁止设会话状态文件（
active.md已废除）——现状看 roadmap「当前位」，待办看待办清单，过程看 git 提交信息，产出物看reports/；任何文档禁止另设「当前状态快照」节，两处记同一件事必然漂移（细则见 doc-conventions 第 10 节） - 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测
- 交付前验收 = 跑
tools/run_all_gates.sh按改动域全绿（唯一入口、唯一闸清单、唯一域划分，禁在文档另列）；合回 master 由 worktree-guard 按 diff 推域校验回执强制（process-conventions §3） - 两类批——迭代批（代码实现，
/iter发射）：禁写design/整个目录与两份根流程清单（待办清单.md/体验验证清单.md）（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批禁止顺手改；产出物只准写reports/；批末只跑代码域闸。非迭代批（工具/规则/文档改动）：不占 roadmap 迭代号，按改动域跑闸。文档内容的落地走五段流水线相应段（文档设计段入口=doc-design 技能；登记条目格式由流水线闸强制） - 五段流水线铁律——一切工作按「登记 → 文档设计／美术设计 → 写需求卡片 → 迭代编排 → 实现」推进，段间不自动流转、每段转进由用户发令；编入迭代的卡片必须设计闭合＋零待裁点，流水线闸
tools/pipeline_gate.py强制（已注册进 run_all_gates.sh 文档域）；实现段零裁断——卡片没写清=上游缺陷，停该卡退回上游，禁内联求裁（process-conventions §2，格式与状态机=doc-conventions §12） - MC/模拟：无数值改动零跑；档位硬闸见
sim-data/README.md「MC 采集档位表」，一档只能由用户发起 - 闸机轮次纪律：新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册（process-conventions §6）
- 变异验证——新增/改写验收函数必须变异变红才算验收成立；无变异红记录只写「已实现，拦截能力未证」（test-conventions §6）
- 验收闭合——每个需求点与每个行为改动都要有从真实入口进入的验收断言，撤销该改动能让对应断言变红；禁删断言/放宽阈值换绿；合回前独立验收审计未过则禁止合并（细则=test-conventions §9＋iter 技能第 5 步）
- 规则评估——没在真实任务上评估过的规则修订，不算完成。
- 中间产物吸收即死——结论先吸收进权威文档、未决先迁待办清单，文件即删且永不提交（doc-conventions 第 11 节）
- 禁写变更记录——文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁写「本版改了哪些条款」式逐版本叙述与
# 2026-xx-xx 缺陷修批——式行内修订注记；沿革只进 git commit log。版本号可作文档现行身份标记留在文首状态行与正文引用中（doc-conventions 第 5 节，机检闸 gdd_lint R4 反转拦截） - 用语红线——一切对用户输出禁自造黑话，需要作者解释的词必须展开成完整白话句（doc-conventions 第 4 节三形态表）
- 呈报四问（读后自检制）——向用户首次完整呈报一件事（需求／缺陷／方案／结论）时，写完先自查：读者只读这一段，能否不看原文答出——① 现状差在哪：现在是什么、缺什么；② 你建议做什么：做完预期什么效果、会动到哪些面；③ 为什么选这个做法：考虑过、放弃过哪些别的路；④ 做完怎么验证：哪些还有把握不足。哪问答不出就补哪问，禁靠加小标题凑数；三句话能说清的小件合并为三句：现状一句、建议与验证一句、没把握的一句；后续追问与推进不必重跑全框架
- 真人检测只登记不阻塞——登记进体验验证清单/实现报告即完成义务，禁以等目检为停工理由或当作合回的前置条件
- 文件头 =
##文档注释，介绍本模块是什么；禁写变更叙事（改动史查 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 节）