@csntgao/uni-base 0.6.2 → 0.6.5

package/packages/core/tests/client.test.ts

@@ -185,6 +185,102 @@ describe('AiEmployeeClient', () => {
     expect(client.messages.filter((message) => message.id === 'ws-message-1')).toHaveLength(1)
   })
 
+  it('deduplicates the same realtime message delivered through different patch paths', async () => {
+    const { client, sockets } = createHarness()
+    const received: string[] = []
+    client.on('message', ({ message }) => received.push(message.content))
+    await client.start()
+    await authenticateAndReady(sockets[0]!)
+
+    // 服务端没给消息 ID 时只能合成；replay 与实时投递的 patch 路径不同，
+    // 合成 ID 必须仍然相同，否则同一条消息会重复显示。
+    const entry = {
+      entry_type: { type: 'assistant_message' },
+      content: JSON.stringify({ text: '同一条回复' }),
+      timestamp: '2026-09-04T02:00:00.000Z',
+    }
+    const frameWithPath = (path: string) => ({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'session-1',
+        payload: { JsonPatch: [{ path, value: entry }] },
+      },
+    })
+    sockets[0]?.receive(frameWithPath('/0'))
+    sockets[0]?.receive(frameWithPath('/3'))
+
+    expect(received).toEqual(['同一条回复'])
+    expect(client.messages.filter((message) => message.content === '同一条回复')).toHaveLength(1)
+  })
+
+  it('keeps a locally sent message single across replay and live echoes', async () => {
+    const { client, sockets } = createHarness()
+    await client.start()
+    await authenticateAndReady(sockets[0]!)
+    await client.sendMessage('给我生成一个文本文件，内容是123456')
+
+    // 同一条用户消息被服务端以不同 ID 回送两次（replay + 实时）。
+    const echo = (messageId: string) => ({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'session-1',
+        payload: {
+          JsonPatch: [
+            {
+              path: '/0',
+              value: {
+                message_id: messageId,
+                entry_type: { type: 'user_message' },
+                content: JSON.stringify({ text: '给我生成一个文本文件，内容是123456' }),
+              },
+            },
+          ],
+        },
+      },
+    })
+    sockets[0]?.receive(echo('replay-message-1'))
+    sockets[0]?.receive(echo('live-message-1'))
+
+    expect(
+      client.messages.filter((message) => message.content === '给我生成一个文本文件，内容是123456'),
+    ).toHaveLength(1)
+  })
+
+  it('keeps the first message single when the server echoes another message id', async () => {
+    // 草稿会话：这条走的是 createSessionWithFirstMessage 原子建会话路径。
+    const { client, sockets } = createHarness(createTransport(), { draft: true })
+    await client.start()
+    await authenticateAndReady(sockets[0]!)
+    await client.sendMessage('首条消息内容')
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'ai_employee',
+      event: {
+        type: 'session_message',
+        session_id: 'atomic-session-default',
+        payload: {
+          JsonPatch: [
+            {
+              path: '/0',
+              value: {
+                message_id: 'server-side-other-id',
+                entry_type: { type: 'user_message' },
+                content: JSON.stringify({ text: '首条消息内容' }),
+              },
+            },
+          ],
+        },
+      },
+    })
+
+    expect(client.messages.filter((message) => message.content === '首条消息内容')).toHaveLength(1)
+  })
+
   it('uses a top-level result only when the current turn has no assistant message', async () => {
     const { client, sockets } = createHarness()
     const received: string[] = []

package/packages/web-components/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniplat/ai-employee-web-components",
-  "version": "0.29.2",
+  "version": "0.29.5",
   "description": "Framework-independent Web Components for Uniplat account, login, application switching and AI Employee chat",
   "type": "module",
   "sideEffects": true,

package/packages/web-components/scripts/verify-runtime-build.mjs

@@ -34,6 +34,7 @@ const requiredExports = [
   'createHrSaasCustomerSupportTransport',
   'exchangeUniplatBaseApplicationTicket',
   'loginWithUniplatBaseIdentityTicket',
+  'parseAiEmployeeAssistantContent',
   'resolveOrganizationEntryDecision',
 ]
 const requiredTags = [

package/packages/web-components/src/chat.ts

@@ -1,15 +1,20 @@
 import {
   AiEmployeeClient,
   AiEmployeeClientError,
+  parseAiEmployeeAssistantContent,
   type AiEmployeeClientErrorDetail,
   type AiEmployeeClientOptions,
   type AiEmployeeConnectionState,
   type AiEmployeeMessage,
   type AiEmployeeSessionSummary,
+  type OpenCustomerSupportAssistantAction,
 } from '@uniplat/ai-employee-client'
 import { LitElement, css, html, nothing, type PropertyValues } from 'lit'
 import type { UniplatCustomerSupportChat, CustomerSupportChatConfig } from './customer-support-chat'
-import { createHrSaasCustomerSupportTransport } from './customer-support-transport'
+import {
+  createHrSaasCustomerSupportTransport,
+  HrSaasCustomerSupportTransportError,
+} from './customer-support-transport'
 import { prototypeIcon } from './prototype-icons'
 import { renderSafeMarkdown } from './safe-markdown'
 
@@ -22,6 +27,11 @@ interface LocalReadBoundary {
   updatedAtMs: number
 }
 
+interface CustomerSupportHandoffUiState {
+  status: 'loading' | 'failed' | 'succeeded'
+  message: string
+}
+
 const AI_ADVISOR_TITLE = '企业服务AI顾问'
 
 export interface AiEmployeeChatEventMap {
@@ -50,6 +60,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     switchingSessionId: { state: true },
     creatingSession: { state: true },
     customerSupportOpen: { state: true },
+    customerSupportHandoffStates: { state: true },
   }
 
   static override styles = css`
@@ -635,6 +646,55 @@ export class UniplatAiEmployeeChat extends LitElement {
       text-underline-offset: 2px;
     }
 
+    .assistant-action {
+      display: flex;
+      align-items: flex-start;
+      flex-direction: column;
+      gap: 6px;
+      margin-top: 8px;
+    }
+
+    .assistant-action-button {
+      display: inline-flex;
+      min-height: 36px;
+      align-items: center;
+      justify-content: center;
+      gap: 7px;
+      padding: 7px 13px;
+      border: 1px solid color-mix(in srgb, var(--uniplat-chat-primary), transparent 58%);
+      border-radius: 9px;
+      outline: none;
+      background: #f0f5ff;
+      color: var(--uniplat-chat-primary);
+      cursor: pointer;
+      font: inherit;
+      font-size: 13px;
+      font-weight: 700;
+    }
+
+    .assistant-action-button:hover,
+    .assistant-action-button:focus-visible {
+      border-color: var(--uniplat-chat-primary);
+      background: #e6efff;
+    }
+
+    .assistant-action-button:disabled {
+      cursor: wait;
+      opacity: 0.65;
+    }
+
+    .assistant-action-button svg {
+      width: 16px;
+      height: 16px;
+    }
+
+    .assistant-action-error {
+      max-width: 280px;
+      color: var(--uniplat-chat-error);
+      font-size: 12px;
+      line-height: 1.5;
+    }
+
     .empty,
     .loading {
       display: grid;
@@ -778,6 +838,7 @@ export class UniplatAiEmployeeChat extends LitElement {
   declare private switchingSessionId: string
   declare private creatingSession: boolean
   declare private customerSupportOpen: boolean
+  declare private customerSupportHandoffStates: ReadonlyMap<string, CustomerSupportHandoffUiState>
   private config: AiEmployeeChatConfig | null = null
   private client: AiEmployeeClient | null = null
   private clientUnsubscribers: Array<() => void> = []
@@ -785,7 +846,13 @@ export class UniplatAiEmployeeChat extends LitElement {
   private sessionListGeneration = 0
   private readyDispatched = false
   private readSyncGeneration = 0
+  private customerSupportHandoffGeneration = 0
   private readonly localMessageIds = new Set<string>()
+  /**
+   * 只有来自 HTTP 历史与会话列表的消息 ID 是服务端持久化 ID，实时事件里的
+   * ws_message_id / 合成 ID 不能用于已读同步，服务端会以 INVALID_ARGUMENT 拒绝。
+   */
+  private readonly persistedMessageIds = new Set<string>()
   private readonly locallyReadBoundaries = new Map<string, LocalReadBoundary>()
   private readonly confirmedReadMessageIds = new Map<string, string>()
   private readonly queuedReadMessageIds = new Map<string, string>()
@@ -813,9 +880,11 @@ export class UniplatAiEmployeeChat extends LitElement {
     this.switchingSessionId = ''
     this.creatingSession = false
     this.customerSupportOpen = false
+    this.customerSupportHandoffStates = new Map()
   }
 
   configure(config: AiEmployeeChatConfig): void {
+    this.customerSupportHandoffGeneration += 1
     this.config = config
     this.releaseClient()
     this.resetView()
@@ -838,6 +907,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     if (!this.drawerOpen) return
     this.drawerOpen = false
     this.pendingInitialMessage = ''
+    this.customerSupportHandoffGeneration += 1
     window.removeEventListener('keydown', this.handleWindowKeyDown)
     this.releaseClient()
   }
@@ -848,6 +918,7 @@ export class UniplatAiEmployeeChat extends LitElement {
   }
 
   override disconnectedCallback(): void {
+    this.customerSupportHandoffGeneration += 1
     window.removeEventListener('keydown', this.handleWindowKeyDown)
     this.releaseClient()
     super.disconnectedCallback()
@@ -1039,7 +1110,9 @@ export class UniplatAiEmployeeChat extends LitElement {
           >
             <span class="session-item-icon" aria-hidden="true">${prototypeIcon('robot')}</span>
             <span class="session-item-title">${session.title}</span>
-            <span class="session-item-preview">${session.latestMessage || '暂无消息'}</span>
+            <span class="session-item-preview"
+              >${sessionPreview(session.latestMessage) || '暂无消息'}</span
+            >
             <span class="session-item-side">
               <span>${formatRelativeTime(session.updatedAt)}</span>
               ${
@@ -1089,6 +1162,10 @@ export class UniplatAiEmployeeChat extends LitElement {
         </div>
       `
     }
+    const parsed =
+      message.role === 'assistant'
+        ? parseAiEmployeeAssistantContent(message.content)
+        : { content: message.content, actions: [] }
     return html`
       <div class="message-row ${message.role}">
         <div class="assistant-message">
@@ -1097,19 +1174,60 @@ export class UniplatAiEmployeeChat extends LitElement {
             <span class="assistant-label"
               >${message.role === 'error' ? '系统提示' : '在线顾问'}</span
             >
-            <div
-              class="message ${message.role} ${message.role === 'assistant' ? 'markdown' : ''}"
-              part="message message-${message.role}"
-              data-message-id=${message.id}
-            >
-              ${message.role === 'assistant' ? renderSafeMarkdown(message.content) : message.content}
-            </div>
+            ${
+              parsed.content
+                ? html`<div
+                    class="message ${message.role} ${
+                      message.role === 'assistant' ? 'markdown' : ''
+                    }"
+                    part="message message-${message.role}"
+                    data-message-id=${message.id}
+                  >
+                    ${
+                      message.role === 'assistant'
+                        ? renderSafeMarkdown(parsed.content)
+                        : parsed.content
+                    }
+                  </div>`
+                : nothing
+            }
+            ${
+              message.role === 'assistant'
+                ? parsed.actions.map((action) => this.renderAssistantAction(message, action))
+                : nothing
+            }
           </div>
         </div>
       </div>
     `
   }
 
+  private renderAssistantAction(
+    message: AiEmployeeMessage,
+    action: OpenCustomerSupportAssistantAction,
+  ) {
+    const state = this.customerSupportHandoffStates.get(action.transactionId)
+    const loading = state?.status === 'loading'
+    const succeeded = state?.status === 'succeeded'
+    return html`<div class="assistant-action" part="assistant-action">
+      <button
+        class="assistant-action-button"
+        part="assistant-action-button"
+        type="button"
+        ?disabled=${loading || succeeded}
+        @click=${() => void this.handleCustomerSupportHandoff(message, action)}
+      >
+        ${prototypeIcon(succeeded ? 'circle-check-filled' : 'headset')}
+        ${loading ? '正在发起人工客服…' : succeeded ? '已发起人工客服' : '发起人工客服'}
+      </button>
+      ${
+        state?.status === 'failed'
+          ? html`<span class="assistant-action-error" role="status">${state.message}</span>`
+          : nothing
+      }
+    </div>`
+  }
+
   private async startClient(): Promise<void> {
     const config = this.config
     if (!config || this.client || !this.isConnected) return
@@ -1159,6 +1277,7 @@ export class UniplatAiEmployeeChat extends LitElement {
       client.on('history', ({ sessionId, messages }) => {
         if (this.client !== client) return
         this.messages = messages
+        for (const message of messages) this.persistedMessageIds.add(message.id)
         if (this.isCurrentConversationVisible(sessionId)) void this.markCurrentSessionRead()
       }),
       client.on('message', ({ sessionId, message, source }) => {
@@ -1180,7 +1299,14 @@ export class UniplatAiEmployeeChat extends LitElement {
         this.dispatchPublicEvent('connection-state-change', { state: current })
       }),
       client.on('processing-state-change', ({ processing }) => {
-        if (this.client === client) this.processing = processing
+        if (this.client !== client) return
+        const finished = this.processing && !processing
+        this.processing = processing
+        // 实时事件只带 ws_message_id；本轮结束后重新取一次历史，
+        // 才能用持久化 ID 同步已读。
+        if (finished && this.isCurrentConversationVisible(client.sessionId ?? '')) {
+          void client.refreshMessages().catch(() => undefined)
+        }
       }),
       client.on('title', ({ sessionId, title }) => {
         if (this.client !== client) return
@@ -1252,6 +1378,9 @@ export class UniplatAiEmployeeChat extends LitElement {
     try {
       const sessions = normalizeSessionSummaries(await listSessions.call(transport))
       if (!this.isCurrentSessionList(generation)) return
+      for (const session of sessions) {
+        if (session.latestMessageId) this.persistedMessageIds.add(session.latestMessageId)
+      }
       const mergedSessions = mergeCurrentSession(sessions, this.currentSessionSummary())
       this.sessions = this.applyLocallyReadState(mergedSessions)
       const currentSession = mergedSessions.find(
@@ -1390,11 +1519,14 @@ export class UniplatAiEmployeeChat extends LitElement {
     const summary: AiEmployeeSessionSummary = {
       sessionId: message.sessionId,
       title: existing?.title || this.chatTitle || '新对话',
-      latestMessage: message.content,
+      latestMessage: messagePreview(message),
       updatedAt: message.createdAt,
       unreadCount: visible ? 0 : Math.max(0, (existing?.unreadCount ?? 0) + unreadIncrement),
     }
-    const latestMessageId = source === 'local' ? existing?.latestMessageId : message.id
+    // 实时消息 ID 不是持久化 ID，不能当作已读游标。
+    const latestMessageId = this.persistedMessageIds.has(message.id)
+      ? message.id
+      : existing?.latestMessageId
     if (latestMessageId) summary.latestMessageId = latestMessageId
     this.sessions = [
       summary,
@@ -1410,7 +1542,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     let latestServerMessage: AiEmployeeMessage | undefined
     for (let index = this.messages.length - 1; index >= 0; index -= 1) {
       const candidate = this.messages[index]
-      if (candidate && !this.localMessageIds.has(candidate.id)) {
+      if (candidate && this.persistedMessageIds.has(candidate.id)) {
         latestServerMessage = candidate
         break
       }
@@ -1418,7 +1550,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     const summary: AiEmployeeSessionSummary = {
       sessionId,
       title: this.chatTitle || '新对话',
-      latestMessage: latestMessage?.content ?? '',
+      latestMessage: latestMessage ? messagePreview(latestMessage) : '',
       updatedAt: latestMessage?.createdAt ?? new Date().toISOString(),
       unreadCount: 0,
     }
@@ -1495,6 +1627,48 @@ export class UniplatAiEmployeeChat extends LitElement {
       })
       return
     }
+    this.openCustomerSupport(customerSupport)
+  }
+
+  private async handleCustomerSupportHandoff(
+    message: AiEmployeeMessage,
+    action: OpenCustomerSupportAssistantAction,
+  ): Promise<void> {
+    const key = action.transactionId
+    const currentState = this.customerSupportHandoffStates.get(key)
+    if (currentState?.status === 'loading' || currentState?.status === 'succeeded') return
+    const customerSupport = this.resolveCustomerSupportConfig()
+    const createHandoffSession = customerSupport?.transport.createHandoffSession
+    if (!customerSupport || !createHandoffSession) {
+      const detail: AiEmployeeClientErrorDetail = {
+        code: 'CUSTOMER_SUPPORT_UNAVAILABLE',
+        message: '人工客服转接暂未配置。',
+        recoverable: false,
+      }
+      this.setCustomerSupportHandoffState(key, { status: 'failed', message: detail.message })
+      this.dispatchPublicEvent('error', detail)
+      return
+    }
+
+    const generation = this.customerSupportHandoffGeneration
+    this.setCustomerSupportHandoffState(key, { status: 'loading', message: '' })
+    try {
+      const result = await createHandoffSession.call(customerSupport.transport, {
+        sourceSessionId: message.sessionId,
+        actionTransactionId: action.transactionId,
+      })
+      if (!this.isCurrentCustomerSupportHandoff(generation, message.sessionId)) return
+      this.setCustomerSupportHandoffState(key, { status: 'succeeded', message: '' })
+      this.openCustomerSupport({ ...customerSupport, sessionId: result.session.id })
+    } catch (error) {
+      if (!this.isCurrentCustomerSupportHandoff(generation, message.sessionId)) return
+      const detail = customerSupportHandoffError(error)
+      this.setCustomerSupportHandoffState(key, { status: 'failed', message: detail.message })
+      this.dispatchPublicEvent('error', detail)
+    }
+  }
+
+  private openCustomerSupport(customerSupport: CustomerSupportChatConfig): void {
     this.releaseClient()
     this.customerSupportOpen = true
     void this.updateComplete.then(() => {
@@ -1507,6 +1681,20 @@ export class UniplatAiEmployeeChat extends LitElement {
     })
   }
 
+  private setCustomerSupportHandoffState(key: string, state: CustomerSupportHandoffUiState): void {
+    const next = new Map(this.customerSupportHandoffStates)
+    next.set(key, state)
+    this.customerSupportHandoffStates = next
+  }
+
+  private isCurrentCustomerSupportHandoff(generation: number, sessionId: string): boolean {
+    return (
+      generation === this.customerSupportHandoffGeneration &&
+      this.drawerOpen &&
+      this.client?.sessionId === sessionId
+    )
+  }
+
   private resolveCustomerSupportConfig(): CustomerSupportChatConfig | null {
     const config = this.config
     if (!config) return null
@@ -1603,6 +1791,7 @@ export class UniplatAiEmployeeChat extends LitElement {
   private resetView(): void {
     this.readSyncGeneration += 1
     this.localMessageIds.clear()
+    this.persistedMessageIds.clear()
     this.locallyReadBoundaries.clear()
     this.confirmedReadMessageIds.clear()
     this.queuedReadMessageIds.clear()
@@ -1619,9 +1808,72 @@ export class UniplatAiEmployeeChat extends LitElement {
     this.switchingSessionId = ''
     this.creatingSession = false
     this.connectionState = 'idle'
+    this.customerSupportHandoffStates = new Map()
   }
 }
 
+function customerSupportHandoffError(error: unknown): AiEmployeeClientErrorDetail {
+  if (error instanceof HrSaasCustomerSupportTransportError) {
+    if (error.code === 'SOURCE_SESSION_NOT_FOUND') {
+      return {
+        code: 'SOURCE_SESSION_NOT_FOUND',
+        message: '来源会话不存在，请刷新后重试。',
+        recoverable: false,
+      }
+    }
+    if (error.code === 'SOURCE_SESSION_ACCESS_DENIED') {
+      return {
+        code: 'SOURCE_SESSION_ACCESS_DENIED',
+        message: '当前身份无权转接此会话。',
+        recoverable: false,
+      }
+    }
+    if (error.code === 'HANDOFF_ACTION_NOT_FOUND') {
+      return {
+        code: 'HANDOFF_ACTION_NOT_FOUND',
+        message: '该人工客服入口已失效，请刷新会话后重试。',
+        recoverable: false,
+      }
+    }
+    if (error.code === 'HANDOFF_ACTION_MISMATCH') {
+      return {
+        code: 'HANDOFF_ACTION_MISMATCH',
+        message: '转接状态已变化，请刷新会话后重试。',
+        recoverable: true,
+      }
+    }
+    if (error.code === 'AUTH_REQUIRED' || error.code === 'UNAUTHORIZED') {
+      return {
+        code: 'AUTHENTICATION_FAILED',
+        message: '登录状态已失效，请重新登录后再试。',
+        recoverable: true,
+      }
+    }
+    if (error.code === 'CUSTOMER_SUPPORT_UNAVAILABLE' || error.code === 'REQUEST_FAILED') {
+      return {
+        code: 'CUSTOMER_SUPPORT_UNAVAILABLE',
+        message: '人工客服暂时不可用，请稍后重试。',
+        recoverable: true,
+      }
+    }
+  }
+  return {
+    code: 'CUSTOMER_SUPPORT_HANDOFF_FAILED',
+    message: '人工客服转接失败，请稍后重试。',
+    recoverable: true,
+  }
+}
+
+function messagePreview(message: AiEmployeeMessage): string {
+  return message.role === 'assistant' ? sessionPreview(message.content) : message.content
+}
+
+function sessionPreview(content: string): string {
+  const parsed = parseAiEmployeeAssistantContent(content)
+  if (parsed.actions.length === 0) return content
+  return parsed.content || '可发起人工客服'
+}
+
 function formatMessageTime(value: string): string {
   const date = new Date(value)
   if (Number.isNaN(date.getTime())) return ''