mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 09:17:31 +00:00
docs: 术语与架构措辞对齐(coldcontext / stablemem / security+device 模块)
1. 术语统一:
- doc_query / doc_commit → coldcontext_query / coldcontext_commit
- 「图记忆 / Graph 层」→「稳定记忆 / Stablemem 层(L3)」
- 分层命名补上 L1/L2/L3 语义:Context(热) / Cold-context(冷) / Stablemem(持久)
涉及 README.md、README_EN.md、assets/docs/{zh,en}/{ARCHITECTURE,OVERVIEW}.md
2. 补上本次最大的结构变化(文档里此前完全没有):
- 安全防火墙作为**独立内核模块**:凭据闸门、工具黑白名单+沙箱、
敏感词与提示词注入预警、按主体授权与插件命名限式;显式代理而非 monkey patch
- device 数据面作为**独立内核模块**:工具注册与路由、inputch/outputch、设备登记;
路由表在 internal/toolroute 以避免 core ↔ kernelboot 成环
3. 历史计划文档(memory-*.md / context-overflow-l4-design / entities-retirement /
git-branching)加**归档说明**:明确术语已过时、现行口径以 ARCHITECTURE.md 为准。
刻意不改写历史正文 —— 那是决策记录,改写等于伪造。
剩余旧词只出现在归档文档与 scripts/capability-bench/PLAN.md(评测历史记录)。
This commit is contained in:
@ -109,7 +109,7 @@ eventLoop() → processTextInput()
|
||||
|---|---|---|---|---|
|
||||
| **L1 Context** | 事件(内联正文 + 块) | **直接投喂**(进 system prompt 时序) | 最近 n 条 / 上限 m 条 | 超限时按相似度迁出 |
|
||||
| **L2 Document** | 事件(内联正文 + 块) | **不直接投喂**(需召回才进 L1) | 无上限 | 冷到阈值后蒸馏进 L3 |
|
||||
| **L3 Graph** | 三元组(节点 + 关系边),节点即记忆块 | 不投喂(经召回进入 L1) | 持久 | 不流出 |
|
||||
| **L3 Stable** | 三元组(节点 + 关系边),节点即记忆块 | 不投喂(经召回进入 L1) | 持久 | 不流出 |
|
||||
|
||||
★ **L1 与 L2 结构完全同构**,唯一区别是「是否被直接投喂给模型」。
|
||||
L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样的事件 + 同样的块,只是不直接进模型视野。
|
||||
@ -138,10 +138,10 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样
|
||||
|
||||
② Document (文件记忆 — 不直接投喂,结构与 L1 同构)
|
||||
DocStore — 每篇文档 = 检索元数据 + 事件列表(内联正文 + 块)
|
||||
写入: Prune归档 / doc_commit / Graph快照(syncGraphToDocs)
|
||||
写入: Prune归档 / coldcontext_commit / stablemem 快照(syncGraphToDocs)
|
||||
读取:
|
||||
├── 自动预填充: Query(input, top3) → 同一向量空间下相似度摘要 → 【相关记忆文档】→ system prompt (只读,不动层)
|
||||
└── LLM主动: doc_query → Consume(取走)
|
||||
└── LLM主动: coldcontext_query → Consume(取走)
|
||||
→ 逐条按各自原始时间戳把事件插回 L1 时序
|
||||
→ 块随事件迁回(同一块 ID,向量不重算),L2 不再持有
|
||||
冷化: FindColdDocs(72h, ≤2次访问) → docToTriples → Graph
|
||||
@ -226,9 +226,38 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样
|
||||
- 正文内联在块里:文本块的 `Text` 是正文,媒体块的 `Data` 是字节
|
||||
- `Doc.Content` 只是**渲染视图**(供摘要/人工阅读/SDK 兼容),不是原文载体
|
||||
- 自动预填充:与 Context 共享的向量空间做相似度检索 → 摘要进 system prompt(**只读**,不动层)
|
||||
- 主动召回:`doc_query` 取走后,**逐条按各自原始时间戳**把事件插回 L1 时序,块随事件迁回
|
||||
- 主动召回:`coldcontext_query` 取走后,**逐条按各自原始时间戳**把事件插回 L1 时序,块随事件迁回
|
||||
- 冷化:`FindColdDocs(72h, ≤2次访问)` → `docToTriples` → Graph
|
||||
|
||||
## 安全防火墙与设备数据面(内核模块)
|
||||
|
||||
###security 内核模块(`internal/kernelmod/security`)
|
||||
|
||||
安全不是"某项能力",而是**横在 Core 与全部外部模块之间的一堵墙**:
|
||||
|
||||
```text
|
||||
Core ──出向审查──▶ 外部(device / plugin / channel)
|
||||
Core ◀─入向审查── 外部
|
||||
```
|
||||
|
||||
- **凭据闸门**:出向把明文换成 `@{别名}`、入向清洗返回值、执行前才回填真实值
|
||||
- **工具黑白名单 + 沙箱**:路径读写根、网络开关、`..` 逃逸拦截(`deny` 永远优先)
|
||||
- **内容审查**:敏感词过滤 + 提示词注入预警(Finding **不带原文**,避免日志泄漏)
|
||||
- **按主体授权**:hard-private 工具对任何非内部主体永久拒绝
|
||||
- **插件命名限式**:插件声明 `qq.owner` / `qq.guest` 等档位,inputch 触发时用
|
||||
`InjectOptions.SecurityProfile` 选择;**未声明的档位名会报错**,不静默回落
|
||||
|
||||
落地形态是**显式代理**(不是 monkey patch):装配时把 `KernelState` 的公共挂载点
|
||||
换成安全对象,业务模块仍认为自己直接与对端交互。
|
||||
|
||||
### device 内核模块(`internal/kernelmod/device`)
|
||||
|
||||
统一拥有:工具注册与路由、inputch、outputch、设备登记。内置工具的路由表在
|
||||
`internal/toolroute`(避免 core ↔ kernelboot 成环),device 保留对外入口;
|
||||
未挂载 device 时 agent 退化为本地 switch。
|
||||
|
||||
---
|
||||
|
||||
### Graph 层
|
||||
|
||||
`internal/memory/graph.go` — `GraphDB`
|
||||
@ -252,10 +281,10 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样
|
||||
| `memory_edit` | 编辑已有实体/关系 |
|
||||
| `memory_delete_entity` | 删除实体及其所有关系 |
|
||||
| `memory_introspect` | 查看记忆统计 |
|
||||
| `doc_query` | 从 Document 搜索 |
|
||||
| `doc_commit` | 写入 Document |
|
||||
| `coldcontext_query` | 从冷上下文(cold context)召回 |
|
||||
| `coldcontext_commit` | 写入冷上下文 |
|
||||
|
||||
`memory_commit` 与 `doc_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把
|
||||
`memory_commit` 与 `coldcontext_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把
|
||||
`[<mime> <短digest>] <描述>` 标记补进句子/正文——**标记由内核拼,模型只给 digest**。
|
||||
要求调用方知道格式,等于让一个拼写错误静默切断引用绑定而全链路无人报错。
|
||||
`memory_commit` 同时新增 `sentence_text`:媒体引用挂在句子上,没有句子就无处可挂。
|
||||
@ -626,7 +655,7 @@ type Plugin interface {
|
||||
|
||||
设计见 [`docs/zh/resident-subagent-design.md`](../../../docs/zh/resident-subagent-design.md)。
|
||||
|
||||
- **驻留子**是轻量内核的独立 agent:自己的调度器、自己的 temp 图记忆、共享的通道登记表。
|
||||
- **驻留子**是轻量内核的独立 agent:自己的调度器、自己的 temp 稳定记忆、共享的通道登记表。
|
||||
- 父对子的控制面:`resident_agents`(list / create / send / inspect / compress / reclaim / destroy)。
|
||||
- **积压及时反馈**:主 agent 长时间忙时(默认 > 5m,可配),内核把排队输入交给
|
||||
一个临时**分诊助手**(`offload_*` 配置):简单的直接处理并回复,需要主 agent 的
|
||||
|
||||
@ -26,8 +26,8 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev
|
||||
|
||||
**三层记忆架构** — 三层不是三种数据结构,而是**同一批记忆块的三层持有关系**:
|
||||
- **Context 层(L1,直接投喂)**:内存中预训练词嵌入评分的事件窗口(StaticEmbedder 词向量 → CosineSimilarity,TF-IDF 回退),实时维护最近上下文,低相关性事件自动下沉到下一层
|
||||
- **Document 层(L2,不直接投喂)**:与 L1 **结构同构**——同样的事件 + 同样的块,只是不直接进模型视野;支持显式提交和隐式归档,冷数据蒸馏到 Graph
|
||||
- **Graph 层(L3,持久)**:SQLite 图数据库,**顶层仍是三元组**(节点 + 关系边),但节点从 `entities` 表升级为 `memory_blocks`;BFS 遍历召回,蒸馏管道从对话中提取三元组
|
||||
- **Document 层(L2,不直接投喂)**:与 L1 **结构同构**——同样的事件 + 同样的块,只是不直接进模型视野;支持显式提交和隐式归档,冷数据蒸馏到稳定记忆(stablemem)
|
||||
- **Stablemem 层(L3,持久)**:SQLite 图数据库,**顶层仍是三元组**(节点 + 关系边),但节点从 `entities` 表升级为 `memory_blocks`;BFS 遍历召回,蒸馏管道从对话中提取三元组
|
||||
|
||||
★ **L1 与 L2 唯一区别是「是否被直接投喂给模型」**:L2 不是 L1 的摘要层,也不是
|
||||
另一种数据形态。召回 = 把事件(连同它持有的块)从“不投喂”的持有层**迁回**“投喂”的持有层。
|
||||
@ -36,7 +36,7 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev
|
||||
不存在「块 + 外部正文」的分离形态。**任何一层都不压缩** —— 视图(检索摘要、渲染结果)
|
||||
可以是压缩的,但视图不是记忆。
|
||||
|
||||
三层流动:上下文 → 冷归档 → 长期图记忆,构成从短期到持久的信息衰减与整合管道;
|
||||
三层流动:上下文 → 冷归档 → 长期稳定记忆,构成从短期到持久的信息衰减与整合管道;
|
||||
每一次都是**迁移**(块 ID 与向量不变,只换持有层),不是复制。
|
||||
|
||||
**媒体记忆(v1.2.0 起:一等记忆块)** — 图片/音频不是附属物,而是记忆的一等节点:
|
||||
@ -46,7 +46,7 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev
|
||||
- **无独立 GC、无引用计数、无 keep-set**:记忆块遵循单层不变量——Context → Document → Graph
|
||||
是块的**迁移**,不是复制、也不靠引用保活;**删除块即删内容**
|
||||
- **v1.1.1 起贯通插件边界**:插件可通过 `InsertWithMedia` / `InjectInputMedia` 读写媒体,
|
||||
模型可用 `memory_commit` / `doc_commit` 的 `media_digests` 参数关联媒体
|
||||
模型可用 `memory_commit` / `coldcontext_commit` 的 `media_digests` 参数关联媒体
|
||||
- **旧机制已整体拆除**:此前把视觉模型生成的描述写进正文、以 `[<mime> <短digest>] <描述>` 标记
|
||||
参与检索的**描述式索引**,以及 `media_refs` 引用计数,均已在 v1.2.0 删除——描述是模型生成的
|
||||
二手信息,检索「别人转述的图片」不如检索图片自己的向量
|
||||
|
||||
Reference in New Issue
Block a user