Skip to content

README.md

Latest commit

 

History

History
210 lines (157 loc) · 9.38 KB

README.md

File metadata and controls

210 lines (157 loc) · 9.38 KB

Hermes 开源项目 Bug 猎手

一个用于 Hermes Agent 的 Skill，帮助你在开源项目中找到真实的、未被修复的 Bug 和功能增强点，自动完成代码修改、安全审查、测试验证，并提交 PR。

不只是抢 "good first issue"——你能挖到别人还没发现的。

安装

将本仓库克隆到 Hermes 的 skills 目录：

git clone https://github.com/toller892/hermes-oss-bug-hunter.git ~/.hermes/skills/github/open-source-bug-hunting

或者在 Hermes 聊天中直接说：

安装 open-source-bug-hunting skill

使用

在 Hermes 中说：

  • "帮我找一些开源项目的 bug"
  • "我想给 lazygit 提交一个 PR"
  • "扫描 browser-use 的代码看看有没有问题"
  • "找下一个可以贡献的项目"

Hermes 会自动加载 Skill 并走完整流程。

工作流程

┌─────────────────────────────────────────────┐
│ 1. 选择策略                                  │
│    A: 扫 GitHub Issues（快，但热门项目竞争激烈） │
│    A2: 维护者已定位 bug 但没人修（命中率高）     │
│    B: 直接读源码找 bug pattern（慢但质量高）    │
│    C: 做功能增强（竞争少，Go 项目尤佳）          │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ 2. 验证无已有 PR → 3. Clone 复现 → 4. 定位根因 │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ 5. 修改代码                                  │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ 6. 预提交审查（requesting-code-review）       │
│    安全扫描 → 基线测试 → 独立 Reviewer        │
│    → 自动修复 → 通过后才允许提交               │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ 7. Fork → 分支 → Commit → Push → 创建 PR     │
│    ⚠️ Push 前必须验证 diff                    │
│    git diff upstream/main --stat             │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ 8. CI 失败？→ 读日志 → 本地修复 → 验证 → 重推  │
│    （循环直到 CI 全绿）                        │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│ 9. Review 反馈 / 重复 PR / 分支损坏 → 处理     │
└─────────────────────────────────────────────┘

前置条件

运行前确保：

# 1. GitHub CLI 已登录
gh auth status

# 2. Git 身份正确（否则 CLA 必炸）
git config user.name   # 必须和 GitHub 用户名一致
git config user.email  # 必须和 GitHub 账号邮箱一致

# 3. 对应语言工具链
go version      # Go 项目需要
python3 --version  # Python 项目需要
rustc --version # Rust 项目需要

三种策略

策略 A：扫描 GitHub Issues

用 -linked:pr 过滤掉已有 PR 的 issue，批量扫 10-15 个仓库。

注意：help wanted 标签的信号比 good first issue 强。

策略 A2：维护者已诊断的 Issue

维护者已在评论里指出具体文件和行号，但没人动手。这类 issue 已经"半解决"了，写代码就行。

策略 B：直接读源码

Clone 代码，用 grep 扫描常见 bug pattern：

  • except: pass 吞异常
  • .strip() 按字符集误用（不是按子串）
  • raise e 导致批量循环丢失部分结果
  • TOCTOU 竞态条件
  • session 级错误标志应为 request 级（如 _disable_streaming）

策略 C：功能增强

label:enhancement 的 issue 往往没有竞争。Go 项目（lazygit、hugo、caddy）比 Python 项目竞争少得多。

CI 失败处理

PR 提交后 CI 跑红是常态。完整 7 步流程：

  1. 读日志 — gh pr checks 看概要，gh run view --log-failed 看详情
  2. 诊断 — 是你的改动导致的，还是 pre-existing flaky test / infra 故障？
  3. 本地修复 — 先读 .github/workflows/*.yml 找 CI 命令，本地复现再改
  4. 提交 — 单 commit PR 用 --amend；多 commit PR 加新 commit
  5. 重推 — git push --force-with-lease（永远不用裸 --force）
  6. 验证 — gh pr checks --watch 等新 commit CI 通过
  7. 回复 — 简短确认修复，指向 commit hash

常见 CI 失败类型：

类型 特征 典型原因
Lint/格式 golangci-lint, ruff, black 风格违规、未用 import
单元测试 pytest, go test 改动破坏已有测试
编译 go build, cargo build 类型错误、缺 import
DCO/签名 DCO, commitlint 缺 --signoff
CLA cla-assistant commit 作者邮箱不匹配

反模式：不看日志盲推、用 # noqa 压警告不改根因、reviewer 正在审时 force push。

分支损坏处理

比 CI 失败更严重 — diff 本身就是错的（整个文件被删、行数异常）。

诊断：git diff upstream/main --stat 显示大量非预期删除；PR 页面 "0 additions & N deletions"。

修复：

git fetch upstream main
git reset --hard upstream/main
git cherry-pick <正确的commit>
git diff upstream/main --stat  # 验证
git push --force-with-lease origin fix/description

预防：每次 push 前必须跑 git diff upstream/main --stat。5 行改动不该显示 13,000 行。

重复 PR 处理

热门 bug 几小时内就会有多人提交 PR。决策树：

  1. 对方质量更高（有测试、更完整）→ 关闭你的，留个好印象
  2. 对方质量更低或停滞 → 保留你的，说明优势
  3. 两者相当 → 让维护者决定，别争

实战案例

项目 类型 策略 PR 结果
hermes-agent api_mode 被 credential refresh 静默重置 B #17596 Open
hermes-agent _disable_streaming 作用域错误 B #25797 重复+分支损坏
browser-use 批量结果丢失 B #4770 Merged
mem0 vision 禁用时 NoneType 崩溃 A #5023 Open
lazygit 新增"删除 worktree 和分支"菜单 C #5557 Open
bat git worktree diff 检测失效 A2 #3708 Open (blocked)
cli/cli gh repo edit 错误报告 fork 可见性 A #13320 Closed
earthly 新增 --bash-completion-file 参数 C #4352 Open
bubbles 导出未导出的 BlinkCanceled 类型 C #964 Open
FerretDB lll 行长度 130/175 → 120 C #5643 Open
hermes-web-ui unhandledRejection 崩溃 + gateway 状态泄漏 A2 #769 Open

GitHub Token 权限

给开源项目提 PR，建议创建 classic PAT 时勾选：

+ ✅ repo         读写仓库（含 fork、分支、commit、PR）
+ ✅ workflow     推送 .github/workflows/ 下的 CI 文件
+ ✅ delete_repo  出问题时能删除 fork 重新来

为什么 workflow 必带？ 当你 clone 上游最新代码、fork 却落后 N commits 时，git push 会把中间 N 个提交一起推到 fork。只要其中任何一个改过 workflow 文件，没这权限 push 直接被拒——哪怕你的改动跟 CI 毫无关系。

其他 scope 全不需要。 read:org、gist、user、copilot 等跟提 PR 无关，不勾。

文件说明

├── SKILL.md              # Skill 主文件（Hermes 加载入口）
├── README.md             # 本文件
└── references/           # 参考文档
    ├── competitive-landscape.md      # 项目竞争态势
    ├── pr-outcomes-analysis.md       # PR 结果分析（9 个 PR 实战复盘）
    ├── github-pr-monitoring.md       # PR 监控工作流 + CLA 修复
    ├── multi-pr-cla-fix-example.md   # 批量 CLA 修复示例
    ├── pr-25797-branch-corruption-case.md  # 分支损坏案例复盘
    ├── code-equivalence-audit.md     # 代码等价审计方法
    └── hermes-agent-bug-scan-2026-05.md  # hermes-agent 扫描记录

许可

MIT