项目定位与总体目标

Trigger.dev 是一个开源平台，用于构建和部署完全托管的 AI Agent 与工作流。它允许开发者使用普通的异步 TypeScript 来编写从简单任务到长时间运行的 AI Agent、媒体处理、复杂实时系统等不同场景的工作流，并提供完整的可观测性、托管队列与弹性伸缩基础设施。

资料来源：README.md:1-12

整个仓库采用 monorepo 结构组织多个包，覆盖 CLI、SDK、核心运行时、构建扩展以及后台执行引擎等关键模块。当前稳定主线版本为 v4.4.x，v4.5.0 处于 RC 阶段（如 v4.5.0-rc.5）。每个发布版本同时发布自托管 Docker 镜像，便于用户在自有基础设施上运行。

Monorepo 包结构与职责

仓库通过 packages/ 与 internal-packages/ 两个目录划分公开发布包与内部包。下表总结了主要包及其职责：

资料来源：packages/cli-v3/package.json:1-20、packages/core/package.json:1-30、packages/trigger-sdk/README.md:1-18、packages/python/package.json:1-15、packages/plugins/package.json:1-12

SDK 与 CLI 的协作模型

CLI 包通过 "bin": { "trigger": "./dist/esm/index.js" } 暴露统一的 trigger 可执行入口，依赖 commander 实现子命令解析。SDK 包被设计为可在用户代码库中以 task({ id, run }) 形式声明任务，CLI 在 dev 与 deploy 阶段读取这些定义并打包上传到平台。

资料来源：packages/cli-v3/package.json:18-30、README.md:60-75

一个最简任务定义示例：

import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { message: string }) => {
    console.log(payload.message);
  },
});

资料来源：README.md:62-75

CLI 与 SDK 通过版本号同步发布（如 4.5.0-rc.5），并提供 npm、pnpm、yarn、bun 多种包管理器的升级命令。

运行时扩展：Python 与 Schema

@trigger.dev/python 包在构建阶段注入 Python 脚本与依赖。它通过 pythonExtension() 配置 requirementsFile、devPythonBinaryPath、scripts 等选项，在容器中创建 /opt/venv 虚拟环境，并提供 run、runInline、runScript 三类执行函数。

资料来源：packages/python/README.md:1-50、packages/python/package.json:1-15

@trigger.dev/schema-to-json 包统一了多种 schema 库到 JSON Schema 的转换，支持 zod、yup、valibot、arktype、runtypes、superstruct、typebox 等。

资料来源：packages/schema-to-json/package.json:30-45

Run Engine 内部架构

run-engine 是平台核心的内部调度引擎，目录位于 internal-packages/run-engine，其 README 描述了以下子系统：

graph TD
  RE[RunEngine] --> DQ[DequeueSystem]
  RE --> RA[RunAttemptSystem]
  RE --> ES[ExecutionSnapshotSystem]
  RE --> WP[WaitpointSystem]
  RE --> BS[BatchSystem]
  RE --> EN[EnqueueSystem]
  DQ --> RA
  RA --> WP
  RA --> BS
  WP --> EN
  ES --> RA
  ES --> WP
  ES --> BS

各子系统职责如下：

• DequeueSystem：从主队列出队任务，处理资源约束与部署校验。
• RunAttemptSystem：管理运行尝试的生命周期、失败处理、重试与取消。
• ExecutionSnapshotSystem：创建执行快照、跟踪状态、维护心跳。
• WaitpointSystem：管理任务同步的等待点（waitpoint），协调阻塞的运行与并发释放。
• BatchSystem：处理批处理运行与完成协调。
• EnqueueSystem：负责入队与调度，配合执行快照工作。

资料来源：internal-packages/run-engine/README.md:1-50

所有子系统共享 Prisma（数据库）、Logger、Tracer、RunQueue、RunLocker、EventBus、Worker、ReleaseConcurrencyQueue 等资源。RunEngine 作为顶层协调者，统一管理这些共享资源并编排子系统交互。

已知问题与社区关注点

社区近期关注的一个显著缺陷：当 @trigger.dev/* 依赖使用 pnpm/bun 的 workspace catalog: 协议时，CLI 在比较版本时会抛出 Invalid comparator: catalog: 错误，阻断本地启动与部署流程。该问题出现在 bun 1.3.14、Node 22.20.0 等常见环境组合下，需要在依赖解析前先展开 catalog 别名。

资料来源：GitHub Issue #3905

此外，v4.5.0 RC 系列（rc.0 至 rc.5）经历了密集迭代，发布通道同时托管 ghcr.io/triggerdotdev/trigger.dev:v4.5.0-rc.X 的自托管镜像，说明 4.5 系列尚处于功能与稳定性收敛阶段。

See Also

• CLI 命令参考
• 自托管部署指南
• TypeScript SDK 文档
• Python 扩展用法

CLI v3、MCP 与已知问题

概述与定位

trigger.dev CLI v3 是整个平台的本地开发与部署入口，安装后暴露二进制命令 trigger，由 packages/cli-v3 包发布（当前版本 4.5.0-rc.5）。它是开发者与 Trigger.dev 云端运行时之间的桥梁，覆盖本地任务运行、版本部署、用户认证以及最近新增的 MCP（Model Context Protocol）服务注册能力。

资料来源：packages/cli-v3/package.json:1-20

CLI v3 通过 tshy 构建并以纯 ESM 形式分发，同时把 skills 目录一并发布，便于 AI 助手或编辑器扩展消费命令语义。bin 字段将 trigger 指向 ./dist/esm/index.js，而 keywords 中包含 nextjs、tanstack-intent 等框架标记，说明其面向现代全栈项目。

资料来源：packages/cli-v3/package.json:21-40

核心命令一览

packages/cli-v3/README.md 文档化了 CLI v3 的一级命令矩阵，下表汇总其用途：

资料来源：packages/cli-v3/README.md:7-22

CLI v3 还承担更新与 MCP 安装职责：update 子命令用于按包管理器升级 CLI（npm/pnpm/yarn/bun 对应 npx trigger.dev@<version> update 等），install-mcp 负责把 Trigger.dev 注册为 AI 编辑器的 MCP Server。

资料来源：README.md:1-40 packages/cli-v3/README.md:7-22

MCP 集成架构

MCP 是 CLI v3 在 v4.5 发布周期引入的扩展点。packages/cli-v3/package.json 中新增的 mcpName: "io.github.triggerdotdev/trigger.dev" 字段遵循 MCP 官方命名规范，使编辑器（如 Cursor、Claude Desktop）能够通过标准协议发现并调用 CLI 暴露的能力。

flowchart LR
    Editor[AI 编辑器 / MCP Client] -->|JSON-RPC| CLI[trigger CLI v3]
    CLI -->|login/init/dev| Local[本地任务与配置]
    CLI -->|deploy/promote| Cloud[Trigger.dev 云平台]
    CLI -->|mcp tools| Skills[skills 目录语义]
    Cloud --> Runs[任务运行 / 调度 / 日志]

平台侧的 SDK 与构建扩展通过 packages/core 统一抽象。该包以 workspace:* 方式被 CLI、SDK、Python 扩展、Redis Worker 等模块共同依赖，确保 CLI 在执行 dev、deploy 时能复用一致的鉴权、追踪与日志语义。

资料来源：packages/core/package.json:1-30 packages/python/package.json:1-30

Python 扩展是另一个与 CLI 协同工作的关键包：通过 pythonExtension() 注册到 trigger.config.ts 的 build.extensions，CLI 在打包阶段即会调用 @trigger.dev/python 处理 requirements.txt 和 .venv 解释器。开发者随后可以在任务中调用 python.runScript("my_script.py", [...]) 触发脚本。

资料来源：packages/python/README.md:1-50 packages/python/package.json:10-30

已知问题与故障排查

社区在 v4.5.0-rc 系列反馈了若干问题，最显著的是 workspace catalog 解析失败：当 @trigger.dev/* 依赖使用 pnpm/bun 的 catalog: 协议时（例如 "@trigger.dev/sdk": "catalog:"），CLI 在依赖比对阶段抛出 Invalid comparator: catalog: 异常并退出，导致 dev、deploy、update 子命令全部失败。

资料来源：GitHub Issue #3905

常见的临时缓解措施包括：

1. 回退到精确版本：将 catalog: 替换为显式的 workspace:* 或 ^4.5.0-rc.5，避免 CLI 的 semver 解析器遭遇未知 comparator。
2. 升级到最新的 rc 版本：v4.5.0-rc.0 → rc.5 的发布说明显示项目持续修复合并冲突与解析路径上的回归，升级往往能直接绕过旧 bug。
3. 使用受支持的包管理器：CLI 在 package.json 中列出 pnpm dlx、yarn dlx、bunx 与 npx 四种调用方式，部分 comparator 行为与所选包管理器相关，按推荐方式调用可减少歧义。

资料来源：Release v4.5.0-rc.5 Release v4.5.0-rc.0

除 catalog 协议问题外，使用 CLI 启动本地开发时还需注意：

• Node 版本要求：packages/cli-v3、packages/core、packages/python 等多个包的 engines 字段统一要求 node >=18.20.0，低于该版本将直接触发 ESM 加载失败。
• Python 解释器路径：pythonExtension 的 devPythonBinaryPath 选项必须指向可执行文件，路径错误会让 dev 命令在打包阶段中断。
• CLI 档案切换：switch 与 list-profiles 共同维护本地凭据，使用多环境（dev/staging/prod）时务必先确认 whoami 输出与目标环境一致。

资料来源：packages/cli-v3/package.json:1-30 packages/python/README.md:1-40

版本节奏与升级建议

trigger.dev 在近期以双轨节奏发布：稳定线（v4.4.3 → v4.4.6）面向生产用户，候选线（v4.5.0-rc.0 → v4.5.0-rc.5）面向提前体验 MCP 与新版构建扩展的用户。每个版本都附带同步发布的自托管 Docker 镜像（ghcr.io/triggerdotdev/trigger.dev:<tag>），便于私有化部署保持版本一致。

资料来源：Release v4.4.6 Release v4.5.0-rc.5

建议在升级前查阅对应 release notes 的 Highlights 段落，确认新引入的 update 流程与既有 deploy 工作流是否兼容——尤其是当仓库同时使用 packages/cli-v3、packages/python、@trigger.dev/sdk 三个工作区包时，统一升版可避免 catalog 解析与依赖漂移引发的连锁错误。

资料来源：packages/cli-v3/package.json:1-30 packages/python/package.json:1-30

See Also

• Trigger.dev 主仓库 README
• CLI v3 命令文档
• Python 扩展说明
• Issue #3905: catalog comparator 解析失败
• v4.5.0-rc.5 发布说明

SDK：Tasks、Realtime、Waits 与 AI Chat

Trigger.dev 是一个用于构建和部署可完全托管的 AI 智能体与工作流的开源平台。其 TypeScript/JavaScript SDK 为开发者提供了一组高层 API（任务、实时订阅、等待点、批量调用、调度等），并由一组内部引擎（@internal/run-engine、@internal/schedule-engine、Coordinator、ClickHouse 存储等）支撑运行时行为。资料来源：README.md、packages/trigger-sdk/README.md。

1. SDK 的整体角色与组成

packages/trigger-sdk 是面向开发者的官方 TypeScript SDK 包，负责在用户代码中声明任务、订阅实时事件、调用 Management API 等。其在代码库中作为核心依赖被多个内部包引用，例如 internal-packages/sdk-compat-tests/package.json 通过 workspace:* 引入 @trigger.dev/sdk，用于跨 SDK 版本的兼容性测试。资料来源：packages/trigger-sdk/README.md、internal-packages/sdk-compat-tests/package.json。

packages/core 则承载 SDK 与平台共享的核心逻辑（schemas、tracer、build、zodSocket、runEngineWorker 等），通过 tshy 暴露大量子入口（如 @trigger.dev/core/v3/*），供 SDK 与服务端复用同一份类型与协议。资料来源：packages/core/package.json。

2. Tasks：声明、执行与可见性

2.1 在代码库中声明 Task

在用户代码中，task() 是声明工作单元的入口：每个任务需要导出、拥有唯一 id、并提供一个 async run(payload) 主函数。SDK 没有运行超时限制，因此该函数非常适合长时运行的 AI 智能体、媒体处理或周期性作业。资料来源：README.md。

import { task } from "@trigger.dev/sdk";

export const helloWorld = task({
  id: "hello-world",
  run: async (payload: { message: string }) => {
    console.log(payload.message);
  },
});

2.2 Task 运行时的执行引擎

Task 在部署后由 @internal/run-engine 驱动。该引擎以 RunEngine 为中枢，组合 DequeueSystem、RunAttemptSystem、ExecutionSnapshotSystem、WaitpointSystem、BatchSystem、EnqueueSystem 等子系统，并通过共享资源（Prisma、RunQueue、RunLocker、EventBus、Worker、ReleaseConcurrencyQueue、Tracer、Logger）协作完成入队、执行、重试、快照与完成。资料来源：internal-packages/run-engine/README.md。

任务运行数据最终落入 ClickHouse 的 trigger_dev.task_runs_v2 表中，结构化字段覆盖环境、版本、并发键、批量操作组、Span/Trace 关联以及冷启动标记等，可用于后续的 Trace 视图与回放。资料来源：internal-packages/clickhouse/src/taskRuns.test.ts。

flowchart LR
  A[用户代码 task] --> B[SDK 客户端]
  B --> C[Coordinator]
  C --> D[RunEngine]
  D --> E[DequeueSystem]
  D --> F[RunAttemptSystem]
  D --> G[WaitpointSystem]
  D --> H[BatchSystem]
  D --> I[ClickHouse task_runs_v2]
  F --> I
  G --> I
  H --> I

3. Realtime、Waits 与 AI Chat

3.1 Realtime 与 Trace 可见性

平台对每个 run 提供完整的 Trace 视图，并支持 tags（最多 10 个）、metadata（随运行进度更新，可供前端实时展示）、批量操作（重放与取消）以及实时告警（按通道通知运行失败与部署事件）。这些能力由 SDK、Coordinator 与 ClickHouse 共同支撑。资料来源：README.md、apps/coordinator/README.md、internal-packages/clickhouse/src/sessions.ts。

3.2 Waits 与 Schedule

跨任务/外部系统的同步由 WaitpointSystem 维护 waitpoint 的完成、阻塞运行以及并发释放。@internal/schedule-engine 则封装全部调度逻辑，提供 ScheduleEngine 类、registerNextTaskScheduleInstance 与 upsertTaskSchedule 等 API；其内置 Redis 分布式调度能力，默认 30 秒执行窗口，可避免雷暴群效应。资料来源：internal-packages/run-engine/README.md、internal-packages/schedule-engine/README.md。

3.3 AI Chat 与 Python 扩展

面向 AI 智能体场景，SDK 通过 Build Extensions 提供可插拔能力：@trigger.dev/python 的 pythonExtension 允许在构建阶段创建 /opt/venv 虚拟环境、解析 requirements.txt、并通过 run、runInline、runScript 等辅助方法在任务中执行 Python 代码，从而可在同一工作流里组合 Node 与 Python 生态。资料来源：packages/python/README.md。

4. 关键功能与运行时映射

资料来源：internal-packages/run-engine/README.md、internal-packages/schedule-engine/README.md、internal-packages/clickhouse/src/taskRuns.test.ts、packages/python/README.md。

5. 已知问题与社区关注点

近期 4.5.0-rc 系列（rc.0 → rc.5）频繁发布，主要由 CLI update 命令与自托管 Docker 镜像（ghcr.io/triggerdotdev/trigger.dev:v4.5.0-rc.*）推送。社区反馈的代表性 Bug 是：当 @trigger.dev/* 依赖在 package.json 中使用 bun/pnpm 的 catalog: 协议时，CLI 会以 Invalid comparator: catalog: 崩溃（#3905）。这是升级到 v4.5.0-rc.x 时需要留意的兼容性问题。资料来源：issue #3905、packages/cli-v3/README.md。

See Also

• Self-hosting Overview
• CLI Commands Reference
• Run Engine Architecture (内部)
• Schedule Engine (内部)
• Python Build Extension

1. 概述

Trigger.dev 是一个用于构建和部署 AI 代理与工作流的开源平台。整个项目按职责拆分为多个可独立演进的包（package）和内部包（internal-package），本文聚焦四个核心组成部分：

当前最新 CLI 发行版本为 4.5.0-rc.5，发布渠道支持 npx / pnpm dlx / yarn dlx / bunx [email protected] update 四种升级方式，对应自托管 Docker 镜像 ghcr.io/triggerdotdev/trigger.dev:v4.5.0-rc.5 README.md:1-30。

2. Run Engine（运行引擎）

Run Engine 是整个平台最核心的执行引擎，由 RunEngine 主类统一协调若干子系统（subsystem），并通过一组共享资源（shared resources）进行通信。架构示意如下：

graph TB
    RE[RunEngine] --> DQ[DequeueSystem]
    RE --> RA[RunAttemptSystem]
    RE --> ES[ExecutionSnapshotSystem]
    RE --> WP[WaitpointSystem]
    RE --> BS[BatchSystem]
    RE --> EN[EnqueueSystem]
    DQ -->|prisma / runQueue| RES[(Shared Resources)]
    RA --> RES
    ES --> RES
    WP --> RES
    BS --> RES
    EN --> RES
    RES --> P[Prisma]
    RES --> L[Logger/Tracer]
    RES --> RQ[RunQueue/RunLocker]
    RES --> EB[EventBus]
    RES --> W[Worker]
    RES --> RC[ReleaseConcurrencyQueue]

各子系统的职责如下 internal-packages/run-engine/README.md:14-49：

• DequeueSystem：负责主队列的出队、运行资源分配、部署校验。
• RunAttemptSystem：管理单次运行尝试（run attempt）的成功/失败、重试与取消。
• ExecutionSnapshotSystem：构建执行快照、维护活跃运行心跳并保留执行历史。
• WaitpointSystem：管理 waitpoint 同步、完成事件、阻塞运行与并发释放。
• BatchSystem：处理批量任务的批量完成与子任务协同。
• EnqueueSystem：处理入队、调度、并发令牌释放。

子系统之间通过共享资源交互。典型交互模式是：DequeueSystem 把任务交给 RunAttemptSystem 执行，RunAttemptSystem 在执行过程中与 WaitpointSystem、BatchSystem 协同，最终把状态变化写入 ExecutionSnapshotSystem internal-packages/run-engine/README.md:53-58。

3. Schedule Engine（调度引擎）

Schedule Engine 提供与 Run Engine 一致风格的集中式调度抽象，导出 ScheduleEngine 主类。典型用法如下 internal-packages/schedule-engine/README.md:23-44：

import { ScheduleEngine } from "@internal/schedule-engine";

const engine = new ScheduleEngine({
  prisma,
  redis: { /* Redis 配置 */ },
  worker: { /* Worker 配置 */ },
  distributionWindow: { seconds: 30 },
});

await engine.upsertTaskSchedule({
  projectId,
  schedule: {
    taskIdentifier: "my-task",
    cron: "0 */5 * * *",
    timezone: "UTC",
    environments: ["env-1", "env-2"],
  },
});

该包在 package.json 中显式声明依赖 @trigger.dev/redis-worker（即 packages/redis-worker），由该子包提供分布式执行时间窗（calculateDistributedExecutionTime），避免大量定时任务在同一瞬间集中触发形成“惊群”问题 internal-packages/schedule-engine/package.json:14-30。Schedule Engine 的运行结果最终仍然写入 Run Engine 的同一组持久化资源（如 Prisma、ClickHouse），并由 cron-parser + cronstrue 解析和可读化 Cron 表达式 internal-packages/schedule-engine/package.json:17-19。

4. Webapp 与运行时数据存储

apps/webapp 是为用户提供可视化运维能力的前端应用，依赖 tailwindcss 3.4.1、tailwind-scrollbar 等样式栈，并使用 tsconfig-paths 与 vite-tsconfig-paths 处理路径别名 apps/webapp/package.json:38-78。其运行所需的 Node 引擎约束为 >=18.19.0 || >=20.6.0 apps/webapp/package.json:80-82。

Webapp 上展示的运行历史、Session、心跳等数据来源于 ClickHouse。internal-packages/clickhouse/src/sessions.ts 中定义了会话表 trigger_dev.sessions_v1 的紧凑数组（Compact Arrays）写入路径与基于 Zod 的查询返回结构，字段覆盖 session_id、environment_type、tags、metadata.data 等关键运维维度 internal-packages/clickhouse/src/sessions.ts:1-90。运行（Run）级别数据则通过 taskRuns.test.ts 中的列定义，可观测到 status、task_identifier、queue、span_id/trace_id、标签数组以及 _version、_is_deleted 等版本控制字段，为 Webapp 的筛选、追溯与软删除提供依据 internal-packages/clickhouse/src/taskRuns.test.ts:1-60。

5. Self-Hosting（自托管）

Trigger.dev 提供两条主线自托管路径 README.md:38-46：

1. Docker Compose：参考 self-hosting/docker 文档，可在本地快速拉起整套平台。
2. Kubernetes：使用官方 Helm Chart 部署到生产级集群。

自托管镜像的标签随 CLI 版本同步发布，例如 ghcr.io/triggerdotdev/trigger.dev:v4.5.0-rc.5 即可直接通过 Helm values 或 docker-compose.yml 引用 README.md:14-30。官方在 Discord 中专门设立了 #self-hosting 频道以提供社区支持 README.md:48-50。

CLI 侧的常用命令覆盖了认证、项目初始化、本地开发运行、部署、版本晋升、Profile 切换与归档等场景 packages/cli-v3/README.md:7-18：

需要注意的是，CLI 在解析 package.json 依赖时使用 semver 比较器，当依赖声明采用 pnpm/bun 的 workspace: catalog: 协议时，会抛出 Invalid comparator: catalog: 错误（见社区 Issue #3905）。该问题在 4.5.0-rc.5 阶段已记录，自托管或 monorepo 用户升级前应关注其修复进度。

6. 相关运行时扩展

• Python 扩展：@trigger.dev/python 通过 pythonExtension 在构建期注入 Python 与 pip，支持 requirements.txt 与 trigger.config.ts 中内联的 requirements 选项，在容器内创建 /opt/venv 虚拟环境，并提供 run / runInline / runScript 三种调用方式 packages/python/README.md:1-25。
• Redis Worker：@trigger.dev/redis-worker 提供带 Schema 校验的分布式队列、可配置并发与拉取速率，以及对未来时刻（future date）调度的支持 packages/redis-worker/README.md:1-8。
• Trigger SDK：@trigger.dev/sdk 是官方 TypeScript SDK，提供 task() 任务定义、部署与运行时 API；其 TypeScript 类型与子路径导出在 packages/core 的 package.json 中统一维护 packages/trigger-sdk/README.md:1-20。

See Also

• Run Engine Source
• Schedule Engine Source
• Webapp Application
• Self-hosting Guides
• CLI v3 Reference

Pitfall Log / 踩坑日志

项目：triggerdotdev/trigger.dev

摘要：发现 19 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 trigger.dev 与安装入口 @trigger.dev/sdk 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npm install @trigger.dev/sdk
• 证据：identity.distribution | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev | repo=trigger.dev; [email protected]/sdk

2. 安装坑 · 失败模式：installation: bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace c...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog: protocol)
• 对用户的影响：Developers may fail before the first successful local run: bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog: protocol)
• 证据：failure_mode_cluster:github_issue | https://github.com/triggerdotdev/trigger.dev/issues/3905 | bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog: protocol)

3. 安装坑 · 失败模式：installation: trigger.dev v4.4.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.4.3
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.4.3
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.3 | trigger.dev v4.4.3

4. 安装坑 · 失败模式：installation: trigger.dev v4.4.4

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.4.4
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.4.4
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.4 | trigger.dev v4.4.4

5. 安装坑 · 失败模式：installation: trigger.dev v4.4.5

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.4.5
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.4.5
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.5 | trigger.dev v4.4.5

6. 安装坑 · 失败模式：installation: trigger.dev v4.4.6

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.4.6
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.4.6
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.6 | trigger.dev v4.4.6

7. 安装坑 · 失败模式：installation: trigger.dev v4.5.0-rc.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.0
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.0
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.0 | trigger.dev v4.5.0-rc.0

8. 安装坑 · 失败模式：installation: trigger.dev v4.5.0-rc.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.1
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.1
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.1 | trigger.dev v4.5.0-rc.1

9. 安装坑 · 失败模式：installation: trigger.dev v4.5.0-rc.2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.2
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.2
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.2 | trigger.dev v4.5.0-rc.2

10. 安装坑 · 失败模式：installation: trigger.dev v4.5.0-rc.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.3
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.3
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.3 | trigger.dev v4.5.0-rc.3

11. 安装坑 · 失败模式：installation: trigger.dev v4.5.0-rc.4

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.4
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.4
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.4 | trigger.dev v4.5.0-rc.4

12. 安装坑 · 失败模式：installation: trigger.dev v4.5.0-rc.5

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.5
• 对用户的影响：Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.5
• 证据：failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.5 | trigger.dev v4.5.0-rc.5

13. 安装坑 · 来源证据：bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog:…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog: protocol)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/triggerdotdev/trigger.dev/issues/3905 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

14. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev | README/documentation is current enough for a first validation pass.

15. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev | no_demo; severity=medium

17. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev | no_demo; severity=medium

18. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev | issue_or_pr_quality=unknown

19. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev | release_recency=unknown