Merge pull request 'sync: d8d-skills-sync 双向同步（先拉后推）' (#4) from sync/d8d-skills-20260408-024009 into master

Reviewed-on: http://gitea.d8d.fun/d8dfun/bmad-method-template/pulls/4

.claude/skills/d8d-skills-sync/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: d8d-skills-sync
-description: '将项目中 .claude/skills/ 下所有 d8d-* 技能目录（d8d-dev、d8d-requirements、d8d-prototype、d8d-skills-sync 等）的修改同步到 bmad-method-template 模板仓库并创建 PR。使用场景：修改了 .claude/skills/ 下任何 d8d-* 目录的文件后，需要将改动同步到上游模板仓库时触发。触发词：同步技能、提PR、sync skill、更新模板。'
+description: '将项目中 .claude/skills/ 下所有 d8d-* 技能目录（d8d-dev、d8d-requirements、d8d-prototype、d8d-skills-sync 等）的修改同步到 bmad-method-template 模板仓库并创建 PR。双向同步：先拉取模板更新到项目，再推送项目变更到模板。使用场景：修改了 .claude/skills/ 下任何 d8d-* 目录的文件后，需要将改动同步到上游模板仓库时触发。触发词：同步技能、提PR、sync skill、更新模板。'
 ---
 
-# D8D Skills Sync — 技能变更同步到模板仓库
+# D8D Skills Sync — 技能变更双向同步
 
-将项目 `.claude/skills/` 下所有 `d8d-*` 目录的修改同步到 `https://gitea.d8d.fun/d8dfun/bmad-method-template` 并创建 PR。
+将项目 `.claude/skills/` 下所有 `d8d-*` 目录与 `https://gitea.d8d.fun/d8dfun/bmad-method-template` 双向同步。
 
 同步范围：所有匹配 `d8d-*/` 的技能目录（包括 d8d-dev、d8d-requirements、d8d-prototype、d8d-skills-sync 自身等）
 
@@ -26,28 +26,66 @@ Gitea 认证信息从项目 git remote URL 提取（oauth2 token 在 remote URL
 
 ```bash
 if [ -d /tmp/bmad-method-template ]; then
-  cd /tmp/bmad-method-template && git pull
+  cd /tmp/bmad-method-template && git checkout master && git pull
 else
   git clone https://gitea.d8d.fun/d8dfun/bmad-method-template.git /tmp/bmad-method-template
 fi
 ```
 
-### Step 2: 检测变更
+### Step 2: 双向检测差异
 
-对每个 `d8d-*` 技能目录逐一对比（自动发现，不硬编码）：
+对比项目 vs 模板 master，分类差异：
 
 ```bash
-# 动态扫描项目中所有 d8d-* 技能目录
-for skill_dir in {PROJECT_ROOT}/.claude/skills/d8d-*/; do
+PROJECT_ROOT={项目根目录}
+
+echo "=== A) 项目有而模板无（需推到模板）==="
+for skill_dir in $PROJECT_ROOT/.claude/skills/d8d-*/; do
   skill=$(basename $skill_dir)
-  diff -rq $skill_dir /tmp/bmad-method-template/.claude/skills/$skill/ 2>/dev/null || true
+  if [ -d /tmp/bmad-method-template/.claude/skills/$skill ]; then
+    diff -rq $skill_dir /tmp/bmad-method-template/.claude/skills/$skill/ 2>/dev/null || true
+  else
+    echo "  NEW in project: $skill/"
+  fi
+done
+
+echo "=== B) 模板有而项目无（需先拉到项目）==="
+for skill_dir in /tmp/bmad-method-template/.claude/skills/d8d-*/; do
+  skill=$(basename $skill_dir)
+  if [ -d $PROJECT_ROOT/.claude/skills/$skill ]; then
+    diff -rq $skill_dir $PROJECT_ROOT/.claude/skills/$skill/ 2>/dev/null || true
+  else
+    echo "  NEW in template: $skill/"
+  fi
 done
 ```
 
-- 如果无差异 → 告知用户"所有 d8d-* 技能文件已是最新，无需同步"
-- 如果有差异 → 列出变更文件清单，继续 Step 3
+如果 A 和 B 都为空 → 告知用户"已是最新，无需同步"。
+如果 B 不为空 → 必须先执行 Step 2.5。
 
-### Step 3: 创建分支并同步
+### Step 2.5: 拉取模板独有更新到项目（⛔ 不可跳过）
+
+⛔ 模板 master 可能有项目没有的更新（其他项目 sync 上去的）。必须先拉取，否则推送时会回退模板的更新。
+
+对 B 类差异文件逐一处理：
+
+1. **模板独有新增内容**（如新增 § 节、新增文件）：
+   ```bash
+   cp /tmp/bmad-method-template/.claude/skills/$skill/$file $PROJECT_ROOT/.claude/skills/$skill/$file
+   ```
+
+2. **双方都修改了同一文件**：
+   - 用 `diff` 查看具体差异
+   - 保留项目独有修改 + 追加模板独有新增内容
+   - ⛔ 不可直接覆盖，需手动合并
+
+3. 拉取完成后提交：
+   ```bash
+   git add .claude/skills/d8d-*/ && git commit -m "chore(skill): 从模板拉取更新 — {摘要}"
+   git push
+   ```
+
+### Step 3: 创建分支并同步项目变更到模板
 
 ```bash
 cd /tmp/bmad-method-template
@@ -56,7 +94,7 @@ git checkout master && git pull
 git checkout -b $BRANCH_NAME
 
 # 同步所有 d8d-* 技能目录（自动发现）
-for skill_dir in {PROJECT_ROOT}/.claude/skills/d8d-*/; do
+for skill_dir in $PROJECT_ROOT/.claude/skills/d8d-*/; do
   skill=$(basename $skill_dir)
   mkdir -p .claude/skills/$skill/
   cp -r $skill_dir* .claude/skills/$skill/
@@ -67,6 +105,7 @@ done
 
 ```bash
 git add .claude/skills/d8d-*/
+git diff --cached --stat  # 确认只有项目独有的变更
 git commit -m "sync: {简要描述变更内容}"
 ```
 
@@ -97,4 +136,5 @@ curl -X POST "${TEMPLATE_REPO_API}/pulls" \
 ### Step 6: 验证
 
 - 确认 API 返回 `html_url`（PR 链接）
+- 确认 PR 的 diff 只包含项目独有的新增（无模板内容回退）
 - 输出 PR URL 给用户