dsh-bili-watch 0.2.9 → 0.2.11

package/README.md

@@ -17,15 +17,15 @@
 dsh plugin --profile web add dsh-bili-watch
 ```
 
-**第二步易漏**：打开 profile 的 `package.json`，在 `dsh.profile.bundles` 数组里加一行 `"dsh-bili-watch"`。`dsh plugin add` 只写 `dependencies`，不写 bundles。漏了这步插件装了但不生效，也不报错。改完重启 DSH。
+装完重启 DSH 即可。DSH 0.2.0-rc.2 起，`dsh plugin add` 会把包自动写进 profile 的 `dsh.profile.bundles`；若用更早的内核，需要自己打开 profile 的 `package.json`，在 `dsh.profile.bundles` 数组里补一行 `"dsh-bili-watch"`。
 
 装完可以验证：`dsh --profile web --dump-config` 里能搜到 `dsh-bili-watch` 才算进了装配。
 
 也可以把本仓库直接放进 `profiles/<名字>/node_modules/dsh-bili-watch`。
 
-插件依赖 DSH 自带的 `@deepseek-ai/dsh-tools`（peer，optional）。profile 里缺这个包时 `index.js` 会报 `ERR_MODULE_NOT_FOUND`，先补装再重启。
+插件依赖 DSH 自带的 `@deepseek-ai/dsh-tools`（peer，optional）。profile 里缺这个包时不会报错：`bili_watch` 工具不注册，`/bili` 命令与插件面板照常可用，日志里会打一行提示。
 
-插件市场已收录（2026-10-21）：在市场里搜 `dsh-bili-watch` 直接安装，这是最省事的方式；市场里暂时搜不到时，按上面的命令装。
+插件市场已收录（2026-10-21）：在市场里搜 `dsh-bili-watch` 安装。新装插件默认不自动启用，装完到「插件」页把它的开关打开，再重启 DSH；市场里暂时搜不到时，按上面的命令装。
 
 ### 只当命令行工具
 
@@ -43,14 +43,14 @@ dsh plugin --profile web add dsh-bili-watch@latest
 dsh plugin --profile web remove dsh-bili-watch
 ```
 
-升级后重启 DSH。卸载不会删除 `deps/` 里的模型、环境与凭证；要清理就在面板里逐项删，或手动删目录。
+升级后重启 DSH。`deps/` 在包目录内，卸载或重装会连模型、环境、凭证一起删掉；要长期保留就把 `BILI_WATCH_PROJ` / `BILI_WATCH_SEEN` 指到包外。日常清理在面板里逐项删即可。
 
 ## 插件面板
 
 装进 DSH 后，打开插件列表，点 `dsh-bili-watch` 卡片进详情页，里面有一块面板（不用先进设置），常规操作无需去对话里敲命令：
 
-- **依赖状态**：ffmpeg、yt-dlp、ASR 环境、OCR 环境、转写模型、登录凭证逐项列出是否就绪、实际路径、占用体积。缺的点击行末「下载」，后台跑 `scripts/fetch-deps`（体积是估算值，实际以跑完为准）。
-- **扫码登录**：凭证未登录时点「重新扫码」，面板里弹出二维码，手机 B 站扫完自动刷新。凭证保存在本机 `deps/credential.json`。
+- **依赖状态**：ffmpeg、yt-dlp、ASR 环境、OCR 环境、转写模型、登录凭证逐项列出是否就绪、实际路径、占用体积。缺的点击行末「一键下载」，后台跑 `scripts/fetch-deps`（体积是估算值，实际以跑完为准）。
+- **扫码登录**：凭证未登录时点「去扫码登录」（已登录是「重新扫码」），面板里弹出二维码，手机 B 站扫完自动刷新。凭证保存在本机 `deps/credential.json`。
 - **删除**：面板按实际路径判断——装在插件目录里的（yt-dlp、转写模型、登录凭证）可直接删；装在插件目录外的（比如复用系统 ffmpeg 或已有的 Python 环境）按钮置灰，旁边标出它实际在哪。
 - **批量**：标题行的「批量下载 / 批量清理」打开勾选清单，默认勾上所有可操作的项，删除前会再确认一次。
 - **抽帧缓存**：显示当前占用与文件数，「立即清除」一键清空；不点则会按规则自动清理——保留天数（默认 7 天）与总量上限（默认 2048 MB），超过则从最旧的删起。规则存在 `deps/cache-config.json`，插件启动和打开面板时各检查一次。
@@ -123,14 +123,14 @@ macOS/Linux 的 ffmpeg 用系统包管理器装，脚本只给提示。其余目
 | 命令 | 做什么 |
 |---|---|
 | `view <BV或链接或URL>` | 元数据 + 简介 + 热评 |
-| `peek <BV或链接>` | 元数据 + 热评 + 5 张均匀帧（最便宜；仅 B 站） |
-| `sub <BV或链接>` | AI 字幕 + 三判据（字/秒、关键词命中、时长） |
+| `peek <BV或链接>` | 元数据 + 热评 + 5 张均匀帧（最便宜；装了 OCR 环境时会顺带识别这 5 帧，成本略高；仅 B 站） |
+| `sub <BV或链接> [--format srt|json] [--out 文件]` | AI 字幕 + 三判据（字/秒、关键词命中、时长）；`--format` 输出 SRT 或 JSON（带官方时间戳） |
 | `comments <BV> [N]` | 评论区，默认按热度排序 |
 | `asr <BV或URL>` | 本地转写音频 |
 | `frames <BV或URL> [--step 秒] [--ocr]` | 抽帧；`--ocr` 顺带识别画面文字 |
 | `ocr <BV>` | 抽帧并 OCR |
-| `text <BV或URL>` | 四级链：字幕 → 转写 → 抽帧 OCR |
-| `sheet <BV> [--grid 3x3]` | 均匀挑帧拼成一张图（只支持 `3x3` / `4x4`，默认 9 帧） |
+| `text <BV或URL> [--format srt|json]` | 四级链：字幕 → 转写 → 抽帧 OCR；`--format srt|json` 带上时间轴口径（字幕 exact，转写与 OCR 是估算） |
+| `sheet <BV> [--grid 3x3]` | 均匀挑帧拼成一张图（`NxM` 如 `3x3`、`4x4`，默认 9 帧） |
 | `substrip <BV> [--step 秒]` | 底部字幕竖拼成一张图 |
 | `danmaku <BV>` | 弹幕热区（按时间桶统计峰值） |
 | `search <关键词> [--days 3]` | 搜视频 |
@@ -142,6 +142,14 @@ macOS/Linux 的 ffmpeg 用系统包管理器装，脚本只给提示。其余目
 
 表里只列常用参数。完整参数（`--out`、`--fresh`、`--scene`、`--ffmpeg`、`--cred`、`--fast`、`--mark-seen`、`--p` 等）跑 `bili-watch help` 看。
 
+## 单条链接软提示
+
+用户的消息里只有一条 B 站视频链接（BV 号或 `b23.tv` 短链）时，插件往消息流里补一句提示，告诉 agent 有这条链接可读、`peek` 最便宜。它**不会**替用户调用工具，也不会自动跑起来——只是让「贴链接不说话」这种场景不容易被漏掉。
+
+- `b23.tv` 短链只提示不展开（插件不解析短链，会请用户换成浏览器地址栏里的完整链接）。
+- 关掉：`deps/ui-config.json` 里 `"autoHint": false`。
+- 消息里除了链接还有别的文字（问题、指令）时不提示，避免打断正常对话。
+
 ## 通用视频 URL
 
 `view` / `text` / `asr` / `frames` 接受非 B 站 URL（YouTube、X、直链 mp4 等），走 yt-dlp：
@@ -172,11 +180,14 @@ AI 字幕（需登录）
 | `BILI_WATCH_FFMPEG` | ffmpeg 可执行文件路径 |
 | `BILI_WATCH_YTDLP` | yt-dlp 可执行文件路径 |
 | `BILI_WATCH_SEEN` | `seen.md` 去重文件路径（默认 `deps/seen.md`）。文件不存在时 `--mark-seen` 记不了，先建一个空文件即可 |
+| `BILI_WATCH_MIRROR` | `cn` 时 `scripts/fetch-deps.*` 走镜像下载（gh-proxy / 清华 PyPI / hf-mirror） |
+| `HF_ENDPOINT` | 转写模型的 HuggingFace 端，默认 `https://hf-mirror.com`；海外可设官方站 |
+| `BILI_ASR_MODEL` | 本地转写用的 faster-whisper 模型名，默认 `small` |
 
 ## 成本
 
 - 字幕接口带一次重试；`text` 最多次试两次（先匿名、有凭证再试一次）。
-- 抽帧会下载视频（360p）并跑 ffmpeg。`--step` 调低抽帧频率，脚本另外限了 `-threads 2`。
+- 抽帧会下载视频（360p）并跑 ffmpeg。`--step` 的秒数调大能减少抽帧数，脚本另外限了 `-threads 2`。
 - 拼图和字幕带把多帧压成一张图，省 token。
 
 ## 限制与风险

package/auto-trigger.js

@@ -10,7 +10,7 @@ const RE_FULL = /https?:\/\/(?:www\.|m\.)?bilibili\.com\/video\/(BV[0-9A-Za-z]{1
 // 短链：能识别，但 look.mjs 不能展开（tools/look.mjs:1249-1251），调用方要单独处理
 const RE_SHORT = /https?:\/\/b23\.tv\/[0-9A-Za-z]{5,12}(?:[/?#][^\s<>"'）)]*)?/gi
 // ?bvid=BV… 形态（tools/look.mjs:1254 支持）
-const RE_BVID_Q = /[?&]bvid=(BV[0-9A-Za-z]{10})/gi
+const RE_BVID_Q = /https?:\/\/(?:www\.|m\.)?bilibili\.com\/video\/[^\s<>"'）)]*?[?&]bvid=(BV[0-9A-Za-z]{10})[^\s<>"'）)]*/gi
 // 裸 BV 号：前后不许粘字母数字
 const RE_BARE = /(?<![0-9A-Za-z])BV[0-9A-Za-z]{10}(?![0-9A-Za-z])/g
 
@@ -33,6 +33,9 @@ function stripWrappers(raw) {
       return ' '
     })
   }
+  // `<https://…>` 是常见自动链接写法；标签块已整段删掉之后，再剥掉包着单个
+  // 无空格 token 的尖括号，避免把 <system-reminder> 这类壳提前破坏。
+  text = text.replace(/<([^<>\s]{8,})>/g, '$1')
   const kept = []
   for (const ln of text.split('\n')) {
     if (/^\s*>/.test(ln)) {

package/client.js

@@ -15,7 +15,7 @@ window.__ModuleLoader__.load({
     const React = require('react')
     const h = React.createElement
 
-    // 包名：生产插件是 dsh-bili-watch，发布树派生时改成 dsh-bili-watch
+    // 包名 = 插件详情页挂点的 key：生产与发布树同名 dsh-bili-watch
     const PKG = 'dsh-bili-watch'
     const API = '/api/bili-watch'
     const jget = async (p) => (await fetch(API + p, { credentials: 'same-origin' })).json()
@@ -96,21 +96,6 @@ window.__ModuleLoader__.load({
       )
     }
 
-    // 设置页入口：先在插件详情页关掉「在设置页显示」时，这里自动隐身
-    function SettingsPanel() {
-      const [show, setShow] = React.useState(null)
-      React.useEffect(() => {
-        jget('/status')
-          .then((j) => setShow(j.ok && j.data.ui?.showInSettings !== false))
-          .catch(() => setShow(false))
-        const onUi = (e) => setShow(!!e?.detail?.showInSettings)
-        window.addEventListener('bili-watch-ui', onUi)
-        return () => window.removeEventListener('bili-watch-ui', onUi)
-      }, [])
-      if (!show) return null
-      return h(Panel, null)
-    }
-
     function Panel() {
       const [st, setSt] = React.useState(null)
       const [err, setErr] = React.useState('')

package/index.js

@@ -92,7 +92,7 @@ const QR_POLL = (key) =>
 const SPI = 'https://api.bilibili.com/x/frontend/finger/spi'
 
 const name = 'dsh-bili-watch'
-const inject = ['commands', 'tools', 'webServer', 'agents']
+const inject = ['commands', 'webServer', 'agents']
 
 function runLook(args, { timeoutMs = 1_200_000 } = {}) {
   return new Promise((resolve) => {
@@ -445,11 +445,23 @@ function runDownload(target) {
   try {
     appendFileSync(DOWNLOAD_LOG, `[${new Date().toISOString()}] 开始下载 ${target}\n`, 'utf8')
   } catch {}
-  const child = spawn(
-    'powershell.exe',
-    ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, '-Target', target],
-    { windowsHide: true, stdio: 'ignore', detached: true },
-  )
+  const win = process.platform === 'win32'
+  const cmd = win ? 'powershell.exe' : 'bash'
+  const args = win
+    ? ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, '-Target', target]
+    : [script.replace(/\.ps1$/i, '.sh'), target]
+  let child = null
+  try {
+    child = spawn(cmd, args, { windowsHide: true, stdio: 'ignore', detached: true })
+  } catch (e) {
+    return { started: false, error: String(e?.message ?? e) }
+  }
+  // detached 子进程不会把 spawn 失败同步抛给我们，必须自己接 error，否则 ENOENT 会带崩宿主
+  child.on('error', (e) => {
+    try {
+      appendFileSync(DOWNLOAD_LOG, `[${new Date().toISOString()}] 启动失败 ${target}：${e?.message ?? e}\n`, 'utf8')
+    } catch {}
+  })
   child.unref()
   return { started: true, log: DOWNLOAD_LOG }
 }
@@ -517,7 +529,7 @@ function parseCommandLine(raw) {
     .split(/\s+/)
     .filter(Boolean)
   const command = tokens.shift()
-  const bv = tokens.length && !tokens[0].startsWith('--') ? tokens.shift() : ''
+  const positionals = []
   const extra = []
   let step = ''
   let cred = ''
@@ -543,12 +555,16 @@ function parseCommandLine(raw) {
       extra.push('--out', tokens.shift())
     } else if (t === '--ffmpeg' && tokens.length) {
       extra.push('--ffmpeg', tokens.shift())
+    } else if (t === '--format' && tokens.length) {
+      extra.push('--format', tokens.shift())
     } else if (t === '--fresh' || t === '--ocr' || t === '--poll' || t === '--check' || t === '--fast' || t === '--scene' || t === '--mark-seen') {
       extra.push(t)
+    } else if (!t.startsWith('--')) {
+      // 非选项 token 都当位置参数收着：BV / 搜索词 / 评论条数都可能出现在选项前后
+      positionals.push(t)
     }
-    // 其余 token 直接丢弃（命令本身不接受别的参数）
   }
-  return { command, bv, extra, step, cred }
+  return { command, bv: positionals[0] || '', extra, step, cred }
 }
 
 async function lookup({ command, bv, extra = [] }) {
@@ -586,7 +602,7 @@ function apply(ctx) {
     name: 'bili',
     description: '看 B 站视频内容：字幕 → 本地转写 → 抽帧 OCR，输出最可信的一份文本',
     input: {
-      hint: '<search 关键词|hot|peek|view|sub|comments|danmaku|asr|frames|sheet|substrip|ocr|text|login|clean> [BV] [--p N] [--step 2] [--days 3] [--order pubdate|click] [--cred 凭证路径] [--fast] [--scene] [--grid 3x3]',
+      hint: '<search 关键词|hot|peek|view|sub|comments|danmaku|asr|frames|sheet|substrip|ocr|text|login|clean> [BV] [--p N] [--step 2] [--days 3] [--order pubdate|click] [--cred 凭证路径] [--fast] [--scene] [--grid 3x3] [--format srt|json] [--out 文件]',
     },
     handler: async (invocation) => {
       const { command, bv, extra } = parseCommandLine(invocation?.rawInput)
@@ -644,7 +660,7 @@ function apply(ctx) {
   // ② 同名工具：模型可调，需要看视频时自己来，不依赖用户敲命令
   //    必须用 defineTool 包一层：ctx.tools.register 收的是编译好的 tool 对象，
   //    直接传 options 会让发往模型的 parameters 变成 null（报 INVALID_REQUEST: schema must be type "object"）。
-  if (defineTool) {
+  if (defineTool && ctx.tools) {
   ctx.tools.register(defineTool({
     name: 'bili_watch',
     description:
@@ -689,6 +705,18 @@ function apply(ctx) {
         type: 'string',
         description: 'command=sheet 时的格子，如 3x3 或 4x4（默认 3x3）。',
       },
+      format: {
+        type: 'string',
+        description: 'command=sub 时可选 srt 或 json（带官方时间戳）；command=text 时可选 json（含时间轴口径：字幕 exact，转写与 OCR 是估算）。不传默认纯文本。',
+      },
+      out: {
+        type: 'string',
+        description: 'command=sub/text 且传了 format 时，把结果写到这个文件路径；不传打印到标准输出。',
+      },
+      limit: {
+        type: 'number',
+        description: 'command=hot/search 的结果条数（hot 默认 10，search 默认 10）。',
+      },
     },
     output: {
       // 注意：DSH 的 output.schema 是「author-facing spec」，编译时 allowRequired=false，
@@ -712,8 +740,18 @@ function apply(ctx) {
       if (args.scene) extra.push('--scene')
       if (typeof args.grid === 'string' && args.grid.trim()) extra.push('--grid', args.grid.trim())
       if (typeof args.days === 'number' && args.days > 0) extra.push('--days', String(Math.floor(args.days)))
+      if (typeof args.limit === 'number' && args.limit > 0) extra.push('--limit', String(Math.floor(args.limit)))
+      if (typeof args.format === 'string' && args.format.trim()) extra.push('--format', args.format.trim())
+      if (typeof args.out === 'string' && args.out.trim()) {
+        const out = args.out.trim()
+        // 工具层是模型可调的：只允许写工作区内的相对路径，挡住绝对路径 / 盘符 / .. 与家目录
+        if (/^([/\\]|[A-Za-z]:|~)|\.\./.test(out)) {
+          return { ok: false, text: '--out 只接受工作区内的相对路径（不能用绝对路径、盘符、~ 或 ..）' }
+        }
+        extra.push('--out', out)
+      }
       if (args.command === 'hot') {
-        const r = await lookup({ command: 'hot', bv: '' })
+        const r = await lookup({ command: 'hot', bv: '', extra })
         return { ok: r.ok, text: r.text }
       }
       const target = args.command === 'search' ? String(args.keyword ?? '').trim() : String(args.bv ?? '').trim()
@@ -812,4 +850,4 @@ function apply(ctx) {
   }
 }
 
-export { apply, inject, name }
+export { apply, inject, name, parseCommandLine }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-bili-watch",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "private": false,
   "description": "Reads Bilibili (and generic URLs via yt-dlp) into text for DSH agents: search, hot, metadata, comments, danmaku, AI subtitles, local ASR, frame OCR.",
   "type": "module",

package/scripts/fetch-deps.ps1

@@ -181,7 +181,7 @@ function Ensure-Model {
     return
   }
   $env:HF_HOME = $hfHome
-  $env:HF_ENDPOINT = $HfEndpoint
+  if (-not $env:HF_ENDPOINT) { $env:HF_ENDPOINT = $HfEndpoint }
   $env:HF_HUB_DISABLE_XET = '1'
   & $asrPy -c "from huggingface_hub import snapshot_download; print(snapshot_download('Systran/faster-whisper-small'))"
   if ($LASTEXITCODE -ne 0) { throw '模型下载失败' }

package/scripts/fetch-deps.sh

@@ -24,11 +24,11 @@ MIRROR="${BILI_WATCH_MIRROR:-}"
 if [ "$MIRROR" = "cn" ]; then
   GH="https://gh-proxy.com/https://github.com"
   PY_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
-  HF_ENDPOINT="https://hf-mirror.com"
+  HF_ENDPOINT="${HF_ENDPOINT:-https://hf-mirror.com}"
 else
   GH="https://github.com"
   PY_INDEX="https://pypi.org/simple"
-  HF_ENDPOINT="https://huggingface.co"
+  HF_ENDPOINT="${HF_ENDPOINT:-https://huggingface.co}"
 fi
 
 fetch_ytdlp() {

package/tools/look.mjs

@@ -234,7 +234,7 @@ async function fetchSubtitle(aid, cid, headers = H) {
       notes.push(`第 ${i + 1} 次：内容为空`)
       continue
     }
-    return { ok: true, text, lan: track.lan, tries: i + 1, notes }
+    return { ok: true, text, cues: sj.body ?? [], lan: track.lan, tries: i + 1, notes }
   }
   return { ok: false, text: '', notes, why: `试了 2 次都没拿到（${notes.join('；')}）` }
 }
@@ -664,16 +664,101 @@ async function cmdView(bv, p = 1) {
   return v
 }
 
-async function cmdSub(bv, credPath, p = 1) {
+// SRT 时间戳：HH:MM:SS,mmm（from/to 是秒，可能带小数）
+function fmtSrtTime(sec) {
+  // 整体按毫秒取整再拆，避免 Math.round 把小数位凑成 1000（非法 SRT 时间戳）
+  const totalMs = Math.max(0, Math.round((Number(sec) || 0) * 1000))
+  const h = Math.floor(totalMs / 3600000)
+  const m = Math.floor(totalMs / 60000) % 60
+  const s = Math.floor(totalMs / 1000) % 60
+  const ms = totalMs % 1000
+  const p = (n, w = 2) => String(n).padStart(w, '0')
+  return `${p(h)}:${p(m)}:${p(s)},${p(ms, 3)}`
+}
+
+// 只给有时间的档用（字幕档是官方时间戳；ASR 档是估算，调用方要自己标 .estimated）
+function cuesToSrt(cues) {
+  const rows = []
+  let n = 0
+  for (const c of cues || []) {
+    const text = String(c?.content ?? '').trim()
+    if (!text) continue
+    const a = Number(c?.from ?? 0)
+    const b = Number(c?.to ?? 0)
+    n++
+    rows.push(String(n), `${fmtSrtTime(a)} --> ${fmtSrtTime(Math.max(b, a))}`, text, '')
+  }
+  return rows.join('\n')
+}
+
+// text 命令的 --format json：把「这一档拿到的东西 + 时间轴口径」一起吐出去
+function emitTextJson(opts, payload) {
+  if (String(opts?.format || '').toLowerCase() !== 'json') return false
+  const text = JSON.stringify(payload, null, 2)
+  if (opts.out) {
+    writeFileSync(opts.out, text, 'utf8')
+    console.log(`✓ 已写入 ${opts.out}（source=${payload.source}）`)
+  } else console.log(text)
+  return true
+}
+
+// --format 输出结构化数据时，过程说明一律走 stderr，保证 stdout 能被 jq / 管道直接消费
+let QUIET = false
+const say = (...a) => (QUIET ? console.error : console.log)(...a)
+
+async function cmdSub(bv, credPath, p = 1, opts = {}) {
+  QUIET = opts.format === 'srt' || opts.format === 'json'
+  const format = String(opts.format || 'text').toLowerCase()
+  const out = String(opts.out || '')
+  if (out && format !== 'json' && format !== 'srt') {
+    console.log('✗ --out 要配合 --format srt|json；纯文本会直接打印到标准输出')
+    process.exitCode = 1
+    return
+  }
+  if (!['text', 'json', 'srt'].includes(format)) {
+    console.log(`✗ 不认识的 --format：${format}（可选 text|srt|json）`)
+    process.exitCode = 1
+    return
+  }
   const cred = credFor(credPath)
   const v = await viewOf(bv, p)
   const pTag = v.pages > 1 ? `（P${v.p}/${v.pages}）` : ''
-  console.log(`视频: ${v.title}  UP: ${v.owner}  时长 ${fmtSec(v.dur)}${pTag}${cred ? '（带凭证）' : '（匿名）'}`)
+  say(`视频: ${v.title}  UP: ${v.owner}  时长 ${fmtSec(v.dur)}${pTag}${cred ? '（带凭证）' : '（匿名）'}`)
   const s = await fetchSubtitle(v.aid, v.cid, headersFor(cred))
   if (!s.ok) {
     console.log(`\n✗ 字幕取不到：${s.why}`)
     console.log(`  ${cred ? '换匿名再试：' : '有凭证可加 --cred：'}node look.mjs sub ${bv}${cred ? '' : ' --cred <凭证>'}`)
     console.log(`  无字幕轨时走：node look.mjs text ${bv}（ASR → OCR）`)
+    process.exitCode = 1
+    return
+  }
+  if (format === 'json' || format === 'srt') {
+    const cues = Array.isArray(s.cues) ? s.cues : []
+    const usable = cues.filter((c) => String(c?.content ?? '').trim()).length
+    if (usable === 0) {
+      console.log('\n✗ 字幕轨里没有可用文案（0 条），不写空文件')
+      process.exitCode = 1
+      return
+    }
+    if (format === 'srt') {
+      const text = cuesToSrt(cues)
+      if (out) {
+        writeFileSync(out, text, 'utf8')
+        console.log(`✓ 已写入 ${out}（${usable} 条，官方时间戳）`)
+      } else console.log(text)
+      return
+    }
+    const payload = {
+      video: { bv, title: v.title, up: v.owner, dur: v.dur, p: v.p, pages: v.pages },
+      lan: s.lan ?? null,
+      timeline: { exact: true, source: 'official-subtitle' },
+      cues: cues.map((c) => ({ from: Number(c?.from ?? 0), to: Number(c?.to ?? 0), content: String(c?.content ?? '') })),
+    }
+    const text = JSON.stringify(payload, null, 2)
+    if (out) {
+      writeFileSync(out, text, 'utf8')
+      console.log(`✓ 已写入 ${out}（${payload.cues.length} 条）`)
+    } else console.log(text)
     return
   }
   const c = credibility(v, s.text)
@@ -885,6 +970,7 @@ async function cmdAsr(bv, p = 1, ffmpeg = '') {
   const r = await transcribe(bv, { p, ffmpeg })
   if (!r.ok) {
     console.log(`\n✗ ${r.why}`)
+    process.exitCode = 1
     return
   }
   console.log(`\n转写 ${r.chars} 字：\n${r.text}`)
@@ -1134,6 +1220,7 @@ function markSeen(bv, title) {
 
 /** 四级链：字幕 → ASR → 抽帧 OCR。输出最可信的一份文本。 */
 async function cmdText(bv, credPath, opts = {}) {
+  QUIET = opts.format === 'json'
   const t0 = Date.now()
   const cred = credFor(credPath)
   const v = await viewOf(bv, opts.p)
@@ -1141,12 +1228,12 @@ async function cmdText(bv, credPath, opts = {}) {
   const done = () => {
     if (!opts.mark) return
     const ok = markSeen(bv, v.title)
-    console.log(`[track] seen: ${ok ? '已记一笔' : '记不了（seen.md 不存在）'}`)
+    say(`[track] seen: ${ok ? '已记一笔' : '记不了（seen.md 不存在）'}`)
   }
   const pTag = v.pages > 1 ? `（P${v.p}/${v.pages}）` : ''
-  console.log(`视频: ${v.title}  UP: ${v.owner}  时长 ${fmtSec(v.dur)}${pTag}`)
+  say(`视频: ${v.title}  UP: ${v.owner}  时长 ${fmtSec(v.dur)}${pTag}`)
   const budget = v.dur > 900 ? '约 2–4 分钟' : v.dur > 300 ? '约 1–3 分钟' : '约 30–90 秒'
-  console.log(`[track] 预算：${v.dur <= 1800 ? budget : '视频超过 30 分钟，字幕取不到会跳过转写直接走画面'}`)
+  say(`[track] 预算：${v.dur <= 1800 ? budget : '视频超过 30 分钟，字幕取不到会跳过转写直接走画面'}`)
 
   // ① 字幕（匿名先试；失败且有凭证再试登录态——AI 字幕轨要登录）
   let s = await fetchSubtitle(v.aid, v.cid, H)
@@ -1160,58 +1247,94 @@ async function cmdText(bv, credPath, opts = {}) {
   // 信道优先：官方字幕能拿到就是可信内容，语速/关键词只作提示，不拦
   // 口径差异（有意）：自动化选片链路会把「语速/关键词不合格」当硬拦，
   // 这里是人看的排查通道，取到就用、质量交给调用方判断。同一判据两种策略，别当 bug 报。
-    console.log(`[track] ${via}: ok ${s.text.length} 字（语速 ${c.sp.rate ?? '?'} 字/秒，关键词 ${c.ks.hit}/${c.ks.total}）`)
+    if (emitTextJson(opts, {
+      video: { bv, title: v.title, up: v.owner, dur: v.dur, p: v.p, pages: v.pages },
+      source: 'subtitle',
+      lan: s.lan ?? null,
+      timeline: { exact: true, source: 'official-subtitle' },
+      cues: (s.cues || []).map((c) => ({ from: Number(c?.from ?? 0), to: Number(c?.to ?? 0), content: String(c?.content ?? '') })),
+      text: s.text,
+    })) {
+      done()
+      return
+    }
+    say(`[track] ${via}: ok ${s.text.length} 字（语速 ${c.sp.rate ?? '?'} 字/秒，关键词 ${c.ks.hit}/${c.ks.total}）`)
     console.log(`\n${s.text}`)
     done()
     return
   }
-  console.log(`[track] 字幕: miss（${s.why}）`)
+  say(`[track] 字幕: miss（${s.why}）`)
 
   // ② 本地 ASR 转写（无字幕时最靠谱，零 token；--fast 跳过，直接走画面）
   if (!opts.fast && asrReady() && v.dur > 1800) {
-    console.log(`[track] 转写: skip（时长 ${fmtSec(v.dur)} 超过 30 分钟，转写会超时）`)
+    say(`[track] 转写: skip（时长 ${fmtSec(v.dur)} 超过 30 分钟，转写会超时）`)
   }
   if (!opts.fast && asrReady() && v.dur <= 1800) {
-    console.log(`[track] 转写: 开始（faster-whisper，最多等 3 分钟）…`)
+    say(`[track] 转写: 开始（faster-whisper，最多等 3 分钟）…`)
     const a = await transcribe(bv, { timeoutMs: 180_000, p: v.p })
     if (a.ok) {
       // 口播类正常 4–6 字/秒；低于 2 字/秒多半是背景音乐、外语歌或纯画面，
       // 这时候转写出来的「字」只是把杂音听成了字，继续往下走 OCR 更靠谱。
       const rate = v.dur > 0 ? a.chars / v.dur : 0
       if (rate >= 2) {
-        console.log(`[track] 转写: ok ${a.chars} 字（${rate.toFixed(1)} 字/秒${a.cached ? '，缓存命中' : ''}；机器转写，专有名词可能有错）`)
+        if (emitTextJson(opts, {
+          video: { bv, title: v.title, up: v.owner, dur: v.dur, p: v.p, pages: v.pages },
+          source: 'asr',
+          timeline: { exact: false, source: 'asr-estimate', note: '无官方时间戳；按标点与字数估算' },
+          text: a.text,
+        })) {
+          done()
+          return
+        }
+        say(`[track] 转写: ok ${a.chars} 字（${rate.toFixed(1)} 字/秒${a.cached ? '，缓存命中' : ''}；机器转写，专有名词可能有错）`)
         console.log(`\n${a.text}`)
         done()
         return
       }
-      console.log(`[track] 转写: 质量低（${a.chars} 字，${rate.toFixed(1)} 字/秒），继续往下试`)
+      say(`[track] 转写: 质量低（${a.chars} 字，${rate.toFixed(1)} 字/秒），继续往下试`)
     } else {
-      console.log(`[track] 转写: miss（${a.why}）`)
+      say(`[track] 转写: miss（${a.why}）`)
     }
   } else if (opts.fast) {
-    console.log(`[track] 转写: skip（--fast）`)
+    say(`[track] 转写: skip（--fast）`)
   } else if (!asrReady()) {
-    console.log(`[track] 转写: skip（环境不可用）`)
+    say(`[track] 转写: skip（环境不可用）`)
   }
 
   // ③ 抽帧 OCR（画面文字转文本）
   if (ocrReady()) {
-    console.log(`[track] 画面 OCR: 抽帧…`)
+    say(`[track] 画面 OCR: 抽帧…`)
     const r = await grabFrames(bv, { step: opts.step ?? 0, p: v.p })
     const text = await runOcr(r.dir)
     if (text && !text.startsWith('[ocr] 失败')) {
-      console.log(`[track] 画面 OCR: ok（${r.dir}；这是画面上的字，不是口播内容）`)
+      if (emitTextJson(opts, {
+        video: { bv, title: v.title, up: v.owner, dur: v.dur, p: v.p, pages: v.pages },
+        source: 'ocr',
+        timeline: { exact: false, source: 'frame-ocr', step: opts.step ?? 'auto' },
+        text,
+      })) {
+        done()
+        return
+      }
+      say(`[track] 画面 OCR: ok（${r.dir}；这是画面上的字，不是口播内容）`)
       console.log(`\n${text}`)
       done()
       return
     }
-    console.log(`[track] 画面 OCR: miss（${text.slice(0, 160)}）`)
+    say(`[track] 画面 OCR: miss（${text.slice(0, 160)}）`)
   } else {
-    console.log(`[track] 画面 OCR: skip（环境不可用）`)
+    say(`[track] 画面 OCR: skip（环境不可用）`)
   }
 
   // ④ 兜底：抽帧读图
-  console.log(`[track] 兜底：抽帧交给模型读图（已耗时 ${Math.round((Date.now() - t0) / 1000)}s）`)
+  if (emitTextJson(opts, {
+    video: { bv, title: v.title, up: v.owner, dur: v.dur, p: v.p, pages: v.pages },
+    source: 'vision',
+    timeline: { exact: false, source: 'frames-for-vision' },
+    text: '',
+    note: '没有可直接导出的文本；已抽帧，交给模型读图',
+  })) return
+  say(`[track] 兜底：抽帧交给模型读图（已耗时 ${Math.round((Date.now() - t0) / 1000)}s）`)
   await cmdFrames(bv, { step: opts.step ?? 0, p: v.p })
 }
 
@@ -1219,7 +1342,7 @@ async function cmdText(bv, credPath, opts = {}) {
 const argv = process.argv.slice(2)
 const cmd = argv[0]
 // 带值的选项：解析位置参数时必须跳过它们的值，否则 `hot --limit 2` 会把 "2" 当成 BV
-const VALUE_OPTS = new Set(['cred', 'days', 'ffmpeg', 'grid', 'key', 'limit', 'order', 'out', 'p', 'step'])
+const VALUE_OPTS = new Set(['cred', 'days', 'ffmpeg', 'grid', 'key', 'limit', 'order', 'out', 'p', 'step', 'format'])
 function positional(list) {
   const out = []
   for (let i = 0; i < list.length; i++) {
@@ -1235,6 +1358,9 @@ function positional(list) {
 }
 const pos = positional(argv)
 const opt = (name, dflt) => {
+  // 兼容 `--name value` 与 `--name=value`（后者以前会被静默忽略，退回默认值）
+  const eq = argv.find((a) => a.startsWith(`--${name}=`))
+  if (eq) return eq.slice(name.length + 3)
   const i = argv.indexOf(`--${name}`)
   return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : dflt
 }
@@ -1473,7 +1599,7 @@ const HELP = `用法:
   node look.mjs hot [--limit 10]              综合热门榜（B 站按热度排）
   node look.mjs peek <BV或链接>              先看标题/简介/热评 + 5 帧，判断内容类型（仅 B 站）
   node look.mjs view <BV或链接或URL>         只看元数据与热评
-  node look.mjs sub <BV或链接> [--cred 凭证路径]   字幕（仅 B 站）
+  node look.mjs sub <BV或链接> [--cred 凭证路径] [--format srt|json] [--out 文件]  字幕（仅 B 站）
   node look.mjs comments <BV或链接> [条数]    评论区（仅 B 站）
   node look.mjs danmaku <BV或链接>           弹幕热区（仅 B 站）
   node look.mjs asr <BV或链接或URL> [--ffmpeg 路径]  本地转写（B 站或通用 URL 均可）
@@ -1482,16 +1608,17 @@ const HELP = `用法:
   node look.mjs sheet <BV或链接> [--grid 3x3] [--step 2]   N 帧拼一张九宫格（仅 B 站）
   node look.mjs substrip <BV或链接> [--step 7]          底部字幕带竖拼一张图（仅 B 站）
   node look.mjs ocr <BV或链接> [--step 2]     抽帧 + OCR 出文字（仅 B 站）
-  node look.mjs text <BV或链接或URL> [--cred 凭证路径] [--step 2] [--fast] [--mark-seen]
+  node look.mjs text <BV或链接或URL> [--cred 凭证路径] [--step 2] [--fast] [--mark-seen] [--format json] [--out 文件]
   node look.mjs login [--poll] [--check]    扫码登录，拿 AI 字幕用的本地凭证
   node look.mjs clean
 
   多 P 视频加 --p N 指定第几个分P（默认 P1）。
+  --format srt|json：sub 给官方字幕的真时间戳；text 的 json 会带时间轴口径（字幕 exact / 转写与 OCR 是估算）。
   B 站目标可以直接贴分享链接，会自己提取 BV 号；短链 b23.tv/... 要先展开成完整链接。
   通用视频 URL（YouTube/X 等）需要 yt-dlp：跑 scripts/fetch-deps.ps1 -Target ytdlp 装到 deps\\yt-dlp.exe（或设 BILI_WATCH_YTDLP / 系统 PATH）。
 `
 try {
-  if (srcErr || src.type === 'error') {
+  if (srcErr || (src.type === 'error' && cmd !== 'search' && cmd !== 'hot')) {
     console.error(`✗ ${srcErr || src.message}`)
     process.exit(1)
   }
@@ -1510,7 +1637,7 @@ try {
   } else if (cmd === 'view') {
     await cmdView(BV, P)
   } else if (cmd === 'sub') {
-    await cmdSub(BV, CRED, P)
+    await cmdSub(BV, CRED, P, { format: opt('format') || 'text', out: opt('out') || '' })
   } else if (cmd === 'comments') {
     await cmdComments(BV, Number(pos[2] || 10))
   } else if (cmd === 'danmaku') {
@@ -1526,7 +1653,7 @@ try {
   } else if (cmd === 'ocr') {
     await cmdOcr(BV, { step: STEP, p: P })
   } else if (cmd === 'text') {
-    await cmdText(BV, CRED, { step: STEP, p: P, fast: flag('fast'), mark: flag('mark-seen') })
+    await cmdText(BV, CRED, { step: STEP, p: P, fast: flag('fast'), mark: flag('mark-seen'), format: opt('format') || 'text', out: opt('out') || '' })
   } else if (cmd === 'clean') {
     if (existsSync(CACHE)) {
       rmSync(CACHE, { recursive: true, force: true })