在已有 TypeScript/JavaScript…

当你需要检查现有仓库、找出容易丢失或超时的后台工作（webhook、cron、队列、长任务、AI agent），并安全地增量引入 Inngest 时使用。

适用场景

解决思路

1. 映射项目形态：阅读 package.json、workspace 文件、app/router 结构、服务端入口、部署配置和测试脚本；识别框架（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；若已存在，先检查版本、client 配置、serve 端点、已注册函数、事件命名、环境变量以及 v3/v4 API 形态，再做任何改动。
3. 查找耐久性缺口：搜索 fire-and-forget 工作（void someAsync()、未 await 的 promise、.then( 链、setTimeout、setInterval、HTTP 响应后脱离的任务、route handler 中的后台工作）；搜索 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 生成、导出、视频/图像处理、embeddings、批量邮件、导入、ETL、同步任务、轮询循环、重试、外部 API 调用）；搜索 AI agent 形态（工具循环、LLM 调用、流式 token、人工审批、多步推理、向量搜索、eval 循环、打分、实验分组、用户反馈信号、需要限流或可重试状态的服务商调用）。
4. 对每个候选分类：P0 为用户可见丢失、重复扣费/邮件/动作、超时、漏掉 webhook 或易崩溃工作流；P1 为脆弱但可恢复的后台工作、人工重试负担、大量 429 或可观测性差；P2 为清理、易用性或未来迁移机会；对每个候选记录：文件、当前触发方式、副作用、幂等键、失败模式、推荐的 Inngest 原语、迁移规模、置信度。
5. 选择最小安全集成：优先一个垂直切片而非大范围重写；尽量保留现有领域函数和数据模型；只添加一次 Inngest client 和 serve 端点；一次一个边界地把副作用移入 step.run；在加入重试前先让事件 ID 和数据库写入幂等；围绕现有行为以及新的事件/函数边界添加测试。
6. 运行适合仓库的发现命令，优先用 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" .；仓库较大时缩小到应用源码目录并排除生成/第三方目录。
7. 按 brownfield 决策矩阵匹配现有形态与 Inngest 原语：HTTP handler 响应前做慢副作用 → 发事件、快速返回，用 inngest.send、事件触发、step.run；webhook 需快速确认但可靠处理 → 验签后发幂等事件，用事件 ID、step.run、重试；cron 中途丢失进度 → cron 触发的耐久函数，用 cron 触发、分页 step.run、flow control；轮询等待外部异步工作 → 耐久等待或轮询，用 step.waitForEvent、step.sleep、step.run；大扇出超出请求/serverless 限制 → 拆分编排与单项工作，用 step.sendEvent、单项函数、concurrency；外部 API 遇到 429 → 把限流移到函数配置，用 throttle、rateLimit、concurrency；人工审核可能持续数天 → 在 Inngest 中持久化等待，用 step.waitForEvent、timeout、realtime；AI agent/工具循环需要可重试进度 → 每个工具/模型边界一个 step，用 step.ai、step.run、step.sleep、realtime；AI 工作流需要生产 eval → 把结果信号附加到耐久运行，用 meta.sessions、step.score、createScorer、defer、group.experiment；现有队列只是掩盖脆弱工作 → 逐步替换队列边界，用事件触发、幂等、函数级重试。
8. 编辑前按紧凑格式总结发现：Inngest audit: - Existing Inngest: none / partial / healthy / risky - Framework: <framework and evidence> - Best first slice: <file + workflow> - Why: <loss/timeout/retry/idempotency failure> - Proposed primitives: <event, steps, flow control, waits, realtime> - Idempotency key: <source of truth> - Files likely touched: <short list> - Tests/checks: <commands or focused cases>；除非用户只要审计，否则随后实施。
9. 若已存在 Inngest，逐项检查：从稳定模块导出单一共享 client；app id 是稳定 slug 且不来自部署相关数据；v4 本地开发使用 INNGEST_DEV=1，生产使用 INNGEST_SIGNING_KEY；serve 端点路径可发现，通常为 /api/inngest；serve handler 注册所有应同步的函数；副作用和非确定性工作都在 step 内；step ID 稳定且具描述性；事件名遵循 domain/noun.verb；可能被重放的事件使用确定性 ID；webhook handler 在发事件前验签；外部 API 有限流处配置 flow control；realtime 使用 v4 原生 inngest/realtime，而非 v3 的 @inngest/realtime 包。
10. 对需要跨模型调用、工具调用、等待、审批或流式 UI 更新保持耐久进度的 AI/agent 工作流使用 Inngest；适合的候选包括：调用工具或外部 API 的多步 agent；可能超过单次 HTTP 请求生命周期的 LLM 工作流；human-in-the-loop 审核、审批、纠正或升级；必须暂停等待外部事件或定时跟进；需要服务商级限流和成本保护的批量 AI 工作；应从耐久执行流式输出用户可见 agent 进度的场景。
11. 采用推荐的 agent 形态：HTTP/UI 请求保存用户意图并发出带稳定 id 的事件；Inngest 函数在 step.run 内加载状态；每次模型调用、工具调用、向量搜索和外部副作用都位于各自的 step.ai 或 step.run 边界；人工暂停使用带 timeout 的 step.waitForEvent 或 step.waitForSignal；进度更新在 step 之间用 step.realtime.publish，或在已有 step.run 内用 inngest.realtime.publish；服务商限流使用 concurrency、throttle 或 rateLimit，而不是临时的进程内限流器。
12. 实施护栏：不要盲目替换可用的队列、cron 或 webhook，先用薄 Inngest 切片保留行为；若仓库已有 client 或 serve 端点，不要创建重复的；不要把数据库写入、API 调用、随机 ID、时间戳或 LLM 调用放在新函数的 step 之外；不要用重试掩盖缺失的幂等性，重试要求副作用幂等；不要在源码中硬编码密钥或开发模式标志；不要让应用无法同步：在 serve 端点注册新函数并运行可用的类型检查/测试。
13. 选择能证明集成路径的验证：对改动应用做 typecheck/build/lint；运行被迁移 handler 或工作流相关的现有测试；在仓库支持时，为“handler 发事件并快速返回”和“函数在 step 边界调用相同领域操作”添加聚焦测试；若本地运行时可用，启动应用和 Inngest dev server，确认函数同步后发送示例事件；若只能做静态检查，明确说明未验证运行时同步。

适用边界 · 注意事项

• 用户是从零开始而非改造已有仓库时，改用 inngest-setup、inngest-durable-functions、inngest-events、inngest-steps 以及本技能中的 agent 模式。
• 请求涉及打分、sessions、实验、延迟 scorer、Insights 或基于结果的评估时，改用 inngest-agent-evals。
• 不要把 agent 状态只保存在内存中；不要因单个工具失败就重试整个 agent 循环；不要因结果未 memoize 而重复为成功的模型调用付费；不要用 setTimeout 或 cron 轮询处理跟进和审批；不要在工作流本身在别处耐久时从进程本地 WebSocket 服务器流式输出进度。