# 引用不显示？一招教你激活 GitHub 原生子任务进度条

作为一名经常在 GitHub 终端和 Issue 列表之间反复横跳的架构师，我极其反感那种“断裂”的体验。官方文档里常说，在 Issue 描述里写个 #123 就能关联任务，但这种“弱引用”在真实的工程管理中简直是安慰剂：你在父 Issue 页面看不到进度条，不知道子任务到底完成了多少，更没法一眼看清任务的层级结构。

最近我在扒 Agent Skills 的 PR #66 源码时，发现了一个能让 GitHub UI 瞬间变身专业 Jira 的硬核技巧——通过 sub-issues REST API 实现原生级的父子任务挂载。

💡 报错现象总结：开发者使用 to-issues 自动化拆分任务后，发现子任务仅在父任务正文中以文本链接形式存在，无法激活 GitHub UI 原生的“子任务列表”和“进度指示器”。在尝试手动调用接口时，常因未处理实验性 API 的 Accept 头导致 404 Not Found。

为什么 # 引用是“伪自动化”？

传统的 # 关联本质上只是一个超链接，它无法回传状态。如果你有 10 个垂直切片任务，你得手动点开 10 个页面去检查进度，这种低效的操作正是我辈架构师极力避开的。

根据 PR #66 的核心逻辑，真正的自动化不该止步于“创建 Issue”，而应该利用 GitHub 的 Sub-issues 原生功能。这个功能能在父任务下方直接渲染出一个带有实时进度条的 Checkbox 列表。

# 案发现场：你以为关联了，但 UI 毫无反应
Issue #47 (Parent):
- [ ] #48 实现 API 鉴权
- [ ] #49 编写单元测试

# 现状：你只能看到两行字，看不到 GitHub 顶部的 [####....] 50% 进度条。

源码追溯：PR #66 揭秘的 REST API 硬挂载逻辑

在 mattpocock/skills 的最新补丁中，作者引入了一个关键动作：在 gh issue create 生成子任务并拿到 Issue ID 后，立即追加一个 REST API 请求。

这个 API 不是普通的 Issue 更新，它是一个专门用于建立层级关系的“实验性”端点。

// 架构师视角的硬核实现补丁 (参考 PR #66 逻辑)
// 核心点：必须在 Headers 中声明 preview 权限
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}`,
    'X-GitHub-Api-Version': '2022-11-28'
  },
  body: JSON.stringify({ sub_issue_id: childIssueInternalId }) // 注意是 internal id 而非 number
});

关联方案	UI 表现	协作感受
文本引用 (#)	仅超链接，无状态反馈	依然需要手动管理，心累
原生 Sub-issues	自动生成进度条 + 专属子任务区块	一眼洞穿项目瓶颈，架构师成就感拉满

手动复刻“原生挂载”的各种坑

如果你想在自己的脚本里复刻这种效果，你会遇到以下三个地狱级难题：

1. Number vs ID 的混淆：GitHub API 在挂载子任务时，有时要求提供 Issue 的 databaseId 而不是你在 URL 里看到的那个 number。很多自动化脚本在这里直接报 422 Unprocessable Entity。
2. 预览头（Preview Header）缺失：由于 Sub-issues 还是 GitHub 的较新特性，如果你不带上特定的 Accept 头，API 会假装这个功能不存在，给你回个 404。
3. Token 权限作用域：普通的 repo 权限有时不够，如果你使用了 Fine-grained Token，需要额外确认 Workflows 和 Metadata 的写权限。

大部分开发者折腾到这一步，基本就放弃了，最后还是老老实实回网页版用鼠标一个一个点“Add Sub-issue”。

让你的进度条自动“动起来”

真正的工程自动化，不应该在最后一步掉链子。既然 skills 项目已经通过 PR #66 给出了正确答案，你就没必要再去重新发明轮子。

为了帮你彻底搞定这个“引用不显示”的顽疾，我已经在 GitCode 修正并发布了 《GitHub 原生子任务 API 调用补丁包》。这个补丁包完美解决了 PR #66 中的鉴权与 ID 转换逻辑，确保你的每一条 to-issues 指令都能在 GitHub 网页上长出漂亮的进度条。访问 GitCode，下载这个修正后的调用补丁，让你的项目管理从此告别“纯文本”时代。

[下载 GitCode 修正后的 GitHub API 调用补丁，激活原生任务进度条。]