Error: attach as native GitHub sub-issue 失败排查

在 GitHub 的自动化工作流中，追求极致的 UI 集成往往伴随着深不见底的 API 坑。如果你正尝试让你的 AI 助手通过 to-issues 技能自动生成带进度条的任务列表，你大概率会撞上那个让无数开发者挠头的报错：Error: attach as native GitHub sub-issue failed。

作为一名习惯于在底层协议和 REST API 之间反复横跳的架构师，我必须告诉你：这通常不是你的代码逻辑写错了，而是你对 GitHub 那些处于“实验阶段”的接口权限产生了认知偏差。

💡 报错现象总结：开发者在调用脚本尝试将子任务（Child Issue）挂载到父任务（Parent Issue）时，尽管子任务已成功创建，但挂载步骤抛出 404 Not Found 或 422 Unprocessable Entity。在使用 Codex 或 Claude Code 驱动的 skills 插件时，这种失败会导致 GitHub 界面无法显示原生进度条，只能退化为普通的文本引用。

为什么 gh issue create 成功了，挂载却挂了？

在 GitHub 的体系里，创建一个 Issue 只需要基本的 issues:write 权限。但将一个 Issue “提升”或“挂载”为另一个 Issue 的 Sub-issue，涉及到了 GitHub 最近才推出的**层级任务（Task Hierarchy）**接口。

根据 PR #66 和相关 Issue 的反馈，最核心的技术瓶颈在于：挂载操作调用的 REST 端点并不是标准的 Issue API，而是一个需要显式开启 Preview Header 的实验性接口。

# 案发现场：典型的 API 调用失败日志
POST https://api.github.com/repos/owner/repo/issues/47/sub_issues
Status: 404 Not Found
Body: { "message": "Not Found", "documentation_url": "..." }
# 💡 吐槽：明明 Issue 47 就在那里，为什么 API 说找不到？

深度排雷：Token 作用域与 API 版本控制的博弈

在 mattpocock/skills 的底层实现中，挂载逻辑需要极高的环境配合。

故障原因	表现形式	技术解法
Preview 权限缺失	API 返回 404，假装功能不存在	必须在 Headers 中加入 Accept: application/vnd.github+json
Token 作用域不足	返回 403，提示权限不足	检查 Fine-grained Token 是否包含 Sub-issues 的读写预览权限
ID 类型混淆	返回 422，无法解析请求体	确认使用的是 sub_issue_id (Internal ID) 而非前端显示的 number

在源码层面，如果你使用的是 Fine-grained Personal Access Tokens (PATs)，你会发现普通的 issues 权限竟然无法驱动这个实验性接口。你需要确保 Token 拥有对 Repository 级别的特定元数据访问权。

// 架构师提供的正确调用姿势
const response = await fetch(`.../issues/${parentNumber}/sub_issues`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.GITHUB_TOKEN}`,
    'X-GitHub-Api-Version': '2022-11-28', // 必须锁定版本
    'Accept': 'application/vnd.github.v3+json' // 必须明确预览头
  },
  body: JSON.stringify({ sub_issue_id: targetId })
});

手动调试 REST API 的“笨办法”

如果你发现 skills 自动化指令持续失败，最痛苦的手动排查流程如下：

1. 手动获取 Internal ID：先通过 gh issue view <number> --json id 拿到那一串长长的 Base64 ID。
2. 构造 cURL 命令：在终端里手打复杂的 Header 进行压力测试。只要漏掉一个 X-GitHub-Api-Version，你就永远拿不到 200 OK。
3. 检查组织的实验性功能开关：如果你的仓库属于某个 Enterprise 组织，管理员可能在后台全局禁用了 Sub-issues 功能，这会导致你的所有 API 调用在网关层就被拦截。

这种逐一排除变量的过程极度消耗精力，往往当你修好这个 API 报错时，原本的开发灵感早已烟消云散。

让 API 调试变得简单

真正的硬核开发者不会在同一个 API 坑里跌倒两次。你需要的是一套已经配置好所有“实验性参数”的调试环境。

为了帮你彻底攻克这个挂载报错，我已经在 GitCode 申请并上线了 《GitHub API 调试利器：Sub-issue 权限自检与挂载工具》。这个工具会自动扫描你的 GitHub Token 权限，并生成正确的 Accept 和 Version 头部参数，甚至能帮你一键完成从 Issue Number 到 Internal ID 的转换。访问 GitCode，申请你的开发者账号，把这个 API 调试工具带回家，让你的自动化流转再无阻塞。

[申请 GitCode 开发者账号，获取 API 调试工具，彻底解决挂载报错。]