「我在右侧栏点了打开文件,标签出来了,里面却是空的——是不是文件系统坏了?」 这个推断跳过了中间一步:标签出现,说明布局层接受了这个请求;标签里没内容,可能发生在更下面一层。
右侧栏参考将右侧栏描述为会话旁的专属区域,可在标签页中展示工作区文件、目录树和产品页面。面板承载标签页,布局则可以包含停靠面板和浮动面板。当前选中的会话拥有自己的区域;根控制器也会为已初始化且保留内容的后台会话留出席位,但只有前台会话可见。
排查时常见的六类误判:
- 把标签已创建当成资源已读取;
- 把资源地址和标签类型当成同一件事;
- 以为打开方式是类型自带的固定属性;
- 以为分栏总会成功;
- 把默认页面当成多开了一个文件;
- 把布局已保存当成重载后一定会恢复。
先记住这一点:布局、地址、内容读取是三层,任何一层失败都可能表现为「标签是空的」。 站内基础版可参考 右侧栏标签与分栏布局怎么工作。
一、右侧栏到底装了什么
这一层由几个东西组成,分清它们的职责,后面的现象就都能对上号。
区域:会话旁的专属空间。每个会话一份,前台可见。
类型注册表:决定一个地址能被哪些标签实现打开。
导航服务:执行打开、分栏、浮动、停靠、聚焦、关闭这些布局操作。
右侧栏包自己拥有区域、类型注册表和导航服务;它的 dockkit 依赖负责计算布局。这里有一条边界要早点记住:文档明确把 dockkit 列为内部实现,不是稳定的扩展接口。 也就是说,不要围绕它写扩展,也不要指望它有公开的布局快照或通用的撤销能力。
再往下还有两层:资源提供者把地址解析成实时值,工作区文件服务负责真正读取文件内容。这两层解释了本文标题里那句提醒——打开标签和读取文件虽然相关,却是两个不同的操作。
二、地址怎么变成标签页
地址的格式是 dsh-resource://<type>/…。协议部分决定由哪个资源提供者处理;会话范围的文件地址同时标识授权会话和文件路径。指南这类页面则使用右侧栏自己的页面标识。
关键概念是标签内容身份 = 类型 kind + 地址。由此会出现两个常见情况:
- 同一个组合再次打开时,默认聚焦已有标签,而不是再开一个;
- 同一个地址用不同的 kind 打开,就是两个不同的标签。
五个操作各自的边界
| 操作或概念 | 用途 | 边界 |
|---|---|---|
openResource |
把资源地址路由到合适的标签类型 | 地址不属于该 scheme 或无人认领时抛错 |
openTab |
按已注册 kind 打开页面 | 没有注册对应实现时抛错 |
revealIfOpened |
默认聚焦已有匹配标签 | 设为 false 可再打开一个 |
preferNewPane |
优先放入新的停靠面板 | 面板预算或空间不足时回退 |
replaceTab |
在原面板与标签位置替换 | 浮动标签的放置方式不同 |
两条打开路径都会先选定类型,再聚焦已有匹配项或放置新标签,随后展开侧栏,最后将导航记为一个历史项。
还有一点容易忽略:放置位置由调用方的选项决定,不是类型的固定属性。 也就是说「这个类型总是开在新面板」这种说法不成立——是调用时要求的,不是类型自带的。
另外,即使你为资源显式指定了 kind,仍然要通过该类型的 canOpen 检查。指定类型不等于跳过校验。
三、分栏和浮动怎么工作
导航服务提供 split、float、dock、focus 和 close。
split作用于当前活动停靠面板或指定面板。允许分栏时返回新面板标识;面板预算或侧栏宽度不允许时,不返回标识,也不记录操作。float把标签移到浮动面板。dock把浮动面板放回停靠区域。
后两个操作在目标不存在或已经处于请求状态时,都不会产生变化。这种「静默无操作」很容易被误判成 bug。
开发扩展或做集成时,可以按这个顺序检查:
- 打开会话区域,先确定内容是「资源地址」还是「按 kind 打开的页面」;
- 用对应的服务操作;只有确有需要时才指定目标面板、替换标签或优先分栏;
- 检查分栏结果,不要假定一定存在新面板——
preferNewPane在无法分栏时会回退到目标面板,让标签仍然可用; - 按需聚焦、浮动、停靠或关闭。注意写操作要求会话区域已挂载,没有区域时会抛错;
- 测试「切到别的会话再切回来」的行为,包括扩展自己保留的标签内容。
空面板会出现默认页面
停靠面板不会一直保持空白:参考文档说明,空根面板会获得一个从已注册指南条目中选出的默认页面。指南标签会列出已注册条目;选中某项后,系统会调用提供该条目的类型,并在当前位置打开。
因此,看到新区域里出现页面时,先别急着认为「多开了一个文件」——这是文档描述的布局行为。
四、插件怎么提供标签内容
一个标签类型由共享同一 id 的两项注册组成:
ctx.sidebarRightTabs里的静态定义,声明 kind 和地址匹配规则;- 一个带键 slot,提供内容主体。
框架通过 useTabInfo() 提供实时的侧栏、面板和标签信息。类型定义可以包含匹配模式、优先级区间,以及可选的同步 canOpen 否决。
有一点容易忽略:标题会在打开时写入布局记录。 需要实时标题时应该用标题 slot,而不是去改写那条记录——改写记录是在改历史,不是在改现实。
Slots 参考解释通用组合契约:SlotMap 声明键及其类型,运行时由拥有者声明子位置。两种情况会在插件激活时直接抛错:向未声明的位置注册,或重复声明已由其他条目拥有的子位置。
贡献遵循拥有者的生命周期。因此,扩展其他组件的 slot 时,也要考虑拥有者被释放并重新挂载的情形——你的注册也会遵循相同的生命周期。
随附的三种类型
| 类型 | 用途 | 注意 |
|---|---|---|
files |
工作区目录树 | 条目在自己的面板里打开资源 |
text |
文档预览 | 通过工作区文件操作读取内容 |
browser |
HTTP(S) 页面 | 有自己的内容与导航边界 |
这里要分清:文件资源观察提供元数据,预览才会通过工作区文件操作读取内容。 还有一点:裸绝对地址没有授权会话,因此会失败,不会借用当前标签的会话。
记住这一点,就能把「地址未授权」和「布局没放对」分开排查:它们的报错差异很大,但用户看到的都可能是「打不开」。
五、重复打开和新分栏有什么区别
这两个选项常被当成同一个开关,其实它们回答的是两个不同的问题。
revealIfOpened 回答:「已经有这个内容了,要不要再开一个?」
默认是聚焦已有标签;设成 false 才会再打开一个。
preferNewPane 回答:「这个新标签放在哪?」
优先放进新面板;空间或预算不允许时回退。
一个决定如何处理已有内容,另一个决定新标签的位置。即使请求新面板,空间和预算仍会限制结果——提出请求不等于一定能实现。
内容为空时怎么分层排查
打开或观察成功,不等于读取已经完成。界面需要根据各自状态分别展示内容和错误。排查时按这个顺序:
- 地址层:地址里的会话对不对?裸绝对地址是没有授权会话的。
- 类型层:有没有类型认领这个地址?
openResource在无人认领时会抛错。 - 布局层:标签放在哪个面板?分栏是否真的成功?
- 读取层:实际读取结果是什么?元数据观察成功不代表内容读到了。
四层各有自己的失败状态。若把「打不开」当成一个整体问题,就容易一直在错误的层里排查。
六、限制与安全边界
文档自身存在一处矛盾,需要如实说明:右侧栏参考的所有权章节称会恢复已保存的布局,而「未实现」章节则称布局仅存内存、重载后会折叠会话。
在测试已安装版本并核对更新后的文档之前,不应把任何一方当作通用的持久化承诺。换句话说,在扩展中不要假设布局一定能跨重载保留。
其他边界:
- dockkit 是内部实现,文档没有承诺公开的布局快照,也没有面向用户的通用撤销;
- 工作区文件读取仍受会话文件系统后端和传输上限约束;
- 浏览器和预览各有内容与导航边界;
- 布局操作成功之后,底层资源仍然可能失败。
最后一条值得单独强调:内容在标签中打开,并不能证明这个文件或网页是可信的。 布局层负责摆放,不负责判断信任;页面能显示出来,也不代表它安全。
七、术语速查
- 面板:容纳标签的区域,可以停靠或浮动。
- 标签 kind:用于选择已注册实现的类别。
- 资源地址:标识内容及其协议的地址。
- Slot:由组件拥有的类型化 UI 扩展位置。
- Dockkit:右侧栏内部布局引擎,不是稳定的扩展接口。
相关阅读
本文依据 DeepSeek Harness 右侧栏与 Slots 参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/right-sidebar-tabs-and-split-layouts-work
插件与文档收录于:https://dsh-plugin.com/zh/blog