opencode 服务器包拆分实践基于 Effect HttpApi 的 opencode-ai/server 独立化路线【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode本文基于 opencode 仓库中的规格文档 server-package.md系统讲解 opencode 的 HTTP 服务器如何从packages/opencode中逐步剥离为独立的opencode-ai/server工作区包。读完本文你将理解为什么必须“不要制造包循环”、契约contract与宿主host之间的依赖方向应如何设计、五步 PR 拆分序列的具体依据以及当前仓库中packages/server已经落地的“可嵌入服务器 API”的真实形态便于你在类似 Monorepo 中复刻这一拆分策略。一、背景服务器代码的“现状”与拆分动机server-package.md 的开篇即明确了本文档的定位这是“在 opencode 服务器迁移到 Effect HttpApi 后端之后面向未来packages/server拆分的实践参考”。规格文档列出了拆分启动前的五项现状每一条都能在当前仓库中找到对应实现服务器仍位于packages/opencode内。入口是 packages/opencode/src/server/server.ts其中的listen(opts)负责监听端口支持可选的 mDNS 广播Default导出了一个基于HttpApiApp.webHandler().handler的 fetch 式应用openapi()则通过OpenApi.fromApi(PublicApi)生成 OpenAPI 文档。运行时与应用层被集中到两个文件。packages/opencode/src/effect/app-runtime.ts 用AppNodeBuilderV1.build(LayerNode.group([...]))组装出AppLayer一次性聚合了Database、Session、Agent、Provider、Plugin、LLM等数十个领域服务packages/opencode/src/effect/run-service.ts 则提供了attach/attachWith把InstanceRef、WorkspaceRef注入到 Effect 上下文与makeRuntime构造带memoMap的ManagedRuntime暴露runSync/runPromise/runFork/runCallback等边界方法。路由树位于src/server/routes/instance/httpapi下由src/server/server.ts承载。实际的 group/handler 文件在 packages/opencode/src/server/routes/instance/httpapi 目录中按config.ts、session.ts、event.ts、pty.ts等主题划分为 20 余个 group 与同名 handler 模块。OpenAPI 生成基于 HttpApi 契约 兼容性转换转换逻辑集中在 packages/opencode/src/server/routes/instance/httpapi/public.ts。这正是规格文档反复强调要“持续收缩”的兼容 shim 层。规格撰写时尚无独立的packages/server工作区。二、目标包布局五个各司其职的工作区规格文档给出的“Future State”是一个五包目标布局其设计意图是让“领域、传输、入口、客户端、扩展面”互不越界目标包职责packages/core共享的领域服务与 schemapackages/serverHTTP 契约、处理器handlers、OpenAPI 生成以及可嵌入的服务器 APIpackages/cliTUI 与 CLI 入口packages/sdk由服务器 OpenAPI 规范生成packages/plugin插件编写面authoring surface对照当前仓库这个布局已经基本成型packages/core、packages/server、packages/cli、packages/sdk 与 packages/plugin 均已存在。尤其值得关注的是 packages/server/package.json 的依赖声明{ name: opencode-ai/server, version: 1.18.29, private: true, dependencies: { opencode-ai/core: workspace:*, opencode-ai/protocol: workspace:*, drizzle-orm: catalog:, effect: catalog: } }注意它只依赖core与protocol不依赖opencode-ai/opencode。这个依赖方向就是下一条核心规则的落地形态。三、拆分的核心规则绝不制造包循环规格文档将整条拆分策略压缩成一句话“Do not create a package cycle.”不要制造包循环并给出在“足够多的共享服务代码离开packages/opencode之前”未来packages/server必须二选一的约束只拥有纯粹的 HttpApi 契约pure HttpApi contracts only或接受由宿主packages/opencode提供的 services / layers / callbacks。同时明确禁止的反模式是packages/server一边importpackages/opencode的 services一边又被packages/opencodeimport去承载路由——两者互为依赖即成环TypeScript 编译、打包与测试隔离都会随之劣化。当前仓库提供了两处可以直接验证该规则的证据证据一依赖方向的静态约束。如上所述opencode-ai/server的依赖清单里没有opencode-ai/opencode而 packages/opencode/src/server/server.ts 中可以看到反方向的引用import type { CorsOptions } from opencode-ai/server/cors即opencode → server的引用是被允许的宿主承载路由时引用被拆出的包而server → opencode是被规格明确禁止的。证据二“宿主注入”模式的实际实现。packages/server/src/routes.ts 展示了“接受宿主提供 services”这条路线的完整形态——它并不 import 任何 opencode 内部实现而是从opencode-ai/core与effect组装自己的服务层const applicationServices LayerNode.group([ Database.node, EventV2.node, httpClient, ToolOutputStore.cleanupNode, SessionV2.node, PermissionSaved.node, PtyTicket.node, Credential.node, PtyEnvironment.node, LocationServiceMap.node, ]) export function createRoutes(password?: string) { return makeRoutes( password ? ServerAuth.Config.configLayer({ username: opencode, password: Option.some(password) }) : ServerAuth.Config.layer, ) } export function createEmbeddedRoutes() { return makeRoutes(ServerAuth.Config.configLayer({ username: opencode, password: Option.none() })) }这里有三个值得注意的设计点applicationServices是一个LayerNode.group只聚合 core 层的服务节点SessionExecution通过AppNodeBuilder.build(..., [[SessionExecution.node, SessionExecutionLocal.node]])以“接口 本地实现”的替换方式接入避免把某个具体实现的节点硬编码进 group。认证是参数化的createRoutes(password?)面向独立监听场景密码可空createEmbeddedRoutes()则固定为Option.none()不启用密码认证专为被宿主内嵌的场景准备。暴露 Web 处理器而非端口这正是规格中“embeddable server API”一词的落地export const routes createRoutes() export const webHandler () HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)), { disableLogger: true })webHandler()返回toWebHandler包装好的 handler宿主可以自行决定挂在哪个 Node server / 端口 / 代理之后——服务器包只交付“请求进、响应出”的能力把“在哪里托管”的决策权完全留给宿主。契约本体则进一步下沉到了 protocol 包packages/server/src/api.ts 全文仅 8 行import { makeDefaultApi } from opencode-ai/protocol/api import { LocationMiddleware } from ./location import { SessionLocationMiddleware } from ./middleware/session-location export const Api makeDefaultApi({ locationMiddleware: LocationMiddleware, sessionLocationMiddleware: SessionLocationMiddleware, })也就是说HttpApi 的“形状”endpoint、schema、错误契约由opencode-ai/protocol统一生产packages/server只负责注入两个与位置Location语义相关的中间件。这比规格设想的“只拥有纯契约”走得更彻底连契约的生成逻辑也独立在了 server 包之外。四、处理器工厂Layer.mergeAll 的分组装配规格中 PR 序列的第 4 步要求“在 handler 工厂的服务依赖可以被宿主层供给、而不是直接 import 之后才提取 handler 工厂”。packages/server/src/handlers.ts 展示了这一步的完成态——18 个 handler 分组以 EffectLayer的形式各自独立最后用Layer.mergeAll合并export const handlers Layer.mergeAll( HealthHandler, LocationHandler, AgentHandler, SessionHandler, MessageHandler, ModelHandler, ProviderHandler, IntegrationHandler, CredentialHandler, PermissionHandler, FileSystemHandler, CommandHandler, SkillHandler, EventHandler, PtyHandler, QuestionHandler, ReferenceHandler, ProjectCopyHandler, )每个 handler 对应 packages/server/src/handlers/ 下的一个文件agent.ts、session.ts、pty.ts等依赖在各自 Layer 内部声明由makeRoutes中的Layer.provide(handlers, ...)统一解析。配套的横切中间件位于 packages/server/src/middleware/authorization.ts认证、schema-error.tsschema 校验错误的统一映射、session-location.ts会话与位置解析。这种“每个 group 自带依赖声明 mergeAll 装配 统一 provide”的结构使得未来新增或移除任何一个 API 分组都不需要触碰其余 handler 的代码符合 routes.md 中“稳定服务在 handler layer 构建时一次性 yield请求级只提供派生上下文”的模式约定。五、建议的 PR 序列五步走法与当前进度规格文档给出的五步序列本质是“按依赖倒序、从最纯的模块开始”的拆分纪律持续收缩 public.ts 中的 OpenAPI 兼容 shim。该文件承担 SDK/OpenAPI 兼容转换routes.md 进一步给出操作准则每收紧一个 source schema 就删掉一个 workaroundOpenAPI 可见 schema 变化时要确认生成的 SDK diff 是有意的且“优先修 source schema而不是新增后处理规则”。把稳定的领域 schema 移入共享包前提是它们不再依赖 opencode 本地运行时模块。当前 packages/schema 与 packages/core 就是这类 schema/领域代码的落点。当契约模块可以不再 importpackages/opencode的任何实现细节时将纯 HttpApi 契约模块提取进packages/server。从当前仓库看契约生成已进一步下沉到 packages/protocolpackages/server/src/api.ts只是薄封装这一步可以视为已完成。在服务依赖可以由宿主层供给之后提取 handler 工厂。对应 packages/server/src/handlers/ 的 18 个分组实现依赖全部来自 core同样已落地。最后才移动服务器托管hosting且必须在包归属清晰之后。当前 packages/opencode/src/server/server.ts 的listen/Default/openapi仍留在 opencode 包内符合“hosting last”的排序。换言之对照规格的五步清单第 1 步是长期任务shim 尚未清零第 3、4 步已经由protocol server两个包承接第 5 步托管迁移被刻意保留在 opencode 内等待包边界进一步固化。六、非目标Non-Goals三条明确的“不做”规格文档用一整节 Non-Goals 锁死了拆分的边界这三条对后续维护者依然有效不要复活旧的双后端dual-backend迁移形态。即不再维护两套并行的后端实现这也与 routes.md 中“保留{ name, data }错误体直到一次有意的破坏性 API 变更”“通用 middleware 不做领域错误映射”等约束一脉相承——迁移是一次性的而不是长期并存的双轨。不要在服务依赖拥有清晰的包边界之前先拆服务器托管。即 hosting 是最后一步不能因为“看起来好拆”就提前动server.ts的listen/openapi导出面。不要在生成物兼容性被证实之前切换 SDK 生成来源。packages/sdk的生成链路经由 OpenAPI只有在确认输出保持兼容后才允许切换到新的包产出。七、如何在仓库中验证与继续阅读如果你希望亲手验证本文所述的包边界与拆分进度以下路径是最直接的入口仓库为只读以下均为查看方式依赖方向对比 packages/server/package.json依赖core、protocol与 packages/opencode/package.json确认server → opencode方向不存在再在packages/opencode/src/server/server.ts中检索opencode-ai/server查看宿主对被拆包的反向引用目前为 CORS 选项类型。可嵌入 API 的形态阅读 packages/server/src/routes.ts 中createRoutes/createEmbeddedRoutes/webHandler三个导出理解“带密码认证”与“内嵌免密”两种装配方式的差异。契约下沉路径从 packages/server/src/api.ts 追到 packages/protocol 的makeDefaultApi再对照 packages/opencode/src/server/routes/instance/httpapi/public.ts 中尚未收缩的兼容转换层。装配与中间件查看 packages/server/src/handlers.ts 与 packages/server/src/middleware/ 下的三个中间件文件。规范文档族server-package.md 所在目录 packages/opencode/specs/effect/ 还有配套的路由模式routes.md、迁移模式migration.md与总体路线图todo.md是理解本次拆分约束的上下文文档。八、小结server-package.md 虽然篇幅不长却为 opencode 的服务器独立化定下了可执行的纪律以“不产生包循环”为唯一铁律用“纯契约 / 宿主注入”两条互斥路线约束packages/server的职责再以五步 PR 序列保证每一次移动都有独立的编译与兼容性验证点最后用三条 Non-Goals 排除掉“双后端长期并存”“过早拆托管”“抢跑 SDK 切换”这三类典型返工路径。从当前仓库的实际状态看契约下沉至packages/protocol与 handler 工厂packages/server/src/handlers/已经完成迁移并以webHandler()形式提供了可嵌入 API而托管逻辑仍按规格留驻在packages/opencode中等待最后一步——这正是该文档所描述的路线在真实代码中的兑现过程。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考