# Croco TV Studio

Croco TV Studio 是一个面向 AI 视频创作的工作台。它把创意、文稿和参考素材整理成可制作的视频项目，并在同一个界面中完成故事梳理、风格设定、角色与场景设计、素材生成和视频编排。

它运行在 DeepSeek Harness 中。你可以和 Agent 对话推进创作，也可以直接在 Studio 里查看、编辑和生成项目内容。

## 核心功能

- **从创意或资料开始**：既可以从一个想法起步，也可以导入 TXT、Markdown、JSON、PDF 和图片等已有资料。
- **整理故事与项目设定**：生成或编辑完整 Story，提取标题、概述、题材、主题、世界观、语言、受众、画面比例和时长等信息。
- **建立统一的视觉风格**：选择已有风格，或根据文字和参考图创建项目风格，并分别管理图像与视频的视觉描述。
- **设计角色、场景和道具**：把故事中的关键实体整理成可编辑卡片；卡片描述只保留主体可见的外观设计，不混入名称复述、人物关系、剧情用途或季集场镜信息，并可生成主图、参考图和其他项目素材。
- **管理角色与声音**：同步角色库或把项目角色保存到本地，在项目中绑定角色图片、Voice ID 和参考音色，也可以为角色生成新的参考音色。
- **生成多媒体素材**：在项目内生成或优化图片，并继续制作语音、视频和音乐素材。
- **规划视频结构**：把 Story 拆分为 Video Unit，设计 Storyboard 和关键分镜，并在 Croco 导演台的时间线上统一编排；选中 Unit 后可在顶层“故事线”中追溯对应的 Story Script 原文。
- **与 Agent 协同创作**：把 Studio 中选中的内容引用到对话，也可以从 Inspector 把选中画面的完整元素上下文和修改要求直接发送到当前 Croco 对话。

Studio 文字引用会随原用户消息持久化，并作为紧邻该指令的模型上下文提交。Agent 可以直接处理参考卡中的精确选区，不需要用户再次粘贴内容。

## 工作流程

新视频创建在打开 Studio 前固定确认三项信息：先确认用户是否已有剧本或故事梗概，再选择横屏 16:9 或竖屏 9:16，最后从实时启用的风格列表中选择视觉风格或填写“其他”。用户没有剧本时，Agent 使用 Story Crafting 先生成并保存 Story，再继续画幅与风格选择；“其他”的文字可以为空，也可以直接描述风格，并由 Studio 后续解析在同一 Conversation 中处理。三步完成前不会打开 Studio，也不会询问视频类型、时长、受众或 Project Folder。入口确认的画幅和预选风格属于解析输入，首次点击“开始解析”不会显示覆盖警告；只有项目已经产生解析结果时，重新解析才要求确认。打开、继续或编辑已有 Croco 项目时直接恢复，不重复执行新视频入口。

Croco TV Studio 用三个阶段组织一个视频项目：

1. **源文件**

   导入文稿和参考素材，整理并确认完整 Story。没有现成文稿时，也可以从创意开始生成。

2. **解析结果**

   在随面板宽度重排的分组表单中查看并编辑项目设定，并继续管理视觉风格、角色、场景和道具，生成项目需要的图片与角色声音素材。

   Entity Extraction 把实体名称单独保存，卡片 Description 和图片 Prompt 都只描述主体本身的可见形态、色彩、材质、结构、光线与设计特征。匹配统一角色库的角色会读取当前选定主图，由当前 Agent 提纯不含艺术风格的具体外观描述；不会写“沿用角色库设定”等占位语，也不会调用独立视觉模型。实体图片规划对角色、场景和道具统一使用 `风格：<项目 imagePrompt>` 注入完整风格描述；风格名称只用于界面展示，不进入最终图片 Prompt。

   角色、场景和道具的「生成」与「重新生成」使用相同的描述、风格和版式流程，仅角色卡 Reference image 区域实际显示图片时附带该参考图；角色库绑定本身不会添加参考图。「优化」只使用当前主图和优化说明。新主图替换旧主图时，旧图保留为历史图片，参考图区保持不变。这些规则同时适用于 Agent 调用和页面按钮。

3. **Croco 导演台**

   把 Story 规划为 Video Unit、Storyboard 和关键分镜，由当前 DSH Agent 准备 H3 Prompt 并生成真实视频轨，使用 480p 素材完成剪辑，最终导出时再准备高清源。

   导演台顶部的“故事线”和“Inspector”是两个独立模式。“故事线”占用完整右侧面板，显示当前 Video Unit 链接的 Story Script 原文；没有 Video Unit 时显示“还没有故事线”。“Inspector”保留画面元素选择与编辑，并可把元素修改请求直接交给当前对话中的 Agent；原生 `Nothing selected` 空态只在 Inspector 中显示。导演台不提供单帧 Capture 下载入口。

「解析 Video Unit」会先检查角色、场景和道具主图以及角色 Reference Voice 的真实文件，并通过现有素材生成链路补齐缺项。素材就绪后，Agent 第一遍根据故事内容与叙事节奏确定 Unit 数量和时长，来源有序且不重叠，原文区间之间可以留白。12 秒以内及按需延长至 12–15 秒是拆解建议，规划与编辑不设置数量或时长区间的硬限制。第二遍先基于每个 Unit 的正式文稿生成 Storyboard 画面描述，再组合风格、版式、真实参考图和生产限制得到 Full Prompt；随后用独立的 Keyframes Prompting System Prompt 从正式文稿提取独立 Unit 的 1–5 个或衔接 Unit 的 0–5 个内部 beat 入口描述，并为每帧生成 Full Prompt。两类规则按产物渐进加载，每完成一个产物就写入正式计划。

Entity Extraction 和 Entity Design 以已有角色的声音描述为基准，为新角色写出丰富、差异明显的声音描述。描述按角色设定展开音高、共鸣、厚薄、气声或颗粒感、咬字和句尾习惯，让同龄、同性别角色也有鲜明的声音身份。已有角色保持既定声音身份；新角色的差异直接体现在描述内容中。

角色 Reference Voice 的声音描述会明确一个具体数字年龄。拆解时优先采用自然偏快、偏快或很快的节奏，自然中快可作为相对较慢的角色选择。年龄与语速等维度属于提示词的描述设计；生成流程直接使用已有声音描述，慢速无需说明原因，也不会因未写年龄或特定语速而拒绝生成。声音描述为空时，Agent 会结合 Story 和已有声音设定补充，不增加用户问题。

Croco 导演台时间线按“Video Unit 标题”、“分镜文稿”、“故事板”、“关键分镜”和原生 Video Clip 五层连续显示。标题只展示编号及相邻 Unit 的衔接按钮；窄卡片简写为 VU01 等，不能通过拖动标题修改时长。Video Unit 只要已有文稿和时间就会显示规划卡，不以 Storyboard 或关键分镜是否成图作为前提。故事板和关键分镜有图片时以图片 cover 为卡片主体，没有图片时显示当前画面 Description；Description 也为空时保留无文案卡片，不在时间栏展示 Full Prompt 或缺项提示。点击三类规划内容卡片会打开对应的文稿或 Prompt 编辑弹框。每个 Video Unit 的三条规划内容、全部关键分镜和唯一绑定的非音频 Video Clip 共用同一时长与关联高亮，实际点击的卡片或原生 Clip 使用更强的精确选中反馈；拖动可编辑卡片的右边界时整组与后续 Unit 实时联动，鼠标旁显示精确时长，松手后统一保存。播放头贯穿全部五层。

Storyboard 和关键分镜保留 Description／Full Prompt 双模式。Description 模式会用当前描述重建完整出图 Prompt；用户手工编辑 Full Prompt 后则切换为 Full Prompt 模式，生成时直接使用新内容，不再拼接或优化。可以由 Agent 按指定卡片或批量生成画面，也可以点击时间线卡片，在 Prompt 弹窗中直接生成或重新生成。已有画面支持填写优化说明并执行 Image Edit。生成状态、失败信息和当前图片都保存在 Project Folder；卡片显示缩略图，重新打开项目后仍会恢复。

视频轨的已绑定 Clip 和待生成占位卡共用边框、圆角、字体及选择反馈；初始空白 main 显示为 `VU01 · Video Clip 待生成`，已有原生内容显示所属 Unit 的 `Video Clip`。调整任意 Unit 时，五层实时使用同一时间尺度，播放头保留绝对时间，仅在超出缩短后的整个项目末尾时夹到末尾；取消或保存失败恢复原位置。预览时长覆盖全部规划 Unit，不把完整规划时长写成首个 Clip 的时长。

Video Unit 标题交界处的“衔接”按钮读写 `dependency`，只允许引用紧邻前片。连接后暂停独立 0 秒关键帧，后段开场由前片继承；解除时恢复仍可用的首帧，无法恢复则提示补齐。当前前片有 H3 job ID 时固定使用 AddGuide 读取原片末尾 22 帧，裁剪或变速不改变这个选择；服务端拒绝时直接报错，不自动换成单帧方案。只有非 H3 视频才提取实际尾帧，作为下一段 H3 R2V 的开场参考。前片缺失时提示先生成或解除衔接，批量重生成等待本次前片的新版本。R2V 多参考图不保证像素级强制首帧。

项目内容保存在独立的 Project Folder 中。Studio 会持续显示各阶段的完成、进行中和失败状态，重新打开项目后可以从已有进度继续。

角色完成主图后，可以从角色卡右上角选择「保存到本地」。Croco 会保存角色描述、Prompt、项目图片和已有 Reference Voice，并自动把当前项目角色绑定到新条目。本地角色与远端同步角色一起显示在 **设置 → 角色管理**，也会由后续项目的 `list_characters` 返回并参与同名角色匹配。匹配完成后，`list_characters` 按角色 ID 把当前主图作为图片输入直接返回给当前 Agent 观察；角色库保存在当前 DSH Profile 的持久目录中，拉取远端角色或更新 Bundle 不会删除本地条目。

## 适合谁

- 希望把故事、脚本或资料转成视频项目的创作者
- 需要统一管理角色、风格和多媒体素材的内容团队
- 希望同时使用 Agent 对话和可视化工作台推进制作的 DeepSeek Harness 用户

## Croco Generation Bundle

Croco Generation Bundle 是 Croco TV Studio 的安装包，包名为 `dsh-croco-generation`。它把 Studio、项目解析、角色与风格管理、文档读取，以及图片、视频、语音和音乐生成能力作为一个 Bundle 交付。

HyperFrames 用于实现 Studio 内部的导演台与预览能力，不是顶层产品名称。

### H3 视频生成

`minimax_h3_video` 是独立文件生成工具，使用统一调度中心的 H3 contract v2，`mode` 支持 `r2v`（多参考，默认）和 `t2v`（文字生成，显式指定）。`duration` 必填，为 3–15 秒整数；漏传或错写字段在上传前报错，不默认生成 6 秒。R2V 接受最多 9 张参考图片、3 条参考音频，合计至少一项；素材依次提交为 `reference_image` 和 `reference_audio`。工具直接使用调用方的最终 Prompt，不再调用豆包优化。

Croco TV Studio 的 Video Unit 使用 `video-unit-generation` 流程，由当前 DSH Agent 读取正式文稿、有序参考图片和角色 Reference Voice，输出包含 H3 六字段的 Prompt，字段顺序不限。当前 Unit 可以独立生成，无需等待其他 Unit 规划完成；Host 保留小数规划，仅在 R2V 请求中向上取整（如 13.2 秒提交 14 秒），实际提交遵循 H3 的 3–15 秒整数范围。输入未变时复用已保存 Prompt；新的生成请求仍生成新视频，成功后自动替换对应 Clip 并刷新原视频区域，旧文件保留为历史。同一 requestId/runId 的重试与恢复复用原任务，不另行付费生成。导演台提供当前／全部 Unit 生成、查看视频和重新生成，不增加 Prompt 审核或手动接入关卡。

首轮默认匹配画幅的 480p，`preview` 表示分辨率而非固定短片长度；实际视频短于 Unit 有效时长时，任务报错且不替换原 Clip。横屏 R2V `preview` 保存 manual latent；开始剪辑、刷新和预览导出均不执行二采。最终导出冻结已有剪辑，只对使用的受支持源二采或复用高清，在副本中直接替换源视频并渲染；原视频和活动项目不变。同源多个 Clip 共享高清，不重新生成首采。

默认成片尺寸跟随二采视频的实际宽高，不固定为 1080p。原编辑画布保留，字幕、图片、遮罩、裁切和动效等全部空间布局按相对位置及大小一起映射到最终画面；剪切时间、变速、转场时序和音频参数不变。媒体检查与导出需要可执行的 FFmpeg／ffprobe。H3 当前只有横屏 R2V `preview` 支持续采，断点默认约保留 72 小时；其他画幅或无有效断点的旧视频仍可预览导出，高清导出不会自动降级或付费重做。

传入上一条成功 H3 任务的 36 字符 `addGuideSourceJobId` 可启用 AddGuide，固定引用原片最后 22 帧，`includeGuideAudio` 默认 `false`。独立视频工具仍支持 `refine=true` 自动二采，以及 `refineExecution: "manual"` 延后二采；`minimax_h3_refine` 对源任务续采。自动二采返回 `video` 与 `firstPassPath`，manual 首轮返回 `video`，续采返回子任务的 `video`。这些均为 H3 原生 latent 二采，不是 FlashVSR。

Croco 渠道管理不再显示豆包 Ark 卡片；独立 `generate_speech` 及其 Ark／Seed-TTS 凭据保留，可通过 DSH 凭据管理配置。固定 HyperFrames 0.8.22 的一例 0.75 倍慢放存在帧覆盖检查失败，完整视频链路的当前验证范围与限制见 [实施记录](./specs/feat-video-unit-h3-generation.md#174-当前实现)。

## 安装与使用

在已安装 DeepSeek Harness Web、Node.js 22.19+（22.x）或 24+ 与 pnpm 的环境中运行：

```bash
dsh plugin --profile web add dsh-croco-generation@latest
```

重启 `dsh web` 后，在对话中提出创建、制作或编辑视频的需求，Agent 会打开 Croco TV Studio。每个 Chat 只显示自己打开的视频项目；切换 Chat 时不会共享或沿用另一个 Chat 的 Studio 内容，切回后会恢复该 Chat 已创建的项目以及上次使用的 Studio Tab 和解析结果分区。不同生成能力需要在 **设置 → 生成插件** 中配置对应的服务凭据。

如果 pnpm 11 报 `ERR_PNPM_IGNORED_BUILDS`，在当前 Profile 的 `$DSH_HOME/profiles/web/pnpm-workspace.yaml` 中合并以下配置，然后重新执行安装命令。未设置 `DSH_HOME` 时，目录为 `~/.dsh/profiles/web`。保留文件中的其他配置；若已有 `allowBuilds`，只追加其下的包名条目。

```yaml
allowBuilds:
  esbuild: true
  onnxruntime-node: false
  protobufjs: false
  '@google/genai': false
  tesseract.js: false
```

这与本仓库的依赖脚本策略一致：允许 esbuild 安装其构建可执行文件，跳过其他列出的脚本。tesseract.js 的脚本只打印募捐提示，Croco 的 PDF 读取和渲染不需要运行它。从 `0.1.4` 升级请使用上面的终端命令；该版本的内置更新器仍检查旧的 TypeScript 文件路径。

`0.1.5` 起，所有服务端入口发布为编译后的 ESM JavaScript，安装和启动不需要额外的 TypeScript loader。现有插件包名、配置和 Client 入口保持不变。

## 开发

运行测试前，确保 `ffmpeg` 和 `ffprobe` 在 PATH 中可执行；视频尾帧测试会生成真实 VFR 视频并检查解码结果。发布 CI 在两个 Node 版本的验证任务中安装这些工具。

```bash
pnpm install --frozen-lockfile
pnpm run build
pnpm run test
```

`pnpm run build` 清理 `dist/`，用 TypeScript 构建服务端 JavaScript 与声明，再构建 `lib/client.js`。发布不携带服务端源码或 Source Map。`pnpm pack` 会自动构建并校验入口；正式分发使用 `pnpm run release:verify` 生成的 `.release/artifacts/` tarball，其中还包含已打补丁的 HyperFrames。发行包同时声明它的运行依赖，由安装器为目标设备解析平台相关包。

`release:verify` 在全新临时目录安装实际 tarball，执行安全扫描、普通 Node 全入口导入、资源检查与 HyperFrames Preview 真实启动。发布 CI 覆盖 Node 22.19 与 24，并在 Node 24 下验证 DSH Web 新安装、从 `0.1.4` 升级与重启；所有验证通过后才将同一 tarball 发布到 npm。

仓库结构、实现约束和完整验证要求见 [AGENTS.md](./AGENTS.md)。

## 独立生成

无需打开 Studio，可直接让 Agent 生成图片、视频、音乐和语音，或转录音频。图片默认使用 GPU Qwen Image 2.1，支持最多10张有序参考图；明确指定 GPT Image 时使用 Runware。TTS 由用户选择 MiMo 或火山；MiMo 支持预设声音、声音设计和声音克隆。音频转录使用 GPU WhisperX，保存文本与字幕文件。服务地址和密钥在本地渠道配置及 DSH Credentials 中管理。