dsh-pf-stream
中文 | English
DeepSeek Harness（DSH）视频感知插件。模型用一个工具即可「看」本地视频：
- 连续事件 → 自适应流式采样。运动时按位移积分抽低 token 过程单元；停稳与顿挫波峰时定格高清焦点单元。
- 可疑时间点 → 确定性检视。能力：元数据探测、指定时间戳抽帧、均匀切片、局部 RoI 放大复核。
全部画布对齐 DeepSeek-V4.1-Flash 视觉编码管线：42px 超像素网格，计费 r×(c+1)+2。四种形态计费均 ≤530 token，满足单图 1024 token 上限。服务端按画布原始分辨率计量。
能力路由
一个主工具 dsh-pf-stream，统一 intent.action 路由：
| action | 引擎 | 用途 |
|---|
pf_stream（默认） | 动态流式采样 | 运动中抽 336² 过程单元（P）；停稳/波峰定格 672² 焦点单元（F）。施密特四状态机 + 双层自适应调节（意图基准 + 内容自闭环 R1-R4） |
timestamps | 确定性检视 | 指定时间戳单帧/组合高清检视，支持 roi_hint 局部放大 |
uniform | 确定性检视 | 固定步长或目标帧数均匀切片 |
probe | 确定性检视 | 仅元数据（显示宽高/旋转/末帧 PTS/流摘要），零视觉 token |
安装
1. 安装插件
- 在 DSH 插件管理器中搜索
dsh-pf-stream，安装最新版本。
- 或直接对智能体说「安装插件 dsh-pf-stream」，智能体经 plugin_manager 完成同一流程。
安装由宿主执行：宿主经 pnpm 安装包，读取 cordis.patch.yml 挂载插件。peer 依赖 @deepseek-ai/cordis 与 @deepseek-ai/schemastery 由宿主运行时解析；运行时直接依赖仅 pngjs，画布 PNG 编码参数固定，输出字节幂等。
2. 准备 ffmpeg 与 ffprobe
任选一种安装方式：
winget install Gyan.FFmpeg # Windows
brew install ffmpeg # macOS
sudo apt install ffmpeg # Debian / Ubuntu
也可从 ffmpeg.org 下载解压，用环境变量指向 bin 目录。可执行文件定位顺序：插件配置 ffmpegPath / ffprobePath → DSH_FFMPEG_PATH / FFMPEG_PATH → DSH_FFMPEG_DIR → ~/.dsh/tools/ffmpeg/bin → ~/.dsh/bin → PATH。
3. 验证安装
安装成功后，模型侧出现工具 dsh-pf-stream。用任一本地视频探测元数据：
{ "video_path": "D:/videos/demo.mp4", "intent": { "action": "probe" } }
返回显示宽高、时长、帧率，即安装成功。
使用
流式感知（问「画面里写了什么」）：
{
"video_path": "D:/videos/demo.mp4",
"intent": { "action": "pf_stream", "focus": "detail", "mode": "dense" }
}
定点复核（流式结果中 12.9s 处发现文字）：
{
"video_path": "D:/videos/demo.mp4",
"intent": {
"action": "timestamps",
"timestamps_ms": [12900],
"roi_hint": { "x": 0.2, "y": 0.3, "w": 0.4, "h": 0.4 }
}
}
顶层同时接受视频检视领域常见便捷字段：start_time / end_time / timestamps / fps / interval / num_frames / crop / probe_only。入口适配器将其归一化为标准 intent 结构。
返回内容
每次调用返回一个或多个画布包：
- PNG 画布：四形态之一（见下表）。单元间双色隔离线阻断相邻边缘特征串扰；可选超像素角标渲染单元编号。画布 PNG 同时作为图像内容块进入模型上下文（单次调用至多
maxImagesPerCall 张）。
- 结构化元数据：
packet_id、每单元 PTS、token 网格 bbox、源采样 bbox、双载体 SHA-256。
- 时序提示行：模型可读的 P/F 单元时间轴（如
[Packet #42 | Anchor: #105 | #101(P, 12.1s, Left-Top) → …]）。
会话级能力：
- 意图跨调用持久化。
- 流式游标续窗：同视频下次调用从上次位置继续。
- 两级历史引用：热区最近 2 包整条带复用；冷区至多 4 个 F 锚点独立载体复用。
- Epoch Compaction：默认 6 包窗口批量热转冷，保持多轮对话 Prefix KV-Cache 前缀稳定。
画布与计费
| 形态 | 布局 | Token |
|---|
FORM_1_STANDARD_STRIP | 4P + 1F，1344×672 | 530 |
FORM_2_COMPACT_4P | 4P，672×672 | 274 |
FORM_3_COMPACT_1F | 1F，672×672 | 274 |
FORM_4_PARTIAL_STRIP | 1-3P + 1F，1344×672 | 530 |
画布样例
FORM_1 标准条带：左半 4 个过程单元（P），右半 1 个焦点单元（F）。
FORM_1 标准条带
FORM_2 纯过程：4 个过程单元。
FORM_2 纯过程
FORM_3 单焦点：roi_hint 局部放大检视。
FORM_3 单焦点 RoI 放大
配置
| 配置项 | 默认 | 说明 |
|---|
renderVisualId | true | 单元左上角超像素反色角标 |
maxPacketsPerCall | 64 | 单次调用返回包数上限 |
maxFramesPerCall | 128 | 确定性抽帧单次目标帧数上限（frame_count 受此钳制） |
maxImagesPerCall | 20 | 单次调用回传图像上限（宿主单条消息图像上限 20） |
maxTokensBudgetPerCall | 65536 | 单次调用视觉 token 预算 |
maxRequestBytes | 56 MiB | 请求字节软水位（Base64 后口径） |
maxColdRefs | 4 | 冷区引用上限 |
defaultStreamWindowMs | 10000 | pts_window 缺省时窗口长度（毫秒） |
streamWorkMaxEdge | 2048 | 流式解码工作分辨率长边上限（定点检视恒全分辨率） |
epochCompactionWindow | 6 | 热转冷批量收敛窗口（包数） |
meteringProfile.imageCountTiersEnabled | false | ≥15 图单边 4096px 规则门控 |
测试
pnpm test # boundary（纯逻辑）+ e2e（fixture 驱动），20 项边界用例
pnpm run build # TypeScript 编译
pnpm verify:host # 宿主契约自检（Schema 形状/关键字子集/依赖边界）
发布
npm 发布由 GitHub Actions 自动执行。流程与版本策略见 docs/发布规范.md。
许可证
Apache-2.0。
