54-复现实验清单 Template v1.0 | 第7章 脚本与命令（Runbook/Makefile/reproduce.sh）

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

第7章 脚本与命令（Runbook/Makefile/reproduce.sh）

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

• 交付一键复现入口与标准命令集：Runbook、Makefile、reproduce.sh，覆盖环境拉起、数据快照校核、训练/推理、评测与比对、UQ 与报表打包，保证幂等可重放、日志可审计、产物可核验。
• 凡涉及路径量（到达时/相位），正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；所有表达括号化；发布要求 p_dim = 1.0 并随附 check_dim_report.json。

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

• 依赖：第3章目录布局与制品、第4章环境锁定、第5章数据快照与血缘、第6章权重参数与新鲜度。
• 引用统一“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%；对外仅 v1.*。

III. Runbook（执行手册纲要）

• 阶段：preflight → data_verify → train → infer → eval → compare → pack。
• 幂等键：每阶段接受 --idempotency_key；重复执行不得改变产物 sha256。
• 失败与回退：任一阶段触发 S1–S5 退出并记录 audit.jsonl，必要时标注 [Restricted]。

RUNBOOK.md（提纲）

# RUNBOOK

- Preflight: env_lock / container_spec / seed_policy 校验

- Data Verify: data_refs / split_manifest / lineage / checksums

- Train: train_config 锁定；产出 best.ckpt / last.ckpt

- Infer: binding_spec / inference_openapi / inference.proto

- Eval & UQ: bench_plan / scorecard / model_uq / uq_summary

- Compare & Pack: compare_spec / validate_report / report_manifest

IV. Makefile（标准目标）

SHELL := /bin/bash

IDK ?= run$$(date +%Y%m%d%H%M%S)

.PHONY: all preflight data_verify train infer eval compare pack clean

all: preflight data_verify train infer eval compare pack

preflight:

python tools/preflight.py --env env_lock.json --container container_spec.yaml \

--seed seed_policy.yaml --out reports/preflight_report.json

data_verify:

python tools/verify_data.py --refs data/data_refs.yaml --splits data/split_manifest.json \

--lineage data/lineage_graph.json --checksums checksums.txt --out reports/data_verify.json

train:

python tools/train.py --config model/train_config.yaml --idempotency_key $(IDK) \

--out weights/best.ckpt --log reports/train.log

infer:

python tools/infer.py --binding inference/binding_spec.md --weights weights/best.ckpt \

--idempotency_key $(IDK) --out outputs/preds.json

eval:

python tools/eval.py --bench eval/bench_plan.yaml --pred outputs/preds.json \

--out eval/scorecard.json --uq uq/uq_summary.json

compare:

python tools/compare.py --spec eval/compare_spec.yaml --score eval/scorecard.json \

--validate reports/validate_report.json

pack:

python tools/pack.py --root PTN_EXPORT --manifest report_manifest.yaml --sign SIGNATURE.asc

clean:

rm -rf outputs/* tmp/*

V. reproduce.sh（一键复现脚本）

#!/usr/bin/env bash

set -euo pipefail

STAGE="${1:-all}"

IDK="${IDK:-run$(date +%Y%m%d%H%M%S)}"

log(){ echo "[$(date -Iseconds)] $*"; }

case "$STAGE" in

preflight)

log "Preflight..."

python tools/preflight.py --env env_lock.json --container container_spec.yaml \

--seed seed_policy.yaml --out reports/preflight_report.json

;;

data_verify)

log "Verify data..."

python tools/verify_data.py --refs data/data_refs.yaml --splits data/split_manifest.json \

--lineage data/lineage_graph.json --checksums checksums.txt --out reports/data_verify.json

;;

train)

log "Train..."

python tools/train.py --config model/train_config.yaml --idempotency_key "$IDK" \

--out weights/best.ckpt --log reports/train.log

;;

infer)

log "Infer..."

python tools/infer.py --binding inference/binding_spec.md --weights weights/best.ckpt \

--idempotency_key "$IDK" --out outputs/preds.json

;;

eval)

log "Eval..."

python tools/eval.py --bench eval/bench_plan.yaml --pred outputs/preds.json \

--out eval/scorecard.json --uq uq/uq_summary.json

;;

compare)

log "Compare & validate..."

python tools/compare.py --spec eval/compare_spec.yaml --score eval/scorecard.json \

--validate reports/validate_report.json

;;

pack)

log "Pack..."

python tools/pack.py --root PTN_EXPORT --manifest report_manifest.yaml --sign SIGNATURE.asc

;;

all)

"$0" preflight && "$0" data_verify && "$0" train && "$0" infer && "$0" eval && "$0" compare && "$0" pack

;;

*)

echo "Usage: $0 {preflight|data_verify|train|infer|eval|compare|pack|all}"

exit 2

;;

esac

# 审计事件

python tools/audit.py --event "$STAGE" --idk "$IDK" --out reports/audit.jsonl

VI. 路径对齐与度量（Path Alignment & Metrics）

• 评测与告警前按“时间→路径→相位”顺序对齐；路径数组满足 len(gamma_ell)=len(d_ell)=len(n_eff)≥2。
• 统一口径（两式等价）：
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
  T_arr = ( ∫ ( n_eff / c_ref ) d ell )
  相位：Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。
• reproduce.sh 的 infer/eval/compare 阶段必须将 delta_form 回显至产物元数据；p_dim = 1.0。

VII. 日志与审计（Logging & Audit）

• 每阶段输出 stdout/stderr 到 reports/*.log，并将关键元信息写入 audit.jsonl：时间戳、idempotency_key、输入/产物 sha256、版本与签名。
• 失败时写入 reason 与建议修复；必要时在图表与清单中标注 [Restricted]。

VIII. 质量门映射（Gate Mapping）

• G1 Schema 完整：脚本与入口参数与清单一致；
• G2 引用合规：命令帮助与 RUNBOOK.md 锚点直指率 ≥ 90%；
• G3 路径规范：gamma/measure/delta_form 必填并校验步长；
• G4 量纲闭合：check_dim_report.json 通过，p_dim = 1.0；
• G5 新鲜度：clock_state="locked"、τ_calib 合规；
• G6 覆盖一致：coverage.mode ∈ {k, alpha, quantile} 贯通数据/模型/误差/管线/本卷；
• G7 协方差一致：Σ PD；
• G8 唯一性与无环：产物 sha256 唯一、lineage 无环。
• 触发 S1–S5 即停止与回退，并输出诊断。

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

• 反例：T_arr = ∫ n_eff / c_ref d ell（无括号） → 修正：改为括号化统一口径。
• 反例：脚本未回显 delta_form 或路径数组不同长 → 修正：在对齐环节补齐并强制一致。
• 反例：无 idempotency_key 导致产物不一致 → 修正：强制 --idempotency_key 并校验冲突。
• 反例：Compare 仅比均值不比区间 → 修正：比对 U=k·u_c 或分位带并提供收敛诊断。

X. 机读制品（Machine-Readable Artifacts）

XI. 交叉引用（Cross-References）

• 第3章（目录与制品）、第4章（环境锁定）、第5章（数据快照）、第6章（权重参数）、第9章（指标与门）、第10章（复现实验流程）。
• 《模型卡》Ch.6/Ch.10/Ch.12；《数据集卡》Ch.10；《误差预算卡》Ch.8/Ch.9；《管线卡》Ch.7/Ch.12。

XII. 勾选清单（Checklist）

• RUNBOOK.md / Makefile / reproduce.sh 已入库并与 report_manifest.yaml 对齐。
• 每阶段要求 --idempotency_key，并在 audit.jsonl 记录输入/产物 sha256。
• 路径对齐显式 gamma/measure/delta_form；len(path) ≥ 2、Δell 合规；p_dim = 1.0。
• 评测比对含点估计与区间（k/alpha/quantile），并输出收敛诊断。
• /validate 通过 G1–G8；不合规项按 [Restricted] 标注与处置；锚点直指率 ≥ 90%。