pipefy-attachments

附件

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

每次将一个文件上传到卡片或表记录附件字段。上传通过 Pipefy 的预签名 URL 流程完成（请求 URL、S3 PUT，然后更新字段）。

---

适用场景

• 用户说“将此文件附加到卡片 X”或“上传到记录 Y 的 documents 字段”。
• 根据文件字节的实际位置选择来源。请遵循所选界面的来源规则。

以下情况不要使用此技能：

• 读取或列出现有附件。此技能范围内没有列表或下载工具。卡片和表记录可通过常规卡片/记录获取工具访问其附件。
• 批量上传。每次调用上传一个文件；由 Agent 层进行迭代。

前提条件

• 一个 Pipefy organization_id。可通过 get_organization 或 get_pipe 查找。
• 一个目标 card_id 或 table_record_id。
• 附件字段的 slug（类似 document_upload 的可读 ID，而不是字段的 UUID）。可通过卡片或表记录获取工具查找。
• 恰好一个可由所选上传界面访问的文件来源。

所需工具

操作	只读
upload_attachment_to_card	否
upload_attachment_to_table_record	否
create_attachment_presigned_url	否

步骤

将本地文件上传到卡片

如果省略 file_name，系统会根据来源文件名推断，因此调用者通常只需传入四个 ID 和来源。

操作参数：

upload_attachment_to_card(organization_id=42, card_id=1234, field_id=document_upload, file_path=~/report.pdf)

从 URL 上传

upload_attachment_to_card(organization_id=42, card_id=1234, field_id=document_upload, file_url=https://example.com/report.pdf)

如果 URL 路径中没有文件名（例如 .../download?id=1），请显式传入 file_name，以便 Pipefy 使用真实名称存储文件。

将本地文件上传到表记录

操作参数：

upload_attachment_to_table_record(organization_id=42, table_record_id=tr-555, field_id=document_upload, file_path=/tmp/export.csv)

覆盖文件名

如需使用不同于来源文件名的名称存储附件，请显式传入 file_name。显式名称优先于推断出的文件名。

upload_attachment_to_card(..., file_url=https://example.com/abc123.pdf, file_name=Invoice-2026.pdf)

使用预签名握手流程

如果一次性上传无法访问文件字节或超出 100 MiB 上限，请使用 create_attachment_presigned_url，并从可读取文件的环境上传：

1. 使用 organization_id 和 file_name 调用 create_attachment_presigned_url（可选传入 content_type / content_length）。它会返回 upload_url（S3 PUT URL）、storage_path（对象键）和 expires_in_seconds。
2. 在可访问上传主机的环境中，在 expires_in_seconds 内通过 HTTP PUT 将文件字节发送到 upload_url（如果传入了 Content-Type / Content-Length，请发送匹配的值）。
3. 通过 update_card_field / set_table_record_field_value 将附件字段设为 [storage_path]。存储 storage_path，不要存储 URL——签名下载 URL 会在读取时生成。

由于文件字节由客户端处理（步骤 2），而非通过工具调用传递，因此不会弄脏模型的上下文。

成功标准

upload_attachment_to_card / upload_attachment_to_table_record（一次性上传）：上传结果包含 download_url（Pipefy 返回的签名 URL）、推断得出或显式指定的 content_type，以及以字节为单位的 file_size，并且卡片或记录的附件字段现在列出了该文件。一次调用即可完成全部工作。

create_attachment_presigned_url（握手流程）在生成 URL 时并未完成：此处成功仅表示已生成目标，尚未修改任何字段，也未附加任何内容。只有完成全部三个步骤才算完成：客户端将字节 PUT 到 upload_url 后，再将字段设为 [storage_path]，附件字段列出该文件。不要将生成 URL 的响应（或提前生成的签名 URL）视为上传已完成。

失败模式

检查源是否可访问、单次上传的 100 MiB 限制、上传有效期和签名标头，以及是否有权写入附件字段。如果签名 URL 过期，请重新生成；针对旧 URL 重试 PUT 并不会刷新它。预签名握手需要分别检查客户端 PUT 和字段更新，不能只检查签名生成。

另请参阅

• pipefy-pipes-and-cards：查找卡片 ID 和附件字段标识。
• pipefy-database-tables：查找表记录 ID 和字段标识。