用 list-claude-conversations 这个 Skill 把 Claude Code 的对话记录一目了然地翻出来：从 jsonl 到 UUID 的排查实战

1. 为什么 Claude Code 的对话记录总像开盲盒

用 Claude Code 写代码超过两周，你大概率会遇到这个场景：某天想翻出三天前讨论过的一段架构方案，记得当时聊得很细，但完全想不起来是在哪个项目目录下聊的，更别提那次会话的 UUID 是什么。于是你打开终端，cd 到~/.claude/projects，看到一堆名字像乱码的文件夹，点进去又是一堆.jsonl文件，文件名清一色是 UUID，肉眼根本对不上号。

这不是你的问题，是 Claude Code 的存储设计决定的。它把每个项目的对话按项目路径分目录存放，目录名是把项目绝对路径里的非字母数字字符全部替换成-得到的。比如D:\Projects\Foo会变成D--Projects-Foo，/home/me/work/api会变成-home-me-work-api。这种规则机器读起来没问题，人读起来就是灾难。再加上每个对话文件本身没有语义化文件名，只有一串 UUID，想找某次对话基本等于开盲盒。

/resume命令能列出当前项目的对话，但它是按时间倒序刷一大片，对话一多就眼花，而且它只覆盖当前项目，跨项目查找无能为力。更麻烦的是，Claude Code 目前没有内置的对话删除或清理功能，记录只会越攒越多。

list-claude-conversations这个 Skill 就是冲着这个痛点来的。它把本机所有项目（或指定项目）的 Claude Code 对话整理成一份可读清单，包含对话标题、UUID、首条用户消息摘要、文件路径、大小、行数、子代理数量，按项目分组展示。核心检索词就是 list-claude-conversations、Claude Code、Skill、jsonl、UUID 这几个，本文会围绕它们把从部署到排查的完整链路讲清楚。

它适合谁？适合所有用 Claude Code 超过一周、本地已经攒了十几个以上会话、开始需要回溯历史上下文的人。如果你只是偶尔用一次，可能感受不深；但只要你开始依赖 Claude Code 做长期项目，这个 Skill 的价值会立刻显现。

2. 部署 list-claude-conversations Skill 与前置准备

在动手之前，先把前置条件理清楚。这个 Skill 本质是一个通过npx skills安装的扩展，它读取的是 Claude Code 已经写在本地磁盘上的 jsonl 文件，所以它不依赖任何在线服务，也不需要额外的 API Key 就能列出对话。但如果你后续想用 AI 帮你解析 jsonl 内容、按 UUID 定位会话并还原上下文，那就需要一个能调用模型的入口，这部分我会在第三节给出可复制的配置。

先看部署。官方给出的安装命令是：

npx skills add https://github.com/xiabq10/Skill --skill list-claude-conversations

这条命令会从 GitHub 仓库把list-claude-conversations这个 Skill 提取到你的本地 Skill 目录。执行过程中 npx 会先拉取 skills 工具本身，然后按--skill参数筛选出目标 Skill。实测下来，第一次执行会稍微慢一点，因为要下载依赖；后续再装别的 Skill 就快了。

装完之后，你可以在 Claude Code 里直接调用它。调用方式不是敲命令，而是用自然语言提问，比如：

• 「当前项目有哪些对话？」
• 「所有项目里都有哪些对话？」
• 「列出所有对话，要详细版」

Skill 会根据你的措辞决定输出简洁版还是详细版。简洁版适合快速扫描，详细版会展开每个对话的元信息。

这里有个容易踩的坑：很多人以为装完 Skill 就能在任意目录下看到所有项目，其实 Skill 读取的是~/.claude/projects这个固定路径。在 Windows 上，~对应的是C:\Users\<你的用户名>，所以完整路径是C:\Users\<你的用户名>\.claude\projects。如果你之前改过 Claude Code 的配置目录，Skill 可能读不到，需要确认环境变量或配置里没有覆盖默认路径。

另外，Skill 本身只负责「列出」，不负责「解析内容」。也就是说，它能告诉你某个 UUID 对应哪次对话、首条消息是什么，但如果你想看这次对话里具体聊了什么、有哪些工具调用、上下文怎么演进的，还得自己去读 jsonl 文件，或者让 AI 帮你读。这就引出了下一节的核心：怎么把 jsonl 读明白，以及怎么配一个能帮你读的模型入口。

前置准备清单：

如果你只是想先看看有哪些对话，装完 Skill 就够了。但如果你想把「找到 UUID」到「还原上下文」这条链路走通，建议把第三节的配置也一起做了。

3. 可复制配置：让模型帮你解析 jsonl 与定位 UUID

Skill 列出清单后，你拿到的是 UUID 和文件路径。接下来要做的是：打开对应的 jsonl，把里面的对话内容还原出来。jsonl 是「每行一个 JSON 对象」的格式，Claude Code 会把一次会话里的每条消息、每次工具调用、每个事件都写成一行。直接cat出来是一大坨，人眼没法看，所以需要一个能理解 JSON 结构的模型来帮你解析。

这里给出一个可复制的配置思路。核心是三件套：Base URL、API Key、Model ID。无论你用的是 Claude Code 本身、还是 Cline、还是别的支持自定义端点的客户端，只要涉及接入模型，这三件套都要填全，缺一个都会报错。

以 Claude Code 的配置为例，它的配置文件通常在~/.claude/settings.json（Windows 是C:\Users\<用户名>\.claude\settings.json）。一个可复制的 settings 片段如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

注意ANTHROPIC_BASE_URL填的是https://taotoken.net/api，不要带多余的路径后缀。API Key 在控制台的 API Keys 页面生成，生成后只显示一次，记得及时保存。Model ID 要和你实际想用的模型对应，填错会报模型不存在。

如果你用的是 Cline 这类支持 MCP 的客户端，配置形态会不一样，但三件套的逻辑一致。Cline 的 MCP 配置通常写在cline_mcp_settings.json里，结构大致是：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "你的mcp包"], "env": { "BASE_URL": "https://taotoken.net/api", "API_KEY": "sk-你的Key", "MODEL_ID": "claude-sonnet-4-20250514" } } } }

如果你用的是 Codex 系的工具，认证信息可能落在auth.json里，形态类似：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "claude-sonnet-4-20250514" }

不管哪种客户端，记住一个原则：Base URL、Key、Model ID 必须成套出现。只填 Key 不填 Base URL，请求会打到默认端点；只填 Base URL 不填 Key，会直接 401；Model ID 写错，会报模型找不到。这三件套是后面所有排查的基础。

配好之后，你就可以让模型帮你读 jsonl 了。一个实用的提问模板是：

读取~/.claude/projects/<项目目录名>/<UUID>.jsonl，按时间顺序还原这次对话的用户消息和助手回复，忽略工具调用的原始参数，只保留工具名和结果摘要。

模型会逐行解析 JSON，把type为user和assistant的行提取出来，按timestamp排序，还原成可读的对话流。这样你就不用自己写解析脚本了。

如果你需要长期做这类解析、或者要跑 Agent 任务，可以考虑用 Coding Plan 这类面向编码场景的方案，它在长上下文和工具调用上更稳。入口在控制台里能找到。

4. 验证请求与成功结果：从清单到 UUID 定位

配置好之后，先做一次最小验证，确认链路是通的。验证分两步：第一步确认 Skill 能列出对话，第二步确认模型能读到 jsonl 内容。

第一步，在 Claude Code 里问「当前项目有哪些对话？」。如果 Skill 正常工作，你会看到类似这样的输出（简洁版）：

项目：D--Projects-Foo - 重构用户认证模块 a1b2c3d4-... 首条消息：帮我把 auth 中间件拆出来... - 修复登录超时 e5f6g7h8-... 首条消息：登录接口偶尔 504...

详细版会多出文件路径、大小、行数、子代理数量。拿到 UUID 后，你就能拼出完整路径：

~/.claude/projects/D--Projects-Foo/a1b2c3d4-....jsonl

第二步，让模型读这个文件。提问：

读取~/.claude/projects/D--Projects-Foo/a1b2c3d4-....jsonl，告诉我这次对话一共多少轮，最后一条用户消息是什么。

如果模型能返回轮数和最后一条消息，说明 Base URL、Key、Model ID 三件套都生效了，jsonl 也能被正确解析。这一步的成功标志是：模型返回的内容和你印象中那次对话对得上，而不是报错或返回空。

验证记录完整性时，可以对照几个字段。jsonl 里每行通常包含type、message、timestamp、uuid、parentUuid等字段。type区分是用户消息还是助手消息，parentUuid用来串起对话树。如果你发现某次对话的行数和 Skill 报告的行数对不上，可能是文件被截断或写入中断。这时候可以用wc -l数一下实际行数：

wc -l ~/.claude/projects/D--Projects-Foo/a1b2c3d4-....jsonl

再和 Skill 报告的行数对比。如果一致，说明文件完整；如果不一致，可能是 Skill 读取时做了过滤，或者文件确实有问题。

按 UUID 定位会话的关键动作就三步：从 Skill 清单拿到 UUID，拼出完整路径，用模型或命令行读取。整个过程不需要你手动去猜目录名，因为 Skill 已经把「项目 → 对话标题 → UUID」这层映射做好了。

实测下来，这套流程在几十个会话的规模下非常顺，基本几十秒就能定位到目标对话。踩过的坑主要是路径拼接：Windows 上的反斜杠和正斜杠混用容易出错，建议统一用正斜杠，或者在 Git Bash 里操作。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节把实际会遇到的报错逐个拆开。这些报错大多不是 Skill 本身的问题，而是模型接入配置或环境的问题。

401 Unauthorized。这是最常见的。原因通常是 API Key 没填、填错、或者过期。排查顺序：先确认ANTHROPIC_API_KEY或对应字段里确实是完整的 Key，没有多余空格；再确认这个 Key 在控制台里还有效；最后确认 Base URL 和 Key 是配套的，没有把 A 平台的 Key 填到 B 平台的端点。如果三件套里 Key 对了但 Base URL 写成了别的地址，也会 401。

local proxy failed。这个报错通常出现在客户端尝试走本地代理但代理没起来的时候。检查你的客户端配置里有没有多余的 proxy 设置，如果有，确认代理进程是否在运行。多数情况下，把代理相关配置清掉、直连 Base URL 就能解决。注意这里说的是客户端自身的网络配置，不是让你去搭什么通道，只是把多余的本地转发关掉。

reading choices 相关报错。这类报错一般出现在模型返回结构不符合客户端预期时，比如客户端期望choices数组但拿到的是别的结构。常见原因是 Model ID 填错了，导致请求打到了不兼容的端点。把 Model ID 改成正确的值，比如claude-sonnet-4-20250514，通常就好了。另外确认 Base URL 没有多加/v1之类的后缀，不同客户端对路径的处理不一样。

OAuth 相关报错。如果你用的是需要 OAuth 授权的客户端，报错可能是 token 过期或授权范围不对。解决办法是重新走一遍授权流程，或者在配置里改用 API Key 方式。对于 Claude Code 这类工具，用 API Key 直连通常比 OAuth 更省事，配置项就是上面那三件套。

除了这些，还有一个容易忽略的点：jsonl 文件路径里的项目目录名。如果你手动拼路径，一定要确认目录名和 Skill 报告的一致。有时候项目路径里有中文或特殊字符，替换规则会把它们也变成-，拼错一个字符就找不到文件。最稳的做法是直接从 Skill 输出里复制完整路径。

排查时建议按这个顺序：先确认 Skill 能列出对话（说明本地文件没问题），再确认模型能读文件（说明三件套没问题），最后确认具体报错对应的配置项。大部分问题都出在第二步的三件套上。

6. 把对话记录变成可检索的资产

走到这里，你已经能把 Claude Code 的对话从一堆 UUID 文件变成一份可读清单，也能按 UUID 定位到具体会话并还原上下文。这套流程的价值不在于「看一眼」，而在于让历史对话变成可检索、可复用的资产。

几个实用技巧。第一，养成用/rename给重要对话起名的习惯，Skill 会优先显示你起的名字，比自动生成的标题好认得多。第二，定期用 Skill 列一遍所有项目，把不再需要的对话记下来，虽然 Claude Code 目前不能直接删，但你可以手动清理对应的 jsonl 文件，清理前记得备份。第三，如果你经常需要回溯上下文，可以把「列出对话 + 读取指定 UUID」做成一个固定提问模板，每次直接套用。

需要模型入口的话，API Keys 页面生成 Key，接入文档里有各客户端的详细配置。想先验证模型能不能正常对话，可以用模型对话页面试一句。长期做编码和 Agent 任务，Coding Plan 会更合适。这三个入口按你的实际需求选，不用全上。

最后留一个我自己的习惯：每次开新项目前，先用 Skill 看一眼这个项目下有没有旧对话，避免重复讨论同一个问题。这个动作花不了几秒，但省下的时间很可观。