dsh-pixelbar 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SilverlingFox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# dsh-pixelbar
 
-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.
+把「花再 Halo PixelBar」桌面像素屏变成 DSH 里可直呼的工具——推一行字、切场景、改屏色、调氛围灯、控音量，全部一句话搞定。
+
+聊天里不用再记命令、也不用先翻文档：在 DSH 里直接说「像素屏推个『在』」，`pixelbar` 工具就发过去了。
+
+> DSH 插件外壳 + 独立可用的 Python HID 脚本，两层都能单独跑。
+
+## 特性
+
+| 能力 | 说明 |
+| --- | --- |
+| 推文字 | 16 字符 / 48 字节上限，7 种颜色、6 种布局（含左右滚动） |
+| 自动回时钟 | 推完默认 15 秒切回时钟界面，避免通知一直挂在屏上 |
+| 场景切换 | clock / game / work / read / cats / dogs / memes / cyber / waves |
+| 屏主题色 | 带颜色校准表，补偿这块屏的 R 偏弱、B 偏强的色偏 |
+| 氛围灯 | 6 种灯效 + 颜色 + 亮度 + 速度 |
+| 硬件音量 | 查询 / 设置 0–16 |
+| 状态检查 | 查控制接口是否在线 |
+
+实测延迟（Windows 11 + Python 3.13）：`status` 约 137 ms，`text` 推送约 73 ms。每次调用起一个短命 python 进程，没引入长驻桥。
+
+## 环境要求
+
+- Windows（脚本用 `windowsHide` + `pythonw.exe` 规避黑框闪烁，其他平台未验证）
+- 花再 Halo PixelBar 设备，USB 连接
+- Python 3.8+
+- `hidapi`：
+
+  ```powershell
+  python -m pip install hidapi
+  ```
+
+- Node.js 18+（仅 DSH 插件外壳需要）
+
+> 设备标识：`VID 0x2D99 / PID 0xA106`，控制接口 `interface=4`、`usage_page=0xFF14`、`usage=0x01`。其它型号未经实测，协议可能不同。
+
+## 安装（DSH 插件）
+
+任选一种。
+
+### 方式一：npm / 插件市场
+
+包已发布：[`dsh-pixelbar`](https://www.npmjs.com/package/dsh-pixelbar)
+
+```powershell
+npm install dsh-pixelbar
+```
+
+装进 DSH profile 目录（`%USERPROFILE%\.dsh\profiles\desktop`），再把 `dsh-pixelbar` 加进该目录 `package.json` 的 `dsh.profile.bundles` 数组，重启 DSH 即可。包里的 `package.json` 声明了 `dsh.bundle: { patch: "./cordis.patch.yml" }`，DSH 会据此加载插件。
+
+> 也可以直接在 DSH 的插件市场 / 插件管理里安装 `dsh-pixelbar`，效果相同。
+
+### 方式二：脚本（离线、免 npm）
+
+1. 双击 `apply.bat`（或 `pwsh -File apply.ps1`）
+
+   脚本会：探测 `%USERPROFILE%\.dsh\profiles\desktop`（找不到就取唯一候选，或用 `DSH_PROFILE_DIR` 指定）→ 复制 `index.js / package.json / cordis.patch.yml / scripts/` 到 profile 的 `node_modules\dsh-pixelbar` → 把 `dsh-pixelbar` 登记进 `dsh.profile.bundles`。原 `package.json` 会备份成 `package.json.pixelbar.bak`。
+
+2. 重启 DSH，新会话里让助手推一句到像素屏验证。
+
+卸载：`rollback.bat`，再重启 DSH。
+
+> 插件目录被复制进 `node_modules`，所以 `pnpm install` 之类操作后可能需要重跑 `apply.ps1`。
+
+## 在 DSH 里用
+
+插件注册单个工具 `pixelbar`：
+
+| 参数 | 值 |
+| --- | --- |
+| `action` | `text`（默认）/ `scene` / `screen` / `light` / `volume` / `clock` / `status` |
+| `text` | 要显示的文字，超过 16 字符自动截断 |
+| `color` | `white` `red` `green` `blue` `yellow` `cyan` `magenta`，默认 `magenta` |
+| `layout` | `left` `center` `right` `stretch` `scroll_left_to_right` `scroll_right_to_left` |
+| `scene` | 见上方场景列表 |
+| `hex` | `#F0B4C8` 这种六位十六进制，用于 `screen` / `light` |
+| `effect` | `breathing` `color_tide` `static` `ripple` `flow` `dynamic` |
+| `brightness` | `low` `medium` `high` |
+| `speed` | `light` 速度 1–10 |
+| `volume` | 0–16；不填 = 查询 |
+| `clock_restore` | 推完多少秒回时钟，默认 15；`0` = 不回 |
+
+例：
+
+- `pixelbar { "text": "在", "color": "cyan" }`
+- `pixelbar { "action": "scene", "scene": "work" }`
+- `pixelbar { "action": "light", "effect": "breathing", "hex": "#F0B4C8", "brightness": "high" }`
+
+## 配置
+
+默认值在 `cordis.patch.yml` 的 `config` 里，工程里对应 `index.js` 的 `DEFAULTS`：
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `python` | 空 | 留空自动探测：环境变量 `DSH_PIXELBAR_PYTHON` → PATH 上的 `python3` / `python` |
+| `script` | `scripts/halo_pixelbar.py` | 相对路径相对于插件目录；也可写绝对路径 |
+| `clockScript` | `scripts/clock_restore.py` | 同上 |
+| `defaultColor` | `magenta` | 默认文字色 |
+| `restoreSeconds` | `15` | 默认回时钟秒数 |
+
+## 独立使用（不经 DSH）
+
+脚本不依赖 DSH，可以单独当命令行工具用：
+
+```powershell
+cd scripts
+
+python halo_pixelbar.py list                  # 列出控制接口
+python halo_pixelbar.py text "在" --color cyan --layout center
+python halo_pixelbar.py ui work               # 切场景
+python halo_pixelbar.py color "#F0B4C8"       # 屏主题色（自动校准）
+python halo_pixelbar.py color "#FF0000" --raw # 跳过校准
+python halo_pixelbar.py light --effect breathing --color "#F0B4C8" --brightness high --speed 5
+python halo_pixelbar.py lightpower off
+python halo_pixelbar.py volume                # 查询
+python halo_pixelbar.py volume 10
+
+python clock_restore.py 20                    # 20 秒后回时钟
+python color_calib.py                         # 色卡，用于目测校准
+```
+
+## HID 协议
+
+真机实测的帧格式（64 字节 HID Output Report）：
+
+```text
+主机请求: 2E AA ED <cmd> <len-hi> <len-lo> <payload...> <checksum> <00 填充>
+设备响应: 2F BB EC <cmd> <len-hi> <len-lo> <payload...> <checksum> <00 填充>
+校验和:   sum(packet[1:]) & 0xFF      # 从 AA 开始求和取低 8 位
+```
+
+| 命令 | 用途 | payload |
+| --- | --- | --- |
+| `0xE8` | 文字 | `00 utf8_len utf8_bytes...` |
+| `0xEF` | 布局 | `01 R G B 00 02 <scroll> <mode> FF` |
+| `0xEF` | 场景 | `02 R G B 00 01 <scene_id> FF FF` |
+| `0xEF` | 屏色 | `03 R G B 00 00 FF FF FF` |
+| `0x6B` | 氛围灯 | `13 <effect> R G B <brightness> <speed>`，**需连发 3 次、间隔 30 ms** |
+| `0x66` | 查询音量 | 空 |
+| `0x67` | 设置音量 | `volume` |
+
+枚举值：
+
+- 场景：`clock=0 game=1 work=2 read=3 cats=4 dogs=5 memes=6 cyber=7 waves=8`
+- 布局 `(scroll, mode)`：`left=(0,0) center=(0,1) right=(0,2) stretch=(0,3) scroll_left_to_right=(1,0) scroll_right_to_left=(1,1)`
+- 灯效：`breathing=1 color_tide=2 static=3 ripple=4 flow=5 dynamic=6`
+- 亮度：`low=0x14 medium=0x28 high=0x3C`
+- 文字颜色：`white=0 red=1 green=2 blue=3 yellow=4 cyan=5 magenta=6`
+
+## 颜色校准
+
+这块屏的 R 通道增益偏低、B 偏强，直接发 sRGB 值会偏青/偏紫。`halo_pixelbar.py` 里内置一张目测校准表（`CALIBRATION`），屏色和布局 RGB 会自动查表替换；文字颜色走硬件枚举，不受影响。
+
+`docs/color-card.html` 是配套的色卡页面：在电脑屏幕上显示标准色，和音箱屏对比，看出偏差后改 `CALIBRATION` 里的映射。
+
+## 已知限制
+
+- 屏幕只有 16 字符 / 48 字节位宽，emoji 不显示，颜文字 `^_^ QAQ (T_T)` 可用。
+- 每次调用新起 python 进程（约 40 ms 启动 + HID 打开），高频推送不建议。
+- 场景 ID、灯效 ID 来自单台设备实测，固件不同可能错位。
+- 只会用 `pythonw.exe` 规避 Windows 控制台闪窗；Linux / macOS 未做适配。
+
+## 排错
+
+| 现象 | 处理 |
+| --- | --- |
+| `未找到 Halo PixelBar 控制接口` | 检查 USB 连接；`python scripts\halo_pixelbar.py list` 看接口是否枚举出来 |
+| `[!] 需要 hid 库` | `python -m pip install hidapi` |
+| 推送成功但屏上没变 | 设备可能处于音乐律动等抢占模式，先切回 `clock` 场景 |
+| 插件加载了但工具报找不到脚本 | 重跑 `apply.ps1`，确认 `node_modules\dsh-pixelbar\scripts\` 存在 |
+
+## 致谢
+
+HID 帧格式最初参考 [Seraph310/halo-pixelbar-mcp](https://github.com/Seraph310/halo-pixelbar-mcp) 的实测结论，后续在本机逐条验证并整理。
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# dsh-pixelbar —— DSH bundle patch（挂载声明）
+# apply.ps1 会把本目录复制到 profile 的 node_modules\，随 DSH 启动加载。
+- insert:
+    - id: dsh-pixelbar
+      name: dsh-pixelbar
+      config:
+        # python：留空 = 自动探测（环境变量 DSH_PIXELBAR_PYTHON → PATH 上的 python3 / python）
+        # script / clockScript：留空 = 使用包内 scripts/ 下的脚本
+        # 需要指定时取消注释并改写：
+        # python: 'C:\Python313\python.exe'
+        # script: 'scripts/halo_pixelbar.py'
+        defaultColor: magenta
+        restoreSeconds: 15

package/index.js

@@ -0,0 +1,239 @@
+import { spawn } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-pixelbar'
+export const inject = ['tools']
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+const DEFAULTS = {
+  // 留空 = 自动探测：环境变量 DSH_PIXELBAR_PYTHON → PATH 上的 python3 / python
+  python: '',
+  // 留空 = 用包内 scripts/ 下的脚本；相对路径相对于本文件所在目录
+  script: join(HERE, 'scripts', 'halo_pixelbar.py'),
+  clockScript: join(HERE, 'scripts', 'clock_restore.py'),
+  defaultColor: 'magenta',
+  restoreSeconds: 15,
+}
+
+const PYTHON_ENV = 'DSH_PIXELBAR_PYTHON'
+
+const COLORS = ['white', 'red', 'green', 'blue', 'yellow', 'cyan', 'magenta']
+const LAYOUTS = ['left', 'center', 'right', 'stretch', 'scroll_left_to_right', 'scroll_right_to_left']
+const SCENES = ['clock', 'game', 'work', 'read', 'cats', 'dogs', 'memes', 'cyber', 'waves']
+const EFFECTS = ['breathing', 'color_tide', 'static', 'ripple', 'flow', 'dynamic']
+const LEVELS = ['low', 'medium', 'high']
+
+// python.exe 是控制台程序，detached 启动时 Windows 会闪一下黑框；
+// 换成 GUI 子系统的 pythonw.exe 就永远不会分配控制台窗口
+function guiPython(python) {
+  if (!/python\.exe$/i.test(String(python))) return python
+  const w = String(python).replace(/python\.exe$/i, 'pythonw.exe')
+  try {
+    return existsSync(w) ? w : python
+  } catch (e) {
+    return python
+  }
+}
+
+// 在 PATH 里找可执行文件，跳过 WindowsApps 那种 0 字节的商店 stub
+function which(cmd) {
+  const isWin = process.platform === 'win32'
+  const exts = isWin
+    ? String(process.env.PATHEXT || '.EXE;.COM;.BAT;.CMD').split(';').filter(Boolean)
+    : ['']
+  const names = /\.[a-z0-9]+$/i.test(cmd)
+    ? [cmd]
+    : exts.flatMap((e) => [cmd + e.toLowerCase(), cmd + e.toUpperCase()])
+  const dirs = String(process.env.PATH || '').split(isWin ? ';' : ':').filter(Boolean)
+  for (const dir of dirs) {
+    for (const n of names) {
+      const p = join(dir, n)
+      try {
+        if (existsSync(p) && statSync(p).size > 0) return p
+      } catch (e) {
+        // 无权限等，跳过
+      }
+    }
+  }
+  return null
+}
+
+function resolvePython(cfg) {
+  const explicit = String(cfg.python || process.env[PYTHON_ENV] || '').trim()
+  if (explicit) return guiPython(explicit)
+  const found = which('python3') || which('python')
+  return guiPython(found || 'python')
+}
+
+function resolveAsset(value, fallback) {
+  const raw = String(value || '').trim()
+  if (!raw) return fallback
+  return isAbsolute(raw) ? raw : join(HERE, raw)
+}
+
+function runPy(python, args, timeoutMs) {
+  return new Promise((resolve) => {
+    let out = ''
+    let err = ''
+    let settled = false
+    const done = (r) => { if (!settled) { settled = true; resolve(r) } }
+    let child
+    try {
+      child = spawn(python, args, {
+        windowsHide: true,
+        env: Object.assign({}, process.env, { PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1' }),
+      })
+    } catch (e) {
+      return done({ ok: false, out: '', err: String((e && e.message) || e) })
+    }
+    const timer = setTimeout(() => {
+      try { child.kill() } catch (e) { /* ignore */ }
+      done({ ok: false, out: out.trim(), err: err.trim() || '超时 ' + timeoutMs + 'ms' })
+    }, timeoutMs)
+    child.stdout.on('data', (d) => { out += d.toString('utf8') })
+    child.stderr.on('data', (d) => { err += d.toString('utf8') })
+    child.on('error', (e) => { clearTimeout(timer); done({ ok: false, out: out.trim(), err: String((e && e.message) || e) }) })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      done({ ok: code === 0, out: out.trim(), err: err.trim() })
+    })
+  })
+}
+
+function scheduleClockRestore(python, clockScript, seconds) {
+  try {
+    const child = spawn(python, [clockScript, String(seconds)], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      env: Object.assign({}, process.env, { PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1' }),
+    })
+    child.unref()
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+function tail(text, n) {
+  const t = String(text || '').trim()
+  const limit = n || 300
+  return t.length > limit ? '…' + t.slice(-limit) : t
+}
+
+export function apply(ctx, config) {
+  const cfg = Object.assign({}, DEFAULTS, config || {})
+  const python = resolvePython(cfg)
+  const script = resolveAsset(cfg.script, DEFAULTS.script)
+  const clockScript = resolveAsset(cfg.clockScript, DEFAULTS.clockScript)
+
+  const tool = {
+    name: 'pixelbar',
+    description:
+      '把短句推到桌面的 Halo PixelBar 像素屏（限 16 字符 / 48 字节，不要用 emoji，可用 ^_^ QAQ (T_T) 之类颜文字）；' +
+      '推完默认 15 秒自动切回时钟。也能切场景、屏色、氛围灯、音量、查设备是否在线。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['text', 'scene', 'screen', 'light', 'volume', 'clock', 'status'],
+          description: '默认 text。text=推文字；scene=切场景；screen=设屏色；light=氛围灯；volume=音量；clock=立刻回时钟；status=查设备',
+        },
+        text: { type: 'string', description: 'action=text 时要显示的文字（超过 16 字符会被截断）' },
+        color: { type: 'string', enum: COLORS, description: '文字颜色，默认 magenta' },
+        layout: { type: 'string', enum: LAYOUTS, description: '可选：文字布局 left/center/right/stretch/滚动' },
+        scene: { type: 'string', enum: SCENES, description: 'action=scene 时的场景名' },
+        hex: { type: 'string', description: 'action=screen / light 时的颜色，如 #F0B4C8（屏色自动套校准表）' },
+        effect: { type: 'string', enum: EFFECTS, description: 'action=light 的灯效，默认 breathing' },
+        brightness: { type: 'string', enum: LEVELS, description: 'action=light 的亮度，默认 medium' },
+        speed: { type: 'number', description: 'action=light 的速度 1-10，默认 5' },
+        volume: { type: 'number', description: 'action=volume 的音量 0-16；不填=查询当前音量' },
+        clock_restore: { type: 'number', description: '推完多少秒切回时钟，默认 15；0=不回时钟' },
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render(_args, value) { return [{ type: 'text', text: value }] },
+    },
+    timeoutMs: 25000,
+    async execute(args) {
+      const a = args || {}
+      const action = String(a.action || (a.text ? 'text' : 'status'))
+
+      if (!existsSync(script)) {
+        return '找不到像素屏脚本：' + script + '（检查插件是否完整安装，或在 config.script 里指定路径）'
+      }
+
+      if (action === 'text') {
+        const raw = String(a.text || '').replace(/\s+/g, ' ').trim()
+        if (!raw) return '（没有要推的文字）'
+        const shown = Array.from(raw).slice(0, 16).join('')
+        const color = COLORS.indexOf(a.color) >= 0 ? a.color : cfg.defaultColor
+        const argv = [script, 'text', shown, '--color', color]
+        if (LAYOUTS.indexOf(a.layout) >= 0) argv.push('--layout', a.layout)
+        const r = await runPy(python, argv, 12000)
+        if (!r.ok) return '推送失败：' + (tail(r.err) || tail(r.out) || '未知错误')
+        const rest = Number(a.clock_restore)
+        const seconds = Number.isFinite(rest) ? rest : (Number(cfg.restoreSeconds) || 15)
+        const restored = seconds > 0 ? scheduleClockRestore(python, clockScript, seconds) : false
+        const cut = raw !== shown ? '（已截到 16 字符）' : ''
+        let note = ''
+        if (seconds > 0) note = '；' + seconds + ' 秒后回时钟' + (restored ? '' : '（回时钟命令启动失败）')
+        return '已推到像素屏：' + shown + cut + '；颜色 ' + color + note
+      }
+
+      if (action === 'scene') {
+        if (SCENES.indexOf(a.scene) < 0) return 'scene 需为：' + SCENES.join('/')
+        const r = await runPy(python, [script, 'ui', a.scene], 12000)
+        return r.ok ? '已切场景：' + a.scene : '切场景失败：' + (tail(r.err) || tail(r.out))
+      }
+
+      if (action === 'screen') {
+        const hex = String(a.hex || '').trim()
+        if (!/^#?[0-9a-fA-F]{6}$/.test(hex)) return 'hex 需形如 #F0B4C8'
+        const r = await runPy(python, [script, 'color', hex], 12000)
+        return r.ok ? '已设屏色：' + (tail(r.out, 120) || hex) : '设屏色失败：' + (tail(r.err) || tail(r.out))
+      }
+
+      if (action === 'light') {
+        const h = String(a.hex || '').trim()
+        const hex = /^#?[0-9a-fA-F]{6}$/.test(h) ? h : '#F0B4C8'
+        const argv = [script, 'light',
+          '--effect', EFFECTS.indexOf(a.effect) >= 0 ? a.effect : 'breathing',
+          '--color', hex,
+          '--brightness', LEVELS.indexOf(a.brightness) >= 0 ? a.brightness : 'medium']
+        const sp = Number(a.speed)
+        if (Number.isFinite(sp)) argv.push('--speed', String(Math.max(1, Math.min(10, Math.round(sp)))))
+        const r = await runPy(python, argv, 12000)
+        return r.ok ? '氛围灯已设：' + tail(r.out, 120) : '氛围灯失败：' + (tail(r.err) || tail(r.out))
+      }
+
+      if (action === 'volume') {
+        const has = a.volume !== undefined && a.volume !== null && a.volume !== ''
+        const argv = has
+          ? [script, 'volume', String(Math.max(0, Math.min(16, Math.round(Number(a.volume) || 0))))]
+          : [script, 'volume']
+        const r = await runPy(python, argv, 12000)
+        return r.ok ? (tail(r.out, 120) || '已执行') : '音量操作失败：' + (tail(r.err) || tail(r.out))
+      }
+
+      if (action === 'clock') {
+        const r = await runPy(python, [script, 'ui', 'clock'], 12000)
+        return r.ok ? '已切回时钟' : '切时钟失败：' + (tail(r.err) || tail(r.out))
+      }
+
+      const r = await runPy(python, [script, 'list'], 12000)
+      if (!r.ok) return '设备未找到：' + (tail(r.err) || tail(r.out))
+      return '设备在线：' + tail(r.out, 200)
+    },
+  }
+
+  const register = () => ctx.tools.register(tool)
+  if (typeof ctx.effect === 'function') ctx.effect(register, 'dsh-pixelbar: pixelbar tool')
+  else register()
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "dsh-pixelbar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "DSH 插件：把花再 Halo PixelBar 桌面像素屏变成常驻工具（推文字 / 切场景 / 屏色 / 氛围灯 / 音量）",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "halo-pixelbar",
+    "pixelbar",
+    "hid",
+    "edifier",
+    "pixel-display"
+  ],
+  "homepage": "https://github.com/SilverlingFox/dsh-pixelbar#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SilverlingFox/dsh-pixelbar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SilverlingFox/dsh-pixelbar/issues"
+  },
+  "author": "SilverlingFox",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/scripts/clock_restore.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""像素屏通知延迟回时钟：推送内容后调用本脚本，delay 秒后自动切回时钟界面
+
+用法:
+    python clock_restore.py [delay秒]   # 默认 15 秒
+    python clock_restore.py 20          # 20 秒后回时钟
+
+内部实现：前台 sleep 后调用 halo_pixelbar.py ui clock（脚本保持运行直到切换完成）
+"""
+import subprocess
+import sys
+import time
+import os
+
+HALO = os.path.join(os.path.dirname(os.path.abspath(__file__)), "halo_pixelbar.py")
+
+
+def restore_clock(delay: float = 15.0):
+    time.sleep(delay)
+    subprocess.run(
+        [sys.executable, HALO, "ui", "clock"],
+        capture_output=True, timeout=30,
+    )
+    return True
+
+
+if __name__ == "__main__":
+    delay = float(sys.argv[1]) if len(sys.argv) > 1 else 15.0
+    restore_clock(delay)
+    print(f"[OK] 已切回时钟界面（{delay} 秒后）")

package/scripts/color_calib.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Halo PixelBar 颜色校准辅助：轮流显示基准色卡，供目测比对
+
+用法:
+    python color_calib.py              # 完整色卡，每色停 4 秒
+    python color_calib.py --single "#FF8800"   # 只显示一个颜色，停 10 秒
+"""
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from halo_pixelbar import HaloPixelBar
+
+# 基准色卡（目标色）：纯色 + 常用色
+COLOR_CARD = [
+    ("纯红",    "#FF0000"),
+    ("纯绿",    "#00FF00"),
+    ("纯蓝",    "#0000FF"),
+    ("纯白",    "#FFFFFF"),
+    ("青色",    "#00FFFF"),
+    ("黄色",    "#FFFF00"),
+    ("品红",    "#FF00FF"),
+    ("默认粉",  "#F0B4C8"),
+    ("橙色",    "#FF8800"),
+    ("天蓝",    "#66AFFF"),
+]
+
+DWELL = 4  # 每个颜色停留秒数
+
+
+def main():
+    # 支持 --single 只显示单个颜色
+    if len(sys.argv) > 1 and sys.argv[1] == "--single" and len(sys.argv) > 2:
+        show_single(sys.argv[2])
+        return
+
+    bar = HaloPixelBar()
+    try:
+        bar.connect()
+        print(f"[OK] 色卡开始，共 {len(COLOR_CARD)} 色，每色 {DWELL} 秒（总约 {len(COLOR_CARD) * DWELL}s）")
+        print("注意看屏幕颜色与标注的偏差！")
+        for name, hexc in COLOR_CARD:
+            bar.set_screen_color(hexc)
+            bar.send_text(name, layout="center")
+            print(f"  显示: {name} ({hexc})")
+            time.sleep(DWELL)
+        # 恢复默认
+        bar.set_screen_color("#F0B4C8")
+        bar.set_scene("clock")
+        print("[OK] 色卡结束，已恢复")
+    except Exception as e:
+        print(f"[FAIL] {e}")
+    finally:
+        bar.close()
+
+
+def show_single(hexc: str):
+    """只显示一个颜色（用于二次确认）"""
+    bar = HaloPixelBar()
+    try:
+        bar.connect()
+        bar.set_screen_color(hexc)
+        bar.send_text(hexc, layout="center")
+        print(f"[OK] 已显示 {hexc}，停留 10 秒")
+        time.sleep(10)
+        bar.set_scene("clock")
+    except Exception as e:
+        print(f"[FAIL] {e}")
+    finally:
+        bar.close()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/halo_pixelbar.py

@@ -0,0 +1,405 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+HALO PIXELBAR 像素屏操控器（墨漓自制 v2）
+=======================================
+基于 Seraph310/halo-pixelbar-mcp 实测协议（2026-07-19 真机验证）。
+
+帧格式（64 字节 HID Output Report，接口 usage_page=0xFF14）：
+  主机请求: 2E AA ED <cmd> <len-hi> <len-lo> <payload...> <checksum> <00 填充>
+  设备响应: 2F BB EC <cmd> <len-hi> <len-lo> <payload...> <checksum> <00 填充>
+  校验和: sum(packet[1:]) & 0xFF（从 AA 开始求和，取低 8 位）
+
+命令：
+  0xE8 文本:   payload = [0x00, utf8_len, utf8_bytes...]   (文本限 16 字符/48 字节)
+  0xEF 像素设置: 9 字节 payload
+    布局:   01 R G B 00 02 <scroll> <mode> FF
+    场景:   02 R G B 00 01 <scene_id> FF FF
+    屏色:   03 R G B 00 00 FF FF FF
+  0x6B 氛围灯: [0x13, effect, R, G, B, brightness, speed]（需连发 3 次，间隔 30ms）
+  0x66 查询音量 / 0x67 设置音量
+
+用法:
+  python halo_pixelbar.py list
+  python halo_pixelbar.py text "你好墨漓" --color cyan --layout center
+  python halo_pixelbar.py layout scroll_r2l
+  python halo_pixelbar.py ui clock
+  python halo_pixelbar.py volume 10
+  python halo_pixelbar.py light --effect breathing --color #F0B4C8 --brightness high
+"""
+
+import sys
+import time
+import argparse
+from enum import IntEnum
+
+try:
+    import hid
+    HAS_HID = True
+except ImportError:
+    HAS_HID = False
+
+VENDOR_ID = 0x2D99
+PRODUCT_ID = 0xA106
+INTERFACE_NUMBER = 4
+CONTROL_USAGE_PAGE = 0xFF14
+CONTROL_USAGE = 0x01
+PACKET_LEN = 64
+FRAME_TYPE = 0xED  # 帧类型字节（MCP 实测）
+LIGHTING_WRITE_REPETITIONS = 3
+LIGHTING_WRITE_DELAY = 0.03
+
+
+class TextColor(IntEnum):
+    WHITE = 0
+    RED = 1
+    GREEN = 2
+    BLUE = 3
+    YELLOW = 4
+    CYAN = 5
+    MAGENTA = 6
+
+
+SCENES = {
+    "clock": 0, "game": 1, "work": 2, "read": 3,
+    "cats": 4, "dogs": 5, "memes": 6, "cyber": 7, "waves": 8,
+}
+
+LAYOUTS = {
+    "left": (0, 0), "center": (0, 1), "right": (0, 2),
+    "stretch": (0, 3),
+    "scroll_left_to_right": (1, 0), "scroll_right_to_left": (1, 1),
+}
+
+EFFECTS = {"breathing": 1, "color_tide": 2, "static": 3, "ripple": 4, "flow": 5, "dynamic": 6}
+BRIGHTNESS = {"low": 0x14, "medium": 0x28, "high": 0x3C}
+
+DEFAULT_RGB = (0xF0, 0xB4, 0xC8)  # 默认粉紫
+
+# ============================================================
+# 颜色校准表（2026-08-01 君辞目测校准）
+# 屏幕特性：R 通道增益低、G 居中、B 偏强 → 含红颜色偏青/偏紫
+# 格式: 目标色(大写hex) -> 补偿色(发到屏幕的值)
+# ============================================================
+CALIBRATION = {
+    "#FF0000": "#FF0303",  # 红: 偏深 → 微提亮
+    "#00FF00": "#03FF03",  # 绿: 偏深 → 微提亮
+    "#0000FF": "#0000FF",  # 蓝: 准
+    # 白 #FFFFFF 跳过（君辞不用白色）
+    "#00FFFF": "#00FFD0",  # 青: 偏蓝 → 减B
+    "#FFFF00": "#FF8800",  # 黄: 君辞钦定（#FF8800 显示效果最像目标黄）
+    "#FF00FF": "#FF00D0",  # 品红: 偏紫 → 减B
+    "#F0B4C8": "#FF6080",  # 默认粉: 偏青 → R拉满压G/B（接近屏极限）
+    "#FF8800": "#FF6000",  # 橙: 偏黄 → 减G
+    "#66AFFF": "#80C0FF",  # 天蓝: 偏深 → 提亮
+}
+
+
+def apply_calibration(color_hex: str) -> str:
+    """应用颜色校准（精确匹配目标色，无匹配则原样返回）"""
+    key = color_hex.strip().upper()
+    if not key.startswith("#"):
+        key = "#" + key
+    return CALIBRATION.get(key, color_hex)
+
+
+def _calibrate_rgb(rgb: tuple) -> tuple:
+    """把 RGB tuple 应用校准后转回 tuple"""
+    h = "#%02X%02X%02X" % tuple(rgb)
+    h = apply_calibration(h)
+    c = h.lstrip("#")
+    return tuple(int(c[i:i + 2], 16) for i in (0, 2, 4))
+
+
+def _pad(data) -> bytes:
+    packet = bytes(data)
+    if len(packet) > PACKET_LEN:
+        return packet[:PACKET_LEN]
+    return packet + bytes(PACKET_LEN - len(packet))
+
+
+def _edifier_packet(command: int, payload) -> bytes:
+    """MCP 实测帧格式: 2E AA ED <cmd> <len-be> <payload> <sum(packet[1:])&0xFF>"""
+    body = bytes(payload)
+    packet = bytearray([0x2E, 0xAA, FRAME_TYPE, command,
+                        (len(body) >> 8) & 0xFF, len(body) & 0xFF])
+    packet.extend(body)
+    packet.append(sum(packet[1:]) & 0xFF)
+    return _pad(packet)
+
+
+def build_text_packet(text: str, color: TextColor = TextColor.WHITE) -> bytes:
+    """文本包: 0xE8, payload = [0x00, utf8_len, utf8_bytes...]（限 16 字符/48 字节）"""
+    text = text.strip()[:16]
+    tb = text.encode("utf-8")
+    while len(tb) > 48:
+        text = text[:-1]
+        tb = text.encode("utf-8")
+    return _edifier_packet(0xE8, [0x00, len(tb), *tb])
+
+
+def build_layout_packet(layout: str, rgb: tuple = DEFAULT_RGB) -> bytes:
+    """布局包: 0xEF, payload = [01 R G B 00 02 scroll mode FF]（RGB 自动校准）"""
+    scroll, mode = LAYOUTS[layout]
+    r, g, b = _calibrate_rgb(rgb)
+    return _edifier_packet(0xEF, [0x01, r, g, b, 0x00, 0x02, scroll, mode, 0xFF])
+
+
+def build_scene_packet(scene: str, rgb: tuple = DEFAULT_RGB) -> bytes:
+    """场景包: 0xEF, payload = [02 R G B 00 01 scene_id FF FF]（RGB 自动校准）"""
+    scene_id = SCENES[scene]
+    r, g, b = _calibrate_rgb(rgb)
+    return _edifier_packet(0xEF, [0x02, r, g, b, 0x00, 0x01, scene_id, 0xFF, 0xFF])
+
+
+def build_screen_color_packet(color_hex: str) -> bytes:
+    """像素屏主题色: 0xEF, payload = [03 R G B 00 00 FF FF FF]（自动应用校准）"""
+    color_hex = apply_calibration(color_hex)
+    c = color_hex.strip().lstrip("#")
+    rgb = tuple(int(c[i:i + 2], 16) for i in (0, 2, 4))
+    return _edifier_packet(0xEF, [0x03, *rgb, 0x00, 0x00, 0xFF, 0xFF, 0xFF])
+
+
+def build_ambient_packet(effect: str, color_hex: str, brightness: str, speed: int) -> bytes:
+    """氛围灯: 0x6B, payload = [13 effect R G B brightness speed]"""
+    c = color_hex.strip().lstrip("#")
+    rgb = tuple(int(c[i:i + 2], 16) for i in (0, 2, 4))
+    return _edifier_packet(0x6B, [0x13, EFFECTS[effect], *rgb, BRIGHTNESS[brightness], speed])
+
+
+def build_ambient_power_packet(enabled: bool) -> bytes:
+    return _edifier_packet(0x6B, [0x00, 0x00, 0x00, 0x00, int(enabled), 0xFF, 0xFF])
+
+
+def build_volume_query_packet() -> bytes:
+    return _edifier_packet(0x66, [])
+
+
+def build_volume_set_packet(volume: int) -> bytes:
+    return _edifier_packet(0x67, [max(0, min(16, volume))])
+
+
+def find_devices():
+    """查找 Halo PixelBar 像素屏控制接口（interface=4, usage_page=FF14）"""
+    found = []
+    for d in hid.enumerate(VENDOR_ID, PRODUCT_ID):
+        if int(d.get("interface_number", -1)) != INTERFACE_NUMBER:
+            continue
+        if int(d.get("usage_page", 0)) != CONTROL_USAGE_PAGE:
+            continue
+        if int(d.get("usage", 0)) != CONTROL_USAGE:
+            continue
+        found.append(d)
+    return found
+
+
+class HaloPixelBar:
+    def __init__(self):
+        self.dev = None
+        self.device_info = None
+
+    def connect(self):
+        devs = find_devices()
+        if not devs:
+            raise RuntimeError("未找到 Halo PixelBar 控制接口（检查 USB 连接）")
+        last_err = ""
+        for attempt in range(5):
+            for d in devs:
+                dev = hid.device()
+                try:
+                    dev.open_path(d["path"])
+                    r = dev.write(build_text_packet(""))
+                    if r >= 0:
+                        self.dev = dev
+                        self.device_info = d
+                        return d
+                    dev.close()
+                except Exception as e:
+                    last_err = str(e)
+                    try:
+                        dev.close()
+                    except Exception:
+                        pass
+            time.sleep(0.6)
+        raise RuntimeError(f"连接失败: {last_err}")
+
+    def send(self, packet: bytes, consume_response: bool = True) -> int:
+        """发送数据包；写入后尝试读取设备响应（避免响应队列堵塞）"""
+        if not self.dev:
+            raise RuntimeError("未连接")
+        r = self.dev.write(packet)
+        if r < 0:
+            return r
+        if consume_response:
+            try:
+                self.dev.read(64, timeout_ms=100)
+            except Exception:
+                pass
+        return r
+
+    def send_text(self, text: str, color: TextColor = TextColor.WHITE, layout: str = None):
+        if layout is not None:
+            self.send(build_layout_packet(layout))
+            time.sleep(0.05)
+        return self.send(build_text_packet(text))
+
+    def set_layout(self, layout: str):
+        return self.send(build_layout_packet(layout))
+
+    def set_scene(self, scene: str):
+        return self.send(build_scene_packet(scene))
+
+    def set_screen_color(self, color_hex: str):
+        return self.send(build_screen_color_packet(color_hex))
+
+    def set_light(self, effect: str, color_hex: str, brightness: str, speed: int):
+        pkt = build_ambient_packet(effect, color_hex, brightness, speed)
+        # 灯光命令需连发 3 次（间隔 30ms）才生效
+        last = -1
+        for i in range(LIGHTING_WRITE_REPETITIONS):
+            last = self.send(pkt, consume_response=False)
+            if last < 0:
+                break
+            if i + 1 < LIGHTING_WRITE_REPETITIONS:
+                time.sleep(LIGHTING_WRITE_DELAY)
+        return last
+
+    def set_light_power(self, enabled: bool):
+        return self.send(build_ambient_power_packet(enabled))
+
+    def get_volume(self) -> dict:
+        self.send(build_volume_query_packet(), consume_response=False)
+        try:
+            resp = self.dev.read(64, timeout_ms=1000)
+        except Exception:
+            return {}
+        if resp and bytes(resp[:4]) == bytes([0x2F, 0xBB, 0xEC, 0x66]):
+            payload = bytes(resp[6:6 + ((resp[4] << 8) | resp[5])])
+            if len(payload) >= 2:
+                return {"maximum": payload[0], "current": payload[1]}
+        return {}
+
+    def set_volume(self, volume: int):
+        return self.send(build_volume_set_packet(volume))
+
+    def close(self):
+        if self.dev:
+            try:
+                self.dev.close()
+            except Exception:
+                pass
+            self.dev = None
+
+
+def main():
+    if not HAS_HID:
+        if "--quiet" in sys.argv:
+            return 0
+        print("[!] 需要 hid 库: pip install hidapi", file=sys.stderr)
+        return 1
+
+    ap = argparse.ArgumentParser(description="Halo PixelBar 像素屏操控器 v2")
+    ap.add_argument("--quiet", action="store_true", help="device offline: skip silently")
+    sub = ap.add_subparsers(dest="cmd")
+
+    sub.add_parser("list", help="列出控制接口")
+    p_text = sub.add_parser("text", help="显示文字")
+    p_text.add_argument("text", nargs="+")
+    p_text.add_argument("--color", default="white", help="white/red/green/blue/yellow/cyan/magenta")
+    p_text.add_argument("--layout", default=None, help="left/center/right/stretch/scroll_left_to_right/scroll_right_to_left")
+    p_layout = sub.add_parser("layout", help="设置布局")
+    p_layout.add_argument("layout", choices=list(LAYOUTS.keys()))
+    p_ui = sub.add_parser("ui", help="切换场景模式")
+    p_ui.add_argument("model", choices=list(SCENES.keys()))
+    p_color = sub.add_parser("color", help="设置像素屏主题色（自动应用校准）")
+    p_color.add_argument("hex", help="如 #F0B4C8")
+    p_color.add_argument("--raw", action="store_true", help="跳过校准，直接发原始值")
+    p_vol = sub.add_parser("volume", help="查询/设置硬件音量")
+    p_vol.add_argument("value", nargs="?", type=int, help="0-16，不填则查询")
+    p_light = sub.add_parser("light", help="氛围灯")
+    p_light.add_argument("--effect", default="breathing", choices=list(EFFECTS.keys()))
+    p_light.add_argument("--color", default="#F0B4C8")
+    p_light.add_argument("--brightness", default="medium", choices=list(BRIGHTNESS.keys()))
+    p_light.add_argument("--speed", type=int, default=5)
+    p_power = sub.add_parser("lightpower", help="氛围灯开关")
+    p_power.add_argument("on", choices=["on", "off"])
+
+    args = ap.parse_args()
+    quiet = getattr(args, "quiet", False) or "--quiet" in sys.argv
+    if not args.cmd:
+        ap.print_help()
+        return 1
+
+    if args.cmd == "list":
+        try:
+            devs = find_devices()
+        except Exception as e:
+            if quiet:
+                return 0
+            print(f"[FAIL] {e}")
+            return 1
+        if not devs:
+            if quiet:
+                return 0
+            print("未找到控制接口（检查 USB 连接）")
+            return 1
+        for d in devs:
+            print(f"  interface={d.get('interface_number')} usage_page={d['usage_page']:04X} "
+                  f"usage={d['usage']:02X} {d.get('product_string','')}")
+        return 0
+
+    bar = None
+    try:
+        bar = HaloPixelBar()
+        info = bar.connect()
+        print(f"[OK] 已连接: {info.get('product_string','')}")
+
+        if args.cmd == "text":
+            r = bar.send_text(" ".join(args.text), TextColor[args.color.upper()], args.layout)
+            print(f"[OK] 显示: {' '.join(args.text)!r} 颜色={args.color} 布局={args.layout or '保持'}")
+        elif args.cmd == "layout":
+            r = bar.set_layout(args.layout)
+            print(f"[OK] 布局: {args.layout}")
+        elif args.cmd == "ui":
+            r = bar.set_scene(args.model)
+            print(f"[OK] 场景: {args.model}")
+        elif args.cmd == "color":
+            sent = args.hex
+            if not args.raw:
+                cal = apply_calibration(args.hex)
+                if cal != args.hex:
+                    print(f"[校准] {args.hex} -> {cal}")
+                sent = cal
+            r = bar.set_screen_color(sent)
+            print(f"[OK] 屏色: {sent}")
+        elif args.cmd == "volume":
+            if args.value is None:
+                v = bar.get_volume()
+                print(f"[OK] 音量: {v.get('current','?')}/{v.get('maximum','?')}")
+            else:
+                r = bar.set_volume(args.value)
+                time.sleep(0.3)
+                v = bar.get_volume()
+                print(f"[OK] 设置音量 {args.value} -> 当前 {v.get('current','?')}")
+        elif args.cmd == "light":
+            r = bar.set_light(args.effect, args.color, args.brightness, args.speed)
+            print(f"[OK] 氛围灯: {args.effect} {args.color}")
+        elif args.cmd == "lightpower":
+            r = bar.set_light_power(args.on == "on")
+            print(f"[OK] 氛围灯: {'开' if args.on == 'on' else '关'}")
+        return 0
+    except Exception as e:
+        if quiet:
+            return 0
+        print(f"[FAIL] {e}")
+        return 1
+    finally:
+        if bar is not None:
+            try:
+                bar.close()
+            except Exception:
+                pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())