6.2 插件
本节目标
搞清楚 dsh 里管理插件的入口:侧栏插件页管安装、启停和配置,设置里的内置插件页看只读清单。
管理插件的入口在哪
0.1.6-alpha.2 起,插件管理整体搬了家,记住两句话:
- 要动手(装、关、开、配),去侧栏的插件页
- 只想看(部署里随附了哪些插件),去设置的内置插件页
设置面板里的内置插件分区现在是纯只读清单:列出本部署随附的全部插件,让你核对有什么、状态正不正常,不能在这里改行为。

侧栏插件页:插件的「应用管理器」
打开左侧栏的插件入口(它是全局页面,不属于某个会话)。页头是标题插件和说明「安装、启用和配置插件」,右侧有插件说明与刷新两个按钮,再往下是分离按钮添加插件。0.2.1-alpha.2 起这一页重新排过版(PR #5922):不再是"官方 / 已安装"两组,而是三段——
- 内置插件配置:开放了配置页的官方插件,固定四张卡,顺序是子智能体(「设置子智能体的递归层级、数量和模型。」)、网页搜索(「设置 DeepSeek 的搜索提供方。」)、Agent 循环(「控制 Agent 派发工具调用的方式。」)、终端(「限制每条命令最多能跑多久、最多输出多少内容。」)。点开卡片就是它自己的配置表单
- 实验性插件:安装随附、默认关闭的官方组合包,每条带实验性标记,开关一打就启用,但不提供卸载。主列表常显四条:智能体团队、语音输入、自动授权审查、开发者工具(查看调试会话原始数据、聊天消息分组数据,以及调试 NodeJS 后端)。0.2.1-alpha.2 起这一段标题右侧多了更多按钮,点开是完整的实验性插件目录,把其余默认收起的包一次列全:Git 工作树、思考过程机器翻译、持久终端、会话搜索、随对话更新的标题、DSH 徽章技能、Ralph 循环、自定义插件市场、Codex 子智能体、Claude Code 子智能体。从目录里启用过的包会升入主列表,不用回目录里翻。其中自定义插件市场(0.2.1-alpha.4 起)启用后会在插件页顶部加出一个发现标签页:点管理索引源添加第三方市场的索引 URL(形如
https://example.com/index.json),就能在页面里浏览并安装该市场的插件,不必再依赖 9.1 节那个独立部署的市场站 - 已安装插件:当前 profile 里装着的组合包,可启停、可卸载(卸载要求确认)
顺带更正两处旧表述
界面里没有叫「官方」的分组标题,official 只是代码里的标记;教程此前把"内置插件配置 + 实验性插件"合写成"官方"一组,看页面时按上面三段找。0.2.0-rc.1/rc.2 时期的自动化任务组合包已退役:定时提醒 0.2.1-alpha.1 起直接内置(见 4.11 节),插件页不再有这个条目。
每张卡片极简:名称、一句话简介、开关;点进组合包详情页能看到完整 npm 包名和它包含的插件行,每行有自己的开关。拨动开关会写入 profile 的组合包层或 cordis.patch.yml 的行覆盖:开了 HMR 的部署立即重组生效,页面不用刷新;没开 HMR 或被更高层覆盖的变更会弹 toast 说明。某个行被其他行依赖时,关掉它前会先问你。
组合包详情页还能看到来源
0.2.1-alpha.1 起,组合包详情页的插件行列表后面多了一个来源信息区块:第三方组合包显示在别处安装它所需的完整 spec(pnpm add 接受的形式,Git 地址、压缩包、本地路径都原样给出),安装随附的官方组合包则显示内置,随后是当前版本。想给另一台机器装同一个插件,照抄这行 spec 就行。
在插件页配置官方插件
原来散在设置里的插件配置区,现在以配置页的形式长在插件页里。部署组装了哪个插件,它的卡片就出现哪个,常见的是这四个:
| 插件 | 控制什么 | 可调参数 |
|---|---|---|
| 终端 | agent 跑命令的边界 | 命令超时、命令输出上限 |
| Agent 循环 | agent 一步能并行派发几个工具调用 | 最大并行工具调用数 |
| 子智能体 | 委派的深度与并发、子代理模型 | 最大递归深度、子智能体并行数量上限、模型选择 |
| 网页搜索 | DeepSeek 的搜索与抓取走哪条路 | 启用新版 Web 搜索 API、API Key、基础地址、搜索次数 / 结果数 |
逐个说关键的:
终端:卡片标题就叫终端。它给 agent 的命令执行兜底,卡片里有两个参数:
- 命令超时:单条命令最长执行多久,超过自动中断。默认 120000 毫秒(2 分钟)。跑长任务(构建、测试)时可以调大
- 命令输出上限:一条命令的输出最多保留多少字节,防止输出刷屏把对话上下文撑爆。输出超出的部分会被截断
注意:它管理的是执行边界(超时和输出),不是命令白名单。agent 能跑什么命令由沙箱权限管(7.2 节)。
Agent 循环:控制 agent 一步内能并行派发多少个工具调用:最大并行工具调用数默认 10,即一步可以同时跑 10 个工具(比如并行读多个文件)。设成 1 就是串行,一个干完再干下一个,最稳但慢;调大更快但更激进。
子智能体:卡片名是中文的子智能体(教程此前写作 Subagent)。委派限制和模型选择放在同一页、共用一个保存按钮,参数原名分别是最大递归深度、子智能体并行数量上限和模型选择,详见 4.7 节。
网页搜索:这一张卡在本批变化最大,0.2.1-rc.2 起顶部多了一个开关启用新版 Web 搜索 API,下面的说明是「默认关闭,搜索通过 DeepSeek Messages 完成。新版 Web 搜索 API 功能与计费详见」,句尾跟着网页搜索与抓取指南的链接。
- 不开(默认):搜索由 DeepSeek Messages 的辅助模型完成,可调的是单次请求最多搜索次数(「辅助模型在一次 Messages 请求内最多可执行的搜索次数,仅适用于 Messages API。」),基础地址那行叫Messages API 基础地址
- 打开:改走 DeepSeek 官方的 Search API(搜网页)和 Fetch API(抓正文),两个参数跟着换掉——每次搜索结果数(「每个查询返回的结果条数,须为 1–50 的整数,默认 10;不控制搜索调用次数。」)取代搜索次数,基础地址一行改叫 Search / Fetch API 基础地址,默认
https://api.deepseek.com/v1/tools,程序自己在后面拼/search或/fetch,留空恢复默认
密钥还是同一个 API Key 输入框(提示「不写入设置文件。留空表示保持当前密钥。」)。差别在没填时的说法:以前是"账号登录不适用",0.2.1-rc.2 起改成「未配置密钥;仅使用 DeepSeek 账号模型的对话可以通过默认接口地址搜索。」——也就是说开了新版 API 之后,用 DeepSeek 账号登录的会话不必再单独配搜索密钥就能搜;只有走自定义端点的才需要自己填。这个开关只在部署同时装配了网页搜索和抓取 API 两个插件时才出现,看不到就说明本部署没带抓取能力。
配置页的编辑规则是草稿制:控件里改的都是暂存值,点保存才真正写入,离开页面草稿丢弃;保存失败会保留草稿让你改,不会悄悄覆盖别人的并发修改。
第三方插件的配置也在这
第三方组合包如果注册了配置页,配置就渲染在它自己的组合包详情页或行页面上,跟着组合包开关同生共死:关掉组合包,配置页一起消失。
实验性插件里能配的两样
0.2.1-alpha.2 起,语音输入组合包的详情页多了设备选择:配置区里三个下拉是输入设备、识别服务、识别语言。输入设备默认走系统默认(括号里带出当前设备名),下面按顺序列出麦克风 1、麦克风 2……选完下方有一条麦克风输入电平的实时跳动,对着说话看它动不动就知道选对没选对;设备不可用时直接提示「麦克风不可用,请选择其他输入设备」。家里有多个麦克风(摄像头自带、USB 声卡、耳机)的,这一项终于不用靠系统默认碰运气了。
0.2.1-alpha.2 起,思考过程机器翻译(实验性)可以在详情页挑翻译服务,翻译服务下拉给四项:Google、Bing、DeepSeek Flash · 账号(付费)、DeepSeek Flash · 官方 API(付费)。它的作用是把 agent 的思考过程翻成你看的界面语言,前两个不花钱,后两个走 DeepSeek 所以要计费。
安装一个新插件
插件页点添加插件,输入框接受包名(可带版本)、Git 地址、压缩包或本地绝对路径。不知道填什么,展开输入框下方的 不知道该填什么? 有三种常见形式的示例,一键填入。
0.2.1-alpha.1 起,这个按钮变成了带下拉箭头的分离按钮:主按钮直接打开安装对话框,点箭头则展开菜单选添加方式——安装第三方插件(同一个安装对话框)和让 Agent 创建插件,后者会关掉菜单、进入创造模式开一个新会话,把「做一个 DSH 插件」的活儿直接交给 agent。想自己动手写插件的读者,这个入口比从预设切换省一步。
流程是先检查再安装:
- 点安装后 Host 先读出这个 spec 指向什么:名字重复、注册表查无此包、路径不对、包里没有组合包内容,都会以一句话打回输入框让你改
- 通过检查进入安装界面,显示读到的包名、简介和版本,pnpm 的命令和输出折叠在查看安装详情里
- 装完提供立即启用:一键启用新包并滚到列表里它的位置;直接关掉则保持已安装但未启用
出错也有交代:注册表不可达、包不存在、磁盘满、profile 不可写、pnpm 拦下构建脚本,各自有一句人话说明,重试就在手边;pnpm 因为依赖的安装脚本罢工时,可以点允许这些脚本并重试,授权会写进 profile 的 pnpm-workspace.yaml。安装过程中随时可以取消安装,Host 会把 profile 文件恢复原样。
0.2.0-rc.2 起,如果已安装的某个插件版本与当前 dsh 不兼容,插件页会提示你重新安装兼容版本,而不是直接报错或继续运行;按提示操作会自动拉取合适的版本并替换。
0.2.1-alpha.3 起修掉了"更新或重装插件之后还在跑旧代码"这个问题。现在能热重载的包换完直接生效、页面不用刷;热重载覆盖不到的会明确告诉你得重启,提示原文是「请重启 DSH 使更改生效。」,后面接一句原因,五种原因各说各的事:「这个 profile 只在启动时应用更改。」「已安装的插件包解析到了另一个目录,或者更改替换了 DSH 安装自带的包。从其他位置安装前请先卸载。」「更改涉及 DSH 自身已加载的模块。」「更改涉及一个不受插件列表管理的插件。」「DSH 无法将已加载的插件与磁盘上的文件进行比较。」包已经装上但需要重启时,安装结果页写的是「已安装,请重启 DSH 加载它。」看到这类提示就照着重启,别以为装完没生效是市场的问题。
官方插件的更新是个独立动作,说明原文:「按需安装的官方插件会在版本与 DSH 不同时提供“更新”。其他插件请先卸载再安装新版。」——第三方包没有一键更新,想升版本得先卸载再装新的。
从哪个 npm 源下载:0.1.7-alpha.2 起,安装流程里会问一步安装源,三选一:
- 默认安装源:官方 npm 仓库
registry.npmjs.org - 中国大陆镜像源:
registry.npmmirror.com,检测到中国大陆网络出口时默认选中它 - 自定义地址:公司内网或私有 npm 源;需要登录的源,把凭据放在本机的
~/.npmrc里
GitHub 类安装失败时,也会提示改用镜像重试,不用自己折腾代理。多个注册表轮流询问,哪个先响应就用哪个,并记住你的选择。
不止市场里的插件
除了 9.1 节图形化市场里装的社区插件,dsh 还有一些官方可选 Profile 包不在市场货架上,比如把 Codex、Claude Code 接成子代理的能力包,装法和用法见 4.7 节。
插件和技能的关系
你可能会问:插件和 4.3 节说的技能告诉 agent 如何完成某类任务的说明书,在会话里用斜杠命令调用。(Skills)是一回事吗?
不完全一样,理解成两层:
- 技能告诉 agent 如何完成某类任务的说明书,在会话里用斜杠命令调用。是给 agent 用的"说明书",告诉它怎么完成某类任务
- 插件是能力的"零件",技能、工具、界面组件都是通过插件装配起来的
技能在会话一次独立的对话记录,有自己的上下文,互不干扰。里用斜杠 / 调用,插件在侧栏插件页管理,它们是 dsh 插件体系的两个侧面。技能怎么用、怎么装、怎么写,在 4.3 节专门讲。
常见问题
问:插件装在哪、怎么装新的?
用侧栏插件页的添加插件装(见上文),或者命令行 dsh plugin --profile web add <包名>(7.1 节)。安装和编写插件属于进阶内容,Part 9 专门讲插件生态。
问:改插件配置有风险吗?
核心插件(终端、Agent 循环)改不好会影响 agent 的正常工作。新手建议先只看不动,熟悉了再调。
问:为什么我在插件页看不到某些随附插件?
插件页只管理组合包;profile 依赖里没有组合包内容的普通包不上页面,只读的完整清单去设置里的内置插件页看。
小结
- 0.1.6-alpha.2 起插件管理集中在侧栏插件页,装、开、关、卸、配一站搞定;0.2.1-alpha.2 起页面排成内置插件配置、实验性插件、已安装插件三段,实验性那段还有个更多按钮展开完整目录
- 设置里的内置插件页只保留只读清单
- 内置插件配置固定四张卡:子智能体、网页搜索、Agent 循环、终端,草稿制保存
- 网页搜索卡片0.2.1-rc.2 起新增启用新版 Web 搜索 API开关(默认关):打开后走 DeepSeek 官方 Search / Fetch API,基础地址、结果数和密钥规则都跟着换一套
- 添加插件先检查后安装,pnpm 拦脚本可授权重试,装完一键启用;热重载覆盖不到时会写清「请重启 DSH 使更改生效」和原因
- 技能是"说明书",插件是"零件",两者是插件体系的不同侧面
插件认识完了,下一节选一个 Agent 预设,让会话带角色干活。