project-view-status

用途

project-view-status 是一个只读型技能，用于汇总 GitHub Project 的进度并生成报告。它按状态（Status）、优先级（Priority）、规模（Size）对项目条目进行统计，输出完成率以及未完成条目的优先级明细，并以表格形式呈现。

主要能力

获取项目信息：标题、描述、URL。
获取全部条目，并按状态、优先级、规模进行分组统计。
计算完成率（done / n）。
输出未完成条目（Status 非 Done，含未设置）的优先级、规模以及状态×优先级交叉统计。
生成包含整体进度、状态别、优先级别（仅未完成）、规模别（仅未完成）的表格报告。

使用方式

前提条件：

目标 GitHub Project 存在。
已安装 gh CLI 并完成认证（带 project 权限范围）。
统计使用 gh 的 --jq（内置 jq），无需另行安装 jq。

流程：

获取项目信息：gh project view <number> --owner <owner> --format json，取得标题、描述、URL。
获取全部条目：先取得 totalCount，再将其作为 --limit 传入，避免固定 --limit 导致分页截断、总件数/明细/完成率出错。示例：

total=$(gh project item-list <number> --owner <owner> --limit 1 --format json --jq '.totalCount')
[[ "${total}" =~ ^[0-9]+$ ]] || { echo "totalCount の取得に失敗した。中止する" >&2; exit 1; }
[ "${total}" -eq 0 ] && { echo "アイテム 0 件"; exit 0; }

获取字段定义：gh project field-list <number> --owner <owner> --format json，取得 Status、Priority、Size 字段的定义与选项值。
按状态、优先级统计：将 Step 2 确认的 ${total} 作为 --limit，仅获取一次，并用同一个 --jq 表达式一次性算出全部统计（避免同一报告内快照混用，不重复多次获取）。示例：

gh project item-list <number> --owner <owner> --limit "${total}" --format json \
  --jq '{
    total: .totalCount,
    n: (.items | length),
    by_status: ([.items[] | .status // "(未設定)"] | group_by(.) | map({key: .[0], count: length})),
    open_by_priority: ([.items[] | select(.status != "Done") | .priority // "(未設定)"] | group_by(.) | map({key: .[0], count: length})),
    open_by_size: ([.items[] | select(.status != "Done") | .size // "(未設定)"] | group_by(.) | map({key: .[0], count: length})),
    open_status_x_priority: ([.items[] | select(.status != "Done") | {status: (.status // "(未設定)"), priority: (.priority // "(未設定)")}] | group_by(.) | map({key: .[0], count: length})),
    done: ([.items[] | select(.status == "Done")] | length)
  }'

由于只获取一次，结果是获取时点的一致快照；若 Step 2 之后条目增加并超过 --limit "${total}"，会出现遗漏，此时输出的 total（.totalCount）与 n（.items | length）不一致（total > n），应视为不完整统计，停止处理并向用户报告（是否重跑由报告后决定）。若某字段在 Step 3 的 field-list 中不存在，则全件为 (未设置)，应跳过该字段对应的小节。完成率由 done / n 算出。open_by_priority、open_by_size、open_status_x_priority 按 Step 5 的格式（优先级别、规模别仅统计未完成），只统计 Status 非 Done（含未设置）的条目。模型将计算结果整理成表格，若存在明显偏斜则加以评论。

生成报告，格式如下：

## プロジェクト進捗レポート: <タイトル>

**更新日時:** YYYY-MM-DD HH:MM

### 全体進捗
- 総アイテム数: N 件
- 完了率: XX% (N/M)
- 進行中: N 件
- レビュー中: N 件
- 未着手: N 件

### ステータス別

| ステータス | 件数 | 割合 |
|-----------|------|------|
| Done | N | XX% |
| In Review | N | XX% |
| In Progress | N | XX% |
| Todo | N | XX% |

### 優先度別（未完了のみ）

| 優先度 | 件数 | In Progress | Todo |
|--------|------|------------|------|
| High | N | N | N |
| Medium | N | N | N |
| Low | N | N | N |

### サイズ別（未完了のみ）

| サイズ | 件数 |
|--------|------|
| XL | N |
| L | N |
| M | N |
| S | N |
| XS | N |

适用场景

需要查看项目整体进度与完成率时。
需要按状态统计件数、按优先级查看未完成明细时。
需要生成项目报告时。

限制与注意事项

--limit 不使用固定值，而传入 totalCount（Step 2 取得的 ${total}），以防分页截断。
属于只读操作，不会修改项目。
字段不存在时跳过对应小节。
条目为 0 件时报告该情况。
需要网络（仅读取）。

验证：Step 5 的报告输出中包含总条目数与完成率、状态别与优先级别的件数统计，且项目未被修改（只读），即视为完成。

sandbox 环境下的执行：Step 1〜4 的 gh project view / gh project item-list / gh project field-list（含 Step 4 的统计获取）均为对 GitHub API 的读取，需要网络，应按命令单位在禁用 sandbox 的情况下执行。本技能不进行任何写入（不修改项目、不写入工作区外）。仅 Step 5 的报告格式化属于本地处理，不需要网络。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项