@mzzsfy/dsh-usage-dash 0.9.0 → 0.10.0

package/README.md

@@ -10,7 +10,7 @@
 - 汇总卡六张:Tokens 用量(服务商总口径)、会话数量、请求数量、最常用模型、平均缓存命中率、活跃天数(恒按天口径,不随视图切换);配置定价规则后 Tokens 卡头部行右侧显示估算费用
 - 活动热力图:GitHub 风格周列×星期行,26 周窗口,五档色阶,悬停明细(配置定价规则后附「费用 ≈」估算行,受「费用显示」开关;费用数据依赖小时桶保留期,仅最近 15 天的天显示,更早的天无该行);仅按天视图展示
 - 缓存命中率曲线:日粒度命中率 + 右侧副轴,并叠加平均生成速度曲线与首 token 延迟曲线(各自单独颜色,读数走悬停;仅含配对数据的槽参与,整图无数据不绘制),悬停显示当前时段命中率、平均生成速度、首 token 延迟与 token 明细(配置定价规则后附当前时段估算费用行,受「费用显示」开关;三粒度趋势图通用)
-- 模型 donut 与列表:按 token 前 5 模型占比环形图(中心为总量);每行名称两行展示(厂商/模型名,其余折叠为「其他」),右侧三排:第一排 token 数·占比,第二排输入输出占比构成(缓存/输入/输出 三段各占该模型 token 总量,缓存=读+写,三段合计 100%,无四桶数据不显示),第三排估算费用·TTFT·生成速度(费用需配置定价规则,TTFT/速度无配对数据不显示),悬停明细含输入/缓存读/缓存写/输出四桶 token 拆分并联动
+- 模型 donut 与列表:按 token 排序的模型占比环形图(中心为总量,模型不超过 5 个时全展示,超过时折叠为前 4 +「其他」,「其他」可展开),每行名称两行展示(厂商/模型名),右侧三排:第一排 token 数·占比,第二排输入输出占比构成(缓存/输入/输出 三段各占该模型 token 总量,缓存=读+写,三段合计 100%,无四桶数据不显示),第三排估算费用·TTFT·生成速度(费用需配置定价规则,TTFT/速度无配对数据不显示),悬停明细含输入/缓存读/缓存写/输出四桶 token 拆分并联动
 - 三粒度堆叠柱状趋势图(数据量大时裁最旧并提示);节头「金额」开关把柱状图从 token 消耗切到金额消耗——柱按模型堆叠估算费用,标题与左轴同步切金额读数(悬停明细保持 token 口径与估算费用行不变,命中率/速度/首 token 延迟曲线不受影响),三粒度通用;开关仅在存在正计价数据时显示(未配置规则或全量未计价时不渲染,避免全零金额柱误导);图例可点击切换显隐:点击单选(仅显示该项,左轴刻度按可见项归一)/再点恢复全部,Ctrl+点击多选,隐藏最后一项无效;悬停明细按当前时段数据展示,零用量模型不显示,全零时段不显示悬浮框
 - 回扫状态行默认隐藏:首次启用自动回扫历史会话,运行中显示进度(常显);右上角为折叠箭头与刷新图标,折叠层内展开扫描异常日志块(逐条:时间/类型/明细,计数即明细条数,上限 200 条超限丢最旧,重建时清空)与「重建」入口(二次确认 3 秒后清库重扫),采集错误常显;折叠且有待读信息(异常日志或写入失败)时箭头带红点提醒,展开后消失;工具栏分主区与右侧操作区,窄宽度时挡位组在主区内换行
 - 会话底栏接管:替换官方信息行为增强版,偏好卡三个开关默认全开——精确缓存命中率(两位小数)、会话 Token 明细(总/命中缓存/未命中缓存/输出)、费用显示(底栏费用项、趋势 tooltip 费用行与回合费用芯片);三开关全关时与官方逐字节一致
@@ -90,3 +90,7 @@ dsh --profile <profile> --no-open --port 9191
 装载本插件需要它在 `dsh.profile.bundles`(`dsh plugin --profile web add @mzzsfy/dsh-usage-dash`);bundles 表变化不支持热重载,需重启 dsh 生效。之后代码改动:宿主半区经 dev-link 自动热重载,client 半区刷新页面即生效。
 
 双语能力经宿主 `locale` 服务声明装载(与官方插件同构);极端旧宿主无该服务时插件整体未激活(cordis 门控,升级宿主即自愈)。
+
+## dsh 版本兼容
+
+三版本(0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.1)兼容通过:激活 live;0.1.7-rc.1 依赖会话用量数据夹具(ENV-003),装载与激活面正常。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-usage-dash",
   "description": "用量统计面板:天/小时/分钟三粒度 token 与请求统计,26 周活跃热力图,会话底栏信息接管与官方动作行回合费用芯片,多条件分时段定价规则与费用估算;复刻自 github.com/HaoyueQin/dsh-usage-statistics-panel,感谢原作者 HaoyueQin",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -20,8 +20,8 @@ const DAY_MAX_SLOTS = 180
 const API_PREFIX = '/api/usage-dash/'
 const ENDPOINTS = { range: 'range', hours: 'hours', minutes: 'minutes', status: 'status', reset: 'reset', restore: 'restore', pricing: 'pricing' }
 
-// 宿主语义 token 之外的插件本地模型色板容量与哨兵
-const GROUP_TOP_COUNT = 5
+// 模型免折叠上限:条目不超它全展示,超过才折叠为 top(上限-1)+Other
+const GROUP_UNFOLDED_MAX = 5
 const OTHER_MODEL = '\u0000other'
 
 const PAD_WIDTH = 2
@@ -603,9 +603,10 @@ const moneyViewOf = (slots, costView) => {
 }
 
 const topWithOther = (ranked) => {
-  const models = ranked.slice(0, GROUP_TOP_COUNT)
-  if (ranked.length > GROUP_TOP_COUNT) {
-    const rest = ranked.slice(GROUP_TOP_COUNT)
+  const folded = ranked.length > GROUP_UNFOLDED_MAX
+  const models = ranked.slice(0, folded ? GROUP_UNFOLDED_MAX - 1 : GROUP_UNFOLDED_MAX)
+  if (folded) {
+    const rest = ranked.slice(models.length)
     // 四桶与费用同源条件挂载:输入条目无该字段(旧形数据/未配价)时哨兵同样不带,防零值假数据
     models.push({
       model: OTHER_MODEL,
@@ -640,7 +641,7 @@ function groupPointSlots(slots) {
 // (预设与自定义挡)用点端点聚合,字段同形;点数据未回为 null,调用方判空不渲染
 const cardsStatsOf = (view, stats, pointView) => (view === 'day' ? stats : pointView)
 
-// 模型用量列表:天视图用预折叠分组,时/分视图折叠点窗口模型(top5+other),点数据未回为 null
+// 模型用量列表:天视图用预折叠分组,时/分视图折叠点窗口模型(超上限折叠 top(上限-1)+other),点数据未回为 null
 const usageModelsOf = (view, grouped, pointView) => (
   view === 'day' ? grouped?.models ?? null : pointView ? topWithOther(pointView.models) : null
 )
@@ -2125,14 +2126,14 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
 .ud-donut-center{font-size:18px;font-weight:600;fill:var(--dsw-alias-label-primary)}
 .ud-donut-label{font-size:11px;fill:var(--dsw-alias-label-tertiary)}
 .ud-models{flex:1 1 260px;min-width:240px;display:flex;flex-direction:column}
-.ud-model-row{display:flex;align-items:center;gap:8px;min-height:48px;padding:2px 4px;border-bottom:1px solid var(--dsw-alias-border-l1)}
+.ud-model-row{display:flex;align-items:center;gap:8px;min-height:46px;padding:1px 4px;border-bottom:1px solid var(--dsw-alias-border-l1)}
 .ud-model-row--expand{cursor:pointer}
 .ud-model-row--expand:hover{background:var(--dsw-alias-interactive-bg-hover)}
 .ud-model-swatch{width:10px;height:10px;border-radius:2px;flex:none}
-.ud-model-id{display:flex;flex-direction:column;gap:1px;min-width:0;flex:1}
+.ud-model-id{display:flex;flex-direction:column;min-width:0;flex:1}
 .ud-model-name{font-size:14px;font-weight:500;color:var(--dsw-alias-label-primary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .ud-model-provider{font-size:12px;color:var(--dsw-alias-label-tertiary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
-.ud-model-values{display:flex;flex-direction:column;align-items:flex-end;gap:1px;font-variant-numeric:tabular-nums;flex:none}
+.ud-model-values{display:flex;flex-direction:column;align-items:flex-end;font-variant-numeric:tabular-nums;flex:none}
 .ud-model-tokens{font-size:12px;color:var(--dsw-alias-label-secondary)}
 .ud-model-io{font-size:11px;color:var(--dsw-alias-label-secondary);white-space:nowrap}
 .ud-model-meta{font-size:11px;color:var(--dsw-alias-label-tertiary);white-space:nowrap}
@@ -2143,8 +2144,9 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
 .ud-model-other--open{grid-template-rows:1fr}
 .ud-model-other-list{overflow:hidden;min-height:0}
 .ud-model-row--sub{min-height:0;padding:4px 4px 4px 28px;background:color-mix(in srgb,var(--dsw-alias-bg-layer-2) 55%,transparent);border-bottom:none}
-.ud-switch{display:inline-flex;align-items:center;cursor:pointer}
-.ud-switch input[type="checkbox"] { position:absolute; opacity:0; width:1px; height:1px; margin:-1px; overflow:hidden; clip:rect(0 0 0 0); }
+.ud-switch{display:inline-flex;align-items:center;cursor:pointer;position:relative}
+/* 透明覆盖 label 而非几何隐藏:聚焦位置即点击位置,防聚焦 scroll-into-view 连锁滚动嵌套滚动容器(弹窗导航被滚走整屏空白) */
+.ud-switch input[type="checkbox"] { position:absolute; inset:0; width:100%; height:100%; margin:0; opacity:0; cursor:pointer; }
 .ud-switch__track{position:relative;width:${SWITCH_TRACK_WIDTH}px;height:${SWITCH_TRACK_HEIGHT}px;border-radius:999px;box-sizing:border-box;flex:none;background:var(--dsw-alias-border-l2);transition:background ${SWITCH_TRANSITION_MS}ms var(--ds-ease-in-out)}
 .ud-switch__thumb{position:absolute;top:${SWITCH_EDGE_INSET}px;left:${SWITCH_EDGE_INSET}px;width:${SWITCH_THUMB_SIZE}px;height:${SWITCH_THUMB_SIZE}px;border-radius:50%;background:var(--dsw-alias-bg-layer-1);transition:transform ${SWITCH_TRANSITION_MS}ms var(--ds-ease-in-out)}
 .ud-switch:not(:has(input[type="checkbox"]:disabled)):hover .ud-switch__track{background:color-mix(in srgb,var(--dsw-alias-border-l2) 85%,var(--dsw-alias-label-tertiary))}
@@ -2292,7 +2294,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
     const colorForModel = (models) => (model) => {
       if (model === OTHER_MODEL) return 'var(--ud-chart-other)'
       const slot = models.findIndex((item) => item.model === model)
-      const rank = Math.min(slot < 0 ? 0 : slot, GROUP_TOP_COUNT - 1) + 1
+      const rank = Math.min(slot < 0 ? 0 : slot, GROUP_UNFOLDED_MAX - 1) + 1
       return `var(--ud-chart-${rank})`
     }
 

package/src/index.js

@@ -55,6 +55,21 @@ const SETTINGS_SCHEMA = schemastery.object({
     .description('定价规则(wire 由 /api/usage-dash/pricing 读写)'),
 })
 
+// 0.1.7 宿主以静态 Config 导出生成设置节表单(maintain 同构);legacy 宿主经
+// settings.register 注册命名空间。根级 volatile 包装:整节 live 表单,节写经
+// loader 原地热更;旧宿主 schemastery 无 volatile 方法,特性检测原样返回
+export const Config = volatileWrap(SETTINGS_SCHEMA)
+
+function volatileWrap(schema) {
+  return typeof schema.volatile === 'function' ? schema.volatile() : schema
+}
+
+// volatile ref 动态解包(get 协议):0.1.7 下 apply 入参 config 为整节单 ref;
+// legacy 宿主 config 为普通对象原样透传
+function unwrapVolatile(value) {
+  return typeof value?.get === 'function' ? value.get() : value
+}
+
 export function apply(ctx, config) {
   const store = sharedStore(ctx.storageDomain)
   const collector = new UsageCollector(ctx, store)
@@ -70,19 +85,44 @@ export function apply(ctx, config) {
   }
   ctx.inject(['settings'], (settingsCtx) => {
     const settings = settingsCtx.settings
-    settings.register(SETTINGS_NAMESPACE, SETTINGS_SCHEMA, { base: config })
-    // 每日本地日首次写入时按保留值清理分钟/小时桶;启动回扫前的触发在下方回扫入口
-    store.retentionDays = () =>
-      settings.get(SETTINGS_NAMESPACE)?.minuteRetentionDays ?? DEFAULT_MINUTE_RETENTION_DAYS
+    // legacy(≤0.1.6)方法面:register/get/update/describe 命名空间语义
+    if (typeof settings.get === 'function' && typeof settings.register === 'function') {
+      settings.register(SETTINGS_NAMESPACE, SETTINGS_SCHEMA, { base: config })
+      // 每日本地日首次写入时按保留值清理分钟/小时桶;启动回扫前的触发在下方回扫入口
+      store.retentionDays = () =>
+        settings.get(SETTINGS_NAMESPACE)?.minuteRetentionDays ?? DEFAULT_MINUTE_RETENTION_DAYS
+      pricing.active = true
+      pricing.rules = () => settings.get(SETTINGS_NAMESPACE)?.pricing?.rules ?? []
+      // revision 取 describe 中本 ns 描述符,settings 任何写入都会自增
+      pricing.revision = () =>
+        settings.describe().find((descriptor) => descriptor.ns === SETTINGS_NAMESPACE)?.revision ?? 0
+      pricing.replace = async (rules) => {
+        // update 深合并下数组整体替换,不动 minuteRetentionDays 用户层
+        await settings.update(SETTINGS_NAMESPACE, { pricing: { rules } })
+        return settings.get(SETTINGS_NAMESPACE)?.pricing?.rules ?? []
+      }
+      return
+    }
+    // 0.1.7+ 形态:静态 Config 导出生成节表单。关闭原生自动页(maintain 同构),
+    // 读经 apply 入参 config 整节解包,写经 configEditor.edit(fiber.entry 与命名空间
+    // 解耦),revision 读 describe 按条目 id 定位(0.1.7 描述符以 entry.options.id 为 ns)
+    if (typeof settings.configure === 'function') {
+      settingsCtx.effect(() => settings.configure({ auto: false }, ctx.fiber))
+    }
+    store.retentionDays = () => unwrapVolatile(config)?.minuteRetentionDays ?? DEFAULT_MINUTE_RETENTION_DAYS
     pricing.active = true
-    pricing.rules = () => settings.get(SETTINGS_NAMESPACE)?.pricing?.rules ?? []
-    // revision 取 describe 中本 ns 描述符,settings 任何写入都会自增
+    pricing.rules = () => unwrapVolatile(config)?.pricing?.rules ?? []
     pricing.revision = () =>
-      settings.describe().find((descriptor) => descriptor.ns === SETTINGS_NAMESPACE)?.revision ?? 0
+      settings.describe?.().find((descriptor) => descriptor.ns === ctx.fiber?.entry?.options?.id)?.revision ?? 0
     pricing.replace = async (rules) => {
-      // update 深合并下数组整体替换,不动 minuteRetentionDays 用户层
-      await settings.update(SETTINGS_NAMESPACE, { pricing: { rules } })
-      return settings.get(SETTINGS_NAMESPACE)?.pricing?.rules ?? []
+      const editor = ctx.get('configEditor')
+      const entry = ctx.fiber?.entry
+      if (!editor || typeof editor.edit !== 'function' || !entry) {
+        throw new Error('usage-dash: configEditor inactive')
+      }
+      // change 回调整体替换 pricing 节,不动 minuteRetentionDays 用户层
+      await editor.edit(entry, (current) => ({ ...current, pricing: { rules } }))
+      return unwrapVolatile(config)?.pricing?.rules ?? []
     }
   })
   const bootScan = async () => {

package/test/client.test.mjs

@@ -420,7 +420,7 @@ test('空态判定仅四项全零成立', () => {
   assert.equal(isEmptyRange({ tokens: 0, cacheHit: 0, requests: 0, turns: 3 }), false)
 })
 
-test('groupStats 折叠 top5 之外为其他哨兵并归并逐日', () => {
+test('groupStats 折叠超免折叠上限条目为其他哨兵并归并逐日', () => {
   const stats = {
     models: [
       { model: 'p/m1', tokens: 500 },
@@ -436,8 +436,8 @@ test('groupStats 折叠 top5 之外为其他哨兵并归并逐日', () => {
     ],
   }
   const grouped = groupStats(stats)
-  assert.deepEqual(grouped.models.map((m) => m.model), ['p/m1', 'p/m2', 'p/m3', 'p/m4', 'p/m5', OTHER_MODEL])
-  assert.equal(grouped.models[5].tokens, 50)
+  assert.deepEqual(grouped.models.map((m) => m.model), ['p/m1', 'p/m2', 'p/m3', 'p/m4', OTHER_MODEL])
+  assert.equal(grouped.models[4].tokens, 100 + 50)
   assert.deepEqual(grouped.daily[0].byModel, { 'p/m1': 400, 'p/m2': 500, [OTHER_MODEL]: 100 })
   assert.deepEqual(grouped.daily[1].byModel, { 'p/m3': 300, [OTHER_MODEL]: 250 })
 })
@@ -460,8 +460,8 @@ test('groupPointSlots 窗口模型超上限折叠其他', () => {
   ]
   const grouped = groupPointSlots(slots)
   assert.equal(grouped.models.at(-1).model, OTHER_MODEL)
-  assert.equal(grouped.models.at(-1).tokens, 1)
-  assert.deepEqual(grouped.daily[0].byModel, { m1: 1, m2: 1, m3: 1, m4: 1, m6: 1, [OTHER_MODEL]: 1 })
+  assert.equal(grouped.models.at(-1).tokens, 1 + 1)
+  assert.deepEqual(grouped.daily[0].byModel, { m1: 1, m2: 1, m3: 1, m6: 1, [OTHER_MODEL]: 1 + 1 })
 })
 
 test('cardsStatsOf 天视图用 range 聚合,时/分视图用点聚合,点未回为 null', () => {
@@ -485,9 +485,9 @@ test('usageModelsOf 天视图用预折叠分组,时/分视图折叠点窗口模
     { model: 'p/m6', tokens: 1 },
   ]
   const folded = usageModelsOf('hour', null, { models: ranked })
-  assert.equal(folded.length, 6)
+  assert.equal(folded.length, 5)
   assert.equal(folded.at(-1).model, OTHER_MODEL)
-  assert.equal(folded.at(-1).tokens, 1)
+  assert.equal(folded.at(-1).tokens, 1 + 1)
   // 空窗口契约:返回空数组渲染空环(与天视图空数据行为一致),非 null 隐藏
   assert.deepEqual(usageModelsOf('minute', null, { models: [] }), [])
   assert.equal(usageModelsOf('minute', null, null), null)
@@ -873,14 +873,14 @@ test('groupStats 哨兵折叠四桶求和,top 模型四桶透传', () => {
   const grouped = groupStats(stats)
   assert.equal(grouped.models[0].inputTokens, 300)
   assert.equal(grouped.models[0].outputTokens, 200)
-  assert.deepEqual(grouped.models[5], {
+  assert.deepEqual(grouped.models[4], {
     model: OTHER_MODEL,
-    tokens: 50,
-    inputTokens: 10,
-    outputTokens: 30,
+    tokens: 100 + 50,
+    inputTokens: 60 + 10,
+    outputTokens: 40 + 30,
     cacheReadTokens: 5,
     cacheWriteTokens: 5,
-    items: [stats.models[5]],
+    items: [stats.models[4], stats.models[5]],
   })
 })
 
@@ -894,7 +894,7 @@ test('groupStats 哨兵费用同源:无 cost 输入不挂 cost,有 cost 求和',
     { model: 'p/m5', tokens: 100 },
     { model: 'p/m6', tokens: 50 },
   ], daily: [] })
-  assert.equal('cost' in bare.models[5], false)
+  assert.equal('cost' in bare.models[4], false)
   const priced = groupStats({ models: [
     { model: 'p/m1', tokens: 500, cost: 1 },
     { model: 'p/m2', tokens: 400, cost: 2 },
@@ -904,7 +904,7 @@ test('groupStats 哨兵费用同源:无 cost 输入不挂 cost,有 cost 求和',
     { model: 'p/m6', tokens: 50, cost: 16 },
     { model: 'p/m7', tokens: 25, cost: 32 },
   ], daily: [] })
-  assert.equal(priced.models[5].cost, 16 + 32)
+  assert.equal(priced.models[4].cost, 8 + 16 + 32)
 })
 
 test('groupStats 哨兵保留其他模型明细供展开与提示', () => {
@@ -920,9 +920,26 @@ test('groupStats 哨兵保留其他模型明细供展开与提示', () => {
     daily: [],
   }
   const grouped = groupStats(stats)
-  assert.deepEqual(grouped.models[5].items, [{ model: 'p/m6', tokens: 50 }])
+  // Given 超过免折叠上限 When 折叠 Then 保留 top4,哨兵在末位并携带其余明细
+  assert.deepEqual(grouped.models[4].items, [{ model: 'p/m5', tokens: 100 }, { model: 'p/m6', tokens: 50 }])
   // Given 旧形条目无四桶 When 折叠 Then 哨兵不合成零值四桶,与 top 条目降级形态一致
-  assert.equal('inputTokens' in grouped.models[5], false)
+  assert.equal('inputTokens' in grouped.models[4], false)
+})
+
+test('groupStats 条目不超免折叠上限时全展示', () => {
+  const stats = {
+    models: [
+      { model: 'p/m1', tokens: 500 },
+      { model: 'p/m2', tokens: 400 },
+      { model: 'p/m3', tokens: 300 },
+      { model: 'p/m4', tokens: 200 },
+      { model: 'p/m5', tokens: 100 },
+    ],
+    daily: [],
+  }
+  const grouped = groupStats(stats)
+  assert.equal(grouped.models.length, 5)
+  assert.equal(grouped.models.some((item) => item.model === OTHER_MODEL), false)
 })
 
 test('groupStats 逐日保留其他明细映射供 tooltip', () => {

package/test/settings-inject.test.mjs

@@ -0,0 +1,237 @@
+// settings 注入集成测试:apply 的 pricing 门面双形分派(legacy 方法面 / 0.1.7
+// 静态 Config + configEditor 面)。stub ctx 装载真实 src/index.js,经捕获的
+// /api/usage-dash/pricing 路由驱动门面,验证激活与读写链路。
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { Readable } from 'node:stream'
+
+const { apply } = await import('../src/index.js')
+
+const PATH_PRICING = '/api/usage-dash/pricing'
+const DEFAULT_MINUTE_RETENTION_DAYS = 7
+
+const RULE = {
+  model: 'default/deepseek-chat',
+  currency: '¥',
+  price: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0 },
+  conditions: [],
+}
+
+// sharedStore 单例按 storageDomain 缓存:每例独立 domain 防串扰;域 open 缺席时
+// store 走内存降级,单测无落盘
+function makeDomain() {
+  return { open: async () => ({}) }
+}
+
+function makeRes() {
+  return {
+    statusCode: null,
+    body: null,
+    writeHead(status) { this.statusCode = status },
+    end(body) { this.body = body },
+  }
+}
+
+function makeReq({ url, method = 'POST', headers = {}, body } = {}) {
+  const req = new Readable({ read() {} })
+  req.method = method
+  req.url = url
+  req.headers = headers
+  if (body !== undefined) req.push(body)
+  req.push(null)
+  return req
+}
+
+const invoke = async (routes, path, reqOptions = {}) => {
+  const route = routes.get(path)
+  assert.ok(route, `route ${path} 未注册`)
+  const res = makeRes()
+  await route.handler(makeReq({ url: path, ...reqOptions }), res)
+  return res
+}
+
+const invokeJson = (routes, path, { headers, payload, ...rest } = {}) =>
+  invoke(routes, path, {
+    headers: { 'content-type': 'application/json', ...headers },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+    ...rest,
+  })
+
+// legacy 方法面桩(≤0.1.6 SettingsProvider):register/get/update/describe 命名空间语义
+function makeLegacySettings(store = {}) {
+  let revision = 0
+  return {
+    register() {},
+    get: () => store,
+    update: async (_ns, patch) => {
+      const pricing = patch.pricing
+      if (pricing) store.pricing = { ...(store.pricing ?? {}), ...pricing }
+      if (patch.minuteRetentionDays !== undefined) store.minuteRetentionDays = patch.minuteRetentionDays
+      revision += 1
+    },
+    describe: () => [{ ns: 'usage-dash', revision }],
+  }
+}
+
+// 0.1.7 形态桩:settings 无 register/get(configure/describe 在),configRef 为整节
+// 单 ref 桩,configEditor 桩合并写回 configStore
+function makeRc17({ configStore = {}, configEditorAvailable = true, withRoutes = true } = {}) {
+  const routes = new Map()
+  const editCalls = []
+  const configRef = { get: () => ({ ...configStore }) }
+  const settingsService = {
+    configure: (presentation, owner) => { return () => {} },
+    describe: () => [{ ns: 'usage-dash', revision: configStore.__revision ?? 0 }],
+  }
+  const configEditor = {
+    async edit(entry, change) {
+      editCalls.push(entry)
+      const next = change({ ...configStore }, {})
+      for (const key of Object.keys(next)) configStore[key] = next[key]
+      configStore.__revision = (configStore.__revision ?? 0) + 1
+    },
+  }
+  const pendingInjects = []
+  const ctx = {
+    on() {},
+    logger: { warn() {} },
+    fiber: { entry: { options: { id: 'usage-dash', name: '@mzzsfy/dsh-usage-dash' } } },
+    get(name) {
+      if (name === 'settings') return settingsService
+      if (name === 'configEditor') return configEditorAvailable ? configEditor : undefined
+      if (name === 'storageDomain') return makeDomain()
+      return undefined
+    },
+    effect(fn) { fn() },
+    inject(_deps, fn) { pendingInjects.push(fn) },
+    webServer: {
+      register(route) {
+        routes.set(route.path, route)
+        return () => routes.delete(route.path)
+      },
+    },
+  }
+  return {
+    ctx,
+    routes,
+    configRef,
+    configStore,
+    editCalls,
+    activateSettings: () => {
+      for (const fn of pendingInjects.splice(0)) {
+        fn({
+          settings: settingsService,
+          interval: () => {},
+          // 注入上下文的 effect 桩:0.1.7 分支经它注册 configure 装配
+          effect(stubEffect) { stubEffect() },
+        })
+      }
+    },
+  }
+}
+
+test('Config 导出契约:根级 volatile 包装,validate 产整节单 ref,默认值对拍', async () => {
+  const mod = await import('../src/index.js')
+  assert.ok(mod.Config, 'Config 导出必须在场')
+  const resolved = mod.Config['~standard'].validate({})
+  assert.equal(resolved.issues, undefined)
+  const section = resolved.value.get()
+  assert.equal(section.minuteRetentionDays, DEFAULT_MINUTE_RETENTION_DAYS)
+  // pricing 缺省对象校验补全:rules 数组缺省为空
+  assert.deepEqual(section.pricing?.rules ?? [], [])
+})
+
+test('0.1.7 形态:settings 激活即门面生效,GET 读 configRef,POST 经 configEditor.edit 整节替换', async () => {
+  // Given configRef 携带用户值 + 路由捕获
+  const rc = makeRc17({ configStore: { minuteRetentionDays: 7, pricing: { rules: [] } } })
+  apply(rc.ctx, rc.configRef)
+  // When 激活 settings 注入
+  rc.activateSettings()
+  // Then GET pricing 回读 configRef 节值
+  const read = await invoke(rc.routes, PATH_PRICING, { method: 'GET' })
+  const readParsed = JSON.parse(read.body)
+  assert.equal(read.statusCode, 200)
+  assert.deepEqual(readParsed.value.rules, [])
+  // When POST 合法规则
+  const saved = await invokeJson(rc.routes, PATH_PRICING, { payload: { rules: [RULE] } })
+  // Then edit 定位本条目,pricing 整节替换,回读新值,revision 自增
+  const savedParsed = JSON.parse(saved.body)
+  assert.equal(saved.statusCode, 200)
+  assert.equal(savedParsed.ok, true)
+  assert.equal(rc.editCalls.length, 1)
+  assert.equal(rc.editCalls[0].options.id, 'usage-dash')
+  assert.deepEqual(rc.configStore.pricing.rules, [RULE])
+  assert.equal(rc.configStore.minuteRetentionDays, 7, 'minuteRetentionDays 用户层不动')
+  assert.deepEqual(savedParsed.value.rules, [RULE])
+  assert.equal(savedParsed.value.revision, 1)
+})
+
+test('0.1.7 形态:configEditor 缺失即 POST 拒绝,GET 回读不受影响', async () => {
+  // Given configEditor 服务缺席
+  const rc = makeRc17({ configEditorAvailable: false })
+  apply(rc.ctx, rc.configRef)
+  rc.activateSettings()
+  // When POST 写规则
+  const saved = await invokeJson(rc.routes, PATH_PRICING, { payload: { rules: [RULE] } })
+  // Then ok:false 错误响应,进程存活(测试走完即证)
+  const savedParsed = JSON.parse(saved.body)
+  assert.equal(savedParsed.ok, false)
+  // When GET 回读
+  const read = await invoke(rc.routes, PATH_PRICING, { method: 'GET' })
+  // Then 仍回 configRef 当前值
+  assert.equal(read.statusCode, 200)
+})
+
+test('0.1.7 形态:configure 在场即关闭原生自动页,register 缺失不抛错', () => {
+  // Given configure 捕获桩
+  const rc = makeRc17()
+  const configureCalls = []
+  rc.ctx.get('settings').configure = (presentation, owner) => { configureCalls.push({ presentation, owner }); return () => {} }
+  // When apply + 激活
+  apply(rc.ctx, rc.configRef)
+  rc.activateSettings()
+  // Then 关闭自动页且 owner 为本插件 fiber
+  assert.equal(configureCalls.length, 1)
+  assert.deepEqual(configureCalls[0].presentation, { auto: false })
+})
+
+// 独立 legacy 用例:register/get/update 命名空间面行为与现状全同
+test('legacy 形态:settings 激活即门面生效,replace 经命名空间 update,revision 经 describe', async () => {
+  const routes = new Map()
+  const store = {}
+  const settingsService = makeLegacySettings(store)
+  const pendingInjects = []
+  const ctx = {
+    on() {},
+    logger: { warn() {} },
+    get(name) {
+      if (name === 'settings') return settingsService
+      if (name === 'storageDomain') return makeDomain()
+      return undefined
+    },
+    effect(fn) { fn() },
+    inject(_deps, fn) { pendingInjects.push(fn) },
+    webServer: {
+      register(route) {
+        routes.set(route.path, route)
+        return () => routes.delete(route.path)
+      },
+    },
+  }
+  apply(ctx, {})
+  for (const fn of pendingInjects.splice(0)) {
+    fn({ settings: settingsService, interval: () => {}, effect(f) { f() } })
+  }
+  // GET 回读命名空间存储值
+  const read = await invoke(routes, PATH_PRICING, { method: 'GET' })
+  assert.equal(read.statusCode, 200)
+  // POST 合法规则经 update 落命名空间
+  const saved = await invokeJson(routes, PATH_PRICING, { payload: { rules: [RULE] } })
+  const savedParsed = JSON.parse(saved.body)
+  assert.equal(savedParsed.ok, true)
+  assert.deepEqual(store.pricing.rules, [RULE])
+  assert.deepEqual(savedParsed.value.rules, [RULE])
+  assert.equal(savedParsed.value.revision, 1)
+})
+