Claude 对话历史管理系统架构设计
最近在整理 Claude Code 的使用记录，发现对话历史分散在 .claude/history.jsonl 和 sessions/ 目录下，查找起来很不方便。
于是决定开发一个Claude 对话历史管理系统，把散落的数据整合起来，支持追溯和浏览。
今天先输出架构方案和 Todo List，方便后续开发。
一、数据源分析
首先看看 .claude 目录结构：
~/.claude/
├── history.jsonl # 用户输入记录（703条）
├── sessions/ # 会话元数据
├── projects/ # 项目目录
├── tasks/ # 任务记录
└── ...
关键数据结构
history.jsonl（每行一条记录）：
{
"display": "用户输入内容",
"pastedContents": {},
"timestamp": 1769771765871,
"project": "/Users/jiafei",
"sessionId": "e7a410c7-f266-427f-a1b6-c05d053ca571"
}
sessions/*.json（会话元数据）：
{
"pid": 24431,
"sessionId": "54c96abf-17c4-4b6c-8cf0-e12705905177",
"cwd": "/Users/jiafei/project",
"startedAt": 1781622166971,
"status": "busy",
"version": "2.1.173"
}
二、系统架构
技术栈
| 层级 | 技术选型 | 说明 |
|---|---|---|
| 前端 | Vue 3 + Vite | 现代化 SPA |
| UI 组件 | Naive UI / Element Plus | 快速开发 |
| 状态管理 | Pinia | 轻量级状态管理 |
| 后端 | Python FastAPI | 高性能异步框架 |
| 数据库 | SQLite | 轻量、免部署 |
| ORM | SQLAlchemy | Python ORM 标准 |
| 导入器 | 自定义 Parser | 解析 .claude 数据 |
核心模块设计
1. 数据导入层（Backend）
# services/importer.py
class ClaudeDataImporter:
"""解析并导入 .claude 目录数据"""
def import_history(self, history_path: str) -> ImportResult:
"""导入 history.jsonl"""
pass
def import_sessions(self, sessions_dir: str) -> ImportResult:
"""导入 sessions 目录"""
pass
def incremental_sync(self) -> SyncResult:
"""增量同步（基于最后导入时间戳）"""
pass
2. 数据模型（Backend）
# models/conversation.py
class Session(Base):
"""会话"""
id = Column(String, primary_key=True) # sessionId
pid = Column(Integer)
cwd = Column(String)
started_at = Column(DateTime)
status = Column(String) # busy, idle, completed
project = Column(String)
class Message(Base):
"""单条消息"""
id = Column(Integer, primary_key=True, autoincrement=True)
session_id = Column(String, ForeignKey("sessions.id"))
display = Column(Text) # 用户输入
timestamp = Column(DateTime)
message_type = Column(String) # user, assistant, system
3. API 接口（Backend）
@router.get("/api/sessions")
async def list_sessions(page: int = 1, page_size: int = 20, project: str = None):
"""会话列表（分页、筛选）"""
@router.get("/api/sessions/{session_id}")
async def get_session_detail(session_id: str):
"""会话详情"""
@router.get("/api/search")
async def search_messages(keyword: str, limit: int = 50):
"""全文搜索"""
@router.post("/api/import")
async def trigger_import():
"""手动触发导入"""
4. 前端页面（Frontend）
src/
├── views/
│ ├── Dashboard.vue # 仪表盘（统计概览）
│ ├── SessionList.vue # 会话列表
│ ├── SessionDetail.vue # 会话详情
│ ├── Search.vue # 搜索页面
│ └── Projects.vue # 项目视图
├── components/
│ ├── MessageItem.vue # 消息组件
│ ├── Timeline.vue # 时间线组件
│ └── FilterBar.vue # 筛选栏
└── stores/
├── session.ts # 会话状态
└── import.ts # 导入状态
三、功能特性
核心功能
| 功能 | 描述 | 优先级 |
|---|---|---|
| 全量导入 | 一次性导入所有 .claude 数据 | P0 |
| 增量同步 | 检测新增记录并同步 | P0 |
| 会话列表 | 按时间、项目筛选浏览 | P0 |
| 会话详情 | 查看单次会话的所有消息 | P0 |
| 全文搜索 | 搜索消息内容 | P1 |
| 项目视图 | 按项目组织会话 | P1 |
| 统计看板 | 活跃度、使用统计 | P2 |
四、Todo List
Phase 1：后端基础 + 导入服务
- 初始化 FastAPI 项目结构
- 定义 SQLAlchemy ORM 模型
- 实现 history.jsonl 解析器
- 实现 sessions 目录解析器
- 实现全量导入服务
- 实现增量同步服务
Phase 2：前端基础框架
- 初始化 Vue 3 + Vite 项目
- 配置路由、状态管理
- 配置 UI 组件库
- 布局组件开发
Phase 3：核心功能开发
- 会话列表页面
- 会话详情页面
- 时间、项目筛选
- 消息时间线展示
Phase 4：搜索与统计
- 全文搜索 API + 前端
- 仪表盘统计页面
- 活跃度图表
Phase 5：优化与完善
- 性能优化
- 错误处理完善
- README 文档
五、开发计划
| 阶段 | 预计时间 | 交付物 |
|---|---|---|
| Phase 1 | 1-2 天 | 后端 API 服务跑通 |
| Phase 2 | 1 天 | 前端框架搭建完成 |
| Phase 3 | 2-3 天 | 核心浏览功能可用 |
| Phase 4 | 1-2 天 | 搜索统计功能 |
| Phase 5 | 1 天 | 优化收尾 |
预计总工期：6-9 天
六、项目结构
claude-history-manager/
├── backend/
│ ├── app/
│ │ ├── main.py
│ │ ├── config.py
│ │ ├── models/
│ │ ├── schemas/
│ │ ├── routers/
│ │ ├── services/
│ │ └── db/
│ ├── data/
│ └── requirements.txt
├── frontend/
│ ├── src/
│ └── package.json
└── README.md
最后
这个项目会开源，有兴趣一起做的朋友可以关注后续更新。
核心价值是把 Claude Code 的对话历史从”散落的数据”变成”可追溯的知识库”，方便回顾重要讨论和决策过程。
转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 1056615746@qq.com
