讓 AI 幫你改作業，而且你看得見它到底做了什麼。
一套給教師用的作業評分框架。你不需要會寫程式——把材料丟進資料夾、 跟 AI 聊幾句、說一聲「開始評分」，就會拿到成績表、每位學生的個別評語、 一份教學總覽報告，以及一份用來查核這次評分可不可信的揭露報表。
開發過程做了 10 次實測（4 個模型 × 3 個平台）。其中 3 次評分者失效， 包括一次分數完全由學號的餘數生成、評語 93.5% 重複的假評分。 三次全部被揭露報表抓到。
但框架不會擋下它們——因為一旦設了及格線，AI 最省力的做法是回頭改分數來通過， 而不是重新認真評。那樣你反而看不到問題。 所以：數字全部攤開給你，判斷權在你。
English summary
GLASS (Glass-box grading) is a rubric-based grading framework for teachers who want to use an LLM to grade student work — without having to trust it blindly.
It does not claim to make AI grading accurate. It claims something narrower and testable: when a grading run goes wrong, you will see it within two minutes.
Across 10 real grading runs (4 models × 3 platforms), 3 raters failed — including one whose scores were generated from student-ID modulo arithmetic with 93.5% duplicated feedback. All three were caught by the disclosure report. None were blocked: the framework deliberately sets no pass/fail threshold on a rater's own output, because a threshold just teaches the model to rewrite scores until it passes, destroying the diagnostic signal.
Docs are in Traditional Chinese. The tooling is language-agnostic — the rubric, dimensions, scale and column names all come from your own config file.
不用安裝任何東西，範例/ 裡有一份跑完的實例（3 位虛構學生）：
| 檔案 | 這是什麼 |
|---|---|
| 總覽報告 | 給教師的教學報告：分數分布、常見錯誤、質性特徵、示範名單、教學建議 |
| 揭露報表 | 給教師查 AI 的報表：這次評分到底有沒有認真讀 |
| 一份低分學生的評語 | 亮點／待改進／具體建議／逐字引證 |
| AI 自己寫的執行紀錄 | 我做了哪些判斷、哪幾份最沒把握、哪些數字對我不利 |
| 評分細則 | 把 rubric 翻譯成「不同人看了會做出相同判定」的程度 |
最能看出這套框架特色的是執行紀錄——裡面沒有「全部通過」這種話， 只有具體的取捨與不確定性。
開一個新資料夾（例如 我的作業評分/），把本專案的 評分框架/ 整包複製進去。
我的作業評分/ ← 你的工作區
└── 評分框架/ ← 從本專案複製進來，裡面不用動
當 AI 工具問你「要開放哪個資料夾」時，請選 整個工作區：
我的作業評分/ ← ✅ 開放「這一層」
├── 評分框架/ ← ❌ 不要只開放這一層
└── 材料/ ← ❌ 也不要只開放這兩個
為什麼：AI 需要在工作區建立 _設定/、作業文本/、評分產出_XXX/ 三個資料夾。
只開放 評分框架/ 的話，它會被迫把你的成績檔案建在框架資料夾裡——
之後更新框架就會蓋掉你自己的資料。
框架有防呆：權限不足時 AI 會停下來請你調整，而不是亂寫。
在工作區建一個資料夾叫 材料，把手邊有的東西全部丟進去。
格式不拘、命名不拘、要不要分子資料夾也不拘。 Excel、Word、PDF、照片、掃描檔、純文字都可以。AI 會自己去認。
| 類別 | 例子 |
|---|---|
| 學生名單 | 學生名單.xlsx、修課清單.csv |
| 作業題目 | 作業說明.docx、第三次作業.pdf，直接貼在對話裡也行 |
| 評分標準 | rubric 的圖片、PDF、Word，或你口述給 AI |
| 學生作答 | 一個資料夾裝所有人，或每人一個子資料夾；PDF／Word／照片皆可 |
| 參考教材（選用） | 講義、投影片。有的話 AI 才能判斷「概念用對了沒」 |
檔名裡有學號會讓辨識更順利，但不是必要的。認不出來 AI 會列清單問你。
開一個 AI 對話（Claude、Gemini、ChatGPT、Codex，或任何有讀檔能力的 agent）， 把工作區給它，然後說：
「請依照
評分框架/AGENTS.md開始。」
接下來 AI 會自己做完這些，過程中會停下來問你：
| 階段 | AI 做什麼 | 你要做什麼 |
|---|---|---|
| ① 盤點 | 掃描 材料/，認出哪個是名單、哪個是作答 |
確認它認對了 |
| ② 補齊 | 列出缺什麼、認不出什麼 | 補檔案，或告訴它那是什麼 |
| ③ 訂標準 | 跟你討論評分標準，寫成細則給你確認 | 這步最重要，請認真看 |
| ④ 準備 | 轉檔、建立統一文本、跑檢查 | 等它跑完 |
| ⑤ 評分 | 等你說「開始評分」才動手 | 說「開始評分」 |
| ⑥ 產出 | 成績表、每人一份評語、兩份報告 | 收成果 |
AI 不會在你說「開始評分」之前開始評分。 前面四步都可以來回修改。 實測中，四個平台上的 AI 都會在階段 ⑤ 前停下來等你。
| 檔案 | 內容 |
|---|---|
成績_<代號>.csv |
全班成績表，可直接匯入 Excel |
評語/ |
每位學生一份，含亮點、待改進、具體建議、原文引證 |
總覽報告_<代號>.pdf |
給你看的教學報告 |
揭露報表_<代號>.pdf |
給你查 AI 的報表，一頁看完 |
對帳結果_<代號>.json |
客觀事實有沒有填錯（人數、字數、繳交狀態…） |
怎麼判讀，見 評分框架/規範/教師指南.md。
這一節你一樣不用打任何指令。 下面每一格的「跟 AI 說」直接複製貼上就行。
| 你想做的事 | 跟 AI 說 |
|---|---|
| 讓另一個 AI（或另一次執行）再評一遍 | 「再用代號 GPT5 評一次。」（代號自己取，能區分就好） |
| 把自己的評分也放進來比 | 「我要自己評，代號用 Human_我。請幫我準備一份可以填的表，我填完你再匯入。」 |
| 比較結果 | 「跑比較分析，用 Human_我 當基準。」 |
你會拿到一份比較報告，回答三個問題：
- 誰比較嚴？——寬鬆度、Bland–Altman 圖
- 誰跟誰排序比較像？——相關矩陣、階層聚類
- 分歧在哪裡？——操作化指紋熱圖，一張圖告訴你各評分者在哪一題的標準不同
統計方法包含加權 Cohen's κ、Gwet AC1/AC2、Krippendorff 序位 α、ICC、 概化理論（兩面向與三面向）。全部自行實作並附驗證案例 （對照 Shrout & Fleiss 1979 與 Krippendorff 官方範例）。
怎麼讀那份報告，見 教師指南 §4。
實測發現：評分者的整體寬鬆度只解釋 0.1% 的分數變異， 而「題目 × 評分者」交互作用解釋 10.3%—— 也就是說，「誰認為哪一題該嚴」比「誰比較嚴」重要 100 倍。
所以判準本身值得單獨保存與交換：
| 你想做的事 | 跟 AI 說 |
|---|---|
| 把這次的評分標準打包 | 「把這次的評分標準打包成模組，作者寫我的名字。」 |
| 用同事給的標準 | 「請匯入 模組包_XXX，然後照它評。」 |
| 明年同一份作業再用 | 「用去年的 模組包_XXX 評這次的作業。」 |
| 看看手上有哪些 | 「列出目前有哪些評分模組。」 |
AI 會產生一個 模組包_<名稱>/ 資料夾，裡面有判準檔與 SHA-256 校驗值。
把整個資料夾複製給對方即可。匯入時工具會檢查結構相不相容，不相容會擋下並說明差在哪。
這樣就能做**「同一份判準 × 不同模型」或「同一個模型 × 不同判準」**的對照， 而且事後可以用雜湊證明用的是哪一份。
跟 AI 說 「跑一下進度檢查。」 它本來就會在評完約 10 份時主動跑一次並回報——這是刻意的設計： 評到一半發現問題，重來的成本是 10%；評完才發現，成本是 100%。
如果 AI 說它不會用這些工具，把這句話給它： 「請完整讀
評分框架/AGENTS.md，特別是第 7 節。」
整個框架只有一條分界線，判準是同一個問題：
修正這一項，需不需要改動評分者的判斷？
| 對帳項 | 揭露項 | |
|---|---|---|
| 真值來源 | 評分者之外（名冊、提取結果、檔案系統、算術） | 評分者自己的產出 |
| 例子 | 人數、字數、繳交狀態、引文能不能在原文找到 | 分數分布、評語重複率、向度共變、每份秒數 |
| 設門檻嗎 | 是，未通過必須修正 | 否，永遠不設 |
早期版本曾對揭露項設過門檻。實測結果：AI 事後填了錯誤的時間碼 （自稱花了 4 小時，實際 2 小時），並出現「評分 → 跑驗證 → 改分數直到通過」的行為。
拿掉門檻之後，成功的產出反而主動寫出對自己不利的事——包括一次 AI 自陳 「我不小心讀到了明文禁止閱讀的稽核者手冊」，那是沒有任何機制抓得到的違規。
完整的設計脈絡、10 次實測的結果、以及八種已知失效模式，見
設計筆記.md。那份文件記錄的是「試過什麼、什麼失敗了」，
比規則本身更有參考價值。
Q：我沒有 rubric，只有大概想法。 可以。第 ③ 步 AI 會跟你對談，把你的想法整理成可操作的評分細則給你確認。
Q：學生作答是手寫拍照。 可以。AI 會先做文字辨識，並在報告中標記辨識品質有疑慮的份數請你確認。
Q：PDF 產不出來，出現 OSError: cannot load library 'libgobject-2.0-0'。
這是 Windows 缺 GTK runtime。框架會自動改用其他方式轉檔（pandoc、wkhtmltopdf、
Chrome headless），全部失敗時會產出 HTML 並明確告訴你——不會靜默略過。
你也可以直接用瀏覽器開 HTML，按 Ctrl+P → 另存為 PDF。
想修好自動轉檔：安裝 GTK for Windows。
Q：我要改評分標準。 第 ③ 步定案前隨時改。定案後要改也可以，但已評的部分要重評，AI 會告訴你影響幾份。
Q：AI 評完我不同意某幾份。 成績表是你的，直接改。框架的定位是輔助與稽核，最終成績一律由你決定。
Q：這會花多久？ 70 份左右的文字作業，約 40–60 分鐘。手寫辨識會更久。 實測中認真評分的 AI 是每份 43–55 秒。
Q：AI 說它評完了，我怎麼知道是真的？ 看揭露報表的四個數字：每份秒數、評語重複率、引文可溯率、向度共變。 判讀方式與實測基準見 教師指南 §2。
Q：這套框架綁定特定的 AI 嗎？
沒有。AGENTS.md 是通用的 agent 執行協定，實測涵蓋 Claude、Gemini、GPT 三家。
工具都是純 Python，不呼叫任何 API。
Q：可以用在中文以外的課程嗎？ 可以。向度名稱、級分名稱、欄位名稱全部來自你自己的設定檔，工具不預設語言。 不過目前文件只有繁體中文。
你不用管這一節。 電腦上要有 Python 3.9 以上（多數電腦已經有）， 其餘套件 AI 會在準備階段自己檢查、自己安裝，缺什麼它會告訴你。
想自己先裝好的話：pip install -r requirements.txt
| 套件 | 用途 | 沒裝會怎樣 |
|---|---|---|
pyyaml |
讀設定檔 | 不能用，必裝 |
openpyxl |
讀 .xlsx 名單 |
名單改存成 .csv 就不用裝 |
pymupdf |
讀 PDF 作業 | 沒有 PDF 作業就不用裝 |
python-docx |
讀 Word 作業 | 沒有 Word 作業就不用裝 |
weasyprint、markdown |
產生 PDF 報告 | 自動改用其他方式；全失敗時給你 HTML |
numpy、matplotlib |
多評分者比較與圖表 | 只影響「進階：控制變異」那一節 |
├── README.md 你正在看的檔案
├── CHANGELOG.md 版本歷程（唯一放版本號的地方）
├── 設計筆記.md 為什麼這樣設計、試過什麼、什麼失敗了
├── requirements.txt
├── LICENSE MIT
├── 評分框架/ ← 複製「這一包」到你的工作區
│ ├── AGENTS.md AI 的執行協定（也是工具的行為規格）
│ ├── CLAUDE.md 轉接檔，3 行
│ ├── 規範/
│ │ ├── 產出規格.md 給 AI：格式細節
│ │ └── 教師指南.md 給你：怎麼判讀、怎麼查 AI、可以叫 AI 做什麼
│ ├── 範本/ 設定與評分細則的範本
│ └── 工具/ 10 支工具 + 3 個程式庫
├── 稽核/
│ └── 稽核者手冊.md ⛔ 不要複製進工作區（見下）
├── 範例/ 3 位虛構學生的完整實例
└── 文件PDF/ 上述文件的 PDF 與 HTML 版，方便列印
那份文件寫的是「怎麼查出 AI 有沒有認真評」的完整判準與實測基準。
如果 AI 讀得到它，最省力的做法就是對著那些判準最佳化，而不是認真評分 ——那樣判準就同時失去了診斷力（Goodhart 定律）。
所以它留在 repo，不隨 評分框架/ 複製進工作區。你要看隨時可以看。
MIT License。歡迎自由使用、修改、散布。
最歡迎的貢獻是實測資料，特別是失效案例。 如果你用這套框架跑出了有意思的結果——某個模型在你的科目上出現奇怪的樣態、 某個揭露指標誤判了、或是你找到框架抓不到的新失效模式——請開一個 Issue。
框架裡的每一條參考基準都來自實測，樣本目前還很小 （10 次執行、2 份作業、1 個學科、1 位人工評分者）。 所有基準都應該視為暫定值，多一份資料就多一分校準。