---
slug: "linear-api-toolkit"
name: "linear-api-toolkit"
version: 1.0.1
displayName: "Linear工具箱(专业版)"
summary: "全功能Linear管理工具，支持批量操作、Webhook集成、高级分析与自定义查询模板。Linear工具箱(专业版)是面向团队与项目管理者的全功能Linear交互工具，在免费版基础上新增批量"
summary_zh: "全功能Linear管理工具，支持批量操作、Webhook集成、高级分析与自定义查询模板。Linear工具箱(专业版)是面向团队与项目管理者的全功能Linear交互工具，在免费版基础上新增批量"
license: "MIT"
edition: "pro"
description: |-
  Linear工具箱(专业版)是面向团队与项目管理者的全功能Linear交互工具，在免费版基础上新增批量操作、Webhook集成、高级分析与自定义查询模板等高级能力。核心能力：
  - 完整的问题查询、项目管理与团队协作能力
  - 批量操作引擎，支持批量创建/更新/迁移
  - Webhook集成，事件订阅与自动化触发
  - 高级分析...
tags:
  - 集成工具
  - 项目管理
  - Linear
  - 专业版
  - API
  - 接口
  - 开发工具
  - webhook
  - linear
  - api
  - llm
  - string
tools:
  - read
  - exec
  - write
homepage: ""
category: "Development"
---
# Linear工具箱(专业版)

## 付费版专享能力

| 能力 | 免费版 | 付费版 |
|---|---|---|
| 基础功能 | 支持 | 支持 |
| Linear工具箱(专业版)功能Linear管理 | 不支持 | 支持 |
| Linear工具箱(专业版)高级分析与自定义查询 | 不支持 | 支持 |
| 代码静态分析与质量评分 | 不支持 | 支持 |
| 依赖漏洞检测与升级建议 | 不支持 | 支持 |
| 批量代码审查与报告生成 | 不支持 | 支持 |

## 核心能力

| 能力 | 说明 | 专业版增强 |
|:-----|:-----|:-----|
| 问题查询 | GraphQL查询与过滤 | 自定义查询模板 |
| 批量操作 | 批量创建/更新/迁移 | 并行引擎+检查点恢复 |
| Webhook集成 | 事件订阅 | 自动化触发与链式工作流 |
| 高级分析 | 效率分析 | 燃尽图+周期报告+趋势预测 |
| 多工作区 | 工作区管理 | 并行操作与快速切换 |
| 自定义模板 | GraphQL查询复用 | 变量引用与条件逻辑 |
| 优先支持 | SLA保障 | 专属技术支持通道 |
### 问题查询

针对问题,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应.
**输入**: 用户提供问题查询相关的配置参数、输入数据和处理选项.
**输出**: 返回问题查询的处理结果。- 验证返回数据的完整性和格式正确性
- 参考`问题查询`的配置文档进行参数调优
### 批量操作

针对批量,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应.
**输入**: 用户提供批量操作相关的配置参数、输入数据和处理选项.
**输出**: 返回批量操作的处理结果。- 验证返回数据的完整性和格式正确性
- 参考`批量操作`的配置文档进行参数调优
### Webhook集成

针对Webhook集成,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应.
**输入**: 用户提供Webhook集成相关的配置参数、输入数据和处理选项.
**输出**: 返回Webhook集成的处理结果。- 验证返回数据的完整性和格式正确性
- 参考`Webhook集成`的配置文档进行参数调优
#
## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 适用场景

### 场景一：迭代规划批量任务分配
项目经理在迭代规划会议后需要批量创建数十个问题并分配给团队成员。通过批量操作命令，从CSV文件导入问题列表，一次性创建所有问题并设置优先级与指派人，配合检查点恢复确保中途失败可续传.
### 场景二：自动化工作流集成
DevOps团队希望在代码合并到主分支时自动关闭对应Linear问题。通过Webhook集成监听Linear状态变更事件，结合CI/CD流水线实现代码合并与问题关闭的自动化联动，减少手动操作遗漏.
### 场景三：敏捷效率分析
敏捷教练希望评估团队的迭代效率。通过高级分析模块生成燃尽图，查看每个迭代的剩余工作量曲线；周期报告展示已完成问题的平均周期时间；趋势预测基于历史数据预估下个迭代的交付能力.
### 场景四：企业多工作区管理
大型企业拥有多个Linear工作区(如产品线A与产品线B)。专业版支持多工作区并行管理，通过`--workspace`参数切换上下文，批量查询跨工作区的问题统计，生成统一视图报告.
### 场景五：自定义查询模板复用
团队积累了常用的复杂GraphQL查询(如"查询本迭代所有阻塞问题及其依赖链")。通过自定义查询模板功能保存查询并参数化，团队成员通过模板名称即可执行，无需重复编写GraphQL.
## 使用流程

本工具属于复杂工具，预计180秒内可完成批量操作配置.
### 依赖说明

### 运行环境
1. **Agent平台**：支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
2. **操作系统**：Windows / macOS / Linux
3. **Node.js**：16+(用于运行CLI工具)

### 第三方依赖

| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---:|---:|---:|---:|
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
| Node.js | 运行时 | 必需 | nodejs.org官方下载 |
| Maton CLI | CLI工具 | 必需 | `npm install -g @maton/cli` |
| Linear GraphQL API | 外部API | 必需 | 需Linear账户与OAuth连接 |
| Webhook接收服务 | 外部系统 | 可选 | 用户自建Webhook端点 |

### API Key 配置
4. **Maton API Key**：通过`maton login`获取，存储在本地配置中
5. **手动配置**：也可通过`MATON_API_KEY`环境变量设置
6. **Linear OAuth**：通过`maton connection create linear`创建OAuth连接
7. **Webhook Secret**：通过`--secret`参数配置，用于签名验证
8. **安全要求**：禁止在SKILL.md或脚本中硬编码API密钥与Webhook密钥，禁止提交到版本控制
9. **团队部署**：建议为不同环境(开发/测试/生产)创建独立连接，避免操作混淆

### 可用性分类
10. **分类**：MD+EXEC()
11. **说明**：基于Markdown的AI Skill，通过自然语言指令驱动Agent执行Linear任务管理与团队效率分析

**结果验证**: 任务完成后,查看输出确认状态。成功时返回摘要和数据;失败时根据错误信息排查,参考恢复章节获取修复步骤.
## 输入格式

| 参数名 | 类型 | 必填 | 说明 |
|:---:|:---:|:---:|:---:|
| content | string | 否 | linear-api-toolkit处理的内容输入 |,  |
| content | string | 否 | linear-api-toolkit处理的内容输入 |, 可选值: json/text/markdown |
| style | string | 否 | 输出风格, 参考 `references/style.md` |

## 输出格式

```json
{
  "success": true,
  "data": {
    result: "toolkit 相关配置参数",
    result: "toolkit 相关配置参数",
    result: "toolkit 相关配置参数",
    "metadata": {
      "template_used": "reviewer",
      "word_count": 0,
      "style": "专业"
    }
  },
  "error": null
}
```

输出模板参考: `assets/output.json`

## 异常处理

| 现象 | 可能原因 | 解决方案 | 优先级 |
|:------|------:|:------|:------|
| 批量导入部分失败 | 个别数据格式错误 | 查看失败日志，修正后单独 | 中 |
| Webhook无响应 | 端点不可达或签名错误 | 检查端点可达性与密钥配置 | 高 |
| 燃尽图为空 | 无状态变更历史 | 确认问题通过API更新状态 | 中 |
| 模板执行失败 | 变量缺失或类型错误 | 检查变量声明与传值 | 中 |
| 多工作区混淆 | 未指定connection | 明确指定--connection参数 | 高 |
| 429速率限制 | 并行度过高 | 降低parallel值，启用retry | 高 |
| 检查点恢复失效 | 缓存被清理 | 重新执行全量操作 | 高 |
| 分析报告超时 | 数据量过大 | 缩小时间范围或分批分析 | 低 |

## 依赖说明(补充)

| 依赖项 | 类型 | 必需 | 说明 |
|---:|:---|---:|---:|
| LLM | 模型 | 是 | 需要LLM进行内容生成, 推荐GPT-4/智谱GLM-4/DeepSeek |
| API Key | 凭证 | 否 | 使用云端LLM时需要, 本地LLM不需要 |

**国内替代方案**:
- OpenAI GPT → 智谱GLM-4 / 百度文心一言 / 通义千问 / DeepSeek
- OpenAI Embedding → 智谱embedding-2 / 百度embedding

## 案例展示

### 批量导入CSV格式
```csv
title,description,priority,assignee,labels
修复登录页样式错误,登录按钮在Safari下错位,2,zhangsan,bug,frontend
新增导出PDF功能,支持将报告导出为PDF格式,3,lisi,feature,backend
优化查询性能,列表查询响应时间超过3秒,2,wangwu,performance,backend
```

### Webhook配置参数

| 参数 | 类型 | 必填 | 说明 |
|:------:|--------|:-------|:------:|
| --url | string | 是 | Webhook接收端点 |
| --events | string | 是 | 订阅事件类型，逗号分隔 |
| --secret | string | 是 | 签名验证密钥 |
| --active | bool | 否 | 是否启用，默认true |

### 分析报告类型

| 报告 | 说明 | 输出格式 |
|----|:--:|---:|
| burndown | 燃尽图，剩余工作量趋势 | HTML/PNG |
| cycle-time | 周期时间分析 | HTML/CSV |
| throughput | 吞吐量统计 | HTML/CSV |
| forecast | 交付能力预测 | HTML/JSON |
| velocity | 团队速率趋势 | HTML/PNG |

### 自定义模板变量

| 变量 | 说明 | 示例 |
|----|----|----|
| $team | 团队key | ABC |
| $cycle | 周期ID | 123 |
| $state | 状态类型 | started |
| $assignee | 指派人ID | user-001 |
| $label | 标签名 | bug |

## 常见问题

### Q1：批量导入中途中断怎么办？
A：专业版支持检查点恢复。重新执行相同命令并添加`--resume`参数，将从上次中断处继续，已成功创建的问题不会重复.
### Q2：Webhook未收到事件通知？
A：检查Webhook端点是否可公网访问，确认事件类型订阅正确。查看Linear管理后台的Webhook delivery日志，确认请求是否发出及响应状态码.
### Q3：燃尽图数据不准确？
A：燃尽图依赖问题的状态变更历史。若问题状态变更未记录时间戳(如手动批量修改)，会影响数据准确性。建议通过API规范更新状态，确保历史可追溯.
### Q4：自定义查询模板如何共享？
A：模板存储在本地配置中。可通过`template export`导出为JSON文件，团队成员通过`template import`导入。建议将模板文件纳入版本控制统一管理.
### Q5：多工作区如何切换？
A：通过`--connection`参数指定工作区对应的连接ID。也可使用`workspace switch <connection-id>`设置默认工作区，后续操作自动作用于该工作区.
### 错误恢复步骤
| 错误场景 | 原因 | 处理方式 |
|:-----|:-----|:-----|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | ，请求；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 已知限制
A：降低`--parallel`参数值(建议4)，并添加`--retry`参数启用自动重试。专业版在收到429后会自动退避并重试，无需手动干预.
### Q7：分析报告支持哪些时间范围？
A：支持`last-N-cycles`(最近N个迭代)、`date-range`(指定日期范围)、`all-time`(全部历史)三种范围。建议使用迭代范围，与敏捷节奏一致.
### Q8：是否支持Linear的AI功能？
A：专业版兼容Linear的AI助手功能。通过API创建的问题可利用Linear内置的AI进行自动分类与优先级建议，但AI功能的可用性取决于Linear订阅级别.
### Q9：如何获取优先技术支持？
A：专业版用户可通过专属支持通道提交工单，享受SLA保障的响应时效。批量操作与分析相关问题建议附带操作日志与参数配置.
### Q10：自定义模板中的变量如何传递？
A：执行模板时通过`--var`参数传递变量值。例如`template run blocked-issues --var team=ABC`。变量在GraphQL查询中以`$variable`形式引用，类型需在查询中声明.
## 错误处理

| 错误场景(续)| 原因 | 处理方式 |
|-----:|-----:|-----:|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 检查网络连接，重试请求；确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |

## 补充限制说明

- 需要LLM支持
- 数据处理能力受限于本地硬件资源
- 大数据量时分析性能可能显著下降