# @chat-adapter/linear 中文文档

规范地址：https://npmcn.com/package/%40chat-adapter/linear/

版本：4\.44\.0
npm 元数据更新时间：2026-11-02T14:56:06.171Z
中文译文更新时间：2026-11-09T11:18:45.494Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chat-adapter/linear
原文对照：https://npmcn.com/package/%40chat-adapter/linear/?lang=original
项目主页：https://chat-sdk.dev/adapters/official/linear
源码仓库：https://github.com/vercel/chat

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：119 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-02-06T21:16:10.314Z
- 最新版本发布：2026-11-02T14:56:05.797Z
- 近 30 天下载量：449223（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

Chat SDK 的线性适配器 — @ mentions in ission 注释和线性代理会话

## 安装

```sh
npm install @chat-adapter/linear
```

也可以使用：`pnpm add @chat-adapter/linear`、`yarn add @chat-adapter/linear`、`bun add @chat-adapter/linear`

## README

[![Linear adapter for Chat SDK](https://chat-sdk.dev/en/adapters/official/linear/og)](https://chat-sdk.dev/adapters/official/linear)

# @chat-adapter/线性

> npm 软件包 : [`@chat-adapter/linear`](https://www.npmjs.com/package/@chat-adapter/linear)

[![Agent Stack](https://img.shields.io/badge/Agent%20Stack-000?style=flat-square&logo=vercel&logoColor=FFF&labelColor=000&color=000)](https://vercel.com/kb/agent-stack) [![MIT License](https://img.shields.io/badge/License-MIT-000?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=000&color=000)](https://npmcn.com/package/LICENSE)

线性适配器 [聊天SDK](https://chat-sdk.dev/)。在问题评论线索和线性应用代理会话中响应@mentions.

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

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

## 安装

```bash
pnpm add @chat-adapter/linear
```

## 带CLI的脚手架

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

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

访问 [适配器目录](https://chat-sdk.dev/adapters) 见其他官方和供应商官方适配器.

## 快开始

关于管理下的证书和网络记录核查,见 [**Vercel 连接**](https://npmcn.com/package/%40chat-adapter/linear/#readme-option-a--vercel-connect)。 。 。 .

适配器自动检测证书来自 `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`数字 :

```typescript
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` | 无\* | 个人 API 密钥 。 自动从 `LINEAR_API_KEY` |
| `accessToken` | 无\* | OAuth 访问符 。 接受字符串,或 (Vercel Connection) a `() => string | Promise<string>` aPI呼叫时引用的解析器 。 自动从 `LINEAR_ACCESS_TOKEN` |
| `clientId` | 无\* | 多租户OAuth应用客户端ID. 自动从 `LINEAR_CLIENT_ID` |
| `clientSecret` | 无\* | 多租户OAuth应用客户端秘密. 自动从 `LINEAR_CLIENT_SECRET` |
| `encryptionKey` | 没有 | AES-256-GCM 密钥用于加密存储的 OAuth 令牌. 自动从 `LINEAR_ENCRYPTION_KEY` |
| `clientCredentials` | 无\* | 单一租户客户证书配置 |
| `clientCredentials.scopes` | 没有 | 客户资格认证的范围。 默认为 `["read", "write", "comments:create", "issues:create"]` |
| `mode` | 没有 | 输入webhook处理模式. 默认为 `"comments"`设置 `"agent-sessions"` 建议的连接设置 |
| `webhookSecret` | 编号\*\* | Webhook 签名秘密。 自动从 `LINEAR_WEBHOOK_SECRET` |
| `webhookVerifier` | 编号\*\* | 自定义验证器 `(request, body) => unknown | Promise<unknown>` 替换 `webhookSecret`优先排序 `webhookSecret`编号 :`LINEAR_WEBHOOK_SECRET`连接模式 |
| `userName` | 没有 | 瓶子显示名. 自动从 `LINEAR_BOT_USERNAME` (默认 : `"linear-bot"`(中文(简体) ) |
| `apiUrl` | 没有 | 覆盖线性图形QL API 基础 URL 。 自动从 `LINEAR_API_URL` |
| `logger` | 没有 | 锁定实例( 默认为 `ConsoleLogger("info")`(中文(简体) ) |

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

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

## 认证

### 选项A——Vercel连接

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

最简单的路径是 `connectLinearAdapter()` 助手从 [`@vercel/connect/chat`](https://www.npmjs.com/package/@vercel/connect)数字 :

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

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

或者自己给田地接线

```typescript
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.  转到 [设置 > 安全访问](https://linear.app/settings/account/security)
2.  下 **个人 API 密钥**,单击 **创建密钥**
3.  选择 **只选择权限** 创建问题,创建注释
4.  选择团队访问
5.  点击 **创建** 设置 `LINEAR_API_KEY`

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

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

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

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

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

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

1.  转到 [设置 > API > 应用程序](https://linear.app/settings/api/applications/new)
2.  创建 OAuth2 应用程序, 并带有您的机器人名称和图标
3.  说明 **客户身份** 财务报告和审定财务报表 **客户端机密**

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

示例召回路由 :

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

示例背景任务 :

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

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

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

```typescript
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加密存储访问和刷新令牌:

```bash
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
```

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

```typescript
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()` 不支持这里

见 [线性代理文件](https://linear.app/developers/agents) 详细情况.

## 直接 API 客户端

对于除了SDK之外的任何事物,进入基础 [线性连接](https://github.com/linear/linear/tree/master/packages/sdk) 通过 `.linearClient`数字 :

```typescript
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.  点击 **创建网点**

## 线索模型

线性有四个线性变体:

| 类型 | 说明 | 线索标识格式 |
| --- | --- | --- |
| 问题层面 | 高层对某一问题的评论 | `linear:{issueId}` |
| 注释线程 | 在具体评论下进行的答复 | `linear:{issueId}:c:{commentId}` |
| 关于问题的代理会议 | 附带问题的助理演员会议 | `linear:{issueId}:s:{agentSessionId}` |
| 评论线索的代理会话 | 附加在评论线上的 App- actor 会话 | `linear:{issueId}:c:{commentId}:s:{agentSessionId}` |

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

## 反应

| SDK 爱莫吉 | 线性情感 |
| --- | --- |
| `thumbs_up` | 拇指向上 |
| `thumbs_down` | 缩略图 下 |
| `heart` | 心脏 |
| `fire` | 开火 |
| `rocket` | 火箭 |
| `eyes` | 双眼 |
| `sparkles` | 闪光 |
| `wave` | 挥发 |

## 环境变量

```bash
# 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, 适配器模式, 以及项目常规 .

```bash
npx skills add vercel/chat
```

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

您也可以安装 [Vercel 插件](https://vercel.com/docs/agent-resources/vercel-plugin) 包括Chat SDK技术与专家代理、代理斜线指令

```bash
npx plugins add vercel/vercel-plugin
```

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

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

## 许可证

麻省理工学院

## 常见问题

### @chat-adapter/linear 是什么？

Chat SDK 的线性适配器 — @ mentions in ission 注释和线性代理会话

### 如何安装 @chat-adapter/linear？

在项目目录运行 npm install @chat-adapter/linear，或使用 pnpm add / yarn add / bun add。

### @chat-adapter/linear 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @chat-adapter/linear 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @chat-adapter/linear 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chat-adapter/linear 可以商用吗？

@chat-adapter/linear 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chat-adapter/linear 的下载量有多少？

根据 npm 官方下载统计，@chat-adapter/linear 在 2026/10/10 – 2026/11/08 这 30 天内被下载 449,223 次，日均约 14,974 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chat-adapter/linear 还在维护吗？

最新版本 4\.44\.0 发布于 2026/11/02（6 天前）；至今共发布 48 个版本，其中过去 12 个月发布了 48 个；首次发布于 2026/02/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。