dsh-sidebar-ratio

English | 中文

给 DSH（DeepSeek Harness） 网页版的两件事：

1. 侧边栏按窗口比例打开 —— 左栏默认 14%，右栏可选；拖原生把手或快捷键直接调，比例记在浏览器里。
2. 同一个父总会话组内共享右侧栏面板 —— 父代理开着的文件/预览面板，切到它的子代理、孙代理、同级子代理时自动带上同一个标签。

不修改 deepseek-harness 任何源码文件。 宽度靠浏览器运行时改内联样式；面板继承只用官方公开的客户端 API。

---

为什么需要它

侧边栏宽度是写死的像素值。 DSH 原生左栏宽度是固定像素、拖动区间只有 264~420px （columns.ts 的 SIDEBAR_MIN/SIDEBAR_MAX）， 所以"想比原生更窄"做不到；右侧栏首次打开固定为窗口的 45%。窗口越宽，固定像素占比越小。

右侧栏面板是按会话隔离的。 每个会话各有一份面板状态，新建即"收起、无标签"， 所以父代理打开的文件面板，一切到子代理会话就没了 —— 这是原生设计而非缺陷，但对 "父代理指挥、子代理执行"的用法很不顺手。

本插件针对这两点分别用两种手段解决。

---

功能

一、侧边栏按窗口比例

操作	效果
拖动原生把手	直接改那一列的比例（左、右都可以），不再被 264~420px 夹住
Alt + ← / →	左侧栏 −1% / +1%
Alt + Shift + ← / →	右侧栏 −1% / +1%
Alt + 0	总开关：关掉即完全回到 DSH 原生行为

• 比例存浏览器 localStorage（key dsh.sidebar-ratio.v1），刷新后保持，不落任何磁盘文件。
• 左栏下限默认 200px、上限 45%；右栏下限默认 300px、上限 70% —— 像素与比例双重夹取，保证中央会话区不被挤没。
• 拖动是接管原生把手实现的，手感与原生一致，而且能拖到 264px 以下。

二、父总会话组内共享右侧栏面板

分组规则：沿会话谱系上溯到顶层，同一个父总会话（顶层会话本身 + 它下面所有层级的子代理）算一组，组内共用一个面板基准。

• 父 → 直接子、父 → 孙、同级子代理之间，行为一致；不同父总会话之间互不影响。
• 只对当前收起的会话生效 —— 目标会话自己已经开着面板时，插件一律不打扰。
• 组基准由谁定（inheritFromParent，默认 false）：
  • false：组内统一。谁开面板谁成为该组基准，父会话开面板自然成为基准。
  • true：严格依据父。只有父总会话能写基准，子代理只读。
• "关掉"只在观测到同一个会话从展开变收起时才认定，所以不会把"新会话本来就没开过"误判成用户关闭。

---

安装

从 GitHub 安装（推荐）

dsh plugin --profile web add github:masknull/dsh-sidebar-ratio

想固定版本（避免跟随主分支变动）：

dsh plugin --profile web add github:masknull/dsh-sidebar-ratio#v0.2.0

CLI 会把包名追加进 profile 的 dsh.profile.bundles，并在启动时应用本包自带的 cordis.patch.yml。 命令行的 git / 路径 / tarball 规格会由 pnpm 先落成真实依赖名，再按真实包名登记到 bundles （apps/cli/src/plugin.ts:59-91），所以上面这两种写法都会正确登记为 dsh-sidebar-ratio。

从本地目录安装（开发用）

dsh plugin --profile web add <绝对路径，例如 E:\AI\dsh-sidebar-ratio>

相对路径也可以 —— CLI 会把它锚定到你当前所在的目录（apps/cli/src/plugin.ts:104-112）， 所以在本仓库根目录直接执行下面这行同样有效：

dsh plugin --profile web add .

装完必须重启一次

新增 bundle 层只在启动时组合，所以：

1. 重启 dsh web
2. 浏览器 F5

之后改代码，什么时候需要重启

改了什么	生效方式
lib/dom.js（宽度逻辑）	只需 F5（宿主半边每次渲染 index.html 都重新读这个文件）
lib/client.js（面板继承逻辑）	需要重启 dsh web（客户端 bundle 的装载图在启动时组合）
lib/index.js、cordis.patch.yml	需要重启（apply 只在启动时执行一次）

本包是纯 JavaScript，没有任何构建步骤：从 GitHub 装下来即可运行，不需要 pnpm build。

---

配置

在 cordis.patch.yml 的 config 里改（改完需要重启）：

键	默认	说明
left	0.14	左侧栏占比；null = 不接管左栏
right	null	右侧栏占比；null = 不接管右栏
minLeft	200	左栏像素下限（原生是 264）
minRight	300	右栏像素下限（原生 RIGHTBAR_MIN 是 300）
enabled	true	宽度接管总开关的默认值
inherit	true	是否启用「父总会话组内共享右侧栏」
inheritAll	false	true = 忽略分组，任意会话切换都继承
inheritFromParent	false	组基准规则，见「功能二」

控制台 API

// 宽度
dshSidebarRatio.get()          // 当前状态；leftBlocked / rightBlocked 会说明"设了但当前不生效"的原因
dshSidebarRatio.set(0.12)      // 左栏 12%（写 12 也表示 12%）
dshSidebarRatio.right(0.26)    // 右栏 26%
dshSidebarRatio.enabled(false) // 临时交还原生行为
dshSidebarRatio.native()       // 两侧都交还原生
dshSidebarRatio.reset()        // 清掉 localStorage 记录，回到配置默认值

// 排查
dshSidebarRatio.debug(true)    // 打开实时日志
dshSidebarRatio.trace()        // 最近 40 条内部事件（谁触发、改成了什么）
dshSidebarRatio.probe()        // 立刻按当前 DOM 重解一次，返回前后签名

// 面板继承
dshSidebarInherit.get()        // 各父总会话组的当前基准、当前会话属于哪一组
dshSidebarInherit.enabled(false)
dshSidebarInherit.all(true)    // 忽略分组
dshSidebarInherit.rootOf(id)   // 某个会话属于哪个父总会话组
dshSidebarInherit.verbose(true)

---

工作原理

宽度：接管 DSH 自己的内联样式，但和 React 讲清楚"谁写的"

插件改的是 React 托管的内联样式（frame 的 grid-template-columns、左栏内容的 width、 两个把手的 left、右侧面板的 width）。难点不在"改"，而在和 React 抢方向盘时不打架，所以有三条规则：

1. 谁改的必须分得清：每次写入前先"认账" —— DOM 现值不等于我们上次写过的值，说明是 React 刚写的， 记为"原生值"。还原时写回这个最新原生值，而不是第一次接管时的过期快照。
2. 重写必须赶在绘制前：MutationObserver 回调本身就是微任务、在绘制之前执行，所以命中时同步重写， 不排 requestAnimationFrame —— 排 rAF 会慢整整一帧，那一帧就是肉眼看到的"官方宽度闪一下"。
3. 观察白名单只是快路径，不是唯一路径：回调只认 frame、两个列容器和插件接管的那几个节点 （中央会话列被刻意排除 —— 流式输出会产生海量 style/class 变更）。白名单认不出、但落在列容器内部的 结构变化（React 换掉中间 wrapper、重建面板）走下一帧核对签名；再兜一层每 400ms 的签名比对 （只读 5 个内联样式串，纯 CSSOM 读、不触发排版），外加 ResizeObserver 覆盖"框体尺寸变了但没 window resize"。 最坏收敛时间有硬上限，不依赖"哪条 mutation 会被漏掉"的假设。

面板继承：只记"意图"，再借官方 API 重放

官方公开面里唯一能跨会话写的入口是 ctx.sidebarRight.openTabIn(sessionId, kind, options) / openResourceIn(sessionId, address, options)，且 openContent 会强制 setExpanded(true) —— 即"打开标签"必然把该会话的右列展开。反过来，没有任何公开 API 能读另一个会话的标签集 （active()/mounted() 只读上屏会话），所以插件自己记住"当前上屏会话开着哪个标签" （kind + contentId）作为组基准，切到组内收起状态的会话时重放。

值得一提的是：DSH v0.1.6-alpha.1 新增的侧边栏终端，官方自己就是用 ctx.sidebarRight.openTabIn(sessionId, 'terminal', { params: … }) 做跨会话重放的 （ui-sidebar-terminal）—— 本插件用的正是同一条官方路径。

---

已知边界

这些不是"没做"，而是官方公开面里没有对应能力，或属于原生行为：

边界	说明
只能继承当前激活的那个标签	active() 只给当前激活标签；没有公开 API 能列出别的会话的标签集
继承不了并存的多个标签、分栏、浮窗、mode	同上；可读的 TabRecord 只有 {id, kind, contentId, title}
继承不了标签内的滚动位置等 params	导航 params 不在公开读取面内。具体到侧边栏终端：官方恢复流程自带 params: { terminalId } 调 openTabIn，插件读不到那串参数，因此子会话会新开一个终端，而不是接续父会话的那一个
无法"只展开、不开标签"	官方没有 setExpandedIn(sessionId, bool)
左栏比例在侧栏收起或帧宽 <1024px 时不生效	收起态是 56px 导轨，不该被拉宽（原生 SIDEBAR_AUTO_COLLAPSE）
右栏比例在右栏没有独立轨道时不生效	帧宽 <768px 会派生自动全屏（原生行为）；该状态下也没有把手可拖
接管期间的宽度范围与原生不同	左栏 200px 下限 / 45% 上限是本插件自造口径；Alt+0 关掉后回到原生 264~420

读数气泡与 dshSidebarRatio.get() 的 leftBlocked / rightBlocked 会明确标注"设了但当前不生效"及其原因， 不会假装生效。

排查

现象	先看什么
宽度没按比例	dshSidebarRatio.get() 看 leftBlocked / rightBlocked；再 debug(true) 看实时日志
切会话时闪一下宽度	dshSidebarRatio.trace()：正常应看到「观察器命中」（同步、肉眼不可见）；若频繁出现「签名不一致」，trace 里会写明漏掉的 target 形态
不确定页面加载的是哪个版本	typeof dshSidebarRatio.trace —— 是函数即新版
面板继承没生效	dshSidebarInherit.get() 看 groups 与 currentRoot；verbose(true) 看捕获/重放日志

---

兼容性与维护锚点

开发期已在 cordis 4.0.2、react-dom 18.3.1 的 DSH 源码树上逐条核对，并对照 dsh-v0.1.6-alpha.1 做过逐字节核验（用 git blob SHA 对撞，而非肉眼比对）：本插件依赖的 13 个锚点文件中 9 个与该版本逐字节相同，另 4 个的差异全部是 tag 侧新增能力，本插件依赖的方法、DOM 标记与属性一律未动， 无破坏性改动。

下表的路径均相对于 deepseek-harness 仓库根目录（链接指向核验所用的 tag）；DSH 升级后若出现异常，优先核对这几处：

依赖的东西	位置
三列网格内联样式、frame 上的 data-*、把手 [data-side]	ui-layout/…/AppFrame.tsx
边界常量 SIDEBAR_MIN/MAX、RIGHTBAR_MIN、CENTER_MIN、RIGHTBAR_MAX_RATIO	ui-layout/…/columns.ts
轨道过渡、.handle、两列 overflow	ui-layout/…/AppFrame.module.css
左栏内容自带内联 width	ui-sidebar/…/SidebarRoot.tsx
右侧面板 data-sidebar-right-panel + 内联 width	ui-sidebar-right/…/shell/SidebarRight.tsx
跨会话打开标签的公开入口 openTabIn / openResourceIn	ui-sidebar-right/…/service.ts
可读的 TabRecord 结构	ui-dockkit/…/contract/types.ts
会话谱系字段 SessionSummary.parentId、会话切换信号	session-controller/…/sessions/service.ts
结构化注入行协议（global / script；script 正文不得含结束标签字面量）	webserver/src/injections.ts
客户端 bundle 发现契约（exports["./client"]、dsh.client.platform）	client/modules/src/index.ts

开发期的逻辑验证方式是零依赖的桩 DOM 回归（该脚手架不随仓库提供，此处仅说明验证强度）：伪造 AppFrame 结构 （含中间 wrapper、面板替换等真实层级）+ 可控计时器 + 手动喂 mutation record，覆盖接管、微任务内同步纠正、 还原最新原生值、单侧还原、阻塞态读数、拖拽拦截等场景；另用变异体反向证明断言不是空转 （把实现改坏必须能被测出来）。

卸载

dsh plugin --profile web remove dsh-sidebar-ratio

然后重启 dsh web + F5。浏览器侧残留只有 localStorage 的 key dsh.sidebar-ratio.v1， 可用 dshSidebarRatio.reset() 清除。

许可

MIT