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

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()

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

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"], "一元二次方程")

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

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

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

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

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

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", {...}) 可用

宿主系统（任何 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 直接安装）            |
  +-----------------------------------------------------------+

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

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