插件

一句话版：插件是 DSH 生态的核心：搜索、记忆、视觉、终端、通知、趣味……几乎一切能力都是插件。装/卸/写,都从"了解插件形态"开始。

一、插件类型

类型	安装方式	生效时机
Bundle 插件	dsh plugin --profile web add "github:..."	装完重启 dsh web
Repository 插件(.dsh-plugin)	插件面板 → repository 源	即改即生效

内核 vs 社区:@deepseek-ai/* 是 DSH 内核包(随发行版);@dsh-external/* 是社区第三方插件,按需装,不随内核。下文安装示例多为社区插件。

形态与清单的差异见 插件解剖。

二、安装 bundle 插件

# 一行 git 源(构建产物已入库,约 15 秒)
dsh plugin --profile web add "github:dsh-external/dsh-session-search#main"

# 本地目录(开发)
dsh plugin --profile web add link:/path/to/plugin

dsh plugin --profile web add <source> 把参数原样转发给 pnpm(_plugin.ts:128_),只接受 pnpm 能识别的源(纯 git 源、link: 等)。&path: 子路径是 repository 插件机制自己的源格式,要装 monorepo 子包,走插件面板的 repository 源(见下),不经过 dsh plugin add。

装完检查组合树:

dsh web --dump-config | grep <插件名>

bundle 安装后重启 dsh web 生效(repository 插件不用)。

依赖解析：双锚点 + 扁平闭包

bundle 装进 profile 后,依赖按下面顺序解析,让 out-of-tree 插件也能复用同一个 cordis 实例:

1. bundle 名双锚点：先查 bundle 自己的安装目录,再查 profile 目录
2. 扁平闭包 fallback：$DSH_HOME/profiles/node_modules
3. 框架被 vendor 化、只发布为 @deepseek-ai/* scoped 包;插件应 import ... from '@deepseek-ai/cordis'。用了裸名 cordis/schemastery 会解析失败,workaround 是在插件目录自身安装缺失的裸名依赖(见 插件解剖)

三、Repository 插件

Repository 机制由第三方 @dsh-external/plugin-console + $DSH_HOME/cordis.patch.yml(repository-plugins.repositories)在家目录层面实现,非 DSH 核心内置。在插件面板添加 github:owner/repo#ref:

• 添加行 = 安装
• 更新 = 固定到远端最新 commit
• 删除行 = 卸载
• 修改立即生效,无需重启

面板流程(以装 monorepo 子包为例):

1. 设置 → 插件 → repository 源 → 添加
2. 源写成 github:owner/repo#ref&path:/packages/<子包>(&path: 是 repository 机制自己的子路径格式)
3. 面板按行解析成 .dsh-plugin 目录挂载;改/删行即时生效

.dsh-plugin 目录格式属于外部 plugin-registry 机制,非 DSH 核心(见 插件解剖)。

四、插件面板

设置 → 插件:

• 浏览已加载插件(用户 / 内置分类)
• 启用 / 停用 / 卸载
• 检查更新
• 管理 repository 插件源

五、插件分类速览

类别	例子
上下文与检索	dsh-session-search、dsh-memory-evolve
编辑与输入	dsh-message-edit、dsh-prompt-studio
界面与体验	dsh-web-panel、dsh-live-stats
模型与推理	dsh-vision、dsh-advisor、dsh-llm-fallbacks
通知与渠道	telegram、qqbot

完整精选见 插件生态。

六、自己写插件

• make-dsh-plugin skill(plugin-registry 自带的官方引导)
• 清单:package.json 的 dsh 字段(dsh.bundle.patch bundle 型 / dsh.client 浏览器半部 / dsh.profile.bundles profile 依赖)
• 挂载:dsh plugin --profile web add 或 patch 层
• 完整开发见 原理课程·插件开发

七、卸载与回写

• 卸载 bundle:dsh plugin --profile web remove <包名> 只删依赖、不回写 patch 层的手动挂载行——cordis.patch.yml 里对应的 insert 行要手动删(见 配置)
• reconcile 按已安装状态(而非依赖 diff):所以 update 能激活"新版本才多出 dsh.bundle 声明"的包
• 插件来自第三方,装前看来源与权限(尤其带网络外发能力的:telegram、zotero 等)

八、常见错误排查

症状 / 报错	原因	解法
裸名 cordis/schemastery 解析失败	装载闭包只含 @deepseek-ai/* 包	在插件目录自身安装缺失裸名依赖
patch 改了不生效	name 不符 → 静默跳过;或 config 是整行替换非深合并	对齐 id/name;--dump-config 核对
bundle 装了不生效	bundle 需重启	重启 dsh web
卸载后仍报错	remove 不回写 patch 层	手动删 cordis.patch.yml 对应 insert 行
面板看不到某插件	缺 client 包 / bundle 未装齐	dsh web --dump-config 对比;看浏览器控制台

下一步

• 插件解剖：形态与 patch 语义
• 配置：patch 层怎么配
• 写第一个插件