本週完成成果
你會把小組分支中的 MediaPipe、RAG、Agent 與模型功能接到同一條最小可行流程，先定義每段輸入輸出，再一次合併一個 feature 並保留回復點。
完成標準｜main 上的最小流程可由 README 一鍵啟動；整合測試包含正常、空輸入與外部服務失敗；每個 PR 都經 Review，不一次合併所有未知變更。
課前準備
步驟 1｜確認第三小時邊界：前兩小時 DLI 由官方課程完成，本篇只做課綱指定的群組 API 大合體。
預期結果｜不將 DLI 答案或平台內容帶入 Repo。
步驟 2｜小組：列出四個 feature 分支的 owner、最新 commit、啟動指令與輸出格式。
預期結果｜不知道 owner 或無法啟動的分支先標紅，不直接 Merge。
步驟 3｜main 建立整合前 tag 或記錄 commit，確保失敗時能回到已知狀態。
git switch main
git pull --ff-only
git rev-parse HEAD
git status --short預期結果｜記下完整 SHA，工作目錄乾淨。
第三小時｜個人技術實作
故事開始｜四位同學各自做出好用零件，但一接起來就出錯：A 傳 gesture，B 等的是 gesture_name；C 回傳文字，D 期待 JSON。像接力賽跑得再快，交棒區沒對好仍會掉棒。
老師先問｜全部分支一次 Merge，出錯再一起修不是更快嗎？一次改太多時很難知道誰造成問題；每次只接一段並跑測試，才有清楚回復點。
生活比喻｜API contract 像插頭規格：兩邊都要同意形狀與電壓。整合測試像每接上一個家電就先開機，而不是全屋接完才送電。
先看全程地圖｜先看懂資料與決策怎麼移動，再開始操作。圖中的箭頭代表下一步，不代表可以跳過人工確認。
MediaPipe ─┐
├→ 統一 JSON → RAG 檢索 → Agent 草稿 → 人工確認
文字輸入 ──┘ │
↓
README 一鍵重現
每合併一支：Review → Merge → Smoke test → 記錄結果步驟 4｜小組：先寫介面契約，不先改程式。
{
"request_id": "demo-001",
"input_type": "gesture_or_text",
"input": {},
"sources": [],
"draft": "",
"needs_human_review": true,
"error": null
}預期結果｜所有模組同意必填欄位、空值與錯誤格式。
步驟 5｜用 Mermaid 畫最小成功路徑與兩條失敗路徑。
```mermaid
flowchart LR
A[輸入] --> B[統一 JSON]
B --> C[RAG]
C --> D[Agent 草稿]
D --> E[人工確認]
B -. 無效輸入 .-> X[清楚錯誤]
C -. 無來源 .-> Y[資料不足]
```預期結果｜圖中有人工確認、無效輸入與無來源處理。
步驟 6｜依序合併 feat-mediapipe、feat-rag、feat-agent；每次 Merge 後立即跑同一 smoke 指令。
python -m codes.integration.smoke --case happy
python -m codes.integration.smoke --case empty-input
python -m codes.integration.smoke --case provider-down預期結果｜三種 case 都得到預期狀態；失敗時停止下一支 Merge。
步驟 7｜更新 README 一鍵啟動段落，請未參與整合的同學只照 README 重跑。
預期結果｜新同學不需口頭提示就能完成安裝、啟動與測試。
課堂收束｜每組指出「最後一個已知正常 commit」與「若 API 失敗，使用者看到什麼」。能回答才算完成整合，不是畫面偶爾成功一次。
指定閱讀與課後作業
指定閱讀｜依課綱完成群組專案 API 合體；Antigravity 用來協助定位問題與提出修改，但每個 diff 仍由學生 Review。Mermaid 官方語法支持可追蹤架構圖。
課後作業方向｜完成所有功能分支 Merge、README 與三種整合測試；不在 main 上直接試錯，不用 force push 消除失敗紀錄。
步驟 8｜小組：將整合測試結果、已知限制與 rollback SHA 寫入 README。
預期結果｜README 至少包含產品架構圖、Codespaces 一鍵啟動、測試方式、分工與限制。
步驟 9｜小組：完成最後一個 integration PR，Review 通過後才 Merge main。
git add README.md codes
git commit -m 'W14: integrate features with smoke tests'
git push -u origin HEAD預期結果｜PR 中列出三個 smoke 結果與 rollback commit。
驗收方式
python -m codes.integration.smoke --case happy
python -m codes.integration.smoke --case empty-input
python -m codes.integration.smoke --case provider-down
rg -n "啟動|架構|測試|限制|rollback" README.md通過條件｜main 可從 README 重現；三種測試通過；介面契約一致；最後正常 SHA 與限制可找到。
應提交的 Repo 檔案
必交｜README.md。只提交課綱指定成果與重現所需說明；不得提交 API key、個資、私人對話、未授權資料或大型模型檔。
常見問題與排除
問題 1｜import 路徑衝突：從 Repo 根目錄以 module 方式執行，統一 package 結構，不到處修改 sys.path。
問題 2｜環境變數名稱不同：建立一份 .env.example 只列名稱與說明，不放值。
問題 3｜Merge 後才發現壞掉：回到已記錄 SHA 診斷，修復用新 commit，不改寫共用歷史。
引用資料
國立中央大學授課課綱／劉書銘老師，《劉書銘老師課程大綱_基礎模型與生成式人工智慧-更新版.pdf》；教師提供附件。用途：W1–W16 時段、實作主題、評量與交付物。
Google for Developers Codelabs，《Building with Google Antigravity》；https://codelabs.developers.google.com/building-with-google-antigravity；查閱日期：2026-08-04。用途：W4、W14 Antigravity Agent 工作區、任務與人工檢查流程。
Mermaid，《Flowcharts Syntax》；https://mermaid.js.org/syntax/flowchart.html；查閱日期：2026-08-04。用途：W6、W14 以文字維護技術架構與整合流程圖。
GitHub Docs，《About pull requests》；https://docs.github.com/en/pull-requests/get-started/about-pull-requests；查閱日期：2026-08-04。用途：W3 branch、Pull Request、討論與合併協作流程。
GitHub Docs，《Quickstart for reviewing pull requests》；https://docs.github.com/en/pull-requests/get-started/reviewing-pull-requests-quickstart；查閱日期：2026-08-04。用途：W3 Code Review 留言、建議、核准與要求修改。