Zerostel

快速开始

npx zerostel install

想先看看效果？npx zerostel demo 会创建一个临时项目，模拟一次 Agent 操作：删除一个文件夹并导致测试失败，然后让你撤销操作。无需 Agent，也不会触及你的任何项目。

然后像平常一样使用你的 Agent。遇到问题时：

zerostel log          # what happened, step by step
zerostel checks       # did the tests pass on the code as it is now?
zerostel undo         # put the files back to before the agent's last turn
zerostel rewind 0     # or all the way back to point zero, where the session started
zerostel handoff      # what the next agent or person needs to carry on
zerostel ui           # the same, clickable, in a local web page

功能

• 记录。 在每个会话的单条时间线上记录每个提示词、工具调用、命令、文件变更、耗时和 token 数量：在终端中运行 zerostel log，或在本地网页中查看 zerostel ui。
• 回退。 在每次可能更改文件的工具调用前后创建快照，包括 shell 命令。撤销一次操作，返回任意步骤，或一直回到起点；每次回退操作本身也可以撤销。
• 防护。 在工具调用运行之前，用你自己的规则阻止它，或要求 Agent 先征求你的同意。所有 Agent 使用相同的规则。
• 检查并交接。 Agent 运行的每项测试、类型检查和构建都会关联到其运行时对应的代码，因此 zerostel checks 能区分基于当前代码通过的检查与基于之后已变更代码通过的检查。zerostel handoff 会向下一位 Agent 或人员提供你的要求、当前进展和已尝试的操作。
• 验证并分享。 使用哈希链记录日志，显示日志是否被编辑；还可生成带隐私模式的单页报告供分享。
• 本地运行。 不会上传任何内容，只有你能读取 ~/.zerostel，并且绝不会触碰你的 .git。

这是为 AI Agent 实施的零信任：假设它们可能出错，查看它们的所有操作，并保留回退途径（实际应用）。它不是沙盒：网络请求、部署和数据库写入都无法撤销。请参阅限制。

为什么

Agent 会编辑几十个文件、运行 rm、git checkout .、迁移脚本和构建脚本。出了问题时，你只能追问它做了什么，以及如何恢复。

有些 Agent 自带检查点，但彼此差异很大。Claude Code 的回溯会跳过通过 Bash 做出的更改。Copilot CLI 会跟踪 shell 命令。Cursor 和 Codex 各有自己的模式。如果你使用多个 Agent，那么对于“改了什么，能不能恢复”这个问题，每个 Agent 给出的答案都不一样。

Zerostel 以相同方式记录所有受支持的 Agent：在每次可能更改文件的工具调用前后为项目拍摄快照，记录提示词、命令、文件、时间和 Token 的时间线，并生成可交给他人的报告。它绝不会触碰你的 .git。

	Agent 自带的检查点	提交 / git stash	Zerostel
shell 命令造成的更改	因 Agent 而异	仅限你提交或暂存的内容	✅ 项目内的内容，以及你列出的文件
恢复到特定步骤	通常按提示词记录	按提交或暂存记录	✅ 按工具调用记录
命令、文件、Token、时间的时间线	部分支持	❌	✅
显示之后是否编辑过的日志	❌	✅（提交哈希）	✅
自定义规则：在工具运行前拦截或询问	因 Agent 而异	❌	✅ 所有 Agent 使用相同规则
不同 Agent 之间行为一致	❌ 各自一套	✅	✅
写入你的 .git	有些会	✅	❌ 绝不会
可分享的会话报告	❌	❌	✅

详情和来源：docs/comparison.md。背后的故事和相关事故：编码 Agent 的检查点无法恢复什么。

与其他工具的比较

Agent 持续添加自带的检查点，也有不少不错的扩展工具：Turnback、Turnal、bashback、logbook、codex-rewind。Zerostel 还提供：

• 回溯时不会丢失工作。 删除或覆盖内容前都会精确备份；每个文件在更改前都会重新检查；--keep-others 会保留其他 Agent 或你之后做出的更改；每次回溯都可以撤销，即使回溯中途停止也不例外。
• 不止项目文件夹。 还能监控 ~/.zshrc 等文件、Windows 用户环境变量和全局安装（列出相关内容及其撤销命令）。
• 与代码关联的证据。 测试和构建结果会与实际运行时对应的代码一并记录，因此，如果代码之后发生了变化，原本通过的结果就会标记为过期；移交记录也可以对照文件夹进行核验。
• 所有 Agent 共用一套规则。 工具运行前可拦截或询问的护栏，以及显示是否经过编辑的日志。
• 保留原样使用 Agent。 接入官方 Agent，不使用分支版本或包装器；零运行时依赖，不会向任何地方发送数据。

也可能有其他工具更适合你：Agent 自带的 /rewind 和 codex-rewind 会连同文件一起恢复对话，Turnal 则可以二分查找导致测试失败的轮次。各工具并列比较及来源。

支持的 Agent 和系统

Agent	方式	状态
Claude Code	hooks	✅ 已在真实会话中测试
Codex	hooks（通过 /hooks 批准一次）	✅ 已在真实会话中测试
Cursor	hooks	✅ 已在真实会话中测试 CLI；CLI 不会发送提示词事件，因此在 CLI 中只能逐项撤销更改。在 Windows 上，请从 PowerShell 启动：从 Git Bash 启动时，其 hooks 不会运行
Gemini CLI	hooks（仅限受信任的文件夹）	✅ 已完成端到端测试¹；适用于 Code Assist Standard/Enterprise 和付费 API 密钥，因为个人账户已于 2026 年 6 月迁移至 Antigravity
Antigravity（CLI、桌面端、IDE）	hooks	✅ 已完成端到端测试¹；它不会传递提示词文本，因此回合会显示为“新回合”
Copilot CLI	hooks（~/.copilot/hooks）	✅ 已在真实会话中测试
opencode	插件	✅ 已在真实会话中测试
DeepSeek Harness	插件	🧪 实验性（dsh 本身仍处于开发者预览阶段）；已完成端到端测试¹
其他任何工具（Aider、脚本……）	zerostel run -- <command> 监视文件	✅ 粒度较粗：不记录工具调用、令牌或护栏

¹ 在 Windows 上使用真实 Agent，并将其模型替换为脚本模型：一次提示词、一项文件写入、一条命令、一次被规则拦截的调用、回合结束以及一次撤销。

只有在你指定实验性 Agent 时才会安装：zerostel install --agent deepseek。欢迎提供真实会话的反馈。

不同 Agent 向其 hooks 报告的信息各不相同（提示词、失败的命令、令牌）；每个 Agent 会向 Zerostel 提供哪些信息。

Zerostel 不关心 Agent 背后使用的是哪个模型：Claude、GPT、Gemini、DeepSeek 或本地模型都会以相同方式记录。

支持 Windows、macOS 和 Linux（也包括 WSL）。CI 会在每次提交后，使用 Node 20、22、24 和 26 在这三个平台上运行测试。

安装

npx zerostel install          # one-off, nothing installed globally
npm install -g zerostel       # or keep the `zerostel` command around

你需要 git 和 Node 20 或更高版本。没有 Node？每个版本都提供一个内置 Node 的独立可执行文件，支持 Windows、macOS 和 Linux：从 Releases 下载并运行 zerostel install。Claude Code、Codex、Antigravity 和 Gemini CLI 的插件、Agent 技能以及下载校验方法：docs/install.md。

文档

命令	所有命令和选项
护栏	规则的工作方式及经过测试的配方
配置	~/.zerostel/config.json
CI	GitHub Action
MCP 服务	让 Agent 读取时间线，并在你提出要求时回退
工作原理	hooks、影子仓库、安全回退和审计链
零信任	每项原则，以及 Zerostel 如何实现它
安全模型	它能保护什么，不能保护什么
各 Agent 自带的检查点	各 Agent 的撤销功能会恢复哪些内容，并附有来源
其他工具	Turnback、Turnal、bashback 等工具的横向比较
常见问题	速度、磁盘占用、git、jj、沙盒、令牌

遇到问题？运行 zerostel doctor：它会检查 Node、git、各 Agent 的 hooks、你的配置和护栏，且其输出可以安全地粘贴到 issue 中。

限制

• 只能恢复已记录的状态。删除后才开始录制，就无法恢复该文件。
• 在一条 shell 命令中没有中间状态：同一条命令创建并删除的文件永远不会被检测到。zerostel run 会在文件稳定后创建快照，因此也可能错过短暂存在的文件。
• 在项目之外，只有列在 watch 下且位于主文件夹中的文件才会创建快照。在 Windows 上，用户环境变量（HKCU\Environment）会在更改它们的命令前后读取，并在回退时恢复；这些变量的值只保存在你机器上的会话日志中，不会出现在报告里。全局软件包只会列出，并附上撤销更改的命令。回退不会动目标时间点上不存在的受监控文件。项目之外的其他所有内容均不受覆盖；时间线仍会显示修改它的命令。
• 以下内容不会创建快照，并会在存在时由 zerostel log 列出：被忽略的文件夹（node_modules、dist/、.gitignore 中的任何内容）、嵌套的 git 仓库和子模块、链接文件夹（符号链接、目录联接）以及超过 maxFileMB 的新文件。
• 在主文件夹、驱动器根目录或主文件夹上层文件夹中启动的 Agent 会生成时间线，但不会创建快照。
• 回退会还原整个文件：使用 --keep-others 时，会保留其他人修改的文件，但不会合并两个 Agent 对同一文件所做的编辑。
• Agent 运行的测试或构建，只有在 Agent 报告结果时才算通过；zerostel check -- <command> 始终能获知结果。
• 在不区分大小写的文件系统上（Windows 和默认设置下的 macOS），仅更改大小写的重命名（例如 readme.md → README.md）不会被视为更改。
• 在 WSL 下，Windows 驱动器上的项目（/mnt/c/...）创建快照的速度很慢。请将它们放在 Linux 文件系统中。
• 如果有不持有你的 audit.key 的对象编辑了日志，审计链会显示这一点。使用你自己账户的人可以读取该密钥并完全重写日志；请在拒绝规则中保留 ~/.zerostel/**，以阻止 Agent 访问。
• 防护规则会匹配工具调用中指定的名称。未指定文件名但访问该文件的脚本或命令可以绕过规则。

路线图

• 已完成： 录制和回退七个 Agent、零点、Web UI、可分享报告、可验证日志、防护规则、MCP 服务、项目外受监控文件、与运行代码关联的检查及失败测试记录、交接、保留其他会话工作的回退，以及通过基于属性的测试检查防护规则。
• 下一步： 任何人无需你的密钥即可验证的签名报告；通过 Zerostel 网关录制对其他 MCP 服务的调用；回退到指定测试最近一次通过的步骤；在真实会话中验证实验性 Agent。
• 欢迎协助： macOS 和 Linux 测试报告，以及任何标记为欢迎协助的事项。

参与贡献

欢迎在讨论区提出问题和想法。要支持新的 Agent，只需在 src/agents/adapters.ts 中添加一个适配器。请参阅 CONTRIBUTING.md 和 docs/architecture.md。

npm ci && npm test && npm run smoke

许可证

Apache-2.0