linearis-oss/linearis

# Linearis CLI 工具，用于 [Linear.app](https://linear.app)，专为 AI 代理优化。JSON 输出、智能 ID 解析、令牌高效的命令，以及“先发现后执行”的工作流，保持代理上下文最小化。也能很好地为偏好在命令行使用结构化数据的用户服务。 ## 为什么？ 官方的 Linear MCP 运行良好，但它连接时会占用约 13k 令牌——代理尚未执行任何操作。Linearis 采取不同方法：不是一次性暴露完整 API 表面，而是通过两层的用量系统让代理按需发现。`linearis usage` 提供约 200 令牌的概览，随后 `linearis usage` 为某一领域提供完整引用，约 300-500 令牌。一次典型的代理交互仅需约 500-700 令牌上下文，而非 13k。 代价是覆盖范围。MCP 暴露完整的 Linear API；Linearis 覆盖日常处理议题、评论、周期、文档和文件等关键操作。如果你需要管理自定义工作流、集成或工作区设置，MCP 是更好的选择。 **本项目解决我自己的痛点，** 满足我使用 Linear 的工作模式：我**确实**在命令行处理票据/议题和评论；我**不会**用它来管理项目或工作区等。效果因人而异。 ## 安装 ``` npm install -g linearis ``` 需要 Node.js >= 22。 ## 认证 ``` linearis auth login ``` 这会在浏览器中打开 Linear，引导你创建 API 密钥，并将令牌加密存储在 `~/.linearis/token`。 或者直接提供令牌： ``` # 通过 CLI 标志 linearis --api-token issues list # 通过环境变量 LINEAR_API_TOKEN= linearis issues list ``` 令牌解析顺序：`--api-token` 参数 > `LINEAR_API_TOKEN` 环境变量 > `~/.linearis/token` > `~/.linear_api_token`（已弃用）。 ## 用法 所有输出均为 JSON。可通过 `jq` 或类似工具进行格式化。 ``` # 发现 linearis usage # overview of all domains linearis issues usage # detailed usage for one domain ``` ### 快速开始 ``` # 发现可用命令 linearis usage # 深入一个域 linearis issues usage # 列出最近的问题 linearis issues list --limit 10 # 搜索问题 linearis issues search "authentication bug" # 创建问题 linearis issues create "Fix login flow" --team Platform --priority 2 # 添加评论 linearis comments create ENG-42 --body "Investigating this now" ``` 如需每个命令和参数的完整参考，请运行： ``` linearis usage ``` ## AI 代理集成 ### 代理如何使用 Linearis CLI 围绕“先发现后执行”的模式构建，与代理的工作方式相匹配： 1. **发现** — `linearis usage` 返回所有领域的紧凑概览（约 200 令牌）。代理读取一次以了解可用功能。 2. **深入** — `linearis usage` 提供某一领域的完整命令参考（约 300-500 令牌）。代理仅加载所需内容。 3. **执行** — 所有命令返回结构化 JSON。不解析人类可读的表格或文本。 这意味着代理永远不会将完整 API 表面加载到上下文中。它按需使用，一次只加载一个领域。 ### Linearis 与 MCP 的对比 | | Linearis | Linear MCP | |---|---|---| | 上下文成本 | 每次交互约 500-700 令牌 | 连接时约 13k 令牌 | | 覆盖范围 | 常见操作（议题、评论、周期、文档、文件） | 完整 Linear API | | 输出 | 通过标准输出返回 JSON | 工具调用响应 | | 设置 | `npm install -g linearis` + Bash 工具 | MCP 服务器连接 | 当令牌效率重要且你主要处理议题及相关数据时，使用 Linearis；当你需要完整 API 覆盖或紧密的工具调用集成时，使用 MCP。 ### 示例提示 ``` ## Linear（项目管理） Tool: `linearis` CLI via Bash. All output is JSON. Discovery: Run `linearis usage` once to see available domains. Run `linearis usage` for full command reference of a specific domain. Do NOT guess flags or subcommands -- check usage first. Ticket format: "ABC-123". Always reference tickets by their identifier. Workflow rules: - When creating a ticket, ask the user which project to assign it to if unclear. - For subtasks, inherit the parent ticket's project by default. - When a task in a ticket description changes status, update the description. - For progress beyond simple checkbox changes, add a comment instead of editing the description. File handling: `issues read` returns an `embeds` array with signed download URLs and expiration timestamps. Use `files download` to retrieve them. Use `files upload` to attach new files, then reference the returned URL in comments or descriptions. ``` 将此（或适用于你工作流的版本）添加到你的 `AGENTS.md` 或 `CLAUDE.md`，以便每个代理会话都能自动在上下文中包含它。 ## 贡献者 由 [contrib.rocks](https://contrib.rocks) 制作。 ## 许可证 MIT。参见 [LICENSE.md](LICENSE.md)。

标签：API安全, API客户端, GNU通用公共许可证, GraphQL, Homebrew安装, JSON输出, Linear.app, Linux 内核安全, LLM代理, MITM代理, Node.js, NPM包, OSV-Scalibr, Token优化, 发现式交互, 威胁情报, 工作流自动化, 开发者工具, 文档结构分析, 智能ID解析, 结构化数据, 自动化攻击, 认证管理, 轻量级上下文, 项目管理