dsh-model-organizer 0.3.1 → 0.3.3

package/DEVELOPING.md

@@ -0,0 +1,130 @@
+# 开发笔记
+
+面向改这个插件的人（包括未来的我）。用户文档在 [README.md](./README.md)。
+
+## ⚠️ 改代码前务必先读：踩过的坑
+
+0. **服务改名会让座位"静默消失"，必须注入新旧两个名字。**
+   DSH 0.1.7 把客户端设置镜像服务从 `settingsScope` 改名为 `configForms`（由 `@deepseek-ai/dsh-client-ui-settings` 提供，`describe()` 返回的还是同一个 mirror 对象）。
+   cordis 的 `ctx.inject([...])` **只要有一个服务永不出现，回调就永远不执行** —— 不报错、不打日志。所以 0.1.7 一升级，本插件的设置页浮窗就凭空消失了（输入框的模型菜单照常，因为它注入的 `slots/modelDirectories/sessions` 都没变）。
+   现在 `apply()` 里同时注入两个名字，用一次性标志保证只挂载一次：
+   ```js
+   ctx.inject(["slots", "configForms", "remote", "remote.settings"], (s) => mountOrderPanel(s, s.configForms.describe()));
+   ctx.inject(["slots", "settingsScope", "remote", "remote.settings"], (s) => mountOrderPanel(s, s.settingsScope.describe()));
+   ```
+   **推论**：升级 DSH 后如果某个座位不见了，第一件事是去新版本的 `dsh-client-ui-*` 包里 grep 自己注入的每个服务名。
+
+1. **`file:` 依赖是打包快照，`link:` 才是符号链接 —— 改仓库可能根本不生效。**
+   profile 里写 `"dsh-model-organizer": "file:../../../dsh-model-organizer"` 时，pnpm 把目录**打包复制**进自己的 store；只有 `pnpm add ./dir`（直接路径）或 `link:` 才是符号链接。
+   症状：改完仓库代码、强刷浏览器，界面毫无变化；查 `window.__dshModelOrganizerBuild` 会发现跑的还是旧构建号，而服务端 bundle 里明明是新代码 —— 因为 DSH 加载的是 `profiles/<p>/node_modules/dsh-model-organizer/lib/client.js` 那份**副本**。
+   排查：直接 grep 那份副本的 `BUILD` 常量，和仓库对比。
+   修法：`dsh plugin --profile web remove dsh-model-organizer && dsh plugin --profile web add link:./dsh-model-organizer`（换成符号链接后只改一处）。在此之前必须**两份同步改**。
+
+2. **0.1.7 的菜单色 token 是半透明的，浮层必须配 `backdrop-filter`。**
+   `--dsw-specific-menu` 现在解析成 `rgba(48,49,54,0.5)`，官方菜单靠 `backdrop-filter: var(--dsw-menu-backdrop-filter)` 配合。只取颜色不取模糊 → 面板是「透视」的，底下的官方卡片按钮直接透上来。
+
+3. **浮层要 `ReactDOM.createPortal` 到 `document.body`。**
+   `settings.models.footer` 座位在设置页很深的子树里，`position: fixed` 会被困在那个子树的堆叠上下文里，被别的插件的悬浮组件（鲸鱼、地球图标等）盖住 —— 提高 z-index 也没用。挂到 body 之后 z-index 才是全局的（本插件用 10000，官方菜单是 1100）。
+
+4. **profile bundle 必须声明 `dsh.bundle.patch`**（指向 `cordis.patch.yml`）。缺了它 dsh 启动即报
+   `profile bundle "..." declares no dsh.bundle in its package.json`。
+
+2. **顶层 `inject` 必须声明座位 standardProps 会读取的每一个服务**（本插件：`locale, slots, sessions, remote, remote.session, remote.settings`）。
+   少一个 → 渲染时抛 `cannot get property "remote.session" without inject` → **条目被静默弃权（abdicate）并回退到内置 UI**，界面无任何报错。
+   调用 `remote.settings.mutate` 还必须显式声明 **`remote.settings`**。
+
+3. **owner props 以组件 props 传入，不经过座位的 `inject` 工厂**：`settings.models.provider-card` 的 `inject` 不接收参数，必须读 `props.provider`。
+
+4. **`single` 座位优先级**：同优先级注册会**直接抛错**；运行时为非 chain 座位**自动分配**优先级（`--nextPriority` 递减），**后注册者胜出**。
+
+5. **drop 事件会在行与容器上各触发一次**（冒泡），需用 ref 加锁，否则重复写入。
+
+6. **边框必须用 longhand**（`borderWidth/borderStyle/borderColor`）。用 shorthand `border` 再叠加 `borderColor` 时，React 会把 shorthand 展开成 longhand；回退时移除 `borderColor`，`border-color` 就落回 **currentColor** —— 表现为「拖拽结束后高亮边框一直不消失」。
+
+7. **拖拽会把源行留在焦点上**。行加 `tabIndex:-1`、drop/dragend 时 `blur()`；并且**不要给行画 `:focus-visible` 背景**（官方 `option` 类自带一条，会变成「拖完还留一块灰底」）。
+
+8. **原生拖拽会让文字变成可拖对象**（浏览器弹「松开鼠标即可搜索」）。解决：`-webkit-user-drag:none` 加在**行的内容**上，不要加在行本身（加在行上会让行也拖不动）。这条是从侧边栏会话行的实现里学来的。
+
+9. **primitive 图标不转发 inline `style`**：需要旋转/变色请传 `className`（本插件为此注入一张极小的自有样式表）。
+
+10. **数组顺序可控，record 键顺序不可控**：`providers` 是 record，宿主要规范化键顺序，整体 `set` 与 `unset`+`set` 都实测无效 —— 所以供应商顺序只能存本机偏好。
+
+11. **面板里用到的每个局部变量都要真的声明**：曾在 `ProviderModelOrder` 里用了 `C`（官方类名映射）却没定义 → `ReferenceError` → 条目再次被静默弃权，表现为「面板整个不见了」。
+
+12. 浏览器半只需 `react` / `react-dom` / `@deepseek-ai/dsh-client-ui-primitives`（都在 shell 的 PLATFORM_MODULES 种子里），无需 `dsh.client.external`。
+
+## 兼容性与鲁棒性（已核查）
+
+### 已发现并修复的真实冲突
+
+**`settings.models.provider-card` 被 `@linxin666/dsh-client-ui-model-capabilities` 占用。**
+该座位是 **keyed**，key 由官方页面固定派发为供应商的 settings namespace（`llm-pi-ai`）；而该插件已经用同一个 key 注册了「模型能力」面板。SlotCore 对 keyed 座位**一个 key 只保留一个占用者**，且同 key 同优先级会直接抛错 —— 它用 `try/catch` 吞掉异常，所以**本插件早期版本一直在静默压制它的「模型能力」面板**（实测：让出该座位后，每个供应商卡片立刻出现「模型能力」）。
+
+**修复**：本插件不再占用该座位，模型排序改由自己拥有的 `settings.models.footer`（list 座位，`id: model-organizer-provider-order`）承载 —— list 座位按 id 去重，天然可与该插件的 `ui-model-capabilities` 共存。
+
+### 其它已做的加固
+
+| 风险 | 处理 |
+| :-- | :-- |
+| 官方 CSS module 哈希变化 / 被别的模块误命中 | 运行时解析前缀，并用**只有该模块才有的第二个类**（`_optionCopy`）校验；缓存与样式表数量绑定；全部失败则退回内置回退样式 |
+| 座位契约变更（prop 改名等） | **不拦截**：让渲染抛错 → SlotCore 弃权该条目 → 官方内置组件自动回填 |
+| 座位被重命名 / 移除 | `slots.inject` 永不触发 → 对应面板静默消失，其它功能不受影响 |
+| 单个座位注册失败 | 每个座位注册独立 `guard`，失败只记一条 warn，**不会拖垮整个插件** |
+| 写入被拒绝 / ops 契约变化 | `mutate` 的同步抛错与 promise 拒绝都有捕获，并在表头显示失败原因 |
+| 本机偏好 | `localStorage` key 带命名空间，读写都有 try/catch |
+| 注入的样式表 | `<style id="dsh-model-organizer-style">`，类名统一 `dsh-mo-*` 前缀，注入幂等 |
+| 服务端半边 | 只有空 `apply()`，不注册任何宿主能力 |
+
+### 仍然存在的风险（无法在插件侧消除）
+
+- **`conversation.input.model` 是 single 座位**：将来若另一个插件以相同优先级注册，SlotCore 会抛错（本插件的 `guard` 会记 warn，官方内置组件仍会渲染）。
+- **官方模型页若改变 keyed 派发约定**，依赖该座位的插件会失效 —— 本插件已不依赖它。
+- **官方 CSS module 若改名**（例如删掉 `optionCopy`），校验会失败并退回回退样式：功能可用、外观降级。
+- **卡片排序**是本插件唯一会改官方 DOM 的地方（给官方列表设 `display:flex` + 给 `li` 设 CSS `order`，不移动节点）。若 DSH 改那棵 DOM，该功能会静默降级，其余功能不受影响。
+
+## 排查手册
+
+### 让 agent 浏览器不显示窗口（消除抢焦点）
+
+`dsh-ego-browser` 驱动的 Chromium 是 DSH 的子进程，默认以真实窗口存在，并且**每次动作工具都会 `Target.activateTarget` 把它顶到前台**（这就是「用着用着 Chrome 跳出来」的原因）。让它完全不出现窗口：
+
+```powershell
+# 只对当前终端会话生效（先这样试）
+$env:EGO_LINUX_HEADLESS = 1
+dsh web
+
+# 永久生效（设完必须重开终端，再启动 DSH）
+setx EGO_LINUX_HEADLESS 1
+```
+
+- 显式设置 `1/true/yes/on` **优先于**「有没有显示环境」的自动推断（含 Windows）。
+- 浏览器是**单例常驻**进程：改完要重启 DSH（或 `ego-browser --stop`）才冷启动生效。
+- **代价**：只损失「实时观察窗」；其余 `ego_*` 工具（导航/点击/输入/JS/截图/下载）全部照常。
+- 不要用 `chromeArgs` 传 `--headless` —— 它在 `CHROME_BLOCKED` 黑名单里，会被过滤掉。
+
+### 改了插件代码但界面没变化
+
+DSH 把客户端 bundle 以 `Cache-Control: public, max-age=31536000, immutable` 下发，而 URL 不随代码变化 —— 普通刷新会一直用缓存。**必须 Ctrl+Shift+R**（或在 DevTools → Network 勾 Disable cache）。
+
+## 发版流程
+
+```sh
+# 1. 改代码后升版本号（npm 不允许覆盖已发布的版本）
+#    package.json 的 version：0.3.2 → 0.3.3
+# 2. 提交并推送
+git add -A && git commit -m "..." && git push
+# 3. 发布
+npm publish
+```
+
+发布需要带 **Bypass 2FA** 的 Granular Access Token（npm 2025-11 起只支持 granular token）。配置方式：
+npmjs.com → 头像 → Access Tokens → Generate New Token → Packages 选 **All Packages + Read and write (publish and stage)**、**Organizations 选 No access**、勾 **Bypass two-factor authentication**；然后
+`npm config set //registry.npmjs.org/:_authToken=npm_xxx`（写进用户级 `.npmrc`，不要放进仓库）。
+
+## 附：关于「(modlens vision)」供应商分组
+
+这些是 **`@liustack/modlens` 自动生成的「视觉变体」路由**，不是配置重复项：
+
+- 机制：modlens 扫描已注册 provider，找出上游元数据声明为 `text` 且不含 image 的模型（默认按 `deepseek` / `glm` / `mimo` 前缀族匹配），为它们注册一条**声明支持图片输入**的伴随路由，界面名加 `(modlens vision)`。
+- 用途：选中该分组下的模型后，粘贴/拖拽图片会走 DSH 原生附件流程，在调用（纯文本）模型前把图片转成证据文本。不选这个分组时，纯文本模型无法接收图片。
+- 调整：编辑 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 里的 `modlens` 配置（`families` / `discover`），整条关掉用 `visionProvider: false`。视觉引擎配置在 `~/.modlens/config.json`。

package/README.md

@@ -1,191 +1,71 @@
 # dsh-model-organizer
 
-DSH（DeepSeek Harness）模型整理插件。全部通过**官方座位（slot）扩展点**实现，不改动任何官方代码。
+给 DSH（DeepSeek Harness）换个更好用的模型选择器：**按供应商分组、可折叠、可拖拽排序**。
 
-## 功能
-
-### 1. 输入框的模型选择：官方同款外观 + 供应商分组折叠 + 推理强度
-覆盖座位 `conversation.input.model`。触发器与弹层**直接复用官方 `dsh-client-ui-model-selection` 的 CSS-module 类名与 primitives 图标**：
-
-- 触发器 `_…_trigger`（28px 胶囊 + `IconDataOutline16` + `IconChevronDownOutline14`，展开时官方 `chevronOpen` 翻转）；模型有推理等级时按官方格式显示 `模型 · 强度`（`triggerLabel` + `triggerEffort` 两个 span）。
-- 弹层 `_…_menu`（20px 圆角、官方定位算法：右对齐、向上弹出、12px 夹取、滚动/缩放重定位、`z-index 1100`）。
-- **供应商行**用官方 `cell` 下钻行（`cellLabel` + `cellValue` 计数 + `cellChevron`），点击展开/收起时箭头旋转 90°；**模型行**用官方 `option`/`optionCopy`/`modelName`/`check`，当前模型打 ✓。
-- **推理强度**：弹层底部一行官方 `cell`（`推理等级` + 当前值 + 箭头）→ 切到等级面板，等级用官方 `option` 行渲染并给当前等级打 ✓；选等级会以 `{provider, model, reasoningEffort}` **整份重提**（与官方一致）；Esc 先返回模型面板、再按一次才关闭。
-
-默认只列出**供应商**、当前供应商自动展开、其余折叠（这是相对官方扁平列表的增强）。
-
-> 类名前缀在运行时从已注入的样式表里解析（锚定 `_triggerEffort` 等只有该模块才有的类名——直接找 `_trigger` 会误命中 updater 模块的 `fThDlq_trigger`），dsh 升级导致哈希变化也不会静默丢样式；解析失败有内置回退样式。
-
-**推理强度行什么时候出现**：与官方一致——只有**当前模型提供推理等级**时才显示。等级来源（宿主 `resolveModelReasoning`）：模型写了 `reasoningEfforts` 就用它；写 `false` 表示非推理模型；**没写则回退到内置 catalog 的能力**（`base.reasoning`），所以自建/改名的模型 ID 通常拿不到等级，需要显式声明：
-
-```yaml
-# settings.yaml → llm-pi-ai.providers.<provider>.models[]
-- id: <你的模型 ID>
-  name: DeepSeek-V4-Pro
-  reasoningEfforts:      # 键=可选等级，值=发给上游的线值；只有 off 可以留空
-    off:
-    high: high
-    max: ultra
-```
-
-### 2. 模型顺序拖拽（写入设置，持久化）
-在**页脚面板**（见功能 3）里，每个供应商行可展开，展开后列出它的模型并可直接拖拽排序：
-
-- **默认折叠**（表头只显示 `模型顺序 | 拖动 ⠿ 调整，松手即保存`），点击表头展开/收起，箭头随之旋转 90°；
-- 表头与模型行都用官方 `cell` / `option` 类渲染（与官方模型页同一套样式）；
-- 状态提示（`已保存 ✓` / `有未保存改动` / 只读）跟在表头文字**右侧**，不会挤压列表布局；
-- 拖动 ⠿ 时列表**实时按目标顺序重排**（其他行让位），**松手即保存**并写回 `llm-pi-ai.providers.<id>.models`（实测 `settings.yaml` 随顺序变化）；
-- 无上下箭头；仅 ≥2 个模型的供应商显示。
+## 它解决什么问题
 
-### 3. 供应商与模型顺序面板（模型页内的浮动面板）
-注册座位 `settings.models.footer`（**list** 座位，用本插件自己的 `id`，可与其它插件共存），并以**固定浮动面板**呈现（右下角 `fixed`，380px，`z-index 900`）：这样在上面配置供应商 API / 模型的同时，就能在右下角直接拖拽排序，不必滚到页面底部。**默认折叠**（只留说明行 + 一个折叠按钮），展开状态记在 `localStorage: dsh-model-organizer.panelOpen`，点一次以后保持。
+官方那个模型下拉是一个扁平长列表——供应商只是粘性小标题，模型多的时候要滚很久，也没法按自己的习惯排序。这个插件把它改成两级：**先看供应商，点开才看模型**，并且供应商和模型的顺序都能直接拖。
 
-面板提供：
-
-- 供应商行（官方 `cell` 样式 + 可点击展开，箭头旋转 90°），**默认折叠**；
-- 展开后嵌套该供应商的模型行（官方 `option` 样式 + 前置圆点 + 缩进，与供应商行视觉区分），可拖拽排序并写入设置；
-- 供应商行本身也可拖拽（调整显示顺序）；
-- 说明行**没有任何悬停反应**（它是说明，不是控件）；折叠按钮是独立的按钮，只有它有悬停/上浮反馈；拖拽手柄 ⠿ 做成按钮样式（悬停出现描边 + 上浮 1px + `cursor:grab`）。
+## 功能
 
-**为什么不写进 settings**：`providers` 是 record，宿主要规范化它的键顺序——整体 `set` 与 `unset`+`set` 两种写法都实测无效（返回 ok、文件被重写，但键顺序与界面顺序都不变）。因此该顺序存储为本插件的本机偏好（`localStorage: dsh-model-organizer.providerOrder`），作用于本插件渲染的模型菜单排列，拖完立即生效（每次渲染读取，无需刷新）。
+**输入框的模型菜单**
+- 默认只列供应商，点一下展开它的模型，当前模型打 ✓
+- 触发器显示 `模型 · 推理等级`，等级可以在菜单底部单独切换
+- 外观沿用官方样式（同一个弹层、同一套图标），不会突兀
 
-## 安装 / 卸载
+**排序**
+- 在「设置 → 模型」右下角的浮窗里，**直接拖动**供应商行或模型行
+- 模型顺序写进 `settings.yaml`（永久、跨设备）；供应商顺序存在本机
 
-`dsh plugin` 只是把参数转发给 profile 目录里的 pnpm，所以下面三种来源都能装（**不需要发布到 npm**）：
+## 安装
 
 ```sh
-# 1) npm（发布后可用，最快）
 dsh plugin --profile web add dsh-model-organizer
-
-# 2) GitHub 仓库
-dsh plugin --profile web add github:NimoXie15/dsh-model-organizer
-
-# 3) 本地目录（开发时用）
-dsh plugin --profile web add link:/absolute/path/to/dsh-model-organizer
 ```
 
-装完**重启 web 服务**（关闭后重新 `dsh web`）。卸载：
+装完重启 web 服务（关掉再 `dsh web`）。卸载：
 
 ```sh
 dsh plugin --profile web remove dsh-model-organizer
 ```
 
-> 改完插件代码如果界面上没变化，先 **Ctrl+Shift+R** 强刷：DSH 把客户端 bundle 以 `Cache-Control: immutable, max-age=31536000` 下发，而 URL 不随代码变化，普通刷新会一直用缓存。
+也可以从 GitHub 或本地目录装（`dsh plugin` 只是转发给 pnpm，不需要发布到 npm）：
 
-## 截图
+```sh
+dsh plugin --profile web add github:NimoXie15/dsh-model-organizer
+dsh plugin --profile web add link:/absolute/path/to/dsh-model-organizer
+```
 
-> 📷 **截图占位**：待补充。上一版截图包含真实供应商 / 会话名称，已全部移除，将在脱敏环境（干净的 profile、示例供应商名）重新截图后补上。
+> **兼容性**：已在 DSH `0.1.7-rc.1` 上验证，同时兼容 `0.1.5`/`0.1.6`（0.1.7 把客户端设置镜像服务从 `settingsScope` 改名为 `configForms`，本插件两个名字都注入，所以两个版本都能用）。
 >
-> 想要的效果预览：
-> - **模型选择菜单**：供应商分组行（可点击展开/收起，箭头旋转）→ 展开后是缩进的模型行（前置圆点、当前项打勾）→ 底部一行「推理等级」入口，点进去是等级列表。
-> - **模型设置页浮窗**：右下角固定面板，表头一行「供应商与模型顺序 · 拖动行即可调整顺序」；展开后是供应商行（右侧显示「N 个模型」），点开某个供应商可以看到它下面的模型行；供应商行和模型行都能直接拖动排序。
-
-## ⚠️ 开发要点（踩过的坑，改代码前务必先读）
-
-1. **profile bundle 必须声明 `dsh.bundle.patch`**（指向 `cordis.patch.yml`）。缺了它 dsh 启动即报
-   `profile bundle "..." declares no dsh.bundle in its package.json`。
-
-2. **顶层 `inject` 必须声明座位 standardProps 会读取的每一个服务**（本插件：`locale, slots, sessions, remote, remote.session, remote.settings`）。
-   少一个 → 渲染时抛 `cannot get property "remote.session" without inject` → **条目被静默弃权（abdicate）并回退到内置 UI**，界面无任何报错。
-   调用 `remote.settings.mutate` 还必须显式声明 **`remote.settings`**。
-
-3. **owner props 以组件 props 传入，不经过座位的 `inject` 工厂**：`settings.models.provider-card` 的 `inject` 不接收参数，必须读 `props.provider`。
+> 升级插件后如果界面没变化，按 **Ctrl+Shift+R** 强刷一次（DSH 的客户端 bundle 带一年 immutable 缓存，普通刷新不会重新下载）。
 
-4. **`single` 座位优先级**：同优先级注册会**直接抛错**；运行时为非 chain 座位**自动分配**优先级（`--nextPriority` 递减），**后注册者胜出**。
-
-5. **drop 事件会在行与容器上各触发一次**（冒泡），需用 ref 加锁，否则重复写入。
-
-6. **边框必须用 longhand**（`borderWidth/borderStyle/borderColor`）。
-   用 shorthand `border` 再叠加 `borderColor` 时，React 会把 shorthand 展开成 longhand；回退时移除 `borderColor`，`border-color` 就落回 **currentColor** ——表现为"拖拽结束后高亮边框一直不消失"。这是本插件踩过的真实坑。
-
-7. **拖拽后要清焦点**：浏览器会把被拖节点留在焦点上。行加 `outline:none` + `tabIndex:-1`，drop/dragend 时 `blur()`。
-
-7b. **面板里用到的每个局部变量都要真的声明**：曾在 `ProviderModelOrder` 里用了 `C`（官方类名映射）却没定义 → `ReferenceError` → 条目再次被静默弃权，表现为"面板整个不见了"。
-
-8. **primitive 图标不转发 inline `style`**：需要旋转/变色请传 `className`（本插件为此注入一张极小的自有样式表）。
-
-9. **数组顺序可控，record 键顺序不可控**（见功能 3）。
-
-10. 浏览器半只需 `react` / `react-dom` / `@deepseek-ai/dsh-client-ui-primitives`（都在 shell 的 PLATFORM_MODULES 种子里），无需 `dsh.client.external`。
-
-## 关于「(modlens vision)」供应商分组
-
-这些是 **`@liustack/modlens` 自动生成的「视觉变体」路由**，不是你的配置重复项（依据：modlens 自带文档 `docs/harness-setup.zh-CN.md`）：
-
-- 机制：modlens 扫描所有已注册 provider，找出上游元数据声明为 `text` 且**不含 image** 的模型（默认按 `deepseek` / `glm` / `mimo` 前缀族匹配），为它们注册一条**声明支持图片输入**的伴随路由，界面名加上 `(modlens vision)`。
-- 用途：**选中该分组下的模型后**，粘贴/拖拽图片与附件按钮会走 DSH 原生附件流程，在调用（纯文本）模型前把图片转成**证据文本**。不选这个分组时，纯文本模型根本无法接收图片。
-- 调整范围：编辑 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`：
-  ```yaml
-  - id: modlens
-    config:
-      families: ['deepseek', 'glm']        # 缩小自动发现前缀（默认 deepseek/glm/mimo）
-      discover: ['openrouter', 'nvidia']   # 只在这些已注册 provider 里发现
-  ```
-  想整条关掉可用 `visionProvider: false`。视觉引擎（用哪个模型读图）配置在 `~/.modlens/config.json`，也可在 **设置 → 插件 → 插件配置** 的卡片里改。
-
-## 兼容性与鲁棒性（已核查）
-
-### 已发现并修复的真实冲突
-
-**`settings.models.provider-card` 被 `@linxin666/dsh-client-ui-model-capabilities` 占用。**
-该座位是 **keyed**，key 由官方页面固定派发为供应商的 settings namespace（`llm-pi-ai`）；而该插件已经用同一个 key 注册了「模型能力」面板。SlotCore 对 keyed 座位**一个 key 只保留一个占用者**，且同 key 同优先级会直接抛错 —— 它用 `try/catch` 吞掉异常，所以**本插件早期版本一直在静默压制它的「模型能力」面板**（实测：让出该座位后，每个供应商卡片立刻出现「模型能力」）。
-
-**修复**：本插件不再占用该座位，模型排序改由自己拥有的 `settings.models.footer`（list 座位，`id: model-organizer-provider-order`）承载 —— list 座位按 id 去重，天然可与该插件的 `ui-model-capabilities` 共存。
-
-### 其它已做的加固
-
-| 风险 | 处理 |
-| :-- | :-- |
-| 官方 CSS module 哈希变化 / 被别的模块误命中 | 运行时解析前缀，并用**只有该模块才有的第二个类**（`_optionCopy`）校验；缓存与样式表数量绑定，晚注入的样式表仍能被发现；全部失败则退回内置回退样式 |
-| 座位契约变更（prop 改名等） | **不拦截**：让渲染抛错 → SlotCore 弃权该条目 → 官方内置组件自动回填，用户始终有可用的选择器 |
-| 座位被重命名 / 移除 | `slots.inject` 永不触发 → 对应面板静默消失，其它功能不受影响 |
-| 单个座位注册失败（含未来与别的插件抢 single/keyed 单元） | 每个座位注册独立 `guard`，失败只记一条 warn，**不会拖垮整个插件** |
-| 写入被拒绝 / ops 契约变化 | `mutate` 的同步抛错与 promise 拒绝都有捕获，并在表头显示失败原因 |
-| 本机偏好 | `localStorage` key 为 `dsh-model-organizer.providerOrder`，带命名空间、读写都有 try/catch |
-| 注入的样式表 | `<style id="dsh-model-organizer-style">`，类名统一 `dsh-mo-*` 前缀，注入幂等 |
-| 服务端半边 | 只有空 `apply()`，不注册任何宿主能力 |
-
-### 仍然存在的风险（无法在插件侧消除）
-
-- **`conversation.input.model` 是 single 座位**：如果将来另一个插件也以相同优先级注册，SlotCore 会抛错（本插件的 `guard` 会记 warn，官方内置组件仍会渲染）。
-- **官方模型页若改变 keyed 派发约定**（不再用 settingsNs 作 key），依赖该座位的插件（含本插件的早期形态）会失效——本插件已不依赖它。
-- **官方 CSS module 若改名**（例如删掉 `optionCopy`），校验会失败并退回回退样式：功能可用、外观降级。
-
-### 与官方页面的耦合（审计结论，非 bug 但要知道）
-
-- **卡片排序**是本插件唯一会改官方 DOM 的地方：给官方供应商列表设 `display:flex; flex-direction:column`，再给每个 `li` 设 CSS `order`（不移动节点）。若 DSH 改动那棵 DOM 的结构，该功能会静默降级（卡片回到文档顺序），其余功能不受影响。
-- **官方 CSS-module 类名**靠运行时解析（锚定只有该模块才有的类名，并用第二个类名校验）；解析失败会退回内置回退样式：功能可用、外观降级。
-- **座位占用只有两个**：`conversation.input.model`（single，priority -1）与 `settings.models.footer`（list，id `model-organizer-provider-order`）。与 `@linxin666/dsh-client-ui-model-capabilities` 冲突的 `settings.models.provider-card` 座位**已被本插件让出**。
-- 只写一个全局：`window.__dshModelOrganizerBuild`（构建标记，用于判断浏览器是否在跑缓存的旧 bundle）；只注入一张 `<style id="dsh-model-organizer-style">`（幂等）。
-
-## 附：环境变量与排查
+## 截图
 
-### 让 agent 浏览器不显示窗口（消除抢焦点）
+📷 待补充。
 
-`dsh-ego-browser` 驱动的那个 Chromium 是 DSH 的子进程，默认会以一个真实窗口存在，并且**每次动作工具都会 `Target.activateTarget` 把它顶到前台**（这就是"用着用着 Chrome 跳出来"的原因）。让它完全不出现窗口：
+## 想让「推理等级」出现，需要模型自己声明
 
-```powershell
-# 只对当前终端会话生效（先这样试）
-$env:EGO_LINUX_HEADLESS = 1
-dsh web
+只有模型提供了等级，菜单里才会出现「推理等级」入口——这与官方行为一致。在你的 `settings.yaml` 里给模型加上：
 
-# 永久生效（设完必须重开终端，再启动 DSH）
-setx EGO_LINUX_HEADLESS 1
+```yaml
+# settings.yaml → llm-pi-ai.providers.<供应商>.models[]
+- id: <你的模型 ID>
+  reasoningEfforts:      # 键=可选等级，值=发给上游的线值；只有 off 可以留空
+    off:
+    high: high
 ```
 
-- 显式设置 `1/true/yes/on` 会**优先于**"有没有显示环境"的自动推断（含 Windows），所以桌面环境下也能强制无头。
-- 浏览器是**单例常驻**进程：改完要重启 DSH（或运行 `ego-browser --stop`）才会冷启动生效。
-- **代价**：只损失「实时观察窗」这一项；其余 `ego_*` 工具（导航/点击/输入/JS/截图/下载）全部照常。
-- 想恢复观察窗：去掉该环境变量并重启 DSH。
-- 不要试图用插件设置里的 `chromeArgs` 传 `--headless` —— 它被列在 `CHROME_BLOCKED` 黑名单里，会被过滤掉。
+## 已知限制
 
-### 改了插件代码但界面没变化
+- 只处理 `llm-pi-ai` 命名空间下的供应商（DeepSeek 官方供应商不在其中）
+- 供应商顺序、浮窗位置是本机偏好，不跨设备同步
+- 只占用两个官方扩展点（`conversation.input.model`、`settings.models.footer`），不改官方代码
 
-DSH 把客户端 bundle 以 `Cache-Control: public, max-age=31536000, immutable` 下发，而 bundle 的 URL 不随代码变化 —— 普通刷新会一直用缓存。**必须 Ctrl+Shift+R 强刷**（或在 DevTools → Network 勾 Disable cache）。
+## 许可
 
-## 已知限制
+MIT
+
+---
 
-- 只处理 `llm-pi-ai` 命名空间；DeepSeek 官方供应商（`dsh-llm-deepseek`）不在其内。
-- 供应商顺序是本机偏好，不同步到其它浏览器/设备；模型顺序写入设置文档，跨设备同步。
-- 推理强度行需要模型声明 `reasoningEfforts`（或 catalog 已知该模型 ID），否则不显示——与官方行为一致。
-- 浮窗位置（拖到哪）也是本机偏好；想复位就清掉 `localStorage` 里的 `dsh-model-organizer.panelPos`。
+开发笔记、兼容性审计、排查手册见 [DEVELOPING.md](./DEVELOPING.md)。

package/lib/client.js

@@ -90,7 +90,7 @@ window.__ModuleLoader__.load({
        code changes, so a browser can keep running an old build until a hard reload.
        Kept OFF the UI (it is not user-facing): read it as
        `window.__dshModelOrganizerBuild` when a stale build is suspected. */
-    const BUILD = "b23";
+    const BUILD = "b24";
 
     let officialClasses = null;
     let officialClassesSheets = -1;
@@ -265,11 +265,16 @@ window.__ModuleLoader__.load({
       /* Floating presentation: the panel sits in the corner of the Models page so
          provider/API configuration and reordering are visible at the same time. */
       floatPanel: {
-        position: "fixed", right: 20, bottom: 20, zIndex: 900, width: 380, maxWidth: "calc(100vw - 40px)",
+        position: "fixed", right: 20, bottom: 20, zIndex: 10000, width: 380, maxWidth: "calc(100vw - 40px)",
         display: "flex", flexDirection: "column", padding: 4,
         border: "1px solid var(--dsw-alias-border-l1)", borderRadius: 14,
         background: "var(--dsw-specific-menu, var(--dsw-alias-bg-module, #222))",
-        boxShadow: "0 10px 30px rgba(0,0,0,.34)", color: "var(--dsw-alias-label-primary)"
+        /* 0.1.7's menu token is translucent and the shipped menu pairs it with this
+           blur; without it the panel reads as see-through and the cards behind it
+           bleed through. The elevation shadow matches the shipped menu too. */
+        backdropFilter: "var(--dsw-menu-backdrop-filter)",
+        boxShadow: "var(--dsw-elevation-prominent, 0 10px 30px rgba(0,0,0,.34))",
+        color: "var(--dsw-alias-label-primary)"
       },
       /* The shipped `cell` sets min-width:100%; the head must stay inside the panel. */
       panelHeadCell: { display: "flex", alignItems: "center", gap: 6, flex: "1 1 auto", minWidth: 0 },
@@ -1105,6 +1110,38 @@ window.__ModuleLoader__.load({
       return known.concat(rest);
     }
 
+    /* A seat entry that throws is silently abdicated, so "my panel is missing" and
+       "my panel threw" look identical from the page. This boundary turns the throw
+       into one visible line, so the failure can be reported instead of guessed. */
+    class PanelBoundary extends React.Component {
+      constructor(props) {
+        super(props);
+        this.state = { err: null };
+      }
+      static getDerivedStateFromError(err) {
+        return { err: err };
+      }
+      render() {
+        if (this.state.err !== null) {
+          const message = String((this.state.err && this.state.err.message) || this.state.err);
+          return h("div", {
+            "data-mo": "panel-error",
+            style: {
+              margin: "8px 0", padding: "6px 10px", borderRadius: 8, fontSize: 12, lineHeight: "18px",
+              whiteSpace: "pre-wrap",
+              border: "1px solid var(--dsw-alias-state-error-primary, #f85149)",
+              color: "var(--dsw-alias-state-error-primary, #f85149)"
+            }
+          }, "dsh-model-organizer 面板渲染失败：" + message);
+        }
+        return this.props.children;
+      }
+    }
+
+    function ProviderOrderPanelGuarded(props) {
+      return h(PanelBoundary, null, h(ProviderOrderPanel, props));
+    }
+
     function ProviderOrderPanel(props) {
       const C = resolveOfficialClasses();
       ensureOwnStyles();
@@ -1164,21 +1201,9 @@ window.__ModuleLoader__.load({
       const idsKey = ids.join("|");
       const dirty = order !== null && order.join("|") !== sourceKey;
 
-      /* Mirror the stored order onto the shipped provider cards (CSS `order` only —
-         the DOM React rendered is never touched). The cards may be (re)rendered after
-         this effect runs, which drops the inline styles, so it is applied again on the
-         next frame and once more shortly after. */
-      useEffect(function () {
-        const list = idsKey.length === 0 ? [] : idsKey.split("|");
-        applyCardOrder(display, list);
-        const frame = requestAnimationFrame(function () { applyCardOrder(display, list); });
-        const timer = setTimeout(function () { applyCardOrder(display, list); }, 400);
-        return function () {
-          cancelAnimationFrame(frame);
-          clearTimeout(timer);
-        };
-      }, [sourceKey, idsKey]);
-
+      /* The shipped provider cards are left exactly as React renders them. Ordering used
+         to be mirrored onto them with inline `order`; that is gone — this plugin adds a
+         floating panel to the Models page and nothing else. */
       function commit(next) {
         if (next.join("|") === baseIds.join("|")) { setOrder(null); return; }
         writeProviderOrder(next);
@@ -1352,56 +1377,19 @@ window.__ModuleLoader__.load({
         : Object.assign({}, S.floatPanel, { left: panelPos.left, top: panelPos.top, right: "auto", bottom: "auto" });
       /* Original layout (header first, list below) with a TOP-anchored panel: the
          header never moves and collapsing pulls the bottom edge up. */
-      return h("div", { ref: panelRef, style: panelStyle },
-        head,
-        panelOpen ? h("div", { style: S.floatBody }, list) : null
+      /* Portalled to <body>: the footer seat lives deep inside the settings page, so a
+         fixed panel there is trapped in that subtree's stacking context and any other
+         plugin's floating widget paints over it. At body level the z-index is global. */
+      return ReactDOM.createPortal(
+        h("div", { ref: panelRef, style: panelStyle, "data-mo": "panel" },
+          head,
+          panelOpen ? h("div", { style: S.floatBody }, list) : null
+        ),
+        document.body
       );
     }
 
     /* -------------------------------- helpers --------------------------------- */
-    /* The Models page renders one <li> per provider inside its own <ul>. The host
-       owns that order (the settings document cannot express it — verified), so the
-       stored preference is applied as CSS `order` on a flex column: the DOM is left
-       exactly as React rendered it, only the visual sequence changes. Cards that do
-       not correspond to a settings provider (catalog-only rows) stay pinned first. */
-    function applyCardOrder(providers, ids) {
-      try {
-        const names = [];
-        for (const id in providers) {
-          const dn = providers[id] ? providers[id].displayName : undefined;
-          if (typeof dn === "string" && dn.length > 0) names.push([id, dn]);
-        }
-        if (names.length === 0) return;
-        names.sort(function (a, b) { return b[1].length - a[1].length; });
-
-        let list = null;
-        let best = 0;
-        const lists = document.querySelectorAll("ul");
-        for (let i = 0; i < lists.length; i++) {
-          const items = lists[i].children;
-          let hits = 0;
-          for (let j = 0; j < items.length; j++) {
-            const text = items[j].textContent || "";
-            for (let k = 0; k < names.length; k++) if (text.indexOf(names[k][1]) !== -1) { hits++; break; }
-          }
-          if (hits >= 2 && hits > best) { best = hits; list = lists[i]; }
-        }
-        if (list === null) return;
-
-        list.style.display = "flex";
-        list.style.flexDirection = "column";
-        const rank = {};
-        for (let i = 0; i < ids.length; i++) rank[ids[i]] = i;
-        const items = list.children;
-        for (let i = 0; i < items.length; i++) {
-          const text = items[i].textContent || "";
-          let matched;
-          for (let k = 0; k < names.length; k++) if (text.indexOf(names[k][1]) !== -1) { matched = names[k][0]; break; }
-          const r = matched === undefined ? undefined : rank[matched];
-          items[i].style.order = String(r === undefined ? -1 : r);
-        }
-      } catch (e) {}
-    }
 
     function namespaceView(view, namespace) {
       if (!view || !view.namespaces) return null;
@@ -1450,6 +1438,18 @@ window.__ModuleLoader__.load({
 
     function apply(ctx) {
       try { window.__dshModelOrganizerBuild = BUILD; } catch (e) {}
+      /* A DOM marker proving this bundle actually applied, independent of any seat.
+         Seat registration is silent by design (a throw abdicates the entry), so
+         "is the new code even loaded?" is otherwise unanswerable from the page. */
+      try {
+        if (document.body !== null && document.querySelector('[data-mo="boot"]') === null) {
+          const boot = document.createElement("div");
+          boot.setAttribute("data-mo", "boot");
+          boot.setAttribute("data-mo-build", BUILD);
+          boot.hidden = true;
+          document.body.appendChild(boot);
+        }
+      } catch (e) {}
       ctx.effect(function () { return ctx.locale.register(NS, { zh: zh, en: en }); }, "dsh-model-organizer: dictionaries");
       const t = ctx.locale.bind(NS);
 
@@ -1481,8 +1481,27 @@ window.__ModuleLoader__.load({
         });
       });
 
-      ctx.inject(["slots", "settingsScope", "remote", "remote.settings"], function (scope) {
-        const mirror = scope.settingsScope.describe();
+      /* The settings mirror moved homes: DSH 0.1.7 exposes it as `configForms`
+         (provided by ui-settings); 0.1.5/0.1.6 exposed the same object as
+         `settingsScope`. A cordis `ctx.inject` whose service never appears simply
+         never runs, so injecting only the old name made this whole seat vanish
+         without a single error once DSH renamed it. Inject both names and mount
+         once — whichever resolves first wins, the other stays dormant. */
+      let orderPanelMounted = false;
+
+      function mountOrderPanel(scope, mirror) {
+        if (orderPanelMounted) return;
+        orderPanelMounted = true;
+        /* Mark that the service resolved and the panel is being mounted — this
+           separates "the seat never rendered" from "the inject never fired". */
+        try {
+          if (document.body !== null && document.querySelector('[data-mo="panel-mounted"]') === null) {
+            const mark = document.createElement("div");
+            mark.setAttribute("data-mo", "panel-mounted");
+            mark.hidden = true;
+            document.body.appendChild(mark);
+          }
+        } catch (e) {}
         mirror.ensure();
         const mutate = function (ops, revision) { return scope.remote.settings.mutate(PI_AI_NS, ops, revision); };
 
@@ -1504,9 +1523,16 @@ window.__ModuleLoader__.load({
               id: "model-organizer-provider-order",
               order: 100,
               inject: face
-            }, ProviderOrderPanel);
+            }, ProviderOrderPanelGuarded);
           });
         });
+      }
+
+      ctx.inject(["slots", "configForms", "remote", "remote.settings"], function (scope) {
+        mountOrderPanel(scope, scope.configForms.describe());
+      });
+      ctx.inject(["slots", "settingsScope", "remote", "remote.settings"], function (scope) {
+        mountOrderPanel(scope, scope.settingsScope.describe());
       });
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-model-organizer",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "DSH 模型整理插件：输入框的模型下拉改为「供应商分组 + 模型二级折叠菜单」（含推理等级），并在模型设置页提供一个可拖拽的「供应商与模型顺序」浮窗。",
   "type": "module",
   "main": "lib/index.js",
@@ -17,6 +17,7 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
+    "DEVELOPING.md",
     "LICENSE"
   ],
   "keywords": [