4963d70215
## 上一轮的遗漏 上次只补了"缺状态行"，但**32 篇正文里的状态声明基本没动**。而那些声明 大多是 1~2 周前写的，代码早已推进。本轮逐篇对代码核实。 ## 逐篇核实结果（方法：读当前代码，不看文档的历史描述） ### 1. memory-usability-plan：待执行 → 已实施 文档写「状态：**待执行**（2026-10-22）」。三条根因实测**全部已修**： | 根因 | 实测 | |---|---| | R1 向量化输入是 jieba 词袋 | ✅ `coldcontext.go` 的 `denseFor` 明写「用事件正文（原文），不用 Summary（jieba 词袋）」 | | R2 媒体块无语义 | ✅ 块 union 化，媒体即块自带描述 | | R3 提示词无引导 | ✅ `tooldefs.go` 明写 `coldcontext_query` 把历史**插回时序**，并下沉到 kernel-memory skill | ### 2. entities-retirement-plan：执行中 → 方案已定、执行未完成 写「三表全退，执行中」，容易被读成"快完成了"。实测生产库： `entities 1292 / relations 978 / sentences 66` 行**仍在用**。 迁移工具就绪，但生产未切换 —— 这个区别对判断风险很关键。 ### 3. scene-memory-fix-plan：部分落地 → 7 步里 5 步完成 逐条核实：步骤 1/2/3/5/6 已完成（含 SDK 的 `ScenePolicy`、 `scene_emerge.go` 已区分 `peer:group_*` 与 `peer:user_*`）； 步骤 4（清现网垃圾场景）与 7（收口验证）属现场操作，未复核。 ### 4. prod-migration-checklist：⚠️ 最危险的一处 写「**状态**：HologramAgent 已停机（inactive + disabled）」—— 那是一次性迁移（2026-10-04）当场的真实状态，**不是现在的**。 照着它读会以为服务停着。改为明确归档说明 + 指向现行 runbook。 ### 5. abstention-criterion：「拒答尚未接入生产路径」已不成立 实测拒答已下沉到图库层（`RecallBlocksGuarded`），生产路径 `toolcall.go:1312` 与端到端探针**走同一条路**。保留了下沉的理由 （第一版放上层，探针绕过它 ⇒ 判据测不到被测路径）。 剩余两项（泛指词检测、n=10 样本偏小）仍开放。 ### 6. toolcall-parallel-execution-plan：阶段 0.5 起为待办 → 全部已完成 实测阶段 0/0.2/0.5/1/2/2.5 与 3/4 全部完成，遗留项也已解决。 ## 顺带修正两处写法 - `memory-restructure-plan.md`：顶部有「执行结果摘要」但正文各步骤仍写 `✗ 未开始`（原始计划快照，有意保留）。加一句读法说明， 避免读者拿正文的快照当现状。 - `future-plan.md` §六：新增 5 条实测确认的待办并去掉 2 条重复项 （遗留表退役、中断子系统原先各出现两次）。 ## 核对 - docs/zh 32 篇全部有状态行，且与代码实测一致 - 代码块全部配平；文档间相对链接全部有效 - go build 通过（纯文档改动）
5.4 KiB
entities 退场迁移方案
归档说明（2026-10-27）：本文是历史计划，术语已过时 ——
doc_query/doc_commit已改名为coldcontext_query/coldcontext_commit， 图记忆（Graph）在对外语义上改称 stablemem（稳定记忆）。 现行架构与术语以assets/docs/zh/ARCHITECTURE.md为准；本文保留作为决策记录。
状态：方案已定，执行未完成（2026-10-31 复核）。
方案是「三表全退」（
entities/relations/sentences并入memory_blocks）。迁移代码在（internal/memory/migrate_entities.go）， 但生产库仍在用旧表：entities 1292 行 relations 978 行 sentences 66 行⇒ 本计划的「执行中」不能读成"快完成了"，而是迁移工具就绪、 生产尚未切换。切换前的剩余读方清单见
legacy-table-retirement.md§八 / §十二。 范围：含生产实例 ${HA_DATA}（用户 2026-10-02 确认迁移） 前置：docs/zh/memory-restructure-plan.md（重构计划） 原则：一次迁移，删除所有 entities 遗留，避免后续误导。
〇、执行前必须确认的一个决策
relations / sentences 两张表跟不跟 entities 一起退？
现状：三元组 = entities + relations + sentences 三表联写（graph.go Commit）。 块形态：节点 = memory_blocks，边 = memory_block_edges。
- 方案 A：三表全退（彻底）—— relations 是第二套边系统，留着必然误导； sentences 的"原句"职责由 text block 承担（memory_block_edges 已支持 sentence 端点 kind，但句子本身该是块）。
- 方案 B：只退 entities（保守）—— relations/sentences 暂留， 改成引用 block id。
已确认方案 A（用户 2026-10-02）：留着 relations 就等于留着第二套边， 两套边系统并存正是"浆糊"的来源。波及面：68 处 SQL（26+29+13）+ 10 个测试文件。 生产实例纳入迁移范围，在第 3 步单独执行并快照回滚。
一、依赖面清单（已核实）
内核（internal/memory）
| 文件 | 依赖 | 处置 |
|---|---|---|
| graph.go | 26 处 SQL，Commit/Recall/merge/delete 全链 | 重写：Commit→PutMemoryBlocks+edges；Recall→块向量召回 |
| noise.go | IsNoiseEntity / NoiseEntities | 改为块判噪或删 |
| scene.go | TagSceneByEntityGlob 等 6 处 | 改挂块节点 |
| migrate.go | LegacyMediaEntityDigest（旧→块迁移） | 改名/扩为全文实体迁移 |
| block.go | 1 处（端点校验引用 entities） | 改：端点只认 block |
| indexer.go | vectorSearchEntities / buildIndexSummary | 改为块索引 |
接口面（对外契约，不能断）
| 调用方 | 现状 | 处置 |
|---|---|---|
| memoryface.go GraphMemory 接口 | Recall/RecallSorted/Commit | 签名保留，实现换块 |
| sdk/memory_impl.go (Recall/Commit) | 外部插件走这条 | 同上，返回类型适配 |
| corehandler_memory.go | 插件 RPC | 同上 |
| cli / webui / healthcheck 插件 | mem.Recall(...) | 签名不变则无感 |
| toolcall.go memory_recall 工具 | g.RecallSorted | 输出格式改块（模型侧 description 同步） |
测试（10 个文件）
recall_order_test / noise_test / graph_test / light_memory_test / scene_test / scene_dedupe_test / reclaim_test / graph_readonly_test / indexer_test / medialive_test —— 随实现重写，判据保留（变异自证的成果不能丢）。
二、迁移步骤（每步可编译可测试）
第 1 步：块召回先行（不动 entities）
- GraphDB.RecallBlocks(queryVec, topK)——vector.SearchScored 走块
- memoryface 加方法（不改旧 Recall 签名）
- toolcall 的 memory_recall 输出切到块结果
- 验收：真库跨维度探针 ≥4/5（用已验证判据）
第 2 步：Commit 换块（写入侧切换）
- distill 产出 → 原句块+字段块+contains 边（重构计划第 2 步）
- memory_commit 工具同样改块
- 旧 Commit 保留但标记 Deprecated，仅存量读取用
- 验收：新写入 0 行进 entities（用计数断言）
第 3 步：存量实体迁移为块
- 沿 MigrateLegacyMediaEntities 方向写 MigrateLegacyEntities： 实体名→text block（带向量），关系→block edges
- 可回滚：先快照 graph.db，迁移后探针验证，确认后清理
- 孤儿（49 个无关系无原句）→ 原样转为孤立块，不编造连接
- 验收：迁移后跨维度 ≥4/5；快照可回滚
第 4 步：物理删除（最后一步，不可逆）
- 删 entities/relations/sentences 三表 + graph.go 全部相关 SQL （26+29+13 处）+ noise.go/scene.go/indexer.go 的实体路
- 删 Entity/Relation/RecallResult 类型，接口面统一块类型
- 删相关测试，保留判据重写为块版
- 验收：
grep -r entities internal/零命中；全量测试绿； 知识库 content.md 的记忆系统描述同步更新
三、风险与回滚
- 每步一个 commit，第 4 步前任意一步可 revert
- 第 3 步动真库前必须快照（cp graph.db graph.db.bak-）
- 生产实例 ${HA_DATA} 不在本次范围（需人工确认后单独做）
四、明确不变
- memory_recall 工具名与参数（调用方模型无感知）
- pkg/embedding provider SPI（内核无感边界）
- scene 机制（改挂块节点，机制本身保留）
- vector.Store / qwen3vl 双模式权重（直接复用）