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 之后的评论，可在处理成功后更新状态。
`scripts/github_issue_comments.py`	封装 GitHub REST API / `gh api` fallback、评论规范化、状态读写和错误 JSON。
`verify_dependencies.py`	检查 token 或已登录的 `gh` CLI；只在使用 `--check-network` 时检查 GitHub API 可达性。它不编译脚本，也不检查 checkpoint 读写。

运行视图

text

用户 prompt（仓库 + Issue 编号）
  -> 主 Agent 确认主工作区 .tmp/gh-issue-comment-monitor/ 路径
  -> check_issue_updates.py 读取 checkpoint 并查询 GitHub（不更新状态）
  -> 覆写本轮 <issue>-updates.json
  -> 主 Agent 只读本轮新评论并完成理解、摘要或后续处理
  -> 处理成功后才由 get_latest_comments.py --update-state 推进 checkpoint
  -> 主 Agent 向用户交付增量结果；下次从新 checkpoint 继续

若没有 checkpoint，脚本会按有界的最新评论路径建立上下文；只有确实需要重建讨论背景时，主 Agent 才扩大扫描范围。

开发视图

分层	内容	边界
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 或需要重建背景时才拉完整上下文。

输出契约

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

get_latest_comments.py 会返回 comments、previous_checkpoint、next_checkpoint 和 state_updated。只有调用方明确要求更新状态时，才会写回 checkpoint。

推荐产物都写在主工作区 .tmp/gh-issue-comment-monitor/ 下：

text

.tmp/gh-issue-comment-monitor/
|-- OWNER-REPO-ISSUE.json
`-- OWNER-REPO-ISSUE-updates.json

GitHub Issue 评论监控 ​

逻辑视图 ​

运行视图 ​

开发视图 ​

Agent 职责与交接边界 ​

设计边界 ​

输出契约 ​

子仓文档导航 ​