pipefy-automations

自动化

仅阅读与你当前使用界面对应的参考文档：MCP 或 CLI。以下工作流使用共享的操作名称和参数。

传统自动化（if/then 规则）、AI 自动化（由提示词驱动）、任务自动化和模拟。

如需了解 AI Agent（带有行为的对话式 Agent），请参阅 pipefy-ai-agents。

---

传统自动化（规则引擎）

操作	用途
get_automations	列出规则及其 event_id、event_params、condition、actionEnabled 和 disabledReason。空条件表达式是 API 占位符，不是启用中的筛选条件。每页最多包含 50 条规则；在得出规则或筛选条件不存在的结论前，请使用 after 继续翻页。
get_automation	获取单条自动化的完整规则配置——返回 event_params 和 action_params（包括 AI 规则的 aiParams）。
create_automation	创建 if/then 规则。active 默认为 true。提供一等类型化 condition（参见条件）；其他字段通过 extra_input 设置。
update_automation	更新规则：提供一等类型化 condition（参见条件）和/或 extra_input。
delete_automation	删除操作不可撤销。
simulate_automation	仅限 AI 的试运行（generate_with_ai 操作）。
get_automation_events	获取可用的触发事件。
get_automation_event_attributes	获取官方的 field_map.value 事件属性令牌。
get_automation_actions	获取管道中可用的操作类型。
create_send_task_automation	创建发送任务规则的快捷方式。

自动化的日志、用量和任务导出功能位于 pipefy-observability 中（get_automation_logs、get_automation_logs_by_repo、get_automations_usage、export_automation_jobs 及相关工具）。

---

AI 自动化（由提示词驱动）

征得同意： 仅当用户明确要求使用 AI 时，才创建或建议 AI 自动化。如果这看起来有用，但用户并未提出要求，请先询问——切勿在用户未要求时引入 AI 自动化。

操作	用途
get_ai_automations	从管道的混合列表中列出 generate_with_ai 规则。每页最多包含 50 条混合规则；在得出 AI 规则不存在的结论前，请使用 after 继续翻页。
get_ai_automation	获取完整配置，包括提示词、字段和条件。
create_ai_automation	创建由提示词驱动的自动化（要求管道已启用 AI）。
update_ai_automation	更改名称、active、提示词、field_ids 或 condition。
delete_ai_automation	删除操作不可撤销。
validate_ai_automation_prompt	预检。 返回 {valid, problems, warnings, field_map}——还会检测提示词中的 %{id} 与 field_ids 是否存在交集。

---

步骤 — 创建 AI 自动化

1. 查找提示词中引用的所有字段的 internal_id：

   get_phase_fields phase_id="<phase_id>"
   

2. 构建提示词，使用 %{<internal_id>} 引用。Pipefy 会静默拒绝未引用字段的提示词（返回 "Input parameters are required."）。

   重要： 必须使用 %{...} 包装形式，以及来自你自己的管道的数字型字段 internal_id——以下示例中的具体数字（例如 900000101）都是虚构的占位符。请通过 get_phase_fields / get_start_form_fields 查找真实 ID；不要照抄文档中的示例数字。

3. 验证提示词：

   validate_ai_automation_prompt pipe_id=67890 prompt="Summarize %{900000102} into the summary field." field_ids=["900000101"]
   

   返回 valid:true|false、problems、warnings、field_map。一次只读调用即可捕获错误，而不必经历 2–3 次失败的变更往返。

4. 创建自动化（仅当 valid:true 时）：使用选定的事件 ID、管道 ID、提示词、输出字段 ID 和名称。MCP 将这些参数作为 event_id、pipe_id、prompt、field_ids 和 name 接受；SDK 则接受包含这些内容的 CreateAiAutomationInput。调用语法请参阅当前使用界面的参考文档。

---

步骤 — 创建传统自动化

1. 发现管道的事件：get_automation_events pipe_id=67890。
2. 发现管道的操作：get_automation_actions pipe_id=67890。（务必先发现；切勿猜测 trigger_id / action_id。）
3. 检查事件×操作兼容性：如果所选 event_id 出现在该操作的 eventsBlacklist 中（来自 get_automation_actions），则这一组合无效。不要依据 triggerEvents 进行判断，它列出的是其他内容。请参阅事件×操作兼容性。
4. 使用发现的 ID 构建规则，并调用 create_automation。
5. 通过读取 get_automation 的结果进行验证。

---

条件 — 通过字段测试设置规则门槛

create_automation 和 update_automation 接受一流的 condition。不要根据 GraphQL 自省猜测其结构——实际结构如下：

{
  "expressions": [
    {"field_address": "900000101", "operation": "equals", "value": "Done", "structure_id": 0}
  ],
  "expressions_structure": [[0]]
}

• field_address 是字段的 internal_id（来自 get_start_form_fields / get_phase_fields 的数字），不是 slug。对于关联卡片的字段，使用 <connectorFieldId>.<targetFieldId>。
• operation（软枚举——任何值都会直接传递，API 会进行验证）：equals、not_equals、present、blank、string_contains、string_not_contains、number_greater_than、number_less_than、date_is_today、date_is_yesterday、date_in_current_week、date_in_last_week、date_in_current_month、date_in_last_month、date_in_current_year、date_in_last_year、date_is、date_is_after、date_is_before。对于 present / blank，省略 value。
• expressions_structure 按 structure_id（而不是位置）对表达式分组。同一个内层数组中的表达式进行 AND 运算，内层数组之间进行 OR 运算：[[0, 1], [2]] 表示 (expr0 AND expr1) OR expr2，[[0, 1]] 表示 expr0 AND expr1，而 [[0], [1]] 表示 expr0 OR expr1。为每个表达式设置单独的 structure_id。两个表达式共用同一个 ID，并以 [[0], [0]] 发送时，保存后 expressions 会变为空，而 expressions_structure 仍为 [[0], [0]]。这条规则不会匹配任何卡片。
• API 会丢弃无法使用的内容，且不会返回错误：与任何 structure_id 都不匹配的数字、空内层数组、structure_id 未列出的表达式，以及缺少 field_address 或 operation 的表达式。从 AND 组中丢弃一个表达式会让该组更容易满足，因此规则可能匹配更多卡片（[[0, 1]] 中有一个表达式被丢弃后，会保存为 [[0]]）。丢弃 OR 组中唯一的表达式会移除该组，因此规则匹配的卡片会更少（[[0], [1]] 中有一个表达式被丢弃后，会保存为 [[0]]）。写入后，请使用 get_automation 重新读取规则。空的 expressions_structure 会匹配所有卡片。同一个数字出现两次时会报错 is invalid。

省略 condition，即可让传统规则不带条件（不会注入默认值）。condition 参数的优先级高于 extra_input 中的任何 condition。

步骤 — 使用动态值更新卡片字段

当用户希望通过 if/then 规则在触发卡片上写入或复制值时使用（例如，在触发 card_created 时设置日期时间）。这需要使用 create_automation，并设置 action_id: update_card_field 和 extra_input.action_params.field_map——而不是一次性 update_card_field 操作（该工具使用字段 slug 进行一次性卡片编辑）。

1. 查找字段 internal_id（仅数字——fieldId 中绝不能使用 slug）：

   get_start_form_fields pipe_id=67890
   get_phase_fields phase_id="<phase_id>"
   

2. 查找触发器、操作和事件属性令牌：

   get_automation_events pipe_id=67890
   get_automation_actions pipe_id=67890
   get_automation_event_attributes
   

   对于 update_card_field，acceptedParameters 不包含 field_map；请使用下方的载荷结构（参见 docs/mcp/tools/automations-and-ai.md）。写入执行时间时，优先使用 get_automation_event_attributes 返回的 value_token。

3. 创建为禁用状态（active=false），以便在验证期间规则不会触发：

   create_automation pipe_id=67890 name="Stamp execution time on new cards" trigger_id=card_created action_id=update_card_field active=false extra_input={"action_params":{"card_id":"%{id}","field_map":[{"fieldId":"<destination_internal_id>","inputMode":"copy_from","value":"%{automation_event_execution_datetime}"}],"fields_map_order":["<destination_internal_id>"]}}
   

   当 inputMode 为 copy_from 时，常见的 value 令牌包括：%{id}（也用于 card_id）、%{created_at}、%{automation_event_execution_datetime}、%{<other_internal_id>}（用于复制另一个字段）。

4. 验证已持久化的配置：

   get_automation automation_id=<id>
   

   确认 action_params.field_map 已往返保留。

5. 确认无误后启用：

   update_automation automation_id=<id> extra_input={"active":true}
   

---

步骤 — 模拟传统自动化

目前，simulate_automation 仅支持 AI（只接受 generate_with_ai action_id）。对于非 AI 规则，请在触发器触发后查看 get_automation_logs。

1. 先读取一条可正常工作的规则：get_automation automation_id=<id>——原样复制 event_params 和 action_params。

2. 使用真实的示例卡片进行模拟：

   simulate_automation pipe_id=67890 action_id=generate_with_ai sample_card_id=456
   

3. 读取即时结果。结果可能包含 simulation_id 和 status:"processing"，且 simulationResult 为 null。保留该 ID，并通过 execute_graphql 再次读取模拟结果；再次调用 simulate_automation 会启动新的模拟：

   query { automationSimulation(simulationId: "<simulation_id>") { status simulationResult details { errorType message } } }
   

   短暂等待后重新读取，直到 status 不再是 processing。如果读取几次后仍处于处理中，请报告结果仍在等待处理，并附上该 ID。

---

传统自动化预检

事件×操作兼容性

此约束采用拒绝列表。若某个 event_id 出现在该操作的 eventsBlacklist（get_automation_actions）中，则该组合无效；这与该事件的 actionsBlacklist（get_automation_events）中出现该 action_id 是一回事：目录中每个条目的两个列表都一致，因此任一列表都可用于判断。

triggerEvents 不是该列表，不能将其用作限制条件。它反映构建器优先提供哪些组合，因此依据它进行成员资格检查会拒绝拒绝列表允许的组合：field_updated + move_single_card 不在 triggerEvents 中，但该规则可以创建并移动卡片。目录中的三种情况会导致此类检查失效。send_a_task 和 send_email_template 返回 triggerEvents: []，但拒绝列表允许它们用于 10 个事件中的 7 个和 9 个；schedule_create_card 和 move_multiple_cards 会在 triggerEvents 中列出各自的 eventsBlacklist 条目；而每个 triggerEvents 非空的操作，在拒绝列表中都允许用于其列表之外的事件。

create_automation 会执行拒绝列表检查。若组合在拒绝列表中，它会拒绝该组合，并返回一条未翻译的错误；其中可读部分是键 event_action_blacklist，且不会写入任何内容。将该键理解为“此事件不能触发此操作”，然后选择其他组合。

update_automation 不会执行此检查。将已存储规则的 event_id 更新为其操作的 eventsBlacklist 中的事件会成功并持久化：以 card_created + move_single_card 创建的规则，接受更新为 scheduler + move_single_card，而创建时会拒绝该组合。因此，规则更新后可能包含在拒绝列表中的组合；更新前检查拒绝列表是调用方的责任，而非 API 的责任。

目录中的拼写不等于输入拼写

get_automation_events 会以 snake_case 报告 acceptedParameters；AutomationEventParamsInput 中除一个参数外，其余参数均以 camelCase 定义。发送目录中的拼写会失败，并报错 Field is not defined on AutomationEventParamsInput。完整映射如下：

参数	目录中的拼写	要发送的 event_params 键
触发字段	trigger_field_ids	triggerFieldIds
SLA 类型	kind_of_sla	kindOfSla，值首字母大写：Expired、Late、Overdue
来源阶段	from_phase_id	fromPhaseId
当前阶段	in_phase_id	inPhaseId
上游规则	trigger_automation_id	triggerAutomationId
目标阶段	to_phase_id	to_phase_id，这是唯一保留 snake_case 的键

周期性规则的计划安排不在 event_params 中：使用 scheduler_frequency（hourly、daily、weekly、monthly）以及 schedulerCron。schedulerCron 是由五个必填字符串（minute、hour、dayOfMonth、month、dayOfWeek）组成的对象，而不是 cron 字符串。

应用标签没有对应的自动化操作

明确限制：目录中没有任何操作可以为卡片应用标签。缺少的是操作，而不是触发器：sla_based 在事件目录中，因此“卡片逾期时”完全可以作为触发器，只是没有可关联的操作。get_automation_actions(pipe_id) 是查询特定管道提供哪些操作的动态事实来源；规划规则前请先读取它，不要假定存在应用标签的操作。

遇到这种需求时：

1. 将需求交给产品处理，而不是交给脚本。 标签规则属于客户的流程，应当无需任何人驱动也能持续触发。API 无法创建这类规则，因此应给用户一个手动步骤：在 Pipefy 中配置规则，并在那里确认界面针对该触发器提供哪些选项。请在交给用户的计划或摘要中说明这一步，就像说明电子邮件模板的配置步骤一样。

2. 适用时，提供确实存在的规则。 update_card_field 接受 sla_based，因此如今可以通过 create_automation 创建“卡片逾期时，为卡片上的某个字段写入值”的规则。状态或标记字段可以传递与标签相同的信号，同时让规则留在流程中。请先通过 get_start_form_fields / get_phase_fields 查找合适的目标字段：许多管道没有名为 Status 的字段，而且自动化需要真实的 internal_id。应提出这个方案，而不是强行采用；用户可能明确需要标签。

   sla_based 的参数要通过 event_params.kindOfSla 传入，使用 camelCase，尽管 get_automation_events 报告的拼写是 kind_of_sla。值首字母大写：Expired、Late、Overdue。发送目录中的拼写会失败，并报错“Field is not defined on AutomationEventParamsInput”。请使用下方的 field_map 配方构造操作，并包含 inputMode。

3. update_card(label_ids=[...]) 是一次性修正，不是自动化。它会替换卡片的整个标签列表：请包含所有应该保留的标签 ID；不要只发送新增标签。每次都必须有东西来运行此调用。会话结束后，不会留下任何持久化的流程行为。仅当用户指出具体卡片需要修正时才使用，并明确说明这一点。不要对一组卡片调用它来代替规则，也不要按计划循环调用：这样会让 Agent 成为运行机制，而不是流程。

4. 标签的增删改查是另一回事。create_label、update_label 和 delete_label 用于管理管道上的标签定义（名称、颜色）。它们都不会为卡片应用标签，也都不是自动化操作。

5. **不要将 AI 自动化或 Agent 行为作为替代方案。**有些组织禁止在其流程中使用 AI，且此处适用同意规则：仅当用户明确提出要求时，才建议使用 AI。

field_map 目标 fieldId

执行 create_automation 时，如果存在 extra_input.action_params.field_map，SDK 会将每个 fieldId 与操作管道（action_repo_id，默认为 pipe_id）上的数字 internal_id 值进行核对。格式为 slug 的 fieldId 和未知的数字 ID 会在 GraphQL 调用前导致失败，并指出有问题的 ID。恢复方法：调用 get_start_form_fields / get_phase_fields，使用 internal_id，不要使用 slug。

阶段转换（move_single_card）

对于触发器为 card_moved 的 move_single_card 操作，仅 create_automation 会验证目标阶段是否可通过 cards_can_be_moved_to_phases 从源阶段到达（使用与 move_card_to_phase 相同的只读数据）。update_automation 不会执行此检查。

如果验证失败，请查看错误消息，其中会列出允许的目标阶段，并提示该转换仅能通过 UI 配置。

恢复方法：读取 error.message 中的允许阶段，或在源阶段上调用 get_phase_allowed_move_targets(phase_id=<source_phase_id>)，其中源阶段来自 event_params.to_phase_id，然后使用允许的目标阶段 ID 重新调用 create_automation。

---

通知意图区分

根据用户表达选择正确的通知工具：

用户提示词	工具	原因
“通知”、“任务”、“提醒某人验证”	create_send_task_automation	内置功能：处理 event_id、task_title、recipients、可选的 event_params 和 condition。
“发送电子邮件”、“回复客户”	send_email_with_template / send_inbox_email（pipefy-members-email-webhooks）	电子邮件功能，不属于自动化。
“webhook”、“调用外部服务”	create_webhook（pipefy-members-email-webhooks）	在卡片事件发生时执行 HTTP 回调。
“自动化”、“if/then 规则”	create_automation	通用规则引擎。

如果 create_send_task_automation 是合适的工具，请勿使用 create_automation 手动构建 action_params.taskParams。

发送电子邮件的自动化依赖于已存在的模板：模板的创建、编辑和删除都没有 API 路径，只能通过 Pipefy UI 完成。如果流程需要新模板或修改模板，请在提供给用户的计划或摘要中说明这一步需要手动通过 UI 完成。

---

Agent 与人工介入模式

结合 AI 自动化和任务自动化，让 AI 处理日常工作，由人工验证影响重大的决策。这是目录中效益最高的模式。

示例流程：

1. create_ai_automation：卡片进入“分析”阶段时，AI 自动填写分类和风险字段。
2. create_send_task_automation：AI 填写的字段更新时，向经理发送任务：“验证卡片 [标题] 上的分类”。
3. create_automation 或 create_field_condition：经理标记“已批准”时，将卡片移至下一阶段。

此模式适用于审批、财务决策、内容发布，以及任何错误会造成现实后果的步骤。另请参阅：pipefy-process-design 编排模式。

---

成功标准

• get_automation 返回包含正确触发器和操作的新规则。
• 创建 AI 自动化前，validate_ai_automation_prompt 返回 valid:true。
• simulate_automation（AI 规则）返回模拟 ID；后续读取 automationSimulation 会返回最终的 simulationResult，或者将结果报告为待处理状态并附上 ID。

失败模式

自动化未触发／日志为空

1. get_automation — 重新读取规则及其 condition。
2. 根据拒绝列表检查事件与操作的配对（参见事件×操作兼容性）。创建时会拒绝黑名单中的配对，但更新时不会，因此创建后经过修改的规则可能包含此类配对。然后确认卡片上确实发生了该事件。
3. 日志为空并不能证明平台发生故障。规则可能处于非活动状态（active: false）、操作已关闭（actionEnabled: false，并带有 disabledReason），或者只是尚未触发。
4. field_map 中的 fieldId 无效时，可能会失败且不会更新卡片（见下文）。
5. 在断定“服务不可用”或归咎于平台之前，请先查看工具错误载荷以及必填字段／阶段转换提示。

其他故障模式

• simulate_automation 仅供 AI 使用。 只接受 generate_with_ai action_id。对于传统规则，请在规则触发后使用 get_automation_logs。
• 模拟结果为异步。 processing 响应表示尚无最终结果。保留 simulation_id，并通过 execute_graphql 使用 automationSimulation 查询读取结果（参见 步骤 — 模拟）。get_automation_logs 需要真实的自动化 ID；再次调用 simulate_automation 会启动新的模拟。
• validate_ai_automation_prompt 返回 valid:false。 查看 problems（按字段列出）和 warnings。最常见的原因是提示词缺少 %{internal_id} 引用，或 field_ids 与提示词中的 %{id} 标记重叠。
• create_automation 的循环检测。 同一管道中的 card_created + create_card 会被拒绝，并返回 "This automation can't be created! It would result in an endless card creation cycle."。请使用不同的触发条件、将目标设为其他管道，或改用 update_card。
• create_automation 因事件或操作未知而失败。 请始终先运行 get_automation_events + get_automation_actions；不要猜测 ID。
• 计划创建一条应用标签的规则。 目录中没有此类操作。该触发条件存在：sla_based 可用，因此缺少的只是标签操作。在提供其他方案前，请参阅 应用标签没有对应的自动化操作。
• move_single_card 出现阶段转换错误。 只有 create_automation 会预先检查转换。请读取错误文本中允许的阶段 ID，或调用 get_phase_allowed_move_targets，然后重新指定允许的目标。转换规则只能在 UI 中编辑。
• 跨管道出现 PERMISSION_DENIED。 SA 必须同时是源管道和目标管道的成员，才能使用 create_connected_card / 跨管道的 create_card。恢复方法：get_pipe_members + invite_members。
• get_automation_logs_by_repo 返回空结果。 该管道没有传统自动化的执行记录；这不是错误。AI Agent 的执行记录是单独的（参见 get_ai_agent_logs）。
• create_send_task_automation 在 active=true 时会立即触发。 如果希望在规则开始触发前完成配置，请先传入 active=false。2026-04-16 发生的孤立任务事件就是一个警示案例。
• update_automation 的 API 不一致。 create_automation 接受顶层 active 参数；update_automation 则要求使用 extra_input={"active": false}。切换现有规则的状态时，请通过 extra_input 传入 active。
• action_repo_id 的含义。 对于跨管道操作（create_connected_card、在其他管道中执行 create_card），它指的是目标管道，而非源管道。
• 模拟会复用真实规则参数。 模拟前，请调用 get_automation 读取有效规则的 event_params 和 action_params，并原样传入。不要手动编写参数。
• field_map 在 fieldId 中使用了 slug。 预检查会在调用 GraphQL 前拒绝非数字 fieldId；slug（例如 due_date）之前会导致 INTERNAL_SERVER_ERROR。恢复方法：调用 get_start_form_fields / get_phase_fields，然后使用 internal_id。
• field_map 中的 fieldId 未知。 如果目标字段不属于操作管道，create_automation 预检查会因该字段 ID 而失败。请在 action_repo_id 对应的管道中重新查找 ID（跨管道操作时，不要只在触发管道中查找）。
• 规则中使用了 update_card_field 操作。 该工具按 slug 更新单张卡片；自动化需要使用 create_automation + 带数字 fieldId 的 field_map。
• 缺少或错误的 card_id。 将 action_params.card_id 设为 "%{id}"，以指向触发该规则的卡片；值为空或错误会导致无法按预期更新。
• field_map.value 中的标记拼写错误。 %{…} 模板中的拼写错误会导致字段在运行时保持不变。请对照 自动化事件属性 以及通过 get_automation 获取的有效规则。
• 规则已运行，但字段未变更。 请检查 get_automation_logs / get_automation_logs_by_repo 中是否有执行错误；无效的 fieldId 可能会静默失败（卡片不会更新）。

另请参阅

• pipefy-building — 用于构建需求的意图 → 领域技能路由器。
• pipefy-ai-agents — 具有行为的对话式 Agent（不同于 AI 自动化）。
• pipefy-observability — 执行日志和使用统计信息。
• pipefy-introspection — 通过原始架构发现触发器和操作类型。
• pipefy-process-design — 编排模式（Agent 式 + 人工验证）。
• docs/mcp/tools/identifiers.md#field-references-slug-vs-internal_id — 权威对照表，说明哪些工具/参数需要 slug、internal_id、uuid 或数字 id（field_address 和 field_map[].fieldId 需要 internal_id）。