Skills
skills/developer.tuya.com/照明 Matter 协议专家

照明 Matter 协议专家

SKILL.md

Skills: LampMatterSkills

照明 Matter 协议专家

提示：matter-kit 自 @ray-js/panel-sdk@1.15.0 开始加入，当前仅支持照明品类设备。

🧠 专家知识定位

精通照明类 Matter 设备面板的 DP 功能点映射与拦截器实践，熟悉标准协议与 Matter 协议双向转换及常见场景的工程化落地。

📚 知识库覆盖范围 (Knowledge Scope)

  • matter-kit 接入与初始化：createMatterKit、默认拦截器使用
  • 标准 DP 与 Matter DP 映射：switch/brightness_control/color_temp_control/hs_color_set 的双向转换
  • 工具与 Hooks：Matter 路数判断、白光能力检测、色温/亮度转换、原始色温展示
  • 与 dp-kit 协同：拦截器顺序、颜色协议处理、状态即时更新

🛠 AI 如何调用此知识

安装本技能后，AI 将具备以下推理与落地能力：

  • 给出符合照明品类的 matter-kit 集成代码模板（含 SmartDeviceModel options/interceptors）
  • 根据 matter 设备 dpSchema 自动判断设备路数与白光能力，并生成 UI/逻辑建议
  • 解释并输出标准 DP ↔ Matter DP 的上报/下发转换策略与公式
  • 指导 matter-kit 与 dp-kit 的协同拦截器顺序与配置，避免状态不一致与精度损失
  • 提供颜色数据（HSV）在 Matter 面板下的正确来源组合与解析方案

🧯 何时使用本技能（When to Use This Skill）

  • 你的面板需要接入 Matter 照明设备，但希望继续以“标准 DP”编码。
  • 同一工程需同时兼容非 Matter 与 Matter 设备，避免双协议逻辑分叉。
  • 需要可靠的亮度/色温映射与 HSV 解析，减少展示精度损失。
  • 需要判断设备路数与白光能力以驱动 UI/场景数据集。
  • 与 dp-kit 协作，需要明确拦截器顺序与乐观更新配置，避免循环与卡顿。
  • 在群组或复杂组合场景下，需遵循 Matter 组合限制并给出 UI 提示。

建议：使用 @ray-js/panel-sdk >= 1.15.0，生产环境关闭 debug，并按拦截器顺序“dp-kit 在前、matter-kit 在后”配置。

🚀 接入指南（核心片段）

  • 生成 matter-kit：
import { SmartDeviceModel, createMatterKit } from '@ray-js/panel-sdk';
import { defaultSchema } from '@/devices/schema';

type SmartDeviceSchema = typeof defaultSchema;

export const matterKit = createMatterKit({
  debug: false,
});

const options = {
  interceptors: matterKit.interceptors,
};

export const devices = {
  common: new SmartDeviceModel<SmartDeviceSchema>(options),
};
  • 使用标准 DP（说明：代码里按标准 DP 读取与下发，Matter 拦截器层自动完成映射）：
import React from 'react';
import { View } from '@ray-js/ray';
import { useProps, useActions } from '@ray-js/panel-sdk';

export default function Home() {
  const power = useProps(p => p.switch_led);
  const bright = useProps(p => p.bright_value);
  const temp = useProps(p => p.temp_value);
  const colour = useProps(p => p.colour_data);
  const actions = useActions();

  return (
    <View>
      <View onClick={() => actions.switch_led.toggle()}>开关: {power ? '开' : '关'}</View>
      <View onClick={() => actions.bright_value.set(500)}>亮度: {bright}</View>
      <View onClick={() => actions.temp_value.set(600)}>色温: {temp}</View>
      <View onClick={() => actions.colour_data.set('012502ad02ee')}>颜色: {colour}</View>
    </View>
  );
}

📦 API 概览（精要）

  • createMatterKit(options?: CreateMatterKitOptions) => CreateMatterKitResult
  • CreateMatterKitResult 关键字段：
    • interceptors：默认拦截器配置（initDevInfo/initDpState/publishDps 等）
    • resolveMatterDevInfo：Matter schema → 标准 schema
    • mapMatterDpState：Matter DP → 标准 DP（上报转换）
    • mapPublishMatterDps：标准 DP → Matter DP（下发转换）
    • resolveColorData：颜色数据解析（结合 bright 与设备信息）
    • utils：
      • checkIsMatterDevice(schema, force?)
      • checkIsMatterHasWhite(dpSchema, force?)
      • getMatterRoad(dpSchema, force?) → 1/2/3/4/5 路
      • temp2Number(kelvin, schemaObj) / number2Temp(value, schemaObj)
      • bright2Number(bright, schemaObj) / number2Bright(value, schemaObj)
      • getTempRgb(kelvin)
    • hooks：useOriginMatterTemp() 获取原始 color_temp_control 值
    • dpCodes：
      • powerCode: switch_led, brightCode: bright_value, temperatureCode: temp_value, colourCode: colour_data
  • Matter dpCodes：switch: 'switch', brightness_control: 'brightness_control', color_temp_control: 'color_temp_control', hsColorCode: 'hs_color_set'

🔀 DP 功能点映射关系与转换说明

  • 映射总览：
    • switch ↔ switch_led（开关）
    • brightness_control(1-254) ↔ bright_value(10-1000)（亮度）
  • color_temp_control(154-370) ↔ temp_value(0-1000)（色温）
    • hs_color_set(色相+饱和度) + brightness_control ↔ colour_data(HSV)
  • 亮度：线性映射保证区间一致
  • 色温：基于卡尔文的非线性映射以优化滑动条显示；精度可能丢失，需用 hooks.useOriginMatterTemp()
  • 颜色：将 H/S 与亮度合并为标准 HSV；在 Matter 面板下 value 来自 bright_value

💡 常用示例

  • 获取设备路数与白光能力：
import { useDpSchema, createMatterKit } from '@ray-js/panel-sdk';
const matterKit = createMatterKit();
const dpSchema = useDpSchema();
const road = matterKit.utils.getMatterRoad(dpSchema);
const hasWhite = matterKit.utils.checkIsMatterHasWhite(dpSchema);
  • 获取原始色温值（避免精度损失）：
const originTemp = matterKit.hooks.useOriginMatterTemp();
  • 颜色数据处理（推荐用 useColourData）：
import { useColourData } from '@ray-js/panel-sdk';
const colorData = useColourData(); // { hue, saturation, value }
  • 手动解析颜色数据：
const colorData = matterKit.resolveColorData({
  colourData: { hue, saturation, value: Number(bright) ?? 0 },
  brightValue: Number(bright) ?? 0,
  devInfo,
});
  • 自定义转换条件：
createMatterKit({
  shouldConvert: params => params.action === 'init',
});
  • 开启调试模式：
createMatterKit({ debug: true });

🤝 与 dp-kit 配合使用（拦截器顺序建议）

  • 建议在 publishDps 中先执行 dp-kit、再执行 matter-kit：
request: {
  publishDps: [
    ...dpKit.interceptors.request.publishDps,
    ...matterKit.interceptors.request.publishDps,
  ],
},

这样 dp-kit 先处理标准协议，再由 matter-kit 转换为 Matter 协议，避免数据不一致。

⚠️ 注意事项

  1. 色温转换可能丢失精度，UI 展示请用 useOriginMatterTemp()
  2. 与 dp-kit 协同时务必注意拦截器顺序
  3. schema 转换会新增标准 DP（switch_led/bright_value 等）并保留原始 Matter DP（switch/brightness_control 等）以便路数判断
  4. 生产环境建议关闭 debug，避免日志过多

📖 专家指令示例

  • 如何在照明面板集成 matter-kit 并使用标准 DP？
  • 请给出 brightness_control 与 bright_value 的双向转换公式与实现示例
  • 如何判断当前 Matter 设备的路数与是否有白光，并据此设计交互？
  • 与 dp-kit 协同时，拦截器应如何排序，原因是什么？
  • 在颜色控制场景下，如何正确组合 hs_color_set 与亮度，得到标准 HSV？

📦 包含资源 (Resources)

  • skills/LampMatterSkills/SKILL_ZH.md（中文技能描述）
  • skills/LampMatterSkills/SKILL.md（英文技能描述模板）

必须开启乐观更新（Optimistic Update）

  • 要求：本技能在多协议并存（标准/Matter）场景下，必须为 dp-kit 启用乐观更新，以避免二次上报、回环与界面卡顿。
  • 版本要求：@ray-js/panel-sdk >= 1.15.0（及以上稳定版本）。
  • 拦截器顺序：请确保拦截器顺序为“dp-kit 在前、matter-kit 在后”。

建议配置示例（简化伪代码，仅示意）：

import { createDpKit } from '@ray-js/panel-sdk';
import { createMatterKit } from '@ray-js/panel-sdk';

const dpKit = createDpKit({
  // 必须启用乐观更新：
  immediate: true,
  ignoreDpDataResponse: true,
});

const matterKit = createMatterKit({
  // 其他 matter-kit 相关配置...
});

// 发布链路：dp-kit 在先，matter-kit 在后
const interceptors = [dpKit.interceptor, matterKit.interceptor];

// 在业务中，统一通过“标准 DP”作为入口进行发布与状态管理
// 如：power、bright_value、color_temp、hsv 等
export function setupInterceptors(client) {
  interceptors.forEach(i => client.use(i));
}

说明：

  • immediate: true 会在本地优先更新 UI 状态，提供更流畅的交互体验；
  • ignoreDpDataResponse: true 可避免设备回包再二次驱动 UI 导致的抖动与回环；
  • 保持 DP 发布顺序一致，生产环境请关闭多余 debug，结合业务需要再决定是否局部关闭乐观更新。

（注）示例中未包含任何本地绝对路径，请按项目结构将上述初始化逻辑放入合适的文件（例如 devices/index.ts），并结合自身工程调整。

🧩 面板 SDK 与 matter-kit 集成指引（003/006 通用）

  • 推荐版本：@ray-js/panel-sdk >= 1.15.0
  • 拦截器顺序：dp-kit 在前、matter-kit 在后（先标准协议，再转换为 Matter）
  • 初始化示例：
// src/devices/index.ts
import {
  SmartDeviceModel,
  SmartGroupModel,
  SmartStorageAbility,
  SmartSupportAbility,
} from '@ray-js/panel-sdk';
import { createDpKit } from '@ray-js/panel-sdk';
import { createMatterKit } from '@ray-js/panel-sdk';
import { getLaunchOptionsSync } from '@ray-js/ray';
import dpCodes from '@/constant/dpCodes';
import { protocols } from '@/devices/protocols';

const isGroupDevice = !!getLaunchOptionsSync()?.query?.groupId;

export const matterDpKit = createMatterKit({
  debug: true,
});

export const dpKit = createDpKit({
  protocols,
  // 003 建议：开启乐观更新并按需忽略 DP 回应，避免亮度循环与 UI 卡顿
  sendDpOption: {
    immediate: true,
      whiteDpCodes: [
        dpCodes?.countdown,
        dpCodes?.switch_led,
        matterDpKit.dpCodes.switch as any,
        // 必须包含 brightness_control：为保证调节彩光亮度时，白光亮度能同步
        matterDpKit.dpCodes.brightness_control as any,
      ].filter(Boolean),
    },
  },
});

const options = {
  abilities: [
    new SmartSupportAbility({
      // 基于 matter schema 生成标准 schema（路数/白光判断依赖）
      initDevInfo: matterDpKit.resolveMatterDevInfo,
    }),
    new SmartStorageAbility(),
  ],
  interceptors: {
    response: dpKit.interceptors.response,
    request: {
      publishDps: [
        ...dpKit.interceptors.request.publishDps,
        ...matterDpKit.interceptors.request.publishDps,
      ],
    },
    init: matterDpKit.interceptors.init,
  },
};

export const devices = {
  common: isGroupDevice
    ? new SmartGroupModel(options as any)
    : new SmartDeviceModel(options as any),
};

🧭 白光支持与路数判定（UI 决策依据）

  • 白光 Tab 判定（3 路 Matter 无白光）：
// src/pages/home/supports.ts
const dpSchema = devices.common.getDpSchema();
const isMatterPanel = matterDpKit.utils.checkIsMatterPanel(dpSchema);
const isSupportWhite = isMatterPanel
  ? matterDpKit.utils.checkIsMatterHasWhite(dpSchema)
  : support.isSupportDp(dpCodes.bright_value);

  • 路数（1~5 路）判定逻辑：

    • 1 路：brightness_control
    • 2 路：brightness_control + color_temp_control
    • 3 路：hs_color_set + brightness_control
    • 4 路：hs_color_set + brightness_control + bright_value
    • 5 路：hs_color_set + brightness_control + color_temp_control

  • 在 Hook 中使用：

// src/hooks/useLampRoad.ts
const dpSchema = devices.common.getDpSchema();
const isMatterPanel = matterDpKit.utils.checkIsMatterPanel(dpSchema);
if (isMatterPanel) {
  const matterRoad = matterDpKit.utils.getMatterRoad(dpSchema);
  // 根据 matterRoad 决定 UI/场景数据（见下方示例）
}

🎛 情景页与编辑页（3 路 Matter 无白光）

  • 情景页数据集切换（示例）：
// src/pages/home/index.tsx（示意）
const dpSchema = devices.common.getDpSchema();
const isMatterPanel = matterDpKit.utils.checkIsMatterPanel(dpSchema);
if (isMatterPanel) {
  const matterRoad = matterDpKit.utils.getMatterRoad(dpSchema);
  // 5->白光场景+彩光场景，4->亮度场景+彩光场景，3->彩光场景，2->白光场景，1->亮度场景
}
  • 情景编辑页隐藏白光 Tab：
// src/pages/SceneEdit/ColorPanel/index.tsx（示意）
const isMatterPanel = matterDpKit.utils.checkIsMatterPanel(dpSchema);
const isMatterHasWhite = matterDpKit.utils.checkIsMatterHasWhite(dpSchema);
const whiteTabHidden = isMatterPanel ? !isMatterHasWhite : (!support.isSupportBright() && !support.isSupportTemp());

🎨 彩光亮度与白光亮度统一（颜色解析）

  • 在 Matter 面板下，HSV 的 V 来自 bright_value：
// src/pages/home/tabs/light/index.tsx / Colour/index.tsx（示意）
const colourData = matterDpKit.resolveColorData({
  colourData: colour_data_origin,
  brightValue: Number(bright_value),
  devInfo: devices.common.getDevInfo(),
});

🚫 群组与混合组合限制

  • 单设备面板可同时支持非 Matter 与 Matter
  • 群组设备不支持 Matter 与非 Matter 混合组合

⚙️ 乐观更新与拦截器顺序建议

  • 启用 sendDpOption.immediate 提升交互流畅度
  • 使用 ignoreDpDataResponse.whiteDpCodes 避免彩光亮度与白光亮度的循环触发
  • 发布 DP 时严格保持顺序：
request: {
  publishDps: [
    ...dpKit.interceptors.request.publishDps,
    ...matterDpKit.interceptors.request.publishDps,
  ],
},

🪤 常见坑位与排查

  1. 3 路 Matter 不存在白光：用 checkIsMatterHasWhite 决定是否展示白光 UI
  2. 3/4 路区分：是否存在 bright_value（4 路包含 bright_value）
  3. 颜色解析需传 devInfo：保证不同设备能力下 HSV/亮度转换准确
  4. 色温滑动条精度：UI 展示需用 hooks.useOriginMatterTemp() 获取原始值
  5. 生产环境关闭 debug：减少日志量与性能影响

任务要求

如果是适配 matter 需求，需要检查并完成以下任务：

  1. src/devices/index.ts 文件引入 matter-kit 并配置拦截器，并启用乐观更新，SmartSupportAbility 需要接入 resolveMatterDevInfo
  2. 白光/彩光是否展示相关逻辑，例如是否展示 白光 tab 的判断，需要使用 checkIsMatterPanel + getMatterRoad 一起做判断，3路是不支持白光 tab 的
  3. 情景数据里，需要使用 checkIsMatterPanel + getMatterRoad 一起做判断，按 matterRoad 返回情景数据，3路不支持白光情景（CW不支持）
  4. 彩光亮度等于白光亮度，代码里取 colour_data 的地方需要处理，改为使用 useColourData
  5. 检查代码里是否有 useLampRoad 类似的获取路数判断逻辑，需要使用 checkIsMatterPanel 判断如果是 matter 则走 getMatterRoad 获取。
Weekly Installs
6
Source
developer.tuya.…erSkills
First Seen
11 days ago
Installed on
amp6
cline6
opencode6
cursor6
kimi-cli6
codex6