cherry-studio/docs/zh/references/message-system.md

消息系统

本文档介绍 Cherry Studio 的消息系统架构，包括消息生命周期、状态管理和操作接口。

消息的生命周期

---

messageBlock.ts 使用指南

该文件定义了用于管理应用程序中所有 MessageBlock 实体的 Redux Slice。它使用 Redux Toolkit 的 createSlice 和 createEntityAdapter 来高效地处理规范化的状态，并提供了一系列 actions 和 selectors 用于与消息块数据交互。

核心目标

• 状态管理: 集中管理所有 MessageBlock 的状态。MessageBlock 代表消息中的不同内容单元（如文本、代码、图片、引用等）。
• 规范化: 使用 createEntityAdapter 将 MessageBlock 数据存储在规范化的结构中（{ ids: [], entities: {} }），这有助于提高性能和简化更新逻辑。
• 可预测性: 提供明确的 actions 来修改状态，并通过 selectors 安全地访问状态。

关键概念

• Slice (createSlice): Redux Toolkit 的核心 API，用于创建包含 reducer 逻辑、action creators 和初始状态的 Redux 模块。
• Entity Adapter (createEntityAdapter): Redux Toolkit 提供的工具，用于简化对规范化数据的 CRUD（创建、读取、更新、删除）操作。它会自动生成 reducer 函数和 selectors。
• Selectors: 用于从 Redux store 中派生和计算数据的函数。Selectors 可以被记忆化（memoized），以提高性能。

State 结构

messageBlocks slice 的状态结构由 createEntityAdapter 定义，大致如下：

{
  ids: string[]; // 存储所有 MessageBlock ID 的有序列表
  entities: { [id: string]: MessageBlock }; // 按 ID 存储 MessageBlock 对象的字典
  loadingState: 'idle' | 'loading' | 'succeeded' | 'failed'; // (可选) 其他状态，如加载状态
  error: string | null; // (可选) 错误信息
}

Actions

该 slice 导出以下 actions (由 createSlice 和 createEntityAdapter 自动生成或自定义)：

• upsertOneBlock(payload: MessageBlock):

  • 添加一个新的 MessageBlock 或更新一个已存在的 MessageBlock。如果 payload 中的 id 已存在，则执行更新；否则执行插入。

• upsertManyBlocks(payload: MessageBlock[]):

  • 添加或更新多个 MessageBlock。常用于批量加载数据（例如，加载一个 Topic 的所有消息块）。

• removeOneBlock(payload: string):

  • 根据提供的 id (payload) 移除单个 MessageBlock。

• removeManyBlocks(payload: string[]):

  • 根据提供的 id 数组 (payload) 移除多个 MessageBlock。常用于删除消息或清空 Topic 时清理相关的块。

• removeAllBlocks():

  • 移除 state 中的所有 MessageBlock 实体。

• updateOneBlock(payload: { id: string; changes: Partial<MessageBlock> }):

  • 更新一个已存在的 MessageBlock。payload 需要包含块的 id 和一个包含要更改的字段的 changes 对象。

• setMessageBlocksLoading(payload: 'idle' | 'loading'):

  • (自定义) 设置 loadingState 属性。

• setMessageBlocksError(payload: string):

  • (自定义) 设置 loadingState 为 'failed' 并记录错误信息。

使用示例 (在 Thunk 或其他 Dispatch 的地方):

import { upsertOneBlock, removeManyBlocks, updateOneBlock } from './messageBlock'
import store from './store' // 假设这是你的 Redux store 实例

// 添加或更新一个块
const newBlock: MessageBlock = {
  /* ... block data ... */
}
store.dispatch(upsertOneBlock(newBlock))

// 更新一个块的内容
store.dispatch(updateOneBlock({ id: blockId, changes: { content: 'New content' } }))

// 删除多个块
const blockIdsToRemove = ['id1', 'id2']
store.dispatch(removeManyBlocks(blockIdsToRemove))

Selectors

该 slice 导出由 createEntityAdapter 生成的基础 selectors，并通过 messageBlocksSelectors 对象访问：

• messageBlocksSelectors.selectIds(state: RootState): string[]: 返回包含所有块 ID 的数组。
• messageBlocksSelectors.selectEntities(state: RootState): { [id: string]: MessageBlock }: 返回块 ID 到块对象的映射字典。
• messageBlocksSelectors.selectAll(state: RootState): MessageBlock[]: 返回包含所有块对象的数组。
• messageBlocksSelectors.selectTotal(state: RootState): number: 返回块的总数。
• messageBlocksSelectors.selectById(state: RootState, id: string): MessageBlock | undefined: 根据 ID 返回单个块对象，如果找不到则返回 undefined。

此外，还提供了一个自定义的、记忆化的 selector：

• selectFormattedCitationsByBlockId(state: RootState, blockId: string | undefined): Citation[]:
  • 接收一个 blockId。
  • 如果该 ID 对应的块是 CITATION 类型，则提取并格式化其包含的引用信息（来自网页搜索、知识库等），进行去重和重新编号，最后返回一个 Citation[] 数组，用于在 UI 中显示。
  • 如果块不存在或类型不匹配，返回空数组 []。
  • 这个 selector 封装了处理不同引用来源（Gemini, OpenAI, OpenRouter, Zhipu 等）的复杂逻辑。

使用示例 (在 React 组件或 useSelector 中):

import { useSelector } from 'react-redux'
import { messageBlocksSelectors, selectFormattedCitationsByBlockId } from './messageBlock'
import type { RootState } from './store'

// 获取所有块
const allBlocks = useSelector(messageBlocksSelectors.selectAll)

// 获取特定 ID 的块
const specificBlock = useSelector((state: RootState) => messageBlocksSelectors.selectById(state, someBlockId))

// 获取特定引用块格式化后的引用列表
const formattedCitations = useSelector((state: RootState) => selectFormattedCitationsByBlockId(state, citationBlockId))

// 在组件中使用引用数据
// {formattedCitations.map(citation => ...)}

集成

messageBlock.ts slice 通常与 messageThunk.ts 中的 Thunks 紧密协作。Thunks 负责处理异步逻辑（如 API 调用、数据库操作），并在需要时 dispatch messageBlock slice 的 actions 来更新状态。例如，当 messageThunk 接收到流式响应时，它会 dispatch upsertOneBlock 或 updateOneBlock 来实时更新对应的 MessageBlock。同样，删除消息的 Thunk 会 dispatch removeManyBlocks。

理解 messageBlock.ts 的职责是管理状态本身，而 messageThunk.ts 负责触发状态变更的异步流程，这对于维护清晰的应用架构至关重要。

---

messageThunk.ts 使用指南

该文件包含用于管理应用程序中消息流、处理助手交互以及同步 Redux 状态与 IndexedDB 数据库的核心 Thunk Action Creators。主要围绕 Message 和 MessageBlock 对象进行操作。

核心功能

1. 发送/接收消息: 处理用户消息的发送，触发助手响应，并流式处理返回的数据，将其解析为不同的 MessageBlock。
2. 状态管理: 确保 Redux store 中的消息和消息块状态与 IndexedDB 中的持久化数据保持一致。
3. 消息操作: 提供删除、重发、重新生成、编辑后重发、追加响应、克隆等消息生命周期管理功能。
4. Block 处理: 动态创建、更新和保存各种类型的 MessageBlock（文本、思考过程、工具调用、引用、图片、错误、翻译等）。

主要 Thunks

以下是一些关键的 Thunk 函数及其用途：

1. sendMessage(userMessage, userMessageBlocks, assistant, topicId)

   • 用途: 发送一条新的用户消息。
   • 流程:
     • 保存用户消息 (userMessage) 及其块 (userMessageBlocks) 到 Redux 和 DB。
     • 检查 @mentions 以确定是单模型响应还是多模型响应。
     • 创建助手消息(们)的存根 (Stub)。
     • 将存根添加到 Redux 和 DB。
     • 将核心处理逻辑 fetchAndProcessAssistantResponseImpl 添加到该 topicId 的队列中以获取实际响应。
   • Block 相关: 主要处理用户消息的初始 MessageBlock 保存。

2. fetchAndProcessAssistantResponseImpl(dispatch, getState, topicId, assistant, assistantMessage)

   • 用途: (内部函数) 获取并处理单个助手响应的核心逻辑，被 sendMessage, resend..., regenerate..., append... 等调用。
   • 流程:
     • 设置 Topic 加载状态。
     • 准备上下文消息。
     • 调用 fetchChatCompletion API 服务。
     • 使用 createStreamProcessor 处理流式响应。
     • 通过各种回调 (onTextChunk, onThinkingChunk, onToolCallComplete, onImageGenerated, onError, onComplete 等) 处理不同类型的事件。
   • Block 相关:
     • 根据流事件创建初始 UNKNOWN 块。
     • 实时创建和更新 MAIN_TEXT 和 THINKING 块，使用 throttledBlockUpdate 和 throttledBlockDbUpdate 进行节流更新。
     • 创建 TOOL, CITATION, IMAGE, ERROR 等类型的块。
     • 在事件完成时（如 onTextComplete, onToolCallComplete）将块状态标记为 SUCCESS 或 ERROR，并使用 saveUpdatedBlockToDB 保存最终状态。
     • 使用 handleBlockTransition 管理非流式块（如 TOOL, CITATION）的添加和状态更新。

3. loadTopicMessagesThunk(topicId, forceReload)

   • 用途: 从数据库加载指定主题的所有消息及其关联的 MessageBlock。
   • 流程:
     • 从 DB 获取 Topic 及其 messages 列表。
     • 根据消息 ID 列表从 DB 获取所有相关的 MessageBlock。
     • 使用 upsertManyBlocks 将块更新到 Redux。
     • 将消息更新到 Redux。
   • Block 相关: 负责将持久化的 MessageBlock 加载到 Redux 状态。

4. 删除 Thunks

   • deleteSingleMessageThunk(topicId, messageId): 删除单个消息及其所有 MessageBlock。
   • deleteMessageGroupThunk(topicId, askId): 删除一个用户消息及其所有相关的助手响应消息和它们的所有 MessageBlock。
   • clearTopicMessagesThunk(topicId): 清空主题下的所有消息及其所有 MessageBlock。
   • Block 相关: 从 Redux 和 DB 中移除指定的 MessageBlock。

5. 重发/重新生成 Thunks

   • resendMessageThunk(topicId, userMessageToResend, assistant): 重发用户消息。会重置（清空 Block 并标记为 PENDING）所有与该用户消息关联的助手响应，然后重新请求生成。
   • resendUserMessageWithEditThunk(topicId, originalMessage, mainTextBlockId, editedContent, assistant): 用户编辑消息内容后重发。先更新用户消息的 MAIN_TEXT 块内容，然后调用 resendMessageThunk。
   • regenerateAssistantResponseThunk(topicId, assistantMessageToRegenerate, assistant): 重新生成单个助手响应。重置该助手消息（清空 Block 并标记为 PENDING），然后重新请求生成。
   • Block 相关: 删除旧的 MessageBlock，并在重新生成过程中创建新的 MessageBlock。

6. appendAssistantResponseThunk(topicId, existingAssistantMessageId, newModel, assistant)

   • 用途: 在已有的对话上下文中，针对同一个用户问题，使用新选择的模型追加一个新的助手响应。
   • 流程:
     • 找到现有助手消息以获取原始 askId。
     • 创建使用 newModel 的新助手消息存根（使用相同的 askId）。
     • 添加新存根到 Redux 和 DB。
     • 将 fetchAndProcessAssistantResponseImpl 添加到队列以生成新响应。
   • Block 相关: 为新的助手响应创建全新的 MessageBlock。

7. cloneMessagesToNewTopicThunk(sourceTopicId, branchPointIndex, newTopic)

   • 用途: 将源主题的部分消息（及其 Block）克隆到一个已存在的新主题中。
   • 流程:
     • 复制指定索引前的消息。
     • 为所有克隆的消息和 Block 生成新的 UUID。
     • 正确映射克隆消息之间的 askId 关系。
     • 复制 MessageBlock 内容，更新其 messageId 指向新的消息 ID。
     • 更新文件引用计数（如果 Block 是文件或图片）。
     • 将克隆的消息和 Block 保存到新主题的 Redux 状态和 DB 中。
   • Block 相关: 创建 MessageBlock 的副本，并更新其 ID 和 messageId。

8. initiateTranslationThunk(messageId, topicId, targetLanguage, sourceBlockId?, sourceLanguage?)

   • 用途: 为指定消息启动翻译流程，创建一个初始的 TRANSLATION 类型的 MessageBlock。
   • 流程:
     • 创建一个状态为 STREAMING 的 TranslationMessageBlock。
     • 将其添加到 Redux 和 DB。
     • 更新原消息的 blocks 列表以包含新的翻译块 ID。
   • Block 相关: 创建并保存一个占位的 TranslationMessageBlock。实际翻译内容的获取和填充需要后续步骤。

内部机制和注意事项

• 数据库交互: 通过 saveMessageAndBlocksToDB, updateExistingMessageAndBlocksInDB, saveUpdatesToDB, saveUpdatedBlockToDB, throttledBlockDbUpdate 等辅助函数与 IndexedDB (db) 交互，确保数据持久化。
• 状态同步: Thunks 负责协调 Redux Store 和 IndexedDB 之间的数据一致性。
• 队列 (getTopicQueue): 使用 AsyncQueue 确保对同一主题的操作（尤其是 API 请求）按顺序执行，避免竞态条件。
• 节流 (throttle): 对流式响应中频繁的 Block 更新（文本、思考）使用 lodash.throttle 优化性能，减少 Redux dispatch 和 DB 写入次数。
• 错误处理: fetchAndProcessAssistantResponseImpl 内的回调函数（特别是 onError）处理流处理和 API 调用中可能出现的错误，并创建 ERROR 类型的 MessageBlock。

开发者在使用这些 Thunks 时，通常需要提供 dispatch, getState (由 Redux Thunk 中间件注入)，以及如 topicId, assistant 配置对象, 相关的 Message 或 MessageBlock 对象/ID 等参数。理解每个 Thunk 的职责和它如何影响消息及块的状态至关重要。

---

useMessageOperations.ts 使用指南

该文件定义了一个名为 useMessageOperations 的自定义 React Hook。这个 Hook 的主要目的是为 React 组件提供一个便捷的接口，用于执行与特定主题（Topic）相关的各种消息操作。它封装了调用 Redux Thunks (messageThunk.ts) 和 Actions (newMessage.ts, messageBlock.ts) 的逻辑，简化了组件与消息数据交互的代码。

核心目标

• 封装: 将复杂的消息操作逻辑（如删除、重发、重新生成、编辑、翻译等）封装在易于使用的函数中。
• 简化: 让组件可以直接调用这些操作函数，而无需直接与 Redux dispatch 或 Thunks 交互。
• 上下文关联: 所有操作都与传入的 topic 对象相关联，确保操作作用于正确的主题。

如何使用

在你的 React 函数组件中，导入并调用 useMessageOperations Hook，并传入当前活动的 Topic 对象。

import React from 'react';
import { useMessageOperations } from '@renderer/hooks/useMessageOperations';
import type { Topic, Message, Assistant, Model } from '@renderer/types';

interface MyComponentProps {
  currentTopic: Topic;
  currentAssistant: Assistant;
}

function MyComponent({ currentTopic, currentAssistant }: MyComponentProps) {
  const {
    deleteMessage,
    resendMessage,
    regenerateAssistantMessage,
    appendAssistantResponse,
    getTranslationUpdater,
    createTopicBranch,
    // ... 其他操作函数
  } = useMessageOperations(currentTopic);

  const handleDelete = (messageId: string) => {
    deleteMessage(messageId);
  };

  const handleResend = (message: Message) => {
    resendMessage(message, currentAssistant);
  };

  const handleAppend = (existingMsg: Message, newModel: Model) => {
    appendAssistantResponse(existingMsg, newModel, currentAssistant);
  }

  // ... 在组件中使用其他操作函数

  return (
    <div>
      {/* Component UI */}
      <button onClick={() => handleDelete('some-message-id')}>Delete Message</button>
      {/* ... */}
    </div>
  );
}

返回值

useMessageOperations(topic) Hook 返回一个包含以下函数和值的对象：

• deleteMessage(id: string):

  • 删除指定 id 的单个消息。
  • 内部调用 deleteSingleMessageThunk。

• deleteGroupMessages(askId: string):

  • 删除与指定 askId 相关联的一组消息（通常是用户提问及其所有助手回答）。
  • 内部调用 deleteMessageGroupThunk。

• editMessage(messageId: string, updates: Partial<Message>):

  • 更新指定 messageId 的消息的部分属性。
  • 注意: 目前主要用于更新 Redux 状态
  • 内部调用 newMessagesActions.updateMessage。

• resendMessage(message: Message, assistant: Assistant):

  • 重新发送指定的用户消息 (message)，这将触发其所有关联助手响应的重新生成。
  • 内部调用 resendMessageThunk。

• resendUserMessageWithEdit(message: Message, editedContent: string, assistant: Assistant):

  • 在用户消息的主要文本块被编辑后，重新发送该消息。
  • 会先查找消息的 MAIN_TEXT 块 ID，然后调用 resendUserMessageWithEditThunk。

• clearTopicMessages(_topicId?: string):

  • 清除当前主题（或可选的指定 _topicId）下的所有消息。
  • 内部调用 clearTopicMessagesThunk。

• createNewContext():

  • 发出一个全局事件 (EVENT_NAMES.NEW_CONTEXT)，通常用于通知 UI 清空显示，准备新的上下文。不直接修改 Redux 状态。

• displayCount:

  • (非操作函数) 从 Redux store 中获取当前的 displayCount 值。

• pauseMessages():

  • 尝试中止当前主题中正在进行的消息生成（状态为 processing 或 pending）。
  • 通过查找相关的 askId 并调用 abortCompletion 来实现。
  • 同时会 dispatch setTopicLoading action 将加载状态设为 false。

• resumeMessage(message: Message, assistant: Assistant):

  • 恢复/重新发送一个用户消息。目前实现为直接调用 resendMessage。

• regenerateAssistantMessage(message: Message, assistant: Assistant):

  • 重新生成指定的助手消息 (message) 的响应。
  • 内部调用 regenerateAssistantResponseThunk。

• appendAssistantResponse(existingAssistantMessage: Message, newModel: Model, assistant: Assistant):

  • 针对 existingAssistantMessage 所回复的同一用户提问，使用 newModel 追加一个新的助手响应。
  • 内部调用 appendAssistantResponseThunk。

• getTranslationUpdater(messageId: string, targetLanguage: string, sourceBlockId?: string, sourceLanguage?: string):

  • 用途: 获取一个用于逐步更新翻译块内容的函数。
  • 流程:
    1. 内部调用 initiateTranslationThunk 来创建或获取一个 TRANSLATION 类型的 MessageBlock，并获取其 blockId。
    2. 返回一个异步更新函数。
  • 返回的更新函数 (accumulatedText: string, isComplete?: boolean) => void:
    • 接收累积的翻译文本和完成状态。
    • 调用 updateOneBlock 更新 Redux 中的翻译块内容和状态 (STREAMING 或 SUCCESS)。
    • 调用 throttledBlockDbUpdate 将更新（节流地）保存到数据库。
  • 如果初始化失败（Thunk 返回 undefined），则此函数返回 null。

• createTopicBranch(sourceTopicId: string, branchPointIndex: number, newTopic: Topic):

  • 创建一个主题分支，将 sourceTopicId 主题中 branchPointIndex 索引之前的消息克隆到 newTopic 中。
  • 注意: newTopic 对象必须是调用此函数之前已经创建并添加到 Redux 和数据库中的。
  • 内部调用 cloneMessagesToNewTopicThunk。

依赖

• topic: Topic: 必须传入当前操作上下文的主题对象。Hook 返回的操作函数将始终作用于这个主题的 topic.id。
• Redux dispatch: Hook 内部使用 useAppDispatch 获取 dispatch 函数来调用 actions 和 thunks。

相关 Hooks

在同一文件中还定义了两个辅助 Hook：

• useTopicMessages(topic: Topic):

  • 使用 selectMessagesForTopic selector 来获取并返回指定主题的消息列表。

• useTopicLoading(topic: Topic):

  • 使用 selectNewTopicLoading selector 来获取并返回指定主题的加载状态。

这些 Hook 可以与 useMessageOperations 结合使用，方便地在组件中获取消息数据、加载状态，并执行相关操作。