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

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

架构

CODEBLOCK0

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

---

配置

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

配置文件：sync-registry.md（与本文件同目录）

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

---

使用触发词

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

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

---

子命令路由

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

CODEBLOCK1

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

---

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

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

执行流程

步骤 1：检查前置条件

CODEBLOCK2

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

CODEBLOCK3

步骤 2：询问本机路径

询问用户两个路径：

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

步骤 3：克隆仓库

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

CODEBLOCK4

每个克隆完成后验证：
CODEBLOCK5

步骤 4：重命名 remote

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

步骤 5：路径适配

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

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

步骤 6：验证

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

步骤 7：生成 Init 报告

CODEBLOCK8

---

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

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

执行流程

步骤 1：环境检测

对 sync-registry.md 中的每个仓库：

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

步骤 2：检查本地状态

对每个仓库执行：
CODEBLOCK9

• - 如果有未提交的本地修改，警告用户并提供选项：

- (a) 先执行 Push 子命令提交本地修改（推荐） - (b) git stash 暂存后再 pull，pull 完后 git stash pop - (c) 忽略警告，直接 pull（可能产生冲突）

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

CODEBLOCK10

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

步骤 4：执行拉取

CODEBLOCK11

• - 使用 --ff-only 防止意外合并冲突
• 如果 fast-forward 失败（有分叉），报告给用户并提供选项：

- (a) git pull relay <分支> --rebase（推荐，保持线性历史） - (b) git pull relay <分支>（允许合并提交） - (c) 跳过此仓库

步骤 5：生成报告

CODEBLOCK12

---

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

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

执行流程

步骤 1：检测变更

对每个仓库执行：
CODEBLOCK13

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

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

CODEBLOCK14

• - 如果服务器有本机没有的提交（另一台电脑推过），中止 push：

> "服务器有更新（来自另一台电脑），请先执行 /data-sync pull 再 push。"

• - 这是"先 pull 后 push"规则的强制执行

步骤 3：展示变更摘要

CODEBLOCK15

步骤 4：安全检查

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

检查项	级别	处理
文件内容匹配 INLINECODE17	阻断	必须确认或排除后才能继续
INLINECODE18 文件被 staged

阻断 | 提示加入 .gitignore |
| 单个文件 > 5MB | 警告 | 展示文件名和大小，用户确认 |
| node_modules/ 被 staged | 阻断 | 检查 .gitignore 是否缺失规则 |
| .gitignore 没有排除常见临时文件 | 警告 | 建议添加规则 |

步骤 5：提交并推送

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

Commit message 格式：sync: <日期> <变更文件数>个文件 (<主要变更简述>)
示例：INLINECODE24

步骤 6：与 GitHub 大版本对比

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

CODEBLOCK17

版本对比判定逻辑：

CODEBLOCK18

步骤 7：生成推送报告

CODEBLOCK19

---

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

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

执行流程

步骤 1：确认归档范围

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

CODEBLOCK20

询问用户：

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

版本号自动建议逻辑：
CODEBLOCK21

步骤 2：确保 relay 是最新的

归档前先同步到服务器：
CODEBLOCK22

步骤 3：打 Tag

CODEBLOCK23

Tag 命名规范：v<主版本>.<次版本>

• - 新增重要内容（新 skill、新蒸馏主题）→ 次版本 +1
• 架构大调整 → 主版本 +1

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

CODEBLOCK24

服务器端 GitHub Credential 配置说明：

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

CODEBLOCK25

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

步骤 5：验证归档

CODEBLOCK26

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

步骤 6：生成归档报告

CODEBLOCK28

---

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

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

执行流程

步骤 1：收集信息

对每个仓库，并行收集：

CODEBLOCK29

步骤 2：判定同步状态

CODEBLOCK30

步骤 3：展示报告

CODEBLOCK31

---

核心规则

1. 绝不删除本地文件

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

2. 增量优先

• - git 天然增量传输，日常同步通常 < 1 MB
• 不重复推送未变更的内容
• INLINECODE33 排除 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*[:=]）
• INLINECODE36 中的代理地址可以推送（不含密钥）
• INLINECODE37（含 API key）已在 .gitignore 中排除
• GitHub token 不写入任何 tracked 文件

---

错误处理

SSH 连接失败

CODEBLOCK32

Git Push 失败

CODEBLOCK33

Git Pull 冲突

CODEBLOCK34

磁盘空间不足

CODEBLOCK35

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

网络中断恢复

如果 push 过程中网络中断：

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

---

版本标签规范

场景	Tag 格式	示例
首次归档	INLINECODE39	INLINECODE40
常规积累归档

v<主>.<次+1> | v1.1, v1.2 |
| 架构变更 / 新增重要模块 | v<主+1>.0 | v2.0 |
| 紧急修复（可选） | v<主>.<次>-hotfix | v1.1-hotfix |

打 tag 的时机建议：

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

---

扩展：添加新仓库

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

CODEBLOCK36

1. 2. 在本机添加 relay remote：

CODEBLOCK37

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

1. 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 同步到所有设备

---

快速参考卡

CODEBLOCK39