dsh-vidlens 1.2.0 → 1.3.0

package/README.md

@@ -1,6 +1,9 @@
 # VidLens for DeepSeek Harness
 
 [![ci](https://github.com/cctv2333/dsh-vidlens/actions/workflows/ci.yml/badge.svg)](https://github.com/cctv2333/dsh-vidlens/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-vidlens.svg)](https://www.npmjs.com/package/dsh-vidlens)
+[![PyPI](https://img.shields.io/pypi/v/vidlens-mcp.svg?cacheSeconds=600)](https://pypi.org/project/vidlens-mcp/)
+[![DSH plugin](https://img.shields.io/badge/topic-dsh--plugin-4B5563)](https://github.com/topics/dsh-plugin)
 [![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 把 [vidlens](https://github.com/cctv2333/vidlens) 从一个 stdio MCP 外壳变成 **DSH 原生插件**：18 个 `vidlens_*` 工具、图片直接进对话、按工具设超时、外加三个零下载的缓存工具。
@@ -99,8 +102,9 @@ dsh plugin --profile desktop add dsh-vidlens
 
 | 工具 | 下载量 | 用途 |
 |---|---|---|
+| `vidlens_watch(url, minutes=5, cursor="next")` | 每段该窗音频（或缓存） | **新增**：一段一段看（默认 5 分钟、约 0.5k 字），返回该段要点 + 「已看 X / 共 Y（%）」，并要求先汇报、再问用户要不要继续 |
 | `vidlens_window(url, start, end)` | 0（有缓存/字幕）或该窗音频 | 某时间窗的台词与停顿 |
-| `vidlens_brief(url, ...)` | 平台字幕 0；无字幕才下音频 | 完整证据报告（结构/停顿/低置信词/广告段落/风险） |
+| `vidlens_brief(url, ..., level="digest")` | 平台字幕 0；无字幕才下音频 | **摘要**（默认约 1.5k 字：章节 + 5 句关键台词 + 全文路径）；`level="full"` 才给 6–9k 字完整报告（结构/停顿/低置信词/广告段落/风险） |
 | `vidlens_seek(query, url='')` | 0（**新增**） | 在缓存转写里按关键词查原话 → 时间码 |
 | `vidlens_audio(url, start, end)` | 该段音频 | SenseVoice 语种/情感/事件 + 节拍与能量 |
 | `vidlens_soundscape(url, start, end)` | 该段音频 | **新增**：AudioSet 527 类声音事件（吃饭/敲击/水声/碰撞…）+ 概率 + 时间码 |
@@ -112,6 +116,39 @@ dsh plugin --profile desktop add dsh-vidlens
 | `vidlens_sheet(url, start, end, cols, rows)` | 该段（20s≈0.9MB） | 带绝对时间码的拼图 |
 | `vidlens_frames(url, at=[...])` | 该段 | 最多 6 张精确帧（读小字用） |
 | `vidlens_scan(url, n=24)` | 最低画质整片（7min≈14-21MB，用完即删） | 全片抽样拼图（无音频视频） |
+| `vidlens_ocr(url, start, end, n=12)` | 该段最低画质 | **把画面上的字读成文本**（本地 OCR，离线）；无人声、无字幕的视频靠它，输出带时间码 |
+
+`vidlens_ocr` 需要一次性装 OCR 依赖（RapidOCR，Apache-2.0，PP-OCRv6 模型随包分发，约 30MB，装完离线）：
+
+```
+"D:\vidlens\vidlens\.venv\Scripts\python.exe" -m pip install rapidocr
+```
+
+没装也不会坏：`vidlens_ocr` 会返回一句「装它只要一步 + pip 命令」，其他工具不受影响。
+
+### 上下文预算（为什么默认给摘要）
+
+一次「看视频」如果按老路子走，实测是这么多字符：
+
+| 调用 | 字符 | 说明 |
+|---|---|---|
+| `meta` + `plan` | ~730 | 便宜 |
+| `window` × 3（各 1 分钟） | ~2,800 | ~0.9k/分钟 |
+| `soundscape`（60 秒） | ~1,500 | 12 窗 × 8 标签 |
+| `brief`（旧版全量） | **~9,000** | 6–9k 字 ≈ 4–6k tokens |
+| 合计 | **~14,200** | 还没算图片 |
+
+关键不在单次有多大，而在于**这些字符之后每一轮都在上下文里**。一个 64k 窗口，
+两三个视频 + 正常对话就会顶到上限，于是出现「看完视频就超上下文」。
+
+所以默认改成三档，按需升级：
+
+1. `vidlens_brief` → **摘要**（约 0.7–1.5k 字：标题/时长/语音覆盖/章节/5 句均匀取样的关键台词/全文路径）；
+2. `vidlens_window` → 只读某一段（约 0.8k 字/分钟），读细节用它，别用 brief 代；
+3. `vidlens_brief(level="full")` → 完整报告（6–9k 字），**只在用户明确要全文时**用一次。
+
+全文始终写在 `out/<id>/brief.md`，不会丢；摘要里直接给路径和下一次该调什么。
+`vidlens_window` 另有 80 行上限，超了会明说「还有 N 行，缩小范围」而不是无限倾倒。
 
 **判断 / 长视频 / 自检**
 
@@ -205,7 +242,7 @@ git tag v1.2.0 && git push origin v1.2.0
 
 `release.yml` 会 `npm pack`、`npm publish --access public`，走 **Trusted Publishing（OIDC）**——
 CI 里没有任何长期 token。npm 的 publisher 只能在包存在后配置，所以**首次发布要在本地做一次**
-（`npm login` → `npm publish`，见 `RELEASING.md`），之后打 tag 即可。
+（`npm stage publish` → `npm stage approve`，全程不需要把 token 交给 CI，见 `RELEASING.md`），之后打 tag 即可。
 
 > 注意：PowerShell 5.1 不支持 `&&`，用 `;` 或分行。
 
@@ -228,6 +265,19 @@ CI 里没有任何长期 token。npm 的 publisher 只能在包存在后配置
   没有在浏览器里验证（无头浏览器对 `file:` / `data:` 导航超时），这一项留待用户目视确认。
 
 
+## 路线图
+
+产品级路线图（已做 / 未做 / 验收标准 / 不做清单）在工程仓库：
+[vidlens/ROADMAP.md](https://github.com/cctv2333/vidlens/blob/main/ROADMAP.md)。
+
+插件专属待办，按工作量从小到大：
+
+1. `Config` schema（现在 `status: absent`，只能手改 YAML）
+2. `/vl <url>` 斜杠命令
+3. `present` 交付物卡片（brief.md / 拼图）
+4. 右侧栏 Web 面板（缓存列表 + brief 预览 + 时间轴）
+5. 设置页（模型路径 / 代理 / cookie）
+
 ## 边界与已知限制
 
 - **job 状态在进程内存**：`vidlens_job_start` 起的任务，桥进程重启（超时/取消/宿主重启）后会消失；已下的缓存不丢，重跑即可。

package/RELEASING.md

@@ -1,22 +1,37 @@
 # 发布（维护者）
 
-两步：**首次发布只能在本地做一次**（包还不存在，npm 没有「包设置」页可配 Trusted Publisher），
-**之后全部走 OIDC**，CI 里没有任何长期 token。
+首次发布用 **staged publishing**（`npm stage publish` **不需要 2FA**，批准时才要）；
+之后全部走 **OIDC Trusted Publishing**，CI 里没有任何长期 token。
 
-## 1. 首次发布（只做一次 · 本地）
+> 别用 `npm publish` 做首次发布：npm 现在对它强制 2FA，CLI 的 `--otp` 也常被同样拒绝
+> （`403 ... bypass 2fa enabled is required`）。
+
+## 1. 首次发布：stage（不需要 2FA）
 
 ```powershell
+npm --version                     # 需要 >= 11.15.0，低了就 npm i -g npm@latest
 cd D:\vidlens\vidlens-mcp-dsh
-npm login                     # 浏览器授权，或按提示输入 OTP
-npm publish --access public   # 账号开了 2FA 会要一次 OTP；这是交互式的，不需要 token
+npm stage publish --access public
+npm stage list                    # 记下 id，等 status 变成 staged
 ```
 
-成功后包就有了：<https://www.npmjs.com/package/dsh-vidlens>
+新包会先在 registry 上生成一个 `0.0.0-stage` 占位版本（公开可见），
+真正要发的版本留在 staging 区，**批准后才上线**。
+
+## 2. 批准（要 2FA，只有你能做）
+
+**用命令行，最可靠**（网页的 Staged Packages 入口时有时无，`/package/<name>/staged` 可能 404）：
+
+```powershell
+npm stage approve <stage-id>      # 会提示输入 6 位 OTP
+npm view dsh-vidlens versions     # 批准后应能看到目标版本
+```
 
-> 为什么不走 CI：npm 的 Trusted Publisher 配置在**包设置**里，包不存在时没有这个页面。
-> 这一步也**不需要**把任何 token 交给 CI。
+> OTP 只有 30 秒有效，输慢了就重来。
+> 如果 2FA 是「安全密钥（WebAuthn）」而不是验证器 App，CLI 无法输入 OTP——
+> 先把 npm 账号的 2FA 改成 TOTP（Authenticator app）再重试。
 
-## 2. 配置 Trusted Publisher（一次性）
+## 3. 配置 Trusted Publisher（一次性）
 
 1. 打开 <https://www.npmjs.com/package/dsh-vidlens/access>
    （或包页 → **Settings** → **Trusted Publisher**）
@@ -24,7 +39,7 @@ npm publish --access public   # 账号开了 2FA 会要一次 OTP；这是交互
 
    | 字段 | 值 |
    |---|---|
-   | Organization or user | `cctv2333` |
+   | Organization or user | `cctv2333` ← **GitHub** 用户名（不是 npm 的 `ghost120`） |
    | Repository | `dsh-vidlens` |
    | Workflow filename | `release.yml`（只写文件名，带 `.yml`） |
    | Environment name | 留空 |

package/bridge/vidlens_bridge.py

@@ -86,6 +86,10 @@ if str(PROJECT) not in sys.path:
     sys.path.insert(0, str(PROJECT))
 os.environ.setdefault("PYTHONIOENCODING", "utf-8")
 os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+# The bridge turns `Image` objects into file paths (see `_image_entry`), so a
+# large sheet costs the plugin nothing. Say so, or vl_mcp's `auto` policy would
+# drop the picture here and the tool would return a path with no attachment.
+os.environ.setdefault("VIDLENS_INLINE_IMAGES", "always")
 
 # ---------------------------------------------------------------------- imports
 IMPORT_ERROR = None
@@ -102,6 +106,36 @@ except BaseException as exc:  # noqa: BLE001 - report, never crash the loop
     IMPORT_ERROR = f"{type(exc).__name__}: {exc}"
     traceback.print_exc(file=sys.stderr)
 
+_INSTALL_HINT = (
+    "vidlens 依赖没法导入。两种修法（任选一种）：\n"
+    "  1) pip install vidlens-mcp —— 然后让插件用同一个解释器：\n"
+    "     插件配置项 pythonPath，或环境变量 VIDLENS_PYTHON。\n"
+    "  2) 用已有的 checkout：把 VIDLENS_PROJECT 设成含 vidlens.py 的目录。\n"
+    "     本进程已经找过: {project}"
+)
+
+
+def _import_error_text() -> str:
+    """Turn a bare ImportError into something the user can act on.
+
+    The raw traceback goes to stderr (visible in the bridge log); what reaches the
+    model is the failure plus the two ways to fix it. Without this the whole plugin
+    answers every call with ``No module named 'vidlens'`` and no lead on why.
+    """
+    err = IMPORT_ERROR or ""
+    hint = _INSTALL_HINT.format(project=PROJECT)
+    match = re.search(r"No module named '([^']+)'", err)
+    if not match:
+        return f"{err}\n\n{hint}"
+    missing = match.group(1).split(".")[0]
+    if missing == "mcp":
+        pip = "pip install mcp"
+    elif missing in ("vl_mcp",) or missing.startswith("vidlens"):
+        pip = "pip install vidlens-mcp"
+    else:
+        pip = f"pip install {missing}"
+    return f"{err}\n\n缺 Python 包 {missing}。先试：{pip}\n{hint}"
+
 
 # ---------------------------------------------------------------- result shaping
 _EXT_MEDIA = {
@@ -399,11 +433,13 @@ def _install_dispatch() -> None:
         "subs": vl.video_subs,
         "brief": vl.video_brief,
         "window": vl.video_window,
+        "watch": vl.video_watch,
         "audio": vl.video_audio,
         "soundscape": vl.video_soundscape,
         "sheet": vl.video_sheet,
         "frames": vl.video_frames,
         "scan": vl.video_visual_scan,
+        "ocr": vl.video_ocr,
         "comments": vl.video_comments,
         "job_start": vl.video_job_start,
         "job": vl.video_job,
@@ -422,7 +458,7 @@ _install_dispatch()
 
 def _handle(req: dict) -> dict:
     if IMPORT_ERROR:
-        raise RuntimeError("vidlens 依赖导入失败: " + IMPORT_ERROR)
+        raise RuntimeError("vidlens 依赖导入失败: " + _import_error_text())
     tool = str(req.get("tool") or "")
     entry = DISPATCH.get(tool)
     if entry is None:
@@ -457,7 +493,7 @@ def main() -> int:
         "project": str(PROJECT),
         "python": sys.version.split()[0],
         "tools": sorted(DISPATCH),
-        "error": IMPORT_ERROR,
+        "error": _import_error_text() if IMPORT_ERROR else None,
     })
     for line in sys.stdin:
         line = line.strip()

package/index.js

@@ -348,23 +348,24 @@ const num = (description) => ({ type: 'number', description })
 const int = (description) => ({ type: 'integer', description })
 const bool = (description) => ({ type: 'boolean', description })
 
-const URL_ARG = str('公开可看的视频链接（B站 / YouTube / 等；无需登录）')
+const URL_ARG = str('视频链接（公开可看）')
+const LANG_ARG = str('zh|yue|ja|en')
+const MODEL_ARG = str('whisper 模型，默认 small')
+const PROMPT_ARG = str('ASR 提示词（方言/术语）')
 
 const TOOLS = [
   {
     name: 'vidlens_meta',
     bridge: 'meta',
     timeoutMs: 120_000,
-    description: '零下载读取公开视频元数据：标题 / UP主 / 时长 / 播放点赞 / 平台字幕是否存在 / 平台标注音乐，并对标题简介做注入风险扫描。'
-      + '用来判断「这个视频值不值得看」，也是后续所有工具的第一步。',
+    description: '0 下载：标题/UP主/时长/播放/字幕情况。先看值不值得看。',
     parameters: P({ url: URL_ARG }, ['url']),
   },
   {
     name: 'vidlens_plan',
     bridge: 'plan',
     timeoutMs: 180_000,
-    description: '零下载按切点与长静音把视频切成章节（窗口默认 300 秒），给出建议观看顺序。'
-      + '长视频先调它，再挑 2-3 段用 vidlens_window（读台词）与 vidlens_sheet（看画面）。',
+    description: '0 下载：按切点/静音分章节。长视频先调它，再挑 2-3 段。',
     parameters: P({
       url: URL_ARG,
       window: num('章节窗口秒数，默认 300（夹在 60–3600 之间）'),
@@ -374,8 +375,7 @@ const TOOLS = [
     name: 'vidlens_subs',
     bridge: 'subs',
     timeoutMs: 180_000,
-    description: '只读平台字幕轨（人工字幕优先，其次自动/AI 字幕），0 媒体下载。'
-      + '方言/口音重、本地 ASR 不确定时，先看这里有没有原字幕；没有字幕再看画面硬字幕。',
+    description: '0 下载：平台字幕（人工优先）。有字幕就别做 ASR。',
     parameters: P({
       url: URL_ARG,
       lang: str('语言偏好，默认 zh；粤语可传 yue'),
@@ -386,43 +386,54 @@ const TOOLS = [
     name: 'vidlens_brief',
     bridge: 'brief',
     timeoutMs: 900_000,
-    description: '完整证据报告：平台字幕优先（0 下载），无字幕才下音频做本地 ASR；含结构/停顿/低置信词/广告段落/风险扫描。'
-      + '超过 20 分钟且无平台字幕时默认只给章节建议；确实要全量逐字才传 full=true。只看画面用 vidlens_sheet / vidlens_frames，不要下整片。',
+    description: '看视频：默认摘要约 1.5k 字（章节+5 句关键台词+全文路径），直接回答；要 6-9k 字全文才传 level="full"。无字幕才下音频做 ASR。',
     parameters: P({
       url: URL_ARG,
-      lang: str('ASR 语言，默认 zh；粤语 yue、日语 ja 等'),
-      model: str('Whisper 模型名，默认 small（仅在没有 SenseVoice 时用到）'),
-      scan_cuts: bool('额外扫镜头切点（会下最低画质视频，约 14-21MB，用完即删）'),
-      refresh: bool('忽略缓存，强制重新转写'),
-      full: bool('长视频无字幕时也做全量逐字转写（很慢，谨慎）'),
-      prompt: str('给 ASR 的提示词，例如「以下是粤语，请保留方言用词」'),
+      lang: LANG_ARG,
+      level: str('digest|full'),
+      model: MODEL_ARG,
+      scan_cuts: bool('扫镜头切点(下14-21MB)'),
+      refresh: bool('忽略缓存'),
+      full: bool('全量转写'),
+      prompt: PROMPT_ARG,
+    }, ['url']),
+  },
+  {
+    name: 'vidlens_watch',
+    bridge: 'watch',
+    timeoutMs: 600_000,
+    description: '分段看：一次一段（默认 5 分钟、约 0.5k 字），回进度与下一步。只在用户要「细看/逐段」时用。',
+    parameters: P({
+      url: URL_ARG,
+      minutes: num('每段分钟，默认5'),
+      cursor: str('next|restart|stop'),
+      lang: LANG_ARG,
+      model: MODEL_ARG,
     }, ['url']),
   },
   {
     name: 'vidlens_window',
     bridge: 'window',
     timeoutMs: 300_000,
-    description: '只看某个时间窗：该窗内的台词（带时间码）与停顿。有缓存或平台字幕则零下载；否则只下这一窗的音频做 ASR，绝不转写全片。'
-      + '适合「刚才那 30 秒他说了什么」，是长视频抽样的主力工具。',
+    description: '读某时间窗的台词与停顿（约 0.8k 字/分钟）。有缓存则 0 下载。',
     parameters: P({
       url: URL_ARG,
-      start: str('起点，秒数或 MM:SS / HH:MM:SS，默认 0'),
-      end: str('终点，秒数或 MM:SS / HH:MM:SS，默认 60'),
-      lang: str('ASR 语言，默认 zh'),
-      model: str('Whisper 模型名，默认 small'),
-      prompt: str('给 ASR 的提示词'),
+      start: str('起点（秒/MM:SS）'),
+      end: str('终点（秒/MM:SS）'),
+      lang: LANG_ARG,
+      model: MODEL_ARG,
+      prompt: PROMPT_ARG,
     }, ['url']),
   },
   {
     name: 'vidlens_audio',
     bridge: 'audio',
     timeoutMs: 300_000,
-    description: '听一段：本地 SenseVoice 的语种 / 情感 / 音频事件（Speech / BGM / Laughter…）+ 节拍与能量（启发式）。'
-      + '只下这一段音频（20 秒约 0.5MB）。情感、事件、BPM 都是近似信号，必须结合画面与平台元数据核对。',
+    description: '听一段：语种/情感/音频事件 + 节拍能量（本地 SenseVoice，启发式）。',
     parameters: P({
       url: URL_ARG,
-      start: str('起点，默认 0'),
-      end: str('终点，默认 20'),
+      start: str('起点（秒/MM:SS）'),
+      end: str('终点（秒/MM:SS）'),
       lang: str('语言提示，默认 zh'),
     }, ['url']),
   },
@@ -430,14 +441,11 @@ const TOOLS = [
     name: 'vidlens_soundscape',
     bridge: 'soundscape',
     timeoutMs: 300_000,
-    description: '听这一段「有什么声音」（不是「说了什么」）：AudioSet 527 类多标签 + 概率 + 时间码。'
-      + '能覆盖吃饭/咀嚼（Chewing）、敲桌子/拍（Knock / Tap / Wood block）、水声（Water / Water tap）、'
-      + '杯子碰撞、拖拽、塑料袋等；**喝水/吞咽没有对应类别**，只能靠水声+画面推断。'
-      + '只下这一段音频（60 秒约 1MB）。概率是模型输出，不是事实断言。',
+    description: '声音事件：AudioSet 527 类（敲击/吃饭/水声…）+ 概率 + 时间码。识别不了喝水。',
     parameters: P({
       url: URL_ARG,
-      start: str('起点，默认 0'),
-      end: str('终点，默认 60'),
+      start: str('起点（秒/MM:SS）'),
+      end: str('终点（秒/MM:SS）'),
       top_k: int('每个窗口保留几个标签，默认 8（上限 20）'),
       min_prob: num('低于这个概率的标签不列出，默认 0.15'),
       window: num('分析窗长秒数，默认 10（2–30）'),
@@ -449,14 +457,13 @@ const TOOLS = [
     bridge: 'sheet',
     images: true,
     timeoutMs: 300_000,
-    description: '只下这一段视频（20 秒约 0.9MB），返回一张拼图，每格左上角烧着绝对时间码，图片直接附在结果里。'
-      + '「看一眼这段画面在发生什么」就用它；比 vidlens_frames 便宜得多。',
+    description: '看某段画面：拼图带绝对时间码，图片直接进对话（20 秒 ≈ 0.9MB）。',
     parameters: P({
       url: URL_ARG,
-      start: str('起点，默认 0'),
-      end: str('终点，默认 20'),
-      cols: int('列数，默认 4（上限 8）'),
-      rows: int('行数，默认 3（上限 6）'),
+      start: str('起点（秒/MM:SS）'),
+      end: str('终点（秒/MM:SS）'),
+      cols: int('列数'),
+      rows: int('行数'),
       height: int('片段下载高度，默认 360'),
     }, ['url']),
   },
@@ -465,11 +472,11 @@ const TOOLS = [
     bridge: 'frames',
     images: true,
     timeoutMs: 300_000,
-    description: '按秒精确取帧（最多 6 张），图片直接附在结果里。只在需要读小字 / 代码 / 表格这类细节时用；成本高于 vidlens_sheet。',
+    description: '按秒取帧（最多 6 张，读小字用）。比 sheet 贵，先试 sheet。',
     parameters: P({
       url: URL_ARG,
       at: { type: 'array', items: { type: 'number' }, description: '要取帧的秒数列表，如 [19.5, 21.0]，最多 6 个' },
-      width: int('输出宽度像素，默认 960'),
+      width: int('宽度px'),
     }, ['url', 'at']),
   },
   {
@@ -477,8 +484,7 @@ const TOOLS = [
     bridge: 'scan',
     images: true,
     timeoutMs: 900_000,
-    description: '全片抽样看画面：有切点按切点、没有就均匀取 n 帧（默认 24），每帧烧上时间码拼成图返回。'
-      + '用于无音频或长时间无语音的视频；代价是下最低画质视频（7 分钟约 14-21MB），用完即删。',
+    description: '全片抽样拼图（无音频视频用）。要下最低画质整片，用完即删。',
     parameters: P({
       url: URL_ARG,
       n: int('抽样帧数，默认 24（4–48）'),
@@ -486,13 +492,25 @@ const TOOLS = [
       rows: int('拼图行数，默认 4'),
     }, ['url']),
   },
+  {
+    name: 'vidlens_ocr',
+    bridge: 'ocr',
+    timeoutMs: 600_000,
+    description: '读画面上的字（本地 OCR，离线）：无人声/无字幕视频靠它，输出带时间码。',
+    parameters: P({
+      url: URL_ARG,
+      start: str('起点，默认 0（秒或 MM:SS）'),
+      end: str('终点，默认整片末尾'),
+      n: int('取帧数，默认 12（1–24）'),
+      width: int('取帧宽度，默认 1280'),
+    }, ['url']),
+  },
   {
     name: 'vidlens_comments',
     bridge: 'comments',
     images: true,
     timeoutMs: 180_000,
-    description: '抓公开视频评论区（目前 B 站免登录）：互动比、正负面词频、争议度启发式、高赞评论，并把评论图片附在结果里。'
-      + '评论是最敌对的文本来源，已做清洗与注入扫描；它是「观众怎么看」，不是「视频讲了什么」。',
+    description: '评论区信号（B站免登录）：互动比/争议度/高赞。默认不带配图。',
     parameters: P({
       url: URL_ARG,
       limit: int('抓多少条评论，默认 40'),
@@ -502,23 +520,22 @@ const TOOLS = [
     name: 'vidlens_job_start',
     bridge: 'job_start',
     timeoutMs: 90_000,
-    description: '长视频后台任务：立即返回 job_id，再用 vidlens_job 轮询。只有明确要全量逐字（full=true）或要扫镜头时才用；'
-      + '普通分析先用 vidlens_brief。任务状态保存在工作进程内存里，进程重启后需重跑（缓存仍在）。',
+    description: '起后台任务（长视频防超时），拿 job_id 再轮询 vidlens_job。',
     parameters: P({
       url: URL_ARG,
-      lang: str('ASR 语言，默认 zh'),
-      model: str('Whisper 模型名，默认 small'),
-      scan_cuts: bool('额外扫镜头切点'),
+      lang: LANG_ARG,
+      model: MODEL_ARG,
+      scan_cuts: bool('扫镜头切点(下14-21MB)'),
       comments: bool('顺带附上评论区分析'),
       full: bool('全量逐字转写'),
-      prompt: str('给 ASR 的提示词'),
+      prompt: PROMPT_ARG,
     }, ['url']),
   },
   {
     name: 'vidlens_job',
     bridge: 'job',
     timeoutMs: 120_000,
-    description: '查询 / 等待后台任务：wait_seconds 建议 20-30（上限 60）。完成时返回完整报告，运行中返回阶段与百分比。',
+    description: '查后台任务：运行中给阶段与百分比，完成给结果。',
     parameters: P({
       job_id: str('vidlens_job_start 返回的 job_id'),
       wait_seconds: num('最多等多少秒，默认 20（夹在 0–60）'),
@@ -528,8 +545,7 @@ const TOOLS = [
     name: 'vidlens_library',
     bridge: 'library',
     timeoutMs: 60_000,
-    description: '列出本地已缓存 / 已处理过的视频（零网络）：标题、时长、转写来源与段数、是否有 brief、拼图与帧数量、占用空间、处理时间。'
-      + '开工前先看它，能避免重复下载；它也是 vidlens_seek 的索引。',
+    description: '0 网络：列本地已缓存视频，避免重复下载。',
     parameters: P({
       limit: int('最多列多少个，默认 20（上限 100）'),
       query: str('按标题或 id 过滤（可选）'),
@@ -539,8 +555,7 @@ const TOOLS = [
     name: 'vidlens_seek',
     bridge: 'seek',
     timeoutMs: 60_000,
-    description: '在已缓存的转写里按关键词查原话，返回视频 id + 绝对时间码（零网络）。用来回答「他在第几分钟说过 X」。'
-      + '给定 url 时只查那一个视频；没命中就先用 vidlens_brief 建立转写。',
+    description: '0 网络：在缓存转写里按关键词查原话→时间码。',
     parameters: P({
       query: str('要查的关键词或原话片段'),
       url: str('可选：只在这个视频里查'),
@@ -551,8 +566,7 @@ const TOOLS = [
     name: 'vidlens_compare',
     bridge: 'compare',
     timeoutMs: 600_000,
-    description: '批量元数据对比（每个链接 0 媒体下载）：一次给出多个视频的时长、字幕情况、播放量、标题，'
-      + '用来快速筛选「这几个视频先看哪个」。最多 8 个链接。',
+    description: '0 媒体下载：多个链接的时长/字幕/播放量对比，先决定看哪个。',
     parameters: P({
       urls: { type: 'array', items: { type: 'string' }, description: '要对比的链接列表（最多 8 个）' },
     }, ['urls']),
@@ -561,8 +575,7 @@ const TOOLS = [
     name: 'vidlens_models',
     bridge: 'models',
     timeoutMs: 30_000,
-    description: '本地模型目录与硬件建议：哪些已安装、多大、什么用途、这台机器适合哪个。只读，绝不自动下载；'
-      + '模型缺失时先调它，再问用户是否安装。',
+    description: '本地模型目录与硬件建议（只读，不自动下载）。',
     parameters: P({
       action: str('list（默认）看目录；recommend 看本机建议'),
     }),
@@ -571,24 +584,150 @@ const TOOLS = [
     name: 'vidlens_doctor',
     bridge: 'doctor',
     timeoutMs: 180_000,
-    description: '自检：python / ffmpeg / yt-dlp / 依赖 / ASR 模型 / 磁盘 / 网络。哪里断了直接说，并给出修法。',
+    description: '自检：python/ffmpeg/yt-dlp/依赖/模型/磁盘/网络，断了直接说。',
+    parameters: P({}),
+  },
+  {
+    name: 'vidlens_budget',
+    bridge: 'budget',
+    local: true,
+    timeoutMs: 5_000,
+    description: '查本对话已用多少上下文预算，是否已进强制摘要模式。',
     parameters: P({}),
   },
 ]
 
-// ----------------------------------------------------------------------- apply
+// --------------------------------------------------------------- context budget
+// DSH hands a tool no session id, but every dispatch carries the Agent it runs
+// for, and there is one Agent per conversation. Keying the ledger on it gives
+// per-chat accounting without inventing ids. The ledger is advisory for the
+// model and a hard clamp for the expensive arguments: past the ceiling, brief is
+// forced to digest, watch cannot widen its window, comments cannot ship base64.
+const BUDGET_WARN = 12_000
+const BUDGET_HARD = 24_000
+const MEMO_TTL_MS = 20 * 60 * 1000
+const ledgers = new WeakMap()
+let nextAgentId = 0
+const fallbackLedger = { chars: 0, calls: 0, sessionId: 'shared', memo: new Map() }
+
+function ledgerFor(exec) {
+  const agent = exec && exec.agent
+  if (!agent || typeof agent !== 'object') return fallbackLedger
+  let ledger = ledgers.get(agent)
+  if (!ledger) {
+    nextAgentId += 1
+    ledger = { chars: 0, calls: 0, sessionId: `s${nextAgentId}`, memo: new Map() }
+    ledgers.set(agent, ledger)
+  }
+  return ledger
+}
 
-const PROMPT = `## vidlens（本地视频取证）
+function memoKey(tool, args) {
+  // Volatile arguments must not collapse into the same key.
+  const stable = {}
+  for (const k of Object.keys(args || {}).sort()) {
+    if (k === 'refresh' || k === 'force' || k === 'session') continue
+    stable[k] = args[k]
+  }
+  try {
+    return `${tool.bridge}|${JSON.stringify(stable)}`
+  } catch {
+    return ''
+  }
+}
+
+function repeatStub(hit) {
+  const head = String(hit.head || '').replace(/\n/g, ' ').slice(0, 120)
+  return ['[重复调用，未重跑] 这次调用的参数与上文那次完全相同，结果没有变化，所以不再重传'
+    + `（上次回传 ${hit.chars} 字）。`,
+    head ? `上次开头：${head}` : '',
+    '要看新东西：改参数（换区间/换 level，或传 refresh=true）——原样重试只会再占一遍上下文。']
+    .filter(Boolean).join('\n')
+}
+
+function failureStub(hit) {
+  return ['[上次同样的调用失败过，未重试]', String(hit.error || '').slice(0, 240),
+    '原样重试只会再烧一次上下文；换 URL/参数，或先 vidlens_doctor 看环境。'].join('\n')
+}
+
+function noteSpend(ledger, text) {
+  ledger.chars += String(text || '').length
+  ledger.calls += 1
+}
+
+function overBudget(ledger) {
+  return ledger.chars >= BUDGET_HARD
+}
 
-拿到公开视频链接时，按人类看片的顺序取样，不要一上来就下载整片：
+function enforceBudget(ledger, tool, args) {
+  const shaped = { ...(args && typeof args === 'object' ? args : {}) }
+  if (!overBudget(ledger)) return shaped
+  if (tool.bridge === 'brief') shaped.level = 'digest'
+  if (tool.bridge === 'watch') {
+    const minutes = Number(shaped.minutes)
+    shaped.minutes = Number.isFinite(minutes) && minutes > 0 ? Math.min(minutes, 5) : 5
+  }
+  if (tool.bridge === 'comments') shaped.with_images = false
+  return shaped
+}
 
-1. \`vidlens_meta\`（0 下载）判断值不值得看；
-2. \`vidlens_plan\`（0 下载）拿章节，挑 2–3 段；
-3. 每段：\`vidlens_window\` 读台词，\`vidlens_sheet\` 看画面（图片直接出现在结果里）；
-4. 平台字幕优先：\`vidlens_subs\`（0 下载）；没有字幕才让 \`vidlens_brief\` 走本地 ASR；
-5. 超过 20 分钟且无字幕时，\`vidlens_brief\` 只给章节是正常行为；要全量逐字用 \`vidlens_job_start(full=true)\` → \`vidlens_job\` 轮询。
+function budgetNote(ledger) {
+  if (ledger.chars < BUDGET_WARN) return ''
+  const kb = (ledger.chars / 1000).toFixed(1)
+  const pct = Math.round((ledger.chars / BUDGET_HARD) * 100)
+  const head = `\n\n[预算] 本对话已回传约 ${kb}k 字（${ledger.calls} 次，占软上限 ${pct}%）。`
+  if (overBudget(ledger)) {
+    return head + '已超软上限：后续只能摘要/分段，level=full 与评论配图已被自动关掉。'
+  }
+  return head + '再加一份全文会明显挤占上下文；能回答就别再加料。'
+}
 
+function budgetReport(ledger) {
+  const tokens = Math.round(ledger.chars / 1.4)
+  const state = overBudget(ledger)
+    ? '已超软上限（brief 强制 digest、watch 每段 ≤5 分钟、评论图关闭）'
+    : ledger.chars >= BUDGET_WARN ? '接近软上限（每次回执会带预算提示）' : '正常'
+  return ['# 上下文预算台账（本对话）',
+    `- 已回传文字: ${ledger.chars} 字（中文约 ${tokens} tokens）`,
+    `- 工具调用: ${ledger.calls} 次`,
+    `- 软上限 ${BUDGET_WARN} 字 / 硬上限 ${BUDGET_HARD} 字`,
+    `- 状态: ${state}`,
+    '',
+    '口径：只统计本插件返回的文字长度，不含图片和你自己的推理；重载插件或新会话会重新计数。'].join('\n')
+}
+
+// ----------------------------------------------------------------------- apply
+
+const PROMPT = `## vidlens（本地视频取证）
+
+拿到公开视频链接时，默认「一次答完」，别让用户陪你看片：
+
+1. \`vidlens_meta\`（0 下载）确认时长/字幕；
+2. \`vidlens_brief\`（默认 digest，约 1.5k 字：章节 + 5 句关键台词 + 全文路径）；
+3. **直接给结论**：讲了什么、立场/结构、值不值得看、哪里可疑。
+   不要问「要继续看吗」，不要一段一段汇报——用户要的是结论，不是陪你走流程。
+4. 摘要只抽样看了几个点，所以结论要说「粗看」；不要把它说成逐字看完。
+   **结论前先写一行覆盖范围**：音频 ✓ / 画面 ✗（或 ✓）/ 评论 ✗——工具结果里已经是这个格式，
+   照抄不要改。没看画面就说没看，别让「我读完了转写」读成「我看完了视频」。
+   要更硬的证据再补一次 \`vidlens_window\`（某段台词）或 \`vidlens_soundscape\`（声音），仍然**一次答完**。
+
+**只有用户明确要「细看 / 详细 / 逐段 / 每段都说」时**才分段：
+\`vidlens_watch\` 一段一段看（默认 5 分钟、约 0.5k 字），每段先把这一段讲给用户、
+报进度（已看 05:00 / 40:45），再问「继续还是先讲这段」。用户说继续才调下一段。
+
+工具顺序（需要更多证据时才往下走）：
+1. \`vidlens_plan\`（0 下载）拿章节，挑 2–3 段；
+2. \`vidlens_window\` 读台词，\`vidlens_sheet\` 看画面（图片直接出现在结果里）；
+3. 平台字幕优先：\`vidlens_subs\`（0 下载）；没有字幕才让 \`vidlens_brief\` 走本地 ASR；
+4. 超过 20 分钟且无字幕时，\`vidlens_brief\` 只给章节是正常行为；要全量逐字用 \`vidlens_job_start(full=true)\` → \`vidlens_job\` 轮询。
+
+- **细看才分段**：只有用户要「细看 / 逐段」时才用 \`vidlens_watch\`；默认模式不要主动分段、也不要说「要不要继续看」。
+  分段时每段先把这一段讲给用户（内容 + 初步判断），报进度（「已看 05:00 / 40:45，12%」），再问一次要不要继续。
 - 开工前先 \`vidlens_library\`，已处理过的视频不要重复下载；问「他哪分钟说过 X」用 \`vidlens_seek\`。
+- **上下文预算**：\`vidlens_brief\` 默认只给摘要（约 1.5k 字）；\`level="full"\` 是 6–9k 字，只在用户明确要全文时才用，
+  而且同一个视频**不要重复调用**（结果已经在上文里了）。看细节用 \`vidlens_window\`（约 0.8k 字/分钟），
+  不要用 brief 代替 window。图片不要连发：一次 1 张，\`vidlens_frames\` 一次最多 2 张，除非用户要求更多；
+  \`vidlens_comments\` 默认不返回配图（base64 很贵），要看评论图才传 with_images=true。
 - 问「有没有敲桌子/吃饭/水声/杂音」用 \`vidlens_soundscape\`（AudioSet 527 类 + 概率 + 时间码）；
   它识别不了「喝水/吞咽」这类动作，别把概率当事实。
 - 一次评估多个链接用 \`vidlens_compare\`（0 媒体下载）。
@@ -618,14 +757,47 @@ export function apply(ctx, config) {
       isConcurrencySafe: () => true,
       timeoutMs: tool.timeoutMs || DEFAULT_TIMEOUT_MS,
       async execute(args, exec) {
-        const payload = { tool: tool.bridge, args: args && typeof args === 'object' ? args : {} }
-        const res = await bridge.call(payload, { signal: exec?.signal, timeoutMs: tool.timeoutMs })
+        const ledger = ledgerFor(exec)
+        if (tool.bridge === 'budget') return { text: budgetReport(ledger) }
+        const shaped = enforceBudget(ledger, tool, args)
+        if (tool.bridge === 'watch') shaped.session = ledger.sessionId
+        if (shaped.refresh === true || shaped.force === true) {
+          const stale = memoKey(tool, shaped)
+          if (stale) ledger.memo.delete(stale)
+        }
+        const key = memoKey(tool, shaped)
+        const hit = key ? ledger.memo.get(key) : null
+        if (hit && Date.now() - hit.at < MEMO_TTL_MS) {
+          return { text: hit.ok ? repeatStub(hit) : failureStub(hit) }
+        }
+        let res
+        try {
+          res = await bridge.call({ tool: tool.bridge, args: shaped },
+            { signal: exec?.signal, timeoutMs: tool.timeoutMs })
+        } catch (err) {
+          if (key) {
+            ledger.memo.set(key, {
+              ok: false, at: Date.now(), error: String(err?.message || err),
+            })
+          }
+          throw err
+        }
         const value = { text: res.text || '' }
         if (tool.images && res.images.length) {
           const { refs, notes } = await attachImages(ctx, res.images)
           if (refs.length) value.images = refs
           if (notes.length) value.text += '\n\n' + notes.map((n) => `（${n}）`).join('\n')
         }
+        if (key) {
+          ledger.memo.set(key, {
+            ok: true,
+            at: Date.now(),
+            chars: value.text.length,
+            head: value.text.slice(0, 160),
+          })
+        }
+        noteSpend(ledger, value.text)
+        value.text += budgetNote(ledger)
         return value
       },
     }
@@ -638,4 +810,8 @@ export function apply(ctx, config) {
   }
 }
 
-export const __internals = { TOOLS, Bridge, resolveProjectDir, resolvePython, PROMPT, attachImages }
+export const __internals = {
+  TOOLS, Bridge, resolveProjectDir, resolvePython, PROMPT, attachImages,
+  BUDGET_WARN, BUDGET_HARD, enforceBudget, budgetNote, budgetReport, noteSpend,
+  memoKey, repeatStub, failureStub,
+}

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "dsh-vidlens",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "VidLens for DeepSeek Harness: turn a public video into an evidence table (timecoded transcript, sampling sheets, sound events, comments) without downloading the whole file. 18 native tools backed by the local vidlens Python core.",
   "keywords": [

package/tools/selftest.mjs

@@ -40,13 +40,44 @@ for (const t of tools) {
   assert(`${t.name}: parameters is an object schema`,
     t.parameters && t.parameters.type === 'object' && t.parameters.properties,
     JSON.stringify(t.parameters || {}).slice(0, 120))
-  assert(`${t.name}: description >= 30 chars`, String(t.description || '').length >= 30)
+  // Schemas cost tokens on every request, so "short but specific" is the goal.
+  // 16 chars still rules out placeholders; the old 30-char bar just forced padding.
+  assert(`${t.name}: description >= 16 chars`, String(t.description || '').length >= 16,
+    String(t.description || ''))
   assert(`${t.name}: has a deadline`, Number(t.timeoutMs) > 0, `${t.timeoutMs}ms`)
   for (const req of t.parameters.required || []) {
     assert(`${t.name}: required '${req}' is declared`, !!t.parameters.properties[req])
   }
 }
 assert('prompt section mentions the sampling order', /vidlens_meta/.test(mod.__internals.PROMPT))
+assert('prompt defaults to one coarse answer', /直接给结论/.test(mod.__internals.PROMPT))
+
+// ------------------------------------------------------------- 1b. budget ledger
+{
+  const I = mod.__internals
+  const ledger = { chars: 0, calls: 0 }
+  assert('budget: no note below the warn line', I.budgetNote(ledger) === '')
+  I.noteSpend(ledger, 'x'.repeat(I.BUDGET_WARN + 10))
+  assert('budget: note appears past the warn line', /预算/.test(I.budgetNote(ledger)))
+  const brief = I.TOOLS.find((t) => t.bridge === 'brief')
+  const watch = I.TOOLS.find((t) => t.bridge === 'watch')
+  const comments = I.TOOLS.find((t) => t.bridge === 'comments')
+  assert('budget: full brief is allowed below the ceiling', I.enforceBudget(ledger, brief, { level: 'full' }).level === 'full')
+  ledger.chars = I.BUDGET_HARD + 1
+  assert('budget: brief is clamped to digest past the ceiling', I.enforceBudget(ledger, brief, { level: 'full' }).level === 'digest')
+  assert('budget: watch is clamped to 5 minutes', I.enforceBudget(ledger, watch, { minutes: 30 }).minutes === 5)
+  assert('budget: comment images are forced off', I.enforceBudget(ledger, comments, { with_images: true }).with_images === false)
+  assert('budget: report renders', /台账/.test(I.budgetReport(ledger)))
+
+  const briefTool = I.TOOLS.find((t) => t.bridge === 'brief')
+  const k1 = I.memoKey(briefTool, { url: 'u', level: 'digest' })
+  const k2 = I.memoKey(briefTool, { url: 'u', level: 'full' })
+  const k3 = I.memoKey(briefTool, { url: 'u', level: 'digest', refresh: true })
+  assert('memo: different args give different keys', k1 !== k2)
+  assert('memo: refresh does not change the key (it clears instead)', k1 === k3)
+  assert('memo: repeat stub names the cost', /未重跑/.test(I.repeatStub({ chars: 1234, head: 'x' })))
+  assert('memo: failure stub refuses a blind retry', /未重试/.test(I.failureStub({ error: 'boom' })))
+}
 
 // -------------------------------------------------------------- 2. python side
 const project = process.env.VIDLENS_PROJECT || path.resolve(ROOT, '..', 'vidlens')
@@ -111,8 +142,8 @@ while (!ready && child.exitCode === null && Date.now() < bootDeadline) {
 assert('bridge boot handshake', !!ready, ready ? `py ${ready.python} @ ${ready.project}` : stderr.slice(-500))
 assert('bridge imported vidlens', !!ready?.ok, ready?.error || '')
 assert('bridge exposes every tool the Host registers',
-  tools.every((t) => (ready?.tools || []).includes(t.bridge)),
-  `missing: ${tools.map((t) => t.bridge).filter((b) => !(ready?.tools || []).includes(b)).join(',')}`)
+  tools.filter((t) => !t.local).every((t) => (ready?.tools || []).includes(t.bridge)),
+  `missing: ${tools.filter((t) => !t.local).map((t) => t.bridge).filter((b) => !(ready?.tools || []).includes(b)).join(',')}`)
 
 try {
   const library = await call('library', { limit: 3 })