DeepSeek Harness 桌面版怎么安装插件？三种方式完整指南

发布日期：2026-10-27 ｜数据截至 2026-10-27，来源为 deepseek-ai/deepseek-harness 官方 GitHub 仓库（v0.2.1-rc.2）

DeepSeek Harness（dsh）的核心设计理念是「Everything is a Plugin」——桌面版本身就是一个插件运行容器，所有扩展能力都通过插件挂载进来。桌面版安装插件有三种路径：一是在应用内 Settings → Plugins 页面直接搜索安装；二是完全退出桌面版后用命令行执行 dsh plugin --profile desktop add <package>，重启生效；三是通过 cordis.yml 补丁文件加载本地开发中的插件。三种方式适用场景不同，本文逐一说清楚，并附一个目前 GitHub 上最受欢迎的社区插件——dsh-our-free-model（44,000+ Star）——的安装和使用方法。

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

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

给桌面版装的插件不会影响 Web 版，反之亦然
命令行操作桌面版插件时必须加 --profile desktop 参数
桌面版需要先启动一次完成 profile 初始化，才能通过命令行管理插件

$DSH_HOME 默认是 ~/.dsh/。

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

这是最直接的方式，不需要命令行。

打开 DeepSeek Harness 桌面版
点击左侧导航的 Settings
进入 Plugins 页面
搜索插件包名（如 dsh-our-free-model）或浏览推荐列表
点击 Install，等待安装完成
部分插件安装后需要重启应用才能生效，设置页会有提示

设置页的 Plugins 页面使用 dsh 内置的 Web Plugin Manager，底层同样调用桌面版自带的 pnpm，不需要系统里单独安装 pnpm。

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

如果你已通过桌面版菜单 Manage dsh Command → Install 注册了 dsh 命令，可以用命令行管理桌面版插件。

重要：命令行操作桌面版插件时，必须先完全退出桌面应用（不只是关窗口——macOS 要退出进程，Windows 要从托盘右键退出），否则会发生进程锁冲突。

# 安装插件
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 clone 下来但没有发布到 npm 的插件，使用 cordis.yml 补丁文件。

注意：这种方式适用于从源码运行的 Web 模式（pnpm dsh web），不直接适用于已安装的桌面版二进制。桌面版开发调试场景通常通过修改 profile patch 文件实现。

创建 my-plugin-patch.yml：

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

启动时附加补丁：

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

插件路径必须是绝对路径。插件在 apply 函数里通过 ctx 注册能力（工具、服务、路由等），框架会在所有声明的依赖就绪后再调用 apply。

插件的基本结构

dsh 插件是导出 apply 函数的 TypeScript 模块，格式极简：

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——免费用 DeepSeek 和 Kimi

GitHub 上目前最受欢迎的 dsh 社区插件是 dsh-our-free-model（44,000+ Star，曾登 GitHub Trending JavaScript 周榜第一）。这个插件的核心卖点是：装上即用，无需 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 热力图、输出速度、首字延迟，数据全部留在本机
OpenAI 兼容本地转发端口：让其他工具（如 Claude Code）通过 base URL 调用这些免费模型
思考强度真实生效：DeepSeek V4.1 Flash 等支持 Off/Low/High/Max 档，按真实 reasoning_effort 下发
路由降级链：多个模型串成命名链，一个失败自动切换下一个
聚合渠道：内置 76 家提供商注册表（SiliconFlow、Kimi、MiniMax、Groq 等），填入 Key 后模型出现在同一选择器

免责提示：Kilo 免费池的模型上游可能记录 prompt 用于改善服务，勿发送敏感内容。

发现更多社区插件

在 GitHub 搜索带有 dsh-plugin 话题的仓库：

https://github.com/topics/dsh-plugin

也可以在官方 Discord 社区（discord.gg/4MrtZUhpxg）和 dsh GitHub Discussions 里找到其他开发者分享的插件。

给自己的插件仓库打上 dsh-plugin 话题可以提升可发现性。

常见问题

Q：桌面版和 Web 版能共用同一个插件吗？ 不能直接共用——两者 profile 独立。同一个 npm 包可以分别安装到两个 profile，但配置和状态是各自隔离的。

Q：命令行安装插件报错"profile 未初始化"怎么办？ 先启动一次桌面版完成初始化，然后完全退出再用命令行操作。桌面版必须至少启动过一次，$DSH_HOME/profiles/desktop 目录才存在。

Q：安装后插件没有出现，怎么排查？ 检查 Settings → Plugins 页面是否有错误提示；部分插件需要重启应用；如果桌面版崩溃启动，可以在原生恢复对话框选择「禁用第三方插件并重启」来排除问题插件。

Q：自制插件能发布到 npm 让别人安装吗？ 可以。发布为普通 npm 包，在 package.json 里加上 dsh-plugin 关键词和 GitHub 话题，用户就能通过 dsh plugin add <your-package> 安装。

总结

dsh 桌面版安装插件有三种方式：Settings → Plugins 页面（新手推荐）、dsh plugin --profile desktop add <package> 命令行（需先完全退出桌面版）、--patch 补丁文件（开发者调试）。桌面版与 Web 版 profile 完全隔离，命令行操作必须加 --profile desktop。目前社区最活跃的插件是 dsh-our-free-model，提供免配置的免费模型通道、用量看板和 OpenAI 兼容本地网关，适合想快速体验 dsh 插件生态的用户。