Linearis：专为AI Agent优化的Linear CLI工具，解决MCP上下文负担

1. 项目概述：为AI Agent量身定制的Linear命令行工具

如果你和我一样，日常开发工作重度依赖Linear来管理任务和Bug，同时又热衷于探索AI Agent如何融入工作流，那你肯定遇到过那个令人头疼的“令牌税”问题。传统的工具，比如官方的Linear MCP服务器，一连接上就要吃掉你上下文的13k个令牌，这还没开始干活呢，宝贵的上下文窗口就被占去了一大块。Linearis这个项目，就是为解决这个痛点而生的。它是一个专门为命令行和AI Agent优化的Linear客户端，核心设计哲学是“按需发现，按量付费”——不是一股脑地把整个API都塞给Agent，而是让它像人类一样，先看看有什么能用的，再深入去用，把每次交互的上下文成本从13k压缩到500-700个令牌。

简单来说，Linearis是一个Node.js写的命令行工具，它通过GraphQL与Linear后端通信，但把所有响应都规整成干净的JSON。这不仅仅是为了机器可读，对于我这种喜欢在终端里用jq、fx处理数据的人来说，结构化输出简直是福音。它覆盖了日常工作中最高频的操作：Issue（任务/缺陷）的查看、创建、搜索、更新；评论的增删改查；以及附件文件的上传下载。对于那些需要管理完整项目、自定义工作流或团队设置的高级场景，官方的MCP可能更合适。但如果你80%的时间都在和具体的任务卡片打交道，Linearis的轻量和高效会让你爱不释手。

2. 核心设计思路：为什么“发现-执行”模式是Agent的福音

2.1 传统MCP的上下文负担问题

在深入Linearis之前，我们需要理解它要解决的根本问题。像Linear MCP这样的模型上下文协议工具，其工作模式是“全量暴露”。一旦连接建立，它会将工具的所有能力描述（包括每个功能的名称、参数、说明）一次性加载到AI模型的上下文中。对于Linear这样功能丰富的平台，这个描述文件可能非常庞大。根据项目文档，这会导致约13k令牌的固定开销。

这13k令牌意味着什么？在目前主流的大语言模型（如Claude 3.5 Sonnet, GPT-4o）的上下文窗口中，这可能是5%到10%的固定占用。对于一次需要处理复杂、多步骤任务的对话，每一次工具调用都可能需要携带这部分“元数据”，严重挤占了用于实际任务描述、历史对话和思考过程的空间。这就像你每次去工具箱拿螺丝刀，都得先把整个工具房的目录背一遍，效率极低。

2.2 Linearis的两级发现机制

Linearis采用了截然不同的“发现-执行”范式。这个设计模拟了人类使用命令行工具的过程：我们通常不会记住git所有子命令的每个参数，而是先用git --help看概览，再用git commit --help看具体用法。

1. 一级发现 (linearis usage): 这个命令返回一个高度压缩的概览，列出所有可用的“领域”，如issues、comments、cycles、files等。它的输出经过精心设计，只包含最核心的信息，体积控制在200个令牌左右。Agent在会话初期只需执行一次，就能建立起对工具能力的整体认知地图。

2. 二级发现 (linearis <domain> usage): 当Agent确定要操作某个具体领域（比如要处理issues）时，它再执行这个命令。此时，它会获得该领域下所有可用命令、参数、选项的完整参考手册。这个手册的详细程度足以让Agent正确构造命令，但因为它只聚焦于一个领域，所以体积仍然可控，大约在300-500个令牌。

3. 执行: 获得具体用法后，Agent就可以构造并执行具体的命令，如linearis issues list --limit 5 --state “in_progress”。所有执行结果都是结构化的JSON。

这种模式的精髓在于延迟加载和上下文隔离。Agent不需要在开始时就为所有可能用不到的功能支付令牌成本。它只为当前任务所需的最小知识集付费。在一次典型的“查找Bug -> 创建子任务 -> 添加评论”的交互中，Agent可能只需要加载issues和comments两个领域的用法说明，总成本远低于一次性加载全部API。

2.3 结构化JSON输出的深层价值

为什么坚持JSON输出？这不仅仅是“机器友好”。在AI Agent的工作流中，可预测、可解析的输出格式至关重要。

• 消除歧义: 人类可读的表格或自由文本（如“Successfully created issue ABC-123”）对模型来说存在解析风险。一个句号的位置、一个换行都可能让模型提取信息失败。而JSON具有严格的语法，模型可以可靠地使用类似response[“id”]或response.issue.identifier的路径来获取数据。
• 支持复杂操作: Linearis的许多命令返回的数据结构可以直接作为另一个命令的输入。例如，issues list返回的Issue对象中包含了完整的id、identifier、title等字段。当需要为其中某个Issue添加评论时，Agent可以直接使用response[0].identifier，而不需要从一串文本中做正则表达式匹配。
• 便于流水线处理: 对于既使用Agent也手动操作的用户，JSON输出可以轻松地与jq结合，进行过滤、转换和格式化，实现强大的命令行自动化。

注意: 虽然JSON是主要输出格式，但在设计给Agent的提示词（Prompt）时，应明确告知它这一特性，并指导它如何利用。例如，可以提示Agent：“所有linearis命令的结果都是JSON格式，你可以直接解析其中的字段，如id、identifier、url等。”

3. 安装、配置与核心命令详解

3.1 环境准备与安装

Linearis基于Node.js，因此首先需要确保你的开发环境已安装Node.js 22或更高版本。你可以通过node --version来检查。如果版本过低，建议使用nvm（Node Version Manager）来管理多个Node版本，这是处理不同项目依赖的行业最佳实践。

# 使用nvm安装并切换到Node.js 22 nvm install 22 nvm use 22

安装Linearis本身非常简单，使用npm的全局安装即可：

npm install -g linearis

这里使用-g（全局）标志是因为Linearis是一个命令行工具，我们希望在任何目录下都能直接调用linearis命令。安装完成后，可以通过linearis --version来验证安装是否成功。

3.2 认证机制与令牌管理

与Linear API交互需要一个访问令牌。Linearis提供了多种灵活且安全的令牌管理方式，其优先级顺序如下：

1. 命令行参数 (--api-token): 最高优先级，适用于临时测试或脚本中。
2. 环境变量 (LINEAR_API_TOKEN): 在Shell会话或容器环境中非常方便。
3. 本地加密文件 (~/.linearis/token): 最推荐的个人日常使用方式。
4. 旧版文件 (~/.linear_api_token): 为了兼容性保留，已弃用。

对于大多数用户，最方便的方式是使用内置的登录命令：

linearis auth login

执行这个命令后，它会自动打开你的默认浏览器，跳转到Linear的API密钥创建页面。整个过程是OAuth式的引导流程，你只需要在浏览器中确认授权，Linear就会生成一个专属于Linearis的API密钥。关键点来了：Linearis不会让你手动复制粘贴这个密钥。它会在后台通过一个本地临时服务器，安全地接收到这个令牌，并立即使用操作系统提供的加密机制（如macOS的Keychain，Linux的libsecret，Windows的Credential Vault）将其加密后存储在~/.linearis/token文件中。这个过程极大降低了令牌因误操作而泄露的风险。

实操心得: 如果你在多台机器或开发容器中使用Linearis，手动设置环境变量可能是更佳选择。你可以在你的Shell配置文件（如.zshrc或.bashrc）中导出LINEAR_API_TOKEN，或者使用direnv这样的工具在项目目录级管理环境变量。切勿将令牌硬编码在脚本或提交到版本库中。

3.3 命令体系与发现之旅

安装并认证后，你就可以开始探索了。正如之前提到的，所有旅程都从usage开始。

第一步：全局概览运行linearis usage。你会看到一个简洁的列表，类似下面这样（经过格式化）：

{ “domains”: [ { “name”: “issues”, “description”: “Create, list, search, update, and manage issues.” }, { “name”: “comments”, “description”: “Manage comments on issues.” }, { “name”: “files”, “description”: “Upload and download file attachments.” }, { “name”: “cycles”, “description”: “View and manage cycles (sprints).” } // ... 其他领域 ] }

这个输出就是给AI Agent的第一张地图。它很小，但指明了所有可能的方向。

第二步：深入特定领域假设你要处理任务。接下来运行linearis issues usage。这时你会得到一份详细的“说明书”，包含list、create、search、read、update等子命令，以及每个子命令可用的参数（如--team、--state、--assignee）、选项（如--limit、--json）和示例。这个文档足够详细，让Agent能正确构造出任何有效的issues相关命令。

核心命令示例解析:

• 列出任务:linearis issues list --limit 10 --state “in_progress” --order “updated”

  • --limit: 控制返回数量，保护上下文不被刷屏。
  • --state: 筛选特定状态的任务（如backlog,in_progress,done）。
  • --order: 按created或updated时间排序。获取最新动态时非常有用。

• 智能搜索:linearis issues search “authentication bug” --team “Platform” --mine

  • search命令功能强大，支持Linear的搜索语法。
  • --mine标志是一个快捷方式，只搜索分配给当前用户的任务，在每日站会前快速查看自己的工作项时极其方便。

• 创建任务:linearis issues create “修复登录流程中的竞态条件” --team “Platform” --priority 2 --description “在并发请求下，令牌刷新机制可能导致…”

  • 创建任务时，--team参数是必须的，因为Linear中任务必须归属于某个团队。
  • --priority对应Linear的优先级数字（0-无, 1-紧急, 2-高, 3-中, 4-低）。在提示Agent时，需要明确这个映射关系。
  • --description支持多行文本，可以直接在命令行中用引号包裹，或者省略此参数，工具会进入交互式编辑器模式（由$EDITOR环境变量指定）。

• 读取任务详情与附件:linearis issues read ENG-123

  • 这个命令不仅返回任务的基本信息，还会返回一个embeds数组。如果任务描述中粘贴了Linear附件图片或文件，这里会包含它们的带签名下载URL和过期时间。这是后续使用files download命令获取文件的关键。

4. AI Agent集成实战与提示词工程

将Linearis集成到AI Agent工作流中，不仅仅是安装一个工具，更重要的是设计有效的提示词（Prompt）来引导Agent正确地使用它。下面是一个深度集成的实战指南。

4.1 构建Agent的“Linear操作手册”

你需要在你的Agent系统提示词（例如CLAUDE.md、AGENTS.md或自定义指令）中添加一个专门的章节。这个章节应该清晰、无歧义地定义工作流规则。以下是一个比官方示例更详细、更可操作的模板：

## 🛠️ Linear 项目管理工具指南 **工具调用方式**: 通过Bash执行 `linearis` 命令行工具。**所有输出均为JSON格式**，请直接解析JSON对象获取结果。 **核心使用原则**: 1. **禁止猜测命令**：绝对不要猜测子命令或参数的名称。必须遵循“发现-执行”流程。 2. **先发现，后操作**： * 如果不确定可用命令，首先运行 `linearis usage` 获取领域列表。 * 确定领域（如 `issues`）后，运行 `linearis issues usage` 获取该领域下所有命令的详细参数。 3. **任务标识符格式**：Linear任务的标准格式为 `“团队键-序号”`，例如 `ENG-123`、`PLAT-42`。在命令中引用任务时，**必须使用此格式**。 **具体工作流规则**: - **任务创建**: - 必须指定 `--team` 参数。如果用户未明确说明团队，**你必须主动询问**：“请问这个任务应该归属哪个团队（如 Platform, Web, Mobile）？” - 优先级使用 `--priority` 参数，数值对应：`0`（无）、`1`（紧急）、`2`（高）、`3`（中）、`4`（低）。 - **子任务处理**: - 创建子任务时，默认应继承父任务所属的团队。在 `linearis issues create` 命令中，使用父任务的团队键作为 `--team` 参数值。 - 建议在子任务描述中通过 `Parent: ABC-123` 的形式建立关联。 - **任务状态与内容更新**: - 如果任务描述中的某个清单项（Checklist）状态发生变化（如从 `[ ]` 变为 `[x]`），**直接更新整个任务描述** (`linearis issues update ABC-123 --description “新的描述内容”`)。 - 如果进展无法用清单项表示（如代码提交、测试结果、讨论要点），**请添加评论** (`linearis comments create ABC-123 --body “进展说明…”`) 而非修改描述。 - **文件附件处理**: - 当需要获取任务中的附件时： 1. 先运行 `linearis issues read ABC-123`。 2. 从返回的JSON的 `embeds` 数组中，找到文件的 `url` 和 `expiresAt`。 3. 使用 `linearis files download <signed-url>` 命令将文件下载到本地临时位置进行分析。 - 当需要上传新文件时： 1. 使用 `linearis files upload /path/to/file.pdf` 上传文件。 2. 命令会返回一个JSON，其中包含 `url` 字段。这是一个指向Linear存储的临时URL。 3. 你可以将这个URL插入到任务描述或评论中，Linear会将其自动渲染为附件。

4.2 实际交互场景模拟

让我们模拟一个Agent处理用户请求的完整过程，看看这个提示词如何生效：

用户请求: “帮我查一下Platform团队里我名下还在进行中的高优先级任务，然后给最新的那个任务添加一条评论，说‘正在联系运维排查底层服务’。”

Agent的思考与执行过程:

1. 理解意图: 用户请求涉及两个操作：1) 查询任务列表；2) 创建评论。两者都属于issues和comments领域。
2. 发现阶段 (如果需要): 假设Agent的长期记忆中已有linearis usage的结果，知道issues和comments是可用领域。但它不确定list命令的具体筛选参数。根据提示词规则，它不能猜测。它会先执行：

   linearis issues usage

   从返回的用法说明中，它会学习到list命令有--state、--priority、--assignee、--mine等参数。
3. 执行查询:

   linearis issues list --team “Platform” --mine --state “in_progress” --priority 2 --limit 1 --order “updated”

   • --mine: 自动过滤出分配给当前API令牌所属用户的任务。
   • --limit 1 --order “updated”: 获取最新更新的那一个。
4. 解析结果: 命令返回JSON。Agent解析它，提取出第一个任务的identifier，例如PLAT-567。
5. 执行评论操作:

   linearis comments create PLAT-567 --body “正在联系运维排查底层服务。”

6. 反馈结果: Agent向用户报告：“已找到任务PLAT-567，并已添加评论‘正在联系运维排查底层服务’。”

整个过程中，Agent只在必要时加载了issues领域的详细用法（约500令牌），加上两次命令的输入输出，总上下文消耗远低于传统MCP的固定开销。这种效率提升在复杂、多轮次的对话中尤为明显。

5. 高级用法、脚本集成与生态结合

Linearis的价值不仅在于与AI Agent交互，它本身就是一个强大的命令行生产力工具。下面介绍几种进阶用法。

5.1 与Shell脚本和自动化流水线集成

由于其纯JSON输出，Linearis可以无缝嵌入Shell脚本，结合jq实现强大的自动化。

示例：生成每日个人工作报告假设你每天下班前想快速汇总自己当天完成的任务，可以写一个脚本：

#!/bin/bash # daily_report.sh TODAY=$(date -u +“%Y-%m-%dT00:00:00.000Z”) # 获取今天完成的、由我创建或完成的任务 linearis issues list \ --mine \ --state “done” \ --completed-after “$TODAY” \ --json | \ jq -r ‘.[] | “- [\(.identifier)] \(.title) (团队: \(.team.name))”’

这个脚本会列出所有当天标记为完成、且与我相关的任务，并格式化为简单的Markdown列表。你可以将其加入Cron定时任务，或绑定到一个Alias上。

示例：批量更新任务状态冲刺（Sprint）结束时，可能需要将某个周期内所有未完成的任务移入下一个周期或打上特定标签。

#!/bin/bash # move_unfinished_issues.sh CYCLE_ID=“last-cycle-uuid” # 通过 linearis cycles list 获取 NEW_CYCLE_ID=“next-cycle-uuid” LABEL_ID=“carry-over-label-uuid” # 通过 linearis labels list 获取 # 1. 获取上个周期所有未关闭的任务ID ISSUE_IDS=$(linearis issues list --cycle $CYCLE_ID --state “backlog,in_progress” --json | jq -r ‘.[].id’) # 2. 遍历每个ID，更新周期和标签 for id in $ISSUE_IDS; do linearis issues update $id --cycle $NEW_CYCLE_ID --label-add $LABEL_ID echo “Updated issue $id” done

重要提示: 在对大量任务进行批量操作前，务必先在一个测试任务上验证命令效果。可以考虑在命令中添加--dry-run标志（如果支持）或先使用--limit 1进行测试。

5.2 与Obsidian、Logseq等知识库联动

如果你使用Obsidian、Logseq等本地优先的知识库管理项目笔记，Linearis可以成为连接任务管理和知识沉淀的桥梁。

你可以创建一个Shell脚本或使用Obsidian的Shell命令插件，当你完成一个Linear任务后，自动在知识库中创建或更新对应的笔记。

#!/bin/bash # create_note_from_issue.sh ISSUE_IDENTIFIER=$1 NOTE_DIR=“$HOME/Obsidian Vault/Projects/Linear” ISSUE_JSON=$(linearis issues read $ISSUE_IDENTIFIER --json) TITLE=$(echo $ISSUE_JSON | jq -r ‘.title’) DESCRIPTION=$(echo $ISSUE_JSON | jq -r ‘.description’) URL=$(echo $ISSUE_JSON | jq -r ‘.url’) STATUS=$(echo $ISSUE_JSON | jq -r ‘.state.name’) NOTE_CONTENT=“# $TITLE **状态:** $STATUS **链接:** [$ISSUE_IDENTIFIER]($URL) ## 描述 $DESCRIPTION ## 工作记录 - $(date +“%Y-%m-%d”): 任务完成，关闭。 “ echo “$NOTE_CONTENT” > “$NOTE_DIR/${ISSUE_IDENTIFIER}.md”

这个脚本读取一个Linear任务的详细信息，并生成一个结构化的Markdown文件，包含任务标题、状态、链接、描述，并预留了工作记录区域。你可以在此基础上扩展，自动提取评论、附件链接等信息。

5.3 性能考量与最佳实践

虽然Linearis很轻量，但在高频或脚本化使用时仍需注意：

• 速率限制: Linear API有速率限制。虽然Linearis做了一些智能合并查询的优化，但在脚本中快速循环调用linearis命令时，仍有触限风险。对于批量操作，建议在循环中添加sleep间隔（如sleep 0.5）。
• 令牌缓存:linearis auth login加密存储的令牌是持久化的。但在某些安全策略严格的CI/CD环境中，可能无法使用这种机制。此时，应使用LINEAR_API_TOKEN环境变量，并确保该变量在流水线中通过安全的方式注入（如GitHub Secrets, GitLab CI Variables）。
• 错误处理: 在脚本中调用linearis时，务必检查命令的退出状态码（$?）。非零状态码通常意味着错误（如认证失败、网络问题、参数错误）。JSON错误信息通常包含在输出中，可以用jq来提取。

6. 常见问题排查与实战技巧

在实际使用中，你可能会遇到一些问题。下面是一些常见情况的排查思路和解决方案。

6.1 认证与连接问题

6.2 命令使用与输出解析问题

6.3 与AI Agent协作时的典型问题

6.4 个人实战技巧分享

• 别名（Alias）是效率倍增器: 在你的.zshrc或.bashrc中为常用命令设置别名。例如：

  alias lils=‘linearis issues list --mine --state “in_progress” | jq’ alias lilsd=‘linearis issues list --mine --state “done” --completed-after “$(date -u -v-1d +”%Y-%m-%dT00:00:00.000Z”)” | jq’

  第一个别名lils列出我所有进行中的任务。第二个别名lilsd列出我昨天完成的任务（macOS日期语法，Linux下需调整）。
• 善用--json标志进行深度处理: 大多数list命令默认输出是精简的JSON。如果你需要完整的、包含所有字段的对象（例如为了提取某个特定字段用于后续脚本），可以加上--json标志来获取完整的GraphQL响应结构。
• 组合命令实现复杂查询: Linear的搜索语法很强大，但有时在命令行中组合list的筛选条件更直观。例如，想找“我创建的、高优先级的、且标题包含‘重构’的任务”：linearis issues list --mine --creator @me --priority 2 --search “重构”。注意@me是一个特殊值，指代当前用户。
• 调试小技巧: 如果某个命令行为不符合预期，可以先加上--verbose或--debug标志（如果工具支持）查看底层请求。或者，直接使用--dry-run看看将要执行的GraphQL查询是什么，这有助于理解工具是如何将命令行参数转换为API调用的。

Linearis的精妙之处在于它在一个看似简单的CLI工具中，平衡了人类使用者的便捷性和AI Agent的效率需求。它没有试图取代官方的MCP，而是在一个更聚焦的场景下，提供了一个优化到极致的解决方案。对于每天泡在终端里、同时又在积极探索AI辅助编程的开发者来说，它无疑是一件趁手的新兵器。它的设计理念——通过良好的约束和设计来降低认知负荷和资源消耗——也值得我们在构建其他AI原生工具时借鉴。