DeepSeek Harness 常见问题与报错排查

DSHOPC 建议先把故障分成八层，排错原则只有一句：先找最后一个正常层，再检查下一个异常层。

1. Node.js / 本机环境
2. DSH 启动 / Web 服务
3. 模型 / 凭据
4. 工作区 / 会话 / Agent 预设 / 权限
5. profile / 配置 / 插件
6. skill（技能）
7. MCP
8. 最后恢复手段

举一个例子：Web UI 能打开、普通模型聊天正常、工作区正常、只有文件读取失败——这时不应该先重装 DSH。因为前面几层已经证明安装、Web 服务、模型链路基本正常，此时应该优先检查的是工作区、Agent 预设、权限和工具调用。

示意图点击放大

如果 DSH 连启动阶段都没到，先从本机环境查起。

症状：node 找不到

终端提示 command not found: node，Windows 下则是 'node' 不是内部或外部命令。先运行 node -v：当前 DSH 0.1.1-rc.2 对 Node.js 的要求是 ^22.19.0 || >=24.0.0。如果 Node 未安装、版本过低，或 PATH（系统查找可执行程序的环境变量）指向旧版本，都要先解决 Node 环境。

怎么确认修好了？

详细安装流程见《DeepSeek Harness 安装与启动教程》（/deepseek-harness/install/）。

症状：npx 可以用，但 dsh plugin 报 pnpm 不存在

插件管理和普通启动不是同一路径：dsh plugin --profile <name> ... 会把后面的参数转发给 pnpm。所以先运行 pnpm -v。如果找不到 pnpm，这是插件管理环境的问题，不是插件本身已经坏了。

怎么确认修好了？

详细见《DeepSeek Harness 插件教程》（/deepseek-harness/plugins/）。

症状：终端里明明装了 Node，换一个终端却找不到

这通常属于 PATH / Shell 环境不一致。先确认 which node，Windows PowerShell 可以用 Get-Command node。如果不同终端解析到了不同位置，先统一 Node 环境，再排 DSH。

如果 Node 环境没问题，下一层看 DSH 进程和 Web 服务。

症状：执行启动命令后进程立刻退出

$ npx @deepseek-ai/dsh web

不要只看浏览器，先看终端有没有明确错误。常见故障范围包括：

• profile 配置错误
• 插件模块解析失败
• 配置 schema 错误
• 端口问题
• 新 Bundle 启动失败

症状：终端进程还在，但浏览器没有自动打开

这不等于 DSH 启动失败。当前默认 Web UI 地址是 http://127.0.0.1:3080，可以手动在浏览器打开。如果你使用了 npx @deepseek-ai/dsh web --no-open，本来就不会自动打开浏览器；SSH 环境下 DSH 也可能主动跳过本机浏览器交接。

怎么确认修好了？

症状：3080 端口被占用

可以先换端口验证：

$ npx @deepseek-ai/dsh web --port 3081

然后打开 http://127.0.0.1:3081。如果换端口后正常，说明故障更可能在原端口占用，而不是整个 DSH 安装。

怎么确认修好了？

症状：看到 EACCES、权限相关端口错误

先做最小检查：换一个普通高位端口，例如 npx @deepseek-ai/dsh web --port 3081。如果恢复正常，就把故障限制在监听端口 / 系统权限层。

症状：想用 --host 0.0.0.0 但启动失败

当前 CLI 有意不支持 --host 0.0.0.0，所以这不是「你的系统网络坏了」，而是当前产品行为。远程访问属于部署 / 网络架构问题，不要把改 host 当作普通的本地启动排错步骤，应当单独设计。

如果 Web UI 已经正常打开，但发消息失败，进入模型层。

症状：MISSING_CREDENTIAL

• 当前选的是哪个提供方
• API 密钥是否已经保存
• 该提供方是否依赖环境变量
• 环境变量是否真的存在

怎么确认修好了？

详细见《DeepSeek Harness 模型配置教程》（/deepseek-harness/models/）。

症状：UNKNOWN_MODEL

第一检查点：当前选中的模型 ID 是否还存在于当前提供方配置。尤其是删除过提供方、改过模型 ID、更新过自定义模型目录以后，容易出现这类问题。

怎么确认修好了？

症状：获取模型列表返回 401

优先检查 API 密钥、API 地址，以及当前服务是否允许这个凭据访问模型列表。但要注意：有些兼容服务本身就不提供 GET /models，所以获取不到列表不等于一定不能调用模型。如果服务文档明确给出了模型 ID，可以手动添加再验证请求。

症状：普通聊天成功，但智能体工具调用失败

这是非常重要的分层点：普通聊天成功，不代表工具调用一定兼容。自定义 OpenAI 兼容端点可能在 developer 角色、token 字段、工具协议或其他请求字段上存在差异。不要因为「模型回答你好没问题」，就直接判断 DSH 智能体已经完全兼容。

怎么确认修好了？

症状：刚改模型配置，但旧会话表现没变化

模型设置要区分「新请求 / 新会话」和「已经有历史的会话」：已有会话可能保留自身日志里的模型信息。排错时，新建一个干净会话更容易确认当前配置。

如果 Web UI 正常、模型能回答，但智能体做不了真实任务，重点看这一层。

症状：输入框不能正常开始任务

先检查有没有选择工作区。当前全新 Web UI 在没有选中工作区时，不能正常开始普通会话任务。选择一个明确的测试工作区即可，不要第一反应改模型。

症状：智能体说「找不到文件」

先确认三件事：

1. 当前 Web UI 选中的工作区
2. 文件是否真的在该工作区
3. 文件名 / 路径是否正确

你可以在终端独立确认文件是否存在：

$ node -e "console.log(require('fs').existsSync('目标文件'))"

如果输出 false，那问题先在路径 / 工作区，而不是智能体的推理能力。

症状：模型回答了，但没有任何工具调用

检查当前 Agent 预设是否拥有对应工具。例如极简模式，当前就没有标准模式那套完整的技能、网页检索、计划、子代理等能力。第一次排错建议使用标准模式，减少变量。详细见《DeepSeek Harness Agent 预设怎么选？》（/deepseek-harness/agent-modes/）。

症状：会话开始后找不到切换 Agent 预设的入口

这是当前的生命周期设计：Agent 预设在会话开始时固定，设置页修改的是后续新建会话的默认预设。如果当前任务确实需要换预设，就新建会话，不要把它当成 UI Bug。

症状：设置页改了权限，但当前会话没变化

设置中的权限主要控制后续新建会话的默认权限；当前会话的权限仍然可以单独调整。记住二者区别：Agent 预设开始后固定，权限在当前会话内仍可调整，不要混淆。

症状：一直卡在「等待审批」

先检查审批内容：智能体到底请求什么操作。如果操作合理且属于当前任务，再判断是否允许；如果明显无关，不要为了让流程继续而盲目批准。

症状：开启 Full access 后问题「好了」

这并不能直接说明原来是 DSH Bug，更可能说明原任务受到了权限 / 审批边界的限制。正确做法是找到具体是哪一项操作被拦住，而不是长期用 Full access 掩盖权限设计问题。

怎么确认这一层修好了？

如果问题发生在安装 / 更新 / 删除某个插件或修改 profile 配置之后，优先看这一层。

症状：插件命令执行成功，但能力没出现

先运行：

$ npx @deepseek-ai/dsh --profile web --dump-config

检查对应 Bundle 层有没有进入 profile。依赖安装成功，不等于已经成为 DSH 配置层：如果包里没有 dsh.bundle 字段，它可能只是普通依赖。

症状：dump-config 能看到插件，但当前 Web UI 还是旧能力

如果你刚刚安装、更新或删除过 Bundle，记住：正在运行的 profile 不会热切换 Bundle 集合。需要：

1. 停止当前 DSH
2. 重新启动对应 profile
3. 再验证能力

症状：刚装插件，重启以后 DSH 起不来

这时不要同时改十个东西。先记录插件包名、版本 / Commit、DSH 版本和错误日志，然后运行 npx @deepseek-ai/dsh --profile web --dump-config 检查新增的层。如果问题明显从这个插件变化开始，优先回退最后一个变化。

最小回退

$ npx @deepseek-ai/dsh plugin --profile web remove <package>

$ npx @deepseek-ai/dsh --profile web --dump-config

确认对应层消失后，再用 npx @deepseek-ai/dsh web 启动。如果基线恢复，问题与该变化高度相关。

症状：GitHub 插件安装卡在 prepare / allowBuilds

这通常是 pnpm ≥10 阻止了 Git 依赖安装阶段的构建脚本。

症状：改 cordis.patch.yml 后行为异常

先不要继续叠更多 patch，运行 npx @deepseek-ai/dsh --profile web --dump-config 理解最终组合。当前 patch 的一个关键边界是：对目标行的 config 是整体替换，不是只深度合并你写的某一个键。所以如果你只重写了这样的片段：

config:
  someField: value

就可能把原来那一行里其他必需配置一起替掉。这是 profile / patch 层的问题。

如果问题只发生在技能上，不需要先重装插件。

症状：新建技能后完全识别不到

先检查路径。项目级优先位置是 <projectRoot>/.dsh/skills，例如 .dsh/skills/seo-audit/SKILL.md。确认：

• SKILL.md 直接在 skill 根下一层
• 没有套很多级目录
• name 是 kebab-case（小写短横线命名）
• frontmatter 格式正确

当前不支持任意 **/SKILL.md 深度递归发现。

症状：项目级技能没有覆盖用户级同名技能

当前本地 rank（来源优先级数值，低者优先）如下：

如果实际没有按预期生效，检查当前项目根：它通常取最近的 .git 祖先目录，没有 .git 时才回退到当前 cwd（工作目录）。

症状：/name 显式调用失败

检查三件事：skill 是否被发现；名称是否完全一致；是否设置了 user-invocable: false：

user-invocable: false

如果用户入口被关闭，/name 本来就不会调用。

症状：显式 /name 成功，但自然语言不自动调用

这不等于 skill 无效，反而说明技能本身的发现与加载链路可能正常。此时优先优化 name、description，以及任务描述与技能范围的匹配度。当前模型目录主要看到 name + description，所以不要把关键路由信息只写在正文里。

症状：模型从来不看到这个技能

检查 frontmatter 是否开启了 disable-model-invocation: true——开启后这个 skill 不会进入模型可调用目录。另外还要检查当前 Agent 预设是否包含 skill 工具：极简模式就不是标准模式那套完整技能组合。

怎么确认技能修好了？

MCP（Model Context Protocol，模型上下文协议）的错误最容易被一句「MCP 连不上」混在一起。实际上至少有五层：

配置
→ 连接
→ 工具发现
→ 工具调用
→ 外部真实结果

症状：加了 MCP 配置，但完全没看到工具

第一步：

$ npx @deepseek-ai/dsh --profile web --patch ./mcp-test.patch.yml --dump-config

确认四件事：MCP Client 插件行存在；serverName 正确；Transport（传输方式）正确；command / url 正确。如果配置根本没进入组合，先别急着查 Server。

症状：Web UI 正常打开，但 MCP 工具不存在

注意当前默认 failOnStartupError: false，所以 MCP 初始连接失败时不一定让整个 DSH 启动失败。也就是说，Web UI 能打开不等于 MCP 成功，要继续看启动日志和 Tools 发现情况。

症状：stdio MCP 启动失败

检查 command 本身能不能在终端执行。比如配置了 command: node，就先确认 node -v；配置了 command: npx，就先确认 npx 和目标包可用。

症状：HTTP MCP 连接失败

逐项检查：

• URL
• 网络
• Header
• Token
• Server 是否真的在线
• Server 是否支持当前 MCP Transport

不要先把问题归到 DSH 模型层。

症状：MCP 工具出现了，但调用超时

当前默认 toolCallTimeoutMs = 60000，也就是 60 秒。先确认：Server 有没有收到请求；外部 API 有没有响应；工具本身是不是卡住。

症状：MCP Server 崩了以后没恢复

当前 MCP Client 默认会自动重连，但重连有失败预算，不是永久保证。连续失败达到上限后，工具会被注销并停止继续恢复。先修复 Server，再重新加载或重启，并确认工具重新出现。完整参数和生命周期见《DeepSeek Harness MCP 教程：连接外部工具》（/deepseek-harness/mcp/）。

症状：改了 serverName 后原工具名全变了

这是预期行为。公开工具名来自 mcp__<serverName>__<rawName>，所以改 serverName 就会改变智能体看到的工具命名空间。如果只是调整连接参数，尽量保持 serverName 稳定。

症状：MCP Server 支持 Resources / Prompts，但 DSH 里看不到

怎么确认 MCP 修好了？

到这里才考虑更重的恢复手段。顺序仍然是：备份 → 最小回退 → 重建基线，而不是直接清空所有状态。

先记录当前环境

至少记录以下字段：

• DSH 版本
• Node.js
• 系统
• 启动命令
• profile
• Agent 预设
• 模型
• 最后一次正常时间
• 最后一个改动
• 完整错误

如果问题与插件 / MCP 有关，再加三项：插件版本 / Commit、MCP Server 版本、Transport。这些信息决定后面能不能复现。

先确认「最小基线」还能不能跑

建立一个新的空测试目录，运行：

$ npx @deepseek-ai/dsh web

不要先加自定义 patch、新 MCP、新插件或复杂工作区。然后按这条链路验证：

Web UI
→ 官方模型
→ 标准模式
→ 测试工作区
→ 随机文件读取

如果这个最小基线能跑，原问题大概率属于附加配置 / 项目 / 插件 / MCP 层；如果最小基线也失败，再回到安装、模型和 profile 基础层。

手工修改配置前先备份

删除整个 ~/.dsh 应该是最后手段

如果最终确实要重建 Harness home，按这个顺序：

1. 先完整备份
2. 记录版本和错误
3. 明确这是最后恢复实验
4. 重建后只恢复一项配置
5. 每恢复一项就测试一次

不要用 Full access 作为最后恢复方案

Full access 是权限模式，不是修复损坏配置、模型协议、MCP Server 或插件兼容性的工具。如果开 Full access 后某一步能执行了，只能说明权限边界发生变化。它不能修复这些问题：UNKNOWN_MODEL、Bundle 启动错误、技能路径错误、MCP Server 离线、Node 版本错误。

什么时候应该进入 Lab，而不是继续猜？

如果你已经做到：记录环境、能稳定复现、换回基线正常、加上某个插件 / MCP / 配置就必现——这就已经不是简单的 Learn 排错了，应该进入 Lab 做完整验证：

基线
→ 加一个变量
→ 复现
→ 回退
→ 再复现

最终才能判断：当前版本兼容或不兼容、某操作系统特有、某配置冲突、第三方项目问题，或者 DSH 本身可能存在 Bug。

示意图点击放大

不要用「现在好像没报错了」作为结束标准。至少要做到：

1. 知道故障属于哪一层
2. 知道你改了什么
3. 能说明为什么这个修改与故障有关
4. 使用明确测试确认恢复
5. 没有为了恢复破坏无关配置

例如一条合格的排错记录长这样：

症状：
MCP 工具不出现

定位：
HTTP MCP Token 环境变量未传入

修改：
正确设置 MCP_TOKEN

验证：
工具重新发现
+ mcp__example__get_status 出现
+ 真实工具调用返回可核对结果

这才是一条可复现、可验证的排错记录。

如果已经定位到具体层，就不要一直停留在这篇总入口，直接进入对应教程：

以下属于 DSHOPC 的分析建议，供参考：

• 按故障层级排查，而不是一次修改多个变量
• 用「最后一个正常层」缩小范围
• 每次修复都要求明确的 Verification（验证）
• 插件和 MCP 采用分层验证
• 自动路由失败与 skill 本身失效分开判断
• Full access 不作为万能修复
• 删除整个 Harness home 只作为备份后的最后恢复手段