dsh-mchose-battery

Readme

# dsh-mchose-battery

**简体中文** | [English](README.en.md)

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

<table>
  <tr>
    <td align="center">
      <img src="./image/screenshot-1.png" alt="效果图1" width="360" /><br/>
      <em>2.4G 模式效果</em>
    </td>
    <td align="center">
      <img src="./image/screenshot-2.png" alt="效果图2" width="360" /><br/>
      <em>USB 接线模式效果</em>
    </td>
  </tr>
</table>

它直接从浏览器通过 **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` 安装（推荐）

```bash
# 从 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 的机器：

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

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

```yaml
- 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**](INSTALL.md)。

---

## WebHID 授权（首次使用）

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

1. 鼠标已连接（有线 **或** 通过 2.4G 接收器）。
2. 在列表中选择 Mchose 设备。
3. 点击 **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`）

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

## License

MIT