npm - @zke-wuhu/agent-only-rgb - Versions diffs - 0.8.4 → 0.8.5 - Mend

@zke-wuhu/agent-only-rgb 0.8.4 → 0.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +226 -231
package/assets/SKILL.md +3 -4
package/assets/ble_sop8.py +6 -6
package/assets/firmware/manifest.json +1 -1
package/assets/ota_client.py +370 -371
package/assets/ota_source.py +11 -11
package/assets/rgb-light.sh +1 -1
package/assets/skill_hooks.json +2 -2
package/package.json +50 -50
package/setup.js +783 -847
package/tests/interactive-install.js +11 -0
package/tests/pty-install.py +12 -1

package/README.md CHANGED Viewed

@@ -1,231 +1,226 @@
-# 让 AI 干活的时候，桌上的灯带跟着变色
-一块 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 脚本里）
-- 所有脚本**不含任何密钥**，可以放心分发
+# 让 AI 干活的时候，桌上的灯带跟着变色
+一块 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 <命令>`。
+## 装完我能干嘛
+在 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 CHANGED Viewed

@@ -150,8 +150,7 @@ python ble_sop8.py brightness        # 查看当前
    **灯效是租约，默认 60 秒**：设备自己倒计时，到点熄灭——所以助手被停止、进程被杀、
    USB 拔掉，灯都不会一直亮着。要长时间保持就加 `--forever`，要指定时长加 `--hold 秒`。
    连续发 `led` 会续约，不用手动清理。
-3. **升级只能刷 `.ota` 包**，不能刷裸 `.bin`。`.ota` 是加密过的，脚本里没有密钥，
-   解密和设备校验都在设备里做。拿错包会直接报"不是 .ota 文件"。
+3. **升级只能刷 `.ota` 包**，不能刷裸 `.bin`。包内容由设备负责校验。拿错包会直接报"不是 .ota 文件"。
 4. **升级过程中不要拔线**。整个过程约 10–60 秒，冒号后面会打进度。
    设备在 APP 也能直接刷：脚本会先发 `ERASE` 把设备切到 AGENT（灯变蓝、会复位一次）。
    BLE 下这一步要等 5–20 秒（Windows 清理旧链路），属正常现象，别急着重试。
@@ -251,7 +250,7 @@ COMMIT_CONFIG（写 flash）→ **逐项回读校验**。哪一项回读不一
 > → `py -3 __SKILL_DIR__/ble_sop8.py led 0000FF --stat breathe`
 > 用户：现在版本多少？能升级吗？
-> → 先 `info`，再根据 `加密升级` 那行回答；能升就用 `ota`
+> → 先 `info`，再根据 `升级支持` 那行回答；能升就用 `ota`
 > 用户：我下载了 app.ota，刷一下
 > → `py -3 __SKILL_DIR__/ble_sop8.py ota app.ota`，边跑边把进度念给用户
@@ -262,6 +261,6 @@ COMMIT_CONFIG（写 flash）→ **逐项回读校验**。哪一项回读不一
 ## 协议说明（内部实现，外部无需了解）
-灯带通过 USB HID / BLE 与主机通信，固件升级走加密包。这些都是**内部实现细节**，
+灯带通过 USB HID / BLE 与主机通信，固件升级走正式发布包。这些都是**内部实现细节**，
 AI 与用户都**不需要、也不应该**去了解或复现协议——所有操作都通过上面的命令表完成。
 不要试图手动构造报文或自行实现刷机工具。

package/assets/ble_sop8.py CHANGED Viewed

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""bleAgentRGB SOP8 设备命令行（用户侧，**不含任何密钥**）。
+"""bleAgentRGB SOP8 设备命令行（用户侧）。
 AI 助手通过这个脚本来"使用设备"：看状态、改灯效、升级固件。
@@ -8,7 +8,7 @@ AI 助手通过这个脚本来"使用设备"：看状态、改灯效、升级固
     python ble_sop8.py led 00FF00 --stat breathe --period 2000 --brightness 60
     python ble_sop8.py led 00FF00 --forever      # 常亮，不自动熄灭
     python ble_sop8.py off                       # 关灯
-    python ble_sop8.py ota app.ota               # 刷加密固件包
+    python ble_sop8.py ota app.ota               # 刷固件包
     python ble_sop8.py check                     # 去远程仓库看有没有新固件
     python ble_sop8.py update                    # 检查 + 下载 + 升级到最新
     python ble_sop8.py --ble led FF0000          # 走蓝牙（需 pip install bleak）
@@ -1986,9 +1986,9 @@ def cmd_info(dev):
     if r[2] == 1:
         health = {0: "可用", 1: "试跑中", 2: "已损坏"}.get(r[29], r[29])
         print("APP 健康  : %s（tries %d/%d）" % (health, r[30], r[31]))
-        print("加密升级  : %s" % ("支持（v%d）" % r[32] if r[32] >= 2
+        print("升级支持  : %s" % ("支持（v%d）" % r[32] if r[32] >= 2
                                    else "不支持（老固件）"))
-        print("密钥编号  : %d%s" % (r[33], "（未写密钥，无法加密升级）"
+        print("设备批次  : %d%s" % (r[33], "（未初始化，无法升级）"
                                    if r[33] == 0 else ""))
         if len(r) >= 38:
             print("最低版本  : %d（低于它的包会被拒，防回滚）"
@@ -1997,7 +1997,7 @@ def cmd_info(dev):
 def cmd_ota(ota_path, use_ble=False, dry_run=False):
-    """交给零密钥客户端；本脚本不碰密钥。"""
+    """交给升级客户端处理。"""
     client = os.path.join(_HERE, "ota_client.py")
     if not os.path.exists(client):
         sys.exit("找不到 ota_client.py（安装不完整，重跑安装器）")
@@ -2221,7 +2221,7 @@ def main():
                          help="idle=空闲 working=执行中 ask=有未回答的问题 "
                               "error=出错 done=完成提示(8s) off=关灯 "
                               "fade=逐渐熄灭 session-start=绿色铺开后逐渐熄灭")
-    p_ota = sub.add_parser("ota", help="刷加密固件包")
+    p_ota = sub.add_parser("ota", help="刷固件包")
     p_ota.add_argument("file", help=".ota 路径")
     p_ota.add_argument("--dry-run", action="store_true",
                        help="只校验包结构，不连设备")

package/assets/firmware/manifest.json CHANGED Viewed

@@ -4,6 +4,6 @@
     "img_ver": 40,
     "sha256": "524640d1ef3b43e447af0c3961aaebb528507f61080eb40f386b3c6ee3f7e4b7",
     "file": "AgentRGB_SOP8_v40.ota",
-    "notes": "v40（zke-wuhu）：USB 产品名 zke-wuhu；板载 1 颗状态指示（暗青常亮，不受灯效影响）+ 外接灯带最多 100 颗；新增 fill 类灯效（中心向两边一次性铺满）与节奏档 pace。加密零密钥包，解密与校验都在设备内完成。"
+    "notes": "v40（zke-wuhu）：USB 产品名 zke-wuhu；板载 1 颗状态指示（暗青常亮，不受灯效影响）+ 外接灯带最多 100 颗；新增 fill 类灯效（中心向两边一次性铺满）与节奏档 pace。"
   }
 }