ghpm-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ghpm-init

PREREQUISITE: Read
../ghpm-shared/SKILL.md
for prerequisites and error handling.

Initialize a GitHub Projects v2 project for use with ghpm skills. Auto-discovers schema and generates config files.

前提条件： 阅读
../ghpm-shared/SKILL.md
了解前提条件和错误处理。

为配合ghpm技能使用，初始化GitHub Projects v2项目。自动发现架构并生成配置文件。

Arguments

参数

Project URL (e.g.,

https://github.com/orgs/<org>/projects/<number>

)

If no arguments, ask the user for the project URL or owner + number.

项目URL（例如：

https://github.com/orgs/<org>/projects/<number>

）

如果未提供参数，询问用户项目URL或所有者+项目编号。

Workflow

工作流程

Phase 1: Validate Access

阶段1：验证访问权限

Parse arguments to extract owner and project number from URL or positional args.
Run
```
gh auth status
```
to verify authentication. If this fails, tell the user to run
```
gh auth login
```
and stop.
Run
```
gh project view <number> --owner <owner> --format json
```
to verify access and get project metadata (id, title). If this fails with 403/404, tell the user to check token scopes (
```
read:project
```
,
```
project
```
) and project access.
Determine the owner type from the project view output. This matters for Phase 3: use
```
organization(login: "<owner>")
```
for org-owned projects or
```
user(login: "<owner>")
```
for user-owned projects.

解析参数，从URL或位置参数中提取所有者和项目编号。
运行
```
gh auth status
```
验证身份验证。如果失败，告知用户运行
```
gh auth login
```
并终止流程。
运行
```
gh project view <number> --owner <owner> --format json
```
验证访问权限并获取项目元数据（ID、标题）。如果返回403/404错误，告知用户检查令牌权限（
```
read:project
```
、
```
project
```
）和项目访问权限。
从项目视图输出中确定所有者类型。这对阶段3很重要：对于组织拥有的项目使用
```
organization(login: "<owner>")
```
，对于个人拥有的项目使用
```
user(login: "<owner>")
```
。

Phase 2: Discover Schema

阶段2：发现架构

Run

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

to get all fields with IDs, types, and options.

Identify the workflow field: find the
```
ProjectV2SingleSelectField
```
named "Status". If multiple candidates or none found, ask the user which field drives the kanban workflow.
Separate the workflow field from other fields.

运行

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

获取所有字段的ID、类型和选项。

识别工作流字段：找到名为“Status”的
```
ProjectV2SingleSelectField
```
。如果找到多个候选字段或未找到，询问用户哪个字段驱动看板工作流。
将工作流字段与其他字段分离。

Phase 3: Discover Views

阶段3：发现视图

Run GraphQL query to fetch all views. Use the owner type determined in Phase 1 to choose the correct root field:

bash

gh api graphql -f query='
{
  organization(login: "<owner>") {
    projectV2(number: <number>) {
      views(first: 50) {
        nodes {
          id
          name
          number
          layout
          filter
          groupByFields(first: 5) {
            nodes {
              ... on ProjectV2Field { name }
              ... on ProjectV2SingleSelectField { name }
              ... on ProjectV2IterationField { name }
            }
          }
          sortByFields(first: 5) {
            nodes {
              field {
                ... on ProjectV2Field { name }
                ... on ProjectV2SingleSelectField { name }
                ... on ProjectV2IterationField { name }
              }
              direction
            }
          }
        }
      }
    }
  }
}'

Transform view data into config format: lowercase layout names (TABLE_LAYOUT -> table, BOARD_LAYOUT -> board, ROADMAP_LAYOUT -> roadmap), preserve filter strings as-is.

运行GraphQL查询获取所有视图。使用阶段1确定的所有者类型选择正确的根字段：

bash

gh api graphql -f query='
{
  organization(login: "<owner>") {
    projectV2(number: <number>) {
      views(first: 50) {
        nodes {
          id
          name
          number
          layout
          filter
          groupByFields(first: 5) {
            nodes {
              ... on ProjectV2Field { name }
              ... on ProjectV2SingleSelectField { name }
              ... on ProjectV2IterationField { name }
            }
          }
          sortByFields(first: 5) {
            nodes {
              field {
                ... on ProjectV2Field { name }
                ... on ProjectV2SingleSelectField { name }
                ... on ProjectV2IterationField { name }
              }
              direction
            }
          }
        }
      }
    }
  }
}'

将视图数据转换为配置格式：将布局名称转为小写（TABLE_LAYOUT → table, BOARD_LAYOUT → board, ROADMAP_LAYOUT → roadmap），保留过滤字符串原样。

Phase 4: Discover Items and Repos

阶段4：发现项目项和仓库

Run
```
gh project item-list <number> --owner <owner> --format json --limit 1000
```
to fetch all items. The
```
--limit
```
flag controls the total count returned (no cursor pagination available), so use a high value. Note: items beyond the limit are silently truncated — see cache reference for details.
Extract unique repository URLs from items to build the repos list.
Store all items in cache.

运行
```
gh project item-list <number> --owner <owner> --format json --limit 1000
```
获取所有项目项。
```
--limit
```
标志控制返回的总数（不支持游标分页），因此使用较高的值。**注意：**超过限制的项目项会被静默截断——详见缓存参考文档。
从项目项中提取唯一的仓库URL以构建仓库列表。
将所有项目项存储到缓存中。

Phase 5: Write Config Files

阶段5：写入配置文件

Assemble
```
.ghpm/config.json
```
with this structure:

json

{
  "version": 1,
  "project": {
    "owner": "<owner>",
    "number": "<number>",
    "id": "<project_node_id>",
    "title": "<project_title>"
  },
  "workflow": {
    "field": "<status_field_name>",
    "field_id": "<status_field_id>",
    "columns": [{ "id": "<option_id>", "name": "<option_name>" }]
  },
  "fields": [
    {
      "name": "<field_name>",
      "id": "<field_id>",
      "type": "<field_type>",
      "options": [{ "id": "<option_id>", "name": "<option_name>" }]
    }
  ],
  "views": [
    {
      "name": "<view_name>",
      "number": "<view_number>",
      "id": "<view_id>",
      "layout": "<table|board|roadmap>",
      "filter": "<filter_string>",
      "sort": [{ "field": "<field_name>", "direction": "<ASC|DESC>" }],
      "group_by": ["<field_name>"]
    }
  ],
  "cache": {
    "ttl_minutes": 30
  },
  "conventions": {
    "branch": "{type}/{issue-number}/{slug}. Detect type from issue labels and title: bug→fix, enhancement/feature→feat, documentation→docs, test→test, refactor→refactor, default→chore",
    "status_sync": "On start, set to InProgress if currently Planned or ReadyForDev. On session end with merged PR, set to Done.",
    "decisions": "When a design decision is detected, nudge before recording. Post as issue comment."
  },
  "repos": ["<owner>/<repo>"]
}

Only include
```
sort
```
key on views that have sort fields.
Only include
```
group_by
```
key on views that have groupBy fields.
Only include
```
options
```
on fields that are
```
single_select
```
or
```
iteration
```
type.
Strip the full URL from repos, keep just
```
owner/repo
```
.

Write

.ghpm/cache.json

per

../ghpm-shared/references/cache.md

Run
```
mkdir -p .ghpm/sessions
```
. Check if
```
.gitignore
```
exists. If it does, check if
```
.ghpm/
```
is already listed. If not, ensure the file ends with a newline before appending
```
.ghpm/
```
on its own line. If
```
.gitignore
```
doesn't exist, create it with
```
.ghpm/\n
```
.

按以下结构组装
```
.ghpm/config.json
```
：

json

{
  "version": 1,
  "project": {
    "owner": "<owner>",
    "number": "<number>",
    "id": "<project_node_id>",
    "title": "<project_title>"
  },
  "workflow": {
    "field": "<status_field_name>",
    "field_id": "<status_field_id>",
    "columns": [{ "id": "<option_id>", "name": "<option_name>" }]
  },
  "fields": [
    {
      "name": "<field_name>",
      "id": "<field_id>",
      "type": "<field_type>",
      "options": [{ "id": "<option_id>", "name": "<option_name>" }]
    }
  ],
  "views": [
    {
      "name": "<view_name>",
      "number": "<view_number>",
      "id": "<view_id>",
      "layout": "<table|board|roadmap>",
      "filter": "<filter_string>",
      "sort": [{ "field": "<field_name>", "direction": "<ASC|DESC>" }],
      "group_by": ["<field_name>"]
    }
  ],
  "cache": {
    "ttl_minutes": 30
  },
  "conventions": {
    "branch": "{type}/{issue-number}/{slug}. Detect type from issue labels and title: bug→fix, enhancement/feature→feat, documentation→docs, test→test, refactor→refactor, default→chore",
    "status_sync": "On start, set to InProgress if currently Planned or ReadyForDev. On session end with merged PR, set to Done.",
    "decisions": "When a design decision is detected, nudge before recording. Post as issue comment."
  },
  "repos": ["<owner>/<repo>"]
}

仅在视图有排序字段时包含
```
sort
```
键。
仅在视图有分组字段时包含
```
group_by
```
键。
仅在字段为
```
single_select
```
或
```
iteration
```
类型时包含
```
options
```
。
移除仓库的完整URL，仅保留
```
owner/repo
```
格式。

按照

../ghpm-shared/references/cache.md

的说明写入

.ghpm/cache.json

。

运行
```
mkdir -p .ghpm/sessions
```
。检查
```
.gitignore
```
是否存在。如果存在，检查
```
.ghpm/
```
是否已在列表中。如果没有，确保文件末尾有换行符，然后在单独一行追加
```
.ghpm/
```
。如果
```
.gitignore
```
不存在，创建并写入
```
.ghpm/\n
```
。

Phase 6: Install Agent Integration (optional)

阶段6：安装Agent集成（可选）

Detect the current agent environment and offer to install hooks/rules for enhanced
```
ghpm-work
```
sessions. See
```
../ghpm-shared/references/integrations.md
```
for available integrations.
Claude Code detection: Check if
```
.claude/
```
directory exists or if the current process is running inside Claude Code.
If detected, ask the user:
```
Detected Claude Code. Install session hooks for ghpm-work? (y/n)
Hooks add: auto session context injection, stale session detection.
Without hooks, ghpm-work still works via explicit commands.
```
If confirmed:
- Add the hooks from
```
../ghpm-shared/references/integrations.md
```
  into
```
.claude/settings.local.json
```
  under the
```
"hooks"
```
  key.
- If
```
.claude/settings.local.json
```
  already exists, merge the
```
"hooks"
```
  key into the existing structure (preserve existing settings and hooks, add new ones).
If declined or agent not detected, skip.

检测当前Agent环境，提供安装钩子/规则以增强
```
ghpm-work
```
会话。详见
```
../ghpm-shared/references/integrations.md
```
中的可用集成。
Claude Code检测：检查是否存在
```
.claude/
```
目录或当前进程是否在Claude Code中运行。
如果检测到，询问用户：
```
检测到Claude Code。是否安装ghpm-work的会话钩子？(y/n)
钩子功能：自动会话上下文注入、过期会话检测。
不安装钩子，ghpm-work仍可通过显式命令运行。
```
如果用户确认：
- 将
```
../ghpm-shared/references/integrations.md
```
  中的钩子添加到
```
.claude/settings.local.json
```
  的
```
"hooks"
```
  键下。
- 如果
```
.claude/settings.local.json
```
  已存在，将
```
"hooks"
```
  键合并到现有结构中（保留现有设置和钩子，添加新钩子）。
如果用户拒绝或未检测到Agent，跳过此步骤。

Phase 7: Report

阶段7：报告

Print summary:

ghpm initialized for <title> (<owner>/projects/<number>)

  Fields:    <count> (<list of field names>)
  Views:     <count> (<list of view names>)
  Repos:     <count>
  Items:     <count> cached

Config:  .ghpm/config.json (gitignored)
Cache:   .ghpm/cache.json (gitignored)
Hooks:   <installed|skipped>

Run /ghpm-status for project overview.

打印摘要：

ghpm 已为<title>（<owner>/projects/<number>）初始化完成

  字段：    <count>（<字段名称列表>）
  视图：     <count>（<视图名称列表>）
  仓库：     <count>
  项目项：     <count> 已缓存

配置文件：  .ghpm/config.json（已加入git忽略）
缓存文件：   .ghpm/cache.json（已加入git忽略）
钩子：   <已安装|已跳过>

运行/ghpm-status查看项目概览。

另请参阅

ghpm-shared — Prerequisites and error handling
ghpm-status — Project health dashboard

ghpm-shared — 前提条件和错误处理
ghpm-status — 项目健康仪表板

ghpm-init

Original

Translation

ghpm-init

ghpm-init

Arguments

参数

Workflow

工作流程

Phase 1: Validate Access

阶段1：验证访问权限

Phase 2: Discover Schema

阶段2：发现架构

Phase 3: Discover Views

阶段3：发现视图

Phase 4: Discover Items and Repos

阶段4：发现项目项和仓库

Phase 5: Write Config Files

阶段5：写入配置文件

Phase 6: Install Agent Integration (optional)

阶段6：安装Agent集成（可选）

Phase 7: Report

阶段7：报告

See Also

另请参阅