project-archive-done

用途

该技能用于整理 GitHub Project 看板：把状态为 Done 的项目条目批量归档，减少看板上已完成条目的堆积。同时它也会检查并说明 GitHub 内置的 Auto-archive 工作流的设置情况，若该工作流已启用，则通常不需要手动执行归档。

前提条件

• 目标 GitHub Project 中存在已完成（Done）的条目。
• 已安装并认证 gh CLI，且具备 project 权限（project スコープ付き）。

使用方式与流程

Step 1：确认 Auto-archive 状态

内置 Auto-archive 工作流启用时会自动归档，因此需向用户确认设置情况。

设置 URL：

• 组织项目：https://github.com/orgs/<owner>/projects/<number>/workflows
• 个人项目：https://github.com/users/<owner>/projects/<number>/workflows

判断分支：

• Auto-archive 已启用 → 基本无需执行该技能，仅在需要立即归档时继续。
• Auto-archive 未启用 → 用该技能执行手动归档，并视需要建议开启 Auto-archive。

Step 2：获取项目条目

gh project item-list <number> \
  --owner <owner> \
  --format json \
  --limit 999

Step 3：获取字段元数据

gh project field-list <number> \
  --owner <owner> \
  --format json

据此定位 Status 字段的 ID 以及 "Done" 选项的 ID。

Step 4：筛选已完成条目

从 Step 2 的结果中提取 Status 为 "Done" 的条目。若 --query 可用：

gh project item-list <number> \
  --owner <owner> \
  --query "status:Done" \
  --format json

Step 5：向用户确认

展示归档对象，例如：

以下の N 件の完了アイテムをアーカイブします:
- #42: feat: ソーシャルログイン（Done）
- #43: fix: バリデーションエラー（Done）
- #44: docs: API ドキュメント更新（Done）

実行しますか？

Step 6：执行归档

对每个条目执行：

gh project item-archive <number> \
  --owner <owner> \
  --id <item-id>

Step 7：报告结果

报告内容包括：

• 已归档：N 件
• 剩余活动条目：M 件
• 看板上的已完成条目：0 件

若 Auto-archive 未启用，建议开启：

推奨: Auto-archive を有効にすると、Done から N 日経過したアイテムが自動でアーカイブされます。
設定: <workflows URL>

验证

Step 7 完成后，可用以下命令确认归档结果：

gh project item-list <number> --owner <owner> --format json --limit 999

若 Status 为 "Done" 的条目已从列表中消失，即表示完成。已归档条目并未被删除，可通过 gh project item-archive --undo 恢复。

适用场景

• 完成条目较多、需要整理看板时。
• 希望按特定条件（日期范围、标签等）筛选后归档。
• 触发用语示例：「完了アイテムをアーカイブ」「Done を整理」「ボード掃除」。

限制与注意事项

• 归档前必须获得用户确认。
• 归档可撤销（gh project item-archive --undo）。
• 归档条目只是从项目视图中隐藏，并不会被删除。
• 与内置 Auto-archive 工作流配合使用，可减少手动执行频率。
• 该技能依赖对 GitHub 的网络操作（gh project item-archive）。在 sandbox 环境中，需要将该命令按命令粒度以禁用 sandbox 的方式执行；在无法解除网络隔离的环境中无法运行。