@zhin.js/adapter-github

GitHub Plugin Runtime 适配器 — Issue/PR 评论区即聊天通道，GitHub App 认证，Webhook 入站经 httpHostToken。

功能特性

• 聊天通道：Issue/PR 评论区映射为群聊，支持收发消息
• Webhook 入站：HMAC-SHA256 验签 → Endpoint.emit(...)
• 出站：send({ conversation, payload }) → Issue/PR comment（conversation.id 为 channel ID）
• GitHub App 认证：JWT → Installation Token
• Agent 工具：按账号、订阅和仓库操作拆分在 agents/github/skills/github-*/tools/，只激活当前任务所需的一组

安装

pnpm add @zhin.js/adapter-github

Webhook 需要 Root 提供 @zhin.js/host-http（zhin runtime start 默认装配）。

前置条件

1. 创建 GitHub App，记录 App ID、私钥与 Webhook Secret。
2. 授予目标仓库所需的 Issues、Pull requests 与 Contents 权限。
3. 将 Webhook 指向公网 HTTPS 的 /github/webhook，并订阅 Issue、PR 与评论事件。
4. 把 App 安装到目标仓库；仓库 Workroom 使用稳定的 owner/repo 地址匹配。

配置（Plugin Runtime）

# zhin.config.yml
plugins:
  github:
    webhook_path: /github/webhook
    auto_reply_repos:
      - zhinjs/zhin
    workspace_root: ./data/github-workspaces
    endpoints:
      - id: my-github-bot
        app_id: "${GITHUB_APP_ID}"
        private_key: ./data/github-app.pem
        webhook_secret: "${GITHUB_WEBHOOK_SECRET}"

private_key 支持文件路径或 PEM 内容。未配置 webhook_secret 时仅 API 出站 / agent 工具可用（无入站）。

AdapterIndex 会先合并插件实例默认值与 endpoint 覆盖值，再把一份完整配置交给 GitHub adapter。协议层只接受这份展开后的 endpoint 配置，不读取环境变量、不解析嵌套 endpoints，也不接受 camelCase 配置别名。${...} 由 composition root 在加载配置时展开。

多 App：一个插件实例挂多个 endpoint（endpoints 数组逐项覆盖顶层字段；id、app_id、private_key 必填）：

plugins:
  github:
    endpoints:
      - id: app-a
        app_id: 123456
        private_key: ./data/app-a.pem
      - id: app-b
        app_id: 234567
        private_key: ./data/app-b.pem

已移除的能力

• ai.githubMcp.enabled / ai.githubMcp.token：Plugin Runtime 迁移后 register-github-mcp（stdio @modelcontextprotocol/server-github，PAT 人身份）已移除，该配置不再生效。如需 MCP 工具，请按 mcps/<name>/index.ts（@zhin.js/mcp-feature）约定自行装配。
• 轮询降级已删除，入站只通过 Webhook；没有保留无效的轮询配置字段。

Channel ID

| 类型 | Channel ID | 示例 | |------|-----------|------| | Issue | owner/repo/issues/N | zhinjs/zhin/issues/42 | | PR | owner/repo/pull/N | zhinjs/zhin/pull/108 |

AI 工具

见 agents/github/skills/github-*/tools/：账号绑定、订阅管理和仓库写入分别按需披露。

架构

| 路径 | 职责 | |------|------| | plugin.ts | 插件元数据；有 DatabaseHost 时定义 github_oauth_users | | adapters/github/index.ts | 薄 defineAdapter 入口（发现约定） | | src/endpoint.ts | Endpoint 生命周期、出站、admit | | src/webhook.ts | HMAC 验签与事件分发 | | src/oauth-users.ts | OAuth 表 SSOT + token 查找 | | src/protocol.ts | 协议纯函数（channel / payload） | | src/gh-client.ts | GitHub API 客户端 |

• 入站：httpHostToken POST → Endpoint.emit(...)
• 出站：send({ conversation, payload })

故障排查

| 现象 | 排查 | | --- | --- | | Webhook 401 | 检查 Secret、X-Hub-Signature-256 与原始请求体 | | App 鉴权失败 | 检查 App ID、私钥 PEM/文件路径与服务器时钟 | | 评论没有进入 Workroom | 先查 Endpoint 收件箱，再核对 Catalog 的 Endpoint 与 owner/repo | | 能收事件但不能回复 | 检查 installation 与仓库权限；PAT MCP 不替代 App 出站 |

License

MIT