#触发器

触发器说明哪个 Provider 事件可以启动一个 workflow。Hub workflow 页面介绍匹配之后运行的 step、输入、路由、提示词和截止时间。

.paseo/workflows/github-issue.yml：

name: triage-issue
on: github.issue_created
filters:
  repo: acme/api
  from_users: [alice]
max_runtime: 2h
steps:
  - id: work
    environment: dev
    max_runtime: 90m
    idle_timeout: 10m
    agent: codex
    prompt:
      - text: Call hub.finish_execution when the step is complete.
      - text: ${{ paseo.prompt }}

逐字段的说明见配置参考。

#在 Hub 中选择 Agent

在 Hub 控制台中创建或编辑触发器时，先选择 daemon 并输入它的工作目录。Hub 不会预填目录：它是那台机器上的路径，必须存在，而且只有你知道 Agent 应该在哪个仓库中工作。随后 Hub 会向该 daemon 查询可用的 Provider、模型、执行模式和思考选项。建议的模型和模式是该 daemon 的默认值。

只有被授予 hub.execute 的 daemon 才会作为目标出现，Provider 也只提供 Claude、Codex 和 OpenCode。Hub 在每次运行时都会预先批准它自己的工具，因为没有人在键盘前批准它们，而只有这些 Provider 的 daemon 契约接受这种做法。

修改 daemon 或工作目录会重新加载这些选项。如果已有的触发器指定的模型、模式或思考选项不再由 daemon 报告，Hub 会把该值标记为不可用，但不会替换它。你可以保留原先编写的值、选择当前可用的值，或切换到 YAML 编辑。

如果 daemon 离线或需要更新的 Paseo 版本，Agent 选择器会显示错误和重试操作。触发器的其余部分及其 YAML 仍然可以编辑。

#保存时会对照 daemon 检查 Agent

保存触发器时，Hub 会请目标 daemon 校验它将要启动的 Agent：Provider、模型、模式、思考选项、Provider 原生选项，以及某个选择可以选中的每个具名 Agent。daemon 不提供的值会在保存时被拒绝，并指出对应字段，而不是等到第一次运行才失败。

run.agent.mode: Mode 'default' is not available for provider 'opencode'

这项检查需要 daemon 已连接。daemon 离线时，新的触发器，以及对 daemon、工作目录或 Agent 的修改都无法保存；拒绝信息会指出是哪个 daemon。编辑已有触发器的提示词、过滤条件或限制则无论如何都能保存。

无论在哪里编写触发器，都会运行相同的检查：控制台表单、它的 YAML 模式、POST /api/v1/triggers/install、paseo hub init 和 paseo hub deploy。

#继续同一个 Agent

控制台中的触发器默认为 Same conversation。同一个 Slack 或 Discord 线程中的消息、同一个 GitHub issue 或 Pull Request 上的事件，以及同一个 Linear issue 上的事件，都会在该项目中继续现有的 Agent。没有对话的事件会启动一个新的 Agent。

如果 Agent 正忙，新的提示词会引导它当前的工作。每次到达都保留各自的输出限制和完成状态。如果可复用的工作区已被归档，Hub 会在发送提示词之前请 Paseo 恢复它。

选择 Custom key 可以按某个输入对到达的事件分组，选择 New agent 则让它们彼此独立。自包含的触发器文档也可以表达同样的选择：

name: support
on:
  slack.mention:
    filters:
      from_users: [U01234567]
run:
  target:
    daemon: laptop
    cwd: /Users/you/code/support
  agent:
    provider: codex
  continuation:
    mode: conversation
  max_runtime: 30m
  idle_timeout: 5m
  prompt: Handle this request and call finish_execution when complete.

延续参考介绍了键和 Agent 复用。运行详情会显示每次到达是创建、继续还是恢复了 Agent。

Hub 在每段提示词中都包含一个 executionId。使用持续的 Agent 时，请把这个 ID 传给 reply 和 finish_execution。这些工具作用于该次到达的目标和契约；旧的或无关的执行 ID 会被拒绝。

#事件

on	触发时机
github.issue_created	有 issue 被创建。
github.pull_request_created	有 Pull Request 被创建。
github.issue_comment_created	issue 上新增了评论。
github.pull_request_comment_created	Pull Request 上新增了对话评论。
github.issue_label_added	issue 被添加了标签。
github.pull_request_label_added	Pull Request 被添加了标签。
slack.mention	机器人在频道中被提及。
discord.mention	机器人在服务器中被提及。
manual.run	通过 API 发起了一次运行。

新的 GitHub workflow 应使用语义化事件。五个旧版事件仍然兼容：github.issues、github.issue_comment、github.pull_request_review、github.pull_request_review_comment 和 github.push。完整的 workflow 以及何时使用哪个事件，见 GitHub 触发器。

每个 Provider 的页面记录了它的事件及其提供的数据：

• GitHub 触发器
• Slack 触发器
• Discord 触发器

#过滤条件

filters 是必填的，而且 from_users 必须存在且非空。缺少它的触发器会在校验时被拒绝。

这个白名单防止陌生人在公开 issue 上的一条评论就在你的机器上启动 Agent。它没有默认值，因为安全的默认值因仓库而异。

白名单只是一层防御。它不能让一个被盗用的、已获准的账号变得可信，也不能让提示词注入变得无害。为外部触发器选择 daemon、工作目录、Provider 策略和输出之前，请先阅读 Hub 安全。

过滤条件	适用于	匹配内容
from_users	全部	GitHub：登录名。Slack 和 Discord：用户 ID，而不是显示名称
repo	GitHub	owner/name
workspace	Slack	Team ID，T01234567
guild	Discord	服务器 ID
channels	Slack、Discord	频道 ID
contains	全部	GitHub 子串；Slack 和 Discord 调用前缀
pattern	全部	调用前缀
connection	全部	组织有多个连接时的连接 slug
label	GitHub 添加标签事件	本次投递添加的标签，不区分大小写
labels	GitHub	issue 或 Pull Request 当前带有的每个所列标签，不区分大小写

所有条件都必须通过。没有 any 模式。

#事件来自哪个连接

repo、workspace 和 guild 在配置激活时会被解析为不可变的 ID，并确定拥有它们的连接。如果指定的资源在组织中没有对应的连接，激活就会失败，因此你会在推送时发现问题，而不是等到有人评论时。

省略资源过滤条件时，触发器会监听组织中该 Provider 的所有连接。要把它固定到某一个连接：

filters:
  connection: acme-github
  from_users: [alice]

激活时编译了什么，见 Hub 的工作原理。

#两个触发器同时匹配时

两个都会运行。触发器没有顺序，也不会相互遮蔽，无论是在同一个配置中还是跨项目。

#回复

在需要回复的 step 上设置 allow_outputs。回复能力是 slack.reply 和 discord.reply。

• 当 step 需要不止一次更新时，设置 max。
• 当 step 必须至少发出一次回复才能完成时，设置 required: true。必需的类型必须已注册，并且在该执行上下文中可用。

GitHub 没有回复能力；带有 github 块的 step 会改为通过 gh 发表评论。契约见输出能力参考。

这项声明授予 hub.reply 工具；提示词必须告诉 Agent 调用它。见告诉 Agent 调用哪个工具。