# ai-agent-teaching

**Repository Path**: sfidea/ai-agent-teaching

## Basic Information

- **Project Name**: ai-agent-teaching
- **Description**: 配套《AI智能体科普实践课》（五年级）课程大纲与教案的课堂互动系统。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI智能体互动教学系统（静态版）

**配套《AI智能体科普实践课》（五年级）课程大纲与教案的课堂互动系统。**
让学生通过玩游戏、做实验、和真正的 AI 对话，直观理解智能体四大组件：
**感知器、规划器、记忆器、执行器（工具）**，以及大语言模型"大脑"如何把它们协作起来。

> 🚀 **静态版特性**：纯 HTML/CSS/JS，**不需要服务器**，可直接部署到 GitHub Pages / Vercel / Netlify 等免费平台。
>
> 🔑 **API Key 由用户输入**：不硬编码 Key，首次使用时引导用户输入自己的 DeepSeek API Key，保存在浏览器 localStorage。
>
> 🔍 **联网搜索**：使用 Wikipedia + DuckDuckGo API（均支持 CORS 跨域，完全免费，无需 Key）。
>
> 外接 **DeepSeek 开放平台** 大模型（用户自行配置 API Key，在网页右上角"设置"里可随时更换）。
>
> 内容深度参考开源书 **《深入理解 AI Agent：设计原理与工程实践》（ai-agent-book）**：
> 首页给出核心公式 **Agent = LLM + 上下文 + 工具**，四个组件实验室各配"进阶原理卡"
> （多模态 / Token / ReAct / RAG / Function Calling / MCP / Harness），
> 智能体实验室可"拆开"查看真实发送给大模型的上下文请求。
> 五年级学生不是"被哄的小朋友"，而是真正的"小工程师"——知识要密、原理要真。

---

## 一、快速开始（三种方式）

### 方式一：直接打开（最简单）

双击 `index.html`，用 Chrome 或 Edge 浏览器打开即可使用。

> ⚠️ 注意：直接用 `file://` 协议打开时，部分浏览器可能限制 fetch API 跨域请求。如果 AI 对话或搜索功能异常，建议使用方式二或方式三。

### 方式二：本地静态服务器（推荐测试用）

需要 Python 3（仅用于启动静态文件服务器，不需要任何第三方包）：

```bash
# 进入项目目录
cd AI智能体互动教学系统_静态版

# 启动静态文件服务器（端口 8124）
python -m http.server 8124

# 浏览器访问
# 打开 http://localhost:8124
```

### 方式三：部署到免费平台（推荐正式使用）

见下方「部署指南」章节，可部署到 GitHub Pages / Vercel / Netlify，完全免费，随时随地访问。

---

## 二、首次使用：配置 API Key

1. 打开页面后，会自动弹出「欢迎使用」引导窗口
2. 按照提示，到 [DeepSeek 开放平台](https://platform.deepseek.com/) 注册并创建 API Key
3. 将 Key（`sk-` 开头）粘贴到输入框，点击「保存并开始使用」
4. 如果暂时没有 Key，可以点击「稍后再说」，知识讲解、游戏、小测验等功能**不需要 Key** 也能使用
5. 之后可随时点击右上角齿轮「设置」按钮修改 API Key 或切换模型

> 🔒 **安全说明**：你的 API Key 只保存在**本机浏览器**（localStorage），不会上传到任何服务器。浏览器直接调用 DeepSeek 官方 API，不经过任何中间服务器。

---

## 三、部署指南

### 部署到 GitHub Pages（免费，推荐）

1. 注册 [GitHub](https://github.com/) 账号
2. 创建一个新仓库（Repository），名字比如 `agent-teaching`
3. 将本项目所有文件上传到仓库（可以直接网页拖拽上传，或用 Git）
4. 进入仓库 **Settings** → **Pages**
5. Source 选择 `Deploy from a branch`，Branch 选 `main` / `root`，点击 Save
6. 等待 1-2 分钟，就能通过 `https://你的用户名.github.io/agent-teaching/` 访问了！

### 部署到 Vercel（免费，国内访问较快）

1. 注册 [Vercel](https://vercel.com/) 账号（可用 GitHub 登录）
2. 点击「Add New...」→「Project」
3. 导入你的 GitHub 仓库，或直接上传项目文件夹
4. Framework Preset 选「Other」，Build Command 留空，Output Directory 留空（或填 `.`）
5. 点击「Deploy」，等待部署完成
6. 会得到一个 `https://xxx.vercel.app` 的网址，随时随地访问

### 部署到 Netlify（免费）

1. 注册 [Netlify](https://www.netlify.com/) 账号
2. 点击「Add new site」→「Deploy manually」
3. 将项目文件夹拖拽到上传区域
4. 等待部署完成，得到 `https://xxx.netlify.app` 网址

### 部署到 Gitee Pages（国内访问快，需要实名认证）

1. 注册 [Gitee](https://gitee.com/) 账号并完成实名认证
2. 创建新仓库，上传项目文件
3. 进入仓库「服务」→「Gitee Pages」
4. 选择分支，点击「启动」
5. 得到 `https://你的用户名.gitee.io/仓库名/` 网址

---

## 四、系统里有哪几个"实验室"

| 页面 | 对应课程 | 学生能做什么 |
| --- | --- | --- |
| **起源实验室** | L01 AI起源与初识 + L02 身边的智能体 | 17 个模块：**L01（9个）**——情境导入（小明的一天）；AI发展史时间轴（13节点：1950图灵测试→1956达特茅斯→专家系统→AI冬天→2012深度学习→2016 AlphaGo→2017 Transformer→2020 GPT-3→2022 ChatGPT→2024 Sora/DeepSeek→2025-2026智能体普及）；AI三大支柱（数据/算法/算力）；**大模型工作原理（六步精简流程+完整演示+Transformer论文原图+8部分逐图解读）**；**图灵测试体验站（4场景判断+AI特征总结+中文房间思辨+强AI/弱AI）**；聊天机器人vs智能体对比表；**AI时代职业演变（四类各8个职业共32个：已消失/正在消失/正在兴起/未来，每个职业配相关图标，卡片高度统一）**；AI伦理小讨论；深度思考（人类该如何面对AI：陶哲轩/自动驾驶/AI绘画/AI编程四案例+AI替代不了的6种能力+5条应对策略）。**L02（8个）**——6大领域智能体案例；AI产品全景（6大类26款产品）；AI四代进化（L1-L4）；推荐算法原理（协同过滤+三人五电影评分演示）；信息茧房与隐私保护；智能体能力圈游戏；**终极思辨（AI有意识吗：6部科幻电影+5位名人预言+3个科学现实分析）**；小测验（8题，含Transformer核心机制/AI最难替代的能力等） |
| **架构实验室（总装图）** | L03 智能体总装图 + L04 拆解一个真实智能体 | 13 个模块：学习目标；情境导入（小机器人买早餐四样本领）；核心公式 Agent = 大脑 + 眼睛 + 手脚（ai-agent-book）；人体类比与智能体总装图（对照表+可点击总装图）；**Model-Harness 结构（科学口径：Model 决策+Harness 治理）**；**总装图拼装互动（点击组件到正确位置）**；组件抢答游戏（10 生活场景题，常驻"重新开始"按钮）；**拆解四问与组件定位表（L04 核心方法）**；**教师示范拆解智能客服（逐环节暂停动画+组件定位表）**；**真实案例拆解库（5 案例：智能客服/出行助手/智能家居/腾讯CodeBuddy/搜索 Agent，每个含四大组件定位+ai-agent-book 依据，CodeBuddy单独深度拆解）**；**五种 Agent 产品对比表（ai-agent-book chapter1: Cursor/Deep Research/Browser Use/豆包手机助手/Pine AI）**；小测验（10 题，架构小达人）；进阶原理卡（10 概念）+课堂小结 |
| **感知器实验室** | L05 / L06 | 13 个模块：认识感知器；模态连连看（文字/语音/图像）；现场感知转化演示（语音+文字）；**OCR 图片文字识别（真实 Tesseract 引擎，支持中文，上传图片即识别）**；模糊 vs 清晰提示词对比实验；观察空间 vs 动作空间；消息四角色分类（system/user/assistant/tool）；Token 化演示（文字→Token→数字向量）；多模态感知三路径（原生/提取文本/工具化）+ **Token 消耗实时对比计算器（图片/音频/PDF 三场景，柱状图+成本估算）**；感知失败与纠错（ASR/OCR/上下文窗口）；提示注入安全；小测验；进阶原理卡（8 个真实工程概念） |
| **规划器实验室** | L07 / L08 | 13 个模块：认识规划器（拆解+排序+执行三法宝）；步骤排排队游戏（7 个任务含 AI Agent 真实任务）；**ReAct 循环可视化（思考→行动→观察三轮动画，自动播放）**；魔法句式 vs 模糊说法对比；现场规划（大任务→小步骤）；**Plan-and-Execute vs ReAct 两种规划范式选择题**；**思维链（CoT）实验（直接问 vs 一步一步想对比）**；**工具选择决策互动（6 场景选工具）**；**提议者-审核者双 Agent 模式（生成计划→独立审核→改进建议）**；**规划失败与反思（3 个真实失败案例选应对策略）**；**上下文轨迹演示（5 轮对话轨迹增长+token 统计+上下文窗口警告）**；小测验（8 题）；进阶原理卡（10 个概念） |
| **记忆器实验室** | L09 / L10 | 13 个模块：学习目标；认识记忆器+记忆层次结构（轨迹/用户长期记忆/业务状态，ai-agent-book chapter3:72）；短期记忆实验（关掉对话就忘）；**记忆三层次评估（基础回忆/多会话检索/主动服务，ai-agent-book chapter3:55）**；**四种存储格式对比（Simple Notes/Enhanced Notes/JSON Cards/Advanced JSON Cards，ai-agent-book chapter3:88）**；班级知识库（长期记忆 RAG）；**RAG 检索增强生成演示（检索→注入→生成三步流程图）**；**认知科学三种长期记忆（情景/语义/程序与 Agent 对应，ai-agent-book chapter3:170）**；说明书（知道/不知道/怎么说）；**隐私与记忆边界（什么该记/不该记+生产系统四道防线：加密存储/访问授权/自动脱敏/被遗忘权）**；判断游戏（8 题含三层次和消歧场景）；小测验（10 题）；进阶原理卡（10 概念）+课堂小结 |
| **执行器实验室** | L11 / L12 | 13 个模块：学习目标；认识执行器（AI 的手）；**工具五分类（感知/执行/协作/事件触发/用户沟通，ai-agent-book chapter4:7，13 工具分类标注）**；有工具 vs 没工具对比实验（真实大模型）；**Function Calling 机制演示（用户提问→AI 输出 JSON 指令→程序执行工具→结果返回模型，四步流程图+JSON 示例）**；**工具描述与选择（工具描述三要素：功能/参数/返回值）**；连线游戏（13 任务→13 工具）；**MCP 协议（工具的 USB 接口，ai-agent-book chapter4:100，Client-Server 架构图+5 类 Server）**；工具百宝箱（开关 13 种工具）；**工具幻觉与约束（危险场景+三道防线：白名单/参数校验/结果验证）**；**多工具协作（链式调用：天气→搜索→计算→提醒，ReAct 循环中的工具链）**；小测验（10 题）；进阶原理卡（10 概念）+课堂小结 |
| **智能体实验室** | L13 综合实战 | 和真正的智能体（外接 DeepSeek）聊天，右侧"内部工作台"实时点亮：感知→规划→记忆→执行→生成（Agent 循环）；可"拆开看看"这一轮真实发给大脑的上下文；可现场关掉某个组件，观察智能体本领的变化；进阶原理卡（Agent 公式 / Harness / 评估 / 多智能体） |

所有"需要连接大模型"的实验都接入了 DeepSeek；知识点讲解、游戏和小测验不需要联网也能用。

---

## 三、课堂建议的使用顺序

1. **先看起源实验室**（L01+L02）：从 AI 发展史和大模型原理入手，玩图灵测试体验站、看职业演变四阶段、讨论 AI 伦理和人类该如何面对 AI；再认识身边的智能体（6大领域/产品全景/四代进化），理解推荐算法和信息茧房，最后思考"AI 有意识吗"。
2. **再看架构实验室**（L03+L04）：整体认识四组件与大脑，玩总装图拼装（点击式）、组件抢答；再用"拆解四问"分析智能客服示范，切换 5 个真实案例库（含腾讯CodeBuddy深度拆解），看五种 Agent 产品对比。
3. **依次进四个实验室**（L05–L12）：玩一个组件，点一个组件，攒知识。
4. **最后进智能体实验室**（L13）：学生提问，全班盯着"工作台"看五步点亮；点"拆开看看"观察真实上下文；可以现场关掉"记忆器"或"执行器"，让学生自己发现"少了它就不行"。
5. 可以结合教案里的**"卡住三步走"**课堂常规：先自己读并复述、再清晰提问、最后求助老师/同伴。

---

## 四、智能体的"工具库"（执行器）

| 工具 | 怎么触发 | 说明 |
| --- | --- | --- |
| 天气查询 | "明天会下雨吗？" | 按城市+日期生成稳定模拟数据（教学演示，可换真实天气 API） |
| 计算器 | "帮我算 25×4+10" | 支持中文算式（乘/加/减/除） |
| 提醒 | "提醒我明天带美术工具" | 记录一条提醒 |
| 课表查询 | "今天下午有什么课？" | 查班级知识库 |
| **联网搜索** | "搜一下：长颈鹿的脖子为什么那么长" | 必应搜索 RSS（通过 allorigins CORS 代理，国内稳定可用）+ Wikipedia 备用；内置课堂安全词过滤 |
| **翻译** | "科学用英语怎么说" | 中英互译（调用大模型，只输出译文） |
| **单位换算** | "3千米等于多少米" / "35摄氏度等于多少华氏度" | 确定性工具（纯代码计算，100% 精确），支持中文数字（一米/一千米） |
| **时间日期** | "现在几点了？" / "三天后是几号？" / "下周五是几号？" | 读真实系统时钟；支持推算（明天/后天/N天后/下周几） |
| **图形计算** | "边长4厘米的正方形面积是多少？" / "半径3的圆周长是多少？" | 确定性工具：正方形/长方形/三角形/平行四边形/梯形/圆/长方体/正方体 的面积、周长、体积，回答带公式 |
| **数学计算** | "60的30%是多少？" / "200元打8折" / "平均分是多少？" | 确定性工具：百分数、折扣、平均数 |
| **计时器** | "帮我计时25分钟（番茄钟）" / "倒计时10秒" / "10秒后提醒我写作业" | 真实倒计时：对话框内显示倒计时条，到点蜂鸣 + 自动提醒（支持番茄工作法）；计时器意图检测优先于提醒工具，确保稳定触发 |
| **猜数字游戏** | "我们来玩猜数字游戏吧！" → "我猜50" | 智能体想 1~100 的整数，学生猜，工具反馈"大了/小了"并缩小范围，教二分法 |
| **成语接龙** | "成语接龙，开始！" → 接成语 / "提示" / "不玩了" | 内置 220+ 成语库带释义：**轮流接龙**——智能体出题，学生接一个，智能体再接一个；**同音/谐音模式**——首字与上一成语末字读音相同即可接（含约 60 组同音字表，覆盖前后鼻音），接错纠正、不会给提示、智能体接不上则学生赢 |
| **单位换算（扩充）** | "1公顷等于多少平方米" / "72千米每小时等于多少米每秒" | 除长度/重量/体积/时间/温度外，新增面积（平方千米/公顷/平方米…）与速度（千米每小时/米每秒…） |

每个工具都可在"执行器实验室·工具百宝箱"单独开关，关闭后去智能体实验室提问即可观察"少了它就不行"。

---

## 五、老师可以配置什么

- **API Key / 模型**：网页右上角齿轮按钮 → 设置。默认模型 `deepseek-v4-flash`（快，适合课堂），可切换 `deepseek-v4-pro`（更强、稍慢）。
- **班级知识库 / 说明书**：在"记忆器实验室"里直接编辑保存，存在本机浏览器（localStorage），重启不丢。
- **工具开关**：在"执行器实验室·工具百宝箱"里开关，会直接影响智能体实验室的行为。

---

## 六、项目结构

```
AI智能体互动教学系统_静态版/
├── index.html            # 主页面
├── css/style.css         # 样式
├── images/               # 图片资源（Transformer架构图等）
├── js/
│   ├── config.js         # 模型配置、班级知识库默认值、天气演示数据、系统提示词（API Key 不硬编码）
│   ├── store.js          # 记忆器数据存取（localStorage）+ 通用 get/set
│   ├── api.js            # DeepSeek 直连（浏览器直接调用官方 API）+ 必应搜索 RSS（CORS代理）联网搜索
│   ├── agent.js          # 智能体核心：感知→规划→记忆→执行→生成 管线（ReAct 循环）
│   ├── ui.js             # 界面小工具（打字机、70+图标、提示等）
│   ├── lab-origin.js     # 起源实验室（L01+L02，17个模块）
│   ├── lab-home.js       # 架构实验室/总装图（L03+L04，含 Agent 核心公式）
│   ├── lab-perception.js # 感知器实验室（含进阶原理卡）
│   ├── lab-planner.js    # 规划器实验室（含进阶原理卡）
│   ├── lab-memory.js     # 记忆器实验室（含进阶原理卡）
│   ├── lab-executor.js   # 执行器实验室（含进阶原理卡）
│   ├── lab-playground.js # 智能体实验室（实时对话 + 管线点亮 + 上下文透视）
│   └── main.js           # 入口 + 首次使用 API Key 引导
└── README.md             # 本说明
```

## 七、说明与安全提示

- **API Key 由用户输入**：静态版不硬编码 API Key，首次使用时引导用户输入自己的 DeepSeek API Key，保存在**本机浏览器**（localStorage）。浏览器直接调用 DeepSeek 官方 API（`api.deepseek.com`），不经过任何中间服务器。
- **Key 安全建议**：由于 Key 存储在浏览器中，建议只在信任的设备上使用；给 DeepSeek 账户设置消费上限；定期更换 Key。不要把包含他人 Key 的浏览器配置对外公开。
- **天气工具是"演示数据"**：由程序按"城市+日期"生成稳定模拟值（教学演示用，不代表真实天气预报），便于课堂随时可演示；如需接入真实天气 API，可在 `js/config.js` / `js/agent.js` 中替换。
- **联网搜索依赖网络**：使用必应搜索 RSS（通过 allorigins CORS 代理，国内稳定可用）+ Wikipedia API（备用），完全免费，无需额外密钥。若课堂网络断网或无法访问这些站点，搜索工具会如实提示"搜索服务暂时不可用"，不影响其他功能。系统内置了课堂安全词过滤（暴力、色情等话题直接拒绝搜索）。
- **计时器是真实倒计时**：调用后对话框内会出现倒计时条，到点蜂鸣并自动提醒（需要浏览器允许声音）。刷新页面后倒计时会重置。计时器意图检测优先于提醒工具，确保"10秒后提醒我写作业"等指令稳定触发。
- **猜数字 / 成语接龙的状态在本次会话内保持**：刷新页面或点"新对话"会重置游戏。
- **课堂隐私规则**：系统内置了"不告诉 AI 家庭住址/电话"的提醒（对应 L10 隐私课），上课时请一并强调。
- **网络故障时**：知识讲解、游戏、小测验均可离线使用；只有"连接大模型"的实验需要联网。若 DeepSeek 无响应，请检查网络或 API Key 余额。
- **"API 密钥无效"提示**：若看到此提示，请点击右上角齿轮「设置」按钮，检查 DeepSeek API Key 是否正确（注意别有多余空格）。可到 [DeepSeek 开放平台](https://platform.deepseek.com/) 确认 Key 状态和账户余额。

祝课堂顺利，四样本领一起转起来！