| name | opencode-github |
| description | GitHub 三階段教學 — ①用 git clone 拿別人的懶人包 ②建自己的 repo 把作品 push 上去 ③換電腦或隔天 git pull 驗收。說「連接 GitHub」「clone 懶人包」「把作品放上 GitHub」「我怕弄丟」「換電腦拿回檔案」時載入。 |
連接 GitHub（三階段）
GitHub 在研習裡會出現三次，因為它不是一堂工具課，而是三個痛點的解答。
不要一次教完，也不要照順序一口氣做完——每一階段都在使用者「已經痛過」之後才出現。
| 階段 | 什麼時候出現 | 老師心裡的話 | 這階段只做 | 要帳號嗎 |
|---|
| ① 消費端 | 研習一開場 | 「講師的東西怎麼拿？」 | git clone 別人的 repo | ❌ 不用 |
| ② 生產端 | 做出第一個作品後 | 「這個我怕弄丟」 | 註冊 → 建 repo → push | ✅ 要 |
| ③ 跨電腦驗收 | 隔天 / 換一台電腦 | 「真的還在嗎？」 | git pull 拿回來 | ✅ 要 |
⚠️ 給 AI agent 的提醒：使用者說「連接 GitHub」時，先問他現在在哪一階段，只做那一階段。
一次把三階段全部倒給零基礎老師，是這包最容易失敗的方式。
🔴 給 AI agent：這份文件該怎麼用
這份的價值不在「步驟」，在「你查不到的那些事」。
| 內容類型 | 你該信誰 |
|---|
gh 的指令名稱、旗標、輸出格式 | 🔴 信 --help 與官方文件。gh 版本一直在更新 |
| GitHub 網頁上的按鈕在哪、選單叫什麼 | 🔴 信使用者眼前的畫面 |
| 「兩道門」的觀念（Git 協定門 vs API 門） | ✅ 信這份。這解釋了九成的「SSH key 明明設好了卻建不了 repo」 |
| 裝置碼會被你的逾時砍掉 | ✅ 信這份。實測過，退出碼 124 |
| 註冊拼圖是風險評分不是解題 | ✅ 信這份。同 IP 多人註冊會被判機器人 |
| credential helper 查不到 ≠ 沒設好 | ✅ 信這份。GCM 的設定在 system 層 |
| 症狀 → 真因對照（常見坑那張表） | ✅ 信這份，最省時間的部分 |
三條執行原則
- 先查現況再動手。 先跑
gh auth status、git config --show-origin --get-all credential.helper 看這台是什麼狀態，回報給使用者。
- 失敗時先報錯誤原文，然後停下來。 不要自己換方法重試，尤其不要重跑
gh auth login——重跑一次就作廢一組碼，使用者會愈弄愈亂。
- 文件跟現況對不上時，以現況為準，並告訴使用者哪裡對不上。
🔴 這一包最容易搞砸的三件事，全部都是「你多做了什麼」而不是「你少做了什麼」：
重跑 gh auth login、在自己的 shell 跑互動指令、看到 --global 查不到就叫使用者去修。
看到卡住，先停、先問，不要動手。
先備條件
驗證：
git --version
gh --version
預期輸出（版號不同沒關係）：
git version 2.49.0.windows.1
gh version 2.65.0 (2025-01-06)
若出現「無法辨識 'git'／'gh' 這個詞彙是否為 Cmdlet」或 command not found
→ 回去跑 00-env-setup，不要在這裡臨時安裝。
關鍵知識：GitHub 有「兩道門」
這一段是本包真正的價值，值得在研習裡花三分鐘講。
GitHub 其實是兩個系統疊在一起，要分別開門：
- Git 協定門 —
clone / push / pull，負責「搬檔案」
- API 門 — 建 repo、開 issue、發 PR、設定 Pages，負責「管理你帳號上的東西」
不同的驗證方式，只開得了不同的門：
| 驗證方式 | Git 協定門（clone/push/pull） | API 門（建 repo、issue、PR） | 老師要付出的代價 |
|---|
| SSH key | ✅ | ❌ | 要產金鑰、貼公鑰、記 passphrase |
| PAT 手動貼 | ✅ | ✅ 但要自己管、易外流 | token 散在設定檔／剪貼簿，會過期、會外洩 |
| gh CLI | ✅ | ✅ | 登入一次，之後不用管 |
這解釋了一個常見的鬼打牆：很多教學只教 SSH key，老師 clone、push 都好好的，
結果一叫 agent「幫我建一個 repo」就失敗——因為那是 API 門，SSH key 開不了。
統一做法：gh CLI ＋ 一條很少人提的指令
gh auth login 預設只開 API 門（gh 自己的指令能用），
git 的 push / pull 仍然會另外跟你要帳號密碼。補上這一條，兩道門才會一起開：
gh auth setup-git
它做的事：把 git 的 HTTPS 憑證也接到 gh 的 token 上。
之後 git 每次需要驗證，就自動去問 gh 拿 token。結果是：
- 登入一次，兩道門都開
- token 存在作業系統的憑證保管庫（Windows 認證管理員 / macOS 鑰匙圈 / Linux keyring），不落地成明文檔案
- AI agent 看不到 token——agent 只是呼叫
git 和 gh，token 由作業系統遞交
- 跨 agent 完全一致：OpenCode、Claude Code、Codex、AntiGravity 都是叫同一支
gh，設定一次全部通用
老師版最小步驟（全程不用碰 token、不用產 SSH key）：
gh auth login → 選 GitHub.com → HTTPS → 瀏覽器登入輸入 8 碼
gh auth setup-git → 把 git 的憑證也接上去
gh auth status → 驗證
為什麼不建議走 GitHub MCP
GitHub MCP 只開 API 門。裝了它，agent 能建 repo、開 issue，
但 clone / push / pull 這些 git 操作它辦不到，還是得回頭用 CLI。
於是你同時維護兩套東西：MCP 的 token ＋ git 的憑證——
多一份會過期、會外流、換 agent 要重設的設定，卻沒有少做任何一件事。
gh 一套就把兩道門都開了，所以本包不裝 GitHub MCP。
（例外：真的要大量自動化 issue／PR 分析時再考慮。研習用不到。）
第一階段（消費端）：把別人的懶人包抓下來
目標：拿到講師的教材。
這階段不做：不註冊帳號、不 push、不解釋什麼是 git、不講 commit。
對老師就一句話：「這是一個下載指令，會把整個資料夾抓到你電腦。」
1-1 選一個放東西的地方
Windows（PowerShell）：
cd $HOME\Documents
Mac / Linux：cd ~/Documents
1-2 抓下來
git clone https://github.com/mathruffian-dot/opencode-lazy-packs.git
預期輸出：
Cloning into 'opencode-lazy-packs'...
remote: Enumerating objects: 120, done.
remote: Total 120 (delta 40), reused 118 (delta 38), pack-reused 0
Receiving objects: 100% (120/120), 84.21 KiB | 2.10 MiB/s, done.
Resolving deltas: 100% (40/40), done.
1-3 驗證
cd $HOME\Documents\opencode-lazy-packs
dir
git remote -v
Mac / Linux：ls 取代 dir
預期看到 README.md、skills 等檔案，以及：
origin https://github.com/mathruffian-dot/opencode-lazy-packs.git (fetch)
origin https://github.com/mathruffian-dot/opencode-lazy-packs.git (push)
看到檔案 = 這階段就完成了。 不要再往下講。
1-4 備援：clone 失敗就下載 ZIP
學校網路擋 git、或指令怎麼樣都跑不起來時：
- 瀏覽器打開 repo 網址
- 點綠色的 Code 按鈕 → Download ZIP
- 解壓縮到
文件 資料夾
缺點：日後對方更新，你要整包重下載；用 git clone 的話一行 git pull 就更新（見第三階段）。
給老師的定心丸
抓下來的是別人的東西，你在自己電腦上怎麼改都不會影響到對方，
也推不上去（你沒有那個 repo 的權限）。這就是第一階段安全的原因——只能拿，不會弄壞。
第二階段（生產端）：把自己的作品放上去
動機：老師剛做出一份教材、一個網頁、一份簡報，心裡冒出「這個我怕弄丟」。
這時候才教這一段，接受度最高。
2-1 註冊 GitHub 帳號
到 https://github.com/signup 用瀏覽器自己註冊。
⚠️ AI agent 不要代填帳號密碼、不要代為註冊、也不要代解驗證，請老師自己在瀏覽器完成。
記下你的帳號名稱（後面會一直用到）。
🔴 註冊一定要在家裡先做，不要留到研習現場
GitHub 註冊會出現拼圖驗證（Arkose Labs FunCaptcha）。它不是在考你解得對不對，是在給你的來源打分數——分數低就一直發新題目，所以會出現「解了十題還在解」的無限循環，而且解對也沒用。
扣分最重的一項，正好就是研習現場的樣子：同一個 IP 在短時間內多人註冊。 整間教室共用一個對外 IP，大概第三、四個人開始就會被當成機器人在批次開帳號。
所以：
- ✅ 前一晚在自己家裡註冊——每個人 IP 不同，這一關天然就過了
- ✅ 註冊完順便在瀏覽器登入一次（如果會跳信箱驗證、裝置確認、2FA 設定，一併做完）
- ❌ 不要全班在現場一起註冊
💡 第二點比看起來重要。 隔天現場要跑 gh auth login，如果瀏覽器已經是登入狀態，
老師只剩「打八碼、按 Authorize」兩個動作，幾十秒的事。
反之，如果他是當天才第一次登入，中間會夾著信箱驗證、裝置確認、甚至被要求當場設 2FA——
這些全部要塞進授權的時間裡，就是現場「重複三次認證才成功」的由來（見 2-2）。
現場真的有人非註冊不可時，照這個順序救：
- 請他開手機熱點，用行動網路註冊（換一個乾淨 IP，最有效）
- 關掉 VPN
- 改用無痕視窗，或換一個沒裝擴充功能的瀏覽器（廣告攔截器與隱私擴充會擋掉驗證用的網域、或清掉驗證 cookie，造成「解對了卻又跳一題」）
- 不要連續猛按重試，越試分數越低，等幾分鐘再來
講師請自備一支手機熱點當救援。這一關助教沒有別的辦法可以救。
2-2 登入 GitHub CLI
先看狀態：
gh auth status
未登入時會顯示：
You are not logged into any GitHub hosts. To log in, run: gh auth login
登入：
gh auth login
會問四個問題，照這樣選：
| 問題 | 選 |
|---|
| What account do you want to log into? | GitHub.com |
| What is your preferred protocol for Git operations? | HTTPS |
| Authenticate Git with your GitHub credentials? | Yes |
| How would you like to authenticate GitHub CLI? | Login with a web browser |
接著終端機會顯示一組 8 碼一次性驗證碼（例如 A1B2-C3D4），
按 Enter 開瀏覽器 → 貼上驗證碼 → 按 Authorize。
想少選兩題可以直接用：gh auth login --web --git-protocol https
🔴 給 AI agent：這一行絕對不要在你自己的 shell 裡跑
這是研習現場最常見的無限循環，成因如下：
gh auth login 印出 8 碼之後不會結束——它要一直活著輪詢 GitHub，等你授權完才拿得到 token。
而你（agent）的指令通常有逾時（常見 2 分鐘）。老師還在手機上打那八碼，gh 就已經被你的逾時砍掉了。
結果是：老師在瀏覽器按了 Authorize、畫面顯示成功，但已經沒有 gh 在等著收 token。
你查 gh auth status 還是未登入 → 你以為失敗 → 重跑 gh auth login → 產生一組全新的 8 碼
→ 老師螢幕上還是舊碼，怎麼打都不對 → 你再重跑 → 無限循環。
實測（gh 2.89）：無 TTY 時 gh auth login 會立刻印出碼與網址，然後持續執行；被逾時砍掉時退出碼是 124。
正確做法 A：開一個獨立視窗讓它活著（Windows）
Start-Process powershell -ArgumentList '-NoExit','-Command','gh auth login --web --git-protocol https'
這個視窗不會被你的逾時影響，gh 可以一直等。macOS／Linux 沒有等價的一行指令，請直接走做法 B。
正確做法 B：請老師自己開終端機
跟他說：「請你自己開一個 PowerShell 視窗，貼上 gh auth login，照著它的指示做。那個視窗先不要關。」
然後——輪詢，不要重跑
不論 A 或 B，接下來你要做的是每隔幾秒查一次狀態，直到成功：
gh auth status
| 退出碼 | 意思 |
|---|
0 | ✅ 登入成功，可以往下做 |
1 | 還沒好，等一下再查 |
🔴 看到「還沒好」不要重跑 gh auth login。
重跑一次就作廢一組碼，老師會愈打愈亂。第一次跑出來的那組碼，在他授權完之前一直有效。
輪詢節奏：每 10 秒查一次，最多等 10 分鐘
不要只等 5 分鐘。 現場實際發生過「重複三次認證才成功」——那不是重試三次終於通了，
是第三次才跑贏逾時。第一次還在找瀏覽器、第二次還在登入，第三次熟了才來得及。
等待期間每分鐘回報一次，例如：
「還在等你完成授權，不用急。完成之後我這邊會自己偵測到。」
這句話很重要。 沒有回報的話，老師會以為當掉了，跑去自己重跑 gh auth login——
那會作廢目前這組碼，等於親手把自己的進度歸零，然後又要重來一輪。
10 分鐘還沒好，才問他「你那邊卡在哪一步？」——還是不要自己重跑。
驗證：
gh auth status
預期輸出：
github.com
✓ Logged in to github.com account 你的帳號 (keyring)
- Active account: true
- Git operations protocol: https
- Token: gho_************************
- Token scopes: 'gist', 'read:org', 'repo', 'workflow'
Token scopes 裡要有 repo，否則後面建 repo 會失敗。
2-3 把 git 的憑證也接上去（本包最關鍵的一行）
gh auth setup-git
成功時沒有任何輸出（沒消息就是好消息）。
驗證——看所有層級，不要只看 --global：
git config --show-origin --get-all credential.helper
下面三種結果任一種都算通過：
| 你看到的 | 意思 | 判定 |
|---|
含 gh.exe' auth git-credential（或 /usr/bin/gh auth git-credential） | gh auth setup-git 生效了 | ✅ 通過 |
manager，來源是 C:/Program Files/Git/etc/gitconfig | Git for Windows 內建的 Git Credential Manager (GCM) 在管，一樣能用 | ✅ 通過 |
| 完全沒有輸出 | 沒有任何憑證管理員 | ⚠️ 這時才需要處理 |
🔴 給 AI agent 的重要提醒：不要用 git config --global --get-regexp credential 當判斷依據。
Windows 用 winget 裝的 Git for Windows 預設就帶 GCM，而且設定寫在 system 層不是 global 層。
只查 --global 會得到空結果，於是誤判成「setup-git 失敗」——但使用者的 git push 其實好好的。
這是本包最容易誤報的一項。
真正的判斷標準是 git push 會不會成功，不是設定檔長什麼樣子。設定看不出來但 push 得上去 → 通過，不要叫使用者去修一個不存在的問題。
兩種憑證管理員的差別（都能用，不用二選一）：
| gh auth setup-git | GCM（Git for Windows 內建） |
|---|
| 第一次 push 時 | 直接過，不問你 | 開瀏覽器讓你授權一次，之後就記住了 |
| token 存哪 | 作業系統憑證保管庫 | 作業系統憑證保管庫 |
| 要另外裝嗎 | 不用（跟著 gh） | 不用（跟著 Git for Windows） |
兩個都沒有的時候，git push 才會退回去要帳號密碼——而 GitHub 早就不接受密碼推送，所以一定失敗。gh auth setup-git 的價值是「保證有」，不是「唯一解」。
2-4 設定 Git 使用者資訊
每一個 commit 都會永久記錄你的名字與 email，公開 repo 任何人都看得到。
先檢查：
git config --global user.name
git config --global user.email
沒有任何輸出 = 尚未設定。 補上：
git config --global user.name "王小明"
git config --global user.email "12345678+你的帳號@users.noreply.github.com"
💡 強烈建議 email 用 GitHub 給的 @users.noreply.github.com 位址，
不要用學校信箱或私人 Gmail——避免公開 repo 把你的信箱送給爬蟲。
去哪裡拿：GitHub 網頁 → 右上角頭像 → Settings → Emails
→ 勾選 Keep my email addresses private → 上面就會顯示你的
數字ID+帳號@users.noreply.github.com。
進階（已登入 gh 的話可以一行拿到，跑不出來就走網頁那條路）：
gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'
2-5 把作品變成一個 repo 並上傳
進到你真的想備份的那個資料夾（不要另外建測試資料夾，用真作品動機才強）：
cd $HOME\Documents\我的教材
git init
git branch -M main
git add .
git commit -m "第一次備份我的教材"
指令在做什麼（給老師的白話版）：
| 指令 | 白話 |
|---|
git init | 跟這個資料夾說「開始幫我記錄版本」 |
git branch -M main | 把主線改叫 main（GitHub 的慣例，避免之後對不上） |
git add . | 把資料夾裡所有東西「放進打包箱」 |
git commit -m "..." | 蓋章存檔，引號裡寫你自己看得懂的說明 |
git init 後若出現 hint: Using 'master' as the name for the initial branch...
那是提示不是錯誤，git branch -M main 就是在處理它。
建立 GitHub repo 並一次上傳：
gh repo create 我的教材英文名 --private --source=. --push
參數逐字解釋：
我的教材英文名 — repo 名字，只用英數字和 -，不要中文、不要空白（例：my-teaching-materials）--private — 只有你自己看得到（研習一律先用 private，確定要公開再改）--source=. — 用「現在這個資料夾」的內容--push — 建好後立刻上傳
預期輸出：
✓ Created repository 你的帳號/my-teaching-materials on GitHub
https://github.com/你的帳號/my-teaching-materials
✓ Added remote https://github.com/你的帳號/my-teaching-materials.git
✓ Pushed commits to https://github.com/你的帳號/my-teaching-materials.git
2-6 驗證
眼睛看（推薦，老師的「哇」就在這一刻）：
gh repo view --web
瀏覽器會打開你的 repo，看到自己的檔案清單 = 成功。
純文字驗證（給 agent 判讀，不開瀏覽器）：
git remote -v
git log --oneline -1
gh repo view --json name,visibility,url
預期：
{"name":"my-teaching-materials","url":"https://github.com/你的帳號/my-teaching-materials","visibility":"PRIVATE"}
2-7 之後的日常（三行循環）
改完東西之後：
git add .
git commit -m "說明你這次改了什麼"
git push
老師只要記這三行就夠用一整年。
第三階段（跨電腦驗收）：確認東西真的還在
動機：第二階段結束時，老師心裡其實半信半疑——「真的存上去了嗎？」
這一階段就是把疑慮變成證據。最好安排在隔天或換一台電腦時做。
情境 A：換一台電腦（或研習現場的第二台）
新電腦上依序做四件事：
# 1. 先跑 00-env-setup 裝好 git 與 gh（略）
gh auth login # 2. 登入（同 2-2）
gh auth setup-git # 3. 接上 git 憑證（同 2-3）
cd $HOME\Documents
gh repo clone 你的帳號/my-teaching-materials # 4. 抓回來
這裡剛好可以回扣「兩道門」：gh repo clone 走 API 門 找到 repo，
實際下載檔案走 Git 協定門。因為 gh auth setup-git 兩道都開了，所以一行就過。
私有 repo 也可以直接 git clone <網址>，同樣不用再輸入任何密碼。
情境 B：同一台電腦、隔天回來
cd $HOME\Documents\my-teaching-materials
git pull
預期輸出（二擇一）：
Already up to date.
或（有更新時）：
Updating a1b2c3d..e4f5g6h
Fast-forward
教案.md | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
驗收清單
dir
git log --oneline -3
三項都過 = 東西真的在雲端，不是只在你那台電腦。
建議在研習現場做的「活體演練」
- A 電腦改一行字 →
git add . → git commit -m "測試" → git push
- B 電腦（或隔壁老師的電腦）
git pull
- 改動出現了
這一刻老師才會真的相信「它是活的」，而不是又一個要背的指令。
順便回答「那我電腦壞掉怎麼辦？」
四行救回來：
# 新電腦：跑完 00-env-setup 之後
gh auth login
gh auth setup-git
gh repo clone 你的帳號/my-teaching-materials
關於「刪除」：本包刻意不教
本包不教 gh repo delete，也不教 rm -rf。 理由有三：
- 兩個都不可逆。
gh repo delete 刪雲端、rm -rf 刪本機，都沒有資源回收桶。
對零基礎老師來說，一個打錯路徑就是災難。
- 和本包的目的相反。這整包在教「不要再弄丟東西」，
中間插一個「會把東西弄不見」的指令，風險遠大於效益。
- 技術上也會卡：
gh auth login 預設拿到的 token 沒有 delete_repo scope，
gh repo delete 會直接回 HTTP 403，要另外跑
gh auth refresh -h github.com -s delete_repo 加權限——
研習中途卡在這裡，時間全沒了。
真的要刪：請到 GitHub 網頁 → 你的 repo → Settings → 最下面 Danger Zone → Delete。
網頁會要求你手動打出 repo 的完整名稱才肯刪。這個「刻意的麻煩」就是保護，不要繞過它。
常見坑
| 症狀 | 原因 / 解法 |
|---|
gh auth login 跑下去沒反應、卡住 | 這是互動指令，agent 在自己的 shell 跑會被逾時砍掉。改用獨立視窗＋輪詢（見 2-2） |
| 打完八碼，agent 一直說沒收到驗證，一直給新碼 | 最常見的循環。 gh 被 agent 的逾時砍掉了，沒人在等 token。
解法：在獨立視窗跑 gh auth login，agent 只負責輪詢 gh auth status（exit 0 才算成功），不要重跑 login（見 2-2） |
| 八碼怎麼打都說錯 | 多半是看到舊碼——login 被重跑過，舊碼已作廢。以最新那個視窗顯示的碼為準 |
| 當天現場才註冊新帳號的人，登入特別慢 | 全新帳號的第一次登入不只是打八碼，中間常常還夾著
信箱驗證 ＋ 首次登入的裝置確認 ＋ 有些人會被要求當場設 2FA。
這些全部要塞進授權的時間裡，比老手慢好幾倍是正常的。
→ 輪詢一律給滿 10 分鐘，並每分鐘回報一次讓他安心。
→ 根本解法還是前一晚在家裡先把帳號註冊好、順便登入一次（見 2-1）——
隔天現場就只剩「打八碼、按 Authorize」兩個動作，幾十秒的事 |
| 註冊時拼圖一直跳、解十題也過不了 | 不是你解錯——那是風險評分，同一個 IP 多人註冊會被當成機器人批次開帳號。
解法：改用手機熱點（換 IP，最有效）／關 VPN／換無痕視窗或沒裝擴充的瀏覽器／不要連續猛按。
根本解法是前一晚在家裡註冊好（見 2-1） |
| 8 碼驗證碼失效 | 裝置碼流程只有幾分鐘有效。研習現場數十人同時登入時特別容易踩到：講解一拖，碼就過期了。重跑 gh auth login 拿新碼即可 |
| 研習現場一堆人同時登不進去 | 幾十台電腦同時開 github.com/login/device＋網路壅塞。建議：請大家前一天先註冊好帳號，現場**分批（一排一排）**進行，講師先示範完整一輪再放行 |
git push 跳視窗要帳號密碼 | 這台完全沒有憑證管理員。跑 gh auth setup-git（見 2-3）。GitHub 已不接受密碼推送，硬輸入也會失敗 |
git push 開了瀏覽器要你授權 | 正常的，那是 Git for Windows 內建的 GCM 在做事。授權一次之後就記住了，不用改成 gh |
| 明明 push 得上去，卻被判定「setup-git 沒做」 | 誤判。GCM 的設定在 system 層，用 git config --global 查不到。改用 git config --show-origin --get-all credential.helper（見 2-3） |
git commit 說 Author identity unknown | 回去做 2-4 的 git config --global user.name / user.email |
gh repo create 回 HTTP 403 / 權限不足 | gh auth status 看 有沒有 ；沒有就 |
成功訊號（機器可判讀）
執行以下檢查，agent 依規則判定：
gh auth status
git config --show-origin --get-all credential.helper
git config --global user.email
git -C <專案資料夾> remote -v
git -C <專案資料夾> log --oneline -1
判定規則：
| 檢查項 | 通過條件 |
|---|
GH_AUTH | gh auth status 含 Logged in to github.com |
GH_SCOPE_REPO | Token scopes 字串含 repo |
GH_SETUP_GIT | credential helper 含 gh ... auth git-credential 或 含 manager（GCM）。
兩者都沒有但 STAGE2_PUSH 成功 → 一樣記 OK（見下方註記） |
GIT_IDENTITY | user.name 與 user.email 皆非空 |
STAGE1_CLONE | 目標資料夾存在，且 git remote -v 有 origin |
STAGE2_PUSH | gh repo view --json url 回得出網址，且 git log 至少一筆 commit |
STAGE3_PULL | git pull 回傳 Already up to date. 或成功 Fast-forward |
最後輸出這一段（未執行的階段填 SKIP，失敗填 FAIL:<原因>）：
GITHUB_PACK_STATUS=OK
GH_AUTH=OK
GH_SCOPE_REPO=OK
GH_SETUP_GIT=OK
GIT_IDENTITY=OK
STAGE1_CLONE=OK
STAGE2_PUSH=OK
STAGE3_PULL=SKIP
只要有任何一項是 FAIL，GITHUB_PACK_STATUS 就必須是 FAIL。
⚠️ 唯一例外：GH_SETUP_GIT。
憑證管理員的設定可能寫在 system 層（Git for Windows 內建的 GCM），查不到不代表壞掉。
只要 STAGE2_PUSH 是 OK，就把 GH_SETUP_GIT 記成 OK——push 得上去就是最終證據。
不要因為這一項就叫使用者去修一個不存在的問題。
回報範本
## GitHub 連接結果
**目前階段**：① 消費端 / ② 生產端 / ③ 跨電腦驗收
- 先備條件（00-env-setup）：git <版本> / gh <版本> ✅
- gh 登入：✅ 帳號 `<帳號>`（scopes 含 repo）
- gh auth setup-git：✅ 兩道門已開（credential helper 指向 gh）
- Git 使用者資訊：`<name>` / `<...@users.noreply.github.com>` ✅
### 階段一：消費端
- clone 目標：`<repo 網址>`
- 本機位置：`<路徑>`
- 結果：✅ 成功 / ⚠️ 改用 ZIP 下載 / ❌ 失敗（原因）
### 階段二：生產端
- repo：`<帳號>/<repo名>`（private）
- 網址：`<url>`
- 首次 commit：`<commit 訊息>`
- push：✅ 成功 / ❌ 失敗（原因）
### 階段三：跨電腦驗收
- 方式：換電腦 clone / 隔天 git pull
- 結果：✅ 檔案與 commit 紀錄都在 / ❌ 不一致（說明）
### 待處理
- <若有，列出；沒有就寫「無」>
