mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 17:27:31 +00:00
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 通过（纯文档改动）
119 lines
5.4 KiB
Markdown
119 lines
5.4 KiB
Markdown
# 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`](./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-<ts>）
|
||
- 生产实例 ${HA_DATA} **不在本次范围**（需人工确认后单独做）
|
||
|
||
## 四、明确不变
|
||
|
||
- memory_recall 工具名与参数（调用方模型无感知）
|
||
- pkg/embedding provider SPI（内核无感边界）
|
||
- scene 机制（改挂块节点，机制本身保留）
|
||
- vector.Store / qwen3vl 双模式权重（直接复用）
|