SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场inngest-brownfield-audit

inngest-brownfield-audit

编程与开发

查看项目

更新于 10-15 12:20

技能介绍

用途

Inngest Brownfield Audit 用于分析已有的 TypeScript 或 JavaScript 代码库，决定在何处以及如何引入 Inngest。它适合以下请求：审计仓库中的 Inngest 机会、向代码库添加 Inngest、让 Webhook / Cron / 后台任务更可靠、找出部署或进程崩溃时可能丢失的工作、替换脆弱的轮询 / 延迟任务 / fire-and-forget Promise、让 AI 工作流或智能体具备持久性。

这是一个以智能体为先的工作流：基于仓库中的证据进行审计，指出驱动每个结论的具体文件和调用点，并做小的集成改动以保持现有行为。如果用户是从零开始而非已有仓库，应使用 inngest-setup、inngest-durable-functions、inngest-events、inngest-steps 等技能；当请求涉及评分、会话、实验、延迟评分器、Insights 或基于结果的评估时，使用 inngest-agent-evals。

主要能力

审计循环包含以下步骤：

  1. 映射项目形态：读取 package.json、工作区文件、应用/路由结构、服务器入口、部署配置和测试脚本；识别框架（Next.js App Router、Next.js Pages Router、Express、Hono、Fastify、Remix、SvelteKit、Astro、NestJS、仅 worker 服务或其他）；在添加文件前检测包管理器和 TypeScript 约定。

  2. 查找现有 Inngest 使用：搜索 inngest、createFunction、serve(、/api/inngest、INNGEST_、step.run、step.sleep、step.waitForEvent、step.sendEvent、step.invoke、step.ai、inngest.send、@inngest/realtime。如果已存在 Inngest，在改动前检查版本、客户端配置、serve 端点、已注册函数、事件命名、环境变量以及 v3/v4 API 形态。

  3. 查找持久性缺口：搜索 fire-and-forget 工作（void someAsync()、未 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、人工审批、多步推理、向量搜索、评估循环、评分、实验分配、用户反馈信号、需要限流或重试安全状态的服务商调用）。

  4. 对每个候选分类：P0 为用户可见丢失、重复扣费/邮件/操作、超时、遗漏 Webhook 或易崩溃工作流；P1 为脆弱但可恢复的后台工作、手动重试负担、大量 429 或可观测性差；P2 为清理、易用性或未来迁移机会。每个候选记录：文件、当前触发器、副作用、幂等键、失败模式、推荐的 Inngest 原语、迁移规模、置信度。

  5. 选择最小的安全集成：优先一个垂直切片而非大范围重写；尽可能保留现有领域函数和数据模型；只添加一次 Inngest 客户端和 serve 端点；一次一个边界地将副作用移入 step.run；在添加重试前使事件 ID 和数据库写入幂等；围绕现有行为和新的事件/函数边界添加测试。

使用方式

技能提供有用的发现命令，建议使用 rg 并保持输出聚焦，例如搜索 inngest 相关符号、setTimeout/setInterval/Promise.all/void/.then(、cron/调度器、webhook 服务商、retry/backoff/poll/status/timeout/429/rate limit、openai/anthropic/ai./generateText/streamText/tool/agent/embedding。仓库较大时，将搜索范围缩小到应用源码目录并排除生成/供应商文件夹。

技能还提供 Brownfield 决策矩阵，将现有形态映射到 Inngest 适配方案和主要原语，例如：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）；AI 工作流需要生产评估 → 将结果信号附加到持久运行（meta.sessions、step.score、createScorer、defer、group.experiment）；现有队列只是隐藏脆弱工作 → 逐步替换队列边界（事件触发、幂等、函数级重试）。

集成计划格式要求在编辑前以紧凑形式总结发现：现有 Inngest 状态（无/部分/健康/有风险）、框架及证据、最佳首个切片（文件 + 工作流）、原因（丢失/超时/重试/幂等失败）、拟用原语（事件、步骤、流控、等待、realtime）、幂等键（事实来源）、可能触及的文件、测试/检查。然后实施，除非用户只要求审计。

如果已存在 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 包。

适用场景

技能包含持久智能体模式，适用于 AI 或智能体工作流需要跨模型调用、工具调用、等待、审批或流式 UI 更新保持持久进度的情况。良好候选包括：调用工具或外部 API 的多步智能体；可能超过单个 HTTP 请求生命周期的 LLM 工作流；人在回路中的审核、批准、纠正或升级；必须暂停等待外部事件或计划后续跟进的智能体；需要服务商级限流和成本保护的批量 AI 工作；应从持久执行流式传输的用户可见智能体进度。

推荐形态：HTTP/UI 请求存储用户意图并发出带稳定 id 的事件；Inngest 函数在 step.run 内加载状态；每个模型调用、工具调用、向量搜索和外部副作用位于各自的 step.ai 或 step.run 边界；人工暂停使用 step.waitForEvent 或 step.waitForSignal 并带超时；进度更新使用步骤间的 step.realtime.publish，或在现有 step.run 内使用 inngest.realtime.publish；服务商限流使用 concurrency、throttle 或 rateLimit，而非临时进程内限流器。

应避免：仅将智能体状态保存在内存中；单个工具失败后重试整个智能体循环；因结果未记忆化而重复为成功的模型调用付费；使用 setTimeout 或 cron 轮询器处理后续跟进和审批；当工作流本身在别处持久时，从进程本地 WebSocket 服务器流式传输进度。

限制

实施护栏包括：不要盲目替换可用的队列、cron 或 Webhook，先用薄 Inngest 切片保留行为；如果仓库已有客户端或 serve 端点，不要创建重复；不要在新函数中将数据库写入、API 调用、随机 ID、时间戳或 LLM 调用放在步骤外；不要用重试掩盖缺失的幂等性，重试需要幂等的副作用；不要在源码中硬编码密钥或开发模式标志；不要让应用无法同步，用 serve 端点注册新函数并运行可用的类型/测试。

验证部分建议选择能证明集成路径的检查：对触及的应用进行类型检查/构建/lint；运行迁移处理器或工作流周围的现有测试；在仓库支持时，为“处理器发出事件并快速返回”和“函数在步骤边界调用相同领域操作”添加聚焦测试；如果本地运行时可用，启动应用和 Inngest 开发服务器，确认函数同步，然后发送示例事件；如果只有静态检查可用，明确说明未验证运行时同步。