docs: 修复记忆分层引用错误 + 补充内置/外部插件说明 + 同步中英文文档

2026-09-22 01:48:11 +00:00 · 2026-07-28 21:56:53 +08:00
parent 51f190e0b6
commit 4218890aed
7 changed files with 74 additions and 46 deletions
--- a/assets/docs/en/ARCHITECTURE.md
+++ b/assets/docs/en/ARCHITECTURE.md
@ -120,17 +120,13 @@ Setting `ctx.Response` at any stage jumps to `after_output`.
       └── LLM active: memory_recall / memory_merge / memory_purge / memory_edit / memory_delete_entity
   Social: person_query / set_trait / relate (wraps GraphDB)

-④ Distillation Pipeline (30min heartbeat)
-   distillContext → window > 2×maxSize → force Prune
-   syncGraphToDocs → Graph snapshot to Document (cross-layer searchable)
-   reorgGraph:
-       Step1: indexer.Sync — rebuild entity vector index
-       Step2: docStore.Reindex — rebuild document vector index
-       Step3: Cold docs → docToTriples → GraphDB.Commit
-       Step4: Entity similarity (Bigram Jaccard > 0.75) → consolidation → LLM decides merge
-       Step5: evaluateGraphQuality → LLM decides keep/delete
+④ Four Independent Heartbeat Loops (separate tickers and config intervals)
+   distillLoop  (distillInterval,  default 30m):  Context pruning — Context.Prune → Document
+   archiveLoop (archiveInterval, default 60m):  Cold doc archival — docToTriples → GraphDB
+   mergeLoop   (mergeInterval,   default 120m): Entity merge detection — similarity → LLM decision
+   reviewLoop  (reviewInterval,  default 120m): Relation review — SentenceRef recall → LLM fix

-⑤ Pipeline Rule Distiller (every heartbeat)
+⑤ Pipeline Rule Distiller (every 10min heartbeat)
   distillOnce → regex match personal info:
     我叫X / 我住在X / 我喜欢X / 我X岁 / 我的工作是X
     → triples → GraphDB.Commit
@ -209,16 +205,15 @@ All vectorization unified under `StaticEmbedder` (`internal/memory/static_embedd
 ### Context Pruning

 ```
-Heartbeat 30min:
-  ├── distillContext()        — Distill current context
-  ├── syncGraphToDocs()       — Graph → Document sync
-  └── reorgGraph()
-      ├── Indexer.Sync()
-      ├── DocStore.Reindex()
-      ├── Cold docs → Graph
-      └── Entity conflicts → enqueueConsolidationTask()
-                                │
-                          selfInputCh → LLM decides merge/skip
+Four independent heartbeat loops (each with configurable interval):
+  ├── distillLoop  (distillInterval,  default 30m)
+  │   └── distillContext() — Context.Prune → Document
+  ├── archiveLoop (archiveInterval, default 60m)
+  │   └── archiveColdDocs() — Cold docs → docToTriples → GraphDB
+  ├── mergeLoop   (mergeInterval,   default 120m)
+  │   └── detectEntityMerge() — Entity similarity detection → LLM decision
+  └── reviewLoop  (reviewInterval,  default 120m)
+      └── reviewRelations() — Relation review → SentenceRef recall → LLM fix
 ```

 Entity conflict detection heuristic (bigram Jaccard > 0.75), routed through `selfInputCh` internal channel, LLM makes the final merge decision.
@ -272,6 +267,25 @@ Built-in plugin registration: `internal/plugins/all.go` blank imports → each p
 External plugin loading: `internal/plugin/dynamic.go` → copy to SHA256 temp path (bypass `plugin.Open` path cache) → `Open` + `Lookup("NewPlugin")`.
 Lua script plugin loading: `internal/lua/` → parse `main.lua` via Lua VM, call `start()` to register tools.

+### Built-in vs External Plugins
+
+| Dimension | Built-in Plugin | External Plugin |
+|-----------|----------------|-----------------|
+| Registration | `init()` calls `plugin.RegisterFactory(name, factory)` | Implements `NewPluginFactory(name, config) (sdk.Plugin, error)` entry function |
+| Compilation | Compiled into `homed` binary, no separate build | Compiled via `plugindev build` to `.so`/`.dll` (`-buildmode=c-shared`), loaded via C ABI bridge |
+| Distribution | Bundled with kernel, not independently installable | `.hmap` package (ZIP archive), installed via WebUI or pluginmgr API |
+| Metadata | `plugin.RegisterPluginMeta()` for display name | `plugin.json` manifest file (name, version, entry, platforms, etc.) |
+| Plugin directory | No separate directory, compiled into binary | `plugins/<name>/` independent directory with `plugin.json` + binary |
+| SDK permissions | Full PluginSDK (SocialAPI read/write, Publish events) | Restricted SDK (SocialAPI read-only, Subscribe-only events) |
+| Lifecycle | Starts/stops with kernel, no individual hot-reload | Independent Start/Stop, supports hot-reload (ReloadOne) and enable/disable |
+| Crash recovery | No independent recovery | Supports `SetAutoRestart(true)` for automatic crash restart |
+
+Common ground:
+- Built-in `RegisterFactory` and external `NewPluginFactory` share the same `NativeFactory` type signature
+- `Registry.Load()` handles both uniformly: checks factory table first (built-in), falls back to dynamic loading (external)
+- Both use the same `Plugin` interface and `PluginSDK`; tool registration, stage hooks, and output channel APIs are identical
+- Both share the same tool registry (`StageHost`); LLM invocations treat them identically
+
 ### PluginSDK Four Channels

 ```
--- a/assets/docs/en/OVERVIEW.md
+++ b/assets/docs/en/OVERVIEW.md
@ -19,7 +19,7 @@ Core architecture: a long-running kernel process (`homed`) that connects to vari
 The significance lies in clear responsibility boundaries: the kernel focuses on orchestration and memory management, while plugins handle IO implementation — the two are not coupled.

 **Three-Layer Memory Architecture** — Manages information retention across long agent runtimes through a tiered storage strategy:
- **Context Layer**: In-memory local word embedding scored event window (jieba + TF-IDF + PMI → CosineSimilarity), maintains recent context in real-time, low-relevance events automatically sink to the next layer
+- **Context Layer**: In-memory pretrained word embedding scored event window (StaticEmbedder word vectors → CosineSimilarity, TF-IDF fallback), maintains recent context in real-time, low-relevance events automatically sink to the next layer
 - **Document Layer**: JSON files + TF-IDF vector-indexed temporary memory, supports explicit submission and implicit archival, cold data distills to Graph
 - **Graph Layer**: SQLite graph database, persists entities and relations, BFS traversal recall, distillation pipeline extracts triples from conversations

--- a/assets/docs/zh/ARCHITECTURE.md
+++ b/assets/docs/zh/ARCHITECTURE.md
@ -120,17 +120,13 @@ eventLoop() → processTextInput()
       └── LLM主动: memory_recall / memory_merge / memory_purge / memory_edit / memory_delete_entity
   Social: person_query / set_trait / relate (包装 GraphDB)

-④ 蒸馏管道 (每30min心跳)
-   distillContext → 窗口>2×maxSize → 强制Prune
-   syncGraphToDocs → Graph 快照写入 Document(跨层可搜索)
-   reorgGraph:
-       Step1: indexer.Sync — 重建实体向量索引
-       Step2: docStore.Reindex — 重建文档向量索引
-       Step3: 冷文档 → docToTriples → GraphDB.Commit
-       Step4: 实体相似度(Bigram Jaccard>0.75) → consolidation → LLM判断合并
-       Step5: evaluateGraphQuality → LLM判断保留/删除
+④ 四个独立心跳循环（各自独立的 ticker 和配置间隔）
+   distillLoop  (distillInterval,  默认30m): 上下文裁剪 — Context.Prune → Document
+   archiveLoop (archiveInterval, 默认60m): 冷文档归档 — docToTriples → GraphDB
+   mergeLoop   (mergeInterval,   默认120m): 实体合并检测 — 相似度 → LLM 裁决
+   reviewLoop  (reviewInterval,  默认120m): 关系复审 — SentenceRef 回溯 → LLM 修正

-⑤ Pipeline 规则蒸馏器 (每心跳)
+⑤ Pipeline 规则蒸馏器 (每10min心跳)
   distillOnce → 正则匹配个人信息:
     我叫X / 我住在X / 我喜欢X / 我X岁 / 我的工作是X
     → 三元组 → GraphDB.Commit
@ -209,16 +205,15 @@ eventLoop() → processTextInput()
 ### 上下文剪枝

 ```
-心跳 30min:
-  ├── distillContext()        — 蒸馏当前上下文
-  ├── syncGraphToDocs()       — Graph→Document 同步
-  └── reorgGraph()
-      ├── Indexer.Sync()
-      ├── DocStore.Reindex()
-      ├── 冷文档→Graph
-      └── 实体冲突 → enqueueConsolidationTask()
-                          │
-                    selfInputCh → LLM 判断合并/跳过
+四个独立心跳循环（各自可配置间隔）:
+  ├── distillLoop  (distillInterval,  默认30m)
+  │   └── distillContext() — Context.Prune → Document
+  ├── archiveLoop (archiveInterval, 默认60m)
+  │   └── archiveColdDocs() — 冷文档 → docToTriples → GraphDB
+  ├── mergeLoop   (mergeInterval,   默认120m)
+  │   └── detectEntityMerge() — 实体相似度检测 → LLM 裁决
+  └── reviewLoop  (reviewInterval,  默认120m)
+      └── reviewRelations() — 关系复审 → SentenceRef 回溯 → LLM 修正
 ```

 实体冲突检测启发式（bigram Jaccard > 0.75），走 `selfInputCh` 内部通道，LLM 最终判断是否合并。
@ -270,6 +265,25 @@ VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。
 外部插件加载：`internal/plugin/dynamic.go` → 复制到 SHA256 临时路径（绕过 `plugin.Open` 路径缓存）→ `Open` + `Lookup("NewPlugin")`。
 Lua 脚本插件加载：`internal/lua/` → 通过 Lua VM 解析 `main.lua`，调用 `start()` 注册工具。

+### 内置插件 vs 外部插件
+
+| 维度 | 内置插件 | 外部插件 |
+|------|----------|----------|
+| 注册方式 | `init()` 调用 `plugin.RegisterFactory(name, factory)` | 实现 `NewPluginFactory(name, config) (sdk.Plugin, error)` 入口函数 |
+| 编译方式 | 编译进 `homed` 二进制，无需独立编译 | 通过 `plugindev build` 编译为 `.so`/`.dll`（`-buildmode=c-shared`），C ABI bridge 加载 |
+| 分发方式 | 随内核分发，不可独立安装/卸载 | `.hmap` 包（ZIP 归档），通过 WebUI 或 pluginmgr API 安装 |
+| 元数据 | 通过 `plugin.RegisterPluginMeta()` 注册显示名 | `plugin.json` manifest 文件（name, version, entry, platforms 等） |
+| 插件目录 | 无独立目录，编译进二进制 | `plugins/<name>/` 独立目录，包含 `plugin.json` + 二进制 |
+| SDK 权限 | 完整 PluginSDK（SocialAPI 读写、Publish 事件） | 受限 SDK（SocialAPI 只读、仅 Subscribe 事件） |
+| 生命周期 | 随内核启动/停止，不可单独热重载 | 独立 Start/Stop，支持热重载（ReloadOne）和禁用/启用 |
+| 崩溃恢复 | 无独立恢复机制 | 支持 `SetAutoRestart(true)` 崩溃自动重启 |
+
+两者的联系：
+- 内置插件的工厂函数 `RegisterFactory` 与外部插件的 `NewPluginFactory` 共用同一个 `NativeFactory` 类型签名
+- `Registry.Load()` 统一处理两者的加载：先查工厂表（内置），无工厂则尝试动态加载（外部）
+- 两者使用相同的 `Plugin` 接口和 `PluginSDK`，工具注册、阶段钩子、输出通道等 API 完全一致
+- 两者共享同一个工具注册表（`StageHost`），LLM 调用时无差别
+
 ### PluginSDK 四通道

 ```
--- a/assets/docs/zh/OVERVIEW.md
+++ b/assets/docs/zh/OVERVIEW.md
@ -19,7 +19,7 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
 这一划分的意义在于职责边界清晰：内核专注于编排与记忆管理，插件负责具体 IO 实现，二者互不耦合。

 **三层记忆架构** — 通过分级存储策略管理 Agent 长周期运行中的信息留存：
- **Context 层**：内存中局部词嵌入评分的事件窗口（jieba + TF-IDF + PMI → CosineSimilarity），实时维护最近上下文，低相关性事件自动下沉到下一层
+- **Context 层**：内存中预训练词嵌入评分的事件窗口（StaticEmbedder 词向量 → CosineSimilarity，TF-IDF 回退），实时维护最近上下文，低相关性事件自动下沉到下一层
 - **Document 层**：JSON 文件 + TF-IDF 向量索引的临时记忆，支持显式提交和隐式归档，冷数据蒸馏到 Graph
 - **Graph 层**：SQLite 图数据库，持久化实体（entities）和关系（relations），BFS 遍历召回，蒸馏管道从对话中提取三元组