插件布局整理
English: README.en.md
一个 DSH 客户端插件：帮你把插件按钮拖到想要的位置、在官方与第三方之间画一条分隔线、把不常用的收起。它只改变按钮的显示位置——不卸载、不启停任何插件。DSH 自带「更多」菜单里的按钮同样可以整理。
适配 DSH >=0.1.7-rc.2：0.1.7-rc.2 起的每个 0.1.x、0.2.x 构建（含全部 rc 与 0.2.1 正式版）都用同一份代码，不需要为版本切换装不同包。
与「更多」菜单相关的能力（「进更多」「出更多」、「分开收纳」、「更多菜单里的分隔线」）只在**宿主自带「更多」**的版本上出现——那是 0.2.1-rc.3 起才有的东西。更早的宿主上这些入口直接不画，其余功能照常。
它能做什么
DSH 把插件按钮投放到五处槽位，外加右侧栏「开始」页的卡片，本插件对这六处一视同仁；侧边栏顶部、对话页右上角与右侧栏「开始」页各自的**「更多」菜单**里的按钮也能整理（见第 3 节）：
| 位置 | 槽位 | 说明 |
|---|
| 左侧边栏·顶部 | sidebar.panellist | 侧边栏「插件 / 定时任务 / SSH / MCP 连接器」那一列 |
| 左侧边栏·底部 | sidebar.footer.action | 侧边栏底部、设置入口上方的图标按钮 |
| 对话页·顶部标签 | conversation.view | 对话页顶部「对话 / 轨迹 / 上下文 / 编队」那一排 |
| 对话页·输入框下方 | conversation.composer.dock | 输入框下方那一行 |
| 右侧边栏·开始页 | 无槽位 | 右侧栏「开始」页的「工作区文件 / 上下文 / 新建终端 / 浏览器 / 会话数据诊断 / 更多工具」卡片 |
| 设置窗口·左侧导航 | settings.section | 设置弹窗左侧的导航行 |
1. 拖拽排序
- 按住任意可拖按钮拖动，松手即保存；拖动中按钮跟随指针，经过的行让开缺口标示落点，松手不会触发按钮本身。
- 第三方按钮始终可拖；官方按钮需先打开「允许拖动官方按钮」（出厂即开，可自行关掉）。
- 默认遵循分组主序：官方整体在前、第三方整体在后，组内顺序完全由拖拽决定。
- 「允许官方和第三方混合排序」出厂即开（挂在「允许拖动官方按钮」下的子开关）：开启后保存的顺序原样生效，第三方按钮可以落到两条官方按钮之间。
- 本插件自己的设置入口（设置导航里的「插件布局整理」那一行）同样可拖、可收纳。
- 三颗「更多」入口（左侧边栏的「更多」、对话页的三个点、右侧边栏的「更多工具」）不参与拖动、永远排在各自列表最后，也不能改判官方 / 第三方：它们只是打开菜单的开关，位置固定；右键菜单里只有「收起」可用，其余几项灰着。对话页那三个点还画在标签条外面，本来就挪不动。
- 把一行直接拖到「更多」入口上松手，就等于把它收进「更多」：拖动过程中那颗入口会亮起描边当落点提示。反过来，在「更多」菜单里按住一行拖出菜单范围（留 12px 余量）松手，就是把它移出「更多」放回主列表；拖出去时这一行会压暗并画上虚线。
- 把一行拖到「已收起的按钮」那颗悬浮按钮上松手，就是收起它：界面上的行、设置页卡片里的行、「更多」菜单里的行都可以；拖动时那颗悬浮按钮会亮起虚线外圈当落点提示。同一次拖动既碰到悬浮框又拖出菜单时，按收起算。
- 设置页卡片里的行反过来拖：拖出本插件设置页整块页面（留 12px 余量）松手就是恢复它——收起与「进更多」一起撤掉、回到原位置，拖出去时这一行压暗并画上虚线。不必正好落到设置弹窗的左侧导航上，甩到页面外面任何地方都算；指针压在悬浮按钮上时按收起算。
2. 官方 / 第三方分隔线
- 出厂即开；关掉「显示官方 / 第三方分隔线」总开关即全不画。可在四个位置分别开关：左侧边栏·顶部、对话页·顶部标签、右侧边栏·开始页、设置窗口·左侧导航；左侧边栏底部与输入框下方永远不画——贴着输入框的两处两类按钮本来就交错，插入一条线会被读成凭空多出来的一组。
- 线画在最后一条官方按钮与第一条第三方按钮之间的空隙正中，横排竖排自动适配方向。
- 弹窗盖住时自动隐藏；设置导航里的线画在弹窗内部（
z-index 1010），其余在 body 级（z-index 90），不会压过官方弹窗。
- 行被卸载、被祖先隐藏或裁剪，或混合排序下两类按钮真正交错时（一条直线描述不了多个交界），整条线自动收起。三颗「更多」入口不参与交界判断——它们钉在列表末尾，不代表任何一组。
- 纯视觉提示，不影响排序规则。
3. 已收起的按钮（收起）
- 在任意可收纳按钮上点右键，弹出与 DSH 官方菜单同样式的「上移 / 下移 / 官方·第三方 / 进更多（或出更多）/ 收起」菜单（同款半透明底、细描边、圆角与图标列）；也可以在设置页行尾点「收起」。
- 菜单里那一项直接写目标分类：当前归「第三方」的行显示「官方」，当前归「官方」的行显示「第三方」，点一下即改判。改判只改本插件的本地记录（与设置页行内按钮同义），插件本身不受影响。
- 被收纳的按钮从界面消失，但插件仍在正常运行——收纳只是视觉隐藏，随时可恢复。
- 两级收纳：**「进更多」把按钮从主列表挪进 DSH 自己的「更多」菜单（仍然点得开），「收起」**才是挪进「已收起的按钮」。右键菜单与设置页每一行都同时有这两个入口，随时能点「出更多」或「恢复」拿回原处。两类行例外：三颗「更多」入口（左侧边栏的「更多」、对话页的三个点、右侧边栏的「更多工具」）与设置窗口左侧导航的那些行。前者就是打开那扇菜单的开关，收进去等于把入口关掉却找不回来；后者的设置弹窗里根本没有「更多」，收走了在设置页里就没有别的入口。这些行的「进更多」在设置页与「已收起的按钮」面板里照样画出来，只是禁用。「更多」入口自己那一行，右键菜单里只留「收起」可用，其余几项灰着。
- 三处「更多」出厂即分开（各自只列自己的；想合并成一份清单就关掉设置页的「分开收纳」）：左侧边栏顶部与底部的按钮只进左侧边栏的「更多」、对话页顶部标签与输入框下方的行只进对话页的「更多」、右侧边栏开始页的卡片只进右侧边栏的「更多工具」；关闭时三处共用一份清单，收进哪一处都在三处出现。设置页左侧导航不收进任何一处。
- 「更多」菜单里的行同样可以拖动排序、右键上移 / 下移 / 转官方·转第三方 / 出更多 / 收起；按住一行拖出菜单范围松手即移出「更多」，拖到悬浮按钮上松手即收起；打开「在「更多」菜单里画分隔线」后，官方条目排在前面、第三方按钮排在后面，中间画一条线（它和页面上的那条同受「显示官方 / 第三方分隔线」总开关管，各自还有自己的分项）。
- 打开方式：快捷键（桌面端默认
Ctrl/Cmd + Shift + O；网页端 Windows / macOS 为 Ctrl/Cmd + Shift + Alt + O，Linux 为 Ctrl/Cmd + Shift + ,；均可在设置里重绑）；屏幕右缘、顶栏正下方的悬浮启动器（可拖到任意位置，松手吸附到较近的左 / 右边缘并保留纵向位置）；设置页「已收起的按钮」区域。
- 面板固定尺寸（宽
min(520px, 92vw)、高 min(720px, 84vh)）：标题、搜索、排序与「全部恢复」钉在顶部，只有列表区滚动，条目再多也不会把面板撑高。
- 顶部同样有搜索框：按名称、id 或所属位置实时过滤，输入框左侧放大镜、右侧 × 图标清空；无匹配时列表显示提示文案。
- 条目可直接点击：点「插件市场」自动打开设置并跳到该页；点侧边栏按钮切换面板；点底部图标或对话标签触发原按钮；点右侧边栏开始页的卡片打开那张页面（右栏收着也会顺带展开，不必先手动翻回「开始」页）。界面上本来就点不动的行（例如插件塞进输入框停靠行的只读统计条）在这里也是灰的、点不动——它本来就没有对应页面，点击不会导航、也不会顺手把面板关掉。按住一行拖到面板外面松手，就是恢复它（留 12px 余量；拖动时这一行原地压暗、不跟着指针走，指针真的离开面板范围才补上虚线），行内那两颗动作按钮照旧点得动。
- 三种排序：按页面 / 按分类 / 按名称，另有独立的「全部恢复」（两步确认）；单行的「恢复」一点即恢复。
- 每行左侧是这个按钮原本的图标——原按钮没画图标时用它所属插件的图标，两样都没有才留空位；后面依次是名称、插件 id 与恢复按钮。名称过长时打点省略，恢复按钮不换行；名称右侧的灰色标签是这个插件的 id，不是页面名。
4. 设置页
设置 → 插件布局整理（本插件在插件管理器的详情面板里也有同一设置页）：
- 顶部分页导航：药丸式分段控件，配色照抄 DSH 自家的
SegmentedControl——整条是浅灰圆角槽（--dsw-alias-interactive-bg-hover），选中项是浮起的药丸（--dsw-alias-bg-layer-1 加 --dsw-elevation-soft 阴影、加粗近黑字），未选中项只有灰字、悬停才转近黑。两组——位置管理（已收起的按钮入口与六张位置卡片）与通用设置（各项开关与快捷键），默认停在位置管理。点击只渲染当前那一组，滚动位置与搜索词在切换时保留；搜索期间已收起的按钮入口卡片让位。
- 通用：「允许拖动官方按钮」总开关（子开关：混合排序）、「显示官方 / 第三方分隔线」总开关（子开关：四个位置与「更多」菜单）、「分开收纳」、「显示悬浮框启动器」、「重置所有配置」（两步确认：首点武装，三秒内再点执行，超时复原；清空顺序、分类、收纳与全部开关）。两项收纳相关的开关里，「分开收纳」是主口径，排在「显示悬浮框启动器」前面。总开关关闭时子行灰显但仍可点击——点灰子行等于「我要用这一路」，会点亮该路并连带顶起总开关。配置还是出厂值时这个按钮是灰的：按下去什么也不会变，留着能点的样子只会让人以为它坏了。
- 标题行：大标题右侧显示当前版本号（如
v1.2.3）；再往右是 导出配置（整个持久化状态写成 JSON 文件）、导入配置（版本不符的整体拒绝，不会半套用）、GitHub 仓库、问题反馈（打开本仓库的 Issues 页面）。放得下时四个按钮与标题同行靠右；窗口太窄放不下时整组掉到第二行、从左边开始与标题左边缘齐，不会甩到右侧留一片空档。
- 快捷键：录制、恢复默认；冲突或不可用的组合有文字警告。
- 已收起的按钮：显示当前数量，一键打开。面板里按位置或按种类分组时，每个分组标题右侧有一个「恢复本组默认」（把这一组覆盖到的每一处位置的顺序与收纳一起清掉；按名称排序没有分组标题，也就没有这个按钮），分组里无事可做时按钮灰置。它是次级动作，字号比标题小、也不跟标题一样加粗。点分组标题即可折叠 / 展开该组（小三角在标题行最右端、恢复按钮之后，跟着转，状态跨刷新记住）；按名称排序没有标题，也就没有折叠；搜索期间照旧可以折叠——收起的组不会被搜索词强行拉开。
- 搜索：位置管理页顶部有搜索框，按按钮名称或 id 实时过滤；卡片与行都不匹配时整张卡片让位，已收起的按钮入口卡片在搜索期间也一并让位，清空（输入框右侧的 ×）即恢复全部。已收起的按钮面板里也有一模一样的搜索行。
- 六张位置卡片：该位置的每个按钮，支持拖拽、上移 / 下移、官方 / 第三方改判、收起与恢复；每张卡片标题右侧有自己的「恢复本组默认顺序」（两步确认），同样是次级动作、不加粗。点卡片标题即可折叠 / 展开这一整类（标题行最右端、恢复按钮之后的三角跟着转，状态跨刷新记住；搜索期间照旧可以折叠——收起的卡片不会被搜索词强行拉开）。每行的名称区（圆点 + 名称 + id）可以点，点了先跳到这个按钮所在的位置、再关掉设置弹窗；界面上本来就点不动的行，名称区灰着不可点——可点却毫无反应比灰着更像坏掉。右侧边栏那张卡片是例外：它走宿主自己的打开通道，右栏收着、或者正显示别的页面时照样可点，点下去右栏会展开并摆出这张卡的页面；卡片本身也按宿主注册表列出，右栏收着时照样能整理，不必先翻回「开始」页。卡片既没有保存顺序、也没有收纳行时，「恢复本组默认顺序」是灰的——无事可做时不该留着能点的样子。
- 宿主服务缺失时进入降级模式（例如没有快捷键服务时只剩启动器），原因显示在设置页顶部。
安装
本包是标准 DSH bundle，用内置插件管理器安装：
dsh plugin add dsh-plugin-layout-organizer
或让 agent 调用 plugin_manager（action=install_bundle，target 指向本目录）。
装好后刷新页面。
开发
需要 Node.js >=24（package.json 的 engines.node；构建依赖 Node 自带的 module.stripTypeScriptTypes，CI 与发版工作流也都用 Node 24）。
node build.mjs # 按 BUILD_ORDER 把 src/ 拼成 lib/client.js，并内联 assets/icons/ 图标
node --check lib/client.js
node test/smoke.mjs # 无头冒烟测试（伪造 DOM / React / ctx）
node test/navigate.mjs # 「设置」两步路由的行为测试
node test/accept.mjs # 源码形态验收探针
（等价于 npm run build / npm run check / npm test。）
持续集成
开 PR 或推送 master 会触发 .github/workflows/ci.yml，跑一遍与发版相同的闸门：构建 → 语法检查 → 校验已提交的 lib/client.js 与源码一致 → 三个测试，最后再加一次类型检查（npx -y --package typescript@6.0.3 tsc -p tsconfig.json，版本与 tools/ts-check.mjs 用的编辑器内置 TS 一致，按需下载，不写进 package.json、不产生锁文件）；工作流只读，不发布也不建 Release。screenshots/ 由插件市场从仓库直接读取，改动要一并提交。
发版
推送 v* tag 即可，.github/workflows/publish.yml 会自动构建、校验构建产物与源码一致、跑测试、发布到 npm（Trusted Publishing / OIDC，无需 token），并用 tools/release-notes.mjs 从 CHANGELOG.md 抽出对应段落创建同名 GitHub Release：
git tag vX.Y.Z && git push origin vX.Y.Z
工作流是幂等的：npm 上已有该版本就跳过发布，Release 已存在就改写说明，可安全重跑。发版前记得三件事——package.json 升号、CHANGELOG.md 新增版本段与底部链接定义行、tag 名与版本号一致（CI 会校验，不一致直接失败）。
源码组织
客户端包只能 require 启动图里已注册的种子词或包，不能按相对路径在运行时分块加载，因此本项目采用模块化源码 + 构建期拼接：
src/ 按职责拆成 types/、shared/、core/、drag/、ui/；build.mjs 持有显式 BUILD_ORDER 清单并按序拼接；- 清单本身就是加载顺序声明——后置模块依赖前置模块的顶层
var / function，所以显式列出而不是目录遍历推断（types/globals.d.ts 仅供类型检查，不参与拼接）；
- TypeScript 语法由 Node 自带的
module.stripTypeScriptTypes（transform 模式）擦除——没有打包器，也没有要装的依赖；
- 产物是单个
lib/client.js，包裹在 window.__ModuleLoader__.load({ id, factory }) 里；
assets/icons/ 存放从 iconfont 下载的 15 个图标 SVG，是构建输入：源码不手写 path，只写 @@svg:file.svg@@ 占位符（shared/icons.ts 七个菜单图标 + 四个标题行动作图标 + 两个搜索行图标 + 一个「出更多」动作图标；core/dom-project.ts 设置行自身图标为 @@svg:layout.svg@16@@）。build.mjs 归一化每个素材——viewBox 取自源文件、宽高默认 14（占位符可指定，标题行四个动作图标为 16、搜索行两个为 13 与 12）、写死的颜色改写为 currentColor、补 aria-hidden / focusable——再把 <svg> 内联进 lib/client.js。动作素材的画布留白差别较大，styles.ts 按素材名（data-ico）做光学校正，让一排按钮的图标看起来等高。layout.svg 同时是 package.json "icon" 指向的包图标；该目录在 files 白名单里，装包后仍可重新构建。
| 模块 | 职责 |
|---|
types/state.ts | DSH 服务（槽位 / locale / 布局 / 快捷键）与本插件状态的 TypeScript 形状，构建期擦除 |
types/globals.d.ts | 构建前言注入的全局声明（React、h、各 hook），仅供类型检查，不参与拼接 |
shared/constants.ts | 插件 id、存储键、六处位置表、官方 id 白名单、DOM 标记名、z-index 常量等 |
shared/icons.ts | 七个右键菜单图标 + 四个标题行动作图标 + 两个搜索行图标 + 一个「出更多」动作图标的 @@svg:…@@ 构建占位符，构建时从 assets/icons/ 归一化内联 |
shared/locale.ts | 中英文案字典 |
core/store.ts | 状态形状（v5）、持久化、纯查询与命令（顺序、分组、收起、进更多与两级收纳） |
core/dom-rows.ts | 各槽位的行发现、账本读取、行打标与配对、几何计算 |
core/dom-line.ts | body 级官方 / 第三方分隔线的创建、定位与隐藏 |
core/dom-menu.ts | 仿 DSH 官方样式的右键菜单及其窗口级事件委托（排序、官方 / 第三方改判、进更多 / 出更多与收起 / 恢复） |
core/dom-project.ts | 投影：写标记与 style.order、收纳隐藏、分隔线调度、设置行自身图标 |
core/dom-navigate.ts | 重新打开被收起的按钮，含「设置」两步路由 |
core/organizer.ts | 调度中枢：rAF 合帧、MutationObserver、槽位订阅 |
core/plugin-icons.ts | 插件图标查询：把插件 id 对到宿主插件清单里登记的图标地址，供行首图标兜底 |
drag/drag-frame.ts | 三个拖拽控制器共用的手势管线（一帧一次的重算节流、捕获阶段监听）与悬浮框落点判定 |
drag/drag-rows.ts | 界面行（DSH 各槽位按钮）的指针拖拽控制器 |
drag/drag-list.ts | 本插件设置页列表的指针拖拽控制器（拖出整块页面松手即恢复） |
drag/drag-stash.ts | 「已收起的按钮」面板的行：拖到面板外松手即恢复 |
ui/styles.ts | 样式注入与全部 CSS 规则 |
ui/kit.ts | React 基础控件（Icon / Switch / Field / Card / Chip / Btn / RowItem / ConfirmBtn） |
ui/search.ts | 搜索框与匹配判定（设置页与面板共用） |
ui/config-actions.ts | 配置导出 / 导入（版本校验）与仓库、Issues 地址 |
ui/scope-card.ts | 单张位置卡片：行列表、上下移、改判、收起、进更多与恢复本组 |
ui/shortcut-card.ts |
已知边界
- 排序与隐藏发生在 DOM 层，插件注册表不会被修改。 DSH 在
register() 时一次性按 priority → order 排序槽位，事后改 order 不会重排；本插件直接给真实 DOM 行写 style.order 与标记属性，因此依赖官方 UI 结构，DSH 大版本升级后可能需要适配。
- 没有权威的「官方 / 第三方」字段。 槽位条目记录的
registrant 不可靠（多个第三方包冒用官方标记），本插件内置官方 id 白名单，并允许在设置页手动改判任意行。
- 「收纳」不是卸载，而且分两级。 被收起的按钮只是隐藏，对应插件照常运行；「进更多」只是挪进 DSH 自己的「更多」菜单（仍可点开），「收起」才挪进「已收起的按钮」，两者都能一键拿回原处。
- 有台账的位置统一按「屏幕上真实存在的行」列条目。 台账里存在、但这一轮没能标记到元素的记录不会出现在设置页里，也不会被按位置错认成别的行——Trae / WorkBuddy 那种「注册在此、渲染别处」的记录正是这样被挡掉的。某个位置整条不在屏幕上时（对话页关着，标签条与停靠行都不渲染），设置页那张卡片退回「上一次投影记下的行」，因此照样能排顺序、收纳，不必把对话页切回来；它只记投影真正标记到过的行，所以同样不会把台账全列一遍，从没上过屏幕的位置仍是空的。右侧边栏·开始页另算：它整条都不进台账，设置页那张卡片按宿主注册表列出卡片（id 用 tab kind，「更多工具」用固定的
more），右栏收着、或正显示别的页面时也照常列，不必先把右栏翻回「开始」页；名字一律取宿主注册的标题，与悬浮框里一致。输入框停靠行里渲染成空的记录（供应商未登录时的统计读数）另有认领钩子兜底——官方药丸认 data-composer-stats（旧宿主）或 data-composer-stat="activity"／"usage"（0.2.1 起把一条拆成了两条），token-saver 认 .st-strip。官方读数（旧宿主的 stats、新宿主的 activity 与 usage）与 7% 用量百分比（context-meter）各自收起、互不牵连，用量百分比分类归官方。
- 这几条读数用功能名显示：宿主没给台账文案，插件补上「会话统计 / 用量统计 / 上下文用量」（
ROW_LABELS，跟着界面语言走），不是把 id 直译成中文。
- 已知问题（bug）：Trae 与 WorkBuddy 的额度读数登记在输入框停靠行槽位、实际却渲染在对话框里，不属于底部停靠行。判断依据是机制而不是名单：投影只认这一轮真正标记到元素的行，而按位置兜底也会跳过声明过
ROW_HOOKS 的记录——这两条记录在停靠行容器里认不到元素，于是既不进卡片、也不留给已收起的按钮一条永远恢复不出来的影子行；同理，以后再有「注册在这个槽位、渲染在别处」的插件也自动适用。对话框内插件的隐藏与收起尚未实现。
许可证
MIT
