Skip to content

dsh-sidebar-rail

Verified

@skylerfee/dsh-sidebar-rail · v0.3.3 · MIT · Web UI

侧栏收起后也能快速切换项目、查看最近会话、管理定时任务和插件;鼠标靠近窗口左缘就会滑出图标轨。Keep quick access to your projects, recent sessions, scheduled tasks and plugins after the sidebar is collapsed.

Install

dsh plugin add @skylerfee/dsh-sidebar-rail

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Readme

English | 简体中文

dsh-sidebar-rail

CI npm 版本 macOS Desktop MIT 许可证

给 DeepSeek Harness 的 macOS Desktop 折叠侧栏补充工作区、最近会话、定时任务、插件和账号入口。

图标轨默认隐藏。收起宿主侧栏后,将指针移到窗口左缘的 12px 热区,就会滑出一条 56px 图标轨;悬停图标可查看浮层,点击条目即可导航。展开侧栏时,搜索、工作区树、账号菜单和设置继续使用宿主原生界面。

界面预览

以下为 macOS Desktop 中文界面、深色外观与 Catppuccin 皮肤下的真实局部截图。工作区名称和会话标题已模糊处理;图中最近会话条数为 9,默认值仍为 5。

工作区、置顶与最近会话我的插件
折叠图标轨的工作区浮层,含置顶项目、最近会话状态和条数设置 图标轨的我的插件浮层,展示用户启用的插件与版本

导航

界面预览 · 安装与启停 · 使用方法 · 设置与本地数据 · 常见问题 · 开发与贡献 · 详细文档

支持范围

环境 / 状态 行为
macOS Desktop,侧栏折叠,视口宽度 ≥ 768px 默认隐藏图标轨,由左缘热区或键盘焦点唤出
macOS Desktop,侧栏折叠,视口宽度 < 768px 不渲染图标轨;仍可用宿主按钮展开侧栏
macOS Desktop,侧栏展开 不渲染图标轨,保留原生侧栏
Web(任意平台) 不渲染图标轨,保留宿主已有的折叠轨
Windows / Linux Desktop 不渲染图标轨,未验证支持

已记录的真机环境为 macOS Desktop 0.2.2-rc.1;其他宿主版本的兼容范围见 package.json 的 peerDependencies。部分新设置与余额显示尚有未验证项,见验证记录。源码开发与检查需要 Node.js ≥ 22.19.0,无需安装项目依赖或构建。

安装与启停

需要 DSH 的 Desktop 或 Web 客户端,以及可用的 profile。安装只影响当前 profile,不改动 DSH 本身。

方式一:插件管理页(推荐)

在 DSH 侧栏进入 插件 页,点右上角 添加插件,在「包名或地址」里填入后按 安装:

@skylerfee/dsh-sidebar-rail

该输入框接受 npm 包名、Git 仓库地址和本地目录,本插件用 npm 包名即可。安装完成后按提示重启或刷新 DSH,再确认「侧栏图标轨」处于启用状态。

方式二:命令行

dsh plugin --profile desktop add @skylerfee/dsh-sidebar-rail

dsh plugin 会把参数转交给 profile 目录里的 pnpm;把 desktop 换成你实际使用的 profile 名,首次使用会自动初始化。也可以直接进 profile 目录执行 pnpm add。装完重启 DSH 生效。

方式三:在对话里让助手安装

启用插件管理工具的 profile 可以让助手代为安装(这是工具参数,不是终端命令):

{
  "action": "install_bundle",
  "target": "@skylerfee/dsh-sidebar-rail"
}

本地开发时把 target 换成本仓库的绝对目录,即安装一条 link: 依赖,改完代码重启即可看到效果。

启停与卸载

启停是 profile 配置层的开关,用插件管理页;命令行只能装卸包。

操作 做法
停用 插件管理页关掉「侧栏图标轨」开关(保留已装依赖,随时可再打开)
重新启用 打开同一个开关
卸载 插件管理页进入详情页点 卸载,或执行 dsh plugin --profile desktop remove @skylerfee/dsh-sidebar-rail

也可以让助手调用 plugin_manager 的 set_bundle(启停)或 remove_bundle(卸载)。停用或卸载后,localStorage 里的本地偏好(置顶项目、最近会话条数)仍保留。

使用方法

  1. 用宿主按钮收起侧栏,将指针移到窗口左缘、顶部窗口控件下方,唤出图标轨。
  2. 在图标上停留约 120ms 打开浮层;移出后约 200ms 关闭浮层。在轨内切换图标只切换浮层。
  3. 点击条目完成导航,图标轨随导航收起;需要原生搜索、设置或工作区管理时,展开宿主侧栏。
入口 可执行的操作
工作区 按「置顶项目 / 项目」查看工作区,行内只显示名称;点击名称切换工作区,点击图钉置顶或取消置顶
最近会话 在工作区浮层底部独立滚动,按更新时间倒序显示,排除归档、空白与子代理会话;点击打开已有会话,显示相对时间及宿主提供的会话状态标识
定时任务 查看未结束、未暂停的任务;点击条目或「打开面板」进入任务面板
我的插件 查看自己安装并启用的插件组合包,过滤宿主内置包;点击进入插件管理面板
更多 查看宿主其他面板入口,或展开原生侧栏
账号与设置 显示宿主账号头像,以及可用的余额、赠金、「查询用量」「充值」链接;未登录时显示提示;并给出「展开侧栏后点左下角设置」的路径说明;登录、退出和付款由宿主或目标网页处理

键盘操作:用 Tab 聚焦图标,轨会随焦点出现。聚焦顶部功能图标后,按 ↓ 或 → 进入对应浮层,再用 Tab 遍历列表;在浮层内按 Escape 关闭并返回触发按钮。Enter 激活聚焦按钮,与点击语义相同;在图标上激活会直接导航,不等同于进入浮层列表。

设置与本地数据

「最近会话条数」默认 5,可设置为 1–20。工作区浮层底部提供加减按钮,插件详情页也提供同一设置。

工作区浮层高度固定(约视口 70%),上方是项目区、下方是最近会话区,两区大小基本一致且各有固定标题行;调条数只改变最近会话是否需要滚动,不改浮层高度。

插件详情页的最近会话条数设置,示例值为 9,可用加减按钮调整

偏好保存在当前客户端的 localStorage['dsh.sidebar-rail.v1']:

字段 用途
pinnedWorkspaceIds 已置顶工作区的 ID,最近置顶的排在前面
recentCount 最近会话显示条数,规范化为 1–20 的整数,无法解析时使用默认值

折叠状态由宿主持有,插件只读;账号与余额通过宿主服务读取,不写入这份偏好。清除客户端存储会丢失这些本地设置。两个设置入口共享该偏好,跨入口即时同步的真机验收情况见验证记录。

常见问题与限制

现象 检查或处理
安装后看不到图标轨 确认使用 macOS Desktop、插件已启用、侧栏已折叠、视口宽度 ≥ 768px;轨默认隐藏,需要将指针移到左缘热区
看不到最近的某个会话 检查条数设置;归档、空白和子代理会话不会进入列表
任务或插件加载失败 服务缺失、结构化失败或请求超过 5s 会进入失败态;用「打开面板」查看宿主页面,或关闭后重开浮层重试
账号没有头像或余额 无头像时使用占位图标;余额不可用时显示提示。账号数据在组件挂载时读取,不保证实时刷新,完整信息以宿主账号页为准
图标轨展开时覆盖页面左侧 它是浮在正文上的临时层,不占宿主栅格宽度;默认隐藏用于保留会话页「对话」标签的入口,可移开指针让轨收起
出现 Sidebar rail unavailable 或启动导入错误 保留界面错误与宿主诊断日志,通过原生侧栏进入插件管理停用,并在本仓库反馈宿主版本、插件版本和复现步骤;不要附凭据或会话正文

插件不接管展开态侧栏,不修改宿主列宽。顶部 48px 留给 macOS 窗口控件;支持减少动态效果的系统偏好。浅色主题、其他平台、真实 remote 故障、插件详情页设置交互和有余额账号的主余额行,以验证记录中的实际结果与未验证项为准。

开发与贡献

npm test               # 纯逻辑与客户端工厂注册测试
npm run check          # 仓库规则、两个入口的语法检查与测试
npm run hooks:install  # 可选:启用本仓库的提交钩子

客户端是手写静态模块,没有依赖安装和构建步骤。测试从 client.js 的 #region 区域提取纯函数,注册测试检查工厂 ID 与完整作用域包名一致;这些检查不能替代 Desktop 真实界面验收。

PR 标题遵循 Conventional Commits,摘要、说明与验证结果使用简体中文,代码标识符和原始诊断保留英文。按 PR 模板填写问题、改动、验证与未验证项;中英文 README 的行为描述同步维护。UI、加载或注册变更需在 docs/verify.md 记录真实环境与操作结果。详细约束见 AGENTS.md 和 CODING_STANDARDS.md。

发布按 ADR-0003:更新版本并推送后,创建 v<version> 的 GitHub Release,由 publish.yml 校验并使用 npm OIDC 信任发布;npm 端需配置允许直接发布的 Trusted Publisher。

详细文档

文档 内容
产品需求 使用场景、交互规格与验收清单
设计说明 增量挂载、布局、数据来源、清理与本地存储
验证记录 各轮真实结果、历史缺陷与未验证项
0.2.0 审查报告 当时发现的问题与复现证据,修复进展见后续验证记录
术语表 轨、侧栏、浮层、当前会话等统一用词
架构决策 窄窗判定、零依赖与发布流程

许可证

MIT © 2026 SkylerFee,见 LICENSE。