内容
# 🎓 三重奏智能代理
**三重奏**是一款高级的教育AI助手，基于Google Agents SDK构建。它通过动态诊断知识空白、检查输入的安全性、通过MCP检索增强生成（RAG）矢量存储检索参考资料，并生成结构化的7天学习计划，为学生量身定制个性化、多轮的学习路径。该系统结合两个不同的人机协作（HITL）检查点——一个用于安全审核，另一个用于家长/教师学习计划审批——确保教育材料的安全性、相关性和与教学要求的完全一致性。
## 🎥 视频演示
[](https://youtu.be/YrWtIcUnS5M)
## 🏗️ 架构和代理层次
代理工作流被结构化为有向图节点，协调不同的子代理和验证规则。下面是显示执行路径的ASCII架构图：
```
+----------------------------------------+
| 学生输入 |
+----------------------------------------+
|
v
+-------------------------+
| 解析输入 |
+-------------------------+
|
v
+-------------------------+
| 安全检查点 | <--- Presidio PII 净化
+-------------------------+
/ \
[安全] [升级]
/ \
v v
+------------------+ +-----------------------+
| 测试代理 | <---------> | 安全审核 | (HITL 检查点 1)
+------------------+ [安全] +-----------------------+
|
v (评分测试 / 子主题)
+------------------+
| 弱点跟踪器 |
+------------------+
|
v (查找子主题弱点)
+----------------------+
| 学习计划生成器 | <--- 使用 FastMCP 索引文档接地
+----------------------+
|
v
+-----------------------+
| 学习计划审批 | (HITL 检查点 2: 家长/教师审核)
+-----------------------+
/ | \
[批准] [修订] [拒绝]
/ | \
v | v
+------------+ | +------------+
| 交付 | | | 拒绝 |
+------------+ | +------------+
v
(带有修订备注)
|
+-----> 回归到学习计划生成器
```
---
## 📋 前置条件
在设置项目之前，请确保已安装以下内容：
* **Python 3.13+**：核心执行运行时。
* **Node.js 18+**：运行前端 SPA 学生界面所需。
* **uv**：现代、高性能的 Python 包管理器（强烈推荐）。
* **Google Cloud SDK (gcloud)**：用于云服务（如果部署到 GCP）。
* **Groq API 密钥**：来自 Groq 控制台的有效 API 密钥。
---
## 🚀 快速入门
按照以下步骤克隆、配置并启动本地游乐场和教师仪表盘：
### 1. 克隆仓库
```bash
git clone <repository_url> capstone-study-coach
cd capstone-study-coach/trifecta-agent
```
### 2. 安装依赖
设置虚拟环境并安装 Python 后端包和 Node.js 前端包：
```bash
# 安装 Python 包和 CLI 实用程序
pip install -e ".[dev]"
# 下载 PDF 导出生成所需的字体
python scripts/download_fonts.py
# 安装前端 UI 依赖
cd frontend && npm install
cd ..
```
### 3. 配置环境
在 `trifecta-agent` 根目录中创建一个 `.env` 文件，基于示例：
```bash
copy .env.example .env
```
打开 `.env` 并配置您的 API 密钥和端口偏好：
```env
GROQ_API_KEY=gsk_YourActualAPIKeyHere
ADK_BASE_URL=http://127.0.0.1:8001
ALLOW_ORIGINS=*
```
### 4. 启动系统
在单独的终端中运行预定义的命令（或使用提供的 `start.ps1` 脚本在 Windows 上）：
* **后端代理服务器（ADK）**：
```bash
# 在 http://127.0.0.1:8001 启动集成 ADK 服务器和 MCP 端点
uvicorn trifecta_agent.fast_api_app:app --port 8001
```
* **教师/审核仪表盘（FastAPI）**：
```bash
# 在 http://127.0.0.1:8080 启动 Uvicorn API 服务器和玻璃态 SPA
make dashboard
```
* **学生 UI（Vite + React）**：
```bash
# 在 http://localhost:7860 启动 Vite 开发服务器
make student-ui
```
---
## 🤖 子代理和 HITL 工作流
个人三重奏采用模块化子代理来划分责任，并结合交互式检查点进行安全性和质量控制：
### 子代理
1. **安全检查点（PII 消除和注入防御）**：使用 Microsoft Presidio Analyzer 和 Anonymizer 引擎清除姓名、电话号码、SSN、电子邮件地址和学生 ID。同时检查输入中的提示注入攻击模式。
2. **交互式测试代理**：触发逐轮多选题测试流程。它通过 FastMCP 查询文档索引以确定生成的问题，并请求 Groq（Llama 3）根据学生选择的难度构建恰好 5 个问题。
3. **弱点跟踪器代理**：确定性、基于规则的 Python 分析器。它聚合历史测试响应，按子主题分组，标记任何低于 `WEAKNESS_THRESHOLD`（默认值：`60%`）的子主题，并分配优先级类别（`高`、`中`、`低`）。
4. **学习计划生成器代理**：提示 Groq（Llama 3）模型使用结构化 JSON 格式合成结构化的 7 天日程。它优先考虑已识别的高优先级弱点主题，集成 FastMCP 学习资源，并讲述激励性介绍。
### 人机协作（HITL）检查点
1. **安全升级（检查点 1）**：如果 `security_checkpoint` 检测到潜在的提示注入关键词，工作流将暂停，引发 `security_escalation` 中断。人类审核员必须在教师仪表盘上审核输入，以标记其 **安全**（匿名并恢复测试）或 **恶意**（引发值错误并终止会话）。
2. **学习计划审批（检查点 2）**：在向学生交付 7 天学习计划之前，工作流将暂停，创建 `study_plan_approval` 中断。教师或家长在仪表盘上审核计划，并可以选择：
- **批准**：直接向学生 UI 交付学习计划。
- **修订**：提交修订备注（例如“添加更多算法练习”），这会将执行路由回 `study_plan_generator` 以重建计划。
- **拒绝**：取消学习计划并通知学生。
---
## 📄 吸收材料和教师控制台导航
为了确定测试问题和学习计划，并管理学生体验，请执行以下步骤：
### 📊 教师控制台功能
教师管理控制台位于 `http://127.0.0.1:8080`，提供五个主要选项卡：
1. **概览和图表**：实时 KPI 摘要（活跃会话、待审阅、平均准确率和索引块）和 Chart.js 图表，映射子主题熟练度和时间线活动。
2. **学生会话**：活跃会话注册。教师可以点击任何会话 ID 来检查深入的学生资料，显示 PII 审核日志、逐题测试答案和生成的计划时间表。
3. **审核队列**：合并中心，用于解决 HITL 提示，显示所提出的学习计划的视觉日历预览网格。
4. **MCP 知识库**：拖放文档上传配对索引浏览器，搜索和预览 RAG 块。
5. **代理设置**：动态调整阈值（例如弱点阈值、测试长度、模型）。
### 1. 吸收学习材料
1. 在 `http://127.0.0.1:8080` 打开 **教师控制台** 并切换到 **MCP 知识库** 选项卡。
2. 在上传区域拖放或浏览选择 PDF、TXT 或 Markdown 文档。
3. 点击 **上传到 MCP 矢量存储**。文件转发到 FastMCP 服务器，分割成重叠块，并索引到本地 `index.json` 矢量文件中。您可以在实时检查器中搜索索引块。
### 2. 进行测试会话
1. 在 `http://localhost:7860` 打开 **学生 UI** （或在游乐场运行 CLI 会话）。
2. 通过输入主题和难度（例如“Python 循环 Hard”）开始会话。
3. 测试代理将搜索 MCP 索引以获取循环，构建 5 个问题，并逐一呈现。
4. 回答每个问题。代理提供即时反馈。
5. 在最后一个问题后，**弱点跟踪器** 打印报告，**学习计划生成器** 起草计划。
6. UI 将暂停并显示“等待家长/教师审批...”。
7. 进入仪表盘，点击 **审核**，插入可选指令，并点击 **批准计划** 或 **请求修订**。
8. 学生 UI 立即更新批准的计划。
9. **导出**：学生可以点击下载 PDF 按钮，接收带有漂亮品牌、离线可用的 ReportLab A4 PDF 学习时间表。
---
## 📊 运行评估
评估循环衡量自定义数据集上的响应质量和图性能。
### 配置
评估指标在 `tests/eval/eval_config.yaml` 中定义。套件使用自定义 LLM-as-a-Judge 指标 (`custom_response_quality`) 在 1（差）至 5（优秀）的范围内评估代理响应，并使用程序化指标 (`agent_turn_count`) 跟踪对话长度。
### 运行评估
使用 `agents-cli` 可执行文件生成对话跟踪并运行评估指标：
```bash
# 步骤 1：合成测试数据集（可选）
agents-cli eval dataset synthesize --count 10
# 步骤 2：使用测试输入生成跟踪
agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json --output eval_traces/
# 步骤 3：使用配置的指标评估跟踪
agents-cli eval grade --config tests/eval/eval_config.yaml --traces eval_traces/ --output grade_results.json
```
运行回归比较或聚类失败：
```bash
# 将候选跟踪与基线进行比较
agents-cli eval compare baseline_grades.json grade_results.json
# 聚类和分析失败模式
agents-cli eval analyze grade_results.json
```
---
## 🏆 Kaggle 提交说明：Agents for Good（教育赛道）
在将此代理提交给 **Kaggle Agents for Good — 教育赛道** 时，请查看以下结构配置：
1. **API 密钥加载**：代理设计为自包含运行。它从环境中读取 `GROQ_API_KEY`。确保在笔记本执行或 Kaggle 机密设置期间注入此密钥。
2. **离线执行和本地吸收**：
* MCP 文档矢量存储使用 `mcp_server/server.py` 内的轻量级、自包含的数学 TF-IDF 引擎。
* 它依赖于本地 JSON 文件 (`index.json`) 进行持久化，消除外部数据库依赖。
* 如果提交到离线环境，请确保 `index.json` 被打包到 zip 包中，以便预吸收的教学大纲材料可读。
3. **容器约束**：FastAPI 服务器和 MCP 服务器在内部作为_stdio 进程运行。对于提交笔记本执行：
* 将依赖项打包到单个 `requirements.txt` 或配置笔记本使用轮式文件离线安装 `pip install -e .`。
* 不要将 uvicorn 作为阻塞进程运行；直接使用 `Runner` 脚本或 `agents-cli` 工具运行代理。
---
## 📄 许可证
该项目根据 Apache License, Version 2.0 许可。参见 [LICENSE](LICENSE) 文件或访问 [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) 以获取更多详细信息。
```
Copyright 2026 Google LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```
