文档同步

本页由 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 验签 → endpointSpec.events
出站：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 start 拉起的实例默认装配，HTTP 由管理网关承载）。

前置条件

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

配置（Plugin Runtime）

yaml

configVersion: 2
# zhin.config.yml
plugins:
  github: "@zhin.js/adapter-github"
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

configVersion: 2
plugins:
  github: "@zhin.js/adapter-github"
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 → endpointSpec.events
出站：send({ conversation, payload })

Console 页面

在所属插件的 Console 页面管理账号：查看配置与运行状态，添加、编辑、启动、停止、替换或删除账号。首次修改启动账号前，管理员需确认迁移清单；保留原身份与历史。此后保存到 Host 运行时存储，不改启动配置或 .env，无需重启进程。

新增仅保存，需手动启动；运行账号的普通配置更新只重连该账号。身份变化走明确替换，新账号不会继承旧 Session 或登录状态。账号凭据变化先按平台实际只读接口核验；平台无法核验时需明确替换。空白或遮蔽的密码不会覆盖既有密码。

读取需要 github:read（read 级别，内置角色 viewer 及以上都有），写入需要 github:write（operate 级别，operator 及以上都有，绑定到本适配器的角色也算）；首次迁移还需管理员身份，见插件权限的级别。无持久化存储时管理操作不可用，提交结果未知时先刷新核实，不重复提交。

故障排查

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

License

MIT

Language / 语言

命令和工具反馈使用当前操作语言，账号绑定等异步流程固定开始时语言。用户名称、第三方内容和结构化协议字段保持原样；语言不改变权限、认证、通知或重试策略。参见官方插件语言说明。

@zhin.js/adapter-github ​

功能特性 ​

安装 ​

前置条件 ​

配置（Plugin Runtime） ​

已移除的能力 ​

Channel ID ​

AI 工具 ​

架构 ​

Console 页面 ​

故障排查 ​

License ​

Language / 语言 ​