@zke-wuhu/agent-only-rgb 0.0.0-stage → 0.8.4

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# 让 AI 干活的时候，桌上的灯带跟着变色
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一块 SOP8 小板子，用 USB 插到电脑上。装一次，之后 AI 开始思考、等你回答、
+干完活、出错，灯带会用不同颜色和节奏告诉你 —— 不用一直盯着屏幕。
+
+**只有板子、没买灯带也能用**：板子上自带 1 颗灯，效果就跑在它上面。
+
+---
+
+## 我要准备什么
+
+| | 说明 |
+|---|---|
+| 板子 | 手里这块，用 **USB 数据线**插电脑（有些线只能充电，会读不到设备） |
+| 灯带 | 可选。WS2812 / SK6812，按灯带上的箭头方向接到板子的灯带接口；**灯珠多的时候按灯带说明单独供电**，别只靠 USB 口带 |
+| 电脑 | Windows / macOS / Linux；需要 Python 3.7+ 和 Node.js 14+（安装器会自己找、自己装依赖） |
+| AI 工具 | WorkBuddy / Claude Code / CodeBuddy / Trae 任选；用别的 AI 也可以在安装时自己填配置目录名；还可以**先只用命令行**，让灯先亮起来 |
+| 驱动 | Windows / macOS 免驱；Linux 若提示权限不足，见下面「灯没亮？」 |
+
+## 三步装好
+
+**1)** 把板子用 USB 插到电脑上。
+
+**2)** 在终端执行这一条：
+
+```bash
+npx @zke-wuhu/agent-only-rgb
+```
+
+它只会问你两件事：
+
+- **外接灯带有几颗？** 没接就填 `0`；接了就填灯带上的灯珠数（最多 100）。
+- **平时用哪个 AI？** 一路回车用推荐配置即可，也可以逐个时机挑，
+  或选「让我的 AI 自己决定」「我自己打字描述想要的效果」。
+
+**3)** 看到灯从中间亮起来、向两边铺满 → 成了。
+
+> 只要这一条命令。**不用 `npm i -g`、不用记安装路径、不用理解「钩子」是什么。**
+> 以后所有操作都长这样：`npx @zke-wuhu/agent-only-rgb <命令>`。
+> 如果以前全局装过旧版命令，安装器会自动检测并打印确切的卸载命令，照着执行一次
+> 即可（例如 `npm uninstall -g @zke-wuhu/agent-only-rgb`；若提示的包名不同，以提示为准）。
+> 之后一律用上面的 `npx` 形式：旧命令不认识 `quickstart` / `theme` / `doctor`，
+> 而且不卸载的话 `npx` 也可能命中 PATH 里的旧版本。
+
+## 装完我能干嘛
+
+在 AI 里（**把当前会话关掉、重新开一个**，技能才会加载）直接说人话：
+
+> 「现在怎么样」 · 「晚上有点刺眼」 · 「关灯」 · 「演示一下」 · 「换个夜间风格」
+
+不想开 AI，或者想先确认灯是好的，就在终端里：
+
+| 想做的事 | 命令（`npx @zke-wuhu/agent-only-rgb` 后面加） |
+|---|---|
+| 现在什么状态、有没有问题 | `brief` |
+| **灯不亮 / 排查问题** | `doctor` |
+| 把所有灯效依次看一遍 | `demo` |
+| 换风格 `pulse` / `night` / `focus` / `vivid` | `theme night` |
+| **先预览某风格再决定切不切**（不写入） | `theme-demo night` |
+| **整体快慢**（慢/正常/快，换主题保留） | `pace slow` / `pace normal` / `pace fast` |
+| **主题内微调单个状态**（亮度/周期/颜色） | `tune working brightness 90`，`tune reset` 清空 |
+| 整体调亮暗（1~100，掉电保持） | `brightness 50` |
+| 直接说人话 | `say '太亮了'` |
+| 重配「AI 什么时候亮什么灯」 | `hooks` |
+| 灯珠数填错了 / 想改用的 AI | `install`（重跑一次） |
+| 检查 / 升级板子固件 | `check` / `update` |
+| 重新走一遍开箱向导 | `quickstart` |
+
+完整命令表：`npx @zke-wuhu/agent-only-rgb --help`。
+
+## 灯珠数：最容易填错的一步
+
+板子上自带 **1 颗灯**，它固定是链上的第 0 颗：
+
+- **没接外接灯带** → 填 `0`。这时板载那颗就是**唯一的效果显示器**，所有灯效跑在它上面。
+- **接了 N 颗灯带** → 填 `N`（最多 100）。这时板载那颗只做设备自身状态指示
+  （升级 / 故障 / 等待），灯效跑在外接的 `N` 颗上；设备里存的链上总数是 `N+1`。
+
+不确定填得对不对：装完跑一次 `demo` 或看开场那次铺满 ——
+**灯应该一直亮到灯带最末端**。末端有灯不亮，就是颗数填少了；
+还有一段永远不亮，多半是填多了或接线方向反了。改数字重跑 `install` 即可，
+配置记在 `~/.agent-only-rgb.json`。
+
+非交互环境（CI、管道）一律不猜、不改动设备里已有的数量。
+
+## 灯没亮？按顺序查
+
+1. **跑 `npx @zke-wuhu/agent-only-rgb doctor`** —— 它会逐项告诉你
+   缺哪个依赖、钩子有没有绑上、设备连没连上、AI 工具找到几个。
+2. **读不到设备**：换一根确定能传数据的 USB 线、换一个电脑口；
+   终端里跑 `npx @zke-wuhu/agent-only-rgb info`，能打印固件版本就是连上了。
+3. **Linux 提示权限不足**：加一条 udev 规则后重新插拔
+   （VID `1209` / PID `A002`）：
+   ```bash
+   echo 'SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="a002", MODE="0666", TAG+="uaccess"' \
+     | sudo tee /etc/udev/rules.d/99-ble-agent-rgb.rules
+   sudo udevadm control --reload-rules && sudo udevadm trigger
+   ```
+4. **灯亮了但只亮一小截 / 位置不对**：回到上面「灯珠数」，重跑 `install` 改数字。
+5. **效果不对、或直接报错**：板子里的固件可能比较老，插着 USB 跑
+   `npx @zke-wuhu/agent-only-rgb update`，升级后重跑一次 `install`。
+6. **终端命令都正常，但 AI 里说话没反应**：关掉当前 AI 会话重新开一个
+   （技能在会话启动时加载）；再跑 `hooks` 确认绑定，或 `doctor` 看结果。
+
+---
+
+# 进阶：它到底做了什么
+
+## 装在什么地方
+
+安装器会：找到可用的 Python 3 → 装 `hidapi` / `bleak` / `certifi` →
+在你选的 AI 工具的 `skills/agent-only-rgb/` 下装一份技能
+（脚本 + 灯光配置 + 钩子声明）→ 写下灯珠数 → 按你的选择绑定钩子 →
+连上板子自检、下发默认灯光档案、亮一次灯给你看。
+
+**所有命令都转发到这份已安装的脚本**（`~/.agent-only-rgb.json` 里记着位置），
+所以 `theme` / `brightness` 改的配置和 AI 读的是同一份；`npx` 缓存清理也不会丢配置。
+
+## 钩子：AI 在什么时候亮什么灯
+
+不用理解「钩子」这个词，它就是「AI 在什么时刻亮什么灯」。安装第 2 步有三种选法：
+
+- **默认 · 用 AI 推荐**（回车即可）：4 个常用时机 —— 你发消息 = 金色从中间扩散、
+  新会话 = 绿色铺满后渐灭、回答结束 / 会话结束 = 渐灭；
+  另外 3 个高频时机（通知、工具调用前后）默认不绑定。
+- **依次配置**：逐个时机挑，每个都列出几种灯效，**最后两项固定是**
+  「让我的 AI 自己决定」和「我自己打字描述想要的效果」。
+  前者由 AI 在运行时按当时语义挑灯效；后者把你写的那句人话**原样**交给 AI
+  翻译成灯效（例如「柔和的紫色慢慢呼吸」）。
+- **保持现状**：重装 / 升级时不改动已有的任何绑定。
+
+选择写进技能目录的 `hook_choices.json`，安装器对**检测到的每个 AI 工具**
+各写一份 `settings.json`；其它技能装的钩子一条都不会被覆盖，选「不绑定」
+也会把该事件的旧绑定清掉。以后改配置**不用重装**：
+
+```bash
+npx @zke-wuhu/agent-only-rgb hooks
+```
+
+设计语言（中轴生长、金=工作 / 绿=交互与完成 / 红=错误 / 淡蓝=待机、禁止白色）
+写在 `lighting.json` 的 `design` 段，AI 会遵守，不会凭记忆乱配色。
+
+## 灯光配置（全部由主机下发）
+
+颜色、节奏、呼吸曲线都来自技能目录的 `lighting.json`，用 `lighting apply`
+写进设备 flash，断电保持。固件里只留一份保守兜底值，所以**改灯效不需要重新烧录**。
+
+主题是整套预设（亮度 + 节奏）：`pulse` 标准 / `night` 夜间 / `focus` 专注 /
+`vivid` 展示；`brightness 50` 是叠加在主题上的总亮度档。两者都写 flash。
+
+```bash
+npx @zke-wuhu/agent-only-rgb lighting show              # 回读设备当前配置
+npx @zke-wuhu/agent-only-rgb lighting apply             # 整套下发 + 回读校验
+npx @zke-wuhu/agent-only-rgb lighting apply my.json     # 自定义配置
+npx @zke-wuhu/agent-only-rgb lighting reset             # 恢复出厂兜底
+npx @zke-wuhu/agent-only-rgb tuning get                 # 14 项调参的当前值与范围
+npx @zke-wuhu/agent-only-rgb tuning set breathe_ms=3000 --save
+npx @zke-wuhu/agent-only-rgb curve get                  # 16 点呼吸曲线
+npx @zke-wuhu/agent-only-rgb curve set 0,0,0,0,2,7,17,29,46,64,88,117,139,179,213,255 --save
+```
+
+`lighting.json` 结构：`master`（总亮度）、`design`（设计语言）、`themes` /
+`active_theme`（风格预设）、`states`（状态表：颜色/模式/亮度/周期）、
+`map`（逐颗颜色）、`tuning`（14 项节奏/几何参数）、`curve`（16 点呼吸曲线，
+0..255 单调不减）。`apply` 会逐项回读校验，任何一项对不上都会报错并指出名字。
+
+## 命令行全表
+
+```bash
+npx @zke-wuhu/agent-only-rgb info                       # 设备信息 / APP 还是 AGENT
+npx @zke-wuhu/agent-only-rgb status                     # 当前显示的场景/灯效/租约
+npx @zke-wuhu/agent-only-rgb led FF0000                  # 常亮红（默认 60 秒后自动熄灭）
+npx @zke-wuhu/agent-only-rgb led 00FF00 --stat breathe --period 2000 --brightness 60
+npx @zke-wuhu/agent-only-rgb led 00FF00 --forever       # 常亮，不自动熄灭
+npx @zke-wuhu/agent-only-rgb led 00FF00 --hold 300      # 保持 300 秒
+npx @zke-wuhu/agent-only-rgb off                        # 关灯
+npx @zke-wuhu/agent-only-rgb count 101                  # 链上总颗数（板载 1 + 外接 100）
+npx @zke-wuhu/agent-only-rgb colors FF0000,00FF00,...    # 逐颗写颜色
+npx @zke-wuhu/agent-only-rgb state working              # 按语义状态切灯
+npx @zke-wuhu/agent-only-rgb onboard-check               # 核对板载指示：效果区纯红、链首暗青
+npx @zke-wuhu/agent-only-rgb ota app.ota                # 刷本地 .ota
+npx @zke-wuhu/agent-only-rgb ota app.ota --dry-run      # 只校验包结构
+npx @zke-wuhu/agent-only-rgb --ble check                # 走蓝牙（--ble 放哪都行）
+```
+
+`--stat` 可选：`on`（默认）、`breathe`、`blink`、`fast`、`marquee`、
+`expand`、`fadeout`、`fill`、`off`。颜色是 RGB332（硬件只有 3/3/2 位精度），
+`FF0000` 会显示成偏暗的红。
+
+`led` 默认带 **60 秒租约**：设备自己倒计时，到点熄灭，所以主机进程被杀、
+USB 拔掉之后灯不会一直亮着。要常亮用 `--forever`，要指定时长用
+`--hold <秒>`（1–254）。租约通过 8 字节报文的保留字节 `[7]` 传递，
+老固件会忽略它（退化为原来的常亮）。
+
+## 自动升级
+
+默认固件源：npm 包内自带（`assets/firmware/`，随 `npm update @zke-wuhu/agent-only-rgb` 更新），不依赖任何外部远程仓库。需要离线 / 自托管镜像时用 `--repo <本地目录>`。
+
+发布方在仓库根目录放 `manifest.json` 即可：
+
+```json
+{
+  "product": "bleAgentRGB_SOP8",
+  "latest": {
+    "img_ver": 38,
+    "file": "firmware/AgentRGB_SOP8_v38.ota",
+    "sha256": "可选，有就校验",
+    "notes": "可选，更新说明"
+  }
+}
+```
+
+没有 `manifest.json` 时会 `git clone --depth 1` 扫描仓库里所有 `*.ota`，
+取包头 `img_ver` 最大的那个。`--repo` 也可以指向本地目录（离线 / 内网镜像）：
+
+```bash
+npx @zke-wuhu/agent-only-rgb --repo D:\firmware update
+```
+
+本机上次成功升级的 `img_ver` 记在 `~/.agent-only-rgb/state.json`
+（可用 `BLE_AGENT_HOME` 改目录），所以重复执行 `update` 不会白刷同一个版本。
+
+安全边界：`.ota` 是经过加密与认证的固件包，工具本身**不含任何密钥**，
+解密与校验都在设备里完成；设备还会拒绝低于已记录版本的旧包，
+防止重放降级。
+
+## 依赖
+
+- Python 3.7+；`hidapi`（USB 通道）、`bleak`（蓝牙通道）、`certifi`（HTTPS）
+- Node.js 14+（只是启动器；实机操作都在 Python 脚本里）
+- 所有脚本**不含任何密钥**，可以放心分发

package/assets/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: agent-only-rgb
+description: 控制 bleAgentRGB SOP8 灯带控制器（WS2812 灯带，板载 1 颗状态指示 + 外接灯带最多 100 颗）。当用户提到灯效、灯光颜色、亮度、呼吸/闪烁/跑马灯、呼吸曲线/节奏/手感、定制灯效配置、关灯、设备状态、固件升级、OTA、刷机，或问"设备连上了吗""接了几颗灯"时使用。
+---
+
+# bleAgentRGB SOP8 设备控制
+
+一块通过 USB HID 或蓝牙 BLE 连接的灯带控制器（VID:PID `1209:A002`，板载 1 颗 + 外接灯带最多 100 颗，
+链上总数在安装时问过用户并写进设备 flash）。
+正常运行叫 **APP**，升级时叫 **AGENT**，两者用同一套 8 字节 HID 报文。
+
+所有操作走一个脚本：`__SKILL_DIR__/ble_sop8.py`（Windows 用 `python`，macOS/Linux 用 `python3`）。
+
+## 先读这里：给 AI 的 5 条铁律
+
+这个产品的用户是**不懂硬件的普通人**。产品承诺：用户只需理解 3 个概念（开箱 / 风格 / 亮度），其余全部自动。请严格遵守：
+
+1. **日常只向用户暴露 3 条命令**：`quickstart`（开箱）、`theme <名字>`（换风格）、`brightness <1-100>`（调亮暗）；看现状用 `brief`。
+   **不要**让用户接触 `scene` / `profile` / `tuning` / `curve` / `lighting apply` / `setup` / 场景号 / flash / HID 这些概念，除非用户明确要求高级定制。
+   例外：**排障时可以直接让用户跑 `doctor`**（它是写给人话的自检报告，不是配置项）。
+2. **用户说人话 → 优先 `say '<原话>'`**，例如"晚上有点刺眼""慢一点""关灯"。它会自动翻译；听不懂会明确列出支持的句式，**别自己乱改参数**。
+3. **绝不发明配色，绝不用白色**。设计语言写在 `lighting.json` 的 `design` 段（中轴生长：金=工作 / 绿=交互·完成 / 红=出错 / 淡蓝=待机，全部中心向外扩散或一次性填充）。用户要换风格**只能** `theme pulse|night|focus|vivid`，不要手改 `states`，更不要说"得改固件"。
+4. **状态灯 100% 交给钩子，AI 不插手（零 token）**。发消息→working 金、会话开始→session-start 绿铺满、**准备提问（AskUserQuestion）前→ask 绿**、一轮结束→idle 淡蓝、会话结束→fade 灭——全部由 AI 工具的钩子自动跑，**你一行灯效命令都不用发**。是否由你主动监管灯带，由 `hook_choices.json` 的 `ai_supervise` 决定（见下方「AI 监管模式」）。**默认 `auto`（有钩子）下你完全不碰灯效命令**——既省 token，也绝不会和钩子打架。只有在 `ai_supervise=on`（或 auto 且无钩子）这种兜底情况下，你才在提问前手动 `state ask`、动手前 `state working`、收工 `state idle`、出错 `state error`。
+5. **出问题按这个顺序查，别一上来就让用户重装**：
+   - 先 `brief`；它说设备没连 → 让用户换一根能传数据的 USB 线、换个口重插，再跑 `doctor`。
+   - 设备正常但灯只亮一截 / 位置不对 → **灯珠数填错了**（安装时问的是「外接灯带有几颗」），让用户重跑 `npx @zke-wuhu/agent-only-rgb install` 改数字；想看全条就 `demo`。
+   - 终端里灯正常、但在 AI 里说话没反应 → 让用户**关掉当前会话、重新开一个**（技能在会话启动时加载），再 `hooks` / `doctor`。
+   - 以上都好使但效果怪 → 板子固件老，插着 USB 跑 `npx @zke-wuhu/agent-only-rgb update`。
+   `quickstart` 是万能重置入口（重绑钩子 + 重装依赖 + 恢复默认风格 + 自检）。钩子在安装时已经用人话问过用户，**别再让用户去理解"绑定"是什么**；改配置引导 `npx @zke-wuhu/agent-only-rgb hooks`。
+
+### 人话 → 动作 映射表（AI 直接用，别让用户学命令）
+
+| 用户说 | 执行 |
+|---|---|
+| 我刚拿到 / 插上了 / 怎么用 | `quickstart` |
+| 现在什么状态 / 灯怎么不亮 | `brief` |
+| 装好了但在 AI 里说话没反应 | 先 `doctor`；让用户**关掉当前会话重开一个**，再 `hooks` |
+| 灯只亮一截 / 末端不亮 | 灯珠数填错：让用户重跑 `npx @zke-wuhu/agent-only-rgb install`；`demo` 可核对 |
+| 板载那颗怎么不变色 | `onboard-check`：效果区打成纯红，链首应恒为暗青（没接灯带时它应是纯红） |
+| 晚上用 / 太刺眼 / 护眼 | `say '晚上有点刺眼'`（→ night）或 `theme night` |
+| 白天 / 拍视频 / 展示一下 | `theme vivid` |
+| 安静点 / 专注模式 | `theme focus` |
+| 恢复默认 / 标准 | `theme pulse` |
+| 想先看看某风格长什么样 | `say '看看夜间效果'` 或 `theme-demo night`（预览，不写入） |
+| 太亮 / 太暗 / 亮一点 | `say '太亮了'` 或 `brightness 50` |
+| 慢一点 / 快一点 | `say '慢一点'` / `pace slow` / `pace fast` |
+| 节奏恢复正常 | `say '恢复正常节奏'` 或 `pace normal` |
+| 工作态想更亮 / 待机太亮 | `tune working brightness 90` / `tune idle brightness 20`；`tune reset` 清空 |
+| 关灯 | `state off` 或 `say '关灯'` |
+| 看看都有什么效果 | `demo` |
+| 装好了吗 / 自检 | `doctor` |
+
+> 主题是**整套预设**（亮度 + 节奏），不是单个参数；切换会重写 flash、掉电保持。
+> `brightness` 是叠加在主题之上的全局档位；`pace` 是叠加在主题之上的**节奏档**
+> （slow/normal/fast，换主题保留，`pace normal` 恢复）；`tune` 是**主题内微调**
+> 单个状态（亮度/周期/颜色），`tune reset` 清空。
+> 下面的「安装与自检 / 硬性规则 / 协议」是**高级参考**，用户没问就别主动讲。
+
+### 钩子策略：AI 必读（用户安装时做的选择）
+
+安装器会问用户「AI 在什么时候亮什么灯」，并把每个时机的选择写进技能目录的
+`hook_choices.json`。**每次会话开始读一次，严格遵守**：
+
+- `choice: "preset"` —— 钩子脚本已直接切灯，你不用管。
+- `choice: "skip"` —— 用户明确不要这个时机有动作，**别自作主张补灯效**。
+- `choice: "ai-decide"` —— 用户把决策权交给你：按此刻真实语义用 `state` / `say`
+  切灯（动手 working、提问工具前 ask、收工 idle、出错 error）。
+- `choice: "custom"` —— 按 `text` 里用户的**原话**执行：翻译成 `say '<原话>'`
+  或对应的 `state` / `theme` / `brightness`，立刻让灯带体现出来。
+
+钩子触发时 `rgb-light.sh event <事件>` 会把同样的指令打进上下文，看到就照做。
+任何选择都不得违背 `lighting.json` 的 `design`（中轴生长、禁止白色）。
+用户想改配置：让他跑 `npx @zke-wuhu/agent-only-rgb hooks`（不用重装），
+**不要**让他手改 JSON。
+
+## 安装与自检（高级参考；客户直接跑 `quickstart` 即可）
+
+最省事的是 `python ble_sop8.py quickstart`：它把下面这些步骤一次性全做完。以下是拆开的高级用法：
+
+灯效要自动亮，需要把本技能挂到 WorkBuddy 的钩子上（会话开始/结束、助手开始/停止干活时触发）。
+**客户不需要理解"钩子"是什么**——一条命令全部搞定：
+
+```bash
+# 第一次安装 / 换机器时跑一次：自动装钩子脚本、合并写进 settings.json、装依赖（hidapi）
+python ble_sop8.py setup
+
+# 之后随时自检：报告"脚本在不在 / 钩子绑没绑 / 依赖齐不齐 / 设备连没连"，缺哪样给哪样的修复命令
+python ble_sop8.py doctor
+
+# 把所有灯效依次打在真实灯带上对照实物（加效果名则只演示那一种，如 demo expand）
+python ble_sop8.py demo
+
+# 总亮度（全局压暗所有效果，写进 lighting.json 的 master 并下发 flash；掉电保持）
+python ble_sop8.py brightness 50     # 设 50%
+python ble_sop8.py brightness        # 查看当前
+```
+
+- `setup` **幂等**：重复跑不会重复写，也不会覆盖其它工具的钩子（只按 `hook_choices.json` 的选择合并本技能需要的那几条；选了「不绑定」会把旧绑定清掉）。`--tool .claude` 可指定绑定到别的 AI 工具。
+- 钩子脚本自带**自修复**：运行时若发现缺依赖（如 hidapi），会自己尝试安装并打印明确提示，绝不会静默黑灯、也绝不阻塞你的流程（任何失败都只提示、最终 exit 0）。
+- 想先看会改什么、先不动手：`python ble_sop8.py setup --dry`。
+- 绑定规则全部声明在技能目录的 `skill_hooks.json` 里（事件、matcher、依赖），`setup`/`doctor`/钩子脚本都读它，**单一事实源**。
+
+> 若以后给技能加了 npm 依赖：只要把包名写进 `skill_hooks.json` 的 `dependencies.npm` 数组，
+> `setup` 会自动装、`doctor` 会自动校验、钩子脚本也会自动修复——客户依旧无需"意识到"要绑。
+
+## 状态灯：由钩子驱动，AI 默认不插手（零 token）
+
+- **默认（钩子模式，`ai_supervise=auto` 且有钩子）**：状态切换全自动，你**从不**发任何灯效命令。用户发消息→working 金、会话开始→session-start 绿铺满、**你准备提问（调 AskUserQuestion）前→ask 绿**、一轮结束→idle 淡蓝、会话结束→fade 灭。用户回答后 UserPromptSubmit 自动把灯转回金色。**全程零 token。**
+- **AI 监管模式（`ai_supervise`）**：每次会话开始先读技能目录 `hook_choices.json` 里的 `ai_supervise`：
+  - `auto`（默认）：有钩子靠钩子（你别管，零 token）；无钩子时自动降级为 AI 兜底（下方"手动"规则生效，会消耗少量 token）。
+  - `on`：每轮你都主动监管灯带（手动规则生效，含提问前切 ask）。
+  - `off`：你完全不碰灯，纯靠钩子/手动。
+- **仅在 `ai_supervise=on`（或 auto 且无钩子）这种兜底情况下，才手动切灯**：
+  - **准备提问前**：`state ask`（绿）——和 AskUserQuestion 同一条消息先后发出；用户回答后立刻 `working` 或 `idle`。
+  - **动手前**：`state working` —— 本轮第一条命令。
+  - **收工前**：`state idle` 作为本轮最后一条命令。
+  - 只用 `state <name>`（idle/working/ask/error/done），**不要用 `scene <数字>`**。
+- **你绝不需要轮询灯的状态**。钩子会保持状态、设备有租约兜底；不要为了"灯还亮不亮"反复跑 `status`/`state`。怀疑灯死了，跑一次 `brief` 即可，别在循环里轮询。
+
+## 什么时候用哪条命令
+
+| 用户说 | 执行 |
+|---|---|
+| 灯变红 / 设成 #FF0000 / 变成绿色 | `py -3 __SKILL_DIR__/ble_sop8.py led FF0000` |
+| 呼吸灯 / 慢闪 / 快闪 / 跑马灯 | `py -3 __SKILL_DIR__/ble_sop8.py led FF0000 --stat breathe` |
+| 调亮度 | 追加 `--brightness 40`（1–100） |
+| 调呼吸/闪烁速度 | 追加 `--period 2000`（毫秒，越大越慢） |
+| 要灯一直亮着不灭 | 追加 `--forever`（默认 60 秒后设备自动熄灭） |
+| 指定亮多久 | 追加 `--hold 300`（秒，1–254） |
+| 关灯 | `py -3 __SKILL_DIR__/ble_sop8.py off` |
+| 切到某个任务状态（空闲/执行中/有提问/出错/完成） | `py -3 __SKILL_DIR__/ble_sop8.py state working` |
+| 接了多少颗灯珠 / 外接 100 颗 | `py -3 __SKILL_DIR__/ble_sop8.py count` / `count 101`（外接 100 颗 = 链上 101） |
+| 每颗灯珠单独给颜色（渐变、彩虹） | `py -3 __SKILL_DIR__/ble_sop8.py colors FF0000,FF7F00,00FF00,...` |
+| 把状态表一次性写进设备 | `py -3 __SKILL_DIR__/ble_sop8.py profile default`（或自己的 JSON） |
+| 设备连上了吗 / 什么版本 | `py -3 __SKILL_DIR__/ble_sop8.py info` |
+| 灯效还在吗 / 现在显示什么（巡检） | `py -3 __SKILL_DIR__/ble_sop8.py status` |
+| 升级固件 / 刷这个包 | `py -3 __SKILL_DIR__/ble_sop8.py ota <文件.ota>` |
+| 有没有新固件 / 检查更新 | `py -3 __SKILL_DIR__/ble_sop8.py check` |
+| 升级到最新版本 | `py -3 __SKILL_DIR__/ble_sop8.py update` |
+| 强制重刷当前版本 | `py -3 __SKILL_DIR__/ble_sop8.py update --force` |
+| 没插 USB / 想走蓝牙 | 上面任意命令**前面加** `--ble`，如 `py -3 __SKILL_DIR__/ble_sop8.py --ble info` |
+
+## 硬性规则（别踩坑）
+
+1. **颜色只有 3/3/2 位精度**。硬件协议把 RGB 压成一个字节，所以 `#FF0000` 会显示成偏暗的红，
+   `#808080` 会变成接近黑。要"亮红"用 `FF0000`，要"亮白"用 `FFFFFF`。别承诺精确色值。
+2. **`--stat` 可选值**：`on`（常亮，默认）、`breathe`（呼吸）、`blink`（慢闪）、
+   `fast`（快闪）、`marquee`（跑马灯，亮度波沿灯带摆锤流动）、`expand`（中心扩散，
+   双波从灯带中点向两端跑，到头驻留后中心重生）、`off`。
+   **灯效是租约，默认 60 秒**：设备自己倒计时，到点熄灭——所以助手被停止、进程被杀、
+   USB 拔掉，灯都不会一直亮着。要长时间保持就加 `--forever`，要指定时长加 `--hold 秒`。
+   连续发 `led` 会续约，不用手动清理。
+3. **升级只能刷 `.ota` 包**，不能刷裸 `.bin`。`.ota` 是加密过的，脚本里没有密钥，
+   解密和设备校验都在设备里做。拿错包会直接报"不是 .ota 文件"。
+4. **升级过程中不要拔线**。整个过程约 10–60 秒，冒号后面会打进度。
+   设备在 APP 也能直接刷：脚本会先发 `ERASE` 把设备切到 AGENT（灯变蓝、会复位一次）。
+   BLE 下这一步要等 5–20 秒（Windows 清理旧链路），属正常现象，别急着重试。
+5. **只能升不能降**。设备记录了最低允许版本，旧包会被拒绝并报 `ROLLBACK`，
+   不会把固件刷坏。要回退只能整片重烧。
+6. 报错 `没找到设备` → 检查 USB 线（要能传数据，不是纯充电线），换一个口重试；
+   或者加 `--ble` 走蓝牙（需 `pip install bleak`）。
+   报错 `缺少 hidapi` → `pip install hidapi`。
+7. **`check` / `update` 默认只看 npm 包里自带的固件**（`firmware/` 目录，离线就能升）。
+   固件升级靠 `npm update @zke-wuhu/agent-only-rgb` 拿到带新固件的新包，再 `update` 刷设备；
+   **产品不再依赖任何外部远程仓库**。想用本地镜像（U 盘/内网/产线），加
+   `--repo <本地目录>`（远程 URL 也支持，但非默认）。本机升过的版本记在
+   `~/.agent-only-rgb/state.json`，所以 `update` 不会重复刷同一个版本；要重刷加 `--force`。
+8. 用户说"升级"但没说版本时：先 `check` 把固件源最新版本、设备当前版本和
+   `本地记录` 念给用户；有新版本再 `update`，别跳过 check 直接刷。
+9. **重复的状态切换别重发整条灯效**。设备里存着"任务状态表"（档案），状态都遵循
+   "光从中点向两边生长、对称双向"的设计，**没有白色**；语义命令用
+   `state idle|working|ask|error|done`（别自己记数字），`state off` 关灯；要换配色/周期
+   才用 `profile <json>` 重写档案。（钩子模式下这些由钩子自动保证，你不需要手动管。）
+10. **灯珠数量是设备事实，不要猜**。要报数量先 `count`（读设备）。用户说换了灯带
+    才 `count <n>`（会写 flash，重启保持）。`colors` 和 `scene` 都受这个数量约束，
+    超出范围的灯珠不会被点亮。
+11. **不要轮询灯状态**。在钩子模式下灯效由钩子自动保持，设备有租约兜底，你**不需要**
+    为了确认"灯还亮不亮"而反复跑 `status`/`state`、更不要按固定间隔（每 30~60 秒）巡检。
+    怀疑灯真的死了，跑一次 `brief` 即可；除非用户明确要求，否则不要自作主张重发灯效。
+
+## 定制灯效：所有灯光配置都由主机下发（固件里没有写死）
+
+灯光参数全部来自 `__SKILL_DIR__/lighting.json`（状态表 + 14 项调参 + 16 点呼吸曲线），
+用 `lighting apply` 写进设备 flash，断电保持。**用户要改灯效时改这份 JSON 或改参数，
+不要改固件源码、也不要说"得重新烧固件"。**
+
+| 用户说 | 执行 |
+|---|---|
+| 呼吸更慢 / 更快，闪得更快 | `tuning set breathe_ms=3000 --save`（同理 blink_slow_ms / blink_fast_ms） |
+| 呼吸的"手感"要改（谷底停顿、冲顶快慢） | `curve set 0,0,0,0,2,7,... --save`（16 点，0..255，单调不减） |
+| 待机/执行/提问/出错的配色和节奏要换 | 改 `lighting.json` 的 `states`（或写一份自己的 JSON）→ `lighting apply [文件]` |
+| 看设备里现在到底存了什么 | `lighting show` |
+| 改坏了 / 恢复默认 | `lighting reset`，或 `lighting apply default` |
+
+`lighting apply` 的顺序：SET_CONFIG（调参）→ SET_CURVE（曲线）→ PROFILE（状态表）→
+COMMIT_CONFIG（写 flash）→ **逐项回读校验**。哪一项回读不一致都会报错并指出名字，
+不要忽略报错、也不要靠"再发一次"掩盖。
+
+14 项调参（`tuning get` 也会打印名字/当前值/范围）：
+
+| 名字 | 范围 | 作用 |
+|---|---|---|
+| `hue_fade_ms` | 100–2000 | 换色时的色相过渡时长 |
+| `val_fade_ms` | 100–2000 | 亮度过渡时长 |
+| `floor_q8` | 4–64 | 亮度最低值（呼吸谷底不完全熄灭） |
+| `tail_ticks` | 8–335 | 跑马灯拖尾长度（10ms/tick） |
+| `head_ticks` | 4–320 | 跑马灯头部长度 |
+| `ease_floor_q8` | 13–255 | 缓动下限 |
+| `turn_hold_perm` | 0–500 | 转向保持（千分比） |
+| `turn_fade_perm` | 100–1000 | 转向淡出（千分比） |
+| `breathe_ms` | 500–10000 | 呼吸一个来回的周期（毫秒） |
+| `blink_slow_ms` | 200–10000 | 慢闪周期 |
+| `blink_fast_ms` | 200–10000 | 快闪周期 |
+| `marquee_step_ms` | 20–10000 | 跑马灯每颗间距（毫秒） |
+| `ttl_s` | 60–3600 | 默认租约（多少秒后自动熄灭） |
+| `refresh_div` | 1–6 | 灯带刷新分频（1 最流畅 / 6 最省电） |
+
+`curve` 的 16 个点是呼吸**上升沿**的亮度采样（0..255，从左到右），固件在点之间线性插值，
+下降沿自动镜像。想"谷底停顿更久"就把前几个点保持为 0；想"更快冲到顶"就抬高后段。
+
+**规则**：`lighting apply` 整份覆盖调参 + 曲线 + 状态表；只微调一两项用 `tuning set`
+（不加 `--save` 只改本次运行，断电或重启就回到 flash 里的值）。改完用 `status` 看效果。
+
+## 用灯带表示"助手自己在干什么"
+
+下面这张表定义**灯语语义**。在默认钩子模式下这些状态由钩子**自动**实现（UserPromptSubmit→working、PreToolUse/AskUserQuestion→ask、Stop→idle 等），你不用手动切，也**不要**手动切——手动切会和钩子打架、白费 token。
+
+> 仅当 `ai_supervise=on`（或 auto 且无钩子）的兜底情况下，才按这张表用 `state <name>` 切灯；默认模式下一律不执行。
+
+| 我的真实状态 | 命令 | 灯 |
+|---|---|---|
+| 空闲，没有任务在跑 | `state idle` | 淡蓝中心向外扩散（慢、暗），不用白色 |
+| 正在读代码 / 跑命令 / 构建 / 抓数据 | `state working` | 金色中心向外扩散 |
+| 这一轮回复里我提了问题、在等用户回答 | `state ask` | 绿色中心向外扩散（慢） |
+| 出错 / 卡住 / 需要人工介入 | `state error` | 红色中心向外扩散（快） |
+| 刚干完、想给个完成提示（一次性） | `state done` | 绿色从中间铺满+余晖，约 8 秒后自动灭 |
+| 用户说关灯 | `state off` | 灭 |
+
+兜底模式下的硬规则（默认模式不执行）：
+
+1. **动手前先切**：本轮**第一个工具调用之前**跑 `state working`。
+2. **结束必回 idle**：把 `state idle` 作为本轮**最后一条命令**，再写最终答复。
+3. **ask 只给真问题**：调用 `AskUserQuestion` 之前先发 `state ask`（绿），与提问工具**同一条消息先后发出**；用户回答后立刻改：继续干 → `working`，干完了 → `idle`。
+4. **输出前自查**：发消息前确认灯显示的是此刻真实状态，不一致就先改再发。
+5. `ai_supervise=off` 或 `auto`（有钩子）时，以上规则一律不执行——钩子已自动实现语义，你手动切反而会和钩子打架、浪费 token。
+6. **绝不轮询**：不要为了确认灯亮不亮而反复跑 `status`/`state`；怀疑灯死了跑一次 `brief` 即可。
+
+## 典型对话
+
+> 用户：把灯调成蓝色呼吸
+> → `py -3 __SKILL_DIR__/ble_sop8.py led 0000FF --stat breathe`
+
+> 用户：现在版本多少？能升级吗？
+> → 先 `info`，再根据 `加密升级` 那行回答；能升就用 `ota`
+
+> 用户：我下载了 app.ota，刷一下
+> → `py -3 __SKILL_DIR__/ble_sop8.py ota app.ota`，边跑边把进度念给用户
+
+> 用户：帮我升级到最新版本
+> → 先 `check`，把"远程最新 img_ver / 设备当前版本 / 本地记录"念给用户；
+>   有新版本再跑 `update`（会自己下载并刷写），最后再用 `info` 确认版本
+
+## 协议说明（内部实现，外部无需了解）
+
+灯带通过 USB HID / BLE 与主机通信，固件升级走加密包。这些都是**内部实现细节**，
+AI 与用户都**不需要、也不应该**去了解或复现协议——所有操作都通过上面的命令表完成。
+不要试图手动构造报文或自行实现刷机工具。