feat: gate official transcript behind a config flag, add UI checkbox

USE_OFFICIAL_TRANSCRIPT env var (default false) controls whether the
pipeline probes the iCourse transcript API before running ASR.
single_run.yml accepts use_official_transcript input; the frontend
exposes it as a small checkbox next to the 单次运行 button.

Author: LeafCreeper

.github/workflows/single_run.yml

@@ -7,6 +7,11 @@ on:
         description: "Comma-separated course IDs to process (e.g. 30004,30005)"
         required: true
         type: string
+      use_official_transcript:
+        description: "Use official iCourse transcripts instead of ASR"
+        required: false
+        default: false
+        type: boolean
 
 permissions:
   contents: write
@@ -157,6 +162,7 @@ jobs:
           StuId: ${{ secrets.STUID }}
           UISPsw: ${{ secrets.UISPSW }}
           COURSE_IDS: ${{ inputs.course_ids }}
+          USE_OFFICIAL_TRANSCRIPT: ${{ inputs.use_official_transcript && '1' || '' }}
           DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
           GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
           SMTP_EMAIL: ${{ secrets.SMTP_EMAIL }}

frontend/index.html

@@ -705,6 +705,13 @@ <h3 class="text-sm font-semibold text-gray-700">单次运行</h3>
             <div x-show="subsSaving" class="spinner !w-4 !h-4 !border-2 !border-white/30 !border-t-white"></div>
             <span x-text="subsSaving ? '加密上传中…' : '保存订阅到 Secret'"></span>
           </button>
+          <label class="flex items-center gap-1.5 cursor-pointer select-none"
+                 :class="singleRunIds.length === 0 ? 'opacity-40' : ''">
+            <input type="checkbox" x-model="singleRunUseOfficial"
+                   :disabled="singleRunIds.length === 0"
+                   class="w-3.5 h-3.5 rounded border-gray-300 text-emerald-500 focus:ring-emerald-400">
+            <span class="text-xs text-gray-500">官方字幕</span>
+          </label>
           <button @click="runSingleRunWorkflow()" :disabled="singleRunTriggering || singleRunIds.length === 0"
                   class="px-5 py-2.5 bg-emerald-500 text-white rounded-lg text-sm font-medium hover:bg-emerald-600 disabled:opacity-50 flex items-center gap-2">
             <div x-show="singleRunTriggering" class="spinner !w-4 !h-4 !border-2 !border-white/30 !border-t-white"></div>

frontend/js/app.js

@@ -282,6 +282,7 @@ document.addEventListener("alpine:init", () => {
     _subsFilterTimer: null, _deptFilterTimer: null,
     subsSaving: false, subsError: "",
     singleRunTriggering: false,
+    singleRunUseOfficial: false,
     /* Per-browser pinned-courses set, lazily synced to localStorage. */
     starred: _loadStarred(),
 
@@ -983,7 +984,7 @@ document.addEventListener("alpine:init", () => {
         // than overloading the scheduled check workflow.
         await ICS.github.triggerSingleRunWorkflow(
           this.repoOwner, this.repoName, "main", creds.token,
-          this.singleRunIds,
+          this.singleRunIds, this.singleRunUseOfficial,
         );
         this._toast(
           "已触发单次运行，处理 " + this.singleRunIds.length + " 门课。请到 Actions 查看进度",

frontend/js/github.js

@@ -266,22 +266,19 @@ async function _setCourseIdsSecret(owner, repo, token, courseIds) {
   return value;
 }
 
-async function _triggerSingleRunWorkflow(owner, repo, ref, token, courseIds) {
-  // Fires the Single Run workflow (single_run.yml) via workflow_dispatch.
-  // The workflow takes a ``course_ids`` input (comma-separated list) and
-  // processes ONLY those courses without touching the persisted
-  // ``COURSE_IDS`` secret used by the daily check workflow.
-  // PAT needs ``Actions: Read and write``.
+async function _triggerSingleRunWorkflow(owner, repo, ref, token, courseIds, useOfficial) {
   const url = `${_GH_API}/repos/${owner}/${repo}/actions/workflows/single_run.yml/dispatches`;
   const ids = (Array.isArray(courseIds) ? courseIds : [])
     .map(String).map((s) => s.trim()).filter(Boolean).join(",");
   if (!ids) throw new Error("单次运行列表为空");
+  const inputs = { course_ids: ids };
+  if (useOfficial) inputs.use_official_transcript = "true";
   const res = await fetch(url, {
     method: "POST",
     headers: { ..._ghHeaders(token), "Content-Type": "application/json" },
     body: JSON.stringify({
       ref: ref || "main",
-      inputs: { course_ids: ids },
+      inputs: inputs,
     }),
   });
   if (res.status === 204) return;

src/pipeline/lecture_runner.py

@@ -36,6 +36,7 @@
 from src.ai import bucketer
 from src.pipeline.ppt_pipeline import PPTPipeline
 from src.ai.transcriber import IncompleteAudioError, NoAudioStreamError
+from src.runtime import config
 
 if TYPE_CHECKING:
     from src.data.database import Database
@@ -202,19 +203,20 @@ def _get_transcript(self, existing: dict | None, course_id: str,
             )
             return existing["transcript"], None
 
-        # Try official transcript before firing up ASR.
-        try:
-            official = self._client.get_transcript_segments(sub_id)
-            if self._official_transcript_usable(official):
-                text = " ".join(s["text"] for s in official)
-                self._reporter.info(
-                    f"    Using official transcript "
-                    f"({len(text)} chars, {len(official)} segments)"
-                )
-                self._db.update_transcript(sub_id, text)
-                return text, official
-        except Exception:
-            pass  # fall through to ASR
+        # Try official transcript before firing up ASR (config-gated).
+        if config.USE_OFFICIAL_TRANSCRIPT:
+            try:
+                official = self._client.get_transcript_segments(sub_id)
+                if self._official_transcript_usable(official):
+                    text = " ".join(s["text"] for s in official)
+                    self._reporter.info(
+                        f"    Using official transcript "
+                        f"({len(text)} chars, {len(official)} segments)"
+                    )
+                    self._db.update_transcript(sub_id, text)
+                    return text, official
+            except Exception:
+                pass  # fall through to ASR
 
         # Pull the audio handle.  ``schedule`` is idempotent — usually the
         # previous lecture already kicked it off (Phase C), but for the

src/runtime/config.py

@@ -164,6 +164,12 @@ def resolve_model_providers() -> list[dict]:
     os.environ.get("VIDEO_DOWNLOAD_CONCURRENCY", "2")
 )
 
+# 是否优先使用 iCourse 官方字幕（跳过 ASR 转录）。默认关闭。
+USE_OFFICIAL_TRANSCRIPT = (
+    os.environ.get("USE_OFFICIAL_TRANSCRIPT", "").strip().lower()
+    in ("1", "true", "yes")
+)
+
 # 监控的课程 ID 列表
 COURSE_IDS = [
     c.strip()