dsh-mchose-battery: DSH 플러그인 설치 및 GitHub 가이드

최근 디렉터리 동기화에서 이 README 스냅샷을 새로 고치지 못했습니다.

dsh-mchose-battery

简体中文 | English

这是一个 DSH（DeepSeek Harness）客户端插件，通过 WebHID 在侧边栏（设置按钮上方）实时显示迈从（Mchose）无线鼠标的电量与连接模式（2.4G / USB）。

2.4G 模式效果

USB 接线模式效果

它直接从浏览器通过 WebHID 读取鼠标——无需配套软件、无需驱动、无需后台进程。每 5 秒刷新一次，并会自动跟随鼠标在有线 USB 与 2.4G 接收器之间切换。

需要 DSH Web 图形界面（http://127.0.0.1:3080），profile 为 web。

功能特性

🪫 实时电量百分比（每 5 秒更新）
🔌 连接模式：2.4G / USB
⚡ 充电状态指示
🎯 侧边栏控件，位于设置按钮正上方（无背景条，灰色图标 + 文字）
🔄 自动检测有线 ↔ 无线切换（5 秒轮询 + 断开事件）

工作原理

插件读取设备的 HID 配置接口（usagePage 0xFF01，VID 0x3837）：

在报告 0x11 上发送 profile-reload 命令
鼠标在输入报告 0x13 上推送 E2 状态报告
报告经 XOR 解码得到电量百分比 / 充电状态 / 设备名
有线 USB = PID 0x4018，2.4G 接收器 = PID 0x100A

前提条件

已安装 DSH，并使用 web profile（Web 图形界面）
支持 WebHID 的浏览器：Chrome / Edge（桌面版）。Firefox 和 Safari 不支持 WebHID。
首次使用需授权鼠标：浏览器会弹出 WebHID 设备选择提示——必须选择 Mchose 鼠标并点击 Connect（连接）。

安装

本插件是一个 profile bundle（包内声明了 dsh.bundle.patch），可用 DSH 自带插件命令直接安装——无需手动编辑补丁。bundle 补丁会自动把插件注册为宿主 entry，进而让 DSH 把它的 WebHID 客户端 bundle 提供给浏览器。

方式一：通过 `dsh plugin` 安装（推荐）

# 从 dsh-mchose-battery 发布的 registry 安装
dsh plugin --profile web add dsh-mchose-battery

搞定。dsh plugin add 会执行 pnpm add、检测到 dsh.bundle 声明，并把包加入 profile 的 bundle 层。然后重启 DSH 并强制刷新（Ctrl+Shift+R）。

想从本地代码库测试而非 registry，也可以用路径： dsh plugin --profile web add ./publish/dsh-mchose-battery

方式二：手动复制

适合不方便使用 dsh plugin / pnpm 的机器：

# 把整个文件夹放到 DSH 能解析的位置
git clone <你的仓库> "$USERPROFILE\.dsh\node_modules\dsh-mchose-battery"

并在 ~/.dsh/profiles/web/cordis.patch.yml 中注册一行：

- insert:
    - id: mchose-battery
      name: dsh-mchose-battery

然后重启 DSH 并强制刷新 Web 界面（Ctrl+Shift+R）。打开控制台应能看到：

[mchose] loaded v4 (polling, no auto-flip)

⚠️ 因为 DSH 在启动时缓存客户端 bundle 的版本号，安装/升级后一般需要重启 DSH（仅刷新页面可能无效）。

面向同事的逐步安装说明：INSTALL.md。

WebHID 授权（首次使用）

第一次（以及浏览器"忘记"设备后），DSH 会弹出 WebHID 设备选择器。请确保：

鼠标已连接（有线或通过 2.4G 接收器）。
在列表中选择 Mchose 设备。
点击 Connect（连接）。

之后侧边栏控件会显示如 78% · 2.4G 或 USB · 100% · ⚡。

故障排查

现象	处理
侧边栏一直显示"连接迈从鼠标"	WebHID 授权未通过——点击控件 / 允许设备
显示"WebHID 不可用"	不是 Chrome/Edge，或 WebHID 被禁用
电量一直显示 `--`	设备不在预期接口上；检查控制台的 `raw=` 十六进制
拔掉 USB 后显示未切换	应在约 5 秒内自动纠正（轮询）；仍未切则重启 DSH

开发

本插件是一个普通的 npm 包：

lib/index.js — 宿主端（空实现）
lib/client.js — 浏览器客户端（WebHID），由 DSH 的客户端 bundle 机制提供
package.json — dsh.client 元数据（platform: "web"、immediately: true）

node --check lib/client.js   # 语法检查

License

MIT

Fransice / dsh-mchose-battery

설치

README