人工客服（即时）
用户在与某智能体对话时，若希望 马上有人在线协助，可点 「人工客服」；由该智能体 事先指定的客服同事 在工作台接单，并在同一对话中（嵌入）或通过 联络（主站）继续沟通。这是 即时 通道，有排队与约等提示。
来源 docs/core-mechanisms/人工客服.md
表述：用户在与某智能体对话时，若希望 马上有人在线协助，可点 「人工客服」；由该智能体 事先指定的客服同事 在工作台接单，并在同一对话中（嵌入）或通过 联络（主站）继续沟通。这是 即时 通道，有排队与约等提示。
不要求马上等到真人时，应引导用户使用 工单（异步留言），见 工单.md。用户文案中 勿 将即时协助称作「工单」。
实现对照：user_agent_cs_config、user_agent_cs_staff、cs_tickets（即时会话）、cs_ticket_messages；路由 /api/v1/user-agents/{id}/human-support、/api/v1/workspaces/{id}/cs-tickets、/api/v1/embed/cs-tickets；Web 页面 /customer-service（CustomerServiceWorkbenchPage · 即时客服 分段）。
1. 与其它能力的分工
| 能力 | 谁发起 | 谁处理 | 界面 |
|---|---|---|---|
| 帮助智能体 / 工作智能体 | 用户 | 大模型自动回复 | 消息、操作助手 |
| 即时人工客服 | 用户（希望马上有人聊） | 本区席位 或已授权的 客服小组 | 人工客服；工作台 即时客服 |
| 工单（异步） | 用户（可不急） | 同一批客服稍后处理 | 提交工单；工作台 工单；见 工单.md |
| 联络（IM） | 任何人 | 真人互聊 | 消息 侧栏 IM；主站即时接单后内嵌联络 |
| 服务通知 | 系统 | 只读触达 | 消息 置顶「服务通知」 |
人工客服 不是 把工作区管理员默认当作客服；管理员若无席位，仅可在功能菜单进入工作台做配置与 oversight，日常接单由 席位同事 或已授权的 客服小组 完成。
2. 按智能体配置
每个可对外服务的智能体（含工作区 帮助智能体 占位 __builtin_assistant__）可单独配置：
| 配置项 | 说明 |
|---|---|
| 开启人工客服 | 关闭时，用户对话中 不显示「人工客服」「提交工单」 |
| 客服席位 | 本区成员，可多选。也可不勾本区人员，改为授权 客服小组（见 §9） |
| 席位在岗状态 | 每位席位自行切换：上班 / 休息中 / 下班。仅 上班 计入即时人工可用；无人上班时客户侧 不提供即时人工客服，引导 提交工单。每次进入「上班」会记录开始时间，离开「上班」（休息或下班）记录结束时间。小组工作台 下点上班，会写入该小组当前服务范围内的各客户区 |
| 待接单提示音 | 内置若干种；按智能体配置。客服同事在运营台轮询到该智能体 即时 新待接单时播放（工单通知可弱于即时，首版可复用席位通知并标明工单） |
谁可以配置
| 智能体 | 配置人 |
|---|---|
| 用户自建智能体 | 该智能体 创建者，或工作区 管理员 |
| 帮助智能体 | 仅工作区 管理员（在工作区协作 → 客服队列 → 本区客服 配置） |
配置入口：
- 我的智能体 → 管理 → 人工客服（自建智能体）
- 工作区协作 → 客服队列（帮助智能体，管理员；页内 本区客服 分段）
3. 用户侧流程（即时）
- 用户在与 已开启人工客服 的智能体对话（消息、操作助手或 网站嵌入）。
- 快捷条出现 「人工客服」 与 「提交工单」。若当前 没有席位上班，则不提供即时入口，并提示改用 提交工单。
- 点「人工客服」（须有人上班）：可先由大模型根据近几轮对话整理诉求，用户确认后提交。
- 系统创建 即时客服会话（绑定
user_agent_id），进入 排队（展示前面人数与约等时间），并向席位发通知。 - 座席接单后在同一对话中沟通；用户可 结束本次客服（排队中=取消排队；沟通中=结束会话）。
- 结束后会话记录 留在当前智能体对话中继续展示；用户可 五星评价（≤3 星可附原因，供座席绩效与知识改进）。
- 不愿等待时可 「不等了，改提工单」，转为异步工单。
同一访客/用户、同一工作区、同一智能体下，若已有进行中的 即时 会话，再次提交会提示已有进行中的请求。
主站用户还可在 工作区协作 → 客服队列 查看自己的即时请求；待接单时可撤回。
4. 客服侧流程（工作台 · 即时）
路径：顶栏「客服」（仅 客服席位 或 客服小组成员 显示）或 功能菜单 → 客服工作台。
工作台同一页，顶栏一行：左侧标题「客服工作台」；右侧为范围组合框（仅小组成员）、在岗状态、刷新。
左侧导航（与技能中心同类）：
| 分段 | 内容 |
|---|---|
| 即时客服 | 待接单 / 我负责的 / 进行中 / 已完结 |
| 工单 | 异步工单队列（见 工单.md） |
| 服务时段 | 上班起止记录（管理员看本区全员；小组工作台看本人在服务范围内的记录） |
右侧为当前分段的详情与对话。主站接单后在页内 联络；嵌入来单走即时消息线程。操作：接单、标记完结。
若你属于客服小组，右侧组合框可在 本区客服 与 小组工作台 之间切换（默认本区客服）。小组工作台只列出该组 已选且已获授权 的客户队列，不是全站所有工作区。在小组工作台接另一客户的单时，不要切换顶栏当前工作区。
5. 顶栏入口规则
| 用户身份 | 顶栏独立「客服」按钮 | 功能菜单「客服工作台」 |
|---|---|---|
| 客服席位 | 显示；有待接单时带角标 | 不重复显示 |
| 客服小组成员 | 显示（即使当前工作区不是本区席位） | 不重复显示 |
| 工作区管理员（非席位、非小组成员） | 不显示 | 显示 |
| 普通成员 | 不显示 | 不显示 |
席位判定：GET /api/v1/me/cs-staff-status → { is_staff, is_group_member, presence, … }。 在岗切换：PUT /api/v1/me/cs-staff-presence → { presence, scope: current|group }（默认 current，现网行为不变）。
6. 即时会话状态
| 状态 | 用户可见 | 客服可见 |
|---|---|---|
| waiting（排队中） | 见队位；可取消 / 改提工单 | 可接单 |
| assigned（沟通中） | 可见处理人；可结束 | 负责客服可回复、完结 |
| resolved（已结束） | 记录常驻；可评分 | 只读 |
| closed（已取消排队） | 只读 | — |
ended_by：staff | customer | cancel。
7. API 摘要（实现）
| 方法 | 路径 | 说明 | |
|---|---|---|---|
| GET/PUT | /api/v1/user-agents/{id}/human-support | 配置 | |
| GET | /api/v1/user-agents/{id}/human-support/status | { enabled, live_available, tickets_available } | |
| GET | /api/v1/me/cs-staff-status | 是否本区席位 / 小组成员 + 在岗状态 | |
| PUT | /api/v1/me/cs-staff-presence | `{ presence, scope: current\ | group }` |
| GET | /api/v1/me/cs-group/desk | 小组工作台即时队列（仅已授权且列入范围的客户） | |
| GET | /api/v1/me/cs-group/desk/cases | 小组工作台工单队列 | |
| GET | /api/v1/me/cs-group/duty-sessions | 小组工作台服务时段 | |
| GET/POST/PATCH | /api/v1/workspaces/{id}/cs-group | 本队客服小组（创建 / 改名） | |
| PUT | /api/v1/workspaces/{id}/cs-group/members | 本队队员 | |
| PUT | /api/v1/workspaces/{id}/cs-group/scope | 服务范围 | |
| POST | /api/v1/workspaces/{id}/cs-group/grants | 本队向客户申请服务 | |
| GET/POST | /api/v1/workspaces/{id}/cs-group-grants | 客户区列出授权 / 用小组编号邀请 | |
| POST | …/cs-group-grants/{grantId}/approve 等 | 批准、拒绝、撤销 | |
| GET | /api/v1/cs-groups/{groupId}/preview | 按小组编号预览（邀请前） | |
| GET | /api/v1/me/cs-staff-duty-sessions | 本人上班时段列表 | |
| GET | /api/v1/workspaces/{id}/cs-staff-duty-sessions | 管理员：全员客服服务时段（可 user_id 筛选） | |
| POST/GET | /api/v1/workspaces/{id}/cs-tickets | 提交 / 即时队列（含队位字段；无人上班时不可提交即时） | |
| POST | .../cs-tickets/{id}/claim | 接单 | |
| POST | .../cs-tickets/{id}/resolve | 座席完结 | |
| POST | .../cs-tickets/{id}/cancel | 取消排队（waiting） | |
| POST | .../cs-tickets/{id}/end | 客户结束（waiting/assigned） | |
| POST | .../cs-tickets/{id}/rating | 结束后评分 | |
| POST | /embed/cs-tickets 等 | 嵌入创建、active、for-session、消息、cancel/end/rating、convert-to-case |
通知：新即时会话 → 席位；接单/完结 → 请求用户（嵌入场景可跳过站内通知）。
8. 数据表（示意）
user_agent_cs_config/user_agent_cs_staffcs_groups/cs_group_members/cs_group_workspace_grants/cs_group_workspace_scopecs_tickets：即时会话；含队位计算字段（响应）、ended_by、评分列cs_ticket_messages：嵌入即时消息
帮助智能体 ID：__builtin_assistant__。
9. 客服小组（跨客户工作台）
一组客服服务多个客户工作区时，用 客服小组，而不是把某人当过席位的工作区全部加起来。
跨区接单须同时满足：
- 你是某客服小组的队员（本队工作区管理员加人；队员须为本队成员）
- 小组把该客户工作区列入 服务范围
- 该客户工作区管理员已 授权 这个小组
缺一则看不见该区队列、不能接单。授权 只给客服权，队员不必成为客户区成员，也看不到客户知识与协作内容。
配置：
- 本队：工作区协作 → 客服队列 → 我们的小组（创建、队员、申请服务、列入范围）
- 客户：工作区协作 → 客服队列 → 授权外来小组（批准申请、用小组编号邀请、撤销）
工作台默认仍是 本区客服；小组成员可在顶栏右侧切到 小组工作台。接其他客户的单时不切换顶栏当前工作区。
10. 相关文档
- 异步工单：
工单.md - 需求真值：
docs/产品规格.md§4.8 - 顶栏布局：
docs/界面与布局.md§3（A3-cs） - 用户帮助：
help/product-features/human-customer-service.md - 联络机制：
docs/core-mechanisms/统一对话与联络.md