按理说，

长任务里最常见的撕裂

当 Agent 在执行长任务时模型、工具、资源还有思考级别都会在轮次之间发生变化。这些变化本身并不坏——长任务需要在每个轮次中调整一下。只是关键问题是一个请求发出后却读到了新旧混合的输入。

至于典型场景。

• 程序提示来自旧版资源，调用文本却来自新版资源；
• 请求开始时模型为 A。途中配置被改为 B，但返回仍按 B 的期望。

这种撕裂是最难排查的 bug 之一：不是逻辑错误，而是状态错误。话说回来，使用者常抱怨“为什么同一次请求返回的不一致”。原因往往就在这里，老实说，

turn 的边界

它既不是使用者在界面上看到的完整 prompt。也不是整个 runAgentLoop。更接近「一次 assistant response，加上它所需的完整工具批次」。

一个 turn 结束后Harness 会把这轮产生的 pending writes 写入 transcript，并为下一轮 provider 请求重建状态。老实说，

“快照”天然与 turn 绑定：每个 turn 都对应一份快照。turn 内部保持稳定，turn 与 turn 之间可随意变动。

快照里装着什么

createTurnState 做了哪些操作？它 调用 session.buildContext 读取当前 active branch 的消息和派生配置，再读取资源、session metadata 和 tool context。工具注册表被展开，active tool name 被映射成具体工具。如果程序提示来自回调，也在此处执行一次得到本轮真正使用的字符串。

至于返回值包含，

• messages
• resources
• toolContext
• streamOptions
• sessionId
• systemPrompt
• model
• 全部工具和 active tools 等信息也一起打包。

CreateContext 再对 messages 做一次顶层浅拷贝，并将 active tool 绑定到本轮解析出的 toolContext。这样，一个 provider 请求所需的可变输入就不再从 Harness 字段里零散读取。而是一份自洽整体，

使用者痛点一览：状态不一致导致调试成本飙升！

• “为什么我的代码跑两遍结果不同？”——因为环境在变化，却没有被锁定。
• “日志显示调用了旧版本 API，却用的是新参数。”——这是典型撕裂现象，
• “想要复现问题，却总是无法复现。”——状态漂移导致不可重现性。
• “调试耗时过久。”——因为必须手动追踪何时何地被改动了数据结构或配置。

快照不是深拷贝—你需要遵循不可变更新原则！

This section explains *** snapshots are shallow copies,not deep freezes.

为什么 snap‑shots 不等于冻结整个对象图？

- resources 容器和 stream options 会被复制，但 skill、prompt template、headers 等更深层对象仍然共享引用；其实，tools 也是具体对象实例而非复制副本。

• 实现依赖调用方遵守不可变更新习惯——使用 setResources 换一组值，而非悄悄 旧对象。

• 源码保证 Harness 自己不会在同一 turn 内重新选择这些对象，不是 JavaScript 世界里的深冻结。

• 深拷贝成本高且收益有限；真正需要保证的是“一轮不会读到被改了一半的配置”，而不是“一切永远不会变”。

三个入口共用同一份快照—避免跨入口撕裂！

• prompt

• skill

• promptFromTemplate

• 三种使用者发起运行，都先调用 createTurnState。

• skill 和 template 一样从这份 state 的 resources 中获取。

• 如果 skill 入口自己另读一份 resources，就可能出现「调用文本来自新版资源、程序提示却来自旧版资源」等撕裂。

• 单一统一入口 + 快照直接关闭此风险。

`保存点`是在工具结果之后设置的—让写入更可靠！

Agent 框架可靠性的主要在于「输入稳定性」——通过拍摄全局快照。把“状态变了”与“请求发出去了”严格分离，从而消除许多中途奇怪 bug。

源码依据：packages/agent/src/harness/agent-harness.ts L354-L397、L538-L565、L442-L497、L658-L704；packages/agent/src/agent-loop.ts L192-L245，pi v0.。commit 845d6ff1.