Agent 程序的三个韧性挑战

1. 错误信息给谁看？ —— 传统错误只给程序员，Agent 错误必须让 LLM 能读懂并自行修复。
2. 事件和状态怎么保持一致？ —— 数据库写入成功却未能成功发布事件，或相反导致程序状态不同步。
3. /timeout 怎么重试才安全？ —— 暴力重试会触发限流甚至封 IP，必须根据错误语义决定是否还有如何重试。

OpenCode 用以下 3 个设计模式应对：

模式 ：错误即反馈

源码位置

packages/llm/src/tool-runtime.ts。packages/llm/src/schema/errors.ts,packages/core/src/tool/…

痛点 🎯

传统的异常信息（如 Error: EACCES) 是为开发者准备的，而真正的“观众”是 LLM。若工具直接抛出异常，整个 Agent 循环会立刻中断。LLM 无法收到错误进行自我修复。

再看真实机制，不 throw。走 Effect 的失败通道 ✅

OpenCode 定义了结构化的错误类型 ToolFailure. 当工具出错时返回该对象，而不是抛异常； 运行时捕获后把它转换成 LLM 可消费的标准结果。

// packages/llm/src/schema/errors.ts
export class ToolFailure extends Schema.TaggedErrorClass(
"LLM.ToolFailure"。{
message: Schema.String,// 面向 LLM 的自然语言描述
error这方面，Schema.optional),// 原始异常
metadata: Schema.optional),},) {}
// 注释：Handlers 必须把内部错误映射到此形状；运行时会捕获 ToolFailure 并
// 将其作为 tool‑error event 返回，使模型能够自我纠正。除 ToolFailure 外的
// 抛出或 yield 将被视为 defect 并导致流失败。

运行时分发函数负责把缺失工具或缺少 execute 的情况直接返回 error，而不是抛异常：

// packages/llm/src/tool-runtime.ts
export const dispatch = => {
const tool = tools;if return Effect.succeed);if return Effect.succeed);return decodeAndExecute.pipe(
Effect.map),// 捕获 ToolFailure → 转成普通 error result。不炸流
Effect.catchTag("LLM.ToolFailure",failure =>
Effect.succeed)
),);}，

具体工具只需要把内部异常映射为 ToolFailure

// packages/core/src/tool/bash.ts
Effect.mapError => new ToolFailure)
// packages/core/src/tool/write.ts
Effect.mapError => new ToolFailure)

Python 等价实现:

class ToolFailure:
"""工具执行失败，但能被运行时吸收成返回值"""
def __init__:
self.message = message
def run_tool:
tool = tools.get
if tool is None:
return {"type": "error","value": f"Unknown tool: {name}"}
至于try，return tool.execute
except ToolFailure as failure:
# 捕获后转成正常返回值，不向上抛
return {"type": "error","value": failure.message}

再看设计约束，仅预期错误转为反馈 🚦

The comment in /packages/core/src/tool/AGENTS.md: only **typed**。**expected** errors should be wrapped into a ToolFailure.. Unanticipated defects must still bubble up so y are visible during debugging.

模式 ：事务内 commit 钩子

packages/core/src/event.ts,packages/core/src/session/context-epoch.ts

痛点 🎯​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​

​ ​ ​ ​ ​ ​
• 改数据库后再发事件，如果网络在发送阶段中断，则数据库已改但客户端收不到对应事件——产生数据不一致。
• 先发事件再改数据库。如果写库失败，则客户端已收到不存在的变更通知，一样导致不一致。
• 经典“双写”场景往往需要额外 “outbox” 表和后台轮询来保证最终一致性，这增加复杂度且仍有窗口期风险。