檢查與疑難排解
怎麼執行檢查
- 用 VS Code 開啟 testbank-starter 資料夾 (出現「是否信任作者」時選「是」)。
- 選單 終端機 (Terminal) > 執行工作… (Run Task…) > 檢查環境。
- 下方面板會逐項檢查, 約一到兩分鐘。Windows 問是否允許變更時按「是」。
檢查可以重複執行, 不會弄壞任何東西。修好一項之後, 再執行一次就好。
全部通過的樣子
每一項前面都是「[通過]」, 最後出現這個框:
==============================================================
★ 全部通過, 可以上課 ★
請打開 tools/_check/test-exam.pdf 看一眼, 確認內容正常。
==============================================================
各項的意思:
| 項目 | 檢查什麼 |
|---|---|
| 1. Python | 有沒有裝 Python、版本夠不夠新 |
| 2. Python 套件 | Agent 讀 PDF、讀 Word 檔、驗算答案要用的元件 (資料夾裡已附, 會自動安裝) |
| 3. LaTeX | 有沒有裝排版軟體 |
| 4. 測試考卷 | 實際排一份有中文、數學式、表格與圖的考卷, 確認排得出來 |
| 5. 上課用資料夾 | 兩個 skill 是否齊全 |
| 6. Codex 保護模式 | (只有 Windows) Python 與 LaTeX 的安裝方式和 Codex 合不合。用 Claude 的老師可略過 |
通過後, 請在 VS Code 左邊的檔案清單點開 tools/_check/test-exam.pdf 看一眼。上課前還沒裝看 PDF 的擴充功能, 所以可能顯示成一堆亂碼, 這是正常的; 想現在確認的話, 到檔案總管找到這個檔案, 用瀏覽器或 PDF 閱讀器開啟。
找不到「檢查環境」這個選項
- 確認 VS Code 開的是 testbank-starter 資料夾本身: 左邊檔案清單最上層應該直接看到
courses、fonts、tools。如果看到的是另一層testbank-starter, 代表開到了上一層, 請重新用「開啟資料夾」選裡面那一層。 - 確認有按「是, 我信任作者」。沒按的話, 視窗上方會有一條「受限模式」的藍色提示, 點它再選信任。
- 確認壓縮檔有解開, 不是直接在壓縮檔裡開。
未通過的項目怎麼處理
Python 未通過, 或出現「python 不是內部或外部命令」
- 還沒裝, 或安裝時沒有勾 Add python.exe to PATH: 照安裝說明 2-1 重新安裝一次 (同一個安裝檔再開一次, 選 Modify 或先解除安裝再裝)。
- 剛裝好: 把 VS Code 所有視窗都關掉再重開。VS Code 只在啟動時認一次電腦上有哪些程式。
- 顯示「版本太舊」: 電腦上有另一個舊版的 Python。照安裝說明裝 3.13 版, 並勾 Add python.exe to PATH。
套件未通過
上課用資料夾已經附了 Windows 加 Python 3.13 要用的元件, 正常情況不需要網路。未通過時:
- 你的 Python 不是 3.13 版, 或用的是 Mac: 這時會改從網路下載, 請確認網路暢通後再執行一次。第一次可能要幾分鐘。
- 訊息裡有
tools/wheels找不到之類的字樣: 資料夾不完整, 請重新下載並解壓縮。 - 其他情形: 把這一項底下的錯誤訊息拍下來, 帶到課堂。
缺少微軟的 Visual C++ 執行元件
比較新、沒裝過什麼軟體的 Windows 電腦會遇到。檢查工具會自動替你安裝 (安裝程式已附在資料夾裡), 過程中 Windows 會問是否允許變更, 請按「是」。
如果你按了「否」或安裝失敗: 再執行一次檢查, 這次按「是」。
Word 轉檔 (pandoc) 未通過
這個元件只在原始檔是 Word 檔時才用到, 工作坊當天用的是 PDF, 不影響上課。請確認網路後再執行一次檢查; 還是不行就先不管它, 帶到課堂處理。
XeLaTeX 未通過 (找不到 xelatex)
- 還沒裝 LaTeX: 照安裝說明 2-3 安裝。
- 剛裝好: 把 VS Code 所有視窗都關掉再重開, 重新檢查。
- 顯示「找到但無法執行」: 重新開機後再檢查一次; 仍然不行, 把 MiKTeX 解除安裝後重裝。
測試考卷未通過
- 「編譯失敗」並提到缺少某個
.sty檔: MiKTeX 安裝時「Install missing packages on-the-fly」沒有設成 Yes。開啟開始功能表的 MiKTeX Console, 左邊選 Settings, 把「Package installation」那一項改成 Always (即自動安裝), 再重新檢查。這次需要網路, 可能要幾分鐘。 - 「無法覆寫 test-exam.pdf」: 你正開著這份 PDF。把它關掉再檢查。
- 等了很久沒有反應: 第一次排版時 LaTeX 要建立字型的索引, 一分鐘內屬正常; 面板每 20 秒會印一行「仍在編譯」。超過十分鐘, 請確認網路後重新執行。
- 跳出一個 MiKTeX 的視窗問要不要安裝套件: 按 Install; 之後照上面第一點把設定改成自動安裝。
中文字型
- 通過, 但提醒「上課用資料夾不完整: fonts 資料夾裡的隨附字型不見了」: 考卷還是做得出來, 只是會用電腦內建的字型, 外觀和別人的不一樣。重新下載上課用資料夾, 解壓縮時不要漏掉
fonts資料夾。 - 未通過 (找不到可用的繁體中文字型): 資料夾裡的字型不見了, 電腦也沒有內建的繁體中文字型。重新下載上課用資料夾即可。
兩個 skill 未通過
資料夾不完整 (多半是只解壓縮了一部分, 或搬動時漏了以 . 開頭的隱藏資料夾)。重新下載、整個解壓縮, 再用 VS Code 開啟新的資料夾。
安裝位置 (Codex 保護模式)
只有 Windows 會出現這一項。用 Claude 的老師可以不理會。
- 通過: Python 與 LaTeX 都是「為所有使用者安裝」, Codex 可以正常使用。
- [注意]: 有軟體是「只為我安裝」。請到 Windows 的「設定 > 應用程式 > 已安裝的應用程式」把 Python 或 MiKTeX 解除安裝, 再照安裝說明重裝成「為所有使用者安裝」, 裝完把 VS Code 完全關閉再重開, 重新檢查。
- 未通過: 軟體是「只為我安裝」, 而這台電腦的 Codex 已經設成完整保護模式, 這個組合下 Codex 排不出考卷。處理方式同上: 到 Windows 的「設定 > 應用程式 > 已安裝的應用程式」把 Python 或 MiKTeX 解除安裝, 再照安裝說明重裝成「為所有使用者安裝」, 裝完把 VS Code 完全關閉再重開, 重新檢查。
上課時可能遇到的狀況
在 VS Code 裡點開 PDF, 看到一堆亂碼
還沒安裝 LaTeX Workshop 這個擴充功能。VS Code 本身不會顯示 PDF。照講義「開始之前」安裝後, 把那個分頁關掉再點開一次。
Agent 說「找不到 python」或「找不到 xelatex」, 但檢查明明通過
- 軟體是在 VS Code 開著的時候裝的: 把 VS Code 所有視窗關掉重開。
- 用 Codex、而且第 6 項不是「通過」: 見上面的安裝位置。
Agent 每次排考卷都要等將近一分鐘
你還沒有以自己的身分跑過「檢查環境」。執行一次檢查, 之後就會變快。
Codex 跳出視窗, 問是否允許它做某件事
這是正常的保護機制, 不是出錯。怎麼判斷要不要允許, 見 Codex 版講義的「Agent 停下來問你的時候」。
Codex 說無法在某個資料夾裡建立或修改檔案
Codex 在 Windows 上的一個已知狀況: 它自己用指令建立的資料夾, 之後反而寫不進去, 於是跳出核可視窗或回報失敗。處理方式: 視窗出現時, 確認路徑在 testbank-starter 資料夾裡面, 就按允許。如果它一直失敗, 把畫面留著, 請講者過去看。
Codex 的 Windows 設定一直失敗或反覆出現
按畫面上的 Continue without administrator access 繼續使用。這個模式的保護比完整模式弱一級, 但 Codex 仍然只能修改 testbank-starter 資料夾裡的東西。
不小心點開了程式檔或設定檔
左邊檔案清單裡 .claude、.agents、.vscode、tools 底下的檔案是給 Agent 和檢查工具用的。點開看沒有關係, 不要改它; 如果不小心打了字, 關閉分頁時選「不要儲存」。
還是解決不了
把檢查結果整個畫面拍下來 (或複製面板裡的文字), 上課時提早十分鐘到, 現場處理。