1. 项目概述与核心价值最近在整理我的AI对话记录时发现了一个痛点无论是ChatGPT还是Claude它们提供的官方数据导出功能虽然能拿到原始数据但浏览和检索体验实在谈不上友好。你拿到手的通常是一个压缩包里面塞满了JSON文件想找半年前某个关于Python异步编程的讨论要么你得一个个文件点开看要么就得自己写脚本去解析。这显然不是我们这些每天和AI“对话”的从业者想要的。我们需要的是一个能本地化、统一管理、并且支持深度检索的个人知识库工具。这正是mirableio/chat-history这个开源项目要解决的问题。简单来说chat-history是一个用Python编写的命令行工具它允许你将从ChatGPT和Claude官方导出的聊天记录ZIP包转换成一个运行在本地的、带Web界面的对话浏览器。它不止于简单的查看更提供了全文搜索、语义搜索、数据统计以及Markdown导出等实用功能让你能真正“拥有”并高效利用这些宝贵的对话历史。对于开发者、研究者、内容创作者或者任何希望系统化整理自己与AI交互记录的人来说这无疑是一个能极大提升效率的“瑞士军刀”。接下来我将结合自己从零部署到深度使用的全过程拆解它的设计思路、实操细节以及那些官方文档里没写的“坑”和技巧。2. 环境准备与项目初始化2.1 基础环境与工具链选择项目明确要求Python 3.11和uv。这里先解释一下为什么是这两个选择而不仅仅是“照着做”。Python 3.11在性能上有显著提升特别是对于这种需要处理大量JSON数据并可能涉及向量计算的应用新版解释器的效率优势是实实在在的。而uv是一个用Rust写的、极速的Python包管理器和安装器由Astral团队也是Ruff的创造者开发。它比传统的pip快一个数量级并且解决了依赖解析和虚拟环境管理的诸多痛点。对于chat-history这种可能频繁更新和安装的工具使用uv能保证依赖安装的确定性和速度。首先确保你的系统已安装Python 3.11或更高版本。在终端输入python3 --version或python --version进行确认。如果没有建议使用pyenvmacOS/Linux或官方安装包进行管理。接下来安装uv。根据官方文档最通用的安装方式是使用curlcurl -LsSf https://astral.sh/uv/install.sh | sh安装完成后重启终端或执行source ~/.bashrc或对应shell的配置文件使uv命令生效。验证安装uv --version。至此基础环境就绪。2.2 数据导出获取原始素材工具再好没有数据也是巧妇难为无米之炊。第一步是从AI服务商那里拿到你的聊天记录。对于ChatGPT (OpenAI):登录 chatgpt.com 。点击左下角你的账户名进入Settings。选择Data controls选项卡。点击Export data。系统会提示你确认并告知数据将通过邮件发送。检查你的注册邮箱通常会收到一封来自OpenAI的邮件内含一个下载链接。下载得到的将是一个名为chatgpt-export-YYYY-MM-DD.zip的文件。对于Claude (Anthropic):登录 claude.ai 。点击左下角你的账户名进入Settings。选择Data privacy controls。点击Export chat history按钮。同样你会收到一封邮件附件是一个ZIP文件名称类似claude_ai_export_YYYY_MM_DD.zip。注意数据导出和邮件发送可能需要几分钟到几小时不等取决于你的对话历史数据量。建议在开始项目前提前操作这一步。另外请妥善保管这些ZIP文件它们包含了你的所有对话原文属于个人隐私数据。2.3 项目初始化与向导使用拿到ZIP文件后建议创建一个专门的项目目录来管理所有相关数据。这样做的好处是隔离性强便于备份和迁移。mkdir my-ai-chat-archive cd my-ai-chat-archive将你下载的ChatGPT和Claude的ZIP文件都移动到这个目录下。然后运行项目的设置向导uvx chat-history如果你是第一次在这个目录运行uvx会自动从PyPI下载chat-history包并启动交互式设置向导。这个过程非常直观扫描文件向导会自动扫描当前目录和你的~/Downloads文件夹寻找可能的导出ZIP。验证与选择它会列出找到的ZIP文件让你确认是否是要处理的文件。提取数据确认后工具会将ZIP解压到项目目录下的./data/子文件夹中。原始ZIP文件会被保留不会删除。生成配置基于提取的数据向导会在./data/目录下创建一个.env配置文件里面写入了数据路径等关键信息。启动服务最后向导会询问你是否要立即启动Web服务器。选择“是”它会自动打开浏览器访问http://127.0.0.1:8080。至此一个本地的、统一的聊天历史浏览器就已经运行起来了。下次你想查看时只需要进入这个项目目录再次运行uvx chat-history或uvx chat-history serve即可。3. 核心功能深度解析与实操3.1 Web界面浏览与基础操作启动服务并打开浏览器后你会看到一个简洁但功能清晰的界面。主视图通常是一个按时间倒序排列的对话列表。每个对话卡片会显示标题自动从对话内容生成或使用模型默认标题、使用的AI提供商图标ChatGPT或Claude、时间戳以及一个预览片段。对话查看与导航点击任意对话即可进入详情页。界面被清晰地分为左右两栏或上下布局。左侧是完整的对话树清晰地展示了用户与AI的多轮交互。右侧是当前选中消息的详细内容渲染。对于AI的回复代码块会进行语法高亮数学公式可能被渲染整体阅读体验远优于直接看JSON。收藏与外部链接这是一个很贴心的功能。对于重要的对话你可以点击星标将其加入“Favorites”收藏方便日后快速找回。另外每个对话详情页都会提供一个“Original Chat”链接点击它会跳转到对应服务商chatgpt.com或claude.ai的原始对话页面方便你在需要时回到官方环境进行后续对话。搜索功能顶部有一个显著的搜索框。输入关键词它会实时在所有对话的标题和内容中进行全文检索并高亮显示匹配结果。这是最基础也是最常用的检索方式。3.2 语义搜索构建你的对话向量库全文搜索虽好但局限于关键词匹配。如果你记得某个概念的大意却忘了具体术语全文搜索就无能为力了。chat-history的语义搜索功能正是为此而生。它利用OpenAI的文本嵌入模型将你的每一条消息包括你的提问和AI的回答转换为一个高维向量然后通过向量数据库FAISS进行相似度检索。这意味着你可以用自然语言去搜索比如“之前讨论过如何用Python处理CSV文件里的中文乱码问题”即使对话里没有“中文乱码”这几个字只要语义相近就能被找出来。启用与配置语义搜索获取API Key你需要一个OpenAI的API Key。前往 OpenAI平台 创建。修改配置停止当前服务编辑./data/.env文件。# 启用语义搜索 CHAT_HISTORY_OPENAI_ENABLEDtrue # 填入你的OpenAI API Key OPENAI_API_KEYsk-your-actual-api-key-here # 可选指定组织ID如果你属于多个组织 # OPENAI_ORGANIZATIONorg-xxx # 可选指定嵌入模型默认为性价比很高的 text-embedding-3-small # OPENAI_EMBEDDING_MODELtext-embedding-3-small重建索引保存.env文件后重新启动服务(uvx chat-history serve)。服务启动时会检查到语义搜索已启用并自动开始为所有对话消息计算嵌入向量。这个过程是增量式的只处理新消息。首次运行可能会花费一些时间取决于你的历史数据量。使用语义搜索在Web界面的搜索框中输入查询词后界面通常会提供一个切换按钮或在下拉提示中区分“全文搜索”和“语义搜索”。选择语义搜索结果将按与查询语句的语义相关性进行排序最相关的结果排在最前面。实操心得语义搜索非常强大但需要注意API调用成本。text-embedding-3-small模型价格低廉但对于成千上万条历史消息首次构建索引仍会产生费用。建议在启用前先用uvx chat-history inspect命令查看一下总的消息条数估算一下成本。另外索引构建是离线的构建完成后后续的搜索查询本身不再产生额外费用除非有新对话加入。3.3 数据统计与洞察chat-history内置了简单的数据统计面板通常可以在Web界面的某个标签页或侧边栏找到。这些统计能给你一些有趣的宏观视角活动概览以日历热图或折线图的形式展示你与AI对话的活跃度看看哪段时间是你的“高产期”。Token统计估算你和AI各自消耗的Token数量。这对于关注使用成本或者回顾自己提问的“信息密度”很有帮助。需要特别注意项目文档明确提到Claude的Token统计是近似值使用了后备的分词器并非Claude原生的精确计数。对于ChatGPT的统计则相对准确。这个数据更适合用于趋势对比而非精确核算。提供商分布看看你更频繁地使用ChatGPT还是Claude。3.4 命令行工具CLI详解除了Web界面chat-history提供了强大的命令行接口适合自动化操作和批量处理。1. 服务管理uvx chat-history serve: 启动Web服务器。这是最常用的命令。--host 127.0.0.1: 指定监听地址默认为本地回环地址最安全。--port 8080: 指定端口如果8080被占用可以改为其他端口如8081。--no-browser: 启动服务但不自动打开浏览器。在服务器或无头环境中使用。2. 数据导出为Markdown这是我认为最实用的功能之一能将结构化的对话转化为扁平的、易于分发的Markdown文件方便导入到Obsidian、Logseq等笔记软件或作为上下文喂给其他AI工具进行深度分析。uvx chat-history export [选项]常用选项组合示例uvx chat-history export --provider all --out ./my_exports: 导出所有提供商ChatGPT和Claude的对话到./my_exports目录按提供商分子文件夹。uvx chat-history export --provider chatgpt --clean: 仅导出ChatGPT的对话并在导出前清理./data/export/chatgpt/目录下的旧文件。uvx chat-history export --exclude-system --exclude-thinking: 导出时排除系统提示词和模型的“思考过程”部分模型如Claude会输出让导出的内容更聚焦于核心问答。3. 数据检查uvx chat-history inspect: 快速在终端打印出数据概览包括识别到的提供商、对话总数、消息总数。在初始化后或怀疑数据有问题时先用这个命令看一眼非常方便。4. 重新运行向导uvx chat-history init: 如果你移动了ZIP文件或者想新增一个提供商的导出数据例如之前只导入了ChatGPT现在想加入Claude可以重新运行向导。它会扫描并让你选择新增的数据源并更新配置文件。5. 更新工具uvx chat-history install: 等同于uvx --reinstall chat-history用于将工具本身更新到最新版本。4. 高级配置与自定义4.1 配置文件.env详解项目将所有配置集中存储在./data/.env文件中这是12-Factor应用的标准做法。理解每个变量有助于你进行高级定制。变量名默认值描述与自定义建议CHAT_HISTORY_DATA_DIRdata所有衍生数据解压的JSON、数据库、索引、导出文件的根目录。不建议修改除非你有强烈的目录规划需求。CHAT_HISTORY_CHATGPT_PATH—ChatGPT导出数据的具体路径。通常由向导自动填写指向./data/chatgpt/目录或其中的conversations.json。如果自动识别失败可以手动指定。CHAT_HISTORY_CLAUDE_PATH—Claude导出数据的路径。同上。CHAT_HISTORY_OPENAI_ENABLEDfalse布尔值控制是否启用语义搜索。设为true以启用。OPENAI_API_KEY—必需若启用语义搜索。你的OpenAI API Key。OPENAI_ORGANIZATION—可选如果你的API Key关联了多个组织在此指定组织ID。OPENAI_EMBEDDING_MODELtext-embedding-3-small使用的嵌入模型。除非有特殊需求否则建议保持默认它在效果和成本间取得了很好平衡。CHAT_HISTORY_SETTINGS_DB_PATH—覆盖用户设置如收藏夹的SQLite数据库路径。一般无需改动除非你想将设置文件存到特定位置。4.2 数据目录结构剖析了解./data/下的目录结构有助于你在出现问题时进行手动排查或备份。my-ai-chat-archive/ ├── chatgpt-export-2024-01-01.zip # 原始ZIP文件建议保留 ├── claude_ai_export_2024_01_01.zip # 原始ZIP文件 └── data/ # 项目生成和管理的所有数据 ├── .env # 配置文件 ├── chatgpt/ # ChatGPT解析后的数据 │ ├── conversations.json # 可能是从ZIP中提取的原文件 │ └── ... # 其他解析后的结构化数据 ├── claude/ # Claude解析后的数据 │ └── ... ├── export/ # export命令的输出目录 │ ├── chatgpt/ │ │ └── [YYYY-MM-DD]-[Title].md │ └── claude/ │ └── ... ├── faiss_index/ # 语义搜索的向量索引如果启用 └── settings.db # SQLite数据库存储收藏夹等用户设置备份策略如果你需要备份整个聊天历史库最安全的方式是备份整个项目目录my-ai-chat-archive/。如果只想备份核心数据那么备份./data/目录即可但请注意.env文件中的API Key是敏感信息。5. 常见问题与故障排除在实际使用中你可能会遇到一些问题。以下是我遇到过的典型情况及其解决方法。5.1 启动与运行问题问题运行uvx chat-history时报错提示命令未找到或Python版本不对。检查uv安装确认uv已正确安装并位于系统PATH中。运行which uv或uv --version。检查Python版本uv会使用系统默认的Python。用python3 --version确认版本≥3.11。如果系统有多个Python版本可以通过uv python pin 3.11命令让uv锁定使用特定版本。问题Web服务启动失败端口被占用。更改端口使用uvx chat-history serve --port 8081指定另一个端口。查找并结束占用进程在Linux/macOS上可以用lsof -i :8080查找占用8080端口的进程ID然后用kill -9 PID结束它。在Windows上可以使用netstat -ano | findstr :8080和taskkill /PID PID /F。5.2 数据导入与解析问题问题向导没有自动找到我的ZIP文件。手动指定路径将ZIP文件直接放在运行命令的当前目录下然后再次运行向导。或者使用uvx chat-history init --path /path/to/your/zip直接指定ZIP文件或所在目录。检查ZIP完整性确保ZIP文件是从官方渠道导出且下载完整可以尝试手动解压看是否能成功。问题导入后Web界面看不到任何对话或对话内容不全。检查配置文件查看./data/.env确认CHAT_HISTORY_CHATGPT_PATH和CHAT_HISTORY_CLAUDE_PATH指向的路径是否正确且该路径下存在有效的conversations.json文件。重新初始化可以尝试删除./data/目录下对应提供商的数据文件夹如./data/chatgpt/然后重新运行uvx chat-history init让工具重新解压和解析ZIP。查看日志启动服务时终端会输出日志。注意是否有关于解析JSON失败的ERROR信息。可能是导出文件格式有变动需要等待工具更新。5.3 语义搜索相关问题问题启用了语义搜索但搜索时没有“语义搜索”的选项或结果不对。确认配置生效首先确保.env文件中CHAT_HISTORY_OPENAI_ENABLEDtrue且OPENAI_API_KEY正确无误。重启服务修改.env后必须完全停止并重启serve进程配置才会被重新加载。观察索引构建重启服务时观察终端输出。应该能看到类似“Creating embeddings for X new messages”的日志。如果没有可能是所有消息都已索引过或者API Key无效导致无法调用OpenAI。检查API Key与网络确认API Key有余额且网络环境可以正常访问OpenAI API。问题语义搜索速度慢。首次为大量历史消息构建索引时需要向OpenAI API发送大量请求受网络和API速率限制耗时较长这是正常的。索引一旦构建完成后续的搜索查询在本地向量库中进行速度会非常快。新增对话后的增量索引也很快。5.4 导出功能问题问题export命令导出的Markdown文件乱码或格式错乱。这通常与原始对话中包含的特殊字符或复杂格式有关。可以尝试使用--exclude-thinking和--exclude-attachments选项排除可能引起问题的部分。导出的Markdown是纯文本对于极度复杂的渲染内容如某些特定格式的表格、图表转换可能不完美。问题如何定期自动备份/导出我的对话chat-history本身没有内置定时任务。但你可以结合系统的定时任务工具如Linux的cronWindows的任务计划程序来实现。例如创建一个简单的Shell脚本backup.sh#!/bin/bash cd /path/to/your/my-ai-chat-archive uvx chat-history export --provider all --clean --out /path/to/backup/dir/$(date %Y%m%d)然后使用cron每周运行一次这个脚本。这样你就有了按日期归档的Markdown版本历史。5.5 性能与维护数据量大了之后会不会变慢文本浏览和全文搜索基于SQLite和FTS全文搜索即使有数万条对话性能也完全没问题。语义搜索索引构建阶段调用OpenAI API是主要瓶颈。构建完成后基于FAISS的向量检索效率极高毫秒级响应。FAISS索引文件会随着数据量增长而变大但现代硬盘空间通常不是问题。建议对于超大规模历史数据例如十万条消息以上可以考虑只对近期或重要的对话启用语义搜索以控制成本和初始化时间。如何升级chat-history工具只需运行uvx chat-history install。uvx会从PyPI拉取最新版本并重新安装。你的数据./data/目录是独立存储的不会受工具升级影响。升级后重启服务即可。这个工具安全吗我的数据会上传吗核心原则这是一个本地优先的工具。你的原始ZIP、解析后的数据、向量索引如果启用全部存储在你的本地机器上。唯一的例外当你启用语义搜索功能时你的对话文本内容会被发送到OpenAI的API以转换为嵌入向量。这是使用该功能所必需的。请阅读OpenAI的 数据使用政策 。如果你对此有顾虑可以完全不启用语义搜索仅使用本地全文搜索功能。网络访问Web服务器默认只监听127.0.0.1意味着只有本机可以访问。请不要将其绑定到0.0.0.0或公网IP除非你清楚如何设置身份验证和网络安全措施。