Convoviz

uv tool install "convoviz[viz]"

将您的 ChatGPT 历史记录转换为整洁、易读的 Markdown（文本文件）。

非常适合归档、本地搜索，或与 Obsidian 等笔记应用一起使用。

使用词云和使用情况图表可视化您的数据。

功能

请参阅 demo/ 文件夹中的词云示例！

使用方法

第一步：导出您的 ChatGPT 数据

1. 登录 chatgpt.com
2. 导航至：个人资料名称（左下角）→ 设置 → 数据控制 → 导出
3. 点击 确认导出
4. 等待 OpenAI 发来的邮件，然后下载 .zip 文件

第二步：安装 Convoviz

快速安装

运行以下命令之一，即可自动安装您所需的一切。

🍎 macOS / 🐧 Linux

1. 打开 终端。
   • macOS：按 Cmd + Space，输入“Terminal”，然后按回车。
   • Linux：按 Ctrl + Alt + T，或在应用菜单中搜索“Terminal”。
2. 复制并粘贴以下命令：

curl -fsSL https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.sh | bash

🪟 Windows

1. 打开 PowerShell。
   • 按下 Windows 键，输入“PowerShell”，然后按回车。
2. 复制并粘贴以下命令：

irm https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.ps1 | iex

# 创建虚拟环境（保持系统 Python 清洁）
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装带有可视化扩展的 convoviz
pip install "convoviz[viz]"

第三步：运行 Convoviz

最简单的方式是在终端中运行以下命令，并按照交互式提示操作：

convoviz

或者，直接提供参数以跳过提示：

convoviz --input path/to/your/export.zip --output path/to/output/folder

convoviz --input export.zip --outputs markdown --outputs graphs

convoviz --help

convoviz config init

convoviz --config path/to/config.toml

第 4 步：检查输出

运行脚本后，前往你的输出文件夹（如果你没有更改，默认是 Documents/ChatGPT-Data），你将看到：

• 整齐格式化的 Markdown 文件
• 可视化图表和图形
• 提取的 Canvas 文档（如果有）
• 用户的“自定义指令”文件 (custom_instructions.json)

如果你使用体验良好，请为这个项目点个 ⭐ 星 吧！这会让我更有动力，也能帮助更多人发现它！

导出为 PDF

你可以尝试使用 convpdf，将 Markdown 文件转换为 PDF。

示例：

# 使用 npm 安装
npm -g install convpdf

# 进入输出目录（默认是 ~/Documents/ChatGPT-Data/）
cd ~/Documents/ChatGPT-Data

# 运行命令（添加 `-j 20` 可加快转换速度）
convpdf Markdown -o PDF

💌 分享你的反馈！

希望这个工具对你有所帮助。我一直在努力改进它，但也需要你的支持。

无论你是技术高手，还是刚接触这类工具的新手，我都非常期待听到你使用这个工具的感受。发现了什么小问题？有哪些建议？或者只是想给我一些鼓励？我都很乐意倾听！

👉 提交一个问题

贡献

有兴趣参与贡献吗？请查看 贡献指南，了解开发环境搭建、代码风格以及如何提交 Pull Request 的方法。

注意事项

python -c "import nltk; nltk.download('stopwords')"

Convoviz 快速上手指南

Convoviz 是一款将 ChatGPT 对话历史转换为整洁 Markdown 文件的工具，支持生成词云和使用图表，非常适合归档、本地搜索或配合 Obsidian 等笔记软件使用。

环境准备

• 操作系统：macOS, Linux, 或 Windows
• Python 环境：需安装 Python 3.8+（推荐通过官方安装包或系统包管理器安装）
• 前置依赖：
  • 若使用一键安装脚本，无需额外配置。
  • 若手动安装，建议创建虚拟环境以保持系统清洁。
  • 离线注意：词云功能依赖 NLTK 数据。若在无网络环境下运行，需提前执行 python -c "import nltk; nltk.download('stopwords')" 下载停用词数据（一键安装脚本已自动处理此步骤）。

安装步骤

方式一：一键安装（推荐）

打开终端并运行以下命令，脚本将自动处理所有依赖：

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/mohamed-chs/convoviz/main/install.ps1 | iex

方式二：使用 pip 手动安装

如果你偏好使用 pip：

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装包含可视化功能的版本
pip install "convoviz[viz]"

基本使用

第一步：导出 ChatGPT 数据

1. 访问 chatgpt.com 并登录。
2. 点击左下角 Profile Name → Settings → Data controls → Export。
3. 点击 Confirm export。
4. 等待 OpenAI 发送邮件，下载生成的 .zip 文件。

(可选：如需快速获取近期对话，可参考项目仓库中的 js/HOW_TO_USE.md 使用直接导出脚本)

第二步：运行转换

最简单的使用方式是直接在终端输入命令，跟随交互式提示操作：

convoviz

程序会自动检测下载文件夹中的导出文件，或引导你指定输入路径。

高级用法：命令行参数

你也可以直接指定输入和输出路径以跳过交互提示：

convoviz --input path/to/your/export.zip --output path/to/output/folder

常用参数示例：

• 仅生成 Markdown 和图表（不生成词云）：

  convoviz --input export.zip --outputs markdown --outputs graphs
  

• 在文件名前添加时间戳：

  convoviz --input export.zip --timestamp
  

• 查看所有可用选项：

  convoviz --help
  

第三步：查看结果

运行完成后，前往输出目录（默认为 Documents/ChatGPT-Data），你将看到：

• 格式整齐的 Markdown 对话文件（含内联图片和引用）。
• 词云图片和使用统计图表。
• 提取的 Canvas 文档（如 .py, .html 文件）。
• 自定义指令文件 (custom_instructions.json)。

提示：如需将生成的 Markdown 转为 PDF，可配合使用 convpdf 工具。