mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 09:17: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 通过（纯文档改动）
158 lines
5.3 KiB
Markdown
158 lines
5.3 KiB
Markdown
# 生产迁移执行清单
|
||
|
||
**日期**：2026-10-04
|
||
**分支**：`feat/context-overflow-l4`（未 push）
|
||
**状态**：⚠️ **归档（2026-10-04 的一次性操作清单）**
|
||
|
||
> 本文记录的是那次停机迁移的**执行现场**。其中「已停机」是当时的真实状态，
|
||
> **不是现在的状态** —— 现在就别照着这份清单判断服务是否在跑。
|
||
>
|
||
> 现行部署操作见 [`deploy-runbook.md`](./deploy-runbook.md)；
|
||
> 服务当前状态用 `systemctl status hologramagent` 查。
|
||
|
||
---
|
||
|
||
## 0. 前置条件（必须全部满足）
|
||
|
||
| 项 | 要求 | 实测 |
|
||
|---|---|---|
|
||
| 服务停机 | `homeagent.service` inactive | ✅ inactive + disabled |
|
||
| WAL 已 checkpoint | `PRAGMA wal_checkpoint(TRUNCATE)` 返回 0\|0\|0 | ⬜ 执行前重查 |
|
||
| 快照已存在 | 一致副本（非 `cp`，用 `.backup`） | ✅ `/var/tmp/ha-prod-migrate/before.db` |
|
||
| 快照基线 | 1294/980/66/98/97 | ✅ 已核对 |
|
||
| 副本验证 | 结构 7 项 + 召回 7/9 | ✅ 已通过 |
|
||
| 代码提交 | 43 包全绿 | ✅ |
|
||
| 磁盘空间 | 迁移后约 18MB（副本实测） | ⬜ 执行前确认 |
|
||
|
||
★ **副本用的就是生产快照**，所以"在副本验证"等价于"在生产数据形态上验证"。
|
||
|
||
---
|
||
|
||
## 1. 执行步骤
|
||
|
||
```bash
|
||
# ① 停机确认（已停，此处防呆）
|
||
systemctl is-active homeagent.service # 期望: inactive
|
||
systemctl is-enabled homeagent.service # 期望: disabled
|
||
|
||
# ② WAL checkpoint
|
||
sqlite3 ${HA_DATA}/memory/graph.db "PRAGMA wal_checkpoint(TRUNCATE)"
|
||
# 期望输出: 0|0|0
|
||
|
||
# ③ 生成新快照（.backup，不是 cp）
|
||
TS=$(date +%Y%m%d-%H%M%S)
|
||
sqlite3 ${HA_DATA}/memory/graph.db ".backup '/var/tmp/ha-prod-migrate/prod-$TS.db'"
|
||
# 核对副本基线与源库一致
|
||
sqlite3 /var/tmp/ha-prod-migrate/prod-$TS.db \
|
||
"SELECT COUNT(*) FROM entities; SELECT COUNT(*) FROM relations; SELECT COUNT(*) FROM sentences;"
|
||
|
||
# ④ 先报告（不写库）
|
||
go run -tags onnxruntime ./cmd/homed-graph-migrate \
|
||
-db ${HA_DATA}/memory/graph.db \
|
||
-embed-provider chineseclip \
|
||
-model-dir /var/tmp/ha-c/models/chinese-clip-vit-b16-onnx
|
||
# ★ 核对：实体 1294，关系 966，块 98，块边 97
|
||
# ★ 若数字对不上 → 停止，不要 -apply
|
||
|
||
# ⑤ 执行迁移（约 200s）
|
||
go run -tags onnxruntime ./cmd/homed-graph-migrate \
|
||
-db ${HA_DATA}/memory/graph.db -apply \
|
||
-embed-provider chineseclip \
|
||
-model-dir /var/tmp/ha-c/models/chinese-clip-vit-b16-onnx
|
||
|
||
# ⑥ 验证
|
||
bash scripts/verify-migration.sh ${HA_DATA}/memory/graph.db
|
||
# 期望：✅ 结构验证全部通过
|
||
|
||
# ⑦ 召回探针
|
||
PROD_SNAPSHOT=${HA_DATA}/memory/graph.db \
|
||
go test -count=1 -tags onnxruntime ./internal/memory/ \
|
||
-run 'TestProbe_生产规模召回' -v
|
||
# 期望：casual 3/4, confusable 1/1, abstention 3/3, 合计 7/9
|
||
```
|
||
|
||
★ 全程**串行**。迁移涉及 1294 个块的 embedding，
|
||
并行会导致资源争用与长时间卡死（此前实测过 600 秒卡死）。
|
||
|
||
★ **旧表不删**。迁移只写块与边，`entities/relations/sentences`
|
||
保持原样（验证脚本第 1 项逐表核对）。
|
||
|
||
---
|
||
|
||
## 2. 期望产出（副本实测值）
|
||
|
||
```
|
||
句子 +66，块 +1294，边 +980，scene_refs +718
|
||
块 2752（带向量 1391），边 2371
|
||
悬空端点 0
|
||
向量维度唯一 512，fingerprint 唯一
|
||
confidence 为 0 的关系边 0 条
|
||
deleted 状态关系边 14 条（对应旧表 14 条）
|
||
中心向量已重建（各向异性 detected，双边中心化启用）
|
||
耗时约 200s
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 回滚
|
||
|
||
### 回滚条件
|
||
|
||
迁移后出现以下任一情况 ⇒ 立即回滚：
|
||
|
||
- 验证脚本报 `❌`
|
||
- 召回探针合计低于 4/9（迁移前基线）
|
||
- 启动后 `memory_recall` 报「检索失败」
|
||
- 健康检查异常
|
||
|
||
### 回滚方式
|
||
|
||
★ **旧表未被改动**，所以回滚很简单：
|
||
|
||
```bash
|
||
# ① 恢复代码到迁移前的提交
|
||
git checkout 75d4609 # 或 d4eda47 / 2fe4ca7 等任一已验证提交
|
||
|
||
# ② 恢复数据库（若需要）
|
||
TS=<迁移时的快照时间戳>
|
||
cp /var/tmp/ha-prod-migrate/prod-$TS.db ${HA_DATA}/memory/graph.db
|
||
# ★ 生产库必须用 .backup 恢复，不要直接 cp 源库
|
||
|
||
# ③ 重建二进制并重启（需你确认后才启服务）
|
||
go build -tags onnxruntime -o build/homed ./cmd/homed
|
||
systemctl enable homeagent.service && systemctl start homeagent.service
|
||
```
|
||
|
||
### 回滚安全性
|
||
|
||
| 保证 | 依据 |
|
||
|---|---|
|
||
| 旧表数据完好 | 迁移只 INSERT 块/边，验证脚本第 1 项核对 |
|
||
| 迁移单事务 | 任一步失败整体回滚 |
|
||
| 迁移自动快照 | 命令自身会生成 `.bak-<时间戳>` |
|
||
| 代码可回退 | 全部改动已提交，未 push |
|
||
|
||
---
|
||
|
||
## 4. 迁移后仍存在的问题（不阻塞迁移，但要记录）
|
||
|
||
| 问题 | 状态 | 补法 |
|
||
|---|---|---|
|
||
| `coexist` 泛指提问召不回端口号 | 0/1 | BFS 接入 `RecallBlocksFused` |
|
||
| 纯中文编造查询不拒答 | 契约外 | 需符号切分改进或换判定信号 |
|
||
| 旧表仍在增长 | 待停双写 | 读方已全切，可摘 `commit()` 里的 INSERT |
|
||
| `TestResidualKeepReturnsTasksToParent` | 既有 flake | 单独复验，勿误判 |
|
||
|
||
---
|
||
|
||
## 5. 与旧快照的关系
|
||
|
||
```
|
||
/var/tmp/ha-prod-migrate/before.db 本轮开始时的生产基线（1294/980/66/98/97）
|
||
/var/tmp/ha-prod-migrate/probe.db 副本，已完整迁移并验证
|
||
/var/tmp/ha-prod-migrate/base-copy.db 迁移前基线探针用
|
||
```
|
||
|
||
★ `before.db` 与 `probe.db` 是**同一份数据的迁移前后对照**，
|
||
两者都在，可随时重跑任何验证。
|