文档同步

本页由 plugins/adapters/github/README.md 自动生成。请修改包内 README 后运行 pnpm sync:adapter-docs。

@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/，只激活当前任务所需的一组

安装

bash

pnpm add @zhin.js/adapter-github

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

前置条件

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

配置（Plugin Runtime）

yaml

# 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 必填）：

yaml

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

@zhin.js/adapter-github ​

功能特性 ​

安装 ​

前置条件 ​

配置（Plugin Runtime） ​

已移除的能力 ​

Channel ID ​

AI 工具 ​

架构 ​

故障排查 ​

License ​