linear

Linear

在此技能目录中使用 scripts/linear。它是一个小巧且无需依赖的封装工具，用于调用 Linear 的公共 GraphQL API，并非 MCP 服务。请使用各命令专属的 --help，不要在回复中复制完整的命令参考。

设置

1. 查看可用命令和相关名词：scripts/linear --help 和 scripts/linear issue --help。
2. 对于实时请求，在进程环境中恰好设置一个凭据。个人密钥使用 LINEAR_API_KEY，OAuth 使用 LINEAR_ACCESS_TOKEN。切勿打印、持久化或将任一凭据放入命令记录中。
3. 从有限范围的发现开始。读取操作默认使用 --limit 10；上限为 100。
4. 输出始终为 JSON：使用 --json 时为紧凑格式，不使用时为缩进格式。--dry-run 不会发起网络请求，只会预览操作。

命令概览

需求	命令
确认当前身份	scripts/linear whoami --json
发现团队	scripts/linear team list --limit 20 --json
列出团队的工作流状态	scripts/linear state list --team ENG --json
缩小已知问题集的范围	scripts/linear issue list --team ENG --state "In Progress" --json
按关键词查找问题	scripts/linear issue search "customer import" --json
读取一个已知问题	scripts/linear issue get ENG-42 --json
读取问题及其项目、周期、层级、评论和关联项	scripts/linear issue get ENG-42 --detail --json
创建问题并指定项目、父级、受派人、标签、状态或截止日期	scripts/linear issue create --team ENG --title "Fix login" --project "Platform" --parent ENG-1 --assignee "Ada Lovelace" --label bug --state "In Progress" --due 2026-08-31
更新问题的受派人、标签、截止日期或项目	scripts/linear issue update ENG-42 --assignee "Ada Lovelace" --label bug --remove-label p2 --due 2026-08-31 --project "Platform"
归档或取消归档问题	scripts/linear issue archive ENG-42 或 scripts/linear issue unarchive ENG-42
列出或读取项目	scripts/linear project list --team ENG --json 或 scripts/linear project get "Roadmap" --json
更新项目	scripts/linear project update "Roadmap" --description "Q3 plan" --status started
列出或读取周期	scripts/linear cycle list --team ENG --json 或 scripts/linear cycle get UUID --json
按关键词查找文档	scripts/linear document search roadmap --json
按 UUID、slug 或 URL 读取文档	scripts/linear document get REF --json
使用有文档记录但不受支持的 GraphQL 操作	scripts/linear raw 'query { viewer { id } }' --json

选择最精简的读取方式

情况	使用
已知问题标识符或 UUID	issue get
有关键词，但没有标识符	issue search 或 document search
需要带筛选条件的有限结果集	issue list、document list、project list 或 cycle list
需要查看某个团队的工作流状态	state list --team ENG
任务需要使用此精简 CLI 之外且有文档记录的操作	使用带有明确 GraphQL 查询的 raw

raw 是一种应急手段，不能替代常规命令。请让查询保持精简，并使用官方 GraphQL 文档确认字段名称和权限。

状态变更

执行操作前，确认目标、范围和回滚路径。无需确认即可进行只读发现。

对于 issue create、issue update、issue move、issue comment、issue archive、issue unarchive、 project update 和原始 GraphQL mutation：

1. 使用读取命令识别 issue、团队、项目或状态。
2. 向用户说明确切的预期变更和恢复路径。
3. 使用 --dry-run --json 运行同一命令；此操作不需要凭据或网络。
4. 获得确认后，使用 --confirm --json 重新运行。
5. 报告返回的标识符和结果，不要泄露凭据。

issue、project 和 cycle 列表中的 --team 筛选器要求使用准确的团队键。issue create 会在创建前解析团队键或准确名称；在添加评论、更新或归档前解析 issue 标识符；通过 UUID 或准确名称解析项目；通过准确名称或邮箱解析负责人；在 issue 所属团队中解析标签；并且仅在该 issue 所属团队中解析目标工作流状态。project update 会通过 UUID 或准确名称解析项目，并通过名称或类型解析状态。它不会猜测 ID、工作流状态、标签或项目状态。为安全的变更操作方法和 Linear 工作流语义加载 references/domain-and-workflows.md。

错误与恢复

• 缺少凭据：仅在命令会话期间导出一个受支持的环境变量，或使用 --dry-run 检查请求。
• GraphQL 错误：即使 HTTP 状态为 200，CLI 也会将 Linear 的首条有效错误消息写入 stderr 并以非零状态退出。请检查权限、准确的标识符以及文档中说明的字段可用性。
• 团队不明确：使用 team list 选择准确的键或名称；不要通过猜测 ID 重试。
• 状态查找失败：先使用 state list --team 列出团队的状态，然后使用准确名称。错误消息也会列出该 issue 所属团队可用的状态。
• 标签查找失败：错误消息会列出该 issue 所属团队可用的标签。请使用准确名称。
• 项目状态查找失败：错误消息会列出可用状态。请使用准确名称或类型（例如 planned、started、paused、completed、canceled）。
• 项目描述被拒绝：Linear 的 projectUpdate 不接受超过 255 个字符的描述。项目描述不得超过 255 个字符。
• 限制错误：选择 1 到 100 之间的值。CLI 不会自动分页。
• 速率限制或传输错误：等待后重试相同的有限范围读取。请遵循 Linear 的速率限制指南，不要添加重试循环。

参考资料

需要了解…	加载…
Linear 的数据模型、工作流语义、安全的变更操作方法	references/domain-and-workflows.md
GraphQL 端点、身份验证、筛选器、分页、错误、速率限制	references/graphql-contract.md
CLI、MCP、原始 GraphQL 与 Agent Session 的选择	references/integration-boundaries.md
来源 URL、访问日期、架构验证流程	references/sources.md

验证

更改后运行离线测试和仓库验证器：

python3 -m unittest linear/tests/test_linear.py
ruby scripts/validate-skills.rb

不适用场景

如果任务是在 Linear 内嵌入实时 Agent，而不是从终端操作 Linear，请使用 Linear 原生 MCP 或 agent-session/webhook API。