rules(规则审阅落地批): 十条评审意见落地——呈报四问/文件头缩窄/禁词表冻结/lean死条文退役/日期批注清除/AGENTS瘦身/分域闸口径/状态栏纯化

- AGENTS.md: 呈报六问改读后自检四问;文件头红线删行数上限与白名单;日期批注清除;回执五况细则挪 process-conventions §3.10;流水线闸过时状态句改事实句
- process-conventions: §1.2 非迭代批改按改动域跑闸;§3.10 承接五况;两处日期批注清除;§2 表格凭据落点改现状清单
- code-conventions: §1.4.1 重写(删 8 行上限/两类白名单/90 文件清偿义务);§2.1 联动;两处日期批注清除
- test-conventions: 三处日期批注清除(三处实证日期属证据保留)
- doc-conventions: §1 lean 死条文删除;§4 词表冻结条款;§12.1 重写(状态行只写状态词;现状=关联文档清单;删括号凭据全部条款);三处日期批注清除;§5 重复词修复
- 术语表: 用语规范节加词表冻结句
- 06-待办清单: 11 条带括号状态行迁移(括号证据移入现状关联文档清单;待裁决说明并入现状;每条状态行只留状态词)
- tools/audit_file_headers.py: 删 R1 行数上限(R0 载体/R2 日期/R3 变更叙事保留)
- tools/gdd_lint.py: R2 表格占比判据与 R2_EXEMPT 整体退役(lean 解读对象已亡,只产存量噪音)
- tools/doc_term_audit.py: 词表冻结注释
- tools/pipeline_gate.py: 状态栏括号凭据核对废止,新增状态行禁括号判据(点名病因短路);闭合证据改现状正文核对(卡片路径磁盘存在性+交叉核、文档路径+版本、art-bible+版本)
- game/tests/static_scan.sh: S10 注释同步

变异验证(test-conventions §6):pipeline_gate 注入括号→状态行含括号内容红 exit1;删正文卡片路径→正文缺卡片路径+交叉核红 exit1;audit_file_headers 注入变更叙事→R2/R3 红 exit1、头注 12 行纯说明→0 红(上限停用实证)。坑册新增:未提交工作区禁 git checkout 变异还原(会连带回滚在途改动),须备份文件法。

全批净变化 +155/−146(12 文件)。
This commit is contained in:
DKChan committed 2026-10-20 23:15:05 +08:00
1 parent 880ee91b20
commit 811f988032
12 files changed
+155 -146

No files matched your search

+6 -6
View File
@@ -16,7 +16,7 @@
## 运行与验证(工作目录 = 含 project.godot 的切片目录)
- **交付前验收 = 跑 `tools/run_all_gates.sh`,按本批改动域选档(`--code` 只跑代码域/`--docs` 只跑文档域/不带参数=两域全量),所选域全绿才合回 master**——它是全部验证闸的唯一入口与唯一清单,**域划分也只写在它这一个地方**,闸件增减与分域调整都只改它,文档禁另列清单。一次改动同批混触 `game/` 与文档面时跑全量档。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推出该验哪个域再校验回执(缺回执/quick 模式/回执 commit ≠ HEAD/域不覆盖本次改动/含新增红,五况一律拦截)
- **交付前验收 = 跑 `tools/run_all_gates.sh`,按本批改动域选档(`--code` 只跑代码域/`--docs` 只跑文档域/不带参数=两域全量),所选域全绿才合回 master**——它是全部验证闸的唯一入口与唯一清单,**域划分也只写在它这一个地方**,闸件增减与分域调整都只改它,文档禁另列清单。一次改动同批混触 `game/` 与文档面时跑全量档。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推出该验哪个域再校验回执(五况拦截细则见 process-conventions §3.10)
- 单件直跑(调试期最窄确认用,**不构成验收**):系统级断言面 `python tools/run_smoke.py`(名带 smoke 但不止存活检查,术语见 `game/tests/README.md`)· 场景探针 `…console.exe --headless --path . res://smoke/ui_probe.tscn` · 单元 `… --script res://tests/run_all.gd`
- 调参批量:`--script res://smoke/adventure_monte_carlo.gd`(全冒险期望)· `res://smoke/reward_expectation.gd`(奖励期望);通关率/难度类测量一律走全冒险
- 数值验证:`python tools/balance_verifier.py`(采集端 `res://smoke/verifier_batch.gd`,报告与原始数据落 `sim-data/`)
@@ -33,7 +33,7 @@
- `sim-data/` — 机器读数据产物;数据件不入 git(入库例外 = README+analyze.py+growth_model.py);MC 锚与读数常驻留盘,无数值调整禁重跑
- `tools/` — python 工具脚本;`archive/` — 收口归档 zip(gitignored)
- `reports/` — 过程件容器:**需求卡片**(写卡段产出,实现批的输入合同)+迭代批产出物(实现报告/代拍板追认单/GDD 反哺点清单);**实现批唯一可写目录**,只放 .md,不是事实源(细则见 `reports/README.md`)
- 根目录:`README.md`(纯指路牌:设计/流程/当前位/待办四个链接,零规则重述)、`roadmap.md`(里程碑+迭代总表六列+顶部「当前位」节=现在做什么)、`stage.txt`/`review-mode.txt`(运行开关);仓库根禁止再设会话状态文件(2026-10-18 用户裁,细则见 doc-conventions 第 10 节)
- 根目录:`README.md`(纯指路牌:设计/流程/当前位/待办四个链接,零规则重述)、`roadmap.md`(里程碑+迭代总表六列+顶部「当前位」节=现在做什么)、`stage.txt`/`review-mode.txt`(运行开关);仓库根禁止再设会话状态文件(细则见 doc-conventions 第 10 节)
## 规范导航(动手前先查表)
@@ -53,20 +53,20 @@
## 硬性红线(勿违反;操作细则在 process-conventions.md 与各规约)
- 主工作区禁止直接改动与提交——一切改动走独立 worktree(豁免:`.zcode/` 与 `.qoder/` 两份本机 harness 配置,实测均不入 git)
- **仓库根禁止设会话状态文件**(2026-10-18 用户裁废除 `active.md`)——现状看 roadmap「当前位」,待办看 06,过程看 git 提交信息,产出物看 `reports/`;任何文档禁止另设「当前状态快照」节,两处记同一件事必然漂移(细则见 doc-conventions 第 10 节)
- **仓库根禁止设会话状态文件**(`active.md` 已废除)——现状看 roadmap「当前位」,待办看 06,过程看 git 提交信息,产出物看 `reports/`;任何文档禁止另设「当前状态快照」节,两处记同一件事必然漂移(细则见 doc-conventions 第 10 节)
- 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口;其余会话零测试,需测试支撑先请示并注明未跑测
- 交付前验收 = 跑 `tools/run_all_gates.sh` **按改动域**全绿(唯一入口、唯一闸清单、唯一域划分,禁在文档另列);合回 master 由 worktree-guard 按 diff 推域校验回执强制(process-conventions §3)
- **两类批**——**迭代批**(代码实现,`/iter` 发射):**禁写 `design/` 整个目录**(含新增/修改/删除),设计文档对它只读、是写测试与实现代码的输入依据;产出物只准写 `reports/`;批末只跑代码域闸。**非迭代批**(工具/规则/文档改动):不占 roadmap 迭代号,按改动域跑闸。文档内容的落地走五段流水线相应段(文档设计段入口=doc-design 技能;登记条目格式由流水线闸强制)
- 五段流水线铁律——一切工作按「登记 → 文档设计/美术设计 → 写需求卡片 → 迭代编排 → 实现」推进,段间不自动流转、每段转进由用户发令;编入迭代的卡片必须设计闭合+零待裁点,流水线闸 `tools/pipeline_gate.py` 强制(工具并行开发中,注册进 run_all_gates.sh 文档域归第二批);实现段零裁断——卡片没写清=上游缺陷,停该卡退回上游,禁内联求裁(process-conventions §2,格式与状态机=doc-conventions §12)
- 五段流水线铁律——一切工作按「登记 → 文档设计/美术设计 → 写需求卡片 → 迭代编排 → 实现」推进,段间不自动流转、每段转进由用户发令;编入迭代的卡片必须设计闭合+零待裁点,流水线闸 `tools/pipeline_gate.py` 强制(已注册进 run_all_gates.sh 文档域);实现段零裁断——卡片没写清=上游缺陷,停该卡退回上游,禁内联求裁(process-conventions §2,格式与状态机=doc-conventions §12)
- MC/模拟:无数值改动零跑;档位硬闸见 `sim-data/README.md`「MC 采集档位表」,一档只能由用户发起
- 闸机轮次纪律:新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册(process-conventions §6)
- 变异验证——新增/改写验收函数必须变异变红才算验收成立;无变异红记录只写「已实现,拦截能力未证」(test-conventions §6)
- 中间产物吸收即死——结论先吸收进权威文档、未决先迁 06,文件即删且永不提交(doc-conventions 第 11 节)
- **禁写变更记录**——文档与代码文件内一律禁设「版本历史/修订记录/变更记录/修改记录/更新记录/更新日志」节或表格,禁写「本版改了哪些条款」式逐版本叙述与 `# 2026-xx-xx 缺陷修批——` 式行内修订注记;沿革只进 git commit log。版本号可作文档现行身份标记留在文首状态行与正文引用中(doc-conventions 第 5 节,机检闸 gdd_lint R4 反转拦截)
- 用语红线——一切对用户输出禁自造黑话,需要作者解释的词必须展开成完整白话句(doc-conventions 第 4 节三形态表)
- 呈报六问——What 现状差异 / Why 动机与不做代价 / How 方案与全部备选 / Where 影响面 / 验收判据 / 不确定点单列收尾;Who/When 不进正文;仅首次描述需求/bug/方案适用
- 呈报四问(读后自检制)——向用户首次完整呈报一件事(需求/缺陷/方案/结论)时,写完先自查:读者只读这一段,能否不看原文答出——① 现状差在哪:现在是什么、缺什么;② 你建议做什么:做完预期什么效果、会动到哪些面;③ 为什么选这个做法:考虑过、放弃过哪些别的路;④ 做完怎么验证:哪些还有把握不足。哪问答不出就补哪问,禁靠加小标题凑数;三句话能说清的小件合并为三句:现状一句、建议与验证一句、没把握的一句;后续追问与推进不必重跑全框架
- 真人检测只登记不阻塞——登记进 07 清单/实现报告即完成义务,禁以等目检为停工理由或收口前置
- 文件头 = `##` 文档注释,介绍本模块,≤8 行两类白名单(①职责摘要 ②使用约束;禁一切文档反向链接;code-conventions §1.4.1,规范权威 = Google pyguide §3.8 + PEP 257;机器闸 tools/audit_file_headers.py)
- 文件头 = `##` 文档注释,介绍本模块是什么;禁写变更叙事(改动史查 git log);禁文档反向链接(code-conventions §1.4.1)
- 数值单一事实源——玩法数值只存 `data/tables/`(.tres)经 ConfigDB 单点读取;禁数值字面量与自建 `load()` 表路径
- RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator,随机只经 `RngService` 统一流
- 架构事实唯一源——架构事实只认 `design/engineering/architecture/architecture.md`;禁立第二架构文档或决策文档体系,历史决策记录只进 git commit log
+7 -11
View File
@@ -21,17 +21,13 @@
### 1.4 命名 = 领域命名,禁止系统 ID 前缀
文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀(`a1_board_generator.gd` → `board_generator.gd`)。设计追溯不靠前缀:代码↔设计的追溯由 GDD 文档承担,系统 ID 只作为文档的追溯锚;文件头注不承担追溯职责,不写任何文档链接(§1.4.1)。豁免:D2 schema 类与 autoload;文档/夹具登记名(如 b4_golden)属文档层。
### 1.4.1 文件头 = `##` 文档注释,介绍本模块,≤8 行,两类白名单制
### 1.4.1 文件头 = `##` 文档注释,介绍本模块
头注的存在性与内容范围以 Python 规范为权威(GDScript 语法近 Python,官方风格指南对文件头零条款,不自造标准):Google Python Style Guide §3.8.2 明文要求——"Files should start with a docstring describing the contents and usage of the module"(文件应以描述模块内容与用法的 docstring 开头);PEP 257——模块一般都应有 docstring,摘要压一行。
头注以 Python 规范为权威(GDScript 语法近 Python,官方风格指南对文件头零条款,不自造标准):Google Python Style Guide §3.8.2——文件应以描述模块内容与用法的 docstring 开头;PEP 257——模块一般都应有 docstring,摘要压一行。载体只用 `##` 文档注释(Godot 官方载体,进编辑器 F1 帮助),头注以说清模块为度,长度不设硬限。
载体与上限:只用 `##` 文档注释(Godot 官方载体,进编辑器 F1 帮助),总行数 ≤8(不含空行,从文件首个非空行到首个非注释代码行)。
黑名单(出现即违规):日期与变更叙事——改动史查 `git log`/`git blame`,变更背景读迭代实现报告;与其他文档或其他文件头重复的内容——零新信息不写;一切文档反向链接——「实现 GDD:xxx」「指路:架构见 xxx」一类全部废止,代码↔设计追溯由 GDD 文档承担。
白名单(只许两类):①职责摘要——这是什么,一句话;项目语境(垂直切片状态/验证目标)以括号并入本行。②使用约束——使用本文件前必须知道的禁令与边界,每条一行。
黑名单(出现即违规):日期与变更叙事——改动史查 `git log`/`git blame`,变更背景读迭代实现报告;与其他文档或其他文件头重复的内容——零新信息不写(pyguide §3.8.2.1);场景结构、生命周期等代码机制描述——"Never describe the code"(pyguide §3.8.5);一切文档反向链接——「实现 GDD:xxx」「指路:架构见 xxx」一类全部废止,代码↔设计追溯由 GDD 文档承担。
机器闸:`tools/audit_file_headers.py`(static_scan S10:行数上限+黑名单机械可判子集)。存量头注按白名单清偿(约 90 文件,清偿批进行中);清偿落地后闸增补「头注必须 `##` 开头」锁死载体;此间新增/改动的文件头必须即合规。
机器闸:`tools/audit_file_headers.py`(static_scan S10:变更叙事黑名单机械可判子集)。行数上限与类别白名单已停用。
### 1.5 禁止事实约定
任何"大家默认这么做"的惯例必须成文进本文件(或 AGENTS.md)才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文,不许靠惯性延续。
@@ -41,7 +37,7 @@
## 2. 契约纪律——跨层/跨类调用的语义
### 2.1 信号与事件契约成文
每个跨类信号:参数语义、发送时点、消费方依赖,必须在发送方 `##` 文档注释成文,每信号一行;计入 §1.4.1 的 8 行上限,装不下时迁契约文档。状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。
每个跨类信号:参数语义、发送时点、消费方依赖,必须在发送方 `##` 文档注释成文,每信号一行;装不下时迁契约文档。状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。
### 2.2 跨层标识符语义单一且成文
位置(index)/ 句柄(handle)/ 键(key)是三种不同的东西。跨类传递标识符时,传递方的语义必须与接收方契约逐字一致,禁止凭"当前恰好相等"传值。
@@ -68,7 +64,7 @@
4. **lambda 捕获循环变量按创建时值**——循环内先落地局部变量再捕获,或用 `bind`。
5. **重命名脚本必须同步 `.uid` 文件**;新增 `class_name` 后必须跑一次编辑器扫描刷新全局类缓存,否则 `--headless --script` 模式解析失败。
6. **`print` 格式占位符与实参类型必须匹配**(`%d` 配 String = 静默输出字面量)。
7. **语言纪律已机器化为 S9 类型闸**(迭代 27——2026-10-17 用户裁写入)——`tools/audit_type_hints.py`,执行载体=静态扫描域 S9(`game/tests/static_scan.sh`),退出码 0=归零。扫描面=产品码(`game/core`+`game/data`+`game/presentation`;smoke/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`;smoke/tests 豁免——测量面容器直构是既有惯例)。三规则: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()`——建种子不进玩法封闭流)。
@@ -96,5 +92,5 @@
## 6. 流程纪律
1. **大改动三段走**:设计稿/伪代码 → 用户审阅 → 实现;实现禁止先于审阅。改动明细只进 git 提交信息,README 与代码内不写修改记录(doc-conventions 第 5 节「禁写变更记录」)。
2. **实现批完成后的登记义务**:06 条目按 doc-conventions §12.1 推进状态,批次过程与结论进 git 提交信息与 `reports/`(2026-10-18 用户裁:根目录会话状态文件已废除,禁止再在其中登记条目)。
2. **实现批完成后的登记义务**:06 条目按 doc-conventions §12.1 推进状态,批次过程与结论进 git 提交信息与 `reports/`(根目录会话状态文件已废除,禁止再在其中登记条目)。
3. **呈现层缺陷的教训回写 D1 GDD 设计输入**(信号载荷 schema / 场景级测试 / 时点状态可见性)。
+17 -18
View File
@@ -11,7 +11,7 @@
**读者测试是每个小节的验收标准**:只读这一节,回答三个问题——这节管的是谁/什么?在什么情况下?会发生什么?答不出来,就重写这一节,而不是给看不懂的地方补注释。
旧体系 lean 格式六条硬规则已停用(其解读对象 `design/archive/` 旧档已删除,现无适用文档;原表格占比 30% 口径随之作废)。`tools/gdd_lint.py` 现为现行文档机检三闸之一(gdd_lint / doc_link_audit / doc_term_audit,分级周期口径见 AGENTS.md);可读性仍是第一内容质量门,lint 是格式机检面,两者并行。
`tools/gdd_lint.py` 现为现行文档机检三闸之一(gdd_lint / doc_link_audit / doc_term_audit,分级周期口径见 AGENTS.md);可读性是第一内容质量门,lint 是格式机检面,两者并行。
## 2. 白话写作规则
@@ -56,6 +56,8 @@
**通行检验标准**:读者是业内人但没读过项目历史——需要作者解释才懂的词不合格,必须展开成完整白话句(换新名词不算改,展开才算改)。**写后自查**:凡自己都要停顿才能想起意思的词,一律展开。
**词表冻结**:doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充;扩表唯一入口=用户实读反馈并经用户裁决,由非迭代批写入,禁 agent 自行增词。
## 5. 结构纪律
| 规则 | 内容 |
@@ -70,10 +72,10 @@
**数值纪律**:正文定规则、取值域、单位;平衡值进 `data/tables/`,provisional 必须标注;已锁数值事实源 = `game/data/tables/*.tres`(现行值)与 owner 文档正文(规则、取值域、单位)。
**登记处唯一性(2026-10-19 用户裁)**:`design/registry/`(`entities.yaml`/`architecture.yaml`)已注销删除,禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款:
**登记处唯一性**:`design/registry/`(`entities.yaml`/`architecture.yaml`)已注销删除,禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款:
1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域,只留 schema 模板与取值域,指针指向 `.tres` 对应行键。
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域,指针指向 `.tres` 对应行键。
3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。
4. **维护通道** = 「设计批 → 同步批」两段式;数值表改完不等于修订完成。
5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。
@@ -101,7 +103,7 @@
## 10. 会话状态——仓库根不设状态文件
**2026-10-18 用户裁:根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计:整文件被读 448 次、平均每次 14 KB 进上下文,但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上,明确写「从它所载内容得知某事实」的只有 20 个会话;文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链,测不出语义失真:10-15 清到 8.6 KB/3 条,10-17 已回到 40 KB,用户为「只写不删」连续三次发火,规矩照样失效。
**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计:整文件被读 448 次、平均每次 14 KB 进上下文,但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上,明确写「从它所载内容得知某事实」的只有 20 个会话;文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链,测不出语义失真:10-15 清到 8.6 KB/3 条,10-17 已回到 40 KB,用户为「只写不删」连续三次发火,规矩照样失效。
废除后的分工:**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节;**待办与待裁**看 [06-待办清单](../gdd/06-待办清单.md)(唯一登记处);**批次过程与结论**看 git 提交信息与 `reports/`;**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件,也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移,这正是本次统计查出七条失实陈述的成因。
@@ -120,7 +122,7 @@
| 出口清理项 | 每迭代出口检查单必含:本迭代中间产物逐份核对(结论已吸收、未决已迁移)后删除 |
| 暂存地非档案库 | 中间文档有两处暂存地,入内文件默认到期即死:`reports/`(需求卡片+迭代产出物)、`design/research/`(调研/提案/评估/历史验收)。`design/` 各子目录不留验证截图——截图属一次性凭据,结论写进 06 或需求卡片后图像即弃(在途图放 `artwork/`,整目录不入 git);只有需要机器逐像素比对的基线图长期入库,落 `game/tests/golden/` |
| 落档必写接收方 | 新报告落档时头部必须写明接收方——`06-待办清单.md` 第几条,或哪张需求卡片。写不出接收方的不落文件,内容在会话里交付即可 |
| 迭代实现报告 | 实现批收口的迭代级报告(各卡状态/代拍板追认单/GDD 反哺点清单),属中间文档,**落 `reports/` 不落 `design/`**(2026-10-17 用户裁:实现批禁写 `design/`,`reports/` 是其唯一可写目录):反哺点裁决落文吸收后按「证据只留最新」退役 |
| 迭代实现报告 | 实现批收口的迭代级报告(各卡状态/代拍板追认单/GDD 反哺点清单),属中间文档,**落 `reports/` 不落 `design/`**(实现批禁写 `design/`,`reports/` 是其唯一可写目录):反哺点裁决落文吸收后按「证据只留最新」退役 |
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本;新证据落位后同批删上一份;待人清单过人闸后同规退役 |
**删除方式**:按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面(grep 文件名于阻塞域),改写或删除指路句,再删文件,收尾跑死链检查全绿。执行入口=项目技能 batch-closure(批后收尾与中间文档退役)。
@@ -142,37 +144,34 @@
正文四属性模板:
```
**现状**:现在缺什么、为什么是问题(关键处带 file:line 或文档指针)。工程直入条目必须在现状里指认证据(bug 证据或工程债条目)。
**现状**=关联文档清单,一行一件:它是什么(设计定稿/需求卡片/相关文档)+文件路径+版本号与日期(闭合类文件必带);必要时在清单前配一句现状说明。机制解释与论证过程不写在这里,归权威文档。路径用普通文本或行内代码书写,机器可搜索。工程直入条目必须在现状里指认证据(bug 证据或工程债条目)。
**缺口**:还差哪一次设计讨论/哪份设计产物才能写卡。尚有未闭合的设计轨时此属性必须存在;全部设计轨闭合后删除。
**归属**:主责系统文档或线别。
**状态**:按状态机取词。
```
状态机按标题里的设计面分轨,状态一律取下例用词。状态行按**状态段累积制**书写:条目每推进一段,就把新状态段接在状态行末尾,段与段用+号连接,书写顺序=推进顺序;已过去的段一律保留、禁删——闭合凭据要留在行内,编排四查与开工核验拿它比对。每段各自按状态词白名单与凭据规则校验,+号只作状态段连接符。
状态机按标题里的设计面分轨,状态一律取下例用词。状态行按**状态段累积制**书写:条目每推进一段,就把新状态段接在状态行末尾,段与段用+号连接,书写顺序=推进顺序;已过去的段一律保留、禁删——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验,+号只作状态段连接符。
```
各轨推进序列(双轨条目设计阶段两段并列推进,一文档轨一美术轨):
文档轨:待文档设计 → 文档设计中 → 文档设计已闭合(凭据=文档路径+版本号,
例:文档设计已闭合(design/gdd/systems/xxx.md v1.2))
美术轨:待美术设计 → 美术设计中 → 美术设计已闭合(凭据=样张过审、art-bible 条款版本,
例:美术设计已闭合(样张过审、art-bible v3.x))
双轨条目设计阶段示例:文档设计已闭合(design/gdd/systems/xxx.md v0.6)+美术设计中
进入下游段(待写卡及之后)的前置条件——双轨:两个设计轨段都在场且都已闭合(带凭据);单轨:本轨闭合段(带凭据)在场
下游共用序列:待写卡 → 已写卡(reports/ 下的需求卡片路径)→ 已编迭代 N → 完成即整条删除
单轨累积示例(已编迭代):文档设计已闭合(design/gdd/systems/xxx.md v1.2)+已写卡(reports/需求卡片-xxx.md)+已编迭代 2
文档轨:待文档设计 → 文档设计中 → 文档设计已闭合
美术轨:待美术设计 → 美术设计中 → 美术设计已闭合
进入下游段(待写卡及之后)的前置条件——双轨:两个设计轨闭合段都在场;单轨:本轨闭合段在场
下游共用序列:待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除
单轨累积示例(已编迭代):文档设计已闭合+待美术设计+已写卡+已编迭代 2
```
凭据括号内禁用+号——+只作状态段连接符,凭据内需要并列多项时用顿号(如上例「样张过审、art-bible v3.x」),用+会被流水线闸误判为状态段。已编迭代 N 段的交叉核依据=同状态行内「已写卡」段括号里的卡片路径。
状态行只写状态词:去掉特批标记与「(备选)」后缀后,残留任何括号即违规。闭合类状态词(文档设计已闭合/美术设计已闭合/已写卡/已写入)的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在现状的关联文档清单里,由流水线闸到正文核对;已编迭代 N 段的交叉核依据=现状清单里的需求卡片路径。
三条特殊通道:
| 设计面 | 通道规则 |
|---|---|
| 工程直入 | 缺陷修复/工程债/测试基建/重构四类工程条目:登记即「待写卡」,凭现状里指认的证据跳过设计轨 |
| 反哺点专条 | 待裁决 → 已写入(落点=文档+版本)→ 删除 |
| 反哺点专条 | 待裁决 → 已写入 → 删除 |
| 备选库条目 | 暂不排期、留在备选库的条目:状态词后缀「(备选)」 |
「已闭合」不带凭据不算合法状态词。特批标记见 12.4。
特批标记见 12.4。
### 12.2 roadmap 迭代行格式
+7 -7
View File
@@ -10,7 +10,7 @@
主工作区(master 检出)只作合并落点,一切开发/设计改动禁止直接发生在主工作区:
1. **开工**:每批次先建独立 worktree:`git worktree add ../g-plan2-<任务名> -b <任务分支>`;所有改动与验证都在 worktree 内进行(未跟踪文件不会出现在新 worktree,需手工搬运)
2. **收尾**:迭代 loop 批次验证全绿(冒烟+场景探针)后在主工作区 `git merge --no-ff <任务分支>`,再 `git worktree remove`+删分支;合回前若 master 已被别的批次推进,先在分支里 `git merge master` 解冲突、重跑本域闸再合回。非 loop 批次默认完成不跑闸(两入口铁规),用户点名或当场问
2. **收尾**:迭代 loop 批次验证全绿(冒烟+场景探针)后在主工作区 `git merge --no-ff <任务分支>`,再 `git worktree remove`+删分支;合回前若 master 已被别的批次推进,先在分支里 `git merge master` 解冲突、重跑本域闸再合回。非 loop 批次合回前同样按本批改动域跑闸(见 §3.10:纯文档批跑 `--docs`);游戏类测试(冒烟/单测/MC/探针)对它默认零执行(两入口铁规,见 §4),用户点名或当场问才跑
3. **豁免面**:仅 `.zcode/`(钩子与配置)与 `.qoder/`(本机 harness 配置)允许主工作区直改——两份实测均不入 git(走 worktree 反而带不进去,改动只对本机生效);其余一律走 worktree,主工作区 git commit 被钩子拦截
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底;钩子只约束 agent,用户手工改动不受限
@@ -21,14 +21,14 @@
| 段 | 入口技能 | 产出 | 出入口铁律 |
|---|---|---|---|
| 一·登记 | 无(闸管格式) | 06-待办清单条目 | 条目=标题登记元数据+正文四属性(现状/缺口/归属/状态);标题登记后不再变,正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 |
| 二·文档设计/美术设计 | doc-design(文档轨,兼任反哺点写入)/asset-ingest(美术录入;样张素材由用户主导产出) | GDD 文档或 art-bible/过审样张素材 | 用户提起或从 06 取出;会话内进行、用户主导、禁无监管自跑;经用户点头确认心智一致才许写入文档;完成判据=待裁点清零,带未裁点的是讨论稿;轨闭合凭据记入 06 状态(文档轨=文档路径+版本号,美术轨=样张过审+art-bible 条款版本) |
| 三·写需求卡片 | req-card | 需求卡片 | 轨闭合后用户发令;新玩法/新系统/新内容必须有设计定稿前置,例外=工程直入四类(缺陷修复/工程债/测试基建/重构)凭证据跳过设计轨;卡片必经 grilling 多轮复核、零待裁点才成立;写完在 06 状态记「已写卡」+卡片路径(防遗忘) |
| 二·文档设计/美术设计 | doc-design(文档轨,兼任反哺点写入)/asset-ingest(美术录入;样张素材由用户主导产出) | GDD 文档或 art-bible/过审样张素材 | 用户提起或从 06 取出;会话内进行、用户主导、禁无监管自跑;经用户点头确认心智一致才许写入文档;完成判据=待裁点清零,带未裁点的是讨论稿;轨闭合凭据记入 06 现状清单(文档轨=文档路径+版本号,美术轨=art-bible 条款版本) |
| 三·写需求卡片 | req-card | 需求卡片 | 轨闭合后用户发令;新玩法/新系统/新内容必须有设计定稿前置,例外=工程直入四类(缺陷修复/工程债/测试基建/重构)凭证据跳过设计轨;卡片必经 grilling 多轮复核、零待裁点才成立;写完在 06 状态记「已写卡」,卡片路径记入现状清单(防遗忘) |
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查:①每卡卡片文件存在 ②每卡设计闭合凭据齐(或工程直入证据)③总估时 ≤2 周 ④写完 roadmap 行后跑流水线闸确认绿;编入未完成迭代,新开迭代行经用户确认 |
| 五·实现 | iter | 代码与配置,可运行的游戏 | 需求卡片永不单独施工,统一由用户指定迭代号触发(=U0 开工令),按 iter 技能与本文 §3 执行;**本段是代码实现批:禁写 `design/` 与根规则文件,产出物只落 `reports/`(见 §3 第 13 条)**;设计权威文档(GDD/art-bible)批内一律不更新;完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |
**实现段零裁断**:实现段的输入在编排段出口已锁死(卡片零待裁点+设计闭合凭据齐+编排四查过)。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、06 状态回退+缺口补记,退回上游;禁自答、禁内联提问求裁断;该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级(自救重试/记录继续/停机呈报)。代拍板白名单保留:授权发生在卡片审问阶段,实现只执行预授权;批后追认单=备案确认。
**流水线闸**:`tools/pipeline_gate.py` 机检 06-待办清单与 roadmap 两文件的格式与互相引用;将注册进 `run_all_gates.sh` 文档域(注册归第二批,本批不注册)。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。
**流水线闸**:`tools/pipeline_gate.py` 机检 06-待办清单与 roadmap 两文件的格式与互相引用;已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。
## 3. 批次工作流标准清单
@@ -50,10 +50,10 @@
9. **验收函数变异验证**——新增/改写的验收函数(冒烟断言/探针自检/闸机判据)必须配一次变异验证:故意把被测件改坏成该类缺陷形态 → 跑最窄那道闸确认变红 → `git checkout` 精确还原;变异点/跑的闸/红输出摘要/还原结论四件记入实现报告变异验证记录表;**无变异红记录的断言不写「已验收」,只写「已实现,拦截能力未证」**(细则见 test-conventions §6)
**完成**
10. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`,**按本批改动域选档**:本批改动触及 `game/`(游戏工程代码、测试、探针、场景)→ `--code`;不触及 `game/` 的一切改动(`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等)→ `--docs`;同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**,闸件增减、分域调整都只改它;**本文与其他文档禁另列闸件清单**(清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因)。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推域强制校验。闸件(`tools/` 下机检脚本与闸壳)自身的改动不占合回全量——其质量义务=落批时的变异验证(test-conventions §6),闸真崩溃时合回闸 fail-closed(跑不出回执即拦),不以合回全量为兜底
10. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`,**按本批改动域选档**:本批改动触及 `game/`(游戏工程代码、测试、探针、场景)→ `--code`;不触及 `game/` 的一切改动(`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等)→ `--docs`;同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**,闸件增减、分域调整都只改它;**本文与其他文档禁另列闸件清单**(清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因)。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推域强制校验(五况拦截:缺回执/quick 模式/回执 commit ≠ HEAD/域不覆盖本次改动/含新增红)。闸件(`tools/` 下机检脚本与闸壳)自身的改动不占合回全量——其质量义务=落批时的变异验证(test-conventions §6),闸真崩溃时合回闸 fail-closed(跑不出回执即拦),不以合回全量为兜底
11. **合并后主区按域复跑**——合并可能引入冲突或环境差异,落回 master 后按本批改动域复跑:触及 `game/` 的批=全量复跑(维持);纯文档域批=复跑文档域档(秒级),不再全量
12. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进 06 条目状态(做完整条删除),涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure(批后收尾与中间文档退役),跨会话教训写记忆库。批次过程与结论由 git 提交信息承载,禁止再写会话状态文件(2026-10-18 用户裁,见 doc-conventions 第 10 节)。`design/` 与根规则文件(`AGENTS.md`/`roadmap.md`)实现批禁写,见 §13
13. **文档同步闸(2026-10-17 改口径:实现批禁写文档)**——实现批**禁写 `design/` 整个目录与根规则文件**,要往外交代的东西一律落 `reports/`:实现报告 `reports/iter<N>-实现报告-<日期>.md`(各卡状态+实机目检总清单+遗留读数义务)、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`(每条写清哪个文件哪一节、改成什么、依据是什么)。设计权威文档(GDD/art-bible)**任何批都不直改**:用户在会话中逐点裁决后,由非迭代批(工具/规则/文档批)写入 `design/`(执行入口=doc-design 技能),并把反哺条目从 `reports/` 清掉(吸收即死;退役执行=batch-closure 技能)。机械面文档(roadmap 行/术语表/README 工具注)同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺,读前先查 `reports/` 与 06;需求卡片必列「关联文档同步面」按两层标注
12. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进 06 条目状态(做完整条删除),涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure(批后收尾与中间文档退役),跨会话教训写记忆库。批次过程与结论由 git 提交信息承载,禁止再写会话状态文件(见 doc-conventions 第 10 节)。`design/` 与根规则文件(`AGENTS.md`/`roadmap.md`)实现批禁写,见 §13
13. **文档同步闸(实现批禁写文档)**——实现批**禁写 `design/` 整个目录与根规则文件**,要往外交代的东西一律落 `reports/`:实现报告 `reports/iter<N>-实现报告-<日期>.md`(各卡状态+实机目检总清单+遗留读数义务)、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`(每条写清哪个文件哪一节、改成什么、依据是什么)。设计权威文档(GDD/art-bible)**任何批都不直改**:用户在会话中逐点裁决后,由非迭代批(工具/规则/文档批)写入 `design/`(执行入口=doc-design 技能),并把反哺条目从 `reports/` 清掉(吸收即死;退役执行=batch-closure 技能)。机械面文档(roadmap 行/术语表/README 工具注)同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺,读前先查 `reports/` 与 06;需求卡片必列「关联文档同步面」按两层标注
14. **实机目检归用户,只登记不阻塞**——真人检测项登记进实现报告目检总清单与 07-体验验证清单即完成批内义务;禁把等目检当停工理由或完成前置
15. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节
+3 -3
View File
@@ -66,7 +66,7 @@
**判据强弱分层**:同一缺陷面往往需要多件配合——**可见性/状态源类**缺陷由 `is_visible_in_tree`、树序、状态源取值的**运行期断言**抓;**内容/观感类**缺陷由 **golden 逐像素比对**抓;**占比/统计类**判据(墨色占比、纹理幅度)只能兜「整框空白/整框糊/压 busy 纹理」,是补充不是主力。写卡时按此分层配齐,别指望一条断言包打。
## 7. 判定三硬闸——闸承载的构造义务(迭代 29 三硬闸 2026-10-17 用户裁升格为纪律)
## 7. 判定三硬闸——闸承载的构造义务(迭代 29 起)
任何**新增或改写的闸承载**(闸脚本/批跑编排/探针入口)必须三闸齐备;现行各闸状态登记归架构文档「测试与质量域」节(本文不另列闸件清单):
@@ -76,9 +76,9 @@
- 负面套件(测试目标就是产生错误输出)仅可豁免第 2 闸,且须在 manifest 显式标记,其余两闸照判。
- 子进程输出须经系统命令解释器重定向落盘再读——`OS.execute` 的输出管道在本机恒空。
**新写测试件全类型标注**(2026-10-17 用户裁写法纪律)——新写的测试件(冒烟断言/探针/单测)参数、返回值、容器一律带类型标注,与 S9 对产品码的要求同型;存量不强制清扫,被批次触碰时顺带换代。暂不机器闸(S9 扫描面=产品码,smoke/tests 豁免是测量面直构惯例的既有裁量)。
**新写测试件全类型标注**——新写的测试件(冒烟断言/探针/单测)参数、返回值、容器一律带类型标注,与 S9 对产品码的要求同型;存量不强制清扫,被批次触碰时顺带换代。暂不机器闸(S9 扫描面=产品码,smoke/tests 豁免是测量面直构惯例的既有裁量)。
## 8. 判定可靠性优先于覆盖率(迭代 29 核心命题 2026-10-17 用户裁成节)
## 8. 判定可靠性优先于覆盖率(迭代 29 核心命题)
- 「跑一遍没崩=通过」无效:测试绿只证明**当前代码没犯这个错**,不证明**犯了这个错会被抓住**;断言存在不等于断言执行。
- **脚本错误会静默中断所在函数的剩余断言,而套件仍报全绿**(机制事实):GDScript 无脚本错误陷阱 API,错误不改进程退出码、不计失败数。三处实证:①2026-09-19「309 项 0 失败」实为断言未跑全(状态记录 83);②敌人表行集纪律 10 条断言因定型数组赋值错误从未执行(迭代 29 修复后两条正向见红=夹具本缺锚行);③`Callable` 形参类型写错致解析函数返回 null、后续断言整段蒸发。
+30 -20
View File
@@ -207,11 +207,11 @@
#### 冒险前资源配比预设(构筑提案)(2026-09-18 登记,来源=会话提及,设计面=文档轨)
**现状**:2026-09-18 用户提案,方向评估通过,登记在案。核心想法=玩家在**开始冒险前**预设地图战斗资源的类型配比——预设的是**分布**(九型格面池的正向权重占比;2026-10-04 立项裁决批口径 gp 型入池成九型,正向权重合计 77),不是落位:装板摇号仍按专属随机流摇出各格类型身份,玩家定分布、摇号定落位(与既定随机性立场相容)。两分法:① **基础资源配比**——正向行权重经覆盖值通道在开局注入;② **关卡特殊资源**——不同关卡(board_biome 图主题)携带配比池之外的特殊资源与差异化分布。设计红利=危险格与安全格同池+极性矩阵使配比自带代价轴(调高某型权重,安全格正向与危险格负向同步变多),不是免费午餐;注入通道=[元进度](systems/跨局循环/元进度.md) v1.0 已定稿的「冒险开始参数面与覆盖值通道」,零新机制;②正是[棋盘生成](systems/排雷循环/棋盘生成.md) board_biome 上下文与[地图战斗资源](systems/战斗循环/地图战斗资源.md)差异化插槽的启用场景。**八项裁决已全裁(2026-10-04 用户令「拍板点全部使用推荐」)**:①预算=组合制(总量挪点为骨架〔总和恒 77〕+每型上下限包络+容量随营地解锁渐进〔gp 首发不可调/预设档 3 套/下限 >0〕);②主权=设计者定包络与默认、玩家包络内分配(验收=默认分布锚+极端构筑护栏带);③容量柜台=奖励格图鉴承接;④注入语义=差值向量(存相对默认偏移 ΣΔ=0,集合操作保留在解锁层作辅语义);⑤渠道边界=清图槽差异化先行+三句不混池口径;盘问轮四裁随落(合成序=表值→玩家配比差值→包络钳制→图级变异偏斜→同调硬币偏置;图鉴柜台逐型商品;冒险开始锁档;包络宽度随容量分级放宽)。全案与淘汰依据原载提案 §八/§九/§十(该提案文件已随吸收即死退役,git 历史可考;需求卡片冻结在档)。影响面/依赖/被依赖清单原载本条(排雷/战斗/冒险/表现四循环十余文档指针),重启时自 git 历史取全文本。**挂起(2026-10-05 用户令)**:移出 roadmap 迭代 14(⑥号卡撤销)——暂不做,本条保留为挂起待办;八项裁决与需求卡片全部冻结保留(需求卡片文件头已挂冻结横幅);重启须用户另行发令。**凭据版本复核(2026-10-18,文档体检第 10 项)**:本条两处写的 `元进度.md v1.0` 是定稿当时的版本号,该文档现行已 v1.21;经查「冒险开始参数面」与「覆盖值通道」在 v1.21 里原样在役(该文档 :26/:98/:100/:119 四处),v1.16 与 v1.18 两行只对注入节作追加说明、未推翻通道结论——闭合判据仍成立,凭据按历史记载保留不改号。
**现状**:构筑提案 2026-09-18 立项、八项裁决全裁(2026-10-04),设计闭合机制=[元进度](systems/跨局循环/元进度.md)「冒险开始参数面与覆盖值通道」(零新机制);2026-10-05 挂起——移出 roadmap 迭代 14,八项裁决与需求卡片冻结保留,重启须用户另行发令;全案与淘汰依据原载已退役提案(git 历史可考),裁决细节冻结在卡片。关联文档:[元进度](systems/跨局循环/元进度.md) v1.0(闭合凭据;现行 v1.21 已复核在役,2026-10-18 文档体检第 10 项);需求卡片 reports/需求卡片-冒险前资源配比预设批-2026-10-04.md(文件头挂冻结横幅)。
**归属**:[地图战斗资源](systems/战斗循环/地图战斗资源.md)修订批(基础配比的权重覆盖语义 + GDD 修订)与[元进度](systems/跨局循环/元进度.md)(解锁容量与注入生产者)共裁;呈现面归[HUD 框架](systems/表现与支撑/HUD框架.md)与[教学引导](systems/表现与支撑/教学引导.md)顺带。
**状态**:文档设计已闭合(八裁全落零拍板点,机制依赖面=元进度.md v1.0「冒险开始参数面与覆盖值通道」)+已写卡(reports/需求卡片-冒险前资源配比预设批-2026-10-04.md)(备选)
**状态**:文档设计已闭合+已写卡(备选)
#### GP 经济换算失衡——GP 袋面值与商店价格的换算关系复查(2026-10-07 登记,来源=审计发现,设计面=文档轨)
@@ -547,61 +547,67 @@
#### 营地交互重做·五张需求卡片(2026-10-18 登记,来源=会话提及,设计面=文档轨)
**现状**:2026-10-17~18 需求讨论澄清会话产出结论文档 `design/research/需求澄清-营地交互重做-2026-10-18.md` v1.0(目标体验原话/目标结构树+纵深稿/10 条交互裁决/验收口径/切批原则/遗留待裁),用户令按工作内容维度拆卡、卡片不预占迭代号。五卡已写(顺序=执行顺序,估时附后):①存档制数据层改造批(隐式单档→3 存档位,≈4.5–5.5d)②主菜单三入口化批(6 钮→3 钮,≈2.5–4d)③选档界面新建批(≈4.5–5.5d)④营地场景图新建批(最大件,≈9–12d)⑤Esc 浮窗与营地顶栏批(≈3–4.5d)。三道复核:grilling 子 Agent 对抗审查(五卡各一)→v1.1;用户裁定「事项按推荐的来」→v1.2;用户两次订正(**卡④留在批内不踢出**;前置由谁解决/何时解决由用户定,美术/设计线=用户自立批〔铁律 2〕,Agent 不代跑不代产——曾越权起草的点选反馈设计稿 v0.1 已撤回删除)→卡④ v2.2。①②③⑤ 零待裁点可编工程波次:②③ 硬耦合同波(「进入存档」钮落点=选档界面),① 是 ③ 前置;⑤ 随 ④ 代码波同行。
**现状**:2026-10-17~18 需求讨论澄清会话产出结论文档,用户令按工作内容维度拆卡、卡片不预占迭代号。五卡已写(顺序=执行顺序):①存档制数据层改造批 ②主菜单三入口化批 ③选档界面新建批 ④营地场景图新建批 ⑤Esc 浮窗与营地顶栏批(各卡估时与内容见卡片自身)。三道复核:grilling 子 Agent 对抗审查(五卡各一)→v1.1;用户裁定「事项按推荐的来」→v1.2;用户两次订正(**卡④留在批内不踢出**;前置归用户自立批,Agent 不代跑不代产——曾越权起草的点选反馈设计稿 v0.1 已撤回删除)→卡④ v2.2。①②③⑤ 零待裁点可编工程波次:②③ 硬耦合同波(「进入存档」钮落点=选档界面),① 是 ③ 前置;⑤ 随 ④ 代码波同行。关联文档:
- 设计澄清定稿:design/research/需求澄清-营地交互重做-2026-10-18.md(v1.0:目标体验原话/目标结构树+纵深稿/10 条交互裁决/验收口径/切批原则/遗留待裁)
- 卡①:reports/需求卡片-存档制数据层改造批-2026-10-18.md
- 卡②:reports/需求卡片-主菜单三入口化批-2026-10-18.md
- 卡③:reports/需求卡片-选档界面新建批-2026-10-18.md
- 卡④:reports/需求卡片-营地场景图新建批-2026-10-18.md(v2.2,美术轨未闭合,见缺口)
- 卡⑤:reports/需求卡片-ESC浮窗与营地顶栏批-2026-10-18.md
**缺口**:卡④(营地场景图)美术轨未闭合,五项前置批内登记待销号——P1 美术渠道 A/B(**待用户裁**,推荐 A);P2 像素规格(Q6 甲过渡口径已裁,执行归用户线);P3 点选反馈设计稿(用户线,未受命开工;Agent 曾越权起草 v0.1,已按用户令撤回删除);P4 参照物(用户后续找);P5 GDD/art-bible 落文(定稿后用户发令)。销号完毕且美术定稿(样张过审+art-bible 条款版本)后卡④方可进代码实现波次。
**归属**:营地交互重做(数据层+呈现层+美术线;五卡路径见状态行,批次归属与波次由用户按工作量另裁)
**归属**:营地交互重做(数据层+呈现层+美术线;五卡路径见现状清单,批次归属与波次由用户按工作量另裁)
**状态**:文档设计已闭合(design/research/需求澄清-营地交互重做-2026-10-18.md v1.0)+待美术设计+已写卡(reports/需求卡片-存档制数据层改造批-2026-10-18.md)+已写卡(reports/需求卡片-主菜单三入口化批-2026-10-18.md)+已写卡(reports/需求卡片-选档界面新建批-2026-10-18.md)+已写卡(reports/需求卡片-营地场景图新建批-2026-10-18.md)+已写卡(reports/需求卡片-ESC浮窗与营地顶栏批-2026-10-18.md)
**状态**:文档设计已闭合+待美术设计+已写卡+已写卡+已写卡+已写卡+已写卡
#### 需求卡片入库纪律未登记——502 批遗留的悬空待办(2026-10-18 登记,来源=批次移交,设计面=反哺点)
**现状**:2026-10-16 迭代 29 编入批(提交 `21c83f5`)认定「需求卡片写进了 roadmap 却没在 06 登记」属流程漏洞,需要补一条卡片入库纪律。该条至今在 06 清单内查无(2026-10-17 与 2026-10-18 两次全文检索零命中)。唯一记过它的地方是根目录状态文件未决面第 31 行,该文件已于 2026-10-18 用户裁废除,故改记本条防遗忘。
**现状**:2026-10-16 迭代 29 编入批(提交 `21c83f5`)认定「需求卡片写进了 roadmap 却没在 06 登记」属流程漏洞,需要补一条卡片入库纪律。该条至今在 06 清单内查无(2026-10-17 与 2026-10-18 两次全文检索零命中)。唯一记过它的地方是根目录状态文件未决面第 31 行,该文件已于 2026-10-18 用户裁废除,故改记本条防遗忘。待裁:这条纪律要不要立;立则写进归属所指的 process-conventions。
**归属**:design/engineering/process-conventions.md 五段流水线的登记段
**状态**:待裁决(这条纪律要不要立;立则写进 process-conventions)
**状态**:待裁决
---
#### req-card 技能的 WorkBuddy 与 ZCode 两份副本内容不一致——取齐待裁(2026-10-18 登记,来源=批次移交,设计面=反哺点)
**现状**:用户级技能 req-card 在本机有两份副本,分别位于 WorkBuddy 与 ZCode 两个 harness 的用户目录 skills/req-card/SKILL.md(都在仓库之外,仓内没有任何登记处)。2026-10-18 逐字节比对:两份内容不同——迭代 28 那批只补了 ZCode 一份,WorkBuddy 那份没跟着改。这条欠账此前只记在根目录会话状态文件的未决面第 32 行,该文件已于 2026-10-18 用户裁废除,故改记本条。
**现状**:用户级技能 req-card 在本机有两份副本,分别位于 WorkBuddy 与 ZCode 两个 harness 的用户目录 skills/req-card/SKILL.md(都在仓库之外,仓内没有任何登记处)。2026-10-18 逐字节比对:两份内容不同——迭代 28 那批只补了 ZCode 一份,WorkBuddy 那份没跟着改。这条欠账此前只记在根目录会话状态文件的未决面第 32 行,该文件已于 2026-10-18 用户裁废除,故改记本条。待裁:以哪一份为权威取齐,或两份各自演化。
**归属**:用户级技能 req-card(仓库外两份副本)
**状态**:待裁决(以哪一份为权威取齐,或两份各自演化)
**状态**:待裁决
---
#### 「魔法道具」与「罕见」两个旧叫法的残留未扫——扫不扫待裁(2026-10-18 登记,来源=批次移交,设计面=反哺点)
**现状**:「魔法道具」随 2026-09-15 可选类道具删除而失效,「罕见」随 2026-09-14 分辨率档位批换装而失效,正文里仍有残留。2026-10-18 实数(全仓 markdown 检索):魔法道具 23 处、罕见 17 处;此前根目录状态文件记的「约 30 处/约 18 处」系旧读数。两词都不在 `tools/doc_term_audit.py` 的退役词表里,机器闸抓不到,只能人工裁。
**现状**:「魔法道具」随 2026-09-15 可选类道具删除而失效,「罕见」随 2026-09-14 分辨率档位批换装而失效,正文里仍有残留。2026-10-18 实数(全仓 markdown 检索):魔法道具 23 处、罕见 17 处;此前根目录状态文件记的「约 30 处/约 18 处」系旧读数。两词都不在 `tools/doc_term_audit.py` 的退役词表里,机器闸抓不到,只能人工裁。待裁:扫或不扫;扫则把两词追加进 doc_term_audit 退役词表防再犯。
**归属**:design/gdd/ 正文用语(权威对照=design/gdd/术语表.md)
**状态**:待裁决(扫或不扫;扫则把两词追加进 doc_term_audit 退役词表防再犯)
**状态**:待裁决
---
#### 「通关」与「通过第 N 关」两种口径混用——统一与否待裁(2026-10-18 登记,来源=批次移交,设计面=反哺点)
**现状**:「通关」一词既被用来指「打完一整局冒险」,也被用来指「通过第 N 关」,2026-10-18 实测 design/gdd 内 188 处(此前状态文件记 273 处,口径是全仓)。歧义直接影响难度曲线读数与验收判据的表述——同一个「通关率」两种读法差一个数量级。
**现状**:「通关」一词既被用来指「打完一整局冒险」,也被用来指「通过第 N 关」,2026-10-18 实测 design/gdd 内 188 处(此前状态文件记 273 处,口径是全仓)。歧义直接影响难度曲线读数与验收判据的表述——同一个「通关率」两种读法差一个数量级。待裁:是否定单一口径并逐处改写。
**归属**:design/gdd/01-核心循环.md 与难度曲线、验收类文档的措辞口径
**状态**:待裁决(是否定单一口径并逐处改写)
**状态**:待裁决
---
#### 流程动词族黑话的第二波清扫待发令——GDD 正文约三千处(2026-10-18 登记,来源=批次移交,设计面=反哺点)
**现状**:2026-10-15 用语规范批只按 A 表替换了词面约 250 处(十二行),流程动词族——需要作者额外解释才看得懂的一类说法——在 GDD 正文仍有约三千处未处理。第二波至今未发令。
**现状**:2026-10-15 用语规范批只按 A 表替换了词面约 250 处(十二行),流程动词族——需要作者额外解释才看得懂的一类说法——在 GDD 正文仍有约三千处未处理。第二波至今未发令。待裁:第二波的范围与发令时点。
**归属**:design/gdd 全树正文用语(权威词表=design/gdd/术语表.md 用语规范节)
**状态**:待裁决(第二波的范围与发令时点)
**状态**:待裁决
---
@@ -629,13 +635,15 @@
#### 计数器寿命域未统一(2026-10-18 登记,来源=会话提及,设计面=文档轨)
**现状**:2026-10-19 用户裁定推翻「寿命域统一口径」方向(原方案五档/四档枚举、`domain` 键扩词表整体作废——作废因由=该方案隐含前提「引擎持有状态、需要字段说明它活多久」被推翻,见提案 §8),改走**效果引擎无状态化重构**:引擎零运行时状态,计数器按 round/battle/level/adventure 四桶外置、由各生命周期宿主对象持有(寿命由宿主生灭决定,不再需要寿命字段),归属用 counter_id 前缀表达(`round_`/`lvl_`/`adv_`/无前缀=battle,`meta_` 非法)+加载期强校验。设计定值与实现设计缺口已全部闭合(提案=design/research/提案-效果引擎无状态化-2026-10-19.md,§7 定值+§7.10 闭合)。本条目原指认的三套机制并存问题由该重构一并消解:①`domain`/`reset_at` 两字段随重构删除;②「按关重置」硬编码名单(`adventure_runner.gd:838-841`)随 level 桶宿主化消失;③`run_ledger.gd:42` 空容器早退自锁缺陷随搬运链删除自动消解(代价=行为变更:adventure 域计数器变真跨战持久、天赋树锋/守变真每关限 2 次——削弱方向已定性,提案 §7.7/§7.8)。副产定值:`pain_layers` 名实不符归 battle、`dig_combo` 死读数随重构顺带删除(提案 §7.10.14)。
**现状**:原「寿命域统一口径」方案 2026-10-19 作废,改走效果引擎无状态化重构(提案 §8)。关联文档:
- 设计定稿:design/research/提案-效果引擎无状态化-2026-10-19.md(v1.2,2026-10-20 §7.10 闭合)
- 需求卡片:reports/需求卡片-效果引擎无状态化批-2026-10-20.md
**证据面缺口(迭代 31 卡② 移交)**:`domain=battle` 每战清零与 `domain=adventure` 跨战持久这一对判据,现无法由单元测试 rig 变异证红(`feat_vouchers_test` 的变异②只钉住事件发射时机,未覆盖寿命域)。闭合此项时须在 runner/MC 面补一次「adventure 域计数器跨战持久 vs battle 域清零」的对照读数,或在文档批确认该判据只由代码注释与装载面约束、不设机检。
**归属**:architecture.md 与 game/core/effect_engine.gd(待立独立批)
**状态**:待裁决(是否统一寿命域口径——2026-10-19 已裁:统一口径方案作废,改走无状态化重构)+文档设计已闭合(design/research/提案-效果引擎无状态化-2026-10-19.md v1.2——2026-10-20 §7.10 闭合)+待写卡+已写卡(reports/需求卡片-效果引擎无状态化批-2026-10-20.md)+已编迭代 32
**状态**:待裁决+文档设计已闭合+待写卡+已写卡+已编迭代 32
---
@@ -645,7 +653,7 @@
**归属**:增益状态.md(:10/:14/:44 及连带指路句);art/ 两文件(等 `gpsweep-20261019` 合回)
**状态**:待裁决(第①项增益状态用词改名与否)+待裁决(第②项 GP 更名分支合回时机)
**状态**:待裁决+待裁决
---
@@ -669,7 +677,7 @@
**归属**:①`奇物.md` §1.1/§2.2/v2.2 行(已订正写入文档);②`奇物.md` §1.3(:121/:223/:229)与 `02-系统清单.md:49`(待裁)
**状态**:已写入(design/gdd/systems/冒险循环/奇物.md v3.19——第①项专长凭证归类订正)+待裁决(第②项资源判据句,心智模型未对齐,不列候选不提前处置)
**状态**:已写入+待裁决
---
@@ -685,9 +693,11 @@
**不做(待用户另裁)**:术语表 A 表词一族、doc-conventions 第 4 节流程动词一族、简明技术中文(STC)通用禁用词一族——三族的逐词计数与清单见卡片 §4「不做」表(本行不复制词面:06 正文引述禁词会自指引爆 doc_term 补充通道,判红)。
需求卡片:reports/需求卡片-代码注释禁用词清扫批-2026-10-20.md(v1.3)。
**归属**:game/ 代码与数据表(代码域,走独立 worktree 批;`AGENTS.md` 与 `design/` 依流水线红线本批禁碰,S11 规则说明自持于 `game/tests/static_scan.sh` 头注与 `game/tests/README.md`)
**状态**:已写卡(reports/需求卡片-代码注释禁用词清扫批-2026-10-20.md,**v1.3**)+已编迭代 32
**状态**:已写卡+已编迭代 32
---
+1 -1
View File
@@ -99,7 +99,7 @@
词面纪律的登记处。通用禁用词与选词以**简明技术中文(STC)词表**为权威:外部技能文件 `C:\Users\DK\.zcode\skills\simplified-technical-chinese\词表.md`,约 170 条,配检查脚本 check.py。
本仓库的机器闸 = `tools/doc_term_audit.py`,已吸收本节项目裁项。本节只登记两类裁项:A 已裁替换、B 豁免条款。历史退役词(雷格/正主/落籍等 7 组)见下方「退役词对照」节,不与 A 表重复。
本仓库的机器闸 = `tools/doc_term_audit.py`,已吸收本节项目裁项。**词表冻结**:本节与该闸的禁用词表不再扩充,扩表唯一入口=用户实读反馈并经用户裁决(由非迭代批写入,agent 禁自行增词)。本节只登记两类裁项:A 已裁替换、B 豁免条款。历史退役词(雷格/正主/落籍等 7 组)见下方「退役词对照」节,不与 A 表重复。
### A. 已裁替换(写新文本必须用「用」列)
+2 -2
View File
@@ -43,11 +43,11 @@ else
fail=1
fi
# S10 — 文件头闸(code-conventions §1.4.1:头注 ≤8 行+日期/变更叙事黑名单)
# S10 — 文件头闸(code-conventions §1.4.1:## 载体+日期/变更叙事黑名单;行数上限已停用)
if python tools/audit_file_headers.py; then
echo "[static_scan] S10 ok"
else
echo "[static_scan] S10 FAIL: 文件头存量见上清单(白名单清偿批在册)"
echo "[static_scan] S10 FAIL: 文件头存量见上清单"
fail=1
fi
+2 -8
View File
@@ -3,9 +3,8 @@
"""audit_file_headers.py — 文件头机器闸(code-conventions §1.4.1)。
文件头 = .gd 文件顶部连续注释区:连续的空行或 # 注释行,首个非注释代码行止。
本脚本只实现机械可判子集(两类白名单的人判面见规范正文):
本脚本只实现机械可判子集(2026-10-20 缩窄:行数上限 R1 与类别白名单已停用):
R0 载体:头注非空时首行必须以 `##` 文档注释开头;
R1 行数上限:头注注释行(非空)> 8 行;
R2 日期:头注出现日期模式(2026-09-12 / 2026年9月 一类)——日期只属于 git log 与迭代报告;
R3 变更叙事词:「迭代N / 本迭代」、批次叙事复合词(本批/拆件批/改造批……)、「迁移到/改名为」
一类变更经过。清单从紧防误伤:「结算批」等玩法机制词不在黑名单;
@@ -20,8 +19,6 @@ from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
SCAN_DIRS = ["game/core", "game/data", "game/presentation"]
MAX_HEADER_LINES = 8
DATE_PAT = re.compile(r"\d{4}\s*[-/.年]\s*\d{1,2}")
NARRATIVE_PATS = [
(re.compile(r"迭代\s*\d|本迭代"), "变更叙事「迭代N」"),
@@ -52,9 +49,6 @@ def audit_path(path):
rows = header_lines(text)
if rows and not rows[0][1].lstrip().startswith("##"):
hits.append((rows[0][0], "R0 头注必须以 ## 文档注释开头"))
if len(rows) > MAX_HEADER_LINES:
hits.append((rows[0][0], "R1 头注 %d 行 > 上限 %d 行(区间 %d-%d 行)"
% (len(rows), MAX_HEADER_LINES, rows[0][0], rows[-1][0])))
for lineno, line in rows:
if DATE_PAT.search(line):
hits.append((lineno, "R2 头注日期"))
@@ -77,7 +71,7 @@ def main():
if violations:
print("[audit_file_headers] FAIL: 文件头存量 %d 处(存量按 code-conventions §1.4.1 白名单清偿)" % violations)
return 1
print("[audit_file_headers] ok: 头注 ≤8 行且零黑名单命中")
print("[audit_file_headers] ok: 头注零黑名单命中(R0 载体/R2 日期/R3 变更叙事)")
return 0
+2
View File
@@ -46,6 +46,8 @@ RETIRED_TERMS = [
("雾格", "2026-09-14", "(雾格移除)", "不做清单"),
("兄弟精", "2026-09-26", "L2 熊地精(bugbear 复用)", "变体名未经批准退役批——用户质问查证后全仓清除"),
# —— 用语规范(2026-10-15 用户令):权威=design/gdd/术语表.md「用语规范」A 表,机器闸吸收 ——
# 词表冻结:本节禁再新增词条;扩表唯一入口=用户实读反馈并经用户裁决,由非迭代批写入,agent 禁自行增词
# (doc-conventions §4「词表冻结」)。
# 注意:「随批」「台账」两词本身是上方行级白名单信号(行内出现即归留档类),对其扫描会自豁免,
# 故不列入;「收口」「在飞」等照常扫描。术语表「用语规范」节已加入节级豁免(词表自身不命中)。
("对标", "2026-10-15", "参照", "用语规范 A 表(STC 1.7)"),
+7 -29
View File
@@ -9,7 +9,6 @@ r"""gdd_lint.py — GDD lean 格式门禁
规则(口径权威 = design/engineering/doc-conventions.md 第 5–6 节文档骨架与结构纪律):
R1 散文段落 ≤ 240 字(代码块/表格/列表/引用不计)
R2 表格字符占比(词条表分域豁免,见 R2_EXEMPT 注)
R3 正文禁止修订注记:~~删除线~~、"作废"、括号内"日期+评审/修订/拍板/裁决/核销"
(登记处/清单按 RULE_EXEMPT 分域豁免)
R4 禁止变更记录节:出现「版本历史/修订记录/变更记录/修改记录/更新记录/更新日志」标题即红
@@ -31,29 +30,18 @@ import sys
from pathlib import Path
MAX_PARA = 240
# 2026-09-14 放宽 60→30:lean 改革后的新模板(参考 analysis/design 两件套)允许
# 短段落与编号人话规则——防铺开的职责改由 R1(段 ≤240 字)与 R9(节点 ≤80 行)承担,
# R2 降为兜底下限(防纯散文文档)。
MIN_TABLE_RATIO = 30
# R2 表格占比判据已停用(2026-10-20 规则审阅批):lean 体系退役后其解读对象已不存在,
# 分域豁免越加越多、只产存量噪音(af94ce97 指纹刷新为证),判据与 R2_EXEMPT 一并拆除。
MAX_PAREN_SPAN = 80
# 规则分域(2026-10-03 用户裁「测试要快/要准」优化批):R1/R2 的体裁前提是「规范文」
# (短段+表格化);登记处/清单/概念文的自然形态就是长条目与叙事散文,硬套=自 2026-09-20
# 规则分域(2026-10-03 用户裁「测试要快/要准」优化批):R1 的体裁前提是「规范文」
# (短段+表格化);登记处/清单的自然形态就是长条目与叙事散文,硬套=自 2026-09-20
# 上线起 8/8 常红零过滤价值(test-perf-report-2026-10-02 §6.2 实证)。R3/R7 不豁免——
# 「provenance 出正文」对一切体裁有效;R4 变更记录节禁令自 2026-10-19 起对一切体裁有效。
R1_EXEMPT = {
"06-待办清单.md", # 全项目待办登记处:现状/状态/方案长条目为体裁
"07-体验验证清单.md", # 体验验证读数清单:同上
}
R2_EXEMPT = {
"01-核心循环.md", # 循环概念文:叙事散文为体裁
"03-内容规模.md", # 规模框架文:多维档位靠散文交代,结构表只有一张
"04-美术音频方向.md", # 美术方向文:同上
"05-不做清单.md", # 清单文:条目散文为体裁
"06-待办清单.md",
"07-体验验证清单.md",
"术语表.md", # 词条表:表格为主体形态,表格占比高是体裁本身
}
# 规则粒度分域豁免(2026-10-15 用户令「清单类文件与术语表不做 GDD 规范性检查」)。
# 原则:**按规则豁免,不按文件拉黑**——体裁规则(R3/R5/R7)对登记处/清单/词条表
# 不适用,但机械可判的完整性规则(R4/R6/R8/R9/R11)一律不豁免,真缺陷不得藏起来。
@@ -201,17 +189,7 @@ def lint_file(path):
if len(p) > MAX_PARA:
issues.append(f"R1 散文段 {len(p)} 字(>{MAX_PARA}): {p[:50]}…")
# R2 表格占比(概念/方向/清单文分域豁免,见 R2_EXEMPT 注)
code_chars = sum(len(l) for l in code_lines)
table_chars = sum(len(l) for l in text.splitlines() if l.strip().startswith("|"))
total = max(len(text) - code_chars, 1)
ratio = int(100 * table_chars / total)
if fname in R2_EXEMPT:
infos.append(f"表格占比 {ratio}%(R2 分域豁免)")
elif ratio < MIN_TABLE_RATIO:
issues.append(f"R2 表格占比 {ratio}%(<{MIN_TABLE_RATIO}%)")
else:
infos.append(f"表格占比 {ratio}%")
# R2 表格占比已停用(见文件头注释)。
# R3 修订注记(代码块豁免;登记处/清单按 RULE_EXEMPT 豁免——变更记录节已整体禁设,无豁免域)
body_no_code = "\n".join(l for l in text.splitlines() if l not in code_lines)
@@ -307,7 +285,7 @@ def lint_file(path):
issues.append(f"R7 最长括号跨度 {longest_span} 字(>{MAX_PAREN_SPAN})——疑似审计注记挤进正文")
infos.append(f"最长括号跨度 {longest_span} 字")
return {"file": str(path), "issues": issues, "infos": infos, "table_ratio": ratio}
return {"file": str(path), "issues": issues, "infos": infos}
def main():
@@ -347,7 +325,7 @@ def main():
else:
for r in results:
mark = "❌ FAIL" if r["issues"] else "✅ PASS"
print(f"\n{mark} {r['file']} (表格占比 {r['table_ratio']}%)")
print(f"\n{mark} {r['file']}")
for i in r["infos"]:
print(f" · {i}")
for issue in r["issues"]:
+71 -41
View File
@@ -119,8 +119,12 @@ def check_title(title, line, issues, where):
return face
def check_segment(word, creds, line, issues, where, root):
"""判据 3 的单段校验。返回 (合法状态词|None, 已写卡路径|None, 已编迭代号|None)。"""
def check_segment(word, line, issues, where):
"""判据 3 的单段校验。返回 (合法状态词|None, 已编迭代号|None)。
2026-10-20 状态栏纯化批:状态行只写状态词(§12.1),括号凭据已废止——
闭合证据改到现状关联文档清单核对(check_todo 内),本函数只认状态词本身。
"""
def red(name, msg):
issues.append((where, line, name, msg))
@@ -128,40 +132,24 @@ def check_segment(word, creds, line, issues, where, root):
base = "已编迭代" if word.startswith("已编迭代") else word
if im is None and base == "已编迭代":
red("状态词非法", "「%s」缺迭代号(须「已编迭代 N」)" % word)
return None, None, None
return None, None
if base not in STATUS_WORDS:
red("状态词非法", "「%s」不在合法状态词白名单" % word)
return None, None, None
cred_text = ";".join(creds)
if base in ("文档设计已闭合", "已写入"):
if not (VER_RE.search(cred_text) and ("/" in cred_text or ".md" in cred_text)):
red("凭据缺失", "「%s」须带括号落点凭据(文档路径+版本号形态)" % base)
elif base == "美术设计已闭合":
if not ("art-bible" in cred_text.lower() and VER_RE.search(cred_text)):
red("凭据缺失", "「美术设计已闭合」凭据须含 art-bible 路径+版本号")
elif base == "已写卡":
rp = None
for c in creds:
m = RESEARCH_RE.search(c)
if m:
rp = m.group(0)
break
if rp is None:
red("凭据缺失", "「已写卡」括号内须为 reports/ 下的需求卡片路径")
elif not (root / rp).is_file():
red("卡片路径不存在", "已写卡路径 %s 相对仓库根不存在" % rp)
return base, rp, None
red("状态词非法", "「%s」不在合法状态词白名单" % base)
return None, None
if im is not None:
return base, None, int(im.group(1))
return base, None, None
return base, int(im.group(1))
return base, None
def check_status(raw, line, face, issues, where, root):
"""判据 3+状态段累积制(§12.1)+特批/备选。返回 (状态词列表, 已写卡路径列表, 已编迭代号|None)。
def check_status(raw, line, face, issues, where):
"""判据 3+状态段累积制(§12.1)+特批/备选。返回 (状态词列表, 已编迭代号|None)。
累积制:按+切段后段数不限,逐段各自合法;再查两条结构约束——
下游段(待写卡/已写卡/已编迭代)在场时上游闭合段必须在场(带日期特批可豁免);
双轨设计阶段(无下游段)必须恰两段且一文档一美术。
状态行只写状态词(§12.1):去掉特批标记与(备选)后缀后,残留任何括号即红——
证据写现状关联文档清单,由 check_todo 到正文核对;此处点名病因后短路,
不再产出碎片「状态词非法」误导红。
"""
content = raw.strip()
m = re.match(r"^\*\*(.+)\*\*$", content)
@@ -175,28 +163,28 @@ def check_status(raw, line, face, issues, where, root):
issues.append((where, line, "特批标记", "〔用户特批〕缺日期(带 YYYY-MM-DD 才放行跳轨)"))
content = APPROVAL_RE.sub("", content)
content = content.replace("(备选)", "").replace("(备选)", "").strip()
if re.search(r"[(())]", content):
issues.append((where, line, "状态行含括号内容",
"括号里的信息(路径/版本/说明)写进现状关联文档清单,状态行只留状态词(§12.1)"))
return [], None
segs = [s.strip() for s in content.split("+") if s.strip()]
if not segs:
issues.append((where, line, "状态词非法", "状态行内容为空"))
return [], [], None
words, cards, iter_no = [], [], None
return [], None
words, iter_no = [], None
for seg in segs:
creds = CRED_RE.findall(seg)
word = CRED_RE.sub("", seg).strip()
w, rp, it = check_segment(word, creds, line, issues, where, root)
w, it = check_segment(seg, line, issues, where)
if w:
words.append(w)
if rp:
cards.append(rp)
if it is not None:
iter_no = it
downstream = [w for w in words if w in DOWNSTREAM_WORDS]
if downstream and face in PRESENCE_FACES and not dated_approval:
need = []
if face in ("文档轨", "双轨") and "文档设计已闭合" not in words:
need.append("文档设计已闭合(凭据)")
need.append("文档设计已闭合")
if face in ("美术轨", "双轨") and "美术设计已闭合" not in words:
need.append("美术设计已闭合(凭据)")
need.append("美术设计已闭合")
if need:
issues.append((where, line, "在场约束",
"下游段(%s)在场但缺上游闭合段 %s(带日期特批可豁免)"
@@ -208,11 +196,16 @@ def check_status(raw, line, face, issues, where, root):
issues.append((where, line, "双轨段数",
"设计面=双轨设计阶段须恰两段且一文档一美术(现 %d 段:文档轨 %d、美术轨 %d)"
% (len(segs), n_doc, n_art)))
return words, cards, iter_no
return words, iter_no
def check_todo(text, issues, where, root):
"""06 全部判据。返回交叉核链(已编迭代条目 → (行号, 迭代号, 卡片路径|None))。"""
"""06 全部判据。返回交叉核链(已编迭代条目 → (行号, 迭代号, 卡片路径|None))。
2026-10-20 状态栏纯化批:闭合类状态词的证据核对从状态栏括号改到现状关联文档
清单(§12.1「状态行只写状态词」)——已写卡对 reports/ 卡片路径+磁盘存在性,
文档轨闭合/已写入对 design/ 路径+版本号,美术轨闭合对 art-bible+版本号。
"""
entries = parse_todo(text)
links = []
if not entries:
@@ -233,8 +226,45 @@ def check_todo(text, issues, where, root):
issues.append((where, line, "属性缺失", "条目缺「**%s**」属性" % req))
if "状态" not in attrs:
continue
words, cards, iter_no = check_status(
attrs["状态"], attr_line["状态"], face, issues, where, root)
words, iter_no = check_status(
attrs["状态"], attr_line["状态"], face, issues, where)
# 现状属性全文(含清单续行):证据核对只看现状,其他属性不算数
xian_lines, in_xian = [], False
for ln, raw in e["body"]:
m = ATTR_LINE_RE.match(raw.strip())
if m:
in_xian = m.group(1) == "现状"
if in_xian:
xian_lines.append(m.group(2))
elif in_xian:
xian_lines.append(raw)
xian = "\n".join(xian_lines)
xline = attr_line.get("现状", line)
# 证据核对一:已写卡 → 现状清单须有卡片路径,逐条验磁盘存在
cards = []
if "已写卡" in words:
cards = RESEARCH_RE.findall(xian)
if not cards:
issues.append((where, xline, "正文缺卡片路径",
"状态段「已写卡」在场,但现状关联文档清单里没有 "
"reports/需求卡片-*.md 路径(§12.1:证据写正文)"))
else:
for rp in cards:
if not (root / rp).is_file():
issues.append((where, line, "卡片路径不存在",
"现状清单里的卡片路径 %s 相对仓库根不存在" % rp))
# 证据核对二:文档轨闭合/反哺已写入 → 现状清单须有文档路径+版本号
# (06 正文里的指针是相对路径,形如 systems/… 或 design/…,只认 .md 收尾+版本号)
if "文档设计已闭合" in words or "已写入" in words:
if not (re.search(r"[^\s ,,()()]+\.md", xian) and VER_RE.search(xian)):
issues.append((where, xline, "正文缺设计定稿指针",
"状态段含文档轨闭合词,但现状清单里没有带版本号的文档路径(§12.1:证据写正文)"))
# 证据核对三:美术轨闭合 → 现状清单须有 art-bible 版本凭据
if "美术设计已闭合" in words:
if not ("art-bible" in xian.lower() and VER_RE.search(xian)):
issues.append((where, xline, "正文缺美术凭据",
"状态段「美术设计已闭合」在场,但现状清单里没有 "
"art-bible 版本凭据(§12.1:证据写正文)"))
need_gap = any(w in GAP_REQUIRED for w in words)
if need_gap and "缺口" not in attrs:
issues.append((where, line, "缺口属性",