前言¶

在 DeepSeek Harness（DSH）里，Skill 通常通过宿主或预设里的 customSkillDirs 指向一组根目录。所有项目共用同一套配置：无法表达「项目 A 只要写作类、项目 B 只要工具类」；若 Skill 库按 category/skill/SKILL.md 分层，只指向父目录往往扫不到任何 Skill，且没有明显报错。从 Hermes 迁过来的人还会习惯「中央库 + 各项目按需链接」的做法——DSH 原生并不等价提供项目级路径清单。

下面介绍社区插件 dsh-skills-symlink（维护者 MYSTERY2019，GitHub 分类为工作流向插件）。它在每个项目根下用 .dsh/skill-paths.yaml 声明本项目要加载的路径，并通过插件配置里的 maxDepth 支持多级目录发现，名称借用了 Hermes 的 skill symlink 说法，但插件本身不创建符号链接。

这是什么¶

dsh-skills-symlink 把 Skill 根路径从宿主/预设挪到项目内：一个项目一份 skill-paths.yaml，其它项目不受影响。同一份中央 Skill 库，不同项目可以只加载各自列出的目录或分类，从而缩小每轮进入上下文的 Skill 名称与描述集合（相对「整库挂进 customSkillDirs」）。

仓库：https://github.com/MYSTERY2019/dsh-skills-symlink
SkillHub 目录页：https://www.skillhub.cn/plugins/MYSTERY2019/dsh-skills-symlink
当前发布版本（资料中的安装 tag）：v0.4.0。

核心功能¶

1. 项目级路径文件：在项目根（最近的 Git 根，否则为会话工作目录）放置 .dsh/skill-paths.yaml，字段为 version 与 skillPaths（相对路径列表）。
2. 多级目录扫描：Skill 布局为 root/category/skill/SKILL.md 时，项目文件仍只写父路径（例如 skills），在 profile 的插件行里设置 maxDepth（1–6，默认 1）控制向下扫描层数。
3. 外部路径可选：引用项目外的共享库（含 ..、绝对路径、指向项目外的符号链接）需在插件行开启 allowExternalPaths: true，否则该条目会被跳过并在日志中说明。
4. 插件页概览：DSH 侧边栏 Plugins → dsh-skills-symlink 可查看各项目的 Skill 概览、展开后的目录树与分类统计（资料中的 Skills overview 一节）。
5. 变更生效时机：Skill 在会话启动时读取；修改路径或新增 Skill 后，通常要在下一次新会话中才会反映；插件支持 watch 监视目录（默认可配置）。

maxDepth、ignore、allowExternalPaths 等写在项目 yaml 里不会生效；插件会忽略并在日志中提示应写在插件行。无效条目（非字符串、未允许的外部路径等）会被单独跳过，不阻断 DSH 启动。

安装与启用¶

环境要求（来自 README）：

• DSH：>=0.2.1-rc.5 且 <0.3.0（0.2.x 线）
• Node.js：^22.19.0 || >=24.0.0
• 从 GitHub 安装时需要能访问 GitHub

DSH Desktop：侧边栏打开 Plugins，添加：

github:MYSTERY2019/dsh-skills-symlink#v0.4.0

安装后重启 DSH；插件页应出现 dsh-skills-symlink。0.2.x 的 dsh CLI 不支持 --profile desktop，Desktop 只能通过插件页安装。

其它 profile（例如 web） 在命令行执行：

dsh plugin --profile web add github:MYSTERY2019/dsh-skills-symlink#v0.4.0

也可从 Release 下载 dsh-skills-symlink-0.4.0.tgz，用本地路径代替 github:... 规格安装。

若曾在 2026-11-04 之前装过被移动的 v0.4.0 tag，已有安装不会自动更新：需先移除再按上面命令重装。

插件以当前 DSH 进程权限运行；安装前请自行查看仓库源码与 LICENSE，确认符合你的安全与合规要求。

典型用法¶

1. 项目内两个 Skill 目录¶

在项目根创建 .dsh/skill-paths.yaml：

version: 1
skillPaths:
  - skills
  - tools/skills

本项目只会加载上述两个目录下的 Skill；其它未配置该文件或未列出路径的项目不会看到这些根。

2. 分层 Skill 库（单路径 + maxDepth）¶

库结构为 skills/某分类/某技能/SKILL.md 时，项目文件仍写：

version: 1
skillPaths:
  - skills

在 profile 的 cordis.patch.yml 中覆盖插件行（注意：覆盖 config 时会整段替换，不会与默认值合并）：

- id: dsh-skills-symlink
  config:
    maxDepth: 2
    allowExternalPaths: true
    ignore:
      - _archive

3. 引用项目外的共享库¶

# 插件行需 allowExternalPaths: true
version: 1
skillPaths:
  - ../shared-skills

4. 安装后自检¶

重启后可在项目目录运行包内脚本（Desktop profile 路径示例）：

node ~/.dsh/profiles/desktop/node_modules/dsh-skills-symlink/scripts/post-install-check.mjs --project .

输出包括实际加载的插件版本、本项目解析到的各根目录；版本不一致、缺少插件行或缺少项目配置文件时会列为问题并以退出码 1 结束。可用 --profile 指定其它 profile，或 --json 供脚本解析。

适用场景与注意¶

适合谁

• 多仓库或多项目共用一套 Skill 中央库，但希望按项目裁剪可见 Skill 集合的团队或个人。
• Skill 按分类目录组织，不想为每个分类单独写一条 customSkillDirs 根，也不想复制 Skill 文件。
• 从 Hermes「中央库 + 项目按需引用」习惯迁移到 DSH 0.2.x 的开发者。

使用时注意

• 新增与已有条目并列的顶层分类时，若项目 yaml 是按分类逐行列举的，需要每个项目加一行；或改为列举共同的父路径并配合合适的 maxDepth。
• 深度超过 maxDepth 的 Skill 不会被加载，对应根可能显示 0 个 Skill；可增大 maxDepth 或调整目录结构。包内 post-install-check.mjs 对「根解析为 0 但更深一层存在 SKILL.md」的情况有提示。
• 插件配置项完整列表与默认值见 README Configuration 表（如 maxRoots、watch、configWatchIntervalMs、logFile 等）；数值越界或非整数会回退默认并打警告，不会阻止 DSH 启动。
• SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；插件归属维护者与开源许可证以 GitHub 仓库为准。

结尾¶

dsh-skills-symlink 把 Hermes 时代「每项目一套 Skill 视图」的思路落到 DSH：路径进项目、多级分类靠 maxDepth、可选外部库与插件页概览便于核对。若你正在 0.2.x 上维护多项目 Skill 库，可按上文安装命令启用，并用 skill-paths.yaml 与 cordis.patch.yml 对齐你的目录结构。

• 目录页：https://www.skillhub.cn/plugins/MYSTERY2019/dsh-skills-symlink
• 源码与文档：https://github.com/MYSTERY2019/dsh-skills-symlink