inngest-brownfield-audit

Inngest 棕地代码审计

当用户要求检查现有代码库、在合适的地方添加 Inngest、迁移脆弱的后台任务，或在做出更改前找出可靠性缺口时，使用此技能。

这是一个 Agent 优先的工作流。根据代码库中的证据进行审计，指出支撑每项结论的具体文件和调用位置，并通过小幅集成变更保留当前行为。

触发时机

遇到以下请求时使用此技能：

• “审计此代码库，找出 Inngest 的应用机会”
• “在此代码库中添加 Inngest”
• “让我们的 Webhook / Cron 任务 / 后台任务更可靠”
• “找出部署或进程崩溃时可能丢失工作的地方”
• “替换脆弱的轮询、延迟任务或启动后不等待的 Promise”
• “让这个 AI 工作流 / Agent 更可靠”

如果用户是从头开始，而不是在现有代码库上工作，请使用 inngest-setup、inngest-durable-functions、inngest-events、inngest-steps，对于 AI 工作流，还要使用此技能中的 Agent 模式。如果请求涉及评分、会话、实验、延迟评分器、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. 查找可靠性缺口。

   • 搜索启动后不等待的任务：void someAsync()、未等待的 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 Agent 模式：工具调用循环、大模型调用、流式 Token、人工审批、多步推理、向量搜索、评估循环、评分、实验分组、用户反馈信号，以及需要速率限制或支持安全重试状态的提供方调用。

4. 为每个候选项分类。

   • **P0：**用户可见的数据丢失、重复扣费 / 发邮件 / 执行操作、超时、Webhook 漏处理或易崩溃的工作流。
   • **P1：**脆弱但可恢复的后台工作、繁重的手动重试、频繁的 429 错误或可观测性差。
   • **P2：**清理工作、易用性改进或未来的迁移机会。
   • 对每个候选项记录：文件、当前触发方式、副作用、幂等键、故障模式、建议使用的 Inngest 基元、迁移规模和置信度。

5. 选择最小且安全的集成方案。

   • 优先选择一条端到端的垂直切片，而不是大范围重写。
   • 尽可能保留现有领域函数和数据模型。
   • 只添加一次 Inngest 客户端和 serve 端点。
   • 一次将一个副作用边界迁移到 step.run 中。
   • 添加重试前，确保事件 ID 和数据库写入具备幂等性。
   • 为现有行为以及新的事件 / 函数边界添加测试。

实用的发现命令

运行适用于此仓库的命令。优先使用 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" .

仓库较大时，将搜索范围缩小到应用源代码目录，并排除生成文件和供应商目录。

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、超时、实时功能
AI Agent／工具循环需要可安全重试的进度	每个工具／模型边界设为一个步骤	step.ai、step.run、step.sleep、实时功能
AI 工作流需要生产环境评估	将结果信号附加到持久化运行记录	meta.sessions、step.score、createScorer、defer、group.experiment
现有队列只是掩盖脆弱的工作	逐步替换队列边界	事件触发器、幂等性、函数级重试

集成计划格式

编辑之前，请按以下简洁格式总结发现：

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>

然后实施，除非用户只要求审计。

现有 Inngest 检查清单

如果已使用 Inngest，请核实：

• 从稳定模块导出一个共享客户端。
• 应用的 id 是稳定的 slug，且不根据部署特定数据生成。
• v4 本地开发使用 INNGEST_DEV=1；生产环境使用 INNGEST_SIGNING_KEY。
• Serve 端点路径易于查找，通常为 /api/inngest。
• Serve 处理程序注册所有应同步的函数。
• 副作用和非确定性工作都在步骤内执行。
• 步骤 ID 稳定且描述清晰。
• 事件名称遵循 domain/noun.verb 格式。
• 可能重放的事件使用确定性 ID。
• Webhook 处理程序在发送事件前验证签名。
• 外部 API 有限制时，配置流控制。
• 实时功能使用 v4 原生的 inngest/realtime，而不是 v3 的 @inngest/realtime 包。

持久化 Agent 模式

当 AI 或 Agent 工作流需要在模型调用、工具调用、等待、审批或流式 UI 更新期间持久保存进度时，请使用 Inngest。

适用场景：

• 会调用工具或外部 API 的多步骤 Agent。
• 可能超出单次 HTTP 请求生命周期的大模型工作流。
• 人工参与的审核、审批、纠正或升级处理。
• 必须暂停以等待外部事件或计划后续操作的 Agent。
• 需要服务商级速率限制和成本保护的大批量 AI 任务。
• 应通过持久化执行流式传输、供用户查看的 Agent 进度。

建议的设计：

1. HTTP/UI 请求保存用户意图，并发出带有稳定 id 的事件。
2. Inngest 函数在 step.run 中加载状态。
3. 每次模型调用、工具调用、向量搜索和外部副作用都放在各自的 step.ai 或 step.run 边界内。
4. 人工暂停使用 step.waitForEvent 或 step.waitForSignal，并设置超时时间。
5. 步骤之间使用 step.realtime.publish 更新进度；也可在现有 step.run 内使用 inngest.realtime.publish。
6. 服务商速率限制使用 concurrency、throttle 或 rateLimit，而非临时的进程内限流器。

避免：

• 只将 Agent 状态保存在内存中。
• 单次工具失败后重试整个 Agent 循环。
• 因未对结果进行记忆化处理而重复调用成功的模型并产生费用。
• 使用 setTimeout 或 cron 轮询器处理后续操作和审批。
• 工作流本身已在其他位置持久化时，仍通过进程本地的 WebSocket 服务流式传输进度。

实现注意事项

• 不要盲目替换正常运行的队列、cron 或 Webhook。首先通过轻量的 Inngest 切片保留现有行为。
• 如果仓库中已有客户端或服务端点，不要重复创建。
• 不要在新函数的步骤之外执行数据库写入、API 调用、随机 ID 生成、时间戳生成或大模型调用。
• 不要通过重试来掩盖缺少幂等性的问题。副作用必须具备幂等性，才能重试。
• 不要在源代码中硬编码密钥或开发模式标志。
• 不要让应用无法同步：将新函数注册到服务端点，并运行可用的类型检查和测试。

验证

选择能够证明集成路径有效的检查：

• 对修改过的应用运行类型检查、构建或 lint。
• 运行迁移后的处理程序或工作流相关的现有测试。
• 如果仓库支持，添加有针对性的测试，验证“处理程序会发出事件并快速返回”以及“函数会在步骤边界内调用相同的领域操作”。
• 如果可以使用本地运行时，启动应用和 Inngest 开发服务器，确认函数已同步，然后发送示例事件。
• 如果只能进行静态检查，请明确说明尚未验证运行时同步。