guanlan-src/docs/振动六层链_接口规格与缺口_v0.1.md

振动六层链 —— 接口规格与缺口（v0.1，2026-09-17）

用途：用户令 2026-09-17 #2「无生成端的那批，能否根据旧包产物通过逆向工程推导实现？」的实测答复。 结论一句话：接口已经写在包里的"壳"上，实现缺失；而"能否对拍验证"这件事，缺的正是标准答案 —— 六层链最关键的两件产物（model_run_l6.parquet、fusion_38.csv）从未随过包，无从逐值对拍。 因此本轮没有凭猜测写实现（本项目的硬规矩：允许响亮降级，不许造数）。

---

1. 壳在包内：四步怎么调、传什么，代码里已经写死了

src/windcms/pipeline.py::analyze() 就是那条链的编排（scripts/windcms.py analyze 是它的命令行入口）：

步骤名	实际执行的脚本	参数	环境变量
ingest	scripts/rudong_tcm_index.py + scripts/rudong_tcm_spectra.py	--root <导出> --out <窗>/index.parquet / --out <窗>/spectra	—
oem_scan	scripts/rudong_tcm_oem_scan.py（缺）	无	M5_WINDOWS（逗号分隔窗清单）、SCAN_BANDS
energy_share	scripts/rudong_line_energy_share.py（缺）	无	同上
model_run	scripts/rudong_model_run.py（缺）	无	同上
fusion	scripts/rudong_fusion_run.py（缺）	无	同上
report	scripts/windcms.py report --farm <场>	—	—
kb	scripts/windcms.py kb --farm <场>	—	—

实测证据（2026-09-17）：

$ python scripts/windcms.py analyze --window w0316 --steps model_run
[model_run] rc=2 0.1s
python.exe: can't open file '…\scripts\rudong_model_run.py': [Errno 2] No such file or directory

⇒ 缺的是实现，不是接口。每步该调谁、该吃哪个环境变量，壳里一条不落。

2. 产物契约（src/windcms/config.py 里写明的路径）

'fusion'        : outputs/<场>/m5_cms_tcm/fusion_38.csv          ← 缺（从未随包）
'model_l6'      : outputs/<场>/m5_cms_tcm/model_run_l6.parquet  ← 缺（从未随包）
'model_summary' : outputs/<场>/m5_cms_tcm/model_run_summary.json ← 在（随包件，已按人工件归类）
'fleet_z'       : outputs/<场>/m5_cms_tcm/fleet_scalar_z.parquet ← 在（随包件）
'baseline'      : outputs/<场>/m5_cms_tcm/baseline_38.json       ← 在（随包件，含人工坐实的两层基线）

3. 为什么"逆向工程 + 逐值对拍"这条路在这四步上走不通

逐值对拍的前提是有标准答案。四步里：

步骤	产物	盘上有没有样件	能否对拍
oem_scan	oem_frequency_scan.parquet、bearing_freq_scan.parquet、gear_freq_scan.parquet、cage_slip_scan.parquet、blade_1p_*.{parquet,csv} 等	在（约 23 件测量形态件）	有样件 ⇒ 可以对拍，但口径（扫哪些频带、窗如何合并、阈值）得先反推
energy_share	未见同名产物	未识别	无样件 ⇒ 不可对拍
model_run	model_run_l6.parquet（+摘要 json）	缺	无标准答案 ⇒ 只能凭口径实现，无法证明"复现"
fusion	fusion_38.csv（+ handoff_vibration_v2.json）	fusion_38.csv 缺；handoff_vibration_v2.json 在，但它是人工交证件（见 §4）	同上 ⇒ 不可对拍

4. handoff_vibration_v2.json 不是"算出来的产物"，而是人工交证件

实测其结构：meta（version/date/from/to/supersedes/principle/v2.1_changes/v2.2_changes/ ★消费端接线约定/★派生件同步纪律）、detectability_prior、cross_source_requests、baseline_三层、 per_turbine（v1_generator / v1_gearbox 的人工裁决 + claim_window）、field_actions_v1、 calibration_updates_v1、open_items、tcm16_schedule。

⇒ 它由振动线人写交给 windscada 线，正文里就是判断、承诺与待办。逆向工程对它无意义 （"推"出来的只是同义改写）。它已按用户令 2026-09-17 #3 登记进人工件台账 outputs/<场>/_human_artifacts.json（kind=human），不参与呼应校验。

5. 结论与待办（给研发/振动线的最小清单）

1. 四个脚本的源码（rudong_tcm_oem_scan.py / rudong_line_energy_share.py / rudong_model_run.py / rudong_fusion_run.py）。接口已知（§1），放进 scripts/ 即可被壳调用。
2. 两件标准答案：model_run_l6.parquet 与 fusion_38.csv 的任一份历史产出（哪一窗都行）。 有了它，oem_scan 侧那 23 件测量件就能照 temp_monthly 的老办法（反推口径 → 逐值对拍 → 一致才敢用） 转成"✓ 已在重算链上"；没有它，实现出来也无法证明复现，只能当成"另一个算法"。
3. 在那之前，系统按现口径如实呈现：这 36 件（vib_handoff_and_scans 里非人工的那部分）标 ✗ 无生成端， 页面缺件时给结构化说明（不静默、不造数、不从交付包补）。

7. oem_scan 侧：分母已齐、分子缺（2026-09-17 反推）

用户令之后的继续推进。这一族（约 23 件测量形态件）有标准答案（随包件在盘上），所以可以反推； 本轮把"哪些部分已经确定、还缺哪一步"钉成了结论。

7.1 已确定：扫描列是"观测 / 理论"的比值，理论侧（分母）包内齐备

• bearing_freq_scan.parquet 的列 FTF/BSF/BPFO/BPFI/BSF_2x/BPFI_sb/BPFO_sb，按 component 聚合后的中位数 ≈ 1.00–1.07（GEN_bearing 1.0018–1.0382；HS_bearing 的边带/2×BSF 达 1.19–1.20） ⇒ 明确是"观测频率 ÷ 理论特征频率"。偏离 1 的部分正是诊断信息（HS 轴承边带偏得最多）。
• gear_freq_scan.parquet 同理；同一行里 IMS_1x / rotor_1x / ring2_2R / sun1_1S / carrier2 取值相同 —— 因为它们都是同一根轴的 1×，比值自然一致（这也反过来印证了"比值"语义）。
• 分母（理论频率）在包内且是"实机/OEM 参数表"级别： reference/rudong/oem_bearing_freqs.json（29 个轴承条目，键名 BPFI_Hz/BPFO_Hz/BSF_Hz/ORF_Hz/shaft_Hz， 例：2nd Stage Planetary Section#0 → BPFI 23.8 / BPFO 17.0 / BSF 7.5 Hz，型号码 NSK LV220-2/…）； reference/rudong/gear_mesh_map_measured.json（shafts_Hz HSS 25.0 / IMS 7.08 / C2 1.67 / LSS 0.20876； gear_mesh_Hz GMF1 19.219 / GMF2 151.56 / GMF3 750.0；stage_ratios 乘积 119.752 = 铭牌）。

7.2 已确定的运动学口径（含一处文档与实现的差异）

blade_1p_records.parquet 的 f1P（转子 1P 频率）= 发电机转速 ÷ 速比 ÷ 60，而由 662 行样件反解出的 等效速比精确等于 119.75（均值 119.750000、标准差 4.6e-15、逐台恒定），不是机型常量/铭牌上的 119.752。

⇒ 实现时必须用 119.75（若照文档写 119.752，f1P 会整体偏 1.7e-5 相对量 —— 这正是我第一次对拍看到 3.7e-6 绝对偏差的来源）。这条差异只有靠"反解样件"才看得出来，文档里读不到。

7.3 仍然缺的：分子 —— "在谱里怎么取观测峰"

要复现这些列，必须在每个理论频率附近从 FFT 谱里取出"观测频率"。这一步的口径（带宽多大、取什么量最大、 要不要抛物线插值、是否按转速做阶次跟踪、多窗/多记录怎么合并）就是缺的 scripts/rudong_tcm_oem_scan.py 的核心，也是唯一还没确定的部分。

已备好的测试台：880 行 bearing_freq_scan / 880 行 gear_freq_scan / 3681 行 cage_slip_scan （后者还带 bin 功率分箱与 n_rec 记录数，ftf_amp 是幅值）—— 口径一旦给出，逐值对拍可以立刻做。

7.4 对取料单的收窄（这条很实用）

原本向振动线要"整个 rudong_tcm_oem_scan.py"；现在可以只问一句话：

在理论特征频率附近怎么取观测峰？（带宽 ±?%、按幅值还是按能量取最大、是否插值校正、是否按 rpm 阶次跟踪、多记录如何合并）

拿到这句话，配上包内已有的理论表与转速，这一族就能照 temp_monthly / fleet_scalar_z 的老办法 （反推 → 逐值对拍 → 一致才敢用）转成"✓ 已在重算链上"。源码仍是首选（省一轮试错），但不再是唯一路径。

---

6. 逆向工程进展：fleet_scalar_z.parquet 的口径已反推（可对拍）

fusion 步的产物里，只有 fleet_scalar_z.parquet 有标准答案（随包件在盘上），因此先攻它。 新增 scripts/rudong_fusion_run.py（--verify 与样件逐值对拍，不改任何件）。

6.1 反推出来的口径

val       = 窗内 median(scalar_value)，按 (turbine, sensor_name, meas_name, condition_key) 分组
n         = 组内记录数（样件口径：n ≥ 3）
fleet_med = 跨机组 median(val)（同一 sensor/meas/bin 下）
z         = (val - fleet_med) / (1.4826 × MAD(val))     ← 稳健 z 分数

尺度是怎么定下来的（四条候选逐个数对）：std(ddof=0)=1.44859 → z=−0.1725 · MAD=0.80209 → z=−0.3116 · IQR/1.349=1.46899 → z=−0.1701 · 1.4826×MAD=1.18918 → z=−0.2102 ← 与样件 −0.210156 命中。

6.2 逐值对拍结果（样件 8,887 行 · 窗 w0127）

列	一致	比率	说明
val	8887 / 8887	100%	取值链完全复现 ⇒ 分组 + 中位数口径确定无疑
n	8606 / 8887	96.8%	与行集口径的残留差异同源
fleet_med	8359 / 8887	94.1%	基线口径仍未复现
z	8180 / 8887	92.0%	随基线偏差

行数：本器 9,163 行 vs 样件 8,887 行（只多不缺，多 276 行，全部是 n≥3 的低样本组）。

6.3 已确认的三条口径（都是"反推 + 复算验证"得来的，不是猜）

1. 分组：(turbine, sensor_name, meas_name, condition_key)。
2. 每组最少记录数：n ≥ 3（样件 n 分布 min=3；加上这条后行数 31,574 → 9,505）。
3. 量纲闸：y_unit ∈ {1, m/s, m/s²} —— 只留振动量纲的标量（无量纲指标 / 速度 / 加速度）。 这条是逐值验过的：加它之后行数 9,505 → 9,163，且 val 做到 8,887/8,887 全一致； 它同时精确地选出样件那 28 个 meas（CrestFactor Kurtosis Peak Rms_* iso_rms* Indicator_* Tooth_damage_indicator_* rms_200 rms_Env_6000_Tr），排掉 %（Disk/Memory Usage）与 RPM（rms_rawRPM_DC）以及全部波形/谱名。注意：原先按 meas_type / meas_source 找都不成立，y_unit 才是那把钥匙。

6.4 仍未闭合的一件事：样件的行集（不是公式）

本轮把 §6.4 的候选试完了，得到一个决定性的结论：

基线算在哪个行集上	fleet_med 不一致	z 不一致
A1 本器行集（9,163 行，= 量纲闸 + n≥3）	528	707
A2 全量组（不卡 n≥3）	3095	3823
A3 只用样件那批键（8,887 行）	0	68
A4 跨窗合并（w0127+w0316）	8337	8884

⇒ 基线公式已经确认无疑：在正确的行集上算 median(val) + 1.4826×MAD，fleet_med 逐值 100% 一致， z 99.2% 一致（剩 68 处，疑似 MAD≈0/小样本键的兜底规则）。

⇒ 剩下的唯一未知是样件的行集比本器少 276 行（3.1%，全是 n≥3 的低样本组，缺 0 行）。 那 276 行会抬高/压低同一键的 fleet 中位数，于是基线整体偏 5–8% —— A1 与 A3 的差距就来自这里。 试过的行集假设全部过砍（都不成立）：

假设	结果
H1 该机组在该 sensor/meas 下覆盖全部 7 个 bin	9,163 → 966 行（砍掉太多）
H2 覆盖 ≥ 2 个 bin	→ 6,847 行（砍掉太多）
H3 每键取 n 最大的前 K 台（K=20/24/28/34）	→ 6,250 / 7,106 / 7,878 / 8,762 行（K=34 仍多 125 行）
bin 覆盖度阈值（已试 3…20）	9,163 → 8,981（th=5）→ 8,933（th=10）→ 7,463（th=16，开始缺行）

★ 一条自我更正：上一轮我曾用"值不一致 = 0"的说法，那是探测脚本里对拍列名写漏（fleet_med/z 在样件侧没有配对的 _本 列，被 continue 跳过了）造成的假象；以上表格是真数。 留在这里，以免下次又被同一类"对拍自己骗自己"骗到。

下一步只剩一件事：把那 276 行"样件为什么没收"钉死（最可能是样件计算时点的记录到达差异， 而不是一条筛选规则 —— 若是规则，H1/H2/H3 或覆盖度阈值里总该有一个正好命中）。钉死之后 fleet_scalar_z 即可正式转 raw-derived。

6.5 结论

• 能推：这条链上"内容是窗内标量函数"的那部分确实可以逆向工程 —— 已经推到 val 逐值 100%、三条口径全部落定；--verify 把这件事做成了可重复的机器判据。
• 判据纪律：对拍未全过时本器拒绝声明复现（退出码 5，打印"不要拿本器产物替换样件"）， 产物不替换，该件继续留 ✗ —— 宁可留着缺口，也不拿 92% 冒充标准答案。
• 下一步（按代价排序）：① 试 §6.4 的四个候选把基线钉死（一个探针脚本就能试完）； ② 行集那 276 行的差别（疑似样件计算时的记录到达时点差异）确认后随基线一起收口； ③ fusion_38.csv 无标准答案，需振动线给一份历史产出（或那四个脚本的源码）。

---

台账现状（2026-09-17）：✓ 呼应成立 1742 件 · ✗ 无生成端 285 件 · ◆ 人工件 209 件 · 无法验证 0 · 未归类 0。 缺料自查：python scripts/chain_gap_check.py --check；取料单：docs/向振动线取料单_v0.1.md。