DeepSeek Harness 常见问题 FAQ：30 个开发者常问的问题

DeepSeek Harness（dsh）是 DeepSeek AI 开源、采用 MIT 协议的 agent harness，围绕"一切皆插件"这一单一扩展机制构建。本页汇总了开发者最常问到的 30 个问题，涵盖安装、配置、扩展与评估——每条回答都有据可查，来自 dsh 自己的文档，并附深入阅读的链接。

我们把这些问题分成了六组——基础概念、安装配置、配置概念、插件、MCP/Claude Code/迁移、以及进阶与实操话题——方便你直接跳到最贴近你当前困惑的那一节，而不用在 30 个问题的长列表里一条条翻找。

基础概念

什么是 DeepSeek Harness？

DeepSeek Harness（dsh）是 DeepSeek AI 开源的 agent harness（智能体运行框架），构建在 Cordis 插件框架之上，核心原则是每一种能力——工具、命令、技能、MCP 桥接、模型适配器——都用同一种插件机制实现。它目前处于开发预览期。完整介绍见《什么是 DeepSeek Harness？》。

DeepSeek Harness 免费吗？

harness 本身免费，采用 MIT 协议。你依然需要为接入的模型 API 付费（无论是 DeepSeek 自己的模型，还是你配置的任何其他 provider），这和使用其他 coding agent 时的付费方式没有本质区别。许可协议和 API 成本具体怎么算，见《DeepSeek Harness 免费吗？》。

harness 本身的代码是开源的、MIT 协议，可以被审查。更大的风险在插件生态：安装一个插件意味着在你机器上执行它的代码，而且没有官方市场对提交内容做审核——发现机制只是一个 GitHub topic，package.json 里的 dsh.bundle 字段是唯一能判断"这是不是真插件"的结构化信号。安装任何来自不熟悉作者的插件之前，先读我们的插件安全清单，尤其是那些安装时需要你授予 allowBuilds 权限的插件。

DeepSeek Harness 稳定到可以用于生产环境了吗？

截至撰稿时，还不行。dsh 明确处于开发预览期，没有 SemVer 承诺，也没有 GitHub Releases 历史记录——它自己的 README 就写明了会有破坏性变更。社区目前对这个状态的态度，见我们的《首周开发者反馈综述》。

DeepSeek Harness 和 agent 框架/SDK 是一回事吗？

不完全是——harness 的范畴更广。它是包裹在模型外面的整个运行时：工具循环、上下文管理、权限、会话处理、扩展机制，而不仅仅是一个调用模型的 API。dsh 是这个概念的一个具体实例，通用定义见《什么是 Agent Harness？》。

安装与配置

怎么安装 DeepSeek Harness？

最快的方式是直接从 npm 运行，不需要克隆任何仓库：

npx @deepseek-ai/dsh web

这会在 http://127.0.0.1:3080 启动 Web UI。分平台的具体步骤和已知坑，见《在 macOS、Windows、Linux 上安装 DeepSeek Harness》和通用的《快速上手》。

系统要求是什么？

Node.js ^22.19.0 或 >=24.0.0，安装插件需要 PATH 里有 pnpm（具体要求 pnpm ≥10，因为它对 git 依赖的构建脚本权限有特殊处理）。Python SDK 有另一套更窄的平台要求，见下面 Python SDK 相关的问题。

DeepSeek Harness 能在 Windows 上跑吗？

可以，但有几个已知的小坑：原生目录选择器的 bug（绕过方案是切换到 directory-picker-browse 后端）、中文路径处理的问题反馈，以及 Node 版本早于 22.15 时会出现的 zlib 报错。具体修复方法见《在 Windows 上安装》。

DeepSeek Harness 能用哪些模型？

原生支持 DeepSeek 自家模型，还内置了 Anthropic、OpenAI、Bedrock、Vertex、Azure 以及 Codex 原生鉴权的 provider 目录，此外任意 OpenAI 兼容的自定义端点也能接。如何添加一个不在内置列表里的 provider，见《在 DeepSeek Harness 中使用 OpenAI、Anthropic 或任意 OpenAI 兼容 API》。

怎么配置我的 DeepSeek API key？

通过 Web UI 的 Settings → Models 面板——把你的 key 粘贴进 DeepSeek 卡片并保存，不需要重启进程。密钥存放在 $DSH_HOME/.credentials.yaml，界面上只会回显一个脱敏后的引用，永远不会显示明文。完整步骤见《DeepSeek Harness API Key 配置》。

配置概念

我能用 Claude 或 GPT 模型代替 DeepSeek 自己的模型吗？

可以——既可以用内置的 Anthropic/OpenAI provider 条目，也可以在你走网关代理的情况下添加一个自定义的 OpenAI 兼容 provider。需要注意的是，DeepSeek 自家的原生 chat-completions 路由是纯文本的；如果你需要某个自定义模型支持图片输入，必须在 settings.yaml 里为它显式声明 input: [text, image]。见《API Key 与模型配置》。

DeepSeek Harness 里的"profile"是什么？

profile 是 $DSH_HOME/profiles/<name> 下一份具名的、可运行的配置——它把哪些插件生效、以及你自己的覆盖层打包在一起。web 和 headless 是保留名字，会自动用模板初始化；其他任何名字的 profile 都只会从基础 bundle 开始。见《Profile 与 Bundle 详解》。

"bundle"是什么？

bundle 是一个插件包所贡献的内容——通过它 package.json 里的 dsh.bundle 字段声明，指向一个描述它往 Cordis 插件树里插入了什么的 YAML patch 文件。一个 profile 由一个或多个 bundle 按顺序层叠而成。同源资料：《Profile 与 Bundle 详解》。

headless 模式是什么？

一种一次性、非交互式的运行方式：dsh --profile headless "任务文本" 跑完一个任务、打印最终回答，完成后退出码为 0（否则为 1）。它完全没有监听端口——没有 Web UI，没有 API 代理——非常适合脚本化和 CI 场景。见《DeepSeek Harness Headless 模式》。

有 DeepSeek Harness 的 CLI 吗？

有——dsh 命令本身就是 CLI，有四种入口模式（--profile <name>、--profile headless "任务"、dsh web、dsh plugin）。见《有没有 DeepSeek CLI？》和完整的《CLI 速查表》。

插件

怎么安装一个插件？

dsh plugin --profile <profile名> add <包说明符>

这条命令会把参数原样转发给 pnpm，所以任何 pnpm 能安装的东西——npm 包名、github:owner/repo、本地路径、或 tarball——都可以作为说明符。完整细节见《如何安装 DeepSeek Harness 插件》。

去哪里找 DeepSeek Harness 插件？

没有官方市场——dsh 唯一认可的发现机制是 GitHub topic dsh-plugin。FindHarness 的插件索引主要来自社区维护的 awesome-dsh-plugin 列表，加上其他补充发现渠道，并对照每个包的 dsh manifest 字段做验真。完整目录见 /plugins，各发现渠道的对比见《如何找到 DeepSeek Harness 插件》。

怎么判断一个插件在安装前是否安全？

检查这个包是否真的声明了 dsh.bundle 字段、读一下它的 patch 文件插入了什么、看看有没有 prepare 脚本（如果你授予 allowBuilds，它会在安装期执行任意代码）、如果是从 GitHub 而不是 npm 安装，记得锁定到具体的 commit。完整的十条检查流程在我们的插件安全清单里。

怎么写自己的插件？

一个 dsh 插件就是一个导出 apply(ctx, config) 函数的普通 TS/JS 模块——没有独立的 manifest 文件格式。最简单的插件形式：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里注册能力
}

完整的开发流程，包括工具注册和发布，见我们的插件开发入门。

dsh 的插件生态是怎么按分类组织的？

FindHarness 把收录的插件分成十二个分类——UI 增强、主题、记忆、工具与能力、工作流与自动化、会话与消息、通知与集成、MCP 连接器、模型与 provider、开发与运行时、技能、以及娱乐向。完整浏览在 /plugins，各分类的代表性插件精选见《插件分类地图》。

MCP、Claude Code 与迁移

DeepSeek Harness 支持 MCP server 吗？

支持，而且是一个正式的、文档完整的功能——不是实验性占位。每个 MCP server 都对应一个 @deepseek-ai/dsh-mcp-client 插件实例，支持 stdio 和 streamable-http 两种传输方式，并带有自动重连机制（指数退避，达到一定次数的连续失败后放弃，直到下次重载）。见《如何在 DeepSeek Harness 中使用 MCP Server》。

dsh 的 MCP 支持和 Claude Code 的一样吗？

很接近，但范围更窄。dsh 把桥接的工具命名为 mcp__<serverName>__<rawName>，和 Claude Code 用的是同一套"server-qualified"命名形状——但 dsh 的 MCP client 只桥接 Tools；Resources 和 Prompts 目前被文档列为"延后实现"，还没有接入任何消费方。完整对比见 DeepSeek Harness vs Claude Code。

DeepSeek Harness 和 Claude Code 有什么区别？

最大的区别在架构层面：dsh 把工具、命令、技能、钩子、MCP 桥接全部收拢成一种插件机制，而 Claude Code 把它们当作各自独立的系统，各有自己的文件格式，并且提供官方市场。两者也不是纯粹的竞争关系——dsh 可以把任务委派给 Claude Code 当子代理。完整拆解见 DeepSeek Harness vs Claude Code。

DeepSeek Harness 能把 Claude Code 当子代理用吗？

可以——dsh-subagent-claude-code 是一个官方子代理 provider，通过 Claude Code 自己的 Agent SDK 来驱动它，此外还有 Codex、Agent Client Protocol、以及若干进程内 agent 的 provider。见《DeepSeek Harness 子代理》；如果你要把 Claude Code 工作流迁移过来，也可以看我们的迁移指南。

我能在 DeepSeek Harness 里复用 Claude Code 的 hooks.json 吗？

可以，通过官方的 dsh-hooks-claude-code 桥接插件，它会把钩子事件翻译成 dsh 自己的扩展点监听器。Codex CLI 的钩子也有对应的 dsh-hooks-codex 桥接插件。见《DeepSeek Harness 的 Hooks 与斜杠命令》。

进阶与实操

Claude Code 的 Skills 和 DeepSeek Harness 兼容吗？

目前没有明确说法。dsh 有自己的 Skill provider 注册表（ctx.skills），在架构上和 Claude Code 的 SKILL.md 约定是两回事，有一条社区讨论（#88）专门问过兼容性问题，dsh 的文档里也没有给出官方的肯定答复。社区插件 dsh-skillport 作为第三方变通方案，能桥接已有的 SKILL.md 库。详情见我们的迁移指南。

有 Python SDK 吗？

有——PyPI 上的 deepseek-harness-sdk，要求 Python 3.10+，平台限定 Linux x64/arm64 和 macOS 14+（arm64）；它自带打包好的运行时，不需要单独安装 Node.js。也有一个 TypeScript SDK，两者都构建在同一套底层的 stdio JSON-RPC 协议之上。见《DeepSeek Harness Python SDK》。

DeepSeek Harness 有哪些沙箱/权限选项？

三档沙箱模式——read-only（只读）、workspace-write（新 session 的默认值，写操作被限制在工作区根目录和平台临时目录内）、danger-full-access（完全不隔离）——由平台特定的机制强制执行（Linux 上是 bwrap/Landlock，macOS 上是 Seatbelt，Windows 上是 ACL 受限令牌方案，此外还有一个 E2B 云沙箱选项，适合想把执行完全放到本机之外的团队）。这些模式会和审批策略打包成"权限预设"，默认配置正好提供两档。完整细节见《DeepSeek Harness 的权限与沙箱》。

我能把 Web UI 暴露到网络上吗？

不能——--host 0.0.0.0 是明确不支持的，尝试这么做会直接报错。官方给出的理由很直接："这会把远程代码执行暴露到网络上"，Web UI 的设计目标就只是 127.0.0.1。如果你需要远程访问，得自己负责搭建隧道或端口转发，即便如此，也有反馈说部分工作区和文件选择器功能通过转发连接无法完全正常工作——把这当成一条非官方、不受支持的路径，而不是一个正式功能。

去哪里报告 bug、查官方文档、或确认当前版本？

截至撰稿时，npm 上发布的版本是 0.1.0-rc.6，明显领先于仓库自己 master 分支 package.json 里写的版本号（0.1.0-rc.5)——想知道准确版本，去查 npm view @deepseek-ai/dsh version，因为没有 GitHub Releases 页面可以核对。dsh 仓库的 GitHub Issues 已被禁用；官方反馈渠道是 GitHub Discussions 和项目 README 里链接的 Discord 社区。另外还有一个基于 VitePress 的中英双语文档站，从 docs/ 目录自动构建部署，不过我们在文章里全程直接链接到 GitHub 仓库里的具体文件，因为这个托管的文档域名出现过限流行为，直接引用不够可靠。

下一步

第一次安装？从快速上手开始。
在权衡 dsh 和你现在用的工具？读 DeepSeek Harness vs Claude Code。
打算迁移已有的 Claude Code 配置？看《从 Claude Code 迁移到 DeepSeek Harness》。
浏览完整插件目录 /plugins，按分类查看。