教育智能体 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

请求示例

{
  "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>"
}

成功响应示例

{
  "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	服务端异常

本地启动

后端

cd backend
pip install -r requirements.txt
python server.py

也可以直接使用：

cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

前端演示页

cd frontend
npm install
npm run dev

如需指定后端地址，可设置：

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

给腾讯云智能体的最小参数说明

如果你们只想保留最简单的调用方式，智能体只传下面这一个字段也能工作：

{
  "html_content": "<section><h1>牛顿第一定律</h1><p>物体在不受外力时，将保持静止或匀速直线运动状态。</p></section>"
}

推荐智能体至少传：

{
  "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 配成独立子域名，进一步隔离主站风险。