paeg-teaching-materials

Китайский | English

Что это

paeg-teaching-materials — это плагин для создания учебных материалов: 6 генераторов материалов + единая точка входа + MCP server.

Происходит из системы учебных материалов образовательного агента PAEG (итерация v0.87-§3.91), переработан в автономный плагин с нулевой зависимостью от хоста.

Related MCP server: Learn Shell

Ключевые особенности

• Сетевая взаимосвязанная архитектура (стандарт ведущих инструментов ⭐): 10 функциональных узлов (поиск материалов / план / PPT / конспект / сценарий / интеллект-карта / видео / Manim / методы обучения / учебный план) — каждый можно использовать и независимо, и как предварительный этап для других функций

• Расширяемый реестр генераторов: расширение через MaterialRegistry.register("自定义类型", generator)

• Нулевая зависимость от хоста: 6 абстракций Protocol (LLMCallable/RefinerProtocol/HandoutGenerator/ScriptGenerator/MindmapGenerator/ResourceProvider) + слабый режим Null

• Единая точка входа: execute(name, args) по аналогии с constraint_engine (JSON-контракт, никогда не выбрасывает исключений)

• Прямая установка как MCP server: pip install + объявление конфигурации MCP — и готово подключение (15 инструментов)

• Интеграция языковых норм: создаваемые материалы автоматически проходят исправление речевых ошибок L0 (переиспользуется paeg-lang-style)

• Проверка качества + оценка: детерминированная структурная проверка + оценка LLM по 5 измерениям

Сетевая взаимосвязанная архитектура (функции и независимы, и являются предварительными этапами ⭐)

Внутри инструмента — переплетённые сетевые соединения и взаимосвязи: каждая функция является узлом первого класса:

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

Три режима рёбер зависимостей:

Двойное предоставление: каждая функция является и независимым MCP-инструментом (execute_tool), и может автоматически оркестрироваться (execute_pipeline разворачивает предварительные этапы по графу зависимостей), а также компоноваться в цепочки через |:

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

Промежуточные артефакты (типизированная Blackboard MaterialContext): resources (накопление через append при поиске материалов) / outline / lecture_script / ppt_outline / completed_stages (отметки этапов, union) — результаты предварительных этапов автоматически потребляются последующими.

Установка

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

Требуется Python 3.9+.

Быстрый старт

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

Подключение в качестве MCP server (устанавливается напрямую, как MCP)

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

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

Объявление конфигурации MCP-клиента (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"
    }
  }
}

Предоставляемые MCP-инструменты (15):

Руководство по подключению внешних проектов

Сценарий A: только единая точка входа (рекомендуется)

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

Сценарий B: инъекция собственной LLM (сильная реализация)

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

Сценарий C: регистрация пользовательского типа материала (расширяемость)

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

Сценарий D: MCP server (мост без кода)

pip install + объявление конфигурации MCP (см. выше) — любой MCP-клиент (Claude/OpenCode/собственный) вызывает напрямую.

Расширяемость

Сопровождаемость

• Нулевая зависимость от хоста: ядро зависит только от stdlib; все функции хоста — через Protocol-инъекцию

• Единый контракт: execute возвращает JSON-строку (контракт MCP), при сбое не выбрасывает исключения

• Слабый режим: работает без хоста (заглушки Null-генераторов), удобно для тестирования и демонстрации

• Интеграция языковых норм: материалы автоматически проходят исправление речевых ошибок L0

• 41 тест: полное покрытие общедоступного API / слабого режима / инъекций / execute / качества / MCP

Архитектура

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

Интеграция с основным проектом PAEG

PAEG подключается через services/material_bridge.py (инъекция хоста + откат без разрушений):

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

Руководство по внесению вклада

Ваш вклад приветствуется!

• Новый тип материала: наследуйте базовый класс Generator + MaterialRegistry.register()

• Новая проверка качества: добавьте функцию в quality/checks.py

• Стиль кода: следуйте существующей структуре модулей и правилам оформления комментариев

Благодарности

• Образовательный агент PAEG — этот плагин извлечён из его системы создания материалов (§3.87-§3.100)

• paeg-lang-style — плагин языковых норм (интеграция L0)

• Presenton / ppt-agent-skills — парадигма конвейера LLM + рендер

• ManimTrainer — парадигма замкнутого цикла рендера Manim

Лицензия

MIT © 2026 PAEG Team