# 云端与本地 Hermes 配置上 GitHub — 实施方案

> **命名：** 云端与本地如何上github
> **版本：** v1.0
> **状态：** 待执行

**目标：** 将云端服务器和本地 WSL 的 Hermes 核心配置（config、skills、memories、logs）纳入 Git 版本管理，并推送至 GitHub 私有仓库，实现系统重装后的快速恢复。

**背景痛点：** 云端 Hermes 在调试网络环境时容易崩溃，需要 Git 版本来兜底，确保技能、配置、记忆等学习经验不丢失。

**架构概要：** 一个 GitHub 私有仓库，两个长期分支（main = 云端, local = WSL），技能通过 merge 在分支间同步。

---

## 一、前置条件检查

### 云端（已具备 ✅）

| 项目 | 状态 |
|------|------|
| Git 已安装 | ✅ v2.43.0 |
| gh CLI 已安装 | ✅ v2.45.0 |
| GitHub 可达 | ✅ 延迟 ~108ms |
| SSH 免密操作 | 需配置 |

### 本地 WSL（需确认 ❓）

| 项目 | 状态 |
|------|------|
| Git 已安装 | 大概率有 |
| gh CLI 已安装 | 待确认 |
| GitHub 可达 | 待确认 |

---

## 二、要跟踪 vs 排除的内容

### ✅ 跟踪（纳入版本管理）

```
~/.hermes/
├── config.yaml        # 配置（不含 API Key 的版本）
├── skills/            # 学习经验（最重要！84个技能，551个文件）
├── memories/          # 用户记忆
├── logs/              # 崩溃调试用日志（日增量 ~几十 KB）
```

**预估大小：** ≈ 11 MB（Git 压缩后约 2~4 MB）
**日增量：** < 1 MB

### ❌ 排除（不跟踪）

```
.env              # 含 API Key，另存到本地 PC
sessions/         # 会话记录，量大无用
state.db          # 数据库文件，二进制
*.lock            # 锁文件，临时的
```

---

## 三、仓库结构设计

### 分支策略：一个仓库两个分支

```
GitHub: hermione/<用户名>/hermes-dotfiles (私有仓库)
│
├── main           ← 云端环境 (vm-0-13-ubuntu)
│   ├── config.yaml
│   ├── skills/
│   │   ├── devops/remote-machine-access/    # 你刚学的技能
│   │   └── ...
│   ├── memories/
│   ├── logs/
│   ├── .gitignore
│   └── scripts/
│       └── recover.sh        # 重装恢复脚本
│
└── local          ← WSL 环境 (localhost)
    ├── config.yaml
    ├── skills/
    ├── memories/
    ├── logs/
    ├── .gitignore
    └── scripts/
        └── recover.sh
```

### 同步策略

```
云端学到新技能 → git commit (main) → git push
WSL 学到新技能 → git commit (local) → git push

想同步技能到另一环境：
  云端：git merge origin/local   # 把 WSL 学的技能合过来
  WSL： git merge origin/main    # 把云端学的技能合过来
```

---

## 四、分步执行任务

### Task 1：云端创建 GitHub Token

**目标：** 准备一个专用于此仓库的 GitHub Token

**操作：**
1. 打开 https://github.com/settings/tokens → Generate new token (classic)
2. 权限勾选：`repo`（完整私有仓库权限）
3. 作用：仅用于此项目，可随时吊销
4. **Token 保存到本地 PC 安全位置**（密码管理器 / WSL ~/secure/）

**验证：** Token 已保存到本地（不是云端 .env），云端崩了也能从本地拿到。

---

### Task 2：云端初始化 Git 仓库并 Push

**目标：** 在云端 ~/.hermes 目录初始化 Git，推送到 GitHub

**步骤：**

**2.1 创建 .gitignore**
```bash
# 敏感信息
.env
*.lock

# 会话和数据库
sessions/
state.db
state.db-shm
state.db-wal

# 临时文件
gateway.lock
gateway.pid
cache/
image_cache/
audio_cache/
*.json
!channel_directory.json

# 日志（只跟踪当前，不跟踪历史）
logs/curator/
```

**2.2 Git 初始化**
```bash
cd ~/.hermes
git init
git add -A
git status   # 确认没有 .env 等敏感文件
```

**2.3 创建初始 commit**
```bash
git commit -m "chore: init hermes dotfiles backup [cloud]"
```

**2.4 创建 local 分支（为 WSL 准备）**
```bash
git checkout -b local
git commit --allow-empty -m "chore: init local branch for WSL"
git checkout main
```

**2.5 创建 GitHub 仓库并 Push**
```bash
gh auth login
gh repo create hermes-dotfiles --private --push --remote origin
git push --all origin
```

**验证：** GitHub 网页可见 hermes-dotfiles 仓库，main 和 local 两个分支都有内容。

---

### Task 3：本地 WSL 配置并 Push local 分支

**目标：** 在 WSL 中同样初始化，推送到 local 分支

**步骤：**

**3.1 确认本地环境**
```bash
# WSL 终端
git --version
gh --version   # 如果没有，需要安装
```

**3.2 本地 .gitignore（同云端）**
```bash
cat > ~/.hermes/.gitignore << 'EOF'
.env
*.lock
sessions/
state.db
state.db-shm
state.db-wal
gateway.lock
gateway.pid
cache/
image_cache/
audio_cache/
*.json
logs/curator/
EOF
```

**3.3 Git 初始化并关联远程仓库**
```bash
cd ~/.hermes
git init
git add -A
git commit -m "chore: init hermes dotfiles backup [local]"
git remote add origin https://github.com/<用户名>/hermes-dotfiles.git
git fetch origin
git rebase origin/local   # 基于远程 local 分支
git push --set-upstream origin local
```

**验证：** GitHub 仓库的 local 分支下有 WSL 的配置。

---

### Task 4：编写一键恢复脚本

**目标：** 创建 `scripts/recover.sh`，系统重装后可一键恢复

**云端恢复脚本（scripts/recover.sh）：**
```bash
#!/bin/bash
# Hermes 云端恢复脚本
# 系统重装后执行：bash recover.sh

set -e

echo "=== Hermes Dotfiles Recovery ==="

# 检查依赖
command -v git >/dev/null 2>&1 || { echo "❌ Git 未安装"; exit 1; }
command -v gh >/dev/null 2>&1 || { echo "❌ gh CLI 未安装，正在安装..."; sudo apt install gh -y; }

# 检查是否已登录
gh auth status >/dev/null 2>&1 || {
  echo "⚠️  请先登录 GitHub"
  echo "   1. 获取 token（从本地 PC 安全位置）"
  echo "   2. 执行: echo \$TOKEN | gh auth login --with-token"
  exit 1
}

# 备份当前 .hermes（如果有）
[ -d ~/.hermes ] && mv ~/.hermes ~/.hermes.bak.$(date +%Y%m%d_%H%M%S)

# 克隆仓库
gh repo clone <用户名>/hermes-dotfiles ~/.hermes
cd ~/.hermes
git checkout main

# 恢复 .env（手动操作，API Key 不在仓库中）
echo ""
echo "⚠️  .env 需要手动恢复："
echo "   从本地 PC 的 ~/secure/hermes-env 复制过来"
echo "   或参考 .env.example 重新配置"
echo ""
echo "✅ 恢复完成！执行以下命令启动："
echo "   cd ~/.hermes && hermes gateway start"
```

**WSL 恢复脚本（scripts/recover-local.sh）：**
内容类似，将 `git checkout main` 改为 `git checkout local`

---

### Task 5：配置定时自动提交（云端 + WSL）

**目标：** 每天自动 commit + push，防止忘记手动提交

**云端 cronjob：**
```python
# 通过 Hermes cron 创建
cronjob create:
  schedule: "0 3 * * *"     # 每天凌晨 3 点
  prompt: >
    执行以下操作：
    1. cd ~/.hermes
    2. git add -A
    3. git diff --cached --quiet || git commit -m "chore: auto backup $(date +%Y-%m-%d)"
    4. git push origin main
  delivery: "local"
```

**WSL 定时（通过 Windows 任务计划程序或 crontab）：**
```bash
# WSL crontab
0 4 * * * cd ~/.hermes && git add -A && git diff --cached --quiet || git commit -m "chore: auto backup $(date +%Y-%m-%d)" && git push origin local
```

---

### Task 6：配置云端 .env 安全存放

**目标：** 将 .env 内容以安全方式存放在本地 PC

**步骤：**
```bash
# WSL 终端
mkdir -p ~/secure
cp ~/.hermes/.env ~/secure/hermes-env-cloud   # 云端 .env 备份
cp ~/.hermes/.env ~/secure/hermes-env-local   # WSL .env 备份（如果不同）
```

这样云端重装后，从 WSL 的 `~/secure/` 取回 .env 即可。

---

### Task 7：全局验证

**目标：** 确认整套系统工作正常

**验证清单：**
- [ ] GitHub 仓库存在，main + local 两个分支 ✅
- [ ] 云端 config.yaml 无 API Key 泄露 ✅
- [ ] 云端 skills/ 所有 84 个技能已入库 ✅
- [ ] WSL skills/ 已入库 ✅
- [ ] 云端定时 push 正常工作 ✅
- [ ] WSL 定时 push 正常工作 ✅
- [ ] 恢复脚本语法正确 ✅
- [ ] .env 已安全备份到 WSL ~/secure/ ✅

---

## 五、系统重装恢复流程（速查表）

当云端服务器重装后：

```
步骤 | 操作                                         | 参考
─────┼──────────────────────────────────────────────┼────────────────
  1  | 装 Hermes                                    | curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash
  2  | 装 gh                                        | sudo apt install gh -y
  3  | 取 token（从本地 PC 密码管理器 / ~/secure/） | 安全位置
  4  | gh auth login                                | echo $TOKEN | gh auth login --with-token
  5  | 执行恢复脚本                                 | bash ~/scripts/recover.sh
  6  | 恢复 .env                                    | 从本地 ~/secure/hermes-env-cloud 复制
  7  | 启动 Gateway                                 | hermes gateway start
```

**总预计耗时：** 5~10 分钟

---

## 六、注意事项 & 安全提醒

| ⚠️ 事项 | 说明 |
|---------|------|
| **Token 权限最小化** | 只需 `repo` 权限，不要给 `admin` 或 `delete_repo` |
| **.env 永不提交** | 确认 .gitignore 已正确配置 |
| **两个分支不混用** | 云端只 push main，WSL 只 push local |
| **技能同步用 merge** | 不在两个分支手动改同一份技能文件 |
| **日志上限** | 日志文件建议设置轮转（log rotation），避免 git 仓库膨胀 |
| **重装前先 push** | 定期检查 git status，确保没有未 push 的 commit |

---

## 七、后续优化方向（非必须）

| 优化项 | 说明 |
|--------|------|
| SSH 免密 Push | 配置 SSH Key 代替 Token，更安全 |
| GitHub Actions 检查 | 自动检查 .env 是否误提交 |
| 加密备份 .env | 用 GPG 加密后提交到仓库 |
| Telegram 通知 | 每日备份失败时通知你 |