# 教育智能体 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 天 |
| `preserve_markdown_fence` | boolean | 否 | 默认为 `false`。当智能体返回的是 ```html fenced code block 时，服务会自动剥离最外层围栏；如果你就是要保留围栏原文，传 `true` |
#### 兼容别名
为了方便不同智能体或旧配置迁移，服务还兼容以下别名：
- `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": "勾股定理
在直角三角形中，a² + b² = c²。
"
}
```
#### 成功响应示例
```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` 字段即可。
## Markdown 代码围栏处理
很多模型会把 HTML 包在下面这种 Markdown 代码块里：
```text
```html
...
```
```
当前服务默认会自动剥离最外层围栏，然后再保存 HTML。
为了避免误判，剥离逻辑是保守的，只有在以下条件同时满足时才会剥离：
- 整个请求内容几乎就是一个外层 fenced code block
- 代码块语言是 `html`、`htm`、`xhtml`、`xml`，或者虽然没写语言但内容明显像 HTML
以下情况不会剥离：
- HTML 正文内部只是包含了几个 ``` 代码围栏示例
- 代码块语言是 `js`、`python` 等非 HTML
- 内容整体看起来不像 HTML
如果你确实希望把最外层 ``` 原样保留到页面中，可以在请求体里传：
```json
{
"html_content": "```html\nhello
\n```",
"preserve_markdown_fence": true
}
```
## 智能体调用约定
建议腾讯云智能体在工具描述中遵守以下规则：
1. `html_content` 必须是完整、可展示的知识讲解内容，优先输出结构化讲解，不要只返回一句话。
2. 推荐使用语义标签，例如 `section`、`article`、`h1`、`h2`、`p`、`ul`、`ol`、`table`。
3. 如果只生成 HTML 片段，服务端会自动补齐基础的 `html/head/body` 包装。
4. 优先输出静态展示内容，不要把它当成前端应用来写。
5. 成功后请直接使用返回的 `url` 对外展示，不要自己拼接文件名。
## 内容限制和安全规则
当 `ALLOW_UNSAFE_HTML=false` 时，默认开启安全拦截，以下内容会被拒绝：
- `