Kilo 项目服务端包拆分实战基于 Effect HttpApi 的 packages/server 抽取指南【免费下载链接】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导读本文以packages/opencode/specs/effect/server-package.md这份内部规划文档为骨架完整梳理 KiloKiloCode项目在将 opencode 服务端迁移到 Effect HttpApi 后端之后如何把 HTTP 契约、处理器、OpenAPI 生成与可嵌入的服务器 API 从单体packages/opencode中抽取为独立packages/server工作区的目标布局、抽取铁律与建议 PR 顺序。读完本文你将掌握 Effect HttpApi 架构下服务端拆包的包依赖约束、服务层注入模式host-provided services以及避免包循环的落地手法并能对照仓库源码理解每一步拆分的判断标准。一、背景为什么需要服务端包拆分文档开篇即点明定位这是一份面向未来packages/server拆分的实操参考Practical reference前提是 opencode 服务端已经迁移到Effect HttpApi 后端。当前仓库中的真实状态与文档描述一致服务端仍存活在packages/opencode内部尚未独立成 workspace运行时与应用层runtime and app layer集中在两个文件中packages/opencode/src/effect/app-runtime.ts与packages/opencode/src/effect/run-service.ts路由树位于packages/opencode/src/server/routes/instance/httpapi/目录下并由packages/opencode/src/server/routes/instance/httpapi/server.ts托管hostOpenAPI 生成基于 HttpApi contract并叠加了一层兼容性翻译逻辑位于packages/opencode/src/server/routes/instance/httpapi/public.ts。也就是说此刻的packages/opencode同时承担了三重身份CLI 入口、领域服务宿主、HTTP 服务器宿主。拆包的目标正是把第三重身份以及部分第二重身份移出让每个 workspace 拥有单一清晰的职责边界。二、现状盘点Effect HttpApi 服务端的三个核心文件2.1 app-runtime.ts应用服务层的总装车间packages/opencode/src/effect/app-runtime.ts是整个服务端依赖图的汇聚点。它通过AppNodeBuilderV1.build与LayerNode.group把 70 余个 Effect 服务节点Npm、FSUtil、Database、Auth、Config、Git、Session、Provider、MCP、ToolRegistry等组装成一个AppLayer再ManagedRuntime.make出全局运行时export const AppLayer AppNodeBuilderV1.build( LayerNode.group([...]), ).pipe(Layer.provideMerge(AppNodeBuilderV1.build(Ripgrep.node)), Layer.provideMerge(Observability.layer)) const rt ManagedRuntime.make(AppLayer, { memoMap })对外只暴露一组运行入口并统一经由attach包装见下文 run-service.tsexport const AppRuntime: Runtime { runSync(effect) { return rt.runSync(wrap(effect)) }, runPromise(effect, options) { return rt.runPromise(wrap(effect), options) }, runFork(effect) { return rt.runFork(wrap(effect)) }, ... }从源码结构看AppLayer是未来拆分时哪些服务留在 opencode、哪些下沉到共享包的决策清单凡是能由宿主层提供的服务如EventV2、ProjectV2、Pty、Credential、MemoryService等未来packages/server都应通过宿主层注入而不是直接 import。2.2 run-service.ts实例/工作区上下文的桥接层packages/opencode/src/effect/run-service.ts解决的是一个关键问题当 Effect 运行时脱离 HTTP 请求上下文执行时如何把当前实例instance与当前工作区workspace重新挂载回 Effect 的 Fiber Context。核心是attachWith/attachattach从WorkspaceContext.workspaceID、当前 Fiber 的InstanceRef/WorkspaceRef以及旧的AsyncLocalStorage实例上下文instanceContext.use()中解析出引用再通过Effect.provideService注入export function attachWithA, E, R(effect: Effect.EffectA, E, R, refs: Refs) { if (!refs.instance !refs.workspace) return effect if (!refs.instance) return effect.pipe(Effect.provideService(WorkspaceRef, refs.workspace)) ... }同时makeRuntime提供了一个按服务惰性构建ManagedRuntime的工厂并支持dispose释放资源。这段代码的价值在于它证明了服务实现与请求上下文是正交的——这正是未来packages/server只依赖纯 HttpApi contract 宿主注入层即可工作的底层前提。2.3 server.ts 与 api.ts路由树的组装方式packages/opencode/src/server/routes/instance/httpapi/server.ts将路由拆成五个层次组装rootApiRoutesRootHttpApi/global/* 与控制类路由声明式鉴权eventApiRoutesSSE 类型化路由EventApiptyConnectApiRoutesWebSocket upgrade 路由PtyConnectApi带 ticket 感知鉴权instanceApiRoutes剩余实例路由InstanceHttpApiserverRoutesv2 服务端路由ServerApidocRoute与uiRoute/docOpenAPI 文档与内嵌 Web UI 的兜底路由。其中docRoute的实现细节值得一提OpenApi.fromApi(PublicApi)被lazy延迟到/doc首次被访问时才计算且结果用HttpServerResponse.jsonUnsafe缓存序列化后的字节数组避免 CLI/脚本进程在模块加载期付出 OpenAPI 生成成本。packages/opencode/src/server/routes/instance/httpapi/api.ts则负责契约组合RootHttpApi、InstanceHttpApi、ServerApi通过HttpApi.make创建再用.addHttpApi(...)逐组聚合Config、Session、Provider、Pty、Tui 等 20 余个 group并在 Kilo 侧追加了 AgentBuilder、Indexing、Memory、Telemetry 等扩展组。三、目标包布局五包职责划分文档给出的未来Future State目标布局如下目标包职责packages/core共享领域服务与 schemapackages/serverHTTP 契约、处理器、OpenAPI 生成以及可嵌入的服务器 APIembeddable server APIpackages/cliTUI 与 CLI 入口packages/sdk从服务器 OpenAPI 规范生成packages/plugin插件编写面对照当前仓库可以确认拆分方向已在推进packages/serveropencode-ai/server已存在骨架其 package.json 仅依赖opencode-ai/core、opencode-ai/protocol与effect没有反向依赖opencode本体packages/server/src/api.ts通过opencode-ai/protocol/api的makeDefaultApi生成契约routes.ts 提供createRoutes(password?)与createEmbeddedRoutes()两个工厂——后者正是文档所说可嵌入服务器 API的雏形packages/core、packages/protocol、packages/sdk、packages/plugin均已是独立 workspacepackages/opencodekilocode/cli的 bin 入口kilo/kilocode对应目标中的 CLI 包。说明关联文档写作时点尚无独立packages/serverworkspace仓库当前已具备该包骨架因此本文以规划目标 现状对照的方式呈现而非把文档描述当作当前终态。四、抽取铁律绝对不要制造包循环文档用单独一节强调Extraction Rule抽取规则在足够多的共享服务代码移出packages/opencode之前未来的packages/server只能二选一只拥有纯 HttpApi 契约own pure HttpApi contracts only接受由packages/opencode提供的服务/Layer/回调accept host-provided services/layers/callbacks。禁止出现双向依赖packages/serverimportpackages/opencode的服务同时packages/opencode又 importpackages/server来托管路由——这会在 workspace 层面形成环破坏构建与类型检查。源码印证packages/opencode/src/server/routes/instance/httpapi/server.ts中大量Layer.provide(...)如Layer.provide(AppNodeBuilderV1.build(app))、Layer.provideMerge(Observability.layer)说明当前路由层是通过注入方式获得服务依赖的而packages/server/src/routes.ts的makeRoutes同样用AppNodeBuilder.build(applicationServices, ...)自建服务层。两条路线正是文档所描述的宿主提供服务模式。五、建议 PR 顺序五步渐进拆分文档给出了明确的落地顺序每一步都有独立的验收标准可以对照源码逐条解读第 1 步持续收缩 OpenAPI 兼容垫片目标文件packages/opencode/src/server/routes/instance/httpapi/public.ts。该文件承载着 HttpApi 自动生成 OpenAPI 与旧版 SDK 期望形状之间的翻译逻辑matchLegacyOpenApi包括修正自引用组件 schemafixSelfReferencingComponents将Schema.optional产生的anyOf: [T, {type:null}]剥回纯TstripOptionalNull为查询参数补充显式 schemaQueryParameterSchemas如limit、start、roots等为路径参数补充模式PathParameterSchemas如sessionID必须匹配^ses.*为 SSE 端点手工声明text/event-stream响应归一化组件命名、折叠重复组件、补充旧版错误 schemaBadRequestError、NotFoundError。拆包的隐含前提是兼容层越薄HttpApi 契约越接近公开 API 形状未来 SDK 重新生成的风险越低。因此这一步只做减法不引入结构性变更。第 2 步将稳定的领域 schema 下沉到共享包迁移条件非常严格仅当 schema 不再依赖 opencode-local 运行时模块时才移入packages/core。仓库中opencode-ai/core已承载Database、EventV2、ProjectV2、Credential、SessionV2、Pty等服务正是这一步持续执行的证据。第 3 步抽取纯 HttpApi 契约模块当契约能够在不 importpackages/opencode实现细节的前提下完成编译时即可将纯契约模块移入packages/server。packages/server/src/api.ts中的makeDefaultApi与packages/protocol/src的makeApi即为这类可独立编译的契约层。第 4 步抽取处理器工厂处理器的前置条件是其服务依赖可以由宿主层供给而非直接 import。packages/server/src/handlers/下已有的 session、provider、pty、question 等 handler 文件以及packages/opencode中instanceApiRoutes通过Layer.provide([...handlers])注入的模式展示了这一抽象边界应当如何切分。第 5 步最后移动服务器托管文档明确要求把 server hosting 放到最后一步前提是包所有权已清晰after package ownership is clear。因为托管代码如server.ts的路由树组装、HttpRouter.toWebHandler、webHandler导出是依赖关系最密集的地方过早移动必然拖拽大量服务实现一起搬家破坏第 4 步建立的注入边界。六、Non-Goals三条禁止事项文档最后列出三条非目标用于约束拆包范围防止过度设计不要复活旧的双后端迁移形态Do not revive the old dual-backend migration shape——即不要回到同时维护新旧两套 HTTP 后端的迁移期结构在服务依赖拥有干净的包边界之前不要拆分服务器托管在确认生成产物保持兼容之前不要切换到新的 SDK 生成包——这与第 1 步收缩兼容垫片、第 3 步重生成 SDK 的节奏是闭环的。这三条共同构成拆包的安全网宁可慢不可乱。七、验证与测试视角packages/opencode/package.json中的test:httpapi脚本提供了拆包过程中可复用的回归手段bun run script/httpapi-exercise.ts --mode coverage --fail-on-missing --fail-on-skip bun run script/httpapi-exercise.ts --mode auth --fail-on-missing --fail-on-skip bun run script/httpapi-exercise.ts --mode effect --fail-on-missing --fail-on-skip --shards 4它以覆盖率/鉴权/Effect 三种模式遍历 HttpApi 路由并以--fail-on-missing --fail-on-skip强制要求路由全量覆盖——这意味着任何一次路由迁移如把某 group 的 handler 从packages/opencode移到packages/server都能被机械地验证是否遗漏端点或鉴权语义。八、总结与行动清单围绕Server Package Extraction拆包的本质是一条依赖方向纪律契约与生成物OpenAPI/SDK优先独立服务实现通过宿主注入而非包间 import托管代码最后迁移每一步以编译独立性 HttpApi 全量覆盖测试作为验收门槛。对想要参与或跟进该拆分的开发者建议的行动路径是先读 server-package.md 确立目标再对照 app-runtime.ts 与 run-service.ts 理解服务层边界最后以 server.ts、public.ts 与 packages/server 为观察窗口验证每一步 PR 是否遵守了纯契约优先、宿主注入次之、托管迁移最后的顺序。【免费下载链接】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），仅供参考
Kilo 项目服务端包拆分实战基于 Effect HttpApi 的 packages/server 抽取指南【免费下载链接】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导读本文以packages/opencode/specs/effect/server-package.md这份内部规划文档为骨架完整梳理 KiloKiloCode项目在将 opencode 服务端迁移到 Effect HttpApi 后端之后如何把 HTTP 契约、处理器、OpenAPI 生成与可嵌入的服务器 API 从单体packages/opencode中抽取为独立packages/server工作区的目标布局、抽取铁律与建议 PR 顺序。读完本文你将掌握 Effect HttpApi 架构下服务端拆包的包依赖约束、服务层注入模式host-provided services以及避免包循环的落地手法并能对照仓库源码理解每一步拆分的判断标准。一、背景为什么需要服务端包拆分文档开篇即点明定位这是一份面向未来packages/server拆分的实操参考Practical reference前提是 opencode 服务端已经迁移到Effect HttpApi 后端。当前仓库中的真实状态与文档描述一致服务端仍存活在packages/opencode内部尚未独立成 workspace运行时与应用层runtime and app layer集中在两个文件中packages/opencode/src/effect/app-runtime.ts与packages/opencode/src/effect/run-service.ts路由树位于packages/opencode/src/server/routes/instance/httpapi/目录下并由packages/opencode/src/server/routes/instance/httpapi/server.ts托管hostOpenAPI 生成基于 HttpApi contract并叠加了一层兼容性翻译逻辑位于packages/opencode/src/server/routes/instance/httpapi/public.ts。也就是说此刻的packages/opencode同时承担了三重身份CLI 入口、领域服务宿主、HTTP 服务器宿主。拆包的目标正是把第三重身份以及部分第二重身份移出让每个 workspace 拥有单一清晰的职责边界。二、现状盘点Effect HttpApi 服务端的三个核心文件2.1 app-runtime.ts应用服务层的总装车间packages/opencode/src/effect/app-runtime.ts是整个服务端依赖图的汇聚点。它通过AppNodeBuilderV1.build与LayerNode.group把 70 余个 Effect 服务节点Npm、FSUtil、Database、Auth、Config、Git、Session、Provider、MCP、ToolRegistry等组装成一个AppLayer再ManagedRuntime.make出全局运行时export const AppLayer AppNodeBuilderV1.build( LayerNode.group([...]), ).pipe(Layer.provideMerge(AppNodeBuilderV1.build(Ripgrep.node)), Layer.provideMerge(Observability.layer)) const rt ManagedRuntime.make(AppLayer, { memoMap })对外只暴露一组运行入口并统一经由attach包装见下文 run-service.tsexport const AppRuntime: Runtime { runSync(effect) { return rt.runSync(wrap(effect)) }, runPromise(effect, options) { return rt.runPromise(wrap(effect), options) }, runFork(effect) { return rt.runFork(wrap(effect)) }, ... }从源码结构看AppLayer是未来拆分时哪些服务留在 opencode、哪些下沉到共享包的决策清单凡是能由宿主层提供的服务如EventV2、ProjectV2、Pty、Credential、MemoryService等未来packages/server都应通过宿主层注入而不是直接 import。2.2 run-service.ts实例/工作区上下文的桥接层packages/opencode/src/effect/run-service.ts解决的是一个关键问题当 Effect 运行时脱离 HTTP 请求上下文执行时如何把当前实例instance与当前工作区workspace重新挂载回 Effect 的 Fiber Context。核心是attachWith/attachattach从WorkspaceContext.workspaceID、当前 Fiber 的InstanceRef/WorkspaceRef以及旧的AsyncLocalStorage实例上下文instanceContext.use()中解析出引用再通过Effect.provideService注入export function attachWithA, E, R(effect: Effect.EffectA, E, R, refs: Refs) { if (!refs.instance !refs.workspace) return effect if (!refs.instance) return effect.pipe(Effect.provideService(WorkspaceRef, refs.workspace)) ... }同时makeRuntime提供了一个按服务惰性构建ManagedRuntime的工厂并支持dispose释放资源。这段代码的价值在于它证明了服务实现与请求上下文是正交的——这正是未来packages/server只依赖纯 HttpApi contract 宿主注入层即可工作的底层前提。2.3 server.ts 与 api.ts路由树的组装方式packages/opencode/src/server/routes/instance/httpapi/server.ts将路由拆成五个层次组装rootApiRoutesRootHttpApi/global/* 与控制类路由声明式鉴权eventApiRoutesSSE 类型化路由EventApiptyConnectApiRoutesWebSocket upgrade 路由PtyConnectApi带 ticket 感知鉴权instanceApiRoutes剩余实例路由InstanceHttpApiserverRoutesv2 服务端路由ServerApidocRoute与uiRoute/docOpenAPI 文档与内嵌 Web UI 的兜底路由。其中docRoute的实现细节值得一提OpenApi.fromApi(PublicApi)被lazy延迟到/doc首次被访问时才计算且结果用HttpServerResponse.jsonUnsafe缓存序列化后的字节数组避免 CLI/脚本进程在模块加载期付出 OpenAPI 生成成本。packages/opencode/src/server/routes/instance/httpapi/api.ts则负责契约组合RootHttpApi、InstanceHttpApi、ServerApi通过HttpApi.make创建再用.addHttpApi(...)逐组聚合Config、Session、Provider、Pty、Tui 等 20 余个 group并在 Kilo 侧追加了 AgentBuilder、Indexing、Memory、Telemetry 等扩展组。三、目标包布局五包职责划分文档给出的未来Future State目标布局如下目标包职责packages/core共享领域服务与 schemapackages/serverHTTP 契约、处理器、OpenAPI 生成以及可嵌入的服务器 APIembeddable server APIpackages/cliTUI 与 CLI 入口packages/sdk从服务器 OpenAPI 规范生成packages/plugin插件编写面对照当前仓库可以确认拆分方向已在推进packages/serveropencode-ai/server已存在骨架其 package.json 仅依赖opencode-ai/core、opencode-ai/protocol与effect没有反向依赖opencode本体packages/server/src/api.ts通过opencode-ai/protocol/api的makeDefaultApi生成契约routes.ts 提供createRoutes(password?)与createEmbeddedRoutes()两个工厂——后者正是文档所说可嵌入服务器 API的雏形packages/core、packages/protocol、packages/sdk、packages/plugin均已是独立 workspacepackages/opencodekilocode/cli的 bin 入口kilo/kilocode对应目标中的 CLI 包。说明关联文档写作时点尚无独立packages/serverworkspace仓库当前已具备该包骨架因此本文以规划目标 现状对照的方式呈现而非把文档描述当作当前终态。四、抽取铁律绝对不要制造包循环文档用单独一节强调Extraction Rule抽取规则在足够多的共享服务代码移出packages/opencode之前未来的packages/server只能二选一只拥有纯 HttpApi 契约own pure HttpApi contracts only接受由packages/opencode提供的服务/Layer/回调accept host-provided services/layers/callbacks。禁止出现双向依赖packages/serverimportpackages/opencode的服务同时packages/opencode又 importpackages/server来托管路由——这会在 workspace 层面形成环破坏构建与类型检查。源码印证packages/opencode/src/server/routes/instance/httpapi/server.ts中大量Layer.provide(...)如Layer.provide(AppNodeBuilderV1.build(app))、Layer.provideMerge(Observability.layer)说明当前路由层是通过注入方式获得服务依赖的而packages/server/src/routes.ts的makeRoutes同样用AppNodeBuilder.build(applicationServices, ...)自建服务层。两条路线正是文档所描述的宿主提供服务模式。五、建议 PR 顺序五步渐进拆分文档给出了明确的落地顺序每一步都有独立的验收标准可以对照源码逐条解读第 1 步持续收缩 OpenAPI 兼容垫片目标文件packages/opencode/src/server/routes/instance/httpapi/public.ts。该文件承载着 HttpApi 自动生成 OpenAPI 与旧版 SDK 期望形状之间的翻译逻辑matchLegacyOpenApi包括修正自引用组件 schemafixSelfReferencingComponents将Schema.optional产生的anyOf: [T, {type:null}]剥回纯TstripOptionalNull为查询参数补充显式 schemaQueryParameterSchemas如limit、start、roots等为路径参数补充模式PathParameterSchemas如sessionID必须匹配^ses.*为 SSE 端点手工声明text/event-stream响应归一化组件命名、折叠重复组件、补充旧版错误 schemaBadRequestError、NotFoundError。拆包的隐含前提是兼容层越薄HttpApi 契约越接近公开 API 形状未来 SDK 重新生成的风险越低。因此这一步只做减法不引入结构性变更。第 2 步将稳定的领域 schema 下沉到共享包迁移条件非常严格仅当 schema 不再依赖 opencode-local 运行时模块时才移入packages/core。仓库中opencode-ai/core已承载Database、EventV2、ProjectV2、Credential、SessionV2、Pty等服务正是这一步持续执行的证据。第 3 步抽取纯 HttpApi 契约模块当契约能够在不 importpackages/opencode实现细节的前提下完成编译时即可将纯契约模块移入packages/server。packages/server/src/api.ts中的makeDefaultApi与packages/protocol/src的makeApi即为这类可独立编译的契约层。第 4 步抽取处理器工厂处理器的前置条件是其服务依赖可以由宿主层供给而非直接 import。packages/server/src/handlers/下已有的 session、provider、pty、question 等 handler 文件以及packages/opencode中instanceApiRoutes通过Layer.provide([...handlers])注入的模式展示了这一抽象边界应当如何切分。第 5 步最后移动服务器托管文档明确要求把 server hosting 放到最后一步前提是包所有权已清晰after package ownership is clear。因为托管代码如server.ts的路由树组装、HttpRouter.toWebHandler、webHandler导出是依赖关系最密集的地方过早移动必然拖拽大量服务实现一起搬家破坏第 4 步建立的注入边界。六、Non-Goals三条禁止事项文档最后列出三条非目标用于约束拆包范围防止过度设计不要复活旧的双后端迁移形态Do not revive the old dual-backend migration shape——即不要回到同时维护新旧两套 HTTP 后端的迁移期结构在服务依赖拥有干净的包边界之前不要拆分服务器托管在确认生成产物保持兼容之前不要切换到新的 SDK 生成包——这与第 1 步收缩兼容垫片、第 3 步重生成 SDK 的节奏是闭环的。这三条共同构成拆包的安全网宁可慢不可乱。七、验证与测试视角packages/opencode/package.json中的test:httpapi脚本提供了拆包过程中可复用的回归手段bun run script/httpapi-exercise.ts --mode coverage --fail-on-missing --fail-on-skip bun run script/httpapi-exercise.ts --mode auth --fail-on-missing --fail-on-skip bun run script/httpapi-exercise.ts --mode effect --fail-on-missing --fail-on-skip --shards 4它以覆盖率/鉴权/Effect 三种模式遍历 HttpApi 路由并以--fail-on-missing --fail-on-skip强制要求路由全量覆盖——这意味着任何一次路由迁移如把某 group 的 handler 从packages/opencode移到packages/server都能被机械地验证是否遗漏端点或鉴权语义。八、总结与行动清单围绕Server Package Extraction拆包的本质是一条依赖方向纪律契约与生成物OpenAPI/SDK优先独立服务实现通过宿主注入而非包间 import托管代码最后迁移每一步以编译独立性 HttpApi 全量覆盖测试作为验收门槛。对想要参与或跟进该拆分的开发者建议的行动路径是先读 server-package.md 确立目标再对照 app-runtime.ts 与 run-service.ts 理解服务层边界最后以 server.ts、public.ts 与 packages/server 为观察窗口验证每一步 PR 是否遵守了纯契约优先、宿主注入次之、托管迁移最后的顺序。【免费下载链接】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），仅供参考
