@huai_xin/dsh-model-picker 0.1.0 → 0.1.2

package/README.md

@@ -1,140 +1,53 @@
 # dsh-model-picker
 
-DSH（DeepSeek Harness）的一个插件：**替换输入框里的模型选择器**，做成可搜索、按 provider 分组的列表。
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的输入框换一个**模型选择器**：可搜索、按 provider 分组，模型和思考档位分成两个独立控件。
 
-## 安装
-
-```sh
-dsh plugin --profile <profile> add /path/to/dsh-model-picker     # 本地目录
-dsh plugin --profile <profile> add <包名>                        # 发布后
-```
-
-装完**刷新页面**（客户端模块在页面启动时加载）。
-
-## 四个"很难查"的坑（都踩过）
+DSH 自带的模型选择器是按两级菜单设计的。模型一多，找一个模型要翻两层；思考档位藏在二级菜单里，改一次要点三次。这个插件把它换成一次点开的列表：直接搜、直接选。
 
-1. **`exports` 必须包含 `"./package.json": "./package.json"`。**
-   客户端模块扫描器是用 `createRequire(...).resolve('<包名>/package.json')` 定位包的，
-   解析失败就**直接跳过这个 entry**——没有报错、没有日志，插件只是永远不出现在浏览器里。
-   （`test/unit/client.mjs` 里钉住了这一条；skill 自带的模板恰好缺它。）
-2. **不要在插件对象上声明 fiber 级 `inject`；把等待放进 `apply`。**
-   这一条是踩了很久才查清的。Cordis 里 fiber 级 `inject` 是一条**必须被满足的依赖边**：
-   服务不可见，`apply` 就永远不被调用，entry 停在 `loading`，然后整个渲染进程启动失败：
+## 它做了什么
 
-   ```
-   Error: web boot: 1 entry did not activate
-   @huai_xin/dsh-model-picker: loading
-   RendererStartupFailure: Renderer boot failed for 1 plugin(s)
-   ```
+**可搜索的模型列表** — 点开即输入，按名字或 id 过滤，按 provider 分组显示。
 
-   本插件改成 `apply` 内部 `ctx.inject([...], install)` 软等待：依赖没到只损失这次注册，
-   不会拖垮整个 boot。**注意这跟 `dsh.client.inject`（清单里那条）是两回事**——后者只影响
-   激活顺序，早先把它清空并没有解决问题，日志里一直是"`factory` 已运行、`apply` 未调用"。
-3. **`ctx.remote` / `ctx.remote.session` 必须经 `inject`（或 `ctx.get`）读取。**
-   属性代理对未声明的服务直接抛 `cannot get property "remote.session" without inject`，
-   而这条异常发生在**组件首次渲染时**，表现为整个槽位消失：entry 被 `abdicate`
-   （`listSubTree` 里 `active: false`），官方 occupant 又已被压住，于是两边都不渲染。
-4. **客户端半边要等宿主重启后才会被收录**：改完 `client.js` 只刷新页面，常常还是旧的。
+**模型与思考档位分开** — 两个按钮、两个浮层，互不干扰。换模型不会顺手改掉档位，改档位也不会换模型。
 
-排查用：宿主日志里的 `[model-picker] host 半边已 apply`（宿主侧）与
-`[model-picker] 客户端自检：…`（浏览器侧各阶段上报，见 `index.js` 的路由）。
-宿主那行有、客户端一行都没有 ⇒ 模块没被下发；只有 `factory 已运行` 而没有 `apply 已调用`
-⇒ entry 卡在依赖上（就是第 2 条）。启动失败时 `%APPDATA%/DSH Desktop/diagnostics/*.zip`
-里的 `dsh-*.error.log` 会指名是哪个 entry。
+**和官方选择器共用一份状态** — 不是另起炉灶。它复用 DSH 自己的 `modelDirectories` 服务，所以你在输入框里选的模型，和 `/model` 命令弹窗里看到的，永远是同一个。切换过程中（Host 还没确认时）两个入口都会显示"正在切换"。
 
-## 它如何与"装饰类"插件共存（目前会丢装饰）
+**跟着模型列表实时变** — 别的插件改了可用模型（开关模型、导入账号、探测到模型不可用……），这个列表会立刻跟着变，不用刷新页面。
 
-官方 picker 自己**声明**了子槽位 `conversation.input.model.label`，provider 插件往那里挂装饰
-（可用性、促销、繁忙度…）。替换者想保住这些装饰，就得自己声明并渲染这个子槽位——**但这在
-当前 slots 架构下做不到**，原因是两条硬规则：
+**新会话显示默认模型** — 而不是空着或显示"没有可用模型"。
 
-1. **子槽位只能被声明一次**（`slot "..." is already declared`）。官方 occupant 还在槽位里
-   （只是被 priority 压住不渲染），它的声明仍然有效，我们再声明一次就抛错。
-2. **`renderSlot` 只能渲染自己声明的子槽位**，否则抛 `SlotOwnershipError`。不声明就无权渲染。
+**子会话里自动隐藏** — 在被指派的 subagent 会话里，Host 不允许换模型，控件直接不渲染，而不是给你一个点了必失败的按钮。
 
-第一版曾按"重新声明"实现，结果注册直接抛错，反而把官方 occupant 挤掉了——那次的表现是
-**整个选择器消失**。所以现在**不声明 `children`**：picker 正常渲染，但 provider 挂在
-`conversation.input.model.label` 上的装饰在这个槽位里不显示。
-
-真要同时满足两者，只有让官方 `ui-model-selection` 的 occupant 完全缺席（停用那个 bundle），
-代价是它的 `/model` 命令贡献一起消失。这是架构限制，不是本插件的实现缺陷。
-
-## 数据层（与官方 `ui-model-selection` 同一套契约）
-
-数据不是自己拼的，走的是和官方相同的三层结构，`test/unit/client.mjs` 逐条钉住：
-
-**1. 全局目录（`ModelCatalogDirectory` 的等价物）**
-- 一份、按 Host generation 作用域，所有会话共用；in-flight 请求去重。
-- 每次失效递增 generation，旧请求的迟到响应**直接丢弃**，不会覆盖新值。
-- `reasoning` 记住每个模型的档位元数据，**模型离开目录后仍能显示档位名字**。
+## 安装
 
-**2. 会话级目录（`ModelDirectory` 的等价物）**
-- store 形状与官方一致：`{ current, routable, groups, failures, status, pending, error }`。
-- `current` = 会话显式选择 ?? 目录 `default`（官方同样的优先级）。加载中显示"加载中"，
-  而不是模型名，也不是"没有可用模型"。
-- `pending` 在 RPC 前后发布，触发器能显示正在结算的选择。
-- `select()` 带 generation 竞态保护：**后发起的胜出**，旧回复即便晚到也不写入。
-  （单测用突变验证过：去掉这个守卫，断言立刻失败。）
-- 切模型时带上适配器的默认档位，与官方提交的三元组一致。
-- `failures` 渲染为提示行，某个 provider 组加载失败不再静默消失。
+```sh
+dsh plugin --profile <你的 profile> add @huai_xin/dsh-model-picker
+```
 
-**3. `modelDirectories` 服务**
-- **优先复用官方已注册的服务**——这正是让输入框和 `/model` 弹窗共享同一份选择状态（含在途
-  状态）的关键。官方服务存在时不重复注册（重复 `ctx.provide` 会抛错）。
-- 官方服务缺席时（bundle 被停用、旧版本），本插件以同名提供一份**同契约**的实现，组件无感知。
-- 按 sessionId 键控目录，不按 binding 对象：binding 访问器可能每次返回新包装，按它做键会导致
-  每次重挂载都新建目录、丢掉在途状态。
+装完**重启宿主**，再刷新页面。客户端代码是在页面启动时加载的，只刷新页面通常还是旧的。
 
-**四个失效事件 + `connection/reset`**：与官方监听集合完全一致；只听 `llm/adapters-updated`
-的旧版会在改设置/凭据后继续提供宿主已拒绝的模型。
+也可以从本地目录装：
 
-**子会话**：addressed subagent 会话里 Host 会拒绝 `selectModel`，官方 picker 在那种会话里
-什么都不渲染，本插件同样返回 `null`。
+```sh
+dsh plugin --profile <你的 profile> add /path/to/dsh-model-picker
+```
 
-**仍与官方不同**（有意保留的范围差异）：没有 `/model` 命令贡献，也不做 analytics 埋点——
-这两项属于官方 bundle，不在"替换输入框选择器"的职责内。
+不想要了就直接停用或移除这个 bundle，不会影响模型本身是否可用。
 
-## 工程结构
+## 已知限制
 
-源码在 `src/` 下按职责拆分，`client.js` 是**构建产物**（勿手改）：
+**会丢掉 provider 插件挂在模型名上的装饰。** DSH 官方选择器声明了一个子槽位 `conversation.input.model.label`，provider 插件往那里挂徽标、可用性提示、促销标记之类的东西。替换者没法继承这个声明——子槽位只能声明一次，官方占用者即使被压住不渲染，它的声明依然有效。所以在这个选择器里，模型名后面不会有那些装饰。
 
-```
-src/
-  client.js          入口：模块注册 + 插件对象 + 装配（含服务复用与槽位注册）
-  core/
-    store.js         snapshot store 契约（getSnapshot/subscribe/set/update）
-    selection.js     readSelection（兼容各代字段拼写）、isAvailable（子会话探测）
-    catalog.js       全局目录：共享缓存、generation 失效、reasoning 记忆
-    directory.js     会话级目录：current/routable/pending/failures + 竞态保护
-    directories.js   modelDirectories 服务的自带实现（官方缺席时使用）
-  ui/
-    ModelPicker.js   组件：触发器 + 模型面板 + 档位面板
-    Chevron.js       展开箭头
-    dict.js          中英字典
-    styles.js        样式表（仅 --dsw-alias-* 主题令牌）
-scripts/build.mjs    零依赖打包器：按依赖顺序拼接 src/ → client.js
-client.js            构建产物，由 scripts/build.mjs 生成
-```
+想同时要装饰和这套交互，只能停用官方的 `ui-model-selection` bundle，代价是它的 `/model` 命令一起消失。这是 DSH 槽位架构的限制，不是本插件能绕过的。
 
-**为什么需要构建**：Client 模块加载器给每个包只有一个浏览器入口
-（`exports["./client"]`），并以 classic script 执行，不会在运行时解析插件的 ESM 依赖图。
-所以源码拆开维护、构建时拼接成单文件，是既能保持可维护性、又不要求宿主提供它没有的能力的做法。
+## 兼容性
 
-打包器只做三件事：深度优先收集本地 `./x.js` 依赖、剥掉 `import`/`export` 语法、按依赖顺序
-拼接。它不做 tree-shaking，也不解析裸模块——遇到裸 import 会直接报错（宿主模块应从 factory
-的 `require` 取）。
+需要 DSH `0.2.1-rc` 及以上。模型数据全部走 DSH 自己的 client remote（`session.modelCatalog` / `session.selectModel`），插件本身不认识任何具体 provider——任何 provider 插件注册的模型都会出现在列表里。
 
-```sh
-node scripts/build.mjs    # 或 pnpm build：重新生成 client.js
-node test/unit/client.mjs # 或 pnpm test：构建 + 离线单测
-```
+## 开发
 
-单测会校验 `client.js` 是否由当前源码构建（每个模块有 `//# module:` 标记，且产物不得旧于
-任何源文件），避免改完源码忘记重新构建、让测试跑在过期产物上。
+见 [AGENTS.md](AGENTS.md)。
 
-## 开发
+## License
 
-```sh
-pnpm build                     # 重新生成 client.js
-pnpm test                      # 构建 + 离线单测（无依赖，自带迷你 React）
-```
+MIT

package/client.js

@@ -96,10 +96,15 @@ const INVALIDATION_EVENTS = Object.freeze([
  * model's effort metadata *after* the model leaves the catalogue — so a level
  * still shows its name while its model is gone.
  *
- * @param remote - the client remote face carrying `session.modelCatalog`.
+ * @param resolveRemote - returns the client remote face carrying `session.modelCatalog`.
+ *   A THUNK, not the face itself: this catalogue is built in `apply`, where the
+ *   `remote` service is often not visible yet (it arrives later in the client boot
+ *   sequence). Capturing the value here froze `undefined` and every load then
+ *   reported "modelCatalog is unavailable".
+ * @param onDiagnostic - optional sink for load-stage notes.
  * @returns the catalogue controller.
  */
-function createCatalog(remote, onDiagnostic) {
+function createCatalog(resolveRemote, onDiagnostic) {
   const store = createStore({ value: null, status: 'idle', error: null })
   const reasoning = new Map()
   // Bumped by every invalidation. A response that resolves under an older
@@ -112,6 +117,11 @@ function createCatalog(remote, onDiagnostic) {
     try { onDiagnostic?.(message) } catch { /* diagnostics never break the load */ }
   }
 
+  /** The remote face as it is right now, or undefined while the service is absent. */
+  const currentRemote = () => {
+    try { return typeof resolveRemote === 'function' ? resolveRemote() : resolveRemote } catch { return undefined }
+  }
+
   const reasoningFor = (selection) => selection === null || selection === undefined
     ? undefined
     : reasoning.get(JSON.stringify([selection.provider, selection.model]))
@@ -120,8 +130,10 @@ function createCatalog(remote, onDiagnostic) {
     const state = store.getSnapshot()
     if (state.status === 'ready' && state.value !== null) return Promise.resolve(state.value)
     if (inflight !== undefined) return inflight
+    const remote = currentRemote()
     const run = remote?.session?.modelCatalog
     if (typeof run !== 'function') {
+      note('modelCatalog 不可用：remote 尚未就绪')
       store.set({ value: state.value, status: 'error', error: 'modelCatalog is unavailable' })
       return Promise.resolve(undefined)
     }
@@ -491,10 +503,17 @@ function createDirectory(catalog, projectedFace, remote, sessionId) {
  *
  * @param catalog - the shared catalogue controller.
  * @param sessions - the sessions service face.
- * @param remote - the client remote face.
+ * @param resolveRemote - returns the client remote face. A thunk for the same
+ *   reason the catalogue takes one: the service is often not visible yet when
+ *   this object is built, and capturing it froze `undefined`.
  * @returns the service object with `directoryFor`.
  */
-function createDirectoryService(catalog, sessions, remote) {
+function createDirectoryService(catalog, sessions, resolveRemote) {
+  /** The remote face as it is right now, or undefined while the service is absent. */
+  const currentRemote = () => {
+    try { return typeof resolveRemote === 'function' ? resolveRemote() : resolveRemote } catch { return undefined }
+  }
+
   /**
    * Keyed by session id, not by binding object.
    *
@@ -518,7 +537,7 @@ function createDirectoryService(catalog, sessions, remote) {
     const projectedFace = (() => {
       try { return binding?.session?.projections?.faceOf?.('modelSelection') } catch { return undefined }
     })()
-    const directory = createDirectory(catalog, projectedFace, remote, sessionId)
+    const directory = createDirectory(catalog, projectedFace, currentRemote(), sessionId)
     directories.set(key, directory)
     return directory
   }
@@ -1063,26 +1082,52 @@ window.__ModuleLoader__.load({
         report(`apply 已调用（slots=${ctx.get('slots') === undefined ? '尚未就绪' : '就绪'}）`)
 
         /**
-         * The catalogue, its subscriptions, and the directory service are built
-         * HERE, in `apply` itself — not inside the `ctx.inject` callback below.
+         * The catalogue is built HERE, in `apply`, but it reads the `remote`
+         * service LAZILY.
          *
-         * This is the one structural difference from the shipped picker that
-         * matters: the shipped plugin calls `ctx.remote.$on(...)` directly in its
-         * `apply` body. The gateway registers a forwarded-event listener in the
-         * calling fiber's private event domain (`events.subscribe(this.ctx, …)`),
-         * and a subscription made from a scope callback — even when that scope is
-         * the same object — is not in the domain the dispatcher publishes to, so
-         * the listener never fires. Building them here keeps the registration in
-         * the plugin's own fiber, exactly like the shipped plugin.
+         * Two facts pull in opposite directions and this is the seam between
+         * them:
+         *
+         *  - Event subscriptions must be installed from the plugin's own `apply`
+         *    fiber. The gateway registers a forwarded-event listener in the
+         *    CALLING fiber's private event domain, and a subscription made from a
+         *    `ctx.inject` callback lands in a different domain: `$on` returns a
+         *    disposer, so it looks successful, but the listener never fires.
+         *  - `remote` is frequently NOT visible yet when `apply` runs. Capturing
+         *    `ctx.get('remote')` here froze `undefined`, and every catalogue load
+         *    then answered "modelCatalog is unavailable".
+         *
+         * So the catalogue holds a resolver, not the face, and the subscription
+         * is attached as soon as the service appears.
          */
-        const remote = (() => {
+        const remoteFace = () => {
           try { return ctx.get('remote') } catch { return undefined }
-        })()
-        const catalog = createCatalog(remote, (message) => { report(message) })
-        const detachCatalog = catalog.attach(remote, (event) => {
-          report(`收到失效事件 ${event}`)
-        })
-        report(`失效订阅：${catalog.canAttach(remote) ? '已挂到 remote.$on' : 'remote 没有 $on，无法订阅'}`)
+        }
+        const catalog = createCatalog(remoteFace, (message) => { report(message) })
+        /**
+         * Attach the invalidation listeners, retrying once the remote exists.
+         *
+         * `ctx.inject` runs the callback as soon as the named services are
+         * visible, which is the point at which `$on` can be reached — and it runs
+         * in this same `apply` fiber, so the subscription still lands in the
+         * dispatching domain.
+         */
+        let detachCatalog = () => {}
+        const attachCatalog = () => {
+          const remote = remoteFace()
+          if (remote === undefined) return false
+          detachCatalog = catalog.attach(remote, (event) => {
+            report(`收到失效事件 ${event}`)
+          })
+          report(`失效订阅：已挂到 remote.$on`)
+          return true
+        }
+        if (!attachCatalog()) {
+          report('remote 尚未就绪，等它出现后再挂失效订阅')
+          if (typeof ctx.inject === 'function') {
+            ctx.inject(['remote'], () => { attachCatalog() })
+          }
+        }
         const detachReset = typeof ctx.on === 'function'
           ? ctx.on('connection/reset', () => { catalog.resetGeneration() })
           : undefined
@@ -1094,7 +1139,7 @@ window.__ModuleLoader__.load({
         })()
         const directories = shipped !== undefined && typeof shipped.directoryFor === 'function'
           ? shipped
-          : createDirectoryService(catalog, sessions, remote)
+          : createDirectoryService(catalog, sessions, remoteFace)
         const ownsDirectories = directories !== shipped
         report(`目录来源：${ownsDirectories ? '本插件自带实现' : '复用官方 modelDirectories'}`)
         const detachDirectories = ownsDirectories && typeof ctx.provide === 'function'
@@ -1130,7 +1175,7 @@ window.__ModuleLoader__.load({
              * picker degrades to its "could not load the model list" state rather
              * than taking the whole slot down.
              */
-            const remoteSession = at['remote.session'] ?? ctx.get('remote.session') ?? remote?.session
+            const remoteSession = at['remote.session'] ?? ctx.get('remote.session') ?? remoteFace()?.session
 
             slots.inject(SLOT, () => {
               report('槽位回调已运行，准备注册 occupant')
@@ -1180,7 +1225,7 @@ window.__ModuleLoader__.load({
                   return {
                     sessionId,
                     localeId,
-                    remote,
+                    remote: remoteFace(),
                     remoteSession,
                     sessions: sessionSessions,
                     catalog,

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "@huai_xin/dsh-model-picker",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A searchable, provider-grouped replacement for the DSH composer's model picker.",
   "type": "module",
   "license": "MIT",