feat(message): enhance message state management with createMessage method for runtime adaptability

gene9831 · gene9831 · commit 3ea4e6f301db · 2026-04-22T16:08:00.000+08:00
diff --git a/packages/kit/src/message/adapters/native.ts b/packages/kit/src/message/adapters/native.ts
@@ -116,6 +116,9 @@ export const createNativeMessageAdapter = (): MessageStateAdapter => {
   return {
     initialize,
     getState,
+    createMessage(message) {
+      return message
+    },
     mutate,
     subscribe,
   }
diff --git a/packages/kit/src/message/adapters/vue.ts b/packages/kit/src/message/adapters/vue.ts
@@ -55,10 +55,14 @@ export const createVueMessageAdapter = (): VueMessageStateAdapter => {
 
     requestState.value = initialState.requestState
     processingState.value = initialState.processingState
-    messages.value.push(...initialState.messages)
+    messages.value = initialState.messages.map(toReactiveMessage)
     initialized = true
   }
 
+  const createMessage = <T extends ChatMessage>(message: T): T => {
+    return toReactiveMessage(message) as T
+  }
+
   const getState = () => {
     if (!initialized) {
       throw new Error('Message state adapter is not initialized')
@@ -94,7 +98,7 @@ export const createVueMessageAdapter = (): VueMessageStateAdapter => {
         return messages.value
       },
       set messages(value) {
-        messages.value = value.map(toReactiveMessage)
+        messages.value = value.map(createMessage)
       },
     }
 
@@ -177,6 +181,7 @@ export const createVueMessageAdapter = (): VueMessageStateAdapter => {
     isProcessing,
     initialize,
     getState,
+    createMessage,
     mutate,
     subscribe,
   }
diff --git a/packages/kit/src/message/core/engine.ts b/packages/kit/src/message/core/engine.ts
@@ -94,6 +94,7 @@ export const createMessageEngine = (
   const plugins = deduplicatePlugins(defaultPlugins.concat(pluginsFromOptions))
 
   const getState = () => adapter.getState()
+  const createMessage = <T extends ChatMessage>(message: T): T => adapter.createMessage(message)
   const subscribe = adapter.subscribe
   const mutate = adapter.mutate
 
@@ -137,16 +138,21 @@ export const createMessageEngine = (
   }
 
   const appendMessages = (...messages: ChatMessage[]) => {
+    const runtimeMessages = messages.map((message) => createMessage(message))
+
     mutate('messages', (draft) => {
-      draft.messages.push(...messages)
+      draft.messages.push(...runtimeMessages)
     })
 
-    runtime.currentTurn.push(...messages)
+    runtime.currentTurn.push(...runtimeMessages)
+
+    return runtimeMessages
   }
 
   // Create base context for plugins
   const getBaseContext = (abortSignal: AbortSignal): BasePluginContext => ({
     getState,
+    createMessage,
     mutate,
     abortSignal,
     currentTurn: runtime.currentTurn,
@@ -174,9 +180,9 @@ export const createMessageEngine = (
     // 请求前对消息进行清洗，去掉不必要的字段
     requestBody.messages = sanitizeMessages(requestBody.messages)
 
-    const assistantMessage = { role: 'assistant', content: '', loading: true } as ChatMessage
+    let assistantMessage = { role: 'assistant', content: '', loading: true } as ChatMessage
+    ;[assistantMessage] = appendMessages(assistantMessage)
     options.setAssistantMessage?.(assistantMessage)
-    appendMessages(assistantMessage)
 
     const result = responseProvider(requestBody, abortSignal)
     const chunks = normalizeToAsyncGenerator(result)
@@ -194,7 +200,7 @@ export const createMessageEngine = (
         }
       })
 
-      const choice = chunk.choices.find((item) => item.index === 0) ?? chunk.choices[0]
+      const choice = (chunk.choices || []).find((item) => item.index === 0) ?? chunk.choices?.[0]
 
       if (!choice) {
         continue
diff --git a/packages/kit/src/message/plugins/toolPlugin.ts b/packages/kit/src/message/plugins/toolPlugin.ts
@@ -23,10 +23,12 @@ type ToolCallContext = BasePluginContext & {
 function fillMissingToolMessages({
   messages,
   cancelledContent,
+  createMessage,
   mutate,
 }: {
   messages: ChatMessage[]
   cancelledContent: string
+  createMessage: BasePluginContext['createMessage']
   mutate: MutateMessageStateFn
 }): void {
   // 第一阶段：从首位开始遍历，收集需要插入的信息
@@ -80,11 +82,13 @@ function fillMissingToolMessages({
   mutate('messages', (draft) => {
     for (let i = insertInfos.length - 1; i >= 0; i--) {
       const { insertAfterIndex, missingToolCallIds } = insertInfos[i]
-      const cancelledMessages: ChatMessage[] = missingToolCallIds.map((toolCallId) => ({
-        role: 'tool',
-        tool_call_id: toolCallId,
-        content: cancelledContent,
-      }))
+      const cancelledMessages: ChatMessage[] = missingToolCallIds.map((toolCallId) =>
+        createMessage({
+          role: 'tool',
+          tool_call_id: toolCallId,
+          content: cancelledContent,
+        }),
+      )
 
       // 在 assistant 消息之后插入所有取消消息
       draft.messages.splice(insertAfterIndex + 1, 0, ...cancelledMessages)
@@ -197,11 +201,11 @@ export const toolPlugin = (
     name: 'tool',
     ...restOptions,
     onTurnStart: (context) => {
-      const { getState, mutate } = context
+      const { getState, createMessage, mutate } = context
       const messages = getState().messages
 
       if (autoFillMissingToolMessages) {
-        fillMissingToolMessages({ messages, cancelledContent: toolCallCancelledContent, mutate })
+        fillMissingToolMessages({ messages, cancelledContent: toolCallCancelledContent, createMessage, mutate })
       }
 
       return restOptions.onTurnStart?.(context)
@@ -217,7 +221,16 @@ export const toolPlugin = (
       return restOptions.onBeforeRequest?.(context)
     },
     onAfterRequest: async (context) => {
-      const { currentMessage, lastChoice, appendMessage, abortSignal, setRequestState, requestNext, mutate } = context
+      const {
+        currentMessage,
+        lastChoice,
+        appendMessage,
+        abortSignal,
+        setRequestState,
+        requestNext,
+        mutate,
+        createMessage,
+      } = context
 
       if (lastChoice?.finish_reason !== 'tool_calls' || !currentMessage.tool_calls?.length) {
         return
@@ -231,15 +244,15 @@ export const toolPlugin = (
 
       const toolCallPromises = currentMessage.tool_calls.map(async (toolCall) => {
         const now = Math.floor(Date.now() / 1000)
-        const toolMessage: ChatMessage = {
+        const toolMessage: ChatMessage = createMessage({
           role: 'tool',
           tool_call_id: toolCall.id,
           content: '',
           metadata: {
             createdAt: now,
             updatedAt: now,
           },
-        }
+        })
 
         appendMessage(toolMessage)
 
diff --git a/packages/kit/src/message/test/vue.test.ts b/packages/kit/src/message/test/vue.test.ts
@@ -87,4 +87,41 @@ describe('createVueMessageAdapter', () => {
       expect(snapshot).toMatchObject(expectedMessageSnapshots[idx])
     })
   })
+
+  it('updates nested message content through the reactive assistant message reference', async () => {
+    const adapter = createVueMessageAdapter()
+    const engine = createMessageEngine(adapter, {
+      plugins: silentDefaultPlugins,
+      responseProvider: mockResponseProvider(['hello', ' world']),
+    })
+
+    const contentSnapshots: string[] = []
+    let stopWatch = () => {}
+
+    watch(
+      adapter.messages,
+      (messages) => {
+        const assistantMessage = messages.find((message) => message.role === 'assistant')
+        stopWatch()
+        if (!assistantMessage) {
+          return
+        }
+
+        stopWatch = watch(
+          () => assistantMessage.content,
+          (content) => {
+            contentSnapshots.push(content as string)
+          },
+          { flush: 'sync', immediate: true },
+        )
+      },
+      { flush: 'sync', immediate: true },
+    )
+
+    await engine.sendMessage('ping')
+    stopWatch()
+
+    const distinctSnapshots = contentSnapshots.filter((content, index) => content !== contentSnapshots[index - 1])
+    expect(distinctSnapshots).toEqual(['', 'hello', 'hello world'])
+  })
 })
diff --git a/packages/kit/src/message/types.ts b/packages/kit/src/message/types.ts
@@ -75,12 +75,32 @@ export type MessageUpdateKinds = MessageUpdateKind | MessageUpdateKind[]
 export type MessageMutationRecipe = (draft: InternalMessageState, skipNotify: () => void) => void
 
 export interface MutateMessageStateFn {
+  /**
+   * 在受控上下文中修改消息状态，并按声明的更新类型分发状态变更通知。
+   *
+   * 这里的“通知”语义对应 `subscribe` 订阅链路，用于驱动依赖 engine 状态快照的观察者；
+   * 它并不等同于具体框架的响应式更新机制。对于 Vue 等运行时，界面更新可能同时依赖
+   * 框架自身的响应式追踪与 `subscribe` 侧的状态通知，两者职责不同，不应混用。
+   */
   (kinds: MessageUpdateKinds, recipe: MessageMutationRecipe): void
 }
 
 export interface MessageStateAdapter {
   initialize(initialState: InternalMessageState): void
   getState(): PublicMessageState
+  /**
+   * 创建一条适配当前运行时的消息对象。
+   *
+   * engine 和 core 插件里凡是“新建消息”的入口，都应统一走这个方法，
+   * 以便不同平台注入各自的运行时能力。
+   *
+   * 例如：
+   * - native/纯 TS 场景：直接返回原对象即可
+   *   `createMessage(message) { return message }`
+   * - Vue 场景：返回 reactive proxy，使后续对 message.content / message.state 的原地修改能够被追踪
+   *   `createMessage(message) { return reactive(message) }`
+   */
+  createMessage<T extends ChatMessage>(message: T): T
   mutate: MutateMessageStateFn
   subscribe(listener: (state: PublicMessageState) => void): () => void
   subscribe(kinds: MessageUpdateKinds, listener: (state: PublicMessageState) => void): () => void
@@ -89,7 +109,21 @@ export interface MessageStateAdapter {
 export interface BasePluginContext {
   getState(): PublicMessageState
   /**
-   * 使用 mutate 函数修改消息，才能正常触发消息更新通知。
+   * 创建一条适配当前运行时的消息对象。
+   *
+   * 插件在运行过程中如果需要主动创建并追加消息，应统一通过此接口构造消息实例，
+   * 而不是直接持有普通对象字面量。这样可以确保消息对象具备当前平台所要求的运行时能力。
+   *
+   * 对于采用响应式机制的平台（例如 Vue），该接口通常会返回带有响应式包装的消息实例。
+   * 如果插件绕过此接口直接创建普通对象，再参与后续的状态更新或原地字段修改，
+   * 可能导致消息内容、状态字段等变更无法被正确追踪。
+   */
+  createMessage<T extends ChatMessage>(message: T): T
+  /**
+   * 在受控上下文中修改状态，并触发与 `subscribe` 对应的状态更新通知。
+   *
+   * 该通知机制面向 engine 的订阅接口，而不是具体框架的响应式系统本身。
+   * 因此，在需要让 `subscribe` 观察者感知到变更时，应通过此接口完成状态写入。
    */
   mutate: MutateMessageStateFn
   abortSignal: AbortSignal
