dsh-router-core 0.2.0 → 0.3.1

package/src/client/settings-nav-icon.ts

@@ -0,0 +1,55 @@
+/**
+ * 给设置导航里「路由」这一行换掉宿主的默认齿轮。
+ *
+ * 为什么需要这个：DSH 0.1.x 的 `settings.section` 注册**只认 id / order / label
+ * 三个字段**，图标是宿主内部按「内置 id 白名单」选的，插件传不了。所以外部
+ * section 一律拿到通用齿轮（跟「通用设置」「远程访问」同一个）。
+ * 在契约长出 icon 字段之前，只能注册后认领自己的那一行。
+ *
+ * 做法跟 dsh-better-sidebar 的 settings-nav-icon.ts 一致：给自己的行打一个
+ * 属性标记，再由 CSS 用 mask 渲染图标（见 router.css 的
+ * `[data-dsh-router-settings-nav]`）。用 mask + currentColor 是为了跟随
+ * 宿主导航的 hover/active 配色，也保持 16px 的图标节奏。
+ *
+ * 匹配方式：按行的**可见文案**认领（label 可能本地化），且只认 `nav button`，
+ * 碰到同名的别人家 section 不会误伤（我们同时校验它确实在设置面板里）。
+ * 卸载时断开观察并摘掉标记，HMR / 插件热卸载安全。
+ */
+
+/** 打在设置导航按钮上的标记属性。 */
+export const SETTINGS_NAV_MARKER = 'data-dsh-router-settings-nav'
+
+/** 设置面板的导航按钮选择器（宿主结构：dialog 里的 nav）。 */
+const NAV_BUTTON_SELECTOR = '[role="dialog"] nav button'
+
+/**
+ * 持续把标记打在文案等于 `label` 的那一行的身上。
+ * @param label 当前本地化的 section 标题（跟注册时的 label 一致）
+ * @returns 清理函数：断开观察 + 摘掉所有本插件打的标记
+ */
+export function registerSettingsNavIcon(label: string): () => void {
+  let disposed = false
+  const wanted = label.trim()
+
+  const sync = (): void => {
+    if (disposed || wanted === '') return
+    for (const button of document.querySelectorAll<HTMLElement>(NAV_BUTTON_SELECTOR)) {
+      const matches = button.textContent?.trim() === wanted
+      if (matches) button.setAttribute(SETTINGS_NAV_MARKER, '')
+      else button.removeAttribute(SETTINGS_NAV_MARKER)
+    }
+  }
+
+  sync()
+  // 设置面板是按需挂载的：body 子树变动时重新认领
+  const observer = new MutationObserver(sync)
+  observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+
+  return () => {
+    disposed = true
+    observer.disconnect()
+    for (const el of document.querySelectorAll(`[${SETTINGS_NAV_MARKER}]`)) {
+      el.removeAttribute(SETTINGS_NAV_MARKER)
+    }
+  }
+}

package/src/client/settings-section.tsx

@@ -0,0 +1,21 @@
+/**
+ * 「设置 → 路由」页 —— 走 DSH 官方 `settings.section` 座位。
+ *
+ * 容器几何（浏览器实测，不是估的）决定了这里的写法：
+ *   - 内容宽 564px（面板 612 − 左右 padding 24）
+ *   - 外壳 `.VOzbGW_options` 是 `overflow-y:auto` 且高度确定，所以**根节点
+ *     限高**（`height:100%`）+ 内容区自己滚，才能做到「tab 条固定、只有
+ *     内容区滚」。不限高就会退化成整页滚，tab 条跟着滚上去
+ *   - 根节点外面套了一层 `display: contents`（宿主 slot renderer 给的），
+ *     但实测 `height:100%` 能穿过它解析到外壳高度
+ *   - 横向会溢出：老布局是按整个中心栏宽做的，卡片 grid 必须按 564px 排
+ *
+ * 组件本身无状态、无 props：数据全在 RouterView 里自己 fetch。
+ */
+import { RouterView } from './RouterView.tsx'
+
+/** 设置页入口组件。 */
+export function RouterSettingsSection(): JSX.Element {
+  // 不传 onBack：设置面板自带关闭，不需要「返回会话」
+  return <RouterView />
+}

package/src/client/workspace-mount.tsx

@@ -5,9 +5,8 @@
  * other sidebar panels (taskboard / ssh / mnemon) through the shared
  * `dsh-panel-activate` event.
  */
-import { useEffect } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
-import { ROUTER_ACTIVE_ATTR, ROUTER_TITLE, ROUTER_VIEW_SELECTOR } from '../shared.ts'
+import { ROUTER_ACTIVE_ATTR } from '../shared.ts'
 import { RouterView } from './RouterView.tsx'
 import { mountRouterSidebarEntry } from './sidebar-entry.ts'
 import { RouterWorkspaceController } from './workspace-controller.ts'
@@ -24,13 +23,7 @@ function conversationColumn(): HTMLElement | undefined {
 
 function mountPanel(controller: RouterWorkspaceController): () => void {
   function Panel(): JSX.Element {
-    useEffect(() => {
-      // Keep the panel title in the browser tab for orientation, like the
-      // official panels do.
-      const original = document.title
-      document.title = ROUTER_TITLE
-      return () => { document.title = original }
-    }, [])
+    // 不改 document.title：这是宿主页面（会话）的标题，插件不该动它。
     return <RouterView onBack={() => controller.close()} />
   }
 

package/src/index.ts

@@ -18,6 +18,9 @@
  *   PATCH /router/api/keys/:id                toggle key {isActive}
  *   GET  /router/api/settings                 { requireApiKey }
  *   PATCH /router/api/settings                { requireApiKey }
+ *   GET  /router/api/stats                    usage overview (period=today|24h|7d|30d)
+ *   GET  /router/api/stats/chart              usage bar chart buckets
+ *   POST /router/api/stats/clear              reset all usage stats
  *   POST /router/api/suppliers/:id/login                  generate login URL
  *   POST /router/api/suppliers/:id/login/callback         {callbackUrl} → add account
  *   GET  /router/api/suppliers/:id/models                 models with enabled state
@@ -28,7 +31,7 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { join, dirname } from 'node:path'
-import { ROUTER_API_BASE } from './shared.ts'
+import { ROUTER_API_BASE, type RouterPeriod } from './shared.ts'
 import { Router } from './router/index.ts'
 import { RouterAdapter } from './llm/adapter.ts'
 import { KeysStore } from './keys.ts'
@@ -128,7 +131,7 @@ export function apply(rawContext: unknown): void {
   const stateFile = process.env.TW2A_STATE_FILE ?? 'data/state.json'
   const store = new SupplierConfigStore(stateFile)
   const credentials = new CredentialStore(process.env.TW2A_AUTH_DIR ?? join(dirname(stateFile), 'auths'))
-  const router = new Router(stateFile, store)
+  const router = new Router(stateFile, store, log)
 
   const keys = new KeysStore(stateFile)
 
@@ -405,6 +408,51 @@ export function apply(rawContext: unknown): void {
     writeJson(res, 200, { ok: true, requireApiKey: keys.requireApiKey })
   })
 
+  // ---- 概览看板：用量统计 ----
+
+  /** 解析并校验周期参数（不接受任意字符串）。 */
+  const periodOf = (raw: string | null): RouterPeriod => {
+    return raw === '24h' || raw === '7d' || raw === '30d' ? raw : 'today'
+  }
+
+  route(`${ROUTER_API_BASE}/stats`, (req, res) => {
+    const period = periodOf(new URL(req.url ?? '/', 'http://localhost').searchParams.get('period'))
+    const s = router.usage.stats(period)
+    writeJson(res, 200, {
+      ok: true,
+      period,
+      requests: s.requests,
+      okCount: s.ok,
+      failed: s.failed,
+      promptTokens: s.promptTokens,
+      completionTokens: s.completionTokens,
+      cachedTokens: s.cachedTokens,
+      avgDurationMs: s.avgDurationMs,
+      avgTtfbMs: s.avgTtfbMs,
+      estimatedInputs: s.estimatedInputs,
+      estimatedOutputs: s.estimatedOutputs,
+      lifetime: s.lifetime,
+      bySupplier: s.bySupplier,
+      byModel: s.byModel,
+      byRequested: s.byRequested,
+      recent: router.usage.recentList(20),
+    })
+  })
+
+  route(`${ROUTER_API_BASE}/stats/chart`, (req, res) => {
+    const period = periodOf(new URL(req.url ?? '/', 'http://localhost').searchParams.get('period'))
+    writeJson(res, 200, { ok: true, chart: router.usage.chart(period) })
+  })
+
+  route(`${ROUTER_API_BASE}/stats/clear`, async (req, res) => {
+    if (req.method !== 'POST') {
+      writeJson(res, 405, { ok: false, error: 'method not allowed' })
+      return
+    }
+    router.usage.clear()
+    writeJson(res, 200, { ok: true })
+  })
+
   // ---- 设置-模型：Router 提供方（固定卡片，插件注册，不可删）+ 模型目录（= 组合） ----
 
   // llm 缺失时（如测试环境）跳过，不影响 /v1 核心。
@@ -461,7 +509,7 @@ export function apply(rawContext: unknown): void {
   ctx.effect(
     () => () => {
       for (const dispose of disposers.splice(0)) dispose()
-      router.dispose()
+      router.dispose() // 内部会 flush 用量统计（防抖中的计数不能丢）
     },
     'dsh-router: teardown',
   )

package/src/llm/adapter.test.ts

@@ -0,0 +1,108 @@
+/**
+ * RouterAdapter 的 usage 契约测试。
+ *
+ * 这些用例存在的原因：adapter 曾把上游 OpenAI 形态的 usage 原样透传给
+ * dsh-llm，导致会话日志里的 usage 全是 `prompt_tokens`（没有 `inputTokens`）。
+ * 下游 token-meter 读 `usage.inputTokens` 得 `undefined`，累加出 `NaN`，
+ * 投影 schema（`z.number().int().nonnegative()`）校验一抛，整条
+ * `session.history` RPC 失败 —— 用户看到的就是「历史加载失败」。
+ *
+ * 所以这里锁死两条：字段名对、口径对（DISJOINT）。
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { toTokenUsage } from '../router/usage-tokens.ts'
+import { translateSse } from './adapter.ts'
+
+/** 跑一遍 SSE 载荷序列，返回产出的 usage chunk（没有则 undefined）。 */
+async function usageOf(...payloads: string[]): Promise<Record<string, unknown> | undefined> {
+  for await (const chunk of translateSse(payloads)) {
+    if (chunk.type === 'usage') return chunk.usage as unknown as Record<string, unknown>
+  }
+  return undefined
+}
+
+/** 一帧 SSE 的 data 载荷（translateSse 吃的是已剥掉 `data:` 前缀的载荷）。 */
+const frame = (obj: unknown): string => JSON.stringify(obj)
+
+/* ---------------- 契约转换 ---------------- */
+
+test('转换：OpenAI 形态的 prompt_tokens → inputTokens，且扣掉缓存（DISJOINT）', () => {
+  // prompt_tokens 是含缓存的总量；DISJOINT 要求 inputTokens 只算未缓存部分
+  const u = toTokenUsage({ promptTokens: 1000, completionTokens: 50, cachedTokens: 300 })
+  assert.deepEqual(u, { inputTokens: 700, outputTokens: 50, cacheReadTokens: 300 })
+})
+
+test('转换：无缓存时不带 cacheReadTokens 字段（不写无意义的 0）', () => {
+  const u = toTokenUsage({ promptTokens: 100, completionTokens: 20, cachedTokens: 0 })
+  assert.deepEqual(u, { inputTokens: 100, outputTokens: 20 })
+})
+
+test('转换：全 0 返回 null（这一帧没真数据，整个省略 usage）', () => {
+  assert.equal(toTokenUsage({ promptTokens: 0, completionTokens: 0, cachedTokens: 0 }), null)
+  assert.equal(toTokenUsage(null), null)
+})
+
+test('转换：NaN / Infinity / 负数一律归零 —— 绝不把 NaN 写进会话日志', () => {
+  const u = toTokenUsage({
+    promptTokens: Number.NaN,
+    completionTokens: Number.POSITIVE_INFINITY,
+    cachedTokens: -5,
+  })
+  assert.equal(u, null) // 全归零 → 视为无数据
+  const partial = toTokenUsage({ promptTokens: Number.NaN, completionTokens: 42, cachedTokens: 0 })
+  assert.deepEqual(partial, { inputTokens: 0, outputTokens: 42 })
+  for (const v of Object.values(partial ?? {})) assert.ok(Number.isFinite(v), `出现非有限数: ${v}`)
+})
+
+test('转换：缓存比总输入还大时 inputTokens 不为负（上游口径打架也要自洽）', () => {
+  const u = toTokenUsage({ promptTokens: 100, completionTokens: 1, cachedTokens: 500 })
+  assert.equal(u?.inputTokens, 0)
+})
+
+/* ---------------- adapter 出口 ---------------- */
+
+test('出口：流式 SSE 的 usage 必须是 DSH 契约，不是上游原样', async () => {
+  const usage = await usageOf(
+    frame({ choices: [{ delta: { content: 'hi' } }] }),
+    frame({
+      choices: [{ delta: {}, finish_reason: 'stop' }],
+      usage: { prompt_tokens: 236655, completion_tokens: 548, prompt_tokens_details: { cached_tokens: 1024 } },
+    }),
+    '[DONE]',
+  )
+  assert.ok(usage !== undefined, '应当产出 usage chunk')
+  // 字段名对
+  assert.equal(usage.prompt_tokens, undefined, '不能把上游字段原样透传')
+  assert.equal(usage.inputTokens, 235631) // 236655 - 1024
+  assert.equal(usage.outputTokens, 548)
+  assert.equal(usage.cacheReadTokens, 1024)
+  // 每个字段都是有限非负整数（投影 schema 的硬要求）
+  for (const [k, v] of Object.entries(usage)) {
+    assert.ok(Number.isInteger(v) && (v as number) >= 0, `${k} 非法: ${v}`)
+  }
+})
+
+test('出口：上游把 usage 拆在多帧时字段级合并（不是被后一帧覆盖）', async () => {
+  // Claude 系：message_start 给输入，message_delta 只给输出
+  const usage = await usageOf(
+    frame({ choices: [{ delta: { content: 'x' } }], usage: { input_tokens: 100, cache_read_input_tokens: 40 } }),
+    frame({ choices: [{ delta: {}, finish_reason: 'stop' }], usage: { output_tokens: 55 } }),
+    '[DONE]',
+  )
+  assert.equal(usage?.inputTokens, 100, '后一帧没有输入，不能把前一帧的输入冲掉')
+  assert.equal(usage?.outputTokens, 55)
+  assert.equal(usage?.cacheReadTokens, 40)
+})
+
+test('出口：上游发全 0 或垃圾 usage 时省略整个 usage chunk', async () => {
+  const zero = frame({ choices: [{ delta: { content: 'x' } }], usage: { prompt_tokens: 0, completion_tokens: 0 } })
+  assert.equal(await usageOf(zero, '[DONE]'), undefined)
+  const junk = frame({ choices: [{ delta: { content: 'x' } }], usage: { prompt_tokens: 'abc', completion_tokens: null } })
+  assert.equal(await usageOf(junk, '[DONE]'), undefined)
+})
+
+test('出口：上游压根不发 usage 时不硬凑 usage chunk', async () => {
+  const sse = frame({ choices: [{ delta: { content: 'x' }, finish_reason: 'stop' }] })
+  assert.equal(await usageOf(sse, '[DONE]'), undefined)
+})

package/src/llm/adapter.ts

@@ -15,6 +15,7 @@ import {
   type LlmModelInfo,
   type StreamChunk,
 } from '@deepseek-ai/dsh-llm'
+import { mergeUsage, normalizeUsage, toTokenUsage, type UsageTokens } from '../router/usage-tokens.ts'
 
 /** 模型目录来源：组合。 */
 export interface RouterAdapterSource {
@@ -107,15 +108,16 @@ interface OpenBlock {
   name?: string
 }
 
-/** openai SSE payload → DSH StreamChunk 流。 */
-async function* translate(payloads: Iterable<string>): AsyncGenerator<StreamChunk> {
+/** openai SSE payload → DSH StreamChunk 流。导出以便单测锁死 usage 契约。 */
+export async function* translateSse(payloads: Iterable<string>): AsyncGenerator<StreamChunk> {
   let nextIndex = 0
   let textBlock: OpenBlock | undefined
   let reasoningBlock: OpenBlock | undefined
   const toolBlocks = new Map<number, OpenBlock>()
   const order: OpenBlock[] = []
   let pendingFinish: { kind: string; failure?: unknown } | undefined
-  let pendingUsage: unknown
+  /** 攒上游各帧的 usage（归一形态），[DONE] 时统一转成 DSH 契约。 */
+  let accumulated: UsageTokens | null = null
 
   const open = (kind: OpenBlock['kind']): OpenBlock => {
     const block: OpenBlock = { index: nextIndex++, kind, text: '' }
@@ -128,7 +130,15 @@ async function* translate(payloads: Iterable<string>): AsyncGenerator<StreamChun
       for (const block of order) {
         yield { type: 'block-end', index: block.index, block: closeBlock(block) }
       }
-      if (pendingUsage !== undefined) yield { type: 'usage', usage: pendingUsage as never }
+      if (accumulated !== null) {
+        // 转成 DSH 的 TokenUsage：**必须**转，不能把上游的 OpenAI 形态
+        // （prompt_tokens，且含缓存）原样透传。字段名和 DISJOINT 口径都
+        // 对不上，下游 token-meter 读到 undefined 会累加出 NaN，投影
+        // schema 校验一抛就是整条 session.history 失败（「历史加载失败」）。
+        // 转换结果为 null（三个数全 0）则整个省略 usage。见 toTokenUsage。
+        const usage = toTokenUsage(accumulated)
+        if (usage !== null) yield { type: 'usage', usage }
+      }
       const reason = pendingFinish ?? { kind: 'stop' }
       yield {
         type: 'finish',
@@ -188,7 +198,9 @@ async function* translate(payloads: Iterable<string>): AsyncGenerator<StreamChun
       }
       if (typeof choice.finish_reason === 'string') pendingFinish = mapFinishReason(choice.finish_reason)
     }
-    if (chunk.usage !== undefined) pendingUsage = chunk.usage
+    // 上游可能把 usage 拆在多个帧里（Claude 系：先给输入、后给输出），
+    // 所以是字段级 max 合并，不是覆盖。攒着，[DONE] 时统一转契约。
+    if (chunk.usage !== undefined) accumulated = mergeUsage(accumulated, normalizeUsage(chunk.usage))
   }
   throw new LlmError('SSE payload stream ended without [DONE]', 'STREAM_CLOSED')
 }
@@ -268,6 +280,6 @@ export class RouterAdapter extends LlmAdapter {
       throw new LlmError(`dsh-router /v1 returned ${resp.status}: ${detail.slice(0, 200)}`, 'TRANSPORT')
     }
     const text = resp.body === null ? '' : await resp.text()
-    yield* translate(parseSseText(text))
+    yield* translateSse(parseSseText(text))
   }
 }