Multi-AI Debugging 是一款面向 AI 辅助调试的多智能体工作流技能，通过把 Claude、Gemini、Codex 作为专门化智能体协同工作，实现系统化的根因分析与修复生成。其定位基于 2024-2025 年多智能体架构下 AI 辅助调试的最佳实践。
用途 该技能用于系统化的根因分析和修复生成，采用任务型模式，包含 6 个独立的调试操作。
核心原则（经三 AI 研究验证）：多智能体议会，由专门化智能体在达成共识前就根因进行辩论；评估者/批评者循环，由修复智能体与批评智能体共同验证方案；链路感知分析，关注完整执行上下文而非仅错误信息；语义日志分析，让 LLM 理解超出正则匹配的内容；跨栈关联，连接前端、后端与基础设施问题；自动修复，在安全场景下采用自愈模式。
质量目标 根因识别准确率 >80%；常见问题诊断时间 <30 分钟；已知模式修复生成成功率 >60%；错误分类误报率 <20%。
适用时机 适用于：调试生产事故、分析错误日志与堆栈跟踪、执行根因分析（RCA）、排查复杂的多服务系统、调查性能下降、理解级联故障、编写事后复盘报告。 不适用于：简单语法错误（IDE 可处理）、明确的编译期错误、已有完善文档的已知问题。
前置条件 必需：错误信息（日志、堆栈跟踪、错误消息）、对相关代码的访问权限。建议：执行链路（如有）、系统指标/可观测性数据、近期变更历史（git log）、用于网络研究的 Gemini CLI、用于深度代码分析的 Codex CLI。集成方面：OpenTelemetry 链路（理想）、日志聚合（CloudWatch、Datadog 等）、APM 工具（可选）。
操作一：快速错误诊断 时间 2-5 分钟，自动化程度 70%，用于常见错误的快速初步诊断。流程为分析错误并给出错误类型、最可能根因、即时修复建议和预防建议，再用 Gemini 做网络研究验证。输出为带修复建议的快速诊断。
操作二：根因分析（RCA） 时间 15-45 分钟，自动化程度 50%，用于复杂问题的深度根因分析。流程包括：上下文智能体收集上下文（git log、diff、相关日志、系统状态）；分析智能体生成假设，列出 3-5 个按可能性排序的根因并附支持证据、反对证据与置信水平；验证智能体交叉验证，设想预期现象、证伪条件、设计复现测试并给出 0-100 置信度；最后生成含事件、日期、时长、影响、时间线、根因、促成因素、解决方案和预防措施的 RCA 报告。
操作三：日志分析与分类 时间 5-15 分钟，自动化程度 80%，用于分析和分类错误日志。流程为对日志条目聚类，识别唯一错误模式，按类型（Bug/配置/网络/资源/安全/用户错误）、严重度（Critical/High/Medium/Low）、影响（数据丢失/服务中断/降级/轻微）分类，统计各模式出现次数，识别根模式（原始错误与级联错误），推荐调查优先级，并进行语义分析寻找时序异常、事件关联、隐藏依赖和人类可能遗漏的模式。输出为已分类并排序的错误报告。
操作四：多智能体议会调试 时间 20-60 分钟，自动化程度 40%，用于需要多视角的复杂问题。流程为并行启动 4 个调试智能体：代码审查者（逻辑错误、边界情况、竞态条件、资源泄漏）、日志分析者（错误序列、时序模式、状态变化、外部依赖）、系统分析师（资源约束、配置问题、依赖问题、基础设施状态）、历史分析师（近期变更、类似历史事件、回归指标、已知问题匹配）。随后合成发现，找出 2 个及以上智能体一致的共识根因，解决冲突假设，合并最强理论证据，给出总体置信度（0-100）并提出修复与验证步骤。
操作五：自动修复生成 时间 10-30 分钟，自动化程度 60%，用于生成并验证修复。修复智能体生成最小改动、含错误处理、带解释注释并建议测试用例的修复；批评智能体评估修复是否真正解决根因、是否引入新缺陷、边界情况、性能与安全影响，给出 APPROVE/NEEDS_REVISION/REJECT 结论；最后生成回归测试，要求能捕获原始缺陷、验证修复有效、覆盖边界情况并可在 CI/CD 中运行。
操作六：自愈模式 时间不定，自动化程度 90%，用于自动检测与修复。定义修复剧本，例如磁盘空间不足、检测到内存泄漏、错误率飙升等，并列举各自检测条件与动作；同时配置智能断路器，由 AI 根据错误率、p99 延迟、依赖健康度等指标预测级联故障风险，给出 OPEN/CLOSED/HALF_OPEN 建议。
多 AI 协调 任务分配策略示例：日志分析由 Gemini 主责、Claude 验证，优势是快速、大上下文；代码分析由 Claude 主责、Codex 验证，优势是深度理解；根因由 Claude 主责、Gemini 验证，优势是推理加搜索；修复生成由 Claude 主责、Codex 验证；研究由 Gemini 主责、Claude 验证，优势是网络搜索。协调命令提供 Gemini 日志搜索、Claude 根因分析、Codex 修复验证的示例。
决策树 错误类型决策树：先判断是否有堆栈跟踪；有则进入代码错误分析，分别对应空指针/类型错误（缺少空值检查）、越界（边界条件）、超时（资源/网络问题）、权限拒绝（认证/授权问题），未知则用多智能体分析；无堆栈跟踪则进入系统错误分析，分别对应连接被拒（服务宕机）、磁盘满（资源耗尽）、内存不足（内存泄漏/容量）、CPU 飙升（性能问题），未知则用多智能体分析。严重度评估分为 CRITICAL（P1，数据丢失、安全泄露、服务完全宕机、直接收入影响）、HIGH（P2，服务显著降级、影响超 10% 用户、潜在数据完整性问题）、MEDIUM（P3，影响低于 10% 用户、有绕过方案、非关键功能损坏）、LOW（P4，外观问题、边界情况错误、无用户影响）。
可观测性集成 提供 OpenTelemetry 模式代码示例，在 trace 中附加错误类型与消息等调试上下文，并收集 trace_id、父 span 和相关日志，交给多智能体调试。还提供日志关联函数示例，按 trace_id 或错误时间窗口查询日志并交给 AI 分析。
示例调试会话 以“API 间歇性返回 500 错误”为例，展示多智能体调试报告：日志分析者发现错误每 5 分钟激增、与后台任务运行相关、日志簇为“连接池耗尽”；代码审查者发现 /api/users.py:145 未归还数据库连接、缺少 try/finally；系统分析师发现连接池上限 20、峰值并发请求 25+、后台任务占用 10 个连接；历史分析师发现两天前提交 abc123 新增了未限制连接的后台任务。共识根因置信度 92%，为后台任务占用连接加 API 处理器缺少连接清理。随后给出修复前后代码对比，并列出验证步骤（添加连接跟踪指标、运行负载测试、监控后台任务期间的连接池使用）和预防措施（添加连接超时、实现连接泄漏检测、审查所有连接池使用）。
相关技能 包括 multi-ai-code-review（部署前审查修复）、multi-ai-verification（验证修复效果）、multi-ai-testing（生成回归测试）、ecs-troubleshooting（容器专属调试）、railway-troubleshooting（Railway 平台调试）。
参考文件 references/log-analysis-patterns.md 为日志分析技术；references/self-healing-playbooks.md 为自动修复模式。