SuperAPI AI 工具集

ai-core/locks

通用与其它

查看项目

更新于 10-16 09:59

技能介绍

用途:Locks 用于多实例协调,回答“谁可以现在运行这个临界区”,与持久化存储回答的“哪些是持久聊天数据”相互独立。它基于 ai-core 与 ai-core/middleware,随 @tanstack/ai 发布,不从 @tanstack/ai-persistence 导入。withPersistence 不会自动锁定整个轮次,存在多写入竞争时需自行按线程或其它键加锁。

主要能力:withLocks 是一个提供 LocksCapability 的 ChatMiddleware,供下游中间件(如 sandbox)消费。核心契约是 LockStore 接口:withLock<T>(key, fn) 接收 key 与回调,返回 Promise;获取键、执行 fn、fn 结束后释放。InMemoryLockStore 随 @tanstack/ai/locks 提供,按 key 串行,仅在同一进程内正确;多实例需自行实现分布式锁,Cloudflare Durable Object 配方见 ai-persistence/build-cloudflare-adapter。可用 defineLock 定义自己的 store(带自动补全)后交给 withLocks。

使用方式:在 chat 的 middleware 中传入 withLocks(new InMemoryLockStore());可与 withPersistence 并用,定位顺序通常状态在前、锁并列或按能力消费方调整。Capability 以对象引用标识,共享同一 token 即可让链中的 withLocks 触达 withSandbox。

限制与常见错误:锁不属于 AIPersistence.stores,不能传给 composePersistence 覆盖,也不能传给一致性测试套件的 skip(该套件不覆盖锁,需单独测租约过期与中止)。良好实现应按 key 串行、使用租约防止崩溃持有者永久阻塞,并把 AbortSignal 传入临界区,回调须响应 signal 并传给可取消依赖;InMemoryLockStore 从不中止其 signal,跨进程无互斥。