為學習者而建構
你知道如何編寫程式碼。但從這裡你看不到的是教室：三十個孩子在早上 9:05 從同一個學校位址打開這個東西、一台共用的 Chromebook、一個答案近在咫尺（只需檢視原始碼）的測驗、一個會幫他們做功課的導師、以及一個全班可以花費的金鑰。請按順序堅持以下原則，並用淺白的語言說明：你幫助的人可能從未讀過程式碼。
這裡的命令使用
viable-harness。在它上架 npm 之前，請改用npx github:VIABLE-Learning-Lab/viable。
1. 先問清楚再開始建構
用一則訊息詢問你無法從請求中得知的事項，然後將答案寫入專案根目錄的 LEARNERS.md 中。
- 學習者是誰？ 13 歲以下、13 到 17 歲或成年人：這會改變哪些是被允許的。
- 他們事後應該能夠做什麼？ 一句話。這決定了這個工具的用途。
- 在哪裡以及有多少人？ 在課堂時間使用學校電腦，還是在家裡？同時有多少人使用？他們是共用電腦嗎？
- 你有什麼可以運用的資源？ Chromebook 無法執行伺服器或下列命令。誰來託管它？
- 學習者使用時需要 AI 嗎？ 通常不需要：你可以建立一個沒有 AI 的測驗。
- 會保留什麼資料，誰能看到它？ 需要姓名，還是一個代碼就夠了？
- 下個學期誰來維護它？ 其他人會依賴它嗎？
如果他們希望 AI 回覆學習者，請在同一則訊息中詢問這些問題，因為每一個都可能改變答案：
- 誰的帳戶付費，其提供者允許這些學習者使用嗎？ 現在就說清楚，對於任何 18 歲以下的人，老師自己的金鑰通常不能用於此目的。references/learner-data.md 說明了三家提供者的要求。在發送訊息之前請先閱讀它。
- 當學習者說出令人擔憂的話時，會通知誰？ 以及要多快？
- 一天最多可以花費多少？ 當達到上限時學習者會看到什麼？
- 對話會保留多久？
將以下內容加入到專案的 AGENTS.md 或 CLAUDE.md 中，以便後續的工作階段能遵守它：
學習者會使用這個工具。請先閱讀 LEARNERS.md。絕對不要將模型金鑰、有分數的答案金鑰或學習者的姓名放在頁面或提示詞中。在分享之前，請執行 `viable-harness review`。
2. 建立能完成任務的最簡方案
每一步都會增加一些需要人來執行、付費和負責的東西。請停在能完成任務的最低步驟，並告訴他們原因。
| 步驟 | 這是什麼 | 需要承擔什麼 |
|---|---|---|
| 0. 一個頁面 | 沒有帳號，伺服器上不儲存任何東西，學習者使用時沒有 AI | 幾乎不需要。大多數測驗、遊戲和模擬都屬於此類 |
| 1. 一個會記得的頁面 | 在班級代碼下儲存工作，沒有姓名 | 一個有規則的資料庫，以及刪除所保留的資料 |
| 2. 學習者旁邊的 AI | 一個回覆學習者的模型 | 一個持有金鑰的伺服器、每個班級的預算、AI 的規則、測試、當學習者說出令人擔憂的話時該怎麼辦，以及，由於必須有成人能夠閱讀，所以還需要一個資料庫和一個給老師的頁面。這就是一個小頁面變成應用程式的地方： 根據我們的經驗，連同測試大約一千行程式碼 |
| 3. 姓名和記錄 | 班級名單、個人作業、成績 | 資料的規則、保留多久，以及通常需要學校的同意書 |
| 4. 一項研究 | 同意書、條件、匯出 | 一個審查委員會，以及哪個版本做了什麼的記錄 |
無論誰要求，都要停下來並告知他們， 並提供最值得建構的鄰近方案：
- 撰寫 IEP、504 計畫、行為計畫或進度報告的 AI。它們需要來自多個來源、長時間的資訊（Common Sense）。
- 一個沒有成人能閱讀的、與兒童的開放式聊天。
- 任何自行決定成績、安置或懲罰的東西。
如果有真正的學習者會使用它，它就再也不是原型了。 「我自己做的」這句話並不能讓工具免於學校的審查（CoSN）。早點告訴他們。
3. 從步驟 2 開始，決定誰來運行什麼
技能會塑造你寫出來的東西。在課堂上，仍然需要有人持有金鑰、監控預算並為此負責。提供這些選項，並說明各自需要付出的代價，讓他們選擇。
| 他們想要 | 使用這個 | 他們仍然需要做 |
|---|---|---|
| 一個有 AI 導師的班級，沒有自己的頁面 | VIABLE 學習平台：告訴它你在教什麼 | 不需要建構任何東西，所以在開始建構任何東西之前先告訴他們 |
| 他們自己的頁面，但由別人管理金鑰、限制和流量 | 使用 VIABLE API 作為模型端點：每個班級一個金鑰，各有自己的每分鐘請求數、每日 token 數和每月成本，以及可供查看的使用情況 | 一個持有金鑰的小型伺服器 |
| 他們自己的頁面和他們自己的模型帳戶 | 他們自己的伺服器，採用 references/classroom.md 中的模式 | 全部 |
| 所有東西都在他們自己的伺服器上 | VIABLE Engine | 執行一個伺服器 |
| 一項有同意書和條件的研究 | VIABLE 開發者平台 | 不需要託管任何東西 |
如果學習者未滿 18 歲，在依賴 VIABLE 選項之前，請讓他們詢問 VIABLE Lab 有哪些適用，如同對待任何提供者一樣。這個技能無法為他們回答這個問題，你也不行。
4. 尋找所需的資源，而不是猜測
- 標準與技能：
viable-harness catalog "<幾個字>"可以找到開放標準、資料集和工具及其授權條款。在依賴某個資源之前，請先檢查其授權條款。 - 學習者常犯的錯誤：
viable-harness misconceptions "<幾個字>"，適用於數學。根據這些來建構錯誤答案和提示。 - 研究建議的做法：
viable-harness guidance "<幾個字>"提供在教學某個時刻該做什麼的建議，每個建議都會引用其研究來源。請保留來源，並且不要引用非來自來源的研究：虛構的引用很常見。
當 Harness 的 MCP 伺服器連接後，find_public_goods 工具、find_misconceptions 工具和 find_guidance 工具也能做到同樣的事情。
5. 在建構過程中堅持這些原則
在為步驟 2 到 4 編寫任何程式碼之前，請先閱讀 references/classroom.md 和 references/learner-data.md。對於會回覆學習者的 AI，也請閱讀 references/ai-beside-learners.md。
- 金鑰和 AI 的提示詞必須留在伺服器上。 頁面會呼叫你的伺服器。
- 按每個學習者或每個班級計算，絕對不要按位址計算。 一所學校通常是一個位址。使用班級代碼且沒有姓名時，你無法區分不同的學習者：按每個班級計算，並對每個瀏覽器設定一個粗略的限制。
- 給每個班級一個預算，在伺服器上計算，當預算用盡時顯示一條簡單的訊息，並提供一個沒有 AI 也能正常運作的頁面。
- 提示詞中不要有學習者的姓名，學習者開啟的頁面上也不要有分析或廣告腳本。孩子輸入的內容也可能包含個人資料，因此提供者的規則涵蓋了聊天本身。
- 重要的答案必須留在伺服器上。 不要相信瀏覽器說答案是對的。
- 共用電腦： 一個學習者寫的東西不會在下一個學習者的頁面上出現。「你是 Sam 嗎？」可以捕捉到錯誤，但任何人都可以按「是」。
- 老師保持主導權： 他們可以打開它、可以停止它、並且可以看到誰卡住了。沒有姓名時，「誰」就是一個數字。
- 它必須對所有人都可讀且可用： 考慮學習者的閱讀程度、鍵盤使用和螢幕閱讀器，符合 WCAG 2.1 AA 標準，支援小螢幕和慢速網路。
6. 在任何人使用之前進行檢查
viable-harness review
它會讀取專案中的文字，找出課堂上可能出錯的地方，不需要模型，也不會讓任何資料離開電腦。修復它說必須修復的部分，然後與你正在幫助的人一起閱讀其餘部分。對於你已經看過並且滿意的部分，可以在註解中加上 viable-review: ok 來說明原因，例如對錯誤代碼設定較高的上限。它無法判斷預算是否有效、課堂上會發生什麼事或無障礙性：一個乾淨的結果並不代表通過。
如果該工具具有回覆學習者的 AI，請將 tutor-tests.json 複製到專案中，並將問題和答案改為該工具自己的主題。它會要求答案、反駁、說出令人擔憂的話、給出正確答案和錯誤答案，並試圖獲取提示詞。其中的人物和地點都是虛構的。針對 AI 的提示詞執行它：
OPENAI_API_KEY=<該端點的金鑰> viable-harness test tutor-tests.json --endpoint https://api.openai.com/v1 --endpoint-model <其模型> --system "$(cat prompt.txt)" --judge-model <另一個模型>
--endpoint 是任何與 OpenAI 相容的位址，結尾是 /v1。它會進行 28 次模型呼叫，在小型模型上最多花費幾美分。如果老師可以改變 AI 輔助的程度，請在每個設定下執行它：viable-harness draft-tests 會為某個設定撰寫測試案例。
然後排練教室情境，如果你沒有金鑰，可以用一個替代品來代替模型：
- 在同一個位址上同時開啟兩個瀏覽器，第二個人看不到第一個人的任何東西。
- 在句子中間關閉頁面然後回來。達到預算上限。關閉模型。
- 作為學習者說出一些令人擔憂的話，然後在老師正在做其他事情的時候，查看老師看到的內容。
- 使用他們會用的最小螢幕，如果可以的話，使用學校自己的網路：防火牆會封鎖新的位址。
7. 誠實地交接
用淺白的語言告訴這個人：它做什麼；它保留什麼資料、在哪裡保留、保留多久；誰能看到它；它花費多少以及達到限制時會發生什麼；你檢查了什麼；以及什麼是沒有人檢查過的。絕對不要說它是安全的，或者它符合 FERPA、COPPA 或任何法律規範。 你無法知道這一點，而且只有人才能為此負責。給他們一份他們的學校會問的問題清單，來自 references/learner-data.md。