故障排查
安装依赖、凭据与配置兼容性、模型网络、端口、工作区、权限审批与构建错误的排查指南
按「症状 → 原因 → 修复」排查 DeepSeek Harness 的常见问题。每节先给现象，再给最可能的原因与可操作的处理。若本节未覆盖，请到社区反馈。
开始之前：三项快速检查
遇到问题时，先按顺序确认这三点，能排除大部分情况：
- Node 版本：
node --version应满足^22.19或>=24。 - 密钥有效：确认模型 API 密钥可用，且网络能访问 API 端点。
- 网络可用：首次启动与模型调用都需要网络。
安装与依赖
| 症状 | 原因 | 修复 |
|---|---|---|
pnpm install 失败、报依赖缺失或校验错误 | pnpm store 缓存损坏或陈旧 | 运行 pnpm store prune 清理陈旧缓存后重新 pnpm install；必要时删除 node_modules 再重装 |
| 依赖下载缓慢或超时 | 网络或 npm 源不可达 | 检查网络，必要时换用可达的 npm 源后重试 |
| 安装报错指向 pnpm 自身 | pnpm 版本过旧 | 升级 pnpm 到较新版本后重试 |
安装插件时被拒绝，提示 prepare 脚本未运行 | pnpm ≥10 在得到显式允许前拒绝运行 git 依赖的 prepare 脚本 | 把 pnpm 打印的确切包键复制进该 profile 的 pnpm-workspace.yaml（onlyBuiltDependencies）；详见插件 |
| 构建产物缺失或命令找不到 | Node 版本不符 | 确认 node --version 满足 ^22.19 或 >=24，详见安装与启动 |
提示「npx/node 不是内部或外部命令」 | Node 未安装，或安装后没有重开终端 | 重新安装 Node.js 并重开终端；Windows 注意安装器是否勾选了加入 PATH，详见安装与启动 |
首次 npx 卡住 | 正在下载依赖，或网络不通 | 确认网络可用，等待首次下载完成 |
凭据文件与版本切换
plugin tree failed to load，并提示 the value for "version" ... must be a string
这不是 Node.js 24 本身的错误。该报错发生在 Web 服务启动前：正在运行的旧版 credentials-local 把 .credentials.yaml 顶层的 version: 1 当作普通凭据，并要求所有顶层值都是字符串。换言之，实际运行的 DSH 与这个凭据文件来自不兼容的预发布格式。
不要仅根据键入的是 npx 还是 dsh 判断版本。报错堆栈中 .../node_modules/@deepseek-ai/dsh/... 的路径才是实际加载的安装位置；在同一个 Node 环境中执行以下检查：
npm list -g @deepseek-ai/dsh --depth=0
npm view @deepseek-ai/dsh version不要把 version: 1 改成 version: "1" 作为长期修复
旧版扁平格式读取器只会把带引号的 version 当成一个名为 version 的普通凭据；若文档还有 refs: 等 mapping，下一项仍会报类型错误。这既不是向当前格式的迁移，也不能解决混用版本的问题。
推荐处理：备份后统一到一个发布版本
先停止所有 DSH 进程，并完整备份 harness home（默认是 ~/.dsh）。备份包含会话、设置与 profile，后续只会移走凭据文件，不会删除这些数据。
cp -a ~/.dsh ~/.dsh.bak-$(date +%Y%m%d-%H%M%S)
npm uninstall -g @deepseek-ai/dsh
npm install -g @deepseek-ai/[email protected]
npm list -g @deepseek-ai/dsh --depth=0
dsh web0.1.1-rc.2 的 .credentials.yaml 是版本化文档；API 密钥最小形状如下，version 必须是数值而不是字符串：
version: 1
refs:
DEEPSEEK_API_KEY: sk-…
OPENAI_API_KEY: sk-…当前发布版会在启动时识别并迁移严格的旧版扁平凭据 mapping。不要在升级后手动删除 version 或把 refs 展平；OAuth 等非普通 API key 的凭据还可能使用额外的 records 区段。格式的权威说明见上游 dsh-credentials-local 文档。
升级后仍无法启动，且可以重新填写密钥
将旧凭据文件改名而不是删除，然后启动 Web UI 并在设置 → 模型重新保存密钥：
mv ~/.dsh/.credentials.yaml ~/.dsh/.credentials.yaml.before-$(date +%Y%m%d-%H%M%S)
chmod 700 ~/.dsh
dsh web这只会让新版本以空凭据存储启动；.credentials.yaml.before-… 仍保留原始数据，sessions、settings、profiles 和其他 ~/.dsh 内容不受影响。新文件创建后，如报权限错误，再执行：
chmod 600 ~/.dsh/.credentials.yaml不要用 cat、截图或工单粘贴该文件内容，也不要把 API key 提交到仓库。
同类启动与配置错误速查
这一组错误通常发生在 Web 服务尚未监听端口之前。先看报错中给出的实际文件路径、profile 名和插件名，只处理被点名的文件；不要因为一个配置文件损坏而删除整个 ~/.dsh。
| 报错片段 | 常见原因 | 安全处理 |
|---|---|---|
credentials-local: ... readable beyond its owner (mode 644) | 凭据文件对同组用户或其他用户可读 | 确认路径无误后执行 chmod 600 ~/.dsh/.credentials.yaml；目录也应为 chmod 700 ~/.dsh。 |
credentials-local: invalid document、must be a mapping、is empty; remove the key instead | YAML 语法错误、顶层不是 mapping、空值或手工编辑留下的重复键 | 先备份整个 harness home；不要把文件内容发给任何人。可以只改名 .credentials.yaml，让 Web UI 重新写入密钥，保留原文件以便回滚。 |
settings-file: invalid document 或 must be a map of namespace sections | settings.yaml / 自定义 settings 文件的 YAML、JSON 损坏，或根节点写成了数组/标量 | 备份报错中给出的 settings 文件，再只改名该文件并启动 dsh web；需要的模型、提供方和界面设置随后在 UI 重新保存。不要改动 .credentials.yaml。 |
failed to parse overlay、must be a top-level YAML array、overlay entry ... must be a mapping | cordis.patch.yml 的 YAML 形状不符合 Loader patch 格式 | 用下方的 dump 命令定位是 profile 级还是 home 级 patch；备份并暂时改名报错中点名的那一个 patch 文件后重试。 |
failed to apply loader entry ... | 某个插件的配置、依赖或启动过程失败 | 从完整堆栈最后一个 cause 找到具体插件；先验证默认组合，再检查该 profile 的插件依赖与 patch。 |
profile "<name>" does not exist | 非内置 profile 尚未创建；只有 web 和 headless 会首次自动初始化 | 按错误提示使用 dsh plugin --profile <name> add <package> 创建所需 profile；不要手工复制另一个 profile 的整个目录。 |
Cannot find package ...、ERR_MODULE_NOT_FOUND | profile 插件依赖未装完整、插件升级后依赖不匹配，或从源码运行但产物尚未构建 | 已安装 CLI：执行 dsh plugin --profile <name> install 后重试；源码仓库：在仓库根执行 pnpm run build，再用 pnpm dsh ... 启动。 |
用配置 dump 区分默认组合与自定义 patch
对 cordis.patch.yml、failed to apply loader entry 或模块解析类错误，先在同一套 DSH 安装中运行：
dsh --profile web --dump-default-config
dsh --profile web --dump-config第一条只检查随安装提供的组合包；第二条还会读取 profile 的 cordis.patch.yml、~/.dsh/cordis.patch.yml 以及命令行 overlay。
- 只有第二条失败：优先检查报错点名的用户 patch；先备份并暂时移开该单一文件，再逐项恢复改动。
- 两条都失败：问题更可能在当前 DSH 安装、内置组合包或该 profile 的依赖；先确认运行版本和
dsh plugin --profile web install的结果。 - 两条都通过但
dsh web失败：读取完整的最内层cause，它通常会指出某个插件配置、端口或凭据文件；再回到本页对应条目处理。
预发布版本的统一原则
DSH 仍处于开发者预览阶段。一次只让一个 CLI 版本管理同一个 $DSH_HOME，并在更新前备份。升级、降级或在不同 Node / nvm 版本之间切换后，先用报错堆栈中的实际加载路径核验版本，再决定迁移、恢复旧文件还是重新填写凭据。
模型与网络
| 症状 | 原因 | 修复 |
|---|---|---|
| 模型不响应或超时 | 密钥无效、网络无法访问 API 端点、Base URL 填错 | 检查密钥是否有效、网络能否访问端点、Base URL 是否正确，见配置模型 |
| 请求被代理拦截或超时 | 代理环境变量配置有误 | 检查 HTTP_PROXY / HTTPS_PROXY，确认代理不拦截模型端点 |
提示 MISSING_CREDENTIAL | 缺少提供方凭据 | 通过模型页保存密钥，或提供被引用的环境变量 |
提示 UNKNOWN_MODEL | 请求的模型未配置 | 选择已配置的模型，或向自定义提供方添加缺失模型 |
| 「获取可用模型」返回 401 | 密钥错误或服务不提供 GET /models | 检查密钥；对不提供该端点的服务手动输入模型 |
| 新会话仍使用旧模型 | 已发送过请求的会话会保留日志中记录的模型 | 在模型选择器切换；该选择只会成为新会话的默认值 |
| 输入框显示「选择模型」并阻止输入 | 已保存的默认值指向已删除的提供方 | 重新选择一个模型 |
| 图片在发送前被拒绝 | 模型未声明图片模态 | 给自定义提供方的模型加 input: [text, image]；DeepSeek 自身的 chat-completions 路由为纯文本，无法通过配置改变 |
| 提供方拒绝了带图片的请求 | 模型声明了端点实际不支持的图片能力 | 从授予图片能力的列表中移除 image（模型的 input 或路由的 defaultInput），然后开启新会话 |
端口冲突
| 症状 | 原因 | 修复 |
|---|---|---|
启动即失败，报告 EADDRINUSE | 默认端口 3080 已被占用 | 换端口：dsh --profile web --port 8080（--port 属于 web 应用）；或先释放占用进程 |
| 不清楚实际监听的端口 | 端口配置为 0 时由操作系统分配 | 以命令打印的地址为准 |
工作区
| 症状 | 原因 | 修复 |
|---|---|---|
| 会话输入框不可用 | 尚未选中工作区 | 点击选择工作区，添加并选中启动 dsh 时所在的目录 |
| 读写文件被拒绝 | 操作超出当前沙箱授权的工作区范围 | 把目标文件放进工作区，或调整权限预设；不要追求过宽的访问范围 |
| 找不到预期的文件 | 工作区指向了错误的目录 | 重新选择正确的项目目录作为工作区 |
权限与审批
| 症状 | 原因 | 修复 |
|---|---|---|
| 操作反复要求审批 | 当前权限预设要求对敏感操作逐一确认 | 检查权限预设；日常使用保留带询问的档位（如 workspace-write） |
| 操作被沙箱拒绝、无法升权 | 主体不得获得超出既有授权的权限（非升权） | 在权限预设允许的范围内重试；确需更宽权限时，由你切换预设或明确批准该次调用 |
受限沙箱报 SANDBOX_UNAVAILABLE | 当前环境未提供所需的沙箱后端 | 改用当前环境可用的沙箱模式或预设 |
构建错误
| 症状 | 原因 | 修复 |
|---|---|---|
pnpm run build 失败 | Node 版本不符、依赖未完整安装、或仓库未同步 | 确认 Node ^22.19 或 >=24，重新 pnpm install 后重试 pnpm run build |
| 从源码启动报模块解析错误 | 未先执行 pnpm run build | 先完成构建再运行 pnpm dsh <args...>，见安装与启动 |
还不行？
以上都没有命中时，带上复现步骤、Node 版本与报错信息，到社区反馈。