Y1hsiaochunnn · Aug 11, 2026 · Aug 10, 2026 · Aug 10, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,4 +1,6 @@
 ---
+
+[简体中文](bug_report_ZH.md)
 name: Bug report
 about: Report a reproducible problem with a board example
 title: "[Bug] "

diff --git a/.github/ISSUE_TEMPLATE/bug_report_ZH.md b/.github/ISSUE_TEMPLATE/bug_report_ZH.md
@@ -0,0 +1,41 @@
+---
+name: 缺陷报告
+about: 报告可复现的开发板示例问题
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+[English](bug_report.md)
+
+## 摘要
+
+请简要说明问题。
+
+## 示例
+
+- 示例路径：
+- 框架和版本：
+- 板卡版本：
+
+## 复现步骤
+
+1.
+2.
+3.
+
+## 预期行为
+
+应发生什么？
+
+## 实际行为
+
+实际发生了什么？
+
+## 日志或截图
+
+请粘贴相关串口日志、构建日志摘录或截图。
+
+## 其他说明
+
+请补充硬件连接、模块或配置改动。
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,12 +1,24 @@
 ## Summary
 
+[简体中文](pull_request_template_ZH.md)
+
 - TODO
 
 ## Validation
 
 - [ ] GitHub Actions passed
+- [ ] Affected examples and framework(s) are listed
+- [ ] The Actions matrix/selected targets are noted
+- [ ] Firmware artifact impact is stated (including no impact)
+- [ ] Managed component changes are described, if any
 - [ ] Hardware behavior checked, if applicable
 
+## Scope Notes
+
+- Affected example paths and frameworks:
+- Hardware or pin considerations:
+- Firmware artifact impact:
+
 ## Notes
 
 - TODO
diff --git a/.github/pull_request_template_ZH.md b/.github/pull_request_template_ZH.md
@@ -0,0 +1,20 @@
+## 概要
+
+[English](pull_request_template.md)
+
+- TODO
+
+## 验证
+
+- [ ] GitHub Actions 已通过
+- [ ] 已列出受影响的示例和框架
+- [ ] 已说明 Actions 矩阵/所选目标
+- [ ] 已说明固件工件影响（包括无影响）
+- [ ] 已说明托管组件变更（如有）
+- [ ] 已检查硬件行为（如适用）
+
+## 范围说明
+
+- 受影响的示例路径和框架：
+- 硬件或引脚注意事项：
+- 固件工件影响：
diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml
@@ -2,58 +2,108 @@ name: Build Examples
 
 on:
   push:
-    branches:
-      - main
-      - master
-    tags:
-      - "v*"
-    paths:
-      - ".github/workflows/examples.yml"
-      - "scripts/discover_examples.py"
-      - "releases/**"
-      - "config/**"
-      - "examples/esp-idf/**"
-      - "examples/arduino/**"
+    branches: [main, master]
+    tags: ["v*"]
   pull_request:
-    paths:
-      - ".github/workflows/examples.yml"
-      - "scripts/discover_examples.py"
-      - "releases/**"
-      - "config/**"
-      - "examples/esp-idf/**"
-      - "examples/arduino/**"
   workflow_dispatch:
     inputs:
       target:
         description: "all, an example name, or a repo-relative example path"
         required: false
         default: "all"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
 permissions:
   contents: read
 
 env:
-  IDF_VERSIONS: "v5.5.4,v6.0.2"
+  IDF_VERSIONS: "v5.5.5,v6.0.2"
   IDF_TARGET: "esp32s3"
-  ARDUINO_CORE_VERSION: "3.3.10"
+  ARDUINO_CORE_VERSION: "3.3.11"
   ARDUINO_FQBN: "esp32:esp32:esp32s3:USBMode=hwcdc,CDCOnBoot=cdc,PSRAM=opi,FlashSize=16M,PartitionScheme=app3M_fat9M_16MB"
   PRODUCT_NAME: "ESP32-S3-Touch-AMOLED-2.06"
 
 jobs:
+  quality:
+    name: Quality and documentation scope
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check repository documentation conventions
+        run: python3 scripts/check_docs.py . --config config/markdown-audit.json
+      - name: Run routing, discovery, and documentation checker tests
+        run: python3 -m unittest discover -s tests -v
+
+  scope:
+    name: Classify changed scope
+    runs-on: ubuntu-latest
+    outputs:
+      esp_idf_mode: ${{ steps.classify.outputs.esp_idf_mode }}
+      arduino_mode: ${{ steps.classify.outputs.arduino_mode }}
+      esp_idf_paths: ${{ steps.classify.outputs.esp_idf_paths }}
+      arduino_paths: ${{ steps.classify.outputs.arduino_paths }}
+      firmware_paths: ${{ steps.classify.outputs.firmware_paths }}
+      unknown_paths: ${{ steps.classify.outputs.unknown_paths }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - id: classify
+        shell: bash
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" || "${{ github.ref }}" == refs/tags/* ]]; then
+            {
+              echo 'esp_idf_mode=all'
+              echo 'arduino_mode=all'
+              echo 'esp_idf_paths=[]'
+              echo 'arduino_paths=[]'
+              echo 'firmware_paths=[]'
+              echo 'unknown_paths=[]'
+            } >> "$GITHUB_OUTPUT"
+          else
+            if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+              base="${{ github.event.pull_request.base.sha }}"
+            else
+              base="${{ github.event.before }}"
+            fi
+            git fetch --no-tags --depth=1 origin "$base"
+            git diff --name-status -z "$base" "${{ github.sha }}" > changed-files.z
+            python3 scripts/ci_scope.py --name-status-file changed-files.z --github-output "$GITHUB_OUTPUT"
+          fi
+          esp_idf_mode="$(grep '^esp_idf_mode=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
+          arduino_mode="$(grep '^arduino_mode=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
+          firmware_paths="$(grep '^firmware_paths=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
+          unknown_paths="$(grep '^unknown_paths=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
+          {
+            echo "### CI scope"
+            echo "- ESP-IDF mode: $esp_idf_mode"
+            echo "- Arduino mode: $arduino_mode"
+            echo "- Firmware paths: $firmware_paths"
+            echo "- Unknown paths: $unknown_paths"
+          } >> "$GITHUB_STEP_SUMMARY"
+
   discover-esp-idf:
+    needs: scope
+    if: needs.scope.outputs.esp_idf_mode != 'none'
     runs-on: ubuntu-latest
     outputs:
       matrix: ${{ steps.discover.outputs.matrix }}
       count: ${{ steps.discover.outputs.count }}
     steps:
       - uses: actions/checkout@v4
       - id: discover
+        shell: bash
         run: |
-          python3 scripts/discover_examples.py \
-            --surface esp-idf \
+          args=()
+          if [[ "${{ needs.scope.outputs.esp_idf_mode }}" == "selected" ]]; then
+            args+=(--selected-paths '${{ needs.scope.outputs.esp_idf_paths }}')
+          fi
+          python3 scripts/discover_examples.py --surface esp-idf \
             --selector "${{ github.event.inputs.target || 'all' }}" \
-            --idf-versions "${IDF_VERSIONS}" \
-            --github-output "$GITHUB_OUTPUT"
+            --idf-versions "${IDF_VERSIONS}" --github-output "$GITHUB_OUTPUT" "${args[@]}"
 
   build-esp-idf:
     needs: discover-esp-idf
@@ -74,37 +124,35 @@ jobs:
       - name: Package firmware
         shell: bash
         run: |
-          python3 releases/package_firmware.py \
-            --framework esp-idf \
-            --project "${{ matrix.path }}" \
-            --build-dir "build/${{ matrix.name }}-${{ matrix.idf }}" \
-            --name "${PRODUCT_NAME}-${{ matrix.name }}-${{ matrix.idf }}" \
-            --framework-version "${{ matrix.idf }}" \
-            --target "${IDF_TARGET}" \
-            --git-sha "${{ github.sha }}" \
-            --output-dir release-artifacts
-      - name: Upload firmware artifact
-        uses: actions/upload-artifact@v4
+          python3 releases/package_firmware.py --framework esp-idf --project "${{ matrix.path }}" \
+            --build-dir "build/${{ matrix.name }}-${{ matrix.idf }}" --name "${PRODUCT_NAME}-${{ matrix.name }}-${{ matrix.idf }}" \
+            --framework-version "${{ matrix.idf }}" --target "${IDF_TARGET}" --git-sha "${{ github.sha }}" --output-dir release-artifacts
+      - uses: actions/upload-artifact@v4
         with:
           name: firmware-esp-idf-${{ matrix.name }}-${{ matrix.idf }}
           path: release-artifacts/*.zip
           if-no-files-found: error
+          retention-days: 14
 
   discover-arduino:
+    needs: scope
+    if: needs.scope.outputs.arduino_mode != 'none'
     runs-on: ubuntu-latest
     outputs:
       matrix: ${{ steps.discover.outputs.matrix }}
       count: ${{ steps.discover.outputs.count }}
     steps:
       - uses: actions/checkout@v4
       - id: discover
+        shell: bash
         run: |
-          python3 scripts/discover_examples.py \
-            --surface arduino \
+          args=()
+          if [[ "${{ needs.scope.outputs.arduino_mode }}" == "selected" ]]; then
+            args+=(--selected-paths '${{ needs.scope.outputs.arduino_paths }}')
+          fi
+          python3 scripts/discover_examples.py --surface arduino \
             --selector "${{ github.event.inputs.target || 'all' }}" \
-            --arduino-core "${ARDUINO_CORE_VERSION}" \
-            --fqbn "${ARDUINO_FQBN}" \
-            --github-output "$GITHUB_OUTPUT"
+            --arduino-core "${ARDUINO_CORE_VERSION}" --fqbn "${ARDUINO_FQBN}" --github-output "$GITHUB_OUTPUT" "${args[@]}"
 
   build-arduino:
     needs: discover-arduino
@@ -124,40 +172,45 @@ jobs:
           arduino-cli core install "esp32:esp32@${{ matrix.core }}"
       - name: Compile ${{ matrix.path }}
         run: |
-          arduino-cli compile \
-            --fqbn "${{ matrix.fqbn }}" \
-            --libraries "${{ matrix.libraries }}" \
-            --export-binaries \
-            --output-dir "build/${{ matrix.name }}-${{ matrix.core }}" \
-            "${{ matrix.path }}"
+          arduino-cli compile --fqbn "${{ matrix.fqbn }}" --libraries "${{ matrix.libraries }}" \
+            --export-binaries --output-dir "build/${{ matrix.name }}-${{ matrix.core }}" "${{ matrix.path }}"
       - name: Package firmware
         run: |
-          python3 releases/package_firmware.py \
-            --framework arduino \
-            --project "${{ matrix.path }}" \
-            --build-dir "build/${{ matrix.name }}-${{ matrix.core }}" \
-            --name "${PRODUCT_NAME}-${{ matrix.name }}-arduino-${{ matrix.core }}" \
-            --framework-version "${{ matrix.core }}" \
-            --target "${IDF_TARGET}" \
-            --git-sha "${{ github.sha }}" \
-            --output-dir release-artifacts
-      - name: Upload firmware artifact
-        uses: actions/upload-artifact@v4
+          python3 releases/package_firmware.py --framework arduino --project "${{ matrix.path }}" \
+            --build-dir "build/${{ matrix.name }}-${{ matrix.core }}" --name "${PRODUCT_NAME}-${{ matrix.name }}-arduino-${{ matrix.core }}" \
+            --framework-version "${{ matrix.core }}" --target "${IDF_TARGET}" --git-sha "${{ github.sha }}" --output-dir release-artifacts
+      - uses: actions/upload-artifact@v4
         with:
           name: firmware-arduino-${{ matrix.name }}-${{ matrix.core }}
           path: release-artifacts/*.zip
           if-no-files-found: error
+          retention-days: 14
+
+  validation:
+    name: Example validation
+    if: always()
+    needs: [quality, scope, discover-esp-idf, build-esp-idf, discover-arduino, build-arduino]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Report stable validation status
+        shell: bash
+        run: |
+          results=("${{ needs.quality.result }}" "${{ needs.scope.result }}" "${{ needs.discover-esp-idf.result }}" "${{ needs.build-esp-idf.result }}" "${{ needs.discover-arduino.result }}" "${{ needs.build-arduino.result }}")
+          printf 'Job results: %s\n' "${results[*]}"
+          for result in "${results[@]}"; do
+            if [[ "$result" == "failure" || "$result" == "cancelled" ]]; then
+              exit 1
+            fi
+          done
+
   publish-release:
     permissions:
       contents: write
-    needs:
-      - build-esp-idf
-      - build-arduino
-    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [validation, build-esp-idf, build-arduino]
+    if: startsWith(github.ref, 'refs/tags/v') && needs.validation.result == 'success'
     runs-on: ubuntu-latest
     steps:
-      - name: Download firmware artifacts
-        uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v4
         with:
           pattern: firmware-*
           path: release-artifacts

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,7 @@
 # Contributing
 
+[简体中文](CONTRIBUTING_ZH.md)
+
 Thank you for helping improve this board repository.
 
 ## Workflow

diff --git a/CONTRIBUTING_ZH.md b/CONTRIBUTING_ZH.md
@@ -0,0 +1,18 @@
+# 贡献指南
+
+[English](CONTRIBUTING.md)
+
+感谢您帮助改进本开发板仓库。
+
+## 流程
+
+1. Fork 仓库并创建主题分支。
+2. 将改动集中在一个缺陷、示例或文档更新上。
+3. 路径、设置或行为变化时更新受影响的文档。
+4. 提交包含简明说明和验证记录的 Pull Request。
+
+## 验证
+
+Pull Request 应使用 GitHub Actions 进行构建验证。硬件行为发生变化时，请说明板卡版本、示例
+路径和已执行的手工检查。ESP-IDF 示例位于 `examples/esp-idf/`，Arduino 草图和随附库位于
+`examples/arduino/`；随附库中的示例默认不属于产品 CI。
diff --git a/FirmWare/README.md b/FirmWare/README.md
@@ -1,7 +1,9 @@
 # Firmware
 
+[简体中文](README_ZH.md)
+
 This directory contains checked-in factory or recovery firmware images for the board.
 
 These binaries are not generated by CI and are not treated as source projects by the build workflow. Use them only when the product documentation or support flow calls for flashing a released binary image.
 
-Source-built firmware artifacts are produced by the `Build Examples` workflow from maintained ESP-IDF and Arduino source projects. Use the helpers in `releases/` to package local build outputs or download CI artifacts.
+Source-built firmware artifacts are produced by the `Build Examples` workflow from maintained ESP-IDF and Arduino source projects. Use the helpers in `releases/` to package local build outputs or download CI artifacts.
diff --git a/FirmWare/README_ZH.md b/FirmWare/README_ZH.md
@@ -0,0 +1,9 @@
+# 固件
+
+[English](README.md)
+
+本目录包含该开发板已提交的出厂或恢复固件映像。它们不由 CI 生成，也不被构建工作流视为源码
+项目。仅在产品文档或支持流程要求刷写已发布二进制文件时使用。
+
+维护中的 ESP-IDF 和 Arduino 源码项目会由 `Build Examples` 工作流生成固件工件；可使用
+`releases/` 中的工具打包构建输出或下载 CI 工件。
diff --git a/Material/images/ESP32-S3-Touch-AMOLED-2.06.jpg b/Material/images/ESP32-S3-Touch-AMOLED-2.06.jpg