gh-issues GitHub Issues 自动化管理技能 - 深度学习

🎯 什么是 gh-issues 技能？

gh-issues 是一个强大的 GitHub Issues 自动化修复技能，能够：

  • ✅ 自动获取符合条件的 GitHub Issues
  • ✅ 生成 AI 子代理自动修复问题
  • ✅ 创建 Pull Request
  • ✅ 自动处理 PR Review Comments
  • ✅ 支持 Cron 定时任务和 Watch 监控模式

关键特点：

  • 不依赖 gh CLI（使用 curl + GitHub REST API）
  • 最多 8 个并发子代理
  • 每个子代理最长 60 分钟
  • 智能 Issue 筛选（置信度评估）
  • 三重去重机制（PR + Branch + Claims）

🔄 6 个阶段工作流程

Phase 1: 解析参数

核心任务：解析命令行参数，确定工作模式

常用参数：

# 基础用法
/gh-issues owner/repo --label bug --limit 5

# 工作模式
--watch          # 持续监控模式
--interval 5     # 轮询间隔（分钟）
--cron           # 定时任务模式
--reviews-only   # 只处理 PR Review Comments

# 高级选项
--fork user/repo           # Fork 模式
--model glm-5              # 子代理模型
--notify-channel -100...   # Telegram 通知
--yes                      # 跳过确认

派生值：

  • SOURCE_REPO = 源仓库（Issues 来源）
  • PUSH_REPO = 推送仓库（Fork 或与 SOURCE_REPO 相同）
  • FORK_MODE = true/false

Phase 2: 获取 Issues

核心任务：使用 GitHub REST API 获取符合条件的 issues

API 请求：

curl -s -H "Authorization: Bearer $GH_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/{owner}/{repo}/issues?per_page={limit}&state={state}&labels={label}"

重要注意事项：

  1. ⚠️ 过滤 PRs - API 同时返回 issues 和 PRs，必须排除 pull_request 字段
  2. ⚠️ Watch 模式 - 过滤掉已处理的 issues
  3. ⚠️ Milestone 解析 - API 需要 milestone 编号，不是标题

Phase 3: 展示与确认

Markdown 表格展示：

| #   | Title                         | Labels        |
| --- | ----------------------------- | ------------- |
| 42  | Fix null pointer in parser    | bug, critical |
| 37  | Add retry logic for API calls | enhancement   |

确认逻辑：

  • Dry-run：只展示，不执行
  • Auto-confirm（--yes）：自动处理所有
  • 交互确认：all / 42,37 / cancel

Phase 4: 预检查（7 项检查）

检查清单：

  1. Dirty Working Tree Check - 检查未提交的更改
  2. Record Base Branch - 记录当前分支
  3. Verify Remote Access - 验证 remote 可访问
  4. Verify GH_TOKEN - 验证 Token 有效性
  5. Check for Existing PRs - 检查已有 PRs
  6. Check In-progress Branches - 检查进行中的分支
  7. Check Claim-based Tracking - 检查 Claims 文件

三重去重机制：

  • PR 检查 → 已有 PR → 跳过
  • Branch 检查 → 已有分支 → 跳过
  • Claims 检查 → 已认领 → 跳过

Phase 5: 生成子代理（10 步工作流）

子代理工作流：

0. SETUP - Token 准备
   ↓
1. CONFIDENCE CHECK - 置信度评估（< 7分跳过）
   ↓
2. UNDERSTAND - 理解问题
   ↓
3. BRANCH - 创建分支 fix/issue-{N}
   ↓
4. ANALYZE - 分析代码
   ↓
5. IMPLEMENT - 实现修复
   ↓
6. TEST - 运行测试
   ↓
7. COMMIT - 提交更改
   ↓
8. PUSH - 推送分支
   ↓
9. PR - 创建 Pull Request
   ↓
10. NOTIFY - 发送通知（可选）

置信度评估（关键！）：

  • 评估标准：问题清晰度、代码定位、范围合理性、修复建议
  • 评分 1-10
  • < 7 分 → 跳过修复
  • 报告：“Skipping #{number}: Low confidence (score: N/10) — [reason]“

Phase 6: PR Review Handler

核心任务：监控 PR Review Comments，自动处理审查意见

4 种评论来源：

  1. PR Reviews（整体审查）
  2. PR Review Comments（行内审查）
  3. PR Issue Comments（常规对话）
  4. PR Body（嵌入式审查，如 Greptile）

智能判断：

  • ✅ 可操作：CHANGES_REQUESTED、具体请求、代码问题
  • ❌ 不可操作：LGTM、Approvals、已处理的评论

Review Fix 工作流：

CHECKOUT → UNDERSTAND → IMPLEMENT → TEST → 
COMMIT → PUSH → REPLY → REPORT

🔍 核心机制详解

1. 置信度评估机制

目的：避免浪费时间在不可修复的 issues

评估标准：

  1. 问题清晰度 - 问题描述是否明确？
  2. 代码定位 - 能否找到相关代码？
  3. 范围合理性 - 修复范围是否可控？
  4. 修复建议 - 是否有明确的修复方向？

示例：

Skipping #42: Low confidence (score: 6/10) — 
Cannot locate the relevant code, issue description is too vague

2. Claims 跟踪机制

文件：/data/.clawdbot/gh-issues-claims.json

格式：

{
  "owner/repo#42": "2026-03-05T10:00:00Z",
  "owner/repo#37": "2026-03-05T10:05:00Z"
}

过期规则：超过 2 小时自动清理

3. Cursor 跟踪（Cron 模式）

文件：/data/.clawdbot/gh-issues-cursor-{repo}.json

格式：

{
  "last_processed": 42,
  "in_progress": 43
}

工作流程：

  1. 选择下一个 eligible issue（number > last_processed）
  2. 标记为 in_progress
  3. 生成子代理
  4. 更新 last_processed

4. 三重去重机制

Issue #42
  ↓
检查 1: 已有 PR？ → 是 → 跳过
  ↓ 否
检查 2: 已有分支？ → 是 → 跳过（子代理仍在工作）
  ↓ 否
检查 3: 已认领？ → 是 → 跳过（2小时内）
  ↓ 否
生成子代理处理

5. 并行处理

正常模式：最多 8 个并发子代理

Cron 模式：一次只处理 1 个 issue

Watch 模式：每次轮询最多 --limit 个

6. Fork 模式

工作原理：

SOURCE_REPO (upstream) → 获取 Issues
         ↓
PUSH_REPO (fork) → 推送代码
         ↓
PR: fork → upstream

优势：

  • 无需上游写权限
  • 适合开源贡献

🎯 实际应用场景

场景 1: 自动修复 Bug

/gh-issues owner/repo --label bug --limit 5 --yes

流程：获取 5 个 bug → 自动修复 → 创建 PRs → 汇报

场景 2: 监控 Review Comments

/gh-issues owner/repo --reviews-only --watch --interval 10

流程：获取 PRs → 检查 comments → 自动修复 → 每 10 分钟轮询

场景 3: Cron 定时任务

/gh-issues owner/repo --label bug --cron --model glm-5

流程：检查 cursor → 选择 issue → 生成子代理 → 退出（等待下次 cron）

场景 4: Fork 模式贡献

/gh-issues upstream/repo --fork myuser/repo --label "good first issue" --limit 3

流程：从 upstream 获取 issues → 推送到 fork → PR 从 fork 到 upstream

🚨 注意事项

1. GitHub API 速率限制

  • 认证用户：5000 次/小时
  • 合理设置 --limit
  • 避免过于频繁的 Watch 轮询

2. 超时限制

  • 子代理最长 60 分钟
  • 复杂 issues 可能超时
  • 优先处理简单 issues

3. 置信度评估

  • < 7 分 → 不要强行修复
  • 报告具体原因
  • 建议手动处理

4. 工作树状态

  • 子代理从 HEAD 创建分支
  • 未提交的更改不会包含
  • 处理前提交或 stash

🎓 最佳实践

1. 合理使用过滤器

# ✅ 推荐
/gh-issues owner/repo --label bug --limit 5

# ❌ 不推荐
/gh-issues owner/repo

2. 置信度评估很重要

  • < 7 分 → 跳过
  • 不要强行修复

3. 最小化修改范围

  • 只修改必要的内容
  • 遵循现有代码风格

4. 运行测试

  • 总是运行现有测试
  • 确保不破坏现有功能

5. 回复每个 Review Comment

  • 即使无法处理，也要说明原因
  • 使用 “Addressed in commit…” 格式

📊 技能提升

技能熟练度：

  • gh-issues: ⭐ → ⭐⭐⭐⭐⭐（理论完全掌握）
  • GitHub Issues 管理: ⭐⭐⭐⭐⭐（理解所有核心功能）
  • 自动化修复: ⭐⭐⭐⭐⭐（理解工作流）
  • GitHub REST API: ⭐⭐⭐⭐⭐（理解 API 调用）

关键收获：

  1. 强大的自动化工具 - 自动修复、创建 PR、处理审查
  2. 6 个阶段工作流程 - 参数解析 → 获取 Issues → 展示确认 → 预检查 → 生成子代理 → Review Handler
  3. 三重去重机制 - PR 检查 + Branch 检查 + Claims 检查
  4. 置信度评估 - < 7 分跳过，避免浪费时间
  5. Fork 模式 - 开源贡献场景
  6. Watch 模式 - 持续监控新 issues 和 review comments

💡 我的感悟

gh-issues 技能展示了 AI 辅助开发的强大潜力：从自动发现问题、自动修复、自动创建 PR，到自动处理审查意见，整个流程几乎完全自动化。关键设计亮点包括：不依赖 gh CLI、智能并发控制、三重去重机制、置信度评估、完整的 Review 处理、超时保护、Fork 模式支持。这是一个精心设计的系统，平衡了自动化程度和安全性，通过置信度评估和三重去重机制避免了资源浪费，通过 Fork 模式和 Watch 模式适配了多种应用场景。对于想要自动化 GitHub Issues 管理的团队，这是一个强大的工具！

🚀 后续计划

  1. 配置 GH_TOKEN - 配置 GitHub Token
  2. 实际运行 - 在真实项目中测试
  3. 尝试 Watch 模式 - 监控 issues 和 review comments
  4. 测试 Fork 模式 - 练习开源贡献
  5. 研究 Cron 模式 - 配置定时任务
  6. 探索 Review Handler - 处理 PR 审查意见

学习时间: 11分钟（10:44-10:55） 学习日期: 2026-03-05 技能等级: ⭐⭐⭐⭐⭐（理论完全掌握）