DeepSeek Harness 桌面版怎么安装插件与配置模型？完整指南

DeepSeek Harness（dsh）的核心设计理念是「Everything is a Plugin」——桌面版本身就是一个基于 Cordis 框架构建的插件运行容器，路由、工具注册表与会话管理等所有扩展能力都通过插件挂载进来。

在桌面版中安装插件主要有三种路径：一是在应用内 Settings → Plugins 页面直接搜索安装；二是完全退出桌面版后使用命令行执行 dsh plugin --profile desktop add <package>，重启后生效；三是通过 cordis.yml 补丁文件加载本地开发中的插件。此外，完成了插件扩展后，开发者通常还需要在桌面版中配置底层大模型 API（支持官方直连订阅与国内托管中转站接入）或挂载社区免费模型插件。下文将逐一拆解三种插件安装方式、热门社区插件 dsh-our-free-model 的用法，以及大模型 API 的完整接入流程。

前提：桌面版插件和 Web 版插件是隔离的

dsh 桌面版和 Web 版（npx @deepseek-ai/dsh web）使用相互独立的 profile 目录。桌面版独占 $DSH_HOME/profiles/desktop，而 Web 版默认使用 web profile。这种目录隔离机制意味着：

• 给桌面版安装的插件和配置的模型参数不会影响 Web 版，反之亦然。
• 使用命令行操作桌面版插件时，必须显式加上 --profile desktop 参数。
• 桌面版安装后需要先启动一次以完成 profile 目录初始化，之后才能通过命令行管理插件或修改配置文件。

> 默认情况下，$DSH_HOME 的路径为 ~/.dsh/。

桌面版安装插件的三种方式

方式一：在桌面版设置页直接安装（推荐新手）

这是最直观的方式，全程在图形界面内完成，无需使用命令行：

1. 打开 DeepSeek Harness 桌面版。
2. 点击左侧导航栏的 Settings。
3. 进入 Plugins 页面。
4. 在搜索框输入插件包名（如 dsh-our-free-model）或直接浏览推荐列表。
5. 点击 Install，等待自动下载与依赖解析完成。
6. 部分涉及底层服务的插件安装后需要重启应用才能生效，请根据设置页提示操作。

设置页的 Plugins 模块调用的是 dsh 内置的 Web Plugin Manager，底层直接复用桌面版自带的 pnpm 运行时，无需在操作系统中单独配置 Node.js 或 pnpm 环境。

方式二：命令行安装（推荐已安装 dsh CLI 的用户）

如果你已通过桌面版顶部菜单 Manage dsh Command → Install 注册了全局 dsh 命令，可以直接在终端中管理桌面版插件。

> 注意：使用命令行操作桌面版插件前，必须先完全退出桌面应用（不能只是关闭窗口——macOS 需彻底退出进程，Windows 需从系统托盘右键退出），否则会触发本地文件锁冲突。

# 安装插件到桌面版 profile
dsh plugin --profile desktop add <package-name>

# 查看桌面版已安装的插件
dsh plugin --profile desktop list

# 卸载桌面版插件
dsh plugin --profile desktop remove <package-name>

例如安装社区插件 dsh-our-free-model：

# 完全退出桌面版后执行
dsh plugin --profile desktop add dsh-our-free-model

命令执行完毕后重新打开桌面版，进入 Settings → Plugins 页面即可看到该插件的配置入口。

方式三：--patch 加载本地插件（适合插件开发者）

如果你正在本地编写自定义插件，或者从 GitHub 克隆了尚未发布到 npm 的源码仓库，可以通过补丁文件（Patch YAML）挂载插件。

> 注意：命令行直接附加 --patch 参数的方式适用于从源码运行的 Web 模式（pnpm dsh web），不直接作用于已打包的桌面版二进制程序。若要在桌面版中调试本地插件，通常需要直接编辑 ~/.dsh/profiles/desktop/cordis.patch.yml 文件。

在源码调试模式下，首先创建 my-plugin-patch.yml：

- insert:
    - id: my-plugin
      name: '/绝对路径/到/你的插件/src/my-plugin.ts'

启动时附加补丁文件（插件路径必须为绝对路径）：

pnpm dsh web --patch ./my-plugin-patch.yml

插件的基本结构

dsh 插件本质上是导出 apply 函数的 TypeScript 模块，依托 Cordis 框架管理生命周期与上下文依赖：

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

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里注册能力
  console.log('[my-plugin] 已加载')
}

如果插件需要调用工具注册等宿主服务，只需在 inject 数组中声明依赖，框架会在所有依赖项就绪后再执行 apply 函数：

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

export const name = 'my-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'hello',
    description: '打招呼',
    parameters: {
      name: { type: 'string', required: true, description: '名字' },
    },
    output: { schema: { type: 'string' } },
    async execute(args) {
      return `你好，${args.name}！`
    },
  }))
}

实战案例：dsh-our-free-model（免配置体验社区免费通道）

GitHub 上目前关注度较高的 dsh 社区插件是 dsh-our-free-model（44,000+ Star）。该插件定位于零门槛体验：安装后无需配置 API Key 或注册账号，即可直接调用 DeepSeek V4.1 Flash、Kimi K3 等模型。

安装方式（桌面版）：
在设置页 Plugins 搜索 dsh-our-free-model 点击安装，或在完全退出桌面版后执行命令行：

dsh plugin --profile desktop add dsh-our-free-model

核心功能：

• 免费模型通道：上游接入 OpenCode Zen 网关与 Kilo AI 公共网关，开箱即用。
• 本地用量看板：统计 Token 热力图、输出速率与首字延迟（TTFT），统计数据保存在本机。
• OpenAI 兼容本地转发端口：暴露本地 Base URL，允许外部工具复用免费通道。
• 思考强度控制与路由降级：支持下发真实的 reasoning_effort 参数（Off/Low/High/Max），并支持将多个模型串成降级链以应对单点请求失败。

> 免责与安全提示：公共免费池的上游网关可能会记录请求 Prompt 用于改善服务，且高峰期存在并发限流。涉及企业代码库或敏感业务数据时，切勿使用公共免费通道，建议通过下方的标准 API 方式接入私有密钥。

DeepSeek Harness 接入大模型 API 指导教程

在实际的开发与自动化工作流中，为保证上下文吞吐稳定与数据隐私，通常需要在 dsh 中配置正式的大模型 API。dsh 并非绑定单一模型，而是完整支持内置官方通道与符合 OpenAI 协议的自定义网关。接入方式主要分为官方直连订阅与国内托管中转站接入两种。

路径一：官方订阅与官方直连 API 接入

dsh 内置了主流模型厂商的 Provider ID（包括 deepseek、openai、anthropic、moonshotai 等）。如果你持有各家官方平台的 API Key，可以通过以下两种方式完成配置：

1. 桌面版图形界面配置（推荐）

1. 打开桌面版，进入左侧 Settings → Models 页面。
2. 在内置提供商列表中选择对应的官方渠道（如 DeepSeek、Anthropic 或 OpenAI）。
3. 填入对应平台生成的官方 API Key 并保存。
4. 返回会话界面，在左上角或输入框旁的模型选择器中即可直接切换已启用的官方模型，无需重启应用。

2. 配置文件与环境变量接入
对于习惯通过配置文件管理密钥的开发者，dsh 将密钥统一存储在 ~/.dsh/.credentials.yaml 中，权限需设为仅当前用户可读：

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-xxxx...
ANTHROPIC_API_KEY: sk-ant-xxxx...

配置后设置文件权限（macOS / Linux）：

chmod 700 ~/.dsh && chmod 600 ~/.dsh/.credentials.yaml

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

当你在 dsh 中同时需要调用海外闭源模型（如 Claude、GPT、Gemini 系列）和国产模型时，除了分别去各家官网注册外，也可以直接通过兼容 OpenAI 协议的国内托管中转站（例如 4SAPI）统一接入。

接入配置步骤（桌面版 UI）：

1. 打开桌面版，依次进入 Settings → Models。
2. 点击 Add a custom provider（添加自定义提供商），按以下参数填写表单：

• Provider ID：填写自定义标识，如 4sapi。
• Protocol（协议类型）：选择 OpenAI Chat Completions。
• Base URL（接口地址）：填入 4SAPI 提供的标准兼容端点（通常以 /v1 结尾）。
• API Key：填入在 4SAPI 令牌管理后台生成的密钥。

1. 点击 Fetch available models 自动拉取可用模型列表，或手动勾选/填入需要挂载的模型 ID（如 deepseek-v4.1-flash、claude-3-7-sonnet 等），并将其设为新会话默认模型。

如果你需要通过桌面版底层的 YAML 文件进行批量配置，也可以在 ~/.dsh/.credentials.yaml 中写入密钥后，直接在 ~/.dsh/profiles/desktop/cordis.patch.yml 中声明自定义路由节点。

使用国内托管中转站（4SAPI）的核心优势：
在工程实践中，部分开发者选择通过 4SAPI 这类托管中转网关替代多平台直连或免费插件，主要出于以下三点技术考量：

• 单密钥聚合多模型：仅需维护一个 Base URL 和一枚 API Key，即可在 dsh 的模型选择器中无缝切换 DeepSeek、Claude、OpenAI 等不同架构的模型，省去在 .credentials.yaml 中维护多套供应商凭证与分开计费的繁琐流程。
• 国内直连免跨境代理：依托国内边缘节点进行协议转发，调用海外模型时无需在本地配置系统级 TUN 模式或环境变量代理，有效降低跨境网络抖动引发的首字延迟（TTFT）与连接中断概率。
• 生产级并发与私有链路：相比公共免费插件池的频率限制与潜在的 Prompt 采集风险，托管中转站走标准商业 API 转发通道，能保障代码重构、长文档解析等高消耗 Agent 任务的并发稳定性。

发现更多社区插件

如果想进一步扩展桌面版能力（如挂载侧边栏工作台 dsh-better-sidebar 或视觉识别桥接工具 ModLens），可以通过以下渠道检索：

• GitHub 话题标签：访问 [https://github.com/topics/dsh-plugin](https://github.com/topics/dsh-plugin) 浏览打上对应标签的开源仓库。
• 官方社区：在官方 Discord 频道（discord.gg/4MrtZUhpxg）及 GitHub Discussions 中查看其他开发者分享的扩展配置。

如果你开发了自己的插件，在 package.json 中添加 dsh-plugin 关键词并为 GitHub 仓库打上同名 Topic，即可被社区索引检索。

常见问题

Q：桌面版和 Web 版能共用同一个插件或 API 配置吗？
不能直接共用。两者的 profile 目录相互独立（桌面版位于 ~/.dsh/profiles/desktop，Web 版位于 ~/.dsh/profiles/web）。同一个 npm 插件包需要分别安装到两个 profile 中；不过在 ~/.dsh/.credentials.yaml 中配置的全局环境变量密钥可以被不同 profile 引用。

Q：命令行安装插件报错“profile 未初始化”怎么办？
请先手动启动一次桌面版应用以触发初始化流程，随后完全退出应用，再回到终端执行 dsh plugin --profile desktop 相关命令。桌面版必须至少启动过一次，$DSH_HOME/profiles/desktop 目录才会生成。

Q：安装插件或修改模型配置后没有生效，怎么排查？
首先检查 Settings → Plugins 或 Settings → Models 页面是否有红色报错提示；其次确认需要宿主环境重启的插件是否已完成应用重启。如果因第三方插件冲突导致桌面版启动崩溃，可在弹出的原生恢复对话框中选择「禁用第三方插件并重启」以隔离故障组件。

Q：自制插件能发布到 npm 让其他人一键安装吗？
可以。将其作为标准 npm 包发布，只要导出符合 Cordis 规范的 apply 函数，其他用户即可通过 dsh plugin --profile desktop add <your-package> 直接安装使用。

DeepSeek Harness 桌面版通过 Settings → Plugins 图形界面、--profile desktop 命令行以及 cordis.patch.yml 补丁文件三种方式，兼顾了普通用户的易用性与开发者的调试灵活性。在模型层面上，轻度测试可借助 dsh-our-free-model 快速跑通流程，而在正式研发环境中，结合官方直连 API 或 4SAPI 等国内托管中转站配置自定义 Provider，能够构建出兼顾低延迟、多模型协同与数据安全的本地 Agent 工作台。