GitHub CLI 怎样用 JSON 输出批量筛选 issue

GitHub CLI 可以通过 gh issue list --json 字段列表 输出结构化数据，再用内置 --jq 筛选。先用仓库、状态和标签缩小查询范围，再从返回的数组里选记录，最后决定给脚本传 JSON 数组还是逐行编号，比拆终端表格更稳定。

官方地址：https://cli.github.com/

下面以“从指定仓库查询开放的 bug，再挑出尚未分配人员的条目”为例。命令中的 OWNER/REPO 必须替换为有访问权限的仓库；示例使用 Bash 类 shell 的引号和续行写法。本文提供操作方法与预期结构，不声称已查询某个真实仓库。

1. 先确定仓库、状态与返回字段

安装 GitHub CLI 并完成授权后，在命令行入口使用 gh issue list。CLI 没有可点击的 JSON 筛选菜单，实际入口就是参数。显式写 --repo，可以避免从当前 Git 目录误推断仓库。

# 获取指定仓库中最多200条开放的bug，字段按后续筛选需要选择
gh issue list --repo OWNER/REPO \
  --state open --label bug --limit 200 \
  --json number,title,assignees,url

返回内容应是一个 JSON 数组；每项含编号、标题、分配人员数组和地址。没有符合条件的记录时，数组可为空。不同仓库的标签名称并不统一，先确认确实有 bug 标签，不能把空结果直接解释为没有任何待办。

默认最多取三十条，因此需要明确 --limit。这里的二百只是本次上限，不代表完整导出全仓库。后面的 jq 仅处理已经取回的数据，如果相关条目没有进入这批结果，调整 jq 表达式也找不到它。

2. 在内置 jq 中筛选，并保留数组形状

在同一命令上追加 --jq。未分配人员对应 assignees 数组长度为零；外层方括号把筛选后的对象收集成一个新数组。

# 在已获取的issue中筛选未分配记录，并保留稳定的JSON数组输出
gh issue list --repo OWNER/REPO \
  --state open --label bug --limit 200 \
  --json number,title,assignees,url \
  --jq '[.[] | select((.assignees | length) == 0) | {number, title, url}]'

表达式里的 .[] 逐项访问数组，select 决定保留哪些对象，最后只留下交付脚本需要的字段。输出里不再有 assignees，不影响筛选，因为该字段已经在 --json 中请求并用于条件判断。

内置 --jq 不要求另装 jq 程序，但它必须配合 --json 和所需字段使用。字段名称与普通表格列标题不是一回事，应以 gh issue list --help 及官方 JSON Fields 为准。拼错字段或未请求嵌套字段，应该修正字段列表，而不是用文本搜索去补救。

3. 将结果保存为脚本约定的输入

如果下游程序读取 JSON，保留数组最容易处理。下面把查询结果先放进临时文件，命令成功后才替换最终文件，避免失败的请求覆盖上一份有效结果。

# Bash示例：失败时保留旧文件，不把请求失败当成空结果
task_output=$(mktemp) || exit 1
if gh issue list --repo OWNER/REPO \
  --state open --label bug --limit 200 \
  --json number,title,assignees,url \
  --jq '[.[] | select((.assignees | length) == 0) | {number, title, url}]' \
  > "$task_output"; then
  mv "$task_output" selected-issues.json
else
  rm -f "$task_output"
  printf '%s\n' 'issue查询失败，保留原结果文件' >&2
  exit 1
fi

若下游只接受一行一个编号，可以让表达式输出 number。以下命令会覆盖同名文本文件，适合独立输出；需要保留上一份结果时，可套用前面的临时文件方式。

# 只输出整数编号，不让标题中的空格或换行影响后续读取
gh issue list --repo OWNER/REPO \
  --state open --label bug --limit 200 \
  --json number,assignees \
  --jq '.[] | select((.assignees | length) == 0) | .number' \
  > issue-numbers.txt

JSON 数组空结果是 []；逐行编号在没有匹配记录时可能是空文件。两者都必须建立在命令成功的前提下。读取编号时，不要将 issue 标题拼接成可执行命令；如果以后扩展为关闭、打标签或修改 issue 的批量操作，应另行确认操作范围，这篇只导出数据。

结果太少、字段为空时怎么判断

如果目标条件本身支持远端搜索，例如未分配人员，应优先用 --search 'no:assignee' 缩小获取范围，再用 JSON 做投影与后处理；这样能减少先取有限条数再过滤所造成的遗漏。即便如此，显式上限仍然存在，不能把一次有限查询称为完整仓库清单。

批量筛选的关键是确定数据契约：仓库和状态决定候选范围，字段列表决定哪些数据可用，jq 决定保留记录与输出形状。把这三层分开保存，脚本后续需要增加字段或改变条件时，就不必重新依赖终端表格的视觉布局。

参考：issue list 官方手册；JSON 与 jq 格式化说明。