HomeAgent/DESIGN.md

HomeAgent 架构设计 v3

一、核心理念

24 小时陪伴用户、随时待命的智能管家。单会话·单 Agent，身份不漂移。

设计原则

• 所有输入走 IO 抽象层（中断模式），不直调 agent 方法
• 所有 LLM 调用走 Provider 接口，不直连 API
• DeepSeek v4 flash 为默认 LLM，thinking 模式关闭
• 人格固定（personal.md），记忆分层管理防止性格突变
• 知识独立于记忆，agent 主动学习
• 插件 = 容器，IO 通道是插件的内嵌组件

---

二、核心抽象

IO 抽象层（唯一输入路径）

外部设备 (Mic/Camera/OneBot/GPIO/HTTP)
        │
        ▼
IOManager
  ├─ Device 接口（每个设备实现）
  │   ├─ Name() / Type() / Description()
  │   ├─ Tools() → 给 LLM 的 Function Calling 工具
  │   ├─ Execute() → 工具调用分发
  │   ├─ Start() / Stop()
  │   └─ OutputCapabilities() → 输出能力声明
  ├─ InputEvent{Source, Type, Payload} → inputCh
  ├─ OutputEvent{Target, Type, Payload} → outputCh
  └─ 路由表: 输入源 → 默认输出通道

输出通道能力声明（OutputCapability 位掩码）：

能力	说明
CapText	文本输出
CapFile	文件传输
CapImage	图片输出
CapAudio	音频输出
CapStructured	结构化数据（JSON/卡片）

Agent 可调用通道工具：

• output_list_channels — 查看所有可用通道及其能力
• output_set_channel — 切换当前回复的输出通道
• output_send — 通过指定通道异步发送消息（校验能力）

API 抽象层（唯一输出路径）

Agent Core → Provider.Chat() → LLM API
                │
        ┌───────┴───────┐
        ▼               ▼
  OpenAIProvider    LuaAdapter
  (DeepSeek API)    (格式转换)

插件系统（OpenClaw 兼容）

Plugin（容器）
  ├─ 元数据: name, version, author, description
  ├─ IOConfig（可选）: 声明 IO 端口
  ├─ Device（可选）: 原生 Go IO 设备实现
  └─ Tools: 给 LLM 的工具定义

插件来源：

• plugins/ 目录热加载，agent 通过 plgreload 工具显式控制重载
• 有原生工厂注册的（如 QQ/OneBot）→ 构造原生设备
• 纯 SKILL.md → 用 PluginDevice 包装为 IO 设备
• 原子化替换：新设备 Start → 原子换路由 → 旧设备 Stop

---

三、记忆体系（三层）

用户输入 → Context（内存, 30条, TF-IDF排序）
              │ 每次响应后裁剪最不相关的
              ▼
          Document（JSON + TF-IDF向量, 冷72h→图）
              │ 心跳蒸馏（30min）
              ▼
          Graph（SQLite三元组, 定期重整+同义合并）

层	存储	容量	裁剪策略
Layer 1: 上下文	RelevanceContext（内存环形缓冲）	30 条	TF-IDF 余弦相似度排序，低分→文档
Layer 2: 文档	document.Store（JSON 文件 + 向量索引）	无上限	72h 未访问 + ≤2 次命中→图
Layer 3: 图	memory.GraphDB（SQLite 三元组）	无上限	定期重整 + bigram Jaccard 同义合并

注入策略：

• 只注入图索引（实体名+类型+提及数）到 prompt，不注入全文
• agent 通过 memory_recall 主动查询详情
• 文档摘要按相关性注入前 3 条

---

四、知识体系

独立于记忆，agent 主动学习。

knowledge/
  smart_home/content.md
  cooking/content.md
       │
       ▼
  TF-IDF 向量索引（字符 bigram）
       │
       ▼
  knowledge_search / knowledge_create / knowledge_list

---

五、人格内核

personal.md → 加载一次 → 固定在 system prompt 最前 → 永不漂移。

---

六、OneBot QQ 通道

go-cqhttp / Lagrange（OneBot 前端）
        │  Reverse WebSocket
        ▼
OneBot Client（internal/onebot/）
  ├─ 事件循环 → Event → IO InputEvent
  ├─ Action 调用 → send_private_msg / send_group_msg / ...
  └─ 自动重连 + 心跳检测
        │
        ▼
Device 注册 → IOManager → Agent

---

七、数据流

用户消息 → IO InputEvent → eventLoop
  │
  ├─ 1. 追加到 RelevanceContext
  ├─ 2. 构建 prompt:
  │     personal.md + 图索引 + 文档摘要 + 上下文 + 工具
  ├─ 3. 工具循环（最多 10 轮）
  │     LLM → tool_calls → Execute → 结果 → LLM → ...
  ├─ 4. 追加响应到上下文
  ├─ 5. 相关性裁剪（Prune → 不相关的归档到文档）
  ├─ 6. OutputEvent → 输出通道
  └─ 7. 记忆候选 → TextMemory(JSONL) + Distiller → GraphDB

心跳（30min）:
  ├─ Indexer.Sync() — 图→向量
  ├─ DocStore.Reindex() — 文档向量重建
  ├─ 冷文档→图归化
  └─ 图同义合并

插件重载（plgreload）:
  ├─ 扫描 plugins/ 目录
  ├─ 加载新插件，Start 新设备
  ├─ 原子替换 IOManager 设备表 + 路由表
  └─ Stop 旧设备

---

八、配置

daemon:
  listen_addr: ":8080"
  data_dir: "/var/lib/homeagent"
  heartbeat_interval: 15s
llm:
  model: "deepseek-v4-flash"
  base_url: "https://api.deepseek.com/v1"
  api_key: "${DEEPSEEK_API_KEY}"
  temperature: 0.7
  max_tokens: 4096

---

九、关键文件

cmd/homed/main.go                — 入口：组装所有子系统
internal/agent/core/agent.go     — Agent 核心：事件循环、工具循环、心跳
internal/agent/core/context.go   — RelevanceContext：TF-IDF 上下文管理
internal/agent/personal.go       — 人格加载
internal/agent/api/provider.go   — Provider 接口 + DeepSeek 实现
internal/agent/io/channel.go     — IO 抽象层：Device/InputEvent/OutputEvent/路由
internal/api/handler.go          — HTTP API 端点
internal/knowledge/knowledge.go  — 知识系统
internal/memory/graph.go         — SQLite 图数据库
internal/memory/indexer.go       — 图索引器
internal/memory/vector/store.go  — TF-IDF 向量存储
internal/memory/document/doc.go  — 文档记忆
internal/memory/text/text.go     — 文本记忆（JSONL）
internal/memory/pipeline/        — 蒸馏器
internal/onebot/                 — OneBot V11 协议实现
internal/plugin/plugin.go        — 插件系统
internal/tracker/tracker.go      — 变更追踪
internal/supervisor/daemon.go    — 守护进程
internal/lua/vm.go               — Lua 适配器 VM
plugins/                         — 插件目录
  qq/SKILL.md                    — QQ 插件 SKILL.md
  qq/skill.json                  — QQ 插件 JSON 元数据
config/config.go                 — 配置加载
pkg/types/                       — 类型定义
DESIGN.md                        — 本架构文档

---

十、与旧设计的核心区别

维度	旧设计 (v1)	当前设计 (v3)
上下文裁剪	固定 FIFO 20 条	TF-IDF 相关性排序 top-K
图记忆注入	关键词 LIKE 查询	向量搜索实体名，只注索引
文档→图	无	72h 冷文档自动归化
图重整	无	向量同步 + bigram Jaccard 同义合并
知识系统	无	knowledge/ 目录 + TF-IDF 向量
人格	无	personal.md 固定注入
向量引擎	无	自研 TF-IDF + 倒排索引（字符 bigram）
部署	Docker 容器 + 快照	单二进制 + overlayfs 追踪
Agent 模型	多 Agent 编排	单 Agent + 工具循环
输出通道	无	能力声明 + 路由 + 校验
插件系统	无	OpenClaw SKILL.md + 原生工厂
QQ 通道	无	OneBot V11 Reverse WS