# @chat-adapter/github 中文文档

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

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

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

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

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

- 包体积（解压后）：87.4 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：4 个
- 首次发布：2026-02-05T23:58:16.688Z
- 最新版本发布：2026-11-02T14:55:45.683Z
- 近 30 天下载量：689134（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

Chat SDK 的 GitHub 适配器 — 在拉请求中响应@mentions 并发布评论线索

## 安装

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

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

## README

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

# @chat-adapter/github (英语)

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

[![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)

用于 GitHub 适配器 [聊天SDK](https://chat-sdk.dev/)。响应公关中的@mentions并发布评论线索.

GitHub 适配器将问题和拉出请求评论视为消息,将问题/PR视为线程.

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

## 安装

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

## 带CLI的脚手架

要用这个适配器预选的新 GitHub bot 脚手架:

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

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

## 快开始

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

适配器自动检测证书来自 `GITHUB_TOKEN` (或 `GITHUB_APP_ID`编号 :`GITHUB_PRIVATE_KEY`, (中文(简体) ), `GITHUB_WEBHOOK_SECRET`,以及 `GITHUB_BOT_USERNAME` 环境变量:

```typescript
import { Chat } from "chat";
import { createGitHubAdapter } from "@chat-adapter/github";

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

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

## 配置

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

| 选项 | 需求 | 说明 |
| --- | --- | --- |
| `token` | 无\* | 个人访问Token。 自动从 `GITHUB_TOKEN` |
| `appId` | 无\* | GitHub App ID (英语). 自动从 `GITHUB_APP_ID` |
| `privateKey` | 没有 | GitHub App私人密钥 (PEM). 自动从 `GITHUB_PRIVATE_KEY` |
| `installationId` | 没有 | 安装ID(多租户的缩写). 自动从 `GITHUB_INSTALLATION_ID` |
| `installationToken` | 无\* | Vercel 连接模式: 安装访问令牌, 或 a `() => string | Promise<string>` aPI呼叫时引用的解析器 。 跳过 App JWT 交换 . |
| `webhookSecret` | 编号\*\* | 韦布克秘密. 自动从 `GITHUB_WEBHOOK_SECRET` |
| `webhookVerifier` | 编号\*\* | 自定义验证器 `(request, body) => unknown | Promise<unknown>` 替换 `webhookSecret`优先排序 `webhookSecret`编号 :`GITHUB_WEBHOOK_SECRET`连接模式 |
| `userName` | 没有 | @mention 检测的瓶名 。 自动从 `GITHUB_BOT_USERNAME` (默认 : `"github-bot"`(中文(简体) ) |
| `botUserId` | 没有 | Bot 的数字用户ID( 如果未提供自动检测) |
| `apiUrl` | 没有 | 覆盖 GitHub API 基础 URL(如 GitHub Entertainment Server). 自动从 `GITHUB_API_URL` |
| `logger` | 没有 | 锁定实例( 默认为 `ConsoleLogger("info")`(中文(简体) ) |

\*一个 `token`编号 :`GITHUB_TOKEN`, (中文(简体) ), `appId`\+ 键`privateKey`编号 :`GITHUB_APP_ID`\+ 键`GITHUB_PRIVATE_KEY`,或 `installationToken` (Vercel Connect)是必须的.

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

## 认证

### 选项A——Vercel连接

使用 [Vercel 连接](https://vercel.com/docs/connect) 到运行时的源安装访问符,而不是存储 GitHub App 私人密钥。 这个 `installationToken` 解析器提供适配器直接发送的令牌(Skipping the App JWT Exchange),并 `webhookVerifier` 通过 Vercel OIDC 令牌来验证 Connect 触发前的 Webhooks 而不是 Webhook 密钥 .

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

```typescript
import { createGitHubAdapter } from "@chat-adapter/github";
import { connectGitHubAdapter } from "@vercel/connect/chat";

createGitHubAdapter({
  ...connectGitHubAdapter("github/acme-github"),
  userName: "my-bot[bot]",
});
```

或者自己给田地接线

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

createGitHubAdapter({
  installationToken: () =>
    getToken("github/acme-github", { subject: { type: "app" } }),
  webhookVerifier: myConnectWebhookVerifier,
  userName: "my-bot[bot]",
});
```

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

> **新鲜度 :** OIDC验证取代了GitHub的签名检查,因此请求新鲜度依赖于短命的OIDC令牌的过期,而不是一个被签名的时间戳,并且没有内置的不收/交付-id去重复. 保留您的 Webhook 处理器同位素( GitHub 也可能重播事件) .

> **设定 `botUserId` 用于自我信息检测.** 在Connect模式下,适配器只持有一个安装令牌,因此无法自发地检测自己的bot用户ID(即: `/app` 搜索需要App的JWT). 没有它,适配器除了用户的评语外,无法分辨自己的评语,并将在循环中回复自己. 适配器从它贴出的第一个评论中学习出ID,但是它活在记忆中——在没有服务器上(在那里,每个网络hook可能会打出一个新实例),这还不够. 过 `botUserId` (你的号码) `…[bot]` 因此,每个实例在前面都知道:
> 
> ```typescript
> createGitHubAdapter({
>   ...connectGitHubAdapter("github/acme-github"),
>   botUserId: 12345678, // id of your-app[bot]
> });
> ```
> 
> 或者设置 `GITHUB_BOT_USER_ID` 环境变量,适配器自动检测。 查找 id( 不需要认证) `curl -s 'https://api.github.com/users/your-app%5Bbot%5D'`。 。 。 .

### 选择B——个人访问托肯

最适合个人项目,测试,或者单重播.

1.  转到 [设置 > 开发者设置 > 个人访问符](https://github.com/settings/tokens)
2.  创建新符号 `repo` 范围
3.  设定 `GITHUB_TOKEN` 环境变量

```typescript
createGitHubAdapter({
  token: process.env.GITHUB_TOKEN!,
});
```

### 备选办法C——GitHub App(建议)

更好的费率限制,安全,并支持多个设施.

**1\. 创建应用程序:**

1.  转到 [设置 > 开发者设置 > GitHub Apps > 新建 GitHub App](https://github.com/settings/apps/new)
2.  设定 **Webhook URL 软件** 改为 `https://your-domain.com/api/webhooks/github`
3.  生成并设定 **Webhook 秘密**
4.  设置权限 :
    -   仓库 > 问题:读取和写入
    -   仓库 > 拉出请求: 读取并写入
    -   仓库 > 元数据: 只读
5.  订阅事件: 问题评论, 拉请求评论
6.  点击 **创建 GitHub 应用**
7.  说明 **应用标识** 并单击 **生成私钥**

**2\. 安装应用程序:**

1.  到您的应用程序设置去 **安装 App**
2.  点击 **安装** 并选择仓库
3.  说明 **安装标识** 从 URL 中 :
    
    ```
    https://github.com/settings/installations/12345678
                                               ^^^^^^^^
    ```
    

**单租户:**

设定 `installationId` 只接受 GitHub App 安装中的评论。 经核实后,提出新的评论(第1段)`issue_comment` 或者说 `pull_request_review_comment` 有动作 `created`从不同的装置得到一个 `404`,处理器不运行,适配器登录一个带有两个ID的警告. 检查是否与您核对 `webhookSecret` 或习惯 `webhookVerifier`,其他事件类型和动作不检查.

无助产 `installation` 对象仍然到达处理器。 GitHub 从寄存器和组织webhooks中省略了它,所以那些一直以这种模式工作. Vercel 连接模式 (`installationToken`)没有配置的安装ID并跳过此检查.

```typescript
createGitHubAdapter({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_PRIVATE_KEY!,
  installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!),
});
```

**多租户( 缩略语) `installationId`:**

```typescript
createGitHubAdapter({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_PRIVATE_KEY!,
});
```

适配器会自动从webhooks中提取安装ID并缓存API客户端每个安装.

## 安装查询

您可以解析与 GitHub App 相关的安装 ID `Thread` 或者说 `Message`数字 :

```typescript
import { Chat } from "chat";
import { createGitHubAdapter } from "@chat-adapter/github";

const github = createGitHubAdapter({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_PRIVATE_KEY!,
  webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
});

const bot = new Chat({
  adapters: { github },
});

bot.onNewMention(async (thread, message) => {
  const installationIdFromThread = await github.getInstallationId(thread);
  const installationIdFromMessage = await github.getInstallationId(message.threadId);

  await thread.post(
    `Thread install: ${installationIdFromThread}, message install: ${installationIdFromMessage}`
  );
});
```

-   单租户 GitHub App模式返回所配置的固定安装ID.
-   PAT 模式返回 `undefined`。 。 。 .
-   多租户模式只有在适配器收到用于该寄存器的网页hook并缓存安装映射后才能成功. 使用恒定状态适配器,使映射存活下来,重新启动.

## 直接 API 客户端

对于除了SDK之外的任何事物,进入基础 [八分卫](https://github.com/octokit/octokit.js) 实例 `.octokit`数字 :

```typescript
const github = bot.getAdapter("github").octokit;

const { data: pulls } = await github.rest.pulls.list({
  owner: "vercel",
  repo: "chat",
  state: "open",
});
```

PAT 和 单租户 GitHub App 模式( 带有固定模式) `installationId`)在任何地方返回同一客户端. 多租户模式需要webhook处理器上下文来解决正确的安装——调用 `.octokit` 在操作器外抛出.

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

## Webhook 设置

对于寄存器或组织网点:

1.  转到仓库/ org **设置** 接下来 **网络呼号** 接下来 **添加网点**
2.  设定 **有效载荷 URL** 改为 `https://your-domain.com/api/webhooks/github`
3.  设定 **内容类型** 改为 `application/json` (需要——默认) `application/x-www-form-urlencoded` 无效)
4.  设定 **秘诀** 来匹配您的 `webhookSecret`
5.  选择事件: 发布评论, 拉请求评论

> **警告:** GitHub App 在应用程序创建期间配置了webhooks. 确定选择 `application/json` 作为内容类型.

## 线索模型

GitHub 有三种评论线索:

| 类型 | A. 背景情况 | 线索标识格式 |
| --- | --- | --- |
| PR级 | PR 对话标签 | `github:{owner}/{repo}:{prNumber}` |
| 审查评论 | PR 文件已更改标签 | `github:{owner}/{repo}:{prNumber}:rc:{commentId}` |
| 问题评论 | 问题线索 | `github:{owner}/{repo}:issue:{issueNumber}` |

## 反应

支持 GitHub 的反应 emoji :

| SDK 爱莫吉 | GitHub 反应 |
| --- | --- |
| `thumbs_up` | +1 键 |
| `thumbs_down` | \-1号 |
| `laugh` | 欢笑 |
| `confused` | 混乱 |
| `heart` | 心脏 |
| `hooray` | 万岁 |
| `rocket` | 火箭 |
| `eyes` | 双眼 |

## 环境变量

```bash
# Personal Access Token auth
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# OR GitHub App auth
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
GITHUB_INSTALLATION_ID=12345678  # Optional for multi-tenant

# Required
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Optional: GitHub Enterprise Server
GITHUB_API_URL=https://github.example.com/api/v3
```

## 特征

### 通讯

| 特性 | 支助 |
| --- | --- |
| 邮件 | 对 |
| 编辑信件 | 对 |
| 删除信件 | 对 |
| 文件上传 | 没有 |
| 流线 | 缓冲(累积后发送) |

### 丰富内容

| 特性 | 支助 |
| --- | --- |
| 卡片格式 | GFM 标记 |
| 按钮 | 没有 |
| 链接按钮 | 没有 |
| 选择菜单 | 没有 |
| 表格 | 全球调频 |
| 字段 | 对 |
| 纸牌中的图像 | 对 |
| 模块 | 没有 |

### 对话

| 特性 | 支助 |
| --- | --- |
| 斜线命令 | 没有 |
| 提及 | 对 |
| 添加反应 | 对 |
| 删除反应 | 部分 |
| 打字指标 | 没有 |
| 模式 | 没有 |
| 电文 | 没有 |

### 信件历史

| 特性 | 支助 |
| --- | --- |
| 获取信件 | 对 |
| 获取单个消息 | 没有 |
| 获取线索信息 | 对 |
| 获取频道消息 | 对 |
| 列表线索 | 对 |
| 获取频道信息 | 对 |
| 后频道消息 | 没有 |

### 平台专用

| 特性 | 支助 |
| --- | --- |
| 多租户 | 是 (GitHub App) (英语) |

## 限制

-   **无打字指标** ——GitHub不支持打字指标
-   **无流线** ——全文张贴信件(编辑后支持更新)
-   **无模式** - GitHub没有直接消息
-   **无模式** – GitHub 不支持交互式模式
-   **动作按钮** ——作为文本被渲染;可点击动作使用链接按钮

## 解决问题

### “ 无效签名” 错误

-   校验 `GITHUB_WEBHOOK_SECRET` 匹配您的 webhook 配置
-   确保请求机构在核查前不会被修改

### "无效 JSON" 错误

-   更改网签 **内容类型** 改为 `application/json`

### 瓶子没有回应提及

-   校验 Webhook 事件配置( 问题 评论, 拉 request review comment)
-   请检查webhook URL正确且可访问
-   确保 `userName` 配置匹配您的机器人的 GitHub 用户名

### “ 需要安装 ID ” 错误

-   当在多租户模式下将 API 调用到 webhook 上下文时发生这种情况
-   使用持久状态适配器( Redis) 存储安装映射
-   第一次互动必须来自网络浏览来建立绘图

### 限制费率

-   PATs 的速率限制比 GitHub Apps 低
-   考虑切换到 GitHub App 用于生产

## 资源

-   [与Hono和Redis一起运送一个 GitHub 代码审查机器人](https://vercel.com/kb/guide/ship-a-github-code-review-bot-with-hono-and-redis?utm_source=chat-sdk_repo&utm_medium=readme&utm_campaign=adapter-github&utm_content=ship-a-github-code-review-bot-with-hono-and-redis) ——走过建设"GitHub"机器人,审查按需要拉动请求. 当一个用户@mentions a bot on a PR时,Chat SDK接取了引用,用再生克隆来旋转一个Vercel Sandbox,并使用AI SDK来分析diff.

见所有指南和模板 [聊天-sdk.dev/资源](https://chat-sdk.dev/resources?utm_source=chat-sdk_repo&utm_medium=readme&utm_campaign=adapter-github&utm_content=resources)。 。 。 .

## 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/github 是什么？

Chat SDK 的 GitHub 适配器 — 在拉请求中响应@mentions 并发布评论线索

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

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

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

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

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

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

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

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

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

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

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

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

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

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