dsh-in-hand 1.5.1 → 1.5.2

package/README.md

@@ -3,7 +3,7 @@
 **掌上 DSH（dsh-in-hand）** —— 手机端的 DeepSeek Harness，不用装 App。 它起初只是一份只读的**任务监控页**——让你在手机上
 瞄一眼 DSH 有几个任务在跑、有没有事在等你；后来接上了 DSH 自己的会话运行时，长成了手机浏览器里
 的 DSH 客户端：左上角会话列表、右上角新建对话、输入框上方是当前会话的实时指标（轮次 / 步数 /
-token 用量 / 缓存命中率 / 上下文占用），可以直接对话、逐字跟随输出、随时打断。
+token/s / Token 消耗 / 缓存命中率 / 上下文占用），可以直接对话、逐字跟随输出、随时打断。
 
 没有 App：不需要原生代码、不需要打包、不需要上架、不需要装任何东西——浏览器打开，用「添加到
 主屏幕」就当一个 App 用（PWA，只要求 HTTPS 或 localhost）。
@@ -36,8 +36,8 @@ metrics row above the composer.
 渲染成手机上看得懂的样子。目的很朴素——不用坐到电脑前，也能知道它现在在干什么、有没有
 事在等你。
 
-后来发现同一组窄接口能接上 DSH **自己的**会话运行时，于是「写」只用了 4 条路由就够：
-对话、逐字收回复、随时停止、切换会话与模型。**读是监控，写是对话**——两者共用一套令牌和
+后来发现同一组窄接口能接上 DSH **自己的**会话运行时，于是「写」只用了 5 条路由就够：
+附件导入、对话、逐字收回复、随时停止、建会话与切换模型。**读是监控，写是对话**——两者共用一套令牌和
 一条反向隧道，始终不碰 GUI。
 
 所以这里没有 App 可装：没有原生代码、没有打包产物、没有应用商店。手机上进一次「添加到主
@@ -72,7 +72,7 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 
 - **读**：把状态渲染成一份手机看得懂的页面，只放行这一条路径就够。
 - **写**：`/taskwatch/chat/*` 把 DSH **自己的**会话运行时接到手机上 —— 直接对话、
-  逐字收回复、随时停止、切换会话与模型。写入口**只有 4 条**，全部列在下面。
+  逐字收回复、随时停止、切换会话与模型。写入口**只有 5 条**，全部列在下面。
 
 采集面完全通过 `ctx.get(...)` 软读取服务，任何一个服务不存在都只会让对应的那一块
 留空，不会让插件挂载失败。对话那一组同理：拿不到 `sessionController` 时只让这一个
@@ -111,18 +111,19 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 | `/taskwatch/sw.js` | JS | service worker |
 | `/taskwatch/icon-192.png` · `/taskwatch/icon-512.png` | PNG | 图标 |
 
-写（`POST`）—— **只有这 4 条**：
+写（`POST`）—— **只有这 5 条**：
 
 | 路径 | 请求体 | 说明 |
 |---|---|---|
-| `/taskwatch/chat/send` | `{sessionId,text,mode?,timeZone?}` | 给会话发一条消息 |
+| `/taskwatch/chat/upload` | 原始二进制（`sessionId/kind/name/mime` 查询参数） | 导入文件或图片；图片由宿主校验，文件按会话签发 receipt |
+| `/taskwatch/chat/send` | `{sessionId,text,attachments?,mode?,timeZone?}` | 给会话发文字和已上传附件 |
 | `/taskwatch/chat/cancel` | `{sessionId}` | 停止当前这一轮 |
 | `/taskwatch/chat/create` | `{}` 或 `{workspace}` | 新建会话；`workspace` 必须命中 `/taskwatch/chat/workspaces` 列出的路径 |
 | `/taskwatch/chat/model` | `{sessionId,provider,model}` | 切换该会话使用的模型 |
 
 全部注册在 `ctx.webServer` 上，不代理 DSH 自身的 `/api`，也不转发任意路径。
-写入口就只有上面 4 条 —— 契约测试会**正面清点**路由表，增删都会让构建失败
-（早先那条断言写的是"源码里不出现 `method === 'POST'`"。加了 4 个写路由之后它
+写入口就只有上面 5 条 —— 契约测试会**正面清点**路由表，增删都会让构建失败
+（早先那条断言写的是"源码里不出现 `method === 'POST'`"。加了 5 个写路由之后它
 照样通过，是条假绿灯：它证明的是"没这么写"，不是"没有这个能力"）。
 
 ### 手机能选工作区，但选不了任意目录
@@ -391,7 +392,7 @@ PWA 外壳由中继本地提供（而不是转发上游），这样它不随上
 ## 开发
 
 ```sh
-node scripts/check-bundle.mjs   # 客户端 bundle + 宿主契约 + 页面的测试（54 项）
+npm run check                   # bundle、文件边界、上传路由与页面契约测试
 node scripts/make-icons.mjs     # 重新生成图标（自实现 PNG 编码，零依赖）
 node scripts/make-demo.mjs      # 生成 docs/demo.html（假数据，供截图与预览）
 ```
@@ -402,6 +403,10 @@ node scripts/make-demo.mjs      # 生成 docs/demo.html（假数据，供截图
 `name` / `apply` / `inject` 三个导出都在，并把 `cordis.patch.yml`、`exports`、
 `dsh` 元数据一并核对。
 
+`check-uploads.mjs` 会起一个本地 `node:http` 测试服务器，覆盖混合附件发送、会话隔离、
+失败重试、数量 / 总大小限制、错误的请求方法与类型，以及宿主缺少上传服务时的错误提示；
+测试只使用内存 fake 服务，不会连接真实模型。
+
 为什么宿主也要钉住：Cordis 的 `inject` 决定框架等哪些服务就绪后才调用 `apply`。
 `webServer` 的服务是在启动阶段之后才发布的，而 `apply` 在组合期就会被调用——
 只写 `ctx.get('webServer')` 软读会在那一刻拿到 `undefined`，于是整段路由注册被

package/lib/index.js

@@ -184,6 +184,13 @@ export function apply(ctx) {
   const questions = new Map()
   const runningById = new Map()
   const runs = new Map()
+  // 只保存本入口签发的会话内上传记录；大小来自实际字节流而非客户端声明。
+  // 文件仍由宿主 receipt 授权，图片由不透明 token 授权；成功接收后才消费。
+  const pendingUploads = new Map()
+  const UPLOAD_TTL_MS = 30 * 60 * 1000
+  const MAX_PENDING_UPLOADS = 128
+  const MAX_SESSION_UPLOADS = 16
+  let activeUploads = 0
 
   ctx.on('agent/status', (payload) => {
     try {
@@ -743,6 +750,25 @@ export function apply(ctx) {
         req.on('error', reject)
       })
 
+      const readBytes = async (req, limit, signal, measure) => {
+        const chunks = []
+        for await (const chunk of limitedChunks(req, limit, signal, measure)) chunks.push(chunk)
+        return Buffer.concat(chunks)
+      }
+
+      const limitedChunks = async function* (req, limit, signal, measure) {
+        signal.throwIfAborted()
+        for await (const chunk of req) {
+          signal.throwIfAborted()
+          const part = Buffer.from(chunk)
+          measure.bytes += part.length
+          if (measure.bytes > limit) throw new Error('附件不能超过 32 MB')
+          yield part
+        }
+        signal.throwIfAborted()
+        if (req.complete === false) throw new Error('上传已中断')
+      }
+
       const readJson = async (req) => {
         const raw = await readRaw(req, 32 * 1024)
         if (!raw) return {}
@@ -750,6 +776,128 @@ export function apply(ctx) {
         return parsed && typeof parsed === 'object' ? parsed : {}
       }
 
+      const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
+      const pruneUploads = () => {
+        const cutoff = Date.now() - UPLOAD_TTL_MS
+        for (const [key, value] of pendingUploads) {
+          if (!value.sending && value.createdAt <= cutoff) pendingUploads.delete(key)
+        }
+      }
+      const checkUploadRoom = (sessionId) => {
+        pruneUploads()
+        let count = 0
+        for (const value of pendingUploads.values()) if (value.sessionId === sessionId) count++
+        if (pendingUploads.size >= MAX_PENDING_UPLOADS || count >= MAX_SESSION_UPLOADS) {
+          throw new Error('待发送附件过多，请先发送已有附件或稍后再试')
+        }
+      }
+      const rememberUpload = (key, value) => {
+        checkUploadRoom(value.sessionId)
+        pendingUploads.set(key, value)
+      }
+      const requireUploadAgent = async (sessionId) => {
+        const service = chatOf()
+        if (typeof service.resolveAgent !== 'function') throw new Error('宿主缺少附件会话校验服务')
+        const found = await service.resolveAgent(sessionId)
+        if (found && found.agent) return found.agent
+        // Older session-controller builds return Agent directly; current public
+        // API returns { agent } or { error }.
+        if (found && found.error) throw found.error
+        if (found && found.session) return found
+        throw new Error('会话不存在')
+      }
+      const requestLifetime = (req, res) => {
+        const controller = new AbortController()
+        const abort = () => controller.abort(new Error('请求已中断'))
+        const closed = () => { if (!res.writableEnded) abort() }
+        req.on('aborted', abort)
+        res.on('close', closed)
+        return {
+          signal: controller.signal,
+          dispose() { req.off('aborted', abort); res.off('close', closed) },
+        }
+      }
+      const requirePost = (req, res, type) => {
+        if (req.method !== 'POST') {
+          res.setHeader('allow', 'POST')
+          json(res, 405, { error: '只接受 POST' })
+          return false
+        }
+        if (String(req.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase() !== type) {
+          json(res, 415, { error: '请求必须使用 ' + type })
+          return false
+        }
+        return true
+      }
+
+      // 原始二进制上传：文件由 fileUploads 按 Session 暂存，图片由 attachments
+      // 先做图像准入再用一次性 token 交给后续 prompt。请求体硬上限沿用交付文件
+      // 的 32 MiB 边界，名称只作为显示名传给宿主，绝不解释为路径。
+      ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/taskwatch/chat/upload',
+        handler: async (req, res) => {
+          if (!requirePost(req, res, 'application/octet-stream')) return
+          if (Number(req.headers['content-length']) > MAX_BYTES) {
+            json(res, 413, { error: '附件不能超过 32 MB' })
+            return
+          }
+          const lifetime = requestLifetime(req, res)
+          let active = false
+          try {
+            const url = new URL(req.url || '/', 'http://127.0.0.1')
+            const sessionId = asText(url.searchParams.get('sessionId')).trim()
+            const kind = asText(url.searchParams.get('kind')).trim().toLowerCase()
+            const name = asText(url.searchParams.get('name')).trim().slice(0, 200)
+            const mime = asText(url.searchParams.get('mime')).trim().toLowerCase()
+            if (!sessionId) throw new Error('缺少 sessionId')
+            if (kind !== 'image' && kind !== 'file') throw new Error('上传类型无效')
+            if (activeUploads >= 8) throw new Error('正在上传的附件过多，请稍后重试')
+            activeUploads++; active = true
+            checkUploadRoom(sessionId)
+            await requireUploadAgent(sessionId)
+            lifetime.signal.throwIfAborted()
+            const measure = { bytes: 0 }
+            if (kind === 'image') {
+              if (!IMAGE_TYPES.has(mime)) throw new Error('只支持 PNG、JPEG、WEBP、GIF 图片')
+              const store = ctx.get('attachments')
+              if (!store || typeof store.saveImage !== 'function') throw new Error('宿主没有图片附件服务')
+              const ref = await store.saveImage({ data: await readBytes(req, MAX_BYTES, lifetime.signal, measure), mediaType: mime, ...(name ? { name } : {}) })
+              lifetime.signal.throwIfAborted()
+              if (!ref || !Number.isSafeInteger(ref.bytes) || ref.bytes < 0 || ref.bytes > MAX_BYTES) throw new Error('图片处理后超过 32 MB 或附件信息无效')
+              const token = randomUUID()
+              rememberUpload('image:' + token, { sessionId, kind, ref, bytes: Math.max(measure.bytes, ref.bytes), createdAt: Date.now() })
+              json(res, 200, { ok: true, upload: {
+                kind: 'image', token, name: ref.name || name || '图片', bytes: ref.bytes,
+                mime: ref.mediaType, width: ref.width, height: ref.height,
+              } })
+              return
+            }
+            const uploads = ctx.get('fileUploads')
+            if (!uploads || typeof uploads.uploadStream !== 'function') throw new Error('宿主没有文件上传服务')
+            const value = await uploads.uploadStream({
+              sessionId,
+              data: limitedChunks(req, MAX_BYTES, lifetime.signal, measure),
+              signal: lifetime.signal,
+              ...(name ? { name } : {}),
+            })
+            lifetime.signal.throwIfAborted()
+            if (!value || !asText(value.receiptId) || !value.file || value.file.bytes !== measure.bytes) throw new Error('宿主返回了无效的文件上传信息')
+            rememberUpload('file:' + value.receiptId, { sessionId, kind, ref: value.file, bytes: measure.bytes, createdAt: Date.now() })
+            json(res, 200, { ok: true, upload: {
+              kind: 'file', receiptId: String(value.receiptId),
+              name: value.file && value.file.name ? value.file.name : name || '文件',
+              bytes: value.file && value.file.bytes ? value.file.bytes : 0,
+            } })
+          } catch (e) {
+            if (!res.destroyed && !res.writableEnded) json(res, 200, { error: why(e) })
+          } finally {
+            if (active) activeUploads--
+            lifetime.dispose()
+          }
+        },
+      }), 'in-hand: chat upload route')
+
       const ctl = () => new AbortController()
 
       // 会话列表。标题只对**活着的**会话可得（sessionTitle 需要一个 Session 对象），
@@ -880,23 +1028,80 @@ export function apply(ctx) {
         kind: 'exact',
         path: '/taskwatch/chat/send',
         handler: async (req, res) => {
+          if (!requirePost(req, res, 'application/json')) return
+          const lifetime = requestLifetime(req, res)
+          const locked = []
           try {
             const body = await readJson(req)
             const sessionId = asText(body.sessionId)
             const text = asText(body.text)
             if (!sessionId) throw new Error('缺少 sessionId')
-            if (!text.trim()) throw new Error('消息不能为空')
+            if (body.attachments !== undefined && !Array.isArray(body.attachments)) throw new Error('附件格式无效')
+            const uploads = body.attachments || []
+            if (uploads.length > 4) throw new Error('一次最多添加 4 个附件')
+            if (!text.trim() && !uploads.length) throw new Error('消息不能为空')
+            pruneUploads()
+            let totalBytes = 0
+            const seen = new Set()
+            // 先原子校验/锁定整批元数据，再做异步读盘，失败时解锁而不消费。
+            for (const item of uploads) {
+              if (!item || typeof item !== 'object') throw new Error('附件格式无效')
+              const kind = asText(item.kind)
+              if (kind !== 'image' && kind !== 'file') throw new Error('附件类型无效')
+              const key = kind + ':' + asText(kind === 'image' ? item.token : item.receiptId)
+              const record = pendingUploads.get(key)
+              if (!record || record.sessionId !== sessionId || record.kind !== kind) throw new Error('附件已失效或不属于当前会话，请重新上传')
+              if (seen.has(key)) throw new Error('请勿重复添加同一个附件')
+              if (record.sending) throw new Error('附件正在发送，请勿重复提交')
+              seen.add(key)
+              totalBytes += record.bytes
+              if (totalBytes > MAX_BYTES) throw new Error('每条消息的附件总大小不能超过 32 MB')
+              record.sending = true
+              locked.push({ key, record, item })
+            }
+            const content = []
+            if (text.trim()) content.push({ type: 'text', text })
+            const agent = uploads.length ? await requireUploadAgent(sessionId) : null
+            lifetime.signal.throwIfAborted()
+            for (const { record, item } of locked) {
+              if (record.kind === 'file') {
+                const receiptId = asText(item.receiptId)
+                const service = ctx.get('fileUploads')
+                if (!service || typeof service.resolve !== 'function') throw new Error('宿主没有文件上传服务')
+                const ref = service.resolve(agent, receiptId)
+                if (!ref || ref.attachmentId !== record.ref.attachmentId || ref.bytes !== record.bytes) throw new Error('文件上传已失效，请重新上传')
+                content.push({ type: 'file', receiptId })
+                continue
+              }
+              if (record.kind === 'image') {
+                const store = ctx.get('attachments')
+                if (!store || typeof store.readImage !== 'function') throw new Error('宿主没有图片附件服务')
+                const stored = await store.readImage(record.ref, lifetime.signal)
+                lifetime.signal.throwIfAborted()
+                content.push({
+                  type: 'image', mediaType: stored.ref.mediaType,
+                  data: Buffer.from(stored.data).toString('base64'),
+                  ...(stored.ref.name ? { name: stored.ref.name } : {}),
+                })
+                continue
+              }
+            }
             const request = {
               requestId: randomUUID(),
               sessionId,
               mode: body.mode === 'steer' ? 'steer' : 'queue',
-              content: [{ type: 'text', text }],
+              content,
             }
             if (asText(body.timeZone)) request.clientTimeZone = asText(body.timeZone)
-            const value = await chatOf().prompt(request, ctl().signal)
-            json(res, 200, { ok: true, accepted: !!(value && value.accepted) })
+            const value = await chatOf().prompt(request, lifetime.signal)
+            if (!value || value.accepted !== true) throw new Error('宿主未接收消息，请重试')
+            for (const { key, record } of locked) if (pendingUploads.get(key) === record) pendingUploads.delete(key)
+            if (!res.destroyed && !res.writableEnded) json(res, 200, { ok: true, accepted: true })
           } catch (e) {
-            json(res, 200, { error: why(e) })
+            if (!res.destroyed && !res.writableEnded) json(res, 200, { error: why(e) })
+          } finally {
+            for (const { record } of locked) record.sending = false
+            lifetime.dispose()
           }
         },
       }), 'in-hand: chat send route')
@@ -968,14 +1173,10 @@ export function apply(ctx) {
         },
       }), 'in-hand: chat stream route')
 
-      // 会话用量：把「几轮 / 几步 / 多少 token / 缓存命中 / 上下文占用」一次交给手机。
-      //
-      // 数据来源都是**真东西**，不是估算：
-      //   - 轮次与步数直接数会话事件流里的 turn/start 与 step/start；
-      //   - token 走 tokenMeter.measure()（宿主自己的计量服务）；
-      //   - 上下文窗口取自 requestContext()。
-      // tokenMeter 是可选服务：拿不到就**不带这些字段**，让页面显示"暂无"，
-      // 而不是填 0 —— 0 和"不知道"在监控页上是两件完全不同的事。
+      // 会话用量：把「轮 / 步 / token/s / 缓存命中 / token 消耗 / 上下文占用」一次交给手机。
+      // 优先读取 sessionController.projections() 的官方持久投影：它不需要激活会话，
+      // 冷会话也能显示完整数字。旧宿主没有投影时，再退回 live 事件和 tokenMeter，
+      // 但不会把估算值冒充成精确的 token 消耗。
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/taskwatch/chat/usage',
@@ -984,19 +1185,80 @@ export function apply(ctx) {
             const url = new URL(req.url || '/', 'http://127.0.0.1')
             const sessionId = url.searchParams.get('sessionId') || ''
             if (!sessionId) throw new Error('缺少 sessionId')
+            const chat = chatOf()
             const store = ctx.get('sessions')
             const live = store !== undefined ? store.get(sessionId) : undefined
-            if (live === undefined) { json(res, 200, { live: false }); return }
+            let baseline = null
+            if (typeof chat.projections === 'function') {
+              try { baseline = await chat.projections({ sessionId }, ctl().signal) } catch { baseline = null }
+            }
+            if (live === undefined && !baseline) { json(res, 200, { live: false }); return }
             const out = { live: true, turns: 0, steps: 0, toolCalls: 0 }
+            const values = baseline && baseline.values && typeof baseline.values === 'object' ? baseline.values : {}
+            const sessionStats = values.sessionStats
+            const tokenUsage = values.tokenUsage
+            const contextPressure = values.contextPressure
+            const contextBreakdown = values.contextBreakdown
+            let hasSessionStats = false
+            let hasTokenUsage = false
+
+            if (sessionStats && typeof sessionStats === 'object') {
+              hasSessionStats = true
+              out.turns = asNum(sessionStats.turns)
+              out.steps = asNum(sessionStats.steps)
+              out.llmMs = asNum(sessionStats.llmMs)
+              out.toolMs = asNum(sessionStats.toolMs)
+              out.ttftMs = asNum(sessionStats.ttftMs)
+              out.ttftSteps = asNum(sessionStats.ttftSteps)
+              out.decodeMs = asNum(sessionStats.decodeMs)
+              out.decodeTokens = asNum(sessionStats.decodeTokens)
+              if (out.decodeMs > 0 && out.decodeTokens >= 0) {
+                out.tokensPerSecond = out.decodeTokens * 1000 / out.decodeMs
+              }
+            }
+
+            if (tokenUsage && typeof tokenUsage === 'object') {
+              hasTokenUsage = true
+              out.uncachedInputTokens = asNum(tokenUsage.uncachedInputTokens)
+              out.outputTokens = asNum(tokenUsage.outputTokens)
+              out.cacheReadTokens = asNum(tokenUsage.cacheReadTokens)
+              out.cacheWriteTokens = asNum(tokenUsage.cacheWriteTokens)
+            }
+
+            if (contextPressure && typeof contextPressure === 'object') {
+              const projected = typeof contextPressure.projectedTokens === 'number' && isFinite(contextPressure.projectedTokens)
+                ? contextPressure.projectedTokens : null
+              const pressure = typeof contextPressure.pressureTokens === 'number' && isFinite(contextPressure.pressureTokens)
+                ? contextPressure.pressureTokens : null
+              if (projected !== null || pressure !== null) {
+                out.contextTokens = projected === null ? pressure : projected
+              }
+              out.contextWindow = asNum(contextPressure.contextWindow)
+            }
+            if (contextBreakdown && typeof contextBreakdown === 'object') {
+              out.contextBreakdown = {
+                systemTokens: asNum(contextBreakdown.systemTokens),
+                toolsTokens: asNum(contextBreakdown.toolsTokens),
+                messageTokens: asNum(contextBreakdown.messageTokens),
+              }
+            }
+
+            // 这几个字段是前端详情与指标条共用的规范化口径。
+            if (hasTokenUsage) {
+              out.tokenConsumption = out.uncachedInputTokens + out.outputTokens +
+                out.cacheReadTokens + out.cacheWriteTokens
+              const promptTokens = out.uncachedInputTokens + out.cacheReadTokens + out.cacheWriteTokens
+              if (promptTokens > 0) out.cacheHitPercent = 100 * out.cacheReadTokens / promptTokens
+            }
 
             try {
               const events = typeof live.ownEvents === 'function' ? live.ownEvents() : []
               for (const e of events) {
                 if (!e || !e.type) continue
-                if (e.type === 'turn/start') {
+                if (!hasSessionStats && e.type === 'turn/start') {
                   const n = asNum(e.data && e.data.turn)
                   if (n > out.turns) out.turns = n
-                } else if (e.type === 'step/start') out.steps += 1
+                } else if (!hasSessionStats && e.type === 'step/start') out.steps += 1
                 else if (e.type === 'tool/call') out.toolCalls += 1
               }
             } catch (e) { out.eventsError = why(e) }
@@ -1005,30 +1267,45 @@ export function apply(ctx) {
             if (meter !== undefined && typeof meter.measure === 'function') {
               try {
                 const m = meter.measure(live)
-                out.totalTokens = asNum(m.totalTokens)
+                if (!hasTokenUsage) out.totalTokens = asNum(m.totalTokens)
                 out.surfaceTokens = asNum(m.surfaceTokens)
                 const base = m.baseline
-                if (base && base.kind === 'usage' && base.usage) {
+                if (!hasTokenUsage && base && base.kind === 'usage' && base.usage) {
                   out.inputTokens = asNum(base.usage.inputTokens)
                   out.outputTokens = asNum(base.usage.outputTokens)
                   out.cacheReadTokens = asNum(base.usage.cacheReadTokens)
                   out.cacheWriteTokens = asNum(base.usage.cacheWriteTokens)
                   out.reasoningTokens = asNum(base.usage.reasoningTokens)
+                  out.tokenConsumption = out.inputTokens + out.outputTokens + out.cacheReadTokens + out.cacheWriteTokens
+                  const promptTokens = out.inputTokens + out.cacheReadTokens + out.cacheWriteTokens
+                  if (promptTokens > 0) out.cacheHitPercent = 100 * out.cacheReadTokens / promptTokens
                 }
               } catch (e) { out.meterError = why(e) }
             } else {
               out.noTokenMeter = true
             }
 
+            if (typeof out.contextTokens !== 'number' && out.surfaceTokens) out.contextTokens = out.surfaceTokens
+            if (!out.tokensPerSecond && out.decodeMs > 0 && out.outputTokens >= 0) {
+              out.tokensPerSecond = out.outputTokens * 1000 / out.decodeMs
+            }
+            if (out.contextWindow > 0 && typeof out.contextTokens === 'number') {
+              out.contextPercent = Math.min(100, 100 * out.contextTokens / out.contextWindow)
+            }
+
             try {
               const rc = typeof live.requestContext === 'function' ? live.requestContext() : undefined
               if (rc) {
                 out.provider = asText(rc.provider)
                 out.model = asText(rc.model)
-                out.contextWindow = asNum(rc.contextWindow)
+                if (!out.contextWindow) out.contextWindow = asNum(rc.contextWindow)
               }
             } catch (e) { /* 上下文窗口拿不到就不带，页面自然不显示百分比 */ }
 
+            if (out.contextWindow > 0 && typeof out.contextTokens === 'number') {
+              out.contextPercent = Math.min(100, 100 * out.contextTokens / out.contextWindow)
+            }
+
             json(res, 200, out)
           } catch (e) {
             json(res, 200, { error: why(e) })