SuperAPI AI 工具集

tanstack-ai-persistence-server

通用与其它

查看项目

更新于 10-16 00:02

技能介绍

用途:为 TanStack AI 聊天提供服务器端状态持久化。withPersistence(persistence) 是一个 ChatMiddleware,把聊天状态写入后端,包括消息、运行(runs)和中断(interrupts,可选元数据)。它不修改 chunk 流,也不替代投递持久性。

主要能力:四个存储——messages(完整模型消息记录,withPersistence 必需)、runs(运行状态、耗时、用量、错误,可选,中断持久化需要)、interrupts(待处理/已解决的工具审批与等待,可选,依赖 runs)、metadata(应用自有的命名空间键值,可选)。类型用 ChatTranscriptPersistence 或 ChatPersistence 标注工厂,不要用裸 AIPersistence。

使用方式:在 chat() 中传入 adapter、messages、threadId、runId,并加 middleware: [withPersistence(persistence)],再用 toServerSentEventsResponse 返回。始终从客户端传 threadId 和 runId,客户端解决待处理中断时转发 resume。开发测试可用 memoryPersistence()。客户端加载历史用 reconstructChat(persistence, request, { authorize }),返回 { messages, activeRun, interrupts };生产多用户必须提供 authorize,否则猜中 threadId 即可读取记录。非聊天活动(图像、音频、TTS、视频、转录)用 withGenerationPersistence。

权威历史契约:messages 非空时,finish 会用该数组覆盖已存线程,必须提交完整记录而非增量;messages 为空时,中间件加载已存线程继续。写入时机:onStart 尽力写待处理快照;中断边界、onFinish、onError 为强制写;onAbort 有条件写——显式取消或不可分离运行时写 aborted,可分离运行的普通断连不写,保持 running 以便后续接管。流式快照默认关闭,可用 snapshotStreaming: true 与 snapshotIntervalMs 开启。

限制:中断需要 runs,否则抛错;不要把消息增量当作 messages 提交,会清空线程;withPersistence 不负责重连断开的流,那是投递持久性;判断终态用 isTerminalRunStatus,不要手写状态列表。具体适配器实现与更多细节暂未提供。