chatgpt-to-md优化并重新复习

chatgpt-to-md优化并重新复习

之前原本写的又重新改了改

\](记录 \| 个人开发库推送至PyPi流程梳理（ChatGPT to Markdown 工具发布完整流程） ) 以上废话 总之因为发现只支持转换Chatgpt的zip文件，因此重新优化了整个代码 主要代码等会开源至github

• ai-conversation-exporter
  

后续进行更新和发布主要修改pyproject.toml文件。

AI对话导出工具：从多平台数据到Markdown的完整发布指南

本文记录了将AI对话导出工具从单一平台支持扩展到多平台支持，并成功发布到PyPI的完整流程。包含项目架构设计、代码实现、发布流程和故障排除。

项目演进背景

最初开发的 chatgpt-to-md 工具仅支持ChatGPT的zip导出格式，但在实际使用中发现用户需要支持更多AI平台。为此重构了整个项目，创建了 ai-conversation-exporter，支持ChatGPT、DeepSeek、Claude等多个平台的对话导出。

项目架构设计

模块化解析器设计

采用插件式架构，每个AI平台有独立的解析器：

ai-exporter/
├── src/
│   └── ai_exporter/
│       ├── __init__.py
│       ├── core.py              # 核心转换逻辑
│       └── parsers/             # 解析器模块
│           ├── __init__.py
│           ├── base.py          # 解析器基类
│           ├── chatgpt.py       # ChatGPT解析器
│           ├── deepseek.py      # DeepSeek解析器
│           ├── claude.py        # Claude解析器
│           └── universal.py     # 通用解析器
├── pyproject.toml
├── README.md
└── LICENSE

核心特性

• 多平台支持：ChatGPT(.zip)、DeepSeek(.jsonl)、Claude(.json)
• 自动格式检测：根据文件内容和扩展名自动选择解析器
• 统一输出：标准Markdown格式，包含YAML front matter
• 容错处理：通用解析器作为后备方案

关键技术实现

1. 解析器基类设计

# src/ai_exporter/parsers/base.py
from abc import ABC, abstractmethod
from typing import List, Dict, Any

class BaseParser(ABC):
    @abstractmethod
    def can_parse(self, file_path: str) -> bool: ...
    
    @abstractmethod
    def parse(self, file_path: str) -> List[Dict[str, Any]]: ...
    
    @abstractmethod
    def get_platform_name(self) -> str: ...

2. 平台特定解析器

每个解析器实现特定平台的格式处理：

• ChatGPTParser: 处理zip压缩包中的conversations.json
• DeepSeekParser: 处理JSONL格式（每行一个消息）
• ClaudeParser: 处理结构化JSON格式
• UniversalParser: 通用JSON/JSONL格式处理

3. 核心转换引擎

# src/ai_exporter/core.py
class AIExporter:
    def __init__(self):
        self.parsers = [
            ChatGPTParser(), DeepSeekParser(), 
            ClaudeParser(), UniversalParser()
        ]
    
    def detect_platform(self, file_path: str):
        # 自动检测文件格式并选择合适的解析器
        for parser in self.parsers:
            if parser.can_parse(file_path):
                return parser
        return self.parsers[-1]  # 返回通用解析器

发布流程完整指南

1. 项目配置 (pyproject.toml)

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "ai-conversation-exporter"  # 唯一包名
version = "0.1.0"
description = "Export conversations from multiple AI platforms to Markdown"
authors = [{name = "Your Name", email = "your.email@example.com"}]
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.7"

[project.scripts]
ai-export = "ai_exporter.core:main"

2. 构建和发布命令

# 进入项目目录
cd "your-project-path"

# 清理旧构建
rm -rf dist/ build/ *.egg-info/

# 构建分发包
python -m build

# 检查包文件
twine check dist/*

# 上传到PyPI
twine upload dist/* -u __token__ -p pypi-你的token

3. 使用示例

# 安装
pip install ai-conversation-exporter

# 使用
ai-export chatgpt_export.zip
ai-export deepseek_conversation.jsonl -o ./output
ai-export claude_chat.json

故障排除手册

常见问题及解决方案

1. 403 Forbidden 错误

原因：

• 包名已被占用
• API Token无效或过期
• Token权限不足

解决方案：

# 检查包名是否被占用
# 访问：https://pypi.org/project/your-package-name/

# 修改为唯一包名（在pyproject.toml中）
name = "your-unique-package-name"

# 重新生成API Token（选择Entire account权限）

2. ModuleNotFoundError

原因：模块导入路径错误

解决方案：使用相对导入

# 正确方式
from .parsers import ChatGPTParser

# 错误方式  
from parsers import ChatGPTParser

3. 文件格式识别失败

解决方案：增强通用解析器

def _deep_search_messages(self, data: Any) -> List:
    # 递归搜索消息数据
    # 支持多种嵌套结构

开发最佳实践

1. 版本管理

• 使用语义化版本号 (MAJOR.MINOR.PATCH)
• 每次发布前更新版本号

2. 测试策略

# 创建测试文件验证各种格式
def create_test_files():
    # 生成不同平台的测试数据
    # 验证解析器是否正确工作

3. 错误处理

• 提供详细的错误信息
• 实现优雅降级（通用解析器）
• 记录解析过程用于调试

项目亮点

1. 架构灵活：易于添加新平台解析器
2. 用户体验：自动检测格式，无需手动指定
3. 输出规范：统一的Markdown格式，便于后续处理
4. 错误容忍：多重解析策略确保成功率

总结

通过模块化设计和标准化发布流程，成功将单一功能工具扩展为支持多平台的通用解决方案。关键成功因素包括：

• 清晰的架构设计
• 完整的错误处理
• 标准化的发布流程
• 详细的文档记录

这个项目不仅解决了实际问题，还提供了一个可复用的Python包开发模板，适用于各种工具类项目的开发和发布。

---

项目地址 : [GitHub链接]
PyPI包 : ai-export-tool-16673
许可证: MIT