---
url: /docs/agentbuff-stack/support-chat.md
---
# 可选客服聊天

I14 首版采用 Crisp，默认关闭。产品公开页的联系入口和工作台的 Support 链接都进入 `/contact`；聊天只在该页主动点击后加载。工具页与私有工作台不嵌入聊天，模板官网仍保持独立。联系页支持英文；开启西班牙语后发布完整的 `/es/contact`，语言切换与工作台跳转使用相应路径。

## 配置

在 `packages/core/website.ts` 中设置：

```ts
metadata: {
  // 其他品牌字段保持原值
  supportEmail: "help@your-domain.com",
},
support: {
  provider: "crisp",
  enabled: false,
  websiteId: null,
},
```

要开启聊天，先在自己的 Crisp 工作区取得公开的 Website ID，将 UUID 填入 `websiteId`，再把 `enabled` 改为 `true`。它是公开站点标识，不是 API 密钥；不要把 REST API 凭据放在产品配置或前端。开启时必须同时填写真实支持邮箱，作为供应商异常时的联系方式。只需要邮箱时保持聊天关闭即可。

执行 `bun config:check` 后重建产品公开页和工作台。离线检查与公开页构建都会拒绝未知供应商、非 UUID 的站点标识、非法邮箱，以及开启但缺少标识或邮件回退的配置。原生成站合入新代码后，需补齐显式的 `support` 对象；没有新数据库迁移或 API 密钥。

没有支持邮箱且聊天关闭时，联系页显示暂不可用，保留 `noindex`，不会进入 sitemap。配置了邮箱后才作为正常联系页索引；开启第二语言时 canonical、hreflang 和 sitemap 对应实际译文，不发布空语言页面。译文来源为 Codex 草稿，人工审校继续列在语言模块的外部验收中。

## 按需加载与故障

页面初次打开只显示邮箱和聊天入口，不加载 Crisp 的第三方脚本。只有用户点击 Open chat 才使用固定的 `https://client.crisp.chat/l.js`。同一页面的并发点击复用一次加载，已经打开后关闭 / 重开继续复用该实例。

脚本下载完成不等于聊天窗口就绪。模板等待 SDK 会话事件，发起打开操作，再由窗口打开事件确认界面状态；15 秒仍未确认或脚本失败时显示失败并保留邮件入口。失败不会自动重试；用户可以重新加载页面后再次主动选择。超时后的迟到会话事件不会重新打开窗口。提示“已打开”不代表客服在线、消息送达或问题已经解决。

实现依据：[官方异步命令与事件](https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/)、[语言配置](https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/language-customization/)，核对日期为 2026-10-11。没有为其他供应商预建通用插件框架；发生真实切换需求时再调整。

## 内容与会话边界

模板不自动设置聊天姓名、邮箱、账号 / 团队 ID、付款信息、任务输入、文件名或结果，也不预填或发送消息。工作台链接和页脚联系链接不携带引用来源；联系页与脚本使用 `no-referrer`，主动加载前移除 URL 查询和片段。联系页不加载既有 Cloudflare 营销统计脚本。

用户主动打开后，Crisp 脚本仍能访问该联系页，并使用其自身网络、Cookie 与访客会话机制。因此界面明确说明连接供应商及可能使用聊天 Cookie，不能称为匿名统计或完全本地处理。当前不采用账号身份校验或跨设备会话连续性；同一浏览器可能恢复此前的访客对话。关闭窗口只关闭界面，不承诺停止供应商网络或删除远程记录；重新加载页面后不会自动再次加载。

站主上线前需在自己的隐私说明中写清供应商、实际 Cookie / 数据范围和联系方式，并核实真实工作区设置。模板不提供通用法律文本，也不把本地契约预览当作实际客服投递。用户手动填写消息的内容由其自行选择，验收程序不会向供应商发送消息。

## 新站与本地验收

`site:create` 在目标新站中将聊天重置为关闭、Website ID 重置为 `null`，同时清空原支持邮箱。连续复制测试使用已启用的来源配置，第二个站点不会继承原客服工作区或收件人。源站配置保持原样。

```bash
bun support:validate
bun support:validate --ui
```

验证器在忽略目录生成独立的开启 / 关闭、英 / 西双语构建，检查联系页、邮件回退、脚本加载边界与 sitemap。`--ui` 使用 `support.localhost:21316` 和受控的本地 SDK 协议，不连接真实 Crisp；临时页面通过内容安全策略限制为本地资源。第一次请求允许打开，第二次模拟脚本失败，第三次在真实 15 秒期限之后返回会话事件；按程序提示完成浏览器流程，再写入它提示的本地结束标记。程序检查请求次数、打开次数及无引用来源，随后停止并清理自己的文件和服务，不修改正常配置或数据库。

当前本地验收与真实外部验收分别记录在[迭代记录](./iteration-progress)。真实工作区的窗口显示、消息往返、Cookie 设置、浏览器限制及供应商故障恢复仍需在明确的测试环境验收；联盟营销的归因、付款 / 退款和结算保持 I14 后续范围。