pipefy-relations

连接与关系

MCP 客户端：阅读 references/mcp.md。CLI 用户：阅读 references/cli.md。以下示例介绍通用操作参数。

跨工作流关联流程和卡片。

---

核心概念

• 流程关系定义流程之间的父子结构（谁与谁连接、约束、自动填充）。在流程上使用 get_pipe_relations 可列出关系 ID 和元数据。
• 卡片关系通过现有流程关系连接单张卡片：传入 source_id = 流程关系的 ID（来自 get_pipe_relations）。默认的 sourceType 为 PipeRelation；当 API 要求基于字段的链接时，使用 extra_input（例如 sourceType: Field）——参见 CreateCardRelationInput 上的 introspect_type。
• GraphQL 中的 表关系按表关系 ID 加载，而不是按数据库表 ID 加载：get_table_relations 接收这些 ID 的非空列表。
• 连接器字段是卡片字段（连接类型），并非用于写入的流程关系。优先使用 update_card + field_updates，并将 operation 设为 ADD/REMOVE（相关的卡片 ID；如果字段连接到数据库表，则使用记录 ID）。任何其他流程或表中的 ID 都会被丢弃，且不会报错：ADD 会保留现有链接；而 update_card_field 如果没有有效 ID，则会清除全部链接。写入后读取链接以确认结果。update_card_field 会替换全部 ID 列表；get_card 的 value 仅包含显示标题——不要据此重新构建 ID 列表。此技能的 get_card_relations 仍会读取连接器字段链接（包含卡片 ID）。create_card_relation / delete_card_relation 通过流程关系写入链接，且采用增量方式——选择与链接类型匹配的操作。delete_card_relation 只会移除通过流程关系创建的链接，不会移除连接器字段链接，并且需要有权编辑父卡片。

---

工具

操作	只读	用途
get_pipe_relations	是	列出某个流程的流程间关系。
create_pipe_relation	否	创建新的流程间关系。
update_pipe_relation	否	更改关系配置（自动填充、约束）。传入每个约束标志；参见失败模式。
delete_pipe_relation	否	具有破坏性；请先审核并批准。
get_table_relations	是	按关系 ID 加载表关系。
get_card_relations	是	列出某张卡片上的所有卡片间关系。
create_card_relation	否	通过现有流程关系连接两张卡片。
delete_card_relation	否	具有破坏性；请先审核并批准。

---

步骤 — 通过现有流程关系连接两张卡片

1. 获取流程关系 ID：

   操作：get_pipe_relations(pipe_id=67890)

   记下关系上的 id 字段（而不是流程 ID）。

2. 创建卡片关系：

   操作：create_card_relation(parent_id=<PARENT_CARD_ID>, child_id=<CHILD_CARD_ID>, source_id=<PIPE_RELATION_ID>)

3. 验证：

   操作：get_card_relations(card_id=<CHILD_CARD_ID>)

---

步骤 — 创建新的流程关系

1. 在两个流程之间创建关系：

   操作：create_pipe_relation(parent_id=111, child_id=222, name="Support Escalation")

2. 使用此关系 — 现在可以使用 create_card_relation 将父流程中的卡片与子流程中的卡片关联。

---

成功标准

• get_pipe_relations 返回包含两个流程 ID 的新关系。
• create_card_relation 执行后，get_card_relations 会显示已关联的卡片 ID。

故障模式

• create_card_relation 失败并提示 "relation not found"： source_id 必须是管道关系 ID（来自 get_pipe_relations），而不是管道 ID。这是两个不同的值。
• 表关系返回空结果： get_table_relations 需要表关系 ID，而不是表 ID。请从表的连接配置中获取表关系 ID。
• update_pipe_relation 会重置你未传入的标志。 Pipefy 要求每次更新都传入全部八个约束标志（allChildrenMustBeDoneToFinishParent、allChildrenMustBeDoneToMoveParent、autoFillFieldEnabled、canConnectExistingItems、canConnectMultipleItems、canCreateNewItems、childMustExistToFinishParent、childMustExistToMoveParent）。未传入的标志会使用默认值：三个 canConnect…/canCreateNewItems 标志为 true，其余五个为 false。因此，即使只是重命名，也会更改关系的约束。请使用 get_pipe_relations 读取关系，并传入每个标志的当前值。若要保留自动填充映射，请省略 ownFieldMaps：传入它会替换整个列表。
• 删除： 移除关系前，请展示受影响的关系并获得批准。

另请参阅

• pipefy-pipes-and-cards — 在关联管道和卡片之前先创建它们；连接器字段更新和 update_card_field 的全量替换说明也在其中。
• docs/mcp/tools/identifiers.md — 了解字段和关系工具的参数应使用 slug 还是数字 ID。
• pipefy-introspection — 当需要非标准的 sourceType 时，用于发现 CreateCardRelationInput。