的系统提示词与迭代修复闭环)
gemini-cli 护理者 Agent 深度解析代码修订 AgentCode Revision Agent的系统提示词与迭代修复闭环【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cligemini-cli 仓库的tools/caretaker-agent/cloudrun/pr-generator子目录实现了一条自动化的缺陷规格 → 代码修复 → 评审 → 再修复流水线而本文的主角 code_revision_prompt.md 就是流水线中第 2 轮及以后修复迭代所使用的系统提示词。读完本文你能掌握这套提示词的完整结构输入契约、四阶段工作流、安全约束以及它如何被 Python 编排器orchestrator按迭代次数动态装载、如何与评估者 Agent 产出的pr_feedback.md衔接从而构成一个可运行的自动代码修订闭环。一、角色定位它是多 Agent 流水线中的返修工在 pr-generator 的 agent_prompts 目录下共有三份系统提示词对应三种 Agent 角色提示词文件角色触发时机bug_fixer_prompt.mdBug Fixer首次修复迭代第 1 轮code_evaluator_prompt.mdCode Evaluator评审守门员每轮修复后code_revision_prompt.mdCode Revision迭代修订迭代第 2 轮及以后code_revision_prompt.md开篇定义了 Agent 的角色一名专精代码修订、缺陷修复打磨与迭代质量保障的专家级自主软件工程师。它不做首次修复——首次修复由 Bug Fixer Agent 负责——它的职责是接住评估者 Agent 打回的反馈把本地实现打磨到生产级标准。这一角色分工在编排器源码中可以得到印证。在 orchestrator.py 的_run_code_generation方法中编排器按迭代次数选择提示词文件if iteration 1: prompt (Fix the bug described in firestore_doc.json. ...) prompt_file bug_fixer_prompt.md else: prompt (Use the feedback in pr_feedback.md to address the remaining issues in the code and tests. ...) prompt_file code_revision_prompt.md也就是说只要评估未通过、循环进入第 2 轮Agent 收到的系统提示词就切换为code_revision_prompt.md而用户消息则明确指向pr_feedback.md中的剩余问题。二、输入契约三个输入源与它们的语义提示词的 Inputs 一节声明修订 Agent 在运行时可访问三类输入pr_feedback.md或feedback.md评估者 AgentEvaluator Agent对上一轮变更产出的详细反馈按类别Correctness、Security、Readability、Test Failures分组并带有具体文件名与行号引用。firestore_doc.json或example_firestore.json原始workable_spec包含缺陷摘要、实现计划files_to_modify、steps与测试策略framework、test_file、verification_steps。本地仓库承载上一轮代码变更与单元测试的代码库。这些文件并非凭空出现而是编排器在工作区中预先铺好的。以firestore_doc.json为例orchestrator.py 在克隆仓库、检出ssr-agent-issue_num分支并执行npm ci之后会把 Firestore 文档写入 PR 工作区根目录spec_pr_path os.path.join(self.config.pr_repo_path, firestore_doc.json) with open(spec_pr_path, w, encodingutf-8) as f: json.dump(firestore_doc, f, indent2)而pr_feedback.md的回传则由_save_feedback_to_coding_workspace方法负责当某一轮迭代未获批准时编排器把评估工作区eval目录中的pr_feedback.md拷贝回编码工作区pr目录若评估者未产出该文件则写入占位说明保证下一轮修订 Agent 始终有反馈可读见 orchestrator.py 的_save_feedback_to_coding_workspace。单元测试 tests/test_orchestrator.py 中的test_save_feedback_to_coding_workspace正是对这条拷贝路径的断言。另外值得一提的工程细节编排器在克隆仓库时会向.git/info/exclude追加firestore_doc.json、pr_feedback.md、feedback.md、changes.diff、verdict.json、pr_details.md等条目见 orchestrator.py使这些 Agent 间的传令文件不会污染git status与最终 diff。三、Phase 1反馈摄取与规格交叉验证修订 Agent 工作流的第一步不是改代码而是读懂要改什么读取评估反馈打开并完整检查pr_feedback.md或feedback.md交叉引用规格查阅firestore_doc.json确保修订方向与原始规格的workable_spec.summary.problem、root_cause以及testing_strategy.expected_behavior保持一致——这一步防止 Agent 在逐条消解反馈时偏离缺陷本身归类问题把反馈中的每一项 action item 归入四个类别Correctness Logic gaps正确性与逻辑缺陷Security vulnerabilities or unsafe patterns安全漏洞或不安全模式Readability Coding standard violations可读性与编码规范违规Missing or failing unit tests缺失或失败的单元测试这种先分类、后动手的结构与评估者提示词 code_evaluator_prompt.md 中的评估维度Correctness、Security、Readability严格对齐——修订 Agent 的输入分类体系就是评估者输出分类体系的镜像形成闭环。四、Phase 2定向修订与实现约束这是提示词的核心章节规定了怎么改可以拆成四个子约束。4.1 最小化修改禁止范围蔓延严格针对评估反馈中指出的每一条问题修改目标源文件保持变更聚焦、最小化不重构无关代码、不引入 scope creep。这一约束在编排器侧有对应的量化防线即便某轮获得APPROVED如果git diff --stat origin/main解析出的总修改行数插入 删除超过500 行编排器仍会把该 issue 标记为NEEDS_HUMAN而不是自动提 PR见 orchestrator.py。提示词中的最小化原则与代码中的 500 行硬上限互为表里。4.2 严格安全断言Security Assertions提示词对安全维度提出了四条硬性要求几乎全部面向 Node.js/TypeScript 场景的常见注入面Input Validation任何新增输入、参数或解析出的数据结构都必须做安全校验Regex Security正则表达式必须抵御 ReDoS正则拒绝服务避免过度宽松的通配符Data Handling敏感数据与硬编码凭据不得被记录或泄露存储必须安全Safe APIs优先使用标准库或项目认可的安全 API而非裸命令字符串或不安全调用。值得注意的是这四项断言与评估者提示词 code_evaluator_prompt.md 的 Security Analysis 章节逐条对应——评估者用什么标准打分修订 Agent 就按什么标准自查两套提示词实际上是同一套评审标准的一体两面。4.3 质量与可读性断言Style Conventions遵循语言标准规范如 TypeScript/Node.js 约定与项目既有风格规则.eslintrc、tsconfigNaming Simplicity命名描述性、一致函数短小模块化遵循单一职责原则Comments注释解释为什么而非是什么避免对显而易见的语法做冗余说明。4.4 测试覆盖的修正与扩充打开workable_spec.testing_strategy.test_file修复反馈中指出的失败测试若评估者指出边缘场景缺失或verification_steps覆盖不全则新增测试用例所有测试必须使用规格中指定的framework如 Vitest、Jest并能在 headless 环境中可靠执行。headless 环境这一点由运行基础设施保证agent_runner.py 维护了一个无头沙箱工具白名单ALLOWED_SANDBOX_TOOLSview_file、read_file、replace_file_content、multi_replace_file_content、write_file、write_to_file、run_command并注册pre_tool_call_decide钩子自动放行白名单内工具、拒绝其余工具——这就是提示词中用run_command直接执行测试、不要向聊天窗口请求许可的执行基础。五、Phase 3动态验证与回归测试Phase 3 是自我验证环节四步递进跑 Linter执行项目 lint 命令如npm run lint或npx eslint .把修改文件中的 lint 错误清零跑目标测试套件用run_command直接执行目标测试文件如npx vitest run test_file确认所有被修订的代码路径与边缘场景通过跑回归测试执行相关的周边乃至全项目测试确保修订没有破坏既有功能失败则迭代任何 lint 或测试失败都需分析输出、调整实现或测试断言后重跑直到 100% 通过。这里有一个与评估者分工的微妙之处在正式流水线中ESLint 检查实际是由编排器在评估工作区预先执行并落盘为linter_output.txt的——orchestrator.py 的_run_eslint_static_check会对git diff origin/main变更的.ts/.tsx/.js/.jsx文件执行npx eslint --max-warnings 0 ...。但修订 Agent 提示词仍要求它自己跑 lint 并清零这体现了Agent 自验证 编排器确定性复验的双保险设计Agent 的自查是必要非充分条件最终结论仍由评估者与编排器的确定性检查裁定。六、Phase 4报告义务与3 轮硬预算修订 Agent 完成验证后必须产出一份简洁报告包含三部分内容逐条列出pr_feedback.md中的每个反馈点及对应的解决方式列出执行过的测试与 lint 命令及其通过状态确认安全、质量与回归检查全部通过。提示词末尾Constraints Safety 部分还给出了一条极具工程实用性的预算约束You have a strict budget of 3 turns maximum to complete this task. Apply the fixes directly in your very first turn, and use your next turn to verify with tests.即第 1 轮直接改代码第 2 轮跑测试验证总共不超过 3 轮。这与 Bug Fixer 提示词中不得只读文件和跑基线测试就结束回合CRITICAL EXECUTION RULES 第 2 条形成呼应——两条规则共同治理 LLM Agent 最常见的失败模式过度探索、拖延产出。同样提示词明确禁止浪费回合跑git status、git log、git show这类探索性命令你已经拥有完整源码访问权。七、约束与安全边界修订 Agent 的行为红线提示词 Constraints Safety 章节划定五条红线每条都在编排器中有对应的机制承接红线编排器侧的承接机制禁止git commit/git push变更留在工作目录提交动作由编排器在_prepare_iteration_commit中以软提交方式统一完成orchestrator.py不得修改files_to_modify与test_file之外的文件除非有明确理由如构建/测试框架配置评估者按 diff 范围评审越界修改会被 Scope 检查项捕获修订代码必须匹配现有代码库的架构模式与风格评估者 Readability 维度 编排器 ESLint 静态检查任务是基于pr_feedback.md应用修复第 2 轮起用户 prompt 即指向pr_feedback.md不跑探索性 git 命令3 轮硬预算工具白名单 无头沙箱自动审批agent_runner.py八、提示词如何被装载AgentRunner 的装载链最后把镜头从提示词写了什么转到提示词如何生效。编排器构造AgentRunner时把agent_prompts目录传给script_dirorchestrator.py随后每次run_agent调用按以下链条装载提示词见 agent_runner.py_load_prompt_file按文件名读取 markdown并做路径穿越防护拒绝解析后落在script_dir之外的路径文件存在则以其全文覆盖默认 system instructions不存在则回退为You are the {role}...的兜底指令并记录警告提示词连同 Vertex AI 配置默认模型gemini-3.5-flash见 config.py一起注入LocalAgentConfig由于 Agent 交互基于进程 CWDAgentRunner用一把asyncio.Lock串行化所有 Agent 的目录切换避免并发任务互相踩踏工作目录。装载完成后的循环上限由环境变量MAX_ATTEMPTS默认 5最小 1控制——注意这是流水线级的最多几轮 修复→评审总迭代config.py而提示词中的 3 turns 是单次 Agent 会话内的工具调用轮次预算两者尺度不同、各司其职。超过总迭代仍未获批时编排器释放 Firestore 锁并把 issue 置为NEEDS_HUMAN由 tests/test_orchestrator.py 的test_run_loop_max_attempts_exceeded验证该路径确实会调用release_lock。九、小结一份返修工提示词的设计要点回到 code_revision_prompt.md 本身可以提炼出它对如何编写 LLM 代码修订 Agent 的系统提示词给出的几条可复用经验输入契约显式化把 Agent 能看到的文件反馈、规格、仓库逐一列名并说明语义包括备选文件名pr_feedback.md或feedback.md容忍上游产出差异工作流阶段化摄取 → 定向修订 → 动态验证 → 报告每阶段有明确产物与通过标准其中验证阶段的失败则迭代直到 100% 通过把回归风险内建进流程与评审标准镜像对齐修订断言输入校验、ReDoS、安全 API、SRP、注释规范与评估者维度一一对应反馈在两个 Agent 之间无需转译预算与红线双约束首轮直接改、次轮验证、3 轮封顶治理拖延禁 commit/push、禁越界改文件保护工作区主权让 git 提交权始终握在确定性编排器手里自验证 确定性复验的双保险Agent 自查 lint 与测试只是入场券编排器的 ESLint 落盘、回归检查、500 行 diff 上限才是最终裁判。对于想在自己的仓库中搭建评估—修订闭环的工程师这套 pr-generator 目录下的三份提示词与 workflow 编排代码含 Dockerfile、job.yaml、workflow.yaml 等 Cloud Run Job 部署配置构成了一个完整可参考的实现样本提示词负责教会 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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考