HomeSense Studio · 小米登录链路交接文档

生成时间：2026-05-17 适用对象：下一任接手的 AI / 开发者 当前主线：mi-cli 取代 HA / hami-cli，作为 HomeSense 的唯一米家控制底座

---

1. 本文档的目的

这份文档只聚焦一件事：

• packages/mi-cli 的小米登录与设备发现为什么还没有真正打通
• 目前已经修到了哪里
• 哪些问题已经确认不是前端问题
• 下一任接手时应该从哪里继续，而不是重新绕一大圈

这不是全项目总交接文档。全局背景仍然看：

• HANDOVER.md

---

2. 当前项目背景里的关键结论

当前项目已经明确切主线：

• HA
• hami-cli

都已经从活跃主线中移出，只保留为归档参考。

现在米家控制主线是：

• packages/mi-cli

目标不是做一个泛化的小米 SDK，而是做一个能真实登录、发现设备、调用场景、小爱、红外、MIoT 属性/动作的控制底座，然后接进：

• Chat
• Workflow / Studio
• 设备管理
• CLI 管理

当前真正阻塞主线的，不是 UI，也不是 Workflow，而是：

• 小米登录态虽然“看起来成功”，但设备云请求仍然 401
• 二维码登录链路虽然已拆出来重做，但当前实现仍未达到可用状态

---

3. 相关目录与关键文件

3.1 当前项目内

• packages/mi-cli/src/mi_cli/api/auth.py
• packages/mi-cli/src/mi_cli/api/auth_qr.py
• packages/mi-cli/src/mi_cli/api/device.py
• packages/mi-cli/src/mi_cli/cli.py
• packages/backend/src/modules/auth/routes.ts
• packages/backend/src/modules/cli-bridge/index.ts
• packages/mi-cli/test.html

3.2 外部参考

成功二维码参考项目：

• D:\files\bilibili-music\backend\app\speaker\qrcode_login.py
• D:\files\bilibili-music\backend\app\api\speaker.py
• D:\files\bilibili-music\frontend\src\components\player\SpeakerPush.vue

米家云 / 小米设备云参考：

• D:\files\HomeSense\References\hass-xiaomi-miot\custom_components\xiaomi_miot\core\xiaomi_cloud.py

---

4. 当前可用的测试入口

4.1 后端接口

当前后端暴露了这些认证相关接口：

• POST /api/auth/login
• POST /api/auth/verify-ticket
• GET /api/auth/status
• POST /api/auth/logout
• POST /api/auth/qr/start
• GET /api/auth/qr/status
• POST /api/auth/qr/reset

4.2 独立测试页

为了绕开正在并行改造的 Vue 前端，已经单独放了一个隔离测试页：

• packages/mi-cli/test.html

这个页面的作用：

• 单独测账号密码登录
• 单独测验证码提交流程
• 单独测扫码登录
• 单独测登录状态
• 单独测设备发现

结论：当前登录问题不是 Studio 页面布局问题，是真正的后端登录链路问题。

---

5. 已经确认修过的点

5.1 验证码提交流程有过真实 bug，已经修过

账号密码登录触发短信/邮箱验证时，之前 verify_ticket 链路里有真实缺陷。

已经做过的修复方向包括：

• verify_ticket 提交链路修正
• ssecurity 持久化修正
• 登录后认证字段保存逻辑修正

这部分不是完全没动过，不能让下一任 AI 从“验证码根本没接上”这个错误前提重新开始。

5.2 login_qr_status / login_qr_reset 一度没有桥接，已经补上

之前后端报过：

• Unknown action: mi-cli.login_qr_status

原因不是二维码本身，而是 cli-bridge 没注册动作。

已补位置：

• packages/backend/src/modules/cli-bridge/index.ts

当前 schema 已包含：

• login_qr
• login_qr_status
• login_qr_reset

5.3 二维码逻辑已经从旧 auth.py 中拆开

为了避免旧密码登录逻辑和二维码逻辑互相污染，已经新建：

• packages/mi-cli/src/mi_cli/api/auth_qr.py

并让 auth.py 中二维码相关 handler 代理到这个模块。

这一步的目的很明确：

• 密码登录链继续修设备云 401
• 二维码登录链尽量直接照搬成功参考，不和旧实现搅在一起

---

6. 当前真实现状

6.1 账号密码 + 验证码链路

用户实测时，曾拿到这样的成功结果：

{
  "status": "success",
  "data": {
    "logged_in": true,
    "token_valid": true,
    "has_saved_login": true,
    "user_id": "2908798005",
    "auth_fields_present": {
      "ssecurity": true,
      "userId": true,
      "cUserId": true,
      "serviceToken": true
    },
    "message": "登录成功"
  }
}

但紧接着再查状态时，又会变成：

{
  "status": "success",
  "data": {
    "logged_in": false,
    "token_valid": false,
    "has_saved_login": true,
    "user_id": "2908798005",
    "auth_fields_present": {
      "ssecurity": true,
      "userId": true,
      "cUserId": true,
      "serviceToken": true
    },
    "message": "Token已过期: AUTH_FAILED: HTTP 401"
  }
}

设备发现也会失败：

{
  "devices": [],
  "error": "AUTH_FAILED",
  "message": "未登录，请先执行 login_qr"
}

这说明：

1. 登录凭据字段保存并非完全失败
2. 真正失败点在“后续访问设备云 API 的认证”
3. 不是简单的“没存到 auth.json”
4. 不是单纯前端传参错误

6.2 二维码登录链路

目前二维码链路已经单独实现了 auth_qr.py，但用户实测反馈仍然是不通：

• 扫码时间明显异常
• 米家 App 内显示系统错误
• 或表现为二维码不正常 / 很快失效 / 对不上

这说明当前 auth_qr.py 虽然是“参考复制思路”，但还不是成功参考项目的完全等价实现。

用户明确要求：

• 不要继续自己发明二维码流程
• 直接照成功项目抄

这是后续实现策略约束，不是建议项。

---

7. 当前最可信的判断

7.1 密码登录问题的判断

当前最可信判断是：

• OTP 验证链已经不是主要矛盾
• 主矛盾是小米设备云请求阶段的认证 / sid / 签名 / cookie / session 行为不对

重点怀疑区域：

• sid 是否应该固定走 xiaomiio
• serviceLogin -> location -> cookies 刷新链路是否完整
• RC4 / nonce / signed_nonce / clientSign / ssecurity 的用法是否和设备云要求一致
• yetAnotherServiceToken / serviceToken / userId 等 cookie 组合是否正确
• 某些接口是否仍用了错误的 cookie 体系或 header

7.2 二维码问题的判断

当前最可信判断是：

• 现在的 auth_qr.py 不是“完全照搬成功实现”
• 只是做了一个相似结构的独立版本
• 所以它现在还不能被默认认为可靠

下一任 AI 应该做的是：

• 逐行对比
• 尽可能保持参考实现行为一致

而不是继续围绕现有失败实现做局部猜测式修补。

---

8. 代码现状摘要

8.1 auth.py

当前文件特点：

• 包含密码登录、验证码登录、登录状态、登出、设备云认证相关逻辑
• 里面经历过多轮修改
• 已经不是“干净可信基线”

注意：

• 不要把它当作权威实现
• 但也不要全盘推翻里面已经修过的 verify_ticket / ssecurity 持久化部分

更稳妥做法：

1. 把密码登录链和设备云请求链分段验证
2. 对照 hass-xiaomi-miot 的云请求实现查 401 根因

8.2 auth_qr.py

当前文件特点：

• 已独立存在
• 试图承接二维码登录
• 结构上参考了成功项目，但不是严格原样移植

这意味着：

• 现在它只是“过渡版本”
• 不是“已经证明可用的最终版”

8.3 test.html

当前文件很关键，因为它能独立做：

• 密码登录
• 验证码提交
• 二维码启动
• 二维码轮询
• 登录状态
• 设备发现

下一任 AI 接手时，优先用这个页面或 curl 直接打接口，不要先回到复杂 Vue 页里排前端问题。

---

9. 当前不要再重复做的错误方向

下一任 AI 不要再重复以下路径：

1. 不要再把问题归咎于前端页面结构
2. 不要再把二维码逻辑混回旧 auth.py
3. 不要再假设“只要 auth.json 里有 serviceToken 就一定能 discover”
4. 不要再围绕用户反复要验证码做盲试
5. 不要再自己造一个“差不多”的二维码流程

用户已经明确表示：

• 有成功参考项目
• 可以直接抄
• 当前最重要的是把米家登录打通

---

10. 下一任 AI 的推荐接手顺序

10.1 第一步：先固定 QR 方案，不要继续散修

直接对比并整理：

• D:\files\bilibili-music\backend\app\speaker\qrcode_login.py
• packages/mi-cli/src/mi_cli/api/auth_qr.py

目标不是“参考思路”，而是：

• 登录 URL 生成逻辑一致
• header 一致
• session / cookie 使用方式一致
• 轮询方式一致
• 成功后 auth 数据保存方式一致

10.2 第二步：确认后端当前跑的是最新代码

需要确认：

• 后端 3000 是否已重启到最新版本
• /api/auth/qr/start
• /api/auth/qr/status

是否真的走到了新的 auth_qr.py

10.3 第三步：如果继续修密码链，重点查设备云 401

对照：

• D:\files\HomeSense\References\hass-xiaomi-miot\custom_components\xiaomi_miot\core\xiaomi_cloud.py

重点核查：

• 请求 sid
• cookie
• header
• nonce / signed_nonce
• RC4 加解密
• clientSign
• serviceToken 刷新链

10.4 第四步：只有登录稳定后，才继续 discover / scene / speaker

当前顺序不要反了。

在登录没稳之前，继续扩 scene_execute、speaker_execute、ir_press_key 没意义。

---

11. 建议的短期验收标准

下一任 AI 不需要一下子把全米家能力都做完。短期只需要拿到这 4 个结果：

1. 二维码登录可稳定成功，或密码登录可稳定成功
2. GET /api/auth/status 不再立刻掉成 HTTP 401
3. discover 能返回至少一批真实设备
4. auth.json 中登录态可以复用，而不是一次成功后立刻失效

只要这四点成立，后面的：

• scene
• speaker
• ir
• workflow 接入

都能继续推进。

---

12. 当前结论

当前不是“项目没有做”，而是已经完成了以下中间状态：

• mi-cli 已经成为活跃主线
• 登录相关后端接口已经有了
• 独立测试页已经有了
• 验证码链有过真实修复
• 二维码链已经被拆为独立模块

但还没有跨过真正可用的门槛：

• 登录态无法稳定用于设备云
• 二维码实现仍未和成功参考完全对齐

所以下一任 AI 最合理的接管方式不是“重构整个 HomeSense”，而是：

• 只盯住小米登录
• 先把二维码或密码链其中一条做成稳定可用
• 再回到设备发现和控制主线

---

13. 一句话交接

当前 HomeSense 的米家主线已经切到 mi-cli，验证码提交 bug 和 ssecurity 持久化问题修过，独立测试页和后端认证路由也齐了；真正未解决的是“小米设备云 401”与“二维码实现尚未完全照搬成功参考”，下一任 AI 应直接对照 bilibili-music 的二维码实现和 hass-xiaomi-miot 的云请求实现继续，而不要再从前端或泛化重构方向重新开始。