CH 17 · 插件安装
本章目标
CH 12 里你其实已经装过三个插件了——dsh-mcp-client、dshmarket、dsh-skill-mcp-panel，但那是"顺手装上、能用就行"，三种装法的门道没展开。这一章把装插件这件事系统过一遍：插件从哪来、装到哪、有哪几种装法、怎么管、装完怎么验证——最后亲手实操装一次，而且是直接让 dsh 帮你装。
先记住一句话：装插件 = 给某个 profile 加一个 npm 依赖。dsh 是"一切皆插件"（CH 08 讲过），但插件的"安装"本身走的是标准的包管理。搞明白装，CH 18 就开始自己写第一个插件。
先看你的安装现场
打开终端，先看 dsh 本体的版本：
dsh --version我这边输出：
0.1.1-rc.2再看 web profile 已经装了哪些插件：
dsh plugin --profile web list我这边输出（就是 CH 12 一路装出来的）：
Legend: production dependency, optional only, dev only
dsh-profile-web C:\Users\mortal\.dsh\profiles\web (PRIVATE)
│
│ dependencies:
├── @deepseek-ai/dsh-mcp-client@0.0.1-rc.1
├── dsh-skill-mcp-panel@2.0.1
└── dshmarket@1.40.0
3 packages注意，这三行正好对应三种装法：mcp-client 是命令行装的，dshmarket 是命令行装的市场本体，dsh-skill-mcp-panel 是在市场里一键装的——而它俩能直接进配置树生效，靠的是第三种机制 bundle 自动挂载。下面挨个讲。
插件从哪来：四种来源
一个插件本质是个 npm 包，来源就这几种：
| 来源 | 写法 | 什么时候用 |
|---|---|---|
| npm 包 | @deepseek-ai/dsh-mcp-client | 最常见。官方包带 @deepseek-ai/ 前缀，社区包用自己的 scope |
| GitHub 源码 | github:owner/repo | 想装某个仓库的主分支，没发 npm 包时用 |
| 本地目录 | . 或 file:../plugin | 自己开发插件时，直接装本机的 checkout，边改边试 |
| tarball / Release 产物 | 一个 .tgz 的 URL 或本地路径 | 作者只发了编译产物，比如 GitHub Release 里的附件 |
至于 CH 12 装的那个 dsh-market（插件市场），它不是新来源，而是一个图形化入口：装好之后在设置里就能浏览、搜索、一键装社区插件，背后调的还是上面这些来源。
装到哪：Profile 级，跟着 profile 走
dsh plugin 管理的是某个 profile 的插件，所以命令必须带 --profile <名字>，决定装到哪个环境。装完的包落在：
$DSH_HOME/profiles/<名字>/node_modulesWindows 上就是 C:\Users\<你的用户名>\.dsh\profiles\web\node_modules，由 pnpm 管理，同时写进 profile 的 package.json。
这里顺带说清一个容易混的点——全局和 Profile 的区别：
- dsh 本体是全局装的（当初
npm install -g @deepseek-ai/dsh），所有 profile 共用同一个 dsh。 - 插件默认是 per-profile 的：
dsh plugin --profile web add xxx只对 web 生效；想给 headless 也用，就得给 headless 也装一遍。 - 机器级配置是另一个层面：
$DSH_HOME/cordis.patch.yml是所有 profile 共享的（官方叫 "machine-local preferences"），而且优先级比 profile 自己的cordis.patch.yml更高——想让所有环境都吃同一套改动，就写这里。
先搞清楚这几个文件分别在哪，别混了。profile 级的在 C:\Users\<你的用户名>\.dsh\profiles\web\cordis.patch.yml（CH 12 里改 MCP 服务器配置的就是它）；机器级的在 C:\Users\<你的用户名>\.dsh\cordis.patch.yml——注意这个文件默认不存在，只有你手动写配置时才会创建，dsh 启动时会读它，不存在就跳过。所以想验证"我写的配置是不是机器级的"，就看它有没有出现在 .dsh 根目录下，而不是 profiles\<名字>\ 里。
- 官方自带的箱内 bundle（
@deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app这些）跟 dsh 装在一起，来自全局安装；你自己 add 的插件则装在 profile 自己的node_modules。
一句话记住：dsh 本体全局，插件跟着 profile，机器级补丁全站生效。
三种装法
① 命令行 dsh plugin：最根本
这是最底层的装法。dsh plugin --profile <名字> 会把后面的参数原样转发给 pnpm——所以 add、remove、update、why、list 这些 pnpm 的动词全都可用，写法也是 npm 包管理的写法：
dsh plugin --profile web add @deepseek-ai/dsh-mcp-client官方文档给的典型例子是装两个子代理插件（它们是可选 bundle）：
dsh plugin --profile web add @deepseek-ai/dsh-subagent-codex @deepseek-ai/dsh-subagent-claude-code
dsh plugin --profile web remove @deepseek-ai/dsh-subagent-codex用本地目录装自己写的插件也走这里——在插件源码目录里执行 dsh plugin --profile web add .，装的就是当前这个 checkout（相对路径会锚定到你执行命令的目录，而不是 profile 目录）。
② 插件市场 dsh-market：最省事
图形化装法。先把市场本体装上：
dsh plugin --profile web add dshmarket装完重启 dsh（bundle 变更要重启，下面讲），设置里就多出"插件市场"，能按分类浏览、搜索、一键安装社区插件。市场里装的插件大多刷新页面即生效，不用重启 dsh；个别 host 级插件会提示"待重启"，按提示操作即可。CH 12 里的 dsh-skill-mcp-panel 就是你在市场里搜出来一键装的。
③ bundle 自动挂载：装上就进配置树
先回答一个你一定疑惑过的现象：为什么 mcp-client 装完还要手动去 cordis.patch.yml 里 insert 服务器配置，而 dshmarket、dsh-skill-mcp-panel 装完什么都没配就能生效？答案在插件自己的 package.json 里——区别就在于有没有 dsh.bundle 声明。一个插件如果想"装上就自动进配置树"，它要在 manifest 里声明这个字段：
{
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
}
}
}dsh 在每次 dsh plugin 成功运行后，会对账 bundle 列表：凡是依赖里解析到带 dsh.bundle 声明的包，就自动把它加进这个 profile 的 bundle 层（配置文件树的最底层基础层，CH 08 讲过），不用你手动 insert。
举个例子，看两个带声明插件的 package.json。dshmarket@1.40.0：
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": { "inject": ["@deepseek-ai/dsh-client-connection", "..."], "platform": "web" }
}dsh-skill-mcp-panel@2.0.1：
"dsh": {
"client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-runtime", "..."] },
"bundle": { "patch": "./cordis.patch.yml" }
}两个都带 bundle.patch 声明，所以都自动进了 profile manifest 的 bundle 列表。打开 web profile 的 package.json，bundle 层长这样：
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-skill-mcp-panel",
"dshmarket"
]
}
}前两个是官方箱内 bundle（跟着 dsh 全局安装走的），后两个就是你装进去的、自动挂载的。而 dsh-mcp-client 呢？它没有 dsh.bundle 声明，所以只是普通依赖——出现在 profile 的 package.json 的 dependencies 里，但没进 bundles 列表。打个比方：bundle 插件像"自带安装说明书、开箱即用"的工具；普通依赖像"只有工具、没说明书"——东西到手了，dsh 不会自动加载它的能力，得你自己动手配。
dsh-mcp-client 就是后者：它是"连接 MCP 服务器的引擎"，知道怎么连，但不知道要连哪台。你得亲手告诉它连哪台服务器、地址是什么、密钥怎么传——这个动作就是往 cordis.patch.yml 里写一条 insert（往配置树里插入一行服务器配置）。CH 12 里你写 Firecrawl 那条配置，就是一次 insert。
另外注意到没有：这俩插件还带 dsh.client 声明（platform: web + inject 一串客户端插件）。这就是它们能往 Web UI 设置里加界面（插件市场、MCP 管理）的原因——既是 bundle（进配置树），又声明了客户端注入（进界面）。
一个必须记住的边界：bundle 成员（bundles 列表里的东西）变更后，要重启 profile 才生效——运行中的 profile 会保留它启动那一刻的 bundle 集合，新装的 bundle 要等下次启动才被加载。注意这里的"重启"只是为了让它自动加载，不是让你去手动配什么——bundle 插件加载完就开箱即用，不需要你碰配置。普通 cordis.patch.yml 的编辑走热重载、不用重启，但 add/remove/update 一个 bundle，重启跑不掉。CH 12 里 dshmarket 装完你重启过 dsh，就是为了让它自动加载。
管理命令速查
| 命令 | 作用 |
|---|---|
dsh plugin --profile web list | 列出这个 profile 装了什么（等价 pnpm list） |
dsh plugin --profile web add <来源> | 安装，来源见上面四种 |
dsh plugin --profile web remove <包名> | 移除 |
dsh plugin --profile web update <包名> | 更新到最新版（有 bundle 声明的会跟着重新对账） |
dsh plugin --profile web why <包名> | 看这个包为什么被装进来（谁依赖它） |
装完怎么验证装对了？两个手段：
- 看依赖和 bundle 归属：
dsh plugin --profile web list能看依赖；要看有没有进 bundle 层，直接翻 profile 的package.json（上面那种dsh.profile.bundles）。 - 看配置树里有没有真的挂上：
dsh --profile web --dump-config打完整的配置树，搜插件名；只想看 bundle 基础层用dsh --profile web --dump-default-config。
装三个真正用得上的社区插件
前面装的插件是为了讲机制，也是用的过程中真有需求——dsh 就是这样，想要什么装什么，一切皆插件。现在装三个"装完立刻提升体验"的社区插件，正好来自 GitHub 源码和 npm 两种来源。安装不用你敲命令行，直接一句话交给 dsh 就行。
dsh-theme：给 Web UI 换肤
一个独立的主题插件，装上后设置里多出「外观」（Appearance）：
- 亮色 / 暗色 / 跟随系统三种外观模式
- 15 套精选主题，其中 5 套阅读向主题 + 1 套代码向的 Carbon Code 主题
- 每套主题把颜色层级、UI 字体、代码字体、字号打包成一个整体配置，一键切换
- 还能实时单独调强调色、背景、前景、表面、侧边栏颜色
- 设置存在浏览器本地，刷新不丢（不跨浏览器、不跨 profile 同步）
想让 dsh 帮你装，在输入框发一句：
帮我把 dsh-theme 插件装到 web profile 并确认生效，它在 GitHub 的 oil-oil/dsh-theme 仓库。开源地址：oil-oil/dsh-theme。装完重启 web profile，设置 → 外观里就能换主题，长这样：
dsh-oil-sticky-prompt：滚动时把最近的用户消息钉在顶部
滚动长回复时，最新一条用户消息会变成一条紧凑的全宽条钉在对话顶部，点一下跳回原文：
- 单条吸附条，多个话题不会互相打架
- 原始换行压平成空格，最多两行
- 不修改消息、不动会话日志、不持久化设置
想让 dsh 帮你装，在输入框发一句：
帮我把 dsh-oil-sticky-prompt 插件装到 web profile 并确认生效，它在 GitHub 的 oil-oil/dsh-oil-sticky-prompt 仓库。开源地址：oil-oil/dsh-oil-sticky-prompt。装完重启 dsh。下图是 dsh 实际帮我装它的对话——它解释了 Peer 依赖告警是预期行为，并说明会在下次重启 web profile 时一起生效：
dsh-better-sidebar：把侧边栏变成完整工作台
功能最重的一个，把右侧栏升级成一套"工作台"。它的布局思路跟 Codex 这类 AI 编程工具的侧边栏是一个路子——把文件、终端、Git 都搬到 Agent 旁边，边看边干：
- 文件工作台：目录树 + 代码编辑器，图片 / Markdown / HTML / PDF / Office 内联预览
- 内嵌浏览器：多开网页 tab，内容跑在沙箱 iframe 里
- 真实终端：xterm + node-pty 跑真实 shell，断线重连，还能可选给模型注入终端工具
- Git 面板：真 diff、历史，右键暂存 / 提交 / 还原
- 后台任务页：看子代理拓扑和后台任务（退出码 / 实时输出 / 强制终止）
- 右侧栏 + 底部面板双工作台，布局按会话记忆
想让 dsh 帮你装，在输入框发一句：
帮我把 dsh-better-sidebar 插件装到 web profile 并确认生效，它在 GitHub 的 omdsh-dev/DSH-better-sidebar 仓库（npm 包名 dsh-better-sidebar）。开源地址：omdsh-dev/DSH-better-sidebar。装完重启 dsh，再硬刷新浏览器就能看到侧边栏（它是 bundle 成员，重启才加载），右侧文件浏览器 + 底部终端一起出现：
这三个都带
bundle声明，装上就自动挂载（③ 讲的机制）。GitHub 源码那两个第一次装如果被 pnpm 的 allowBuilds 拦了，按「常见坑」里那条处理。
常见坑
| 问题 | 怎么回事 | 怎么处理 |
|---|---|---|
| 装完界面没变化？ | 装的若是 bundle 成员，运行中的 profile 不会自动重新加载 | 重启 dsh 再进设置看 |
装 Git 源码插件第一次 add 报 allowBuilds 错？ | pnpm ≥10 默认阻止源码包跑 prepare 构建脚本 | 按报错打印的提示，把 allow key 复制进 profile 目录下的 pnpm-workspace.yaml，再重跑一次 add |
| 装 dsh-better-sidebar 报 "Ignored build scripts"？ | pnpm 11 拦截了 node-pty 这类原生模块的构建脚本 | 在 profile 目录（C:\Users\<你的用户名>\.dsh\profiles\web）跑 pnpm approve-builds --all，再硬刷新 |
| 装完出现两个侧边栏？ | 之前手动挂载过的行和自动 bundle 双挂载了 | 删掉 cordis.patch.yml 里旧的 - insert: ... better-sidebar ... 手动挂载行 |
| 装到别的环境去了？ | --profile 决定装到哪 | 确认命令里的 profile 名是你要的那个（web / headless …） |
| 装完不生效、也没报错？ | 装的可能是普通依赖（没有 dsh.bundle 声明） | 它只是"包到位"，能力要自己在 cordis.patch.yml 里 insert 才接上（mcp-client 就是典型） |
这一章你学到了什么
能自己完成下面几条，就算过关：
- [ ] 能说出插件的四种来源（npm / GitHub / 本地目录 / tarball），以及插件市场不是来源而是图形入口
- [ ] 知道
dsh plugin --profile <名字>管理的是某个 profile 的插件，装进它的node_modules - [ ] 能分清：dsh 本体全局安装、插件 per-profile、
$DSH_HOME/cordis.patch.yml机器级全站生效 - [ ] 会用三种装法：命令行 add / 市场一键装 / 依赖带
dsh.bundle声明自动挂载 - [ ] 能说出三个社区插件的用途（dsh-theme 换肤 / dsh-oil-sticky-prompt 吸附提示条 / dsh-better-sidebar 侧边栏工作台），并亲手把它们装好
- [ ] 知道 bundle 成员变更要重启 profile，普通 patch 编辑走热重载
- [ ] 会
list/remove/update管理插件，用--dump-config验证装没装进配置树