From 66b2ed20f3efdd98c5b1a7f6ab41c3cf3c260b38 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Thu, 5 Nov 2026 05:31:11 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A7=84=E7=BA=A6(=E6=A6=82=E5=BF=B5/=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0=E5=88=86=E7=95=8C=C2=B7=E7=94=A8=E6=88=B7=E7=AB=8B202?= =?UTF-8?q?6-11-05):=20doc-conventions=20=E6=95=B0=E5=80=BC=E7=BA=AA?= =?UTF-8?q?=E5=BE=8B=E6=8D=A2=E4=BB=A3=E2=80=94=E2=80=94GDD=20=E6=A6=82?= =?UTF-8?q?=E5=BF=B5=E6=96=87=E6=A1=A3=E5=8F=AA=E5=AE=9A=E6=A6=82=E5=BF=B5?= =?UTF-8?q?/=E6=9C=BA=E5=88=B6/=E8=A7=84=E5=88=99=EF=BC=8C=E6=95=B0?= =?UTF-8?q?=E9=87=8F=E9=9D=A2=E4=B8=8E=E5=91=88=E7=8E=B0=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=E7=BB=86=E8=8A=82=E4=B8=8D=E8=BF=9B=E6=A6=82=E5=BF=B5=E6=AD=A3?= =?UTF-8?q?=E6=96=87=EF=BC=9B=E5=88=86=E5=B7=A5=E4=B8=89=E5=A4=84=E5=AE=9A?= =?UTF-8?q?=E6=A1=88(=E5=8F=96=E5=80=BC=E5=9F=9F=E4=B8=8E=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=E5=A5=91=E7=BA=A6=3Dgame/data/schemas/*.gd=20?= =?UTF-8?q?=E5=9F=9F=E6=A0=A1=E9=AA=8C=E6=89=A7=E6=B3=95=C2=B7=E7=8E=B0?= =?UTF-8?q?=E8=A1=8C=E5=80=BC=3Ddata/tables/*.tres=C2=B7=E5=91=88=E7=8E=B0?= =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E8=A7=84=E6=A0=BC=3Ddesign/gdd/ux/=20?= =?UTF-8?q?=E5=91=88=E7=8E=B0=E5=AE=9E=E7=8E=B0=E8=AE=BE=E8=AE=A1=E8=A7=84?= =?UTF-8?q?=E6=A0=BC=E5=B1=82=E8=B1=81=E5=85=8D=E6=A6=82=E5=BF=B5=E7=BA=AF?= =?UTF-8?q?=E5=BA=A6)=EF=BC=9B=E7=A6=81=E5=AE=9E=E7=8E=B0=E5=86=85?= =?UTF-8?q?=E5=AE=B9=E8=A1=8C=E6=95=B0=E6=8D=AE=E7=B4=A2=E5=BC=95=E4=BE=8B?= =?UTF-8?q?=E5=A4=96=E6=89=A9=E5=8F=8A=20data/schemas=EF=BC=9B=E6=94=B6?= =?UTF-8?q?=E5=8F=A3=E6=9D=A1=E6=AC=BE=201/2/5=20=E9=9A=8F=E5=8A=A8(GDD=20?= =?UTF-8?q?=E8=A1=A8=E6=A0=BC=E6=AD=A3=E6=96=87=E2=86=92=E6=A6=82=E5=BF=B5?= =?UTF-8?q?=E8=A7=84=E5=88=99=E5=8F=A5=C2=B7=E8=B0=83=E5=8F=82=E8=A1=A8?= =?UTF-8?q?=E9=94=81=E6=95=B0=E5=88=A0=E5=88=97=E2=86=92=E6=A6=82=E5=BF=B5?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=8D=E5=AD=98=E7=8E=B0=E8=A1=8C=E5=80=BC?= =?UTF-8?q?=C2=B7=E5=8E=8B=E7=BC=A9=E6=89=B9=20GDD=20=E8=A1=A8=E6=A0=BC?= =?UTF-8?q?=E2=86=92=E5=8F=82=E6=95=B0=E5=A5=91=E7=BA=A6=E8=8A=82)?= =?UTF-8?q?=EF=BC=9B=C2=A76=20=E9=AA=A8=E6=9E=B6=E8=B0=83=E5=8F=82?= =?UTF-8?q?=E8=A1=A8=E8=8A=82=E6=94=B9=E5=8F=82=E6=95=B0=E5=A5=91=E7=BA=A6?= =?UTF-8?q?(=E6=A6=82=E5=BF=B5=E9=9D=A2+=E6=8C=87=E8=B7=AF=20schema)?= =?UTF-8?q?=EF=BC=9BAGENTS=20=E6=9C=AF=E8=AF=AD=E8=A1=8C=E5=90=8C=E6=AD=A5?= =?UTF-8?q?(=E8=A7=84=E5=88=99=3Downer=20=E6=A6=82=E5=BF=B5=E9=9D=A2=C2=B7?= =?UTF-8?q?=E5=8F=96=E5=80=BC=E5=9F=9F=3Dschemas)=EF=BC=9B=E5=AD=98?= =?UTF-8?q?=E9=87=8F=E6=97=A7=E8=B0=83=E5=8F=82=E8=A1=A8=E8=8A=82=E6=B8=85?= =?UTF-8?q?=E6=89=AB=E5=BD=92=E7=8B=AC=E7=AB=8B=E6=89=B9=E3=80=81=E6=B6=88?= =?UTF-8?q?=E5=8C=96=E6=9C=9F=E4=B8=8D=E4=BD=9C=E6=9C=BA=E6=A3=80=E5=AF=B9?= =?UTF-8?q?=E8=B1=A1(=E9=97=B8=E6=97=A0=E6=AD=A4=E9=A1=B9=E5=88=A4?= =?UTF-8?q?=E6=8D=AE)=EF=BC=9B=E6=9C=AC=E6=AD=A5=E5=87=AD=E6=8D=AE:=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=9F=9F=E9=97=B8=208=20=E9=81=93=E5=85=A8?= =?UTF-8?q?=20exit=3D0,=E5=9B=9E=E6=89=A7=20all=5Fgreen=3Dtrue=20=E5=9F=BA?= =?UTF-8?q?=E7=BA=BF=20937d14a1,=E5=88=A4=E5=AE=9A=3D=E9=97=B8=E5=86=B5?= =?UTF-8?q?=E4=B8=8E=E5=9F=BA=E7=BA=BF=E4=B8=80=E8=87=B4=E6=97=A0=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E7=BA=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- design/engineering/doc-conventions.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 54ed1c74..1c64ff41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,7 +48,7 @@ | 概念切分与互链 | `design/engineering/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 | | 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 | | 架构（唯一事实源） | `design/engineering/architecture/architecture.md`——历史决策沿革查 git commit log，不另设决策文档 | -| 术语与已锁数值 | 规范名与定义 = `design/gdd/术语表.md`（全库唯一对照表，仅 owner 文档可修订）；现行数值 = `game/data/tables/*.tres`；规则与取值域 = 各系统 owner 文档。冲突须显式提出，禁默默改值 | +| 术语与已锁数值 | 规范名与定义 = `design/gdd/术语表.md`（全库唯一对照表，仅 owner 文档可修订）；现行数值 = `game/data/tables/*.tres`；规则（概念面）= 各系统 owner 文档；取值域与字段契约 = `game/data/schemas/*.gd`。冲突须显式提出，禁默默改值 | | 现在做什么 / 待办与待裁 | 根 `roadmap.md` 顶部「当前位」节＋迭代总表六列 · 待办唯一登记处 `待办清单.md` · 批次过程与结论查 git 提交信息与 `reports/` | ## 回答风格规则（只管对话输出；文档写作归 doc-conventions §2–§4） diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index d9567a17..78d33dc1 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -67,21 +67,21 @@ | 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 | | 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | | 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | -| 禁实现内容 | 系统文档与概念文档全文禁写实现细节——代码路径（`.gd`／`.py`／`.sh` 与运行时文件路径）、测试文件名、断言名、类名／方法名／信号名／常量名／调试与遥测入口名、提交号一律不出现；唯一例外＝数据索引（`game/data/tables/*.tres` 这类表路径与表名、表字段名与表内枚值、存档键、封闭词表标签）。实现事实归 `architecture.md`；验收标准只写玩家或系统可观测面。本行由文档域闸的能力审计机检两个可判死的面（带后缀路径、反引号调用形态），其余靠写卡段人工核对；闸件清单与域划分的唯一出处＝`tools/run_all_gates.sh` 头部 | +| 禁实现内容 | 系统文档与概念文档全文禁写实现细节——代码路径（`.gd`／`.py`／`.sh` 与运行时文件路径）、测试文件名、断言名、类名／方法名／信号名／常量名／调试与遥测入口名、提交号一律不出现；唯一例外＝数据索引（`game/data/tables/*.tres` 与 `game/data/schemas/` 的表路径与表名、表字段名与表内枚值、存档键、封闭词表标签）。实现事实归 `architecture.md`；验收标准只写玩家或系统可观测面。本行由文档域闸的能力审计机检两个可判死的面（带后缀路径、反引号调用形态），其余靠写卡段人工核对；闸件清单与域划分的唯一出处＝`tools/run_all_gates.sh` 头部 | | 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | | 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 | | 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | | 活体清单不冻结计数 | 对会生长的清单（文档树构成、UI 层项、RNG 流词表等）不写死计数与枚举——写指针到 owner（根索引/常量表/实现文件），现状值由 owner 承载；历史计数只进 git 提交信息 | -**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。 +**数值纪律（概念/实现分界，2026-11-05 用户立）**：GDD 概念文档只定概念、机制与规则——是什么、有什么、为什么；数量面（多大、多少、多大概率）与呈现实现细节不进概念文档正文。分工三处：取值域与字段契约归 `game/data/schemas/*.gd`（表结构定义＋域校验执法，provisional 随值标注）；现行值归 `game/data/tables/*.tres`；呈现实现规格（冻结公式、像素值、动效参数）居 `design/gdd/ux/`＝呈现实现设计规格层，豁免概念纯度约束。存量系统文档的旧调参表节由独立清扫批消化，消化期不作机检对象（现行闸无此项判据）。 **登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款： -1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。 -2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。 +1. **双写失同步禁止**——任何数值变更必须同步受影响三处：概念文档正文中表述该数值的规则句（若有）、`data/tables/` 行值与 schema 校验域、相关待办清单现状——其一未更新即视为变更未完成。 +2. **锁数后概念文档不存现行值**——概念文档参数契约节只留概念与意图，指针指向 `.tres` 对应行键与 schema 域校验。 3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。 4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。 -5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。 +5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + 概念文档参数契约节改为概念句与指针 + 待办清单刷新」四步全收才记版本号。 ## 6. 文档类型与骨架 @@ -98,7 +98,7 @@ | `待办清单.md`（仓库根） | 流水线唯一登记处：条目=登记元数据标题＋四属性正文，状态随流水线段推进（格式与状态机见第 12.1 节）；各系统文档「待办」节只留指路存根 | | `roadmap.md`（根目录） | 里程碑表＋迭代总表，一行一迭代，记录编排与实现进度（六列格式见第 12.2 节） | -**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／调参表（取值域+provisional 标注）／验收标准（玩家或系统可观测的判据，禁实现细节）／待办（指路存根）。 +**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／参数契约（概念面：本系统有哪些参数、各自设计意图一句话；取值域与字段契约指路 `game/data/schemas/`，不进本文）／验收标准（玩家或系统可观测的判据，禁实现细节）／待办（指路存根）。 **命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `02-系统清单.md`，旧代号（a1–d6）仅限解读归档。