SuperAPI AI 工具集

triage-issue

编程与开发

查看项目

更新于 10-16 07:44

技能介绍

triage-issue 是一个缺陷排查(triage)技能,用于调查已报告的 bug 并定位到根因,然后输出一份以 TDD 形态组织的修复计划,作为 issue 工件。根据资料,它主要在以下情况触发:用户报告 bug、说出 "triage",或提出相关排查请求。该技能的设计理念是尽量不以交互方式打扰用户,最大程度减少用户提示。

处理流程

  1. 捕获问题(最多一次提示) 如果用户尚未描述 bug,则只问一个问题:"What's the problem you're seeing?" 然后立即开始调查,不再追加追问。

  2. 探索与诊断 派出 Explore agent,查明:bug 表现位置(入口点、UI、API 响应);执行了哪条代码路径(追踪流程);为何失败(根因,而非仅症状);相关代码(相似模式、相邻模块、已有测试)。可使用 git --no-pager grep -n -C 3 <pattern> 和 ast-grep run -p '<pattern>' -l <lang> -C 3 进行结构化追踪。

  3. 确定修复形态 基于调查锁定:针对根因的最小改动;受影响的模块及其接口契约;需要测试覆盖的行为;分类:regression / missing feature / design flaw。

  4. 设计 TDD 修复计划 按 RED-GREEN 循环组织成有序列表,每个循环是通过公共接口的垂直切片。规则:测试断言通过公共接口可观察的行为,而非内部控制状态;一次一个测试;垂直切片,不采用"先写全部测试,再写全部代码";每个测试必须能在内部大幅重构后依然成立;如确需清理,包含一个最终 REFACTOR 步骤。持久性门槛:计划读起来像规格说明,而非补丁;不包含文件路径、行号或内部结构体名称。

  5. 提交 issue 使用 gh issue create --title "<bug summary>" --body-file <tmp> 并套用模板。不要先让用户审阅,直接提交,然后分享 URL 和一句话根因总结。

模板结构包括:Problem(Actual 实际发生、Expected 预期、Repro 复现步骤或"非确定性;在 <上下文> 中观察到");Root Cause Analysis(涉及的代码路径,用模块+行为描述而非文件路径;当前代码为何失败,是契约违规而非某行;促成因素);TDD Fix Plan(每一步 RED:写断言某可观察行为的测试;GREEN:最小改动使其通过;可选 REFACTOR);Acceptance Criteria(验收标准清单)。

资料还给出了跨技术栈的 RED-GREEN 示例:Python(pytest)中,RED 测试断言 account_service.balance(new_id) == Decimal("0"),GREEN 在账户构造函数中初始化默认余额;Rust(cargo test)中,RED 测试断言 service.balance(id)? == Decimal::ZERO,GREEN 在 Account::new 中初始化默认余额。

适用场景:适用于用户报告 bug、需要进行根因排查并生成结构化修复计划的开发流程,尤其希望减少交互、直接产出可交付 issue 的场景。限制:资料未提供关于该技能的其它限制、平台约束、收费或价格信息,相关事实暂未提供。