@tasklens/server

TaskLens 服务端辅助。 把 @tasklens/core 的事件流接到浏览器所需的四条路由 —— 框架无关，一行挂载。

它解决的是一个很具体的劝退点："Agent 的审批需要后端配合"。有了这个包，配合成本从"改架构"降到"挂一个 handler"。

pnpm add @tasklens/server

快速开始

import { createTaskLensServer } from '@tasklens/server'
import { createRun } from '@tasklens/core'

const lens = createTaskLensServer({ basePath: '/api/tasklens', cors: true })

// Express / Connect / Nest
app.use(lens.middleware())

// 原生 Node http
http.createServer(lens.nodeHandler()).listen(3000)

// Serverless / 自研路由：自己拿结果
const result = await lens.handle({ method: req.method, url: req.url, body: await req.json() })

Agent 侧拿到传输层，事件自动推给所有订阅者：

const run = createRun({ goal: '…', transport: lens.transport(runId) })

四条路由

| 方法 | 路径 | 用途 | | --- | --- | --- | | GET | {base}/runs/:runId/stream | SSE，支持 Last-Event-ID 续传 + 心跳 | | GET | {base}/runs/:runId | 快照 { events, lastSeq, state }，SSR 首屏直接用 | | POST | {base}/runs/:runId/approvals/:approvalId | 幂等决策回传 | | POST | {base}/runs/:runId/steps/:stepId/retry | 步骤级重试 |

配置

createTaskLensServer({
  basePath: '/api/tasklens',   // 挂载前缀
  store: createFileStore({ dir: '.tasklens/runs' }),  // 默认内存（进程重启即丢）
  hub: existingHub,            // 多个服务共享同一份运行时状态时传入
  heartbeatMs: 15000,          // SSE 心跳
  maxEventsPerRun: 5000,       // 每个 run 在内存中保留的事件上限，0 = 不限
  cors: true,                  // true | 固定的 Origin 字符串；默认关闭
  authorize: async (req) => checkAuth(req),   // 返回 false → 401
  onRequest: ({ method, path, status }) => log(method, path, status),
})

返回的能力

| 成员 | 说明 | | --- | --- | | transport(runId) | 交给 createRun({ transport }) 的通道 | | middleware() | Express / Connect / Nest 中间件 | | nodeHandler() | 原生 http.createServer handler | | handle(req) | 框架无关的 JSON 处理（SSE 走 openStream） | | openStream(runId, res, lastEventId?) | 自定义框架时显式开流 | | snapshot(runId) | SSR 首屏快照读取 | | close() | 释放定时器与连接 |

另有 publishTo(server, runId, event)（手动灌事件，测试/回放用）、createMemoryStore / createFileStore（持久化）。

许可

MIT © 李学丹 · 仓库与完整文档