在 Apple 平台用 HomeKit 与…

当需要在 iOS/iPadOS/macOS 应用中管理 HomeKit 家庭、房间、配件、特征、动作集与触发器，或把 Matter 设备接入自有生态时使用。

适用场景

解决思路

1. 在 Xcode 的 Signing & Capabilities 中为 app target 启用 HomeKit capability。
2. 在 Info.plist 中添加 NSHomeKitUsageDescription，值为用途说明字符串，例如 "This app controls your smart home accessories."。
3. 若要把 Matter 设备接入自有生态：添加 MatterSupport Extension target，并将其 principal class 设为 MatterAddDeviceExtensionRequestHandler 的子类。
4. 在 Info.plist 的 NSBonjourServices 中添加 _matter._tcp、_matterc._udp、_matterd._udp 条目。
5. 仅当调用方以编程方式提供 Matter setup payload 时，才申请并添加 com.apple.developer.matter.allow-setup-payload 权限。
6. 按框架边界选择 API：HomeKit 用于 homes、rooms、accessories、characteristics、actions、triggers；MatterSupport 用于把 Matter 接入 app 生态；AccessorySetupKit 用于选择并授权附近蓝牙或 Wi-Fi 配件；CoreBluetooth 用于交换蓝牙 GATT 数据；NetworkExtension 用于配置配件 Wi-Fi 网络。
7. 只创建一个 HMHomeManager 并在整个 app 中共享；设置其 delegate，实现 homeManagerDidUpdateHomes 后再访问 manager.homes / primaryHome；不要在该回调触发前读取 homes。
8. 实现 homeManager(_:didUpdate:) 检查 HMHomeManagerAuthorizationStatus，若包含 .authorized 则表示已获得 HomeKit 访问权限。
9. 通过 home.rooms 获取房间列表；用 home.roomForEntireHome() 获取未分配具体房间的默认房间。
10. 用 home.addAndSetupAccessories { error in ... } 调起系统 UI 发现并添加配件。
11. 遍历 home.accessories，读取 accessory.name 和 accessory.room?.name；再遍历 accessory.services，对每个 service 遍历 service.characteristics，读取 characteristic.characteristicType 和 characteristic.value。
12. 用 home.assignAccessory(accessory, to: room) { error in ... } 把配件移动到指定房间（如先找到名为 "Bedroom" 的房间）。
13. 用 characteristic.readValue { error in ... } 读取特征值，并从 characteristic.value 按类型转换，例如 as? Bool。
14. 用 characteristic.writeValue(newValue) { error in ... } 写入特征值；写前检查权限、格式、min/max/step 和允许值等 metadata。
15. 用 characteristic.enableNotification(true) { error in ... } 开启通知；在 HMAccessoryDelegate 的 accessory(_:service:didUpdateValueFor:) 中接收实时更新。
16. 创建动作集：用 home.addActionSet(withName:) 得到 HMActionSet；用 HMCharacteristicWriteAction(characteristic:targetValue:) 创建动作，再调用 actionSet.addAction(action) 加入动作。
17. 用 home.executeActionSet(actionSet) { error in ... } 执行动作集。
18. 创建定时触发器：构造 DateComponents 设置 hour/minute；用 Calendar.current.nextDate(after: Date(), matching: timeOfDay, matchingPolicy: .nextTime) 得到首次触发时间；创建 HMTimerTrigger(name:fireDate:recurrence:)，用 home.addTrigger 添加；再用 trigger.addActionSet 关联动作集，最后 trigger.enable(true) 启用。
19. 创建事件触发器：用 HMCharacteristicEvent(characteristic:triggerValue:) 定义事件，创建 HMEventTrigger(name:events:predicate:)，用 home.addTrigger 添加，再按需关联动作集并启用。
20. Matter commissioning 前先检查 MatterAddDeviceRequest.isSupported；不支持则直接返回。
21. 构造 MatterAddDeviceRequest.Topology(ecosystemName:homes:)，其中 homes 为 [MatterAddDeviceRequest.Home(displayName:)]。
22. 用 MatterAddDeviceRequest(topology:setupPayload:showing:) 创建请求并 await request.perform() 调起系统配对 UI；不预置 setup code 时 setupPayload 传 nil，showing 传 .allDevices 表示显示所有设备。
23. 若要直接提供 setup code：import Matter，把 MTRSetupPayload 作为 setupPayload 传入；此场景需要 setup-payload entitlement。
24. 过滤可发现的设备：用 MatterAddDeviceRequest.DeviceCriteria.vendorID(0x1234) 等作为 showing；用 .all([.vendorID(...), .not(.productID(...))]) 或 .any(...) 组合多个条件。
25. 为完整生态支持创建 MatterSupport Extension；由扩展处理 commissioning 回调，按需覆盖方法，但不要在覆盖中调用 super；凭据验证、房间选择、配置、commissioning、网络关联的覆盖可参考 references/matter-commissioning.md#advanced-matter-extension-handler。
26. 在 home 上设置 HMHomeDelegate，以接收配件和房间变化。
27. 在 accessory 上设置 HMAccessoryDelegate，以接收 characteristic 更新。
28. 在所有 completion handler 中处理 error。
29. Matter extension handler 实现 commissionDevice(in:onboardingPayload:commissioningID:)。
30. 发布前用 HomeKit Accessory Simulator 测试 action sets。
31. 触发器创建后必须调用 trigger.enable(true)。

适用边界 · 注意事项

• 需要把 Matter 设备接入自有生态时，不要使用 HomeKit 的 setup 流程，应使用 MatterAddDeviceRequest 加配置好的 MatterSupport 扩展。
• 需要选择或授权附近蓝牙/Wi-Fi 配件、交换蓝牙 GATT 数据、配置配件 Wi-Fi 网络时，应分别用 AccessorySetupKit、CoreBluetooth、NetworkExtension，而不是 HomeKit。
• 设备不支持 Matter（MatterAddDeviceRequest.isSupported 为 false）时，不要执行 Matter commissioning。