XiucuiGuan/teachany-hepbl

TeachAnyHEPBL

將大學課程專案目標（+ 可選學科 / 課程 / 交付物）轉換為：

1. PNG 長圖 — 結構化 HE-PBL 拆解 + 課程知識系統圖
2. 互動式網頁 — 與長圖內容一致的互動式專案拆解網頁，含可線上填寫的專案書、小組資訊欄，支援一鍵提交到教師信箱（規範見 references/interactive-webpage.md）
3. 編輯 URL — https://www.teachany.cn/pbl?… 用於對話調整、節點修改、課件製作

拆解使用 TeachAny 在 teachany.cn 上的六階段管線（LLM + 課程索引）。不要自行編造知識節點，應根據目標課程大綱（課程大綱 / 培養方案）對齊，而非編造章節級結構。

工作流程

1. 解析課程專案目標與可選欄位（見 references/parameters.md）。預設 --grade university。
2. 從 此技能目錄（SKILL.md 所在位置）執行內建 CLI：

python3 scripts/hepbl-decompose.py \
  --goal "使用者的專案任務原文" \
  --grade university \
  --subject computer-science \
  -o ./pbl-output

3. 首次執行時，若缺少相依套件請安裝：pip install playwright && playwright install chromium
4. 按照 references/course-blueprint.md 擬定 HE-PBL 設計 — 三維目標、Bloom 層級、前置知識鏈、學術工作流程。使用 references/examples.md 作為風格參考。
5. 設計方案權威校準（存在設計方案文件時強制，不得跳過）：從設計方案逐字提煉 overlay JSON → 執行 scripts/calibrate_hepbl.py 重建網頁與長圖（詳見下文「設計方案權威校準門禁」與「技術路線可視化規範」）。
6. 回覆 PNG 路徑、互動式網頁路徑、JSON 中的節點數量、三維目標以及 edit_url（提供給使用者的連結中永遠不要加入 auto=1）。
7. 若 Playwright 失敗，請依照 references/fallback.md 處理 — 仍須回覆編輯連結。

受限機器替換腳本（保留原方案，執行不順時改用）

scripts/hepbl-decompose-local.py 是原始腳本的替換版（原始 hepbl-decompose.py 保留不動），針對以下已驗證的本機問題：

1. Playwright 內建 Chromium 下載停滯（CDN 無法連線）→ 自動回退 channel="msedge" 系統 Edge
2. 360s 超時不足 → TIMEOUT_MS = 900_000（pbl 頁統一索引 localStorage 超配額，每次全量重建約 100–180s，全流程實測 8–11 分鐘，務必背景執行）
3. goto 偶發 net::ERR_NETWORK_CHANGED → 自動重試 3 次（間隔 5s）

# 用法與原始腳本完全一致（模板仍依 ../assets/hepbl-report.html 相對定位，請勿移動）
python scripts/hepbl-decompose-local.py --goal "..." --grade university --subject mathematics -o ./pbl-output

排障速查：長圖有了但缺少互動網頁 = 腳本被複製到其他位置執行導致 ../assets/ 模板找不到（靜默跳過，將模板放回同級即可）；本機 SciPy 被 Windows 應用程式控制原則封鎖（_trlib DLL），LP 類專案程式碼一律以 PuLP(CBC) 為主、SciPy 用 try/except 設為可選交叉驗證（NumPy/PuLP 正常）。

HE-PBL 設計標準（輸出中必須包含）

每個設計都必須包含：

• 知識目標 / 能力目標 / 素質目標（三維目標）
• Bloom 的認知層級（記憶 / 理解 / 應用 / 分析 / 評價 / 創造）每個目標
• 前置知識要求（與先前課程 / 章節的前置知識鏈）
• 核心概念與難點 對應課程知識系統
• 專案流程：文獻調研 → 方案設計 → 實施驗證 → 成果匯報
• 可評估產出 附學術標準（實驗報告 / 設計文件 / 答辯）

完整標準請見 references/course-blueprint.md。

設計方案權威校準門禁（強制）

存在設計方案文件（如「PBL 專案設計方案」md）時，引擎拆解僅為初稿，最終交付必須通過校準門禁：

1. 逐字提煉 overlay：節點名稱、三維目標、約束數字、基準結果（x*/Z*/影子價格）、階段學時全部從設計方案文件逐字摘取，不得編造或改寫。
2. null 刪除污染：引擎編造欄位（techRoute/pathPlan/projectBlueprint/stats）在 overlay 中設為 null，deep_merge 時刪除；_ 前綴元資料鍵剝離。
3. 長圖 = 網頁：使用 scripts/calibrate_hepbl.py 重建網頁與長圖（Playwright 整頁截圖，device_scale_factor=2），交付前完成自查（節點名稱與設計方案一致、payload 零殘留、summary 與節點數一致）。
4. 統一標題：overlay 必須含 title 欄位（與設計方案標題逐字一致）——網頁 Hero、標籤頁、匯出報告、長圖標題全部取自 DATA.title（缺失時回退 goal）。
5. 繼續編輯入口：網頁端「在 TeachAnyHE 開啟」按鈕一鍵複製 @skill:TeachAnyHE 技能呼叫指令（貼上到 WorkBuddy 對話框即可以高等教育場景繼續編輯）；引擎 teachany.cn 連結降級為「TeachAny 引擎初稿」小字連結保留（DATA.edit_url）。

技術路線可視化規範

• 網頁端優先渲染 techStages[]（stage/hours/tasks[]/output）+ toolChain[]（name/use）分層流程圖：工具鏈 chips → 箭頭銜接 → 階段卡（序號圓點 + 連接線 + 學時徽章 + 任務清單 + 階段產出）；缺失時回退 projectPhases 四段式列表。
• 資料契約與區塊結構見 references/interactive-webpage.md；完整 overlay 範例見 references/calibration-example-lp.json。

輸出範本

## HE-PBL 課程設計拆解

**專案**：{title}

![課程知識路徑拆解]({png_path})

- **圖譜節點**：{nodeCount}（大綱對齊 {matched} · 拓展 {external}）
- **知識目標**：{...}
- **能力目標**：{...}
- **素質目標**：{...}
- **布魯姆層級**：{...}
- **互動式網頁**：[開啟專案拆解網頁]({html_path})（可線上填寫專案書、小組資訊並提交教師信箱）
- **繼續編輯**：網頁端「在 TeachAnyHE 開啟」按鈕一鍵複製技能呼叫指令（貼上到 WorkBuddy 對話框即可以 HE 場景繼續編輯）· 引擎初稿連結：{edit_url}

「在 TeachAnyHE 開啟」按鈕複製的指令貼上到 WorkBuddy 對話框，可繼續對話修改拆解、調整知識點、一鍵製作課件。

在支援圖片的環境中於對話中顯示 PNG。

為什麼不手寫圖譜？

TeachAny 會將節點與課程索引比對、執行相關性審查，並建立依賴邊緣。純 LLM 列表會遺漏大綱對齊，並產生虛假節點 ID。

範例

完整的 HE-PBL 範例庫請見 references/examples.md，涵蓋 數學 / 電腦 / 通訊 / 電氣 課程。快速範例：

範例 1 — 資料結構：python3 scripts/hepbl-decompose.py --goal "設計校園導航最短路徑系統…" --grade university --subject computer-science --deliverable engineering-prototype -o ./pbl-output

範例 2 — 信號與系統：python3 scripts/hepbl-decompose.py --goal "FIR 濾波器設計與頻譜分析…" --grade university --subject communications --deliverable simulation-report -o ./pbl-output

其他資源

• 參數參考：references/parameters.md
• HE-PBL 設計標準：references/course-blueprint.md
• 互動式網頁規範：references/interactive-webpage.md
• 範例庫：references/examples.md
• Playwright 不可用時：references/fallback.md