HomeSense Studio · 项目转交（2026-05-22）

生成：2026-05-22 | 取代 2026-05-20 版 HANDOVER.md 适用对象：接手的 AI 或开发者

一、项目定位（最高参照）

这是面向找工作的演示系统。不是生产级产品，不是学术探索。目标是：做一个能拿给面试官看、能讲得出设计思路、能现场跑得动的演示系统。

三层叠加才是完整：

集大成 — 吸收 27 个开源项目（Dify / Claude Code / HA Core / Orra / ACE 等）的设计思路
定居智能家居 — 所有抽象回到一盏灯、一台电视、一个红外按键上证明
从消费到生产 — "Studio" 概念（Skill 自晋升/经验沉淀/编排）能在 Demo 中展示一个环节即成功

二、当前阶段：CLI 集成（2026-05-22 起）

这是当前唯一的开发方向。 以下内容全部暂停，不要碰：

❌ LLM / agent 对话路径
❌ Demo 路径（"在 Toshiba 电视上看 Bilibili"）
❌ plan-library / compiled plan
❌ intent-router / context-completer
❌ 任何涉及 LLM 推理的内容

Why: 底层 CLI 集成（mi-cli、adb-cli）还没完成。executor-gateway、agent-runtime 等上层依赖 CLI 的执行能力，CLI 不稳定上层全是空中楼阁。

当前聚焦：让 CLI 命令能正确执行，打通 REST API → CLI Bridge → mi-cli/adb-cli 的全链路。

三、已完成的工作

3.1 IR 红外设备控制（已跑通）

项目	状态
`POST /api/user-devices/:id/capabilities/execute`	✅ 可用
中文能力名 → 英文 key 映射（22 条）	✅ `CN_CAPABILITY_TO_KEY`
JSON 文件缓存能力列表（`data/mi-cache/{did}.json`）	✅ 用户明确指定 JSON 即可
3 个 IR 设备注册（乐视电视/东芝电视/机顶盒）	✅
小爱音箱万能遥控版作为 IR 网关	✅ mi_did=108654953

关键发现： mi-cli 的 device_action 走 /miotspec/action API 是正常工作的。ir_press_key / ir_get_keys 这条老路对此账户返回 permission error（code=-4）。所有 IR 执行必须走 device_action。

3.2 后端 REST API

packages/backend/src/modules/device/user-device-routes.ts 包含：

GET /api/user-devices — 列出设备（含 room 关联）
GET /api/user-devices/:id — 单设备详情
PUT /api/user-devices/:id — 编辑设备
DELETE /api/user-devices/:id — 删除设备
POST /api/user-devices — 新建设备
GET /api/user-devices/:id/capabilities — 查能力（走 JSON 缓存 / mi-cli）
POST /api/user-devices/:id/capabilities/execute — 执行能力（核心端点）
GET /api/user-devices/ping-all — 批量 ping
GET /api/user-devices/mi-candidates — MI 设备候选（绑定下拉）

3.3 前端设备管理

DevicesView.vue — 设备管理页面，含 MI/ADB 标签、创建/编辑/删除弹窗
DeviceDetailView.vue — 设备详情页，可点击能力卡片直接执行动作
当前显示 6 个设备：小爱音箱(id:5)、机顶盒(id:4)、东芝电视(id:3)、华为手机(id:2)、test-success(id:1)

3.4 CLI Bridge

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

完整的 mi-cli Zod schema（20+ actions，含 device_action/device_capabilities/device_prop）
完整的 adb-cli Zod schema（20+ actions）
子进程运行器（可注入 mock 测试）
第三方 executor 注册机制
补偿/重试策略（DEVICE_OFFLINE → retry 3次, AUTH_FAILED → fallback login_qr 等）
智能错误处理：按 error code 走 retry/fallback/abort/notify

3.5 架构抽象（已完成但暂时用不上）

HANDOVER-2026-05-20 详细记录了 DI 重构 + Repository 模式 + 5 个 Repository + 心脏系统（memory-kernel → experience → skills-system → knowledge-compiler → self-enhancement）。这些是面试能讲的架构亮点，但当前阶段不要继续推进（不涉及 module 解耦/新的抽象/心脏链路接入）。

四、当前设备清单

设备	控制方式	mi_did	ADB
东芝电视	MI（红外）	ir.2038224602945437696	❌
机顶盒	MI（红外）+ ADB	ir.2038476279661080578	✅ 待接通
乐视电视	MI（红外）	ir.2038581922699296768	❌
华为手机	ADB	❌	✅
小爱音箱万能遥控版	MI（语音+IR网关）	108654953	❌

Demo 场景基础： 机顶盒同时具备 IR 控制（开关机/音量/频道）和 ADB 控制（安装/启动 App），是"在东芝电视上看 Bilibili"的关键跳板。

五、仍需完成的工作（CLI 集成范畴内）

P0：ADB CLI 集成

adb-cli 包已经存在（packages/adb-cli/，untracked），但：

需要确认 adb-cli 能否作为子进程执行（类似 mi-cli，python -m adb_cli run '{...}'）
需要在服务注册表中注册 adb-cli 作为一等执行器
需要前端设备详情页支持 ADB 操作（截图、App 列表、启动 App）
验证标准： 对机顶盒（ADB 已连接）执行 launch_app 能正常工作

P1：executor-gateway 的 mi-cli 路由确认

executor-gateway/index.ts 的 resolveStepExecutor() 将 mi-cli → cli:mi-cli，adb → cli:adb-cli。需要确认：

cli:mi-cli 前缀的路由能否正确执行 cliBridge.run('mi-cli', ...)
agent-runtime Level 1（匹配 plan 路径）能否调用 executor-gateway 执行 IR 控制

P2：设备状态反馈（执行结果可视化）

IR 执行成功后（{ code: 0 }），前端需要给用户明确的 toast 反馈
执行失败的场景需要更友好的错误展示

不做的事情（明确不在此阶段）

agent 路径的 DEVICE_NOT_FOUND 问题 → LLM 推理层的问题，不在此阶段修
self-enhancement 触发 → 心脏链路的事，不在此阶段
更多 IR 设备的新增/发现 → 现有 3 个够 demo 用
后端模块再拆分/抽象 → 架构已经够用

六、技术栈速查

项	值
语言	TypeScript ESM (`"type": "module"`)
DB	better-sqlite3（零外部服务）
Server	Fastify (port 3000)
前端	Vue 3 + Vite (port 43173)
桥接	CLI Bridge（child_process → JSON stdout）
mi-cli	Python 子进程，走 `/miotspec/action`
adb-cli	Python 子进程（待集成）
测试	Vitest v4

七、启动命令

bash

# 后端
cd packages/backend && npx tsx watch src/index.ts

# 前端
cd packages/frontend && npx vite --host 0.0.0.0

# 类型检查
cd packages/backend && npx tsc --noEmit

# 测试
cd packages/backend && npm test

# IR 能力执行测试（开机）
printf '{"capability":"开机"}' | curl -s -X POST http://localhost:3000/api/user-devices/3/capabilities/execute -d @- -H "Content-Type: application/json"

八、关键文件速查

目的	路径
后端入口	`packages/backend/src/index.ts`
设备路由（IR 执行）	`packages/backend/src/modules/device/user-device-routes.ts`
CLI Bridge（子进程+Zod schema）	`packages/backend/src/modules/cli-bridge/index.ts`
服务注册	`packages/backend/src/modules/service-registry/index.ts`
executor-gateway	`packages/backend/src/modules/executor-gateway/index.ts`
IR 缓存（乐视）	`packages/backend/data/mi-cache/ir.2038581922699296768.json`
IR 缓存（东芝）	`packages/backend/data/mi-cache/ir.2038224602945437696.json`
IR 缓存（机顶盒）	`packages/backend/data/mi-cache/ir.2038476279661080578.json`
小爱缓存	`packages/backend/data/mi-cache/108654953.json`
设备列表页	`packages/frontend/src/views/DevicesView.vue`
设备详情页	`packages/frontend/src/views/DeviceDetailView.vue`
前端 API 客户端	`packages/frontend/src/api/index.ts`
mi-cli Python	`packages/mi-cli/src/mi_cli/`
adb-cli Python	`packages/adb-cli/`（untracked，待集成）
项目精神	`C:\Users\a1\.claude\projects\D--files-HomeSense-Stdio\memory\project_intent.md`
当前焦点	`C:\Users\a1\.claude\projects\D--files-HomeSense-Stdio\memory\current_focus.md`

九、开工检查清单（给接手 AI）

[ ] 跑 cd packages/backend && npx tsc --noEmit — 零错误
[ ] 跑 cd packages/backend && npm test — tests pass
[ ] 读 memory/project_intent.md 理解项目精神
[ ] 读 memory/current_focus.md 理解当前阶段约束
[ ] 先和用户确认"现在继续搞 X？" — 不要默认从上个 session 结尾继续
[ ] 验证 IR 执行：printf '{"capability":"开机"}' | curl -s -X POST http://localhost:3000/api/user-devices/3/capabilities/execute -d @- -H "Content-Type: application/json"
[ ] 判断任何新任务：「这件事属于 CLI 集成范畴吗？」— 不是就不要做

本文件替代 2026-05-20 版 HANDOVER.md。当前阶段全部围绕 CLI 集成，不碰 LLM/demo/plan 等上层内容。

HomeSense Studio · 项目转交（2026-05-22）

HomeSense Studio · 项目转交（2026-05-22） ​

一、项目定位（最高参照） ​

二、当前阶段：CLI 集成（2026-05-22 起） ​

三、已完成的工作 ​

3.1 IR 红外设备控制（已跑通） ​

3.2 后端 REST API ​

3.3 前端设备管理 ​

3.4 CLI Bridge ​

3.5 架构抽象（已完成但暂时用不上） ​

四、当前设备清单 ​

五、仍需完成的工作（CLI 集成范畴内） ​

P0：ADB CLI 集成 ​

P1：executor-gateway 的 mi-cli 路由确认 ​

P2：设备状态反馈（执行结果可视化） ​

不做的事情（明确不在此阶段） ​

六、技术栈速查 ​

七、启动命令 ​

八、关键文件速查 ​

九、开工检查清单（给接手 AI） ​

HomeSense Studio · 项目转交（2026-05-22）

一、项目定位（最高参照）

二、当前阶段：CLI 集成（2026-05-22 起）

三、已完成的工作

3.1 IR 红外设备控制（已跑通）

3.2 后端 REST API

3.3 前端设备管理

3.4 CLI Bridge

3.5 架构抽象（已完成但暂时用不上）

四、当前设备清单

五、仍需完成的工作（CLI 集成范畴内）

P0：ADB CLI 集成

P1：executor-gateway 的 mi-cli 路由确认

P2：设备状态反馈（执行结果可视化）

不做的事情（明确不在此阶段）

六、技术栈速查

七、启动命令

八、关键文件速查

九、开工检查清单（给接手 AI）