SuperAPI AI 工具集

add-a-store

编程与开发

查看项目

更新于 10-15 23:33

技能介绍

用途:add-a-store 是 rat-stack 中用于添加持久化存储的技能。它要求先命名存储的事实及其归属(系统记录与写入者),再为任务定义服务端口,选择厂商实现、迁移与资源 Layer,并在各存储实现上验证行为。

主要能力与步骤:1) 命名事实与归属,区分源数据与派生副本,复用 RunLog 等既有存储前先确认事实类型确实不同,避免双写;2) 为应用任务定义小而有名的端口操作,把 schema 与预期失败放在端口旁,区分 InvalidDatabaseInput 与 DatabaseError,显式定义重试与操作身份;3) 在存储语句前解码输入,用 schema 解码返回行与领域条目;4) 按厂商实现并约束读取,明确键、索引、排序、行预算与分页规则,检查查询计划,未测量值标注为猜测;5) 同步维护 schema、迁移与资源,连接串脱敏,不通过端口或失败信息暴露凭据;6) 在每套存储实现上证明行为,D1 用本地 SQLite、Hyperdrive Postgres 用 PGlite,覆盖结果变体、人员隔离、排序、限制、非法输入与类型化存储失败,必要时验证重放与原子性;7) 在组合根提供 Layer,经由 add-a-capability 暴露新动作,有状态工作流再遵循 add-a-lifecycle-machine。

使用方式:先读 AGENTS.md 并遵守其源码优先规则,从 packages/database 起步。相关文件包括 packages/database/src/model.ts、run-log.ts、store.ts、vendor.ts、run-log-vendor.ts、schema/d1.ts、schema/postgres.ts、migrations.ts、d1.ts、hyperdrive-postgres.ts、postgres-migrations.ts,测试参考 packages/database/test/run-log.test.ts、local-layers.ts、migration-paths.test.ts。完成后运行 pnpm turbo run check test build 并修复失败。

限制:现有端口没有原子多写操作,两次端口调用不代表共享事务;RunLog.record 每次生成新 UUIDv7,并非重放幂等;已部署站点目前不提供也不调用 RunLog;部署厂商行为与厂商切换尚未经验证;运行时与环境不同时需补充真实基础设施验证。资料未提供价格、收费或平台支持信息。