diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index c9d1ff08444c5..b7027973c2ae0 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -22,55 +22,87 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
+      # 1️⃣ Checkout main 分支代码到 ./main 目录
       - uses: actions/checkout@v4
+        with:
+          path: main
+
+      # 2️⃣ Checkout docs 分支到 ./mkdocs 目录
       - uses: actions/checkout@v4
         with:
           ref: docs
           path: mkdocs
-      - run: |
-          mv -f mkdocs/* .
-          mv solution/CONTEST_README.md docs/contest.md
-          mv solution/CONTEST_README_EN.md docs-en/contest.md
-      - name: Configure Git Credentials
+
+      # 3️⃣ 移动竞赛 README 到 mkdocs/docs 结构中
+      - name: Move contest files
         run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          cp main/solution/CONTEST_README.md mkdocs/docs/contest.md
+          cp main/solution/CONTEST_README_EN.md mkdocs/docs-en/contest.md
 
+      # 4️⃣ 安装 Python
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
 
+      # 5️⃣ 设置缓存 Key（按周）
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
 
+      # 6️⃣ 缓存 mkdocs-material 的编译产物
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
+          path: mkdocs/.cache
           restore-keys: |
             mkdocs-material-
-            
+
+      # 7️⃣ 安装依赖
       - name: Install dependencies
+        working-directory: mkdocs
         run: |
           python3 -m pip install --upgrade pip
           python3 -m pip install -r requirements.txt
           python3 -m pip install "mkdocs-material[imaging]"
           sudo apt-get install pngquant
-          
+
+      # 8️⃣ 设置 API token 环境变量
       - name: Set MKDOCS_API_KEYS environment variable
         run: echo "MKDOCS_API_KEYS=${{ secrets.MKDOCS_API_KEYS }}" >> $GITHUB_ENV
 
-      - run: |
+      # 9️⃣ 执行构建
+      - name: Build site
+        working-directory: mkdocs
+        run: |
           python3 main.py
           mkdocs build -f mkdocs.yml
           mkdocs build -f mkdocs-en.yml
+          echo "leetcode.doocs.org" > ./site/CNAME
+
+      # 🔟 提交缓存到 docs 分支
+      - name: Commit cache files back to docs branch
+        working-directory: mkdocs
+        run: |
+          if [ -d ".git" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+            git add .cache/path-map.json || true
+            git add .cache/plugin/git-committers/page-authors.json || true
 
-      - name: Generate CNAME file
-        run: echo "leetcode.doocs.org" > ./site/CNAME
+            if git diff --cached --quiet; then
+              echo "No changes to commit"
+            else
+              git commit -m "chore: update committers and path map [bot]"
+              git push origin HEAD:docs
+            fi
+          else
+            echo "::error ::Git directory not found in mkdocs/. Are you sure checkout was successful?"
+            exit 1
 
+      # 1️⃣1️⃣ 上传构建产物
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./site
+          path: mkdocs/site
 
   deploy:
     needs: build