rollback

将一个工具恢复到其已记录的安装之前的状态。

概要Copy Anchor Link

apothem rollback --harness NAME|all [--install-id ULID | --last] [--yes]
                 [--project PATH]
                 [--quiet|-q] [--verbose|-v]
                 [--format plain|json] [--json] [--no-color]

rollback 会将每个所选工具恢复到已记录的那次安装过程之前所处的状态——默认是最近一次，或由 --install-id 指定的那一次。它按照该次安装的账本记录，从最新的更改开始依次处理：

• 从该次安装所捕获的备份中，在记录的路径上恢复该次安装覆盖的每个文件和目录（被该次安装替换的目录会被精确恢复，不包含该次安装向其中添加的文件）；
• 移除该次安装创建的每个文件和目录，并放回该次安装清除掉的任何旧有布局路径；
• 移除该次安装创建的共享数据存储（memory、contexts、learning），除非另一个已安装的工具仍在使用它们；
• 在该次安装创建的目录变空之后将其移除。

你主目录中一个其他安装也在使用的文件或文件夹（技能文件夹，或 ~/.config/apothem/）会像共享数据存储一样处理：只要另一个安装仍列出它，回滚就会保留它，并且只会为使用它的最后一个安装恢复或移除它。对于该次安装发现已经存在的文件夹（在第一个工具之后安装的第二个工具），如果它是由一个此后已放弃它的安装所创建的，它就会随使用它的最后一个安装一并移除，因此回滚每个工具后不会留下任何东西。当一个可能使用该文件夹的安装的记录无法读取时，回滚会在更改任何内容之前以错误停止，并且不写入 rollback 记录；修复该记录后再次运行。

回滚操作移除或替换的所有内容，都会先复制到 Apothem 备份根目录（~/.apothem/backups/）中，因此回滚本身也可以手动撤销。随后，回滚会向工具账本追加一条 rollback 记录。回滚较早的安装时，只会恢复或移除该较早安装所记录的目标，并会将同一根目录下此后的每次安装从账本的活动安装中剔除。之后的安装在这些目标之外添加的文件会保留在原位。

账本为每个安装根目录保留最新的 10 条安装记录（以及它们所引用的备份）；更早的安装将无法再按 id 回滚，并会报告 rollback.no_record。apothem backups prune 可按需降低这一上限，并且绝不会移除最近一次安装恢复时所依据的备份。

在添加此行为之前的 Apothem 版本所写入的记录不会列出该次安装创建了哪些文件；回滚这样的记录只会恢复被覆盖的文件。

除非提供了 --yes，否则会按工具逐一提示确认。当无法进行提示时——--format json（提示文本会破坏单一的 JSON 文档）或非交互式 shell（无 TTY）——除非提供了 --yes，否则该命令会预先以一个结构化的 rollback.confirmation_required 错误（退出码 1）拒绝执行。--install-id 和 --last 用于选择安装过程，二者互斥。

--harness all 回滚是有意做到穷尽的：它覆盖每一个已注册的工具，包括配置档案的 exclude_harnesses 在安装时跳过的工具——恢复安装前的状态是一项清理操作，因此它会触及先前范围更广的安装可能留下的记录。没有已记录安装的工具，会在 results 中以一行 "outcome": "error" 的形式失败（参见 JSON 输出），运行会继续处理其余工具。该命令随后在没有任何目标被回滚时以退出码 1 结束，在至少一个目标被回滚且同时记录了失败时以退出码 2（部分结果）结束。

选项Copy Anchor Link

JSON 输出Copy Anchor Link

该示例展示的是单个指定工具的外层结构。在 --harness all 下，harness 为 all，output_path 为 null，而 results 承载所有被选中工具的行。

{
  "schema_version": 1,
  "status": "success",
  "command": "rollback",
  "action": "rolled_back",
  "harness": "claude-code",
  "profile_path": null,
  "project": null,
  "files_written": [],
  "results": [],
  "warnings": [],
  "error": null,
  "output_path": "C:\\Users\\Example\\.claude\\settings.json"
}

每个被恢复或移除的目标都会出现在 results 中，带有 "operation": "rollback"，且 outcome 为 created 或 updated（同时出现在 files_written 中）；message 说明该路径是被恢复还是被移除。恢复失败（例如备份已被删除）为 "outcome": "error"。未记录任何更改的安装以 "outcome": "skipped" 报告。当针对单个指定的工具不存在匹配的安装记录时，该命令会报告一个 rollback.no_record 错误，并带有 "status": "error"。在 --harness all 下，没有匹配记录的工具则改为 results 中的一行 "outcome": "error"。

示例Copy Anchor Link

apothem rollback --harness claude-code --last
apothem rollback --harness claude-code --install-id 01J9Z… --yes
apothem rollback --harness cursor --project . --last --json

退出码Copy Anchor Link

另请参阅Copy Anchor Link

• apothem install——安装一个工具配置
• apothem update——从当前的共享配置档案重新安装
• apothem uninstall——移除一个工具配置
• apothem status——报告安装、验证和漂移状态