dsh-bili-watch 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sacredbluedragon
+
+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,146 @@
-# Temporary Holding Version
+# dsh-bili-watch
 
-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.
+给 AI「看」B 站视频的 DSH 插件：元数据、AI 字幕、评论区、本地转写、抽帧 OCR、九宫格拼图、弹幕热区。
+
+一句话：模型能直接看一条 B 站视频——先用最便宜的方式拿到文字，文字不够再看画面。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-bili-watch
+```
+
+**第二步不能省**：打开 profile 的 `package.json`，在 `dsh.profile.bundles` 数组里加一行 `"dsh-bili-watch"`。`dsh plugin add` 只写 `dependencies`，不写 bundles——漏了这一步插件装了但完全不生效（不报错、无入口）。装完重启 DSH。
+
+也可以把本仓库直接放到 `profiles/<名字>/node_modules/dsh-bili-watch`。
+
+> 插件依赖 DSH 自带的 `@deepseek-ai/dsh-tools`（peer，optional）。若 profile 缺这个内核工具包，`index.js` 会报 `ERR_MODULE_NOT_FOUND`，先补装再重启。
+
+## 依赖
+
+| 能力 | 需要 | 没有时 |
+|---|---|---|
+| 元数据 / 评论 / 弹幕 / 搜索 / 热榜 | 无（匿名 HTTP） | — |
+| 抽帧 / 九宫格 / 字幕带 | `ffmpeg` | 跳过，文字档仍可用 |
+| AI 字幕 | 一次扫码登录（SESSDATA） | 返回「无字幕轨」，自动降级 |
+| 本地转写 | Python 3.10+ 与 faster-whisper（`deps/.venv-asr`） | 跳过，自动降级 |
+| 画面 OCR | Python 3.10+ 与 rapidocr_onnxruntime（`deps/.venv-ocr`） | 跳过，只剩基础抽帧 |
+| 通用视频 URL | yt-dlp | 只支持 B 站 |
+
+前置：Node.js ≥ 22（插件运行环境本身就有 node，命令行跑也一样）。
+
+`ffmpeg` 查找顺序：`--ffmpeg` 参数 → `BILI_LOOK_FFMPEG` → 插件 `deps/` → PATH。
+
+`deps/` 是运行期目录：Python venv、模型缓存、yt-dlp、凭证都放这里，默认不进 git（见 `.gitignore`）。ASR/OCR 的 Python 环境是**可选依赖**，不配也能用，只是会少两档。
+
+`deps/_bili-asr.py` 默认从 `hf-mirror.com` 下载模型（国内快）；海外网络可先设 `HF_ENDPOINT=https://huggingface.co` 再跑 `fetch-deps`。
+
+### 可选依赖（一键安装）
+
+```powershell
+# Windows（powershell.exe 或 pwsh 都可以）
+powershell -ExecutionPolicy Bypass -File scripts\fetch-deps.ps1 -Target all
+powershell -ExecutionPolicy Bypass -File scripts\fetch-deps.ps1 -Target all -Mirror cn   # 国内网络：gh-proxy + 清华 PyPI + hf-mirror
+
+# 单项：ffmpeg / ytdlp / asr / ocr / model
+powershell -ExecutionPolicy Bypass -File scripts\fetch-deps.ps1 -Target ytdlp
+powershell -ExecutionPolicy Bypass -File scripts\fetch-deps.ps1 -Target model
+```
+
+```bash
+# macOS / Linux
+bash scripts/fetch-deps.sh all
+BILI_LOOK_MIRROR=cn bash scripts/fetch-deps.sh all
+```
+
+脚本是幂等的：目标已存在就跳过，`-Force` 重下（Windows）；`-DryRun` 只打印命令、不下载。装 venv 时会验证包能不能 import，上次装到一半的半成品会被自动重建。`-Target model` 依赖 ASR 环境先装好（脚本会提示）。
+
+**GitHub 下载不动怎么办**：ffmpeg 目标要从 GitHub 拉约 80 MB 的 BtbN 压缩包，国内直连经常断。三条替代路径：
+
+1. 加 `-Mirror cn` 重试（走 gh-proxy）；
+2. 手动下载 `ffmpeg.exe` 放进 `deps\` 后重跑（会被跳过）；
+3. 已有 ffmpeg 就设 `BILI_LOOK_FFMPEG` 指向它。
+
+macOS/Linux 的 ffmpeg 由系统包管理器安装（脚本只给提示），其余目标与 Windows 一致；sh 版本单项失败会继续跑完再汇总。
+
+## 凭证
+
+**匿名也能用**：元数据、评论、抽帧、弹幕都不需要登录。
+
+只有「拿 AI 字幕」需要登录，二选一：
+
+1. `login`：插件出二维码，手机 B 站扫码。凭证存插件 `deps/credential.json`，不出本机。
+2. `--cred <文件路径>`：读一份现成的 `{sessdata, bili_jct, buvid3, buvid4}` JSON。
+
+凭证取值：给了 `--cred` 就只用它（读不到就按匿名跑，不会偷偷换回 `deps/credential.json`）；没给才用 `deps/credential.json`；都没有就匿名。
+
+> 这份文件等于你的账号登录态。别分享、别提交、别上传。
+
+## 命令
+
+| 命令 | 做什么 |
+|---|---|
+| `view <BV或链接或URL>` | 元数据 + 简介 + 热评 |
+| `peek <BV或链接>` | 元数据 + 热评 + 5 张均匀帧（最便宜；仅 B 站） |
+| `sub <BV>` | AI 字幕 + 三判据（字/秒、关键词命中、时长） |
+| `comments <BV> [N]` | 评论区，默认按时间倒序 |
+| `asr <BV或URL>` | 本地转写音频 |
+| `frames <BV或URL> [--step 秒] [--ocr]` | 抽帧；`--ocr` 顺带识别画面文字 |
+| `ocr <BV>` | 抽帧并 OCR |
+| `text <BV或URL>` | 四级链：字幕 → 转写 → 抽帧 OCR |
+| `sheet <BV> [--grid 3x3]` | 均匀挑 9/16 帧拼成一张图 |
+| `substrip <BV> [--step 秒]` | 底部字幕竖拼成一张图 |
+| `danmaku <BV>` | 弹幕热区（按时间桶统计峰值） |
+| `search <关键词> [--days 3]` | 搜视频 |
+| `hot [--limit 10]` | 综合热门榜 |
+| `login [--check] [--poll]` | 扫码登录 |
+| `clean` | 清空临时目录 `%TEMP%\bili-watch` |
+
+工具侧等价入口：`bili_watch` 工具（参数 `command` + `bv`），或 `/bili` 命令。
+
+## 通用视频 URL
+
+`view` / `text` / `asr` / `frames` 接受非 B 站 URL（YouTube、X、直链 mp4 等），走 yt-dlp：
+
+- 把 `yt-dlp.exe` 放进 `deps/`，或设 `BILI_LOOK_YTDLP`，或让它在 PATH 里。
+- 下载按 URL 哈希隔离在 `%TEMP%\bili-watch\`，不会串目录。
+- `peek` / `sub` / `comments` / `danmaku` / `sheet` / `substrip` / `ocr` 只支持 B 站。
+
+## 降级链
+
+```
+AI 字幕（需登录）
+   ↓ 没有字幕轨
+本地转写（可选依赖）
+   ↓ 没装 / 转写质量差（< 2 字/秒）
+抽帧 + OCR（可选依赖）
+   ↓ 没装
+读图（模型自己看帧）
+```
+
+每一步都会打印「为什么降级」，不会静默跳过。
+
+## 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `BILI_LOOK_PROJ` | ASR/OCR 环境目录（默认插件 `deps/`） |
+| `BILI_LOOK_FFMPEG` | ffmpeg 可执行文件路径 |
+| `BILI_LOOK_YTDLP` | yt-dlp 可执行文件路径 |
+| `BILI_LOOK_SEEN` | `seen.md` 去重文件路径（默认 `deps/seen.md`） |
+
+## 成本
+
+- 字幕一次请求，最便宜。
+- 抽帧会下载视频（360p）并跑 ffmpeg，CPU 占用可以用 `--step` 调低频率；脚本已限 `-threads 2`。
+- 九宫格/字幕带是把多帧压成一张图，省 token。
+
+## 风险
+
+- **凭证**：等同账号登录态，泄露即被盗。只存本机、不进日志。
+- **频率**：正常看几条没问题；批量扫几百条会触发风控。
+- **只读**：插件只读，不点赞、不评论、不留观看历史。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-bili-watch bundle patch layer
+# profile 的 dsh.profile.bundles 列出本包名即整层生效
+- insert:
+    - id: dsh-bili-watch
+      name: dsh-bili-watch

package/deps/.gitkeep

@@ -0,0 +1 @@
+# 运行期依赖目录：Python venv、模型缓存、yt-dlp、凭证都放在这里（默认不进 git）。

package/deps/_bili-asr.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+_bili-asr.py —— 把本地音频/视频文件转成文字（faster-whisper，CPU int8）
+
+为什么单独有这个文件：
+  B 站很多新视频没有 AI 字幕轨（刚发布几小时还没转写完，或者 UP 没开），
+  只靠 B 站字幕会把一大半候选判成「不可信」。本地转写能补上这一块。
+
+口径：
+  · 只跑 CPU + int8：本机 PyPI 版 ctranslate2 没有 CUDA 算子，装 GPU 版要另配 cuDNN，不值得。
+  · 模型默认 small（约 250 MB，一个 3 分钟视频约 30–45 秒）；可 --model 换 base/tiny。
+  · 模型与缓存落 D 盘项目目录（HF_HOME），不碰用户主目录。
+  · 音频由调用方先转成 16 kHz 单声道 wav 再传进来——这里不碰网络、不碰 B 站接口。
+
+用法：
+  .venv-asr\\Scripts\\python.exe _bili-asr.py <音频或视频文件> [-o 输出.txt] [--model small] [--lang zh]
+  不给 -o 就往 stdout 打正文（调用方直接取 stdout 更省事）。
+"""
+import argparse
+import os
+import sys
+
+# ⭐ 必须在 import faster_whisper 之前设好，否则它会先按默认去连 HuggingFace
+_HERE = os.path.dirname(os.path.abspath(__file__))
+os.environ.setdefault("HF_HOME", os.path.join(_HERE, ".hf-home"))
+# 国内直连 huggingface.co 基本下不动，默认走镜像；已经能直连的可以自己改回
+os.environ.setdefault("HF_ENDPOINT", "https://hf-mirror.com")
+os.environ.setdefault("HF_HUB_DISABLE_TELEMETRY", "1")
+# ⭐ 必须关掉 Xet：新版本 huggingface_hub 默认走 cas-server.xethub.hf.co，
+#   镜像站不代理那条重建接口，会报 CAS Client Error: 401 Unauthorized（2026-10-17 实测）。
+os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+# 避免 OpenMP 在多核上抢线程把机器拖死
+os.environ.setdefault("OMP_NUM_THREADS", str(max(1, (os.cpu_count() or 4) // 2)))
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("src", help="音频或视频文件路径")
+    ap.add_argument("-o", "--out", help="输出文本文件；不给就打印到 stdout")
+    ap.add_argument("--model", default=os.environ.get("BILI_ASR_MODEL", "small"),
+                    help="Whisper 模型：tiny / base / small / medium（默认 small）")
+    ap.add_argument("--lang", default="zh", help="语言，默认 zh（自动识别可传 auto）")
+    args = ap.parse_args()
+
+    if not os.path.isfile(args.src):
+        print("[asr] 找不到文件：" + args.src, file=sys.stderr)
+        return 2
+
+    try:
+        from faster_whisper import WhisperModel
+    except Exception as e:  # noqa: BLE001
+        print("[asr] 导入 faster_whisper 失败：%s" % e, file=sys.stderr)
+        return 3
+
+    print("[asr] 加载模型 %s（首次会下载，之后本地读）…" % args.model, file=sys.stderr)
+    try:
+        model = WhisperModel(args.model, device="cpu", compute_type="int8")
+    except Exception as e:  # noqa: BLE001
+        print("[asr] 加载模型失败：%s" % e, file=sys.stderr)
+        return 4
+
+    print("[asr] 开始转写…", file=sys.stderr)
+
+    # ⭐ 先自己解码一次 + 量 VAD 语音时长，用来区分两种「空转写」（2026-10-17 实测踩到）：
+    #   · 纯 BGM 骑车视频，音频很响（mean -14.4 dB）但没人说话 → 语音时长≈0，空是内容结果；
+    #   · 转写环境坏了（模型没加载/依赖缺/静音检测误杀）→ 明明有语音段却零字。
+    # 只看「有没有音频/时长多少」判不出来，必须看 VAD 到底找到了多少「像人说话」的片段。
+    speech_sec = 0.0
+    audio = None
+    vad_ok = False
+    try:
+        import numpy as np  # noqa: F401
+        from faster_whisper.audio import decode_audio
+        from faster_whisper.vad import VadOptions, get_speech_timestamps
+
+        audio = decode_audio(args.src, sampling_rate=16000)
+        stamps = get_speech_timestamps(audio, VadOptions(min_silence_duration_ms=400))
+        speech_sec = sum(float(s["end"]) - float(s["start"]) for s in stamps) / 16000.0
+        vad_ok = True
+        print("[asr] VAD 语音段 %d 个，共 %.1f 秒" % (len(stamps), speech_sec), file=sys.stderr)
+    except Exception as e:  # noqa: BLE001
+        # 量不出来不影响转写本身，但调用方会少一条判据，必须显式标出来（不能静默）
+        print("[asr] VAD 不可用：预检失败（不影响转写，但空文本将无法归因）：%s" % e, file=sys.stderr)
+
+    try:
+        segments, info = model.transcribe(
+            args.src,
+            language=None if args.lang == "auto" else args.lang,
+            vad_filter=True,              # 掐掉静音段，纯画面/纯音乐的视频会得到空文本
+            vad_parameters={"min_silence_duration_ms": 400},
+            beam_size=5,
+            condition_on_previous_text=False,  # 防止长视频里一段错就带着后面全错
+        )
+        parts = []
+        for seg in segments:
+            t = (seg.text or "").strip()
+            if t:
+                parts.append(t)
+    except Exception as e:  # noqa: BLE001
+        print("[asr] 转写失败：%s" % e, file=sys.stderr)
+        return 5
+
+    text = "".join(parts).strip()
+    print("[asr] 完成：%d 段，%d 字，语种 %s" % (len(parts), len(text), info.language), file=sys.stderr)
+    # 给调用方的机器可读标记：转写为空时靠它判「没人说话」还是「环境坏了」
+    # vad_ok 单独标出来：取不到语音秒数时调用方要报「VAD 不可用」，不能当成 0 秒
+    print("[asr] vad_ok=%d" % (1 if vad_ok else 0), file=sys.stderr)
+    print("[asr] speech_seconds=%.2f" % speech_sec, file=sys.stderr)
+    # ⭐ 段数给调用方做辅助判据：
+    #   总时长短不代表是噪声——「说了两句短话」每句 1 秒、两段，和「咳嗽一声」一段，
+    #   总时长都是 2 秒。段数 ≥2 说明有过多次发声，更可能是短话而非噪声。
+    print("[asr] speech_segments=%d" % (len(stamps) if vad_ok else -1), file=sys.stderr)
+    print("[asr] chars=%d" % len(text), file=sys.stderr)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text + "\n")
+        print("[asr] 已写入：" + args.out, file=sys.stderr)
+    else:
+        sys.stdout.write(text + "\n")
+    # 空文本是结果不是错误：纯音乐 / 纯录屏 / 无声演示的视频就该是空的
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/index.js

@@ -0,0 +1,235 @@
+/**
+ * dsh-bili-watch —— B 站「看内容」的命令与工具入口。
+ *
+ * 为什么单独做插件：看视频的动作是固定的（取字幕 / 转写 / 抽帧 OCR），
+ * 让人敲 /bili 少花推理 token；同时注册一个 bili_watch 工具，模型自己也能调，
+ * 不会因为「只做了命令」而变成没人调度。
+ *
+ * 两侧执行同一份 lookup：spawn 插件自带的只读工具
+ *   <插件目录>\tools\look.mjs
+ * 只读、默认匿名：不修改任何业务状态文件，可反复调用。
+ */
+import { spawn } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const LOOK = join(HERE, 'tools', 'look.mjs')
+const COMMANDS = ['search', 'hot', 'peek', 'view', 'sub', 'comments', 'danmaku', 'asr', 'frames', 'sheet', 'substrip', 'ocr', 'text', 'login', 'clean']
+
+const name = 'dsh-bili-watch'
+const inject = ['commands', 'tools']
+
+function runLook(args, { timeoutMs = 1_200_000 } = {}) {
+  return new Promise((resolve) => {
+    let out = ''
+    let err = ''
+    let done = false
+    const finish = (res) => {
+      if (done) return
+      done = true
+      resolve(res)
+    }
+    let child
+    try {
+      child = spawn(process.execPath, [LOOK, ...args], { windowsHide: true })
+    } catch (e) {
+      finish({ code: -1, out: '', err: `启动失败：${e?.message ?? e}` })
+      return
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill()
+      } catch {}
+      finish({ code: -2, out: out.trim(), err: (err + '\n[超时]').trim() })
+    }, timeoutMs)
+    child.stdout.on('data', (d) => {
+      out += d
+    })
+    child.stderr.on('data', (d) => {
+      err += d
+    })
+    child.on('error', (e) => {
+      clearTimeout(timer)
+      finish({ code: -1, out: out.trim(), err: String(e?.message ?? e) })
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      finish({ code, out: out.trim(), err: err.trim() })
+    })
+  })
+}
+
+/** 把 "text BV1xx --cred path --step 2" 拆成 { command, bv, extra }。 */
+function parseCommandLine(raw) {
+  const tokens = String(raw ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+  const command = tokens.shift()
+  const bv = tokens.length && !tokens[0].startsWith('--') ? tokens.shift() : ''
+  const extra = []
+  let step = ''
+  let cred = ''
+  while (tokens.length) {
+    const t = tokens.shift()
+    if (t === '--step' && tokens.length) {
+      step = tokens.shift()
+      extra.push('--step', step)
+    } else if (t === '--p' && tokens.length) {
+      extra.push('--p', tokens.shift())
+    } else if (t === '--cred' && tokens.length) {
+      cred = tokens.shift()
+      extra.push('--cred', cred)
+    } else if (t === '--days' && tokens.length) {
+      extra.push('--days', tokens.shift())
+    } else if (t === '--limit' && tokens.length) {
+      extra.push('--limit', tokens.shift())
+    } else if (t === '--order' && tokens.length) {
+      extra.push('--order', tokens.shift())
+    } else if (t === '--grid' && tokens.length) {
+      extra.push('--grid', tokens.shift())
+    } else if (t === '--out' && tokens.length) {
+      extra.push('--out', tokens.shift())
+    } else if (t === '--ffmpeg' && tokens.length) {
+      extra.push('--ffmpeg', tokens.shift())
+    } else if (t === '--fresh' || t === '--ocr' || t === '--poll' || t === '--check' || t === '--fast' || t === '--scene' || t === '--mark-seen') {
+      extra.push(t)
+    }
+    // 其余 token 直接丢弃（命令本身不接受别的参数）
+  }
+  return { command, bv, extra, step, cred }
+}
+
+async function lookup({ command, bv, extra = [] }) {
+  if (!command || !COMMANDS.includes(command)) {
+    return { ok: false, text: `用法：/bili <${COMMANDS.join('|')}> <BV> [--step 2] [--cred 凭证路径]` }
+  }
+  if (!['clean', 'login', 'hot'].includes(command) && !bv) {
+    return { ok: false, text: `缺少 BV 号，用法：/bili ${command} <BV>` }
+  }
+  const args =
+    command === 'clean'
+      ? ['clean']
+      : command === 'login'
+        ? ['login', ...extra]
+        : command === 'hot'
+          ? ['hot', ...extra]
+          : [command, bv, ...extra]
+  const r = await runLook(args)
+  const text = (r.out || r.err || '').trim() || '（没有输出）'
+  return { ok: r.code === 0, text }
+}
+
+function apply(ctx) {
+  // ① 斜杠命令：人敲，确定性执行，不花推理 token
+  ctx.commands.register({
+    definitionId: 'dsh-bili-watch',
+    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]',
+    },
+    handler: async (invocation) => {
+      const { command, bv, extra } = parseCommandLine(invocation?.rawInput)
+      const r = await lookup({ command, bv, extra })
+      return { kind: r.ok ? 'success' : 'error', text: r.text }
+    },
+  })
+
+  // ② 同名工具：模型可调，需要看视频时自己来，不依赖用户敲命令
+  //    必须用 defineTool 包一层：ctx.tools.register 收的是编译好的 tool 对象，
+  //    直接传 options 会让发往模型的 parameters 变成 null（报 INVALID_REQUEST: schema must be type "object"）。
+  ctx.tools.register(defineTool({
+    name: 'bili_watch',
+    description:
+      '用户给出 B 站视频链接 / BV 号，要我看、总结、判断这条视频讲了什么、有没有坑、值不值得看时使用。读取一个 B 站视频的内容材料（只读、匿名）。优先级：字幕 → 本地 ASR 转写 → 抽帧 OCR。command=peek 最便宜：只拿标题/简介/热评 + 均匀 5 帧，用来先判断是口播还是画面，再决定走 text 还是 ocr；command=text 会按优先级自动降级并返回最可信的一份文本（推荐）；view=元数据与热评；comments=评论区；asr=强制本地转写；frames=抽帧（可加 ocr=true 顺带识别画面文字）；ocr=抽帧并识别画面文字；sub=只要字幕；search=按关键词搜视频（配 days 可只留最近 N 天发布的，结果按播放量降序，用来看「这几天有什么值得看」）；hot=综合热门榜（B 站按热度排的前 N 条）；danmaku=弹幕热区（观众在哪一段反应最集中，判断名场面在哪）；sheet=把 N 帧拼成九宫格一张图（看图省 token）；substrip=把底部字幕逐段竖拼成一张图（硬字幕视频最省）。多 P 视频用 p 指定第几个分P（默认 P1）。拿到文本后由你负责理解与总结。',
+    parameters: {
+      command: {
+        type: 'string',
+        required: true,
+        enum: ['search', 'hot', 'peek', 'view', 'sub', 'comments', 'danmaku', 'asr', 'frames', 'sheet', 'substrip', 'ocr', 'text'],
+        description: '要看哪一类材料；想要「讲了什么」的原料用 text，想先看有什么可看的用 search/hot。',
+      },
+      keyword: {
+        type: 'string',
+        description: 'command=search 时的搜索关键词（如「DeepSeek」「AI 编程」）。',
+      },
+      days: {
+        type: 'number',
+        description: 'command=search 时只保留最近 N 天发布的（再按播放量降序）；不传则不限时间。',
+      },
+      bv: { type: 'string', description: 'BV 号（如 BV1xx411c7mD），或直接贴 B 站分享链接（https://www.bilibili.com/video/BV.../?...），会自动提取 BV 号。search/hot 不需要。' },
+      p: {
+        type: 'number',
+        description: '多 P 视频的分P序号（1 起）；不传默认 P1。',
+      },
+      step: {
+        type: 'number',
+        description: '抽帧间隔秒数（frames/ocr/text 用）；不传则按视频时长自适应（长视频更疏，省 CPU）。',
+      },
+      ocr: {
+        type: 'boolean',
+        description: 'command=frames 时是否顺带识别画面文字。',
+      },
+      fast: {
+        type: 'boolean',
+        description: 'command=text 时跳过本地转写，字幕拿不到就直接抽帧 OCR（画面类视频更快）。',
+      },
+      scene: {
+        type: 'boolean',
+        description: 'command=frames 时按画面变化点抽帧（吸附到变化最多的时刻，比等间隔更准，默认关）。',
+      },
+      grid: {
+        type: 'string',
+        description: 'command=sheet 时的格子，如 3x3 或 4x4（默认 3x3）。',
+      },
+      limit: {
+        type: 'number',
+        description: 'command=search 时最多返回几条（默认 10）、command=hot 时取前 N 条（默认 10）。',
+      },
+      cred: {
+        type: 'string',
+        description: '可选的 B 站凭证 JSON 路径（只在 command=sub/text 时需要；不传就匿名，匿名拿不到 AI 字幕轨）。',
+      },
+    },
+    output: {
+      // 注意：DSH 的 output.schema 是「author-facing spec」，编译时 allowRequired=false，
+      // 写 required（无论属性级还是顶层数组）会抛 JsonSchemaError: unsupported JSON schema。
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', description: '执行是否成功' },
+          text: { type: 'string', description: '输出文本' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: String(value?.text ?? '').slice(0, 24000) }],
+    },
+    execute: async (args) => {
+      const extra = []
+      if (typeof args.p === 'number' && Number.isInteger(args.p) && args.p > 0) extra.push('--p', String(args.p))
+      if (typeof args.step === 'number' && Number.isFinite(args.step) && args.step > 0) extra.push('--step', String(args.step))
+      if (args.ocr) extra.push('--ocr')
+      if (args.fast) extra.push('--fast')
+      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 (args.command === 'hot') {
+        if (typeof args.limit === 'number' && args.limit > 0) extra.push('--limit', String(Math.floor(args.limit)))
+        const r = await lookup({ command: 'hot', bv: '', extra })
+        return { ok: r.ok, text: r.text }
+      }
+      if (typeof args.limit === 'number' && args.limit > 0) extra.push('--limit', String(Math.floor(args.limit)))
+      if (typeof args.cred === 'string' && args.cred.trim()) extra.push('--cred', args.cred.trim())
+      const target = args.command === 'search' ? String(args.keyword ?? '').trim() : String(args.bv ?? '').trim()
+      if (args.command === 'search' && !target) return { ok: false, text: 'search 需要 keyword 参数（要搜什么词）' }
+      if (!target) return { ok: false, text: '缺少 BV 号或分享链接' }
+      const r = await lookup({ command: args.command, bv: target, extra })
+      return { ok: r.ok, text: r.text }
+    },
+  }))
+}
+
+export { apply, inject, name }

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "dsh-bili-watch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "private": false,
+  "description": "A DSH plugin that lets an AI agent \"watch\" Bilibili videos: AI subtitles, local ASR, frame OCR, danmaku heatmap, comments, and nine-grid frame sheets.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "bili-watch": "tools/look.mjs"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "tools/",
+    "scripts/",
+    "deps/.gitkeep",
+    "deps/_bili-asr.py"
+  ],
+  "keywords": [
+    "bilibili",
+    "video",
+    "asr",
+    "ocr",
+    "danmaku",
+    "dsh",
+    "deepseek",
+    "subtitles"
+  ],
+  "author": "Sacredbluedragon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sacredbluedragon/dsh-bili-watch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sacredbluedragon/dsh-bili-watch/issues"
+  },
+  "homepage": "https://github.com/Sacredbluedragon/dsh-bili-watch#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  }
+}