GitHub Issue Resolver
Autonomous agent for discovering, analyzing, and fixing open GitHub issues — with a 5-layer guardrail system.
⚠️ GUARDRAILS — Read First
Every action goes through guardrails. Before any operation:
- 1. Load
guardrails.json config - Validate scope (repo, branch, path)
- Check action gate (auto/notify/approve)
- Validate command against allowlist
- Log to audit trail
For guardrail details, see references/guardrails-guide.md.
Key Rules (Non-Negotiable)
- - Never touch protected branches (main, master, production)
- Never modify .env, secrets, CI configs, credentials
- Never force push
- Never modify dependency files without explicit approval
- Never modify own skill/plugin files
- One issue at a time — finish or abandon before starting new
- All dangerous actions require user approval (write code, commit, push, PR)
- Everything is logged to
audit/ directory
Workflow
Phase 1 — Issue Discovery
Trigger: User provides a GitHub repository (owner/repo).
Steps:
- 1. Validate repo against guardrails:
python3 scripts/guardrails.py repo <owner> <repo>
If blocked, tell the user and stop.
- 2. Fetch, score, and present issues using the recommendation engine:
python3 scripts/recommend.py <owner> <repo>
This automatically fetches open issues, filters out PRs, scores them by severity/impact/effort/freshness, and presents a formatted recommendation.
Always use recommend.py — never manually format issue output. The script ensures consistent presentation every time.
For raw JSON (e.g., for further processing):
CODEBLOCK2
⏹️ STOP. Wait for user to select an issue.
Phase 2 — Fixing
Trigger: User selects an issue.
Steps:
- 1. Lock the issue (one-at-a-time enforcement):
CODEBLOCK3
- 2. Read full issue thread including comments.
- 3. Clone the repo (Gate:
notify):
CODEBLOCK4
- 4. Create a safe branch (Gate:
auto):
CODEBLOCK5
- 5. Explore codebase — read relevant files. For each file:
CODEBLOCK6
- 6. Plan the fix — explain approach to user:
CODEBLOCK7
⏹️ STOP. Wait for user to approve the plan before implementing.
- 7. Implement the fix (Gate:
approve):
- Apply changes
- Check diff size:
python3 scripts/guardrails.py diff <line_count>
- Log:
python3 scripts/audit.py log_action write_code success
Phase 3 — Testing
After implementing:
- 1. Find and run tests (Gate:
notify):
CODEBLOCK8
- 2. If tests fail AND
autoRollbackOnTestFail is true:
- Revert all changes
- Notify user
- Suggest alternative approach
- 3. If no tests exist, write basic tests covering the fix.
- 4. Report results to user.
Phase 4 — Draft PR for Review (Approval REQUIRED)
⚠️ NEVER create PR automatically. Always ask first.
Do NOT dump full diffs in chat. For any non-trivial project, push the branch
and let the user review on GitHub where they get syntax highlighting, file-by-file
navigation, and inline comments.
- 1. Commit changes (Gate:
approve):
CODEBLOCK9
- 2. Show a change summary (NOT the raw diff) — keep it concise:
CODEBLOCK10
- 3. Ask explicitly: "Ready to push and create a draft PR?"
- 4. Only after user says "yes" (Gate:
approve):
python3 scripts/sandbox.py run git push -u origin fix-issue-<number>
python3 scripts/sandbox.py run gh pr create --draft --title "..." --body "..."
Note: PRs are always created as
draft by default.
The PR body should include a detailed description of all changes, test results,
and link to the issue (Closes #N).
- 5. Share the PR link — user reviews on GitHub.
- 6. Unlock the issue:
python3 scripts/guardrails.py issue_unlock
Scripts Reference
| Script | Purpose | Run Without Reading |
|---|
| INLINECODE13 | Primary entry point — fetch, score, and present issues | ✅ |
| INLINECODE14 |
Raw issue fetcher (used internally by recommend.py) | ✅ |
|
scripts/analyze_issue.py | Deep analysis of single issue | ✅ |
|
scripts/create_pr.py | PR creation wrapper | ✅ |
|
scripts/guardrails.py | Guardrail enforcement engine | ✅ |
|
scripts/sandbox.py | Safe command execution wrapper | ✅ |
|
scripts/audit.py | Action logger | ✅ |
References
GitHub Issue 解决器
用于发现、分析和修复开放 GitHub Issue 的自主代理 — 配备5层防护栏系统。
⚠️ 防护栏 — 请先阅读
每个操作都经过防护栏检查。 在执行任何操作之前:
- 1. 加载 guardrails.json 配置
- 验证范围(仓库、分支、路径)
- 检查操作门控(自动/通知/审批)
- 根据允许列表验证命令
- 记录到审计追踪
有关防护栏的详细信息,请参阅 references/guardrails-guide.md。
关键规则(不可协商)
- - 绝不触碰受保护分支(main、master、production)
- 绝不修改 .env、密钥、CI配置、凭证
- 绝不强制推送
- 未经明确批准绝不修改依赖文件
- 绝不修改自身技能/插件文件
- 一次只处理一个 Issue — 完成或放弃后才能开始新任务
- 所有危险操作均需用户批准(编写代码、提交、推送、PR)
- 所有操作均记录到 audit/ 目录
工作流程
阶段 1 — Issue 发现
触发条件: 用户提供 GitHub 仓库(owner/repo)。
步骤:
- 1. 根据防护栏验证仓库:
bash
python3 scripts/guardrails.py repo
如果被阻止,告知用户并停止。
- 2. 使用推荐引擎获取、评分并展示 Issue:
bash
python3 scripts/recommend.py
此脚本自动获取开放 Issue,过滤掉 PR,根据严重性/影响/工作量/新鲜度进行评分,并以格式化推荐形式展示。
始终使用 recommend.py — 绝不要手动格式化 Issue 输出。该脚本确保每次展示的一致性。
如需原始 JSON(例如用于进一步处理):
bash
python3 scripts/recommend.py --json
⏹️ 停止。等待用户选择 Issue。
阶段 2 — 修复
触发条件: 用户选择 Issue。
步骤:
- 1. 锁定 Issue(一次只处理一个的强制措施):
bash
python3 scripts/guardrails.py issuelock number>
- 2. 阅读完整 Issue 线程,包括评论。
- 3. 克隆仓库(门控:notify):
bash
python3 scripts/sandbox.py run git clone https://github.com//.git /tmp/openclaw-work/
- 4. 创建安全分支(门控:auto):
bash
python3 scripts/sandbox.py run git checkout -b fix-issue-
- 5. 探索代码库 — 读取相关文件。对于每个文件:
bash
python3 scripts/guardrails.py path
- 6. 制定修复方案 — 向用户解释方法:
## 建议修复方案
- 问题:[根本原因]
- 解决方案:[变更内容]
- 文件:[文件列表及各文件变更内容]
- 预估差异大小:[行数]
⏹️ 停止。等待用户批准方案后再实施。
- 7. 实施修复(门控:approve):
- 应用变更
- 检查差异大小:python3 scripts/guardrails.py diff
- 记录:python3 scripts/audit.py logaction writecode success
阶段 3 — 测试
实施后:
- 1. 查找并运行测试(门控:notify):
bash
python3 scripts/sandbox.py run npm test # 或 pytest、cargo test 等
- 2. 如果测试失败且 autoRollbackOnTestFail 为 true:
- 回滚所有变更
- 通知用户
- 建议替代方案
- 3. 如果没有测试存在,编写覆盖修复内容的基本测试。
- 4. 向用户报告结果。
阶段 4 — 草稿 PR 供审查(需要审批)
⚠️ 绝不自动创建 PR。始终先询问。
不要在聊天中倾倒完整差异。 对于任何非平凡项目,推送分支并让用户在 GitHub 上审查,那里有语法高亮、逐文件导航和内联评论。
- 1. 提交变更(门控:approve):
bash
python3 scripts/sandbox.py run git add .
python3 scripts/sandbox.py run git commit -m Fix #:
- 2. 展示变更摘要(而非原始差异)— 保持简洁:
## 变更内容
- src/models.py — 添加字段验证(标题长度、枚举检查)
- app.py — 为 POST 端点添加验证、400 错误响应
- tests/test_app.py — 22 个覆盖验证规则的新测试
- 4 个文件变更,约 100 行源代码 + 约 150 行测试代码
- 所有测试通过 ✅
- 3. 明确询问: 准备好推送并创建草稿 PR 了吗?
- 4. 仅在用户说是之后(门控:approve):
bash
python3 scripts/sandbox.py run git push -u origin fix-issue-
python3 scripts/sandbox.py run gh pr create --draft --title ... --body ...
注意:PR 默认始终创建为草稿。
PR 正文应包含所有变更的详细描述、测试结果以及 Issue 链接(Closes #N)。
- 5. 分享 PR 链接 — 用户在 GitHub 上审查。
- 6. 解锁 Issue:
bash
python3 scripts/guardrails.py issue_unlock
脚本参考
| 脚本 | 用途 | 无需阅读即可运行 |
|---|
| scripts/recommend.py | 主要入口点 — 获取、评分并展示 Issue | ✅ |
| scripts/fetch_issues.py |
原始 Issue 获取器(由 recommend.py 内部使用) | ✅ |
| scripts/analyze_issue.py | 单个 Issue 的深度分析 | ✅ |
| scripts/create_pr.py | PR 创建封装器 | ✅ |
| scripts/guardrails.py | 防护栏执行引擎 | ✅ |
| scripts/sandbox.py | 安全命令执行封装器 | ✅ |
| scripts/audit.py | 操作记录器 | ✅ |
参考资料