插件使用

koishi-plugin-hub-pusl 是一个 Koishi 插件，用于在 QQ 群内推送图片到 Hub 仓库并创建 PR，或随机拉取图片到群内。

安装

将插件目录复制到 Koishi 项目的 external/ 下：

cp -r /path/to/HubPuslBot /path/to/koishi/external/koishi-plugin-hub-pusl
cd /path/to/koishi
npm install ./external/koishi-plugin-hub-pusl

或者使用 npm pack 打包后安装：

cd /path/to/HubPuslBot
npm pack
cd /path/to/koishi
npm install /path/to/HubPuslBot/koishi-plugin-hub-pusl-0.1.0.tgz

配置

配置项	必填	默认值	说明
commandPrefix	否	nwtf	命令前缀，命令为 {prefix}-push 和 {prefix}-pull
githubToken	是	-	GitHub Personal Access Token，需要 repo 权限
githubRepo	是	-	上游仓库，格式：owner/repo
baseBranch	否	main	PR 目标分支
githubMirror	否	""	镜像前缀，用于 pull 下载图片，例如 https://gh-proxy.org/
allowedGroups	否	[]	允许使用的群号列表，为空则允许所有群
adminUsers	否	[]	允许 push 的用户 QQ 号，为空则允许所有人
imageDir	否	images	图片在仓库中的目录
maxFileSize	否	20	最大允许图片大小（MB）
historyPath	否	./hub-pusl-history.json	群拉取记录文件路径

配置示例

plugins:
  hub-pusl:
    commandPrefix: nwtf
    githubToken: ghp_xxxxxxxxxxxx
    githubRepo: NoWayToFix/NWTFhub
    baseBranch: main
    githubMirror: "https://gh-proxy.org/"
    allowedGroups:
      - "123456789"
    adminUsers:
      - "987654321"
    imageDir: images
    maxFileSize: 20

命令

push

nwtf-push <标题> [附带图片]

将图片推送到 Hub 仓库并创建 PR。

• 标题会成为文件名（例如 可爱小猫 → 可爱小猫.png）
• 图片可以随命令发送，也可以引用一条带图片的消息
• 同名文件会被拒绝，需要更换标题
• Bot 会自动 Fork 上游仓库，在 Fork 上创建分支并上传，然后创建跨仓库 PR

示例：

nwtf-push 可爱小猫 [发送一张猫的图片]

Bot 返回：

图片已推送，PR：https://github.com/NoWayToFix/NWTFhub/pull/1

pull

nwtf-pull

从 Hub 仓库随机拉取一张图片发送到群内。

• 不会重复发送已发过的图片
• 所有图片都发过后，自动重置记录循环
• 先发送文件名（例如 可爱小猫.png），再发送图片

示例：

nwtf-pull

Bot 返回：

可爱小猫.png
[图片]

镜像源

如果机器人所在网络无法直连 raw.githubusercontent.com，可以通过 githubMirror 配置镜像前缀。

配置后，pull 下载图片的 URL 格式为：

{mirror}https://github.com/{owner}/{repo}/blob/{branch}/{path}

常用的镜像：

镜像	前缀
gh-proxy.org	https://gh-proxy.org/
GitClone	https://gitclone.com/github.com/

WARNING

镜像源可用性不稳定，请自行测试。如果不配置镜像，插件会直连 raw.githubusercontent.com。

日志

插件使用 Koishi 内置的日志系统，日志标签为 hub-pusl。

如需查看调试日志，在 Koishi 配置中设置：

logger:
  levels:
    hub-pusl: 0   # 0=debug, 1=info, 2=warn, 3=error

工作流程

Push:
  用户发命令 → 下载图片 → 检查重名 → 确保 Fork → 同步 Fork → 创建分支 → 上传文件 → 创建 PR

Pull:
  用户发命令 → 列出上游图片 → 随机选择 → 下载图片 → 发送文件名 + 图片