# ReAct 大模型演示项目

教学用 React 项目，演示 **ReAct（Reasoning + Acting）** 模式：大模型如何通过「思考 → 调用工具 → 观察结果」解决需要实时数据的问题。

- **模型接口**：阿里云百炼 DashScope（`qwen-plus`，OpenAI 兼容模式）
- **对比演示**：普通对话（无工具）vs ReAct（Function Calling）
- **真实工具**：时间查询、数学计算、天气（Open-Meteo）、汇率（Frankfurter）

## 学生学习文档（推荐阅读）

完整讲义、工具原链接、开发思路、运行流程见：

**[docs/README.md](./docs/README.md)**

| 文档 | 内容 |
|------|------|
| [01-ReAct概念讲解](./docs/01-ReAct概念讲解.md) | 什么是 ReAct |
| [06-工具选型与使用说明](./docs/06-工具选型与使用说明.md) | **工具是否真实、怎么选的、怎么用** |
| [02-工具清单与官方链接](./docs/02-工具清单与官方链接.md) | 工具 API 原链接与技术细节 |
| [03-开发思路与项目架构](./docs/03-开发思路与项目架构.md) | **为什么这样开发、代码结构** |
| [04-运行流程详解](./docs/04-运行流程详解.md) | **从启动到出结果的完整流程** |
| [05-课堂演示与自学指南](./docs/05-课堂演示与自学指南.md) | 讲课/练习/排错 |

## 快速开始

### 1. 安装依赖

```bash
cd 06_代码/Day_02/react-demo
npm install
```

### 2. 启动开发服务器

```bash
npm run dev
```

浏览器打开 http://localhost:5173

### 3. 配置 API Key

任选其一：

- 在页面右上角输入 **DashScope API Key**（`sk-xxx`）
- 或设置系统环境变量 `DASHSCOPE_API_KEY`

> 页面输入的 Key 仅保存在浏览器 `sessionStorage`，关闭标签页后清除。

API Key 获取：[阿里云百炼控制台](https://bailian.console.aliyun.com/)

## 自测脚本

```bash
npm run dev                   # 必须先启动（工具 API 走本地代理）

node scripts/test-tools-proxy.mjs  # 测天气/汇率代理（推荐）
node scripts/test-tools.mjs        # 直连外部 API
node scripts/test-react.mjs        # 测完整 ReAct（需 DASHSCOPE_API_KEY）
```

> **注意**：天气、汇率工具在浏览器中通过 `/api/frankfurter`、`/api/open-meteo` 等**本地代理**访问，直接打开 `dist/index.html` 或绕过 Vite 会导致 `Failed to fetch`。

## 项目结构

```
src/
├── lib/
│   ├── dashscope.ts   # DashScope API 封装
│   ├── react-loop.ts  # ReAct 推理循环
│   ├── thought.ts     # 思考步骤补全
│   ├── rounds.ts      # 轮次分组
│   └── tools.ts       # 工具定义与真实执行逻辑
├── components/        # UI 组件
├── data/questions.ts  # 预设示例问题
└── App.tsx            # 主界面
```

## 构建部署

```bash
npm run build
npm run preview
```

生产部署时需配置反向代理，将 `/api/dashscope` 转发到 `https://dashscope.aliyuncs.com`。