SuperAPI AI 工具集

state

数据与分析

查看项目

更新于 10-15 22:17

技能介绍

用途:state 是服务端键值存储,值由 scope(命名空间)和 key 寻址,在所有连接引擎的 worker 间共享,并通过可插拔适配器(kv 或 redis)持久化。调用方通过 iii.trigger({ function_id: 'state::...', payload }) 使用六个 state::* 函数,另有 state::list_keys 和内部 state::ui-content。安装命令为 iii trigger compose::add worker=state;它会替代引擎旧的内置 state 服务,需先从引擎配置中移除旧服务。

主要能力:state::set 写入或替换值,触发 state:created 或 state:updated;state::get 读取单个值;state::delete 删除键并以旧值触发 state:deleted;state::update 对存储值应用有序原子操作(set、merge、increment、decrement、append、remove);state::list 枚举 scope 内所有值;state::list_groups 枚举当前含数据的 scope。适配器方面,kv(默认)支持 file_based(默认)或易失的 in_memory 模式,redis 代理到 Redis 后端,函数接口在各适配器间一致。

使用方式:state 不向 SDK 客户端推送更新,反应性由 state 触发器提供,在每次成功变更后触发 state:created、state:updated 或 state:deleted。绑定触发器需先 iii.registerFunction('orders::on-status-change', handler),再 iii.registerTrigger({ type: 'state', function_id: 'orders::on-status-change', config: { scope: 'orders', key: 'status' } })。config 字段均可选,scope 省略匹配所有 scope,key 省略匹配 scope 内所有键;支持 condition_function_id,仅显式 false 阻止执行。处理器收到 { type: "state", event_type, scope, key, old_value, new_value }。

适用场景:两个以上函数需要共享状态而不想单独建数据库;计数器或按实体文档需要原子部分更新而非读改写;一个函数的写入应触发其他副作用(缓存失效、审计日志、通知、投影);只想监视特定 scope/key 变化。

限制:设计上无 schema,值均为不透明 JSON,需要注册 JSON Schema 与校验时应使用 configuration worker;读取(state::get、state::list、state::list_groups)不触发触发器,仅 set/update/delete 触发;触发器投递异步,处理器失败不回滚写入,删除不存在的键仍以 null 旧值发出 state:deleted;流式、广播给订阅者的数据应使用引擎的 stream 接口;存储位于 worker 进程内,kv 的 in_memory 后端在 worker 停止后丢失,默认 file_based 后端与 redis 可跨重启存活。