48-实验协议卡 Template v1.0 | 第12章 附录（表单/清单/模板）

目录 ／ 文档-技术白皮书 ／ 48-实验协议卡 Template v1.0

第12章 附录（表单/清单/模板）

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

• 汇集本协议卡执行所需的表单、清单、机读模板与导出骨架；默认与第3–11章口径一致，引用采用“卷名 + 版本 + 锚点（P/S/M/I）”。
• 涉及到达时/相位等路径量时，正文显式 gamma(ell) 与测度 d ell，并在数据/元数据记录 delta_form ∈ {general, factored}。

II. 附录清单（索引）
A. 协议卡 protocol.yaml
B. 发布清单 manifest.yaml
C. 处理管线 pipeline.yaml
D. 数据架构 schema.json（节选）
E. 误差预算卡 error_budget.csv（表头）
F. 质量门配置 gates.yaml
G. 回退策略 fallbacks.yaml
H. 引用注册表 references.yml
I. 结果页骨架 results.md（最小版）
J. 评分卡 scorecard.json（节选）
K. 路径数据示意 paths.parquet（表头）
L. 审计轨迹 audit.jsonl（单行示例）
M. 发布目录结构与一页式自检清单

III. 模板与表单（可直接落库）

A. protocol.yaml

version: "1.0.0"

protocol:

id: "ptn-exp-0001"

title: "Baseline PTN Observation"

geometry:

frame: "RA-Dec" # 或 "xyz"

q_att: [0,0,0,1]

r_hat: [<unit_vector>]

FOV_deg: 1.0

occlusion_mask: "masks/occ.png"

path:

gamma_ell: "<array-of-meters>" # 显式路径

d_ell: "<array-of-meters>" # 显式测度

delta_form: "general" # 或 "factored"

timebase:

fs_hz: 2000

t_exp_s: 0.01

cadence_s: 0.05

band:

lambda_ref_m: 1.55e-6

k_ref_inv_m: 4.0536679e6

window: "hann" # rect|hann|blackman

instrument:

id: "INS-001"

mode: "timing" # imaging|spectral|mixed

calibration:

version: "1.2.0"

timestamp: "2025-09-24T10:00:00Z"

freshness_s: 86400

sync:

ref: "GNSS_PPS"

fallback: ["PTP","NTP"]

thresholds: { abs_ns: 50, skew_ns: 5, allan_1s: 1.0e-11 }

gates: ["G1","G2","G3","G4","G5","G6","G7","G8"]

see:

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

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

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

B. manifest.yaml

dataset_id: "ptn-demo"

version: "1.0.0"

created_at: "2025-09-24T16:00:00Z"

producer: "PTN.Workgroup.Core"

see:

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

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

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

references:

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

checksum: { algo: "sha256", value: "<64-hex>" }

release_tier: "public"

C. pipeline.yaml

version: "1.0.0"

pipeline:

- id: step-10-ingest

in: ["raw/*.parquet"]

out: ["stage/ingested.parquet"]

checks: ["G1","G8"]

- id: step-20-calibrate

in: ["stage/ingested.parquet"]

out: ["stage/calibrated.parquet"]

checks: ["G5"]

- id: step-30-arrival

in: ["stage/calibrated.parquet"]

out: ["stage/arrival.parquet"]

compute:

form: "T_arr = ( ∫ ( n_eff / c_ref ) d ell )"

requires: ["path.gamma_ell","path.d_ell","medium.n_eff_profile","ref.c_ref"]

delta_form: "general"

checks: ["G3","G4"]

- id: step-40-noisefit

in: ["stage/arrival.parquet"]

out: ["stage/denoised.parquet","reports/noise.json"]

model: "huber"

checks: ["G6"]

- id: step-50-export

in: ["stage/denoised.parquet"]

out: ["PTN_EXPORT/"]

checks: ["G2","G4","G7","G8"]

exports:

must_include: ["manifest.yaml","schema.json","check_dim_report.json","quality_report.json","audit.jsonl"]

D. schema.json（节选）

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PTN Data Object v1.0.0",
  "type": "object",
  "required": [ "record_id", "acq", "path", "medium", "ref", "obs", "version", "see", "references" ],
  "properties": {
    "record_id": { "type": "string" },
    "acq": {
      "type": "object",
      "required": [ "ts_start", "ts_end" ],
      "properties": {
        "ts_start": { "type": "string", "format": "date-time" },
        "ts_end": { "type": "string", "format": "date-time" }
      }
    },
    "path": {
      "type": "object",
      "required": [ "gamma_ell", "d_ell" ],
      "properties": {
        "gamma_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 },
        "d_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 }
      }
    },
    "medium": {
      "type": "object",
      "required": [ "n_eff_profile" ],
      "properties": { "n_eff_profile": { "type": "array", "items": { "type": "number" }, "minItems": 2 } }
    },
    "ref": {
      "type": "object",
      "required": [ "c_ref" ],
      "properties": { "c_ref": { "type": "number", "minimum": 290000000.0, "maximum": 310000000.0 } }
    },
    "obs": {
      "type": "object",
      "properties": { "T_arr": { "type": "number" }, "Phi": { "type": "number" } }
    },
    "see": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    "references": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    "version": { "type": "string" }
  }
}

E. error_budget.csv（表头）

source,symbol,unit,type,estimate,distribution,correlation,note,see[]

Absolute timing,δt_abs,s,A,u(δt_abs),approx-N,vs_channel_skew,,Core.Metrology v1.0

Path measure,d ell,m,B,u(d ell),uniform,with gamma(ell),,Core.DataSpec v1.0:TARR

Medium index,n_eff(ell),1,A/B,u(n_eff),GP(L_c),length L_c,,Core.Terms v1.0

F. gates.yaml

version: "1.0.0"

gates:

G1: { schema: true }

G2: { cite_anchor_min: 0.90, forbid_external_links: true }

G3: { path_min_len: 2, require_sync: true }

G4: { p_dim: 1.0, units: { T_arr: "s", Phi: "rad" } }

G5: { tau_calib_s_max: 86400 }

G6: { Q_res_band: [0.0, 0.2], robust_surrogate: true }

G7: { epsilon_flux_guard: "≈0@O(theta^2)" }

G8: { unique_record_id: true, unique_checksum: true }

G. fallbacks.yaml

version: "1.0.0"

triggers:

SYNC: ["clock_unlocked","abs_t_over","skew_over","allan_over"]

DIM: ["p_dim_fail","check_dim_fail"]

SMP: ["fs_below_nyquist","Delta_ell_over","path_len_short","path_desync"]

PAX: ["theta_over","coherence_fail"]

NOISE: ["Q_res_over","flux_nonconserve"]

CALIB: ["tau_calib_expired","u_theta_over"]

CITE: ["ver_missing","anchor_coverage_low","external_link_found"]

INTG: ["record_dup","checksum_dup","audit_missing"]

actions:

sync_fallback: ["GNSS","PTP","NTP"]

switch_fullwave: true

segment_adapt: { T_coh: "shrink", L_coh: "shrink", B_coh: "increase" }

robust_substitute: ["huber","quantile"]

recalibrate: true

labels:

restricted: "[Restricted]"

H. 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"

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

methods_bench: "Data.Benchmarks v1.0:PROTO"

I. results.md（最小版）

# PTN Results — v1.0.0

## 1. Summary

- One-liner; core metrics with intervals (ΔT_arr, r_phi, ε_flux, p_dim, Q_res).

## 2. Identifiers

- dataset_id / method_id / baseline_id / versions / seeds / time window.

## 3. Core Metrics

- ΔT_arr (s): mean ± U(k), histogram/KDE, BA plot.

- r_phi (1): value + 95% CI; phase scatter vs identity.

- ε_flux (1): distribution; paraxial guard lines.

- p_dim (1), Q_res (1).

## 4. Compliance

- check_dim_report.json summary; anchor_coverage / ver_presence; clock_state / τ_calib.

## 5. Figures

- PDF/PNG list with units & legends.

J. scorecard.json（节选）

{

"version": "1.0.0",

"dataset_id": "ptn-demo",

"baseline": { "id": "base-001", "version": "1.2.3" },

"method": { "id": "mA-010", "version": "2.0.0" },

"metrics": {

"DeltaT_arr_s": { "mean": -2.3e-9, "std": 4.8e-9, "U_k2": 1.5e-9 },

"r_phi": { "value": 0.72, "ci95": [0.61, 0.80] },

"epsilon_flux": { "median": 0.004, "p95": 0.011 },

"p_dim": 1.0,

"Q_res": 0.13

},

"score": { "Q": 0.78 },

"tests": {

"paired": { "DeltaT_arr": { "p_perm": 0.004, "B": 10000 } },

"FDR": 0.08

},

"see": [

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

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

"Data.Benchmarks v1.0:PROTO"

],

"version_lock": true

}

K. paths.parquet（表头示例）

record_id,gamma_ell[],d_ell[],n_eff[],unit_gamma,unit_dell,unit_n,delta_form

01H..., [..], [..], [..], m, m, 1, general

L. audit.jsonl（单行示例）

{
  "run_id": "01JXYZABCD...",
  "started_at": "2025-09-24T16:10:00Z",
  "tools": [ { "name": "ptn-cli", "version": "1.4.2" } ],
  "random_seeds": [ 20250924 ],
  "input_hashes": [ "sha256:..." ],
  "events": [ { "ts": "...", "clock_state": "locked", "delta_t_abs_ns": 23, "allan_1s": 1.2e-11 } ],
  "references": [ "EFT.WP.Core.Equations v1.1:S20-1" ],
  "version": "1.0.0"
}

IV. 发布目录结构（建议）

PTN_EXPORT/

manifest.yaml

data/

observations.parquet

paths.parquet

schema/

schema.json

reports/

check_dim_report.json

quality_report.json

audit.jsonl

figs/

*.pdf

*.png

scorecard.json

results.md

SIGNATURE.asc

V. 一页式自检清单（Publish Checklist）

• 文内与数据 see[]/references[] 采用“卷名+版本+锚点”，锚点直指率 ≥ 90%，无外链/别名。
• 路径型表达显式 gamma(ell) 与 d ell；delta_form 已记录；len(path) ≥ 2。
• p_dim = 1.0，clock_state=locked，|ts_start − calib.timestamp| ≤ τ_calib。
• 采样满足 f_s ≥ 2 f_max，Δell ≤ ( c_ref / f_s ) / max(n_eff)；相位采样 Δt ≤ λ_ref / (2 c_ref)。
• 发布包齐备：manifest/schema/data/reports/figs/scorecard/results.md，checksum 唯一且签名完成。
• 禁止裸用 c、T、n；不混用 T_fil/T_trans 与 n/n_eff；轴单位与量纲在图注中显式。
• 若处于 [Restricted]，所有图表已追加标签并列出触发项，仅发布定性结论与诊断图。

VI. 引用与版本（Citations & Versioning）

• 固定写法：见《<卷名> vX.Y》<章节> <锚点>；优先 P/S/M/I；正文与导出一致。
• 规范锚点示例：EFT.WP.Core.Equations v1.1:S20-1/S21-2、EFT.WP.Core.Metrology v1.0:check_dim、EFT.WP.Core.DataSpec v1.0:TARR、Data.Benchmarks v1.0:PROTO。
• 对外仅 v1.*；如需 v0.*，显著标注“草案/非承诺”。