前言¶
用智能体或 DSH 办公时，桌面上的花再 Halo PixelBar 往往要靠本机脚本或单独记一套 HID 命令。想在对话里说一句「屏上打个『在』」就要先切终端、查参数，和「工具即对话」的习惯不一致。dsh-pixelbar 把设备控制收成 DSH 里的单个工具 pixelbar，背后再带一套可单独运行的 Python HID 脚本；两层可以分开用，也可以只装插件外壳。
这是什么¶
dsh-pixelbar 是维护者 SilverlingFox 发布的 客户端 类 DSH 插件：插件外壳通过 Cordis 补丁注册工具，实际设备通信由 bundled 的 halo_pixelbar.py 等脚本完成。它解决的是「像素屏推字、切场景、改屏色、氛围灯、硬件音量」在 Harness 里不可直接调用的问题。
- 目录页：skillhub.cn/plugins/SilverlingFox/dsh-pixelbar
- 源码与文档：github.com/SilverlingFox/dsh-pixelbar
- npm 包名：
dsh-pixelbar（README 标明当前发布版本对应 package 为 1.0.1，许可证 MIT）
核心功能¶
README 中列出的能力如下，均属已文档化行为。
| 能力 | 说明 |
|---|---|
| 推文字 | 最多 16 字符 / 48 字节；7 种颜色、6 种布局（含左右滚动） |
| 自动回时钟 | 推字后默认 15 秒切回时钟，避免通知长期占屏 |
| 场景 | clock / game / work / read / cats / dogs / memes / cyber / waves |
| 屏主题色 | 内置颜色校准表，补偿屏体 R 偏弱、B 偏强 |
| 氛围灯 | 6 种灯效，可调颜色、亮度、速度 |
| 硬件音量 | 查询或设置 0–16 |
| 状态 | 检查控制接口是否在线 |
每次调用会起一个短命的 Python 进程，未引入长驻桥；README 在 Windows 11 + Python 3.13 下写明 status 约 137 ms、text 约 73 ms（环境不同会有差异）。
环境与硬件¶
- 操作系统：脚本针对 Windows（
windowsHide+pythonw.exe避免黑框）；Linux / macOS 未做适配。 - 设备：花再 Halo PixelBar，USB 连接；文档给出
VID 0x2D99/PID 0xA106，控制接口interface=4、usage_page=0xFF14、usage=0x01，其它型号未实测。 - Python 3.8+，需安装
hidapi：
python -m pip install hidapi
- Node.js 18+：仅 DSH 插件外壳需要（
package.json中engines.node为>=18）。
安装与启用¶
README 提供三种等价路径，未使用 dsh plugin add github:... 一类拼写；以下命令均来自官方说明。
方式一：npm 或 DSH 插件市场¶
包已发布到 npm：
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 插件市场 / 插件管理中安装同名包。
方式二：离线脚本（免 npm）¶
- 双击
apply.bat，或执行pwsh -File apply.ps1。 - 脚本会定位 profile（可用环境变量
DSH_PROFILE_DIR覆盖），把index.js、package.json、cordis.patch.yml、scripts/复制到 profile 下node_modules\dsh-pixelbar，并写入dsh.profile.bundles；原package.json备份为package.json.pixelbar.bak。 - 重启 DSH，在新会话里让助手调用
pixelbar验证。
卸载：运行 rollback.bat 后重启 DSH。若在 profile 里执行 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 |
六位十六进制，用于 screen / light |
effect |
breathing color_tide static ripple flow dynamic |
brightness |
low medium high |
speed |
氛围灯速度 1–10 |
volume |
0–16；省略则查询 |
clock_restore |
推字后多少秒回时钟，默认 15；0 表示不回 |
典型调用示例（与 README 一致）：
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 单独用脚本¶
HID 层不依赖 DSH，可在 scripts 目录直接调用，便于排错或写自己的自动化：
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 light --effect breathing --color "#F0B4C8" --brightness high --speed 5
python halo_pixelbar.py volume
python halo_pixelbar.py volume 10
适用场景与注意¶
适合谁：已在 Windows 上使用 DSH、并已连接 Halo PixelBar，希望助手用自然语言改屏显、场景和灯效，而不想每次手写 HID 或维护多套脚本的开发者。
权限与安全：插件与 Python 脚本以当前 DSH 进程权限在本机执行，会通过 USB HID 控制外设。安装前应阅读仓库源码与 MIT 许可证，确认 profile 与 node_modules\dsh-pixelbar 中的文件来源可信。
已知限制（README 原文）：
- 屏宽有限，emoji 不显示；颜文字类 ASCII 可用。
- 高频推送每次新起 Python 进程，不适合极高频场景。
- 场景 / 灯效 ID 来自单机实测，固件不同可能不一致。
- 推送成功但屏无变化时，设备可能处于音乐律动等抢占模式，可先切回
clock场景。
社区目录站点 skillhub.cn 与 DeepSeek / 幻方无官方从属关系；DSH 生态以「一切皆插件」为常见做法，本文仅介绍该插件本身的行为与安装方式。
结尾¶
dsh-pixelbar 把 Halo PixelBar 收成 DSH 里的 pixelbar 工具，并保留完整 Python HID 工具链；适合要在对话里控桌面像素屏、又需要命令行兜底的本机用户。更多细节与 HID 帧格式见 GitHub README；插件入口见 目录页 与 仓库。
