核心摘要：DeepSeek Harness（简称 dsh）是 DeepSeek 开源的智能体运行框架，底层基于 Cordis 实现“一切皆插件”的模块化架构。截至 2026 年 11 月 10 日，@deepseek-ai/dsh 在 npm 官方仓库的 latest 与 next 标签均指向开发者预览版 0.2.2-rc.1，强制要求运行时环境 **Node.js >=24.9.0**。在排查 dsh 故障时，应遵循“分层隔离、单变量复验”原则，依次按 环境与版本基准 → Host 进程启动 → 插件激活同步 → 大模型 API 接入与网络请求 → 子代理（Subagent）委派 → 会话持久化 六个层级定位根因，避免通过盲目重装、删目录或频繁更换 API Key 掩盖真实报错。

一、 排错前置基准：锁定运行版本与启动入口

在解决“页面打不开”或“插件加载报错”前，首要任务是确认当前终端或桌面进程实际调用的 dsh 二进制来源及 Node.js 版本。在 npm 查看到最新版本，并不代表本地当前运行的进程已同步更新；同时，由于框架基于 Cordis 依赖注入驱动，单个前置插件初始化失败会导致下游依赖模块连锁静默。

截至 2026 年 11 月 10 日，官方仓库的 0.2.2-rc.1 仍处于“开发者预览（Developer Preview）”阶段，包清单声明 engines.node >= 24.9.0。请勿参考早期基于 import.meta.main 编写的旧版教程来降低 Node 版本要求。

在终端依次执行以下命令，核验本地环境基线：

node --version
npm --version
npm view @deepseek-ai/dsh dist-tags --json
npm view @deepseek-ai/dsh@0.2.2-rc.1 version engines --json
dsh --version

注：若您仅通过 npx 临时拉起服务，本地未生成全局 dsh 命令属于正常现象，无需将最后一条命令报错视为安装损坏。

区分三类运行入口的版本边界：

  1. npm 包运行：受全局或项目本地 node_modules 及 npx 缓存控制。
  2. 源码编译运行：仓库固定 Tag 声明包管理器为 pnpm@11.28.5。标准构建与启动链路为 pnpm install → pnpm run build → pnpm dsh web。注意 pnpm dsh web 仅负责拉起服务，不会触发重新编译；拉取新代码后若界面未更新，必须重新执行 build。
  3. Desktop 桌面客户端：内置独立的运行时环境。升级全局 npm 包不会更新桌面端内核，核对版本时需检查桌面应用自身版本号，以及菜单栏 “管理 dsh 命令…” 暴露的内置 CLI 路径。

二、 安装中断、命令无输出与 3080 端口冲突排查

将“依赖包拉取失败”、“Host 进程未启动”与“浏览器未自动弹窗”拆分为三个独立阶段处理：

1. 依赖下载与原生模块编译失败

当报错停留在 npm install 阶段时，先验证包管理器的连通性（此步骤仅代表 npm 链路正常，不代表后续大模型 API 网络可达）：

npm config get registry
npm ping
npm view @deepseek-ai/dsh@0.2.2-rc.1 version

2. 命令闪退或无响应

若执行启动命令后进程直接退出且无预期日志，首先核对 node --version 是否满足 >=24.9.0，并确认 which dsh 指向的入口文件未被旧版本残留覆盖。

3. Web 端口占用（EADDRINUSE）与访问地址误区

npx @deepseek-ai/dsh@0.2.2-rc.1 web --port 8080 --no-open

若 8080 端口可正常启动，只需定位并正常退出占用原端口的旧实例即可，切勿粗暴地批量强杀所有 Node 进程。此外，当前版本的 CLI 严格校验监听参数，**不支持传入 --host 0.0.0.0**，强行添加该参数会直接被 CLI 拒绝。

三、 Host 进程启动崩溃：解读诊断日志与 Profile 配置层

当 Host 进程无法拉起时，切勿只搜索终端最后一行泛化的错误提示，应第一时间查阅 CLI 输出中 Full diagnostics: 指向的原始诊断报告。

1. 定位启动诊断报告

在 0.2.2-rc.1 中，一旦核心必需插件激活失败，系统会输出完整的原始调用栈、阻塞等待中的插件列表以及缺失的上游服务，并将报告持久化至 $DSH_HOME/logs/startup-<timestamp>-<uuid>.log（默认路径为 ~/.dsh/logs/）。若仅是非必需的可选插件加载失败，则不一定触发该崩溃日志。

2. 修复 cannot resolve profile bundle

遇到组合包解析失败时，需先区分缺失的是 dsh 内置组合包 还是 Profile 额外安装的外部扩展包：

若确认是 web Profile 的外部依赖目录丢失，但清单文件依然完好，可在备份该 Profile 后借助 pnpm 按清单补齐依赖：

pnpm --version
dsh plugin --profile web install

注意：该命令并非所有 bundle 报错的万能药。如果某个插件本就打算废弃，应调用针对该包名的 remove 命令以同步清理配置清单，而非手动删除文件夹。

3. 核查配置覆盖层级（Config Patch）

修改了配置却未生效，通常是受到了配置叠加规则的覆盖。可通过以下命令导出默认配置与最终合成配置进行本地 Diff 比对：

dsh --profile web --dump-default-config
dsh --profile web --dump-config

四、 插件状态排错：区分安装、选中、激活与前端同步

在 DeepSeek Harness 中，“插件已安装”、“组合包已勾选（enabled）”、“Host 后端已激活”与“浏览器前端同步完成”处于四个不同的生命周期阶段。

官方 plugin-manager 规范明确指出：enabled 仅代表用户的配置意图已落盘保存，不代表插件已成功加载运行。日常管理插件应通过 Web 界面左侧边栏的 “插件” 面板操作；而 “设置” 页面下的插件列表仅为只读状态展示，不可混用。

状态返回码 / 现象 核心成因 标准排错动作
restart-required (restartReason: no-hmr) 目标插件不支持热模块替换（HMR） 确认配置保存后，手动重启搭载该 Profile 的运行时进程并复验。
unsupported-platform 宿主系统或 CPU 架构不在插件白名单内 核查实际运行 dsh Host 进程的服务器/本机系统，而非仅看打开浏览器的客户端设备。
application: 'failed' 插件在激活阶段或服务依赖解析阶段抛出异常 查阅 .plugin-manager/logs 诊断日志。注意此时包安装与勾选状态可能已落盘，系统不会完全自动回滚。
仅浏览器端同步报错 前端状态拉取或渲染异常 打开浏览器开发者工具检查客户端同步报错，与后端 Host 激活状态分开排查。

五、 大模型 API 接入指南与请求故障排查

当界面能够正常加载，但发起对话时提示模型报错或无响应，问题通常出在 API 接入配置、协议匹配或请求参数兼容性上。

1. DeepSeek Harness 大模型接入配置教程

在 Web 或桌面端界面中，进入 “设置 → 模型 → 自定义设置”（或通过 Profile Patch 配置文件），即可接入外部大模型服务。根据开发团队的网络环境与模型调度需求，通常分为以下两种接入路径：

路径 A：官方原生订阅 / 直连 API 接入

适用于直接调用 DeepSeek 官方平台、OpenAI 或 Anthropic 原生接口的场景：

  1. 选择协议类型：在协议下拉框中严格匹配目标厂商规范。当前版本核心支持 openai-completions（标准对话补全）、openai-responses 及 anthropic-messages。
  2. 填写基础地址（Base URL）：输入官方 API 根路径（如 [https://api.deepseek.com/v1](https://api.deepseek.com/v1) 或 [https://api.openai.com/v1](https://api.openai.com/v1)）。切勿将尾部的 /chat/completions 完整请求路径拼接到基础地址中。
  3. 配置凭证与模型 ID：填入官方控制台生成的 API Key，或配置对应的环境变量引用；手动输入或拉取官方精确的模型标识符。若直连海外官方接口，需确保下文第六节所述的 Host 进程网络代理已正确配置。
路径 B：国内托管 API 中转站接入（以 4SAPI 为例）

在复杂的 Agent 工作流中，开发者常需同时调用多个海内外厂商的模型（例如主对话使用 Claude 或 GPT 系列，辅助任务调用 DeepSeek）。此时若采用原生直连，往往需要维护多套异构协议配置，且极易因 Node.js 进程级代理配置不当触发 fetch failed。

作为替代方案，许多开发者会选择接入 4SAPI 等国内托管 API 聚合中转站。从工程排错与架构维护角度来看，这种方式具备三个核心优势：

接入步骤：在“自定义设置”中将协议固定为 openai-completions，API 地址填写中转站的 /v1 基础地址，填入聚合 Key 后，按平台模型广场提供的标准模型 ID 录入即可。

2. 模型层常见报错与兼容性调优

完成基础配置后，若请求依然失败，请按以下顺序逐项核验：

{
  "compat": {
    "supportsDeveloperRole": false,
    "maxTokensField": "max_tokens"
  }
}

六、 浏览器可访问但 Host 报 fetch failed：排查进程网络

许多开发者会遇到“浏览器能正常打开模型接口文档，但 dsh 发起请求却报 fetch failed”的现象。这是因为浏览器的系统代理不等于 Node.js Host 进程的网络路径，切勿看到 fetch failed 就盲目断定是 API Key 错误。

  1. 环境变量代理机制： dsh 启动时仅读取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 与 NO_PROXY 环境变量，不会自动读取操作系统的图形化代理设置。同时，在项目工作目录放置 .env 无法注入这些网络变量，必须通过启动前的终端环境或全局 $DSH_HOME/.env 进行配置。
  2. 安全脱敏自检命令： 在启动终端执行以下脚本，可在不泄露含密码代理地址的前提下，检查当前 Shell 环境是否已注入网络与证书变量（注：这仅反映当前终端状态，不代表 Desktop 独立进程或 $DSH_HOME/.env 内部状态）：
node -e 'for (const k of ["HTTP_PROXY","HTTPS_PROXY","ALL_PROXY","NO_PROXY","NODE_EXTRA_CA_CERTS"]) console.log(k + ": " + (process.env[k] ? "set" : "unset"))'
  1. 协议限制与企业内网证书： 当前版本不支持 SOCKS 代理协议。若处于开启了 TLS 流量审计的企业内网，需在启动前将 NODE_EXTRA_CA_CERTS 指向组织派发的根证书文件（.pem / .crt），重启对应 Host 进程后再对原先失败的操作进行复验。本地回环地址（Loopback）默认按规则直连。

七、 主模型对话正常，但 Codex 子代理（Subagent）执行失败

在 dsh 中，主模型回复正常仅能证明基础对话链路畅通；像 subagent_codex 这样的子代理插件拥有完全独立的运行时沙箱与身份验证边界。

根据 0.2.2-rc.1 的 Codex Provider 规范，排查子代理故障需重点关注以下机制：

  1. 锁定平台载荷（Locked Payload）与可选依赖： Codex 组合包内嵌了与特定操作系统和架构绑定的二进制载荷。如果在不支持的平台上运行、安装包损坏，或在安装时附加了省略 optional dependencies 的参数，子代理会在首次委派任务的 initialize 阶段直接崩溃。插件不会自动回退去调用宿主机系统全局安装的 codex CLI。因此，在终端单独运行原生 codex 成功，不能证明插件内置载荷完好。
  2. 工具暴露与覆盖规则： 当前版本的 Codex 组合包激活后会自动向全局注入 subagent_codex 工具，无需照搬早期旧教程手动复制 Preset。若界面看不到该工具，应检查是否未按要求重启 Host，或对应工具行是否被后续的 Config Patch 显式禁用、被同名 Preset 覆盖。
  3. 拆解 product-error 与临时会话边界： 当遇到 product-error 时，需查阅 Host 原始诊断日志以区分故障究竟发生在 初始化（Initialize） → 传输（Transport） → 产品执行（Execution） → 结果校验（Validation） 的哪一环，不能将其简单等同于“模型 API 地址填错”。此外，每次 Codex 委派都会拉起全新的临时线程（Ephemeral Thread），不可将其视为可跨次续接的原生长会话。

八、 历史会话无法打开：区分格式不兼容、数据损坏与写锁冲突

遇到旧会话加载失败时，请先备份保留原始会话文件，切勿直接手动篡改日志结构进行所谓的“版本降级”。官方 Session 模块将持久化异常严格划分为三类：

排查提示：如果所有新建会话均正常，唯独某个旧会话一旦继续对话就报错，请对比两者的历史上下文。旧会话中若包含历史图片或特殊工具调用记录，这些载荷会在每次新请求中持续携带发送；若当前切换的新模型不支持多模态输入，仅修改本地模型能力声明无法消除历史载荷，必须在全新会话中验证。

九、 提交高价值可复现 Issue 的标准清单

经过上述分层排查后，若确认属于框架本身的 Bug 并准备前往官方 GitHub Discussions 提交反馈，请勿仅上传一张前端报错截图。一份能帮助维护者快速定位的报告应包含以下结构化信息：

1. 运行入口：npm Web / 源码编译构建 / Desktop 桌面端
2. 版本基线：dsh 版本、Node.js 版本、桌面客户端版本（如适用）
3. 宿主环境：操作系统版本、CPU 架构、当前使用的 Profile 名称
4. 最小复现步骤：从进程启动到触发故障的确切 CLI 命令或界面点击路径
5. 原始错误堆栈：日志中的第一处 Root Cause、失败模块名称或服务端返回的 HTTP 状态码与响应体
6. 单变量对照结果：更换监听端口 / 禁用第三方插件 / 切换至纯文本新会话后故障是否依然复现
7. 诊断附件：对应时段的 startup-*.log 或 .plugin-manager/logs 片段、失败时间戳及网关 Request ID

安全脱敏提醒：DeepSeek Harness 生成的底层启动诊断报告与插件原始异常堆栈不会自动对敏感信息进行脱敏，日志中可能包含明文 API Key、代理账密或带认证 Token 的本地访问 URL。在公开社区提交日志片段前，请务必全文检索并抹除敏感凭证字段，仅保留技术诊断结构。

参考资料与核验基准