chore(文档缺陷订正与机检补件): 四份根文件用词与死指订正＋新增引用可核机检件
修文档缺陷四处：AGENTS.md「收口」×2、「不得」×3 换白话；roadmap.md:87「对拍」「标旗」换代； reports/README.md 指向已迁移的 design/gdd/06-待办清单.md 改指仓库根；待办清单 iter19 遗留第⑦项 前半「数据配置.md:223 历史行死指」实查核销（该文件版本史行已随禁写变更记录规约消亡，现 212 行）。 补机检：tools/doc_ref_audit.py 核文档内「文件:行号」指针的目标存在性与行界，带扫描面为空与 引用数为零双自检；双向变异证据——注入不存在路径 EXIT=1、注入超界行号 EXIT=1、还原 EXIT=0。 doc_term 扫描面扩到四份根文件：扩面前实测这批文件自身含 3 处用语表废止词，先改现实再扩面， 扩面后「疑似现行」0、注入「完美排雷」见红 EXIT=1、还原 EXIT=0。 08d 引用可核暂不注册进闸壳：建档须改 game/tests/.gates/baseline.json，触 game/ 即要求代码域全量测试， 文档域批按测试两入口铁规零跑——注册欠账已登记待办清单。内容锚核对实测 81 处出 58 条未命中（约七成噪声）， 按建议级交付不判红。文档域闸全绿。
This commit is contained in:
DKChan committed
1 parent
735a08d889
commit
7493aebca8
8 files changed
+254
-12
No files matched your search
@@ -31,7 +31,7 @@
|
||||
- `artwork/` — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 `archive/`
|
||||
- `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/` — 游戏工程本体（代码 + smoke/ 冒烟 + tests/ 单元集成）
|
||||
- `sim-data/` — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑
|
||||
- `tools/` — python 工具脚本；`archive/` — 收口归档 zip（gitignored）
|
||||
- `tools/` — python 工具脚本；`archive/` — 批次完结归档 zip（gitignored）
|
||||
- `reports/` — 过程件容器：**需求卡片**（写卡段产出，实现批的输入合同）＋迭代批产出物（实现报告/代拍板追认单/GDD 反哺点清单）；**实现批唯一可写目录**，只放 .md，不是事实源（细则见 `reports/README.md`）
|
||||
- 根目录：`README.md`（纯指路牌：设计/流程/当前位/待办四个链接，零规则重述）、`roadmap.md`（里程碑＋迭代总表六列＋顶部「当前位」节＝现在做什么）、`待办清单.md`（流水线唯一登记处，条目级待办与状态）、`体验验证清单.md`（需真人试玩才能下结论的验证项）、`stage.txt`/`review-mode.txt`（运行开关）；仓库根禁止再设会话状态文件（细则见 doc-conventions 第 10 节）
|
||||
|
||||
@@ -56,22 +56,22 @@
|
||||
- **仓库根禁止设会话状态文件**（`active.md` 已废除）——现状看 roadmap「当前位」，待办看待办清单，过程看 git 提交信息，产出物看 `reports/`；任何文档禁止另设「当前状态快照」节，两处记同一件事必然漂移（细则见 doc-conventions 第 10 节）
|
||||
- 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测
|
||||
- 交付前验收 = 跑 `tools/run_all_gates.sh` **按改动域**全绿（唯一入口、唯一闸清单、唯一域划分，禁在文档另列）；合回 master 由 worktree-guard 按 diff 推域校验回执强制（process-conventions §3）
|
||||
- **两类批**——**迭代批**（代码实现，`/iter` 发射）：**禁写 `design/` 整个目录与两份根流程清单（`待办清单.md`/`体验验证清单.md`）**（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批不得顺手改；产出物只准写 `reports/`；批末只跑代码域闸。**非迭代批**（工具/规则/文档改动）：不占 roadmap 迭代号，按改动域跑闸。文档内容的落地走五段流水线相应段（文档设计段入口=doc-design 技能；登记条目格式由流水线闸强制）
|
||||
- **两类批**——**迭代批**（代码实现，`/iter` 发射）：**禁写 `design/` 整个目录与两份根流程清单（`待办清单.md`/`体验验证清单.md`）**（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批禁止顺手改；产出物只准写 `reports/`；批末只跑代码域闸。**非迭代批**（工具/规则/文档改动）：不占 roadmap 迭代号，按改动域跑闸。文档内容的落地走五段流水线相应段（文档设计段入口=doc-design 技能；登记条目格式由流水线闸强制）
|
||||
- 五段流水线铁律——一切工作按「登记 → 文档设计／美术设计 → 写需求卡片 → 迭代编排 → 实现」推进，段间不自动流转、每段转进由用户发令；编入迭代的卡片必须设计闭合＋零待裁点，流水线闸 `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）
|
||||
- **验收闭合**——每个需求点与每个行为改动都要有从真实入口进入的验收断言，撤销该改动能让对应断言变红；禁删断言/放宽阈值换绿；合回前独立验收审计未过不得合并（细则=test-conventions §9＋iter 技能第 5 步）
|
||||
- **验收闭合**——每个需求点与每个行为改动都要有从真实入口进入的验收断言，撤销该改动能让对应断言变红；禁删断言/放宽阈值换绿；合回前独立验收审计未过则禁止合并（细则=test-conventions §9＋iter 技能第 5 步）
|
||||
- 规则评估——没在真实任务上评估过的规则修订，不算完成。
|
||||
- 中间产物吸收即死——结论先吸收进权威文档、未决先迁待办清单，文件即删且永不提交（doc-conventions 第 11 节）
|
||||
- **禁写变更记录**——文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁写「本版改了哪些条款」式逐版本叙述与 `# 2026-xx-xx 缺陷修批——` 式行内修订注记；沿革只进 git commit log。版本号可作文档现行身份标记留在文首状态行与正文引用中（doc-conventions 第 5 节，机检闸 gdd_lint R4 反转拦截）
|
||||
- 用语红线——一切对用户输出禁自造黑话，需要作者解释的词必须展开成完整白话句（doc-conventions 第 4 节三形态表）
|
||||
- 呈报四问（读后自检制）——向用户首次完整呈报一件事（需求／缺陷／方案／结论）时，写完先自查：读者只读这一段，能否不看原文答出——① 现状差在哪：现在是什么、缺什么；② 你建议做什么：做完预期什么效果、会动到哪些面；③ 为什么选这个做法：考虑过、放弃过哪些别的路；④ 做完怎么验证：哪些还有把握不足。哪问答不出就补哪问，禁靠加小标题凑数；三句话能说清的小件合并为三句：现状一句、建议与验证一句、没把握的一句；后续追问与推进不必重跑全框架
|
||||
- 真人检测只登记不阻塞——登记进体验验证清单/实现报告即完成义务，禁以等目检为停工理由或收口前置
|
||||
- 真人检测只登记不阻塞——登记进体验验证清单/实现报告即完成义务，禁以等目检为停工理由或当作合回的前置条件
|
||||
- 文件头 = `##` 文档注释，介绍本模块是什么；禁写变更叙事（改动史查 git log）；禁文档反向链接（code-conventions §1.4.1）
|
||||
- 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径
|
||||
- RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流
|
||||
- 架构事实唯一源——架构事实只认 `design/engineering/architecture/architecture.md`；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log
|
||||
- Core 层零 UI 依赖——完整战斗必须可 `--headless --script` 跑通；fail-fast——数据校验错误一律致命中止，无软回退
|
||||
- spec-AC 一致性——规约与验收标准不得在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离）
|
||||
- spec-AC 一致性——规约与验收标准禁止在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离）
|
||||
- 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节）
|
||||
@@ -160,3 +160,4 @@
|
||||
**获取概率提升**是元进度/营地的合法提升轴（可提升=奇物高档位出现率/秘宝解锁进度/地图 T3/T4 权重），但**不动保底**——保底是承诺不是概率，禁止任何概率件改变 T3「每板必有回复」类承诺。
|
||||
|
||||
**专长 rarity 语义约束**：Boss 三选一候选按档配比或加权抽取，使罕见度对出现率生效（字段双脱钩修复——此前 rarity 不影响抽选也不稳代表幅度）；具体配比归调参批。
|
||||
|
||||
+1
-1
@@ -18,7 +18,7 @@
|
||||
- **不放设计结论。** 本目录的文件是"待处理的申请单"，不是事实源。反哺点由你在会话中讨论定稿后，
|
||||
另开文档批写进 `design/`，写完即可删除本目录对应条目。
|
||||
- **不放图。** 图像白名单不含本目录，放了会被熵增闸判红。
|
||||
- **不放进度状态。** 现在做什么看根 `roadmap.md` 顶部「当前位」节，待办与待裁看 `design/gdd/06-待办清单.md`（2026-10-18 用户裁：根目录会话状态文件已废除，本目录也不许兼做状态记录）。
|
||||
- **不放进度状态。** 现在做什么看根 `roadmap.md` 顶部「当前位」节，待办与待裁看仓库根 `待办清单.md`（2026-10-18 用户裁：根目录会话状态文件已废除，本目录也不许兼做状态记录）。
|
||||
|
||||
## 生命周期
|
||||
|
||||
|
||||
+1
-1
@@ -84,7 +84,7 @@
|
||||
> **迭代粒度界定（对齐敏捷迭代/Sprint）**：一个迭代 = 一句迭代目标 + **3–8 个更改任务** + 一份计划书 loop + 一次合并登记，交付一个可验证增量（≈一次迭代交付）。单交付物不成迭代——并入相邻迭代当任务卡；用户输入闸未解的任务不进迭代（留待办清单当 backlog，解闸后编入下一个迭代）；**迭代周期 ≈ 一周左右**（2026-10-11 用户裁定——原「软时间盒 ≤3 个工作日，超限即切迭代」系 3abb3bd2 成文时自造、用户从未立过此规，就此废弃）。**里程碑 = 2–4 个迭代的发布级目标 + 出口验收闸（≈Release）**。
|
||||
>
|
||||
1. **计划书**（`.zcode/plans/<迭代名>-loop-plan-<日期>.md`）：迭代目标与完成定义 / 现状事实（代码级，开工自行复核）/ 设计契约（违反即返工，标 🔴 触碰=L3 停机）/ 范围边界 / 任务卡 T0..Tn（逐卡估时）/ 验证闸 / 异常分级 / 代拍板白名单。
|
||||
2. **T0 开工**：建 worktree + 基线复读记档（冒烟/探针/三闸/MC 对拍基准）+ `git status` 归属核对（并行遗留只标旗不碰）。
|
||||
2. **T0 开工**：建 worktree + 基线复读记档（冒烟/探针/三闸/MC 与基线数据逐项比对基准）+ `git status` 归属核对（并行遗留只登记不触碰）。
|
||||
3. **循环骨架**：一轮 = 一个任务卡——读卡 → 对事实源 → 实装 → 轻闸全绿 → 提交（代拍板随 commit 记录）→ 状态记录追加（查撞号）→ 下一轮。单 worktree 多点提交一次合并；轮内禁开第二个 worktree；基线每轮开工时点重测；断点续跑 = `git log` 对任务卡定轮次 + 重跑当轮轻闸。
|
||||
4. **轻闸**（每轮必跑，headless）：`tools/run_all_gates.sh --quick`（迭代中段自检档）。
|
||||
5. **重闸**（批末 Tn）：`tools/run_all_gates.sh` **按本批改动域跑**（触及 `game/` → `--code`，这是代码域唯一触发；不触及 `game/` 的一切路径 → `--docs`；一次改动同批混触两域 → 不带参数全量），所选域全绿——闸件清单、顺序与域划分只在该脚本里定义，本文件与 AGENTS.md/规约均不另列；改闸件自身（`tools/` 下机检脚本与闸壳）不占合回全量，质量义务＝落批时的变异验证；涉核心的 MC 与基线逐位比对、素材批的机检断言另行。
|
||||
|
||||
@@ -0,0 +1,219 @@
|
||||
#!/usr/bin/env python3
|
||||
r"""doc_ref_audit.py — 文档内代码引用可核检查（机检）
|
||||
|
||||
职责：现行文档里凡写「某文件:第几行」，就该指得动。本工具核两件事：
|
||||
①路径可解析——目标文件在 git 受控文件清单里存在；
|
||||
②行号在界内——引用的行号不超过目标文件的实际行数。
|
||||
动机：条目与规约常写 `board_view.gd:737` 这类指针，代码前进后行号漂移、文件迁移改名，
|
||||
账面就与现实脱节而无人知（2026-10-21 迭代 32 收尾时实测抓到两例）。
|
||||
|
||||
扫描面：`design/` 现行文档树 ＋ 四份根文件（`待办清单.md`／`体验验证清单.md`／`roadmap.md`／`AGENTS.md`）。
|
||||
排除面：`reports/` 与 `design/research/`——两处是中间文档暂存地（doc-conventions 第 11 节），
|
||||
入内文件按「吸收即死」退役，历史件不回溯改，故不入本闸判据。
|
||||
|
||||
自检二道（防假绿）：扫描文件数为零 ⇒ FAIL；抽取到的引用数为零 ⇒ FAIL。
|
||||
（正则被改写失手或路径写错时，检查会静默空转并报绿——与 static_scan 各段同规。）
|
||||
|
||||
判据分两档：
|
||||
红（判 FAIL）＝路径不存在／行号超界；
|
||||
建议（只报告）＝同名文件有多条路径需要人工定位／`--anchors` 的内容锚没在目标行附近找到。
|
||||
|
||||
用法:
|
||||
python tools/doc_ref_audit.py # 全扫，报告模式
|
||||
python tools/doc_ref_audit.py --strict # 有红项时 exit 1（供门禁）
|
||||
python tools/doc_ref_audit.py --anchors # 追加内容锚核对（只报告，不判红）
|
||||
python tools/doc_ref_audit.py <file.md> ... # 只扫指定文件
|
||||
exit：0=全绿 / 1=有红项（--strict）/ 2=扫描面异常（目录缺失）
|
||||
"""
|
||||
import argparse
|
||||
import io
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
REPO = Path(__file__).resolve().parents[1]
|
||||
|
||||
SCAN_DIRS = ["design"]
|
||||
SCAN_EXCLUDE_DIRS = ["design/research"]
|
||||
ROOT_FILES = ["待办清单.md", "体验验证清单.md", "roadmap.md", "AGENTS.md"]
|
||||
|
||||
# 引用形态：路径或文件名 + 扩展名 + 半/全角冒号 + 行号。反引号可包在中间或外面，
|
||||
# 因此先抓到扩展名为止，冒号允许紧跟或在反引号之后。
|
||||
REF_RE = re.compile(
|
||||
r"([\w./一-鿿-]+\.(?:gd|tres|sh|py|json|md|cfg|yml|yaml|txt|png|html))"
|
||||
r"[`”』」]?\s*[:：]\s*(\d+)"
|
||||
)
|
||||
# 内容锚：同一行内的反引号片段或「」内文本，取长度 ≥4 的第一个非引用片段
|
||||
ANCHOR_RE = re.compile(r"`([^`\n]{4,60})`|「([^」\n]{4,60})」")
|
||||
ANCHOR_WINDOW = 12
|
||||
# 留档信号（与 doc_term_audit 同口径）：同句带日期或退役/注销类说明时，指向已不存在的路径
|
||||
# 属历史叙述而非现行指针，降为建议级报出、不判红。
|
||||
ARCHIVE_RE = re.compile(
|
||||
r"\d{4}-\d{2}-\d{2}|退役|注销|已删|已废除|已废|废除|作废|历史|原名|改名|迁入|迁到|移到|迁至"
|
||||
)
|
||||
|
||||
|
||||
def tracked_files():
|
||||
out = subprocess.run(
|
||||
["git", "-c", "core.quotepath=false", "-C", str(REPO), "ls-files"],
|
||||
capture_output=True, text=True, encoding="utf-8", errors="ignore",
|
||||
)
|
||||
if out.returncode != 0:
|
||||
return None
|
||||
return {l.strip().strip('"').replace("\\", "/") for l in out.stdout.splitlines() if l.strip()}
|
||||
|
||||
|
||||
def collect_docs(explicit):
|
||||
if explicit:
|
||||
return [p for p in explicit if Path(p).is_file()]
|
||||
paths = []
|
||||
for d in SCAN_DIRS:
|
||||
root = REPO / d
|
||||
if not root.is_dir():
|
||||
return None
|
||||
for p in sorted(root.rglob("*.md")):
|
||||
rel = p.relative_to(REPO).as_posix()
|
||||
if any(rel.startswith(x + "/") for x in SCAN_EXCLUDE_DIRS):
|
||||
continue
|
||||
paths.append(rel)
|
||||
for f in ROOT_FILES:
|
||||
if (REPO / f).is_file():
|
||||
paths.append(f)
|
||||
return paths
|
||||
|
||||
|
||||
def resolve(name, doc_rel, index, bybase):
|
||||
"""返回 (命中路径列表, 解析方式)。方式=exact / ambiguous / none。"""
|
||||
name = name.strip("./")
|
||||
if "/" in name:
|
||||
for cand in (
|
||||
os.path.normpath(os.path.join(os.path.dirname(doc_rel), name)).replace("\\", "/"),
|
||||
os.path.normpath(name).replace("\\", "/"),
|
||||
):
|
||||
if cand in index:
|
||||
return [cand], "exact"
|
||||
return [], "none"
|
||||
cands = sorted(bybase.get(name, []))
|
||||
if not cands:
|
||||
return [], "none"
|
||||
if len(cands) == 1:
|
||||
return cands, "exact"
|
||||
return cands, "ambiguous"
|
||||
|
||||
|
||||
def line_count(path, cache):
|
||||
if path not in cache:
|
||||
try:
|
||||
cache[path] = len(io.open(REPO / path, encoding="utf-8", errors="ignore").read().splitlines())
|
||||
except OSError:
|
||||
cache[path] = 0
|
||||
return cache[path]
|
||||
|
||||
|
||||
def anchor_of(line, name):
|
||||
"""取同句里可当内容锚的片段：反引号或「」内、长度 ≥4、且自身不是文件路径。"""
|
||||
for m in ANCHOR_RE.finditer(line):
|
||||
frag = (m.group(1) or m.group(2)).strip()
|
||||
if name.split("/")[-1] in frag:
|
||||
continue
|
||||
if re.search(r"\.(gd|tres|sh|py|json|md|yaml|yml|html|png)$", frag):
|
||||
continue
|
||||
if re.fullmatch(r"[\d:~\-]+", frag):
|
||||
continue
|
||||
return frag
|
||||
return None
|
||||
|
||||
|
||||
def check(doc_rel, index, bybase, cache, anchors=False):
|
||||
reds, advises = [], []
|
||||
text = io.open(REPO / doc_rel, encoding="utf-8", errors="ignore").read()
|
||||
for ln, line in enumerate(text.splitlines(), 1):
|
||||
for m in REF_RE.finditer(line):
|
||||
name = m.group(1).lstrip("①②③④⑤⑥⑦⑧⑨⑩〔［[（(「」·、。，,;；")
|
||||
num = int(m.group(2))
|
||||
hits, how = resolve(name, doc_rel, index, bybase)
|
||||
if how == "none":
|
||||
if ARCHIVE_RE.search(line):
|
||||
advises.append("%s:%d 引用已退役件 指 `%s`——同句带日期或退役/注销类说明，按留档处理" % (doc_rel, ln, name))
|
||||
else:
|
||||
reds.append("%s:%d 引用可核/路径不存在 文档指 `%s`，git 受控文件清单里没有这件" % (doc_rel, ln, name))
|
||||
continue
|
||||
if how == "ambiguous":
|
||||
advises.append("%s:%d 同名多路径 指 `%s`——命中 %d 件（%s），需写全路径" % (
|
||||
doc_rel, ln, name, len(hits), ", ".join(hits[:3])))
|
||||
target = hits[0]
|
||||
total = line_count(target, cache)
|
||||
if num > total:
|
||||
if ARCHIVE_RE.search(line):
|
||||
advises.append("%s:%d 行号已越界（留档句） 指 `%s:%d`，目标现 %d 行——同句带退役/日期说明" % (
|
||||
doc_rel, ln, name, num, total))
|
||||
else:
|
||||
reds.append("%s:%d 引用可核/行号超界 指 `%s:%d`，目标文件现只有 %d 行" % (doc_rel, ln, name, num, total))
|
||||
continue
|
||||
if anchors:
|
||||
frag = anchor_of(line, name)
|
||||
if frag:
|
||||
lines = io.open(REPO / target, encoding="utf-8", errors="ignore").read().splitlines()
|
||||
lo, hi = max(0, num - 1 - ANCHOR_WINDOW), min(len(lines), num + ANCHOR_WINDOW)
|
||||
window = "\n".join(lines[lo:hi])
|
||||
if frag not in window:
|
||||
advises.append("%s:%d 内容锚未命中 指 `%s:%d`，同句片段「%s」不在该线 ±%d 行内" % (
|
||||
doc_rel, ln, os.path.basename(name), num, frag[:28], ANCHOR_WINDOW))
|
||||
return reds, advises
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser(description="文档内代码引用可核检查")
|
||||
ap.add_argument("files", nargs="*", help="指定文件；缺省扫 design/ 现行树＋四份根文件")
|
||||
ap.add_argument("--strict", action="store_true", help="有红项时 exit 1")
|
||||
ap.add_argument("--anchors", action="store_true", help="追加内容锚核对（只报告）")
|
||||
args = ap.parse_args()
|
||||
|
||||
index = tracked_files()
|
||||
if index is None:
|
||||
print("引用可核 FAIL：git ls-files 取不到受控文件清单（扫描面异常）")
|
||||
return 2
|
||||
docs = collect_docs(args.files)
|
||||
if docs is None:
|
||||
print("引用可核 FAIL：扫描目录缺失（design/ 不在位）")
|
||||
return 2
|
||||
if not docs:
|
||||
print("引用可核 FAIL：扫描面为空——路径写错导致的静默假绿")
|
||||
return 1
|
||||
|
||||
bybase = {}
|
||||
for p in index:
|
||||
bybase.setdefault(p.rsplit("/", 1)[-1], []).append(p)
|
||||
|
||||
cache, all_reds, all_adv = {}, [], []
|
||||
total_refs = 0
|
||||
for doc in docs:
|
||||
reds, adv = check(doc, index, bybase, cache, anchors=args.anchors)
|
||||
total_refs += doc_ref_count(doc)
|
||||
all_reds += reds
|
||||
all_adv += adv
|
||||
if total_refs == 0:
|
||||
print("引用可核 FAIL：抽取到的引用数为零——正则或扫描面失手，属假绿防线")
|
||||
return 1
|
||||
|
||||
for r in all_reds:
|
||||
print(r)
|
||||
print("── 引用可核：扫描 %d 件文档 · 抽取引用 %d 处 · 红项 %d · 建议 %d" % (
|
||||
len(docs), total_refs, len(all_reds), len(all_adv)))
|
||||
if all_adv:
|
||||
for a in all_adv[:25]:
|
||||
print(" （建议）" + a)
|
||||
if len(all_adv) > 25:
|
||||
print(" （建议）…另有 %d 条" % (len(all_adv) - 25))
|
||||
return 1 if (args.strict and all_reds) else 0
|
||||
|
||||
|
||||
def doc_ref_count(doc_rel):
|
||||
text = io.open(REPO / doc_rel, encoding="utf-8", errors="ignore").read()
|
||||
return sum(len(REF_RE.findall(l)) for l in text.splitlines())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -14,8 +14,9 @@ r"""doc_term_audit.py — GDD 退役术语扫描（半自动）
|
||||
python tools/doc_term_audit.py <file.md> ... # 只扫指定文件
|
||||
python tools/doc_term_audit.py --json # 机器可读
|
||||
|
||||
口径：扫 design/gdd/ 与 design/art/ 两处文档域（2026-10-21 迭代 32 卡①反哺批扩面 art，
|
||||
用户裁）——design/research（历史提案）、docs/（样例）与 production/ 不在扫描域；
|
||||
口径：扫 design/gdd/ 与 design/art/ 两处文档域 ＋ 四份根文件（`待办清单.md`／`体验验证清单.md`／
|
||||
`roadmap.md`／`AGENTS.md`，2026-10-21 迭代 32 卡①反哺批扩面，用户裁；根文件同属现行文本）
|
||||
——design/research（历史提案）与 reports/（中间文档）不在扫描域；
|
||||
词表扩充 = 改 RETIRED_TERMS（受 doc-conventions §4 词表冻结约束：唯一入口=用户实读反馈并经用户裁决）。
|
||||
"""
|
||||
import argparse
|
||||
@@ -71,6 +72,10 @@ RETIRED_TERMS = [
|
||||
]
|
||||
|
||||
DEFAULT_DIRS = ["design/gdd", "design/art"]
|
||||
# 根规则与流程文件同属现行文本，2026-10-21 迭代 32 反哺批复测后纳入扫描面：
|
||||
# 当日实测这批文件自身含 3 处用语表废止词（roadmap 的「对拍」「标旗」、AGENTS 的「收口」×2），
|
||||
# 随同批订正后判红归零才扩面——先改现实、再让闸盯住现实，避免带红扩面。
|
||||
DEFAULT_FILES = ["待办清单.md", "体验验证清单.md", "roadmap.md", "AGENTS.md"]
|
||||
|
||||
# 用语规范 A 表补充词专项补扫：随批/台账 两词本身是上方行级白名单信号（行内出现即归
|
||||
# 留档类），主扫描对它们自豁免；本通道只做节外残留的专项报告，供后续触碰批清偿。
|
||||
@@ -191,6 +196,7 @@ def main():
|
||||
for d in DEFAULT_DIRS:
|
||||
paths += sorted(Path(d).rglob("*.md"))
|
||||
paths += sorted(Path(d).rglob("*.yaml"))
|
||||
paths += [Path(f) for f in DEFAULT_FILES]
|
||||
paths = [p for p in paths if Path(p).exists()]
|
||||
|
||||
findings = scan(paths) + scan_supplement(paths)
|
||||
|
||||
@@ -185,6 +185,9 @@ gate "07 doc_link" "doc_link.log" "$PY" "$REPO/tools/doc_link_audit.py" --strict
|
||||
gate "08 doc_term" "doc_term.log" "$PY" "$REPO/tools/doc_term_audit.py" --strict
|
||||
# ── 8c. 流水线闸（待办清单条目状态机＋roadmap 迭代总表＋一次交叉核，判据=doc-conventions §12）──
|
||||
gate "08c 流水线闸" "pipeline.log" "$PY" "$REPO/tools/pipeline_gate.py"
|
||||
# 8d 引用可核（tools/doc_ref_audit.py，2026-10-21 交付）暂不注册：新闸件无基线记录必判「闸况变化」拦回执，
|
||||
# 而建档要改 game/tests/.gates/baseline.json——触 game/ 即要求代码域全量测试（process-conventions §3.10 推域口径），
|
||||
# 文档域批按测试两入口铁规零跑游戏测试。注册与建档随下一个触 game/ 的批次一并做（待办清单在册）。
|
||||
fi
|
||||
# ── 6c. 回放确定性对拍（条件闸件；属代码域）──
|
||||
if in_domain code; then
|
||||
|
||||
@@ -513,9 +513,9 @@
|
||||
4. **迷雾对三关扩对**（iter19 卡②遗留）：素材不入 git 致三关逐关 floor avg 实查受限，ui_contrast 迷雾测点现按在册单值 #453020；素材入库或授权读素材后，以 tools 脚本算三关逐关 avg→最亮者核合成（最坏情况判据契约 7 完整化）。**归属**：对比度探针面（前置＝素材可读授权）
|
||||
5. **字面量墨收测前置**（iter19 卡②遗留）：bcard 属性描述/类型脚注/✓章/primary_button 字四处内联 Color8 无常量形态，收测需先在 ui_kit 立常量（呈现批顺路件，改 ui_kit 越当批面）。**归属**：呈现优化批（ui_kit 常量面）
|
||||
6. **TG_* 装饰带非文字判据**（iter19 卡②遗留）：卡顶类型色带为 8px Bayer 抖动装饰带（DitherBand），非文字；如需机检化（WCAG 1.4.11 非文字 3:1）另立探针段裁决。**归属**：对比度探针扩展段
|
||||
7. **数据配置.md:223 历史行死指 + 商店房截图纳屏**（iter19 卡①遗留）：前者＝v0.4 版本史行 backtick 指已退役探针（doc_link advisory 级不 FAIL，历史行不改写原则下留观，如需清零可下批 prose 化+补退役行）；后者＝商店房截图纳屏留后续呈现批（考证结论在 shot_probe 头注）。**归属**：文档卫生批/呈现批
|
||||
7. **商店房截图纳屏**（iter19 卡①遗留）：商店房截图纳屏留后续呈现批（考证结论在 shot_probe 头注）。本项原并列的「`数据配置.md:223` 历史行死指」半句已于 2026-10-21 实查核销——禁写变更记录规约生效后该文件的版本史行整段已不存在（现全文 212 行，文内零版本史行），被指对象随之消亡。**归属**：呈现批
|
||||
|
||||
**归属**：①熵增闸白名单 ②冒险结构/战斗开场参数面 ③⑤呈现优化批 ④⑥对比度探针面/扩展段 ⑦文档卫生批/呈现批——逐项见现状清单
|
||||
**归属**：①熵增闸白名单 ②冒险结构/战斗开场参数面 ③⑤呈现优化批 ④⑥对比度探针面/扩展段 ⑦呈现批——逐项见现状清单
|
||||
|
||||
**状态**：待写卡（备选）
|
||||
|
||||
@@ -713,7 +713,7 @@
|
||||
|
||||
#### `game/` 域文档两处措辞订正欠账（2026-10-21 登记，来源=批次移交，设计面=工程直入）
|
||||
|
||||
**现状**：两处 `game/` 内文本与现实不符，改 `game/` 任何路径都会触发代码域全量测试（2026-10-20 用户裁「零代码批不改该行、登记欠账」），故不入本写入批：①`game/tests/static_scan.sh:100` S11 注释仍称「完美排雷」不在退役词对照表里——2026-10-21 起该词已入表（术语表退役词对照行在册），注释与 `:122` 追加行按「S11 权威=术语表解析」口径可一并订正；②`game/tests/README.md:58` 记「manifest 已登记实跑 26 套件」——迭代 32 卡② 后现况为 35 套件（含 counter_prefix_fatal 负面套件），以 `run_all.gd` 现况为准更新。
|
||||
**现状**：两处 `game/` 内文本与现实不符，改 `game/` 任何路径都会触发代码域全量测试（2026-10-20 用户裁「零代码批不改该行、登记欠账」），故不入本写入批：①`game/tests/static_scan.sh:100` S11 注释仍称「完美排雷」不在退役词对照表里——2026-10-21 起该词已入表（术语表退役词对照行在册），注释与 `:122` 追加行按「S11 权威=术语表解析」口径可一并订正；②`game/tests/README.md:58` 记「manifest 已登记实跑 26 套件」——迭代 32 卡② 后现况为 35 套件（含 counter_prefix_fatal 负面套件），以 `run_all.gd` 现况为准更新。同文件另两处 `design/qa/` 死指已另有在册条目（本清单「game/tests/README 分级表证据落点行仍指 design/qa/」），本条不重复登记。
|
||||
|
||||
**归属**：`game/tests/`（代码域，随下一个触碰 game/ 的批次顺带清）
|
||||
|
||||
@@ -721,6 +721,16 @@
|
||||
|
||||
---
|
||||
|
||||
#### 引用可核闸注册与建档欠账（2026-10-21 登记，来源=会话提及，设计面=工程直入）
|
||||
|
||||
**现状**：新机检件 `tools/doc_ref_audit.py`（文档内「文件:行号」指针的存在性与行界核对，件头注即判据）已于 2026-10-21 交付并双向验证——注入不存在路径 EXIT=1、注入超界行号 EXIT=1、扫描面为空自判 FAIL、还原 EXIT=0（当日实测：63 件文档／81 处引用／红项 0／建议 6）。它**尚未注册进 `tools/run_all_gates.sh` 文档域**，原因＝注册要把绿记录写进 `game/tests/.gates/baseline.json`（先例见 8f66ae15 之 08c 与 e8b6751b 之 06b），而改 `game/` 下任何路径都要求代码域回执、即跑全量游戏测试，文档域批按测试两入口铁规零跑（2026-10-20 用户裁「不为边际正确性付跑测成本」）。同批附带交付：`tools/doc_term_audit.py` 扫描面已扩到四份根文件（待办清单／体验验证清单／roadmap／AGENTS），扩面实测「疑似现行」0 处、变异注入见红 EXIT=1 还原 EXIT=0。内容锚核对（`--anchors`）实测 81 处引用出 58 条未命中，噪声约七成，按建议级交付不判红，待真实批次积累后再定是否收紧。
|
||||
|
||||
**归属**：`tools/run_all_gates.sh` 注册行＋`game/tests/.gates/baseline.json` 建档（代码域批次顺带）
|
||||
|
||||
**状态**：待写卡
|
||||
|
||||
---
|
||||
|
||||
#### 迭代 32 移交项一——奇物门票三处玩家文案待定性后传导（2026-10-21 登记，来源=批次移交，设计面=文档轨）
|
||||
|
||||
**现状**：「门票（专长门票）→专长凭证」已在 [术语表](design/gdd/术语表.md) 「退役词对照」在册；迭代 32 卡① 清了 `game/` 注释面的 36 处，但下列三处是**数据值与玩家可见文案**、属 奇物／专长 归类表述，需文档侧先定性才动，故本批只移交不改：①`game/data/tables/shop.tres:86` `"display_name": "奇物门票"`；②③`game/presentation/curio_interact_controller.gd:165`／`:166` 交互文案「奇物门票／选定即开一次奇物三选一」。代码闸拦不到它们——S11 只取注释面（.gd 取 # 后、.tres 取 ; 后），数据值与 UI 文案不在其扫描语义内。关联文档：[奇物](design/gdd/systems/冒险循环/奇物.md)（归类口径 owner，现行版本以文首状态行为准）。用户 2026-10-21 裁＝与本清单「2026-10-18 冒记案遗留待裁两项」第②项（资源成员判据句）同源，待该项裁决后走传导批。
|
||||
@@ -742,3 +752,6 @@
|
||||
**归属**：design/gdd/ 各件（机制表述面）＋ design/gdd/术语表.md（口径与除外注）
|
||||
|
||||
**状态**：待文档设计
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user