插件生命周期管理：装了就要能拔（Plugin Lifecycle）

适用：所有 dsh 用户，尤其是"装了一堆插件想清理"的人。本章讲官方 dsh plugin 命令的边界，以及用 dsh-unplug 做到"所有插件插拔自如"：列出、完整卸载、禁用不删、一键修复。

1. 官方能做什么，不能做什么

官方 dsh plugin 有两个基本概念：

• bundle：npm 包，manifest 声明 dsh.bundle.patch，装进 profile 的 dsh.profile.bundles 列表；
• patch 行：cordis.patch.yml 里 - insert: / - override: 下列出的插件行（profile 和 home 各有一份）。

dsh plugin --profile <name> add <pkg> 会同时写 bundles 列表 + pnpm 依赖；dsh plugin --profile <name> remove <pkg> 只处理 bundles 列表和依赖。它不管：

1. profile/home cordis.patch.yml 里残留的插件行；

2. "先禁用不删"（disable），之后想恢复（enable）；

3. 拔完之后的残留审计（孤儿行、悬空 bundle）。

这就是"装了好装、拔不下来"的真实来源。

2. 安装 dsh-unplug

dsh plugin add dsh-unplug

零运行时依赖、默认只读；破坏性操作必须显式确认（CLI --yes / --force，agent 工具 force: true）。

3. 日常三件套

dsh-unplug                    # 什么都不输：直接给你中文菜单
dsh-unplug list               # 看看装了什么（bundles + 补丁行）
dsh-unplug fix --yes          # 一键修复：清掉悬空 bundle 和孤立补丁行

装多了想清理：

dsh-unplug remove <插件> --yes          # 完整卸载（bundle + 补丁行 + 依赖）
dsh-unplug remove --dry-run <插件>      # 先预览会删什么，不执行
dsh-unplug disable <插件>               # 临时禁用不删，随时 enable 恢复
dsh-unplug enable <插件>

忘记插件名？直接 dsh-unplug remove，它会列出当前已装的插件和可直接复制的命令。

4. 它到底改了什么

层	remove 做什么	disable 做什么
dsh.profile.bundles	移出列表	移入 disabledBundles
dependencies	pnpm remove	保留
profile cordis.patch.yml	删除该插件行	行上加 disabled: true
home cordis.patch.yml	同上	同上
残留	删完自动重跑 audit	—

reconcile / fix 则反过来：把 bundles 列表里解析不了的包、补丁行里引用不存在包的记录，一次性清掉。

5. 审计与排查

dsh-unplug audit --json       # 机器可读：孤儿行 / 悬空 bundle / 缺失 patch 文件
dsh-unplug list --all         # 一次看所有 profile

真实环境建议：每次升级或"拔插件后 dsh 起不来"时，先跑 dsh-unplug audit，再看 dsh --profile <name> --dump-config 对照。

6. 注意

• remove 是破坏性操作：会删依赖、改 patch 文件。先 --dry-run 再 --yes；
• 官方 bundle 自带的 patch 行（如 @deepseek-ai/dsh-base 内部的工具行）不是孤儿——audit 只对 profile/home 层报孤儿；
• 本插件仓库：github.com/zoahdev/dsh-unplug（npm: dsh-unplug）。