feat(courseware): AI Teacher Assistant Agent 模块化

- Course Vision & Structure Builder / Activity Designer / Teaching Copilot / QA Optimizer / Content Generator
- RAG 引用规范: [Source: Filename/Page] | [Source: URL]
- api/courseware/*, routes_courseware, weaviate_retrieve refs, docs/COURSEWARE_AGENT.md

Co-authored-by: Cursor <cursoragent@cursor.com>

api/courseware/__init__.py

@@ -0,0 +1,18 @@
+# api/courseware – AI Teacher Assistant Agent（模块化）
+"""
+基于「课程描述 + 辅助材料」与 RAG，生成全链路教学资源的 AI 教师助教。
+所有生成内容均带 Reference：本地 VDB [Source: Filename/Page]，Web [Source: URL]。
+"""
+from api.courseware.vision_builder import build_course_vision
+from api.courseware.activity_designer import design_activities_and_assignments
+from api.courseware.teaching_copilot import teaching_copilot
+from api.courseware.qa_optimizer import optimize_from_quiz_data
+from api.courseware.content_generator import generate_lesson_plan_and_ppt_data
+
+__all__ = [
+    "build_course_vision",
+    "design_activities_and_assignments",
+    "teaching_copilot",
+    "optimize_from_quiz_data",
+    "generate_lesson_plan_and_ppt_data",
+]

api/courseware/activity_designer.py

@@ -0,0 +1,49 @@
+# api/courseware/activity_designer.py
+"""
+Activity & Assignment Designer：课堂活动、作业及评分标准（Rubric）；从上传资料提取核心知识点。
+"""
+from typing import Optional
+
+from api.config import client, DEFAULT_MODEL, USE_WEAVIATE
+from api.courseware.rag import get_rag_context_with_refs, inject_refs_instruction
+from api.courseware.references import append_references_to_content
+from api.courseware.prompts import ACTIVITY_DESIGNER_SYSTEM, ACTIVITY_DESIGNER_USER_TEMPLATE
+
+
+def design_activities_and_assignments(
+    topic: str,
+    learning_objectives: Optional[str] = None,
+    rag_context_override: Optional[str] = None,
+    max_tokens: int = 2200,
+) -> str:
+    """
+    设计课堂活动、作业及 Rubric；支持从上传资料提取核心知识点并与目标一致。
+    """
+    query = f"{topic}\n{learning_objectives or ''}"[:1500]
+    rag_context, refs = get_rag_context_with_refs(query, top_k=8, max_context_chars=5000)
+    if rag_context_override:
+        rag_context = rag_context_override
+    ref_instruction = inject_refs_instruction(refs)
+    user_content = ACTIVITY_DESIGNER_USER_TEMPLATE.format(
+        topic=topic.strip() or "（未提供主题）",
+        learning_objectives=(learning_objectives or "（未提供，请根据主题推断）").strip(),
+        rag_context=rag_context or "（无检索到知识库摘录，将基于通用教学设计回答。）",
+        ref_instruction=ref_instruction,
+    )
+    try:
+        resp = client.chat.completions.create(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": ACTIVITY_DESIGNER_SYSTEM},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.5,
+            max_tokens=max_tokens,
+            timeout=90,
+        )
+        out = (resp.choices[0].message.content or "").strip()
+    except Exception as e:
+        out = f"生成失败：{e}。请稍后重试。"
+    if refs and "## References" not in out and "[Source:" not in out:
+        out = append_references_to_content(out, refs)
+    return out

api/courseware/content_generator.py

@@ -0,0 +1,48 @@
+# api/courseware/content_generator.py
+"""
+Content Generator：生成 Markdown 详细教案，并导出可用于生成 PPT 的结构化数据。
+"""
+from typing import Optional
+
+from api.config import client, DEFAULT_MODEL
+from api.courseware.rag import get_rag_context_with_refs, inject_refs_instruction
+from api.courseware.references import append_references_to_content
+from api.courseware.prompts import CONTENT_GENERATOR_SYSTEM, CONTENT_GENERATOR_LESSON_PLAN_TEMPLATE
+
+
+def generate_lesson_plan_and_ppt_data(
+    topic: str,
+    duration: Optional[str] = None,
+    outline_points: Optional[str] = None,
+    max_tokens: int = 2800,
+) -> str:
+    """
+    生成 Markdown 详细教案 + 可用于 PPT 的结构化数据（每页 title、bullets、speaker_notes）。
+    """
+    query = f"{topic}\n{outline_points or ''}"[:2000]
+    rag_context, refs = get_rag_context_with_refs(query, top_k=8, max_context_chars=5000)
+    ref_instruction = inject_refs_instruction(refs)
+    user_content = CONTENT_GENERATOR_LESSON_PLAN_TEMPLATE.format(
+        topic=topic.strip() or "（未提供主题）",
+        duration=(duration or "1 课时").strip(),
+        outline_points=(outline_points or "（未提供，请根据主题生成）").strip(),
+        rag_context=rag_context or "（无检索到知识库摘录。）",
+        ref_instruction=ref_instruction,
+    )
+    try:
+        resp = client.chat.completions.create(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": CONTENT_GENERATOR_SYSTEM},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.4,
+            max_tokens=max_tokens,
+            timeout=120,
+        )
+        out = (resp.choices[0].message.content or "").strip()
+    except Exception as e:
+        out = f"生成失败：{e}。请稍后重试。"
+    if refs and "## References" not in out and "[Source:" not in out:
+        out = append_references_to_content(out, refs)
+    return out

api/courseware/prompts.py

@@ -0,0 +1,96 @@
+# api/courseware/prompts.py
+"""
+AI Teacher Assistant Agent 各模块独立 Prompt 模板。
+"""
+
+# ------------------------- Course Vision & Structure Builder -------------------------
+COURSE_VISION_SYSTEM = """你是一位课程设计专家，负责根据课程基本信息与教学大纲，产出课程定位、学习目标与层级化知识树（Knowledge Tree）。
+输出必须基于提供的「课程知识库摘录」与大纲；若存在引用，回答末尾必须包含 References，格式为 [Source: 文件名/页码] 或 [Source: URL]。"""
+
+COURSE_VISION_USER_TEMPLATE = """请根据以下信息，生成：
+1. **课程定位**：一句话说明课程在培养方案中的角色与目标受众。
+2. **学习目标**：3–6 条可衡量的学习目标（Learning Objectives）。
+3. **知识树（Knowledge Tree）**：层级化结构（如 模块 → 单元 → 知识点），与大纲对应。
+
+**课程基本信息：**
+{course_info}
+
+**教学大纲（或要点）：**
+{syllabus}
+
+**参考知识库摘录（请据此保持与现有课程内容一致）：**
+{rag_context}
+
+{ref_instruction}
+请直接输出以上三部分，并确保引用格式正确。"""
+
+
+# ------------------------- Activity & Assignment Designer -------------------------
+ACTIVITY_DESIGNER_SYSTEM = """你是课堂活动与作业设计专家。根据课程目标与上传资料中的核心知识点，设计课堂活动、作业及对应评分标准（Rubric）。
+输出必须基于提供的参考资料；回答末尾必须包含 References，格式为 [Source: 文件名/页码] 或 [Source: URL]。"""
+
+ACTIVITY_DESIGNER_USER_TEMPLATE = """请针对以下主题与目标，设计：
+1. **课堂活动**：1–2 个可实施的课堂活动（时长、步骤、所需材料）。
+2. **作业**：1 个作业（题目描述、提交形式、截止建议）。
+3. **评分标准（Rubric）**：与该作业对应的评分维度与等级说明。
+
+**主题/模块：** {topic}
+**学习目标（可选）：** {learning_objectives}
+**参考知识库摘录（请提取核心知识点并与之对齐）：**
+{rag_context}
+
+{ref_instruction}
+请直接输出以上三部分，并确保引用格式正确。"""
+
+
+# ------------------------- Teaching Copilot & Student Adaptation -------------------------
+TEACHING_COPILOT_SYSTEM = """你是课堂实时助教（Teaching Copilot），根据当前授课内容与学生画像（姓名、进度、行为），给出即时教学建议与个性化调整建议。
+回答末尾若依据了资料，必须包含 References：[Source: 文件名/页码] 或 [Source: URL]。"""
+
+TEACHING_COPILOT_USER_TEMPLATE = """**当前授课内容/问题：**
+{current_content}
+
+**学生画像（可选）：**
+{student_profiles}
+
+**参考知识库摘录：**
+{rag_context}
+
+{ref_instruction}
+请给出简洁的实时建议（如：强调某点、提问建议、对某位学生的关注建议），并确保引用格式正确。"""
+
+
+# ------------------------- Course QA Optimizer -------------------------
+QA_OPTIMIZER_SYSTEM = """你基于学生答题数据（Smart Quiz）分析薄弱点，并给出后续教学优化建议（如补充讲解、练习题、复习重点）。
+回答末尾若依据了资料，必须包含 References：[Source: 文件名/页码] 或 [Source: URL]。"""
+
+QA_OPTIMIZER_USER_TEMPLATE = """**学生答题数据摘要（Smart Quiz）：**
+{quiz_summary}
+
+**相关课程主题/章节：** {course_topic}
+
+**参考知识库摘录（用于对齐课程目标与知识点）：**
+{rag_context}
+
+{ref_instruction}
+请输出：1) 薄弱点分析；2) 后续教学建议（可操作）；并确保引用格式正确。"""
+
+
+# ------------------------- Content Generator (Lesson Plan & PPT) -------------------------
+CONTENT_GENERATOR_SYSTEM = """你负责生成详细教案（Markdown）及可用于生成 PPT 的结构化数据（如每页标题、要点、备注）。
+输出必须基于提供的参考资料；回答末尾必须包含 References：[Source: 文件名/页码] 或 [Source: URL]。"""
+
+CONTENT_GENERATOR_LESSON_PLAN_TEMPLATE = """请根据以下主题与大纲，生成：
+1. **详细教案（Markdown）**：含教学目标、重难点、教学步骤、时间分配、互动设计、作业/预习。
+2. **PPT 结构化数据**：JSON 或分条列出每页的 title、bullets（3–5 条）、speaker_notes（可选）。
+
+**主题/章节：** {topic}
+**课时/时长建议：** {duration}
+**大纲要点：**
+{outline_points}
+
+**参考知识库摘录：**
+{rag_context}
+
+{ref_instruction}
+请先输出 Markdown 教案，再输出 PPT 结构化数据，最后附 References。"""

api/courseware/qa_optimizer.py

@@ -0,0 +1,46 @@
+# api/courseware/qa_optimizer.py
+"""
+Course QA Optimizer：基于学生答题数据（Smart Quiz）分析弱点，自动优化后续教学建议。
+"""
+from typing import Optional
+
+from api.config import client, DEFAULT_MODEL
+from api.courseware.rag import get_rag_context_with_refs, inject_refs_instruction
+from api.courseware.references import append_references_to_content
+from api.courseware.prompts import QA_OPTIMIZER_SYSTEM, QA_OPTIMIZER_USER_TEMPLATE
+
+
+def optimize_from_quiz_data(
+    quiz_summary: str,
+    course_topic: Optional[str] = None,
+    max_tokens: int = 1500,
+) -> str:
+    """
+    基于 Smart Quiz 答题数据摘要，分析薄弱点并给出后续教学优化建议。
+    """
+    query = f"{quiz_summary}\n{course_topic or ''}"[:2000]
+    rag_context, refs = get_rag_context_with_refs(query, top_k=6, max_context_chars=4000)
+    ref_instruction = inject_refs_instruction(refs)
+    user_content = QA_OPTIMIZER_USER_TEMPLATE.format(
+        quiz_summary=quiz_summary.strip() or "（未提供答题数据）",
+        course_topic=(course_topic or "（未指定）").strip(),
+        rag_context=rag_context or "（无检索到知识库摘录。）",
+        ref_instruction=ref_instruction,
+    )
+    try:
+        resp = client.chat.completions.create(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": QA_OPTIMIZER_SYSTEM},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.4,
+            max_tokens=max_tokens,
+            timeout=90,
+        )
+        out = (resp.choices[0].message.content or "").strip()
+    except Exception as e:
+        out = f"生成失败：{e}。请稍后重试。"
+    if refs and "## References" not in out and "[Source:" not in out:
+        out = append_references_to_content(out, refs)
+    return out

api/courseware/rag.py

@@ -0,0 +1,47 @@
+# api/courseware/rag.py
+"""
+Courseware RAG：统一检索并返回带引用的上下文。
+- 本地 VDB（Weaviate / 上传文件 chunks）：[Source: Filename/Page]
+- Web Search（可选）：[Source: URL]
+"""
+from typing import List, Tuple, Optional
+
+from api.config import USE_WEAVIATE
+from api.weaviate_retrieve import retrieve_from_weaviate_with_refs, RefItem
+from api.courseware.references import format_references, append_references_to_content
+
+
+def get_rag_context_with_refs(
+    query: str,
+    top_k: int = 8,
+    web_search_urls: Optional[List[str]] = None,
+    max_context_chars: int = 6000,
+) -> Tuple[str, List[RefItem]]:
+    """
+    获取 RAG 上下文与引用列表。优先使用 Weaviate；可选追加 web 来源。
+    context 已包含可放入 prompt 的参考摘录；refs 用于最终标注。
+    """
+    text = ""
+    refs: List[RefItem] = []
+    if USE_WEAVIATE and query and len(query.strip()) >= 3:
+        text, refs = retrieve_from_weaviate_with_refs(query, top_k=top_k)
+        if text and max_context_chars > 0 and len(text) > max_context_chars:
+            text = text[:max_context_chars] + "\n..."
+    if web_search_urls:
+        for url in web_search_urls[:10]:
+            url = (url or "").strip()
+            if url:
+                refs.append({"type": "web", "url": url})
+    return (text or "").strip(), refs
+
+
+def inject_refs_instruction(refs: List[RefItem]) -> str:
+    """生成给 LLM 的引用说明：要求回答中必须标注引用。"""
+    if not refs:
+        return "（本次无检索到参考资料，回答中可注明「无引用」。）"
+    ref_block = format_references(refs)
+    return (
+        "回答末尾必须附「References」小节，按以下格式逐条列出所依据来源：\n"
+        "本地资料使用 [Source: 文件名/页码]，网络来源使用 [Source: URL]。\n"
+        "本次参考来源：\n" + ref_block
+    )

api/courseware/references.py

@@ -0,0 +1,42 @@
+# api/courseware/references.py
+"""
+Reference 规范：所有 RAG 生成内容必须附带引用。
+- 本地 VDB： [Source: Filename/Page]
+- Web Search： [Source: URL]
+"""
+from typing import List, Dict, Any
+
+
+def format_ref_item(item: Dict[str, Any]) -> str:
+    """单条引用格式化为 [Source: ...]。"""
+    t = (item.get("type") or "").strip().lower()
+    if t == "web" or item.get("url"):
+        url = (item.get("url") or "").strip()
+        if url:
+            return f"[Source: {url}]"
+    # 默认按本地 VDB
+    source = (item.get("source") or item.get("source_file") or "uploaded").strip()
+    page = (item.get("page") or "").strip()
+    if page:
+        return f"[Source: {source}/{page}]"
+    return f"[Source: {source}]"
+
+
+def format_references(refs: List[Dict[str, Any]]) -> str:
+    """将引用列表格式化为多行 [Source: ...]，去重保持顺序。"""
+    seen: set = set()
+    lines: List[str] = []
+    for r in refs:
+        s = format_ref_item(r)
+        if s and s not in seen:
+            seen.add(s)
+            lines.append(s)
+    return "\n".join(lines) if lines else ""
+
+
+def append_references_to_content(content: str, refs: List[Dict[str, Any]]) -> str:
+    """在正文末尾追加 References 小节。"""
+    ref_block = format_references(refs)
+    if not ref_block:
+        return content.rstrip()
+    return content.rstrip() + "\n\n## References\n\n" + ref_block

api/courseware/teaching_copilot.py

@@ -0,0 +1,60 @@
+# api/courseware/teaching_copilot.py
+"""
+Teaching Copilot & Student Adaptation：课堂实时辅助，按学生画像（Name, Progress, Behavior）动态调整建议。
+"""
+from typing import Optional, List, Dict, Any
+
+from api.config import client, DEFAULT_MODEL
+from api.courseware.rag import get_rag_context_with_refs, inject_refs_instruction
+from api.courseware.references import append_references_to_content
+from api.courseware.prompts import TEACHING_COPILOT_SYSTEM, TEACHING_COPILOT_USER_TEMPLATE
+
+
+def _format_student_profiles(profiles: List[Dict[str, Any]]) -> str:
+    """将学生画像列表格式化为可读文本。"""
+    if not profiles:
+        return "（未提供）"
+    lines = []
+    for i, p in enumerate(profiles[:20], 1):
+        name = p.get("name") or p.get("Name") or "—"
+        progress = p.get("progress") or p.get("Progress") or "—"
+        behavior = p.get("behavior") or p.get("Behavior") or "—"
+        lines.append(f"- 学生{i}: Name={name}, Progress={progress}, Behavior={behavior}")
+    return "\n".join(lines)
+
+
+def teaching_copilot(
+    current_content: str,
+    student_profiles: Optional[List[Dict[str, Any]]] = None,
+    max_tokens: int = 1200,
+) -> str:
+    """
+    课堂实时辅助：根据当前授课内容与学生画像给出即时建议与个性化调整。
+    """
+    query = current_content[:1500]
+    rag_context, refs = get_rag_context_with_refs(query, top_k=6, max_context_chars=3500)
+    ref_instruction = inject_refs_instruction(refs)
+    profiles_text = _format_student_profiles(student_profiles or [])
+    user_content = TEACHING_COPILOT_USER_TEMPLATE.format(
+        current_content=current_content.strip() or "（未提供当前内容）",
+        student_profiles=profiles_text,
+        rag_context=rag_context or "（无检索到知识库摘录。）",
+        ref_instruction=ref_instruction,
+    )
+    try:
+        resp = client.chat.completions.create(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": TEACHING_COPILOT_SYSTEM},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.5,
+            max_tokens=max_tokens,
+            timeout=60,
+        )
+        out = (resp.choices[0].message.content or "").strip()
+    except Exception as e:
+        out = f"生成失败：{e}。请稍后重试。"
+    if refs and "## References" not in out and "[Source:" not in out:
+        out = append_references_to_content(out, refs)
+    return out

api/courseware/vision_builder.py

@@ -0,0 +1,47 @@
+# api/courseware/vision_builder.py
+"""
+Course Vision & Structure Builder：课程定位、学习目标、层级化知识树。
+"""
+from typing import Optional
+
+from api.config import client, DEFAULT_MODEL, USE_WEAVIATE
+from api.courseware.rag import get_rag_context_with_refs, inject_refs_instruction
+from api.courseware.references import append_references_to_content
+from api.courseware.prompts import COURSE_VISION_SYSTEM, COURSE_VISION_USER_TEMPLATE
+
+
+def build_course_vision(
+    course_info: str,
+    syllabus: str,
+    max_tokens: int = 2000,
+) -> str:
+    """
+    输入：课程基本信息 + 教学大纲。
+    输出：课程定位、学习目标、层级化知识树；含 References。
+    """
+    query = f"{course_info}\n{syllabus}"[:2000]
+    rag_context, refs = get_rag_context_with_refs(query, top_k=8, max_context_chars=5000)
+    ref_instruction = inject_refs_instruction(refs)
+    user_content = COURSE_VISION_USER_TEMPLATE.format(
+        course_info=course_info.strip() or "（未提供）",
+        syllabus=syllabus.strip() or "（未提供）",
+        rag_context=rag_context or "（无检索到知识库摘录，将基于通用课程设计经验回答。）",
+        ref_instruction=ref_instruction,
+    )
+    try:
+        resp = client.chat.completions.create(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": COURSE_VISION_SYSTEM},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.4,
+            max_tokens=max_tokens,
+            timeout=90,
+        )
+        out = (resp.choices[0].message.content or "").strip()
+    except Exception as e:
+        out = f"生成失败：{e}。请稍后重试。"
+    if refs and "## References" not in out and "[Source:" not in out:
+        out = append_references_to_content(out, refs)
+    return out

api/routes_courseware.py

@@ -0,0 +1,170 @@
+# api/routes_courseware.py
+"""AI Teacher Assistant Agent（Courseware）API：课程愿景、活动设计、课堂助教、QA 优化、教案与 PPT 数据。"""
+from typing import Optional, List, Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from api.config import USE_WEAVIATE
+from api.courseware import (
+    build_course_vision,
+    design_activities_and_assignments,
+    teaching_copilot,
+    optimize_from_quiz_data,
+    generate_lesson_plan_and_ppt_data,
+)
+
+router = APIRouter(prefix="/api/courseware", tags=["courseware"])
+
+
+# ------------------------- Course Vision & Structure Builder -------------------------
+class VisionRequest(BaseModel):
+    course_info: str = Field(..., min_length=1, description="课程基本信息")
+    syllabus: str = Field(..., min_length=1, description="教学大纲或要点")
+
+
+class VisionResponse(BaseModel):
+    ok: bool = True
+    content: str = Field(..., description="课程定位、学习目标、知识树（含 References）")
+    weaviate_used: bool = False
+
+
+@router.post("/vision", response_model=VisionResponse)
+def post_vision(req: VisionRequest):
+    """课程愿景与结构：输出课程定位、学习目标、层级化知识树。"""
+    try:
+        content = build_course_vision(
+            course_info=req.course_info.strip(),
+            syllabus=req.syllabus.strip(),
+        )
+        return VisionResponse(content=content, weaviate_used=USE_WEAVIATE)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ------------------------- Activity & Assignment Designer -------------------------
+class ActivitiesRequest(BaseModel):
+    topic: str = Field(..., min_length=1, description="主题/模块")
+    learning_objectives: Optional[str] = Field(None, description="学习目标（可选）")
+    rag_context_override: Optional[str] = Field(None, description="覆盖 RAG 上下文（如上传资料摘要）")
+
+
+class ActivitiesResponse(BaseModel):
+    ok: bool = True
+    content: str = Field(..., description="课堂活动、作业、Rubric（含 References）")
+    weaviate_used: bool = False
+
+
+@router.post("/activities", response_model=ActivitiesResponse)
+def post_activities(req: ActivitiesRequest):
+    """活动与作业设计：课堂活动、作业、评分标准；支持从上传资料提取知识点。"""
+    try:
+        content = design_activities_and_assignments(
+            topic=req.topic.strip(),
+            learning_objectives=req.learning_objectives.strip() if req.learning_objectives else None,
+            rag_context_override=req.rag_context_override.strip() if req.rag_context_override else None,
+        )
+        return ActivitiesResponse(content=content, weaviate_used=USE_WEAVIATE)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ------------------------- Teaching Copilot & Student Adaptation -------------------------
+class StudentProfile(BaseModel):
+    name: Optional[str] = None
+    progress: Optional[str] = None
+    behavior: Optional[str] = None
+
+
+class CopilotRequest(BaseModel):
+    current_content: str = Field(..., min_length=1, description="当前授课内容/问题")
+    student_profiles: Optional[List[StudentProfile]] = Field(None, description="学生画像 Name, Progress, Behavior")
+
+
+class CopilotResponse(BaseModel):
+    ok: bool = True
+    content: str = Field(..., description="实时建议（含 References）")
+    weaviate_used: bool = False
+
+
+@router.post("/copilot", response_model=CopilotResponse)
+def post_copilot(req: CopilotRequest):
+    """课堂实时助教：根据当前内容与学生画像给出即时建议。"""
+    try:
+        profiles = [p.model_dump() for p in (req.student_profiles or [])]
+        content = teaching_copilot(
+            current_content=req.current_content.strip(),
+            student_profiles=profiles,
+        )
+        return CopilotResponse(content=content, weaviate_used=USE_WEAVIATE)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ------------------------- Course QA Optimizer -------------------------
+class QAOptimizeRequest(BaseModel):
+    quiz_summary: str = Field(..., min_length=1, description="学生答题数据摘要（Smart Quiz）")
+    course_topic: Optional[str] = Field(None, description="相关课程主题/章节")
+
+
+class QAOptimizeResponse(BaseModel):
+    ok: bool = True
+    content: str = Field(..., description="薄弱点分析与教学建议（含 References）")
+    weaviate_used: bool = False
+
+
+@router.post("/qa-optimize", response_model=QAOptimizeResponse)
+def post_qa_optimize(req: QAOptimizeRequest):
+    """基于 Smart Quiz 答题数据分析弱点并给出教学优化建议。"""
+    try:
+        content = optimize_from_quiz_data(
+            quiz_summary=req.quiz_summary.strip(),
+            course_topic=req.course_topic.strip() if req.course_topic else None,
+        )
+        return QAOptimizeResponse(content=content, weaviate_used=USE_WEAVIATE)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ------------------------- Content Generator (Lesson Plan & PPT) -------------------------
+class ContentRequest(BaseModel):
+    topic: str = Field(..., min_length=1, description="主题/章节")
+    duration: Optional[str] = Field(None, description="课时/时长建议")
+    outline_points: Optional[str] = Field(None, description="大纲要点")
+
+
+class ContentResponse(BaseModel):
+    ok: bool = True
+    content: str = Field(..., description="Markdown 教案 + PPT 结构化数据（含 References）")
+    weaviate_used: bool = False
+
+
+@router.post("/content", response_model=ContentResponse)
+def post_content(req: ContentRequest):
+    """生成详细教案（Markdown）与可用于 PPT 的结构化数据。"""
+    try:
+        content = generate_lesson_plan_and_ppt_data(
+            topic=req.topic.strip(),
+            duration=req.duration.strip() if req.duration else None,
+            outline_points=req.outline_points.strip() if req.outline_points else None,
+        )
+        return ContentResponse(content=content, weaviate_used=USE_WEAVIATE)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ------------------------- Status -------------------------
+@router.get("/status")
+def get_courseware_status():
+    """Courseware Agent 状态与能力列表。"""
+    return {
+        "weaviate_configured": USE_WEAVIATE,
+        "reference_policy": "All outputs include References: [Source: Filename/Page] or [Source: URL]",
+        "modules": [
+            "vision",       # Course Vision & Structure Builder
+            "activities",   # Activity & Assignment Designer
+            "copilot",     # Teaching Copilot & Student Adaptation
+            "qa-optimize", # Course QA Optimizer
+            "content",     # Content Generator (Lesson Plan & PPT)
+        ],
+    }

api/routes_teacher.py

@@ -128,7 +128,7 @@ def post_assessment_analysis(req: AssessmentAnalysisRequest):
 
 @router.get("/api/teacher/status")
 def get_teacher_status():
-    """教师 Agent 状态（是否已配置 Weaviate）。"""
+    """教师 Agent 状态（是否已配置 Weaviate）；含 Courseware 模块入口。"""
     return {
         "weaviate_configured": USE_WEAVIATE,
         "features": [
@@ -137,4 +137,8 @@ def get_teacher_status():
             "assignment-questions",
             "assessment-analysis",
         ],
+        "courseware_modules": [
+            "vision", "activities", "copilot", "qa-optimize", "content",
+        ],
+        "courseware_base": "/api/courseware",
     }

api/server.py

@@ -34,6 +34,8 @@ from api.tts_podcast import (
 from api.routes_directory import router as directory_router
 # ✅ 教师 Agent：课程描述、文档建议、作业题库、学习评估
 from api.routes_teacher import router as teacher_router
+# ✅ Courseware：课程愿景、活动设计、课堂助教、QA 优化、教案与 PPT
+from api.routes_courseware import router as courseware_router
 
 # ✅ LangSmith (optional)
 try:
@@ -96,6 +98,7 @@ app.add_middleware(
 # ✅ NEW: include directory/workspace APIs BEFORE SPA fallback
 app.include_router(directory_router)
 app.include_router(teacher_router)
+app.include_router(courseware_router)
 
 # ----------------------------
 # Static hosting (Vite build)

api/weaviate_retrieve.py

@@ -2,12 +2,16 @@
 """
 与 ClareVoice 共用同一 Weaviate 数据库（GenAICourses）的检索封装。
 教师 Agent 和 Clare 均可调用，需与 build_weaviate_index 使用相同 embedding（HF all-MiniLM-L6-v2）。
+支持带引用的检索：返回 (text, refs)，用于标注 [Source: Filename/Page]。
 """
 import os
-from typing import Optional
+from typing import List, Optional, Tuple
 
 from .config import USE_WEAVIATE, WEAVIATE_URL, WEAVIATE_API_KEY, WEAVIATE_COLLECTION
 
+# 引用项：本地 VDB 为 {"type": "vdb", "source": "Filename", "page": "1"}，Web 为 {"type": "web", "url": "..."}
+RefItem = dict
+
 
 def retrieve_from_weaviate(query: str, top_k: int = 8, timeout_sec: float = 45.0) -> str:
     """
@@ -59,3 +63,75 @@ def retrieve_from_weaviate(query: str, top_k: int = 8, timeout_sec: float = 45.0
     except concurrent.futures.TimeoutError:
         print(f"[weaviate_retrieve] timeout after {timeout_sec}s")
         return ""
+
+
+def retrieve_from_weaviate_with_refs(
+    query: str, top_k: int = 8, timeout_sec: float = 45.0
+) -> Tuple[str, List[RefItem]]:
+    """
+    从 Weaviate 检索并返回正文与引用列表。引用用于标注 [Source: Filename/Page]。
+    若 node 无 file_name/page 等元数据，则用 index_name 或 "GenAICourses" 作为 source。
+    """
+    if not USE_WEAVIATE or not query or len(query.strip()) < 3:
+        return "", []
+
+    def _call() -> Tuple[str, List[RefItem]]:
+        try:
+            import weaviate
+            from weaviate.classes.init import Auth
+            from llama_index.core import Settings, VectorStoreIndex
+            from llama_index.vector_stores.weaviate import WeaviateVectorStore
+            from llama_index.embeddings.huggingface import HuggingFaceEmbedding
+
+            Settings.embed_model = HuggingFaceEmbedding(
+                model_name=os.getenv("HF_EMBEDDING_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
+            )
+            client = weaviate.connect_to_weaviate_cloud(
+                cluster_url=WEAVIATE_URL,
+                auth_credentials=Auth.api_key(WEAVIATE_API_KEY),
+            )
+            try:
+                if not client.is_ready():
+                    return "", []
+                vs = WeaviateVectorStore(
+                    weaviate_client=client,
+                    index_name=WEAVIATE_COLLECTION,
+                )
+                index = VectorStoreIndex.from_vector_store(vs)
+                nodes = index.as_retriever(similarity_top_k=top_k).retrieve(query)
+                if not nodes:
+                    return "", []
+                texts = []
+                refs: List[RefItem] = []
+                seen = set()
+                for n in nodes:
+                    content = n.get_content()
+                    if isinstance(content, str) and content.strip():
+                        texts.append(content.strip())
+                    # NodeWithScore: n.node 或 n 上可能有 metadata
+                    node = getattr(n, "node", n)
+                    meta = getattr(node, "metadata", None) or {}
+                    fname = (meta.get("file_name") or meta.get("source_file") or meta.get("filename") or WEAVIATE_COLLECTION or "GenAICourses").strip()
+                    page = (meta.get("page_label") or meta.get("page_number") or meta.get("page") or "")
+                    page_str = str(page).strip() if page else ""
+                    key = (fname, page_str)
+                    if key not in seen:
+                        seen.add(key)
+                        refs.append({"type": "vdb", "source": fname, "page": page_str})
+                return "\n\n---\n\n".join(texts), refs
+            finally:
+                client.close()
+        except ImportError as e:
+            print(f"[weaviate_retrieve] 未安装 weaviate/llama_index，跳过 RAG: {e}")
+            return "", []
+        except Exception as e:
+            print(f"[weaviate_retrieve] {repr(e)}")
+            return "", []
+
+    try:
+        import concurrent.futures
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as ex:
+            return ex.submit(_call).result(timeout=timeout_sec)
+    except concurrent.futures.TimeoutError:
+        print(f"[weaviate_retrieve] timeout after {timeout_sec}s")
+        return "", []

docs/COURSEWARE_AGENT.md

@@ -0,0 +1,96 @@
+# AI Teacher Assistant Agent（Courseware）API
+
+将原有教师端能力重构为**模块化 AI Teacher Assistant Agent**，基于「课程描述 + 辅助材料」与 RAG，生成全链路教学资源。所有生成内容均带 **Reference**。
+
+## Reference 规范（技术约束）
+
+- **本地 VDB（Weaviate / 上传文件）**：`[Source: Filename/Page]`
+- **Web Search**：`[Source: URL]`
+
+回答末尾包含 References 小节，或正文中按上述格式标注来源。
+
+## 核心模块与 API
+
+| 模块 | 路径 | 说明 |
+|------|------|------|
+| Course Vision & Structure Builder | `POST /api/courseware/vision` | 输入课程基本信息 + 教学大纲 → 课程定位、学习目标、层级化知识树 |
+| Activity & Assignment Designer | `POST /api/courseware/activities` | 设计课堂活动、作业及 Rubric；支持从上传资料提取核心知识点（`rag_context_override`） |
+| Teaching Copilot & Student Adaptation | `POST /api/courseware/copilot` | 课堂实时辅助；根据学生画像（Name, Progress, Behavior）动态调整建议 |
+| Course QA Optimizer | `POST /api/courseware/qa-optimize` | 基于 Smart Quiz 答题数据分析弱点，输出教学优化建议 |
+| Content Generator | `POST /api/courseware/content` | 生成 Markdown 详细教案 + 可用于 PPT 的结构化数据 |
+
+- 状态：`GET /api/courseware/status`
+
+## 请求/响应示例
+
+### 1. Course Vision
+
+```json
+POST /api/courseware/vision
+{
+  "course_info": "IST345 生成式人工智能与负责任创新",
+  "syllabus": "Week 1–5 基础；Week 6–10 应用与伦理。"
+}
+
+→ { "ok": true, "content": "...课程定位、学习目标、知识树...\n\n## References\n[Source: GenAICourses]", "weaviate_used": true }
+```
+
+### 2. Activities（可传入上传资料摘要）
+
+```json
+POST /api/courseware/activities
+{
+  "topic": "RAG 与检索增强",
+  "learning_objectives": "理解 embedding、检索流程",
+  "rag_context_override": "（可选）从上传文件 RAG 得到的摘要，覆盖 Weaviate 检索"
+}
+```
+
+### 3. Teaching Copilot
+
+```json
+POST /api/courseware/copilot
+{
+  "current_content": "正在讲 Transformer 自注意力",
+  "student_profiles": [
+    { "name": "张三", "progress": "80%", "behavior": "积极提问" },
+    { "name": "李四", "progress": "60%", "behavior": "沉默" }
+  ]
+}
+```
+
+### 4. QA Optimizer
+
+```json
+POST /api/courseware/qa-optimize
+{
+  "quiz_summary": "第 3 题正确率 45%，多数混淆了 encoder/decoder",
+  "course_topic": "Transformer 与 Seq2Seq"
+}
+```
+
+### 5. Content（教案 + PPT 数据）
+
+```json
+POST /api/courseware/content
+{
+  "topic": "Prompt Engineering",
+  "duration": "1 课时",
+  "outline_points": "Zero-shot, Few-shot, CoT"
+}
+```
+
+## 代码结构
+
+- `api/courseware/`：模块化实现
+  - `prompts.py`：各模块独立 Prompt 模板
+  - `references.py`：Reference 格式化（Filename/Page、URL）
+  - `rag.py`：RAG 上下文 + 引用（Weaviate + 可选 Web）
+  - `vision_builder.py`、`activity_designer.py`、`teaching_copilot.py`、`qa_optimizer.py`、`content_generator.py`
+- `api/weaviate_retrieve.py`：新增 `retrieve_from_weaviate_with_refs()` 返回 `(text, refs)`
+- `api/routes_courseware.py`：Courseware API 路由
+
+## 与教师端原有接口的关系
+
+- 原有 `api/teacher/*`（课程描述、文档建议、作业建议、评估分析）保留不变。
+- `GET /api/teacher/status` 增加 `courseware_modules` 与 `courseware_base`，便于前端跳转或聚合展示。