linear

Linear GraphQL

在 Symphony app-server 会话期间进行原始 Linear GraphQL 操作时使用此技能。

主要工具

使用 Symphony 的 app-server 会话提供的 linear_graphql 客户端工具。 它会在会话中复用 Symphony 配置的 Linear 身份验证。

工具输入：

{
  "query": "query or mutation document",
  "variables": {
    "optional": "graphql variables object"
  }
}

工具行为：

• 每次工具调用发送一个 GraphQL 操作。
• 即使工具调用本身已完成，也要将顶层 errors 数组视为 GraphQL 操作失败。
• 查询和变更应尽可能精简；只请求所需字段。

探索不熟悉的操作

需要了解不熟悉的变更、输入类型或对象字段时，通过 linear_graphql 进行有针对性的内省。

列出变更名称：

query ListMutations {
  __type(name: "Mutation") {
    fields {
      name
    }
  }
}

检查特定输入对象：

query CommentCreateInputShape {
  __type(name: "CommentCreateInput") {
    inputFields {
      name
      type {
        kind
        name
        ofType {
          kind
          name
        }
      }
    }
  }
}

常见工作流

按键、标识符或 id 查询 issue

按以下顺序逐步尝试：

• 如果有类似 MT-686 的工单键，先使用 issue(id: $key)。
• 需要按标识符搜索时，改用 issues(filter: ...)。
• 获取内部 issue id 后，优先使用 issue(id: $id) 进行范围更窄的读取。

按 issue 键查找：

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

按标识符筛选查找：

query IssueByIdentifier($identifier: String!) {
  issues(filter: { identifier: { eq: $identifier } }, first: 1) {
    nodes {
      id
      identifier
      title
      state {
        id
        name
        type
      }
      project {
        id
        name
      }
      branchName
      url
      description
      updatedAt
    }
  }
}

将键解析为内部 id：

query IssueByIdOrKey($id: String!) {
  issue(id: $id) {
    id
    identifier
    title
  }
}

已知内部 id 后读取 issue：

query IssueDetails($id: String!) {
  issue(id: $id) {
    id
    identifier
    title
    url
    description
    state {
      id
      name
      type
    }
    project {
      id
      name
    }
    attachments {
      nodes {
        id
        title
        url
        sourceType
      }
    }
  }
}

查询 issue 的团队工作流状态

需要准确的 stateId 来更改 issue 状态时，先执行此操作：

query IssueTeamStates($id: String!) {
  issue(id: $id) {
    id
    team {
      id
      key
      name
      states {
        nodes {
          id
          name
          type
        }
      }
    }
  }
}

编辑现有评论

通过 linear_graphql 使用 commentUpdate：

mutation UpdateComment($id: String!, $body: String!) {
  commentUpdate(id: $id, input: { body: $body }) {
    success
    comment {
      id
      body
    }
  }
}

创建评论

通过 linear_graphql 使用 commentCreate：

mutation CreateComment($issueId: String!, $body: String!) {
  commentCreate(input: { issueId: $issueId, body: $body }) {
    success
    comment {
      id
      url
    }
  }
}

将 issue 移至其他状态

使用带有目标 stateId 的 issueUpdate：

mutation MoveIssueToState($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue {
      id
      identifier
      state {
        id
        name
      }
    }
  }
}

将 GitHub PR 关联到 issue

关联 PR 时，使用 GitHub 专用的附件变更：

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

如果只需要附加普通 URL，且不需要 GitHub 专属链接元数据，请使用：

mutation AttachURL($issueId: String!, $url: String!, $title: String) {
  attachmentLinkURL(issueId: $issueId, url: $url, title: $title) {
    success
    attachment {
      id
      title
      url
    }
  }
}

架构探索期间使用的内省模式

不确定具体字段或变更形式时，使用以下模式：

query QueryFields {
  __type(name: "Query") {
    fields {
      name
    }
  }
}

query IssueFieldArgs {
  __type(name: "Query") {
    fields {
      name
      args {
        name
        type {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
            }
          }
        }
      }
    }
  }
}

将视频上传到评论

分三步完成：

1. 使用 fileUpload 调用 linear_graphql，获取 uploadUrl、assetUrl 以及所需的上传标头。
2. 使用 curl -X PUT 将本地文件字节上传到 uploadUrl，并使用 fileUpload 返回的确切标头。
3. 再次使用 commentCreate（或 commentUpdate）调用 linear_graphql，并在评论正文中包含生成的 assetUrl。

实用变更：

mutation FileUpload(
  $filename: String!
  $contentType: String!
  $size: Int!
  $makePublic: Boolean
) {
  fileUpload(
    filename: $filename
    contentType: $contentType
    size: $size
    makePublic: $makePublic
  ) {
    success
    uploadFile {
      uploadUrl
      assetUrl
      headers {
        key
        value
      }
    }
  }
}

使用规则

• 使用 linear_graphql 编辑评论、上传文件以及执行临时 Linear API 查询。
• 优先采用与已知信息相符且范围最窄的 issue 查找方式：键 -> 标识符搜索 -> 内部 id。
• 对于状态转换，先获取团队状态，并使用准确的 stateId，不要在变更中硬编码名称。
• 将 GitHub PR 关联到 Linear issue 时，优先使用 attachmentLinkGitHubPR，而非通用 URL 附件。
• 不要为 GraphQL 访问引入新的原始令牌 Shell 辅助工具。
• 如果上传需要使用 Shell，仅将其用于 fileUpload 返回的签名上传 URL；这些 URL 已包含所需的授权信息。