GitHub Issue 评论监控

gh-issue-comment-monitor 是一个轻量 GitHub Issue 协作 skill，用来让 Agent 只读取本轮需要处理的新评论，而不是反复加载完整 issue 历史。

逻辑视图

这个 skill 的核心是“GitHub Issue 评论 + 本地 checkpoint + 本轮 updates 文件”。GitHub 是只读数据源；checkpoint 只记录上次成功处理到的位置；updates 是供 Agent 本轮消费的有界评论集合。

模块	职责
SKILL.md	定义触发场景、上下文纪律和脚本调用原则。
scripts/check_issue_updates.py	只检查 checkpoint 之后是否有新评论，不更新状态。
scripts/get_latest_comments.py	获取 checkpoint 或指定 comment id 之后的评论；--update-state 会在抓取后立即写状态，不确认评论是否已处理。
scripts/github_issue_comments.py	封装 GitHub REST API / gh api fallback、评论规范化、状态读写和错误 JSON。
verify_dependencies.py	检查 token 或已登录的 gh CLI；只在使用 --check-network 时检查 GitHub API 可达性。它不编译脚本，也不检查 checkpoint 读写。

运行视图

用户 prompt（仓库 + Issue 编号）
  -> 主 Agent 确认当前工作根目录；默认是本次 run，用户明确指定长期跟进时才使用 retained work root
  -> check_issue_updates.py 读取 checkpoint 并查询 GitHub（不更新状态）
  -> 覆写本轮 <issue>-updates.json
  -> 主 Agent 只读本轮新评论并完成理解、摘要或后续处理
  -> 处理成功后，从同一 updates 快照确认候选 ID；本地 state 省略 updated_at 时间游标
  -> 主 Agent 向用户交付增量结果；下次从新 checkpoint 继续

若没有 checkpoint，脚本只读取评论列表最后一页的尾部，最多 --limit 条，不保证覆盖全部历史，也可能少于请求条数。已有 checkpoint 时，--max-pages 限制扫描页数，--limit 另行限制返回条数；truncated=false 不代表全部未处理评论已返回。主 Agent 处理一批、确认该批 checkpoint，再读取下一批。

get_latest_comments.py --update-state 会重新查询并立即写状态；不能用它确认先前 check 的快照，否则期间到达的新评论也可能被标为已处理。候选中的 last_seen_comment_updated_at 也不适合作为 ID 分批游标：较早评论被晚编辑，可能让下一次 since 查询漏掉未处理的较大 ID 评论。确认副本时应省略此字段，让后续按 ID 扫描，并保留页数截断检查；旧 state 也先去掉此时间字段。精确步骤见使用方式。

开发视图

分层	内容	边界
Agent 契约层	SKILL.md	定义触发条件、上下文纪律和状态更新时机，不保存 Issue 数据。
文档层	docs/index.md、usage.md、dependencies.md、reference.md	分别解释架构、调用、依赖和能力示例，不参与运行。
入口脚本层	scripts/check_issue_updates.py、scripts/get_latest_comments.py	解析参数并组装检查/取回流程。
共享实现层	scripts/github_issue_comments.py	封装 GitHub API / gh api fallback、规范化评论、JSON 输出与本地状态读写。
环境预检层	verify_dependencies.py	只报告外部访问前置；不代替功能测试或编译检查。

Agent 职责与交接边界

默认由一个主 Agent 独立调用脚本、读取 updates、处理新评论并决定何时更新 checkpoint。这个 skill 没有必需的子 Agent、checker 或 reviewer，普通使用无需额外授权启动它们。

• 主 Agent 的输入是用户 prompt、Issue 定位信息和现有 checkpoint；交付的是本轮增量评论结论及必要的后续行动。
• 主 Agent 不得在新评论尚未成功处理时推进 checkpoint，也不得把 updates 文件变成累计归档。
• 如果上层任务因其他原因另行引入子 Agent 或 reviewer，主 Agent 仍持有 checkpoint 更新权；交给其他 Agent 的应是本轮 updates 或摘要，不是无界的完整 Issue 历史。

设计边界

• 只读取评论，不修改 GitHub Issue。
• checkpoint 只记录最后处理到的位置，不保存完整评论正文。
• updates 文件只保存本次返回的评论，不做累计归档。
• checkpoint 之后的筛选仍要求评论 ID 更大；旧评论的后续编辑不在当前增量覆盖范围内。
• checkpoint 与 updates 的写入由一个主 Agent 串行负责，处理快照期间不得被其他调用覆写。
• 当任务只是“看最新回复”时，优先读取增量；只有缺少 checkpoint 或需要重建背景时才拉完整上下文。

输出契约

check_issue_updates.py 会返回 has_updates、new_comments、latest_comment 和 recommended_checkpoint，但不会更新状态。

get_latest_comments.py 会返回 comments、previous_checkpoint、next_checkpoint 和 state_updated。--update-state 只表示抓取后进行了本地状态写入，不表示 Agent 已理解、回复或完成后续任务。常规处理应先不带该标志抓取，再确认已消费的快照。

默认情况下，checkpoint 与本轮 updates 写入同一个 run：

.tmp/
`-- runs/<run-id>/gh-issue-comment-monitor/
    |-- OWNER-REPO-ISSUE.json
    `-- OWNER-REPO-ISSUE-updates.json

只有用户明确指定长期跟进时，才将整个 gh-issue-comment-monitor/ 工作目录放到 .tmp/retained/<work-name>/ 下；不要拆分 checkpoint 与 updates。

子仓文档导航

• 能力展示
• 使用方式
• 依赖说明
• 架构概览