§15 给网站加一个会"看"页面的 AI 对话助手

3天前我帮一个做技术博客的朋友接 AI 助手。他最怕两件事：一是要改一大堆后端代码，二是 AI 答非所问。我用 EdgeOne Makers 的 AI Assistant 模板给他半小时搞定，零后端改动。这一章我就把这事拆给你看。

经验：很多人以为"给网站加 AI 客服"得自己搭 RAG、向量库、检索服务。在 Makers 上不用——模板把脏活全接了，你只写业务 API 的 Schema。

15.1 它到底解决什么

你给网站加一段 <script>，右下角就多一个聊天气泡。用户问"这篇文章讲了什么"，AI 能根据当前页面内容回答；问"搜一下 React 相关的文章"，AI 会调用你的搜索接口返回真实数据。支持嵌到任何站点：React、Vue、WordPress、纯静态 HTML 都行。

15.2 部署：一行代码的事

先在 Makers 控制台用 AI Assistant 模板部署一个 Agent。配置环境变量：

变量	必填	说明
`AI_GATEWAY_MODEL`	否	模型 ID，默认 `@makers/deepseek-v3`
`DATA_API_BASE_URL`	否	你的后端 API 根地址，如 `https://api.example.com`
`DATA_API_KEY`	否	后端认证 Token，会加到 `Authorization: Bearer` 头
`AI_GATEWAY_API_KEY`	是*	模型网关 Key，一键部署时自动注入
`AI_GATEWAY_BASE_URL`	是*	模型网关地址，一键部署时自动注入

标叔的结论：AI_GATEWAY_API_KEY / AI_GATEWAY_BASE_URL 标星是因为一键部署会自动注入，你根本不用管；只有本地调试才手动填。别被"必填"吓到。

部署完绑定自定义域名（如 chat.example.com），然后在网站 </body> 前加一行：

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

刷新页面，气泡就出现了。完事。

15.3 外观与提示词都能改

气泡颜色、位置、名字靠 data-* 属性：

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

AI 的人设、欢迎语、推荐问题写在项目根目录的 ai-chat-assistant.config.json：

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

建议：systemPrompt 别写"你是万能助手"。越具体（行业 + 语气 + 优先动作），AI 越不跑偏。

15.4 让 AI 查你的业务数据：API Schema

光靠页面内容不够，得让 AI 调你的接口。写 api-schema.json：

{
  "endpoints": [
    {
      "path": "GET /api/posts/{id}",
      "description": "Get the full content of a single blog post by its ID. Use search_posts first if you don't know the ID."
    }
  ]
}

写法	效果
`GET /api/posts/{id}` + `{"id":"5"}`	变成 `GET /api/posts/5`
`GET` 多余参数	拼成 query string `?q=react`
`POST` 多余参数	放进 JSON body

警告：description 写"获取数据"这种模糊话，AI 根本不知道什么时候该调。写成"功能 + 使用时机"才灵。AI 只能调你 Schema 里定义的接口，不会自己乱造请求——这是安全边界，不是缺陷。

后端要开 CORS：

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

15.5 它怎么工作的

embed.js 注入气泡 + 一个同源 iframe（加载 /widget）。iframe 提取页面内容，通过 postMessage 发给 Agent；Agent 调 /chat，把页面内容塞进上下文，判断要不要查你的 API，最后用 SSE 流式把答案推回来。

经验：用 iframe 是因为它和 Agent 同域，内部请求同源，没有跨域麻烦。你后端在哪都行（AWS、阿里云、自建），只要 DATA_API_BASE_URL 指过去。

15.6 本地调试与常见坑

git clone https://github.com/你的用户名/ai-assistant.git
cd ai-assistant
npm install
cp .env.example .env   # 填入 AI_GATEWAY_API_KEY 等
edgeone makers dev     # 本地开发服务器

问题	答案
后端不在 Makers 上能用吗	能，只要公网可达
不配 Schema 能用吗	能，AI 只看页面内容
支持哪些模型	所有 OpenAI 兼容的：DeepSeek、GPT-4o、Claude、通义千问
SPA 支持吗	支持，路由切换自动重新提取页面

标叔的结论：每轮对话 AI 最多调 4 次工具，频率限制在你后端做。Agent 本身不替你限流。

下一章，我们换个角度——不碰 UI，直接用一句话让 AI 把整个项目部署上线。