mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-01 06:47:29 +00:00
931c803421
只改仓库内文件的纯展示品牌名与已随批 2 落地的安装路径；运行时契约、仓库 URL、
域名、环境变量、可执行名、插件名一律不动。
一、纯展示名（HomeAgent → HologramAgent，共 44 处 / 18 个文件）
- README.md 4、README_EN.md 4（标题、client 变体说明、Windows 安装包名、AGPL 段）
- docs/ 8 个文件 14 处（git-branching 1、ci-cd-runbook 1、commondev-design 3、
commondev-agent-runtime-design 4、deploy-runbook 1、legacy-issues 1、
prod-migration-checklist 1、triple-extract-attention 2）
- assets/docs/ 6 个文件 14 处（zh/en 的 OVERVIEW 2+2、ARCHITECTURE 2+2、
PLUGIN_DEV 3+3）
- assets/branding/mascot-xiaozhai-guide.md 2 处（身份行、标志名）
- site/index.html 6 处（title、meta description、og:title、logo alt、页头字、
插件卡片文案 "HologramAgent 接入 AgentMail"）
二、安装路径对齐批 2 产物（共 10 处）
- /usr/lib/homeagent → /usr/lib/hologram（7 处：README 2、README_EN 2、
multimodal-space 3）
- /usr/share/doc/homeagent → /usr/share/doc/hologramagent（3 处：README 1、
README_EN 1、multimodal-space 1；注意 Doc 路径带 agent 后缀）
- site/index.html 的 19 处 HomeAgent 里，13 处是 github.com/JianFeeeee/HomeAgent
仓库 URL，属红线整串保留；只改 URL 之外的展示文案（其余 13 处零改动）
三、明确不改（红线 / 一致性冲突）
- site/index.html 的 23 个 github.com/JianFeeeee/homeagentsdk 外链（21 条
example + 2 条纯仓库），SDK 仓改名属批 4-b，一个未动
- 核心仓仓库 URL、sdk./introduce.homeagent.jianfgit.xyz 域名、HOMEAGENT_ 前缀、
homed/waiter/hmapdev、.hmap、homeagent-mail-bridge 等插件名、third_party/、
internal/ 与 cmd/ 全部零改动
- ~/.homeagent 路径本批保持原样：cmd/waiter/main.go:109、daemon.go:290 硬编码
仍为 .homeagent，全仓无 .hologram 命中；照规格改文档会指向程序不用的目录，
需与代码侧那条线一起改（遗留项，已单独上报）
判据：文档区展示名残留归零（44 文件）、红线计数与 base e3584bb 逐项相同、
三条变异均被咬住且还原后复绿。
152 lines
5.0 KiB
Markdown
152 lines
5.0 KiB
Markdown
# 生产迁移执行清单
|
||
|
||
**日期**：2026-10-04
|
||
**分支**：`feat/context-overflow-l4`（未 push）
|
||
**状态**：HologramAgent 已停机（inactive + disabled）
|
||
|
||
---
|
||
|
||
## 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` 是**同一份数据的迁移前后对照**，
|
||
两者都在，可随时重跑任何验证。
|