mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-01 06:47:29 +00:00
feat(memory): L2 与 L1 同构 —— 事件列表承载原文，正文内联在块里
块化重构（memory-restructure-plan）换了底层数据结构，但 L1↔L2 的流动没跟着改，
导致这条链出现结构性失效。本次按设计原文修复。
## 断点（生产实测）
**① L2 只存渲染视图，事件本体丢失**
ContextToDoc 把每条事件拍平成一行：truncate(Response,100)、truncate(工具输出,200)。
生产库 1000 篇归档文档实测：
- response 段恰好 103 字符（=100+"..."）：311/2094 = 15.1%
- 工具输出段恰好 203 字符：7593/13261
- ToolsUsed 完全不存
⇒ 原文在落库那一刻就不存在了，召回再全也拿不回来。
**② L2 里没有文本块，与 L1 不同构**
L2 块分布 image 437 / audio 7 / text 0 —— 文本全靠 Content 这个视图。
**③ 召回造合成事件，时间戳用归档时刻**
doc_query 用 d.CreatedAt 造一条 cold_storage 事件、正文取 Content 再截 2000 字、
且完全不回填 Blocks。块自带 created_at（捕获时刻），实测与 doc.created_at
差近两小时，却没人用。
**④ 块在 Consume 时两层同时消失**
Consume 从内存与磁盘同时删除文档，而块的字节只存在于那个 .json 里。
生产 L2 有 444 个块，其中 396 个不在 L3（约 248MB）—— 一旦被命中即永久丢失。
## 修法（按设计，不是按我的推断）
设计前提（写进 ARCHITECTURE 与计划文档）：
· 记忆块是唯一物理载体，层是持有关系
· L1 与 L2 结构同构，唯一区别是「是否直接投喂给模型」
· 正文（含多媒体正文）内联在块里；事件只是块的容器
· 任何一层都不压缩（视图不是记忆）
· 内核不得硬编码任何插件行为
1. Doc 增加 Events []DocEvent（与 ContextEvent 同构），成为文档主体
2. 正文各自成块：Input 一块、Response 一块（BlockText，Text 即正文）
3. restoreDocEvents 逐条按原始时间戳迁回 L1，块随事件迁回
4. Content 保留为渲染视图（contentFromEvents 生成），不再是原文载体
5. 蒸馏 docToTriples 改用 documentOriginalText：从块读原文，不再用视图
6. 删掉 ARCHITECTURE 里「过滤 agentcli/terminal 来源」——那是内核硬编码
插件名，改由插件经 NoMemory/Cleaner 声明
## 顺带修掉的真实缺陷
simpleHash 是 O(n²) 且哈希串长度正比于内容：
for _, c := range s { h += fmt.Sprintf("%x", c) }
压力测试实测 1.25MB 正文归档耗时 **270 秒**；生产实测 content_hash
是 content 的 2.2 倍（52072 字 → 114491 字）。
换成 sha256 前 16 字节：**270s → 0.52s（520 倍）**，定长 32 hex。
## 存量
按拍板不迁移，等系统自然冲刷。降级路径：无 Events 的旧文档仍按旧行为召回
（整篇渲成一条事件），不伪造成「有原始事件」。生产副本实测 1104 篇旧文档
全部正常加载。
## 判据（16 条，全部有变异自证）
document/blockflow_test.go（11 条）：正文完整性、文本块粒度、逐条保留、
视图定位、幂等、存量兼容、原文可用性、hash 线性、3 条压力
core/recalldoc_test.go（5 条）：逐条回填、原始时间戳、块迁回、
回填不截断、存量降级、批量压力
变异全部被抓：
· 落库 truncate(100) → ArchivePreservesFullText（实测 len=303/原 10215）
· Input/Response 合成一块 → InputAndResponseAreSeparateTextBlocks（实际 1）
· 召回用 d.CreatedAt → RestoresEachEventAtOriginalTimestamp（回填 1/期望 3）
· 召回不回填 Blocks → MigratesBlocksBackToContext
· 召回再截 2000 字 → TextIsNotTruncatedOnTheWayBack（2003/原 18020）
· 恢复 O(n²) hash → HashIsLinearAndFixedLength（超时 >300s）
## 验证
- go build ./... 通过
- go test ./... -count=1：58 包 0 失败
- go test -race ./internal/memory/document/ ./internal/agent/core/：通过
- 生产数据副本实际启动：1104 篇文档加载正常、0 崩溃、干净退出
- 副本 e2e：新归档 2 事件 / 4 文本块、正文 3207 字完整回读、时间戳精确
## 不改
- 公开 SDK 契约（TextEvent / DocMemoryAPI / InsertWithMedia 已等价）
- 存量文档（等自然冲刷）
- 渲染层截断常数（独立议题，避免与本次修复互相掩盖）
This commit is contained in:
JianFeeeee
444
docs/zh/memory-blockflow-repair-plan.md
Normal file
444
docs/zh/memory-blockflow-repair-plan.md
Normal file
@ -0,0 +1,444 @@
|
||||
# 三层记忆系统修复计划：块化重构后的失效面
|
||||
|
||||
> 状态：**已实施**（2026-10-22）。实施记录见文末 §九。
|
||||
> 原计划写作于同日，下述前提与失效面均经源码与生产数据核实。
|
||||
> 触发：块化统一（`docs/zh/memory-restructure-plan.md`）重构了底层数据结构，
|
||||
> 但上层「层的流动」没有跟着改，导致 L1↔L2 这条链出现结构性失效。
|
||||
>
|
||||
> 本文只写**经源码与生产数据核实**的失效点。每条都标了证据位置，
|
||||
> 不含推测、不含性能断言。
|
||||
|
||||
---
|
||||
|
||||
## 〇、设计前提（不可动摇，任何修法违反即错）
|
||||
|
||||
### 前提 A：记忆块是唯一的物理载体
|
||||
|
||||
`docs/zh/memory-restructure-plan.md` §〇 纠错表原话：
|
||||
|
||||
> | 分层是 L0 对话/L1 文档/L2 graph/L3 blocks | L0=context / L1=doc / L2=graph。
|
||||
> **blocks 不是新的一层**，是图节点从文本升级为带向量的多模态节点 |
|
||||
|
||||
`MemoryBlock` 是 union：文本块负载在 `Text`，媒体块在 `Data`（配 MIME/宽高/尺寸）。
|
||||
**同一个块 ID 在 context → doc → graph 全程不变。层是持有关系，不是数据种类的划分。**
|
||||
|
||||
### 前提 B：L1 与 L2 结构同构，唯一区别是「是否直接投喂给模型」
|
||||
|
||||
这是**层与层的定义**，不是实现细节：
|
||||
|
||||
| | L1 Context | L2 Document |
|
||||
|---|---|---|
|
||||
| 承载单元 | 事件（内联正文 + 块） | 事件（内联正文 + 块） |
|
||||
| 结构 | 同构 | 同构 |
|
||||
| 与模型的关系 | **直接投喂**（进 system prompt 时序） | **不直接投喂**（需经召回才进入 L1） |
|
||||
| 容量 | 最近 n 条 / 上限 m 条 | 无上限 |
|
||||
| 流动性 | 超限时按相似度迁出 | 冷到阈值后蒸馏进 L3 |
|
||||
|
||||
⇒ L2 **不是**「L1 的摘要层」，也**不是**「另一种数据形态」。
|
||||
它就是**同样的事件 + 同样的块**，只是不直接进模型视野。
|
||||
召回 = 把块（连同它所属事件）从"不投喂"的持有层**迁回**"投喂"的持有层。
|
||||
|
||||
### 前提 C：正文（含多媒体正文）内联在块里
|
||||
|
||||
文本块的 `Text` 就是正文；媒体块的 `Data` 就是字节。
|
||||
**不存在"块 + 外部正文"的分离形态**，也不存在靠渲染字符串承载原文的路径。
|
||||
事件是块的容器，不是块的替代品。
|
||||
|
||||
### 前提 D：任何一层都不压缩
|
||||
|
||||
原文必须完整保留。视图（检索摘要、给模型看的渲染）可以是压缩的，
|
||||
但**视图不是记忆**。把视图当记忆存，等于在存储端就丢了原文。
|
||||
|
||||
### 前提 E：Graph 顶层仍是三元组，块只是它的节点实现
|
||||
|
||||
`internal/memory/sentence_block.go` — `putTripleBlocksTx`：
|
||||
|
||||
```go
|
||||
src := MemoryBlock{ID: TripleBlockID(t.Subject), Text: t.Subject, SemanticType: t.SubjectType}
|
||||
dst := MemoryBlock{ID: TripleBlockID(t.Object), Text: t.Object, SemanticType: t.ObjectType}
|
||||
// 边：src --edge_type=Relation--> dst，落在 memory_block_edges
|
||||
```
|
||||
|
||||
三元组 =【节点】【关系边】【节点】，这个**顶层结构没有变**。
|
||||
变的是节点的物理表示：`entities` 表 → `memory_blocks` 表。
|
||||
`entities` 退场不等于三元组退场。
|
||||
|
||||
### 前提 F：内核不得硬编码任何插件行为
|
||||
|
||||
这是**铁律**。任何依赖具体插件名（`agentcli` / `terminal` / `qq` …）的内核分支都是错的。
|
||||
插件的行为差异一律由插件自己**声明**：`ToolDef.NoMemory`、`ToolDef.Cleaner`、
|
||||
`ChannelDef.NoMemory`、`ChannelDef.Cleaner`、`InjectOptions`。
|
||||
|
||||
### 前提 G：SDK 已通过一套等价接口实现同等能力
|
||||
|
||||
公开 SDK（`third_party/homeagent-sdk/sdk/memory.go`）已提供与内核同构的表达：
|
||||
|
||||
| SDK 接口 | 对应的内核概念 |
|
||||
|---|---|
|
||||
| `TextEvent{Role, Content, Timestamp, Channel, Attachments}` | 事件（正文内联 + 附件） |
|
||||
| `DocMemoryAPI.Insert(doc)` | 写入 L2（纯文本） |
|
||||
| `DocMemoryAPI.InsertWithMedia(doc, attachments)` | 写入 L2（正文 + 媒体块） |
|
||||
| `DocMemoryAPI.Query(text, topK)` | 只读召回（不删除） |
|
||||
| `MediaAttachment{Digest, MIME, Data}` | 块引用：带 `Data` 为新内容，只带 `Digest` 为引用已有 |
|
||||
| `TextMemoryAPI.Append(TextEvent)` | 时间序文本日志 |
|
||||
|
||||
⇒ **SDK 契约不需要改动**。修的是内核实现没跟上契约语义，不是契约本身。
|
||||
|
||||
---
|
||||
|
||||
## 一、失效面清单（经核实）
|
||||
|
||||
### 失效 1：L2 只存了事件的渲染视图，事件本体被丢弃
|
||||
|
||||
**位置**：`internal/memory/document/document.go` — `ContextToDoc`
|
||||
|
||||
`Prune` 交给 L2 的是结构完整的 `[]ContextEntry`（Timestamp/Source/Content/
|
||||
Response/ToolsUsed/ToolResults/Blocks），但落库时被拍平成一个字符串：
|
||||
|
||||
```go
|
||||
for _, e := range entries {
|
||||
line := fmt.Sprintf("[%s] %s: %s", e.Timestamp.Format("15:04"), e.Source, e.Content)
|
||||
line += fmt.Sprintf(" → %s", truncate(e.Response, 100)) // 正文 → 视图
|
||||
line += fmt.Sprintf("\n [工具] %s: %s", tr.Name, truncate(tr.Output, 200))
|
||||
}
|
||||
content := strings.Join(parts, "\n")
|
||||
```
|
||||
|
||||
只有 `Doc.Content` 被保存。**后果**：事件的时间戳只剩 `HH:MM`，
|
||||
`Response` 只剩 100 rune，工具输出只剩 200 rune，`ToolsUsed` 完全不存。
|
||||
|
||||
这直接违反前提 B（L1/L2 同构）与前提 C（正文内联在块里）——
|
||||
L1 里是完整事件，L2 里却退化成一段文本。
|
||||
|
||||
**生产证据**（`/home/newqqagent/memory/documents/`，1000 篇归档文档）：
|
||||
|
||||
| 度量 | 实测值 |
|
||||
|---|---|
|
||||
| response 段恰好 103 字符（=100+`...`） | 311 / 2094 段 = **15.1%** |
|
||||
| 工具输出段恰好 203 字符（=200+`...`） | **7593 / 13261 段** |
|
||||
|
||||
⇒ 原文**在落库那一刻就不存在了**。这不是"召回时没取全"，是存储端丢失。
|
||||
|
||||
### 失效 2：L2 里没有文本块，L1/L2 不同构
|
||||
|
||||
**位置**：`internal/memory/document/document.go` — `blocksFromEntries`
|
||||
|
||||
块的 `modality` 实测分布（同一批生产文档）：
|
||||
|
||||
```
|
||||
L2 块总数 444：image 437 / audio 7 / text 0
|
||||
```
|
||||
|
||||
**后果**：L2 里"块"只承载媒体，文本内容全靠 `Doc.Content` 这个视图。
|
||||
违反前提 B/C——L1 的事件正文 + 块，到 L2 变成了"字符串 + 仅媒体块"。
|
||||
（对照：L3 的文本是有块的，`putTripleBlocksTx` 的主语块/宾语块都是 `BlockText`。）
|
||||
|
||||
### 失效 3：召回时新建合成事件，而非把块按原时序迁回
|
||||
|
||||
**位置**：`internal/agent/core/toolcall.go` — `executeDocTool` 的 `doc_query` 分支
|
||||
|
||||
```go
|
||||
docs := a.docStore.Consume(query, topK) // 读 + 从 L2 删除
|
||||
...
|
||||
a.context.InsertByTimestamp(ContextEvent{
|
||||
Timestamp: d.CreatedAt, // ← 归档时刻，非事件时刻
|
||||
Source: "cold_storage", // ← 新造来源
|
||||
Input: fmt.Sprintf("加载文档记忆: %s", query),
|
||||
Response: content, // ← 渲染视图，且再截 2000
|
||||
})
|
||||
// ← 完全没有把 d.Blocks 挂回去
|
||||
```
|
||||
|
||||
三处偏离设计（`ARCHITECTURE.md` L107-108、L178）：
|
||||
|
||||
> doc_query → Consume(读取并删除)
|
||||
> → **逐条** context.Append{Timestamp: **原始时间戳**, Source: 原来源}
|
||||
> → 文档以原始时间戳写入 context 时间线, 从 docStore 删除
|
||||
|
||||
**生产证据**（块自带 `created_at`，与归档时刻差近两小时）：
|
||||
|
||||
```
|
||||
媒体块 created_at = 2026-10-12 11:09:51 ← 事件发生时刻（captureBlockMedia 里 time.Now()）
|
||||
doc.created_at = 2026-10-12 13:04:54 ← 归档时刻
|
||||
```
|
||||
|
||||
443/443 个媒体块都带有效 `created_at`。**块自带它该回到哪个时刻的坐标，现在没人用。**
|
||||
|
||||
### 失效 4：块在 Consume 时两层同时消失
|
||||
|
||||
**位置**：`internal/memory/document/document.go` — `Consume` → `removeDoc`
|
||||
|
||||
```go
|
||||
func (s *Store) removeDoc(id string) {
|
||||
delete(s.docs, id)
|
||||
...
|
||||
os.Remove(filepath.Join(s.dir, id+".json")) // 块的字节只在这个文件里
|
||||
}
|
||||
```
|
||||
|
||||
`doc_query` 调用 `Consume` 后，文档（含 `d.Blocks`）从内存与磁盘同时删除；
|
||||
而 `toolcall.go` 不回填 `Blocks`。**后果**：这些块既不在 L2（已删）也不在 L1（没挂），
|
||||
只剩局部变量引用，函数返回后即不可达。
|
||||
|
||||
**生产风险敞口**：L2 现有 444 个块，其中 **396 个不在 L3**（`graph.db` 里查不到），
|
||||
原始字节约 **248 MB**。一旦被 `doc_query` 命中即永久丢失。
|
||||
|
||||
### 失效 5：时序渲染用固定 120 rune 截断正文
|
||||
|
||||
**位置**：`internal/agent/core/process.go` — `formatMergedTimeline`
|
||||
|
||||
```go
|
||||
sb.WriteString(fmt.Sprintf(" → %s", truncateStr(e.Response, 120)))
|
||||
```
|
||||
|
||||
上下文预算可以是几百 K token（`ComputeTokenBudget`），但每条正文**永远只显示前 120 字**。
|
||||
原文即使用前提 D 完整保存在库里，模型也看不到——这是"不压缩"在**渲染环节**的漏口。
|
||||
|
||||
**生产证据**（`context.json`）：2 条 `cold_storage` 事件的 response 分别 1541 / 1209 字符，
|
||||
渲染出来都是 123 字符。
|
||||
|
||||
### 失效 6：`Prune` 的归档过滤要求本身违反前提 F
|
||||
|
||||
**位置**：`ARCHITECTURE.md` L13 写「过滤掉 `agentcli` 和 `terminal` 来源后归档」。
|
||||
|
||||
`agentcli` / `terminal` 是**插件名**。把它们写进内核归档规则 = 硬编码插件行为，违反前提 F。
|
||||
|
||||
**当前代码**：`Prune` 里没有任何源名过滤，该要求**未实现**；
|
||||
生产库里有 325 行 `agentcli` 归档（全部是终端状态行）。
|
||||
|
||||
⇒ 这不是"补上过滤"，而是**该要求应作废，改由插件声明驱动**（前提 F）。
|
||||
|
||||
---
|
||||
|
||||
## 二、修复顺序（按依赖）
|
||||
|
||||
失效 1/2 是存储形态，3/4 是召回形态，5 是渲染，6 是文档纠错。
|
||||
**必须先修存储**——存储里没有事件本体，召回就没有东西可放回。
|
||||
|
||||
| # | 动作 | 依赖 | 涉及文件 |
|
||||
|---|---|---|---|
|
||||
| ① | L2 存储形态改为「事件 + 块」（与 L1 同构） | — | `memory/document/document.go` |
|
||||
| ② | 文本正文以块承载（消灭 `Content` 作为唯一文本载体） | ① | 同上 + `agent/core/context.go` |
|
||||
| ③ | 召回按块/事件原始时序迁回 L1 | ①② | `agent/core/toolcall.go` |
|
||||
| ④ | 时序渲染改为按预算分配 | 独立 | `agent/core/process.go` |
|
||||
| ⑤ | 作废失效 6 的文档要求（改由 `NoMemory` 声明驱动） | 独立 | `ARCHITECTURE.md` |
|
||||
|
||||
### ① 的具体形状
|
||||
|
||||
`Doc` 与 `RelevanceContext` 的事件列表**同构**：
|
||||
|
||||
```
|
||||
L1: events []ContextEvent // Timestamp/Source/Input/Response/ToolsUsed/ToolResults/Blocks
|
||||
L2: events []ContextEvent // 同一结构，同一字段
|
||||
```
|
||||
|
||||
- `Doc` 保留 `ID` / `Summary` / `Vector` / `DenseVec` / `DenseFP` / `AccessCount` 等
|
||||
**检索元数据**（这些是 L2 作为"可检索容器"的附加属性，L1 不需要）
|
||||
- 事件列表**内联正文**（`Response` 完整，不截断）+ 持有的块
|
||||
- `Doc.Content` 降级为**纯渲染视图**（供摘要/人看/兼容 SDK 的 `Doc.Content`），
|
||||
不再作为原文载体；原文从事件读
|
||||
|
||||
> ⚠️ 注意与「已否决做法」的区别：不是新造一个异构字段把 `ContextEvent` 旁挂上去，
|
||||
> 而是让 **L2 的承载结构就是 L1 的那一套**。事件列表是文档的主体，不是附件。
|
||||
|
||||
### ② 的具体形状
|
||||
|
||||
- 归档时，每条事件的正文（`Input` / `Response`）生成对应文本块（`Modality=BlockText`，
|
||||
`Text` 即正文），块 `CreatedAt` = 事件时间戳
|
||||
- 媒体块照旧（`Data` 内联字节）
|
||||
- 事件 `Blocks` 里同时含文本块与媒体块 → L1/L2/L3 三处同构
|
||||
|
||||
### ③ 的具体形状
|
||||
|
||||
```
|
||||
doc_query → 取出 L2 事件列表（迁移语义：取出后 L2 不再持有）
|
||||
→ 逐条按各自 Timestamp 插回 L1 时序
|
||||
→ 事件持有的块随之迁回（同一块 ID，向量不重算）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、判据（先写判据再改，避免自证）
|
||||
|
||||
> 教训（本次已发生）：先改代码再写测试，测试就只会证明"我改的是我以为的"。
|
||||
> 判据必须**从设计前提推导**，且必须能在改动前**红**。
|
||||
|
||||
### ① 存储形态（L1/L2 同构）
|
||||
|
||||
- [ ] 归档后能从 L2 取回**逐条**事件的原始 `Timestamp`（完整时刻，非 `HH:MM`）、
|
||||
`Source`、`Response`（完整，非截断）、`ToolsUsed`、`ToolResults`
|
||||
- [ ] 变异：把 `Response` 改回 `truncate(..,100)` ⇒ 红
|
||||
- [ ] 变异：丢掉 `ToolsUsed` ⇒ 红
|
||||
- [ ] 变异：时间戳改回 `Format("15:04")` ⇒ 红
|
||||
|
||||
### ② 文本块
|
||||
|
||||
- [ ] 归档文档的文本块 `Text` 与事件正文逐字一致
|
||||
- [ ] 文本块 `CreatedAt` == 事件 `Timestamp`
|
||||
- [ ] 变异：不生成文本块（只存 `Doc.Content`）⇒ 红
|
||||
|
||||
### ③ 召回
|
||||
|
||||
- [ ] `doc_query` 后事件按**各自原始时间戳**回到 L1
|
||||
- [ ] 块 `ID`/`Vector`/`CreatedAt` 全程不变（迁移而非重建）
|
||||
- [ ] 块的持有层从 L2 变为 L1，**不同时留在两层**
|
||||
- [ ] 变异：用 `d.CreatedAt` 当时间戳 ⇒ 红
|
||||
- [ ] 变异：不回填 `Blocks` ⇒ 红
|
||||
|
||||
### ④ 渲染
|
||||
|
||||
- [ ] 预算宽裕时正文完整可见（含结尾哨兵）
|
||||
- [ ] 预算紧张时仍保留开头（不能整条消失）
|
||||
- [ ] 单条超长正文不得把其余事件整段挤掉
|
||||
|
||||
### ⑤ 文档纠错
|
||||
|
||||
- [ ] `ARCHITECTURE.md` 不再出现任何插件名作为内核归档规则
|
||||
- [ ] 判据：`grep -rn '"agentcli"\|"terminal"' internal/agent/core internal/memory`（非测试）为空
|
||||
|
||||
---
|
||||
|
||||
## 四、禁止事项（此前已犯，写下来防复发）
|
||||
|
||||
| 禁止 | 原因 |
|
||||
|---|---|
|
||||
| 给 `Doc` 加异构字段旁挂事件快照（如 `Entries []ContextEntry`） | L2 主体就是事件列表本身，不是"Doc + 附件" |
|
||||
| 改 `truncateStr` 的常数当作"修复压缩" | 视图截断不是记忆压缩问题；根因在存储形态 |
|
||||
| 任何插件名字面量进内核分支 | 违反前提 F |
|
||||
| 编造不存在的 API 再补注释解释它"应该"怎样 | 实现必须以真实存在的设施为准 |
|
||||
| 先按自己的理解写测试再改代码 | 会把误解固化成判据 |
|
||||
| 改公开 SDK 契约 | 前提 G：SDK 已等价，修内核实现 |
|
||||
|
||||
---
|
||||
|
||||
## 五、已否决的做法
|
||||
|
||||
### 否决 1：新增 `Doc.Entries` 存事件快照（2026-10-22，已实现又撤销）
|
||||
|
||||
错在**异构旁挂**：`Doc` 仍是字符串主体，事件列表被当成附件挂上去。
|
||||
正确形态是 §二①：事件列表**成为 L2 的主体**，与 L1 同构。
|
||||
|
||||
### 否决 2：把渲染层截断常数调大（2026-10-22，已撤销）
|
||||
|
||||
根因在存储形态，不在渲染常数。§二④ 单独处理，且应是**按预算分配**而非改常数。
|
||||
|
||||
---
|
||||
|
||||
## 六、已拍板的决定
|
||||
|
||||
### 1. 事件本体在 L2 的形态（2026-10-22 拍板）
|
||||
|
||||
**L2 就是 doc 存储，本身与 Context 同构，区别只在于是否被直接投喂给模型。**
|
||||
|
||||
⇒ 不是“复用 `ContextEvent` 当旁挂字段”，也不是“把事件也变成块”这种额外抽象。
|
||||
**事件列表就是 L2 文档的主体**，与 L1 事件列表同一结构。
|
||||
|
||||
### 2. 正文形态（2026-10-22 拍板）
|
||||
|
||||
**正文（包括多媒体正文）本身就内联在块里。**
|
||||
|
||||
⇒ 文本块的 `Text` 是正文，媒体块的 `Data` 是字节。
|
||||
不存在“块 + 外部正文”的分离形态，也不靠渲染字符串承载原文。
|
||||
|
||||
### 3. SDK（2026-10-22 拍板）
|
||||
|
||||
**记忆部分 SDK 已通过一套接口实现等价功能** ⇒ **不改公开 SDK 契约**。
|
||||
|
||||
对照表（`third_party/homeagent-sdk/sdk/memory.go`）：
|
||||
|
||||
| SDK 接口 | 等价的内核概念 |
|
||||
|---|---|
|
||||
| `TextEvent{Role, Content, Timestamp, Channel, Attachments}` | 事件（正文内联 + 附件） |
|
||||
| `DocMemoryAPI.Insert(doc)` | 写入 L2（纯文本） |
|
||||
| `DocMemoryAPI.InsertWithMedia(doc, attachments)` | 写入 L2（正文 + 媒体块） |
|
||||
| `DocMemoryAPI.Query(text, topK)` | 只读召回（不删除） |
|
||||
| `MediaAttachment{Digest, MIME, Data}` | 块引用（带 Data 为新内容，仅 Digest 为引用） |
|
||||
|
||||
⇒ 修的是内核实现没跟上契约语义，不是契约本身。
|
||||
|
||||
### 4. 存量数据（2026-10-22 拍板）
|
||||
|
||||
**等待系统自然冲刷**，不做迁移脚本。
|
||||
|
||||
约束：
|
||||
- 新代码必须能**读旧格式**（缺事件列表/缺文本块时降级），不得 panic、不得静默丢内容
|
||||
- 降级路径要有明确日志，便于判断存量退出进度
|
||||
- 旧格式文档被召回时按旧行为处理，**不伪造成“有原始事件”**
|
||||
|
||||
---
|
||||
|
||||
## 七、待确认的细节（实现层面，不阻塞开工）
|
||||
|
||||
1. **文本块与事件是一对一还是一对多？**
|
||||
一条事件生成一个文本块（`Input` + `Response` 合在一个 `Text` 里），还是各一块（便于分别检索）？
|
||||
|
||||
2. **`Doc.Content` 保留为渲染视图，还是彻底删除？**
|
||||
若保留，与事件列表信息重复；若删除，SDK 的 `Doc.Content` 则由事件列表现场渲染填充。
|
||||
|
||||
3. **L2 事件的检索向量怎么算？**
|
||||
现在 `denseFor` 用 `Summary + Content`。改为事件列表后，
|
||||
是用 `Summary + 各事件正文拼接`，还是用文本块自己的向量做融合（与媒体块一致）？
|
||||
|
||||
---
|
||||
|
||||
## 八、验收口径
|
||||
|
||||
- `go build ./...` 通过
|
||||
- 全量 `go test ./... -count=1` 0 失败（当前基线：58 包通过 / 0 失败）
|
||||
- §三 每条判据有对应测试，且**变异测试**各自能被抓住
|
||||
- 生产侧（可在副本库验证）：`doc_query` 召回后块不消失；新旧两种格式文档都能正确召回
|
||||
|
||||
---
|
||||
|
||||
## 九、实施记录（2026-10-22）
|
||||
|
||||
### 已落地
|
||||
|
||||
| # | 动作 | 落地位置 |
|
||||
|---|---|---|
|
||||
| ① | L2 存储形态改为「事件 + 块」 | `document.Doc.Events []DocEvent`；`ContextToDoc` 落盘事件列表 |
|
||||
| ② | 正文各自成文本块 | `docBlocksForEntry` / `entriesToEvents`；Input、Response 各一块（`BlockText`） |
|
||||
| ③ | 召回按原始时序迁回 | `Agent.restoreDocEvents`；`DocEvent.InOut()` 从块读回正文 |
|
||||
| ④ | 蒸馏改用原文 | `documentOriginalText`（有 Events 用块内原文，存量退回 Content） |
|
||||
| ⑤ | 文档纠错 | `ARCHITECTURE.md` 删除「过滤 agentcli/terminal」，改为「由插件声明驱动」 |
|
||||
|
||||
### Content 的定位（按拍板）
|
||||
|
||||
`Doc.Content` **保留为渲染视图**，由 `contentFromEvents` 生成：
|
||||
|
||||
- 供摘要、人工阅读、SDK 的 `Doc.Content` 字段使用
|
||||
- **不是**原文载体 —— 原文在 `Events[i].Blocks` 里文本块的 `Text`
|
||||
- 视图也不主动截断（存储层不替渲染层做决定）
|
||||
|
||||
### 存量
|
||||
|
||||
按拍板**不做迁移**，等系统自然冲刷。降级路径：
|
||||
|
||||
- `Doc.HasEvents() == false` ⇒ 召回时整篇渲成一条 `cold_storage` 事件（旧行为）
|
||||
- 不伪造成「有原始事件」；有日志可观测
|
||||
|
||||
### 判据与变异
|
||||
|
||||
新增两组判据（各条都在改动前设计、改动后可跑）：
|
||||
|
||||
| 文件 | 判据数 | 覆盖 |
|
||||
|---|---|---|
|
||||
| `internal/memory/document/blockflow_test.go` | 7 | 存储形态、文本块粒度、逐条保留、视图定位、幂等、存量兼容、原文可用性 |
|
||||
| `internal/agent/core/recalldoc_test.go` | 5 | 逐条回填、原始时间戳、块迁回、回填不截断、存量降级 |
|
||||
|
||||
**变异测试（全部被抓住）**：
|
||||
|
||||
| 变异 | 被哪条抓住 |
|
||||
|---|---|
|
||||
| 正文落库时 truncate(100) | `TestL2_ArchivePreservesFullText` / `TestL2_ContentIsRenderedViewNotSource` |
|
||||
| Input/Response 合成一块 | `TestL2_InputAndResponseAreSeparateTextBlocks`（及 3 条连带） |
|
||||
| 召回用 `d.CreatedAt` 当时间戳 | `TestRecallByDoc_RestoresEachEventAtOriginalTimestamp` |
|
||||
| 召回不回填 Blocks | `TestRecallByDoc_MigratesBlocksBackToContext` |
|
||||
| 召回再截 2000 字 | `TestRecallByDoc_TextIsNotTruncatedOnTheWayBack` |
|
||||
|
||||
### 未做（明确不做）
|
||||
|
||||
- **不改公开 SDK 契约**：`TextEvent` / `DocMemoryAPI` / `InsertWithMedia` 已等价
|
||||
- **不迁移存量文档**：等自然冲刷
|
||||
- **不改渲染层截断常数**（失效 5）：根因已在存储形态修掉；渲染按预算分配是独立议题，
|
||||
避免与本次修复混在一起、互相掩盖
|
||||
Reference in New Issue
Block a user