网页聊天 Widget、SSE 与 Origin 白名单

聊天入口把一条触发路由公开为网页组件。entry_key 会出现在页面源码中，这是设计预期；安全边界来自入口状态、限速、Origin 白名单、可信身份票据和业务最终授权，而不是隐藏入口标识。

最小接入

<script src="https://<你的中枢>/widget.js" data-entry="<entry_key>" async></script>

在控制台为入口绑定路由，并配置标题、开场白、外观、上传能力和可嵌入站点。匿名访客可以继续同一段会话，但浏览器生成的 visitor_id 不是可信业务身份；需要调用受身份约束的工具时，业务后端必须从当前登录态签发短期票据。

Origin 白名单

每项必须是精确的 scheme://host[:port]，不能带路径、查询参数、用户信息或通配符。
空数组表示不限制浏览器来源，不表示“拒绝全部”。
携带 Origin 的浏览器请求不匹配时，在创建业务任务前返回 403。
小程序和服务端调用通常不携带浏览器 Origin，因此不受这道门禁限制；它们需要使用自己的签名、票据或服务端鉴权。

Origin 白名单用于防止其他网站直接盗嵌，不是登录、租户隔离或业务权限机制。

默认展开

appearance.default_open 默认是 false，页面加载后显示气泡。设为 true 后，已有官方嵌入脚本无需修改即可加载时展开；脚本上的 data-open="1" 仍可对当前嵌入强制展开。

SSE 结果流

POST /chat/:entry_key 创建任务并返回 job_id。
客户端连接 GET /chat/:entry_key/events/:job_id。
open/status/phase/delta 可用于临时展示；reset 要求丢弃尚未完成的文本。
只有 done.reply 是权威终态；timeout 只表示本次连接窗口结束，不证明任务失败。
断线恢复可使用 Last-Event-ID，最终历史仍以服务端任务和对话总账为准。

自建客户端必须支持 reset，也不能把已经收到的 delta 当成业务完成证据。

固定版本参考