@mzzsfy/dsh-model-capability-editor 0.3.0 → 0.4.0

package/README.md

@@ -23,7 +23,7 @@ DeepSeek Harness 模型能力编辑插件:编辑 `llm-pi-ai` 管理的第三方
   | off 勾选拼写填值 | 对象形态 `off: "拼写"` |
 
 - input 四态:未声明(删除字段)/ 仅文本(`["text"]`)/ 文本+图像(`["text", "image"]`)/ 仅图片(`["image"]`,纯视觉网关不收文本输入)。
-- 保存前本地校验:非 off 档勾选但拼写空白时拒绝保存并提示具体模型与档位(空白拼写会静默以档位名作线上值,易被误当作已填;off 档留空有专门语义,不参与校验)。卡片与行内编辑块均拦截。
+- 保存前本地校验:非 off 档勾选但拼写空白时拒绝保存并提示具体模型与档位(空白拼写会静默以档位名作线上值,易被误当作已填;off 档留空有专门语义,不参与校验)。卡片与行内编辑块均拦截。保存与校验反馈经全站浮出通知(`@mzzsfy/dsh-toast` 可选依赖,缺失时降级 console)。
 - 一键草稿填充:卡片底部「填充草稿」对当前 provider 内未声明任何档位的模型填入七档全勾、拼写留空(线上值=档位名)的草稿;只改内存草稿,不触碰 inputMode,已声明档位的模型不受影响,写回仍需手动保存。
 - 保存 = mutate set `providers.<route>.models` 整个数组:以 describe 读到的数组为基线,未编辑条目原样保留,settings 未声明的(自动发现的)模型不被删除;providers 缺失或 models 非数组时拒绝保存(防静默覆写为空数组)。
 - 修订冲突:重读 describe 取新 revision,按字段级 diff 仅重放本次修改(仅用户改过的模型条目的 `reasoningEfforts` / `input` 两字段,其余字段保留最新文档值),重试一次;再冲突报错终止并保留用户输入,绝不静默覆盖。"本次修改"以草稿加载时点冻结的种子为参照:加载后他方对基线的修改,不会被零编辑或仅改单一字段的保存静默回滚(该保证覆盖保存开始后的并发写,revision 乐观锁语义)。
@@ -40,7 +40,12 @@ dsh plugin --profile web add @mzzsfy/dsh-model-capability-editor
 
 ## 前置:dsh 本体版本
 
-需要 dsh 本体 0.1.2 及以上(读写经 `remote.settings` 服务面,该面由 0.1.2 引入的 host 侧 `dsh-api-settings-controller` 提供)。更旧的本体上无此服务面,client 半区因注入声明 `remote.settings` 未满足而保持未激活(无 UI、无告警、不影响 web 启动与其他插件);请先升级 dsh,或改用插件 0.1.2(旧 settings 面,已停止维护)。
+支持 dsh 0.1.1-rc.2 / 0.1.2-rc.1 / 0.1.5-alpha.2(实测)。settings 传输按宿主代际自适应:
+
+- 0.1.2+(boot wire 带 `batches` 批次调度):`remote.settings` 以点分 inject 声明交由 cordis 门控,fiber 等 namespace `$mount` 完成才激活,激活即就绪。宿主 `parseBootManifest` 将 `batches` 校验为必填数组(缺失即整页拒绝启动),判据被上游 schema 钉死;宿主未来若移除该字段,本插件退化为 api 面或恒定禁用,不阻塞 boot。
+- 0.1.1(旧 boot wire,无该 namespace):点分声明会永远 pending 拖垮整页 web boot,故声明两代基座 `remote` + `connection`,settings 传输在 apply 内异步定面轮询:从 `connection.api` 面起等,面在首拍即定型;缺失持续满等待窗(1s)则恒定禁用并告警,不影响 web 启动。
+
+注意 0.1.1 本体的 `llm-pi-ai` schema 不认识 0.1.5 引入的 `compat.chatTemplateArgs` 字段,settings.yaml 中该字段会让 0.1.1 的 `llm-pi-ai` settings 注册整体失败(host 侧行为),编辑器随之无数据;从 yaml 删除该字段即恢复。
 
 ## 前置:移除 dsh-better-reasoning-effort
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-model-capability-editor",
   "description": "在设置页编辑第三方模型的思考档位与图片输入声明,解决手写配置易错与档位拼写不可控",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -1,4 +1,4 @@
-// 模型能力编辑 Client 半区:settings.section 独立设置页卡片。
+// 模型能力编辑 Client 半区:官方模型页行内注入,锚点破坏时浮动入口回退。
 // 以 DSH client-modules 自注册格式发布:__ModuleLoader__.load({id, factory}),
 // factory(require) 中 require('react') 与 require('react-dom/client') 由 DSH client
 // runtime 的模块表解析(宿主种子一级键,缺失即整个宿主 UI 不存在,不降级)。
@@ -32,6 +32,12 @@ window.__ModuleLoader__.load({
     // 插件实例代际:宿主热重载/禁用重建时区分新旧实例,样式清理只认自有属主
     let instanceSeq = 0
 
+    // 宿主代际判据:0.1.2+ 的 client-modules boot wire 带 batches 批次调度
+    // (宿主 parseBootManifest 将其校验为必填数组,缺失即整页拒绝启动,判据
+    // 被上游 schema 钉死);0.1.1 的 wire 无此字段。宿主未来若移除 batches,
+    // 退化为 api 面或恒定禁用,不阻塞 boot
+    const hasBatchesWire = typeof window !== 'undefined' && window.__DSH_BOOT__?.batches !== undefined
+
 const CSS = [
   '.mce-card { display:flex; flex-direction:column; gap:10px; color:inherit; font-size:13px;',
   '  border:1px solid var(--dsw-alias-separator-primary, rgba(128,128,128,0.35)); border-radius:10px; padding:12px;',
@@ -309,23 +315,50 @@ function anchorsBroken({ titleMatched, hasEditor, modelIdInputCount }) {
   return titleMatched === true && hasEditor === true && modelIdInputCount === 0
 }
 
-function unwrapResult(result) {
-  if (result !== null && typeof result === 'object' && result.ok === true) return result.value
-  const error = new Error(result && result.error && result.error.message
-    ? result.error.message
-    : 'settings RPC 调用失败')
-  error.code = result && result.error ? result.error.code : undefined
-  throw error
+// settings 传输 → 插件内部 settings 面(describe() / mutate(ns, ops, revision))。
+// 两种宿主传输形态,能力面在 0.1.1 即存在:
+// - typed remote 面(dsh 0.1.2+):方法直返 RemoteResult 信封 {ok,value|error};
+// - connection.api 面(dsh 0.1.1+):settings.describe() 无参,settings.mutate({ns,ops,...})
+//   单对象参数,返回 {rpcId,result:{ok,value|error}} 信封。
+// 面缺失或形状不完整返回 null,由调用方降级呈现只读原因。
+function unwrapEnvelope(envelope) {
+  if (envelope !== null && typeof envelope === 'object' && envelope.ok === true) return envelope.value
+  if (envelope !== null && typeof envelope === 'object' &&
+      envelope.result !== null && typeof envelope.result === 'object') {
+    if (envelope.result.ok === true) return envelope.result.value
+    return rejectRpc(envelope.result.error)
+  }
+  return rejectRpc(envelope && envelope.error)
+}
+
+function rejectRpc(error) {
+  const rpcError = new Error(error && error.message ? error.message : 'settings RPC 调用失败')
+  rpcError.code = error ? error.code : undefined
+  throw rpcError
 }
 
-// dsh 0.1.2 remote.settings 服务 → 插件内部 settings 面(describe() / mutate(ns, ops, revision))。
-// remote 面缺失或形状不完整返回 null,由调用方降级呈现只读原因。
-function makeSettingsFace(remote) {
-  if (remote === null || typeof remote !== 'object' ||
-      typeof remote.describe !== 'function' || typeof remote.mutate !== 'function') return null
+function makeSettingsFace(transport) {
+  if (transport === null || typeof transport !== 'object') return null
+  const typed = typeof transport.describe === 'function' && typeof transport.mutate === 'function'
+  if (typed) {
+    return {
+      describe: async () => unwrapEnvelope(await transport.describe()),
+      mutate: async (ns, ops, expectedRevision) =>
+        unwrapEnvelope(await transport.mutate(ns, ops, expectedRevision)),
+    }
+  }
+  const api = transport.api
+  if (api === null || typeof api !== 'object' ||
+      api.settings === null || typeof api.settings !== 'object' ||
+      typeof api.settings.describe !== 'function' || typeof api.settings.mutate !== 'function') return null
   return {
-    describe: async () => unwrapResult(await remote.describe()),
-    mutate: async (ns, ops, expectedRevision) => unwrapResult(await remote.mutate(ns, ops, expectedRevision)),
+    describe: async () => unwrapEnvelope(await api.settings.describe({})),
+    mutate: async (ns, ops, expectedRevision) =>
+      unwrapEnvelope(await api.settings.mutate({
+        ns,
+        ops,
+        ...(expectedRevision === undefined ? {} : { expectedRevision }),
+      })),
   }
 }
 
@@ -520,7 +553,7 @@ function CapabilityCard(props) {
         patch({ phase: 'readonly', reason: 'remote.settings 服务面缺失,无法读写模型声明' })
         return
       }
-      const value = unwrapResult(await settings.describe())
+      const value = await settings.describe()
       if (value.writable !== true) {
         patch({ phase: 'readonly', reason: 'settings 当前只读,模型能力编辑不可用' })
         return
@@ -559,7 +592,7 @@ function CapabilityCard(props) {
     patch({ route: nextRoute, phase: 'ready' })
     void (async () => {
       try {
-        const value = unwrapResult(await props.settings.describe())
+        const value = await props.settings.describe()
         if (seq !== routeSeqRef.current) return
         const ns = findNsEntry(value)
         if (ns === undefined) {
@@ -610,7 +643,7 @@ function CapabilityCard(props) {
         ? '已保存,但模型 ' + droppedDraftIds.join(', ') + ' 已被其他写者删除,对应修改未写入'
         : '已保存并写回 settings.yaml', droppedDraftIds.length > 0 ? 'error' : 'ok')
       try {
-        const value = unwrapResult(await props.settings.describe())
+        const value = await props.settings.describe()
         const ns = findNsEntry(value)
         if (ns === undefined) {
           // 保存后命名空间被他方移除:明确告知刷新,不再裸抛
@@ -736,7 +769,7 @@ function RowEditor(props) {
           patch({ phase: 'error', notice: 'remote.settings 服务面缺失,无法读写模型声明' })
           return
         }
-        const value = unwrapResult(await settings.describe())
+        const value = await settings.describe()
         const ns = findNsEntry(value)
         if (!alive) return
         if (ns === undefined) { patch({ phase: 'hidden' }); return }
@@ -762,13 +795,13 @@ function RowEditor(props) {
       // S3:官方行内 ID 输入是活动状态,改名已落盘则以新 ID 为目标,否则回落原 ID
       const el = props.idInputEl
       const liveId = el && el.isConnected ? el.value : modelId
-      const first = unwrapResult(await settings.describe())
+      const first = await settings.describe()
       const nsFirst = findNsEntry(first)
       const baselineIds = new Set(nsFirst !== undefined ? modelsOf(nsFirst.value, route).map((entry) => String(entry.id)) : [])
       const targetId = resolveTargetId(liveId, modelId, baselineIds)
       const { models: written, droppedDraftIds } = await saveModels(settings, route, new Map([[targetId, state.draft]]))
       // S4:保存后重读重建草稿,基线新鲜,保留他方词汇表外档位
-      const second = unwrapResult(await settings.describe())
+      const second = await settings.describe()
       const nsSecond = findNsEntry(second)
       const latest = nsSecond !== undefined
         ? modelsOf(nsSecond.value, route).find((entry) => String(entry.id) === String(targetId))
@@ -839,11 +872,15 @@ function RowEditor(props) {
 }
 
     return {
-      // 点分声明 remote.settings 面:cordis 注入门控使 fiber 等 namespace
-      // 挂载完成后才激活(官方插件同构),apply 期面必然就绪,无需探测分支
-      inject: ['remote', 'remote.settings'],
+      // inject 按宿主代际二选一(判据 hasBatchesWire 见上):0.1.2+ 以点分
+      // 声明交由 cordis 门控(fiber 等 namespace $mount 完成才激活,激活即
+      // 就绪;不声明则点分读取永远抛错,实测);0.1.1 的 boot wire 无该
+      // namespace,点分声明会永远 pending 拖垮整页 web boot
+      // (assertEntriesActive 对 pending throw,实测),故声明两代都具备的
+      // 基座服务,settings 传输在 apply 内异步定面轮询。
+      inject: hasBatchesWire ? ['remote', 'remote.settings'] : ['remote', 'connection'],
       apply(ctx) {
-        const settings = makeSettingsFace(ctx.remote.settings)
+        let settings = null
 
         // 行内注入器:MutationObserver 监听官方设置页,reconcile 把编辑块
         // 挂进已展开的模型行;官方结构变化导致锚点全失时,在模型页右侧注入
@@ -864,6 +901,47 @@ function RowEditor(props) {
         // 本实例代际号:样式属主判定用
         const instanceId = ++instanceSeq
 
+        // settings 面按代际取形:0.1.2+ 点分声明下 fiber 等挂载完成才激活,
+        // apply 时已就绪,直接取形;0.1.1 无 typed 面,轮询从 api 相位起——
+        // connection.api 面是 0.1.1 唯一 settings RPC 通道。两代路径对读取
+        // 抛错/面缺失均收敛为恒定只读降级:定面完成前 settings 为 null,
+        // reconcile 早退
+        const FACE_POLL_INTERVAL_MS = 50
+        // 等待窗:各代宿主上面在首拍即定型,窗口只是防御性上界,非真实时延
+        const API_FACE_WAIT_MS = 1000
+        const FACE_UNAVAILABLE_WARN = '[dsh-model-capability-editor] settings RPC 面不可用,编辑功能禁用'
+        // 0.1.1 轮询:读取抛错(cordis get trap)与面缺失同义;窗口判定前置,
+        // 任何路径都不绕过终止性——满窗即恒定禁用,不再重排
+        const faceStartedAt = Date.now()
+        const facePoll = () => {
+          if (disposed) return
+          const expired = Date.now() - faceStartedAt >= API_FACE_WAIT_MS
+          try {
+            settings = makeSettingsFace(ctx.connection)
+            if (settings !== null) { scheduleScan(); return }
+          } catch {
+            // namespace/服务读取未就绪:按轮询节拍重试
+          }
+          if (expired) {
+            console.warn(FACE_UNAVAILABLE_WARN)
+            return
+          }
+          setTimeout(facePoll, FACE_POLL_INTERVAL_MS)
+        }
+        if (hasBatchesWire) {
+          try {
+            settings = makeSettingsFace(ctx.remote !== undefined ? ctx.remote.settings : undefined)
+          } catch (error) {
+            // 一次性终态判定,失败原因随告警留痕
+            console.warn(FACE_UNAVAILABLE_WARN, error)
+            settings = null
+          }
+          if (settings === null) console.warn(FACE_UNAVAILABLE_WARN)
+          else scheduleScan()
+        } else {
+          facePoll()
+        }
+
         function docInfo() {
           const outlet = document.querySelector('[data-slot="settings.section"]')
           if (outlet === null) return null
@@ -941,6 +1019,8 @@ function RowEditor(props) {
 
         function reconcile() {
           if (disposed) return
+          // 定面未完成:不做任何 RPC 与注入,面就绪后 scheduleScan 会再触发
+          if (settings === null) return
           // 已脱离文档的挂载点:官方页卸载或重建了行,释放对应 root
           for (const [container, root] of roots) {
             if (!container.isConnected) {
@@ -979,7 +1059,7 @@ function RowEditor(props) {
           }
           void (async () => {
             try {
-              const value = unwrapResult(await settings.describe())
+              const value = await settings.describe()
               if (disposed || seq !== reconcileSeq) return
               const ns = findNsEntry(value)
               if (ns === undefined) return

package/src/logic.mjs

@@ -208,23 +208,50 @@ export function anchorsBroken({ titleMatched, hasEditor, modelIdInputCount }) {
   return titleMatched === true && hasEditor === true && modelIdInputCount === 0
 }
 
-function unwrapResult(result) {
-  if (result !== null && typeof result === 'object' && result.ok === true) return result.value
-  const error = new Error(result && result.error && result.error.message
-    ? result.error.message
-    : 'settings RPC 调用失败')
-  error.code = result && result.error ? result.error.code : undefined
-  throw error
+// settings 传输 → 插件内部 settings 面(describe() / mutate(ns, ops, revision))。
+// 两种宿主传输形态,能力面在 0.1.1 即存在:
+// - typed remote 面(dsh 0.1.2+):方法直返 RemoteResult 信封 {ok,value|error};
+// - connection.api 面(dsh 0.1.1+):settings.describe() 无参,settings.mutate({ns,ops,...})
+//   单对象参数,返回 {rpcId,result:{ok,value|error}} 信封。
+// 面缺失或形状不完整返回 null,由调用方降级呈现只读原因。
+function unwrapEnvelope(envelope) {
+  if (envelope !== null && typeof envelope === 'object' && envelope.ok === true) return envelope.value
+  if (envelope !== null && typeof envelope === 'object' &&
+      envelope.result !== null && typeof envelope.result === 'object') {
+    if (envelope.result.ok === true) return envelope.result.value
+    return rejectRpc(envelope.result.error)
+  }
+  return rejectRpc(envelope && envelope.error)
+}
+
+function rejectRpc(error) {
+  const rpcError = new Error(error && error.message ? error.message : 'settings RPC 调用失败')
+  rpcError.code = error ? error.code : undefined
+  throw rpcError
 }
 
-// dsh 0.1.2 remote.settings 服务 → 插件内部 settings 面(describe() / mutate(ns, ops, revision))。
-// remote 面缺失或形状不完整返回 null,由调用方降级呈现只读原因。
-export function makeSettingsFace(remote) {
-  if (remote === null || typeof remote !== 'object' ||
-      typeof remote.describe !== 'function' || typeof remote.mutate !== 'function') return null
+export function makeSettingsFace(transport) {
+  if (transport === null || typeof transport !== 'object') return null
+  const typed = typeof transport.describe === 'function' && typeof transport.mutate === 'function'
+  if (typed) {
+    return {
+      describe: async () => unwrapEnvelope(await transport.describe()),
+      mutate: async (ns, ops, expectedRevision) =>
+        unwrapEnvelope(await transport.mutate(ns, ops, expectedRevision)),
+    }
+  }
+  const api = transport.api
+  if (api === null || typeof api !== 'object' ||
+      api.settings === null || typeof api.settings !== 'object' ||
+      typeof api.settings.describe !== 'function' || typeof api.settings.mutate !== 'function') return null
   return {
-    describe: async () => unwrapResult(await remote.describe()),
-    mutate: async (ns, ops, expectedRevision) => unwrapResult(await remote.mutate(ns, ops, expectedRevision)),
+    describe: async () => unwrapEnvelope(await api.settings.describe({})),
+    mutate: async (ns, ops, expectedRevision) =>
+      unwrapEnvelope(await api.settings.mutate({
+        ns,
+        ops,
+        ...(expectedRevision === undefined ? {} : { expectedRevision }),
+      })),
   }
 }
 

package/test/client-boot.test.mjs

@@ -1,6 +1,9 @@
-// client 注入契约 BDD:remote.settings 面的存在性由 cordis 注入门控保证
-// (点分 inject 声明使 fiber 等 namespace 挂载完成后才激活,官方插件同构),
-// apply 内不做面缺失探测——面在 apply 期必然就绪,直接消费。
+// client 注入契约 BDD:inject 按宿主代际二选一——0.1.2+(带 __DSH_BOOT__
+// wire)点分声明 remote.settings 由 cordis 门控等挂载,0.1.1(无 wire)声明
+// 两代基座 remote+connection,settings 传输在 apply 内按面形状异步轮询——
+// 0.1.2+ 的 remote.settings 直返 RemoteResult 信封,0.1.1 的 connection.api
+// 走 HTTP 面({rpcId,result} 信封);面形状由 makeSettingsFace 判定,缺失面
+// 降级只读呈现,不阻塞 fiber。
 // require 桩采用宿主语义:未知模块名 throw(宿主 client-modules 对种子表外
 // 键直接抛错),使顶层硬依赖与可选消费的降级路径都被真实执行。
 
@@ -45,13 +48,130 @@ function loadFactory() {
   return factoryPromise
 }
 
-test('注入契约:inject 声明 remote 基座与 remote.settings 点分面', async () => {
+// apply 的定面轮询(settle→scheduleScan)会在测试结束后的一拍触达 document;
+// 桩 querySelector 恒 null,扫描回调即静默返回,异步尾巴不抛错
+globalThis.document ??= { querySelector: () => null, getElementById: () => null }
+// applyTracked 真实执行 effect fn(其中 new MutationObserver),桩不派发变更
+globalThis.MutationObserver ??= class { observe() {} disconnect() {} }
+
+// cordis effect 语义:注册即执行,返回的 disposer 由宿主持有;测试以
+// applyTracked 持有 disposer,用例结束前统一清算,停掉面轮询的定时器链。
+// 在原对象上临时替换 effect(禁止 spread):spread 会把 getter 展开成
+// 数据属性,面读取计数桩(getter)从此对 apply 内不可见,断言恒真失效
+function applyTracked(entry, ctx) {
+  const disposers = []
+  const userEffect = ctx.effect
+  ctx.effect = (fn, name) => {
+    if (userEffect !== undefined) userEffect(fn, name)
+    disposers.push(fn())
+    return name
+  }
+  try { entry.apply(ctx) } finally {
+    if (userEffect === undefined) delete ctx.effect
+    else ctx.effect = userEffect
+  }
+  return () => { for (const dispose of disposers) dispose() }
+}
+
+// apply 期面已就绪路径走 batches wire 快取;0.1.1 路径走 facePoll。测试环境
+// 无 __DSH_BOOT__,默认全走 0.1.1 分支;带 wire 场景由 wire 测试覆盖
+// 0.1.2+ wire 判据 = batches 批次调度字段(0.1.1 wire 无)
+const BOOT_WIRE = { rev: 'test', batches: [] }
+function withBootWire(value, fn) {
+  const had = Object.prototype.hasOwnProperty.call(globalThis.window, '__DSH_BOOT__')
+  const previous = globalThis.window.__DSH_BOOT__
+  if (value === undefined) delete globalThis.window.__DSH_BOOT__
+  else globalThis.window.__DSH_BOOT__ = value
+  try { return fn() } finally {
+    if (had) globalThis.window.__DSH_BOOT__ = previous
+    else delete globalThis.window.__DSH_BOOT__
+  }
+}
+
+test('注入契约:0.1.2+(wire.batches)点分声明 remote.settings,0.1.1 声明基座', async () => {
   const factory = await loadFactory()
-  const entry = factory(requireOf())
-  assert.deepEqual(entry.inject, ['remote', 'remote.settings'])
+  withBootWire(BOOT_WIRE, () => {
+    const entry = factory(requireOf())
+    assert.deepEqual(entry.inject, ['remote', 'remote.settings'])
+  })
+  withBootWire(undefined, () => {
+    const entry = factory(requireOf())
+    assert.deepEqual(entry.inject, ['remote', 'connection'])
+  })
 })
 
-test('禁用分支清偿:client.js 不再含面缺失探测告警(时序竞态已由门控消除)', () => {
+test('面选择:0.1.1 形态(无 wire)typed 缺失走 connection.api 面', async () => {
+  const factory = await loadFactory()
+  withBootWire(undefined, () => {
+    const effects = []
+    const dispose = applyTracked(factory(requireOf()), {
+      remote: {},
+      connection: { api: { settings: { describe() {}, mutate() {} } } },
+      effect: (fn, name) => effects.push(name),
+    })
+    assert.deepEqual(effects, ['model-capability-editor: models-page injector'])
+    dispose()
+  })
+})
+
+test('面选择:0.1.2+(wire)typed 面挂载完成,apply 期直接消费', async () => {
+  const factory = await loadFactory()
+  withBootWire(BOOT_WIRE, () => {
+    const effects = []
+    const dispose = applyTracked(factory(requireOf()), {
+      remote: { settings: { describe() {}, mutate() {} } },
+      connection: null,
+      effect: (fn, name) => effects.push(name),
+    })
+    assert.deepEqual(effects, ['model-capability-editor: models-page injector'])
+    dispose()
+  })
+})
+
+test('定面轮询:0.1.1 直接走 api 面定面成功;面缺失满窗恒定禁用并停轮询', async (t) => {
+  const factory = await loadFactory()
+  // mock 定时器:轮询/扫描链与 Date.now() 全部确定性推进,不真等超时窗口。
+  // settings 面经 connection.api 属性读取,以 getter 计数锁定"读了多少拍":
+  // 首拍定面 ⇒ 计数 1 且不再增长;恒定禁用 ⇒ 计数随窗口耗尽停止
+  const trackedConnection = (settingsFace) => ({
+    get connection() {
+      this.reads = (this.reads ?? 0) + 1
+      return { api: { settings: settingsFace } }
+    },
+  })
+  t.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
+  withBootWire(undefined, () => {
+    // 场景一(0.1.1 主干路径):api 面可定面 → 首拍定型,零告警,不再读
+    const warnOk = t.mock.method(console, 'warn', () => {})
+    const okConn = trackedConnection({ describe() {}, mutate() {} })
+    const disposeOk = applyTracked(factory(requireOf()), okConn)
+    assert.equal(okConn.reads, 1, 'api 面必须首拍定面')
+    t.mock.timers.tick(1000 + 50)
+    assert.equal(okConn.reads, 1, '定面后不得继续轮询')
+    assert.equal(warnOk.mock.callCount(), 0, 'api 面可定面时不得有降级告警')
+    disposeOk()
+    warnOk.mock.restore()
+    // 场景二(两代皆无):窗口耗尽 → 恒定禁用告警,轮询终止(计数停止增长)
+    t.mock.timers.reset()
+    t.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
+    const warns = []
+    const warnNone = t.mock.method(console, 'warn', (text) => warns.push(text))
+    const noneConn = trackedConnection(undefined)
+    const disposeNone = applyTracked(factory(requireOf()), noneConn)
+    t.mock.timers.tick(1000 + 50)
+    assert.ok(
+      warns.some((text) => text.includes('settings RPC 面不可用')),
+      '两代面皆缺必须留下禁用告警',
+    )
+    const readsAtExhaust = noneConn.reads
+    t.mock.timers.tick(1000 + 50)
+    disposeNone()
+    assert.equal(noneConn.reads, readsAtExhaust, '恒定禁用后轮询必须终止')
+    assert.equal(warns.length, 1, '禁用告警必须只出现一次')
+  })
+})
+
+test('禁用分支清偿:client.js 不再含面缺失探测告警', () => {
   const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
   assert.ok(!source.includes('缺少 remote.settings'), '残留面缺失探测告警分支')
 })
@@ -88,14 +208,29 @@ test('toast 可选消费:模块表有 toast 走 show,缺失降级 console.warn',
   assert.equal(typeof withoutToast.apply, 'function')
 })
 
-test('apply 期面已就绪:settings 面直接消费,注册注入 effect', async () => {
+test('apply 注册注入 effect:两代路径均成立', async () => {
   const effects = []
   const factory = await loadFactory()
   const entry = factory(requireOf())
-  const result = entry.apply({
-    remote: { settings: { describe() {}, mutate() {} } },
-    effect: (fn, name) => effects.push(name),
+  withBootWire(undefined, () => {
+    // 0.1.1:typed 面在场也不被消费(版本排他,轮询只读 connection)
+    let typedReads = 0
+    const remote = {}
+    Object.defineProperty(remote, 'settings', { get() { typedReads += 1; return { describe() {}, mutate() {} } } })
+    const disposeLegacy = applyTracked(entry, { remote, connection: null, effect: (fn, name) => effects.push(name) })
+    assert.equal(typedReads, 0, '0.1.1 路径不得消费 typed 面')
+    disposeLegacy()
+  })
+  withBootWire(undefined, () => {
+    // 两代路径下 effect 注册契约一致
+    const effectsWire = []
+    const dispose = applyTracked(entry, {
+      remote: { settings: { describe() {}, mutate() {} } },
+      connection: null,
+      effect: (fn, name) => effectsWire.push(name),
+    })
+    assert.deepEqual(effectsWire, ['model-capability-editor: models-page injector'])
+    dispose()
   })
-  assert.equal(result, undefined)
   assert.deepEqual(effects, ['model-capability-editor: models-page injector'])
 })

package/test/parity.test.mjs

@@ -24,7 +24,7 @@ function clientLogic() {
       + ' COMPETITOR_MARKERS, effortsToDrafts, draftsToEfforts, isExpressibleEfforts, inputToMode, modeToInput,'
       + ' invalidReasoningLevels, fillDrafts,'
       + ' applyDraft, mergeBaselineModels, detectCompetitorTraces, stashDrafts, restoreDrafts, isModelsTitle,'
-      + ' anchorsBroken, resolveTargetId, unwrapResult, makeSettingsFace, describeNs, modelsOf, findNsEntry,'
+      + ' anchorsBroken, resolveTargetId, unwrapEnvelope, rejectRpc, makeSettingsFace, describeNs, modelsOf, findNsEntry,'
       + ' writeModels, saveModels, draftsFromModels };',
   )
   return factory()
@@ -282,14 +282,14 @@ test('client.js 语法可被 node 解析', () => {
   execFileSync(process.execPath, ['--check', join(PKG_ROOT, 'src', 'client.js')])
 })
 
-// 保存流双副本守卫:client.js 的 unwrapResult/makeSettingsFace/describeNs/modelsOf/
-// writeModels/saveModels/draftsFromModels 全段与 logic.mjs 必须逐字符一致(单文件
-// 格式无法 require,靠此测试防漂移;client 终点 LOGIC-END,logic 侧到文件尾)。
-// 锚点为 `function unwrapResult`:它是全部 RPC 解包路径的唯一入口,副本在旧锚点
-// '// dsh 0.1.2 remote.settings' 之前,不纳入守卫会让解包漂移无任何测试兜底。
+// 保存流双副本守卫:client.js 的 unwrapEnvelope/rejectRpc/makeSettingsFace/describeNs/
+// modelsOf/writeModels/saveModels/draftsFromModels 全段与 logic.mjs 必须逐字符一致
+// (单文件格式无法 require,靠此测试防漂移;client 终点 LOGIC-END,logic 侧到文件尾)。
+// 锚点即 `function unwrapEnvelope` 本身:它是全部 RPC 信封解包路径的唯一入口;
+// 旧锚点 `function unwrapResult` 已随函数重命名废止。
 test('client.js wire 适配与保存流段与 logic.mjs 同源', () => {
   const sectionOf = (source, label) => {
-    const begin = source.indexOf('function unwrapResult')
+    const begin = source.indexOf('function unwrapEnvelope')
     assert.ok(begin >= 0, label + ' 缺少守卫段起点')
     // 终点:client 侧守卫段以 LOGIC-END 收束;logic 侧守卫段即文件尾
     const end = source.indexOf('/* LOGIC-END */')

package/test/wire-face.test.mjs

@@ -1,5 +1,8 @@
-// BDD:dsh 0.1.2 remote.settings 服务面适配 — 官方 RemoteResult 信封 {ok,value|error}
-// 适配为插件内部 RPC 面;保存流经适配层端到端保持冲突重放语义。
+// BDD:settings 传输适配 — 两种宿主形态统一为插件内部 RPC 面:
+// - dsh 0.1.2+ typed remote 面(remote.settings):方法直返 RemoteResult 信封 {ok,value|error}
+// - dsh 0.1.1+ connection.api 面:settings.describe() 无参,settings.mutate({ns,ops,...})
+//   单对象参数,返回 {rpcId,result:{ok,value|error}} 信封
+// 保存流经适配层端到端保持冲突重放语义。
 
 import test from 'node:test'
 import assert from 'node:assert/strict'
@@ -21,6 +24,91 @@ test('适配面:transport 抛错原样上抛,不被吞成假信封', async () =>
   await assert.rejects(() => face.mutate('llm-pi-ai', [], 1), (error) => error === boom)
 })
 
+test('connection.api 面(0.1.1):describe 走 {rpcId,result} 信封', async () => {
+  let calls = 0
+  const face = makeSettingsFace({ api: { settings: {
+    describe: async (payload) => {
+      calls += 1
+      assert.deepEqual(payload, {})
+      return { rpcId: 'r1', result: { ok: true, value: { writable: true, namespaces: [] } } }
+    },
+    mutate: async () => { throw new Error('不应调用') },
+  } } })
+  const value = await face.describe()
+  assert.equal(calls, 1)
+  assert.deepEqual(value, { writable: true, namespaces: [] })
+})
+
+test('connection.api 面(0.1.1):mutate 单对象参数,result.ok 解包', async () => {
+  const calls = []
+  const face = makeSettingsFace({ api: { settings: {
+    describe: async () => ({ rpcId: 'r', result: { ok: true, value: {} } }),
+    mutate: async (payload) => {
+      calls.push(payload)
+      return { rpcId: 'r', result: { ok: true, value: { ns: payload.ns, revision: 8 } } }
+    },
+  } } })
+  const written = await face.mutate('llm-pi-ai', [{ op: 'set', path: ['a'], value: 1 }], 7)
+  await face.mutate('llm-pi-ai', [{ op: 'unset', path: ['b'] }], undefined)
+  assert.deepEqual(calls, [
+    { ns: 'llm-pi-ai', ops: [{ op: 'set', path: ['a'], value: 1 }], expectedRevision: 7 },
+    { ns: 'llm-pi-ai', ops: [{ op: 'unset', path: ['b'] }] },
+  ])
+  assert.deepEqual(written, { ns: 'llm-pi-ai', revision: 8 })
+})
+
+test('connection.api 面:result.ok false 以 code 透传冲突', async () => {
+  const face = makeSettingsFace({ api: { settings: {
+    describe: async () => ({ rpcId: 'r', result: { ok: true, value: {} } }),
+    mutate: async () => ({ rpcId: 'r', result: { ok: false, error: { code: CONFLICT_CODE, message: 'stale' } } }),
+  } } })
+  await assert.rejects(
+    () => face.mutate('llm-pi-ai', [], 1),
+    (error) => error.code === CONFLICT_CODE,
+  )
+})
+
+test('面选择:describe+mutate 双全即 typed 面,api 形状不再探测', async () => {
+  let apiCalls = 0
+  const face = makeSettingsFace({
+    describe: async () => ({ ok: true, value: {} }),
+    mutate: async () => ({ ok: true, value: {} }),
+    api: { settings: { describe: async () => { apiCalls += 1; return {} }, mutate: async () => ({}) } },
+  })
+  await face.describe()
+  assert.equal(apiCalls, 0, 'typed 面命中后不得触达 connection.api')
+})
+
+test('connection.api 端到端:保存流走 HTTP 信封,冲突一次重放成功', async () => {
+  let describeCount = 0
+  let mutateCount = 0
+  const face = makeSettingsFace({ api: { settings: {
+    describe: async () => {
+      describeCount += 1
+      const revision = describeCount === 1 ? 1 : 2
+      return {
+        rpcId: 'r',
+        result: {
+          ok: true,
+          value: {
+            writable: true,
+            namespaces: [{ ns: 'llm-pi-ai', revision, value: { providers: { 'new-api': { models: [{ id: 'auto' }] } } } }],
+          },
+        },
+      }
+    },
+    mutate: async (payload) => {
+      mutateCount += 1
+      if (mutateCount === 1) return { rpcId: 'r', result: { ok: false, error: { code: CONFLICT_CODE, message: 'stale' } } }
+      assert.equal(payload.expectedRevision, 2)
+      return { rpcId: 'r', result: { ok: true, value: { ns: payload.ns, revision: 3 } } }
+    },
+  } } })
+  const result = await saveModels(face, 'new-api', new Map([['auto', draft]]))
+  assert.equal(mutateCount, 2)
+  assert.deepEqual(result.models[0].reasoningEfforts, { high: 'ultra' })
+})
+
 test('makeSettingsFace:remote 缺失或形状不完整返回 null', () => {
   for (const remote of [null, undefined, {}, { describe: () => {} }, { mutate: () => {} }]) {
     assert.equal(makeSettingsFace(remote), null)