企业官网建设流程全解析

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_message（customType 为rewind-report），渲染时把本次调查得到的report填入{{report}}占位符。它的语义可以拆成三层：

1. 状态告知：Checkpoint called and rewound.——告诉模型，之前的检查点已被调用并完成回滚；
2. 内容保留：Report retained below.——探测过程中得到的结论没有丢失，而是保留在下方报告中；
3. 行为约束与引导：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。整体工作流如下：

1. 建立检查点：模型调用checkpoint，传入goal（调查目标）。CheckpointTool.execute()记录startedAt时间戳，并把当前内存消息数记为checkpointMessageCount（CheckpointState接口，见 checkpoint.ts）；
2. 自由探索：Agent 在检查点之后进行搜索、读文件、跑命令等探索性操作，这些中间过程会不断累积到会话上下文里；
3. 归纳报告：探索结束，模型调用rewind，传入report（调查发现摘要）；
4. 延迟落盘：rewind工具本身只是返回Rewind requested.，真正的回滚被推迟到当前助手回合结束（turn_end）时由AgentSession异步执行；
5. 分支重建：会话树在检查点位置分出新分支，探测分支被"剪掉"，只保留branch_summary（废弃路径的摘要）；
6. 报告注入：rewind-report隐藏消息被持久化并作为 developer 角色指引注入下一次模型调用（这就是本文章主题模板的用武之地）。

从工具定义看，checkpoint的输入 schema 是{ goal: string }，rewind的输入 schema 是{ report: string }，两者都声明approval = "read"、strict = true、loadMode = "discoverable"（checkpoint.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或首个文本内容块中提取报告存入#pendingRewindReport（agent-session.ts），真正的分支操作要等回合结束。

四、turn_end 延迟应用：分支、剪枝与报告注入

回滚的核心实现是AgentSession.#applyRewind()（agent-session.ts），其执行顺序如下：

1. 写 branch_summary：调用sessionManager.branchWithSummary(checkpointEntryId, report, { startedAt })，在检查点位置记录废弃路径的摘要；若检查点条目已失效，则回退到从根（root）分支并记录告警日志Rewind branch checkpoint missing, falling back to root（agent-session.ts）；
2. 注入 rewind-report：调用sessionManager.appendCustomMessageEntry("rewind-report", prompt.render(rewindReportTemplate, { report }), false, details, "agent")，其中details = { report, startedAt, rewoundAt }。这就是关联文档模板被实际写入会话日志的位置；
3. 记录完成状态：#lastCompletedRewind = { report, startedAt, rewoundAt }，供后续 resume/导航时重水合；
4. 重建上下文：从新活动分支构建会话上下文，替换当前回合的消息数组与agent.state.messages——探测分支与成功的 rewind 工具结果因此不会出现在下一次 provider 调用中；
5. 收尾：重置 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.与调查报告正文。测试还验证了回滚后toolResult（rewind 的返回）从上下文消失，会话消息角色序列变为["user", "assistant", "toolResult", "branchSummary", "custom", "assistant"]。

另一个测试（agent-session-checkpoint-rewind-branch.test.ts 起）验证了"检查点激活提醒"机制：在活动检查点存在时，如果模型试图 yield，#enforceRewindBeforeYield()会注入<system-warning>强制要求先调用rewind（agent-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 报告

1. 报告要精炼但信息完整：report是唯一跨过回滚边界保留的探索成果，后续模型只能依靠它继续推理，建议包含：已确认的事实、排除的假设、关键文件路径与行号、剩余风险、下一步建议；
2. 配合"再次探索需新建 checkpoint"：回滚后模型需要新探索时，应重新调用checkpoint建立新的安全点，而不是再次调用rewind（工具层会直接报错拒绝）；
3. 区分"上下文回滚"与"代码回滚"：rewind只回滚活动会话/会话树上下文，不恢复文件或 git 状态；需要代码级还原时，应另行依赖 git 等版本控制手段；
4. 关注分支摘要的可读性：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