Back to Details

linear

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Linear GraphQL

Linear GraphQL

All Linear operations go through the 
linear_graphql
client tool exposed by Symphony's app server. It handles auth automatically.
json
{
  "query": "query or mutation document",
  "variables": { "optional": "graphql variables" }
}
One operation per tool call. A top-level 
errors
array means the operation failed even if the tool call completed.
所有Linear操作均通过Symphony应用服务器提供的
linear_graphql
客户端工具执行，它会自动处理身份验证。
json
{
  "query": "query or mutation document",
  "variables": { "optional": "graphql variables" }
}
每次工具调用对应一个操作。如果返回结果中包含顶层
errors
数组，即使工具调用完成，也表示操作失败。

Workpad

Workpad

Maintain a local 
workpad.md
in your workspace. Edit freely (zero API cost), then sync to Linear at milestones — plan finalized, implementation done, validation complete. Do not sync after every small change.
First sync — create the comment, save the ID:
graphql
mutation CreateComment($issueId: String!, $body: String!) {
  commentCreate(input: { issueId: $issueId, body: $body }) {
    success
    comment { id }
  }
}
Write the returned 
comment.id
to 
.workpad-id
so subsequent syncs can update.
Subsequent syncs — read 
.workpad-id
, update in place:
graphql
mutation UpdateComment($id: String!, $body: String!) {
  commentUpdate(id: $id, input: { body: $body }) { success }
}
在你的工作区中维护本地的
workpad.md
文件。可自由编辑（无API成本），并在关键节点（计划定稿、实现完成、验证通过）时同步到Linear。不要在每次小改动后都同步。
首次同步 — 创建评论，保存ID：
graphql
mutation CreateComment($issueId: String!, $body: String!) {
  commentCreate(input: { issueId: $issueId, body: $body }) {
    success
    comment { id }
  }
}
将返回的
comment.id
写入
.workpad-id
文件，以便后续同步时可以更新该评论。
后续同步 — 读取
.workpad-id
文件，原地更新：
graphql
mutation UpdateComment($id: String!, $body: String!) {
  commentUpdate(id: $id, input: { body: $body }) { success }
}

Query an issue

查询问题

The orchestrator injects issue context (identifier, title, description, state, labels, URL) into your prompt at startup. You usually do not need to re-read.
When you do, use the narrowest lookup for what you have:
graphql
undefined
编排器会在启动时将问题上下文（标识符、标题、描述、状态、标签、URL）注入到你的提示词中。通常你无需重新查询。
当你确实需要查询时，根据已有的信息使用最精准的查询方式：
graphql
undefined

By ticket key (e.g. MT-686)

By ticket key (e.g. MT-686)

query($key: String!) { issue(id: $key) { id identifier title url description state { id name type } project { id name } } }

For comments and attachments:

```graphql
query($id: String!) {
  issue(id: $id) {
    comments(first: 50) { nodes { id body user { name } createdAt } }
    attachments(first: 20) { nodes { url title sourceType } }
  }
}
query($key: String!) { issue(id: $key) { id identifier title url description state { id name type } project { id name } } }

如需查询评论和附件：

```graphql
query($id: String!) {
  issue(id: $id) {
    comments(first: 50) { nodes { id body user { name } createdAt } }
    attachments(first: 20) { nodes { url title sourceType } }
  }
}

State transitions

状态转换

Fetch team states first, then move with the exact 
stateId
:
graphql
query($id: String!) {
  issue(id: $id) {
    team { states { nodes { id name } } }
  }
}
graphql
mutation($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue { state { name } }
  }
}
请先获取团队状态，再使用准确的
stateId
进行状态转换：
graphql
query($id: String!) {
  issue(id: $id) {
    team { states { nodes { id name } } }
  }
}
graphql
mutation($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue { state { name } }
  }
}

Attach a PR or URL

附加PR或URL

graphql
undefined
graphql
undefined

GitHub PR (preferred for PRs)

GitHub PR (preferred for PRs)

mutation($issueId: String!, $url: String!, $title: String) { attachmentLinkGitHubPR(issueId: $issueId, url: $url, title: $title, linkKind: links) { success } }
mutation($issueId: String!, $url: String!, $title: String) { attachmentLinkGitHubPR(issueId: $issueId, url: $url, title: $title, linkKind: links) { success } }

Plain URL

Plain URL

mutation($issueId: String!, $url: String!, $title: String) { attachmentLinkURL(issueId: $issueId, url: $url, title: $title) { success } }
undefined
mutation($issueId: String!, $url: String!, $title: String) { attachmentLinkURL(issueId: $issueId, url: $url, title: $title) { success } }
undefined

File upload

文件上传

Three steps:
  1. Get upload URL:
graphql
mutation($filename: String!, $contentType: String!, $size: Int!) {
  fileUpload(filename: $filename, contentType: $contentType, size: $size, makePublic: true) {
    success
    uploadFile { uploadUrl assetUrl headers { key value } }
  }
}
  1. PUT file bytes to 
    uploadUrl
    with the returned headers (use 
    curl
    ).
  2. Embed 
    assetUrl
    in comments/workpad as 
    ![description](url)
    .
三个步骤：
  1. 获取上传URL：
graphql
mutation($filename: String!, $contentType: String!, $size: Int!) {
  fileUpload(filename: $filename, contentType: $contentType, size: $size, makePublic: true) {
    success
    uploadFile { uploadUrl assetUrl headers { key value } }
  }
}
  1. 使用
    curl
    工具，将文件字节通过PUT请求上传到
    uploadUrl
    ，并携带返回的请求头。
  2. 在评论或Workpad中使用
    ![描述](url)
    的格式嵌入
    assetUrl
    。

Issue creation

创建问题

Resolve project slug to IDs first:
graphql
query($slug: String!) {
  projects(filter: { slugId: { eq: $slug } }) {
    nodes { id teams { nodes { id key states { nodes { id name } } } } }
  }
}
Then create:
graphql
mutation($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { identifier url }
  }
}
$input
fields: 
title
, 
teamId
, 
projectId
, and optionally 
description
, 
priority
(0–4), 
stateId
. For relations, follow up with:
graphql
mutation($input: IssueRelationCreateInput!) {
  issueRelationCreate(input: $input) { success }
}
Input: 
issueId
, 
relatedIssueId
, 
type
(
blocks
or 
related
).
先将项目slug解析为ID：
graphql
query($slug: String!) {
  projects(filter: { slugId: { eq: $slug } }) {
    nodes { id teams { nodes { id key states { nodes { id name } } } } }
  }
}
然后创建问题：
graphql
mutation($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { identifier url }
  }
}
$input
字段包括：
title
、
teamId
、
projectId
，可选字段有
description
、
priority
（0–4）、
stateId
。如需添加关联关系，可执行后续操作：
graphql
mutation($input: IssueRelationCreateInput!) {
  issueRelationCreate(input: $input) { success }
}
输入参数：
issueId
、
relatedIssueId
、
type
（
blocks
或
related
）。

Rules

规则

  • No introspection. Never use 
    __type
    or 
    __schema
    queries. They return the entire Linear schema (~200K chars) and waste the context window. Every pattern you need is documented above.
  • Keep queries narrowly scoped — ask only for fields you need.
  • Sync the workpad at milestones, not after every change.
  • For state transitions, always fetch team states first — never hardcode state IDs.
  • Prefer 
    attachmentLinkGitHubPR
    over generic URL attachment for GitHub PRs.
  • 禁止自省：绝不允许使用
    __type
    或
    __schema
    查询。这类查询会返回整个Linear架构（约200KB字符），浪费上下文窗口。你所需的所有使用模式均已在上述文档中说明。
  • 保持查询范围精准——只请求你需要的字段。
  • 仅在关键节点同步Workpad，而非每次改动后都同步。
  • 进行状态转换时，务必先获取团队状态——绝不要硬编码状态ID。
  • 对于GitHub PR，优先使用
    attachmentLinkGitHubPR
    而非通用URL附加方式。