dsh-plugin-dedupe：給 DSH profile 加一道插件去重檢查

前言¶

用 DSH 時，插件一般裝在 profile 目錄裏，由 profile 的 package.json 統一管理。裝得多了會出現一個問題：同一個插件可能被聲明兩次，比如一次來自 github:、一次來自本地 file:，包名相同、來源不同，結果 node_modules 裏同名包多份並存，輕則佔空間，重則讓運行時加載到錯誤版本，排查起來很費時間。

dsh-plugin-dedupe 解決的就是這件事：在安裝前掃描 profile，發現重複聲明直接阻斷安裝。下面介紹它的功能、安裝和使用方式。

這是什麼¶

dsh-plugin-dedupe（DSH 插件去重守護）是 Jiaoyc224 維護的開源插件，MIT 許可證，當前版本 0.1.0。一句話定位：防止在 DSH profile 中重複安裝同一插件。

它有兩種工作方式：

1、作爲 DSH 插件加載時，啓動階段自動掃描當前 profile 的 package.json 依賴和 node_modules 實際安裝情況；
2、作爲 pnpm install 的 preinstall 鉤子，在安裝前運行檢查腳本，發現錯誤時返回非零退出碼，阻斷安裝。

它在 package.json 中聲明瞭 peerDependencies: @deepseek-ai/cordis ^4.0.1，且標記爲 optional。

它檢查什麼¶

檢測邏輯分兩層：先解析 package.json 的 dependencies / devDependencies / optionalDependencies / peerDependencies，再掃描 node_modules 統計實際安裝的包名。具體規則如下：

檢測類型	行爲	說明
同名依賴重複聲明（不同來源）	錯誤	同一包名在 `package.json` 中出現多個不同來源，如 github + file
同名依賴多字段聲明（同一來源）	警告	同一包在 `dependencies`/`devDependencies` 中聲明且來源協議相同
`node_modules` 同名包多次	警告	同名包在 `node_modules` 中出現多次（不同版本/來源並存）
未聲明但已安裝的 `dsh-*` 插件	警告	可能是舊殘留或手動複製進來的

只有「不同來源的重複聲明」算錯誤，會阻斷安裝；其餘情況降級爲警告。實際的阻斷輸出大致是這樣：

[dsh-plugin-dedupe] 掃描 profile: C:\Users\<your-user>\.dsh\profiles\web
❌ 檢測到重複聲明: "dsh-agent-teams" 在 package.json 中有多個來源:
   github:NanmiCoder/dsh-agent-teams
   file:E:/fake/dsh-agent-teams
[dsh-plugin-dedupe] 檢測到 1 個重複插件錯誤，已阻斷安裝。

安裝¶

在 DSH profile 目錄下直接安裝：

cd <your-dsh-profile-dir>  # 例如: C:\Users\<user>\.dsh\profiles\web
pnpm add github:Jiaoyc224/dsh-plugin-dedupe

或者使用 dsh plugin 命令：

dsh plugin --profile web add github:Jiaoyc224/dsh-plugin-dedupe

啓用 preinstall 鉤子¶

preinstall 鉤子需要手動添加。編輯 profile 的 package.json，在 scripts 中加入：

{
  "scripts": {
    "preinstall": "node node_modules/dsh-plugin-dedupe/scripts/check-duplicates.mjs"
  }
}

這樣每次運行 pnpm install 前，都會先執行去重檢查，發現重複插件會返回非零退出碼，阻斷安裝。

有一個首次安裝的注意點：剛裝完插件後，需要先運行一次 pnpm install 生成 node_modules/dsh-plugin-dedupe，其後的 pnpm install 纔會觸發 preinstall 鉤子。這一步可以用 pnpm install --prefer-offline 避免死循環。

獨立運行檢查¶

不想掛鉤子的話，檢查腳本可以單獨運行：

# 在 profile 根目錄下
node node_modules/dsh-plugin-dedupe/scripts/check-duplicates.mjs

# 或指定 profile 目錄
node node_modules/dsh-plugin-dedupe/scripts/check-duplicates.mjs --profile /path/to/profile

插件的 bin 字段也提供了 dsh-dedupe 命令，指向同一個檢查腳本。

環境變量配置¶

插件支持兩個環境變量：

環境變量	說明	默認值
`DSH_DEDUPE_WARN_ORPHANS`	設爲 `true` 時也警告非插件類的未聲明依賴	`false`
`DSH_PROFILE_DIR`	手動指定 profile 根目錄	自動向上查找

適用場景與注意¶

適合的場景很明確：profile 裏插件數量多、來源雜（npm、github、本地 file、link 混用），或者經常在本地調試插件、需要來回切換來源的 DSH / 智能體開發者。如果你只有一個 profile、只從單一來源裝插件，這個插件的作用有限。

幾點注意：

1、插件以當前 dsh 進程的權限運行，安裝第三方插件前建議先檢查其源碼和許可證；
2、preinstall 鉤子只對 pnpm install 生效，需要手動在 profile 的 package.json 中配置；
3、錯誤（阻斷安裝）和警告（僅提示）的邊界見上文規則表，按需通過 DSH_DEDUPE_WARN_ORPHANS 調整未聲明依賴的提醒力度。

結尾¶

dsh-plugin-dedupe 做的事情很小但很實際：把「插件重複安裝」從事後排查變成安裝前攔截。如果你在 DSH profile 管理上遇到過同名插件多來源並存的問題，值得一試。

社區目錄頁：https://www.skillhub.cn/plugins/Jiaoyc224/dsh-plugin-dedupe
GitHub 倉庫：https://github.com/Jiaoyc224/dsh-plugin-dedupe