AI Agent Issue 分诊Triage工作流解析oh-my-posh code-changes Skill 的 Phase 1 特殊入口【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-poshoh-my-posh 仓库在 .agents 目录下为 AI 编码代理内置了一套名为 code-changes 的完整编排工作流本文聚焦其中针对纯 Issue 分诊场景设计的特殊入口——issue-triage.md。这篇文章将讲解什么请求应当走分诊入口、四步分诊流程如何执行、分析报告需要满足怎样的结构化契约以及停止门stop gate如何在分诊与实施之间建立强制边界。读完你不仅能按规范完成一次高质量的 Issue 分诊还能理解它如何与 Analyze、Plan、Verify 等阶段无缝衔接。一、Issue 分诊在 code-changes 工作流中的定位code-changes 是 oh-my-posh 仓库中定义的一套从 Issue、PR、想法到交付代码的编排工作流整体分为六个阶段Analyze → Plan → Delegate → Supervise → Verify → Deliver详见 SKILL.md。它有一个核心纪律分析永远先行代码永远最后Analysis always comes first; code comes last。在这条主流程之外SKILL.md 声明了两个特殊案例Special cases它们是Phase 1Analyze的替代入口而不是独立轨道Pull request 评审意见处理 → pr-review-comments.mdIssue 分诊 → issue-triage.md关键约束在于无论任务从哪扇门进入都必须产出同一种分析报告工件见 artifacts.md这样 Plan 阶段无需关心任务来自哪扇门即可直接消费。其余流程Phases 2–6对特殊案例原样适用。二、入口判定什么请求该走分诊入口issue-triage.md 的开头给出了明确的入口谓词。当任务的措辞是纯粹的裸分诊——例如look at issue #n看一下 #n 号 Issue、triage #n分诊 #n、is #n still valid#n 是否仍然有效——且没有要求任何修复时走本入口。反过来如果请求已经隐含了修复意图例如fix issue #n、issue #n: users cant log in则直接使用 analyze.md而不是分诊入口。原因在文档中讲得很清楚analyze.md 的开头就陈述了这一谓词——fix这类措辞本身就携带了越过停止门的许可carries the go past the stop gate而分诊入口是仅交付分析的入口不包含这份许可。两篇文档在这一点上互为镜像判定时先看请求是否隐含修复动作即可。三、四步分诊流程分诊入口将 Phase 1 的分析工作收敛为四个明确步骤每一步都有可执行的指令1. 收集完整信息gh issue view n --comments第一步是读取完整报告、每一条评论以及链接的 Issuelinked issues。这与 analyze.md 的收集完整上下文阶段一致不仅要看 Issue 正文还要看后续讨论、引用内容以及报告指向的任何代码。分诊的输入质量直接决定输出质量跳过评论区往往意味着丢失了最关键的复现细节或已尝试的排查路径。2. 复现问题第二步是复现报告描述的行为。文档明确要求先复现、再理论化Reproduce before theorizing与 analyze.md 同源。一次成功的复现能把分析从假设变成事实并为后续 Verify 阶段免费提供验证用例。同时文档也给出了现实约束当复现所需的运行环境无法满足时例如缺少特定操作系统、Shell、字体或硬件必须明说——明确指出无法在当前环境复现并退而求其次基于代码推理且推理结果要在报告中标注为未经复现验证unverified-by-repro。诚实标注证据边界比含糊其辞的应该没问题有价值得多。3. 在代码中定位根因而非在 Issue 文本中找第三步是分诊最核心的纪律根因要到代码里去找而不是在 Issue 文本里找。Issue 报告描述的是症状symptoms而且常常对原因做出错误猜测Issue reports describe symptoms and often guess wrong about causes。这与 analyze.md 中的警告完全一致绝不单凭 Issue 文本、评审意见或堆栈跟踪下结论——报告和机器人评审经常出错。实操上对应 analyze.md 的检查既有成果做法查找现有辅助函数、相似模块/段以及曾经改动过同一区域的提交git log -- path避免重复发明轮子。同时要区分根因与症状修在崩溃发生的位置不等于修在崩溃发生的原因上。4. 评估影响范围Blast Radius最后一步回答三个问题谁还会受影响who else is affected从什么时候开始受影响——定位是哪个 release 或哪次 commit 引入的问题since when是否存在绕过方案whether workarounds exist。影响面评估是分诊区别于普通代码阅读的关键产出之一它决定了修复的优先级、是否需要紧急处理以及是否应该在修复落地前先给用户一个可行的 workaround。四、交付物一份结构化分析报告分诊的交付物是一份面向用户的书面分析报告包含四个必填部分确认或无法复现Confirmed / Could-not-reproduce必须附带证据根因Root cause必须附带文件引用file references建议修复及其范围Proposed fix and its scope或者说明为什么不需要修复——包括三种典型情况符合预期works-as-intended、重复 Issueduplicate、环境问题environment problem建议回复Suggested reply当发现需要反馈给上游时给出拟好的 Issue 回复文案。这份报告直接映射到 Phase 1 的标准工件结构。artifacts.md 定义了分析报告的五个字段字段含义root_cause发生了什么、为什么附文件引用proposed_change修复范围详细到足以据此拆分任务out_of_scope刻意不动的部分repro_statusreproduced-with-evidence有证据复现或 unverified-by-repro未复现验证附原因open_questions尚未解决的问题停止门通过后应为空issue-triage.md 明确写道报告映射到root_cause/proposed_change/out_of_scope/repro_status/open_questions这一工件Plan 阶段可以直接原样接住so Plan can pick it up unchanged。这正是整个工作流以工件为交接契约设计思想的体现阶段之间不靠口头交接而靠落成文字的结构化工件。五、停止门Stop Gate分诊不等于放行实施issue-triage.md 的最后一节是Gate它声明了一个强制约束This is the Phase 1 stop gate: implement only on go, then continue from Phase 2.这是 Phase 1 的停止门只有收到明确放行信号才允许实施放行后从 Phase 2Plan继续。这一设计与主流程的停止门一脉相承。SKILL.md 规定Phase 1 结束时必须把分析与建议方案报告给用户并等待放行只有用户在请求中已经给出明确 go例如do it、fix it and commit、implement with Sonnet时才可跳过停止门。而 analyze.md 进一步补了两个关键边界为分析给出的 go不等于为实施给出的 go第一次通过时给的 go不会顺延到 Verify 失败后的重新诊断——每次重进 Phase 1 都会重新激活停止门。对分诊场景而言triaging和fixing是两件截然不同的事分诊的产出是分析本身实施必须等用户明确点头。这个门的存在防止了 Agent 在看一下 #n这种低强度请求下擅自越界改代码。六、与后续阶段的衔接与升级机制分诊完成后流程回到主轨道PlanPhase 2直接从分诊报告钉规格pinned spec拆任务、定并行/串行、分配工作区主树或隔离 worktree、规划合并顺序详见 plan.mdDelegatePhase 3按任务匹配执行者层级trivial / implementer / coordinator-direct模型分层的具体映射见 model-tiers.mdVerifyPhase 5只在合并后的最终状态上运行质量门与功能验证且绝不向下委派详见 verify.mdDeliverPhase 6遵循 conventional-commit 与用户未要求则不 push/不开 PR的推送政策详见 deliver.md。分诊过程中如果出现以下情形可以触发升级Escalation——向最强推理模型提出一个具体的判断题而不是交出整个阶段见 escalate.md读完代码后仍无法有把握地钉住根因而不是反复重读报告修复呈架构性跨越模块边界、触碰公共 API/接口、引入横切抽象涉及安全、认证、加密、支付或数据迁移操作不可逆或影响面大schema 迁移、删除、force-push、生产配置Verify 连续第二次把同一任务打回见 verify.md 的重试上限。大多数分诊任务不应触发升级——协调者层级Coordinator足以独立完成分析、评审与验证升级只发生在真正需要的调用点上。七、最佳实践小结把 issue-triage.md 与整套 code-changes 工作流放在一起看可以提炼出几条可迁移的分诊纪律先判入口再动手纯分诊走 issue-triage.md隐含修复的请求直接走 analyze.md两者殊途同归到同一份分析报告证据分级能复现就给出有证据复现环境受限就明说并基于代码推理标注未经复现验证根因在代码不在文本Issue 描述症状且常猜错原因永远以实际实现为准量化影响面回答影响谁、何时引入、有无 workaround三个问题报告结构化root_cause/proposed_change/out_of_scope/repro_status/open_questions五字段齐全Plan 才能无脑接住尊重停止门分诊的产出是分析实施必须等用户明确的 go绝不擅自越界需要沟通就给出回复文案当发现应反馈上游时交付一份可直接使用的 Issue 回复。这套规范虽然以 oh-my-posh 仓库的 .agents/skills 目录为载体但其先分析、门控放行、工件交接、分级执行的骨架具有通用性——任何以代码变更收尾的 Agent 任务都可以借鉴这套分诊入口的设计来避免看一眼就动手的常见失误。【免费下载链接】oh-my-poshThe most customisable and low-latency cross platform/shell prompt renderer项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-posh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考