yoooclaw-light git:20260828.dc8a6c0A

Immutable. This exact content never changes and is served at /api/v1/blob/77c82cbae7ada68c.

---
name: yoooclaw-light
description: 灯效控制：使用 yoooclaw CLI 立即播放一次灯效，或创建、查看、修改、启停、删除“通知→灯效”持久规则。用户要求现在或任务完成后亮灯，或表达“当/如果/每次收到某类通知时亮灯”时使用。
---

# YoooClaw 灯效

通过本机 `yoooclaw` CLI 控制一次性灯效和通知触发的持久灯效规则。

## 选择分支

根据用户希望灯效发生的时机选择一个分支，并在执行前完整读取对应 reference：

| 用户意图 | 必须读取 | 完成判定 |
|---|---|---|
| 现在亮灯、任务开始/处理中/完成后亮灯 | [`references/one-shot.md`](references/one-shot.md) | 命令成功且结构化结果确认请求已下发，或报告明确失败 |
| 当/如果/每次收到某类通知时亮灯；管理已有规则 | [`references/rules.md`](references/rules.md) | 创建或变更结果经结构化响应核验；只读请求返回实际规则或明确空结果 |

一次性播放是立即下发到在线硬件的单次操作；持久规则保存在云端，由后续通知触发。用户同时要求两者时依次执行两个分支，分别核验结果。

## 共同边界

- 两个分支都使用已配置的 API key 并需要网络；一次性播放还要求硬件在线。规则管理不需要 daemon 常驻。
- 本次第一条灯效业务命令前运行一次 `yoooclaw --version`。命令不可用或版本号无效时报告 CLI 不可用，不猜测命令替代品。
- 用户选择非默认 profile 时，在 `light` 或 `lightrule` 前加入全局参数 `--profile <name>`。
- 支持 JSON 输出的命令追加 `--format json`，同时检查退出状态和顶层 `ok`；`ok=false` 按失败处理。
- API key 只从现有凭据读取。需要重新配置时使用 `yoooclaw auth set-api-key -` 从 stdin 输入，不把 key 写进命令行或回复。
- 对 `AUTH_REQUIRED`、设备离线、网络失败和其他业务错误，保留脱敏后的 code/message，并只给一个与当前分支对应的下一步。网络写操作最多重试一次；结果不确定时先用只读命令核验，避免重复下发或重复创建。

最终回复区分“灯效请求已下发”和“持久规则已保存”，只报告用户需要的标题、原因、预设/规则、状态及必要 warning。