dsh-video-forge：DSH 中的在线视频生成

前言¶

DeepSeek Harness（DSH）的核心理念是「一切皆插件」。在构建多模态智能体或编排视频生成任务时，常见需求包括：在对话中直接调用视频模型、对长时任务进行持久化跟踪、在工具链中复用视频资产等。现有方案往往需要自己搭建任务队列、持久化存储或复杂数据结构，开发与维护成本较高。

dsh-video-forge 插件在 DSH 工作区对话中提供在线模型视频生成能力，内置任务持久化、实时进度卡片、成本估算等机制，把视频生成能力与 DSH 的工作流深度集成。

是什么¶

dsh-video-forge 是一个 DSH 插件，用于在 DeepSeek Harness 工作区对话中使用在线视频模型生成视频。插件不包含本地推理路径，仅作为在线模型的客户端，负责任务提交、持久化跟踪、结果流转与成本估算。插件由 tkliuxing 维护，分类为模型推理。

插件的主要能力包括：

在对话中直接调用视频生成工具，生成结果保存到工作区的 renders/<shot>/vNNN.mp4；
使用任务持久化账本，在超时或重启后可恢复任务状态，避免重复计费；
提供实时聊天卡片，在生成过程中展示进度；
提供成本估算与用量查询，基于公开价格源进行聚合与缓存。

安装与启用¶

插件需要 DSH 0.2.x（支持 ^0.2.0-rc.1 || ^0.2.1-rc.2）与 Node.js ^22.19.0 || >=24.0.0。

在 DSH 的 web profile 下执行：

dsh plugin --profile web add dsh-video-forge

安装完成后重启对应 profile，插件即可生效。

配置与提供者¶

插件支持以下协议（在 GUI 插件页选择协议）：

Volcengine ARK (Seedance)
MiniMax (H3)
OpenAI (Sora)
自定义 OpenAI-Videos 兼容网关

配置方式有两种：

通过 GUI：Sidebar → Plugins → Video Forge，选择协议并填写 baseUrl、凭证引用、模型等，支持添加多个提供者。API Key 通过 DSH 凭证服务存储，界面只显示掩码尾数。
通过配置文件：在 profile 的 cordis.patch.yml 中添加配置，例如：

- id: video-forge
  name: dsh-video-forge
  config:
    providers:
      - id: ark
        protocol: ark-seedance
        baseUrl: https://ark.cn-beijing.volces.com/api/v3
        authRef: ARK_API_KEY
        models:
          - id: doubao-seedance-2-0-fast-260128
            modes: [t2v, i2v, flf2v, s2v]
            resolutions: ['480p', '720p']
            aspectRatios: ['16:9', '9:16', '1:1']
    defaultProvider: ark
    defaultModel: doubao-seedance-2-0-fast-260128

模型引用格式为 providerId::modelId。凭证通过 DSH 凭证服务优先解析，其次解析环境变量 <PROVIDER>_API_KEY。

典型用法¶

在对话中使用工具调用：

文本生成视频：
“Make a 5-second shot of a lighthouse at dusk” → 调用 video_generate，返回任务 id 与后台 job id，结果保存在 renders/<shot>/v001.mp4，并在聊天中显示进度卡片。
图像生成视频：
“Make the cat in materials/cat.png turn to the camera” → 使用 first-frame (i2v) 生成，支持拖入工作区图片，插件识别图片路径与字节。
续拍：
“Continue that shot” → 使用 from 工具，以上一拍的最后一帧作为下一拍的起始帧，保存在同一 shot 文件夹。
角色一致性：
“Alice walks in” → 使用 characters: ['alice'] 引用在 video-project.yaml 中注册的角色描述与参考图片，使角色在不同 shot 中保持一致。
查询状态：
“Did it finish?” 或在超时/重启后 → 调用 video_status 查看任务状态、进度、结果位置、失败原因、内容审查拒绝等信息；若未提供任务 id，也会显示当前配置与 manifest 信息。
取消任务：
使用 video_cancel 请求提供者停止任务（与 job_kill 不同，后者仅停止监控，提供者可能继续计费）。

工具列表¶

video_generate：提交一次生成任务（t2v / i2v / flf2v / s2v），返回任务 id 与后台 job id；shot 指定渲染目录；from 续拍；characters 引用已注册角色；拒绝（只读对话、远程工作区、manifest 异常、重复请求）在付费前发生。
video_status：恢复入口；显示最近任务、进度、结果位置、失败、内容审查拒绝、提供者用量；无任务 id 时报告设置与 manifest。
video_cancel：请求提供者停止任务。

成本与数据流出¶

video_status 支持成本查询：

cost: true：按提供者/模型/shot 聚合已结算用量，并按价格表计算总额；estimate 在提交前对请求进行估算。

所有金额标注为估算，最终以提供者账单为准。价格来自公开价格源（LiteLLM 的 model_prices_and_context_window.json），转换汇率 7.0 CNY/USD，按分辨率分层计算。价格源在后台静默获取，缓存于 $DSH_HOME/dsh-video-forge/price-cache.json，优先级为「用户自定义 > 最新抓取 > 缓存 > 内置快照」。每个金额标注 price_source（remote / cache / bundled / none）、年龄与最后一次失败；无价格表的模型标注为「not priced」而非 0。可通过 priceSourceUrl 指定镜像（jsDelivr、npmmirror）或留空以禁用。

数据流出：

上传内容为提示词、引用图片路径、video-project.yaml 中的角色描述、from 的上一拍最后一帧，均通过配置的提供者上传，使用你的 API Key，受提供者条款约束。插件不向作者发送任何数据；插件本身无遥测。提供者的内容审查可拒绝任务，拒绝记录后不再重试相同请求，修改后的请求可继续。

技能（Skills）¶

插件随附五个技能，通过模型 skill 工具加载或部分作为 /name 命令提供，用于引导工作流：

video-project（/video-project）：说明工作区布局与 video-project.yaml，包含路径、默认值、风格、角色、版本编号。
video-prompting：讲解提示词的撰写与修订（主体、运动、镜头、风格、时长与宽高比、提供者差异）。
video-storyboard（/video-storyboard）：将脚本拆分为 storyboard/shots.yaml，并逐拍生成。
video-iterate：讲解续拍 (from)、角色一致性、交付前的最后一帧自检。
video-guide（/video-guide）：端到端使用指南，包括设置、能力边界、成本、视频落地位置。

工作区项目结构¶

典型工作区结构如下：

<workspace>/
  video-project.yaml        # 可选：默认、风格、角色、路径映射
  materials/                # 参考图片（任意布局，路径为工作区相对）
  renders/<shot>/v001.mp4   # 每一拍，不会被覆盖
  renders/<shot>/v001.json  # 生成信息：提示词、模型、素材、用量
  renders/<shot>/v001.last.jpg  # 最后一帧（ARK），用于 `from`

第一次生成时，插件会写入带注释的 video-project.yaml 和 renders/.gitignore（内容为 *）。manifest 示例：

version: 1
defaults: { provider: ark, model: doubao-seedance-2-0-fast-260128, resolution: 720p, aspect_ratio: "16:9" }
style: warm film grain, soft daylight
characters:
  alice: { refs: [materials/alice/*.png], description: "red scarf, short black hair" }
paths: { renders: renders }

适用场景与注意¶

适合在 DSH 工作区中集成在线视频模型、管理多拍任务与角色一致性、复用视频资产的开发者。
插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。
所有生成均通过在线提供者完成，插件本身不包含本地推理路径、ffmpeg 或模型权重，无需 GPU。
成本与用量以提供者账单为准，价格源为公开快照，可能发生变更，建议定期核对。

结尾¶

dsh-video-forge 把在线视频生成能力嵌入 DSH 对话，提供任务持久化、进度卡片与成本估算，适合需要统一编排视频生成工作流的使用者。插件维护与文档可参考：GitHub 仓库。