GitHub 通知插件

为 Zhin.js 提供 GitHub 仓库事件通知功能。支持好友或群管理订阅仓库的 push、issue、star、fork、unstar、PR 等事件。

功能特性

• ✅ 支持多种事件类型：push、issue、star、fork、unstar、pull_request
• ✅ 基于 GitHub Webhook 实时推送
• ✅ 权限控制：仅好友或群管理可订阅
• ✅ 多平台支持：适配所有 Zhin 适配器
• ✅ 数据持久化：使用数据库存储订阅信息
• ✅ 签名验证：支持 Webhook Secret 验证

安装

pnpm add @zhin.js/plugin-github-notify

配置

在 zhin.config.ts 中添加插件：

export default defineConfig({
  plugins: [
    'http',              // 必需：提供 HTTP 服务
    'adapter-process',   // 或其他适配器
    'github-notify'      // GitHub 通知插件
  ],
  plugin_config: {
    'github-notify': {
      webhook_secret: 'your-webhook-secret' // 可选：Webhook 签名密钥
    }
  }
})

使用方法

1. 订阅仓库

订阅所有事件：

github.subscribe zhinjs/zhin

订阅指定事件：

github.subscribe zhinjs/zhin push issue star

订阅 PR 事件：

github.subscribe zhinjs/zhin pr

2. 查看订阅列表

github.list

3. 取消订阅

github.unsubscribe zhinjs/zhin

GitHub Webhook 配置

步骤 1: 订阅仓库

在聊天中使用命令订阅仓库后，会收到提示信息。

步骤 2: 配置 GitHub Webhook

1. 访问仓库设置页面：https://github.com/owner/repo/settings/hooks
2. 点击 "Add webhook"
3. 填写配置：
   • Payload URL: http://your-domain:port/api/github/webhook
   • Content type: application/json
   • Secret: 与插件配置中的 webhook_secret 保持一致（可选）
   • Events: 选择需要的事件类型
     • Just the push event（仅 push）
     • Send me everything（所有事件）
     • Let me select individual events（自定义选择）
       • Pushes
       • Issues
       • Stars
       • Forks
       • Pull requests

步骤 3: 测试

配置完成后，GitHub 会发送一个测试 Webhook。如果成功，你将在日志中看到：

收到 GitHub Webhook: ping - owner/repo

之后任何符合订阅的事件都会自动推送到订阅的聊天中。

事件类型

| 事件类型 | 命令参数 | GitHub 事件 | 说明 | |---------|---------|------------|------| | Push | push | push | 代码推送 | | Issue | issue | issues | Issue 创建/更新/关闭 | | Star | star | star (created) | 仓库被 star | | Unstar | unstar | star (deleted) | 仓库被 unstar | | Fork | fork | fork | 仓库被 fork | | Pull Request | pr / pull_request | pull_request | PR 创建/更新/合并 |

通知消息格式

Push 事件

📦 zhinjs/zhin
🌿 username pushed to main

📝 3 commits:
  • abc1234 feat: add new feature
  • def5678 fix: resolve bug
  • ghi9012 docs: update README

🔗 https://github.com/zhinjs/zhin/tree/main

Issue 事件

🐛 zhinjs/zhin
👤 username 打开了 issue #123

📌 Bug: Something is broken

🔗 https://github.com/zhinjs/zhin/issues/123

Star 事件

⭐ zhinjs/zhin
👤 username starred the repository

🔗 https://github.com/zhinjs/zhin

Fork 事件

🍴 zhinjs/zhin
👤 username forked to username/zhin

🔗 https://github.com/username/zhin

Pull Request 事件

🔀 zhinjs/zhin
👤 username 打开了 PR #456

📌 feat: Add awesome feature

🔗 https://github.com/zhinjs/zhin/pull/456

权限控制

• 私聊: 所有好友都可以订阅
• 群聊: 仅群管理员可以订阅（需要适配器支持权限检查）

数据库结构

github_subscriptions 表

| 字段 | 类型 | 说明 | |------|------|------| | id | integer | 主键 | | repo | text | 仓库名 (owner/repo) | | events | json | 订阅的事件列表 | | target_id | text | 目标 ID（用户或群） | | target_type | text | 类型 (private/group) | | adapter | text | 适配器名称 | | bot | text | 机器人名称 | | created_at | datetime | 创建时间 | | updated_at | datetime | 更新时间 |

github_events 表

| 字段 | 类型 | 说明 | |------|------|------| | id | integer | 主键 | | repo | text | 仓库名 | | event_type | text | 事件类型 | | payload | json | 事件载荷 | | created_at | datetime | 创建时间 |

API 端点

POST /api/github/webhook

接收 GitHub Webhook 事件。

Headers:

• X-GitHub-Event: 事件类型
• X-Hub-Signature-256: 签名（如果配置了 secret）

Body: GitHub Webhook Payload (JSON)

Response:

{
  "message": "OK",
  "notified": 3
}

开发

构建

pnpm build

测试

# 使用 ngrok 或其他工具暴露本地端口
ngrok http 8086

# 使用生成的 URL 配置 GitHub Webhook
# 例如: https://abc123.ngrok.io/api/github/webhook

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！