GitHub Adapter

Appearance

配置说明 ​

本页面详细介绍 GitHub 适配器的所有配置项。

基础设置 ​

token ​

  • 类型: string
  • 必填: 是
  • 说明: GitHub Personal Access Token (PAT)

用于认证 GitHub API 请求。请确保 Token 具有以下权限：

  • repo - 访问仓库
  • read:user - 读取用户信息
  • read:discussion - 读取 Discussions
  • write:discussion - 发表和修改 Discussions

silentMode ​

  • 类型: boolean
  • 默认值: false
  • 说明: 静默模式

开启后，适配器将不会向 GitHub 发送任何内容（如评论、回复等），仅接收事件。适用于：

  • 测试和调试场景
  • 只需要监听事件而不需要回复的场景
  • 避免误操作的保护模式

注意

静默模式下，所有通过 bot.sendMessage() 等方法发送消息的操作都会被阻止。

通信模式选择 ​

mode ​

  • 类型: 'webhook' | 'pull'
  • 默认值: 'pull'
  • 说明: 通信模式

两种模式的对比：

特性Pull 模式Webhook 模式
公网 IP不需要需要
实时性较差（取决于轮询间隔）实时
事件支持部分受限完整支持
代理支持支持不支持
配置难度简单中等

Pull 模式配置 ​

当 mode 设置为 'pull' 时，以下配置项生效：

repositories ​

  • 类型: Array<{ owner: string, repo: string }>
  • 必填: 是（仅 Pull 模式）
  • 说明: 监听的仓库列表

配置示例：

json
{
  "repositories": [
    {
      "owner": "koishi-shangxue-plugins",
      "repo": "koishi-plugin-adapter-github"
    },
    {
      "owner": "koishijs",
      "repo": "koishi"
    }
  ]
}

提示

  • 可以同时监听多个仓库，适配器会自动处理所有仓库的事件
  • 此配置项仅在 Pull 模式下需要配置

interval ​

  • 类型: number
  • 默认值: 20
  • 单位: 秒
  • 说明: 轮询间隔

建议值：

  • 开发测试：10-20 秒
  • 生产环境：30-60 秒

注意

轮询间隔过短可能导致 API 请求频率过高，触发 GitHub 的速率限制。

useProxy ​

  • 类型: boolean
  • 默认值: false
  • 说明: 是否使用代理

proxyUrl ​

  • 类型: string
  • 默认值: "http://localhost:7897"
  • 说明: 代理地址
  • 生效条件: useProxy 为 true

支持的代理协议：

  • HTTP: http://host:port
  • HTTPS: https://host:port

配置示例：

json
{
  "mode": "pull",
  "interval": 30,
  "useProxy": true,
  "proxyUrl": "http://localhost:7890"
}

Webhook 模式配置 ​

当 mode 设置为 'webhook' 时，以下配置项生效：

webhookPath ​

  • 类型: string
  • 默认值: "/github/webhook"
  • 说明: Webhook 路径

完整的 Webhook URL 格式：

url
http://你的服务器地址:端口/github/webhook

webhookSecret ​

  • 类型: string
  • 可选: 是
  • 说明: Webhook 密钥

用于验证 GitHub 发送的请求是否合法。强烈建议在生产环境中配置此项。

配置示例：

json
{
  "mode": "webhook",
  "webhookPath": "/github/webhook",
  "webhookSecret": "your-secret-key"
}

网络重试设置 ​

autoDispose ​

  • 类型: boolean
  • 默认值: true
  • 说明: 遇到错误时是否按最大重试次数重试后关闭插件

两种模式的区别：

  • 开启（默认）: 重试达到最大次数后自动关闭插件，避免无限重试消耗资源
  • 关闭: 永远重试，不会关闭插件（延迟最大叠加到 1 分钟/次）

适用场景：

  • 开启：适合生产环境，避免网络问题导致插件持续消耗资源
  • 关闭：适合开发环境或网络不稳定的场景，确保插件不会因临时网络问题而关闭

maxRetries ​

  • 类型: number
  • 默认值: 10
  • 说明: 最大重试次数
  • 生效条件: autoDispose 为 true

重试机制说明：

  • 每次重试间隔递增 5 秒（第 1 次 5 秒，第 2 次 10 秒，依此类推）
  • 最大延迟为 60 秒
  • 默认 10 次重试，最后一次约等待 1 分钟

配置示例：

json
{
  "autoDispose": true,
  "maxRetries": 10
}

TIP

提示

重试机制主要用于插件启动时获取 GitHub 用户信息失败的情况。如果网络环境不稳定，可以适当增加 maxRetries 的值，或关闭 autoDispose 以实现永久重试。

高级设置 ​

loggerinfo ​

  • 类型: boolean
  • 默认值: false
  • 说明: 日志调试模式

开启后会输出详细的调试日志，包括：

  • 接收到的事件详情
  • API 请求和响应
  • 错误堆栈信息

提示

在遇到问题时，建议开启此选项以获取更多调试信息。