Windows 从零装一个自己的 DeepSeek Harness：安装、配置、插件与踩坑

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

先说清楚它是什么，不然装完也不知道拿它干嘛。

DeepSeek Harness（命令行叫 dsh）是 DeepSeek 开源的智能体框架，MIT 协议，官方自己的说法是「一切皆插件」，底层跑在 Cordis 上。你可以把它理解成一个装在你自己电脑上的、能读写文件、能跑命令、能自己拆任务的 AI 编程助手——和网页版对话的区别是：它真的会动你的文件。

我用了几个月，最直观的感受是：IDE 插件是「你写，它补」；dsh 是「你说，它做，你审」。

这篇写给 Windows 用户，从下载到配好第一个插件，全程不跳步。

说明：下面涉及版本、端口、配置路径的内容，以我本机实测（v44.x 桌面版）为准。这个项目还处在开发者预览阶段，官方明确写了会有破坏性变更，看到和本文不一致的地方，以官方文档为准。

一、装之前，先确认这三件事

1. 系统：Windows 10 1809 以上 / Windows 11。老版本 Win10 的 WebView 组件可能缺东西，能升级就先升。

2. 磁盘：桌面客户端装完占 200MB 上下；如果用 npm 路线，加上 node_modules 大概 1–2GB。留 5GB 空间不慌。

3. 网络：第一次启动要拉依赖、要连模型 API。公司网络挂代理的话，先把 HTTP_PROXY / HTTPS_PROXY 配好，不然会卡在「转圈」上，看起来像卡死，其实是在等网络。

如果你只是想“用起来”，跳第二节的 A 路线，五分钟能跑通。如果你想改代码、写插件，走 B 路线。

二、路线 A：桌面客户端（推荐给第一次用的人）

下载地址：官网下载页 DeepSeek | 下载 DeepSeek ，里面选 Windows 版。装的时候一路下一步即可。

装完打开，你会看到一个 Web 界面（对，桌面版本质是把 Web UI 包在 Electron 里，所以两边的操作完全一样）。

接着做三件事，缺一不可：

1. 配模型

左上角设置 → 模型，找到 DeepSeek 那张卡片，把 API Key 粘进去（Key 在 DeepSeek 申请）。保存后不用重启，下一个请求就生效。

Key 存在哪？存在 %USERPROFILE%\\.dsh\\.credentials.yaml 里，页面本身只会拿到脱敏的描述符，不会回显明文——这点做得比很多工具讲究。

2. 选工作区

点选择工作区，把你要让它干活的那个项目文件夹加进来。没选工作区，输入框是灰的，这是新手第一个卡点，很多人以为是 bug。

工作区就是它能碰的范围。它看不到工作区以外的文件，这是设计如此，不是权限没配好。

3. 发第一个任务

选好工作区，直接发一句：

读一下这个目录，告诉我这是做什么的项目，主要入口文件在哪

它会自己列目录、读文件、给结论。第一次跑的时候留意状态栏——它每调一次工具都会显示，这个习惯后面排查问题很有用。

三、路线 B：npm 路线（想改代码、写插件选这个）

前提：装 Node.js（建议 20 LTS 以上），装了之后在 PowerShell 里验证一下：

node -v
npm -v

然后一条命令启动：

npx @deepseek-ai/dsh web

默认会在 http://127.0.0.1:3080 起服务，并且自动打开浏览器。不想让它自动开就加 –no-open：

npx @deepseek-ai/dsh web –no-open

想从源码跑（写插件基本都得这样）：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

注意 pnpm run build 只是准备产物，pnpm dsh web 会直接用现成的产物，不会再编译——别以为它卡住了。

四、配置文件到底在哪（这条最有用）

装完先记住三个路径，后面所有“改了不生效”的问题都能从这儿查：

第三行那个 cordis.patch.yml 是关键：模型页里填的东西，最后都落在这个文件里。它在界面上有入口——设置页顶部有「打开配置文件」，浏览器和服务器在同一台机器时能直接点开。

改完不用重启，适配器下一次请求会重新读。

五、装好之后，先玩这三个能力

1. 技能（SKILL.md）

一个技能就是一个文件夹，里面放一个 SKILL.md，写上“什么时候该用我、分几步做、输出什么格式”。放进技能目录后，它在合适的时机自己会被调用，你不用每次重新解释流程。

这东西的价值在于把重复的活固化成流程。比如「每周拉一次上周的提交，按人统计，写成本周周报」，写一次，之后一句话触发。

2. 子代理

让它拆出去一个小助手干杂活：搜资料、读一堆文件、跑一组测试。主对话不会被中间过程刷屏，你只看结果。长任务特别有用。

3. 权限与计划模式

它对文件动手之前，会按当前权限策略问你。这个东西别关——第一次用的人最容易嫌它烦，然后把审批全关了，结果它一个 rm -rf 你就笑不出来了。

计划模式则是先给方案、你点头再执行，适合“我不确定它理解对没有”的时候。

六、插件：这里的门槛比想象中低

官方的定位是「一切皆插件」，所以插件不是外挂，是给它加器官。

一个最小插件就是一个 TypeScript 文件，导出一个 apply 函数：

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
console.log('[hello-plugin] loaded!')
}

就这么多。想让它注册一个能调用的工具，声明依赖再调 ctx.tools.register()：

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

export const name = 'my-tool-plugin'
export const inject = ['tools'] // 声明我要用 tools 服务，框架会等它就绪

export function apply(ctx: Context) {
ctx.tools.register(/* 工具定义 */)
}

插件是函数、对象、类三种写法都行，绝大多数场景函数写法够了；只有当你要给别的插件提供服务时，才需要类写法。

怎么加载进去？ 用一个 cordis.yml 覆盖层，用 insert 插进去：

– insert:
– id: hello
name: 'D:/path/to/my-plugin.ts' # 必须是绝对路径

然后带着它启动：

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

启动时终端会打印 [hello-plugin] loaded!，看到这句就成功了。

顺带一个我很喜欢的设计：通过 ctx 注册的东西（事件、工具、定时器）在插件卸载时会自动清理，不用手动 removeListener。需要自己收尾的资源用 ctx.effect() 返回一个清理函数就行。

七、去哪找插件（地址都在这）

官方自己不打“插件商店”这个牌子，社区约定是给仓库打 dsh-plugin 话题，所以：

最主要的入口，就这一个：

• dsh-plugin · GitHub Topics · GitHub

按 star 排序，或者按最近更新排序（我更建议看最近更新，这个项目迭代快，三个月没动的插件大概率装不上）。

其他几个有用的地址：

社区里能看到的两类补充（都是第三方，星标不多，装之前请自己读一遍代码）：

• BrokenDreamStar/dsh-skills-mcp —— 给 dsh 加 skills 和 MCP 管理界面：GitHub – BrokenDreamStar/dsh-skills-mcp: 为deepseek harness添加skills和mcp管理功能 · GitHub
• @zebbkira/dsh-skills-mcp-manager —— 同类思路的 npm 包：https://www.npmjs.com/package/@zebbkira/dsh-skills-mcp-manager

这两类插件存在的根本原因值得单独说一句：dsh 本体没有原生的 MCP 添加入口。讨论区里就有人专门开了帖问这件事（Discussion #1754）。所以如果你手上一堆 MCP server 想接进来，要么等官方，要么用上面这类社区插件桥接——别在设置里翻半天找不到，那是真的没有。

提醒：插件跑在你的机器上，权限和你一样大。装之前至少看一眼有没有 child_process / 网络请求 / 读 \\.ssh 之类的东西。这不是危言耸听，是这类工具的通病。

八、Windows 上最容易卡住的五个地方

1. npx 报「无法加载文件，因为在此系统上禁止运行脚本」

PowerShell 的执行策略问题。用管理员身份开一个 PowerShell，执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2. 路径里有中文或空格

你的项目在 D:\\我的 项目\\ 这种路径下，某些工具链会解析出错。要么把项目挪到纯英文路径，要么所有路径都加引号。这跟 dsh 关系不大，是 Windows 生态的老毛病。

3. 端口 3080 被占用

启动报 EADDRINUSE。先看是谁占的：

netstat -ano | findstr :3080

拿到 PID 后 taskkill /PID <pid> /F，或者干脆换个端口启动。

4. 中文乱码

Windows 默认代码页是 GBK，输出中文容易变问号。在启动脚本里加一句：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONIOENCODING = "utf-8"

5. 装完接口调不通，一直转圈

九成是网络。先确认 HTTPS_PROXY 有没有配、代理软件是不是拦了 127.0.0.1（很多代理默认不走本地回环，加个例外）。别急着怀疑软件坏了。

九、最后说两句实话

第一，它不会让你不用学编程。 它把「我知道要做什么，但懒得敲」这段省掉了；「我不知道要做什么」这段，它帮不了你，甚至会给你一堆看起来很对的错误方案。

第二，先把权限管住。 新手最容易犯的错是把审批全关掉图省事。它确实会更快，但出错的时候也更快——而且是在你的真实文件上。

第三，插件别贪多。 每装一个就多一份别人代码在你机器上的执行权，也多了下次升级时的一份不兼容风险。先只用官方的能力，等真的觉得“这里缺个东西”了，再去 topics 里找。

装完之后建议的第一件事：找一个你自己的小项目，让它读一遍、写个 README。这件事不涉及写代码，但能让你完整看到它“读—想—写—验”的全过程，比任何教程都直观。

参考链接汇总

• DeepSeek Harness 主仓库：GitHub – deepseek-ai/deepseek-harness: DeepSeek Harness: Everything is a Plugin. · GitHub
• 官方文档：DeepSeek Harness
• 插件话题页：dsh-plugin · GitHub Topics · GitHub
• 讨论区：deepseek-ai/deepseek-harness · Discussions · GitHub
• 插件开发教程：第一个插件 | DeepSeek Harness
• 下载页：DeepSeek | 下载 DeepSeek
• DeepSeek 开放平台：DeepSeek