dsh-in-hand 1.5.1 → 1.6.0

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 个写路由之后它
 照样通过，是条假绿灯：它证明的是"没这么写"，不是"没有这个能力"）。
 
 ### 手机能选工作区，但选不了任意目录
@@ -330,6 +331,138 @@ dsh plugin --profile web add <你的绝对路径>/dsh-in-hand
 PWA 外壳由中继本地提供（而不是转发上游），这样它不随上游插件的版本变化而失效；
 页面文件与插件共用同一份，避免两边漂移。
 
+## 局域网直连（同一 Wi-Fi）
+
+上面那条路要域名、要 nginx、要一条 `ssh -R` —— 适合"人在外面也想看"。如果手机和电脑
+就在同一个屋子里，还有一条更短的路：**让中继直接监听内网地址，手机连同一个 Wi-Fi
+直连它。**
+
+### 怎么开（中继侧开关）
+
+中继默认只监听回环（`127.0.0.1`），连局域网都到不了，只有隧道能进。开局域网模式就是
+一个开关：在中继目录里放一个空的 `.lan` 标记文件，或者给它设环境变量 `RELAY_LAN=1`，
+它就从 `127.0.0.1` 改为绑定 `0.0.0.0`；删掉标记文件即关闭（这个开关是中继**启动时**
+读的，改完要重启它才生效）。中继自己的
+`/taskwatch/lan` 页面（**不需要令牌，也不含任何凭据**）会列出当前是否已开启、本机可用
+的内网地址和连接步骤。
+
+### 手机怎么进
+
+1. 在跑中继的电脑上打开 `http://127.0.0.1:3099/taskwatch/pair`，页面上会显示一个
+   **6 位配对码**（只有从本机访问才显示）。
+2. 手机连同一个 Wi-Fi，打开 `http://192.168.1.20:3099/taskwatch`（把 `192.168.1.20`
+   换成电脑的内网地址，以中继 `/taskwatch/lan` 列出的为准）。它会进配对页。
+3. 输入那 6 位码即可。配对码 **2 分钟有效、最多试 5 次、只能用一次**；换到的 cookie
+   有效期 30 天，并且每次带着它访问都会滑动续期。
+
+页面右上角那个双入口胶囊也可以在这条路上用（见下一节）。
+
+### 这条路的硬限制
+
+- **`http://` 不是安全上下文。** 装不成 PWA、没有 service worker 离线外壳，摄像头 /
+  麦克风、剪贴板 API 也用不了。页面本身照常能用 —— 但"添加到主屏幕当一个 App 用"
+  这件事只在 HTTPS 那条路上成立。
+- **IP 会随 DHCP 变。** 路由器重新分配地址之后，手机上存的那条
+  `http://192.168.x.x:3099` 就失效了；以中继 `/taskwatch/lan` 当前列出的地址为准。
+- **开启客户端隔离（AP isolation）的 Wi-Fi 连不上。** 那种设置下同一 Wi-Fi 的设备之间
+  互相不可见，手机到不了电脑 —— 这是路由器的行为，不是这条路能绕开的。
+- **出了这个 Wi-Fi 就连不上。** 要外网访问就用上面的隧道那条路。
+
+### 安全提醒
+
+**拿到这条地址 + 配对码，等于拿到你机器上的一个终端。** 手机端能驱动 agent，而 DSH
+默认是 `danger-full-access`。所以：只在自己家、朋友家这类你信得过的网络里开；公司 /
+公共网络的 Wi-Fi 不要常开；不用的时候就删掉 `.lan` 标记文件，让它退回只监听回环。
+
+配对码这一层是刻意收紧的：它一次性，并且只在**本机 `127.0.0.1`** 的页面上显示 ——
+能操作这台电脑的人，才能授权一台手机。
+
+## 连接原理（实现路径）
+
+### 两条路
+
+远端（人在外面）：
+
+```
+手机
+  └─ HTTPS  https://dsh.example.com          （示例域名，不是真实部署）
+       └─ nginx（服务器）                     反向代理：TLS 终止
+            └─ SSH 反向隧道 ssh -R            本机主动连出，不需要公网 IP 与端口映射
+                 └─ 本机中继 127.0.0.1:3099   校验中继令牌，按白名单转发
+                      └─ DSH 上游 127.0.0.1:3080   /taskwatch/*（读 + /taskwatch/chat/* 写）
+```
+
+局域网（同一个 Wi-Fi）：
+
+```
+手机
+  └─ HTTP   http://192.168.1.20:3099/taskwatch   直连中继（中继绑定 0.0.0.0）
+       └─ 同一套 6 位配对码 → 30 天 cookie
+            └─ DSH 上游 127.0.0.1:3080
+```
+
+### 为什么用 SSH 反向隧道
+
+家里的机器通常在 NAT 后面：没有固定公网 IP，也没开入站端口。反向隧道是**本机主动连出**
+到服务器，服务器再顺着这条已经建立的连接把请求送回来 —— 所以不需要公网 IP，也不需要在
+路由器上做端口映射。服务器那一侧只多一个 nginx 反代负责 TLS 终止。
+
+### 令牌和 6 位配对码各解决什么
+
+两段路，两道锁，解的不是同一个问题：
+
+- **中继令牌**（中继侧的 `RELAY_TOKEN`，或它自己生成在 `.token` 里的值）管的是
+  「**服务器 → 本机中继**」这一段：证明这个请求是从被授权的隧道入口进来的。比较是定长
+  的（`timingSafeEqual`），并且令牌不会被转发给上游。
+- **6 位配对码**管的是「**手机 → 中继**」这一段：手机第一次访问时用它换一张 30 天、会
+  滑动续期的 `HttpOnly` cookie。配对码 2 分钟有效、最多试 5 次、只能用一次，并且只在
+  **`127.0.0.1`** 的页面上显示。
+
+### 为什么中继看不出手机在哪个网络
+
+隧道那条路上，请求在中继眼里**来源都是 `127.0.0.1`** —— 它看到的对端是隧道，不是手机。
+所以中继分不清手机是在家里、在 4G，还是在同一个 Wi-Fi 里；同理，HTTPS 页面也没法探测
+`http://` 内网地址（浏览器按混合内容拦掉，IP 主机连"可升级"都不算）。
+
+这就是手机页右上角那个双入口胶囊只能"事后切"、不能"事先测"的原因：
+
+- 胶囊上显示当前走的是哪条路（远端 / 局域网），点一下在 **自动 → 固定局域网 →
+  固定远端** 之间循环，选择记在 `localStorage`。
+- **自动**只用两个信号：这条路刚才通不通、你上次选了哪条。远端路上
+  `GET /taskwatch/upstream-health` 体检失败（隧道或 DSH 挂了）就切局域网（若可用）；
+  局域网路上请求失败（手机离开了 Wi-Fi）就切回远端。能用的那条路不会被主动换掉。
+
+### 换路为什么不重输配对码
+
+换路等于换了一个**源**（`https://…` ↔ `http://192.168.x.x:3099`），而浏览器的 cookie 是
+**按源隔离**的 —— 在远端那条路上换到的 cookie，到了局域网这条路等于不存在。
+
+所以页面点切换时，先向当前这条路的中继要一张凭据：
+
+1. `POST /taskwatch/ticket`（带令牌）→ 中继返回另一条路的 URL，末尾带一次性 `?t=…`；
+2. 手机跳过去，中继兑换这张票：**60 秒有效、兑换即作废、重放无效**，同时给那条路种下
+   cookie；
+3. 于是不用重新输那 6 位配对码。
+
+这三个接口都在中继侧，**中继不在本仓库**：`GET /taskwatch/entries`（入口清单与当前入口）、
+`POST /taskwatch/ticket`（换路凭据）、`GET /taskwatch/upstream-health`（上游体检）。
+详细的实现与部署文档在中继仓库 **`dsh-in-hand-relay`**（该仓库尚未创建，此处只写仓库名）。
+中继没升级时，页面上的胶囊不会出现，其余功能不受影响。
+
+> 注：上面「在外网 / 手机上访问」一节描述的是只转发读路径的只读中继；实际的中继同时
+> 承载 `/taskwatch/chat/*` 的写入口（见上面的路由表）和本节这三个双入口接口。中继代码
+> 不在本仓库。
+
+### 502 排查
+
+看到 502 先分清它从哪一段来，三种情况的处置完全不同：
+
+| 现象 | 断在哪 | 说明 |
+|---|---|---|
+| 服务器 nginx 回的 502 | 隧道那一段 | `ssh -R` 断了，或者本机中继没在跑；重新拉起隧道 / 中继 |
+| 中继回的 502，响应头带 `x-taskwatch-hop: relay` | 中继 → DSH 上游 | 中继自己发的：隧道是通的，但上游 DSH 不可达（回环端口没在监听，或插件没挂载） |
+| 手机上**反复**看到 502 | 手机的 service worker | v1.6.0 之前的 SW 会把那次 502 存成外壳，之后离线导航一直吃它，而服务端早已恢复 —— v1.6.0 起只缓存 2xx，并把 `CACHE` 升到 v13 清掉已存的 502 |
+
 ## 安全边界
 
 - **写入口等于一台终端**。一旦放行 `/taskwatch/chat/send`，能打开这个页面的人就能在
@@ -391,7 +524,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 +535,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) })