opencode 开发规约解析Effect 服务模式、模块结构与数据库迁移实战指南【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencodeopencode 的packages/opencode/AGENTS.md是该仓库贡献者与 AI Agent 共用的开发规约文件规定了数据库 schema 与迁移的位置、开发服务器TUI的运行方式、模块组织形式以及一整套 Effect 框架编码规则。本文以该文档为骨架逐节展开先确认 Drizzle schema 与迁移的真实落点再演示如何用 tmux 驱动交互式 TUI 的调试流程最后深入makeRuntime与InstanceState两个核心基础设施的源码实现帮助你在编写或迁移 Effect 代码时直接遵循本仓库已验证的工程约定。一、数据库Schema 与 Migrations 的落点规约文档给出两条硬约束SchemaDrizzle schema 位于packages/core/src/**/*.sql.tsMigrations数据库迁移位于packages/core且由 core 包负责执行applied by core。在仓库中可以验证这两个声明与实际代码一致schema 文件 与 workspace.sql.ts 正是packages/core/src下匹配*.sql.ts模式的 Drizzle schema 定义配套还有># 在后台 tmux 会话中启动 TUI tmux new-session -d -s opencode-dev bun dev # 抓取当前 TUI 输出以检查状态 tmux capture-pane -pt opencode-dev # 完成后显式结束会话 tmux kill-session -t opencode-dev这条工作流的要点在于tmux capture-pane让 Agent 或开发者可以非交互地读取终端画面从而在自动化流程CI 冒烟、Agent 自检中验证 TUI 启动是否成功、是否报错。对应的dev脚本定义在 package.jsondev: bun run ./src/index.ts另有dev:temporary指向src/temporary.ts的实验入口。三、模块结构为什么禁用export namespace文档Module shape一节明确不要用export namespace Foo { ... }做模块组织原因是它不是标准 ESM、会阻止 tree-shaking、并且会破坏 Node 原生 TypeScript runner 的运行。推荐替代方案是「扁平顶层导出 文件末尾自导出」// src/foo/foo.ts export interface Interface { ... } export class Service extends Context.ServiceService, Interface()(opencode/Foo) {} export const layer Layer.effect(Service, ...) export const defaultLayer layer.pipe(...) export * as Foo from ./foo消费方导入的是命名空间投影import { Foo } from /foo/foo yield * Foo.Service Foo.layer Foo.defaultLayer这一模式在仓库中是普遍约定例如 Account 服务 末尾的export * as Account from ./account、Agent 服务 的export * as Agent from ./agent以及src/config/下每个配置模块首行/尾行的自导出如 agent.ts 的export * as ConfigAgent from ./agent。两个细节值得注意命名空间私有不导出的顶层声明文件内 helper留在同一文件中即可。它们不会被export * as投影出去外部无法访问但文件自身代码可以正常调用Effect 服务标签Context.ServiceService, Interface()(opencode/Foo)使用统一的opencode/前缀标签方便在层Layer解析与追踪日志中识别服务来源。何时是index.ts当模块是foo/index.ts单命名空间目录时自导出的源应使用.而不是./index// src/foo/index.ts export const thing ... export * as Foo from .多兄弟目录不要加 barrel对于包含多个独立模块的目录如src/session/、src/config/保持每个兄弟文件各自持有自己的自导出不要添加 barrelindex.ts。消费方直接导入具体兄弟文件import { SessionRetry } from /session/retry import { SessionStatus } from /session/status文档给出的理由是性能层面的barrel 会强制所有 import 经过它并求值每一个兄弟模块既摧毁 tree-shaking 又拖慢模块加载。src/config/目录约 20 个平级模块文件正是这一约定的典型实践。四、Effect 编码规则Core 用法规约opencode Effect rules一节规定了 Effect 代码的默认写法这些规则同样在 specs/effect/migration.md 的迁移参考中得到呼应组合用Effect.gen(function* () { ... })需要命名/可追踪的 effect 用Effect.fn(Domain.method)内部 helper 用Effect.fnUntracedEffect.fn/Effect.fnUntraced接受 pipeable 算子作为额外参数因此避免多余的外层.pipe()包裹回调式 API 用Effect.callback包裹用Effect.void代替Effect.succeed(undefined)/Effect.succeed(void 0)需要Date时优先DateTime.nowAsDate而不是new Date(yield* Clock.currentTimeMillis)。模块约定方面src/config目录要求新增配置模块时遵循文件顶部的现有自导出模式例如export * as ConfigAgent from ./agent。五、Schema 与错误建模多字段数据用Schema.Class单值类型用 branded schemaSchema.brand类型化错误用Schema.TaggedErrorClassdefect 类原因用Schema.Defect而非unknown在Effect.gen/Effect.fn内直接失败分支优先yield* new MyError(...)而不是yield* Effect.fail(new MyError(...))。配合 migration.md 中预期失败应是错误通道上的类型化错误而不是抛出异常或 defect的表述可以看出该仓库把可预期失败建模为类型化错误通道作为迁移完成的基本判据之一。六、Runtime 与 InstanceState两种状态的分工这是规约中最具工程判断力的一节决定了服务级单例和每项目/每目录状态分别放在哪里。makeRuntime服务级共享运行时所有服务统一使用makeRuntime位于 run-service.ts。读源码可以确认它的实际形态export function makeRuntimeI, S, E(service: Context.ServiceI, S, layer: Layer.LayerI, E) { let rt: ManagedRuntime.ManagedRuntimeI, E | undefined const getRuntime () (rt ?? ManagedRuntime.make(Layer.provideMerge(layer, Observability.layer), { memoMap })) return { runSync, runPromiseExit, runPromise, runFork, runCallback, ... } }见 run-service.ts#L33-L47关键点返回对象包含runPromise、runFork、runCallback等方法源码中还有runSync、runPromiseExit是文档列举之外的补充懒初始化的ManagedRuntime通过共享的memoMap来自opencode-ai/core/effect/memo-map去重层实例同一进程中多个服务解析同一依赖时不会重复构建层每次执行前attach(...)会把当前 fiber 上下文中的InstanceRef/WorkspaceRef注入使服务在运行时感知当前实例/工作区这是回调边界能带上下文的基础。InstanceState按目录隔离的实例状态InstanceState位于 instance-state.ts用于每个目录/每个项目需要独立副本、且需要随实例销毁而清理的状态。源码实现印证了文档描述的所有机制export const make A, E never, R never( init: (ctx: InstanceContext) Effect.EffectA, E, R | Scope.Scope, ): ... Effect.gen(function* () { const cache yield* ScopedCache.makestring, A, E, R({ capacity: Number.POSITIVE_INFINITY, lookup: () Effect.gen(function* () { return yield* init(yield* context) }), }) const off registerDisposer((directory) Effect.runPromise(ScopedCache.invalidate(cache, directory))) yield* Effect.addFinalizer(() Effect.sync(off)) return { [TypeId]: TypeId, cache } })见 instance-state.ts#L26-L45内部就是一个以目录为 key的ScopedCache容量无穷每个打开的项目拿到独立状态副本通过registerDisposer注册到 instance-registry.ts当某个目录的实例被销毁时自动ScopedCache.invalidate实现打开即建立、关闭即清理。规约给出的使用守则每一条都对应上面源码的行为判断标准如果两个打开的目录不应该共享同一份服务状态就该用InstanceState别叠加状态机直接把活干在InstanceState.make闭包里——ScopedCache已保证只执行一次和并发去重不要再额外加 fiber、ensure()回调或started标志清理用 Finalizer在make闭包内用Effect.addFinalizer/Effect.acquireRelease处理订阅注销、进程拆除等清理逻辑后台消费者用Effect.forkScoped闭包内 fork 的 fiber 会随实例销毁被中断让init()非阻塞的正确姿势在init()的调用点forkInstanceState.get(state)例如Effect.forkIn(scope)而不是在make闭包内部 fork——闭包内 fork 会导致状态对其他读取它的方法不完整。生产路径bootstrap 已接管并发控制文档还指出 project/bootstrap.ts 已经把每个服务的init()包在Effect.forkDetach里因此生产环境中init()是 fire-and-forget服务侧应保持init()内部同步由调用方控制并发。查看 bootstrap.ts#L41-L45 可见它用Effect.forEach以concurrency: unbounded并发拉起 LSP、ShareNext、Format、VCS、Snapshot、Project 各服务的init()并带InstanceBootstrap.init的 span 追踪——这与上面第 5 条规则共同构成完整的初始化并发模型。七、Effect v4 beta 与推荐服务API 注意当前仓库使用的 Effect v4 beta见 patches/effect4.0.0-beta.83.patch中不存在Effect.fork与Effect.forkDaemon需要把 fiber 放入特定 scope 时使用Effect.forkIn(scope)优先让渡给 Effect 服务而非临时平台 APIeffect 化服务内文件 I/O 优先FileSystem.FileSystem而非裸fs/promises进程优先ChildProcessSpawner.ChildProcessSpawnerChildProcess.make(...)而非自造封装HTTP 优先HttpClient.HttpClient而非裸fetch涉及路径、配置、时钟、日期时优先Path.Path、Config、Clock、DateTime后台循环/定时任务用Effect.repeat或Effect.schedule配合Effect.forkScoped并在层定义中启动Effect.cached去重当多个并发调用方应共享一次在途计算时使用Effect.cached而不是手工维护Fiber | undefined或Promise | undefined变量。migration.md 的 Platform Edges 清单将Effect.cached、Effect.callback、FSUtil.Service、AppProcess.Service、HttpClient并列为迁移时的平台边缘标准件回调边界用EffectBridge来自原生或外部系统的回调parcel/watcher、node-pty、原生fs.watch、插件回调等如果需要带着实例/工作区上下文重新进入 Effect 服务应使用 bridge.ts 提供的EffectBridge。普通 async 代码要么显式传递上下文要么留在 Effect fiber 内部——不要引入环境实例上下文垫片。八、把规约落到日常开发一张检查表综合文档正文与 migration.md 的迁移清单向该仓库提交代码前可对照检查代码是否为单一 Effect 主体而非对服务调用套 Promise 包装预期失败是否为错误通道上的类型化错误Schema.TaggedErrorClass而非 throw 或 defectLayer 依赖是否显式defaultLayer是否负责生产接线测试是否使用开放层替换依赖是否用makeRuntime建运行时、用InstanceState承载每目录状态且没有叠加started标志新配置模块是否沿用src/config的自导出模式多兄弟目录是否避免 barrel非 Effect 代码进入共享层时是否优先走AppRuntime仅在服务确实位于AppLayer之外时才新增服务级运行时。结语packages/opencode/AGENTS.md虽然篇幅不长但它浓缩了 opencode 的核心工程决策数据库 schema 与迁移下沉到packages/core的*.sql.ts体系交互式 TUI 通过 tmux 会话驱动以便结果可检查模块组织采用扁平导出 自导出命名空间投影以保住 ESM tree-shakingEffect 代码则以makeRuntime共享memoMap的服务运行时与InstanceStateScopedCache按目录隔离的实例状态划分状态边界并统一了 Schema 建模、回调桥接与后台任务的做法。遵循这些规约无论是人工贡献还是 Agent 辅助开发都能在 packages/opencode 这个多包 monorepo 中保持一致的代码形态。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考