前言¶

在 DSH（DeepSeek Harness）里控制米家设备，常见做法是让模型读设备状态、再生成控制指令，每次操作都会占用上下文和调用额度。若你只是想开关灯、调风速或跑一个手动场景，把整条链路都交给大模型并不划算。

下面介绍社区插件 dsh-mijia-sidebar（维护者 EchoChan314，分类：客户端）：在 DSH 侧边栏提供「米家控制」面板，设备列表、属性读写、设备动作与手动场景通过本机 mijiaAPI CLI 执行，经插件私有 RPC 通道到达 Host 半区，不经过模型回合。

这是什么¶

dsh-mijia-sidebar 是 DSH 的 bundle 插件，入口为 cordis.patch.yml，同时提供 Host 半区（lib/index.js）与浏览器半区（lib/client.js）。面板在侧边栏注册入口，打开后可刷新设备、展开卡片进行控制。

与「让模型写 mijia 命令再执行」相比，面板操作走 /mijia RPC（动作包括 snapshot、props、state、get、set、action、run_scene、setHidden 等），Host 半区直接调用 python -m mijiaAPI，不占用模型上下文。

核心功能¶

不经过大模型的控制链路¶

所有面板操作经包内 /mijia 通道（ctx.connection.register）到 Host 半区，由本机 CLI 与米家云端通信。设备列举、批量读属性、规格中文说明等还配合助手脚本 lib/state.py（list / state / spec 三种模式）。

面板能力¶

• 场景：手动场景按钮，一键 run_scene。
• 设备卡片：网格展示；展开后分「控制 / 状态 / 动作」三组。bool 用开关，enum 用选项按钮，数值用滑块加「设置」，文本可输入提交；只读属性直接显示值。
• 一次读回全部属性：展开设备时用一次云调用取该设备全部可读属性，避免对每个属性单独 get。
• 中文说明：属性名与枚举优先从 miot-spec multiLanguage 拉取（本地缓存 7 天），否则回退内置词表；枚举显示为「说明（原值）」。
• 隐藏与别名：可在面板隐藏设备并在底部恢复；按 model 配置显示别名（也可写配置文件）。
• 展开状态持久化：当前展开设备记在浏览器 localStorage。
• 内置分类图标：按型号关键字匹配线性图标；若字段带回图标地址则直接使用。

配置与日志¶

配置文件路径：$DSH_HOME/mijia-sidebar.config.json，默认 ~/.dsh/mijia-sidebar.config.json（Windows 为 %USERPROFILE%\.dsh\mijia-sidebar.config.json）。示例：

{
  "hiddenDids": ["105830834"],
  "aliases": {
    "zhimi.fan.za4": "落地扇",
    "yeelink.light.stripe": "客厅吊灯"
  }
}

环境变量：MIJIA_PYTHON 指定运行 mijiaAPI 的解释器；DSH_HOME 默认为 ~/.dsh。解释器候选顺序为 MIJIA_PYTHON → python3 → python →（仅 Windows）py -3。

改动设备的操作会写入 $DSH_HOME/mijia-sidebar.log，单文件上限 1 MiB，轮转保留一份历史。

安装与启用¶

前置条件：

1. Python ≥ 3.10，且 python3 或 python 在 PATH 中。
2. 同一解释器安装 mijiaAPI：pip install mijiaAPI 或 python -m pip install mijiaAPI。
3. 扫码登录：python -m mijiaAPI login，凭证在 ~/.config/mijia-api/auth.json（与 mijia MCP server 共用，插件不另存）。
4. DSH 需具备 Host 侧的 connection 与 webServer 服务；Node 引擎要求 ≥ 20（见 package.json）。

三种安装方式效果相同，装完后重启或刷新 DSH。Host 半区（lib/*.js、lib/*.py）有改动时，须在 DSH 里重启插件进程；仅改浏览器半区时刷新页面即可。

从本地目录安装（bundle）¶

在 DSH 会话里执行，路径指向仓库或解压目录：

plugin_manager install_bundle /path/to/dsh-mijia-sidebar

从 GitHub 获取后安装¶

git clone https://github.com/EchoChan314/dsh-mijia-sidebar.git
plugin_manager install_bundle ./dsh-mijia-sidebar

从 npm 安装¶

npm install dsh-mijia-sidebar
plugin_manager install_bundle ./node_modules/dsh-mijia-sidebar

典型用法¶

1. 完成 mijiaAPI 登录与插件安装后，在 DSH 侧边栏点击「米家控制」入口打开面板。
2. 使用顶部「刷新」拉取设备快照；在「场景」区点击如「回家」「离家」等手动场景。
3. 点击设备卡片展开：在「控制」区改开关、档位或滑块；在「动作」区点「开机」「关机」等按钮。
4. 不需要某设备时，用卡片右上角隐藏；底部「已隐藏设备」可恢复。别名可在面板操作后写回配置文件，或事先编辑 mijia-sidebar.config.json 中的 aliases。

写入属性后面板会先乐观更新再回读比对（米家云端立即回读常返回旧值），最多重试几次。

适用场景与注意¶

适合谁：已在 DSH 日常开发或对话中使用、家里设备接入米家、希望侧边栏一点就控、且愿意在本机维护 Python 与 mijiaAPI 登录态的开发者或高级用户。

权限与安全：插件以当前 DSH 进程权限运行，会启动本机 Python 调用 mijiaAPI；安装前建议阅读仓库源码与 MIT 许可证。列表下发到浏览器半区的设备字段仅 did、name、model、spec_type、online、icon 六项，不含 token、localip 等；凭证仅由 mijiaAPI 读写，插件不复制转发。需要属性中文说明时会请求 miot-spec.org（不含设备信息与凭证），结果缓存在 ~/.config/mijia-api/<spec_type>.lang.json。

常见错误（面板顶部错误卡片，message 为处理指引）：

DSH 生态强调「一切皆插件」；社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-mijia-sidebar 把米家设备控制收进 DSH 侧边栏：场景、属性与动作走本机 mijiaAPI 与私有 RPC，不占用模型回合。需要细节、截图与开发说明时，以仓库 README 为准。

• 目录页：https://www.skillhub.cn/plugins/EchoChan314/dsh-mijia-sidebar
• GitHub：https://github.com/EchoChan314/dsh-mijia-sidebar