leomuf/foxquiz
GitHub: leomuf/foxquiz
一款基于 Google ADK 与 Gemini 驱动的 AI 测验生成 Web 应用，帮助中小学生在安全、互动的环境中高效备考。
Stars: 0 | Forks: 0
# 🦊 FoxQuiz：动态交互式备考伴侣
🌐 **立即在线体验：** [https://foxquiz.app](https://foxquiz.app)
## 🎯 项目概述
FoxQuiz 是一款智能、极具吸引力且对儿童安全的备考应用程序，旨在帮助 5-12 年级的孩子在充满趣味和本地化的环境中掌握学术主题。FoxQuiz 由 **Google ADK 2.0** 和 **Gemini 2.5 Flash** 驱动，具备动态吉祥物教学法（狐狸 Felix、猫头鹰 Olivia、恐龙 Dino）、智能课程检查、学术同行评审节点以及最先进的安全防护机制，以保障学生的安全。
## 🎥 项目演示与解说
了解我们为什么要开发 FoxQuiz，观看完整的功能演示，并探索技术深入剖析：
📺 **在 YouTube 上观看演示：** [FoxQuiz 解说视频](https://youtu.be/5zt7EqS9uvg)
## 项目结构
```
foxquiz/
├── app/ # Core agent code
│ ├── agent.py # Main agent logic
│ └── app_utils/ # App utilities and helpers
├── tests/ # Unit, integration, and load tests
├── AGENTS.md # AI-assisted development guide
└── pyproject.toml # Project dependencies
```
## 环境要求
在开始之前，请确保您具备以下条件：
- **uv**：Python 包管理器（用于本项目中的所有依赖管理）- [安装](https://docs.astral.sh/uv/getting-started/installation/)（使用 `uv add ` [添加包](https://docs.astral.sh/uv/concepts/dependencies/)）
- **agents-cli**：Agents CLI - 使用 `uv tool install google-agents-cli` 安装
- **Google Cloud SDK**：用于 GCP 服务 - [安装](https://cloud.google.com/sdk/docs/install)
## 快速开始
如果尚未安装 `agents-cli` 及其技能，请先安装：
```
uvx google-agents-cli setup
```
安装所需的包：
```
agents-cli install
```
使用本地 Web 服务器测试 Agent：
```
agents-cli playground
```
你也可以通过 `uv run adk` 使用 [ADK](https://adk.dev/) CLI 中的功能。
## 🖥️ 运行和重启应用程序
### 1. 如何启动应用程序
要启动 FoxQuiz 本地 playground 或 Web 服务器，你可以使用标准化的 Agent CLI，或者直接启动 FastAPI 应用程序：
* **选项 A（标准 Agent CLI）：**
agents-cli playground
* **选项 B（直接使用 FastAPI/Uvicorn 命令）：**
uv run uvicorn app.fast_api_app:app --reload --host 127.0.0.1 --port 8000
启动后，打开浏览器并访问 `http://127.0.0.1:8000` 即可与 FoxQuiz 互动！
### 🔄 如何重启应用程序（全新会话和日志）
如果你需要清除当前活动会话或重置服务器输出以获取全新的控制台日志，请按照以下步骤操作：
1. **终止在端口 8000 上运行的服务器进程：**
* 在 **Linux / WSL** 上（即时清理端口）：
kill $(lsof -t -i:8000)
*（替代方案：`fuser -k 8000/tcp`）*
* **手动查找进程**：
ps aux | grep -E "uvicorn|fast_api_app"
kill
2. **启动全新的服务器会话：**
只需再次运行启动命令：
agents-cli playground
# 或者
uv run uvicorn app.fast_api_app:app --reload --host 127.0.0.1 --port 8000
## 命令
| 命令 | 描述 |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `agents-cli install` | 使用 uv 安装依赖 |
| `agents-cli playground` | 启动本地开发环境 |
| `agents-cli lint` | 运行代码质量检查 |
| `agents-cli eval` | 评估 Agent 行为（生成、评分、分析等 — 请参阅 `agents-cli eval --help`） |
| `uv run pytest tests/unit tests/integration` | 运行单元测试和集成测试 |
## 🛠️ 项目管理
| 命令 | 功能说明 |
|---------|--------------|
| `agents-cli scaffold enhance` | 添加 CI/CD 流水线和 Terraform 基础设施 |
| `agents-cli infra cicd` | 一键设置整个 CI/CD 流水线 + 基础设施 |
| `agents-cli scaffold upgrade` | 自动升级到最新版本，同时保留自定义配置 |
## 🏛️ 高并发与可扩展性架构
FoxQuiz 从底层设计之初就支持高并发、多用户并行访问。该技术栈可以无缝扩展，以适应数千名同时在线的学生：
### 1. 客户端表现的独立性
* **状态隔离：** 每个用户完全在自己的 Web 浏览器中运行自己的单页应用（HTML/CSS/JS）副本。所有的测验逻辑、计时器、动画和吉祥物状态都在客户端机器上本地运行，从而实现并行访问者之间的零交叉或资源争用。
### 2. 异步 FastAPI 与会话隔离
* **非阻塞异步 IO：** 后端由运行在 **Uvicorn** 上的 **FastAPI** 提供支持，以异步方式处理传入的 HTTP 请求。
* **隔离会话：** 在 ADK 2.0 下，每个用户会话都会被分配一个唯一的匿名 `session_id` 和 `user_id`（在浏览器中作为 UUID 生成）。Agent 编排器为每个会话运行独立、完全隔离的测验生成工作流图实例，防止数据串扰。
### 3. Serverless 云数据库 (Google Cloud Firestore)
持久层依赖于 **Cloud Firestore (Native Mode)**，这是 Google 为全球级并发构建的无服务器文档存储：
* **弹性扩展：** 与传统关系型数据库（会达到连接池限制）不同，Firestore 会自动扩展以处理数以万计的同时读写操作。
* **原子满意度计数器（无竞态条件）：** 对于**聚合的点赞计数器**，使用了 Firestore 原生的**原子递增**。如果 100 名用户完成测验并在同一毫秒点击“点赞”，Firestore 保证它们都能被准确计数，不会出现事务死锁或更新丢失的情况。
* **独立文档：** 写入点踩评论日志和保存冻结的测验会使用随机 UUID 创建唯一的文档，从而允许并行创建以最高的云端速度执行。
## 🔗 零 Token 冻结测验分享
FoxQuiz 包含一项互动社交功能，允许学生冻结并与朋友、父母或老师分享他们生成的测验：
* **即时发送给接收者：** 当用户点击 **“分享”** 时，前端会“冻结”当前的 10 道题测验状态，并将其作为静态文档保存在 Google Cloud Firestore 的 `quizzes/{quiz_id}` 路径下。
* **零 Token 成本：** 当接收者访问生成的分享链接时，我们的 FastAPI 后端 (`/quiz/{quiz_id}`) 会提供静态 SPA 布局，并直接加载冻结的 JSON 数据。**这不会触发任何 LLM 模型调用，也不会消耗任何 Vertex AI token**，从而实现了即时分享和无限的可扩展性。
* **无服务器 TTL 保留：** 为了限制云存储开销并严格遵守针对未成年人的 GDPR/LGPD 数据最小化准则，每个分享的测验在写入时都会带有 `expires_at` 时间戳。Firestore 原生的生存时间 (TTL) 策略会在创建后 **30 天**自动删除分享的测验。
* **本地离线导出：** 学生还可以点击 **“另存为 HTML”**，将完整的测验以样式精美、独立的 HTML 文件下载到本地，该文件无需任何云依赖即可离线使用。
## 🛡️ 安全检查点与公开仓库准备
为了使 FoxQuiz 能够作为**公开的 GitHub 仓库**安全发布，而不暴露敏感的防御规则或安全系统指令，它实现了一个动态的无服务器配置系统：
* **动态配置：** Prompt 注入关键词、管理命令正则表达式、防御性分类 prompt 以及本地化的阻止响应都私密地存储在 Google Cloud Firestore 的 `system_config/security` 文档中。
* **无代码暴露：** 防御性正则表达式和系统级指令永远不会提交到 Git，从而防止攻击者逆向工程出防护机制的漏洞。
* **多阶段拦截：** `BeforeAgentCallback` 拦截所有传入的用户 prompt。它执行快速的关键词和正则表达式匹配，拦截管理命令覆盖（例如删除日志或修改系统配置的请求），并使用私有的 prompt 配置运行 LLM 分类器。
* **记录的安全事件：** 恶意注入尝试或管理绕过命令会被立即阻止，并安全地记录到私有的 `security_events` Firestore 集合中以供审计。
### 🤠 自动化治安官守卫（零 Token 自动封禁）
为了防止恶意行为者或自动化机器人通过不断违反安全规则来耗尽我们的 Vertex AI token 预算，我们实现了一个代号为 **The Sheriff Guard（治安官守卫）** 的自动化防御子系统：
1. **安全的客户端指纹识别：** 对于每个请求，我们提取客户端的 IP 地址，并使用存储在 Firestore 中的密钥生成单向安全哈希 (`hashed_ip = SHA-256(IP + salt)`)。由于原始 IP 地址属于 GDPR/LGPD 规定的个人数据，该指纹识别器为未成年人提供了零 PII（个人身份信息）的安全性，同时能够唯一识别屡次违规的垃圾信息发送者。
2. **零 Token 快速拦截：** 传入的请求会与快速、本地内存中的活动封禁列表（具有 5 分钟的 TTL）进行匹配。如果匹配到被封禁的签名，请求会在入口处立即被短路拦截，**恰好消耗 0 个 LLM token**，从而保护系统预算。
3. **法槌（三振出局触发器）：** 如果用户违反了安全规则，该事件将连同其哈希签名记录到 `security_events` 中。治安官会检查他们最近的日志：如果某个签名在任何 1 小时的窗口内累积了 **3 次或更多次安全违规**，他们将自动被封禁 24 小时。该封禁记录会被写入 Firestore 的 `banned_signatures` 集合，并立即在本地活动封禁缓存中更新。
## 开发
在 `app/agent.py` 中编辑你的 Agent 逻辑，并使用 `agents-cli playground` 进行测试 - 它会在保存时自动重新加载。
## 部署
```
gcloud config set project
agents-cli deploy
```
要添加 CI/CD 和 Terraform，请运行 `agents-cli scaffold enhance`。
要设置你的生产基础设施，请运行 `agents-cli infra cicd`。
## 可观测性
内置的遥测功能可导出到 Cloud Trace、BigQuery 和 Cloud Logging。
## 💖 支持本项目，让教育保持免费！
FoxQuiz 是一项 **100% 免费、开源且无广告**的教育倡议，旨在让全球儿童都能获得高质量、安全且个性化的备考体验。
为了让这个平台能够免费向世界各地的学生和学校开放，我们依靠社区的捐款来支付活跃的 LLM API 成本。**所有经济捐助的 100% 都将直接用于资助使用 FoxQuiz 的孩子们的 Google Gemini API 教育 token。**
* **通过 PayPal 直接支持我们：** [PayPal.me/Muffato](https://paypal.me/Muffato)
* **在 GitHub 上赞助我们：** 点击我们仓库顶部的 **Sponsor**（赞助）心形按钮！
*每一份力量都很重要。感谢您赋能下一代学生！* 🎓🦊✨
标签：AI测验, Cloud Run, Google ADK, 后端开发, 教育软件, 逆向工具, 青少年教育