47-PTN Template v1.0 | 第8章 交叉引用与依赖管理

目录 ／ 文档-技术白皮书 ／ 47-PTN Template v1.0

第8章 交叉引用与依赖管理

I. 依赖图（Dependency Graph）

1. 分层结构：
   • Core 层：Core.Terms v1.0，Core.Equations v1.1，Core.Parameters v1.0，Core.Metrology v1.0，Core.Errors v1.0，Core.DataSpec v1.0。
   • Methods/Metrology 层：Methods.* v1.0（Repro/SimStack/Inference/Falsification/Cleaning/Imaging/CrossStats/SynthData），Metrology.* v1.0（TimeBase/Sync/Instrument/PathCorrection）。
   • Data/Engineering 层：Data.* v1.0（DatasetCards/ModelCards/Pipeline/Benchmarks）与各类模板族。
2. 有向无环要求（DAG）：上层严禁回指下层；Core 不依赖 Methods/Data；Methods 可依赖 Core；Data 可依赖 Core/Methods。
3. 关键边集合（示例）：
   • Ch.2 术语 → Core.Terms v1.0:P10-*
   • Ch.3 控制式 → Core.Equations v1.1:S20-*，Core.Metrology v1.0:check_dim
   • Ch.4 预测/证伪 → Methods.Falsification v1.0，Methods.CrossStats v1.0
   • Ch.5 数据契约 → Core.DataSpec v1.0:TARR，Core.Metrology v1.0
   • Ch.6 设计/采样 → Metrology.* v1.0
   • Ch.7 不确定度 → Core.Metrology v1.0，Methods.SimStack v1.0
4. 路径项强制：凡涉及到达时/相位等路径量，必须显式 gamma(ell) 与 d ell，并在数据或元数据记录 delta_form。

II. 引用表（Reference Table，规范口径）

固定写法：见《<卷名> vX.Y》<章节> <锚点>；优先直指 P/S/M/I 锚点；正文内联引用与数据 see[] 二者需一致。

III. Lint 规则（Citation & Dependency Lint）

1. 覆盖率阈值
   • 版本显式率 ver_presence ≥ 1.00（所有引用必须带版本）。
   • 锚点直指率 anchor_coverage ≥ 0.90（≥90% 引用直指 P/S/M/I）。
   • 路径测度显式率 path_measure_presence = 1.00（涉及路径量处 100% 明示 gamma(ell), d ell 且记录 delta_form）。
2. 命名与冲突
   • 禁止裸用 c、T、n；统一为 c_ref、T_fil（或具体量名）、n_eff（或 n）。
   • T_fil（张力）与 T_trans（透射系数）不可混用；n（数密度）与 n_eff（有效折射率）严格区分。
3. 书写与格式
   • 内联符号一律反引号；含除号/积分/复合算符强制加括号。
   • 公式、符号、定义禁用中文；小节标题罗马数字+加粗；项目符号用“- 空格”。
4. 依赖图校验
   • 拒绝环：检测 Core ← Methods 或 Core ← Data 的反向边；检测章内自环。
   • 层级越权：Data 不得定义基础术语或最小方程；Methods 不得覆盖 Core 的量纲口径。
5. 导出一致性
   导出清单必须包含 references[]（卷名+版本+锚点）与 version；清单内引用与正文一致。
6. 评分与门控
   • 通过条件：ver_presence=1.00 ∧ anchor_coverage≥0.90 ∧ path_measure_presence=1.00 ∧ DAG 无环。
   • 失败动作：标注 lint:fail，阻断发布步骤，要求修正项及定位。

IV. 异常处理（Resolution Playbook）

• 缺版本号：回退查证最新稳定线；若无证据不得默认；在正文与 see[] 同步补齐。
• 缺锚点：请求作者细化到 P/S/M/I；如仅能到章，需附“临时引用”标记并在发布前清零。
• 路径/测度缺失：补写 gamma(ell)、d ell 与 delta_form；若确不可得，移除路径型结论或降级为“示意”。
• 冲突名混用：统一替换为规范名；增补“术语对齐表”并锁定在 Ch.2。
• 循环依赖：断开高层对低层的反向指针；将共享内容上移至 Core 或抽象至 Appendix（共享）。
• 跨版本不一致：若正文与导出清单版本不一致，以导出清单为准并回写正文；发布前强制二者一致。
• 外链/别名：正文与数据中禁用外链与别名；仅允许“卷名+版本+锚点”的规范串。

V. 机读规则与样例（可直接落库）

A. references.yml（注册表）

version: "1.0.0"

refs:

core_terms_p10_3: "EFT.WP.Core.Terms v1.0:P10-3"

core_eq_s20_1: "EFT.WP.Core.Equations v1.1:S20-1"

core_met_checkdim: "EFT.WP.Core.Metrology v1.0:check_dim"

core_dataspec_tarr: "EFT.WP.Core.DataSpec v1.0:TARR"

methods_fals_plan: "EFT.WP.Methods.Falsification v1.0:PLAN"

methods_crossstats: "EFT.WP.Methods.CrossStats v1.0:KPI"

met_sync_pps: "EFT.WP.Metrology.Sync v1.0:PPS"

B. lint_config.yaml（规则与阈值）

version: "1.0.0"

rules:

version_presence: 1.00

anchor_coverage: 0.90

path_measure_presence: 1.00

forbid_raw_symbols: ["c","T","n"]

conflict_pairs:

- ["T_fil","T_trans"]

- ["n","n_eff"]

dag_enforce: true

forbid_external_links: true

inline_code_backticks: true

outputs:

report: "reports/citation_lint.json"

gate: "G2"

C. citation_lint.json（报告格式）

{
  "ver_presence": 1.0,
  "anchor_coverage": 0.93,
  "path_measure_presence": 1.0,
  "dag_ok": true,
  "violations": [
    {
      "type": "FORBID_RAW_SYMBOL",
      "where": "Ch.3 §IV",
      "detail": "found raw 'n' → use 'n_eff' or 'n' with unit"
    }
  ],
  "actions": [ { "fix": "replace_raw_symbol", "targets": [ "n→n_eff" ], "status": "pending" } ]
}

D. 文内与数据双端一致性示例

• 文内：见《EFT.WP.Core.Equations v1.1》Ch.2 S20-1。
• 数据 see[]：["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim","EFT.WP.Core.DataSpec v1.0:TARR"]。
• 导出 manifest.yaml 含：references[] 与 version，与正文一致。

VI. 例行检查（发布前清单）

• 全文引用均为“卷名+版本+锚点”，无别名/外链。
• anchor_coverage ≥ 90%；剩余≤10% 为暂存引用并已列入修复工单。
• 所有路径型表达均显式 gamma(ell) 与 d ell，并在元数据记录 delta_form。
• 依赖图无环，层级不越权。
• 导出包包含 references[] 与 version，与正文一致。
• 冲突名未混用；禁止裸用 c、T、n。

VII. 异常样例（规范化前后对照）

• 错误：见《Core.Equations:S20-1》（缺版本）。
  修正：见《EFT.WP.Core.Equations v1.1》Ch.2 S20-1。
• 错误：T_arr = ∫ n_eff / c_ref d ell（缺括号与路径/测度声明）。
  修正：T_arr = ( ∫ ( n_eff / c_ref ) d ell )；正文显式 gamma(ell) 与 d ell，元数据补 delta_form。
• 错误：参见 Methods.Falsification（缺锚点）。
  修正：见《EFT.WP.Methods.Falsification v1.0》Ch.* PLAN。

VIII. 发布门（与质量门 G2 对齐）

• 触发条件：ver_presence < 1、anchor_coverage < 0.90、path_measure_presence < 1、或 dag_ok = false。
• 处置：阻断 release，输出 citation_lint.json 与差异补丁；修正后自动重试。