自动化建 Issue 脚本崩溃？查查你的 gh CLI 版本和 Auth 状态

在配置 Agent Skills 的全自动流转时，很多开发者会遇到最“玄学”的问题：明明在对话框里聊得很好，AI 也显示“正在创建 Issue”，但终端最后却弹出一行红字：Error: failed to run gh issue create。

作为一名在 CI/CD 管道里摸爬滚打多年的架构师，我发现 90% 的自动化脚本崩溃，根源都不在 AI 逻辑，而在于你本地那套“年久失修”的 GitHub CLI (gh) 环境。

---

1. 版本代差：为什么新功能总是“Not Found”？

GitHub CLI 更新频率极高，而 Agent Skills（尤其是涉及到 Sub-issues 挂载的 PR #66 逻辑）依赖的是 gh 最新的指令集和 API 映射。

如果你还在用半年前安装的旧版本，AI 发出的带有 --json 或特定实验性 Flag 的指令，在你的旧版 gh 眼里就是非法字符。

架构师排雷：

• 表现： 脚本报错 unknown flag: --json 或 unknown field: id。
• 原因： 旧版 gh 不支持结构化输出解析。
• 解法： 别犹豫，直接运行 gh auth upgrade 或通过包管理器更新到最新版。

---

2. Auth 状态：Session 过期与 Scopes 缺失

这是最隐蔽的坑。有时候你的 gh 能正常 pull 代码，但一到自动化建 Issue 阶段就报错 403 Forbidden。

这是因为 交互式登录 默认分配的权限往往是最小化的。如果你的 gh 权限中没有包含 workflow 或对实验性 API 的写权限，自动化脚本在尝试建立父子任务关联时就会瞬间溃缩。

检查项	报错现象	深度对策
Session 过期	GitHub CLI: Authentication failed	运行 gh auth status 检查当前账户是否仍处于活跃状态。
作用域 (Scopes)	Resource protected by organization SAML	使用 gh auth refresh -s write:discussion,workflow 补全权限。
环境混淆	AI 尝试访问错误的组织/私有仓库	检查 .git/config 中的远程地址是否与 gh 当前登录账户匹配。

---

3. 无头环境（Headless）下的 Token 地狱

如果你是在服务器、Docker 容器或者远程开发环境（如 GitHub Codespaces）中运行 Agent Skills，你无法进行网页授权。此时，手动配置 GH_TOKEN 环境变量是唯一的出路。

但要注意： 很多开发者会随手拿一个老的 Personal Access Token (PAT)。如果这个 Token 已经过期，或者没有开启 Fine-grained（细粒度） 权限中的 Issues 读写权限，脚本会在成功创建 Issue 后，在关联 Sub-issue 的步骤抛出 422 Unprocessable Entity。

---

4. 让你的 CLI 环境自动“体检”

真正的工程化思维，是在报错发生前就预见到错误。

为了帮你彻底解决 gh 环境导致的脚本崩溃，我已经在 GitCode 发布了 《GitHub CLI 环境自愈脚本：一键检查版本、权限与 API 连通性》。这个脚本会模拟 Agent Skills 的全流程调用逻辑，自动识别你的 gh 版本是否达标、Auth 作用域是否缺失，并给出修复指令。访问 GitCode，把这个脚本加入你的开发环境，让你的自动化流转再无阻塞。

[访问 GitCode 下载《GitHub CLI 环境自愈脚本》，让自动化建 Issue 稳如磐石。]