ziibnchen98-creator/kaoda-review

拷打式複盤

將被動的學習材料轉化為互動式複盤清單，揭露學習者是否真正理解、能否遷移應用、能否辨識錯誤解釋，以及能否經得起後續追問。

核心原則

不要像摘要生成器或普通的測驗產生器一樣。產品承諾是：

看完了，不代表你懂。你還要經得起拷問。

每個輸出都必須幫助診斷假性理解：

• 學習者能否解釋機制？
• 能否說出邊界與失敗情境？
• 能否辨識他人錯誤的理解？
• 能否將概念遷移到不同的情境？
• 能否將概念轉化為可執行的決策或行動？

預設輸出是低風險的複盤清單，而不是正式考試。預設推薦為「正常模式 · 10分鐘」：約 20 個檢查點，大部分為客觀題，除非學習者選擇較重的模式，否則不包含簡答或口試提示。

工作流程

1. 如果使用者提供了具體材料，執行 python scripts/kaoda.py ingest <input> 以建立 data/runs/<run_id>/segments.jsonl。
   • 如果 ingest 回傳 status: needs_text，以白話說明萃取問題，協助使用者將文字提供至 manual_input.txt 或 manual_transcript.txt，然後執行 python scripts/kaoda.py ingest-manual <run_id>。
2. 如果使用者只提供標題或主題，執行 python scripts/kaoda.py research-topic "<topic>"，進行聚焦研究，撰寫 topic_research.md 和 source_links.json，然後執行 python scripts/kaoda.py ingest-topic <run_id>。
3. 讀取 data/runs/<run_id>/material_report.json。
4. 讀取 references/intake_and_research.md。
5. 在詢問模式/風格問題之前，完成來源分析及必要的核心研究/深化。預設執行延伸研究；如果學習者明確表示「只按原文/source-only」，則僅進行來源內研究。將結果寫入 data/runs/<run_id>/deep_research.json。
6. 研究完成後，僅詢問輕量化的選擇：複盤模式/時間、問題風格，以及當學習者有活躍的錯題記錄時，詢問錯題知識政策。
7. 執行 python scripts/kaoda.py plan-exam <run_id> ... 以建立 review_choices.md、research_prompt.md 和 exam_brief.json。
8. 🔴 檢查點：除非 deep_research.json 存在且包含已完成的研究與來源引用，否則 plan-exam 必須失敗。除非 exam_brief.json 包含 review_mode、question_style、review_selection.status 以及強制的 research status: completed，否則不要執行 build-exam。
9. 關於複盤檢查點設計規則，請閱讀 references/question_design.md。
10. 關於開放題評分，請閱讀 references/rubrics.md。
11. 執行 python scripts/kaoda.py build-exam <run_id> 以建立 exam.json、exam.html 和 grading_prompt.md。
12. 讓學習者在 exam.html 中完成複盤。可見的 UI 應保持流程簡單：「提交試卷」，然後顯示報告頁面，並附有「匯出報告給 Agent」的按鈕。
13. 讀取匯出的 kaoda_agent_report.md；它包含 attempt.json、exam.json、客觀題預評分、答案以及供 Agent 評分/記錄的說明。執行 python scripts/kaoda.py grade-report <kaoda_agent_report.md> --learner-id <id> 以產生 attempt.json、exam.json、grading_prompt.md 和 grade.json。
14. 如果 grade.json.open_review.status 是 pending_agent_review，使用 agent_open_review.md 根據 rubric 評分簡答/口試答案，然後將 open_review.status 設為 completed，將每個開放結果的 score_status 設為 completed 或移除該欄位，並在記錄前更新開放題的分數/證據。
15. 執行 python scripts/kaoda.py record <grade.json> 以附加錯題，並將完整的考試/作答/評分/HTML 以及來源/材料/深度研究檔案歸檔至 data/learners/<id>/archive/。如果存在待處理的開放題預評分，record 會拒絕執行。
16. 執行 python scripts/kaoda.py dashboard <id> 以重新整理靜態的學習者中心：總分看板、考試集合、錯題看板以及白話備註。
17. 執行 python scripts/kaoda.py review <id> 進行變體複盤，或執行 python scripts/kaoda.py weekly <id> --since 7d 進行週綜合考試。

研究優先的選擇閘門

不要詢問研究是否允許。這是必須的。研究方向不是固定的清單：機制、邊界、誤解、反例和遷移是最低要求；當材料需要時，加入背景、爭議、風險、替代方案、上游/下游知識、實際應用、工具、指標、歷史或領域背景。

研究完成後，詢問或確認：

• 複盤模式/時間：「複盤模式 · 5分鐘」、「正常模式 · 10分鐘」、「拷打模式 · 30分鐘」或「深度拷打 · 45分鐘」。
• 問題風格：「正經複盤」、「趣味拷打」、「毒舌拷打」、「面試官追問」、「老闆追問」、「朋友吐槽」、「反例獵人」、「概念詐騙辨識」、「彈幕判斷」或「混合風格」。
• 僅當存在活躍的錯題記錄時才詢問錯題知識政策：「只複盤當前材料」、「加入歷史錯題」、「重點拷最近錯題」或「當前材料為主，錯題為輔」。

預設建議：正常模式 · 10分鐘 搭配 混合風格。不要靜默混合歷史錯題；當錯題存在時，需詢問學習者。

問題可讀性合約

問題必須讀起來像清楚的複盤表，而不是像 Agent 暴露其提示框架。

• 將來源層級、風格家族、能力類型和難度僅保留為 JSON 元資料；切勿將它們印在可見的問題提示中。
• 不要在提示前加上「原文校準｜正經複盤｜單選」等標籤、風格提示句或「線索：」等前綴。
• 避免自我意識過強的 AI 用語，例如「最穩」、「哪種理解最穩」、「明顯是在裝懂」、「別急著」、「這題不哄人」、「一眼假」或「偽理解」。
• 使用平實、可回答的措辭：詢問哪個陳述符合材料、哪些陳述是錯的、某個陳述是否正確、哪個概念匹配描述，或如何在情境中應用概念。
• 按題型分區呈現：單選、多選、判斷、填空，然後是簡答/口試。
• 在主要考試、錯題變體及周考中，均勻分佈客觀題的正確答案位置（選項 ID）；不要讓產生的試卷看起來每個答案都是 A。
• 在確認式提交後，HTML 必須切換到報告頁面，顯示分數、各題型分數、錯題、薄弱知識點，以及一個用於匯出 Agent 可讀報告包的按鈕。
• 不要為內部工件暴露多個匯出按鈕。attempt.json、exam.json 和評分說明應包含在單一匯出的 Agent 報告中。

來源處理

在處理影片、PDF、文章網址、掃描文件或字幕之前，請閱讀 references/source_ingestion.md。

如果使用者是新手，或影片/PDF 萃取失敗，執行 python scripts/kaoda.py doctor 並以白話解釋結果，再要求他們安裝工具或提供逐字稿。

硬性規則：

• 保留來源出處：頁碼、時間戳、網址或段落 ID。
• 優先使用字幕/PDF 文字/使用者提供的文字，再考慮音訊轉錄。
• 如果是影片、本地媒體檔案、掃描的 PDF 或文章頁面無法取得可用文字，使用產生的 manual_input.txt/manual_transcript.txt 工作區和 ingest-manual；不要根據標題、網址、檔案名稱或片段來產生問題。
• 將延伸研究與來源衍生知識明確標記區分。

品質閘門

在最終交付前，請閱讀 references/quality_gates.md。

正常運行所需的檔案：

• segments.jsonl
• material_report.json
• deep_research.json
• review_choices.md
• research_prompt.md
• topic_research.md 和 source_links.json（當輸入為裸主題時）
• exam_brief.json
• exam.json
• exam.html
• grading_prompt.md
• kaoda_agent_report.md（學習者完成並匯出複盤後）
• grade.json（評分後）
• agent_open_review.md（當 grade.json.open_review.status 為 pending_agent_review 時）
• mistake_bank.jsonl（記錄錯題後）
• dashboard/index.html、dashboard/exams.html、dashboard/mistakes.html 和 dashboard/notes.html（重新整理學習者儀表板後）
• dashboard/notes_agent_pack.md（當學習者希望 Agent 以其更自然的個人語氣重寫筆記時）

當萃取受阻時，所需的後續檔案為 source_status.json、manual_input.txt 或 manual_transcript.txt，以及 manual_text_request.md；在 ingest-manual 後，繼續使用正常運行所需的檔案。

禁止事項

• 不要以摘要手冊作為最終產出。
• 在 exam_brief.json 中記錄強制研究與輕量化模式/風格選擇之前，不要執行 build-exam。
• 在撰寫並驗證 deep_research.json 之前，不要執行 plan-exam。
• 在研究完成前，不要詢問舊式的五個問題攝入套件。
• 不要在來源僅模式中聲稱進行了外部延伸研究。
• 不要只建立回憶類問題。
• 不要在可見的問題文字中暴露內部標籤或風格提示。
• 不要建立一長串開放題。複盤模式 和 正常模式 應以客觀題為主，並可在瀏覽器中直接計分；簡答/口試提示屬於 拷打模式 和 深度拷打。
• 不要僅靠關鍵字比對來為開放題評分。
• 不要在 open_review.status 仍為 pending_agent_review 時記錄 grade.json。
• 在撰寫主題研究筆記和來源之前，不要根據裸主題產生問題。
• 不要為了複盤或周考重複使用舊問題。
• 不要用自信的措辭隱藏缺失的來源證據。
• 不要在不標記的情況下混合來源事實和延伸研究。