building-loops

构建循环

Loop 是一种工作流，带有 origin_product: "loops" 标签，且只有一种结构：一个触发器、一个“Create AI task”步骤、一个可选的通知步骤，以及一个退出节点。桌面端 Loops 界面会读取这种结构。如果工作流包含其他内容，它仍会运行，但桌面端会将其显示为“已在工作流编辑器中更改”，并设为只读。

按以下顺序构建：先用 workflows-create 创建草稿，再用 workflows-test-run 逐步测试；对于定时循环，接着使用 workflows-schedule-create，然后在用户确认后使用 workflows-enable。对于本文未涵盖的操作（修改草稿、发布已上线的工作流、读取日志），请使用 building-workflows 技能。

图结构

只替换尖括号中的值。用户不需要通知时，请省略 notify 步骤及其边。

{
  "name": "<short name>",
  "description": "",
  "status": "draft",
  "origin_product": "loops",
  "exit_condition": "exit_only_at_end",
  "variables": [{ "key": "task_final_message", "type": "string", "default": "" }],
  "actions": [
    { "id": "trigger", "name": "Trigger", "type": "trigger", "config": <trigger config> },
    {
      "id": "create_task",
      "name": "Create AI task",
      "type": "function",
      "config": {
        "template_id": "template-posthog-create-task",
        "inputs": {
          "prompt": { "value": "<task prompt>" },
          "repository": { "value": "<owner/name>" },
          "connectors": { "value": ["<mcp connection id>"] },
          "skills": { "value": ["<skill name>"] },
          "posthog_mcp_scopes": { "value": "read_only" },
          "non_failure_status_codes": { "value": [409] }
        }
      },
      "output_variable": [{ "key": "task_final_message", "result_path": "final_message" }]
    },
    { "id": "notify", "name": "Notify", "type": "function", "config": <notify config> },
    { "id": "exit", "name": "Exit", "type": "exit", "config": { "reason": "Task finished" } }
  ],
  "edges": [
    { "from": "trigger", "to": "create_task", "type": "continue" },
    { "from": "create_task", "to": "notify", "type": "continue" },
    { "from": "notify", "to": "exit", "type": "continue" }
  ]
}

任务步骤

prompt 为必填项。该步骤会在无人值守的情况下运行，因此请将其写成完整的任务说明：要做什么、怎样才算“完成”，以及需要报告什么。

切勿在提示词中使用 {event.properties.<name>} 模板来放入事件文本。每次运行都会在单独的 <triggering_event> 区块中收到完整的触发事件；该区块会标明内容是数据，并转义其中的尖括号，因此区块内的任何内容都无法伪造标签。请直接指出属性名称，让运行过程从该处读取：

从触发事件的 text 属性中读取消息，然后……

模板会将原始值直接渲染到提示词的指令部分，位于该区块之前，且不会进行转义。Slack 发帖人、问题作者或客户的终端用户都可以编写该值，因此精心构造的内容可能会被 Agent 当作指令读取，而 Agent 可能持有仓库凭据。

只有循环需要时，才包含其他输入：

• repository：仅当任务涉及代码时，使用用户提供的 owner/name。切勿使用记忆中的仓库。请先确认仓库可访问：GitHub 使用 integrations-list，然后使用 integrations-github-repos-retrieve 检索该确切名称。
• connectors：来自 mcp-connections-list 的 ID。只接受与项目中所有人共享的连接。
• skills：来自 skill-list 的确切名称，最多 10 个。
• posthog_mcp_scopes：默认使用 read_only。只有用户要求任务在 PostHog 中进行更改时，才使用 full。
• channel：循环所属的空间，格式为 <space id>|<space name>。只有应用告知你循环将在哪个空间中创建时才设置此项，切勿使用用户输入的空间名称。此后，每次运行都会显示在该空间的动态中，循环也会列在该空间下。
• reply_in_slack_thread：对于由 Slack 触发且结果应返回到线程中的循环，设置为 true（JSON 布尔值，不是模板字符串）。这种情况下无需另加通知，因此请省略 notify 步骤。

每个循环都必须保持图中所示的 non_failure_status_codes 不变。运行触及任务限制时，API 会返回 409。若不提供此输入，该步骤会以通用的获取错误失败，用户也就看不到任务限制消息。

工作流会在此步骤等待，直到任务完成。下一步随后会在该步骤的结果中看到 final_message、pr_urls 和 status。

触发器配置

为用户指定的来源选择触发器。桌面应用循环表单可编辑 Schedule 和 GitHub 触发器。

Schedule，在计划行上设置频率（如下）：

{ "type": "schedule" }

GitHub 事件，一个仓库，一种事件类型：

{
  "type": "internal-event",
  "filters": {
    "source": "internal-events",
    "events": [{ "id": "$github_event_received", "type": "events" }],
    "properties": [
      { "key": "repository", "value": ["<owner/name>"], "operator": "exact", "type": "event" },
      {
        "key": "event_type",
        "value": ["<issues | issue_comment | pull_request | push>"],
        "operator": "exact",
        "type": "event"
      },
      { "key": "actor_access", "value": ["write"], "operator": "exact", "type": "event" }
    ]
  }
}

保留 actor_access 过滤器。它可防止没有仓库写入权限的人启动任务。用户要求缩小到某个操作时（“当一个议题被打开时”），再添加一个属性过滤器：{ "key": "action", "value": ["<action>"], "operator": "exact", "type": "event" }。没有 action 过滤器的 pull_request 循环会在每次向所有已打开的拉取请求推送内容时触发。

事件	操作
issues	opened、reopened、closed、edited、deleted、labeled、unlabeled、assigned、unassigned、pinned、unpinned、transferred
pull_request	opened、reopened、closed、synchronize、edited、ready_for_review、converted_to_draft、review_requested、review_request_removed、labeled、unlabeled、assigned、unassigned
issue_comment	created、edited、deleted
push	无，push 没有操作

Slack 消息，位于一个或多个频道中。channel 为必填项，且接受频道 ID。使用项目的 Slack 集成（integrations-list，类型为 slack）中的 integrations-channels-retrieve，将名称解析为 ID。切勿猜测 ID：

{
  "type": "internal-event",
  "filters": {
    "source": "internal-events",
    "events": [{ "id": "$slack_message_received", "type": "events" }],
    "properties": [
      { "key": "channel", "value": ["<channel id>"], "operator": "exact", "type": "event" },
      { "key": "bot_id", "value": "is_not_set", "operator": "is_not_set", "type": "event" },
      { "key": "thread_ts", "value": "is_not_set", "operator": "is_not_set", "type": "event" }
    ]
  }
}

保留 bot_id 和 thread_ts 过滤器。它们会将循环限制为用户手动输入的顶层消息，这正是工作流编辑器的 Slack 触发器所创建的循环。不加这两个过滤器，循环就会对其他应用发布的每条提醒以及任意线程下的每条回复启动任务，并消耗每日任务额度。只有用户提出要求时才放宽限制：使用 bot_id 和 is_set，仅匹配应用和机器人；对指定发布者使用 user 或 app_id 的 exact 过滤器；移除 thread_ts 过滤器以包含回复。

PostHog 事件，每次符合条件的事件发生时触发：

{
  "type": "event",
  "filters": {
    "events": [{ "id": "<event>", "name": "<event>", "type": "events", "order": 0, "properties": [] }],
    "properties": [],
    "filter_test_accounts": false
  }
}

PostHog 事件触发器会在每次符合条件的事件发生时创建任务，而且工作流编辑器的用量警告不会在此路径中运行。创建循环前先设定范围：使用属性过滤器缩小事件范围，并通过 trigger_masking 对常见事件进行限流；它是与 actions 和 edges 同级的顶层字段。

"trigger_masking": { "hash": "{person.id}", "ttl": 3600, "threshold": null }

hash 是用于去重键的 HogQL 模板，因此 {person.id} 会对每个人触发一次。ttl 是抑制同一哈希值重复触发的时长，单位为秒，范围从 60 秒到约 3 年。threshold 则会在同一哈希值匹配 N 次后触发一次；普通去重时请省略该项。切勿发送 bytecode；服务器会根据 hash 编译它。一个工作流每天最多可创建 100 个任务，一个项目的所有工作流合计每天最多可创建 500 个任务，因此，繁忙事件上的无限循环会耗尽项目额度，之后触发的下一个工作流将被拒绝。在桌面应用中编辑循环时，会保留 trigger_masking。

手动，从“手动触发”按钮运行：

{
  "type": "manual",
  "template_id": "template-source-webhook",
  "inputs": { "event": { "value": "$workflow_triggered" }, "distinct_id": { "value": "{request.body.user_id}" } }
}

Schedule row

工作流创建后，使用 workflows-schedule-create 创建它，并将工作流 ID 作为 workflow_id。rrule 必须且只能是以下其中一种。不要使用 BYHOUR 或 BYMINUTE。

频率	rrule
每小时	FREQ=HOURLY;INTERVAL=1
每天	FREQ=DAILY;INTERVAL=1
工作日	FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR
每周一天	FREQ=WEEKLY;INTERVAL=1;BYDAY=<MO..SU>
一次	FREQ=DAILY;COUNT=1

starts_at 是首次运行时间，格式为带 UTC 偏移量的 ISO 8601 时间。运行时刻取自该值，因此请根据用户所需的时间选择下一次发生的日期和时间。timezone 是用户的 IANA 时区。每小时运行的计划从整点开始。

Notify step

任务的结果通过任务步骤中的 output_variable 传递到通知步骤：{variables.task_final_message} 是 Agent 的结束消息。如果消息需要链接到拉取请求，请将 { "key": "task_pr_urls", "result_path": "pr_urls" } 添加到列表中，并添加相匹配的 variables 条目。

Slack，template_id 为 template-slack。slack_workspace 是来自 integrations-list 的 Slack 集成 ID。使用 integrations-channels-retrieve 解析 channel，并在总结之前读取该频道的 is_member。值为 False 表示 PostHog Slack 应用不在该频道中：首次实际运行时将无法发帖，结果也无人收到，因此请让用户邀请该应用，而不是构建循环：

{
  "template_id": "template-slack",
  "inputs": {
    "slack_workspace": { "value": <integration id> },
    "channel": { "value": "<channel id>" },
    "text": { "value": "<loop name> finished: {variables.task_final_message}" }
  }
}

电子邮件：将步骤的 type 设置为 function_email，而不是 function。from 是来自 integrations-list 的发件人 ID，to 是包含用户地址的对象。将 html 设为空字符串：运行时要求提供此键，设为空字符串时会发送纯文本电子邮件。email 输入支持 Liquid，因此在此处使用 {{ variables.task_final_message }}：

{
  "template_id": "template-email",
  "inputs": {
    "email": {
      "value": {
        "from": { "integrationId": <sender id> },
        "to": { "email": "<user email>", "name": "" },
        "subject": "<loop name> finished",
        "text": "{{ variables.task_final_message }}",
        "html": ""
      }
    }
  }
}

Structured output

如果通知步骤或用户需要任务的特定字段（例如判断结果或计数），请让任务直接提供该字段，而不要解析文本。为每个字段添加一个输出变量，将其 result_path 设为 output.<name>，并添加类型为 string、number 或 boolean 的相匹配的 variables 条目。任务会收到要返回哪些字段的说明，之后可通过 {variables.<name>} 获取相应值。如果 final_message 已足够，则无需这样做。

Test run

在安排或启用草稿之前先进行测试。workflows-test-run 会逐步运行，并模拟所有出站调用，因此不会实际创建任何内容。通知步骤和任务都会进行测试，因此测试运行通过只能说明工作流图已正确连接，并不代表 Slack 或电子邮件投递正常。

1. 对于计划循环，不设置 current_action_id，并使用 globals { "event": { "event": "$scheduled", "properties": {} } } 运行。对于 GitHub 或 Slack 循环，请发送触发器的事件名称，以及符合筛选条件的属性，不要提供用户。对于 PostHog 事件循环，请发送该事件并附带用户。
2. 预期 nextActionId = create_task。再次运行，并设置 current_action_id: "create_task"。
3. 预期任务调用会被模拟，且 nextActionId = notify（或 exit）。继续运行，直到退出步骤。

第 1 步出现 status=skipped，表示示例事件与触发器筛选条件不匹配。请修正示例，而不是触发器。

Loops 中不支持的功能

应用内通知、推送通知以及任何其他步骤类型。如果用户提出此类需求，请说明 Loops 暂不支持，并提供最接近的适用循环。不要为了绕过限制而添加操作、边或输入。