docs: 文档写作规范成文并补引用纪律，行动经济与教学引导系统文档成文

CLAUDE.md

@@ -21,6 +21,7 @@
 - `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（评审确立，勿违反）
 
@@ -30,11 +31,7 @@
 - **fail-fast**：数据校验错误一律致命中止，无软回退（D2 Rule 6）
 - **spec-AC 一致性**：规约与验收标准不得在同一输入上给出不同答案——D2 两轮评审确立的阻塞标准，所有 GDD 同尺度
 - GDD 评审纪律：`/design-review` 必须在独立会话跑（与 `/design-system` 隔离）
-- **用语纪律（2026-09-09 评审确立，勿违反）**：GDD、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语（反例："非雾腿""双闸"）。只能使用（a）人人可懂的直白语言，或（b）游戏行业通用专业术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。需要指代新概念时，用直白描述性短语（正例："剔除雾格后的可推理率""两项达标判据"）；确需给新概念命名时，首次出现处必须附一句白话定义并登记 `design/registry` 术语条目——不得让读者猜测比喻含义。**（2026-09-14 增补）自造词的唯一例外 = 玩家在游戏里也会看到的专属名词**（道具名、界面用语，如"显影尘""探巢摆钟"）——文档内部的机制概念不得造词，一律直白描述。
-- **文档形态纪律（2026-09-13 评审确立，勿违反）**：GDD 及一切设计文档遵循 lean 格式——模板 `.claude/docs/templates/game-design-document.md`，门禁 `tools/gdd_lint.py`（新文档与每次修订后必须 PASS）。六条硬规则：① 散文段 ≤240 字，全文表格占比 ≥60%；② 枚举、数值边界、边界情况、依赖一律表格；流程一律字符画（代码块）或出口分发表，禁止散文描述步骤；③ 体验锚点用关键词（支柱 | 关键词 | 机制承诺 表），禁长篇情绪描述；④ 公式**结论先行**——先一行加粗结论，再"推导"小标题放公式代码块、Variables 表与验算表，公式本体必须保留（推理证明不可省）；⑤ 修订历史只写文末「版本历史」表——正文禁止 ~~删除线~~、"（作废）"、"（日期+评审/修订/拍板）"式注记；义务台账、拍板记录、registry 回执等审计元数据入 `design/registry` 或附录，不入正文。评审发现写 review log，正文只收干净的现行规则；⑥ **规则两段式：人话先行、举证在后（可读性承重条款）**：核心规则/玩法/系统按两段写——**人话阶段**：作用于哪个系统、在什么情况下、谁触发、触发后发生什么；效果与情况用枚举表列出；**举证阶段**：逐效果给出计算方法/公式（就地给出或指向公式节）；纯流程规则明写"无计算"。读者测试：没读过本文档的人能否回答"管的是谁？什么时候？会发生什么？"——答不出就重写。规则名禁止纯名词短语（反例："获取路由""编排被动性"）；编号引用（AC-x / F-x / EC-x / 义务×）不进人话，只进举证与依据。**（2026-09-14 用户拍板增补）**：R2 表格占比阈值已由 60% 放宽至 30%（防铺开职责由 R1/R9 承担）——既有 13 份 GDD 按旧口径继续成立，不回改。
-- **两件套纪律（2026-09-14 用户拍板，新系统 GDD 即日生效）**：新系统设计文档写一对——`design/gdd/[system].md` 只装**结论**（设计目的/系统范围[负责·不负责]/核心循环/领域章节×2–6/依赖与输出/P0 最小闭环/P1·P2 后置表/调参表/验收标准/版本历史），**设计推演**（候选取舍、机理、为什么）装 `design/gdd/analysis/[system].md`（每个问题四段：广度分析→深度分析→综合判断；不入 lint 门禁，钩子豁免）。判据：正文出现超过一行的"为什么"即违规——挪 analysis。优先级诚实条款：**后置 ≠ 删除**，复活后置行 = 修订 GDD，禁止静默加回。数值默认后置：正文定规则/域/单位，平衡值进数据表（provisional 必须标注）。既有 13 份 GDD 维持 lean v1 形态不回改；模板 v2 与 analysis 骨架见 `.claude/docs/templates/game-design-document.md`。
-⑦ **树形文档体系与一页纸节点（导航承重条款）**：全部设计文档构成一棵树——根索引 `systems-index` 承载整棵树的形状与每个节点的一句话概要，读者靠索引决定进入哪个节点，索引必须随文档增删同步维护。树内每个节点（GDD 内的每一节、每条规则、每张公式）内容控制在一页纸内（直接内容 ≤80 行，`tools/gdd_lint.py` R9 强制）：装不下就拆成子节点，禁止铺开；节点内顺序 = 人话 → 表格枚举 → 字符流程图 → 举证公式。**session-state 条目纪律**：`production/session-state/active.md` 每条进度 ≤3 行（粗体键 + 短句），详情一律外链到对应 GDD/报告/日志，禁止把定稿摘要、义务清单、回写清单整段塞进条目。
-- **新骨架过渡口径（2026-09-14 用户拍板）**：`design/gdd/` 现行循环式新骨架**不适用**上方 lean 形态纪律（`gdd_lint` 门禁）、两件套纪律与"根索引 = systems-index"条款——那几条仅约束归档体系（`design/archive/gdd-2026-09-14/`，只读）的解读与引用。新骨架纪律三条：① **可读性优先**——人话先行、节点一页纸以内，不过 lint；② **文档增删必须同步根索引 `02-系统清单.md`**；③ 每个子系统一份文档，**不建 analysis 推演件**。`gdd_lint` 的 PostToolUse 钩子同批停用（工具本体留在 `tools/` 备查）。已锁数值事实源不变：`design/registry/entities.yaml` 与 `data/tables/`；registry 中 owner 指向旧 GDD 的条目改指归档路径，待对应新 systems 文档定稿后再逐条改指新文档。
+- **文档写作规范（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 用户拍板成文）
 

design/gdd/systems/排雷循环/行动经济.md

@@ -1,3 +1,213 @@
 # 行动经济
 
+> 一句话：每轮行动点怎么花、停手与刷新的代价
+> 状态：已定稿（自旧体系迁移）
 > 旧版参考：../../../archive/gdd-2026-09-14/a3-action-economy.md
+
+## 设计目的
+
+每场战斗里，玩家真正在花的钱只有一种：行动点（AP）。行动经济就是这本账——每轮发给你固定的行动点，挖格、插旗、拔旗各花 1 点，花完这一轮就结束了。没有这本账，"挖这一格值不值"就没有统一的价格语言。
+
+它还要给"我不想赌了"一个体面的出口：主动停手能把剩余行动点 1:1 存进储备池，攒够了可以当场换掉整张雷图。推理本身不收钱——连锁展开免费——花钱的只是"兑现"这个动作。
+
+## 系统范围
+
+边界这样划：行动经济只管"多少钱、怎么扣、什么时候算一轮结束"。棋盘上这个动作合不合法、执行后格子变成什么样，归排雷玩法；扣完钱之后收益怎么兑现成战斗效果，归战斗结算。行动经济自身是个纯账本：零随机、零画面、零教学内容。
+
+负责：
+
+| 负责 | 说明 |
+|---|---|
+| 行动点账本 | 全项目唯一扣减入口：余量检查、扣费、结束判定在同一个原子事务里完成，不允许双重折算 |
+| 统一价目 | 挖 / 插旗 / 拔旗各 1 点；移动与连锁展开免费（冻结项，不参与调参） |
+| 轮次结束仲裁 | 清图、停手、耗尽三种结束方式同时成立时，按固定优先级只裁出一个赢家 |
+| 储备行动点池 | 停手进账、刷新支出、战斗结束清零（详见核心规则） |
+| 对下游的经济契约 | 五条契约约束收益兑现侧，由战斗结算负责对账验收 |
+
+不负责：
+
+| 不负责 | 归谁 |
+|---|---|
+| 棋盘规则与动作执行 | [排雷玩法](排雷玩法.md) |
+| 轮次编排与结算兑现 | [战斗结算](../战斗循环/战斗结算.md) |
+| 奖励内容与档位 | [奖励道具经济](../战斗循环/奖励道具经济.md) |
+| 数值表本体与读取机制 | [数据配置](../表现与支撑/数据配置.md)（本系统只回填自己的表） |
+| 界面呈现 | [HUD 框架](../表现与支撑/HUD框架.md) |
+| 教学口径的呈现 | [教学引导](../表现与支撑/教学引导.md) |
+
+## 在核心循环中的位置
+
+```
+扫雷阶段：玩家每个动作 ──(过账本扣费)──▶ 行动经济 ──(轮末输出：怎么结束的 + 换不换图)──▶ 战斗结算 ──▶ 冒险推进
+```
+
+行动经济站在"扫雷"这一段。它的上游是玩家在棋盘上的每个动作，下游是轮末结算：它不决定你能做什么，只决定每件事花多少、这一轮什么时候算完。
+
+## 核心规则
+
+### 每轮预算与价目
+
+每轮开始时，行动点被硬重置为表值（现行默认 8 点）——上一轮没用完的不累积、不结转。储备行动点（RAP，停手攒下来的池子）正好相反：开轮时原样保留，一分不动。
+
+花钱的动作只有三种，价格一样：
+
+| 动作 | 花费 | 说明 |
+|---|---|---|
+| 挖开格 | 1 点 | 只能挖小人 8 向相邻的格子；若触发连锁展开（flood fill 式整片翻开），连锁翻开的部分免费，且计入清图进度 |
+| 插旗 | 1 点 | 同样限相邻格。旗只是棋盘上的标记，不是背包里的实物，想用多少有多少——它的稀缺性完全由"要花 1 点行动点"承载 |
+| 拔旗 | 1 点 | 与插旗对称：移除标记，无任何返还 |
+
+不花钱的有两件事：移动小人（点已翻开的格子走过去，仅限已探明区域）和连锁展开。这两项免费是冻结设计，服务"边缘探索不心疼"的氛围，不是经济杠杆。
+
+本作明确不做经典扫雷的 chord（双击数字格一键翻开周围）。每一格的兑现都必须花行动点，一键开一片会让行动点预算失去意义。
+
+### 轮次结束：三种出口与仲裁
+
+一轮在以下任一时刻结束：行动点扣到 0 的瞬间、玩家主动停手、全部安全格开完（含连锁翻开的格）。扣到 0 的那一刻轮次立即结束——不存在"0 点还能再操作一下"的窗口。
+
+如果几种结束方式在同一瞬间同时成立（典型例子：最后 1 点行动点挖开了最后一个安全格），按固定优先级只裁一个赢家，与事件到达顺序无关：
+
+| 结束方式 | 优先级 | 胜出后发生什么 |
+|---|---|---|
+| 清图 | 最高 | 剩余行动点清零（不进储备池），发清图奖励，下一轮换一张新图 |
+| 停手 | 居中 | 剩余行动点 1:1 存入储备池，下一轮继续同一张图 |
+| 耗尽 | 最低 | 剩余行动点恒为 0（实现层断言兜底），下一轮继续同一张图 |
+
+清图优先于耗尽是有意的：否则"耗尽优先"的实现会把清图的高光时刻结算成最差结局，训练玩家永远留着最后一格不敢挖。
+
+轮次结束时，账本只向下游输出一条两字段的消息——这一轮怎么结束的、下一轮要不要换图的建议。权威的换图指令由战斗结算之后回发；建议仅是编排参考。消息里不夹带任何折算数值，因为收益兑现全部是具体的战斗效果，不存在抽象点数。
+
+### 停手与储备行动点
+
+停手是玩家在挖掘期任意时刻的主动决定：立即结束本轮，剩余行动点按 1:1 原值存入储备池——没有乘数、没有加成。图没开完，下一轮接着在同一张图上挖。停手不是收入来源，而是纯粹的风险管理工具：它买到的是"退出权"，不是战斗收益。停手意图经排雷玩法的批次提交入口进入账本（保证单一结算序），由账本仲裁后自行外发轮次结束消息。
+
+储备池的生命周期以一场战斗为界：战斗内跨轮次、跨雷图一直累积；战斗结束立刻清零。清零必须在界面上可见，防止玩家觉得"攒的钱凭空没了"。MVP 阶段储备池没有上限。
+
+### 挖掘期刷新：花储备换新图
+
+储备池唯一的支出是刷新雷图。玩家在挖掘期经界面入口发起，储备值不低于刷新门槛（默认 8 点）时扣费，当场换一张新图继续挖。注意刷新不终结这一轮：行动点不重置、本轮剩余行动点保留；但换来的新图不发清图奖励（它又不是清图），旧图上的旗随旧图一起失效（插旗花的钱不退）。
+
+每轮最多刷新 2 次（轮内计数，开轮重置），没有冷却，每次独立检查门槛并扣费。禁止"攒满就自动刷"——刷新永远是玩家的决定。
+
+停手与刷新合起来构成这本账的基线节拍：满行动点一轮停手，正好攒够一次刷新。
+
+### 标中旗的兑付约束
+
+插旗标中了巢穴，收益在当轮结算兑付（标中 = 巢穴被控制、里面怪物被削弱）。兑付受五条硬约束，核心思想是"认雷不认旗"：
+
+| 约束 | 含义 |
+|---|---|
+| 一次性 | 每颗雷在一场战斗内至多兑付一次，资格随首次兑付消费 |
+| 当轮结算 | 旗只是当轮兑付的载体，不囤积到以后 |
+| 资格认雷格实例 | 拔掉重插同一格，不恢复已消费的资格——堵死"每轮花 2 点重插刷收益"的农场 |
+| 不逐轮重复 | 同一颗雷的收益不会每轮反复发 |
+| 换图重置 | 新图的雷是新实例，资格自然重来 |
+
+### 收益直兑与五条经济契约
+
+扫雷侧的全部收益都以战斗效果直接兑现：挖开安全格给主角加增益、标中旗给怪物加减益、惊动巢穴给敌方上增益、清图发奖励。不存在中间货币、不存在折算乘数——折算公式根本不存在。
+
+这本账对下游立了五条经济契约，保证"推理的收益大于盲赌的代价"这条底线在数值上闭合：
+
+1. **单一当量**：所有收益来源用同一张效果对照表归一换算，不允许分源改率。
+2. **标中旗锚**：标中旗的减益档位必须严格高于最低档安全格增益——否则没人愿意插旗。
+3. **挖掘风险不等式**：挖一格的期望收益必须大于期望代价。
+4. **清图奖励大于零**，并预留按图类型差异化分支的结构位。
+5. **清图支配性**：推到底清图的期望收益，不低于"确定格挖完就弃图刷新"的期望收益——否则清图玩法会被刷新策略淘汰。
+
+**结论**：五条契约由战斗结算作为唯一对账责任方闭合验收；概率侧由棋盘生成的可推理率参数锚定，惩罚侧由敌人系统的惩罚上限表锚定。
+
+推导：
+
+```
+条款 3（挖掘决策健康不等式）：
+  P(安全) × 增益当量下界  >  P(雷) × 敌方增益当量上界
+
+条款 5（清图支配性）：
+  清图奖励当量  ≥  弃图节省的期望雷险当量 + 轮数差 × 敌方结算强度当量
+```
+
+| 变量 | 含义 | 锚定来源 |
+|---|---|---|
+| P(安全) / P(雷) | 挖掘目标格为安全格 / 为雷的概率 | [棋盘生成](棋盘生成.md)的可推理率参数 |
+| 增益当量下界 | 最低档安全格增益换算值 | 战斗结算的效果对照表 |
+| 敌方增益当量上界 | 踩雷惩罚的换算上限 | [敌人系统](../战斗循环/敌人系统.md)的惩罚上限表 |
+| 清图奖励当量 | 清图奖励的换算值 | [奖励道具经济](../战斗循环/奖励道具经济.md) |
+
+### 配置纪律
+
+全部数值（每轮几点、每个动作花多少、刷新门槛、每轮刷新上限）都存配置表、经统一读取口读入，代码里零玩法数值字面量。本系统零随机、无随机数流。改数值 = 改表回填，不动代码；表不变，行为逐位相同。
+
+## 依赖与输出
+
+| 方向 | 系统 | 接口要点 |
+|---|---|---|
+| 上游 | [数据配置](../表现与支撑/数据配置.md) | 配置表 schema 与类型化读取；本系统是该表的回填责任方 |
+| 上游 | [排雷玩法](排雷玩法.md) | 挖/插/拔的调用方：只判棋盘合法性，扣费必须过账本 |
+| 下游 | [战斗结算](../战斗循环/战斗结算.md) | 轮末两字段消息的接收方；回发换图指令与战斗结束信号；五条经济契约的对账责任方 |
+| 下游 | [奖励道具经济](../战斗循环/奖励道具经济.md) | 清图奖励内容与图类型差异化插槽的归口 |
+| 下游 | [HUD 框架](../表现与支撑/HUD框架.md) | 行动点与储备池常显；刷新入口；清零反馈；动作被拒原因的双源呈现（棋盘非法 vs 资源不足） |
+| 下游 | [教学引导](../表现与支撑/教学引导.md) | 价目与"储备池战斗结束清零"的教学口径来源 |
+
+账本对外是一组封闭的布尔入口（开轮 / 挖 / 插旗 / 拔旗 / 停手 / 刷新 / 结算完成通知 / 战斗结束通知）：受理返回真、拒绝返回假且状态不变。相位非法的拒绝附带调试诊断，但不致命中止——进程致命只留给数据配置通道。
+
+## P0 最小闭环
+
+1. 战斗结算发开轮通知：行动点硬重置为表值，储备池不动，进入可操作状态。
+2. 玩家挖 / 插旗 / 拔旗，每个动作过账本扣 1 点；连锁展开免费且计入清图进度。
+3. 玩家可随时停手（剩余行动点 1:1 入库），或储备够门槛时刷新换图（每轮至多 2 次）。
+4. 结束路径在账本事务内仲裁，只裁一个赢家。
+5. 轮末两字段消息发给战斗结算，后者把收益逐行兑现进结算明细。
+6. 战斗结束信号到达：储备池清零，账本休眠，等下一场战斗的开轮通知。
+
+## P1 / P2 后置
+
+| 优先级 | 内容 | 后置原因 |
+|---|---|---|
+| P1 | 储备池跨战斗携带开关 | 现行每场战斗清零（防滚雪球）；是否解禁连刷策略，等实测数据说话 |
+| P1 | 清图奖励按图类型差异化 | 结构位已预留，内容归奖励道具经济的表设计 |
+| P2 | 地形成本修饰（不同格子不同价） | MVP 价目均匀是有意简化；钩子已预留，待非雾地形变异定稿 |
+| P2 | 行动点耗尽的教学提示 | 规则已定"0 点即收轮"；若新手困惑，加提示不改规则，归教学引导 |
+
+## 调参表
+
+配置表为单行全局表；已锁数值以 [registry 的 action_economy 条目](../../../registry/entities.yaml) 为准。
+
+| 参数 | 域 | 现行值 | 说明 |
+|---|---|---|---|
+| ap_per_round | int [1, 32] | 8 | 每轮行动点；兼作停手转存的规模旋钮 |
+| dig_ap_cost | int [1, 8] | 1 | 挖单格成本（下限 1：为 0 则预算系统失效） |
+| flag_place_ap_cost | int [0, 8] | 1 | 插旗成本 |
+| flag_pull_ap_cost | int [0, 8] | 1 | 拔旗成本 |
+| rap_refresh_cost | int [1, 64] | 8 | 刷新门槛；默认等于每轮预算，构成"满预算停手 = 恰好一刷"的基线节拍 |
+| move_ap_cost | int | 0 | 移动免费——冻结，非调参项 |
+| chain_ap_cost | int | 0 | 连锁免费——冻结，非调参项 |
+| refresh_cap_per_round | int | 2（provisional，结构位预留） | 每轮刷新上限，开轮重置计数 |
+
+跨字段校验：任一动作成本不得超过每轮预算，违反即加载期致命（fail-fast）。各域上界（8 / 64）是 MVP 量级护栏而非推导界，随调参需要修订。
+
+## 验收标准
+
+- 开轮硬重置：新一轮开始，行动点回到表值；储备池保持上轮结束时的值不变。
+- 连锁免费：一次挖掘触发连锁翻开任意多格，扣费恒为 1 点，且连锁格计入清图判定。
+- 耗尽即收轮：行动点扣到 0 的瞬间轮次结束，此后一切动作请求被拒绝且状态不变。
+- 仲裁唯一：最后 1 点行动点挖开最后一个安全格时，判清图（剩余清零 + 换图 + 清图奖励），不判耗尽；输出恰一条。
+- 停手 1:1：剩余 3 点停手，储备池加 3，下轮同图继续。
+- 刷新规则：储备不足时刷新被拒绝且状态不变；同一轮第 3 次刷新被拒绝；刷新不重置行动点、不发清图奖励、旧图上的旗失效。
+- 储备清零：战斗结束信号到达后储备池归 0，账本进入休眠。
+- 跨字段校验：任一动作成本配置超过每轮预算时，加载期致命中止。
+- 零随机：同一动作序列驱动两个独立账本实例，轮次结束记录与储备轨迹逐项相同。
+- 表实一致：配置表字段与 registry `action_economy` 条目逐字段一致。
+
+## 待拍板
+
+| 条目 | 内容 |
+|---|---|
+| 拔旗定价复核 | 拔旗 1 点是否为正确定价，旧体系留了实测义务（原型补丁验证），至今未执行 |
+| 刷新经济性监控 | 挖掘期当场刷新无结算发生，"弃图率 / 刷新率"预警阈值如何与调参联动复核，未定 |
+
+## 版本历史
+
+| 版本 | 日期 | 改动 |
+|---|---|---|
+| v0.1 | 2026-09-14 | 自归档 GDD 压缩改写 |

design/gdd/systems/表现与支撑/教学引导.md

@@ -1,3 +1,121 @@
 # 教学引导
 
+> 一句话：新手教学与提示
+> 状态：范围草案（待设计）
 > 旧版参考：../../../archive/gdd-2026-09-14/systems-index.md（旧体系未单独成文，旧编号 D5）
+
+## 设计目的
+
+这游戏有两层玩法——扫雷推理和自动战斗——而"扫雷攒下的因，逐行兑现成战斗的果"这条因果线，是新手最容易断掉的一环。教学引导的任务，就是让玩家不读说明书也能自己接上这条线：学会挖、插旗、移动三个基本动作，看懂结算明细在回答他刚才的哪一步棋，知道"停手"和"刷新"这两个风险管理出口的存在。
+
+## 系统范围
+
+边界这样划：教学引导只管"教什么、什么时候教"。承载教学的界面设施——toast 提示条（棋盘区上缘浮出的非模态提示，自动消退、不劫持输入）和图例面板（可随时回看的模态覆盖层）——归 HUD 框架所有；本系统是这两个设施的内容供应方。被教学的规则本体永远归各系统自己的文档，本文件只引用、不重新定义。
+
+负责：
+
+| 负责 | 说明 |
+|---|---|
+| 教学条目清单 | 教哪些事、每条归属哪个上游系统的规则 |
+| 触发条件与频次 | 每条提示什么时候出现、出现几次（如"每场冒险至多一次"） |
+| 两层循环的教学顺序 | 先教扫雷还是先教读结算、怎么把因果关系讲明白 |
+
+不负责：
+
+| 不负责 | 归谁 |
+|---|---|
+| toast 与图例面板的呈现机制 | [HUD 框架](HUD框架.md) |
+| 被教学规则的本体定义 | 各系统文档 |
+| 文案的多语言生产 | [设置与本地化](设置与本地化.md) |
+
+## 在核心循环中的位置
+
+```
+扫雷段（教三动作与价目）──▶ 结算段（教归因读法）──▶ 冒险段（教血账与恢复）
+        教学不是循环里的一段，而是贴在循环各段上的提示层
+```
+
+教学引导不打断循环的节奏：它在每个阶段第一次遇到关键机制时贴一条轻提示，玩家忘了可以随时翻图例面板。
+
+## 核心规则（已确证的范围与约束）
+
+教学的具体形态未定（见待设计问题清单）。本节只收从现行设计能确证的边界与约束。
+
+### 承载设施已定
+
+HUD 框架定稿时已为教学留好两个承载位，本系统的内容将来装进这两个容器：
+
+- **toast 提示条**：用于"第一次遇到"类提示。非模态、自动消退（约 2.5 秒）、不打断挖掘操作。
+- **图例面板**：用于常量性知识。模态覆盖层，恒在、不设解锁门、可随时回看。
+
+### 已登记的教学条目
+
+以下条目在上游系统定稿时已登记为教学或提示义务，构成本系统的内容输入：
+
+| 条目 | 来源 | 要教的事 |
+|---|---|---|
+| 行动点价目 | [行动经济](../排雷循环/行动经济.md) | 挖 / 插旗 / 拔旗各花多少、移动与连锁免费 |
+| 储备池清零提示 | [行动经济](../排雷循环/行动经济.md) | 必须说清"储备行动点在战斗结束时清零"，防止"攒的钱凭空没了"的误读 |
+| chord 不存在的首遇提示 | [HUD 框架](HUD框架.md)（承接排雷玩法的呈现义务） | 经典扫雷玩家会习惯性双击数字格——本作没有 chord，点数字格 = 移动小人。每场冒险提示一次，非模态 |
+| 挖非相邻格的首次提示 | [HUD 框架](HUD框架.md) | 挖与旗都限小人 8 向相邻的格子，第一次越界操作时提示 |
+| 增益叠层节奏 | [增益状态](../战斗循环/增益状态.md) | "同一轮拿满优于跨轮慢慢叠"——增益有结算次数衰减，教学要传达这个节奏 |
+| 库存关卡末清空 | [奖励道具经济](../战斗循环/奖励道具经济.md) | 道具库存随关卡结束清空，需有反馈与教学条目 |
+
+### 内容原则
+
+- **整体后置**：教学引导是 MVP 之后的打磨项（见 [不做清单](../../05-不做清单.md)：先验证核心循环，再谈好听好看），里程碑定位 Alpha。
+- **一次性提示**：首次触发类提示每场冒险至多出现一次，不反复轰炸。
+- **只教规则，不替玩家玩**：教学解释规则与因果，不提供自动操作或"最优解"提示。
+
+## 依赖与输出
+
+| 方向 | 系统 | 接口要点 |
+|---|---|---|
+| 上游 | [排雷玩法](../排雷循环/排雷玩法.md) | 三动作规则与事件——教学时机的数据源 |
+| 上游 | [行动经济](../排雷循环/行动经济.md) | 价目与停手 / 刷新口径——教学内容的权威来源 |
+| 上游 | [战斗结算](../战斗循环/战斗结算.md) | 结算明细的归因读法——"教玩家读结算"的素材 |
+| 上游 | [HUD 框架](HUD框架.md) | toast 与图例面板两个承载位 |
+| 下游 | [设置与本地化](设置与本地化.md) | 教学文案的多语言生产 |
+
+## P0 最小闭环
+
+教学引导整体后置，MVP 不要求最小闭环。Alpha 期的最小集合候选：三动作教学 + 行动点价目 + "扫雷的因 = 战斗的果"归因提示 + chord 首遇提示。
+
+## P1 / P2 后置
+
+| 优先级 | 内容 | 后置原因 |
+|---|---|---|
+| P1 | 教学引导全体 | MVP 打磨项排后（不做清单），里程碑 Alpha |
+| P2 | 可重看的教学手册（图例面板兼任） | 待教学形态定稿后评估 |
+
+## 调参表
+
+暂无本系统自有的参数。toast 停留时长等呈现常量归 [HUD 框架](HUD框架.md) 的调参表。
+
+## 验收标准
+
+待设计。方向性判据（供未来定稿参考）：
+
+- 玩家不看任何外部说明，能完成挖 / 插旗 / 移动三个动作，并说出每个动作花多少行动点。
+- 玩家能在结算明细里指出至少一行收益来自他刚才的哪一步操作。
+- 首次提示不重复轰炸：同一提示每场冒险至多出现一次。
+
+## 待拍板
+
+| 条目 | 内容 |
+|---|---|
+| 雾格失义：雾类教学条目 | 原设计的图例条目"迷雾 = 无雷盲区"与雾格首遇三要点提示，随雾格机制移除整体失义，不迁入。未来非雾地形变异（岩浆 / 冰冻等）定稿时，需要补对应的图例条目与首遇提示——届时归[地形变异](../排雷循环/地形变异.md)提出、本系统承接 |
+
+## 待设计问题清单
+
+1. 教学形态：线性开局教程，还是全部走情景触发式提示？
+2. 因果教学顺序：先教扫雷操作，还是先教读结算明细？两者如何衔接？
+3. 图例面板的条目全集与分组方式（雾条目删除后剩什么结构）。
+4. 教学文案的定稿权归属，以及与本地化流程的分工。
+5. 是否提供"再教一次"的入口（图例面板是否兼任手册）。
+
+## 版本历史
+
+| 版本 | 日期 | 改动 |
+|---|---|---|
+| v0.1 | 2026-09-14 | 自归档线索整合为范围草案（旧体系未单独成文） |

docs/doc-conventions.md

@@ -0,0 +1,136 @@
+# 文档写作规范（写文档前必读）
+
+> **地位**：本文是本项目文档写作的规范权威，与 `docs/code-conventions.md`（代码规范）对等——写代码前必读代码规范，写文档前必读本文。CLAUDE.md 只保留摘要与指针，细则以本文为准。
+> **适用范围**：`design/` 下一切现行文档（顶层文档、`systems/` 系统文档、`design/ux/`、`design/art/`、`design/research/`）与 `production/` 会话记录；`docs/` 其他说明文档参照执行。
+> **成文**：2026-09-14。整合来源：用语纪律（2026-09-09 评审确立）· 文档形态纪律（2026-09-13 评审确立）· 两件套与树形文档体系纪律（2026-09-14 用户拍板）· 新骨架过渡口径（2026-09-14 用户拍板）· 可读性纪律（2026-09-14 用户提出）· 引用纪律（2026-09-14 用户提出）。
+
+## 0. 总纲
+
+文档是写给人看的：先让人读懂，再谈结构整齐。默认读者没有读过项目历史——可能是半年后的你自己，也可能是未来的协作者。下面所有规则都为这个读者服务。
+
+## 1. 可读性第一（最高纪律）
+
+**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——
+
+1. 这节管的是谁/什么？
+2. 在什么情况下？
+3. 会发生什么？
+
+答不出来，就重写这一节，而不是给看不懂的地方补注释。
+
+**与旧体系门禁的关系**：旧体系的 lean 格式六条硬规则与 `tools/gdd_lint.py` 门禁已随 2026-09-14 归档停用（PostToolUse 钩子同批停用，工具本体留 `tools/` 备查），此后仅用于解读 `design/archive/` 里的旧文档（解读时注意其表格占比口径为 30%，2026-09-14 由 60% 放宽）。现行文档不跑 lint；可读性是唯一的内容质量门。旧模板文件留档 `.claude/docs/templates/` 备查。
+
+## 2. 白话写作规则
+
+写文档像向朋友当面解释你的游戏。具体做法：
+
+1. **完整句子优先**：用完整的句子把话说完；一段只说一件事，长句拆短句。
+2. **禁止碎片笔记体**：正文不得写压缩碎片，不得把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不得使用只有作者自己懂的缩略语。
+3. **每节人话开头**：每个小节的第一段先用白话说清"这是什么、为什么需要它"，然后再展开细节。做到只读各节第一段，就能看懂整篇文档的故事线。
+4. **术语首现即解释**：专业术语或项目概念第一次出现时，用一句话（可以用括号）解释它是什么，之后才允许直接使用。玩家会看到的专属名词（如"显影尘"）同样要说清。
+5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录；正文用直白语言把规则本身说出来。
+6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆——都不是我们要的文档。
+
+## 3. 表达分工：散文、表格、字符画、公式
+
+不同内容用不同载体，各司其职：
+
+| 内容 | 载体 | 纪律 |
+|---|---|---|
+| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |
+| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁止把需要解释的内容塞进单元格让读者自己拼 |
+| 流程、状态流转 | 字符画（代码块） | 禁止用散文逐步描述流程 |
+| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表；公式本体必须保留 |
+| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁止长篇情绪描述 |
+
+节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。
+
+**规则两段式**：核心规则先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法或公式；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。
+
+## 4. 用语纪律（禁自造黑话）
+
+文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语（历史反例："非雾腿""双闸"）。
+
+- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。
+- 需要指代新概念时，用直白的描述性短语（正例："剔除雾格后的可推理率"）。
+- 确需给新概念命名时：首次出现处必须附一句白话定义，并登记 `design/registry` 术语条目——不得让读者猜测比喻含义。
+- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语，如"显影尘""探巢摆钟"）。文档内部的机制概念不得造词。
+
+## 5. 结构纪律
+
+| 规则 | 内容 |
+|---|---|
+| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |
+| 一页纸节点 | 一节、一条规则的内容控制在一页纸内（约 ≤80 行）；装不下就拆节，禁止铺开 |
+| 一系统一文档 | 每个子系统一份设计文档，不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
+| 正文只写现行规则 | 禁止删除线、"（作废）"、"（日期+拍板）"式注记；修订只进文末「版本历史」表；义务台账、拍板记录等审计信息入 `design/registry` 或附录，不入正文 |
+| 后置 ≠ 删除 | P1/P2 后置的内容逐条列出；复活后置项 = 修订文档，禁止静默加回 |
+| 数值纪律 | 正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `data/tables/` 与 `design/registry/entities.yaml` |
+
+## 6. 文档类型与骨架
+
+**顶层六文档**：
+
+| 文档 | 管什么 |
+|---|---|
+| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 |
+| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |
+| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 |
+| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 |
+| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 |
+| `05-不做清单.md` | 明确写：这些我不要 |
+
+**系统文档骨架**（`systems/` 下统一采用）：
+
+| 章节 | 要求 |
+|---|---|
+| 文首引言 | 一句话定位 + 状态（已定稿/范围草案/待设计）+ 旧版参考链接 |
+| 设计目的 | 2-4 句白话，为什么需要这个系统 |
+| 系统范围 | 负责/不负责两张表；表前一段白话说明边界 |
+| 在核心循环中的位置 | 处于哪一段、上下游是谁（字符画一行 + 两句白话） |
+| 核心规则 | 领域章节 ×2–6，每节一页纸 |
+| 依赖与输出 | 上游/下游/对外事件与接口（表格；引用纪律见第 7 节） |
+| P0 最小闭环 / P1·P2 后置 | MVP 最小集合与后置清单 |
+| 调参表 | 参数名/取值域/现行值，provisional 标注 |
+| 验收标准 | 可验证的判据 |
+| 待拍板（可选） | 冲突、缺口、设计变更失义条目 |
+| 版本历史 | 表格 |
+
+**命名**：中文、见名知意（如"游戏概念""棋盘生成"）；禁止 a1_/b1_ 编号前缀；不留纯空目录。
+
+## 7. 引用纪律（跨文档高内聚低耦合）
+
+目标：修改或删除一个概念时，只改它的 owner 文档；引用方最多删掉一个链接。反例对照 = 2026-09-14 雾格删除事故——雾格/迷雾/fog 三名并存、雾机制被织进多份文档的规则正文，导致全仓几十处文字修改与大量事后一致性复查。
+
+| 规则 | 内容 |
+|---|---|
+| 单点定义 | 每个概念只在 owner 文档里定义一次，registry 术语条目登记其规范名 |
+| 规范名唯一 | 正文只准用规范名，禁止别名散开——否则删除时 grep 搜不全 |
+| 引用不转述 | 跨文档引用 = 规范名 + 链接，禁止复述对方的规则细节、公式与数值；若发现自己需要一条规则，那是自己的概念，就地定义 |
+| 引用落到对外承诺 | 跨文档链接只锚到对方文档明示的对外内容（事件、接口、规则条目），不锚其内部细节 |
+| 依赖逐条列出 | 系统文档的「依赖与输出」节逐条列出本系统依赖的他人概念（规范名 + 链接）——这份清单就是删除概念时的影响面清单 |
+| 引用必登记反向边 | 引用他系统概念时，在被引方的 registry 条目 `referenced_by` 里登记——影响面靠它机械列出，不靠全仓搜 |
+| 链接断了也好读 | 引用处的句子在链接失效后仍通顺完整（写"变异规则见《地形变异》"，不把半截语义挂在链接里） |
+
+**引用格式**：一律 Markdown 相对链接，指向文件、必要时带节锚点（例：`[地形变异 · 变异类型](systems/排雷循环/地形变异.md#变异类型)`）——机械可查，死链可被工具检出。
+
+**删除概念 SOP**：① 查 registry 该条目的 `referenced_by`，得到影响面清单 → ② owner 文档删除概念 → ③ 纯引用方删链接即完事；机制被织入对方规则的，按清单逐处修订 → ④ 收尾跑一遍死链检查，全绿即干净。
+
+**诚实边界**：机制耦合无法靠删链接消灭——别人的规则真的因你的概念而改变时，改内容不可避免。引用纪律保证的是：这类修改有一份现成清单（反向边 + 依赖节），不用事后全仓搜索。
+
+## 8. 归档与事实源
+
+- `design/archive/gdd-2026-09-14/` 是旧版 GDD 体系的只读归档：不维护、不修改，**禁止作为事实引用**。
+- 旧文档里的概念写进现行文档时，必须翻译成现行术语与现行决策口径（例：雾格已从设计中移除，不得作为现行机制引用）。
+- registry 中 owner 仍指向旧 GDD 路径的条目，在对应新系统文档定稿后逐条改指新路径。
+
+## 9. 会话记录纪律
+
+`production/session-state/active.md` 每条进度 ≤3 行（粗体键 + 短句）；详情一律外链到对应文档或报告，禁止把定稿摘要、义务清单整段塞进条目。
+
+## 版本历史
+
+| 版本 | 日期 | 说明 |
+|---|---|---|
+| v1 | 2026-09-14 | 首版成文：整合用语纪律、文档形态纪律、两件套与树形文档体系、新骨架过渡口径，新增可读性第一纪律与系统文档骨架 |
+| v2 | 2026-09-14 | 新增第 7 节引用纪律（跨文档高内聚低耦合：单点定义 / 规范名唯一 / 引用不转述 / 反向边登记 / 删除概念 SOP），原 7/8 节顺延为 8/9 |

production/session-state/active.md

@@ -127,3 +127,5 @@ D2 数据配置 → A3 行动经济 → A4 地形变异 → B3 增益状态 →
 46. **GDD 体系重构（2026-09-14，用户拍板批）**：旧 GDD 体系整体封存为 `design/archive/gdd-2026-09-14/`（只读参考、不作事实引用，两个 legacy 子目录不保留）；`design/gdd/` 原位重建循环式新骨架——6 份顶层文档 + `systems/` 四循环（排雷/战斗/冒险/表现与支撑）20 份子系统占位文档，根索引 = `02-系统清单.md`（文档增删必须同步）。雾格已从设计中移除，地形变异未来范围只覆盖非雾变异（待定）。
 
 47. **新骨架 00–05 成文 + 全仓旧路径清偿（2026-09-14，用户逐份审阅批）**：00 游戏概念 / 01 核心循环 / 03 内容规模 / 04 美术音频方向 / 05 不做清单 成文（子 agent 起草、用户审阅定稿，02 索引已随骨架建立）；元进度外层循环补入 01——元进度资源定名**钥石**（关底 Boss 看守的区域核心，击杀取走、局外解锁永久提升，用户拍板；registry 登记随元进度设计批补）。**旧路径清偿**：CLAUDE.md 头部导航与 Project Layout 改指新骨架 + 新增「新骨架过渡口径」条款（lean/lint/两件套纪律仅约束归档，新骨架纪律 = 可读性优先 + 索引同步 + 不建 analysis）；registry owner ×33 与切片代码头注 ×17 改指归档路径；gdd_lint PostToolUse 钩子停用（工具留 `tools/` 备查）。**已知待办**：registry/数据表雾残留清理批（variation.tres fog 行 / board_gen L2 锚行雾参数 / 显影尘·地穴全图卷 fog_reveal / L2 层名"雾漫巢径"）；registry status_effect.mvp_content 缺暴走/失衡两行登记。
+
+48. **文档写作规范成文 + 引用纪律补入（2026-09-14）**：`docs/doc-conventions.md` v1 成文（另一会话，整合全部写作纪律为写文档前必读的单一权威），本会话补第 7 节「引用纪律」（单点定义/规范名唯一/引用不转述/反向边登记/删除概念 SOP，雾格事故为对照反例）；CLAUDE.md 挂必读指针与摘要。同批：`systems/排雷循环/行动经济.md`（自归档迁移定稿）与 `systems/表现与支撑/教学引导.md`（范围草案）成文（另一会话）。