@chat-adapter/github (英语)

npm 软件包 : @chat-adapter/github

用于 GitHub 适配器 聊天SDK。响应公关中的@mentions并发布评论线索.

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

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

安装

pnpm add @chat-adapter/github

带CLI的脚手架

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

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

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

快开始

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

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

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编号 :GITHUB_TOKEN, (中文(简体) ), appId+ 键privateKey编号 :GITHUB_APP_ID+ 键GITHUB_PRIVATE_KEY,或 installationToken (Vercel Connect)是必须的.

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

认证

选项A——Vercel连接

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

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

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

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

或者自己给田地接线

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] 因此,每个实例在前面都知道:

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. 转到 设置 > 开发者设置 > 个人访问符
2. 创建新符号 repo 范围
3. 设定 GITHUB_TOKEN 环境变量

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

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

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

1. 创建应用程序:

1. 转到 设置 > 开发者设置 > GitHub Apps > 新建 GitHub App
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并跳过此检查.

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

多租户( 缩略语) installationId:

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

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

安装查询

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

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之外的任何事物,进入基础 八分卫 实例 .octokit数字 :

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 有三种评论线索:

反应

支持 GitHub 的反应 emoji :

环境变量

# 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

特征

通讯

丰富内容

对话

信件历史

平台专用

限制

• 无打字指标 ——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 代码审查机器人 ——走过建设"GitHub"机器人,审查按需要拉动请求. 当一个用户@mentions a bot on a PR时,Chat SDK接取了引用,用再生克隆来旋转一个Vercel Sandbox,并使用AI SDK来分析diff.

见所有指南和模板 聊天-sdk.dev/资源。 。 。 .

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 (全文).

许可证

麻省理工学院