故障排查

先记录精确的包、DSH、Node、OS 版本和最后成功步骤。公开日志只保留必要片段，移除 token、API key、用户目录和作品正文。

现象	检查与处理
找不到 dsh/pnpm	新开终端，核对 Node/npm 全局安装目录是否在 PATH，再查看 `dsh --version`
启动后没有 Web 页面	确认自定义 profile 来自 `--from-default-profile web`，基础 profile 不自动变成 Web
安装 tgz 报路径被拆开	将文件放到有写权限的无空格目录；仅外层加引号可能不足以解决当前宿主转发限制
missing peer 提示	Cordis/React/DSH 共享模块由宿主提供；核对精确宿主版本。若启动仍报缺模块，不要把提示当通过
页面连接被拒绝	使用当前启动进程给出的完整链接，确认端口和进程仍在；不要复用过期 token
端口已占用	换空闲端口；确认不是重复启动同一 profile
工具或技能出现两份	停止实例，移除旧开发 file patch 和手工技能目录变量，保留正式安装入口再重启
模型认证、额度或限流失败	在宿主设置核对服务、模型与凭据；先发短消息，不反复重跑昂贵章节
向量维度不匹配	核对实际模型输出维度及“发送维度参数”选项，配置改变后重建对应索引
检索回退/场景识别失败	查看可选服务状态；基础检索可能仍可用，回退不等于增强服务成功
编辑保存冲突	重新读取当前文件与版本，核对他处修改，再保存；不要强盖
进度与聊天印象不同	让主控重新查询实际书仓；模型文字不是定稿或提交证据

提交 Bug 时附最小合成复现、精确错误和相关文件名即可。内容损坏先完整备份现场，勿删除事务目录或重写状态文件尝试“清空恢复”。