Superpowers能力增强方案：从安装配置到自动化实战全解析
2026/10/7 7:52:53
1. 为什么 Claude Code 的对话记录值得单独归档
用 Claude Code 写代码的人大多有过这种体验：某个下午和它来回几十轮，把一段祖传逻辑拆干净、补上测试、顺手修了三个边界 bug，结果第二天想回头翻当时那套方案，终端里只剩滚动的历史，/resume能恢复会话却没法把内容整段拿出来。Claude Code 本身没有导出按钮，它把每一轮对话以 JSONL 追加写进本地目录，一行一个 JSON 对象，字段里塞着 role、content、tool_use、tool_result、时间戳。文件在，但直接打开是一坨没有换行的长字符串，人眼基本没法读。
Claude Conversation Extractor 就是冲着这个缺口来的命令行工具。它扫描~/.claude/projects/下的chat_*.jsonl，把散落的会话解析成结构化的 Markdown、JSON 或 HTML，支持按编号导出、按最近条数导出、全文搜索，还能把工具调用参数、MCP 响应、终端命令输出一起带出来。适合三类人：需要把调试过程沉淀成团队文档的开发者、想给 AI 协作留审计痕迹的技术负责人、以及单纯不想让好方案随终端滚走的人。
我试过把一周的会话批量导出成 Markdown 丢进 Obsidian，检索效率比翻终端高太多。下面按“先装工具、再配环境、然后跑通导出、最后校验字段”的顺序走一遍，命令都能直接复制。
2. 安装 Claude Conversation Extractor 与 Python 环境准备
这个工具是 Python 包，要求 Python 3.8 以上。装法有两种，强烈建议用 pipx，因为它把工具隔离在独立虚拟环境里，不会污染你项目里的依赖，也不会撞上系统 Python 的 externally managed 限制。
macOS 上先补 pipx：
brew install pipx pipx ensurepath pipx install claude-conversation-extractorWindows 用 py 启动器：
py -m pip install --user pipx py -m pipx ensurepath # 重启终端后 pipx install claude-conversation-extractorUbuntu / Debian：
sudo apt install pipx pipx ensurepath pipx install claude-conversation-extractor如果你已经在虚拟环境里工作，也可以直接 pip：
pip install claude-conversation-extractor装完验证一下命令是否进 PATH：
claude-extract --help claude-start --help两个入口分别对应命令行模式和交互式界面。claude-start会打印 ASCII 标志并进入实时搜索菜单，适合不记参数的人；claude-extract适合写进脚本批量跑。
装之前先确认 Claude Code 确实产生过会话，否则工具扫不到文件会直接报 “No Claude sessions found”。检查目录：
ls -la ~/.claude/projects/正常应该看到若干以项目路径编码命名的子目录，里面躺着chat_*.jsonl。Windows 对应路径是%USERPROFILE%\.claude\projects\。如果这个目录不存在，说明你还没在 Claude Code 里真正对话过，先跑一轮再说。
注意：工具是只读的，不会改动 Claude Code 的任何文件，也不会联网，所有解析都在本地完成。这一点对处理含内部代码的会话很重要。
3. 可复制的导出配置与目录结构示例
真正开始导出前，先把输出目录和格式定下来。工具默认把结果写到~/Desktop/Claude logs/，文件名形如claude-conversation-2025-06-09-abc123.md。我习惯改成项目内的归档目录，方便跟代码一起提交或单独备份。
先看会话列表，拿到编号：
claude-extract --list输出会列出每条会话的编号、时间、首条消息摘要。拿到编号后按需导出：
# 导出编号 1、3、5 claude-extract --extract 1,3,5 # 导出最近 5 条 claude-extract --recent 5 # 全量导出 claude-extract --all # 指定输出目录 claude-extract --output ~/my-claude-backups格式用--format控制，三种可选：
| 格式 | 参数 | 适用场景 |
|---|---|---|
| Markdown | --format md | 默认，人读、进知识库 |
| JSON | --format json | 程序处理、二次分析 |
| HTML | --format html | 带语法高亮，适合分享 |
claude-extract --format json --extract 1 claude-extract --format html --all如果要把工具调用、MCP 响应、系统消息、终端输出都保留，加--detailed：
claude-extract --detailed --format html --recent 5导出后的目录结构大致是这样：
my-claude-backups/ ├── claude-conversation-2025-06-09-abc123.md ├── claude-conversation-2025-06-09-def456.md └── claude-conversation-2025-06-10-ghi789.md如果你想把导出动作固化下来，可以写一个 settings 风格的配置片段放进自己的脚本仓库，把路径和格式集中管理：
{ "source_dir": "~/.claude/projects", "output_dir": "~/my-claude-backups", "format": "md", "detailed": true, "recent": 10 }这个 JSON 不是工具自带的配置文件，而是我用来驱动自己包装脚本的参数集，读出来拼成claude-extract命令即可。这样换机器时只改一处路径。
搜索功能单独走claude-search：
claude-search "API integration" claude-search "error handling"它不区分大小写，支持精确和部分匹配，会显示匹配预览和上下文，命中后可以直接导出对应会话。交互式菜单里选 “Search conversations” 也能进实时搜索。
4. 验证导出请求与字段校验
导出跑完别急着关终端，先做几项校验，确认内容完整、字段没丢。
第一步，确认文件真的生成了：
ls -lh ~/my-claude-backups/第二步，看 Markdown 头部结构是否正常：
head -n 40 ~/my-claude-backups/claude-conversation-2025-06-09-abc123.md一份健康的导出应该能看到会话标题、时间、以及按角色分段的对话块。如果只有标题没有正文，多半是--detailed没加，或者源 JSONL 本身只有元数据。
第三步，用 JSON 格式做字段级校验。先导出一份 JSON：
claude-extract --format json --extract 1 --output /tmp/cc-check然后用 Python 快速检查关键字段是否存在：
import json, glob for path in glob.glob("/tmp/cc-check/*.json"): with open(path, encoding="utf-8") as f: data = json.load(f) print("file:", path) print("keys:", list(data.keys())) msgs = data.get("messages", []) print("message count:", len(msgs)) if msgs: print("first role:", msgs[0].get("role")) print("has content:", bool(msgs[0].get("content")))跑出来如果message count大于 0、role和content都在，说明解析链路是通的。如果messages为空，回到源文件确认：
wc -l ~/.claude/projects/*/chat_*.jsonl行数为 0 或文件不存在，就是 Claude Code 那边没写记录，跟导出工具无关。
第四步，抽查工具调用是否被保留。在 Markdown 里搜tool_use或命令片段：
grep -n "tool_use\|tool_result" ~/my-claude-backups/*.md | head带--detailed时这些应该出现；不带时被省略是预期行为。
5. 常见报错排查：No Claude sessions found 与 externally managed
排障这块我踩过的坑集中在三类，逐个说。
报错一：No Claude sessions found
工具扫不到会话。先确认 Claude Code 装过且用过：
ls -la ~/.claude/projects/目录不存在，或者存在但没有chat_*.jsonl，就是这个原因。另一个高频原因是用户不匹配——你用 sudo 或另一个账户跑的导出，扫的是那个账户的 home，自然找不到你日常账户的会话。确认当前用户：
whoami echo $HOME确保$HOME/.claude/projects/就是 Claude Code 实际写入的位置。权限问题也会导致扫不到，ls -la看下目录是否可读。
报错二：externally managed environment
这是 pip 在受管系统 Python 上装包时的拦截。别硬加--break-system-packages，直接用 pipx：
pipx install claude-conversation-extractorpipx 会把工具装进独立环境，绕开系统 Python 的限制，也不会破坏系统包。
报错三：local proxy failed/ 连接类报错
这个工具本身完全离线，不发起网络请求，所以出现代理相关报错通常是你的 shell 环境变量在干扰，比如HTTP_PROXY、HTTPS_PROXY被设成了不可用的地址。检查并临时清掉：
env | grep -i proxy unset HTTP_PROXY HTTPS_PROXY ALL_PROXY再重跑导出。工具不需要任何网络出口，清掉代理变量后应该恢复正常。
报错四：reading choices或 JSON 解析失败
源 JSONL 某一行被截断（比如 Claude Code 写入过程中被强杀），解析器读到半行 JSON 就会抛错。定位坏行：
python -c " import json p='你的chat文件路径.jsonl' for i,l in enumerate(open(p,encoding='utf-8'),1): try: json.loads(l) except Exception as e: print(i, e) "把报错行号对应的那条记录手动剔除或修复，再重新导出。日常遇到解析失败，先怀疑源文件完整性，而不是工具本身。
关于 OAuth 与鉴权
Claude Conversation Extractor 只读本地 JSONL，不碰任何账号鉴权，所以不会出现 OAuth 过期、token 失效这类问题。如果你在别的环节看到 OAuth 报错，那是 Claude Code 自身的登录态问题，跟导出工具无关，重新登录 Claude Code 即可。
6. 把导出流程接进日常归档与检索
工具跑通之后，真正提升效率的是把它变成习惯动作。我的做法是每周固定跑一次全量导出，输出到项目外的备份目录，再用claude-search做关键词回溯。比如想找当时怎么处理分页边界，直接：
claude-search "pagination boundary"命中后导出对应会话，Markdown 丢进知识库，标签打上项目名和日期。这样半年后回看，方案、踩坑、最终代码都在一份可检索的文档里，而不是散在终端历史。
如果你还想在导出之外做更顺的模型调用和编码协作，可以了解下 TaoToken 的接入方式。模型对话入口在 https://taotoken.net/api，API Key 在 https://taotoken.net/api-keys 管理，接入文档在 https://taotoken.net/doc，长期编码和 Agent 场景可以看 Coding Plan。这些链接都带上了归因参数，方便你从这篇教程直接跳过去。
最后留一个实用技巧：把导出命令包成 shell 函数写进.zshrc或.bashrc，比如alias cc-archive='claude-extract --all --detailed --format md --output ~/my-claude-backups'，以后一条命令完成归档，不用每次记参数。源 JSONL 建议保留，别删，导出只是可读副本，原始记录在排查解析问题时还有用。