@orderg-x/dsh-video-preview 0.4.1 → 0.5.0

package/README.md

@@ -14,13 +14,15 @@
 
 让 DSH（DeepSeek Harness）的对话流里直接播放本地视频 / 音频：模型录屏、转码、配音生成的文件，回合结束时播放器自动出现在回复正下方——Claude 桌面端 / Codex 同款位置，不用点任何东西，也不用模型专门调工具。说一句「播一下 ~/Movies/a.mp4」也行。
 
-> **一句话**：DeepSeek Harness（DSH）插件，在对话里直接播放本地视频和音频。模型录屏、转码、配音做出来的文件，播放器自动出现在回复下面；别的文件用 `play_video` 工具播。
+模型自己也能「看」：`look_video` 按时间截几帧拼成一张图交给模型，顺便量声音、找黑屏、查手机能不能播——做完视频它能自己检查，你说「不对」时它能看到你说的是哪一段。
+
+> **一句话**：DeepSeek Harness（DSH）插件，在对话里直接播放本地视频和音频。模型录屏、转码、配音做出来的文件，播放器自动出现在回复下面；别的文件用 `play_video` 工具播；模型用 `look_video` 自己看画面、听声音。
 >
 > **什么时候用**：「录个屏」「把视频转成 mp4」「生成一段配音」之后，想直接在对话里看、听。
 >
 > **安装**：`dsh plugin add @orderg-x/dsh-video-preview`（npm 包），重启 DSH。
 >
-> **English:** a DeepSeek Harness (DSH) plugin that plays local video and audio inline in the chat. Files the model makes (screen recordings, transcodes, voiceovers) get a player under its reply automatically, and the `play_video` tool plays any other file. Install with the `dsh plugin add` command above, then restart DSH.
+> **English:** a DeepSeek Harness (DSH) plugin that plays local video and audio inline in the chat. Files the model makes (screen recordings, transcodes, voiceovers) get a player under its reply automatically, and the `play_video` tool plays any other file. The `look_video` tool lets the model see a video itself: a contact sheet of frames, plus checks for silence, black frames and phone compatibility. Install with the `dsh plugin add` command above, then restart DSH.
 
 ![demo](assets/demo.gif)
 
@@ -72,6 +74,24 @@ DSH 的消息渲染块只有 text / image / file / table，**没有 video**，
 | `autoplay` | 否 | 自动播放（浏览器通常会拦） |
 | `loop` | 否 | 循环播放 |
 
+## 模型自己看视频（look_video）
+
+模型看不了视频文件本身，`look_video` 替它看：
+
+- **截帧拼图**：按时长均匀截 4–12 帧，拼成一张图交给模型，每格标时间；也可以只看一段（`from` / `to`），或者要某几刻的大图（`at`，最多 6 张）
+- **听声音**：整段几乎没声、开头 / 结尾 / 中间没声、声音太小、爆音（削波）、只有一边声道
+- **看画面**：黑屏（第一帧黑会让封面变黑）、整段画面没动、中间一大段卡住
+- **手机能不能播**：读 mp4 / mov 文件头（不解码），查编码（H.264 10bit / 4:4:4、hev1、AC-3、ALAC……）、文件头在末尾（网页要下完才能播）、超过 4K、没录完；有问题给出 ffmpeg 改法
+
+怎么做的：在本机一个看不见的 Chrome / Edge 里打开视频截帧、解码声音（和设计工作台的体检同一套），看一次一秒左右。没装 Chrome / Edge 时只给文件头信息。
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `path` | 是 | 本地文件路径（视频或音频） |
+| `at` | 否 | 要看大图的时间点，例如 `["0:12", "1:05.5"]` |
+| `from` / `to` | 否 | 只看这一段 |
+| `frames` | 否 | 拼图里截几帧（默认按时长，最多 16） |
+
 ## 能播什么
 
 DSH 的播放器是 Chromium 内核，能播什么由它决定：
@@ -109,12 +129,17 @@ v0.3.0 之前的版本只看 cookie 名字，网页能伪造 cookie 读到任意
             │
             └─append deliverables/presented 事件（官方 present 工具同款通道）
 自动    session/event 收集这一轮的路径 → agent/turn-stopping 时挑出新文件 → 同一条通道
+看视频  look_video ──读文件头（probe）──▶ 临时本机服务（随机口令、只收本机、Range）
+            └─无头 Chrome / Edge 截帧 + 解码声音 ──▶ 拼图存进 DSH 附件库，图和体检结果一起交给模型
 路由    /dsh-video-preview/media    签名 token · HTTP Range 流式（大文件不进内存）
         /dsh-video-preview/preview  DSH 登录态 · 供侧边栏 / 回复下方的播放器
 客户端  turnTail 槽 / documentPreviews 渲染器 / toolview 槽
 ```
 
 - `lib/index.js` —— 服务端：工具 + deliverables 事件 + 两条流式路由（读盘出错只断当前请求，不会带崩 DSH）
+- `lib/look.js` —— look_video：取帧时间、浏览器里截帧拼图和量声音、声音 / 画面的问题、给模型的字
+- `lib/probe.js` —— 读 mp4 / mov 的盒子（不解码）：编码、时长、帧率、旋转、文件头位置，手机兼容规则
+- `lib/browser.js` —— 无头 Chrome / Edge（CDP 管道，闲置自动关）
 - `lib/auto-present.js` —— 自动播放：挖路径、挑新文件、回合收尾前呈现（回合结束后才 append 的话，界面要重开会话才刷出来）
 - `lib/client.js` —— 客户端：回复下方播放器 / 侧边栏预览 / 工具块兜底 / 出错诊断（`exports.inject` 是客户端**短服务名**，写包名会一直 pending）
 - `locale/*.json`、`icon.svg` —— DSH 插件页的卡片标题、说明和图标
@@ -126,12 +151,15 @@ v0.3.0 之前的版本只看 cookie 名字，网页能伪造 cookie 读到任意
 node test/test-routes.mjs   # 把门、Range、HEAD、读盘出错、工具的格式提示
 node test/test-client.mjs   # 三个挂载点、视频卡 / 音频条、折叠、出错诊断
 node test/test-auto.mjs     # 自动播放：新 / 老文件、正文优先、各种路径写法、不重复、重放不动手
+node test/test-look.mjs     # look_video：手搓 mp4 测编码规则；有 Chrome / Edge 时用 test/fixtures 的样片测黑屏、单声道、没声、画面不动
 ```
 
 ## 已验证
 
 DeepSeek Harness 0.2.1-rc.2 桌面端端到端实测：回复下方播放器（mp4 / HEVC 的 mov / m4a，中文文件名）、侧边栏预览和播放、avi 的转码提示、文件被移走后的出错提示；伪造登录 cookie 的请求被拒；模型用 say / avconvert 生成的 m4a、mp4（含带空格的中文文件名）没调 `play_video`，回合结束时播放器实时出现且能播；视频卡悬停预览 / 点击播放 / 下载、音频条播放、超过 3 个时折叠展开、深浅两种主题下的配色。
 
+`look_video` 在同一台机器的 DSH 桌面端用 DeepSeek-V4.1-Flash 实测：用户说「三个视频帮我看看有没有问题」，模型自己对三个文件调 `look_video`，答出黑屏、爆音、HEVC / WebM 在别处放不了；问「1 秒左右是不是闪了一下」，模型用 `from` / `to` 逐帧看了那一小段，11 秒答出是黑场硬切到亮色。
+
 参考实现：[@goodandready/dsh-image-gen](https://www.npmjs.com/package/@goodandready/dsh-image-gen)（客户端插件套路）与官方 `dsh-tool-present`（deliverables 通道）。
 
 ## 反馈

package/lib/browser.js

@@ -0,0 +1,252 @@
+/**
+ * 无头浏览器：look_video 在电脑上另开一个看不见的 Chrome（或 Edge、Chromium、Brave），
+ * 打开视频按时间取帧、解出声音来量，和 DSH 自己的界面无关。
+ *
+ * 用 --remote-debugging-pipe 和它说话（不开端口，别的程序连不进来）；临时用户目录，用完删掉；
+ * 闲置一会儿自己关，插件停用时一起关。找不到浏览器 → available() 是 false，调用的地方只给文件信息。
+ * （和 dsh-design-studio 的 browser.js 同一份，只改了临时目录的前缀）
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn, execFile } from 'node:child_process'
+
+const IDLE_MS = 90000 // 闲置多久关掉
+const CALL_MS = 30000 // 一条指令最多等多久
+const LOAD_MS = 15000 // 页面载入最多等多久（到点照样往下走：有个图一直载不完也能量）
+const MAX_PAGES = 3 // 同时开几个页面
+
+/** 这台电脑上的 Chromium 系浏览器；DSH_VIDEO_BROWSER / DSH_DESIGN_BROWSER / CHROME_BIN 可以指定 */
+export function findBrowser({ env = process.env, platform = process.platform, exists = fs.existsSync, home = os.homedir() } = {}) {
+  const roots = [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.LOCALAPPDATA].filter(Boolean)
+  const mac = (app, bin) => [`/Applications/${app}.app/Contents/MacOS/${bin}`, `${home}/Applications/${app}.app/Contents/MacOS/${bin}`]
+  const list = {
+    darwin: [...mac('Google Chrome', 'Google Chrome'), ...mac('Microsoft Edge', 'Microsoft Edge'), ...mac('Chromium', 'Chromium'), ...mac('Brave Browser', 'Brave Browser')],
+    win32: roots.flatMap((d) => [`${d}\\Google\\Chrome\\Application\\chrome.exe`, `${d}\\Microsoft\\Edge\\Application\\msedge.exe`, `${d}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`]),
+    linux: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium', '/usr/bin/microsoft-edge', '/usr/bin/brave-browser'],
+  }
+  for (const p of [env.DSH_VIDEO_BROWSER, env.DSH_DESIGN_BROWSER, env.CHROME_BIN, ...(list[platform] || [])]) {
+    if (!p) continue
+    try { if (exists(p)) return p } catch { /* 读不了就下一个 */ }
+  }
+  return null
+}
+
+/** CDP 管道上的消息：JSON 后面跟一个 \0。一块数据里可能有半条、也可能有好几条 */
+export function frameReader(onMsg) {
+  let buf = Buffer.alloc(0)
+  return (chunk) => {
+    buf = buf.length ? Buffer.concat([buf, chunk]) : chunk
+    let i
+    while ((i = buf.indexOf(0)) >= 0) {
+      const text = buf.subarray(0, i).toString('utf8')
+      buf = buf.subarray(i + 1)
+      let msg
+      try { msg = JSON.parse(text) } catch { continue }
+      onMsg(msg)
+    }
+  }
+}
+
+const PREFIX = 'dsh-video-browser-'
+const STALE_MS = 3600 * 1000 // 一小时没动过的临时用户目录：上回没删掉的（DSH 被强退、插件进程直接退出）
+let swept = false
+
+/** 清掉以前留下的临时用户目录（每个进程只扫一次；正在用的浏览器闲置 90 秒就关，不会一小时不动） */
+function sweep(dir = os.tmpdir(), now = Date.now()) {
+  if (swept) return
+  swept = true
+  let names = []
+  try { names = fs.readdirSync(dir) } catch { return }
+  for (const n of names) {
+    if (!n.startsWith(PREFIX)) continue
+    const p = path.join(dir, n)
+    try { if (now - fs.statSync(p).mtimeMs > STALE_MS) fs.rmSync(p, { recursive: true, force: true }) } catch { /* 下次再说 */ }
+  }
+}
+
+export function createBrowser({ bin = findBrowser(), log = () => {}, idleMs = IDLE_MS, launch = spawn, platform = process.platform } = {}) {
+  let proc = null
+  let starting = null
+  let dir = ''
+  let seq = 0
+  let open = 0
+  let idle = null
+  let dead = false // destroy() 之后：不再开浏览器，排队的、新来的都直接失败
+  const pending = new Map() // 指令 id → { resolve, reject, timer }
+  const waiters = new Set() // 等事件的：{ method, sessionId, done }
+  const queue = [] // 等空位开页面的
+
+  const fail = (err) => {
+    for (const p of pending.values()) { clearTimeout(p.timer); p.reject(err) }
+    pending.clear()
+  }
+
+  const onMsg = (msg) => {
+    if (msg.id) {
+      const p = pending.get(msg.id)
+      if (!p) return
+      pending.delete(msg.id)
+      clearTimeout(p.timer)
+      if (msg.error) p.reject(new Error(msg.error.message || 'cdp error'))
+      else p.resolve(msg.result || {})
+      return
+    }
+    for (const w of [...waiters]) if (w.method === msg.method && (!w.sessionId || w.sessionId === msg.sessionId)) w.done(msg.params || {})
+  }
+
+  function call(method, params = {}, sessionId) {
+    if (!proc) return Promise.reject(new Error('browser not running'))
+    return new Promise((resolve, reject) => {
+      const id = ++seq
+      const timer = setTimeout(() => { if (pending.delete(id)) reject(new Error(`${method} timeout`)) }, CALL_MS)
+      pending.set(id, { resolve, reject, timer })
+      try { proc.stdio[3].write(`${JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })}\0`) } catch (e) { pending.delete(id); clearTimeout(timer); reject(e) }
+    })
+  }
+
+  /** 等一个事件（到点就当等到了，返回 null） */
+  function once(method, sessionId, ms) {
+    let w
+    const p = new Promise((resolve) => {
+      const timer = setTimeout(() => { waiters.delete(w); resolve(null) }, ms)
+      w = { method, sessionId, done: (v) => { clearTimeout(timer); waiters.delete(w); resolve(v) } }
+      waiters.add(w)
+    })
+    return p
+  }
+
+  // 宿主进程退出时浏览器来不及报「退出了」：那时同步删掉临时目录
+  let onHostExit = null
+  function cleanup() {
+    if (onHostExit) { process.removeListener('exit', onHostExit); onHostExit = null }
+    proc = null
+    starting = null
+    fail(new Error('browser exited'))
+    for (const w of [...waiters]) w.done(null) // 等页面载入的不用再等了
+    const d = dir
+    dir = ''
+    // 自己建的临时用户目录：浏览器退了马上删（Windows 上进程刚退时文件可能还占着，隔一会儿再试，最多三次；
+    // 还删不掉的，下次开浏览器时按时间清掉）
+    if (d) {
+      let tries = 0
+      const rm = () => {
+        try { fs.rmSync(d, { recursive: true, force: true }) } catch (e) {
+          if (++tries < 4) setTimeout(rm, 2000).unref?.()
+          else log(new Error(`临时目录删不掉，留在 ${d}：${e && e.message}`))
+        }
+      }
+      rm()
+    }
+  }
+
+  async function start() {
+    if (proc) return
+    if (starting) return starting
+    if (!bin) throw new Error('no-browser')
+    if (dead) throw new Error('browser closed')
+    sweep()
+    starting = (async () => {
+      dir = fs.mkdtempSync(path.join(os.tmpdir(), PREFIX))
+      const d = dir
+      onHostExit = () => { try { fs.rmSync(d, { recursive: true, force: true }) } catch { /* 下次开浏览器时按时间清 */ } }
+      process.once('exit', onHostExit)
+      const args = ['--headless=new', '--remote-debugging-pipe', `--user-data-dir=${dir}`, '--no-first-run', '--no-default-browser-check',
+        '--disable-extensions', '--disable-background-networking', '--disable-sync', '--disable-default-apps', '--disable-component-update',
+        '--mute-audio', '--hide-scrollbars', '--force-color-profile=srgb',
+        ...(platform === 'darwin' ? ['--use-mock-keychain'] : []),
+        ...(platform === 'linux' && process.getuid && process.getuid() === 0 ? ['--no-sandbox'] : []),
+        'about:blank']
+      const p = launch(bin, args, { stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'], windowsHide: true })
+      proc = p
+      p.on('exit', () => { if (proc === p) cleanup() })
+      p.on('error', (e) => { log(e); if (proc === p) cleanup() })
+      p.stdio[4].on('data', frameReader(onMsg))
+      p.stdio[3].on('error', () => {})
+      await call('Browser.getVersion')
+    })()
+    try { await starting } catch (e) { stop(); throw e } finally { starting = null }
+  }
+
+  function stop() {
+    clearTimeout(idle)
+    const p = proc
+    if (!p) return
+    try { p.stdio[3].end() } catch { /* 已经断了 */ }
+    if (platform === 'win32') {
+      execFile('taskkill', ['/pid', String(p.pid), '/T', '/F'], (err) => {
+        if (!err) return
+        log(err)
+        try { p.kill() } catch { /* 已经退了 */ }
+      })
+    } else { try { p.kill('SIGKILL') } catch { /* 已经退了 */ } }
+  }
+
+  /** 插件停用：关掉浏览器，排队等页面的都失败，之后再也不开 */
+  function destroy() {
+    dead = true
+    for (const next of queue.splice(0)) next()
+    stop()
+  }
+
+  const touch = () => {
+    clearTimeout(idle)
+    if (!open) idle = setTimeout(() => { if (!open) stop() }, idleMs)
+  }
+
+  /**
+   * 开一个 w×h 的页面载入 url，fn(page) 里量 / 截图，完了关掉。
+   *   page.eval(表达式)：在页面里算（Promise 会等），返回 JSON 值
+   *   page.shot({ clip })：截视口；clip（{ x, y, width, height }，CSS 像素，按整页坐标 = 视口位置 + 滚动距离）只截那一块 → JPEG Buffer
+   */
+  async function withPage({ url, w, h, scale = 1, dark = false }, fn) {
+    if (dead) throw new Error('browser closed')
+    if (open >= MAX_PAGES) await new Promise((r) => queue.push(r))
+    if (dead) throw new Error('browser closed')
+    open++
+    clearTimeout(idle)
+    let targetId = ''
+    try {
+      await start()
+      ;({ targetId } = await call('Target.createTarget', { url: 'about:blank' }))
+      const { sessionId } = await call('Target.attachToTarget', { targetId, flatten: true })
+      const c = (m, p) => call(m, p, sessionId)
+      await c('Page.enable')
+      // 和右侧栏里一样按桌面方式排版（mobile: false）：页面宽就是 w，不看 <meta viewport>
+      await c('Emulation.setDeviceMetricsOverride', { width: w, height: h, deviceScaleFactor: scale, mobile: false })
+      await c('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: dark ? 'dark' : 'light' }, { name: 'prefers-reduced-motion', value: 'reduce' }] })
+      const loaded = once('Page.loadEventFired', sessionId, LOAD_MS)
+      const nav = await c('Page.navigate', { url })
+      if (nav.errorText) throw new Error(nav.errorText)
+      await loaded
+      const page = {
+        eval: async (expression) => {
+          const r = await c('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true })
+          if (r.exceptionDetails) throw new Error((r.exceptionDetails.exception && r.exceptionDetails.exception.description) || r.exceptionDetails.text || 'eval failed')
+          return r.result ? r.result.value : undefined
+        },
+        shot: async ({ clip, quality = 82 } = {}) => {
+          const r = await c('Page.captureScreenshot', { format: 'jpeg', quality, ...(clip ? { clip: { ...clip, scale: 1 } } : {}) })
+          return Buffer.from(r.data, 'base64')
+        },
+      }
+      return await fn(page)
+    } finally {
+      if (targetId && proc) call('Target.closeTarget', { targetId }).catch(() => {})
+      open--
+      const next = queue.shift()
+      if (next) next()
+      touch()
+    }
+  }
+
+  return {
+    available: () => !!bin,
+    bin: () => bin,
+    withPage,
+    stop,
+    destroy,
+    running: () => !!proc,
+  }
+}

package/lib/index.js

@@ -25,8 +25,12 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import crypto from 'node:crypto'
+import http from 'node:http'
 import { pipeline } from 'node:stream'
 import { autoPresent, sessionCwd, fromBashPath } from './auto-present.js'
+import { createBrowser } from './browser.js'
+import { probeFile } from './probe.js'
+import { inspect, formatLook, parseTime, MAX_AT, MAX_FRAMES, MAX_AUDIO_BYTES, MAX_AUDIO_SECONDS } from './look.js'
 
 export const name = '@orderg-x/dsh-video-preview'
 export const inject = ['tools', 'webServer', 'sessionProjections']
@@ -448,6 +452,15 @@ export function apply(ctx) {
 
   ctx.tools.register(tool)
 
+  // look_video 用的无头浏览器：用到时才开，闲置自己关，插件停用时关掉
+  let browser = null
+  ctx.effect(() => {
+    const b = createBrowser({ log: (e) => { try { ctx.logger.warn(`dsh-video-preview: 无头浏览器：${e && e.message ? e.message : e}`) } catch { /* 没 logger 就算了 */ } } })
+    browser = b
+    return () => { b.destroy(); if (browser === b) browser = null }
+  }, 'dsh-video-preview: headless browser')
+  ctx.tools.register(lookTool(ctx, () => browser))
+
   if (typeof ctx.on === 'function') {
     autoPresent(ctx, {
       kindOf,
@@ -457,3 +470,161 @@ export function apply(ctx) {
     })
   }
 }
+
+// ── look_video：让模型自己看视频 ────────────────────────────────────────────
+
+/**
+ * 给无头浏览器开的临时服务：只在 127.0.0.1 上、只给这一个文件、路径里带随机口令，看完就关。
+ * 和 DSH 自己的服务分开：不用登录态，页面和视频同源（能整个读出来解声音、画到画布上取帧）。
+ */
+export async function serveOne(real) {
+  const key = crypto.randomBytes(16).toString('hex')
+  const server = http.createServer(async (req, res) => {
+    try {
+      const host = String(req.headers.host || '')
+      const p = new URL(req.url, 'http://127.0.0.1').pathname
+      if (!LOOPBACK.has(req.socket.remoteAddress) || !LOOPBACK_HOST.test(host)) return reply(res, 403, 'forbidden')
+      if (p === `/${key}/`) {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' })
+        return res.end('<!doctype html><meta charset="utf-8"><title>look</title><body style="margin:0">')
+      }
+      if (p !== `/${key}/media`) return reply(res, 404, 'not found')
+      const stat = await fs.promises.stat(real)
+      stream(req, res, { real, stat })
+    } catch {
+      try { reply(res, 500, 'error') } catch { /* 已经回过了 */ }
+    }
+  })
+  await new Promise((ok, no) => { server.once('error', no); server.listen(0, '127.0.0.1', ok) })
+  const origin = `http://127.0.0.1:${server.address().port}`
+  return {
+    page: `${origin}/${key}/`,
+    src: `${origin}/${key}/media`,
+    close: () => new Promise((ok) => { server.closeAllConnections?.(); server.close(() => ok()) }),
+  }
+}
+
+/** look_video 的图：存进 DSH 的附件库，附件引用放进工具结果；附件库用不了就存成文件（一天前的顺手删掉） */
+const LOOK_DIR = path.join(os.tmpdir(), 'dsh-video-look')
+
+function pruneLookDir(maxAge = 24 * 3600 * 1000) {
+  let names = []
+  try { names = fs.readdirSync(LOOK_DIR) } catch { return }
+  const old = Date.now() - maxAge
+  for (const n of names) {
+    const f = path.join(LOOK_DIR, n)
+    try { if (fs.statSync(f).mtimeMs < old) fs.rmSync(f, { force: true }) } catch { /* 下次再说 */ }
+  }
+}
+
+async function keepImages(ctx, jpgs, base, log) {
+  const attachments = ctx && typeof ctx.get === 'function' ? ctx.get('attachments') : null
+  const name = (i) => `${base.replace(/[^\w.-]+/g, '-').slice(0, 60)}-${i + 1}.jpg`
+  if (attachments) {
+    try {
+      const refs = await attachments.saveImages(jpgs.map((b, i) => ({ data: b, mediaType: 'image/jpeg', name: name(i) })))
+      return { images: [...refs] }
+    } catch (e) { log(e) }
+  }
+  pruneLookDir()
+  fs.mkdirSync(LOOK_DIR, { recursive: true })
+  const files = jpgs.map((b, i) => {
+    const f = path.join(LOOK_DIR, `${Date.now().toString(36)}-${name(i)}`)
+    fs.writeFileSync(f, b)
+    return f
+  })
+  return { files }
+}
+
+/** 工具结果显示成：文字 + 一张张图 */
+function withImages(value) {
+  const blocks = [{ type: 'text', text: value.text }]
+  for (const ref of Array.isArray(value.images) ? value.images : []) blocks.push({ type: 'image', attachment: ref })
+  return blocks
+}
+
+/** 只读文件头就够的格式（probe.js 认得的） */
+const ISO_EXT = new Set(['.mp4', '.m4v', '.mov', '.m4a', '.3gp'])
+
+export function lookTool(ctx, getBrowser) {
+  const log = (e) => { try { ctx.logger.warn(`dsh-video-preview: look_video：${e && e.message ? e.message : e}`) } catch { /* 没 logger 就算了 */ } }
+  return defineTool({
+    name: 'look_video',
+    description:
+      '看一个本地视频（或音频）的内容：在电脑上用看不见的 Chrome / Edge 打开，按时间取几帧拼成一张图交给你（每格左上角标了时间），' +
+      '再量声音（有没有声、多大、哪段没声、有没有爆音、是不是只有一边有声），顺便查手机上能不能放（编码、文件头位置）。' +
+      '你做完、改完视频（录屏、剪辑、转码、配音、合成动画）后，交给用户之前先用它看一眼；用户说视频「不对」「黑屏」「没声音」「手机放不了」时也用它。' +
+      `at 给几个时间点（如 ["0:12", "1:05"]，最多 ${MAX_AT} 个）看那几刻的大图；from / to 只看一段；frames 改取几帧（最多 ${MAX_FRAMES}）。` +
+      '要逐帧看某一刻附近（闪一下、跳帧、颜色突变），把 from / to 缩到那前后零点几秒、frames 设大，不用自己写网页或脚本去解码。',
+    parameters: {
+      path: { type: 'string', required: true, description: '本地文件的绝对路径，例如 /Users/me/Movies/demo.mp4' },
+      at: { type: 'array', items: { type: 'string' }, description: `可选：看这几刻的大图，写成 "0:12"、"1:05.5" 或秒数 "83"（最多 ${MAX_AT} 个）` },
+      from: { type: 'string', description: '可选：只看从这里开始的一段，如 "0:30"' },
+      to: { type: 'string', description: '可选：只看到这里为止，如 "1:00"' },
+      frames: { type: 'number', description: `可选：拼图里取几帧（默认按长短 4–12 帧，最多 ${MAX_FRAMES}）` },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { text: { type: 'string' }, images: { type: 'array', items: { type: 'object' } } },
+        required: ['text'],
+      },
+      render: (_args, value) => withImages(value),
+    },
+    async execute(args, exec) {
+      const a = args || {}
+      const raw = String(a.path || '')
+      if (!raw) throw new Error('path 不能为空')
+      const session = exec && exec.agent && exec.agent.session
+      const file = resolvePath(raw, session ? sessionCwd(ctx, session) : '')
+      if (!file) throw new Error(`拿不到会话的工作目录，请给绝对路径：${raw}`)
+      let real, st
+      try {
+        real = await fs.promises.realpath(file)
+        st = await fs.promises.stat(real)
+      } catch {
+        throw new Error(`找不到文件：${file}`)
+      }
+      if (!st.isFile()) throw new Error(`不是文件：${file}`)
+      const ext = path.extname(real).toLowerCase()
+      if (UNPLAYABLE_EXT.has(ext)) {
+        const { out, cmd } = convertHint(real)
+        return { text: `${ext} 格式浏览器打不开，看不了。先转成 ${path.extname(out)}：\n${cmd}\n转好后再用 look_video 看 ${out}` }
+      }
+      const kind = kindOf(real)
+      if (!kind) return { text: `不是视频 / 音频文件（${ext || '没有扩展名'}）。能看的：${[...VIDEO_EXT, ...AUDIO_EXT].join(' ')}` }
+
+      const at = (Array.isArray(a.at) ? a.at : a.at ? [a.at] : []).slice(0, MAX_AT).map(parseTime)
+      if (at.some((t) => Number.isNaN(t))) return { text: `认不出时间：${JSON.stringify(a.at)}。写成 "0:12"、"1:05.5" 或秒数 "83"。` }
+      const from = a.from != null && a.from !== '' ? parseTime(a.from) : 0
+      const to = a.to != null && a.to !== '' ? parseTime(a.to) : Infinity
+      if (Number.isNaN(from) || Number.isNaN(to)) return { text: `认不出 from / to：${a.from ?? ''} / ${a.to ?? ''}。写成 "0:30" 这样。` }
+      if (to <= from) return { text: `to（${a.to}）要比 from（${a.from}）晚。` }
+
+      const probe = ISO_EXT.has(ext) ? await probeFile(real).catch(() => null) : null
+      const base = { name: path.basename(real), size: fmtSize(st.size), probe, kind, ext }
+      const b = getBrowser()
+      if (!b || !b.available()) {
+        return { text: `${formatLook({ ...base, res: null })}\n\n这台电脑上没找到 Chrome / Edge，看不了画面、量不了声音（上面只是文件头里的信息）。` }
+      }
+      const noTrack = probe && !probe.audio && !probe.noMoov
+      const long = probe && probe.duration > MAX_AUDIO_SECONDS
+      const audioSkipped = st.size > MAX_AUDIO_BYTES ? `文件太大（${fmtSize(st.size)}），没量声音。` : long ? `超过 ${MAX_AUDIO_SECONDS / 60} 分钟，没量声音。` : ''
+      const srv = await serveOne(real)
+      let res
+      try {
+        res = await inspect(b, { page: srv.page, src: srv.src, kind, at: at.length ? at : null, from, to, frames: a.frames, wantAudio: !noTrack && !audioSkipped })
+      } catch (e) {
+        log(e)
+        return { text: `${formatLook({ ...base, res: null })}\n\n无头浏览器没看成（${e && e.message ? e.message : e}），上面只是文件头里的信息。` }
+      } finally {
+        srv.close()
+      }
+      const jpgs = res.jpgs.map((x) => Buffer.from(x, 'base64'))
+      const kept = jpgs.length ? await keepImages(ctx, jpgs, path.basename(real, ext), log) : {}
+      const text = formatLook({ ...base, res, audioSkipped, images: kept.images ? kept.images.length : 0, files: kept.files || [] })
+      return kept.images ? { text, images: kept.images } : { text }
+    },
+  })
+}

package/lib/look.js

@@ -0,0 +1,475 @@
+/**
+ * look_video 的里子：在无头浏览器里打开视频，按时间取帧（拼成一张带时间的图，或几张大图），
+ * 把声音解出来量（有没有声、多大、哪段没声、有没有爆音、是不是只有一边有声），再把这些变成给模型看的字。
+ *
+ *   pageTools   注进页面的函数（在浏览器里跑，Node 不执行）：open / frames / audio
+ *   inspect     开页面、取帧、量声音 → 原始结果
+ *   findings    原始结果 + 文件头信息（probe.js）→ 问题清单
+ *   formatLook  给模型的字
+ */
+
+import { videoName, audioName, compatOf } from './probe.js'
+
+export const MAX_FRAMES = 16 // 拼图里最多几帧
+export const MAX_AT = 6 // at 一次最多看几刻的大图
+export const MAX_AUDIO_BYTES = 400 << 20 // 再大就不解声音了（要整个读进浏览器）
+export const MAX_AUDIO_SECONDS = 30 * 60 // 再长也不解（解出来的采样太多）
+const SHEET_W = 1536 // 拼图宽
+const BIG_EDGE = 1280 // 单张大图的长边
+
+/** 「1:23」「1:23.5」「83」「83s」「01:02:03」→ 秒；认不出 → NaN */
+export function parseTime(v) {
+  if (typeof v === 'number') return Number.isFinite(v) && v >= 0 ? v : NaN
+  const s = String(v ?? '').trim().replace(/s$/i, '')
+  if (!/^\d+(:\d{1,2}){0,2}(\.\d+)?$/.test(s)) return NaN
+  return s.split(':').reduce((sum, x) => sum * 60 + Number(x), 0)
+}
+
+/** 秒 → 「0:05」「1:23」「1:02:03」；短片（一分钟以内）带一位小数，取帧的时间才分得清 */
+export function fmtTime(t, short = false) {
+  const x = Math.max(0, t)
+  if (short) {
+    const s = Math.round(x * 10) / 10
+    return `0:${s < 10 ? '0' : ''}${s.toFixed(1)}`
+  }
+  const total = Math.round(x)
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const sec = String(total % 60).padStart(2, '0')
+  return h ? `${h}:${String(m).padStart(2, '0')}:${sec}` : `${m}:${sec}`
+}
+
+/** 默认取几帧：越长取越多 */
+export function frameCount(duration) {
+  if (duration <= 3) return 4
+  if (duration <= 10) return 6
+  if (duration <= 60) return 9
+  return 12
+}
+
+/**
+ * 在 [from, to] 里均匀取 n 帧，头尾都取（第一帧就是封面，最后一帧看收尾）。
+ * 最后一帧往前让一点：正好落在结尾时很多视频解不出画面。
+ */
+export function pickTimes(duration, { frames, from = 0, to = duration } = {}) {
+  const end = Math.min(duration, to)
+  const start = Math.min(Math.max(0, from), end)
+  const n = Math.max(1, Math.min(MAX_FRAMES, Math.round(frames || frameCount(end - start))))
+  const last = Math.max(start, end - Math.min(0.1, (end - start) / 20))
+  if (n === 1 || last <= start) return [start]
+  return Array.from({ length: n }, (_, i) => Math.round((start + ((last - start) * i) / (n - 1)) * 1000) / 1000)
+}
+
+// ── 页面里跑的 ──────────────────────────────────────────────────────────────
+
+/* eslint-disable */
+/** 注进页面：window.__dshLook = { open, frames, audio }。这个函数只在浏览器里执行 */
+export function pageTools() {
+  if (window.__dshLook) return true
+  let v = null
+  const wait = (el, ev, ms) => new Promise((ok) => {
+    const t = setTimeout(() => done(false), ms)
+    const done = (x) => { clearTimeout(t); el.removeEventListener(ev, on); ok(x) }
+    const on = () => done(true)
+    el.addEventListener(ev, on)
+  })
+  async function seek(t) {
+    if (Math.abs(v.currentTime - t) < 0.0005 && v.readyState >= 2) return true
+    v.currentTime = t
+    const ok = await wait(v, 'seeked', 8000)
+    // 跳完再等这一帧真画出来（有的视频 seeked 早于画面）；等不到也照样往下走
+    if ('requestVideoFrameCallback' in v) await Promise.race([new Promise((r) => v.requestVideoFrameCallback(() => r())), new Promise((r) => setTimeout(r, 150))])
+    return ok
+  }
+  async function open(src) {
+    v = document.createElement('video')
+    v.muted = true
+    v.preload = 'auto'
+    v.playsInline = true
+    v.src = src
+    document.body.append(v)
+    const ok = await Promise.race([wait(v, 'loadeddata', 20000), new Promise((r) => v.addEventListener('error', () => r(false), { once: true }))])
+    if (!ok) return { error: v.error ? v.error.code : 0, message: v.error ? v.error.message : 'timeout' }
+    let duration = v.duration
+    // 浏览器录的 webm 常常不写时长（Infinity）：跳到很远的地方，浏览器就知道多长了
+    if (!Number.isFinite(duration)) {
+      v.currentTime = 1e9
+      await wait(v, 'seeked', 8000)
+      duration = Number.isFinite(v.duration) ? v.duration : v.currentTime
+      v.currentTime = 0
+      await wait(v, 'seeked', 8000)
+    }
+    return { duration, w: v.videoWidth, h: v.videoHeight }
+  }
+  const luma = (d, i) => d[i] * 0.2126 + d[i + 1] * 0.7152 + d[i + 2] * 0.0722
+  /**
+   * 一帧的亮度、反差、亮着的点占多少（千分之几，160×90 上数，黑底上的字也数得到），
+   * 和一个 16×9 的灰度指纹（比前后帧是不是一样）
+   */
+  function stats(sg, mg) {
+    const d = sg.getImageData(0, 0, 16, 9).data
+    const fp = []
+    let sum = 0
+    for (let i = 0; i < d.length; i += 4) { const y = luma(d, i); fp.push(Math.round(y)); sum += y }
+    const mean = sum / fp.length
+    let sq = 0
+    for (const y of fp) sq += (y - mean) * (y - mean)
+    const m = mg.getImageData(0, 0, 160, 90).data
+    let lit = 0
+    for (let i = 0; i < m.length; i += 4) if (luma(m, i) > 48) lit++
+    return { y: Math.round(mean), sd: Math.round(Math.sqrt(sq / fp.length)), lit: Math.round((lit / (m.length / 4)) * 10000) / 10, fp }
+  }
+  function label(g, text, x, y, size) {
+    g.font = `600 ${size}px -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif`
+    const w = g.measureText(text).width + size * 0.8
+    const h = size * 1.5
+    g.fillStyle = 'rgba(0,0,0,.72)'
+    g.beginPath()
+    g.roundRect(x, y, w, h, h / 2)
+    g.fill()
+    g.fillStyle = '#fff'
+    g.textBaseline = 'middle'
+    g.fillText(text, x + size * 0.4, y + h / 2)
+  }
+  /**
+   * 取帧。sheet：拼成一张（cols 列、每格 cw×ch，左上角标时间）；否则每帧一张大图（长边 edge）。
+   * 返回 { jpgs: [base64…], stats: [{ t, y, sd, lit, fp, ok }] }
+   */
+  async function frames(times, labels, o) {
+    const W = v.videoWidth || 16
+    const H = v.videoHeight || 9
+    const small = document.createElement('canvas')
+    small.width = 16
+    small.height = 9
+    const sg = small.getContext('2d', { willReadFrequently: true })
+    const mid = document.createElement('canvas')
+    mid.width = 160
+    mid.height = 90
+    const mg = mid.getContext('2d', { willReadFrequently: true })
+    const out = { jpgs: [], stats: [] }
+    let sheet = null
+    let g = null
+    if (o.sheet) {
+      sheet = document.createElement('canvas')
+      sheet.width = o.cols * o.cw + (o.cols + 1) * o.gap
+      sheet.height = Math.ceil(times.length / o.cols) * o.ch + (Math.ceil(times.length / o.cols) + 1) * o.gap
+      g = sheet.getContext('2d')
+      g.fillStyle = '#1b1d22'
+      g.fillRect(0, 0, sheet.width, sheet.height)
+    }
+    for (let i = 0; i < times.length; i++) {
+      const ok = await seek(times[i])
+      sg.drawImage(v, 0, 0, 16, 9)
+      mg.drawImage(v, 0, 0, 160, 90)
+      out.stats.push({ t: times[i], ok, ...stats(sg, mg) })
+      if (sheet) {
+        const x = o.gap + (i % o.cols) * (o.cw + o.gap)
+        const y = o.gap + Math.floor(i / o.cols) * (o.ch + o.gap)
+        g.drawImage(v, x, y, o.cw, o.ch)
+        label(g, labels[i], x + 6, y + 6, Math.max(13, Math.round(o.cw / 18)))
+      } else {
+        const k = Math.min(1, o.edge / Math.max(W, H))
+        const c = document.createElement('canvas')
+        c.width = Math.round(W * k)
+        c.height = Math.round(H * k)
+        const cg = c.getContext('2d')
+        cg.drawImage(v, 0, 0, c.width, c.height)
+        label(cg, labels[i], 10, 10, Math.max(16, Math.round(c.width / 40)))
+        out.jpgs.push(c.toDataURL('image/jpeg', 0.85).split(',')[1])
+      }
+    }
+    if (sheet) out.jpgs.push(sheet.toDataURL('image/jpeg', 0.85).split(',')[1])
+    return out
+  }
+  /**
+   * 把声音整个解出来（16 kHz）量：每声道的峰值、均方根、削波的比例，和每 0.1 秒一格的响度（dB，混成一路）。
+   * 没有声轨 / 解不出来 → { error }
+   */
+  async function audio(src) {
+    let buf
+    try {
+      const ab = await (await fetch(src)).arrayBuffer()
+      buf = await new OfflineAudioContext(1, 1, 16000).decodeAudioData(ab)
+    } catch (e) {
+      return { error: String((e && e.message) || e) }
+    }
+    const n = buf.length
+    const chs = buf.numberOfChannels
+    const data = Array.from({ length: chs }, (_, c) => buf.getChannelData(c))
+    const per = data.map((d) => {
+      let peak = 0
+      let sq = 0
+      let clip = 0
+      for (let i = 0; i < n; i++) { const a = Math.abs(d[i]); if (a > peak) peak = a; sq += d[i] * d[i]; if (a >= 0.99) clip++ }
+      return { peak, rms: Math.sqrt(sq / Math.max(1, n)), clip }
+    })
+    const step = Math.round(buf.sampleRate / 10)
+    const win = []
+    for (let s = 0; s < n; s += step) {
+      let sq = 0
+      const e = Math.min(n, s + step)
+      for (let c = 0; c < chs; c++) for (let i = s; i < e; i++) sq += data[c][i] * data[c][i]
+      const r = Math.sqrt(sq / Math.max(1, (e - s) * chs))
+      win.push(r > 0 ? Math.max(-100, Math.round(20 * Math.log10(r))) : -100)
+    }
+    return { duration: buf.duration, channels: chs, samples: n, per, win }
+  }
+  window.__dshLook = { open, frames, audio }
+  return true
+}
+/* eslint-enable */
+
+// ── 开页面量 ─────────────────────────────────────────────────────────────────
+
+/** 拼图的排法：横的 3–4 列，竖的 4–6 列；整张长边不超过 1568 */
+export function sheetLayout(w, h, n) {
+  const portrait = h > w
+  const cols = Math.min(n, portrait ? (n <= 4 ? n : n <= 10 ? 5 : 6) : n <= 4 ? 2 : n <= 9 ? 3 : 4)
+  const rows = Math.ceil(n / cols)
+  const gap = 8
+  let cw = Math.floor((SHEET_W - (cols + 1) * gap) / cols)
+  let ch = Math.round((cw * (h || 9)) / (w || 16))
+  const tall = rows * ch + (rows + 1) * gap
+  if (tall > 1568) {
+    const k = (1568 - (rows + 1) * gap) / (rows * ch)
+    cw = Math.floor(cw * k)
+    ch = Math.floor(ch * k)
+  }
+  return { cols, cw, ch, gap }
+}
+
+/**
+ * 在无头浏览器里看一个文件：src 是这个文件在本机临时服务上的地址（同源，能跳进度、能整个读）。
+ *   kind      'video' | 'audio'
+ *   at        要看的时间点（秒）；给了就出几张大图，不给就按 from / to / frames 均匀取、拼成一张
+ *   wantAudio 要不要量声音（文件太大、明知没声轨时不量）
+ * → { info: { duration, w, h } | { error }, times, sheet, jpgs, stats, audio }
+ */
+export async function inspect(browser, { page, src, kind, at, from, to, frames, wantAudio = true }) {
+  return browser.withPage({ url: page, w: 800, h: 600 }, async (p) => {
+    await p.eval(`(${pageTools.toString()})()`)
+    const info = await p.eval(`window.__dshLook.open(${JSON.stringify(src)})`)
+    const res = { info, times: [], sheet: false, jpgs: [], stats: [], audio: null }
+    if (info && !info.error && kind === 'video' && info.w > 0) {
+      const short = info.duration < 60
+      const times = at && at.length
+        ? at.map((t) => Math.min(Math.max(0, t), Math.max(0, info.duration - 0.05)))
+        : pickTimes(info.duration, { frames, from, to })
+      const labels = times.map((t) => fmtTime(t, short))
+      const sheet = !(at && at.length)
+      const o = sheet ? { sheet: true, ...sheetLayout(info.w, info.h, times.length) } : { sheet: false, edge: BIG_EDGE }
+      // 分几次取：一次 eval 有时间上限，帧多的长视频分开取稳一点
+      if (sheet) {
+        const r = await p.eval(`window.__dshLook.frames(${JSON.stringify(times)}, ${JSON.stringify(labels)}, ${JSON.stringify(o)})`)
+        res.jpgs = r.jpgs
+        res.stats = r.stats
+      } else {
+        for (let i = 0; i < times.length; i++) {
+          const r = await p.eval(`window.__dshLook.frames(${JSON.stringify([times[i]])}, ${JSON.stringify([labels[i]])}, ${JSON.stringify(o)})`)
+          res.jpgs.push(...r.jpgs)
+          res.stats.push(...r.stats)
+        }
+      }
+      res.times = times
+      res.sheet = sheet
+    }
+    // 画面打不开（比如这台电脑解不了 HEVC）声音也可能解得出来，照样量；量的时候出错（太长超时）只算声音没量成
+    if (wantAudio && info && info.duration > MAX_AUDIO_SECONDS) res.audio = { skipped: `超过 ${MAX_AUDIO_SECONDS / 60} 分钟，没量声音。` }
+    else if (wantAudio) {
+      try {
+        res.audio = await p.eval(`window.__dshLook.audio(${JSON.stringify(src)})`)
+      } catch (e) {
+        res.audio = { error: String((e && e.message) || e), failed: true }
+      }
+    }
+    return res
+  })
+}
+
+// ── 看出来的问题 ─────────────────────────────────────────────────────────────
+
+const SILENT_DB = -50 // 这一格比这还小就算没声
+const QUIET_DB = -35 // 有声的部分平均比这还小：声音太小
+
+/** 每 0.1 秒一格的响度 → 没声的段 [[开始秒, 结束秒]]（至少 minSec 秒） */
+export function silences(win, minSec = 1.5) {
+  const out = []
+  let s = -1
+  for (let i = 0; i <= win.length; i++) {
+    const quiet = i < win.length && win[i] < SILENT_DB
+    if (quiet && s < 0) s = i
+    if (!quiet && s >= 0) {
+      if ((i - s) / 10 >= minSec) out.push([s / 10, i / 10])
+      s = -1
+    }
+  }
+  return out
+}
+
+const db = (x) => (x > 0 ? Math.round(20 * Math.log10(x) * 10) / 10 : -100)
+
+/** 声音 → { summary, issues: [{ level, text }] } */
+export function audioFindings(a, { duration, short = false } = {}) {
+  if (!a || a.error) return null
+  const issues = []
+  const peak = Math.max(...a.per.map((c) => c.peak))
+  const rms = Math.sqrt(a.per.reduce((s, c) => s + c.rms * c.rms, 0) / a.per.length)
+  const loud = a.win.filter((x) => x >= SILENT_DB)
+  const active = loud.length ? Math.round(10 * Math.log10(loud.reduce((s, x) => s + 10 ** (x / 10), 0) / loud.length)) : -100
+  const total = duration || a.duration
+  const t = (x) => fmtTime(x, short)
+  if (db(peak) < SILENT_DB) {
+    issues.push({ level: 'bad', text: `整段几乎没有声音（最大 ${db(peak)} dB）` })
+    return { summary: `有声轨，但几乎没声（最大 ${db(peak)} dB）`, issues, peak: db(peak), active }
+  }
+  for (const [s, e] of silences(a.win)) {
+    const atStart = s < 0.15
+    const atEnd = e >= a.win.length / 10 - 0.15
+    if (atStart && atEnd) continue
+    if (atStart) issues.push({ level: 'warn', text: `开头 ${t(0)}–${t(e)} 没声音` })
+    else if (atEnd) issues.push({ level: 'warn', text: `结尾 ${t(s)}–${t(Math.min(e, total))} 没声音` })
+    else if (e - s >= 3) issues.push({ level: 'warn', text: `${t(s)}–${t(e)} 没声音（${Math.round(e - s)} 秒）` })
+  }
+  if (active < QUIET_DB) issues.push({ level: 'warn', text: `声音偏小：有声的部分平均 ${active} dB（一般 -20 dB 左右），手机外放可能听不清` })
+  const clipRate = a.per.reduce((s, c) => s + c.clip, 0) / Math.max(1, a.samples * a.per.length)
+  if (clipRate > 0.001) issues.push({ level: 'bad', text: `有爆音（削波）：${(clipRate * 100).toFixed(1)}% 的采样顶到了最大值；把音量调小再导出（ffmpeg 加 -af volume=-6dB）` })
+  if (a.channels === 2) {
+    const [l, r] = a.per.map((c) => db(c.rms))
+    if (l > SILENT_DB + 10 && r < SILENT_DB) issues.push({ level: 'bad', text: '只有左声道有声音（右边没声）：戴耳机只有一边响；转成单声道或复制到两边（ffmpeg 加 -af pan=stereo|c0=c0|c1=c0）' })
+    if (r > SILENT_DB + 10 && l < SILENT_DB) issues.push({ level: 'bad', text: '只有右声道有声音（左边没声）：戴耳机只有一边响；复制到两边（ffmpeg 加 -af pan=stereo|c0=c1|c1=c1）' })
+  }
+  return { summary: `有声，${a.channels === 1 ? '单声道' : a.channels === 2 ? '立体声' : `${a.channels} 声道`}，有声的部分平均 ${active} dB，最大 ${db(peak)} dB`, issues, peak: db(peak), active }
+}
+
+const BLACK_Y = 16 // 平均亮度
+const BLACK_LIT = 3 // 亮着的点不到千分之三（黑底上有字、有画面的不算黑屏；只有鼠标指针的还算）
+const SAME = 2.5 // 两帧指纹平均差多少以内算一样
+
+const fpDiff = (a, b) => a.reduce((s, x, i) => s + Math.abs(x - b[i]), 0) / a.length
+
+/** 取到的帧 → 问题：黑屏、画面一直没变 */
+export function frameFindings(stats, { duration, short = false, sheet = true } = {}) {
+  const issues = []
+  if (!stats.length) return issues
+  const t = (x) => fmtTime(x, short)
+  const black = stats.filter((s) => s.y <= BLACK_Y && s.lit <= BLACK_LIT)
+  const failed = stats.filter((s) => !s.ok)
+  if (failed.length) issues.push({ level: 'warn', text: `有 ${failed.length} 帧跳不过去（${failed.map((s) => t(s.t)).join('、')}）：文件可能不能拖进度条（浏览器录的、没写索引的），那几格可能是旁边的画面` })
+  if (sheet && black.length === stats.length) {
+    issues.push({ level: 'bad', text: `取的 ${stats.length} 帧全是黑的：画面可能没录上（录屏没权限、录错了屏幕、画面被遮住）` })
+    return issues
+  }
+  if (black.length) {
+    const first = stats[0] === black[0]
+    const last = stats[stats.length - 1] === black[black.length - 1] && stats.length > 1
+    if (first && sheet) issues.push({ level: 'warn', text: `第一帧（${t(stats[0].t)}）是黑的：封面会是黑的，有的平台拿第一帧当缩略图` })
+    const mid = black.filter((s) => (s !== stats[0] || !sheet) && (s !== stats[stats.length - 1] || !sheet))
+    if (mid.length) issues.push({ level: 'warn', text: `这几刻是黑屏：${mid.map((s) => t(s.t)).join('、')}` })
+    if (last && sheet) issues.push({ level: 'warn', text: `最后一帧（${t(stats[stats.length - 1].t)}）是黑的：结尾可能多了一段黑屏` })
+  }
+  if (sheet && stats.length >= 3 && duration > 2) {
+    const same = stats.slice(1).every((s, i) => fpDiff(s.fp, stats[i].fp) <= SAME)
+    if (same) issues.push({ level: 'warn', text: `取的 ${stats.length} 帧几乎一模一样：整段画面可能没动（录屏卡住了、录到了静止的窗口）；要是本来就是静态画面就没事` })
+    else {
+      // 连着好几格一样，而且占了一大段
+      let s = 0
+      for (let i = 1; i <= stats.length; i++) {
+        const cont = i < stats.length && fpDiff(stats[i].fp, stats[i - 1].fp) <= SAME
+        if (!cont) {
+          if (i - s >= 4 && stats[i - 1].t - stats[s].t >= duration * 0.3) issues.push({ level: 'warn', text: `${t(stats[s].t)}–${t(stats[i - 1].t)} 画面没变（${i - s} 帧一样）：要是本该有动作，可能卡住了` })
+          s = i
+        }
+      }
+    }
+  }
+  return issues
+}
+
+// ── 给模型的字 ───────────────────────────────────────────────────────────────
+
+const ERR = { 1: '读取被中止', 2: '网络错误（文件读不全）', 3: '解码出错（文件可能坏了，或者编码浏览器不支持）', 4: '浏览器不支持这个格式或编码' }
+
+/**
+ * 拼成给模型的字。
+ *   name, size     文件名、大小（字符串）
+ *   probe          probe.js 读到的文件头（可能是 null）
+ *   res            inspect 的结果（没浏览器时是 null）
+ *   kind           'video' | 'audio'
+ *   audioSkipped   没量声音的原因（可选）
+ *   images         实际交出去几张图
+ */
+/** 不是 MP4 / MOV 的容器：手机上能不能放只看扩展名就知道个大概 */
+const CONTAINER = {
+  '.webm': 'WebM：iPhone 上的微信和一些老设备放不了；要发给别人看就转成 MP4（H.264 + AAC）',
+  '.mkv': 'MKV：手机、微信、网页大多放不了；要发给别人看就转成 MP4（H.264 + AAC），多数时候不用重新编码：ffmpeg -i 原文件 -c copy 新文件.mp4',
+  '.ogv': 'OGV：苹果设备和微信放不了；要发给别人看就转成 MP4（H.264 + AAC）',
+}
+
+export function formatLook({ name, size, probe, res, kind, ext = '', audioSkipped = '', images = 0, files = [] }) {
+  const info = res && res.info
+  const duration = (info && !info.error && info.duration) || (probe && probe.duration) || 0
+  const short = duration > 0 && duration < 60
+  const v = probe && probe.video
+  const w = (info && info.w) || (v && (v.dw || v.w)) || 0
+  const h = (info && info.h) || (v && (v.dh || v.h)) || 0
+  const codec = [videoName(v), audioName(probe && probe.audio)].filter(Boolean).join(' + ')
+  const head = [
+    kind === 'video' && w ? `${w}×${h}` : '',
+    duration ? fmtTime(duration) : '',
+    v && v.fps ? `${Math.round(v.fps)} fps` : '',
+    codec,
+    size,
+  ].filter(Boolean).join('，')
+  const lines = [`看了 ${name}（${head}）：`]
+
+  if (info && info.error) {
+    lines.push(`浏览器打不开：${ERR[info.error] || info.message || '原因不明'}。`)
+  }
+  if (res && res.jpgs.length) {
+    if (res.sheet) {
+      lines.push(`图 1：${res.times.length} 帧，从 ${fmtTime(res.times[0], short)} 到 ${fmtTime(res.times[res.times.length - 1], short)} 均匀取，从左到右、从上到下，每格左上角是时间。`)
+    } else {
+      res.times.forEach((t, i) => lines.push(`图 ${i + 1}：${fmtTime(t, short)} 那一刻（原画面缩到长边 ${BIG_EDGE} 以内）。`))
+    }
+    if (!images && files.length) lines.push(`（这个 DSH 版本没法把图直接给你，存成了文件：\n${files.join('\n')}）`)
+  } else if (kind === 'video' && info && !info.error && !info.w) {
+    lines.push('这个文件里没有画面（只有声音）。')
+  }
+
+  const issues = []
+  if (res && res.stats.length) issues.push(...frameFindings(res.stats, { duration, short, sheet: res.sheet }))
+
+  // 声音
+  const a = res && res.audio
+  const hasTrack = probe ? !!probe.audio : null
+  if (audioSkipped || (a && a.skipped)) lines.push(`声音：${audioSkipped || a.skipped}`)
+  else if (probe && !probe.audio && kind === 'video' && !probe.noMoov) {
+    lines.push('声音：没有声轨（这个视频是哑的）。要是本该有配音 / 背景音乐，是合成时没把声音放进去。')
+  } else if (a && a.failed) {
+    lines.push(`声音：没量成（${a.error}）。`)
+  } else if (a && a.error) {
+    lines.push(hasTrack ? `声音：有声轨（${audioName(probe.audio)}），但浏览器解不出来。` : '声音：没有声轨，或者浏览器解不出来。')
+  } else if (a) {
+    const f = audioFindings(a, { duration, short })
+    lines.push(`声音：${f.summary}。`)
+    issues.push(...f.issues)
+  }
+
+  issues.push(...compatOf(probe))
+  if (CONTAINER[ext]) issues.push({ level: 'warn', text: CONTAINER[ext] })
+  if (issues.length) {
+    lines.push('', '问题：')
+    for (const it of issues) lines.push(`- ${it.level === 'bad' ? '【严重】' : ''}${it.text}`)
+  } else if (res && !(info && info.error)) {
+    // 只说查过的
+    const ok = [
+      res.stats.length ? '画面没有黑屏、没卡住' : '',
+      a && !a.error && !a.skipped ? '声音正常' : '',
+      probe ? '编码手机上能放' : '',
+    ].filter(Boolean)
+    if (ok.length) lines.push('', `没发现问题：${ok.join('，')}。`)
+  }
+  if (res && res.sheet && res.jpgs.length) lines.push('', `要看某一刻的大图：look_video 带 at，例如 at: ["${fmtTime(duration / 2, short)}"]；只看一段：from / to。`)
+  else if (res && res.jpgs.length) lines.push('', '要逐帧看那附近（找闪一下、跳帧、颜色突变）：from / to 缩到那一小段（比如前后 0.3 秒），frames 设成 16。')
+  return lines.join('\n')
+}

package/lib/probe.js

@@ -0,0 +1,262 @@
+/**
+ * 不解码，只读 MP4 / MOV / M4A 的「盒子」：多长、画面多大、什么编码、有没有声轨、文件头（moov）在前还是在后。
+ * 手机能不能播主要看这些（H.264 是不是 4:2:0、HEVC 的标签、moov 在不在前面）。
+ * 只读顶层盒子的头和 moov（最多 64 MB），大文件不进内存。认不出来的格式（webm、mkv……）返回 null。
+ */
+
+import fs from 'node:fs'
+
+const MAX_MOOV = 64 << 20
+const TOP = new Set(['ftyp', 'moov', 'mdat', 'wide', 'free', 'skip', 'pnot', 'uuid', 'moof', 'mfra', 'styp', 'sidx', 'meta'])
+
+/** buf 里一个挨一个的盒子：{ type, body }（body 是去掉盒子头的那段） */
+function* boxes(buf) {
+  let p = 0
+  while (p + 8 <= buf.length) {
+    let len = buf.readUInt32BE(p)
+    const type = buf.toString('latin1', p + 4, p + 8)
+    let hdr = 8
+    if (len === 1) {
+      if (p + 16 > buf.length) return
+      len = Number(buf.readBigUInt64BE(p + 8))
+      hdr = 16
+    } else if (len === 0) len = buf.length - p
+    if (len < hdr || p + len > buf.length) return
+    yield { type, body: buf.subarray(p + hdr, p + len) }
+    p += len
+  }
+}
+
+const child = (buf, type) => {
+  if (!buf) return null
+  for (const b of boxes(buf)) if (b.type === type) return b.body
+  return null
+}
+const dig = (buf, ...types) => types.reduce((b, t) => child(b, t), buf)
+
+/** mvhd / mdhd：{ scale, dur }（版本 1 的时长是 64 位） */
+function timeOf(body) {
+  if (!body || body.length < 20) return null
+  if (body[0] === 1) return body.length >= 32 ? { scale: body.readUInt32BE(20), dur: Number(body.readBigUInt64BE(24)) } : null
+  return { scale: body.readUInt32BE(12), dur: body.readUInt32BE(16) }
+}
+
+/** esds 里的 objectTypeIndication：0x40 / 0x66-0x68 是 AAC，0x69 / 0x6B 是 MP3 */
+function esdsType(esds) {
+  if (!esds || esds.length < 6) return 0
+  let p = 4 // version + flags
+  const len = () => { let n = 0; for (let i = 0; i < 4 && p < esds.length; i++) { const b = esds[p++]; n = (n << 7) | (b & 0x7f); if (!(b & 0x80)) break } return n }
+  while (p < esds.length) {
+    const tag = esds[p++]
+    const n = len()
+    if (tag === 0x03) { const flags = esds[p + 2]; p += 3; if (flags & 0x80) p += 2; if (flags & 0x40) p += 1 + esds[p]; if (flags & 0x20) p += 2; continue }
+    if (tag === 0x04) return esds[p] || 0
+    p += n
+  }
+  return 0
+}
+
+/** 一条轨道的 stsd 第一项：编码标签和细节 */
+function sampleEntry(stsd, kind) {
+  if (!stsd || stsd.length < 16) return null
+  const entries = stsd.subarray(8)
+  const first = boxes(entries).next().value
+  if (!first) return null
+  const e = { tag: first.type }
+  const b = first.body
+  if (kind === 'vide' && b.length >= 78) {
+    e.w = b.readUInt16BE(24)
+    e.h = b.readUInt16BE(26)
+    const kids = b.subarray(78)
+    const avcC = child(kids, 'avcC')
+    if (avcC && avcC.length >= 4) { e.profile = avcC[1]; e.level = avcC[3] }
+    const hvcC = child(kids, 'hvcC')
+    if (hvcC && hvcC.length >= 2) e.profile = hvcC[1] & 0x1f
+    // 颜色：nclx（MP4）/ nclc（MOV）= 原色、传输特性、矩阵；传输特性 16 = PQ、18 = HLG，就是 HDR
+    const colr = child(kids, 'colr')
+    if (colr && colr.length >= 10) {
+      const type = colr.toString('latin1', 0, 4)
+      if (type === 'nclx' || type === 'nclc') e.color = { prim: colr.readUInt16BE(4), trc: colr.readUInt16BE(6), matrix: colr.readUInt16BE(8), full: type === 'nclx' && colr.length >= 11 ? !!(colr[10] & 0x80) : undefined }
+    }
+    // 杜比视界：dvh1 / dvhe 标签，或者 hvc1 里带 dvcC / dvvC（iPhone 录的 HDR）
+    if (/^dv(h1|he|a1|av)$/.test(first.type) || child(kids, 'dvcC') || child(kids, 'dvvC')) e.dolby = true
+    const trc = e.color && e.color.trc
+    if (trc === 16 || trc === 18 || e.dolby) e.hdr = e.dolby ? '杜比视界' : trc === 18 ? 'HLG' : 'PQ'
+  } else if (kind === 'soun' && b.length >= 28) {
+    const ver = b.readUInt16BE(8)
+    e.channels = b.readUInt16BE(16)
+    e.rate = b.readUInt32BE(24) >>> 16
+    const skip = ver === 1 ? 16 : ver === 2 ? 36 : 0
+    const kids = b.subarray(28 + skip)
+    const esds = child(kids, 'esds') || dig(kids, 'wave', 'esds')
+    if (esds) e.oti = esdsType(esds)
+  }
+  return e
+}
+
+function parseTrak(trak) {
+  const tkhd = child(trak, 'tkhd')
+  const mdia = child(trak, 'mdia')
+  const hdlr = child(mdia, 'hdlr')
+  if (!hdlr || hdlr.length < 12) return null
+  const kind = hdlr.toString('latin1', 8, 12)
+  const t = timeOf(child(mdia, 'mdhd'))
+  const stbl = dig(mdia, 'minf', 'stbl')
+  const track = { kind, ...(sampleEntry(child(stbl, 'stsd'), kind) || {}), seconds: t && t.scale ? t.dur / t.scale : 0 }
+  if (kind === 'vide' && tkhd && tkhd.length >= 84) {
+    // 显示尺寸（16.16 定点数，在 tkhd 末尾）和旋转（矩阵前两项）
+    track.dw = Math.round(tkhd.readUInt32BE(tkhd.length - 8) / 65536)
+    track.dh = Math.round(tkhd.readUInt32BE(tkhd.length - 4) / 65536)
+    const m = tkhd[0] === 1 ? 52 : 40
+    const a = tkhd.readInt32BE(m) / 65536
+    const b = tkhd.readInt32BE(m + 4) / 65536
+    track.rotate = (Math.round(Math.atan2(b, a) * 180 / Math.PI) + 360) % 360
+    const stts = child(stbl, 'stts')
+    if (stts && stts.length >= 8) {
+      const n = Math.min(stts.readUInt32BE(4), Math.floor((stts.length - 8) / 8))
+      let frames = 0
+      const deltas = new Set()
+      for (let i = 0; i < n; i++) { frames += stts.readUInt32BE(8 + i * 8); deltas.add(stts.readUInt32BE(12 + i * 8)) }
+      track.frames = frames
+      if (track.seconds > 0) track.fps = Math.round((frames / track.seconds) * 100) / 100
+      track.vfr = deltas.size > 2
+    }
+  }
+  return track
+}
+
+/**
+ * 读一个文件 → { container, brand, size, duration, faststart, fragmented, video, audio, tracks }；
+ * 不是 MP4 / MOV 一类的返回 null。没有 moov（没录完、被截断）时 noMoov: true。
+ */
+export async function probeFile(file) {
+  const fh = await fs.promises.open(file, 'r')
+  try {
+    const { size } = await fh.stat()
+    const read = async (pos, len) => {
+      const b = Buffer.alloc(len)
+      const { bytesRead } = await fh.read(b, 0, len, pos)
+      return b.subarray(0, bytesRead)
+    }
+    const top = []
+    let pos = 0
+    while (pos + 8 <= size && top.length < 4096) {
+      const h = await read(pos, 16)
+      if (h.length < 8) break
+      let len = h.readUInt32BE(0)
+      const type = h.toString('latin1', 4, 8)
+      let hdr = 8
+      if (len === 1) {
+        if (h.length < 16) break
+        len = Number(h.readBigUInt64BE(8))
+        hdr = 16
+      } else if (len === 0) len = size - pos
+      if (len < hdr || !/^[\x20-\x7e]{4}$/.test(type)) break
+      top.push({ type, pos, len, hdr })
+      pos += len
+    }
+    if (!top.length || !TOP.has(top[0].type)) return null
+    const ftyp = top.find((b) => b.type === 'ftyp')
+    const moov = top.find((b) => b.type === 'moov')
+    const mdat = top.find((b) => b.type === 'mdat')
+    const brand = ftyp ? (await read(ftyp.pos + ftyp.hdr, 4)).toString('latin1') : ''
+    const out = {
+      container: brand === 'qt  ' ? 'mov' : 'mp4',
+      brand: brand.trim(),
+      size,
+      duration: 0,
+      faststart: !!moov && (!mdat || moov.pos < mdat.pos),
+      fragmented: top.some((b) => b.type === 'moof'),
+      truncated: pos > size,
+      video: null,
+      audio: null,
+      tracks: [],
+    }
+    if (!moov) return { ...out, noMoov: true }
+    if (moov.len > MAX_MOOV) return { ...out, bigMoov: true }
+    const body = (await read(moov.pos, moov.len)).subarray(moov.hdr)
+    const mv = timeOf(child(body, 'mvhd'))
+    if (mv && mv.scale) out.duration = mv.dur / mv.scale
+    if (child(body, 'mvex')) out.fragmented = true
+    for (const b of boxes(body)) {
+      if (b.type !== 'trak') continue
+      const t = parseTrak(b.body)
+      if (!t) continue
+      out.tracks.push(t)
+      if (t.kind === 'vide' && !out.video) out.video = t
+      if (t.kind === 'soun' && !out.audio) out.audio = t
+    }
+    if (!out.duration) out.duration = Math.max(0, ...out.tracks.map((t) => t.seconds || 0))
+    return out
+  } finally {
+    await fh.close()
+  }
+}
+
+// ── 编码叫什么、手机能不能播 ───────────────────────────────────────────────
+
+const H264_PROFILE = { 66: 'Baseline', 77: 'Main', 88: 'Extended', 100: 'High', 110: 'High 10', 122: 'High 4:2:2', 244: 'High 4:4:4', 44: 'CAVLC 4:4:4' }
+const VIDEO_NAME = { avc1: 'H.264', avc3: 'H.264', hvc1: 'HEVC', hev1: 'HEVC', dvh1: 'HEVC', dvhe: 'HEVC', dva1: 'H.264', dvav: 'H.264', av01: 'AV1', vp09: 'VP9', vp08: 'VP8', mp4v: 'MPEG-4 Part 2', apcn: 'ProRes', apch: 'ProRes', apcs: 'ProRes', apco: 'ProRes', ap4h: 'ProRes 4444', jpeg: 'Motion JPEG', 'png ': 'PNG', 'rle ': 'Animation', s263: 'H.263', h263: 'H.263' }
+const PCM = new Set(['lpcm', 'sowt', 'twos', 'in24', 'in32', 'fl32', 'fl64', 'raw ', 'ipcm', 'fpcm'])
+
+/** 视频编码的名字，例如「H.264 High」「HEVC Main 10 HDR（HLG）」 */
+export function videoName(v) {
+  if (!v) return ''
+  const base = VIDEO_NAME[v.tag] || v.tag.trim()
+  const hdr = v.hdr ? ` HDR（${v.hdr}）` : ''
+  if (base === 'H.264') return (H264_PROFILE[v.profile] ? `${base} ${H264_PROFILE[v.profile]}` : base) + hdr
+  if (base === 'HEVC') return `${base}${v.profile === 2 ? ' Main 10' : v.profile === 4 ? ' RExt' : ''}${hdr}`
+  return base + hdr
+}
+
+/** 音频编码的名字 */
+export function audioName(a) {
+  if (!a) return ''
+  if (a.tag === 'mp4a') return a.oti === 0x69 || a.oti === 0x6b ? 'MP3' : 'AAC'
+  if (PCM.has(a.tag)) return '未压缩 PCM'
+  return { Opus: 'Opus', opus: 'Opus', 'ac-3': 'AC-3', 'ec-3': 'E-AC-3', alac: 'ALAC', samr: 'AMR', 'fLaC': 'FLAC', '.mp3': 'MP3' }[a.tag] || a.tag.trim()
+}
+
+/**
+ * 别处（手机、微信、网页、苹果设备）能不能播：[{ level: 'bad' | 'warn', text }]。
+ * bad = 很多地方放不了，warn = 有些地方放不了或体验差。只看文件头能看出来的。
+ */
+export function compatOf(p) {
+  if (!p) return []
+  const out = []
+  const v = p.video
+  const a = p.audio
+  if (p.noMoov) out.push({ level: 'bad', text: '文件里没有索引（moov）：多半没录完或被截断了，大多数播放器打不开；重新导出一次' })
+  if (v) {
+    const name = videoName(v)
+    // 杜比视界的标签按底下的编码算：dvh1 像 hvc1，dvhe 像 hev1，dva1 / dvav 像 avc1
+    const tag = { dvh1: 'hvc1', dvhe: 'hev1', dva1: 'avc1', dvav: 'avc3' }[v.tag] || v.tag
+    if ((tag === 'avc1' || tag === 'avc3') && [110, 122, 244, 44].includes(v.profile)) {
+      out.push({ level: 'bad', text: `${name}（不是 8 位 4:2:0）：iPhone、微信、QuickTime 和很多电视放不了；重新编码时加 -pix_fmt yuv420p` })
+    } else if (tag === 'hev1') {
+      out.push({ level: 'bad', text: 'HEVC 的标签是 hev1：iPhone、Safari、QuickTime 放不了；不用重新编码，重新封装就行：ffmpeg -i 原文件 -c copy -tag:v hvc1 新文件.mp4' })
+    } else if (tag === 'hvc1') {
+      out.push({ level: 'warn', text: 'HEVC：苹果设备能放；部分安卓、没装扩展的 Windows、一些网页放不了；要到处都能放就转成 H.264' })
+    } else if (v.tag === 'av01') {
+      out.push({ level: 'warn', text: 'AV1：较新的手机和浏览器才行，老 iPhone、老电脑放不了' })
+    } else if (v.tag === 'vp09' || v.tag === 'vp08') {
+      out.push({ level: 'warn', text: `${name} 装在 MP4 里：iPhone、微信可能放不了` })
+    } else if (!['avc1', 'avc3'].includes(tag)) {
+      out.push({ level: 'bad', text: `${name}：浏览器和手机放不了（老编码或剪辑用的格式）；要分享就转成 H.264` })
+    }
+    const w = v.dw || v.w
+    const h = v.dh || v.h
+    if (v.hdr) out.push({ level: 'warn', text: `HDR 视频（${v.hdr}）：iPhone、新款 Mac 上正常；发到微信、很多安卓、网页和不支持 HDR 的屏幕上常常发灰、颜色变淡或过曝；要到处都正常就转成普通的 SDR（BT.709），iPhone 上可以在「设置 → 相机 → 录制视频」关掉 HDR 再录` })
+    if (Math.max(w, h) > 4096 || Math.min(w, h) > 2304) out.push({ level: 'warn', text: `画面 ${w}×${h} 超过 4K：很多手机放不了或很卡` })
+  }
+  if (a) {
+    const name = audioName(a)
+    if (a.tag === 'ac-3' || a.tag === 'ec-3' || a.tag === 'samr') out.push({ level: 'bad', text: `声音是 ${name}：Chrome（DSH 的播放器）和很多手机放不出声；转成 AAC：-c:a aac` })
+    else if (a.tag === 'Opus' || a.tag === 'opus') out.push({ level: 'warn', text: '声音是 Opus 装在 MP4 里：老 iPhone、Safari 放不出声；要稳就用 AAC' })
+    else if (a.tag === 'alac') out.push({ level: 'warn', text: '声音是 ALAC（苹果无损）：Chrome（DSH 的播放器）和很多安卓放不出声；要分享就转成 AAC' })
+  }
+  if (!p.faststart && !p.noMoov && p.size > 2 << 20) {
+    out.push({ level: 'warn', text: '文件头（moov）在末尾：网页、手机在线看要整个下完才开始放；重新封装就行：ffmpeg -i 原文件 -c copy -movflags +faststart 新文件.mp4' })
+  }
+  return out
+}

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Video Player",
-    "description": "Plays local video and audio right in the chat: recordings and voiceovers the model makes get a player under the reply automatically, and open full-size in the sidebar."
+    "description": "Plays local video and audio right in the chat: recordings and voiceovers the model makes get a player under the reply automatically, and open full-size in the sidebar. The model can also look at a video itself: frame contact sheets, audio checks and phone compatibility."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "视频播放",
-    "description": "在对话里直接播放本地视频和音频：模型录的屏、配的音会自动出播放器，就在回复下面；侧边栏里也能大屏看。"
+    "description": "在对话里直接播放本地视频和音频：模型录的屏、配的音会自动出播放器，就在回复下面；侧边栏里也能大屏看。模型也能自己看视频：截帧拼图、听声音、查手机能不能播。"
   }
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@orderg-x/dsh-video-preview",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1 test/*.mjs"
   },
-  "description": "Inline video and audio playback for DeepSeek Harness: a play_video tool plus a native player under the reply and in the sidebar, served by a guarded, Range-capable streaming route.",
+  "description": "Inline video and audio playback for DeepSeek Harness: a play_video tool plus a native player under the reply and in the sidebar, served by a guarded, Range-capable streaming route, and a look_video tool that shows the model frame contact sheets with audio, black-frame and phone-compatibility checks.",
   "license": "MIT",
   "repository": {
     "type": "git",