SuperAPI AI 工具集

linear-sdk-scripting

编程与开发

查看项目

更新于 11-03 00:41

技能介绍

用途

linear-sdk-scripting 用于通过官方 TypeScript SDK(@linear/sdk)操作 Linear:编写一次性的 Node 脚本并执行,以读取、创建、更新、搜索问题,以及处理项目、评论、团队、周期、标签等。它可替代 Linear MCP 服务器——MCP 能做的事(读取问题、创建问题、评论、修改状态、查询团队/项目/周期)都可通过调用 SDK 方法完成。

主要能力

  • 读取:当前用户(viewer)、问题列表(支持过滤,如按状态类型)、单条问题(按 UUID)、团队、用户、项目。
  • 写入:创建问题、更新问题(如改标题、改指派人)、添加评论;变更操作返回包含 success 和实体的 payload,实体访问器通常是 Promise。
  • 分页与关系遍历由 SDK 规范化,方法和输入名称可预测;需要未知字段或过滤条件时,查阅 references/docs-index.md 并抓取对应文档页面,而不是猜测。

使用方式

  1. 准备个人 API 密钥:SDK 从 LINEAR_API_KEY 环境变量读取密钥。不要通过预先检查该变量是否为空来判断密钥是否存在——脚本运行在非交互、非登录 shell 中,不会自动加载 ~/.zshrc 等配置文件,变量为空不代表密钥未配置。真正缺失时,引导用户访问 https://linear.app/settings/account/security 创建密钥(以 lin_api_ 开头),可先执行 export LINEAR_API_KEY="lin_api_REPLACE_ME" 载入当前会话;是否持久化到 shell 配置文件必须事先征得用户明确同意,且不得回显或提交密钥。
  2. 安装 SDK:保持一个专用工作目录,含独立 node_modules,要求 Node 18 及以上。一次性初始化后复用:
LINEAR_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/linear-sdk-scripting"
mkdir -p "$LINEAR_DIR"
cd "$LINEAR_DIR"
[ -f package.json ] || npm init -y >/dev/null
npm ls @linear/sdk >/dev/null 2>&1 || npm install @linear/sdk
  1. 执行模式:每个任务将 .mjs 脚本写入工作目录,先 source 常见 shell 配置文件以加载已持久化的密钥,再用 node 运行。.mjs 支持顶层 await,无需 async 包装;需要后续解析时输出 JSON 字符串。
LINEAR_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/linear-sdk-scripting"
cat > "$LINEAR_DIR/task.mjs" <<'EOF'
import { LinearClient } from "@linear/sdk"

const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY })

const me = await linear.viewer
const myIssues = await me.assignedIssues({ first: 20 })
for (const issue of myIssues.nodes) {
  console.log(`${issue.identifier}  ${issue.title}`)
}
EOF
for f in ~/.zshenv ~/.zshrc ~/.zprofile ~/.profile ~/.bashrc ~/.bash_profile; do
  [ -f "$f" ] && source "$f"
done
node "$LINEAR_DIR/task.mjs"
  1. 处理认证失败:密钥缺失或无效表现为 AuthenticationLinearError(状态 401)。检测到后先 source 配置文件并重试一次;仍失败才视为密钥确实缺失或无效,再与用户走密钥设置流程。脚本应主动尝试执行,而不是预先以环境变量为空为门槛。

适用场景

需要在 Linear 中批量或自动化读写数据、替代 MCP 服务器、以可复现脚本完成问题查询与状态流转、评论、项目/团队/周期查询等任务。

限制与注意事项

  • 必须从工作目录运行脚本(或指向其中的脚本),使 @linear/sdk 可解析;NODE_PATH 对 ESM import 无效,仅适用于 CommonJS require。
  • 许多 SDK 属性与嵌套关系是异步的,需 await(如 await issue.state、await issue.assignee)。
  • 连接需分页:使用 connection.pageInfo.hasNextPage 与 await connection.fetchNext() 迭代,更多示例见 references/recipes.md。
  • 将团队键(如 ENG)、工作流状态名(如 Done)、指派人邮箱等人类输入解析为 ID 时需先查询,查阅 references/recipes.md 的 lookup-then-mutate 模式。
  • 密钥属敏感信息,不得打印到对话记录或提交到任何位置。