深入理解 DSH plugin 客户端资源:地址、注册、读取与释放到底怎么对齐才不会被泄漏住
“资源读了却一直不释放”,原因往往不是忘了清理,而是把地址记录当成了资源本身。 DSH plugin 的客户端资源模型里,地址记录会在页面存续期内保留,但它不持有流也不持有值。真正的存活只由订阅与钉住决定。 DSH插件 读了资源不释放,通常是把地址记录当成了资源本身。
地址把内容变成活数据
组件按地址读取,不引用拥有者的运行时。(来源)
客户端资源模型把一个地址变成任何 Web Client 组件都能读的活数据。dsh-client-resources 提供 ctx.resources 服务与 useResource 全局标准 hook;拥有某类内容的包为它的协议注册一个提供方,组件按地址读取该内容的当前状态。
右侧 Sidebar 的 tab 是这个模型的第一个消费方。这条设计的目标很明确:预览、标题之类的“活数据”不该让 UI 组件直接依赖某个功能插件的运行时。
地址:scheme 与 host 可读,路径归协议
地址按字符串比较,大小写不同就是两份记录。(来源)
资源地址是 dsh-resource://<type>/… 形式的 URL。host 命名协议,必须是 ResourceProtocolMap 的键;路径归协议自己,由其拥有者逐段做百分号编码。
需要作用域的协议把作用域放进路径:file 协议的地址形如 dsh-resource://file/session/<sessionId>/<path>,其中 path 可以相对工作区根,也可以是保留前导斜杠的绝对路径,用 fileAddressFor(sessionId, cwd, path) 构造、parseFileAddress(address) 读回。
模型本身只读 scheme 与 host:protocolOf(address) 对 dsh-resource:// URL 返回小写 host,对其它任何字串返回 undefined。其它 scheme 下的地址——例如 Sidebar 的 sidebar://guide——不指向资源,读作 none。
几个边界值得记住:
dsh-resource://file/absolute/home/me/notes.md可以解析,但没有授权 Session,会以workspace-file/unknown-workspace失败,不会借用当前或 Tab 的 Session;DSH-RESOURCE://File/session/s1/a是另一份记录,openResource只接受fileAddressFor生成的规范小写拼写;subagentchat地址指向已寻址的 subagent Conversation,其值持有一个SessionReference,直到资源关闭;/home/me/notes.md不是 URL,读作none。
注册提供方:一个协议一个提供方
流必须在 signal 中止时停下。(来源)
协议拥有者在 ResourceProtocolMap 上声明其值类型,并在自己的 ctx.effect 里注册一个提供方,使协议与插件同寿。open(address, { signal }) 返回一条 RemoteResult 帧流——首帧是当前状态,之后每次变化一帧——并且必须在 signal 中止时停下。
失败是携带 RemoteFailure 的 ok: false 帧;流里抛出是编程错误,不会被捕获。这条区分很重要:业务失败要变成帧,不能靠抛异常。
一个协议恰有一个提供方,第二次注册抛错。注册时若该协议的地址已被持有,则立刻打开它们的流;提供方 dispose 时结束这些流,地址读作 none 直到提供方回来。
读取:四种状态的含义
failed 会保留上一个值,不会把界面清空。(来源)
每个 slot 组件不论作用域都在 props 上收到 useResource。useResource<P>(address) 以类型参数命名协议,返回该地址的当前快照;订阅就是持有资源的方式。另一个持有者让资源存活时,新挂载的组件立刻读到最新值而不重开流。
四种状态:
| status | 含义 | value | failure |
|---|---|---|---|
none | 协议没有注册提供方,或地址不是资源地址 | undefined | undefined |
loading | 流已打开、尚未产出 | undefined | undefined |
live | 最新一帧成功 | 最新的 ok 值 | undefined |
failed | 最新一帧报告失败 | 保留的上一个 ok 值 | 该帧的 RemoteFailure |
failed 由消费方自己呈现:模型把最后一个值留在失败旁,正文可以带提示显示旧内容而不是一片空白,下一个 ok 帧会清除失败。模型本身不产生任何用户可见文案——这也是为什么你的组件必须自己处理 failed。
持有与释放:订阅或钉住
最后一个持有者离开时,流被中止、值被丢弃。(来源)
资源有持有者就存活:一个订阅中的 useResource,或一次钉住。
ctx.resources.pin(address, signal) 在不订阅的情况下让资源保持打开直到 signal 中止;已中止的信号什么也不钉。右侧 Sidebar 在每条打开的 tab 记录存续期内钉住其地址,因此切 tab 卸载正文不会关流。
第一个持有者打开提供方的流;最后一个释放时中止它、丢弃值,并把快照回到 loading(有提供方)或 none(没有)。提供方在这次释放之后产出的帧被丢弃,迭代器被归还。
ctx.resources.source(address) 是 hook 背后的裸 observable,按地址引用稳定,供 React 之外的调用方使用;只读它的快照不算持有。
这条“订阅即持有”的设计意味着:组件卸载就是释放,不需要额外的清理代码。反过来说,如果你想让资源在组件卸载后继续存活,必须显式 pin。
值的形状与限制
多数流只推元数据,内容要自己再读。(来源)
file 提供方的值是 WorkspaceFileStat { absolutePath, version, bytes? }:首帧来自 Host 的 stat,后续观察更新版本。消费方自己经 Workspace Files Remote 命名空间读取内容;Preview 按 tab 独立刷新。
subagentchat 提供方保留已寻址 Session 并产出其 SessionReference,在资源 signal 中止时释放该 reference。
限制有四个:记录在页面存续期内保留——地址的记录在最后一个持有者离开后仍留着,不持有流也不持有值,因此内存随读过的不同地址数增长;忽略 signal 的提供方会一直跑到它的下一帧;失败类型是 Remote 面的 RemoteFailure,来源不是 Remote 调用的提供方得自己铸一个;拼错的协议或畸形的地址读作 none,没有别的诊断。
验证:同名资源与重复读取
验证要覆盖状态迁移、单提供方约束与释放后的行为。(来源) 六步:
- 注册一个提供方,首次读地址,断言状态从
loading变成live。 - 再注册同一协议,断言抛错,而不是后者覆盖。
- 组件卸载后读同一地址,断言状态回到
loading(提供方仍在)。 - 用
pin钉住后卸载组件,断言流仍开着且live。 - 中止 pin 的信号,断言快照回到
loading或none。 - 读一个拼错协议的地址,断言状态是
none且没有 failure。
如果第 3 步仍是 live,先检查是否有另一个组件或 tab 在持有同一地址——资源是按地址共享的,不是按组件。
右侧栏如何消费这套模型,可以对照右侧栏资源模型;客户端模块注入见Client 模块 wire。
一句话收束: 地址按字符串比对、一个协议一个提供方、失败是帧不是异常、failed 保留旧值、订阅或 pin 才算持有、记录会留着但不持有流。
常见问题
敏感,DSH plugin 按字符串比较地址。DSH plugin 只接受 fileAddressFor 生成的规范小写拼写,手写的不同大小写是另一份记录。
不会,DSH plugin 保留上一个 ok 值。DSH plugin 把失败放在值旁边,消费方可以显示旧内容加提示,下一个 ok 帧会清除失败。
不算,DSH plugin 明确说只读快照不构成持有。DSH plugin 只有订阅中的 useResource 或一次 pin 才能让资源存活。
不会报错,DSH plugin 把它读作 none。DSH plugin 对拼错的协议或畸形地址没有别的诊断,只有 none 这一个结果。
相关术语
- ResourceProtocolMap
- ResourceProtocolMap 是客户端资源的协议到值类型映射,协议拥有者通过声明合并写入自己的值类型。— packages/client/resources/src/index.ts
- useResource
- useResource 是全局标准 hook,按地址返回资源当前快照,订阅即持有。— packages/client/resources/src/index.ts
- pin
- pin 是在不订阅的情况下让资源保持打开直到信号中止的持有方式,已中止的信号什么也不钉。— packages/client/resources/src/index.ts
- RemoteFailure
- RemoteFailure 是资源失败帧携带的失败类型,来自 Remote 面,非 Remote 来源的提供方需自行铸造。— packages/client/resources/src/index.ts
来源
- DeepSeek Harness 官方参考 - 客户端资源· deepseek-ai
- packages/client/resources/src/index.ts· deepseek-ai