ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 在不同 profile 的差异:web 有入口、headless 没有,问题出在哪

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH pluginprofileheadlesswebDeepSeek Harness
同一个插件,在 web 里能看到入口,换 headless 或 sdk 就消失了。本文把 profile 当成三份独立安装来解释:装在哪、加载什么、插件该怎么设计才能跨入口复用。

一个插件在 dsh web 里能点开设置卡片,换 dsh --profile headless "跑个任务" 之后,工具还在,卡片却没了。于是有人开始怀疑打包漏了文件。

其实什么都没漏。你面对的是三份独立的安装。

同一个插件,三种命运

同一个 DSH plugin 放进三个 profile,会得到三种正常但不同的结果。 把同一个插件分别放进三个 profile,结果通常是:

web:工具能调用,设置里有入口,工具结果有卡片。因为它既加载 Host 半,也加载浏览器半。

headless:工具能调用,日志里有结果,但没有界面。因为它只跑一次任务并打印答案,没有浏览器。

sdk:工具能调用,调用方通过 JSON-RPC 拿结果,同样没有界面。

三种结果都正常。 差别不在插件质量,而在承载它的 profile 有没有界面、有没有加载客户端资源。

DSH plugin profile 是三份独立安装,不是模式开关

DSH plugin 的 profile 是三份独立安装,不是同一个东西的模式开关。 把它理解成「同一套东西的不同启动模式」,是很多误判的起点;它更像三个独立项目:

text
$DSH_HOME/
└── profiles/
    ├── web/      # 自己的 node_modules、patch、bundles
    ├── headless/ # 另一份
    └── sdk/      # 再一份

每个 profile 目录里有两样关键东西:

  1. package.json:记录树外插件依赖,以及 dsh.profile 里的 bundles 顺序;
  2. cordis.patch.yml:用户自己的 patch 层,在组合包层之后应用。

装插件时用 dsh plugin --profile <名称> add,装进的是那一个 profile。 这就是为什么同一个包名,在 web 里能从设置界面看到,在 headless 里连列表都没有。

profile 会在首次使用时初始化。 web、headless、sdk、sdk-minimal、acp 都会从随附模板自动准备;desktop 是保留名,CLI 会拒绝针对它的启动与配置 dump。

为什么 DSH plugin 在 web 有入口、headless 没有

入口属于界面,不属于插件本身。 一个带设置卡片的插件,代码通常分两半:

部分负责在 headless 里
Host 半注册服务、工具、事件正常加载
浏览器半注册设置卡片、工具渲染不存在

headless 没有浏览器环境,浏览器半自然没有承载。 这不是加载失败,是压根没有那一层。

反过来也成立: 浏览器半依赖的组件、样式、资源,在 web 之外的 profile 里没有意义。硬把它塞进 headless,只会得到一堆无效注册。

判断你的插件属于哪种: 如果它只是注册工具或事件,它天然跨 profile;如果它在 Host 半里 import 了浏览器组件,那它只适合 web。

DSH plugin 多 profile 支持的设计规则

DSH plugin 的第一条规则:Host 半不许 import 浏览器代码。 这是最硬的一条。Host 半一旦引用了只在浏览器里存在的模块,headless 加载时会直接失败,或者被静默跳过。

第二条,能力通过服务与工具暴露,而不是通过界面。 想让 headless 也能用,就把能力注册成工具或服务;界面只是另一个入口。

第三条,不要假设「一定有界面」。 代码里不要写「如果界面上没有就报错」,headless 下这等于自己制造故障。

第四条,入口按 profile 区分。 在 cordis.yml 里给界面半单独一行,并把它放在只在 web 生效的层里;不要用一个入口同时做两件事。

一个可操作的检查: 在 headless 里启动一次,看日志里有没有「模块找不到」或「未定义组件」。有,说明 Host 半混进了浏览器依赖。

DSH plugin 跨 profile 的验证矩阵

对 DSH plugin 来说,「装上了」不等于「在这个 profile 里能用」。 按矩阵逐个验证:

bash
dsh web                                  # web:看界面与工具列表
dsh --profile headless "列出工作区文件"   # headless:看输出
dsh --profile sdk                        # sdk:JSON-RPC 连接
dsh --profile web --dump-config          # 看组合层
  1. 在 web 里启动:确认工具列表有它、界面入口有它;
  2. 在 headless 里运行一次任务:确认工具能被调用、输出里有结果;
  3. 在 sdk 里连一次:确认服务能响应,不需要界面;
  4. 每个 profile 都执行 --dump-config,确认插件那一层存在;
  5. 卸载后重复第 1 步,确认入口消失、没有残留。

第 4 步能区分「没装」和「装了没生效」。 层不在,是安装问题;层在但行为不对,是代码问题。

如果只在 web 验证过,就不要对外说「支持 headless」。 支持与否,以 headless 里能调用工具为准。

DSH plugin 的三个常见误判

误判一:把插件装进 web,然后在 headless 里找。 每个 profile 依赖独立,装哪份用哪份。要在多个 profile 用,就在每个里各装一次。

误判二:以为重置 profile 只重置配置。 --from-default-profile 用模板替换整个 profile,插件与组合顺序都会没。重置前先记 bundles 与插件清单。

误判三:把 desktop 当普通 profile。 desktop 是保留名,CLI 拒绝针对它的启动与配置 dump,相关操作由桌面端自己管理。想用命令行调试,另建一个具名 profile。

还有一种隐蔽情况:插件装了,但 profile 启动参数指定了另一个。 启动时确认 --profile 后面的名字,和安装时用的是同一个。

跨 profile 复用不是「多打一个包」,而是「把界面从能力里拆出来」。拆开之后,web 是入口之一,headless 和 sdk 是另外两个,插件只需要保证 Host 半干净。想看 bundle 与 profile 的关系,读 DSH plugin 打包成 bundle;想看界面半怎么拆,读 DSH plugin 界面开发;想看加载卡住怎么查,读 DSH plugin 本地调试。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

插件在 dsh web 里有入口,换 headless 就看不见,是没装好吗?

这通常是因为 DSH plugin 装进了 web profile。每个 profile 在 $DSH_HOME/profiles/<name> 下有独立依赖,装进 web 的插件不会出现在 headless;界面入口也只存在于带 UI 的 profile。

headless profile 里能用到插件注册的工具吗?

DSH plugin 注册的工具在 headless profile 里能用,但看不到界面入口。headless 运行一次任务并打印最终答案,没有 Web UI;工具是否注册成功要看日志或输出,而不是看界面。

想让一个插件同时支持 web 和 headless,代码上要注意什么?

插件要同时支持 web 和 headless,就得把 Host 半与界面半分开:Host 只做服务与工具注册,不 import 浏览器代码;界面半只在 web profile 加载。这样 headless 没有界面资源时,Host 仍能正常工作。

用 --from-default-profile 重置 profile,会把已装的插件清掉吗?

会,重置会清掉已装的插件,只保留随附模板的内容。它会用模板的全新副本替换该 profile,原有组合与依赖被覆盖;重置前先记录 bundles 列表与插件名,重置后按清单重装。

相关术语

profile
profile 是 Harness 的具名组装环境,位于 $DSH_HOME/profiles/<name>,各自维护独立依赖、patch 与组合包列表。— dsh CLI README
headless
headless 是只运行一次任务并打印最终答案的 profile,没有图形界面,适合脚本与自动化。— dsh CLI README
sdk profile
sdk profile 是通过 JSON-RPC stdio 为 SDK 客户端提供服务的 profile,直到连接关闭,同样不提供 Web UI。— dsh CLI README
组合包列表
组合包列表是 profile manifest 里的 bundles 顺序,决定该 profile 启动时按什么顺序叠加哪些配置层。— DeepSeek Harness CLI 行为参考

来源