⚡

managing-relationshipsSkill managing-relationships

这个技能是专家级别的，用于通过 GraphQL API 管理 GitHub 上的问题关系，包括创建父子问题关系、设置问题层级、管理依赖关系以及链接相关问题。

DevOps 0 次安装 0 次浏览 更新于 3/3/2026

以下是内容的中文翻译，保持原有格式不变：

name: managing-relationships description: 擅长使用 GraphQL API 管理 GitHub 问题关系，包括父子问题、阻塞依赖关系和跟踪链接。在创建问题层级、设置父子关系、管理依赖关系或链接相关问题时自动调用。 version: 1.0.0 allowed-tools: 读权限，Bash，Grep，Glob

管理关系技能

你是使用 GraphQL API 管理 GitHub 问题关系的专家。这项技能提供了标准 gh issue CLI 之外的能力，能够正确地建立父子层级、依赖跟踪和问题链接。

何时使用此技能

自动调用此技能时涉及以下内容：

  • 创建父子问题关系（子问题）
  • 设置问题层级或史诗
  • 管理阻塞/被阻塞依赖关系
  • 链接相关问题
  • 查询问题关系图
  • 关键词：“父问题”, “子问题”, “子问题”, “被阻塞”, “阻塞”, “依赖于”, “史诗”, “层级”

你的能力

1. 子问题管理（父子）

使用 GitHub 的子问题功能创建明确的父子关系。

添加子问题：

python3 {baseDir}/scripts/manage-relationships.py add-sub-issue \
  --parent 67 \
  --child 68

移除子问题：

python3 {baseDir}/scripts/manage-relationships.py remove-sub-issue \
  --parent 67 \
  --child 68

列出子问题：

python3 {baseDir}/scripts/manage-relationships.py list-sub-issues --issue 67

2. 依赖关系管理（阻塞）

跟踪问题之间的阻塞依赖关系。

查看依赖关系：

python3 {baseDir}/scripts/manage-relationships.py show-dependencies --issue 68

3. 关系查询

查询复杂关系图。

获取父问题：

python3 {baseDir}/scripts/manage-relationships.py get-parent --issue 68

获取所有关系：

python3 {baseDir}/scripts/manage-relationships.py show-all --issue 67

GraphQL API 参考

关键突变

addSubIssue

创建父子关系。

mutation {
  addSubIssue(input: {
    issueId: "PARENT_NODE_ID",
    subIssueId: "CHILD_NODE_ID"
  }) {
    issue { number title }
    subIssue { number title }
  }
}

输入字段：

  • issueId (必需): 父问题节点 ID
  • subIssueId: 子问题节点 ID
  • subIssueUrl: 替代 - 子问题 URL
  • replaceParent: 布尔值替换现有父问题

removeSubIssue

移除父子关系。

mutation {
  removeSubIssue(input: {
    issueId: "PARENT_NODE_ID",
    subIssueId: "CHILD_NODE_ID"
  }) {
    issue { number }
    subIssue { number }
  }
}

reprioritizeSubIssue

重新排序父问题内的子问题。

mutation {
  reprioritizeSubIssue(input: {
    issueId: "PARENT_NODE_ID",
    subIssueId: "CHILD_NODE_ID",
    afterId: "SIBLING_NODE_ID"
  }) {
    issue { number }
  }
}

关键查询字段

问题关系

query {
  repository(owner: "OWNER", name: "REPO") {
    issue(number: 67) {
      # 父子
      parent { number title }
      subIssues(first: 50) {
        nodes { number title state }
      }
      subIssuesSummary {
        total
        completed
        percentCompleted
      }

      # 依赖关系
      blockedBy(first: 10) {
        nodes { number title }
      }
      blocking(first: 10) {
        nodes { number title }
      }

      # 跟踪（来自任务列表）
      trackedInIssues(first: 10) {
        nodes { number title }
      }
      trackedIssues(first: 10) {
        nodes { number title }
      }
      trackedIssuesCount
    }
  }
}

直接 GraphQL 使用

对于脚本未覆盖的操作，直接使用 gh api graphql：

获取问题节点 ID

gh api graphql -f query=
query {
  repository(owner: "OWNER", name: "REPO") {
    issue(number: 67) { id }
  }
}

添加多个子问题

gh api graphql -f query=
mutation {
  add1: addSubIssue(input: {issueId: "PARENT_ID", subIssueId: "CHILD1_ID"}) {
    subIssue { number }
  }
  add2: addSubIssue(input: {issueId: "PARENT_ID", subIssueId: "CHILD2_ID"}) {
    subIssue { number }
  }
}

查询完整层级

gh api graphql -f query=
query {
  repository(owner: "OWNER", name: "REPO") {
    issue(number: 67) {
      number
      title
      subIssues(first: 100) {
        nodes {
          number
          title
          state
          subIssues(first: 10) {
            nodes { number title }
          }
        }
      }
    }
  }
}

工作流程模式

模式 1: 创建问题层级

创建父问题和子问题时：

  1. 先创建所有问题
  2. 获取父问题和子问题的节点 ID
  3. 将每个子问题添加为父问题的子问题
  4. 验证关系
# 步骤 1: 获取 ID
python3 {baseDir}/scripts/manage-relationships.py get-ids --issues 67,68,69,70

# 步骤 2: 添加关系
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 67 --child 68
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 67 --child 69
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 67 --child 70

# 步骤 3: 验证
python3 {baseDir}/scripts/manage-relationships.py list-sub-issues --issue 67

模式 2: 史诗与嵌套子问题

对于复杂层级：

史诗 (#1)
├── 功能 A (#2)
│   ├── 任务 A1 (#5)
│   └── 任务 A2 (#6)
└── 功能 B (#3)
    └── 任务 B1 (#7)

# 顶层子问题
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 1 --child 2
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 1 --child 3

# 嵌套子问题
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 2 --child 5
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 2 --child 6
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue --parent 3 --child 7

模式 3: 将问题移动到新父问题

# 使用 replaceParent 标志
python3 {baseDir}/scripts/manage-relationships.py add-sub-issue \
  --parent 100 \
  --child 68 \
  --replace-parent

错误处理

常见错误

“问题可能不包含重复的子问题”

  • 子问题已经是这个父问题的子问题
  • 先检查现有关系

“子问题只能有一个父问题”

  • 子问题已经有不同父问题
  • 使用 --replace-parent 标志或先从当前父问题中移除

“问题未找到”

  • 验证问题编号是否存在
  • 检查仓库所有者/名称

故障排除

# 检查问题是否有父问题
python3 {baseDir}/scripts/manage-relationships.py get-parent --issue 68

# 列出所有关系
python3 {baseDir}/scripts/manage-relationships.py show-all --issue 68

与其他技能的集成

与创建问题技能

  • 创建问题后，使用此技能建立关系
  • 在问题正文中引用父问题：“Part of #67”

与组织标签技能

  • 标签指示类型，关系指示结构
  • 一起使用以实现完整的问题组织

与项目管理技能

  • 子问题出现在项目板上
  • 在项目中跟踪层级进度

环境要求

此技能需要：

  • 通过适当权限认证的 gh CLI
  • 启用问题的仓库
  • GraphQL API 访问权限

最佳实践

  1. 先创建问题，然后建立关系 - 在链接之前确保所有问题存在
  2. 在正文中记录关系 - 添加 “Part of #X” 以提高可见性
  3. 检查现有父问题 - 避免孤立问题
  4. 谨慎使用层级 - 深层嵌套 (>3 层) 变得难以管理
  5. 结合标签使用 - 对于父问题使用 type:epic 标签

限制

  • 每个问题只能有一个父问题 - 不能有多个子继承
  • 没有循环引用 - 如果 B 是 A 的祖先，则 A 不能成为 B 的父问题
  • API 速率限制 - 仔细批量操作
  • 阻塞关系 - 目前通过 API 仅读（在 UI 中管理）

资源

脚本

参考

常见错误

错误 1: 使用任务列表而不是子问题 API

❌ 错误 - 使用任务列表而不是子问题 API：
## 子问题
- [ ] #68
- [ ] #69
- [ ] #70

✅ 正确 - 使用 GraphQL addSubIssue 突变：
python manage-relationships.py add-sub-issue --parent 67 --child 68
python manage-relationships.py add-sub-issue --parent 67 --child 69
python manage-relationships.py add-sub-issue --parent 67 --child 70

为什么重要：

  • 任务列表只创建 “被跟踪” 关系，在问题侧边栏可见
  • 子问题创建真正的父子层级，具有：
    • 进度跟踪 (3/4 完成，75%)
    • GitHub UI 中的层级导航
    • 子问题聚合和汇总

错误 2: 没有先获取问题节点 ID

❌ 错误 - 直接在 GraphQL 中使用问题编号：
mutation {
  addSubIssue(input: {issueId: "67", subIssueId: "68"}) { ... }
}

✅ 正确 - 先获取节点 ID，然后使用它们：
# 步骤 1: 获取节点 ID
python manage-relationships.py get-ids --issues 67,68

# 步骤 2: 在突变中使用节点 ID
mutation {
  addSubIssue(input: {
    issueId: "I_kwDOQTQw6c7Z4spt",
    subIssueId: "I_kwDOQTQw6c7Z4swL"
  }) { ... }
}

为什么重要：GraphQL 使用节点 ID（而不是问题编号）。脚本自动处理此问题，但直接 API 调用需要转换。

错误 3: 没有检查现有父问题

❌ 错误 - 添加子问题时没有检查现有父问题：
python manage-relationships.py add-sub-issue --parent 100 --child 68
# 错误：子问题只能有一个父问题

✅ 正确 - 先检查，如果需要则使用 --replace-parent 标志：
# 检查现有父问题
python manage-relationships.py get-parent --issue 68

# 如果有父问题，使用替换标志
python manage-relationships.py add-sub-issue --parent 100 --child 68 --replace-parent

为什么重要：每个问题只能有一个父问题。尝试添加到新父问题而不使用替换标志将失败。

错误 4: 创建循环引用

❌ 错误 - 创建层级中的循环引用：
# A 是 B 的父问题
python manage-relationships.py add-sub-issue --parent A --child B
# 然后尝试使 B 成为 A 的父问题
python manage-relationships.py add-sub-issue --parent B --child A
# 错误：无法创建循环引用

✅ 正确 - 计划层级结构后再创建：
史诗 (#1)
├── 功能 A (#2)
│   └── 任务 A1 (#5)
└── 功能 B (#3)
    └── 任务 B1 (#7)

为什么重要：GitHub 防止循环引用。在创建关系之前规划您的层级结构。

错误 5: 创建后不验证

❌ 错误 - 添加关系后不验证：
python manage-relationships.py add-sub-issue --parent 67 --child 68
# 只是假设它工作了

✅ 正确 - 验证关系是否创建：
python manage-relationships.py add-sub-issue --parent 67 --child 68
python manage-relationships.py list-sub-issues --issue 67
# 确认：子问题 (4)：#68, #69, #70, #71

为什么重要：API 调用可能会默默失败或部分失败。始终验证结果是否符合预期。

错误 6: 深层嵌套 (>3 层)

❌ 错误 - 过多的嵌套层级：
史诗
└── 主题
    └── 功能
        └── 故事
            └── 任务
                └── 子任务 (6 层！)

✅ 正确 - 保持层级浅 (2-3 层)：
史诗
├── 功能 A
│   ├── 任务 A1
│   └── 任务 A2
└── 功能 B
    └── 任务 B1

为什么重要：深层嵌套变得难以管理和导航。大多数项目最多 2-3 层效果最佳。

重要说明

  • 标准 gh issue CLI 不支持关系管理
  • 总是通过 gh api graphql 使用 GraphQL API 管理关系
  • 子问题在 GitHub UI 中出现，具有进度跟踪
  • 任务列表复选框 (- [ ] #68) 创建 “被跟踪” 关系，而不是父子关系
  • 每个问题只能有一个父问题（没有多重继承）
  • 创建后验证关系以确认成功