电机AI辅助设计软件插件

dsh-motor-ai-l0 · DSH 插件（bundle） · 纯 JS，零求解器依赖

不装 RMxprt / Motor-CAD / Python / license，把 120 个候选在十几毫秒内压成 Top5， 只把求解器时间花在最值得的那几个上。

📁 算例集：3 个真实算例（含反例）→ examples/ · 能力边界

覆盖电机设计全流程：需求解析 → 参数识别 → 候选矩阵 → L0/L1/L2 解算 → Top10 与校验 → 完整方案。 L0 用代理模型与经验公式毫秒级广筛候选；L1 RMxprt、L2 Motor-CAD 为可选精算工具。 装完即用 —— 无需预装 RMxprt / Motor-CAD / Python，无需 license。

快速开始

# 安装（dsh 未进 PATH 时用 npx）
npx -y @deepseek-ai/dsh plugin --profile web add dsh-motor-ai-l0

# 离线自检（无需 DSH Runtime，裸 Node 即可）
node scripts/verify.mjs

标准流水线（顺序很重要）

1. motor_param_matrix —— 由功率 / 转速 / 电压生成候选参数矩阵
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 给出。

两条通道的分工（v0.2.2）

通道	触发	输出	适用
公式通道（默认）	l0Mode: 'auto' / 'formula'	效率 + 温升 + 损耗拆分 + 齿/轭磁密 + 功率因数 + 可行判定 —— 字段完整	日常排序与相对比较
代理通道（可选增强）	l0Mode: 'surrogate'	仅效率（温升/损耗/磁密不输出）	异步机效率排序的交叉参考

代理模型 v2.3.0-fixseg（在 v2.2.0 基础上用全量 6029 条真实 RMxprt 结果重训，特征扩为含 poles 的 5 维；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）自动降级 —— 不会硬给一个数。

⚠️ 代理通道可能离线 / 覆盖率 0：部分部署环境代理模型文件缺失或加载失败时，会静默降级到公式通道（字段完整、始终可用）。公式通道是「未标定默认通道」（见「已知精度边界」），其输出 confidence 现为 0.5 的明确标记值（v0.2.7 前恒为 1.0，会误导下游采信绝对值），仅代表「未标定、可排序不可绝对值采信」，不等于高置信预测；代理通道输出带逐预测 confidence（低于阈值自动降级）。经验回灌闭环（tools/feedback/experience-hub.mjs）的 shadow 若给出显著更优的影子模型，即视为触发正式重训的信号——请勿把 confidence: 0.5 的公式结果当终值。

能力边界

本版本做参数矩阵生成、物理校验、L0 估算排序、TopN 交接与回归质量门；不做 RMxprt / Motor-CAD 调用、MCP Server、Python 桥接、多目标优化。

工具

入参别名：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）

$ motor_param_matrix       { power_kw: 15, speed_rpm: 1460, voltage_v: 380, motor_type: 'induction', count: 120 }  →  120 候选
$ motor_design_validate    17 条物理校验  →  0 passed / 80 warning / 40 failed
$ motor_l0_estimate        sort_by: 'efficiency'  →  Top5，OD310 / 6 极 / η=95.17%

→ 这 5 个方案直接作为 L1（RMxprt）的入参，而不是把 120 个全丢给求解器。 完整算例、复现命令与另外两个工况（75kW 异步、200kW 高速 PMSM 反例）见 examples/。

配置

配置位于 cordis.patch.yml（查看：npx -y @deepseek-ai/dsh --profile web --dump-config）。最常用四项：

其余配置项（本地统计 usageLog；L0 运行 surrogatePath / surrogateConfidenceThreshold / maxMatrixSize / topNPreview / tempRiseRange / airGapFluxT / highSpeedRpm；脱敏回传 telemetryEnabled / telemetryEndpoint / telemetryBatchSize / telemetryIntervalSec / sessionTelemetry）见 docs/ENGINEERING.md 与本文「脱敏聚合指标回传」节。

⚠️ tempRiseRange 命名待议：它对齐 L1 max_temp 的钳位区间（°C），不是 L0 温升（K），拟改 maxTempClamp。

用量统计（本地，隐私安全）

每次工具调用向 ~/.dsh/storages/dsh-motor-ai-l0/usage.jsonl 追加一行元数据：

{"ts":"2026-09-22T06:40:12.345Z","tool":"motor_l0_estimate","ok":true,"elapsed_ms":2,"n":20,"failed":0,"sort_by":"efficiency","top_n":10}

• 只记次数 / 耗时 / 规模 / 成败，不记设计参数与结果内容 —— 行业 Know-how 不落盘
• 开关：配置项 usageLog（默认开）；所有写入静默降级，绝不影响工具调用
• 数据可自行聚合（周期 / 命中率 / 失败率），也可作为社区统计面板 （dsh-usage-statistics-panel、dsh-usage-unified 等 DSH 社区插件）的本地数据源搭配使用
• 累积的真实工况分布后续直接服务公式系数标定与代理模型训练

脱敏聚合指标回传（显式可选，默认关闭）

在本地 usage.jsonl 之上，可选地把「按工具聚合的统计量」回传到你指定的端点 （如管理端 /api/admin/dsh-plugins/<id>/usage-report）。这是显式 opt-in：

合规底线（与 DSH 生态遥测规范一致）：

• 默认全关，不配置 = 零外发（本地 usage.jsonl 照记，行为与 0.1.4 逐字节一致）
• 只回传白名单聚合统计量（调用次数 / 成败 / 耗时分布 / 规模总和 / 成功速率 / 来源版本 / 平台 OS）；绝不包含设计参数正文、结果明细（效率/温升/损耗）、提示词、工作目录、密钥
• 逐条明细只保留在本机；error 字段截断到 80 字并去换行/路径，避免夹带参数/密钥
• 回传是 fire-and-forget：网络/超时/拒绝都静默降级，绝不影响工具主流程

启用示例（cordis.patch.yml）：

telemetryEnabled: true
telemetryEndpoint: 'http://127.0.0.1:5000/api/admin/dsh-plugins/motor-ai-l0/usage-report'
telemetryIntervalSec: 300

免费额度与联网行为（默认开启，与遥测相互独立）

⚠️ 本插件有两条相互独立的「对外」通道，默认状态不同，请分别看待：

• 遥测回传（telemetryEnabled / designExperienceUpload）：默认 关闭，不配置 = 零外发（见上节）。
• 每日免费额度（freeQuotaEnabled，本节）：默认 开启，但计数与放行完全在本地完成， 后端不可达也不影响使用。

v0.5.0 语义升级（important）

闸门从「后端决定 + 断网放行」改为 「本地为准的硬闸 + 非阻塞旁路遥测」。原因是一条实测到的事故级缺陷：

旧实现 checkFreeQuota 里是 await fetch(...) + 4s 超时。一旦 commerceBackendUrl 指向一个 在中国大陆不可达的地址（实测 *.workers.dev 被 DNS 污染、TCP 443 直连超时）， 国内用户每次工具调用都要白等 4 秒才拿到放行 —— 限流没生效，延迟先炸了。

现在的行为：

• 每日 10 次硬闸（本地计数，fail-closed）：默认 10 次/天，按本地自然日重置。 计数只认本地 free-quota.json，断网也拦——否则「分发出去即失联」时闸门形同虚设。
• 非阻塞旁路遥测：若 config.commerceBackendUrl / config.backendUrl / env.DSH_BACKEND_URL 已显式配置，插件会顺手 POST /api/dsh/free-call（载荷 { plugin_id, device_id }）做旁路计数， 但这是 fire-and-forget，调用链不等待（实测后端挂死时闸门 1ms 返回）。 未配置地址 ⇒ 一个网络请求都不发，不再向 http://127.0.0.1:5000 打无意义请求。
• 后端不再决定放行：即使后端返回 allowed: false，本地未超限就照常放行（旧版会拦）。
• 与完整版共用一本账：配额文件路径 $DSH_HOME/storages/dsh-motor-ai/free-quota.json （与完整版 lib/license.mjs:52 的激活态同目录同文件），同机上 l0 与完整版不会分裂成两本。
• device_id = sha256(hostname|platform|arch).slice(0, 16)——以主机名 + 平台 + 架构派生的设备指纹， 与完整版逐字节一致，用于后端归并同一台机器的额度账。

💡 「出厂即孤岛」已不再是问题：每日 10 次闸门现在完全不依赖后端，装完即生效。 是否部署接收端只影响两件事——① 匿名使用数据（次数/成败/耗时）是否回流；② 换机后额度能否归并。

v0.5.2 P0-门1'修复：同步批量脱闸（important）

v0.5.1 的「同链只扣 1 次」用「_consumed WeakSet（key = config 对象）+ queueMicrotask 复位」实现，实测有致命盲区（scripts/_repro_syncbatch.mjs）：

v0.5.2 起「同链」判据改为显式调用链令牌（newQuotaChain() / withQuotaChain()）： 聚合入口每次调用新建唯一令牌并透传给三个子纯函数 ⇒ 整链仍只扣 1 次，而循环调用因令牌 互不相同 ⇒ 各计一次。

v0.5.1 P0-门1修复（important）

v0.5.0 的闸门只装在四个工具的 execute 上，quota_probe 实测复现了一个脱闸路径： import 直调纯函数 runL0Pipeline ×12 次，本地 free-quota.json 的 free 恒 = 0—— 脚本/CI 可零限制跑完三步链。v0.5.1 起：

• 四个纯函数入口全部过闸：runL0Pipeline / buildParamMatrix / runDesignValidate / runL0Estimate 首行即 assertFreeQuota(...)，靠一次性消费标记保证整链只扣 1 次 （探针防回归断言：一次 pipeline 调用 = +1）。 ⚠️ v0.5.1 版的「一次性消费标记」以 config 对象引用为判据，同步批量循环会脱闸； v0.5.2 起改为调用链令牌（见上节），本节其余结论不变。
• 执行侧不再 await enforceQuota：await 边界会放跑消费标记造成每次调用扣 2 次， 改为 execute 捕获 QuotaExceededError 直接回引导文案。
• 内部离线批量工具显式 bypass：experience-hub capture（作者侧 2000 次迭代采样）与 case-feedback（社区反馈聚合）传 freeQuotaEnabled: false，不计用户额度。

额度用尽时的提示（同时发给模型与用户）包含联系与升级两条路：

今日免费额度已用尽（10/10 次/天，按本地自然日重置）。

📮 联系插件制作者（使用反馈 / 问题排查 / 购买授权 / 定制开发）：
   邮箱：13546196530@163.com

📦 下载完整版 dsh-motor-ai（解锁无限次调用与完整能力）：
   1) DSH 插件市场（dshhub-market 口令市场，搜 dsh-motor-ai）
   2) npm：npm install dsh-motor-ai@next

或者：
1) 明天再用（免费额度按本地自然日自动重置）；
2) 安装完整版 dsh-motor-ai 解锁无限调用；
3) 购买授权或反馈请联系 13546196530@163.com。

如何调整：

1. 换每日上限（本地闸门）：

   DSH_FREE_DAILY_LIMIT=50      # 环境变量覆盖，默认 10
   

2. 完全关闭闸门与联网（照常使用、不限次）—— 打开 cordis.patch.yml：

   freeQuotaEnabled: false   # 关闭每日免费额度闸门（不限次、不发任何计请求）
   

   （v0.4.3 起该开关已暴露到配置；此前用户无法关闭。）

接收端部署（可选，只影响数据回流与跨机额度归并）

v0.5.0 起免费额度闸门已在本地闭环，不部署接收端功能完全不受影响。 部署的收益：匿名使用数据回流 + 换机后额度归并。

1. 官方接收端（已上线，开箱即用）：https://dsh-motor-ai-receiver.wangxuewangxue98.deno.net （Deno Deploy 2 + Deno KV，零服务器成本）。端点契约与 lib/quota.mjs 注释逐字一致：
   • POST /api/dsh/free-call —— 免费额度旁路计数（设备级）。v0.5.1 起插件随载荷上报 本地自然日 day 与本地限额 limit，接收端按同一把尺计数（缺省回落接收端默认值）； 响应 { allowed, used, remaining, limit, day }。
   • GET /api/dsh/stats —— 只读聚合统计（v0.5.1 新增）：各端点事件总数/当日数/ 当日独立设备数，不含任何设备指纹或载荷明细，供运营观测。
   • POST /api/dsh/telemetry / POST /api/dsh/experience —— 契约预留，暂无插件客户端接线 （l0 与完整版仓库均无 POST 代码；活的流量只有 free-call 旁路）。为将来接入保留。 cordis.patch.yml 默认已配置该地址；不想回传改空串即可。
2. 自建：参考实现在 dsh-motor-ai-receiver-deno（Deno Deploy + KV，境内可达）与 dsh-motor-ai-receiver（Cloudflare Worker + D1，境外可达），部署后把地址改成你的域名。

🔴 中国大陆部署者请注意：*.workers.dev 域名在境内被 DNS 污染，实测解析到 103.252.115.49 / 199.59.149.236 等黑洞 IP、TCP 443 直连超时（同网络下 registry.npmjs.org 正常）； *.vercel.app 同样被污染。 官方接收端已部署在 Deno Deploy 2：https://dsh-motor-ai-receiver.wangxuewangxue98.deno.net （*.deno.net 域名本机直连实测 200 / 1.3s，IP 69.67.170.170 未被污染；线上闸门 10+2 拒实测通过）， cordis.patch.yml 默认已指向该地址。实测可达的其它平台：*.deno.dev、render.com、 onrender.com、fly.io、railway.app。若你的用户在国内，不要把地址指向 workers.dev。 所幸 v0.5.0 起闸门已本地闭环，选不到可达后端也不会拖慢调用（旁路遥测非阻塞）。

1. 接收端无鉴权（npm pack 即可读走任何内嵌 key），故按「统计信道」标准设计（append-only + 限流 + 白名单校验）。

社区反馈（结论式，永不自动提交）

遇到「我的工况跑不出方案 / 结果明显不合理」时，可以把结论反馈给作者。 插件提供 tools/feedback/case-feedback.mjs，在你自己的机器上生成一份可直接粘贴的 issue 草稿：

import { buildCaseFeedbackDraft } from 'dsh-motor-ai-l0/tools/feedback/case-feedback.mjs'

const draft = buildCaseFeedbackDraft({
  pluginVersion: '0.2.5',
  cases: [{ label: '工况A', spec: { power_kw: 450, voltage_v: 690, speed_rpm: 985, poles: 6 } }],
})
// 粘贴到 https://github.com/wangxuewangxue98/dsh-motor-ai-l0/issues/new?template=case-feedback.yml

草稿只含三类内容：

三条硬约束：

1. 工具只返回草稿字符串，不导出 params / matrix —— 脱敏不靠过滤，靠不产出。
2. 草稿生成后强制过 10 项脱敏自检（几何/槽数/匝数/电流/效率/客户名/绝对路径/UNC/哈希/邮箱）， 命中任一项即抛错、拒绝输出。
3. 永不实现自动提交。自动上报是信任的重灾区，作者需要收到有人愿意署名的东西。

闭环承诺：反馈修复后，该工况会被匿名化纳入 benchmarks/ 回归用例，由 CI 永久保护。

提交前请看 .github/ISSUE_TEMPLATE/ —— 有问题反馈、案例反馈、 标定数据贡献三套模板。

已知精度边界

L0 物理通道目前是 v0.1 未标定版（回归质量门判定 DEBT）：6 个标定案例效率低于参考带 0.35~2.96pt，温升偏保守。根因是损耗模型尚未用 RMxprt 批量结果标定（铁损未分齿/轭、铜损缺电路约束、机械损未标定、散热筋未计）。 因此 L0 的正确用法是排序与相对比较，不是绝对值采信 —— 排序稳定性优于绝对精度。完整实算数据与标定计划见 docs/QUALITY-GATE.md。

明确不适用的工况（实测，见 examples/03）：

门控"宁可交白卷，也不给假答案"是刻意设计：level 设为 l1/l2 时插件立即抛错，绝不静默降级成 L0 结果。

文档与许可

• docs/ENGINEERING.md —— 目录结构、字段契约 Param 锁、17 条校验规则、与 Python 体系差异、工程复盘、配置全表、路线图
• docs/QUALITY-GATE.md —— 回归质量门（两道门 + divergence）、实算对照、待校准清单
• MIT © Motor-AI