Linear SDK — TypeScript Client for Linear Agents

简介

Linear SDK 是官方 TypeScript 客户端，包装 Linear GraphQL API。每个方法完全类型化（Issue / Project / Cycle / Team / User），自带分页和限速处理。适合超出 MCP 能力的 Linear 自动化 agent 和 bot —— 批量导入、复杂查询、定时分诊。需要 Node 18+ / Bun / Deno。装机时间 2 分钟。

Hello, Linear

import { LinearClient } from "@linear/sdk";

const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

// 拿我的 issue
const me = await linear.viewer;
const issues = await me.assignedIssues({ first: 50 });

for (const issue of issues.nodes) {
  console.log(`${issue.identifier} — ${issue.title} (${(await issue.state).name})`);
}

创建带完整字段的 issue

const team = await linear.team("ENG");

const issue = await linear.createIssue({
  teamId: team.id,
  title: "Auth flow drops state on redirect",
  description: "**Steps to reproduce:**\n1. Login\n2. Click external link\n3. Click back\n\nState lost.",
  priority: 1,  // 紧急
  assigneeId: (await linear.viewer).id,
  labelIds: [
    (await team.labels()).nodes.find(l => l.name === "bug")?.id!,
  ],
  projectId: "your-project-id",
});

console.log(`Created ${issue.issue?.identifier}`);

批量分诊带限速感知

import pLimit from "p-limit";

const limit = pLimit(5);  // 5 并发，SDK 在 429 时自动重试

const stale = await linear.issues({
  filter: {
    state: { type: { eq: "started" } },
    updatedAt: { lt: new Date(Date.now() - 14 * 86400_000) },
  },
});

await Promise.all(
  stale.nodes.map(issue =>
    limit(() =>
      issue.update({
        labelIds: [...issue.labelIds, STALE_LABEL_ID],
      }),
    ),
  ),
);

Webhook payload 配 SDK

// Express handler
app.post("/webhooks/linear", async (req, res) => {
  if (req.body.action === "create" && req.body.type === "Issue") {
    const issue = await linear.issue(req.body.data.id);
    if ((await issue.priority) === 1) {
      await notifySlack(`🔥 Urgent issue: ${issue.title}`);
    }
  }
  res.sendStatus(200);
});

FAQ

Q: SDK 和 MCP 怎么选？ A: 交互式 agent 用 MCP（Claude Code 在会话里问 Linear 问题）。定时或 webhook 驱动的自动化用 SDK（Inngest 任务、GitHub Action、服务端 bot）。很多团队两个都用。

Q: SDK 限速感知吗？ A: 感知 —— 内置 429 上的指数退避重试。高吞吐任务配 p-limit（并发上限）+ 持久化进度便于恢复。

Q: 能直接用 Linear GraphQL 吗？ A: 能 —— 类型化 SDK 方法只是 GraphQL 包装。SDK 没暴露的查询用 linear.client.rawRequest(query, variables) 发任意 GraphQL。