DSH plugin 怎么用 dsh-resource://：useResource 与资源钉住释放

DSH plugin 的客户端资源模型把「一个地址」变成任何 Web 组件都能读的活数据：拥有内容的包注册协议提供方，组件按地址订阅。 它的关键约束是持有者决定生命周期——一个订阅中的 useResource 或一次 pin 都能让资源存活；第一个持有者打开提供方的流，最后一个释放时中止流、丢弃值，快照回到 loading 或 none。这也解释了为什么切 tab 卸载正文不会关流：右侧栏在每条 tab 存续期内钉住了它的地址。

DSH plugin 的资源模型：地址、提供方与读取方

一句话结论：协议拥有值类型并注册唯一提供方；组件只认地址，不引用拥有者运行时。

1. ctx.resources：资源服务与 useResource 全局 hook 的提供者。
2. 协议声明：协议拥有者在 ResourceProtocolMap 上声明值类型。
3. 唯一提供方：一个协议恰有一个提供方，第二次注册抛错。
4. 读取方：组件按地址读取当前状态，无需知道谁在产生数据。
5. 第一个消费方：右侧 Sidebar 的 tab 就是这套模型。

DSH plugin 的 dsh-resource:// 地址：协议是 host，路径归协议

一句话结论：dsh-resource://<type>/…，host 必须是协议键；规范小写拼写才被接受。

1. file 协议的作用域：session/<id> 后接相对路径，或 absolute 后接去掉前导斜杠的绝对路径。
2. 构造与解析：用 fileAddressFor(sessionId, cwd, path) 与 parseFileAddress(address)。
3. 只读 scheme 与 host：protocolOf(address) 只返回小写 host。
4. 字符串比较：大小写变体是另一条记录，别手拼地址。

DSH plugin 的提供方注册：一条帧流，必须响应 signal

一句话结论：open 返回帧流，首帧是当前状态，之后每次变化一帧；中止信号必须让流停下。

ctx.effect(() => ctx.resources.register<'note'>({
  protocol: 'note',
  async *open(address, { signal }) {
    yield await ctx.remote.notes.read(id, signal)
    for await (const change of ctx.remote.notes.follow(id, signal)) yield change
  },
}))

1. 首帧即状态：不要等「第一次变化」才发数据。
2. 失败是帧：ok: false 携带 RemoteFailure；流里抛异常是编程错误。
3. 必须响应中止：忽略 signal 的提供方会一直跑到下一帧才停。
4. 注册时机：放在 ctx.effect 里，让协议与插件同寿。
5. 已被持有的地址：注册时会立刻打开它们的流；提供方 dispose 后地址读作 none。

DSH plugin 的读取：useResource 的四种状态

一句话结论：none、loading、live、failed 四态；failed 保留上一个成功值，便于继续展示旧内容。

1. 订阅即持有：组件挂载时订阅；另一个持有者存在时，你可以立刻读到最新值而不重开流。
2. 失败展示自负：模型不产生任何用户可见文案。
3. 类型参数命名协议：useResource<'file'>(address) 让返回值类型跟着协议走。
4. 多数流只推元数据：例如 file 协议给的是文件 stat，内容由消费方另行读取。

DSH plugin 的持有与释放：订阅与 pin

一句话结论：有持有者就活；最后一个离开时中止流、丢弃值、回到 loading 或 none。

1. 两种持有：订阅中的 useResource，或一次 ctx.resources.pin(address, signal)。
2. pin 的语义：不订阅也保持打开，直到 signal 中止；已中止的信号什么也不钉。
3. Sidebar 的用法：在每条打开 tab 的存续期内钉住地址，因此切 tab 不关流。
4. 释放后果：中止流、丢弃值、快照回到 loading（有提供方）或 none；之后的帧被丢弃。
5. 裸 observable：ctx.resources.source(address) 按地址引用稳定，只读快照不算持有。

DSH plugin 排查注意事项

一句话结论：资源问题先分「地址不对」「提供方没注册」「没人持有」三类。

1. 一直 none → 协议没注册提供方，或地址不是资源地址（拼错也是 none）。
2. 一直 loading → 提供方没发首帧，或持有者已全部离开。
3. 失败后空白 → 消费方没处理 failed，应该继续显示旧值加提示。
4. 切 tab 流断了 → 没有 pin 住地址，正文卸载触发释放。
5. 内存增长 → 每条地址的记录会保留到页面关闭，读过的不同地址越多占用越大。
6. 修复状态如实：本文的地址规则、帧流契约、四态与持有语义均取自官方「客户端资源」页面；file 协议与 Remote 命名空间细节以对应包文档为准。

来源：客户端资源、dsh-client-resources README、右侧 Sidebar。