Royi15/Bug-Hunter-Agent

# 🐛 Bug Hunter Agent 一款由 AI 驱动的 CLI 工具，能自动为您的源代码生成单元测试并执行它们。当测试失败时，它会生成详细的错误报告，尝试通过 AI 生成修复方案，并通过重新运行相同的测试来验证修复效果。该循环将重复进行，直到测试通过或您选择停止。 由 **Gemini 3.1 Flash Lite** 通过免费的 Google AI Studio API 提供支持。 ## 🚀 工作原理 该 Agent 会将您的源文件通过六个阶段的 pipeline 进行处理： ``` ┌─────────────────────────────────────────────────────┐ │ Your Source Code │ └─────────────────────────┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 1. Code Ingestion │ │ - Validates file extension against supported │ │ language list │ │ - Reads the source file from disk │ └─────────────────────────┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 2. Test Generation (Gemini 3.1 Flash Lite) │ │ - Verifies the content is real source code │ │ - Derives expected behaviour from function │ │ names, docstrings, and type hints — NOT from │ │ tracing through the implementation │ │ - Generates adversarial unit tests │ └─────────────────────────┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ 3. Test Executor │ │ - Saves generated tests to bug_hunter_output/ │ │ - Runs pytest / jest locally OR in Docker │ │ - Captures stdout and stderr │ └──────────────┬──────────────────────┬───────────────┘ │ │ [PASSED] [FAILED] │ │ ▼ ▼ Save logs & end ┌──────────────────────────────┐ │ 4. Error Analysis Engine │ │ (Gemini 3.1 Flash Lite) │ │ - Source + Tests + Log │ │ - Root-cause analysis │ └──────────────┬───────────────┘ │ ▼ ┌──────────────────────────────┐ │ 5. Artifacts │ │ bug_hunter_output/ │ │ ├── test_generated.py │ │ ├── terminal_output.log │ │ └── REPORT.md │ └──────────────┬───────────────┘ │ ▼ ┌──────────────────────────────┐ │ 6. Code Fixer │ │ (Gemini 3.1 Flash Lite) │ │ │ │ User picks: │ │ 1. Do nothing │ │ 2. Save fix as a new file │ │ 3. Overwrite original file │ └──────────────┬───────────────┘ │ ▼ ┌──────────────────────────────┐ │ Verification │ │ Re-runs the same tests on │ │ the fixed code (no new API │ │ call — zero extra tokens) │ └──────┬───────────────┬───────┘ │ │ [PASSED] [FAILED] │ │ ▼ ▼ Done! Re-analyse & loop back to step 6 ``` ## 🛠️ 环境要求 - Python 3.9+ - 一个免费的 **Gemini API key**（见下文） - 用于 Python 文件的 `pytest`，用于 JS/TS 文件的 `jest`（仅在**本地**执行时需要） - **Docker Desktop** *(可选)* — 用于在沙盒隔离的容器中执行（参见 [Docker 支持](#docker-support)） - **Bash** — hooks 运行所必需（见下文说明） ### Windows 上的 Bash 这些 hooks 是 shell 脚本，需要一个 `bash` 解释器。在 **macOS 和 Linux** 上，系统已自带该环境。在 **Windows** 上，您需要以下之一： - **Git for Windows** *(推荐 — 您可能已经安装了)* — 会自动安装 Git Bash 并将 `bash.exe` 添加到您的 PATH 中。可在 [git-scm.com](https://git-scm.com/download/win) 下载。 - **WSL (Windows Subsystem for Linux)** — Windows 内部的完整 Linux 环境。在管理员权限的 PowerShell 中运行 `wsl --install` 进行启用。 要在安装后验证 bash 是否可用，请在终端中运行： ``` bash --version ``` 如果您看到版本号，说明 hooks 可以正常工作。如果提示找不到命令，请先安装 Git for Windows。 ## ⚙️ 安装说明 ### 1. 获取免费的 Gemini API key 前往 **[Google AI Studio](https://aistudio.google.com/app/apikey)**，使用您的 Google 账号登录，然后点击 **Create API Key**。完全免费 — 无需信用卡。 ### 2. 克隆并安装依赖 ``` git clone cd Bug-Hunter-Agent pip install -r requirements.txt ``` ### 3. 添加您的 API key 在主根目录下打开一个 `.env` 文件并输入： ``` GEMINI_API_KEY=your_actual_key_here ``` ### 4. (可选) 安装 pytest 如果您尚未安装： ``` pip install pytest ``` ## 用法 ``` python bug_hunter.py ``` **示例：** ``` python bug_hunter.py mycode.py python bug_hunter.py src/utils.js python bug_hunter.py lib/parser.ts ``` **输出示例 — 测试失败，已应用并验证修复：** ``` ══════════════════════════════════════════════════════ Bug Hunter Agent ══════════════════════════════════════════════════════ Docker is available. Where would you like to run the tests? 1. Run locally (uses your system Python / Node) 2. Run in Docker (isolated container — make sure Docker is running) Your choice (1/2): 1 [1/4] Ingested 'mycode.py' (Python, 842 chars) [2/4] Generating tests with gemini-3.1-flash-lite... 7 test case(s) planned via pytest [3/4] Running: python -m pytest bug_hunter_output/test_generated_code.py -v --tb=short Tests FAILED (exit 1) [4/4] Analyzing failures with Gemini 3.1 Flash Lite... ────────────────────────────────────────────────────── Bugs found. What would you like to do? ────────────────────────────────────────────────────── 1. Do nothing — keep the original file as-is 2. Create a copy — save the fixed code to a new file 3. Fix in place — overwrite the original file ────────────────────────────────────────────────────── Your choice (1/2/3): 2 [FIX] Requesting fix from Gemini... [FIX] Fixed copy saved to: mycode_fixed.py [VERIFY] Re-running existing tests against the fixed code... Tests PASSED (exit 0) [VERIFY] All tests passed — fix confirmed! ══════════════════════════════════════════════════════ Artifacts saved to: bug_hunter_output/ test_generated_code.py (unit tests) terminal_output.log (raw console log) REPORT.md (bug analysis) Fixed copy: mycode_fixed.py ══════════════════════════════════════════════════════ ``` ## 🐳 Docker 支持 每次运行 Agent 时，系统都会询问您是在本地还是在隔离的 Docker 容器中执行生成的测试。该决定会根据您机器上安装的软件自动做出。 ### 提示的工作原理 **如果安装了 Docker Desktop：** ``` Docker is available. Where would you like to run the tests? 1. Run locally (uses your system Python / Node) 2. Run in Docker (isolated container — make sure Docker is running) Your choice (1/2): ``` 选择 **2** 会立即检查 Docker daemon 是否确实在运行。如果已安装 Docker Desktop 但未打开，Agent 会停止运行并提示清晰的信息，而不是静默失败： ``` [ERROR] Docker is installed but the daemon is not running. Please open Docker Desktop and try again. ``` **如果未安装 Docker：** ``` [WARNING] Docker is not installed on this machine. Tests will run locally using your system Python / Node. Proceed locally? (Y/N): ``` 回答 **N** 将正常退出。回答 **Y** 将像往常一样继续在本地执行。 ### 容器内运行的内容 | Framework | Docker image | 测试的安装方式 | |-----------|-------------|------------------------| | pytest | `python:3.11-slim` | `pip install pytest`（如果存在 `requirements.txt` 则加上 `-r requirements.txt`） | | jest | `node:18-slim` | `npm install jest --save-dev` | Agent 会将源文件和生成的测试文件复制到一个临时目录中，将其作为 `/app` 挂载到容器内部，运行测试并捕获输出。每次运行后容器都会被销毁（`--rm`）。 ### 安装 Docker 在 [docker.com/get-started](https://www.docker.com/get-started) 免费下载 **Docker Desktop**。支持 Windows、macOS 和 Linux 平台。 ## 输出文件 所有输出都会写入 `bug_hunter_output/` 目录（已被 gitignore 忽略）。 | 文件 | 描述 | |------|-------------| | `test_generated_code.py` | Gemini 生成的对抗性单元测试套件 | | `terminal_output.log` | 最近一次测试运行的原始 stdout + stderr | | `REPORT.md` | 错误报告 — 仅在测试失败时创建 | `REPORT.md` 包含针对每个 bug 的详细分析：失败原因、根本原因以及带有代码示例的具体修复建议。 ## 代码修复与验证循环 当测试失败时，Agent 会提供三个选项： | 选项 | 处理方式 | |--------|-------------| | **1 — 不进行操作** | 退出。原文件保持不变。 | | **2 — 创建副本** | Gemini 的修复方案会保存为您原文件旁边的 `_fixed.`。永远不会修改原文件。 | | **3 — 原地修复** | Gemini 的修复方案将直接覆盖原文件。 | 保存任何修复方案后，Agent 会自动针对修复后的代码重新运行**相同的测试** — 无需新的 API 调用，也不会消耗额外的 token。如果测试仍然失败，将重新分析错误并再次显示菜单。您可以继续迭代，或者随时选择选项 1 停止。 ## 支持的语言 | 扩展名 | 语言 | 测试运行器 | |-----------|----------|-------------| | `.py` | Python | pytest | | `.js` | JavaScript | jest | | `.ts` | TypeScript | jest | | `.c` | C | pytest | | `.cpp` | C++ | pytest | | `.java` | Java | pytest | | `.go` | Go | pytest | | `.rs` | Rust | pytest | | `.rb` | Ruby | pytest | | `.php` | PHP | pytest | | `.cs` | C# | pytest | | `.kt` | Kotlin | pytest | | `.swift` | Swift | pytest | 扩展名不受支持的文件在进行任何 API 调用之前会立即被拒绝。扩展名受支持但内容并非代码（如随机文本、普通文章、数据文件）的文件会在 Gemini 的内容验证步骤中被拒绝。 ## 🪝 开发者 Hooks 本项目为想要使用 **Claude Code** 处理代码库的开发者配备了完整的 hooks 系统。这些 hooks 与运行 `bug_hunter.py` 毫无关系 — 它们旨在保护开发环境本身。每当 Claude Code 编辑文件、运行命令或结束会话时，hooks 都会自动拦截这些操作，以强制执行安全规则、防止破坏性操作、备份您的文件并总结活动情况。 所有 hooks 都位于 `.claude/hooks/` 中。它们在 `.claude/settings.json` 中注册，并在您使用 Claude Code 处理本项目时自动触发。 ### Hook 概览 | Hook | 事件 | 触发器 | 功能说明 | |------|-------|---------|--------------| | `pre_command_firewall.sh` | PreToolUse | Bash | 阻止匹配危险正则表达式模式的命令 | | `pre_rate_limiter.sh` | PreToolUse | Bash | 统计每个会话的命令数；达到限制时先警告后阻止 | | `pre_commit_validator.sh` | PreToolUse | Bash | 强制要求遵循约定的 commit 消息格式 | | `pre_secrets_guard.sh` | PreToolUse | Read | 阻止 AI 助手读取 `secret_files.txt` 中列出的文件 | | `post_auto_backup.sh` | PostToolUse | Edit / Write | 为每个已编辑的文件创建带有时间戳的备份 | | `post_syntax_checker.sh` | PostToolUse | Edit / Write | 对保存的文件运行语法检查器 (bash/python/gcc) | | `post_session_summary.sh` | Stop | — | 会话结束时打印格式化的活动报告 | ### Hook 详情 #### `pre_command_firewall.sh` 从 `config/dangerous_patterns.txt` 读取正则表达式模式，并阻止任何匹配的 Bash 命令。如果命令被阻止，AI 助手会收到一条错误消息，说明匹配了哪个模式，并被要求使用更安全的替代方案。 **要添加被阻止的模式**，请打开 `config/dangerous_patterns.txt` 并添加一行： ``` # 阻止关闭机器 shutdown\s+ ``` #### `pre_rate_limiter.sh` 使用 `data/.command_count` 跟踪当前会话中运行的 Bash 命令总数。当计数超过 `WARNING_THRESHOLD` 时发出警告，并在达到 `MAX_COMMANDS` 时完全阻止。 **要在会话中途重置计数器**，请创建文件 `data/.reset_commands`（hook 会在下次运行时自动将其删除）： ``` touch .claude/hooks/data/.reset_commands ``` #### `pre_commit_validator.sh` 拦截 `git commit -m "..."` 调用并强制执行以下三项规则： 1. 消息必须以 `config/commit_prefixes.txt` 中的有效前缀开头 2. 消息长度必须在 10 到 72 个字符之间 3. 消息不得以句号结尾 如果未找到前缀，hook 会分析暂存区的 diff 并建议一个前缀： - 新文件 → `feat:` - 测试/spec 文件 → `test:` - Markdown 文件 → `docs:` - 删除多于插入 → `refactor:` **要添加新的有效前缀**，请将其添加到 `config/commit_prefixes.txt`（每行一个）。 #### `pre_secrets_guard.sh` 阻止 AI 助手读取 `config/secret_files.txt` 中列出的任何文件。匹配是基于后缀且不区分大小写的，因此 `.env` 会拦截 `project/.env`、`C:\Users\..\.env` 等。 **要保护其他文件**，请将条目添加到 `config/secret_files.txt`： ``` .env my_credentials.json private_key.pem ``` #### `post_auto_backup.sh` 每次执行 Edit 或 Write 操作后，将修改后的文件复制到 `data/.backups/.`。每个文件仅保留最近的 `MAX_BACKUPS` 个副本；较旧的副本会被自动删除。 所有备份活动都会记录到 `data/session_.log` 中。 #### `post_syntax_checker.sh` 每次执行 Edit 或 Write 操作后，根据文件类型运行相应的语法检查器： | 扩展名 | 检查器 | |-----------|---------| | `.sh`, `.bash` | `bash -n` | | `.py` | `python3 -m py_compile` | | `.c`, `.h` | `gcc -fsyntax-only` | | 其他所有类型 | 静默跳过 | 语法错误将作为警告报告（exit 1） — 它们不会阻断会话。 #### `post_session_summary.sh` 开发会话结束时，读取 `data/session_.log` 并打印格式化的摘要： ``` ════════════════════════════════════════ SESSION SUMMARY REPORT ════════════════════════════════════════ Session: abc123 Period: 2025-05-27 14:00:00 -> 2025-05-27 14:42:17 ── Activity ───────────────────────── Total actions: 18 Backups made: 9 Syntax checks: 9 Syntax errors: 0 ── Most Edited Files ──────────────── 1. bug_hunter.py (6 edits) 2. hooks.conf (2 edits) 3. requirements.txt (1 edit) ── File Types ─────────────────────── .py files: 7 .sh files: 2 ``` ## Hook 配置参考 所有配置文件均位于 `.claude/hooks/config/`。 ### `hooks.conf` 控制速率限制器和备份轮换： ``` # 每个 session 在被阻止前允许的最大 Bash 命令数 MAX_COMMANDS=50 # 达到此阈值时发出警告（必须 < MAX_COMMANDS） WARNING_THRESHOLD=40 # 每个文件保留的最大带时间戳 backups 数量 MAX_BACKUPS=5 ``` ### `dangerous_patterns.txt` 每行一个 POSIX 扩展正则表达式。匹配任何模式的命令都将被阻止。以 `#` 开头的行是注释。 ``` # 默认阻止的内容示例： rm\s+-rf\s+/ # recursive delete of root dd\s+if= # raw disk writes curl.*\|\s*(ba)?sh # piping remote scripts to shell ``` ### `commit_prefixes.txt` 每行一个约定式 commit 前缀。任何不以 `: ` 开头的 `git commit -m` 消息都将被阻止。 ``` feat fix docs refactor test chore ``` ### `secret_files.txt` 每行一个文件名后缀（不区分大小写）。AI 助手无法读取任何路径以列出的条目结尾的文件。 ``` .env .env.local .env.production .env.staging ``` ## 在本地测试 Hooks 使用 `hook_runner.sh` 即可模拟任何 hook 链，而无需活跃的实时会话： ``` # 测试 command 防火墙 — 应该阻止 echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"session_id":"test"}' \ | bash .claude/hooks/hook_runner.sh PreToolUse Bash # 测试安全 command — 应该通过 echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"},"session_id":"test"}' \ | bash .claude/hooks/hook_runner.sh PreToolUse Bash # 测试编辑后的 backup + syntax check 链 echo '{"tool_name":"Edit","tool_input":{"file_path":"bug_hunter.py"},"session_id":"test"}' \ | bash .claude/hooks/hook_runner.sh PostToolUse Edit ``` ## 📂 项目结构 ``` Bug-Hunter-Agent/ ├── bug_hunter.py Main agent ├── requirements.txt ├── .env Your API key (never committed) ├── .gitignore └── .claude/ ├── settings.json Registers hooks with Claude Code └── hooks/ ├── pre_command_firewall.sh ├── pre_rate_limiter.sh ├── pre_commit_validator.sh ├── pre_secrets_guard.sh ├── post_auto_backup.sh ├── post_syntax_checker.sh ├── post_session_summary.sh ├── hook_runner.sh Local hook simulator ├── hooks_config.txt hook_runner.sh routing table ├── config/ │ ├── hooks.conf │ ├── dangerous_patterns.txt │ ├── commit_prefixes.txt │ └── secret_files.txt └── data/ Runtime only — gitignored ├── .backups/ ├── .command_count └── session_.log ``` ## ❌ 常见错误 | 错误 | 原因 | 修复方法 | |-------|-------|-----| | `GEMINI_API_KEY is not set` | 缺少 `.env` 或 key 为空 | 将您的 key 添加到 `.env` 中 | | `Rate limit exceeded` | 达到免费层级限制 | 等待约 1 分钟后重试 | | `Invalid API key` | `.env` 中的 key 错误 | 从 Google AI Studio 重新复制 | | `Unsupported file type` | 扩展名不在支持列表中 | 使用受支持语言的文件 | | `Gemini rejected the file` | 文件扩展名正确但并非真正的代码 | 传入实际的源代码文件 | | 测试中出现 `ModuleNotFoundError` | 源文件不在 Python 路径中 | Agent 会自动设置 `PYTHONPATH` — 请确保您从项目根目录运行 | | `Docker is installed but the daemon is not running` | Docker Desktop 已关闭 | 打开 Docker Desktop 并等待其完成启动，然后重试 | | Docker 输出中出现 `UnicodeDecodeError` | 系统区域设置不匹配 | 已在内部处理 — 输出将作为 UTF-8 读取并使用替换字符 | | Docker 运行长时间卡住 | 首次使用时正在拉取镜像 | 等待约 60 秒；镜像缓存后后续运行会很快 |

标签：AI编程, Docker, IPv6支持, SOC Prime, 代码修复, 单元测试, 安全规则引擎, 安全防御评估, 开发工具, 请求拦截, 逆向工具