# 05 · 课堂演示与自学指南

本文面向**教师讲课**和**学生自学**，提供推荐流程、演示话术与练习任务。

---

## 一、推荐课堂流程（约 30–40 分钟）

| 环节 | 时间 | 做什么 | 对应文档 |
|------|------|--------|----------|
| 导入 | 5 min | 提问：「AI 怎么知道今天深圳天气？」 | [01-ReAct概念讲解.md](./01-ReAct概念讲解.md) |
| 概念 | 8 min | 讲解 T→A→O→A，对照左侧概念面板 | 同上 |
| 工具 | 5 min | 介绍四个工具及官方链接 | [02-工具清单与官方链接.md](./02-工具清单与官方链接.md) |
| 演示 | 10 min | 计算题 + 天气题，开启对比模式 | 下文「演示脚本」 |
| 代码导览 | 8 min | 看 `react-loop.ts`、`tools.ts` | [03-开发思路与项目架构.md](./03-开发思路与项目架构.md) |
| 小结 | 4 min | 随堂检查 + 布置练习 | 下文「课后练习」 |

---

## 二、演示脚本（教师可参考）

### 演示 1：大数计算（对比最明显）

1. 启动项目，填入 API Key
2. 选择：「请计算 12345 × 6789 等于多少？」
3. 开启「对比模式」，点击「运行演示」
4. **指左侧**：无 Thought/Action/Observation，直接给答案，可能算错
5. **指右侧**：
   - 第 1 轮 Thought：为什么要调 calculate
   - Action：调用参数
   - Observation：`83810205`
   - Answer：引用真实结果
6. **强调**：ReAct 不是让模型更聪明，而是让它**敢用工具、会用工具、用结果说话**

### 演示 2：实时天气（幻觉对比）

1. 选择：「深圳现在的天气怎么样？」
2. 观察左侧可能「编造」温度/天气
3. 观察右侧调用 `get_weather`，数据来自 Open-Meteo
4. 打开 [02-工具清单与官方链接.md](./02-工具清单与官方链接.md) 给学生看原 API 链接

### 演示 3：纯知识题（不需要工具）

1. 选择：「用一句话解释什么是 ReAct？」
2. 右侧也应出现 Thought，但**无 Action**
3. 说明：不是什么问题都要调工具，模型会先判断

---

## 三、API Key 配置方式

### 方式 A：页面输入（适合课堂）

在右上角输入 `sk-xxx`，保存在浏览器 `sessionStorage`。

### 方式 B：环境变量（适合开发/自测）

**Windows PowerShell：**

```powershell
$env:DASHSCOPE_API_KEY = "sk-你的key"
npm run dev
```

**Windows 永久设置：** 系统属性 → 环境变量 → 新建 `DASHSCOPE_API_KEY`

**验证：**

```powershell
echo $env:DASHSCOPE_API_KEY.Length   # 应为 35 左右
node scripts/test-react.mjs
```

### 获取 Key

登录 [百炼控制台](https://bailian.console.aliyun.com/) 创建 API Key。

---

## 四、学生自学路径

```mermaid
flowchart LR
    A[读 01 概念] --> B[读 02 工具链接]
    B --> C[跑 npm run dev]
    C --> D[自己点三个示例题]
    D --> E[读 04 运行流程]
    E --> F[打开 src 对照代码]
    F --> G[做课后练习]
```

### 建议学习时间

| 阶段 | 时间 |
|------|------|
| 阅读文档 + 跑通 demo | 1 小时 |
| 对照源码理解 | 1–2 小时 |
| 完成练习 1–3 | 1 小时 |

---

## 五、课后练习

### 练习 1：观察记录（基础）

任选两道「需工具」示例题，填写表格：

| 项目 | 题 1 | 题 2 |
|------|------|------|
| 问题 | | |
| 调用了什么工具 | | |
| Observation 关键数据 | | |
| 普通模式是否可靠 | | |

### 练习 2：链接溯源（基础）

在 [02-工具清单与官方链接.md](./02-工具清单与官方链接.md) 中找到：

1. DashScope Function Calling 文档 URL
2. Open-Meteo 地理编码 API 的完整示例 URL
3. Frankfurter 汇率 API 文档 URL

### 练习 3：读代码（进阶）

阅读 `src/lib/react-loop.ts`，回答：

1. 循环最多几轮？在哪里定义？
2. 工具结果如何写回 `messages`？
3. `onStep` 在什么时候被调用？

### 练习 4：小改动（挑战）

1. 在 `questions.ts` 增加一题：「东京现在天气如何？」
2. 在 `TOOL_LABELS` 中为工具增加更中文的显示名
3. （可选）增加第五个工具，如「BMI 计算器」

---

## 六、评分参考（自查清单）

| 能力 | 达标标准 |
|------|----------|
| 概念 | 能口述 ReAct 四步及与普通对话的区别 |
| 工具 | 能说出四个工具用途及数据来源 |
| 流程 | 能画出一次完整 tool_calls 循环 |
| 实践 | 能本地跑通 demo 并完成一次对比演示 |
| 拓展 | 能指出模型何时不应调用工具 |

---

## 七、网络与环境注意事项

1. **关闭 VPN**：访问 `dashscope.aliyuncs.com` 时 VPN 可能导致 TLS 失败
2. **Node 版本**：建议 18 或以上
3. **端口占用**：5173 被占用时可改 `vite.config.ts` 的 `server.port`
4. **防火墙**：确保可访问 `dashscope.aliyuncs.com`、`open-meteo.com`、`frankfurter.app`

---

## 八、教师常见问题

**Q：学生问「Thought 是模型想的还是程序写的？」**

A：优先展示模型返回的推理内容；若模型未返回，程序会根据问题和工具类型**自动生成**教学用思考文案，保证链条完整可见。见 `thought.ts`。

**Q：为什么不用 Coze / Dify？**

A：本课重点是理解 ReAct 原理和 Function Calling 机制，手写循环更透明。

**Q：工具能不能换成自己的业务 API？**

A：可以。在 `tools.ts` 增加 `TOOL_DEFINITIONS` 条目和 `executeTool` 分支即可。

---

返回目录：[README.md](./README.md)