claude-conversation-extractor-guide

Configure-Handle

411人浏览 · 2026-06-02 11:49:40

Configure-Handle · 2026-06-02 11:49:40 发布

Claude Conversation Extractor — 完整使用手册

适用于 claude-conversation-extractor v1.1.2（2026-06 安装于本机）

PyPI: https://pypi.org/project/claude-conversation-extractor/
GitHub: https://github.com/ZeroSumQuant/claude-conversation-extractor
维护者: Dustin Kirby · License: MIT
作用: 从 ~/.claude/projects 提取 Claude Code 会话，导出为 markdown / json / html

1. 工具简介

项目	值
包名（PyPI）	`claude-conversation-extractor`
版本	1.1.2
依赖	无第三方运行时依赖（仅 Python 3.12）
主入口	`claude-extract`（包名 ≠ 命令名）
附带命令	`claude-extract` / `claude-logs` / `claude-search` / `claude-start`
默认输出目录	`/root/Desktop/Claude logs/`
数据源	`~/.claude/projects/-<encoded-cwd>/*.jsonl`

2. 完整安装流程

2.1 系统准备（解决 PEP 668）

Debian/Ubuntu 默认禁止向系统 Python 直接 pip install（externally-managed environment）。需要 venv 或 venv 模块。

# 安装 venv 模块（root 一次性操作）
apt-get install -y python3.12-venv

2.2 创建隔离虚拟环境

# 在家目录下建立统一 venv 目录
python3 -m venv ~/.venvs/claude-tools

选 ~/.venvs/ 而不是项目目录里的 .venv，是把它当作机器级工具，不被任何单个项目污染。

2.3 升级 pip + 安装包

source ~/.venvs/claude-tools/bin/activate
pip install --quiet --upgrade pip
pip install claude-conversation-extractor

输出示例：

Successfully installed claude-conversation-extractor-1.1.2

2.4 验证安装

source ~/.venvs/claude-tools/bin/activate
claude-extract --help        # 应打印帮助
claude-extract --list        # 应列出所有会话
which claude-extract         # 应指向 /root/.venvs/claude-tools/bin/claude-extract

2.5 安装产物

/root/.venvs/claude-tools/
├── bin/
│   ├── claude-extract     ← 主入口
│   ├── claude-logs        ← 日志查看
│   ├── claude-search      ← 独立搜索
│   ├── claude-start       ← 启动 UI
│   ├── pip / pip3
│   └── python → python3 → /usr/bin/python3
└── lib/python3.12/site-packages/
    └── claude_conversation_extractor-1.1.2.dist-info/
        ├── extract_claude_logs.py
        ├── interactive_ui.py
        ├── realtime_search.py
        ├── search_cli.py
        └── search_conversations.py

3. 为什么必须 `source activate`？（`PATH` 机制详解）

3.1 直接原因

pip install 把可执行脚本装到了 venv 自己的 bin 目录：

/root/.venvs/claude-tools/bin/claude-extract   ← 在这里

而 shell 默认的 PATH（不激活 venv 时）通常只有：

/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

不包含 venv 的 bin。所以：

$ which claude-extract
（空，不存在）

$ source ~/.venvs/claude-tools/bin/activate
(venv) $ which claude-extract
/root/.venvs/claude-tools/bin/claude-extract

3.2 `source activate` 做了什么？

activate 脚本做的事只有几件：

把 VIRTUAL_ENV 环境变量设为 venv 路径
把 venv 的 bin 目录前置到 PATH
改 PS1 让提示符显示 (venv)
定义 deactivate 函数

第 2 条是关键 — 之后 claude-extract 就能被 shell 解析到。

3.3 4 种"免 source"方案

方案	命令	优缺点
A. 绝对路径	`~/.venvs/claude-tools/bin/claude-extract --list`	零配置，但每次打长路径
B. 软链接到系统 bin（推荐）	`ln -s ~/.venvs/claude-tools/bin/claude-extract /usr/local/bin/`	一次设置，全局可用
C. 永久加 PATH	`echo 'export PATH="$HOME/.venvs/claude-tools/bin:$PATH"' >> ~/.bashrc`	需重开终端
D. 加 alias	`echo 'alias claude-extract=$HOME/.venvs/claude-tools/bin/claude-extract' >> ~/.bashrc`	同上

推荐方案 B（软链接）一次性命令：

for cmd in claude-extract claude-logs claude-search claude-start; do
  ln -sf ~/.venvs/claude-tools/bin/$cmd /usr/local/bin/$cmd
done

之后任意位置直接 claude-extract --list，不再需要 source。

4. 所有可用参数

4.1 参数速查表

参数	简写	类型	默认值	作用
`--list`		flag		只列出会话，不导出
`--limit LIMIT`		int	全部	`--list` 时限制显示条数
`--extract N`		int / 列表		导出第 N 个会话（逗号分隔多选）
`--recent N`		int		导出最近 N 个
`--all`	`--logs`	flag		导出全部会话
`--output DIR`		path	`/root/Desktop/Claude logs/`	输出目录
`--format FMT`		`markdown` \| `json` \| `html`	`markdown`	导出格式
`--detailed`		flag		包含工具调用、MCP 响应、系统消息
`--search TEXT`		string		在会话全文中搜索
`--search-regex REGEX`		string		用正则搜索
`--search-date-from YYYY-MM-DD`		date		搜索起始日期
`--search-date-to YYYY-MM-DD`		date		搜索结束日期
`--search-speaker {human,assistant,both}`		enum	`both`	限定发言者
`--case-sensitive`		flag		大小写敏感
`--interactive`	`-i`, `--start`, `-s`	flag		启动 TUI 交互界面
`--export MODE`		string		导出模式（如 `logs`）
`--help`	`-h`	flag		显示帮助

4.2 `claude-extract` 帮助原文

usage: claude-extract [-h] [--list] [--extract EXTRACT] [--all]
                      [--recent RECENT] [--output OUTPUT] [--limit LIMIT]
                      [--interactive] [--export EXPORT] [--search SEARCH]
                      [--search-regex SEARCH_REGEX]
                      [--search-date-from SEARCH_DATE_FROM]
                      [--search-date-to SEARCH_DATE_TO]
                      [--search-speaker {human,assistant,both}]
                      [--case-sensitive] [--format {markdown,json,html}]
                      [--detailed]

Extract Claude Code conversations to clean markdown files

5. 典型使用场景

5.1 查看会话列表

claude-extract --list              # 全部
claude-extract --list --limit 10   # 最近 10 条

输出字段：项目目录 / Session ID / 修改时间 / 消息数 / 大小 / 首条预览

5.2 导出当前会话

# 简单版（默认 markdown，到默认目录）
claude-extract --extract 1

# 到指定目录 + 详细模式（含工具调用）
claude-extract --extract 1 --output ~/projects/rasdaemon/ --detailed

# 多种格式
claude-extract --extract 1 --format markdown
claude-extract --extract 1 --format json
claude-extract --extract 1 --format html

5.3 批量导出

# 多个指定编号
claude-extract --extract 1,3,5

# 最近 N 个
claude-extract --recent 5

# 一次性全部
claude-extract --all
claude-extract --all --output /backup/claude-logs/ --format html

5.4 搜索

# 关键词
claude-extract --search "configure.ac"

# 正则
claude-extract --search-regex "ERROR.*timeout"

# 限定时间范围 + 发言者
claude-extract --search "make" \
  --search-date-from 2026-05-01 \
  --search-date-to 2026-06-01 \
  --search-speaker assistant

# 大小写敏感
claude-extract --search "SQLite" --case-sensitive

5.5 交互式 UI

claude-extract --interactive   # 或 -i, --start, -s

适合：不知道要导哪个、想浏览后勾选。

5.6 配合其它命令

# 把所有会话打包备份
claude-extract --all --output /tmp/claude-backup/ && \
  tar czf claude-logs-$(date +%Y%m%d).tar.gz /tmp/claude-backup/

# 找出含某个 bug 的会话
claude-extract --search "segmentation fault" --search-speaker assistant

6. 故障排查

现象	原因	解决
`claude-extract: command not found`	没激活 venv 且没建软链	见 §3.3
`error: externally-managed-environment`	直接 `pip install` 到系统 Python	用 venv 或 `--break-system-packages`
`ensurepip is not available`	缺 `python3.12-venv`	`apt install python3.12-venv`
列表为空	还没跑过 Claude Code	跑一次后重试
导出的 md 文件没工具调用	默认不包含	加 `--detailed`
输出到错误目录	没指定 `--output`	默认是 `/root/Desktop/Claude logs/`

7. 卸载

# 1. 删 venv（连命令一起）
rm -rf ~/.venvs/claude-tools

# 2. 删软链接（如果建过）
rm -f /usr/local/bin/claude-extract \
      /usr/local/bin/claude-logs \
      /usr/local/bin/claude-search \
      /usr/local/bin/claude-start

# 3. 删 ~/.bashrc 里的 PATH / alias 行（如有）

8. 速查卡片（贴到工位）

┌──────────────────────────────────────────────┐
│ Claude Conversation Extractor 速查           │
├──────────────────────────────────────────────┤
│ 激活:   source ~/.venvs/claude-tools/bin/activate
│ 列表:   claude-extract --list                │
│ 导出:   claude-extract --extract N           │
│         claude-extract --recent N            │
│         claude-extract --all                 │
│ 格式:   --format markdown|json|html          │
│ 详:    --detailed                            │
│ 输出:  --output /path/                       │
│ 搜:    --search "text"                       │
│         --search-regex "regex"               │
│ UI:    claude-extract -i                     │
└──────────────────────────────────────────────┘

亚马逊云科技技术品牌专区

更多推荐

基于大数据+Hadoop+深度学习的淘宝用户购物可视化与行为预测系统设计与开发

亚马逊云科技技术品牌专区

基于大数据爬虫+Hadoop+深度学习的旅游推荐系统设计与开发

亚马逊云科技技术品牌专区

学Linux选学校：一线城市还是老家？

而二线城市很多机构的老师，自己都没进过大厂，技术停留在五年前的水平，甚至对着PPT照本宣科。而二线机构缺乏企业合作资源，项目案例永远是“搭建博客系统”“配置个LAMP环境”——这些在现在的云计算岗位面试中，连初筛都过不了。在一线城市学习，你接触的同学、老师、企业内推资源，都是二线城市没法比的。而老家机构的学员，最好的结果也就是去本地小公司做网管，月薪五六千，天花板肉眼可见。在IT培训这行干了快十年