给网站加一个 AI 对话助手：EdgeOne Makers 一行代码嵌入的完整做法

摘要： 使用 EdgeOne Makers 的 AI Chat Assistant 模板，可为任意网站添加 AI 对话助手。部署模板、配置环境变量、绑定自定义域名后，在页面插入一行 embed.js 脚本即可生效。助手能读取当前页面内容，并按 api-schema.json 定义调用你的后端接口。

给网站加 AI 对话助手的实际工作量是四步：部署模板、配环境变量、绑自定义域名、页面里插一行 script。嵌入代码只有一行，放在 body 结束标签之前，刷新页面右下角就会出现聊天气泡。助手默认能读取用户当前浏览的页面内容作为上下文，如果额外配置了 api-schema.json，它还能调用你自己的后端接口返回真实业务数据。它不会调用 schema 里没定义的接口，每轮对话最多调用 4 次工具。

一、这个 AI 对话助手能做到什么，做不到什么

能做到的：

读取用户当前所在页面的内容作为上下文。用户问"这篇文章讲了什么"，助手基于当前页面内容回答。

按你定义的接口查询业务数据。配置 api-schema.json 后，用户问"帮我搜索 React 相关文章"，助手会调用你的搜索接口返回真实数据；问"第 3 篇的详细内容"，它会调用详情接口获取全文。

嵌入任意网站。博客、电商、文档站、管理后台都可以，不限制前端框架。

单页应用的路由切换自适应。脚本会自动检测 URL 变化，路由切换时重新提取页面内容发送给 AI。

做不到或有边界的：

不会自动获取全站数据。它的信息来源只有两个——当前页面内容，以及你在 api-schema.json 中明确定义的接口。

不会调用未定义的接口。AI 只能调用 schema 中明确定义的接口，不会自行构造其他请求。

每轮对话最多调用 4 次工具。链路很长的查询需要拆成多轮，或在后端把多次查询合并成一个接口。

回答质量取决于模型与提示词。它是一套对话能力的工程接入方案，不对回答准确率做保证，涉及订单、支付、合规答复等高风险场景建议保留人工通道。

二、部署 AI Chat Assistant 模板并配置环境变量

从 AI Chat Assistant 模板直接部署一个项目，在部署配置页填写环境变量。已有项目则进入项目设置的环境变量页填写。

通过一键部署时，AI_GATEWAY_API_KEY 和 AI_GATEWAY_BASE_URL 会自动注入，不需要手动准备密钥即可先跑通。需要让助手查询业务数据时才需要填后两项。

模型方面支持所有 OpenAI 兼容的模型接口，包括 DeepSeek、Claude、通义千问等。换模型只需修改 AI_GATEWAY_BASE_URL 与 AI_GATEWAY_API_KEY，以及 AI_GATEWAY_MODEL。

三、为什么必须绑定自定义域名

进入控制台的项目 → 域名管理，绑定自己的域名，例如 chat.example.com。

绑定自定义域名后无需任何鉴权即可访问，这是正式使用的前提条件。 没有绑定自定义域名时，直接用平台默认地址嵌入到生产站点会受访问鉴权限制，对外用户打不开。免费版支持 200 个自定义域名并提供免费 SSL 证书，证书可通过自动验证、DNS 委派验证、文件验证等方式申请。

建议用子域名，例如 chat.你的主域名，和主站分开管理。

四、一行代码嵌入网站，以及外观自定义

在网站 HTML 的 </body> 之前添加一行：

<script src="https://chat.example.com/embed.js" async></script>

刷新页面，右下角出现聊天气泡，点击即可对话。

通过 data-* 属性自定义外观：

<script
  src="https://chat.example.com/embed.js"
  data-color="#10b981"
  data-position="bottom-left"
  data-name="小助手"
  async
></script>

名称、欢迎语、系统提示词、推荐问题在项目根目录的配置文件里改：

{
  "name": "我的助手",
  "welcome": "你好！有什么可以帮你的？",
  "systemPrompt": "你是一个专业的电商客服助手。回答要简洁友好，优先推荐店铺商品。",
  "suggestedQuestions": [
    "有哪些热门商品？",
    "如何查询订单状态？",
    "退换货政策是什么？"
  ]
}

修改后推送代码或重新部署即可生效。

五、让助手回答你自己的业务数据

配置 api-schema.json 定义可调用的接口。

endpoint 路径规则：路径中的 {param} 会被同名参数值替换。GET /api/posts/{id} 配合参数 {"id": "5"} 实际请求 GET /api/posts/5。未用于路径替换的参数，GET 请求作为 query string（如 GET /api/posts?q=react），POST 或 PUT 请求作为 JSON body。

description 的写法直接决定效果。它告诉 AI 什么时候该调用这个接口：

// ❌ 太模糊
"description": "获取数据"

// ✅ 清楚说明功能 + 使用时机
"description": "Get the full content of a single blog post by its ID. Use search_posts first if you don't know the ID."

写清楚两件事：这个接口做什么、什么情况下该用它。接口之间有依赖关系时（先搜索拿到 ID 再查详情），在 description 里写明调用顺序。

后端跨域要求。助手会从 EdgeOne 域名向你的后端发起请求，需要在后端设置 CORS：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

生产环境建议把 Access-Control-Allow-Origin 收敛为你的助手域名，不要长期使用通配符。

六、在不同框架中嵌入

React / Next.js

useEffect(() => {
  const s = document.createElement('script');
  s.src = 'https://chat.example.com/embed.js';
  s.async = true;
  document.body.appendChild(s);
  return () => document.body.removeChild(s);
}, []);

Vue

<script setup>
import { onMounted } from 'vue'
onMounted(() => {
  const s = document.createElement('script')
  s.src = 'https://chat.example.com/embed.js'
  s.async = true
  document.body.appendChild(s)
})
</script>

WordPress

在主题的 footer.php 中 </body> 前添加：

<script src="https://chat.example.com/embed.js" async></script>

静态 HTML

直接在 </body> 前添加同样一行，不需要任何构建工具。

七、AI 对话助手是怎么工作的

整条链路如下：

用户在网站提问，embed.js 注入聊天气泡和一个 iframe（加载与 Agent 同源的 widget 页面）。embed.js 提取当前页面内容，通过 postMessage 发送给 iframe。iframe 内的 widget 页面发起 fetch('/chat') 请求，Agent 依次完成四步：把页面内容注入 AI 上下文、判断是否需要调用后端接口、需要则调用你的 API 获取数据、基于所有信息生成回答，并通过 SSE 流式返回给前端。用户看到实时生成的回答。

为什么用 iframe：iframe 加载的是与 Agent 同域的 widget 页面，内部所有 API 请求都是同源的，不存在跨域问题。这也是嵌入代码能做到只有一行、不需要在宿主站点做任何跨域配置的原因。

八、常见问题

后端不在腾讯云上，可以用吗？ 可以。后端可以部署在任何有公网地址的地方，只需把 DATA_API_BASE_URL 指向你的后端地址。

不配置 api-schema.json 能用吗？ 能用。不配置时 AI 只根据当前页面内容回答问题，不会调用任何外部接口。文档站、博客这类场景通常不配置也够用。

AI 会不会调用 schema 里没定义的接口？ 不会。AI 只能调用 api-schema.json 中明确定义的接口，不会自行构造其他请求。

支持哪些模型？ 支持所有 OpenAI 兼容的模型接口，包括 DeepSeek、Claude、通义千问等，通过修改环境变量切换。

单页应用支持如何？ 支持。脚本会自动检测 URL 变化，路由切换时重新提取页面内容发送给 AI。

如何限制调用频率？ 在你的后端做限流。Agent 每轮对话最多调用 4 次工具，这是平台侧的上限。

本地怎么调试？ 克隆仓库后安装依赖，复制 .env.example 为 .env 并填入 AI_GATEWAY_API_KEY 等变量，执行 edgeone makers dev 启动开发服务器。

总结

这套方案的工程成本集中在前期：部署模板、配两三个环境变量、绑一个子域名，之后宿主站点只需要加一行 script。它的能力边界清晰——信息来源是当前页面内容加上你明确定义的接口，不会越界调用，每轮最多 4 次工具调用。想让它答得准，关键不在模型，在 systemPrompt 写得够具体、api-schema.json 的 description 写清楚了调用时机。

面向 C 端用户的场景建议保留人工客服入口，把 AI 助手定位成常见问题的第一道分流，而不是全部替代。

产品完整能力与控制台入口见 EdgeOne Makers 产品页：https://cloud.tencent.com/product/makers

当前首购特惠 EdgeOne Makers 专业版 Pro 套餐 39 元/月，具体以活动页实际展示为准：https://cloud.tencent.com/act/pro/makers-pro