Linear

Linear

用于在 Linear 中管理问题、项目和团队的工具与工作流。

---

⚠️ 工具可用性（请先阅读）

此技能支持多个工具后端。请使用可用的后端：

1. MCP 工具（mcp__linear）——如果你的工具集中有此工具
2. Linear CLI（linear 命令）——始终可通过 Bash 使用
3. 辅助脚本——用于复杂操作

如果没有 MCP 工具，请通过 Bash 使用 Linear CLI：

# View an issue
linear issues view ENG-123

# Create an issue
linear issues create --title "Issue title" --description "Description"

# Update issue status (get state IDs first)
linear issues update ENG-123 -s "STATE_ID"

# Add a comment
linear issues comment add ENG-123 -m "Comment text"

# List issues
linear issues list

不要将“MCP 工具不可用”报告为阻碍因素——改用 CLI。

---

🔐 安全：Varlock 集成

重要：切勿在终端输出或 Claude 的上下文中暴露 API 密钥。

安全命令（始终使用）

# Validate LINEAR_API_KEY is set (masked output)
varlock load 2>&1 | grep LINEAR

# Run commands with secrets injected
varlock run -- npm run query -- "query { viewer { name } }"

# Check schema (safe - no values)
cat .env.schema | grep LINEAR

不安全命令（切勿使用）

# ❌ NEVER - exposes key to Claude's context
linear config show
echo $LINEAR_API_KEY
printenv | grep LINEAR
cat .env

新项目设置

1. 创建带有 @sensitive 注解的 .env.schema：

   # @type=string(startsWith=lin_api_) @required @sensitive
   LINEAR_API_KEY=
   

2. 将 LINEAR_API_KEY 添加到 .env（切勿提交此文件）

3. 配置 MCP 以使用环境变量：

   {
     "mcpServers": {
       "linear": {
         "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
       }
     }
   }
   

4. 在执行操作前使用 varlock load 进行验证

---

快速入门（首次使用）

1. 检查设置

运行设置检查，验证你的配置：

npm run setup

此操作会检查：

• 是否已设置有效的 LINEAR_API_KEY
• 是否已安装 @linear/sdk
• Linear CLI 是否可用（可选）
• MCP 配置（可选）

2. 获取 API 密钥（如有需要）

如果设置检查提示缺少 API 密钥：

1. 在浏览器中打开 Linear
2. 前往设置（齿轮图标）-> 安全与访问权限 -> 个人 API 密钥
3. 点击创建密钥并复制密钥（以 lin_api_ 开头）
4. 将其添加到环境中：

# Option A: Add to shell profile (~/.zshrc or ~/.bashrc)
export LINEAR_API_KEY="lin_api_your_key_here"

# Option B: Add to Claude Code environment
echo 'LINEAR_API_KEY=lin_api_your_key_here' >> ~/.claude/.env

# Then reload your shell or restart Claude Code

3. 测试连接

验证一切正常：

npm run query -- "query { viewer { name } }"

你应该会看到你在 Linear 中的姓名。

4. 常见操作

# Create issue in a project
npm run ops -- create-issue "Project" "Add rate limiting to auth endpoints" "Auth endpoints have no rate limiting, allowing brute-force attacks. Add configurable limits per endpoint with 429 responses when exceeded."

# Update issue status
npm run ops -- status Done ENG-123 ENG-124

# Edit issue title or description (fix typos, expand bodies)
npm run ops -- update-issue ENG-123 description --file /tmp/description.md --force
npm run ops -- update-issue ENG-123 title "Corrected title" --force
echo "New body from pipeline" | npm run ops -- update-issue ENG-123 description --stdin --force
npm run ops -- update-issue ENG-123 description "Short inline update" --strict=false

# Create sub-issue
npm run ops -- create-sub-issue ENG-100 "Sub-task" "Details"

# Update project status
npm run ops -- project-status "Phase 1" completed

# Show all commands
npm run ops -- help

完整参考请参阅项目管理命令。

---

问题创建检查清单（必需）

创建 Linear 问题时，务必完成以下三个步骤，即使用户没有提及。

1. 包含验收标准的详细描述。 每个问题描述都必须包含 ## Acceptance Criteria 部分，至少列出 2 项具体且可测试的检查项。请参阅 docs/issue-template.md，其中提供了规范模板和填写完整的示例。CLI 的 create-issue / create-sub-issue 会拒绝缺少此结构的描述；对于 MCP save_issue 调用方，请先使用 npm run ops -- validate-description --stdin 验证草稿（见下文）。如果用户只提供标题，请使用下方模板自行起草描述。

   详尽程度——默认使用完整的六部分模板。 除非用户的措辞明确表示要简短（“quick issue”、“one-liner”、“just the AC”、“brief”、“terse”、“minimum”、“short”），否则请按 Context → Problem → Proposal → Acceptance Criteria → Verification → Out of scope 组织正文。120 个字符 / 2 项是验证器的拒绝下限，并非评审者期望的标准。如果用户只给出标题，请根据完整模板起草详尽的正文；与其只交付下限内容，不如提出后续问题。对于细微改动（拼写错误修正、单行配置调整），如果验收标准本身显而易见且可测试，可以将 Problem 合并到 Context 中，并省略 Verification；这是有意精简，而非默认做法。

   ## Context
   **Title:** <title>
   
   <What is changing and why. 2-4 sentences. Link prior issues, docs, or incidents that motivate this.>
   
   ## Problem
   <What specifically is broken, missing, or insufficient today. Name the file, flow, or behavior.>
   
   ## Proposal
   <What you intend to do about it. High-level approach, not implementation line-by-line.>
   
   ## Acceptance Criteria
   - [ ] <Concrete, testable outcome>
   - [ ] <Concrete, testable outcome>
   
   ## Verification
   <How the AC will actually be checked. Manual steps, test command, or review instruction.>
   
   ## Out of Scope
   - <What this issue does NOT cover — redirect to the follow-up or explain why it's deferred>
   

   如需打印模板，请运行：npm run ops -- create-issue --template。完整示例请参阅 docs/issue-template.md。

2. 标签。 根据标签分类添加标签：

   • 恰好添加一个类型标签（feature、bug、refactor、chore、spike）
   • 添加 1-2 个领域标签（backend、frontend、security、infrastructure 等）
   • 视情况添加范围标签（blocked、breaking-change、tech-debt）

3. 项目分配。 根据上下文（当前冲刺、功能领域或用户指示）分配到合适的项目。如果无法确定项目，请询问用户。在批量处理 / 子 Agent 场景中，请使用父问题关联的项目或默认的计划项目。

更新现有问题时，应保留已有标签和项目——只添加缺少的标签，或更正分配错误的标签。

MCP 工具。 调用 mcp__linear__save_issue（或任何 MCP 问题创建工具）之前，请通过 validate-description --stdin 验证草稿描述；只有在命令以 0 退出时才调用 save_issue：

echo "$DRAFT_BODY" | npm run ops -- validate-description --stdin
# exit 0 → 可以安全调用 save_issue
# exit 5 → 修正描述；重新通过管道传入；再试一次

CLI 已对 create-issue / create-sub-issue 执行此检查。MCP 没有服务端检查——对于 MCP 路径，只有这项预检和事后运行的 npm run lint-issues 审计能够确保合规。对于保存在文件中的较长草稿，请使用 --file <path>，而非 --stdin。

详尽程度 ≠ 验证。 验证通过（退出码为 0）仅表示满足 120 个字符 / 2 项验收标准的下限。除非用户明确要求简短，否则请按完整的六部分模板（Context → Problem → Proposal → AC → Verification → Out of Scope）组织正文——参见上文第 1 条。

执行机制。 CLI + SDK 路径设有强制检查；MCP 路径依靠指示 + 审计。曾考虑使用拦截 save_issue 的 PreToolUse 钩子，但最终否决：它仅在 Claude Code 作为运行环境时触发，安装针对每位用户单独进行，且负载格式取决于执行框架的版本。请在本地或 CI 中运行 npm run lint-issues -- --since 24h，以事后发现指示层面的偏差。

---

项目规划工作流

请参阅问题创建检查清单——每个问题都必须包含描述、标签并分配项目。

从一开始就在正确的项目中创建问题

最佳实践：规划新阶段或计划时，在同一次规划会议中创建项目及其问题。避免先在一个兜底项目中创建问题，再将它们移到其他项目。

推荐工作流

1. 先创建项目：

   npm run ops -- create-project "Phase X: Feature Name" "My Initiative"
   

2. 将项目状态设为 Planned：

   npm run ops -- project-status "Phase X: Feature Name" planned
   

3. 直接在项目中创建问题（使用 --template 先打印规范模板，或通过 heredoc 传入多行描述）：

   # Print the template to seed your description
   npm run ops -- create-issue --template
   
   # Create the issue with a template-shaped description
   npm run ops -- create-issue "Phase X: Feature Name" "Parent task" "$(cat <<'EOF'
   ## Context
   Implement the core feature with integration tests and documentation.
   
   ## Acceptance Criteria
   - [ ] All API endpoints return correct responses
   - [ ] Test coverage >80% on new modules
   EOF
   )" --labels feature,backend
   
   npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "$(cat <<'EOF'
   ## Context
   Set up database schema and migrations for the new feature tables.
   
   ## Acceptance Criteria
   - [ ] Migration runs cleanly on a fresh database
   - [ ] Rollback migration restores prior schema
   EOF
   )"
   

4. 开始工作时更新项目状态：

   npm run ops -- project-status "Phase X: Feature Name" in-progress
   

为什么这很重要

• 可追溯性：问题从创建时起就与项目关联
• 指标：从第一天起准确跟踪项目进度
• 工作流：无需浪费时间在项目之间移动问题
• 组织管理：Linear 视图和筛选器能正常工作

应避免的反模式

❌ 先在“暂存”项目中创建问题，再将它们移到其他项目：

# Don't do this
create-issue "Phase 6A" "New feature"  # Wrong project
# Later: manually move to Phase X      # Extra work

---

项目管理命令

project-status

更新 Linear 中项目的状态。接受可映射到 Linear API 的易用术语。

npm run ops -- project-status <project-name> <state>

有效状态：

输入	描述	API 值
backlog	尚未开始	backlog
planned	已安排在未来进行	planned
in-progress	正在进行	started
paused	暂时搁置	paused
completed	已成功完成	completed
canceled	将不再进行	canceled

示例：

# Start working on a project
npm run ops -- project-status "Phase 8: MCP Decision Engine" in-progress

# Mark project complete
npm run ops -- project-status "Phase 8" completed

# Partial name matching works
npm run ops -- project-status "Phase 8" paused

link-initiative

将现有项目关联到某个计划。

npm run ops -- link-initiative <project-name> <initiative-name>

示例：

# Link a project to an initiative
npm run ops -- link-initiative "Phase 8: MCP Decision Engine" "Q1 Goals"

# Partial matching works
npm run ops -- link-initiative "Phase 8" "Q1 Goals"

unlink-initiative

将项目从某个计划中移除。

npm run ops -- unlink-initiative <project-name> <initiative-name>

示例：

# Remove incorrect link
npm run ops -- unlink-initiative "Phase 8" "Linear Skill"

# Clean up test links
npm run ops -- unlink-initiative "Test Project" "Q1 Goals"

错误处理：

• 如果项目未关联到指定计划，则返回错误
• 如果找不到项目或计划，则返回错误

完整的项目生命周期示例

# 1. Create project linked to initiative
npm run ops -- create-project "Phase 11: New Feature" "Q1 Goals"

# 2. Set state to planned
npm run ops -- project-status "Phase 11" planned

# 3. Create issues in the project
npm run ops -- create-issue "Phase 11" "Parent task" "Description"
npm run ops -- create-sub-issue ENG-XXX "Sub-task 1" "Details"

# 4. Start work - update to in-progress
npm run ops -- project-status "Phase 11" in-progress

# 5. Mark issues done
npm run ops -- status Done ENG-XXX ENG-YYY

# 6. Complete project
npm run ops -- project-status "Phase 11" completed

# 7. (Optional) Link to additional initiative
npm run ops -- link-initiative "Phase 11" "Q2 Goals"

---

工具选择

根据任务选择合适的工具：

优先级	工具	使用场景
1	MCP（官方服务）	大多数操作——首选
2	lin CLI	安装后可用于读取和更新状态的快速途径（可选）
3	辅助脚本	批量操作、标签分类体系、项目工作流
4	SDK 脚本	复杂操作（循环、条件语句）
5	GraphQL API	上述工具不支持的操作

lin CLI（可选快速途径）

如果已安装 lin Rust 二进制文件，该技能会自动使用它来执行：

• 更新问题状态（status、done、wip）
• 列出计划
• 搜索问题（search <query>）
• 列出问题（list-issues [--team X] [--state Y]）
• 用户信息（whoami）

lin 不可用时，所有操作都会静默回退到 SDK。

安装（可选）：

brew install aaronkwhite/tap/lin    # macOS (Homebrew)
cargo install lincli                # Any platform with Rust

禁用：设置 LINEAR_USE_LIN=0，即可在已安装 lin 的情况下跳过它。

MCP 服务配置

使用位于 mcp.linear.app 的官方 Linear MCP 服务：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.linear.app/sse"],
      "env": { "LINEAR_API_KEY": "your_api_key" }
    }
  }
}

WARNING：请勿使用已弃用的社区服务。详情请参阅 troubleshooting.md。

MCP 服务可靠性（官方服务）

操作	可靠性	备注
创建问题	✅ 高	完全支持
更新状态	✅ 高	直接使用 state: "Done"
列出/搜索问题	✅ 高	支持筛选器和查询
添加评论	✅ 高	支持使用问题 ID

快速更新状态

# Via MCP - use human-readable state names
update_issue with id="issue-uuid", state="Done"

# Via helper script (bulk operations)
node scripts/linear-helpers.mjs update-status Done 123 124 125

辅助脚本参考

有关辅助脚本的详细用法，请参阅 troubleshooting.md。

并行 Agent 执行

对于批量操作或后台执行，请使用 Linear-specialist 子 Agent：

Task({
  description: "Update Linear issues",
  prompt: "Mark ENG-101, ENG-102, ENG-103 as Done",
  subagent_type: "Linear-specialist"
})

适合使用 Linear-specialist（并行）的场景：

• 批量更新状态（3 个或更多议题）
• 更改项目状态
• 创建多个议题
• 代码更改后的同步操作

适合直接执行的场景：

• 查询单个议题
• 查看议题详情
• 快速检查状态
• 需要立即获得结果的操作

有关并行执行模式，请参阅 sync.md。

图片上传

步骤 1：从对话上下文中提取图片

在 Claude Code 中以内联方式分享的图片不会自动保存到磁盘 — 它们以 base64 格式保存在会话 JSONL 中。请使用提取脚本：

# Find the current session JSONL
ls -t ~/.claude/projects/<project-path>/*.jsonl | head -1

# Extract all inline images (saves to /tmp by default)
npm run extract-image -- <path-to-session.jsonl>

# Or specify a custom output directory
npm run extract-image -- <path-to-session.jsonl> ~/Desktop

图片将保存到 /tmp/shared-image-0.png、/tmp/shared-image-1.png 等路径。

务必先用 Read 工具验证提取的图片，再进行上传。

步骤 2：创建议题

# Standard approach
npm run ops -- create-issue "Project Name" "Issue title" "Description"

注意：如果需要指定特定团队，但 create-issue 选择了错误的团队，请使用 GraphQL 并显式指定 teamId：

# 获取项目所属团队
npm run query -- 'query { projects(filter: { name: { containsIgnoreCase: "PROJECT NAME" } }) { nodes { id name teams { nodes { id name key } } } } }'

# 显式指定 teamId 创建议题
npm run query -- 'mutation { issueCreate(input: { teamId: "TEAM_UUID", projectId: "PROJECT_UUID", title: "Issue title", description: "Description" }) { success issue { id identifier url } } }'

步骤 3：上传图片并附加到议题

npm run upload-image -- /tmp/shared-image-0.png ENG-123 "Optional comment text"

脚本将：

1. 将文件上传到 Linear 的 S3 存储
2. 在议题上发布评论，并以 Markdown 格式嵌入图片

支持的格式：PNG、JPG/JPEG、GIF、WebP、SVG、PDF

已知问题

问题	原因	修复方法
create-issue 选择了错误的团队	工作区中有多个团队	使用 GraphQL 并显式指定 teamId（参见步骤 2）
upload-image.ts 提示 "Issue not found"	附加图片前议题已被删除	确保议题存在
磁盘上找不到图片	以内联方式分享，而非作为文件分享	从会话 JSONL 中提取（步骤 1）

---

关键要求

议题 → 项目 → 计划

每个议题都必须关联到一个项目。每个项目都必须关联到一个计划。

实体	必须关联到	如果缺失
议题	项目	不会显示在项目看板中
项目	计划	不会显示在路线图中

有关完整的项目创建检查清单，请参阅 projects.md。

---

约定

议题状态

• 分配给我：设置 state: "Todo"
• 未分配：设置 state: "Backlog"

标签

使用基于领域的标签分类法 — 必需规则请参阅议题创建检查清单，完整分类法请参阅 docs/labels.md。

# Validate labels
npm run ops -- labels validate "feature,security"

# Suggest labels for issue
npm run ops -- labels suggest "Fix XSS vulnerability"

SDK 自动化脚本

仅在 MCP 工具不足时使用。 对于涉及循环、映射或批量更新的复杂操作，请使用 @linear/sdk 编写 TypeScript 脚本。请参阅 sdk.md，了解：

• 完整的脚本模式和模板
• 常见自动化示例（批量更新、筛选、报告）
• 工具选择标准

与多步骤操作的原始 GraphQL 相比，脚本提供完整的类型提示，也更容易调试。

GraphQL API

仅作为后备方案。 当 MCP 或 SDK 不支持所需操作时使用。

有关完整文档（包括以下内容），请参阅 api.md：

• 身份验证和设置
• 查询和变更示例
• 超时处理模式
• MCP 超时解决方法
• Shell 脚本兼容性

快速临时查询：

npm run query -- "query { viewer { name } }"

项目与计划

有关高级项目和计划管理模式，请参阅 projects.md。

快速参考 - 常用项目命令：

# Create project linked to initiative
npm run ops -- create-project "Phase X: Name" "My Initiative"

# Update project status
npm run ops -- project-status "Phase X" in-progress
npm run ops -- project-status "Phase X" completed

# Link/unlink projects to initiatives
npm run ops -- link-initiative "Phase X" "My Initiative"
npm run ops -- unlink-initiative "Phase X" "Old Initiative"

projects.md 中的主要主题：

• 项目创建检查清单（必需步骤）
• Content 与 Description 字段
• 创建前先发现
• 开始工作前验证代码库
• 子问题管理
• 项目状态更新
• 项目进展更新（状态报告）

---

同步模式（批量操作）

有关将代码更改批量同步到 Linear，请参阅 sync.md。

快速同步命令：

# Bulk update issues to Done
npm run ops -- status Done ENG-101 ENG-102 ENG-103

# Update project status
npm run ops -- project-status "My Project" completed

批量导入问题（bulk-create.ts）

从清单目录中，为同一团队创建多个问题，每个问题都有自己的 Markdown 描述和可选媒体文件。媒体通过 Linear 的 fileUpload API 上传，并嵌入描述中（图片内嵌，其他文件作为链接）。

适用场景：导入客户反馈、回顾行动项或 custdev 工单，其中每个问题都需要附上截图或录音。

LINEAR_API_KEY=xxx npx tsx scripts/bulk-create.ts \
  --manifest ./feedback-2026-04 \
  --config ./feedback-2026-04/config.json

先预览清单，不创建问题或上传文件：

npx tsx scripts/bulk-create.ts \
  --manifest ./feedback-2026-04 \
  --config ./feedback-2026-04/config.json \
  --dry-run

清单目录：

feedback-2026-04/
  tickets.json        # [{ key, title, priority?, labels?, files? }, ...]
  config.json         # { team_key, state_name?, default_priority? }
  desc-<key>.md       # description markdown per ticket (optional)
  <media files>       # referenced by each ticket's files[]

配置按名称而非 UUID 解析：

• team_key → 通过 findTeamByKey 查找（例如，"ENG"）
• state_name → 可选的工作流状态（例如，"Triage"）
• 工单 labels → 按团队解析标签名称，且不区分大小写；默认对未知名称发出警告，也可使用 --strict 使其失败

---

参考

文档	用途
api.md	GraphQL API 参考、超时处理
sdk.md	SDK 自动化模式
sync.md	批量同步模式
projects.md	项目与计划管理
troubleshooting.md	常见问题、MCP 调试
docs/labels.md	标签分类体系

外部资源： Linear MCP Documentation