企业官网建设流程全解析

• 开发工具
• CLI
• AI 技能/插件
• 测试
• 人工智能
• AI 评测

本篇技术指南围绕 SuperClaude Framework 内置的/sc:troubleshoot斜杠命令展开，系统讲解其触发时机、命令行参数、五步行为流、四类排查模式（代码缺陷、构建失败、性能劣化、部署异常）以及"诊断优先、修复需确认"的安全边界设计。读完本文，你将掌握如何在 Claude Code 会话中一键发起结构化根因分析、阅读并利用诊断报告，并在用户确认后安全应用修复。

命令定位：SuperClaude 的"问题诊断"入口

/sc:troubleshoot是 SuperClaude Framework 三十个斜杠命令中负责质量与排查的核心命令之一，官方定义为：诊断并解决代码、构建、部署与系统行为中的问题（"Diagnose and resolve issues in code, builds, deployments, and system behavior"）。

从命令的元数据（src/superclaude/commands/troubleshoot.md）可以看到它的分类属性：

在命令体系中的位置，可参见 docs/reference/commands-list.md：它归属于"测试与质量"类别，与/sc:test、/sc:analyze、/sc:reflect并列。在"何时用什么命令"的决策树中，/sc:troubleshoot对应的是"SOMETHING BROKEN? → /sc:troubleshoot (find the cause)"这一环节——它只负责找原因，不负责重构，这是理解该命令的关键前提。

命令的定义文件同时存在于两处：src/superclaude/commands/troubleshoot.md（包内源文件）与 plugins/superclaude/commands/troubleshoot.md（插件分发副本），两者内容一致。安装机制由 src/superclaude/cli/install_commands.py 实现：默认将命令文件复制到~/.claude/commands/sc/目录，从而获得/sc:命名空间。

触发时机：什么情况下应该调用它

原文档明确列出了四类典型触发场景，当 Claude Code 会话中出现以下需求时，应优先考虑调用/sc:troubleshoot：

• 代码缺陷与运行时错误调查请求：例如空指针异常、非法参数、逻辑错误的定位与分析；
• 构建失败分析与解决需求：例如编译错误、打包失败的根因排查；
• 性能问题诊断与优化需求：例如接口响应变慢、资源占用异常的定位；
• 部署问题分析与系统行为调试：例如服务无法启动、配置不生效等生产环境问题。

这四类触发场景与命令的--type参数一一对应（详见下文），实际使用时可以直接将问题描述作为命令参数传入。

命令语法与参数详解

/sc:troubleshoot [issue] [--type bug|build|performance|deployment] [--trace] [--fix]

各参数含义如下：

补充说明：--type默认值由问题描述内容推断，当问题描述足够明确（例如直接提及"编译错误"）时可以省略。--trace与--fix可独立使用，例如"深度诊断但不修复"用--trace，"诊断并准备修复"用--fix，两者可以组合为--trace --fix。

五步行为流：从现象到结论的规范路径

命令执行时遵循固定的行为流，每一步都有明确的产出：

1. Analyze（分析）：解析问题描述，收集相关系统状态信息（错误信息、运行环境、最近变更等）；
2. Investigate（调查）：通过系统性模式分析定位潜在根因，形成候选假设；
3. Debug（调试）：执行结构化调试流程，包括日志检查与状态审查，逐一验证假设；
4. Propose（提议）：验证解决方案的可行性，评估影响面与风险等级；
5. Resolve（解决）：应用适当的修复方案，并验证修复是否真正生效。

这五步并非线性空转，其背后有三大核心行为准则：

• 系统性根因分析：坚持"假设—验证—取证"循环，而不是盲目重试；
• 多领域排查能力：覆盖代码、构建、性能、部署四个域；
• 安全修复应用：任何修复都伴随验证环节与文档记录。

值得一提的是，框架在更底层还提供了一份独立的排查协议——plugins/superclaude/skills/troubleshoot/SKILL.md（troubleshoot 技能）。它定义了一条更严格的心智流程：STOP（不重跑相同命令）→ Observe（观察实际与预期差异）→ Hypothesize（列出 2-3 个可能原因）→ Investigate（查文档、日志、栈追踪、配置）→ Root Cause（找到根本原因而非症状）→ Fix（针对根因修复）→ Verify（确认修复生效）→ Learn（沉淀解决方案）。同时它明确列出了一系列严格禁止的反模式：

• "出错了？那就再试一次"（Got an error. Let's just try again）；
• "重试：第 1 次……第 2 次……第 3 次……"（不做任何原因分析的无脑重试）；
• "超时了，那就把等待时间调大"（忽略根因的侥幸处理）；
• "有警告但能跑，那就算了"（为未来埋技术债）。

该技能还规定了标准输出格式——每次排查必须产出如下结构化的根因分析报告：

## Root Cause Analysis **Error**: [Exact error message] **Expected**: [What should have happened] **Cause**: [Root cause with evidence] **Fix**: [Solution addressing root cause] **Prevention**: [How to prevent recurrence]

/sc:troubleshoot命令的行为流与该技能协议相互呼应：命令负责流程编排与多域排查，技能负责底层的心智纪律与反模式约束，共同保证"诊断出根因"而非"掩盖症状"。

工具协调：排查过程中的工具矩阵

诊断过程并非空谈，命令会协调 Claude Code 的四大基础工具完成取证：

• Read：日志分析、系统状态检查——读取错误日志、配置文件、状态文件；
• Bash：诊断命令执行与系统调查——运行测试、检查进程、抓取系统信息；
• Grep：错误模式检测与日志分析——在日志与代码中检索错误签名、重复出现的异常模式；
• Write：诊断报告与解决方案文档的落盘——输出结构化的排查结论。

这套"读文件—跑命令—搜模式—写报告"的组合，保证了每一个诊断结论都有可复核的证据链支撑。

关键排查模式：四类问题的标准打法

原文档给出了四类问题的模式化排查路径，这也是--type参数的实战意义所在：

选择正确的--type能让排查聚焦在正确的证据源上：例如bug类问题优先看栈追踪与相关代码路径，build类问题优先看构建日志与依赖树，performance类问题优先看指标与热点，deployment类问题优先看环境差异与配置一致性。

实战示例：四类问题的完整调用

以下四个示例完整保留自原文档，展示了真实会话中的调用方式与预期产出：

1. 代码缺陷调查

/sc:troubleshoot "Null pointer exception in user service" --type bug --trace # Systematic analysis of error context and stack traces # Identifies root cause and provides targeted fix recommendations

--trace让分析深入错误上下文与栈追踪，目标是定位空指针的真正来源（例如未初始化的依赖、空集合遍历），而不是表层报错行。

2. 构建失败分析

/sc:troubleshoot "TypeScript compilation errors" --type build --fix # Analyzes build logs and TypeScript configuration # Automatically applies safe fixes for common compilation issues

注意这里带了--fix：命令会先分析构建日志与 tsconfig 配置，然后在征得用户确认后对常见编译问题应用安全修复。带--fix的调用路径是"诊断 → 向用户确认 → 应用修复 → 用测试验证"。

3. 性能问题诊断

/sc:troubleshoot "API response times degraded" --type performance # Performance metrics analysis and bottleneck identification # Provides optimization recommendations and monitoring guidance

未带--fix，因此只做指标分析与瓶颈定位，输出优化建议与监控指引，不擅自改动任何代码。

4. 部署问题解决

/sc:troubleshoot "Service not starting in production" --type deployment --trace # Environment and configuration analysis # Systematic verification of deployment requirements and dependencies

--type deployment引导排查聚焦环境差异与依赖验证，--trace加深对启动日志与配置链的分析。

边界与安全：能做什么，不能做什么

原文档用两节（Boundaries 与 CRITICAL BOUNDARIES）清晰划定了命令的行为边界。

Will（会做）：

• 使用结构化调试方法论执行系统性问题诊断；
• 提供经过验证的解决方案与全面的问题分析；
• 应用带验证环节与详细解决文档的安全修复。

Will Not（不会做）：

• 不做充分分析与用户确认就应用高风险修复；
• 未经明确许可与安全验证就修改生产系统；
• 在未完全理解系统影响的前提下进行架构级变更。

关键边界：诊断优先，修复必须显式授权

/sc:troubleshoot最核心的安全设计是DIAGNOSE FIRST（诊断优先）原则——该命令默认只诊断，不修复：

默认行为（不带--fix标志）：

1. 诊断问题；
2. 定位根因；
3. 给出解决方案选项；
4. 在此停止，将发现呈现给用户——不应用任何修复。

带--fix标志时：

1. 完成诊断后，先向用户确认是否应用修复；
2. 只有在用户明确批准后才应用修复；
3. 修复后用测试验证有效性。

明确禁止（不带--fix标志）：

• 不应用任何代码变更；
• 不修改任何文件；
• 不自动执行修复。

输出物：诊断报告，必须包含四部分：

• 问题描述（Issue description）；
• 根因分析（Root cause analysis）；
• 按优先级排序的解决方案（Proposed solutions, ranked）；
• 每个方案的风险评估（Risk assessment for each solution）。

下一步（Next Step）：用户审阅诊断报告后，二选一继续：

• 重新运行并加上--fix标志以应用推荐修复；
• 使用/sc:improve（参见 src/superclaude/commands/improve.md）进行更大范围的代码改进/重构。

这套"诊断—报告—确认—修复"的闭环设计，在框架的命令输出分类中也得到了印证：/sc:troubleshoot被明确归类为文档型命令（Document-Only Commands）——它默认只产出诊断报告，修复必须依赖--fix标志加用户确认（参见 docs/reference/commands-list.md）。这与/sc:implement、/sc:improve等执行型命令形成鲜明对比。

与其他能力的配合

与 Introspection 模式配合

当排查结果与预期不符，或需要复盘"为什么上次的解决方案没有生效"时，可结合--introspect模式（src/superclaude/modes/MODE_Introspection.md）进行元认知分析。该模式专门用于"错误恢复"与"结果与预期不符"的场景，输出带 🤔 🎯 ⚡ 📊 💡 等透明化标记的推理过程，帮助把一次失败排查转化为可复用的经验。

与 Serena MCP 安装排查配合

若问题出在 SuperClaude 自身的 MCP 环境（例如 Serena 无法启动），可参考 docs/troubleshooting/serena-installation.md 中的专项排查指南。该文档记录了"Failed to spawn: serena"错误的典型场景：安装器曾错误地使用uv run serena而非uvx安装 Serena MCP。解决方案依次为：

1. 移除损坏安装：claude mcp remove serena；
2. 用uvx方式直接安装：uvx --from git+https://github.com/oraios/serena serena --help；
3. 重新注册：claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant；
4. 验证：claude mcp list。

其核心教训是：uv run serena依赖本地项目依赖，而uvx直接运行远程 GitHub 仓库中的工具，后者才是 Serena 的正确安装方式。手动配置时需在~/.claude.json的mcpServers中写入对应命令与参数。

与常见问题快速参考配合

文档 docs/reference/common-issues.md 提供了另一层"快修"视角——它汇总了覆盖约 90% 场景的五个高频问题（命令不生效、安装验证、权限问题、MCP 服务器异常、组件缺失）及对应的一行命令解法，可作为/sc:troubleshoot深度诊断之前的快速检查清单。当快速方案不奏效时，再进入系统性根因分析流程。

总结

/sc:troubleshoot是 SuperClaude Framework 中一个"小而严谨"的基础排查命令：它用--type参数覆盖代码、构建、性能、部署四大问题域，用--trace提供深度追踪能力，用五步行为流保证诊断过程的系统性，而"诊断优先 +--fix显式授权"的边界设计则确保它永远把用户安全与代码库完整性放在第一位。配合框架底层的 troubleshoot 技能协议（反模式约束与根因分析报告格式）以及 Introspection 模式的复盘能力，它构成了一条完整的"发现问题 → 定位根因 → 确认修复 → 验证生效 → 沉淀经验"的闭环链路。

无论你是想排查一次诡异的运行时异常，还是分析构建失败、定位性能瓶颈、解决生产部署问题，都可以从一句简单的/sc:troubleshoot "问题描述" --type 对应类型 --trace开始，让 Claude Code 先给出有证据支撑的诊断报告，再决定是否以--fix授权修复。

• 开发工具
• CLI
• AI 技能/插件
• 测试
• 人工智能
• AI 评测