pipefy-reports

报告

请阅读 MCP 参考 或 CLI 参考，了解你所使用的接口。仅加载相关参考资料。

管道报告和组织报告：发现、CRUD 和异步导出。

---

通用模式

• 使用 get_pipe_report_columns 和 get_pipe_report_filterable_fields 构建 ReportCardsFilter；对于不常见的输入，使用 introspect_type。
• get_pipe_reports 不会在查询中包含 cardCount（Pipefy 在解析它时可能会报错）。

---

管道报告工具

操作	只读	用途
get_pipe_reports	是	列出某个管道的所有报告。
get_pipe_reports	是	在需要时，通过 report_id 加载一份报告。
get_pipe_report_columns	是	查找报告筛选器可用的列。
get_pipe_report_filterable_fields	是	查找报告中可筛选的字段。
create_pipe_report	否	创建新的管道报告。
update_pipe_report	否	更新报告名称或筛选条件。
delete_pipe_report	否	具有破坏性；请先审查并批准。 如果所选接口提供确认流程，请使用该流程。
export_pipe_report	否	触发异步导出。

组织报告工具

操作	只读	用途
get_organization_reports	是	列出所有组织级报告。
get_organization_report	是	获取单份组织报告的数据。
create_organization_report	否	创建组织级报告。
update_organization_report	否	更新报告配置。
delete_organization_report	否	具有破坏性；请先审查并批准。 如果所选接口提供确认流程，请使用该流程。
export_organization_report	否	触发异步导出。

导出状态和下载

操作	用途
get_pipe_report_export	查询管道报告的导出状态（在执行 export_pipe_report 后）。
get_organization_report_export	查询组织报告的导出状态（在执行 export_organization_report 后）。
export_pipe_audit_logs	导出管道审计日志（与卡片报告导出分开）。

---

步骤 — 导出管道报告

1. 列出可用报告：

   操作：get_pipe_reports pipe_uuid=<PIPE_UUID>（get_pipe 会提供 UUID）。

2. 触发导出：

   操作：export_pipe_report pipe_id=67890 pipe_report_id=123

3. 轮询直至完成：

   操作：get_pipe_report_export export_id=<EXPORT_ID>

   每隔 5–10 秒重复查询，直到 state 为 done（或 failed）。

4. **下载：**通过 HTTPS 使用 done 导出响应中的签名 fileURL。

   该链接会在返回它的读取操作发生 1 小时后过期；在此之前，持有该链接的任何人都可以下载文件。将链接提供给用户时，请告知其将在 1 小时后过期；如需获取新链接，请再次读取导出结果。

---

步骤 — 创建带筛选条件的管道报告

1. 查找可筛选字段：

   操作：get_pipe_report_filterable_fields pipe_uuid=<PIPE_UUID>（get_pipe 会提供 UUID）。

2. 使用 ReportCardsFilter 结构创建报告（而不是顶层的 current_phase 数组）：

   参数：

   create_pipe_report pipe_id=67890 name="Phase subset" filter='{"operator":"and","queries":[{"field":"current_phase","operator":"eq","type":"select","value":"<phase_id>"}]}'
   

   使用步骤 1 中完全一致的 field 字符串。无效结构会在 GraphQL 执行前被拒绝，并提示使用 get_pipe_report_filterable_fields。

---

成功标准

• get_pipe_report_export（或 get_organization_report_export）达到终态 done 或 failed。
• 下载的导出文件包含预期的卡片/报告数据。

故障模式

• 导出卡在 processing： 包含许多卡片的大型管道可能需要几分钟。如果每隔 5 到 10 秒轮询一次，持续一分钟后导出仍处于 processing 状态，请改为每隔 60 秒轮询一次。几分钟后仍处于 processing 状态，则重试触发导出。
• get_pipe_reports 返回的 cardCount 为 null： 这是已知的 Pipefy API 行为；该工具会自动省略此字段。
• 筛选条件在传入 GraphQL 之前被拒绝： 不要传入 {"current_phase":["id"]}；请使用 operator + queries（参见上文第 2 步）。
• 创建后筛选条件不起作用： 使用 get_pipe_report_filterable_fields 确认准确的 field 字符串和 value 格式。

另请参阅

• pipefy-observability — 导出自动化任务历史记录（不同于管道报告）。
• pipefy-introspection — 查看复杂筛选条件的 ReportCardsFilter 输入结构。