From 3c3597285268be8a94b67d2c5ed2b8b85d68269c Mon Sep 17 00:00:00 2001
From: beijingzyl <1772066848@qq.com>
Date: Sat, 6 Dec 2025 21:21:31 +0100
Subject: [PATCH 1/7] fix precommit

---
 .github/workflows/pre-commit.yml | 41 ++++++++++++++++++++++++++++++++
 workflow/envs/environment.yaml   |  1 +
 2 files changed, 42 insertions(+)
 create mode 100644 .github/workflows/pre-commit.yml

diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
new file mode 100644
index 00000000..534f3f30
--- /dev/null
+++ b/.github/workflows/pre-commit.yml
@@ -0,0 +1,41 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - develop
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch full history for diff comparison
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+      - name: Cache pre-commit hooks
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: |
+            pre-commit-${{ runner.os }}-
+      - name: Install pre-commit
+        run: pip install pre-commit
+      - name: Run pre-commit on changed files
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            # For PRs, compare against base branch
+            pre-commit run --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.sha }}
+          elif [ -n "${{ github.event.before }}" ] && [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
+            # For pushes, compare against previous commit
+            pre-commit run --from-ref ${{ github.event.before }} --to-ref ${{ github.sha }}
+          else
+            # Fallback: check all files if we can't determine the diff
+            pre-commit run --all-files
+          fi
+
diff --git a/workflow/envs/environment.yaml b/workflow/envs/environment.yaml
index 6535e3f1..402b078f 100644
--- a/workflow/envs/environment.yaml
+++ b/workflow/envs/environment.yaml
@@ -74,3 +74,4 @@ dependencies:
     - mkdocs-awesome-nav
     - mike>=1.1.0
     - python-markdown-math
+    - pre-commit>=4.0.0

From 2d0466e056690cd35993fc61c545a3617b7458d6 Mon Sep 17 00:00:00 2001
From: beijingzyl <1772066848@qq.com>
Date: Sat, 6 Dec 2025 21:37:56 +0100
Subject: [PATCH 2/7] fix precommit

---
 .github/workflows/pre-commit.yml | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
index 534f3f30..bdf5839e 100644
--- a/.github/workflows/pre-commit.yml
+++ b/.github/workflows/pre-commit.yml
@@ -27,13 +27,18 @@ jobs:
       - name: Install pre-commit
         run: pip install pre-commit
       - name: Run pre-commit on changed files
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.sha }}
+          BEFORE_SHA: ${{ github.event.before }}
         run: |
-          if [ "${{ github.event_name }}" == "pull_request" ]; then
+          if [ "$EVENT_NAME" == "pull_request" ]; then
             # For PRs, compare against base branch
-            pre-commit run --from-ref ${{ github.event.pull_request.base.sha }} --to-ref ${{ github.sha }}
-          elif [ -n "${{ github.event.before }}" ] && [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
+            pre-commit run --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA"
+          elif [ -n "$BEFORE_SHA" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
             # For pushes, compare against previous commit
-            pre-commit run --from-ref ${{ github.event.before }} --to-ref ${{ github.sha }}
+            pre-commit run --from-ref "$BEFORE_SHA" --to-ref "$HEAD_SHA"
           else
             # Fallback: check all files if we can't determine the diff
             pre-commit run --all-files

From eef23b8628545e2ab37fb125e2ed77a2b0c510bd Mon Sep 17 00:00:00 2001
From: beijingzyl <1772066848@qq.com>
Date: Sat, 6 Dec 2025 21:44:36 +0100
Subject: [PATCH 3/7] fix precommit

---
 .github/workflows/pre-commit.yml | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
index bdf5839e..a67ece74 100644
--- a/.github/workflows/pre-commit.yml
+++ b/.github/workflows/pre-commit.yml
@@ -35,12 +35,20 @@ jobs:
         run: |
           if [ "$EVENT_NAME" == "pull_request" ]; then
             # For PRs, compare against base branch
-            pre-commit run --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA"
+            pre-commit run --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA" || EXIT_CODE=$?
           elif [ -n "$BEFORE_SHA" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
             # For pushes, compare against previous commit
-            pre-commit run --from-ref "$BEFORE_SHA" --to-ref "$HEAD_SHA"
+            pre-commit run --from-ref "$BEFORE_SHA" --to-ref "$HEAD_SHA" || EXIT_CODE=$?
           else
             # Fallback: check all files if we can't determine the diff
-            pre-commit run --all-files
+            pre-commit run --all-files || EXIT_CODE=$?
           fi
 
+          # Check if any files were modified by pre-commit
+          if git diff --exit-code; then
+            exit ${EXIT_CODE:-0}
+          else
+            echo "❌ Files were modified by pre-commit hooks. Please run 'pre-commit run --all-files' locally and commit the changes."
+            git diff
+            exit 1
+          fi

From cae954a45b73b6ea5862939faae35e91c8e0655b Mon Sep 17 00:00:00 2001
From: beijingzyl <1772066848@qq.com>
Date: Sat, 6 Dec 2025 22:03:10 +0100
Subject: [PATCH 4/7] fix precommit

---
 CONTRIBUTING.md | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1e453650..09cf3da6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -99,16 +99,27 @@ pip install pytest pytest-cov black flake8
 
 ### Submitting a Pull Request
 
-1. **Push your branch** to your fork:
+1. **Ensure pre-commit checks pass** (Important!)
+   ```bash
+   # Run pre-commit on all files
+   pre-commit run --all-files
+   
+   # Or run on specific files
+   pre-commit run --files path/to/your/files
+   ```
+   
+   The pre-commit checks will automatically run in CI, but running them locally first saves time.
+
+2. **Push your branch** to your fork:
    ```bash
    git push origin feature/your-feature-name
    ```
 
-2. **Open a Pull Request** on GitHub
-3. **Fill out the PR template** completely
-4. **Link related issues** using keywords like "Closes #123"
-5. **Wait for review** and address any feedback
-6. **Ensure CI checks pass**
+3. **Open a Pull Request** on GitHub
+4. **Fill out the PR template** completely
+5. **Link related issues** using keywords like "Closes #123"
+6. **Wait for review** and address any feedback
+7. **Ensure CI checks pass** - All checks (including pre-commit) must pass before the PR can be merged
 
 ## Coding Standards
 

From 24e795fade1503c067f1b7a9fd08ba6bf974bc85 Mon Sep 17 00:00:00 2001
From: beijingzyl <1772066848@qq.com>
Date: Sat, 6 Dec 2025 22:19:03 +0100
Subject: [PATCH 5/7] fix precommit

---
 CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 09cf3da6..6fb8c478 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -103,11 +103,11 @@ pip install pytest pytest-cov black flake8
    ```bash
    # Run pre-commit on all files
    pre-commit run --all-files
-   
+
    # Or run on specific files
    pre-commit run --files path/to/your/files
    ```
-   
+
    The pre-commit checks will automatically run in CI, but running them locally first saves time.
 
 2. **Push your branch** to your fork:

From 1c87cd19dba4d844c609556d1f00145d607239d2 Mon Sep 17 00:00:00 2001
From: beijingzyl <1772066848@qq.com>
Date: Thu, 11 Dec 2025 11:34:21 +0100
Subject: [PATCH 6/7] fix precommit file changed

---
 .github/workflows/check-precommit-applied.yml | 96 +++++++++++++++++++
 .github/workflows/pre-commit.yml              | 54 -----------
 .pre-commit-config.yaml                       | 15 ++-
 3 files changed, 107 insertions(+), 58 deletions(-)
 create mode 100644 .github/workflows/check-precommit-applied.yml
 delete mode 100644 .github/workflows/pre-commit.yml

diff --git a/.github/workflows/check-precommit-applied.yml b/.github/workflows/check-precommit-applied.yml
new file mode 100644
index 00000000..521faf66
--- /dev/null
+++ b/.github/workflows/check-precommit-applied.yml
@@ -0,0 +1,96 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - develop
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checkout full repo history to ensure diff calculation works
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      # Cache pre-commit environments
+      - name: Cache pre-commit hooks
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: |
+            pre-commit-${{ runner.os }}-
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Run pre-commit on diff
+        id: run_precommit
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.sha }}
+          BEFORE_SHA: ${{ github.event.before }}
+        run: |
+          set -e
+
+          echo "🔍 Determining diff range..."
+
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            FROM_REF="$BASE_SHA"
+            TO_REF="$HEAD_SHA"
+            echo "PR event: checking diff from $FROM_REF to $TO_REF"
+          elif [ -n "$BEFORE_SHA" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
+            FROM_REF="$BEFORE_SHA"
+            TO_REF="$HEAD_SHA"
+            echo "Push event: checking diff from $FROM_REF to $TO_REF"
+          else
+            # Edge case: unknown base; check all files
+            echo "⚠️  Unable to determine diff automatically — running on all files."
+            set +e
+            pre-commit run --all-files
+            EXIT_CODE=$?
+            set -e
+            echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Run pre-commit on diff
+          set +e
+          pre-commit run --from-ref "$FROM_REF" --to-ref "$TO_REF"
+          EXIT_CODE=$?
+          set -e
+
+          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+
+      - name: Check for uncommitted changes from pre-commit
+        run: |
+          if ! git diff --quiet; then
+            echo "❌ pre-commit hooks modified files."
+            echo "   Please run the following locally:"
+            echo ""
+            echo "       pre-commit install"
+            echo "       pre-commit run --all-files"
+            echo ""
+            echo "   Then commit and push the changes."
+            echo ""
+            git diff --color
+            exit 1
+          fi
+
+          echo "✔️ No changes detected. pre-commit checks passed."
+
+      - name: Fail if hooks returned errors
+        if: steps.run_precommit.outputs.exit_code != '0'
+        run: |
+          echo "❌ pre-commit hooks reported issues."
+          exit 1
diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
deleted file mode 100644
index a67ece74..00000000
--- a/.github/workflows/pre-commit.yml
+++ /dev/null
@@ -1,54 +0,0 @@
-name: pre-commit
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-      - develop
-
-jobs:
-  pre-commit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Fetch full history for diff comparison
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.12'
-      - name: Cache pre-commit hooks
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/pre-commit
-          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
-          restore-keys: |
-            pre-commit-${{ runner.os }}-
-      - name: Install pre-commit
-        run: pip install pre-commit
-      - name: Run pre-commit on changed files
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          HEAD_SHA: ${{ github.sha }}
-          BEFORE_SHA: ${{ github.event.before }}
-        run: |
-          if [ "$EVENT_NAME" == "pull_request" ]; then
-            # For PRs, compare against base branch
-            pre-commit run --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA" || EXIT_CODE=$?
-          elif [ -n "$BEFORE_SHA" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
-            # For pushes, compare against previous commit
-            pre-commit run --from-ref "$BEFORE_SHA" --to-ref "$HEAD_SHA" || EXIT_CODE=$?
-          else
-            # Fallback: check all files if we can't determine the diff
-            pre-commit run --all-files || EXIT_CODE=$?
-          fi
-
-          # Check if any files were modified by pre-commit
-          if git diff --exit-code; then
-            exit ${EXIT_CODE:-0}
-          else
-            echo "❌ Files were modified by pre-commit hooks. Please run 'pre-commit run --all-files' locally and commit the changes."
-            git diff
-            exit 1
-          fi
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index cb03c2c6..7b8588c6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,14 +1,18 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
     rev: v0.12.10
     hooks:
-      # Run the linter.
+      # Run the linter (fix issues automatically).
       - id: ruff-check
-        args: [ --fix ]
+        args: [--fix]
+        pass_filenames: true
+        stages: [commit]
+
       # Run the formatter.
       - id: ruff-format
-      
+        pass_filenames: true
+        stages: [commit]
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
@@ -16,7 +20,10 @@ repos:
       - id: check-case-conflict
       - id: end-of-file-fixer
       - id: trailing-whitespace
+
   - repo: https://github.com/kynan/nbstripout
     rev: 0.8.1
     hooks:
       - id: nbstripout
+        pass_filenames: true
+        stages: [commit]

From 8aa7333493af14cbc8ea0f83a27e3afb80c68628 Mon Sep 17 00:00:00 2001
From: beijingzyl <1772066848@qq.com>
Date: Fri, 12 Dec 2025 13:43:27 +0100
Subject: [PATCH 7/7] fix the bug in pre-commit

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e0803c30..092d2e7e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -116,7 +116,7 @@ pip install pytest pytest-cov black flake8
    ```
 
 2. **Open a Pull Request** on GitHub:
-   - **Target branch**: 
+   - **Target branch**:
      - Use `develop` for new features and non-critical bug fixes
      - Use `main` only for hotfixes or critical patches to the current stable release
    - Most contributions should target the `develop` branch