mcpField
G
github-projects

github-projects

github.com/existential-birds生产力85120 次安装11 周前更新
代码仓库

关于 github-projects

通过 `gh project` 命令管理 GitHub Projects v2 的技能，涵盖项目、关联事项和自定义字段操作，并为删除等高影响操作设置核验步骤。

主要功能

  1. 01列出、查看和创建项目
  2. 02修改项目设置并关联仓库或团队
  3. 03添加、编辑、归档和删除事项
  4. 04创建及管理自定义字段
  5. 05支持 JSON 输出与 jq 查询
  6. 06执行高影响操作前核验目标

适用场景

  1. 01将 issue 或 PR 加入项目并更新字段
  2. 02批量添加仓库中的开放 issue
  3. 03管理项目字段和仓库或团队关联

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/existential-birds/beagle --skill github-projects

安装后在 Claude Code 中输入/github-projects确认已加载。

附带文件references/fields.mdreferences/items.md

详细介绍

GitHub Projects CLI

通过 gh project 命令管理 GitHub Projects (v2)。需要 project scope，可通过 gh auth refresh -s project 添加。

前提条件

确认身份验证包含 project scope：

gh auth status  # Check current scopes
gh auth refresh -s project  # Add project scope if missing

闸门（具有破坏性和重大影响）

project close、project unlink、item-archive、item-delete 和 field-delete 等命令会更改或移除数据。请按顺序进行检查，不要依赖之前轮次中的记忆。

  1. 通过： 运行 gh project view PROJECT_NUM --owner OWNER（或 gh project list --owner OWNER --format json），并确认 title（或 JSON 中的 title）与目标项目相符。
  2. 通过： 对于条目和字段，ITEM_ID、FIELD_ID、PROJECT_ID 和选项 ID 只能使用本会话中通过 gh project item-list … --format json 或 gh project field-list … --format json 获取的值，不得猜测、截断或从无关输出中复制。
  3. 然后运行具有破坏性的子命令。
批量添加（管道）
  1. 通过： 对单个 --url 运行一次 gh project item-add，并确认该条目出现在 gh project item-list … --format json（或 UI）中，然后再对多个 URL 使用 xargs 或循环。

快速参考

列出和查看项目
# List your projects
gh project list

# List org projects (including closed)
gh project list --owner ORG_NAME --closed

# View project details
gh project view PROJECT_NUM --owner OWNER

# Open in browser
gh project view PROJECT_NUM --owner OWNER --web

# JSON output with jq filtering
gh project list --format json | jq '.projects[] | {number, title}'
创建和编辑项目
# Create project
gh project create --owner OWNER --title "Project Title"

# Edit project
gh project edit PROJECT_NUM --owner OWNER --title "New Title"
gh project edit PROJECT_NUM --owner OWNER --description "New description"
gh project edit PROJECT_NUM --owner OWNER --visibility PUBLIC

# Close/reopen project
gh project close PROJECT_NUM --owner OWNER
gh project close PROJECT_NUM --owner OWNER --undo  # Reopen
将项目关联到仓库
# Link to repo
gh project link PROJECT_NUM --owner OWNER --repo REPO_NAME

# Link to team
gh project link PROJECT_NUM --owner ORG --team TEAM_NAME

# Unlink
gh project unlink PROJECT_NUM --owner OWNER --repo REPO_NAME

项目条目

添加现有议题/PR
# Add issue to project
gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/issues/123

# Add PR to project
gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/pull/456
创建草稿条目
gh project item-create PROJECT_NUM --owner OWNER --title "Draft item" --body "Description"
列出条目
# List items (default 30)
gh project item-list PROJECT_NUM --owner OWNER

# List more items
gh project item-list PROJECT_NUM --owner OWNER --limit 100

# JSON output
gh project item-list PROJECT_NUM --owner OWNER --format json
编辑条目

通过 ID 编辑条目（通过 item-list --format json 获取）。

# Edit draft issue title/body
gh project item-edit --id ITEM_ID --title "New Title" --body "New body"

# Update field value (requires field-id and project-id)
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --text "value"
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --number 42
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --date "2024-12-31"
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --single-select-option-id OPTION_ID
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --iteration-id ITER_ID

# Clear field value
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --clear
归档/删除条目
gh project item-archive PROJECT_NUM --owner OWNER --id ITEM_ID
gh project item-delete PROJECT_NUM --owner OWNER --id ITEM_ID

项目字段

列出字段
gh project field-list PROJECT_NUM --owner OWNER
gh project field-list PROJECT_NUM --owner OWNER --format json
创建字段
# Text field
gh project field-create PROJECT_NUM --owner OWNER --name "Notes" --data-type TEXT

# Number field
gh project field-create PROJECT_NUM --owner OWNER --name "Points" --data-type NUMBER

# Date field
gh project field-create PROJECT_NUM --owner OWNER --name "Due Date" --data-type DATE

# Single select with options
gh project field-create PROJECT_NUM --owner OWNER --name "Priority" \
  --data-type SINGLE_SELECT \
  --single-select-options "Low,Medium,High,Critical"
删除字段
gh project field-delete --id FIELD_ID

常见工作流

添加议题并设置状态
# 1. Add issue to project
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/123

# 2. Get item ID and field IDs
gh project item-list 1 --owner "@me" --format json | jq '.items[-1]'
gh project field-list 1 --owner "@me" --format json

# 3. Update status field
gh project item-edit --id ITEM_ID --project-id PROJECT_ID \
  --field-id STATUS_FIELD_ID --single-select-option-id OPTION_ID
批量添加议题
# Add all open issues from a repo
gh issue list --repo owner/repo --state open --json url -q '.[].url' | \
  xargs -I {} gh project item-add 1 --owner "@me" --url {}

JSON 输出和 jq 模式

# Get project IDs
gh project list --format json | jq '.projects[] | {number, id, title}'

# Get field IDs and options
gh project field-list 1 --owner "@me" --format json | jq '.fields[] | {id, name, options}'

# Get item IDs with field values
gh project item-list 1 --owner "@me" --format json | jq '.items[] | {id, title, fieldValues}'

# Filter items by status
gh project item-list 1 --owner "@me" --format json | \
  jq '.items[] | select(.status == "In Progress")'

参考文件

  • items.md：条目管理、编辑字段值、批量操作
  • fields.md：字段类型、创建自定义字段、选项管理

命令摘要

命令用途
project list列出项目
project view查看项目详情
project create创建新项目
project edit修改项目设置
project close关闭/重新打开项目
project link/unlink关联到仓库/团队
project item-add添加现有议题/PR
project item-create创建草稿条目
project item-list列出项目条目
project item-edit更新条目字段
project item-archive归档条目
project item-delete移除条目
project field-list列出项目字段
project field-create添加自定义字段
project field-delete移除字段

评论

支持 Markdown