TROUBLESHOOTING
故障排查
保留证据，定位最窄失败层，并用原失败动作证明恢复。
先说结论
排障先看问题属于哪一层：桌面、Provider、LSP、SQLite，还是仓库门禁。动手修之前，先保存原始错误、命令退出码和最小复现。删除数据或连续重试很容易把证据一起抹掉。
怎么理解
| 现象 | 首查位置 | 证明恢复的动作 |
|---|---|---|
| 桌面提示重新连接 | bootstrap 错误、host 进程与事件订阅 | 明确重试成功，Composer 恢复可用 |
| 无法发送 | 项目选择、能力目录、审批、active Turn | thread/start/turn/start 或 steer 成功并收到事件 |
| Provider 断线 | session identity、transport、generation 与 retry budget | resume 后可继续同一 public Thread |
| LSP 无诊断 | runtime env、roots、语言服务 readiness | 实际 file(action=diagnostics) 成功 |
| 数据状态异常 | SUPER_DOLPHIN_HOME、SQLite 路径与迁移 | 使用预期数据库启动并通过 schema 检查 |
| guard/build 失败 | 失败规则、变更文件与生成物 drift | 对应聚焦检查和 change-aware gate 通过 |
怎么使用
- 记录操作系统/架构、产品 commit、Go/Node/Provider CLI/语言服务器版本。
- 记录精确复现步骤、预期和实际行为、命令与 exit status。
- 只保留最小、脱敏日志；删除 token、用户数据、本地数据库内容、Provider home 和机器路径。
- 从最窄所有权层验证：配置 → 进程 → RPC/Provider → Thread/Turn → UI projection；跨层请求可在可观测性与链路追踪中按 Trace ID 关联。
- 恢复后重复原失败动作，而不是只确认进程重新出现。
常见问题
桌面与 Thread
Bootstrap 失败时使用显式“重新连接后端”；应用不会无限自动重试。第一条消息失败时分别检查 Thread 是否创建、Turn 是否启动、事件是否到达。存在 active Turn 时先中断或等待，不重复提交。
Provider 与审批
身份字段不完整时不要删除 Provider home 或换默认账号；先核对 Thread binding。审批卡住时确认 request identity 与当前 Thread，绝不自动批准。恢复连续失败意味着 retry budget 已耗尽，应保留错误并人工处理。
LSP 与路径
遇到 path_outside_workspace 时统一 command/cwd/resources/roots 的路径体系；显式 WSL 桥接例外是 host cwd 使用 Windows 路径，而传入 sidecar 的 resources/roots 使用映射到同目录的 Linux 路径。
Windows 原生出现 bundle、manifest、digest 或 gopls.exe 错误时，检查 SUPER_DOLPHIN_LSP_BUNDLE_DIR 与 SUPER_DOLPHIN_LSP_MANIFEST 是否指向完整发行包。校验失败必须 fail-fast，不能临时改用 PATH 中的 gopls。
Windows Host → WSL2 启动后若工具清单只暴露 file/grep，说明 MCP 进程存在但语义语言服务器没有就绪。进入目标发行版运行 command -v go gopls node typescript-language-server，把实际 Linux PATH 显式传给 wsl.exe --cd ... env ... 启动的非登录 WSL 进程，再依次调用 structure、inspect、xref 和 file(action=diagnostics)。客户端显示 enabled 不是 PASS。
Go 工具链不足时检查 GOTOOLCHAIN；local 模式下 fail-fast 是预期。
SQLite 与门禁
不要在未知 schema 状态下手工修改数据库。生成物 drift 使用对应生成器修复；架构 guard 失败应修改依赖或更新经过评审的规范真源，不能移除测试。
适用范围
- 上游 Provider outage、账号、计费、系统策略和第三方语言服务器缺陷不由项目维护者控制。
- 未回复的支持请求不代表功能受支持或修复已经排期。
- 安全漏洞不得进入公开 issue；请遵循项目安全策略并等待私密渠道。
- 当前所选公开仓库地址尚未开放匿名访问，公共 issue 与私密报告入口可能还不可用。
延伸阅读
需要提交问题时阅读项目与社区，按渠道和最小证据要求准备报告。