Axiu Docs

Appearance

Git-Plugin ​

源码仓库：https://github.com/QingYingX-Bot/Git-Plugin

面向 Yunzai 的 Git 仓库助手，支持 GitHub、Gitee、GitCode、Gitea 四个平台。

Git-Plugin 可以查询仓库、Issue、PR、README，支持仓库订阅、轮询推送、Webhook 实时推送，以及 Git 仓库链接自动解析。平台实现按 Provider 分离，GitHub / Gitee / GitCode / Gitea 的 API、鉴权和地址规则互不混用。

功能 ​

功能说明
仓库查询查看描述、Star、Fork、默认分支、更新时间
Issue 查询按编号查详情；只填仓库时列出开启 Issue 编号
PR 查询按编号查详情；只填仓库时列出开启 PR 编号
README 查询读取仓库 README
API 限流查询 GitHub API rate limit
帮助图使用独立模板渲染插件命令帮助
仓库订阅在群聊或私聊订阅仓库更新
轮询推送定时检查新增 Issue / PR
仓库更新卡片定时检查分支 commit，推送带作者、分支、变更统计、Release / Tag 的更新卡片
Webhook 推送接收平台 webhook 并推送到订阅会话
链接解析自动解析 Git 仓库链接，并生成仓库卡片图
插件更新支持 #gt更新 / #git更新 快捷更新 Git-Plugin

支持平台 ​

平台默认 APIProvider
GitHubhttps://api.github.commodel/providers/githubProvider.js
Giteehttps://gitee.com/api/v5model/providers/giteeProvider.js
GitCodehttps://api.gitcode.com/api/v5model/providers/gitcodeProvider.js
Gitea{baseUrl}/api/v1model/providers/giteaProvider.js

安装 ​

在 Yunzai 根目录执行：

bash
git clone https://github.com/QingYingX-Bot/Git-Plugin.git plugins/Git-Plugin
cd plugins/Git-Plugin
npm install

安装后重启 Yunzai。

配置 ​

默认配置：

text
plugins/Git-Plugin/config/default_config/git.yaml

运行配置：

text
plugins/Git-Plugin/config/config/git.yaml

首次运行会从默认配置复制一份到运行配置。真实 token、webhook secret、Gitea 实例地址写到运行配置里。

Token 权限 ​

平台推荐权限
GitHubFine-grained PAT，Contents / Issues / Pull requests 只读
Gitee私人令牌，仓库 / Issue / PR 读权限
GitCodeAccess Token，仓库 / Issue / PR 读权限
GiteaAccess Token，repository / issue 读权限

网络代理 ​

访问 GitHub 慢或经常出现 TLS 建连失败时，可以在运行配置中填写代理：

yaml
proxy: "http://127.0.0.1:7890"

代理会用于平台 API 请求、README / Issue / PR 正文图片下载，以及仓库更新卡片的作者头像下载。

Webhook 配置 ​

yaml
webhook:
  enabled: true
  host: "0.0.0.0"
  port: 6192
  path: "/git/webhook"
  secret: "your-secret"
  pushClosedEvents: false
  allowedEventTypes:
    - issues
    - pull_requests
    - push

Webhook URL：

text
http://host:6192/git/webhook

有公网域名时填平台侧 Payload URL，例如：

text
https://githook.example.com/git/webhook

默认推送 Issues / PR / Push 相关事件，并过滤 closed。事件列表和其他事件含义见 WEBHOOK_EVENTS.md。

仓库卡片 ​

仓库查询和链接解析支持仓库卡片图。Gitee、GitCode、Gitea 链接解析默认使用插件内置模板渲染仓库卡片。GitHub 链接解析默认使用官方 OpenGraph 图片，也可以切换到统一模板。 内置模板会优先显示仓库所属账号/组织头像，平台标识使用本地 SVG 图标。 Issue / PR 详情和开启编号列表使用插件内置模板渲染为图片，渲染失败时自动回落文本。 README 查询使用插件内置模板渲染 Markdown 图片，渲染失败时自动回落文本。

yaml
card:
  githubMode: "opengraph"

可选值：

值说明
opengraphGitHub 使用官方 OpenGraph 图片，其它平台使用内置模板
template四个平台都使用内置模板

仓库更新卡片 ​

commit 轮询推送使用 resources/repo-update-card.html 渲染卡片图，字体使用 resources/fonts/HarmonyOS_SansSC_Bold.ttf。卡片会显示平台、仓库、作者头像、分支、commit、文件变更统计和 commit 正文首段，并支持 light / dark 两种主题。

当最新 commit 命中 Tag 或 Release 时，卡片会补充对应版本信息。检测到分支回退后再次更新时，会合并显示为“仓库回退更新”，并在同一张图里展示回退 commit 和更新 commit。

同一仓库可配置多个分支，commit 轮询会按 platform:owner/repo:branch 独立记录最新 SHA、历史 SHA 和回退状态。

推送目标为 QQBot 官机时，仓库更新和 Webhook Push 会附加操作按钮；“查看版本”在 Release / Tag 有链接时出现。“更新插件”在当前推送仓库匹配本地插件目录、推送分支对应本地当前分支且本地分支具备上游时出现；本地存在 git diff 改动时显示为“强制更新插件”，并发送强制更新命令。其他适配器保持普通图片或文本推送。

快速开始 ​

订阅一个 GitHub 仓库：

text
##githubsub QingYingX-Bot/Git-Plugin

订阅多个仓库：

text
##githubsub owner/repo,owner2/repo2，owner3/repo3、owner4/repo4
##gitsub github owner/repo,owner2/repo2

多个仓库可使用 ,、，、、 分隔。

查询仓库：

text
##githubrepo QingYingX-Bot/Git-Plugin

查询开启 Issue 编号：

text
##githubissue QingYingX-Bot/Git-Plugin

查询某个 Issue：

text
##githubissue QingYingX-Bot/Git-Plugin#1

查询开启 PR 编号：

text
##githubpr QingYingX-Bot/Git-Plugin

通用命令 ​

通用命令通过第一个参数指定平台。

命令说明
#gitrepo github owner/repo查询仓库
#gitissue github owner/repo#1查询 Issue
#gitissue github owner/repo查询开启 Issue 编号列表
#gitpr github owner/repo#1查询 PR
#gitpr github owner/repo查询开启 PR 编号列表
#gitreadme github owner/repo查询 README
#gitlimit查询 API 限流
#gitsub github owner/repo,owner2/repo2订阅一个或多个仓库
#gitunsub github owner/repo取消订阅仓库
#gitlist查看当前会话订阅
#gitlist github查看当前会话指定平台订阅
#gitdefault github owner/repo设置当前会话默认仓库
#gitlink on开启链接自动解析
#gitlink off关闭链接自动解析
#gt帮助查看 Git-Plugin 帮助图
#gt更新 / #git更新更新 Git-Plugin
#gt强制更新 / #git强制更新强制更新 Git-Plugin

Gitea 通用命令需要带实例地址：

text
##gitrepo gitea https://gitea.example.com owner/repo
##gitissue gitea https://gitea.example.com owner/repo#1
##gitpr gitea https://gitea.example.com owner/repo#1
##gitsub gitea https://gitea.example.com owner/repo,owner2/repo2

平台直达命令 ​

平台直达命令使用完整平台名前缀。

平台仓库IssuePRREADME订阅
GitHub#githubrepo owner/repo#githubissue owner/repo#1#githubpr owner/repo#1#githubreadme owner/repo#githubsub owner/repo
Gitee#giteerepo owner/repo#giteeissue owner/repo#I12345#giteepr owner/repo#1#giteereadme owner/repo#giteesub owner/repo
GitCode#gitcoderepo owner/repo#gitcodeissue owner/repo#1#gitcodepr owner/repo#1#gitcodereadme owner/repo#gitcodesub owner/repo
Gitea#gitearepo https://gitea.example.com owner/repo#giteaissue https://gitea.example.com owner/repo#1#giteapr https://gitea.example.com owner/repo#1#giteareadme https://gitea.example.com owner/repo#giteasub https://gitea.example.com owner/repo

只填仓库时，Issue / PR 命令会返回开启编号列表：

text
##githubissue owner/repo
##githubpr owner/repo

编号连续时会压缩显示：

text
1~4, 8, 10~12

订阅推送 ​

订阅目标由命令发送位置决定：

发送位置推送目标
群聊当前群
私聊当前好友

订阅数据按仓库 key 保存：

text
github:owner/repo
gitee:owner/repo
gitcode:owner/repo
gitea:https://gitea.example.com:owner/repo

轮询配置：

yaml
pollingEnabled: true
checkIntervalMinutes: 30

推送模式 ​

配置触发方式推送内容推送目标
pollingEnabled插件定时拉平台 API新增 Issue / PRsubscriptions.json 中的订阅会话
repoUpdate插件定时拉最新 commit分支 commit 更新repoUpdate.list.groups/friends
webhook平台实时回调插件接口Issues / PR / Pushsubscriptions.json 中的订阅会话

repoUpdate 适合没有公网 webhook 地址、只想给固定群或好友推 commit 更新的场景。webhook 适合实时推送，平台仓库页面需要添加 webhook。多个平台、多个仓库可以共用同一个插件 webhook URL；每个仓库需要在对应平台单独添加一次。同一仓库同时启用 repoUpdate 和 webhook 的 push 事件时，commit 更新会重复提醒。

commit 轮询配置示例：

yaml
repoUpdate:
  enabled: true
  cron: "0 */30 * * * *"
  theme: "light"
  list:
    - groups:
        - "1070221868"
      friends: []
      autoScan: false
      exclude: []
      repos:
        - platform: github
          repo: qingyingx-bot/git-plugin
          branch: main
        - platform: github
          repo: qingyingx-bot/git-plugin
          branch: dev
      note: "commit 更新轮询"

QQBot 官机按钮配置示例：

yaml
qqBotButtons:
  enabled: true
  showCommit: true
  showRepo: true
  showCompare: false
  showRelease: true
  showUpdatePlugin: true
  updateAction: "input"
  updateCommand: "#更新{plugin}"

数据文件 ​

运行数据写入 plugins/Git-Plugin/data/：

文件内容
subscriptions.json仓库订阅
defaultRepos.json当前会话默认仓库
linkSettings.json当前会话链接解析开关
lastCheck.json轮询检查时间戳
lastSha.jsoncommit 更新检测的最新 SHA
shaHistory.jsoncommit 更新检测的最近 SHA 记录
pendingRewrite.json分支回退后等待合并推送的记录

data/ 与 config/config/ 默认被 git 忽略。

目录结构 ​

text
apps/                    命令入口
apps/update.js           插件更新快捷命令
components/config.js     配置读取
resources/help.html       帮助图模板
resources/issue-pr-card.html Issue / PR 查询图模板
resources/readme-card.html README 查询图模板
resources/repo-card.html  仓库卡片模板
resources/repo-update-card.html commit 更新卡片模板
resources/fonts/          卡片字体资源
resources/icons/          平台 SVG 图标
model/providers/         平台 Provider
model/formatters/        消息格式化
model/releaseInfo.js     Release / Tag 信息读取
model/repoParser.js      仓库参数解析
model/repoStore.js       订阅和默认仓库存储
model/pollingService.js  轮询推送
model/repoUpdateService.js commit 更新检测
model/webhookServer.js   Webhook 接收

开发说明 ​

新增平台时：

  1. 新增 model/providers/*Provider.js
  2. 在 model/platform.js 注册平台名和显示名
  3. 在 model/providers/index.js 注册 Provider
  4. 在命令层补充平台直达命令
  5. 在 README 和 WEBHOOK_EVENTS.md 补充说明

平台 API 差异放在 Provider 内，命令层只解析消息并调用统一接口。

指令列表 ​

Git-Plugin-更新 ​

  • 描述：无
  • 事件：message
  • 优先级：50
正则表达式处理函数
^\[#/!！\]?(?:gt|git)(?:插件)?(?:安?静)?(?:强制)?更新$update
^\[#/!！\]?(?:gt|git)update$update

Git-Plugin-链接卡片 ​

  • 描述：无
  • 事件：message
  • 优先级：500
正则表达式处理函数
/https?:\\/\\/(?:github\\.com|gitee\\.com|gitcode\\.com)\\/\[^\\s\\/#?\]+\\/\[^\\s\\/#?\]+(?:\[\\/?#\]\[^\\s\]\*)?/iresolveLink

Git-Plugin-帮助 ​

  • 描述：无
  • 事件：message
  • 优先级：500
正则表达式处理函数
^\[#/!！\]?(gt帮助|gthelp|git帮助|githelp)$help

Git-Plugin-查询 ​

  • 描述：无
  • 事件：message
  • 优先级：500
正则表达式处理函数
^\[#/!！\]?(githubrepo|gitcoderepo|giteerepo|gitearepo|gitrepo)\\brepo
^\[#/!！\]?(githubissue|gitcodeissue|giteeissue|giteaissue|gitissue)\\bissue
^\[#/!！\]?(githubpr|gitcodepr|giteepr|giteapr|gitpr)\\bpull
^\[#/!！\]?(githubreadme|gitcodereadme|giteereadme|giteareadme|gitreadme)\\breadme
^\[#/!！\]?(githublimit|gitcodelimit|giteelimit|gitealimit|gitlimit)$rateLimit

Git-Plugin-设置 ​

  • 描述：无
  • 事件：message
  • 优先级：500
正则表达式处理函数
^\[#/!！\]?(githubdefault|gitcodedefault|giteedefault|giteadefault|gitdefault)\\bsetDefault
^\[#/!！\]?gitlink\\bsetLink

Git-Plugin-订阅 ​

  • 描述：无
  • 事件：message
  • 优先级：500
正则表达式处理函数
^\[#/!！\]?(githubsub|gitcodesub|giteesub|giteasub|gitsub)\\bsubscribe
^\[#/!！\]?(githubunsub|gitcodeunsub|giteeunsub|giteaunsub|gitunsub)\\bunsubscribe
^\[#/!！\]?gitlist(?:\\s+(github|gitee|gitcode|gitea))?$list

Git-Plugin-订阅轮询 ​

  • 描述：无
  • 事件：message
  • 优先级：1000

← 返回插件列表

© 2026 阿修Axiu · Axiu Network · 闽ICP备2026017611号-1