---
name: huawei-pr
description: Standardize pull request titles and descriptions for the ha-huawei-smarthome repository. Use when preparing, opening, or updating a PR for this project.
metadata:
  short-description: Huawei SmartHome PR format and checks
---

# Huawei SmartHome PR 规范

用于在本仓库创建或更新 PR，统一标题、正文和验证信息。先检查 PR 实际 diff，再按变更类型填写；不要声称未执行的验证，也不要为满足格式要求而扩大代码改动。

## 标题

使用 Conventional Commit 前缀：

```text
<type>(可选范围): <简短摘要>
```

常用类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。范围可用产品 ID 或代码层，例如 `fix(100z): ...`、`feat(mqtt): ...`。摘要使用中文或英文均可，保持简短、具体；不要使用含糊标题、emoji、机器人名称或把多个无关事项塞进一个标题。

## 正文

正文使用中文，通常按以下结构编写：

```markdown
## 变更内容
- 说明改了什么以及解决什么问题。

## 验证
- 写明实际运行的命令和结果；未运行时说明原因。

## 关联
- Closes #123
```

`关联` 仅在该 PR 完整解决问题时使用 `Closes #123`；若只是相关或部分处理，写 `Related to #123`。没有关联 issue 时省略该节。

按需添加 `兼容性影响`，说明实体变化、平台行为、配置或存储迁移等实际影响。没有影响时省略，不要填充泛化的“无影响”。

## 产品实现边界

- 单品的服务映射、字段解释、枚举、缩放、命令 payload 和状态行为必须写在该产品自己的 `device_adapters/prod_<prodId>.py` 中。不要把单品行为放进框架层、实体工厂或跨产品共享模块。
- 相似的型号、服务名或字段不代表协议行为相同。本项目要求每个 `prodId` 独立实现并硬编码，不接受为了相似单品提取公共产品行为、基类或自动推断规则。可以使用框架已有的中性接口，但不能借此合并单品协议逻辑。
- 只有框架缺少真正通用的基础能力时才修改框架。如果某个单品因此无法实现，将框架能力和该单品适配拆成不同 PR；在适配器 PR 中关联框架 PR，并说明依赖关系与合并顺序。不要把框架改造和单品适配混在一个 PR。

## 功能覆盖取舍

- 不要求完整复刻产品的所有功能；应尽可能覆盖该单品在 Home Assistant 中有实际价值的基本能力。
- 按用户可见价值和协议语义选择实体，不以 Profile 服务数量或实体数量作为覆盖目标。优先处理设备的主要控制和核心状态。
- 不建议加入重复表达同一能力、纯内部信息、冗余管理项或对日常使用没有实际价值的功能。遇到语义不确定或缺少可靠证据的字段时，不猜测投影；必要时在 PR 中简要说明未纳入的主要功能及原因。
- PR 正文概述已实现的基本能力即可，不宣称功能完整，也不需要逐项罗列所有未实现的 Profile 服务。

## 产品适配器变更

适配器 PR 需增加设备验证信息，便于维护者区分实测与推断：

```markdown
## 设备验证
- prodId / 型号：
- 状态读取：已实测 / 未实测（简述范围）
- 控制命令：已实测 / 未实测（简述范围）
- 尚未验证：
```

只陈述实际完成的设备验证。依据 Profile 或相似产品推断的行为应明确标为未实测；不适用的项目可省略。新适配器还需同步更新 `docs/supported-devices.md`。不要在 PR 正文粘贴完整 Profile、原始日志、账号凭据、令牌或设备隐私标识。

## 提交前核对

- PR 目标分支为 `master`，标题符合上述格式。
- Diff 聚焦于一个逻辑变更；正文与实际 diff 一致。
- 验证信息如实，包括未运行验证及原因；本规范不要求仅为 PR 格式额外新增测试文件。
- 涉及新产品适配时，列明 `prodId`、真机验证状态，并更新支持设备清单。
- 没有混入凭据、个人数据、完整 Profile 或未脱敏日志。

创建 PR 前确认用户已要求推送或开 PR；本技能只规范内容，不授予额外的提交、推送或发布权限。