实时人工交接

当访客在 AI 智能体那里遇到困难时，可以请求人工帮助并真正获得帮助 — 实时进行，使用您的团队已经用于阅读转录的相同对话菜单。

访客流程

1. 智能体（在帮助中心垂直领域，或通过您配置的精选答案）在其回复中显示一个 Connect me with a human 药丸按钮。
2. 访客点击药丸按钮。两件事立即发生：
   • 对话在服务器上标记有 human_requested_at 时间戳。
   • 潜在客户捕获表单打开，以便访客留下他们的电子邮件 — 如果他们在操作员加入之前导航离开，这很有用，这样您的团队可以进行离线跟进。
3. 小部件显示 "Connecting you with someone…" 横幅。 在操作员认领对话之前，机器人保持静默 — 每个后续访客消息都被排队等待操作员， 而不是获得 LLM 回复。
4. 当操作员认领时，横幅翻转为 "Sarah joined the chat" （或 "An agent joined" 如果您在工作区设置中关闭了个性化 — 见下文）。
5. 操作员的回复以内联聊天气泡的形式出现，带有 "Operator" 标签。 访客的消息实时流回操作员的控制台（3 秒轮询）。

操作员流程

1. Conversations 侧边栏条目显示一个红色徽章，其中包含等待人工的对话数量。
2. 打开 /app/conversations 并切换到 Needs human 过滤器药丸。 每行显示访客点击人工按钮的时间、他们所在的页面以及他们捕获的电子邮件（如果有）。
3. 点击一行 → 线程显示实时消息。点击右上角的 Claim 以接管对话。
4. 当您认领对话时：
   • 机器人将不会自动响应。
   • 使用底部的回复框（Cmd / Ctrl + Enter 发送）。
   • 访客消息实时出现 — 当您认领时，页面每 2 秒轮询一次。
5. 完成后点击 Release。机器人在下一个访客消息时恢复； 对话历史保持不变以供分析和未来参考。

工作区设置

一些旋钮位于工作区级别的 Settings 中：

• Live chat personalize（默认开启）。开启时，访客在加入横幅中看到操作员的真实姓名。 为受监管行业（法律、医疗保健、金融）关闭它，其中不应暴露个别操作员身份 — 访客看到 "An agent from <Brand>"。

通知

每个捕获的潜在客户都会触发现有的通知级联（潜在客户捕获电子邮件、仪表板 sonner toast、 选择加入成员的浏览器推送）。当访客请求人工时应用相同的触发器 — 潜在客户表单触发是规范信号。

智能路由（第 2 阶段）

当访客点击 Connect me with a human 时，服务器根据操作员可用性和您的营业时间 选择三种响应之一：

• Queued. 操作员在线且在您的营业时间内。访客看到 "Connecting you with someone…"，对话被标记，机器人在认领之前保持静默。
• Offline — no operators around. 在营业时间内但没有人 在他们的个人资料中标记自己 Receive live chats（或没有打开管理员标签页）。 访客看到 "No one's around right now — drop your email and we'll reach out." 对话不会被标记；机器人在访客的下一个消息时正常恢复。
• Offline — after hours. 在您配置的营业时间之外。 访客看到 "We're closed right now. We're back <day at time>. Drop your email and we'll follow up first thing."

操作员选择加入

每个工作区成员在 Profile settings 中单独设置他们的可用性：

• Receive live chats 复选框 — 开启时 AND 您的管理员标签页在过去 2 分钟内处于活动状态， 您算作可用操作员。
• 当标签页在前台时每 60 秒触发一次心跳，当标签页隐藏时暂停。

营业时间

在 Settings → Live chat 中配置。 暂时使用 JSON 编辑（可视化网格编辑器将在下一个版本中发布）：

{
  "enabled": true,
  "timezone": "America/New_York",
  "schedule": {
    "monday":    [{"start": "09:00", "end": "17:00"}],
    "tuesday":   [{"start": "09:00", "end": "17:00"}],
    "wednesday": [
      {"start": "09:00", "end": "12:00"},
      {"start": "13:00", "end": "17:00"}
    ],
    "thursday":  [{"start": "09:00", "end": "17:00"}],
    "friday":    [{"start": "09:00", "end": "17:00"}],
    "saturday":  [],
    "sunday":    []
  }
}

• 天键小写。24 小时制 HH:mm。空数组 = 全天关闭。
• 支持每天多个窗口（例如午休时间）。
• 时区是任何 IANA 标识符 — 服务器针对 PHP 的 tz 数据库进行验证。
• 设置 "enabled": false（或留空整个字段）以保持始终开启。

Slack / Teams 通知

在 Settings → Live chat 中， 粘贴任一平台的 incoming-webhook URL。当访客请求人工时，排队的监听器会触发一个紧凑的 ping， 其中包含对话 URL，以便操作员可以直接从 Slack / Teams 跳入而无需打开仪表板。

• Slack — 使用 Slack 应用配置中的标准 incoming-webhook URL。 Slack 自动展开对话链接。
• Microsoft Teams — 来自 Teams 频道连接器的 incoming-webhook URL。 我们作为带有 "Open conversation" 按钮的 MessageCard 发布。

未认领对话的自动回退

访客不应该永远停留在 "Connecting you…" 气泡上。一个计划任务每分钟运行一次， 并清除任何等待超过 5 分钟而没有认领的对话的 human_requested_at 标志。 机器人放下一个关闭说明（"Looks like everyone's busy at the moment — leave your email and we'll follow up"） 并恢复自动回复。

操作员优化（第 3 阶段）

预设回复

保存您的团队反复输入的回复（密码重置说明、退款政策、运输 ETA），位于 Settings → Canned replies。 每个条目都有一个短标签（操作员搜索的内容）和完整的回复文本。 使用向上/向下手柄重新排序 — 最常用的回复应该位于顶部。

在任何实时对话中，点击文本区域上方的 Canned reply 按钮。 模糊搜索标签或内容，选择一个，文本区域就会填充。操作员可以在点击发送之前编辑。

内部注释

将回复框从 Reply 切换到 Internal note（文本区域变成琥珀色）。 内部注释对对话线程中的其他操作员可见，但永远不会发送给访客。 对于交接上下文很有用："Visitor seems frustrated — I tried X already, please pick up." 自动生成的转移审计消息也使用此角色。

打字指示器

两个方向，无需设置：

• 当您在操作员控制台中输入时，访客在他们的聊天上方看到 "<Operator> is typing…"。
• 当访客在小部件中输入时，操作员在消息日志中看到一个三点气泡。

实现为 5 秒自过期服务器端时间戳；双方轮询现有端点，因此不需要额外的基础设施。

对话转移

点击回复栏中的 Transfer 按钮。在线队友显示在顶部，带有绿色 "Online" 徽章； 离线队友仍然列出（您可能想要移交给稍后会认领的人）。选择目标会重新分配认领， 广播到访客的小部件，以便 "joined the chat" 横幅刷新到新操作员的姓名， 并在线程中放下一个系统注释以供上下文。

营业时间网格编辑器

第 2 阶段的 JSON 文本区域被 Settings → Live chat 中的可视化 7 天网格取代。点击任何一天的 "+ Window" 按钮以添加另一个开放块（午休时间、轮班拆分）， 或检查 "Closed" 以休息那天。时区选择器有 15 个最常见的 IANA 区域以及用于 PHP 识别的任何区域的 "Custom…" 选项。

标签 + 评分 + UI 重建（第 4 阶段）

对话标签

对对话进行分类，以便您的团队可以过滤和报告它们。 在 Settings → Tags 管理列表： 每个标签都有一个标签（最多 60 个字符）和一个十六进制颜色，用于驱动芯片背景。

在任何对话线程中，末端侧面板有一个 Tags 部分。点击芯片的 × 以分离； + Tag 打开未选择的工作区标签的模糊搜索下拉菜单。

对话列表：一个 "Tags" 选择下拉菜单加入现有的 Needs human / Live now 过滤器药丸。 每行还将应用的标签显示为紧凑芯片，与现有徽章一起。

满意度评分

操作员释放对话后，访客看到一个 "Was this helpful?" 提示，带有点赞/点踩按钮 + 可选评论字段。 第一个评分在服务器端锁定；后来的提交仅更新评论 — 买家抱怨 Intercom 风格的 "rating overwritten" 惊喜。

操作员端：末端窗格上下文面板在访客卡片下显示评分 + 评论。 对话列表还在每行存在评分时显示 👍 / 👎 芯片。

对话线程 UI 重建

线程页面现在是一个真正的帮助台表面：

• 双窗格布局 在桌面（≥ md）上 — 左侧聊天，右侧上下文侧边栏。 侧边栏在移动设备上折叠到带有 "Details" 按钮的 Sheet 抽屉中。
• 右窗格侧边栏 部分：访客（匿名 ID、语言、返回标志、带链接图标的页面 URL）、 潜在客户（电子邮件 mailto / 电话 tel: 链接）、标签、满意度信号、计时瓷砖（认领年龄 / 等待时间 / 开始时间）。
• 紧凑统一操作栏 在顶部：实时药丸、状态徽章、claim / release / force-release 按钮在一个集群中。
• Composer 保持在底部，带有 Reply / Note 标签、预设回复选择器、转移下拉菜单和打字去抖动器（全部从第 3 阶段继承）。

已发布的路由（累积）

• POST /app/conversations/{id}/note — 内部注释
• POST /app/conversations/{id}/typing — 操作员打字提示
• POST /app/conversations/{id}/transfer — 重新分配认领
• POST / DELETE /app/conversations/{id}/tags/{tagId} — 附加 / 分离标签
• POST /api/v1/widget/typing — 访客打字提示（JWT）
• POST /api/v1/widget/satisfaction — 访客评分（JWT）
• GET / POST / PATCH / DELETE /app/settings/canned-replies/… — CRUD + 重新排序
• GET / POST / PATCH / DELETE /app/settings/tags/… — 工作区标签 CRUD