如果你要设计一个能从终端命令一路走到 AI Agent 循环的架构——用户敲一行opencode run fix this bug你的系统怎么把这个字符串变成一次完整的 LLM 推理你可能会想这有什么难的process.argv解析一下switch-case 分发函数里调 LLM完事。对但如果你的 CLI 有 20 个选项、3 种交互模式非交互/本地交互/远程附加、还需要加载完整的项目上下文配置、插件、Provider——switch-case 会在第 5 个选项时变成一团浆糊。opencode 的作者也经历了这个演变。前两篇拆了yargs 注册和bootstrap 初始化现在看它们怎么汇合成一条完整链路——从opencode到 Agent Loop。【问题】——为什么一个run命令需要三层路由naive 方案process.argv switch-case 的终点如果你只做一次 LLM 调用的确不需要三层。一个脚本就够了constargsprocess.argv.slice(2)if(args[0]run){constmessageargs.slice(1).join( )constresultawaitcallLLM(message)console.log(result)}这个方案在三个维度上同时失效。第一参数爆炸。opencode 的run命令有 20 选项--model、--agent、--interactive、--format json、--file、--continue、--session、--fork……每个选项有自己的类型、别名、默认值、互斥规则。手写解析器到第 5 个选项就开始出现undefined is not a function。相比之下yargs 的声明式路由把 20 选项每一行一个.option()搞定。第二生命周期。run需要一个完整的项目上下文——配置加载、插件初始化、Provider 注册。如果不加载LLM 调用连 API key 都找不到。如果加载完不释放下次启动内存泄漏。第三模式分裂。同一个run命令要同时支持非交互式发一条消息就退出、本地交互式开 TUI 持续对话、远程附加式连到已运行的 server。三种模式共享 80% 的 session 逻辑但输出处理和生命周期完全不同。三个人在三个 PR 里往同一个 switch-case 加代码——这就是 opencode 选择三层路由的直接原因。opencode 的选择CLI 层 → Effect 层 → Session 层的三层过滤三层不是拍脑袋分的每一层解决一个维度的问题层级文件职责解决 naive 的哪个痛点Layer 1: CLI 层src/index.tsyargs 声明式注册 参数解析“参数爆炸”——20 选项每行一个.option()Layer 2: Effect 层src/cli/effect-cmd.tsInstanceStore 加载 自动 dispose“生命周期”——Effect.ensuringEffect 的 finally 等效机制保证退出时执行清理兜底清理Layer 3: Session 层src/cli/cmd/run.tssession 创建 三叉戟执行“模式分裂”——非交互/交互/附加各自走不同路径这不是最优解——它多了一些间接层每层都有抽象成本。但它在可扩展性和正确性上赢回了这些成本。继续看每层的具体代码。【设计】——三层架构各层职责Layer 1yargs builder 声明式注册入口文件src/index.ts是这个 CLI 的路由表。45 行代码注册了 20 个命令每个命令一个.command()调用sources/opencode/packages/opencode/src/index.ts L45-116。如果你熟悉 02-01这里不加新东西。关键是第 85 行.command(RunCommand)——RunCommand不是普通 yargs 命令对象它是用effectCmd()包装过的。这里有一个容易忽略的设计细节.middleware()注册在全局cli上但它只在 yargs 完成参数解析之后执行。这意味着 middleware 可以读到所有 flag 的值。opencode 利用这一点在 middleware 里设置环境变量OPENCODE_PRINT_LOGS、OPENCODE_LOG_LEVEL确保这些配置在 handler 被调用之前就已生效。你可能会问既然.middleware能做到为什么不把 InstanceStore 加载也放进 middleware因为 middleware 无法被 effect-cmd 的finally覆盖——如果 middleware 里加载了 Instance 但 handler 抛异常没有Effect.ensuring兜底dispose 会漏掉。Layer 2effectCmd 包装器effectCmd是连接 yargs 世界和 Effect 世界的桥梁。它做的事可以用一句话说清帮你加载 InstanceContext然后调用你的 handler最后确保 dispose。sources/opencode/packages/opencode/src/cli/effect-cmd.ts L69-95这里的核心机制是instance选项。RunCommand是这样声明的instance:(args)!args.attach,--attach模式连接到远程服务器不需要本地 Instance。普通的opencode run则需要。这个条件写在effectCmd的配置里而不是在 handler 内部判断——因为 handler 类型签名需要InstanceRefEffect 上下文中的实例引用如果不加载实例handler 里的yield* InstanceRefEffect 的依赖获取语法类似 await 但用于 Effect 上下文会直接 defect。边界场景如果instance为 true 但store.load失败比如找不到项目目录effectCmd 不会调用 handler——错误直接冒泡到src/index.ts的 catch 块显示错误后 exit(1)。这比在每个 handler 里写 try-catch 更干净。Layer 3run handler 三叉戟RunCommand的 handler 是整个 CLI 最长的函数——约 650 行L241-893。但它不复杂只是因为处理了三种模式的排列组合。handler 的入口是Effect.fn(Cli.run)(function* (args) { ... })。Effect.fnEffect 的命名追踪机制类似给函数贴标签调试时一眼看出调用来源给函数加了一个命名 span在 Effect 追踪系统里显示为Cli.run——调试时看 tracing 一眼就能认出这是哪个命令。handler 的顶层逻辑是三个 if 分支构成三叉戟if(交互模式本地非继续)→ runInteractiveLocalMode()elseif(附加模式)→ execute(attachSDK)else(默认, 含非交互和交互继续)→ execute(localSDK)这个判断不是随意分的。sources/opencode/packages/opencode/src/cli/cmd/run.ts L837-893模式 A 是开新局——创建全新的交互式 session用 in-process server不走 HTTP通过 fetch function 直接调用 Server 的app.fetch。模式 B 和 C 都走execute()但区别是 SDK 绑定对象不同B 走 HTTPC 走 in-process。为什么模式 A 要单独抽出来因为runInteractiveLocalMode内部做了三件事启动 in-process ServerServer.Default()创建 session直接进入交互式 TUI而execute()的设计是先创建 session再根据参数决定怎么执行——它更通用但多了一个 session 创建→等待的步骤。纯--interactive场景下这个等待是多余的。【源码】——主流程三块骨架session 解析创建 / 继续 / forkexecute()的第一步是拿到一个 session ID。session()函数sources/opencode/packages/opencode/src/cli/cmd/run.ts L391-468处理了 7 种排列组合这里的fork是一个有意思的设计。它不是简单的复制 session而是创建一个新的空 session 但继承原 session 的 title 和 directory。目的是让你在同一个项目里开一个平行时空继续调试不影响之前的对话历史。naive 方案不会考虑 fork——因为单次 LLM 调用不需要。但 opencode 的目标是一个持续数小时的交互式 session用户可能需要回到上一个决策点重来。fork 就是这个重来机制的基础。执行分叉command / prompt / 交互想象你敲了opencode run --command /review。你期待的是直接执行 code review不开新的对话轮次。但如果你敲的是opencode run 帮我 review 这段代码你期待的是LLM 理解上下文后给出建议。这两个都是run但底层 API 完全不同。看看 opencode 怎么处理的有了 session IDexecute()根据参数走三条路径sources/opencode/packages/opencode/src/cli/cmd/run.ts L763-834路径 A 和 B 的区别是 API 语义不同session.command()发送的是命令如/review、/commitsession.prompt()发送的是普通文本消息。但底层走的都是同一条事件流。三个路径共享events订阅和loop()。loop()是一个for await...of循环消费 SDK 返回的 event stream根据事件类型决定是打印文本、显示工具调用、还是处理权限请求。naive 方案不会区分 command 和 prompt——一个 prompt 函数就够了。但 opencode 需要让 slash command 有特殊的执行语义比如不开启新 turn、直接返回结果所以才分了两个 API。事件循环loop() 流式消费loop()函数sources/opencode/packages/opencode/src/cli/cmd/run.ts L632-753是整个run命令的输出处理核心。它订阅 session 的事件流在for await...of里处理 9 种事件类型这个循环的优雅之处在于它是同构的——非交互模式和交互模式都用同一套事件模型。区别只在于消费方式非交互模式下loop()直接打印到 stdout交互模式下事件被转发到 TUI 组件如RunFooter的event()方法。naive 方案可能会用 callback 或 Promise chain 来输出流——每个事件一个.then()。但对 9 种事件类型和 7 种筛选条件来说callback 地狱比for await...of难读 10 倍。【权衡】——三层路由 vs 扁平方案可扩展性每命令独立文件 vs 一个巨大 switch扁平方案如果只支持 3 个命令100 行代码搞定。但 opencode 有 20 个命令如果在一个文件里会超过 3000 行。opencode 的选择是每个命令一个文件通过effectCmd统一接口src/cli/cmd/ run.ts ← effectCmd handler650行 generate.ts ← effectCmd handler agent.ts ← effectCmd handler config.ts ← effectCmd handler session.ts ← effectCmd handler...新增一个命令 ≈ 创建一个文件 在index.ts加一行.command()。不需要修改已有代码。代价是增加了间接层。新手第一次看代码需要理解effectCmd的instance、directory、builder、handler四个配置项分别控制什么。但对比在一个 3000 行文件里搜case run这点学习成本是值的。这种「按职责切层」的架构思路在提高生产力的开源项目里反复出现。类似的架构权衡在公众号Ai拆代码的曹操每周拆解——关注后回复路由获取完整架构图集。生命周期effectCmd 自动 dispose vs 手动清理bootstrap是 02-02 的核心函数它做加载→执行→释放三步exportasyncfunctionbootstrapT(directory:string,cb:()PromiseT){constctxawaitInstanceRuntime.load({directory})try{returnawaitcontext.provide(ctx,cb)}finally{awaitInstanceRuntime.disposeInstance(ctx)}}effectCmd做的事情等价——但它是通用的不需要每个命令写一遍 try-finally。如果你不用effectCmd在runhandler 里你也要手动bootstrap()。那为什么还保留bootstrap函数cli/bootstrap.ts因为bootstrap不依赖 Effect 运行时AppRuntime.runPromise是 Effect 的入口把 Effect 程序转换成 Promise 执行——它是一个纯 async/await 版本用在不需要 Effect 的简单场景比如 stream.transport.ts 里用来执行一次性的文件操作。边界失效案例如果store.dispose本身抛异常比如 IPCserver.instance.disposed无法发送effectCmd的finally里的AppRuntime.runPromise会失败导致 dispose 未执行。opencode 的做法是dispose内部 catch 所有异常确保即使 IPC 失败也不影响内存清理。三种交互模式为什么必须分开看一个设问如果--interactive --attach和--interactive走同一条路径会有什么问题答案是SDK 的创建方式不同。本地模式用fetchfunctionin-process HTTP远程模式用真实的 HTTP 客户端。这两个 SDK 的session.command()和session.prompt()接口一样但底层传输完全不同——本地模式不经过 TCP远程模式需要处理ServerAuth.headers()。naive 方案可能会把 SDK 创建放在 handler 入口之后所有逻辑共享同一个sdk对象。但 opencode 的三种模式在 SDK 创建之前就有差异目录解析、auth 头、fetch 函数等共享反而会导致if (args.attach)散落在整个 handler 里。所以作者选择了先分叉再执行的策略在 handler 顶部解决所有参数校验和 SDK 创建三个干净的分支各自走不同的执行路径execute()作为共享核心处理非交互模式【锚点】——“路由即边界”三层路由不是过度设计——它是系统复杂度的自然映射。CLI 层是「入口边界」负责把字符串解析成结构化参数。不关心业务逻辑只关心--flag和positional。边界之外是用户的终端边界之内是 opencode 的世界。Effect 层是「生命周期边界」负责加载和释放 InstanceContext。不关心命令做什么只关心 Efffect 运行的上下文的正确性。边界之外是未初始化状态边界之内是一切就绪。Session 层是「执行边界」负责把参数变成一次 Agent 循环。不关心参数怎么来的只关心 session 创建、事件流消费、输出展示。边界之外是 CLI 参数边界之内是 LLM 推理。下次你设计一个需要从终端到 AI 调用的系统记住三层路由的核心原则「路由即边界——把三层职责分开换掉任何一层都不影响其他两层。」不是在代码里显式写三个 class而是在架构上把这三个职责分开。需求变了你只需要换掉其中一层的实现。如果你觉得这个架构模式有用转发给你的同事——下次你们讨论从终端到AI调用时就能用同一套语言对话。下一篇拆解斜杠命令系统/review、/commit、/diff怎么在 run handler 的三叉戟里找到自己的位置。