homeassistant-dashboard-designer

Home Assistant 仪表盘设计器

将仪表盘设计成系统：结构可预测、模板可复用、偏差最小化。仅将 Stitch 视为灵感来源；请将设计转换为安全的 Lovelace YAML。

主要输入：自然语言（默认）

你可以用自然语言提供指导。此技能必须在内部推断结构化意图（仪表盘意图、视图名称、实体映射、约束），同时遵循设计系统，并在 Home Assistant MCP 可用时验证实体和服务。

自然语言中建议至少包含以下信息：

• 要更改什么（添加／移除／重构）以及原因（目标）。
• 要在哪里更改：config/dashboards/** 下的确切视图／局部文件路径。
• 你关心的任何约束：桌面端／移动端列数、图表时间范围偏好、“不要改动”的模板／区域。

如果缺少上述任何信息，请提出有针对性的澄清问题（不要要求提供完整的“意图块”）。

自然语言请求示例：

• “重构 config/dashboards/infrastructure/views/06_mariadb.yaml，使其符合其他 Infrastructure 视图使用的 button-card 优先系统。保留相同实体，不添加新模板；桌面端 4 列／移动端 2 列。”

可选输入：结构化意图（允许，但非必需）

如果用户提供结构化意图，请接受。不要要求用户提供。

dashboard_type: infra  # infra|home|energy|environment
view_name: "Infrastructure Overview"
target_paths:
  dashboard_yaml: "config/dashboards/infrastructure/dashboard.yaml"
  view_yaml: "config/dashboards/infrastructure/views/07_docker_containers.yaml"
entities:
  - name: "Proxmox01"
    cpu: "sensor.proxmox01_cpu"
    memory: "sensor.proxmox01_mem"
constraints:
  desktop_columns: 4
  mobile_columns: 2
notes:
  - "Preserve existing templates; minimize diff."

如果要更新现有视图，且上下文中无法明确判断，请询问：

• 哪个视图文件（单个视图字典）是事实来源？
• 有没有“不要改动”的区域／模板？
• 有没有必须保留的备用卡片？

输出约定（始终遵守）

• 一个有效的 Lovelace 视图（单个视图字典）
• 确定性的排序（卡片／区域顺序稳定）
• 区域注释（简短且一致）
• 卡片样式差异为零（不使用一次性样式；使用模板／片段）
• 明确说明使用备用卡片的理由（在备用卡片旁的 YAML 注释中说明）

卡片优先级模型

优先尝试第 1 层。只有在第 1 层无法安全实现需求时，才使用第 2 层。

第 1 层（主要）：

• custom:button-card（结构＋图块＋标题＋容器）
• card-mod（仅用于共享／全局润色；可使用共享片段）
• custom:flex-horseshoe-card（单指标径向遥测）
• custom:mini-graph-card（单指标趋势）

第 2 层（备用，必须在注释中说明理由）：

• entities、markdown、history-graph、conditional
• iframe（最后手段）

布局规则（硬性约束）

• 允许的布局容器：grid、vertical-stack
• 最大嵌套深度：2（示例：grid -> vertical-stack -> 卡片）
• 网格单元格内不得使用 horizontal-stack（优先增加网格列数，或使用 vertical-stack）
• 不得自由定位
• 不得在 card-mod 中嵌入布局逻辑
• 对于 type: sections 视图中的密集图块列表，外层面板应保持全宽（column_span: 4），并使用 custom:layout-card 使内层图块网格能够响应式布局（除非用户另有要求，否则桌面端为 4 列／移动端为 2 列）。
• 在 type: sections 视图中，紧接顶部芯片／徽标下方的第一个区域必须是全宽容器（column_span: 4），且只包含一个包装卡片；该卡片还需设置 grid_options.columns: full，以避免出现狭窄列的空白。
• 移除／移动内容后，向上整合布局：不得留下空白区域、空占位符或刻意稀疏的行，除非用户明确要求留白。

注意：如果仓库／视图使用 Home Assistant type: sections，请将 sections 视为顶层结构，并在每个区域内遵循相同的容器规则（区域中只能包含 grid／vertical-stack 卡片及其子项）。

设计系统规则（实现规范）

Button Card（主要渲染器）

• 使用 custom:button-card 作为结构基元。
• 必须使用模板。不得内联各卡片的 styles:；样式应放在集中管理的模板／片段中。
• 通过变量或模板 JS 实现逻辑（避免在各卡片中重复逻辑）。

card-mod（样式约束层）

• 仅用于共享／全局的细节优化：
  • 统一内边距
  • 控制边框圆角
  • 去除阴影
  • 统一排版
• 不得设置特定实体的样式
• 不得逐卡片尝试不同的视觉效果

Flex Horseshoe Card

• 每张卡片仅展示一个主要指标。
• 明确设置颜色阈值。
• 不得混用单位。

Mini Graph Card

• 每个图表仅展示一个指标。
• 每个仪表板使用一致的时间范围。
• 图例应尽量精简（仅在必要时显示）。

模板架构（必需）

• 视图只能引用模板（对于 custom:button-card：每个实例都必须指定 template:）。
• 模板接受变量；视图传入变量。
• 除非有明确指示，否则不得创建新模板。

检查仓库实际情况（重要）：

• 如果仓库已有成熟模板（例如，Infrastructure 使用 bearstone_*），则使用现有模板。
• 如果规范要求的“必需模板类别”不存在，请映射到最接近的现有模板并指出差距，或请求明确许可后再添加模板。

Stitch MCP（仅用于获取灵感）

仅将 Stitch 用于了解：

• 视觉层级（标题、分组、密度）
• 间距节奏（内边距／间隙）
• 分组模式（面板、区块）

切勿将 Stitch 的输出视为实现代码。

向 Stitch 提示时，须原样包含以下约束：

Grid-only layout. No absolute positioning. No JS frameworks. No custom HTML/CSS outside card-mod.
Card types limited to: custom:button-card, card-mod, custom:flex-horseshoe-card, custom:mini-graph-card, and HA core fallback cards only if unavoidable.
Max layout nesting depth: 2. No horizontal-stack inside grid cells.

可选 Stitch 交接（轻量桥接）

仅当用户明确要求视觉构思、布局探索或多个方案时使用。

• 触发 Stitch 流程：
  • 用户要求获取重新设计灵感、多个方案或多个视觉方向。
• 跳过 Stitch 流程：
  • 用户要求直接重构／更新仪表板，且无需构思。
• 前提条件：
  • Stitch 仅用于构思层级／间距／分组。
  • 切勿将 Stitch 输出复制为实现代码。
  • 最终实现仍须遵循此技能中所有允许使用的卡片／布局规则。

交接产物（仅限摘要，不导出代码）：

stitch_intent:
  layout_pattern: "<grid and grouping pattern to translate>"
  section_hierarchy: "<header/panel/section ordering>"
  density_target: "<compact|balanced|spacious>"
  cards_to_translate:
    - "<visual card concept mapped to allowed Lovelace card types>"

翻译要求：

• 仅将 stitch_intent 转换为获准使用的 Lovelace 结构（grid、vertical-stack，优先使用 Tier 1 卡片）。
• 将任何不受支持的 Stitch 概念重新映射到符合要求的卡片／容器；需要使用 Tier 2 时，须在文中说明回退选择。

Stitch 不可用时的回退行为：

• 使用此技能的设计系统和规则继续手动构思。
• 明确说明降级模式（“Stitch 不可用；继续手动规划层级／密度”）。
• 不得因 Stitch 不可用而阻碍仪表板工作。

工作流（按此顺序执行）

1. 对此仓库使用直接更新模式：
   • 直接编辑生产 YAML（此技能工作流中不使用暂存的仪表盘副本）。
   • 尽量减少差异，并在重启/重新加载 HA 前完成验证，以确保回滚安全。
2. 编辑前，读取目标仪表盘/视图/局部文件/模板及其包含的目标：
   • 确认确切的源视图/局部文件/模板文件。
   • 确认引用的 !include 文件/目录存在且属于处理范围。
3. 根据用户请求和现有仪表盘上下文确定意图：infra（NOC）、home、energy 或 environment。每个视图只保留一种意图。
4. 编辑前验证实体和服务：
   • 优先使用 Home Assistant MCP 验证实时实体/服务（若可用则必须使用）。
   • 写入 YAML 前，在工作笔记中记录 MCP 验证步骤。
   • 如果 MCP 不可用，请用户确认实体 ID 和服务（不要猜测）。
5. 在约束下拟定布局：顶层使用 grid，可选用 vertical-stack 分组。
   • 如果使用 Stitch，先概述 stitch_intent，并将其视为此步骤的参考输入。
   • 移除内容后，将卡片/区块向上重排，消除空隙并减少空行。
6. 优先使用 Tier 1 卡片；复用现有模板；避免一次性样式。
7. 如果必须使用后备卡片，添加行内注释，说明 Tier 1 无法满足要求的原因。
8. 按以下顺序验证：
   • 运行 pwsh -NoProfile -File tools/validate_dashboards.ps1。
   • 运行 pwsh -NoProfile -File tools/ha_ui_smoke.ps1。
   • 如果可用，运行 Home Assistant 配置验证（ha core check 或 homeassistant --script check_config）。
   • 对每个已更改的视图文件，运行此技能中的 scripts/validate_lovelace_view.py。
9. 失败处理：
   • 如果无法满足要求：说明违反的规则，并提出符合要求的替代方案。
   • 如果验证失败：停止，展示错误输出，并提出修正后的 YAML。不要留下无效配置。

示例流程：

• 用户请求重新设计灵感 -> 使用所需约束进行 Stitch 构思 -> 概述 stitch_intent -> 转换为 Lovelace 安全的 YAML -> 运行验证检查。

参考资料

• 需要完整约束集和仓库特定映射说明时，请阅读 references/dashboard_rules.md。

Home Assistant MCP 验证（可用时必须执行）

编写 Lovelace YAML 前，确认：

• 每个 entity:（以及通过变量引用的任何实体）均存在。
• 计划调用的每项服务均存在，且负载结构正确（尤其是 service_data）。

启用 Home Assistant MCP 时，请使用它来：

• 列出/确认实体（避免 sensor.foo_bar 与 sensor.foobar 之类的拼写错误）。
• 确认仪表盘卡片引用的实体确实存在。
• 在提交 YAML 更改前验证服务名称和字段。

如果 MCP 未启用或无法访问，请停止并询问缺少的实体/服务 ID，不要凭空编造。