ha-integration-reviewer

niracler's avatarfrom niracler

严格的 Home Assistant 集成代码审查。用于提交 PR 前的全面检查，包括 Quality Scale 规则验证、代码风格、Config Flow、测试覆盖和文档。当用户说"审查我的 HA 集成"、"检查我的代码是否符合 HA 规范"、"帮我 review 一下准备提交的代码"时触发。

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 26, 2025
[Code Review]

When & Why to Use This Skill

The HA Integration Reviewer is a specialized Claude skill designed for rigorous code analysis of Home Assistant integrations. It automates the pre-Pull Request (PR) checklist by validating code against the official Quality Scale, ensuring strict adherence to Home Assistant's coding standards, asynchronous programming patterns, and comprehensive test coverage requirements. By dynamically fetching the latest developer documentation and rules from GitHub, it provides real-time, accurate feedback to help developers meet the high standards of the Home Assistant core repository.

Use Cases

  • Pre-submission PR Audit: Automatically review integration code before submitting to the home-assistant/core repository to identify violations and reduce manual review cycles.
  • Quality Scale Leveling: Evaluate existing integrations against the Home Assistant Quality Scale (Bronze to Platinum) and receive actionable suggestions to upgrade the integration's rank.
  • Asynchronous Code Optimization: Detect blocking I/O operations in the event loop and ensure proper implementation of async/await patterns and task gathering.
  • Config Flow & UI Validation: Verify that unique_id settings, translation strings, and configuration flows comply with the latest UI/UX standards for a seamless user experience.
  • Test Coverage Enforcement: Analyze test suites to ensure they meet the mandatory 95% coverage threshold using modern fixtures and snapshot testing techniques.
nameha-integration-reviewer
description严格的 Home Assistant 集成代码审查。用于提交 PR 前的全面检查，包括 Quality Scale 规则验证、代码风格、Config Flow、测试覆盖和文档。当用户说"审查我的 HA 集成"、"检查我的代码是否符合 HA 规范"、"帮我 review 一下准备提交的代码"时触发。

HA Integration Reviewer

以最严格的 Home Assistant Reviewer 视角审查集成代码。

审查流程

1. 确定审查范围

# 获取待审查的文件（ha-core 使用 dev 分支）
git diff --name-only HEAD~1  # 最近一次提交
git diff --name-only dev     # 与 dev 分支的差异（ha-core 主分支）

或用户指定的目录/文件。

2. 并行启动检查 Agent

使用 Task 工具并行启动多个专项检查，详见 review-workflow.md：

Agent 1: Quality Scale 规则检查
Agent 2: 代码风格检查
Agent 3: Config Flow 检查
Agent 4: 测试覆盖检查
Agent 5: 文档与 Manifest 检查

并行启动示例:

Task(subagent_type="general-purpose", prompt="检查 Quality Scale 规则...")
Task(subagent_type="general-purpose", prompt="检查代码风格...")
Task(subagent_type="general-purpose", prompt="检查 Config Flow...")

3. 动态获取最新规范

不要使用过时的静态文档，每次审查时动态获取：

Quality Scale 规则

WebFetch: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/core/integration-quality-scale/rules/{rule_name}.md

编码规范

WebFetch: https://raw.githubusercontent.com/home-assistant/core/dev/.github/copilot-instructions.md

开发者文档

使用 Context7 获取最新的 Home Assistant 开发者文档。

4. 参考其他集成

查看 ha-core 中类似集成的实现：

gh api repos/home-assistant/core/contents/homeassistant/components/{integration_name}

5. 汇总审查报告

输出结构化报告，包含：

  • 每个检查维度的结果
  • 具体问题及其文件位置
  • 修复建议及优先级

检查清单速查

详见 common-issues.md，包含：

  • 代码风格常见问题
  • 日志规范
  • 异常处理
  • 实体与设备
  • Config Flow
  • 服务注册
  • 文档规范

Quality Scale 验证要点

Done 规则

验证代码是否真正符合规则要求，而非仅仅标记为 done。

Todo 规则

检查是否接近完成，提示用户考虑完成以提升 Quality Scale 等级。

Exempt 规则

评估豁免理由是否合理，是否真的不适用于该集成。

关键审查标准

异步编程

  • 所有外部 I/O 必须 async
  • 禁止在事件循环中阻塞
  • 使用 gather 替代循环中的 await

异常处理

  • 缩小 try 块范围
  • 使用 ServiceValidationError 处理输入错误
  • 使用 HomeAssistantError 处理通信故障

Config Flow

  • unique_id 正确设置
  • 100% 测试覆盖
  • UI 文本规范（避免 "Click"，加粗按钮标签）

测试

  • 位于 tests/components/{domain}/
  • 使用 fixture 和 snapshot testing
  • 覆盖率 >= 95%