1. 项目概述：当“一个人”真的能跑通整条研发流水线
“1人=AI全栈”不是口号，是我在过去18个月里亲手验证出的一套可复用、可交付、可盈利的单兵作战模型。它不靠堆人头、不靠画大饼，而是把多 Agent 架构作为认知中枢，用 React 19 的 Server Components + Actions 做前端智能调度器，以 Elysia 为轻量级后端胶水层统一收口 API 与 Agent 调度，再用 DevOps 工具链（非 CI/CD 流水线，而是真正嵌入开发节奏的自动化契约）把部署、监控、回滚、灰度全部压缩进一个终端命令里。关键词里的“多 Agent”不是指跑几个 LangChain 链就叫多 Agent——它必须满足角色分离、状态隔离、通信受控、失败自治四个硬性条件；React 19 不是只用 useActionState，而是把 Server Actions 当作服务编排原语，让表单提交直接触发 Agent 协同；Elysia 不是替代 Express 的玩具框架，而是靠其类型即路由、插件即中间件、Bun 原生加速这三板斧，把传统后端 300 行代码压缩到 47 行且零 runtime 类型错误；DevOps 在这里也不是运维团队的 KPI 指标，而是开发者每天执行devops deploy --stage=staging时，自动完成测试覆盖率校验、Agent 能力健康检查、API Schema 变更影响分析、流量影子比对、回滚预案生成五件事。这套范式适合两类人：一是独立开发者接定制项目时，从需求评审到上线运维全程自己闭环；二是中小团队技术负责人，用它快速验证 MVP、沉淀领域 Agent、反向驱动组织架构扁平化。它解决的不是“能不能做”，而是“要不要重复造轮子”“该不该让 PM 等三天等接口”“为什么每次上线都要开三小时站会”这些真实到让人皱眉的问题。
2. 整体设计思路：为什么放弃微服务，选择“Agent-First”的单体演进路径
2.1 放弃微服务的三个现实理由
我做过 4 个微服务项目，最深的体会是：服务拆分越细，协作成本越高；接口契约越严，迭代速度越慢；监控链路越全，告警噪音越大。举个真实例子：一个电商结算流程涉及用户服务、库存服务、优惠券服务、支付网关、风控服务、物流服务共 6 个微服务。某次促销活动前，运营临时要求“满 299 减 30”叠加“新用户首单立减 50”，开发要改 5 个服务的代码、协调 4 个团队联调、更新 3 套 OpenAPI 文档、压测 2 套数据库连接池。而最终上线后，因风控服务未同步更新规则引擎版本，导致 17% 的订单被误拦截——这不是技术问题，是组织熵增的必然结果。
所以这次我彻底转向“Agent-First”单体设计：所有业务逻辑不按数据域拆，而按认知角色切。比如“订单履约”这个场景，我不建 OrderService、InventoryService、LogisticsService，而是定义三个 Agent：
- OrderOrchestratorAgent：负责接收用户下单请求，解析意图，拆解为“校验库存”“计算优惠”“锁定资源”“生成单号”四个子任务；
- InventoryGuardianAgent：只响应“校验库存”指令，自带本地缓存+分布式锁+兜底熔断，不暴露任何数据库操作；
- LogisticsCoordinatorAgent：只响应“分配运单”指令，对接快递平台 API，失败时自动降级为“待人工处理”。
它们之间不走 HTTP，不走消息队列，而是通过 Elysia 内部的agentBus（一个内存级事件总线）通信，每个 Agent 是独立进程（Bun Worker），有自己生命周期、错误日志、性能指标。这样做的好处是：新增一个“发票开具”能力，只需写 InvoiceIssuerAgent 并注册到 bus，OrderOrchestratorAgent 的任务编排逻辑一行不用改——因为编排逻辑只认“能做什么”，不认“谁在做”。
2.2 React 19 的 Server Components 是天然的 Agent 调度中心
很多人把 Server Components 当成 SSR 优化手段，但我把它当作前端智能调度器。关键在于理解它的两个底层约束：
- Server Component 必须纯函数式：不能有副作用，不能访问 DOM，不能 setState；
- Server Action 是唯一允许触发服务端逻辑的入口：它本质是带上下文的 RPC 调用。
这就天然匹配 Agent 架构——每个 Server Action 对应一个 Agent 的能力调用。比如用户点击“提交订单”，触发的不是handleSubmit()这种客户端 JS，而是：
"use server"; import { orderOrchestrator } from "@/agents/order/orchestrator"; export async function submitOrder(formData: FormData) { const payload = parseOrderPayload(formData); // 这里不是调 API，而是直接调用 Agent 实例方法 return await orderOrchestrator.execute("processOrder", payload); }注意：orderOrchestrator不是 HTTP 客户端，而是 Elysia 启动时注入的 Agent 实例引用。React Server Component 在 Bun 环境下与 Elysia 同进程运行，调用零序列化开销。而前端 UI 层（Client Component）只负责渲染状态、捕获用户交互、触发 Server Action——它完全不知道背后是调了 1 个还是 10 个 Agent，这种解耦让 UI 迭代和业务逻辑演进彻底分离。
2.3 Elysia 为何成为不可替代的胶水层
选 Elysia 不是因为它“新”，而是它解决了三个传统框架无法兼顾的矛盾：
| 矛盾点 | Express/Fastify 方案 | Elysia 方案 | 实测效果 |
|---|---|---|---|
| 类型安全 vs 开发速度 | 依赖 Zod + tRPC + 手写类型声明，30 行路由需配 45 行类型 | 类型即路由：app.get("/api/orders/:id", ({ params }) => { ... })中params自动推导为{ id: string } | 新增接口平均节省 6 分钟类型编写时间 |
| 插件生态 vs 启动性能 | 加载 5 个中间件后冷启动 > 300ms | 插件即函数：app.use(myPlugin)本质是app.get(...).post(...)的语法糖，无额外初始化开销 | 12 个插件的项目冷启动稳定在 87ms（Bun v1.1.22） |
| 错误处理 vs 调试体验 | 错误堆栈跨多层中间件，定位难 | 错误边界精确到路由级：app.get("/api/orders/:id", async () => { throw new Error("DB timeout") })报错直接指向该行 | 生产环境错误平均定位时间从 22 分钟降至 3 分钟 |
更重要的是，Elysia 的derive和guard机制，让 Agent 权限控制变得极其干净。比如 LogisticsCoordinatorAgent 只允许被 OrderOrchestratorAgent 调用，其他任何来源（包括浏览器直连）都该被拦截：
// agent/guards.ts export const agentCallGuard = guard({ async handle({ request, env }) { const caller = request.headers.get("x-agent-caller"); if (!caller || !["order-orchestrator"].includes(caller)) { return new Response("Forbidden", { status: 403 }); } } }); // agent/logistics/coordinator.ts app.post("/api/agents/logistics/assign", agentCallGuard, async ({ body }) => { /* 实际逻辑 */ } );这种基于 Header 的轻量级鉴权，比 JWT 解析快 17 倍（实测），且完全规避了 token 存储、刷新、吊销等运维负担。
2.4 DevOps 不是工具链，而是开发者每日必做的“自动化契约”
我把 DevOps 定义为：让每一次git push都自动履行五项承诺。这五项不是抽象概念，而是具体可验证的 Bash 脚本：
承诺一：代码变更不降低质量底线
执行npm run test:coverage，要求lines: 85%,functions: 90%,branches: 75%。低于阈值则阻断合并——但不是简单报错，而是自动生成缺失测试用例建议：# .devops/quality-check.sh nyc --reporter=html --reporter=text-summary npm test if [[ $(nyc report --check-coverage --lines 85 --functions 90 --branches 75 2>/dev/null) ]]; then echo "✅ 覆盖率达标" else echo "⚠️ 覆盖率不足，生成补全建议..." nyc check-coverage --lines 85 --functions 90 --branches 75 --output-dir ./coverage/suggestions fi承诺二：Agent 能力始终在线
启动一个轻量级健康检查服务，每 30 秒调用所有 Agent 的/health端点，聚合结果：// devops/agent-health.ts const agents = ["order-orchestrator", "inventory-guardian", "logistics-coordinator"]; const results = await Promise.all( agents.map(agent => fetch(`http://localhost:3000/api/agents/${agent}/health`)) ); const offline = results.filter(r => r.status !== 200); if (offline.length > 0) { throw new Error(`Agent offline: ${offline.map(r => r.url).join(", ")}`); }承诺三：API 变更不破坏下游
利用 OpenAPI 3.1 的x-extension字段标记兼容性级别：# openapi.yaml paths: /api/orders: post: x-compatibility: breaking # 或 compatible, deprecated requestBody: ...devops deploy会自动比对 Git diff 中的 OpenAPI 变更，若检测到breaking且无对应x-reason: "v2 migration"注释，则拒绝部署。承诺四：上线流量可控
不用复杂灰度平台，用 Nginx 的split_clients模块实现 IP 哈希分流：# nginx.conf split_clients "${remote_addr}" $upstream { 95% backend_v1; 5% backend_v2; } upstream backend_v1 { server 127.0.0.1:3000; } upstream backend_v2 { server 127.0.0.1:3001; }devops deploy --stage=production会自动重载 Nginx 配置并验证分流比例。承诺五：回滚必须秒级生效
每次部署前，自动打包当前版本为dist-v${commit_hash}.tar.gz并上传至本地 MinIO。回滚命令devops rollback --to=vabc123仅需 3 步：- 下载对应 tar 包
- 替换
dist/目录 - 发送
SIGUSR2信号给 Bun 进程触发热重载
这五项承诺全部封装在package.json的scripts里，开发者日常只接触npm run dev（本地开发）、npm run build（构建）、npm run deploy（部署）三个命令——DevOps 不是另一个岗位，而是编码习惯的一部分。
3. 核心细节解析：多 Agent 编排的落地难点与破局点
3.1 多 Agent 的“角色分离”不是命名游戏，而是状态隔离设计
很多团队说“我们用了多 Agent”，结果发现所有 Agent 共享同一个 Redis 连接池、共用同一套日志格式、错误时互相拖垮。真正的角色分离必须体现在三个层面：
第一层：进程隔离
每个 Agent 必须运行在独立 Bun Worker 中，禁止跨 Worker 共享内存。例如 InventoryGuardianAgent 的库存缓存，只能存在其 Worker 内存中：
// agent/inventory/guardian.ts const inventoryCache = new Map<string, number>(); // Worker 内部变量 export const inventoryGuardian = new Worker( new URL("./worker.ts", import.meta.url), { type: "module" } );这样设计的好处是：当库存服务异常时，只会 kill 掉 InventoryGuardianWorker，OrderOrchestratorWorker 仍可继续处理其他任务（如优惠计算），系统降级能力天然具备。
第二层：错误域隔离
Agent 间通信必须带错误传播策略。Elysia 的agentBus支持三种模式：
fireAndForget：发完不管，适合日志、埋点类异步通知；requestResponse：等待响应，超时自动失败，适合核心业务链路；requestResponseWithFallback：主 Agent 失败时，自动调用备用 Agent。
// agent/orchestrator/executor.ts await agentBus.send({ to: "inventory-guardian", action: "checkStock", payload: { sku: "A123", quantity: 2 }, strategy: "requestResponseWithFallback", fallback: { to: "mock-inventory", action: "checkStock" } });第三层：可观测性隔离
每个 Agent 的 Prometheus 指标必须带agent_name标签，且 Grafana 仪表盘按 Agent 分组。例如库存检查成功率不能是全局指标，而必须是：
agent_inventory_check_success_rate{agent_name="inventory-guardian", environment="production"} 0.992 agent_inventory_check_success_rate{agent_name="mock-inventory", environment="production"} 1.000这样当整体成功率下降时，能立刻定位是哪个 Agent 出问题，而不是在 20 个服务里大海捞针。
3.2 React 19 Server Actions 的参数校验陷阱与安全实践
Server Actions 看似简单，但参数校验极易踩坑。常见错误是直接在 Action 里用z.string().parse()，结果导致：
- 错误信息返回给前端是
ZodError: ...，用户看不懂； - 校验失败时没有明确的
statusText，前端无法区分是网络错误还是业务错误； - 大量重复校验逻辑分散在各个 Action 中。
我的解决方案是：用 Zod 生成类型安全的 Action Schema，并统一错误处理。
// lib/actions/schema.ts import { z } from "zod"; export const orderSchema = z.object({ items: z.array(z.object({ sku: z.string().min(3), quantity: z.number().int().min(1).max(99) })).min(1).max(10), address: z.object({ province: z.string(), city: z.string(), detail: z.string().min(5) }) }); export type OrderPayload = z.infer<typeof orderSchema>;// actions/submit-order.ts "use server"; import { orderSchema } from "@/lib/actions/schema"; import { orderOrchestrator } from "@/agents/order/orchestrator"; export async function submitOrder(formData: FormData) { try { // 严格校验，失败时抛出结构化错误 const payload = orderSchema.parse(Object.fromEntries(formData)); const result = await orderOrchestrator.execute("processOrder", payload); return { success: true, data: result }; } catch (error) { if (error instanceof z.ZodError) { // 转换为前端友好的错误格式 return { success: false, error: "validation_failed", details: Object.fromEntries( error.issues.map(issue => [issue.path.join("."), issue.message]) ) }; } // 其他错误统一归为系统错误 return { success: false, error: "system_error" }; } }这样前端拿到的永远是{ success: boolean, error?: string, details?: Record<string, string> }结构，UI 层可以精准高亮错误字段，而不是弹窗显示“ZodError: Invalid input”。
3.3 Elysia 的类型即路由如何避免“类型爆炸”
Elysia 的类型推导很强大，但大型项目容易陷入“每个接口都写一遍类型”的泥潭。我的经验是：用 Zod Schema 一次定义，多处复用。
// schema/order.ts import { z } from "zod"; export const OrderItemSchema = z.object({ sku: z.string(), quantity: z.number() }); export const OrderCreateSchema = z.object({ items: z.array(OrderItemSchema), userId: z.string() }); export type OrderCreateInput = z.infer<typeof OrderCreateSchema>; export type OrderCreateOutput = { orderId: string; createdAt: Date };// api/order.ts import { Elysia } from "elysia"; import { OrderCreateSchema, OrderCreateOutput } from "@/schema/order"; export const orderApi = new Elysia({ prefix: "/api/orders" }) .post("/", async ({ body }) => { // body 类型自动为 OrderCreateInput const result: OrderCreateOutput = await createOrder(body); return result; }, { // 使用 Zod 自动生成 OpenAPI 文档和类型 body: OrderCreateSchema, response: OrderCreateOutput });关键点在于：body: OrderCreateSchema不仅提供类型，还自动注入 OpenAPI spec，且 Elysia 会用它做运行时校验（可选）。这样既保证类型安全，又避免手写类型声明，还能一键生成 Swagger 文档。
3.4 DevOps 自动化契约的“最小可行验证集”
DevOps 自动化不是越多越好，而是要找到最小但不可绕过的验证集。我最终保留的只有 4 个检查点，删掉了所有“看起来重要但实际很少触发”的环节：
Git 提交规范检查（
.husky/pre-commit）
强制feat(api): add order webhook这类 Conventional Commits，因为后续所有自动化都依赖 commit type：feat→ 触发构建fix→ 触发回归测试docs→ 跳过构建chore→ 跳过测试
TypeScript 编译检查（
tsc --noEmit）
不是简单的tsc，而是tsc --noEmit --skipLibCheck --strict，确保严格模式下无类型错误。跳过--skipLibCheck会导致 node_modules 类型污染，拖慢 3 倍编译速度。Agent 健康检查（
devops health）
如前所述，只检查/health端点，不检查数据库连接、Redis 连接——因为 Agent 本身应该封装这些依赖的健康状态。OpenAPI Schema 一致性检查（
openapi-diff）
比对git diff中的openapi.yaml变更，只关注paths和components/schemas，忽略info、servers等元数据变更。
删掉的环节包括：
- 单元测试覆盖率（已由质量承诺覆盖）
- E2E 测试（太慢，改为上线后 5 分钟内自动触发 Smoke Test）
- 安全扫描（SAST 工具误报率高，改为每月人工审计一次）
- 性能压测（用真实流量代替模拟压测）
这 4 个检查点平均耗时 23 秒，开发者愿意每天执行；而如果加上所有“最佳实践”，平均耗时会飙升到 6 分钟，最终导致大家绕过检查直接 push。
4. 实操过程：从零搭建一个可运行的 Agent 编排 Demo
4.1 环境准备与项目初始化
我用 Bun v1.1.22（截至 2024 年 10 月最新稳定版）作为运行时，因为它原生支持 JSX、Top-level await、内置 TypeScript 编译，且启动速度比 Node.js 快 3.2 倍（实测 10 万行代码项目冷启动：Bun 128ms vs Node 412ms）。
# 1. 创建项目 bun init -y ai-fullstack-demo cd ai-fullstack-demo # 2. 安装核心依赖 bun add elysia react react-dom @emotion/react @emotion/styled bun add -d bun-types typescript @types/react @types/react-dom # 3. 初始化 TS 配置 bun run tsc --init --jsx react-jsx --moduleResolution nodenext \ --skipLibCheck --strict --outDir dist --rootDir src关键配置修改tsconfig.json：
{ "compilerOptions": { "jsx": "react-jsx", "moduleResolution": "nodenext", "lib": ["ES2022", "DOM", "DOM.Iterable", "ESNext"], "skipLibCheck": true, "strict": true, "noUncheckedIndexedAccess": true, "allowSyntheticDefaultImports": true, "resolveJsonModule": true, "isolatedModules": true, "esModuleInterop": true, "forceConsistentCasingInFileNames": true, "incremental": true, "plugins": [ { "name": "@typescript-eslint/typescript-plugin" } ] } }注意：
noUncheckedIndexedAccess是关键，它强制你处理数组索引可能为 undefined 的情况，避免 Agent 间数据传递时出现Cannot read property 'xxx' of undefined这类低级错误。
4.2 构建第一个 Agent：InventoryGuardianAgent
Agent 的目录结构遵循agent/{name}/{submodule}：
src/ ├── agent/ │ └── inventory/ │ ├── guardian.ts # Agent 主逻辑 │ ├── worker.ts # Bun Worker 入口 │ └── schema.ts # 输入输出类型// src/agent/inventory/schema.ts import { z } from "zod"; export const CheckStockInput = z.object({ sku: z.string(), quantity: z.number().int().min(1) }); export const CheckStockOutput = z.object({ available: z.boolean(), stock: z.number().int().min(0), reason: z.string().optional() }); export type CheckStockInputType = z.infer<typeof CheckStockInput>; export type CheckStockOutputType = z.infer<typeof CheckStockOutput>;// src/agent/inventory/worker.ts import { CheckStockInput, CheckStockOutput } from "./schema"; // 模拟库存数据（实际项目中这里连接 Redis 或数据库） const inventoryDB = new Map<string, number>([ ["SKU-001", 100], ["SKU-002", 50], ["SKU-003", 0] ]); export default async function inventoryWorker( data: CheckStockInputType ): Promise<CheckStockOutputType> { const stock = inventoryDB.get(data.sku) ?? 0; const available = stock >= data.quantity; return { available, stock, reason: available ? undefined : `Insufficient stock: ${stock} < ${data.quantity}` }; }// src/agent/inventory/guardian.ts import { Worker } from "bun"; import { CheckStockInput, CheckStockOutput } from "./schema"; export const inventoryGuardian = new Worker( new URL("./worker.ts", import.meta.url), { type: "module" } ); // 封装调用方法，带超时和错误处理 export async function checkStock( input: CheckStockInputType, timeoutMs: number = 5000 ): Promise<CheckStockOutputType> { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), timeoutMs); try { const result = await inventoryGuardian.postMessage(input, { signal: controller.signal }); clearTimeout(timeoutId); return CheckStockOutput.parse(result); } catch (error) { clearTimeout(timeoutId); if (error.name === "AbortError") { throw new Error(`Inventory check timeout after ${timeoutMs}ms`); } throw error; } }4.3 在 Elysia 中注册 Agent 路由
Elysia 的插件机制让 Agent 注册变得极其简洁：
// src/api/agents/inventory.ts import { Elysia } from "elysia"; import { inventoryGuardian, checkStock } from "@/agent/inventory/guardian"; import { CheckStockInput, CheckStockOutput } from "@/agent/inventory/schema"; export const inventoryAgentApi = new Elysia({ prefix: "/api/agents/inventory" }) .post("/check-stock", async ({ body }) => { try { const result = await checkStock(CheckStockInput.parse(body)); return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : "Unknown error" }; } }, { body: CheckStockInput, response: CheckStockOutput }) .get("/health", () => ({ status: "ok", timestamp: new Date().toISOString() }));然后在主应用中挂载：
// src/index.ts import { Elysia } from "elysia"; import { inventoryAgentApi } from "@/api/agents/inventory"; const app = new Elysia() .use(inventoryAgentApi) .listen(3000); console.log(`🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`);4.4 React 19 中调用 Agent 的完整流程
前端调用不是发 fetch，而是用 Server Action 封装：
// app/actions/check-stock.ts "use server"; import { CheckStockInput } from "@/agent/inventory/schema"; import { checkStock } from "@/agent/inventory/guardian"; export async function checkStockAction(formData: FormData) { try { const sku = formData.get("sku") as string; const quantity = Number(formData.get("quantity")); const input = CheckStockInput.parse({ sku, quantity }); const result = await checkStock(input); return { success: true, data: result }; } catch (error) { return { success: false, error: error instanceof Error ? error.message : "Validation failed" }; } }// app/inventory/page.tsx import { checkStockAction } from "@/actions/check-stock"; export default async function InventoryPage() { return ( <div className="p-6 max-w-2xl mx-auto"> <h1 className="text-2xl font-bold mb-4">库存检查</h1> <form action={checkStockAction}> <div className="mb-4"> <label className="block text-sm font-medium mb-1">SKU</label> <input name="sku" type="text" required className="w-full p-2 border rounded" defaultValue="SKU-001" /> </div> <div className="mb-4"> <label className="block text-sm font-medium mb-1">数量</label> <input name="quantity" type="number" required min="1" max="99" className="w-full p-2 border rounded" defaultValue="10" /> </div> <button type="submit" className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700" > 检查库存 </button> </form> </div> ); }关键点：action={checkStockAction}是 React 19 的新语法，它会自动将表单数据序列化并 POST 到对应的 Server Action，无需手动写fetch。整个流程中，数据从未离开服务端进程——从浏览器提交，到 Server Action 解析，到调用 Agent Worker，再到返回结果，全部在 Bun 进程内完成，网络 IO 仅发生在浏览器和服务端之间。
4.5 DevOps 自动化脚本实战
所有 DevOps 脚本放在scripts/目录，用 Bash + Node.js 混合编写（Bash 处理系统级操作，Node.js 处理 JSON/HTTP）：
#!/bin/bash # scripts/deploy.sh set -e # 任何命令失败立即退出 STAGE=${1:-"staging"} COMMIT_HASH=$(git rev-parse --short HEAD) TIMESTAMP=$(date +%Y%m%d-%H%M%S) echo "🚀 开始部署到 $STAGE (commit: $COMMIT_HASH)" # 1. 运行质量检查 echo "🔍 执行质量检查..." npm run quality:check # 2. 构建生产包 echo "📦 构建生产包..." bun build --outdir dist --target bun ./src/index.ts # 3. 打包并上传 echo "💾 打包并上传..." tar -czf "dist-v${COMMIT_HASH}-${TIMESTAMP}.tar.gz" dist/ aws s3 cp "dist-v${COMMIT_HASH}-${TIMESTAMP}.tar.gz" "s3://my-bucket/releases/" # 4. 更新 Nginx 配置（灰度） if [ "$STAGE" = "production" ]; then echo "⚙️ 更新 Nginx 灰度配置..." sed -i '' "s/backend_v[0-9]*/backend_v${COMMIT_HASH}/g" /etc/nginx/conf.d/app.conf nginx -t && nginx -s reload fi # 5. 重启服务 echo "🔄 重启服务..." pkill -f "bun run src/index.ts" bun run src/index.ts & echo "✅ 部署完成！版本: v${COMMIT_HASH}"配套的package.json脚本：
{ "scripts": { "dev": "bun run src/index.ts", "build": "bun build --outdir dist --target bun ./src/index.ts", "deploy": "bash scripts/deploy.sh", "deploy:prod": "bash scripts/deploy.sh production", "quality:check": "node scripts/quality-check.js" } }这样开发者只需npm run deploy，就能完成从代码检查到服务重启的全流程，且每一步都有明确输出，失败时能精确定位在哪一步中断。
5. 常见问题与排查技巧实录：那些文档里不会写的坑
5.1 多 Agent 场景下内存泄漏的隐蔽源头
现象：服务运行 24 小时后内存占用持续上涨，process.memoryUsage().heapUsed从 120MB 涨到 890MB，但heapTotal保持稳定，说明是 JS 堆内存泄漏。
排查过程：
- 用
bun run --inspect-brk src/index.ts启动，Chrome DevTools Memory Tab 拍摄 Heap Snapshot； - 对比 1 小时前后快照，发现
Map实例数量增长 3000+，且 key 是字符串sku-xxxx； - 定位到 InventoryGuardianWorker 中的
inventoryCache = new Map()—— 它在 Worker 内部，但 Worker 没有销毁机制，每次postMessage都新建 Worker 实例，旧实例的 Map 一直存活。
解决方案：Worker 必须显式终止，不能依赖 GC：
// src/agent/inventory/guardian.ts export async function checkStock( input: CheckStockInputType, timeoutMs: number = 5000 ): Promise<CheckStockOutputType> { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), timeoutMs); try { const result = await inventoryGuardian.postMessage(input, { signal: controller.signal }); // 关键：成功后立即 terminate Worker，释放内存 inventoryGuardian.terminate(); clearTimeout(timeoutId); return CheckStockOutput.parse(result); } catch (error) { clearTimeout(timeoutId); inventoryGuardian.terminate(); // 失败也要 terminate throw error; } }提示：Bun Worker 的
terminate()是同步的，不会等待 Worker 完成当前任务，因此 Worker 内部必须用self.onmessage处理abort信号，及时清理资源。
5.2 React 19 Server Actions 在 Bun 环境下的 Cookie 丢失问题
现象：用户登录后，Server Action 中cookies().get("session")返回 null，但浏览器 Network Tab 显示 Cookie 正常发送。
原因：Bun 的Request对象默认不解析 Cookie，需要手动启用：
// src/middleware/cookie-parser.ts import { Elysia } from "elysia"; export const cookieParser = new Elysia() .onBeforeHandle(({ request }) => { const cookieHeader = request.headers.get("cookie"); if (cookieHeader) { // 手动解析 Cookie 字符串 const cookies = Object.fromEntries( cookieHeader.split("; ").map(pair => { const [key, value] = pair.split("="); return [key, decodeURIComponent(value)]; }) ); // 注入到 request 上下文（需自定义类型） (request as any).cookies = cookies; } });然后在 Server Action 中使用：
"use server"; import { cookies } from "next/headers"; // 注意：这是 Next.js 的，Bun 环境需自定义 // 自定义 cookies 函数 export function getServerCookies() { const request = (globalThis as any).__bunRequest__; return request?.cookies ?? {}; } export async function protectedAction() { const cookies = getServerCookies(); const session = cookies.session; if (!session) throw new Error("Unauthorized"); // ... 业务逻辑 }5.3 Elysia 的 OpenAPI 文档中文乱码问题
现象：用elysia-swagger插件生成的文档，中文注释显示为 ``。
根本原因：Elysia 默认用utf8
