dsh-motor-ai-l0 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -5,6 +5,20 @@
 
 版本三重一致性：`package.json.version` = `SKILL.md` 的 `metadata.version` = `CHANGELOG.md` 最新条目。
 
+## [0.2.3] - 2026-09-27 — 默认通道回归修复 + 对外物料（推广就绪）
+
+### 🔴 P0 回归修复：`auto` 不再进入代理通道
+- **现象**：0.2.2 把 `l0Mode='auto'` 纳入代理分支后，异步机默认输出严重残缺 —— `temp_rise=0`、`tooth_flux_density`/`yoke_flux_density`/`power_factor` 全 `undefined`、`feasible_count=0`（120 个候选无一可行），且 `sort_by='temp_rise'/'total_loss'/'torque_density'` 全部退化为 0，排序失效。
+- **根因**：`buildSurrogateResult()` 只输出 `efficiency` 一项，温升 / 损耗 / 磁密 / 可行判定均为 0 或缺失。代理通道本就只适合"效率排序"，不适合做默认。
+- **修复**：`tools/l0/l0-estimate.mjs:72` 代理分支条件回退为仅 `l0Mode === 'surrogate'`；`auto` 走字段完整的公式通道。代理模型 v2.2.0 与显式 `surrogate` 通道保持可用。
+- **验证**：`verify.mjs` 61/61 通过；异步 15kW/1460rpm `auto` → `feasible_count=80`、Top1 效率 95.17% / 温升 14.6K / 轭磁密 1.39T（字段完整）。
+
+### 📣 对外物料（推广就绪）
+- **README**：删除 0.1.7 时代过时的「surrogate 实验特性 / cv_r2≈0 / 特征泄漏」警告，替换为 v0.2.2 真实指标表（异步三段 OD 覆盖 / 样本数 / CV R² / MAE，PMSM 自动降级）；新增价值主张、示例输出（15kW 实跑 16 ms Top5）、通道分工表、明确不适用工况表；配置表补 `surrogatePath` / `surrogateConfidenceThreshold`。
+- **examples/**（新增，随包发布）：3 个真实算例 —— ① 15kW/1460rpm 异步（80 可行，16 ms）② 75kW/1480rpm/660V 异步（效率封顶并列时的二次排序）③ **200kW/22000rpm 高速 PMSM 反例**（`recommended=null`，公开能力边界）。
+- **keywords**：9 → 20（补 `induction-motor` `motor-sizing` `ansys` `电机设计` `永磁同步电机` `异步电机` 等中英文关键词）。
+- **assets/marketplace-listing.md**：0.1.0 → 0.2.2，重写 listing 文案、实测性能表、截图清单、npm 检查清单（含 npmjs 官方源踩坑提示）。
+
 ## [0.2.2] - 2026-09-26 — 代理通道修复（模型 v2.2.0）
 
 ### 🔴 P0 修复：代理模型 coef 空间错位（0.2.1 升级不可用根因）

package/README.md

@@ -2,6 +2,11 @@
 
 `dsh-motor-ai-l0` · DSH 插件（bundle） · 纯 JS，零求解器依赖
 
+> **不装 RMxprt / Motor-CAD / Python / license，把 120 个候选在十几毫秒内压成 Top5，
+> 只把求解器时间花在最值得的那几个上。**
+
+📁 **[算例集：3 个真实算例（含反例）→ examples/](examples/README.md)** · [能力边界](#已知精度边界)
+
 覆盖电机设计全流程：需求解析 → 参数识别 → 候选矩阵 → L0/L1/L2 解算 → Top10 与校验 → 完整方案。
 L0 用代理模型与经验公式毫秒级广筛候选；L1 RMxprt、L2 Motor-CAD 为**可选**精算工具。
 装完即用 —— 无需预装 RMxprt / Motor-CAD / Python，无需 license。
@@ -25,7 +30,21 @@ node scripts/verify.mjs
 > ⚠️ `motor_l0_estimate` 只接受 `params_list`（每项含 16 个 L1 顶层字段），**不接受** `power_kw` / `speed_rpm` 这类散装命名参数 —— 请先用第 1 步生成矩阵再传入。
 > L0 结果只用于**排序与相对比较**，不用于绝对值交付；输出恒带 `solve_mode='l0'` 标记，最终结论须由 L1/L2 给出。
 >
-> **⚠️ surrogate 通道为实验特性（0.1.7 标注）**：`l0Mode='surrogate'` 当前仅供实验——训练样本 od_range（约 612~2651mm）与真实中小机座（100~500mm）不匹配，段外样本全部降级公式通道；PMSM 段 cv_r2≈0 且特征含公式效率泄漏（`l0_eff`）。启用时工具输出带 `surrogate_experimental: true` 警告字段。**排序决策请使用默认公式通道**，重训前不承诺预测质量。
+> **两条通道的分工（v0.2.2）**
+>
+> | 通道 | 触发 | 输出 | 适用 |
+> |---|---|---|---|
+> | **公式通道**（默认） | `l0Mode: 'auto'` / `'formula'` | 效率 + 温升 + 损耗拆分 + 齿/轭磁密 + 功率因数 + 可行判定 —— 字段完整 | 日常排序与相对比较 |
+> | **代理通道**（可选增强） | `l0Mode: 'surrogate'` | **仅效率**（温升/损耗/磁密不输出） | 异步机效率排序的交叉参考 |
+>
+> 代理模型 v2.2.0 由 4955 条真实 RMxprt 结果训练（`designs.db.l0_residuals`，`fault=0`，效率 ∈ [50,99]），按机座外径分三段：
+>
+> | 机种 | 样本 OD 覆盖 | 样本数 | 5 折 CV R² | MAE |
+> |---|---|---|---|---|
+> | 异步 small / medium / large | 150.6–756.5 / 151.3–1085.4 / 1196–2651 mm | 1291 / 2578 / 1276 | 0.652 / 0.438 / 0.670 | 1.44 / 3.29 / 4.53 pp |
+> | PMSM small / medium / large | 612–1178 mm（均为大机座） | 367 / 745 / 355 | ≤ 0.31 → **自动降级公式通道** | — |
+>
+> 因此 **PMSM 与段外样本始终走公式通道**；`auto` 默认走字段完整的公式通道。启用代理时输出带 `surrogate_experimental: true`，且置信度低于阈值（`surrogateConfidenceThreshold`，默认 0.4）自动降级 —— 不会硬给一个数。
 
 ## 能力边界
 
@@ -48,6 +67,25 @@ node scripts/verify.mjs
 入参别名：`power`→`power_kw`、`rpm`→`speed_rpm`、`volt`→`voltage_v`。
 `sort_by` 白名单：`efficiency` `torque_density` `temp_rise` `total_loss` `power`（`temp_rise`、`total_loss` 升序，越小越好）。
 
+## 示例（15kW / 1460rpm / 380V 异步，实跑 16 ms）
+
+```text
+$ motor_param_matrix       { power_kw: 15, speed_rpm: 1460, voltage_v: 380, motor_type: 'induction', count: 120 }  →  120 候选
+$ motor_design_validate    12 条物理校验  →  120 passed / 0 failed
+$ motor_l0_estimate        sort_by: 'efficiency'  →  Top5，80 个可行候选
+```
+
+| # | OD (mm) | L (mm) | 极数 | 槽数 | 效率 (%) | 温升 (K) | 轭磁密 (T) | 总损耗 (W) |
+|---|---|---|---|---|---|---|---|---|
+| 1 | 310 | 226.4 | 6 | 72 | 95.17 | 14.6 | 1.39 | 604 |
+| 2 | 327 | 216.6 | 6 | 72 | 95.02 | 14.6 | 1.38 | 628 |
+| 3 | 278 | 187.1 | 6 | 72 | 94.94 | 20.5 | 1.38 | 642 |
+| 4 | 343 | 206.7 | 6 | 72 | 94.89 | 14.7 | 1.38 | 650 |
+| 5 | 294 | 177.2 | 6 | 72 | 94.81 | 20.5 | 1.38 | 663 |
+
+→ 这 5 个方案直接作为 L1（RMxprt）的入参，而不是把 120 个全丢给求解器。
+完整算例、复现命令与另外两个工况（75kW 异步、200kW 高速 PMSM **反例**）见 **[`examples/`](examples/README.md)**。
+
 ## 配置
 
 配置位于 `cordis.patch.yml`（查看：`npx -y @deepseek-ai/dsh --profile web --dump-config`）。最常用四项：
@@ -55,7 +93,9 @@ node scripts/verify.mjs
 | 配置项 | 默认 | 说明 |
 |---|---|---|
 | `level` | `'l0'` | 层级总闸。设为 `l1`/`l2` 立即抛错（快速失败，杜绝静默降级） |
-| `l0Mode` | `'auto'` | `formula` 纯公式 / `surrogate` 代理模型 / `auto` 自动降级 |
+| `l0Mode` | `'auto'` | `formula` 纯公式（字段完整）/ `surrogate` 代理模型（**仅输出效率**）/ `auto` = 公式通道，段外与低置信度自动降级 |
+| `surrogatePath` | `'models/l0_surrogate_family.json'` | 代理模型路径（v2.2.0） |
+| `surrogateConfidenceThreshold` | `0.4` | 代理置信度门限，低于此值降级公式 |
 | `efficiencyCap` | `96` | 效率封顶（与 L1 同口径，避免两层排序跳变） |
 | `insulationClass` | `'F'` | 绝缘等级，决定温升限值（B=80K / F=105K / H=125K） |
 
@@ -108,6 +148,15 @@ telemetryIntervalSec: 300
 L0 物理通道目前是 **v0.1 未标定版**（回归质量门判定 DEBT）：6 个标定案例效率低于参考带 0.35~2.96pt，温升偏保守。根因是损耗模型尚未用 RMxprt 批量结果标定（铁损未分齿/轭、铜损缺电路约束、机械损未标定、散热筋未计）。
 因此 L0 的正确用法是**排序与相对比较**，不是绝对值采信 —— **排序稳定性优于绝对精度**。完整实算数据与标定计划见 [`docs/QUALITY-GATE.md`](docs/QUALITY-GATE.md)。
 
+**明确不适用的工况**（实测，见 [`examples/03`](examples/03-pmsm-200kw-22000rpm.md)）：
+
+| 工况 | 表现 | 建议 |
+|---|---|---|
+| 高速 PMSM（>10000rpm） | 轭部磁路模型外推失真（轭磁密算得 >5 T，物理不可能）、温升 300 K+；门控会拒绝输出任何可行方案（`recommended = null`） | 直接进 L1 / L2 |
+| 效率绝对值交付 | 本版未标定，6 个标定案例偏差 0.35~2.96 pt | 仅排序，绝对值由 L1 复核 |
+
+> 门控"宁可交白卷，也不给假答案"是刻意设计：`level` 设为 `l1`/`l2` 时插件立即抛错，绝不静默降级成 L0 结果。
+
 ## 文档与许可
 
 - [`docs/ENGINEERING.md`](docs/ENGINEERING.md) —— 目录结构、字段契约 Param 锁、12 条校验规则、与 Python 体系差异、工程复盘、配置全表、路线图

package/examples/01-y2-15kw-1460rpm.md

@@ -0,0 +1,70 @@
+# 算例 1 · Y2 系列 15kW / 1460rpm / 380V 三相异步机
+
+> 本文件所有数值均由插件 **v0.2.2 实跑产出**（`l0Mode: auto`，Node.js 直调），未做人工修饰。
+> 复现方式见本文件末尾「复现命令」。
+
+## 1. 输入（Spec）
+
+| 项目 | 值 |
+|---|---|
+| 功率 | 15 kW |
+| 转速 | 1460 rpm |
+| 电压 | 380 V |
+| 机种 | induction（三相异步） |
+| 候选规模 | 120 |
+
+## 2. 流水线耗时
+
+| 步骤 | 工具 | 耗时 |
+|---|---|---|
+| 生成参数矩阵 | `motor_param_matrix` | 4 ms |
+| 物理一致性校验 | `motor_design_validate` | 6 ms |
+| L0 估算 + 排序 | `motor_l0_estimate` | 6 ms |
+| **合计** | | **16 ms**（120 个候选，单候选均摊 0.04 ms） |
+
+## 3. 校验与估算汇总
+
+| 指标 | 值 |
+|---|---|
+| 生成候选数 | 120 |
+| 通过 12 条物理校验 | 120（0 条 `failed`） |
+| 可行（feasible）候选 | **80** |
+| 估算成功 / 失败 | 120 / 0 |
+| 推荐方案（`recommended`） | OD 310 mm / 6 极 / 效率 95.17% / `verdict: feasible` |
+
+## 4. Top5（按效率降序，已按「几何 + 极数 + 槽数」去重）
+
+| # | OD (mm) | ID (mm) | L (mm) | 极数 | 槽数 | 效率 (%) | 温升 (K) | 齿磁密 (T) | 轭磁密 (T) | 功率因数 | 总损耗 (W) |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | 310 | 207.9 | 226.4 | 6 | 72 | 95.17 | 14.6 | 1.04 | 1.39 | 0.92 | 604 |
+| 2 | 327 | 218.8 | 216.6 | 6 | 72 | 95.02 | 14.6 | 1.04 | 1.38 | 0.92 | 628 |
+| 3 | 278 | 186.0 | 187.1 | 6 | 72 | 94.94 | 20.5 | 1.04 | 1.38 | 0.92 | 642 |
+| 4 | 343 | 229.7 | 206.7 | 6 | 72 | 94.89 | 14.7 | 1.04 | 1.38 | 0.92 | 650 |
+| 5 | 294 | 196.9 | 177.2 | 6 | 72 | 94.81 | 20.5 | 1.04 | 1.38 | 0.92 | 663 |
+
+**读法**：齿磁密恒定 1.04 T 是本版 L0 按经验磁密取值的结果（非逐槽有限元解）；轭磁密 1.38–1.39 T 落在常规 1.2–1.6 T 区间，未触发 V08 轭饱和门控（1.9 T）。
+
+## 5. 怎么用这个结果
+
+1. Top5 直接作为 L1（RMxprt）的入参矩阵 —— 求解器只跑 5 个方案，而不是 120 个。
+2. 效率用于**相对排序**，绝对值需 L1 复核（本版 L0 物理通道为未标定版，见 README「已知精度边界」）。
+3. 若客户对温升敏感，改用 `sort_by: 'temp_rise'`（升序）重排，无需重跑矩阵。
+
+## 6. 复现命令
+
+```bash
+# 方式 A：在 DSH 内（插件已安装）
+#   依次调用 motor_param_matrix → motor_design_validate → motor_l0_estimate
+#   入参：{ power_kw: 15, speed_rpm: 1460, voltage_v: 380, motor_type: 'induction', count: 120 }
+
+# 方式 B：裸 Node 直调（无需 DSH Runtime）
+node -e "
+import('./tools/l0/param-matrix.mjs').then(async (M) => {
+  const E = await import('./tools/l0/l0-estimate.mjs')
+  const cfg = { l0Mode: 'auto', level: 'l0' }
+  const rows = M.buildParamMatrix({ power_kw: 15, speed_rpm: 1460, voltage_v: 380, motor_type: 'induction', count: 120 }, cfg).matrix
+  const r = E.runL0Estimate({ params_list: rows, top_n: 5, sort_by: 'efficiency' }, cfg)
+  console.log(r.feasible_count, r.recommended, r.results.slice(0, 5).map(x => x.efficiency))
+})
+"
+```

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

@@ -0,0 +1,70 @@
+# 算例 2 · 75kW / 1480rpm / 660V 三相异步机（矿用隔爆功率档）
+
+> 本文件所有数值均由插件 **v0.2.2 实跑产出**（`l0Mode: auto`，Node.js 直调），未做人工修饰。
+
+## 1. 输入（Spec）
+
+| 项目 | 值 |
+|---|---|
+| 功率 | 75 kW |
+| 转速 | 1480 rpm |
+| 电压 | 660 V |
+| 机种 | induction（三相异步） |
+| 候选规模 | 120 |
+
+## 2. 流水线耗时
+
+| 步骤 | 工具 | 耗时 |
+|---|---|---|
+| 生成参数矩阵 | `motor_param_matrix` | 1 ms |
+| 物理一致性校验 | `motor_design_validate` | 2 ms |
+| L0 估算 + 排序 | `motor_l0_estimate` | 1 ms |
+| **合计** | | **4 ms**（120 个候选，单候选均摊 0.01 ms） |
+
+## 3. 校验与估算汇总
+
+| 指标 | 值 |
+|---|---|
+| 生成候选数 | 120 |
+| 通过 12 条物理校验 | 120（0 条 `failed`） |
+| 可行（feasible）候选 | **80** |
+| 估算成功 / 失败 | 120 / 0 |
+| 推荐方案（`recommended`） | OD 435 mm / 6 极 / 效率 96% / `verdict: feasible` |
+
+## 4. Top5（按效率降序，已按「几何 + 极数 + 槽数」去重）
+
+| # | OD (mm) | ID (mm) | L (mm) | 极数 | 槽数 | 效率 (%) | 温升 (K) | 齿磁密 (T) | 轭磁密 (T) | 功率因数 | 总损耗 (W) |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | 435 | 291.7 | 262.5 | 6 | 72 | 96 | 27.1 | 1.04 | 1.38 | 0.92 | 1922 |
+| 2 | 450 | 274.5 | 301.9 | 4 | 24 | 96 | 31.7 | 1.04 | 1.60 | 0.92 | 2603 |
+| 3 | 450 | 274.5 | 288.8 | 4 | 24 | 96 | 32.2 | 1.04 | 1.60 | 0.92 | 2560 |
+| 4 | 414 | 277.1 | 301.9 | 6 | 72 | 96 | 26.5 | 1.04 | 1.38 | 0.92 | 1953 |
+| 5 | 414 | 277.1 | 275.6 | 6 | 72 | 96 | 27.0 | 1.04 | 1.38 | 0.92 | 1867 |
+
+## 5. 这个算例能说明什么
+
+**效率并列时的二次排序。** 前 5 名效率全部为 96 —— 这是配置项 `efficiencyCap`（默认 96）的封顶结果，不是巧合。封顶的意义是与 L1 同口径，避免 L0/L1 两层排序跳变；代价是效率维度失去区分度。此时应换维度看：
+
+| 维度 | 结论 |
+|---|---|
+| 总损耗 | #5（1867 W）最优，比 #2（2603 W）低 28% |
+| 温升 | #4（26.5 K）最优 —— 6 极方案整体优于 4 极 |
+| 轭磁密 | 4 极方案 1.60 T 已越过 1.5 T 警告线，6 极 1.38 T 更从容 |
+
+> 实践建议：`sort_by` 用 `efficiency` 拿到第一梯队后，再用 `total_loss` / `temp_rise` 复排一次（`sort_by` 白名单：`efficiency` `torque_density` `temp_rise` `total_loss` `power`，后两者升序）。
+
+## 6. 复现命令
+
+```bash
+node -e "
+import('./tools/l0/param-matrix.mjs').then(async (M) => {
+  const E = await import('./tools/l0/l0-estimate.mjs')
+  const cfg = { l0Mode: 'auto', level: 'l0' }
+  const rows = M.buildParamMatrix({ power_kw: 75, speed_rpm: 1480, voltage_v: 660, motor_type: 'induction', count: 120 }, cfg).matrix
+  for (const by of ['efficiency', 'total_loss', 'temp_rise']) {
+    const r = E.runL0Estimate({ params_list: rows, top_n: 3, sort_by: by }, cfg)
+    console.log(by, '->', r.results.map(x => x.params.stator_od + '/' + x.params.poles + 'p'))
+  }
+})
+"
+```

package/examples/03-pmsm-200kw-22000rpm.md

@@ -0,0 +1,66 @@
+# 算例 3 · 200kW / 22000rpm / 380V 高速 PMSM（**能力边界反例**）
+
+> ⚠️ 这个算例**故意展示插件做不好的工况**。我们把它完整公开，是为了让使用者一眼看清 L0 的适用边界 ——
+> 而不是装上一跑、拿到一堆看似漂亮的效率数字就去报价。
+
+## 1. 输入（Spec）
+
+| 项目 | 值 |
+|---|---|
+| 功率 | 200 kW |
+| 转速 | 22000 rpm |
+| 电压 | 380 V |
+| 机种 | pmsm（永磁同步，高速） |
+| 候选规模 | 120 |
+
+## 2. 实跑结果
+
+| 指标 | 值 |
+|---|---|
+| 生成候选数 | 120 |
+| 通过 12 条物理校验 | **0**（全部被判 `failed`） |
+| 可行（feasible）候选 | **0** |
+| 推荐方案（`recommended`） | `null`（**不推荐任何方案**） |
+
+Top5（按效率降序）：
+
+| # | OD (mm) | ID (mm) | L (mm) | 极数 | 槽数 | 效率 (%) | 温升 (K) | 齿磁密 (T) | 轭磁密 (T) | 判定 |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | 253 | 182.3 | 164.0 | 2 | 12 | 95.42 | 379.9 | 1.04 | 5.28 | `infeasible_thermal` |
+| 2 | 253 | 182.3 | 172.3 | 2 | 12 | 95.39 | 368.4 | 1.04 | 5.28 | `infeasible_thermal` |
+| 3 | 253 | 182.3 | 180.6 | 2 | 12 | 95.37 | 357.7 | 1.04 | 5.28 | `infeasible_thermal` |
+| 4 | 253 | 182.3 | 188.9 | 2 | 12 | 95.35 | 347.7 | 1.04 | 5.28 | `infeasible_thermal` |
+| 5 | 253 | 182.3 | 197.1 | 2 | 12 | 95.33 | 338.4 | 1.04 | 5.28 | `infeasible_thermal` |
+
+## 3. 逐项解读
+
+| 现象 | 说明 |
+|---|---|
+| **轭磁密 5.28 T** | 物理上不可能（硅钢 1.8–2.0 T 即深度饱和）。根因是本版 L0 的轭部磁路模型未覆盖 22000rpm / 2 极高速工况的极短轭部路径，属**模型外推失真**，不是设计结果 |
+| **温升 338–380 K** | 远超 F 级限值 105 K。高速风摩耗与高频铁损的估算模型在本版未标定 |
+| **`recommended = null`、`feasible_count = 0`** | ✅ **这是正确的行为**：V08 轭饱和门控识别到 `yoke_sat = true`，拒绝输出任何"看起来可行"的方案。宁可交白卷，也不给假答案 |
+| 效率 95.33–95.42% | 在模型失真前提下**不可用**，请勿采信 |
+
+## 4. 结论与建议用法
+
+| 工况 | L0 是否适用 |
+|---|---|
+| 中低速异步机（≤3000rpm，150–1085mm 机座） | ✅ 适用，见算例 1 / 2 |
+| 常规 PMSM（≤6000rpm） | ⚠️ 排序可用，绝对值需 L1 复核 |
+| **高速 PMSM（>10000rpm）** | ❌ **不适用**，请直接进入 L1（RMxprt）/ L2（Motor-CAD） |
+
+插件的 `level` 配置会强制这一点：`l0Mode: 'auto'` 下无效方案不会进入 TopN；若你把 `level` 设为 `l1`/`l2`，插件会**立即抛错**而不是静默给出 L0 结果 —— 这是刻意设计的快速失败。
+
+## 5. 复现命令
+
+```bash
+node -e "
+import('./tools/l0/param-matrix.mjs').then(async (M) => {
+  const E = await import('./tools/l0/l0-estimate.mjs')
+  const cfg = { l0Mode: 'auto', level: 'l0' }
+  const rows = M.buildParamMatrix({ power_kw: 200, speed_rpm: 22000, voltage_v: 380, motor_type: 'pmsm', count: 120 }, cfg).matrix
+  const r = E.runL0Estimate({ params_list: rows, top_n: 5, sort_by: 'efficiency' }, cfg)
+  console.log('feasible =', r.feasible_count, '| recommended =', JSON.stringify(r.recommended))
+})
+"
+```

package/examples/README.md

@@ -0,0 +1,42 @@
+# 算例集 · dsh-motor-ai-l0
+
+本目录的每个算例都是 **v0.2.2 实跑产出**（`l0Mode: auto`，裸 Node 直调，无需 DSH Runtime / RMxprt / Motor-CAD），
+数值未经人工修饰 —— 包括做不好的那一个。
+
+| # | 算例 | 工况 | 结果概览 | 用途 |
+|---|---|---|---|---|
+| [01](01-y2-15kw-1460rpm.md) | Y2 系列 15kW 异步 | 15 kW / 1460 rpm / 380 V | 120 候选 → 80 可行，Top1 效率 95.17%、温升 14.6 K，**16 ms** | 入门：看完整输出长什么样 |
+| [02](02-75kw-1480rpm-660v.md) | 75kW 异步（矿用档） | 75 kW / 1480 rpm / 660 V | 120 候选 → 80 可行，效率封顶并列，**4 ms** | 进阶：效率并列时如何用损耗/温升二次排序 |
+| [03](03-pmsm-200kw-22000rpm.md) | 200kW 高速 PMSM | 200 kW / 22000 rpm / 380 V | **0 可行**，`recommended = null` | 边界：看清 L0 不适用什么（反例） |
+
+## 三步流水线（顺序固定）
+
+```text
+motor_param_matrix       功率/转速/电压 → 候选参数矩阵
+        ↓
+motor_design_validate    12 条物理校验，剔除 failed
+        ↓
+motor_l0_estimate        毫秒级估算 + 排序 + TopN + L1 交接载荷
+```
+
+> `motor_l0_estimate` 只接受 `params_list`（由第 1 步生成，每项含 16 个 L1 顶层字段），
+> **不接受** `power_kw` / `speed_rpm` 这类散装参数。
+
+## 复现
+
+所有算例文件末尾都带有可直接粘贴的 `node -e` 命令，在插件根目录执行即可复现（Node.js ≥ 22）：
+
+```bash
+cd dsh-motor-ai-l0
+node -e "<算例文件中的命令>"
+```
+
+## 关于数值的可信度
+
+| 用途 | 是否可信 |
+|---|---|
+| 方案之间的**相对排序** | ✅ L0 的设计目标，排序稳定性优先 |
+| 效率 / 温升的**绝对值** | ⚠️ 本版物理通道未标定，须由 L1（RMxprt）复核 |
+| 高速 PMSM（>10000rpm）任何结论 | ❌ 见算例 03 |
+
+细节见根目录 [README.md](../README.md)「已知精度边界」与 [docs/QUALITY-GATE.md](../docs/QUALITY-GATE.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-motor-ai-l0",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "main": "./index.mjs",
   "description": "电机AI辅助设计软件插件 · 覆盖电机设计全流程（需求解析 → 候选矩阵 → L0/L1/L2 解算 → Top10 校验）；L0 毫秒级广筛，纯 JS 零求解器依赖",
@@ -14,6 +14,7 @@
     "models/",
     "scripts/",
     "docs/",
+    "examples/",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
@@ -45,11 +46,22 @@
     "dsh",
     "motor-design",
     "electric-motor",
-    "motor-ai",
+    "electric-machine-design",
+    "induction-motor",
+    "asynchronous-motor",
     "pmsm",
+    "permanent-magnet-synchronous-motor",
+    "motor-sizing",
+    "motor-selection",
+    "electromagnetic-design",
+    "motor-ai",
     "l0-estimate",
     "rmxprt",
-    "motor-cad"
+    "motor-cad",
+    "ansys",
+    "电机设计",
+    "永磁同步电机",
+    "异步电机"
   ],
   "license": "MIT",
   "repository": {

package/scripts/_publish_0_2_3.py

@@ -0,0 +1,67 @@
+import os, sys, json, tarfile, hashlib
+from datetime import datetime, timedelta, timezone
+
+PLUGIN_DIR = r"D:\dsh-motor-ai-l0"
+DIST_DIR = os.path.join(PLUGIN_DIR, "dist")
+BUNDLE = os.path.join(DIST_DIR, "dsh-motor-ai-l0-v0.2.3.tar.gz")
+REGISTRY_PY = r"D:\MotorDesign\Core\dsh_registry.py"
+PLUGIN_ID = "dsh-motor-ai-l0"
+VERSION = "0.2.3"
+
+sys.path.insert(0, os.path.dirname(REGISTRY_PY))
+import dsh_registry as R
+
+EXCLUDE_DIRS = {".git", "__pycache__", "node_modules", "dist", ".workbuddy"}
+EXCLUDE_EXT = {".bak", ".pyc", ".pyo"}
+
+def walk_files(root):
+    for dp, dn, fn in os.walk(root):
+        dn[:] = [d for d in dn if d not in EXCLUDE_DIRS]
+        for f in fn:
+            if os.path.splitext(f)[1] in EXCLUDE_EXT:
+                continue
+            yield os.path.join(dp, f)
+
+print("== 打包 ==")
+os.makedirs(DIST_DIR, exist_ok=True)
+with tarfile.open(BUNDLE, "w:gz") as tf:
+    for fp in sorted(walk_files(PLUGIN_DIR)):
+        rel = os.path.relpath(fp, PLUGIN_DIR)
+        tf.add(fp, arcname=rel)
+    count = len(tf.getmembers())
+print("  条目数:", count)
+
+print("== SHA256 ==")
+h = hashlib.sha256()
+with open(BUNDLE, "rb") as f:
+    for chunk in iter(lambda: f.read(1 << 20), b""):
+        h.update(chunk)
+sha = h.hexdigest()
+print("  ", sha)
+
+print("== 注册表 ==")
+R.update_plugin_fields(PLUGIN_ID, {"version": VERSION, "status": "published"}, db_path=None)
+R.set_release_gate(PLUGIN_ID, True,
+                   "v0.2.3 修复 auto 走代理通道导致字段残缺(temp_rise=0/feasible_count=0)的回归 + "
+                   "对外物料(README 真实指标/examples 3 算例/keywords 20/listing 0.2.2) + verify 61/61",
+                   db_path=None)
+token_id = f"tok_{sha[:12]}"
+R.issue_token(PLUGIN_ID, token_id, token_type="one_time", tier="free",
+              expires_at=(datetime.now(timezone.utc) + timedelta(days=90)).isoformat(), db_path=None)
+print("  version ->", VERSION, "| token ->", token_id)
+
+print("== publish-log ==")
+log = {
+    "plugin_id": PLUGIN_ID,
+    "version": VERSION,
+    "timestamp": datetime.now(timezone.utc).isoformat(),
+    "bundle": os.path.basename(BUNDLE),
+    "sha256": sha,
+    "token_id": token_id,
+    "channel": "l0",
+    "tier": "free",
+}
+with open(os.path.join(PLUGIN_DIR, "metadata", "publish-log.json"), "w", encoding="utf-8") as f:
+    json.dump(log, f, ensure_ascii=False, indent=2)
+print("  ", json.dumps(log, ensure_ascii=False))
+print("DONE")

package/skills/motor-l0-estimate/SKILL.md

@@ -22,7 +22,7 @@ whenToUse: >
 user-invocable: true
 metadata:
   author: Motor-AI
-  version: 0.2.2
+  version: 0.2.3
   level: l0
   tier: free
 ---

package/tools/l0/l0-estimate.mjs

@@ -69,7 +69,9 @@ export function runL0Estimate(rawArgs, config = {}) {
 
   // ---- 代理模型通道（需显式启用 l0Mode='surrogate'）----
   // 'auto' 与 'surrogate' 都走代理通道；'auto' 下代理失败/降级会自动回退公式通道（函数尾部）
-  if (l0Mode === 'surrogate' || l0Mode === 'auto') {
+  // 代理通道仅输出效率（温升/损耗/磁密/可行判定均由公式通道给出），
+  // 因此只在用户显式指定 surrogate 时启用：auto 默认走字段完整的公式通道。
+  if (l0Mode === 'surrogate') {
     try {
       const modelPath = config.surrogatePath ?? 'models/l0_surrogate_family.json'
       const model = loadSurrogateModel(modelPath)