Unreal Agent 踩坑五连会话分叉、幂等收件箱与异步超时哪一个最致命【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agentUnreal Agent 是一套来自 Unreal Labs 的 async-first agent harness它把LLM 推理与工具执行彻底解耦模型发出工具调用后立即返回工具以 Operation 形式异步落地执行执行完成再把结果回填进上下文。这套设计直接对冲掉了 Agent 最贵的两个痛点——LLM 空等和 token 浪费社区里相比 Codex 省 40% 成本的说法也正是由此而来。但解耦从来不是免费的。异步化把单线程的提问—回答变成了多事件源并发汇合用户输入、操作完成、心跳、模型响应在同一个事件循环里竞争会话还要支持分叉、崩溃恢复与重试。我在通读 harness/session/session.go、harness/inbox/inbox.go、harness/coordinator/loop.go 之后整理了五类最容易踩的坑从心智负担到数据一致性依次排雷。坑一并发投递时收件箱成了静默丢弃的黑洞先看最简单的坑。Inbox 是整个 harness 的输入入口它的职责用包注释一句话说得很清楚Package inbox owns input deduplication for one session——为单个会话做输入去重。去重的依据是调用方提供的全局唯一 ID。在 harness/inbox/local.go 的run循环里逻辑非常直白case input : -submissions: if _, duplicate : seen[input.ID]; duplicate { continue } seen[input.ID] struct{}{} queued append(queued, input)同一个 ID 第二次进来直接continue静默丢弃连错误都不返回。这套设计的语义是至少一次投递、恰好一次处理——生产者可以放心重试代价是去重责任完全压在 ID 的生成质量上。于是第一个坑出现了如果调用方把 ID 生成得不够唯一比如按内容哈希、按时间戳截断、或者两个客户端共用一套 ID 空间那么两条不同的消息会共享同一个 ID其中一条被无声吞掉。最隐蔽的是第三条Submit的调用方以为成功了返回 nil但事件从未进入会话。去重保护的是重发而不是错误——ID 一旦撞车丢消息是静默的。更值得注意的边界在 harness/coordinator/loop.go 的slurpChannel事件循环从 Inbox 里批量舀输入空闲 1msslurpIdleTimeout或凑满 100 条slurpMaxItems就进入处理。这意味着消息不是逐条处理而是按批次提交——批内某条输入处理失败会导致整批回滚报错但已被seen记下的 ID 不会再被重放恢复后这条输入可能直接丢失。排雷结论ID 必须由调用方生成、全局唯一、跨重试稳定这是 Inbox 一切正确性的前提。坑二会话分叉Fork继承的是一份残缺历史如果说坑一是入口处的丢消息坑二则是出口处的语义撕裂。会话被设计成只追加、可分叉的账本这个能力由 harness/sessionstore/sessionstore.go 的Store接口暴露Fork( ctx context.Context, id session.ID, parentID session.ID, previousTurnID session.TurnID, ) (Snapshot, error)分叉的实现在 harness/sessionstore/localfile/state.go 的forkStoredState从父会话的历史里找到previousTurnID对应的边界把边界之前的条目全部继承然后追加一条ItemFork记录最后resetOwnedState()清空子会话自己拥有的轮次、响应与工具调用状态。问题就在inheritItem里那行不起眼的代码case sessionstore.ItemToolCallStatus: status : item.Data.(sessionstore.ToolCallStatus) // TODO: Preserve status snapshots in forked history without making inherited operations dispatchable. status.Operations nil分叉继承下来的工具调用状态其 Operation 列表被强制清空了。也就是说父会话里还在执行中的 Bash 命令、ViewImage 任务在子会话里只剩一个状态快照外壳没有对应的可执行工作单。代码里的注释直接把设计矛盾写在了脸上——既想保留状态快照又不想让继承的操作在子会话里被重新派发执行。再看协调器恢复分叉历史时的处理harness/coordinator/loop.go 的addItemToLocalStatecase sessionstore.ItemFork: ... // FIXME: Forks leave inherited calls without results and retain pending-input accounting. clear(current.state.toolCalls) clear(current.state.operations)FIXME注释承认了一个真实缺陷分叉后继承下来的工具调用既没有结果还残留着待处理输入的记账状态availableInputs与deliveredInputs的差值不会自动归零。如果父会话 fork 时正卡在一个长时间运行的 Operation 上子会话的模型上下文里会看到一个被调用过但永远没有结果的工具调用——模型读历史时会以为工具还在运行或产生幻觉式的推断。TestCoordinatorForkStopsWhenChildIsIdleharness/coordinator/fork_test.go用 10 种组合父会话处于未调度/运行中/已完成/压缩中/压缩响应等阶段 × 子会话是否使用工具钉死了分叉的语义边界子会话不得继承父会话的待执行工作、不得启动父会话的 in-flight 工具调用但必须保留父会话的上下文与轮次边界。这套测试非常严格却恰恰说明——分叉只保证上下文延续不保证执行状态延续。多任务并发时如果天真地以为 fork 出的子会话可以接着把父会话没跑完的活干完就会在父工具结果缺失上踩坑。坑三grace period 与异步完成的竞态——工具结果被推迟甚至错配异步化的核心难点是模型在一次响应里可能发起多个工具调用它们各自异步执行、完成时间参差不齐。如果每完成一个就立刻把结果塞回上下文再调一次模型token 和延迟都会爆炸如果傻等最慢的那个又回到同步阻塞。Unreal Agent 的解法是 grace period——宽限期。协调器维护graceToolCalls集合与一个toolCallCompletionGracePeriod1 秒计时器harness/coordinator/loop.goif len(completed) 0 { hasPendingSiblings : false for _, status : range completed { for key : range current.state.toolCalls { if key.turnID status.TurnID { current.state.graceToolCalls[key] struct{}{} hasPendingSiblings true } } } if hasPendingSiblings { current.state.grace time.After(toolCallCompletionGracePeriod) } }逻辑是同一轮里某个工具完成后先把它的结果扣住不发等最多 1 秒看同一轮的其他工具是否也完成好把结果批量塞进一次模型请求。如果 1 秒内全部完成宽限期提前结束否则超时后把已完成的先发出去。这套机制在 harness/coordinator/grace_test.go 里被穷举验证包括先完成的工具不立即发模型、迟到的兄弟节点加入宽限期、新输入打断宽限期等场景。但踩坑点也恰恰藏在竞态里宽限期窗口内如果新输入到达steeringclearToolGrace()会立即清掉所有挂起的工具结果与计时器harness/coordinator/loop.go 的clearToolGrace那些快完成但还没完成的工具其结果要等模型对 steering 输入做出响应、新的工具状态 reconcile 之后才可能被带回。多任务并发下的实际体验就是任务 A 的结果明明 0.9 秒就完成了却可能因为任务 B 拖了 10 秒导致 A 的结果在模型视角里迟到了一整轮。如果业务上把工具结果当作即时反馈会觉得模型在装傻而真实原因是 harness 有意用 1 秒的窗口换 token 效率。排雷要点不要把工具完成时间当作确定性事件结果到达模型上下文的时机受同轮兄弟任务与宽限期策略共同决定。坑四LLM 超时重试背后的幂等债务异步架构把超时问题从一个请求放大成一串请求。LLM 适配层的重试逻辑在 harness/llm/messagesapi/retry.goreturn err.StatusCode 408 || err.StatusCode 409 || err.StatusCode 429 || err.StatusCode 500408请求超时、409冲突、429限流、5xx 全部重试且尊重服务端返回的Retry-After-Ms/Retry-After头遵循InitialBackoff与MaxBackoff的退避策略harness/primitives/remote.go 里DefaultRemoteRequest的默认值是最大 30 秒退避、初始 2 秒。问题在于超时是幂等债务的重灾区。一次 LLM 调用超时重试时会话里已经写入了ItemTurn轮次创建记录。重试成功后新响应会追加为新的ItemModelResponse——但轮次 ID 已经换了requestModelResponse里每次uuid.New()生成新 TurnID。此时协调器通过received.turnID ! current.state.currentTurnID过滤迟到的模型响应case received : -modelResponses: if current.cancelModel nil || received.turnID ! current.state.currentTurnID { continue }旧轮次的响应如果因为网络抖动晚到会被直接丢弃。这本是防御超时的正确姿势但衍生出一个隐蔽坑被丢弃的响应对应的工具调用永远不会被调度而会话历史里已经记录了这个轮次的存在。恢复时Resume会话会重放历史、重算工具调用状态——harness/coordinator/loop.go 的restore会把非终态的 Operation 重新派发。也就是说超时重试的正确性依赖Operation 必须可恢复且可重放这要求 Operation 的Idempotency字段harness/operation/operation.go 中Spec.Idempotency与Operation.Idempotency被认真使用。Operation 每次派发前都会被克隆并连同幂等数据一并交给 ManagerdispatchOperationToManager里的value.Idempotency value.Idempotency.Clone()而LocalOperationManager.Add的注释明确写着Add starts an operation at most once for each ID during the managers lifetimeharness/operation/local_manager.go。所以超时重试的正确姿势是重试的是整个协调循环而不是单个请求——LLM 请求失败后靠会话持久化 收件箱去重 Operation 幂等三层兜底把重试过的轮次变成恢复后的新轮次。如果跳过这些层、直接在应用层做 HTTP 级重试就可能出现模型被调了两次、工具被调度了一次半的状态错乱。坑五远程沙箱执行中的结果未知与心跳超时最后一个坑来自 Operation 的可插拔执行模型。README 里明确说了Operations are versioned and always serializable而 LocalOperationManager 可以替换为代理 Operation Manager——把序列化后的 Operation 转发给远程沙箱进程执行README.md 的 Extending the harness 一节。harness/operation/remote_job.go 里的RemoteJobHandler接口就是为此设计的。远程执行引入了 LocalOperationManager 里没有的致命歧义——取消Cancel一个远程任务时结果可能已经发出但尚未送达。看 harness/operation/local_manager.go 的取消分支if current.remoteJobHandlerIndex 0 { if err : manager.remoteJobs.cancel(...); err ! nil { manager.failLocalOperation(operations, current, fmt.Errorf(remote job outcome is unknown because cancellation failed: %v, err)) } continue }错误信息直言不讳remote job outcome is unknown because cancellation failed——远程任务取消失败时这个 Operation 的结果变成了薛定谔的猫可能已经完成、可能正在执行、可能永远不会回来。协调器只能把这个 Operation 标记为失败但真实结果可能已经污染了沙箱里的共享状态比如远程沙箱里已执行的apt install或已写入的文件而会话历史对这一切一无所知。更隐蔽的是心跳。协调器在只等工具调用的状态下会按ToolHeartbeatInterval定时投递心跳控制消息postHeartbeatharness/coordinator/loop.gopayload, err : json.Marshal(inbox.ControlMessage{ Mode: inbox.Heartbeat, Reason: fmt.Sprintf(Heartbeat: waited %g seconds for tool calls.\nRunning: %s, ...), })心跳本身走的就是 Inbox——一个带去重的通道。如果心跳消息 ID 生成出错复用 ID心跳会被静默丢弃模型将长时间得不到工具还在跑的反馈用户界面会看起来卡死如果ToolHeartbeatInterval配置为负值协调器直接拒绝启动。再加上远程 HTTP 层的ResponseIdleTimeout默认 30 秒与RetryAfter类头信息远程执行链路里的每一个超时都对应一次重试 or 取消的决策而决策错了就落进上面的结果未知。排雷优先级五坑里谁最致命把这五个坑按可恢复性排序结论很明确坑故障模式是否可自动恢复收件箱 ID 撞车消息静默丢弃否——数据丢失且无感知分叉继承残缺历史子会话读到无结果的工具调用部分——靠新上下文重跑但语义已错grace 竞态工具结果迟到一整轮是——模型会收到后续结果只是延迟LLM 超时重试轮次/响应错配是——靠恢复重放 幂等兜底远程取消结果未知沙箱状态污染否——污染发生在 harness 视野之外最致命的是坑一收件箱 ID 撞车。因为它把幂等的语义建立在调用方契约上而契约一旦被违反失败是静默的、不可感知的、且不留给恢复机制任何把柄。分叉缺陷虽然语义上很扎眼源码里挂着 FIXME但至少测试覆盖了 10 种组合、失败模式可观测收件箱的 ID 撞车则连错误日志都不会有。次致命的是坑五远程沙箱取消后结果未知直接让操作状态与真实世界状态永久性分叉而分叉发生在 harness 的可见范围之外。规避方案按投入产出比排序ID 纪律所有 Input 与 Operation 的 ID 必须由调用方生成、UUID 级唯一、跨重试稳定并在测试里显式断言同一 ID 投递两次只处理一次harness/inbox/local_test.go 的用例方向。分叉前收敛fork 之前先StopWhenIdle让父会话把 in-flight 工具收尾避免把无结果工具调用带入子会话对 fork 出的子会话单独做一轮上下文压缩切断对父会话 in-flight 状态的依赖。正视 grace 的语义不要把工具结果到达时间当作确定性事件对结果迟到敏感的业务用ToolHeartbeatInterval让模型持续感知工具仍在运行而不是靠人工判断卡死。超时重试分层LLM 请求超时后放弃 HTTP 级重试直接终止轮次、交给会话恢复Resume重放所有自定义 Operation 必须填充Idempotency数据并保证相同幂等键只执行一次副作用。远程执行给不确定结果留出口远程任务取消失败时把 Operation 标记为未知而非失败并让上层策略决定是重试还是终止整个会话——永远不要假定远程沙箱是幂等的。async-first 的真正门槛不在把工具调用变成异步而在于把每一次不确定都变成可恢复的确定。Unreal Agent 用 Append-Only 会话账本、幂等收件箱和可序列化的 Operation 搭建了这套恢复框架但它的每一个组件都要求使用者理解并遵守底层契约——这正是排雷的本质不是修 bug而是驯服不确定性。【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/11 4:11:10 · 阅读 1.2k Unreal Agent 踩坑五连：会话分叉、幂等收件箱与异步超时，哪一个最致命？
Unreal Agent 踩坑五连会话分叉、幂等收件箱与异步超时哪一个最致命【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agentUnreal Agent 是一套来自 Unreal Labs 的 async-first agent harness它把LLM 推理与工具执行彻底解耦模型发出工具调用后立即返回工具以 Operation 形式异步落地执行执行完成再把结果回填进上下文。这套设计直接对冲掉了 Agent 最贵的两个痛点——LLM 空等和 token 浪费社区里相比 Codex 省 40% 成本的说法也正是由此而来。但解耦从来不是免费的。异步化把单线程的提问—回答变成了多事件源并发汇合用户输入、操作完成、心跳、模型响应在同一个事件循环里竞争会话还要支持分叉、崩溃恢复与重试。我在通读 harness/session/session.go、harness/inbox/inbox.go、harness/coordinator/loop.go 之后整理了五类最容易踩的坑从心智负担到数据一致性依次排雷。坑一并发投递时收件箱成了静默丢弃的黑洞先看最简单的坑。Inbox 是整个 harness 的输入入口它的职责用包注释一句话说得很清楚Package inbox owns input deduplication for one session——为单个会话做输入去重。去重的依据是调用方提供的全局唯一 ID。在 harness/inbox/local.go 的run循环里逻辑非常直白case input : -submissions: if _, duplicate : seen[input.ID]; duplicate { continue } seen[input.ID] struct{}{} queued append(queued, input)同一个 ID 第二次进来直接continue静默丢弃连错误都不返回。这套设计的语义是至少一次投递、恰好一次处理——生产者可以放心重试代价是去重责任完全压在 ID 的生成质量上。于是第一个坑出现了如果调用方把 ID 生成得不够唯一比如按内容哈希、按时间戳截断、或者两个客户端共用一套 ID 空间那么两条不同的消息会共享同一个 ID其中一条被无声吞掉。最隐蔽的是第三条Submit的调用方以为成功了返回 nil但事件从未进入会话。去重保护的是重发而不是错误——ID 一旦撞车丢消息是静默的。更值得注意的边界在 harness/coordinator/loop.go 的slurpChannel事件循环从 Inbox 里批量舀输入空闲 1msslurpIdleTimeout或凑满 100 条slurpMaxItems就进入处理。这意味着消息不是逐条处理而是按批次提交——批内某条输入处理失败会导致整批回滚报错但已被seen记下的 ID 不会再被重放恢复后这条输入可能直接丢失。排雷结论ID 必须由调用方生成、全局唯一、跨重试稳定这是 Inbox 一切正确性的前提。坑二会话分叉Fork继承的是一份残缺历史如果说坑一是入口处的丢消息坑二则是出口处的语义撕裂。会话被设计成只追加、可分叉的账本这个能力由 harness/sessionstore/sessionstore.go 的Store接口暴露Fork( ctx context.Context, id session.ID, parentID session.ID, previousTurnID session.TurnID, ) (Snapshot, error)分叉的实现在 harness/sessionstore/localfile/state.go 的forkStoredState从父会话的历史里找到previousTurnID对应的边界把边界之前的条目全部继承然后追加一条ItemFork记录最后resetOwnedState()清空子会话自己拥有的轮次、响应与工具调用状态。问题就在inheritItem里那行不起眼的代码case sessionstore.ItemToolCallStatus: status : item.Data.(sessionstore.ToolCallStatus) // TODO: Preserve status snapshots in forked history without making inherited operations dispatchable. status.Operations nil分叉继承下来的工具调用状态其 Operation 列表被强制清空了。也就是说父会话里还在执行中的 Bash 命令、ViewImage 任务在子会话里只剩一个状态快照外壳没有对应的可执行工作单。代码里的注释直接把设计矛盾写在了脸上——既想保留状态快照又不想让继承的操作在子会话里被重新派发执行。再看协调器恢复分叉历史时的处理harness/coordinator/loop.go 的addItemToLocalStatecase sessionstore.ItemFork: ... // FIXME: Forks leave inherited calls without results and retain pending-input accounting. clear(current.state.toolCalls) clear(current.state.operations)FIXME注释承认了一个真实缺陷分叉后继承下来的工具调用既没有结果还残留着待处理输入的记账状态availableInputs与deliveredInputs的差值不会自动归零。如果父会话 fork 时正卡在一个长时间运行的 Operation 上子会话的模型上下文里会看到一个被调用过但永远没有结果的工具调用——模型读历史时会以为工具还在运行或产生幻觉式的推断。TestCoordinatorForkStopsWhenChildIsIdleharness/coordinator/fork_test.go用 10 种组合父会话处于未调度/运行中/已完成/压缩中/压缩响应等阶段 × 子会话是否使用工具钉死了分叉的语义边界子会话不得继承父会话的待执行工作、不得启动父会话的 in-flight 工具调用但必须保留父会话的上下文与轮次边界。这套测试非常严格却恰恰说明——分叉只保证上下文延续不保证执行状态延续。多任务并发时如果天真地以为 fork 出的子会话可以接着把父会话没跑完的活干完就会在父工具结果缺失上踩坑。坑三grace period 与异步完成的竞态——工具结果被推迟甚至错配异步化的核心难点是模型在一次响应里可能发起多个工具调用它们各自异步执行、完成时间参差不齐。如果每完成一个就立刻把结果塞回上下文再调一次模型token 和延迟都会爆炸如果傻等最慢的那个又回到同步阻塞。Unreal Agent 的解法是 grace period——宽限期。协调器维护graceToolCalls集合与一个toolCallCompletionGracePeriod1 秒计时器harness/coordinator/loop.goif len(completed) 0 { hasPendingSiblings : false for _, status : range completed { for key : range current.state.toolCalls { if key.turnID status.TurnID { current.state.graceToolCalls[key] struct{}{} hasPendingSiblings true } } } if hasPendingSiblings { current.state.grace time.After(toolCallCompletionGracePeriod) } }逻辑是同一轮里某个工具完成后先把它的结果扣住不发等最多 1 秒看同一轮的其他工具是否也完成好把结果批量塞进一次模型请求。如果 1 秒内全部完成宽限期提前结束否则超时后把已完成的先发出去。这套机制在 harness/coordinator/grace_test.go 里被穷举验证包括先完成的工具不立即发模型、迟到的兄弟节点加入宽限期、新输入打断宽限期等场景。但踩坑点也恰恰藏在竞态里宽限期窗口内如果新输入到达steeringclearToolGrace()会立即清掉所有挂起的工具结果与计时器harness/coordinator/loop.go 的clearToolGrace那些快完成但还没完成的工具其结果要等模型对 steering 输入做出响应、新的工具状态 reconcile 之后才可能被带回。多任务并发下的实际体验就是任务 A 的结果明明 0.9 秒就完成了却可能因为任务 B 拖了 10 秒导致 A 的结果在模型视角里迟到了一整轮。如果业务上把工具结果当作即时反馈会觉得模型在装傻而真实原因是 harness 有意用 1 秒的窗口换 token 效率。排雷要点不要把工具完成时间当作确定性事件结果到达模型上下文的时机受同轮兄弟任务与宽限期策略共同决定。坑四LLM 超时重试背后的幂等债务异步架构把超时问题从一个请求放大成一串请求。LLM 适配层的重试逻辑在 harness/llm/messagesapi/retry.goreturn err.StatusCode 408 || err.StatusCode 409 || err.StatusCode 429 || err.StatusCode 500408请求超时、409冲突、429限流、5xx 全部重试且尊重服务端返回的Retry-After-Ms/Retry-After头遵循InitialBackoff与MaxBackoff的退避策略harness/primitives/remote.go 里DefaultRemoteRequest的默认值是最大 30 秒退避、初始 2 秒。问题在于超时是幂等债务的重灾区。一次 LLM 调用超时重试时会话里已经写入了ItemTurn轮次创建记录。重试成功后新响应会追加为新的ItemModelResponse——但轮次 ID 已经换了requestModelResponse里每次uuid.New()生成新 TurnID。此时协调器通过received.turnID ! current.state.currentTurnID过滤迟到的模型响应case received : -modelResponses: if current.cancelModel nil || received.turnID ! current.state.currentTurnID { continue }旧轮次的响应如果因为网络抖动晚到会被直接丢弃。这本是防御超时的正确姿势但衍生出一个隐蔽坑被丢弃的响应对应的工具调用永远不会被调度而会话历史里已经记录了这个轮次的存在。恢复时Resume会话会重放历史、重算工具调用状态——harness/coordinator/loop.go 的restore会把非终态的 Operation 重新派发。也就是说超时重试的正确性依赖Operation 必须可恢复且可重放这要求 Operation 的Idempotency字段harness/operation/operation.go 中Spec.Idempotency与Operation.Idempotency被认真使用。Operation 每次派发前都会被克隆并连同幂等数据一并交给 ManagerdispatchOperationToManager里的value.Idempotency value.Idempotency.Clone()而LocalOperationManager.Add的注释明确写着Add starts an operation at most once for each ID during the managers lifetimeharness/operation/local_manager.go。所以超时重试的正确姿势是重试的是整个协调循环而不是单个请求——LLM 请求失败后靠会话持久化 收件箱去重 Operation 幂等三层兜底把重试过的轮次变成恢复后的新轮次。如果跳过这些层、直接在应用层做 HTTP 级重试就可能出现模型被调了两次、工具被调度了一次半的状态错乱。坑五远程沙箱执行中的结果未知与心跳超时最后一个坑来自 Operation 的可插拔执行模型。README 里明确说了Operations are versioned and always serializable而 LocalOperationManager 可以替换为代理 Operation Manager——把序列化后的 Operation 转发给远程沙箱进程执行README.md 的 Extending the harness 一节。harness/operation/remote_job.go 里的RemoteJobHandler接口就是为此设计的。远程执行引入了 LocalOperationManager 里没有的致命歧义——取消Cancel一个远程任务时结果可能已经发出但尚未送达。看 harness/operation/local_manager.go 的取消分支if current.remoteJobHandlerIndex 0 { if err : manager.remoteJobs.cancel(...); err ! nil { manager.failLocalOperation(operations, current, fmt.Errorf(remote job outcome is unknown because cancellation failed: %v, err)) } continue }错误信息直言不讳remote job outcome is unknown because cancellation failed——远程任务取消失败时这个 Operation 的结果变成了薛定谔的猫可能已经完成、可能正在执行、可能永远不会回来。协调器只能把这个 Operation 标记为失败但真实结果可能已经污染了沙箱里的共享状态比如远程沙箱里已执行的apt install或已写入的文件而会话历史对这一切一无所知。更隐蔽的是心跳。协调器在只等工具调用的状态下会按ToolHeartbeatInterval定时投递心跳控制消息postHeartbeatharness/coordinator/loop.gopayload, err : json.Marshal(inbox.ControlMessage{ Mode: inbox.Heartbeat, Reason: fmt.Sprintf(Heartbeat: waited %g seconds for tool calls.\nRunning: %s, ...), })心跳本身走的就是 Inbox——一个带去重的通道。如果心跳消息 ID 生成出错复用 ID心跳会被静默丢弃模型将长时间得不到工具还在跑的反馈用户界面会看起来卡死如果ToolHeartbeatInterval配置为负值协调器直接拒绝启动。再加上远程 HTTP 层的ResponseIdleTimeout默认 30 秒与RetryAfter类头信息远程执行链路里的每一个超时都对应一次重试 or 取消的决策而决策错了就落进上面的结果未知。排雷优先级五坑里谁最致命把这五个坑按可恢复性排序结论很明确坑故障模式是否可自动恢复收件箱 ID 撞车消息静默丢弃否——数据丢失且无感知分叉继承残缺历史子会话读到无结果的工具调用部分——靠新上下文重跑但语义已错grace 竞态工具结果迟到一整轮是——模型会收到后续结果只是延迟LLM 超时重试轮次/响应错配是——靠恢复重放 幂等兜底远程取消结果未知沙箱状态污染否——污染发生在 harness 视野之外最致命的是坑一收件箱 ID 撞车。因为它把幂等的语义建立在调用方契约上而契约一旦被违反失败是静默的、不可感知的、且不留给恢复机制任何把柄。分叉缺陷虽然语义上很扎眼源码里挂着 FIXME但至少测试覆盖了 10 种组合、失败模式可观测收件箱的 ID 撞车则连错误日志都不会有。次致命的是坑五远程沙箱取消后结果未知直接让操作状态与真实世界状态永久性分叉而分叉发生在 harness 的可见范围之外。规避方案按投入产出比排序ID 纪律所有 Input 与 Operation 的 ID 必须由调用方生成、UUID 级唯一、跨重试稳定并在测试里显式断言同一 ID 投递两次只处理一次harness/inbox/local_test.go 的用例方向。分叉前收敛fork 之前先StopWhenIdle让父会话把 in-flight 工具收尾避免把无结果工具调用带入子会话对 fork 出的子会话单独做一轮上下文压缩切断对父会话 in-flight 状态的依赖。正视 grace 的语义不要把工具结果到达时间当作确定性事件对结果迟到敏感的业务用ToolHeartbeatInterval让模型持续感知工具仍在运行而不是靠人工判断卡死。超时重试分层LLM 请求超时后放弃 HTTP 级重试直接终止轮次、交给会话恢复Resume重放所有自定义 Operation 必须填充Idempotency数据并保证相同幂等键只执行一次副作用。远程执行给不确定结果留出口远程任务取消失败时把 Operation 标记为未知而非失败并让上层策略决定是重试还是终止整个会话——永远不要假定远程沙箱是幂等的。async-first 的真正门槛不在把工具调用变成异步而在于把每一次不确定都变成可恢复的确定。Unreal Agent 用 Append-Only 会话账本、幂等收件箱和可序列化的 Operation 搭建了这套恢复框架但它的每一个组件都要求使用者理解并遵守底层契约——这正是排雷的本质不是修 bug而是驯服不确定性。【免费下载链接】unreal-agentAsync-first agent harness项目地址: https://gitcode.com/gh_mirrors/un/unreal-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考