kazari-qwp/dsh-tiered-plugin-menu

简体中文 | English

让每个工作区、每个会话都能独立开关 DSH 插件，并使用各自不同的配置。

比如，只在写代码的工作区启用某个插件，在其他工作区关闭；同一个插件，在会话 A 使用配置 A，在会话 B 使用配置 B。直接从侧栏的小插件按钮打开菜单，在「设置」中使用原插件的配置界面。

配置按 客户端 → 父工作区 → 子工作区 → 会话 逐级继承，支持任意深度的工作区树。没有单独设置时沿用上级，需要时在工作区或单个会话里覆盖。

按钮位置

• 客户端插件：图中「工作区」总标题右侧的插头图标，设置整个客户端的默认插件与配置。
• 工作区插件：鼠标悬停在工作区名称这一行，点击出现的插头图标。
• 会话插件：鼠标悬停在会话名称这一行，点击出现的插头图标。

工作区和会话按钮在悬停时显示，上图未悬停的行里不会显示按钮。

安装

在 DSH 的 插件 → 添加插件 中输入 npm 包名：

dsh-tiered-plugin-menu

如果镜像源仍返回首次发布的占位包，请切换到 npm 官方源后重试。

也可以在命令行安装：

dsh plugin --profile desktop add dsh-tiered-plugin-menu

也可以从 Releases 下载构建好的 .tgz 安装。

Web 版换成自己的 profile 名称，通常是 web。未开启热重载时重启 DSH。不需要预先安装临时消息等其他插件。

升级至 0.6.3： 安装后重启 DSH。此版修复隔离插件在历史查询和会话面板中读不到投影数据的问题，包括 Context 洞察统计为空；同时包含 0.6.2 的 SDK 加载修复。已有会话日志不需要改写。原因与验证。

发行包包含宿主、浏览器构建产物、bundle patch 与许可，不需要安装时运行构建脚本。GitHub 源码需要先构建，直接安装请使用 Release 的 tarball。这是 DSH 官方打包教程支持的分发方式。

使用

• 侧栏「工作区」总标题旁的插件图标打开客户端配置；各工作区、会话行上的图标打开对应层级配置。
• 外层一个包显示一项，继承｜启用｜关闭按钮同时作用于包内全部组件。
• 点击包进入组件列表，才能逐个控制。组件开关不一致时，外层显示「部分启用」。
• 「设置」展开原插件的配置卡；没有可复用的配置卡时提供 JSON 编辑器。设置页与详情页都有配置卡时分别显示，中间用横线分隔。
• 本层关闭后不再执行继承来的实例；下级明确启用仍可覆盖上级关闭。
• 客户端级使用 DSH 原有入口和开关，下两级创建独立实例；可选的实验性隔离开关也会给客户端入口提供独立环境。离开页面不会卸载后台会话的实例。
• 关闭分级菜单时，释放它加载的下级实例、接口和界面入口，保留持久化配置；再次开启时恢复。只有客户端级原本启用的插件会恢复原生前端。
• 选中另一个会话时切换前端绑定；进入洞察、设置等页面保留当前绑定。
• 更新已安装插件时，等待 DSH 完成模块与 CSS 重载，再更新下级前端和已打开的配置卡，保留选中的会话及其配置。

例如客户端配置 A、工作区配置 B、其中一个会话配置 C：该会话用 C，同工作区其他继承的会话用 B，其他工作区继承 A。

按工作区树继承

菜单自己的设置页中，按工作区树继承 默认开启，修改后立即保存生效。各层插件仍在侧栏菜单中配置。

父级取最近的已注册上级目录，与 DSH 的「工作区树」分组一致；未注册的中间目录会跳过。每个插件沿树寻找最近的明确配置，继承时共用上级实例。关闭开关后，各工作区直接继承客户端，已有独立配置和下级默认设置仍保留。改变或删除上级时，依赖其服务的组件也会重新连接。

目录层级与 Agent 的父子关系分别处理：Superagent 的 Worker 目录位于 Router 目录下时，可以继承 Router 所在工作区的配置，即使 Worker 并不是 DSH 原生子 agent。

插件隔离（实验性）

菜单设置页的第二个开关是 插件隔离（实验性），默认关闭，升级后也不会自动开启。修改后立即保存，重启 DSH 生效。

给插件提供相对独立的环境，可能能修复一些兼容性问题，但也可能带来更多兼容性问题。

开启后从客户端级开始隔离，复用工作区／会话实例已有的模块加载、目录重定向、服务路由和释放逻辑。工具、技能、命令、提示词片段、统计投影使用带插件标识的稳定名称，让两个工具同名的插件也能在同一个会话中共存。有明确声明的服务依赖继续连接，其余服务保持独立。

客户端私有数据首次从 <配置文件名>.data/ 中的新目录开始，原插件目录保留；关闭隔离并重启后，客户端入口恢复使用原目录。固定端口、外部进程、同名 Agent 预设，以及依赖其他插件原始公开名称的代码不在此次覆盖范围内。实测范围与限制。

下级默认设置

每个菜单都有 本级｜下级 选项卡，默认打开本级。下级页面的总开关默认为 继承，切到 独立 后可以设置下级的插件开关，并复用原插件的配置卡。

在哪里设置「下级」	用于哪些新实例
客户端	新顶层工作区（关闭树继承时为所有新工作区），以及没有归属工作区的新会话
工作区	新普通会话；开启树继承时也用于新子工作区
会话	新子 agent，包括后续各级子 agent

独立下级设置中明确启用或关闭的插件，会在新建时复制到对应实例；仍选「继承」的插件继续沿用上级。编辑默认值不会启动测试实例，也不会改写已有工作区、会话或子 agent。恢复会话、重启和重新打开工作区都不会重新应用默认值。

子 agent 按实际父子关系查找最近的独立下级设置；自身没有另设时，继续沿用父会话的下级默认设置，因此可以传到孙 agent。它们各自获得独立的配置副本。普通会话分叉不会因为记录了父会话 ID 就被当成子 agent。

嵌套工作区同样查找最近的独立工作区下级设置；更改默认值不会覆盖已经创建的下级。

分层配置保存在 $DSH_HOME/plugins/tiered-plugin-menu.json，可通过菜单插件的 dataFile 更改。客户端配置通过 DSH 原生配置编辑器写入 profile。已有的整包配置会迁移到组件配置项。

依赖处理

修改开关前，菜单先计算完整的影响范围：

• 启用组件时，如果依赖尚未启用，列出依赖并提供自动启用／取消。
• 关闭被依赖的组件时，列出仍在使用它的组件并提供自动关闭／取消，也包含继承该依赖的下级会话。
• 依赖根本没安装或不可用时直接报错，开关保持原状，不会自动安装。
• 属于同一个包不代表互相依赖。外层开关按整包操作；详情页的单独开关根据 DSH 服务声明及已观察到的运行依赖处理。

这些确认规则作用于本菜单内的操作；DSH 自带插件页仍按其原生逻辑运行。

自动目录隔离

下级实例通过 Node 文件接口创建或确保目录存在时，菜单为它分配私有目录；同样的逻辑路径可以在不同实例中保存不同数据。继承上级实例时共用上级目录，独立启用时使用自己的目录。配置里的路径保持原样，不依赖 stateDir 等字段名，也不按插件名称适配。

相对路径和 .. 先在原来的逻辑路径中解析，再决定是否重定向；realpath 返回逻辑路径，因此继续拼接子路径或访问上级不会误入内部存储目录。普通文件接口与 SQLite 打开路径已经测试，Superagent 的两个下级实例使用相同 stateDir，也能分别持有锁和数据库。

数据保存在菜单配置文件旁的 <配置文件名>.data/ 中，按作用域和包区分；重开菜单或恢复会话继续使用原来的私有数据。首次使用隔离功能时创建新的私有数据目录，已有目录不会被搬动或删除。实测结果与覆盖范围。

兼容情况

当前版本 0.6.1，测试环境为 DSH 0.2.2-rc.1、Node.js 24。支持整包、组件开关和依赖确认，通过 DSH 的通用机制实现，不按具体插件名称写适配，不修改 DSH 或第三方插件源码。

0.6.1 修复开启实验性隔离后，点击旧会话导致侧栏条目消失的问题：私有辅助服务不再错误替换宿主服务。原会话文件未丢失，更新后重启 DSH 即可重新加载。原因与回归检查。

自动识别已安装的包。下两级中，未声明自兼容性的插件放在「未验证自兼容性」分组，启用前需要确认；不会因为启动成功就自动标记已验证。

实现上按作用域隔离插件提供的服务，并转发 DSH 的工具、提示词、命令、技能、统计投影和 HTTP 等共享注册。下级实例进入真实 Loader 入口，因此即使客户端级关闭，DSH 也能加载已安装包的原前端和 CSS。菜单不再内嵌第三方前端副本。

不同插件也能同时注册同名技能提供器和技能：先筛选当前会话可见的来源，再由 DSH 处理技能优先级；释放一个来源不会移除其他来源。技能隔离与 0.5.2 回归结果。

工具同名的插件可以分别在不同工作区、不同会话启用。下级工具使用 DSH 原生的逐 Agent 注册，参数、执行函数和结果渲染各自独立。可选的实验性开关进一步通过不同的公开名称处理同一会话内的工具重名。工具隔离与 0.5.3 结果、实验性隔离实测。

Agent 预设声明也按作用域隔离：不同工作区、会话可以使用同名预设的不同配置，不再重复注册报错。保留原预设 ID 和 DSH 的版本持有机制，子 agent 仍能使用父 agent 持有的预设版本。这一适配使用当前锁定 DSH 版本的声明表，并非跨版本稳定接口。Superagent 实测范围与上游问题。

0.2.1 的更新修复经过旧版菜单对照复现，并使用原版 dsh-context 0.82.2 → 0.83.0 前端包验证：洞察页渲染、CSS 替换、会话配置保留，以及模块短暂移除后重新加载均通过。更新回归说明。

隔离测试包含十个包。临时消息、dsh-context、通知在两个工作区、四个会话中通过 54 组功能开关组合。另外七个样本逐个验证了生命周期、独立配置及原前端模块可见性；Clock 的原配置组件另测了两个会话分别保存。具体结果、版本和复现方法。

第二批又加入 Better Sidebar、Agent Teams、另一款记忆插件、Force Compact、Bill、Auto Mode、Workbench 和 Simplify，共八个新样本。下级混装通过 110/110 项生命周期与配置检查，实测修复了菜单不兼容自定义统计校验器的问题。Workbench 的原生路由清理失败在不装菜单时也复现。第二批报告。

0.5.1 的第三批把八个新插件与原来的十八个混装。排除不装菜单也会发生的记忆工具重名冲突后，25 个包通过 341/341 项下级生命周期与配置检查。本轮发现并补齐了技能注册隔离：打包技能和运行时技能会随当前工作区、会话选择实例，并随实例释放。第三批结果与原生对照。

@fooxe/dsh-memory 在不装菜单时也存在原生 HTTP 路由清理问题。本次测试中，从原生实例未启用的干净进程启动，下级用例可通过；菜单不会清理它先前留下的原生注册。

这里隔离配置、生命周期及上述文件访问，不是安全沙箱。未进入私有目录的全局文件、写死的 TCP 端口、原生扩展和外部进程的文件访问不在这层隔离范围。没有穷尽测试每个第三方工具、UI 操作和远程接口；绕过已测试 DSH 接口的自定义前端仍可能需要进一步处理。

自兼容性声明

自兼容性指同一插件的多个独立实例能够同时运行，各自使用独立的配置和运行状态。插件作者可以在 package.json 用布尔值声明：

{
  "dsh": {
    "tieredPluginMenu": {
      "selfCompatible": true
    }
  }
}

true 表示作者声明自兼容，统一适用于工作区、会话及子 agent；false 或未填写仍视为未验证，启用时需要确认。它不代表该插件与其他插件互相兼容。这是本菜单的约定，不是 DSH 官方认证。自家临时消息插件也遵循同样规则，菜单不会代替其他插件写入声明。

从 0.5.4 起，selfCompatible 替代 supportsChildInstances。声明过旧字段的插件需同步改名，菜单不再读取旧字段。

开发

npm ci --ignore-scripts
npm run check
npm pack

可以在独立 checkout 中构建。vendor/ 包含未经改动的 MIT 测试依赖，不需要访问私有仓库。check 执行类型检查、构建和 42 项测试，使用真实 DSH 服务/插件及 React/jsdom，不使用浏览器自动化或付费模型。覆盖下级默认设置、深层工作区树、实时切换继承、预设隔离与版本持有、会话卸载恢复、原生配置卡保存和重启保留。

大规模第三方测试在一次性断网虚拟机内运行，见 复现说明。这些步骤不向个人 DSH 实例安装测试样本。

主要文件：src/manager.ts 管理实例和继承；src/dependencies.ts 计算依赖计划；src/runtime-tree.ts 管理 Loader 入口；src/isolation.ts 隔离服务；src/scoped-services.ts 转发共享注册；src/client/ 实现菜单及原客户端绑定。

许可

MIT，允许商用、修改和分发，保留许可声明即可。打包的校验库及源码测试依赖保留原许可，见 THIRD_PARTY_NOTICES.txt。