SuperAPI AI 工具集

inngest-brownfield-audit

编程与开发

查看项目

更新于 10-16 06:19

技能介绍

用途:在既有代码库中审计并决定如何引入 Inngest,而不是从零搭建。适用于“审计本仓库的 Inngest 机会”“让 webhook/cron/后台任务更可靠”“找出部署或进程崩溃时可能丢失的工作”“替换脆弱的轮询、延迟任务或 fire-and-forget promise”“让 AI 工作流/智能体持久化”等请求。若从零开始,应改用 inngest-setup、inngest-durable-functions、inngest-events、inngest-steps 等。

主要能力(审计循环):一、映射项目结构,读取 package.json、工作区文件、路由/服务器入口、部署配置和测试脚本,识别 Next.js App Router/Pages Router、Express、Hono、Fastify、Remix、SvelteKit、Astro、NestJS、worker-only 等框架,并确认包管理器与 TypeScript 约定。二、查找既有 Inngest 使用,搜索 inngest、createFunction、serve(、/api/inngest、INNGEST_、step.run、step.sleep、step.waitForEvent、step.sendEvent、step.invoke、step.ai、inngest.send、@inngest/realtime,若有则先检查版本、客户端配置、serve 端点、已注册函数、事件命名、环境变量及 v3/v4 API 形态。三、查找持久性缺口:fire-and-forget(void 异步调用、未 await 的 promise、.then、setTimeout、setInterval、HTTP 响应后的游离任务、路由处理器中的后台工作);cron 与调度器(cron、node-cron、agenda、bull、bullmq、bee-queue、qstash、sqs、temporal、trigger.dev、部署 cron 配置、定时 API 路由);webhook 与至少一次投递的生产者(Stripe、Clerk、GitHub、Slack、Shopify、HubSpot、Linear、Svix 及通用 webhook);长时间任务(PDF 生成、导出、音视频处理、嵌入、批量邮件、导入、ETL、同步任务、轮询循环、重试、外部 API 调用);AI 智能体形态(工具循环、LLM 调用、流式 token、人工审批、多步推理、向量检索、评估循环、需要限流或重试安全状态的 provider 调用)。四、对每个候选分级:P0 为用户可见丢失、重复扣费/邮件/动作、超时、漏掉 webhook 或易崩溃流程;P1 为脆弱但可恢复的后台工作、人工重试负担、429 噪音或可观测性差;P2 为清理、易用性或未来迁移机会。记录文件、当前触发方式、副作用、幂等键、失败模式、推荐的 Inngest 原语、迁移规模和置信度。五、选择最小安全集成,优先单个垂直切片,尽量保留现有领域函数和数据模型,客户端与 serve 端点只添加一次,逐个边界把副作用移入 step.run,在加重试前先保证事件 ID 和数据库写入幂等,并围绕原有行为和新事件/函数边界补充测试。

决策参考:HTTP 处理器在响应前做慢副作用 → 发事件并快速返回,用 inngest.send、事件触发、step.run;webhook 需快速确认但可靠处理 → 验签后发幂等事件,用事件 ID、step.run、重试;cron 中途丢失进度 → cron 触发的持久函数,用 cron 触发、分页 step.run、流程控制;轮询等待外部异步 → 持久等待或持久轮询,用 step.waitForEvent、step.sleep、step.run;大扇出超出请求/无服务器限制 → 拆分编排与单项工作,用 step.sendEvent、每项函数、并发;外部 API 遇 429 → 把限制移到函数配置,用 throttle、rateLimit、concurrency;人工审核需数天 → 在 Inngest 中持久等待,用 step.waitForEvent、超时、realtime;AI 智能体/工具循环需重试安全进度 → 每个工具/模型边界一步,用 step.ai、step.run、step.sleep、realtime;现有队列仅掩盖脆弱工作 → 逐步替换队列边界。

集成计划格式:编辑前先以紧凑格式汇总发现——既有 Inngest 状态(none/partial/healthy/risky)、框架及证据、最佳首个切片(文件+工作流)、原因(丢失/超时/重试/幂等失败)、拟用原语、幂等键来源、可能触及的文件、测试/检查命令。除非用户明确只要审计,否则随后实施。

使用方式:可运行仓库适配的发现命令,优先 rg 并保持输出聚焦,例如 rg -n "inngest|createFunction|step\.|serve\(|/api/inngest|INNGEST_" ., rg -n "setTimeout|setInterval|Promise\.all|void [a-zA-Z0-9_]+\(|\.then\(" ., rg -n "cron|node-cron|schedule|bull|bullmq|bee-queue|agenda|qstash|sqs" ., rg -n "webhook|stripe|svix|clerk|github|shopify|slack|hubspot|linear" ., rg -n "retry|backoff|poll|status|timeout|429|rate limit|rate-limit" ., rg -n "openai|anthropic|ai\.|generateText|streamText|tool|agent|embedding" .。仓库较大时应缩小到应用源码目录并排除生成/第三方目录。若已有 Inngest,需检查:共享客户端是否从稳定模块导出;app id 是否为稳定 slug 且不依赖部署数据;v4 本地开发使用 INNGEST_DEV=1,生产使用 INNGEST_SIGNING_KEY;serve 端点路径通常为 /api/inngest 且可发现;serve 处理器注册所有应同步的函数;副作用与非确定性工作位于步骤内;步骤 ID 稳定且具描述性;事件名遵循 domain/noun.verb;可能重放的事件使用确定性 ID;webhook 处理器先验签再发事件;外部 API 有限制处配置流程控制;realtime 使用 v4 原生 inngest/realtime 而非 v3 的 @inngest/realtime。

持久智能体模式:适合多步工具调用、可能超出一个 HTTP 请求生命周期的 LLM 工作流、人在环路审批/纠正/升级、需暂停等待外部事件或定时跟进、需 provider 级限流与成本保护的批量 AI 工作、希望从持久执行流式输出进度。推荐形态:HTTP/UI 请求保存用户意图并发带稳定 id 的事件;Inngest 函数在 step.run 内加载状态;每次模型调用、工具调用、向量检索和外部副作用各自位于 step.ai 或 step.run 边界;人工暂停用 step.waitForEvent 或 step.waitForSignal 并设超时;进度更新用 step.realtime.publish 或现有 step.run 内的 inngest.realtime.publish;provider 限流用 concurrency、throttle、rateLimit 而非进程内临时限流。应避免:仅把智能体状态留在内存;单个工具失败后重试整个智能体循环;结果未记忆化导致重复成功模型调用被计费;用 setTimeout 或 cron 轮询处理跟进与审批;工作流本身持久却在进程本地 WebSocket 推流。

实现护栏与验证:不要盲目替换可用的队列、cron 或 webhook,先用薄 Inngest 切片保留行为;已有客户端或 serve 端点时不重复创建;新函数中不要把数据库写入、API 调用、随机 ID、时间戳或 LLM 调用放在步骤外;不要用重试掩盖缺失的幂等性;不要硬编码密钥或开发模式标志;不要让应用无法同步,注册新函数并运行类型检查/测试。验证可选:对受影响应用做类型检查/构建/lint,运行迁移处理器或工作流相关现有测试,增加“处理器发事件并快速返回”和“函数在步骤边界调用相同领域操作”的聚焦测试;若本地运行可用,启动应用与 Inngest 开发服务器,确认函数同步并发送示例事件;若只能静态检查,应明确说明未验证运行时同步。

限制:本资料未提供该技能的具体安装命令、依赖版本、收费或价格信息,这些内容暂未提供;实际可用性取决于仓库技术栈与 Inngest 集成条件。