256 lines
8.0 KiB
Markdown
256 lines
8.0 KiB
Markdown
# 教育智能体 HTML 发布服务
|
||
|
||
这个服务用于接收智能体生成的知识点讲解 HTML，将内容保存为服务器上的唯一随机文件名，并返回可直接访问的链接。
|
||
|
||
当前主实现为 FastAPI，接口地址默认前缀为 `/api`。生成后的 HTML 文件默认存放在 `backend/data/generated_html/`，元数据记录在 `backend/data/html_generator.db`。
|
||
|
||
## 适用场景
|
||
|
||
- 教育智能体生成知识点讲解页
|
||
- 将模型输出的 HTML 片段封装为完整页面
|
||
- 为智能体返回可分享、可打开的独立链接
|
||
- 保留一定天数后自动清理过期文件
|
||
|
||
## 推荐对接方式
|
||
|
||
腾讯云智能体侧建议直接使用本服务的 OpenAPI 文档：
|
||
|
||
- OpenAPI 地址：`https://你的域名/openapi.json`
|
||
- 接口文档地址：`https://你的域名/docs`
|
||
|
||
如果你们使用腾讯云智能体的 API 插件或 HTTP 工具节点，推荐直接导入上面的 OpenAPI 文档；如果不导入，也可以手工按本文档配置请求参数。
|
||
|
||
## 接口总览
|
||
|
||
### 1. 生成 HTML
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/api/html/generate`
|
||
- Content-Type：`application/json`
|
||
|
||
#### 请求头
|
||
|
||
| 名称 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `Content-Type` | string | 是 | 固定为 `application/json` |
|
||
| `X-API-Key` | string | 否 | 当服务端配置了 `API_KEY` 时必填 |
|
||
|
||
#### 请求体参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `html_content` | string | 是 | 智能体生成的 HTML 内容，可以是完整 HTML，也可以是 HTML 片段 |
|
||
| `title` | string | 否 | 页面标题，最大 120 个字符 |
|
||
| `source` | string | 否 | 来源标识，建议填智能体名称、工作流名或插件名，最大 80 个字符 |
|
||
| `request_id` | string | 否 | 请求追踪 ID，方便排查问题，最大 120 个字符 |
|
||
| `ttl_days` | integer | 否 | 文件保留天数，默认 7 天，最大 30 天 |
|
||
|
||
#### 兼容别名
|
||
|
||
为了方便不同智能体或旧配置迁移，服务还兼容以下别名：
|
||
|
||
- `html` -> `html_content`
|
||
- `content` -> `html_content`
|
||
- `expire_days` -> `ttl_days`
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"title": "勾股定理讲解",
|
||
"source": "tencent-education-agent",
|
||
"request_id": "lesson-math-20260321-001",
|
||
"ttl_days": 7,
|
||
"html_content": "<section><h1>勾股定理</h1><p>在直角三角形中，a² + b² = c²。</p></section>"
|
||
}
|
||
```
|
||
|
||
#### 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"message": "HTML file generated successfully",
|
||
"unique_id": "vE7k7llv3zXc1A08",
|
||
"url": "https://你的域名/api/html/vE7k7llv3zXc1A08/content",
|
||
"query_url": "https://你的域名/api/html/vE7k7llv3zXc1A08",
|
||
"title": "勾股定理讲解",
|
||
"source": "tencent-education-agent",
|
||
"request_id": "lesson-math-20260321-001",
|
||
"size_bytes": 1286,
|
||
"created_at": "2026-03-21T12:00:00.000000",
|
||
"expires_at": "2026-03-28T12:00:00.000000"
|
||
}
|
||
```
|
||
|
||
#### 字段说明
|
||
|
||
| 返回字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `message` | string | 接口处理结果说明 |
|
||
| `unique_id` | string | 系统生成的唯一 ID |
|
||
| `url` | string | 可直接打开的 HTML 页面地址 |
|
||
| `query_url` | string | 查询该记录元数据的地址 |
|
||
| `title` | string \| null | 页面标题 |
|
||
| `source` | string \| null | 来源标识 |
|
||
| `request_id` | string \| null | 请求追踪 ID |
|
||
| `size_bytes` | integer | 实际生成文件大小，单位字节 |
|
||
| `created_at` | string | 创建时间，UTC |
|
||
| `expires_at` | string | 过期时间，UTC |
|
||
|
||
### 2. 查询已生成 HTML 的元数据
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/api/html/{unique_id}`
|
||
|
||
返回结构与生成接口一致，可用于后续查询链接是否仍有效。
|
||
|
||
### 3. 访问 HTML 内容
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/api/html/{unique_id}/content`
|
||
|
||
这个地址会直接返回 `text/html` 内容。智能体侧通常只需要使用生成接口返回的 `url` 字段即可。
|
||
|
||
## 智能体调用约定
|
||
|
||
建议腾讯云智能体在工具描述中遵守以下规则：
|
||
|
||
1. `html_content` 必须是完整、可展示的知识讲解内容，优先输出结构化讲解，不要只返回一句话。
|
||
2. 推荐使用语义标签，例如 `section`、`article`、`h1`、`h2`、`p`、`ul`、`ol`、`table`。
|
||
3. 如果只生成 HTML 片段，服务端会自动补齐基础的 `html/head/body` 包装。
|
||
4. 优先输出静态展示内容，不要把它当成前端应用来写。
|
||
5. 成功后请直接使用返回的 `url` 对外展示，不要自己拼接文件名。
|
||
|
||
## 内容限制和安全规则
|
||
|
||
当 `ALLOW_UNSAFE_HTML=false` 时，默认开启安全拦截，以下内容会被拒绝：
|
||
|
||
- `<script>`
|
||
- `<iframe>`
|
||
- `<object>` / `<embed>` / `<base>`
|
||
- `<form>`
|
||
- `<link>`
|
||
- `meta refresh`
|
||
- 内联事件属性，例如 `onclick=`
|
||
- `javascript:` 协议
|
||
|
||
这是为了避免智能体把任意动态脚本直接挂到线上域名下。
|
||
|
||
当前项目默认配置已经改为 `ALLOW_UNSAFE_HTML=true`，也就是：
|
||
|
||
- 不再拦截 `<script>`、`<link>` 等标签
|
||
- 返回 HTML 时不再附加严格的 CSP 头
|
||
- 适合需要 JavaScript 动态展示的页面
|
||
|
||
这意味着安全风险将由你们自己兜底，建议至少做到：
|
||
|
||
- 独立子域名部署
|
||
- 不挂载登录态 Cookie
|
||
- 不与主站后台同域
|
||
- 对智能体输出做额外审核
|
||
|
||
### 推荐约束
|
||
|
||
- 推荐把生成 HTML 的访问域名单独隔离，例如 `html.example.com`
|
||
- 推荐全站 HTTPS
|
||
- 不要在该域名下挂载登录态 Cookie
|
||
- 生产环境不要把 `ALLOW_UNSAFE_HTML` 设为 `true`
|
||
- 单次 HTML 内容大小默认不超过 `200000` 字节
|
||
|
||
## 常见状态码
|
||
|
||
| 状态码 | 含义 |
|
||
| --- | --- |
|
||
| `201` | HTML 创建成功 |
|
||
| `400` | HTML 内容不安全或业务参数非法 |
|
||
| `401` | API Key 不正确 |
|
||
| `404` | 记录不存在或已过期 |
|
||
| `422` | 请求体格式不符合要求 |
|
||
| `500` | 服务端异常 |
|
||
|
||
## 本地启动
|
||
|
||
### 后端
|
||
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
python server.py
|
||
```
|
||
|
||
也可以直接使用：
|
||
|
||
```bash
|
||
cd backend
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
### 前端演示页
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
如需指定后端地址，可设置：
|
||
|
||
```bash
|
||
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
`backend/.env.example` 已给出示例，核心配置如下：
|
||
|
||
| 变量名 | 类型 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `APP_NAME` | string | `HTML Knowledge API` | 服务名称 |
|
||
| `API_PREFIX` | string | `/api` | 接口前缀 |
|
||
| `PUBLIC_BASE_URL` | string | `http://localhost:8000` | 对外可访问的服务域名 |
|
||
| `ALLOWED_ORIGINS` | JSON array / string | `["*"]` | CORS 白名单 |
|
||
| `HTML_STORAGE_DIR` | string | `./data/generated_html` | HTML 文件存储目录 |
|
||
| `DEFAULT_RETENTION_DAYS` | integer | `7` | 默认保留天数 |
|
||
| `MAX_RETENTION_DAYS` | integer | `30` | 最大允许保留天数 |
|
||
| `MAX_HTML_LENGTH` | integer | `200000` | 单次 HTML 最大字节数 |
|
||
| `API_KEY` | string | 空 | 非空时启用 `X-API-Key` 鉴权 |
|
||
| `ALLOW_UNSAFE_HTML` | boolean | `true` | 是否关闭 HTML 安全拦截；当前默认开启，便于执行 JS |
|
||
|
||
## 给腾讯云智能体的最小参数说明
|
||
|
||
如果你们只想保留最简单的调用方式，智能体只传下面这一个字段也能工作：
|
||
|
||
```json
|
||
{
|
||
"html_content": "<section><h1>牛顿第一定律</h1><p>物体在不受外力时，将保持静止或匀速直线运动状态。</p></section>"
|
||
}
|
||
```
|
||
|
||
推荐智能体至少传：
|
||
|
||
```json
|
||
{
|
||
"title": "牛顿第一定律讲解",
|
||
"source": "tencent-education-agent",
|
||
"request_id": "physics-lesson-001",
|
||
"html_content": "<section>...</section>"
|
||
}
|
||
```
|
||
|
||
## 目录说明
|
||
|
||
- `backend/app/main.py`：FastAPI 应用入口
|
||
- `backend/app/routers/html.py`：HTML 生成、查询、访问接口
|
||
- `backend/app/schemas.py`：请求与响应模型
|
||
- `backend/app/models.py`：数据库模型
|
||
- `backend/server.py`：本地启动脚本
|
||
- `frontend/app/page.tsx`：手工联调用演示页
|
||
|
||
## 后续建议
|
||
|
||
如果你们后面还想继续增强，可以优先做这三项：
|
||
|
||
1. 为 `generate` 接口增加业务层面的调用日志和审计记录。
|
||
2. 给智能体增加更严格的 HTML 输出提示词模板，减少不合规标签。
|
||
3. 把 `PUBLIC_BASE_URL` 配成独立子域名，进一步隔离主站风险。
|