1. 项目概述为AI编程时代引入“时光机”如果你和我一样已经深度依赖Claude Code、Cursor这类AI编程助手来写代码那你一定遇到过这个场景AI助手噼里啪啦改了一堆文件你看着满屏的变更心里却犯嘀咕——“它到底是怎么想的为什么要这么改” 或者更糟AI助手突然“跑偏”生成了一堆垃圾代码你想回退到几分钟前那个思路清晰的状态却发现除了git reset --hard这种“一刀切”的办法根本无从下手。这就是entireio/cli以下简称Entire要解决的核心痛点。它不是一个全新的AI工具而是一个**“元工具”**一个专门为AI编程工作流设计的“黑匣子”和“时光机”。简单来说Entire会悄无声息地嵌入到你现有的Git工作流和AI工具如Claude Code、Cursor、GitHub Copilot CLI等中在你每次与AI交互、每次提交代码时自动、完整地记录下整个会话过程。想象一下你的Git提交历史旁边多了一个完全同步的、可搜索的“上下文层”。每一次提交都关联着生成这些代码的完整对话记录、使用的提示词、AI的思考过程、修改了哪些文件甚至Token消耗。这不仅仅是日志而是一个结构化的、版本化的知识库。当你想知道“三个月前这个复杂的函数为什么被重构”时不再需要翻聊天记录或靠模糊的记忆直接entire explain那个提交当时的完整对话和决策过程就一目了然。当AI助手“发疯”时你可以用entire rewind精准回退到任何一个之前的“检查点”就像游戏存档一样从那个完好的状态无缝继续。1.1 核心价值从“是什么”到“为什么”的跨越传统版本控制系统如Git完美地回答了“代码发生了什么变化”What changed。而Entire旨在回答一个在AI协作时代至关重要的问题“代码为什么这样变化”Why it changed。这个“为什么”包含了人类开发者与AI助手之间完整的协作上下文意图溯源最初的提示词Prompt是什么是模糊的需求描述还是精确的指令决策过程AI是如何一步步推理的它考虑了哪些方案又为什么否决了它们变更关联每一次AI的输出具体修改了哪些文件的哪些行这些修改之间的逻辑关系是什么状态恢复在漫长的调试或重构会话中任何一个中间状态都可以被保存和恢复避免了“推倒重来”的挫败感。对于团队而言它的价值更加凸显。新成员接手一个大量使用AI生成或修改的项目时可以通过Entire的记录快速理解前辈的“创作过程”极大缩短上手时间。在需要审计或合规的场景下AI生成代码的完整溯源也提供了可靠的依据。1.2 设计哲学无侵入、Git原生、多智能体兼容使用Entire最直观的感受就是“轻”。它严格遵循了几个关键设计原则这也是我认为它可能成功的原因无侵入你的主分支Entire永远不会在你的main、master或任何功能分支上创建提交。所有会话数据元数据都被巧妙地存储在一个独立的、名为entire/checkpoints/v1的分支上。你的代码提交历史保持绝对干净。Git原生工作流它通过安装Git钩子Hooks和与各AI工具的插件接口来捕获数据。你不需要改变现有的git commit、git push习惯。它只是在一旁安静地记录。多智能体支持它不绑定任何单一AI供应商。目前官方支持Claude Code、Cursor、GitHub Copilot CLI、Gemini CLI、OpenCode等主流工具并且可以同时启用多个。你的工作流不会因为切换AI工具而断裂。手动提交策略检查点Checkpoint的创建与你或AI工具的Git提交动作绑定。这给了开发者完全的控制权只在认为有意义的时间点保存状态避免了自动保存可能带来的噪音。接下来我将带你深入Entire的内部机制手把手完成从安装、配置到高阶使用的全过程并分享我在实际体验中总结的实操技巧和避坑指南。2. 核心概念与架构解析要玩转Entire必须吃透它的几个核心概念。这些概念构成了其数据模型和工作流的基石。2.1 会话与检查点理解数据模型会话是你与AI助手一次完整的、有逻辑关联的交互周期。例如你打开终端启动Claude Code让它“为项目添加用户登录功能”然后经过多轮对话和代码修改最终完成并提交代码——这整个过程构成一个会话。一个会话包含会话ID格式为YYYY-MM-DD-UUID如2024-05-17-abc123de-f456-7890-abcd-ef1234567890。这确保了全局唯一性。完整转录你和AI之间所有的输入提示词和输出。文件变更追踪会话过程中哪些文件被创建、读取、修改、删除。工具调用记录AI调用了哪些外部工具或命令如果AI支持。元数据时间戳、使用的AI模型、Token消耗等。检查点则是会话中的一个“存档点”。你可以把它想象成游戏中的快速保存。在Entire的默认策略下每当你执行git commit时就会自动创建一个检查点。检查点捕获了截至该提交时刻当前会话的所有状态。它的ID是一个12位的十六进制字符串如a3b2c4d5e6f7短小精悍便于在entire rewind命令中快速选择。关键理解一个会话可以包含多个检查点多次提交但一个检查点只属于一个会话。当你entire rewind时你回退到的是某个检查点它承载着那个时间点的代码状态和会话上下文。2.2 双分支存储策略如何保持Git历史清洁这是Entire设计中最精妙的部分。它采用了“代码与上下文分离存储”的策略。你的工作分支 (main/feature) Entire元数据分支 (entire/checkpoints/v1) │ │ │─── 开始AI会话 ────────────────────────┤ │ 你 “添加登录功能” │ │ AI “我将创建auth.py...” │ 会话开始元数据开始记录 │ │ ▼ (修改文件) │ │ │ ▼ (执行 git commit) ▼ [你的代码提交: “feat: add auth”] ───────► [检查点#1: 保存此刻的会话快照] │ │ │─── 继续会话 ──────────────────────────┤ │ 你 “加个JWT验证” │ │ AI “好的修改auth.py...” │ │ │ ▼ (修改文件) │ │ │ ▼ (执行 git commit) ▼ [你的代码提交: “feat: add JWT”] ───────► [检查点#2: 保存新的快照]左侧分支是你的常规Git分支只有你或AI工具发起的纯净代码提交。Entire绝不污染这里。右侧分支是Entire自动创建和维护的entire/checkpoints/v1分支。这个分支存储了所有会话的元数据JSON格式并通过Commit SHA与左侧分支的提交一一对应。当你推送代码到远程仓库时Entire可以配置为自动将这个元数据分支也推送到一个指定的远程仓库甚至是另一个私有仓库从而实现代码与上下文的同步备份。2.3 支持的智能体与钩子机制Entire本身不直接与AI模型交互而是通过“钩子”监听AI工具的活动。目前它支持多种“智能体”智能体钩子安装位置工作原理Claude Code.claude/settings.json修改Claude Code的配置文件注入自定义脚本在Claude Code执行命令、修改文件时触发事件。Cursor.cursor/hooks.json利用Cursor IDE的钩子系统监听编辑器内的AI活动。GitHub Copilot CLI.github/hooks/entire.json利用Copilot CLI的钩子接口。Gemini CLI.gemini/settings.json类似Claude Code通过配置文件注入。OpenCode.opencode/plugins/entire.ts作为OpenCode的插件运行。钩子机制详解以Claude Code为例当你运行entire enable --agent claude-code时CLI会做以下几件事检查~/.config/claude或项目内的.claude/settings.json文件。在该JSON配置中添加或更新一个hooks字段其中包含onCommandStart、onCommandEnd、onFileChanged等事件的监听器。这些监听器指向Entire CLI内置的处理器。当Claude Code启动一个命令、结束命令或文件被修改时就会调用这些处理器将事件数据发送给Entire的后台进程进行记录。这种方式的优点是非侵入性。AI工具本身无需做任何修改Entire只是作为一个“观察者”附加上去。你可以同时为多个AI工具启用钩子Entire会智能地识别当前活跃的是哪一个并记录相应数据。3. 从零开始安装与基础工作流实操理论讲完我们动手实操。我将以macOS系统、使用Claude Code为主要AI工具的场景为例演示最完整的工作流。3.1 环境准备与安装首先确保你的系统已安装Git并且已经安装并认证了你打算使用的AI工具例如已登录Claude Code。Entire提供了多种安装方式推荐使用Homebrew管理起来最方便。# 1. 添加Entire的Homebrew Tap并安装 brew tap entireio/tap brew install entireio/tap/entire # 安装后验证是否成功 entire --version对于Windows用户可以使用Scoopscoop bucket add entire https://github.com/entireio/scoop-bucket.git scoop install entire/cli对于Go开发者也可以直接go installgo install github.com/entireio/cli/cmd/entirelatest # 确保$GOPATH/bin或$HOME/go/bin在你的PATH环境变量中3.2 在项目中启用与配置进入你的Git项目仓库开始初始化Entire。cd ~/projects/my-ai-powered-app entire enable首次运行entire enable它会启动一个交互式界面列出所有检测到的、已安装的AI智能体让你选择为哪些启用钩子。使用上下键选择空格键勾选回车确认。这里我勾选claude-code。这个过程背后发生了在你的项目根目录创建.entire/文件夹。创建.entire/settings.json项目级配置建议提交到Git。根据你的选择修改对应AI工具的配置文件如.claude/settings.json安装钩子。在本地初始化entire/checkpoints/v1分支如果不存在。可能会提示你进行设备认证entire login用于可选的远程服务如后续的AI总结功能。非交互式启用如果你想在脚本中自动化可以使用--agent标志。entire enable --agent claude-code --agent cursor重要配置分离元数据仓库如果你的代码仓库是公开的但不想让AI会话记录也公开可以在启用时指定一个单独的私有仓库来存放检查点数据。entire enable --checkpoint-remote github:your-private-org/checkpoints-repo这会在.entire/settings.json中配置strategy_options.checkpoint_remote。之后你的代码推送到origin而会话元数据则推送到这个指定的私有仓库。3.3 典型工作流实战现在模拟一个真实的开发场景。步骤1开始日常开发假设我正在开发一个功能为我的Web应用添加一个API速率限制中间件。我像往常一样在终端里用Claude Code开始工作。# 正常使用Claude Code claude /edit middleware/rate_limiter.py # AI开始生成代码...此时Entire已经在后台启动了一个新的会话并开始记录所有交互。步骤2进行多次修改与提交AI生成了初始代码我检查后觉得需要调整桶算法的参数。我继续与Claude对话修改代码。经过几轮迭代我觉得当前版本不错准备提交。git add middleware/rate_limiter.py git commit -m feat: add initial rate limiter middleware就在这个git commit完成的瞬间Entire自动创建了本会话的第一个检查点Checkpoint将到目前为止的所有对话、文件变更状态作为一个快照保存到entire/checkpoints/v1分支并与这个提交的SHA关联。我继续工作让AI添加基于Redis的分布式支持。代码修改完毕后再次提交。git add middleware/rate_limiter.py git commit -m feat: make rate limiter distributed with Redis第二个检查点随之创建。现在这个会话里有了两个检查点。步骤3查看状态与历史随时可以查看当前会话的状态entire status输出会显示当前会话ID、已创建的检查点数量、关联的提交以及启用了哪些智能体。步骤4使用“时光机”回退糟糕在让AI添加“滑动窗口”逻辑时它理解错了我的意图把代码改得一团糟。我想回到添加Redis支持之后、那个清晰正确的状态。entire rewindCLI会展示当前会话中所有可用的检查点列表通常按时间倒序排列每个检查点会显示其ID、关联的Git提交信息摘要和创建时间。我选择第二个检查点即“feat: make rate limiter distributed with Redis”对应的那个。Entire会将我工作目录中的文件恢复到该检查点时的状态。注意它不会修改我的Git提交历史只是把工作区的文件内容回退了。现在我的代码回到了那个正确的节点并且Entire的会话记录也回到了那个时间点。我可以基于这个状态重新给AI更清晰的指令继续开发。步骤5恢复之前的会话第二天我回到这个项目想继续昨天的工作。我不需要去回忆昨天最后用的是什么提示词。# 切换到昨天工作的分支如果不在的话 git checkout feature/rate-limiter # 恢复该分支上最新的会话 entire resumeentire resume会做三件事确保你位于正确的分支。从entire/checkpoints/v1分支拉取该分支上最新的会话元数据。在终端打印出类似于“你可以运行claude命令继续上次的对话”的提示实际上由于AI工具的状态是临时的它更多是恢复文件状态和上下文记录你需要手动重新启动AI工具但Entire保留了所有历史上下文供你查询。步骤6推送与同步开发完成准备推送。git push origin feature/rate-limiter如果配置了push_sessions: true默认Entire会自动将entire/checkpoints/v1分支的更新也推送到配置的远程仓库。你的代码和它的“创作记忆”就一起同步到了远程。3.4 配置详解项目设置与本地覆盖Entire的配置清晰且灵活采用两级覆盖机制。项目级配置(.entire/settings.json): 通常提交到版本库供团队共享。{ enabled: true, strategy_options: { push_sessions: true, checkpoint_remote: { provider: github, repo: mycompany/private-checkpoints }, summarize: { enabled: true } } }本地覆盖配置(.entire/settings.local.json): 被.gitignore忽略用于个人偏好。{ log_level: debug, telemetry: false }entire status命令会显示最终生效的配置。log_level设为debug在排查问题时非常有用。自动总结功能当summarize.enabled为true且安装了Claude CLI时每次创建检查点Entire会在后台调用Claude AI为这段会话生成一个简短总结包括意图、成果、学习点和未决事项。这个总结会保存在元数据中方便日后快速浏览。4. 高级用法、问题排查与实战心得掌握了基础工作流后我们来看一些提升效率的高级技巧和常见问题的解决方法。4.1 高级特性与应用场景1. 并行会话与Git Worktree支持如果你在使用Git的Worktree功能在多个工作树中同时进行不同的任务Entire能完美应对。每个工作树都有独立的会话跟踪。你可以在worktree-a里用AI重构用户模块同时在worktree-b里用AI调试支付接口两者互不干扰。entire status只会显示当前工作树下的活动会话。2. 解释任意提交不只是自己刚写的代码对于历史提交甚至是同事的提交只要当时使用了Entire记录你都可以追溯上下文。# 解释某个特定的提交 entire explain abc123def # 解释当前分支最新的提交 entire explain HEAD这个命令会从entire/checkpoints/v1分支中找到关联的元数据并以友好的格式展示当时的会话摘要、关键提示词和文件变更是代码审查和知识传承的神器。3. 清理与管理长时间使用后可能会有一些孤立的临时数据。entire clean清理当前提交关联的会话数据。entire clean --all --force强制清理整个仓库中所有孤立的Entire数据。在遇到状态冲突或奇怪错误时这是“重启大法”。entire sessions stop手动标记一个或多个活跃会话为已结束。适用于AI工具异常退出导致Entire认为会话仍挂起的情况。4. 禁用与卸载如果不想在某个项目中使用Entire了运行entire disable。它会移除安装的所有钩子但不会删除已经存储在entire/checkpoints/v1分支上的历史数据。你的代码提交历史丝毫无损。4.2 常见问题与排查指南即使设计得再完善在实际复杂环境中也可能遇到问题。下面是我遇到或预见的一些典型情况及其解决思路。问题现象可能原因解决方案运行entire命令提示Not a git repository当前目录不是Git仓库根目录。cd到你的Git项目目录下再执行命令。entire status显示Entire is disabled未在当前仓库启用或钩子被意外移除。运行entire enable重新启用。entire rewind提示No rewind points found当前会话中还没有创建任何检查点即没有执行过git commit。正常使用AI工具工作并进行一次提交。执行git push后Entire元数据推送失败报SSH认证错误这是go-git库的一个已知问题SSH认证信息可能未正确加载。将GitHub的host key添加到known_hosts文件ssh-keyscan -t rsa,ecdsa github.com ~/.ssh/known_hostsAI工具如Claude Code行为异常怀疑钩子冲突其他工具或自定义脚本修改了同一个钩子配置文件。1. 检查对应的配置文件如.claude/settings.json。2. 临时重命名该文件测试AI工具是否恢复正常。3. 运行entire disable然后entire enable --force重新安装纯净的钩子。entire/checkpoints/v1分支出现合并冲突罕见情况可能因多人同时在同一个仓库启用Entire并推送元数据导致。1. 备份你的工作。2. 运行entire clean --all --force清理本地状态。3. 删除本地该分支git branch -D entire/checkpoints/v1。4. 重新启用Entireentire enable它会尝试从远程拉取并重建。调试模式当遇到任何诡异问题时开启调试日志是第一步。# 通过环境变量 ENTIRE_LOG_LEVELdebug entire status # 或通过本地配置 echo {log_level: debug} .entire/settings.local.json entire status调试输出会详细显示Entire正在做什么、读取了哪些配置、与AI工具的钩子如何通信对于定位问题至关重要。4.3 安全、隐私与最佳实践建议安全与隐私第一Entire将你的所有会话数据包括完整的对话记录以明文JSON形式存储在Git仓库中。这意味着如果仓库是公开的这些数据也是公开的。务必注意敏感信息泄露风险虽然Entire内置了简单的密钥检测和打码功能但它不是万无一失的。绝对不要在提示词中直接输入密码、API密钥、私钥等敏感信息。最佳实践对于公开项目强烈建议使用--checkpoint-remote参数将元数据分支推送到一个单独的私有仓库。我的实战心得与建议提交即存档养成好习惯Entire的检查点与git commit绑定。这鼓励了更小、更频繁的提交。每次完成一个逻辑完整的微任务就提交一次相当于为你的AI协作过程创建了一个清晰的“章节标记”回退和追溯都会非常方便。善用entire explain进行代码审查在团队评审代码时除了看Diff让提交者提供entire explain commit-sha的输出。这能极大提升评审效率评审者能直接理解代码变更的“意图”和“思考过程”而不是凭空猜测。“时光机”用于探索而非撤销entire rewind的主要价值在于安全地探索不同方案。你可以让AI尝试一个激进的重构如果不满意立刻回退到之前稳定的检查点成本为零。这彻底改变了我们与AI协作的心理负担从“怕它改坏”变成了“尽管试试看”。本地配置是利器将.entire/settings.local.json中的log_level默认设为info在需要时改为debug。关闭telemetry匿名统计如果你在意数据。这些本地设置不会影响你的队友。注意智能体冲突如果你同时启用了Claude Code和Cursor的钩子确保你了解它们是如何共存的。通常哪个AI工具触发了文件修改就由哪个工具的钩子报告事件。但如果你发现记录有遗漏可以尝试只启用你最常用的那个工具。Entire CLI代表了一种新的范式它承认AI已成为我们编程工作流中不可或缺的“协作者”并致力于为这种协作关系提供可观察性、可追溯性和可逆性。它没有试图取代Git或任何AI工具而是在它们之间架起了一座坚固的桥梁将原本易逝的“思考过程”固化为可管理的知识资产。对于任何严肃地在项目中使用AI编程的开发者或团队来说花一点时间配置Entire很可能会在未来为你节省大量的调试、理解和沟通成本。