SAOS-3624/dsh-watch-together ↗★ 7

dsh-watch-together

Watch a video together with a text-only agent: follow the user's real playback position, hand over one segment at a time just before it ends, and keep a single text stream of scripted lines, interjections and the user's replies.

パッケージ
dsh-watch-together
互換性
未検証
Harness ピア範囲
>=0.1.0-rc.7
バージョン
0.1.1
ライセンス
Apache-2.0
最終更新
2026/11/01

インストール

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:SAOS-3624/dsh-watch-together

ドキュメント

README 全文を読む ↗

dsh-watch-together

test npm license

陪一个只会读文字的模型一起看视频:跟着你的真实播放进度一段段往下看,在你快看完这一段时把画面和台词递过来。

名字全小写,带横杠 —— 和 dsh-video-storyboard 同一个风格。

English TL;DR — a DSH plugin that watches a video together with a text-only agent: it follows the real playback position reported by a browser extension, hands the agent one storyboard + transcript per segment just before that segment ends, and speaks the scripted lines at the exact second. Code, identifiers and the tool schema are English; the docs below are Chinese.

  • 它是什么:一个 DSH 插件,只注册一个工具 watch_together
  • 它不是什么:不是全片概览,不是播放器,也不带 TTS 引擎(声音自己接,见 §接声音)
  • 依赖:node + ffmpeg + 一个浏览器扩展(可选但强烈建议)

30 秒开始

npm i dsh-watch-together          # 会连带装 dsh-video-storyboard
node bin/watch.mjs doctor         # 自检:ffmpeg / 扩展 / 字幕 / 声音,逐项 OK 才算就绪
node bin/watch.mjs install-extension   # 装一次浏览器扩展(以后正常开浏览器就行)

然后在会话里:

watch_together({ wait: true })    // 跟着你浏览器里正在放的那一支走

配置在哪、缺什么怎么补:全部集中在 docs/CONFIG.zh.md —— ffmpeg / yt-dlp / B 站 cookies / ASR / 浏览器扩展 / 调试端口 / 声音 / 悬浮窗,一节一个服务。


它和 dsh-video-storyboard 是什么关系

两个插件,一个依赖。 这不是一个包里的两个开关。

dsh-video-storyboarddsh-watch-together(本包)
版本0.5.x0.0.7
工具video_storyboard / video_zoom / video_probe / video_locatewatch_together
干什么把一段视频变成一张可引用的宫格(一次性、全片或指定窗口)跟着播放进度一段一段看下去
依赖方向不依赖陪看(storyboard → watch = 0 处)依赖视频识别,单向

陪看天生建立在视频识别之上:它每次交付的那一格画面和清单,都是调用 dsh-video-storyboard 的 runStoryboard() 算出来的。所以本包把 dsh-video-storyboard 写成普通依赖(^0.5.0), npm i dsh-watch-together 会连它一起装上 —— 装的是库代码,不会因此多注册四个 video_* 工具 (工具由各自的插件入口注册)。

想只要视频识别、不要陪看:装 dsh-video-storyboard 就行,本包不会被拖进来。

发布顺序 —— 但版本号不需要对齐

本包依赖 dsh-video-storyboard@^0.5.0。这是范围,不是等号:semver 对 0.x 的规定是 ^0.5.0 = >=0.5.0 的 currentTime。它准到毫秒,不用猜。 把这个值取出来有两条路:

A. 浏览器扩展(推荐)B. 调试端口(备用)
怎么开始装一次扩展,一分钟每次开一个专用窗口
用哪个浏览器你平时那个,书签登录都在另一个窗口,要重新登一次
位置精度页面真值,每秒上报页面真值,每 15 秒读一次
手工步骤装扩展(一次性)双击 scripts/start-edge-debug.cmd
适合所有人不想装扩展 / 扩展读不到的站点

装扩展:双击 scripts\install-extension.cmd —— 它复制好扩展、把路径放进剪贴板、打开扩展管理页, 然后一直在那儿等:你点完三下它自己会说「✓ 扩展装上了」,播个视频它再说「✅ 全部完成」。 一个文件、一次双击,装和验证都在里面。步骤与常见错误:docs/BRIDGE.zh.md。

装了之后:你正常打开 Edge 播 B 站,插件就能看到你在第几秒。不用开专用窗口,不用配端口。

扩展上报什么:只有当前可见标签页的 currentTime / duration / title / url / paused, POST 到 127.0.0.1:9377。不读页面内容、不发外网。源码一共 170 行: extension/content.js(读)+ extension/background.js(发)。

插件不会自己开浏览器(这条老路 2026-10-31 已删):多开一个窗口并不能让用户正在看的 那一页报出位置。读不到就问一句「你看到几分几秒了」。

两条通道任意通一条就行,插件优先用扩展那条(更新更勤)。

B. 备用通道:专用窗口(为什么不能直接用你现在的浏览器)

Chromium 136 之后(这台机器的 Edge 是 152)不允许在默认 profile 上开调试端口, 这是微软/谷歌的安全修复,绕不过去。所以那个窗口有它自己的 --user-data-dir=%USERPROFILE%\.dsh\edge-watch:

  • 第一次要在里面登录一次 B 站,之后它一直记着(Cookie 存在那个 profile 里)
  • 你的日常 Edge 完全不受影响,可以同时开着
  • 书签/扩展不在里面 —— 它只是个"看片的窗口"

scripts/start-edge-debug.cmd 就是干这个的,双击即可:

scripts/start-edge-debug.cmd          # 端口 9333
scripts/start-edge-debug.cmd 9444     # 换一个端口

端口写进配置(桌面版读不到 setx 的环境变量,所以推荐写文件):

// ~/.dsh/video.json
{ "browserPort": 9333 }
DSH_BROWSER_DEBUG_PORT=9333      # 或者环境变量
watch_together({ browserPort: 9333 })   // 或者单次传参

端口别用 9222:那是 Chrome DevTools 的惯例端口,WorkBuddy 自己就占着(实测读到的会是它的界面)。

为什么进度会"读不到"(重要)

插件每 15 秒真读一次位置,中间按墙钟外推。三种情况要分清:

状态判断依据行为
读数新鲜(≤5 秒)刚读到直接信
读数 6–16 秒旧正常的外推窗口按墙钟往前推,误差下一次读取就纠回来
超过 20 秒没读到错过了一次读取推出来的位置要多越过 5 秒才敢开口(宁可晚,不能早)
超过 60 秒没读到连错过三次不再推,明确要你报进度

你半路做的动作,它怎么应对

你做什么它怎么做
暂停位置不再变,它安静等着。恢复播放后接着说,不会打扰你
拖进度条跳过去位置立刻跟上;跳过的部分不补说。跳超过 1 分钟会提醒模型一次
拖回去重看位置对了,但看过的段不会重说一遍(避免复读)。也会提醒模型一次
视频播完停下来,叫模型收个尾、问下一支看什么
换一支片子时长/地址变了就认出来,停下来并叫模型重新开始跟这一支
切到别的标签页只有当前可见的标签页上报,所以不会读错标签页
关掉浏览器约 20 秒没消息就问你现在看到哪儿;一直没回应就停表,不空转

暂停、跳转、回看这些都不需要你通知它 —— 它每秒都在读真实进度, 位置永远是对的,只是"说不说话"的策略不同。

读不到最常见的原因:扩展被停用了 / 陪看服务没在跑 / 那个窗口被关了 / 页签切走了。 watch_together({ statusOnly: true }) 可以随时看钟的状态:读到第几秒、可不可信、为什么没说话。 node bin/watch.mjs doctor 会分别列出两条通道各自通不通。

它顺带报三块诊断信息 —— 用户说"后面越来越慢 / 它突然不说话了"时,靠这三块定位卡在哪一环:

字段含什么
segment { index, from, to, delivered, total }在第几段、起止、这一场已交付几段、整片共几段(片长未知时 total 是 null)
speech { queued, lastLateSec, busyUntil }还欠几句台词、上一句比画面晚了几秒、串行声音引擎忙到什么时候
build { inflight, cached, lastMs }正在建哪一段、缓存里已有几段、上一段建了多久

null 一律表示"没测到",不是 0。queued 要读 watch.json,所以只在 statusOnly 里算 (循环每 2 秒付这个 IO 不值得)。

接声音(核心不发声,声音你自己接)

这个包不带任何 TTS 引擎,也不读 ~/.dsh/tts.json。它只做两件事:

  1. 在正确的播放时刻把台词交出去;
  2. 每次结果里带上 speech 事件,at 是这句话在时间轴上的位置。

念不念、用什么念、念多快,全由你(或宿主)决定。

手把手的声音配置教程(挂载适配器、选晓萱等音色、验证、排错)见 docs/VOICE.zh.md。

事件长什么样

watch_together 交付一段时,返回值里有:

"speech": [
  { "at": 191, "text": "钓上来了,池子里那条比他想的配合。", "state": "scheduled", "segment": 180 }
]

后台循环里某句到点时,会把同一条推给你,state 变成 "due"。

同进程:订阅

import { onSpeech } from 'dsh-watch-together/voice';

const off = onSpeech(async ({ state, text }) => {
  if (state !== 'due') return;      // scheduled 只是清单,不是"现在念"
  await mySpeak(text);              // ← 你自己的引擎
});

有人订阅时:到点的台词直接交给订阅者,循环不会再叫醒模型(省 token,也避免同一句被说两遍)。 没人订阅时:台词照旧走"叫醒模型、模型自己说"那条路 —— 功能完整,只是安静。

只做展示的订阅者要传 { voice: false }(聊天框就是这么干的):否则循环会以为"有人会念", 从此不再叫醒模型 —— 陪看会默默地变成哑巴。

别忘了上报"真的出声了":due 只是"该念了",合成还要 0.6~2 秒。悬浮窗里的字等的是 state === 'spoken'(开始播放那一瞬调 api.emitSpoken(e))。不上报也能用,但字会先于声音 出现(2.5 秒兜底),也就是这次修掉的那个不同步。

节奏:宁可少说一句,不要越说越晚

引擎是串行的(一句念完才轮到下一句),所以台词密度直接决定声音会不会越拖越远:

  • 钟会记"引擎到什么时候才空出来"(字数/5 秒),上一句还在说时不会再塞下一句;
  • 拖过迟到宽限(3 秒)的那句直接作废 —— 少说一句,而不是晚 20 秒说;
  • 适配器还能先放弃:排队超过 3.5 秒就跳过这一句,并发 state: 'skipped';
  • 展示层收到 skipped 会撤掉兜底定时器,没出声的字不会出现在悬浮窗里。

所以"台词准时"和"每句都念"是互斥的,这个包选前者。想少丢词就让模型每段少写两句 —— 交付说明里会把每句的落点列出来,平均间隔小于 6 秒时会明确警告"太密"。

现成适配器:examples/voice-edge-tts

带了一个可以直接用的适配器:edge-tts 合成 → ffplay 播放 → 失败退回系统声音。 每一句都会在 stderr 打一行时间码:

[voice 03:11.4] 钓上来了,池子里那条比他想的配合。

调试时最想知道的就是"它到底是第几秒吐出来这句话",这行比音频本身还有用。

启用只要一个文件:

// ~/.dsh/voice.json
{ "adapter": "/dsh-watch-together/examples/voice-edge-tts/index.mjs" }

或者环境变量 DSH_VOICE_ADAPTER=。插件启动时 import() 它,挂不上只写一行 warn, 不会影响插件启动。

最小适配器(一分钟)

// my-voice.mjs
import { execFile } from 'node:child_process';

export function attach({ onSpeech }) {
  return onSpeech(({ state, text }) => {
    if (state === 'due') execFile('say', [text], () => {});   // macOS;换成你自己的引擎
  });
}

attach(api) 收到 { onSpeech, speechSubscribers, emitSpeech, emitSpoken, lastSpeech },返回一个退订函数即可。 想放弃某一句就发 state: 'skipped'(见 docs/VOICE.zh.md)。

聊天框 / 悬浮窗:一条统一的文本流

插话那句和剧本台词走同一条流,一起显示在聊天框里,也一起被念出来:

role是什么会念
line剧本台词(到点由循环写进来)是
assistant模型插话时说的那句是
user你自己打的字否

它们都落在 chat.jsonl(%LOCALAPPDATA%\dsh-video-storyboard\cache\ —— 缓存目录由 dsh-video-storyboard 管,两个插件共用一份)。

模型自己说的话怎么进到框里? 靠 say:

watch_together({ say: "你看这条,鱼比人还紧张。" })

插件读不到模型的正常回复,所以插话时想让用户看见并听见,就得把这句话交给 say。

插话之后:先说话,再干活

用户问一句话,模型常常先去取图/zoom,回来才开口 —— 而"回来"要十几秒,用户那边就是 "叫了它一声,它没理我"。所以 watch_together 有三条硬规则(src/interject.js):

  1. 回插话的那次调用必须带 say,字先写进流,图和清单后到:
    watch_together({ say: "我看一眼", speakNow: true })   // 一次调用,先说再看
    
  2. 没回就追问:下一次工具结果末尾会挂 [未回应] 用户 N 秒前说的「…」你还没回, 直到真的带了 say 为止(3 分钟后自动作废)。
  3. 回话和脚本台词不许挤在一起:你说话之后 12 秒内的脚本台词会被取走 ([lines·太近])交回给模型按刚说的那句重写;那段时间里循环也不会再发词 (src/reply-guard.js)。两句挨着念,声音引擎串行,后一句排太久会被适配器直接丢掉。

三种"停下来"的信号

用户不需要说"别看了"——这三件事本身就是指令,插件会停表,并且像插话一样叫醒模型, 让它在同一轮里知道"别再按旧的跑了":

信号怎么发现之后
关掉悬浮窗钟每 2 秒看一次窗口 pid停表 + [hangup]:不要再调 watch_together、不要再念台词;下一次调用直接返回,不建图、不起钟、不重开窗(除非 open: true)
关掉浏览器 / 切走页签位置读数断了20 秒后一句台词都不再念(位置只能外推,外推过期就不许出声);5 分钟仍读不到就停表
换片 / 播完位置桥的 dur 或视频页地址变了(每 2 秒判一次)停表 + 叫醒:"换片了/播完了";阻塞等待里会当场返回 [video-changed]

关窗为什么必须真的叫醒:wake: false(默认)关的是"这一段该说话了"那种打扰。 关窗/换片/播完不是打扰,是"事情变了"——它们走的是不受那个开关影响的通道。

悬浮窗(不用浏览器)

examples/floating-chat/window.py 是个真·独立悬浮窗:无边框圆角、置顶、 按住顶部拖动、右下角可拉伸、回车发送、Esc 关闭。用标准库 tkinter,不装任何第三方包。

pythonw examples/floating-chat/window.py     # 无控制台

它长这样:剧本台词是琥珀色气泡(左边一道竖线,表示"这句会被念出来")、 模型插话是浅灰气泡、你说的话是蓝色气泡靠右,每条上面一行小字写着谁、什么时候。

几个有意为之的细节:

行为为什么
按真实 DPI 建窗(SetProcessDpiAwareness)不声明的话 Windows 会把窗口当 96dpi 位图拉伸,高分屏上整窗发虚
只做内部焦点,不抢系统焦点窗口一开就把焦点从浏览器抢走的话,敲空格想暂停会打进聊天框
往上翻历史时新消息不把你拽回底部只有本来就贴着底才自动滚
关窗时记住位置和大小(~/.dsh/watch-window.json 的 geometry)下次不用重新摆
增量读 chat.jsonl(开场只回放最后 60 条)以前每 200ms 全量解析,两小时一场几千条会越来越慢
圆角外的像素用 -transparentcolor 抠掉tkinter 没有圆角窗口;取不到这个能力就老实退成直角

一定要用带 tkinter 的 Python:Windows 商店版自带;python.org 官方安装包勾上 tcl/tk 也有。 WorkBuddy 托管的那份没有 tkinter。

它和聊天记录页(http://127.0.0.1:9377/,只读兜底)看的是同一个文件,两个一起开着也不打架。 浏览器置顶小窗(/widget + 画中画)那条老路已经删了 —— 要先开一个标签页、关掉就没了。

命令行(没有 DSH 宿主时)

bin/watch.mjs 是给没有 watch_together 工具的会话(比如普通的终端 AI)用的壳, import 的是同一份 src/。完整用法就是 node bin/watch.mjs help:

命令干什么
doctor自检:插件 / ffmpeg / 端口 / 扩展心跳 / 登录,逐项 OK/FAIL
start [url]起一个带调试端口的专用浏览器窗口(备选通道)
login从浏览器直读 cookie 落盘 + 验 B 站登录
wait [秒]等用户真的放起了视频,返回地址 / 标题 / 时长 / 位置
status当前位置 + 当前段 + 余量 buffer + 下一步该跑什么
fill一次把 5 分钟余量内的段全建好(别一段一段挤)
seg [auto|from to]出这一段的宫格 + 清单 + 句子时间轴
subs [from to]只拉字幕时间轴(不出图,1 秒)
cue '[[at,"词"]]'到点念台词;check 只核对不念
say "文本" / voices立刻念一句 / 列出可用音色
chat / reply起聊天服务 / 替用户回一句
bridge前台盯着扩展上报(排查用)
install-extension装浏览器扩展(三分钟,装完自己验证)

素材:图和字幕是两半,缺一不可

台词来自"看到什么"+"听到什么",所以一段的素材有两半,工具会记账:

一半从哪来记在过去哪
imagestoryboard 九宫格(一次交付给一张)watch.json 的 material[段起点].image
transcript句子 + 每句真实起始秒(字幕轨或 ASR)material[段起点].transcript

两半都交出去过,交付结果里就会出现:

[素材] 图 ✔ 字幕 ✔ —— 两半都到了,现在写台词(`lines`)。

缺一半时它会直接写出下一步该调什么:

[素材] 图 ✔ 字幕 ✘ —— 句子的真实秒数还没有,先取字幕:
  watch_together({ transcriptOnly: true, input: , from: , size:  })

transcriptOnly: true 就是"图与字幕分开返回"那个开关:只给句子和秒数、不出图、不读播放位置。 命令行等价物是 node bin/lines.mjs scan(读的是同一份字幕缓存)。

记住口径:它只记"我交出去过什么",不假装能验证"模型有没有看"—— 但没交出去过的东西,不会被当成素材用。

写台词的两条路(省 token)

写一段台词的代价,全在"看图"上:一张 storyboard 400~700 vision token。 但台词真正需要的只有两件事 —— 这段在说什么、那句话在第几秒,字幕里都有,而且是纯文本。

# 1) 纯文本候选:8~10 句 + 每句真实起始秒,一张图都不解码
node bin/lines.mjs scan --input  --from 180 --size 180

# 2) 直接写进去(秒数可以写 195,也可以写 03:15)
node bin/lines.mjs set --input  --from 180      --at 200 --text "…" --at 250 --text "…"

# 3) 完全不经过模型:按打分选 3 句写进稿子(只是复述字幕,不会"评论")
node bin/lines.mjs auto --input  --from 180 --size 180 --count 3

node bin/lines.mjs list --input      # 哪些段已经写过、各几句
node bin/lines.mjs cues --input  --from 180 --size 60   # 原始字幕,排查用

字幕会缓存在 /subs-.json,同一支片子只抓一次; --refresh 强制重抓,--quiet 关掉头部那行说明。

代价对比(每段):看图写 ≈ 1,200~1,900 token,scan(只看候选句)+ set ≈ 300 token, auto ≈ 0(脚本自己挑,应急用)。auto 只会把字幕复述一遍,它的定位是「这段我懒得管」,不是默认路径 —— 正常还是看图 + 字幕写人话。

它不是全片概览

  • 一次只看一段,看完再下一段
  • 想细看某一格 → video_zoom({ cellId: 3 })(那是 dsh-video-storyboard 的工具)
  • 每段 5 格 ≈ 1,000–1,300 token;90 分钟片约 4.5–6 万 token(是一次性概览的 4–6 倍,换的是"有时间顺序")

长视频:一段短前情(默认关)

段数多了以后,模型可能丢掉上一段发生了什么。需要时显式打开,交付时会附一小段 [前情]:

  • recap: true 或环境变量 DSH_WATCH_RECAP=1 才开启;默认不产生任何前情;
  • 只取当前段之前最近 1~2 段(recapSegments,默认 2,最多 3);
  • 只读本地字幕缓存的原句,不读模型写过的台词槽;
  • 绝不读当前段之后的内容,不会剧透;
  • 整段上限 420 字符(recapMaxChars),超长截断;第一段没有前情,也不额外联网/跑 ASR。

默认关是因为没有实测数据前,每段 200+ token 是纯成本;开启后请自己对照后段是否真的少复述。这段不是全片总结;想看全片概览请另外用 video_storyboard 的概览能力。

代码结构

src/
  index.js          插件入口:只注册 watch_together,并挂上声音与聊天框
  register.js       watch_together 的注册入口
  tool-spec.js      watch_together 的 schema + 兜底校验
  handler.js        watch_together 的 execute

  watch-loop.js     后台循环:每段到点自己叫醒模型
  watch-run.js      一次陪看调用:读位置、建这一段、到点交付
  watch-modes.js    各种等待模式(waitUntil / nextLine / refill)
  watch-actions.js  单发命令(status / voices / speak / cookies / wake / stop)

  watch.js          门面:转发下面两个
  watch-state.js    看到哪儿了:watch.json 读写 + 段长/交付点算术
  watch-lines.js    该说什么了:位置轴上的台词队列
  lines-util.js     不读图也