# https://github.com/triggerdotdev/trigger.dev 项目说明书

生成时间：2026-06-12 03:50:20 UTC

## 目录

- [System Architecture & Repository Overview](#page-1)
- [CLI v3, MCP & Known Issues](#page-2)
- [SDK: Tasks, Realtime, Waits & AI Chat](#page-3)
- [Run Engine, Scheduling, Webapp & Self-Hosting](#page-4)

<a id='page-1'></a>

## System Architecture & Repository Overview

### 相关页面

相关主题：[CLI v3, MCP & Known Issues](#page-2), [Run Engine, Scheduling, Webapp & Self-Hosting](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)
- [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)
- [packages/cli-v3/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json)
- [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json)
- [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md)
- [packages/schema-to-json/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/schema-to-json/package.json)
- [packages/python/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/package.json)
- [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)
- [packages/plugins/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/plugins/package.json)
- [packages/rsc/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/rsc/package.json)
- [internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)
</details>

# System Architecture & Repository Overview

## 项目定位与总体目标

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/` 两个目录划分公开发布包与内部包。下表总结了主要包及其职责：

| 包名 | 路径 | 职责 |
| :--- | :--- | :--- |
| `trigger.dev` (cli-v3) | `packages/cli-v3` | 命令行工具，提供 `login`、`init`、`dev`、`deploy` 等命令 |
| `@trigger.dev/core` | `packages/core` | SDK 与平台共用的核心代码（含 schemas、tracer、otel 等） |
| `@trigger.dev/sdk` | `packages/trigger-sdk` | 官方 TypeScript SDK，用于定义与触发任务 |
| `@trigger.dev/schema-to-json` | `packages/schema-to-json` | 将 Zod、Yup、Valibot 等 schema 库转换为 JSON Schema |
| `@trigger.dev/python` | `packages/python` | Python 运行时与构建扩展，允许在任务中执行 Python 脚本 |
| `@trigger.dev/plugins` | `packages/plugins` | 插件契约与接口定义 |
| `@trigger.dev/rsc` | `packages/rsc` | React Server Components 集成支持 |
| `run-engine` (内部) | `internal-packages/run-engine` | 平台侧的任务调度与执行引擎 |

资料来源：[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]()

一个最简任务定义示例：

```ts
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 描述了以下子系统：

```mermaid
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](https://github.com/triggerdotdev/trigger.dev/issues/3905)

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

## See Also

- [CLI 命令参考](https://trigger.dev/docs/cli)
- [自托管部署指南](https://trigger.dev/docs/self-hosting/overview)
- [TypeScript SDK 文档](https://trigger.dev/docs/sdk)
- [Python 扩展用法](https://trigger.dev/docs/python-extension)

---

<a id='page-2'></a>

## CLI v3, MCP & Known Issues

### 相关页面

相关主题：[System Architecture & Repository Overview](#page-1), [SDK: Tasks, Realtime, Waits & AI Chat](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli-v3/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json)
- [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)
- [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json)
- [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md)
- [packages/python/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/package.json)
- [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)
- [packages/plugins/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/plugins/package.json)
- [packages/rsc/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/rsc/package.json)
- [packages/redis-worker/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/package.json)
- [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)
</details>

# 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 的一级命令矩阵，下表汇总其用途：

| 命令 | 主要功能 |
| :--- | :--- |
| `login` | 触发.dev 账号登录，支持后续鉴权操作 |
| `init` | 在已有项目中初始化 Trigger.dev |
| `dev` | 本地运行 Trigger.dev 任务 |
| `deploy` | 将 v3 项目部署到云端 |
| `whoami` | 显示当前登录用户与项目详情 |
| `logout` | 退出当前账号 |
| `list-profiles` | 列出本地保存的所有 CLI 配置档案 |
| `preview archive` | 归档一条预览分支 |
| `promote` | 将历史部署版本提升为当前版本 |
| `switch` | 在多个 CLI 配置档案之间切换 |

资料来源：[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 暴露的能力。

```mermaid
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](https://github.com/triggerdotdev/trigger.dev/issues/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](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.5) [Release v4.5.0-rc.0](https://github.com/triggerdotdev/trigger.dev/releases/tag/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](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.6) [Release v4.5.0-rc.5](https://github.com/triggerdotdev/trigger.dev/releases/tag/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](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)
- [CLI v3 命令文档](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)
- [Python 扩展说明](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)
- [Issue #3905: catalog comparator 解析失败](https://github.com/triggerdotdev/trigger.dev/issues/3905)
- [v4.5.0-rc.5 发布说明](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.5)

---

<a id='page-3'></a>

## SDK: Tasks, Realtime, Waits & AI Chat

### 相关页面

相关主题：[CLI v3, MCP & Known Issues](#page-2), [Run Engine, Scheduling, Webapp & Self-Hosting](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)
- [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md)
- [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)
- [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json)
- [internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)
- [internal-packages/schedule-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md)
- [apps/coordinator/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/apps/coordinator/README.md)
- [internal-packages/clickhouse/src/taskRuns.test.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.test.ts)
- [internal-packages/clickhouse/src/sessions.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/sessions.ts)
- [packages/redis-worker/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/README.md)
- [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)
</details>

# SDK：Tasks、Realtime、Waits 与 AI Chat

Trigger.dev 是一个用于构建和部署可完全托管的 AI 智能体与工作流的开源平台。其 TypeScript/JavaScript SDK 为开发者提供了一组高层 API（任务、实时订阅、等待点、批量调用、调度等），并由一组内部引擎（`@internal/run-engine`、`@internal/schedule-engine`、Coordinator、ClickHouse 存储等）支撑运行时行为。资料来源：[README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)、[packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/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](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md)、[internal-packages/sdk-compat-tests/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/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](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json)。

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

### 2.1 在代码库中声明 Task

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

```ts
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](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)。

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

```mermaid
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](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)、[apps/coordinator/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/apps/coordinator/README.md)、[internal-packages/clickhouse/src/sessions.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/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](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)、[internal-packages/schedule-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/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](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)。

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

| SDK 能力 | 主要 API/概念 | 运行时/存储后端 |
| :--- | :--- | :--- |
| 任务执行 | `task({ id, run })` | `RunEngine` + `RunAttemptSystem` |
| 实时与可观测 | tags / metadata / Trace | Coordinator + ClickHouse `task_runs_v2` |
| 等待与并发 | Waitpoint、并发键 | `WaitpointSystem`、`ReleaseConcurrencyQueue` |
| 调度 | `upsertTaskSchedule` | `ScheduleEngine` + Redis 分布式调度 |
| 批量与回放 | bulk action group ids | `BatchSystem` + ClickHouse |
| 多语言扩展 | `pythonExtension` | Build Pipeline + `/opt/venv` |

资料来源：[internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)、[internal-packages/schedule-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md)、[internal-packages/clickhouse/src/taskRuns.test.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.test.ts)、[packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/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](https://github.com/triggerdotdev/trigger.dev/issues/3905)）。这是升级到 v4.5.0-rc.x 时需要留意的兼容性问题。资料来源：[issue #3905](https://github.com/triggerdotdev/trigger.dev/issues/3905)、[packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)。

## See Also

- [Self-hosting Overview](https://trigger.dev/docs/self-hosting/overview)
- [CLI Commands Reference](https://trigger.dev/docs/cli-commands)
- [Run Engine Architecture (内部)](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)
- [Schedule Engine (内部)](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md)
- [Python Build Extension](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)

---

<a id='page-4'></a>

## Run Engine, Scheduling, Webapp & Self-Hosting

### 相关页面

相关主题：[System Architecture & Repository Overview](#page-1), [SDK: Tasks, Realtime, Waits & AI Chat](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)
- [internal-packages/schedule-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md)
- [internal-packages/schedule-engine/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/package.json)
- [internal-packages/clickhouse/src/sessions.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/sessions.ts)
- [internal-packages/clickhouse/src/taskRuns.test.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.test.ts)
- [packages/redis-worker/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/README.md)
- [packages/redis-worker/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/package.json)
- [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)
- [packages/cli-v3/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json)
- [apps/webapp/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/apps/webapp/package.json)
- [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)
- [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md)
- [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)
- [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json)
</details>

# Run Engine, Scheduling, Webapp & Self-Hosting

## 1. 概述

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

| 组件 | 包路径 | 角色 |
| :--- | :--- | :--- |
| Run Engine | `internal-packages/run-engine` | 任务运行生命周期与执行编排的核心 |
| Schedule Engine | `internal-packages/schedule-engine` | 基于 Cron 的定时任务调度与分发 |
| Webapp | `apps/webapp` | 面向用户的 Dashboard、运行监控、批量操作界面 |
| Self-Hosting | Docker / Helm Chart | 用于私有化部署的发行包与编排模板 |

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

## 2. Run Engine（运行引擎）

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

```mermaid
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](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)：

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

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

## 3. Schedule Engine（调度引擎）

Schedule Engine 提供与 Run Engine 一致风格的集中式调度抽象，导出 `ScheduleEngine` 主类。典型用法如下 [internal-packages/schedule-engine/README.md:23-44](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md)：

```ts
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](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/package.json)。Schedule Engine 的运行结果最终仍然写入 Run Engine 的同一组持久化资源（如 Prisma、ClickHouse），并由 `cron-parser` + `cronstrue` 解析和可读化 Cron 表达式 [internal-packages/schedule-engine/package.json:17-19](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/package.json)。

## 4. Webapp 与运行时数据存储

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

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](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/sessions.ts)。运行（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](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.test.ts)。

## 5. Self-Hosting（自托管）

Trigger.dev 提供两条主线自托管路径 [README.md:38-46](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)：

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](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)。官方在 Discord 中专门设立了 `#self-hosting` 频道以提供社区支持 [README.md:48-50](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)。

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

| 命令 | 用途 |
| :--- | :--- |
| `trigger login` | 登录 Trigger.dev 账户 |
| `trigger init` | 在现有项目里初始化 Trigger.dev |
| `trigger dev` | 本地运行任务 |
| `trigger deploy` | 部署 v3 项目到云端 |
| `trigger promote` | 将历史版本晋升为当前版本 |
| `trigger preview archive` | 归档一个 preview 分支 |

需要注意的是，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](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)。
- **Redis Worker**：`@trigger.dev/redis-worker` 提供带 Schema 校验的分布式队列、可配置并发与拉取速率，以及对未来时刻（future date）调度的支持 [packages/redis-worker/README.md:1-8](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/README.md)。
- **Trigger SDK**：`@trigger.dev/sdk` 是官方 TypeScript SDK，提供 `task()` 任务定义、部署与运行时 API；其 TypeScript 类型与子路径导出在 `packages/core` 的 `package.json` 中统一维护 [packages/trigger-sdk/README.md:1-20](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md)。

## See Also

- [Run Engine Source](https://github.com/triggerdotdev/trigger.dev/tree/main/internal-packages/run-engine)
- [Schedule Engine Source](https://github.com/triggerdotdev/trigger.dev/tree/main/internal-packages/schedule-engine)
- [Webapp Application](https://github.com/triggerdotdev/trigger.dev/tree/main/apps/webapp)
- [Self-hosting Guides](https://trigger.dev/docs/self-hosting/overview)
- [CLI v3 Reference](https://github.com/triggerdotdev/trigger.dev/tree/main/packages/cli-v3)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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; install=@trigger.dev/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

<!-- canonical_name: triggerdotdev/trigger.dev; human_manual_source: deepwiki_human_wiki -->