jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-06 17:27:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(memory): doc 层去掉 jieba 摘要 + doc_query 返回真实内容 + 三层记忆提示词

Browse Source 
上一轮（memory-blockflow-repair-plan）修好了 L1↔L2 结构，但功能不可用。
用生产数据实测：三个互不相关查询分数全挤在 0.75~0.79，区分度≈0，
命中内容与查询无关。本次修四层。

## ① 向量输入：Summary + Content → 事件正文

denseFor 原用 `VectorizeDense(doc.Summary + " " + doc.Content)`，而 Summary
由 summarizeEntries → memory.ExtractKeywords → TokenizeContentWords → jieba.Tag()
生成。同一来源的摘要逐字同质：

    来自 1 个来源的 1 条对话 (src0) 涉及: 用户, 提问
    来自 1 个来源的 1 条对话 (src1) 涉及: 用户, 提问

真实 chineseclip 实测（4 篇主题完全不同的短正文）：两两余弦 0.85~0.95。
这与设计矛盾 —— ARCHITECTURE 写的是「统一多模态空间（主）」，而 Summary
是主路径的输入，却由最末一级的词法分词产出。

改为 documentTextForVector(doc)：按事件顺序拼原文（块里的正文）。
存量无 Events 的文档退回 Content。

★ 媒体不单独生成摘要：媒体块与文本块在同一事件内
  （Doc.Events[i].Blocks），事件正文进入向量即覆盖其语义。
  为媒体单独写描述正是 CAS 时代「描述式索引」的错误，v1.2.0 已拆除。
  「按图搜图」是视觉路（RecallBlocks）的职责，已有独立通路。

## ② doc 层移除 jieba 语义生成

- summarizeEntries：jieba 词袋 → 取首条事件正文首行（真实内容，可读）
- 删除 extractTags / extractEntities（纯 jieba 词袋）
- 删除 Doc.Tags / Doc.Entities（前者唯一消费点是 doc_query 返回的
  「标签: map, content」噪声行；后者零消费点）
- doc_commit 删除 tags 参数（无处可存，留着会骗模型）

★ TF-IDF 回退路径**保留**（Store.tfidfEmb/tfidfIdx/ensureTFIDF/Reindex）：
  它是「稠密空间没加载」时的兜底，按 ARCHITECTURE「统一多模态空间（主）
  → 词嵌入 → TF-IDF（回退）」必须保留。但它不能是主路径 —— 一旦稠密空间
  可用，jieba 就不参与。

## ③ doc_query 返回真实内容

旧返回：「已加载 3 篇文档记忆: #1(来自 1 个来源的 1 条对话 (agent) 涉及: ok)」
——全 jieba 词袋，模型无法判断有没有用（这是它几乎不调用 doc_query 的直接原因）。

新返回：
    已召回 3 篇历史记忆，原文已按各自**原始时间戳**插回对话时序（不是当前对话）：

    [1] 2026-06-07 08:09 · webui · 2 条事件 · 含 1 份媒体
        配色方案怎么定？
        结论：紫蓝红三色带按六比三比一…

    共回填 N 条事件。要引用其中的细节，直接看对话时序里对应时间点即可。

每条给出「时间 · 来源 · 事件数 · 媒体数」+ 真实正文前几行。

## ④ 提示词：agent 终于能理解三层记忆

- doc_query 描述：一句话 → 覆盖「L2 是什么 / 何时用 / 调用后原文回填到时序 /
  与 memory_recall 分工 / 消费式副作用」
- doc_commit 描述：说清「适合写整段过程结论，不适合写单个事实」
- 系统提示词新增【三层记忆】段（内核运行时块）：L1 对话时序 / L2 历史记忆 /
  L3 图记忆各自是什么、怎么取、如何选择
- 预填充文案（crossModalMarkdown）：统计描述 → 时间+来源+正文开头，
  并在块尾明确引导「要完整原文用 doc_query」

## ⑤ 向量算法版本（否则修复对存量无效）

实测踩到的坑：改完 denseFor 后，1055 篇存量文档分数纹丝不动（0.78/0.79/0.76，
区分度 0.003）—— 因为 DenseFP 只记「哪个向量空间」，不记「用什么文本算的」，
指纹不变 ⇒ 全部命中跳过条件 ⇒ 永不重算。

修法：DenseFP = 空间指纹 + "|" + docVectorAlgoVersion(v2)。
算法一变，存量自动重算一次。

## 判据（每条都有变异自证）

document/retrieval_quality_test.go（6 条）：
- Top1HitsCorrectDoc / DistinctQueriesHitDistinctDocs / ScoreGapIsSignificant
- VectorInputIsBodyNotSummary（正文哨兵必须进向量）
- SummaryNoiseMustNotPolluteVector（主题不同的短正文，两两余弦 <0.80）
- AlgoVersionChangeForcesRecompute（换算法必须触发存量重算）

core/recalldoc_test.go（+2）：返回值必须含时间/来源/真实正文/时序说明
core/prompt_memory_test.go（5 条）：工具描述五项覆盖、doc_commit 范围、
  三层记忆段落、tags 参数已删、预填充文案含内容与 doc_query 引导

变异全部被抓住（截断落库 / Summary+Content / 去掉算法版本 / 旧预填充文案 /
一句话工具描述 / 删三层记忆段）。

## 验证

- go build ./... 通过；go vet ./... 干净
- go test ./... -count=1：58 包 0 失败
- go test -race ./internal/memory/document/ ./internal/agent/core/：通过
- 真实数据（chineseclip 512 维）：
  · 旧格式存量（1055 篇，无 Events）：4/5 → 仍是旧分数，等自然冲刷
  · 新格式文档（走 ContextToDoc）：4/5 top1 命中正确，
    区分度最高 0.18（旧实现 0.003）
This commit is contained in:
JianFeeeee
2026-10-22 19:49:25 +08:00
parent b1f02a22b6
commit e2cb6e70e0
9 changed files with 1052 additions and 294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
internal/agent/core/tooldefs.go
View File

@ -177,6 +177,26 @@ func (a *Agent) buildSystemPrompt(memContext string, userInput string) string {
prompt = appendPromptBlock(prompt, memContext)
}
// 【三层记忆】是**内核运行时块**（提示词分层规范：内核行为由内核生成）。
//
// 它讲的是内核的真实执行语义（哪些内容在哪一层、何时会进上下文、
// 哪个工具会做什么），不是工具用法 —— 工具用法归各 ToolDef.Description。
//
// 为什么必须有这一段：此前系统提示词从未解释 L1/L2/L3 是什么，
// agent 只能从工具名猜。生产日志实测：agent 几乎从不调用 doc_query，
// 即使调用了也只看返回值、不知道原文已被回填到对话时序。
prompt = appendPromptBlock(prompt, "【三层记忆】记忆分三层，你要知道自己现在在看哪一层：\n"+
"- **对话时序（L1，你现在看得到）**：最近的事件，按时间排列在上面那段【对话时序】里。"+
"窗口放不下的会更早被移出，但不会丢。\n"+
"- **历史记忆（L2，不直接给你看）**：被移出窗口的事件，连同**完整原文**（含图片/音频）保存在这里。"+
"每次你收到新输入，内核会按语义相似度自动挑几篇相关的放在【历史记忆】块里，"+
"但那只是片段 —— 要看某次的完整原文与过程，调用 `doc_query`："+
"它会把命中的事件**按原始时间戳插回你的对话时序**（不是返回一段摘要，那些事件真的回到了时间线上）。\n"+
"- **图记忆（L3，长期）**：实体与关系（谁是什么、某值现在是多少、谁和谁什么关系），"+
"用 `memory_recall` 查、`memory_commit` 记。\n"+
"选择口径：要**原文与过程** → `doc_query`；要**关系与当前值** → `memory_recall`；"+
"要**成文的可复用知识** → `knowledge_search`。")
// 记忆维护：具体选哪个工具、各有什么副作用，都写在 memory_* 的工具描述里
//（【记忆清理】前缀）。这里只保留那条**不看描述也会犯**的错：只描述计划不执行。
prompt = appendPromptBlock(prompt, "【记忆维护】用户要求整理或清理记忆时，必须真的调用 memory_* 工具去做，"+
@ -556,24 +576,47 @@ func (a *Agent) buildToolDefs() []interface{} {
}
if a.docStore != nil {
tools = append(tools, toolDefWith("doc_query", "查询文档记忆。输入查询内容，返回相关文档摘要。", map[string]interface{}{
"query": map[string]interface{}{"type": "string", "description": "查询内容"},
"top_k": map[string]interface{}{"type": "integer", "description": "返回数量", "default": 3},
}, []string{"query"}, parallelOpts()))
tools = append(tools, toolDef("doc_commit", "提交一条文档记忆。将重要信息显式写入文档记忆层。", map[string]interface{}{
"content": map[string]interface{}{"type": "string", "description": "文档内容"},
"summary": map[string]interface{}{"type": "string", "description": "摘要（可选）"},
"tags": map[string]interface{}{
"type": "array",
"description": "标签列表",
"items": map[string]interface{}{"type": "string"},
},
"media_digests": map[string]interface{}{
"type": "array",
"description": "可选：这篇文档关联的媒体 digest（对话或 memory_recall 的「关联媒体」里显示的十六进制串，短的即可）。填了以后检索到这篇文档就能看到并取回原图/音频。",
"items": map[string]interface{}{"type": "string"},
},
}, "content"))
// ★ doc_query / doc_commit 的描述必须与**真实行为**一致。
//
// 旧描述只有一句「查询文档记忆。输入查询内容，返回相关文档摘要」：
// · "文档记忆"没有定义，模型不知道 L2 是什么；
// · "返回相关文档摘要"与真实行为**不符**（真实是把事件逐条按
// 原始时间戳插回对话时序）；
// · 没说什么时候该用，也没说与 memory_recall 的分工。
// 结果：生产实测 agent 几乎不调用 doc_query，即使调用也只看返回值、
// 不知道原文已回填到时序。
tools = append(tools, toolDefWith("doc_query",
"从**历史记忆层**（L2）召回过去的事件原文。"+
"\n\n**这一层是什么**：当前对话窗口里只看得到最近的事件；更早的事件被移出窗口后，"+
"连同原文完整保存在历史层，不会丢失。"+
"\n\n**何时用**：记得«这事办过/说过»但想不起细节；需要当时的原始过程而非结论；"+
"跨会话、跨天追问；用户问\"上次那个\"/\"之前怎么弄的\"。只想知道某个事实的当前值、"+
"或某个实体的关系，用 memory_recall（图记忆），不要用这个。"+
"\n\n**调用后会发生什么**：命中的事件会**逐条按原始时间戳插回你的对话时序**"+
"（就是【对话时序】那一段，出现在它当时的时间点上），"+
"返回值会列出每条的时间/来源/正文开头。要引用细节，读时序里对应时间点即可。"+
"\n\n**副作用**：召回即从历史层取出（消费式），该文档不再留在 L2。",
map[string]interface{}{
"query": map[string]interface{}{"type": "string", "description": "查询内容，用当时可能出现的词描述"},
"top_k": map[string]interface{}{"type": "integer", "description": "召回多少篇（默认 3）", "default": 3},
}, []string{"query"}, parallelOpts()))
tools = append(tools, toolDef("doc_commit",
"把**整段结论/过程**写进历史记忆层（L2）。"+
"\n\n**适合写什么**：做完一件事的完整过程与结论、排查链条、方案取舍的理由 —— "+
"这些内容长、有上下文、以后要回看原文。"+
"\n\n**不适合写什么**：单个事实或实体关系（谁是谁、某值等于多少、偏好）→ 用 memory_commit；"+
"可复用的成文知识 → 用 knowledge_create。"+
"\n\n写入后会参与后续的自动预填充与 doc_query 召回。",
map[string]interface{}{
"content": map[string]interface{}{"type": "string", "description": "文档内容（完整正文，不要自己截断）"},
"summary": map[string]interface{}{"type": "string", "description": "一句话摘要（可选，留空则由正文首行生成）"},
"media_digests": map[string]interface{}{
"type": "array",
"description": "可选：这篇文档关联的媒体 digest（对话或 memory_recall 的「关联媒体」里显示的十六进制串，短的即可）。填了以后检索到这篇文档就能看到并取回原图/音频。",
"items": map[string]interface{}{"type": "string"},
},
}, "content"))
}
if a.social != nil {