主流 Agent 入门教程 / DeepSeek Harness

17. 常见问题排查

本篇目录 · 26 节

来源：DeepSeek Harness

本文属于《DeepSeek Harness 入门教程（实战版）》· 第五部分 · 排错与进阶

第 17 章　常见问题排查：先定位哪一层坏了

排查 Agent 产品最容易犯的错，是看到“任务失败”就立刻重装、换模型或放宽权限。DeepSeek Harness 同时包含界面、Host、Profile、模型 Provider、Agent 预设、工具、审批和项目代码；不同层的故障，表面上都可能只是“它没完成”。

这一章不做一张越来越长的报错对照表，而是建立一条固定路径：

保留现场 → 确认失败层 → 做最小只读检查 → 只修一处 → 独立复验

你会得到一份可以直接套用的排查模板，并能处理本教程主线最常见的阻塞：Desktop/CLI 启动、模型路线、权限审批、插件与 Profile、Skill/MCP、Goal/子智能体、Schedule/Headless，以及日报助手自身。

17.1 出错后先别做三件事

先不要：

连续点击重试，制造多个相同任务、审批或定时任务；
直接升级、重装或删除 Profile，把原始证据和可回退状态一起抹掉；
把 API Key、完整配置 dump、崩溃日志或会话导出原样贴到公开渠道。

先记录以下信息：

使用 Desktop 还是 CLI/Web，操作系统与 CPU 架构；
DSH 的完整版本号，包括 alpha、beta 或 rc 后缀；
当前 Profile、Agent 预设、权限模式和工作区；
最后一项成功操作，以及第一项失败操作；
原始错误码、退出码、失败工具名和发生时间；
是否能在“新任务 + Read Only + 最小提示词”中复现。

“界面卡住了”信息太少；“v0.1.7-rc.2 Desktop，标准模式、Read Only，新任务读取 PROJECT.md 时工具卡片返回某错误”才是可定位的问题。

17.2 用五层模型快速分流

从最外层往里查，每次只问一个问题：

层	最小检查	能排除什么
应用/Host	能否启动、打开设置、创建空任务	安装、端口、Host 与界面故障
模型路线	新建 Read Only 任务，只让模型回复固定文字	账号/API Provider、凭证、模型 ID
Agent/工具	查看执行轨迹与插件列表	预设、工具注册、审批、插件加载
工作区/权限	读取一个已知文件，再尝试受控写入	目录选错、沙箱、审批策略
项目	绕过 DSH，直接运行 `npm run check` 与 `npm test`	项目自身代码、配置与网络问题

最外层失败时，不要让内层背锅。例如 Desktop 根本没启动，就没有必要先改模型 Key；npm test 在系统终端已经失败，也不能先责怪 Agent 预设。

17.3 做一次五分钟健康检查

在没有故障时先知道“正常是什么样”，以后更容易比较。

第一步：记录版本

CLI/Web 路线在系统终端运行：

node --version
npm --version
npx @deepseek-ai/dsh@0.1.7-rc.2 --version

Windows PowerShell 找不到 npx 时使用 npx.cmd。Desktop 路线从应用菜单的“关于”或更新界面记录完整版本，不要拿系统里的全局 CLI 版本代替 Desktop 内置运行时版本。

第二步：验证最小模型请求

在 daily-report 工作区新建标准模式、Read Only任务，发送：

只回复 MODEL_OK，不调用工具，不解释。

看到 MODEL_OK 只证明当前任务的模型路线可用，不证明文件工具或项目正常。

第三步：验证只读工具

再新建一个 Read Only 任务，发送：

只读取当前工作区的 PROJECT.md，并报告第一行标题。
不要运行 Shell，不要访问网络，不要修改文件。

核对执行轨迹中确实发生了文件读取，回答也与文件一致。最后绕过 DSH，在系统终端进入 daily-report 并运行：

npm run check
npm test

四项结果——版本、模型、只读工具、项目检查——构成你的健康基线。某次故障只破坏其中一项时，排查范围会立刻缩小。

17.4 Desktop 启动失败、白屏或反复恢复

先读原生错误弹窗，不要只记住“打不开”。当前 Desktop 在首次致命错误前会尝试写入 crash-<UTC 时间>-<source>.log；弹窗成功写入时会显示准确路径。macOS 的默认日志目录是 ~/Library/Logs/DeepSeek Harness，Windows 位于该应用 userData 目录下的 logs。Desktop 官方说明

按以下顺序处理：

记录弹窗中的 source、应用版本、运行时版本和首个错误；
若错误含 EADDRINUSE，先完全退出其他 DSH 实例，再重启，不要先重装；
若刚安装或启用第三方插件后才失败，使用原生恢复操作“停用第三方 bundle、备份 Profile patch 并重启”；
只有应用能正常进入后，再使用菜单中的“检查更新”；不要用下载页上不明版本覆盖当前安装。

原生恢复会保留已安装包，把 Desktop Profile 的 cordis.patch.yml 重命名为带时间戳的备份，并创建空 patch；Home 级 patch 不会随之重置。因此恢复后能启动，只能说明问题位于第三方 bundle 或 Desktop Profile patch，不能证明 Home 级配置一定正确。

崩溃报告可能包含本机路径、Session ID、提示词、工具输出或第三方插件消息。分享前先复制一份并脱敏，不要直接编辑唯一原件。

17.5 CLI/Web 启动失败或浏览器打不开

先把“找不到命令”和“应用启动失败”分开。

`dsh` 找不到，但 `npx` 可用

这通常只是全局 PATH 问题。入门阶段直接验证：

npx @deepseek-ai/dsh@0.1.7-rc.2 --version
npx @deepseek-ai/dsh@0.1.7-rc.2 --help

两条命令成功，就没有必要立刻修改全局 npm 前缀或使用管理员权限。后续继续用 npx @deepseek-ai/dsh@0.1.7-rc.2 ... 即可。

Web 报端口占用

保留原始错误，换一个明确的本地端口验证：

npx @deepseek-ai/dsh@0.1.7-rc.2 web --port 3100 --no-open

终端打印就绪地址后，手动打开 http://127.0.0.1:3100。如果新端口成功，故障在旧端口占用，不在模型或项目。不要为了远程访问把 Host 随意暴露到公网地址；远程场景回第 5 章使用 SSH 隧道。

Profile 组合失败

先在不启动应用的情况下检查有效配置：

npx @deepseek-ai/dsh@0.1.7-rc.2 --profile web --dump-config

--dump-config 失败时，错误通常已经指向 YAML、schema、模块解析或插件加载层。它成功也只证明配置可以组合，不保证运行时端口、网络和服务激活都成功。CLI 行为参考

如果需要把输出保存到文件，先假设里面含有本机路径、Provider 配置和凭证引用；不要把完整 dump 当成普通截图公开。

17.6 模型不回答：先区分账号路线与 API 路线

Desktop 登录账号模型与 API Key Provider 是两条独立入口。账号余额不足，不代表 API Key 失效；API Provider 的 401，也不代表登录账号异常。先看当前任务模型选择器使用的是哪条路线，再处理对应配置。

症状	最小检查	修复方向
`MISSING_CREDENTIAL`	“设置 → 模型”中凭证是否显示已设置	为当前 Provider 保存凭证或修复环境变量引用
`INVALID_CREDENTIAL` / 401	Provider、端点与凭证是否配套	重新保存正确凭证；不要把 Key 发进对话
`UNKNOWN_MODEL`	当前任务选中的模型 ID 是否仍在 Provider 中	选择已配置模型，或补回准确模型 ID
模型发现返回 401	端点的 `GET /models` 是否接受该凭证	检查 Key；不支持模型发现时手动录入
模型列表格式无法识别	返回是否既无 `data` 数组也无 `models` 对象	手动录入模型，不把“发现失败”当成“推理一定失败”
只有某些中转模型失败	协议与请求形状是否匹配	核对 OpenAI/Anthropic/DeepSeek 协议与兼容设置

修复后一定新建 Read Only 任务，重新执行 17.3 的 MODEL_OK。旧任务可能仍绑定旧模型选择或已有失败上下文；只在旧消息上点重试，不能证明新配置已经用于新 Agent。模型 Provider 官方排错

17.7 卡在审批、工具缺失或“明明允许却没执行”

审批是一次性的敏感操作决策，不是永久授权。ask 策略会等待应答，never 会直接拒绝；审批通道缺失或应答失败时也会失败关闭，而不是默认放行。审批服务官方说明

按症状判断：

界面有待审批卡片：先读动作、路径和理由，再允许或拒绝；
已经拒绝：该次请求不会因你后来改主意自动执行，让 Agent 重新提出具体操作；
没有卡片却返回 approval unavailable：检查当前 Profile 是否加载审批应答器，以及界面连接是否仍有效；
Read Only 下要求写文件：这是权限边界生效，不是工具损坏；换成 Workspace Write 之前先确认任务确实需要写；
工具完全不在轨迹中：检查 Agent 预设、插件作用域和新任务的工具列表，不要先放宽沙箱。

如果只有一个动作被拦，不要把整场任务切到更宽权限。保持原权限，让 Agent 缩小操作范围或再次请求单次审批，通常更容易审查。

17.8 插件显示“已启用”，能力却不可用

“已启用”表示配置选择了它，不等于模块成功加载。打开“设置 → 插件 → 插件列表”，同时看：

条目 ID 与完整包名；
启用/停用状态；
实际运行状态；
加载错误；
它属于 Profile、Agent 预设还是 Client 界面。

第三方 bundle 加载失败时，插件管理页会保留条目和错误，允许停用或修复。诊断日志位于所选 Profile 的 .plugin-manager/logs 下；日志可能包含 registry、代理、路径和包管理器输出，分享前必须脱敏。插件管理器官方说明

排查顺序：

先停用最近新增或更新的第三方 bundle；
按界面提示重启当前 Profile；
在只读插件列表确认核心条目无加载错误；
新建任务验证能力；
仍失败时再查看诊断日志，不要连续重复安装。

Desktop 与 CLI/Web Profile 的依赖、锁文件和启用选择相互独立。在 Desktop 中坏掉的插件，要在 Desktop 插件页或原生恢复里处理；运行 dsh plugin --profile web 不会修复 Desktop。

17.9 Skill 找不到，或 MCP 工具没有出现

Skill 找不到

先检查四项：

项目级路径是否为 .dsh/skills/<name>/SKILL.md；
frontmatter 是否同时有合法的 name 与 description；
name 是否使用 kebab-case，并与调用名一致；
新建任务后，输入 /name 是否出现内联建议。

Skill 文件存在但没有被发现，优先检查路径和 frontmatter；已经被发现但行为没遵守，才检查描述是否触发、是否显式调用，以及正文规则是否互相冲突。

MCP 工具没有出现

先确认 MCP Server 的启动命令在系统终端能运行，再检查当前 Profile 的配置和插件列表。工具出现时应带 Server 命名空间，例如 mcp__daily_report_fs__...；只看到一个泛化工具名，不能证明连到了预期 Server。

最后做一正一反两个检查：

在已授权目录中读取或写入一个练习文件；
尝试访问授权目录外的无敏感测试路径，确认被拒绝。

正向失败通常指向进程、配置或路径；反向竟然成功则是权限边界过宽，不能因为“工具能用”就验收通过。具体步骤回第 12 章。

17.10 Goal、子智能体、Schedule 与 Headless 看起来“不工作”

这四种机制的停顿原因不同，先看它们各自的状态入口。

Goal 没继续

用 /goal 查看 phase、Round 和剩余轮数。paused 需要用户明确恢复；达到 Round 上限不会偷偷扩容；Host 或进程重启后也不能把“持久状态”误解为“后台一定仍在运行”。先恢复，再观察下一 Round 是否启动。

子智能体没有结果

打开父任务顶部的子级目录，确认子任务究竟是运行中、需要输入、失败还是已完成。父 Agent 说“我已委派”不是独立证据；没有子会话或工具轨迹时，先检查当前预设是否真的包含 subagent 工具。

定时任务没触发

依次检查 Schedule 插件是否启用、任务是否活动、下一次时间与 Asia/Shanghai 是否正确、原 Session 是否仍可恢复、Desktop/Web Host 是否正在运行。不要在没看任务列表和投递记录前重复创建同名任务。

Headless 没有输出或脚本误判成功

默认模式在首个非空推理增量前可能静默。自动化需要进度时用 --json，但仍要同时检查进程退出码：0 表示轮次完成，1 表示中止或错误；有 final 事件也不保证运行成功。详细边界回第 15 章。

17.11 日报助手失败：先绕过 Agent

进入 daily-report 目录，按成本从低到高运行：

npm run check
npm test

npm run check 失败：先修 sources.json 或配置解析，不要访问网络；
npm run check 成功、npm test 失败：问题在代码或测试回归；
两者都成功、npm start 失败：再检查真实数据源、网络、代理、速率限制和输出文件权限；
系统终端成功、Agent 中失败：回到工作区、权限、Shell 工具和审批层。

只有前两项成功且你接受真实外部请求时，才运行：

npm start

npm start 会访问配置的数据源并覆盖 daily-report.md，不是普通只读诊断。不要为了确认 DSH 是否在线就拿它当第一条探针。

17.12 把证据交给 Agent，而不是让它猜

需要 DSH 帮忙分析时，在新的 Read Only 任务中使用下面模板：

请只诊断，不修改文件、不安装软件、不改变配置、不访问外部网络。

环境：
- 操作系统与架构：<填写>
- DSH 入口与完整版本：<Desktop 或 CLI/Web；填写版本>
- Profile / Agent 预设 / 权限：<填写>
- 工作区：<只写目录名，必要时隐藏上级路径>

现象：
- 最后一项成功操作：<填写>
- 第一项失败操作：<填写>
- 原始错误码或退出码：<填写>
- 是否能在新任务复现：<填写>

请输出：
1. 最可能失败层及依据；
2. 两个最小只读检查，按顺序列出；
3. 每个检查的预期结果与下一分支；
4. 当前证据不足时，明确还缺什么。

粘贴日志前删除 API Key、Authorization 头、Cookie、账号标识、完整本机路径和私有仓库地址。脱敏时保留错误码、时间、版本、失败阶段和调用顺序，否则日志会安全但失去诊断价值。

17.13 什么时候应该回退，而不是继续试

遇到以下情况先停：

修复动作要求删除整个 Harness Home、Profile 或工作区；
不清楚一条管理员或 sudo 命令会改哪些文件；
第三方插件来源、构建脚本或兼容版本无法确认；
日志显示凭证可能已经进入对话、脚本或公开仓库；
同一个写操作被重复执行，无法确认是否已经部分成功；
修复需要扩大到工作区之外，但当前没有明确授权。

优先回退最近一项可识别变更：停用新插件、恢复 Profile patch 备份、切回已知模型、改用新任务、撤销项目差异。不要把“重装一切”当作通用回退方案。

17.14 本章验收

请确认你现在能够：

用“应用 → 模型 → Agent/工具 → 权限/工作区 → 项目”五层模型定位问题；
完成版本、最小模型、只读工具与项目命令四项健康检查；
从 Desktop 原生弹窗找到崩溃报告，而不是先删除配置；
区分账号模型问题与 API Provider 问题；
区分审批拒绝、审批通道不可用与工具根本不存在；
判断插件“已启用”与“已成功加载”不是一回事；
分别检查 Skill、MCP、Goal、子智能体、Schedule 和 Headless 的状态入口；
用 npm run check、npm test、npm start 的顺序判断日报助手失败层；
能生成一份不含凭证、但保留版本和错误码的诊断材料；
在修复后用新任务或独立命令复验，而不是只相信原任务的文字结论。

排错的目标不是“让红色提示消失”，而是知道哪一层恢复了、用什么证据证明、是否引入了新的权限或副作用。下一章会把本教程已经覆盖的能力与尚未展开的进阶方向分开，给出学完之后的继续学习路线。

← 上一章：案例七：把经验沉淀到项目、Skill 与 Profile　|　回目录　|　下一章：进阶学习路线：从“跟着做”到独立完成任务 →

第 17 章 常见问题排查：先定位哪一层坏了