Linear

核心用法

本 Skill 提供通过 Maton 平台安全接入 Linear 官方 GraphQL API 的完整文档指南，支持查询和管理 Issues、Projects、Teams、Cycles、Labels、Comments 等核心资源。所有 API 请求经 Maton 代理转发至 api.linear.app，自动注入 OAuth Token，用户仅需配置 MATON_API_KEY 环境变量即可调用。

关键特性包括：

• GraphQL 原生支持：完整的查询、变更（Mutation）示例，涵盖分页、过滤、搜索等高级用法
• 多连接管理：支持通过 Maton-Connection 头部指定多个 Linear 账户
• 标准化错误处理：清晰的 HTTP 状态码与 GraphQL 错误格式说明

显著优点

1. 零代码安全风险：T-MD 纯文档分类，无可执行代码，天然免疫代码注入与供应链攻击
2. 可信商业背书：Maton 平台托管 OAuth，Linear 为知名项目管理 SaaS，双重信任保障
3. 权限最小化：默认只读访问，写入操作需显式用户确认，符合安全最佳实践
4. 开发友好：提供 Python、JavaScript 完整示例，Relay 风格分页文档详尽

潜在局限

• 依赖外部服务：必须持续信任 Maton 平台的 OAuth 代理服务可用性与安全性
• 功能边界：部分高级变更（如删除 Issue、创建 Labels/Projects）可能需额外 OAuth 授权，需联系支持开通
• 无离线能力：纯网络依赖型 Skill，无法本地缓存或离线使用
• 许可证未声明：当前版本未明确开源许可证，商业使用需自行确认合规性

适合人群

• 使用 Linear 作为项目管理工具的研发团队
• 需要将 AI Agent 与现有工单系统集成的自动化开发者
• 追求低代码、高安全性的企业用户（已通过 CLS-Certify A 级认证）

常规风险

• API 密钥泄露：MATON_API_KEY 如不慎提交至代码仓库，可能导致 Linear 账户被滥用
• OAuth 范围越权：用户需理解并监控 Maton 平台的 OAuth 授权范围变更
• 第三方代理风险：Maton 作为中间层，理论上可见 API 请求内容（虽经 TLS 加密传输）

核心用法

Linear Skill 是一个纯文档型工具，提供通过 Maton 代理服务访问 Linear API 的完整指南。用户需先获取 Maton API Key 并建立 OAuth 连接，然后通过 GraphQL 端点 https://api.maton.ai/linear/graphql 执行查询和操作。

关键步骤：
1. 认证配置：设置 MATON_API_KEY 环境变量，从 maton.ai/settings 获取
2. 建立连接：调用 /connections 端点创建 Linear OAuth 连接，通过返回 URL 完成授权
3. 执行 GraphQL 操作：使用 POST 请求发送 GraphQL 查询，支持 Issues、Projects、Teams、Cycles、Labels、Comments 等全量操作

典型操作示例：

• 查询当前用户：{ viewer { id name email } }
• 列取 Issues：{ issues(first: 10) { nodes { id identifier title state { name } } } }
• 创建 Issue：mutation { issueCreate(input: { teamId: "...", title: "..." }) { success issue { id } } }
• 搜索 Issues：{ searchIssues(first: 10, term: "keyword") { nodes { id title } } }

显著优点

1. 简化 OAuth 流程：Maton 代理管理 Linear OAuth 令牌，用户只需单一 API Key
2. 完整 GraphQL 支持：涵盖 Linear 全部核心资源（Issues、Projects、Teams、Cycles、Labels、Comments、Workflow States、Users）
3. 多连接管理：支持通过 Maton-Connection 头部切换多个 Linear 账户
4. 标识符友好：支持使用 MTN-527 风格标识符替代 UUID
5. Relay 分页：标准游标分页支持，便于处理大量数据

潜在缺点与局限性

1. 外部服务依赖：完全依赖 Maton 代理服务（api.maton.ai），若服务不可用则无法访问 Linear
2. 写操作需确认：所有创建、更新、删除操作需要显式用户批准，增加交互步骤
3. OAuth 范围限制：部分操作（如删除、创建 Labels/Projects）可能需要额外 OAuth 范围，需联系 Maton 支持
4. 无原生 REST：Linear 仅提供 GraphQL，对不熟悉 GraphQL 的用户有学习曲线
5. 网络要求：必须保持网络连接，无法离线使用

适合人群

• 开发团队：需要自动化 Linear 工作流、集成 CI/CD 流水线
• 项目经理：需要批量查询、分析项目进度和团队工作负载
• 数据分析师：需要导出 Linear 数据进行自定义报表和分析
• 已有 Maton 用户：已使用 Maton 其他集成的用户可复用 API Key

常规风险

| 风险类型 | 等级 | 说明 |

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

| API 密钥泄露 | 中 | MATON_API_KEY 泄露可能导致 Linear 数据被访问，需安全存储 |

| 服务可用性 | 中 | 依赖 Maton 代理服务，建议实现超时和重试机制 |

| 误操作数据 | 低 | 写操作需用户确认，但仍建议操作前备份关键数据 |

| 速率限制 | 低 | Linear API 存在速率限制，高频调用需实现退避策略 |

安全建议： 使用密钥管理系统存储 MATON_API_KEY，启用 TLS 证书验证，定期轮换密钥，监控异常 API 调用模式。