dsh-motor-ai-l0 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -5,6 +5,25 @@
 
 版本三重一致性：`package.json.version` = `SKILL.md` 的 `metadata.version` = `CHANGELOG.md` 最新条目。
 
+## [0.2.4] - 2026-10-07 — 代理模型 v2.3.0-fixseg 部署 + GBR 残差校正启用
+
+### 🚀 代理模型升级：v2.2.0 → v2.3.0-fixseg
+- **特征空间扩展**：5 特征（含 `poles`），OD 三分位切段（small/medium/large × induction/pmsm）。
+- **模型锁定**：云端重训流水线锁定 `scikit-learn==1.9.1`（`numpy==2.5.0` / `scipy==1.18.1`），复现 G7 门禁（纯 numpy 回放 vs sklearn 重训 maxdiff < 1e-6）。
+- **校验**：`verify.mjs` 70/70 通过；代理模型版本断言 `2.3.0-fixseg`。
+
+### ✨ 新能力：GBR 残差校正（ridge_plus_gbr 第二阶段）
+- `lib/surrogate-engine.mjs` 新增 `predictGBR()`，消费模型每段 `gbr` 字段（400 树 / `lr=0.05`），对 ridge 基线做残差修正：`final = primary + gbr_residual`。
+- 单测新增 4 例（无 gbr 退化为 0、残差量级合理、预测携带 `used_gbr` / `gbr_residual_pp`），单测 18 → 22 全绿。
+- 置信度门控维持 ridge 通道口径（不放大降级），仅提升预测精度。
+
+### 🔧 工程
+- `tools/l0/pipeline.mjs` 聚合工具随包发布（一步跑完 `buildParamMatrix → runDesignValidate → runL0Estimate`，规避 DSH 2000 行截断）。
+- 版本三重一致性：package.json / SKILL.md metadata / CHANGELOG 同步至 0.2.4。
+
+### ⚠️ 不在本次发布范围
+- V16（极数-转速同步一致性校验）等规则层改动仍在开发中，未并入本版本，避免裹挟未经验证的变更。
+
 ## [0.2.3] - 2026-09-27 — 默认通道回归修复 + 对外物料（推广就绪）
 
 ### 🔴 P0 回归修复：`auto` 不再进入代理通道

package/README.md

@@ -27,6 +27,12 @@ node scripts/verify.mjs
 2. `motor_design_validate` —— 批量物理校验，剔除 `failed`
 3. `motor_l0_estimate` —— 对剩余候选排序，输出 TopN 与 L1 交接载荷
 
+> ⚠️ **推荐用聚合工具 `motor_l0_pipeline` 一步跑完上述三步链**。DSH 对话上下文有 **2000 行读取上限**：
+> 当 `count=120` 时，单 `motor_param_matrix` 就回显 4000+ 行，模型静默丢行后计数对不上 120 还**无报错**——
+> 这是「让模型亲手编排三步链」的结构性风险（三案例实战全中）。聚合工具在插件进程内跑完三步链，
+> 只回吐紧凑摘要（计数自检 + Top10 + 交接载荷 + 文件交接路径），上下文恒 < 2000 行，从根上绕开截断。
+> 只有在单独调试某一步（查完整校验报告、手调 failed 阈值）时才拆开用三个独立工具。
+
 > ⚠️ `motor_l0_estimate` 只接受 `params_list`（每项含 16 个 L1 顶层字段），**不接受** `power_kw` / `speed_rpm` 这类散装命名参数 —— 请先用第 1 步生成矩阵再传入。
 > L0 结果只用于**排序与相对比较**，不用于绝对值交付；输出恒带 `solve_mode='l0'` 标记，最终结论须由 L1/L2 给出。
 >
@@ -37,7 +43,7 @@ node scripts/verify.mjs
 > | **公式通道**（默认） | `l0Mode: 'auto'` / `'formula'` | 效率 + 温升 + 损耗拆分 + 齿/轭磁密 + 功率因数 + 可行判定 —— 字段完整 | 日常排序与相对比较 |
 > | **代理通道**（可选增强） | `l0Mode: 'surrogate'` | **仅效率**（温升/损耗/磁密不输出） | 异步机效率排序的交叉参考 |
 >
-> 代理模型 v2.2.0 由 4955 条真实 RMxprt 结果训练（`designs.db.l0_residuals`，`fault=0`，效率 ∈ [50,99]），按机座外径分三段：
+> 代理模型 v2.3.0-fixseg（在 v2.2.0 基础上用全量 6029 条真实 RMxprt 结果重训，特征扩为含 `poles` 的 5 维；`designs.db.l0_residuals`，`fault=0`，效率 ∈ [50,99]），按机座外径分三段：
 >
 > | 机种 | 样本 OD 覆盖 | 样本数 | 5 折 CV R² | MAE |
 > |---|---|---|---|---|
@@ -60,9 +66,10 @@ node scripts/verify.mjs
 
 | 工具 | 作用 | 关键入参 |
 |---|---|---|
+| `motor_l0_pipeline` | **推荐入口**：三步链聚合，只回紧凑摘要 + 文件交接，根治 2000 行截断 | `power_kw` `speed_rpm` `count` `top_n` `write_handoff` |
 | `motor_param_matrix` | 生成候选参数矩阵（聚焦扫描，非笛卡尔积） | `power_kw` `speed_rpm` `voltage_v` `poles` `count` |
-| `motor_l0_estimate` | 毫秒级估算 + 排序 + L1 交接载荷 | `params_list` `top_n` `sort_by` |
-| `motor_design_validate` | 12 条物理一致性校验，返回 `passed`/`warning`/`failed` | `params_list` `escalate` |
+| `motor_l0_estimate` | 毫秒级估算 + 排序 + L1 交接载荷（默认 Top10） | `params_list` `top_n` `sort_by` |
+| `motor_design_validate` | 15 条物理一致性校验，返回 `passed`/`warning`/`failed` | `params_list` `escalate` |
 
 入参别名：`power`→`power_kw`、`rpm`→`speed_rpm`、`volt`→`voltage_v`。
 `sort_by` 白名单：`efficiency` `torque_density` `temp_rise` `total_loss` `power`（`temp_rise`、`total_loss` 升序，越小越好）。
@@ -94,9 +101,9 @@ $ motor_l0_estimate        sort_by: 'efficiency'  →  Top5，80 个可行候选
 |---|---|---|
 | `level` | `'l0'` | 层级总闸。设为 `l1`/`l2` 立即抛错（快速失败，杜绝静默降级） |
 | `l0Mode` | `'auto'` | `formula` 纯公式（字段完整）/ `surrogate` 代理模型（**仅输出效率**）/ `auto` = 公式通道，段外与低置信度自动降级 |
-| `surrogatePath` | `'models/l0_surrogate_family.json'` | 代理模型路径（v2.2.0） |
+| `surrogatePath` | `'models/l0_surrogate_family.json'` | 代理模型路径（v2.3.0-fixseg） |
 | `surrogateConfidenceThreshold` | `0.4` | 代理置信度门限，低于此值降级公式 |
-| `efficiencyCap` | `96` | 效率封顶（与 L1 同口径，避免两层排序跳变） |
+| `efficiencyCap` | `96` | 效率封顶（与 L1 同口径，避免两层排序跳变）。v0.2.4 起仅钳**展示值** `efficiency`，排序按 `efficiency_raw`（未封顶真值） |
 | `insulationClass` | `'F'` | 绝缘等级，决定温升限值（B=80K / F=105K / H=125K） |
 
 其余配置项（本地统计 `usageLog`；L0 运行 `surrogatePath` / `surrogateConfidenceThreshold` / `maxMatrixSize` / `topNPreview` / `tempRiseRange` / `airGapFluxT` / `highSpeedRpm`；脱敏回传 `telemetryEnabled` / `telemetryEndpoint` / `telemetryBatchSize` / `telemetryIntervalSec` / `sessionTelemetry`）见 [`docs/ENGINEERING.md`](docs/ENGINEERING.md#八配置全表) 与本文「脱敏聚合指标回传」节。

package/docs/ENGINEERING.md

@@ -225,7 +225,7 @@ Python 走 `Knowledge/y_series_physics.json` 查表；L0 要求零外部依赖
 | `surrogateConfidenceThreshold` | `0.7` | 置信度低于此值自动降级到公式模式 |
 | `maxMatrixSize` | `2000` | 参数矩阵最大组合数 |
 | `topNPreview` | `20` | L0 结果预览返回的 TopN 数量 |
-| `efficiencyCap` | `96` | 效率封顶（对齐 `motor_tools.py:752`，避免 L0/L1 排序跳变） |
+| `efficiencyCap` | `96` | 效率封顶（对齐 `motor_tools.py:752`，避免 L0/L1 排序跳变）。⚠ v0.2.4 起它只作用于**展示值** `efficiency`；排序与区分度看 `efficiency_raw` |
 | `tempRiseRange` | `[45, 130]` | `max_temp` 钳位区间（**°C**）。⚠ 命名待议 —— 易被误读为 L0 温升（K），拟改 `maxTempClamp` |
 | `airGapFluxT` | `0.8` | 气隙磁密基准 T（齿 / 轭磁密反算输入），PMSM 典型 0.75~0.90 |
 | `insulationClass` | `'F'` | 绝缘等级，决定温升限值（B=80K / F=105K / H=125K） |

package/docs/QUALITY-GATE.md

@@ -41,7 +41,9 @@ node scripts/regression.mjs --json              # 机器可读输出
 2. **铜损**：槽面积由几何推算，缺少「匝数 × 电流」的电路约束；槽满率 0.45 与电密 5.5 A/mm² 均为经验值
 3. **机械损**：`MECH_LOSS_K = 5` 未标定，仅保证量级正确
 4. **温升**：散热面积按**光滑**机座外表面积计，未计散热筋；`COOLING_COEFFICIENT` 为单点标定
-5. **效率封顶**：`efficiencyCap=96` 是为与 `_run_simulated` 同口径的权宜值，对高效高速机会低估
+5. **效率封顶**：`efficiencyCap=96` 是为与 `_run_simulated` 同口径的权宜值，对高效高速机会低估。
+   v0.2.4 起封顶只影响展示值 `efficiency`；**排序与 TopN 区分度改用未封顶真值 `efficiency_raw`**，
+   整批触顶时结果行会带 `efficiency_capped=true`、顶层带 `efficiency_note` 说明
 
 ---
 
@@ -78,6 +80,7 @@ node scripts/regression.mjs --json              # 机器可读输出
 
 - [ ] 用 RMxprt 批量结果做 native vs L1 回归，拟合 `kh/ke`、`MECH_LOSS_K`、`COOLING_COEFFICIENT`
 - [ ] 回归目标：标定域内 `|Δη| ≤ 2pt`、`|Δ温升| ≤ 10K`
+- [x] 校准前先解耦"封顶"与"排序"（v0.2.4 已完成）：cap 保持 96 维持 L1 同口径，排序改用 `efficiency_raw`
 - [ ] 校准完成后重新评估 `efficiencyCap` 是否需要放宽（当前 96 对高速高效机偏保守）
 
 ### 翻转判据

package/examples/02-75kw-1480rpm-660v.md

@@ -43,7 +43,11 @@
 
 ## 5. 这个算例能说明什么
 
-**效率并列时的二次排序。** 前 5 名效率全部为 96 —— 这是配置项 `efficiencyCap`（默认 96）的封顶结果，不是巧合。封顶的意义是与 L1 同口径，避免 L0/L1 两层排序跳变；代价是效率维度失去区分度。此时应换维度看：
+**效率并列时的二次排序。** 前 5 名的**展示值**全部为 96 —— 这是配置项 `efficiencyCap`（默认 96）的封顶结果，不是巧合。封顶的意义是与 L1 同口径，避免 L0/L1 两层排序跳变。
+
+⚠️ **v0.2.4 起这两个数要分开读**：`efficiency` 是钳位后的展示值（触顶时都等于 96），
+`efficiency_raw` 才是未封顶真值，**排序按 `efficiency_raw` 进行**，所以 Top5 的先后顺序是有物理依据的，
+不是并列。要看真实差距请读结果行里的 `efficiency_raw` 字段。若仍只见并列，可换维度看：
 
 | 维度 | 结论 |
 |---|---|

package/index.mjs

@@ -17,7 +17,9 @@
  * @property {number} surrogateConfidenceThreshold  置信度低于此值降级到公式
  * @property {number} maxMatrixSize          参数矩阵最大组合数
  * @property {number} topNPreview            L0 结果预览 TopN
- * @property {number} efficiencyCap          效率封顶（对齐 _run_simulated L752）
+ * @property {number} efficiencyCap          效率封顶（对齐 _run_simulated L752）。
+ *                                            v0.2.4 起仅钳展示值 efficiency；
+ *                                            排序与区分度看未封顶真值 efficiency_raw
  * @property {[number, number]} tempRiseRange temp 钳位区间 (°C)，对齐 L1 max_temp；命名待议（拟改 maxTempClamp）
  * @property {boolean} [l1Enabled]           预留
  * @property {boolean} [l2Enabled]           预留

package/lib/design-rules.mjs

@@ -43,6 +43,7 @@ export const RULE_CATALOG = [
   { id: 'V12', name: '温升限值', severity: 'warning', needs: 'power_kw 或 torque_nm（+ 冷却方式）' },
   { id: 'V14', name: '反电势闭环', severity: 'failed', needs: 'voltage/speed/poles/stator_id/core_length/slots_stator/parallel_circuits/turns_per_coil' },
   { id: 'V15', name: '槽满率可行性', severity: 'failed', needs: 'stator_od/stator_id/slots_stator/poles/peak_current/turns_per_coil/parallel_circuits' },
+  { id: 'V16', name: '极数-转速同步一致性', severity: 'failed', needs: 'speed/poles' },
 ]
 
 /** 可在 config 中把严重度提升为 failed 的规则（默认 warning） */
@@ -426,6 +427,31 @@ export function validateDesign(row, opts = {}) {
     skipped.push('V15')
   }
 
+  // ---- V16 极数-转速同步一致性（超同步拦截，P0 门禁）----
+  // 异步电动机额定转速必须低于同步转速 n_sync = 120·f_line/p（转差为正才能输出转矩）；
+  // 若 n_sync ≤ 额定转速 ⇒ 转差 ≤ 0（超同步），异步机无法作为电动机运行（只能作发电机/制动）。
+  // 同步机（PMSM/BLDC/IPM）无转差概念，本规则不适用，显式跳过。
+  // ⚠ 工频 f_line 按 IEC/中国 50Hz 假设；60Hz 电网需后续在 config 暴露 line_freq_hz。
+  if (speed !== null && poles !== null) {
+    const isPm = isPmsmType(row?.motor_type)
+    if (isPm) {
+      skipped.push('V16')
+    } else {
+      const LINE_FREQ_HZ = 50
+      const nSync = (120 * LINE_FREQ_HZ) / poles
+      metrics.sync_speed_rpm = round1(nSync)
+      if (nSync <= speed) {
+        // 推荐极数：满足 n_sync > 转速 的最大极数（取 floor 留 1e-6 余量避免同步边界=speed 误判）
+        const recommendedPole = Math.max(2, Math.floor((120 * LINE_FREQ_HZ) / speed - 1e-6) || 2)
+        fail('V16', `极数 ${poles} 与转速 ${speed}rpm 不同步：同步转速 ${round1(nSync)}rpm ≤ 额定转速，` +
+          `异步机转差≤0（超同步），无法作为电动机运行；该转速档应选 ${recommendedPole} 极` +
+          `（n_sync=${(120 * LINE_FREQ_HZ) / recommendedPole}rpm）`)
+      }
+    }
+  } else {
+    skipped.push('V16')
+  }
+
   // ---- V13 每线圈匝数下限（附在 V06 组，不单独占号）----
   // v0.1.6：闭环反推可能给出 turns_per_coil=1（380V/高频低匝数场景，hairpin 扁线绕组可行），
   // 故下限改为 <1（仅排除真正不可实现的 0/负匝数），不再误报 1 匝方案。

package/lib/formula-engine.mjs

@@ -302,6 +302,13 @@ export function estimateTempRise({ statorOd, coreLength, cooling }, totalLossW)
  * L1 仿真效率去噪克隆 —— motor_tools.py:750-752
  *   base_eff = 85 + (od-180)·0.04 + (poles-8)·1.2，Python 侧另有 ±1.5 噪声
  */
+/**
+ * 未封顶效率的物理硬上界（v0.2.4）
+ * 仅作数值保险：物理模型不可能算出 >100% 的效率，取 99.9 以防浮点/极端输入溢出。
+ * 注意与 efficiencyCap 的区别：cap 是「与 L1 同口径」的口径约定，此值是物理边界。
+ */
+const RAW_EFF_MAX = 99.9
+
 export function l1EfficiencyProxy({ statorOd, poles }, clampMax = SIM_EFF.clampMax) {
   const base =
     SIM_EFF.base +
@@ -384,6 +391,11 @@ export function quickL0Estimate(params, opts = {}) {
   const poleFactor = POLE_EFFICIENCY_FACTOR[poles] ?? 0.98
   const rawEff = efficiencyFromLosses(powerKw, totalLossW) * poleFactor
   const efficiency = round2(Math.min(efficiencyCap, Math.max(SIM_EFF.clampMin, rawEff)))
+  // v0.2.4：efficiencyCap 存在的意义是「与 L1 同口径」，不是物理真值。
+  // 大机座整批触顶时 efficiency 全被压成同一个数 ⇒ TopN 排序失去区分度（450kW 实测 10/10 触顶）。
+  // 故额外保留未封顶真值供排序使用，并打触顶标记，让调用方知道 efficiency 是"钳位显示值"。
+  const efficiencyRaw = round2(clamp(rawEff, SIM_EFF.clampMin, RAW_EFF_MAX))
+  const efficiencyCapped = rawEff > efficiencyCap + 1e-9
 
   // ---- 温升（物理通道，含液冷标定修正）----
   const tempRise = estimateTempRise({ statorOd, coreLength, cooling }, totalLossW)
@@ -409,6 +421,8 @@ export function quickL0Estimate(params, opts = {}) {
 
   const native = {
     efficiency,
+    efficiency_raw: efficiencyRaw,
+    efficiency_capped: efficiencyCapped,
     torque: round2(torque),
     temp_rise: tempRise,
     total_loss: totalLossW,

package/lib/param-schema.mjs

@@ -136,7 +136,9 @@ export const PARAM_SCHEMA = {
 
 /** L0 原生字段 —— 物理损耗通道的独立产出 + v0.1.6 可追溯诊断字段 */
 export const L0_NATIVE_FIELDS = [
-  'efficiency',       // %   物理损耗模型推算
+  'efficiency',       // %   物理损耗模型推算（按 efficiencyCap 封顶，与 L1 同口径）
+  'efficiency_raw',   // %   未封顶真实值（v0.2.4）—— 排序用，避免封顶压平区分度
+  'efficiency_capped',// bool 是否触顶被封（v0.2.4）—— 触顶时 efficiency 非真值
   'torque',           // Nm  9550·P/n
   'temp_rise',        // K   热负荷法温升（注意：与 max_temp 的 °C 口径不同）
   'total_loss',       // W   铜损+铁损+机械损

package/lib/surrogate-engine.mjs

@@ -151,6 +151,51 @@ export function predictLinear(features, coeffs) {
   return result
 }
 
+/**
+ * 评估单棵 GBR 决策树（sklearn 数组导出格式）
+ * 约定：feature[i] === -2 表示叶子节点，values[i] 为叶子输出；
+ *       叶子节点 left/right 均为 -1。以 maxIter 兜底防异常树结构死循环。
+ * @param {number[]} features 标准化特征向量
+ * @param {object} tree 单棵树 { feature, threshold, left, right, values }
+ * @returns {number} 该树对残差的贡献
+ */
+function applyTree(features, tree) {
+  let node = 0
+  const maxIter = tree.feature.length + 1
+  for (let i = 0; i < maxIter; i++) {
+    const f = tree.feature[node]
+    if (f === -2) {
+      return tree.values[node]
+    }
+    if (features[f] <= tree.threshold[node]) {
+      node = tree.left[node]
+    } else {
+      node = tree.right[node]
+    }
+  }
+  return tree.values[node] ?? 0
+}
+
+/**
+ * GBR 残差校正预测（ridge_plus_gbr 第二阶段）
+ * 公式（与训练端 M1 一致）：residual = init + learning_rate * Σ applyTree(features, tree)
+ * 残差与 primary 线性预测同单位（效率百分点），最终效率 = primary + residual。
+ * 模型无 gbr 字段时返回 0（退化为纯 ridge 通道，行为不变）。
+ * @param {number[]} features 标准化特征向量
+ * @param {object|undefined} gbr GBR 模型对象（含 init/learning_rate/trees）
+ * @returns {number} 残差修正量（效率百分点）
+ */
+export function predictGBR(features, gbr) {
+  if (!gbr || !Array.isArray(gbr.trees) || gbr.trees.length === 0) {
+    return 0
+  }
+  let sum = 0
+  for (const tree of gbr.trees) {
+    sum += applyTree(features, tree)
+  }
+  return (gbr.init ?? 0) + (gbr.learning_rate ?? 1) * sum
+}
+
 /**
  * 代理模型预测单个样本（分族模型）
  * @param {object} params L0 参数字典
@@ -166,7 +211,7 @@ export function predictSurrogate(params, model, motorType = null) {
   if (model.schema === 'l0_surrogate_family') {
     const segment = selectFamilySegment(statorOd, type, model)
     if (segment) {
-      return predictFromSegment(params, segment.primary, model, type)
+      return predictFromSegment(params, segment, model, type)
     }
     // 超出范围，返回 null 让调用方降级
     return null
@@ -183,7 +228,8 @@ export function predictSurrogate(params, model, motorType = null) {
 /**
  * 从分族模型预测
  */
-function predictFromSegment(params, primary, model, motorType) {
+function predictFromSegment(params, segment, model, motorType) {
+  const primary = segment.primary
   const norm = {
     // primary.feature_names 是 v1.x 格式；v2.x 把特征顺序存在顶层 model.features
     featureOrder: primary.feature_names ?? model.features,
@@ -192,11 +238,20 @@ function predictFromSegment(params, primary, model, motorType) {
   }
   const features = extractFeatures(params, norm)
 
-  // 预测效率 (物理合理性钳位: 效率不可能 <50% 或 >99%)
+  // 基础预测（加权 Ridge）
   const rawEff = predictLinear(features, primary)
-  const efficiency = Math.min(99, Math.max(50, rawEff))
 
-  // 置信度：基于 R² 和特征范围
+  // GBR 残差校正（ridge_plus_gbr 第二阶段）：final = base + residual
+  // 残差与 primary 同单位（效率百分点），模型无 gbr 字段时退化为纯 ridge（行为不变）
+  const gbrResidual = predictGBR(features, segment.gbr)
+  const correctedEff = rawEff + gbrResidual
+
+  // 预测效率 (物理合理性钳位: 效率不可能 <50% 或 >99%)
+  const efficiency = Math.min(99, Math.max(50, correctedEff))
+
+  const usedGbr = !!segment.gbr && Array.isArray(segment.gbr.trees) && segment.gbr.trees.length > 0
+
+  // 置信度：基于 R² 和特征范围（维持与纯 ridge 通道一致，避免改变降级判定）
   const confidence = estimateConfidence(features, norm, primary.cv_r2)
 
   return {
@@ -207,6 +262,8 @@ function predictFromSegment(params, primary, model, motorType) {
     prediction_source: 'surrogate',
     family: { motor_type: motorType, size: primary.tag?.split('_')[0] },
     cv_r2: primary.cv_r2,
+    used_gbr: usedGbr,
+    gbr_residual_pp: usedGbr ? Math.round(gbrResidual * 1000) / 1000 : 0,
   }
 }
 
@@ -387,5 +444,6 @@ export default {
   buildSurrogateResult,
   extractFeatures,
   selectFamilySegment,
+  predictGBR,
   DEFAULT_CONFIDENCE_THRESHOLD,
 }