HomeSense Studio · 交接文档

生成：2026-05-20 | 旧版 HANDOVER.md（2026-05-01）已废弃适用对象：接手的 AI 或开发者

一、项目精神（最高参照）

"我项目的精神就是能集大成用上各种先进技术理念、和参考项目，定居于智能家居场景，现在升级成了有生产能力的家庭工作室 Studio。"

三层叠加才是完整：

集大成 — 27 个被验证的开源项目源码级吃下来（Dify / Claude Code / HA Core / Orra / ACE / OpenClaw / mempalace / phone-mcp / miot-mcp 等），不是参考思路是真吸收
定居智能家居 — 所有抽象能力回到一盏灯、一台电视、一个红外按键上证明
从消费到生产 — "Studio" 是关键。老 HomeSense 是消费家居能力，Plus 是生产家居能力（编排/沉淀/自动晋升 Skill/自增强）

⚠️ 求职展示是外形，不是精神。 不要把这个项目当作品集做。

详细精神记录在 C:\Users\a1\.claude\projects\D--files-HomeSense-Stdio\memory\project_intent.md

二、用户指定的工作流

阶段 1: 理解架构 → 阶段 2: 重构拆解 → 阶段 3: 基础设施搭建测试 → 阶段 4: 组合拼装

当前已在阶段 3 末尾 / 阶段 4 入口。 不急，"花时间做好"。"方向不对可以回头"。

关键约束：

不要 push 到远程（"你不要自己推，我叫你推你再推"）
每次压缩恢复后，先确认主线再开工，不要闷声接着上次的做
项目不会换架构方向；开放修订设计本身

三、当前里程碑状态（2026-05-20）

已完成：Stage A + B（基础设施解耦 + Repository 模式）

Git 历史（master，本地上游 13 commits，未 push）：

d197e6e fix: resolve TDZ in constructor defaults across all modules + add heart integration test
f6a61d5 refactor: extract KnowledgeCompilerRepository — Stage B-5
5fecacd refactor: extract SkillsRepository + add loadAll() — Stage B-4
d210d83 refactor: extract ExperienceRepository + ExperienceFileStore — Stage B-3
221a580 refactor: extract MemoryRepository (heart write paths) — Stage B-2
e0719d3 refactor: extract ConversationRepository — establish Stage B pattern
7f7c31e test infra: vitest + in-memory db + fakes for fully decoupled module tests
ab02abd refactor: inject getDb into llm-provider service
... (往上 6 个 DI 重构 commits 到初始提交)

关键架构资产：

资产	路径
5 个 Repository 接口	`modules/{conversation,memory-kernel,experience,skills-system,knowledge-compiler}/repository.ts`
In-memory DB 工厂	`db/index.ts` → `createInMemoryDb()`
Test support 3 件套	`test-support/{fake-event-bus,fake-cli-bridge,fake-llm-service}.ts`
8 个解耦测试 + 1 个心脏集成测试	`modules/*/decoupling.test.ts` + `heart/heart.integration.test.ts`
架构理解报告	`docs/architecture-understanding-2026-05-19.md`（352 行 16 子系统逐个画像）

测试状态：8 files, 35 tests, all passing（cd packages/backend && npm test）

四、架构总览（38 个模块，7 层）

┌─────────────────────────────────────────────────┐
│  L1 Chat Surface          L3 Studio Surface      │
│  (agent-runtime)          (workflow/)             │
├─────────────────────────────────────────────────┤
│  Execution Gateway                                │
│  executor-gateway / manifest-registry /           │
│  agent-adapter / a2a-client / cli-bridge          │
├─────────────────────────────────────────────────┤
│  ★ Heart System — 5 模块，记忆心脏 ★              │
│                                                   │
│  memory-kernel  ─── 知识图谱 + 向量 + 观察         │
│       ↓                                           │
│  experience  ─────── 经验存储 + 重要性 + 自动转 Skill│
│       ↓ (importance ≥ 0.7)                        │
│  skills-system  ──── Skill 注册 + DB 持久化        │
│       ↓                                           │
│  knowledge-compiler ─ 编译 → compiled_knowledge    │
│       ↓                                           │
│  self-enhancement ── 失败反思 + 规则/Skill 生成     │
├─────────────────────────────────────────────────┤
│  Support Subsystems                                │
│  rule-engine / cron / compensation /               │
│  device-state-poller / event-bus /                 │
│  service-registry / approval / channels            │
├─────────────────────────────────────────────────┤
│  Chat Pipeline                                     │
│  intent-router / context-completer /               │
│  candidate-plan / rerank-service / plan-library    │
├─────────────────────────────────────────────────┤
│  Storage (SQLite family)                           │
│  better-sqlite3 / FTS5 / embedding (JSON col)      │
└─────────────────────────────────────────────────┘

五、「心脏」真实断裂点（最重要）

项目"心脏没跳"的原因不是架构问题，是以下断裂点：

❌ 最关键的断裂：Self-Enhancement 零调用

selfEnhancementService.processFailureAndEnhance() 未被任何业务代码调用
agent-runtime 的失败路径没挂入，workflow 的失败路径没挂入
这导致 ACE Skillbook 三角色（Reflect → GenerateRule → GenerateSkill）从未在真实路径上执行
heart.integration.test.ts 已验证：如果能调用，它是能工作的

❌ Embedding 列存未接

compiled_knowledge_embeddings 表有结构，LLM slot 有配置入口
但 semanticSearch 需要真实 vector，当前 FakeLlmService.embed() 只返回 mock
没接 qwen3-embedding-8b，所以 memory 的语义搜索不工作

❌ observeOutcome 被写入但从未被消费

三处触发（chat tool call 后、workflow 节点后、plan 步骤后）都会写 observation
但 recallObservations() 的结果没有被任何业务逻辑用作决策依据
L2/L3 应该用它重排候选，但实际没用

⚠️ 次要空壳

state-machine/ — 35 行内存 Map，无持久化，无事件触发
device-state-poller — 已 DI 重构但需要真实设备数据
cronService — 只从 DB 加载 trigger_type='cron' 的 workflow，当前 0 条
compensationService — 实现完整但无模块调用

已完成并验证的链路

✅ observeOutcome → attributes/triples 持久化（heart.test 验证）
✅ experience → skill auto-promotion（importance ≥ 0.7）（heart.test 验证）
✅ **skill 持久化 + 重启恢复 **（heart.test 验证）
✅ knowledge-compiler 四源编译（heart.test 验证）
✅ failure→reflect→skill/rule 生成（单独调用有效，缺业务触发）

六、下一步工作（按优先级）

P0：让心脏跳起来（阶段 4 核心）

1. Self-Enhancement 接入失败链路

agent-runtime/index.ts 失败路径 → processFailureAndEnhance()
workflow/run-workflow.ts 的 executor_call 失败 → 同上
代码上就是加几行调用

2. observeOutcome → 真正影响行为

L2/L3 在构建 context 时调用 recallObservations() → 用结果重排候选 Plan
这是"记忆有用"的直观证明

3. Embedding 接真

LLM slot 接 qwen3-embedding-8b
semanticSearch() 走真实向量召回
db/index.ts 里 sqlite-vss 当前不用，可考虑启用或继续 JSON 列存

P1：工程基建收尾

Stage C · Heart Event Emitter 类型化

把 eventBus.fire('string_name', data) 变成枚举类型
已有 FakeEventBus.lastOf() / countOf() 可用

Stage D · Composition Root

创建 src/composition.ts → buildContainer({db}) 一键构造所有模块
参考 app.ts 的启动流程作为蓝本

P2：Demo 主线

Demo：「在东芝电视上看 B 站」端到端
需要 mi-cli、adb-cli、bilibili-cli 三桥协同
参考 plan-library/ 中的硬编码路径

七、技术栈速查

项	值
语言	TypeScript ESM (`"type": "module"`)
DB	better-sqlite3 + FTS5（零外部服务）
Server	Fastify
LLM	多 provider：deepseek-v4-flash / ollama / mimo / openai
Embedding	`qwen3-embedding-8b`（预留，未接）
Reranker	`qwen3-reranker-8b`（预留，未接）
桥接	CLI Bridge（child_process → JSON stdout）
智能家居	miot-mcp 协议（mi-cli）
测试	Vitest v4（新测试一律走 vitest，不走 node:test）
前端	Vue3 + Vite，端口 43173
后端端口	3000

八、关键路径文件速查

目的	路径
入口+启动	`src/index.ts` → `src/app.ts`
所有数据库表结构	`src/db/index.ts` — `createTables()` 38 张表
心脏集成测试	`src/heart/heart.integration.test.ts`
5 个 Repository 接口	`modules/*/repository.ts`
设计源文档	`D:\files\HomeSense\新生\`
参考项目源码	`D:\files\HomeSense\References\`
架构梳理报告	`docs/architecture-understanding-2026-05-19.md`

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

[ ] 跑 cd packages/backend && npx tsc --noEmit — 零错误
[ ] 跑 cd packages/backend && npm test — 35 tests pass
[ ] 读 memory/project_intent.md 理解项目精神
[ ] 读 memory/feedback_understand_before_acting.md 理解用户协作方式
[ ] 先和用户确认"现在继续搞 X？" — 不要默认从上个 session 结尾继续
[ ] 对于任何新功能/重构，判断：「这会让心脏跳起来 + demo 主线能跑更近还是更远？」

十、验证命令

bash

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

# 全部测试
cd packages/backend && npm test

# 心脏集成测试单独跑
cd packages/backend && npx vitest run src/heart/heart.integration.test.ts

# 启动后端
cd packages/backend && node --loader tsx src/index.ts

# 健康检查
curl http://localhost:3000/api/health

本文件替代 2026-05-01 旧版 HANDOVER.md。旧版第二至十节（含 memory 索引、中断任务、快速命令）已过时，以当前版本和代码为准。

HomeSense Studio · 交接文档

HomeSense Studio · 交接文档 ​

一、项目精神（最高参照） ​

二、用户指定的工作流 ​

三、当前里程碑状态（2026-05-20） ​

已完成：Stage A + B（基础设施解耦 + Repository 模式） ​

四、架构总览（38 个模块，7 层） ​

五、「心脏」真实断裂点（最重要） ​

❌ 最关键的断裂：Self-Enhancement 零调用 ​

❌ Embedding 列存未接 ​

❌ observeOutcome 被写入但从未被消费 ​

⚠️ 次要空壳 ​

已完成并验证的链路 ​

六、下一步工作（按优先级） ​

P0：让心脏跳起来（阶段 4 核心） ​

P1：工程基建收尾 ​

P2：Demo 主线 ​

七、技术栈速查 ​

八、关键路径文件速查 ​

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

十、验证命令 ​

HomeSense Studio · 交接文档

一、项目精神（最高参照）

二、用户指定的工作流

三、当前里程碑状态（2026-05-20）

已完成：Stage A + B（基础设施解耦 + Repository 模式）

四、架构总览（38 个模块，7 层）

五、「心脏」真实断裂点（最重要）

❌ 最关键的断裂：Self-Enhancement 零调用

❌ Embedding 列存未接

❌ observeOutcome 被写入但从未被消费

⚠️ 次要空壳

已完成并验证的链路

六、下一步工作（按优先级）

P0：让心脏跳起来（阶段 4 核心）

P1：工程基建收尾

P2：Demo 主线

七、技术栈速查

八、关键路径文件速查

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

十、验证命令