data-sync

# 重要数据同步 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 <本机路径> 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 验证： ```bash 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：收集信息** 对每个仓库，并行收集： ```bash # 本机 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 <文件> │ └─ 其他文件冲突 → 报告冲突文件列表和冲突行数 → 不自动解决，逐个展示差异，交给用户处理 ``` ### 磁盘空间不足 ```bash # 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： ```bash ssh root@129.211.0.193 "cd /root/git-relay && git init --bare <新仓库名>.git" ``` 2. 在本机添加 relay remote： ```bash 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 中： ```bash 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 ← 随时查看同步状态 ```