Kilo HTTP 路由模式实践指南：基于 Effect HttpApi 的实例路由架构、错误边界与 OpenAPI 兼容治理

Kilo HTTP 路由模式实践指南基于 Effect HttpApi 的实例路由架构、错误边界与 OpenAPI 兼容治理【免费下载链接】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/routes.md 为骨架系统讲解 Kilo本仓库开源编码 Agent 平台opencode服务端如何基于 Effect 的HttpApi体系组织实例instanceHTTP 路由从HttpApiBuilder.group的 handler 编写范式、稳定服务注入时机、错误边界设计到public.ts中 OpenAPI/SDK 兼容层的治理策略。读完本文你将掌握一套可复用的、经过真实生产代码验证的 Effect HttpApi 路由设计规范并能在新增或改造 HTTP 端点时对照源码逐条落地。适用范围与定位routes.md是packages/opencode/src/server/routes/instance/httpapi目录下文简称httpapi目录的编写指引它定义了三层约束Handler 形态普通 JSON 与流式streaming端点统一使用HttpApiBuilder.group(...)只有 WebSocket 升级或 catch-all 兜底等无法归入请求/响应模型的场景才允许裸HttpRouter。错误边界领域错误在 handler 边界翻译为端点声明的公开 HTTP 错误通用中间件不得兼任领域错误映射器。OpenAPI 兼容public.ts独占 SDK/OpenAPI 兼容性转换并通过收紧源 schema 逐步收缩这些转换。该目录下实际代码严格遵循了这一规范groups/存放 21 个HttpApi组的端点声明handlers/存放 20 个对应的 handler 实现middleware/存放授权、Schema 错误、压缩、工作区路由等横切中间件api.ts负责组与中间件的最终组装。Handler Shape一切从HttpApiBuilder.group开始标准写法构建期 yield 稳定服务闭包捕获routes.md给出的规范示例是在构建 handler 层时一次性yield稳定服务然后在端点实现中闭包引用这些服务export const sessionHandlers HttpApiBuilder.group(InstanceHttpApi, session, (handlers) Effect.gen(function* () { const session yield* Session.Service return handlers.handle(list, () session.list()) }), )真实实现比示例更完整。handlers/session.ts 中sessionHandlers在Effect.gen的头部一次性 yield 了 14 个稳定服务Session.Service、SessionShare.Service、SessionPrompt.Service、SessionRevert.Service、SessionCompaction.Service、SessionRunState.Service、Agent.Service、Permission.Service、SessionStatus.Service、Todo.Service、SessionSummary.Service、EventV2Bridge.Service、KiloViewers.Service以及Scope.Scope随后所有端点实现直接闭包引用这些局部变量。这种构建期注入、请求期闭包的模式带来两个直接收益依赖解析只发生一次每个服务实例在 handler 层构建时由 Effect 运行时解析而不是在每个请求内重复解析减少请求路径上的开销端点实现极薄每个Effect.fn(SessionHttpApi.xxx)只关注参数解构与业务编排可读性高、易于测试。不要在请求处理器内重建稳定层规范明确警告不要在请求处理器内部重建稳定层如调用Effect.provide(SomeLayer)。稳定服务必须在路由/层边界提供请求级 provisioning 只留给请求派生上下文。这条约束在 AGENTS.md 中被进一步细化避免在请求处理器或裸路由回调中调用Effect.provide(...)稳定层应在应用/层边界统一提供而不是按请求重建或限定作用域避免使用HttpRouter.provideRequest(...)除非依赖本身就是请求级的中间件中只允许用Effect.provideService(...)注入请求派生上下文如WorkspaceRouteContext、InstanceRef、WorkspaceRef严禁借道请求 effect 夹带稳定服务。对照 server.tsInstanceHttpApi的 20 个 handler 组含 Kilo 自定义组正是在HttpApiBuilder.layer(...).pipe(Layer.provide([...]))组装边界统一提供的——这正是提供一次、全局复用原则的落地。流式响应与handleRawroutes.md指出 group 也覆盖流式 HTTP 端点。handlers/session.ts 中的prompt端点就是典型handler 内返回HttpServerResponse.stream(...)流式输出 AI 回复同时端点声明位于HttpApiGroup内保持 OpenAPI 元数据与路由上下文完整。对于需要裸请求/响应的已声明端点含 WebSocket 升级AGENTS.md 补充了handleRaw(...)的用法——它仍留在HttpApiBuilder.group的 typed 路由树中中间件、路由上下文和 OpenAPI 元数据都不丢失export const ptyConnectHandlers HttpApiBuilder.group(PtyConnectApi, pty-connect, (handlers) Effect.gen(function* () { const pty yield* Pty.Service return handlers.handleRaw(connect, (ctx) connectPty(ctx.request, pty)) }), )裸HttpRouter的适用边界规范给出的裸HttpRouter使用场景只有两类WebSocket 升级等无法归入请求/响应 HttpApi 模型的路由如PtyConnectApi之外的升级端点catch-all 兜底路由例如 server.ts 中挂载 Web UI 静态资源的router.add(*, /*, ...)——它不在声明的 API 面内无法用 HttpApi 描述。判定原则很简单只有当 HttpApi 是错误的抽象时才用裸路由其余一律走 group。Error Boundaries在路由边界翻译领域错误期望的服务错误 → 端点声明的公开 HTTP 错误routes.md的错误边界规范是期望expected的服务错误必须在 handler 边界映射为端点声明的公开 HTTP 错误。具体到实现一次性映射就地内联one-off mappings inline重复出现的映射抽取为小 helper。handlers/session.ts 完美呈现了这两种形态const requireSession Effect.fn(SessionHttpApi.requireSession)(function* (sessionID: SessionID) { return yield* SessionError.mapStorageNotFound(session.get(sessionID)) })mapStorageNotFound就是把存储层会话不存在类错误翻译为公开ApiNotFoundError的小 helper被get、children、todo、messages、update等多个端点复用而init端点中promptSvc.command(...).pipe(Effect.mapError(() new HttpApiError.BadRequest({})))、share端点中映射为HttpApiError.InternalServerError则属于就地内联的一次性映射。值得注意的是 handlers/session.ts 的注释揭示了一个判断细节share/unshare 的失败并非全部由客户端引起存储与网络失败是真实可能——因此映射为类型化 500 而非一律 400 BadRequest。翻译必须忠实于错误语义而不是图省事统一归为客户端错误。通用中间件不做领域错误映射规范要求通用中间件应只处理横切关注点与最终未知缺陷兜底不得变成领域错误映射器。对照 middleware/error.ts 顶部的注释这一点被落实为一条硬性约定Keep typed HttpApi failures on their declared error path; this boundary only replaces defect-only empty 500s.即类型化的 HttpApi 失败必须留在其声明的错误路径上errorLayer只负责替换仅有缺陷defect的空 500——包括 SQLite 锁竞争返回带ref的 503 与busyMessage、配置解析类错误400以及未知缺陷的统一兜底NamedError.Unknown 500。领域错误映射永远发生在 handler 内部而不是这一层。公开 JSON 错误必须是显式 schema 契约routes.md要求公开 JSON 错误应是声明在每个端点或 group 上的显式 schema 契约内置HttpApiError.*只有在其生成的 body 恰好就是想要的公开线上形态时才允许使用。errors.ts 中的ApiNotFoundError是显式契约的范本——它用Schema.ErrorClass精确描述了线上错误体的两个字段export class ApiNotFoundError extends Schema.ErrorClassApiNotFoundError(NotFoundError)( { name: Schema.Literal(NotFoundError), data: Schema.Struct({ message: Schema.String, }), }, { httpApiStatus: 404 }, ) {}而 groups/session.ts 的端点声明则把哪些错误会出现在 4xx/5xx 响应中写进了 OpenAPIHttpApiEndpoint.get(get, SessionPaths.get, { params: { sessionID: SessionID }, query: WorkspaceRoutingQuery, success: described(Session.Info, Get session), error: [HttpApiError.BadRequest, ApiNotFoundError], })同一文件中shell端点声明error: [HttpApiError.BadRequest, ApiNotFoundError, SessionBusyError]permissionRespond端点声明PermissionNotFoundError——端点可能抛出的每一种公开错误都显式列在 schema 上SDK 生成与 OpenAPI 文档因此与真实行为严格一致。保留{ name, data }错误体routes.md明确要求在做出刻意的破坏性 API 变更之前必须保留现有的{ name, data }错误体。这一形状是整个 SDK 错误处理如wrapClientError提取.data.message的既有约定middleware/error.ts 的兜底响应通过new NamedError.Unknown({ message, ref }).toObject()输出{ name: Unknown, data: { message, ref } }middleware/schema-error.ts 的 Schema 拒绝路径同样输出{ name: BadRequest, data: { message, kind } }非/api/前缀路径与其它 4xx/5xx 保持一致确保 SDK 能统一解析public.ts 的addLegacyErrorSchemas在 OpenAPI 组件中显式注册了BadRequestError、NotFoundError两个{ name, data }形状的 schema。可见{ name, data }是贯穿 handler、中间件、OpenAPI 三层的一致线上契约任何改动都必须视为破坏性变更走正式流程。OpenAPI 兼容public.ts与源 schema 治理兼容层的工作方式public.ts 是 SDK/OpenAPI 兼容转换的唯一所有者。它以OpenApi.annotations({ transform: matchLegacyOpenApi })挂载在公开 API 上见 public.tsmatchLegacyOpenApi对 Effect 生成的 OpenAPI 文档做一系列还原/对齐处理例如查询参数还原QueryParameterSchemas把解码后的 Effect 类型还原为 SDK 调用者期望的公开形态如GET /session limit声明为{ type: number }因为运行时查询参数实际以字符串传输路径参数模式PathParameterSchemas为sessionID^ses.*、messageID^msg.*、partID^prt.*、permissionID^per.*、ptyID^pty.*等品牌化 ID 补充 pattern剥离 optional nullstripOptionalNull递归移除Schema.optional在 OpenAPI union 中引入的{ type: null }分支使请求/响应类型与旧 SDK 期望一致补充旧错误 schemaaddLegacyErrorSchemas注入BadRequestError/NotFoundError组件并把内置EffectHttpApiErrorBadRequest等 400/404 响应统一改写为 legacy 形态SSE 协议显式化对/event、/global/event、/api/event的 GET 端点将 200 响应显式声明为text/event-stream 对应 Event schema因为 HttpApi 对 SSE 没有一等公民的响应 schema。收缩转换源 schema 优先routes.md对兼容层的治理策略是通过收紧源 schema一次修复一个 workaround逐步缩小public.ts的转换面。这直接呼应了public.ts中大量该转换是历史包袱的注释——例如 public.ts 对QueryParameterSchemas的说明查询 schema 描述的是解码后的 Effect 值但生成的 SDK 需要公开调用形态。每消除一个这样的差异就少一条转换规则。变更 OpenAPI 可见源 schema 的三条铁律当某个 OpenAPI 可见的源 schema需要变更时routes.md规定了三条检查验证生成的 SDK diff 是有意为之——不要在不自知的情况下悄悄改变 SDK 类型除非 PR 明确声明否则保留 legacy 兼容性——public.ts的转换规则本质上是在为历史 SDK 兜底随意突破会导致旧客户端断裂优先修源 schema而不是新增后处理规则——每新增一条public.ts转换规则都是在累积技术债正确方向是让源 schema 直接产出正确的 OpenAPI。从 public.ts 可以看到该原则的实例非 V2 API 路径会删除operation.security与生成的 401 响应 union因为鉴权仍是运行时中间件不该出现在 legacy 公开 OpenAPI 元数据中——这是让声明如实反映运行时的刻意设计而非兼容妥协。Checklist For Route PRs提交前的自检清单routes.md以一份可勾选的 PR 清单收尾。这份清单可作为任何涉及实例路由的改动新增端点、调整 handler、重构中间件的最终验收标准结合上文源码可逐条对照稳定服务在 handler 层构建时 yield——对照 handlers/session.ts所有服务在Effect.gen头部一次注入端点实现闭包引用期望的领域错误在路由边界被翻译——对照SessionError.mapStorageNotFound/mapBusyhelper 与Effect.mapError就地映射端点/group 的错误 schema 描述公开 body 与状态码——对照 groups/session.ts 的error: [HttpApiError.BadRequest, ApiNotFoundError]声明中间件不新增领域特定的名称检查——通用中间件middleware/error.ts、middleware/schema-error.ts只做横切处理与缺陷兜底裸路由仅用于 HttpApi 不适用之处——如 server.ts 的 Web UI catch-all 与 WebSocket 升级端点。从规范到组装一条请求的完整生命周期最后把上述规范串起来看一条请求如何流过整棵路由树见 server.ts 的路线图注释路由树分层rootApiRoutes/global/*与控制路由→eventApiRoutes类型化 SSE→ptyConnectApiRoutes类型化 WebSocket 升级→instanceApiRoutes其余实例路由→uiRoute裸 catch-all 兜底层组装api.ts 中InstanceHttpApi聚合 21 个 Kilo HttpApi 组含AgentBuilderApi、MemoryApi等 Kilo 自有组并挂载SchemaErrorMiddlewareOpenCodeHttpApi再聚合 Root、Event、Instance、Server 与PtyConnectApi中间件链SchemaErrorMiddleware请求体解码失败 → 截断后的InvalidRequestErrormiddleware/schema-error.tsAuthorization鉴权 各组的InstanceContextMiddleware/WorkspaceRoutingMiddleware错误兜底errorLayer拦截未被声明错误路径覆盖的缺陷输出带ref的NamedError.Unknown保证线上响应永远符合{ name, data }契约文档输出/doc路由懒加载OpenApi.fromApi(PublicApi)并缓存序列化结果server.ts让不提供文档服务的 CLI/脚本进程免于支付构建开销。结语packages/opencode/specs/effect/routes.md虽短却是一份高度凝练的架构契约它把如何写一个 Effect HttpApi 路由收敛为可执行、可审查、可自动校验的规则集而其下的 handlers/、groups/、middleware/、public.ts 则是这份契约的完整实现样本。无论你是要在 Kilo 中新增一个实例端点、重构既有 handler还是研究 Effect HttpApi 在真实大型项目中的工程化落地本文梳理的稳定服务构建期注入 → handler 边界翻译错误 → 端点 schema 显式声明 → 兼容层源 schema 优先治理四步范式都值得作为首要参考。【免费下载链接】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），仅供参考