docs: update docs directory structure
- Updated links in CONTRIBUTING.md and README.md to point to the correct Chinese documentation paths. - Removed outdated files including the English and Chinese versions of the branching strategy, contributing guide, and test plan documents. - Cleaned up references to non-existent documentation in the project structure to streamline the contributor experience.
This commit is contained in:
fullex
@@ -0,0 +1,81 @@
|
||||
# Cherry Studio Documentation / 文档
|
||||
|
||||
This directory contains the project documentation in multiple languages.
|
||||
|
||||
本目录包含多语言项目文档。
|
||||
|
||||
---
|
||||
|
||||
## Languages / 语言
|
||||
|
||||
- **[中文文档](./zh/README.md)** - Chinese Documentation
|
||||
- **English Documentation** - See sections below
|
||||
|
||||
---
|
||||
|
||||
## English Documentation
|
||||
|
||||
### Guides
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [Development Setup](./en/guides/development.md) | Development environment setup |
|
||||
| [Branching Strategy](./en/guides/branching-strategy.md) | Git branching workflow |
|
||||
| [i18n Guide](./en/guides/i18n.md) | Internationalization guide |
|
||||
| [Logging Guide](./en/guides/logging.md) | How to use the logger service |
|
||||
| [Test Plan](./en/guides/test-plan.md) | Test plan and release channels |
|
||||
|
||||
### References
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [App Upgrade Config](./en/references/app-upgrade.md) | Application upgrade configuration |
|
||||
| [CodeBlockView Component](./en/references/components/code-block-view.md) | Code block view component |
|
||||
| [Image Preview Components](./en/references/components/image-preview.md) | Image preview components |
|
||||
|
||||
---
|
||||
|
||||
## 中文文档
|
||||
|
||||
### 指南 (Guides)
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [开发环境设置](./zh/guides/development.md) | 开发环境配置 |
|
||||
| [贡献指南](./zh/guides/contributing.md) | 如何贡献代码 |
|
||||
| [分支策略](./zh/guides/branching-strategy.md) | Git 分支工作流 |
|
||||
| [测试计划](./zh/guides/test-plan.md) | 测试计划和发布通道 |
|
||||
| [国际化指南](./zh/guides/i18n.md) | 国际化开发指南 |
|
||||
| [日志使用指南](./zh/guides/logging.md) | 如何使用日志服务 |
|
||||
| [中间件开发](./zh/guides/middleware.md) | 如何编写中间件 |
|
||||
| [记忆功能](./zh/guides/memory.md) | 记忆功能使用指南 |
|
||||
| [赞助信息](./zh/guides/sponsor.md) | 赞助相关信息 |
|
||||
|
||||
### 参考 (References)
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [消息系统](./zh/references/message-system.md) | 消息系统架构和 API |
|
||||
| [数据库结构](./zh/references/database.md) | 数据库表结构 |
|
||||
| [服务](./zh/references/services.md) | 服务层文档 (KnowledgeService) |
|
||||
| [代码执行](./zh/references/code-execution.md) | 代码执行功能 |
|
||||
| [应用升级配置](./zh/references/app-upgrade.md) | 应用升级配置 |
|
||||
| [CodeBlockView 组件](./zh/references/components/code-block-view.md) | 代码块视图组件 |
|
||||
| [图像预览组件](./zh/references/components/image-preview.md) | 图像预览组件 |
|
||||
|
||||
---
|
||||
|
||||
## Missing Translations / 缺少翻译
|
||||
|
||||
The following documents are only available in Chinese and need English translations:
|
||||
|
||||
以下文档仅有中文版本，需要英文翻译：
|
||||
|
||||
- `guides/contributing.md`
|
||||
- `guides/memory.md`
|
||||
- `guides/middleware.md`
|
||||
- `guides/sponsor.md`
|
||||
- `references/message-system.md`
|
||||
- `references/database.md`
|
||||
- `references/services.md`
|
||||
- `references/code-execution.md`
|
||||
|
Before Width: | Height: | Size: 150 KiB After Width: | Height: | Size: 150 KiB |
|
Before Width: | Height: | Size: 40 KiB After Width: | Height: | Size: 40 KiB |
|
Before Width: | Height: | Size: 35 KiB After Width: | Height: | Size: 35 KiB |
|
Before Width: | Height: | Size: 563 KiB After Width: | Height: | Size: 563 KiB |
@@ -16,7 +16,7 @@ Cherry Studio implements a structured branching strategy to maintain code qualit
|
||||
- Only accepts documentation updates and bug fixes
|
||||
- Thoroughly tested before production deployment
|
||||
|
||||
For details about the `testplan` branch used in the Test Plan, please refer to the [Test Plan](testplan-en.md).
|
||||
For details about the `testplan` branch used in the Test Plan, please refer to the [Test Plan](./test-plan.md).
|
||||
|
||||
## Contributing Branches
|
||||
|
||||
@@ -18,11 +18,11 @@ The plugin has already been configured in the project — simply install it to g
|
||||
|
||||
### Demo
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## i18n Conventions
|
||||
|
||||
@@ -19,7 +19,7 @@ Users are welcome to submit issues or provide feedback through other channels fo
|
||||
|
||||
### Participating in the Test Plan
|
||||
|
||||
Developers should submit `PRs` according to the [Contributor Guide](../CONTRIBUTING.md) (and ensure the target branch is `main`). The repository maintainers will evaluate whether the `PR` should be included in the Test Plan based on factors such as the impact of the feature on the application, its importance, and whether broader testing is needed.
|
||||
Developers should submit `PRs` according to the [Contributor Guide](../../CONTRIBUTING.md) (and ensure the target branch is `main`). The repository maintainers will evaluate whether the `PR` should be included in the Test Plan based on factors such as the impact of the feature on the application, its importance, and whether broader testing is needed.
|
||||
|
||||
If the `PR` is added to the Test Plan, the repository maintainers will:
|
||||
|
||||
+1
-1
@@ -85,7 +85,7 @@ Main responsibilities:
|
||||
- **SvgPreview**: SVG image preview
|
||||
- **GraphvizPreview**: Graphviz diagram preview
|
||||
|
||||
All special view components share a common architecture for consistent user experience and functionality. For detailed information about these components and their implementation, see [Image Preview Components Documentation](./ImagePreview-en.md).
|
||||
All special view components share a common architecture for consistent user experience and functionality. For detailed information about these components and their implementation, see [Image Preview Components Documentation](./image-preview.md).
|
||||
|
||||
#### StatusBar
|
||||
|
||||
@@ -192,4 +192,4 @@ Image Preview Components integrate seamlessly with CodeBlockView:
|
||||
- Shared state management
|
||||
- Responsive layout adaptation
|
||||
|
||||
For more information about the overall CodeBlockView architecture, see [CodeBlockView Documentation](./CodeBlockView-en.md).
|
||||
For more information about the overall CodeBlockView architecture, see [CodeBlockView Documentation](./code-block-view.md).
|
||||
@@ -1,3 +0,0 @@
|
||||
# 消息的生命周期
|
||||
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
# 数据库设置字段
|
||||
|
||||
此文档包含部分字段的数据类型说明。
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------------------------------ | ------------------------------ | ------------ |
|
||||
| `translate:target:language` | `LanguageCode` | 翻译目标语言 |
|
||||
| `translate:source:language` | `LanguageCode` | 翻译源语言 |
|
||||
| `translate:bidirectional:pair` | `[LanguageCode, LanguageCode]` | 双向翻译对 |
|
||||
@@ -1,127 +0,0 @@
|
||||
# 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` 定义，大致如下：
|
||||
|
||||
```typescript
|
||||
{
|
||||
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 的地方):**
|
||||
|
||||
```typescript
|
||||
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` 中):**
|
||||
|
||||
```typescript
|
||||
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` 负责**触发状态变更**的异步流程，这对于维护清晰的应用架构至关重要。
|
||||
@@ -1,105 +0,0 @@
|
||||
# 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 的职责和它如何影响消息及块的状态至关重要。
|
||||
@@ -1,156 +0,0 @@
|
||||
# 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` 对象。
|
||||
|
||||
```typescript
|
||||
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` 结合使用，方便地在组件中获取消息数据、加载状态，并执行相关操作。
|
||||
@@ -70,7 +70,7 @@ Cherry Studio 是一款支持多个大语言模型（LLM）服务商的桌面客
|
||||
|
||||
👏 欢迎加入 [Telegram 群组](https://t.me/CherryStudioAI)｜[Discord](https://discord.gg/wez8HtpxqQ) | [QQ群(575014769)](https://qm.qq.com/q/lo0D4qVZKi)
|
||||
|
||||
❤️ 喜欢 Cherry Studio? 点亮小星星 🌟 或 [赞助开发者](sponsor.md)! ❤️
|
||||
❤️ 喜欢 Cherry Studio? 点亮小星星 🌟 或 [赞助开发者](./guides/sponsor.md)! ❤️
|
||||
|
||||
# 📖 使用教程
|
||||
|
||||
@@ -181,7 +181,7 @@ https://docs.cherry-ai.com
|
||||
6. **社区参与**：加入讨论并帮助用户
|
||||
7. **推广使用**：宣传 Cherry Studio
|
||||
|
||||
参考[分支策略](branching-strategy-zh.md)了解贡献指南
|
||||
参考[分支策略](./guides/branching-strategy.md)了解贡献指南
|
||||
|
||||
## 入门
|
||||
|
||||
@@ -190,7 +190,7 @@ https://docs.cherry-ai.com
|
||||
3. **提交更改**：提交并推送您的更改
|
||||
4. **打开 Pull Request**：描述您的更改和原因
|
||||
|
||||
有关更详细的指南，请参阅我们的 [贡献指南](CONTRIBUTING.zh.md)
|
||||
有关更详细的指南，请参阅我们的 [贡献指南](./guides/contributing.md)
|
||||
|
||||
感谢您的支持和贡献！
|
||||
|
||||
@@ -16,7 +16,7 @@ Cherry Studio 采用结构化的分支策略来维护代码质量并简化开发
|
||||
- 只接受文档更新和 bug 修复
|
||||
- 经过完整测试后可以发布到生产环境
|
||||
|
||||
关于测试计划所使用的`testplan`分支，请查阅[测试计划](testplan-zh.md)。
|
||||
关于测试计划所使用的`testplan`分支，请查阅[测试计划](./test-plan.md)。
|
||||
|
||||
## 贡献分支
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Cherry Studio 贡献者指南
|
||||
|
||||
[**English**](../CONTRIBUTING.md) | [**中文**](CONTRIBUTING.zh.md)
|
||||
[**English**](../../CONTRIBUTING.md) | **中文**
|
||||
|
||||
欢迎来到 Cherry Studio 的贡献者社区！我们致力于将 Cherry Studio 打造成一个长期提供价值的项目，并希望邀请更多的开发者加入我们的行列。无论您是经验丰富的开发者还是刚刚起步的初学者，您的贡献都将帮助我们更好地服务用户，提升软件质量。
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
|
||||
## 开始之前
|
||||
|
||||
请确保阅读了[行为准则](../CODE_OF_CONDUCT.md)和[LICENSE](../LICENSE)。
|
||||
请确保阅读了[行为准则](../../CODE_OF_CONDUCT.md)和[LICENSE](../../LICENSE)。
|
||||
|
||||
## 开始贡献
|
||||
|
||||
@@ -32,7 +32,7 @@
|
||||
|
||||
### 测试
|
||||
|
||||
未经测试的功能等同于不存在。为确保代码真正有效，应通过单元测试和功能测试覆盖相关流程。因此，在考虑贡献时，也请考虑可测试性。所有测试均可本地运行，无需依赖 CI。请参阅[开发者指南](dev.md#test)中的“Test”部分。
|
||||
未经测试的功能等同于不存在。为确保代码真正有效，应通过单元测试和功能测试覆盖相关流程。因此，在考虑贡献时，也请考虑可测试性。所有测试均可本地运行，无需依赖 CI。请参阅[开发者指南](./development.md#test)中的"Test"部分。
|
||||
|
||||
### 拉取请求的自动化测试
|
||||
|
||||
@@ -60,11 +60,11 @@ git commit --signoff -m "Your commit message"
|
||||
|
||||
### 获取代码审查/合并
|
||||
|
||||
维护者在此帮助您在合理时间内实现您的用例。他们会尽力在合理时间内审查您的代码并提供建设性反馈。但如果您在审查过程中受阻，或认为您的 Pull Request 未得到应有的关注，请通过 Issue 中的评论或者[社群](README.zh.md#-community)联系我们
|
||||
维护者在此帮助您在合理时间内实现您的用例。他们会尽力在合理时间内审查您的代码并提供建设性反馈。但如果您在审查过程中受阻，或认为您的 Pull Request 未得到应有的关注，请通过 Issue 中的评论或者[社群](../README.md#-community)联系我们
|
||||
|
||||
### 参与测试计划
|
||||
|
||||
测试计划旨在为用户提供更稳定的应用体验和更快的迭代速度，详细情况请参阅[测试计划](testplan-zh.md)。
|
||||
测试计划旨在为用户提供更稳定的应用体验和更快的迭代速度，详细情况请参阅[测试计划](./test-plan.md)。
|
||||
|
||||
### 其他建议
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# 🖥️ Develop
|
||||
|
||||
## IDE Setup
|
||||
|
||||
- Editor: [Cursor](https://www.cursor.com/), etc. Any VS Code compatible editor.
|
||||
- Linter: [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
|
||||
- Formatter: [Biome](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
|
||||
|
||||
## Project Setup
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
### Setup Node.js
|
||||
|
||||
Download and install [Node.js v22.x.x](https://nodejs.org/en/download)
|
||||
|
||||
### Setup Yarn
|
||||
|
||||
```bash
|
||||
corepack enable
|
||||
corepack prepare yarn@4.9.1 --activate
|
||||
```
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
```bash
|
||||
yarn install
|
||||
```
|
||||
|
||||
### ENV
|
||||
|
||||
```bash
|
||||
copy .env.example .env
|
||||
```
|
||||
|
||||
### Start
|
||||
|
||||
```bash
|
||||
yarn dev
|
||||
```
|
||||
|
||||
### Debug
|
||||
|
||||
```bash
|
||||
yarn debug
|
||||
```
|
||||
|
||||
Then input chrome://inspect in browser
|
||||
|
||||
### Test
|
||||
|
||||
```bash
|
||||
yarn test
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
# For windows
|
||||
$ yarn build:win
|
||||
|
||||
# For macOS
|
||||
$ yarn build:mac
|
||||
|
||||
# For Linux
|
||||
$ yarn build:linux
|
||||
```
|
||||
@@ -15,11 +15,11 @@ i18n ally是一个强大的VSCode插件，它能在开发阶段提供实时反
|
||||
|
||||
### 效果展示
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## i18n 约定
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
|
||||
### 参与测试计划
|
||||
|
||||
开发者按照[贡献者指南](CONTRIBUTING.zh.md)要求正常提交`PR`（并注意提交target为`main`）。仓库维护者会综合考虑（例如该功能对应用的影响程度，功能的重要性，是否需要更广泛的测试等），决定该`PR`是否应加入测试计划。
|
||||
开发者按照[贡献者指南](./contributing.md)要求正常提交`PR`（并注意提交target为`main`）。仓库维护者会综合考虑（例如该功能对应用的影响程度，功能的重要性，是否需要更广泛的测试等），决定该`PR`是否应加入测试计划。
|
||||
|
||||
若该`PR`加入测试计划，仓库维护者会做如下操作：
|
||||
|
||||
+1
-1
@@ -85,7 +85,7 @@ graph TD
|
||||
- **SvgPreview**: SVG 图像预览
|
||||
- **GraphvizPreview**: Graphviz 图表预览
|
||||
|
||||
所有特殊视图组件共享通用架构，以确保一致的用户体验和功能。有关这些组件及其实现的详细信息，请参阅 [图像预览组件文档](./ImagePreview-zh.md)。
|
||||
所有特殊视图组件共享通用架构，以确保一致的用户体验和功能。有关这些组件及其实现的详细信息，请参阅[图像预览组件文档](./image-preview.md)。
|
||||
|
||||
#### StatusBar 状态栏
|
||||
|
||||
@@ -192,4 +192,4 @@ const { containerRef, error, isLoading, triggerRender, cancelRender, clearError,
|
||||
- 共享状态管理
|
||||
- 响应式布局适应
|
||||
|
||||
有关整体 CodeBlockView 架构的更多信息，请参阅 [CodeBlockView 文档](./CodeBlockView-zh.md)。
|
||||
有关整体 CodeBlockView 架构的更多信息，请参阅 [CodeBlockView 文档](./code-block-view.md)。
|
||||
@@ -1,6 +1,24 @@
|
||||
# `translate_languages` 表技术文档
|
||||
# 数据库参考文档
|
||||
|
||||
## 📄 概述
|
||||
本文档介绍 Cherry Studio 的数据库结构，包括设置字段和翻译语言表。
|
||||
|
||||
---
|
||||
|
||||
## 设置字段 (settings)
|
||||
|
||||
此部分包含设置相关字段的数据类型说明。
|
||||
|
||||
### 翻译相关字段
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------------------------------ | ------------------------------ | ------------ |
|
||||
| `translate:target:language` | `LanguageCode` | 翻译目标语言 |
|
||||
| `translate:source:language` | `LanguageCode` | 翻译源语言 |
|
||||
| `translate:bidirectional:pair` | `[LanguageCode, LanguageCode]` | 双向翻译对 |
|
||||
|
||||
---
|
||||
|
||||
## 翻译语言表 (translate_languages)
|
||||
|
||||
`translate_languages` 记录用户自定义的的语言类型（`Language`）。
|
||||
|
||||
@@ -0,0 +1,404 @@
|
||||
# 消息系统
|
||||
|
||||
本文档介绍 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` 定义，大致如下：
|
||||
|
||||
```typescript
|
||||
{
|
||||
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 的地方):**
|
||||
|
||||
```typescript
|
||||
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` 中):**
|
||||
|
||||
```typescript
|
||||
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` 对象。
|
||||
|
||||
```typescript
|
||||
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` 结合使用，方便地在组件中获取消息数据、加载状态，并执行相关操作。
|
||||
Reference in New Issue
Block a user