HomeSense Studio · Codex 接管提示词

适用场景：你是一个 AI 开发者，即将接手 HomeSense Studio 项目。当前日期：2026-05-23

一、一句话定位

这是一个面向求职展示的智能家居 Studio 演示系统。核心场景：在浏览器里管理小米设备、发送红外按键、ADB 操控手机/电视。不是生产级产品。

二、架构全貌

前端 Vue 3 (Vite) :43173
  └─ /api/* 代理 → 后端 Fastify (Node.js) :3000
                   ├─ SQLite (Better-SQLite3) → data/homesense.db
                   ├─ cli-bridge → 子进程调用 mi-cli (Python)
                   └─ mi-cli → mi Home API (HTTP)

三层分层：

顶层：LLM / AI 工具调用 → 只看 user_devices 表
中层：设备管理（user_devices 表）→ 用户维护的干净列表
底层：mi-cli 作为能力来源 → 绑了 mi_did 的设备走 mi-cli

三、当前代码状态（全部已提交 push）

最新 commit: ddc2167 feat: IR device single-capability mode + DB-backed caching

已推送到 github + gitee 两个 remote

关键文件结构

packages/
├── backend/src/
│   ├── index.ts                          # 入口
│   ├── app.ts                            # Fastify app 组装
│   ├── db/index.ts                       # SQLite schema + 迁移（所有表定义在这里）
│   └── modules/
│       ├── cli-bridge/index.ts           # 子进程调 mi-cli，Zod schema 校验
│       ├── device/
│       │   ├── routes.ts                 # MI 原生设备路由（/api/devices/*）
│       │   ├── user-device-routes.ts     # 用户设备管理（/api/user-devices/*）← 核心文件
│       │   └── room-routes.ts            # 房间管理（/api/rooms/*）
│       └── ...
├── frontend/src/
│   ├── api/index.ts                      # 所有 API 调用定义
│   ├── views/
│   │   ├── DevicesView.vue               # 设备列表页
│   │   ├── DeviceDetailView.vue          # 设备详情（能力列表 + IR 遥控面板）
│   │   └── IntegrationsView.vue          # MI 登录/ADB 连接
│   └── router/index.ts                   # 路由
└── mi-cli/src/
    └── mi_cli/
        ├── cli.py                        # CLI 入口 + ACTION_MAP
        ├── api/
        │   ├── auth.py                   # 登录（QR / 密码 / ticket）
        │   ├── device.py                 # 设备发现、spec 解析、IR 按键 ← 关键
        │   ├── ir.py                     # IR 控制器直接操作
        │   └── speaker.py                # 音箱能力
        └── capability/
            └── engine.py                 # 能力映射引擎（MIoT spec → 中文能力名）

四、已实现的功能

设备管理

[x] CRUD 设备（名称/类型/房间/MI绑定/ADB IP/IP地址）
[x] 房间管理（CRUD 房间）
[x] MI 发现设备并绑定（弹窗选择 candidate）
[x] 在线状态检测（ping）
[x] MI 登录（QR 扫码 / 密码 + ticket）

IR 遥控（机顶盒/电视）

[x] IR 设备统一显示"遥控按键"能力
[x] 按需加载真实按键码表（点"点击加载按键码表"）
[x] 点击按键发送红外信号（key_id）
[x] 能力列表、IR 键码全部缓存到 SQLite，永久有效
[x] 手动刷新按钮传 ?refresh=true 才重新拉 mi-cli
[ ] 东芝电视、乐视电视的 IR 键码未实测

音箱能力

[x] 电源开关、亮度、色温、目标温度、模式、风速
[x] 执行文本命令、播放文本、播放音乐、音量、关机、暂停

ADB

[x] 连接设备、截屏、点按、输入文字、按键、启动应用
[ ] ADB 设备控制（tap/input）未在设备管理流程中集成

五、启动方式

bash

# 后端（端口 3000）
cd packages/backend && npm run dev

# 前端（端口 43173，自动代理 /api → :3000）
cd packages/frontend && npm run dev

前端端口在 packages/frontend/vite.config.ts 中通过 VITE_DEV_PORT env 或 fallback 43173 配置。

六、核心数据流

用户设备列表页 `/api/user-devices`

user_devices 表 JOIN rooms 表 → 返回 {id, name, device_type, room_id, room_name, mi_did, adb_ip, ip_address}

获取能力列表 `/api/user-devices/:id/capabilities[?refresh=true]`

DB device_capabilities 表缓存 → 有缓存直接返回
→ 无缓存/refresh=true → cliBridge.run('mi-cli', 'device_capabilities', {did}) → 写 DB 缓存

IR 按键 `/api/user-devices/:id/ir-keys[?refresh=true]`

DB device_capabilities 表缓存 ir_keys_json → 有缓存直接返回
→ 无缓存/refresh=true → cliBridge → mi-cli handle_device_ir_keys()
  → _find_device_in_cache(did) → parent_id → _get_ir_controller_list()
  → 按 name 匹配 controller → _request_api(/v2/irdevice/controller/keys, {did}) → 只拉匹配的

IR 按键发送 `/api/user-devices/:id/ir-press`

cliBridge → mi-cli handle_device_ir_press()
  → 同上解析链 → _request_api(/v2/irdevice/controller/key/click, {did, key_id})

执行能力 `/api/user-devices/:id/capabilities/execute`

中文能力名 → CN_CAPABILITY_TO_KEY 映射表 → speaker 系列走 speaker_execute/speaker_play
→ 其他走 device_action（MIoT 通用 action）

七、DB 缓存策略

device_capabilities 表：

mi_did TEXT PK
capabilities_json TEXT — 能力列表
ir_keys_json TEXT — IR 按键码表
updated_at TEXT

永久缓存，不过期。 用户点"刷新"按钮才带 ?refresh=true 重新拉 mi-cli 并更新。

八、数据库表（只列出活跃的）

表	用途
user_devices	用户管理的设备清单
rooms	房间
device_capabilities	能力列表 + IR 键码缓存
llm_providers / llm_model_slots	LLM 配置
conversations / conversation_sessions / conversation_messages	对话
agent_instances	Agent 实例
skills	技能定义
workflows / workflow_nodes / workflow_edges / workflow_runs	工作流
rules / rule_actions	规则引擎
experiences	经验沉淀
memory_entities / memory_triples / memory_attributes	记忆图
compiled_knowledge_items / compiled_knowledge_embeddings / compiled_knowledge_fts	知识库
settings	设置
compensation_tasks	补偿任务
embedding_profiles	嵌入配置

九、用户偏好（从对话中总结）

做事方式

开工前先确认主线，不要闷头接着上次的做
不要 push 到远程，除非用户明确说"提交并推送"
禁止使用 web_search / web_fetch 内置工具，必须走 tavily-proxy MCP
读中文提问 + 英文搜索关键词
搜索信息用中文组织回答，注明来源 URL

代码风格

实用优先，不做过早抽象
不对 demo 系统做生产级加固（认证、权限、限流等不是重点）
改动前先理解现有逻辑，不要引入不必要的重构

十、房间设计说明

rooms 表和 user_devices.room_id 完全独立于小米生态。 用户在自己本地建房间、指定设备归属，MI 那边的 room_name 只作为展示信息，不参与映射。

十一、已知问题 / 待办

IR 按键码表为空 — 之前 _get_ir_controllers 获取 handle_device_ir_keys 时用 controller_id 参数调 keys API，实际需要用 did。已修复。但如果有其他 controller 也出现空 keys，检查 param 名
Speaker 能力实测过但覆盖不全 — 目前 speakers 路由只返回了基础能力，外接音箱/灯炮等有待测试
ADB 设备控制 — tap/input 功能在 ADB 页面可用，但未集成到设备管理流程中
.superpowers/ 和 tmp/ 目录有临时文件，需要清理

HomeSense Studio · Codex 接管提示词

HomeSense Studio · Codex 接管提示词 ​

一、一句话定位 ​

二、架构全貌 ​

三、当前代码状态（全部已提交 push） ​

关键文件结构 ​

四、已实现的功能 ​

设备管理 ​

IR 遥控（机顶盒/电视） ​

音箱能力 ​

ADB ​

五、启动方式 ​

六、核心数据流 ​

用户设备列表页 /api/user-devices ​

获取能力列表 /api/user-devices/:id/capabilities[?refresh=true] ​

IR 按键 /api/user-devices/:id/ir-keys[?refresh=true] ​

IR 按键发送 /api/user-devices/:id/ir-press ​

执行能力 /api/user-devices/:id/capabilities/execute ​

七、DB 缓存策略 ​

八、数据库表（只列出活跃的） ​

九、用户偏好（从对话中总结） ​

做事方式 ​

代码风格 ​

十、房间设计说明 ​

十一、已知问题 / 待办 ​

HomeSense Studio · Codex 接管提示词

一、一句话定位

二、架构全貌

三、当前代码状态（全部已提交 push）

关键文件结构

四、已实现的功能

设备管理

IR 遥控（机顶盒/电视）

音箱能力

ADB

五、启动方式

六、核心数据流

用户设备列表页 `/api/user-devices`

获取能力列表 `/api/user-devices/:id/capabilities[?refresh=true]`

IR 按键 `/api/user-devices/:id/ir-keys[?refresh=true]`

IR 按键发送 `/api/user-devices/:id/ir-press`

执行能力 `/api/user-devices/:id/capabilities/execute`

七、DB 缓存策略

八、数据库表（只列出活跃的）

九、用户偏好（从对话中总结）

做事方式

代码风格

十、房间设计说明

十一、已知问题 / 待办