ha-integration-reviewer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HA Integration Reviewer

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

Review integration code from the perspective of a strict Home Assistant Reviewer.

Prerequisites

Tool	Type	Required	Install
git	cli	Yes	`brew install git` or git-scm.com
gh	cli	No	`brew install gh` then `gh auth login` (for referencing other integrations)
Context7 MCP	mcp	No	`npx -y @upstash/context7-mcp` — add to Claude Code MCP settings (for HA developer docs)

Do NOT proactively verify these tools on skill load. If a command fails due to a missing tool, directly guide the user through installation and configuration step by step.

Tool	Type	Required	Install
git	cli	Yes	`brew install git` or git-scm.com
gh	cli	No	`brew install gh` then `gh auth login` (for referencing other integrations)
Context7 MCP	mcp	No	`npx -y @upstash/context7-mcp` — add to Claude Code MCP settings (for HA developer docs)

Do NOT proactively verify these tools on skill load. If a command fails due to a missing tool, directly guide the user through installation and configuration step by step.

审查流程

Review Process

1. 确定审查范围

1. Define Review Scope

bash

undefined

bash

undefined

获取待审查的文件（ha-core 使用 dev 分支）

git diff --name-only HEAD~1 # 最近一次提交 git diff --name-only dev # 与 dev 分支的差异（ha-core 主分支）


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

git diff --name-only HEAD~1 # 最近一次提交 git diff --name-only dev # 与 dev 分支的差异（ha-core 主分支）


Or directories/files specified by the user.

2. 并行启动检查 Agent

2. Launch Inspection Agents in Parallel

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

其他 Agent 环境：以下检查相互独立，可按顺序依次执行。

text

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

Quality Scale 验证 - 读取 quality_scale.yaml，验证 done 规则
代码风格检查 - 对照 copilot-instructions.md
Config Flow 检查 - 验证 unique_id 和测试覆盖
测试覆盖检查 - 确认 >= 95%
文档检查 - 验证 strings.json 和 README

所有检查完成后，汇总结果生成统一报告。

Use the Task tool to launch multiple specialized inspections in parallel, see review-workflow.md for details.

Other Agent Environments: The following inspections are independent of each other and can be executed sequentially.

text

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

Quality Scale Validation - Read quality_scale.yaml and verify done rules
Code Style Check - Compare against copilot-instructions.md
Config Flow Check - Validate unique_id and test coverage
Test Coverage Check - Confirm coverage >= 95%
Documentation Check - Validate strings.json and README

After all inspections are completed, summarize the results to generate a unified report.

3. 动态获取最新规范

3. Dynamically Obtain the Latest Specifications

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

Do NOT use outdated static documentation, dynamically obtain the latest specifications for each review:

Quality Scale 规则

Quality Scale Rules

text

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

其他环境：
curl -sL <URL>
作为替代。

text

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

Other Environments: Use
curl -sL <URL>
as an alternative.

编码规范

Coding Specifications

text

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

其他环境：
curl -sL <URL>
作为替代。

text

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

Other Environments: Use
curl -sL <URL>
as an alternative.

开发者文档

Developer Documentation

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

若未安装 Context7 MCP，从 GitHub 仓库直接获取：
curl -sL https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/...

Use Context7 to obtain the latest Home Assistant developer documentation.

If Context7 MCP is not installed, obtain directly from the GitHub repository:
curl -sL https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/...

4. 参考其他集成

4. Reference Other Integrations

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

bash

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

Check implementations of similar integrations in ha-core:

bash

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

5. 汇总审查报告

5. Summarize Review Report

输出结构化报告，包含：

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

Output a structured report including:

Results of each inspection dimension
Specific issues and their file locations
Fix suggestions and priorities

检查清单速查

Quick Reference for Inspection Checklist

详见 common-issues.md，包含：

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

See common-issues.md, which includes:

Common code style issues
Log specifications
Exception handling
Entities and devices
Config Flow
Service registration
Documentation specifications

Quality Scale 验证要点

Quality Scale Verification Key Points

使用 quality-scale-rule-verifier Agent

Use quality-scale-rule-verifier Agent

ha-core 仓库提供了专门的 Quality Scale 验证 agent：

位置:

repos/ha-core/.claude/agents/quality-scale-rule-verifier.md

调用方式:

text

undefined

The ha-core repository provides a dedicated Quality Scale verification agent:

Location:

repos/ha-core/.claude/agents/quality-scale-rule-verifier.md

Invocation Method:

text

undefined

验证单个规则

"Check if the {integration} integration follows the {rule_name} rule"

验证整个等级

"Verify that this integration reaches the {tier} quality scale"


该 agent 会动态获取规则文档并验证实现，比静态检查更准确。

"Verify that this integration reaches the {tier} quality scale"


This agent dynamically fetches rule documents and validates implementations, which is more accurate than static checks.

Done 规则

Done Rules

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

Verify whether the code truly complies with the rule requirements, not just marked as done.

Todo 规则

Todo Rules

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

Check if they are close to completion, and prompt users to consider completing them to improve the Quality Scale tier.

Exempt 规则

Exempt Rules

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

Evaluate whether the exemption reason is reasonable and if the rule is truly not applicable to the integration.

关键审查标准

Key Review Standards

异步编程

Asynchronous Programming

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

All external I/O must be async
Blocking operations in the event loop are prohibited
Use
```
gather
```
instead of await in loops

异常处理

Exception Handling

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

Narrow the scope of try blocks
Use
```
ServiceValidationError
```
to handle input errors
Use
```
HomeAssistantError
```
to handle communication failures

Config Flow

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

unique_id is set correctly
100% test coverage
UI text specifications (avoid "Click", bold button labels)

测试

Testing

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

Located in
```
tests/components/{domain}/
```
Use fixture and snapshot testing
Coverage >= 95%