05 · 持久化层

架构剖析第五篇：SQLite + 文件树的分层存储、迁移、路径自愈。 对应「技术架构长视频」章节 5。来源 ARCHITECTURE.md §6。

---

§6.1 为什么选 SQLite

• 单文件、零运维、事务安全（WAL）；
• 单进程用户桌面应用，无并发争用问题；
• 数据（对话树、元数据、凭证索引）直接和 workspace/ 文件树平行。

§6.2 数据分层

• SQLite（workspace/familiars.db）：结构化数据 —— agent 元信息、对话树索引、待办/日程/提醒、技能 manifest、权限/审批、Broker 元、凭证加密引用（SECRET.json 是内容落地的密文）……
• 文件树（workspace/）：对话内容本身（dialogue_<n>/、turn_*、step_*）、报告、工坊产物、市场资源、SECRET.json、.bridge.log / audit.log。

迁移

• 迁移器在 src/storage/migrations/（.sql 或 .py），启动时按版本跑，当前到 v19；

• 备份 workspace/familiars.db 后再升级；迁移不可逆。

路径自愈（重点）

• bridge 启动时跑 align_all_paths()：
  1. 仓库根漂移 —— 自动比较每个 dialogue.path 前缀是否匹配当前仓库根，漂移则自动改写 dialogue.json + turn_*/plan.json + step_*.json，并记录到 workspace/.paths_aliases.json；
  2. 外部目录别名 —— python -m src.tools.paths_migrate <old> <new> --record（先 --dry-run），每次开机回放。
• 日志文件（.bridge.log、audit.log）永不改写，保留真实历史。

---

视频时间点映射

视频时间点	内容
（待录制）	SQLite 与文件树怎么分、为什么
（待录制）	把 repo 文件夹移动一下 → 看路径自动对齐

---

下一篇：06-主动决策与礼物 →