用户给 GIF / 文件 / B站链接
        │
   ┌────▼─────┐   ffprobe：时长/分辨率/轨道；GIF 逐帧时间轴
   │  探测    │   → access_status（USER_FILE_READY / VIDEO_READY / …）
   └────┬─────┘
        │
   ┌────▼─────┐   ffmpeg 内置 scene 检测（不装 PySceneDetect）
   │  采样    │   概览：均匀 + 首尾 + 镜头切换；精读：围绕指定时间窗
   └────┬─────┘   成本闸门：超图片 token 预算就**减帧**，不超发
        │
   ┌────▼─────┐   GIF 按**帧序号**取（帧延迟不均时按时间 seek 会取错）
   │  抽帧    │   视频按 -ss 取（走 http range，不整段下载）
   └────┬─────┘
        │  图片内容块 + 时间戳清单 → 模型自己看
   ┌────▼─────┐
   │ 模型分析 │   （不开额外 API 调用；就是当前会话的模型）
   └────┬─────┘
        │
   ┌────▼─────┐   紧凑事件（一条 25~50 token）：只有时间范围 + 变化描述
   │ 事件落库 │   证据帧由服务端按时间范围**派生**，模型不用输出 frame_id
   └────┬─────┘   SQLite 第二层：media_tasks / media_frames / media_events / media_raw_outputs
        │
   ┌────▼─────┐   只把标了 w:1 的写成**一条**摘要；推断不写入
   │ 长期记忆 │   → 复用锚点记忆插件的结构化写入接口（第三层）
   └──────────┘

cd '<你的安装目录>\video-understanding'

# ① 数据库（首次会自动创建；也可手动）
node -e "const {createVideoService}=await import('./src/service.js');const s=createVideoService();console.log(s.health());s.close()"

# ② 挂到既有 snowluma-host MCP server（纯追加，自动备份 + 语法检查 + 可一键回滚）
node scripts/integrate-bridge.mjs --apply

# ③ 真实验证（stdio 握手 + 真抽一帧）
node scripts/verify-mcp.mjs --selftest

# 重启桥接，让 QQ 会话拿到新工具（在 qq-bridge 目录下）
restart.bat

node scripts/integrate-bridge.mjs --remove   # 撤掉工具（数据库与临时文件保留）

import { createVideoService } from './src/service.js';
const svc = createVideoService();
await svc.probeSource({ target });            // 探测：拿得到吗、什么能力
await svc.analyze({ target, count: 6 });      // 抽帧（返回帧图 + 时间戳清单）
svc.saveEvents(task_id, events);              // 落时间线（紧凑格式）
svc.queryEvents({ taskId, fromMs, toMs, kind });   // 过滤字段用 camelCase
svc.timeline(task_id);                        // 回读时间线与帧清单
svc.stats();                                  // 成本与失败率
svc.pruneTemp();                              // 按保留期清理第一层

// 先看能不能拿到
{ "tool": "video_bilibili", "arguments": { "target": "BV1GJ411x7h7" } }
// 概览：6 帧，约 1152 token
{ "tool": "video_frames", "arguments": { "source_bilibili": "BV1GJ411x7h7", "count": 6 } }
// 追问某一段 → 局部加密
{ "tool": "video_frames", "arguments": { "source_bilibili": "BV...", "mode": "focus", "start_ms": 62000, "end_ms": 70000, "count": 4 } }
// 落时间线（紧凑格式，一条 25~47 token；w:1 表示值得长期记住）
{ "tool": "video_save_events", "arguments": { "task_id": "V_xxx", "events": [
  { "t": [0, 480],      "e": "平趴不动",     "k": "st", "m": 0 },
  { "t": [1480, 2000],  "e": "支起上身抬头", "k": "mv", "m": 1, "a": "cat", "w": 1 },
  { "t": [3480, 3520],  "e": "回趴",         "k": "mv", "m": 0 }
] } }
// 之后按视频/时间/类型回查（不花 token）
{ "tool": "video_query_events", "arguments": { "task_id": "V_xxx", "from_ms": 1000, "to_ms": 2100, "kind": "motion" } }
// 只把值得记的写进长期记忆
{ "tool": "video_remember", "arguments": { "task_id": "V_xxx" } }

{
  "ffmpegPath": "",              // 留空用 PATH
  "tempRetentionMinutes": 120,   // 第一层（帧图 + 原始模型输出）保留多久；事件不受影响
  "limits": {
    "maxFrames": 16,             // 单次抽帧硬上限
    "defaultFrames": 6,
    "maxDurationSec": 1800,
    "maxBytes": 524288000,
    "frameMaxWidth": 0,          // 0=不限（概览靠像素地板省 token）
    "jpegQuality": 4
  },
  "sampling": {
    "sceneDetect": true,
    "sceneThreshold": 0.3,
    "sceneDetectMaxDurationSec": 600   // 超长视频跳过场景检测，防扫全片
  },
  "cost": {
    "maxImageTokens": 4000       // 超预算自动减帧
  }
}

node scripts/doctor.mjs --bilibili BV1GJ411x7h7   # 环境 + 真实 B 站连通
node --test                                       # 93 个单元/集成测试
node tests/live/bilibili.live.mjs                 # 真实外网联调（需手动）
node scripts/verify-mcp.mjs --selftest            # 走真实 MCP 协议验证工具

video-understanding/
├── package.json / config.example.json
├── migrations/
│   ├── 001_init.sql                  任务/帧/事件/成本 四张表
│   └── 002_three_layer_storage.sql   原始输出表 + 事件字段/索引
├── src/
│   ├── config.js      上限与校验（非法值直接报错）
│   ├── media.js       ffmpeg/ffprobe 封装：argv 数组、超时、协议白名单、请求头白名单
│   ├── probe.js       归一化探测 + GIF 逐帧时间轴 + access_status
│   ├── sampling.js    采样计划、scene 检测、token 估算、成本闸门、时间戳夹紧
│   ├── frames.js      抽帧（GIF 按帧号 / 视频按 seek）
│   ├── event-format.js  紧凑事件 schema、token 预算、证据帧派生
│   ├── events.js      旧格式事件校验（兼容保留）
│   ├── store.js       SQLite 持久化 + 缓存键 + 三层查询 + 成本统计
│   ├── service.js     门面：analyze / saveEvents / queryEvents / timeline / stats / pruneTemp
│   ├── adapters/bilibili.js   B 站适配器（能力状态机 + 明确非官方）
│   ├── memory-bridge.js       第三层：与锚点记忆插件的单向对接（只写 w:1）
│   ├── net-guard.js   URL 安全闸门（协议/内网/DNS）
│   ├── mcp-tools.js   9 个 MCP 工具
│   └── log.js         分级日志（不含媒体内容与凭据）
├── scripts/  integrate-bridge / verify-mcp / doctor
└── tests/    unit / integration / live / fixtures