# eduAgent

**Repository Path**: hzcui/eduAgent

## Basic Information

- **Project Name**: eduAgent
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知解 Edu Agent

知解 Edu Agent 是一个面向教育场景的网页版智能体工作台。它从原来的微信小程序拍题链路演进而来，当前以 Web 产品为主形态，保留了原有的拍题精讲能力，并扩展出学科学伴、教学辅助、角色模拟等模块。

当前目标不是只做一个能调用模型的演示页，而是把 OCR、分步教学、教师工作流和校本知识约束收拢到同一个产品骨架里，便于后续继续补知识库、账号、历史记录和多角色工作台。

## 当前能力

### 1. 拍题精讲

上传题图后，后端会调用 PaddleOCR 提取题目文本，再通过 MiniMax 生成分步讲解与互动选项。前端会展示处理中状态、步骤进度、答案反馈与最终解析。

### 2. 学科学伴

围绕某个知识点进行持续对话，偏向启发式讲解、纠偏和追问，不直接退化成一次性问答框。

### 3. 教学辅助

教师输入学科、主题、目标和学情后，系统会调用智能体生成课堂流程、分层任务、形成性评价和课后建议。

### 4. 角色模拟

支持面试官、历史人物、口语考官等对话场景，适合课堂演练、表达训练与情境教学。

### 5. 校本知识上下文

Web 前端已提供知识库文本输入区，可将课程标准、教材节选、课堂规约或校本要求作为上下文注入智能体回答。

## 项目结构

```text
zhijie-edu-agent/
├── docs/
│   ├── local-dev-architecture.md
│   └── web-product-architecture.md
├── server/
│   ├── app.js
│   ├── config.js
│   ├── data/
│   ├── routes/
│   │   ├── agents.js
│   │   ├── knowledge-base.js
│   │   └── solve-sessions.js
│   ├── services/
│   │   ├── agent-service.js
│   │   ├── knowledge-base-service.js
│   │   ├── ocr-service.js
│   │   ├── provider-utils.js
│   │   └── tutor-service.js
│   └── stores/
├── src/
│   ├── App.jsx
│   ├── main.jsx
│   └── styles.css
├── index.html
├── vite.config.mjs
├── package.json
└── README.md
```

## 技术架构

### 前端

- React + Vite
- 单页产品工作台
- 通过 `/api/health`、`/api/agents/*`、`/api/solve-sessions/*` 与后端通信

### 后端

- Express
- `/api/solve-sessions` 负责拍题精讲主链路
- `/api/agents` 负责通用教育智能体能力
- 当存在 `dist/` 时，Express 会直接托管前端构建产物

### AI 能力

- OCR: PaddleOCR layout-parsing HTTP 服务
- Tutor / Agent: MiniMax Anthropic 兼容接口

## 安装前你需要准备什么

### 本地环境

- Node.js 18 或更高版本。项目服务端直接使用了 Node 内置 `fetch`。
- npm。默认使用 `package-lock.json` 安装依赖。
- 一台可访问外网的开发机器。如果你只跑 mock 模式，这一点不是必须。

### 用户必须提供的外部信息

如果你想跑真实链路而不是 mock 演示，需要用户自己提供下面这些信息：

1. `PADDLE_OCR_URL`：可访问的 PaddleOCR HTTP 接口地址。
2. `PADDLE_OCR_AUTH_TOKEN`：该 OCR 接口要求的 token。
3. `MINIMAX_API_KEY`：MiniMax API Key。

### 哪些情况下可以不提供密钥

如果只是本地安装、看界面、联调前后端、演示页面结构，可以不提供真实 OCR 和模型密钥，直接使用 mock：

- `OCR_PROVIDER=mock`
- `TUTOR_PROVIDER=mock`

这种模式下，后端仍能启动，前端也能正常访问；只是不会调用真实 OCR 与真实大模型。

## 快速启动

这个导出目录只保留当前 Web 版运行所需文件，不再包含旧的小程序源码、构建产物和本地调试素材。

### 1. 安装依赖

```bash
npm install
```

### 2. 创建环境变量文件

```bash
cp .env.example .env
```

Windows PowerShell 可改用：

```powershell
Copy-Item .env.example .env
```

### 3. 配置环境变量

按需填写 `.env`。推荐按下面两种模式二选一。

#### 模式 A：只验证安装和页面联调

`.env` 至少保持：

```env
OCR_PROVIDER=mock
TUTOR_PROVIDER=mock
```

这时不需要真实 OCR 地址和模型密钥。

#### 模式 B：跑真实 OCR + 真实智能体链路

`.env` 需要至少填好：

```env
OCR_PROVIDER=paddle
TUTOR_PROVIDER=minimax
PADDLE_OCR_URL=你的 OCR 服务地址
PADDLE_OCR_AUTH_TOKEN=你的 OCR Token
MINIMAX_API_KEY=你的 MiniMax Key
```

如果你的 OCR 服务或模型服务地址不是默认值，也应一并改掉相关 URL。更完整的变量说明见 [docs/local-dev-architecture.md](docs/local-dev-architecture.md)。

### 4. 启动后端

```bash
npm run dev:server
```

默认监听 `http://127.0.0.1:3000`。

你可以先访问下面这个地址确认服务是否就绪：

```text
http://127.0.0.1:3000/api/health
```

如果是 live 模式，返回里的 `liveConfig.paddleReady` 和 `liveConfig.minimaxReady` 应该为 `true`。

### 5. 启动前端开发环境

```bash
npm run dev:web
```

Vite 默认运行在 `http://127.0.0.1:5173`，并将 `/api` 代理到本地 Express。

浏览器打开后可直接访问：

```text
http://127.0.0.1:5173
```

### 6. 构建前端

```bash
npm run build:web
```

构建后会生成 `dist/`，可直接由 Express 托管。

### 7. 以接近生产的方式本地运行

```bash
npm run build:web
npm start
```

然后访问：

```text
http://127.0.0.1:3000
```

这时由 Express 直接托管 `dist/`。

## 常见启动判断标准

### 能说明安装成功的最低标准

1. `npm install` 没报错。
2. `npm run dev:server` 能启动成功。
3. 打开 `/api/health` 能返回 JSON。
4. `npm run dev:web` 能打开前端页面。

### 能说明真实链路成功的最低标准

1. `/api/health` 里 `paddleReady` 和 `minimaxReady` 都是 `true`。
2. 拍题精讲上传图片后，不再返回 mock 或保底结果。
3. 学科学伴、教学辅助等接口能返回真实模型响应。

## 常见问题

### 1. 后端能启动，但真实能力不可用

通常是 `.env` 中 provider 仍是 `mock`，或者虽然切到了 `paddle` / `minimax`，但缺少 URL、token、API key。

### 2. 前端改了但 3000 端口页面没变化

因为 `npm start` 或直接运行 Express 时，如果存在 `dist/`，后端会托管构建产物。修改 `src/` 后需要重新执行：

```bash
npm run build:web
```

### 3. 端口冲突

可以在 `.env` 中改 `PORT`，例如：

```env
PORT=3001
```

### 4. 上传图片时报大小错误

可在 `.env` 中调整：

```env
MAX_UPLOAD_SIZE_MB=8
```

## 一套最短可复制命令

### 只跑 mock 演示

```bash
npm install
cp .env.example .env
npm run dev:server
npm run dev:web
```

### 跑真实链路

```bash
npm install
cp .env.example .env
# 编辑 .env，填入 PaddleOCR 和 MiniMax 信息
npm run dev:server
npm run dev:web
```

## 已验证项

- `npm run build:web` 可成功构建
- `GET /api/health` 可返回 OCR / Tutor 就绪状态
- `GET /api/agents/catalog` 可返回当前智能体目录
- `POST /api/agents/respond` 可返回真实 MiniMax 响应
- Express 可在存在 `dist/` 时返回首页 HTML 与静态资源

## 文档索引

- [docs/web-product-architecture.md](docs/web-product-architecture.md): 当前 Web 产品形态、模块设计、接口与后续扩展重点
- [docs/local-dev-architecture.md](docs/local-dev-architecture.md): 原本地验证版架构、OCR / Tutor 接入方式与环境变量说明
- [docs/calculus-course-plan.md](docs/calculus-course-plan.md): 微积分课程第一批知识库条目、三端功能拆分与课程 MVP 建议
- [docs/calculus-knowledge-base.md](docs/calculus-knowledge-base.md): 可直接用于当前产品文本注入的微积分总知识库主文件
- [server/data/calculus-knowledge-base.json](server/data/calculus-knowledge-base.json): 后续接入产品时可直接读取的微积分结构化知识库
- [docs/calculus-knowledge-schema.md](docs/calculus-knowledge-schema.md): 微积分结构化知识库字段说明

## 当前阶段最值得继续补的东西

1. 知识库结构，不再只停留在一段自由文本输入。
2. 用户体系与会话历史，避免每次打开都从零开始。
3. 教师工作台能力，比如备课资产沉淀、模板复用与结果导出。
4. 更清晰的多角色产品边界，例如学生端、教师端、管理端。