Add teacher agent, docs, and project updates; ClareVoiceV1 remains untracked (nested repo)

.gitignore

@@ -31,3 +31,9 @@ data/courses/**/raw/
 
 # HF Space clones (nested repos – push main project only)
 hf_space/
+
+# 临时目录：ClareVoice 独立仓库 push 用，push 完成后可删除
+_clarevoice_push/
+
+# ClareCourseWare Space 本地 clone，push 到 HF 后保留或删除
+ClareCourseWare_push/

PUSH_TO_HF.md

@@ -0,0 +1,61 @@
+# 推送到 Hugging Face Space（claudqunwang/ClareVoice）
+
+## 之前「整库 force 推送」和「只换 UI」的区别
+
+| | 之前的做法（整库 force 推送） | 只换 UI（推荐） |
+|---|---|---|
+| **操作** | `git push huggingface main --force`，把本地整份项目推上去 | 先 clone HF 上现有 Space，只**新增** web 前端 + 后端 api，改 Dockerfile，再普通 push |
+| **结果** | HF 上所有内容被本地项目**完全覆盖**，你在 HF 上改过的 app.py、config、Dockerfile、README 等都会变成本地版本 | HF 上现有文件**全部保留**，只多出 `web/`、`api/` 和一个新的 Dockerfile，运行时改用 React UI |
+| **你的改动** | 会丢失 | 会保留（原有文件仍在仓库里） |
+
+所以：**不想覆盖在 HF 上的改动、只想换成 React UI 时**，不要用 force 推送整库，而是按下面「只换 UI」的步骤做。
+
+---
+
+## 做法一：只换 UI（保留你在 HF 上的所有改动）
+
+在**本机**执行（需已安装 git、node、python）：
+
+```bash
+# 1. 克隆 HF 上当前的 Space（保留你的历史与改动）
+git clone https://huggingface.co/spaces/claudqunwang/ClareVoice
+cd ClareVoice
+
+# 2. 从本地 Clare 项目复制「仅 UI 相关」内容（不覆盖你已有的文件）
+#    把下面的 /path/to/AI_Agent_Clare-main 改成你本机项目路径
+PROJECT=/Users/qunwang/AI_Agent_Clare-main
+
+cp -r "$PROJECT/web" .
+cp -r "$PROJECT/api" .
+
+# 3. 用「产品版」Dockerfile 替换当前的（改为构建 web + 跑 FastAPI 提供 React UI）
+cp "$PROJECT/Dockerfile" .
+
+# 4. 为 FastAPI 增加依赖（Space 原 requirements 可能没有）
+echo "fastapi>=0.111.0" >> requirements.txt
+echo "uvicorn[standard]>=0.30.0" >> requirements.txt
+echo "python-multipart>=0.0.9" >> requirements.txt
+
+# 5. 提交并推送（普通 push，不 force）
+git add web/ api/ Dockerfile requirements.txt
+git status   # 确认只多了 web、api 和 Dockerfile
+git commit -m "Switch to React product UI (web + api), keep existing files"
+git push
+```
+
+这样 HF 上会多出 `web/`、`api/` 和新的 `Dockerfile`，**原有 app.py、config.py、clare_core.py 等都不会被覆盖**；之后 Space 会用新 Dockerfile 构建并显示 React UI。
+
+**注意**：新 Dockerfile 的启动命令是 `uvicorn api.server:app`，即运行时用的是 **api/** 里的后端（api/config.py、api/clare_core.py 等）。若你之前在 HF 上只改了**根目录**的 config、clare_core，那些修改不会自动出现在新 UI 的后端里；若需要沿用，可以把根目录的配置或逻辑同步到 api/ 下，或再改 Dockerfile 的 working directory 让 api 使用根目录模块（需自行改 import 路径）。
+
+---
+
+## 做法二：整库覆盖（不保留 HF 上的改动）
+
+仅当你确定要**用本地项目完全替换** Space 内容时再用：
+
+```bash
+cd /Users/qunwang/AI_Agent_Clare-main
+git push -u huggingface main --force
+```
+
+这会用本地整份项目（含 GENAI COURSES、当前 README、.gitignore 等）覆盖 HF 上的 ClareVoice，你在 HF 上做过的任何修改都会丢失。

api/config.py

@@ -200,3 +200,15 @@ Safety and honesty:
 - Do not fabricate references, exam answers, or grades.
 """
 
+# ============================
+# Weaviate（教师 Agent / ClareVoice 共用，可选）
+# ============================
+WEAVIATE_URL = (os.getenv("WEAVIATE_URL") or "").strip()
+WEAVIATE_API_KEY = (os.getenv("WEAVIATE_API_KEY") or "").strip()
+WEAVIATE_COLLECTION = (os.getenv("WEAVIATE_COLLECTION") or "GenAICourses").strip()
+if WEAVIATE_COLLECTION and not WEAVIATE_COLLECTION[0].isupper():
+    WEAVIATE_COLLECTION = "GenAICourses"
+USE_WEAVIATE = bool(WEAVIATE_URL and WEAVIATE_API_KEY)
+if USE_WEAVIATE and not WEAVIATE_URL.startswith("http"):
+    WEAVIATE_URL = "https://" + WEAVIATE_URL
+

api/routes_teacher.py

@@ -0,0 +1,140 @@
+# api/routes_teacher.py
+"""教师 Agent API：课程描述、文档建议、作业题库建议、学习评估分析。"""
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from api.teacher_agent import (
+    generate_course_description,
+    suggest_course_doc_content,
+    suggest_assignments_questions,
+    analyze_student_assessment,
+)
+from api.config import USE_WEAVIATE
+
+router = APIRouter(tags=["teacher"])
+
+
+class CourseDescriptionRequest(BaseModel):
+    topic: str = Field(..., min_length=1, description="课程主题/名称")
+    outline_hint: str | None = Field(None, description="可选：大纲或要点")
+
+
+class CourseDescriptionResponse(BaseModel):
+    ok: bool = True
+    description: str
+    weaviate_used: bool = False
+
+
+@router.post("/api/teacher/course-description", response_model=CourseDescriptionResponse)
+def post_course_description(req: CourseDescriptionRequest):
+    """课程描述生成。"""
+    try:
+        desc = generate_course_description(
+            topic=req.topic.strip(),
+            outline_hint=req.outline_hint.strip() if req.outline_hint else None,
+        )
+        return CourseDescriptionResponse(
+            description=desc,
+            weaviate_used=USE_WEAVIATE,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+class DocSuggestionRequest(BaseModel):
+    topic: str = Field(..., min_length=1, description="主题或章节")
+    current_doc_excerpt: str | None = Field(None, description="当前已有内容片段")
+    doc_type: str = Field("讲义/课件", description="文档类型")
+
+
+class DocSuggestionResponse(BaseModel):
+    ok: bool = True
+    suggestion: str
+    weaviate_used: bool = False
+
+
+@router.post("/api/teacher/doc-suggestion", response_model=DocSuggestionResponse)
+def post_doc_suggestion(req: DocSuggestionRequest):
+    """课程文档内容建议。"""
+    try:
+        suggestion = suggest_course_doc_content(
+            topic=req.topic.strip(),
+            current_doc_excerpt=req.current_doc_excerpt.strip() if req.current_doc_excerpt else None,
+            doc_type=req.doc_type.strip() or "讲义/课件",
+        )
+        return DocSuggestionResponse(
+            suggestion=suggestion,
+            weaviate_used=USE_WEAVIATE,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+class AssignmentQuestionsRequest(BaseModel):
+    topic: str = Field(..., min_length=1, description="主题")
+    week_or_module: str | None = Field(None, description="周次/模块")
+    question_type: str = Field("混合", description="题型：选择题、简答题、开放题、混合")
+
+
+class AssignmentQuestionsResponse(BaseModel):
+    ok: bool = True
+    suggestion: str
+    weaviate_used: bool = False
+
+
+@router.post("/api/teacher/assignment-questions", response_model=AssignmentQuestionsResponse)
+def post_assignment_questions(req: AssignmentQuestionsRequest):
+    """作业和题库生成建议。"""
+    try:
+        suggestion = suggest_assignments_questions(
+            topic=req.topic.strip(),
+            week_or_module=req.week_or_module.strip() if req.week_or_module else None,
+            question_type=req.question_type.strip() or "混合",
+        )
+        return AssignmentQuestionsResponse(
+            suggestion=suggestion,
+            weaviate_used=USE_WEAVIATE,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+class AssessmentAnalysisRequest(BaseModel):
+    assessment_summary: str = Field(..., min_length=1, description="学生表现/评估摘要")
+    course_topic_hint: str | None = Field(None, description="可选：相关课程主题")
+
+
+class AssessmentAnalysisResponse(BaseModel):
+    ok: bool = True
+    analysis: str
+    weaviate_used: bool = False
+
+
+@router.post("/api/teacher/assessment-analysis", response_model=AssessmentAnalysisResponse)
+def post_assessment_analysis(req: AssessmentAnalysisRequest):
+    """学生学习评估分析。"""
+    try:
+        analysis = analyze_student_assessment(
+            assessment_summary=req.assessment_summary.strip(),
+            course_topic_hint=req.course_topic_hint.strip() if req.course_topic_hint else None,
+        )
+        return AssessmentAnalysisResponse(
+            analysis=analysis,
+            weaviate_used=USE_WEAVIATE,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/api/teacher/status")
+def get_teacher_status():
+    """教师 Agent 状态（是否已配置 Weaviate）。"""
+    return {
+        "weaviate_configured": USE_WEAVIATE,
+        "features": [
+            "course-description",
+            "doc-suggestion",
+            "assignment-questions",
+            "assessment-analysis",
+        ],
+    }

api/server.py

@@ -31,6 +31,8 @@ from api.tts_podcast import (
 
 # ✅ NEW: course directory + workspace schema routes
 from api.routes_directory import router as directory_router
+# ✅ 教师 Agent：课程描述、文档建议、作业题库、学习评估
+from api.routes_teacher import router as teacher_router
 
 # ✅ LangSmith (optional)
 try:
@@ -92,6 +94,7 @@ app.add_middleware(
 
 # ✅ NEW: include directory/workspace APIs BEFORE SPA fallback
 app.include_router(directory_router)
+app.include_router(teacher_router)
 
 # ----------------------------
 # Static hosting (Vite build)

api/teacher_agent.py

@@ -0,0 +1,116 @@
+# api/teacher_agent.py
+"""
+教师端 AI Agent：基于与 Clare 相同的 Weaviate（GenAICourses）与 OpenAI，为教师提供：
+- 课程描述生成
+- 课程文档内容建议
+- 作业和题库生成建议
+- 学生学习评估分析
+"""
+from typing import Optional
+
+from .config import client, DEFAULT_MODEL, USE_WEAVIATE
+from .weaviate_retrieve import retrieve_from_weaviate
+
+TEACHER_SYSTEM = """你是一位面向高校教师的 AI 助教，擅长课程设计、教学材料建议与学习评估分析。
+你与 Clare 共用同一套 GENAI 课程知识库（Weaviate）。回答时请优先依据提供的「课程知识库摘录」，
+并结合通用教学经验，给出简洁、可操作的中文建议。若未提供知识库摘录，则基于通用教育学与学科知识回答。"""
+
+
+def _call_llm(user_content: str, system_extra: str = "", max_tokens: int = 1500) -> str:
+    system = TEACHER_SYSTEM
+    if system_extra:
+        system = system + "\n\n" + system_extra
+    try:
+        resp = client.chat.completions.create(
+            model=DEFAULT_MODEL,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.6,
+            max_tokens=max_tokens,
+            timeout=60,
+        )
+        return (resp.choices[0].message.content or "").strip()
+    except Exception as e:
+        print(f"[teacher_agent] LLM error: {repr(e)}")
+        return f"生成时出错：{repr(e)}。请稍后重试。"
+
+
+def generate_course_description(
+    topic: str,
+    outline_hint: Optional[str] = None,
+) -> str:
+    """
+    课程描述生成：根据课程主题（及可选大纲要点）生成一段可用于课程介绍/选课页的描述。
+    """
+    rag = retrieve_from_weaviate(topic, top_k=6) if USE_WEAVIATE else ""
+    user = f"请根据以下信息，生成一段简洁的**课程描述**（约 150–250 字），适合放在课程介绍或选课页面。\n\n"
+    user += f"**课程主题/名称：** {topic}\n\n"
+    if outline_hint:
+        user += f"**大纲或要点（可选）：**\n{outline_hint}\n\n"
+    if rag:
+        user += "**参考知识库摘录（请据此保持与现有课程内容一致）：**\n" + rag[:4000] + "\n\n"
+    user += "请直接输出课程描述正文，无需重复题目。"
+    return _call_llm(user, max_tokens=800)
+
+
+def suggest_course_doc_content(
+    topic: str,
+    current_doc_excerpt: Optional[str] = None,
+    doc_type: str = "讲义/课件",
+) -> str:
+    """
+    课程文档内容建议：针对某一主题或现有文档片段，给出可写入讲义/课件的内容建议。
+    """
+    rag = retrieve_from_weaviate(topic, top_k=8) if USE_WEAVIATE else ""
+    user = f"请针对以下**课程文档**（类型：{doc_type}）给出**内容建议**：结构要点、关键概念、可选的例子或习题方向。\n\n"
+    user += f"**主题或章节：** {topic}\n\n"
+    if current_doc_excerpt:
+        user += f"**当前已有内容（片段）：**\n{current_doc_excerpt[:2000]}\n\n"
+    if rag:
+        user += "**参考知识库摘录：**\n" + rag[:5000] + "\n\n"
+    user += "请用分点或短段落给出建议，便于教师直接采纳或改写。"
+    return _call_llm(user, max_tokens=1200)
+
+
+def suggest_assignments_questions(
+    topic: str,
+    week_or_module: Optional[str] = None,
+    question_type: str = "混合",
+) -> str:
+    """
+    作业和题库生成建议：根据主题（及可选周次/模块）给出作业题、练习题或考试题建议。
+    question_type 可为：选择题、简答题、开放题、混合 等。
+    """
+    rag = retrieve_from_weaviate(topic, top_k=8) if USE_WEAVIATE else ""
+    user = f"请根据以下课程信息，给出**作业与题库**的生成建议：包含题目类型、难度分布、2–3 道示例题（含参考答案要点）。\n\n"
+    user += f"**主题：** {topic}\n\n"
+    if week_or_module:
+        user += f"**周次/模块：** {week_or_module}\n\n"
+    user += f"**题型偏好：** {question_type}\n\n"
+    if rag:
+        user += "**参考知识库摘录：**\n" + rag[:5000] + "\n\n"
+    user += "请直接给出建议与示例题，便于教师录入题库或布置作业。"
+    return _call_llm(user, max_tokens=1500)
+
+
+def analyze_student_assessment(
+    assessment_summary: str,
+    course_topic_hint: Optional[str] = None,
+) -> str:
+    """
+    学生学习评估分析：根据教师提供的学生表现摘要（如作业/测验得分、常见错误、参与度等），
+    给出简要分析结论与教学改进建议。
+    """
+    rag = ""
+    if course_topic_hint and USE_WEAVIATE:
+        rag = retrieve_from_weaviate(course_topic_hint, top_k=4)
+    user = "请根据以下**学生学习评估信息**，给出简要的**分析结论**与**教学改进建议**（分点、可操作）。\n\n"
+    user += f"**评估摘要：**\n{assessment_summary}\n\n"
+    if course_topic_hint:
+        user += f"**相关课程主题：** {course_topic_hint}\n\n"
+    if rag:
+        user += "**参考知识库摘录（可选，用于对齐课程目标）：**\n" + rag[:3000] + "\n\n"
+    user += "请用中文输出，控制在 300–500 字。"
+    return _call_llm(user, max_tokens=800)

api/weaviate_retrieve.py

@@ -0,0 +1,61 @@
+# api/weaviate_retrieve.py
+"""
+与 ClareVoice 共用同一 Weaviate 数据库（GenAICourses）的检索封装。
+教师 Agent 和 Clare 均可调用，需与 build_weaviate_index 使用相同 embedding（HF all-MiniLM-L6-v2）。
+"""
+import os
+from typing import Optional
+
+from .config import USE_WEAVIATE, WEAVIATE_URL, WEAVIATE_API_KEY, WEAVIATE_COLLECTION
+
+
+def retrieve_from_weaviate(query: str, top_k: int = 8, timeout_sec: float = 45.0) -> str:
+    """
+    从 Weaviate Cloud 的 GenAICourses 中检索与 query 相关的课程片段。
+    使用 HuggingFace all-MiniLM-L6-v2 与建索引时一致。
+    若未配置 Weaviate、query 过短、或依赖未安装，返回空字符串（教师 Agent 仍可运行，仅无 RAG）。
+    """
+    if not USE_WEAVIATE or not query or len(query.strip()) < 3:
+        return ""
+
+    def _call() -> str:
+        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)
+                return "\n\n---\n\n".join(n.get_content() for n in nodes) if nodes else ""
+            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/FRONTEND_BACKEND_AND_PODCAST.md

@@ -0,0 +1,109 @@
+# Clare AI Agent：前后端配合说明 & Podcast 集成到独立网站
+
+## 一、前后端需要配合做什么
+
+整体上：**前端负责 UI 和用户操作，后端负责会话状态、RAG、LLM 调用和音频生成**。具体分工如下。
+
+### 1. 会话与身份
+
+| 能力 | 后端 | 前端 |
+|------|------|------|
+| 登录 | `POST /api/login` 校验并建立会话（内存里存 `user_id`） | 收集姓名/ID，调用 login，存 `user`（如 `user_id` = email） |
+| 会话状态 | 按 `user_id` 存 history、course_outline、weaknesses、cognitive_state、上传文件等 | 所有需要会话的请求都带 `user_id`（如 `user.email`） |
+
+### 2. 对话与内容
+
+| 能力 | 后端 | 前端 |
+|------|------|------|
+| 对话 | `POST /api/chat`：RAG 检索 + LLM 生成，返回回复 + 可选 references | 发 message、learning_mode、language_preference，渲染回复和引用 |
+| 上传 | `POST /api/upload`：解析文件、更新该用户的 course_outline / RAG chunks | 选文件、doc_type，上传后刷新侧边栏/状态 |
+| 导出 | `POST /api/export`：根据当前会话 history 生成 Markdown 文本 | 调 export，展示或下载文本 |
+| 总结 | `POST /api/summary`：对当前会话做总结，返回 Markdown | 调 summary，展示在右侧或弹窗 |
+
+### 3. 音频（TTS / Podcast）
+
+| 能力 | 后端 | 前端 |
+|------|------|------|
+| TTS | `POST /api/tts`：接收一段 text，调用 OpenAI TTS，返回 **MP3 二进制**（`audio/mpeg`） | 传 `user_id` + `text`，用 `response.blob()` 得到 Blob → `URL.createObjectURL(blob)` 给 `<audio src>` 播放或下载 |
+| Podcast | `POST /api/podcast`：根据 `source=summary|conversation` 用当前会话生成脚本，再 TTS 合成，返回 **MP3 二进制**（`audio/mpeg`） | 传 `user_id` + `source`，同样用 Blob → Object URL 播放/下载 |
+
+### 4. 其他
+
+- Memory Line、Profile 状态、Quiz 等：前端按需调对应 API，后端按 `user_id` 读会话状态并返回。
+- 前端需统一配置 **API 基地址**（如 `VITE_API_BASE`），保证请求发到 Clare 后端。
+
+**小结**：后端不写前端 UI，只提供 REST API 和会话状态；前端负责所有展示、表单和把「当前用户」(`user_id`) 带到每次请求里。Podcast 当前是「请求一次、返回一段 MP3 流」，不落盘。
+
+---
+
+## 二、把 Podcast 集成到「独立网站」的两种方式
+
+当前实现里，**Podcast 不会生成可下载的 MP3 文件链接**，而是接口**直接返回 MP3 字节流**，由调用方在内存里播放或触发下载。
+
+若你要在**独立网站**（与当前 React 应用分离的站点）里集成 podcast，有两种常见做法。
+
+### 方式 A：不落盘，直接用 API 返回的 MP3 流（当前能力即可）
+
+**流程：**
+
+1. 独立网站（同源或配置好 CORS 的后端代理）向 Clare 后端发：  
+   `POST /api/podcast`，body：`{ "user_id": "...", "source": "summary" | "conversation", "voice": "nova" }`。
+2. 后端生成 podcast，**直接在响应体里返回 MP3**（`Content-Type: audio/mpeg`）。
+3. 独立网站用 `fetch` 拿到 `response.blob()`，然后：
+   - **播放**：`URL.createObjectURL(blob)` 得到临时 URL，赋给 `<audio src="...">`；
+   - **下载**：用 `<a download>` + Object URL，或 Blob 转成文件让用户保存。
+
+**特点：**
+
+- **不需要**在后端生成「可下载的 MP3 文件」再让网站访问；
+- 不占磁盘、不涉及文件 URL；适合「当前会话、一次性听/下」；
+- 独立网站只要能用 JavaScript 调 Clare 的 API（或通过自己的后端转发）即可。
+
+**结论：**  
+若独立网站可以发 POST 并处理 Blob，**不需要**先生成可下载的 MP3 文件再给网站访问；直接使用接口返回的 MP3 流即可播放和下载。
+
+---
+
+### 方式 B：生成可下载的 MP3 文件，网站用「链接」播放/下载
+
+适用于：
+
+- 需要**固定、可分享的链接**（例如发给别人、放 RSS、嵌入第三方播放器）；
+- 希望**缓存**同一脚本的 MP3，避免重复生成；
+- 独立网站只能提供「一个 MP3 地址」，不能发 POST（例如纯静态页、外嵌 `<audio src="https://...">`）。
+
+**做法：**
+
+1. **后端**在生成完 podcast 后：
+   - 把 MP3 写入**文件**（例如 `/static/podcasts/<session_id>_<timestamp>.mp3`）或对象存储（如 S3/OSS），
+   - 返回一个**可访问的 URL**，例如：  
+     `https://your-api.com/static/podcasts/xxx.mp3` 或存储的 public URL。
+2. **独立网站**：
+   - 用该 URL 做 `<audio src="...">` 播放；
+   - 或用 `<a href="..." download>下载</a>` 提供下载。
+
+这样就是「**生成可下载的 MP3，再让网站通过文件 URL 访问/播放**」。
+
+若要采用方式 B，后端需要增加逻辑（例如）：
+
+- 在 `POST /api/podcast` 里，生成 MP3 后写入指定目录或上传到存储；
+- 在响应里不再只返回 `audio/mpeg` 流，而是返回 JSON，例如：  
+  `{ "url": "https://.../podcasts/xxx.mp3", "expires_in": 3600 }`；  
+  或保留当前「直接返回 MP3」的行为，并**额外**提供一个 `GET /api/podcast/<id>` 或静态路径，用于通过 URL 访问已生成的 MP3。
+
+---
+
+## 三、简要对比
+
+| 维度 | 方式 A：直接用 API 返回的 MP3 流 | 方式 B：生成 MP3 文件 + URL |
+|------|----------------------------------|-----------------------------|
+| 是否需要生成可下载文件 | **否** | **是**（写盘或对象存储） |
+| 网站如何播放/下载 | 用 Blob + Object URL 或 `<a download>` | 用返回的 URL 做 `<audio src>` / 下载链接 |
+| 是否可分享/固定链接 | 否（每次请求新生成） | 是 |
+| 是否适合纯静态页「只填 URL」 | 否（需能发 POST） | 是 |
+| 当前 Clare 是否支持 | **是**（现有 `/api/podcast` 即可） | 需在后端增加「落盘/存储 + 返回 URL」 |
+
+**总结：**
+
+- **不需要**「先生成可下载的 MP3 再让网站访问」：用现有 `/api/podcast`，在独立网站里用 POST + Blob 即可播放和下载（方式 A）。
+- **需要**「可分享链接、外嵌播放器、纯 URL 访问」时：再在后端增加「生成 MP3 文件并返回 URL」的能力（方式 B）。

docs/TEACHER_AGENT.md

@@ -0,0 +1,50 @@
+# 教师 Agent（AI 智能建课）
+
+面向教师的 AI 助教，与 Clare 共用同一 Weaviate 数据库（GenAICourses），辅助设计与改进课程。
+
+## 功能
+
+| 功能 | 说明 |
+|------|------|
+| **课程描述生成** | 根据课程主题（及可选大纲）生成可用于课程介绍/选课页的简洁描述 |
+| **课程文档内容建议** | 针对某一主题或现有文档片段，给出讲义/课件的内容与结构建议 |
+| **作业和题库生成建议** | 根据主题与周次，给出作业题、练习题或考试题建议与示例 |
+| **学生学习评估分析** | 根据学生表现摘要，给出分析结论与教学改进建议 |
+
+## 使用方式
+
+1. **Web 界面**：启动后端与前端后，在页面右上角点击 **「AI 智能建课」** 进入教师仪表盘；使用完毕可点击 **「返回学习」** 回到 Clare 对话。
+2. **API**：直接调用以下接口（需已登录或按需鉴权）：
+   - `POST /api/teacher/course-description` — 课程描述
+   - `POST /api/teacher/doc-suggestion` — 文档建议
+   - `POST /api/teacher/assignment-questions` — 作业/题库建议
+   - `POST /api/teacher/assessment-analysis` — 学习评估分析
+   - `GET /api/teacher/status` — 状态（是否已配置 Weaviate）
+
+## Weaviate 配置（可选）
+
+与 ClareVoice 相同：在环境变量或 `.env` 中配置：
+
+- `WEAVIATE_URL`：Weaviate Cloud 集群地址（如 `https://xxx.c0.us-west3.gcp.weaviate.cloud`）
+- `WEAVIATE_API_KEY`：API Key
+- `WEAVIATE_COLLECTION`：可选，默认 `GenAICourses`
+
+配置后，教师 Agent 会从 GenAICourses 中检索相关课程片段作为 RAG 上下文，生成更贴合课程内容的建议。未配置时仍可运行，仅不使用知识库检索。
+
+## 依赖（启用 Weaviate 时）
+
+若需在**本仓库**（非 ClareVoice Space）使用 Weaviate，请安装：
+
+```bash
+pip install weaviate-client>=4.0.0 llama-index-core>=0.10.0 llama-index-vector-stores-weaviate>=0.2.0 llama-index-embeddings-huggingface>=0.1.0 sentence-transformers>=2.2.0
+```
+
+索引需使用 **HuggingFace** `sentence-transformers/all-MiniLM-L6-v2` 构建（与 ClareVoice / `build_weaviate_index.py` 一致）。
+
+## 代码结构
+
+- `api/config.py` — Weaviate 相关环境变量（`USE_WEAVIATE` 等）
+- `api/weaviate_retrieve.py` — 共用 Weaviate 检索
+- `api/teacher_agent.py` — 四个功能的 LLM + RAG 逻辑
+- `api/routes_teacher.py` — FastAPI 路由
+- `web/src/components/TeacherDashboard.tsx` — 教师仪表盘 UI（四张卡片）

docs/VECTOR_DB_LOGIC_AND_MULTI_COURSE.md

@@ -0,0 +1,222 @@
+# ClareVoice 向量数据库逻辑 · 多课程支持 · 优化计划
+
+本文档**只描述 ClareVoice（HF Space）**的向量库设计与扩展思路。
+
+---
+
+## 一、当前向量数据库是怎么做的
+
+**ClareVoice 使用 Weaviate Cloud 作为课程知识库**，同时会话级 RAG 用内存 + FAISS。双路检索结果在对话时拼接。
+
+### 1.1 Weaviate + 内存双路检索
+
+| 数据源 | 存储位置 | 用途 | 检索入口 |
+|--------|----------|------|----------|
+| **Weaviate Cloud** | 持久化向量库（GCP） | GENAI 课程文档（151+ 文档，由 `build_weaviate_index.py` 一次性写入） | `_retrieve_from_weaviate(question)` |
+| **内存 + FAISS** | 进程内 `SESSIONS[user_id]["rag_chunks"]` | Module 10 预读 + 用户上传文件 | `retrieve_relevant_chunks()` |
+
+**Weaviate 流程简述：**
+
+1. **建索引（一次性）**  
+   - 脚本：`hf_space/GenAICoursesDB_space/build_weaviate_index.py`  
+   - 读取 `GENAI COURSES` 目录（.md / .pdf / .txt / .py / .ipynb / .docx），用 LlamaIndex `SimpleDirectoryReader` 加载 → `VectorStoreIndex.from_documents()` + `WeaviateVectorStore`，写入 Weaviate Cloud 的 **collection `GenAICourses`**。  
+   - Embedding：默认 `sentence-transformers/all-MiniLM-L6-v2`（与 ClareVoice 运行时一致）；可选 `EMBEDDING_PROVIDER=openai` 用 `text-embedding-3-small`。
+
+2. **运行时检索**（`hf_space/ClareVoice/app.py`）  
+   - 配置：`WEAVIATE_URL`、`WEAVIATE_API_KEY`、`WEAVIATE_COLLECTION`（默认 `GenAICourses`），`USE_WEAVIATE_DIRECT=True` 时启用。  
+   - `_get_weaviate_embed_model()`：懒加载并缓存 **HuggingFaceEmbedding(all-MiniLM-L6-v2)**（与建索引时一致）。  
+   - `_retrieve_from_weaviate(question, top_k=5)`：连接 Weaviate Cloud → `WeaviateVectorStore` + `VectorStoreIndex.from_vector_store(vs)` → `as_retriever(similarity_top_k=top_k).retrieve(question)` → 将 node 内容用 `---` 拼接成字符串返回。  
+   - 启动时 `_warmup_weaviate_embed()` 在后台线程预热 embedding 模型，减少首次检索超时。  
+   - 未配置 Weaviate 时回退到调用 **GenAICoursesDB Space** 的 `/retrieve` 接口。
+
+3. **对话时的组合**  
+   - 先按会话用 `retrieve_relevant_chunks(sess["rag_chunks"])` 得到「Module 10 + 上传」的 context。  
+   - 若配置了 Weaviate，再调 `_retrieve_from_weaviate(message)`，把返回的课程检索文本**拼在**上面 context 后面，一起交给 LLM。
+
+---
+
+### 1.2 数据从哪来、存在哪
+
+| 来源 | 何时写入 | 存在哪 |
+|------|----------|--------|
+| Module 10 预读 | 进程启动时 | 全局 cache → 每会话 `rag_chunks` |
+| 用户上传文件 | Gradio 上传回调 | 追加到 `sess["rag_chunks"]` |
+| GENAI 课程文档 | 本地运行 `build_weaviate_index.py` | **Weaviate Cloud** collection `GenAICourses` |
+
+### 1.3 Chunk 长什么样（内存/FAISS 侧）
+
+会话级 `rag_chunks` 里每个元素是一个 dict，例如：
+
+```python
+{
+  "text": "一段正文...",
+  "source_file": "module10_responsible_ai.pdf",  # 或上传的文件名
+  "section": "pdf_unstructured#1",               # 段落/页码标识
+  "doc_type": "Literature Review / Paper",       # Syllabus / Lecture Slides / ...
+  "embedding": [0.1, -0.02, ...]                  # 维度由 rag_engine 所用 embedding 模型决定
+}
+```
+
+- **Embedding**：ClareVoice 的 `rag_engine` 里用 `clare_core.get_embedding()`（或同配置的 embedding）为每个 chunk 生成向量。
+- **解析**：PDF 优先 `unstructured.io`，失败则 pypdf；DOCX/PPTX 用 python-docx/pptx；按空行分段落再按约 1400 字符打包成 chunk。
+
+**Weaviate 侧**：由 LlamaIndex 写入的 document/node，带向量与元数据；检索时取 `node.get_content()` 拼成字符串，无单独 chunk dict 结构要求。
+
+### 1.4 检索流程（retrieve_relevant_chunks，仅内存/FAISS）
+
+1. **入参**  
+   - `query`：用户问题  
+   - `chunks`：当前会话的 `sess["rag_chunks"]`  
+   - 可选：`allowed_source_files`、`allowed_doc_types`（例如只查「刚上传的那份文件」）
+
+2. **先做范围过滤**  
+   - 若有 `allowed_source_files` / `allowed_doc_types`，只保留符合的 chunks，再参与后续步骤。
+
+3. **向量检索（默认开启）**  
+   - 用当前配置的 embedding 模型对 query 生成向量；  
+   - 用当前过滤后的 chunks 临时建一个 **VectorStore**（FAISS IndexFlatL2 或列表余弦）；  
+   - 取 top `k*2` 个候选（默认 k=4），再按 `vector_similarity_threshold`（默认 0.7）过滤。
+
+4. **Rerank**  
+   - 对候选做 **token 重叠**（query 与 chunk 的 token 交集）；  
+   - 综合分 = `0.7 * 向量相似度 + 0.3 * 归一化 token 重叠`，再取 top k。
+
+5. **无结果或分数过低**  
+   - 回退到**纯 token 重叠**检索（按词匹配，无向量）。
+
+6. **拼上下文**  
+   - 对最终 top chunks 做 token 截断（单 chunk 500、总 context 2000），拼成一段 `context_text` 返回给 LLM，同���返回 `used_chunks` 供前端展示引用。
+
+### 1.5 可选：GenAICoursesDB 回退
+
+- 若**未配置 Weaviate**，ClareVoice 用 `GENAI_COURSES_SPACE` 调用 GenAICoursesDB Space 的 `/retrieve` 接口，作为课程知识库的「远程 RAG」回退。
+
+### 1.6 小结（当前逻辑）
+
+- **Weaviate Cloud**：存 GENAI 课程知识库（`build_weaviate_index.py` 建索引，`_retrieve_from_weaviate` 检索）。
+- **内存 + FAISS**：会话级 `rag_chunks`（Module 10 预读 + 用户上传），`retrieve_relevant_chunks()` 检索。
+- **对话时**：先取 FAISS 的 context，再调 `_retrieve_from_weaviate` 把课程检索结果拼在后面，一起交给 LLM。
+- **多课程**：当前 Weaviate 单 collection（GenAICourses）；支持多门课时可在 Weaviate 内按 `course_id` 或分 collection 扩展（见下文）。
+
+---
+
+## 二、要支持多门课程，需要怎么做
+
+目标：**多门课程并存、按课程（或 workspace）隔离检索**，且不破坏现有单会话、单课程使用方式。  
+**ClareVoice 已有 Weaviate**，多课程可在此基础上扩展（多 collection 或单 collection + course_id 过滤）。
+
+### 2.1 数据模型上区分「课程」
+
+- 为 chunk / 文档增加**课程维度**，例如：
+  - `course_id`：对应 `course_directory` 里的一门课；
+  - 或 `workspace_id`：对应某个 workspace（若一个 workspace 绑定一门课）。
+- 会话侧增加「当前使用的课程/workspace」：
+  - 例如 `sess["course_id"]` 或 `sess["workspace_id"]`，由前端「选课/选 workspace」或默认规则设定。
+
+这样：  
+- **建索引时**：每个 chunk 带上 `course_id`（或 `workspace_id`）；  
+- **检索时**：只在该会话当前 `course_id`（或当前 workspace 绑定的课程）对应的数据里搜。
+
+### 2.2 两种实现路径
+
+**路径 A：内存 + 按课程分桶（仅会话级）**
+
+- 会话结构扩展为例如：`sess["rag_chunks_by_course"] = { "course_ai_001": [...], "course_ml_002": [...] }`。
+- 或保持 `sess["rag_chunks"]` 为「当前课程」的列表，在**切换课程**时从「课程级缓存」里加载对应列表。
+- **课程级 chunk 从哪来**：
+  - **方案 A1**：仍以「上传」为主——用户选一门课再上传，上传时带 `course_id`，写入 `rag_chunks_by_course[course_id]`。
+  - **方案 A2**：预置「课程资料」——每门课有预解析好的 chunk 列表，登录/选课后加载到会话或课程缓存。
+- **检索**：只对当前课程的 chunk 列表做现有 `retrieve_relevant_chunks()`，逻辑不变。
+
+**路径 B：Weaviate 扩展（推荐）**
+
+- ClareVoice 已用 **Weaviate Cloud** 存 GENAI 课程（单 collection `GenAICourses`）。多课程可：
+  - **方案 B1**：多 collection——每门课一个 collection，如 `GenAICourses`、`Course_ML_101`；`_retrieve_from_weaviate` 根据 `sess["course_id"]` 或配置选择 `index_name`。
+  - **方案 B2**：单 collection + 元数据过滤——在 Weaviate 的 class 上增加属性 `course_id`（或 `courseId`），建索引时写入；检索时用 Weaviate 的 **filter**（如 `where course_id == "course_ai_001"`）再做向量检索。
+- **写入**：  
+  - 预置课程：沿用或扩展 `build_weaviate_index.py`，按课程目录/配置写入，带 `course_id`；  
+  - 用户上传：解析 → embedding → 写入 Weaviate，并带上当前 `course_id`（需在 ClareVoice 中接 Weaviate 写接口）。
+- **检索**：  
+  - query embedding + **filter (course_id = 当前课程)**；  
+  - 再在应用层做 token rerank / 截断，拼 context。
+- **会话**：存 `user_id`、`course_id`；多门课共享同一 Weaviate 集群，靠 collection 或 filter 隔离。
+
+### 2.3 与 Gradio 前端配合
+
+- **选课/选 workspace**：  
+  - 若 UI 有选课或 workspace，在会话中维护 `sess["course_id"]` / `sess["workspace_id"]`，上传与检索时只作用当前课程。
+- **上传**：  
+  - 上传回调里从当前会话读 `course_id`（若有），写入 chunk 池或 Weaviate 时带课程维度。
+- **对话**：  
+  - 多课程下从「当前课程对应的 chunk 源」取数（内存分桶或 Weaviate filter），再调 `retrieve_relevant_chunks()` 或 `_retrieve_from_weaviate(..., course_id=...)`。
+
+### 2.4 小结：多课程支持要做的事
+
+| 项目 | 说明 |
+|------|------|
+| Chunk 增加 course_id（或 workspace_id） | 建索引/写入时必带；检索时按此过滤。 |
+| 会话增加当前课程 | `sess["course_id"]` 或 `sess["workspace_id"]`，由选课/选 workspace 设定。 |
+| 上传与选课绑定 | 上传时带 course_id，写入对应课程 chunk 池或向量库。 |
+| 检索只查当前课程 | 内存方案：只对当前课程的 chunk 列表检索；向量库方案：filter by course_id。 |
+| 可选：课程预置资料 | 每门课预解析+embedding，放入课程缓存或持久化向量库。 |
+
+---
+
+## 三、向量数据库的优化计划与想法
+
+在「写清当前逻辑」和「多课程支持」之上，可以���阶段做以下优化。
+
+### 3.1 短期（不引入新服务）
+
+- **按会话/按课程复用 FAISS 索引**  
+  - 当前是**每次** `retrieve_relevant_chunks` 都 `VectorStore()` + `build_index(chunks)`，重复建索引。  
+  - 改为：对同一份 `chunks`（按会话或按 course_id 的列表）**建一次索引并缓存**，只有 chunks 变化（如新上传）时再重建。这样检索延迟和 CPU 都会明显下降。
+
+- **Chunk 与 embedding 分离缓存**  
+  - 对「未改动的文件」缓存其 chunk 列表（或甚至只缓存 embedding），避免重复解析、重复调 OpenAI Embeddings；上传同一文件时可直接复用。
+
+- **检索参数可配置**  
+  - `top_k`、`vector_similarity_threshold`、`RAG_CONTEXT_TOKEN_LIMIT` 等放进 config 或 API，便于按课程/场景调优（如考试模式用更大 top_k）。
+
+- **多课程内存分桶**  
+  - 实现 2.1 / 2.2 路径 A：`rag_chunks_by_course` + 选课接口，先支持多门课隔离，为后续迁到向量库打基础。
+
+### 3.2 中期（扩展 Weaviate / 持久化向量库）
+
+- **ClareVoice 已接 Weaviate Cloud**；可在此基础上：  
+  - Schema 增加 `course_id`（及可选 `workspace_id`、`uploaded_at`）；  
+  - 多 collection 或单 collection + filter，实现多课程隔离；  
+  - 上传时写入 Weaviate（需在服务端接 Weaviate 写接口），预置课程继续用 `build_weaviate_index.py` 或同类脚本。
+
+- **统一检索接口**  
+  - 封装一层「RAG 检索」：内部根据配置选择「内存 FAISS」或「Weaviate」（及可选 GenAICoursesDB 回退）；对上层仍返回 `(context_text, used_chunks)`，便于后续扩展与多课程切换。
+
+- **课程级预建索引**  
+  - 每门课预解析 + 批量 embedding → 写入 Weaviate（按 course_id 或分 collection）；用户选课后直接查。
+
+### 3.3 中长期（效果与规模）
+
+- **混合检索（Hybrid）**  
+  - 向量检索 + 关键词（BM25/lexical）再融合（如 RRF），减少纯向量「语义漂移」或专有名词漏检。
+
+- **Rerank 模型**  
+  - 向量初筛后用小型的 cross-encoder 或 rerank API 精排，再截断进 context，提升引用准确度。
+
+- **分片与规模**  
+  - 按 `course_id` 分 collection 或分索引，便于按课程做备份、迁移、删除；单集合过大时再考虑按时间或按文档分片。
+
+- **可观测性**  
+  - 记录检索延迟、命中 chunk 数、分数分布；可选 A/B 不同 top_k 或阈值，便于调参。
+
+---
+
+## 四、总结表
+
+| 维度 | ClareVoice 当前 | 多课程（建议） | 优化方向 |
+|------|-----------------|----------------|----------|
+| 课程知识库 | **Weaviate Cloud**（GenAICourses） | 多 collection 或 course_id 过滤 | 多课程 schema、统一检索接口 |
+| 会话 RAG | 内存 rag_chunks + FAISS | 按 course_id 分桶或统一走 Weaviate | 索引复用、课程级预建 |
+| 检索 | Weaviate + FAISS 双路，结果拼接 | 先按 course_id 过滤再检索 | Hybrid、rerank、可调参 |
+| 数据来源 | Module10 预读 + 上传 + **Weaviate 课程** | + 课程预置资料、多课程上传 | 批量预置、可观测 |
+
+按上述步骤：先把「当前向量库逻辑」和「多课程支持」在设计与实现上对齐，再分阶段做「缓存/索引复用 → 扩展 Weaviate 多课程 → 混合检索与规模化」，即可在支持多门课的同时逐步优化 ClareVoice 向量数据库的表现与可维护性。

requirements.txt

@@ -23,4 +23,11 @@ gradio_client>=1.0.0
 faiss-cpu>=1.7.4
 unstructured[pdf]>=0.12.0
 # Optional dependencies for unstructured (if needed)
-# unstructured[local-inference]>=0.12.0  # Uncomment if using local models
+# unstructured[local-inference]>=0.12.0  # Uncomment if using local models
+
+# 教师 Agent + ClareVoice 共用 Weaviate（可选，需配置 WEAVIATE_URL / WEAVIATE_API_KEY）
+# weaviate-client>=4.0.0
+# llama-index-core>=0.10.0
+# llama-index-vector-stores-weaviate>=0.2.0
+# llama-index-embeddings-huggingface>=0.1.0
+# sentence-transformers>=2.2.0

web/src/App.tsx

@@ -11,6 +11,7 @@ import { Button } from "./components/ui/button";
 import { Toaster } from "./components/ui/sonner";
 import { toast } from "sonner";
 import { LeftSidebar } from "./components/sidebar/LeftSidebar";
+import { TeacherDashboard } from "./components/TeacherDashboard";
 
 // backend API bindings
 import { apiChat, apiUpload, apiMemoryline, apiQuizStart } from "./lib/api";
@@ -378,6 +379,7 @@ function App() {
 
   const [isTyping, setIsTyping] = useState(false);
   const [leftSidebarOpen, setLeftSidebarOpen] = useState(false);
+  const [showTeacherDashboard, setShowTeacherDashboard] = useState(false);
   const [leftPanelVisible, setLeftPanelVisible] = useState(true);
   const [showProfileEditor, setShowProfileEditor] = useState(false);
   const [showOnboarding, setShowOnboarding] = useState(false);
@@ -1361,6 +1363,9 @@ function App() {
               setShowReviewBanner(false);
               localStorage.setItem("reviewBannerDismissed", "true");
             }}
+            showTeacherView={showTeacherDashboard}
+            onShowTeacherDashboard={() => setShowTeacherDashboard(true)}
+            onBackFromTeacher={() => setShowTeacherDashboard(false)}
           />
         </div>
 
@@ -1483,6 +1488,9 @@ function App() {
 
           <main className="flex flex-1 min-w-0 min-h-0 overflow-hidden flex-col">
             <div className="flex-1 min-h-0 min-w-0 overflow-hidden">
+              {showTeacherDashboard ? (
+                <TeacherDashboard onBack={() => setShowTeacherDashboard(false)} />
+              ) : (
               <ChatArea
                 messages={messages}
                 onSendMessage={handleSendMessage}
@@ -1526,6 +1534,7 @@ function App() {
                 // ✅ bio is still allowed to be updated by chat/Clare
                 onProfileBioUpdate={(bio) => updateUser({ bio })}
               />
+              )}
             </div>
           </main>
         </div>

web/src/components/Header.tsx

@@ -52,6 +52,11 @@ interface HeaderProps {
   reviewStarOpacity?: number; // 0..1
   reviewEnergyPct?: number;   // 0..100
   onStarClick?: () => void;   // recommended: switch to Review
+
+  // ✅ 教师 Agent：AI 智能建课 入口
+  showTeacherView?: boolean;
+  onShowTeacherDashboard?: () => void;
+  onBackFromTeacher?: () => void;
 }
 
 export function Header({
@@ -72,6 +77,9 @@ export function Header({
   reviewStarOpacity,
   reviewEnergyPct,
   onStarClick,
+  showTeacherView,
+  onShowTeacherDashboard,
+  onBackFromTeacher,
 }: HeaderProps) {
   const [showProfileEditor, setShowProfileEditor] = useState(false);
 
@@ -191,6 +199,30 @@ export function Header({
           {isDarkMode ? <Sun className="h-5 w-5" /> : <Moon className="h-5 w-5" />}
         </Button>
 
+        {showTeacherView && onBackFromTeacher ? (
+          <TooltipProvider>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button variant="outline" size="sm" onClick={onBackFromTeacher} className="gap-1.5">
+                  返回学习
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent>返回 Clare 学习助手</TooltipContent>
+            </Tooltip>
+          </TooltipProvider>
+        ) : onShowTeacherDashboard ? (
+          <TooltipProvider>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button variant="outline" size="sm" onClick={onShowTeacherDashboard} className="gap-1.5">
+                  AI 智能建课
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent>教师：课程描述、文档建议、作业题库、学习评估</TooltipContent>
+            </Tooltip>
+          </TooltipProvider>
+        ) : null}
+
         {user && currentWorkspace ? (
           <>
             <DropdownMenu>

web/src/components/TeacherDashboard.tsx

@@ -0,0 +1,352 @@
+// web/src/components/TeacherDashboard.tsx
+// AI 智能建课：课程描述、文档建议、作业题库建议、学习评估分析
+import React, { useState, useEffect } from "react";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "./ui/card";
+import { Button } from "./ui/button";
+import { Input } from "./ui/input";
+import { Textarea } from "./ui/textarea";
+import { Label } from "./ui/label";
+import { ArrowLeft, Loader2, Lightbulb, FileText, ClipboardList, BarChart3 } from "lucide-react";
+import {
+  apiTeacherStatus,
+  apiTeacherCourseDescription,
+  apiTeacherDocSuggestion,
+  apiTeacherAssignmentQuestions,
+  apiTeacherAssessmentAnalysis,
+  type TeacherStatus,
+} from "../lib/api";
+import { toast } from "sonner";
+
+type FeatureId = "course-description" | "doc-suggestion" | "assignment-questions" | "assessment-analysis";
+
+const FEATURES: { id: FeatureId; title: string; desc: string; icon: React.ReactNode }[] = [
+  {
+    id: "course-description",
+    title: "课程描述生成",
+    desc: "根据课程主题生成可用于课程介绍或选课页的简洁描述",
+    icon: <FileText className="h-6 w-6" />,
+  },
+  {
+    id: "doc-suggestion",
+    title: "课程文档内容建议",
+    desc: "针对某一主题或现有文档片段，给出讲义/课件的内容与结构建议",
+    icon: <Lightbulb className="h-6 w-6" />,
+  },
+  {
+    id: "assignment-questions",
+    title: "作业和题库生成建议",
+    desc: "根据主题与周次，给出作业题、练习题或考试题建议与示例",
+    icon: <ClipboardList className="h-6 w-6" />,
+  },
+  {
+    id: "assessment-analysis",
+    title: "学生学习评估分析",
+    desc: "根据学生表现摘要，给出分析结论与教学改进建议",
+    icon: <BarChart3 className="h-6 w-6" />,
+  },
+];
+
+type Props = {
+  onBack: () => void;
+};
+
+export function TeacherDashboard({ onBack }: Props) {
+  const [status, setStatus] = useState<TeacherStatus | null>(null);
+  const [loading, setLoading] = useState<FeatureId | null>(null);
+  const [results, setResults] = useState<Record<FeatureId, string>>({
+    "course-description": "",
+    "doc-suggestion": "",
+    "assignment-questions": "",
+    "assessment-analysis": "",
+  });
+
+  const [topicDescription, setTopicDescription] = useState("");
+  const [outlineHint, setOutlineHint] = useState("");
+  const [topicDoc, setTopicDoc] = useState("");
+  const [docExcerpt, setDocExcerpt] = useState("");
+  const [docType, setDocType] = useState("讲义/课件");
+  const [topicAssignment, setTopicAssignment] = useState("");
+  const [weekOrModule, setWeekOrModule] = useState("");
+  const [questionType, setQuestionType] = useState("混合");
+  const [assessmentSummary, setAssessmentSummary] = useState("");
+  const [courseTopicHint, setCourseTopicHint] = useState("");
+
+  useEffect(() => {
+    apiTeacherStatus()
+      .then(setStatus)
+      .catch(() => setStatus({ weaviate_configured: false, features: [] }));
+  }, []);
+
+  const handleCourseDescription = async () => {
+    if (!topic.trim()) {
+      toast.error("请输入课程主题");
+      return;
+    }
+    setLoading("course-description");
+    setResults((r) => ({ ...r, "course-description": "" }));
+    try {
+      const res = await apiTeacherCourseDescription({
+        topic: topic.trim(),
+        outline_hint: outlineHint.trim() || undefined,
+      });
+      setResults((r) => ({ ...r, "course-description": res.description }));
+      if (res.weaviate_used) toast.success("已结合课程知识库生成");
+    } catch (e: any) {
+      toast.error(e?.message || "生成失败");
+    } finally {
+      setLoading(null);
+    }
+  };
+
+  const handleDocSuggestion = async () => {
+    if (!topicDoc.trim()) {
+      toast.error("请输入主题或章节");
+      return;
+    }
+    setLoading("doc-suggestion");
+    setResults((r) => ({ ...r, "doc-suggestion": "" }));
+    try {
+      const res = await apiTeacherDocSuggestion({
+        topic: topicDoc.trim(),
+        current_doc_excerpt: docExcerpt.trim() || undefined,
+        doc_type: docType.trim() || "讲义/课件",
+      });
+      setResults((r) => ({ ...r, "doc-suggestion": res.suggestion }));
+      if (res.weaviate_used) toast.success("已结合课程知识库");
+    } catch (e: any) {
+      toast.error(e?.message || "生成失败");
+    } finally {
+      setLoading(null);
+    }
+  };
+
+  const handleAssignmentQuestions = async () => {
+    if (!topicAssignment.trim()) {
+      toast.error("请输入主题");
+      return;
+    }
+    setLoading("assignment-questions");
+    setResults((r) => ({ ...r, "assignment-questions": "" }));
+    try {
+      const res = await apiTeacherAssignmentQuestions({
+        topic: topicAssignment.trim(),
+        week_or_module: weekOrModule.trim() || undefined,
+        question_type: questionType.trim() || "混合",
+      });
+      setResults((r) => ({ ...r, "assignment-questions": res.suggestion }));
+      if (res.weaviate_used) toast.success("已结合课程���识库");
+    } catch (e: any) {
+      toast.error(e?.message || "生成失败");
+    } finally {
+      setLoading(null);
+    }
+  };
+
+  const handleAssessmentAnalysis = async () => {
+    if (!assessmentSummary.trim()) {
+      toast.error("请输入学生评估摘要");
+      return;
+    }
+    setLoading("assessment-analysis");
+    setResults((r) => ({ ...r, "assessment-analysis": "" }));
+    try {
+      const res = await apiTeacherAssessmentAnalysis({
+        assessment_summary: assessmentSummary.trim(),
+        course_topic_hint: courseTopicHint.trim() || undefined,
+      });
+      setResults((r) => ({ ...r, "assessment-analysis": res.analysis }));
+      if (res.weaviate_used) toast.success("已结合课程知识库");
+    } catch (e: any) {
+      toast.error(e?.message || "分析失败");
+    } finally {
+      setLoading(null);
+    }
+  };
+
+  return (
+    <div className="h-full flex flex-col bg-background">
+      <div className="flex-shrink-0 flex items-center gap-4 px-4 py-3 border-b border-border">
+        <Button variant="ghost" size="icon" onClick={onBack} title="返回">
+          <ArrowLeft className="h-5 w-5" />
+        </Button>
+        <div>
+          <h1 className="text-lg font-semibold">AI 智能建课</h1>
+          <p className="text-sm text-muted-foreground">
+            基于 GENAI 课程知识库，辅助设计与改进课程
+            {status?.weaviate_configured && (
+              <span className="ml-2 text-green-600 dark:text-green-400">· 知识库已连接</span>
+            )}
+          </p>
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-auto p-4 md:p-6">
+        <div className="grid gap-6 md:grid-cols-2 max-w-5xl mx-auto">
+          {FEATURES.map((f) => (
+            <Card key={f.id} className="flex flex-col">
+              <CardHeader className="pb-2">
+                <div className="flex items-center gap-2">
+                  <span className="text-muted-foreground">{f.icon}</span>
+                  <CardTitle className="text-base">{f.title}</CardTitle>
+                </div>
+                <CardDescription>{f.desc}</CardDescription>
+              </CardHeader>
+              <CardContent className="flex-1 flex flex-col gap-3">
+                {f.id === "course-description" && (
+                  <>
+                    <div>
+                      <Label>课程主题 / 名称 *</Label>
+                      <Input
+                        placeholder="例如：检索增强生成 (RAG)"
+                        value={topicDescription}
+                        onChange={(e) => setTopicDescription(e.target.value)}
+                        className="mt-1"
+                      />
+                    </div>
+                    <div>
+                      <Label>大纲或要点（可选）</Label>
+                      <Textarea
+                        placeholder="可粘贴现有大纲要点"
+                        value={outlineHint}
+                        onChange={(e) => setOutlineHint(e.target.value)}
+                        rows={2}
+                        className="mt-1"
+                      />
+                    </div>
+                    <Button
+                      onClick={handleCourseDescription}
+                      disabled={loading === "course-description"}
+                    >
+                      {loading === "course-description" ? (
+                        <Loader2 className="h-4 w-4 animate-spin mr-2" />
+                      ) : null}
+                      开始使用
+                    </Button>
+                  </>
+                )}
+                {f.id === "doc-suggestion" && (
+                  <>
+                    <div>
+                      <Label>主题或章节 *</Label>
+                      <Input
+                        placeholder="例如：Prompt Engineering 核心原则"
+                        value={topicDoc}
+                        onChange={(e) => setTopicDoc(e.target.value)}
+                        className="mt-1"
+                      />
+                    </div>
+                    <div>
+                      <Label>当前已有内容片段（可选）</Label>
+                      <Textarea
+                        placeholder="可粘贴现有讲义片段"
+                        value={docExcerpt}
+                        onChange={(e) => setDocExcerpt(e.target.value)}
+                        rows={2}
+                        className="mt-1"
+                      />
+                    </div>
+                    <div>
+                      <Label>文档类型</Label>
+                      <Input
+                        value={docType}
+                        onChange={(e) => setDocType(e.target.value)}
+                        className="mt-1"
+                      />
+                    </div>
+                    <Button
+                      onClick={handleDocSuggestion}
+                      disabled={loading === "doc-suggestion"}
+                    >
+                      {loading === "doc-suggestion" ? (
+                        <Loader2 className="h-4 w-4 animate-spin mr-2" />
+                      ) : null}
+                      开始使用
+                    </Button>
+                  </>
+                )}
+                {f.id === "assignment-questions" && (
+                  <>
+                    <div>
+                      <Label>主题 *</Label>
+                      <Input
+                        placeholder="例如：RAG 与向量检索"
+                        value={topicAssignment}
+                        onChange={(e) => setTopicAssignment(e.target.value)}
+                        className="mt-1"
+                      />
+                    </div>
+                    <div>
+                      <Label>周次 / 模块（可选）</Label>
+                      <Input
+                        placeholder="例如：Week 7"
+                        value={weekOrModule}
+                        onChange={(e) => setWeekOrModule(e.target.value)}
+                        className="mt-1"
+                      />
+                    </div>
+                    <div>
+                      <Label>题型偏好</Label>
+                      <Input
+                        placeholder="选择题、简答题、开放题、混合"
+                        value={questionType}
+                        onChange={(e) => setQuestionType(e.target.value)}
+                        className="mt-1"
+                      />
+                    </div>
+                    <Button
+                      onClick={handleAssignmentQuestions}
+                      disabled={loading === "assignment-questions"}
+                    >
+                      {loading === "assignment-questions" ? (
+                        <Loader2 className="h-4 w-4 animate-spin mr-2" />
+                      ) : null}
+                      开始使用
+                    </Button>
+                  </>
+                )}
+                {f.id === "assessment-analysis" && (
+                  <>
+                    <div>
+                      <Label>学生评估摘要 *</Label>
+                      <Textarea
+                        placeholder="例如：本周作业得分分布、常见错误、参与度简述…"
+                        value={assessmentSummary}
+                        onChange={(e) => setAssessmentSummary(e.target.value)}
+                        rows={4}
+                        className="mt-1"
+                      />
+                    </div>
+                    <div>
+                      <Label>相关课程主题（可选）</Label>
+                      <Input
+                        placeholder="便于结合知识库分析"
+                        value={courseTopicHint}
+                        onChange={(e) => setCourseTopicHint(e.target.value)}
+                        className="mt-1"
+                      />
+                    </div>
+                    <Button
+                      onClick={handleAssessmentAnalysis}
+                      disabled={loading === "assessment-analysis"}
+                    >
+                      {loading === "assessment-analysis" ? (
+                        <Loader2 className="h-4 w-4 animate-spin mr-2" />
+                      ) : null}
+                      开始使用
+                    </Button>
+                  </>
+                )}
+
+                {results[f.id] && (
+                  <div className="mt-2 p-3 rounded-md bg-muted/60 text-sm whitespace-pre-wrap border border-border">
+                    {results[f.id]}
+                  </div>
+                )}
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

web/src/lib/api.ts

@@ -392,3 +392,99 @@ export async function apiPodcast(payload: {
   }
   return res.blob();
 }
+
+// --------------------
+// 教师 Agent API（AI 智能建课）
+// --------------------
+const TEACHER_TIMEOUT_MS = 90000;
+
+export type TeacherStatus = {
+  weaviate_configured: boolean;
+  features: string[];
+};
+
+export async function apiTeacherStatus(): Promise<TeacherStatus> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(`${base}/api/teacher/status`, {}, 10000);
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "Teacher status failed"));
+  return data as TeacherStatus;
+}
+
+export async function apiTeacherCourseDescription(payload: {
+  topic: string;
+  outline_hint?: string | null;
+}): Promise<{ description: string; weaviate_used: boolean }> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/api/teacher/course-description`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "Course description failed"));
+  return data as { description: string; weaviate_used: boolean };
+}
+
+export async function apiTeacherDocSuggestion(payload: {
+  topic: string;
+  current_doc_excerpt?: string | null;
+  doc_type?: string;
+}): Promise<{ suggestion: string; weaviate_used: boolean }> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/api/teacher/doc-suggestion`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "Doc suggestion failed"));
+  return data as { suggestion: string; weaviate_used: boolean };
+}
+
+export async function apiTeacherAssignmentQuestions(payload: {
+  topic: string;
+  week_or_module?: string | null;
+  question_type?: string;
+}): Promise<{ suggestion: string; weaviate_used: boolean }> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/api/teacher/assignment-questions`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "Assignment questions failed"));
+  return data as { suggestion: string; weaviate_used: boolean };
+}
+
+export async function apiTeacherAssessmentAnalysis(payload: {
+  assessment_summary: string;
+  course_topic_hint?: string | null;
+}): Promise<{ analysis: string; weaviate_used: boolean }> {
+  const base = getBaseUrl();
+  const res = await fetchWithTimeout(
+    `${base}/api/teacher/assessment-analysis`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    TEACHER_TIMEOUT_MS
+  );
+  const data = await parseJsonSafe(res);
+  if (!res.ok) throw new Error(errMsg(data, "Assessment analysis failed"));
+  return data as { analysis: string; weaviate_used: boolean };
+}