oh-my-pi 的 rewind 机制与 rewind-report 报告模板把 Agent 探索上下文安全回滚到 Checkpoint【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本文以packages/coding-agent/src/prompts/system/rewind-report.md这份系统提示模板为切入点讲解 oh-my-pi⌥ Coding agent with the IDE wired in中checkpoint/rewind工具对的工作机制Agent 如何在探索性调查前建立检查点、用一段精炼报告回滚上下文以及rewind-report模板如何在回滚后把报告作为 developer 角色指引重新注入模型上下文。读完本文你将理解这条安全网链路的完整数据流并能在自己的会话里正确使用checkpoint与rewind。一、rewind-report.md一份只有 4 行的关键系统提示关联文档packages/coding-agent/src/prompts/system/rewind-report.md全文如下Checkpoint called and rewound. Report retained below. Need explore again → new checkpoint. Report: {{report}}这份模板虽然极短却是 rewind 回滚链路中注入给下一次模型调用的恢复指引。它属于 Agent 会话内的隐藏custom_messagecustomType 为rewind-report渲染时把本次调查得到的report填入{{report}}占位符。它的语义可以拆成三层状态告知Checkpoint called and rewound.——告诉模型之前的检查点已被调用并完成回滚内容保留Report retained below.——探测过程中得到的结论没有丢失而是保留在下方报告中行为约束与引导Need explore again → new checkpoint.——如果模型还需要继续探索不能重复调用rewind而是必须新建一个checkpoint对应测试中断言的 Do not callrewindagain。该模板由 agent-session.ts 以rewindReportTemplate导入并在回滚落盘时通过prompt.render(rewindReportTemplate, { report })渲染agent-session.ts。可见模板 报告文本 元数据三者共同构成了回滚后的恢复上下文。二、机制全景从 Checkpoint 到 Rewind 的两段式工作流checkpoint与rewind是一对配套工具源码位于 checkpoint.ts它们的模型面提示词分别位于 checkpoint.md 与 rewind.md。整体工作流如下建立检查点模型调用checkpoint传入goal调查目标。CheckpointTool.execute()记录startedAt时间戳并把当前内存消息数记为checkpointMessageCountCheckpointState接口见 checkpoint.ts自由探索Agent 在检查点之后进行搜索、读文件、跑命令等探索性操作这些中间过程会不断累积到会话上下文里归纳报告探索结束模型调用rewind传入report调查发现摘要延迟落盘rewind工具本身只是返回Rewind requested.真正的回滚被推迟到当前助手回合结束turn_end时由AgentSession异步执行分支重建会话树在检查点位置分出新分支探测分支被剪掉只保留branch_summary废弃路径的摘要报告注入rewind-report隐藏消息被持久化并作为 developer 角色指引注入下一次模型调用这就是本文章主题模板的用武之地。从工具定义看checkpoint的输入 schema 是{ goal: string }rewind的输入 schema 是{ report: string }两者都声明approval read、strict true、loadMode discoverablecheckpoint.ts。三、rewind 工具的实现细节与错误边界RewindTool.execute()的校验逻辑非常明确checkpoint.ts无活动检查点且已有完成的 rewind抛出ToolError(Checkpoint already completed; continue from the retained rewind report instead of calling rewind again.)——这正是rewind-report模板第二句语义在工具层的硬约束无活动检查点且无完成的 rewind抛出ToolError(No active checkpoint. Create a checkpoint before calling rewind.)报告为空params.report.trim()后长度为零时抛出ToolError(Report cannot be empty.)。成功路径返回toolResult({ report, rewound: true })文本内容为Rewind requested. Report captured for context replacement.值得注意返回的rewound: true并不代表回滚已经完成。AgentSession收到成功结果后先从details.report或首个文本内容块中提取报告存入#pendingRewindReportagent-session.ts真正的分支操作要等回合结束。四、turn_end 延迟应用分支、剪枝与报告注入回滚的核心实现是AgentSession.#applyRewind()agent-session.ts其执行顺序如下写 branch_summary调用sessionManager.branchWithSummary(checkpointEntryId, report, { startedAt })在检查点位置记录废弃路径的摘要若检查点条目已失效则回退到从根root分支并记录告警日志Rewind branch checkpoint missing, falling back to rootagent-session.ts注入 rewind-report调用sessionManager.appendCustomMessageEntry(rewind-report, prompt.render(rewindReportTemplate, { report }), false, details, agent)其中details { report, startedAt, rewoundAt }。这就是关联文档模板被实际写入会话日志的位置记录完成状态#lastCompletedRewind { report, startedAt, rewoundAt }供后续 resume/导航时重水合重建上下文从新活动分支构建会话上下文替换当前回合的消息数组与agent.state.messages——探测分支与成功的 rewind 工具结果因此不会出现在下一次 provider 调用中收尾重置 advisor 会话状态保留成本统计、从新分支同步 todo 状态、关闭因历史重写而失效的 provider 会话最后清空#checkpointState与#pendingRewindReport。SessionManager.branchWithSummary()session-manager.ts会生成一个类型为branch_summary的条目并写入持久化索引其字段包括fromId、summary、details等同时把活动叶子指针leaf重置到分支起点。五、上下文重建branchSummary 与 rewind-report 如何重新进入模型视野回滚后的下一次模型调用其上下文由 session-context.ts 的buildSessionContext()重建规则如下遇到branch_summary条目时转换成 LLM 可见的branchSummary消息用户角色渲染为summary块rewind-report是隐藏的custom_message以 developer 角色注入携带恢复指引与报告正文。测试 agent-session-checkpoint-rewind-branch.test.ts 精确断言了这一顺序最终一次 provider 调用的上下文中summary用户消息存在、rewind-reportdeveloper 消息存在且位于 summary 之后并且报告中必须包含模板原文Checkpoint called and rewound. Report retained below. Need explore again → new checkpoint.与调查报告正文。测试还验证了回滚后toolResultrewind 的返回从上下文消失会话消息角色序列变为[user, assistant, toolResult, branchSummary, custom, assistant]。另一个测试agent-session-checkpoint-rewind-branch.test.ts 起验证了检查点激活提醒机制在活动检查点存在时如果模型试图 yield#enforceRewindBeforeYield()会注入system-warning强制要求先调用rewindagent-session.ts而回滚剪枝后这条提醒从活动路径中消失。六、持久化与会话文件回滚如何跨进程存活rewind的副作用会通过正常的SessionManagerappend 持久化机制写入会话.jsonl文件branch_summary与custom_message两个条目。会话文件命名格式为ISO 时间戳(冒号与点替换为安全字符)_uuidv7.jsonl默认存放在~/.omp/agent/sessions/encoded-cwd/目录详见 rewind.md。在进程重启或会话树导航后持久化的rewind-report会重新水合#lastCompletedRewind模型得以继续沿用之前保留的报告而无需重新探索。注意持久化的报告/摘要内容受全局会话持久化上限MAX_PERSIST_CHARS 500_000约束。七、使用边界rewind 能回滚什么、不能回滚什么明确边界有助于避免误用官方工具文档 rewind.md 有完整清单回滚后恢复的状态会话树分支重置到checkpointEntryId或根回退废弃探索路径的branch_summary保留的rewind-report自定义消息从该分支重建的内存消息。不会恢复的状态文件系统或 git 状态rewind 不做代码级还原artifacts.ts 管理的工件blob-store.ts 的 blob 载荷history-storage.ts 的提示历史行agent-storage.ts 的认证等其他 Agent 存储。其他限制包括checkpoint.enabled默认关闭false需显式开启子代理默认不发现该工具需在 requested-tools 列表中显式请求且请求checkpoint/rewind任一会自动包含另一个一个会话同时最多只有一个活动检查点不支持命名或多检查点选择。八、实战建议用好 checkpoint/rewind 报告报告要精炼但信息完整report是唯一跨过回滚边界保留的探索成果后续模型只能依靠它继续推理建议包含已确认的事实、排除的假设、关键文件路径与行号、剩余风险、下一步建议配合再次探索需新建 checkpoint回滚后模型需要新探索时应重新调用checkpoint建立新的安全点而不是再次调用rewind工具层会直接报错拒绝区分上下文回滚与代码回滚rewind只回滚活动会话/会话树上下文不恢复文件或 git 状态需要代码级还原时应另行依赖 git 等版本控制手段关注分支摘要的可读性branch_summary在压缩渲染时以用户角色summary块呈现报告质量直接影响后续回合的推理效率。结语rewind-report.md虽然只有四行但它把检查点已回滚、报告已保留、如需再探索请新建检查点这条完整的状态机规则固化进了系统提示是 oh-my-pi 中checkpoint/rewind探索回滚机制收尾的关键一环。配合 checkpoint.ts 的工具实现、agent-session.ts 的延迟应用逻辑、session-manager.ts 的分支持久化与 session-context.ts 的上下文重建你可以完整理解这条安全网的每一个环节并在自己的 Agent 会话中放心地进行长程探索。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
oh-my-pi 的 rewind 机制与 rewind-report 报告模板：把 Agent 探索上下文安全回滚到 Checkpoint
oh-my-pi 的 rewind 机制与 rewind-report 报告模板把 Agent 探索上下文安全回滚到 Checkpoint【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本文以packages/coding-agent/src/prompts/system/rewind-report.md这份系统提示模板为切入点讲解 oh-my-pi⌥ Coding agent with the IDE wired in中checkpoint/rewind工具对的工作机制Agent 如何在探索性调查前建立检查点、用一段精炼报告回滚上下文以及rewind-report模板如何在回滚后把报告作为 developer 角色指引重新注入模型上下文。读完本文你将理解这条安全网链路的完整数据流并能在自己的会话里正确使用checkpoint与rewind。一、rewind-report.md一份只有 4 行的关键系统提示关联文档packages/coding-agent/src/prompts/system/rewind-report.md全文如下Checkpoint called and rewound. Report retained below. Need explore again → new checkpoint. Report: {{report}}这份模板虽然极短却是 rewind 回滚链路中注入给下一次模型调用的恢复指引。它属于 Agent 会话内的隐藏custom_messagecustomType 为rewind-report渲染时把本次调查得到的report填入{{report}}占位符。它的语义可以拆成三层状态告知Checkpoint called and rewound.——告诉模型之前的检查点已被调用并完成回滚内容保留Report retained below.——探测过程中得到的结论没有丢失而是保留在下方报告中行为约束与引导Need explore again → new checkpoint.——如果模型还需要继续探索不能重复调用rewind而是必须新建一个checkpoint对应测试中断言的 Do not callrewindagain。该模板由 agent-session.ts 以rewindReportTemplate导入并在回滚落盘时通过prompt.render(rewindReportTemplate, { report })渲染agent-session.ts。可见模板 报告文本 元数据三者共同构成了回滚后的恢复上下文。二、机制全景从 Checkpoint 到 Rewind 的两段式工作流checkpoint与rewind是一对配套工具源码位于 checkpoint.ts它们的模型面提示词分别位于 checkpoint.md 与 rewind.md。整体工作流如下建立检查点模型调用checkpoint传入goal调查目标。CheckpointTool.execute()记录startedAt时间戳并把当前内存消息数记为checkpointMessageCountCheckpointState接口见 checkpoint.ts自由探索Agent 在检查点之后进行搜索、读文件、跑命令等探索性操作这些中间过程会不断累积到会话上下文里归纳报告探索结束模型调用rewind传入report调查发现摘要延迟落盘rewind工具本身只是返回Rewind requested.真正的回滚被推迟到当前助手回合结束turn_end时由AgentSession异步执行分支重建会话树在检查点位置分出新分支探测分支被剪掉只保留branch_summary废弃路径的摘要报告注入rewind-report隐藏消息被持久化并作为 developer 角色指引注入下一次模型调用这就是本文章主题模板的用武之地。从工具定义看checkpoint的输入 schema 是{ goal: string }rewind的输入 schema 是{ report: string }两者都声明approval read、strict true、loadMode discoverablecheckpoint.ts。三、rewind 工具的实现细节与错误边界RewindTool.execute()的校验逻辑非常明确checkpoint.ts无活动检查点且已有完成的 rewind抛出ToolError(Checkpoint already completed; continue from the retained rewind report instead of calling rewind again.)——这正是rewind-report模板第二句语义在工具层的硬约束无活动检查点且无完成的 rewind抛出ToolError(No active checkpoint. Create a checkpoint before calling rewind.)报告为空params.report.trim()后长度为零时抛出ToolError(Report cannot be empty.)。成功路径返回toolResult({ report, rewound: true })文本内容为Rewind requested. Report captured for context replacement.值得注意返回的rewound: true并不代表回滚已经完成。AgentSession收到成功结果后先从details.report或首个文本内容块中提取报告存入#pendingRewindReportagent-session.ts真正的分支操作要等回合结束。四、turn_end 延迟应用分支、剪枝与报告注入回滚的核心实现是AgentSession.#applyRewind()agent-session.ts其执行顺序如下写 branch_summary调用sessionManager.branchWithSummary(checkpointEntryId, report, { startedAt })在检查点位置记录废弃路径的摘要若检查点条目已失效则回退到从根root分支并记录告警日志Rewind branch checkpoint missing, falling back to rootagent-session.ts注入 rewind-report调用sessionManager.appendCustomMessageEntry(rewind-report, prompt.render(rewindReportTemplate, { report }), false, details, agent)其中details { report, startedAt, rewoundAt }。这就是关联文档模板被实际写入会话日志的位置记录完成状态#lastCompletedRewind { report, startedAt, rewoundAt }供后续 resume/导航时重水合重建上下文从新活动分支构建会话上下文替换当前回合的消息数组与agent.state.messages——探测分支与成功的 rewind 工具结果因此不会出现在下一次 provider 调用中收尾重置 advisor 会话状态保留成本统计、从新分支同步 todo 状态、关闭因历史重写而失效的 provider 会话最后清空#checkpointState与#pendingRewindReport。SessionManager.branchWithSummary()session-manager.ts会生成一个类型为branch_summary的条目并写入持久化索引其字段包括fromId、summary、details等同时把活动叶子指针leaf重置到分支起点。五、上下文重建branchSummary 与 rewind-report 如何重新进入模型视野回滚后的下一次模型调用其上下文由 session-context.ts 的buildSessionContext()重建规则如下遇到branch_summary条目时转换成 LLM 可见的branchSummary消息用户角色渲染为summary块rewind-report是隐藏的custom_message以 developer 角色注入携带恢复指引与报告正文。测试 agent-session-checkpoint-rewind-branch.test.ts 精确断言了这一顺序最终一次 provider 调用的上下文中summary用户消息存在、rewind-reportdeveloper 消息存在且位于 summary 之后并且报告中必须包含模板原文Checkpoint called and rewound. Report retained below. Need explore again → new checkpoint.与调查报告正文。测试还验证了回滚后toolResultrewind 的返回从上下文消失会话消息角色序列变为[user, assistant, toolResult, branchSummary, custom, assistant]。另一个测试agent-session-checkpoint-rewind-branch.test.ts 起验证了检查点激活提醒机制在活动检查点存在时如果模型试图 yield#enforceRewindBeforeYield()会注入system-warning强制要求先调用rewindagent-session.ts而回滚剪枝后这条提醒从活动路径中消失。六、持久化与会话文件回滚如何跨进程存活rewind的副作用会通过正常的SessionManagerappend 持久化机制写入会话.jsonl文件branch_summary与custom_message两个条目。会话文件命名格式为ISO 时间戳(冒号与点替换为安全字符)_uuidv7.jsonl默认存放在~/.omp/agent/sessions/encoded-cwd/目录详见 rewind.md。在进程重启或会话树导航后持久化的rewind-report会重新水合#lastCompletedRewind模型得以继续沿用之前保留的报告而无需重新探索。注意持久化的报告/摘要内容受全局会话持久化上限MAX_PERSIST_CHARS 500_000约束。七、使用边界rewind 能回滚什么、不能回滚什么明确边界有助于避免误用官方工具文档 rewind.md 有完整清单回滚后恢复的状态会话树分支重置到checkpointEntryId或根回退废弃探索路径的branch_summary保留的rewind-report自定义消息从该分支重建的内存消息。不会恢复的状态文件系统或 git 状态rewind 不做代码级还原artifacts.ts 管理的工件blob-store.ts 的 blob 载荷history-storage.ts 的提示历史行agent-storage.ts 的认证等其他 Agent 存储。其他限制包括checkpoint.enabled默认关闭false需显式开启子代理默认不发现该工具需在 requested-tools 列表中显式请求且请求checkpoint/rewind任一会自动包含另一个一个会话同时最多只有一个活动检查点不支持命名或多检查点选择。八、实战建议用好 checkpoint/rewind 报告报告要精炼但信息完整report是唯一跨过回滚边界保留的探索成果后续模型只能依靠它继续推理建议包含已确认的事实、排除的假设、关键文件路径与行号、剩余风险、下一步建议配合再次探索需新建 checkpoint回滚后模型需要新探索时应重新调用checkpoint建立新的安全点而不是再次调用rewind工具层会直接报错拒绝区分上下文回滚与代码回滚rewind只回滚活动会话/会话树上下文不恢复文件或 git 状态需要代码级还原时应另行依赖 git 等版本控制手段关注分支摘要的可读性branch_summary在压缩渲染时以用户角色summary块呈现报告质量直接影响后续回合的推理效率。结语rewind-report.md虽然只有四行但它把检查点已回滚、报告已保留、如需再探索请新建检查点这条完整的状态机规则固化进了系统提示是 oh-my-pi 中checkpoint/rewind探索回滚机制收尾的关键一环。配合 checkpoint.ts 的工具实现、agent-session.ts 的延迟应用逻辑、session-manager.ts 的分支持久化与 session-context.ts 的上下文重建你可以完整理解这条安全网的每一个环节并在自己的 Agent 会话中放心地进行长程探索。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考