Linear

核心用法

Linear skill 通过 Maton 平台提供托管 OAuth 认证，允许用户以编程方式访问 Linear 的 GraphQL API。核心能力涵盖：

• Issue 管理：查询、筛选、搜索、创建、更新任务（支持按 team、state、priority、title 过滤）
• 项目管理：列举 projects、cycles、labels、workflow states
• 团队协作：查询 teams、users、comments，支持评论增删
• 多账户支持：通过 connection ID 区分多个 Linear 工作区

支持 CLI（maton linear 命令族）、Python、JavaScript 三种调用方式，所有请求经 api.maton.ai/linear/graphql 代理转发，自动注入 OAuth token。

显著优点

1. 托管 OAuth 简化认证：无需自行处理 Linear OAuth 流程，Maton 统一托管 token 刷新与权限管理
2. GraphQL 完整能力：暴露 Linear 原生 GraphQL 全部查询与变更能力，无功能阉割
3. 多语言示例丰富：提供 CLI、Python、JavaScript 完整代码片段，降低接入门槛
4. 细粒度权限控制：支持按 connection 隔离多账户，write 操作需用户显式确认
5. 自动分页支持：CLI 内置 --paginate 自动处理 Relay 风格游标分页

潜在缺点与局限性

• 网络依赖：必须能访问 api.maton.ai 和 api.linear.app，无法离线使用
• GraphQL 学习成本：需理解 Linear GraphQL schema 才能构建复杂查询
• OAuth 范围限制：部分操作（如删除 issue、创建 label/project）可能需额外 scope，需联系 Maton 支持开通
• 代理层延迟：请求经 Maton 代理转发，相比直连 Linear API 存在额外网络跳数
• 供应商锁定：深度依赖 Maton 平台，迁移至其他 OAuth 方案需重构认证逻辑

适合人群

• 需将 Linear 数据同步至内部 BI/数据仓库的工程师
• 构建自动化工作流（如基于 GitHub PR 自动创建 Linear issue）的 DevOps 团队
• 希望用 Python/Node.js 脚本批量管理任务的项目经理
• 多 Linear 工作区需统一管理的跨团队协作场景

常规风险

• Token 泄露：MATON_API_KEY 作为根凭证需妥善保管，泄露将导致所有托管连接被滥用
• 误操作风险：GraphQL mutation 可直接删除数据，建议生产环境先测试于 sandbox
• Rate limit：Linear API 存在速率限制，高频批量操作需实现退避重试
• Schema 变更：Linear GraphQL schema 可能演进，需关注 Apollo Studio 更新日志

核心用法

该 skill 为纯文档型 API 集成工具，通过 Maton 代理服务 桥接 Linear 官方 GraphQL API。用户需配置 MATON_API_KEY 环境变量，通过 CLI (maton linear) 或直接调用 https://api.maton.ai/linear/graphql 端点执行查询与变更操作。核心能力覆盖：

• Issues：列表查询、条件过滤、全文搜索、创建/更新/删除
• Projects & Teams：项目列表、团队信息及关联问题查看
• Cycles & Labels：迭代周期与标签管理
• Comments：问题评论的增删查
• Workflow States：工作流状态枚举

所有请求均为 POST 方法，采用 Relay 风格游标分页，CLI 支持 --paginate 自动翻页。

显著优点

1. 托管 OAuth 简化认证：无需直接处理 Linear OAuth 流程，Maton 代理自动注入令牌
2. 多连接管理：支持多 Linear 账号切换，通过 --connection 参数指定
3. GraphQL 完整能力：暴露 Linear 全量 GraphQL 查询能力，非阉割版 REST 封装
4. 多语言示例：提供 Bash、Python、JavaScript 完整调用示例，降低接入门槛
5. 写入保护机制：文档明确要求写操作前用户显式确认，降低误操作风险

潜在缺点与局限性

• 依赖 Maton 服务可用性：核心功能依赖 api.maton.ai 代理，若 Maton 服务故障则完全不可用
• T3 来源可信度：由个人开发者 byungkyu 维护，非 Linear 官方或顶级开源基金会背书
• 网络可达性要求：需稳定访问 Maton 及 Linear 官方 API，企业内网环境可能受限
• 无离线能力：纯云端代理模式，无法本地缓存或离线操作
• OAuth 范围限制：部分高级操作（如删除、创建标签/项目）可能需要额外授权，需联系 Maton 支持开通

适合人群

• 研发团队：需要批量查询/更新 Linear Issue 的开发者、项目经理
• 自动化运维：希望将 Linear 集成到 CI/CD 流水线或内部工单系统的工程师
• 数据分析师：需导出项目数据做离线分析的场景
• 多账号管理者：同时维护多个 Linear Workspace 的团队成员

常规风险

| 风险类别 | 说明 | 缓解建议 |

|---------|------|---------|

| API Key 泄露 | `MATON_API_KEY` 泄露可导致 Linear 数据被非法访问 | 存储于 shell 配置文件，定期轮换，避免日志打印 |

| 误操作数据 | GraphQL mutation 无二次确认，可能误删/误改 | 生产环境操作前先在测试项目验证，使用 `--connection` 明确指定目标 |

| 代理单点故障 | Maton 服务不可用导致完全中断 | 关键业务保留 Linear 官方 API 直连作为 fallback |

| 权限范围不足 | 部分操作因 OAuth scope 受限失败 | 提前规划所需权限，必要时联系 Maton 支持 |

| 网络中间人攻击 | 虽强制 TLS 1.2+，但仍需验证证书 | 企业环境部署证书固定策略 |