# qwen-barlight-mc

**Repository Path**: ensleep/qwen-barlight-mc

## Basic Information

- **Project Name**: qwen-barlight-mc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-04
- **Last Updated**: 2026-10-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# qwen-barlight-mc

把机械革命（MECHREVO）等**同方 / Uniwill 模具**笔记本机身上的 RGB 灯条（「海岸线」灯效）
当作 **[Qwen Code](https://qwenlm.github.io/qwen-code-docs/)** 的运行状态指示灯——
让机器用灯光告诉你 Qwen 现在是在待命、在干活、在等你确认，还是已经干完了。

| 状态 | 触发时机 | 灯条 |
| --- | --- | --- |
| 无任务 | Qwen 启动 / 回到空闲 | 绿色常亮 |
| 处理任务中 | 你提交了消息，模型在干活 | 绿紫分段流动 |
| 等待你确认 / 反馈 | 需要授权或等你回复 | 橙色常亮 |
| 任务完成 | 一个回合正常结束 | 红色常亮 |
| 回合异常结束 | 出错中断 | 红色呼吸 |
| Qwen 退出 | 会话结束 | 关灯 |

状态切换由 Qwen Code 的 hooks 自动驱动，不需要手动干预；也可以随时手动指定状态。

- 仓库：<https://gitee.com/ensleep/qwen-barlight-mc>
- 许可：MIT
- **零依赖**：只用 Windows 自带的 PowerShell（5.1+）直接 P/Invoke `hid.dll` / `setupapi.dll`
  读写 USB-HID Feature Report。不需要 .NET SDK、不需要 Node、不需要 Python、
  不需要装任何 PowerShell 模块，包里全是文本文件。

## 支持的机型

> **判定原则：看 USB 接口，不看型号名。** 只要系统能枚举出 ITE 灯条接口
> （`VID_048D`，灯条 PID 见下表），本 skill 就能用。同一套模具换牌子
> （机械革命 / 机械师 / XMG / Eluktronics / Captiva / Monster 等）灯条行为一致。
> 这一点与开源项目 [iteglow](https://github.com/JeanElsner/iteglow) 的结论一致：
> 支持与否由 `048d:7001`（灯条）/ `048d:600b`（键盘）决定，而不是由固定的型号清单决定。

### 已实测

| 机型 | 主板型号 | 灯条 |
| --- | --- | --- |
| 机械革命 耀世 16 Ultra | `YAOSHI Series-X6AR55xY` | `048d:7001`（ITE Device 8233），选择字节 `0x22` |

### 按灯条接口判定（同方 / Uniwill 系 ITE 灯条）

| 灯条 PID | 设备选择字节 | 备注 |
| --- | --- | --- |
| `0x7001` | `0x22` | `ITE Device(8233)`，最常见 |
| `0x7000` | `0x21` | |
| `0x6010` | `0x02` | |
| `0x6005` / `0x6008` | `0x02` | |

键盘接口是 `0x600B`（`ITE Device(8291)`），脚本已把它排除，不会误打到键盘上。

### 想知道自己的机器行不行

解压/克隆后跑一次只读探测（不改动任何设置）：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\LightBar.ps1 -Probe
```

输出里 `角色=灯条` 的那一行就是可用接口，会同时打印 PID 和选择字节。例如实测机器：

```
枚举到 4 个 VID_048D 的 HID 接口：
  PID=600B UsagePage=0xFF03 Usage=0x0001 In=65 Out=65 Feature=9  角色=键盘
  PID=7001 UsagePage=0xFF03 Usage=0x0002 In=65 Out=65 Feature=9  角色=灯条  选择字节=0x22
  ...
将使用：PID=7001。
```

- 有「角色=灯条」→ 能用；
- 没有 → 本机灯条不走 USB-HID（或需要先退出官方灯效控制中心）。

型号不在上表时，脚本会按「厂商 ME 第二集合（Usage=2）」兜底；仍不确定时用
`-ProductId` / `-Selector` 手工指定。

## 环境要求

- Windows 10 / 11
- Windows PowerShell 5.1 或 PowerShell 7+（系统自带 5.1 即可）
- 机器带上述 ITE USB-HID 灯条

## 安装

### 方式一：从 Gitee 在线安装（推荐）

在 **PowerShell** 里执行：

```powershell
$f = "$env:TEMP\qwen-lightbar-install.ps1"
irm https://gitee.com/ensleep/qwen-barlight-mc/raw/master/install.ps1 -OutFile $f
powershell -NoProfile -ExecutionPolicy Bypass -File $f
```

脚本发现自己不是随包运行，会自动把仓库文件从 Gitee 拉取到临时目录，再完成安装。

想写成一行也行：

```powershell
iex ((irm https://gitee.com/ensleep/qwen-barlight-mc/raw/master/install.ps1).TrimStart([char]0xFEFF))
```

> **不要写 `irm <raw 地址> | iex`。** 本仓库脚本是带 UTF-8 BOM 的（PowerShell 5.1 要靠它
> 才能正确读取中文），而 `irm` 会把 BOM 保留成字符串开头的 `U+FEFF`，直接管道给 `iex`
> 会以 `Unexpected token ')'` 之类的错误解析失败。上面两种写法分别用“先落盘再执行”和
> “显式去掉 BOM 字符”绕开这个问题。

> 若默认分支不是 `master`（比如改成了 `main`），把地址里的 `master` 换成对应分支名；
> 也可以显式指定：`.\install.ps1 -RepoUrl <地址> -Branch <分支>`。

### 方式二：克隆后安装

```powershell
git clone https://gitee.com/ensleep/qwen-barlight-mc.git
cd qwen-barlight-mc
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```

### 方式三：下载 zip 手动解压

下载仓库 zip 解压到任意目录（如 `D:\tools\qwen-barlight-mc`），在该目录执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```

### 安装脚本做了什么

- 把 skill 拷到 `%USERPROFILE%\.qwen\skills\qwen-lightbar\`；
- 备份 `%USERPROFILE%\.qwen\settings.json` 为 `settings.json.bak-qwen-lightbar`，
  再把 8 个状态灯 hook 合并进去（只摘除自己以前注册的，不动别人的 hook）；
- 写回后立刻回读校验，解析失败会自动从备份还原；
- 跑一次设备枚举自检并打印结果。

只装 skill、不碰配置文件：

```powershell
.\install.ps1 -SkipHooks
```

### 装完必做

**重启 Qwen Code**（`/exit` 后重新启动）hooks 才会生效；重启后可以用 `/hooks`
查看当前会话实际加载了哪些 hook。

## 手动使用

```powershell
# 切换状态
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.qwen\skills\qwen-lightbar\scripts\set-state.ps1" working

# 自定义颜色 / 效果
...\scripts\LightBar.ps1 -Color 00FF00,8800FF -Effect 5 -Brightness 100 -Speed 5   # 绿紫流动
...\scripts\LightBar.ps1 -Color FF8800 -Effect 1 -Brightness 100                  # 橙色常亮
...\scripts\LightBar.ps1 -Off                                                     # 关灯
...\scripts\LightBar.ps1 -Probe                                                   # 只读：枚举设备
```

状态取值：`idle` / `working` / `waiting` / `done` / `error` / `off`。

`LightBar.ps1` 参数：

| 参数 | 说明 |
| --- | --- |
| `-Color RRGGBB[,RRGGBB...]` | 颜色，多个用**逗号**分隔；多个颜色即组成调色板（自动循环填满 7 个槽位） |
| `-Effect N` | 1=常亮 2=呼吸 3=波浪 4=聚散 5=霓虹 6=跑动 |
| `-Brightness 0-100` | 亮度（灯条量程 0-100） |
| `-Speed 1-10` | 速度，1 最快 |
| `-Direction 0-2` | 0 无 / 1 右 / 2 左 |
| `-ColorIndex N` | 颜色字节：1=槽位 1 静态色（默认），8=走调色板（多色时自动用 8） |
| `-ProductId HEX`（别名 `-Pid`） | 指定灯条 HID 产品号 |
| `-Selector N` | 覆盖设备选择字节 |
| `-Off` / `-Probe` / `-FirmwareVersion` | 关灯 / 只读枚举 / 只读固件版本 |

> PowerShell 的 `-File` 调用**不支持重复参数**，`-Color a -Color b` 会报
> `ParameterAlreadyBound`，多色必须写成 `-Color a,b`。

## hooks 自动切灯

`%USERPROFILE%\.qwen\settings.json` 的 `hooks` 里注册了下列事件，全部指向
`<skill>\scripts\set-state.ps1`。会话中的事件带 `async: true`（不阻塞对话），
**只有 `SessionEnd` 是 `async: false`**——Qwen 退出时会立刻结束进程，
后台异步 hook 来不及跑完就被杀掉，灯就关不掉。

| 事件 | matcher | 状态 | async |
| --- | --- | --- | --- |
| `SessionStart` | `.*` | idle | true |
| `UserPromptSubmit` | —— | working | true |
| `PermissionRequest` | `.*` | waiting | true |
| `Notification` | `permission_prompt` | waiting | true |
| `Notification` | `idle_prompt` | idle | true |
| `Stop` | —— | done | true |
| `StopFailure` | `.*` | error | true |
| `SessionEnd` | `.*` | off | **false** |

强杀进程或直接关终端窗口时不保证触发 `SessionEnd`，灯会停在上一个状态；
下次启动的 `SessionStart → idle` 会把它纠正回绿色常亮。

## 排错

| 现象 | 原因 / 处理 |
| --- | --- |
| 报「拒绝访问 (Win32 5)」 | 灯条被厂商灯效控制中心独占，先在托盘里退出它 |
| 命令成功但灯条毫无反应 | 所有 HID 写入都会「返回成功」，**必须肉眼确认**；多半是 PID 或设备选择字节不对，用 `-Probe` 核对 |
| 灯条不动但键盘乱闪 | 打到了键盘接口，用 `-Probe` 确认 `-ProductId` |
| 开机后灯条恢复成厂商样式 | 灯条不保存状态，重启后需重新下发；`SessionStart` hook 会自动设回 `idle` |
| hooks 不生效 | 需要重启 Qwen Code；确认没开 `disableAllHooks` / 安全模式；用 `/hooks` 查看 |
| `irm` 下载失败 / 很慢 | Gitee 偶发限流或网关拦截，重试，或改用 `git clone` 方式安装 |
| `irm … \| iex` 报 `Unexpected token ')'` | 脚本带 UTF-8 BOM，管道里 BOM 变成 `U+FEFF` 破坏解析；按「方式一」先落盘或加 `.TrimStart([char]0xFEFF)` |
| 装机后中文乱码 | 本仓库脚本是带 BOM 的 UTF-8；若手工改过脚本，请保持 UTF-8 BOM，否则 PowerShell 5.1 会按 ANSI 解析 |

## 卸载

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\uninstall.ps1
```

会摘除本 skill 注册的 hook（保留其它 hook）、关闭灯条、删除安装目录。
加 `-KeepFiles` 可以只摘 hook、不删目录。

## 工作原理

9 字节 HID Feature Report，byte0 是报告 ID：

```
设效果: 00 08 SS EE PP BB CC DD SV     设颜色: 00 14 00 01 RR GG BB 00 00
```

- 第 3 字节 `PP` 是**设备选择字节，不是开关**（`0x7001`→`0x22`、`0x7000`→`0x21`、
  `0x6010`→`0x02`）。照搬键盘的 `0x02` 发往 `0x7001` 会「返回成功但灯条毫无反应」——
  这是最容易踩的坑。
- 颜色字节 `CC`：`1` = 取槽位 1 的静态色，`8` = 循环整个调色板
  （呼吸、霓虹等多色效果必须用 `8`）。
- 有没有「关灯」控制码？没有——关灯 = 静态 + 亮度 0。
- 灯条读不回状态（命令 `0x88` 恒返回 0），只能读固件版本（`0x80`）；
  状态只能由主机侧保存，每次改状态都是重新下发一遍。

协议细节参考：tuxedo-drivers `src/ite_8291_lb/ite_8291_lb.c`、
JeanElsner/iteglow `docs/protocol.md`、Gumwars/HydroControl `DESIGN.md`；
本仓库在 `0x048d:0x7001` 上实机验证过全部状态。

## 目录结构

```
qwen-barlight-mc/
├─ SKILL.md              # Qwen Code skill 定义
├─ README.md             # 本文件
├─ CHANGELOG.md
├─ LICENSE               # MIT
├─ install.ps1           # 安装（本地 / 从 Gitee 在线）
├─ uninstall.ps1         # 卸载
├─ .gitattributes        # 统一 CRLF 检出
└─ scripts/
   ├─ LightBar.ps1       # 灯条控制核心（零依赖）
   └─ set-state.ps1      # 状态 → 灯条命令，供 hooks 调用
```

## 作者

ensleep

## 许可

MIT，见 [LICENSE](LICENSE)。