让智能体，来到你的用户身边。

01 · 一行代码接入

将下面的 HOST 替换为本服务的域名，替换租户、项目和用户标识。右下角会出现对话图标。同源电脑浏览器点击后打开浮动对话框，手机或窄屏进入完整 H5 页面；跨站接入也进入完整页面，避免第三方 Cookie 限制导致身份失效。

<script src="https://HOST/widget.js" data-tenant-id="TENANT_ID" data-project-uuid="PROJECT_UUID" data-user-id="USER_ID" async></script>

02 · 用户身份与记忆

默认代码使用匿名身份：同一个浏览器、同一个项目和用户 ID 可以延续记忆。清除浏览器数据或更换设备后会建立独立身份。用户 ID 是标识，单独提供它不能验证用户身份。

如果需要已登录用户跨设备延续历史与记忆，在后台生成项目 API Key，由客户后端验证自己的用户登录状态后，向本服务换取身份凭证。请求中的 userId 必须来自已验证的登录会话。

POST https://HOST/api/v1/tokens
Authorization: Bearer YOUR_PROJECT_API_KEY
Content-Type: application/json

{
  "tenantId": "TENANT_ID",
  "projectId": "PROJECT_UUID",
  "userId": "YOUR_LOGGED_IN_USER_ID"
}

响应包含 token 和 expiresAt，凭证有效期为 15 分钟。将 token 传入嵌入代码的 data-token；每次用户进入时由客户后端重新获取。项目 API Key 仅存放在客户后端。

<script src="https://HOST/widget.js" data-tenant-id="TENANT_ID" data-project-uuid="PROJECT_UUID" data-user-id="USER_ID" data-token="SHORT_LIVED_TOKEN" async></script>

凭证通过地址片段传给 H5，不进入服务器访问日志；成功验证后会从地址栏移除。聊天会话有效期为 24 小时。历史和记忆按租户、项目、用户身份隔离；匿名和已验证身份各自独立，不自动合并。

03 · 知识与业务资料

在后台添加文本，或导入 TXT / Markdown 文件。首版每个项目支持 100 份资料，每份最多 60,000 个字符。服务会按当前问题的关键词检索相关片段，加入模型上下文。暂不支持 PDF 解析或向量检索。

业务资料接口为可选配置，不需要采集客户当前网页。配置后，仅在已验证用户对话时请求客户的公网 HTTPS JSON 接口，自动附带 tenantId、projectId 和 userId。projectId 为当前智能体的 UUID，客户接口可按需使用或忽略；如配置令牌，则使用 Authorization: Bearer 传递。接口超时、失败或未配置时，对话仍可进行。

GET https://api.customer.com/agent-context?tenantId=TENANT_ID&projectId=PROJECT_UUID&userId=USER_ID
Authorization: Bearer YOUR_CONTEXT_TOKEN
Accept: application/json

响应示例：
{"membership":"普通会员","preferredCategory":"户外用品"}

接口应只返回当前用户对话所需的资料，并在客户系统中校验访问权限。响应大小限制为 32 KB，请求超时为 8 秒；不访问内网地址，不跟随重定向。

04 · 业务跳转

在后台「业务引导」配置引导名称、使用场景和 HTTPS 地址，每条引导可选择或编辑展示方式：常驻按钮以卡片式按钮固定显示在聊天输入框上方，多个入口可横向浏览；按需卡片不常驻显示，由智能体在需求匹配时通过工具调用生成。按需卡片必须填写使用场景。卡片随回复保存，用户点击「确认前往」后才打开客户网站，不会自动跳转。已有引导默认使用常驻按钮。删除引导后，历史卡片保留但不可再跳转。点击后附带以下关联参数，已有其他查询参数会保留。

https://customer.com/orders?tenantId=TENANT_ID&projectId=PROJECT_UUID&userId=USER_ID

这些参数用于业务关联，不是登录凭证。客户网站应使用自身的登录和权限校验。当前版本仅负责引导，不创建订单、不发起支付，也不自动调用会改变客户业务数据的接口。

05 · 本地体验

进入后台“一行接入”，点击“体验悬浮入口”即可验证完整跳转。点击“预览对话”则以工作空间专用预览身份进入，不与真实终端用户混用。

“接入与 API”中的“联调测试”页面可逐项验证：以 debug_ 测试用户模拟已登录或匿名身份并检查切换后的数据隔离，发送测试消息查看流式响应与失败原因，核对每个业务跳转携带的 tenantId、projectId、userId，模拟从客户网站返回对话，并诊断客户后端换取的 data-token。测试数据可一键清除，不影响真实用户。