Feature request: additive top-level sidebar navigation for plugins

[zhaobo258-netizen]

Summary

Please expose an additive, root-scoped primary navigation extension for Web client plugins. This would let plugins contribute discoverable top-level entries such as Calendar, Files, Data, or Browser without replacing the entire sidebar or patching the DOM.

Downstream use case

I am building a calendar plugin. The existing conversation.view extension works for a session-scoped tab, but a calendar is a global tool. It should remain reachable from primary navigation independently of whichever session is active.

Similar needs are already visible in community work:

• dsh-sidebar-files —— 给 DSH 侧边栏加上 类 VS Code 资源管理器的文件树 #1941 implements Sessions/Files sidebar tabs, but notes that shell changes may break the injection and require a fallback to a footer button and modal.
• [Feature request] A general per-workspace child slot for the workspace overflow menu (`sidebar.workspaces.entry`) #1413 and Feature request: extensible actions in the workspace row menu #2631 request additive workspace-row actions. They demonstrate demand for supported UI contribution points, but do not cover root-level navigation.
• feat(sidebar): first-class workspace-less "chat" sessions — Work/Chat affordance in the sidebar and a "no workspace" option in the picker #1795 mentions a list slot in the sidebar session area, but focuses on Work/Chat session modes.

This request is separate: a generic extension point for plugin-owned first-level application destinations.

Current gap

In the public contracts shipped with @deepseek-ai/dsh@0.1.0-rc.6:

• sidebar and sidebar.workspaces are single-owner surfaces.
• sidebar.footer.action is additive, but semantically limited to footer actions.
• conversation.view is additive, but scoped to an active conversation.

A plugin therefore has to choose between replacing core UI, using a semantically incorrect location, or relying on fragile DOM/CSS injection.

Possible contract

The exact naming is only illustrative. One option would be:

"sidebar.navigation": {
  kind: "list"
  scope: "root"
  owner: PrimaryNavigationOwnerProps
}

"shell.page": {
  kind: "list"
  scope: "root"
  owner: ShellPageOwnerProps
}

A higher-level registry could also work:

ctx.navigation.register({
  id: "calendar",
  label: t("calendar"),
  icon: CalendarIcon,
  order: 30,
  target: { type: "shell.page", id: "calendar" },
})

Expected behavior

• Multiple plugins can coexist with deterministic ordering.
• Expanded sidebar shows icon and label; collapsed rail shows icon, tooltip, and accessible name.
• Entries can be hidden by plugin or user settings.
• Keyboard navigation and visible focus follow core behavior.
• Unregistering or uninstalling a plugin removes its entry cleanly.
• Core Workspaces, Search, and Settings entries are never replaced.
• The navigation target can be session-independent.

The smallest useful step would be an additive primary-navigation item that can activate an existing view. For genuinely global tools, a root-scoped page surface would be the better long-term target.

This is not a request for a Calendar-specific special case. If an equivalent contract is already planned, please point me to it. I would be happy to test the API with a minimal downstream plugin example.

[tianhao8687]

The gap analysis matches current master: sidebar.workspaces is single-owner, sidebar.footer.action is additive but action-only, and conversation.view is session-scoped. A calendar should not have to impersonate any of those.

I would avoid exposing two unrelated registrations (sidebar.navigation plus shell.page) unless the framework can commit and dispose them atomically. A simpler contract is one root-scoped page contribution, analogous to settings.section:

'shell.page': {
  kind: 'list'
  scope: 'root'
  // registration options: id, order, label, icon
}

The shell can project each page registration into both the sidebar rail and the page body, so a plugin cannot leave an orphan nav item or unreachable page. Important semantics to define up front:

• duplicate IDs reject; core IDs are reserved;
• disposing the active page falls back to the previous/core page and restores focus;
• ordering is deterministic, with localized labels and an approved semantic icon vocabulary;
• collapsed mode supplies tooltip + accessible name and full keyboard navigation;
• optional visibility/disabled state is data, not DOM injection; and
• URL/history behavior is owned by the shell.

A first increment could register a page and let the shell create its nav item automatically. That is enough to validate the API with the Calendar plugin before adding user reordering or more complex routing.

[weijiafu14]

你的现状分析是准的，我能给一份独立佐证——我把 DSH 客户端包里 SlotMap 的声明整个数过一遍（43 个座位，逐个记 kind 和 scope）。结论和你一致，但有一个座位你漏了，它可能是今天唯一能用的临时落点。

一、frame 级只有 4 个座位，其中 3 个是 single

座位	kind	说明
sidebar	single	已被占用，注册即替换整个侧栏
conversation	single	同上
details	single	同上
shell.overlay	list	可叠加的浮层，点击穿透

也就是说：frame 这一层唯一可加性的座位是 shell.overlay，而它是浮层不是导航项。你说的"要么替换核心 UI、要么用语义不对的位置、要么靠脆弱的 DOM/CSS 注入"——这个三选一是座位表的直接后果，不是谁没找对 API。

对你的日历插件，shell.overlay 也许能当个临时落点：从 sidebar.footer.action 放一个入口，点开在 overlay 里画一个全局面板。它不是你要的一等公民导航，但它是加性的、root scope 的、不用替换任何人的东西，比 DOM 注入稳。要不要走这条你自己判断——它解决的是"我今天能不能发布"，不是你这个提案要解决的问题。

二、single 的代价我们付过，可以给你一个具体的案例

我维护 pi2dsh（Pi 生态兼容层），它在 DSH Web 里也有自己的一半。我们撞的正是 sidebar 是 single 这件事：

想在侧栏加东西的插件，只能整个替换侧栏。 于是社区里出现了 dsh-better-sidebar —— 一个替换掉官方侧栏、然后自己开放扩展位的插件。它很好用，但后果是：想在侧栏露面的插件，就得依赖它。 我们的子代理任务面板就是这么落地的（与 dsh-better-sidebar 组合）。

这条链的问题不是谁做得不好，而是 single 座位必然催生一个"二级平台"：一个第三方插件事实上成了侧栏的守门人，所有想上侧栏的插件都得先跟它对齐。用户装两个各自替换侧栏的插件时，只有一个能赢。

这个案例值得放进你的提案，因为它把"缺扩展点"的代价说成了具体的东西：不是插件作者不方便，是生态被迫在框架之外重建了一个框架。

三、@tianhao8687 那个"一个 shell.page、类比 settings.section"的建议，我可以从实践上背书

他建议不要同时开 sidebar.navigation 和 shell.page 两个不相关的注册、改成一个 root-scoped 的页面贡献，由 shell 自己投影出导航项和页面体。这个形状是对的，而且 settings.section 这个类比选得特别准——因为它是今天少数真正对仓库外插件敞开的座位。

我们的产品层就是用 settings.section 在 DSH 的设置页里挂了一个自己的管理页，跑在真 DSH loop 上。它证明了两件事：

1. slot 体系本身对仓库外插件没有白名单（这一点和 settings 的数据面不同，见下）；
2. "注册一个 section、由宿主负责放到哪、怎么排序、怎么销毁"这个契约是能用的——插件不需要碰 shell 的布局，也就不会因为 shell 改版而碎掉（你引的 dsh-sidebar-files —— 给 DSH 侧边栏加上 类 VS Code 资源管理器的文件树 #1941 提到的正是这个风险）。

所以他说的"shell 把每个 page 注册同时投影进侧栏 rail 和页面体，插件就不可能留下孤儿导航项或不可达页面"，在 settings 那边已经是既成事实，不是设想。

一个必须说清的坑（我们踩过）：settings.section 只给了你 UI 那一半。数据那一半在 apiproxy 里有一张硬编码白名单，仓库外插件的 ctx.settings.register 命名空间拿不到配置面，只能自己起 ctx.webServer 路由重写一遍数据面。#3114 正是在提这件事的 RFC。你这个提案如果被接受，最好一并明确 shell.page 的数据面走哪条路——否则会重演"UI 位开了、数据面还得自己造"的局面。

四、这个诉求的规模比你列的更大

你引了 #1941、#1413、#2631、#1795。还有两条同源的：

• #4543 —— 我们提的上游提案，问题类完全相同；
• #4594 —— 正文里引用了 Proposal: first-class bundle-to-bundle dependencies (in-box bundles already rely on this — third-party bundles can't) #4543，并且描述的正是上面第二节那个 dsh-better-sidebar 强依赖问题。

加上你这条就是 7 个独立线程在要同一样东西，跨越日历、文件、会话、工作区行、浏览器等完全不同的用例。这个数字本身是论据：七个人各自撞到同一堵墙、各自绕出一套不同的临时办法，说明缺的是一个契约而不是七个特例。 建议把这份清单放进原帖开头。

边界与利益相关

我们不修 DSH 自家组件——slot 体系、shell、侧栏都在 DSH 里。上面全是佐证、经验和串联。

座位清单那部分是我自己从客户端包的 SlotMap 声明数出来的，不是官方文档，版本也只覆盖我手上那份；如果你在源码里读到不同结果以你的为准。

利益相关：我维护 pi2dsh，并且 #4543 是我们提的——所以我在这个议题上不是中立第三方，我是这个契约的潜在受益者之一。这一点你在权衡我上面那些话时应该知道。这条不推销：你要的是官方开一个座位，装我们的东西对此毫无帮助（我们和你一样卡在同一堵墙前面）。