@orderg-x/dsh-video-preview 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrderG-X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/hero.svg" alt="dsh-video-preview — 模型录屏、配音做完，播放器自动出现在回复下面" width="760" />
+
+<p>
+  <a href="https://github.com/OrderG-X/dsh-video-preview/releases"><img src="https://img.shields.io/github/v/release/OrderG-X/dsh-video-preview?label=release&color=4D6BFE" alt="release" /></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT" />
+  <a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://img.shields.io/badge/DSH-plugin-4D6BFE" alt="DSH plugin" /></a>
+</p>
+
+</div>
+
+![hero](assets/hero.png)
+
+让 DSH（DeepSeek Harness）的对话流里直接播放本地视频 / 音频：模型录屏、转码、配音生成的文件，回合结束时播放器自动出现在回复正下方——Claude 桌面端 / Codex 同款位置，不用点任何东西，也不用模型专门调工具。说一句「播一下 ~/Movies/a.mp4」也行。
+
+> **一句话**：DeepSeek Harness（DSH）插件，在对话里直接播放本地视频和音频。模型录屏、转码、配音做出来的文件，播放器自动出现在回复下面；别的文件用 `play_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.
+
+![demo](assets/demo.gif)
+
+## 安装
+
+```sh
+dsh plugin add @orderg-x/dsh-video-preview
+```
+
+也可以直接装发布包：`dsh plugin add https://github.com/OrderG-X/dsh-video-preview/releases/latest/download/dsh-video-preview.tgz`。装完**重启 DSH**（客户端代码在 DSH 启动时打包，不重启看不到播放器）。DSH「插件」页里显示为「视频播放」。
+
+> **从 0.3.x 升级**：0.4.0 起包名改成 `@orderg-x/dsh-video-preview`（npm 上的 `dsh-video-preview` 是别人的包）。装上新版后，到「插件」页把旧的「dsh-video-preview」移除，再重启 DSH。旧版还在时新版不会启动，旧版照常能用；以前对话里的视频链接都还能播。
+
+开发时可以直接链到本地目录：`dsh plugin --profile desktop add link:/path/to/dsh-video-preview`，改了代码同样要重启。
+
+## 它解决什么
+
+DSH 的消息渲染块只有 text / image / file / table，**没有 video**，工具调用块又默认折叠。这个插件用纯官方插件 API 补上内联播放（零 `@deepseek-ai/*` 依赖，和官方 `present` 工具同款机制）。
+
+一次 `play_video` 调用后，用户能看到：
+
+1. **回复下方的播放器**（主显示位）——小卡片，一个一行：
+   - 视频只露画面（200 高、按原比例），角上标时长；鼠标移上去静音预览、浮出文件名 / 大小 / 下载，点一下从头带声音播
+   - 音频是一条细条：圆形播放键、文件名、大小、时长、可拖的进度条
+   - 超过 3 个先折叠成「还有 N 个媒体文件」；同一时间只有一个在出声
+   - 配色、圆角、字体用 DSH 自己的设计变量，深浅色主题跟着走
+2. **交付文件芯片**——点「在侧边栏预览」打开大屏播放器（DSH 原生把 mp4 列为「不可预览」，这里接管）
+3. **工具块里的小播放器**（兜底）——展开工具调用块后可见
+
+模型用自带 `present` 工具交付的媒体文件，也会自动出现播放器。
+
+## 自动播放（不用调工具）
+
+模型这一轮里生成的视频 / 音频（录屏、ffmpeg / avconvert 转码、`say` 配音……），回合收尾时自动挂上播放器：
+
+- **怎么找**：从这一轮的命令参数、命令输出、回复正文里挖出媒体文件路径（带空格、中文、`~`、相对路径、shell 转义都认）
+- **挂哪些**：只挂这一轮里新写出来的文件（刚下载、解压出来的也算），以前就有的不挂；回复正文提到的优先，没提才用命令里的，中间文件不刷屏；一轮最多 8 个
+- **不重复**：已经用 `play_video` / `present` 播过的不再挂
+- **中途停掉**：来不及在收尾时挂，会在回合结束后补上（重新打开会话可见）
+
+## 用法
+
+对话里直接说「播一下 /Users/me/Movies/a.mp4」，模型会调 `play_video`。参数：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `path` | 是 | 本地文件路径（支持 `~`；相对路径按会话的工作目录算） |
+| `title` | 否 | 播放器标题，默认文件名 |
+| `autoplay` | 否 | 自动播放（浏览器通常会拦） |
+| `loop` | 否 | 循环播放 |
+
+## 能播什么
+
+DSH 的播放器是 Chromium 内核，能播什么由它决定：
+
+| | 格式 |
+| --- | --- |
+| 能播 | 视频 mp4 / m4v / mov / webm / ogv，音频 mp3 / wav / ogg / m4a / aac / flac / opus |
+| 看编码 | mkv / 3gp：要看文件里的编码，播不了会在播放器下面说明并给出转码命令 |
+| 播不了 | avi / flv / wmv / wma / ts / mpg / rmvb 等 —— `play_video` 会直接说明，并给出转码命令 |
+
+转码（需要 [ffmpeg](https://ffmpeg.org/)，macOS 上 `brew install ffmpeg`）：
+
+```sh
+ffmpeg -i in.avi -c:v libx264 -c:a aac -movflags +faststart out.mp4   # 视频
+ffmpeg -i in.wma -c:a aac out.m4a                                      # 音频
+```
+
+播放出错时，播放器下面会告诉你是哪种情况：文件被移走了、没有权限、插件没加载（要重启 DSH），还是编码不支持（附转码命令）。
+
+## 安全
+
+DSH 的本地网页服务本身不做鉴权，浏览器里任何网页都摸得到 `127.0.0.1`，所以两条播放路由自己把门：
+
+- **只给媒体文件**：按扩展名判断，软链接按它指向的真实文件算；别的文件一律 403。
+- **防 DNS 重绑定和跨站**：Host 必须是本机名或 DSH 自己的地址；跨站请求、Origin 不是 DSH 自己的都拒。
+- **签名地址**（`/dsh-video-preview/media`）：token = HMAC(密钥, 文件绝对路径)，密钥存在 `~/.dsh/cache/dsh-video-preview.secret`（0600），同一台机器上跨重启、跨宿主都有效。
+- **侧边栏 / 回复下方的地址**（`/dsh-video-preview/preview`，没有 token）：交给 DSH 自己的 `connection` 服务验登录 cookie；老版本 DSH 没有这个服务时只收本机连接。
+
+v0.3.0 之前的版本只看 cookie 名字，网页能伪造 cookie 读到任意文件，请升级。
+
+## 架构
+
+```
+服务端  play_video 工具 ──校验文件──▶ 返回带签名的 URL
+            │
+            └─append deliverables/presented 事件（官方 present 工具同款通道）
+自动    session/event 收集这一轮的路径 → agent/turn-stopping 时挑出新文件 → 同一条通道
+路由    /dsh-video-preview/media    签名 token · HTTP Range 流式（大文件不进内存）
+        /dsh-video-preview/preview  DSH 登录态 · 供侧边栏 / 回复下方的播放器
+客户端  turnTail 槽 / documentPreviews 渲染器 / toolview 槽
+```
+
+- `lib/index.js` —— 服务端：工具 + deliverables 事件 + 两条流式路由（读盘出错只断当前请求，不会带崩 DSH）
+- `lib/auto-present.js` —— 自动播放：挖路径、挑新文件、回合收尾前呈现（回合结束后才 append 的话，界面要重开会话才刷出来）
+- `lib/client.js` —— 客户端：回复下方播放器 / 侧边栏预览 / 工具块兜底 / 出错诊断（`exports.inject` 是客户端**短服务名**，写包名会一直 pending）
+- `locale/*.json`、`icon.svg` —— DSH 插件页的卡片标题、说明和图标
+- `cordis.patch.yml` —— bundle patch（insert 行的 `name` 必须是完整包名，客户端按它解析 bundle）
+
+## 测试
+
+```sh
+node test/test-routes.mjs   # 把门、Range、HEAD、读盘出错、工具的格式提示
+node test/test-client.mjs   # 三个挂载点、视频卡 / 音频条、折叠、出错诊断
+node test/test-auto.mjs     # 自动播放：新 / 老文件、正文优先、各种路径写法、不重复、重放不动手
+```
+
+## 已验证
+
+DeepSeek Harness 0.2.1-rc.2 桌面端端到端实测：回复下方播放器（mp4 / HEVC 的 mov / m4a，中文文件名）、侧边栏预览和播放、avi 的转码提示、文件被移走后的出错提示；伪造登录 cookie 的请求被拒；模型用 say / avconvert 生成的 m4a、mp4（含带空格的中文文件名）没调 `play_video`，回合结束时播放器实时出现且能播；视频卡悬停预览 / 点击播放 / 下载、音频条播放、超过 3 个时折叠展开、深浅两种主题下的配色。
+
+参考实现：[@goodandready/dsh-image-gen](https://www.npmjs.com/package/@goodandready/dsh-image-gen)（客户端插件套路）与官方 `dsh-tool-present`（deliverables 通道）。

package/assets/hero.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="210" viewBox="0 0 760 210" role="img" aria-label="dsh-video-preview">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0d1117"/>
+      <stop offset="1" stop-color="#161b22"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#4D6BFE" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#4D6BFE" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+
+  <style>
+    .float { animation: float 3.4s ease-in-out infinite; }
+    @keyframes float { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-5px); } }
+    .halo { animation: halo 3.4s ease-in-out infinite; transform-box: fill-box; transform-origin: center; }
+    @keyframes halo { 0%, 100% { opacity: 0.75; transform: scale(1); } 50% { opacity: 1; transform: scale(1.08); } }
+    .ripple { fill: none; stroke: #4D6BFE; stroke-width: 2; opacity: 0; transform-box: fill-box; transform-origin: center;
+      animation: ripple 3.4s cubic-bezier(0.2, 0.6, 0.4, 1) infinite; }
+    .r2 { animation-delay: 1.7s; }
+    @keyframes ripple { 0% { transform: scale(0.55); opacity: 0.85; } 70% { transform: scale(1.7); opacity: 0; } 100% { transform: scale(1.7); opacity: 0; } }
+    .press { transform-box: fill-box; transform-origin: center; animation: press 3.4s ease-in-out infinite; }
+    @keyframes press { 0%, 55%, 100% { transform: scale(1); } 62% { transform: scale(0.9); } 70% { transform: scale(1); } }
+    .pill { animation: pill 3.4s ease-in-out infinite; }
+    .p2 { animation-delay: 0.12s; } .p3 { animation-delay: 0.24s; } .p4 { animation-delay: 0.36s; }
+    @keyframes pill { 0%, 60%, 100% { opacity: 1; } 66% { opacity: 0.72; } }
+  </style>
+
+  <rect width="760" height="210" rx="18" fill="url(#bg)"/>
+  <rect x="0.5" y="0.5" width="759" height="209" rx="17.5" fill="none" stroke="#30363d"/>
+
+  <circle class="halo" cx="76" cy="92" r="62" fill="url(#glow)"/>
+  <circle class="ripple" cx="76" cy="92" r="30"/>
+  <circle class="ripple r2" cx="76" cy="92" r="30"/>
+
+  <g class="float">
+    <g class="press">
+        <circle cx="76" cy="92" r="36" fill="#4D6BFE"/>
+        <path d="M67 75v34l27-17z" fill="#ffffff"/>
+    </g>
+  </g>
+
+  <text x="146" y="86" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif"
+        font-size="38" font-weight="700" fill="#ffffff" letter-spacing="-0.5">dsh-video-preview</text>
+
+  <text x="146" y="116" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif"
+        font-size="14.5" fill="#8b949e">Inline video and audio for DSH chats: the player shows up under the reply.</text>
+
+  <text x="146" y="138" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif"
+        font-size="14.5" fill="#8b949e">模型录屏、配音做完，播放器自动出现在回复下面，不用调工具。</text>
+
+  <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif" font-size="12" font-weight="600">
+    <g class="pill">
+      <rect x="146" y="156" width="126" height="26" rx="13" fill="#4D6BFE" fill-opacity="0.16" stroke="#4D6BFE" stroke-opacity="0.45"/>
+      <text x="209" y="173" fill="#8ea6ff" text-anchor="middle">inline player</text>
+    </g>
+    <g class="pill p2">
+      <rect x="280" y="156" width="141" height="26" rx="13" fill="#4D6BFE" fill-opacity="0.16" stroke="#4D6BFE" stroke-opacity="0.45"/>
+      <text x="350.5" y="173" fill="#8ea6ff" text-anchor="middle">Range streaming</text>
+    </g>
+    <g class="pill p3">
+      <rect x="429" y="156" width="97" height="26" rx="13" fill="#3fb950" fill-opacity="0.14" stroke="#3fb950" stroke-opacity="0.4"/>
+      <text x="477.5" y="173" fill="#7ee787" text-anchor="middle">auto-play</text>
+    </g>
+    <g class="pill p4">
+      <rect x="534" y="156" width="67" height="26" rx="13" fill="#3fb950" fill-opacity="0.14" stroke="#3fb950" stroke-opacity="0.4"/>
+      <text x="567.5" y="173" fill="#7ee787" text-anchor="middle">audio</text>
+    </g>
+  </g>
+</svg>

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Bundle patch for @orderg-x/dsh-video-preview
+# The row id differs from the old dsh-video-preview package's, so both can sit in a profile without a duplicate-id error.
+- insert:
+    - id: orderg-x-video-preview
+      name: '@orderg-x/dsh-video-preview'

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
+  <rect width="128" height="128" rx="28" fill="#4D6BFE"/>
+  <rect x="18" y="28" width="92" height="72" rx="12" fill="none" stroke="#FFFFFF" stroke-width="7"/>
+  <path d="M55 47 L55 81 L83 64 Z" fill="#FFFFFF" stroke="#FFFFFF" stroke-width="5" stroke-linejoin="round"/>
+</svg>

package/lib/auto-present.js

@@ -0,0 +1,267 @@
+/**
+ * 自动呈现：这一轮里新生成的视频 / 音频，不用模型调 play_video，回合结束时自动挂上播放器。
+ *
+ * 做法（全走官方事件，不改 DSH）：
+ *   session/event 里盯住这一轮的 tool/call（参数）、tool/result（输出）、assistant/message（回复正文），
+ *   从里面挖出像媒体文件路径的字符串；回合收尾前（agent/turn-stopping）逐个 stat，
+ *   留下「存在、是普通文件、这一轮里才写过」的，append 一条 deliverables/presented ——
+ *   和 play_video / 官方 present 同一条通道，turnTail 播放器和交付芯片自然就出来了。
+ *
+ * 去噪：回复正文里提到的新文件优先（那是模型要交给用户的）；正文一个都没提，才用命令里挖到的。
+ * 老文件（这一轮之前就有的）不算：修改时间、创建时间、ctime 任一落在这一轮里就算新
+ * （下载、解压出来的文件修改时间常是旧的）；同一轮已经呈现过的不重复；最多 MAX_FILES 个。
+ * 收尾钩子没跑到（中途停掉）才在实时的 turn/end 上补；重放历史时事件时间是旧的，不会往老会话里补东西。
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const EXT_RE = /\.(mp4|m4v|mov|webm|ogv|mkv|3gp|mp3|wav|ogg|oga|m4a|aac|flac|opus|weba)(?![A-Za-z0-9_])/gi
+// 路径只会从这些字符后面开始（空白、引号、括号、= : , 等，含中文标点）
+const BEFORE = new Set([...' \t"\'`=:,;()[]{}<>|*（）「」『』【】《》“”‘’，、：；'])
+const MAX_STARTS = 12 // 每个扩展名往回最多试这么多个起点
+const LOOKBACK = 1024 // 往回最多看这么远
+const MAX_TOOL_GROUPS = 300
+const MAX_TEXT_GROUPS = 100
+const MAX_FILES = 8
+const CLOCK_SLACK_MS = 2000 // 文件时间和事件时间的误差余量
+const LIVE_MS = 120000 // turn/end 离现在超过这么久就当是重放
+
+/**
+ * 从一段文字里挖出可能是媒体路径的片段。
+ * 每处 .mp4 之类的结尾给一组候选：从长到短（「/Users/me/My Movies/a.mp4」排在「Movies/a.mp4」前面），
+ * 检查时取第一个真实存在的，这样带空格的路径也能认出来。
+ */
+export function candidatesIn(text) {
+  const groups = []
+  if (typeof text !== 'string' || !text) return groups
+  for (const line of text.split(/\r?\n/)) {
+    EXT_RE.lastIndex = 0
+    let m
+    while ((m = EXT_RE.exec(line))) {
+      const end = m.index + m[0].length
+      const from = Math.max(0, end - LOOKBACK)
+      const starts = []
+      for (let s = m.index - 1; s >= from && starts.length < MAX_STARTS; s--) {
+        if (BEFORE.has(line[s])) continue
+        if (s === 0 || BEFORE.has(line[s - 1])) starts.push(s)
+      }
+      if (starts.length) groups.push(starts.reverse().map((s) => line.slice(s, end)))
+    }
+  }
+  return groups
+}
+
+/** 工具参数是 JSON 字符串：拆开把所有字符串值都拿出来（命令里的引号就不会挡路了） */
+function stringsOf(value, out = []) {
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value)
+      if (parsed && typeof parsed === 'object') return stringsOf(parsed, out)
+    } catch { /* 不是 JSON，就当普通文字 */ }
+    out.push(value)
+  } else if (Array.isArray(value)) {
+    for (const v of value) stringsOf(v, out)
+  } else if (value && typeof value === 'object') {
+    for (const v of Object.values(value)) stringsOf(v, out)
+  }
+  return out
+}
+
+/** 消息里的文字块；assistant 的 reasoning 不算（那是打算，不是结果） */
+function textsOf(content) {
+  if (typeof content === 'string') return [content]
+  if (!Array.isArray(content)) return []
+  return content.filter((c) => c && c.type === 'text' && typeof c.text === 'string').map((c) => c.text)
+}
+
+/**
+ * 会话现在的工作目录：DSH 的 workingDirectory 投影（会话里切过目录就是新的），
+ * 没有就用会话头里建会话时的目录。都拿不到返回空串。
+ */
+export function sessionCwd(ctx, session) {
+  let cwd
+  try {
+    cwd = ctx && ctx.sessionProjections && ctx.sessionProjections.stateOf(session, 'workingDirectory')
+  } catch { /* 没装这个投影 */ }
+  if (typeof cwd !== 'string' || !cwd) cwd = session && session.header && session.header.cwd
+  return typeof cwd === 'string' && path.isAbsolute(cwd) ? cwd : ''
+}
+
+/**
+ * 候选片段 → 每种写法一组绝对路径（相对路径按工作目录挨个试，越靠后的目录越新）。
+ * 写法按顺序：字面的先试（文件名本身就可能带 %20），再试 URL 解码、shell 转义去掉的。
+ */
+function resolveAll(raw, cwds) {
+  const p = raw.replace(/^file:\/\//i, '')
+  const variants = [p]
+  if (p.includes('%')) {
+    try {
+      const d = decodeURIComponent(p)
+      if (d !== p) variants.push(d)
+    } catch { /* 不是编码过的，只用字面的 */ }
+  }
+  for (const v of [...variants]) {
+    if (v.includes('\\')) variants.push(v.replace(/\\(.)/g, '$1')) // shell 里转义的空格：My\ Movies
+  }
+  return variants.map((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))
+  })
+}
+
+/**
+ * @param ctx 插件 ctx（要 ctx.on）
+ * @param opts.kindOf 判断媒体类型（和路由同一把尺子）
+ * @param opts.now 测试用
+ * @param opts.log 出错时写日志
+ */
+export function autoPresent(ctx, { kindOf, now = Date.now, log = () => {} }) {
+  const turns = new WeakMap()
+
+  function addGroups(st, texts, tier) {
+    const max = tier === 'text' ? MAX_TEXT_GROUPS : MAX_TOOL_GROUPS
+    const list = st[tier]
+    for (const t of texts) {
+      for (const g of candidatesIn(t)) {
+        if (list.length >= max) return
+        const key = g[0]
+        if (st.seen.has(tier + key)) continue
+        st.seen.add(tier + key)
+        list.push(g)
+      }
+    }
+  }
+
+  /** 这一轮里写过：修改时间、创建时间、ctime 任一落在这一轮里（下载、解压出来的修改时间常是旧的） */
+  function isFresh(stat, st) {
+    const t = Math.max(stat.mtimeMs || 0, stat.ctimeMs || 0, stat.birthtimeMs || 0)
+    return stat.isFile() && stat.size > 0 && t >= st.start - CLOCK_SLACK_MS
+  }
+
+  /**
+   * 一组候选里取第一个存在的；它要是这一轮新写的媒体文件就返回路径。
+   * 相对路径在好几个工作目录下都有：旧的跳过接着看，都是新的取最后一个目录（最近用过的）。
+   */
+  async function pick(group, st, cwds) {
+    for (const raw of group) {
+      for (const paths of resolveAll(raw, cwds)) {
+        let exists = false
+        let hit = null
+        for (const p of paths) {
+          let stat
+          try { stat = await fs.promises.stat(p) } catch { continue }
+          exists = true
+          if (isFresh(stat, st) && kindOf(p)) hit = p
+        }
+        if (exists) return hit
+      }
+    }
+    return null
+  }
+
+  /** 这些候选里「这一轮新写的媒体文件」，按出现顺序去重 */
+  async function freshIn(groups, st, cwds) {
+    const found = []
+    for (const g of groups) {
+      if (found.length >= MAX_FILES * 2) break
+      const p = await pick(g, st, cwds)
+      if (p && !found.includes(p)) found.push(p)
+    }
+    return found
+  }
+
+  /**
+   * 挑出要呈现的文件并 append。回合收尾前（agent/turn-stopping）调一次，界面实时就能看到；
+   * 收尾钩子没跑到（中途停掉、出错）才在 turn/end 补一次，那时要重新打开会话才看得到。
+   * 可以重复调：已经呈现过的不会再来。
+   */
+  async function finish(session, st) {
+    st.finished = true
+    // 工具跑过的目录按最近用过的顺序排；会话的工作目录没被工具用过就排最前
+    const base = sessionCwd(ctx, session)
+    const cwds = [...st.cwds]
+    if (base && !st.cwds.has(base)) cwds.unshift(base)
+    // 正文里提到了新文件，就只认正文的（哪怕已经用 play_video 播过），命令里的中间文件不挂
+    let fresh = await freshIn(st.text, st, cwds)
+    if (!fresh.length) fresh = await freshIn(st.tool, st, cwds)
+    const files = fresh.filter((p) => !st.presented.has(p)).slice(0, Math.max(0, MAX_FILES - st.auto))
+    if (!files.length || typeof session.append !== 'function') return
+    for (const p of files) st.presented.add(p)
+    st.auto += files.length
+    session.append('deliverables/presented', {
+      turn: st.turn,
+      callId: `dsh-video-preview:auto:${st.turn}:${++st.batches}`,
+      files: files.map((p) => ({ path: p, description: `▶️ ${path.basename(p)}` })),
+    })
+  }
+
+  function observe(session, event) {
+    const d = (event && event.data) || {}
+    if (event.type === 'turn/start') {
+      turns.set(session, {
+        turn: d.turn,
+        start: typeof event.time === 'number' ? event.time : now(),
+        cwds: new Set(), // 这一轮工具跑过的目录，最近用过的排最后
+        text: [],
+        tool: [],
+        seen: new Set(),
+        presented: new Set(),
+        auto: 0,
+        batches: 0,
+        finished: false,
+      })
+      return
+    }
+    const st = turns.get(session)
+    if (!st || (d.turn !== undefined && d.turn !== st.turn)) return
+    switch (event.type) {
+      case 'tool/call':
+        addGroups(st, stringsOf(d.arguments), 'tool')
+        break
+      case 'tool/result':
+        if (d.meta && typeof d.meta.cwd === 'string' && path.isAbsolute(d.meta.cwd)) {
+          st.cwds.delete(d.meta.cwd)
+          st.cwds.add(d.meta.cwd)
+        }
+        addGroups(st, textsOf(d.message && d.message.content), 'tool')
+        break
+      case 'assistant/message':
+        addGroups(st, textsOf(d.message && d.message.content), 'text')
+        break
+      case 'deliverables/presented':
+        for (const f of Array.isArray(d.files) ? d.files : []) {
+          if (f && typeof f.path === 'string') st.presented.add(path.normalize(f.path))
+        }
+        break
+      case 'turn/end': {
+        turns.delete(session)
+        const t = typeof event.time === 'number' ? event.time : now()
+        if (st.finished || now() - t > LIVE_MS) return
+        finish(session, st).catch((e) => log(e))
+        break
+      }
+    }
+  }
+
+  ctx.on('session/event', (session, event) => {
+    try {
+      if (session && event) observe(session, event)
+    } catch (e) {
+      log(e)
+    }
+  })
+
+  // 回合正常收尾前：这时候 append，事件还在这一轮里，界面实时刷出播放器
+  ctx.on('agent/turn-stopping', async ({ agent, turn, signal } = {}) => {
+    try {
+      const session = agent && agent.session
+      const st = session && turns.get(session)
+      if (!st || st.turn !== turn || (signal && signal.aborted)) return
+      await finish(session, st)
+    } catch (e) {
+      log(e)
+    }
+  })
+}