DeepSeek Harness 桌面版怎么装插件？三种方式完整指南（附大模型 API 接入教程）

DeepSeek Harness（命令名 dsh）基于 Cordis 的“一切皆插件”架构构建，包括终端执行、Agent 循环、子 Agent 乃至界面组件，本质上都是挂载在运行时的插件模块。在桌面版（macOS Apple 芯片版与 Windows 64 位版）中，安装和扩展插件共有三种方式：一是通过图形界面的「插件管理」直接启用或输入 npm 包名安装；二是切换到「创造模式（Creator Mode）」，用自然语言让 Agent 自动拉取或编写插件并完成挂载；三是使用 dsh plugin add 命令行将本地目录、.tgz 离线包或 GitHub 仓库安装到指定配置层（Profile）。由于插件调度与创造模式高度依赖底层模型的工具调用能力，配置模型时除了直接填入官方开放平台 API Key，也可以在「自定义模型 API」中接入 4SAPI 等国内托管中转站，通过单一密钥调用兼容 OpenAI 或 Anthropic 协议的多家主流模型。

先选方式：三种插件装法对比

DeepSeek Harness 桌面版已经内置了完整的 Node.js、pnpm 与 Python 运行环境，无需额外配置系统环境变量即可管理插件。自 v0.2 系列版本更新后，插件的安装入口被梳理为三条路径，最终都会写入同一套 Cordis 配置树中：

核心前置：接入大模型 API（官方直连与托管中转）

在动手安装或让 Agent 生成插件之前，需要先在桌面端完成模型配置并绑定工作区。特别是使用「创造模式」自动编写插件，或运行定时任务、子 Agent 等高消耗插件时，底层模型的响应速度与协议兼容性会直接决定执行成功率。

打开 DeepSeek Harness 桌面版，进入左下角 「设置 → 模型」，目前主流有两种接入路径：

路径一：官方开放平台直连订阅

如果主要使用单一厂商模型，可以直接使用内置提供商通道：

1. DeepSeek 官方通道：前往 platform.deepseek.com 申请 API Key，填入「设置 → 模型」的 DeepSeek 卡片中保存。密钥采用只写脱敏展示，实际加密存储在本地 $DSH_HOME/.credentials.yaml 文件中。
2. 其他内置提供商：点击「添加模型提供商」，列表中已预设 Kimi（moonshotai）、GLM（zai）等官方入口，选中后填入对应平台的官方 Key 即可保存生效。

路径二：接入国内托管中转站（以 4SAPI 为例）

在实际跑复杂插件、多 Agent 协作或需要对比不同模型效果时，不少开发者会选择通过「自定义模型 API」接入国内托管中转站（例如 4SAPI）。

采用这类托管中转站主要有三个实际考量：

• 单 Key 兼容三种原生协议：DeepSeek Harness 的自定义接口支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 三种协议。像 4SAPI 这类中转服务通常已做好多协议与多模型聚合，只需维护一个 Key，就能在 Harness 里按任务切换 DeepSeek、Claude 或 GPT 等不同系列模型，省去在多个海外及国内平台分别注册和绑卡的繁琐。
• 链路稳定与降低中断率：Agent 循环（Agent Loop）和插件安装常涉及连续多轮的 Tool Calling，国内网络直连中转节点能减少跨国网络抖动引起的请求超时。
• 用量与成本边界可控：子 Agent 和定时任务插件会在后台持续消耗 Token，通过中转站后台可以集中查看调用明细并设置额度上限，避免单日账单意外超支。

具体配置步骤：

1. 进入 「设置 → 模型 → 添加自定义模型 API」。
2. 填写基础信息：

• Provider ID（提供商标识）：自定义填写，例如 4sapi。
• 基础 URL（Base URL）：填入服务商控制台提供的 API 地址（注意通常以 /v1 结尾，不要把 /chat/completions 等具体路径填进去，以免拼接报错）。
• 协议选择：根据要调用的主力模型，在下拉框中选择 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages。
• API Key：填入在 4SAPI 控制台生成的令牌密钥。

1. 同步模型列表：点击下方的 「获取可用模型」 按钮，系统会自动拉取该接口支持的所有模型，勾选日常需要的模型后保存即可立即使用。

方式一：图形界面「插件管理」直接安装

这是最适合日常办公和普通用户的装法，全程不需要打开终端或修改 YAML 配置文件。

1. 开启官方实验性插件：

打开桌面版左侧边栏的 「插件」 页面（或进入「设置 → 插件」），可以看到官方内置的插件列表。除了默认开启的终端、Agent 循环和子 Agent 外，可以根据需求直接勾选开启 定时任务、Agent 团队、自动授权审核、语音输入 等实验性插件。

1. 安装外部 npm 插件包：

在插件管理页面的添加入口中，直接输入社区已发布到 npm 的插件包名（例如记忆管理插件 dsh-memory 或社区整理的工具包），点击安装即可。

1. 日常管理：

已安装的插件会在页面中显示运行状态（运行中、已停用或加载失败），支持在界面上一键启停、卸载或查看来源信息。

方式二：「创造模式」对话式安装与自建插件

DeepSeek Harness 内置了「极简、标准、PTC、创造」四种 Agent 预设模式。其中 「创造模式（Creator Mode）」 自带运行时检查工具、plugin_manager 插件管理工具以及完整的 Cordis 插件开发指引。你可以直接用一句话让 AI 帮你装好现成插件，或者现场写一个新插件。

1. 切换到创造模式：

先在左下角选择好项目工作区，点击左上角新建会话，在模式切换菜单中选择 「创造模式」。

1. 发送安装或开发指令：

• 安装现成插件：直接把插件的 npm 包名或 GitHub 仓库地址发给它，例如输入：帮我安装并启用 github:webkong/dsh-plugin-manager 插件，并确认是否加载成功。
• 现场编写新插件：如果你觉得现有界面缺少某项顺手的功能，可以直接提需求。例如使用官方示例提示词：帮我写一个 DSH 插件，在侧栏增加「项目笔记」入口，列出当前工作区的 Markdown 文件，点击后能预览内容。完成安装并验证页面能打开。

1. 确认权限弹窗：

Agent 调用 plugin_manager 修改配置层时，每一步操作都需要 danger-full-access 权限。界面弹出授权询问时，检查执行内容无误后点击单次批准（单次批准不会改变当前会话的默认安全模式）。完成后，插件会直接写入当前 Profile 并对后续会话生效。

方式三：命令行 dsh plugin add 与本地挂载

当你需要安装未发布到 npm 的 GitHub 源码仓库、第三方提供的 .tgz 离线包，或者自己手写插件调试时，使用命令行最为直接可控。

1. 安装不同来源的插件包

打开终端，通过 --profile 指定目标环境后执行 add 命令（命令底层会转发给对应 Profile 目录下的 pnpm 处理）：

# 1. 安装已发布到 npm 的预构建插件
dsh plugin --profile web add dsh-hello-plugin

# 2. 安装本地打包好的 .tgz 离线包
dsh plugin --profile web add ./powercontext-dsh-0.0.2.tgz

# 3. 从 GitHub 仓库直接拉取安装
dsh plugin --profile web add github:webkong/dsh-plugin-manager#main

# 4. 挂载本地正在开发的插件目录（注意：必须在插件文件夹的父目录执行）
dsh plugin --profile web add ./my-local-plugin

> 避坑提醒：挂载本地插件目录时，切记不要先 cd 进插件目录再执行 add ./my-local-plugin，否则路径解析会多嵌套一层导致启动报错 cannot resolve profile bundle，务必在插件的上一级父目录执行命令。

2. 验证配置树与卸载

安装完成后，插件包名会自动写入 $DSH_HOME/profiles/<profile>/package.json 的 dsh.profile.bundles 列表中。重启客户端前，可以用以下命令打印合并后的配置树，确认插件是否已挂上：

# 打印组合后的配置树，检查输出中是否包含新插件的 id
dsh --profile web --dump-config

# 卸载不再需要的插件
dsh plugin --profile web remove <插件包名>

得益于 Cordis 框架的“可逆副作用（Reversible Effects）”机制，卸载插件后，它注册过的工具、事件监听和界面入口会自动清理干净，不会在主程序里残留僵尸状态。

装插件前必须知道的安全边界

与浏览器的沙盒扩展不同，DeepSeek Harness 的插件与主程序之间没有进程隔离。插件会直接加载进同一棵 Cordis 运行树，与宿主共享操作系统用户权限、工作区文件以及模型 API 凭据。

在安装社区第三方插件前，建议按以下四点做基础排查：

1. 检查挂载的扩展点：如果插件接入了 tools/pre-execute（可拦截或查看每次工具调用）、agent/pre-step（可读取对话消息）或 webServer.tapIndex（可重写前端页面），务必先确认其源码可信。
2. 排查异常外发请求：在插件源码中搜索 fetch 或 http，警惕将本地提示词、代码片段或使用习惯暗中发往外部未知服务器的插件（尤其是打着“免费模型”旗号的可疑插件）。
3. 核对凭据读取行为：任何访问 credentials.* 或读取 API Key 的插件，都应当在说明文档中给出合理用途解释。
4. 注意卸载后的数据残留：卸载插件只会移除代码和运行时挂载项，插件在运行期间生成的本地文件（例如保存在 $DSH_HOME/memory/memory.db 的数据库或 .dsh/rules.yaml）仍会保留在磁盘上，需要彻底清理时请手动删除对应文件。

常见问题

安装 GitHub 源码插件时失败，提示构建脚本被拦截怎么办？

这是因为底层依赖的 pnpm（v10 及以上版本）默认拒绝自动执行 Git 依赖包里的 prepare 构建脚本。报错时终端会打印出对应的包键名，只需打开该 Profile 下的 pnpm-workspace.yaml 文件，手动添加构建授权后再重新执行 add 即可：

allowBuilds:
  插件包名: true

提示插件版本与当前 Harness 运行时不兼容怎么办？

新版加入了前置版本校验，若插件声明的运行时版本与当前桌面版不一致，会在下载前直接拦截。如确认插件可用，可通过命令行添加一次性版本豁免（写入 compatibility.json）：
dsh plugin --profile web allow-version <包名@版本> --dsh-version <当前版本号> --accept-risk。

修改插件的自定义配置（cordis.patch.yml）为什么把默认配置冲掉了？

DeepSeek Harness 的配置按层叠加，但自定义 cordis.patch.yml 对目标插件的 config 是整行替换而非深层合并。因此，在覆盖某个插件的配置项时，需要将该插件原本需要保留的其他默认字段一并写上，只写单个字段会导致其余配置被清空。

DeepSeek Harness 将 Agent 的所有能力拆解成了可插拔的积木：普通用户用图形界面和「创造模式」就能在几分钟内扩展出自己的工作台，开发者则能通过 dsh plugin 命令行深度定制工作流。在实际使用中，建议先在独立测试目录中跑通插件，并搭配官方 API 或额度可控的 4SAPI 等中转服务来管理多模型调用，在保证本地文件安全的前提下发挥 Agent 的自动化能力。