type EmbedChannel struct {
    ID                     string         // UUID 主键
    TenantID               uint64         // 所属租户
    AgentID                string         // 绑定的 Agent（默认 builtin-quick-answer）
    Name                   string         // 渠道名称
    Enabled                bool           // 是否启用
    PublishToken           string         // 长效发布令牌，"em_" 前缀
    AllowedOrigins         JSON           // 允许的来源 Origin 列表（JSONB）
    WelcomeMessage         string         // 欢迎语
    RateLimitPerMinute     int            // 单 IP 每分钟限流（默认 30）
    RateLimitPerDay        int            // 渠道级每日限流（默认 10000）
    PrimaryColor           string         // 主题色
    PageTitle              string         // 页面标题
    HeaderTitleMode        string         // "channel" | "session"
    ShowSuggestedQuestions bool           // 推荐问题开关
    WidgetPosition         string         // 挂件位置
    AllowWebSearch         bool           // 允许联网搜索
    AllowFileUpload        bool           // 允许文件/图片上传
    DefaultLocale          string         // 默认语言
    WebhookURL             string         // 出站 webhook（HTTPS）
    WebhookSecret          string         // HMAC-SHA256 签名密钥
    ...
}

embed := r.Group("/api/v1/embed/:channel_id", middleware.EmbedAuth(embedService, tenantService, redisClient))
{
    embed.POST("/exchange", embedHandler.ExchangeEmbedSession)
    embed.GET("/config", embedHandler.GetEmbedConfig)
    embed.GET("/suggested-questions", embedHandler.GetEmbedSuggestedQuestions)
    embed.GET("/chunks/:chunk_id", embedHandler.GetEmbedChunk)
    embed.POST("/sessions", embedHandler.CreateEmbedSession)
    embed.POST("/knowledge-chat/:session_id", embedHandler.EmbedKnowledgeChat)
    embed.POST("/agent-chat/:session_id", embedHandler.EmbedAgentChat)
    embed.GET("/messages/:session_id/load", embedHandler.EmbedLoadMessages)
    embed.POST("/sessions/:session_id/stop", embedHandler.EmbedStopSession)
    embed.POST("/sessions/:session_id/events", embedHandler.EmbedRelayWebhookEvent)
    // 消息推荐问题、MCP OAuth、工具审批、文件服务等路由略
    embed.GET("/files", newFileServeHandler(...))
}

{ "success": true, "data": { "session_token": "ems_...", "expires_in": 1800 } }

{ "success": true, "data": { "id": "<session_uuid>", "sig": "<HMAC-SHA256 base64>" } }

<script
  src="https://your-weknora.example.com/weknora-widget.js"
  data-channel="你的渠道UUID"
  data-token="em_你的publish_token"
  data-position="bottom-right"
  data-primary-color="#07C05F"
  data-title="AI Assistant"
></script>

<script
  src="https://your-weknora.example.com/weknora-widget.js"
  data-channel="你的渠道UUID"
  data-token-endpoint="https://your-backend.example.com/weknora/embed-token"
  data-position="bottom-right"
></script>

<script src="https://your-weknora.example.com/weknora-widget.js"></script>
<script>
  WeKnora.init({
    channel: '渠道UUID',
    tokenEndpoint: 'https://your-backend.example.com/weknora/embed-token', // 或 token: 'em_...'
    position: 'bottom-right',
    primaryColor: '#07C05F',
    title: 'AI Assistant',
    baseUrl: 'https://your-weknora.example.com',
  });
  WeKnora.setContext({ userId: 'u_123', page: location.pathname }); // 上下文随每次提问注入
  WeKnora.setLocale('en-US');
  WeKnora.openWithQuery('如何重置密码？');   // 打开面板并自动发送提问
  WeKnora.on('ready', () => console.log('widget ready'));
  // 其他：WeKnora.open() / close() / toggle() / destroy() / off(event, fn)
</script>

<iframe src="https://your-weknora.example.com/embed/渠道UUID"
        width="400" height="600" style="border:none"></iframe>

sequenceDiagram
    autonumber
    participant Visitor as "访客浏览器"
    participant Host as "宿主页面 (weknora-widget.js)"
    participant Backend as "站长后端 (安全模式可选)"
    participant Iframe as "嵌入页 SPA (/embed/:channel_id)"
    participant API as "WeKnora API (/api/v1/embed/:channel_id)"
    participant Webhook as "站长 Webhook"

    Visitor->>Host: 加载页面, script 标签自动初始化
    Host->>Iframe: 创建 iframe (悬浮面板)
    Iframe-->>Host: postMessage "bootstrap_request"
    alt 安全模式 (data-token-endpoint)
        Host->>Backend: GET /weknora/embed-token
        Backend->>API: POST /exchange (Authorization: Embed em_...)
        API-->>Backend: "{ session_token: ems_..., expires_in: 1800 }"
        Backend-->>Host: "{ token: ems_... }"
    else 静态模式 (data-token)
        Note over Host: 直接使用页面内的 em_ token
    end
    Host-->>Iframe: postMessage "provide_token"
    Iframe->>API: GET /config (Authorization: Embed token)
    API-->>Iframe: "EmbedChannelPublicConfig (无任何密钥)"
    Iframe->>API: POST /sessions
    API-->>Iframe: "{ id, sig (HMAC-SHA256) }"
    Note over Iframe: session id + sig 存入 localStorage
    Visitor->>Iframe: 输入问题
    Iframe->>API: POST /agent-chat/:session_id (X-Embed-Session: sig)
    API-->>Webhook: 异步 POST message_sent (X-WeKnora-Signature)
    API-->>Iframe: SSE 流式回复
    API-->>Webhook: 异步 POST message_received
    Iframe-->>Host: postMessage "message_received"