pp-trigger-dev

Trigger.dev — Printing Press CLI

前置条件：安装 CLI

此技能使用 trigger-dev-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install trigger-dev --cli-only
   

2. 验证：trigger-dev-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent／运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/developer-tools/trigger-dev/cmd/trigger-dev-pp-cli@latest

如果安装后 --version 报告 "command not found"，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，不要继续执行技能命令。

何时使用此 CLI

当 Agent 任务需要以编程方式操作 Trigger.dev 时，可使用此 CLI：对失败的运行进行分类、审计计划任务健康状况、比较不同环境中的环境变量、计算多次运行的大模型成本，或监视新出现的失败。它是官方 trigger.dev CLI 的补充工具（官方 CLI 侧重于开发时的 deploy/init/dev），通过可脚本化、面向 Agent 的原生命令，提供管理 API 接口，并支持离线 FTS 和带类型的退出码。

独特功能

其他用于此 API 的工具都不具备这些功能。

实时终端告警

• runs watch — 监视运行中的新失败，并在失败出现的瞬间中断终端操作，同时发送桌面通知和声音告警，并返回非零退出码，因此可与 Shell 循环配合使用。

  当 Agent 或值班工程师需要在失败出现的瞬间做出响应，而不是轮询控制面板或等待邮件时，请使用此功能。

  trigger-dev-pp-cli runs watch --task daily-digest --notify --sound
  

不断积累的本地状态

• schedules stale — 列出已停止触发或近期运行成功率较低的计划任务——这是其他工具都无法提供的僵尸 cron 审计。

  在环境变量轮换、Postgres URL 变更或任何可能导致 cron 任务失效却无人察觉的静默配置变更后，请使用此功能。

  trigger-dev-pp-cli schedules stale --days 7 --min-success-rate 0.5 --agent
  

• runs span-cost — 遍历近期运行，按模型和任务归类并显示成本最高的大模型 span，同时列出 token 总数和费用——这是财务负责人真正需要的报告。

  当 AI 产品工程师或 Agent 需要在下一个账单周期结束前，找出哪个模型与任务组合消耗了大部分大模型预算时，请使用此功能。

  trigger-dev-pp-cli runs span-cost --since 7d --by model,task --top 20 --agent --select spans.model,spans.task_identifier,spans.total_cost_cents
  

• failures top — 统计给定时间范围内重复出现最多的（任务、错误特征）组合——通过机械式分组完成，不使用大模型或 NLP。

  在事故处理中，当 Agent 需要找出主要错误特征，而不是手动阅读 200 份堆栈跟踪时，请使用此功能。

  trigger-dev-pp-cli failures top --since 7d --top 20 --agent --select patterns.task_identifier,patterns.error_signature,patterns.count,patterns.last_occurred_at
  

• runs find — 在已同步的运行表中使用 FTS5 进行搜索，涵盖错误消息、标签、元数据和任务标识符，并按最近程度排序。

  当 Agent 只有一段错误消息，且需要找到匹配的运行而不想输入 TRQL 时，请使用此功能。

  trigger-dev-pp-cli runs find "payload too large" --status FAILED --since 30d --agent
  

运维规范

• envvars diff — 并排比较两个环境中的环境变量，显示缺失的键、多余的键和不同的值（已屏蔽）。

  当 Agent 正在排查“在 staging 上正常，在 prod 上失败”的问题时，请使用此功能——答案几乎总是环境变量，而 diff 让你只需执行一条命令即可找到答案。

  trigger-dev-pp-cli envvars diff --from prod --to staging --project proj_abc --agent
  

Agent 易用性

• runs get — runs get 会返回带类型的退出码：0=COMPLETED、20=FAILED、21=CRASHED、22=SYSTEM_FAILURE、23=CANCELED、3=not-found、4=auth-error。Cobra 注解 pp:typed-exit-codes 让用户和 Agent 可以直接读取此契约。

  当 Agent 正在编写遍历多个运行的 Shell 循环，并希望根据成功或失败进行分支处理而不解析 JSON 时，请使用此功能。

  trigger-dev-pp-cli runs get run_abc123 --json && echo COMPLETED || echo "$?"
  

命令参考

batches — 管理批次

• trigger-dev-pp-cli batches <batchId> — 根据批次 ID 检索批次，包括其状态和该批次中所有运行的 ID。

deployments — 管理部署

• trigger-dev-pp-cli deployments get-latest-v1 — 检索经过身份验证的项目的最新非托管部署信息。
• trigger-dev-pp-cli deployments get-v1 — 根据部署 ID 检索特定部署的信息。
• trigger-dev-pp-cli deployments list-v1 — 列出经过身份验证的环境中的部署，按时间从近到远排序。

projects — 管理项目

query — 管理查询

• trigger-dev-pp-cli query execute-v1 — 对运行数据执行 TRQL（Trigger.dev Query Language）查询。TRQL 是一种类似 SQL 的查询语言，……
• trigger-dev-pp-cli query get-schema-v1 — 获取 TRQL 查询的架构，包括所有可用表、列、数据类型、说明以及……
• trigger-dev-pp-cli query list-dashboards-v1 — 列出可用的内置仪表板及其小组件。每个仪表板都包含用于常见……的预构建 TRQL 查询。

queues — 管理队列

• trigger-dev-pp-cli queues list-v1 — 列出环境中的所有队列，并支持分页。
• trigger-dev-pp-cli queues retrieve-v1 — 根据队列 ID，或类型和名称获取队列。

runs — 管理运行

• trigger-dev-pp-cli runs list-v1 — 列出特定环境中的运行。你可以按状态、创建时间、任务标识符、版本等筛选运行。
• trigger-dev-pp-cli runs retrieve-v1 — 检索运行信息，包括其状态、有效负载、输出和尝试记录。如果你使用……进行身份验证

schedules — 管理计划

• trigger-dev-pp-cli schedules create-v1 — 根据指定选项创建新的 IMPERATIVE 计划。
• trigger-dev-pp-cli schedules delete-v1 — 根据计划 ID 删除计划。此操作仅适用于在仪表板或……中创建的 IMPERATIVE 计划
• trigger-dev-pp-cli schedules get-v1 — 根据计划 ID 获取计划。
• trigger-dev-pp-cli schedules list-v1 — 列出所有计划。你也可以对结果进行分页。
• trigger-dev-pp-cli schedules update-v1 — 根据计划 ID 更新计划。此操作仅适用于在仪表板或……中创建的 IMPERATIVE 计划

tasks — 管理任务

• trigger-dev-pp-cli tasks — 使用 SDK 4.3.1+ 批量触发任务，最多支持 1,000 个有效负载（之前的版本为 500 个）。

timezones — 管理时区

• trigger-dev-pp-cli timezones — 获取计划任务支持的所有时区。

waitpoints — 管理等待点

• trigger-dev-pp-cli waitpoints complete-token-callback-v1 — 使用令牌……时 url 字段中返回的预签名回调 URL 完成等待点令牌。
• trigger-dev-pp-cli waitpoints complete-token-v1 — 完成等待点令牌，解除通过 wait.forToken() 等待该令牌的运行的阻塞。可选的 data……
• trigger-dev-pp-cli waitpoints create-token-v1 — 创建新的等待点令牌，可用于暂停运行，直到外部事件完成该令牌。该令牌……
• trigger-dev-pp-cli waitpoints list-tokens-v1 — 返回当前环境中等待点令牌的分页列表。结果按创建日期排序，……
• trigger-dev-pp-cli waitpoints retrieve-token-v1 — 根据 ID 检索等待点令牌，包括其当前状态，以及完成后的输出。

查找合适的命令

如果你知道要做什么，但不知道该用哪个命令，可以直接向 CLI 询问：

trigger-dev-pp-cli which "<capability in your own words>"

which 会根据此 CLI 精选的功能索引，将自然语言功能查询匹配到最合适的命令。退出码 0 表示至少有一个匹配项；退出码 2 表示没有可信的匹配项，此时请改用 --help 或使用更具体的查询。

操作示例

排查今天的失败

trigger-dev-pp-cli sync --resources runs --since 1d && trigger-dev-pp-cli failures top --since 1d --top 10 --agent --select 'task,error_signature,count,last_seen'

同步今天的运行记录，然后按任务和规范化后的错误特征分组，找出主要的失败模式。

监控部署时段

trigger-dev-pp-cli runs watch --task my-task --notify --sound

部署期间保持终端运行 — 首次出现新的 FAILED 运行记录时，命令会以非零状态码退出并发出提示音。

审计不同环境间的环境变量差异

trigger-dev-pp-cli envvars diff --project proj_abc --from prod --to staging --agent

比较两个环境的变量；值会被隐藏，并标记差异。

查找出现特定错误的运行记录

trigger-dev-pp-cli runs find "connection timeout" --since 7d --status FAILED --agent --select 'id,taskIdentifier,error.message,createdAt'

使用 --select 缩小 Agent 上下文，只保留重要字段，并对本地存储进行子串搜索。

运行精选的 TRQL 配方

trigger-dev-pp-cli query run cost-by-model-7d --param env=prod --agent

无需编写 SQL，即可执行精选的 TRQL 查询。配方涵盖按常见维度统计的失败率、成本和延迟。

身份验证设置

身份验证使用 Trigger.dev 密钥，并通过 Authorization: Bearer 标头传递。将 TRIGGER_SECRET_KEY 设置为对应环境的密钥 — 开发环境使用 tr_dev_…，生产环境使用 tr_prod_…，个人访问令牌使用 tr_pat_…。每个密钥都限定于特定环境：开发密钥无法管理生产环境的运行记录。

运行 trigger-dev-pp-cli doctor 以验证设置。

Agent 模式

为任意命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。在冗长的 API 响应中，这对控制上下文大小至关重要：

  trigger-dev-pp-cli batches mock-value --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 支持离线使用 — 有本地 SQLite 存储时，同步和搜索命令可以使用它

• 非交互式 — 从不提示输入，每项输入都通过标志传入

• 显式重试 — 仅当已存在的创建操作也应视为成功时使用 --idempotent；仅当删除目标不存在也应视为成功时使用 --ignore-missing

响应信封

从本地存储或 API 读取数据的命令会将输出包装在来源信息信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时 API 还是本地存储。只有当 stdout 连接到终端时，才会将易读的 N results (live) 摘要打印到 stderr — 管道或 Agent 消费者会在 stdout 上收到纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有异常之处时，请记录下来：

trigger-dev-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
trigger-dev-pp-cli feedback --stdin < notes.txt
trigger-dev-pp-cli feedback list --json --limit 10

条目会保存在本地的 ~/.trigger-dev-pp-cli/feedback.jsonl。除非设置了 TRIGGER_DEV_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 TRIGGER_DEV_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认情况下，数据仅保存在本地。

写下让你意外的地方，而不是提交错误报告。简短、具体、一行即可：这些细节会不断累积。

输出交付

每条命令都支持 --deliver <sink>。输出会写入指定的接收端，并可同时输出到 stdout，也可替代 stdout，这样 Agent 就能路由命令结果，无需手动通过管道传递。支持以下三种接收端：

接收端	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（--compact 时使用 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回列出受支持方案的结构化错误。Webhook 失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。若定时运行的 Agent 每次都以相同配置调用同一命令，就可以使用配置 — 例如 HeyGen 的 “Beacon” 模式。

trigger-dev-pp-cli profile save briefing --json
trigger-dev-pp-cli --profile briefing batches mock-value
trigger-dev-pp-cli profile list --json
trigger-dev-pp-cli profile show briefing
trigger-dev-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、为 help 或 --help → 显示 trigger-dev-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并附加 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/developer-tools/trigger-dev/cmd/trigger-dev-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add trigger-dev-pp-mcp -- trigger-dev-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which trigger-dev-pp-cli 如果未找到，提供安装选项（参见本技能顶部的先决条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   trigger-dev-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，进一步查看子命令帮助：trigger-dev-pp-cli <command> --help。