# HomeAgent 架构设计 v4

## 一、核心理念

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

### 设计原则
- **核心零 IO** — Core 没有任何硬编码 IO 能力，所有 IO 来自插件
- **所有输出是工具调用** — Agent 必须显式调用 `output_send` 才能通信，推理不自动路由
- **所有 LLM 调用走 Provider 接口** — 不直连 API
- **DeepSeek v4 flash** 为默认 LLM，thinking 模式关闭
- **人格固定**（personal.md），记忆分层管理防止性格突变
- **知识独立于记忆**，agent 主动学习
- **插件 = 三通道**：工具、阶段钩子、事件订阅

---

## 二、核心域 vs 插件域

```
┌──────────────────────────────────────────────────────────────────┐
│                        核心域 (Core Domain)                         │
│                                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────────┐ │
│  │ Provider  │  │  Memory   │  │Knowledge │  │  Pipeline Stages  │ │
│  │  (LLM)   │  │ (T/D/G)  │  │ (TF-IDF) │  │   编排器          │ │
│  └──────────┘  └──────────┘  └──────────┘  └───────────────────┘ │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────────────────┐ │
│  │ Relevance│  │  Context  │  │    Plugin Host                   │ │
│  │  Tf-Idf  │  │ Persist  │  │  (调用钩子 + 路由工具)            │ │
│  └──────────┘  └──────────┘  └──────────────────────────────────┘ │
│                    核心无任何 IO 能力                               │
├──────────────────────────────────────────────────────────────────┤
│                        边界 (Plugin API)                           │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  RegisterTool(name, handler)   ← 插件注册工具给 LLM          │ │
│  │  RegisterStage(stage, handler) ← 插件挂入消息处理阶段         │ │
│  │  Subscribe(eventType, handler) ← 插件订阅系统事件             │ │
│  │  Publish(event)                → 插件发布事件                 │ │
│  │  Settings().Get/Set/List       ← 读写核心/插件配置            │ │
│  │  Memory().Recall/Commit        ← 图记忆访问                   │ │
│  │  Knowledge().Search/Create     ← 知识库访问                   │ │
│  └──────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────┤
│                        插件域 (Plugin Domain)                      │
│                                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │  WebUI   │  │   QQ     │  │OutputBus │  │ 未来插件: ……     │ │
│  │ HTTP/WS  │  │ OneBot   │  │通道管理   │  │                  │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │
│                    所有 IO 都在这里                                 │
└──────────────────────────────────────────────────────────────────┘
```

### 核心职责
- LLM 调用编排（Provider → Agent 工具循环）
- 三层记忆管理（Context → Document → Graph）
- 知识库维护（Knowledge Store）
- 阶段管道编排（Stage Pipeline）
- Context 相关性管理（TF-IDF 余弦相似度）
- 心跳蒸馏 + 图重整

### 插件职责
- 接收外部输入（WebSocket、HTTP、硬件等）
- 提供输出能力（文本发送、文件传输等）
- 干预消息处理流（阶段钩子）
- 观察系统状态（事件订阅）

---

## 三、消息处理阶段管道

```
                       ┌──────────────────────────────────────────┐
                       │            on_input                      │
                       │  消息到达，Agent 未做任何处理               │
                       │  └→ 插件可鉴权/拉黑/改写/短路回复           │
                       └──────────┬───────────────────────────────┘
                                  │ 通过
                       ┌──────────▼───────────────────────────────┐
                       │  内部：Context Append + Memory Recall     │
                       │         + Context 组装                    │
                       └──────────┬───────────────────────────────┘
                                  │ 就绪
                       ┌──────────▼───────────────────────────────┐
                       │            pre_action                     │
                       │  上下文已就绪，即将调用 LLM                 │
                       │  └→ 插件可注入 system 消息 / 修改 context  │
                       └──────────┬───────────────────────────────┘
                                  │ LLM 调用
                       ┌──────────▼───────────────────────────────┐
                       │            post_action                    │
                       │  LLM 返回文本 + 工具调用列表                │
                       │  └→ 插件可审查/修改文本、增删工具调用        │
                       └──────────┬───────────────────────────────┘
                                  │ 判断有无工具调用
                    ╱─────────────┴─────────────╲
              有工具调用                      无工具调用
                  │                              │
       ┌──────────▼──────────────┐               │
       │    before_toolcall       │               │
       │  即将执行某个工具调用     │               │
       │  └→ 插件可拒绝/放行/     │               │
       │     修改参数/审计        │               │
       └──────────┬──────────────┘               │
                  │ 执行工具                      │
       ┌──────────▼──────────────┐               │
       │    after_toolcall       │               │
       │  工具执行完毕，准备喂回   │               │
       │  └→ 插件可脱敏/改写结果  │               │
       └──────────┬──────────────┘               │
                  │ 回到 post_action 继续循环     │
                  └──────────────────────────────┘
                                                  │
                       ┌──────────────────────────┘
                       ▼
            ┌──────────────────────────────────────────┐
            │          before_output                    │
            │  最终文本就绪，即将调用 output_send        │
            │  └→ 插件可改写回复/添加格式/适配渠道       │
            └──────────────────┬───────────────────────┘
                               │ output_send 调用
            ┌──────────────────▼───────────────────────┐
            │          after_output                     │
            │  输出完成                                  │
            │  └→ 记录/统计/清理资源                     │
            └──────────────────────────────────────────┘
```

### 7 个阶段总表

| 阶段 | 触发时机 | 插件读写权限 | 典型用途 |
|---|---|---|---|
| `on_input` | 消息到 Agent，零处理 | 可读写 `raw_message`，可设置 `response` 短路 | 黑名单、限流、自定义指令前缀 |
| `pre_action` | Memory+Context 就绪，LLM 调用前 | 可读写 `context_messages`（追加/修改） | 注入 RAG 结果、插入时政 context |
| `post_action` | LLM 返回文本 + 工具调用列表 | 可读写 `llm_text`、`tool_calls`、`context_messages` | 敏感词过滤、强制 redirect 工具 |
| `before_toolcall` | 单个工具调用执行前 | 可读写 `tool_call.name`、`tool_call.args`，设置 `deny=true` 拒绝 | 审计高危操作、OS 命令白名单 |
| `after_toolcall` | 单个工具执行完毕 | 可读写 `tool_result` | 脱敏数据库结果、排序搜索结果 |
| `before_output` | 最终文本就绪，output_send 前 | 可读写 `final_text`，可设置 `skip_output=false` | 添加表情/at 前缀、多平台格式适配 |
| `after_output` | output_send 已调用 | 只读 `final_text` | 统计日志、触发后续流程 |

### 循环规则

`post_action → before_toolcall → after_toolcall → 回到 post_action` 构成**内循环**。Agent 在以下条件退出循环进入 `before_output`：
- LLM 返回纯文本（无工具调用）
- `before_toolcall` 拒绝所有剩余工具且 LLM 无可执行工具
- 循环超过 `max_tool_rounds` 上限

### 短路规则

每个阶段插件都可设置 `ctx.Response`，一旦设置管道立即短路到 `after_output`：
```
on_input → ctx.Response = "hello" → 跳过后面的所有阶段 → after_output
```

---

## 四、记忆体系（三层递进）

```
输入消息
    │
    ▼
┌─────────────────────────────────────────────────────┐
│  Layer 1: Context (RelevanceContext)                 │
│  内存中维护最近 topK 条事件，TF-IDF 评分，JSON 持久化   │
│  每次 Append/Prune → save() 防崩溃丢数据              │
│  keep=30 条活跃，多余 → 归档到 Document               │
└────────────────────┬────────────────────────────────┘
                     │  Prune 时
                     ▼
┌─────────────────────────────────────────────────────┐
│  Layer 2: Document (document.Store)                  │
│  文件系统 JSON + TF-IDF 向量索引                      │
│  冷文档（72h 未访问 + access ≤ 2）→ 蒸馏到 Graph     │
│  也可以由用户主动 commit（doc_commit 工具）           │
└────────────────────┬────────────────────────────────┘
                     │  reorg 心跳
                     ▼
┌─────────────────────────────────────────────────────┐
│  Layer 3: Graph (GraphDB + Indexer)                  │
│  SQLite: entities + relations                        │
│  Entity: name, type, mention_count                   │
│  Relation: source → target, relation_type, confidence│
│  搜索: 关键词 → 向量搜索实体 → BFS 遍历邻居          │
│  蒸馏: 原始记录 → Distiller → 三元组提交             │
└─────────────────────────────────────────────────────┘
```

### 数据流关系

```
Context 修剪 → Document 归档 → reorg 心跳 → Graph 消化
                                              ↑
                                     Distiller (原始记录 → 三元组)
```

### 工具入口（Agent 暴露给 LLM）

- `memory_recall(query)` → 从 Graph 召回
- `memory_commit(triples)` → 写入 Graph
- `memory_introspect()` → 查看统计
- `doc_query(query)` → 从 Document 搜索
- `doc_commit(title, content)` → 写入 Document

---

## 五、知识体系

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

```
knowledge/<name>/
    content.md

knowledge.Store
    └─ TF-IDF 向量索引 (character bigram)
    └─ 独立于 memory 的 vector.Store 实例
    └─ Start() 时扫描目录训练索引
    └─ Add(name, content) 时增量更新
```

### 工具入口

- `knowledge_search(query)` → 向量搜索
- `knowledge_create(name, content)` → 新增
- `knowledge_list()` → 列出所有

### 为什么独立于 memory？

- Memory 是 LLM 的"对话记忆"——谁说过什么、上下文
- Knowledge 是 LLM 的"知识库"——外部注入的固定知识
- 两者 TF-IDF 索引实例隔离，不互相污染

---

## 六、三通道插件交互

```
插件 ──→ 核心                  核心 ──→ 插件
──────────────────────────────────────────────────
RegisterTool(name, fn)  ──→  buildToolDefs()
                             executeToolCall() → fn
                             （Tracker 自动包裹 Pre/PostAction）

RegisterStage(stage, fn) ──→  runStage() 在对应阶段调用 fn(ctx)
                             返回后检查 ctx.Response 决定是否短路

Subscribe(eventType, fn) ──→  Publish(event)
                             所有订阅者收到（观察型）
```

### 通道对比

| 通道 | 方向 | 用途 | 可否拦截 |
|---|---|---|---|
| **工具** (RegisterTool) | 插件→核心→LLM | LLM 主动调用插件功能 | 否 |
| **阶段** (RegisterStage) | 核心→插件 | 核心触发插件干预消息流 | 是（response 短路） |
| **事件** (Subscribe/Publish) | 双方向 | 审计/日志/状态通知 | 否 |

---

## 七、Agent 内部完整流程

```
processTextInput(input)
    │
    ├── on_input stage ────────────── 插件可拦截/改写
    │
    ├── context.Append(input)
    ├── context.Prune(input)         → 归档到 Document
    ├── buildMemoryContext()         → Indexer.BuildContext → Graph Recall
    │
    ├── pre_action stage ──────────── 插件可注入 context
    │
    ├── [循环] process(input)
    │   ├── buildSystemPrompt (人格+记忆+技能+上下文)
    │   ├── buildToolDefs (内置工具 + 插件工具)
    │   ├── provider.Chat() → LLM
    │   │
    │   ├── post_action stage ─────── 插件可见 LLM 输出 + 工具列表
    │   │
    │   ├── 有工具调用？
    │   │   ├── 每个工具:
    │   │   │   ├── before_toolcall stage ── 插件可拒绝/改参
    │   │   │   ├── Tracker.PreAction
    │   │   │   ├── executeToolCall() ──── 路由到插件或内置
    │   │   │   ├── Tracker.PostAction
    │   │   │   └── after_toolcall stage ── 插件可改结果
    │   │   └── → 回到 post_action (继续循环)
    │   │
    │   └── 无工具调用 → 退出循环
    │
    ├── context.Append(response)
    ├── before_output stage ───────── 插件可改写最终文本
    ├── Publish(agent_output event)
    ├── output_send (调用插件注册的 output 工具)
    │
    └── after_output stage ────────── 插件只读，做统计/日志
```

---

## 八、记忆整理（心跳 LLM 驱动消歧）

图数据库在长期运行中会积累**同义实体**（如「张三」与「张先生」指同一人）和**矛盾关系**。心跳流程如下：

### 流程

```
心跳 tick (30min)
    │
    ├── distillContext()         — 蒸馏上下文
    ├── syncGraphToDocs()        — 图→文档
    │
    └── reorgGraph()
        ├── Indexer.Sync()       — 图→向量（自动）
        ├── DocStore.Reindex()   — 文档重建索引（自动）
        ├── 冷文档→图归化        — 将冷文档归档为图三元组（自动）
        │
        └── 实体冲突检测 → 发现相似实体对
                │ 如：「张三」(person, 5次) vs 「张先生」(person, 3次)  相似度 0.75
                │
                ▼
            enqueueConsolidationTask()
                │ 通过 IO 层注入 Agent 输入队列
                │ channel = "_consolidation_"（内部通道，不对外输出）
                ▼
            Agent 处理 (processConsolidation)
                │ 如同普通用户消息，走完整 LLM 工具循环
                │ 但输出仅写记忆，不发外部通道
                ▼
            LLM 决策：
                ├─ 判断为同一实体 → 调用 memory_merge 合并
                │   → "已将「张先生」合并到「张三」，3 条关系已重定向"
                ├─ 判断为不同实体 → 回复"跳过"
                └─ 不确定 → 回复"待定，需更多上下文"
```

### 关键设计

| 特性 | 说明 |
|---|---|
| **启发式检测，LLM 决策** | bigram Jaccard 仅做候选筛选（低门槛 0.5），LLM 做最终判断 |
| **走 IO 输入队列** | 不阻塞心跳，不抢占用户输入，享受完整 Agent 上下文 |
| **`_consolidation_` 通道** | 内部专用通道，输出只写记忆层，不被外部插件路由 |
| **`memory_merge` 工具** | LLM 通过此工具执行合并，自动重定向关系 + 累积 mention_count |
| **异步非阻塞** | 整理任务排队在 inputCh 尾部，Agent 按序处理，不影响用户体验 |

### 类比

类似人类睡眠时大脑的海马体回放——白天经历的记忆在休息时被自发整理、关联、去重。HomeAgent 的心跳就是它的"睡眠周期"，而 LLM 的参与相当于前额叶皮层执行语义判断。类比：

```diff
- 人类:  白天经历 → 海马体暂存 → 睡眠 → 前额叶整理 → 长期记忆
+ Agent: 用户交互 → Context缓存 → 心跳 → LLM 消歧 → GraphDB 存储
```

---

## 九、Child Agent

不走阶段管道，独立轻量 Agent：

```
spawn_child(task) → 新建轻量 Agent
    ├── 独立 system prompt（仅有任务描述）
    ├── 仅 output_send 工具
    ├── 无 persistent memory
    ├── 无 Graph/Document 访问
    ├── 上限 5 轮工具循环
    └── 销毁时返回结果文本
```

---

## 九、LLM Provider 与 Lua 适配层

LLM 调用全部通过 `Provider` 接口，核心实现是 `LuaAdaptedProvider`：

```
Agent
  │
  ▼
Provider 接口 (Name / Chat / ChatStream)
  │
  ▼
LuaAdaptedProvider
  ├── 1. 序列化 CompletionRequest → raw JSON
  ├── 2. adapter.transform_request(rawJSON) → 协议特定请求体
  ├── 3. 读取 adapter.endpoint + adapter.headers 发 HTTP
  ├── 4. adapter.transform_response(rawHTTPBody) → 统一响应格式
  └── 5. 反序列化为 CompletionResponse
```

### Lua 适配器契约

每个适配器是一个返回 table 的 Lua 脚本，位于 `data/adapters/*.lua`：

```lua
adapter.name = "deepseek"
adapter.version = "2.0.0"
adapter.endpoint = "/chat/completions"
adapter.headers = {}  -- 静态头（Go 自动加 Authorization）

-- 请求变换：raw JSON → 协议格式
function adapter.transform_request(raw_body) return transformed end

-- 响应变换：HTTP body → 统一格式 {content, reasoning_content, finish_reason, token_usage, tool_calls}
function adapter.transform_response(raw_body) return unified end

-- 流变换（可选）：SSE data line → {content, done}
function adapter.transform_stream_chunk(raw_line) return chunk end
```

### Lua VM 能力

- `json.encode(table)` → 使用 Go `json.Marshal` 的 JSON 序列化
- `json.decode(string)` → 使用 Go `json.Unmarshal` 的 JSON 反序列化
- 全局函数 `log(level, msg)` / `http_get(url)` / `http_post(url, body)`
- 适配器内置 3 个：`openai.lua`、`deepseek.lua`、`ollama.lua`

## 十、配置中心 (ConfigRegistry)

配置不再分散在各处——通过 `ConfigRegistry` 统一管理：

```
Plugin (通过 SDK)
  │
  ├─ Settings().Get("core.llm.model")        → 读核心配置
  ├─ Settings().Set("plugin.qq.token", x)    → 写插件配置
  ├─ Settings().List("plugin.")              → 列出所有插件键
  │
  ▼
ConfigRegistry (线程安全 KV 存储)
  ├── 持久化到 data/settings.json
  ├── 键命名空间: core.* / plugin.<name>.*
  ├── Register(key, default)  ← 注册默认值（不标记 dirty）
  ├── Get/Set/List/Delete     ← 运行时读写
  └── Flush()                 ← 写回磁盘
```

### WebUI 配置编辑

```
┌──────────────────────────────────┐
│  侧边栏         编辑区            │
│  ┌──────┐  ┌──────────────────┐  │
│  │ core │  │ core.llm.model   │  │
│  │plugin│  │ [input field]    │  │
│  │.qq   │  │ [保存]           │  │
│  │plugin│  ├──────────────────┤  │
│  │.webui│  │ core.llm.base_url│  │
│  └──────┘  │ [input field]    │  │
│            │ [保存]           │  │
│            └──────────────────┘  │
└──────────────────────────────────┘
```

- `GET /api/v1/settings?prefix=core.` → 列出配置键值 + 插件列表
- `PUT /api/v1/settings` → `{key, value}` 写入配置

## 十一、SDK API 定义

### PluginAPI (`internal/plugin/sdk/api.go`)

```go
type PluginAPI struct {
    Name    string
    Version string
}

func NewPluginAPI(name, version string, bus EventBus, mem MemoryAPI, know KnowledgeAPI) *PluginAPI

// 三通道
func (p *PluginAPI) RegisterTool(name string, handler ToolHandler) error
func (p *PluginAPI) RegisterStage(stage Stage, handler StageHandler)
func (p *PluginAPI) Subscribe(eventType EventType, handler EventHandler)
func (p *PluginAPI) Publish(evt *Event)

// 访问子系统的快捷方式
func (p *PluginAPI) Memory() MemoryAPI
func (p *PluginAPI) Knowledge() KnowledgeAPI
```

### 阶段上下文 (`StageContext`)

```go
type StageContext struct {
    RawMessage  string                    // 当前输入（可改写 on_input）
    UserID      string
    GroupID     string
    ContextMsgs []map[string]interface{}  // 可注入的消息
    LLMText     string                    // LLM 返回文本（可改写 post_action）
    ToolCalls   []ToolCall                // 工具调用列表（可增删 post_action/before_toolcall）
    ToolResults []ToolResult              // 工具执行结果（可改写 after_toolcall）
    FinalText   string                    // 最终输出文本（可改写 before_output）
    Response    *string                   // 设置后短路管道
    Phase       Stage                     // 当前阶段
    Memory      []MemItem                 // 召回的记忆
    Extra       map[string]interface{}    // 扩展字段
}
```

---

## 十二、事件系统

### 事件类型

| 类型 | 发布时机 | 用途 |
|---|---|---|
| `raw_input` | 消息到达 Agent | 记录输入日志 |
| `agent_output` | 最终输出发送后 | 记录输出日志 |
| `tool_call` | 每个工具调用完成 | 审计工具调用 |
| `reasoning` | LLM 推理文本 | 展示推理过程 |
| `system` | 系统状态变更 | 健康检查、插件变更 |

### Event Bus (`internal/events/bus.go`)

```go
type Bus struct{}
func NewBus() *Bus
func (b *Bus) Publish(event *Event)
func (b *Bus) Subscribe(eventType EventType, handler Handler) func()
```

---

## 十三、自循环输入通道

核心维护一个独立的 `selfInputCh (chan string)`，用于内部任务（记忆消歧、系统维护），不经过 IO 层：

```
心跳检测 → entitySimilarity() → enqueueConsolidationTask()
                                         │
                                    injectSelf(msg)
                                         │
                                    selfInputCh ─→ eventLoop ─→ processTextInput
                                         │
                                   不经过 IOManager，不经过任何插件
```

区别于 IOManager.InputChan（外部输入），selfInputCh 是核心自有的纯 Go channel，
确保即使没有 IO 插件，记忆整理等维护任务也能正常执行。

## 十四、数据流全景

```
外部 (QQ/HTTP/硬件)
    │ 通过插件
    ▼
IOManager.InjectInput() → inputCh
    │
    ▼
Agent.eventLoop() → handleInput → processTextInput
    │
    ├── 1. on_input stage（插件可拦截）
    ├── 2. Context.Append
    ├── 3. Memory Recall (Indexer → Graph)
    ├── 4. pre_action stage（插件可注入）
    ├── 5. 工具循环 (最多 10 轮)
    │      LLM → post_action → [before_toolcall → 执行 → after_toolcall] → LLM ...
    ├── 6. Context.Append(response)
    ├── 7. Prune（不相关 → Document）
    ├── 8. before_output stage（插件可改写）
    ├── 9. EmitOutput (通过 output_send 到对应通道)
    ├── 10. after_output stage（插件只读）
    └── 11. memory_candidate → TextMemory + Distiller → GraphDB

心跳（30min）:
    ├── distillContext()
    ├── syncGraphToDocs()
    └── reorgGraph()
        ├── Indexer.Sync() — 图→向量（自动）
        ├── DocStore.Reindex() — 文档向量重建（自动）
        ├── 冷文档→图归化（自动）
        └── 实体冲突检测 → 走 LLM 消歧（详见第八章）
```

---

## 十五、代码结构

```
cmd/homed/main.go                        — 入口：组装所有子系统, 零 IO
cmd/waiter/main.go                       — CLI 客户端 (Unix socket)
internal/
├── agent/
│   ├── core/
│   │   ├── agent.go                     — Agent: eventLoop/interceptLoop/process/distillLoop
│   │   ├── context.go                   — RelevanceContext：TF-IDF 上下文管理
│   │   └── stages.go                    — StageHost：阶段管道编排 (并行执行)
│   ├── api/
│   │   └── provider.go                 — Provider 接口 + DeepSeek/Ollama/LuaAdaptedProvider
│   ├── io/
│   │   └── channel.go                  — IOManager (排队/中断/输出三通道)
│   └── personal.go                     — 人格加载
├── sdk/                                 ★ PluginSDK: 核心 Go API
│   ├── plugin.go                       — Plugin 接口 + PluginSDK 结构体
│   ├── memory.go                       — MemoryAPI (图/文本/文档)
│   ├── knowledge.go                    — KnowledgeAPI
│   ├── settings.go                     — SettingsAPI (配置)
│   └── llm.go                          — LLMAPI (源管理)
├── config/
│   └── registry.go                     — ConfigRegistry：统一配置中心 (SQLite)
├── events/
│   └── bus.go                          — 系统事件总线 (Publish/Subscribe)
├── plugin/
│   ├── registry.go                     — 注册表：生命周期 Load/StopAll/Reload, RegisterFactory
│   ├── manifest.go                     — PluginManifest (plugin.json 元数据)
│   ├── dynamic.go                      — .so 动态加载器 (Go plugin.Open)
│   └── plugin.go                       — SKILL 插件解析 (OpenClaw 兼容)
├── plugins/
│   ├── all.go                          — 空白导入触发所有内置插件 init()
│   ├── timer/plugin.go                 — 定时器 (timer_set 工具 + 中断反馈)
│   ├── cli/plugin.go                   — CLI 插件 (Unix socket, InjectTextSync)
│   ├── openclaw/plugin.go              — OpenClaw 兼容 (SKILL.md → SDK 工具注册)
│   └── webui/                          — WebUI 插件 (HTTP 服务器 + 仪表盘)
│       ├── plugin.go
│       └── handler.go
├── memory/
│   ├── graph.go                        — SQLite 图数据库
│   ├── indexer.go                      — 图索引器
│   ├── vector/store.go                 — TF-IDF 向量存储
│   ├── document/doc.go                 — 文档记忆
│   ├── text/text.go                    — 文本记忆 (JSONL)
│   └── pipeline/                       — 蒸馏器
├── knowledge/
│   └── knowledge.go                    — 知识系统
├── onebot/                             — OneBot V11 QQ 协议实现
├── tracker/                            — 变更追踪 (overlayfs)
├── supervisor/                         — 守护进程
├── skill/                              — 技能管理器
├── lua/
│   ├── vm.go                           — Lua VM (json.encode/decode, transform)
│   └── adapters/                       — LLM 协议适配器脚本
├── network/                            — 网络监控
├── container/                          — 容器管理
├── snapshot/                           — 快照
├── embed/                              — 嵌入
└── tokenizer/                          — 分词器
config/                                 — 顶层配置加载
├── config.go                           — Config 结构
└── config.yaml
pkg/types/                              — 类型定义
docs/
├── ARCHITECTURE.md                     — 本架构文档
├── ADAPTER.md                          — Lua 适配器文档
└── PLAN.md                             — 实施计划/概览
```

---

## 十六、与旧设计 (v3) 的关键区别

| 维度 | v3 | v4 |
|------|-----|-----|
| 插件交互 | Device 接口 + IOManager 路由 | 三通道：Tool/Stage/Event/Settings |
| 消息流编辑 | 无（纯事件推送） | 阶段管道 7 个 hook 点 |
| Event Bus | 无 | `internal/events/bus.go` |
| SDK | 无 | `internal/plugin/sdk/` (含 SettingsAPI) |
| LLM 适配 | 硬编码 Provider | Lua 脚本 raw JSON 变换 |
| 配置管理 | 分散在各处 | ConfigRegistry 统一 KV 存储 |
| 核心 IO | IOManager `EmitOutput` 直出 | 全部走 `output_send` 工具 |
| 插件工具路由 | IOManager `ExecuteTool` 链 | StageHost + Registry 双层路由 |
| 内部任务 | 无 | selfInputCh 自循环通道（不经过 IO） |

---

## 十七、插件自注册与动态加载

### 自注册机制

内置插件通过 `init()` 自注册，无需 `main.go` 硬编码：

```go
// internal/plugins/timer/plugin.go
func init() {
    plugin.RegisterFactory("timer", func(name string, config map[string]interface{}) (sdk.Plugin, error) {
        return New(name), nil
    })
}
```

空白导入文件 `internal/plugins/all.go` 触发所有内置插件的 `init()`：

```go
package plugins
import (
    _ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/cli"
    _ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/openclaw"
    _ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/timer"
    _ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/webui"
)
```

`main.go` 不再需要 `RegisterNative` 调用，只需设置包级变量注入运行时依赖：

```go
cli.DefaultSocket = *cliSocket
openclaw.SkillsDir = filepath.Join(*dataDir, "skills")
webui.Configure(httpAddr, sup, memDB, ...)
pluginReg.Load(plgDir)  // 自动扫描目录 + 使用已注册的工厂
```

`Load()` 分两步执行：
1. 扫描 `plugins/` 下已有子目录，匹配已注册工厂加载
2. 对已注册工厂但尚无目录的，自动创建目录并加载

### 动态 .so 加载

第三方插件编译为 `.so` 文件，放入 `<data>/plugins/<name>/`：

```
<data>/plugins/myplugin/
    plugin.json   { "name": "myplugin", "version": "1.0", "entry": "plugin.so" }
    plugin.so     (Go -buildmode=plugin, 导出 NewPlugin 函数)
```

加载器 (`internal/plugin/dynamic.go`) 流程：

```go
tryLoadSO(dir, name, config):
    1. plugin.Open("plugin.so")
    2. Lookup("NewPlugin") — 签名 func(name string, config map[string]interface{}) (sdk.Plugin, error)
    3. 调用 factory, 包装为 dynamicPlugin
```

内置插件保持 init() 自注册编译进内核，第三方插件以 .so 形式热加载。

---

## 十八、中断打断机制

### 架构

```
interceptLoop (独立 goroutine)
    ├── InputInterruptChan() ← 定时器/消息通知等
    │
    ├── (a) cancelLLM() → Provider HTTP 请求取消
    ├── (b) interceptCh < text → process() turn 前 drainInterrupt()
    └── (c) InjectInput("interrupt", "text", ...) → 空闲时触发新处理
```

### 三种投递路径

| 路径 | 目标 | 触发时机 |
|------|------|---------|
| **(a) cancelLLM** | 取消进行中的 Provider HTTP 请求 | 拦截到 `context.Canceled` |
| **(b) interceptCh** | process() 工具循环中注入 `[打断消息]` | 每个 LLM call 前 `drainInterrupt()` |
| **(c) InjectInput** | eventLoop 空闲时启动新处理循环 | 无进行中请求时 |

### process() 内中断注入

```go
for turn := 0; turn < maxTurns; turn++ {
    if text := a.drainInterrupt(); text != "" {
        msgs = append(msgs, agentAPI.Message{
            Role: "system",
            Content: fmt.Sprintf("[打断消息] %s", text),
        })
    }
    // LLM call with cancellable context
    reqCtx, cancel := context.WithCancel(a.ctx)
    a.cancelLLM = cancel       // interceptLoop 可调用
    resp, err := provider.Chat(reqCtx, req)
    a.cancelLLM = nil
    cancel()
    // ... tool call loop ...
}
```