用途:当需要调试、修复缺陷、排查错误或做根因分析,或用户反馈报错、堆栈跟踪、异常行为时使用。核心原则是“未先做根因调查,不得动手修复”,避免对症下药式修复导致问题反复。
主要能力(分阶段): 一、根因调查:先收集症状(错误信息、堆栈、复现步骤),信息不足时一次只问一个问题;沿症状回溯代码路径,搜索全部引用并阅读失败点逻辑;检查近期变更,例如 git log --oneline -20 -- <affected-files>,判断是否为回归;尝试确定性复现;检索同一区域此前的调试记录,同一文件反复出问题视为架构异味的信号。输出“根因假设”,即具体且可验证的断言。 二、模式分析:判断是否匹配已知模式,如竞态条件(间歇、时序相关,检查共享状态并发访问)、空值传播(NoMethodError、TypeError)、状态损坏(数据不一致、部分更新,检查事务、回调、钩子)、集成失败(超时、异常响应,涉及外部 API 与服务边界)、配置漂移(本地正常、预发或生产失败,涉及环境变量、功能开关、数据库状态)、缓存陈旧(显示旧数据、清缓存即恢复)。同时查阅项目已知问题与同区域历史修复。若均不匹配,在脱敏(去掉主机名、IP、文件路径、SQL、客户数据)后按错误类别而非原始信息做外部搜索。 三、假设验证:写任何修复前先验证假设,可在疑似根因处加临时日志、断言或调试输出并运行复现,看证据是否吻合;假设不成立则回到第一阶段补充证据,不要猜测。三次假设失败即停止,告知用户可能是架构问题,并给出继续调查、升级人工评审或加日志等待复现等选项。警示信号包括“先临时修一下”、未追踪数据流就提修复方案、每修一处又冒出新的问题(层错而非代码错)。 四、实施:确认根因后修根因而非症状,做最小改动(尽量少动文件与行数,不顺手重构相邻代码);编写回归测试,要求修复前失败、修复后通过;运行完整测试套件不得引入回归;若涉及超过 5 个文件,需先向用户标注影响范围。 五、验证与报告:重新复现原始问题确认已修复,运行测试套件,输出结构化调试报告,包含症状、根因、修复(含文件引用)、证据、回归测试位置、相关历史问题与架构备注、状态(DONE、DONE_WITH_CONCERNS、BLOCKED),并将报告按当日日期保存到 memory/ 供后续会话参考。
限制与注意:无法验证的修复不得交付;不得说“这应该能修好”,要运行测试来证明;根因不清时升级处理;间歇性缺陷或需依赖预发环境时状态标注为 DONE_WITH_CONCERNS。资料未提供具体安装命令、依赖环境或费用信息。