maraino/gh-inbox

来源：https://github.com/maraino/gh-inbox

gh-inbox

一个 GitHub CLI (https://cli.github.com) 扩展，用于清理你的通知收件箱：按仓库、类型、原因、时长、状态或相关人批量将通知标记为已完成或已读，或取消订阅。

``console $ gh inbox list 查看审查请求、预览并清理已合并和已关闭的通知，以及分类处理 issue

$ gh inbox clean –state merged,closed 将标记 1835 条通知为已完成。 1835 条通知 按仓库分组 321 acme/gitops 132 acme/agent … 再次运行并添加 –apply 执行操作，或添加 –list 查看每条通知。

$ gh inbox clean –state merged,closed –apply 已将 1835 条通知标记为已完成。

## 安装

```sh
gh extension install maraino/gh-inbox

或者，使用 Go 1.26.7 或更高版本：

go install github.com/maraino/gh-inbox@latest

go install 会将 gh-inbox 二进制文件放入你的 GOBIN。你可以直接以 gh-inbox 运行，或安装为扩展以便使用 gh inbox 命令：

git clone https://github.com/maraino/gh-inbox && cd gh-inbox && gh extension install .

gh-inbox 使用你的 gh 登录凭据。你的 token 需要 notifications 或 repo scope，如果需要按团队或 @me 过滤审查请求，还需要 read:org。

GitHub Enterprise Server

使用 gh 登录到主机，然后通过 --hostname 传入，或设置 GH_HOST：

gh auth login --hostname github.example.com
gh inbox --hostname github.example.com list --summary

gh 也可以从 GH_ENTERPRISE_TOKEN 获取 token。已标记为完成的通知记录按主机分别保存。

使用方式

gh inbox list [filters | --rule name[,name] | --rules] [--sort key[,key]] [--reverse] [--limit n] [--json | --summary]

gh inbox clean [filters] [--action done|read|unsubscribe] [--apply] [--all] [--list [--sort key[,key]] [--reverse]]

gh inbox clean --rule name[,name] | --rules [--rules-file file] [--apply] [--list [--sort key[,key]] [--reverse]]

gh inbox triage [filters | --rule name[,name] | --rules] [--sort key[,key]] [--reverse]

gh inbox unwatch [owner/name...] [--apply]

list 显示匹配过滤器的通知，按最近更新优先排列。clean 对它们执行操作：除非传入 --apply，否则只显示将要执行的操作；除非传入 --all，否则拒绝操作全部通知。它显示所操作通知的摘要，或配合 --list 逐条显示，与 list 一样。triage 逐条浏览：按 o 在浏览器中打开，d 标记为已完成，r 标记为已读，u 取消订阅，s 跳过，p 返回上一条，q 退出。请求运行期间按下的键会被忽略，粘贴的文本和带 Alt 的按键也会被忽略，因此误触不会影响下一条通知。unwatch 取消关注仓库，通知中 subscribed 原因的来源就是关注的仓库。不带参数时，列出这些仓库，通知最多的优先；传入名称或 * 通配符时，显示将要取消关注的仓库，并通过 --apply 执行。你参与或被提及的讨论仍会通知你，收件箱中已有的通知会保留到你清理它们为止。

list、triage 和 clean --list 按最近更新优先排列。--sort 可按 updated（最新优先）、repo、type、reason 或 state（open、draft、merged、closed，然后是未知）排序。使用多个键时（如 --sort repo,state），后续键打破平局，其余通知仍按最近更新优先。--reverse 反转排序。

过滤器

• 多值过滤器（逗号分隔或重复指定）匹配任意一个值即命中。取反的过滤器在没有任何值匹配时命中。通知必须匹配每一个过滤器。
• 涉及人员的过滤器接受登录名或 @me。审查请求的过滤器还接受 org/team，且 @me 包含你所在的团队。
• GitHub 在审查提交后会移除审查请求，因此 --review-requested @me 匹配你仍欠的审查，而 --reason review_requested 匹配所有因你被请求审查而发出的通知。
• Pull Request 或 issue 的状态或人员过滤器不匹配其他类型的通知（如 CI 运行）。无法再读取的 Pull Request 和 issue 会被跳过并列出。

规则

你可以将重复执行的清理操作保存为规则，存放在 ~/.config/gh-inbox/rules.yml（或 $XDG_CONFIG_HOME/gh-inbox/rules.yml）。每条规则有一个名称、一个操作（默认为 done），以及与标志同名同值的过滤器：

rules:
  - name: merged
    filters:
      state: [merged, closed]

  - name: stale-ci
    action: read
    filters:
      type: ci
      older-than: 7d

  - name: noisy-repos
    action: unsubscribe
    filters:
      repo: ["acme/infra", "acme/docs-*"]
      reason: subscribed

examples/rules.yml 是一个可供复制的起点。gh inbox clean --rules 应用所有规则，--rule merged,stale-ci 只应用指定名称的规则。与过滤器一样，不加 --apply 则什么也不会发生。gh inbox list 和 gh inbox triage 也接受 --rule 和 --rules，用于显示或逐条浏览规则将要操作的通知。

规则按文件中的顺序应用，一条通知只交给第一个匹配它的规则。规则必须有过滤器，任何一条规则有误都会在执行前阻止所有规则。

示例

# 查看收件箱内容，按仓库、类型、原因和状态分组
gh inbox list --summary

# 等待你或你的团队审查的 Pull Request
gh inbox list --state open --review-requested @me

# 逐条浏览你欠的审查
gh inbox triage --state open --review-requested @me

# 过去一天发生了什么
gh inbox list --newer-than 24h

# 查看你关注的哪些仓库填满了收件箱，并取消关注其中一个
gh inbox unwatch
gh inbox unwatch acme/infra --apply

# 带有 dependencies 标签的草稿 Pull Request
gh inbox list --draft --label dependencies

# 将已合并和已关闭的 Pull Request 和 issue 标记为已完成
gh inbox clean --state merged,closed --apply

# 应用所有已保存的规则，例如在 cron 中使用
gh inbox clean --rules --apply

# 打开既未指派给你也未等待你审查的 Pull Request
gh inbox clean --type pr --state open --not-involves @me --apply

# 将超过一周的 CI 通知标记为已读
gh inbox clean --type ci --older-than 7d --action read --apply

# 取消订阅仅因关注仓库而关注的讨论
gh inbox clean --repo 'acme/*' --reason subscribed --action unsubscribe --apply

已完成的通知

将通知标记为完成会将其从收件箱中移除。在 github.com 上它会出现在 “Done” 筛选器下，有新活动时会重新出现。API 仍会列出已完成的通知，且无法与已读通知区分。因此 gh-inbox 会将它标记为完成的通知记录在 ~/.local/state/gh-inbox//done.json（或 $XDG_STATE_HOME 下），并在有新活动之前跳过它们。在其他地方（如 github.com）标记为完成的通知不在记录中，clean 会再次将它们标记为完成，这没有影响。--no-cache 会忽略此记录。

缓存

为了让连续运行多个命令更快，gh-inbox 将 API 响应缓存在 ~/.cache/gh-inbox/（或 $XDG_CACHE_HOME 下）：

• 通知列表在 GitHub 确认没有新内容的情况下最多复用 10 分钟，此确认不计入速率限制。使用 gh-inbox 标记通知为已完成或已读、或取消订阅会生成新的列表。在 github.com 上已读的通知在列表刷新前可能仍显示为未读。
• Pull Request 或 issue 的详细信息（如状态和标签）在其通知无新活动时最多复用一小时。某些更改（如新增标签）不算活动。

--no-cache 会忽略缓存以及已完成通知的记录；它获取的响应仍会更新缓存。

其他标志

触发速率限制或临时服务器错误的请求会自动重试。

开发

make          # lint、测试和构建
make test     # 测试，启用竞态检测器；RACE= 可关闭
make lint     # golangci-lint
make fmt      # 格式化代码
make govulncheck
make install  # 构建并安装工作区作为 gh 扩展
make demo     # 录制 demo/demo.gif；需要带 Pillow 的 Python 3

golangci-lint 和 govulncheck 是 Go 工具依赖，go tool 会运行 go.mod 中固定的版本。代码位于 internal/：

demo/ 录制了上面的 GIF。demo/fakeapi 为 github.localhost 主机提供模拟收件箱，capture.py 在伪终端中运行命令，render.py 绘制帧。

许可证

MIT