本地同步与数据新鲜度

适用形态: D2 (self-host, always-on) — 生产语料的本地机与跑判断的常驻节点 分离时。D1 (纯本地) 不需要本流程 (本机即生产即消费)。

决策背景: ADR-011 · 私有 data repo 的单写者纪律。

为什么需要这一步

always-on 形态下,跑判断 / 评审的常驻节点 (云 VM) 与生产语料的本地机是两台机器。 Wiki (_wiki/) 是判断的背景知识,由本地编译;常驻节点要用上最新背景,就得有一条 同步链路把快照送过去。

约束 (ADR-011 §7): confidential 语料不进审计主仓,走独立私有 data repo; 且 data repo 单写者 —— 只有本地生产机能写,远端只读拉取。这样既隔离敏感数据, 又避免多写冲突。

数据链路

本地生产机  data_sync.sh ──push──▶  私有 data repo ──(远端 timer 自动 vm_pull --ff-only)──▶  常驻节点 _wiki/ ──▶ 判断卡片背景知识
本地生产机  git push     ──────────▶  main (代码 / skills)  ───────(同上 --ff-only)─────────▶  常驻节点代码

要点:

• 本地只推,远端只拉。 data repo 的唯一写入口是 scripts/data_sync.sh。
• 远端 scripts/vm_pull.sh 由 systemd timer 周期触发 (示例 30min),--ff-only 永不产生合并,并把 wiki/ 快照物化到 _wiki/。
• 新鲜度阈值默认 48 小时 (scripts/data_freshness.py);超过即在判断卡片 "背景知识"字段标 ⚠️。

任务 A · 刷新 wiki 新鲜度

何时做: 判断卡片背景知识标了 ⚠️ (快照 > 48h);或刚往 raw/ 加了素材、 重编了 _wiki/,想让常驻节点用上新背景。

在本地生产机,两步 — 先编译、再推送:

cd ~/boss-vault
# ① 重编译 wiki (启发式, 无需 API key) —— 把 raw/ 最新素材编成 _wiki/
python3 scripts/build_wiki.py --dry-run   # 先看会产出多少 (只统计)
python3 scripts/build_wiki.py             # 真编译, 覆盖 _wiki/

# ② 推快照到私有 data repo
bash scripts/data_sync.sh --status        # 看最后同步时间 (只读)
bash scripts/data_sync.sh --dry-run       # 演练, 打印将推什么 (不写不推)
bash scripts/data_sync.sh                 # 真推

应看到 ✓ 已推送 (…)(有变更)或 ✓ 无变更, 不提交 (幂等)。

⚠️ 只推不编 = 推旧货。 常见坑: 只跑 data_sync.sh 不跑 build_wiki.py → 推的还是上次编的旧 _wiki,新素材没进 (表现: 浏览页实体的文件时间戳停在旧日期)。 先编译、再推。

生效: 远端 timer 最迟一个周期内自动拉到并物化到 _wiki/,下一单判断 / 评审即用新背景。已发完的单不受影响。远端只读知识库浏览页(运维管理台内、 受访问控制)也随之显示最新实体。

前置 (一次性): data repo 须先 clone 到本地。仓名必须含 boss-vault-data 字样 —— data_sync.sh 会校验 origin URL 防误推到别的仓。

git clone <your-private-data-repo> ~/boss-vault-data

非默认路径用 DATA_REPO_DIR=/path bash scripts/data_sync.sh。

任务 B · 本地代码跟上 main

何时做: 合了新 PR,想让本机 /boss 也用上修好的版本。

cd ~/boss-vault
git status                 # 确认无未提交脏改动
git checkout main
git pull origin main

有未提交改动先 git stash,pull 完再 git stash pop。本机不必与常驻节点同版, 但跟上 main 能保证本机 /boss 也是最新逻辑。

远端自动 (无需手动)

项	谁做
拉新代码 (main --ff-only)	vm_pull systemd timer
拉 wiki 快照 + 物化到 _wiki/	同 vm_pull.sh
worker / 长连接接收常驻	systemd 自动重启

VM 侧手动操作 (改 .env、重启 service、看日志) 见 部署指南 与 故障排查。

速查表

场景	命令 (本地生产机)
卡片新鲜度 ⚠️	bash scripts/data_sync.sh
看最后同步时间	bash scripts/data_sync.sh --status
只演练不推	bash scripts/data_sync.sh --dry-run
代码跟 main	git checkout main && git pull origin main
raw 加料后刷新	先 build_wiki.py 再 data_sync.sh

相关

• ADR-011 · 私有 data repo
• 部署指南 · 三种形态
• 故障排查

---

v1.0 · 见 ADR-011 §7 单写者纪律