Linear GraphQL Patterns

Linear GraphQL Patterns 是一份针对 Linear API 的 GraphQL 查询编写与审查参考，主要用于在编写或评审面向 Linear API 的 GraphQL 查询时提供模式指导，涉及片段选择、连接类型遍历、批量请求等主题。

用途 该技能面向需要与 Linear API 交互的开发者，帮助在编写或审查 GraphQL 查询时遵循 Linear 的接口约定，减少常见错误。资料中提到的 linear-graphql-expert 智能体会检查涉及 lib/queries/ 的 PR，并对 @deprecated 字段发出警告。

主要能力与模式

1. 连接模式（游标分页）：Linear 中每个列表查询都返回 Connection 类型。示例查询使用 issues(first: 50, after: $cursor, filter: {...}, orderBy: updatedAt)，并选择 pageInfo { hasNextPage endCursor } 与 nodes { id identifier title state { name } }。资料建议始终选择 pageInfo { hasNextPage endCursor } 以获取游标，first 通常使用 50-100，最大 250。
2. Fragment 库：建议在 lib/queries/fragments.graphql.ts 中定义可复用片段。资料给出了 IssueCore 片段示例，包含 id、identifier、title、priority、estimate、dueDate、url、state { id name type }、team { id key name }、assignee { id email displayName }、parent { id identifier }、cycle { id name }、project { id name }、labels { nodes { id name color } } 等字段。
3. Mutation 模式：Mutation 返回带 success 与实体的 Payload。示例为 issueCreate(input: { ... }) 返回 success、issue { ...IssueCore } 与 lastSyncId。资料强调在将实体视为已创建之前，始终检查 success。
4. 同步 ID：每个 Mutation 返回 lastSyncId。在最终一致性场景下，可在后续读取时传入 syncId 参数以确保一致性。Webhook 负载包含 dataSyncId，可用于匹配。
5. 避免 N+1 陷阱：建议积极使用 nodes 连接，在一次查询中获取 labels/assignees，而不是按 issue 逐个解析。
6. 弃用处理：资料给出 Schema 弃用说明链接 https://linear.app/developers/deprecations。常见需关注的弃用包括旧版 archivedAt（现为 trashed）、state 字符串（现为 state { id name type }）。
7. 复杂度感知查询：每个查询都有复杂度成本，可在响应头 X-Complexity 中查看。建议单次查询成本保持在 1000 以下，将重连接拆分到多次查询。限流说明见 https://linear.app/developers/rate-limiting。

使用方式 资料未提供具体的安装命令或调用步骤，仅给出参考链接与代码模式示例。Schema 参考位于 https://studio.apollographql.com/public/Linear-API/variant/current/schema/reference。

适用场景 适用于编写或审查针对 Linear API 的 GraphQL 查询、组织可复用 Fragment、处理分页与批量请求、处理 Mutation 返回与同步一致性、规避 N+1 查询、跟踪字段弃用以及控制查询复杂度的开发工作。

限制 资料未说明该技能的收费、价格、支持平台或具体效果。安装与集成方式暂未提供。