@chat-adapter/线性

npm 软件包 : @chat-adapter/linear

线性适配器 聊天SDK。在问题评论线索和线性应用代理会话中响应@mentions.

线性适配器将发出评论视为消息,将问题视为线性.

联合国 聊天-sdk.dev/适应者/官方/线性 指南: vercel.com/kb/chat-sdk (英语)

安装

pnpm add @chat-adapter/linear

带CLI的脚手架

要用这个适配器预选的新线形机器人脚手架:

npx create-chat-sdk@latest my-bot --adapter linear memory

访问 适配器目录 见其他官方和供应商官方适配器.

快开始

关于管理下的证书和网络记录核查,见 Vercel 连接。 。 。 .

适配器自动检测证书来自 LINEAR_API_KEY, (中文(简体) ), LINEAR_ACCESS_TOKEN, (中文(简体) ), LINEAR_CLIENT_CREDENTIALS_CLIENT_ID编号 :LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET,或 LINEAR_CLIENT_ID编号 :LINEAR_CLIENT_SECRET附加时 LINEAR_WEBHOOK_SECRET 财务报告和审定财务报表 LINEAR_BOT_USERNAME数字 :

import { Chat } from "chat";
import { createLinearAdapter } from "@chat-adapter/linear";

const bot = new Chat({
  userName: "my-bot",
  adapters: {
    linear: createLinearAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Linear!");
});

适配器默认为 mode: "comments" 处理 Comment (原始内容存档于2018-10-21). webhoks. 对于Vercel Connected和线性应用器装置,我们明确建议设置 mode: "agent-sessions" 要处理 AgentSessionEvent 包括会话中的提及和答复.

配置

在不提供时,所有选项都从环境变量中自动检测出.

*一个 apiKey, (中文(简体) ), accessToken (字符串或 Vercel 连接解析器),顶级 clientId编号 :clientSecret,或 clientCredentials 需要(通过配置或嵌入 vars).

页:1 webhookSecret (通过配置或 LINEAR_WEBHOOK_SECRET或一个 webhookVerifier 需要时间。 何时 webhookVerifier 它被设定为优先, 而秘密被忽略.

认证

选项A——Vercel连接

使用 Vercel 连接 在运行时源出 Linear 访问令牌, 而不是存储长寿令牌或 OAuth 密件。 过 accessToken 作为解析器并用 webhookVerifier (从 Connect 触发器转发的 Vercel OIDC 令牌) 而不是 Webhook 机密 .

最简单的路径是 connectLinearAdapter() 助手从 @vercel/connect/chat数字 :

import { createLinearAdapter } from "@chat-adapter/linear";
import { connectLinearAdapter } from "@vercel/connect/chat";

createLinearAdapter({
  ...connectLinearAdapter("linear/acme-linear"),
  mode: "agent-sessions",
});

或者自己给田地接线

import { getToken } from "@vercel/connect";

createLinearAdapter({
  accessToken: () =>
    getToken("linear/acme-linear", { subject: { type: "app" } }),
  webhookVerifier: myConnectWebhookVerifier,
  mode: "agent-sessions",
});

我们建议给Vercel Connect bots代理会话 启用 代理会话活动 在Linear应用程序上,并使用一个应用程序辅助器安装. 选择 mode 留着 "comments" 默认; 现有 bots 不需要更改其配置 。 更改适配器模式不会改变应用程序的webhook订阅或权限.

accessToken 接受一个 string 或者说 () => string | Promise<string> 解析器在API呼叫中被引用,因此它与Connect的短命符号相组成. 何时 webhookVerifier 设定它优先于 webhookSecret 财务报告和审定财务报表 LINEAR_WEBHOOK_SECRET。 。 。 .

新鲜度 : OIDC的验证取代了 Linear 的签名 + 时间戳检查,所以请求新鲜度依赖于短寿命的 OIDC 令牌的过期而不是 >5 min 时间戳拒绝,并且没有内置的送货去重复。 保持您的网络处理器 idempotent (Linear 也可以将事件传出异常状态).

选项B——个人 API 密钥

最适合个人项目,测试,或单工作空间bots. 行动归你个人所有.

1. 转到 设置 > 安全访问
2. 下 个人 API 密钥,单击 创建密钥
3. 选择 只选择权限 创建问题,创建注释
4. 选择团队访问
5. 点击 创建 设置 LINEAR_API_KEY

createLinearAdapter({
  apiKey: process.env.LINEAR_API_KEY!,
});

备选案文C——预取的OAuth访问令牌

当您的应用程序已经管理 OAuth 流时使用此功能, 您只希望适配器使用单个的工作空间符号操作 .

createLinearAdapter({
  accessToken: process.env.LINEAR_ACCESS_TOKEN!,
});

备选方案D——多租户OAuth安装

使用顶级 clientId 编号 : clientSecret 为Slack-type多租户安装. 每个线性工作空间安装单独存储, Webhook 请求解决正确的工作空间符号 organizationId,以及 withInstallation() 允许您针对特定组织进行网页浏览处理.

1. 转到 设置 > API > 应用程序
2. 创建 OAuth2 应用程序, 并带有您的机器人名称和图标
3. 说明 客户身份 财务报告和审定财务报表 客户端机密

const adapter = createLinearAdapter({
  clientId: process.env.LINEAR_CLIENT_ID!,
  clientSecret: process.env.LINEAR_CLIENT_SECRET!,
  mode: "agent-sessions",
});

示例召回路由 :

await bot.initialize();
const { organizationId } = await adapter.handleOAuthCallback(request, {
  redirectUri: process.env.LINEAR_REDIRECT_URI!,
});

示例背景任务 :

await adapter.withInstallation("org-id", async () => {
  await adapter.postMessage("linear:issue-id", "Hello from a background job");
});

选择E——单一租户客户证书

如果您想要没有多租户安装的应用程序身份, 请使用明确 clientCredentials 相会. 适配器会自动取出并刷新符号 .

createLinearAdapter({
  clientCredentials: {
    clientId: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_ID!,
    clientSecret: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET!,
    scopes: ["read", "write", "comments:create", "issues:create"],
  },
  mode: "agent-sessions",
});

脚本加密

对于多租户的OAuth安装,通过一个编码为32字节的基数64键作为 encryptionKey (或设置) LINEAR_ENCRYPTION_KEY)在休息时使用AES-256-GCM加密存储访问和刷新令牌:

openssl rand -base64 32

何时 encryptionKey 已经设定, setInstallation() 在将符号写入已配置的状态适配器之前加密它们 getInstallation() 解密透明。 已存在的纯文本记录继续工作,这样您就可以在不冲洗安装的情况下滚动键入. 没有 encryptionKey,将符号存储在平面文本中(上一个默认值).

让机器人@-mentionable(可选)

为了让机器人出现在 Linear 的 @ 提到降为特工:

1. 在 OAuth 应用程序设置中,启用 代理会话活动 在网络呼声下
2. 由工作空间管理员安装应用程序 actor=app 编辑 app:mentionable 范围 :

https://linear.app/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://your-domain.com/callback&
  response_type=code&
  scope=read,write,comments:create,issues:create,app:mentionable&
  actor=app

如果您使用单租户客户证书,请在其中要求相同的范围:

createLinearAdapter({
  clientCredentials: {
    clientId: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_ID!,
    clientSecret: process.env.LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET!,
    scopes: [
      "read",
      "write",
      "comments:create",
      "issues:create",
      "app:mentionable",
    ],
  },
});

安装后 actor=app设置 mode: "agent-sessions" 所以适配器处理 AgentSessionEvent 作为提及:

• onNewMention 会话创建事件起火
• thread.startTyping() 发送电子线条 thought
• thread.post(stream) 使用代理活动和会议计划更新
• 会话线索只是附加的,所以 sent.edit() 编号 : sent.delete() 不支持这里

见 线性代理文件 详细情况.

直接 API 客户端

对于除了SDK之外的任何事物,进入基础 线性连接 通过 .linearClient数字 :

const linear = bot.getAdapter("linear").linearClient;

const issue = await linear.issue("ENG-123");
const project = await issue.project;

API密钥,访问令牌,以及单租户客户端-证书模式在任何地方返回同一个客户端. 多租户 OAuth 模式需要 Webhook 处理器上下文来解决每升令牌——调用 .linearClient 在操作器外抛出.

前一个 .client geetter 仍然作为 贬值的别名工作 .linearClient。 。 。 .

Webhook 设置

说明: Webhook 管理需要工作空间管理员访问. 如果您没有看到 API 设置页面, 请请工作空间管理员为您创建 webhook .

1. 转到 设置 > API 并单击 创建网点
2. 填写:
   • 标签:一个描述性名称(例如"Chat Bot")
   • 網址数字 : https://your-domain.com/api/webhooks/linear
3. 复制 签名秘密 作为 LINEAR_WEBHOOK_SECRET
4. 下 数据变化事件,选择:
   • 评论 (需为 mode: "comments"(中文(简体) )
   • 代理会话活动 (需为 mode: "agent-sessions"(中文(简体) )
   • 问题 (建议)
   • Emoji 反应 (可选)
5. 下 团队选择选择 所有公共小组 或特定的团队
6. 点击 创建网点

线索模型

线性有四个线性变体:

当用户写出评论时,bot会在同一评论线索内回复.

反应

环境变量

# API Key auth
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx

# OR pre-obtained access token
LINEAR_ACCESS_TOKEN=lin_oauth_xxxxxxxxxxxx

# OR single-tenant client credentials auth
LINEAR_CLIENT_CREDENTIALS_CLIENT_ID=your-client-id
LINEAR_CLIENT_CREDENTIALS_CLIENT_SECRET=your-client-secret
# Optional, comma-separated
LINEAR_CLIENT_CREDENTIALS_SCOPES=read,write,comments:create,issues:create

# OR multi-tenant OAuth installs
LINEAR_CLIENT_ID=your-client-id
LINEAR_CLIENT_SECRET=your-client-secret
LINEAR_REDIRECT_URI=https://your-domain.com/api/linear/install/callback
# Optional: encrypt stored OAuth tokens at rest
LINEAR_ENCRYPTION_KEY=...

# Optional: inbound webhook mode
# comments | agent-sessions
LINEAR_MODE=comments

# Required
LINEAR_WEBHOOK_SECRET=your-webhook-secret

# Optional: override the Linear GraphQL API base URL
LINEAR_API_URL=...

特征

通讯

丰富内容

对话

信件历史

对于代理线条, fetchMessages() 丢出一个 ValidationError 如果会话没有相关议题,或者其议题ID与线程ID中的议题ID不符. 适配器在获取会话注释或活动之前检查此选项 .

限制

• 评论线索仍然基于评论 – 输入指标和本地流仅用于应用程序代理会议
• 代理会话线索仅为附件 —— 说 editMessage 财务报告和审定财务报表 deleteMessage 用于正常评论的工作,但不用于会议活动
• 无模式 - 线性没有直接消息
• 无模式 ——线性不支持交互式模式
• 动作按钮 ——作为文本被渲染;可点击动作使用链接按钮
• 删除反应 ——需要进行反应ID查询(不直接支持)

解决问题

“ 无效签名” 错误

• 校验 LINEAR_WEBHOOK_SECRET 匹配您 webhook 配置中的秘密
• 在创建时只显示一次网球秘诀—— 如果丢失则重生

瓶子没有回应提及

• 校验webhook事件配置 评论 资源类型
• 对于应用程序代理模式,也启用 代理会话活动
• 请检查webhook URL是否正确且可访问
• 确保 userName 配置匹配用户提及机器人的方式
• 如果使用 App-actor 安装, 请确保应用安装 actor=app 财务报告和审定财务报表 app:mentionable
• 线性在反复失败后可能自动失效的 Webhooks

"Webhook" 已过期错误

• Webhook 时间戳太老了( > 5分钟)
• 通常表示交付延迟或时钟 skew
• 检查您的服务器时间是否同步

AI 编码代理

如果您使用OpenAI Codex, Claude Code, 或 Cursor 等AI编码代理, 在写入代码前安装 Chat SDK 技能, 使其了解 SDK API, 适配器模式, 以及项目常规 .

npx skills add vercel/chat

技术参考文献 node_modules/chat/docs,加上已发布的软件包中的适配器指南和启动模板.

您也可以安装 Vercel 插件 包括Chat SDK技术与专家代理、代理斜线指令

npx plugins add vercel/vercel-plugin

插件是可选的;单是技能就足以用Chat SDK来构建.

关于可代理阅读的文件,见 聊天- sdk.dev/llms.txt (页数索引)或 聊天- sdk.dev/llms- full.txt (全文).

许可证

麻省理工学院