前言¶
用智能體或 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；插件入口見 目錄頁 與 倉庫。
