边缘安全加速平台 EO 为网站添加 AI 对话助手

你将获得：

·一个开箱即用的 AI 对话 Widget（气泡 + 聊天面板）。

·自动提取当前页面内容作为 AI 上下文。

·通过 API Schema 让 AI 实时查询你的后端数据。

·支持嵌入到任何网站（博客、电商、文档站、管理后台等）。

一、效果预览

用户在你的网站上看到一个聊天气泡，点击后打开对话面板：

·问"这篇文章讲了什么？"→ AI 根据页面内容回答。

·问"帮我搜索 React 相关文章"→ AI 调用你的搜索接口，返回真实数据。

·问"第 3 篇文章的详细内容"→ AI 调用详情接口获取全文。

二、前置条件

1. 一个 EdgeOne Makers 账号。

2. 你的网站（任何框架：React、Vue、WordPress、静态 HTML 等）。

3. （可选）你的后端 API 地址，如果需要 AI 查询业务数据。

四、1、部署 Agent

使用下面的示例模板直接开始部署。

在部署配置页面，填写环境变量（见下方第 2 步）。

五、2、配置环境变量

在部署配置页面（或部署后进入项目 > 设置 > 环境变量），填写以下配置：

注意：说明：

注意：AI_GATEWAY_API_KEY 和 AI_GATEWAY_BASE_URL 通过一键部署时会自动注入。

六、3、绑定自定义域名

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

注意：说明：

注意：绑定自定义域名后无需任何鉴权即可访问，这是正式使用的前提条件。

七、4、嵌入到你的网站

在你网站的 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>

九、自定义系统提示词与推荐问题

编辑项目根目录的 ai-chat-assistant.config.json：

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

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

十一、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 编写技巧

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."

十三、后端跨域要求

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

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

十五、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> 前添加即可，无需任何构建工具。

十九、工作原理

用户在你的网站提问 ↓embed.js 注入气泡 + iframe（加载同源 /widget） ↓embed.js 提取页面内容，通过 postMessage 发送给 iframe ↓┌─────────────────────────────────────────┐│ iframe 内的 /widget 页面（同源） ││ ││ fetch('/chat') → Agent 处理： ││ 1. 将页面内容注入 AI 上下文 ││ 2. AI 判断是否需要调用后端接口 ││ 3. 如果需要 → 调用你的 API → 获取数据 ││ 4. AI 基于所有信息生成回答 ││ 5. SSE 流式返回给前端 │└─────────────────────────────────────────┘ ↓用户看到实时生成的回答

注意：说明：

注意：为什么用 iframe？ iframe 加载的是 Agent 同域的 /widget 页面，内部所有 API 请求都是同源的，不存在跨域问题。

20、本地调试

# 克隆你的仓库git clone https://github.com/你的用户名/ai-assistant.gitcd ai-assistant# 安装依赖npm install# 配置环境变量cp .env.example .env# 编辑 .env 填入 AI_GATEWAY_API_KEY 等# 启动开发服务器edgeone makers dev

21、环境变量一览

注意：说明：

注意：助手名称、欢迎语、系统提示词、推荐问题等配置在项目根目录的 ai-assistant.config.json 中修改。

22、常见问题

Q：我的后端不在 EdgeOne 上，可以用吗？

可以。你的后端可以部署在任何有公网地址的地方（AWS、阿里云、自建服务器等），只需设置 DATA_API_BASE_URL 指向你的后端地址。

Q：不配置 api-schema.json 能用吗？

能用。不配置时 AI 只根据当前页面内容回答问题，不会调用任何外部接口。

Q：AI 会不会调用 schema 里没定义的接口？

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

Q：支持哪些模型？

支持所有 OpenAI 兼容的模型接口，包括 DeepSeek、GPT-4o、Claude、通义千问等。只需修改 AI_GATEWAY_BASE_URL 和 AI_GATEWAY_API_KEY。

Q：embed.js 对单页应用（SPA）支持如何？

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

Q：如何限制 AI 调用频率？

在你的后端做限流即可。Agent 每轮对话最多调用 4 次工具。

23、相关链接

·Makers Agents 文档

·Makers Agents 快速开始

·Makers Models