技术文档

超级智能体外站接入指南（HTML / Hexo / Hugo / 任意站点）

Noise

2026-04-02

#超级智能体 #外站接入

摘要：本指南介绍如何将超级智能体嵌入外部站点，无需特定框架。用户可通过引入JS脚本、指定初始化参数或自动初始化方式实现悬浮对话面板。强调安全性，要求提供AI参数或系统Token。适用于HTML、Hexo、Hugo等任意网站。

指南面向“外部站点前台悬浮智能体”接入，不要求你和本项目使用同一框架。

你可以直接在任意网站加载一个 JS 文件，让智能体悬浮在页面右下角或左下角并可对话。

（注：V3.4之后版本）

1. 一句话接入方式

你只需要在外站页面引入本项目提供的脚本：

脚本地址：https://www.noisevip.cn/super-agent-embed.js
对话接口：https://www.noisevip.cn/api/ai/super-agent

本项目已为该对话接口增加跨域支持（CORS），可直接被外站调用。

安全默认策略（已更新）：

外站接入默认必须使用外站独立 AI 参数（apiService + apiKey/apiToken + apiModel，可选 apiBaseUrl）
未提供外站 AI 参数时，请求会直接报错，不再自动复用站内 AI 配置
如确需复用站内 AI，必须额外提供系统 Token 鉴权（systemToken / data-system-token）
仅当 systemToken 能被后端正确识别为有效站内系统令牌时，才会放行复用站内智能体能力；缺失、错误或无效 token 都会被拒绝，仍不能复用站内 AI

2. 纯 HTML 站点接入（可直接复制）

把下面代码放进你的网站 HTML（通常是 </body> 前）：

<script src="https://www.noisevip.cn/super-agent-embed.js"></script>
<script>
  window.VipSuperAgent.init({
    apiBase: "https://www.noisevip.cn",
    title: "超级智能体",
    subtitle: "问我当前页面内容",
    hideSubtitle: false,
    compactHeader: true,
    primaryColor: "#f59e0b",
    iconUrl: "https://www.noisevip.cn/images/favicon.ico",
    apiService: "openai",
    apiKey: "sk-xxxx",
    apiBaseUrl: "https://api.openai.com/v1/chat/completions",
    apiModel: "gpt-4o-mini",
    systemToken: "",
    mode: "chat",
    apiSystemPrompt: "你是网站智能助手",
    quickQuestions: ["你是谁？", "这篇文章讲了什么？", "帮我总结当前页面重点"],
    runtimeSkills: [
      { "name": "写作规范", "enabled": true, "content": "回答保持条理清晰，优先给可执行步骤。" }
    ],
    runtimeMcpServers: {
      "knowledge": {
        "url": "https://mcp.example.com/query",
        "headers": { "Authorization": "Bearer your-mcp-token" },
        "enabled": true
      }
    },
    panelOpacity: 0.92,
    zIndex: 2147483000,
    anchorSelector: ""
  });
</script>

参数说明：

apiBase：必填，固定填你的智能体服务域名 https://www.noisevip.cn（不带 /api/ai/super-agent，不是接入方自己的网站域名）
title/subtitle：面板标题
hideSubtitle：可选，是否隐藏副标题（默认 false）
compactHeader：可选，紧凑头部样式（默认 false）
primaryColor：可选，主色（支持 #hex 或 rgb/rgba，默认 #f59e0b）
iconUrl：可选，悬浮图标图片（必须是纯 URL 字符串，不要包含反引号或额外空格；如需强制刷新缓存可追加 ?v=2）
apiService：可选，自定义服务标识
apiKey：可选，自定义服务 Key（外站接入建议必填）
apiToken：可选，apiKey 的别名参数（任选其一）
apiBaseUrl：可选，外站自定义接口地址
apiModel：可选，模型
systemToken：可选，系统鉴权 Token；仅当你要“复用站内 AI”时填写
mode：可选，请求模式（chat | search | execute，默认 chat）
apiSystemPrompt：可选，系统提示词
quickQuestions：可选，面板快捷提问列表（字符串数组）
runtimeSkills：可选，运行时 Skill 列表（优先于后台 Skill 配置）
runtimeMcpServers：可选，运行时 MCP 服务（优先于后台 MCP 配置）
dailyLimitPerUser：可选，请求限额参数（默认 0，由服务端统一判断）
panelOpacity：可选，弹窗透明度（0.55 - 1.00）
buttonLeft/buttonTop：可选，悬浮按钮定位参数；仅根据 buttonLeft 判断左右（左下/右下），buttonTop 会被忽略，始终贴底显示
panelLeft/panelTop：可选，对话面板定位参数；仅根据 panelLeft 判断左右（左下/右下），panelTop 会被忽略，始终贴底显示
zIndex：可选，层级
anchorSelector：可选，若你的站点已有“上滑/下滑按钮”，可传其 CSS 选择器，智能体会自动对齐在其上方

2.0 接入方需要替换哪些参数

必填：apiBase（应填 https://www.noisevip.cn）
一般建议替换：title、subtitle、iconUrl、anchorSelector（按接入方站点 UI 调整）
若接入方要使用自己的第三方 AI：填写 apiService + apiKey/apiToken + apiModel，可选再填 apiBaseUrl
若接入方不填 AI 参数：将返回错误，不再默认复用站内配置
若接入方希望复用站内 AI：必须提供 systemToken（或 data-system-token）通过鉴权

2.1 最少代码接入写法

如果你只想最小可用接入（使用你自己的第三方 AI，不依赖后台配置），可直接复制：

<script src="https://www.noisevip.cn/super-agent-embed.js"></script>
<script>
  window.VipSuperAgent.init({ apiBase: "https://www.noisevip.cn", apiToken: "sk-xxxx", apiService: "openai", apiModel: "gpt-4o-mini", compactHeader: true, primaryColor: "#f59e0b" });
</script>

说明：

上述写法即可直接用第三方 AI 服务，不要求你在 Noise宝藏阁后台先配置该服务。
如需自定义网关，补充 apiBaseUrl 即可。

2.2 一行 Script 自动初始化（无需再写第二段 JS）

如果你希望“只引一个 script 就完成初始化”，可以直接这样写：

<script
  src="https://www.noisevip.cn/super-agent-embed.js"
  data-super-agent
  data-api-base="https://www.noisevip.cn"
  data-title="超级智能体"
  data-subtitle="欢迎提问"
  data-hide-subtitle="false"
  data-compact-header="true"
  data-primary-color="#f59e0b"
  data-icon-url="https://www.noisevip.cn/images/favicon.ico"
  data-api-service="openai"
  data-api-key="sk-xxxx"
  data-api-base-url="https://api.openai.com/v1/chat/completions"
  data-api-model="gpt-4o-mini"
  data-system-token=""
  data-api-system-prompt="你是网站智能助手"
  data-mode="chat"
  data-runtime-skills='[{"name":"写作规范","enabled":true,"content":"回答保持条理清晰，优先给可执行步骤。"}]'
  data-runtime-mcp-servers='{"knowledge":{"url":"https://mcp.example.com/query","headers":{"Authorization":"Bearer your-mcp-token"},"enabled":true}}'
  data-quick-questions='["你是谁？","这篇文章讲了什么？"]'
  data-panel-opacity="0.92"
  data-z-index="2147483000"
  data-anchor-selector=".scroll-top-btn"
></script>

2.2.1 自动初始化最小示例（验证头像是否生效）

如果你要快速验证外站头像是否正确更新，建议先用这段最小写法：

<script
  src="https://www.noisevip.cn/super-agent-embed.js?v=20260402"
  data-super-agent
  data-api-base="https://www.noisevip.cn"
  data-api-service="openai"
  data-api-token="sk-xxxx"
  data-api-model="gpt-4o-mini"
  data-icon-url="https://www.noisevip.cn/images/favicon.ico?v=20260402"
></script>

说明：

data-icon-url 必须是纯 URL 字符串，不要包含反引号、中文引号或前后空格
super-agent-embed.js 与 iconUrl 都建议带版本参数（?v=...）避免浏览器/CDN 缓存
若页面同时存在多段初始化代码，最终以后执行的那段配置为准

支持的 data-* 参数：

data-super-agent：存在即启用自动初始化
data-api-base：必填，智能体服务域名（如 https://www.noisevip.cn）
data-title / data-subtitle
data-hide-subtitle：true | false
data-compact-header：true | false
data-primary-color：主色（如 #f59e0b）
data-icon-url
data-api-service / data-api-key / data-api-base-url / data-api-model / data-api-system-prompt
data-api-token（data-api-key 别名）
data-system-token：复用站内 AI 时必填系统鉴权 Token
data-mode：chat | search | execute
data-runtime-skills / data-runtime-mcp-servers（JSON 字符串）
data-quick-questions（JSON 字符串数组）
data-daily-limit-per-user：可选，请求参数，默认 0
data-panel-opacity（0.55 - 1.00）
data-button-left / data-button-top / data-panel-left / data-panel-top
data-z-index
data-anchor-selector

说明：

位置已限制为底部双角：仅允许右下角或左下角，不再支持顶部任意位置。
若未配置定位参数，组件默认在右下角展示。
若同时设置 anchorSelector 与 buttonLeft/buttonTop，优先使用显式参数，但仅用于判断左右角位。
buttonTop / panelTop 会被忽略，组件始终贴底布局，避免出现在左上角。
若 buttonLeft 或 panelLeft 传入 0 等极小值，脚本会按“未配置”处理并回退默认右下角。
若传入 runtimeSkills / runtimeMcpServers，将优先覆盖后台同名配置，仅对当前外站请求生效。
外站传入 panelOpacity 会覆盖后台透明度设置，仅对当前嵌入实例生效。
后台可配置“每访客每日调用上限”，达到上限后站内与外站均会返回限额提示。
外部嵌入面板右上角提供“设置”按钮，可在展开状态中配置自定义 AI 服务参数并保存到浏览器本地。
外部嵌入设置面板支持填写系统 Token；仅在“需要复用站内 AI”时使用。
外站嵌入默认开启隐私遮罩，不会在前台展示后端实际服务商与模型信息。
外站设置缓存按“接入站点域名 + apiBase”隔离，避免不同网站之间互相带出服务商与模型信息。
外站未填写 AI 参数，或 service/key/model 参数不完整且未提供系统 Token 时，会在前端与接口侧同时提示错误。

2.3 MCP 与 Skill 联动说明

前台不需要新增操作按钮，智能体会自动在每次问答中尝试联动已启用的 Skill 与 MCP。
返回消息会附带 MCP 调用状态（成功/失败）与联动数量标记，便于观察运行情况。
外部嵌入样式已对齐本站智能体，默认无横向滚动条，仅保留上下滚动。
会话记录与弹窗展开状态会保存在接入站点浏览器本地，路由跳转后可自动恢复。
外站脚本会为每个浏览器生成独立 clientId，用于每日调用次数限额统计。

2.4 身份字段模型

当前超级智能体已统一采用四个身份字段参与记忆隔离与调试元信息：

principalId：强身份主键。优先表示“已登录用户 / 外部账号主键 / unionId / openId / memberId”这类可跨渠道稳定识别的主体。
participantId：渠道参与者标识。表示“当前渠道里的这个参与者是谁”，适合区分站内悬浮窗、外站嵌入、OpenAI 兼容客户端等不同入口。
visitorId：访客或设备标识。用于匿名场景下识别浏览器/设备。
conversationId：当前会话、线程或 session 标识。用于把同一参与者的多轮对话继续隔离成不同会话。

各入口默认规则：

站内 SuperAgentWidget：自动发送 participantId=site-widget:{clientId}、visitorId={clientId}、conversationId={当前对话ID}；若用户已登录，后端会再补出 principalId。
外站 super-agent-embed.js：自动发送 participantId=external-embed:{clientId}、visitorId={clientId}、conversationId={当前对话ID}。
OpenAI 兼容接口：支持从请求体、metadata、请求头中读取这四个字段；未显式提供时会优先从鉴权用户和 clientId 推导。
若外站开启 privacyMask（外站嵌入默认开启），响应 meta 中的 scopeKey、principalId、participantId、visitorId、conversationId 会按公开模式打码。

记忆 scope 规则：

存在 principalId 时，记忆写入 scopeType=user。
不存在 principalId 时，记忆写入 scopeType=visitor。
scopeKey 会统一包含 principal/visitor + role + channel + participant + conversation，保证不同渠道、不同会话都走同一套隔离逻辑。

3. Hexo 接入

推荐放在主题脚本注入位置，或 layout/_partial/footer.ejs。

<script src="https://www.noisevip.cn/super-agent-embed.js"></script>
<script>
  window.VipSuperAgent.init({
    apiBase: "https://www.noisevip.cn",
    title: "超级智能体",
    subtitle: "欢迎提问",
    apiService: "openai",
    apiToken: "sk-xxxx",
    apiModel: "gpt-4o-mini",
    dailyLimitPerUser: 0,
    anchorSelector: ".scroll-top-btn"
  });
</script>

如果你的上滑按钮 class 不是 .scroll-top-btn，改为你实际的 class/id。

4. Hugo 接入

推荐放在 layouts/partials/footer.html 或主题统一脚本区：

<script src="https://www.noisevip.cn/super-agent-embed.js"></script>
<script>
  window.VipSuperAgent.init({
    apiBase: "https://www.noisevip.cn",
    title: "超级智能体",
    subtitle: "可结合当前文章问答",
    apiService: "openai",
    apiToken: "sk-xxxx",
    apiModel: "gpt-4o-mini",
    dailyLimitPerUser: 0,
    anchorSelector: "#back-to-top"
  });
</script>

5. 任意框架（Vue/React/Next/Nuxt/Svelte）

在全局布局注入脚本（只加载一次）
在页面 mounted 后执行 window.VipSuperAgent.init(...)
路由切换无需手动传 slug，脚本会读取当前 location.pathname 和 document.title

5.1 OpenAI 兼容接口与微信渲染能力

OpenAI 兼容接口会返回清洗后的正文，不再把 <think>...</think> 标签直接暴露给客户端
若模型包含思考链路，reasoning_content 会独立返回；开启 include_thinking 时会在正文中同时展示“思考过程 + 最终回答”
OpenAI 兼容接口会额外提供媒体信息（如 Markdown 图片）用于客户端渲染
OpenAI 兼容接口现已支持透传 principalId / participantId / visitorId / conversationId
兼容字段既可放在请求体顶层，也可放在 metadata 中；请求头同时支持 x-principal-id / x-participant-id / x-visitor-id / x-conversation-id
若只提供 clientId 而未显式提供身份字段，服务端会自动补出 participantId 与 visitorId，并尽量从鉴权信息推导 principalId
微信通道会将 Markdown 转为可读文本，避免未渲染标记直接显示
微信超时异步回复会推送文本结果，并对图片链接追加图文消息展示

6. 文章页上下文感知说明

脚本会自动把以下上下文传给智能体：

pathname
title
articleSlug（当路径形如 /article/{slug}）

所以在“文章详情页 -> 点击智能体提问”时，智能体会优先感知当前文章上下文。

7. 自定义图标（后台统一配置）

本项目后台已支持配置：

ai.superAgent.iconUrl
ai.superAgent.defaultMode
ai.superAgent.searchTabEnabled
ai.superAgent.showUnreadBadge
ai.superAgent.fusionEnabled
ai.superAgent.fusionSearchEnabled
ai.superAgent.allowActionCommands
ai.superAgent.requireAuth

8. 外站场景下“保存指令/流程/模板”说明

外站嵌入默认面向访客问答。若你希望外站也能触发“保存指令/保存流程/保存模板”等自写入能力，需满足：

请求身份是后台登录用户（通常 admin/editor/author）
后台开启 ai.superAgent.selfWriteEnabled=true
建议使用 execute 模式（或开启 ai.superAgent.chatActsAsExecute=true）
动作未被 ai.agentControl.rolePolicies 拦截

否则外站通常只能进行普通问答与检索，不会执行高权限写入。

你可以在 Noise宝藏阁后台统一管理图标 URL，也可以在外站 init 里用 iconUrl 覆盖。

同时可在后台设置首页悬浮智能体的默认模式、是否显示搜索标签页、是否显示未读角标。
前台组件已支持失败重试与移动端下拉收起交互。
可按需开启 Fusion 上下文增强与 Fusion 联合检索增强，让智能体回答引用流程状态、技能推荐与多源检索结果。
智能体技能来源已统一切换为“技能仓库”，请在后台技能仓库页面完成 GitHub 导入、启用与导出管理。
技能仓库支持一键同步全部已启用 GitHub 仓库，智能体会自动读取同步后的技能内容。
建议默认关闭 ai.superAgent.allowActionCommands，避免未登录访客通过前台悬浮智能体触发动作类指令。
当该开关关闭时，前台仅提供问答能力；删除/发布/回滚等动作请走后台控制台或已授权网关。
建议开启 ai.superAgent.requireAuth 并配置 ai.superAgent.allowedRoles，仅允许已登录且角色命中的用户使用前台智能体。

8. 常见问题

8.1 外站加载了脚本，但不显示

检查 super-agent-embed.js 是否能访问
检查控制台是否有 CSP 拦截（站点禁止第三方脚本）
检查 z-index 是否被你站点遮盖（可调大 zIndex）
若你替换了 iconUrl 且首次出现位置异常，升级到最新脚本并给脚本/头像 URL 增加 ?v=时间戳，避免缓存旧样式

8.2 能显示但无法对话

检查 apiBase 是否写对
检查接口返回是否 200
检查 HTTPS 混合内容问题（https 页面不能请求 http 接口）
apiModel 必须是字符串模型 ID（如 gpt-4o-mini / deepseek-chat），不要传对象
外站若未配置 apiKey/apiToken 且未配置 systemToken，会被安全策略拦截
需要复用站内 AI 时，确认请求已携带 systemToken（会走系统鉴权）

8.4 返回 `Failed to parse URL from /api/admin/apikeys`

这是旧版本后端在服务端侧错误使用相对路径导致的问题，升级到最新版本即可修复。
该问题与外站接入参数无关，apiBase/apiKey/apiToken/apiModel 保持现有写法即可。

8.3 和上滑按钮没对齐

优先传 anchorSelector 指向你站点实际按钮
若不传，脚本按默认右下策略定位

9. 校验清单

页面右下角出现悬浮智能体按钮
点击可展开对话面板
发送问题能收到 data.answer
文章详情页提问时上下文生效
与站点上滑/下滑按钮位置协调

10. 品牌化模板（可直接复制）

10.1 暗色企业风

<script src="https://www.noisevip.cn/super-agent-embed.js"></script>
<script>
  window.VipSuperAgent.init({
    apiBase: "https://www.noisevip.cn",
    apiService: "openai",
    apiToken: "sk-xxxx",
    apiModel: "gpt-4o-mini",
    title: "企业智能助手",
    subtitle: "欢迎咨询产品与文档",
    compactHeader: true,
    hideSubtitle: false,
    primaryColor: "#2563eb",
    anchorSelector: ".scroll-top-btn"
  });
</script>

10.2 清亮简洁风

<script src="https://www.noisevip.cn/super-agent-embed.js"></script>
<script>
  window.VipSuperAgent.init({
    apiBase: "https://www.noisevip.cn",
    apiService: "openai",
    apiToken: "sk-xxxx",
    apiModel: "gpt-4o-mini",
    title: "在线助手",
    subtitle: "快速问答",
    compactHeader: true,
    hideSubtitle: true,
    primaryColor: "#f59e0b",
    anchorSelector: "#back-to-top"
  });
</script>

本文为「Noise」原创内容或编译整理；除特别说明外，文中图片并非个人手绘，可能来源于网络、AI 生成、截图等，后期使用 PhotoMator / Procreate 进行处理，仅用于学习与交流。如涉及版权或来源标注不全，请联系处理。未经授权，禁止用于商业用途，禁止抹除水印。转载请注明出处与链接并保留本声明。

...

评论功能加载中...

Noise

执迷不悟

菜单导航

超级智能体外站接入指南（HTML / Hexo / Hugo / 任意站点）

1. 一句话接入方式

2. 纯 HTML 站点接入（可直接复制）

2.0 接入方需要替换哪些参数

2.1 最少代码接入写法

2.2 一行 Script 自动初始化（无需再写第二段 JS）

2.2.1 自动初始化最小示例（验证头像是否生效）

2.3 MCP 与 Skill 联动说明

2.4 身份字段模型

3. Hexo 接入

4. Hugo 接入

5. 任意框架（Vue/React/Next/Nuxt/Svelte）

5.1 OpenAI 兼容接口与微信渲染能力

6. 文章页上下文感知说明

7. 自定义图标（后台统一配置）

8. 外站场景下“保存指令/流程/模板”说明

8. 常见问题

8.1 外站加载了脚本，但不显示

8.2 能显示但无法对话

8.4 返回 `Failed to parse URL from /api/admin/apikeys`

8.3 和上滑按钮没对齐

9. 校验清单

10. 品牌化模板（可直接复制）

10.1 暗色企业风

10.2 清亮简洁风

评论 (0)

目录

Noise

推荐阅读

安全管理网络层封禁恶意攻击对接指南

智能体记忆系统与知识库存储运行运维说明

宝藏阁智能体对外接入与OpenClaw集成指南

菜单导航

超级智能体外站接入指南（HTML / Hexo / Hugo / 任意站点）

1. 一句话接入方式

2. 纯 HTML 站点接入（可直接复制）

2.0 接入方需要替换哪些参数

2.1 最少代码接入写法

2.2 一行 Script 自动初始化（无需再写第二段 JS）

2.2.1 自动初始化最小示例（验证头像是否生效）

2.3 MCP 与 Skill 联动说明

2.4 身份字段模型

3. Hexo 接入

4. Hugo 接入

5. 任意框架（Vue/React/Next/Nuxt/Svelte）

5.1 OpenAI 兼容接口与微信渲染能力

6. 文章页上下文感知说明

7. 自定义图标（后台统一配置）

8. 外站场景下“保存指令/流程/模板”说明

8. 常见问题

8.1 外站加载了脚本，但不显示

8.2 能显示但无法对话

8.4 返回 Failed to parse URL from /api/admin/apikeys

8.3 和上滑按钮没对齐

9. 校验清单

10. 品牌化模板（可直接复制）

10.1 暗色企业风

10.2 清亮简洁风

评论 (0)

目录

Noise

推荐阅读

安全管理网络层封禁恶意攻击对接指南

智能体记忆系统与知识库存储运行运维说明

宝藏阁智能体对外接入与OpenClaw集成指南

8.4 返回 `Failed to parse URL from /api/admin/apikeys`