1d52ba85d5
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（评测历史记录）。
4.9 KiB
entities 退场迁移方案
归档说明（2026-10-27）：本文是历史计划，术语已过时 ——
doc_query/doc_commit已改名为coldcontext_query/coldcontext_commit， 图记忆（Graph）在对外语义上改称 stablemem（稳定记忆）。 现行架构与术语以assets/docs/zh/ARCHITECTURE.md为准；本文保留作为决策记录。
状态：已确认（方案 A：三表全退），执行中 范围：含生产实例 ${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 双模式权重（直接复用）