# ai-ti

**Repository Path**: blackfox/ai-ti

## Basic Information

- **Project Name**: ai-ti
- **Description**: 城建智能体大赛参赛项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI TI - 高职高数解题辅导系统

一个前后端分离的高数辅导项目：前端提供学生解题、教师看板、错题本、学情预警 UI；后端对接腾讯智能体 API，提供普通与流式解题接口，以及错题与学情相关接口。

## 1. 项目架构

### 1.1 目录结构

```text
ai_ti/
├── frontend/                 # Vue 3 + Vite 前端
│   ├── src/
│   │   ├── App.vue           # 主页面（学生/教师/错题/预警）
│   │   ├── main.js           # 前端入口
│   │   ├── style.css         # Tailwind 入口样式
│   │   └── components/
│   │       └── MarkitdownRenderer.vue  # Markdown 渲染组件
│   ├── vite.config.js        # 本地开发端口与 /ai 代理配置
│   └── package.json
└── backend/
    ├── main.py               # FastAPI 服务与业务接口
    ├── start.sh              # 后端启动脚本（含健康检查）
    ├── .env.example          # 环境变量示例
    └── .env                  # 本地环境变量（请勿提交密钥）
```

### 1.2 运行架构

```mermaid
flowchart LR
    A[Browser<br/>http://127.0.0.1:3001] --> B[Vite Dev Server]
    B -->|/ai proxy| C[FastAPI<br/>http://127.0.0.1:8000]
    C --> D[Tencent Agent API<br/>BASE_URL + APP_KEY]
    C --> E[In-memory data<br/>study_record / error_questions]
```

### 1.3 核心交互链路（学生解题）

1. 前端调用 `POST /ai/solve/stream`（流式）。
2. 后端转发请求到腾讯智能体 API（SSE）。
3. 后端把增量文本转为标准 SSE 事件返回前端（`delta/done/error`）。
4. 前端逐段渲染答案，提升交互流畅度。

## 2. 技术栈

- 前端：`Vue 3`、`Vite`、`Tailwind CSS`、`markdown-it`
- 后端：`FastAPI`、`Uvicorn`、`requests`、`Pydantic`
- 接口协议：HTTP + SSE（流式返回）

## 3. 启动前准备

### 3.1 环境要求

- Node.js 18+（建议）
- pnpm（前端当前使用 `pnpm-lock.yaml`）
- Python 3.10+（建议）

### 3.2 配置后端环境变量

在 `backend` 目录创建 `.env`（可直接复制 `.env.example`）：

```bash
cp backend/.env.example backend/.env
```

至少需要配置：

- `APP_KEY`：腾讯智能体应用密钥
- `BASE_URL`：腾讯智能体接口地址（默认示例已给出）

也支持别名变量（优先级更高）：

- `TENCENT_BOT_APP_KEY`
- `TENCENT_BOT_BASE_URL`

## 4. 如何启动

建议开两个终端：一个跑后端，一个跑前端。

### 4.1 启动后端（端口 8000）

在项目根目录执行：

```bash
pip install fastapi uvicorn requests pydantic
bash backend/start.sh
```

启动后可访问：

- 健康检查：`http://127.0.0.1:8000/`
- Swagger：`http://127.0.0.1:8000/docs`

### 4.2 启动前端（端口 3001）

在项目根目录执行：

```bash
cd frontend
npm install
npm run dev
```

打开：

- `http://127.0.0.1:3001`

> 前端 `vite.config.js` 已配置代理：`/ai -> http://127.0.0.1:8000`，本地开发无需额外处理跨域。

## 5. 主要接口一览

- `POST /ai/solve`：非流式解题
- `POST /ai/solve/stream`：流式解题（推荐，前端当前使用）
- `POST /error/add`：新增错题
- `GET /error/list`：查询错题
- `POST /error/clear`：清空错题
- `GET /teacher/overall-data`：教师学情总览
- `GET /warning/analysis`：学情预警分析
- `GET /`：服务健康检查

## 6. 常见问题

### 6.1 前端提示请求失败 / 无流式内容

优先检查：

1. 后端是否启动成功（访问 `http://127.0.0.1:8000/`）。
2. `backend/.env` 是否配置了正确 `APP_KEY`。
3. `BASE_URL` 是否可用且与腾讯控制台配置一致。

### 6.2 端口冲突

- 前端默认端口：`3001`（见 `frontend/vite.config.js`）
- 后端默认端口：`8000`（见 `backend/start.sh`）

可通过修改对应配置或设置环境变量 `PORT`（后端）解决。

## 7. 开发建议

- 不要把真实密钥提交到仓库（`backend/.env` 应仅本地使用）。
- 当前错题与学情数据是内存存储，重启服务会丢失，生产化建议接数据库。
- 若要上线，建议把前后端启动改为 `docker-compose` 或统一进程管理（如 systemd / pm2）。