gemini-cli 自动修 Bug 流水线解析Bug Fixer Agent 系统提示词设计与源码级实现【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli在 gemini-cli 仓库的 tools/caretaker-agent 目录下运行着一条“GitHub Issue → 自动定位 → 自动修复 → 自动评测 → 自动提交 PR”的无人值守流水线caretaker-agent。本文以该流水线中 PR 生成器pr-generator的第一轮编码智能体系统提示词 bug_fixer_prompt.md 为主体完整拆解它对“自动修 Bug 的 Coding Agent”的角色约束、输入规范、四阶段工作流与安全边界并结合 orchestrator.py、agent_runner.py 等源码说明这份提示词是如何被装载进无头headless沙箱、与工具白名单和迭代循环协同工作的。读完后你将掌握一份面向自动化代码修改场景的系统提示词应该如何设计其“强制动作、输入契约、验证闭环与越权护栏”以及这类 Agent 在 Cloud Run 环境中运行的完整机制。提示词在 PR 生成流水线中的位置pr-generator 由一个 Python 工作流目录驱动入口是 worker.py它初始化 Config 并启动 Orchestrator 状态机。状态机按轮次循环第 1 轮调用Coding Agent系统提示词文件正是bug_fixer_prompt.mdorchestrator.py 第 341-351 行第 2 轮及以后若评测未通过则改用 code_revision_prompt.md 读取上一轮反馈pr_feedback.md进行定向修订每轮代码生成后由 code_evaluator_prompt.md 定义的 Evaluator Agent 输出verdict.json判定APPROVED或NEEDS_REVISION。也就是说bug_fixer_prompt.md是这条“生成—评测—修订”迭代环的起点提示词它面对的输入是上游 triage 阶段产出的“可执行缺陷规格”workable_spec产出则是对目标仓库的真实文件修改。角色定义以测试驱动和防回归为目标的自主工程师提示词开篇的 Role 一节给出的定位是You are an expert autonomous software engineer specializing in bug resolution, test-driven development, and regression prevention.即“专长于缺陷解决、测试驱动开发TDD与回归防护的专家级自主软件工程师”。任务目标被明确限定为三步接收 bug 规格 → 在本地仓库应用修复 → 实现完备测试并验证。值得注意的是角色措辞中反复出现autonomous自主——这意味着 Agent 运行在无人值守环境中不可能停下来向人提问。这一前提正是后面“CRITICAL EXECUTION RULES”中“不得只看不改”“不得请求许可”等硬性规则的由来。三条关键执行规则对抗 LLM 的“只读惰性”提示词中最具工程价值的是 CRITICAL EXECUTION RULES 一节它针对 LLM Agent 常见的三类失败模式设置了强约束强制文件编辑MANDATORY FILE EDITS必须使用文件编辑工具replace_file_content、multi_replace_file_content或write_file修改workable_spec.implementation_plan.files_to_modify中列出的文件并向workable_spec.testing_strategy.test_file添加新的测试断言禁止“看完即止”DO NOT STOP AFTER VIEWING OR BASELINE TESTS绝不允许在仅读取文件或仅运行未修改的基线测试后就结束会话必须在本地工作区产生具体文件修改立即应用编辑APPLY EDITS IMMEDIATELY打开并查看目标文件后应立即用编辑工具应用修复与测试断言随后用run_command验证。这三条规则与运行环境的源码实现形成了精确呼应。agent_runner.py 第 38-65 行 定义了无头沙箱的工具白名单与自动批准钩子# Permitted tool allowlist for headless sandbox operations ALLOWED_SANDBOX_TOOLS { # Reading tools view_file, read_file, # File writing editing tools replace_file_content, multi_replace_file_content, write_file, write_to_file, # Command execution run_command, } if hooks is not None: hooks.pre_tool_call_decide def auto_approve_all_tools(context, tool_call) - str: Only auto-approves safe, allowlisted tools in headless mode. if tool_call.name in ALLOWED_SANDBOX_TOOLS: return PROCEED return REJECT从源码结构看提示词中点名的replace_file_content、multi_replace_file_content、write_file、run_command恰好都落在白名单内白名单内工具被pre_tool_call_decide钩子自动放行无人点击“允许”名单外工具一律REJECT。这解释了为什么提示词需要反复强调“必须用编辑工具落盘”——因为无头环境里不存在人工确认Agent 若只停留在“阅读 思考”层面会话就会被白白消耗掉。输入规范workable_spec 字段契约提示词规定 Agent 会收到一个包含workable_spec的 JSON 载荷需要提取的关键字段如下字段路径含义提示词中的用途workable_spec.implementation_plan.files_to_modify目标文件清单限定必须修改的文件范围workable_spec.implementation_plan.steps详细修复步骤说明修复实施的逐步指令workable_spec.testing_strategy.framework测试框架如 Vitest、Jest、Pytest决定新测试用什么框架编写workable_spec.testing_strategy.test_file测试应添加/更新的测试文件测试断言的落点workable_spec.testing_strategy.verification_steps需要验证的具体断言/场景测试用例的设计依据这份规格并非凭空传给 Agent。在 orchestrator.py 第 215-221 行Orchestrator 会把校验通过的 Firestore 文档原样落盘为 PR 工作区根目录下的firestore_doc.json——这正是提示词 Phase 1 要求解析的文件。规格中的另一个顶层字段issue_idorchestrator.py 第 159 行与github_metadataowner/repo/issue_number则用于后续的锁校验、分支命名与 PR 创建。工作流详解四个阶段如何落地Phase 1摄入与验证Ingestion Validation解析 JSON 输入即firestore_doc.json从workable_spec中提取全部相关细节验证本地环境确认自己位于目标仓库根目录确认files_to_modify列出的文件存在检查test_file是否存在若不存在则计划创建它。对应的环境准备由 Orchestrator 在 Agent 启动前完成orchestrator.py 第 102-143 行克隆或同步origin/main、设置 bot 的 git 身份、把firestore_doc.json/pr_feedback.md/changes.diff等管线产物写入.git/info/exclude以免污染git status再git checkout -B ssr-agent-issue_num origin/main切出特性分支并以NODE_OPTIONS--max-old-space-size4096 npm ci --no-audit --no-fund --maxsockets 3安装依赖orchestrator.py 第 200-213 行。所以提示词里“确认位于仓库根目录”这条实际上由外层AgentRunner的工作目录切换保证run_agent通过 working_directory 上下文管理器 将进程 CWD 切到repo_path并用全局asyncio.Lock串行化因为os.chdir是进程级操作。Phase 2实施MANDATORY FILE EDITS应用代码修改使用replace_file_content或write_file严格依照steps修改files_to_modify中的文件不重构无关代码保持改动最小化并聚焦于该 bug实现测试打开或创建test_file添加与verification_steps对齐的新测试用例确保使用指定framework测试需整洁、可读必要时对外部依赖做 mock。这里“最小化改动”原则与外层状态机形成闭环_prepare_iteration_commitorchestrator.py 第 372-397 行 实际位于 orchestrator.py对每轮工作区做git add . git reset --soft origin/main后生成 diff若第 1 轮没有任何改动会直接抛OrchestrationError(Failed to generate any code changes in the first iteration.)终止本次任务。换言之“只看不改”不仅浪费一次迭代还会让整次 Job 失败。Phase 3验证与校验Verification Validation提示词对验证阶段的命令选择做了非常具体的规定只跑目标测试只运行test_file中的测试来验证修复明确禁项不要运行npm run preflight推荐命令形式以 Vitest 为例npx vitest run path/to/test_filenpm test -w workspace -- path/to/test_file零失败要求目标测试文件内所有用例必须全部通过失败迭代若失败分析错误输出 → 用文件编辑工具修正实现或测试 → 重跑目标测试 → 循环直至干净通过。只跑目标测试而非全量套件是受计算资源约束的工程决策整个 Job 容器限额为 2 CPU / 8Gi 内存、超时 3600 秒见 job.yaml。确定性回归检查则由 Orchestrator 在评测通过后另行执行——_run_regression_checksorchestrator.py 第 530-574 行在评测沙箱中执行npm run clean、npm ci并对test:ci类失败通过 PreflightFilter 的白名单规则判断是否可豁免。Phase 4报告Reporting概述所做修改并列出被修改的文件列出运行的测试及其通过/失败状态确认未检测到回归。这一节对应的是 Agent 会话结束时的文本输出最终会被AgentRunner.run_agent收集进full_output按step_index排序拼接 content 与 thoughts见 agent_runner.py 第 234-247 行供上层日志追溯。约束与安全边界提示词末尾的 Constraints Safety 三条规则划定了 Coding Agent 的行为边界不得运行git commit、git push或任何修改远程仓库的命令改动只留在工作目录不得修改files_to_modify与test_file之外的文件除非有明确理由例如测试框架所需的包配置更新新代码必须匹配现有代码库的风格与模式。这些约束与白名单机制互为表里即便 Agent 试图git pushrun_command虽在白名单内可以执行但外层 Orchestrator 才是真正掌握 git 远程操作的一方——它使用内存中的http.extraHeader认证头推送分支并调用 GitHubClient 创建 PRorchestrator.py 第 647-691 行。把“改代码”与“推代码”分离给两个信任层级是该流水线安全设计的核心Agent 永远只是工作区的编辑者而非发布者。提示词的装载与执行机制从源码看这份 Markdown 提示词的运行链路如下Orchestrator.__init__将script_dir指向 agent_prompts 目录orchestrator.py 第 75-82 行第 1 轮调用时传入system_prompt_filebug_fixer_prompt.mdAgentRunner._load_prompt_file读取文件内容作为system_instructions并做路径穿越防护agent_runner.py 第 99-121 行若文件缺失则回退到默认指令并记 warningLocalAgentConfig(vertexTrue, project..., location..., model..., system_instructions..., workspaces[repo_path])组装本地 Agent 配置默认模型为gemini-3.5-flash由 config.py 的MODEL_NAME环境变量控制job.yaml 中亦有同一默认值任务级 prompt 由 Orchestrator 动态拼接orchestrator.py 第 342-350 行内容与提示词中 CRITICAL 规则高度一致——强制编辑、禁止只读收场、headless 沙箱中用run_command直接执行测试命令、不要在聊天中请求许可。依赖方面requirements.txt 声明了google-antigravity0.1.0、google-cloud-firestore、google-genai等核心包Dockerfile 基于python:3.11-slim从官方node:20-slim镜像拷入 Node 20因为 Agent 需要执行npx vitest等 npm 命令以非 root 用户运行workflow/worker.py。迭代上限、500 行护栏与人工兜底bug_fixer_prompt.md的“失败即迭代”策略有明确的上界均由源码中的确定性逻辑执行最大轮数MAX_ATTEMPTS环境变量默认 5最小 1见 config.py 第 41-44 行并发双锁任务启动前经 db_interface.py 的 Firestore 事务获取 15 分钟锁lock.holderlock.expires_at状态置为COMMIT_GENERATIONgeneration_attempts 2时直接转NEEDS_HUMAN改动规模护栏即使 Evaluator 给出APPROVED若git diff --stat origin/main统计的增删行数超过 500 行同样转入NEEDS_HUMANorchestrator.py 第 272-288 行失败兜底Workflow 层workflow.yaml捕获 Job 异常后将 Firestore 文档状态改写为NEEDS_HUMAN并清空锁字段Cloud Run Job 自身配置maxRetries: 2job.yaml。这套“提示词自律 白名单强制 状态机兜底”的三层防线正是该提示词设计的深层逻辑LLM 的输出不可完全信任因此每一条提示词中的关键规则必须编辑、禁止 push、限定测试命令在 Orchestrator、工具钩子或 Firestore 状态机中都有对应的确定性执行者。与评测/修订提示词的分工理解bug_fixer_prompt.md的边界需要对照同目录的另两份提示词code_evaluator_prompt.md评测者明确“不得自己修代码”只依据changes.diff与规格做正确性、安全性含 ReDoS、敏感信息泄漏检查、可读性评审读取 Orchestrator 预先生成的linter_output.txt不得自行跑 linter最终输出verdict.json并按严格格式## Commit Message/## PR Description两级标题供 Orchestrator 正则解析写出pr_details.md或pr_feedback.mdcode_revision_prompt.md修订者以pr_feedback.md为驱动做定向精修且被限制在“最多 3 个回合”内完成要求第一轮就直接应用修改。三者构成清晰的职责切分Bug Fixer 负责首轮“从规格到实现”、Evaluator 负责独立审查、Revision Agent 负责按反馈收敛而文件级交互firestore_doc.json、changes.diff、verdict.json、pr_feedback.md、pr_details.md全部被写进 git exclude避免污染 diff。小结bug_fixer_prompt.md 表面上是一份 90 余行的系统提示词实际上是一份“无头编码 Agent 的操作契约”它用 CRITICAL 规则消灭 LLM 的只读惰性用workable_spec字段表锁定输入输出契约用四阶段工作流规范“摄入—实施—验证—报告”的闭环用安全约束把 Agent 关在“工作区编辑者”的角色里。而真正让这份契约可信的是仓库中的配套实现——agent_runner.py 的工具白名单钩子、orchestrator.py 的迭代状态机、db_interface.py 的 Firestore 双锁与状态转移以及 job.yaml/workflow.yaml 定义的资源与重试边界。对希望自建“自动修 Bug Agent”的团队而言这套“提示词设计 确定性护栏”的分工方式以及agent_prompts、workflow、tests含 test_orchestrator.py 等测试的目录组织都是可直接参考的工程范式。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考