Linear_知识管理 skill-PHP中文网

Linear

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

通过托管OAuth实现Linear API集成，使用GraphQL查询和管理问题、项目、团队、周期及标签。适用于需要创建、更新或查询Linear问题、搜索任务、管理项目或跟踪工作等场景；其他第三方应用请使用api-gateway技能。

使用管理 OAuth 认证访问线性 API

功能概述

使用管理 OAuth 认证访问线性 API是一项面向实际任务的技能，主要用于使用 GraphQL.；QQQQQQQQQQQQQQQQQQQQQQQQQQQQLTHLAGE :CLI: .；

核心要点

Python: . .；
Base URL. 所有请求。
它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

使用与执行

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

结果检查与注意事项

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

Linear

通过受管 OAuth 认证访问 Linear API。使用 GraphQL 查询和管理 issue、项目（projects）、团队（teams）、迭代周期（cycles）、标签（labels）及评论（comments）。

快速开始

CLI：

maton linear issue list -c ABC -L 10

maton api '/linear/graphql'

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': '{ viewer { id name email } }'}).encode()
req = urllib.request.Request('https://api.maton.ai/linear/graphql', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://api.maton.ai/linear/graphql

所有请求均以 POST 方式发送至 GraphQL 端点。Maton 将请求代理至 api.linear.app，并自动注入您的 OAuth Token。

安装

NPM：

npm install -g @maton/cli

Homebrew：

brew install maton-ai/cli/maton

认证

CLI：

maton login                          # 在浏览器中打开以获取 API 密钥
maton login --interactive            # 跳过浏览器，直接粘贴 API 密钥
maton whoami                         # 显示当前认证状态

手动配置：

在 maton.ai 登录或注册账户
访问 maton.ai/settings
复制您的 API 密钥
将 API 密钥设为环境变量 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

连接管理

您可在 https://api.maton.ai 管理 Linear 的 OAuth 连接。

列出连接

CLI：

maton connection list linear --status ACTIVE

maton api -X GET /connections -f app=linear -f status=ACTIVE

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=linear&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

CLI：

maton connection create linear

maton api /connections -f app=linear

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'linear'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接详情

CLI：

maton connection view {connection_id}

maton api /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应示例：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2026-02-04T23:03:22.676001Z",
    "last_updated_time": "2026-02-04T23:03:51.239577Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "linear",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权流程。

删除连接

CLI：

maton connection delete {connection_id}

maton api -X DELETE /connections/{connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

若您拥有多个 Linear 连接，请显式指定要使用的连接：

CLI：

maton linear issue list -c ABC --connection {connection_id}

maton api /linear/graphql --connection {connection_id}

Python：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': '{ viewer { id name } }'}).encode()
req = urllib.request.Request('https://api.maton.ai/linear/graphql', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

若存在多个连接，请始终明确指定连接 ID，以确保请求路由到目标 Linear 账户。

安全与权限

访问范围限定于已连接 Linear 账户内的 issues、projects、teams、cycles 和 comments。
所有写操作均需用户显式授权。 在执行任何创建（create）、更新（update）或删除（delete）调用前，必须向用户确认目标资源及其预期影响。

API 参考

Linear 使用 GraphQL API。所有操作均以 POST 请求形式发送，请求体为 JSON 格式，且必须包含 query 字段。

Viewer（当前用户）

POST /linear/graphql
Content-Type: application/json

{"query": "{ viewer { id name email } }"}

示例：

maton linear whoami

组织（Organization）

POST /linear/graphql
Content-Type: application/json

{"query": "{ organization { id name urlKey } }"}

示例：

maton linear org view

团队（Teams）

列出团队

POST /linear/graphql
Content-Type: application/json

{"query": "{ teams { nodes { id name key } } }"}

示例：

maton linear team list

获取单个团队

POST /linear/graphql
Content-Type: application/json

{"query": "{ team(id: \"ABC\") { id name key issues { nodes { id identifier title } } } }"}

示例：

maton linear team view ABC

Issues

列出 Issues

POST /linear/graphql
Content-Type: application/json

{"query": "{ issues(first: 10, filter: { team: { key: { eq: \"ABC\" } } }) { nodes { id identifier title state { name } priority createdAt } pageInfo { hasNextPage endCursor } } }"}

示例：

maton linear issue list -c ABC -L 10

通过 ID 或 Identifier 获取 Issue

POST /linear/graphql
Content-Type: application/json

{"query": "{ issue(id: \"ABC-123\") { id identifier title description state { name } priority assignee { name } team { key name } createdAt updatedAt } }"}

示例：

maton linear issue view ABC-123

过滤 Issues

按工作流状态类型（state type）过滤：

POST /linear/graphql
Content-Type: application/json

{"query": "{ issues(first: 10, filter: { state: { type: { eq: \"started\" } } }) { nodes { id identifier title state { name type } } } }"}

示例：

maton linear issue list --state started -L 10

按标题（title）过滤：

POST /linear/graphql
Content-Type: application/json

{"query": "{ issues(first: 10, filter: { title: { containsIgnoreCase: \"bug\" } }) { nodes { id identifier title } } }"}

示例：

maton linear issue list --title bug -L 10

搜索 Issues

POST /linear/graphql
Content-Type: application/json

{"query": "{ searchIssues(first: 10, term: \"shopify\") { nodes { id identifier title } } }"}

示例：

maton linear issue search shopify -L 10

创建 Issue

POST /linear/graphql
Content-Type: application/json

{"query": "mutation { issueCreate(input: { teamId: \"TEAM_ID\", title: \"New issue title\" }) { success issue { id identifier title state { name } } } }"}

示例：

maton linear issue create --team-id TEAM_ID -t 'New issue title'

更新 Issue

POST /linear/graphql
Content-Type: application/json

{"query": "mutation { issueUpdate(id: \"ABC-123\", input: { title: \"Updated title\", priority: 2 }) { success issue { id identifier title priority } } }"}

示例：

maton linear issue update ABC-123 -t 'Updated title' --priority 2

Projects（项目）

列出 Projects

POST /linear/graphql
Content-Type: application/json

{"query": "{ projects(first: 10) { nodes { id name state createdAt } } }"}

示例：

maton linear project list

Cycles（迭代周期）

列出 Cycles

POST /linear/graphql
Content-Type: application/json

{"query": "{ cycles(first: 10) { nodes { id name number startsAt endsAt } } }"}

示例：

maton linear cycle list

Labels（标签）

列出 Labels

POST /linear/graphql
Content-Type: application/json

{"query": "{ issueLabels(first: 20) { nodes { id name color } } }"}

示例：

maton linear label list

Workflow States（工作流状态）

POST /linear/graphql
Content-Type: application/json

{"query": "{ workflowStates(first: 20) { nodes { id name type team { key } } } }"}

示例：

maton linear state list

Users（用户）

POST /linear/graphql
Content-Type: application/json

{"query": "{ users(first: 20) { nodes { id name email active } } }"}

示例：

maton linear user list

Comments（评论）

列出 Comments

POST /linear/graphql
Content-Type: application/json

{"query": "{ issue(id: \"ABC-123\") { comments(first: 10) { nodes { id body createdAt user { name } } } } }"}

示例：

maton linear comment list --issue ABC-123 -L 10

创建 Comment

POST /linear/graphql
Content-Type: application/json

{"query": "mutation { commentCreate(input: { issueId: \"ABC-123\", body: \"Looking into this\" }) { success comment { id body } } }"}

示例：

maton linear comment create --issue ABC-123 -b 'Looking into this'

分页

Linear 使用 Relay 风格的基于游标的分页机制。CLI 支持通过 --paginate 参数自动处理分页。

示例：

maton linear issue list -c ABC --paginate

代码示例

CLI

# 列出某团队的所有 issues
maton linear issue list -c ABC -L 10

# 查看指定 issue
maton linear issue view ABC-123

# 创建新 issue
maton linear issue create --team-id TEAM_ID -t 'Fix login'

# 添加评论
maton linear comment create --issue ABC-123 -b 'Looking into this'

JavaScript

const response = await fetch('https://api.maton.ai/linear/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `{ issues(first: 10) { nodes { id identifier title state { name } } } }`
  })
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    'https://api.maton.ai/linear/graphql',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'query': '{ issues(first: 10) { nodes { id identifier title state { name } } } }'
    }
)
data = response.json()

注意事项

Linear 仅提供 GraphQL API（无 REST API）
Issue 标识符（如 ABC-123）可直接用于 id 参数，替代 UUID
优先级（Priority）取值含义：0 = 无优先级，1 = 紧急，2 = 高，3 = 中，4 = 低
工作流状态类型（Workflow state types）：backlog、unstarted、started、completed、canceled
GraphQL Schema 支持内省（introspection），地址为 https://api.linear.app/graphql
使用 searchIssues(term: "...") 对 issues 执行全文检索
部分变更操作（mutation）（如删除、创建 labels/projects）可能需要额外的 OAuth 权限范围（scopes）。若您收到 scope 错误，请联系 Maton 支持团队（support@maton.ai），说明所需的具体操作/API 及使用场景

错误处理

状态码	含义
400	缺失 Linear 连接，或 GraphQL 校验失败
401	Maton API 密钥无效或未提供
403	当前 OAuth 权限范围不足以执行该操作
429	请求频率超限（Rate limited）
4xx/5xx	Linear API 返回的透传错误

GraphQL 错误统一返回在 errors 数组中：

{
  "errors": [
    {
      "message": "Invalid scope: `write` required",
      "extensions": {
        "type": "forbidden",
        "code": "FORBIDDEN",
        "statusCode": 403
      }
    }
  ]
}

故障排查：API 密钥问题

CLI：

检查当前认证状态：

maton whoami

通过列出连接验证 API 密钥有效性：

maton connection list

手动方式：

确认 MATON_API_KEY 环境变量已正确设置：

echo $MATON_API_KEY

通过列出连接验证 API 密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF