8.3 · 聊天项管理（Chat Item Management）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节8.3 状态全文译文模块界面与交互、工具、记忆与模型调用、检索、召回与知识系统、接口与服务契约

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节Chat Item Management 上一章8.2 下一章8.4

源码线索

backend/open_webui/models/chats.py
backend/open_webui/routers/chats.py
src/lib/apis/chats/index.ts
src/lib/components/chat/MessageInput/InputMenu/Chats.svelte
src/lib/components/chat/MessageInput/InputMenu/Knowledge.svelte
src/lib/components/chat/MessageInput/InputMenu/Notes.svelte
src/lib/components/chat/Settings/Interface/ManageFloatingActionButtonsModal.svelte
src/lib/components/chat/Settings/Interface/ManageImageCompressionModal.svelte
src/lib/components/chat/Settings/SyncStatsModal.svelte
src/lib/components/chat/Tags.svelte

模块标签

界面与交互
工具、记忆与模型调用
检索、召回与知识系统
接口与服务契约
频道、笔记与协作

中文译文

聊天项管理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/8.3-chat-item-management

翻译时间：2026-06-09T16:09:38.216Z

翻译模型：deepseek-chat

原文字符数：11501

项目：Open WebUI (open-webui)

---

聊天项管理

目的与范围

本文档描述 Open WebUI 侧边栏中的聊天项管理系统，涵盖聊天会话的显示、组织和用户操作方式。聊天项是侧边栏导航中显示的单个会话条目。本页重点介绍单个聊天项的显示、加载及执行的操作，包括置顶、归档、重命名和删除。

关于整体侧边栏架构和导航结构，请参见侧边栏组件架构。关于将聊天组织到文件夹的详细信息，请参见文件夹系统。关于用于重新组织聊天的拖放机制，请参见拖放系统。

聊天列表数据模型

聊天列表管理系统通过 Svelte store 在全局状态中维护多个不同的聊天集合。后端将这些数据存储在 chat 表中 backend/open_webui/models/chats.py:40-41。

Store	用途	来源
`chats`	常规（未置顶）聊天列表	`getChatList()` API `src/lib/apis/chats/index.ts:99-104`
`pinnedChats`	单独显示的置顶聊天	`getPinnedChatList()` API `src/lib/apis/chats/index.ts:335-337`
`activeChatIds`	具有活动任务（如流式传输）的聊天 ID 集合	实时 Socket.IO 更新 `src/lib/stores/index.ts:32`
`tags`	用于筛选/组织的全局标签列表	`getAllTags()` API `src/lib/apis/chats/index.ts:503-505`

每个聊天项由 ChatModel backend/open_webui/models/chats.py:73-95 或 ChatResponse backend/open_webui/models/chats.py:157-172 Pydantic 模式表示，其中包含 archived、pinned 和 folder_id 等元数据。

来源： src/lib/components/layout/Sidebar.svelte:7-33、src/lib/components/layout/Sidebar/ChatItem.svelte:21-39、backend/open_webui/models/chats.py:40-172

聊天列表初始化与加载

初始化过程确保侧边栏在挂载时填充用户的对话历史、置顶项和相关标签。

graph TB
    subgraph "Sidebar.svelte [onMount]"
        initChatList["initChatList()"]
    end

    subgraph "initChatList() 逻辑"
        reset["重置 currentChatPage=1<br/>scrollPaginationEnabled=false"]
        folders["initFolders()"]
        parallel["Promise.all() API 调用"]
        tagsAPI["getAllTags(token)"]
        pinnedAPI["getPinnedChatList(token)"]
        chatsAPI["getChatList(token, page)"]

        parallel --> tagsAPI
        parallel --> pinnedAPI
        parallel --> chatsAPI
    end

    subgraph "Store 更新"
        updateTags["tags.set(_tags)"]
        updatePinned["pinnedChats.set(_pinnedChats)"]
        updateChats["chats.set(_chats)"]
    end

    initChatList --> reset
    reset --> folders
    folders --> parallel
    tagsAPI --> updateTags
    pinnedAPI --> updatePinned
    chatsAPI --> updateChats
    updateChats --> enablePag["scrollPaginationEnabled.set(true)"]

Sidebar.svelte 中的 initChatList 函数通过重置分页并同时获取数据来编排完整的聊天列表初始化，以最大限度地减少加载时间 src/lib/components/layout/Sidebar.svelte:211-239。

基于滚动的分页

Open WebUI 使用基于滚动的分页系统来处理大量对话历史。后端通过 limit 和 skip 参数处理 get_session_user_chat_list 端点 backend/open_webui/routers/chats.py:52-73。

const loadMoreChats = async () => {
    chatListLoading = true;
    currentChatPage.set($currentChatPage + 1);

    let newChatList = await getChatList(localStorage.token, $currentChatPage);

    // 一旦到达列表底部（无结果）
    // 则无需继续查询
    allChatsLoaded = newChatList.length === 0;
    await chats.set([...($chats ? $chats : []), ...newChatList]);

    chatListLoading = false;
};

来源： src/lib/components/layout/Sidebar.svelte:241-255、backend/open_webui/routers/chats.py:62-73

聊天项组件结构

ChatItem.svelte 组件是显示对话的主要单元。它使用 viewedAt 在本地跟踪已读状态，以防止服务器状态过期时 UI 闪烁 src/lib/components/layout/Sidebar/ChatItem.svelte:94-105。

graph LR
    subgraph "ChatItem.svelte [组件]"
        state["内部状态：<br/>mouseOver, confirmEdit, generating"]

        subgraph "UI 逻辑"
            formatTime["formatTimeAgo(timestamp)"]
            editTitle["editChatTitle(id, title)"]
            deleteHandler["deleteChatHandler(id)"]
        end

        subgraph "渲染逻辑"
            activeIndicator["$activeChatIds.has(id) 旋转器"]
            titleDisplay["聊天标题（可编辑）"]
            menu["ChatMenu.svelte"]
        end
    end

    API_CHATS["/api/v1/chats"]

    editTitle --> API_CHATS
    deleteHandler --> API_CHATS

未读状态逻辑

如果聊天不是当前活动聊天、不在活动任务列表中，并且其 updatedAt 时间戳大于 effectiveReadAt（服务器端 lastReadAt 和客户端 viewedAt 的最大值），则该聊天被标记为未读 src/lib/components/layout/Sidebar/ChatItem.svelte:100-105。

来源： src/lib/components/layout/Sidebar/ChatItem.svelte:68-105

核心聊天操作

重命名与标题生成

用户可以手动重命名聊天，或使用 AI 生成标题。

手动重命名：双击触发输入字段。提交时，editChatTitle 调用 updateChatById src/lib/components/layout/Sidebar/ChatItem.svelte:120-138。
AI 标题生成：generateTitleHandler 调用 generateTitle API src/lib/components/layout/Sidebar/ChatItem.svelte:304-339。

置顶与取消置顶

聊天可以置顶到侧边栏顶部。此状态通过 toggleChatPinnedStatusById 切换 src/lib/components/layout/Sidebar/ChatMenu.svelte:51-54。后端更新 chat 表中的 pinned 列 backend/open_webui/models/chats.py:53。

归档与删除

归档：archiveChatHandler 调用 archiveChatById src/lib/components/layout/Sidebar/ChatItem.svelte:189-209。归档聊天的 archived 标志在数据库中设置为 True backend/open_webui/models/chats.py:52。
删除：deleteChatHandler 调用 deleteChatById。如果被删除的聊天是活动聊天，用户将被重定向到首页路由 src/lib/components/layout/Sidebar/ChatItem.svelte:163-185。

克隆

克隆使用 cloneChatById 创建对话副本，并将用户重定向到新 ID src/lib/components/layout/Sidebar/ChatItem.svelte:140-159。

来源： src/lib/components/layout/Sidebar/ChatItem.svelte:120-209、backend/open_webui/models/chats.py:52-53

搜索与筛选

侧边栏通过 SearchModal.svelte 提供搜索界面。

搜索功能

API 搜索：调用 getChatListBySearchText，该函数查询后端以查找与输入匹配的聊天标题 src/lib/apis/chats/index.ts:130-132。
标签筛选：用户可以使用 getChatListByTagName 按标签筛选聊天 src/lib/apis/chats/index.ts:468-470。

来源： src/lib/components/layout/Sidebar.svelte:47、src/lib/apis/chats/index.ts:130-470

导出与下载

用户可以将对话导出为多种格式。

格式	实现	特性
纯文本 (.txt)	`getChatAsText`	将历史记录转换为 Markdown 风格字符串 `src/lib/components/layout/Navbar/Menu.svelte:54-62`。
PDF (.pdf)	`jsPDF` 和 `html2canvas-pro`	通过克隆 DOM 元素并将其渲染到画布来支持"样式化导出" `src/lib/components/layout/Navbar/Menu.svelte:74-180`。
JSON (.json)	`downloadJSONExport`	导出完整聊天对象以进行备份/导入 `src/lib/components/layout/Navbar/Menu.svelte:230-236`。

来源： src/lib/components/layout/Navbar/Menu.svelte:54-236、src/lib/components/layout/Sidebar/ChatMenu.svelte:60-196

拖放集成

聊天项已集成到拖放系统中。

拖拽开始：ChatItem.svelte 设置一个 1x1 透明图像作为拖拽预览，以避免视觉杂乱，并序列化聊天 ID src/lib/components/layout/Sidebar/ChatItem.svelte:1-6, 245-257。
放入文件夹：RecursiveFolder.svelte 通过调用 updateChatFolderIdById 移动对话来处理放置操作 src/lib/components/layout/Sidebar/RecursiveFolder.svelte:177-195。
JSON 导入：将 JSON 文件拖放到文件夹上会触发 importChats src/lib/components/layout/Sidebar/RecursiveFolder.svelte:102-120。

来源： src/lib/components/layout/Sidebar/ChatItem.svelte:1-257、src/lib/components/layout/Sidebar/RecursiveFolder.svelte:102-195