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 读明白以及怎么配一个能帮你读的模型入口。前置准备清单项目要求说明Node.js建议 18npx 依赖 Node 环境Claude Code已安装并至少用过一次否则 projects 目录为空磁盘权限可读~/.claude/projects只读即可Skill 不写文件模型入口可选用于解析 jsonl 内容见第三节配置如果你只是想先看看有哪些对话装完 Skill 就够了。但如果你想把「找到 UUID」到「还原上下文」这条链路走通建议把第三节的配置也一起做了。3. 可复制配置让模型帮你解析 jsonl 与定位 UUIDSkill 列出清单后你拿到的是 UUID 和文件路径。接下来要做的是打开对应的 jsonl把里面的对话内容还原出来。jsonl 是「每行一个 JSON 对象」的格式Claude Code 会把一次会话里的每条消息、每次工具调用、每个事件都写成一行。直接cat出来是一大坨人眼没法看所以需要一个能理解 JSON 结构的模型来帮你解析。这里给出一个可复制的配置思路。核心是三件套Base URL、API Key、Model ID。无论你用的是 Claude Code 本身、还是 Cline、还是别的支持自定义端点的客户端只要涉及接入模型这三件套都要填全缺一个都会报错。以 Claude Code 的配置为例它的配置文件通常在~/.claude/settings.jsonWindows 是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会直接 401Model 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 看一眼这个项目下有没有旧对话避免重复讨论同一个问题。这个动作花不了几秒但省下的时间很可观。