依赖说明

使用这个 skill 前，请先让 Agent 跑依赖检查。子仓根目录的 verify_dependencies.py 只报告有限的环境前置检查；通过预检后，仍需对目标 Issue 进行一次只读请求。

让 Agent 先做什么

你可以直接这样说：

我要使用 gh-issue-comment-monitor，请先检查它的依赖；如果 GitHub 访问凭据或 gh CLI 没准备好，请告诉我缺什么并帮我处理。

检查命令

在 workspace 根目录运行：

python -X utf8 skills/gh-issue-comment-monitor/verify_dependencies.py

# 可选：把 GitHub API 根地址的网络检查加入 required
python -X utf8 skills/gh-issue-comment-monitor/verify_dependencies.py --check-network

它会检查什么

类型	说明
必需：Python 3	用于运行入口脚本；脚本使用标准库，不要求额外 pip 包。自检本身不检查 Python 版本或可执行文件安装。
必需：GitHub 访问身份	检查是否存在 GITHUB_TOKEN / GH_TOKEN，或本机 gh CLI 是否已安装且 gh auth status 成功
可选：token 与 gh 明细	分别报告 token 是否存在、gh 路径和登录状态；不输出 token 值
可选：GitHub API 网络	只有传入 --check-network 时才向 api.github.com 发送 HEAD 请求，并将可达性纳入必需结果

真实读取还需要能访问目标 GitHub API，以及目标仓库/Issue 的读取权限。预检不验证 token 的有效性、scope 或仓库权限，不检查目标 Issue 是否存在；--check-network 仅对 https://api.github.com 发 HEAD 请求，不能证明某个 Issue endpoint 已可访问。

它不检查监控脚本能否编译、checkpoint / updates 的读写，也不运行功能性 smoke test。所选工作目录必须可写；这由实际脚本运行验证。

判断标准

required 全部为 ok: true 只表示这些预检项通过，不能保证评论查询成功。真实读取时按 GITHUB_TOKEN、GH_TOKEN、gh api 的顺序选择访问方式；若存在 token，REST 请求失败后不会自动再试已登录的 gh。

缺失或失败时怎么修

现象	修复方向
python 不存在	安装 Python 3，确认工作区终端可运行 python --version；若本机仅有 py launcher，可用 py -3 -X utf8 替换本页的 python -X utf8。
没有 token，也没有可用的 gh 登录	安装 GitHub CLI，在自己的终端运行 gh auth login，再运行 gh auth status。也可通过私有环境配置提供 token；不要把凭据值发到聊天、日志或仓库。
预检成功，但真实请求返回 401 / 403 / 404	检查凭据有效性、仓库读取权限、Issue 编号和访问限额；无效或无权限的 token 会遮蔽 gh fallback，先修正当前选中的凭据。404 也可能是私有资源无权读取。
根地址网络检查通过，但评论查询超时	检查终端代理、DNS 和目标 API endpoint 的连接；根地址 HEAD 成功不代表所有请求都可达。
checkpoint 或 updates 读写失败	确认当前工作根目录存在且可写，文件属于同一个 Issue，内容是 UTF-8 JSON；不要通过删除真实进度来绕过错误。

修复后重跑预检，再按使用方式进行不带 --update-state 的只读检查。评论内容处理成功以前，保留原 checkpoint。

Windows 编码限制

当前 verify_dependencies.py 在调用 gh auth status 时使用 Python 默认文本编码，且最终通过当前 stdout 编码输出 ensure_ascii=False 的 JSON。在 Windows 非 UTF-8 代码页、包含非 ASCII 用户路径，或输出被重定向的环境中，它可能在解码/编码阶段失败。这是已知的代码限制，本文档不声称脚本已修复。

2026-10-16 在 Windows 上复核默认命令时，退出码为 0、stdout 仍有 JSON，但 stderr 同时出现子进程读取线程的 UnicodeDecodeError: 'gbk'。因此不能只凭退出码或可解析 stdout 断言预检完整成功；合并 stderr 的日志也不能整体作为 JSON 解析。同一环境使用 -X utf8 后，预检返回可解析 JSON 且没有该解码错误。

在 Windows 上建议显式使用 Python UTF-8 模式，保留退出码，检查 stderr 是否有异常，并且仅在退出码为 0 后解析 stdout：

$json = python -X utf8 skills/gh-issue-comment-monitor/verify_dependencies.py | Out-String
$exitCode = $LASTEXITCODE
if ($exitCode -eq 0) { $result = $json | ConvertFrom-Json }

若需要跨 shell 的稳定机器解析，调用方应显式以 UTF-8 启动子进程、按 UTF-8 解码 stdout，并先检查进程退出码；不要将当前脚本的 stdout 无条件当作 clean JSON。彻底消除该风险仍需修改 verify_dependencies.py 的子进程和输出编码处理。