Visual Studio Code Agents 窗口单面板详情布局Single-Pane Detail Panel状态与转换规范指南【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode本文以仓库 SINGLE_PANE_SCENARIOS.md 为骨架主体展开。该文档是 VS Code AgentsSessions窗口single-pane 单面板详情布局的用户场景、可见性状态与转换矩阵的权威规格说明配合 LAYOUT.md、LAYOUT_CONTROLLER.md 以及 src/vs/sessions/contrib/layout 下的源码实现共同阅读可完整掌握该布局的启用方式、控件契约、状态机设计以及背后的实现架构。这篇技术指南将帮助你搞清楚三件事如何开关该实验性布局、它在什么条件下生效第三面板的编辑器内容与停靠详情面板在哪些状态下如何出现与消失以及每一次用户操作切换会话、切换标签、点击各按钮、拖动分隔条如何通过受控的转换规则落到正确的面板构图。文中给出的是可直接用于开发与回归测试的完整场景清单与状态转换表而不是笼统的功能介绍。一、文档定位与变更门槛SINGLE_PANE_SCENARIOS.md 的第一段就给出了一个非常重要的“规范变更闸门”Specification change gate本文档只描述单面板布局的用户场景、状态与转换矩阵它不是手工测试脚本。如果一个 bug 修复只是“恢复某个既有场景”那么它应当被写进回归测试layout-controller 与 single-pane strategy 的单元测试而不是改这份文档。只有当预期的状态模型或转换矩阵本身发生变化时才允许更新本文档。这意味着该文档扮演的是“单一事实来源”的角色状态机如何定义、每个动作应该落到什么构图由它来裁定实现细节、像素、样式、动作摆放则由代码、设计 token、组件 fixture 与聚焦测试负责。参考同级的编辑区规格 Editor presentation 与控制器文档 LAYOUT_CONTROLLER.md、desktopSessionLayoutController.md可以看到同样的分权原则LAYOUT.md只管部件归属与 workbench 拓扑控制器文档管理“规则标签 / 持久化 / 测试归属”而本场景文档管理“状态与转换”。二、功能总览一个开关、一次读取、两条发布通道整个 single-pane 功能被一个实验性设置门控项值设置键sessions.layout.singlePaneDetailPanel代码常量DOCK_DETAIL_PANEL_SETTING读取时机仅启动时读取一次——修改该设置后需要**窗口重载window reload**才生效读取者只有createSessionsWorkbench它负责挑选 workbench/parts 组合在源码 sessionConfig.ts 中该常量定义与注释说明完全一致启用后Agents 窗口会把详情面板auxiliary bar停靠在 editor part 内部让一条编辑区标签栏横跨编辑内容与详情面板的整条宽度。读取结果被发布为两条通道供两类代码分别消费IAgentWorkbenchLayoutService.isSinglePaneLayoutEnabled—— 供命令式代码读取SinglePaneLayoutEnabledContext上下文键 —— 只供声明式when子句读取。其中上下文键定义于 contextkeys.ts其描述注释特意强调这是“gating single-pane behaviour 的唯一真相源由 workbench 在构造时按其所选布局设置一次”。功能必须依赖上述两个发布结果做判断任何命令式代码都禁止直接读设置或直接读上下文键。生效矩阵场景布局设置ON默认值 非手机视口单面板布局本文描述的全部内容手机视口phone viewport始终使用经典布局设置OFF所有 Agents 窗口使用经典布局本文其余内容完全不适用编辑区拓扑限制单面板布局下主编辑器Main Editor只支持恰好一个 editor group编辑器 split/grid 命令、快捷键、菜单、open-to-side 请求、split 拖放目标全部被禁用程序化创建 group、多 group 布局请求会被拒绝上述限制不适用于独立的 chat grid聊天网格仍是多组的。这一限制直接来自 LAYOUT.md 的描述single-pane 将 Editor 与 Auxiliary Bar 组成一个位于活动会话旁的“side pane”编辑器共享的多组能力被关闭。从源码结构看MainEditorPart/EditorGroupView只承载一个 group正是为了保证“一条标签栏 编辑内容 停靠详情面板”的单一构图不被拆分。三、第三面板的三大区域单面板布局下第三个面板是一张单一视觉卡片card内部包含三个区域区域是什么归属所有者标签栏Tab bar横跨全宽的一条标签条Changes / File / Browser 标签 末尾的Editor group 标题MainEditorPart/EditorGroupView编辑内容Editor content标签栏下方的编辑区多文件 diff 的 Changes、单个文件、浏览器等右侧按详情宽度内缩Editor part右侧按详情宽度内嵌详情面板Detail panel右侧停靠的辅助栏Branch Changes Checks或 Explorer/FilesDockedAuxiliaryBarController把 aux bar 停靠进 editor part 内部实现上停靠逻辑位于 dockedAuxiliaryBarController.ts编辑区的停靠式标签栏布局由MainEditorPart.layout的keepForDockedTabBar分支维护源码位于 src/vs/sessions/browser/parts/editorPart.ts。不变式Invariants——标签栏永远可见只要第三面板被展示——包括编辑内容被隐藏时、以及 new-session 视图中——标签栏都保持可见。即使 editor part 在逻辑上被隐藏它仍由MainEditorPart.layout的keepForDockedTabBar路径在 single-pane 详情可见时维持布局。另外在可见侧栏打开/恢复空 FilesEmpty Files会揭示 Files 详情用户可以随后隐藏该详情下次打开 Empty Files 时它会被再次揭示。四、面板可见性状态机设E 编辑内容可见D 详情面板可见。面板支持以下四种状态状态ED含义Editor Detail✅✅正常协作状态左编辑内容、右详情、顶部标签栏Detail only❌✅编辑内容折叠Hide Editor标签栏 详情可见聊天区接管被释放的编辑宽度。详情保持自身宽度不拉伸填满面板。进入该状态会关闭所有非停靠的编辑标签仅保留停靠的 Changes/Files 标签可重开的标签被捕获并在编辑区再次显示时恢复不可恢复的例如 dirty 的 untitled Search 编辑器被丢弃Editor only✅❌详情被关掉编辑内容填满面板标签栏仍横跨顶部Side pane closed❌❌整个第三面板关闭仅剩聊天。通过Toggle Side Panel或在最后一个编辑标签关闭时到达永远不会由详情切换按钮触发。关闭整个侧栏并不关闭编辑器——只有Detail only式折叠编辑隐藏而详情保持打开才会关闭编辑器当两部分同时隐藏时编辑器原封不动侧栏重新打开时它们会回来下面几类规则是状态机的“补丁”控制何时应用哪个转换4.1 可见性画像visibility profile的共享范围只有Existing Sessions共享持久化的 Editor/Details 可见性画像。New Session不套用、也不捕获该画像它进入时只做一次性处理当恢复出的编辑集合里除受管 Changes 与 Empty Files 输入外别无其他输入时隐藏一次编辑器。提交Submit才会播种 Existing 画像。活动编辑器决定详情内容每个 diff 编辑器选中 Changes每个文件编辑器选中 Files。4.2 尺寸分配从 closed 打开侧栏例如聊天占满全宽时点击Changes以Sizing.Distribute揭示编辑器。网格用被揭示视图的位置来分配其所在 split因此 Sessions part 与侧栏在不经任一部分自算宽度的情况下获得等宽空间。之后的侧栏尺寸是workbench 级别而非每个会话级别编辑器网格节点宽度由 workbench 网格所有并全局持久化workbench.sessions.partSizes用户一旦调整过侧栏宽度该宽度就一直保留——包括跨会话切换切换会话不改变侧栏宽度与跨重载。切换 Details 时编辑器可见时开关详情不会改动编辑器网格节点与 Sessions/chat 宽度详情在既有侧栏内打开并从编辑内容取宽度隐藏详情把宽度还给编辑内容。重载无闪烁workbench 拥有几何重载时 workbench 用自己的持久化 part-sizesworkbench.sessions.partSizes由createDesktopGridDescriptor消费恢复侧栏编辑节点宽度一次绘制就按正确尺寸画好网格。workbench 层面隐藏编辑器仍会把网格节点折叠到详情宽度并缓存捕获的编辑器隐藏宽度_dockedEditorSizeBeforeHide在立即 re-show 时优先于当前 Details 可见性生效。会话列表折叠后重开关闭整个侧栏会把编辑器网格节点折叠到0px但“Editor-before-Details”的关闭顺序会在节点仍可见时先捕获当前侧栏宽度重开时恢复该构图而不会把0px当作用户宽度。若 New Session 之后落到仅 Files 状态隐藏编辑器而 Details 仍可见时节点收缩到 Details 宽度并捕获该侧栏宽度供下次打开文件使用回到 Existing Session 的 Editor-only 画像则恢复同一宽度——因此反复切换会话不会改变 Sessions/chat 边界。五、控件全集与行为契约下表是单面板布局的全部用户控件。这是实现侧按钮注册、when门控、命令实现与测试侧single-pane strategy 测试都必须对标的契约控件位置效果Toggle Details≡编辑器头部布局工具栏位于操作溢出按钮与一个分隔符之后显示/隐藏详情面板默认快捷键⌥⌘L。若编辑器已隐藏隐藏详情会揭示编辑器→Editor only面板绝不会被留空。它从不改动 Sessions 侧栏——后者始终由用户显式控制。其toggled状态AuxiliaryBarVisibleContext与实际渲染保持同步。仅当活动标签是Changes 或 Files非 Browser/Search——它们没有详情时才显示Maximize / Restore编辑器标题栏主要行内位置最大化编辑区最大化期间强制展示 Changes 详情取消最大化时恢复。默认快捷键⌥⌘E在编辑区可见时切换最大化/还原Hide Editorright-panel-hide编辑器标题栏标签条Maximize/Restore 之后关闭编辑内容并保留详情→Detail only。停靠侧栏收缩到详情宽度被释放的编辑宽度进入聊天而非详情。无论当前是否有详情面板可见它始终显示且始终可用Show Editorright-panel-show编辑器标题栏标签条与 Hide Editor 同一槽位再次揭示可能是空的编辑内容。只要编辑区是关闭的它就始终显示与活动标签是否支持详情无关Collapse All DiffsChanges 编辑器头部主要行内位置折叠 Changes 多文件 diff 中的所有文件SessionChangesEditor.collapseAllDiffsAdd Tab标签条末尾打开 Add Tab 菜单Browser⇧⌘K BSearch⌘K S仅 workspace-backed 会话当 Changes 标签缺失时提供Changes项、当 Files 标签缺失时提供Files项⌘K B任何 workspace 会话均可。恢复出的受管 Changes/Files 标签插入标签条末尾。Search 会打开新的 Search 编辑器Quick Chats 不可用。编辑区关闭时隐藏Toggle Side Panel命令 / 快捷键关闭/打开整个侧栏编辑器 详情一体→ 纯聊天及返回。机制位于 workbench 布局服务toggleSidePane编辑区最大化时共享的Workbench.toggleSidePane()会记住最大化状态、取消最大化、再执行折叠使被恢复的详情也一并隐藏重开时先恢复完整侧栏构图再重新最大化编辑器。隐藏处于焦点的侧栏会把焦点移到会话列表Toggle Sessions List标题栏 / 命令折叠/展开左侧会话列表。折叠把释放的宽度给编辑器/详情侧栏不是聊天重开恢复之前的编辑器/详情宽度聊天拿回空间。任何 single-pane 编辑器或详情操作都不会改变该可见性Grid sash聊天与第三面板之间拖动侧栏从不改变 Details 可见性。Details 保持最小宽度编辑内容先让步、在宽度压力下最终折叠。详情-only 时把侧栏拖宽仍保持编辑内容关闭。Details 可见时双击保留当前 Details 宽度把其余宽度在聊天与编辑内容间平分无 600px 上限窄布局中网格最小宽度优先。reset 后隐藏 Details 不改变聊天/侧栏边界并把 Details 宽度还给编辑内容。Details 隐藏时 sash 用原生平分detail-only 模式下 reset 会把 Details 重置为300pxChanges pill会话头部 meta 行打开受管 Changes 多文件 diff 编辑器并在侧栏已关闭或处于 detail-only 时显式揭示编辑区。受管 Changes 标签仍被排除在“自动 reveal-on-open”之外——仅激活其标签不会揭示编辑器5.1 编辑器动作可见性三组互相独立、门控不同的按钮在编辑器动作层面需要区分三类视觉逻辑本段是理解控件“为何如此排布”的关键Maximize/Restore、Toggle Details、Open in Modal在编辑区关闭时全部隐藏受MainEditorAreaVisibleContext控制。Toggle Details 紧排在 Maximize/Restore 之前。Hide Editor 与 Show Editor 是互斥的一对负责编辑区状态的开关两者都渲染在标签条 editor-title 布局簇MenuId.EditorTitleLayout、紧接 Maximize/Restore 之后只分别以MainEditorAreaVisibleContext为 true/false 门控。与 Toggle Details 不同它们不看活动标签是否有停靠详情面板、也不看详情当前是否可见——没有HasDockedDetailsContext门控、没有AuxiliaryBarVisibleContext前置条件这与 Maximize/Restore 在同一簇中“始终显示”的行为一致。Hide Editor 在自身run()里无条件揭示辅助栏即使详情此前被隐藏也有落脚点其详情面板实际显示什么由 New/Existing Session strategy 的详情面板映射经共享的SinglePaneDetailPanelCoordinator决定——活动标签自己的详情若 Browser 标签无自有详情则回退到 Changes/Files见第七节。Show Editor 通过会话头 Changes pill 同款的显式揭示 APIrevealEditorPartExplicitly()揭示编辑器再聚焦编辑器 group。Toggle Details 保留“有停靠详情面板”门控HasDockedDetailsContext定义于 contextkeys.ts受管 Changes/Files 标签或文本文件编辑器为 true——切换一个不存在的详情面板毫无意义。5.2 受管 Files 占位标签的生命周期空的 Files 占位标签与 Changes 标签在编辑器 group 为空且发生 view-open 触发会话切换或侧栏揭示时打开只要布局处于Detail only两者都保持存在。空 Files 占位激活期间agent-feedback 导航浮层被隐藏。打开一个真实文件会作为对该次 open 的一次性反应one-shot“收拾掉”空占位得到[Changes][file]条带——这是一次性的、不是常驻规则因此用户仍可在真实文件打开时通过Files添加 Files 标签该操作打开EmptyFileEditorInput而非真实文件故不会被收拾掉。Existing 与 New Session 在真实文件关闭时都不会重新添加占位只有当那次关闭让每个主编辑器 group 都变空时它们才关闭整个侧栏。5.3 New Session 的转换归属是分离的入场Entry只拥有“会话恢复后的一次性冗余 Editor 隐藏”这一转换。已完成的一次 closed→open Toggle Side Panel 转换只拥有“受管标签安定后仅 Files 的 dock 转换”。最后一个编辑器关闭监听 editor service 的 did-close 事件用共享的 all-main-groups-empty 判定editor-part 自动可见性被抑制期间忽略程序化关闭随后关闭整个侧栏。通用侧栏 reveal 通知永不启动该 toggle 规则——因此“编辑器打开”不能反哺进入该规则。5.4 空编辑组是生命周期所有的SinglePaneWorkbench在所有编辑器关闭时不改变可见性New 与 Existing Session 在最后编辑器关闭时关闭整个侧栏Quick Chat 则保持侧栏打开。5.5 布局驱动 vs 用户驱动的编辑器变更默认停靠标签在settled 的会话切换恢复时重新打开进空 group基础控制器在恢复纪元working-set apply aux 恢复完成后触发onDidEndSessionLayoutRestorestrategy 据此对账。这一点对 New Session 至关重要其空的working set 会先关闭上一会话的停靠标签、在切换之后腾空 group在 settled 的恢复结束点对账读到的是可靠的空 group从而重开两个受管标签。若在异步 apply 期间对瞬态的编辑器变更即时反应会与空状态发生竞态。用户驱动的编辑器变更打开文件、关闭标签在 Editor 可见时不会重开默认值在 Detail only 下标准关闭动作不能移除受管输入每次对账都会恢复被生命周期工作移除的任一输入。Existing→Existing 导航会在原地用新会话的 Changes 输入替换旧会话的 Changes 输入保留标签位置与激活状态——而不是“可见地关闭 Changes 标签再打开另一个”。5.6 无文件夹 composer 到 workspace draft 的两步过渡打开New Session先露出无文件夹 composer再播种其具体 workspace draft第一步移除上一会话的 Changes 标签期间共享 Files 占位可保持 group 非空第二步在wantsChangesTab变为 true 时显式确保 Changes当选中的会话文件夹与新会话默认文件夹不同时workspace 门控的 working-set 恢复可能稍后才安定并移除那个过早的 Changes 标签保留 Files因此 settled 恢复会对未创建会话重复一次 one-shot Changes ensure。只依赖空组规则或只依赖初始 eligibility 转换都会让 Files 成为唯一标签直到下一次 reveal 或 New Session 手势。5.7 New Session 提交Submit提交保留当前 Editor/Details 构图并播种 Existing Sessions 画像。Files 标签保持激活直到被提交会话上报首批文件变更此后 Changes 变为激活——但不揭示 Editor。该“待定激活”只作用于被提交的会话切走不会在别的会话里激活 Changes。5.8 Detail-only 不变式无论何时侧栏处于Detail onlyaux-bar 详情可见而无编辑区——例如 new-session 视图或编辑器被隐藏的已创建会话侧栏都收缩到持久化 Details 宽度且停靠详情面板展示受管停靠输入——因此 Changes 与 Files始终存在。打开文件会恢复之前的“Editor Detail 组合宽度”不改变 Details 宽度。两个输入都带EditorInputCapabilities.CannotClose能力每次对账读取的都是已 settled 的当前部件可见性即使 group 非空也恢复被生命周期工作移除的任一输入。Editor 可见时该能力被移除并维持“只向空 group 添加”的严格规则。5.9 关闭受管标签Editor 可见时用户可关闭受管 Changes/Files 标签它们非 preview、非 sticky。这种关闭被尊重且无任何 dismissal 记账默认标签只在 view-open 触发时向空编辑组打开外加前述一次性 submit 激活。所以关掉一个标签而另一个或真实文件还在时group 非空、不会重建。Detail only 下关闭命令与标签上的关闭手段一致地让底层输入保持打开内部生命周期工作仍可在 working-set 应用、会话切换、陈旧标签清理时强关任一输入。Editor 可见时关闭最后一个标签会关闭整个侧栏重开空组恢复默认值。workspace 会话在 Editor 可见期间关掉受管标签后Add Tab菜单会给出对应重开项——ChangesSinglePaneChangesTabMissingContext门控与FilesSinglePaneFilesTabMissingContext门控两键定义见 contextkeys.ts重加的标签使 group 非空因此得以存活。5.10 生命周期清理后的重开、跨重载记忆、打开文件与缺失动作生命周期工作强关所有标签后整个侧栏可能关闭侧栏重开时受管 Changes/Files 标签被 re-ensure。关闭整个侧栏的状态跨窗口重载被记住。重载后被恢复的受管标签不会再次揭示详情详情面板的强制揭示以“编辑内容可见”为门控因此完全关闭的侧栏保持关闭直到用户重开。打开文件Files的 add-tab 项打开的标签是pinned非 preview tab。单面板模式中不存在的动作Close Editor Area经典布局保留它single-pane 自己的Show Editor动作是 Hide Editor 的对应物。六、标签类型Tabs标签说明Changes自定义SessionChangesEditorBranch Changes 下拉 diff 统计 内嵌多文件 diff。pinned 且排在首位每个带 workspace 的会话都有包括 New Session draftFile空 File 标签EmptyFileEditorInput作为落地标签外加用户打开的真实文件编辑器。打开时pinned、不激活、保持焦点preserve-focus——绝不从聊天抢焦点Browser集成浏览器BrowserEditorInput自动受管标签pinned 的 Changes 标签与默认 File 标签都在suppressEditorPartAutoVisibility()下打开——它们从不揭示编辑内容。只有用户动作打开真实文件/diff或拖动 sash才揭示编辑器。源码中的实现分布见 singlePaneDockedTabsCoordinator.ts 与 emptyFileEditor.contribution.ts。七、详情面板内容由活动标签驱动SinglePaneLayoutController实现于 singlePaneLayoutController.ts负责把活动编辑标签映射为详情内容详情面板的可见性是全局的可见期间其容器跟随活动标签活动标签详情面板Changes 或任何 diff 编辑器Branch Changes 文件列表 Checks详情可见期间展示 Changes 容器任何文件或 Markdown 预览编辑器ExplorerFiles/Explorer 树详情可见期间展示 Files 容器Browser瞬时隐藏当 Browser 标签激活且编辑区保持可见时隐藏切回时恢复。若编辑区本身在 Browser 激活时被隐藏如Hide Editor面板改显 Changes/Files 回退内容——因为它是屏幕上仅剩的东西规则 1 —— “激活即揭示激活后尊重”切到 Changes/File 标签会用正确容器揭示详情。同一标签保持激活期间用户的显式隐藏详情用详情切换按钮被尊重、不会被再次强制揭示切换标签会再次揭示。规则 2 —— Browser 是瞬时的但仅在编辑区可见时成立Browser 标签在编辑内容停留在屏幕上时隐藏详情面板切回 Files/Changes恢复它。Browser 激活时隐藏编辑区Hide Editor不会让面板空白——它显示与会话无活动编辑器时相同的 Changes/Files 回退再次揭示编辑区Show Editor后“Browser 隐藏详情”规则恢复。实现上这个“活动标签 → 详情容器”的映射由 singlePaneDetailPanelCoordinator.ts 承担同步机制而具体哪类会话回退到什么容器则由三种 strategyNew/Existing/Quick Chat各自裁定。八、会话生命周期布局规则Existing Sessions共享 Editor/Details 可见性画像New Sessions不拥有生命周期可见性状态其一次性入场规则只在 Empty Files 是唯一输入时隐藏冗余编辑内容提交保留当前构图并更新 Existing 画像。8.1 Quick Chats / 无 workspace带已保存编辑器的 Quick Chat 与 Existing Sessions共享侧栏总可见性可见的 Existing 构图映射为 Editor-onlyQuick Chat 没有 Details隐藏构图保持隐藏。打开第一个编辑器、以及带编辑器的 Quick Chat 内做可见性变更都会在首次切换前更新共享画像。不带编辑器的 Quick Chat 会瞬时隐藏侧栏但不覆写该画像——因此切到 Existing Session 或另一个带编辑器的 Quick Chat 时恢复共享可见性。8.2 多个可见会话多会话可见时可见性恢复是reveal-only只揭示不隐藏聚焦 workspace 会话时揭示其画像启用的部件聚焦 quick chat 或另一个无侧栏内容的会话时不隐藏 Editor。折叠回单个 Quick Chat 时 Editor 保持可见折叠回 workspace 会话时恢复该会话类型的完整共享画像。reveal-only 只适用于面板同步激活中的 Changes/Files 编辑器仍发布其 docked-details 能力Toggle Details 始终可用。九、单会话转换矩阵未最大化时该矩阵是全文的“结论性浓缩”任何动作在任何状态下的预期结果都应能在下表中查到。从动作到任何 workspace 会话状态切到同类型的另一会话相同的共享 editor/detail 画像每会话标签被恢复New ↔ Existing在生命周期类型间导航恢复目标类型的共享画像NewSubmit保留当前可见性播种 Existing 画像Detail onlynew session从 Files 打开一个文件Editor Detail编辑器被揭示并保持打开Detail only/Side pane closedcreated session点击ChangespillEditor onlyChanges 编辑器被揭示详情保持关闭除非另行恢复/打开Detail onlynew sessionToggle Details隐藏详情Editor only揭示空的编辑器——侧栏不消失Detail onlynew session将网格 sash 拖宽Detail only编辑器保持关闭Detail onlynew sessionToggle Sessions List 关闭Detail only详情面板按会话列表宽度变宽编辑器保持关闭Detail onlyToggle Details隐藏详情Editor only编辑器被揭示Editor DetailHide EditorDetail only详情保持宽度聊天扩展Editor DetailToggle Details隐藏详情Editor onlyEditor Detail调整窗口或外侧 sashEditor Detail调整大小从不改变详情可见性Editor onlyToggle Details显示详情Editor DetailDetail only/Editor only/Editor DetailToggle Side PanelSide pane closedSide pane closedToggle Side Panel恢复之前的 editor/detail 状态与最大化状态任何状态切到另一 workspace 会话相同的 editor/detail 可见性editor/detail 侧栏可见Toggle Sessions List 关闭同一面板状态editor/detail 侧栏按会话列表宽度变宽侧栏增长后会话列表已关Toggle Sessions List 打开同一面板状态editor/detail 侧栏回到折叠前宽度任何状态关闭最后一个编辑标签Side pane closed纯聊天打开标签恢复面板Detail onlycreated session将网格 sash 拖宽Detail only编辑内容保持关闭Editor only/Editor Detail激活Browser标签Editor only详情隐藏瞬时的Editor onlyBrowser 激活激活Files/Changes标签Editor Detail详情恢复Editor onlyBrowser 激活Hide EditorDetail only详情显示 Changes/Files 回退不会留空Detail onlyBrowser 是最后一个活动标签Show EditorEditor only详情再次隐藏——Browser 的瞬时隐藏规则恢复任何 new-session 面板状态Submit会话相同可见性与活动标签文件变更到达后 Changes 变为激活十、实现结构导读源码级证据场景文档明确指出规格与测试的分工边界——SINGLE_PANE_SCENARIOS.md 的第八节即“测试归属”具体的转换与回归问题属于 layout-controller 与 single-pane strategy 的测试本文档只定义状态模型与预期构图不是手工测试脚本。从源码结构看该功能的实现可以分成三层workbench 组合层browser/目录singlePaneWorkbench.ts、singlePaneEditorPart.ts、singlePaneAuxiliaryBarPart.ts、dockedAuxiliaryBarController.ts 负责把 Editor part 与 Auxiliary Bar 组合成一个带停靠详情栏的单一卡片并处理keepForDockedTabBar这类特殊布局路径。控制器层baseSessionLayoutController.ts 定义共享行为singlePaneLayoutController.ts 是与经典桌面 desktopSessionLayoutController.ts 平行的兄弟控制器二者都继承BaseLayoutController。策略层contrib/layout/browser/singlePane/控制器通过恰好三个生命周期策略组成其行为而非复用桌面的继承体系——singlePaneNewSessionStrategy.ts——未创建的 workspace-backed draftsinglePaneExistingSessionStrategy.ts——已创建的 workspace-backed 会话同时拥有 Toggle Details 命令与共享的受管标签协调器singlePaneQuickChatStrategy.ts——无 workspace 的 quick chat。每个策略拥有其阶段的完整纵向行为切片侧栏可见性、详情面板Changes/Files映射以及对两个 workspace 阶段共享受管标签对账管线SinglePaneDockedTabsCoordinator它同时执行 detail-only 的编辑区折叠。详情面板同步机制SinglePaneDetailPanelCoordinator与共享的 New/Existing 编辑器可见性画像存储singlePaneVisibilityProfileStore.ts是非策略的协调对象。场景文档反复出现的“一次性one-shot反应”“restore epoch”“settled 对账”“恢复驱动的编辑器变更 vs 用户动作”这些概念正对应控制器源码中_isRestoringSessionLayout的会话切换恢复信令与onDidEndSessionLayoutRestore回调——restore 驱动的编辑器变更绝不与用户动作混淆。与该控制器直接对应的测试位于 singlePaneStrategies.test.ts 及 baseSessionLayoutController.test.ts与规范中“回归测试承载 bug 修复、本文档承载状态与转换”的变更闸门互为印证。结语把这份场景文档当“状态机仲裁者”使用SINGLE_PANE_SCENARIOS.md 并不是一份使用手册而是一份面向开发与测试的可执行状态规范。在阅读或修改 single-pane 布局时请遵循它的纪律判断一个现象是不是 bug先查转换矩阵与各不变式标签栏永可见、关闭整个侧栏不关编辑器、Detail only 下 Changes/Files 永驻、reload 后关闭状态保持——任何偏离都指向回归修 bug 不进本文档进回归测试布局控制器测试与 single-pane strategy 测试新增用户动作时先确认它属于哪一条“状态到状态”的转换再在对应 strategyNew / Existing / Quick Chat中实现并保持“发布通道优先”的门控纪律命令式代码读IAgentWorkbenchLayoutService.isSinglePaneLayoutEnabled声明式when读SinglePaneLayoutEnabledContext绝不直接碰底层设置。需要继续深入时按序阅读 LAYOUT.md拓扑与部件归属→ LAYOUT_CONTROLLER.md控制器规则标签与持久化→ SESSIONS.md会话架构即可。【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Visual Studio Code Agents 窗口单面板详情布局Single-Pane Detail Panel状态与转换规范指南【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode本文以仓库 SINGLE_PANE_SCENARIOS.md 为骨架主体展开。该文档是 VS Code AgentsSessions窗口single-pane 单面板详情布局的用户场景、可见性状态与转换矩阵的权威规格说明配合 LAYOUT.md、LAYOUT_CONTROLLER.md 以及 src/vs/sessions/contrib/layout 下的源码实现共同阅读可完整掌握该布局的启用方式、控件契约、状态机设计以及背后的实现架构。这篇技术指南将帮助你搞清楚三件事如何开关该实验性布局、它在什么条件下生效第三面板的编辑器内容与停靠详情面板在哪些状态下如何出现与消失以及每一次用户操作切换会话、切换标签、点击各按钮、拖动分隔条如何通过受控的转换规则落到正确的面板构图。文中给出的是可直接用于开发与回归测试的完整场景清单与状态转换表而不是笼统的功能介绍。一、文档定位与变更门槛SINGLE_PANE_SCENARIOS.md 的第一段就给出了一个非常重要的“规范变更闸门”Specification change gate本文档只描述单面板布局的用户场景、状态与转换矩阵它不是手工测试脚本。如果一个 bug 修复只是“恢复某个既有场景”那么它应当被写进回归测试layout-controller 与 single-pane strategy 的单元测试而不是改这份文档。只有当预期的状态模型或转换矩阵本身发生变化时才允许更新本文档。这意味着该文档扮演的是“单一事实来源”的角色状态机如何定义、每个动作应该落到什么构图由它来裁定实现细节、像素、样式、动作摆放则由代码、设计 token、组件 fixture 与聚焦测试负责。参考同级的编辑区规格 Editor presentation 与控制器文档 LAYOUT_CONTROLLER.md、desktopSessionLayoutController.md可以看到同样的分权原则LAYOUT.md只管部件归属与 workbench 拓扑控制器文档管理“规则标签 / 持久化 / 测试归属”而本场景文档管理“状态与转换”。二、功能总览一个开关、一次读取、两条发布通道整个 single-pane 功能被一个实验性设置门控项值设置键sessions.layout.singlePaneDetailPanel代码常量DOCK_DETAIL_PANEL_SETTING读取时机仅启动时读取一次——修改该设置后需要**窗口重载window reload**才生效读取者只有createSessionsWorkbench它负责挑选 workbench/parts 组合在源码 sessionConfig.ts 中该常量定义与注释说明完全一致启用后Agents 窗口会把详情面板auxiliary bar停靠在 editor part 内部让一条编辑区标签栏横跨编辑内容与详情面板的整条宽度。读取结果被发布为两条通道供两类代码分别消费IAgentWorkbenchLayoutService.isSinglePaneLayoutEnabled—— 供命令式代码读取SinglePaneLayoutEnabledContext上下文键 —— 只供声明式when子句读取。其中上下文键定义于 contextkeys.ts其描述注释特意强调这是“gating single-pane behaviour 的唯一真相源由 workbench 在构造时按其所选布局设置一次”。功能必须依赖上述两个发布结果做判断任何命令式代码都禁止直接读设置或直接读上下文键。生效矩阵场景布局设置ON默认值 非手机视口单面板布局本文描述的全部内容手机视口phone viewport始终使用经典布局设置OFF所有 Agents 窗口使用经典布局本文其余内容完全不适用编辑区拓扑限制单面板布局下主编辑器Main Editor只支持恰好一个 editor group编辑器 split/grid 命令、快捷键、菜单、open-to-side 请求、split 拖放目标全部被禁用程序化创建 group、多 group 布局请求会被拒绝上述限制不适用于独立的 chat grid聊天网格仍是多组的。这一限制直接来自 LAYOUT.md 的描述single-pane 将 Editor 与 Auxiliary Bar 组成一个位于活动会话旁的“side pane”编辑器共享的多组能力被关闭。从源码结构看MainEditorPart/EditorGroupView只承载一个 group正是为了保证“一条标签栏 编辑内容 停靠详情面板”的单一构图不被拆分。三、第三面板的三大区域单面板布局下第三个面板是一张单一视觉卡片card内部包含三个区域区域是什么归属所有者标签栏Tab bar横跨全宽的一条标签条Changes / File / Browser 标签 末尾的Editor group 标题MainEditorPart/EditorGroupView编辑内容Editor content标签栏下方的编辑区多文件 diff 的 Changes、单个文件、浏览器等右侧按详情宽度内缩Editor part右侧按详情宽度内嵌详情面板Detail panel右侧停靠的辅助栏Branch Changes Checks或 Explorer/FilesDockedAuxiliaryBarController把 aux bar 停靠进 editor part 内部实现上停靠逻辑位于 dockedAuxiliaryBarController.ts编辑区的停靠式标签栏布局由MainEditorPart.layout的keepForDockedTabBar分支维护源码位于 src/vs/sessions/browser/parts/editorPart.ts。不变式Invariants——标签栏永远可见只要第三面板被展示——包括编辑内容被隐藏时、以及 new-session 视图中——标签栏都保持可见。即使 editor part 在逻辑上被隐藏它仍由MainEditorPart.layout的keepForDockedTabBar路径在 single-pane 详情可见时维持布局。另外在可见侧栏打开/恢复空 FilesEmpty Files会揭示 Files 详情用户可以随后隐藏该详情下次打开 Empty Files 时它会被再次揭示。四、面板可见性状态机设E 编辑内容可见D 详情面板可见。面板支持以下四种状态状态ED含义Editor Detail✅✅正常协作状态左编辑内容、右详情、顶部标签栏Detail only❌✅编辑内容折叠Hide Editor标签栏 详情可见聊天区接管被释放的编辑宽度。详情保持自身宽度不拉伸填满面板。进入该状态会关闭所有非停靠的编辑标签仅保留停靠的 Changes/Files 标签可重开的标签被捕获并在编辑区再次显示时恢复不可恢复的例如 dirty 的 untitled Search 编辑器被丢弃Editor only✅❌详情被关掉编辑内容填满面板标签栏仍横跨顶部Side pane closed❌❌整个第三面板关闭仅剩聊天。通过Toggle Side Panel或在最后一个编辑标签关闭时到达永远不会由详情切换按钮触发。关闭整个侧栏并不关闭编辑器——只有Detail only式折叠编辑隐藏而详情保持打开才会关闭编辑器当两部分同时隐藏时编辑器原封不动侧栏重新打开时它们会回来下面几类规则是状态机的“补丁”控制何时应用哪个转换4.1 可见性画像visibility profile的共享范围只有Existing Sessions共享持久化的 Editor/Details 可见性画像。New Session不套用、也不捕获该画像它进入时只做一次性处理当恢复出的编辑集合里除受管 Changes 与 Empty Files 输入外别无其他输入时隐藏一次编辑器。提交Submit才会播种 Existing 画像。活动编辑器决定详情内容每个 diff 编辑器选中 Changes每个文件编辑器选中 Files。4.2 尺寸分配从 closed 打开侧栏例如聊天占满全宽时点击Changes以Sizing.Distribute揭示编辑器。网格用被揭示视图的位置来分配其所在 split因此 Sessions part 与侧栏在不经任一部分自算宽度的情况下获得等宽空间。之后的侧栏尺寸是workbench 级别而非每个会话级别编辑器网格节点宽度由 workbench 网格所有并全局持久化workbench.sessions.partSizes用户一旦调整过侧栏宽度该宽度就一直保留——包括跨会话切换切换会话不改变侧栏宽度与跨重载。切换 Details 时编辑器可见时开关详情不会改动编辑器网格节点与 Sessions/chat 宽度详情在既有侧栏内打开并从编辑内容取宽度隐藏详情把宽度还给编辑内容。重载无闪烁workbench 拥有几何重载时 workbench 用自己的持久化 part-sizesworkbench.sessions.partSizes由createDesktopGridDescriptor消费恢复侧栏编辑节点宽度一次绘制就按正确尺寸画好网格。workbench 层面隐藏编辑器仍会把网格节点折叠到详情宽度并缓存捕获的编辑器隐藏宽度_dockedEditorSizeBeforeHide在立即 re-show 时优先于当前 Details 可见性生效。会话列表折叠后重开关闭整个侧栏会把编辑器网格节点折叠到0px但“Editor-before-Details”的关闭顺序会在节点仍可见时先捕获当前侧栏宽度重开时恢复该构图而不会把0px当作用户宽度。若 New Session 之后落到仅 Files 状态隐藏编辑器而 Details 仍可见时节点收缩到 Details 宽度并捕获该侧栏宽度供下次打开文件使用回到 Existing Session 的 Editor-only 画像则恢复同一宽度——因此反复切换会话不会改变 Sessions/chat 边界。五、控件全集与行为契约下表是单面板布局的全部用户控件。这是实现侧按钮注册、when门控、命令实现与测试侧single-pane strategy 测试都必须对标的契约控件位置效果Toggle Details≡编辑器头部布局工具栏位于操作溢出按钮与一个分隔符之后显示/隐藏详情面板默认快捷键⌥⌘L。若编辑器已隐藏隐藏详情会揭示编辑器→Editor only面板绝不会被留空。它从不改动 Sessions 侧栏——后者始终由用户显式控制。其toggled状态AuxiliaryBarVisibleContext与实际渲染保持同步。仅当活动标签是Changes 或 Files非 Browser/Search——它们没有详情时才显示Maximize / Restore编辑器标题栏主要行内位置最大化编辑区最大化期间强制展示 Changes 详情取消最大化时恢复。默认快捷键⌥⌘E在编辑区可见时切换最大化/还原Hide Editorright-panel-hide编辑器标题栏标签条Maximize/Restore 之后关闭编辑内容并保留详情→Detail only。停靠侧栏收缩到详情宽度被释放的编辑宽度进入聊天而非详情。无论当前是否有详情面板可见它始终显示且始终可用Show Editorright-panel-show编辑器标题栏标签条与 Hide Editor 同一槽位再次揭示可能是空的编辑内容。只要编辑区是关闭的它就始终显示与活动标签是否支持详情无关Collapse All DiffsChanges 编辑器头部主要行内位置折叠 Changes 多文件 diff 中的所有文件SessionChangesEditor.collapseAllDiffsAdd Tab标签条末尾打开 Add Tab 菜单Browser⇧⌘K BSearch⌘K S仅 workspace-backed 会话当 Changes 标签缺失时提供Changes项、当 Files 标签缺失时提供Files项⌘K B任何 workspace 会话均可。恢复出的受管 Changes/Files 标签插入标签条末尾。Search 会打开新的 Search 编辑器Quick Chats 不可用。编辑区关闭时隐藏Toggle Side Panel命令 / 快捷键关闭/打开整个侧栏编辑器 详情一体→ 纯聊天及返回。机制位于 workbench 布局服务toggleSidePane编辑区最大化时共享的Workbench.toggleSidePane()会记住最大化状态、取消最大化、再执行折叠使被恢复的详情也一并隐藏重开时先恢复完整侧栏构图再重新最大化编辑器。隐藏处于焦点的侧栏会把焦点移到会话列表Toggle Sessions List标题栏 / 命令折叠/展开左侧会话列表。折叠把释放的宽度给编辑器/详情侧栏不是聊天重开恢复之前的编辑器/详情宽度聊天拿回空间。任何 single-pane 编辑器或详情操作都不会改变该可见性Grid sash聊天与第三面板之间拖动侧栏从不改变 Details 可见性。Details 保持最小宽度编辑内容先让步、在宽度压力下最终折叠。详情-only 时把侧栏拖宽仍保持编辑内容关闭。Details 可见时双击保留当前 Details 宽度把其余宽度在聊天与编辑内容间平分无 600px 上限窄布局中网格最小宽度优先。reset 后隐藏 Details 不改变聊天/侧栏边界并把 Details 宽度还给编辑内容。Details 隐藏时 sash 用原生平分detail-only 模式下 reset 会把 Details 重置为300pxChanges pill会话头部 meta 行打开受管 Changes 多文件 diff 编辑器并在侧栏已关闭或处于 detail-only 时显式揭示编辑区。受管 Changes 标签仍被排除在“自动 reveal-on-open”之外——仅激活其标签不会揭示编辑器5.1 编辑器动作可见性三组互相独立、门控不同的按钮在编辑器动作层面需要区分三类视觉逻辑本段是理解控件“为何如此排布”的关键Maximize/Restore、Toggle Details、Open in Modal在编辑区关闭时全部隐藏受MainEditorAreaVisibleContext控制。Toggle Details 紧排在 Maximize/Restore 之前。Hide Editor 与 Show Editor 是互斥的一对负责编辑区状态的开关两者都渲染在标签条 editor-title 布局簇MenuId.EditorTitleLayout、紧接 Maximize/Restore 之后只分别以MainEditorAreaVisibleContext为 true/false 门控。与 Toggle Details 不同它们不看活动标签是否有停靠详情面板、也不看详情当前是否可见——没有HasDockedDetailsContext门控、没有AuxiliaryBarVisibleContext前置条件这与 Maximize/Restore 在同一簇中“始终显示”的行为一致。Hide Editor 在自身run()里无条件揭示辅助栏即使详情此前被隐藏也有落脚点其详情面板实际显示什么由 New/Existing Session strategy 的详情面板映射经共享的SinglePaneDetailPanelCoordinator决定——活动标签自己的详情若 Browser 标签无自有详情则回退到 Changes/Files见第七节。Show Editor 通过会话头 Changes pill 同款的显式揭示 APIrevealEditorPartExplicitly()揭示编辑器再聚焦编辑器 group。Toggle Details 保留“有停靠详情面板”门控HasDockedDetailsContext定义于 contextkeys.ts受管 Changes/Files 标签或文本文件编辑器为 true——切换一个不存在的详情面板毫无意义。5.2 受管 Files 占位标签的生命周期空的 Files 占位标签与 Changes 标签在编辑器 group 为空且发生 view-open 触发会话切换或侧栏揭示时打开只要布局处于Detail only两者都保持存在。空 Files 占位激活期间agent-feedback 导航浮层被隐藏。打开一个真实文件会作为对该次 open 的一次性反应one-shot“收拾掉”空占位得到[Changes][file]条带——这是一次性的、不是常驻规则因此用户仍可在真实文件打开时通过Files添加 Files 标签该操作打开EmptyFileEditorInput而非真实文件故不会被收拾掉。Existing 与 New Session 在真实文件关闭时都不会重新添加占位只有当那次关闭让每个主编辑器 group 都变空时它们才关闭整个侧栏。5.3 New Session 的转换归属是分离的入场Entry只拥有“会话恢复后的一次性冗余 Editor 隐藏”这一转换。已完成的一次 closed→open Toggle Side Panel 转换只拥有“受管标签安定后仅 Files 的 dock 转换”。最后一个编辑器关闭监听 editor service 的 did-close 事件用共享的 all-main-groups-empty 判定editor-part 自动可见性被抑制期间忽略程序化关闭随后关闭整个侧栏。通用侧栏 reveal 通知永不启动该 toggle 规则——因此“编辑器打开”不能反哺进入该规则。5.4 空编辑组是生命周期所有的SinglePaneWorkbench在所有编辑器关闭时不改变可见性New 与 Existing Session 在最后编辑器关闭时关闭整个侧栏Quick Chat 则保持侧栏打开。5.5 布局驱动 vs 用户驱动的编辑器变更默认停靠标签在settled 的会话切换恢复时重新打开进空 group基础控制器在恢复纪元working-set apply aux 恢复完成后触发onDidEndSessionLayoutRestorestrategy 据此对账。这一点对 New Session 至关重要其空的working set 会先关闭上一会话的停靠标签、在切换之后腾空 group在 settled 的恢复结束点对账读到的是可靠的空 group从而重开两个受管标签。若在异步 apply 期间对瞬态的编辑器变更即时反应会与空状态发生竞态。用户驱动的编辑器变更打开文件、关闭标签在 Editor 可见时不会重开默认值在 Detail only 下标准关闭动作不能移除受管输入每次对账都会恢复被生命周期工作移除的任一输入。Existing→Existing 导航会在原地用新会话的 Changes 输入替换旧会话的 Changes 输入保留标签位置与激活状态——而不是“可见地关闭 Changes 标签再打开另一个”。5.6 无文件夹 composer 到 workspace draft 的两步过渡打开New Session先露出无文件夹 composer再播种其具体 workspace draft第一步移除上一会话的 Changes 标签期间共享 Files 占位可保持 group 非空第二步在wantsChangesTab变为 true 时显式确保 Changes当选中的会话文件夹与新会话默认文件夹不同时workspace 门控的 working-set 恢复可能稍后才安定并移除那个过早的 Changes 标签保留 Files因此 settled 恢复会对未创建会话重复一次 one-shot Changes ensure。只依赖空组规则或只依赖初始 eligibility 转换都会让 Files 成为唯一标签直到下一次 reveal 或 New Session 手势。5.7 New Session 提交Submit提交保留当前 Editor/Details 构图并播种 Existing Sessions 画像。Files 标签保持激活直到被提交会话上报首批文件变更此后 Changes 变为激活——但不揭示 Editor。该“待定激活”只作用于被提交的会话切走不会在别的会话里激活 Changes。5.8 Detail-only 不变式无论何时侧栏处于Detail onlyaux-bar 详情可见而无编辑区——例如 new-session 视图或编辑器被隐藏的已创建会话侧栏都收缩到持久化 Details 宽度且停靠详情面板展示受管停靠输入——因此 Changes 与 Files始终存在。打开文件会恢复之前的“Editor Detail 组合宽度”不改变 Details 宽度。两个输入都带EditorInputCapabilities.CannotClose能力每次对账读取的都是已 settled 的当前部件可见性即使 group 非空也恢复被生命周期工作移除的任一输入。Editor 可见时该能力被移除并维持“只向空 group 添加”的严格规则。5.9 关闭受管标签Editor 可见时用户可关闭受管 Changes/Files 标签它们非 preview、非 sticky。这种关闭被尊重且无任何 dismissal 记账默认标签只在 view-open 触发时向空编辑组打开外加前述一次性 submit 激活。所以关掉一个标签而另一个或真实文件还在时group 非空、不会重建。Detail only 下关闭命令与标签上的关闭手段一致地让底层输入保持打开内部生命周期工作仍可在 working-set 应用、会话切换、陈旧标签清理时强关任一输入。Editor 可见时关闭最后一个标签会关闭整个侧栏重开空组恢复默认值。workspace 会话在 Editor 可见期间关掉受管标签后Add Tab菜单会给出对应重开项——ChangesSinglePaneChangesTabMissingContext门控与FilesSinglePaneFilesTabMissingContext门控两键定义见 contextkeys.ts重加的标签使 group 非空因此得以存活。5.10 生命周期清理后的重开、跨重载记忆、打开文件与缺失动作生命周期工作强关所有标签后整个侧栏可能关闭侧栏重开时受管 Changes/Files 标签被 re-ensure。关闭整个侧栏的状态跨窗口重载被记住。重载后被恢复的受管标签不会再次揭示详情详情面板的强制揭示以“编辑内容可见”为门控因此完全关闭的侧栏保持关闭直到用户重开。打开文件Files的 add-tab 项打开的标签是pinned非 preview tab。单面板模式中不存在的动作Close Editor Area经典布局保留它single-pane 自己的Show Editor动作是 Hide Editor 的对应物。六、标签类型Tabs标签说明Changes自定义SessionChangesEditorBranch Changes 下拉 diff 统计 内嵌多文件 diff。pinned 且排在首位每个带 workspace 的会话都有包括 New Session draftFile空 File 标签EmptyFileEditorInput作为落地标签外加用户打开的真实文件编辑器。打开时pinned、不激活、保持焦点preserve-focus——绝不从聊天抢焦点Browser集成浏览器BrowserEditorInput自动受管标签pinned 的 Changes 标签与默认 File 标签都在suppressEditorPartAutoVisibility()下打开——它们从不揭示编辑内容。只有用户动作打开真实文件/diff或拖动 sash才揭示编辑器。源码中的实现分布见 singlePaneDockedTabsCoordinator.ts 与 emptyFileEditor.contribution.ts。七、详情面板内容由活动标签驱动SinglePaneLayoutController实现于 singlePaneLayoutController.ts负责把活动编辑标签映射为详情内容详情面板的可见性是全局的可见期间其容器跟随活动标签活动标签详情面板Changes 或任何 diff 编辑器Branch Changes 文件列表 Checks详情可见期间展示 Changes 容器任何文件或 Markdown 预览编辑器ExplorerFiles/Explorer 树详情可见期间展示 Files 容器Browser瞬时隐藏当 Browser 标签激活且编辑区保持可见时隐藏切回时恢复。若编辑区本身在 Browser 激活时被隐藏如Hide Editor面板改显 Changes/Files 回退内容——因为它是屏幕上仅剩的东西规则 1 —— “激活即揭示激活后尊重”切到 Changes/File 标签会用正确容器揭示详情。同一标签保持激活期间用户的显式隐藏详情用详情切换按钮被尊重、不会被再次强制揭示切换标签会再次揭示。规则 2 —— Browser 是瞬时的但仅在编辑区可见时成立Browser 标签在编辑内容停留在屏幕上时隐藏详情面板切回 Files/Changes恢复它。Browser 激活时隐藏编辑区Hide Editor不会让面板空白——它显示与会话无活动编辑器时相同的 Changes/Files 回退再次揭示编辑区Show Editor后“Browser 隐藏详情”规则恢复。实现上这个“活动标签 → 详情容器”的映射由 singlePaneDetailPanelCoordinator.ts 承担同步机制而具体哪类会话回退到什么容器则由三种 strategyNew/Existing/Quick Chat各自裁定。八、会话生命周期布局规则Existing Sessions共享 Editor/Details 可见性画像New Sessions不拥有生命周期可见性状态其一次性入场规则只在 Empty Files 是唯一输入时隐藏冗余编辑内容提交保留当前构图并更新 Existing 画像。8.1 Quick Chats / 无 workspace带已保存编辑器的 Quick Chat 与 Existing Sessions共享侧栏总可见性可见的 Existing 构图映射为 Editor-onlyQuick Chat 没有 Details隐藏构图保持隐藏。打开第一个编辑器、以及带编辑器的 Quick Chat 内做可见性变更都会在首次切换前更新共享画像。不带编辑器的 Quick Chat 会瞬时隐藏侧栏但不覆写该画像——因此切到 Existing Session 或另一个带编辑器的 Quick Chat 时恢复共享可见性。8.2 多个可见会话多会话可见时可见性恢复是reveal-only只揭示不隐藏聚焦 workspace 会话时揭示其画像启用的部件聚焦 quick chat 或另一个无侧栏内容的会话时不隐藏 Editor。折叠回单个 Quick Chat 时 Editor 保持可见折叠回 workspace 会话时恢复该会话类型的完整共享画像。reveal-only 只适用于面板同步激活中的 Changes/Files 编辑器仍发布其 docked-details 能力Toggle Details 始终可用。九、单会话转换矩阵未最大化时该矩阵是全文的“结论性浓缩”任何动作在任何状态下的预期结果都应能在下表中查到。从动作到任何 workspace 会话状态切到同类型的另一会话相同的共享 editor/detail 画像每会话标签被恢复New ↔ Existing在生命周期类型间导航恢复目标类型的共享画像NewSubmit保留当前可见性播种 Existing 画像Detail onlynew session从 Files 打开一个文件Editor Detail编辑器被揭示并保持打开Detail only/Side pane closedcreated session点击ChangespillEditor onlyChanges 编辑器被揭示详情保持关闭除非另行恢复/打开Detail onlynew sessionToggle Details隐藏详情Editor only揭示空的编辑器——侧栏不消失Detail onlynew session将网格 sash 拖宽Detail only编辑器保持关闭Detail onlynew sessionToggle Sessions List 关闭Detail only详情面板按会话列表宽度变宽编辑器保持关闭Detail onlyToggle Details隐藏详情Editor only编辑器被揭示Editor DetailHide EditorDetail only详情保持宽度聊天扩展Editor DetailToggle Details隐藏详情Editor onlyEditor Detail调整窗口或外侧 sashEditor Detail调整大小从不改变详情可见性Editor onlyToggle Details显示详情Editor DetailDetail only/Editor only/Editor DetailToggle Side PanelSide pane closedSide pane closedToggle Side Panel恢复之前的 editor/detail 状态与最大化状态任何状态切到另一 workspace 会话相同的 editor/detail 可见性editor/detail 侧栏可见Toggle Sessions List 关闭同一面板状态editor/detail 侧栏按会话列表宽度变宽侧栏增长后会话列表已关Toggle Sessions List 打开同一面板状态editor/detail 侧栏回到折叠前宽度任何状态关闭最后一个编辑标签Side pane closed纯聊天打开标签恢复面板Detail onlycreated session将网格 sash 拖宽Detail only编辑内容保持关闭Editor only/Editor Detail激活Browser标签Editor only详情隐藏瞬时的Editor onlyBrowser 激活激活Files/Changes标签Editor Detail详情恢复Editor onlyBrowser 激活Hide EditorDetail only详情显示 Changes/Files 回退不会留空Detail onlyBrowser 是最后一个活动标签Show EditorEditor only详情再次隐藏——Browser 的瞬时隐藏规则恢复任何 new-session 面板状态Submit会话相同可见性与活动标签文件变更到达后 Changes 变为激活十、实现结构导读源码级证据场景文档明确指出规格与测试的分工边界——SINGLE_PANE_SCENARIOS.md 的第八节即“测试归属”具体的转换与回归问题属于 layout-controller 与 single-pane strategy 的测试本文档只定义状态模型与预期构图不是手工测试脚本。从源码结构看该功能的实现可以分成三层workbench 组合层browser/目录singlePaneWorkbench.ts、singlePaneEditorPart.ts、singlePaneAuxiliaryBarPart.ts、dockedAuxiliaryBarController.ts 负责把 Editor part 与 Auxiliary Bar 组合成一个带停靠详情栏的单一卡片并处理keepForDockedTabBar这类特殊布局路径。控制器层baseSessionLayoutController.ts 定义共享行为singlePaneLayoutController.ts 是与经典桌面 desktopSessionLayoutController.ts 平行的兄弟控制器二者都继承BaseLayoutController。策略层contrib/layout/browser/singlePane/控制器通过恰好三个生命周期策略组成其行为而非复用桌面的继承体系——singlePaneNewSessionStrategy.ts——未创建的 workspace-backed draftsinglePaneExistingSessionStrategy.ts——已创建的 workspace-backed 会话同时拥有 Toggle Details 命令与共享的受管标签协调器singlePaneQuickChatStrategy.ts——无 workspace 的 quick chat。每个策略拥有其阶段的完整纵向行为切片侧栏可见性、详情面板Changes/Files映射以及对两个 workspace 阶段共享受管标签对账管线SinglePaneDockedTabsCoordinator它同时执行 detail-only 的编辑区折叠。详情面板同步机制SinglePaneDetailPanelCoordinator与共享的 New/Existing 编辑器可见性画像存储singlePaneVisibilityProfileStore.ts是非策略的协调对象。场景文档反复出现的“一次性one-shot反应”“restore epoch”“settled 对账”“恢复驱动的编辑器变更 vs 用户动作”这些概念正对应控制器源码中_isRestoringSessionLayout的会话切换恢复信令与onDidEndSessionLayoutRestore回调——restore 驱动的编辑器变更绝不与用户动作混淆。与该控制器直接对应的测试位于 singlePaneStrategies.test.ts 及 baseSessionLayoutController.test.ts与规范中“回归测试承载 bug 修复、本文档承载状态与转换”的变更闸门互为印证。结语把这份场景文档当“状态机仲裁者”使用SINGLE_PANE_SCENARIOS.md 并不是一份使用手册而是一份面向开发与测试的可执行状态规范。在阅读或修改 single-pane 布局时请遵循它的纪律判断一个现象是不是 bug先查转换矩阵与各不变式标签栏永可见、关闭整个侧栏不关编辑器、Detail only 下 Changes/Files 永驻、reload 后关闭状态保持——任何偏离都指向回归修 bug 不进本文档进回归测试布局控制器测试与 single-pane strategy 测试新增用户动作时先确认它属于哪一条“状态到状态”的转换再在对应 strategyNew / Existing / Quick Chat中实现并保持“发布通道优先”的门控纪律命令式代码读IAgentWorkbenchLayoutService.isSinglePaneLayoutEnabled声明式when读SinglePaneLayoutEnabledContext绝不直接碰底层设置。需要继续深入时按序阅读 LAYOUT.md拓扑与部件归属→ LAYOUT_CONTROLLER.md控制器规则标签与持久化→ SESSIONS.md会话架构即可。【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
