第 8 章　插件、Bundle 与 Profile：给 DSH 装能力

约 5 分钟 · 2,568 字 · 13 个小节

本章你会学会

分清 Plugin、Bundle、Profile 三个词；
知道一个插件是怎么被“装进去”的；
用 Plugin Manager 安装、启用、停用、卸载；
理解第三方插件的信任边界；
遇到“装了但不生效”时怎么排查。

8.1 三个词，三个层级

先记住一句话：

Plugin 是能力，Bundle 是安装包，Profile 是工作环境。

词	你可以理解成	回答的问题
Plugin	一个可插拔的能力模块	运行的时候执行什么？
Bundle	一个可安装的“补丁包”	哪些配置和代码一起分发？
Profile	一套安装环境	这个环境装了哪些 Bundle？

Plugin

Plugin 是运行时单元。它可以：[1]

注册工具；
注册服务；
注册 Skill；
添加界面；
监听事件；
改变 Agent 的行为。

例如，一个笔记类插件可以注册一组笔记工具、一个 Config 和一个 Skill。

Bundle

Bundle 是一个 npm 包，里面通常有：[2]

一个 cordis.patch.yml（或一组 patch 文件）；
要挂载的插件代码；
可能还有 Skill、界面资源、图标。

它的作用是：

把“要加哪些插件、怎么配置”打包；
让用户一条命令安装；
安装后，它的配置行仍然可以被上层覆盖。

一个 Bundle 可以挂载多个 Plugin；一个 Plugin 也可以被不同的 Bundle 引用。

Profile

Profile 是安装环境，通常对应：[3]

desktop：桌面应用；
web：浏览器；
headless：命令行一次性执行。

它里面有：

已安装的 Bundle 列表；
自己的 cordis.patch.yml；
第三方插件依赖。

Profile 决定“这个环境装了什么”，Bundle 决定“装的东西包含什么”，Plugin 决定“实际运行什么”。

8.2 它们和 Preset 的关系

Profile（desktop）
 ├─ Bundle A（dsh-base）
 ├─ Bundle B（dsh-web-app）
 │    └─ 声明 Preset: standard / creator / ...
 └─ Bundle C（你的插件）
      └─ 挂载 Plugin: 你的工具

Preset（standard / creator）
 └─ 给某个 Agent 选择一组 Plugin

Bundle 可以声明 Preset；
Preset 是“给哪个 Agent 用哪些 Plugin”；
Profile 是“这个环境装了哪些 Bundle”；
Plugin 是“真正执行的能力”。

8.3 用 Plugin Manager 安装

在 Desktop 里，通常有 Plugin Manager / 插件页面。

基本流程：

打开插件页面；
搜索或选择要安装的 Bundle；
阅读说明、权限、依赖；
确认安装；
按提示重启/重载；
检查工具、Skill、界面是否出现。

安装前要看的

作者/来源是否可信；
它要求什么权限；
是否依赖外部 CLI/服务；
是否会执行安装脚本；
是否和已有插件重名/冲突；
有没有卸载方式。

安装后要检查

插件是否显示“已启用”；
工具列表里有没有新工具；
Skill 列表里有没有新 Skill；
有没有报错/警告；
是否需要重启。

8.4 为什么“装了但不生效”

常见原因：

现象	可能原因
插件列表里有，但工具没有	没启用；需要重启/重载；依赖缺失
启动报错	版本不兼容；缺 peer 依赖；配置错误
工具名冲突	和另一个插件用了同一个名字
需要登录/CLI	外部依赖没装/没登录
只在某个模式里有	工具被挂在某个 Preset 里，不是全局
改了代码不生效	服务端插件需要重载；不是热更新

排查顺序

看 Plugin Manager 的状态和错误；
看是否需要重启；
看依赖/版本；
看是否和已有插件冲突；
看工具是否只在某个 Preset 中；
看日志/诊断。

8.5 配置插件

很多插件有配置项，例如：

可执行文件路径；
API 地址；
超时；
输出上限。

在 DSH 里，插件通常用 Config schema 声明这些字段，Plugin Manager 会显示成表单。

原则：

优先用界面配置；
不要手动改 profile 的 package.json；
不要手动改 cordis.patch.yml，除非你知道层顺序；
改完要重载/重启；
配置里的密钥要放在安全位置。

8.6 第三方插件的信任边界

这是最重要的一节。

插件不是“配置文件”，它可能执行代码。

安装第三方插件，相当于让别人的代码在你的 DSH 进程里运行。它可能：

读取你的文件；
调用网络；
执行命令；
修改配置；
安装依赖；
运行安装脚本。

所以：

只装可信来源；
看权限和代码；
不要给不必要的 full access；
先在测试工作区试；
出问题能卸载/回滚；
不要把密钥交给不信任的插件。

8.7 卸载与回滚

安装前就要想好怎么卸载：

Plugin Manager 里能否停用/移除；
是否会留下配置/数据；
是否会改 profile 的 bundle 列表；
是否需要重启；
有没有版本回退。

重要环境先备份 profile，或至少记录安装前的状态。

马上试试

打开 Plugin Manager，看看当前装了哪些 Bundle；
找到“已启用/已停用”的区别；
不要急着安装新插件，先读一个插件的说明和权限；
找一个你已经在用的插件，看看它注册了哪些工具/Skill；
写下：如果它出问题，你怎么停用它？

常见坑

把 Plugin 和 Bundle 混为一谈：一个是能力，一个是安装包。
以为装了 Bundle 就一定启用：还要看选择/重载/依赖。
手动改 profile 配置：容易破坏层顺序。
不看权限就装：插件可以执行代码。
装完不重启：很多插件需要重载才生效。

小结

Plugin = 能力，Bundle = 安装包，Profile = 工作环境。
Preset 决定“给哪个 Agent 用哪些 Plugin”。
用 Plugin Manager 安装/启用/卸载；不要手改 profile。
第三方插件是代码，不是纯配置；信任和权限第一。
装了不生效，先查状态、重载、依赖、冲突、Preset 范围。

第三部分练习

用一句话向你朋友解释 Plugin、Bundle、Profile 的区别。
打开 Plugin Manager，记录当前启用的 Bundle 数量。
找一个插件，阅读它的权限/依赖，判断你是否愿意安装。
解释为什么“Preset 不是安全沙箱”。
写下一个“插件装坏了怎么回滚”的步骤清单。

参考

链接均为公开来源；产品行为可能随版本变化。

第 8 章 插件、Bundle 与 Profile：给 DSH 装能力