claude-code-history-files-finder

Claude Code 历史文件查找器

搜索并恢复存储在活动主目录和显式注册的长期归档中的 Claude Code 会话历史记录内容。

功能

• 从 file-history 快照中恢复已删除或丢失文件的原始字节，包括在最初的 Write 调用后发生更改的文件
• 在对话历史记录中搜索特定代码或内容
• 分析过去会话中的文件修改
• 随时间追踪工具使用情况和文件操作
• 查找包含特定关键词或主题的会话

完整性不变量

常规历史记录搜索必须覆盖以下两类来源：

1. 自动发现的活动主目录（~/.claude、配置文件主目录和当前的 CLAUDE_CONFIG_DIR），以及
2. 在 ~/.claude/history-sources.json 中注册的所有归档。

除非命令输出确认已搜索注册的归档，否则不要断定某个会话、主题、文件或操作不存在。所需归档不可用属于严重配置错误。--home 和 --main-only 是精确的诊断范围，会有意绕过归档注册表；这两个标志的结果不能用于证明整个历史记录中不存在某项内容。

完整的来源集合是必要条件，但并非充分条件——即使覆盖了所有来源，另外三种失败模式仍会导致错误地得出“未找到”的结论，每种情况都有专门的扩展搜索方式（脚本会在零匹配时自动打印这些方式）：

1. 项目猜错。 你搜索了一个项目，但对话实际发生在另一个项目中。扩展搜索：--all-projects 一次性扫描所有项目。
2. 工具用错。 对话发生在 Codex 或 Kimi CLI 中，它们的 rollout/线缆日志存储在独立位置，Claude 注册表不会覆盖这些位置。扩展搜索：--codex 和 --kimi（两者均需显式启用；如果项目同时使用这两个工具开发，请同时传入）。
3. 措辞变化。 记忆中的引文与实际措辞在标点或少数词语上有所不同，因此精确短语搜索没有命中。扩展搜索：改用更短、更有辨识度的子字符串重试。

还有一个会与以上三种情况同时出现的陷阱：当前会话总会匹配你刚输入的短语（技能参数、命令和这段推理都会记录在当前会话中）。如果排名靠前的命中记录的时间范围从几分钟前开始，那几乎可以肯定是当前会话——请根据内部时间范围确认，然后使用 --exclude-session <id> 重新运行，以查看真正的结果。

会话文件位置

每个 Claude 历史根目录都在以下位置存储会话： <history-root>/projects/<encoded-project-path>/<session-id>.jsonl。系统会自动发现活动根目录。持久归档根目录只需在 ~/.claude/history-sources.json 中配置一次，之后便会默认纳入搜索范围。

Claude 也可能在 <history-root>/file-history/<session-id>/<opaque-backup-name> 中保存检查点载荷。JSONL 中的 file-history-snapshot.snapshot.trackedFileBackups 映射会将每个原始路径关联到其不透明备份名称和版本。这个配套存储与 projects/ 分开：仅将 JSONL 复制到长期归档，并不能证明检查点数据也一并复制了。该格式是观察到的 Claude Code 运行时细节，并非有文档说明的稳定 API，因此，随附的恢复解析器会验证所选映射、版本与名称是否一致、路径是否位于允许范围内，以及字节是否一致；若这些信息不匹配，则会明确报错。

目录名称是项目的绝对工作目录路径，其中每个 / 都替换为 -——绝不是目录名本身。 例如，/Users/<name>/Desktop/my-app 会变为 -Users-<name>-Desktop-my-app，因此单独的 my-app 无法与目录直接匹配。

在断定项目没有历史记录之前，请使用默认来源集运行随附命令。不要根据失败的 ls 推断历史记录不存在：

python3 scripts/analyze_sessions.py list /path/to/project
python3 scripts/analyze_sessions.py search /path/to/project '<keyword>'

如果 ls <basename> 没有返回结果，说明查询使用了错误的名称，并不表示历史记录不存在。随附的 analyze_sessions.py 会展开 ~、解析绝对路径、在名称唯一时回退到反向查找目录名，并搜索所有已配置的来源。建议传入项目的完整绝对路径；也接受 ~、相对路径和单独的名称。

注意：从 Claude Desktop 的 cowork / 内置 Claude Code 模式运行的会话也会保存在这里（Desktop 运行的是内置 CLI）；只有 Desktop 的原生聊天记录存放在别处（位于 LevelDB 存储中，而非 JSONL）。因此，“它是在 Desktop 中运行的”并不意味着它不会出现在 ~/.claude/projects/ 中。

默认同时搜索活动配置和长期归档

~/.claude 只是默认主目录。任何通过按模型配置文件使用 Claude Code 和第三方模型的人（每个配置文件都有自己的 CLAUDE_CONFIG_DIR），都会累积不会经过 ~/.claude 的并行历史记录：

• ~/.claude-profiles/<name>/projects/… — 每个配置文件一个（例如 kimi、deepseek、glm、step 配置文件）
• ~/.claude-<name>/projects/… — 偶尔出现的同级主目录
• 当前 shell 中 CLAUDE_CONFIG_DIR 指向的任意位置

长期归档是第二类独立来源。活动目录可能只保留最近的会话，而归档会在较旧的 JSONL 文件从活动目录中消失后继续保留它们。因此，仅搜索活动主目录也可能产生与仅搜索默认主目录相同的假阴性。

analyze_sessions.py 会处理这两类来源：list 和 search 会自动发现所有活动主目录并加载归档注册表，按 ID 去重会话，合并各副本中的内部时间范围，并保留每个来源标签作为来源信息。关键词搜索会扫描每个物理副本并对相同记录去重，因此即使较新的活动副本具有相同的会话 ID，归档中独有的记录也不会因此消失。只有在有意进行诊断时才限制搜索范围：

# default: active homes + registered archives
scripts/analyze_sessions.py search /path/to/project keyword

# exact diagnostic scope; not a completeness check
scripts/analyze_sessions.py search /path/to/project keyword --main-only

# exact diagnostic scope (repeatable)
scripts/analyze_sessions.py search /path/to/project keyword --home ~/.claude-profiles/kimi

# test a non-default source registry
scripts/analyze_sessions.py search /path/to/project keyword \
  --history-sources /path/to/history-sources.json

不要使用临时的原始 grep 来证明记录不存在。 它必须独立解析注册表、覆盖所有活动根目录、搜索非消息事件载荷，并根据内部记录时间戳筛选日期；随附脚本已经完成了这些工作。

有关 JSONL 详细结构和提取模式，请参阅 references/session_file_format.md。

核心操作

1. 列出项目的会话

查找特定项目的所有会话文件：

python3 scripts/analyze_sessions.py list /path/to/project

按最大内部 JSONL 时间戳对会话排序，并显示完整的内部时间范围、大小、路径和来源溯源信息。绝不会使用文件修改时间。

可选：使用 --limit N 仅显示 N 个会话（默认值：10），并使用 --from-date 或 --to-date 保留内部时间范围与指定时间窗口重叠的会话。--all-projects 会列出所有项目（按编码后的项目名称分组）；--exclude-session <id>（可重复使用）会跳过指定会话。

2. 按关键词搜索会话

查找包含特定内容的会话：

python3 scripts/analyze_sessions.py search /path/to/project keyword1 keyword2

返回按关键词出现频率排序的会话，其中包含：

• 提及总次数
• 每个关键词的详细统计
• 会话和匹配记录的内部时间范围
• 匹配字段类型、会话来源溯源信息和匹配来源溯源信息
• 主要匹配路径以及其他匹配副本

搜索范围包括消息、思考文本（不含签名）、工具输入/结果、 队列操作内容、附件、最后提示词、系统/摘要内容、 自定义标题，以及文件历史快照中的原始路径。可选： 使用 --case-sensitive 区分大小写；使用 --from-date 和 --to-date 按匹配记录自身的内部时间戳筛选，而不是按会话修改时间筛选。--exclude-session <id>（可重复使用）会排除会话——搜索刚刚输入的短语时，请传入当前会话的 ID，因为你自己的命令会使当前会话匹配。

仅指定日期的边界涵盖本地日历日的全天。日期时间边界必须带有 Z 或明确的 UTC 偏移量。日期筛选生效时，缺少有效内部时间戳的记录会被排除，并显示提示；迁移或复制后，绝不要用文件修改时间替代。

2a. 未知项目时进行搜索 — --all-projects

必需的项目参数代表一个猜测；猜错时，限定项目的搜索会报告虚假的“未找到”。省略位置参数，改为搜索所有项目（list 也接受相同的标志）：

python3 scripts/analyze_sessions.py search --all-projects 'some phrase'

使用 --all-projects 时，每个位置参数都是一个关键词，因此可以进行多关键词搜索：search --all-projects keyword1 keyword2。不使用该标志时，第一个位置参数是项目路径，其余参数是关键词。

预期输出：遍历所有来源中每个项目的所有会话，并在每个匹配结果中显示一行 Project:，标明编码后的项目目录。这会扫描完整历史——大型目录树需要几分钟，而非几秒。

2b. 纳入 Codex 历史记录 — --codex

Claude Code 并非唯一拥有历史记录的工具。Codex 会将 rollout 保存在 <codex-home>/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl 以及 archived_sessions/ 中（codex home = --codex-home、$CODEX_HOME 或 ~/.codex）。它们的架构与 Claude 不同，因此默认搜索会完全跳过这些文件；--codex 会额外搜索 rollout：

python3 scripts/analyze_sessions.py search /path/to/project 'some phrase' --codex

Codex 匹配结果会在单独的部分（📦）中显示，包含会话 ID、cwd、内部时间范围、提及次数和匹配字段。项目位置参数会根据 rollout 的 session_meta cwd 筛选文件（递归匹配）；使用 --all-projects 时则会搜索所有 rollout。event_msg 消息镜像与 response_item 消息文本完全重复，因此只计数一次。Rollout 记录格式见 references/session_file_format.md。

--codex 只会扩大搜索范围。Codex rollout 不包含 Claude 的文件历史映射，因此 recover_content.py 遇到 Codex rollout 时会明确报告边界错误，而不会返回一个看似成功但内容为空的恢复结果。

2c. 纳入 Kimi CLI 历史记录 — --kimi

Kimi CLI（kimi-code）将会话保存在 <kimi-home>/sessions/wd_<workspace>_<hash>/session_<uuid>/agents/<agent>/wire.jsonl 中，并使用每个会话的 state.json 保存 id/cwd/title 及以毫秒表示的 创建和更新时间范围（kimi home = --kimi-home、$KIMI_HOME 或 ~/.kimi-code）。wire 架构与 Claude 和 Codex 的都不同，因此 默认搜索会完全跳过它；--kimi 会额外搜索 wire：

python3 scripts/analyze_sessions.py search /path/to/project 'some phrase' --kimi

Kimi 命中项会显示在单独的部分（🌙），其中包含会话 id、标题、cwd、 内部范围、提及次数和匹配字段。项目位置参数会根据会话的 state.json cwd 筛选会话（递归匹配）；使用 --all-projects 时则会搜索所有会话。子 Agent 的 wire （agents/agent-N/）属于同一对话的不同运行，因此匹配项会按会话聚合， 并在每个匹配字段前加上 Agent 名称（例如 main:message、agent-0:tool_input）。可搜索的内容是 对话本身——提示词（turn.prompt / turn.steer，会为任意 origin 建立索引——搜索有意采用较宽泛的匹配范围）、追加的消息、助手内容部分、 工具调用和工具结果。静态的 固定内容（配置/配置文件系统提示词、工具快照、用量/令牌指标）有意不纳入索引： 只在共享系统提示词中出现的关键词会匹配每个会话，而本工具应当可靠地告知你 对话内容中「未找到」的情况。

--kimi 只会扩大搜索范围，与 --codex 完全相同。Kimi wire 日志 不包含 Claude 的文件历史映射，因此文件恢复仍仅支持 Claude Code JSONL；不要将 Kimi wire 路径传给 recover_content.py。--codex 和 --kimi 可以组合使用——同时使用这两种工具开发的项目需要在同一条命令中 指定这两个标志。

脚本打印的零匹配提示会指出尚未应用的 --all-projects / --codex / --kimi / 更短的子字符串选项—— 在断定内容不存在之前，请先查看 stderr。

3. 恢复已删除的内容

从所选会话恢复文件：

python3 scripts/recover_content.py <session-path-from-search>

对于每个路径，默认模式会合并同一会话 ID 的所有已知副本，选取最新的有效文件历史检查点，并从活动或已注册的存档伴随存储中恢复其原始字节。这样可以还原后续的 Edit 或由 shell 驱动的更改，还能恢复二进制文件或未通过 Write 工具调用创建的文件。如果较晚的 backupFileName: null 表示删除标记，则会恢复最后一个可用检查点，并在报告中注明后续删除。若某个路径没有可用的快照检查点，脚本会恢复最新的 Write 调用，并在 recovery_report.txt 中将其标记为保真度较低。若某个 Write 对应的 tool_result 明确包含 is_error: true，则会跳过该 Write；尝试写入不等于检查点。原始目录结构会保留在 ./recovered_content/ 下。

按关键词筛选：

python3 scripts/recover_content.py <session-path-from-search> \
  -k ModelLoading FRONTEND deleted

仅恢复路径中包含任一关键词的文件。

自定义输出目录：

python3 scripts/recover_content.py <session-path-from-search> -o ./my_recovery/

已注册的存档根目录和同 ID 的 JSONL 副本会自动纳入。如果未注册的伴随检查点存储位于其他位置，请添加直接包含 <session-id>/ 目录的根目录：

python3 scripts/recover_content.py <session-path-from-search> \
  --file-history-root /path/to/file-history \
  -o ./my_recovery/

缺少所引用备份的快照元数据属于保真度错误：恢复会在写入任何所选文件之前中止，而不会静默地改用过时的 Write 内容。只有在用户明确接受可能缺少后续 Edit 或 shell 更改时，才使用 --write-only。

4. 分析会话统计信息

获取详细的会话指标：

python3 scripts/analyze_sessions.py stats /path/to/session.jsonl

报告内容：

• 消息数量（用户/助手）
• 工具使用情况细分
• 文件操作数量（Write/Edit/Read）

可选：使用 --show-files 列出所有文件操作。

5. 提取用户原话

生成一份阅读页面，展示用户实际输入的内容——涵盖所有主目录和归档中的每条用户消息，并将框架噪声归入附录：

python3 scripts/extract_user_messages.py --days 7

默认写入 ~/.claude-flow-viewer/user-words.html（主要格式）和 .md——这是一个持久化路径；请避免使用 /tmp（操作系统会清理其中的文件）。传入一个 OUT_BASE 位置参数即可写入其他位置。实用标志：--group-by project|day（默认 project）、--min-dup N（套话频率阈值）、--home <path>（精确限定范围，可重复指定）。

这项任务的难点不在于解析，而在于判断作者身份：user 记录不一定由用户撰写。提取器实现了 references/session_file_format.md 中介绍的五类污染——命令封装、钩子／循环注入的套话（按频率检测，涵盖独立出现和追加在末尾两种形式）、[Image #N] 占位符、整篇文档粘贴，以及 Agent 口吻的重新注入（与较早的助手文本进行内容匹配）；此外，还会从 attachment.queued_command 记录中恢复工作中途输入的内容，并与之后送达的用户记录去重。修改过滤器前，请先阅读该参考章节。

6. 整理会话结束情况（崩溃恢复／积压审查）

对某个时间窗口或项目中的会话结束情况进行分类，并打印每个会话的完整最后一条助手消息——适用于查询“哪些会话被重启／崩溃中断了”或“哪些较早的会话仍在等待回复，并未真正结束”：

python3 scripts/analyze_sessions.py triage --all-projects \
  --from-date 2026-08-05T12:30:00+00:00 --to-date 2026-08-05T13:05:00+00:00

报告范围内每个会话的会话 ID（始终完整显示，不截断——请直接将其复制到任何后续报告中）、工作目录，以及五种结构化 kind 之一：interrupted_explicit（会话最后一条相关记录是明确的中断标记）、net_error（最后一轮助手回复因 API／传输错误而中止）、done（最后一轮助手回复生成了实际文本，且开头并非 API 错误）、empty（完全没有助手轮次），或 stuck_no_result——用于概括所有其他情况，因为就整理会话而言，它们的含义相同：**最后一轮没有生成文本回复，因此文件停止记录时模型仍在工作。**这包括仍在等待结果的工具调用、已收到结果但之后没有助手轮次的工具调用（框架很可能在结果到达后、模型下一轮被记录前停止了），以及仅包含思考内容或其他空内容的最后一轮。

**done 是结构标签，并不表示没有未完成事项。**会话可能在一段正常的 text 内容结束，因为助手提出了发现、决定或问题，却一直没有得到回复——要区分“已完全处理完毕”和“正在等你回复”，必须阅读打印出的 last_assistant_text。因此，此命令默认会打印其中最多 4000 个字符（使用 --tail-chars 0 表示不限制），而不是只显示截断的标题。完整说明及为何这与 kind 字段属于不同维度，请参阅 references/session_file_format.md 中的“检测会话中断”。

实用标志：--kind KIND（可重复指定，仅筛选特定类别——例如，--kind stuck_no_result --kind interrupted_explicit 表示“只显示崩溃有可能导致的会话”）；--exclude-title-prefix TEXT（可重复指定——排除开场提示以 TEXT 开头的会话，适用于项目自身的自动化约定，例如代码审查钩子总是以同一条固定提示开场；否则，这些会话会主导审查结果，因为它们通常以结构化工具调用结束，而非中断）；--tail-chars N（限制打印的最后一条助手文本长度；默认 4000，0 = 不限制）。与 list 共用 --from-date／--to-date／--home／--main-only／--history-sources，与 list 和 search 共用 --all-projects／项目路径／--exclude-session。

工作流示例

有关文件恢复、追踪文件演变和批量操作的详细工作流示例，请参阅 references/workflow_examples.md。

恢复最佳实践

去重

recover_content.py 会合并 ID 相同的会话副本，为每个原始路径保留文件历史版本最高的副本，并在版本相同时使用检查点时间戳。较晚的删除墓碑不会抹去较早且可恢复的备份；它只会改变报告的状态。对于没有可用检查点的路径，恢复会保留内部时间戳最新的 Write 调用。不同副本之间 JSONL 行的物理顺序不足以作为时间证据，而明确失败的 Write 工具结果会将该次 Write 排除在恢复范围之外。

关键词选择

选择具有辨识度且出现在以下内容中的关键词：

• 文件名或路径
• 函数／类名称
• 代码中的独特字符串
• 错误消息或注释

输出整理

创建描述性输出目录：

# Bad
python3 scripts/recover_content.py session.jsonl -o ./output/

# Good
python3 scripts/recover_content.py session.jsonl -o ./recovered_deleted_docs/
python3 scripts/recover_content.py session.jsonl -o ./feature_xy_history/

验证

恢复后，务必验证内容：

# Check directory structure (files preserved in subdirectories)
find ./recovered_content/ -type f

# Read recovery report (shows full output paths)
cat ./recovered_content/recovery_report.txt

# Spot-check content and compare the report's SHA-256 with the source backup
head -20 ./recovered_content/src/components/ImportantFile.jsx

将 Source: file-history 及其 SHA-256 视为精确捕获的检查点证据。将 Source: Write 视为可恢复的检查点，而非文件最终状态的证明。

限制

可恢复的内容

✅ 可用文件历史快照引用的精确字节 ✅ 配套文件历史存储中存在的二进制文件 ✅ 经 Edit 或 shell 命令修改、且被后续检查点捕获的文件 ✅ 没有快照元数据时通过 Write 写入的文件（保真度较低） ✅ 消息或工具结果中明确显示的文本（需手动提取）

无法恢复的内容

❌ 从未写入磁盘的文件（仅被讨论过） ❌ 会话开始前已删除的文件 ❌ 与归档 JSONL 一同删除或未复制的快照负载 ❌ 会话中未捕获的外部工具输出

Edit／Read 记录可以显示路径和 Edit 增量，但它们本身并非完整文件的恢复来源。

文件版本

• 文件历史备份是精确捕获的检查点，但不能保证之后没有发生未被检查点记录的文件系统变更。
• 没有文件历史条目时，Write 恢复无法重建后续的 Edit 或 shell 变更；Edit 记录包含的是增量，而非完整的变更后文件。
• 文件历史 JSONL／存储约定基于运行时观察，可能会演变；元数据格式错误或相互冲突时，必须明确报错，不得猜测。

故障排除

未找到会话

# Re-run with the full absolute project path and the default source set.
python3 scripts/analyze_sessions.py list /absolute/path/to/project

# Inspect a custom registry only when diagnosing its configuration.
python3 scripts/analyze_sessions.py list /absolute/path/to/project \
  --history-sources /path/to/history-sources.json

**“未找到”通常是项目标识错误或源集合不完整。**确认输出显示 Searched N source(s)，并包含预期的 active:<label> 和 archive:<label> 条目。如果使用了 --main-only 或 --home，请在不带这些参数的情况下重新运行。必须修复缺失的必需归档，或有意更改其注册表条目；不要默默忽略错误并声称会话不存在。如果确认源集合完整，请按照“完整性不变量”部分中的逐步扩大搜索范围：--all-projects → --codex → --kimi → 更短的子字符串，并使用 --exclude-session 排除当前会话。

恢复结果为空

可能的原因：

• 关键词与会话中的文件路径不匹配
• 会话早于文件创建时间
• 文件路径从未由文件历史或 Write 捕获

解决方案：

• 尝试使用 --show-edits 标志查看 Edit 操作
• 扩大关键词搜索范围
• 搜索相邻会话
• 如果精确备份错误指出缺少配套存储，请找到该存储并传入 --file-history-root；不要声称过时的 Write 检查点代表最终状态

大型会话文件

对于超过 100 MB 的会话：

• 逐行搜索 JSONL 流，而不是加载整个会话。
• 恢复时分块复制精确的备份字节，并且仅保留五条轻量级 Edit 摘要，绝不保留完整的 Edit 旧值／新值负载。
• 恢复时仍会保留有效的 Write 负载和复制合并所需的记录指纹，因此内存用量并非恒定。使用 -k 限制恢复范围，并预期运行时间会随发现的每个物理副本而增加。

安全与隐私

分享恢复的内容之前

会话文件可能包含：

• 含用户名的绝对路径
• API 密钥或凭据
• 公司专属信息

分享前务必进行脱敏：

# Read-only audit; review every hit before creating a separate redacted copy.
rg -n --hidden -S \
  '(api[_-]?key|password|token|secret|/Users/[^/]+/|/home/[^/]+/)' \
  recovered_content/

recovery_report.txt 也包含敏感信息：其中记录了请求的会话副本、原始绝对路径、检查点位置和输出路径。请与恢复的文件一并审查并脱敏报告；默认情况下不要分享。

安全存储

恢复的内容具有与原始会话相同的敏感性。请安全存储，并遵循组织处理会话数据的政策。

下一步：继续中断的工作

找到相关会话历史后，建议继续这项工作：

Found [N] relevant sessions with recoverable context.

Options:
A) Resume work — run /daymade-claude-code:continue-claude-work to pick up where you left off (Recommended)
B) Just show me the content — I'll decide what to do with it

维护者验证

在源代码仓库中，daymade-claude-code/_conversation_core/ 是此技能、local-conversation-history、continue-claude-work 和 continue-codex-work 共用的代码 SSOT。sync_core.py 会将该软件包打包到各技能的 scripts/_core/ 中；切勿直接编辑打包后的副本。

修改共享代码后，请同步并验证全部四个打包副本，然后运行查找器的隔离测试夹具：

uv run python ../sync_core.py sync
uv run python ../sync_core.py check
python -m unittest discover -s tests -p "test_*.py"