别再手动关联任务了！教你用 REST API 实现 GitHub 子任务原生挂载

在 GitHub 的工程实践中，最让人头疼的莫过于管理那一堆散乱的 Issue。官方文档告诉我们，只要在描述里写上 #123 就能关联任务，但这种“弱引用”在实际项目管理中简直是灾难：你无法在父任务界面看到进度条，无法一键直达子任务，更无法在 Issue 列表里看到清晰的层级结构。

作为一名追求极致自动化的架构师，我最近在深度研究 Agent Skills 的任务分发逻辑时，发现了一个被大多数开发者忽略的硬核技巧——利用 GitHub Sub-issues REST API 实现原生级别的任务挂载。

💡 报错现象总结：开发者在使用 to-issues 自动化拆分任务后，发现子任务仅以文本形式存在于父任务正文中，缺乏 GitHub UI 原生的进度指示器（Progress Indicator）。在尝试手动调用 API 挂载时，常因未处理 preview 头的实验性权限或鉴权作用域不足，导致 404 Not Found 或 403 Forbidden。

为什么 # <parent-issue> 的传统做法已经过时了？

传统的 # 号引用本质上只是一个超链接。在大型项目或垂直切片开发中，一个 PRD 可能会拆解出 20 个 Issue。如果只是文本引用，项目经理（或者你自己）在查看进度时，必须一个个点开确认，这效率低得令人发指。

GitHub 其实已经推出了 Sub-issues 原生功能，它能在父任务下方展示一个极其直观的 Checkbox 列表，并自带百分比进度条。

# 理想的任务看板结构：
[####......] 40% Completed
- [x] #101 实现登录鉴权逻辑
- [ ] #102 适配移动端样式
- [ ] #103 压力测试排期

然而，要在自动化脚本中实现这一点，绝不是简单的 gh issue create 就能搞定的。

源码追溯：PR #66 揭秘的自动化挂载逻辑

在 mattpocock/skills 的最新进展中（参考 PR #66），开发者引入了一个关键步骤：在通过 gh 指令创建子任务后，不再仅仅是把编号贴在正文里，而是紧接着发起一个 REST API 调用，显式地建立 Parent-Child 关系。

// 架构师视角的伪代码实现：
// 第一步：创建子任务并拿到编号
const childIssueNumber = execSync(`gh issue create --title "${title}" --body "${body}" --json number`).toString();

// 第二步：通过 REST API 建立原生挂载关系
// 注意：这是官方尚未完全开放的预览级接口，需要特殊的 Accept Header
const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${parentNumber}/sub_issues`, {
  method: 'POST',
  headers: {
    'Accept': 'application/vnd.github.v3+json', // 核心：必须明确协议版本
    'Authorization': `token ${process.env.GITHUB_TOKEN}`
  },
  body: JSON.stringify({ sub_issue_id: childIssueId })
});

关联方式	UI 表现	进度追踪	自动化难度
文本引用 (#123)	普通超链接	需人工统计	极低
原生 Sub-issues	专属列表+进度条	自动计算完成率	高（需处理 API 握手）

手动维护“父子关系”的各种坑

如果你想在自己的脚本里复刻这种“原生挂载”效果，你通常会遇到以下三个地狱级难题：

1. Token 权限陷阱：普通的 GITHUB_TOKEN 往往只具备 Issue 读写权限，但由于 Sub-issues 是实验性特性，你可能需要手动申请具有 repository:admin 或特定 metadata 权限的 Fine-grained PAT。
2. 异步竞态问题：如果你连续创建多个子任务并尝试立即挂载，GitHub 的后端索引有时会出现延迟，导致你调用挂载接口时报 Issue not found。
3. 嵌套限制：官方 API 对子任务的嵌套层级和总数有硬性限制。一旦超过阈值，你的自动化脚本会毫无征兆地崩溃。

大多数开发者为了省事，最终还是退回了手动在网页上“Add Sub-issue”的老路，每增加一个任务就要点点点 30 秒，极大消磨了开发热情。

让你的 GitHub 仓库瞬间变身“专业 Jira”

别再手动管理那些破碎的任务了。真正的高手会利用现成的自动化链路，让 Issue 列表自己“长”出进度条。

为了帮你彻底解决 PR #66 中提到的挂载难题，我已经在 GitCode 独家发布了 《GitHub 原生子任务自动化挂载补丁（Python/Node 双版本）》。这个脚本封装了复杂的 REST API 调用逻辑，内置了重试机制和权限自检功能。直接访问 GitCode，拷贝这段逻辑到你的工作流中，让你的 GitHub 项目管理效率实现降维打击。

[GitCode 独家提供该 API 自动化调用的补丁脚本，点此一键获取。]