pipefy-introspection

自省与原始 GraphQL

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

架构发现、组织信息和备用执行器。

这是解析策略中的第 2 层：专用操作失败或不存在时，使用自省了解 API，然后通过 execute_graphql 直接运行操作。

如果专用写入操作报告失败，请在尝试通过 execute_graphql 执行变更前，重新读取目标。只有读取结果显示写入未生效时，才继续操作。如果结果无法确定，请报告情况并停止；再次创建可能会产生重复数据。

第 1 层： 存在专用操作——使用它。 第 2 层： 使用自省 + execute_graphql（此技能）。 第 3 层： 直接使用 curl/httpx 作为备用方案——参见 pipefy-api-fallback。

---

工具

操作	只读	用途
introspect_type	是	类型结构：fields、inputFields、enumValues。可选的 max_depth。
introspect_query	是	根查询参数和返回类型。可选的 max_depth。
introspect_mutation	是	根变更参数和返回类型。可选的 max_depth。
search_schema	是	按类型名称/描述进行关键词搜索。可选的 kind 筛选条件。
execute_graphql	否	执行任意 GraphQL。
get_organization	是	加载组织信息（名称、套餐、UUID、成员数量、管道数量）。
list_organizations	是	列出调用者可访问的组织——无需 ID。用于发现组织的零知识入口。

---

max_depth（introspect_type / query / mutation）

max_depth 默认值为 1。

• 1 — 仅类型/字段信息（不内联子类型）。
• 2+ — 内联解析引用的输入/输出类型（resolvedType），因此一次调用即可替代先自省变更、再分别自省各输入类型的操作。

示例：

introspect_mutation mutation_name="createCard" max_depth=2

标量（ID、String、Int 等）不会展开。

search_schema 中的 kind

可选筛选条件：OBJECT、INPUT_OBJECT、ENUM、SCALAR、INTERFACE、UNION。

search_schema keyword="automation" kind="INPUT_OBJECT"

---

何时使用自省

• 专用工具返回错误，而你需要了解原因——自省输入类型以检查参数名称/类型。
• create_phase_field 的字段类型：工具的输入架构会列出这些类型。当架构不可见或需要检查是否存在偏差时，introspect_type('FieldTypeId') 会列出这些类型。
• 使用 extra_input 之前：自省对应的输入类型以查找可选键。
• 未知变更签名：在使用 execute_graphql 之前，调用 introspect_mutation('createSomething')。
• 探索架构：使用 search_schema('automation') 查找相关类型和输入。

何时使用 execute_graphql

• 此操作不存在专用操作。
• 专用工具失败，且你已使用自省了解正确的载荷。
• 临时查询，例如通过 pipe(id: $id) { organization { uuid } } 解析组织 UUID。
• 没有单个工具能够覆盖的复杂嵌套查询。

始终优先使用专用操作。 它们会验证输入、处理分页，并以统一方式格式化错误。专用工具无法解决问题时，才使用 execute_graphql 作为备用方案。

---

步骤——发现变更签名

1. 按关键词搜索变更：

   search_schema keyword="label"
   

2. 获取完整的变更签名：

   introspect_mutation mutation_name="createLabel"
   

3. 发现输入类型字段：

   introspect_type type_name="CreateLabelInput"
   

4. 使用发现的变更及其变量执行 execute_graphql。

---

常见备用方案示例

适用于专用工具无法满足需求的场景，可直接使用以下模式。

示例 1 — 发现 create_phase_field 的有效字段类型

introspect_type('FieldTypeId')

CreatePhaseFieldInput.type 是一个 ID 标量，但 API 将其有效值公布为 FieldTypeId 枚举。create_phase_field 输入架构会列出相同的值。

配方 2 — 按标题查找卡片（find_cards 无法实现）

find_cards 只搜索自定义字段值。要按标题搜索：

execute_graphql query='query($pipeId: ID!, $first: Int) { cards(pipe_id: $pipeId, first: $first) { edges { node { id title current_phase { name } } } } }' variables='{"pipeId":"<pipe-id>","first":50}'

在客户端按标题筛选。对于较大的 pipe，使用 after 分页。

配方 3 — 查明 extra_input 对任何变更操作接受哪些参数

当工具接受 extra_input 时（例如 create_automation、update_label），查明所有可选键：

introspect_mutation('createAutomation')     # find the input type name
introspect_type('CreateAutomationInput')    # see all inputFields

与工具的主要参数对比，以了解哪些键可通过 extra_input 额外提供。

配方 4 — 查明组织 ID

若要回答“我可以访问哪些组织？”且手头没有任何信息，请调用 list_organizations——它不需要 ID，并会返回每个组织的 id、uuid、name 以及你的角色。这是入口；只有在你已有 pipe 时，才使用下面的 GraphQL 后备方案。

当用户只有 pipe ID，且需要其 organization_id 时：

execute_graphql query='query($id: ID!) { pipe(id: $id) { organization { id uuid name } } }' variables='{"id":"<pipe-id>"}'

配方 5 — 创建后更新单选字段的选项

创建时，要设置选项，请将 options 传给 create_phase_field。使用此配方稍后更改选项。

execute_graphql query='mutation($id: ID!, $options: [String!]) { updatePhaseField(input: { id: $id, options: $options }) { phase_field { id label options } } }' variables='{"id":"<field-id>","options":["High","Medium","Low"]}'

配方 6 — 检查阶段转换规则

当 move_card_to_phase 因“不是有效的目标阶段”而失败时：

execute_graphql query='query($id: ID!) { phase(id: $id) { id name cards_can_be_moved_to_phases { id name } } }' variables='{"id":"<current-phase-id>"}'

返回当前阶段可到达的有效目标阶段。

---

成功标准

• introspect_type 返回输入类型的完整字段列表。
• execute_graphql 无错误地返回预期数据。

失败模式

• introspect_type 返回 null：类型名称区分大小写；尝试使用 PascalCase（例如，CreateLabelInput，而不是 create_label_input）。
• search_schema 返回大量结果：它会进行不区分大小写的子字符串匹配；像 "card" 这样的宽泛关键词会产生大量结果。优先使用 "AiAgent"、"FieldCondition" 等具体名称。
• introspect_mutation 开销较大：它会获取所有根变更字段，并在客户端筛选（单个大型查询）。如果你已知道变更操作名称，优先对具体输入类型使用 introspect_type。
• execute_graphql 返回 GraphQL 错误：检查 path 和 message。
• 原始 HTTP 端点：该工具包会将公共 schema 的内省请求和操作发送至同一端点 <PIPEFY_BASE_URL>/graphql（默认为 https://app.pipefy.com/graphql）。如需直接调用，请参阅 pipefy-api-fallback。

另请参阅

• docs/mcp/tools/introspection.md — MCP 参数，以及 execute_graphql 上查询与变更操作不匹配的提示。
• pipefy-api-fallback — 第 3 级：工具包不可用时直接使用 HTTP 后备方案。
• pipefy-pipes-and-cards — 最常用的专用工具（优先于 execute_graphql）。