Torpor

# 休眠 > AI 编程会话的本地时间旅行。 AI 编程代理移动速度很快，直到它们慢慢创造出一个破碎的未来。 休眠记录了验证的检查点、分支历史、会话证据和在 `.torpor/` 下的安全项目状态，这样您就可以返回到一个受信任的检查点，保留失败的未来作为证据，并在新的分支上安全地继续。 Git 是源代码控制。 休眠是 AI 编程工作流的恢复。 ## 为什么休眠存在 想象一下，您正在使用 Codex、Claude Code、OpenCode 或其他本地代理等 AI 编程 CLI 构建一个长期项目。起初，一切感觉都很顺利。您要求代理添加一个功能、修复一个错误、重命名文件、改善结构、更新测试并清理旧代码。每个任务在发生时看起来都很合理。 经过多次会话，项目开始出现问题。错误并不在一个明显的文件中。它可能来自三天前重构的代码、昨天更改的辅助函数、删除的配置文件和当时看起来不错的快速修复。现在，代理试图修复一个已经有多个层次过去决策构建的系统。 当您在正确的时间进行了干净的提交时，Git 会有所帮助。但是，AI 工作通常会经历混乱的中间状态：提示、工具调用、部分编辑、失败的修复、删除的文件以及后来看起来有问题的更改。当项目出现问题时，要求代理“撤销错误的部分”可能存在风险，因为代理可能不知道问题从哪里开始。 休眠就是为这一刻而存在的。 与其删除失败的未来，休眠将其保留为证据。 您可以返回，继续安全，并仅显示损坏的未来中帮助代理理解需要避免的部分。 ## 休眠的作用 - 为 AI 编程会话保存分支感知的检查点。 - 创建由正常检查点存储支持的受信任的零基线。 - 将损坏的未来保留为证据。 - 安全地恢复受信任的检查点。 - 在旅行后创建继续分支。 - 将 `.torpor/` 保持在时间之上。 - 通过始终开启的智能观察连接检查点、文件、分支、旅行和风险证据。 - 验证清单、哈希、块、包、存档和分支元数据。 - 支持 Codex 和 Claude 包装流程。 - 为 AI 编程客户端公开 MCP 工具。 - 捕获本地会话证据以用于包装的 CLI 会话。 - 以受控的级别显示失败的未来证据。 在以下情况下使用休眠： - AI 代理正在对多个会话进行实际编辑。 - 项目足够大，以至于“让代理撤销它”存在风险。 - 您想在返回受信任的检查点之前保留损坏的未来。 - 您需要分支感知的恢复，而不删除失败的证据。 - 您想要具有哈希、清单、验证和恢复检查的本地、可检查的检查点。 您可能不需要休眠来进行一次性的单文件实验。对于严肃的 AI 辅助项目，它属于 Git 旁边，因为它保护了不同层次的工作。 ## 60 秒演示 在 [docs/demo.md](docs/demo.md) 中查看复制粘贴的演练。 简短版本： ```bash cargo install --path . --locked mkdir torpor-demo cd torpor-demo printf 'print("安全版本")\n' > app.py torpor setup --mode hybrid torpor doctor torpor zero create torpor save "安全检查点" printf 'raise RuntimeError("损坏的未来")\n' > app.py torpor save "损坏的未来" torpor travel --branch main --checkpoint main-0001 cat app.py torpor verify ``` 在旅行后，休眠将失败的未来保存在 `.torpor/` 中，并从恢复的检查点继续在一个继续分支上。 ## 快速入门 ```bash cargo install --path . --locked torpor setup --mode hybrid torpor doctor torpor zero create torpor save "已知的良好检查点" torpor run codex # 或 torpor run claude torpor checkpoints torpor branches torpor travel torpor reveal torpor verify ``` ## 文档 - [快速入门](docs/quickstart.md) - [示例](docs/examples.md) - [Codex 设置](docs/codex.md) - [Claude Code 设置](docs/claude-code.md) - [MCP](docs/mcp.md) - [存储和完整性](docs/storage-integrity.md) - [零基线](docs/zero-baseline.md) - [旅行模型](docs/travel-model.md) - [恢复显示](docs/reveal-model.md) - [威胁模型](docs/threat-model.md) - [FAQ](docs/faq.md) - [为什么休眠存在](docs/launch-story.md) - [愿景](VISION.md) - [架构](ARCHITECTURE.md) - [路线图](ROADMAP.md) - [变更日志](CHANGELOG.md) - [贡献](CONTRIBUTING.md) - [行为准则](CODE_OF_CONDUCT.md) ## 核心工作流 ```text 1. 在项目中启用休眠。 2. 保存受信任的检查点。 3. 继续使用 AI 编程代理。 4. 如果项目出现问题，则返回。 5. 休眠将保存损坏的状态作为逃脱检查点。 6. 休眠将恢复受信任的检查点。 7. 休眠将创建一个新的继续分支。 8. 失败的未来仍然可用作证据。 ``` ## 示例：逃离破碎的未来 ```bash torpor on torpor save "身份验证系统稳定" torpor run codex # 稍后，在项目出现问题后 torpor travel # 选择： # 分支：main # 检查点：main-0001 torpor reveal --level 2 torpor verify ``` 休眠恢复了较旧的检查点，创建了一个新分支，并为代理提供了一个受控的总结，说明在逃脱的未来中发生了什么。 ## 休眠与 Git 的区别 Git 是源代码控制。 休眠是 AI 会话恢复。 | 需要 | Git | 休眠 | | --- | --- | --- | | 跟踪源代码更改 | 是 | 是，作为恢复证据 | | 恢复文件 | 是 | 是，具有检查点验证 | | 保存失败的 AI 未来 | 手动 | 是 | | 在回滚后创建继续分支 | 手动 | 是 | | 存储 AI 会话证据 | 否 | 是 | | 向代理显示失败的未来上下文 | 否 | 是 | | 将恢复历史视为时间之上 | 否 | 是 | 休眠不会取代 Git。两者结合使用。 ## 时间之上 `.torpor/` 在时间之上。 这意味着休眠永远不会快照、恢复、倒回、删除或覆盖 `.torpor/` 作为项目状态。 项目文件可以通过时间移动。 `.torpor/` 记得每一个时间线。 ## 检查点和存档 休眠默认优先级为 `5`，因为恢复通常比节省一点磁盘空间更重要。 在当前的 V2 存储中，优先级为 `5` 的正常检查点使用经过验证的压缩块包作为恢复路径。默认情况下，它们不会将每个保存都复制到完整项目存档中。 零基线是项目的第一个受信任的源现实： ```bash torpor zero create torpor zero status ``` 零由一个正常的经过验证的检查点支持。`.torpor/zero/` 存储元数据、文件状态 Merkle 摘要和人类可读的摘要，而确切的字节仍然存在于休眠的对象存储和检查点清单中。 当您需要一个可移植的存档时，请使用： ```bash torpor pin-archive --branch main --checkpoint main-0001 torpor export --branch main --checkpoint main-0001 --archive portable-main-0001.tar.zst ``` 固定和导出的存档使用确定性的 tar 数据，zstd 级别为 `22`，帧校验和，远距离匹配。外部检查可能需要： ```bash zstd --long=31 -d -c .torpor/timelines/<branch>/backups/<checkpoint>/workspace.tar.zst | tar -tf - ``` ## 恢复显示 在旅行后，休眠不会将整个失败的未来转储到代理中。 相反，它在不同级别显示证据： ```text 1 = 最小摘要 2 = 摘要加上关键分支/检查点/路径事实 3 = 更深入的任务和更改摘要 4 = 选定的文件证据 5 = 最大详细证据包 ``` 这控制了令牌的使用，同时保留了对更深入证据的访问。 ## 基本命令 ```bash torpor setup torpor doctor torpor on torpor off torpor status torpor zero create torpor zero status torpor save "安全检查点" torpor checkpoints torpor branches torpor verify torpor reveal torpor analyze torpor file-history src/app.py torpor travel torpor travel --branch main --checkpoint main-0001 torpor pin-archive --branch main --checkpoint main-0001 torpor export --branch main --checkpoint main-0001 --archive portable-main-0001.tar.zst torpor run codex torpor run claude torpor mcp ``` ## Codex 设置 构建休眠并将 stdio MCP 服务器注册到 Codex： ```bash cargo install --path . --locked codex mcp add torpor -- torpor mcp codex mcp list ``` 对于 Codex `$torpor` 命令界面，请安装捆绑的技能： ```bash mkdir -p ~/.codex/skills cp -R plugins/torpor/skills/torpor ~/.codex/skills/torpor ``` 在 Codex 内部： ```text $torpor setup $torpor status $torpor done implemented the requested change $torpor checkpoints $torpor verify ``` ## Claude Code 设置 构建休眠并验证捆绑的 Claude Code 插件： ```bash cargo install --path . --locked claude plugin validate plugins/torpor ``` 从此检查点加载插件时： ```bash claude --plugin-dir plugins/torpor ``` 在 Claude Code 内部： ```text /torpor:torpor setup /torpor:torpor status /torpor:torpor done implemented the requested change /torpor:torpor checkpoints /torpor:torpor verify ``` MCP-only 设置： ```bash claude mcp add torpor -- torpor mcp ``` MCP 服务器是客户端中立的。任何兼容的本地代理客户端都可以通过其 MCP 配置指向此二进制文件来启动相同的 `torpor mcp` 命令。 通过 `torpor run codex` 或 `torpor run claude` 启动的包装会话通过 PTY 运行，并记录为 JSON Lines 转录本，位于活动分支的 `sessions/` 目录中。这不会取代 CLI 的内置恢复或会话历史，但它为休眠提供了自己的本地证据轨迹，以了解包装会话期间发生了什么。 ## 存储和完整性内部 休眠使用 `.torpor/` 下的经过验证的本地存储。 当前存储包括： - 检查点清单 - 内容寻址块 - 压缩块包 - 块定位器索引 - 可选的可移植工作区存档 - 内容哈希 - 包哈希 - 存档哈希 - Merkle 根 - 分支血统元数据 - 恢复前的验证 - `torpor verify` 休眠检查： - 图元数据 - 分支血统 - 清单 - 块 - 包 - 固定的工作区存档 - 恢复关键路径 - `.torpor/` 排除规则 ## 安全模型 休眠设计为关闭失败。 如果验证失败，休眠应该拒绝信任检查点，而不是静默恢复不安全的历史。 同时使用 Git 和正常的备份。休眠是一个恢复层，而不是其他所有安全实践的替代品。 ## 当前状态 休眠还处于早期阶段。 已实现的组件包括： - `torpor on`、`torpor off`、`torpor status` 和 `torpor doctor` - 基于分支的 `.torpor/` 存储 - 优先级为 `1-5` 的经过验证的检查点 - 以 `torpor zero create/status` 为后盾的检查点零基线 - 内容寻址块 - 压缩块包 - 通过 `pin-archive` 和 `export` 实现的可选可移植工作区存档 - 清单、哈希和 Merkle 根 - 分支和检查点列表 - `torpor verify` - `torpor travel` - 恢复前的逃脱检查点 - 旅行后的继续分支 - 恢复显示输出 - `torpor run codex` - `torpor run claude` - PTY 转录捕获 - stdio MCP 服务器模式 - GitHub Actions CI 仍然处于早期阶段： - UX润色 - 更多现实世界的测试 - 更多示例 - 更多CLI适配器 - 更强的文档 - 安装包 - 更广泛的平台验证 ## 项目价值观 - 本地优先 - 关闭失败 - 零作为元数据优于已验证存储 - 分支感知 - 诚实的范围 - 代理友好 - Git 兼容 - 恢复优先于便利 - 证据优先于猜测 ## 开发检查 ```bash cargo test cargo fmt --check cargo clippy --all-targets --all-features -- -D warnings ``` ## 致谢 由 Kylne700 创建。 休眠由 Kylne700 构思、指导和维护，OpenAI Codex 提供了 AI 辅助开发支持。 参见 [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md)。 ## 安全 休眠读取、快照、验证和恢复项目文件。请负责任地报告安全敏感问题。 参见 [SECURITY.md](SECURITY.md)。 ## 贡献 欢迎改进恢复安全性、检查点完整性、文档准确性和安装清晰度的贡献。 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 Apache-2.0。参见 [LICENSE](LICENSE)。