WashData 的 Playground（试验场）是 Home Assistant 智能插座家电监控集成内置的参数模拟与自动优化工具：在不动任何实时设置的前提下，用真实检测引擎回放历史洗衣周期，帮你"先试再改"。无论你想调优 off_delay、验证 min_power 门槛，还是自动扫描出最优参数值，Playground 都能让你在虚拟沙盒里看到确定性的结果，再一键应用到设备，彻底告别"改完参数才知道对不对"的踩坑体验。

为什么需要参数沙盒：直接改参数的三大风险

WashData 通过监测智能插座的功率曲线来识别洗衣机的启动、结束和程序匹配。它依赖min_power（最小功率门槛）、off_delay（关机延迟）、start_threshold_w（启动阈值）等参数，而这些参数和每台家电、每个插座的特性强相关。直接在线修改参数的常见痛点：

• 试错成本高：参数设错可能导致周期被拆成两段、漏检、或迟迟不结束，只能等下一次真实洗衣才能验证；
• 影响面看不清：off_delay调大一点，对最近 20 个周期分别是什么后果？肉眼无法评估；
• 最优值不可知：参数之间互相耦合，手动调参只能一次动一个，找不到全局最优。

Playground 的设计目标是字节级保真：回放时驱动的是和线上完全相同的CycleDetector、Stage 1–5 匹配器、进度计算与通知判断逻辑（源码见 playground.py，入口函数 simulate_cycle_detail）。官方文档的完整技术参考见 docs/internal/reference/09-playground.md。它有三条安全承诺：

1. 只读：不触碰 HA 状态、不发事件、不推送通知、不写入任何存储；
2. 编辑隔离：面板里的修改只存在于 Playground，直到你显式"发布（publish）"才写入设备设置；
3. 永不崩溃：所有入口函数出错时返回{"error": ...}标记，而不是让面板崩溃。

Playground 是什么：三种模式一张图看懂

Playground 面板由三部分组成：顶部是参数控制面板（初始值直接读取设备当前实时设置，带"与实时设置一致/有 N 项改动"提示），中部是周期功率图（可悬停读数、缩放、拖动平移），底部抽屉提供跨周期批量模式：

单周期模拟：回放一条功率曲线看完整时间线

在 Simulate 模式下，选中一条历史周期点击运行，Playground 会把它的所有功率读数按生产节奏逐条喂给真实检测器，并在回放结束后追加一段合成静默尾部（0W 读数，跨度为max(off_delay, min_off_gap) × 1.5 + 300s），让"自然结束"有机会触发。

你会得到四样东西（对应 finalize 的输出结构）：

• series 时间线：每一步的状态、功率、进度、剩余时间、阶段、匹配置信度、预计能耗与费用；
• events 事件日志：状态切换（OFF->STARTING）、周期检测、匹配确认（match_commit）、通知触发等类型化事件；
• alerts 告警清单：例如false_end（一个周期被拆成多段）、ambiguous（两个程序得分接近）、overrun/underrun（时长超过典型值 150% 或不足 55%）；
• outcome 结论：是否检测成功、终止原因、匹配到的 profile、置信度、超时长比例。

一个实用场景：怀疑stop_threshold_w设得太低导致烘干尾段识别异常，只需在面板把它调高再重跑同一周期，立刻看到结束点是否前移、告警是否消失。面板还会提示"当前使用你编辑的设置 vs 当前实时设置"（pg_override_active），对比一目了然。

历史回放模式：参数改动的前后对比（A/B diff）

单周期模拟看个例，Test on history看整体。它会批量回放你最近的周期（默认 20 条，上限 50 条），每一行给出：检测是否成功、匹配到的 profile、是否匹配正确（与标签比对）、终止原因、实际时长 vs 记录时长、告警代码列表，并附一个汇总条："X/Y 检测到 · Z 条匹配正确"。

关键在于前后对比：当你在参数面板里修改了任何值，引擎会额外跑一遍"未修改"的基线，并输出三类差异（见 _diff_rows）：

• newly_correct：原来没匹配对、现在匹配对了的周期 —— 改参数带来的收益；
• regressed：原来对、现在错的周期 —— 必须警惕的退化；
• end_timing_changed：终止原因变化或结束时刻偏移超过 60 秒的周期。

判断逻辑很直白：新增收益 > 退化数量，且 end_timing 变化都在可接受范围，这个参数改动才值得发布。

自动优化模式：参数扫描如何找到最优值

Optimize（参数扫描）是 Playground 的杀手锏。你只需选一个参数（如off_delay）和一个目标指标，它会在一组候选值上（每轴最多 20 个值）对最近周期批量重放，画出指标曲线（一维）或热力图（二维双参数），并自动标出最佳值与当前值的位置。

五个内置目标指标及其方向（定义见 objective_metric）：

例如：洗衣机在两次洗衣之间总有短暂低功率，导致周期被错误断开 —— 选min_off_gap+false_end_rate目标，看曲线哪里出现拐点，把拐点右侧的值设为新参数即可。面板会明确提示"在你显式应用之前，什么都不会改变"，并给出"应用最佳值"的确认弹窗。

如何把模拟结果安全发布到实时设置

这是新手最容易犹豫的一步，机制其实很克制：

1. 发布范围有白名单：只有真正对应持久化设置的参数（检测类参数 + 两个时长比例）能被写回设备设置（见 PUBLISHABLE_SETTING_KEYS）；
2. 沙盒专属参数不会污染配置：Stage 2–4 的匹配评分权重（corr_weight、dtw_bandwidth、dtw_blend等 11 个旋钮）只是沙盒专用覆盖项，供你观察"如果匹配器权重不同会怎样"，它们永远不会被写入设备的entry.options；
3. 逐项确认：面板对"发布单个值"和"发布整组修改"都有二次确认文案（如"将 off_delay = 300 保存到此设备设置？"），你可以选择只发布验证过的那一项。

另外，面板支持命名预设：把一组验证过的参数组合存为 preset，之后换设备、或参数被建议系统覆盖后，一键恢复整套配置。

实战清单：什么症状该打开 Playground

结合内置的调参建议系统（设置页旁会显示带灯泡图标的调优建议），下面这份对照表帮你快速定位：

💡提示：长周期（如 4 小时洗碗机，约 2800 个采样点）的模拟会作为后台分块任务执行，进度条显示"Step X / Y"，且断连后可重新挂接查看结果，不会卡死面板。

常见问题 FAQ

Q1：Playground 的模拟和真实运行结果一定一致吗？一致。它复用的是生产代码路径——同一个检测器类、同一套匹配与进度函数，唯一的区别是数据来自存储的历史读数。这也是它能作为调参依据的根本原因（详见 09-playground.md 的"字节级保真"契约）。

Q2：模拟会不会发送通知或改变家电状态？不会。所有通知（开始/结束/提前提醒/里程碑）只作为events事件记录在时间线里，包括"该通知会因免打扰时段被拦截"也会如实标注。

Q3：Optimize 的"最佳值"可以直接相信吗？建议结合 Test on history 的 diff 二次确认：最佳值在目标指标上最优，但可能造成其他周期结束时刻偏移。两个模式都满意后再发布。

Q4：面板显示"重启 Home Assistant 以启用 Playground"？集成刚加载完成时 WebSocket 命令可能尚未注册，重启 HA 即可，属于一次性提示。

总结

WashData Playground 把"改参数"从赌博变成了科学实验：Simulate 看单周期细节 → Test on history 看群体前后对比 → Optimize 自动扫描出候选最优 → 逐项确认后才发布。核心源码在 custom_components/ha_washdata/playground.py，技术细节可查阅 docs/internal/reference/09-playground.md。记住它的安全底线——"在你明确应用之前，此处任何操作都不改动实时数据"——你就可以放心大胆地在沙盒里试参数了。