@tasklens/core

TaskLens 核心运行时。 一个 createRun() 埋点入口 + 两种传输层，把 Agent 的执行过程变成一份可渲染的事件流。

零运行时依赖，Node 与浏览器双端可用（只依赖 @tasklens/protocol）。

pnpm add @tasklens/core

Agent 跑在浏览器里（零后端）

import { createRun } from '@tasklens/core'

const run = createRun({ goal: '给 20 位未激活用户发激活邮件' })

const [findUsers, genDrafts, send] = run.plan([
  '查询未激活用户',
  '生成邮件草稿',
  '发送',
])                                            // → ['step_1', 'step_2', 'step_3']

// 用 plan() 返回的 id 推进步骤
run.stepStart(findUsers)
const rows = await run.tool('db.query', () => queryUsers({ active: false }), {
  args: { table: 'users' },
  risk: 'low',
})                                            // → call + result 两条事件，含耗时
run.stepDone(findUsers)

// 高风险动作：挂起，等界面上的用户点"批准"
const outcome = await run.requestApproval({
  stepId: send,
  summary: '即将向 20 位真实用户发送邮件',
  risk: 'high',
  preview: { kind: 'list', title: '收件人', items: [{ label: '[email protected]' }] },
})

if (outcome.approved) {
  await sendEmails(rows)
}

run.done('已发送 20 封')

requestApproval() 返回的 Promise 由 UI 层的决策解开 —— 业务代码里不出现任何状态机。 outcome.decision 可能是 approve / edit / reject / timeout / closed，用 outcome.approved 判断"是否放行"（approve 与 edit 都算放行）。

步骤句柄

run.step(title) 创建一个计划之外的步骤并返回句柄（增量式 Agent 很常见）——它会把 stepId 绑好，省掉重复参数：

const step = run.step('生成邮件草稿')
step.start()
step.progress({ message: '3 / 20', ratio: 0.15 })
step.progress('正在重试…')                            // 简写
step.error(new Error('429 上游限流'), { retryable: true })
await step.approve({ summary: '…', risk: 'high' })    // stepId 已绑定
step.done()

Agent 跑在 Node 里，浏览器通过 SSE 观看

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

const lens = createTaskLensServer({ basePath: '/api/tasklens' })
app.use(lens.middleware())

const run = createRun({ goal: '…', transport: lens.transport(runId) })
// 事件自动广播给所有订阅者；断线重连、Last-Event-ID 续传由 @tasklens/vue 侧负责

传输层

| 传输 | 场景 | | --- | --- | | createMemoryTransport() | 浏览器内运行 / 单机脚本 / 测试（默认） | | createHub() / hubTransport | 服务端多订阅者广播，可传自定义 HubStore 持久化 | | 自定义 | 实现 Transport 接口，把事件接到你自己的通道 |

完整 API

createRun(options) → Run

| 方法 | 说明 | | --- | --- | | plan(steps) | 声明步骤，返回 stepId 数组（可传字符串或 PlanStep）；面板据此渲染"还剩几步" | | step(title, agent?) | 创建一个计划之外的步骤句柄（start/progress/done/error/tool/toolCall/toolResult/approve） | | stepStart / stepProgress / stepDone / stepError | stepId 版本的低层 API | | tool(name, fn, opts?) | 包一次工具调用：自动产出 call + result（含耗时、异常、可选 tokens/cost） | | toolCall(input) / toolResult(input) | 需要自己控制时机的低层 API（toolCall 返回 callId） | | requestApproval(input) | 挂起等待人工决策 → ApprovalOutcome | | decide(input) | 投递决策（幂等）；组件与 HTTP 端点最终都走到这里 | | isDecided(approvalId) | 某次审批是否已决策 | | retry(stepId, fromEventId?) / onRetry(handler) | 步骤级重试锚点 | | pause(reason) | 'approval' / 'user' / 'quota' | | emit(payload) | 产出任意事件（自定义类型 / 业务字段透传，前向兼容） | | done(summary?, opts?) / error(err, code?) | 收尾 | | subscribe(listener) | 订阅事件，返回取消函数 |

相关包

• @tasklens/protocol —— 事件协议与状态派生
• @tasklens/server —— SSE + 快照 + 审批端点
• @tasklens/vue —— Vue 3 组件层

许可

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