@orderg-x/dsh-video-preview 0.4.0 → 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,10 +151,17 @@ 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 通道）。
+
+## 反馈
+
+遇到问题或想要新功能，[提一个 issue](https://github.com/OrderG-X/dsh-video-preview/issues/new/choose)。报问题时写上 DSH 版本和插件版本，修起来最快。

package/lib/auto-present.js

@@ -89,6 +89,13 @@ export function sessionCwd(ctx, session) {
   return typeof cwd === 'string' && path.isAbsolute(cwd) ? cwd : ''
 }
 
+/** Windows 上 DSH 用 Git Bash 跑命令，模型给的路径常是 /c/Users/… 这种写法：换成 C:\\Users\\…；别的系统原样 */
+export function fromBashPath(p, platform = process.platform) {
+  if (platform !== 'win32') return p
+  const m = /^\/([a-zA-Z])(?:\/(.*))?$/.exec(p)
+  return m ? `${m[1].toUpperCase()}:\\${(m[2] || '').replace(/\//g, '\\')}` : p
+}
+
 /**
  * 候选片段 → 每种写法一组绝对路径（相对路径按工作目录挨个试，越靠后的目录越新）。
  * 写法按顺序：字面的先试（文件名本身就可能带 %20），再试 URL 解码、shell 转义去掉的。
@@ -103,9 +110,12 @@ function resolveAll(raw, cwds) {
     } catch { /* 不是编码过的，只用字面的 */ }
   }
   for (const v of [...variants]) {
-    if (v.includes('\\')) variants.push(v.replace(/\\(.)/g, '$1')) // shell 里转义的空格：My\ Movies
+    if (!v.includes('\\')) continue
+    // shell 里转义的空格：My\ Movies。Windows 上反斜杠是路径分隔符，只去掉空格前面那个
+    variants.push(process.platform === 'win32' ? v.replace(/\\ /g, ' ') : v.replace(/\\(.)/g, '$1'))
   }
   return variants.map((v) => {
+    v = fromBashPath(v)
     if (v === '~' || v.startsWith('~/')) v = path.join(os.homedir(), v.slice(1))
     return path.isAbsolute(v) ? [path.normalize(v)] : cwds.map((c) => path.resolve(c, v))
   })

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/client.js

@@ -503,7 +503,7 @@ window.__ModuleLoader__.load({
         items.push({
           url: '/dsh-video-preview/preview?p=' + encodeURIComponent(p),
           kind: isAudio ? 'audio' : 'video',
-          name: (typeof f.title === 'string' && f.title) || p.split('/').pop() || p,
+          name: (typeof f.title === 'string' && f.title) || p.split(/[\\/]/).pop() || p,
           autoplay: !!f.autoplay,
           loop: !!f.loop,
         })
@@ -573,7 +573,7 @@ window.__ModuleLoader__.load({
         return h('p', { style: { padding: 16, color: '#888', fontSize: 13 } }, t(key, ZH[key]))
       }
       const audio = AUDIO_RE.test(p)
-      const media = { url: src, kind: audio ? 'audio' : 'video', name: p.split('/').pop() || p }
+      const media = { url: src, kind: audio ? 'audio' : 'video', name: p.split(/[\\/]/).pop() || p }
       if (reason) {
         return h('div', { style: { padding: 16 } }, h(ErrorCard, { reason, media, t }))
       }

package/lib/index.js

@@ -22,10 +22,15 @@
  */
 
 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 } from './auto-present.js'
+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']
@@ -61,7 +66,7 @@ const LOOPBACK_HOST = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i
  * 创建的会话）token 就对不上，媒体请求全部 403。
  */
 function loadSecret() {
-  const file = path.join(process.env.HOME || '.', '.dsh', 'cache', 'dsh-video-preview.secret')
+  const file = path.join(os.homedir(), '.dsh', 'cache', 'dsh-video-preview.secret')
   try {
     const s = fs.readFileSync(file, 'utf8').trim()
     if (s) return s
@@ -110,6 +115,9 @@ function kindOf(file) {
 }
 
 /** shell 单引号：文件名里的 $(...)、反引号、双引号都原样当字面，单引号写成 '\'' */
+/** 各系统装 ffmpeg 的一句话 */
+const FFMPEG_INSTALL = { darwin: 'brew install ffmpeg', win32: 'winget install ffmpeg', linux: 'sudo apt install ffmpeg（或用系统自带的包管理器）' }
+
 function shq(s) {
   return "'" + String(s).replace(/'/g, "'\\''") + "'"
 }
@@ -127,7 +135,7 @@ function convertHint(file) {
 
 /** 工具参数里的路径 → 绝对路径：~ 换成家目录，相对路径按会话的工作目录算；没有工作目录就返回空串 */
 function resolvePath(raw, cwd) {
-  const p = String(raw || '').replace(/^~(?=\/|$)/, process.env.HOME || '~')
+  const p = fromBashPath(String(raw || '')).replace(/^~(?=[\\/]|$)/, os.homedir())
   if (path.isAbsolute(p)) return path.resolve(p)
   return cwd ? path.resolve(cwd, p) : ''
 }
@@ -401,7 +409,7 @@ export function apply(ctx) {
         const { out, cmd } = convertHint(file)
         throw new Error(
           `DSH 的播放器（Chromium 内核）放不了 ${ext} 格式。先转成 ${path.extname(out)} 再播：\n${cmd}\n` +
-          `没装 ffmpeg 的话：brew install ffmpeg。转好后用 play_video 播 ${out}`)
+          `没装 ffmpeg 的话：${FFMPEG_INSTALL[process.platform] || FFMPEG_INSTALL.linux}。转好后用 play_video 播 ${out}`)
       }
       const kind = kindOf(file)
       if (!kind) {
@@ -444,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,
@@ -453,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 }
+    },
+  })
+}