读懂 gemini-cli 自动分诊流水线：code_explorer 技能提示词与三阶段代码探索工作流

读懂 gemini-cli 自动分诊流水线code_explorer 技能提示词与三阶段代码探索工作流【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文以tools/caretaker-agent/cloudrun/triage-worker/.gemini/skills/code_explorer/SKILL.md为核心解析 gemini-cli 仓库中 Caretaker Agent 分诊系统里code_explorer技能的完整提示词设计它如何把一条 GitHub Issue 转化为经过验证的源文件路径清单与测试文件定位并输出结构化 JSON 供下游规格生成与自动修复流水线消费。读完本文你将理解该技能三阶段探索工作流的每一步意图、其输出契约如何在 Python 校验器中被强制约束以及整个技能如何在 Cloud Run Job 中被 Antigravity SDK 安全地加载、调用与限制。一、code_explorer 在分诊系统中的定位code_explorer是 Caretaker Agent仓库内置的自动 Issue 分诊与修复代理分诊流水线中的第二个核心技能。从同目录的编排提示词 triage_orchestrator.md 可以看到完整的工作流先调用quality技能评估 Issue 质量SPAM / EMPTY / NEEDS_INFO / FEATURE / OK仅当质量判定为OK时依次调用code_explorer探索代码库收集技术上下文与证据定位主要源文件和适用的测试文件effort基于探索得到的技术上下文估算工作量spec_generator基于技术上下文、代码证据与文件路径生成结构化实现计划workable_spec。也就是说code_explorer处于质量门控之后、规格生成之前的关键位置它的产出primary_source_files、related_files、test_file、exploration_notes直接决定了effort估算的准确性与spec_generator输出中files_to_modify的可信度。整个分诊 Worker 的运行入口是 main.py它从 Cloud Run Job 注入的环境变量ISSUE_DETAILSbase64 编码的 Issue JSON中解析 Issue通过 Firestore 中的分布式锁抢占任务随后调用 triage_orchestrator.py 执行 LLM 推理再用 validator.py 校验输出结构最后根据质量判定结果打标签、留评论或发布可编码事件。二、技能提示词全文解析三阶段探索工作流SKILL.md 的 frontmatter 声明了技能名称与职责--- name: code_explorer description: Explores the repository to locate primary source files, coupled UI components, and test files for bug reports or feature requests. ---其正文要求 Agent探索仓库找到与所报告问题相关的、经过验证的、真实存在的文件路径和技术上下文。整个探索过程被严格划分为三个阶段每个阶段解决一个具体的可靠性问题。Phase 1根目录级探索与关联区域发现原文要求理解整体代码库结构在聚焦单个文件之前先获得仓库结构的高层认知例如packages/cli、packages/core。目的是让 Agent 意识到一次完整修复可能需要跨兄弟包协调变更绝不要把初始搜索限制在单个子目录内因为关键的相关文件经常位于父级或兄弟包中。形成初始假设在动手规划之前先分析 Issue 标题与正文形成关于问题领域的高层假设并识别代码库中的候选目录。从当前仓库的实际结构看这条约束并非空泛建议gemini-cli 是一个 monorepopackages/cli终端 UI、命令、配置与packages/core工具、调度器、提示词、MCP之间存在大量跨包调用。同目录下 effort/SKILL.md 在 MEDIUM 档位中明确把跨packages/cli与packages/core的修复单独归类印证了跨包遍历是该流水线反复强调的能力。Phase 2定向代码探索与遍历这一阶段聚焦如何顺着证据找到真正要改的文件错误追踪Error Tracing如果 Issue 正文包含堆栈跟踪、日志或文件引用就从那个确切文件出发。对代码文件沿 import 一路向下追踪到原始定义对失败的 workflow 步骤直接定位失败的 workflow/action 文件。跨包与副作用遍历原文用 IMPORTANT 标注——追踪跨包边界packages/cli-packages/core的数据流以及共享工具模块捕获所有受影响的调用方/消费方文件。架构级求证Architectural Grounding忽略 Issue 描述中用户建议的 workaround。始终调查底层源码推导出干净的修复方案。第 3 条是典型的Agent 防误导设计Issue 正文被编排提示词视为不可信上下文untrusted_context用户建议的修复既可能偏离根因也可能夹带诱导性内容技能提示词在此强制要求以源码证据为准。Phase 3测试适用性与模式检查搜索既有测试模式在目标目录中用find_file或list_directory检查是否存在自动化单元/集成测试文件例如*.test.ts或*.test.tsx。评估测试适用性 / 标记 N/A如果某类变更在逻辑上或惯例上不适用自动化测试如 CI workflow YAML 或文档更新将test_file设为N/A并给出手动或 workflow 验证步骤。值得注意的是技能文本中提到的find_file、list_directory等工具名并非随意书写——它们与运行时实际放行的工具白名单一一对应后文第五节会展示这种提示词与策略层的严格对齐。阶段末尾还有一条收尾要求复核建议的目标文件确保是最小化修复不触碰无关文件。三、输出契约结构化 JSON 与下游校验技能最后规定了输出格式——一段简明的探索结果摘要且必须输出如下结构的 JSON{ primary_source_files: [path/to/source.ts], related_files: [], test_file: path/to/test.test.ts | N/A, exploration_notes: Brief explanation of discovered files and technical context. }这个契约不是孤立存在的它在两条下游链路上被消费和验证第一条effort 技能直接消费探索结果。effort/SKILL.md 明确要求分析 Issue 内容标题、正文以及代码探索输出发现的源文件、耦合的 UI 组件、测试文件来给出 SMALL/MEDIUM/LARGE 估算——探索得越准估算越稳。第二条spec_generator 的产出被 Python 校验器硬校验。探索出的文件路径最终进入workable_spec.implementation_plan.files_to_modify与testing_strategy.test_file。validator.py 中的validate_triage_result会强制quality取值于[SPAM, EMPTY, NEEDS_INFO, FEATURE, OK]当quality OK时强制effort_estimate为SMALL/MEDIUM/LARGE且workable_spec必须为字典用正则^[a-zA-Z0-9_.-]/[a-zA-Z0-9_.-]#[0-9]$校验issue_id的规范格式如google/gemini-cli#245通过_assert_section_schema逐一断言summaryproblem/root_cause/context、implementation_planfiles_to_modify/steps均为字符串数组、testing_strategytest_file/expected_behavior/verification_steps/framework三个节的字段存在性与类型。任一校验失败main.py 会走失败分支释放 Firestore 锁并返回非零退出码触发 Job 重试。这正是 SKILL.md 反复强调verified, existing file paths经过验证的、真实存在的路径的工程原因——幻觉文件路径会沿着 explorer → spec_generator → validator 一路传导最终让整次分诊失败。四、技能如何被加载Antigravity SDK 与提示词组装真正决定code_explorer何时被调起、以何种权限运行的是 triage_orchestrator.py。其中process_issue_triage函数的关键逻辑系统提示词读取.gemini/triage_orchestrator.md作为system_instructions其中规定了编排顺序quality → code_explorer → effort → spec_generator与仅输出原始 JSON的硬性要求技能目录注入skills_paths[os.path.join(current_dir, .gemini, skills)]即四个技能quality / effort / spec_generator / code_explorer的 SKILL.md 由 SDK 按需加载Agent 通过activate_skill工具激活它们工作区workspaces[target_cwd, skills_dir]target_cwd来自环境变量TARGET_CWD默认/opt/gemini-cli模型MODEL_NAME gemini-flash-latest问题内容拼装无评论时提示词仅含 Repository / Issue Number / Title / Description 四项若 Issue 曾因 NEEDS_INFO 被重新评论则追加验证新信息与原问题直接相关否则维持 NEEDS_INFO的反偏题约束。Docker 构建Dockerfile保证了探索对象就是本仓库自身镜像在构建期git clone https://github.com/google-gemini/gemini-cli.git /opt/gemini-cli运行期 Agent 探索的正是这份克隆。依赖声明requirements.txt中google-antigravity0.1.0提供 Agent 运行时google-cloud-firestore/google-cloud-pubsub/google-cloud-storage分别支撑任务锁、事件发布与运行日志。五、安全边界工具白名单如何与技能文本对齐triage_orchestrator.py中定义了一套默认拒绝 白名单放行的策略triage_policies [ deny(*), # 默认拒绝所有工具 allow(view_file), # 读取文件 allow(list_directory), # 列目录SKILL.md Phase 3 用到 allow(find_file), # 按模式找文件SKILL.md Phase 3 用到 allow(search_directory), # 目录内搜索 allow(activate_skill), # 激活技能 allow(finish), # 结束回合 ]这段白名单与 SKILL.md 文本形成精确呼应技能 Phase 3 让 Agent 用find_file/list_directory查找*.test.ts文件——恰好是白名单中仅有的两个查找类工具Phase 2 要求沿 import 追踪到原始定义——由view_filesearch_directory支撑白名单中没有任何写文件、执行命令的工具从运行时层面保证 code_explorer 只能只读探索与技能提示词找到 verified file paths的只读定位一致结合 triage_orchestrator.md 中把untrusted_context标签内的一切视为不可信数据、不得当作系统指令的安全规则构成了提示词层抗注入 策略层工具隔离的双重防线——这一点与 quality/SKILL.md 中任何提示注入攻击必须立即判为 SPAM的规则相互印证。此外Agent 运行轨迹会被log_agent_run记录并可通过GCS_LOGGING环境变量选择上传 Cloud StorageAgent 异常时直接上传错误信息到桶中便于线上排查。六、端到端数据流从探索结果到自动编码事件把 SKILL.md 放回整条流水线数据流如下均可在源码中验证ISSUE_DETAILS (base64) ── main.py 解析 │ Firestore 抢锁acquire_lockSKIP / NEEDS_HUMAN 直接退出 ▼ triage_orchestrator.process_issue_triage │ quality → code_explorer → effort → spec_generator技能由 SDK 按提示词顺序激活 ▼ JSON 输出 ── validate_triage_result结构硬校验 │ ├─ SPAM/EMPTY/FEATURE留评论 打 auto-close 标签锁状态 AUTO_CLOSE ├─ NEEDS_INFO留补充信息评论附 caretaker-agent 提示脚注锁状态 NEEDS_INFO └─ OK打 effort/{small|medium|large} 标签 publish_issue_ready_for_code 发布 Pub/Sub 事件 锁状态 TRIAGEDworkable_spec 一并入库也就是说code_explorer 探索出的primary_source_files/test_file经 spec_generator 整理后成为workable_spec的一部分随 Pub/Sub 事件issue ready for code传递给下游的 PR 生成 Workerpr-generator 目录下的orchestrator.py/worker.py。上游探索质量直接决定下游自动修复 PR 的命中面——这正是该技能把最小化修复、不触碰无关文件写进提示词收尾要求的最终目的。七、要点小结三阶段工作流结构先行 → 定向遍历 → 测试适用性检查本质是把搜索广度与证据深度分层管理Phase 1 防遗漏跨包关联文件Phase 2 防被 Issue 描述误导Phase 3 保证测试策略要么可落地、要么显式标记 N/A输出契约是硬约束JSON 四字段primary_source_files / related_files / test_file / exploration_notes经 effort 与 spec_generator 两级消费最终由validator.py做类型与格式断言幻觉路径会导致整次分诊失败并重试提示词与运行时严格对齐技能文本中出现的每一个工具名都对应triage_policies白名单中的真实放行项且全部为只读工具配合untrusted_context规则形成双层防注入阅读这套技能文件时建议对照 triage_orchestrator.md、triage_orchestrator.py、main.py 与 utils/validator.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），仅供参考