pipefy-pipes-and-cards

管道与卡片

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

读取、创建、更新和删除管道、阶段、阶段字段、标签、卡片、附件和字段条件。

---

通用模式

• 字段类型：create_phase_field 使用 API 的 FieldTypeId 枚举值（小写，例如 short_text，而不是 SHORT_TEXT）。工具的输入架构会列出这些值。

• extra_input 会合并额外的 API 键（驼峰命名）；与主要参数重复的键会被忽略。

• 阶段连接仅用于 UI。 创建或重新排序阶段不会设置阶段连接 / allowed_phases。请在 Pipefy UI 中配置边；移动卡片前使用 get_phase_allowed_move_targets。API 无法添加转换边。

• 写入后验证。 创建或更新后，使用匹配的读取工具（get_pipe、get_card、get_phase_fields 等）重新读取，再报告成功。不要仅凭写入响应就认定操作成功。

---

管道操作

操作	只读	用途
get_pipe	是	获取管道元数据，包括阶段和字段。
search_pipes	是	按名称模式搜索。
create_pipe	否	在组织中创建新管道。
update_pipe	否	重命名管道或更改管道设置。
delete_pipe	否	具有破坏性；请先审核并批准。
clone_pipe	否	克隆现有管道。
get_pipe_members	是	列出管道成员。

步骤 — 创建包含阶段的管道

1. 创建管道：

   create_pipe name="Customer Onboarding" organization_id=300123456

2. 设置阶段结构。 create_pipe 已会在键 1、2 和 3 处添加 Inbox、Doing 和 Done。除这三个阶段之外，不要为每个请求的名称都调用一次 create_phase。

   如果管道需要三个或更多阶段，且最后一个阶段是最终阶段，请使用 update_phase 重命名 Inbox、Doing 和 Done。不要为 Done 设置 done，以使其保持为最终阶段。只创建位于第二个阶段和最后一个阶段之间的阶段，索引依次为 2.01、2.02 等。如果管道需要的阶段少于三个，请删除不打算保留的空默认阶段。delete_phase 具有破坏性；请先审核并批准。

   index 是浮点排序键：介于两个现有键之间的值会将阶段插入这两个阶段之间。相同的键没有固定顺序；请使用其他阶段未使用的键。新管道的 Inbox、Doing 和 Done 键分别为 1、2 和 3，0 会使阶段不出现在 get_pipe 的阶段列表中。get_pipe 按升序将每个键作为 phases[].index 返回。在 2 和 3 之间，请使用两位小数（2.01、2.02、……、2.99）：2.10 与 2.1 是相同的浮点数，因此第十个值会与第一个值冲突。index 不会设置阶段连接 / allowed_phases（请在 Pipefy UI 中配置这些连接；移动前使用 get_phase_allowed_move_targets）。

   调用 get_pipe，并确认阶段名称的顺序符合预期。

3. 添加起始表单字段 — 在起始表单阶段调用 create_phase_field。

---

阶段操作

操作	只读	用途
get_pipe	是	从管道响应中读取阶段元数据。
create_phase	否	向管道添加阶段。
update_phase	否	重命名阶段、设置完成标记。update_phase 没有索引字段。若要移动没有卡片的阶段，请先删除，再使用排序键重新创建。
delete_phase	否	具有破坏性；请先审核并批准。
get_phase_allowed_move_targets	是	在调用 move_card_to_phase 之前获取有效的目标阶段（仅限 UI 配置的连接）。
get_phase_cards_count	是	通过 get_phase 获取各阶段的原生卡片数量。
get_phase_cards	是	获取阶段中分页列出的卡片。

---

跨阶段播种 Pipe

使用此工作流在每个工作流阶段（演示、QA 检查清单、混沌 Pipe）中至少放置一张卡片，无需使用 execute_graphql。转换边必须已在 Pipefy UI 中存在。

所需工具

操作	只读
get_pipe	是
get_phase_cards_count	是
create_card	否
get_phase_cards	是
get_phase_allowed_move_targets	是
move_card_to_phase	否

调用 move_card_to_phase 前，请先调用 get_phase_allowed_move_targets。必填的空字段可能会阻止移动。

步骤

1. 加载阶段 ID — get_pipe(pipe_id) → 收集工作流阶段的 phases[].id。对于起始表单提交，create_card 中省略 phase_id。

   get_pipe pipe_id="301234567"

2. 查找空阶段 — 对每个候选 phase_id 调用 get_phase_cards_count。目标是 cards_count 为 0 的阶段（如果起始表单显示为 0，但你怀疑已有卡片，请在创建重复卡片前调用 get_phase_cards）。

   get_phase_cards_count phase_id="341234567"

3. 在空阶段中创建卡片 — 循环调用 create_card 并传入 phase_id。当 fields 非空时，键会通过 get_phase_fields(phase_id) 和 get_start_form_fields(pipe_id) 进行筛选。

   create_card pipe_id="301234567" phase_id="341234567" title="Seeded" fields={}
   

4. 验证清单 — 调用 get_phase_cards(phase_id, first=50)，确认预期的卡片 ID/标题。

5. 移动前 — 对卡片当前所在阶段调用 get_phase_allowed_move_targets，然后仅将卡片移至 allowed_phases[].id 中的阶段，调用 move_card_to_phase。

   get_phase_allowed_move_targets phase_id="<current_phase_id>"

成功标准

• 每个目标阶段的 cards_count >= 1（或 get_phase_cards 列出了已播种的卡片）。
• 移动操作仅使用 allowed_phases 返回的阶段。

失败情况

• allowed_phases 为空： 在 Pipefy UI 中配置 阶段 → 连接；API 无法添加边。
• 计数意外为空： 使用 get_phase_cards 列出卡片，再创建新卡片以避免重复。

---

阶段字段操作

操作	只读	用途
get_phase_fields	是	列出阶段上的字段。
get_start_form_fields	是	列出用于创建卡片的起始表单字段。
create_phase_field	否	向阶段添加字段。
update_phase_field	否	重命名、重新排序、更改必填标记。
delete_phase_field	否	具有破坏性；请先审核并批准。

字段类型： field_type 接受 FieldTypeId 值，可在 create_phase_field 输入架构中查看（或使用 introspect_type type_name="FieldTypeId"）。对于选择、单选和清单类型，请设置 options。connector 字段还需要 extra_input.connectedRepoId：Pipe ID 或表格 ID。

---

卡片操作

操作	只读	用途
get_card	是	标题、阶段、管道、可选字段。不返回标签或负责人。
get_cards	是	按管道分页列出卡片。
get_records	是	按日期、阶段、标签、负责人、创建者、标题或自定义字段列出、计数和筛选管道中的卡片；返回准确的 totalCount。
find_cards	是	按单个字段值筛选。
create_card	否	默认：开始表单。可选的 phase_id 会指定创建卡片的阶段。
fill_card_phase_fields	否	填写阶段字段；仅筛选可编辑的 ID。
update_card	否	更新标题、负责人、标签、截止日期或字段。对于列表类型的字段（连接、附件、清单），优先使用带有 operation ADD/REMOVE 的 field_updates。管道标签和负责人是卡片属性（label_ids / assignee_ids，全部替换），而非字段 — 请参阅标签操作。如果设置了 field_updates，属性参数会被丢弃。对于连接字段，请发送相关的卡片 ID。
update_card_field	否	单字段 updateCardField；列表类型字段会全部替换。对于连接字段，值应为相关的卡片 ID（而非显示标题）。不要根据 get_card 的 value（仅包含标题）重建；请通过 get_card_relations 读取 ID。对于字段，优先使用 update_card + ADD/REMOVE。管道标签应使用 label_ids，而非此工具。
move_card_to_phase	否	请先调用 get_phase_allowed_move_targets；必填字段为空时可能会阻止移动。
delete_card	否	具有破坏性；请先审核并批准。
add_card_comment	否	向卡片添加文本评论。
update_comment	否	更新现有卡片评论。
delete_comment	否	具有破坏性；请先审核并批准。

步骤 — 创建卡片

1. 获取开始表单字段（必需 — 切勿跳过）：

   get_start_form_fields pipe_id=301234567

2. 使用字段创建卡片：

   create_card pipe_id=301234567 title="My Card" fields={"field_slug":"value"}
   

3. 报告结果，包含卡片 ID 和链接：https://app.pipefy.com/open-cards/<CARD_ID>

计数和筛选卡片

get_records 可通过一次调用回答“有多少”：设置 first=1 并读取 records.totalCount，而非页面长度。按组（每位负责人、每个标签）计数时，每组调用一次。 在 where 和 order_by 中，field 必须是来自 get_phase_fields 的自定义字段 UUID（对于开始表单字段，请调用 get_phase_fields，并将 phase_id 设为 get_pipe 的 startFormPhaseId）；slug 会被拒绝。 日期使用 ISO 8601 格式：CREATED_AT 和 FINISHED_AT 等日期时间属性需要带时区偏移，而 date 自定义字段应使用不带时间的日期（"2026-07-03"），因为非 UTC 偏移会导致 eq 返回 0，并使 between 的时间范围发生偏移。between 使用 {"min": ..., "max": ...}。 like 和 ilike 都会忽略大小写，并按任意顺序将值中的每个词与子字符串匹配：% 和 _ 是字面字符，因此应使用 ilike: "acme"，而非 "%acme%"。若要按 ID 查找卡片，请使用 where={"attribute": "ID", "eq": "<id>"}。 使用 where 或 search_term 时，分页最多返回 10,000 张卡片。 若要列出所有卡片，请将 after 设为上一页的 pageInfo.endCursor 进行分页，直到 hasNextPage 为 false，并确认行数总和与 totalCount 相符。

get_records pipe_id=67890 where={"attribute":"FINISHED_AT","between":{"min":"2026-01-01T00:00:00-03:00","max":"2026-01-31T23:59:59-03:00"}}

get_cards 的分页

get_cards pipe_id=301234567 first=50 after=<endCursor>

从响应中读取 pageInfo.hasNextPage 和 pageInfo.endCursor；将 after=<endCursor> 设为下一页的参数。

---

标签操作

操作	只读	用途
get_pipe	是	从 pipe 响应的 labels 中列出 pipe 标签。
create_label	否	创建带颜色的标签。
update_label	否	重命名或更改颜色。
delete_label	否	具有破坏性；请先审查并批准。

这些工具用于管理 pipe 上的标签定义。要将 pipe 标签应用到卡片上，请使用 update_card(label_ids=[...])，它会替换卡片的整个标签列表：请包含所有应保留的 ID；不要只发送新标签的 ID。get_card 不会返回标签——请通过 execute_graphql（card(id: ...) { labels { id } }）读取当前 ID，合并后再写入。带有 operation ADD/REMOVE 的 field_updates 适用于列表类型的字段，不适用于卡片属性标签。当用户希望自动应用标签（“超过截止日期时将其标记为逾期”）时，请停止并阅读 pipefy-automations（应用标签没有对应的自动化操作）：没有任何自动化操作可以实现此功能，而对一组卡片调用 update_card 会让 Agent 成为运行时，而不是让流程本身执行。

---

字段条件操作

操作	用途
get_field_conditions	列出某个阶段上的所有字段条件。
get_field_condition	按 ID 加载一个字段条件。
create_field_condition	创建显示/隐藏规则。报告成功前，请确认规则位于请求的阶段上。
update_field_condition	更新条件操作或规则。
delete_field_condition	具有破坏性；请先审查并批准。

不要隐藏必填字段；请先清除 required。

---

成功标准

• Pipe 和阶段在 Pipefy UI 中可见。
• get_pipe 返回新 pipe ID 和阶段。
• 通过 create_card 创建的卡片会显示在 pipe 的第一个阶段中。

失败情况

• **create_field_condition 因阶段缺失或错误而失败：**请删除返回的条件后再重新创建；不要在同一个请求阶段上盲目重试创建。
• **create_card 因缺少必填字段而失败：**请先调用 get_start_form_fields，以查找必填的 field_id 值。
• **create_card / 写入操作报告失败（消息为空或不明确）：**不要盲目重试。任何重试前，请重新读取 get_cards / get_phase_cards_count（或 pipe 的 cards_count）——参见 pipefy-api-fallback（写入失败状态不明确时，重试前先重新读取）。
• 更新连接器字段后连接缺失：update_card_field 会整体替换字段值——写入一个关联卡片 ID 会丢弃其余 ID（附件、检查清单等其他列表字段也同样会整体替换）。优先使用带有 operation ADD/REMOVE 和关联卡片 ID 的 update_card。不要根据 get_card 的 value（仅包含显示标题）重建整个列表；若要执行 REMOVE 或安全地完整重写，请通过 get_card_relations（或 GraphQL array_value）获取当前关联卡片 ID。对于通过 pipe 关系（而非连接器字段）进行的写入，请使用 create_card_relation / delete_card_relation——参见 pipefy-relations。Pipe 标签和受分配人不是字段：请使用 update_card(label_ids=) / assignee_ids（整体替换）；field_updates ADD 无法处理它们。
• create_phase_field 拒绝类型（Field type not found with id: ...）：请使用小写的 FieldTypeId 值（short_text，而非 SHORT_TEXT）。introspect_type type_name="FieldTypeId" 会列出这些值。

另请参阅

• pipefy-relations — 在工作流之间关联 pipe 和卡片。
• pipefy-automations — 为 pipe 添加自动化规则。
• pipefy-introspection — 查找字段类型和 mutation 签名。
• docs/mcp/tools/identifiers.md#field-references-slug-vs-internal_id — 各工具/参数应使用 slug、internal_id、uuid 还是数字 ID 的权威映射（例如，update_card_field 使用字段 slug）。