生命快照与目录映射 · 设计文档

版本: v1.0 · 2026-08-29 解决: Hermes Cloud 配置、Profile 目录、会话记录的备份与跨平台恢复

一、为什么不用 symlink 直接提交

实测结论（2026-08-29）

平台	git 存什么	克隆后得到什么
Linux (`core.symlinks=true`)	只有目标路径字符串（如 `/opt/data/config.yaml`，一个18字节blob）	一条指向不存在路径的死链接，内容永远不在仓库里
Windows (`core.symlinks=false` 默认)	同上一个小文本文件	一个普通文件，内容就是路径字符串——这正是你之前看到"快捷方式只提交了快捷方式"的原因

结论：symlink 在 git 里≠目录拷贝。它适合"同机多入口"（省空间），完全不适合跨平台备份/恢复。

正确方案：快照脚本（sync-life-snapshot.sh）

不链接，而是每次运行时把可提交的文本资产"复制汇聚"到仓库：

✅ 内容真正进仓库（跨平台可用）
✅ 自动脱敏（api_key → SK-REDACTED）
✅ 排除二进制/缓存/node_modules（profiles 393MB → 快照仅 344KB）
✅ SQLite 会话库 → 导出为纯文本 markdown（Windows 也可直接读）

二、快照覆盖范围（每目录说明）

源位置	内容	快照方式	大小
`/opt/data/config.yaml`	Hermes 核心配置	脱敏整拷	~2KB
`/opt/data/profiles/*/config.yaml`	8个Profile配置	脱敏整拷	~16KB
`/opt/data/profiles/*/SOUL.md`	8个分身灵魂	原样拷	~24KB
`/opt/data/profiles/*/skills-manifest.txt`	技能清单（索引非内容）	生成	~8KB
`/opt/data/state.db(messages)`	会话聊天记录	导出最近500条为MD	~150KB
`/opt/data/skills/**/SKILL.md`	全局技能索引	清单	~4KB
目录拓扑	profiles/全局目录结构	生成	~2KB

明确排除（.gitignore 已拦截）：profiles//home（271MB缓存）、node_modules、sessions二进制、logs、cache、.db。

三、Linux 下的目录映射（symlink 用法）

在本机使用时（非提交），用 symlink 把外部目录挂进仓库视图，方便统一浏览：

# 只在本机浏览用, .gitignore 已忽略这些链接(不会提交)
ln -sfn /opt/data/config.yaml ~/.fmode-harness-agent/live/hermes-config.yaml
ln -sfn /opt/data/profiles ~/.fmode-harness-agent/live/profiles
ln -sfn /opt/data/skills ~/.fmode-harness-agent/live/skills
ln -sfn /opt/data/knowledge-base ~/.fmode-harness-agent/live/knowledge-base

.gitignore 规则：

live/

四、Windows 下的等价方案

Windows 开发者模式开启后可 mklink（需管理员），但对 git 提交依然无效（同 Linux 结论）。Windows 端的正确姿势：

克隆仓库后直接运行快照脚本（Git Bash 支持 bash 脚本）：

git clone https://git.fmode.cn/liuyuyang/agent-yuyang001.git $env:USERPROFILE\.fmode-harness-agent
cd $env:USERPROFILE\.fmode-harness-agent
bash scripts/sync-life-snapshot.sh   # 快照逻辑同Linux(SQLite/markdown/sed都跨平台)

要"看"实时目录：用 New-Item -ItemType SymbolicLink（管理员）或直接在资源管理器固定常用路径，不要指望把它提交。

五、恢复方案（部署新环境时）

5.1 全量恢复流程

# 1. 克隆
git clone https://git.fmode.cn/liuyuyang/agent-yuyang001.git ~/.fmode-harness-agent

# 2. 引导(YOLO/中文/SSH/env骨架)
cd ~/.fmode-harness-agent && bash scripts/bootstrap.sh

# 3. 恢复 Hermes 主配置
cp snapshots/hermes-config.yaml /opt/data/config.yaml
# 把 SK-REDACTED 换成真实 key(来自 secrets/.env, 不在仓库里)
sed -i "s/SK-REDACTED/$FMODE_API_KEY/" /opt/data/config.yaml

# 4. 恢复 Profiles
for p in snapshots/profiles/*/; do
  name=$(basename $p)
  mkdir -p /opt/data/profiles/$name
  [ -f $p/config.yaml ] && cp $p/config.yaml /opt/data/profiles/$name/config.yaml
  [ -f $p/SOUL.md ] && cp $p/SOUL.md /opt/data/profiles/$name/SOUL.md
done
# 同样把每个config里的 SK-REDACTED 换回真值

# 5. 架构自检
bash audit-arch.sh

5.2 会话记录恢复

快照MD（500条）：直接阅读/检索，进 RAG 或作为冷启动上下文

完整数据库（148MB）：不进 git（体积+隐私），恢复大库用 S3：

# 上传(本机)
obsutil cp /opt/data/state.db obs://storage-s3-nkkj/user/sr2WiPsDyQ/db/state-$(date +%F).db -e=... 
# 下载(新机)  索引在 life/BINARY_INDEX.md

5.3 恢复验证清单

检查	命令
配置生效	`hermes config get approvals.mode` = off
Profile完整	`ls /opt/data/profiles/` 有8个目录
会话可查	grep snapshots/sessions-recent.md
技能索引	`cat snapshots/skills-index.txt`
架构免疫	`bash audit-arch.sh` 全PASS

六、自动化节奏

手动：任何重要变更后随手跑 bash scripts/sync-life-snapshot.sh
每日 cron（建议）：0 22 * * * bash ~/.fmode-harness-agent/scripts/sync-life-snapshot.sh
大库（state.db）每周末传 S3 一次

SNAPSHOT-DESIGN.md 5.1 KB Постоянная ссылка История Исходник