Linear工具箱(免费版)

本工具通过GraphQL API帮助用户与Linear交互，实现问题查询、项目管理、团队协作等核心功能。免费版聚焦日常查阅与基础操作需求。

概述

Linear是现代软件开发团队青睐的任务管理工具，其GraphQL API提供了强大的查询与操作能力。然而直接编写GraphQL查询对非技术用户门槛较高。本工具将常用操作封装为简洁的CLI命令，同时提供Python示例供集成使用，让Agent能够按需查询问题、管理项目、追踪团队进度。

免费版面向个人开发者与团队成员的日常使用，提供完整的查询能力与基础写入操作，不限制使用次数。

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：GraphQL、查询管理、Linear、支持问题查看与基、础操作、工具箱、是一款通过、API、交互的任务管理工、支持问题查询、项目浏览、团队管理与评论查、看等核心能力、周期与标签、查看当前用户与组、织信息、创建与更新问题、Use、when、需要项目管理、任务规划、进度跟踪、团队协作时使用、不适用于实际人员、绩效评估等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：开发者查询待办问题

开发者希望快速查看分配给自己的高优先级未完成问题。通过CLI命令按团队与状态过滤，获取问题列表与标识符，无需打开Linear网页端即可了解待办事项。

场景二：项目经理浏览项目状态

项目经理需要了解各项目的当前进展。通过项目列表命令获取所有项目及状态，针对关注的项目深入查看关联问题，评估是否需要调整资源分配。

场景三：团队成员添加协作评论

团队成员在审查问题时希望添加上下文评论。通过评论创建命令为指定问题添加说明，支持提及与其他成员，保持协作信息完整。

场景四：自动化脚本查询任务

开发者编写自动化脚本，通过Python示例调用GraphQL API查询待办任务，集成到每日站会提醒或个人看板中。

快速开始

本工具属于中等复杂度工具，预计120秒内可完成首次查询。

依赖详情

# 通过NPM安装
npm install -g @maton/cli
# ...
# 或通过Homebrew安装
brew install maton-ai/cli/maton

Step 2：配置认证

# 浏览器登录获取API密钥
maton login
# ...
# 或交互式输入API密钥
maton login --interactive
# ...
# 验证认证状态
maton whoami

Step 3：创建Linear连接

# 创建OAuth连接
maton connection create linear
# ...
# 打开返回的URL完成OAuth授权

Step 4：查询问题

# 列出团队的最近10个问题
maton linear issue list -c ABC -L 10
# ...
# 查看特定问题详情
maton linear issue view ABC-123

示例

环境变量配置

# 设置API密钥
export MATON_API_KEY="你的API密钥"

CLI命令速查

问题优先级说明

工作流状态类型

最佳实践

实践一：查询前先明确范围

Linear中问题数量可能庞大，直接全量查询会消耗大量资源。建议先通过team list确定团队key，再按团队过滤查询。使用-L参数限制返回数量，避免响应过大。

实践二：善用过滤器

问题列表支持按状态类型、标题关键词过滤。--state started只返回进行中的问题；--title bug只返回标题含"bug"的问题。合理使用过滤器能快速定位目标问题。

实践三：写入操作需确认

所有写入操作(创建/更新/删除)执行前应与用户确认目标资源与预期效果。特别是更新操作，先通过issue view确认当前状态，避免误操作覆盖重要信息。

实践四：多连接场景指定连接

若配置了多个Linear连接(如个人账户与企业账户)，执行操作时通过--connection参数指定目标连接，确保操作作用于正确的账户。

实践五：分页查询处理大数据集

对于大量问题，使用--paginate参数启用自动翻页。CLI基于游标分页自动获取全部结果，避免手动处理分页逻辑。

常见问题

Q1：提示401未授权怎么办？

A：检查API密钥是否正确配置。执行maton whoami验证认证状态。若密钥过期，重新执行maton login获取新密钥。

Q2：提示400缺少Linear连接？

A：说明尚未创建Linear OAuth连接。执行maton connection create linear创建连接，并打开返回的URL完成OAuth授权。

Q3：提示403权限不足？

A：某些操作(如删除、创建标签)需要额外的OAuth权限。联系API服务方支持团队，说明所需操作与使用场景，申请权限调整。

Q4：问题标识符ABC-123如何使用？

A：Linear的问题标识符(如ABC-123)可在命令中替代UUID使用。ABC是团队key，123是问题序号。maton linear issue view ABC-123即可查看对应问题。

已知限制

A：免费版不限制使用次数，但批量操作、Webhook集成与高级分析功能需使用专业版。

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

错误处理

免费版限制

本免费体验版限制以下高级功能：

• 批量操作(批量创建/更新/迁移问题)
• Webhook集成(事件订阅与自动化触发)
• 高级分析(效率分析、燃尽图、周期报告)
• 自定义GraphQL查询模板
• 多工作区并行管理
• 优先技术支持

解锁全部功能请使用专业版：linear-api-toolkit-pro

依赖说明

运行环境

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

第三方依赖

API Key 配置

• Maton API Key：通过maton login获取，存储在本地配置中
• 手动配置：也可通过MATON_API_KEY环境变量设置
• Linear OAuth：通过maton connection create linear创建OAuth连接
• 安全要求：禁止在SKILL.md或脚本中硬编码API密钥，禁止提交到版本控制

可用性分类

• 分类：MD+EXEC(纯Markdown指令，部分功能需要exec命令行执行能力)
• 说明：基于Markdown的AI Skill，通过自然语言指令驱动Agent执行Linear任务管理操作

输出格式

{
  "success": true,
  "data": {
    "result": "Linear工具箱(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "linear apikit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}