1. 为什么 Windows 上跑 DSH 这么费劲以及我选择封装工具包的直接原因1.1 DSH 到底是干嘛的DSH 的全称是 DeepSeek Harness。按我的理解它是一个给大模型提供干活框架的命令行工具模型在终端里接到任务后不是只停在对话框里给建议而是真的调用你本地的文件系统、命令行工具和插件体系去把任务做掉。类似形态的工具这两年冒出来不少Codex Harness 就是同一个赛道里的知名产品。DSH 和它的区别在于DSH 更强调模型接口的开放性、插件组装自由度和本地部署的灵活性。你可以把它接到 DeepSeek 的接口上跑日常编码任务也可以通过配置挂上一堆插件实现文档检索、自动化测试、批量数据处理这些扩展能力。我第一次接触 DSH 是在 Linux 服务器上一条管道命令装完就能直接用体验非常顺。后来想在 Windows 笔记本上同样配一套结果发现网上教程不少但真正能从头跑到尾的没几篇。这个工具本身不复杂问题几乎全出在环境适配这一层。所以这篇文章除了把安装过程完整捋一遍之外还会把高频报错的排查链路写清楚尤其是 Windows 特有的权限问题——这些内容在官方文档里基本找不到。1.2 Windows 环境的三个老大难结合我自己踩坑的经历和社区里铺天盖地的提问Windows 版本装 DSH 的障碍集中在三个方面。第一是环境依赖不一致。DSH 的安装脚本和插件生态默认面向 POSIX 环境很多路径处理、权限调用都是 Linux 风格。Windows 虽然有 Git Bash、WSL、PowerShell 这些兼容层但官方脚本不会替你做判断装到一半发现缺 Git、缺 Node.js、缺 PowerShell 模块都是家常便饭。第二是命令分发机制不一样。在 Linux 里装好工具软链接一放全局命令就有了。Windows 则要处理 PATH 变量、可执行文件扩展名、符号链接权限这些细节。任何一个环节出问题你就会撞上那句无比熟悉的提示dsh 不是内部或外部命令也不是可运行的程序或批处理文件。第三是权限模型差异。Windows 的 ACL 权限系统比 Unix 的 755 权限要复杂得多。很多工具在启动时会给自己的数据目录设置写入权限在 Unix 上是零成本操作到 Windows 上就可能触发 SetNamedSecurityInfoW 这类系统 API 的拒绝访问错误也就是社区里高频出现的 setnamedsecurityinfow failed (win32 5): grantwrite 报错。说白了DSH 本身不难用难在大部分资料都默认你是 Linux 用户。我最后决定把整个安装流程封装成 hsx-dsh-tools-v0.1.2 这个工具包原因也很直接让每个 Windows 用户都去跟脚本搏斗一遍太浪费生命了。环境探测、依赖查验、权限修复、启动器这些事本来就该一次性做好。2. hsx-dsh-tools-v0.1.2 的组成一键安装和双击启动是怎么实现的2.1 工具包里面装了什么先看目录结构你拿到压缩包解压之后应该是这样的hsx-dsh-tools-v0.1.2/ ├── install.bat # 一键安装入口双击后按提示操作 ├── start-dsh.bat # 双击启动入口日常使用就靠它 ├── uninstall.bat # 卸载脚本 ├── bin/ │ └── dsh.cmd # DSH 命令行启动包装器 ├── config/ │ ├── dsh.config.json # 主配置文件 │ └── profiles/ # profile 配置目录 ├── plugins/ # 插件目录 ├── scripts/ │ ├── check-env.ps1 # 环境检查脚本 │ ├── install-core.ps1 # 安装核心逻辑 │ ├── fix-acl.ps1 # Windows ACL 权限修复脚本 │ └── make-shortcut.ps1 # 创建快捷方式 └── logs/ # 安装与运行日志bin 目录放的是 dsh.cmd 而不是一个赤裸裸的 exe这个选择是有讲究的。DSH 核心本身是脚本产物一个 cmd 包装器能同时处理参数传递、临时环境变量注入、中文终端编码切换还能在出错时把窗口停住防止用户错过报错信息。这些都是裸 exe 不好做到的。2.2 安装脚本的工作流程install.bat 只是个入口真正的逻辑在 install-core.ps1 里。为什么这么拆分因为双击 .bat 是 cmd 环境下最稳的交互方式但要做系统检测、JSON 配置写入、ACL 修改这类操作PowerShell 能力强得多。所以 .bat 负责拉起 PowerShellPowerShell 负责干活。安装流程按这个顺序走权限检测。默认安装到当前用户目录不需要管理员权限但如果你选择创建开始菜单快捷方式脚本会在这一步自动弹出提权请求。环境预检。check-env.ps1 会逐项扫描系统版本、PowerShell、Git、Node.js以及可选的 Docker、Redis、Elasticsearch 组件。预检结果逐条打印缺失项直接告诉你该装什么。部署核心文件。默认复制到 %LOCALAPPDATA%\hsx-dsh-tools 目录不污染系统盘 Program Files。写入初始配置。生成 dsh.config.json 和一个默认 profile把数据目录指到用户目录下。权限修正。针对数据目录执行 fix-acl.ps1从根上避免后面出现 setnamedsecurityinfow 之类的 ACL 报错。创建快捷方式。如果用户同意生成DeepSeek Harness (DSH)的快捷方式到开始菜单和桌面。环境预检这一步我做成了一张便于对照的表检查项作用缺失时的提示Windows 10 21H2 / Windows 11旧系统缺少新版 API提示升级系统PowerShell 5.1安装脚本的运行时提示升级 PowerShellGit插件管理、版本相关命令依赖提示安装 GitNode.js 18DSH 核心运行时提示安装 Node.js LTSDocker Desktop容器类插件可选依赖仅警告不影响基础功能Redis / Elasticsearch检索与缓存类插件可选依赖仅警告按需安装2.3 为什么是双击启动而不是改全局 PATH这是工具包设计里最核心的一个取舍。传统思路是安装时用 setx 把 bin 目录写进系统 PATH一劳永逸。但我试过之后发现这条路在 Windows 上有四个坑第一setx 修改的 PATH 不会立刻作用于当前已打开的终端窗口用户经常要重启终端甚至重启电脑才能生效。第二Windows 的 PATH 变量有长度限制堆满 JDK、Python、Node 的机器上再追加新路径很容易顶满。第三全局 PATH 被工具包修改本质上是在污染系统环境以后卸载还会留下残留。第四为了让 dsh 命令可用你还得处理环境变量在子进程间的传递稍有不慎就会遇到找不到模块的怪问题。所以 start-dsh.bat 换了个思路启动时临时把 bin 目录和 Node.js 路径注入到当前会话的 PATH 里再拉起 dsh。这样做的好处是每次双击都能得到一个确定可用的环境不需要用户关心 PATH 到底配没配。代价是你在普通的 cmd 窗口里直接敲 dsh 还是不行但这对绝大多数用户来说根本不是问题——你不需要记住 dsh 有哪些参数直接双击启动进去了再说。启动器里还顺带做了两件小事一是chcp 65001 nul把终端切到 UTF-8避免中文乱码二是出错时停在窗口前提示按任意键关闭防止报错一闪而过。3. 跟着走一遍从解压到首个任务跑通3.1 安装前建议先做三件事第一次接触这套工具的人建议按这个顺序准备把压缩包解压到一个没有空格的路径比如 D:\hsx-dsh-tools。放在桌面或者带空格的文件夹里虽然大多数情况下没问题但某些插件脚本对空格路径处理不好能避免就避免。先看一眼系统版本Win10 21H2 以上或 Win11 最省心。真要用 Win10 老版本安装脚本会给出提示但别指望所有插件都能正常工作。如果机器上装了第三方杀毒软件安装第一遍建议临时关掉实时防护。脚本行为的误报率不低等确认安装成功后可以再开回来。3.2 一键安装过程实录双击 install.bat 后正常情况下你会看到类似下面的输出[hsx-dsh-tools] 正在检查系统环境... 操作系统: Windows 11 23H2 (build 22631) PowerShell: 7.4.2 Git: 2.44.0 Node.js: 20.11.1 Docker: 未安装不影响基础功能 环境检查完成。 [hsx-dsh-tools] 正在部署核心文件... 目标目录: C:\Users\你的用户名\AppData\Local\hsx-dsh-tools 配置文件: 已写入 数据目录: C:\Users\你的用户名\AppData\Local\hsx-dsh-tools\data [hsx-dsh-tools] 正在修复目录权限... 数据目录 ACL: OK [hsx-dsh-tools] 已创建开始菜单快捷方式: DeepSeek Harness (DSH) 安装完成双击桌面或开始菜单里的 DeepSeek Harness (DSH) 即可启动。如果你机器上有检查项显示缺失先补装对应依赖再重新运行 install.bat。特别注意 Node.js 版本DSH 对 Node 版本有一定要求装 LTS 版最稳。这里我不推荐用系统自带的包管理器去装 Node直接去官网下安装包更省事装完以后 PATH 是自动配好的不会埋雷。3.3 双击启动和首次认证安装完成后双击桌面上的DeepSeek Harness (DSH)快捷方式。第一次启动时由于还没有完成身份认证终端会打印类似下面的提示[DSH] 检测到未完成认证请打开以下地址完成登录 https://... 按 Enter 继续...把这段地址复制到浏览器打开登录你的模型服务账号按页面提示完成授权再回到终端按 Enter认证流程就算走完了。整个过程和我最早在 Linux 上遇到的一致只是 Windows 上多了一道代理判断的环节如果浏览器能正常打开登录页基本不会卡住。如果你在这个阶段看到的是 dsh web authentication required; reopen the url printed by dsh web.别慌这通常意味着上一次认证流程没走完或者是 token 过期了。解决办法很简单重新执行一次dsh web用新打印出来的 URL 走一遍授权不要拿旧地址硬刷。3.4 怎么判断装好了认证通过后在 DSH 交互界面里依次执行下面三条命令dsh --version dsh --help dsh plugin list三条都能正常输出就说明核心安装没问题。注意这里的用法是你在 DSH 交互环境里面执行命令不是在普通 cmd 窗口里直接敲。如果你是用 start-dsh.bat 启动的交互界面里直接输入--version或help这类子命令也行两种方式都支持。最后做个最简单的真实任务验证一下让它列出当前目录下所有 Python 文件并统计行数。能正确输出结果整个安装链路就算真正跑通了。4. 高频报错排查实录我踩过的坑都给你标好了4.1 dsh 不是内部或外部命令先分三种情况这个报错出现的概率最高但它背后的原因差别很大处理方式也不一样。第一种情况是你在普通 cmd 窗口里敲 dsh提示找不到命令。这是正常的因为工具包默认走的是双击启动路线没有改全局 PATH。解决办法是以后都用 start-dsh.bat 启动或者如果你确实需要全局命令行可用手动把C:\Users\你的用户名\AppData\Local\hsx-dsh-tools\bin加进系统 PATH 即可。第二种情况是你明明安装了但where dsh在系统里搜不到任何结果。这多半说明安装过程根本没走完或者被杀毒软件拦截了关键文件。去 logs 目录看安装日志找到出错的那一步重新跑一遍 install.bat。第三种情况有点隐蔽dsh.cmd 文件存在命令也能找到但执行时报错说找不到 node。这种情况通常是 Node.js 没有正确加入 PATH或者系统里有多个 Node 版本冲突。在启动器会话里检查一下node --version是否能正常输出不能的话就需要先修复 Node.js 的安装。4.2 plugin tree failed to load: failed to apply loader entry include这个报错我前前后后遇到过三次每次都是同一个原因插件树的 include 引用路径断裂了。DSH 加载插件的时候是按树状结构走的每个插件配置文件里可以声明多种 loader其中一种就是 include。include 的作用是把另一个插件或配置文件的路径引进来让它们组成一棵插件树。如果被引用的文件不存在了或者相对路径因为目录移动对不上了就会触发这条错误。排查链路建议按下面几步走打开 dsh.config.json确认 plugins 目录指向哪里。去 plugins 目录下找到报错插件的 manifest 文件一般是 dsh.plugin.json。逐个检查里面 include loader 写的相对路径确认目标文件真实存在。常见的一个问题是我之前把工具包解压到了别的目录里面的相对路径是按当时的目录结构写的搬家以后就全断了。手动修正路径后保存重启 DSH。举个例子下面这个 manifest 里的 include 就很容易出问题{ name: my-plugin, version: 0.1.0, loaders: [ { type: include, entry: ../../common/dsh.plugin.json } ] }这个../../common/dsh.plugin.json是相对于当前文件所在目录解析的。一旦你把这个插件文件夹移到了更深的层级或者把 common 目录挪走了这个路径就会失效。排查这类问题的时候别猜直接看路径用资源管理器一层一层对过去最快。4.3 dsh web authentication required; reopen the url printed by dsh web这条提示我在换机器和清理 token 的时候都遇到过。字面的意思是需要重新认证请重新打开 dsh web 打印出来的 URL。首先要理解 DSH 的 web 认证是怎么设计的。执行dsh web后程序会启动一个本地服务同时在终端打印一个授权 URL。你需要在浏览器里打开这个 URL登录模型服务的账号完成授权后浏览器会带着一个回调地址去访问本地服务程序拿到 token 之后保存起来。整个链路缺了任何一环命令行都不会进入正常界面。所以当你看到 reopen the url 时正确的做法是重新执行一次dsh web用新打印的 URL 走授权而不是拿着旧的授权链接反复刷。旧链接是单次有效的过期就失效。如果你反复重试都卡在认证环节大概率是本地存储的 token 文件损坏了。这时候执行一下登出命令或者去 profile 目录里把认证缓存文件删掉再重新走一遍完整的认证流程。4.4 setnamedsecurityinfow failed (win32 5): grantwriteWindows 权限拒绝的根源这个报错是纯 Windows 问题在 Linux 上永远碰不到。它的本质是 DSH 或其插件在启动时调用 SetNamedSecurityInfoW 这个系统 API想给自己的数据目录添加写入权限但 Windows 返回了访问拒绝。win32 错误码 5 就是 ERROR_ACCESS_DENIED。什么情况下会触发这个错误最常见的两个场景第一个是数据目录被放在了受保护的位置。比如当初安装时用了管理员权限把数据写进了 C:\Program Files 下面的某个目录。这种目录默认只允许管理员和 SYSTEM 写入普通用户启动 DSH 时想给目录添加写权限系统直接拒绝。解决办法是把数据目录迁移到%LOCALAPPDATA%\hsx-dsh-tools\data然后重新配一下 dsh.config.json 里的路径。第二是目录的所有者不对。如果你用管理员账户创建了数据目录之后再用普通用户运行 DSH普通用户并没有给该目录修改权限的资格。这时候运行工具包里的 fix-acl.ps1 脚本以管理员身份执行下面的命令powershell -ExecutionPolicy Bypass -File scripts\fix-acl.ps1 -Target C:\Users\你的用户名\AppData\Local\hsx-dsh-tools脚本会把这个目录的写权限授予当前用户。如果你更习惯手动作业也可以直接用 icaclsicacls C:\Users\你的用户名\AppData\Local\hsx-dsh-tools /grant %USERNAME%:(OI)(CI)M这条命令里的 (OI)(CI) 表示该权限继承到子目录和子文件M 是修改权限。执行完后ACL 报错应该就消失了。还有一个小概率但值得注意的情况日志里如果出现了C:\Windows\System32\driverstore\filerepository这个路径说明 DSH 的数据目录配置被错误地指到了 Windows 驱动文件仓库里。那不是 DSH 该碰的地方出现这种路径基本可以断定是配置文件写坏了直接改回用户目录别用 fix 的思路去硬改系统目录权限。4.5 报错速查表报错信息根因方向优先处理dsh 不是内部或外部命令PATH 未生效或未配置用 start-dsh.bat 启动或手动补全 PATHplugin tree failed to load ... include插件引用路径断裂修正 manifest 里的 include 相对路径dsh web authentication required ...认证流程未完成或 token 过期重新执行 dsh web打开新 URLsetnamedsecurityinfow failed (win32 5)Windows ACL 权限不足运行 fix-acl.ps1 或迁移数据目录plugin tree failed to load ... loader加载器类型或版本不匹配确认插件格式与 DSH 版本匹配5. 插件体系入门dshmarket 安装与插件开发格式5.1 profile 和插件树到底是个什么概念DSH 里有两个概念必须搞清楚不然后面用插件会一脸懵。第一个是 profile。简单说profile 就是一套独立配置上下文包含模型接口配置、启用的插件集合、工作目录这些信息。你可以建多个 profile 应对不同场景互不干扰。社区里最常用的是 web 这个 profile它针对网页相关工具和检索类任务做了预先配置。第二个是插件树。DSH 加载插件不是平铺着一个个来而是按树状结构组织的。根节点是 profile 的插件集合每个插件可以继续通过 include loader 把别的插件挂到自己下面这样就形成了一棵树。树状结构的好处是插件可以分层组织公共能力放底层业务功能放上层加载时按依赖关系逐层展开。5.2dsh plugin --profile web add dshmarket这条命令做了什么这条命令我在社区里每天都能看到有人问实际是执行了三件事第一dsh plugin告诉 DSH 这是插件管理操作。第二--profile web指定了在 web 这个 profile 下操作不影响其他 profile 的插件集合。第三add dshmarket表示从已配置的插件市场安装 dshmarket 这个插件。安装成功后dshmarket 插件会出现在该 profile 的插件目录里。这个插件的价值在于它本身是一个插件的市场入口装了它之后你可以继续用它去检索和安装更多社区插件而不用自己去源码仓库手动找。之后想装新插件直接在 DSH 界面里执行dsh plugin --profile web search 关键词 dsh plugin --profile web add 插件名5.3 插件的基本目录与 manifest 格式DSH 插件的基本结构并不复杂一个标准插件的目录大概是这样的my-plugin/ ├── dsh.plugin.json # 插件清单文件 ├── loaders/ │ ├── main.js # 主加载脚本 │ └── helper.py # 可选的辅助脚本 └── assets/ # 静态资源核心是 dsh.plugin.json 这个 manifest它的格式大致如下{ name: my-plugin, version: 0.1.0, description: 我的第一个 DSH 插件, loaders: [ { type: node, entry: loaders/main.js }, { type: include, entry: ../common/dsh.plugin.json } ], config: {} }字段解释name 和 version 是插件的基本标识。loaders 是核心部分每项代表一种加载方式。type 为 node 时entry 指向 JavaScript 文件type 为 python 时entry 指向 Python 脚本type 为 include 时entry 指向另一个 plugin manifest 文件这是插件树形成的关键。config 用来存放插件自身的静态配置。5.4 一个最小可用的示例光说概念不好理解给你一个最小示例。manifest 文件写好后再写一个 loaders/main.js{ name: hello-dsh, version: 0.1.0, description: 最小示例插件, loaders: [ { type: node, entry: loaders/main.js } ] }module.exports function(ctx) { return { name: hello-dsh, async run(input) { return { message: 你好DSH你输入了${input} }; } }; };把它放进插件的目录再在 DSH 里加载这个插件它就能在收到输入时返回一句问候。这只是概念演示实际插件的 API 接口会随 DSH 版本迭代有变化但 idea 是一致的插件本质上是一个暴露了 run 方法的模块DSH 负责把上下文传进来让插件去执行真正的任务。5.5 插件加载的两个高频阻碍插件写好了却加载失败多半是两个原因。一个是 Node loader 需要 Node.js 18 以上版本低了某些语法不支持另一个是 Python loader 需要 python 命令在 PATH 里Windows 上如果装的是 Microsoft Store 版的 Python命令名可能被限制成 python3 之类需要自己改一下环境变量或者把 loader 命令换成绝对路径。这部分是社区里讨论插件开发格式时常被忽略的坑我单独拎出来提醒一下。6. DSH 和 Codex Harness 怎么选以及我现在的使用习惯6.1 两者定位差异说句实话DSH 和 Codex Harness 虽然都被叫做 harness但用起来侧重点不一样。我个人的体感是Codex Harness 和 OpenAI 生态贴得更紧官方驱动的成分多DSH 的优势在模型接口选择和插件组装自由度上接 DeepSeek 本家接口时支持最完整同时也能通过兼容接口接其他模型。我把两个工具的主观差异整理成了一张表方便参考对比维度DSHCodex Harness默认模型生态DeepSeek 系列优先OpenAI 系列优先模型接口开放性更开放可配置兼容接口相对贴近官方生态插件体系社区驱动插件树结构官方插件体系更紧凑Windows 上手难度原生可用配合本工具包较顺官方有桌面版终端版配置门槛接近我的建议很简单如果你主力用 DeepSeek直接选 DSH如果你已经在 OpenAI 生态里投入了很多Codex 更合适。两个都装也没问题只要注意它们的数据目录和 PATH 别混在一起。6.2 我用下来的几个固定习惯这套工具包我自己用了两周多回头总结出几件每天都会做的事第一永远从 start-dsh.bat 进入不在普通 cmd 里硬敲 dsh。这能规避掉绝大多数 PATH 和环境变量导致的怪问题。第二所有配置、插件、数据目录都固定在 hsx-dsh-tools 这个文件夹里备份只需要打包这一个目录迁移机器时直接整套搬过去解压重装一次就行。第三每次升级 DSH 之后先看一遍插件树。因为升级经常带来配置格式的微调插件树没跟上就会出现 include 加载失败。看完再决定要不要重新安装 market 插件。第四遇到 setnamedsecurityinfow 这类权限报错绝不反复用管理员身份运行 DSH。根治办法只有一个把数据目录挪到用户可写的位置然后跑一次 fix-acl.ps1。靠提权绕过问题只会让数据目录的权限归属越来越乱。6.3 给 Windows 新手的最后叮嘱如果是完全没接触过命令行的新手我的建议是给自己留一个完整下午先把工具包装好然后不要急着配一堆插件先用默认配置跑几天把 DSH 的核心交互流程熟悉了再碰进阶功能。插件这东西装多了只会让你在出问题时无从下手。核心依赖的版本保持干净也很重要。我自己踩过 Node.js 多版本混装的坑dsh.cmd 找到的 node 不是预期版本结果所有插件全部加载失败。现在我只留一个 Node.js LTS 在系统里其他项目需要的版本一律用 nvm 这样的版本管理器隔离绝不污染全局环境。出错时日志文件都在 logs/ 目录里去社区提问题之前先把自己的日志贴出来别人才能帮你定位。
1. 为什么 Windows 上跑 DSH 这么费劲以及我选择封装工具包的直接原因1.1 DSH 到底是干嘛的DSH 的全称是 DeepSeek Harness。按我的理解它是一个给大模型提供干活框架的命令行工具模型在终端里接到任务后不是只停在对话框里给建议而是真的调用你本地的文件系统、命令行工具和插件体系去把任务做掉。类似形态的工具这两年冒出来不少Codex Harness 就是同一个赛道里的知名产品。DSH 和它的区别在于DSH 更强调模型接口的开放性、插件组装自由度和本地部署的灵活性。你可以把它接到 DeepSeek 的接口上跑日常编码任务也可以通过配置挂上一堆插件实现文档检索、自动化测试、批量数据处理这些扩展能力。我第一次接触 DSH 是在 Linux 服务器上一条管道命令装完就能直接用体验非常顺。后来想在 Windows 笔记本上同样配一套结果发现网上教程不少但真正能从头跑到尾的没几篇。这个工具本身不复杂问题几乎全出在环境适配这一层。所以这篇文章除了把安装过程完整捋一遍之外还会把高频报错的排查链路写清楚尤其是 Windows 特有的权限问题——这些内容在官方文档里基本找不到。1.2 Windows 环境的三个老大难结合我自己踩坑的经历和社区里铺天盖地的提问Windows 版本装 DSH 的障碍集中在三个方面。第一是环境依赖不一致。DSH 的安装脚本和插件生态默认面向 POSIX 环境很多路径处理、权限调用都是 Linux 风格。Windows 虽然有 Git Bash、WSL、PowerShell 这些兼容层但官方脚本不会替你做判断装到一半发现缺 Git、缺 Node.js、缺 PowerShell 模块都是家常便饭。第二是命令分发机制不一样。在 Linux 里装好工具软链接一放全局命令就有了。Windows 则要处理 PATH 变量、可执行文件扩展名、符号链接权限这些细节。任何一个环节出问题你就会撞上那句无比熟悉的提示dsh 不是内部或外部命令也不是可运行的程序或批处理文件。第三是权限模型差异。Windows 的 ACL 权限系统比 Unix 的 755 权限要复杂得多。很多工具在启动时会给自己的数据目录设置写入权限在 Unix 上是零成本操作到 Windows 上就可能触发 SetNamedSecurityInfoW 这类系统 API 的拒绝访问错误也就是社区里高频出现的 setnamedsecurityinfow failed (win32 5): grantwrite 报错。说白了DSH 本身不难用难在大部分资料都默认你是 Linux 用户。我最后决定把整个安装流程封装成 hsx-dsh-tools-v0.1.2 这个工具包原因也很直接让每个 Windows 用户都去跟脚本搏斗一遍太浪费生命了。环境探测、依赖查验、权限修复、启动器这些事本来就该一次性做好。2. hsx-dsh-tools-v0.1.2 的组成一键安装和双击启动是怎么实现的2.1 工具包里面装了什么先看目录结构你拿到压缩包解压之后应该是这样的hsx-dsh-tools-v0.1.2/ ├── install.bat # 一键安装入口双击后按提示操作 ├── start-dsh.bat # 双击启动入口日常使用就靠它 ├── uninstall.bat # 卸载脚本 ├── bin/ │ └── dsh.cmd # DSH 命令行启动包装器 ├── config/ │ ├── dsh.config.json # 主配置文件 │ └── profiles/ # profile 配置目录 ├── plugins/ # 插件目录 ├── scripts/ │ ├── check-env.ps1 # 环境检查脚本 │ ├── install-core.ps1 # 安装核心逻辑 │ ├── fix-acl.ps1 # Windows ACL 权限修复脚本 │ └── make-shortcut.ps1 # 创建快捷方式 └── logs/ # 安装与运行日志bin 目录放的是 dsh.cmd 而不是一个赤裸裸的 exe这个选择是有讲究的。DSH 核心本身是脚本产物一个 cmd 包装器能同时处理参数传递、临时环境变量注入、中文终端编码切换还能在出错时把窗口停住防止用户错过报错信息。这些都是裸 exe 不好做到的。2.2 安装脚本的工作流程install.bat 只是个入口真正的逻辑在 install-core.ps1 里。为什么这么拆分因为双击 .bat 是 cmd 环境下最稳的交互方式但要做系统检测、JSON 配置写入、ACL 修改这类操作PowerShell 能力强得多。所以 .bat 负责拉起 PowerShellPowerShell 负责干活。安装流程按这个顺序走权限检测。默认安装到当前用户目录不需要管理员权限但如果你选择创建开始菜单快捷方式脚本会在这一步自动弹出提权请求。环境预检。check-env.ps1 会逐项扫描系统版本、PowerShell、Git、Node.js以及可选的 Docker、Redis、Elasticsearch 组件。预检结果逐条打印缺失项直接告诉你该装什么。部署核心文件。默认复制到 %LOCALAPPDATA%\hsx-dsh-tools 目录不污染系统盘 Program Files。写入初始配置。生成 dsh.config.json 和一个默认 profile把数据目录指到用户目录下。权限修正。针对数据目录执行 fix-acl.ps1从根上避免后面出现 setnamedsecurityinfow 之类的 ACL 报错。创建快捷方式。如果用户同意生成DeepSeek Harness (DSH)的快捷方式到开始菜单和桌面。环境预检这一步我做成了一张便于对照的表检查项作用缺失时的提示Windows 10 21H2 / Windows 11旧系统缺少新版 API提示升级系统PowerShell 5.1安装脚本的运行时提示升级 PowerShellGit插件管理、版本相关命令依赖提示安装 GitNode.js 18DSH 核心运行时提示安装 Node.js LTSDocker Desktop容器类插件可选依赖仅警告不影响基础功能Redis / Elasticsearch检索与缓存类插件可选依赖仅警告按需安装2.3 为什么是双击启动而不是改全局 PATH这是工具包设计里最核心的一个取舍。传统思路是安装时用 setx 把 bin 目录写进系统 PATH一劳永逸。但我试过之后发现这条路在 Windows 上有四个坑第一setx 修改的 PATH 不会立刻作用于当前已打开的终端窗口用户经常要重启终端甚至重启电脑才能生效。第二Windows 的 PATH 变量有长度限制堆满 JDK、Python、Node 的机器上再追加新路径很容易顶满。第三全局 PATH 被工具包修改本质上是在污染系统环境以后卸载还会留下残留。第四为了让 dsh 命令可用你还得处理环境变量在子进程间的传递稍有不慎就会遇到找不到模块的怪问题。所以 start-dsh.bat 换了个思路启动时临时把 bin 目录和 Node.js 路径注入到当前会话的 PATH 里再拉起 dsh。这样做的好处是每次双击都能得到一个确定可用的环境不需要用户关心 PATH 到底配没配。代价是你在普通的 cmd 窗口里直接敲 dsh 还是不行但这对绝大多数用户来说根本不是问题——你不需要记住 dsh 有哪些参数直接双击启动进去了再说。启动器里还顺带做了两件小事一是chcp 65001 nul把终端切到 UTF-8避免中文乱码二是出错时停在窗口前提示按任意键关闭防止报错一闪而过。3. 跟着走一遍从解压到首个任务跑通3.1 安装前建议先做三件事第一次接触这套工具的人建议按这个顺序准备把压缩包解压到一个没有空格的路径比如 D:\hsx-dsh-tools。放在桌面或者带空格的文件夹里虽然大多数情况下没问题但某些插件脚本对空格路径处理不好能避免就避免。先看一眼系统版本Win10 21H2 以上或 Win11 最省心。真要用 Win10 老版本安装脚本会给出提示但别指望所有插件都能正常工作。如果机器上装了第三方杀毒软件安装第一遍建议临时关掉实时防护。脚本行为的误报率不低等确认安装成功后可以再开回来。3.2 一键安装过程实录双击 install.bat 后正常情况下你会看到类似下面的输出[hsx-dsh-tools] 正在检查系统环境... 操作系统: Windows 11 23H2 (build 22631) PowerShell: 7.4.2 Git: 2.44.0 Node.js: 20.11.1 Docker: 未安装不影响基础功能 环境检查完成。 [hsx-dsh-tools] 正在部署核心文件... 目标目录: C:\Users\你的用户名\AppData\Local\hsx-dsh-tools 配置文件: 已写入 数据目录: C:\Users\你的用户名\AppData\Local\hsx-dsh-tools\data [hsx-dsh-tools] 正在修复目录权限... 数据目录 ACL: OK [hsx-dsh-tools] 已创建开始菜单快捷方式: DeepSeek Harness (DSH) 安装完成双击桌面或开始菜单里的 DeepSeek Harness (DSH) 即可启动。如果你机器上有检查项显示缺失先补装对应依赖再重新运行 install.bat。特别注意 Node.js 版本DSH 对 Node 版本有一定要求装 LTS 版最稳。这里我不推荐用系统自带的包管理器去装 Node直接去官网下安装包更省事装完以后 PATH 是自动配好的不会埋雷。3.3 双击启动和首次认证安装完成后双击桌面上的DeepSeek Harness (DSH)快捷方式。第一次启动时由于还没有完成身份认证终端会打印类似下面的提示[DSH] 检测到未完成认证请打开以下地址完成登录 https://... 按 Enter 继续...把这段地址复制到浏览器打开登录你的模型服务账号按页面提示完成授权再回到终端按 Enter认证流程就算走完了。整个过程和我最早在 Linux 上遇到的一致只是 Windows 上多了一道代理判断的环节如果浏览器能正常打开登录页基本不会卡住。如果你在这个阶段看到的是 dsh web authentication required; reopen the url printed by dsh web.别慌这通常意味着上一次认证流程没走完或者是 token 过期了。解决办法很简单重新执行一次dsh web用新打印出来的 URL 走一遍授权不要拿旧地址硬刷。3.4 怎么判断装好了认证通过后在 DSH 交互界面里依次执行下面三条命令dsh --version dsh --help dsh plugin list三条都能正常输出就说明核心安装没问题。注意这里的用法是你在 DSH 交互环境里面执行命令不是在普通 cmd 窗口里直接敲。如果你是用 start-dsh.bat 启动的交互界面里直接输入--version或help这类子命令也行两种方式都支持。最后做个最简单的真实任务验证一下让它列出当前目录下所有 Python 文件并统计行数。能正确输出结果整个安装链路就算真正跑通了。4. 高频报错排查实录我踩过的坑都给你标好了4.1 dsh 不是内部或外部命令先分三种情况这个报错出现的概率最高但它背后的原因差别很大处理方式也不一样。第一种情况是你在普通 cmd 窗口里敲 dsh提示找不到命令。这是正常的因为工具包默认走的是双击启动路线没有改全局 PATH。解决办法是以后都用 start-dsh.bat 启动或者如果你确实需要全局命令行可用手动把C:\Users\你的用户名\AppData\Local\hsx-dsh-tools\bin加进系统 PATH 即可。第二种情况是你明明安装了但where dsh在系统里搜不到任何结果。这多半说明安装过程根本没走完或者被杀毒软件拦截了关键文件。去 logs 目录看安装日志找到出错的那一步重新跑一遍 install.bat。第三种情况有点隐蔽dsh.cmd 文件存在命令也能找到但执行时报错说找不到 node。这种情况通常是 Node.js 没有正确加入 PATH或者系统里有多个 Node 版本冲突。在启动器会话里检查一下node --version是否能正常输出不能的话就需要先修复 Node.js 的安装。4.2 plugin tree failed to load: failed to apply loader entry include这个报错我前前后后遇到过三次每次都是同一个原因插件树的 include 引用路径断裂了。DSH 加载插件的时候是按树状结构走的每个插件配置文件里可以声明多种 loader其中一种就是 include。include 的作用是把另一个插件或配置文件的路径引进来让它们组成一棵插件树。如果被引用的文件不存在了或者相对路径因为目录移动对不上了就会触发这条错误。排查链路建议按下面几步走打开 dsh.config.json确认 plugins 目录指向哪里。去 plugins 目录下找到报错插件的 manifest 文件一般是 dsh.plugin.json。逐个检查里面 include loader 写的相对路径确认目标文件真实存在。常见的一个问题是我之前把工具包解压到了别的目录里面的相对路径是按当时的目录结构写的搬家以后就全断了。手动修正路径后保存重启 DSH。举个例子下面这个 manifest 里的 include 就很容易出问题{ name: my-plugin, version: 0.1.0, loaders: [ { type: include, entry: ../../common/dsh.plugin.json } ] }这个../../common/dsh.plugin.json是相对于当前文件所在目录解析的。一旦你把这个插件文件夹移到了更深的层级或者把 common 目录挪走了这个路径就会失效。排查这类问题的时候别猜直接看路径用资源管理器一层一层对过去最快。4.3 dsh web authentication required; reopen the url printed by dsh web这条提示我在换机器和清理 token 的时候都遇到过。字面的意思是需要重新认证请重新打开 dsh web 打印出来的 URL。首先要理解 DSH 的 web 认证是怎么设计的。执行dsh web后程序会启动一个本地服务同时在终端打印一个授权 URL。你需要在浏览器里打开这个 URL登录模型服务的账号完成授权后浏览器会带着一个回调地址去访问本地服务程序拿到 token 之后保存起来。整个链路缺了任何一环命令行都不会进入正常界面。所以当你看到 reopen the url 时正确的做法是重新执行一次dsh web用新打印的 URL 走授权而不是拿着旧的授权链接反复刷。旧链接是单次有效的过期就失效。如果你反复重试都卡在认证环节大概率是本地存储的 token 文件损坏了。这时候执行一下登出命令或者去 profile 目录里把认证缓存文件删掉再重新走一遍完整的认证流程。4.4 setnamedsecurityinfow failed (win32 5): grantwriteWindows 权限拒绝的根源这个报错是纯 Windows 问题在 Linux 上永远碰不到。它的本质是 DSH 或其插件在启动时调用 SetNamedSecurityInfoW 这个系统 API想给自己的数据目录添加写入权限但 Windows 返回了访问拒绝。win32 错误码 5 就是 ERROR_ACCESS_DENIED。什么情况下会触发这个错误最常见的两个场景第一个是数据目录被放在了受保护的位置。比如当初安装时用了管理员权限把数据写进了 C:\Program Files 下面的某个目录。这种目录默认只允许管理员和 SYSTEM 写入普通用户启动 DSH 时想给目录添加写权限系统直接拒绝。解决办法是把数据目录迁移到%LOCALAPPDATA%\hsx-dsh-tools\data然后重新配一下 dsh.config.json 里的路径。第二是目录的所有者不对。如果你用管理员账户创建了数据目录之后再用普通用户运行 DSH普通用户并没有给该目录修改权限的资格。这时候运行工具包里的 fix-acl.ps1 脚本以管理员身份执行下面的命令powershell -ExecutionPolicy Bypass -File scripts\fix-acl.ps1 -Target C:\Users\你的用户名\AppData\Local\hsx-dsh-tools脚本会把这个目录的写权限授予当前用户。如果你更习惯手动作业也可以直接用 icaclsicacls C:\Users\你的用户名\AppData\Local\hsx-dsh-tools /grant %USERNAME%:(OI)(CI)M这条命令里的 (OI)(CI) 表示该权限继承到子目录和子文件M 是修改权限。执行完后ACL 报错应该就消失了。还有一个小概率但值得注意的情况日志里如果出现了C:\Windows\System32\driverstore\filerepository这个路径说明 DSH 的数据目录配置被错误地指到了 Windows 驱动文件仓库里。那不是 DSH 该碰的地方出现这种路径基本可以断定是配置文件写坏了直接改回用户目录别用 fix 的思路去硬改系统目录权限。4.5 报错速查表报错信息根因方向优先处理dsh 不是内部或外部命令PATH 未生效或未配置用 start-dsh.bat 启动或手动补全 PATHplugin tree failed to load ... include插件引用路径断裂修正 manifest 里的 include 相对路径dsh web authentication required ...认证流程未完成或 token 过期重新执行 dsh web打开新 URLsetnamedsecurityinfow failed (win32 5)Windows ACL 权限不足运行 fix-acl.ps1 或迁移数据目录plugin tree failed to load ... loader加载器类型或版本不匹配确认插件格式与 DSH 版本匹配5. 插件体系入门dshmarket 安装与插件开发格式5.1 profile 和插件树到底是个什么概念DSH 里有两个概念必须搞清楚不然后面用插件会一脸懵。第一个是 profile。简单说profile 就是一套独立配置上下文包含模型接口配置、启用的插件集合、工作目录这些信息。你可以建多个 profile 应对不同场景互不干扰。社区里最常用的是 web 这个 profile它针对网页相关工具和检索类任务做了预先配置。第二个是插件树。DSH 加载插件不是平铺着一个个来而是按树状结构组织的。根节点是 profile 的插件集合每个插件可以继续通过 include loader 把别的插件挂到自己下面这样就形成了一棵树。树状结构的好处是插件可以分层组织公共能力放底层业务功能放上层加载时按依赖关系逐层展开。5.2dsh plugin --profile web add dshmarket这条命令做了什么这条命令我在社区里每天都能看到有人问实际是执行了三件事第一dsh plugin告诉 DSH 这是插件管理操作。第二--profile web指定了在 web 这个 profile 下操作不影响其他 profile 的插件集合。第三add dshmarket表示从已配置的插件市场安装 dshmarket 这个插件。安装成功后dshmarket 插件会出现在该 profile 的插件目录里。这个插件的价值在于它本身是一个插件的市场入口装了它之后你可以继续用它去检索和安装更多社区插件而不用自己去源码仓库手动找。之后想装新插件直接在 DSH 界面里执行dsh plugin --profile web search 关键词 dsh plugin --profile web add 插件名5.3 插件的基本目录与 manifest 格式DSH 插件的基本结构并不复杂一个标准插件的目录大概是这样的my-plugin/ ├── dsh.plugin.json # 插件清单文件 ├── loaders/ │ ├── main.js # 主加载脚本 │ └── helper.py # 可选的辅助脚本 └── assets/ # 静态资源核心是 dsh.plugin.json 这个 manifest它的格式大致如下{ name: my-plugin, version: 0.1.0, description: 我的第一个 DSH 插件, loaders: [ { type: node, entry: loaders/main.js }, { type: include, entry: ../common/dsh.plugin.json } ], config: {} }字段解释name 和 version 是插件的基本标识。loaders 是核心部分每项代表一种加载方式。type 为 node 时entry 指向 JavaScript 文件type 为 python 时entry 指向 Python 脚本type 为 include 时entry 指向另一个 plugin manifest 文件这是插件树形成的关键。config 用来存放插件自身的静态配置。5.4 一个最小可用的示例光说概念不好理解给你一个最小示例。manifest 文件写好后再写一个 loaders/main.js{ name: hello-dsh, version: 0.1.0, description: 最小示例插件, loaders: [ { type: node, entry: loaders/main.js } ] }module.exports function(ctx) { return { name: hello-dsh, async run(input) { return { message: 你好DSH你输入了${input} }; } }; };把它放进插件的目录再在 DSH 里加载这个插件它就能在收到输入时返回一句问候。这只是概念演示实际插件的 API 接口会随 DSH 版本迭代有变化但 idea 是一致的插件本质上是一个暴露了 run 方法的模块DSH 负责把上下文传进来让插件去执行真正的任务。5.5 插件加载的两个高频阻碍插件写好了却加载失败多半是两个原因。一个是 Node loader 需要 Node.js 18 以上版本低了某些语法不支持另一个是 Python loader 需要 python 命令在 PATH 里Windows 上如果装的是 Microsoft Store 版的 Python命令名可能被限制成 python3 之类需要自己改一下环境变量或者把 loader 命令换成绝对路径。这部分是社区里讨论插件开发格式时常被忽略的坑我单独拎出来提醒一下。6. DSH 和 Codex Harness 怎么选以及我现在的使用习惯6.1 两者定位差异说句实话DSH 和 Codex Harness 虽然都被叫做 harness但用起来侧重点不一样。我个人的体感是Codex Harness 和 OpenAI 生态贴得更紧官方驱动的成分多DSH 的优势在模型接口选择和插件组装自由度上接 DeepSeek 本家接口时支持最完整同时也能通过兼容接口接其他模型。我把两个工具的主观差异整理成了一张表方便参考对比维度DSHCodex Harness默认模型生态DeepSeek 系列优先OpenAI 系列优先模型接口开放性更开放可配置兼容接口相对贴近官方生态插件体系社区驱动插件树结构官方插件体系更紧凑Windows 上手难度原生可用配合本工具包较顺官方有桌面版终端版配置门槛接近我的建议很简单如果你主力用 DeepSeek直接选 DSH如果你已经在 OpenAI 生态里投入了很多Codex 更合适。两个都装也没问题只要注意它们的数据目录和 PATH 别混在一起。6.2 我用下来的几个固定习惯这套工具包我自己用了两周多回头总结出几件每天都会做的事第一永远从 start-dsh.bat 进入不在普通 cmd 里硬敲 dsh。这能规避掉绝大多数 PATH 和环境变量导致的怪问题。第二所有配置、插件、数据目录都固定在 hsx-dsh-tools 这个文件夹里备份只需要打包这一个目录迁移机器时直接整套搬过去解压重装一次就行。第三每次升级 DSH 之后先看一遍插件树。因为升级经常带来配置格式的微调插件树没跟上就会出现 include 加载失败。看完再决定要不要重新安装 market 插件。第四遇到 setnamedsecurityinfow 这类权限报错绝不反复用管理员身份运行 DSH。根治办法只有一个把数据目录挪到用户可写的位置然后跑一次 fix-acl.ps1。靠提权绕过问题只会让数据目录的权限归属越来越乱。6.3 给 Windows 新手的最后叮嘱如果是完全没接触过命令行的新手我的建议是给自己留一个完整下午先把工具包装好然后不要急着配一堆插件先用默认配置跑几天把 DSH 的核心交互流程熟悉了再碰进阶功能。插件这东西装多了只会让你在出问题时无从下手。核心依赖的版本保持干净也很重要。我自己踩过 Node.js 多版本混装的坑dsh.cmd 找到的 node 不是预期版本结果所有插件全部加载失败。现在我只留一个 Node.js LTS 在系统里其他项目需要的版本一律用 nvm 这样的版本管理器隔离绝不污染全局环境。出错时日志文件都在 logs/ 目录里去社区提问题之前先把自己的日志贴出来别人才能帮你定位。
