XiucuiGuan/teachany-hepbl

TeachAnyHEPBL

Turn a university course project goal (+ optional discipline / course / deliverable) into:

1. PNG long image — structured HE-PBL breakdown + course knowledge-system graph
2. Interactive webpage — an interactive project decomposition webpage consistent with the long image content, including online-fillable project forms and team info panel, with one-click submission to the teacher's email (spec: see references/interactive-webpage.md)
3. Edit URL — https://www.teachany.cn/pbl?... for chat refinement, node tweaks, courseware

The decomposition uses TeachAny's six-stage pipeline on teachany.cn (LLM + curriculum index). Do not invent knowledge nodes yourself — align against the target course syllabus (course outline / training plan) rather than fabricating chapter-level structure.

Workflow

1. Parse the course project goal and optional fields (see references/parameters.md). Default --grade university.
2. Run the bundled CLI from this skill directory (where SKILL.md lives):

python3 scripts/hepbl-decompose.py \
  --goal "original project task description" \
  --grade university \
  --subject computer-science \
  -o ./pbl-output

3. On first run, install deps if missing: pip install playwright && playwright install chromium
4. Draft the HE-PBL design following references/course-blueprint.md — three-dimension objectives, Bloom's levels, prerequisite chain, academic workflow. Use references/examples.md as style reference.
5. Authoritative calibration of design plan (mandatory when a design document exists, do not skip): Extract overlay JSON verbatim from the design plan → Run scripts/calibrate_hepbl.py to rebuild the webpage and long image (see details below in "Authoritative Calibration Gate" and "Technical Route Visualization Standard").
6. Reply with the PNG path, interactive webpage path, node counts from JSON, the three-dimension objectives, and edit_url (never include auto=1 in links you give users).
7. If Playwright fails, follow references/fallback.md — still return an edit link.

Restricted local replacement script (keep original script, use replacement when it fails)

scripts/hepbl-decompose-local.py is a replacement for the original script (original hepbl-decompose.py remains unchanged), addressing the following verified local issues:

1. Playwright's bundled Chromium download stalls (CDN unreachable) → auto-fallback to channel="msedge" system Edge
2. 360s timeout insufficient → TIMEOUT_MS = 900_000 (pbl page unified index localStorage exceeds quota, full rebuild takes 100–180s each time, full pipeline tested at 8–11 minutes, must run in background)
3. goto intermittent net::ERR_NETWORK_CHANGED → auto-retry 3 times (5s interval)

# Usage identical to original script (template still relative to ../assets/hepbl-report.html, do not move)
python scripts/hepbl-decompose-local.py --goal "..." --grade university --subject mathematics -o ./pbl-output

Troubleshooting quick info: Long image present but missing interactive webpage = script was run from a different directory causing ../assets/ template not found (silently skipped; place template back in the same directory); local SciPy blocked by Windows app control policy (_trlib DLL), LP-type project code uses PuLP(CBC) primarily, SciPy uses try/except as optional cross-validation (NumPy/PuLP normal).

HE-PBL design standards (required in output)

Every design MUST include:

• Knowledge Objective / Ability Objective / Quality Objective (three-dimension objectives)
• Bloom's taxonomy level (Remember / Understand / Apply / Analyze / Evaluate / Create) per objective
• Prerequisite knowledge requirements (prerequisite chain to prior courses / chapters)
• Core concepts and difficulties mapped to the course knowledge system
• Project workflow: Literature review → Scheme design → Implementation verification → Results presentation
• Assessable deliverables with academic standards (lab report / design document / defense)

See references/course-blueprint.md for the full standard.

Authoritative calibration gate for design plans (mandatory)

When a design document exists (e.g., "PBL Project Design Plan" md), the engine decomposition is only a draft; the final delivery must pass through the calibration gate:

1. Extract overlay verbatim: Node names, three-dimension objectives, constraint numbers, baseline results (x*/Z*/shadow prices), stage hours — all extracted word-for-word from the design document, do not fabricate or rephrase.
2. null deletion sanitization: Engine-invented fields (techRoute/pathPlan/projectBlueprint/stats) set to null in overlay, deleted during deep_merge; strip metadata keys with _ prefix.
3. Long image = webpage: Rebuild webpage and long image using scripts/calibrate_hepbl.py (Playwright full-page screenshot, device_scale_factor=2), self-check before delivery (node names match design document, zero payload residue, summary and node count consistent).
4. Unified title: Overlay MUST include a title field (verbatim match with design document title) — webpage Hero, tab, exported report, and long image title all taken from DATA.title (fallback to goal if missing).
5. Continue editing entry: The "Open in TeachAnyHE" button on the webpage copies a @skill:TeachAnyHE skill invocation command (paste into WorkBuddy dialog to continue editing in HE context); keep the teachany.cn engine link as a small "TeachAny Engine Draft" link (DATA.edit_url).

Technical route visualization standard

• Prioritize rendering techStages[] (stage/hours/tasks[]/output) + toolChain[] (name/use) layered flowchart on the web: tool chain chips → arrow connectors → stage cards (numbered dots + connecting lines + hour badges + task lists + stage outputs); fallback to projectPhases quad-list when missing.
• Data contract and block structure: see references/interactive-webpage.md; full overlay example: see references/calibration-example-lp.json.

Output template

## HE-PBL Course Design Decomposition

**Project**：{title}

![Course Knowledge Path Decomposition]({png_path})

- **Graph Nodes**: {nodeCount} (Syllabus Aligned {matched} · Extended {external})
- **Knowledge Objective**: {...}
- **Ability Objective**: {...}
- **Quality Objective**: {...}
- **Bloom's Level**: {...}
- **Interactive Webpage**: [Open Project Decomposition Webpage]({html_path}) (online-fillable project forms and team info panel with email submission to teacher)
- **Continue Editing**: The "Open in TeachAnyHE" button on the webpage copies a skill invocation command (paste into WorkBuddy dialog to continue editing in HE context) · Engine Draft Link: {edit_url}

The command copied by the "Open in TeachAnyHE" button, when pasted into WorkBuddy dialog, allows continued conversation to modify the decomposition, adjust knowledge points, and create courseware with one click.

Show the PNG in chat when the environment supports images.

Why not hand-write the graph?

TeachAny matches nodes against curriculum indexes, runs relevance review, and builds dependency edges. A plain LLM list misses syllabus alignment and produces fake node IDs.

Examples

See references/examples.md for a full HE-PBL example library across Mathematics / Computer Science / Communications / Electrical courses. Quick examples:

Example 1 — Data Structures: python3 scripts/hepbl-decompose.py --goal "Design a campus navigation shortest path system..." --grade university --subject computer-science --deliverable engineering-prototype -o ./pbl-output

Example 2 — Signals and Systems: python3 scripts/hepbl-decompose.py --goal "FIR filter design and spectrum analysis..." --grade university --subject communications --deliverable simulation-report -o ./pbl-output

Additional resources

• Parameter reference: references/parameters.md
• HE-PBL design standard: references/course-blueprint.md
• Interactive webpage spec: references/interactive-webpage.md
• Example library: references/examples.md
• Playwright unavailable: references/fallback.md