---

name: data-sync description: "重要資料同步工具。通過雲伺服器中轉站在多臺電腦間同步 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，解析倉庫列表和伺服器資訊。如果配置檔案不存在或格式異常，報錯並提示使用者檢查。

---

使用觸發詞

使用者說以下任一觸發詞時啟動本 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 金鑰： bash 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 配置說明：

來源於7w4.net。

首次通過伺服器中轉推送 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： 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   ← 隨時檢視同步狀態

這個工具能有效解決多臺電腦間同步 Claude Code 配置的問題，流程設計清晰，錯誤提示友好，安全檢查機制也比較完善。但對普通使用者而言配置過程稍顯複雜，需要理解伺服器和 GitHub 等概念，裝置間同步時偶爾出現的衝突也需要手動處理。整體質量良好，適合有技術基礎的使用者使用。