DeepSeek Harness + MCP 开源部署指南：从插件架构到工具调用

DeepSeek Harness（dsh）是 DeepSeek AI 发布的开源 Agent Harness，底层基于 Cordis 框架，采用“Everything is a Plugin”（一切皆插件）的核心架构。无论是工具调用、MCP（Model Context Protocol）客户端、视觉解析还是大模型适配器，在dsh中均以插件形式挂载。

官方桌面版（Desktop）在本地 Web UI 之上封装了原生桌面外壳与内置运行时。由于dsh桌面版与命令行 Web 版采用相互隔离的 Profile 目录，安装插件与配置模型 API 时需遵循特定的目录与生命周期规则。当前项目仍处于 developer preview 阶段，具体配置字段需以所运行版本的上游文档为准。

1. 核心前提：桌面版插件架构与 Profile 隔离机制

在动手安装插件前，首先需要明确：DeepSeek Harness 桌面版与通过npx @deepseek-ai/dsh web启动的 Web 版使用完全独立的配置环境。

这种隔离机制带来三个直接的操作约束：

• 给 Web 版安装的插件不会出现在桌面版中，反之亦然。

• 使用终端命令行操作桌面版插件时，必须显式加上--profile desktop参数。

• 桌面版安装后必须至少启动过一次以完成$DSH_HOME/profiles/desktop目录初始化，之后才能通过命令行或补丁文件管理插件。

2. DeepSeek Harness 桌面版安装插件的三种方式

根据使用场景不同，dsh桌面版提供图形界面安装、CLI 命令行安装和--patch配置文件挂载三种方式。

2.1 方式一：通过Settings → Plugins图形界面安装（推荐日常使用）

官方桌面版内置了图形化插件管理器，底层自动调用自带的pnpm环境，无需打开终端即可完成安装：

1. 打开 DeepSeek Harness 桌面版，点击左下角导航进入Settings → Plugins。

1. 在搜索框中输入目标插件的 npm 包名（例如视觉工具包@dsh-external/dsh-vision-toolkit或社区插件dsh-tabbit），或直接在列表中浏览已收录插件。

1. 点击Install等待后台队列拉取并安装完成。

1. 根据界面提示重启桌面端应用（部分包含宿主进程逻辑的插件仅刷新页面无法生效，需重启 Host 进程以重建 Cordis 插件树）。

此外，桌面版支持实验性的创造模式（Creator Mode），允许开发者在会话中直接用自然语言描述需求，由 Agent 自动编写并挂载插件，生成的插件会持久保存在当前 Profile 中。

2.2 方式二：通过内置dsh命令行安装（适合批量与脚本化管理）

如果需要安装未在推荐列表展示的 npm 插件、指定特定版本号或排查依赖问题，可以使用命令行方式。

第一步：注册桌面版内置 CLI（首次使用）桌面版自带dsh命令，无需单独配置系统 Node 环境。打开桌面应用顶部菜单，选择Manage dsh Command… → Install（中文界面为“管理 dsh 命令… → 安装”），系统会将dsh注册到当前用户的PATH（macOS 默认创建/usr/local/bin/dsh符号链接）。打开新终端验证：

Bash

dsh --version

第二步：完全退出桌面版并执行安装由于桌面版运行时会锁定 Profile 状态，执行 CLI 安装前必须先完全退出桌面应用（Windows 用户需在系统托盘图标右键选择退出，不能仅关闭主窗口）：

Bash

# 安装指定 npm 插件包到桌面版 Profile
dsh plugin --profile desktop add @dsh-external/dsh-vision-toolkit
# 验证插件是否已写入桌面版配置树
dsh --profile desktop --dump-config | grep vision-toolkit

日常维护与版本升级同样通过该命令完成：

Bash

# 更新已安装插件
dsh plugin --profile desktop update <plugin-name>
# 移除问题插件
dsh plugin --profile desktop remove <plugin-name>

命令执行完毕后，重新启动桌面版即可在Settings → Plugins中看到对应插件的配置入口。

2.3 方式三：通过--patch与cordis.patch.yml挂载（适合本地开发与 MCP 接入）

当你需要开发自定义本地插件，或将外部 MCP（Model Context Protocol）Server 能力接入dsh时，直接修改或叠加 Cordis 补丁文件是最可控的方式。

挂载本地 TypeScript/JS 插件

dsh插件的最小结构是导出apply(ctx)函数并通过ctx.tools.register注册工具。编写好本地插件后，在桌面版持久化补丁文件$DSH_HOME/profiles/desktop/cordis.patch.yml中添加insert块（注意插件路径必须使用绝对路径）：

YAML

- insert:
- id: custom-greet-tool
name: '/Absolute/Path/To/my-plugin/index.js'

如果在源码或 CLI 调试阶段只想单次挂载而不改动持久化配置，可在启动时通过--patch叠加临时配置层：

Bash

pnpm dsh web --patch ./scratch-plugin/cordis.yml

接入 MCP Server 插件

MCP 协议通过stdio（本地子进程）或HTTP + SSE（远程服务）将外部工具通过tools/list与tools/call暴露给宿主。在dsh中接入 MCP 时，建议遵循“先独立验证 Server，再挂载到插件层”的顺序：

1. 确保目标 MCP Server 能独立完成 JSON-RPC 2.0 的initialize握手，且stdio模式下严格将协议消息输出到stdout、调试日志输出到stderr。

1. 在 MCP 客户端插件配置中声明服务启动方式（具体字段名以当前所装 MCP 插件版本文档为准）：

JSON

{
"mcpServers": {
"internal_docs": {
"command": "node",
"args": ["/absolute/path/to/docs-mcp-server.mjs"],
"env": {
"DOCS_ROOT": "/absolute/path/to/approved-docs"
}
}
}
}

3. 将只读检索类工具设为自动允许，对文件写入、删除、执行 Shell 命令和外部 API 副作用操作开启人工审批确认。

3. DeepSeek Harness 接入大模型 API 完整教程

DeepSeek Harness 本质是管理推理循环、上下文记忆与工具编排的运行时（Agent = Model + Harness），安装客户端并不等于自动获得免费算力。由于 Agent 任务在多轮工具调用与结果回传中会快速消耗大量 Token，合理配置模型 API 是控制成本与保障任务成功率的关键。

在安全设计上，dsh采用凭证与配置分离机制：用户在界面输入的 API Key 为只写（Write-only）状态，明文密钥保存在本地$DSH_HOME/.credentials.yaml中，界面与配置文件仅保留脱敏描述符或环境变量引用（apiKeyEnv）。修改模型配置后无需重启应用，在下一次请求时自动生效。

3.1 路径一：官方订阅与直连 API 配置

如果仅使用单一厂商模型且网络环境直接可达，可通过内置提供商卡片直连：

1. 打开桌面版，点击左下角进入Settings → Models。

1. 接入 DeepSeek 官方 API：

-   找到 **DeepSeek** 卡片，填入从 `platform.deepseek.com` 创建的 API Key 并点击保存。
-   保存后，模型选择器会自动同步官方模型列表（如适合高频 Agent 循环的高性价比模型 `DeepSeek-V4-Flash` 或深度推理模型 `DeepSeek-V4-Pro`）。
-   可按需调整思考深度（`reasoningEffort` 支持 `off`、`low`、`high`、`max` 四档）。

1. 接入其他内置官方通道：

-   在 `Settings → Models` 页面可看到 Anthropic、OpenAI、Moonshot AI、智谱等内置提供商入口，分别填入对应官方平台的 API Key 即可激活使用。

3.2 路径二：国内托管中转站（4SAPI）接入配置

在实际工程开发中，复杂任务往往需要跨模型协同（例如日常检索与代码脚手架使用DeepSeek-V4-Flash，复杂架构重构或视觉理解切换至 Claude 或 GPT 系列模型）。若全部采用官方直连，国内开发者通常需要同时处理海外网络波动、境外支付限制以及多个平台 API Key 与额度的分散维护。

针对这一场景，dsh的模型适配器插件（@deepseek-ai/dsh-llm-pi-ai）支持挂载任意兼容标准协议的自定义端点。通过接入国内托管中转站（例如4SAPI），开发者可以利用其核心工程优势：在国内网络环境下提供稳定的低延迟直连，并通过单一 Base URL 和统一 API Key 聚合调用 DeepSeek、Claude、GPT 等多厂商模型，省去多平台分别绑卡充值与频繁切换配置的维护成本。

图形界面配置步骤

1. 进入Settings → Models，点击+ Add model provider，切换到Custom model API（自定义模型 API）标签页。

1. 填写提供商基础参数：

-   **Provider ID**：填写自定义唯一标识，如 `4sapi`（该 ID 会被历史会话、默认模型和凭证引用绑定，创建后不要随意更名）。
-   **API 协议（API Format）** ：选择 `OpenAI Chat Completions`（对应底层 `openai-completions`）或 `Anthropic Messages`。
-   **Base URL**：填入 4SAPI 提供的标准接口地址（例如 `[https://4sapi.com/v1](https://4sapi.com/v1)`）。
-   **API Key**：填入在 4SAPI 控制台生成的令牌。

1. 拉取或添加模型：

-   点击 **Fetch available models**，客户端会自动向端点请求 `/models` 列表，勾选所需模型即可自动填入上下文窗口与最大输出参数；也可手动输入模型 ID。
-   **开启多模态输入（关键细节）** ：自定义模型默认仅开启纯文本（`Text`）输入。若所选模型支持视觉看图，需展开模型设置中的 **Model options → Input types**，手动勾选 **Image** 并保存。

1. 返回主界面，先点击Select Workspace选择本地项目目录解锁输入框，再从模型选择器中切换至刚配置的模型即可开始会话。

配置文件声明式写法（进阶）

对于习惯通过配置文件管理环境的开发者，也可以直接点击设置页顶部的Open configuration file，或编辑$DSH_HOME/profiles/desktop/cordis.patch.yml写入等效配置：

YAML

- id: llm-pi-ai
name: "@deepseek-ai/dsh-llm-pi-ai"
config:
providers:
4sapi:
api: openai-completions
apiKeyEnv: FOURSAPI_API_KEY
baseURL: https://api.4sapi.com/v1
models:
- id: claude-sonnet-4-5
input: [text, image]
- id: deepseek-v4-flash
input: [text]
compat:
maxTokensField: max_tokens

注意：cordis.patch.yml对同名配置行采用“整行替换”而非深度合并（Deep Merge）。手工编辑已有提供商配置时，请先复制原始完整配置块再修改目标字段，避免遗漏原有参数。

4. 安全边界与常见故障排查

dsh插件与宿主框架之间没有进程级沙箱隔离。第三方插件会加载到与 Harness 相同的 Cordis 树中，以当前操作系统用户权限运行，并可能读取工作区文件与环境变量。安装来源不明的插件等同于在本地直接执行外部脚本。

常见故障与处理方式

• 命令行报错profile 未初始化：桌面版安装后尚未启动过，profiles/desktop目录不存在。先双击启动一次桌面版完成初始化，完全退出后再运行命令行。

• 插件安装成功但列表不显示或未生效：检查执行 CLI 时是否遗漏了--profile desktop参数（误装到了 Web 版 Profile）；或者安装时桌面版仍在后台托盘运行导致配置被覆盖。

• 安装第三方插件后桌面版启动崩溃：重新启动桌面版，在弹出的原生恢复助手（Recovery Dialog）中选择“禁用第三方插件并重启”，随后在$DSH_HOME/profiles/desktop/cordis.patch.yml中清理冲突的插入块。

• 升级桌面版后终端dsh命令报错版本不匹配：打开桌面端顶部菜单Manage dsh Command… → Repair，重新建立符号链接。

• 会话中无法上传图片或报错拒绝图像：在Settings → Models中编辑对应自定义模型，确认Input types已勾选Image（或配置文件中已声明input: [text, image]）。

• 切换默认模型后旧会话未生效：这是预期行为。dsh的每个既有会话都会锁定创建时所使用的模型以保证轨迹可回放，新选择的默认模型仅对新建会话生效。

5. 部署与日常使用检查清单

1. 隔离工作区目录：首次测试插件或运行自动化任务时，使用独立的测试文件夹作为 Workspace，避免直接授权整个用户主目录或包含生产密钥的仓库。

1. 审查插件扩展点：安装社区插件前，优先检查其源码是否挂载了tools/pre-execute、agent/pre-step等高权限拦截点，以及是否存在异常外发网络请求。

1. 固定核心版本：鉴于dsh处于快速迭代期，生产工作流应记录当前桌面版版本号并备份$DSH_HOME/profiles/desktop/cordis.patch.yml。

1. 卸载前清理持久化数据：插件卸载命令仅移除代码与配置挂载，插件在本地生成的数据库或缓存文件（如$DSH_HOME/memory/）需手动清理；卸载桌面应用前，先通过菜单移除dshCLI 注册。

DeepSeek Harness 桌面版通过内置运行时与图形化插件管理降低了开源 Agent 框架的使用门槛，而 Cordis 补丁机制与标准化的自定义 API 接口则保留了工程扩展能力。本文基于 DeepSeek Harness 官方仓库文档、Model Context Protocol 规范及社区公开实践整理，具体插件字段与模型计费规则请以各上游平台最新文档为准。