ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 右侧栏:资源模型、文档渲染器与 Workspace Files 怎么对齐

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness右侧栏文档渲染器Workspace Files
右侧栏 tab 能开,但资源地址、owner props 与文档渲染器接不上。本文讲 tab 身份 (kind, address)、类型注册的排序认领、useTabInfo 的字段,以及文档渲染器的选择与 Workspace Files 的读取面。

右侧栏最容易接错的不是组件,而是身份:tab 是 (kind, address) 二元组,不是 id。 DSH plugin 的右侧栏把地址当内容身份、把类型注册当一次排序认领。理解这两条,才知道为什么“同一个文件”能开成两个 tab。 DSH插件 接右侧栏时,tab 的身份是 (kind, address),不是 id。

一个会话一个停靠面

布局是纯规划器算出的历史记录,停靠 pane 从不空着。(来源)

每个会话恰有一个停靠面,保存在会话作用域的 slot store 里、由 rightbar.session 绘制。root 作用域的 rightbar 控制器为选中 Session 和拥有已初始化 keepMounted 正文的后台 Session 保留独立席位;只有前台 Conversation 可见。刷新会恢复已保存的布局。

面的每一次变化都是 kit 纯规划器算出的一条历史记录;停靠的 pane 从不空着,根 pane 为空时会加入根据已注册引导入口选出的默认页。

一个 tab 类型是共用定义 id 的两次注册:在 ctx.sidebarRightTabs 里的静态定义说明其 kind 打开哪些地址,一次 keyed slot 注册提供它的正文。框架注入 useTabInfo() 以读取 Sidebar、窗格与标签的实时信息;各类型把自身状态放在 slot store 里,包之间只以类型形式引用彼此的声明。

地址就是 tab 的内容身份

资源地址与页面地址是两族,调用方不能自己拼页面地址。(来源)

每个 tab 都由一个地址字串打开,地址就是 tab 的内容身份。

资源地址是 dsh-resource://<type>/… 形式的 URL:host 命名资源协议,其后是该协议自己的路径;所有协议共用一个 scheme,新增协议只新增 host。file 协议的路径以其作用域开头:session/<sessionId> 后接相对该会话工作区根的路径,或 absolute 后接去掉前导 / 的绝对路径。id 与每一段路径都做组件编码,盘符的 : 保留原样。

fileAddressFor(sessionId, cwd, path) 构造地址——相对路径或工作区内的绝对路径成为 session 相对地址,其他绝对路径成为 absolute 地址;parseFileAddress(address) 读回各部分或返回 undefined。

页面地址是 Sidebar 为按 kind(而非按资源)打开的 tab 记下的地址:sidebar://<kind>,由 Sidebar 自己在 openTab(kind) 运行时写入。调用方从不拼它——引导页与文件树以 openTab('guide')、openTab('files') 打开。

tab 身份是 (kind, address) 二元组:注册表的认领把地址原文用作记录的 contentId。所以同一地址经同一类型再次打开会找到已有 tab,同一地址经两个类型打开则是两个 tab。

Tab 类型注册是一次排序认领

没有任何类型认领会抛错,那是接线错误而不是用户错误。(来源)

ctx.sidebarRightTabs.register(definition) 在调用方的生命周期内注册一个类型的一份实现并返回注销器;调用方把它放在自己的 ctx.effect 里,因此实现与贡献它的插件同寿,同一 id 的第二次注册抛错。

定义是静态的:没有运行时 hook,也没有按 tab 或按会话的东西。关键字段:

  • id — 该实现的身份,在所有注册中唯一;正文与标题坑位按它注册;
  • kind — 类型的判别名,也是 openTab 点名的对象;可以重复,extension 能接管 builtin;
  • patterns — 可选的资源地址 glob;含 : 的模式匹配整个地址,不含的匹配 URL 的路径部分且任意深度都中;
  • priority — extension(缺省且最高)、builtin、fallback;
  • canOpen(address) — 可选同步否决,对 glob 命中生效;
  • title(address) — chip 文本,在 tab 打开时捕获进布局记录,之后不再改写;
  • keepMounted — 可选懒保活,已访问正文跨隐藏、Session 切换与停靠切换保留。

路由是一次排序认领。candidates(address) 对模式命中且未被否决的类型排序:先按档,再按最长命中模式长度,最后按注册顺序。claim(address, kind?) 取第一个候选,或直接用点名的 kind——跳过 glob,但 canOpen 仍生效——返回 { kind, contentId: address, title }。没有任何类型认领的地址会抛错。

同一个 kind 可同时携带一个 builtin 与一个 extension 注册。extension 在认领、get(kind)、openTab(kind) 与引导页上生效,席位按生效定义的 id 找正文与标题,不涉及 slot 优先级;extension 注销后 builtin 恢复。

Slot 与 owner props

useTabInfo() 的字段就是正文能拿到的全部实时信息。(来源)

Sidebar 声明四个扩展 slot,其文档 tab 另有一个 keyed 文档正文 slot:

Slot基数与用途
sidebar.right.pane.tab按定义 id keyed,会话作用域;提供一个 tab 的正文,未注册正文的 kind 渲染「无法查看此内容」
sidebar.right.pane.tab.title按定义 id keyed;chip 标题,可选,无条目时显示捕获的 title(address)
sidebar.right.tab.guidechain,会话作用域;替换引导 tab 的内容而不替换 tab
sidebar.right.tab.menu.itemlist,会话作用域;追加在 kit 布局动作之后,执行动作的条目必须调用 owner 的 dismiss()
sidebar.right.tab.document按文档实现 id keyed;文档 tab 内选中的文件渲染器

正文、标题与引导页替换项接收 useTabInfo(),返回 { sidebar, panel, tab }:sidebar 含 expanded 与 fullscreen;panel.id 标识所属窗格,必填的 panel.isFloating 区分浮窗与停靠;tab 移动时两者通过 hook 更新,tab.id 保持不变;tab 还含 visible、navigation、signal 与 actions。

几条生命期规则要记:所有 tab 都要求 Session 位于前台;停靠正文还要求展开且选中;停靠标题要求展开;前台浮窗不随整栏收起。signal 在记录消失或插件卸载时中止,不因隐藏或切换 Session 而中止。

navigation.revision 在每次导航到该 tab 时递增,params 不变也递增,正文可以仅凭「又被导航了」行动;按地址打开的 tab 为 1,没有人按地址打开的记录(种入的引导、刷新或撤销恢复的 tab)为 0。

Tab 域为每条打开的记录保有一个 occurrence:记录出现即在资源模型里钉住,因此切换 tab 卸载正文也不丢内容;记录消失即中止并丢弃;撤销恢复的记录是新的 occurrence。

文档渲染器:选择与归属分开

切换渲染器不改 tab,也不改资源地址。(来源)

text tab 是共享的 Document Preview 所有者。其根注册声明 sidebar.right.tab.document 并提供 ctx.documentPreviews。渲染器在自己的 effect 中注册 DocumentPreviewDefinition 元数据,再通过 ctx.slots.inject('sidebar.right.tab.document', ...) 等待 slot,以 key: definition.id 和自己的 locale 命名空间注册组件。

注册表记录唯一的 id、extensions、本地化 title()、loading,以及可选的 priority 与 wrap。后缀匹配不区分大小写,先排 extension(缺省值)、再排 builtin,随后比较后缀长度(长者优先)与注册顺序。与 tab kind 替换不同,注册表保留所有实现;工具栏列出匹配的候选,按 tab 记住选择。未知扩展名使用纯文本。

DocumentPreviewProps 派生自 PropsRuntime<'sidebar.right.tab.document'>。owner 提供原始 resourceAddress、content、当前 wrap,以及声明依赖的 addResource 与 setResources 回调:文本内容为 { kind: 'text', text, pages, eof },完整字节为 { kind: 'bytes', data }。这些瞬时缓冲区按只读方式借用,不得进入持久布局或 Session JSON;PDF 在转移到 Worker 前复制字节。

自行加载的渲染器则接收 { kind: 'renderer', revision, loaded, failed, reload } 而不是文件字节。正文调用自己的注入 face,在 revision 变化和卸载时取消请求,并通过 loaded(version) 报告已展示的源版本;加载失败时调用 failed(),使后续文件变化能够触发重试。父组件忽略过期报告,保留共享的重新加载与源文件变更控件。

Workspace Files 与内置类型

file 资源只推元数据,内容要经 Remote 命名空间自己读。(来源)

Host 的 ctx.workspaceFiles 与生成的 workspaceFiles Remote 命名空间读取 Session 文件系统后端允许的文件:stat(path) 返回 { absolutePath, version, bytes? };read(path, { offset?, limit? }) 返回一页行;readBytes(path, { range?, baseFile? }) 在 maxFileBytes 上限内返回完整文件或字节窗口;list(path) 限定在工作区根内返回直接子项;search(...) 通过打包的 rg 搜索;changes(path) 监听一个目标。

dsh-api-workspace-files 注册 file 提供方,ResourceProtocolMap.file 直接是 WorkspaceFileStat。Session 地址携带授权 Session 与相对或绝对路径,Host 原样接收并解析;裸 absolute 地址没有授权 Session,以 workspace-file/unknown-workspace 失败,不借用当前或 Tab Session。

内置类型有五个:guide(builtin,openTab('guide'))、text(fallback,dsh-resource://file/**,只认领 Session 地址)、files(builtin,openTab('files'))、browser(可多开的 builtin)、subagentchat(builtin,指向已寻址的 subagent Conversation)。

验证:注册一个文档型 tab

验证要覆盖认领顺序、正文分发与渲染器切换。(来源) 六步:

  1. 注册一个 priority: 'extension' 的图片类型,打开一张 *.png,断言它压过 text 的 fallback。
  2. 用 openTab('image') 打开另一个地址,断言 canOpen 仍生效。
  3. 同一地址先按 text 打开、再按 image 打开,断言得到两个 tab。
  4. 在正文里读 useTabInfo(),断言 panel.isFloating 与 tab.navigation.revision 符合预期。
  5. 不注册正文只注册类型,断言渲染「无法查看此内容」而不是崩溃。
  6. 切换文档渲染器,断言 tab 与资源地址都没变,只是渲染组件换了。

如果第 1 步没有压过内置类型,先检查 patterns 是否匹配整个地址——不含 : 的模式只匹配路径部分。

slot 与 inject 的完整规则见Slot 的 hooks 与 injection;客户端资源模型见客户端资源生命周期。

一句话收束: tab 身份是 kind 加地址、页面地址只能由 Sidebar 写、认领按档与模式长度排序、extension 可接管 builtin、渲染器切换不改 tab、file 资源只推元数据。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里同一个资源地址能用两个类型分别打开吗?

能,DSH plugin 的 tab 身份是 kind 与 address 的二元组。DSH plugin 让同一地址经同一类型再次打开时找到已有 tab,经两个类型打开则是两个 tab。

DSH plugin 的 title(address) 会随内容更新吗?

不会,DSH plugin 在 tab 打开时捕获一次并写进布局记录。DSH plugin 的活标题要靠标题 slot 读自己的 store。

DSH plugin 的 extension 能接管 builtin 的 kind 吗?

能,DSH plugin 允许 extension 接管 builtin 的 kind。DSH plugin 在认领、get、openTab 与引导页上以 extension 生效,注销后 builtin 恢复。

DSH plugin 切换文档渲染器时,会改动 tab 或地址吗?

不会,DSH plugin 明确切换渲染器不改变 tab 或资源地址。DSH plugin 把预览策略与资源归属分开。

相关术语

sidebar.right.pane.tab
sidebar.right.pane.tab 是按定义 id keyed 的会话作用域 slot,用来提供一个 tab 的正文。— DeepSeek Harness 官方参考 - 右侧 Sidebar
useTabInfo
useTabInfo 是框架注入的 hook,返回 sidebar、panel 与 tab 三部分实时信息。— DeepSeek Harness 官方参考 - 右侧 Sidebar
DocumentPreviewDefinition
DocumentPreviewDefinition 是文档渲染器注册的元数据,含 id、extensions、title、loading 与可选 priority 与 wrap。— DeepSeek Harness 官方参考 - 右侧 Sidebar
WorkspaceFileStat
WorkspaceFileStat 是 file 资源的值,含 absolutePath、version 与可选 bytes,只推元数据不推内容。— packages/client/resources/src/index.ts

来源