从 fileHistory 快照回滚实验说起Claude Code 的 Base URL 该怎么填如果你正在读 Claude Code 的源码想复现utils/fileHistory.ts里那套「编辑前存 v1、每轮对话后盘点、回滚时 copyFile 覆盖」的机制第一道坎往往不是代码本身而是让 Claude Code 的工具调用真正打到模型上。逐个厂商申请通道、配环境变量、处理区域限制这些琐事会把研究节奏切得很碎。这篇就把接入这一步固定下来打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 Key然后把 Claude Code 的 Base URL 填成https://taotoken.net/api注意不要带/v1也不要加 UTM 参数。TaoToken 在这里只负责提供 Key 和 Base URL不参与快照、备份、回滚、copyFile 或 readFileState 的任何逻辑——那些仍然是 Claude Code 自己的事。配通之后你才有条件去观察fileHistoryMakeSnapshot的引用复用、fileHistoryRewind的权限恢复以及超过MAX_SNAPSHOTS100后最早快照被淘汰的表现。下面按「先接入、再验证、后排查」的顺序展开。一、原问题与场景为什么研究 fileHistory 要先解决模型访问原文通过 sourceMap 还原了utils/fileHistory.ts讲清楚了几件事fileHistoryTrackEdit在 Edit/Write 执行前先存一份 v1 备份代表「AI 改之前」的状态每轮对话结束后fileHistoryMakeSnapshot对所有被追踪文件做一次盘点未变化的文件复用上一次的备份引用回滚时applySnapshot用copyFile把备份覆盖回原路径并恢复文件权限备份落在~/.claude/file-history/{sessionId}/命名格式是SHA256(path)[:16]v{version}子 Agent 在forkedAgent.ts里拿到的是空回调updateFileHistoryState: () {}因此不产生快照MAX_SNAPSHOTS 100超出后淘汰最早的快照copyFileHistoryForResume迁移备份时优先用硬链接失败才降级为拷贝。这些行为要真正跑起来观察前提是 Claude Code 能正常发起对话、调用工具。而 Claude Code 走的是 Anthropic 协议配置项集中在settings.json的ANTHROPIC_*环境变量里。如果模型访问这一步没打通你连一次 Edit 都触发不了更别提看磁盘上多出几份备份。所以本篇的定位很明确把「按官方渠道给 Claude Code 配模型访问」这一步替换成更省事的方式让你把精力留给快照与回滚实验本身。二、TaoToken 前置注册、创建 Key、确认 Base URL在动手改配置之前先把三样东西准备好注册账号访问 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 完成注册。创建 API Key进入控制台创建 Key形如YOUR_API_KEY。这个 Key 就是后面ANTHROPIC_AUTH_TOKEN要填的值。确认 Base URLhttps://taotoken.net/api。这里要强调两点——不要写成https://taotoken.net/api/v1也不要在这个地址后面拼 UTM 参数。Claude Code 会在这个 Base URL 基础上拼接自己的路径多一段/v1或查询串都可能导致请求 404 或鉴权异常。需要再说明一次边界TaoToken 只提供 Key 和 Base URL它不介入 fileHistory 的任何逻辑。快照什么时候创建、备份文件叫什么名字、回滚覆盖哪些路径全部由 Claude Code 本地代码决定。你把它理解成一个「模型访问入口」即可。三、可复制配置Claude Code 的 settings.json 怎么写Claude Code 读取的是settings.json里的环境变量配置。下面是一份可直接复制的模板把YOUR_API_KEY换成你刚创建的值{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }几个要点ANTHROPIC_BASE_URL必须是https://taotoken.net/api结尾不带斜杠、不带/v1。ANTHROPIC_AUTH_TOKEN填你的 Key。注意这里用的是AUTH_TOKEN而不是API_KEY两者在 Claude Code 里的语义不同填错会走到不同的鉴权分支。ANTHROPIC_MODEL填你要用的模型 ID。具体可用 ID 以控制台或文档为准不要凭记忆硬写。如果你更习惯用 CLI 方式启动也可以用npm i -g taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m claude-sonnet-4-5-20250929这条命令会把 Key、Base URL、模型 ID 一次性注入省去手改settings.json的步骤。两种方式选一种即可不要同时配避免互相覆盖。配置完成后建议重启一次 Claude Code确保新的环境变量被读取。四、验证请求与成功结果从一次 Edit 开始观察快照配置对不对最直接的验证方式是让它真的改一个文件。第一步发起一次简单编辑。在 Claude Code 里让它修改一个测试文件比如让它把demo.ts里的某个函数名改掉。这一步会触发 Edit 工具进而调用fileHistoryTrackEdit。第二步检查备份目录。编辑完成后去看~/.claude/file-history/{sessionId}/正常情况下你应该能看到一个以SHA256(path)[:16]v1命名的备份文件。这个 v1 就是「AI 改之前」的原始内容。如果目录不存在或为空说明工具调用没有真正走到模型或者fileHistoryTrackEdit没有拿到有效的captured状态。第三步跑多轮对话验证引用复用。原文给了一个很清晰的实验设计追踪三个文件跑四轮对话观察磁盘上是否只新增两份额外备份。具体预期是Snapshot 1Av1, Bv1, Cv1 → 磁盘 3 个备份文件Snapshot 2Av2, Bv1, Cv1 → 只新增 1 个A 变了Snapshot 3Av2, Bv1, Cv2 → 只新增 1 个C 变了Snapshot 4Av2, Bv1, Cv2 → 无新增全都没变。如果你观察到的新增数量与这个预期一致说明fileHistoryMakeSnapshot的引用复用逻辑正常工作同时也侧面证明模型访问是通的——因为每一轮对话都真实发生了。第四步验证回滚。用fileHistoryRewind回到某个历史 messageId检查目标文件是否被copyFile覆盖回对应版本以及文件权限是否被恢复。这一步能验证applySnapshot的行为。第五步验证快照上限。如果你愿意多跑几轮可以观察超过 100 个快照后最早的快照是否被淘汰。这个实验比较耗时但能确认MAX_SNAPSHOTS 100的边界行为。五、本篇常见错排查报错一请求返回 404 或路径拼接异常。最常见的原因是 Base URL 写成了https://taotoken.net/api/v1。Claude Code 会自己拼路径多一段/v1就会打到不存在的端点。改成https://taotoken.net/api即可。另外检查有没有在地址后面误加了 UTM 查询串。报错二鉴权失败、401。先确认ANTHROPIC_AUTH_TOKEN填的是 Key 本身而不是ANTHROPIC_API_KEY。这两个变量在 Claude Code 里走不同分支填错位置会导致鉴权头没带上。其次确认 Key 没有多余空格或换行。报错三配置改了但不生效。Claude Code 通常在启动时读取settings.json。改完配置后要重启进程。如果你同时用了 CLI 注入和settings.json两者可能互相覆盖建议只保留一种。报错四编辑发生了但备份目录是空的。这种情况要分两层看。第一层确认工具调用真的打到了模型——如果对话本身没成功Edit 根本不会执行。第二层如果你是在子 Agent 场景下观察注意forkedAgent.ts里的updateFileHistoryState是空函数子 Agent 不产生快照这是设计如此不是 bug。报错五回滚后文件权限不对。applySnapshot会恢复文件权限但如果你在回滚前后手动改过权限或者备份文件本身的权限在迁移过程中丢失可能出现不一致。检查copyFileHistoryForResume是否走了硬链接路径——硬链接共享 inode权限是同一份如果降级为copyFile权限需要显式chmod。报错六Session Resume 后备份找不到。恢复会话时copyFileHistoryForResume会把旧 session 的备份迁移到新 session 目录。如果迁移失败可能是跨文件系统导致硬链接失败且降级逻辑没生效。检查新旧目录是否在同一挂载点。六、语义一致的 CTA接入配置和排障相关的操作集中在 API Keys 页面和接入文档里创建和管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档含 Base URL 与各客户端配置说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你想先验证模型是否可用可以直接在模型对话里发一条测试请求模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite如果你打算长期用 Claude Code 做源码研究、跑多轮快照实验或者把这类观察变成日常编码流程的一部分可以了解 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite回到本篇的主题fileHistory 的快照与回滚机制本身完全在 Claude Code 本地运行TaoToken 只解决「让工具调用打到模型」这一步。把 Base URL 填对、Key 配好你就能把注意力放回fileHistoryMakeSnapshot的引用复用、applySnapshot的覆盖行为以及那 100 个快照的淘汰边界上。
从 fileHistory 快照回滚实验说起Claude Code 的 Base URL 该怎么填如果你正在读 Claude Code 的源码想复现utils/fileHistory.ts里那套「编辑前存 v1、每轮对话后盘点、回滚时 copyFile 覆盖」的机制第一道坎往往不是代码本身而是让 Claude Code 的工具调用真正打到模型上。逐个厂商申请通道、配环境变量、处理区域限制这些琐事会把研究节奏切得很碎。这篇就把接入这一步固定下来打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 Key然后把 Claude Code 的 Base URL 填成https://taotoken.net/api注意不要带/v1也不要加 UTM 参数。TaoToken 在这里只负责提供 Key 和 Base URL不参与快照、备份、回滚、copyFile 或 readFileState 的任何逻辑——那些仍然是 Claude Code 自己的事。配通之后你才有条件去观察fileHistoryMakeSnapshot的引用复用、fileHistoryRewind的权限恢复以及超过MAX_SNAPSHOTS100后最早快照被淘汰的表现。下面按「先接入、再验证、后排查」的顺序展开。一、原问题与场景为什么研究 fileHistory 要先解决模型访问原文通过 sourceMap 还原了utils/fileHistory.ts讲清楚了几件事fileHistoryTrackEdit在 Edit/Write 执行前先存一份 v1 备份代表「AI 改之前」的状态每轮对话结束后fileHistoryMakeSnapshot对所有被追踪文件做一次盘点未变化的文件复用上一次的备份引用回滚时applySnapshot用copyFile把备份覆盖回原路径并恢复文件权限备份落在~/.claude/file-history/{sessionId}/命名格式是SHA256(path)[:16]v{version}子 Agent 在forkedAgent.ts里拿到的是空回调updateFileHistoryState: () {}因此不产生快照MAX_SNAPSHOTS 100超出后淘汰最早的快照copyFileHistoryForResume迁移备份时优先用硬链接失败才降级为拷贝。这些行为要真正跑起来观察前提是 Claude Code 能正常发起对话、调用工具。而 Claude Code 走的是 Anthropic 协议配置项集中在settings.json的ANTHROPIC_*环境变量里。如果模型访问这一步没打通你连一次 Edit 都触发不了更别提看磁盘上多出几份备份。所以本篇的定位很明确把「按官方渠道给 Claude Code 配模型访问」这一步替换成更省事的方式让你把精力留给快照与回滚实验本身。二、TaoToken 前置注册、创建 Key、确认 Base URL在动手改配置之前先把三样东西准备好注册账号访问 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 完成注册。创建 API Key进入控制台创建 Key形如YOUR_API_KEY。这个 Key 就是后面ANTHROPIC_AUTH_TOKEN要填的值。确认 Base URLhttps://taotoken.net/api。这里要强调两点——不要写成https://taotoken.net/api/v1也不要在这个地址后面拼 UTM 参数。Claude Code 会在这个 Base URL 基础上拼接自己的路径多一段/v1或查询串都可能导致请求 404 或鉴权异常。需要再说明一次边界TaoToken 只提供 Key 和 Base URL它不介入 fileHistory 的任何逻辑。快照什么时候创建、备份文件叫什么名字、回滚覆盖哪些路径全部由 Claude Code 本地代码决定。你把它理解成一个「模型访问入口」即可。三、可复制配置Claude Code 的 settings.json 怎么写Claude Code 读取的是settings.json里的环境变量配置。下面是一份可直接复制的模板把YOUR_API_KEY换成你刚创建的值{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }几个要点ANTHROPIC_BASE_URL必须是https://taotoken.net/api结尾不带斜杠、不带/v1。ANTHROPIC_AUTH_TOKEN填你的 Key。注意这里用的是AUTH_TOKEN而不是API_KEY两者在 Claude Code 里的语义不同填错会走到不同的鉴权分支。ANTHROPIC_MODEL填你要用的模型 ID。具体可用 ID 以控制台或文档为准不要凭记忆硬写。如果你更习惯用 CLI 方式启动也可以用npm i -g taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m claude-sonnet-4-5-20250929这条命令会把 Key、Base URL、模型 ID 一次性注入省去手改settings.json的步骤。两种方式选一种即可不要同时配避免互相覆盖。配置完成后建议重启一次 Claude Code确保新的环境变量被读取。四、验证请求与成功结果从一次 Edit 开始观察快照配置对不对最直接的验证方式是让它真的改一个文件。第一步发起一次简单编辑。在 Claude Code 里让它修改一个测试文件比如让它把demo.ts里的某个函数名改掉。这一步会触发 Edit 工具进而调用fileHistoryTrackEdit。第二步检查备份目录。编辑完成后去看~/.claude/file-history/{sessionId}/正常情况下你应该能看到一个以SHA256(path)[:16]v1命名的备份文件。这个 v1 就是「AI 改之前」的原始内容。如果目录不存在或为空说明工具调用没有真正走到模型或者fileHistoryTrackEdit没有拿到有效的captured状态。第三步跑多轮对话验证引用复用。原文给了一个很清晰的实验设计追踪三个文件跑四轮对话观察磁盘上是否只新增两份额外备份。具体预期是Snapshot 1Av1, Bv1, Cv1 → 磁盘 3 个备份文件Snapshot 2Av2, Bv1, Cv1 → 只新增 1 个A 变了Snapshot 3Av2, Bv1, Cv2 → 只新增 1 个C 变了Snapshot 4Av2, Bv1, Cv2 → 无新增全都没变。如果你观察到的新增数量与这个预期一致说明fileHistoryMakeSnapshot的引用复用逻辑正常工作同时也侧面证明模型访问是通的——因为每一轮对话都真实发生了。第四步验证回滚。用fileHistoryRewind回到某个历史 messageId检查目标文件是否被copyFile覆盖回对应版本以及文件权限是否被恢复。这一步能验证applySnapshot的行为。第五步验证快照上限。如果你愿意多跑几轮可以观察超过 100 个快照后最早的快照是否被淘汰。这个实验比较耗时但能确认MAX_SNAPSHOTS 100的边界行为。五、本篇常见错排查报错一请求返回 404 或路径拼接异常。最常见的原因是 Base URL 写成了https://taotoken.net/api/v1。Claude Code 会自己拼路径多一段/v1就会打到不存在的端点。改成https://taotoken.net/api即可。另外检查有没有在地址后面误加了 UTM 查询串。报错二鉴权失败、401。先确认ANTHROPIC_AUTH_TOKEN填的是 Key 本身而不是ANTHROPIC_API_KEY。这两个变量在 Claude Code 里走不同分支填错位置会导致鉴权头没带上。其次确认 Key 没有多余空格或换行。报错三配置改了但不生效。Claude Code 通常在启动时读取settings.json。改完配置后要重启进程。如果你同时用了 CLI 注入和settings.json两者可能互相覆盖建议只保留一种。报错四编辑发生了但备份目录是空的。这种情况要分两层看。第一层确认工具调用真的打到了模型——如果对话本身没成功Edit 根本不会执行。第二层如果你是在子 Agent 场景下观察注意forkedAgent.ts里的updateFileHistoryState是空函数子 Agent 不产生快照这是设计如此不是 bug。报错五回滚后文件权限不对。applySnapshot会恢复文件权限但如果你在回滚前后手动改过权限或者备份文件本身的权限在迁移过程中丢失可能出现不一致。检查copyFileHistoryForResume是否走了硬链接路径——硬链接共享 inode权限是同一份如果降级为copyFile权限需要显式chmod。报错六Session Resume 后备份找不到。恢复会话时copyFileHistoryForResume会把旧 session 的备份迁移到新 session 目录。如果迁移失败可能是跨文件系统导致硬链接失败且降级逻辑没生效。检查新旧目录是否在同一挂载点。六、语义一致的 CTA接入配置和排障相关的操作集中在 API Keys 页面和接入文档里创建和管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档含 Base URL 与各客户端配置说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你想先验证模型是否可用可以直接在模型对话里发一条测试请求模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite如果你打算长期用 Claude Code 做源码研究、跑多轮快照实验或者把这类观察变成日常编码流程的一部分可以了解 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite回到本篇的主题fileHistory 的快照与回滚机制本身完全在 Claude Code 本地运行TaoToken 只解决「让工具调用打到模型」这一步。把 Base URL 填对、Key 配好你就能把注意力放回fileHistoryMakeSnapshot的引用复用、applySnapshot的覆盖行为以及那 100 个快照的淘汰边界上。
