paeg-teaching-materials

Deutsch | English

Was ist das?

paeg-teaching-materials ist ein Plugin zur Erstellung von Lehrmaterialien – 6 Materialgeneratoren + einheitlicher Ausführungseinstieg + MCP-Server.

Stammt aus dem PAEG-Bildungsagenten-Materialsystem (v0.87-§3.91-Iteration), umgebaut zu einem hostunabhängigen eigenständigen Plugin.

Related MCP server: Learn Shell

Kernfunktionen

• Netzartige Verbindungsarchitektur (Top-Tool-Standard ⭐): 10 Funktionsknoten (Recherche/Gliederung/PPT/Skript/Vorlesungsmanuskript/Mindmap/Video/Manim/Lernmethoden/Lernplan) – jeder einzeln nutzbar und zugleich Vorstufe anderer Funktionen

• Erweiterbare Generator-Registry: MaterialRegistry.register("benutzerdefinierter Typ", generator) erweitert sofort

• Null-Host-Abhängigkeit: 6 Protocol-Abstraktionen (LLMCallable/RefinerProtocol/HandoutGenerator/ScriptGenerator/MindmapGenerator/ResourceProvider) + Null-Schwachmodus

• Einheitlicher Ausführungseinstieg: execute(name, args) analog zu constraint_engine (JSON-Vertrag, wirft niemals Ausnahmen)

• MCP-Server direkt installierbar: pip install + MCP-Konfigurationsdeklaration genügt (15 Tools)

• Sprachnorm-Verknüpfung: Materialausgabe durchläuft automatisch L0-Satzfehlerkorrektur (nutzt paeg-lang-style wieder)

• Qualitätsprüfung + Bewertung: Deterministische Strukturprüfung + LLM-5-Dimensionen-Bewertung

Netzartige Verbindungsarchitektur (Funktionen sowohl eigenständig als auch Vorstufe ⭐)

Im Inneren des Tools herrscht verflochtene netzartige Verdrahtung und Verbindung – jede Funktion ist ein Knoten erster Klasse:

research（查资料·广播前置）
   ├──→ outline（大纲）──→ ppt（PPT 制作）
   ├──→ script（讲稿）──→ video（教学视频）
   ├──→ handout / manim / method / study_plan / mindmap(可选)

Drei Modi von Abhängigkeitskanten:

Doppelte Exposition: Jede Funktion ist sowohl ein eigenständiges MCP-Tool (execute_tool) als auch automatisch orchestrierbar (execute_pipeline expandiert Vorstufen gemäß Abhängigkeitsgraph), sowie per |-Verkettung kombinierbar:

from paeg_teaching_materials import MaterialRegistry
from paeg_teaching_materials.tools import ResearchTool, OutlineTool, PptTool

# 1. 独立调用
result = MaterialRegistry.execute_plan("ppt", ctx, {"topic": "导数"})
#   自动执行: research → outline → ppt（查资料是前置环节）

# 2. 链式组合（LangChain Runnable 模式）
pipeline = ResearchTool() | OutlineTool() | PptTool()  # 组合结果仍是 Tool

# 3. 依赖图自省（MCP: list_dependencies）
graph = MaterialRegistry.get_resolver().dependency_graph()

Zwischenprodukte (typisierte MaterialContext-Blackboard): resources (Recherche·append-Akkumulation) / outline / lecture_script / ppt_outline / completed_stages (Stufenmarkierungen·union) – Vorstufenprodukte werden automatisch von nachgelagerten Stufen konsumiert.

Installation

pip install -e /path/to/paeg-teaching-materials
# 可选依赖：
pip install -e "paeg-teaching-materials[pptx]"    # PPT 渲染
pip install -e "paeg-teaching-materials[manim]"   # Manim 渲染
pip install -e "paeg-teaching-materials[mcp]"     # MCP server

Erfordert Python 3.9+.

Schnellstart

from paeg_teaching_materials import MaterialRegistry, execute

# 1. 注入你的 LLM（任何项目接入点）
def my_llm(system, user, max_tokens=2000, temperature=0.7):
    return call_your_llm(system, user, max_tokens=max_tokens)
MaterialRegistry.inject(llm=my_llm)

# 2. 生成物料（统一执行入口）
result = execute("generate_handout", {"topic": "一元二次方程", "subject": "数学"})
# → {"material_type": "handout", "topic": "...", "ok": true, "output": "## 教学目标..."}

# 3. 质量检查 + 评审
from paeg_teaching_materials import check_material_structure, judge_material
issues = check_material_structure(result["output"], "handout")
score = judge_material(result["output"], "一元二次方程")

Anbindung als MCP-Server (wie MCP direkt installierbar und nutzbar)

# 方式 1：console_scripts 入口（pip install 后）
paeg-teaching-materials-mcp

# 方式 2：python -m 入口（源码运行）
python -m paeg_teaching_materials.mcp_server

MCP-Client-Konfigurationsdeklaration (config/mcp_servers.json):

{
  "mcpServers": {
    "paeg-teaching-materials": {
      "command": "python",
      "args": ["-m", "paeg_teaching_materials.mcp_server"],
      "cwd": "D:/wbo-workspace/paeg_project/paeg-teaching-materials"
    }
  }
}

Exponierte MCP-Tools (15 Stück):

Integrationsanleitung für externe Projekte

Szenario A: Nur einheitlichen Ausführungseinstieg verwenden (empfohlen)

from paeg_teaching_materials import execute
result = execute("generate_ppt", {"topic": "微积分", "subject": "数学"})

Szenario B: Eigenes LLM injizieren (starke Implementierung)

from paeg_teaching_materials import MaterialRegistry
MaterialRegistry.inject(llm=my_llm, refiner=my_refiner)
result = MaterialRegistry.generate("handout", "力学", "物理")

Szenario C: Benutzerdefinierten Materialtyp registrieren (Erweiterbarkeit)

from paeg_teaching_materials import MaterialRegistry
from paeg_teaching_materials.generators.base import Generator

class QuizGenerator(Generator):
    material_type = "quiz"
    def generate(self, topic, subject="通用", learner_id="anon", **kw):
        return {"material_type": "quiz", "topic": topic, "ok": True, "output": "..."}

MaterialRegistry.register("quiz", generator=QuizGenerator())
# 现在 execute("generate_quiz", {...}) 可用

Szenario D: MCP-Server (Null-Code-Brücke)

pip install + MCP-Konfigurationsdeklaration (siehe oben) – jeder MCP-Client (Claude/OpenCode/eigenentwickelt) kann direkt aufrufen.

Erweiterbarkeit

Wartbarkeit

• Null-Host-Abhängigkeit: Kernpaket hängt nur von stdlib ab; Hostfunktionen vollständig per Protocol injiziert

• Einheitlicher Vertrag: execute gibt JSON-String zurück (MCP-Vertrag), wirft bei Fehlern keine Ausnahmen

• Schwachmodus: Ohne Host lauffähig (Null-Generator als Platzhalter), erleichtert Tests und Demos

• Sprachnorm-Verknüpfung: Materialausgabe durchläuft automatisch L0-Satzfehlerkorrektur

• 41 Tests: Vollständige Abdeckung von öffentlicher API/Schwachmodus/Injektion/execute/Qualität/MCP

Architektur

宿主系统（任何 Python 项目 / 智能体）
  MaterialRegistry.inject(llm=..., refiner=..., resources=...)  <- 宿主注入
  execute("generate_handout", {...})                            <- 统一入口
        |
        | 零宿主依赖（Protocol 抽象）
        v
paeg_teaching_materials（独立插件）
  +-------------------+  +-------------------+  +----------------+
  | registry.py       |  | generators/       |  | quality/       |
  | MaterialRegistry  |  | ppt/handout/...   |  | checks/judge   |
  +---------+---------+  +---------+---------+  +----------------+
            |                      |
            v                      v
  +-----------------------------------------------------------+
  | executor.py（execute 统一入口，JSON 契约）                   |
  | mcp_server.py（FastMCP 15 工具，stdio 直接安装）            |
  +-----------------------------------------------------------+

Integration mit dem PAEG-Hauptprojekt

PAEG bindet über services/material_bridge.py an (Host-Injektion + zerstörungsfreies Fallback):

from services.material_bridge import install_material_plugin
install_material_plugin()   # server.py 启动时调用一次
# 注入 PAEG LLM（subagents._safe_chat）+ Refiner（paeg.refiner）+ 资源（library）
# 插件未安装 → 静默回退 PAEG 原物料实现（旧文件永不删除）

Tests

python -m pytest tests/ -q
# 22 项：公共 API / 弱模式 / 注入 / execute / 质量 / MCP server

Beitragsrichtlinien

Beiträge sind willkommen!

• Neuen Materialtyp hinzufügen: Generator-Basisklasse erben + MaterialRegistry.register()

• Neue Qualitätsprüfung: Funktion in quality/checks.py hinzufügen

• Codestil: Vorhandener Modulstruktur + Kommentarkonventionen folgen

Danksagungen

• PAEG-Bildungsagent – dieses Plugin wurde aus dessen Materialerstellungssystem extrahiert (§3.87-§3.100)

• paeg-lang-style – Sprachnorm-Plugin (L0-Verknüpfung)

• Presenton / ppt-agent-skills – LLM+Render-Pipeline-Paradigma

• ManimTrainer – Manim-Render-Schleifen-Paradigma

Lizenz

MIT © 2026 PAEG Team