From 1379810e09c1df2d45047b9011166381a56fa18f Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 03:41:38 +0800 Subject: [PATCH 1/8] =?UTF-8?q?=E5=B7=A5=E7=A8=8B(=E8=BD=A6=E9=81=93?= =?UTF-8?q?=E9=93=81=E5=BE=8B):=20=E7=9B=B4=E6=94=B9=E8=BD=A6=E9=81=93?= =?UTF-8?q?=E9=A6=96=E4=B8=AA=E7=9C=9F=E5=AE=9E=E6=8F=90=E4=BA=A4=E2=80=94?= =?UTF-8?q?=E2=80=94=E5=B7=A5=E7=A8=8B=E6=94=B9=E5=8A=A8=E6=8A=A5=E5=91=8A?= =?UTF-8?q?=E8=90=BD=E6=A1=A3=EF=BC=88V2=20=E9=AA=8C=E8=AF=81=E5=85=BC?= =?UTF-8?q?=E8=AF=84=E4=BC=B0=E4=B8=80=E6=A0=B7=E6=9C=AC=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reports/工程改动报告-车道铁律-2026-10-26.md | 45 +++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 reports/工程改动报告-车道铁律-2026-10-26.md diff --git a/reports/工程改动报告-车道铁律-2026-10-26.md b/reports/工程改动报告-车道铁律-2026-10-26.md new file mode 100644 index 00000000..f6e03f9d --- /dev/null +++ b/reports/工程改动报告-车道铁律-2026-10-26.md @@ -0,0 +1,45 @@ +# 工程改动报告——车道铁律换代（worktree 收窄＋直改闸） + +2026-10-26 · 本批=工程改动＋文档设计改动混合批，用户逐点裁决后发令执行 · 按旧流程 worktree 落地合回（e2cc26ec），合回后新规即时生效 + +## 改了什么 + +**规则换代**：2026-09-19 立的「一切改动走独立 worktree」铁律，改为**车道铁律**——判据与改动域划分同一（文件性质）：代码面（`game/` 下非 `.md` 行为载体）唯一强制 worktree；其余一切面（含 `game/` 内 `.md`）主工作区直改＋直提，验收＝commit 点 git pre-commit 钩子现场跑 `--docs`（秒级），绿落地红拦，无回执流程。动机：文档维护类小改动高频，全套 worktree 仪式成本远超改动本身；机检强度不降级——绑定点从 merge 挪到 commit，验的就是提交字节。 + +**落地件**（worktree 批 lane-reform-20261026，6 文件）： + +| 件 | 内容 | +|---|---| +| `tools/hooks/pre-commit`（新增，版本化） | 直改闸：staged 判代码面（game/ 非非 md）；非代码面→现场跑 `run_all_gates.sh --docs`；代码面→主区拦／worktree 跳过；两段拒绝文案（新增红／闸自身故障） | +| `.gitattributes`（新增） | `tools/hooks/* text eol=lf`——autocrlf=true 下检出转 CRLF 会毁 bash 钩子 | +| `tools/run_all_gates.sh` | 开工自检：`core.hooksPath` 失位且默认钩子位无 pre-commit→红＋自愈命令（防换机/重克隆后静默免验） | +| `AGENTS.md` | 红线第一条换代＋验收段/四类段/导航表/Layout 五处同步 | +| `design/engineering/process-conventions.md` | §1 整节改写（两车道＋执法分层）＋§2/§3 四处扫尾 | +| `design/engineering/architecture/architecture.md` | 测试与质量域新增「车道分层执法」登记（两层职责表＋不对称取舍依据） | + +**本机件**（`.zcode/`，不入 git，主区直改）：`worktree-guard.sh` 车道化收窄（Edit/Write 只拦代码面；commit 只拦 staged 含代码面＋`-a` 形态查工作区；新增 `--no-verify`/`-n` agent 禁用拦截；合回闸零改——推域判据已被同日另批改为文件性质，天然一致）＋四技能（doc-design/iter-plan/asset-ingest/batch-closure）车道条款与收尾闸口径 11 处。`core.hooksPath=tools/hooks` 已配置（worktree 共享）。 + +## 验证结果（七条全过，撤销对应改动均可复现变红） + +| # | 测试 | 结果 | +|---|---|---| +| V1 | 临时分支造红（新根文件绊熵增闸）→commit | 钩子跑闸→红项可见→文案 A 逐字→提交中止，分支尖未动 | +| V2 | 本报告直提 master | 走真实直改车道（见下「评估」） | +| V3 | 主区 Edit `game/core/damage_math.gd` | 守卫拦，文案正确，文件零改动 | +| V4a | bash 改 game 文件→stage→单独 commit | ZCode 层按 staged 路径拦 | +| V4b | `add&&commit` 单命令链（ZCode 层看不到 stage） | git 层接住：`[直改闸] 主工作区禁止直提代码面`，master 零位移 | +| V5 | `git commit --no-verify` | ZCode 层拦（agent 禁用该旗标） | +| V6 | 临时 worktree 双提交 | docs 提交 7.3s 过闸落地（冷检出钩子执行正常＝LF 钉死生效）；game 提交跳闸秒落 | +| V7 | 带代码面的分支无回执 merge 进 master | 合回闸六况照常拦＋按域指引（回归确认零改） | + +## 评估（真实任务） + +1. **重量减轻（已测）**：本报告＝新规后第一个真实直改提交——动作数 2（写文件→add+commit，闸自动），对照旧流程 8 动作（建 worktree→搬运→改→跑闸→冻结件核→并 master→merge→删区）。 +2. **冷启动 AI 检验（待用户开新会话）**：布置一次真实小文档改动＋一次造红修红，观察冷 AI 不建 worktree、零游戏测试、红后动作收敛于修红重提。 +3. **game/ 车道零扰回归（待下一迭代批）**：定义入库提交约 +6s（预期）、代码提交零打扰、合回闸行为不变，记入该批实现报告。 + +## 边界与遗留 + +- 合并前已在途的旧 worktree（camp-art-doc ×2、camp-prompts-doc、iter37-plan、mutation-purge、quotaface）检出无钩子文件——git 对缺位钩子静默跳过，零打扰；其下次并入 master 后自然纳入执法。 +- 守卫 `--no-verify`/`-n` 判定是词法匹配（与既有词法判同精度级），消息值误报理论存在；git 层直改闸为最终兜底。 +- 主区 `game/tests/.gates/receipt.json` 现为 V1 测试残留（红回执，gitignored），下次任何跑批覆写，无影响。 From f52cf0d7637648360df87012829f9ebd695cf58f Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 03:47:54 +0800 Subject: [PATCH 2/8] =?UTF-8?q?=E6=A0=B8=E6=9F=A5(=E9=80=80=E5=BD=B9?= =?UTF-8?q?=E8=B7=AF=E5=BE=84):=20design/research=20=E6=B4=BB=E5=BC=95?= =?UTF-8?q?=E7=94=A8=E5=85=A8=E4=BB=93=E6=A0=B8=E6=9F=A5=E8=AE=B0=E5=BD=95?= =?UTF-8?q?=E8=90=BD=E6=A1=A3=E2=80=94=E2=80=94=E7=8E=B0=E8=A1=8C=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E9=9B=B6=E6=B4=BB=E5=BC=95=E7=94=A8=EF=BC=88=E5=91=BD?= =?UTF-8?q?=E4=B8=AD=E7=9A=86=E5=B7=B2=E9=80=80=E5=BD=B9=E5=A3=B0=E6=98=8E?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E9=9B=B6=E4=BF=AE=E6=94=B9=EF=BC=9B=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E9=9D=A2=E4=B8=A4=E5=A4=84=E9=99=88=E6=97=A7=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=E6=8C=87=E9=92=88=E7=95=99=E5=BE=85=E5=B7=A5=E7=A8=8B?= =?UTF-8?q?=E8=BD=A6=E9=81=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reports/车道核查-退役路径引用-2026-10-26.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 reports/车道核查-退役路径引用-2026-10-26.md diff --git a/reports/车道核查-退役路径引用-2026-10-26.md b/reports/车道核查-退役路径引用-2026-10-26.md new file mode 100644 index 00000000..a99386b5 --- /dev/null +++ b/reports/车道核查-退役路径引用-2026-10-26.md @@ -0,0 +1,5 @@ +# 车道核查：退役路径 design/research/ 的活引用（2026-10-26） + +- 查了什么：全仓 md（链接与正文指针）＋非 md 载体，关键词 `design/research`；`design/` 下已无该目录。 +- 命中什么：md 三处——AGENTS.md 两处、doc-conventions.md §11 一处、道具退役素材库.md 头注一处，均为「已退役」声明或历史迁出注记，非活引用，未动。非 md 四处——`tools/repo_structure_audit.py` 退役清单与 `tools/doc_ref_audit.py` 件头注（执法件自身，非活引用）；另有 `game/data/tables/shop.tres` 与 `game/presentation/views/tile_palette.gd` 各一处注释仍把 `design/research/...md` 当权威出处指向，目标文件已不在（`reports/` 无同名件），属代码面陈旧指针，本次不动，留待工程改动车道处理。 +- 改没改：现行文档零活引用，本核查零修改；本文为唯一产出。 From afdf8bf55e6fd5fb2e9e8057a01ca66da771230a Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 03:49:57 +0800 Subject: [PATCH 3/8] =?UTF-8?q?=E6=A0=B8=E6=9F=A5(=E9=80=80=E5=BD=B9?= =?UTF-8?q?=E8=B7=AF=E5=BE=84):=20=E8=AE=B0=E5=BD=95=E8=AE=A1=E6=95=B0?= =?UTF-8?q?=E8=AE=A2=E6=AD=A3=E2=80=94=E2=80=94md=20=E5=91=BD=E4=B8=AD?= =?UTF-8?q?=E5=9B=9B=E5=A4=84=EF=BC=88=E4=B8=89=E4=BB=BD=E6=96=87=E4=BB=B6?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E5=8E=9F=E8=AF=AF=E5=86=99=E4=B8=89=E5=A4=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reports/车道核查-退役路径引用-2026-10-26.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reports/车道核查-退役路径引用-2026-10-26.md b/reports/车道核查-退役路径引用-2026-10-26.md index a99386b5..a7cbb11a 100644 --- a/reports/车道核查-退役路径引用-2026-10-26.md +++ b/reports/车道核查-退役路径引用-2026-10-26.md @@ -1,5 +1,5 @@ # 车道核查：退役路径 design/research/ 的活引用（2026-10-26） - 查了什么：全仓 md（链接与正文指针）＋非 md 载体，关键词 `design/research`；`design/` 下已无该目录。 -- 命中什么：md 三处——AGENTS.md 两处、doc-conventions.md §11 一处、道具退役素材库.md 头注一处，均为「已退役」声明或历史迁出注记，非活引用，未动。非 md 四处——`tools/repo_structure_audit.py` 退役清单与 `tools/doc_ref_audit.py` 件头注（执法件自身，非活引用）；另有 `game/data/tables/shop.tres` 与 `game/presentation/views/tile_palette.gd` 各一处注释仍把 `design/research/...md` 当权威出处指向，目标文件已不在（`reports/` 无同名件），属代码面陈旧指针，本次不动，留待工程改动车道处理。 +- 命中什么：md 四处（三份文件）——AGENTS.md 两处、doc-conventions.md §11 一处、道具退役素材库.md 头注一处，均为「已退役」声明或历史迁出注记，非活引用，未动。非 md 四处——`tools/repo_structure_audit.py` 退役清单与 `tools/doc_ref_audit.py` 件头注（执法件自身，非活引用）；另有 `game/data/tables/shop.tres` 与 `game/presentation/views/tile_palette.gd` 各一处注释仍把 `design/research/...md` 当权威出处指向，目标文件已不在（`reports/` 无同名件），属代码面陈旧指针，本次不动，留待工程改动车道处理。 - 改没改：现行文档零活引用，本核查零修改；本文为唯一产出。 From 88914222b6f970cee219583b4c92642c47d64134 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 03:52:48 +0800 Subject: [PATCH 4/8] =?UTF-8?q?=E5=B7=A5=E7=A8=8B(=E8=BD=A6=E9=81=93?= =?UTF-8?q?=E9=93=81=E5=BE=8B):=20=E8=AF=84=E4=BC=B0=E4=BA=8C=E7=BB=93?= =?UTF-8?q?=E6=9E=9C=E8=90=BD=E6=A1=A3=E2=80=94=E2=80=94=E5=AD=90=E4=BB=A3?= =?UTF-8?q?=E7=90=86=E5=86=B7=E5=90=AF=E5=8A=A8=E5=85=A8=E8=BF=87=EF=BC=9B?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=AE=9E=E6=B5=8B=EF=BC=9A=E5=AD=90=E4=BB=A3?= =?UTF-8?q?=E7=90=86=E5=B7=A5=E5=85=B7=E8=B0=83=E7=94=A8=E4=B8=8D=E7=BB=8F?= =?UTF-8?q?=20ZCode=20=E5=AE=88=E5=8D=AB=E5=B1=82=EF=BC=8Cgit=20=E5=B1=82?= =?UTF-8?q?=E4=B8=BA=E5=94=AF=E4=B8=80=E5=85=A8=E6=8F=90=E4=BA=A4=E8=80=85?= =?UTF-8?q?=E6=89=A7=E6=B3=95=E5=B1=82=EF=BC=88=E8=93=84=E6=84=8F=20--no-v?= =?UTF-8?q?erify=20=E4=B8=BA=E6=AE=8B=E4=BD=99=E6=9A=B4=E9=9C=B2=E9=9D=A2?= =?UTF-8?q?=EF=BC=8C=E7=99=BB=E8=AE=B0=20architecture=20=E8=BD=A6=E9=81=93?= =?UTF-8?q?=E8=8A=82=EF=BC=89=EF=BC=9B=E5=AE=88=E5=8D=AB=E6=97=97=E6=A0=87?= =?UTF-8?q?=E6=A3=80=E6=9F=A5=E6=94=B9=E6=89=AB=20-m=20=E5=89=8D=E5=8F=82?= =?UTF-8?q?=E6=95=B0=E5=8C=BA=EF=BC=88=E6=B6=88=E6=81=AF=E6=8F=90=E5=8F=8A?= =?UTF-8?q?=E6=97=97=E6=A0=87=E5=90=8D=E8=AF=AF=E6=8B=A6=EF=BC=8C=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E8=B8=A9=E4=B8=AD=E5=8D=B3=E4=BF=AE=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/engineering/architecture/architecture.md | 2 +- reports/工程改动报告-车道铁律-2026-10-26.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index e044f528..2c04a094 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -226,7 +226,7 @@ | **git pre-commit 钩子** | `tools/hooks/pre-commit`（版本化本体，`core.hooksPath` 挂载；在位性由 run_all_gates.sh 跑批自检——失位即红） | 直改车道闸机检：staged 不含代码面的提交，提交点现场跑 `run_all_gates.sh --docs`（秒级文本扫描），绿落地红拦；staged 含代码面时主工作区＝拦（代码面唯一合法路径＝worktree 批合回）、任务 worktree＝跳过（归批末闸＋合回闸，不打扰迭代批中间提交） | staged 文件性质＋主区/worktree 判定（git-dir 与 common-dir 同一＝主区） | | **worktree-guard**（ZCode PreToolUse） | `.zcode/hooks/worktree-guard.sh`（本机件，不入 git） | agent 侧车道纪律：主工作区代码面的 Edit/Write 与 staged 含代码面的 commit 拦截；`git commit --no-verify` 拦截（该旗标仅属用户）；合回闸回执六况校验 | 路径性质＋分支名＋回执 JSON＋git 图 | -取舍依据：失败代价不对称——docs 红是死链/术语/格式，下次任何跑批对基线比对必暴露、秒级修复，故文档面轻执法（commit 点闸、无回执流程）；代码面红是运行时行为坏，保留「worktree＋批末域闸＋回执硬绑定」全套。git 层钩子对一切提交者生效（含用户手工提交，紧急出口 `--no-verify`）；ZCode 层只约束 agent。 +取舍依据：失败代价不对称——docs 红是死链/术语/格式，下次任何跑批对基线比对必暴露、秒级修复，故文档面轻执法（commit 点闸、无回执流程）；代码面红是运行时行为坏，保留「worktree＋批末域闸＋回执硬绑定」全套。git 层钩子对一切提交者生效（含用户手工提交，紧急出口 `--no-verify`）；ZCode 层只约束 agent。子代理覆盖面（2026-10-26 冷启动评估实测）：子代理的工具调用不经过 ZCode 层守卫（代码面 Edit 未被拦、`--no-verify` 探针未被拦）——ZCode 层实际只覆盖主会话工具调用，git 层因此是唯一覆盖一切提交者的执法层；残余暴露面＝蓄意 `--no-verify`（pre-commit 族钩子被该旗标整族跳过，git 层无法自防），属故意越权而非遗忘型失误，与防遗忘的设计目标正交。 ### 三条判定硬闸现行状态 diff --git a/reports/工程改动报告-车道铁律-2026-10-26.md b/reports/工程改动报告-车道铁律-2026-10-26.md index f6e03f9d..d43a9079 100644 --- a/reports/工程改动报告-车道铁律-2026-10-26.md +++ b/reports/工程改动报告-车道铁律-2026-10-26.md @@ -35,7 +35,7 @@ ## 评估（真实任务） 1. **重量减轻（已测）**：本报告＝新规后第一个真实直改提交——动作数 2（写文件→add+commit，闸自动），对照旧流程 8 动作（建 worktree→搬运→改→跑闸→冻结件核→并 master→merge→删区）。 -2. **冷启动 AI 检验（待用户开新会话）**：布置一次真实小文档改动＋一次造红修红，观察冷 AI 不建 worktree、零游戏测试、红后动作收敛于修红重提。 +2. **冷启动 AI 检验（已完成——2026-10-26 用户裁以子代理代行，提示词仿当日真实批令口吻）**：全过——零 worktree、零游戏测试、零手动跑闸（闸全部由 commit 点钩子自动跑，共 3 次 2 绿 1 红）、造红被拦后读日志定位红因→清理→无扩大测试。附带真发现：代码面两处陈旧 `design/research` 注释指针（shop.tres:98、tile_palette.gd:11，见核查记录）留待工程车道。**架构发现**：子代理工具调用不经过 ZCode 守卫层（代码面 Edit 未拦、`--no-verify` 未拦）——git 层是唯一全提交者执法层，正常提交路径全被拦；残余暴露面＝蓄意 `--no-verify`，已在 architecture.md 车道节登记。 3. **game/ 车道零扰回归（待下一迭代批）**：定义入库提交约 +6s（预期）、代码提交零打扰、合回闸行为不变，记入该批实现报告。 ## 边界与遗留 From ecac5dfc89f4f0623a30dd08058295a3e90dcae9 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 04:08:17 +0800 Subject: [PATCH 5/8] =?UTF-8?q?=E5=B7=A5=E5=85=B7(=E7=99=BB=E8=AE=B0):=20?= =?UTF-8?q?=E8=A7=84=E7=BA=A6=E8=AF=BB=E5=8F=96=E9=92=A9=E5=AD=90=E5=B1=82?= =?UTF-8?q?=E6=9D=A1=E7=9B=AE=EF=BC=88=E5=BE=85=E6=89=A7=E8=A1=8C=EF=BC=89?= =?UTF-8?q?=E2=80=94=E2=80=94=E8=AF=BB=E6=8A=95=E9=80=92=EF=BC=8B=E5=86=99?= =?UTF-8?q?=E9=97=B8=EF=BC=8B=E5=AE=88=E5=8D=AB=E5=BF=AB=E9=80=9F=E9=80=9A?= =?UTF-8?q?=E9=81=93=EF=BC=8C=E6=94=B9=E5=8A=A8=E9=9D=A2=E5=85=A8=E5=9C=A8?= =?UTF-8?q?=20.zcode/=20=E4=B8=8D=E5=85=A5=20git?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 待办清单.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/待办清单.md b/待办清单.md index 83ffe989..7217b4e3 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,6 +2,15 @@ 本清单是流水线的唯一登记处：要做的事先在此登记一条，随流水线段推进改状态，做完整条删除；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据含可选优先级，正文＝实况/缺口/改动面/状态四属性）与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 +#### 规约读取钩子层——读投递＋写闸＋守卫快速通道（2026-10-26 登记，来源=会话提及） + +**实况**：证据＝2026-10-25 导航触发排查与调研（OpenAI harness engineering＋symphony＋社区实证：指令文件是上下文非强制；本会话实测守卫每次触发 ~1.24s、事故会话累计 ~72s）。用户裁：走钩子层——①PostToolUse(Read) 规约投递闸：读到 design/、game/ 文件即注入对应规约要点（每会话每域一次）＋读规约本体记 read: 读取记录；②规则闸并入 worktree-guard：Edit/Write 写 design/、game/ 与 Bash 文件触碰动词＋路径命中两域时，读取记录缺对应规约条目即拦（记录文件不存在＝投递闸未运行→闸不启用，fail-open 成对出现）；③守卫快速通道：worktree 内 Edit 族免 python＋git（~0.2s）。改动全部在 .zcode/（不入 git，主区直改）；记录按会话失效。子代理不经守卫层（2026-10-26 车道铁律批 88914222 实测）→ 子代理兜底＝spawn 提示词带规约要求。 +- 相关文档 .zcode/hooks/rule-delivery.sh（新建）、worktree-guard.sh、config.json；方案全文＝2026-10-26 会话呈报（十项验证清单同批执行） + +**改动面**：工具代码 + +**状态**：待执行 + #### AdventureRunner 职责真拆分——三宿主共 25 条转发属性属 S13 计数迎合装置，须按变化原因重立协作件（2026-10-25 登记，来源=批次移交，优先级＝P0） **实况**： From 2999203f18374dd925e58204f00282b25a657044 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 04:15:29 +0800 Subject: [PATCH 6/8] =?UTF-8?q?=E5=B7=A5=E5=85=B7(=E5=87=BA=E8=B4=A6):=20?= =?UTF-8?q?=E8=A7=84=E7=BA=A6=E8=AF=BB=E5=8F=96=E9=92=A9=E5=AD=90=E5=B1=82?= =?UTF-8?q?=E6=9D=A1=E7=9B=AE=E5=AE=8C=E6=88=90=E5=8D=B3=E5=88=A0=E2=80=94?= =?UTF-8?q?=E2=80=94=E4=B8=89=E4=BB=B6=E5=B7=B2=E8=90=BD=E5=9C=B0=E5=B9=B6?= =?UTF-8?q?=E8=BF=87=E5=8D=81=E9=A1=B9=E9=AA=8C=E8=AF=81=EF=BC=88=E6=8A=95?= =?UTF-8?q?=E9=80=92/=E5=86=99=E9=97=B8/=E5=BF=AB=E9=80=9F=E9=80=9A?= =?UTF-8?q?=E9=81=93=20332ms=EF=BC=8C=E5=85=A8=E9=83=A8=E7=BA=AF=20bash=20?= =?UTF-8?q?=E5=86=85=E5=BB=BA=E9=9B=B6=E9=A2=9D=E5=A4=96=E8=BF=9B=E7=A8=8B?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E6=94=B9=E5=8A=A8=E5=9C=A8=20.zcode/=20?= =?UTF-8?q?=E4=B8=8D=E5=85=A5=20git?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 待办清单.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/待办清单.md b/待办清单.md index 7217b4e3..83ffe989 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,15 +2,6 @@ 本清单是流水线的唯一登记处：要做的事先在此登记一条，随流水线段推进改状态，做完整条删除；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据含可选优先级，正文＝实况/缺口/改动面/状态四属性）与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 -#### 规约读取钩子层——读投递＋写闸＋守卫快速通道（2026-10-26 登记，来源=会话提及） - -**实况**：证据＝2026-10-25 导航触发排查与调研（OpenAI harness engineering＋symphony＋社区实证：指令文件是上下文非强制；本会话实测守卫每次触发 ~1.24s、事故会话累计 ~72s）。用户裁：走钩子层——①PostToolUse(Read) 规约投递闸：读到 design/、game/ 文件即注入对应规约要点（每会话每域一次）＋读规约本体记 read: 读取记录；②规则闸并入 worktree-guard：Edit/Write 写 design/、game/ 与 Bash 文件触碰动词＋路径命中两域时，读取记录缺对应规约条目即拦（记录文件不存在＝投递闸未运行→闸不启用，fail-open 成对出现）；③守卫快速通道：worktree 内 Edit 族免 python＋git（~0.2s）。改动全部在 .zcode/（不入 git，主区直改）；记录按会话失效。子代理不经守卫层（2026-10-26 车道铁律批 88914222 实测）→ 子代理兜底＝spawn 提示词带规约要求。 -- 相关文档 .zcode/hooks/rule-delivery.sh（新建）、worktree-guard.sh、config.json；方案全文＝2026-10-26 会话呈报（十项验证清单同批执行） - -**改动面**：工具代码 - -**状态**：待执行 - #### AdventureRunner 职责真拆分——三宿主共 25 条转发属性属 S13 计数迎合装置，须按变化原因重立协作件（2026-10-25 登记，来源=批次移交，优先级＝P0） **实况**： From b6f11c1f8aaee732a25563f2f301e110130f5e2f Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 04:54:43 +0800 Subject: [PATCH 7/8] =?UTF-8?q?docs(=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3?= =?UTF-8?q?=C2=B7=E7=9F=A5=E8=AF=86=E6=B2=89=E6=B7=80=E6=89=B9):=20?= =?UTF-8?q?=E4=B8=89=E4=BB=B6=E8=A1=A5=E6=96=87=E2=80=94=E2=80=94=E9=80=9A?= =?UTF-8?q?=E4=BF=A1=E5=BD=A2=E6=80=81=E9=80=89=E5=9E=8B=E7=90=86=E7=94=B1?= =?UTF-8?q?(=E6=95=B0=E6=8D=AE=E6=B5=81=C2=A72:=E5=90=8C=E6=AD=A5=E7=9B=B4?= =?UTF-8?q?=E8=BF=9E=3D=E5=8F=AF=E5=9B=9E=E6=94=BE=E7=BA=A2=E7=BA=BF,Godot?= =?UTF-8?q?=E4=BF=A1=E5=8F=B7=3D=E5=90=8C=E6=AD=A5=E6=B4=BE=E5=8F=91,?= =?UTF-8?q?=E6=97=A0=E4=BA=8B=E4=BB=B6=E5=BE=AA=E7=8E=AF)=EF=BC=8B?= =?UTF-8?q?=E6=95=88=E6=9E=9C=E5=BC=95=E6=93=8E=E3=80=8C=E5=85=A8=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=E8=A7=A3=E9=87=8A=E5=99=A8=E4=B8=8D=E6=98=AF=E4=BA=8B?= =?UTF-8?q?=E4=BB=B6=E6=80=BB=E7=BA=BF=E3=80=8D=E5=AE=9A=E4=BD=8D(?= =?UTF-8?q?=E5=9F=BA=E7=A1=80=E5=B1=82=E8=A1=A8,=E5=88=A0T3=E6=89=A9?= =?UTF-8?q?=E7=AD=BE=E5=86=BB=E7=BB=93=E8=AE=A1=E6=95=B0=E6=8B=AC=E6=B3=A8?= =?UTF-8?q?)=EF=BC=8B=E6=9E=B6=E6=9E=84=E5=8E=9F=E5=88=999=E3=80=8C?= =?UTF-8?q?=E5=81=9C=E7=82=B9=E6=9D=83=E5=A8=81=E5=9C=A8=E6=A0=B8=E5=BF=83?= =?UTF-8?q?=E5=B1=82=E3=80=8D(=E4=B8=A4=E5=B1=82=E9=98=BB=E5=A1=9E?= =?UTF-8?q?=E6=9C=BA=E5=88=B6)=EF=BC=9B=E5=8D=81=E5=A4=84=E5=88=A0?= =?UTF-8?q?=E6=94=B9=E2=80=94=E2=80=94=E6=9C=AA=E5=86=B3=E9=97=AE=E9=A2=98?= =?UTF-8?q?=E8=A1=A8=E5=B7=B2=E8=90=BD=E5=AE=9A=E4=B8=89=E8=A1=8C(QQ-01/02?= =?UTF-8?q?/03,gdUnit4=E5=86=B3=E5=AE=9A=E8=BF=81=E6=B5=8B=E8=AF=95?= =?UTF-8?q?=E4=B8=8E=E8=B4=A8=E9=87=8F=E5=9F=9F)=EF=BC=8B=E5=BC=95?= =?UTF-8?q?=E6=93=8E=E7=9F=A5=E8=AF=86=E7=BC=BA=E5=8F=A3=E8=8A=82=E5=8E=8B?= =?UTF-8?q?=E7=BC=A9=E4=B8=BAengine-reference=E6=8C=87=E9=92=88=EF=BC=8B?= =?UTF-8?q?=E8=A6=86=E7=9B=96GDD=E8=A1=8C=E5=85=AB=E8=AE=A1=E6=95=B0?= =?UTF-8?q?=E6=99=AE=E6=9F=A5=E6=94=B9=E6=A0=B9=E7=B4=A2=E5=BC=95=E6=8C=87?= =?UTF-8?q?=E9=92=88=EF=BC=8B=E5=B1=82=E9=A1=B9=E3=80=8C18=E9=A1=B9?= =?UTF-8?q?=E3=80=8D=E4=B8=A4=E5=A4=84=E5=86=BB=E7=BB=93=E8=AE=A1=E6=95=B0?= =?UTF-8?q?=EF=BC=8BRngService=E6=B5=81=E8=AF=8D=E8=A1=A8=E6=9E=9A?= =?UTF-8?q?=E4=B8=BE=E6=94=B9PURPOSE=5FTAGS=E6=8C=87=E9=92=88(=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E7=BC=BA=E4=B9=9D=E6=B5=81)=EF=BC=8B=E5=AD=98?= =?UTF-8?q?=E6=A1=A3=E8=B7=AF=E5=BE=84=E8=8A=82=E3=80=8CMVP=E6=97=A0?= =?UTF-8?q?=E5=AD=98=E6=A1=A3=E3=80=8D=E8=BF=87=E6=97=B6=E9=99=88=E8=BF=B0?= =?UTF-8?q?=E4=B8=8E=E6=97=A7=E5=A5=91=E7=BA=A6=E5=8F=A5=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?(=E6=84=8F=E5=9B=BE=E5=BA=8F=E5=88=97/=E7=AA=97=E5=8F=A3?= =?UTF-8?q?=E9=80=89=E6=8B=A9=E5=BA=8F=E5=88=97=E5=B7=B2=E9=9D=9E=E7=8E=B0?= =?UTF-8?q?=E8=A1=8C)=EF=BC=8BMVP=E5=85=B3=E9=94=AE=E8=B7=AF=E5=BE=84?= =?UTF-8?q?=E8=A1=8C=EF=BC=8B=E6=95=B0=E6=8D=AE=E6=B5=81=E8=8A=82=E9=87=8D?= =?UTF-8?q?=E5=8F=B74=E2=86=925=EF=BC=9Bdoc-conventions=20=C2=A75=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E3=80=8C=E6=B4=BB=E4=BD=93=E6=B8=85=E5=8D=95=E4=B8=8D?= =?UTF-8?q?=E5=86=BB=E7=BB=93=E8=AE=A1=E6=95=B0=E3=80=8D(=E4=B8=89?= =?UTF-8?q?=E5=AE=9E=E4=BE=8B=E8=AF=84=E4=BC=B0)=EF=BC=9Barchitecture=20v1?= =?UTF-8?q?.14=E2=86=92v1.15=EF=BC=9B=E5=BE=85=E5=8A=9E=E6=B8=85=E5=8D=95?= =?UTF-8?q?=E7=99=BB=E8=AE=B0=E7=9B=B4=E6=94=B9=E6=89=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../engineering/architecture/architecture.md | 40 ++++++++----------- design/engineering/doc-conventions.md | 1 + 待办清单.md | 9 +++++ 3 files changed, 26 insertions(+), 24 deletions(-) diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index 2c04a094..7b71b09c 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,11 +2,11 @@ ## 文档状态 -- 版本：1.14 -- 最近更新：2026-10-26（改动域判据由路径前缀改为文件性质——`game/` 内 `.md` 归文档域） +- 版本：1.15 +- 最近更新：2026-10-26（通信形态选型理由、效果引擎定位、架构原则 9 停点机制补文＋已落定未决项、过时陈述与冻结计数清扫） - 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定） - 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调） -- 覆盖 GDD：现行全集——`design/gdd/` 顶层 00–08 共 9 件 + `systems/` 五域 25 件（排雷循环 4 / 战斗循环 5 / 冒险循环 5 / 跨局循环 5 / 表现与支撑 6）+ `ux/` 8 件；原英文命名 12 份系统 GDD 已全部迁入中文域目录，原「未设计」预留（A5 扫雷秘宝 / C1–C4 / B5 / D3–D6）均已立项成文 +- 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准） - 事实源地位：本文是架构事实的唯一来源——分层/所有权/数据流/API 边界/测试与质量域均以本文为准；历史决策沿革查 git commit log，不另设决策文档体系 - 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；测试层级＝冒烟/单元/集成/系统四级＋UI 探针与渲染 golden（2026-10-22 用户裁，测试术语与层级重构批），闸机按改动域分跑在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计 - 技术总监签核：2026-09-12 — 有条件通过（原条件「决策记录须于正式工程骨架前定稿」已满足：骨架已成、沿革在 git 历史可查；`.claude/docs/director-gates.md` 缺失已登记技术债） @@ -16,13 +16,9 @@ ## 引擎知识缺口摘要 -- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `design/engineering/engine-reference/godot/breaking-changes.md` 与 `deprecated-apis.md`；**结论：无一条破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）。 +- 引擎事实现行事实源＝`design/engineering/engine-reference/godot/`（VERSION / breaking-changes / deprecated-apis / current-best-practices 四件）——迁移核实结论、语义变化与编码注意一律查那里，本文不重复。 +- 渲染器与窗口基座＝gl_compatibility + 1280×800（2026-09-12 裁）；UI/渲染域为引擎风险集中地，采纳引擎增量前对照 engine-reference 核实。 - 写码纪律不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 核实后再用；4.8（dev 阶段）稳定版发布后跑 `/setup-engine refresh`。 -- 三类必须入编码纪律的引擎事实（详见 `design/engineering/engine-reference/godot/current-best-practices.md`）： - 1. **GDScript 4.7 两条语义变化**：打包数组元素赋值不再触发属性 setter；类型化返回的方法覆盖必须显式 `return`。 - 2. **新项目默认值已变**：stretch mode `canvas_items` / aspect `expand`（4.7）；Windows 渲染驱动 D3D12（4.6，仅 Forward+ 线）——创建 project.godot 后逐项核对。 - 3. `Resource.duplicate(true)` 深复制不再覆盖外部子资源——D2 表资源复制语义注意。 -- 残余风险敞口：modules/ 分域参考未建（按实现期需要建，非阻塞）；UI/渲染域（D1/B5）为 MEDIUM 风险集中地——渲染器与窗口基座已定（gl_compatibility + 1280×800，2026-09-12），采纳引擎增量前对照文档核实。 --- @@ -77,7 +73,6 @@ | D3 存档序列化 | 基础层 | Alpha | ✅ | LOW | | D6 设置/本地化 | 基础层 | 完整愿景 | ✅ | LOW | -**MVP 关键路径**（实现已验证）：D2 → A3/A4/B3 → A1 → A2 → B2/B4 → B1 → D1-lite。 **依赖分层与唯一回边**：A2 只外发三事件（cell_revealed / flag_judged / round_end），B4/B1 订阅后回调——A2 不依赖任何下游（TD-SYSTEM-BOUNDARY 裁决，全项目唯一允许回边）。 --- @@ -91,11 +86,11 @@ | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| | **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机 | 类型化属性读取；`load_tables(root, collect_only)`；`resolve()`（R1 floor）；debug override；`set_reload_gate()`；诊断收集器 | 无（基础层顶点） | Resource/.tres 加载、autoload 生命周期——LOW | -| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流：board_gen / reward_roll；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 | +| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流词表现值以 `RngServiceCore.PURPOSE_TAGS` 为准；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 | | **action_economy**（A3） | AP/RAP 账本、last_round_end、轮次相位机 {Idle, Active, Waiting}、结束仲裁 | 意图与通知布尔面：notify_round_start / request_dig / request_stop / request_refresh / notify_settlement_done / notify_combat_end；预授权通道：grant_reserve_ap / finish_round_stop；ap/rap/phase 只读 | ConfigDB（ActionEconomyTable）；effect_engine（事件发射 dispatch——基础层内同层引用）；B1 回发 next_round_mode/battle_over | 无 | | **variation 定义**（A4） | VariationTable schema（现行 6 行：六 region——贫矿脉 global 行 2026-10-16 用户令屏蔽删行，global 型机制代码保留）与 F1 候选池门控谓词 | `variant_pool(level_index, board_type, node_type="")`（门控三维：unlock+board_types+节点身份——global 行仅 boss/elite 入池，缺省跳过零扰动）；`global_variant_row(level_index, board_type, node_type)`（全局型单行决议访问器） | ConfigDB（VariationTable） | 无 | | **status_container**（B3） | 状态实例容器（战斗域生命周期、跨轮跨图延续） | 5 API：notify_battle_start / apply_effect / query_active / decay_round / notify_battle_end | ConfigDB（StatusEffectTable） | 无（RefCounted） | -| **effect_engine**（内容数据驱动扩展批 iter17 建域） | 零运行时可变状态的系统（见「架构原则」条 8）：事件/事实/效果类型/算子四词表封闭（迭代 21 T3 扩签：EVENTS 18→19 +seal_missed 标错判定、FACTS +battle_index 关卡域战斗序）+ 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·adv_ 前缀走冒险桶跨战斗持久） | rebuild（每战重建订阅表）/`dispatch(ctx, event, payload, facts)`/`validate_trigger_row` + 静态计数口 `counter`·`counter_add`·`counter_spend`·`bucket_of`·`counter_id_legal`（计数器读写只经 EffectContext 引用束，无导出/灌入接口） | ConfigDB（feats/treasure 行集）、EffectContext（四桶引用由宿主持有：round/battle 桶归编排器、level 桶归关卡域、adventure 桶归 RunLedger） | 无（零随机全确定） | +| **effect_engine**（内容数据驱动扩展批 iter17 建域） | 零运行时可变状态的系统（见「架构原则」条 8）：全同步解释器——事件由宿主在明确代码点位显式调 dispatch 进件，命中序＝装载声明序（feats→treasure→树规则）写死保种子复放，不是事件总线/事件循环；事件/事实/效果类型/算子四词表封闭 + 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·adv_ 前缀走冒险桶跨战斗持久） | rebuild（每战重建订阅表）/`dispatch(ctx, event, payload, facts)`/`validate_trigger_row` + 静态计数口 `counter`·`counter_add`·`counter_spend`·`bucket_of`·`counter_id_legal`（计数器读写只经 EffectContext 引用束，无导出/灌入接口） | ConfigDB（feats/treasure 行集）、EffectContext（四桶引用由宿主持有：round/battle 桶归编排器、level 桶归关卡域、adventure 桶归 RunLedger） | 无（零随机全确定） | | **save_system**（D3，Alpha；iter27 已升格 autoload「SaveManager」） | 存档格式与版本比较 | （契约规范源：`../../gdd/systems/表现与支撑/存档序列化.md`——契约锚：SCHEMA_VERSION + master_seed + 各流 scope 计数器快照，须在无正在执行中的 open_stream 实例时切出） | ConfigDB、RngService 只读计数器 | FileAccess——LOW | | **settings/localization**（D6，愿景） | 设置项、翻译数据 | （契约规范源：`../../gdd/systems/表现与支撑/设置与本地化.md`） | ConfigDB | 无 | @@ -161,9 +156,9 @@ ### 视觉层装配合同 -- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（现行 18 项，kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。 +- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。 - 全仓唯一落位口 = `_apply_layer_contract()`（装配尾统一排序+登记）；散落 `move_child` 由冒烟 V1d 源码断言判红；**改层序只改合同表**。 -- 具体层清单不复制进本文（双写失同步禁令）——查现行 18 项直接读 `main.gd`。 +- 具体层清单不复制进本文（双写失同步禁令）——查现行层项直接读 `main.gd`。 ### 会话生命周期（RunScope） @@ -194,7 +189,7 @@ ## 测试与质量域 -> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。 +> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。第三方测试框架（gdUnit4）经 2026-09-12 评估不引入，现行测试载体＝本节自制闸体系。 ### 模块归属 @@ -311,21 +306,20 @@ B1 ──install_board / retire_board──▶ A2 B1 ──generate(L,D)─ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB display_name ``` -- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。 +- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。选型理由＝可回放（架构原则 3）：同步直连让调用顺序显式可见，「同种子逐位相同」才可断言；Godot 信号本身就是同步函数派发，全库不存在事件循环。事件驱动形态服务的是并发/IO 场景对外部不确定时序的反应性，与本作「顺序确定」的需求相反。 - 事件规范序：A2 发射序 = 触发格 BFS、8 邻行主序；事件序契约 `flag_judged` < `round_end` 全路径统一。 - **呈现层订阅禁令（切片缺陷②教训固化）**：呈现层永不直接订阅 排雷玩法／行动经济 的事件流，只订 战斗结算 步骤流与 `level_runner`——核心事件形态变化不得直接冲击界面。 -### 3. 存档/读档路径（MVP 无存档；契约已锁） +### 3. 存档/读档路径 -- MVP 无元进度持久化（C4/D3 归 Alpha）。**已锁契约**：续玩/复盘快照 = master_seed + 各流 scope 计数器 + 意图序列 + 窗口选择序列；快照切出须发生在无正在执行中的 `open_stream` 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）。 -- 可回放性已实证：切片冒烟同种子双跑步骤流逐行相同（B1 AC-33 前身）。 -- D3 Alpha 期按此契约设计格式；SCHEMA_VERSION 高版本拒读。 +- 存档系统已实装：格式、三槽位、断点域与迁移链的现行契约以 `design/gdd/systems/表现与支撑/存档序列化.md`（owner）为准。 +- RNG 快照契约（现行仍成立）：断点续玩回填 = master_seed + 各流 scope 计数器；快照切出须发生在无正在执行中的 open_stream 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）；SCHEMA_VERSION 高版本拒读。 ### 4. 打包与字体（CJK 随包发行） CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无中文字形。此项是 HUD框架 正式化的硬性前置，同时进导出 checklist 核对项。 -### 4. 初始化顺序 +### 5. 初始化顺序 ``` 进程启动 @@ -380,6 +374,7 @@ CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无 6. **依赖单向 + 组合根模式**——层间单向依赖、唯一回边 = A2 事件订阅面；核心写调用唯一发生在组合根；禁上帝对象（切片 1100 行 main.gd 反面案例 → 9 单元拆分）。 7. **呈现层契约成文**——面向呈现的信号载荷必须有成文 schema；模态覆盖层必须有"打开时遮挡物隐藏"场景级断言；场景级 UI 探针测试为标配（切片缺陷 ①②④⑤ 教训沉淀）。 8. **系统无状态**——效果引擎这类系统零运行时可变状态：数据由宿主对象持有并随宿主生灭，状态按参数传入系统，系统只做判定（立项判据=2026-10-19 用户会话裁定；落地=迭代 32 卡②，2026-10-21 用户裁写入）。系统实例不持计数器——计数器住桶（round/battle/level/adventure 四桶，EffectContext 引用束），桶住宿主。 +9. **停点权威在核心层**——玩家决策停点（选路、三选一、商店、恢复这类）的推进守卫住核心层状态机：停点未兑付，推进口一律拒绝（零自动推进契约）；呈现层模态只做开合与输入锁——阻塞是两层结构，核心守卫为权威、模态为体验；停点态是核心状态、随断点序列化，headless 跑批与真实局同一套规则，中断续玩恢复到同一停点。 --- @@ -387,9 +382,6 @@ CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无 | ID | Summary | Priority | Resolution Path | |----|---------|----------|-----------------| -| QQ-01 | 渲染器选择（Forward+ vs gl_compatibility）与项目窗口基线 | High | **已落定**（2026-09-12）：gl_compatibility + 1280×800 基座（canvas_items + expand）；沿革见 git 历史 | -| QQ-02 | 事件总线载体与 A2 事件捕获测试 API | High | **已落定**（2026-09-12）：组合根直连 signal + Waiting 相位触发；autoload 全局总线否决 | -| QQ-03 | gdUnit4 是否引入并迁移冒烟用例 | Medium | **已落定**：deferred（现行双载体承载；D2 OQ1 关闭） | | QQ-04 | 轮内刷新数值连锁（清图支配性条款⑤ / 真人刷图行为获取期望）重算 | Medium | playtest 实测 | | QQ-05 | 战斗末可选类"j==0 补发 1 件"兜底是否采纳（切片遗留待办） | Medium | playtest + B4 GDD 修订批 | | QQ-06 | 可选类退出格子池后 buff 频率被动上升（44%→59%）的难度对冲杠杆（敌 HP / 权重 / 幅度） | High | C3 调参 + 切片数据复测 | diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index cb333f1a..1689565f 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -69,6 +69,7 @@ | 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | | 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | | 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | +| 活体清单不冻结计数 | 对会生长的清单（文档树构成、UI 层项、RNG 流词表等）不写死计数与枚举——写指针到 owner（根索引/常量表/实现文件），现状值由 owner 承载；历史计数只进 git 提交信息 | **数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。 diff --git a/待办清单.md b/待办清单.md index 83ffe989..f2423fdc 100644 --- a/待办清单.md +++ b/待办清单.md @@ -19,6 +19,15 @@ **状态**：待文档设计 +#### 架构文档知识沉淀与冻结计数清扫批——通信选型理由/效果引擎定位/停点原则补文＋过时陈述删改（2026-10-26 登记，来源=会话提及） + +**实况**：来源＝AdventureRunner 拆分设计会话（原会话进行中）的架构讨论沉淀＋顺带删除扫描，方案经用户逐条审毕。三件补文＋十处删改落 architecture.md（v1.14→v1.15）；含可选项＝MVP 关键路径行删除与 doc-conventions §5「活体清单不冻结计数」规则（用户审定顺带执行）。总线不立的裁定与现行登记一致，零动作。证据＝三处实测——RngService 行流词表记 2 流而 game/core/rng_service.gd:9 PURPOSE_TAGS 实为 11 流；层项「18 项」两处计数写死（v1.14 视觉层装配合同节）；数据流§3「MVP 无存档」与存档系统现行事实（game/core/save_manager.gd，存档序列化.md v7）相反。 +- 相关文档：design/engineering/architecture/architecture.md v1.15（本批产出） + +**改动面**：文档 + +**状态**：待执行 + #### 超预算图策略升级路径——等比缩放与滚动视口两案待裁（2026-10-24 登记，来源=批次移交） **实况**：迭代 34 卡④（信息迷雾可见性批，已合回 master，提交 16a7ec80）按「参数限图」交付，图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图，两条升级路径都要动冻结件，均未设计：①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值；②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13，已超出该上限（level-map 已登记随动缺口，本批不裁方案）。 From 24f07dc409956172643127b4b1e1a8076ca1bee9 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Mon, 26 Oct 2026 04:55:06 +0800 Subject: [PATCH 8/8] =?UTF-8?q?docs(=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3?= =?UTF-8?q?=C2=B7=E7=9F=A5=E8=AF=86=E6=B2=89=E6=B7=80=E6=89=B9):=20?= =?UTF-8?q?=E6=89=B9=E6=9C=AB=E6=94=B6=E5=B0=BE=E2=80=94=E2=80=94=E5=BE=85?= =?UTF-8?q?=E5=8A=9E=E6=B8=85=E5=8D=95=E6=9D=A1=E7=9B=AE=E5=88=A0=E9=99=A4?= =?UTF-8?q?=EF=BC=88=E4=BA=A7=E5=87=BA=E5=B7=B2=E8=90=BD=20architecture.md?= =?UTF-8?q?=20v1.15=EF=BC=8Bdoc-conventions=20=C2=A75=EF=BC=8Ccommit=20b6f?= =?UTF-8?q?11c1f=EF=BC=8C=E5=AE=8C=E6=88=90=E5=8D=B3=E5=88=A0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 待办清单.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/待办清单.md b/待办清单.md index f2423fdc..83ffe989 100644 --- a/待办清单.md +++ b/待办清单.md @@ -19,15 +19,6 @@ **状态**：待文档设计 -#### 架构文档知识沉淀与冻结计数清扫批——通信选型理由/效果引擎定位/停点原则补文＋过时陈述删改（2026-10-26 登记，来源=会话提及） - -**实况**：来源＝AdventureRunner 拆分设计会话（原会话进行中）的架构讨论沉淀＋顺带删除扫描，方案经用户逐条审毕。三件补文＋十处删改落 architecture.md（v1.14→v1.15）；含可选项＝MVP 关键路径行删除与 doc-conventions §5「活体清单不冻结计数」规则（用户审定顺带执行）。总线不立的裁定与现行登记一致，零动作。证据＝三处实测——RngService 行流词表记 2 流而 game/core/rng_service.gd:9 PURPOSE_TAGS 实为 11 流；层项「18 项」两处计数写死（v1.14 视觉层装配合同节）；数据流§3「MVP 无存档」与存档系统现行事实（game/core/save_manager.gd，存档序列化.md v7）相反。 -- 相关文档：design/engineering/architecture/architecture.md v1.15（本批产出） - -**改动面**：文档 - -**状态**：待执行 - #### 超预算图策略升级路径——等比缩放与滚动视口两案待裁（2026-10-24 登记，来源=批次移交） **实况**：迭代 34 卡④（信息迷雾可见性批，已合回 master，提交 16a7ec80）按「参数限图」交付，图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图，两条升级路径都要动冻结件，均未设计：①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值；②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13，已超出该上限（level-map 已登记随动缺口，本批不裁方案）。