# 振动六层链 —— 接口规格与缺口（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`。

### 7.5 `blade_1p_records` 的接续入口（本轮探到的确切起点）

按"先啃运动学已确定的那件"继续，把下一次能接着做的入口探清楚了：

| 事项 | 实测结论 |
|---|---|
| 覆盖范围 | 只两个测点：`Main_bearing_front` / `Main_bearing_rear`；662 行；时间 2026-01-27 11:35 ~ 2026-02-01 23:16（**w0127 首窗**，其索引在 `m5/tcm_index.parquet`，不在 `windows/w0127/`） |
| 转速来源 | ★ 样件行的 `rpm` **不是**同一记录里 `Kurtosis` 行的 rpm：样件 `rpm=1601.0371`，而索引里 `trigger_time` 同一条的 `Kurtosis` 行 `rpm=1604.2537`。⇒ 1P 分析用的是**该记录自己的转速**（`RpmProfile` / `rawRPM` 那类），不是标量指标行带的转速。这条搞错，`f1P` 就对不上（速比 119.75 本身不变） |
| 谱文件命名 | ★**更正**：`spectra/p<NN>/<meas_name>_n<lines>_<seq>.npz`（例 `FFT_4_Tr_n401_0000.npz`）；"记录 ↔ npz"**不需要靠枚举顺序去猜** —— `rudong_tcm_spectra.py` 落盘时已同时写出 `spectra_meta.parquet`（每行一条谱：turbine/sensor/meas_name/trigger_time/**shard/shard_row**/x_offset/x_delta），取数配方就是该脚本头部那句 `v = npz["values"][shard_row]; x = x_offset + arange(len(v))*x_delta`。本包新增 `scripts/spectra_lookup.py` 把它封成一条命令 |
| 谱本身 | npz 内是幅值数组；频率轴由索引的 `x_offset`/`x_delta`/`lines` 给出（例 `FFT_16000: lines=400, x_offset=0, x_delta=40` ⇒ 40 Hz/线）⇒ 频率轴可算；`f1P=0.223 Hz` 落在**第 0 条线**上 —— 这正是"1P 在低频谱里极难分辨"的原因，也解释了为什么这一族要专门做（样件 `energy_pct` 只有 0.38%） |

**下一次接手的最短路径**（三步，都在包内可做）：
① ~~读枚举顺序建映射~~ **已完成**：映射本来就是产品（`spectra_meta.parquet`），本包已封装为 `scripts/spectra_lookup.py`（实测 `WTG01/Main_bearing_rear/FFT_4_Tr` → `spectra/p00/FFT_4_Tr_n401_0000.npz` 第 1 行，0.01 Hz/线，401 点）；
② 用 `x_offset + i*x_delta` 重建频率轴，在 `f1P` 附近按候选口径（最近线 / ±2% 带内取最大 / 抛物线插值）取幅值，与样件 `a1P` 对拍；
③ `a1P` 一旦对上，`struct`（疑似 `a1P / fleet` 归一分）、`energy_pct`、`g1/g2/g4` 闸门与 `verdict` 有望按同样办法逐个对拍。

> 本轮到此为止的自我约束：**没有**在"峰值拾取口径未知"时硬写实现 —— 那样产出的数字无法证明是复现，只会给交付物掺进"看起来对"的东西。取料单里那**一句话**（或那四个脚本）到位后，上面三步当天可做完。
---

## 8. 1P 这一族的**本地阻塞点**（2026-09-17 查证）

用户令"做①（查 1 月 decode 件在不在）"的结论：**不在**。

| 查证项 | 结果 |
|---|---|
| `blade_1p_records` 时间跨度 | 2026-01-27 11:35 ~ 2026-02-01 23:16（**w0127 窗**） |
| w0127 的索引 | **在**（随包件 `m5_cms_tcm/tcm_index.parquet`，330,308 行、2026-01-27 ~ 2026-02-03、含样件那批时间戳的 89 行记录） |
| w0127 的**源件导出** | **不在**：`data/raw/如东/windcms/` 下只有 `CMS_RuDong_CGN_202603-04`（3–4 月）+ 厂家报告；`data/raw/如东/m5_cms_tcm/` 只有一份 docx |
| w0127 的谱库 | **不在**（盘上只有 w0316 的谱：1,701 分片 / 420,742 条谱记录） |

⇒ **1P 在本机无法重算**，缺的是**源件**，不是工具：索引在、查表工具（`scripts/spectra_lookup.py`）在、
运动学口径（`f1P = rpm/(60×119.75)`）在、频率轴算法在 —— 独独缺 1 月的 decode 导出。
这条已作为**第 7 项**加进取料单（`docs/向振动线取料单_v0.1.md` 第五节）。

**也因此确认**：`oem_scan` 侧那 23 件（谱在盘上，w0316）**仍可在本地推进**，只要拿到峰值拾取口径；
而 1P 那 662 行需要"口径 + 1 月源件"两样。两条路的先后可以按到料快慢决定。