1. 从 v1 到 v2opencode 这次架构调整到底在解决什么问题如果你最近在折腾 opencode大概率已经注意到 v2 的架构路线图里反复出现三个词Effect 原生 Agent 循环、session_input 收件箱、EventV2 事件核心。这三个东西不是三个独立的功能点而是同一套架构思路的三个切面。我先把结论摆出来v2 的核心目标是把 opencode 从一个能跑 Agent 的工具改造成一个事件驱动、可恢复、可观测的 Agent 运行时。v1 时代最让人头疼的是什么我自己的体感是三点。第一Agent 循环和 UI 状态耦合太紧一旦会话中断或者进程重启之前跑到哪一步基本靠猜。第二输入处理是同步阻塞的用户在 Agent 执行过程中想插一句话、想追加一个文件、想取消当前任务体验很割裂。第三事件系统是事后补丁式的日志、状态、UI 更新各走各的通道排查问题时要在好几个地方对时间线。v2 的路线图本质上是在回答一个问题当 Agent 不再是一次性的问答而是一个长时间运行、可能被中断、可能被并发输入、需要被审计的进程时它的内核应该长什么样Effect 负责把副作用和并发语义收进类型系统session_input 收件箱负责把输入从函数调用变成消息投递EventV2 负责把整个运行时的状态变化统一成一条可订阅的事件流。三者合起来就是一套 Agent 运行时的骨架。这篇文章适合两类人看。一类是正在用 opencode 做实际开发、想搞清楚 v2 升级后自己的配置和 skill 会不会受影响的人另一类是自己写 Agent 框架、想借鉴这套设计思路的人。我会尽量把每个设计决策背后的为什么讲清楚而不是只罗列 API。2. Effect 原生 Agent 循环把副作用关进类型系统2.1 为什么是 Effect而不是继续用 Promise 和 async/await先说一个很多人会问的问题Agent 循环用 async/await 不是挺好吗为什么要引入 Effect 这种带运行时的心智负担关键在于 Agent 循环的本质不是一次异步调用而是一个带取消、带重试、带资源清理、带并发限制的长生命周期流程。用 async/await 写这种流程你会遇到几个绕不过去的坑取消语义不统一。AbortController 能取消 fetch但取消不了你自己写的重试逻辑也取消不了已经进入队列的工具调用。资源清理靠 finally。一旦有嵌套的并发分支finally 的执行顺序和时机就变得很难推理。错误类型丢失。Promise 的 reject 是一个 unknown你在上层根本不知道这个错误是模型返回格式错误还是工具执行超时还是用户主动取消。Effect 的价值在于它把这些东西变成了一等公民。一个 Effect 描述的是一个可能失败、可能被中断、需要资源、可能并发的计算而不是一个已经发出去的 Promise。这意味着 Agent 循环可以在真正执行之前被组合、被拦截、被重试策略包裹而不需要把重试逻辑散落在每个 await 周围。我举个具体的对比。v1 里处理工具调用失败后重试大概是这样的思路在调用点包一层 try/catch判断错误类型决定要不要重试重试几次每次之间 sleep 多久。这段逻辑如果要在十个工具上复用要么抽函数要么复制粘贴。而在 Effect 里重试是一个组合子const callTool (tool: Tool, input: unknown) Effect.tryPromise({ try: () tool.execute(input), catch: (e) new ToolError({ tool: tool.name, cause: e }), }).pipe( Effect.retry(Schedule.exponential(200 millis).pipe( Schedule.compose(Schedule.recurs(3)) )), Effect.timeout(30 seconds), );这段代码描述的是这个工具调用最多重试三次、指数退避、整体超时 30 秒但它本身不执行。你可以把它塞进更大的循环里也可以给它加日志、加指标、加熔断全部通过 pipe 组合。这就是原生的含义——Agent 循环的每一步都是 Effect而不是 Effect 被包在 async 函数里。2.2 Agent 循环的状态机长什么样v2 的 Agent 循环我理解成一个显式状态机而不是 v1 那种while(true) 里调模型的隐式循环。核心状态大致是这几个状态含义可能的下一状态Idle等待输入ThinkingThinking模型推理中ToolCall / Responding / FailedToolCall执行工具Thinking回填结果Responding输出最终回复IdleFailed不可恢复错误Idle等待新输入Cancelled被中断Idle这个状态机的好处是每一步转移都可以被事件化。EventV2 订阅的就是这些转移UI 渲染的也是这些转移。v1 里Agent 到底在干嘛这个问题之所以难回答就是因为状态藏在闭包和局部变量里外部看不见。v2 把它显式化了。还有一个细节值得说Thinking 到 ToolCall 的转移是可以并发的。模型一次可能返回多个工具调用v2 允许这些调用并行执行但结果回填必须按顺序。这里 Effect 的Effect.all配合{ concurrency: unbounded }或者指定并发数就能表达而回填顺序通过数组索引保证。如果用 Promise.all你得自己维护一个 index 到 result 的映射还要处理某个调用失败时其他调用怎么办——是全部取消还是等剩下的跑完。Effect 里这就是Effect.all的mode参数语义清晰。2.3 中断与恢复Agent 循环最容易被低估的部分我在实际使用中最看重的一点是中断后的恢复能力。设想一个场景Agent 正在执行一个耗时很长的工具调用用户按了 CtrlC或者进程因为某种原因退出了。v1 的做法基本是这次会话就废了你得重新描述需求。v2 的路线图里Agent 循环的每一步都会把状态写入 session恢复时从最后一个持久化的状态继续。这里的关键设计是状态快照的粒度。如果每执行一个工具就快照一次开销太大如果只在会话结束时快照中断就丢状态。v2 的选择我理解是在状态转移的边界上快照也就是 Idle→Thinking、Thinking→ToolCall 这些点。工具执行本身是幂等的话恢复时重新执行一次也没问题不幂等的话需要在工具层面标记恢复时跳过已经成功的那次。提示如果你自己写工具尽量让工具执行幂等或者在工具描述里明确标注副作用。这直接决定了 Agent 中断恢复后会不会重复扣款、重复发消息这类问题。Effect 在这里的作用是中断传播。当一个 Effect 被中断时它会沿着组合链向上传播所有已经获取的资源会按获取的逆序释放。这意味着 Agent 循环被中断时不会留下工具执行到一半、连接没关、锁没释放的中间态。这是 async/await 很难保证的因为 Promise 一旦发出就无法撤回。3. session_input 收件箱把输入从函数调用变成消息投递3.1 为什么需要收件箱这个抽象v1 里用户输入的处理路径很直接UI 拿到输入调用 Agent 的 run 方法run 方法把输入拼进 prompt发给模型。这条路径在一问一答场景下没问题但一旦 Agent 在长时间运行问题就来了用户在 Agent 执行过程中想追加一句顺便把测试也改了v1 要么忽略要么打断当前执行重新开始。多个来源的输入键盘、文件监听、定时任务、其他 Agent想同时喂给同一个会话没有统一的入口。输入需要排队、需要去重、需要优先级v1 没有地方放这些逻辑。session_input 收件箱就是把输入从一次函数调用变成一个有队列语义的消息通道。所有输入先进入收件箱Agent 循环在合适的时机从收件箱取消息。这个合适的时机通常是当前 Thinking 或 ToolCall 完成、准备进入下一轮的时候。这个设计带来的直接好处是输入不再打断执行。用户可以在 Agent 跑工具的时候追加需求这条需求会排在收件箱里等当前这轮结束再被处理。体验上就是我说的话它听到了只是等它忙完这步再回应而不是我说的话把它的思路打断了。3.2 收件箱的消息模型与优先级收件箱里的消息我理解至少有这么几类UserMessage用户直接输入的内容优先级中等。SystemMessage系统注入的提示比如当前目录变了、某个文件被外部修改了优先级较高。CancelSignal取消当前执行的信号优先级最高需要立即处理。ToolResult工具执行结果回填这个其实可以不走收件箱直接进 Agent 循环但走收件箱能让整个流程更统一。优先级的意义在于当多个消息同时到达时谁先被处理。CancelSignal 必须最先因为它决定了后续消息还有没有意义。SystemMessage 次之因为它可能改变 Agent 对环境的认知。UserMessage 最后因为它是新任务可以等当前任务收尾。这里有个容易踩的坑收件箱的背压。如果 Agent 执行很慢用户疯狂输入收件箱会堆积。v2 需要有一个策略要么限制队列长度要么合并同类消息要么给用户反馈你的消息已排队前面还有 N 条。我倾向于限制长度加合并因为无限队列最终会 OOM而直接丢弃用户输入体验太差。3.3 收件箱与 Agent 循环的交互点收件箱不是独立于 Agent 循环的它和循环的交互点设计得好不好直接决定了整个运行时的响应性。我理解 v2 的交互点有这么几个循环开始前从收件箱取一批消息合并成初始上下文。每轮 Thinking 结束后检查收件箱有没有 CancelSignal有就中断。ToolCall 全部完成后、下一轮 Thinking 前取新消息决定是继续当前任务还是切换任务。循环进入 Idle 时阻塞等待收件箱有新消息。第 3 点是设计上最微妙的地方。如果收件箱里有新消息Agent 是应该先处理完当前任务再处理新消息还是立即切换我的经验是默认不切换因为用户追加的消息往往是补充说明不是新任务。但如果消息里明确带了停止、取消、换个方向这类意图就应该切换。这个判断可以交给模型做也可以用一个轻量的意图分类器。注意收件箱的取消息操作必须是原子的否则并发场景下会出现同一条消息被两个循环分支取走的情况。Effect 的Queue或者Ref配合STM能保证这一点自己用数组加锁很容易写错。4. EventV2 事件核心让运行时状态变成一条可订阅的流4.1 v1 事件系统的三个痛点在讲 EventV2 之前先说说 v1 的事件系统为什么需要重做。我总结下来是三个痛点第一事件类型不统一。日志是一种事件UI 状态更新是一种事件Agent 状态转移又是一种事件但它们走的是不同的通道。排查一个问题时你要在日志文件、UI 状态树、Agent 内部状态三个地方对时间线非常痛苦。第二事件没有 schema。v1 的事件很多是{ type: string, payload: any }消费方要自己判断 payload 长什么样。一旦生产方改了字段消费方在运行时才炸。第三事件没有回放能力。事件发出去就没了想复现一个 bug 只能靠日志而日志往往不完整。EventV2 的目标就是解决这三点统一类型、强 schema、可回放。4.2 EventV2 的事件分类与 schema 设计我理解 EventV2 把事件分成几个大类每类有自己的 schema事件类别代表事件消费方Session 生命周期SessionCreated, SessionArchived存储层、UIAgent 状态AgentStateChanged, AgentFailedUI、监控模型交互ModelRequested, ModelResponded日志、成本统计工具调用ToolInvoked, ToolCompleted, ToolFailedUI、审计输入InputEnqueued, InputDequeuedUI、调试错误ErrorRaised, ErrorRecovered监控、告警每个事件都有明确的字段定义用 TypeScript 的 discriminated union 表达。消费方通过switch (event.type)就能穷尽所有情况编译器会帮你检查有没有漏掉分支。这一点比 v1 的anypayload 强太多。schema 的另一个好处是跨版本兼容。v2 的事件可以带一个version字段消费方根据版本决定怎么解析。这样即使事件结构演进了老消费方也不会直接崩。4.3 事件回放调试 Agent 的杀手锏EventV2 最让我兴奋的能力是回放。因为所有状态变化都是事件理论上只要把事件流按顺序重放就能复现任意一个历史会话的完整过程。这对调试 Agent 太重要了。设想一个场景用户报告Agent 在某个任务上卡住了。v1 时代你只能看日志猜。v2 时代你可以把那个会话的事件流拉出来在本地重放一步步看 Agent 在哪个状态、收到了什么输入、做了什么决策。如果事件流里还记录了模型的原始响应你甚至能复现模型的思考过程。回放的实现要点是事件必须自包含。也就是说一个事件不能依赖外部可变状态才能被理解。比如 ToolCompleted 事件里要带上工具名、输入、输出、耗时而不是只带一个 toolId 让消费方去查。这样回放时不需要重建整个运行时环境。提示事件流会很大尤其是模型交互事件。生产环境要考虑采样和归档策略比如只保留最近 N 天的完整事件更早的只保留摘要。opencode 归档后去哪了这个问题本质上就是事件流的生命周期管理。4.4 事件与 Effect 的结合点EventV2 和 Effect 不是两套独立的东西它们有明确的结合点。Effect 提供了Effect.tap、Effect.onInterrupt、Effect.onError这些组合子可以在不改变计算逻辑的前提下插入副作用。事件发射就是典型的副作用const thinking (context: Context) callModel(context).pipe( Effect.tap((response) emitEvent({ type: ModelResponded, response, at: Date.now() }) ), Effect.onError((error) emitEvent({ type: ErrorRaised, error, at: Date.now() }) ), Effect.onInterrupt(() emitEvent({ type: AgentCancelled, at: Date.now() }) ), );这样事件发射就和业务逻辑解耦了。业务代码只管计算事件由组合子负责。而且因为 Effect 的中断语义是可靠的onInterrupt一定会被调用不会出现取消了但没记录的情况。5. 三个组件如何咬合一次完整请求的生命周期光讲三个组件各自的设计还不够得看它们怎么协同。我拿一次典型的用户提问 → Agent 执行 → 返回结果来串一遍。第一步输入入队。用户在 UI 输入问题UI 构造一个 UserMessage投递到 session_input 收件箱。同时 EventV2 发出 InputEnqueued 事件UI 可以据此显示消息已发送。第二步循环取消息。Agent 循环处于 Idle 状态阻塞等待收件箱。收到消息后发出 InputDequeued 事件状态转移到 Thinking发出 AgentStateChanged 事件。第三步模型推理。循环调用模型发出 ModelRequested 事件。模型返回后发出 ModelResponded 事件。如果返回的是工具调用状态转移到 ToolCall。第四步工具执行。每个工具调用是一个 Effect可以并发。执行前发 ToolInvoked执行后发 ToolCompleted 或 ToolFailed。所有工具完成后状态回到 Thinking把结果回填给模型。第五步循环判断。每轮 Thinking 结束后循环检查收件箱有没有 CancelSignal。有就中断发 AgentCancelled。没有就继续直到模型返回最终回复。第六步输出与归位。模型返回最终回复状态转移到 Responding输出给 UI然后回到 Idle等待下一条消息。整个过程中EventV2 是唯一的真相来源。UI 不直接读 Agent 内部状态而是订阅事件流根据事件更新自己的渲染。这样 UI 和 Agent 内核彻底解耦甚至可以把 UI 换成 CLI、换成 Web、换成别的什么只要它能消费事件流。这里有个设计上的取舍值得说事件是同步发还是异步发。同步发的话事件消费方的处理会阻塞 Agent 循环异步发的话事件可能乱序或者丢失。v2 我理解是同步发到内存队列异步刷到持久化存储。这样 Agent 循环只承担入队开销持久化的延迟不影响执行但事件顺序在内存队列里是保证的。6. 迁移到 v2 时我踩过的坑和给你的建议6.1 配置和 skill 的兼容性v2 架构调整后最直接的影响是配置结构。v1 的配置里很多字段是平铺的v2 因为引入了收件箱和事件系统配置需要分层。我升级时遇到的第一个坑就是老的 skill 配置在 v2 下不生效因为 skill 的触发时机从输入到达时变成了消息从收件箱取出时。如果你有自定义 skill需要检查两点一是 skill 的触发条件是不是依赖了 v1 的同步输入语义二是 skill 里如果有长时间运行的操作要考虑它会不会阻塞收件箱的消费。我的建议是把 skill 里的耗时操作改成 Effect这样它能被中断、能被事件化和 v2 的运行时语义一致。6.2 免费额度和 provider 相关的报错热词里有个报错很典型error from provider (console): opencodes free tier can only be used from within opencode。这个错误的本质是免费额度的使用场景限制。免费模型通常只允许在 opencode 自身的运行时里调用如果你通过其他方式比如自己写的脚本、第三方客户端去调就会被拒绝。这个限制和 v2 架构没有直接关系但 v2 的事件系统让这个错误的可观测性变好了。以前你只看到一个报错字符串现在 EventV2 会发出 ErrorRaised 事件带上 provider、model、调用来源这些字段排查起来清楚很多。如果你遇到这个错误先确认调用是不是发生在 opencode 运行时内部而不是外部脚本。6.3 Agent 执行被终止的排查思路agent execution terminated due to error这个报错在 v2 下有了更清晰的排查路径。我的排查顺序是先看 EventV2 的事件流找到最后一个 AgentStateChanged 事件确认终止发生在哪个状态。看这个状态之前有没有 ErrorRaised 事件有的话看 error 的 cause 链。如果是 ToolCall 状态终止看对应的 ToolFailed 事件确认是工具本身失败还是超时。如果是 Thinking 状态终止看 ModelResponded 事件确认模型返回是否符合预期格式。如果事件流里什么都没有那可能是进程级的问题看系统日志。这个顺序比 v1 时代看日志猜高效太多因为事件流本身就是结构化的排查线索。6.4 关于 Agent 记忆和安全的思考热词里出现了 agent 记忆、agent 安全、a-memguard 这些词说明大家开始关注 Agent 长期运行带来的问题。v2 的 session_input 收件箱和 EventV2 其实为记忆和安全提供了基础设施收件箱是记忆的入口事件流是记忆的载体。但基础设施不等于解决方案。我自己的做法是在收件箱层面做输入过滤把明显不安全的输入挡在 Agent 循环之外在事件流层面做审计所有工具调用和模型交互都有记录出问题能追溯。至于记忆的长期存储和检索那是另一个话题v2 的架构至少让这件事变得可行因为状态是显式的、可序列化的。注意事件流里可能包含敏感信息比如用户输入、文件内容、模型响应。持久化事件流时要做脱敏或者加密别把事件存储变成新的泄露点。7. 我对这套架构的个人判断用了一段时间 v2 之后我最大的感受是它把 Agent 从脚本变成了系统。v1 的 Agent 更像一个写得比较长的脚本能跑但边界模糊、状态隐式、出错难查。v2 的 Agent 是一个有明确状态机、有输入队列、有事件总线的系统每个部分职责清晰可以独立测试、独立替换。Effect 的引入是有学习成本的我一开始也觉得不就是个 Agent 循环吗至于上这么重的东西吗。但当我真正需要处理中断恢复、并发工具调用、资源清理这些场景时Effect 的组合子确实比手写 async/await 省心。尤其是中断传播自己实现很容易漏掉边界情况。session_input 收件箱是我最喜欢的设计。它让边跑边聊成为可能而不是要么等它跑完要么打断它重来。这个体验上的差异用过就回不去了。EventV2 的价值会随着时间显现。现在你可能只觉得它是个更好的日志系统但当你要做 Agent 评估、要做成本分析、要做故障复现时一条完整的事件流就是最宝贵的资产。如果你正在考虑迁移到 v2我的建议是先从小范围开始挑一个不关键的项目试水把配置和 skill 的兼容性问题暴露出来再逐步铺开。架构升级的红利是长期的但迁移的阵痛是短期的别一次性全切。 opencode v2 架构解析：Effect Agent 循环、session_input 收件箱与 EventV2 事件核心
1. 从 v1 到 v2opencode 这次架构调整到底在解决什么问题如果你最近在折腾 opencode大概率已经注意到 v2 的架构路线图里反复出现三个词Effect 原生 Agent 循环、session_input 收件箱、EventV2 事件核心。这三个东西不是三个独立的功能点而是同一套架构思路的三个切面。我先把结论摆出来v2 的核心目标是把 opencode 从一个能跑 Agent 的工具改造成一个事件驱动、可恢复、可观测的 Agent 运行时。v1 时代最让人头疼的是什么我自己的体感是三点。第一Agent 循环和 UI 状态耦合太紧一旦会话中断或者进程重启之前跑到哪一步基本靠猜。第二输入处理是同步阻塞的用户在 Agent 执行过程中想插一句话、想追加一个文件、想取消当前任务体验很割裂。第三事件系统是事后补丁式的日志、状态、UI 更新各走各的通道排查问题时要在好几个地方对时间线。v2 的路线图本质上是在回答一个问题当 Agent 不再是一次性的问答而是一个长时间运行、可能被中断、可能被并发输入、需要被审计的进程时它的内核应该长什么样Effect 负责把副作用和并发语义收进类型系统session_input 收件箱负责把输入从函数调用变成消息投递EventV2 负责把整个运行时的状态变化统一成一条可订阅的事件流。三者合起来就是一套 Agent 运行时的骨架。这篇文章适合两类人看。一类是正在用 opencode 做实际开发、想搞清楚 v2 升级后自己的配置和 skill 会不会受影响的人另一类是自己写 Agent 框架、想借鉴这套设计思路的人。我会尽量把每个设计决策背后的为什么讲清楚而不是只罗列 API。2. Effect 原生 Agent 循环把副作用关进类型系统2.1 为什么是 Effect而不是继续用 Promise 和 async/await先说一个很多人会问的问题Agent 循环用 async/await 不是挺好吗为什么要引入 Effect 这种带运行时的心智负担关键在于 Agent 循环的本质不是一次异步调用而是一个带取消、带重试、带资源清理、带并发限制的长生命周期流程。用 async/await 写这种流程你会遇到几个绕不过去的坑取消语义不统一。AbortController 能取消 fetch但取消不了你自己写的重试逻辑也取消不了已经进入队列的工具调用。资源清理靠 finally。一旦有嵌套的并发分支finally 的执行顺序和时机就变得很难推理。错误类型丢失。Promise 的 reject 是一个 unknown你在上层根本不知道这个错误是模型返回格式错误还是工具执行超时还是用户主动取消。Effect 的价值在于它把这些东西变成了一等公民。一个 Effect 描述的是一个可能失败、可能被中断、需要资源、可能并发的计算而不是一个已经发出去的 Promise。这意味着 Agent 循环可以在真正执行之前被组合、被拦截、被重试策略包裹而不需要把重试逻辑散落在每个 await 周围。我举个具体的对比。v1 里处理工具调用失败后重试大概是这样的思路在调用点包一层 try/catch判断错误类型决定要不要重试重试几次每次之间 sleep 多久。这段逻辑如果要在十个工具上复用要么抽函数要么复制粘贴。而在 Effect 里重试是一个组合子const callTool (tool: Tool, input: unknown) Effect.tryPromise({ try: () tool.execute(input), catch: (e) new ToolError({ tool: tool.name, cause: e }), }).pipe( Effect.retry(Schedule.exponential(200 millis).pipe( Schedule.compose(Schedule.recurs(3)) )), Effect.timeout(30 seconds), );这段代码描述的是这个工具调用最多重试三次、指数退避、整体超时 30 秒但它本身不执行。你可以把它塞进更大的循环里也可以给它加日志、加指标、加熔断全部通过 pipe 组合。这就是原生的含义——Agent 循环的每一步都是 Effect而不是 Effect 被包在 async 函数里。2.2 Agent 循环的状态机长什么样v2 的 Agent 循环我理解成一个显式状态机而不是 v1 那种while(true) 里调模型的隐式循环。核心状态大致是这几个状态含义可能的下一状态Idle等待输入ThinkingThinking模型推理中ToolCall / Responding / FailedToolCall执行工具Thinking回填结果Responding输出最终回复IdleFailed不可恢复错误Idle等待新输入Cancelled被中断Idle这个状态机的好处是每一步转移都可以被事件化。EventV2 订阅的就是这些转移UI 渲染的也是这些转移。v1 里Agent 到底在干嘛这个问题之所以难回答就是因为状态藏在闭包和局部变量里外部看不见。v2 把它显式化了。还有一个细节值得说Thinking 到 ToolCall 的转移是可以并发的。模型一次可能返回多个工具调用v2 允许这些调用并行执行但结果回填必须按顺序。这里 Effect 的Effect.all配合{ concurrency: unbounded }或者指定并发数就能表达而回填顺序通过数组索引保证。如果用 Promise.all你得自己维护一个 index 到 result 的映射还要处理某个调用失败时其他调用怎么办——是全部取消还是等剩下的跑完。Effect 里这就是Effect.all的mode参数语义清晰。2.3 中断与恢复Agent 循环最容易被低估的部分我在实际使用中最看重的一点是中断后的恢复能力。设想一个场景Agent 正在执行一个耗时很长的工具调用用户按了 CtrlC或者进程因为某种原因退出了。v1 的做法基本是这次会话就废了你得重新描述需求。v2 的路线图里Agent 循环的每一步都会把状态写入 session恢复时从最后一个持久化的状态继续。这里的关键设计是状态快照的粒度。如果每执行一个工具就快照一次开销太大如果只在会话结束时快照中断就丢状态。v2 的选择我理解是在状态转移的边界上快照也就是 Idle→Thinking、Thinking→ToolCall 这些点。工具执行本身是幂等的话恢复时重新执行一次也没问题不幂等的话需要在工具层面标记恢复时跳过已经成功的那次。提示如果你自己写工具尽量让工具执行幂等或者在工具描述里明确标注副作用。这直接决定了 Agent 中断恢复后会不会重复扣款、重复发消息这类问题。Effect 在这里的作用是中断传播。当一个 Effect 被中断时它会沿着组合链向上传播所有已经获取的资源会按获取的逆序释放。这意味着 Agent 循环被中断时不会留下工具执行到一半、连接没关、锁没释放的中间态。这是 async/await 很难保证的因为 Promise 一旦发出就无法撤回。3. session_input 收件箱把输入从函数调用变成消息投递3.1 为什么需要收件箱这个抽象v1 里用户输入的处理路径很直接UI 拿到输入调用 Agent 的 run 方法run 方法把输入拼进 prompt发给模型。这条路径在一问一答场景下没问题但一旦 Agent 在长时间运行问题就来了用户在 Agent 执行过程中想追加一句顺便把测试也改了v1 要么忽略要么打断当前执行重新开始。多个来源的输入键盘、文件监听、定时任务、其他 Agent想同时喂给同一个会话没有统一的入口。输入需要排队、需要去重、需要优先级v1 没有地方放这些逻辑。session_input 收件箱就是把输入从一次函数调用变成一个有队列语义的消息通道。所有输入先进入收件箱Agent 循环在合适的时机从收件箱取消息。这个合适的时机通常是当前 Thinking 或 ToolCall 完成、准备进入下一轮的时候。这个设计带来的直接好处是输入不再打断执行。用户可以在 Agent 跑工具的时候追加需求这条需求会排在收件箱里等当前这轮结束再被处理。体验上就是我说的话它听到了只是等它忙完这步再回应而不是我说的话把它的思路打断了。3.2 收件箱的消息模型与优先级收件箱里的消息我理解至少有这么几类UserMessage用户直接输入的内容优先级中等。SystemMessage系统注入的提示比如当前目录变了、某个文件被外部修改了优先级较高。CancelSignal取消当前执行的信号优先级最高需要立即处理。ToolResult工具执行结果回填这个其实可以不走收件箱直接进 Agent 循环但走收件箱能让整个流程更统一。优先级的意义在于当多个消息同时到达时谁先被处理。CancelSignal 必须最先因为它决定了后续消息还有没有意义。SystemMessage 次之因为它可能改变 Agent 对环境的认知。UserMessage 最后因为它是新任务可以等当前任务收尾。这里有个容易踩的坑收件箱的背压。如果 Agent 执行很慢用户疯狂输入收件箱会堆积。v2 需要有一个策略要么限制队列长度要么合并同类消息要么给用户反馈你的消息已排队前面还有 N 条。我倾向于限制长度加合并因为无限队列最终会 OOM而直接丢弃用户输入体验太差。3.3 收件箱与 Agent 循环的交互点收件箱不是独立于 Agent 循环的它和循环的交互点设计得好不好直接决定了整个运行时的响应性。我理解 v2 的交互点有这么几个循环开始前从收件箱取一批消息合并成初始上下文。每轮 Thinking 结束后检查收件箱有没有 CancelSignal有就中断。ToolCall 全部完成后、下一轮 Thinking 前取新消息决定是继续当前任务还是切换任务。循环进入 Idle 时阻塞等待收件箱有新消息。第 3 点是设计上最微妙的地方。如果收件箱里有新消息Agent 是应该先处理完当前任务再处理新消息还是立即切换我的经验是默认不切换因为用户追加的消息往往是补充说明不是新任务。但如果消息里明确带了停止、取消、换个方向这类意图就应该切换。这个判断可以交给模型做也可以用一个轻量的意图分类器。注意收件箱的取消息操作必须是原子的否则并发场景下会出现同一条消息被两个循环分支取走的情况。Effect 的Queue或者Ref配合STM能保证这一点自己用数组加锁很容易写错。4. EventV2 事件核心让运行时状态变成一条可订阅的流4.1 v1 事件系统的三个痛点在讲 EventV2 之前先说说 v1 的事件系统为什么需要重做。我总结下来是三个痛点第一事件类型不统一。日志是一种事件UI 状态更新是一种事件Agent 状态转移又是一种事件但它们走的是不同的通道。排查一个问题时你要在日志文件、UI 状态树、Agent 内部状态三个地方对时间线非常痛苦。第二事件没有 schema。v1 的事件很多是{ type: string, payload: any }消费方要自己判断 payload 长什么样。一旦生产方改了字段消费方在运行时才炸。第三事件没有回放能力。事件发出去就没了想复现一个 bug 只能靠日志而日志往往不完整。EventV2 的目标就是解决这三点统一类型、强 schema、可回放。4.2 EventV2 的事件分类与 schema 设计我理解 EventV2 把事件分成几个大类每类有自己的 schema事件类别代表事件消费方Session 生命周期SessionCreated, SessionArchived存储层、UIAgent 状态AgentStateChanged, AgentFailedUI、监控模型交互ModelRequested, ModelResponded日志、成本统计工具调用ToolInvoked, ToolCompleted, ToolFailedUI、审计输入InputEnqueued, InputDequeuedUI、调试错误ErrorRaised, ErrorRecovered监控、告警每个事件都有明确的字段定义用 TypeScript 的 discriminated union 表达。消费方通过switch (event.type)就能穷尽所有情况编译器会帮你检查有没有漏掉分支。这一点比 v1 的anypayload 强太多。schema 的另一个好处是跨版本兼容。v2 的事件可以带一个version字段消费方根据版本决定怎么解析。这样即使事件结构演进了老消费方也不会直接崩。4.3 事件回放调试 Agent 的杀手锏EventV2 最让我兴奋的能力是回放。因为所有状态变化都是事件理论上只要把事件流按顺序重放就能复现任意一个历史会话的完整过程。这对调试 Agent 太重要了。设想一个场景用户报告Agent 在某个任务上卡住了。v1 时代你只能看日志猜。v2 时代你可以把那个会话的事件流拉出来在本地重放一步步看 Agent 在哪个状态、收到了什么输入、做了什么决策。如果事件流里还记录了模型的原始响应你甚至能复现模型的思考过程。回放的实现要点是事件必须自包含。也就是说一个事件不能依赖外部可变状态才能被理解。比如 ToolCompleted 事件里要带上工具名、输入、输出、耗时而不是只带一个 toolId 让消费方去查。这样回放时不需要重建整个运行时环境。提示事件流会很大尤其是模型交互事件。生产环境要考虑采样和归档策略比如只保留最近 N 天的完整事件更早的只保留摘要。opencode 归档后去哪了这个问题本质上就是事件流的生命周期管理。4.4 事件与 Effect 的结合点EventV2 和 Effect 不是两套独立的东西它们有明确的结合点。Effect 提供了Effect.tap、Effect.onInterrupt、Effect.onError这些组合子可以在不改变计算逻辑的前提下插入副作用。事件发射就是典型的副作用const thinking (context: Context) callModel(context).pipe( Effect.tap((response) emitEvent({ type: ModelResponded, response, at: Date.now() }) ), Effect.onError((error) emitEvent({ type: ErrorRaised, error, at: Date.now() }) ), Effect.onInterrupt(() emitEvent({ type: AgentCancelled, at: Date.now() }) ), );这样事件发射就和业务逻辑解耦了。业务代码只管计算事件由组合子负责。而且因为 Effect 的中断语义是可靠的onInterrupt一定会被调用不会出现取消了但没记录的情况。5. 三个组件如何咬合一次完整请求的生命周期光讲三个组件各自的设计还不够得看它们怎么协同。我拿一次典型的用户提问 → Agent 执行 → 返回结果来串一遍。第一步输入入队。用户在 UI 输入问题UI 构造一个 UserMessage投递到 session_input 收件箱。同时 EventV2 发出 InputEnqueued 事件UI 可以据此显示消息已发送。第二步循环取消息。Agent 循环处于 Idle 状态阻塞等待收件箱。收到消息后发出 InputDequeued 事件状态转移到 Thinking发出 AgentStateChanged 事件。第三步模型推理。循环调用模型发出 ModelRequested 事件。模型返回后发出 ModelResponded 事件。如果返回的是工具调用状态转移到 ToolCall。第四步工具执行。每个工具调用是一个 Effect可以并发。执行前发 ToolInvoked执行后发 ToolCompleted 或 ToolFailed。所有工具完成后状态回到 Thinking把结果回填给模型。第五步循环判断。每轮 Thinking 结束后循环检查收件箱有没有 CancelSignal。有就中断发 AgentCancelled。没有就继续直到模型返回最终回复。第六步输出与归位。模型返回最终回复状态转移到 Responding输出给 UI然后回到 Idle等待下一条消息。整个过程中EventV2 是唯一的真相来源。UI 不直接读 Agent 内部状态而是订阅事件流根据事件更新自己的渲染。这样 UI 和 Agent 内核彻底解耦甚至可以把 UI 换成 CLI、换成 Web、换成别的什么只要它能消费事件流。这里有个设计上的取舍值得说事件是同步发还是异步发。同步发的话事件消费方的处理会阻塞 Agent 循环异步发的话事件可能乱序或者丢失。v2 我理解是同步发到内存队列异步刷到持久化存储。这样 Agent 循环只承担入队开销持久化的延迟不影响执行但事件顺序在内存队列里是保证的。6. 迁移到 v2 时我踩过的坑和给你的建议6.1 配置和 skill 的兼容性v2 架构调整后最直接的影响是配置结构。v1 的配置里很多字段是平铺的v2 因为引入了收件箱和事件系统配置需要分层。我升级时遇到的第一个坑就是老的 skill 配置在 v2 下不生效因为 skill 的触发时机从输入到达时变成了消息从收件箱取出时。如果你有自定义 skill需要检查两点一是 skill 的触发条件是不是依赖了 v1 的同步输入语义二是 skill 里如果有长时间运行的操作要考虑它会不会阻塞收件箱的消费。我的建议是把 skill 里的耗时操作改成 Effect这样它能被中断、能被事件化和 v2 的运行时语义一致。6.2 免费额度和 provider 相关的报错热词里有个报错很典型error from provider (console): opencodes free tier can only be used from within opencode。这个错误的本质是免费额度的使用场景限制。免费模型通常只允许在 opencode 自身的运行时里调用如果你通过其他方式比如自己写的脚本、第三方客户端去调就会被拒绝。这个限制和 v2 架构没有直接关系但 v2 的事件系统让这个错误的可观测性变好了。以前你只看到一个报错字符串现在 EventV2 会发出 ErrorRaised 事件带上 provider、model、调用来源这些字段排查起来清楚很多。如果你遇到这个错误先确认调用是不是发生在 opencode 运行时内部而不是外部脚本。6.3 Agent 执行被终止的排查思路agent execution terminated due to error这个报错在 v2 下有了更清晰的排查路径。我的排查顺序是先看 EventV2 的事件流找到最后一个 AgentStateChanged 事件确认终止发生在哪个状态。看这个状态之前有没有 ErrorRaised 事件有的话看 error 的 cause 链。如果是 ToolCall 状态终止看对应的 ToolFailed 事件确认是工具本身失败还是超时。如果是 Thinking 状态终止看 ModelResponded 事件确认模型返回是否符合预期格式。如果事件流里什么都没有那可能是进程级的问题看系统日志。这个顺序比 v1 时代看日志猜高效太多因为事件流本身就是结构化的排查线索。6.4 关于 Agent 记忆和安全的思考热词里出现了 agent 记忆、agent 安全、a-memguard 这些词说明大家开始关注 Agent 长期运行带来的问题。v2 的 session_input 收件箱和 EventV2 其实为记忆和安全提供了基础设施收件箱是记忆的入口事件流是记忆的载体。但基础设施不等于解决方案。我自己的做法是在收件箱层面做输入过滤把明显不安全的输入挡在 Agent 循环之外在事件流层面做审计所有工具调用和模型交互都有记录出问题能追溯。至于记忆的长期存储和检索那是另一个话题v2 的架构至少让这件事变得可行因为状态是显式的、可序列化的。注意事件流里可能包含敏感信息比如用户输入、文件内容、模型响应。持久化事件流时要做脱敏或者加密别把事件存储变成新的泄露点。7. 我对这套架构的个人判断用了一段时间 v2 之后我最大的感受是它把 Agent 从脚本变成了系统。v1 的 Agent 更像一个写得比较长的脚本能跑但边界模糊、状态隐式、出错难查。v2 的 Agent 是一个有明确状态机、有输入队列、有事件总线的系统每个部分职责清晰可以独立测试、独立替换。Effect 的引入是有学习成本的我一开始也觉得不就是个 Agent 循环吗至于上这么重的东西吗。但当我真正需要处理中断恢复、并发工具调用、资源清理这些场景时Effect 的组合子确实比手写 async/await 省心。尤其是中断传播自己实现很容易漏掉边界情况。session_input 收件箱是我最喜欢的设计。它让边跑边聊成为可能而不是要么等它跑完要么打断它重来。这个体验上的差异用过就回不去了。EventV2 的价值会随着时间显现。现在你可能只觉得它是个更好的日志系统但当你要做 Agent 评估、要做成本分析、要做故障复现时一条完整的事件流就是最宝贵的资产。如果你正在考虑迁移到 v2我的建议是先从小范围开始挑一个不关键的项目试水把配置和 skill 的兼容性问题暴露出来再逐步铺开。架构升级的红利是长期的但迁移的阵痛是短期的别一次性全切。