DSH plugin 右侧栏:资源模型、文档渲染器与 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.guide | chain,会话作用域;替换引导 tab 的内容而不替换 tab |
sidebar.right.tab.menu.item | list,会话作用域;追加在 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
验证要覆盖认领顺序、正文分发与渲染器切换。(来源) 六步:
- 注册一个
priority: 'extension'的图片类型,打开一张*.png,断言它压过text的 fallback。 - 用
openTab('image')打开另一个地址,断言canOpen仍生效。 - 同一地址先按
text打开、再按image打开,断言得到两个 tab。 - 在正文里读
useTabInfo(),断言panel.isFloating与tab.navigation.revision符合预期。 - 不注册正文只注册类型,断言渲染「无法查看此内容」而不是崩溃。
- 切换文档渲染器,断言 tab 与资源地址都没变,只是渲染组件换了。
如果第 1 步没有压过内置类型,先检查 patterns 是否匹配整个地址——不含 : 的模式只匹配路径部分。
slot 与 inject 的完整规则见Slot 的 hooks 与 injection;客户端资源模型见客户端资源生命周期。
一句话收束: tab 身份是 kind 加地址、页面地址只能由 Sidebar 写、认领按档与模式长度排序、extension 可接管 builtin、渲染器切换不改 tab、file 资源只推元数据。
常见问题
能,DSH plugin 的 tab 身份是 kind 与 address 的二元组。DSH plugin 让同一地址经同一类型再次打开时找到已有 tab,经两个类型打开则是两个 tab。
不会,DSH plugin 在 tab 打开时捕获一次并写进布局记录。DSH plugin 的活标题要靠标题 slot 读自己的 store。
能,DSH plugin 允许 extension 接管 builtin 的 kind。DSH plugin 在认领、get、openTab 与引导页上以 extension 生效,注销后 builtin 恢复。
不会,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
来源
- DeepSeek Harness 官方参考 - 右侧 Sidebar· deepseek-ai
- packages/client/resources/src/index.ts· deepseek-ai