【插件教程】GitHub统计 插件使用说明

Ulanzi

一、插件介绍
GitHub统计 插件，将 GitHub 仓库的实时数据以精美的图标形式呈现在 Ulanzi Deck 按键上。包含 七个独立监视器，配有实时预览、多色主题、矢量字体渲染和内置多语言教程，支持多语言。
七大主要功能

功能	说明
📊 仓库统计	查看任意公开仓库的星标、复刻、未关闭议题和关注者数量
🏷️ 最新发布	显示最新发布的版本标签、总下载量和发布距今时间
📝 提交活动	统计最近 7 天的提交次数，显示最近贡献者及时间
⚙️ CI / 动作	监控最新 GitHub 动作 运行状态（通过/失败/进行中）
🔀 问题与拉取请求	分别统计未关闭的议题和未关闭的拉取请求数量
👤 用户 / 组织	查看任意用户或组织的资料统计（关注者、仓库数等）
⏱️ API 配额	实时显示 GitHub API 请求配额剩余量及重置倒计时

核心特性

• 按下轮播 — 每个按键一次只展示一个指标，按下按键即可切换到下一个
• 自动刷新 — 可配置刷新间隔（默认 30 分钟），数据实时更新
• 8 种颜色主题 — GitHub / 暗色 / 蓝 / 绿 / 紫 / 橙 / 红 / 青，一键切换
• 4 种矢量字体 — Sans (Roboto) / Mono (Roboto Mono) / Serif (Roboto Slab) / Display (Orbitron)
• 可选 Token 配置 — 无 Token 可查公开数据（约 60 次/小时）；添加 Token 可查私有仓库 + 提升至 5000 次/小时
  

二、安装插件
方式一：通过 Ulanzi Studio 应用商店安装

• 确保 Ulanzi Studio 已更新至 3.1.0 或更高版本
• 启动 Ulanzi Studio 软件
• 点击顶部导航栏的 「应用商店」 图标
• 在搜索框中输入 「GitHub统计」 并回车
• 找到官方插件（作者：Jean Almeida），点击 「安装」
• 安装完成后，在主编辑界面右侧的 「动作列表」 中，可看到新增的 「GitHub统计」 分类，包含 7 个动作
  

方式二：手动安装

• 访问插件 GitHub 仓库：https://github.com/JEAN-ALMEIDA-CZO/GitHub-Repo-Stats-Plugin
• 下载最新 Release 的插件压缩包
• 解压后，将 com.github.repostats.ulanziPlugin 文件夹复制到 Ulanzi Studio 插件目录：
  
  • Windows：C:\Users\你的用户名\AppData\Roaming\Ulanzi\UlanziDeck\Plugins
  • macOS：~/Library/Application Support/Ulanzi/UlanziDeck/Plugins
    
• 重启 Ulanzi Studio，插件将自动加载
  

三、授权与连接（Token 配置）
GitHub统计 插件支持两种使用模式，根据需求选择：
模式一：无需授权（快速开始）

• 适用于查看公开仓库的数据
• 无需任何配置，直接输入仓库名称即可使用
• 限制：受 GitHub API 匿名配额限制，约 60 次/小时，多按键同时使用可能较快耗尽
  

模式二：使用 个人访问令牌（推荐）

• 适用于查看私有仓库数据，或需要更高 API 配额
• 配置后配额提升至 5000 次/小时
  

获取 GitHub Token 步骤

• 打开浏览器，访问：https://github.com/settings/tokens
• 点击 「Generate new token」 → 选择 「Generate new token (classic)」
• 填写 Token 描述，例如：Ulanzi Deck Plugin
• 勾选权限范围（仅需读取公开/私有仓库信息，可只勾选 public_repo 或 repo）
• 滚动到底部，点击 「Generate token」
• ⚠️ 重要： 立即复制生成的 Token 字符串（以 ghp_ 开头），页面刷新后将无法再次查看
  

在插件中配置 Token

• 在 Ulanzi Studio 中，将任意 GitHub统计 动作拖拽到按键上
• 在右侧属性面板中，找到 「身份验证」 区块
• 在 「GitHub Token」 输入框中粘贴你的 Token
• 配置会自动保存并立即生效
  

💡 提示： Token 对所有 7 个动作共用，只需在一个动作中配置一次即可。

四、七大动作详解

4.1 仓库统计功能介绍：

实时显示任意公开仓库的核心指标 —— 星标数、复刻数、未关闭议题数和关注者数。
操作步骤：

• 从右侧动作列表中，将 「仓库统计」 拖拽到任意按键上
• 在右侧属性面板中，找到 「仓库」 区块
• 在输入框中输入仓库名称，格式为 owner/repo（例如：microsoft/vscode）
  
  • ✅ 也可以直接粘贴完整的 GitHub 仓库链接，插件会自动提取 owner/repo
    
• 按键上会居中显示一个指标，并配有对应图标
• 按下按键可在四个指标间切换：
  
  • ⭐ 星标数
  • 🍴 复刻数
  • ⚠️ 未关闭问题
  • 👁️ 关注者
    
• 根据需要设置 「刷新间隔」 和 「外观主题」
  

01

使用技巧：

• 公开仓库无需 Token 即可使用
• 过长的仓库名会自动滚动显示（跑马灯效果）
• 建议将刷新间隔设置为 30 分钟以上，避免频繁请求
  

4.2 最新发布功能介绍：

显示仓库最新发布的版本标签、总下载量以及发布距今的时间。
操作步骤：

• 将 「最新发布」 动作拖拽到按键上
• 输入目标仓库名称（owner/repo 格式）
• 按键默认显示最新发布的版本标签（例如：v3.2.1）
• 按下按键可在三个指标间切换：
  

• 🏷️ 版本号
• ⬇️ 总下载量—— 所有发布文件的下载次数之和
• 📅 发布时间—— 显示"约 X 天前"或具体日期
  

02

使用技巧：

• 若仓库尚未发布任何版本，按键显示 —
• 下载量统计包含所有 发布资产 的下载次数总和
• 按设定的刷新间隔自动检查是否有新版本发布
  

4.3 提交活动功能介绍：

统计仓库最近 7 天的提交次数，并显示最近一次提交的作者和时间。
操作步骤：

• 将 「提交活动」 动作拖拽到按键上
• 输入目标仓库名称
• 按键默认显示最近 7 天内的提交总数
• 按下按键可切换查看：
  

• 📝 提交次数
• 👤 最近提交作者
• 🕐 最近提交时间
  

03

使用技巧：

• 显示 100+ 表示 7 天内提交超过 100 次（已达 GitHub API 单页上限）
• 非常适合用来判断一个项目当前是否处于活跃开发状态
• 私有仓库需要配置 Token 才能查看
  

4.4 CI / 活动功能介绍： 实时监控仓库最新的 GitHub 活动 工作流运行状态。
操作步骤：

• 将 「CI / 活动」 动作拖拽到按键上
• 输入目标仓库名称
• 按键以颜色 + 图标直观显示最新工作流状态：
  
  • 🟢 绿色 ✓ = 通过
  • 🔴 红色 ✗ = 失败
  • 🟡 黄色 = 进行中
  • ⚪ 灰色 = 无运行记录或离线
    
• 按下按键可切换查看：
  
  • ⚙️ 运行状态
  • 🕐 最近运行时间
    

04

使用技巧：

• 公开仓库无需 Token 即可使用
• 为提升查询速度，已自动排除由 PR 触发的运行记录
• 建议为 CI 监控设置较短的刷新间隔（如 5-10 分钟），实时掌握构建状态
  

4.5 问题与拉取请求功能介绍： 分别统计仓库中未关闭的 问题 和未关闭的 拉取请求 数量。
操作步骤：

• 将 「问题 & 拉取请求」 动作拖拽到按键上
• 输入目标仓库名称
• 按键默认显示未关闭的议题数量
• 按下按键可在两类数据间切换：
  
  • 🔵 未关闭问题
  • 🟣 未关闭拉取请求
    

05

使用技巧：

• 两类数据各自配有独立图标，一眼可辨
• 数据来源于 GitHub Search API，统计准确
• 活跃的开源项目建议设置较短刷新间隔，及时掌握社区动态
  

4.6 用户 / 组织功能介绍：

查看任意 GitHub 用户或组织的资料统计数据。

⚠️ 注意： 此动作的输入项与其他动作不同，需要切换为用户名（而非 owner/repo）

操作步骤：

• 将 「用户/组织」 动作拖拽到按键上
• 在属性面板中找到 「账号」 区块
• 在输入框中输入 GitHub 用户名（例如：torvalds，无需输入 @ 符号）
• 按键默认显示用户的关注者数量
• 按下按键可切换查看：
  
  • 👥 关注者
  • 📦 公开仓库数
  • 📝 Gist 数量
  • 👤 正在关注
    

06

使用技巧：

• 用户名和组织名均支持（例如：输入 google 可查看 Google 组织的数据）
• 非常适合用来追踪自己 GitHub 账号的成长情况
• 输入时无需加 @ 前缀
  

4.7 API 限制功能介绍： 实时显示当前 GitHub API 请求配额的剩余量，以及配额重置倒计时。
操作步骤：

• 将 「API限制」 动作拖拽到按键上
• 若已配置 Token，在「身份验证」区块确认 Token 已填写
• 按键默认显示 剩余请求数 / 配额上限（例如：4823 / 5000）
• 按下按键可切换查看：
  
  • 📊 剩余请求数
  • ⏰ 配额重置倒计时
    

07

使用技巧：

• 无 Token 时，配额上限约为 60 次/小时
• 添加 Token 后，配额上限提升至 5000 次/小时
• 当配额剩余不足 10% 时，按键会自动以警告色提醒
• 同时运行多个监视器时，建议将此动作放在控制面板上，随时掌握 API 使用情况
  

五、个性化设置每个 GitHub统计 动作都支持丰富的个性化配置，让你的按键面板独一无二。
5.1 刷新间隔

• 控制数据自动更新的频率，单位为分钟
• 建议设置：
  
  • 仓库统计 / 用户统计：30~60 分钟（数据变化不频繁）
  • CI 状态监控：5~10 分钟（需要较及时的反馈）
  • API 配额监控：15~30 分钟
    
• 设置完毕后，点击属性面板中的 「立即刷新」 按钮可手动触发一次数据更新
  

5.2 颜色主题插件内置 8 种精心设计的颜色主题，点击色卡即可切换。
5.3 矢量字体插件内置 4 种高质量矢量字体。
5.4 动画效果

• 开启后，按键图标上会显示一道扫描线动画，循环扫过按键表面
• 动画效果类似科幻界面中的雷达扫描，增加视觉吸引力
• 若追求简洁风格或需要节省性能，可关闭此选项
  

5.5 实时预览

• 属性面板顶部提供 128×128 实时预览区域
• 每次修改配置（主题、字体、动画等），预览区域会自动更新
• 预览数据使用演示数据，仅用于展示效果，非真实 GitHub 数据
• 预览每 120ms 自动轮播不同指标，展示完整的按键效果
  

六、常见问题排查
6.1 按键显示「未找到」或离线图标可能原因：

• 输入的仓库名或用户名拼写错误
• 仓库为私有仓库但未配置 Token
• 仓库已被删除或重命名
  

解决方法：

• 检查 用户/组织 格式是否正确（注意大小写，GitHub 用户名区分大小写）
• 若为私有仓库，请在「身份验证」区块配置 GitHub Token
• 直接在浏览器访问 https://github.com/owner/repo，确认仓库存在
  

6.2 按键显示「速率限制」错误可能原因：

• GitHub API 配额已耗尽（匿名用户约 60 次/小时，认证用户 5000 次/小时）
• 同时运行了过多监视器按键，请求过于频繁
  

解决方法：

• 在「身份验证」区块配置 GitHub 个人访问令牌，将配额提升至 5000 次/小时
• 适当增大刷新间隔（建议不低于 30 分钟）
• 将「API Rate Limit」动作添加到面板，实时监控配额使用情况
• 配额将在整点（UTC 时间）自动重置
  

6.3 按下按键没反应可能原因：

• 插件未正确加载
• 按键未被正确配置
  

解决方法：

• 确认 Ulanzi Studio 已更新至 3.1.0 或更高版本
• 在「应用商店」中检查插件是否为最新版本，点击「更新」若有可用更新
• 删除按键，重新拖拽动作配置一次
• 重启 Ulanzi Studio
  

6.4 Token 配置后仍然无法访问私有仓库可能原因：

• Token 权限不足
• Token 已过期或被撤销
  

解决方法：

• 访问 https://github.com/settings/tokens，确认 Token 状态为 Active
• 若私有仓库属于个人账号，Token 需勾选 repo 权限范围
• 若私有仓库属于组织，还需在组织中授权此 Token
• 重新生成 Token 并配置到插件中
  

6.5 长用户名或仓库名显示不完整说明：

这是正常行为，插件已内置跑马灯效果。

• 当文本内容超出按键宽度时，会自动以 120ms 每帧的速度滚动显示
• 滚动方向为从右至左，循环播放
• 无需任何配置，插件会自动检测是否需要滚动
  

6.6 如何同时监控多个仓库？

方法：为每个仓库分别创建按键。

• 将「仓库统计」动作多次拖拽到不同按键上
• 为每个按键配置不同的 用户/组织
• 所有按键独立运行，互不影响
• 建议将相关仓库的按键放在同一页面，方便一览
  

💡 提示： 同时监控大量仓库时，请注意 API 配额限制，建议配置 Token。

七、获取更多帮助

• 🌐 插件 GitHub 仓库：https://github.com/JEAN-ALMEIDA-CZO/GitHub-Repo-Stats-Plugin
• 🔧 问题反馈：在 GitHub 仓库中提交 Issue