重要数据同步 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，解析仓库列表和服务器信息。如果配置文件不存在或格式异常，报错并提示用户检查。

---

使用触发词

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

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

---

子命令路由

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

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

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

---

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

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

执行流程

步骤 1：检查前置条件

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

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

• 如果 git 未安装，提示安装方法
• 如果 SSH 连接失败，引导用户配置 SSH 密钥：

  ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
  # 然后手动将公钥添加到服务器 ~/.ssh/authorized_keys
  # 或从旧电脑上 scp 已有密钥对

步骤 2：询问本机路径

询问用户两个路径：

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

步骤 3：克隆仓库

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

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

每个克隆完成后验证：

git -C <路径> log -1 --format="%h %s (%ci)"

步骤 4：重命名 remote

克隆默认创建 origin remote，重命名为 relay（与 skill 规范一致）：

git -C <路径> remote rename origin relay

步骤 5：路径适配

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

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

步骤 6：验证

对每个仓库执行 status 检查，确认一切正常：

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：检查本地状态

对每个仓库执行：

git -C <本机路径> status --short

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

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

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

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

步骤 4：执行拉取

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：检测变更

对每个仓库执行：

git -C <本机路径> status --short
git -C <本机路径> diff --stat

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

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

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：提交并推送

用户确认后，对每个有变更的仓库执行：

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 之间的差距：

# 获取最近的 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 以来的完整变更：

# 每个仓库
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 是最新的

归档前先同步到服务器：

git -C <本机路径> push relay <分支>

步骤 3：打 Tag

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 时，需要在服务器上配置认证：

# 方式一：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：验证归档

# 路径 A 验证（本机直推后）
git -C <本机路径> ls-remote origin --tags | grep <版本号>

# 路径 B 验证（服务器中转后）
ssh root@<服务器IP> "cd /root/git-relay/<仓库>.git && git log --oneline -1 && git tag -l | tail -3"

如果有 GitHub token 可用，额外通过 API 验证：

curl -s -H "Authorization: token <token>" \
  https://api.github.com/repos/mwangxiang/<仓库>/tags | head -20

步骤 6：生成归档报告

=== Data Sync Backup 报告 ===

claude-config:
  版本: v1.1
  Tag 说明: "新增 data-sync skill, windtunnel 更新"
  推送方式: 服务器中转 (路径 B)
  GitHub: mwangxiang/claude-config 验证通过
  变更统计: 15 files, +320 -45 (自 v1.0)
  归档大小: ~2.1 MB (git pack)

knowledge-base:
  版本: v1.0
  Tag 说明: "初始归档：记忆库+skill-factory+SOP"
  推送方式: 服务器中转 (路径 B)
  GitHub: mwangxiang/wangxiang-study-lab 验证通过
  变更统计: 272 files (首次归档)
  归档大小: ~8.5 MB (git pack)

归档历史:
  claude-config: v1.0 (02-20) → v1.1 (02-23) [本次]
  knowledge-base: v1.0 (02-23) [本次, 首次]

建议下一步: 归档完成，GitHub 已保存完整快照。下次累积较多变更后再 backup。

---

子命令四：Status（同步状态）

场景：快速查看各仓库在本机、服务器、GitHub 三个节点的同步状态。

执行流程

步骤 1：收集信息

对每个仓库，并行收集：

# 本机
git -C <本机路径> log -1 --format="%h %s (%ci)"
git -C <本机路径> status --short | wc -l
git -C <本机路径> describe --tags --abbrev=0 2>/dev/null
git -C <本机路径> rev-list --count HEAD 2>/dev/null

# 服务器
ssh -o ConnectTimeout=5 root@<服务器IP> \
  "cd /root/git-relay/<仓库>.git && git log -1 --format='%h %s (%ci)'"

# 对比 hash
LOCAL_HASH=$(git -C <本机路径> log -1 --format="%H")
SERVER_HASH=$(ssh root@<服务器IP> "cd /root/git-relay/<仓库>.git && git log -1 --format='%H'")

步骤 2：判定同步状态

比较 LOCAL_HASH 和 SERVER_HASH
│
├─ 相同 → "已同步"
├─ 本机领先（本机有服务器没有的 commit） → "本机有未推送的变更"
├─ 服务器领先（服务器有本机没有的 commit） → "服务器有更新，需要 pull"
└─ 双方都有对方没有的 commit → "已分叉，需要手动处理"

步骤 3：展示报告

=== Data Sync Status ===

claude-config:
  本机:    abc1234 "sync: 更新skill" (2026-02-23 20:00)
  服务器:  abc1234 "sync: 更新skill" (2026-02-23 20:00)
  同步状态: 已同步
  未提交修改: 0 个文件
  最近 tag: v1.1 (距今 3 commits)

knowledge-base:
  本机:    def5678 "sync: 记忆库" (2026-02-23 19:30)
  服务器:  aaa9999 "sync: 另一台电脑推送" (2026-02-23 21:00)
  同步状态: 服务器有更新，需要 pull
  未提交修改: 2 个文件
  最近 tag: v1.0 (距今 5 commits)

建议下一步:
  → knowledge-base: 先 pull 最新，再处理本地修改
  → 可执行 /data-sync pull 自动处理

---

核心规则

1. 绝不删除本地文件

• 所有 git 操作使用安全模式（--ff-only、不使用 --force）
• pull 冲突时报告给用户，不自动覆盖
• 禁止的命令：git reset --hard、git clean -f、git checkout .、git push --force

2. 增量优先

• git 天然增量传输，日常同步通常 < 1 MB
• 不重复推送未变更的内容
• .gitignore 排除 node_modules、telemetry、debug 等大体积临时文件

3. 服务器是最新最全

• 两台电脑都推到服务器，服务器永远保留最完整的版本
• GitHub 只在大版本时接收推送，可以落后于服务器

4. 先 pull 后 push

• Push 前自动 fetch 检查服务器是否领先
• 如果服务器有本机没有的提交，中止 push 并要求先 pull
• 避免分叉和不必要的合并提交

5. 确认后再执行

• Push 和 Backup 操作展示变更摘要后，等待用户确认
• Pull 如有本地修改，先警告用户
• 大版本 Tag 需要用户确认版本号和说明

6. 敏感信息保护

• 推送前扫描 API key、token、password（正则：(api_key|token|password|secret)\s*[:=]）
• settings.json 中的代理地址可以推送（不含密钥）
• tech-library.md（含 API key）已在 .gitignore 中排除
• GitHub token 不写入任何 tracked 文件

---

错误处理

SSH 连接失败

SSH 连接服务器失败
│
├─ Connection refused（端口未开放或 sshd 未运行）
│   → 提示: "服务器 SSH 端口不可达，请检查服务器状态或防火墙规则"
│   → 如果只是暂时性故障，可以先做本地 commit，稍后再 push
│
├─ Connection timed out（网络不通）
│   → 提示: "网络连接超时，请检查网络或 VPN"
│   → 建议稍后重试
│
├─ Permission denied（密钥认证失败）
│   → 提示: "SSH 认证失败，请检查 ~/.ssh/ 密钥配置"
│   → 引导: ssh-keygen + 将公钥添加到服务器
│
└─ Host key verification failed（首次连接或 IP 变更）
    → 提示: "服务器指纹变更，如确认安全请执行:"
    → ssh-keygen -R <服务器IP>

Git Push 失败

Push 失败
│
├─ rejected (non-fast-forward)
│   → 原因: 服务器有本机没有的提交（另一台电脑推过）
│   → 处理: 先 pull 再 push（强制执行"先pull后push"规则）
│
├─ remote: Repository not found
│   → 原因: bare repo 路径错误或已被删除
│   → 处理: 检查 sync-registry.md 中的路径是否正确
│   → 恢复: ssh 到服务器确认 /root/git-relay/ 下的仓库列表
│
└─ fatal: unable to access (GitHub push)
    → 原因: GitHub 不可达或认证失败
    → 处理: 自动切换到服务器中转推送（路径 B）

Git Pull 冲突

Pull 产生冲突
│
├─ 仅 markdown 文件冲突
│   → 展示冲突内容（<<<< ==== >>>>标记），建议用户手动选择保留哪个版本
│   → markdown 冲突通常是两端同时编辑了同一段落
│   → 解决后: git add <文件> && git commit
│
├─ 配置文件冲突（settings.json、.claude/settings.local.json）
│   → 展示两个版本的差异
│   → 建议保留当前电脑的配置（配置通常是机器特定的）
│   → 保留本机版: git checkout --ours <文件> && git add <文件>
│
└─ 其他文件冲突
    → 报告冲突文件列表和冲突行数
    → 不自动解决，逐个展示差异，交给用户处理

磁盘空间不足

# Push 前检查服务器剩余空间
ssh root@<服务器IP> "df -h /root/git-relay/ | tail -1"

• 如果服务器剩余 < 500 MB，发出警告
• 如果服务器剩余 < 100 MB，阻断 push 并建议清理

网络中断恢复

如果 push 过程中网络中断：

• git push 是原子操作，中断不会破坏远端仓库
• 重新执行相同的 push 命令即可恢复
• 提示用户: "推送被中断，请检查网络后重新执行 /data-sync push"

---

版本标签规范

场景	Tag 格式	示例
首次归档	v1.0	v1.0
常规积累归档	v<主>.<次+1>	v1.1, v1.2
架构变更 / 新增重要模块	v<主+1>.0	v2.0
紧急修复（可选）	v<主>.<次>-hotfix	v1.1-hotfix

打 tag 的时机建议：

• 累积 10+ commits 或 20+ files changed
• 新增了重要 skill
• 记忆库有重大更新
• 电脑迁移前（确保完整备份）

---

扩展：添加新仓库

1. 在服务器上创建 bare repo：

   ssh root@129.211.0.193 "cd /root/git-relay && git init --bare <新仓库名>.git"

2. 在本机添加 relay remote：

   cd <本机项目路径>
   git remote add relay root@129.211.0.193:/root/git-relay/<新仓库名>.git
   git push relay <分支>

3. 在 sync-registry.md 仓库列表中追加一行

4. （可选）在 GitHub 创建对应的私有仓库，在服务器 bare repo 中：

   ssh root@129.211.0.193
   cd /root/git-relay/<新仓库名>.git
   git remote add github https://github.com/mwangxiang/<仓库名>.git

---

与其他 Skill 的配合

• dev-log：大版本归档时，可先用 /dev-log 生成详细的版本文档，再用 /data-sync backup 推送
• distill：蒸馏完新知识后，用 /data-sync push 同步到服务器
• ai-auto-dev：Codex 完成开发后，用 /data-sync push 保存成果
• skill-factory：新 skill 交付部署后，用 /data-sync push 同步到所有设备

---

快速参考卡

/data-sync init     ← 新电脑首次配置（克隆+路径适配）
/data-sync pull     ← 换电脑时，拉取最新
/data-sync push     ← 工作完毕，推送变更（自动对比大版本）
/data-sync backup   ← 里程碑时，归档到 GitHub（打 tag）
/data-sync status   ← 随时查看同步状态