@csntgao/uni-base 0.6.2 → 0.6.5

package/AGENTS.md

@@ -180,13 +180,13 @@ pnpm --filter @uniplat/ai-employee-web-components pack
 5. 用户输入始终通过宿主 transport 的 HTTP 能力发送，不通过 WebSocket 发送。
 6. `4401` 仅表示 JWT 无效或过期，需要重新调用 `getAccessToken()` 并退避重连；`4400` 和 `4403` 是不可自动恢复的协议或权限错误。`1013` 以及认证帧中的 `SERVICE_*`、`KANBAN_AUTH_FAILED`、`REALTIME_UNAVAILABLE` 表示服务暂不可用，最多退避重连 3 次，不能误报为凭证失效。
 7. 重连前优先通过 HTTP 恢复历史；历史恢复失败时才请求 WebSocket replay 兜底。
-8. 实时消息必须按稳定 ID 去重，并忽略其他 session 的事件。
+8. 实时消息必须按稳定 ID 去重，并忽略其他 session 的事件。服务端缺少消息 ID 时的合成 ID 只能取消息本身，不得把 JSON Patch 的 `path`/`op` 等投递信封算进指纹，否则同一条消息经 replay 与实时两条路径会得到不同 ID 而重复显示。本地已发送的用户消息在回声窗口内不消费匹配条目，replay 与实时的多次回声都要挡住；首条消息与后续消息都必须登记该窗口。
 9. 主动断开和销毁后不得遗留 socket、心跳、重连任务或事件监听。
 10. 未指定既有 `sessionId` 时，打开抽屉和点击“开启新对话”只能建立本地草稿，不得创建后端空 Session。首条消息必须通过 `createSessionWithFirstMessage()` 原子提交 `request_id + ae_code + agent_code + content + trusted_context + attachments`；失败重试同一操作必须复用原 `request_id`，成功后才绑定服务端返回的 Session 并订阅实时通道。已有 Session 的后续消息继续使用 `sendMessage(sessionId, content)`。
 
 `ai_employee` channel、`session_message`、`session_title_updated`、订阅帧字段以及关闭码都是后端契约，不要仅为前端命名一致性自行修改。
 
-人工客服使用同一个 `/api/user-realtime/ws`，但必须单独请求并订阅 `customer_support` channel；不得把客服会话并入 `ai_employee` 状态机。客服 HTTP transport 复用 HR-SaaS `customer_support_api` 的 `user_session_page`、`user_session_create`、`user_message_page`、`user_message_send` 和 `user_mark_read`。首条用户消息必须通过 `user_session_create.initial_message` 原子创建客服会话，不得先创建空会话再发送。点击“转人工”应释放数字员工连接并在同一抽屉切换到 `<uniplat-customer-support-chat>`；不得再向数字员工发送模拟转人工文本，也不得要求 Host 拼装第二个抽屉。未显式配置 `customerSupport` 时，数字员工组件必须复用自身的 `realtimeUrl`、`transport.getAccessToken()` 与同源 `/api/general/project/hr_saas/service/customer_support_api`；只有非标准网关或独立鉴权场景才要求 Host 覆盖。
+人工客服使用同一个 `/api/user-realtime/ws`，但必须单独请求并订阅 `customer_support` channel；不得把客服会话并入 `ai_employee` 状态机。客服 HTTP transport 复用 HR-SaaS `customer_support_api` 的 `user_session_page`、`user_session_create`、`user_session_handoff_create`、`user_message_page`、`user_message_send` 和 `user_mark_read`。首条用户消息必须通过 `user_session_create.initial_message` 原子创建客服会话，不得先创建空会话再发送。职责越界动作的转接必须通过 `user_session_handoff_create` 原子创建客服会话，只提交来源数字员工会话 ID 和服务端生成的动作 UUID；客户端不得提交 `ae_code`、`agent_code`、组织、用户或角色作为权限依据。点击“转人工”应释放数字员工连接并在同一抽屉切换到 `<uniplat-customer-support-chat>`；不得再向数字员工发送模拟转人工文本，也不得要求 Host 拼装第二个抽屉。未显式配置 `customerSupport` 时，数字员工组件必须复用自身的 `realtimeUrl`、`transport.getAccessToken()` 与同源 `/api/general/project/hr_saas/service/customer_support_api`；只有非标准网关或独立鉴权场景才要求 Host 覆盖。
 
 ## 安全要求
 
@@ -224,10 +224,12 @@ chat.open(initialMessage?)
 
 `initialMessage` 是可选字符串；非空时由组件在初始化成功后通过既有消息发送链路自动发送：未配置 `sessionId` 时使用 `createSessionWithFirstMessage()` 原子创建会话并提交首条消息，已配置 `sessionId` 时使用 `sendMessage()` 作为该会话的后续消息。Host 不得代为创建会话或操作组件私有输入状态。未传、空字符串或纯空白时只打开抽屉，保持原有行为。
 
-不要把对象、回调或 token 改为 HTML attribute。`sessionId` 可选；传入时直接绑定已有会话，不传时组件只建立本地草稿。transport 必须提供 `createSessionWithFirstMessage()`，由 SDK 生成 UUID `request_id` 并在首条消息时一次性提交创建会话所需的数据；Host 只负责协议字段映射，不得先调用空 Session 创建接口。网络失败、组件重建或同一标签页刷新后，用户重试未改变的同一首条消息时复用原 `request_id`；默认恢复存储只允许包含 UUID 和输入摘要，不得保存消息正文、附件内容、JWT 或后端响应。成功响应中的 `sessionId/messageId/executionId/aeCode/agentCode/conversationType` 是唯一权威标识。`getOrCreateSession()/createSession()` 已从公开 transport 删除，不再保留旧空会话兼容分支。聊天组件初始关闭，Host 只负责配置并调用 `open()` 激活；固定右侧抽屉、标题、关闭按钮、消息区、输入区和转人工入口均由组件自身渲染，关闭时组件自行调用 `close()` 并释放实时连接。Host 不得再包裹重复抽屉或拼装抽屉内部界面。标题左侧会话入口由组件内部切换到原型“我的会话”视图；真实列表复用 transport 的可选 `listSessions()`，选择后由组件调用 core `bindSession()`，可选 `markSessionRead()` 更新已读状态。当前选定会话始终视为已读，在聊天界面和“我的会话”列表中都不显示未读角标，也不计入标题入口的聚合未读数；历史加载完成、列表加载完成、当前会话收到实时消息以及从会话列表返回时，组件应立即清除该会话本地未读并异步同步 Host，失败后在下一次触发时重试。历史消息与列表响应使用不同消息 ID 时，以列表返回的 `latestMessageId` 再次同步，不得让当前会话重新出现未读角标；其他未选定会话的新消息仍应计为未读。
+不要把对象、回调或 token 改为 HTML attribute。`sessionId` 可选；传入时直接绑定已有会话，不传时组件只建立本地草稿。transport 必须提供 `createSessionWithFirstMessage()`，由 SDK 生成 UUID `request_id` 并在首条消息时一次性提交创建会话所需的数据；Host 只负责协议字段映射，不得先调用空 Session 创建接口。网络失败、组件重建或同一标签页刷新后，用户重试未改变的同一首条消息时复用原 `request_id`；默认恢复存储只允许包含 UUID 和输入摘要，不得保存消息正文、附件内容、JWT 或后端响应。成功响应中的 `sessionId/messageId/executionId/aeCode/agentCode/conversationType` 是唯一权威标识。`getOrCreateSession()/createSession()` 已从公开 transport 删除，不再保留旧空会话兼容分支。聊天组件初始关闭，Host 只负责配置并调用 `open()` 激活；固定右侧抽屉、标题、关闭按钮、消息区、输入区和转人工入口均由组件自身渲染，关闭时组件自行调用 `close()` 并释放实时连接。Host 不得再包裹重复抽屉或拼装抽屉内部界面。标题左侧会话入口由组件内部切换到原型“我的会话”视图；真实列表复用 transport 的可选 `listSessions()`，选择后由组件调用 core `bindSession()`，可选 `markSessionRead()` 更新已读状态。已读同步只能使用服务端持久化消息 ID：HTTP 历史 `listMessages()` 与 `listSessions().latestMessageId` 返回的 ID 才可作为 `markSessionRead()` 的游标，实时事件里的 `ws_message_id` 与本地合成 ID 一律不得提交，服务端会以 `INVALID_ARGUMENT` 拒绝。本轮回复结束（`processing` 由真变假）且会话可见时应重新拉取历史，拿到持久化 ID 再同步已读。当前选定会话始终视为已读，在聊天界面和“我的会话”列表中都不显示未读角标，也不计入标题入口的聚合未读数；历史加载完成、列表加载完成、当前会话收到实时消息以及从会话列表返回时，组件应立即清除该会话本地未读并异步同步 Host，失败后在下一次触发时重试。历史消息与列表响应使用不同消息 ID 时，以列表返回的 `latestMessageId` 再次同步，不得让当前会话重新出现未读角标；其他未选定会话的新消息仍应计为未读。
 
 数字员工的 `assistant` 回复必须通过共享的安全 Markdown 渲染器展示；用户、系统和错误消息保持普通文本。Markdown 只能生成白名单结构，原始 HTML 必须作为文本转义，链接只允许 HTTP(S) 和 `mailto:`，不得直接注入未净化 HTML。
 
+数字员工最终回复尾部可以携带一个平台生成的 `assistant_action/open_customer_support` JSON 结构块。SDK 公共解析器只接受字段集合严格等于 `type/action/transaction-id/trigger/entry`、固定枚举值正确且 `transaction-id` 为 UUID4 的独立尾部 JSON；合法动作从展示文本和会话摘要中移除原始 JSON，并在对应 assistant 消息下渲染“发起人工客服”，非法、不完整、重复或夹在正文中的动作不得执行。动作不得按 `ae_code` 或 `agent_code` 分支。点击时调用客服 transport 的可选 `createHandoffSession({ sourceSessionId, actionTransactionId })`；加载中禁止并发提交，失败后以同一 UUID 重试，成功后使用接口返回的客服会话 ID 切换同一抽屉。动作 UUID 不得进入 DOM、公共事件、URL、日志或安全错误信息。
+
 工作台内置应用切换通过 Account Context 的 `workbench` 配置：
 
 ```ts
@@ -248,7 +250,7 @@ customerSupportChat.configure({
 })
 ```
 
-`transport` 负责客服会话列表、首条消息原子创建、历史消息、后续发送、已读同步与 `getAccessToken()`；真实 HR-SaaS 对接使用 `createHrSaasCustomerSupportTransport()`。组件初始关闭，由 Host 或数字员工组件调用 `open()`。组件自身拥有完整抽屉、会话列表、消息区、输入区和关闭行为。公开事件为 `ready`、`message-sent`、`message-received`、`connection-state-change`、`closed` 与 `error`，不得包含 JWT、transport 或后端原始异常。
+`transport` 负责客服会话列表、首条消息原子创建、职责越界交接、历史消息、后续发送、已读同步与 `getAccessToken()`；职责越界交接通过可选 `createHandoffSession()` 暴露，真实 HR-SaaS 对接使用 `createHrSaasCustomerSupportTransport()` 并映射 `user_session_handoff_create`。组件初始关闭，由 Host 或数字员工组件调用 `open()`。组件自身拥有完整抽屉、会话列表、消息区、输入区和关闭行为。公开事件为 `ready`、`message-sent`、`message-received`、`connection-state-change`、`closed` 与 `error`，不得包含 JWT、动作 UUID、transport 或后端原始异常。
 
 通知中心通过 JavaScript property 配置：
 

package/CLAUDE.md

@@ -180,13 +180,13 @@ pnpm --filter @uniplat/ai-employee-web-components pack
 5. 用户输入始终通过宿主 transport 的 HTTP 能力发送，不通过 WebSocket 发送。
 6. `4401` 仅表示 JWT 无效或过期，需要重新调用 `getAccessToken()` 并退避重连；`4400` 和 `4403` 是不可自动恢复的协议或权限错误。`1013` 以及认证帧中的 `SERVICE_*`、`KANBAN_AUTH_FAILED`、`REALTIME_UNAVAILABLE` 表示服务暂不可用，最多退避重连 3 次，不能误报为凭证失效。
 7. 重连前优先通过 HTTP 恢复历史；历史恢复失败时才请求 WebSocket replay 兜底。
-8. 实时消息必须按稳定 ID 去重，并忽略其他 session 的事件。
+8. 实时消息必须按稳定 ID 去重，并忽略其他 session 的事件。服务端缺少消息 ID 时的合成 ID 只能取消息本身，不得把 JSON Patch 的 `path`/`op` 等投递信封算进指纹，否则同一条消息经 replay 与实时两条路径会得到不同 ID 而重复显示。本地已发送的用户消息在回声窗口内不消费匹配条目，replay 与实时的多次回声都要挡住；首条消息与后续消息都必须登记该窗口。
 9. 主动断开和销毁后不得遗留 socket、心跳、重连任务或事件监听。
 10. 未指定既有 `sessionId` 时，打开抽屉和点击“开启新对话”只能建立本地草稿，不得创建后端空 Session。首条消息必须通过 `createSessionWithFirstMessage()` 原子提交 `request_id + ae_code + agent_code + content + trusted_context + attachments`；失败重试同一操作必须复用原 `request_id`，成功后才绑定服务端返回的 Session 并订阅实时通道。已有 Session 的后续消息继续使用 `sendMessage(sessionId, content)`。
 
 `ai_employee` channel、`session_message`、`session_title_updated`、订阅帧字段以及关闭码都是后端契约，不要仅为前端命名一致性自行修改。
 
-人工客服使用同一个 `/api/user-realtime/ws`，但必须单独请求并订阅 `customer_support` channel；不得把客服会话并入 `ai_employee` 状态机。客服 HTTP transport 复用 HR-SaaS `customer_support_api` 的 `user_session_page`、`user_session_create`、`user_message_page`、`user_message_send` 和 `user_mark_read`。首条用户消息必须通过 `user_session_create.initial_message` 原子创建客服会话，不得先创建空会话再发送。点击“转人工”应释放数字员工连接并在同一抽屉切换到 `<uniplat-customer-support-chat>`；不得再向数字员工发送模拟转人工文本，也不得要求 Host 拼装第二个抽屉。未显式配置 `customerSupport` 时，数字员工组件必须复用自身的 `realtimeUrl`、`transport.getAccessToken()` 与同源 `/api/general/project/hr_saas/service/customer_support_api`；只有非标准网关或独立鉴权场景才要求 Host 覆盖。
+人工客服使用同一个 `/api/user-realtime/ws`，但必须单独请求并订阅 `customer_support` channel；不得把客服会话并入 `ai_employee` 状态机。客服 HTTP transport 复用 HR-SaaS `customer_support_api` 的 `user_session_page`、`user_session_create`、`user_session_handoff_create`、`user_message_page`、`user_message_send` 和 `user_mark_read`。首条用户消息必须通过 `user_session_create.initial_message` 原子创建客服会话，不得先创建空会话再发送。职责越界动作的转接必须通过 `user_session_handoff_create` 原子创建客服会话，只提交来源数字员工会话 ID 和服务端生成的动作 UUID；客户端不得提交 `ae_code`、`agent_code`、组织、用户或角色作为权限依据。点击“转人工”应释放数字员工连接并在同一抽屉切换到 `<uniplat-customer-support-chat>`；不得再向数字员工发送模拟转人工文本，也不得要求 Host 拼装第二个抽屉。未显式配置 `customerSupport` 时，数字员工组件必须复用自身的 `realtimeUrl`、`transport.getAccessToken()` 与同源 `/api/general/project/hr_saas/service/customer_support_api`；只有非标准网关或独立鉴权场景才要求 Host 覆盖。
 
 ## 安全要求
 
@@ -224,10 +224,12 @@ chat.open(initialMessage?)
 
 `initialMessage` 是可选字符串；非空时由组件在初始化成功后通过既有消息发送链路自动发送：未配置 `sessionId` 时使用 `createSessionWithFirstMessage()` 原子创建会话并提交首条消息，已配置 `sessionId` 时使用 `sendMessage()` 作为该会话的后续消息。Host 不得代为创建会话或操作组件私有输入状态。未传、空字符串或纯空白时只打开抽屉，保持原有行为。
 
-不要把对象、回调或 token 改为 HTML attribute。`sessionId` 可选；传入时直接绑定已有会话，不传时组件只建立本地草稿。transport 必须提供 `createSessionWithFirstMessage()`，由 SDK 生成 UUID `request_id` 并在首条消息时一次性提交创建会话所需的数据；Host 只负责协议字段映射，不得先调用空 Session 创建接口。网络失败、组件重建或同一标签页刷新后，用户重试未改变的同一首条消息时复用原 `request_id`；默认恢复存储只允许包含 UUID 和输入摘要，不得保存消息正文、附件内容、JWT 或后端响应。成功响应中的 `sessionId/messageId/executionId/aeCode/agentCode/conversationType` 是唯一权威标识。`getOrCreateSession()/createSession()` 已从公开 transport 删除，不再保留旧空会话兼容分支。聊天组件初始关闭，Host 只负责配置并调用 `open()` 激活；固定右侧抽屉、标题、关闭按钮、消息区、输入区和转人工入口均由组件自身渲染，关闭时组件自行调用 `close()` 并释放实时连接。Host 不得再包裹重复抽屉或拼装抽屉内部界面。标题左侧会话入口由组件内部切换到原型“我的会话”视图；真实列表复用 transport 的可选 `listSessions()`，选择后由组件调用 core `bindSession()`，可选 `markSessionRead()` 更新已读状态。当前选定会话始终视为已读，在聊天界面和“我的会话”列表中都不显示未读角标，也不计入标题入口的聚合未读数；历史加载完成、列表加载完成、当前会话收到实时消息以及从会话列表返回时，组件应立即清除该会话本地未读并异步同步 Host，失败后在下一次触发时重试。历史消息与列表响应使用不同消息 ID 时，以列表返回的 `latestMessageId` 再次同步，不得让当前会话重新出现未读角标；其他未选定会话的新消息仍应计为未读。
+不要把对象、回调或 token 改为 HTML attribute。`sessionId` 可选；传入时直接绑定已有会话，不传时组件只建立本地草稿。transport 必须提供 `createSessionWithFirstMessage()`，由 SDK 生成 UUID `request_id` 并在首条消息时一次性提交创建会话所需的数据；Host 只负责协议字段映射，不得先调用空 Session 创建接口。网络失败、组件重建或同一标签页刷新后，用户重试未改变的同一首条消息时复用原 `request_id`；默认恢复存储只允许包含 UUID 和输入摘要，不得保存消息正文、附件内容、JWT 或后端响应。成功响应中的 `sessionId/messageId/executionId/aeCode/agentCode/conversationType` 是唯一权威标识。`getOrCreateSession()/createSession()` 已从公开 transport 删除，不再保留旧空会话兼容分支。聊天组件初始关闭，Host 只负责配置并调用 `open()` 激活；固定右侧抽屉、标题、关闭按钮、消息区、输入区和转人工入口均由组件自身渲染，关闭时组件自行调用 `close()` 并释放实时连接。Host 不得再包裹重复抽屉或拼装抽屉内部界面。标题左侧会话入口由组件内部切换到原型“我的会话”视图；真实列表复用 transport 的可选 `listSessions()`，选择后由组件调用 core `bindSession()`，可选 `markSessionRead()` 更新已读状态。已读同步只能使用服务端持久化消息 ID：HTTP 历史 `listMessages()` 与 `listSessions().latestMessageId` 返回的 ID 才可作为 `markSessionRead()` 的游标，实时事件里的 `ws_message_id` 与本地合成 ID 一律不得提交，服务端会以 `INVALID_ARGUMENT` 拒绝。本轮回复结束（`processing` 由真变假）且会话可见时应重新拉取历史，拿到持久化 ID 再同步已读。当前选定会话始终视为已读，在聊天界面和“我的会话”列表中都不显示未读角标，也不计入标题入口的聚合未读数；历史加载完成、列表加载完成、当前会话收到实时消息以及从会话列表返回时，组件应立即清除该会话本地未读并异步同步 Host，失败后在下一次触发时重试。历史消息与列表响应使用不同消息 ID 时，以列表返回的 `latestMessageId` 再次同步，不得让当前会话重新出现未读角标；其他未选定会话的新消息仍应计为未读。
 
 数字员工的 `assistant` 回复必须通过共享的安全 Markdown 渲染器展示；用户、系统和错误消息保持普通文本。Markdown 只能生成白名单结构，原始 HTML 必须作为文本转义，链接只允许 HTTP(S) 和 `mailto:`，不得直接注入未净化 HTML。
 
+数字员工最终回复尾部可以携带一个平台生成的 `assistant_action/open_customer_support` JSON 结构块。SDK 公共解析器只接受字段集合严格等于 `type/action/transaction-id/trigger/entry`、固定枚举值正确且 `transaction-id` 为 UUID4 的独立尾部 JSON；合法动作从展示文本和会话摘要中移除原始 JSON，并在对应 assistant 消息下渲染“发起人工客服”，非法、不完整、重复或夹在正文中的动作不得执行。动作不得按 `ae_code` 或 `agent_code` 分支。点击时调用客服 transport 的可选 `createHandoffSession({ sourceSessionId, actionTransactionId })`；加载中禁止并发提交，失败后以同一 UUID 重试，成功后使用接口返回的客服会话 ID 切换同一抽屉。动作 UUID 不得进入 DOM、公共事件、URL、日志或安全错误信息。
+
 工作台内置应用切换通过 Account Context 的 `workbench` 配置：
 
 ```ts
@@ -248,7 +250,7 @@ customerSupportChat.configure({
 })
 ```
 
-`transport` 负责客服会话列表、首条消息原子创建、历史消息、后续发送、已读同步与 `getAccessToken()`；真实 HR-SaaS 对接使用 `createHrSaasCustomerSupportTransport()`。组件初始关闭，由 Host 或数字员工组件调用 `open()`。组件自身拥有完整抽屉、会话列表、消息区、输入区和关闭行为。公开事件为 `ready`、`message-sent`、`message-received`、`connection-state-change`、`closed` 与 `error`，不得包含 JWT、transport 或后端原始异常。
+`transport` 负责客服会话列表、首条消息原子创建、职责越界交接、历史消息、后续发送、已读同步与 `getAccessToken()`；职责越界交接通过可选 `createHandoffSession()` 暴露，真实 HR-SaaS 对接使用 `createHrSaasCustomerSupportTransport()` 并映射 `user_session_handoff_create`。组件初始关闭，由 Host 或数字员工组件调用 `open()`。组件自身拥有完整抽屉、会话列表、消息区、输入区和关闭行为。公开事件为 `ready`、`message-sent`、`message-received`、`connection-state-change`、`closed` 与 `error`，不得包含 JWT、动作 UUID、transport 或后端原始异常。
 
 通知中心通过 JavaScript property 配置：
 

package/README.md

@@ -680,6 +680,10 @@ accountContext.configure({
 
 数字员工的 `assistant` 回复按 Markdown 渲染，支持标题、强调、删除线、行内代码、代码块、引用、有序/无序列表、分隔线及安全链接；用户消息、系统消息和错误消息仍按普通文本显示。原始 HTML 不会注入 DOM，非 HTTP(S) 或 `mailto:` 链接不会生成可点击链接。
 
+当 KanbanBackend 在最终 assistant 回复尾部附加规范的 `assistant_action/open_customer_support` JSON 时，组件会隐藏原始 JSON，并在该消息下显示“发起人工客服”。解析不依赖 `aeCode` 或 `agentCode`；只有字段集合完整、固定值正确、`transaction-id` 为 UUID4 且动作作为独立尾部 JSON 出现时才可执行。非法、不完整、重复或正文内的动作不会触发接口。SDK 同时导出 `parseAiEmployeeAssistantContent()`，供其他消息视图复用同一安全解析规则。
+
+用户点击该动作后，组件调用客服 transport 的 `createHandoffSession()`，请求体只映射为 `source_session_id` 和 `action_transaction_id`。请求期间按钮禁用，失败后可使用同一动作 UUID 重试；成功后组件释放数字员工连接，并使用接口返回的客服会话 ID 在同一抽屉打开人工客服。动作 UUID 不会进入 DOM、公共事件、URL、日志或错误文案。
+
 点击“转人工”后，数字员工连接会先释放，再由同一抽屉切换为 `<uniplat-customer-support-chat>`；不会向数字员工发送一条模拟转人工文本，也不要求 Host 创建第二个抽屉。默认情况下，组件复用数字员工的 `realtimeUrl` 和 `transport.getAccessToken()`，并请求同源 `/api/general/project/hr_saas/service/customer_support_api`，因此使用标准网关路径的 Host 无需增加配置。只有客服网关地址或鉴权提供者不同时，才显式传入 `customerSupport` 覆盖默认配置：
 
 ```ts
@@ -704,7 +708,7 @@ chat.configure({
 
 ### Customer Support Chat
 
-`<uniplat-customer-support-chat>` 也可以独立使用。它直接复用 HR-SaaS 的 `user_session_page`、`user_session_create`、`user_message_page`、`user_message_send` 和 `user_mark_read`，实时连接订阅 Kanban 的 `customer_support` channel。首条消息通过 `user_session_create.initial_message` 原子创建会话，后续消息使用 `user_message_send`。打开抽屉或点击“新对话”只进入本地空白态，不提前创建等待中会话；历史遗留的无消息 `waiting` 会话也不会被自动恢复。只有首条消息成功创建会话后，界面才显示“等待客服接入”。
+`<uniplat-customer-support-chat>` 也可以独立使用。它直接复用 HR-SaaS 的 `user_session_page`、`user_session_create`、`user_session_handoff_create`、`user_message_page`、`user_message_send` 和 `user_mark_read`，实时连接订阅 Kanban 的 `customer_support` channel。首条消息通过 `user_session_create.initial_message` 原子创建会话，后续消息使用 `user_message_send`；数字员工职责越界交接由 transport 的可选 `createHandoffSession({ sourceSessionId, actionTransactionId })` 调用 `user_session_handoff_create`。打开抽屉或点击“新对话”只进入本地空白态，不提前创建等待中会话；历史遗留的无消息 `waiting` 会话也不会被自动恢复。只有首条消息成功创建会话后，界面才显示“等待客服接入”。
 
 ```html
 <uniplat-customer-support-chat id="customer-support"></uniplat-customer-support-chat>
@@ -753,7 +757,7 @@ uniplat-ai-employee-chat {
 }
 ```
 
-主要 `::part`：`container`、`header`、`session-list-button`、`session-header`、`session-back-button`、`session-list`、`session-item`、`session-item-current`、`session-list-loading`、`session-list-empty`、`session-list-error`、`close-button`、`status`、`messages`、`time-marker`、`message`、`message-user`、`message-assistant`、`message-system`、`message-error`、`composer`、`input`、`send-button`、`human-service-button`、`empty`、`loading`、`activity` 和 `error`。
+主要 `::part`：`container`、`header`、`session-list-button`、`session-header`、`session-back-button`、`session-list`、`session-item`、`session-item-current`、`session-list-loading`、`session-list-empty`、`session-list-error`、`close-button`、`status`、`messages`、`time-marker`、`message`、`message-user`、`message-assistant`、`message-system`、`message-error`、`assistant-action`、`assistant-action-button`、`composer`、`input`、`send-button`、`human-service-button`、`empty`、`loading`、`activity` 和 `error`。
 
 ## Vue 和 Nuxt
 

package/docs//346/225/260/345/255/227/345/221/230/345/267/245/345/256/214/346/225/264/346/212/275/345/261/211/346/216/245/345/205/245/350/257/264/346/230/216.md

@@ -36,6 +36,52 @@ Host 不再渲染或包裹以下内容：
 
 Host 仍负责提供 `realtimeUrl`、`aeCode`、`agentCode` 和 transport。JWT 继续只由 `transport.getAccessToken()` 返回，不得写入组件属性、HTML attribute 或 URL。
 
+## 职责越界转人工
+
+KanbanBackend 可以在最终 assistant 回复末尾附加以下平台动作：
+
+```json
+{
+  "type": "assistant_action",
+  "action": "open_customer_support",
+  "transaction-id": "550e8400-e29b-41d4-a716-446655440000",
+  "trigger": "out_of_scope",
+  "entry": "help_and_support"
+}
+```
+
+组件会在历史消息和实时消息中统一解析这个独立尾部 JSON。合法动作的原始 JSON 不显示，并在对应回复下渲染“发起人工客服”；字段缺失、额外字段、非 UUID4、重复动作或正文中的 JSON 都不会执行。该能力不按数字员工或 Agent 分支。其他消息视图可从 core 或 Web Components 包导入 `parseAiEmployeeAssistantContent()` 复用相同解析规则。
+
+标准 `createHrSaasCustomerSupportTransport()` 已实现 `createHandoffSession()`，并将公开参数严格映射为：
+
+```json
+{
+  "source_session_id": "数字员工会话 ID",
+  "action_transaction_id": "动作 transaction-id"
+}
+```
+
+点击期间组件会禁止并发提交；失败时显示稳定的安全提示，用户重试会继续使用原动作 UUID；成功时按接口返回的客服会话 ID 释放数字员工连接并切换同一抽屉。Host 无需重建匿名身份，也不得把 `ae_code`、`agent_code`、`org_id`、`user_id` 或角色字段加入转接请求。JWT 继续由原 transport 的 `getAccessToken()` 按请求获取。动作 UUID 不进入 DOM、公共事件、URL、日志或错误文案。
+
+如果 Host 覆盖 `customerSupport.transport`，自定义 transport 需要实现可选方法：
+
+```ts
+async createHandoffSession({ sourceSessionId, actionTransactionId }) {
+  const response = await hostApi.createCustomerSupportHandoff({
+    source_session_id: sourceSessionId,
+    action_transaction_id: actionTransactionId,
+  })
+  return {
+    session: response.session,
+    initialMessage: response.initial_message,
+    created: response.created,
+    repaired: response.repaired,
+  }
+}
+```
+
+若未显式覆盖客服配置，组件会自动复用数字员工 `realtimeUrl`、`transport.getAccessToken()` 和同源 HR-SaaS 客服网关，因此 QQXBWebsite 的标准接入不需要增加新的 token 或 WebSocket 状态机。
+
 ## 会话列表
 
 标题左侧按钮由组件内部负责，点击后切换为原型中的“我的会话”界面。面板头部的“开启新对话”按钮只切换到本地草稿，不创建后端 Session。用户发送首条消息时，组件才通过 Host transport 原子创建会话并提交首条消息：

package/package.json

@@ -1,21 +1,10 @@
 {
   "name": "@csntgao/uni-base",
-  "version": "0.6.2",
+  "version": "0.6.5",
   "type": "module",
-  "packageManager": "pnpm@11.3.0",
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "pnpm --filter @uniplat/ai-employee-client build && pnpm --filter @uniplat/ai-employee-web-components build && pnpm --filter @uniplat/ai-employee-vanilla-example build",
-    "dev": "pnpm --filter @uniplat/ai-employee-client build && pnpm --filter @uniplat/ai-employee-web-components build && pnpm --filter @uniplat/ai-employee-vanilla-example dev",
-    "lint": "eslint . --max-warnings 0",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "pnpm --filter @uniplat/ai-employee-client typecheck && pnpm --filter @uniplat/ai-employee-web-components typecheck"
-  },
   "devDependencies": {
     "@eslint/js": "^9.32.0",
     "eslint": "^9.32.0",
@@ -27,5 +16,15 @@
     "typescript-eslint": "^8.39.0",
     "vite": "^7.1.0",
     "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "pnpm --filter @uniplat/ai-employee-client build && pnpm --filter @uniplat/ai-employee-web-components build && pnpm --filter @uniplat/ai-employee-vanilla-example build",
+    "dev": "pnpm --filter @uniplat/ai-employee-client build && pnpm --filter @uniplat/ai-employee-web-components build && pnpm --filter @uniplat/ai-employee-vanilla-example dev",
+    "lint": "eslint . --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "pnpm --filter @uniplat/ai-employee-client typecheck && pnpm --filter @uniplat/ai-employee-web-components typecheck"
   }
-}
+}

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniplat/ai-employee-client",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Browser client for Uniplat AI Employee sessions and realtime messages",
   "type": "module",
   "sideEffects": false,

package/packages/core/src/assistant-actions.ts

@@ -0,0 +1,120 @@
+export interface OpenCustomerSupportAssistantAction {
+  type: 'assistant_action'
+  action: 'open_customer_support'
+  transactionId: string
+  trigger: 'out_of_scope'
+  entry: 'help_and_support'
+}
+
+export type AiEmployeeAssistantAction = OpenCustomerSupportAssistantAction
+
+export interface ParsedAiEmployeeAssistantContent {
+  content: string
+  actions: readonly AiEmployeeAssistantAction[]
+}
+
+interface StructuredJsonCandidate {
+  content: string
+  json: string
+}
+
+const ACTION_KEYS = ['action', 'entry', 'transaction-id', 'trigger', 'type'] as const
+const OPEN_CUSTOMER_SUPPORT_MARKER = /"action"\s*:\s*"open_customer_support"/g
+const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/**
+ * Parses a trusted platform action from the final standalone JSON block of an
+ * assistant response. Invalid or ambiguous input is returned unchanged and is
+ * never made executable.
+ */
+export function parseAiEmployeeAssistantContent(content: string): ParsedAiEmployeeAssistantContent {
+  const source = typeof content === 'string' ? content : ''
+  const candidate = trailingStructuredJson(source)
+  if (!candidate || markerCount(source) !== 1) return unchanged(source)
+
+  let value: unknown
+  try {
+    value = JSON.parse(candidate.json)
+  } catch {
+    return unchanged(source)
+  }
+  const action = parseOpenCustomerSupportAction(value)
+  if (!action) return unchanged(source)
+  return Object.freeze({
+    content: candidate.content,
+    actions: Object.freeze([action]),
+  })
+}
+
+export function isUuidV4(value: unknown): value is string {
+  return typeof value === 'string' && UUID_V4_PATTERN.test(value)
+}
+
+function trailingStructuredJson(content: string): StructuredJsonCandidate | null {
+  const withoutTrailingWhitespace = content.trimEnd()
+  const fenced = withoutTrailingWhitespace.match(
+    /(?:^|\r?\n)[\t ]*```json[\t ]*\r?\n([\s\S]*?)\r?\n[\t ]*```$/i,
+  )
+  if (fenced?.index !== undefined) {
+    return {
+      content: withoutTrailingWhitespace.slice(0, fenced.index).trimEnd(),
+      json: fenced[1]?.trim() ?? '',
+    }
+  }
+
+  const starts = [...withoutTrailingWhitespace.matchAll(/(?:^|\r?\n)[\t ]*(\{)/g)]
+  for (let index = starts.length - 1; index >= 0; index -= 1) {
+    const match = starts[index]
+    const objectOffset =
+      match?.index === undefined ? -1 : match.index + (match[0]?.indexOf('{') ?? -1)
+    if (objectOffset < 0) continue
+    const json = withoutTrailingWhitespace.slice(objectOffset).trim()
+    try {
+      JSON.parse(json)
+      return {
+        content: withoutTrailingWhitespace.slice(0, match?.index ?? 0).trimEnd(),
+        json,
+      }
+    } catch {
+      // Try an earlier line-start object. Nested or malformed trailing JSON is
+      // never accepted merely because it contains an action-looking fragment.
+    }
+  }
+  return null
+}
+
+function parseOpenCustomerSupportAction(value: unknown): OpenCustomerSupportAssistantAction | null {
+  if (!isRecord(value)) return null
+  const keys = Object.keys(value).sort()
+  if (keys.length !== ACTION_KEYS.length || keys.some((key, index) => key !== ACTION_KEYS[index])) {
+    return null
+  }
+  if (
+    value.type !== 'assistant_action' ||
+    value.action !== 'open_customer_support' ||
+    !isUuidV4(value['transaction-id']) ||
+    value.trigger !== 'out_of_scope' ||
+    value.entry !== 'help_and_support'
+  ) {
+    return null
+  }
+  return Object.freeze({
+    type: 'assistant_action',
+    action: 'open_customer_support',
+    transactionId: value['transaction-id'],
+    trigger: 'out_of_scope',
+    entry: 'help_and_support',
+  })
+}
+
+function markerCount(value: string): number {
+  return [...value.matchAll(OPEN_CUSTOMER_SUPPORT_MARKER)].length
+}
+
+function unchanged(content: string): ParsedAiEmployeeAssistantContent {
+  return Object.freeze({ content, actions: Object.freeze([]) })
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/packages/core/src/client.ts

@@ -313,12 +313,7 @@ export class AiEmployeeClient {
       content,
       createdAt: now.toISOString(),
     }
-    for (const [pendingContent, sentAt] of this.pendingLocalMessages) {
-      if (now.getTime() - sentAt > LOCAL_MESSAGE_MATCH_WINDOW_MS) {
-        this.pendingLocalMessages.delete(pendingContent)
-      }
-    }
-    this.pendingLocalMessages.set(content, now.getTime())
+    this.rememberPendingLocalMessage(content)
     this.appendMessage(message, 'local')
     this.setProcessing(true)
     return message
@@ -374,6 +369,9 @@ export class AiEmployeeClient {
       content,
       createdAt: result.createdAt ?? result.startedAt,
     }
+    // 首条消息同样要登记本地回声窗口：服务端 replay 与实时事件可能带着与
+    // createSessionWithFirstMessage 不同的消息 ID 回来。
+    this.rememberPendingLocalMessage(content)
     this.appendMessage(message, 'local')
     this.setProcessing(true)
     this.replayHistoryOnNextSubscription = true
@@ -610,11 +608,27 @@ export class AiEmployeeClient {
     this.emit('ready', { sessionId })
   }
 
+  private rememberPendingLocalMessage(content: string): void {
+    const now = Date.now()
+    for (const [pendingContent, sentAt] of this.pendingLocalMessages) {
+      if (now - sentAt > LOCAL_MESSAGE_MATCH_WINDOW_MS) {
+        this.pendingLocalMessages.delete(pendingContent)
+      }
+    }
+    this.pendingLocalMessages.set(content, now)
+  }
+
+  /**
+   * 本地已渲染的用户消息会被服务端以 replay 和实时事件多次回送，且不保证复用
+   * 同一个消息 ID。窗口期内不消费该条目，多次回声都要挡住；本地发送本身每次都
+   * 会追加气泡，所以重复发送同样内容不会因此丢消息。
+   */
   private matchesPendingLocalMessage(message: AiEmployeeMessage): boolean {
     const sentAt = this.pendingLocalMessages.get(message.content)
     if (sentAt === undefined) return false
+    if (Date.now() - sentAt <= LOCAL_MESSAGE_MATCH_WINDOW_MS) return true
     this.pendingLocalMessages.delete(message.content)
-    return Date.now() - sentAt <= LOCAL_MESSAGE_MATCH_WINDOW_MS
+    return false
   }
 
   private appendMessage(message: AiEmployeeMessage, source: 'local' | 'realtime'): void {

package/packages/core/src/customer-support-types.ts

@@ -52,6 +52,18 @@ export interface CustomerSupportCreateSessionResult {
   initialMessage?: CustomerSupportMessage
 }
 
+export interface CustomerSupportHandoffRequest {
+  sourceSessionId: string
+  actionTransactionId: string
+}
+
+export interface CustomerSupportHandoffResult {
+  session: CustomerSupportSession
+  initialMessage: CustomerSupportMessage
+  created: boolean
+  repaired: boolean
+}
+
 export interface CustomerSupportTransport {
   getAccessToken(): Promise<string>
   listSessions(): Promise<readonly CustomerSupportSession[]>
@@ -59,6 +71,9 @@ export interface CustomerSupportTransport {
   createSession(
     request: CustomerSupportCreateSessionRequest,
   ): Promise<CustomerSupportCreateSessionResult>
+  createHandoffSession?(
+    request: CustomerSupportHandoffRequest,
+  ): Promise<CustomerSupportHandoffResult>
   listMessages(sessionId: string): Promise<CustomerSupportMessagePage>
   sendMessage(
     sessionId: string,

package/packages/core/src/index.ts

@@ -1,4 +1,10 @@
 export { AiEmployeeClient, AiEmployeeClientError, AiEmployeeTransportError } from './client'
+export { isUuidV4, parseAiEmployeeAssistantContent } from './assistant-actions'
+export type {
+  AiEmployeeAssistantAction,
+  OpenCustomerSupportAssistantAction,
+  ParsedAiEmployeeAssistantContent,
+} from './assistant-actions'
 export { CustomerSupportClient, CustomerSupportClientError } from './customer-support-client'
 export {
   NotificationCenterClient,
@@ -50,6 +56,8 @@ export type {
   CustomerSupportCreateSessionResult,
   CustomerSupportErrorCode,
   CustomerSupportErrorDetail,
+  CustomerSupportHandoffRequest,
+  CustomerSupportHandoffResult,
   CustomerSupportMessage,
   CustomerSupportMessagePage,
   CustomerSupportSenderType,

package/packages/core/src/protocol.ts

@@ -96,7 +96,7 @@ function parseSessionPayload(payload: JsonRecord, sessionId: string): ParsedSess
   for (const rawPatch of patches) {
     const patch = asRecord(rawPatch)
     const value = asRecord(patch.value)
-    const parsed = messageFromEntry(value, sessionId, patch)
+    const parsed = messageFromEntry(value, sessionId)
     if (parsed) messages.push(parsed)
   }
 
@@ -129,11 +129,7 @@ function parseSessionPayload(payload: JsonRecord, sessionId: string): ParsedSess
   return { messages, fallbackResult, processing }
 }
 
-function messageFromEntry(
-  entry: JsonRecord,
-  sessionId: string,
-  patch: JsonRecord,
-): AiEmployeeMessage | null {
+function messageFromEntry(entry: JsonRecord, sessionId: string): AiEmployeeMessage | null {
   const entryTypeValue = entry.entry_type
   const entryType =
     typeof entryTypeValue === 'string' ? entryTypeValue : stringValue(asRecord(entryTypeValue).type)
@@ -168,7 +164,9 @@ function messageFromEntry(
     role === 'user'
       ? messageId || webSocketMessageId || stringValue(entry.id)
       : webSocketMessageId || messageId || stringValue(entry.id)
-  const fingerprint = stableString({ entry, path: patch.path, op: patch.op })
+  // 同一条消息经 replay 与实时两条路径投递时 patch 的 path/op 不同，
+  // 合成 ID 只能取消息本身，否则同一条消息会得到不同 ID 而重复显示。
+  const fingerprint = stableString(entry)
   const id = explicitId || `realtime:${sessionId}:${hashText(fingerprint)}`
   return createMessage(sessionId, role, content, id, entry)
 }

package/packages/core/src/types.ts

@@ -112,6 +112,12 @@ export type AiEmployeeErrorCode =
   | 'RATE_LIMITED'
   | 'SEND_IN_PROGRESS'
   | 'EMPTY_MESSAGE'
+  | 'SOURCE_SESSION_NOT_FOUND'
+  | 'SOURCE_SESSION_ACCESS_DENIED'
+  | 'HANDOFF_ACTION_NOT_FOUND'
+  | 'HANDOFF_ACTION_MISMATCH'
+  | 'CUSTOMER_SUPPORT_UNAVAILABLE'
+  | 'CUSTOMER_SUPPORT_HANDOFF_FAILED'
   | 'CLIENT_DESTROYED'
 
 export interface AiEmployeeClientErrorDetail {

package/packages/core/tests/assistant-actions.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { parseAiEmployeeAssistantContent } from '../src'
+
+const transactionId = '8f0b790c-1c5f-4f8c-95cc-4ead9d9cfb1a'
+
+function actionJson(overrides: Record<string, unknown> = {}): string {
+  return JSON.stringify(
+    {
+      type: 'assistant_action',
+      action: 'open_customer_support',
+      'transaction-id': transactionId,
+      trigger: 'out_of_scope',
+      entry: 'help_and_support',
+      ...overrides,
+    },
+    null,
+    2,
+  )
+}
+
+describe('parseAiEmployeeAssistantContent', () => {
+  it('extracts one valid fenced action and removes the raw JSON from display content', () => {
+    const parsed = parseAiEmployeeAssistantContent(
+      `该问题超出我的职责范围。\n\n您可以从‘帮助与支持’菜单项入口发起人工客服。\n\n\`\`\`json\n${actionJson()}\n\`\`\``,
+    )
+
+    expect(parsed.content).toBe(
+      '该问题超出我的职责范围。\n\n您可以从‘帮助与支持’菜单项入口发起人工客服。',
+    )
+    expect(parsed.actions).toEqual([
+      {
+        type: 'assistant_action',
+        action: 'open_customer_support',
+        transactionId,
+        trigger: 'out_of_scope',
+        entry: 'help_and_support',
+      },
+    ])
+  })
+
+  it('accepts a trailing standalone raw JSON action', () => {
+    const parsed = parseAiEmployeeAssistantContent(`暂时无法处理。\n${actionJson()}`)
+
+    expect(parsed.content).toBe('暂时无法处理。')
+    expect(parsed.actions[0]?.transactionId).toBe(transactionId)
+  })
+
+  it.each([
+    actionJson({ 'transaction-id': 'not-a-uuid' }),
+    actionJson({ trigger: 'technical_failure' }),
+    actionJson({ entry: 'other' }),
+    actionJson({ extra: true }),
+    '{"type":"assistant_action"}',
+  ])('does not execute malformed or incomplete actions', (json) => {
+    const source = `无法处理。\n\n\`\`\`json\n${json}\n\`\`\``
+    const parsed = parseAiEmployeeAssistantContent(source)
+
+    expect(parsed).toEqual({ content: source, actions: [] })
+  })
+
+  it('rejects an ambiguous response containing the action more than once', () => {
+    const block = `\`\`\`json\n${actionJson()}\n\`\`\``
+    const source = `无法处理。\n\n${block}\n\n${block}`
+
+    expect(parseAiEmployeeAssistantContent(source)).toEqual({ content: source, actions: [] })
+  })
+
+  it('leaves ordinary JSON and inline action-looking prose unchanged', () => {
+    const ordinary = '示例：{"action":"open_customer_support"}，这不是平台动作。'
+
+    expect(parseAiEmployeeAssistantContent(ordinary)).toEqual({
+      content: ordinary,
+      actions: [],
+    })
+  })
+})