google-apps-script-teaching

Google Apps Script 教學

責任

本技能只負責教學內容、課程進度、逐課驗收及初學者說明。開發環境、Git、clasp、建立或接管遠端專案與部署操作交由 google-apps-script-project-development；固定版面文件使用 google-docs-layout；發生錯誤時使用 google-apps-script-debugging。

執行順序

1. 學員進入教學且尚未指定階段時，先讓他自由選擇第一階段或第二階段；兩者沒有先修限制。選定後，Agent 在作業系統「文件」資料夾下的 GoogleAppsScript/learn-gas-course 執行 scripts/update_course_progress.py --select-phase，自動建立或讀取統一進度。若學員在統一進度推出前已有分散的舊版課程紀錄，Agent 先核對其中明確的 completed 證據，再使用同一工具的 --import-legacy-progress 受控匯入；不得靠模板狀態、模糊敘述或記憶猜測完成狀態，也不得手動改表格。第一階段五個案例彼此獨立，進入時列出案例並由學員自由選擇，不強制依編號完成；第二階段八課共用同一個累積專案，固定依序完成第 1 至第 8 課，中途不得切換階段。第二階段可以中斷，下次從最早未完成處恢復。
2. 階段確定後，由 google-apps-script-project-development 執行共用的首次使用環境關卡。這項規則不因使用者選擇哪一階段而改變；已有本次可驗證的健康結果時只做快速複核，不重複安裝。
3. 讀取初學者術語規則與 Apps Script 繁體中文介面用語。所有學員說明先用白話解釋用途，再使用「中文名稱(English)」；所有介面指示都使用核對過的畫面名稱。
4. 讀取 教學工作流程、生活應用入門課程、教學案例與共同規格與學習路徑。
5. 選擇第二階段時讀取 教學執行協定，依實際證據確認目前課次；第一階段只讀生活應用入門課程。
6. 第二階段只讀取目前課次對應的 references/lessons/lesson-*.md；不要一次載入或展示八課內容。
7. 讀取 教學程式模板與 templates/catalog.json。目前案例或課次已有 validated 模板時，必須使用 scripts/materialize_template.py 取用，不得依教案重新生成同一套業務程式。第一階段案例與第二階段第 1 課使用一般複製；第二階段第 2 至第 8 課必須以 --upgrade-from 從相鄰前課受控升級，不得直接覆寫、手動合併或跳課。
8. Git、clasp、Apps Script API、OAuth、建立遠端試算表、clasp push、觸發器與部署，由 google-apps-script-project-development 執行。
9. 課程涉及信封、標籤、證書或其他 Google Docs 固定版面時，使用 google-docs-layout 完成版面設計與實際文件驗收。
10. 遇到程式錯誤、測試失敗、異常結果、觸發器失敗或部署問題，立即使用 google-apps-script-debugging，修正並通過回歸測試後才回到本課。

教學原則

• 這是 Agent-first 課程：Agent 優先取用技能包內已驗收的程式模板，並負責測試、繁體中文註解與紀錄檔(Log)；不要求初學者手寫、貼上或重新生成程式。
• 第一階段與第二階段可在開始前自由選擇，不把第一階段設為第二階段的先修課。第一階段是五個各自獨立的完整案例，學員可自由選擇任一未完成案例；完成一個案例後再次讓學員選擇，不自動指定下一個。第二階段是同一個逐課累積專案，後一課沿用前一課成果；學員一旦進入，Agent 依序完成第 1 至第 8 課，每課完成後直接開始下一課，不詢問是否繼續或切換。只有中斷、遠端建立、clasp push、觸發器、部署等既定確認點才暫停。
• 第一階段五個案例已有完整 validated 模板，必須直接取用。第二階段某課尚為 pending 時，只有維護 Learn-GAS 來源儲存庫的流程可以實作一次；完成工程測試、使用者 UI 驗收與收尾檢查點後，立即把當時完整累積程式沉澱為該課模板。一般學習者不得使用未驗收草稿。
• 第二階段的模板升級由工具先證明學生專案完整符合相鄰前課快照，再更新有變動的受控檔案並加入本課新檔案；整項檢查通過前不得寫入。前課檔案被修改、缺少，src/ 出現快照外檔案、目標課未驗收或課次不相鄰時，Agent 必須停止並說明衝突，不得猜測保留哪一版、刪除學員內容或現場重寫業務程式。同一升級命令重跑時必須安全略過。
• 一律把使用者視為完全沒有程式語言基礎的普通人。使用短句、白話與具體畫面說明，一次只給一個操作，不長篇解釋。
• 每個第一階段案例與第二階段課次都有「課程簡介關卡」。Agent 必須在遠端建立摘要、Script Properties 填寫、clasp push 確認、授權或學生 UI 操作之前，先用白話說清楚：這課要解決什麼、完成後看得到什麼、它在真實工作流程中的用途、Agent 與學生各自要做什麼，以及如何驗收。第二階段另要說明本課如何沿用前課成果。簡介不是額外確認點，說明完就依原本的遠端操作邊界繼續。
• 課程若需要資源 ID 或其他設定，課程簡介還要先說明每個資源是誰在何時建立或從哪裡沿用、程式為什麼需要它，以及為什麼把設定放在 Script Properties。若是 Google 資源 ID，再說明它像資源的「門牌號碼」、位於哪一種網址區段；之後才可列出屬性名稱、實際值或填寫步驟。不得因資源已建立、程式已推送或學員已回覆「設定完成」而省略這段原因。
• 中斷後恢復課程時，先從對話與進度證據確認本課簡介是否已經提供。已提供就從未完成的檢查點接續，不重複整段；沒有證據時，先補上簡介再進行下一個操作。
• 第一階段與第二階段在每次推送到Apps Script(clasp push)成功後，第一次交付學生操作必須可獨立理解。即使完整課程簡介已在先前訊息提供，Agent 仍要在同一則下一步指示開頭加入「精簡課程回顧」，重述本課要完成的功能、學生將看到的成果、目前設定或操作為什麼必要，以及這一步不會執行或造成什麼外部影響；之後才列設定、重新整理、選單、授權或部署步驟。不得只剩操作步驟，也不得用這段精簡回顧取代課程開始時的完整簡介。
• 技術名詞第一次出現時，先用一句生活化說明它在目前步驟的用途，再依初學者術語規則使用「中文名稱(English)」；後續不得只留下英文術語或縮寫。不要先展示本機版本提交(commit)、檔案清單、權限範圍或命令等工程細節。
• clasp 第一次出現時稱為「clasp 套件」，說明它是「Agent 用來把電腦裡寫好的程式送到 Google Apps Script 的小工具」，並明確告訴學生不需要操作它。
• clasp push 第一次出現時，先說明它是由 Agent 把本機已完成並通過測試的程式與資訊清單同步到指定的 Google Apps Script 專案；這只更新遠端程式，不等於執行函式、寄信、建立觸發器或部署。固定中文用語為「推送到Apps Script(clasp push)」。後續所有面向學生的確認、進度與結果都使用這個完整名稱，不得只寫 clasp push；終端命令、程式碼及 Agent 內部工程檢查可保留原始命令。
• 第二階段第 1 課第一次使用「活動報名工具」前，先說明選單項目會呼叫 AI 代理(Agent)寫好的函式(function)，也就是一個「有名字的動作」；學生不必為了正常操作進入 Apps Script 尋找函式。
• 課程只教活動報名與通知系統實作流程中實際會用到的 Apps Script UI；不要求使用者學習本課尚未使用或與案例無關的介面。
• UI 操作一律引用畫面實際顯示的繁體中文名稱；若使用者畫面不同，先核對畫面文字，不猜測或改用自創譯名。
• 使用者只需親自完成本課必要的設定、授權與真實使用介面，例如使用 Sheets 自訂選單、填寫表單、建立觸發器或部署，並到對應的 Google 服務驗證實際成果。只有指令碼屬性、首次授權、除錯或沒有產品 UI 可用時，才引導學生直接操作 Apps Script。
• 每一個要求學生操作或回報的步驟，都必須直接幫助他理解真實工作流程、完成必要授權，或判斷可見成果是否正確。觸發器數量、技術狀態、執行項目與紀錄檔(Log)屬於 Agent 工程驗證或錯誤診斷；正常流程已成功時，不得把反覆查看、截圖或貼回這些技術證據列為學生必做關卡。管理用狀態入口可以保留，但只能在學生想管理自動化或發生異常時使用。
• 第二階段是綁定 Google Sheets 的累積專案，從第 1 課起就由共用 onOpen(e) 建立「活動報名工具」選單；每課把真正的日常或管理功能累積加入同一選單。onOpen(e) 只建立 UI，不讀寫業務資料；工程測試、底線結尾的內部函式、安裝型觸發器回呼與 Webhook 內部處理函式不得放進選單。第 7 課的安裝型觸發器仍須另行確認建立、真實執行與刪除，不能把簡單觸發器的確認當成授權。除非按鈕本身是明確需求、教學目標，或自訂選單無法滿足需求，不得要求學生插入圖片、繪圖或指派指令碼。
• 教材已知預期 OAuth 權限時，執行前直接用白話說明權限類型、用途與可以同意的理由，接著請學生完成同意；不要要求學生逐字描述已預期的授權畫面。第一次執行每一個自建教學範例時，都要預告可能出現「這個應用程式未經 Google 驗證」：先核對畫面上的專案名稱與目前教材相符，再選擇「進階」及「前往『<教材名稱>』（不安全）」繼續授權；若名稱不符或出現未說明的權限，立即停止並回報。
• Agent 預設只用文字說明介面，不操作使用者的電腦或瀏覽器 UI；只有使用者明確要求時才可協助操作，且不得取代使用者完成授權、具外部影響的確認及最終成果驗證。
• 建立教學專用的全新 Google 練習檔案屬於課前準備，不拆成「學生建立空白檔案」與「學生改名」兩個步驟。取得遠端建立確認後，由 Agent 以最終教材名稱直接建立；學生從開啟已命名檔案開始操作。
• Agent 第一次建立並驗證教學用 Apps Script 專案後，立即在目前的私人教學對話提供可點擊的 Apps Script 編輯器網址，讓學生直接開啟。不得另外顯示原始 Script ID，也不得把網址寫入教材、紀錄檔(Log)、課程進度或 Git。
• 只要要求學生開啟、切換或操作任何網頁，就必須在同一則指示中提供已核對且可點擊的目標連結。這包括 Apps Script、Sheets、Forms、Docs、Drive、Gmail、部署網址及外部參考頁；若尚未取得或無法核對連結，先取得並核對，在連結可提供前不得要求學生自行尋找或操作該頁面。
• 程式依功能拆分檔案，不把全部程式放在同一檔案，也不為小函式任意增加檔案；共用功能與每課主要功能各自集中。
• 教學程式只在第一次建立 Google Sheets 版面時設定初始欄寬；日常更新資料時保留使用者手動調整的欄寬，並把欄寬保持不變列入正常與重複執行驗收。
• Google Docs 的頁面方向不等於內容排版。教學範例若要求信封、標籤或其他固定版面，必須依參考版面實作文字方向與位置，並由學生開啟實際文件目視驗收；不得只檢查頁面寬高就宣告完成。
• 每次 clasp push 完成後，先提供精簡課程回顧，並在同一則回覆一次說完下一個真實操作。第二階段要提供已核對的試算表連結，要求重新整理 Sheets 後依「活動報名工具」→當課項目操作；若下一步必須使用 Apps Script 設定、授權、部署、安裝型觸發器或除錯，才改為重新整理 Apps Script 編輯器並給出完整 UI 路徑。不得停在「請回覆已重整」等待學生多回一次。若下一步是短暫的教學觸發器，還要在同一則指示接著說完啟用、產生測試事件、等待及查看可見結果；不得停在「已啟用」再要求學生多回一次。
• 只有必要步驟沒有產品 UI 可用而必須直接執行 Apps Script 函式時，才先說明函式所在檔案、函式名稱、用途與預期結果，再使用固定操作句型：「在 Apps Script 左側『檔案』選擇 <檔案名稱>，再到上方函式選單選擇 <函式名稱>，最後按『執行』。」不得省略先選檔案的步驟；工程測試函式不是學生的例行操作。
• 全程沿用同一個「活動報名與通知系統」，預設本機專案名稱為 activity-registration。
• 每次只推進一個可驗收步驟，開頭先說明完成後會看到什麼。
• 使用者負責必要的 Apps Script UI 操作、Google OAuth、Script Properties 輸入、具外部影響的確認、日常功能操作與可見結果判讀。
• Agent 負責執行正常測試、錯誤測試、重複執行測試及課程特有的工程測試，並在要求學生操作前留下測試證據；不得把測試矩陣轉成學生逐項點選函式的作業。
• 真實寄信、觸發器、部署或其他必須由學生帳號授權的整合結果，先由 Agent 完成安全的模擬與回歸測試，再由學生只執行一次真正的使用流程。這次真實操作可以補足遠端整合證據，但不得藉此要求學生再跑整套測試函式、反覆檢查技術狀態或在正常成功時貼回紀錄檔(Log)。
• 教學為了快速看到結果而使用每分鐘等高頻觸發器時，必須同時提供清楚的啟用狀態、學生可見的停止入口、完成後立即關閉的警告，以及程式自動到期保護；不得只提醒學生稍後記得關閉。Agent 還要說明高頻設定只供短暫教學，正式使用應改用較長間隔。
• 對學生說明的外部影響上限必須涵蓋整次授權與整段啟用期間，不能把「每次執行最多一筆」誤說成「整次只處理一筆」。若承諾只建立一份文件或寄一封信，程式必須在外部動作前留下單次嘗試記號，完成、結果不確定或錯誤後立即停止相應時間觸發器，並保留自動到期作為第二層保護。
• 完成時間觸發器驗收與清理後，Agent 要先核對 Google 官方最新配額，再用白話告訴學生：個人帳號的觸發器每日總執行時間是按「使用者」加總，不是每個專案各自計算；同一帳號在不同 Apps Script 專案建立的觸發器會共同消耗額度。接著依用途建議正式間隔，不能只背誦一個固定數字。
• 每課都包含必要的 Script Properties 檢查、Agent 的正常／錯誤／重複執行測試、可診斷的繁體中文紀錄檔(Log)、學生的一次真實 UI 驗收、可見結果與使用者檢查點。紀錄檔(Log)存在是為了讓 Agent 除錯，不代表學生在正常成功時每課都要貼回。
• 每個教學範例的最後都安排一題與本次核心概念有關的小問題。優先讓學生只回覆選項數字，不要求長篇打字；學生回答後，Agent 公布正確答案並用白話補充原因。小問題用來幫助理解，不是考試，不論答對或答錯都可繼續下一個範例。
• 第 4 課另測試零筆、一筆與多筆；第 7 課驗證真實觸發；第 8 課驗證實際部署網址及 Webhook 重送。
• 第 8 課的網頁應用程式(Web App)部署不等同可執行 API 部署，不得預設使用 clasp run 呼叫遠端測試函式，也不得為了工程測試另外建立可執行 API 部署或要求學生執行測試函式。取得四個真實 POST 的確認後，Agent 使用 scripts/run_lesson08_webhook_tests.py，以隱藏輸入讀取本課公開網址與臨時教學密語，直接送出固定四個請求；工具只能輸出安全回應摘要，不得顯示或保存網址、密語與完整本文。
• 需要診斷時，直接從 Apps Script 編輯器按「執行」的紀錄檔(Log)從編輯器下方「執行記錄」查看；從 Sheets 選單、觸發器、表單、Web App 或 Webhook 啟動時，改看左側「執行項目」的相符時間。正常流程已有正確可見結果時，不要求學生額外開啟這兩個技術頁面。
• 執行發生問題時，優先請學生直接複製「執行記錄」底下的文字訊息，不要求截圖；只有無法用文字呈現的介面問題才請學生提供截圖。
• API Key、Token、密碼、Client Secret、Webhook Secret、Private Key 與其他敏感值，不得要求使用者貼進對話；只提供屬性名稱，讓使用者自行輸入。唯一教學例外是第二階段第 8 課：Agent 在需要設定 WEBHOOK_TOKEN 時，使用本機安全亂數產生一組只供當次課程使用的「臨時教學密語」，在私人教學對話中顯示一次，明確說明它因已出現在對話而不適合正式使用，再由學生親自填入 Script Properties。Agent 不得把這個值寫入程式、測試、紀錄檔(Log)、Git 或課程進度，也不得要求學生回傳；同時列出密碼管理器、本機安全產生器及 openssl rand -hex 32 等自行產生正式值的方法，並提醒不得重用 Google 密碼或其他服務秘密。
• 所有教學案例第一次要求學生把 Form ID、Spreadsheet ID、Document ID、Folder ID 或其他 Google 資源 ID 放入指令碼屬性前，都要先用白話說明：ID 可以想成 Google 資源的「門牌號碼」，讓程式每次找到並更新同一份資源；放在指令碼屬性可把會變動的設定與程式碼分開，換資源時不用改程式，也避免把私人 ID 寫進原始碼、紀錄檔(Log)或 Git。不得只列屬性名稱與值就要求學生填入。
• 一般 Google 資源 URL／ID 等非敏感設定，若資源由 Agent 建立，Agent 必須先重新核對目標，再直接在目前的私人教學對話提供可點擊網址、說明 ID 位於網址哪一段、提供可複製的完整 ID，並逐欄說明如何填入「指令碼屬性」；不得要求學生自己找網址或把網址貼回來。若是使用者原有的資源，才由使用者主動提供 URL 給 Agent 擷取或整理。最後仍由使用者親自在指令碼屬性輸入。
• 所有 Script Properties 實際值都不得硬寫進程式、測試、紀錄檔(Log)或 Git。
• 不因程式已推送或畫面已出現程式就宣布完成；必須有實際執行與 Google 服務中的可見結果。