Data Sync

重要数据同步工具。通过云服务器中转站在多台电脑间同步 Claude Code 关键配置（skills、hooks、记忆库、skill-factory），GitHub 作为大版本归档。支持 init/pull/push/backup/status 五个子命令。

# 重要数据同步 Skill（data-sync）

通过云服务器 bare repo 中转，在多台电脑之间增量同步 Claude Code 的关键数据资产，GitHub 作为大版本归档备份。

## 架构

```
电脑A ←──(pull/push)──→ 服务器 relay (最新最全) ←──(pull/push)──→ 电脑B
                              │
                        (backup: 大版本归档)
                              ↓
                           GitHub (私有仓库)
```

- **服务器是唯一中间节点**——两台电脑不直接通信，所有同步经过服务器
- **GitHub 是归档层**——不参与日常同步，只在大版本时接收推送
- **本机数据永远安全**——所有操作只增不删，不使用任何破坏性 git 命令

---

## 配置

仓库注册表和服务器信息存放在独立文件中，添加/修改仓库无需编辑本 SKILL.md：

**配置文件**：[sync-registry.md](sync-registry.md)（与本文件同目录）

读取方式：执行前先读取 `sync-registry.md`，解析仓库列表和服务器信息。如果配置文件不存在或格式异常，报错并提示用户检查。

---

## 使用触发词

用户说以下任一触发词时启动本 skill：

- `/data-sync`
- "同步数据" / "拉取同步" / "推送同步" / "数据备份" / "同步状态"

---

## 子命令路由

启动后，首先判断用户意图，路由到对应子命令：

```
用户请求进来
│
├─ "init" / "初始化" / "新电脑配置"
│   → Init 子命令（新电脑首次配置）
│
├─ "pull" / "拉取" / "同步到本机" / 未指定（默认）
│   → Pull 子命令
│
├─ "push" / "推送" / "上传"
│   → Push 子命令
│
├─ "backup" / "归档" / "大版本" / "推到GitHub"
│   → Backup 子命令
│
└─ "status" / "状态" / "检查"
    → Status 子命令
```

如果用户意图不明确，展示子命令菜单让用户选择。

---

## 子命令零：Init（新电脑初始化）

**场景**：新电脑首次使用，需要从服务器克隆全部仓库并配置环境。

### 执行流程

**步骤 1：检查前置条件**

```bash
# 检查 git 是否安装
git --version

# 检查 SSH 连接
ssh -o ConnectTimeout=5 root@<服务器IP> "echo ok"
```

- 如果 git 未安装，提示安装方法
- 如果 SSH 连接失败，引导用户配置 SSH 密钥：
  ```bash
  ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
  # 然后手动将公钥添加到服务器 ~/.ssh/authorized_keys
  # 或从旧电脑上 scp 已有密钥对
  ```

**步骤 2：询问本机路径**

询问用户两个路径：
- `.claude` 配置目录（默认 `~/.claude`，通常不需要改）
- 学习工作库目录（用户指定项目根路径）

**步骤 3：克隆仓库**

按 `sync-registry.md` 中的仓库列表逐个克隆：

```bash
git clone root@<服务器IP>:/root/git-relay/claude-config.git <.claude路径>
git clone root@<服务器IP>:/root/git-relay/claude-knowledge-base.git <学习工作库路径>
```

每个克隆完成后验证：
```bash
git -C <路径> log -1 --format="%h %s (%ci)"
```

**步骤 4：重命名 remote**

克隆默认创建 `origin` remote，重命名为 `relay`（与 skill 规范一致）：
```bash
git -C <路径> remote rename origin relay
```

**步骤 5：路径适配**

自动检测并提示需要修改的绝对路径：

1. 读取 `<.claude路径>/CLAUDE.md`，列出其中所有硬编码路径
2. 提示用户将旧路径替换为新电脑的实际路径
3. 检查 `settings.json` 中的代理端口是否需要更新

**步骤 6：验证**

对每个仓库执行 status 检查，确认一切正常：
```bash
git -C <路径> remote -v         # 确认 relay remote
git -C <路径> log -1 --oneline  # 确认有内容
git -C <路径> status --short    # 确认干净状态
```

**步骤 7：生成 Init 报告**

```
=== Data Sync Init 报告 ===

环境:
  Git: v2.43.7
  SSH: root@129.211.0.193 连接正常

仓库:
  claude-config:
    路径: C:\Users\新用户\.claude
    Remote: relay → 129.211.0.193:/root/git-relay/claude-config.git
    最新提交: 6955b12 "migration: full state backup" (2026-02-23)
    状态: 就绪

  knowledge-base:
    路径: D:\项目\VScode辅助工作学习
    Remote: relay → 129.211.0.193:/root/git-relay/claude-knowledge-base.git
    最新提交: 857b757 "migration: full knowledge base backup" (2026-02-23)
    状态: 就绪

待办:
  → 请检查 CLAUDE.md 中的路径引用是否正确
  → 请确认 settings.json 中的代理端口

初始化完成。可以开始使用 /data-sync pull 和 push 了。
```

---

## 子命令一：Pull（拉取同步）

**场景**：切换到另一台电脑开始工作前，拉取最新内容。

### 执行流程

**步骤 1：环境检测**

对 `sync-registry.md` 中的每个仓库：
1. 检查本机路径是否存在（不存在 → 提示用户先执行 `init`）
2. 检查是否有 `relay` remote 配置（没有 → 报错并提示配置命令）
3. 检查 SSH 连接到服务器是否正常（失败 → 见"错误处理"章节）
4. 如有异常，报告并询问用户是否继续

**步骤 2：检查本地状态**

对每个仓库执行：
```bash
git -C <本机路径> status --short
```

- 如果有未提交的本地修改，**警告用户**并提供选项：
  - (a) 先执行 Push 子命令提交本地修改（推荐）
  - (b) `git stash` 暂存后再 pull，pull 完后 `git stash pop`
  - (c) 忽略警告，直接 pull（可能产生冲突）

**步骤 3：先检查是否有更新**

```bash
git -C <本机路径> fetch relay <分支>
git -C <本机路径> log HEAD..relay/<分支> --oneline
```

- 如果没有新提交，报告"已是最新"并跳过
- 如果有新提交，展示变更概览后继续

**步骤 4：执行拉取**

```bash
git -C <本机路径> pull relay <分支> --ff-only
```

- 使用 `--ff-only` 防止意外合并冲突
- 如果 fast-forward 失败（有分叉），报告给用户并提供选项：
  - (a) `git pull relay <分支> --rebase`（推荐，保持线性历史）
  - (b) `git pull relay <分支>`（允许合并提交）
  - (c) 跳过此仓库

**步骤 5：生成报告**

```
=== Data Sync Pull 报告 ===

claude-config:
  状态: 已更新
  更新: 3 files changed (+45, -12)
  最新提交: abc1234 "sync: skill迭代" (2026-02-23)

knowledge-base:
  状态: 已是最新（无更新）

建议下一步: 本机已同步到最新，可以开始工作。工作完毕后执行 /data-sync push。
```

---

## 子命令二：Push（推送同步 + 版本对比）

**场景**：在当前电脑完成工作后，推送变更到服务器。

### 执行流程

**步骤 1：检测变更**

对每个仓库执行：
```bash
git -C <本机路径> status --short
git -C <本机路径> diff --stat
```

- 列出所有修改、新增、删除的文件
- 如果没有变更，跳过该仓库并报告"无变更"

**步骤 2：检查服务器是否领先**

```bash
git -C <本机路径> fetch relay <分支>
git -C <本机路径> log HEAD..relay/<分支> --oneline
```

- 如果服务器有本机没有的提交（另一台电脑推过），**中止 push**：
  > "服务器有更新（来自另一台电脑），请先执行 /data-sync pull 再 push。"
- 这是"先 pull 后 push"规则的强制执行

**步骤 3：展示变更摘要**

```
claude-config 变更:
  修改: skills/ai-auto-dev/skill.md
  新增: skills/data-sync/SKILL.md
  共 2 个文件

knowledge-base 变更:
  修改: Claude Code辅助学习记忆库.md
  修改: 思维蒸馏.md
  共 2 个文件
```

**步骤 4：安全检查**

扫描变更文件，检查以下项目：

| 检查项 | 级别 | 处理 |
|--------|------|------|
| 文件内容匹配 `(api_key\|token\|password\|secret)\s*[:=]` | 阻断 | 必须确认或排除后才能继续 |
| `.env` 文件被 staged | 阻断 | 提示加入 `.gitignore` |
| 单个文件 > 5MB | 警告 | 展示文件名和大小，用户确认 |
| `node_modules/` 被 staged | 阻断 | 检查 `.gitignore` 是否缺失规则 |
| `.gitignore` 没有排除常见临时文件 | 警告 | 建议添加规则 |

**步骤 5：提交并推送**

用户确认后，对每个有变更的仓库执行：
```bash
git -C <本机路径> add -A
git -C <本机路径> commit -m "sync: <自动生成的变更摘要>"
git -C <本机路径> push relay <分支>
```

Commit message 格式：`sync: <日期> <变更文件数>个文件 (<主要变更简述>)`
示例：`sync: 2026-02-23 4 files (skill迭代+记忆库更新)`

**步骤 6：与 GitHub 大版本对比**

推送完成后，自动对比当前状态与 GitHub 最近 tag 之间的差距：

```bash
# 获取最近的 tag
git -C <本机路径> describe --tags --abbrev=0 2>/dev/null

# 如果有 tag，统计差距
git -C <本机路径> log <最近tag>..HEAD --oneline
git -C <本机路径> diff --stat <最近tag>..HEAD
```

**版本对比判定逻辑**：

```
获取最近 tag
│
├─ 无 tag
│   → 提示: "尚无大版本归档，建议执行 /data-sync backup 打 v1.0"
│
├─ 自上次 tag 以来 < 5 commits 且 < 10 files changed
│   → 提示: "变更较少，暂不需要归档"
│
├─ 自上次 tag 以来 5-15 commits 或 10-20 files changed
│   → 提示: "变更适中，可考虑归档"
│
└─ 自上次 tag 以来 > 15 commits 或 > 20 files changed
    → 强烈建议: "变更较多，建议尽快执行 /data-sync backup"
```

**步骤 7：生成推送报告**

```
=== Data Sync Push 报告 ===

claude-config:
  提交: abc1234 "sync: 2026-02-23 2 files (新增data-sync skill)"
  推送: relay/master 成功
  传输量: ~15 KB (增量)
  距上次大版本: +8 commits, 15 files changed → 建议归档

knowledge-base:
  提交: def5678 "sync: 2026-02-23 2 files (记忆库+蒸馏更新)"
  推送: relay/master 成功
  传输量: ~3 KB (增量)
  距上次大版本: 无 tag → 建议打 v1.0

建议下一步:
  → 两个仓库都有较多未归档变更，建议执行 /data-sync backup
  → 或继续工作，下次再归档
```

---

## 子命令三：Backup（大版本归档到 GitHub）

**场景**：累积了较多变更，或达到里程碑，需要完整归档到 GitHub。

### 执行流程

**步骤 1：确认归档范围**

展示各仓库自上次 tag 以来的完整变更：

```bash
# 每个仓库
git -C <本机路径> describe --tags --abbrev=0 2>/dev/null
git -C <本机路径> log <最近tag>..HEAD --oneline  # 或 git log --oneline（无tag时）
git -C <本机路径> diff --stat <最近tag>..HEAD
```

询问用户：
- 归档哪些仓库（全部 / 选择性）
- 版本号（自动建议下一个版本号，用户可修改）
- 版本说明（一句话概括本次归档的主要内容）

**版本号自动建议逻辑**：
```
获取最近 tag
│
├─ 无 tag → 建议 v1.0
├─ 最近 tag 是 vX.Y
│   ├─ 有新增 skill 或重大模块 → 建议 vX.(Y+1)
│   └─ 仅小改 → 建议 vX.(Y+1)
└─ 用户可手动指定任意版本号
```

**步骤 2：确保 relay 是最新的**

归档前先同步到服务器：
```bash
git -C <本机路径> push relay <分支>
```

**步骤 3：打 Tag**

```bash
git -C <本机路径> tag -a <版本号> -m "<版本说明>"
git -C <本机路径> push relay <分支> --tags
```

Tag 命名规范：`v<主版本>.<次版本>`
- 新增重要内容（新 skill、新蒸馏主题）→ 次版本 +1
- 架构大调整 → 主版本 +1

**步骤 4：推送到 GitHub（自动选择路径）**

```
检测 GitHub 连通性
│
├─ 本机能连 GitHub（curl --max-time 5 https://api.github.com）
│   → 路径 A：本机直推
│   git -C <本机路径> push origin <分支> --tags
│   （如果没有 origin remote，自动添加）
│
└─ 本机不能连 GitHub（超时或拒绝）
    → 路径 B：服务器中转推
    ssh root@<服务器IP> "cd /root/git-relay/<仓库>.git && git push github --mirror"
    │
    ├─ 成功 → 继续
    └─ 失败（服务器未配置 GitHub credential）
        → 引导配置：
        ssh root@<服务器IP>
        cd /root/git-relay/<仓库>.git
        git remote set-url github https://<token>@github.com/mwangxiang/<仓库>.git
        # 或配置 credential helper
```

**服务器端 GitHub Credential 配置说明**：

首次通过服务器中转推送 GitHub 时，需要在服务器上配置认证：

```bash
# 方式一：URL 内嵌 token（简单但 token 明文存储）
ssh root@<服务器IP>
cd /root/git-relay/<仓库>.git
git remote set-url github https://mwangxiang:<GitHub_PAT>@github.com/mwangxiang/<仓库>.git

# 方式二：git credential store（token 存文件，稍安全）
ssh root@<服务器IP>
git config --global credential.helper store
# 首次 push 时输入用户名和 token，之后自动记住
```

获取 GitHub Personal Access Token：GitHub Settings → Developer settings → Personal access tokens → 创建，勾选 `repo` 权限。

**步骤 5：验证归档**

```bash
# 路径 A 验证（本机直推后）
git -C <本机路径>