查看家庭概况
只读总结我当前默认家庭的房间、设备、设备组、情景和自动化，不要修改。
你会看到真实家庭结构摘要与 0 项改动。把 Yeelight MCP 接入你的 AI
已经配置好 Yeelight Home，并且 AI 客户端支持 MCP？跟着真实安装向导选中客户端、完成连接，再从只读查询走到一次可验证的灯光响应。
- 预计时间
- 16 分钟
- 完成后你会看到
- AI 能读到你真实的默认家庭，先预览一个明确动作，再在你确认后只执行一次并读回真实状态。
开始前准备
- Yeelight Home 已安装并能正常运行
- Yeelight Pro 账号已登录并选好默认家庭
- AI 客户端支持 MCP
- 执行控制或家庭修改时使用有权限的账号
先确认 Yeelight Home 已经就绪
本教程不重复安装 Yeelight Home，也不重复配置家庭。运行两条只读命令；只有版本可读、doctor 返回 `status: ok` 且已经登录时，才继续接入 MCP。
如果任一命令失败，先进入 Yeelight Home 教程完成安装、扫码和默认家庭选择。
yeelight-home version --jsonyeelight-home version --json
交互演示，不会在你的电脑上执行命令，也不会连接设备。
yeelight-home doctor --jsonyeelight-home doctor --json
交互演示，不会在你的电脑上执行命令，也不会连接设备。
看到这个就成功两条命令都能运行，doctor 显示 `status: ok` 和 `authenticated: true`。
如果没有成功提示找不到命令、没有登录或没有默认家庭时，先完成 Yeelight Home 教程；不要把二维码、Token、Cookie 或完整 doctor 输出发给别人。
选择 AI 客户端并审阅安装计划
运行真实交互向导，不加 `--yes`。向导会先列出 20 个已验证的 MCP 客户端，让你自己选择；随后明确显示客户端、四步计划和确认问题。默认连接本机 Yeelight Home Runtime。
输入客户端序号，检查计划里写的是“连接本机 Yeelight Home Runtime”，确认无误后输入 Y。后续账号检查允许继续使用当前账号，也允许重新扫码切换账号。
yeelight-home setup --lang zh-CN --mode mcpyeelight-home setup --lang zh-CN --mode mcp
交互演示，不会在你的电脑上执行命令，也不会连接设备。
以上顺序来自 yeelight-home 0.1.25 的真实 TTY 输出；客户端列表在页面中做了横向压缩，终端会完整逐行显示。
也可以让 AI 陪你完成
请运行 `yeelight-home setup --lang zh-CN --mode mcp`。让我自己选择要配置的 AI 客户端，并把最终四步计划原样显示给我确认。检查登录时让我决定继续使用当前账号还是重新扫码；任何二维码、Token 或家庭编号都不要发到聊天里。完成后提醒我完全退出并重开刚才选择的 AI 客户端。
查看文字版
实测 yeelight-home 0.1.25：选择 Codex 后，向导显示 Runtime、账号检查、本地 MCP 配置和只读验证四步；演示在最终确认处取消，因此没有修改任何客户端配置。
向导可以重新扫码切换账号；不要因为已经登录就强制跳过账号检查。
看到这个就成功setup 完成客户端配置和只读家庭验证，并提示重新启动所选 AI 客户端。
如果没有成功不想继续时在最终计划处输入 n，终端会明确显示“已取消安装，没有修改任何配置”。没有检测到想用的客户端时，从列表中手动选择；不要用 `--agent auto --yes` 跳过新手需要的选择和确认。
重启 AI，再做第一次只读验证
完全退出并重开刚才配置的 AI 客户端。第一次只让 AI 读取默认家庭名称、房间和设备概况，不控制设备，也不修改家庭。
检查 Yeelight MCP 是否可用
请检查 Yeelight MCP 是否已经连接。只读取我当前默认的易来家庭名称、房间数量和设备数量，不要控制设备，也不要修改任何设置。如果失败，请告诉我卡在连接、登录、默认家庭还是工具加载。
只读验证，0 项改动。 脱敏交互演示，不会读取你的家庭或控制设备。
看到这个就成功AI 返回你真实的家庭名称和数量，并明确没有修改任何内容。
如果没有成功工具列表为空时先完全重启客户端，再检查 MCP 配置；401 通常需要重新扫码并确认账号区域，连接正常但家庭为空时检查默认家庭。
体验 1：让 AI 看懂你的家
先让 AI 只读整理房间、设备、设备组、情景和自动化，再指出重名、默认房间或未归类设备。
生成一份家庭地图
请只读检查我当前默认的易来家庭，把房间、设备、设备组、情景和自动化整理成一份普通人能看懂的家庭地图，并指出重名、默认房间和没有归类的设备。先不要修改。
只读检查，没有修改家庭结构。 脱敏交互演示，不会读取你的家庭或控制设备。
查看文字版
用户要求只读总结当前家庭；AI 读取房间、设备组、情景和自动化，并明确 0 项改动。画面只展示交互结构，不包含真实家庭数据。
看到这个就成功AI 返回与你家庭一致的地图和可理解的整理建议。
如果没有成功结果属于错误家庭时先运行 `yeelight-home home select` 重新选择默认家庭；名称重复时让 AI 展开房间、位置和候选设备，不要猜。
体验 2：读取一盏灯的真实状态
先读再控能避免重复动作和错误目标。说清房间、位置和设备名称，只询问设备实际支持的属性。
只读取指定灯光
请读取客厅电视墙左侧射灯现在的开关和亮度；如果它支持色温，也一起告诉我。只读取，不要调整。找不到唯一设备时先列出候选，不要自行选择。
只读状态查询。 脱敏交互演示，不会读取你的家庭或控制设备。
看到这个就成功AI 返回指定设备的真实状态，并说明没有执行控制。
如果没有成功候选不唯一时补充左右、床头、电视墙等位置；属性不支持时接受设备真实能力，不要求 AI 臆造结果。
体验 3：先预览一次灯光调整
让 AI 先说明唯一目标、当前状态和计划变化，明确等待确认；此时灯光不应发生变化。
预览客厅落地灯亮度
我想把客厅沙发旁的落地灯调到 40% 亮度。先确认你找到的是哪一盏，读取它当前的真实亮度，再告诉我计划变化；现在不要执行。
没有取得确认，不发送控制。 脱敏交互演示，不会读取你的家庭或控制设备。
查看文字版
演示按房间和位置锁定落地灯，当前值以实时读回为准，计划值为 40%，最后停在等待确认；没有控制设备。
只有目标和变化都正确时，才进入下一步。
看到这个就成功AI 给出唯一目标、真实当前状态、计划变化和等待确认状态。
如果没有成功目标不唯一时补充房间、位置或昵称；设备离线或不支持亮度时停止，不要换一个相似设备继续。
体验 4：先看清情景影响范围
情景可能同时改变多台设备。先确认家庭、情景名称、影响对象和大致效果，不要直接执行。
预览客厅观影情景
请在我当前默认家庭里找到客厅的“观影”情景，先告诉我会影响哪些设备和大致效果，不要马上执行；如果有同名情景，先列出候选。
多设备情景尚未执行。 脱敏交互演示，不会读取你的家庭或控制设备。
多设备动作必须先核对影响范围。
看到这个就成功AI 清楚说明真实影响范围，并等待你的确认。
如果没有成功不存在该情景时让 AI 列出当前家庭的情景名称；同名时补充房间；权限不足时换用有权限账号，不要绕过。
体验 5：确认后只执行一次并读回
只有目标和计划都正确时才继续。让 AI 复用刚才的唯一目标，只发送一次控制，然后重新读取真实状态。
确认刚才的单灯调整
我确认执行刚才对客厅沙发旁落地灯的调整：亮度改为 40%。只执行一次，完成后重新读取这盏灯的状态并告诉我是否生效；如果结果不明确，不要再次控制，直接说明问题。
结果不明确时停止，不盲目重复控制。 脱敏交互演示，不会读取你的家庭或控制设备。
只确认你刚刚预览过的目标和变化。
看到这个就成功AI 明确报告只执行一次，并用控制后的真实状态证明是否生效。
如果没有成功状态没变化时检查设备在线状态、属性支持和账号权限；读回不一致时停止，不连续重试。
默认本地路线与云端兼容路线
普通用户直接运行 `yeelight-home setup --lang zh-CN --mode mcp`：默认 `mcpSource` 是 `local`，AI 客户端按配置自动启动 `yeelight-home mcp serve --stdio`。只有明确需要轻量云端兼容时才加 `--mcp-source cloud`，由本地代理在请求时读取凭据并连接 Metadata MCP 与 IoT MCP；它们直接接入 Yeelight PRO 云端，不以本地 Runtime 作为执行底座。直连网关属于 LAN 教程，不是本页主路线。
先试这几个日常场景
先选 3-5 个最容易理解的例子。每句话都可以直接发给你的 AI。
读取指定灯状态
只读查看客厅电视墙左侧射灯的开关、亮度和它实际支持的其他属性，不要调整。
你会看到唯一设备的实时属性。预览单灯亮度
预览把主卧床头右侧射灯调到 30%，先读取当前值并等我确认，不要执行。
你会看到目标、真实当前值、计划值和等待确认状态。预览已有情景
找到客厅观影情景，说明真实影响范围并等我确认，不要直接执行。
你会看到情景影响对象和预期效果。执行一次并读回
执行我刚确认的单灯调整一次，然后读回状态；结果不明确时停止。
你会看到一次写入和真实状态读回。更多完整场景
核对灯组成员
只读列出儿童房筒灯组的全部灯位和各自状态，确认是否有离线或不同步的灯。
你会看到灯组成员和逐灯位状态。预览整组调光
先确认儿童房筒灯组全部成员，再预览把整组调到 55%，不要只控制其中一盏。
你会看到完整成员范围和整组控制预览。检查重复名称
只读找出全屋同名设备、情景和自动化，按房间列出容易混淆的对象。
你会看到带房间和类型的重名清单。检查离线设备
只读检查当前家庭中的离线设备，并按房间和最近可见状态整理，不要尝试控制。
你会看到离线设备与排查顺序。自动化体检
只读检查自动化触发条件、动作对象和启用状态，找出冲突、重复或无效配置。
你会看到按优先级排列的自动化问题。情景影响对比
只读比较客厅观影和全亮两个情景的影响设备和目标状态，不要执行。
你会看到两个真实情景的差异。家庭整理建议
根据房间、设备和设备组的真实结构给出整理建议，先给计划，不要重命名或移动设备。
你会看到零写入的整理计划。预览设备重命名
预览把主卧床头右侧射灯改成“主卧右阅读灯”，先确认唯一设备和影响，不要执行。
你会看到重命名目标和影响预览。预览新建情景
根据当前真实设备预览一个“晚间阅读”情景，列出每个动作，先不要创建。
你会看到可审阅的情景动作计划。权限范围检查
只读告诉我当前账号能查看和能修改哪些家庭内容，不执行任何写操作。
你会看到当前账号可用能力与受限项。失败后停止复核
检查刚才未确认成功的控制，只读设备状态和在线情况，不要再次发送控制。
你会看到失败原因线索与零重试记录。遇到问题
为什么必须先安装 Yeelight Home？
本教程的默认 MCP 路线由 AI 客户端启动本机 `yeelight-home mcp serve --stdio`。先完成 Yeelight Home 安装、登录和默认家庭选择，MCP 才有可用的本地 Runtime 与账号上下文。
本机需要升级 Yeelight Home 吗？
先运行 `yeelight-home version --json`，再用 `npm view yeelight-home version` 查看 npm 最新版。教程实测时本机和 npm 最新版均为 0.1.25，因此没有为了升级而重复安装。
Yeelight MCP 是一个还是两个项目？
教程统一称为 Yeelight MCP。默认本地路线只配置 Yeelight Home Runtime；高级云端路线会一次配置 Metadata MCP 和 IoT MCP，普通用户不需要分别理解或安装。
默认 local 和 cloud 有什么区别？
不写 `--mcp-source` 时默认 `local`，复用 Yeelight Home 的完整本地语义能力。`cloud` 是轻量兼容路线，连接托管的 Metadata 与 IoT 服务。对小白用户优先使用默认 local。
需要自己启动 MCP 服务器吗？
通常不需要。完成 setup 并重启 AI 客户端后，客户端会按配置自动启动本地 stdio 服务；不要另外开一个长期终端进程。
为什么 setup 一开始让我选择 AI 客户端？
不同客户端的 MCP 配置位置和写入方式不同。交互向导列出 20 个已验证客户端，让你明确选择真正要配置的目标，避免写入不需要的软件。
为什么不推荐 `--agent auto --yes`？
它适合明确知道目标的无人值守场景。小白用户需要看到客户端选择、账号检查和最终计划，因此教程保留交互确认。
已经登录了，setup 为什么还检查账号？
因为用户可能正想切换账号。交互流程允许继续使用当前账号，也允许重新扫码；它不应无条件跳过登录检查。
二维码过期或账号区域不对怎么办？
重新运行 setup，或按账号区域运行 `yeelight-home auth login --qr --region cn`；新加坡、美国、欧洲账号分别使用 `sg`、`us`、`eu`。二维码和扫码结果不要转发。
有多个家庭时如何指定？
先运行 `yeelight-home home select`，在终端按序号或完整名称选择默认家庭。对话中仍应说清家庭名称，尤其是多个家庭存在同名房间时。
为什么配置完成后 AI 里没有 Yeelight 工具？
先完全退出并重开 AI 客户端，而不是只关闭当前对话。仍为空时重新运行 setup，确认选中了正确客户端，并检查它读取的 MCP 配置位置。
提示不支持这个 AI 客户端怎么办？
setup 只对验证过的适配器写配置，未知客户端会明确失败，不会假报成功。先在列表中选择受支持客户端；新客户端需要单独增加适配器。
现有 MCP 配置是空文件或 JSON 损坏怎么办？
先备份对应客户端配置，再把空文件修复成合法 JSON 后重跑 setup。不要直接删除整个配置目录，因为其中可能还有其他 MCP。
出现 401、登录失效或家庭为空怎么办？
核对账号区域并重新扫码，然后运行 `yeelight-home doctor --json`。登录正常但家庭为空时检查账号是否有 Yeelight Pro 家庭以及默认家庭是否选对。
为什么 AI 找到多个同名灯？
房间里常有多盏同名筒灯或射灯。补充家庭、房间、左右位置或设备昵称；在唯一目标确定前只列候选，不执行。
为什么写操作要求确认或管理员权限？
控制、重命名、移动设备、情景和自动化修改的影响范围不同。先预览并确认；结构性修改需要家庭管理员时，应换用有权限账号，不要绕过。
控制后状态没有变化怎么办？
先检查设备是否在线、属性是否支持和状态读回是否一致。结果不明确时停止，不连续重发；否则一次网络延迟可能造成重复动作。
网关 LAN MCP 也在这篇教程里吗？
不在。`--mode lan --mcp-source gateway` 是直连网关兼容路线，还需要网关地址和 LAN 条件；本页只讲普通用户的 Yeelight MCP 主路线。
关注易来，继续探索
获取产品动态、智能照明灵感与 Yeelight AI 的最新实践。选择你常用的平台，扫码关注或直接访问。
微信公众号
Yeelight 易来
关注官方公众号，获取产品更新、使用指南与智能照明内容。
使用微信扫码关注。 抖音
Yeelight 易来
观看易来产品、空间光影与智能照明的短视频内容。
使用抖音扫码关注。
腾讯视频号
姜兆宁 Yeelight 易来
关注易来 CEO 的家居视频号，了解智能照明与真实家庭空间。
使用微信扫码关注视频号。