54-复现实验清单 Template v1.0 | 第3章 清单结构与制品（Artifacts Layout）

目录 ／ 文档-技术白皮书（V5.05） ／ 54-复现实验清单 Template v1.0

第3章 清单结构与制品（Artifacts Layout）

I. 目标与范围（Purpose & Scope）

• 定义 PTN_EXPORT/ 根目录下复现实验最小可复现包（MRB）的目录结构、强制/可选制品、校验与签名要求，确保任意环境下一键复现、等价比对、可审计发布。
• 凡涉及路径量（到达时/相位），正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；所有表达括号化，发布要求 p_dim = 1.0 并随附 check_dim_report.json。

II. 输入与依赖（Inputs & Dependencies）

• 依赖《数据集卡》Ch.3/Ch.4/Ch.6/Ch.7/Ch.10、《模型卡》Ch.4/Ch.6/Ch.7/Ch.10/Ch.11/Ch.12、《误差预算卡》Ch.5/Ch.6/Ch.8/Ch.9、《管线卡》Ch.12、《参数注册卡》Ch.4/Ch.6/Ch.8/Ch.9。
• 引用统一以“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%。

III. 目录结构（Directory Layout）

PTN_EXPORT/

model/ # 模型清单与配置

model_manifest.yaml

compat_matrix.yaml

control_spec.yaml

train_config.yaml

hpo_space.yaml

inference/ # 部署接口与绑定

inference_openapi.yaml

inference.proto

binding_spec.md

uq/ # UQ 与误差预算

model_uq.yaml

uq_summary.json

budget_breakdown.csv

eval/ # 评测与评分

bench_plan.yaml

scorecard.json

eval_report.md

monitoring/ # 监控与回退

monitoring_rules.yaml

rollback_fsm.yaml

alerts.jsonl

reports/ # 校核与审计

check_dim_report.json

validate_report.json

audit.jsonl

data/ # 数据快照（可选：或由 Dataset 包引用）

data_refs.yaml

split_manifest.json

figs/ # 图表（双份导出）

model_arch.svg

path_profile.pdf

latency_hist.pdf

throughput_series.svg

report_manifest.yaml # 发布清单（本章强制）

SIGNATURE.asc # 签名（本章强制）

checksums.txt # 全量 sha256（本章强制）

IV. 制品分层（Artifacts by Tier）

• 强制（Must）：report_manifest.yaml、SIGNATURE.asc、checksums.txt、check_dim_report.json、validate_report.json、model_manifest.yaml、control_spec.yaml、bench_plan.yaml、scorecard.json、model_uq.yaml、uq_summary.json、monitoring_rules.yaml、rollback_fsm.yaml、audit.jsonl、图表双份导出（PDF/SVG 与 PNG/JPG）。
• 条件（Conditional）：data_refs.yaml、split_manifest.json（若不直接依赖外部 Dataset 包）；hpo_space.yaml（开展 HPO 时）。
• 可选（Optional）：repro_notes.md、perf_summary.md、env_lock.json、container_spec.yaml（若本清单同时承担环境锁定）。

V. 清单与校验（Manifest & Verification）
A. report_manifest.yaml（模板）

version: "1.0.0"

bundle:

model: ["model/model_manifest.yaml","model/compat_matrix.yaml","model/control_spec.yaml","model/train_config.yaml"]

inference: ["inference/inference_openapi.yaml","inference/inference.proto","inference/binding_spec.md"]

uq: ["uq/model_uq.yaml","uq/uq_summary.json","uq/budget_breakdown.csv"]

eval: ["eval/bench_plan.yaml","eval/scorecard.json","eval/eval_report.md"]

monitoring: ["monitoring/monitoring_rules.yaml","monitoring/rollback_fsm.yaml","monitoring/alerts.jsonl"]

reports: ["reports/check_dim_report.json","reports/validate_report.json","reports/audit.jsonl"]

figs: ["figs/model_arch.svg","figs/path_profile.pdf","figs/latency_hist.pdf","figs/throughput_series.svg"]

checksums: "checksums.txt"

sign: "SIGNATURE.asc"

see:

- "Dataset Card v1.0:Ch.4"

- "Model Card v1.0:Ch.4"

- "Error Budget Card v1.0:Ch.8"

B. checksums.txt

sha256 model/model_manifest.yaml <64-hex>

sha256 reports/check_dim_report.json <64-hex>

...

VI. 单位/量纲与路径口径（Units/Dimensions & Path Forms）

• 所有数据字段与计算表达式必须注明单位与量纲，发布前运行 I70-dim_check，要求 p_dim = 1.0。
• 到达时（两式等价）：
  T_arr = ( 1 / c_ref ) * ( ( ∫ n_eff d ell ) )
  T_arr = ( ( ∫ ( n_eff / c_ref ) d ell ) )
• 相位累计：
  Phi = ( ( 2π / λ_ref ) * ( ∫ n_eff d ell ) )

目录中 control_spec.yaml 与 path_profile.pdf 应与上述口径一致；数据侧记录 delta_form；数组 len(gamma_ell)=len(d_ell)=len(n_eff)≥2。

VII. 质量门映射（Gates Mapping）

• G1 Schema 完整：目录与强制制品齐备；
• G2 引用合规：report_manifest.yaml 的 see[]/version 锚点直指率 ≥ 90%；
• G3 路径规范：gamma/measure/delta_form 在 control_spec.yaml 与数据制品中齐备；
• G4 量纲闭合：check_dim_report.json 通过、p_dim = 1.0；
• G5 新鲜度：若包含数据/参数快照，须满足 freshness.policy；
• G6 覆盖一致：coverage.mode ∈ {k, alpha, quantile} 在各制品一致；
• G7 协方差一致：Σ PD，并与误差预算配置匹配；
• G8 唯一性与无环：checksums.txt 无重复条目，引用 lineage 无环。
• 触发 S1–S5（量纲/新鲜度/路径/协方差/引用）即拒绝验收或标注 [Restricted]。

VIII. 反例与修正（Anti-Patterns & Fixes）

• 反例：T_arr = ∫ n_eff / c_ref d ell（无括号） → 修正：改为括号化统一口径。
• 反例：report_manifest.yaml 缺 checksums/sign → 修正：补充并校验。
• 反例：图表未标单位/覆盖口径 → 修正：在图注补齐单位与 coverage.mode。
• 反例：路径制品无 delta_form 或数组不同长 → 修正：补齐 delta_form 并保证 len(gamma_ell)=len(d_ell)=len(n_eff)。
• 反例：跨卷口径不一致（如 k 与 quantile 混用） → 修正：统一 coverage.mode 并在清单中声明。

IX. 交叉引用（Cross-References）

• 《数据集卡》Ch.4（Schema/单位/量纲）、Ch.6（Splits/Versioning）；
• 《模型卡》Ch.4（控制式）、Ch.6/Ch.7/Ch.8/Ch.10/Ch.11/Ch.12；
• 《误差预算卡》Ch.5/Ch.6/Ch.8/Ch.9；
• 《管线卡》Ch.12（产出与发布）；
• 《参数注册卡》Ch.4/Ch.6/Ch.8/Ch.9。

X. 勾选清单（Checklist）

• 目录结构与清单与本章一致；report_manifest.yaml / SIGNATURE.asc / checksums.txt 齐备。
• 所有强制制品存在且 sha256 校验通过；引用锚点直指率 ≥ 90%。
• 路径制品显式 gamma/measure/delta_form；数组同长、步长与对齐合规；p_dim = 1.0。
• coverage.mode 在 UQ/评测/部署/监控制品中一致；Σ PD。
• 图表双份导出且标注单位、see[]/version 与覆盖说明；不合规项标注 [Restricted] 并给出修正路径。