ChatGPTClaudeGrok / X / CursorGemini

DSH plugin Slot 的 hooks 与 injection:叠加顺序、props 与重挂载

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessSlotshooksinjection
会声明 slot,但多个插件往同一注入点叠加时顺序和 props 不对。本文讲声明与生命周期、四类输入的分工、框架 hooks 与 scope 的对应、inject 的私有注入点,以及 hoc 层的嵌套与重挂载规则。

“两个插件往同一个 slot 注入,结果顺序反了、props 也没拿到”,问题通常不在组件,而在你选错了输入通道。 DSH plugin 的 Slots 把 owner 值、私有注入、槽级注入与共享 store 分得很细,选错就会拿到不该拿的数据。 DSH插件 往同一个 slot 注入时,先选对输入通道,再谈顺序。

Slot 是类型化组合,组件拿不到 ctx

Slots 是 Web Client 的类型化 React 组合系统。(来源)

dsh-client-ui-slots 定义不依赖 React 的注册表与类型代数;dsh-client-ui-renderer 把可观测源绑定成钩子、渲染整棵树,并在内部拥有 React context。功能插件通过 ctx.slots.register() 贡献 UI,绝不导入其他功能插件的组件。

SlotMap 是编译期注册表。包通过声明合并写入 key、cardinality、scope、owner props、keyed props 与可选的 slot 级 inject face。运行时声明则是拥有该渲染位置的组件在 children 中给出的对应条目。

组件绝不会收到 ctx。父组件在某次渲染时已经知道的值通过 renderSlot 的 owner 参数进入;共享视图状态使用声明的 store;service 与 model object 留在 apply closure 中,只向组件投影 callback 或 observable source。

声明与生命周期由 Cordis effect 决定

销毁一个 entry 会递归折叠它声明的 child slot。(来源)

声明一个 child 会同时产生三种效果:令该 child key 生效、授权 parent entry 调用 renderSlot 或 renderSlotChain、记录运行时 dispatch 规格。

每个声明只能有一个存活 owner。向未声明 slot 注册,或重复声明其他 entry 已拥有的 child,都会在插件激活时失败——这类错误在启动阶段就能看到,不必等到渲染。

root 是唯一内建声明,也是唯一由 Cordis service 自身渲染的 key:ui-renderer 调用 ctx.slots.renderSlot('root', {}),其余每个后代都通过声明它的 entry 所收到的 renderSlot 或 renderSlotChain prop 渲染。

注册和声明遵循 Cordis effect 生命周期。因此,向其他包的 slot 贡献功能时要使用 ctx.slots.inject(key, callback):callback 会在每段声明生命周期内运行,owner 折叠时其 effect 随之移除,owner 再次挂载时则重新运行。

四类输入的分工

先判断数据属于谁,再选通道。(来源)

注册组件会在 binding 位置收到组装后的输入。四类主要输入:

  1. owner 值与标准 scope 值 — 推导为 PropsRuntime<K>;
  2. 共享视图状态 — 声明 store 后,组件拿到 selector hook 与 mutation callback,类型为 PropsStore<H>;
  3. 私有数据与 callback — 由注册项的 inject factory 提供,类型为 InjectFace<I>;
  4. 获授权的 child renderer — 由 children keys 推导为 PropsRenderSlots<S>。

另外还有两类:本地化 t 函数来自注册项的 locale namespace;chain 选中的值通过 ComposedProps 提供为 matched,hoc 包裹的 owner 内容提供为 children。

当 entry 声明 session 或 session-maybe child 时,PropsRenderSlots 还会提供 SessionProvider:不传 session prop 时继承外围 binding;显式传入 SessionReference 或 undefined 时,只覆盖该子树。严格 session entry 在 binding generation 改变时重新挂载;空白 session-maybe entry 接受首个 binding 时不重新挂载。

框架 hooks 与 scope 的对应

hooks 由目标 slot 的 scope 提供,与注册包无关。(来源)

当前组合中的 adapter 会添加标准 props:

  • 所有 scope — useSessions、useSessionStatus、useSessionRetainInfo、useSessionAccess(ui-session),useWorkspaces、useWorkspaceAccess(ui-workspace),useRemoteAccess(api-remote-access),usePanelInfo(ui-layout);
  • session — sessionId、useSession、useProjection、useAccess,以及 useConversation、useInput、inputActions、useChat、useTrajectory;
  • session-maybe — 同名但结果可选。

Renderer 还会根据声明的 store 创建 useStore,并根据声明的 locale namespace 创建 t。这些是由注册项推导的 props,不属于全局标准 props。

框架与领域 adapter owner 可以通过 ctx.slots.provideRoot() 或 ctx.uiSession.provide() 扩展标准集合,同时提供对应的声明合并。普通功能组件不应自行创建 React hook prop,也不应为 entry 私有数据添加全局标准 prop。

inject 是功能私有注入点

hooks 对象里存的是裸 source,绑定由 renderer 完成。(来源)

注册项的 inject 选项是通常使用的功能私有注入点。它的 factory 在插件的 apply 世界中运行,可以闭包捕获已经注入的 Cordis service,并且只返回组件所需的数据与 callback。

作用域参数随 slot 变化:session slot 收到 sessionId;session-maybe 收到 sessionId | undefined;声明 store 后还会收到该 store 绑定后的 actions。

返回值中保留的 hooks 对象接收裸 getSnapshot 与 subscribe source。Renderer 把 hooks: { status } 转换为组件 prop useStatus(selector),并按 source identity 缓存绑定。组件不会收到 source 本身,也不直接调用 useSyncExternalStore。

当每个 occupant 都需要同一种能力时,slot owner 可以在 child 声明里放置 inject face:普通成员原样交给所有 occupant;hooks 对象中的函数成员是 hook factory,它收到 slot 的标准 props 与可选的逐次渲染 hookContext,再返回提供给 occupant 的受限 hook。conversation.chat.node 正是用这套机制,为当前渲染的 node 提供 useTurnData(key)。

hoc 层的嵌套与重挂载

顺序在渲染前就编译好,重挂载由“层链是否变化”决定。(来源)

选择原则可以压缩成一句:一次渲染时 owner 已知的值走 owner props;单个 entry 的 callback 与私有 observable 走注册项 inject;由 slot owner 控制、所有 occupant 共享的能力走 slot 级 inject;需要跨 entry 共享或跨重新挂载保留的可变视图状态走声明的 store。React node 通过 child slot 组合,不通过注入值传递。

priority 的含义随基数变化:对 single、list、keyed 与 hoc cell,它是遮蔽优先级;对 chain,它是选举顺序。数值越小越先运行或渲染。

hoc 层的嵌套规则:不带 key 的层是通配层,作用于每次分派;带 key 的层只在 owner 传入相同 entryKey 时生效;同一 id 下,精确 key 的层替换该 key 的通配层。各层依次按 order、priority、注册顺序升序嵌套,最小者在最外层。

每层收到同一份 owner props,并以 children 收到内一层(最内层是 owner 的内容),且至多渲染一次;不渲染 children 的层替换其内部的全部内容。owner props 不得使用 children 这个名字。省略 children 时各层包裹空内容;没有适用的层时原样渲染内容。

重新挂载的判据是层链:增减一个适用于本次分派的层会让其内部内容重新挂载;session 或 session-maybe 作用域的层在 Session binding 变化时也会让内部内容重新挂载;分派同一 key 的 outlet 共享一条编译好的层链,因此为其他 key 注册的层不会让它们的内容重新挂载;outlet 切换 entryKey 时会换到另一条层链,即使生效的层相同,内容也会重新挂载。

错误语义也要分清:崩溃的层照常上报错误,并在出错的那一处渲染它的 children,直到该处本次挂载结束;该层保持注册,因此其他出现处仍保留它。被包裹内容抛出的错误穿过所有层,不记到任何层名下。

验证:两个插件注入同一 slot

验证要同时看顺序、props 来源与重挂载次数。(来源) 六步:

  1. 插件 A 注册一条 list 项 order: 100,插件 B 注册 order: 50,断言 B 在前。
  2. 两个插件注册同一 id 的 single cell,断言 priority 小者渲染,而不是两者都出现。
  3. 给其中一项声明 store,断言它通过 useStore 拿到状态,而不是从 owner props 读。
  4. 给某一项加 inject,断言 factory 能拿到 sessionId,且组件拿到的是 useXxx 而不是裸 source。
  5. 在运行时新增一个适用于该分派的 hoc 层,断言内部内容重新挂载一次。
  6. 切换 outlet 的 entryKey,断言内容重新挂载,即使生效层相同。

如果第 5 步没有重新挂载,先确认这层的 key 是否真的匹配本次分派——带 key 的层不会作用于其他 entryKey。

slot 基数与作用域的完整对照,可以对照客户端 Slot 概览;客户端资源生命周期见客户端资源生命周期。

一句话收束: 组件不拿 ctx、声明随 effect 折叠、四类输入各归其位、hooks 只给 source、hoc 顺序编译期固定、重挂载只看层链。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 Slot 组件能拿到 ctx 吗?

不能,DSH plugin 明确说组件绝不会收到 ctx。DSH plugin 让父组件已知的值走 owner 参数,共享视图状态走 store,service 与 model 留在 apply closure 里只投影 callback 或 observable。

DSH plugin 的 inject factory 在哪个世界运行?

在插件的 apply 世界运行,DSH plugin 允许它闭包捕获已注入的 Cordis service。DSH plugin 要求它只返回组件需要的数据与 callback。

DSH plugin 的 chain 里 priority 是遮蔽等级吗?

不是,DSH plugin 只在 single、list、keyed 与 hoc 里把 priority 当遮蔽优先级。DSH plugin 在 chain 里把它当选举顺序,数值越小越先运行。

DSH plugin 的 hoc 层不渲染 children 会怎样?

会替换其内部的全部内容,DSH plugin 把这当作有意覆盖。DSH plugin 规定省略 children 时各层包裹空内容,没有适用层时原样渲染内容。

相关术语

SlotMap
SlotMap 是编译期注册表,通过声明合并写入 key、基数、作用域、owner props 与可选的 slot 级 inject face。— packages/client/ui-slots/src/index.ts
PropsRuntime
PropsRuntime<K> 是注册组件从 owner 值与标准 scope 值推导出的 props 类型。— packages/client/ui-slots/src/index.ts
InjectFace
InjectFace 是注册项 inject factory 返回给组件的私有数据、callback 与 observable hook 形状。— packages/client/ui-slots/src/index.ts
hoc 层
hoc 层是按 id 与可选 key 寻址的一层包裹,按 order、priority 与注册顺序升序嵌套,最小者最外层。— DeepSeek Harness 官方参考 - Web Client Slots

来源