zwz/minimap1.1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3b660203dd4ee0e576b05d97786c38463789f745
minimap1.1/README.md
ZhangYonghao 3b660203dd fix:修复接口调用问题
2026-03-21 21:27:20 +08:00

8.0 KiB
Raw Blame History

教育智能体 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 配成独立子域名，进一步隔离主站风险。
Reference in New Issue View Git Blame Copy Permalink