69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
# mijia-api Go 重构设计(2026-07-16)
|
|
|
|
> [!NOTE]
|
|
> This document may not reflect the current implementation.
|
|
> See the final report for up-to-date state:
|
|
> [Final Report](../reports/mijia-go-api.md)
|
|
|
|
## [S1] 问题
|
|
|
|
将 Python 版 mijia-api(v4.1.2)重构为纯 Go 库,只保留 API 核心功能,排除 skills、MCP server、CLI、decrypt 调试脚本、文档站。
|
|
|
|
## [S2] 方案概览
|
|
|
|
- 项目形态:纯 Go 库,module 路径 `git.misaka.ren/m1saka/mijia-go-api`,包名 `mijia`,代码放仓库根目录。
|
|
- 功能范围:完整底层 API + 高级设备封装(mijiaDevice 等价物)。
|
|
- Go 版本:1.22+,尽量只用标准库;二维码终端输出用 `github.com/mdp/qrterminal/v3`。
|
|
|
|
## [S3] 包结构
|
|
|
|
```
|
|
|
|
|
|
|
|
/ (package mijia)
|
|
crypto.go ← miutils.py: GenNonce / SignedNonce / RC4-drop1024 加解密 / 签名 / GenerateEncParams(有序 KV)
|
|
auth.go ← 登录: QRLogin、passToken 静默刷新、auth.json 读写、UA/deviceId 生成
|
|
client.go ← Client 结构、session headers/cookies、统一加密请求 request()
|
|
api.go ← GetHomesList / GetDevicesList(分页) / GetSharedDevicesList / GetScenesList / RunScene /
|
|
GetConsumableItems / GetDevicesProp / SetDevicesProp / RunAction / GetStatistics / CheckNewMsg
|
|
device.go ← Device 高级封装: miot-spec 抓取解析+缓存、Get/Set(类型与 range 校验)/RunAction
|
|
errors.go ← ERROR_CODE 表 + 错误类型(LoginError/APIError/DeviceGetError/DeviceSetError 等)
|
|
types.go ← 请求/响应结构体
|
|
```
|
|
|
|
## [S4] 认证与加密关键点
|
|
|
|
1. 二维码扫码登录:`account.xiaomi.com/pass/serviceLogin` → `longPolling/loginUrl` → 终端二维码 → 长轮询(120s)→ 回调取 serviceToken;响应需去 `&&&START&&&` 前缀。
|
|
2. passToken 有效时静默刷新 token;auth.json 保存 ua/deviceId/pass_o/ssecurity/serviceToken/passToken/userId/cUserId/expireTime(30 天)等。
|
|
3. 加密请求(base `https://api.mijia.tech/app`,全部 POST form):
|
|
- nonce = base64(8 字节随机 + 分钟时间戳字节);signedNonce = base64(SHA256(ssecurity||nonce))。
|
|
- RC4 必须先丢弃 1024 字节 keystream(标准库 crypto/rc4 手动 drop)。
|
|
- 双重签名:先对明文 params 签 `rc4_hash__`,RC4 加密后再签 `signature`;签名串顺序固定 `POST&uri&data=..&rc4_hash__=..&signedNonce`,Go 用有序 KV 切片而非 map。
|
|
- data JSON 必须紧凑无空格。
|
|
- 响应可能是 gzip 压缩后的 RC4 密文:先直接 JSON 解析,失败则解密,解密后 UTF-8 无效再 gzip 解压。
|
|
4. `Available()`:检查 auth 字段完备 + 调 check_new_msg 验证,结果缓存 60 秒。
|
|
|
|
## [S5] API 方法映射
|
|
|
|
与 Python 版一一对应(URI、请求体 JSON 完全一致),注意:
|
|
- GetDevicesList 分页(start_did/max_did,直到 has_more=false),home_id 为空时遍历所有家庭。
|
|
- RunAction 逐条请求,prop get/set 批量。
|
|
- 多数接口需 home 的 owner uid(从 GetHomesList 查)。
|
|
- SetDevicesProp code==1 表示网关已接收但结果未知;非 0/1 查 ERROR_CODE 附中文消息。
|
|
|
|
## [S6] 高级设备封装
|
|
|
|
`NewDevice(api, did 或 name)`:
|
|
- 从设备列表解析 model → GET `https://home.miot-spec.com/spec/{model}` 正则提取内嵌 JSON → 解析 services/properties/actions(siid/piid/aiid、类型、rw、range、value-list)→ 本地 JSON 缓存(auth.json 同目录)。
|
|
- `Get(name)` / `Set(name, value)`(bool/int/float 类型转换、range 与枚举校验)/ `RunAction(name, args...)`;属性名 `-` 与 `_` 互为别名。不做 Python 的动态属性语法糖。
|
|
|
|
## [S7] 错误处理与测试
|
|
|
|
- 错误:哨兵/自定义错误类型 + ERROR_CODE map(码→中文)。
|
|
- 测试:crypto.go 的纯函数(nonce 格式、signedNonce、RC4-drop1024、签名串)用与 Python 实现对照生成的固定向量做单测;spec HTML 解析用本地样本。网络调用不做集成测试。
|
|
|
|
## [S8] 排除项
|
|
|
|
mcp_server.py、skills/、docs/、decrypt/、`__main__.py` CLI、qrcode 图片生成(仅终端二维码)。
|