pipefy-api-fallback

Pipefy API 备用方案（第 3 层——最后手段）

根据你使用的接口，阅读 MCP 参考 或 CLI 参考。只加载相关参考。

仅当第 1 层和第 2 层均失败后，此技能才会启用。直接调用 Pipefy GraphQL API，绕过工具包连接。

如果写入操作报告失败，请在切换层级或重试前重新读取目标。变更可能已经生效；请遵循写入失败结果不明确。

---

3 层解析策略（始终按顺序执行）

1. 尝试专用操作（create_card、get_phase_cards、get_phase_allowed_move_targets、update_pipe 等）。有关卡片／阶段的播种和清点，请参阅 pipefy-pipes-and-cards — 跨阶段播种管道。
2. 专用操作不可用或意外失败时，使用架构内省和 execute_graphql。请参阅 pipefy-introspection。
3. 仅当工具包连接不可用，或 GraphQL 执行因基础设施错误而失败时，才使用直接 HTTP。

不要因一次失败就跳到第 3 层。 按顺序执行各层。测试新的 mutation 属于第 2 层。

---

身份验证

有两种方式（使用环境中可用的方式）。如果两种方式都可用，优先使用 Service Account。

若要查看设置了哪些变量，只列出变量名，绝不要显示变量值：

env | cut -d= -f1 | grep '^PIPEFY_'

不要运行 env、printenv 或 echo 来选择这些变量：在用户同意之前，这会将密钥打印到对话中。

读取任何 PIPEFY_* 变量之前，请告知用户你将读取哪个变量，并说明其值会通过 Authorization 标头或令牌请求发送到 app.pipefy.com，然后等待用户同意。不要从用户未指定的文件中读取。

选项 A — OAuth2 Client Credentials（首选）：

TOKEN=$(curl -s -X POST https://app.pipefy.com/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_ID\",\"client_secret\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

选项 B — Personal Access Token（PAT）：

TOKEN="$PIPEFY_PAT"   # or $PIPEFY_TOKEN

新集成已弃用 PAT，但环境中可能仍有 PAT。

令牌规则

• Bearer 前缀为必填项——没有该前缀，Pipefy 会拒绝请求。
• 不得在回复用户时或日志中泄露 PIPEFY_SERVICE_ACCOUNT_CLIENT_ID、PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET、PIPEFY_PAT 或 PIPEFY_TOKEN。
• Service Account 令牌在有效期内会重复使用；仅在令牌过期（401）时重新获取。

---

端点

用途	URL
查询、mutation 和内省	https://app.pipefy.com/graphql
OAuth2 令牌	https://app.pipefy.com/oauth/token

此端点用于查询、mutation 和公开架构内省；https://api.pipefy.com/graphql 的响应也相同。工具包使用此端点访问公开架构（PIPEFY_BASE_URL 加 /graphql）。Portal 工具及其他少数工具还会使用另外两个端点 /graphql/interfaces 和 /internal_api；请参阅 docs/mcp/tools/portal.md。

---

执行 GraphQL 查询

curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id name } }"}' | jq .

执行 GraphQL mutation

curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateCard($input: CreateCardInput!) { createCard(input: $input) { card { id } } }",
    "variables": {
      "input": {
        "pipe_id": 67890,
        "title": "Fallback Card"
      }
    }
  }' | jq .

---

通过原始 API 进行内省

需要通过直接 HTTP 发现架构时，调用同一端点：

# All queries and mutations
curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __schema { queryType { fields { name description } } mutationType { fields { name description } } } }"}'

# Type details
curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __type(name: \"CreateCardInput\") { inputFields { name description type { name kind ofType { name kind } } } } }"}'

---

错误代码 → 原因

GraphQL 错误（包括语法错误 GRAPHQL_PARSE_FAILED）会返回 HTTP 200：请检查 errors 数组及其 extensions.code，而不是 HTTP 状态码。身份验证失败会返回 HTTP 401；请求正文不是有效的 JSON 时，会返回 HTTP 500 和纯文本页面。

Code	可能原因	处理方法
HTTP 401，正文为 {"errors": [{"title": "Unauthorized", ...}]}	缺少或为空的 Authorization 标头，或者发送的令牌没有 Bearer 前缀	修正标头：Authorization: Bearer $TOKEN，并确保令牌非空。
HTTP 401，正文为 {"error": "invalid_token", ...}	存在 Bearer 令牌，但令牌无效或已过期	重新获取令牌（选项 A）。
PERMISSION_DENIED	Service Account 不是此 pipe/table 的成员；对于不存在的 pipe 或 card ID，Pipefy 也会返回此错误	验证 ID；通过 invite_members 添加 SA，或询问用户。
resource_not_found	ID 不存在，或 SA 无权查看	验证 ID；检查 pipe/table 成员资格。
invalid_input	参数名称或类型错误	运行 introspect_type（第 2 层）以重新检查输入结构。
undefinedField	查询选择了该类型不存在的字段	对该类型运行 introspect_type 并修正字段选择。
INTERNAL_SERVER_ERROR	API 错误或不支持的负载	不要使用相同的负载重试。 尝试其他 mutation 或变通方案。
missingRequiredInputObjectAttribute	输入中缺少必填字段	将负载与 __type(name: …InputType) 进行比较。
写入失败但结果不明确（success: false，消息为空或不清楚）	mutation 可能已经生效（服务器上产生了副作用）	重试前先重新读取 — 参见写入失败但结果不明确。

---

写入失败但结果不明确（重试前先重新读取）

即使 mutation 已经生效，写入操作和 execute_graphql 仍可能报告失败。盲目重试会重复创建客户数据（例如，尽管 success: false，仍创建了许多卡片）。

1. 不要立即重新运行相同的创建操作/mutation。
2. 先重新读取：检查目标 pipe 或 phase 上的 get_cards / get_phase_cards_count / 返回的 ID / cards_count。如果有写入前记录的计数或 ID 集合，优先与之比较。
3. 仅当重新读取明确表明写入未生效时，才重试。
4. 如果重新读取无法得出结论（没有写入前的基准、分页截断结果，或计数无法证明写入不存在），则停止 — 向用户报告结果不明确的失败以及重新读取的证据。不要猜测性重试。
5. 严格禁止 — 不支持客户端侧幂等性： CreateCardInput 没有 idempotency_key（只有 clientMutationId，它并不提供创建幂等性）。不要自行编造客户端侧键，也不要假设重试是安全的。在 API 添加真正的幂等性之前，重新读取是唯一安全的做法。

---

已知变通方案

跨 pipe 创建卡片

• 使用 action: create_card 和 field_map 的 createAutomation 在跨 pipe 目标上可能会返回 INTERNAL_SERVER_ERROR。不要原样重试该负载。
• 对于一次性关联卡片，如果 connector 字段的 canCreateNewConnected: true，则可以使用 throughConnectors 调用 createCard 创建卡片。
• createCard 不会创建自动化规则。如果用户需要今后自动创建卡片，请说明这次一次性调用无法满足该需求。

Pipe 列表短于 pipesCount

• pipesCount 是组织范围内的总数；organization { pipes { ... }} 和 search_pipes 只会返回当前调用身份所属的 Pipe。列表较短或为空都是预期行为，并非错误。角色不会扩大结果范围：super_admin 得到的结果也受相同的成员关系范围限制。详情和变通方法：docs/mcp/tools/organization.md。
• organization { pipes(include_publics: true) } 会将组织内公开的 Pipe 也纳入列表，但通常仍少于 pipesCount。
• 服务账号最常遇到此情况：SA 初始时不属于任何 Pipe。
• 通过 API 创建的 Pipe 会自动对 SA 可见。
• 在 UI 中创建的 Pipe 则需要将 SA 添加为管理员。
• 变通方法：向用户获取 Pipe ID，然后直接查询 pipe(id: "...")。

invite_members 会静默接受未知邮箱

• Pipefy 会为拼写错误的地址创建新的 user_id，而不会拒绝邀请。调用前请检查邮箱语法。

---

外部资源（原始 API 也失败时）

• Pipefy 开发者门户：
  • https://developers.pipefy.com/reference/cards
  • https://developers.pipefy.com/reference/pipes
  • https://developers.pipefy.com/reference/automation-creation
  • https://developers.pipefy.com/reference/how-to-handle-errors
• API 参考：
  • https://api-docs.pipefy.com/reference/mutations/overview/
  • https://api-docs.pipefy.com/reference/queries/overview/
• 社区和更新日志：
  • https://community.pipefy.com/api-76
  • https://developers.pipefy.com/changelog
• 状态页： https://status.pipefy.com

搜索完整的错误消息加上 "Pipefy GraphQL"，或 mutation 名称加上 "example Pipefy API"。

---

升级并求助用户（绝对最后手段）

只有在上述 3 个层级和外部资源都无效后，才执行以下操作：

1. 准确说明已尝试的方式（专用操作、内省、原始 API）。
2. 展示未经改动的错误响应。
3. 提出具体的变通方法（例如：“通过 Pipefy UI 创建，然后使用生成的 ID 通过 API 继续操作”）。
4. 停止——不要循环尝试。

---

成功标准

• 操作完成，且没有 HTTP 4xx/5xx 错误。
• 响应包含 data 键，且 errors 为 null 或不存在。

失败模式

• HTTP 401：请求头缺失、为空或不包含 Bearer （响应正文为 Unauthorized），或者令牌无效或已过期（响应正文为 invalid_token）。修正请求头，或重新获取 OAuth 令牌（选项 A）。
• HTTP 200 时出现 GRAPHQL_PARSE_FAILED：GraphQL 语法错误。请验证查询字符串；通过 shell 嵌入时，正确转义引号。
• HTTP 500：首先检查请求正文是否为有效 JSON，因为格式错误的正文也会返回 500。如果正文有效，则视为 Pipefy API 故障：检查 status.pipefy.com，稍后重试。不要循环尝试。
• errors 数组中出现 INTERNAL_SERVER_ERROR——不要使用相同的载荷重试；改用其他 mutation 路径。
• 写入失败情况不明确——创建或其他写入操作后报告的错误消息为空或含糊：重试前重新读取计数/ID；绝不要盲目重试创建操作（写入失败情况不明确——重试前重新读取）。

安全注意事项

• 绝不要以纯文本形式记录或打印令牌。
• 优先使用环境变量，而非内联凭据。
• PIPEFY_TOKEN / PIPEFY_PAT 仅用于个人/开发用途；服务账号请使用服务账号凭据（PIPEFY_SERVICE_ACCOUNT_CLIENT_ID + PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET）。

另请参阅

• pipefy-introspection — 第 2 层：在退回到直接 HTTP 请求之前，使用 execute_graphql 和内省工具。