From 6d77b7fbf019ad60fb0517d15dbd802b4ea84280 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 19:11:03 +0800 Subject: [PATCH 1/9] =?UTF-8?q?docs(=E7=99=BB=E8=AE=B0):=20=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E5=AF=BC=E8=88=AA=E8=A7=A6=E5=8F=91=E6=97=B6=E6=9C=BA?= =?UTF-8?q?=E5=89=8D=E7=A7=BB=E6=9D=A1=E7=9B=AE=EF=BC=88=E5=BE=85=E6=89=A7?= =?UTF-8?q?=E8=A1=8C=EF=BC=89=E2=80=94=E2=80=94=E8=AF=BB=E8=A7=84=E5=88=99?= =?UTF-8?q?=E4=BB=8E=E5=8A=A8=E6=89=8B=E5=89=8D=E6=8F=90=E5=89=8D=E5=88=B0?= =?UTF-8?q?=E5=AE=9A=E6=96=B9=E6=A1=88=E5=89=8D=EF=BC=8C=E8=AF=81=E6=8D=AE?= =?UTF-8?q?=EF=BC=9D2026-10-25=20=E6=9E=B6=E6=9E=84=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=E4=BC=9A=E8=AF=9D=E8=AE=A8=E8=AE=BA=E6=9C=9F=E6=9C=AA=E8=AF=BB?= =?UTF-8?q?=E8=A7=84=E7=BA=A6=E6=8B=BC=E6=96=B9=E6=A1=88=E8=A1=A5=E8=AF=BB?= =?UTF-8?q?=E5=90=8E=E6=92=A4=E5=9B=9E?= 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 e1cdb0b3..018c9f07 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,6 +2,15 @@ 本清单是流水线的唯一登记处:要做的事先在此登记一条,随流水线段推进改状态,做完整条删除;各系统文档的「待办」节只留一行指路存根,不再自建条目。条目格式(标题=登记元数据含可选优先级,正文=实况/缺口/改动面/状态四属性)与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 +#### 规范导航触发时机前移——读规则提前到定方案前(2026-10-25 登记,来源=会话提及) + +**实况**:证据=2026-10-25 会话 session_2aa5792b53f16f98417c6a552e5ecf4d 模型 IO 日志 r37–r39:「架构与规范对齐批」讨论期 Agent 未读 doc-conventions 即拼出落文方案,用户发问后才补读并自检撤回(原案违 concept-conventions §1 附加物封装与 doc-conventions §5 正文单点维护)。根因=AGENTS.md「规范导航」触发词只写「写文档/改文档前」,方案讨论期不触发——管住了写、没管住定方案。用户裁:触发时机前移,确认写什么内容之前就得读规则约束。 +- 相关文档 AGENTS.md「规范导航」节与文首指针行、design/engineering/doc-conventions.md 文首标题行 + +**改动面**:文档 + +**状态**:待执行 + #### 超预算图策略升级路径——等比缩放与滚动视口两案待裁(2026-10-24 登记,来源=批次移交) **实况**:迭代 34 卡④(信息迷雾可见性批,已合回 master,提交 16a7ec80)按「参数限图」交付,图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图,两条升级路径都要动冻结件,均未设计:①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值;②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13,已超出该上限(level-map 已登记随动缺口,本批不裁方案)。 From c36f97d77895d7796d92b756377215b8132e1b8f Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 19:11:04 +0800 Subject: [PATCH 2/9] =?UTF-8?q?docs(=E8=A7=84=E5=88=99=E4=BF=AE=E8=AE=A2):?= =?UTF-8?q?=20=E8=A7=84=E8=8C=83=E5=AF=BC=E8=88=AA=E8=A7=A6=E5=8F=91?= =?UTF-8?q?=E5=89=8D=E7=A7=BB=E2=80=94=E2=80=94=E8=AF=BB=E8=A7=84=E5=88=99?= =?UTF-8?q?=E4=BB=8E=E3=80=8C=E5=86=99X=E5=89=8D=E3=80=8D=E6=8F=90?= =?UTF-8?q?=E5=89=8D=E5=88=B0=E3=80=8C=E5=AE=9AX=E6=96=B9=E6=A1=88?= =?UTF-8?q?=E5=89=8D=E3=80=8D=EF=BC=9AAGENTS.md=20=E6=96=87=E9=A6=96?= =?UTF-8?q?=E6=8C=87=E9=92=88=E4=B8=8E=E5=AF=BC=E8=88=AA=E8=A1=A8=E5=A4=B4?= =?UTF-8?q?=E6=94=B9=E3=80=8C=E5=AE=9A=E6=96=B9=E6=A1=88=E5=89=8D=E5=85=88?= =?UTF-8?q?=E6=9F=A5=EF=BC=88=E7=A1=AE=E8=AE=A4=E5=86=99=E4=BB=80=E4=B9=88?= =?UTF-8?q?=E5=86=85=E5=AE=B9=E4=B9=8B=E5=89=8D=E8=AF=BB=E8=A7=84=E5=88=99?= =?UTF-8?q?=EF=BC=8C=E4=B8=8D=E6=98=AF=E5=8A=A8=E6=89=8B=E5=89=8D=E6=89=8D?= =?UTF-8?q?=E8=AF=BB=EF=BC=89=E3=80=8D=EF=BC=8B=E4=BB=A3=E7=A0=81/?= =?UTF-8?q?=E6=B5=8B=E8=AF=95/=E6=96=87=E6=A1=A3=E4=B8=89=E8=A1=8C?= =?UTF-8?q?=E6=97=B6=E6=9C=BA=E6=A0=BC=E5=90=84=E5=89=8D=E7=BD=AE=E3=80=8C?= =?UTF-8?q?=E5=AE=9AX=E6=96=B9=E6=A1=88=E3=80=8D=E6=AE=B5=EF=BC=8Cdoc-conv?= =?UTF-8?q?entions=20=E6=96=87=E9=A6=96=E6=A0=87=E9=A2=98=E3=80=8C?= =?UTF-8?q?=E5=86=99=E6=96=87=E6=A1=A3=E5=89=8D=E5=BF=85=E8=AF=BB=E3=80=8D?= =?UTF-8?q?=E6=94=B9=E3=80=8C=E5=AE=9A=E6=96=87=E6=A1=A3=E6=96=B9=E6=A1=88?= =?UTF-8?q?=E5=89=8D=E5=BF=85=E8=AF=BB=E3=80=8D=EF=BC=882026-10-25=20?= =?UTF-8?q?=E7=94=A8=E6=88=B7=E8=A3=81=EF=BC=9B=E8=B5=B7=E5=9B=A0=EF=BC=9D?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=AF=B9=E9=BD=90=E4=BC=9A=E8=AF=9D=E8=AE=A8?= =?UTF-8?q?=E8=AE=BA=E6=9C=9F=E6=9C=AA=E8=AF=BB=E8=A7=84=E7=BA=A6=E6=8B=BC?= =?UTF-8?q?=E6=96=B9=E6=A1=88=E3=80=81=E8=A1=A5=E8=AF=BB=E5=90=8E=E4=B8=A4?= =?UTF-8?q?=E5=A4=84=E8=BF=9D=E4=BE=8B=E6=92=A4=E5=9B=9E=E2=80=94=E2=80=94?= =?UTF-8?q?=E6=97=A7=E8=A7=A6=E5=8F=91=E8=AF=8D=E5=8F=AA=E7=AE=A1=E5=86=99?= =?UTF-8?q?=E3=80=81=E6=B2=A1=E7=AE=A1=E4=BD=8F=E5=AE=9A=E6=96=B9=E6=A1=88?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 10 +++++----- design/engineering/doc-conventions.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1226851d..12f662b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ 扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发,MVP 优先管线。 设计入口:`design/gdd/02-系统清单.md`(根索引)· 概念:`design/gdd/00-游戏概念.md` -> 本文件只保留全局元信息与硬性红线索引;领域细则在子文档,动手前先查「规范导航」。 +> 本文件只保留全局元信息与硬性红线索引;领域细则在子文档,定方案前先查「规范导航」。 ## Technology Stack @@ -36,15 +36,15 @@ - `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/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,不另设决策文档 | diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index fc2d36bb..cb333f1a 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -1,4 +1,4 @@ -# 文档写作规范(写文档前必读) +# 文档写作规范(定文档方案前必读) > **地位**:本文是文档写作的规范权威,与 `design/engineering/code-conventions.md`(代码规范)对等;AGENTS.md 只留导航指针,细则以本文为准。 > **适用范围**:`design/` 下一切现行文档与根目录 `roadmap.md`;概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。 From d121d653634a5eb33a019e7c80b0648623890946 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 19:11:47 +0800 Subject: [PATCH 3/9] =?UTF-8?q?docs(=E5=87=BA=E8=B4=A6):=20=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E5=AF=BC=E8=88=AA=E8=A7=A6=E5=8F=91=E6=97=B6=E6=9C=BA?= =?UTF-8?q?=E5=89=8D=E7=A7=BB=E6=9D=A1=E7=9B=AE=E5=AE=8C=E6=88=90=E5=8D=B3?= =?UTF-8?q?=E5=88=A0=E2=80=94=E2=80=94=E6=94=B9=E5=8A=A8=E5=B7=B2=E9=9A=8F?= =?UTF-8?q?=E6=9C=AC=E6=89=B9=E8=90=BD=E6=96=87=EF=BC=88c36f97d7=EF=BC=89?= =?UTF-8?q?=EF=BC=8C--docs=20=E5=9F=9F=E9=97=B8=E5=85=A8=E7=BB=BF?= 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 018c9f07..e1cdb0b3 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,15 +2,6 @@ 本清单是流水线的唯一登记处:要做的事先在此登记一条,随流水线段推进改状态,做完整条删除;各系统文档的「待办」节只留一行指路存根,不再自建条目。条目格式(标题=登记元数据含可选优先级,正文=实况/缺口/改动面/状态四属性)与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 -#### 规范导航触发时机前移——读规则提前到定方案前(2026-10-25 登记,来源=会话提及) - -**实况**:证据=2026-10-25 会话 session_2aa5792b53f16f98417c6a552e5ecf4d 模型 IO 日志 r37–r39:「架构与规范对齐批」讨论期 Agent 未读 doc-conventions 即拼出落文方案,用户发问后才补读并自检撤回(原案违 concept-conventions §1 附加物封装与 doc-conventions §5 正文单点维护)。根因=AGENTS.md「规范导航」触发词只写「写文档/改文档前」,方案讨论期不触发——管住了写、没管住定方案。用户裁:触发时机前移,确认写什么内容之前就得读规则约束。 -- 相关文档 AGENTS.md「规范导航」节与文首指针行、design/engineering/doc-conventions.md 文首标题行 - -**改动面**:文档 - -**状态**:待执行 - #### 超预算图策略升级路径——等比缩放与滚动视口两案待裁(2026-10-24 登记,来源=批次移交) **实况**:迭代 34 卡④(信息迷雾可见性批,已合回 master,提交 16a7ec80)按「参数限图」交付,图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图,两条升级路径都要动冻结件,均未设计:①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值;②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13,已超出该上限(level-map 已登记随动缺口,本批不裁方案)。 From db532f54fa676e5c1b6d31fadbc8123649bbcb04 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 20:20:48 +0800 Subject: [PATCH 4/9] =?UTF-8?q?docs(=E7=99=BB=E8=AE=B0):=20concept-convent?= =?UTF-8?q?ions=20=E8=AF=BB=E8=A7=A6=E5=8F=91=E5=89=8D=E7=A7=BB=E6=9D=A1?= =?UTF-8?q?=E7=9B=AE=EF=BC=88=E5=BE=85=E6=89=A7=E8=A1=8C=EF=BC=89=E2=80=94?= =?UTF-8?q?=E2=80=94=E6=A6=82=E5=BF=B5=E5=BB=BA=E6=A8=A1=E8=AF=BB=E8=A7=84?= =?UTF-8?q?=E7=BA=A6=E6=8F=90=E5=89=8D=E5=88=B0=E5=AE=9A=E6=96=B9=E6=A1=88?= =?UTF-8?q?=E5=89=8D=EF=BC=8C=E6=89=BF=E6=8E=A5=E5=AF=BC=E8=88=AA=E5=89=8D?= =?UTF-8?q?=E7=A7=BB=E6=89=B9=E6=8E=92=E6=9F=A5=E5=87=BA=E7=9A=84=E5=90=8C?= =?UTF-8?q?=E6=AC=BE=E6=97=B6=E6=9C=BA=E9=94=99=E4=BD=8D?= 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 e1cdb0b3..46c994b4 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,6 +2,15 @@ 本清单是流水线的唯一登记处:要做的事先在此登记一条,随流水线段推进改状态,做完整条删除;各系统文档的「待办」节只留一行指路存根,不再自建条目。条目格式(标题=登记元数据含可选优先级,正文=实况/缺口/改动面/状态四属性)与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 +#### concept-conventions 读触发前移——概念建模读规约提前到定方案前(2026-10-25 登记,来源=会话提及) + +**实况**:证据=2026-10-25 触发时机排查(承接导航触发前移批 d121d653):concept-conventions.md 文首「写设计文档前必须通读本文」与已修的 doc-conventions 同款时机错位——概念建模实际发生在文档方案讨论期,本文 §1(附加物封装)正是被撤回原方案违反的条款(会话 session_2aa5792b53f16f98417c6a552e5ecf4d 模型 IO 日志 r37–r39),补读却发生在用户发问之后。用户裁:本批只修本文档两处触发词前移。 +- 相关文档 design/engineering/concept-conventions.md 文首与 §1 首句;AGENTS.md「规范导航」(d121d653 已前移) + +**改动面**:文档 + +**状态**:待执行 + #### 超预算图策略升级路径——等比缩放与滚动视口两案待裁(2026-10-24 登记,来源=批次移交) **实况**:迭代 34 卡④(信息迷雾可见性批,已合回 master,提交 16a7ec80)按「参数限图」交付,图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图,两条升级路径都要动冻结件,均未设计:①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值;②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13,已超出该上限(level-map 已登记随动缺口,本批不裁方案)。 From 752e33670039dddefbabf969d7fe420be47209d9 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 20:20:49 +0800 Subject: [PATCH 5/9] =?UTF-8?q?docs(=E8=A7=84=E5=88=99=E4=BF=AE=E8=AE=A2):?= =?UTF-8?q?=20concept-conventions=20=E8=AF=BB=E8=A7=A6=E5=8F=91=E5=89=8D?= =?UTF-8?q?=E7=A7=BB=E2=80=94=E2=80=94=E6=96=87=E9=A6=96=E3=80=8C=E5=86=99?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3=E5=89=8D=E5=BF=85=E9=A1=BB?= =?UTF-8?q?=E9=80=9A=E8=AF=BB=E3=80=8D=E6=94=B9=E3=80=8C=E5=AE=9A=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=96=B9=E6=A1=88=E5=89=8D=E5=BF=85=E9=A1=BB=E9=80=9A?= =?UTF-8?q?=E8=AF=BB=E3=80=8D=EF=BC=8B=C2=A71=20=E9=A6=96=E5=8F=A5?= =?UTF-8?q?=E3=80=8C=E5=8A=A8=E7=AC=94=E4=B9=8B=E5=89=8D=E5=85=88=E5=81=9A?= =?UTF-8?q?=E6=A6=82=E5=BF=B5=E5=BB=BA=E6=A8=A1=E3=80=8D=E6=94=B9=E3=80=8C?= =?UTF-8?q?=E5=AE=9A=E6=96=B9=E6=A1=88=E5=89=8D=E5=85=88=E5=81=9A=E6=A6=82?= =?UTF-8?q?=E5=BF=B5=E5=BB=BA=E6=A8=A1=E3=80=8D=EF=BC=882026-10-25=20?= =?UTF-8?q?=E7=94=A8=E6=88=B7=E8=A3=81=EF=BC=8C=E5=8F=AA=E4=BF=AE=E6=9C=AC?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9B=E6=9C=AC=E6=96=87=20=C2=A71=20?= =?UTF-8?q?=E9=99=84=E5=8A=A0=E7=89=A9=E5=B0=81=E8=A3=85=E6=AD=A3=E6=98=AF?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=AF=B9=E9=BD=90=E4=BC=9A=E8=AF=9D=E8=A2=AB?= =?UTF-8?q?=E6=92=A4=E5=9B=9E=E6=96=B9=E6=A1=88=E7=9A=84=E8=BF=9D=E4=BE=8B?= =?UTF-8?q?=E6=9D=A1=E6=AC=BE=E2=80=94=E2=80=94=E6=A6=82=E5=BF=B5=E5=BB=BA?= =?UTF-8?q?=E6=A8=A1=E5=AE=9E=E9=99=85=E5=8F=91=E7=94=9F=E5=9C=A8=E6=96=B9?= =?UTF-8?q?=E6=A1=88=E8=AE=A8=E8=AE=BA=E6=9C=9F=EF=BC=8C=E8=AF=BB=E8=A7=A6?= =?UTF-8?q?=E5=8F=91=E5=8D=B4=E5=9C=A8=E5=8A=A8=E7=AC=94=E6=9C=9F=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/engineering/concept-conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/design/engineering/concept-conventions.md b/design/engineering/concept-conventions.md index e2fc2a33..58370433 100644 --- a/design/engineering/concept-conventions.md +++ b/design/engineering/concept-conventions.md @@ -3,13 +3,13 @@ > 约束范围:设计文档的概念建模与跨文档引用。写作层(句子、结构、骨架)归 `design/engineering/doc-conventions.md`;本文管概念怎么切、文档怎么互链。 > 概念只在 owner 文档里定义一次;跨系统术语的规范名、定义与互斥关系登记在 `design/gdd/术语表.md`。某概念被谁引用,靠全仓搜索它的规范名得出,不设第二处登记表。 -**写设计文档前必须通读本文。** +**定文档方案前必须通读本文。** --- ## 1. 概念封装纪律(概念对象化建模) -动笔之前先做概念建模:像写代码划分对象那样,把设计切成分界清晰的概念——每个概念有自己的规范名、自己的属性、自己的规则,概念之间靠显式关系(包含、挂载、引用)连接,而不是把所有内容揉进一个概念里。概念没有边界,删除修改就得全仓翻找。 +定方案前先做概念建模:像写代码划分对象那样,把设计切成分界清晰的概念——每个概念有自己的规范名、自己的属性、自己的规则,概念之间靠显式关系(包含、挂载、引用)连接,而不是把所有内容揉进一个概念里。概念没有边界,删除修改就得全仓翻找。 | 规则 | 内容 | |---|---| From 79d8ee9562496f7d4e0c33c65f11688fce85e995 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 20:21:13 +0800 Subject: [PATCH 6/9] =?UTF-8?q?docs(=E5=87=BA=E8=B4=A6):=20concept-convent?= =?UTF-8?q?ions=20=E8=AF=BB=E8=A7=A6=E5=8F=91=E5=89=8D=E7=A7=BB=E6=9D=A1?= =?UTF-8?q?=E7=9B=AE=E5=AE=8C=E6=88=90=E5=8D=B3=E5=88=A0=E2=80=94=E2=80=94?= =?UTF-8?q?=E6=94=B9=E5=8A=A8=E5=B7=B2=E9=9A=8F=E6=9C=AC=E6=89=B9=E8=90=BD?= =?UTF-8?q?=E6=96=87=EF=BC=88752e3367=EF=BC=89=EF=BC=8C--docs=20=E5=9F=9F?= =?UTF-8?q?=E9=97=B8=E5=85=A8=E7=BB=BF?= 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 46c994b4..e1cdb0b3 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,15 +2,6 @@ 本清单是流水线的唯一登记处:要做的事先在此登记一条,随流水线段推进改状态,做完整条删除;各系统文档的「待办」节只留一行指路存根,不再自建条目。条目格式(标题=登记元数据含可选优先级,正文=实况/缺口/改动面/状态四属性)与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 -#### concept-conventions 读触发前移——概念建模读规约提前到定方案前(2026-10-25 登记,来源=会话提及) - -**实况**:证据=2026-10-25 触发时机排查(承接导航触发前移批 d121d653):concept-conventions.md 文首「写设计文档前必须通读本文」与已修的 doc-conventions 同款时机错位——概念建模实际发生在文档方案讨论期,本文 §1(附加物封装)正是被撤回原方案违反的条款(会话 session_2aa5792b53f16f98417c6a552e5ecf4d 模型 IO 日志 r37–r39),补读却发生在用户发问之后。用户裁:本批只修本文档两处触发词前移。 -- 相关文档 design/engineering/concept-conventions.md 文首与 §1 首句;AGENTS.md「规范导航」(d121d653 已前移) - -**改动面**:文档 - -**状态**:待执行 - #### 超预算图策略升级路径——等比缩放与滚动视口两案待裁(2026-10-24 登记,来源=批次移交) **实况**:迭代 34 卡④(信息迷雾可见性批,已合回 master,提交 16a7ec80)按「参数限图」交付,图包络约 10 层×8 槽即当前冻结画布的屏预算上限。若后续定值批需要更大的完整可见图,两条升级路径都要动冻结件,均未设计:①等比缩放——动「节点图标 20px 烘焙 1:1」与「通道折线冻结 2/3/4px」两条冻结值;②滚动视口——新增视口交互范式。迭代 35 生成图实测深度域 L3 达 0–13,已超出该上限(level-map 已登记随动缺口,本批不裁方案)。 From bcb5cce3b64567e02d080c1ef784f574ef13466f Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 20:22:04 +0800 Subject: [PATCH 7/9] =?UTF-8?q?docs(=E6=9E=B6=E6=9E=84=E4=B8=8E=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E5=AF=B9=E9=BD=90=E6=89=B9=C2=B7=E9=97=AD=E5=90=88?= =?UTF-8?q?=E8=90=BD=E6=96=87):=20=E2=91=A1=E6=A1=88=E7=94=B2=E7=BB=84?= =?UTF-8?q?=E5=90=88=E6=A0=B9=E6=8B=86=E4=BB=B6=E6=A6=82=E5=BF=B5=E6=88=90?= =?UTF-8?q?=E6=96=87(=E5=91=88=E7=8E=B0=E5=B1=82=E5=BD=92=E5=B1=9E?= =?UTF-8?q?=E8=A1=8C+=E8=A3=85=E9=85=8D=E8=8A=82=E5=AE=9A=E4=B9=89+code-co?= =?UTF-8?q?nventions=20=C2=A71.3=20=E6=8B=AC=E6=B3=A8,=E6=8E=A7=E5=88=B6?= =?UTF-8?q?=E5=99=A8=E4=B8=80=E8=AF=8D=E5=BC=83=E7=94=A8,=E8=A7=86?= =?UTF-8?q?=E5=9B=BE=E7=A6=81=E7=9B=B4=E8=BF=9E)+=E2=91=A2=E6=A1=88a=20eff?= =?UTF-8?q?ect=5Fengine=20=E5=9C=88=E5=B1=82=E5=BD=92=E4=BD=8D=E5=9F=BA?= =?UTF-8?q?=E7=A1=80=E5=B1=82(A3/B4=20=E6=B6=88=E8=B4=B9=E4=BE=9D=E8=B5=96?= =?UTF-8?q?=E7=99=BB=E8=AE=B0,=E5=8F=8D=E5=90=91=E4=BE=9D=E8=B5=96?= =?UTF-8?q?=E6=82=AC=E6=A1=88=E6=B6=88=E8=A7=A3);=20=E2=91=A3=E6=9D=A1?= =?UTF-8?q?=E7=9B=AE=E4=B8=83=E4=BB=B6=E5=85=A8=E7=BB=93=E6=8C=89=E5=90=B8?= =?UTF-8?q?=E6=94=B6=E5=8D=B3=E6=AD=BB=E5=88=A0=E9=99=A4,=E2=91=A6?= =?UTF-8?q?=E6=A0=A1=E9=AA=8C=E6=96=87=E6=A1=88=E6=9C=AA=E5=86=B3=E5=85=88?= =?UTF-8?q?=E8=BF=81=E7=8B=AC=E7=AB=8B=E6=9D=A1=E7=9B=AE,=E2=91=A4?= =?UTF-8?q?=E6=94=B6=E6=95=9B=E7=A0=81=E6=94=B9=E7=99=BB=E8=AE=B0=E6=89=A9?= =?UTF-8?q?=E5=B1=95=E6=80=BB=E5=9E=8B=E6=94=B6=E6=95=9B=E6=89=B9=E6=9D=A1?= =?UTF-8?q?=E7=9B=AE,S6~S8=20=E6=9D=A1=E7=9B=AE=E5=86=BB=E7=BB=93=E8=A7=A3?= =?UTF-8?q?=E9=99=A4=E6=94=B9=E5=B7=A5=E7=A8=8B=E7=9B=B4=E6=94=B9=E7=B1=BB?= =?UTF-8?q?=E5=BE=85=E6=89=A7=E8=A1=8C(2026-10-25=20=E7=94=A8=E6=88=B7?= =?UTF-8?q?=E8=A3=81=E6=A1=88=E7=94=B2/=E6=A1=88a)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../engineering/architecture/architecture.md | 12 +++++----- design/engineering/code-conventions.md | 2 +- 待办清单.md | 22 +++++++++++-------- 3 files changed, 21 insertions(+), 15 deletions(-) diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index 145f4d1b..eeafa8a6 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,8 +2,8 @@ ## 文档状态 -- 版本:1.10 -- 最近更新:2026-10-25(架构与规范对齐批部分落文——模块归属表 API 对齐实现实况+B1 域文件集成文+明细行协议两层化指针+层合同计数 18;2026-10-25 用户令) +- 版本:1.11 +- 最近更新:2026-10-25(架构与规范对齐批闭合落文——②组合根拆件概念成文〔呈现层归属+成员三件,2026-10-25 用户裁案甲〕+③effect_engine 圈层归位基础层〔A3/B4 消费依赖登记,反向依赖悬案消解,用户裁案 a〕) - 引擎: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)均已立项成文 @@ -92,9 +92,10 @@ |---|---|---|---|---| | **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(无) | 无——纯逻辑 | -| **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);B1 回发 next_round_mode/battle_over | 无 | +| **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) | 无(零随机全确定) | | **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 | 无 | @@ -105,7 +106,7 @@ | **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 / 相位 | 无(零表读取、零 UI——切片实证) | | **unit_container**(B2) | hero/enemy 单位实例(hp/atk/实例池:池快照+冷却+摇定动作+保底计数)、行值快照 | spawn / query_alive / rollable_skills / special_skills / 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 随行为环退役) | ConfigDB(EnemyTable/SkillTable/HeroTable) | 无 | -| **reward_economy**(B4) | 格面资源身份映射(install 期预分配、Ready 只读、换图映射消亡)、极性路由字典面((类型, 极性)→ 字典行查询;路由执行归 B1 授予段)、F6 当量供给投影 | 封闭 API:roll_board / query_identity / query_full_snapshot / grant / grant_clear / retire_mapping / polarity_row / phase / weighted_pick;另有 is_mapped 静默布尔投影(批量工具用) | ConfigDB(RewardTable);reward_roll 流(scope = 每次 install 批) | 无 | +| **reward_economy**(B4) | 格面资源身份映射(install 期预分配、Ready 只读、换图映射消亡)、极性路由字典面((类型, 极性)→ 字典行查询;路由执行归 B1 授予段)、F6 当量供给投影 | 封闭 API:roll_board / query_identity / query_full_snapshot / grant / grant_clear / retire_mapping / polarity_row / phase / weighted_pick;另有 is_mapped 静默布尔投影(批量工具用) | ConfigDB(RewardTable);effect_engine(事件发射 dispatch——上层消费基础层);reward_roll 流(scope = 每次 install 批) | 无 | | **helper_items**(A5,切片已实装秘宝域) | HelperItemTable、探测显影语义 | (契约规范源:`../../gdd/systems/跨局循环/秘宝.md`——桥接位:A2 查询接口 + A4 counter_item_ids) | A2 / A4 / B4 | 无 | ### 功能层 @@ -115,7 +116,6 @@ | **battle_orchestrator**(B1) | 段序骨架(七段结构冻结)、轮 facts 缓冲、可回放步骤流、[明细行协议](../../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)(基础行型+扩展行两层 + 字段分层,词表以 owner「明细流水」节为准)、条款③⑤闭合对账、**战斗域全部跨系统调用权**、效果引擎宿主(每战 rebuild;round/battle 桶为编排器自有字典、经 EffectContext 引用挂载)+ 树规则挂点施加面(posture 窗/sense 限次/守侧 seal_missed 发射/聚乘算入账前) | `begin_battle(encounter)`;窗口/刷新意图提交面(扮演 D1);`level_clear()`;步骤流(输出契约) | B2/B3/B4 全调用面(**唯一调用方=B1 域文件集:battle_orchestrator.gd + settlement/ 五段段类 + damage_controller**);A3 request_refresh 代理 + 回发;A2 install/retire + 三事件订阅;A1 generate(attempt 非 scope 事件);D2 SettlementTable + set_reload_gate | 无(零随机、禁 await——切片 88 冒烟实证可回放) | | **damage_controller**(B1 域·伤害单据管线) | 伤害单据唯一兑现管线(单据九栏目声明→分量掷点/克制修正/伤害下限归一→明细行发射;双方同规) | 兑付入口(编排侧开单)+ fx 揭示回调注入位 | B2 单位实例(单据目标传入);B1 注入(EffectContext 引用束与编排回调) | 无 | | **settlement/ 五段段类**(B1 域·结算段件) | B1 每轮结算序列的五段逻辑件(授予/增益减益/战斗/衰减/判定——细则见下「战斗域装配现状」节) | 段处理入口(B1 接线调用);可直接 `new()` 单测 | B2/B3/B4 兑付面与 B1 轮 facts 缓冲(各段按职责) | 无 | -| **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) | 无(零随机全确定) | | **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 | 无 | @@ -131,6 +131,7 @@ | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| | **D1 HUD**(呈现面拆分持续换代:组合根 main.gd + 三屏壳(MenuScreen/CampScreen/AdventureScreen)+ views/ 视图单元(现行承载面见「呈现层装配与会话生命周期」节;早期 9 单元清单与 LevelStripView 已随场景换代退役);营地覆盖层=四柜台并排〔树淬炼主界面/锻造工坊·秘宝匣钥匙门/图鉴常开——迭代 21 T6 程序占位重排〕) | 全部 Control/CanvasLayer(例外:BoardView 棋盘本体与 BattleStageView 站桩本体 = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界〔BoardWorld/CellUnit;StageWorld/StandeeBody——B 区 slot_row 伴随件留壳层〕,探针契约面不变——棋盘 Node2D 迁移批 Phase A 2026-09-23 / 战斗舞台 Phase B 2026-09-26)、输入→意图翻译(**唯一提交路径 = settle_batch,不直调 A3**)、呈现义务状态记录(A2×6 / B2×4 / B3×4 / B4×5 / B1×3) | 视图单元接口(信号外发、setter 只读注入) | A2 compute_move_path / ActionOutcome;A3 ap/rap;B1 步骤流行协议(数据源);ConfigDB display_name | **MEDIUM**:Control / CanvasLayer / draw_* / InputEvent / RichTextLabel——对照 breaking-changes.md 4.5–4.7 条目(CanvasItem 线条无抗锯齿羽化、设备 ID 常量、RichTextLabel 图片参数两轮变化) | +| **组合根拆件**(呈现侧写口子件:curio_interact_controller / camp_shop_presenter / treasure_interact_controller) | 代组合根执行核心写调用(冒险节点后续推进/营地购买与刷新/道具使用——依赖与回调由 main 构造注入) | 各拆件的写入口(仅组合根装配面可达;视图零直连) | 构造注入的核心写引用(推进/商店/道具各域——详见各拆件头注) | 无 | | **battle_presentation**(B5,垂直切片后) | 结算动画 / 伤害数字 / 战斗舞台 | (契约规范源:`../../gdd/systems/战斗循环/战斗表现.md`——前置「战斗表现美术测试」锁双舞台陷阱) | B1 步骤流(回放脚本源)、D1 | **MEDIUM**:AnimationPlayer(String→StringName 变更)/ Tween | | **audio**(D4,Alpha) | 音频挂点 | (挂点 = B1 明细行类型流;负反馈聚合——单结算至多一次) | B1 流水 | AudioStreamPlayer(4.7 area_mask 默认 1→0 注意) | | **tutorial**(D5,Alpha) | 教学条目 | (口径来源:A2/A3/B3/B1 各教学条目) | 各上游 | 无 | @@ -145,6 +146,7 @@ - 呈现场景拆为三屏壳:MenuScreen(开始菜单屏)/CampScreen(营地屏)/AdventureScreen(冒险屏——内含关卡地图与战斗两容器)。 - 屏成员经组合根 main.gd 一级句柄暴露(探针挂载假设 `main.X` 路径零迁移);局态一律住 RunScope 节点,禁在屏/视图侧持有局态引用。 +- **组合根拆件**=组合根构造注入、代组合根执行核心写调用的呈现侧子件(现行三件:curio_interact_controller/camp_shop_presenter/treasure_interact_controller——冒险节点后续推进、营地购买与刷新、道具使用)。视图禁直连拆件;核心写调用的可达路径仍是「视图→信号→组合根(含拆件)→核心」,依赖规则与组合根单点装配不变。成员见「模块归属·呈现层」表。 ### 视觉层装配合同 diff --git a/design/engineering/code-conventions.md b/design/engineering/code-conventions.md index 508b9cc1..5824697e 100644 --- a/design/engineering/code-conventions.md +++ b/design/engineering/code-conventions.md @@ -16,7 +16,7 @@ 设计稿与实现同尺度:功能 = 类(状态 + 行为 + 信号),类是封装的最小交付单位。工具性纯函数只允许挂在明确的宿主类下(静态装配器/工厂),不允许无主散落。 ### 1.3 依赖单向,核心写调用完成 -依赖方向唯一:`views →(信号)→ 组合根 →(写调用)→ core`。视图零核心写调用(纯 setter / 信号外发优先);"读核心状态 → 拼展示文案"集中于装配器(presenter);核心写接口(settle_batch / player_request_refresh / runner 推进)只允许在组合根出现。 +依赖方向唯一:`views →(信号)→ 组合根 →(写调用)→ core`。视图零核心写调用(纯 setter / 信号外发优先);"读核心状态 → 拼展示文案"集中于装配器(presenter);核心写接口(settle_batch / player_request_refresh / runner 推进)只允许在组合根出现——组合根=main.gd+其构造注入的组合根拆件(成员与边界见架构文档「模块归属·呈现层」),视图不得直连拆件。 ### 1.4 命名 = 领域命名,禁止系统 ID 前缀 文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀(`a1_board_generator.gd` → `board_generator.gd`)。设计追溯不靠前缀:代码↔设计的追溯由 GDD 文档承担,系统 ID 只作为文档的追溯锚;文件头注不承担追溯职责,不写任何文档链接(§1.4.1)。豁免:D2 schema 类与 autoload;文档/夹具登记名(如 b4_golden)属文档层。 diff --git a/待办清单.md b/待办清单.md index e1cdb0b3..49dcde9e 100644 --- a/待办清单.md +++ b/待办清单.md @@ -30,23 +30,27 @@ #### S6/S7/S8 静态规则落地——编排唯一性/禁 await/信号纪律三闸(2026-10-24 登记,来源=审计发现) -**实况**:工程债证据=reports/审计-game代码结构审查-2026-10-24.md §二 C2:三规则 static_scan.sh TODO 在案(架构文档静态扫描表自认未落地)——S6 core↔core 信号禁 lambda 捕获 self、S7 B2/B3/B4 API 符号命中文件 ⊆ B1 文件集、S8 结算路径 await 零命中。2026-10-24 审查人工 grep 结论干净(core 零 await、A2/B3/B4 零相互直调),但防线缺位=回归无闸。S7 前置:须先在架构文档成文 B1 文件集边界(含 core/settlement/ 五段类与 damage_controller——现归属表零条目,见「架构与规范对齐批」条目①;2026-10-25 该前置已落文备齐,冻结状态不变)。**2026-10-24 用户裁:条目整条冻结待④(「架构与规范对齐批」)裁决后再写卡**——写卡会话核对结论:S6(core 信号禁 lambda)与 S8(结算路径禁 await,文件集可按现行结算文件直接枚举)与④零依赖、技术上可先行,但按「先裁④再动③」整条冻结不先行。 +**实况**:工程债证据=reports/审计-game代码结构审查-2026-10-24.md §二 C2:三规则 static_scan.sh TODO 在案(架构文档静态扫描表自认未落地)——S6 core↔core 信号禁 lambda 捕获 self、S7 B2/B3/B4 API 符号命中文件 ⊆ B1 文件集、S8 结算路径 await 零命中。2026-10-24 审查人工 grep 结论干净(core 零 await、A2/B3/B4 零相互直调),但防线缺位=回归无闸。S7 前置:须先在架构文档成文 B1 文件集边界(含 core/settlement/ 五段类与 damage_controller——现归属表零条目,见「架构与规范对齐批」条目①;2026-10-25 该前置已落文备齐,冻结状态不变)。**2026-10-24 用户裁:条目整条冻结待④(「架构与规范对齐批」)裁决后再写卡**——写卡会话核对结论:S6(core 信号禁 lambda)与 S8(结算路径禁 await,文件集可按现行结算文件直接枚举)与④零依赖、技术上可先行,但按「先裁④再动③」整条冻结不先行。**2026-10-25 解冻与改道**:「架构与规范对齐批」整条闭合(②组合根拆件成文、③effect_engine 圈层归位基础层,B1 域文件集与归属表成员上一批已落文备齐),冻结条件解除;按改动四类本条属工程改动直改类(用户 2026-10-25 明示工具代码不写卡),状态改待执行——三闸开工待用户发令。 **改动面**:工具代码 +**状态**:待执行 + +#### 效果引擎校验文案计数错误——封闭事实词表数写死「9 项」实为 18(2026-10-25 登记,来源=审计发现) + +**实况**:证据=reports/审计-game代码结构审查-2026-10-24.md §三 漂移清单第 5 条(原「架构与规范对齐批」条目⑦,该条目 2026-10-25 闭合删除、未决先迁本条):game/core/effect_engine.gd:360 校验报错文案「事实词汇封闭 9 项」实为 18 项——一行字符串修订,零行为变化。属游戏代码字符串修订,按改动四类走需求改动通道。 + +**改动面**:游戏代码 + **状态**:待写卡 -#### 架构与规范对齐批——代码结构审查发现的文档-实现漂移(2026-10-24 登记,来源=审计发现) +#### 明细行扩展总型收敛批——四个专长实名行型收敛为单一扩展行型+效果载荷(2026-10-25 登记,来源=批次移交) -**实况**:审计报告=reports/审计-game代码结构审查-2026-10-24.md(§二 C3/C4/C5+§三 漂移清单)。漂移与待裁件七件:①架构文档「模块归属」多行 API 清单与实现不符(A2 try_* 便捷形/B2 ambush_grant_plan/B4 equivalence_supply 不存在;实有 grant_reserve_ap/finish_round_stop/check_skill_unlocks 未登记;damage_controller 与 settlement/ 五段类零条目——S7 落地的前置);②code-conventions §1.3 核心写调用位置——三拆件控制器(presentation/curio_interact_controller.gd、camp_shop_presenter.gd、treasure_interact_controller.gd)持写调用 vs 规范「只允许在组合根出现」的 spec-AC 冲突,须裁「改规范成文组合根家族」vs「调用收回 main」;③A3→EffectEngine 反向依赖(core/action_economy.gd:43-49)——真违约或事实源失真二选一(effect_engine 降层登记基础层 vs B1 代发 vs 仅补登记);④架构文档 :149/151 层合同计数写死 17 项 vs LAYER_CONTRACT 实 18 项;⑤明细行协议三处三个数(头注 9/实发 13/架构文档 15);⑥§1.3 例举 submit_window_selection 符号已退役;⑦core/effect_engine.gd:360 校验文案「9 项」实为 18 项。 +**实况**:证据=game/core/battle_orchestrator.gd 文件头注(行型清单——现行四专长实名串 fx_reveal/mine_neutralized/insurance_used/fx_preview_area)+design/gdd/systems/战斗循环/战斗结算.md 明细流水节「扩展行」节(词表两层定稿:基础 9 类+扩展行 1 类,2026-10-25 用户裁「概念+指引」法,git 提交 82d0cf24)。现行实现以四个实名串承载扩展行型值。收敛=游戏代码改动:行型值并为单一扩展串、效果身份走 effect_id 载荷;随动 battle_log_view._format_row 行文案与呈现聚合、playtest_logger JSONL 对拍锚必红须重锚(重锚只能用户发起,可与「结算明细日志行序重锚批」并账一次跑);收敛落定后 owner 文档「扩展行」节的过渡句随反哺点摘除。 -**2026-10-25 部分落文(用户令执行已裁件)**:⑤明细行协议两层化(基础 9 类+扩展行 1 类;文档只写概念与指引,效果身份清单指向实现侧 battle_orchestrator.gd 头注,专长实名串永不入文档词表)落战斗结算.md 明细流水节+验收标准+来源类别豁免封闭清单五类对齐;①归属表 API 对齐实现实况(A2 撤 try_* 便捷形换查询只读面、A3 补 grant_reserve_ap/finish_round_stop、B2 换 check_skill_unlocks、B4 撤 equivalence_supply、level_runner 撤幻影 grant_node_active)+damage_controller 与 settlement/ 五段段类两行入表+B1 域文件集成文(S7 判据来源已备);④层合同计数 17→18(实数核对);⑥§1.3 例举换代 player_request_refresh。凭据=architecture.md v1.10+战斗结算.md/code-conventions.md(本批 git 提交)。 +**改动面**:游戏代码 -**缺口**:②核心写调用位置(案甲改规范成文「组合根家族=main+三拆件控制器」vs 案乙调用经回调收口回 main——乙涉游戏代码须转需求通道)与③A3→EffectEngine 反向依赖(案 a effect_engine 降登记基础层 vs 案 b B1 代发改码 vs 案 c 仅补登记消费依赖)两裁决点待用户拍板,裁后落文闭合条目;⑦校验文案改数属游戏代码字符串修订,归需求改动通道随卡顺带。 - -**改动面**:文档 - -**状态**:待文档设计 +**状态**:待写卡 #### 营地五界面窗口化批——营地功能页点开后的呈现形态(2026-10-22 登记,来源=会话提及) From 79733fa57f39fea67739da3ded977e7e7659cc46 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 20:38:52 +0800 Subject: [PATCH 8/9] =?UTF-8?q?=E5=B7=A5=E7=A8=8B(S8=E7=BB=93=E7=AE=97?= =?UTF-8?q?=E7=A6=81await=E9=97=B8):=20B1=E5=9F=9F=E6=96=87=E4=BB=B6?= =?UTF-8?q?=E9=9B=86await=E9=9B=B6=E5=91=BD=E4=B8=AD=E8=90=BD=20static=5Fs?= =?UTF-8?q?can(S13=E5=90=8E=E7=8B=AC=E7=AB=8B=E6=AE=B5,=E6=96=87=E4=BB=B6?= =?UTF-8?q?=E9=9B=86=E7=BC=BA=E4=BD=8D=E8=87=AA=E6=A3=80),=E7=9B=98?= =?UTF-8?q?=E9=9D=A2=E9=9B=B6=E5=AD=98=E9=87=8F,=E6=92=A4=E9=94=80?= =?UTF-8?q?=E8=AF=81=E6=98=8E=E7=BA=A2=E7=BB=BF=E9=97=AD=E7=8E=AF,--code?= =?UTF-8?q?=20=E5=9F=9F=E9=97=B8=E5=85=A8=E7=BB=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- game/tests/static_scan.sh | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/game/tests/static_scan.sh b/game/tests/static_scan.sh index 0582fd30..4074a72a 100644 --- a/game/tests/static_scan.sh +++ b/game/tests/static_scan.sh @@ -91,7 +91,6 @@ fi # TODO(正式工程落地后精化为扫描配置并升格为硬失败): # S6 core↔core 信号连接只许方法 Callable(禁 lambda 捕获 self);发射者禁反向引用 # S7 B2/B3/B4 API 符号命中文件 ⊆ B1 文件集(编排唯一性) -# S8 结算路径 await 零命中(B1 结算/编排文件集) # ── S11 — 代码注释禁用词 ── # 禁「板级」「门票」「正主」「落籍」「完美排雷」等退役词进注释面(完整词表见术语表解析) @@ -253,4 +252,39 @@ else fail=1 fi +# ── S8 — 结算路径 await 零命中(B1 结算/编排文件集)── +# 规则(architecture.md「静态扫描域 S1–S8 承接清单」S8 行 / D2 AC-14 口径):结算本体是 +# 可回放纯逻辑步骤流(同种子同输入逐位复现),await 会打断确定性——「模块归属」B1 行已写明 +# 「禁 await——切片 88 冒烟实证」。本闸为防回归防线(2026-10-24 人工 grep 盘面干净)。 +# 扫描面:B1 域文件集(与 architecture.md「模块归属」B1 行同口径)=battle_orchestrator.gd +# + settlement/ 五段段类 + damage_controller.gd,共 7 文件,显式清单见 S8_FILES。 +# 执行侧字面值豁免:脚本必须带字面值才能工作;文件集与架构文档冲突时以 B1 域文件集为准。 +# 判据:文件集内出现 await 关键字即红(词边界 \bawait\b,任何形态——await 信号/协程/ +# get_tree());排除注释行(行首 #/##)与字符串字面量(双引号包裹段内的 await 非代码), +# 口径仿 S1/S2 的 grep 排除手法。 +# 自检:清单内文件缺位(路径写错/被改名)即判红——防扫面为空静默绿。 +S8_FILES="game/core/battle_orchestrator.gd game/core/settlement/aura_segment.gd game/core/settlement/combat_segment.gd game/core/settlement/decay_segment.gd game/core/settlement/grant_segment.gd game/core/settlement/verdict_segment.gd game/core/damage_controller.gd" +S8_MISS=0 +for f in $S8_FILES; do + if [ ! -f "$f" ]; then + echo "[static_scan] S8 FAIL: 文件集缺位——$f 不存在(路径写错/被改名导致的静默空转)" + S8_MISS=1 + fi +done +if [ "$S8_MISS" -eq 1 ]; then + fail=1 +else + S8_HITS=$(grep -rnE '\bawait\b' $S8_FILES 2>/dev/null \ + | grep -vE '^[^:]+:[0-9]+:[[:space:]]*#' \ + | grep -vE '"[^"]*\bawait\b[^"]*"' \ + | wc -l) + if [ "$S8_HITS" -gt 0 ]; then + echo "[static_scan] S8 FAIL: 结算路径 await 命中 $S8_HITS 处(同种子逐位回放不可被 await 打断)" + grep -rnE '\bawait\b' $S8_FILES 2>/dev/null | grep -vE '^[^:]+:[0-9]+:[[:space:]]*#' | grep -vE '"[^"]*\bawait\b[^"]*"' + fail=1 + else + echo "[static_scan] S8 ok(扫描面 B1 文件集 7 个 .gd,await 零命中)" + fi +fi + exit $fail From e63de5548e53ed6569d4768d1f9ec1464c3a91cd Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 25 Oct 2026 20:45:38 +0800 Subject: [PATCH 9/9] =?UTF-8?q?=E5=B7=A5=E7=A8=8B(S6=E4=BF=A1=E5=8F=B7?= =?UTF-8?q?=E7=BA=AA=E5=BE=8B=E9=97=B8):=20core=20=E4=BF=A1=E5=8F=B7?= =?UTF-8?q?=E8=BF=9E=E6=8E=A5=E7=A6=81=E5=86=85=E8=81=94=20lambda=20?= =?UTF-8?q?=E8=90=BD=20static=5Fscan(S10=20=E5=90=8E=E7=8B=AC=E7=AB=8B?= =?UTF-8?q?=E6=AE=B5,=E8=B1=81=E5=85=8D=E9=80=9A=E9=81=93=20s6-signal-exem?= =?UTF-8?q?pt),=E7=9B=98=E9=9D=A2=E9=9B=B6=E5=AD=98=E9=87=8F,=E6=92=A4?= =?UTF-8?q?=E9=94=80=E8=AF=81=E6=98=8E=E7=BA=A2=E7=BB=BF=E9=97=AD=E7=8E=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- game/tests/static_scan.sh | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/game/tests/static_scan.sh b/game/tests/static_scan.sh index 0582fd30..2851c244 100644 --- a/game/tests/static_scan.sh +++ b/game/tests/static_scan.sh @@ -51,6 +51,36 @@ else fail=1 fi +# ── S6 — core 信号连接禁内联 lambda(架构文档 S 表:core↔core 信号连接只许方法 Callable,禁 lambda 捕获 self)── +# 扫描面:$DIR_CORE(game/core,core↔core 规则域=core 文件集;单点变量防空转)。 +# 判据=信号连接的内联 lambda 形态,保守集合(误报零容忍,拿不准的形态宁可不抓不红): +# ①同行形态:`.connect(` 后紧接 `func`——`sig.connect(func(a): ...)`; +# ②跨行形态:行尾以 `.connect(` 结束、下一行以 `func(` 起始(awk 前行状态机实现)。 +# 拿不准不抓的形态:bind/Callable 变量中转等间接 lambda 通道、注释外的字符串字面量内 `.connect(func` 同行 +# 全行注释已排除、行尾注记已豁免——间接通道归人工评审,本闸只防直接内联 lambda 回归。 +# 豁免通道:行内注记 s6-signal-exempt(仿 S2 rng-seed-exempt)——确需内联 lambda 的在册例外逐处留档。 +# 规则第二句「发射者禁持有订阅者反向引用」:静态判据不成熟(持有引用形态难可靠识别),不造弱判据, +# 该句归人工评审面承接,本闸只防内联 lambda 回归(2026-10-24 人工 grep 盘面干净,闸为防回归防线)。 +if require_scan_face "S6" "$DIR_CORE"; then +S6_HITS="$( + grep -rnE '\.connect[[:space:]]*\([[:space:]]*func\b' "$DIR_CORE" --include='*.gd' 2>/dev/null \ + | grep -vE '^[^:]+:[0-9]+:[[:space:]]*#' | grep -v 's6-signal-exempt'; + find "$DIR_CORE" -name '*.gd' -print0 2>/dev/null | xargs -0 awk ' + prev ~ /\.connect[ \t]*\([ \t]*$/ && $0 ~ /^[ \t]*func[ \t]*\(/ && + prev !~ /^[ \t]*#/ && prev !~ /s6-signal-exempt/ && $0 !~ /s6-signal-exempt/ { + print FILENAME ":" FNR ":" $0 " (跨行 lambda——上一行行尾 .connect( )" + } + { prev = $0 }' +)" +if [ -n "$S6_HITS" ]; then + echo "[static_scan] S6 FAIL: core 信号连接内联 lambda 命中(只许方法 Callable,禁 lambda 捕获 self)" + echo "$S6_HITS" + fail=1 +else + echo "[static_scan] S6 ok(扫描面 $DIR_CORE 共 $(scan_files "$DIR_CORE") 个 .gd,内联 lambda 零命中)" +fi +fi + # S1/S2 — 玩法代码禁 randomize()/自建 RandomNumberGenerator/全局随机函数(绕开 RngService 的口子) # 违规签名=裸 randomize/rand* 调用(实例方法 .randi() 排除) @@ -89,7 +119,6 @@ if [ "$hits" -gt 0 ]; then echo "[static_scan] S5 FAIL: core 裸引用 autoload fi # TODO(正式工程落地后精化为扫描配置并升格为硬失败): -# S6 core↔core 信号连接只许方法 Callable(禁 lambda 捕获 self);发射者禁反向引用 # S7 B2/B3/B4 API 符号命中文件 ⊆ B1 文件集(编排唯一性) # S8 结算路径 await 零命中(B1 结算/编排文件集)