💡 導讀：六個實驗桌，能不能變成一條生產線？

想像一間檢驗研究室：一個人匯入變異表，第二個人檢查品質，第三個人做註釋，另外的人比較分子軌跡、畫圖、檢查 DNA 的序列偏好。每個人都完成了自己的工作，可是每次要交報告時，還得手動整理六份檔案。只要少複製了一份，後面的結論就可能接錯資料。

Day 21–26，我們已經用人工資料完成六個單獨可跑的 Python 練習。今天不是教你再寫一次 QC 或 Motif 演算法，而是學會讓電腦按照正確順序執行既有模組。 這就是命令列工具（CLI, Command-Line Interface）的價值。

這篇仍採用你原本的「逆向拆解學習法」：先讓 Google AI Studio 畫出一條看得見的流程，再回到 Python，把每一個畫面背後的功能接起來；我們不必從一個空白檔案摸索出所有架構。

一、核心概念：CLI 是替研究流程寫好的操作說明

在 Terminal 輸入以下指令，就能讓 Day27 教學程式依序跑 Day21–26：

python3.12 day27_alpha_variant_cli.py run --mode demo --output-dir day27_output

它會在本機完成六站工作並保留每一站的 JSON、CSV／SVG／HTML，最後寫出一份可核對的總摘要。

重要區別： 這份 day27_alpha_variant_cli.py 是為本文新增的離線教育 CLI，不是私人 GitHub v0.1.0 已存在的 alpha-variant 程式，也沒有真正連上 Google AlphaGenome Atlas／Model API。

二、第一步：之前用 Google AI Studio 做出 MVP 畫面

進入 Google AI Studio 的應用程式建構介面，使用教學包中的 AI_STUDIO_DAY27_PROMPT.txt。讓 AI 生成有六張步驟卡、輸出摘要、錯誤提醒及 JSON 檢視的前端原型。先從畫面問自己：

• 使用者按下「Run」時，真正該執行哪段程式？
• 哪個函式負責匯入 VCF、哪段程式負責 QC？
• 哪個步驟會拒絕非合成來源？
• 圖上的數字能不能回查原本的 JSON？
• 如果執行到第五站失敗，前四站不應被誤稱為整條流程完成。

AI Studio 生成 React 介面，不會自動變成 Python 後端。 畫面上的「Run」只能是尚未接線的 UI，除非之後真的另行建置並驗證本地後端。今天我們在 WSL 終端機直接執行 Python，不要求新手學會建立伺服器。

逆向拆解：一眼看懂 UI 對應哪支 Python

AI Studio 六站流程介面（設計／MVP）
       |
       v
Python Day27 CLI:  run --mode demo
       |
       +-- Day21.execute_offline()    → VCF / QC / review JSON
       +-- Day22.execute_offline()    → QC trace + probes
       +-- Day23.execute_offline()    → annotation JSON / CSV
       +-- Day24.emit_artifacts()     → REF/ALT delta
       +-- Day25.emit_outputs()       → traceable SVG
       +-- Day26.write_outputs()      → synthetic PPM motifs
       |
       v
Pipeline summary + SHA-256 manifest + HTML dashboard

這樣即使不懂所有函式內部邏輯，也能從「輸入 → 功能 → 輸出」三件事逐步理解軟體。

三、今天動手做：真正把六個離線 Lab 串起來

需要準備什麼？

只有 WSL Ubuntu 的 Python 3.12 和本篇 ZIP；不需 pip install、unzip、GitHub 權限或 API Key。ZIP 已包含 Day21–26 既有教學模組的位元相同副本與六份人工輸入，並在 DAY27_SOURCE_MANIFEST.json 保存原始 SHA-256。這樣讀者不用回頭一篇篇搜尋散落的檔案。

下載 AlphaGenome_Day27_AlphaVariant_CLI_API_Bridge_Author_Review_Pack.zip 到 Windows Downloads，依序執行：

cd /mnt/c/Users/user/Downloads
mkdir -p ~/alphagenome-day27-qa
python3.12 -m zipfile -e \
  AlphaGenome_Day27_AlphaVariant_CLI_API_Bridge_Author_Review_Pack.zip \
  ~/alphagenome-day27-qa
cd ~/alphagenome-day27-qa

python3.12 -m unittest -v test_day27_alpha_variant_cli

python3.12 day27_alpha_variant_cli.py run \
  --mode demo \
  --output-dir day27_output

python3.12 day27_alpha_variant_cli.py verify \
  --run-dir day27_output

如果看到 Output directory already exists，不是程式壞了，而是程式刻意避免覆寫舊實驗紀錄；請改成新的 --output-dir day27_output_002。不要為了重跑就刪除舊結果。

程式中的六行整合核心

你不需要先理解整份 CLI；找到 run_pipeline()，裡面這段才是「接線」的重點：

results[21] = modules[21].execute_offline(vcf, reference, regions, scores, temp_root / "day21")
results[22] = modules[22].execute_offline(vcf, reference, regions, temp_root / "day22")
results[23] = modules[23].execute_offline(
    vcf, reference, regions, scores, temp_root / "day23",
    input_day21=temp_root / RUN_FILES[21],
)
results[24] = modules[24].emit_artifacts(track, temp_root / RUN_FILES[23], temp_root / "day24")
results[25] = modules[25].emit_outputs(temp_root / RUN_FILES[24], track, temp_root / "day25")
results[26] = modules[26].write_outputs(
    motif, temp_root / "day26", day25_summary_path=temp_root / RUN_FILES[25],
)

這段是從完整程式抽出的閱讀用排版摘錄，保留相同呼叫關係；真正執行請用 ZIP 中通過測試的 day27_alpha_variant_cli.py，不要只複製六行到空白檔案。它們須在函式內搭配輸入、模組和錯誤處理才能執行。

▶ 實測輸出與如何讀它

在作者審稿環境 Python 3.13.5 的執行結果，主要欄位為：

{
  "status": "PASS",
  "mode": "OFFLINE_ONLY",
  "variant_id": "chr1:110:A>G",
  "pipeline_stage_count": 6,
  "candidate_count": 8,
  "selected_count": 3,
  "missing_score_count": 1,
  "largest_absolute_delta": -0.3,
  "motif_a_delta": -0.12,
  "motif_b_delta": 0.12,
  "real_api_calls_this_run": 0
}

以上是 stdout 的核心欄位摘錄，不是完整 JSON。結果路徑在每台電腦會不同，不應抄成固定值。

verify 命令會重新計算輸出檔 SHA-256；本次環境回傳：

{"artifact_count": 23, "checksums": "MATCH", "mode": "OFFLINE_ONLY", "real_api_calls_this_run": 0, "stage_count": 6, "status": "PASS"}

這只代表產物和本機清單一致，不等於證明外部來源真實，更不是臨床驗證。和 Day28 學到的 provenance 精神相通：我們要把「這次到底跑了什麼」留下來。

從 JSON 找回每一步

day27_output/
  day21/day21_review_packet.json
  day22/day22_qc_report.json
  day23/day23_annotation_report.json
  day24/day24_track_delta_report.json
  day25/day25_locus_summary.json
  day26/day26_motif_report.json
  day27_pipeline_summary.json
  day27_run_manifest.json
  day27_stages.csv
  day27_pipeline_flow.svg
  day27_review_dashboard.html

用 Windows 檔案總管開啟 \\wsl.localhost\Ubuntu-24.04\home\user\alphagenome-day27-qa\day27_output，再用瀏覽器打開 day27_review_dashboard.html，就能看完整的六站流程與各站結果連結。

四、對照真正的 AlphaGenome API：為什麼今天還不接 LIVE？

離線教學、歷史真實模型查詢、現行 LIVE 請求是三個不同證據層級。

今天的 CLI run 只有 --mode demo 或 --mode offline，刻意不提供 --mode live。就算你的環境變數中已經有 API Key，它也不會讀取或呼叫 API。將來若要接入真正的 Atlas 或 Model API，必須另外建立、測試、核准來源與權限，以及保留原始回應和版本資訊；那是另一個實作階段。

同時留意：Day21–26 的多個合成檔案雖使用同一人工變異識別碼 chr1:110:A>G，但不是同一次實驗測量。Day23 的人工分數 −0.17、Day24 的人工差分 −0.30 和 Day26 的人工序列偏好變化 ±0.12，不能相加成綜合危險指數。

五、今天的工程觀念：讓失敗也容易追查

• 不覆寫： 既有輸出目錄存在就拒絕執行，讓舊實驗可保留。
• 先跑完再定稿： 六站暫時寫到同一個暫存資料夾；所有檢查通過後才移到目標目錄，避免把中途失敗的結果標成整體 PASS。
• 來源紀錄： DAY27_SOURCE_MANIFEST.json 記錄程式與 fixture 的 SHA；day27_run_manifest.json 記錄輸出檔 SHA，包括總摘要。這些不是密碼學簽章或研究來源的獨立背書。
• 可重新驗證： 執行 verify --run-dir ... 能發現檔案遭修改、缺少、輸出損壞或雜湊不一致。
• 保留無法知道的事： 所有人工註釋保留 REVIEW_REQUIRED，沒有替讀者產生醫療判斷。

✅ 本日 Checklist

• [ ] 我能用一行命令串起 Day21–26 的六個教學模組。
• [ ] 我能指出 run 與 verify 的用途不同，且 live 不被允許。
• [ ] 我知道 Day21、23、24、25、26 的人工資料是以來源／變異 ID 關聯，數值不能任意合併。
• [ ] 我能打開輸出 HTML，找到六站 JSON 與 day27_run_manifest.json。
• [ ] 我明白 AI Studio UI 原型不等於本機 Python 已接線，更不是官方 Atlas API。

六、科學證據與限制

這是一個 OFFLINE SYNTHETIC EDUCATIONAL DEMO，僅驗證 Python 模組編排、輸入與輸出合約、SHA-256 一致性與錯誤處理。全部示例皆為人工資料 TOY_NOT_GRCH38，不具備患者診斷、遺傳分型、病理預測或臨床決策能力。Day21–26 沒有真實模型查詢，Day27 不會執行真正 AlphaGenome Atlas 或 Model API。

此程序並非完整支援 VCF 規範、複雜 indel 正規化、正式 Motif binding 模型、醫療級輸入驗證或部署安全。GitHub v0.1.0 的既有私人 alpha-variant 命令是另一份獨立程式，不要把本篇測試當作其已經整合六日新模組的證據。

七、明日預告

Day 28 將反過來檢查研究報告：除了產生看起來漂亮的 JSON 和圖表，我們還要說清楚資料來源、模型限制、缺值、校準狀態與人工審閱。下一站是 AlphaGenome 的限制與證據追蹤 —— 學會說清楚我們不知道什麼。

延伸閱讀與來源

• AlphaGenome 官方研究說明
• GA4GH / SAMtools VCF v4.3 格式規範
• UCSC Genome Browser BED 格式說明