前言¶

在 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