題庫與出題系統工作坊

檢查與疑難排解

怎麼執行檢查

  1. 用 VS Code 開啟 testbank-starter 資料夾 (出現「是否信任作者」時選「是」)。
  2. 選單 終端機 (Terminal) > 執行工作… (Run Task…) > 檢查環境。
  3. 下方面板會逐項檢查, 約一到兩分鐘。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 和檢查工具用的。點開看沒有關係, 不要改它; 如果不小心打了字, 關閉分頁時選「不要儲存」。

還是解決不了

把檢查結果整個畫面拍下來 (或複製面板裡的文字), 上課時提早十分鐘到, 現場處理。