所有DSH相关文章已经push到github，大家可以访问此仓库：

https://github.com/HaroldFrey/DSH-USE

其余相关AI Agent或工具使用文章请阅读公众号文章合集：

DeepSeek Harness 安装指南

本文档面向首次在本机部署 DeepSeek Harness 的开发者，从安装 Node.js 开始，逐步完成环境准备、目录规划、安装、验证与启动。

文中出现的盘符与路径均为示例，读者可根据自己的磁盘情况调整。

1. DeepSeek Harness 是什么

DeepSeek Harness 是 DeepSeek AI 开源的 Agent 运行框架，命令行工具名为 dsh，使用 TypeScript 编写，采用 MIT 许可证，于 2026 年 8 月开源。

官方文档站对其定位的表述为「用于构建 Agent Harness 的插件化 SDK」。模型负责推理，Harness 负责工具调用、上下文管理、权限控制、会话持久化等工程部分。

社区教程中常将其概括为 Agent = Model + Harness，该说法未见于官方一手资料。

1.1 架构特点

• 一切皆插件
  ：内核基于 Cordis 插件系统，只负责插件的加载、卸载与依赖管理。模型、工具、技能、会话、沙箱、存储、调度、界面等全部能力均由插件提供，可在配置层自由替换与重组，无需修改源码。
• 配置分层叠加
  ：通过 Profile 与组合包分层组合配置，运行 dsh --profile web --dump-config 可查看实际生效的完整配置树。
• 运行过程可观测
  ：模型接收到的全部内容，包括系统提示词、思维链、工具调用与结果、子 Agent 调度，都写入仅追加的会话日志，可在 Trajectory 视图中按来源查看。
• 模型无关
  ：默认接入 DeepSeek API，同时支持其他提供方与自定义 OpenAI 兼容端点，模型路由无需重启即可切换。

1.2 运行模式

四种模式对应四个内置预设，目录名分别为 standard、ptc、minimal、cordis；「创造模式」的预设 id 即 cordis。内置预设随 @deepseek-ai/dsh-agent-presets 发布，全部位于该包的 presets/ 目录下，没有第五种。

1.3 使用形态

• Web UI，默认监听 127.0.0.1:3080
• headless 模式，一次性运行并打印最终结果，适合脚本与 CI 场景
• CLI、Python SDK、TypeScript SDK

1.4 项目状态

当前为开发者预览版，官方明确说明后续会有破坏性变更，不建议作为生产环境的关键依赖。

2. 环境要求

Node.js 的版本要求取自官方仓库根目录 package.json 的 engines 字段， https://github.com/deepseek-ai/deepseek-harness/blob/master/package.json

需要说明的是：作为入口的 @deepseek-ai/dsh 包本身并不声明 engines 字段，装好的依赖树里也没有可直接查的版本门槛，因此这个要求无法从已装文件里核对，只能看官方仓库，或用下面这条命令查注册表元数据（需要联网）：

npm view @deepseek-ai/dsh engines

实践中的判断标准很简单：用 Node.js 的 LTS 版本，避开 23.x。安装完成后按第 3.3 节用 node --version 确认实际生效的版本。

3. 安装 Node.js

3.1 下载

访问 https://nodejs.org/，下载 LTS 版本。

注意核对版本号是否满足第 2 节的要求。需为 22.19.0 至 23.0.0 之间，或不低于 24.0.0；23.x 不在支持范围内。

3.2 安装

运行安装程序，保持默认选项即可。建议记录安装路径，后续排查问题时需要用到。

3.3 验证

打开终端，执行：

node --versionnpm --version

两条命令都应输出具体版本号。若 node --version 的输出不满足第 2 节的版本要求，需要卸载后重新安装。

4. 规划目录布局

DSH 涉及三个互不相同的目录概念，安装前需要区分清楚。

4.1 三个独立的概念

关键点：把程序安装到某个盘符，不会让数据也存到该盘符。数据目录由 DSH_HOME 决定，默认为用户主目录下的 .dsh。在 Windows 上即 C:\Users\<用户名>\.dsh。

4.2 为什么需要规划

以下内容会随使用持续增长，且 DSH 不会自动清理：

若保持默认设置，以上内容会全部写入系统盘。将数据目录规划到非系统盘，可以避免系统盘持续增长，也便于系统重装时保留数据。

4.3 推荐布局

将数据目录放在程序目录内部，便于整体备份与迁移。

需要注意两点：

• 数据目录不等于只有你自己的数据。profiles\node_modules
   由 DSH 在首次启动时用 pnpm 安装，实测 25366 个文件、197 MB，是数据目录里最大的部分；attachments 要到首次上传图片时才会出现。
• 不要为了省事在数据目录里执行 npx dsh。npx
   会向上查找，把 dsh 解析到程序目录，命令看似能跑起来，但 profile 初始化会在执行命令的当前目录下建立 profiles\，等于把 profile 装到了错误的位置；在受限沙箱里还会因为无法写入工作区之外的路径而直接报 EPERM 失败。命令一律在程序目录下执行，并保留 cd /d 这一步（见第 10 节的启动脚本）。

4.4 需要转移的其他位置

系统临时目录是 Windows 沙箱机制的一部分，修改会影响系统上的其他程序，不建议调整。同理，被沙箱拦下的写入并不区分盘符，把数据目录挪到 D 盘只解决「数据增长」，不改变「Agent 只能改工作区之内」这一限制。

5. 配置环境变量

5.1 设置变量

打开命令提示符，执行：

setx DSH_HOME "<程序目录>\home"setx DSH_AGENTS_HOME "<程序目录>\agents"

变量值需使用绝对路径，不要使用相对路径。上面命令中的 <程序目录> 指 DSH 的程序目录（第 4.3 节中的 D:\APP_Install\24_deepseek-harness），执行前需替换为实际路径。

5.2 必须注意的生效范围

setx 设置的变量只对之后新建的进程生效。已经打开的终端，以及从旧进程派生的终端，读取到的仍是旧环境。

如果使用 VS Code 等编辑器的集成终端，必须完全退出并重启该编辑器。仅新建终端标签不够，因为集成终端继承的是编辑器进程的环境变量。

这一步容易出错。如果跳过，DSH 会回退到默认数据目录，配置与凭据会被写入系统盘，且不易察觉。

5.3 验证

新开一个终端，按所用 shell 执行对应命令：

echo$DSH_HOME# Git Bashecho %DSH_HOME%         # CMD$env:DSH_HOME           # PowerShell

输出应为设置的数据目录路径。若输出为空，说明当前终端仍是旧环境，需要重新打开或重启编辑器。

6. 配置 npm 缓存

npm 缓存默认位于系统盘，会随每次 npm 安装持续增长，建议一并转移。

npm config set cache \"D:\APP_Install\npm-cache"

验证：

npm config get cache

该设置写入用户目录下的 .npmrc 文件，对本机所有 npm 项目生效。

修改缓存路径不会搬走已有缓存，原目录的内容仍留在系统盘，需要手工清理。

7. 安装 DeepSeek Harness

7.1 初始化项目目录

cd /d D:\APP_Install\24_deepseek-harnessnpm init -y

7.2 执行安装

npm install @deepseek-ai/dsh

包名必须为 @deepseek-ai/dsh。 npm 上另有一个名为 deepseek-harness 的包，那是第三方占位包，版本号为 0.0.1，安装后不提供任何功能，不要安装。

安装过程需要数分钟，会下载约 500 个包。

7.3 安装脚本被拦截的说明

npm 的较新版本引入了 allow-scripts 安全机制，默认拦截第三方包的安装脚本。安装完成后可能看到类似提示：

npm warn allow-scripts 5 packages haveinstall scripts not yet covered byallowScripts

在 Windows 上，被拦截的脚本通常不影响使用：

若后续出现子进程或终端相关故障，可执行以下命令补跑这些脚本：

npm approve-scripts \  --allow-scripts-pending

8. 验证安装

8.1 检查配置树

cd /d D:\APP_Install\24_deepseek-harnessnpx dsh --profile web --dump-config

该命令输出实际生效的完整配置树。确认无报错，且输出中包含 session-persistence-jsonl 条目。

8.2 确认数据目录指向

配置树中该条目的 root 字段显示的是未求值的表达式 dshHomePath('sessions')，需要单独验证实际解析结果：

node -e "console.log(require(  '@deepseek-ai/dsh-home-paths').dshHomePath('sessions'))"

该包随 profile 安装，不在程序目录的 dependencies 里，因此必须在程序目录下执行（在别处执行会报 Cannot find module）。若报错提示找不到模块且你确认已在程序目录，说明 profile 尚未初始化，先执行一次 npx dsh --profile web --dump-config 再重跑。

输出应为设置的数据目录下的 sessions 路径。若输出的是系统盘路径，说明环境变量未生效，参见第 5.2 节。

此步骤必须在正式使用前完成。 否则可能在数据已经写入系统盘之后才发现问题。

9. 启动服务

npx dsh web

首次启动需要约 60 至 70 秒准备 Web 前端，之后启动会快很多。

启动完成后终端输出访问地址：

dsh web:http://127.0.0.1:3080/?token=<令牌>

服务器会自动打开浏览器并跳转到带令牌的地址。每次启动令牌都会变化，请以当次终端输出的链接为准。

若本机存在可用网卡地址，这一行还会在链接后追加一段 (LAN: http://<局域网地址>:3080/?token=...)。单机使用只需用第一个 127.0.0.1 的链接即可。

关于访问控制，有三点容易误解：

• 带令牌的地址只在首次访问时需要。校验通过后服务器返回 303 重定向到干净的 http://127.0.0.1:3080/，并种下签名 cookie（名称以 dsh-auth- 开头，有效期以天计）。此后同一浏览器再访问不带令牌的地址即可正常打开。若开了无痕模式或换了浏览器，则需要重新使用带令牌的链接。
• 令牌是进程级的，重启服务后旧令牌立即失效。但上面那个 cookie 不会随重启失效，所以「重启后旧的带令牌链接打不开」属于正常现象，直接用不带令牌的地址或新链接即可。
• 直接访问既无令牌、又无有效 cookie 的地址会返回 401，这是访问控制机制，不是故障。

常用参数：

停止服务：在运行服务的终端窗口按 Ctrl+C。

10. 创建启动脚本

为避免环境变量未生效导致数据写入系统盘，建议在程序目录下新建 start-dsh.cmd：

@echo offset "DSH_HOME=<程序目录>\home"set "DSH_AGENTS_HOME=<程序目录>\agents"cd /d "<程序目录>"npx dsh web

脚本中显式设置环境变量，不依赖系统环境，可规避终端继承旧环境的问题。其中的 <程序目录> 指 DSH 的程序目录（第 4.3 节中的 D:\APP_Install\24_deepseek-harness），替换为实际路径后双击即可启动。

若使用中文注释，需将文件保存为 GBK 编码，否则在命令提示符中会显示为乱码。

11. 常见问题

12. 参考来源

官方资源

• 项目仓库：https://github.com/deepseek-ai/deepseek-harness
• 官方文档：https://deepseek-harness.github.io/deepseek-harness/
• npm 包页面：https://www.npmjs.com/package/@deepseek-ai/dsh
• 安全须知：SAFETY.md
• DeepSeek 开放平台：https://platform.deepseek.com/

第三方教程

• 菜鸟教程 DeepSeek Harness 系列：https://www.runoob.com/deepseek-harness/deepseek-harness-tutorial.html
• CSDN 安装教程：https://blog.csdn.net/2301_81024796/article/details/163746154

本文档事实依据

以下结论均取自官方仓库源码与文档，链接可直接打开核对。

DeepSeek Harness 首次使用与配置

本文档面向已完成安装的读者，说明首次启动、配置 API Key、选择工作区的完整流程，以及日常操作与故障排查。

安装步骤参见同目录下的 01-安装方案.md。

1. 启动服务

1.1 使用启动脚本

如果安装时已按安装指南创建了 start-dsh.cmd，直接双击该文件即可。

脚本会先设置数据目录环境变量，检查端口占用情况，然后启动服务。

1.2 使用命令行

打开终端，执行：

cd /d D:\APP_Install\24_deepseek-harnessnpx dsh web

首次启动需要约 60 至 70 秒准备 Web 前端。

1.3 启动前的检查

使用命令行启动前，先确认环境变量已生效：

echo$DSH_HOME# Git Bashecho %DSH_HOME%         # CMD$env:DSH_HOME           # PowerShell

输出应为数据目录路径。若输出为空，当前终端读取的是旧环境，需要重新打开终端或完全重启编辑器，否则数据会写入系统盘。

2. 打开界面

启动完成后，终端输出访问地址：

dsh web:http://127.0.0.1:3080/?token=<令牌>

服务器会自动打开浏览器并跳转到该地址。

必须使用带令牌的完整链接。 既没带令牌、也没有有效 cookie 时，页面会返回 401，这是访问控制机制，不是故障。

打开带令牌的链接后，服务器会立即重定向到干净的 http://127.0.0.1:3080/，并种下一个签名 cookie（名称以 dsh-auth- 开头，有效期以天计）。因此：

• 同一浏览器只需首次使用带令牌的链接，之后直接访问不带令牌的地址即可。
• 每次启动令牌都会变化，但 cookie 不会随重启失效。重启服务后旧的带令牌链接打不开，属正常现象。
• 无痕模式、换浏览器或清了 cookie 后，需要重新使用当次终端输出的链接。

3. 配置 API Key

进入界面后，打开 设置 → 模型，填入 DeepSeek API 密钥并保存。

密钥格式以 sk- 开头，在 https://platform.deepseek.com/ 申请。

保存后模型路由立即生效，不需要重启服务。

密钥写入数据目录下的 .credentials.yaml 文件。若需要确认存储位置是否正确，检查该文件是否出现在预期的数据目录中。

4. 选择工作区

4.1 工作区的作用

工作区是 Agent 实际操作的项目目录。官方默认权限策略规定：文件写入限制在工作区内，危险操作前需要征询许可。

工作区划定的是 Agent 可以改动的范围，因此选择范围需要谨慎。

4.2 选择方法

点击 选择工作区，添加目标目录，然后选中它。

选中工作区之前，会话输入框不可用，这是正常现象。

4.3 选择原则

一次只选择一个具体的项目目录。

不建议选择以下目录：

• 盘符根目录，例如 D:\ 或 C:\
• 包含大量项目的上层目录，例如 D:\Projects

原因见官方安全须知：沙箱与审批机制能够降低风险，但不保证隔离。

建议做法：

5. 运行第一个任务

选中工作区后，启动一个会话并发送任务，例如：

阅读这个项目的结构，说明它由哪些部分组成。

Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护执行计划。若某个操作根据当前权限策略需要审批，界面会先弹出确认。

6. 运行模式

新建会话时可以选择运行模式，各模式能力差异较大：

四种模式对应四个内置预设，目录名分别为 standard、ptc、minimal、cordis。「创造模式」的预设 id 是 cordis，不是 creative；内置预设随 @deepseek-ai/dsh-agent-presets 发布，位于该包的 presets/ 目录下，没有第五种。

日常编码辅助使用标准模式即可，它也是 Web 的默认预设。

7. 权限与审批

官方安全须知中包含以下内容，使用前应当了解：

• 本项目会执行模型生成的代码与命令，加载第三方插件，访问网络、进程、凭据与文件
• 模型的错误输出、缺陷、配置错误、恶意输入或不可信插件，可能损坏主机、修改或删除文件、泄露数据
• 沙箱、审批提示与权限控制能够降低风险，但不保证隔离
• 官方建议：以最小权限运行；保持项目可访问文件的备份；逐条审查要执行的命令

遇到审批请求时，应逐条确认操作内容，不要连续无条件允许。

8. 数据存储位置

数据目录由 DSH_HOME 环境变量决定。默认布局如下：

其中 profiles\node_modules 由 DSH 在首次启动时用 pnpm 安装，实测 25366 个文件、197 MB，是数据目录里最大的部分；attachments 要到首次上传图片时才会出现。

会话按 sessions\--<项目目录名>--\<会话ID>\ 的层级组织。

8.1 持续增长的内容

目前无需主动处理。当占用明显增大时，可按需清理。

9. 日常操作

9.1 启动与停止

启动使用启动脚本或 npx dsh web。停止在运行服务的终端窗口按 Ctrl+C。

9.2 检查服务状态

netstat -ano | findstr 3080

输出包含 LISTENING 表示服务正在运行。

9.3 升级

cd /d D:\APP_Install\24_deepseek-harnessnpm install @deepseek-ai/dsh@latest

项目处于开发者预览阶段，升级前建议查看版本变更说明。

升级不会影响数据目录，会话与配置均保留。

升级后应重新执行数据目录验证：

node -e "console.log(require(  '@deepseek-ai/dsh-home-paths')  .dshHomePath('sessions'))"

该包随 profile 安装，不在程序目录的 dependencies 里，因此必须在程序目录下执行（在别处执行会报 Cannot find module）。若报错提示找不到模块且你确认已在程序目录，说明 profile 尚未初始化，先执行一次 npx dsh --profile web --dump-config 再重跑。

确认输出仍指向预期的数据目录。

10. 故障排查

若启动脚本提示端口已被占用，说明已有实例在运行。关闭该实例后再启动，不要重复启动多个实例。

11. 参考来源

官方资源

• 项目仓库：https://github.com/deepseek-ai/deepseek-harness
• 官方文档：https://deepseek-harness.github.io/deepseek-harness/
• Web UI 使用指南：docs/user/guide/index.zh.md
• 安全须知：SAFETY.md
• npm 包页面：https://www.npmjs.com/package/@deepseek-ai/dsh
• DeepSeek 开放平台：https://platform.deepseek.com/

第三方教程

• 菜鸟教程 DeepSeek Harness 系列：https://www.runoob.com/deepseek-harness/deepseek-harness-tutorial.html
• CSDN 安装教程：https://blog.csdn.net/2301_81024796/article/details/163746154

本文档事实依据

以下结论均取自官方仓库源码与文档，链接可直接打开核对。

DeepSeek Harness 自定义技能使用指南

本文档说明如何在 DeepSeek Harness 中使用自定义技能，包括技能格式、存放位置、部署方式与验证方法。

阅读前需已完成安装，并能正常启动 Web UI。安装步骤参见同目录下的 01-安装方案.md。

1. 技能是什么

技能是一组可复用的指令，告诉 Agent 在特定场景下应当如何工作。技能本身不是工具，它不提供新能力，而是为已有能力提供工作流程。

Agent 在会话中能看到的技能目录只包含名称与描述，技能正文在调用时才加载。因此描述写得准确，直接决定 Agent 能否在正确时机选用该技能。

2. 技能的存放位置

2.1 扫描路径

技能提供方按优先级顺序扫描以下根目录：

项目根目录指包含 .git 的最近祖先目录。若不存在，则使用当前 cwd。

优先级数值小的先扫描。同名技能由靠前的来源胜出。用户级 DSH 根会跳过其 .system 子目录。

需要区分两件事：技能名取自 frontmatter 的 name 字段，与所在目录名无关。上面的 <名称> 只是习惯写法，目录叫 foo 而 frontmatter 写 name: bar 时，对外呈现的是 bar。目录名不规范不影响加载，frontmatter 的 name 不规范才会被丢弃。

此表只说明扫描哪些目录，不代表需要做配置：includeDefaultRoots 默认为 true，项目根与用户根默认全部扫描（见 2.3 节）。

2.2 本机路径

本机的 DSH_HOME 已配置为 D:\APP_Install\24_deepseek-harness\home，因此用户级技能目录是：

<DSH_HOME>\skills\

该目录存放对所有项目生效的技能。仅对某个项目生效的技能应放在该项目根目录下的 .dsh/skills。

本文档配套的技能仓库

本机这套技能来自 https://github.com/HaroldFrey/frey-skills，主题是 FPGA 开发全流程与 Bash 脚本工程化。想直接使用这套技能，就从这里开始：

git clone \  https://github.com/HaroldFrey/frey-skills.git \  C:\Users\<用户名>\.claude\skills

仓库根目录下每个子目录就是一个技能（<名称>/SKILL.md），与第 3 节的格式要求一致；仓库整体是静态文件，克隆后无需构建。

注意：不要克隆到 <DSH_HOME>/skills 里。 那样会得到 <DSH_HOME>/skills\frey-skills\<名称>\SKILL.md，而 DSH 只扫描根目录下一层（见 3.1 节），仓库整体落在第二层，结果是一个技能都不会被发现。正确做法是克隆到别处，再按第 5 节把技能接进来——5.2（直接复制）与 5.3（目录联接）任选其一。

本机当前状态

• D:\APP_Install\24_deepseek-harness\home\skills\ 已存在，里面不是技能副本，而是指向 C:\Users\28968\.claude\skills 的目录联接，一处一个：

  这样技能只在 C:\Users\28968\.claude\skills 维护一份，DSH 与 Claude Code 共用。建立与删除联接的命令见 5.3 节。

• full-review\
   —— 指向 C:\Users\28968\.claude\skills\full-review
• vivado-synth\
   —— 指向 C:\Users\28968\.claude\skills\vivado-synth
• … —— 其余技能同理
• D:\APP_Install\24_deepseek-harness\home\skills\

• DSH_AGENTS_HOME 由启动脚本设为 D:\APP_Install\24_deepseek-harness\agents，但若当前终端是旧环境，该变量可能为空，此时 user-agents 根会回退到 C:\Users\<用户名>\.agents\skills。该目录不存在也不影响使用，只是少一个扫描根。

2.3 是否需要额外配置

不需要。技能提供方的 includeDefaultRoots 默认值为 true，上述项目根与用户根默认全部扫描。

<DSH_HOME>/skills 目录若不存在，需手工创建。

3. 技能的格式

3.1 两种组织形式

不支持嵌套发现，即 <根目录>/<子目录>/<名称>/SKILL.md 不会被扫描到。目录联接之所以可用，是因为它被当作真正的目录处理，联接出来的 <名称> 仍在根目录的第一层。

3.2 名称规则

技能名称必须为 kebab-case，正则约束为 ^[a-z0-9]+(?:-[a-z0-9]+)*$。只允许小写字母、数字与连字符。

3.3 frontmatter 字段

技能文件以 YAML frontmatter 开头：

---name:my-skilldescription:说明技能做什么、何时使用。---技能正文写在这里。

两个布尔字段接受 YAML 布尔值，以及不区分大小写的 true/false、yes/no、on/off、1/0。

注意，会导致技能被整体丢弃的是下面两类，且都会输出警告：

而真拼写错误（如 disable-model-invocaton，少一个 i）走的是下一条规则：DSH 不把它当成这两个字段，因而静默忽略，技能照常加载，只是你想要的排除效果没有生效。也就是说，拼错不会报错，反而更隐蔽，写完应到 Trajectory 视图确认结果符合预期。

未列出的 frontmatter 字段不参与技能的领域模型，会被忽略。

4. 从 Claude Code 迁移技能

4.1 格式对照

结构与必填字段一致，因此 Claude Code 的技能可以直接迁移。差异只在于部分可选字段不被读取。

补充说明 allowed-tools。 DSH 的 frontmatter 只认上表列出的字段，allowed-tools 不在其中，会被当作未知字段忽略，因此这个白名单在 DSH 侧完全不起作用。技能本身只提供指令、不改变权限；真正决定 Agent 能做什么的是所选预设挂载了哪些工具，以及工作区范围与审批策略。

graph 一类纯自定义字段同样不参与 DSH 的领域模型，保留它们不会报错。

4.2 需要注意的两点

工具限制会失效。allowed-tools 不被 DSH 读取，技能声明中的工具白名单不再生效。若该限制对技能的正确性重要，需要在预设或权限策略层面另行约束。

附件路径需自行确认。 技能若引用了同目录下的附属文件，DSH 会按技能目录解析相对路径，通常可直接工作；若引用了绝对路径且指向 Claude Code 的目录，需相应调整。

这里要区分读和写：技能目录一般位于工作区之外（本机的 C:\Users\28968\.claude\skills 就是如此），按默认的 workspace-write 策略，Agent 读取这类附属文件不受限制，但写入或修改会落在工作区之外而被沙箱拦下，需要一次单独的升权审批。若技能要求 Agent 就地修改自己的附属文件，应先把技能放进工作区，或调整权限策略。

5. 部署方式

以下四种方式任选其一。5.2 与 5.3 可直接使用；5.4 在 Web UI 下不生效，仅作为原理说明与「确实需要自定义预设时」的入口。

5.1 使用本文档配套的技能仓库

技能集发布在 https://github.com/HaroldFrey/frey-skills，说明与克隆命令见 2.2 节。

仓库的 git clone 只负责把文件拿到本地，让它被 DSH 扫描到还需要下面的步骤：克隆到 <DSH_HOME>/skills 之外的位置，再用 5.2 或 5.3 接进来。实际推荐 5.3（目录联接）——技能仍由 git pull 统一更新，不存在第二份副本；5.2 适合你希望 DSH 与 Claude Code 使用不同技能集的情况。

若不想建联接，也可以把仓库根目录直接加进 customSkillDirs（见 2.1 节），但该配置在 Web UI 下不生效，原因见 5.4 节。

5.2 直接复制

把技能目录复制到 <DSH_HOME>/skills 下。

适用场景：技能不常更新，或希望 DSH 使用与 Claude Code 不同的技能集。

优点：互不影响，DSH 侧可自由增删改。

缺点：两份副本需要分别维护。若技能来自远程仓库，更新后需重新复制。

5.3 目录联接

在 <DSH_HOME>/skills 下为每个技能建立目录联接，指向技能的真实位置。

适用场景：技能由远程仓库统一维护，不希望存在两份副本。

注意：联接必须建在每个技能这一层，不能对整个技能目录建一个联接。DSH 只扫描根目录下一层的 <名称>/SKILL.md，不递归查找嵌套目录。

Windows 上的实现选择：

推荐使用目录联接，它不需要管理员权限，且允许跨盘符。

建立联接，在命令提示符中执行：

mklink /J ^  "<DSH_HOME>\skills\full-review" ^  "<技能源目录>\full-review"

命令中的 <技能源目录> 指技能的真实存放位置，本机为 C:\Users\28968\.claude\skills。

批量建立，在批处理文件中使用：

FOR /D %%dIN ("<技能源目录>\*") DO ^  mklink /J "<DSH_HOME>\skills\%%~nxd" ^  "%%d"

删除联接：

rmdir "<DSH_HOME>\skills\full-review"

删除联接只移除链接本身，不会删除目标目录的内容。不要对联接使用带 /S 参数的删除命令，避免误删目标内容。

在 Git Bash 中的注意事项：ln -s 默认可能创建副本而非链接。需要使用 cmd 调用 mklink，或设置 MSYS=winsymlinks:nativestrict 后再使用 ln -s。

5.4 配置扫描目录（在 Web 上不适用）

有一种做法是改配置、把技能所在目录直接加入扫描列表，不做复制也不做链接。看起来很干净，但在 Web UI 下不生效，原因如下。（下面示例写的是权限更高的目录；仓库整体的布局问题另见 2.2 节的警告。）

配置位置：profile 的补丁文件，路径为 <DSH_HOME>/profiles/web/cordis.patch.yml。

若照此配置：

-id:skill-filesystemname:'@deepseek-ai/dsh-skill-filesystem'config:customSkillDirs:-C:\Users\28968\.claude\skills

为什么不生效：这条补丁命中的是 host 平面的 skill-filesystem 行，而 dsh-web-app 已经把该行置为 disabled: true——Web 界面刻意不在这里发现技能，改由每个会话的预设自行挂载。会话里真正生效的，是预设作用域内那一行 skill-filesystem（见第 6 节）。两者作用域不同，补丁改不到后者。

如果确实想走配置路线，正确做法是复制一份预设再改，改动位置在预设自己的组合文件里：

• <DSH_HOME>\.agent-presets\<你的预设 id>\agent.cordis.yml

复制 agent-presets 包内 presets/standard/ 整个目录到该位置后，修改其中的 skill-filesystem 行。注意两点：

• 预设里的 config 会整体替换该行的配置，不是合并。写了 customSkillDirs 就等于放弃原来的默认根，而 <DSH_HOME>/skills 正是来自默认根——若不显式带回，用户级技能会一起消失。
• 作者目录是 <DSH_HOME>/.agent-presets，不是 <DSH_HOME>/skills，两者用途不同。

需要说明的是，复制预设后改写这一路径本机未实测，属于依据「预设作用域与配置替换规则」推出的做法，改完应到 Trajectory 视图确认技能目录符合预期。

结论：只是想把自己的技能接进来，用 5.2 或 5.3 更简单可靠；只有需要「一套完全自定义的根 + 自定义工具/提示词」时，才值得走预设复制这条路。

6. 生效条件

6.1 预设模式决定技能是否可用

技能要在会话中可用，以下两个组件必须启用：

这两个组件在两个平面上各有一行，容易混淆：

• host 平面
  ：web profile 把这两行置为 disabled: true。Web 界面刻意不在这里发现技能，而是把 agent 平面的能力整体交给预设。
• 预设平面
  ：每个预设在自己的组合文件里重新声明这两行，会话真正用的是这一份。

各预设的实际状态（依据已装包 @deepseek-ai/dsh-agent-presets 的 presets/*/agent.cordis.yml）：

Web 的默认预设是 standard，因此默认创建的会话就能用技能，不需要额外操作。

预设模式在会话创建时固定，之后修改预设选择或默认值只影响此后新建的会话；已提交过内容的会话不能中途切换预设。

创建自定义预设的目录是 <DSH_HOME>/.agent-presets/<id>/，与技能根目录是两回事。

6.2 热重载

技能提供方会监视各扫描根目录（深度 1）。新增、改名或删除技能无需重启服务，会在下一个模型步骤前刷新；技能包内的附属文件改动不会触发刷新。

7. 验证方法

7.1 使用 Trajectory 视图

在 Web UI 中打开 Trajectory 视图，查看系统提示词。技能若加载成功，其名称与描述会出现在 Agent 可见的技能目录中。

该方式是直接观察实际注入模型的内容，不依赖 Agent 的自述，可作为准确判断依据。

7.2 分步验证

出现问题时，按以下顺序逐步定位：

1. 先只放一个基础技能。选择 frontmatter 只有 name 与 description 的技能，避免引入其他变量。
2. 启动服务，新建会话时选择标准模式。
3. 打开 Trajectory 视图，确认该技能出现在目录中。
4. 再放入一个带附加字段的技能，例如包含 allowed-tools 的技能，确认其仍能出现。
5. 全部确认后，再放入完整技能集。

7.3 常见故障定位

8. 常见问题

技能放在项目里还是用户目录。

放在项目根目录的 .dsh/skills 下，只对该项目生效，优先级也更高。放在 <DSH_HOME>/skills 下对所有项目生效。同名时项目级胜出。

Agent 不主动使用技能。

技能是否被调用由 Agent 根据 description 判断。把描述写清楚，说明技能做什么以及何时该用，能显著提高被选中的概率。

技能与权限策略的关系。

技能只提供指令，不改变权限。技能要求 Agent 执行的操作仍受工作区范围与审批策略约束。

没有现成技能可用，从哪里获取。

可用 https://github.com/HaroldFrey/frey-skills 这套技能集起步，取用方式见 2.2 节。要自己写技能，可用配套的 /skill-maker 工作流，它会按制作流程引导你完成创建与迭代。

9. 参考来源

本文档配套技能仓库

• frey-skills
  ：https://github.com/HaroldFrey/frey-skills本机正在使用的技能集，覆盖 FPGA 开发全流程（Verilog/SV 编码、Vivado 综合与仿真、时序分析）与 Bash 脚本工程化。取用方式见 2.2 节。

官方资源

• 技能子系统文档：https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/skills.md
• 项目仓库：https://github.com/deepseek-ai/deepseek-harness
• 官方文档站：https://deepseek-harness.github.io/deepseek-harness/

本文档事实依据

以下结论均取自官方仓库源码与文档，链接可直接打开核对。

如需转载，请联系作者获得授权(点击公众号主页的“联系我们”)