ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 客户端插槽地图:一个按钮能插在哪、pane-tab 与设置区怎么分

插件开发发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH plugin客户端插槽Slot客户端开发
客户端插槽不是随便找个位置渲染,而是位置、数量与作用域三件事。本文把页头、侧栏、设置、会话四类位置分开,讲 cardinality 与 scope 怎么选,并给选错插槽的三种症状。

插槽不是「找个地方渲染组件」,而是「向宿主声明一段内容应该出现在哪、能有几条、跟谁同生命周期」。 这三个问题分别对应位置、cardinality 与 scope(来源)。只选位置、不管另外两个,最常见的结果是「内容显示了,但切换会话就没了」或「装了两个插件,只剩一个」。

DeepSeek Harness 插槽不是组件,是位置契约

组件回答「长什么样」,插槽回答「放在哪、能放几个、什么时候销毁」。 插件向插槽注册的是内容与元数据,宿主决定最终渲染。(来源)

这条契约带来两个约束:

  1. 位置由宿主决定 — 你选的是插槽名,不是 CSS 坐标;同一个插槽在不同布局里可能出现在不同位置;
  2. 生命周期由作用域决定 — 内容不是一直存在,它跟着插槽的 scope 走。

把插槽当成普通组件挂载,容易写出「在设置页塞一个全局按钮」或「在侧栏塞一个只对当前会话有意义的操作」。前者位置不对,后者生命周期不对。

判断方法:先问「这段内容属于哪个界面区域」,再问「它需要几条」,最后问「它跟全局还是会话走」。三问清楚,插槽基本就选对了。

DeepSeek Harness 四类位置:页头、侧栏、设置、会话

客户端插槽可以按位置分四类,每类适合的内容不同。 下面是一张定位表(来源):

位置典型插槽适合放什么不适合放什么
页头detail actions / badge针对当前对象的操作、状态标签全局导航、长表单
侧栏pane-tab、右侧栏常驻工作台、资源面板一次性提示
设置settings.section配置项、插件设置卡高频操作按钮
会话消息或会话相关插槽与当前会话绑定的内容全局统计、跨会话工具

页头与侧栏最容易混:页头是「针对当前对象做什么」,侧栏是「一直在这里的工具」。把常驻工具放到页头,会随着页面切换消失;把一次性操作放到侧栏,会长期占位。

设置与会话也容易混:设置是「配置一次、长期生效」,会话是「这次对话相关」。把会话级操作放进设置,切换会话后它还在,用户会以为它作用于全局。

四类位置不是绝对分类,具体插槽名以官方文档为准。但「对象级、常驻、配置、会话」这四个语义,能覆盖大多数选型。

DeepSeek Harness cardinality 与 scope 怎么选

位置选对之后,cardinality 与 scope 决定内容是否稳定。 两者经常被忽略,却是「重复」「消失」「串会话」的根因。(来源)

cardinality 看三件事:

  • 能不能有多条 — 单条插槽注册第二个会被拒绝或覆盖;
  • 怎么寻址 — 按 id 寻址的插槽,id 冲突会导致后注册失败;
  • 顺序是否有意义 — 列表型插槽要明确排序,否则每次渲染顺序可能不同。

scope 看两件事:

  • 跟全局还是会话 — 会话级内容切会话应重建,全局内容应保留;
  • 面板关闭后是否销毁 — 侧栏面板关闭时,内容是否应该卸载并清理订阅。

一个实用原则:内容里持有会话状态,就用会话 scope;内容里只有全局配置,就用全局 scope。不要为了「省事」全用全局,否则切会话会串数据。

cardinality 与 scope 选错,通常不会在单插件测试里暴露,而是在「装第二个插件」或「切换会话」时出现。

DeepSeek Harness 选错插槽的三种症状

三种症状几乎覆盖所有插槽选型错误。 看到它们,先回查位置、数量、作用域(来源):

  1. 不显示 — 插槽名写错、scope 不匹配、宿主没有渲染该插槽;
  2. 重复 — cardinality 允许列表却用了固定 id,或同一内容注册了两次;
  3. 切会话消失/残留 — scope 选错:会话级内容用了全局,或全局内容用了会话。

不显示最容易误判成「插件没加载」。判断方法:换一个已知可用的插槽注册同样内容,如果能显示,问题在插槽名或 scope;如果仍不显示,才查客户端模块加载。

重复通常来自 id。按 id 寻址的插槽,两个插件用同一个 id,后注册的会失败或被忽略;表现是「装了两个,只有一个」。

切会话消失/残留最隐蔽。会话级内容用全局 scope,切换后还显示上一个会话的数据;全局内容用会话 scope,切换后被销毁,看起来像「功能时有时无」。

DeepSeek Harness 三个选型例

三个例子覆盖常见需求,可以直接对照。 选型时先找最接近的例子(来源):

  1. 设置卡 — 放设置区,单条,全局 scope;内容只在设置页显示,保存后长期生效。
  2. 侧栏工作台 — 放 pane-tab,单条,面板 scope;关闭面板时卸载,避免后台订阅泄漏。
  3. 会话内操作 — 放会话相关插槽,会话 scope;切换会话时重建,避免串数据。

三个例子的共同点是「内容生命周期与位置语义一致」。设置卡长期存在,侧栏面板跟面板,会话操作跟会话。

如果需求不在三个例子里,用四问判断:属于哪个区域、需要几条、跟谁同生命周期、关闭时是否要清理。四问清楚,再去找具体插槽名。

DeepSeek Harness 验证:显示、重复、切会话

验证插槽,不要只看「显示出来了」。 三步(来源):

  1. 显示 — 在目标页面能看到内容,且位置符合预期;
  2. 重复 — 注册第二个同类内容,确认是并存、拒绝还是覆盖,行为符合 cardinality;
  3. 切会话 — 切换会话、关闭面板、刷新页面,确认内容按 scope 重建或保留。

三步都过,插槽才算接对。只过第一步,常见问题是切会话后数据串了;只过前两步,常见问题是面板关闭后订阅还在。

旧文 dev-client-slots 讲单个 Slot 的声明与 props,dev-sidebar-right 只讲右侧栏;本篇补的是全站插槽定位表。先定位置,再定数量与作用域,客户端扩展就不会靠试。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 的客户端插槽是什么,和普通组件有什么区别?

DeepSeek Harness 的客户端插槽是宿主预留的位置契约,插件向插槽注册内容;普通组件只负责渲染,插槽还决定位置、数量限制与作用域。

DeepSeek Harness 的 pane-tab 和设置区插槽怎么选?

DeepSeek Harness 里,pane-tab 属于侧栏面板的标签位,适合常驻工作台;设置区插槽属于设置页,适合配置项。前者面向日常操作,后者面向配置,不要用错位置。

DeepSeek Harness 插槽的 cardinality 是什么意思?

DeepSeek Harness 里,cardinality 是插槽允许的条目数量与寻址方式,例如单条、列表、按 id 寻址;选错会让内容覆盖、重复或不显示。

DeepSeek Harness 插件切换会话后内容消失,和插槽 scope 有关吗?

DeepSeek Harness 里,有关。DeepSeek Harness 的插槽 scope 决定内容绑定全局还是会话;需要跟随会话的内容应选会话作用域,否则切换后可能被清掉或残留。

相关术语

客户端插槽
客户端插槽是 DeepSeek Harness 客户端预留的扩展位置,插件向它注册内容,由宿主决定渲染位置、数量与作用域。— DeepSeek Harness 官方文档 - 客户端 Slots
cardinality
cardinality 是插槽对条目数量与寻址的限制,决定同名内容能否并存、如何按 id 定位。— DeepSeek Harness 官方文档 - 客户端 Slots
scope
scope 是插槽内容的作用域,决定内容是全局存活还是绑定到某个会话、面板或页面生命周期。— DeepSeek Harness 官方文档 - 客户端 Slots
pane-tab
pane-tab 是 DeepSeek Harness 侧栏面板中的标签位,用于放置常驻的工作台或工具面板。— DeepSeek Harness 官方文档 - 客户端 Slots

来源