Merge branch 'master' into arch51-docs
# Conflicts: # design/engineering/architecture/architecture.md
This commit is contained in:
DKChan committed
commit
644c56939a
390 files changed
+8159
-1747
No files matched your search
@@ -2,8 +2,8 @@
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 版本：1.32
|
||||
- 最近更新：2026-11-03（架构审查 5.2 文档漂移订正——主角账三件与刷新账件四行补登记替代失效的 HeroLedger 行、MetaProgression 基础层补登记行（四 Autoload 唯一跨 Autoload 依赖件）、拆件定稿节冻结计数摘除（活体清单不冻结计数）、CurioStop 行落账指称随拆件改指；EC8 热重载规格经用户裁决保留原状（实装排期另立待办条目）、本批一度摘除已撤回，本文「抗热重载」快照句随规格保留；沿革查 git）
|
||||
- 版本：1.35
|
||||
- 最近更新：2026-11-04（架构审查 5.2 文档漂移订正并入 P1 余项批之后——主角账三件与刷新账件四行补登记替代失效的 HeroLedger 行、MetaProgression 基础层补登记行（四 Autoload 唯一跨 Autoload 依赖件）、拆件定稿节冻结计数摘除（活体清单不冻结计数）、CurioStop 行落账指称随拆件改指；EC8 热重载规格经用户裁决保留原状（实装排期另立待办条目）、一度摘除已撤回，「抗热重载」快照句随规格保留；沿革查 git）
|
||||
- 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定）
|
||||
- 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调）
|
||||
- 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准）
|
||||
@@ -102,7 +102,7 @@
|
||||
| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API |
|
||||
|---|---|---|---|---|
|
||||
| **board_generator**（A1） | 生成算法（五阶段管线）、BoardGenTable 回填、生成期指标集、合法性谓词（clearable / R₀≠S / min_safe）、可推理率度量（metric_version）；生成姿态 = MVP 同步生成 + 加载幕（切片实证 10×10/12×12 同步可接受，WorkerThread 留扩展） | `generate(L, D, rng) -> Board`；度量独立入口×3（推理器 / F3 度量 / 合法性谓词——独立纯函数、同一实现） | ConfigDB（BoardGenTable/VariationTable）；board_gen 流（一次 open_stream = 一张图）；dig_ap_cost 只读 | 无 |
|
||||
| **minesweeper_rules**（A2） | 棋盘状态（已开集 O / 封印集 G / 小人位）、三事件面、批次仲裁、install 四不变式 | `install_board(board)`；`settle_batch(intents)`（唯一提交入口）；查询只读面（current_board / hero_pos / is_revealed / has_seal 等）；`compute_move_path(cell)` 只读；`retire_board()`；三源拒绝（board_face / resource_face / phase）+ sub_reason 封闭枚举 | A1 产物（Board class_name 数据契约）；A3 try_spend / last_round_end（迭代 41 由属性改方法）/ 相位 | 无（零表读取、零 UI——切片实证） |
|
||||
| **minesweeper_rules**（A2） | 棋盘状态（已开集 O / 封印集 G / 小人位）、三事件面、批次仲裁、install 四不变式 | `install_board(board)`；`settle_batch(intents)`（唯一提交入口）；查询只读面（current_board / hero_pos / is_revealed / has_seal 等）；`compute_move_path(cell)` 只读；`preview_reveal(cell)` 只读预览口（零写入零事件——0 格连锁传播闭包；迭代 50 己案建口）；`retire_board()`；三源拒绝（board_face / resource_face / phase）+ sub_reason 封闭枚举 | A1 产物（Board class_name 数据契约）；A3 try_spend / last_round_end（迭代 41 由属性改方法）/ 相位 | 无（零表读取、零 UI——切片实证） |
|
||||
| **unit_container**（B2） | hero/enemy 单位实例（hp/atk/实例池：池快照+冷却+摇定动作+保底计数）、行值快照 | spawn / query_alive / rollable_skills / special_skills / check_trigger_unlocks / set_pending_action / pending_action / basic_streak / commit_action / tick_cooldowns / apply_damage / heal / default_target / check_skill_unlocks / despawn_all（2026-09-16 敌人技能池批：query_beat/query_attack/advance 随行为环退役；rollable_skills/special_skills/check_trigger_unlocks 带 facts 参——2026-10-27 情境条件触发器实装，事实缺键=条件假拦下，百分比事实走阈值式折算） | ConfigDB（EnemyTable/SkillTable/HeroTable） | 无 |
|
||||
| **reward_economy**（B4） | 格面资源身份映射（install 期预分配、Ready 只读、换图映射消亡）、极性路由字典面（（类型, 极性）→ 字典行查询；路由执行归 B1 授予段）、F6 当量供给投影；装配期摇号面已拆出掷格件 RewardRoller（2026-11-02 轴戊设计闭合、迭代 49 卡① 建件——roll_board 装配序＝守卫→复位→委托→收纳→ready；受理账面留守） | 封闭 API：roll_board / query_identity / query_full_snapshot / grant / grant_clear / retire_mapping / polarity_row / phase（weighted_pick 退役——返行选行算子迁掷格件）；另有 is_mapped 静默布尔投影（批量工具用）；实测类变量 11 | ConfigDB（RewardTable）；BattleFxHost 经注入 Callable `luck_bias_query` 取偏运合计（reward_roll 发射与 bias_rewards 求和移至效果层完成）；reward_roll 流（scope = 每次 install 批，取号经掷格件） | 无 |
|
||||
| **helper_items**（A5，切片已实装秘宝域） | HelperItemTable、探测显影语义 | （契约规范源：`../../gdd/systems/跨局循环/秘宝.md`——桥接位：A2 查询接口 + A4 counter_item_ids） | A2 / A4 / B4 | 无 |
|
||||
@@ -132,7 +132,7 @@
|
||||
| **level_runner**（C1-lite，切片已建） | 关卡域生命周期（节点链推进、共享 B4 + HP 携带、关卡末 level_clear） | 节点推进接口；LevelTable（`level.tres`——节点 enum {battle,reward,rest,boss}、末节点必须 Boss、ConfigDB 跨表校验⑧） | B1（直构 BattleOrchestrator 接线战斗）、ConfigDB LevelTable | 无 |
|
||||
| **run_structure**（C2） | 冒险/关卡序列、失败重开、**master_seed 唯一接线方** | （契约规范源：`../../gdd/systems/冒险循环/冒险结构.md`） | RngService.set_master_seed、C3/D2 | 无 |
|
||||
| **difficulty**（C3） | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表（切片 monte_carlo 为工具原型） | 调参输出（经 D2 R1 解析/编排器传递，禁反向调用生成） | ConfigDB、B1 对账输出（调参约束清单）、A1 报告 C | 无 |
|
||||
| **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEYS 六键/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编）。**存档内元进度数据读写原语归 MetaStateStore——已落地（迭代 41）：本类纯转发读已退役（消费方直连 meta_state），业务规则与写口编排留本类；hero_override 内联锻造加值与树淬炼 flat；并组三组（forge_select(kind,route_id)／hero_type_axes()→{attack,armor}／tree_camp_status()→{rows,fork_groups}）；补 meta_state 成员装配** | 公开面 20 定稿：buy_treasure_unlock / refresh_treasure_unlocks / treasure_shop_status / forge_buy_level / forge_buy_unlock / forge_select / hero_type_axes / forge_shop_status / settle_adventure / hero_override / tree_can_buy / tree_buy / tree_toggle_fork / tree_buy_fork / tree_rule_keys / tree_camp_status / toggle_attunement / attune_camp_status / attune_refresh_charges / buy_attune_refresh | D3、C2、ConfigDB | 无 |
|
||||
| **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEY_PARAMS 六键参数字典（迭代 50 键值字典化）/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编）。**存档内元进度数据读写原语归 MetaStateStore——已落地（迭代 41）：本类纯转发读已退役（消费方直连 meta_state），业务规则与写口编排留本类；hero_override 内联锻造加值与树淬炼 flat；并组三组（forge_select(kind,route_id)／hero_type_axes()→{attack,armor}／tree_camp_status()→{rows,fork_groups}）；补 meta_state 成员装配** | 公开面 20 定稿：buy_treasure_unlock / refresh_treasure_unlocks / treasure_shop_status / forge_buy_level / forge_buy_unlock / forge_select / hero_type_axes / forge_shop_status / settle_adventure / hero_override / tree_can_buy / tree_buy / tree_toggle_fork / tree_buy_fork / tree_rules（返参数字典——迭代 50 R1 换代）/ tree_camp_status / toggle_attunement / attune_camp_status / attune_refresh_charges / buy_attune_refresh | D3、C2、ConfigDB | 无 |
|
||||
|
||||
### 战斗域装配现状（迭代 27——2026-10-17 用户裁写入；RunLedger 段已随迭代 39 拆件批退役，四账去向见下「冒险域拆分（现状登记）」节）
|
||||
|
||||
@@ -271,7 +271,7 @@
|
||||
|---|---|---|---|
|
||||
| **worktree-guard**（ZCode PreToolUse） | `.zcode/hooks/worktree-guard.sh`（本机件，不入 git） | agent 侧车道纪律：主工作区 Edit/Write 与主区非 merge `git commit` 拦截（豁免 `.zcode/`、`.qoder/`；worktree 内目标快速放行；合并收尾提交凭 MERGE_HEAD 豁免）；`git commit --no-verify` 拦截（该旗标仅属用户）；iter 分支合回一卡一提交数卡校验；规则闸 | 路径性质＋分支名＋MERGE_HEAD＋git 图 |
|
||||
|
||||
验证收拢为合回后本地 CI 全量（post-merge 触发），commit 点零执法；主工作区防污染由 ZCode 层守卫承担——只约束 agent，用户手工改动不受限。子代理覆盖面（2026-10-26 冷启动评估实测）：子代理的工具调用不经过 ZCode 层守卫——ZCode 层实际只覆盖主会话工具调用；残余暴露面＝子代理写主工作区与蓄意 `--no-verify`（该旗标整族跳过 git 层钩子），属故意越权而非遗忘型失误，与防遗忘的设计目标正交。
|
||||
验证收拢为合回后远端 CI（post-merge 钩子推送 origin master 触发 Gitea Actions，runner＝Mac 本机 host 模式；按改动域分流，分流单点＝tools/ci/domain_route.sh），commit 点零执法；主工作区防污染由 ZCode 层守卫承担——只约束 agent，用户手工改动不受限。子代理覆盖面（2026-10-26 冷启动评估实测）：子代理的工具调用不经过 ZCode 层守卫——ZCode 层实际只覆盖主会话工具调用；残余暴露面＝子代理写主工作区与蓄意 `--no-verify`（该旗标整族跳过 git 层钩子），属故意越权而非遗忘型失误，与防遗忘的设计目标正交。
|
||||
|
||||
### 三条判定硬闸现行状态
|
||||
|
||||
@@ -283,22 +283,24 @@
|
||||
|
||||
背景事实（run_smoke 头注在案）：GDScript 运行时脚本错误不改进程退出码、不计入冒烟失败数、且静默中断所在函数剩余断言——2026-09-19 状态记录 83 实证「309 项 0 失败」实为断言未跑全。这是 SCRIPT ERROR 扫描必须存在于判定层的原因。
|
||||
|
||||
### 静态扫描域 S1–S8 承接清单
|
||||
### 静态扫描域 S1–S13 承接清单
|
||||
|
||||
静态扫描域规则（2026-09-12 立，沿革见 git commit log；下表为现行事实登记）：
|
||||
|
||||
| # | 规则 | 状态 |
|
||||
|---|---|---|
|
||||
| S1 | 玩法代码禁 `randomize()`、自建 `RandomNumberGenerator`（D2 Rule 5） | **在位**（硬失败；扫描面 game/core + game/presentation） |
|
||||
| S1 | 玩法代码禁 `randomize()`、自建 `RandomNumberGenerator`（D2 Rule 5） | **在位**（硬失败；扫描面 game/core + game/presentation）。非产品码三目录（`game/tests`／`game/probe`／`game/sim`）不进本闸与 S2——它们自建且**显式定种**的随机源是合法测量口径（同种子对拍改前改后读数），禁的是不定种形态；适用域分档与无机器闸的理由见 code-conventions §4 第 13 条（2026-11-03 架构审查 P1 余项裁：不扩扫描面，人工评审承载） |
|
||||
| S2 | 禁全局随机函数 `randi()` / `randf()` / `randf_range()`——全局 RNG 绕开 RngService（specialist 补登） | **在位**（与 S1 同段硬失败；实例方法 `.randi()` 排除、`rng-seed-exempt` 豁免注记在案） |
|
||||
| S3 | core/ 禁 ConfigDB 外 data 表加载（`load(` / `preload(` / `ResourceLoader.load`；schema class_name 直引豁免）（D2 Rule 2） | **在位**（warning 级——class_name 直引误报需人工复核；路径已由裸 `core` 修正为 `game/core`，此前恒零命中静默空转；豁免 config_db.gd 自身＝数值单一事实源的正主） |
|
||||
| S3 | core/ 禁 ConfigDB 外 data 表加载（`load(` / `preload(` / `ResourceLoader.load`；schema class_name 直引豁免）（D2 Rule 2） | **在位**（warning 级——class_name 直引误报需人工复核；路径已由裸 `core` 修正为 `game/core`，此前恒零命中静默空转；豁免 config_db.gd 自身＝数值单一事实源的正主）。2026-11-03 架构审查 P1 余项裁**维持 warning 级不升硬**：升硬的前提是先有可靠的直引误报排除判据，该判据未立；本行状态即事实源，禁在别处另列 |
|
||||
| S4 | core/ 禁 `extends Control/Node2D`、禁 `.tscn` preload（D2 Rule 7） | **在位**（硬失败） |
|
||||
| S5 | core/ 禁裸引用 autoload 全局标识符（`ConfigDB` / `RngService` 直接写 = --script 模式 parse error）——构造注入 only（specialist 升格） | **在位**（硬失败；形态＝标识符后紧跟 `.` 的成员访问，排除注释行与字符串字面量） |
|
||||
| S6 | core↔core 信号连接只许方法 Callable（禁 lambda 捕获 self）；发射者禁持有订阅者反向引用 | **在位**（2026-10-25 落闸：内联 lambda 禁令机器闸——同行与跨行两形态、豁免注记 `s6-signal-exempt`、盘面零存量；「发射者禁反向引用」句静态判据不成熟，归人工评审面承接、不造弱判据） |
|
||||
| S7 | B1 编排唯一性：B2/B3/B4 API 符号命中文件 ⊆ B1 文件集；A2/B3/B4 零相互直调（B1 AC-43） | **在位**（2026-10-25 落闸：符号清单×B1 域文件集，族内自调用豁免、豁免注记 `s7-b1-exempt`、缺位自检；全符号形态盘面零存量） |
|
||||
| S8 | 结算路径 `await` 零命中（B1 结算/编排文件集）；字面量扫描 = warning 级 + 人工三要素复核（D2 AC-14 口径） | **在位**（2026-10-25 落闸：B1 域文件集 await 零命中，文件集缺位自检、排除注释与字符串；盘面零存量。本行后半句「字面量扫描＝warning 级＋人工三要素复核」为独立子项、仍归人工面） |
|
||||
| S8 | 结算路径 `await` 零命中（B1 结算/编排文件集）；字面量扫描 = warning 级 + 人工三要素复核（D2 AC-14 口径） | **在位**（2026-10-25 落闸：B1 域文件集 await 零命中，排除注释与字符串；盘面零存量。清单单点＝`static_scan.sh` 的 `B1_SET`，S7 的豁免名单由它派生（原两份 14 文件抄本已并点，2026-11-03 架构审查 P1 裁）。自检两件：①清单内文件缺位即红；②**目录域反向对账**——`game/core/settlement/` 实有 `.gd` 未登记进 `B1_SET` 即红（新段类忘登记＝await 面静默失效，2026-11-03 补）。反向对账只覆盖 settlement/：装板/授予/效果端口/掷格四件结算码住 `game/core` 根下，纯目录域覆盖不住，根下新增仍由本行「模块归属」B1 登记面＋写卡段申报承接。本行后半句「字面量扫描＝warning 级＋人工三要素复核」为独立子项、仍归人工面 |
|
||||
|
||||
域外扩充两件（均硬失败在位）：**S9** 类型闸（`tools/audit_type_hints.py`，迭代 27 T5——产品码无类型容器/有值返回缺类型/参数缺类型）；**S10** 文件头闸（`tools/audit_file_headers.py`——头注 ≤8 行 + 日期/变更叙事黑名单）。
|
||||
域外扩充五件（S11/S12/S13 自 2026-09-29 起陆续落闸，本表原先只登记到 S10，2026-11-03 补齐登记面）：**S9** 类型闸（`tools/audit_type_hints.py`，迭代 27 T5——产品码无类型容器/有值返回缺类型/参数缺类型；扫描面＝产品码三目录）；**S10** 文件头闸（`tools/audit_file_headers.py`——头注 `##` 载体＋日期/变更叙事黑名单；扫描面＝产品码三目录）；**S11** 代码注释禁用词闸（扫描面＝`game/` 全域 `.gd`/`.tres`/`.md`/`.json`/`.sh`，词表单点取 `design/gdd/术语表.md`）；**S12** 效果引擎无状态化旧件零残留闸（扫描面＝`game/` 全域 `.gd`/`.tres`，旧符号与旧 id 字面清单为脚本字面值）；**S13** 第三方质量规则闸（`tools/gdstyle_gate.py`，钉 gdstyle v0.4.0；扫描面＝产品码三目录，存量以 `tools/gdstyle_baseline.txt` 欠账簿登记，判定＝基线外新键红、同键数值恶化红）。
|
||||
|
||||
S11/S12 扫描面覆盖全域，故 sim/probe/tests 的术语与旧件面**在册**；其余十一闸（S1–S10、S13）扫描面止于产品码，非产品码三目录不受约束——分档理由与各目录的运行期承接通道见 code-conventions §4 第 13 条。**防空转自检现行状态**（本文「三层承载与判定原则」要求扫描面为空即判红）：S1–S8 与 S11/S12/S13 各自带空面或缺位自检；**S9/S10 两件已补齐同款自检**（`tools/audit_type_hints.py` 与 `tools/audit_file_headers.py` 缺目录或扫描面零个 `.gd` 一律判红，并绿时打印扫描面件数供核；2026-11-03 架构审查 P1 余项的工程改动批落地，本表此前登记的「静默零命中即 PASS」偏差已清偿）。
|
||||
|
||||
### 三层承载与判定原则
|
||||
|
||||
|
||||
@@ -72,12 +72,13 @@
|
||||
4. **lambda 捕获循环变量按创建时值**——循环内先落地局部变量再捕获，或用 `bind`。
|
||||
5. **重命名脚本必须同步 `.uid` 文件**；新增 `class_name` 后必须跑一次编辑器扫描刷新全局类缓存，否则 `--headless --script` 模式解析失败。
|
||||
6. **`print` 格式占位符与实参类型必须匹配**（`%d` 配 String = 静默输出字面量）。
|
||||
7. **语言纪律已机器化为 S9 类型闸**——`tools/audit_type_hints.py`，执行载体=静态扫描域 S9（`game/tests/static_scan.sh`），退出码 0=归零。扫描面=产品码（`game/core`+`game/data`+`game/presentation`；probe/sim/tests 不在扫描面——测量面容器直构是既有惯例）。三规则：R1 无类型容器（显式非参数化 `Dictionary`/`Array` 注解）／R2 有值返回缺返回类型（纯副作用缺 `-> void` 属写法面不入闸）／R3 参数缺类型（`_init` 豁免——构造注入面形态自由）。
|
||||
7. **语言纪律已机器化为 S9 类型闸**——`tools/audit_type_hints.py`，执行载体=静态扫描域 S9（`game/tests/static_scan.sh`），退出码 0=归零。扫描面=产品码三目录（`game/core`＋`game/data`＋`game/presentation`）；非产品码三目录的适用域分档见本节第 13 条。三规则：R1 无类型容器（显式非参数化 `Dictionary`/`Array` 注解）／R2 有值返回缺返回类型（纯副作用缺 `-> void` 属写法面不入闸）／R3 参数缺类型（`_init` 豁免——构造注入面形态自由）。
|
||||
8. **`:= {}` 推断形态不算债**——`var x := {}` 类赋值推断属类型推断合法面，不入 R1 扫描；只有显式写的非参数化容器注解才算无类型容器。
|
||||
9. **行级白名单通道 `# type-hint: ignore`**——豁免该行不入 S9；豁免理由必须随行注明（现行例：`board_generator` 四函数的 db 参鸭子型——typed 参拒冒烟夹具 `_BoardRowStub` 注入）。
|
||||
10. **`# rng-seed-exempt` 标记豁免通道**——S1/S2 随机函数扫描对该行豁免；限定用途=非玩法 RNG 消费面的引擎熵（现行例：组合根种子编辑框空态取 `randi()`——建种子不进玩法封闭流）。
|
||||
10. **`# rng-seed-exempt` 标记豁免通道**——S1/S2 随机函数扫描对该行豁免；限定用途=非玩法 RNG 消费面的引擎熵（现行例：组合根种子编辑框空态取 `randi()`——建种子不进玩法封闭流）；非产品码三目录自建随机源的定种要求见第 13 条。
|
||||
11. **`--script` 模式禁裸 autoload 标识符**——`ConfigDB`/`RngService` 等 autoload 名在 `--headless --script` 模式编译器不解析（parse error）；产品码与测试夹具一律经节点路径取用（`get_node("/root/…")`／`AUTOLOAD_PATH_*` 常量）；静态扫描域 S5 硬失败承载在位。
|
||||
12. **Variant 参数化现行口径**——账本类字典/数组标注 `Dictionary[Variant, Variant]`/`Array[Variant]` 即合格（满足 R1）；元素类型精化列后续事项、不入硬纪律，口径变更须用户裁决后续批次另行写入。
|
||||
13. **静态扫描适用域按来源分档（2026-11-03 架构审查 P1 余项裁）**——S 系静态扫描（S1–S13）的扫描面一律止于产品码三目录，`game/tests`／`game/probe`／`game/sim` 不进任何 S 系扫描面；这三目录的可靠性由运行期通道承接，各通道是：`game/tests`＝闸 00/01/02（冒烟·单元与集成·系统测试）、`game/probe`＝闸 03/04/05（场景探针与渲染 golden；同目录内 `type_glow_shot_probe` 是人工取证件、`probe_ui_util` 是探针共用面，两者不入闸）、`game/sim`＝不入 CI，属用户手动发起的调参与数值测量批量。三目录**允许**自建 `RandomNumberGenerator`，条件＝**必须显式定种**（改前改后读数要用同种子对拍，这是全项目测量口径）；三目录真正禁止的形态是不定种随机——`randomize()` 与全局 `randi()`／`randf()`／`randf_range()`，一旦命中那次运行结果不可复现，读数与取证一并失效。这条对三目录的部分目前**无机器闸**（S1/S2 扫描面不含它们）：扩面需给每处合法定种挂 `rng-seed-exempt` 注记、只拦得住新增，2026-11-03 用户裁不扩，改由本条文字＋批末独立验收审计的人工评审承载。术语口径：`tools/run_all_gates.sh` 里的「测量面」指 `game/tests`＋`game/sim`（影响面选闸用语，`game/probe` 不在其中——改探针必须跑 03/05），与本条分档无关；本文不再用「测量面」统称这三个目录。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -7,12 +7,12 @@
|
||||
|
||||
## 1. 分支纪律（worktree 铁律）
|
||||
|
||||
主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区（2026-10-31 用户裁恢复；2026-10-30 的「主区直改＋直提」车道与 commit 点 pre-commit 直改闸随之退役；验证模型不动——合回后本地 CI 仍是唯一强制验证点）：
|
||||
主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区（2026-10-31 用户裁恢复；2026-10-30 的「主区直改＋直提」车道与 commit 点 pre-commit 直改闸随之退役；验证模型同构——合回后远端 CI 是唯一强制验证点，2026-11-03 用户裁，细则见本节第 3 条）：
|
||||
|
||||
1. **worktree 车道（一切面）**：每批先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；建区后立刻跑 `tools/setup_worktree_userdir.sh`——给该区独立 Godot user 目录（测试夹具、试玩日志、截图产物不与其他区共用；主区不生成，真实档保持原位）。所有改动与提交都在 worktree 内自由进行——commit 点零钩子检查（`tools/hooks/pre-commit` 已删除）。豁免面仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）
|
||||
2. **收口顺序（固定）**：**冻结 → 件核 → 并 master → 重塑 → 主区合回 → 删区**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先在 worktree 内 `git merge master` 解冲突（必须在合回之前，合回后才并＝CI 验的是中间态）；**重塑**＝迭代分支（iter<N> 形）合回前执行 `python tools/reshape_cards.py`，把分支线性史按卡末态快照压成一卡一笔（可选追加一笔纯文档收尾），master 台账由此每卡一行——工具自带「重塑前后树逐字节一致」断言与 backup 分支，不改任何文件内容；非迭代批免重塑；然后主工作区 `git merge --no-ff <任务分支>`——这是主区唯一合法写动作（合回守卫对迭代分支数卡校验，未归卡提交拦下）。**合回落地即 `git worktree remove`＋删分支（合回即删，2026-09-19 原裁）；post-merge 钩子已在合回落地时自动触发 CI，红态不回滚合并——新开修复 worktree（`fix-<任务名>` 分支，非 iter<N> 形免重塑免数卡）修复提交再合，落地复验追绿后删修复区**。游戏类测试（冒烟/单测/MC/探针）批内默认零执行（两入口铁规，见 §4），用户点名或当场问才跑
|
||||
3. **合回后验证（本地 CI，2026-10-30 用户裁）**：git merge 合回 master 落地后 post-merge 钩子（`tools/hooks/post-merge`）后台触发 `tools/ci_runner.sh merge` 对 master 尖跑一次全量域闸——唯一强制全量验证点；CI 红态下修复合回落地即由 post-merge 钩子复验追绿（红态修复走新开修复 worktree，`fix-<任务名>` 分支，非 iter<N> 形免重塑免数卡；post-commit 钩子保留为红态主区直提兜底触发，绿态与无状态零触发）。重跑判据：同一份字节禁止第二次人手跑；有意义的重跑只剩「验证修复」一类。CI 红不回滚合并——红项记 `game/tests/.gates/ci-status.json`，开工先读 CI 状态，红未修不开新批。跑批起手 `--editor --quit` 刷类名缓存（在册坑：.godot 缓存不入 git，合并后失配假红假绿）。并跑语义＝跑完补跑（coalesce）：跑批期间新触发不中断当前轮，轮尾对最新尖端补跑，绝不逐笔各跑一轮。**回执等待纪律（2026-11-02 用户裁）**：合回落地即向用户呈报本批总结，回执等待一律以 run_in_background 后台任务运行 `tools/ci_watch.sh <合并提交>`（认领判据与容错细则＝该件头注），禁前台 sleep／轮询循环等 CI；后台任务唤醒会话后按回执续行——绿即删区收口，红或超时即呈报走修复批。闸重跑等一切分钟级跑批等待同此纪律
|
||||
4. **执法分层（全机械，零自觉依赖）**：①`.zcode/hooks/worktree-guard.sh`（PreToolUse，本机件不入 git）——agent 侧：主工作区 Edit/Write 与主区非 merge `git commit` 拦截（豁免 `.zcode/`、`.qoder/`；worktree 内目标快速放行；合并收尾提交凭 MERGE_HEAD 豁免）、`git commit --no-verify` 拦截（该旗标仅属用户）、iter<N> 分支合回的一卡一提交数卡校验、规则闸（写 design/／game/ 前核对会话规约读取记录）。②post-merge／post-commit 钩子——本地 CI 触发（仅主工作区；任务 worktree 内的合并不触发）。③git 层不设车道钩子（pre-commit 直改闸已退役）——用户手工改动不受限；ZCode 层只约束 agent（子代理不经守卫层）
|
||||
3. **合回后验证（远端 CI，2026-11-03 用户裁取代本地 CI）**：git merge 合回 master 落地后 post-merge 钩子（`tools/hooks/post-merge`）自动 `git push origin master` 触发远端 CI（Gitea Actions，runner＝Mac 本机 host 模式），工作流按改动域分流（分流算法单点＝`tools/ci/domain_route.sh`：游戏码批＝两域全量含渲染闸，文档批＝文档域秒级闸，纯闸件/管线批＝零触发）——唯一强制验证点。回执由 `tools/ci_watch.sh remote` 轮询 Gitea API 写回 `game/tests/.gates/ci-status.json`（合同不变：commit/verdict/red_gates/key_lines/note），agent 开工先读 CI 状态的纪律不变，红未修不开新批。CI 红态不回滚合并——修复走新开修复 worktree（`fix-<任务名>` 分支，非 iter<N> 形免重塑免数卡），修复合回落地即再推再验追绿（追绿同链；本地跑批件 `ci_runner.sh` 与本地追绿钩子 post-commit 已退役）。导入缓存刷新（.godot 不入 git 的在册坑）由工作流「导入缓存刷新」步接管。**回执等待纪律（2026-11-02 用户裁）**：合回落地即向用户呈报本批总结，回执等待一律以 run_in_background 后台任务运行 `tools/ci_watch.sh remote <合并提交>`（认领判据与容错细则＝该件头注），禁前台 sleep／轮询循环等 CI；后台任务唤醒会话后按回执续行——绿即删区收口，红或超时即呈报走修复批。闸重跑等一切分钟级跑批等待同此纪律
|
||||
4. **执法分层（全机械，零自觉依赖）**：①`.zcode/hooks/worktree-guard.sh`（PreToolUse，本机件不入 git）——agent 侧：主工作区 Edit/Write 与主区非 merge `git commit` 拦截（豁免 `.zcode/`、`.qoder/`；worktree 内目标快速放行；合并收尾提交凭 MERGE_HEAD 豁免）、`git commit --no-verify` 拦截（该旗标仅属用户）、iter<N> 分支合回的一卡一提交数卡校验、规则闸（写 design/／game/ 前核对会话规约读取记录）。②post-merge 钩子——远端 CI 触发（推送＋挂回执等待；仅主工作区，任务 worktree 内的合并不触发）。③git 层不设车道钩子（pre-commit 直改闸已退役）——用户手工改动不受限；ZCode 层只约束 agent（子代理不经守卫层）
|
||||
|
||||
## 2. 五段流水线
|
||||
|
||||
@@ -44,12 +44,12 @@
|
||||
5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟
|
||||
|
||||
**实施**
|
||||
6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并
|
||||
6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并。拆件/重构产出的新 core 件不属新增玩法，由 test-conventions §8.3「新增 core 件的覆盖登记义务」承接（被 tests 面点名，或在能力行申报「经宿主链覆盖」），核对动作归本清单第 10 条的收尾提交
|
||||
7. **验收改动先行声明**——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补
|
||||
|
||||
**完成**
|
||||
8. **合回后 CI 验证（唯一强制验证点）**——主工作区 `git merge --no-ff <任务分支>` 落地后 post-merge 钩子自动跑全量域闸（不带参数档，02 全套件），判定与红项落 `game/tests/.gates/ci-status.json`。全量是唯一强制档：跨卡触面、探针与未申报套件的消费漏网只有全量闸能抓（迭代 44 实证），关联档选测的盲区由它兜底。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分（含选闸算法与套件族映射表）**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。开发期手动跑批按需选档（按文件性质判域：代码面→`--code`，文档件→`--docs`，两类都有→全量；`--code` 关联档选测——02 只跑「需求卡片申报 ∪ diff 推导」并集套件、00 冒烟／01 系统测试／09 静态扫描三件保险恒跑、横切面回落全量——算法见闸脚本），手动跑不构成验收。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占 CI 全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变；闸真崩溃时 CI 判红在案（跑不出回执＝verdict 红，fail-closed 语义保留）
|
||||
9. **重跑语义（2026-10-30 用户裁，取代原「每批一次／合并后零复跑」口径）**——同一份字节禁止第二次人手跑；允许的重跑只剩两类：① CI 红后的修复合回（post-merge 钩子复验，每轮修复至多触发一轮）；② 用户自发发起的全量回归。「跑都跑了再跑一遍保险」「顺手改点再补一跑」都不构成重跑理由。类名缓存刷新与开机确认由 CI 跑批起手接管（§1 第 2 条），合并后无手工动作
|
||||
8. **合回后 CI 验证（唯一强制验证点）**——主工作区 `git merge --no-ff <任务分支>` 落地后 post-merge 钩子自动推送 origin master 触发远端 CI；远端按改动域分流（§1 第 3 条），游戏码批跑全量域闸（不带参数档，02 全套件），判定与红项由 `ci_watch.sh remote` 写回 `game/tests/.gates/ci-status.json`。全量是游戏码批的强制档：跨卡触面、探针与未申报套件的消费漏网只有全量闸能抓（迭代 44 实证），关联档选测的盲区由它兜底。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。`tools/run_all_gates.sh` 是全部验证闸的**唯一入口、唯一清单与唯一域划分（含选闸算法与套件族映射表）**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。开发期手动跑批按需选档（按文件性质判域：代码面→`--code`，文档件→`--docs`，两类都有→全量；`--code` 关联档选测——02 只跑「需求卡片申报 ∪ diff 推导」并集套件、00 冒烟／01 系统测试／09 静态扫描三件保险恒跑、横切面回落全量——算法见闸脚本），手动跑不构成验收。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占 CI 全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变；闸真崩溃时远端 CI 判红在案（job 失败＝verdict 红，fail-closed 语义保留）
|
||||
9. **重跑语义（2026-10-30 用户裁，取代原「每批一次／合并后零复跑」口径）**——同一份字节禁止第二次人手跑；允许的重跑只剩两类：① CI 红后的修复合回（post-merge 钩子再推再验，每轮修复至多触发一轮）；② 用户自发发起的全量回归。「跑都跑了再跑一遍保险」「顺手改点再补一跑」都不构成重跑理由。导入缓存刷新由远端工作流「导入缓存刷新」步接管，合并后无手工动作
|
||||
10. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`/`待办清单.md`/`体验验证清单.md`）实现批禁写，见 §12
|
||||
11. **文档同步闸（实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，**另禁写 `game/tests/README.md`（能力清单，归写卡段维护，test-conventions §8.9）**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter<N>-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务+实现决定记录——超白名单／超卡片明列范围事项逐条记「决了什么／为什么／代价／撤销方式」，全部按卡执行时只写一行「零拍板」）、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由工程/文档设计改动批（直改类）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注
|
||||
12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置
|
||||
@@ -62,7 +62,7 @@
|
||||
|
||||
**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。
|
||||
|
||||
**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**。强制验证点＝合回后本地 CI 的全量档（§1 第 2 条）；分档只服务开发期手动跑批。真人实机目检归用户不进自动闸。
|
||||
**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**。强制验证点＝合回后远端 CI（游戏码批走全量档，细则见 §1 第 3 条）；分档只服务开发期手动跑批。真人实机目检归用户不进自动闸。
|
||||
|
||||
## 5. MC 采集档位细则
|
||||
|
||||
|
||||
@@ -25,9 +25,9 @@
|
||||
每个缺陷修复必须在探针或冒烟中留下能抓住该缺陷的断言（例：封印动作耗尽 AP → 必须进入第 2 轮；
|
||||
选用道具 → 库存态必须变 Used）。没有回归断言的修复视为未完成。
|
||||
|
||||
## 4. 验证时机（合回后本地 CI 制，2026-10-30 换代）
|
||||
## 4. 验证时机（合回后远端 CI 制，2026-11-03 换代）
|
||||
|
||||
开发期窄测义务不变：每批开发中，本批新增/改动的验收测试自己跑绿即收口（卡内只测自己改的东西，process-conventions §6）。全量验证归合回后的本地 CI：git merge 合回 master 触发 post-merge 钩子跑 `tools/run_all_gates.sh` 不带参数档（两域全量，02 全套件——跨卡触面与关联档选测的盲区由全量兜底），结果落 `game/tests/.gates/ci-status.json`；CI 红态下修复合回落地即由 post-merge 钩子复验追绿（修复走新开 `fix-<任务名>` 修复 worktree，process-conventions §1）。同一份字节禁止第二次人手跑。该脚本是全部验证闸的唯一入口与唯一清单，域划分与选闸算法只写在脚本里，本文禁另列闸件清单。
|
||||
开发期窄测义务不变：每批开发中，本批新增/改动的验收测试自己跑绿即收口（卡内只测自己改的东西，process-conventions §6）。全量验证归合回后的远端 CI：git merge 合回 master 落地后 post-merge 钩子推送 origin master，远端按改动域分流跑 `tools/run_all_gates.sh`（游戏码批＝不带参数档两域全量、02 全套件——跨卡触面与关联档选测的盲区由全量兜底；文档批＝文档域秒级闸；分流算法单点＝`tools/ci/domain_route.sh`），回执由 `tools/ci_watch.sh remote` 轮询写回 `game/tests/.gates/ci-status.json`；CI 红态下修复合回落地即再推再验追绿（修复走新开 `fix-<任务名>` 修复 worktree，process-conventions §1；本地跑批件 ci_runner.sh 与本地追绿钩子 post-commit 已退役）。同一份字节禁止第二次人手跑。该脚本是全部验证闸的唯一入口与唯一清单，域划分与选闸算法只写在脚本里，本文禁另列闸件清单。
|
||||
行为探针使用随机化玩家行为（封印/停手/刷新/无效点击）——自动玩家不做的动作就是测试盲区。
|
||||
|
||||
## 5. 测试函数怎么写——验收清单条目的落码规范
|
||||
@@ -99,6 +99,8 @@
|
||||
|
||||
**能力清单维护锚（2026-10-29 用户裁改版定稿）**：`game/tests/README.md`「能力清单」是**实现指导＋阅读导航＋义务声明**——只宣布「要验证什么」，不记「是否已验证／是否跑过」；落地账归现行验收闭合链（改动—验收对照表逐条挂断言＋合回前独立验收审计），本清单不承载验证状态。表为四列：能力｜系统｜真实入口｜代表用例（`文件:函数`）。**维护归写卡段，当场入表**：写需求卡片时，本批新增能力当场写入能力行——真实入口取自设计文档已定的入口，代表用例＝卡里定死的计划测试（`文件:函数`）；受影响存量行（入口／用例名变更）同批更新；能力退役删行。**实现照单落名**：测试函数名以清单为唯一依据，名实不符＝卡片没写清＝停卡退回。**收尾核对**：批末收尾只核对表上名字与实际落地一致（改名则回表），不刷任何批次字段；实现批禁写该文件的现行红线不变（process-conventions §3 第 11 条），核对义务归收尾提交。三层模型见 §8.9。改动—验收对照表纪律不变：新增或改写的每条断言仍须挂一行（上文「测试侧」）；断言改判仍受 §8.4 真实入口口径约束。
|
||||
|
||||
**新增 core 件的覆盖登记义务（2026-11-03 架构审查 P1 余项裁）**：拆件或重构产出的新 core 文件不触发 process-conventions §3 第 6 条「新功能必配新测试」（那条只管新增玩法/机制），因此单由本条承接——新 core 件要么被 `game/tests/` 某套件按文件名或 `class_name` 点名，要么在承接它的能力行「代表用例」里申报「经宿主链覆盖（宿主＝<件>）」；两者都无＝批末收尾核对时补登。本条**不是覆盖率要求**，与 §7「覆盖率不是目标」同轨：登记的是能力义务的归属，不做文件计数——「每个 core 件必须被点名一次」的机器闸已裁否（它逼出为点名而点名的空套件，且与 §7 正面冲突）。落笔面沿用现行分工：申报行由写卡段入能力清单（实现批禁写该文件），核对归批末收尾提交。
|
||||
|
||||
### 8.4 真实入口断言（验收闭合的主判据）
|
||||
|
||||
- **唯一口径（2026-10-24／2026-10-28 用户两裁）**：每个需求点与每个行为改动的验收＝一条从真实入口进入的断言，可 grep 定位、在当轮真实跑批中执行并通过。**禁变异类测试**（把生产码或数据表改成错值看断言抓不抓得到）；**禁撤销类取证**（回退本批改动或该 hunk 看断言红不红）——两者都是人为制造红，属伪造证据，一律禁止。
|
||||
|
||||
Reference in new issue
Block a user