DSH plugin 在不同 profile 的差异:web 有入口、headless 没有,问题出在哪
一个插件在 dsh web 里能点开设置卡片,换 dsh --profile headless "跑个任务" 之后,工具还在,卡片却没了。于是有人开始怀疑打包漏了文件。
其实什么都没漏。你面对的是三份独立的安装。
同一个插件,三种命运
同一个 DSH plugin 放进三个 profile,会得到三种正常但不同的结果。 把同一个插件分别放进三个 profile,结果通常是:
web:工具能调用,设置里有入口,工具结果有卡片。因为它既加载 Host 半,也加载浏览器半。
headless:工具能调用,日志里有结果,但没有界面。因为它只跑一次任务并打印答案,没有浏览器。
sdk:工具能调用,调用方通过 JSON-RPC 拿结果,同样没有界面。
三种结果都正常。 差别不在插件质量,而在承载它的 profile 有没有界面、有没有加载客户端资源。
DSH plugin profile 是三份独立安装,不是模式开关
DSH plugin 的 profile 是三份独立安装,不是同一个东西的模式开关。 把它理解成「同一套东西的不同启动模式」,是很多误判的起点;它更像三个独立项目:
$DSH_HOME/
└── profiles/
├── web/ # 自己的 node_modules、patch、bundles
├── headless/ # 另一份
└── sdk/ # 再一份
每个 profile 目录里有两样关键东西:
package.json:记录树外插件依赖,以及dsh.profile里的 bundles 顺序;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 里能用」。 按矩阵逐个验证:
dsh web # web:看界面与工具列表
dsh --profile headless "列出工作区文件" # headless:看输出
dsh --profile sdk # sdk:JSON-RPC 连接
dsh --profile web --dump-config # 看组合层
- 在 web 里启动:确认工具列表有它、界面入口有它;
- 在 headless 里运行一次任务:确认工具能被调用、输出里有结果;
- 在 sdk 里连一次:确认服务能响应,不需要界面;
- 每个 profile 都执行
--dump-config,确认插件那一层存在; - 卸载后重复第 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 本地调试。
常见问题
这通常是因为 DSH plugin 装进了 web profile。每个 profile 在 $DSH_HOME/profiles/<name> 下有独立依赖,装进 web 的插件不会出现在 headless;界面入口也只存在于带 UI 的 profile。
DSH plugin 注册的工具在 headless profile 里能用,但看不到界面入口。headless 运行一次任务并打印最终答案,没有 Web UI;工具是否注册成功要看日志或输出,而不是看界面。
插件要同时支持 web 和 headless,就得把 Host 半与界面半分开:Host 只做服务与工具注册,不 import 浏览器代码;界面半只在 web profile 加载。这样 headless 没有界面资源时,Host 仍能正常工作。
会,重置会清掉已装的插件,只保留随附模板的内容。它会用模板的全新副本替换该 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 行为参考
来源
- dsh CLI README· deepseek-ai
- DeepSeek Harness CLI 行为参考· deepseek-ai
- DeepSeek Harness 开发文档:打包与安装插件· deepseek-harness