docs: rewrite DESIGN.md and ARCHITECTURE.md matching current architecture

- Plugin = container with embedded IO channel
- OneBot QQ protocol support
- Output channel capability validation
- Atomic hot-reload (plgreload)
- Three-layer memory (TF-IDF relevance pruning)
- Remove all Docker/snapshot/multi-agent outdated content

DESIGN.md

@@ -1,241 +1,188 @@
-# HomeAgent 架构设计 v2
+# HomeAgent 架构设计 v3
 
 ## 一、核心理念
 
-24 小时陪伴用户、随时待命的智能管家。**单会话·单 Agent**（可分身/调用其他 Agent），身份不漂移。
+24 小时陪伴用户、随时待命的智能管家。**单会话·单 Agent**，身份不漂移。
 
 ### 设计原则
-- 所有输入走 IO 抽象层（中断模式），不直调 agent 方法
-- DeepSeek v4 flash 为默认 LLM，thinking 模式关闭
-- 人格固定（personal.md），记忆分层管理防止性格突变
-- 知识独立于记忆，agent 主动学习
+- **所有输入走 IO 抽象层（中断模式）**，不直调 agent 方法
+- **所有 LLM 调用走 Provider 接口**，不直连 API
+- **DeepSeek v4 flash** 为默认 LLM，thinking 模式关闭
+- **人格固定**（personal.md），记忆分层管理防止性格突变
+- **知识独立于记忆**，agent 主动学习
+- **插件 = 容器**，IO 通道是插件的内嵌组件
 
 ---
 
-## 二、人格内核（Personality Core）
+## 二、核心抽象
+
+### IO 抽象层（唯一输入路径）
 
 ```
-personal.md ──→ 固定注入 system prompt
+外部设备 (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
+  └─ 路由表: 输入源 → 默认输出通道
 ```
 
-- 纯文本 Markdown 文件，定义 agent 的人格、行为准则
-- 加载一次永不改变（不随对话漂移）
-- 放在 prompt 最前面，优先级最高
+**输出通道能力声明**（`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
 
 ---
 
-## 三、记忆体系（Memory System）
-
-三层分级架构，自顶向下逐渐持久化、抽象化：
+## 三、记忆体系（三层）
 
 ```
-             用户输入
-                 │
-                 ▼
-     ┌─────────────────────┐
-     │  Layer 1: 上下 文    │  RelevanceContext
-     │  基于相关性保留      │  30 条活跃，TF-IDF 排序
-     │  最不相关的→文档记忆 │  
-     └────────┬────────────┘
-              │ 相关性裁剪（每次响应后）
+用户输入 → Context（内存, 30条, TF-IDF排序）
+              │ 每次响应后裁剪最不相关的
               ▼
-     ┌─────────────────────┐
-     │  Layer 2: 文档记忆   │  document.Store
-     │  全文 + TF-IDF 向量  │  JSON 持久化
-     │  冷文档→图数据库     │  72h 未访问→Graph
-     └────────┬────────────┘
+          Document（JSON + TF-IDF向量, 冷72h→图）
               │ 心跳蒸馏（30min）
               ▼
-     ┌─────────────────────┐
-     │  Layer 3: 图数据库   │  memory.GraphDB (SQLite)
-     │  实体-关系三元组     │  向量索引（实体名）
-     │  定期重整+同义合并   │  bigram Jaccard
-     └─────────────────────┘
+          Graph（SQLite三元组, 定期重整+同义合并）
 ```
 
-### Layer 1: 上下文（RelevanceContext）
+| 层 | 存储 | 容量 | 裁剪策略 |
+|---|---|---|---|
+| Layer 1: 上下文 | `RelevanceContext`（内存环形缓冲） | 30 条 | TF-IDF 余弦相似度排序，低分→文档 |
+| Layer 2: 文档 | `document.Store`（JSON 文件 + 向量索引） | 无上限 | 72h 未访问 + ≤2 次命中→图 |
+| Layer 3: 图 | `memory.GraphDB`（SQLite 三元组） | 无上限 | 定期重整 + bigram Jaccard 同义合并 |
 
-**不再使用固定条数裁剪。改为：**
-
-1. 每次用户输入后，计算**模型输出**与每条上下文的 TF-IDF 余弦相似度
-2. 按相关性从高到低排序，保留 topK（默认 30）
-3. 最不相关的上下文 → 归档到文档记忆（Layer 2），保留全文+向量
-4. 活跃上下文中只保留最近且相关性高的内容
-
-**相关文件：** `internal/agent/core/context.go`
-
-### Layer 2: 文档记忆（Document Store）
-
-**作用：**
-- 存储被上下文裁剪下来的事件摘要、agent 主动提交的文档、图记忆同步的索引
-- 每个文档包含：摘要、全文、标签、实体、来源、访问计数、最后访问时间
-- TF-IDF 向量索引（字符 bigram），支持向量相似度搜索
-
-**冷文档归化：**
-- 心跳检测（每 30min）：找出 72h 未访问且访问次数 ≤ 2 的文档
-- 转为图数据库三元组（文档→包含内容、提及实体、标签、来源）
-- 清理已归化的冷文档
-
-**相关文件：** `internal/memory/document/document.go`
-
-### Layer 3: 图数据库（Graph Memory）
-
-**存储：** SQLite 三元组（实体-关系-实体），每个关系带置信度、会话 ID、日期桶
-
-**注入方式（区分于文档注入）：**
-- 用户消息到达时，先对实体名做**向量相似度搜索**（TF-IDF）
-- 找到相关实体名 → 查询图数据库
-- 只注入**节点索引**（实体名+类型+提及次数+关系类型）到 prompt，不注入全文
-- 需要更多细节时，agent 调用 `memory_recall` 工具查询
-
-**定期重整（心跳触发，每 30min）：**
-1. 同步实体名到向量索引（`Indexer.Sync()`）
-2. 文档记忆向量索引重建
-3. 冷文档→图归化
-4. 实体同义合并（bigram Jaccard > 0.5）
-
-**相关文件：** `internal/memory/graph.go`, `internal/memory/indexer.go`
-
-### Agent 可用记忆工具
-
-| 工具 | 作用 | 操作对象 |
-|------|------|----------|
-| memory_recall | 检索图记忆 | GraphDB |
-| memory_commit | 写入三元组 | GraphDB |
-| memory_introspect | 查看记忆统计 | GraphDB |
-| doc_query | 向量查询文档记忆 | Document Store |
-| doc_commit | 提交文档 | Document Store |
+**注入策略**：
+- 只注入**图索引**（实体名+类型+提及数）到 prompt，不注入全文
+- agent 通过 `memory_recall` 主动查询详情
+- 文档摘要按相关性注入前 3 条
 
 ---
 
-## 四、知识体系（Knowledge System）
+## 四、知识体系
 
-独立于记忆系统，用于 agent 学习知识：
+独立于记忆，agent 主动学习。
 
 ```
 knowledge/
-  smart_home/
-    content.md     ← 原始知识文件
-  cooking/
-    content.md
-  ...
+  smart_home/content.md
+  cooking/content.md
        │
        ▼
-  TF-IDF 向量索引 ← 知识目录扫描时自动构建
+  TF-IDF 向量索引（字符 bigram）
        │
        ▼
-  knowledge_search(query) → 返回相关内容
+  knowledge_search / knowledge_create / knowledge_list
 ```
 
-**知识来源：**
-1. **agent 主动学习**：调用 `knowledge_create` 工具，生成知识→写入目录+向量化
-2. **用户上传**：HTTP 文件上传端点 → 写入目录+向量化
-3. **预置知识**：`knowledge/` 目录下的 content.md
-
-**相关文件：** `internal/knowledge/knowledge.go`
-
-### Agent 可用知识工具
-
-| 工具 | 作用 |
-|------|------|
-| knowledge_search | 向量搜索知识库 |
-| knowledge_list | 列出知识分类 |
-| knowledge_create | agent 主动创建知识 |
-
 ---
 
-## 五、数据流总览
+## 五、人格内核
+
+```personal.md``` → 加载一次 → 固定在 system prompt 最前 → 永不漂移。
+
+---
+
+## 六、OneBot QQ 通道
 
 ```
-用户消息
-  │
-  ▼
-IO 输入中断 (channel.go)
-  │
-  ▼
-eventLoop → processTextInput
-  │
-  ├─ 1. 追加上下文 (RelevanceContext.Append)
-  │     └─ 计算向量，缓存
-  │
-  ├─ 2. 构建 prompt：
-  │     ├─ 人格设定 (personal.md)
-  │     ├─ 图记忆索引 (Indexer.BuildContext → 向量搜索实体名 → Recall → 摘要注入)
-  │     ├─ 文档记忆摘要 (DocStore.Query → 注入前3条摘要)
-  │     ├─ 工作记忆上下文 (RelevanceContext.Format)
-  │     ├─ 技能注入 (skills)
-  │     └─ 工具说明 (indexer + doc + knowledge tools)
-  │
-  ├─ 3. 工具循环 (process)
-  │     ├─ 调用 LLM (DeepSeek v4 flash)
-  │     ├─ 解析 tool_calls
-  │     ├─ 执行工具 (memory_*/knowledge_*/doc_*/设备工具)
-  │     └─ 返回结果，循环直到无 tool_calls
+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. 相关性裁剪 (RelevanceContext.Prune)
-  │     └─ 最不相关的 → 文档记忆归档
-  │
-  ├─ 6. IO 输出响应
-  │
-  └─ 7. 记忆候选事件
-        └─ → TextMemory (JSONL 持久化)
-            └─ → Distiller → GraphMemory (三元组萃取)
+  ├─ 5. 相关性裁剪（Prune → 不相关的归档到文档）
+  ├─ 6. OutputEvent → 输出通道
+  └─ 7. 记忆候选 → TextMemory(JSONL) + Distiller → GraphDB
 
-心跳线程 (每 30min):
-  ├─ distillContext: 安全裁剪兜底
-  ├─ syncGraphToDocs: 图→文档索引同步
-  ├─ reorgGraph:
-  │   ├─ Indexer.Sync(): 实体名→向量索引
-  │   ├─ DocStore.Reindex(): 文档向量重建
-  │   ├─ 冷文档→图归化
-  │   └─ 同义实体合并
-  └─ (后续) GraphDB 向量索引生成/重整
+心跳（30min）:
+  ├─ Indexer.Sync() — 图→向量
+  ├─ DocStore.Reindex() — 文档向量重建
+  ├─ 冷文档→图归化
+  └─ 图同义合并
+
+插件重载（plgreload）:
+  ├─ 扫描 plugins/ 目录
+  ├─ 加载新插件，Start 新设备
+  ├─ 原子替换 IOManager 设备表 + 路由表
+  └─ Stop 旧设备
 ```
 
 ---
 
-## 六、关键文件
-
-```
-cmd/homed/main.go               — 入口：组装所有子系统
-internal/agent/core/agent.go     — Agent 核心：事件循环、工具循环、心跳
-internal/agent/core/context.go   — RelevanceContext：基于 TF-IDF 的上下文管理
-internal/agent/personal.go       — Personality：personal.md 加载
-internal/agent/api/provider.go   — LLM Provider：DeepSeek API 封装
-internal/agent/io/channel.go     — IO 抽象层：中断输入、设备注册
-internal/api/handler.go          — HTTP API：REST + OpenAI 兼容端点
-internal/knowledge/knowledge.go  — 知识系统：目录扫描、向量索引、搜索
-internal/memory/graph.go         — 图数据库：SQLite 三元组 CRUD
-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/tracker/tracker.go      — Change Tracker：overlayfs 文件变更追踪
-internal/plugin/plugin.go        — 插件平台：SKILL.md 加载
-internal/supervisor/daemon.go    — 守护进程：健康检查、自动 rollback
-internal/lua/vm.go               — Lua 适配器 VM
-config/config.go                 — 配置加载
-pkg/types/                       — 类型定义
-```
-
----
-
-## 七、配置示例
+## 八、配置
 
 ```yaml
 daemon:
   listen_addr: ":8080"
   data_dir: "/var/lib/homeagent"
   heartbeat_interval: 15s
-  check_interval: 30s
-
 llm:
-  provider: "openai"
   model: "deepseek-v4-flash"
-  base_url: "https://api.deepseek.com"
+  base_url: "https://api.deepseek.com/v1"
   api_key: "${DEEPSEEK_API_KEY}"
   temperature: 0.7
   max_tokens: 4096
@@ -243,15 +190,51 @@ llm:
 
 ---
 
-## 八、对比原设计
+## 九、关键文件
 
-| 维度 | 旧设计 | 新设计 |
-|------|--------|--------|
-| 上下文裁剪 | 固定 20 条 FIFO | TF-IDF 相关性排序，保留最相关 |
-| 上下文→文档 | 蒸馏器每周期 flush | 每次响应后按相关性裁剪归档 |
+```
+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 冷文档自动归化 |
-| 图重整 | 无 | 心跳：向量同步+同义合并 |
-| 知识系统 | 无 | `knowledge/` 目录+向量索引+工具 |
+| 图重整 | 无 | 向量同步 + bigram Jaccard 同义合并 |
+| 知识系统 | 无 | `knowledge/` 目录 + TF-IDF 向量 |
 | 人格 | 无 | `personal.md` 固定注入 |
-| 向量引擎 | 无 | 自研 TF-IDF + 倒排索引 |
+| 向量引擎 | 无 | 自研 TF-IDF + 倒排索引（字符 bigram） |
+| 部署 | Docker 容器 + 快照 | 单二进制 + overlayfs 追踪 |
+| Agent 模型 | 多 Agent 编排 | 单 Agent + 工具循环 |
+| 输出通道 | 无 | 能力声明 + 路由 + 校验 |
+| 插件系统 | 无 | OpenClaw SKILL.md + 原生工厂 |
+| QQ 通道 | 无 | OneBot V11 Reverse WS |

docs/ARCHITECTURE.md

@@ -1,79 +1,50 @@
-# HomeAgent 架构设计文档
+# HomeAgent 架构参考
 
-> 基于 NextAgent 认知解耦架构，结合图记忆与工具调用系统的单二进制 AI 家庭助手。
-> 参考设计：NextAgent — 严格的边界划分 + 工具调用；TrulyMEM — 自主图记忆系统
+> 基于 NextAgent 认知解耦架构 + TrulyMEM 自主图记忆 + OneBot 协议。
 
----
-
-## 一、核心设计原则
-
-### 1. 认知解耦架构（源自 NextAgent）
-
-系统分为三个严格边界层：
+## 一、分层架构
 
 ```
-┌──────────────────────────────────────────────────────────────────┐
-│                    外层：IO 抽象层（唯一输入路径）                    │
-│  IOManager ── Microphone / Camera / GPIO / HTTP / Sensors       │
-│  所有外部输入 → InputEvent → inputCh                              │
-└──────────────────────────┬───────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────┐
+│                    IO 抽象层（唯一输入路径）                   │
+│  Device(Mic/Speaker/Camera/GPIO/OneBot-QQ/PluginDevice)  │
+│  所有外部输入 → InputEvent → inputCh                       │
+│  输出通道: 能力声明(text/file/image/audio/structured)       │
+│  路由表: 输入源 → 默认输出通道                               │
+└──────────────────────────┬───────────────────────────────┘
                            │
-┌──────────────────────────▼───────────────────────────────────────┐
-│                  中层：Agent 操作层（核心编排器）                    │
-│  Agent Core ── 事件循环 consume inputCh                          │
-│   ├─ 构建上下文（记忆索引 + 技能注入 + ToolDef）                    │
-│   ├─ Provider.Chat() → CompletionResponse                       │
-│   └─ 通过 IO 层输出 text + memory_candidate 事件                   │
-└──────────────────────────┬───────────────────────────────────────┘
+┌──────────────────────────▼───────────────────────────────┐
+│                   Agent 操作层（核心编排器）                  │
+│  eventLoop() consume inputCh                              │
+│   ├─ RelevanceContext（TF-IDF 相关性管理）                   │
+│   ├─ 工具循环（Provider.Chat → tool_calls → Execute → ...) │
+│   ├─ 记忆索引注入（图索引 + 文档摘要）                        │
+│   └─ 心跳蒸馏（30min：向量同步 + 冷归档 + 同义合并）          │
+└──────────────────────────┬───────────────────────────────┘
                            │
-┌──────────────────────────▼───────────────────────────────────────┐
-│                    内层：API 抽象层（唯一输出路径）                    │
-│  Provider ── OpenAI / Ollama / LuaAdaptedProvider                 │
-│  所有 LLM 调用通过 Provider.Chat() / ChatStream()                  │
-└──────────────────────────────────────────────────────────────────┘
+┌──────────────────────────▼───────────────────────────────┐
+│                  API 抽象层（唯一输出路径）                    │
+│  Provider.Chat() → DeepSeek API / OpenAI / Ollama         │
+│  LuaAdapter 做请求/响应格式转换                             │
+└──────────────────────────────────────────────────────────┘
 ```
 
 **三条核心规则：**
-1. 所有外部输入 → 必须通过 `IOManager.InjectInput()` / `InjectText()` 注入
-2. 所有 LLM 调用 → 必须通过 `Provider.Chat()` / `ChatStream()` 发出
-3. Agent Core 不直接操作记忆系统，只发射 `memory_candidate` 事件，由 Memory Pipeline 异步消费
+1. **所有外部输入** → 必须通过 `IOManager.InjectInput()` / `InjectText()` 注入
+2. **所有 LLM 调用** → 必须通过 `Provider.Chat()` 发出
+3. **Agent 不直接操作记忆系统**，只发射 `memory_candidate` 事件，由 Memory Pipeline 异步消费
 
-### 2. 自主记忆系统（源自 TrulyMEM）
+## 二、子系统详解
 
-```
-User Input ──→ Agent Core ──→ Provider ──→ LLM Response
-                      │
-                      ▼
-            IO 层发射 memory_candidate 事件
-                      │
-                      ▼
-            Memory Pipeline Distiller 消费
-                      │
-                      ▼
-            周期蒸馏 → Graph Memory (SQLite)
-                      │
-                      ▼
-            删除原始会话文件
-```
+### 2.1 IO 抽象层（唯一输入路径）
 
-**关键约束：**
-- Agent 上下文中只注入**记忆索引 + 摘要**，**永远不**注入原始文本
-- Agent 必须通过 `memory_recall` tool call **主动查询** 获取完整记忆细节
-- 记忆蒸馏完全异步、自主运行，不阻塞主流程
-
----
-
-## 二、系统层次详解
-
-### 2.1 IO 抽象层（`internal/agent/io/channel.go`）
-
-**唯一输入路径。** 所有外部输入必须通过此层进入系统。
+所有外部输入必须通过此层进入系统。
 
 ```
 Device(Microphone) ─┐
-Device(Camera)     ─┤
-Device(GPIO)       ─┤──→ IOManager.InjectInput() → InputEvent → inputCh → Agent Core
-Device(RobotArm)   ─┤
+Device(OneBot-QQ)  ─┤
+Device(Plugin)     ─┤──→ IOManager → InputEvent → inputCh → Agent
+Device(GPIO)       ─┤
 HTTP API           ─┘
 ```
 
@@ -82,297 +53,175 @@ HTTP API           ─┘
 | 类型 | 说明 |
 |------|------|
 | `InputEvent` | Source + Type + Payload — 所有外部输入的标准化格式 |
-| `OutputEvent` | Target + Type + Payload — 所有输出的标准化格式 |
-| `Device` | 接口：Name() / Type() / Tools() / Execute() |
+| `OutputEvent` | Target + Type + Payload + OutputChannel — 输出路由 |
+| `Device` | 接口：Name/Type/Description/Tools/Execute/Start/Stop/OutputCapabilities |
 | `DeviceType` | Input / Output / IO |
-| `ToolDef` | Name + Description + Parameters — 与 LLM Function Calling 同构 |
+| `ToolDef` | Name + Description + Parameters + Handler — 与 LLM 函数调用同构 |
+| `OutputCapability` | 位掩码：text, file, image, audio, structured |
 
-**内置设备（目前为桩实现，待真正硬件接入）：**
+**内置设备：**
 
-| 设备 | 方向 | ToolDef 暴露 |
-|------|------|-------------|
-| Microphone | Input | `{name}_capture` — 录音 |
-| Speaker | Output | `{name}_speak` — 语音播放 |
-| Camera | Input | `{name}_capture` 拍照 + `{name}_stream` 视频流 |
-| RobotArm | IO | `{name}_move` 移动 + `{name}_grip` 夹爪 |
-| GPIO | IO | `{name}_gpio_write` + `{name}_gpio_read` |
+| 设备 | 方向 | 工具 |
+|------|------|------|
+| Microphone | Input | capture — 录音 |
+| Speaker | Output | speak — 语音播放 |
+| Camera | Input | capture 拍照 |
+| OneBot QQ | IO | send_private/send_group/get_group_member_info/get_group_list |
+| PluginDevice | IO | 插件声明工具 |
+| GPIO | IO | gpio_write/gpio_read |
 
-**Device 与 Tool 同构原则：**
-- 所有 Device 的 `Tools()` 返回 `[]ToolDef`，格式与 LLM Function Calling 完全一致
-- Agent Core 自动收集所有 Device 的 ToolDef 合并到请求的 `tools` 字段
-- Agent 通过 Function Calling 调用设备 capability
+**输出通道能力校验：**
+- 每个 Device 声明 `OutputCapabilities()` → 位掩码
+- `output_send` 工具发送前校验通道是否支持文本
+- `output_list_channels` 只列出有输出能力的通道
 
-### 2.2 API 抽象层（`internal/agent/api/provider.go`）
-
-**唯一输出路径。** 所有 LLM 请求通过此层发出。
+### 2.2 API 抽象层（唯一输出路径）
 
 ```
-Agent Core ──→ ProviderManager ──→ Provider.Chat()
-                   │
-         ┌─────────┼─────────┐
-         ▼         ▼         ▼
-   OpenAI    Ollama    LuaAdaptedProvider
-                                 │
-                         ┌───────┴───────┐
-                         ▼               ▼
-                   Lua Adapter    Base Provider
-                   (transform)    (OpenAI/Ollama)
-```
-
-**Provider 接口：**
-
-```go
-type Provider interface {
-    Name() string
-    Chat(ctx, req) → (*CompletionResponse, error)
-    ChatStream(ctx, req) → (<-chan StreamChunk, error)
-}
+Agent Core → Provider.Chat()
+                │
+        ┌───────┴───────┐
+        ▼               ▼
+  OpenAIProvider    LuaAdapter
+  (DeepSeek API)    (格式转换)
 ```
 
 | 实现 | 说明 |
 |------|------|
-| `OpenAIProvider` | 标准 OpenAI API 格式，支持 /chat/completions |
-| `OllamaProvider` | Ollama /api/chat 格式，本地部署 |
+| `OpenAIProvider` | 标准 OpenAI API 格式，DeepSeek v4 flash 默认 |
 | `LuaAdaptedProvider` | 通过 Lua 脚本转换请求/响应的适配 wrapper |
 
-**Lua 适配器机制：**
-- 适配器文件位于 `{dataDir}/adapters/*.lua`
-- 每个适配器返回 Lua table 包含 `name` + `transform_request` + `transform_response`
-- 首次运行时自动从 embed.FS 复制捆绑适配器（openai / deepseek / ollama / custom）
-- 支持热重载（`POST /api/v1/adapters`）
-- 用于兼容不同 API 供应商的请求/响应格式差异
+Lua 适配器位于 `{dataDir}/adapters/*.lua`，每个适配器返回 `name` + `transform_request` + `transform_response`。
 
-### 2.3 Agent 操作层（`internal/agent/core/agent.go`）
-
-**纯编排器，不涉及张量运算。**
+### 2.3 Agent 操作层（核心编排器）
 
 ```
-eventLoop()
-    │
-    ▼  select on inputCh
-handleInput(evt)
+eventLoop() → select on inputCh
     │
     ▼
-process(input)
-    ├─ indexer.BuildContext(input) → 仅摘要+索引
-    ├─ buildSystemPrompt() → 拼接 system prompt
-    ├─ buildToolDefs() → 收集 IO 工具 + 记忆工具
-    ├─ provider.Chat(req) → LLM 调用
-    ├─ 记忆候选事件 → IO 层 EmitOutput("memory", "memory_candidate", ...)
-    └─ 输出 → IO 层 EmitOutput(source, "text", ...)
+handleInput(evt) → processTextInput(input)
+    │
+    ├─ 1. RelevanceContext.Append(input)
+    ├─ 2. 构建 prompt: personal.md + 图索引 + 文档摘要 + 上下文 + 工具
+    ├─ 3. 工具循环（最多 10 轮）
+    │     LLM → tool_calls → Execute → 结果注入 → 下一轮
+    ├─ 4. 追加响应到上下文
+    ├─ 5. RelevanceContext.Prune() → 低分事件→文档记忆归档
+    ├─ 6. OutputEvent → 输出通道
+    └─ 7. memory_candidate → TextMemory + Distiller → GraphDB
 ```
 
-**关键设计决策：**
-- Agent 不直接持有 `memory.GraphDB` 引用 — 只通过 `Indexer` 构建上下文
-- Agent 不直接调用 `memory.Commit()` — 只发射事件让 Pipeline 异步处理
-- `Indexer.BuildContext()` 只返回内存索引摘要，不返回原始数据
-- `buildSystemPrompt()` 中注入 `memory_recall` / `memory_commit` / `memory_introspect` 工具说明
-- **所有输出走 IO 层** — 文本输出和记忆事件都通过 EmitOutput
+**人格注入：** personal.md 加载一次，固定在 system prompt 最前，永不漂移。
 
-### 2.4 图记忆系统（`internal/memory/graph.go`）
-
-SQLite 三元组存储，支持实体-关系-实体的图遍历。
-
-**数据库 Schema：**
-
-```sql
-entities(id PK, name UNIQUE, type, mention_count, created_at, updated_at)
-relations(id PK, source_id FK→entities, target_id FK→entities,
-          relation_type, confidence, status, session_id, turn_id,
-          created_at, updated_at, date_bucket)
+**工具分发：**
+```
+executeToolCall(tc)
+  ├─ memory_* → executeMemoryTool
+  ├─ knowledge_* → executeKnowledgeTool
+  ├─ doc_* → executeDocTool
+  ├─ output_* → executeOutputChannel/Send/ListChannels
+  └─ 其他 → io.ExecuteTool → Device.Execute
 ```
 
-**核心操作：**
+### 2.4 记忆系统
 
-| 操作 | 说明 |
-|------|------|
-| `Commit(triples, sessionID, turnID)` | 写入三元组 → 自动 upsert 实体 + 插入关系 |
-| `Recall(keywords, seedEntities, depth, session)` | 关键词搜索 → 图遍历 → 返回实体+关系 |
-| `Purge(criteria, mode)` | 软/硬删除匹配的关系 |
-| `Introspect()` | 统计信息：实体数、关系数、热点实体 |
-| `Archive(days)` | 归档超过指定天数的关系 |
-
-**Context Injection 机制（`internal/memory/indexer.go`）：**
-- `BuildContext(userInput)` → 关键词提取 → `GraphDB.Recall()` → 构建摘要
-- `FormatContext(context)` → 输出格式如：
-  `【记忆索引】关联 N 个记忆实体，高频：A、B、C 索引: A, B, C | 需更多细节请用 memory_recall 查询`
-- `BuildToolPrompt()` → 生成 `memory_recall/commit/introspect/purge` 工具的 prompt 说明
-- `GetToolDefinitions()` → 返回 LLM Function Calling 格式的工具定义
-
-### 2.5 记忆管道（`internal/memory/pipeline/pipeline.go`）
-
-自主异步蒸馏管线。
+三层分级，自顶向下逐渐持久化、抽象化：
 
 ```
-Agent Core → EmitOutput("memory", "memory_candidate", {input, response})
+Layer 1: 上下文（RelevanceContext）
+  内存环形缓冲，TF-IDF 余弦相似度排序
+  每次响应后保留 top 30，低分→文档记忆
+
+Layer 2: 文档记忆（document.Store）
+  JSON 文件 + TF-IDF 向量索引（字符 bigram）
+  冷文档（72h 未访问 + ≤2 次）→ 图数据库
+
+Layer 3: 图数据库（memory.GraphDB）
+  SQLite 三元组（实体-关系-实体）
+  只注入索引（实体名+类型+提及次数）到 prompt
+  定期重整：向量同步 + bigram Jaccard 同义合并
+```
+
+### 2.5 知识系统
+
+独立于记忆，agent 主动学习。
+
+```
+knowledge/{category}/content.md
     │
     ▼
-onMemory(input, response) 回调
+TF-IDF 向量索引（字符 bigram）
     │
     ▼
-Append() → records[] 内存缓冲区
-    │
-    ▼ 每 10 分钟触发
-distillLoop()
+工具: knowledge_search / knowledge_create / knowledge_list
+```
+
+### 2.6 插件系统
+
+OpenClaw SKILL.md 兼容。
+
+```
+Plugin（容器）
+  ├─ 元数据: name, version, author
+  ├─ IOConfig（可选）: 声明 IO 端口
+  ├─ Device（可选）: 原生 Go 设备
+  └─ Tools: LLM 工具定义
+
+Registry:
+  ├─ NativeFactory: "qq" → onebot.NewDevice
+  ├─ SetIOManager: 绑定 IO 管理器
+  └─ Reload(): 原子化重载
+```
+
+**热插拔流程：**
+1. 扫描 `plugins/` 目录
+2. 原生工厂优先，无工厂则 LoadSKILL.md
+3. 新设备 Start（预先启动）
+4. `IOManager.AtomicSwapDevices()` 原子替换设备表 + 路由表
+5. 旧设备 Stop（后台 goroutine）
+
+### 2.7 OneBot QQ 通道
+
+```
+OneBot 前端（go-cqhttp/Lagrange）
+    │  Reverse WebSocket
+    ▼
+OneBot Client（internal/onebot/）
+  ├─ 事件: message/notice/request → IO InputEvent
+  ├─ 动作: send_private_msg / send_group_msg / get_group_info / ...
+  ├─ 自动重连（指数退避 1s→30s）
+  └─ 事件 handler 注入 IO 层
     │
     ▼
-extractKeyTriples() → GraphDB.Commit()
-    │
-    ▼
-cleanupRawFiles() 删除超期原始文件
+Device（internal/onebot/device.go）
+  ├─ Tools: qq_send_private_msg, qq_send_group_msg, etc.
+  ├─ Execute → Client.SendAction
+  └─ Start → Connect + 注册事件 handler
 ```
 
-**配置：**
-- `Interval: 10m` — 每 10 分钟蒸馏一次
-- `RetentionDays: 7` — 原始记录保留 7 天
-- `BatchSize: 50` — 每批处理 50 条
+### 2.8 变更追踪器
 
-### 2.6 技能系统（`internal/skill/manager.go`）
-
-兼容 OpenClaw 格式的技能管理。
-
-**技能格式：**
-- `{skillsDir}/{name}/SKILL.md` — Markdown 描述文件
-- `{skillsDir}/{name}/skill.json` — 可选的元数据文件
-
-**注入机制：**
-- `GetInjectedPrompt()` → 收集所有已启用的技能内容注入到 system prompt
-- 支持安装/卸载/启用/禁用
-
-### 2.7 Supervisor 守护进程（`internal/supervisor/daemon.go`）
-
-```go
-type Daemon struct {
-    cfg       *types.Config
-    cm        *container.Manager // Docker 容器管理
-    nm        *network.Monitor   // 网络监控
-    sm        *snapshot.Manager  // 快照管理
-    agents    map[AgentID]*agentInstance
-}
-```
-
-**职责：**
-- Agent 生命周期管理（launch / restart / shutdown）
-- 健康检查循环（心跳间隔 15s）
-- 自动快照循环（快照间隔 10m）
-- 故障恢复：失败 MaxRetries(3) 次后自动回滚到最近快照
-- 网络监控：检查 LLM API 可达性，影响 Agent 健康状态
-
-### 2.8 快照与回滚（`internal/snapshot/manager.go`）
-
-基于 Docker commit/save/load 的版本管理。
-
-**快照流程：**
-`Docker Commit(container → image) → SaveImage(image → .tar) → 记录快照元数据`
-
-**回滚流程：**
-`Stop(container) → Remove(container) → LoadImage(.tar) → 创建新容器 → Start`
-
-**策略：**
-- 定时快照（每 10m）
-- 操作前快照（PreAction — 可选）
-- 限制最大保留（默认 20 个）
-- 溢出时自动删除最旧的
-
-### 2.9 网络监控（`internal/network/monitor.go`）
-
-异步定时检查 LLM API 端点可达性。
-
-**监控方式：**
-- HTTP HEAD 请求到配置的 endpoints
-- 并发检查（goroutine per endpoint）
-- DNS 解析检查（fallback: google.com → baidu.com）
-- 结果聚合：`LLMAPIReachable` + `DNSResolving` + 平均延迟
-
-**影响：**
-- 网络不可达 → Agent 状态变为 `HealthDegraded`
-- 持续不可达 → 触发回滚策略
-
-### 2.10 Lua 虚拟机（`internal/lua/vm.go`）
-
-纯 Go 的 gopher-lua 5.1 VM，用于 API 格式适配器。
-
-**功能：**
-- 加载 `{adapterDir}/*.lua` 适配器脚本
-- `CallTransform(name, input)` — 调用 adapter 的 transform_request
-- `CallResponseTransform(name, raw)` — 调用 adapter 的 transform_response
-- `ReloadAll()` — 热重载所有适配器
-- 内置 mock 函数：`log()`, `json_encode()`, `http_get()`, `http_post()`
-
-### 2.11 Embedder（`internal/embed/embedder.go`）
-
-向量嵌入接口，支持文本相似度计算。
-
-| 实现 | 说明 |
-|------|------|
-| `OllamaEmbedder` | 通过 Ollama API 获取嵌入向量（默认: nomic-embed-text, 768d） |
-| `HashEmbedder` | 基于字符哈希的本地嵌入（无需外部依赖），用于备选方案 |
-
-**可用性：** Embedder 已定义但尚未集成到记忆系统中。
-
-### 2.12 Tokenizer（`internal/tokenizer/jieba.go`）
-
-中文分词工具，基于 gojieba。全局单例，线程安全。
-
-**功能：**
-- `ExtractKeywords(text, topK)` — 提取关键词（TF-IDF 加权）
-- `Cut(text)` — 分词
-- `Tag(text)` — 词性标注
-
----
-
-## 三、数据流全景
-
-### 3.1 正常交互流程
+Overlayfs 文件变更追踪：
 
 ```
-外部输入（HTTP POST / voice / GPIO 事件）
-          │
-          ▼
-IOManager.InjectInput()
-  → InputEvent{Source, Type, Payload}
-  → 推入 inputCh
-          │
-          ▼
-Agent Core eventLoop()
-  1. consume InputEvent
-  2. Indexer.BuildContext(input) → 记忆摘要（仅索引+摘要）
-  3. buildSystemPrompt() → 拼接 system + 记忆 + 技能 + 工具
-  4. buildToolDefs() → IO 工具 + 记忆工具
-  5. Provider.Chat(req) → LLM 响应
-  6. EmitOutput(target, "text", response)
-  7. EmitOutput("memory", "memory_candidate", {input, response})
-          │
-    ┌─────┴─────┐
-    ▼           ▼
-IO 输出      Memory Pipeline（异步）
-    │           │
-    ▼           ▼
-HTTP        Append() → 周期蒸馏
-Response    → GraphDB.Commit()
-Speaker     → 清理原始文件
+PreAction(tool) → 记录文件 hash
+PostAction(tool) → diff → ChangeSet{ID, Tool, Files[]SHA256}
+Rollback() → 用 overlayfs 下层恢复
 ```
 
-### 3.2 记忆查询流程
+健康检查失败 → `tracker.Rollback()`。
+
+### 2.9 Supervisor 守护进程
 
 ```
-Agent 推理中决定调用 memory_recall
-    │
-    ▼
-LLM 返回 tool_call: {name: "memory_recall", args: {query_intent: "..."}}
-    │
-    ▼
-Agent Core 解析 tool_call → 调用 GraphDB.Recall(keywords)
-    │
-    ▼
-返回实体+关系数据 → 注入后续 LLM 请求上下文
+Daemon:
+  ├─ SetTracker() → 绑定变更追踪器
+  ├─ RegisterAgent("main") → 注册主 agent
+  └─ 健康检查周期 → LLM API 可达性
+       └─ 连续失败 → tracker.Rollback()
 ```
 
----
-
-## 四、配置系统
-
-配置文件: `/etc/homeagent/config.yaml`（YAML）。若文件不存在则使用默认配置。
+## 三、配置
 
 ```yaml
 daemon:
@@ -380,116 +229,56 @@ daemon:
   data_dir: "/var/lib/homeagent"
   heartbeat_interval: 15s
   check_interval: 30s
-  log_level: "info"
-
-defaults:
-  image: "homeagent/agent-base:latest"
-  llm_endpoints:
-    - "https://api.openai.com/v1"
-  snapshot_policy:
-    interval: 10m
-    max_snapshots: 20
-    pre_action: true
-    post_action: false
-  rollback_policy:
-    max_retries: 3
-    health_threshold: 3
-    cooldown_period: 30s
-    auto_rollback: true
-  openclaw_enabled: true
-
-agents: []
+llm:
+  provider: "openai"
+  model: "deepseek-v4-flash"
+  base_url: "https://api.deepseek.com/v1"
+  api_key: "${DEEPSEEK_API_KEY}"
+  temperature: 0.7
+  max_tokens: 4096
 ```
 
----
+## 四、数据目录
+
+```
+{dataDir}/
+├── memory/
+│   ├── graph.db           # SQLite 图数据库
+│   ├── text/              # JSONL 文本记忆
+│   ├── documents/         # JSON 文档记忆
+│   └── raw/               # 原始记录（蒸馏后删除）
+├── knowledge/             # 知识库
+│   └── {name}/content.md
+├── plugins/               # 插件
+│   └── {name}/
+│       ├── SKILL.md
+│       └── skill.json
+├── skills/                # 技能
+├── adapters/              # Lua 适配器
+├── personal/              # 人格
+│   └── personal.md
+├── changesets/            # 变更追踪记录
+└── snapshots/             # 快照
+```
 
 ## 五、HTTP API
 
 | 方法 | 路径 | 说明 |
 |------|------|------|
+| POST | `/v1/chat/completions` | OpenAI 兼容对话 |
+| GET | `/api/v1/knowledge` | 知识查询/列表 |
+| POST | `/api/v1/knowledge` | 创建知识 |
+| DELETE | `/api/v1/knowledge?name=` | 删除知识 |
 | GET | `/api/v1/status` | 系统状态 |
-| GET | `/api/v1/agents` | Agent 列表 |
-| POST | `/api/v1/agents` | 创建 Agent |
-| GET | `/api/v1/agents/{id}` | Agent 详情 |
-| POST | `/api/v1/agents/{id}/start/stop/restart` | 操作 |
-| GET | `/api/v1/agents/{id}/snapshots` | 快照列表 |
-| POST | `/api/v1/agents/{id}/rollback/{snap}` | 回滚 |
-| GET | `/api/v1/memory?q=关键词` | 记忆检索 |
-| POST | `/api/v1/memory` | 写入三元组 |
-| DELETE | `/api/v1/memory` | 删除记忆 |
-| GET | `/api/v1/memory/context?q=...` | 获取上下文注入 |
-| GET | `/api/v1/memory/tools` | 记忆工具定义 |
-| GET | `/api/v1/skills` | 技能列表 |
-| POST | `/api/v1/skills` | 安装技能 |
-| DELETE | `/api/v1/skills?name=...` | 卸载技能 |
-| GET | `/api/v1/adapters` | 适配器列表 |
-| POST | `/api/v1/adapters` | 安装适配器 |
-| DELETE | `/api/v1/adapters/{name}` | 删除适配器 |
-| GET | `/api/v1/network` | 网络状态 |
 | GET | `/api/v1/config` | 配置查看 |
-| PUT | `/api/v1/config` | 配置更新 |
-| GET | `/` | WebUI 仪表盘 |
 
----
-
-## 六、数据目录结构
-
-```
-{dataDir}/
-├── config.yaml          # 系统配置
-├── memory/
-│   ├── graph.db         # SQLite 图记忆数据库
-│   └── raw/             # 原始会话记录文件
-│       └── raw_*.jsonl
-├── skills/              # 安装的技能
-│   └── {name}/
-│       ├── SKILL.md
-│       └── skill.json
-├── adapters/            # Lua API 格式适配器
-│   ├── openai.lua
-│   ├── deepseek.lua
-│   ├── ollama.lua
-│   └── custom.lua
-└── snapshots/           # Docker 快照
-    └── {agent_id}/
-        └── snap_*.tar
-```
-
----
-
-## 七、构建与部署
-
-**构建：**
+## 六、构建与部署
 
 ```bash
-make build       # 编译主二进制（~15MB）
-make install     # 编译 + 安装到 /usr/local/bin
+make build       # 编译主二进制
+make run         # 编译 + 启动（数据 /tmp/homeagent）
+make install     # 安装到系统
 make test        # 运行测试
-make fmt         # gofmt
-make lint        # golangci-lint
 ```
 
-**部署：**
-
-- 单二进制：`homed -config /etc/homeagent/config.yaml -data /var/lib/homeagent`
-- systemd：`deploy/homeagent.service`
-- 依赖：Go 1.19+（CGo enabled，用于 go-sqlite3）；Docker 可选（快照/回滚）
-
----
-
-## 八、设计限制与后续计划
-
-### 已知限制
-1. Agent Core 目前是单轮 tool_call 处理，尚未实现完整的多轮 tool 执行循环
-2. Embedder 已定义但未接入图记忆 — 缺失向量相似度排序和 ANN 索引
-3. 记忆蒸馏器使用简单启发式三元组提取，生产环境应调用 LLM 进行结构化抽取
-4. Linux namespace 隔离（overlayfs）尚未实现作为 Docker 替代方案
-5. Speaker / Microphone / Camera 均为桩实现，无实际 ALSA/PulseAudio/Video4Linux 驱动
-6. 无真正的唤醒词检测
-7. LuaAdaptedProvider 失败时无重试/降级逻辑
-8. 无持久化消息历史管理（目前仅内存中保留最近 50 条）
-
-### 路线图
-- **近期**：完成 tool_call 执行循环 → 设备真正驱动 → 向量记忆增强
-- **中期**：单二进制 namespace 隔离 → 唤醒词检测 → CI/CD 流水线
-- **远期**：多 Agent 协作 → 分布式部署 → 联邦记忆
+依赖：Go 1.19+ (CGo enabled for go-sqlite3)。单二进制部署。