# 03 · 开发思路与项目架构

本文说明：**为什么这样设计**、**代码怎么分层**、**关键设计决策**。

---

## 学习目标

1. 理解本项目的教学目标与技术选型
2. 能根据目录找到对应源码
3. 理解「思考步骤补全」等健壮性设计

---

## 1. 教学目标（先定目标，再写代码）

| 目标 | 页面/代码如何支撑 |
|------|-------------------|
| 让学生理解 ReAct 概念 | 左侧 `ConceptPanel` 概念面板 |
| 对比「无工具 vs 有工具」 | `ComparePanel` 左右并列 |
| 看见完整推理链 | `ReActChain` 按轮展示 T→A→O→A |
| 工具效果真实可验证 | 接入 Open-Meteo、Frankfurter 等公开 API |
| 课堂只需 DashScope | 模型统一走百炼 `qwen-plus` |

设计原则：**能看得见、能对比、能复现**。

---

## 2. 技术选型

| 层次 | 选择 | 原因 |
|------|------|------|
| 前端框架 | React 18 + TypeScript | 组件化清晰，适合教学演示 UI |
| 构建工具 | Vite 5 | 启动快，内置 dev 代理 |
| 大模型 | DashScope `qwen-plus` | 课程统一要求；支持 Function Calling |
| API 格式 | OpenAI 兼容模式 | `fetch` 即可调用，无需额外 SDK |
| 工具数据 | 公开免费 API | 学生无需再申请天气/汇率 Key |

---

## 3. 项目目录结构

```
06_代码/Day_02/react-demo/
├── docs/                    # 学生学习文档（本目录）
├── scripts/
│   ├── test-tools.mjs       # 工具 API 自测
│   └── test-react.mjs       # ReAct 完整链路自测
├── src/
│   ├── App.tsx              # 主界面：输入、运行、状态管理
│   ├── main.tsx             # React 入口
│   ├── types/index.ts       # 类型定义（Step、Round、Message）
│   ├── data/questions.ts    # 预设示例问题
│   ├── lib/
│   │   ├── dashscope.ts     # 大模型 API 封装（普通模式 + 底层请求）
│   │   ├── react-loop.ts    # ReAct 主循环（核心逻辑）
│   │   ├── thought.ts       # 思考文案生成（健壮性关键）
│   │   ├── rounds.ts        # 步骤分组为「轮次」
│   │   └── tools.ts         # 工具定义 + 真实执行
│   ├── components/
│   │   ├── ConceptPanel.tsx # 概念讲解
│   │   ├── ComparePanel.tsx # 左右对比容器
│   │   ├── ReActChain.tsx   # ReAct 推理链 UI
│   │   └── PlainChain.tsx   # 普通模式流程 UI
│   └── styles/index.css     # 样式
├── vite.config.ts           # 开发代理配置
├── package.json
└── README.md
```

---

## 4. 分层架构图

```mermaid
flowchart TB
    subgraph UI层
        App[App.tsx]
        Compare[ComparePanel]
        ReactUI[ReActChain]
        PlainUI[PlainChain]
    end

    subgraph 业务层
        Loop[react-loop.ts<br/>ReAct 循环]
        Plain[dashscope.ts<br/>plainChat]
        Thought[thought.ts<br/>思考补全]
        Rounds[rounds.ts<br/>轮次分组]
    end

    subgraph 工具层
        Tools[tools.ts<br/>executeTool]
    end

    subgraph 外部服务
        DS[DashScope qwen-plus]
        OM[Open-Meteo]
        FK[Frankfurter]
        Local[本地时间/计算]
    end

    App --> Compare
    Compare --> ReactUI
    Compare --> PlainUI
    App --> Loop
    App --> Plain
    Loop --> Thought
    Loop --> Rounds
    Loop --> Tools
    Loop --> DS
    Plain --> DS
    Tools --> OM
    Tools --> FK
    Tools --> Local
```

---

## 5. 核心模块职责

### 5.1 `dashscope.ts` — 大模型网关

- 封装 `chatCompletion()`：统一发请求、解析错误
- `plainChat()`：普通模式，**不传 tools**
- 开发环境请求走 `/api/dashscope/...`，由 Vite 代理到阿里云

### 5.2 `react-loop.ts` — ReAct 心脏

伪代码逻辑：

```
while 轮次 < 6:
    回复 = 调用模型(messages, tools)
    if 回复没有 tool_calls:
        生成最终 Thought + Answer
        结束
    else:
        生成 Thought（调用前）
        记录 Action（工具名 + 参数）
        执行工具 → 得到 Observation
        把 tool 结果追加到 messages
        继续下一轮
```

### 5.3 `thought.ts` — 为什么需要它？

**问题**：DashScope 在 Function Calling 时，经常**不返回**可见的思考文字（`content` 为空）。

**后果**：页面上只能看到 Action → Observation，学生看不到 Thought。

**解决**：`resolveThought()` 三层策略：

1. 优先用模型返回的 `reasoning_content` 或正文
2. 否则根据「问题 + 工具类型」**自动生成结构化思考文案**
3. 最终回答前再生成「综合 Observation 的思考」

这样课堂上**链条始终完整**。

### 5.4 `tools.ts` — 工具双职责

每个工具包含两部分：

| 部分 | 作用 | 谁使用 |
|------|------|--------|
| `TOOL_DEFINITIONS` | JSON Schema 描述 | 发给大模型，供其选择调用 |
| `executeTool()` | 真正执行逻辑 | 浏览器/脚本在收到 tool_calls 后执行 |

### 5.5 UI 组件分工

| 组件 | 职责 |
|------|------|
| `ReActChain` | 按「第 N 轮」展示 Thought → Action → Observation → Answer |
| `PlainChain` | 展示普通模式「跳过循环、直接输出」 |
| `ComparePanel` | 顶部 VS 摘要 + 左右对比 + 教学提示条 |

---

## 6. 关键设计决策记录

### 决策 1：对比模式默认开启

学生第一眼就能看到「无工具」和「ReAct」的差异，降低讲解成本。

### 决策 2：工具在浏览器端执行

- 模型只负责「决定调什么、传什么参数」
- 真实 HTTP 请求由 `executeTool()` 在浏览器发起
- 天气/汇率 API 支持 CORS，可直接访问

### 决策 3：最多 6 轮推理

防止模型反复调用工具导致死循环或费用失控（`MAX_LOOPS = 6`）。

### 决策 4：API Key 存 sessionStorage

- 方便课堂演示（不用每次输入）
- 关闭标签页即清除
- 不上传到任何自建服务器

### 决策 5：思考步骤可合成

教学演示优先「链条可见」，在模型沉默时由程序补全文案，并标注为「第 N 轮思考」。

---

## 7. 数据流（从用户点击到界面更新）

```mermaid
sequenceDiagram
    participant U as 用户
    participant App as App.tsx
    participant Loop as react-loop
    participant DS as DashScope
    participant Tool as executeTool
    participant UI as ReActChain

    U->>App: 点击「运行演示」
    App->>Loop: runReAct(key, question, onStep)
    Loop->>UI: onStep(input)
    Loop->>DS: chatCompletion + tools
    DS-->>Loop: tool_calls
    Loop->>UI: onStep(thought, action)
    Loop->>Tool: executeTool(name, args)
    Tool-->>Loop: observation 文本
    Loop->>UI: onStep(observation)
    Loop->>DS: messages + tool 结果
    DS-->>Loop: 最终 content
    Loop->>UI: onStep(thought, answer)
    Loop-->>App: RunResult
```

---

## 8. 随堂检查

1. `TOOL_DEFINITIONS` 和 `executeTool` 分别做什么？
2. 为什么单独拆出 `thought.ts`？
3. Vite 代理解决了什么问题？

<details>
<summary>参考答案</summary>

1. 前者描述工具给模型看；后者真正执行工具逻辑。
2. 模型调用工具时常不输出思考文字，需要程序补全以保证教学可见性。
3. 浏览器直接请求 DashScope 会有 CORS 跨域限制，代理转发可绕过。

</details>

---

下一篇：[04-运行流程详解.md](./04-运行流程详解.md)