Kilo opencode 的 Effect 工程化实践服务形状、运行边界与错误建模权威指南【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocodepackages/opencode/specs/effect/guide.md是 Kilo 仓库中 Effect 代码编写与迁移的核心规范文档本文以其为骨架结合仓库内src/effect/的真实实现与test/effect/的测试用例进行源码级展开。读完本文你将掌握如何用「一个模块一个服务」的形状组织 Effect 服务、如何通过AppRuntime统一管理运行边界与InstanceState实现按目录隔离的状态、如何用Schema.TaggedErrorClass建模领域错误并把 HTTP 细节挡在服务层之外以及如何用testEffect编写符合规范的 Effect 测试。规范的范围与定位该指南服务于packages/opencode包Kilo 的核心 Agent 引擎描述的是新代码与迁移工作的首选形态它是 todo.md 路线图的配套文档——后者定义了 P0类型化错误 渲染 HTTP、P1测试迁移、P2运行时标志服务化、P3全局路径显式化等优先级它与 errors.md类型化错误迁移互补errors.md 是ERR/RENDER/HTTP轨道的详细参考指南明确声明如果某个遗留文件与规范不一致只有当它已经在迁移范围内时才去迁移避免无边界地重写存量代码。也就是说这份文档不是完美主义的理论手册而是一份与路线图绑定、按优先级落地的工程规范。服务形状一个模块一个服务指南要求每个服务使用一个独立模块遵循「扁平顶层导出 可追踪的 Effect 方法 显式 Layer 文件底部自再导出」的形态。原文给出的完整模板如下export interface Interface { readonly get: (id: FooID) Effect.EffectFooInfo, FooError } export class Service extends Context.ServiceService, Interface()(opencode/Foo) {} export const layer Layer.effect( Service, Effect.gen(function* () { const state yield* InstanceState.makeState(Effect.fn(Foo.state)(() Effect.succeed({}))) const get Effect.fn(Foo.get)(function* (id: FooID) { const s yield* InstanceState.get(state) return yield* loadFoo(s, id) }) return Service.of({ get }) }), ) export const defaultLayer layer.pipe(Layer.provide(FooDep.defaultLayer)) export * as Foo from ./foo配套的硬性规则禁止export namespace Foo { ... }命名空间会掩盖模块边界破坏扁平导出与依赖分析公开服务方法使用Effect.fn(Foo.method)让方法名进入追踪span信息便于观测小型内部辅助函数使用Effect.fnUntraced不需要产生 span辅助函数保持为同一文件内的非导出顶层声明自再导出index.ts用export * as Foo from .其他文件用export * as Foo from ./foosrc/config目录保持既有的文件顶部自导出模式。这种形状的核心思想是Interface定义契约、Service作为 Effect Context 标签、layer负责装配依赖、defaultLayer提供一键可用的闭合层而export * as Foo让调用方可以用Foo.Service、Foo.layer的命名空间访问风格同时保持每个模块自身独立可读。运行边界统一走 AppRuntime指南要求绝大多数代码通过AppRuntime运行。查看 app-runtime.ts 的实现可以验证其职责const rt ManagedRuntime.make(AppLayer, { memoMap }) // ... export const AppRuntime: Runtime { runSync(effect) { return rt.runSync(wrap(effect)) }, runPromise(effect, options) { return rt.runPromise(wrap(effect), options) }, runPromiseExit(effect, options) { return rt.runPromiseExit(wrap(effect), options) }, runFork(effect) { return rt.runFork(wrap(effect)) }, runCallback(effect) { return rt.runCallback(wrap(effect)) }, dispose: () rt.dispose(), }关键机制托管AppLayerAppLayer由AppNodeBuilderV1.build(LayerNode.group([...]))组装涵盖了 Npm、FSUtil、Database、Auth、Storage、Session、MCP、LSP、Plugin、RuntimeFlags 等几十个服务节点并且通过Layer.provideMerge合入 Ripgrep 与 Observability共享全局memoMapManagedRuntime.make(AppLayer, { memoMap })传入进程级 memoMap保证缓存型服务Bus、Session 等在 CLI、HTTP、测试等不同入口间保持同一实例身份恢复实例/工作区引用wrap(effect)调用attach(effect)见 run-service.ts它会把非 Effect 代码中捕获的InstanceRef/WorkspaceRef注入到 Effect 的 Fiber 上下文中从而跨越边界恢复当前 instance/workspace 上下文。因此在应用边界CLI 命令、HTTP handler、普通 async 适配器统一使用AppRuntime.runPromise(effect)。makeRuntime(...)仍然存在run-service.ts 中可见但只用于少数刻意的服务级边界与迁移遗留除非某个服务确实无法放进AppLayer否则不要新增服务级运行时。运行时标志类型化服务而非可变全局指南禁止在 Effect 代码里直接读取可变的Flag或延迟读process.env统一改为通过RuntimeFlags.Service读取。查看 runtime-flags.ts 可以看到其实现本质一个基于ConfigService.Service的类型化配置服务所有标志都由KILO_*环境变量经 EffectConfig解析而来。代表性标志及默认值来自源码标志环境变量默认值autoShareKILO_AUTO_SHAREfalsepureKILO_PUREfalsedisableDefaultPluginsKILO_DISABLE_DEFAULT_PLUGINSfalsedisableEmbeddedWebUiKILO_DISABLE_EMBEDDED_WEB_UIfalsedisableExternalSkillsKILO_DISABLE_EXTERNAL_SKILLSfalsedisableLspDownloadKILO_DISABLE_LSP_DOWNLOADfalseexperimentalBackgroundSubagentsKILO_EXPERIMENTAL_BACKGROUND_SUBAGENTStrue提供显式 kill switchenableExaKILO_ENABLE_EXA或旧KILO_EXPERIMENTAL_EXAfalseclientKILO_CLIENTcli值得注意的解析细节大多数 experimental 标志遵循「伞形开关」模式KILO_EXPERIMENTALtrue时整体开启单独的KILO_*标志可以覆盖它——源码中的enabledByExperimental(name)正是这个语义显式设置的标志优先否则回退到KILO_EXPERIMENTAL少数标志是「专属开关」不受KILO_EXPERIMENTAL影响例如experimentalNativeLlmKILO_EXPERIMENTAL_NATIVE_LLM和experimentalWebSocketsKILO_EXPERIMENTAL_WEBSOCKETS这一点由 runtime-flags.test.ts 中的专门用例验证整数型标志如outputTokenMax、bashDefaultTimeoutMs会校验必须是正整数非法值零、负数、小数、非数字字符串一律解析为undefined测试用例覆盖了这些边界。测试中要改变行为时使用显式的 layer 变体而不是改环境变量const it testEffect(MyService.defaultLayer.pipe(Layer.provide(RuntimeFlags.layer({ experimentalReferences: true }))))并且严格遵循一条纪律服务/Layer 构建完成后不得再修改process.env或Flag。测试用的RuntimeFlags.layer(overrides)会生成一个忽略外部ConfigProvider的闭合层源码中通过ConfigProvider.fromUnknown({})实现保证测试确定性。每实例状态InstanceState 与 ScopedCache当两个打开的目录instance不应共享同一份服务状态时使用InstanceState。查看 instance-state.ts 的实现底层是一个ScopedCache以目录directory为 key容量无限通过registerDisposer注册清理器当实例卸载时自动调用ScopedCache.invalidate(cache, directory)释放对应条目提供了get/use/useEffect/has/invalidate等便捷方法其中get每次从当前上下文懒读取目录因此同一个InstanceState句柄在切换实例上下文后仍能取到正确目录的状态。订阅、finalizer 与作用域内后台工作都应放进InstanceState.make(...)的初始化器中const cache yield * InstanceState.makeState( Effect.fn(Foo.state)(function* () { const bus yield* Bus.Service yield* bus.subscribeAll().pipe( Stream.runForEach((event) handleEvent(event)), Effect.forkScoped, ) yield* Effect.acquireRelease(openResource, closeResource) return yield* loadInitialState() }), )两条纪律不要在InstanceState之上再加started标志——让ScopedCache处理只运行一次和并发去重Effect.cached式语义若需要让init()非阻塞在调用方/引导边界 fork不要在InstanceState.make(...)内部 fork 然后带着部分初始化的状态提前返回。instance-state.test.ts 用大量it.live用例验证了这些保证同一目录缓存命中初始化只执行一次、不同目录相互隔离、reloadInstance/disposeAllInstances触发 finalizer 与失效、高并发访问下的去重与目录保持跨Effect.sleep、Effect.yieldNow、Effect.promise等异步边界仍能取回正确目录以及一个目录内的可变状态不泄漏到另一个目录。错误建模领域错误走 Error 通道Defect 留给缺陷规范的核心原则预期中的领域失败放在 Effect 的 error 通道上Defect 只用于 bug、不可能状态和最终的未知边界兜底。export class SessionBusyError extends Schema.TaggedErrorClassSessionBusyError()(SessionBusyError, { sessionID: SessionID, message: Schema.String, }) {} export type Error Storage.Error | SessionBusyError export interface Interface { readonly get: (id: SessionID) Effect.EffectInfo, Error }规则清单新预期领域错误用Schema.TaggedErrorClass定义带结构化字段可序列化、可匹配从服务模块导出领域级Error联合类型并写进服务方法签名在Effect.gen/Effect.fn中直接预期失败用yield* new MyError(...)未知 cause 字段用Schema.Defect保留用Effect.try(...)、Effect.tryPromise(...)、Effect.mapError、Effect.catchTag、Effect.catchTags把外部失败翻译成领域错误禁止对用户、IO、校验、资源缺失、认证、provider、busy 状态等失败使用Effect.die(...)。这与 errors.md 中ERR轨道目标完全一致预期失败类型化、服务接口暴露失败类型、HTTP 状态码与线格式只在路由边界处理、面向用户的边界渲染结构化错误而非Error: SomeName字符串。HTTP 错误边界服务层保持传输无关服务模块必须保持 HTTP 无关不得 import HTTP 状态码、HttpApiError、HttpServerResponse或路由专属错误 schemaHTTP handler 负责把服务错误翻译成端点声明的公开错误 schema一次性翻译直接内联只有同一翻译反复出现时才抽取共享小助手不要把通用中间件变成领域错误注册表——中间件只处理横切关注点与最终的未知 defect 兜底在刻意破坏性 API 变更之前保留既有公开线格式如{ name, data }。这种分层让服务可以被 CLI、HTTP、测试等任意传输复用错误契约沉淀在服务接口与端点 schema 上。Schema以 Effect Schema 为唯一事实来源Schema.Class用于有明确身份的导出数据对象Schema.Struct用于局部形状与简单嵌套对象Schema.brand用于单值 ID复用具名 refinement而不是到处重写约束优先用窄边界辅助函数而非通用的 Schema-to-Zod 桥接。同时指南承认了三处刻意保留的边界不是偷懒而是策略公开插件工具仍然通过tool.schema z暴露 Zod工具参数 JSON Schema 通过工具专属辅助函数生成公开配置与 TUI schema 通过 schema 脚本生成。首选服务优先 yield 既有服务而非临时用平台 API在已 effectified 的代码中优先通过依赖注入使用既有服务而不是降级到临时平台 API场景首选避免应用文件 IOFSUtil.Service裸fs/promises子进程AppProcess.Service直接ChildProcessSpawner.spawn或遗留 process 助手HTTP 请求HttpClient.HttpClientEffect 代码内裸fetch路径/配置/时间Path.Path、Config、Clock、DateTime各自为政回调式 APIEffect.callback手写 Promise 包装空返回值Effect.voidEffect.succeed(undefined)并发共享计算Effect.cached重复发起同一计算后台循环使用Effect.repeat/Effect.schedule配合Effect.forkScoped且 fork 在所属 layer/state 的作用域内进行保证随作用域关闭自动清理。Promise 与 ALS 桥接bridge.ts 中的EffectBridge是官方认可的 Promise/callback 互操作助手用于需要保留 instance/workspace 上下文的桥接场景。它暴露四个方法promise(effect): 把 Effect 变成 Promisefork(effect): 后台 fork 一个 fiberrun(effect): 返回一个 callback 风格的 Effectbind(fn): 把同步函数绑定到当前捕获的上下文。其实现细节印证了文档描述make()创建时通过captureSync()捕获当前 Fiber 上下文中的InstanceRef/WorkspaceRef见 instance-ref.ts 中的两个Context.Reference随后每次跨回 Promise 回调时用restore(...)恢复 Kilo 兼容上下文Instance.restore与WorkspaceContext.restore。指南同时强调普通 JS 回调如果需要实例数据应当显式接收该数据而不是隐式依赖全局上下文。测试testEffect 统一模式指南指向 EFFECT_TEST_MIGRATION.md 作为详细迁移规则核心模式是const it testEffect(Layer.mergeAll(MyService.defaultLayer)) describe(my service, () { it.instance(does the thing, () Effect.gen(function* () { const svc yield* MyService.Service expect(yield* svc.run()).toEqual(ok) }), ) })testEffect与三个 runner 变体实现在 test/lib/effect.tsit.effect(...)纯 Effect 行为提供TestClockTestConsole测试环境it.live(...)真实时钟、文件系统 mtime、子进程、git、锁等真实集成行为仅保留 TestConsole 捕获输出it.instance(...)需要一个作用域内临时 opencode 实例的服务测试通过withTmpdirInstance提供TestInstance。配套规则优先使用test/fixture/fixture.ts中的 Effect 感知 fixturestmpdirScoped、provideInstance、provideTmpdirInstance等避免 sleep改为等待真实事件、Deferred或确定性的状态迁移layer 构建后避免可变process.env、Flag或模块全局变更部分服务桩用Layer.mock缺失方法若被误调用应大声失败避免自定义ManagedRuntime、attach(...)或临时的run(...)测试包装器。迁移文档还给出了明确的反模式清单test(..., async () Effect.runPromise(...))、局部run/load/svc包装器、测试文件里的自定义ManagedRuntime.make(...)、围绕 Effect 失败的 Promisetry/catch、用Promise.withResolvers/Bun.sleep/setTimeout做同步等都是要被移除的形态并发行为要用 fibers、Deferred和Effect.all(..., { concurrency: unbounded })保留不能无意串行化。验证命令在packages/opencode目录内运行bun run typecheck bun run test -- path/to/test.ts注意不要在仓库根目录运行测试——仓库对此有守卫必须在包目录内执行。小结这份指南把 Effect 工程化落到了五条主线上模块形状Service Shape、运行边界AppRuntime、状态隔离InstanceState、错误建模Error channel Schema.TaggedErrorClass与测试纪律testEffect。它既是新代码的编写规范也是 P0–P3 迁移路线的执行准则。若要进一步追踪迁移进度可阅读配套的 todo.md路线图与 errors.md错误迁移细节想观察规范落地的真实范例instance-state.test.ts 与 runtime-flags.test.ts 是最直接的参考。【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考