SuperAPI AI 工具集

Linear SDK Usage

编程与开发

查看项目

更新于 10-16 05:29

技能介绍

用途 该技能面向使用 Linear 官方 SDK(@linear/sdk)实现 Linear 集成的场景,例如以编程方式创建 issue,以及进阶的 fetch/modify 数据操作。资料同时给出官方参考文档链接:SDK 概览、进阶用法、fetch/modify、错误处理,以及使用 linear.new 创建 issue。

主要能力

  • 初始化客户端:使用 API Key(new LinearClient({ apiKey: process.env.LINEAR_API_KEY }))、OAuth(new LinearClient({ accessToken: token }))以及 actor 模式(accessToken 配合授权时设置的 actor=app 归因)。
  • 惰性连接获取:SDK 返回 LinearFetch<T>,可自动解析嵌套连接,例如先取 team,再取 issues,再逐个 await issue.assignee。
  • 变更操作:通过 client.createIssue 创建 issue,并检查 result.success,再 await result.issue。
  • 类型化错误:AuthenticationError(token 无效)、UserError(输入校验失败)、RatelimitedError(需退避,可检查 headers.get("X-RateLimit-Reset"))、NetworkError(指数退避重试)、GraphqlError(服务端错误,可捕获 errors[].extensions.code)。
  • 分页辅助:提供 async function* paginate(query, vars) 生成器,基于 pageInfo.hasNextPage 与 endCursor 迭代,资料注明用于 lib/pagination.ts。
  • UI 介导创建:通过 linear.new 深链接进行创建,适用于需要用户输入的分诊流程。

使用方式 按资料示例初始化客户端后,使用 client.team、team.issues({ first: 50 }) 等获取数据,遍历 issues.nodes;对嵌套字段使用 await 惰性获取。创建 issue 时调用 client.createIssue({ teamId, title, description, priority: 1 }),并校验 success。分页使用提供的 paginate 生成器。错误处理按错误类型分别应对。

适用场景 适用于需要在应用中集成 Linear、批量或程序化创建 issue、读取与修改 Linear 数据、处理分页与限流、以及构建需要用户输入的分诊创建流程。

限制与注意事项 资料指出惰性访问会触发 N+1 查询,建议改用 client.issues({ filter, includeArchived: false }) 并配合预先选择嵌套字段的 GraphQL 查询,或通过 client.client.rawRequest() 使用原始 GraphQL。actor 模式的归因由授权时的 actor=app 设置,而非每次调用设置。其余如具体收费、价格、平台支持范围等事实暂未提供。