本週完成成果
這一週，我們要做的不是一個很厲害、什麼都會的 AI，而是一位「會先幫忙整理資料的小幫手」。下課前，你會親手把一段生活中的文字交給 Gemini，請它整理重點，再由你判斷它有沒有看錯或亂猜。
你最後會帶走兩個成果：一支真的能執行的 week02_api_test.py，以及一份用自己的話寫成的 week02_personal_idea.md。老師驗收時看的是你的操作、判斷與修改過程，不是誰問出的答案最華麗。
課前準備
步驟 1｜GitHub 網頁：確認 W1 commit 已推送，並從同一個課程 Repo 恢復原 Codespace。不要為每週重建新的 Codespace。
步驟 2｜Google AI Studio：使用自己的 Google 帳號開啟 API Keys 頁面。若校方帳號沒有建立專案／金鑰權限，改用教師核准的帳號方案，不要借用同學的 key。
步驟 3｜安全邊界：API key 等同密碼。不得貼在程式碼、Markdown、issue、PR、聊天訊息或截圖中；疑似外洩時立即停用並重建。
第二、三小時｜課堂教材與個人技術實作
故事開始｜星期二下課前，班代收到一大段社團活動公告。不到五分鐘，群組裡已經有人問：「哪一天？」「在哪裡？」「要帶什麼？」班代一邊找原文、一邊重複回答，還差點把時間抄錯。這時候，如果有一位小幫手能先把公告整理成五個重點，班代只要回頭核對一次，就輕鬆多了。今天，你要做的就是這位「校園活動資訊整理助手」。
老師先問｜AI 幫我們整理之後，是不是可以直接貼到班群？先不要。AI 很像一位動作快、偶爾會自作主張的助理：它可以先整理，但最後仍要由人對照原文。原文沒寫報名截止日，它就不能替我們猜一個日期。
先把 GitHub 想成一本「雲端作業本」｜Repository（簡稱 Repo）就是你這門課的整本作業本；commit 像在今天完成的頁面蓋上日期章，旁邊寫清楚這次改了什麼；push 則是把 Codespace 裡的新頁送回 GitHub，讓老師和未來的自己都找得到。Git 是背後幫忙保留每次修改紀錄的工具。
學生可能會問｜「那 Google Drive 不就好了？」一般雲端硬碟很適合放報告；GitHub 更適合程式，因為它會清楚留下哪一行何時被修改、誰修改，以及能不能回到先前版本。之後小組合作時，也比較不會出現 final、final2、真的final 這一串檔名。
今天只做五件事｜第一，看懂 GitHub 作業本；第二，把 API key 像密碼一樣收好；第三，用 prompt 把任務說清楚；第四，請 Gemini 整理一段公告；第五，由你核對答案，再把成果 commit、push 回 GitHub。
先看全程地圖｜遇到不熟悉的英文名詞不用急，先記住資料怎麼走：生活中的原始文字交給 AI，AI 只產生候選整理，人負責最後核對，確認後才保存。
┌──────────────┐
│ 一段生活公告 │
└──────┬───────┘
↓
┌──────────────┐
│ 寫清楚 Prompt│
│ 告訴 AI 任務 │
└──────┬───────┘
↓
┌──────────────┐
│ Gemini API │
│ 產生候選整理 │
└──────┬───────┘
↓
┌──────────────┐
│ 人工逐項核對 │
│ 原文沒有就不猜│
└──────┬───────┘
↓
┌──────────────┐
│ commit 保存 │
│ push 到 GitHub│
└──────────────┘課堂案例｜我們使用一則特別標示為「教學用虛構資料」的校園活動公告。輸入是真實生活中常見的雜亂文字；希望得到的輸出是活動名稱、日期、地點、適合對象與待確認事項。這不是比文筆，而是練習把問題說清楚、把結果查清楚。
步驟 1｜GitHub 網頁：開啟自己的課程 Repo，依序找出 Files、Commits 與 Codespaces。請用一句話向鄰座同學說明：Files 是目前版本，Commits 是版本歷史，Codespace 是執行與修改程式的環境。
步驟 2｜Codespaces 終端機：確認自己位於正確 Repo，並觀察目前分支與最近一次 commit。
pwd
git remote -v
git branch --show-current
git log -1 --oneline預期結果：pwd 位於課程 Repo；remote 指向自己的 GitHub Repo；分支名稱符合教師規定；git log 顯示 W1 的最新版本。若 Repo 擁有者不是自己，先停止操作。
步驟 3｜Google AI Studio：先看老師故意下的模糊指令「幫我整理一下」，再換成下面這段清楚指令。兩人一組比較結果：哪一個比較容易核對？AI 有沒有補上原文沒寫的內容？
請整理下面的校園活動公告。只使用原文資訊，輸出：
1. 活動名稱
2. 日期與時間
3. 地點
4. 適合對象
5. 原文沒有說明、需要人工確認的事項
公告：{課堂提供的公開測試文字}老師小結｜Prompt 就是你交代給 AI 的工作說明。就像請同學幫忙買午餐，只說「幫我買東西」一定會出問題；若說清楚品項、數量與不能加辣，結果才比較接近需要。可是說得再清楚，拿到餐點後仍然要檢查。
步驟 4｜Google AI Studio：在 API Keys 頁面建立新 Auth key。Google 官方文件記錄新建 key 預設採 Auth key，並公告 Standard key 的遷移期限；不要沿用 unrestricted Standard key。
步驟 5｜GitHub 網頁：進入 Settings → Codespaces → Secrets → New secret。名稱輸入 GEMINI_API_KEY，值貼上剛建立的 key，Repository access 只選自己的課程 Repo。
步驟 6｜Codespaces：停止並重新啟動 Codespace，或依 GitHub 畫面套用新 Secret。只檢查變數是否存在，不得輸出內容。
python - <<'PY'
import os
print('GEMINI_API_KEY is set:', bool(os.getenv('GEMINI_API_KEY')))
PY預期結果：GEMINI_API_KEY is set: True。若是 False，先確認 Secret 名稱、Repo access 和 Codespace 是否重啟。
步驟 7｜Codespaces 終端機：安裝課程鎖定的依賴。Dev Container 正常完成時通常已安裝；重跑此指令應保持相同相容版本。
python -m pip install -r courseware/gs3073-b/requirements.txt步驟 8｜Codespaces 編輯器：開啟 week02_api_test.py。範例從環境變數讀取 key 和模型名稱，不會把 key 寫進原始碼。先用課堂案例驗證 API，再把 prompt 改成自己的 AI 應用點子。
import os
import sys
from google import genai
api_key = os.getenv('GEMINI_API_KEY')
model = os.getenv('GEMINI_MODEL', 'gemini-3.6-flash')
if not api_key:
sys.exit('Missing GEMINI_API_KEY. Add it as a Codespaces Secret and restart the codespace.')
announcement = (
'【教學用虛構資料】校園 AI 創意工作坊\n'
'日期：10 月 15 日 14:00–16:00\n'
'地點：圖書館二樓討論室\n'
'對象：對 AI 應用有興趣的在校學生\n'
'備註：請自備筆電；報名截止日尚未公告。'
)
prompt = (
'你是校園活動資訊整理助手。請只根據下面公告，整理活動名稱、'
'日期時間、地點、適合對象，以及仍需人工確認的資訊。\n\n'
f'公告：\n{announcement}'
)
client = genai.Client(api_key=api_key)
response = client.models.generate_content(model=model, contents=prompt)
if not response.text:
sys.exit('The API returned no text. Check the model and request status.')
print(f'Model: {model}')
print(response.text)步驟 9｜Codespaces 終端機：執行程式，逐項對照課堂測試公告。將模型回覆視為候選摘要，不視為正確答案。
python week02_api_test.py預期結果：第一行顯示實際模型名稱，後面出現五項摘要；至少能指出一項需要人工核對的內容。若模型不存在，依教師公告更新 GEMINI_MODEL。
步驟 10｜個人課堂練習：建立 week02_personal_idea.md，先完成「目標使用者、問題、預期輸入、預期輸出」四欄，並寫出一項模型可能答錯的風險。不得直接貼上整段模型回答。
# W2 個人 AI 應用點子
## 目標使用者
## 要解決的問題
## 預期輸入
## 預期輸出
## AI 在其中的角色
## 八週內可驗證的成果
## 需要的資料與隱私風險
## 我修改了模型建議的地方課堂收束｜老師抽選兩個點子，全班一起回答三句話：「它幫誰？」「它省下哪一件麻煩事？」「我們怎麼知道它有幫上忙？」例如「做一個聊天機器人」還太模糊；「拿十則公開活動公告測試，逐則檢查日期與地點，錯誤處標記人工確認」才是可以實際驗證的方向。
指定閱讀與課後作業
先分清楚｜上面的「校園活動資訊整理助手」是第二、三小時在教室裡，由老師帶著完成的課堂實作。下面才是回家練習的指定閱讀與課後作業；兩者不是同一件事。
指定閱讀｜依原始課綱，回家完成 W3Schools 的 Python Variables、Data Types、Numbers 三個單元。閱讀時先不用背名詞，試著把變數想成貼了標籤的收納盒：prompt 盒子放文字、次數盒子放整數。讀完後要能辨認 str、int、float、bool，並知道放錯類型時程式為什麼會出錯。此閱讀不算入第二、三小時課堂教材。
課後作業方向｜回家後不是重做一次老師的公告範例，而是換成你每天真的會遇到的小麻煩。你可以選「整理社團活動公告」、「把宿舍採買清單分類」或「把一週讀書計畫拆成每日任務」，也可以提出自己的題目。先寫清楚它幫誰、輸入什麼、輸出什麼，以及最後由誰核對。不要使用同學姓名、電話、學號、私人對話或其他個資。
步驟 11｜個人：完成 week02_api_test.py，至少修改 prompt 成自己的情境並成功取得一次文字回覆。不得提交真實 API key，也不要提交完整私人對話紀錄。
步驟 12｜個人：完成 week02_personal_idea.md。除課堂四欄外，補上「八週內可驗證成果、需要的資料與隱私風險、我修改模型建議的地方」。
步驟 13｜Codespaces 終端機：先檢查差異與疑似秘密，只加入兩個本週檔案，commit 後 push 到自己的 GitHub Repo。畫面若出現疑似 key，立即停止、移除並輪替 key。
git diff -- week02_api_test.py week02_personal_idea.md
git add week02_api_test.py week02_personal_idea.md
git commit -m 'W2: test Gemini API and document AI idea'
git push驗收方式
python week02_api_test.py
git grep -nE 'AIza[0-9A-Za-z_-]{20,}|GEMINI_API_KEY=' -- . ':!docs/courseware/gs3073-b-authoring-standard.md' || true
git status --short
git log -1 --oneline通過條件：API 有文字回覆；秘密搜尋沒有命中真實 key；工作目錄乾淨；最新 commit 以 W2: 開頭。教師驗收只看執行結果與 commit，不收取 API key。
應提交的 Repo 檔案
必交：week02_api_test.py、week02_personal_idea.md。不得提交 .env、API key、完整 API 回應紀錄、帳務畫面或 Google Cloud 專案識別資訊。
常見問題與排除
問題 1｜ModuleNotFoundError: google：確認安裝的是 google-genai，而不是名稱相近的舊套件；重新執行 requirements 安裝後再試。
問題 2｜Missing GEMINI_API_KEY：確認 Secret 名稱完全一致、已授權給正確 Repo，並重新啟動 Codespace。不要用 print 顯示 key。
問題 3｜401／403：先在 AI Studio 檢查 key 類型、專案與 API 狀態；不要重複建立大量 key，也不要借用他人的 key。
問題 4｜429 或 quota exceeded：停止連續重試，記錄發生時間與一次錯誤摘要，依教師安排稍後重試。額度不是程式正確性的唯一證據。
問題 5｜模型名稱失效：依當週教師公告設定 GEMINI_MODEL。模型與 API 規則會變動，因此教材記錄查閱日期，不承諾永久可用。
引用資料
國立中央大學授課課綱／劉書銘老師，《劉書銘老師課程大綱_基礎模型與生成式人工智慧-更新版.pdf》；教師提供附件。用途：W1–W16 時段、實作主題、評量與交付物。
GitHub Docs，《What is GitHub?》；https://docs.github.com/en/get-started/start-your-journey/what-is-github；查閱日期：2026-08-04。用途：Git、GitHub、Repository 與協作平台的角色差異。
GitHub Docs，《Creating a repository for your project on GitHub》；https://docs.github.com/en/get-started/start-your-journey/creating-a-repository-for-your-project-on-github；查閱日期：2026-08-04。用途：Repository、commit、共同工作空間與版本歷史。
GitHub Docs，《Using source control in your codespace》；https://docs.github.com/en/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace；查閱日期：2026-08-04。用途：Codespaces 中修改、commit 與 push 的標準流程。
GitHub Docs，《Specifying recommended secrets for a repository》；https://docs.github.com/en/enterprise-cloud@latest/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository；查閱日期：2026-08-04。用途：Codespaces 建議 Secrets 與個人密鑰設定。
Google AI for Developers，《Using Gemini API keys》；https://ai.google.dev/gemini-api/docs/api-key；查閱日期：2026-08-04。用途：Gemini Auth key、環境變數與金鑰安全規則。
Google APIs，《Google Gen AI Python SDK》；https://github.com/googleapis/python-genai；查閱日期：2026-08-04。用途：google-genai 安裝、Client 與 generate_content Python 介面。
Google AI for Developers，《Text generation》；https://ai.google.dev/gemini-api/docs/generate-content/text-generation；查閱日期：2026-08-04。用途：Gemini Python SDK 文字生成請求、模型參數與回應文字介面。
W3Schools（課綱指定閱讀），《Python Variables》；https://www.w3schools.com/python/python_variables.asp；查閱日期：2026-08-04。用途：W2 課後 Python Variables 指定閱讀與練習。
W3Schools（課綱指定閱讀），《Python Data Types》；https://www.w3schools.com/python/python_datatypes.asp；查閱日期：2026-08-04。用途：W2 課後 Python Data Types 指定閱讀與練習。
W3Schools（課綱指定閱讀），《Python Numbers》；https://www.w3schools.com/python/python_numbers.asp；查閱日期：2026-08-04。用途：W2 課後 Python Numbers 指定閱讀與練習。