尧图网页设计 
KiloCode Server 测试指南基于 Effect 的 HttpApi 中间件与路由测试模式【免费下载链接】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本文围绕 KiloCode 仓库中packages/opencode/test/server/AGENTS.md这份服务端测试规范展开系统讲解如何在该目录内编写针对 HttpApi 中间件、路由、代理与工作区路由策略的测试从testEffect构建测试内 HTTP 服务器、用小型HttpApiBuilder探针路由暴露上下文到二级上游服务器的生命周期管理、WebSocket 协议转发断言与全局可变状态的 Scoped 层封装。读完本文你可以在该仓库中独立编写符合规范的 Server 层测试并理解每条约定背后的实现依据。测试目录定位与规范原文Server Test Guide 是packages/opencode/test/server/目录的测试编写规范开篇即声明适用范围Use these patterns for server and HttpApi middleware tests in this directory.该目录包含约 40 个测试文件命名上以httpapi-*为主覆盖授权、压缩、CORS、错误中间件、事件、实例上下文、工作区路由、PTY、SDK 等辅以workspace-proxy.test.ts、workspace-routing.test.ts、session-*.test.ts等。规范给出的 12 条约定可归纳为六类模式测试主服务器testEffectNodeHttpServer.layerTest探针路由小型HttpApiBuilder组暴露被测中间件上下文中间件顺序与生产声明顺序保持一致上游服务器用Layer.build(...)建入当前测试作用域状态管理Scoped 层管理 flag、数据库重置等全局可变状态项目上下文tmpdirScoped({ git: true })Project.use.fromDirectory(dir)。下文逐条展开并结合目录内真实测试文件给出实现证据。主测试服务器testEffect 与 NodeHttpServer.layerTest规范第 6 条要求UsetestEffect(...)withNodeHttpServer.layerTestfor the primary in-test server and make relativeHttpClientrequests against it.testEffect定义于 test/lib/effect.ts它接收一个层并把用户层与测试环境层TestConsole、TestClock合并返回effect假时钟环境与live真实时钟两种测试入口export const testEffect R, E(layer: Layer.LayerR, E) makeR, E(Layer.provideMerge(layer, testEnv), Layer.provideMerge(layer, liveEnv))NodeHttpServer.layerTest来自effect/platform-node是layer的测试变体——监听随机可用端口而不占用固定端口。目录内共享的 httpapi-layer.ts 展示了生产路由如何挂到测试服务器上export const httpApiLayer servedRoutes.pipe( Layer.provide(layerWebSocketConstructorGlobal), Layer.provideMerge(NodeHttpServer.layerTest), Layer.provideMerge(NodeServices.layer), )其中servedRoutes用HttpRouter.serve(HttpApiApp.routes, ...)挂载来自 src/server/routes/instance/httpapi/server 的完整生产路由树。同文件的request辅助函数L21-L27正是“对测试内服务器发起相对路径HttpClient请求”的落地它把http://localhost作为基准 URL 构造HttpClientRequest因此测试中直接写HttpClient.get(/probe)即可命中本地监听端口。在 httpapi-instance-context.test.ts 中可以看到典型装配const it testEffect(Layer.mergeAll(testStateLayer, NodeHttpServer.layerTest, NodeServices.layer, workspaceLayer))四个层分别对应测试状态数据库重置、测试 HTTP 服务器、Node 服务与带运行期 flag 的工作区层。探针路由用微型 HttpApiBuilder 组替代完整 API 树规范第 1、3 条主张测试路由、上下文、代理或中间件策略时优先使用“带微型假路由的聚焦中间件测试”而不是挂载完整 API 路由树用小型HttpApiBuilder探针组声明被测的有类型中间件并暴露上下文如WorkspaceRouteContext、InstanceRef、WorkspaceRef。httpapi-instance-context.test.ts 是该模式的完整范本。探针处理器只读取上下文并回显const probeInstanceContext Effect.gen(function* () { const instance yield* InstanceRef const workspaceID yield* WorkspaceRef return { directory: instance?.directory, worktree: instance?.worktree, projectID: instance?.project.id, workspaceID, } })探针 API 用Schema声明响应结构并挂上两个被测中间件const ProbeApi HttpApi.make(instance-context-probe).add( HttpApiGroup.make(probe) .add( HttpApiEndpoint.get(get, /probe, { query: WorkspaceRoutingQuery, success: ProbeResult }), HttpApiEndpoint.get(session, /session, { query: WorkspaceRoutingQuery, success: ProbeResult }), ... ) .middleware(InstanceContextMiddleware) .middleware(WorkspaceRoutingMiddleware), )注意这里探针只保留三个轻量端点/probe、/session、/dispose-probe却挂上了生产同款中间件链从而可以在不引入完整路由树的前提下断言中间件产出的上下文值。WorkspaceRoutingQuery让端点接受?directory/?workspace查询参数测试因此能通过 URL 直接驱动路由决策。中间件顺序与生产声明顺序一致规范第 4 条要求测试中间件交互时中间件声明顺序必须与生产一致例如InstanceContextMiddleware之后是WorkspaceRoutingMiddleware。从源码结构看探针组中.middleware(InstanceContextMiddleware).middleware(WorkspaceRoutingMiddleware)的链式声明顺序就是生产路由树的镜像。这一约定的价值在测试断言中体现httpapi-instance-context.test.ts 中“uses workspace routing output instead of raw directory hints”用例验证了先由实例上下文中间件解析目录、再由工作区路由中间件覆写目录的级联行为——请求同时携带?workspace...与x-kilo-directory头时最终返回的directory是路由输出的工作区目录而非原始目录提示。若测试中声明顺序颠倒这类交互断言就无法复现生产语义。中间件实现分别位于 src/server/routes/instance/httpapi/middleware/instance-context 与 src/server/routes/instance/httpapi/middleware/workspace-routing测试通过instanceContextLayer、workspaceRoutingLayer装配它们的依赖如Socket.layerWebSocketConstructorGlobal见 L49-L52。二级上游服务器Layer.build 建入当前测试作用域规范第 5 条For secondary upstream servers, build EffectNodeHttpServer.layer(...)into the current test scope withLayer.build(...)so the listener stays alive until the test scope exits.workspace-proxy.test.ts 中的listenTestServer是这一约定的标准实现function listenTestServerE, R(handler: TestHandlerE, R) { return Effect.gen(function* () { // Build into the current test scope so the listener stays alive until the // test finishes. Using Effect.provide here would release it immediately. const context yield* Layer.build(NodeHttpServer.layer(Http.createServer, { host: 127.0.0.1, port: 0 })) const server Context.get(context, HttpServer.HttpServer) yield* server.serve(HttpServerRequest.HttpServerRequest.use(handler)) return HttpServer.formatAddress(server.address) }) }源码注释点明了关键陷阱如果在生成器内直接用Effect.provide挂层层会在 provide 返回后立即释放监听器随即关闭而Layer.build(...)把层构建进当前作用域监听器随作用域存活到测试结束。port: 0让 OS 分配空闲端口HttpServer.formatAddress再把实际端口格式化回http://127.0.0.1:port供测试拼接上游 URL。同一目录的 httpapi-workspace-routing.test.ts 中的listenAdditionalServer采用了相同写法说明这是跨文件的统一约定。坚持 Effect HTTP 栈避免 Bun.serve规范第 10 条明确AvoidBun.servewhen testing Effect HTTP middleware. Keep the test in the Effect HTTP stack unless the production path being tested is Bun-specific.理由从源码结构可以印证本目录所有测试的服务器层都来自NodeHttpServer.layer/NodeHttpServer.layerTesteffect/platform-node请求侧用HttpClient/FetchHttpClientWebSocket 用effect/unstable/socket/Socket。整套断言语境HttpServerResponse、HttpApiProxy、中间件上下文都是 Effect 类型若混入Bun.serve请求链路会脱离 Effect 作用域与层系统无法复用testEffect的生命周期管理。该约束的例外情形是“被测生产路径本身 Bun 专属”——只要生产路径走 Effect HTTP 栈测试也应保持同栈。WebSocket 路径Socket.makeWebSocket 断言协议转发与帧中继规范第 11 条For WebSocket paths, useSocket.makeWebSocket(...)from the test client and assert protocol forwarding or frame relay when relevant.workspace-proxy.test.ts 的 “proxies websocket messages and protocols” 用例给出了完整拓扑Client - proxy listener - HttpApiProxy.websocket - upstream listener上游用echoWebSocket处理程序响应连接建立时回发protocol:协商协议此后对每帧回发echo:帧内容。测试客户端通过Socket.makeWebSocket(proxyUrl, { protocols: chat })连接代理用Queue收帧并断言expect(yield* Queue.take(messages)).toBe(protocol:chat) yield* write(hello) expect(yield* Queue.take(messages)).toBe(echo:hello)第一条断言验证 WebSocket 子协议头Sec-WebSocket-Protocol被正确转发第二条验证帧中继。这种“上游自报协议 逐帧回声”的构造使得转发正确性可以只用消息序列本身证明无需检查网络层。httpapi-pty.test.ts 等 PTY 相关测试也遵循同一Socket.makeWebSocket客户端模式。全局可变状态Scoped 层与 Finalizer 恢复规范第 7 条要求flag、数据库重置等全局可变状态一律使用 Scoped 测试层在 finalizer 中恢复。Flag 覆盖。test/fixture/flag.ts 的withFixedWorkspaceID是标准写法进入时保存旧值通过Effect.addFinalizer在作用域关闭时还原注释中强调这“preserves the original try/finally semantics regardless of test outcome”——无论测试成功或失败都会恢复。httpapi-instance-context.test.ts 用它固定KILO_WORKSPACE_ID验证“配置工作区 ID 优先于路由目标工作区”的策略分支。数据库重置。test/fixture/db.ts 的resetDatabase提供防御性边界const dbPath Database.path() if (dbPath ! :memory:) throw new Error(Refusing to reset non-test database: ${dbPath})拒绝触碰任何磁盘库只有内存库才允许删除及清理-wal/-shm旁路文件。在测试层中它被包进Layer.effectDiscard层创建时重置一次Effect.addFinalizer中再重置一次形成“进入即清、离开即清”的闭环见 httpapi-instance-context.test.ts L33-L43 与 httpapi-workspace-routing.test.ts L39-L48。项目上下文tmpdirScoped 与直连数据库辅助规范第 13 条UsetmpdirScoped({ git: true })plusProject.use.fromDirectory(dir)for project-backed requests.tmpdirScoped定义于 test/fixture/fixture.ts是tmpdir的 Effect 作用域版在os.tmpdir()下创建opencode-test-*随机目录git: true时执行git init、关闭 fsmonitor 与 gpgsign、写入测试身份并提交一个空 root commitconfig选项会写入带$schema的opencode.json清理通过Effect.addFinalizer挂到作用域关闭时先disposeInstancesFor(dir)释放实例与 watcher再停止 git fsmonitor 守护进程并删除目录。配套约定是Project.use.fromDirectory(dir)——用真实目录注册项目而不是直接造数据保证项目 ID、worktree 路径等与生产解析逻辑一致。实例上下文测试中“provides instance context from the routed directory”用例即按此模式const dir yield* tmpdirScoped({ git: true }) const project yield* Project.use.fromDirectory(dir) yield* serveProbe() const response yield* HttpClient.get(/probe?directory${encodeURIComponent(dir)})直连数据库的边界。规范第 14 条当测试需要“有持久化状态但无对应运行期状态”时允许绕过服务直接写库但必须收拢在“窄命名、注释说明该状态含义”的辅助函数中。test/fixture/fixture.ts 的seedProject就是这样一个范例它从InstanceRef取上下文直接db.insert(ProjectTable)种入项目记录onConflictDoNothing命名直白且注释说明了用途——“custom test runtimes need the instance project in their core database”。provideTmpdirProject则把seedProject组合进provideTmpdirInstance供需要“项目行已入库”的请求路径使用。注释要求解释非显然的测试拓扑规范第 15 条对非显然的测试拓扑要加注释尤其是同时涉及本地测试服务器与假上游服务器的测试。workspace-proxy.test.ts 的 WebSocket 用例即示范// Client - proxy listener - HttpApiProxy.websocket - upstream listener. // The client never connects to upstream directly.上游处理函数内部也有说明性注释“The upstream announces the negotiated protocol, then echoes every received frame. The assertions use those messages to prove proxy flow.” 这类注释把“谁连接谁、消息序列证明什么”固化在代码里让后续读者不必逆向推导拓扑。模式速查与适用边界将 12 条规范压缩为一张速查表场景约定做法参考实现聚焦中间件/路由/代理策略微型假路由探针组不挂完整路由树httpapi-instance-context.test.ts主测试服务器testEffectNodeHttpServer.layerTest相对路径HttpClient请求httpapi-layer.ts中间件交互声明顺序与生产一致如 InstanceContext 先于 WorkspaceRoutinghttpapi-instance-context.test.ts L98-L110二级上游服务器Layer.build(NodeHttpServer.layer(...))建入当前作用域workspace-proxy.test.ts L33-L42HTTP 中间件测试不用Bun.serve保持 Effect HTTP 栈目录内全部httpapi-*测试WebSocketSocket.makeWebSocket断言协议转发/帧中继workspace-proxy.test.ts L160-L180flag / 数据库等全局状态Scoped 层 finalizer 恢复flag.ts、db.ts项目支撑型请求tmpdirScoped({ git: true })Project.use.fromDirectory(dir)fixture.ts L150-L195直连数据库收拢在窄命名、带注释的辅助函数中fixture.ts seedProject复杂拓扑注释说明本地服务器与假上游的连接关系workspace-proxy.test.ts L64-L66适用边界需要说明这份规范约束的是packages/opencode/test/server/目录内的测试其前提是生产路径基于 Effect HttpApi 栈HttpRouter.serveNodeHttpServer只有当被测路径本身 Bun 专属时才允许跳出该栈。目录内另有 httpapi-exercise/ 子目录提供了一套 DSL/断言/运行器工具链用于对 API 做批量路由演练属于规范之外的可选基础设施。掌握以上模式后你可以按“探针组声明被测中间件 →testEffect装配测试服务器 → 上游用Layer.build挂入作用域 → 状态走 Scoped 层 → 项目目录用tmpdirScoped注册”的固定骨架在该仓库中新增或评审 Server 层测试并以bun test运行目录内用例验证行为。【免费下载链接】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），仅供参考 KiloCode Server 测试指南：基于 Effect 的 HttpApi 中间件与路由测试模式
KiloCode Server 测试指南基于 Effect 的 HttpApi 中间件与路由测试模式【免费下载链接】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本文围绕 KiloCode 仓库中packages/opencode/test/server/AGENTS.md这份服务端测试规范展开系统讲解如何在该目录内编写针对 HttpApi 中间件、路由、代理与工作区路由策略的测试从testEffect构建测试内 HTTP 服务器、用小型HttpApiBuilder探针路由暴露上下文到二级上游服务器的生命周期管理、WebSocket 协议转发断言与全局可变状态的 Scoped 层封装。读完本文你可以在该仓库中独立编写符合规范的 Server 层测试并理解每条约定背后的实现依据。测试目录定位与规范原文Server Test Guide 是packages/opencode/test/server/目录的测试编写规范开篇即声明适用范围Use these patterns for server and HttpApi middleware tests in this directory.该目录包含约 40 个测试文件命名上以httpapi-*为主覆盖授权、压缩、CORS、错误中间件、事件、实例上下文、工作区路由、PTY、SDK 等辅以workspace-proxy.test.ts、workspace-routing.test.ts、session-*.test.ts等。规范给出的 12 条约定可归纳为六类模式测试主服务器testEffectNodeHttpServer.layerTest探针路由小型HttpApiBuilder组暴露被测中间件上下文中间件顺序与生产声明顺序保持一致上游服务器用Layer.build(...)建入当前测试作用域状态管理Scoped 层管理 flag、数据库重置等全局可变状态项目上下文tmpdirScoped({ git: true })Project.use.fromDirectory(dir)。下文逐条展开并结合目录内真实测试文件给出实现证据。主测试服务器testEffect 与 NodeHttpServer.layerTest规范第 6 条要求UsetestEffect(...)withNodeHttpServer.layerTestfor the primary in-test server and make relativeHttpClientrequests against it.testEffect定义于 test/lib/effect.ts它接收一个层并把用户层与测试环境层TestConsole、TestClock合并返回effect假时钟环境与live真实时钟两种测试入口export const testEffect R, E(layer: Layer.LayerR, E) makeR, E(Layer.provideMerge(layer, testEnv), Layer.provideMerge(layer, liveEnv))NodeHttpServer.layerTest来自effect/platform-node是layer的测试变体——监听随机可用端口而不占用固定端口。目录内共享的 httpapi-layer.ts 展示了生产路由如何挂到测试服务器上export const httpApiLayer servedRoutes.pipe( Layer.provide(layerWebSocketConstructorGlobal), Layer.provideMerge(NodeHttpServer.layerTest), Layer.provideMerge(NodeServices.layer), )其中servedRoutes用HttpRouter.serve(HttpApiApp.routes, ...)挂载来自 src/server/routes/instance/httpapi/server 的完整生产路由树。同文件的request辅助函数L21-L27正是“对测试内服务器发起相对路径HttpClient请求”的落地它把http://localhost作为基准 URL 构造HttpClientRequest因此测试中直接写HttpClient.get(/probe)即可命中本地监听端口。在 httpapi-instance-context.test.ts 中可以看到典型装配const it testEffect(Layer.mergeAll(testStateLayer, NodeHttpServer.layerTest, NodeServices.layer, workspaceLayer))四个层分别对应测试状态数据库重置、测试 HTTP 服务器、Node 服务与带运行期 flag 的工作区层。探针路由用微型 HttpApiBuilder 组替代完整 API 树规范第 1、3 条主张测试路由、上下文、代理或中间件策略时优先使用“带微型假路由的聚焦中间件测试”而不是挂载完整 API 路由树用小型HttpApiBuilder探针组声明被测的有类型中间件并暴露上下文如WorkspaceRouteContext、InstanceRef、WorkspaceRef。httpapi-instance-context.test.ts 是该模式的完整范本。探针处理器只读取上下文并回显const probeInstanceContext Effect.gen(function* () { const instance yield* InstanceRef const workspaceID yield* WorkspaceRef return { directory: instance?.directory, worktree: instance?.worktree, projectID: instance?.project.id, workspaceID, } })探针 API 用Schema声明响应结构并挂上两个被测中间件const ProbeApi HttpApi.make(instance-context-probe).add( HttpApiGroup.make(probe) .add( HttpApiEndpoint.get(get, /probe, { query: WorkspaceRoutingQuery, success: ProbeResult }), HttpApiEndpoint.get(session, /session, { query: WorkspaceRoutingQuery, success: ProbeResult }), ... ) .middleware(InstanceContextMiddleware) .middleware(WorkspaceRoutingMiddleware), )注意这里探针只保留三个轻量端点/probe、/session、/dispose-probe却挂上了生产同款中间件链从而可以在不引入完整路由树的前提下断言中间件产出的上下文值。WorkspaceRoutingQuery让端点接受?directory/?workspace查询参数测试因此能通过 URL 直接驱动路由决策。中间件顺序与生产声明顺序一致规范第 4 条要求测试中间件交互时中间件声明顺序必须与生产一致例如InstanceContextMiddleware之后是WorkspaceRoutingMiddleware。从源码结构看探针组中.middleware(InstanceContextMiddleware).middleware(WorkspaceRoutingMiddleware)的链式声明顺序就是生产路由树的镜像。这一约定的价值在测试断言中体现httpapi-instance-context.test.ts 中“uses workspace routing output instead of raw directory hints”用例验证了先由实例上下文中间件解析目录、再由工作区路由中间件覆写目录的级联行为——请求同时携带?workspace...与x-kilo-directory头时最终返回的directory是路由输出的工作区目录而非原始目录提示。若测试中声明顺序颠倒这类交互断言就无法复现生产语义。中间件实现分别位于 src/server/routes/instance/httpapi/middleware/instance-context 与 src/server/routes/instance/httpapi/middleware/workspace-routing测试通过instanceContextLayer、workspaceRoutingLayer装配它们的依赖如Socket.layerWebSocketConstructorGlobal见 L49-L52。二级上游服务器Layer.build 建入当前测试作用域规范第 5 条For secondary upstream servers, build EffectNodeHttpServer.layer(...)into the current test scope withLayer.build(...)so the listener stays alive until the test scope exits.workspace-proxy.test.ts 中的listenTestServer是这一约定的标准实现function listenTestServerE, R(handler: TestHandlerE, R) { return Effect.gen(function* () { // Build into the current test scope so the listener stays alive until the // test finishes. Using Effect.provide here would release it immediately. const context yield* Layer.build(NodeHttpServer.layer(Http.createServer, { host: 127.0.0.1, port: 0 })) const server Context.get(context, HttpServer.HttpServer) yield* server.serve(HttpServerRequest.HttpServerRequest.use(handler)) return HttpServer.formatAddress(server.address) }) }源码注释点明了关键陷阱如果在生成器内直接用Effect.provide挂层层会在 provide 返回后立即释放监听器随即关闭而Layer.build(...)把层构建进当前作用域监听器随作用域存活到测试结束。port: 0让 OS 分配空闲端口HttpServer.formatAddress再把实际端口格式化回http://127.0.0.1:port供测试拼接上游 URL。同一目录的 httpapi-workspace-routing.test.ts 中的listenAdditionalServer采用了相同写法说明这是跨文件的统一约定。坚持 Effect HTTP 栈避免 Bun.serve规范第 10 条明确AvoidBun.servewhen testing Effect HTTP middleware. Keep the test in the Effect HTTP stack unless the production path being tested is Bun-specific.理由从源码结构可以印证本目录所有测试的服务器层都来自NodeHttpServer.layer/NodeHttpServer.layerTesteffect/platform-node请求侧用HttpClient/FetchHttpClientWebSocket 用effect/unstable/socket/Socket。整套断言语境HttpServerResponse、HttpApiProxy、中间件上下文都是 Effect 类型若混入Bun.serve请求链路会脱离 Effect 作用域与层系统无法复用testEffect的生命周期管理。该约束的例外情形是“被测生产路径本身 Bun 专属”——只要生产路径走 Effect HTTP 栈测试也应保持同栈。WebSocket 路径Socket.makeWebSocket 断言协议转发与帧中继规范第 11 条For WebSocket paths, useSocket.makeWebSocket(...)from the test client and assert protocol forwarding or frame relay when relevant.workspace-proxy.test.ts 的 “proxies websocket messages and protocols” 用例给出了完整拓扑Client - proxy listener - HttpApiProxy.websocket - upstream listener上游用echoWebSocket处理程序响应连接建立时回发protocol:协商协议此后对每帧回发echo:帧内容。测试客户端通过Socket.makeWebSocket(proxyUrl, { protocols: chat })连接代理用Queue收帧并断言expect(yield* Queue.take(messages)).toBe(protocol:chat) yield* write(hello) expect(yield* Queue.take(messages)).toBe(echo:hello)第一条断言验证 WebSocket 子协议头Sec-WebSocket-Protocol被正确转发第二条验证帧中继。这种“上游自报协议 逐帧回声”的构造使得转发正确性可以只用消息序列本身证明无需检查网络层。httpapi-pty.test.ts 等 PTY 相关测试也遵循同一Socket.makeWebSocket客户端模式。全局可变状态Scoped 层与 Finalizer 恢复规范第 7 条要求flag、数据库重置等全局可变状态一律使用 Scoped 测试层在 finalizer 中恢复。Flag 覆盖。test/fixture/flag.ts 的withFixedWorkspaceID是标准写法进入时保存旧值通过Effect.addFinalizer在作用域关闭时还原注释中强调这“preserves the original try/finally semantics regardless of test outcome”——无论测试成功或失败都会恢复。httpapi-instance-context.test.ts 用它固定KILO_WORKSPACE_ID验证“配置工作区 ID 优先于路由目标工作区”的策略分支。数据库重置。test/fixture/db.ts 的resetDatabase提供防御性边界const dbPath Database.path() if (dbPath ! :memory:) throw new Error(Refusing to reset non-test database: ${dbPath})拒绝触碰任何磁盘库只有内存库才允许删除及清理-wal/-shm旁路文件。在测试层中它被包进Layer.effectDiscard层创建时重置一次Effect.addFinalizer中再重置一次形成“进入即清、离开即清”的闭环见 httpapi-instance-context.test.ts L33-L43 与 httpapi-workspace-routing.test.ts L39-L48。项目上下文tmpdirScoped 与直连数据库辅助规范第 13 条UsetmpdirScoped({ git: true })plusProject.use.fromDirectory(dir)for project-backed requests.tmpdirScoped定义于 test/fixture/fixture.ts是tmpdir的 Effect 作用域版在os.tmpdir()下创建opencode-test-*随机目录git: true时执行git init、关闭 fsmonitor 与 gpgsign、写入测试身份并提交一个空 root commitconfig选项会写入带$schema的opencode.json清理通过Effect.addFinalizer挂到作用域关闭时先disposeInstancesFor(dir)释放实例与 watcher再停止 git fsmonitor 守护进程并删除目录。配套约定是Project.use.fromDirectory(dir)——用真实目录注册项目而不是直接造数据保证项目 ID、worktree 路径等与生产解析逻辑一致。实例上下文测试中“provides instance context from the routed directory”用例即按此模式const dir yield* tmpdirScoped({ git: true }) const project yield* Project.use.fromDirectory(dir) yield* serveProbe() const response yield* HttpClient.get(/probe?directory${encodeURIComponent(dir)})直连数据库的边界。规范第 14 条当测试需要“有持久化状态但无对应运行期状态”时允许绕过服务直接写库但必须收拢在“窄命名、注释说明该状态含义”的辅助函数中。test/fixture/fixture.ts 的seedProject就是这样一个范例它从InstanceRef取上下文直接db.insert(ProjectTable)种入项目记录onConflictDoNothing命名直白且注释说明了用途——“custom test runtimes need the instance project in their core database”。provideTmpdirProject则把seedProject组合进provideTmpdirInstance供需要“项目行已入库”的请求路径使用。注释要求解释非显然的测试拓扑规范第 15 条对非显然的测试拓扑要加注释尤其是同时涉及本地测试服务器与假上游服务器的测试。workspace-proxy.test.ts 的 WebSocket 用例即示范// Client - proxy listener - HttpApiProxy.websocket - upstream listener. // The client never connects to upstream directly.上游处理函数内部也有说明性注释“The upstream announces the negotiated protocol, then echoes every received frame. The assertions use those messages to prove proxy flow.” 这类注释把“谁连接谁、消息序列证明什么”固化在代码里让后续读者不必逆向推导拓扑。模式速查与适用边界将 12 条规范压缩为一张速查表场景约定做法参考实现聚焦中间件/路由/代理策略微型假路由探针组不挂完整路由树httpapi-instance-context.test.ts主测试服务器testEffectNodeHttpServer.layerTest相对路径HttpClient请求httpapi-layer.ts中间件交互声明顺序与生产一致如 InstanceContext 先于 WorkspaceRoutinghttpapi-instance-context.test.ts L98-L110二级上游服务器Layer.build(NodeHttpServer.layer(...))建入当前作用域workspace-proxy.test.ts L33-L42HTTP 中间件测试不用Bun.serve保持 Effect HTTP 栈目录内全部httpapi-*测试WebSocketSocket.makeWebSocket断言协议转发/帧中继workspace-proxy.test.ts L160-L180flag / 数据库等全局状态Scoped 层 finalizer 恢复flag.ts、db.ts项目支撑型请求tmpdirScoped({ git: true })Project.use.fromDirectory(dir)fixture.ts L150-L195直连数据库收拢在窄命名、带注释的辅助函数中fixture.ts seedProject复杂拓扑注释说明本地服务器与假上游的连接关系workspace-proxy.test.ts L64-L66适用边界需要说明这份规范约束的是packages/opencode/test/server/目录内的测试其前提是生产路径基于 Effect HttpApi 栈HttpRouter.serveNodeHttpServer只有当被测路径本身 Bun 专属时才允许跳出该栈。目录内另有 httpapi-exercise/ 子目录提供了一套 DSL/断言/运行器工具链用于对 API 做批量路由演练属于规范之外的可选基础设施。掌握以上模式后你可以按“探针组声明被测中间件 →testEffect装配测试服务器 → 上游用Layer.build挂入作用域 → 状态走 Scoped 层 → 项目目录用tmpdirScoped注册”的固定骨架在该仓库中新增或评审 Server 层测试并以bun test运行目录内用例验证行为。【免费下载链接】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），仅供参考