简要结论
从 Node、端口、网络、模型配置到工作区权限，按最短路径定位问题。
排错的目标不是一次尝试所有方案，而是尽快判断问题位于哪一层。
命令无法运行
先执行：
node --version
npm --version
npx @deepseek-ai/dsh --help如果 Node 不存在或版本过旧，先处理运行时。若 npm 下载失败，再检查公司代理、Registry、证书和网络策略。
Web UI 打不开
确认终端进程仍在运行，并查看日志中实际输出的 URL。默认端口可能被其他进程占用，也可能被安全软件拦截。
不要为了“解决端口问题”直接关闭所有 Node 进程。先定位具体监听进程和项目。
会话编辑区不可用
检查是否已经选择工作区。官方 Web UI 指南指出，新界面在选中工作区前不会启用会话编辑器。
模型请求失败
按顺序检查：
- Provider 与模型 ID。
- API Key 是否有效、是否有额度。
- Base URL 是否正确。
- 网络是否能访问端点。
- 普通对话和工具调用是否都失败。
保留 HTTP 状态码和错误类型，但在分享日志前删除 Key、请求正文中的私人数据与本地绝对路径。
Plugin 安装后无法启动
- 对照 Plugin README 的兼容版本。
- 检查包名和发布者。
- 查看它是否依赖特定 Bundle 或配置行。
- 暂时移除新增 Plugin，确认基础 Profile 能否恢复。
- 不要在没有备份时连续修改多层配置。
无法定位时，整理最小复现、系统版本、Node 版本、dsh 版本和脱敏日志，再到官方 Discussions 或对应 Plugin 仓库反馈。
六层诊断法
按由外到内的顺序，每次只验证一层：
| 层 | 最小探针 | 通过标准 |
|---|---|---|
| 运行时 | node --version、dsh help | 命令退出正常 |
| 启动与端口 | 查看启动日志和监听地址 | Web UI 可访问 |
| Provider | 一句纯文本请求 | 有完整响应 |
| 工作区 | 读取一个已知小文件 | 路径与内容正确 |
| 工具与权限 | 调用只读工具 | 参数、审批、结果一致 |
| Plugin 组合 | 禁用新增项后对照启动 | 能定位到具体增量 |
如果第 3 层未通过，不要调整 Prompt；如果禁用插件后问题仍在，不要继续审查该插件源码。
保存最小复现
一份有效的问题报告至少包含：
- 操作系统、Node、dsh 和相关 Plugin 版本；
- 精确启动命令与所用 Profile；
- 从干净工作区开始的最短复现步骤；
- 预期结果与实际结果；
- 脱敏错误、时间戳和失败层；
- 是否能在禁用第三方 Plugin 后复现。
不要上传完整 Session Log 前就假定它没有秘密。工具结果可能包含文件内容、路径、环境变量或外部服务返回的数据。
停止条件
连续改动两层配置却没有新的诊断证据时，停止试错，恢复最后一个已知可用状态。重新从最小探针开始，通常比继续叠加“可能有用”的设置更快。