跳到主要内容
AI教程

使用 CDAF 为 AI 智能体提供快速、经验证的视频上下文

安装 CDAF，生成并验证带时间戳的伴随文件，将视频文本上下文集成到 AI 工作流中。

AI我搜编辑部阅读约 13 分钟
CDAF 视频上下文工作流

CDAF 的作用

CDAF 是 Cached Descriptive Asset Files（缓存式描述资产文件）的缩写，是一种开放的视频伴随文件格式。它使用与视频相同的基本文件名，在视频旁存储带时间戳的纯文本描述。例如，sunset-drone.mp4 会与 sunset-drone.cdaf 配对。

其目标是只描述一次视频，并在后续 AI 任务中重复使用该描述。智能体无需针对每个问题都将同一段素材发送给视频理解模型，而是可以验证并读取体积小得多的 CDAF 文件。

footage/
sunset-drone.mp4
sunset-drone.cdaf

原始视频保持不变，仍可由普通视频软件播放。伴随文件是 UTF-8 文本，包含一个简短的元数据标头，以及针对语言模型优化的 Markdown 描述。

为什么伴随文件可以安全复用

CDAF 标头会记录对应视频的准确 SHA-256 哈希值和字节大小。符合规范的工具使用这些值判断描述是否仍然有效。如果视频发生变化，伴随文件就会过期，不应继续使用。

--- CDAF/1.0
video: sunset-drone.mp4
sha256: 4a7d1ed4…
bytes: 48211394
duration: 00:00:31.500
generator: gemini-2.5-flash
created: 2026-08-26T14:03:12Z
---

## Summary
A 31-second aerial drone clip of a coastal highway at golden hour…

## Segments
[00:00.0-00:05.2] Wide aerial establishing shot…
[00:05.2-00:12.8] The drone pushes in and descends…

## Transcript
(no speech)

## On-screen Text
(none)

## Tags
drone, aerial, coastal highway, golden hour, sunset

正文可以提供摘要、带时间戳的片段、转录文本、屏幕文字和标签。有关规范格式、新鲜度语义、版本控制规则和章节语法，请参阅项目的 CDAF 1.0 规范。

主要功能

  • 经验证的复用：SHA-256 和字节大小元数据会将伴随文件与其所描述的确切视频关联起来。
  • 可读的文本格式：智能体无需再次解码视频，即可读取、搜索和复用描述。
  • 带时间戳的片段：片段时间范围可用于选择剪辑和创建剪辑清单。
  • 零依赖核心：解析、序列化、哈希计算、新鲜度检查和片段提取均使用 Python 标准库。
  • 面向批处理的 CLI：命令行工具可以为整个目录生成伴随文件，并跳过已处于最新状态的文件。
  • 多种细节配置：生成过程支持 brief、standard 和 rich 输出。
  • 智能体技能：打包好的技能会指导编程智能体在分析视频前先检查经验证的伴随文件。
  • 可选的本地生成：代码仓库提供 --local 提供程序，可使用本地模型生成内容，无需 API 密钥。
  • 可选的探测功能：CDAF 可以使用 ffprobe 获取时长、分辨率和帧率元数据；当 ffprobe 不可用时，也能平稳降级。

安装智能体技能

让受支持的编程智能体快速掌握伴随文件优先工作流的方法是：

npx cdaf-skill

默认情况下，该命令会将技能安装到 ~/.claude/skills/cdaf，使其可供所有项目使用。其他受支持的安装方式包括：

npx cdaf-skill --project
npx cdaf-skill --dir <path>
npx cdaf-skill --print
  • --project 会将技能安装到当前项目的 ./.claude/skills/cdaf。
  • --dir 会将技能安装到指定目录。
  • --print 会将技能写入标准输出，以便粘贴到其他智能体框架中。

重复运行安装程序是安全的。未发生变化的技能不会被修改；如果技能已修改，则会先备份为 SKILL.md.bak，再进行替换。

分析视频文件前，请查找具有相同基本文件名的 .cdaf 文件。如果其标头中的 bytes 和 sha256 值与视频匹配，请读取该文件，而不要处理视频本身。

安装 CDAF CLI

Python CLI 需要 Python 3.10 或更高版本。由于 PyPI 版本仍在路线图中，当前 README 建议直接从代码仓库安装。

pip install "cdaf[generate] @ git+https://github.com/UditAkhourii/cdaf.git#subdirectory=cli"

如果你使用的是克隆到本地的代码仓库，请从本地 cli 目录安装 CLI：

pip install ./cli[generate]

生成器实现使用 Gemini Files API。请从 Google AI Studio 获取 Gemini API 密钥，然后将其设置到环境变量中。

macOS 和 Linux

export GEMINI_API_KEY=your-key

Windows PowerShell

$env:GEMINI_API_KEY="your-key"

素材会通过你自己的 API 密钥进行处理。仅用于读取或验证现有伴随文件的命令不需要 API 密钥或生成器依赖项。

生成伴随文件

将一个或多个视频放入某个目录，然后对该目录运行 cdaf generate：

cdaf generate ./footage

CDAF 会描述这些视频，并创建具有相同基本文件名的伴随文件。再次运行时，生成过程会跳过伴随文件已经是最新状态的视频。

选择细节配置

使用 --detail 选择三种已记录的生成配置之一：

cdaf generate ./footage --detail brief
cdaf generate ./footage --detail standard
cdaf generate ./footage --detail rich

请根据下游任务所需的描述性上下文数量选择配置。你还可以使用 --model 选择 Gemini 模型，或使用 --force 请求重新生成。

cdaf generate ./footage --model <gemini-model>
cdaf generate ./footage --force

检查视频库状态

使用 status 命令将伴随文件分类为 FRESH、STALE 或 MISSING：

cdaf status ./footage
  • FRESH：伴随文件与当前视频匹配。
  • STALE：伴随文件存在，但其中记录的身份信息已不再与视频匹配。
  • MISSING：不存在匹配的 CDAF 伴随文件。

该命令不需要 API 密钥或生成器依赖项，因此适合对现有资产库执行轻量级检查。

读取经过验证的描述

如果需要获取伴随文件正文并将其用于智能体、脚本或提示词，请使用 cdaf read：

cdaf read ./footage/sunset-drone.mp4

该命令会在输出描述前验证哈希值。它会拒绝输出已过期的伴随文件，从而将新鲜度规则落实在工具中，而不是仅依赖智能体指令。

在自动化流程中验证伴随文件

只有当匹配的伴随文件格式正确且处于最新状态时，验证命令才会成功退出：

cdaf validate ./footage/clip.mp4

由于只有有效且最新的伴随文件才会让命令以状态码 0 退出，因此该命令可用于脚本或持续集成工作流。验证操作不需要 API 密钥或可选的生成器依赖项。

在 Python 中使用 CDAF

核心 Python API 可让应用程序在将伴随文件正文传递给语言模型前，先定位、加载并验证该文件。

from cdaf import load, check_freshness, sidecar_path_for

video = "footage/sunset-drone.mp4"
sidecar = load(sidecar_path_for(video))

if check_freshness(video, sidecar) == "fresh":
    context_for_llm = sidecar.body

这一模式是 CDAF 集成的核心：推导预期的伴随文件路径、解析文件、对照视频验证新鲜度，并且仅在结果为 fresh 时使用 sidecar.body。

该软件包的核心还支持序列化、分块 SHA-256 计算和片段提取。这些操作仅使用标准库。只有在请求生成时，才会导入生成器专用代码。

构建伴随文件优先的智能体工作流

  1. 在编辑、搜索或问答任务中接收视频路径。
  2. 查找具有相同基本文件名的 .cdaf 文件。
  3. 对照当前视频检查伴随文件的新鲜度。
  4. 如果文件是最新的，则读取其文本，而不是再次运行视频理解流程。
  5. 如果文件已过期或缺失，请先重新生成，再依赖其中的内容。
  6. 将摘要、片段、转录文本、屏幕文字和标签用作下游任务的上下文。

打包好的智能体技能建议：在探索阶段进行轻量级大小检查，在涉及重要决策时执行完整哈希检查。应用程序应根据具体操作选择适当的验证级别，同时遵守不得信任过期描述这一核心规则。

高级技巧

以文本方式搜索视频集合

视频拥有伴随文件后，智能体和命令行工具便可搜索 .cdaf 文件，而无需逐个打开视频。标签和描述可以把诸如没有人物的海岸日落镜头之类的请求，转化为对资产库的文本检索。

将片段转换为编辑决策

诸如 [00:05.2-00:12.8] 的带时间戳行提供了时间范围，程序化编辑器可以将其转换为剪辑或序列。README 特别指出，Remotion、HyperFrames 和提示词转编辑工具等工作流都能从这种结构中受益。

复用转录文本时间信息

存在语音时，Transcript 部分会将对话与时间轴对齐。编辑工作流可以复用这些信息来生成字幕和同步音频，而无需再次运行理解流程。

使用可选的 ffprobe 元数据

如果 ffprobe 可用，CDAF 的探测组件可以收集时长、分辨率和每秒帧数元数据。如果没有 ffprobe，引擎仍可平稳运行，因此这项可选集成不会阻碍基本的伴随文件操作。

考虑本地生成

代码仓库提供了通过 --local 使用的本地提供程序。当不应使用 API 密钥时，它可用于通过本地模型生成内容。请查看代码仓库中的本地提供程序实现，了解当前受支持的本地模型配置。

将后端与格式分离

CDAF 本身与模型无关。Gemini 是随附的远程生成器后端，其他视频语言模型后端也可以适配相同的 Sidecar 类型。其他 Claude、GPT 和本地 VLM 后端仍列在路线图中，不应假定它们目前已经可用。

复现基准测试

代码仓库包含一个客观基准测试，可使用 ffmpeg 根据脚本化方案合成视频。请按顺序运行以下阶段：

python benchmarks/bench.py make
python benchmarks/bench.py run
python benchmarks/bench.py report

第一步需要 ffmpeg，第二步需要 GEMINI_API_KEY，最后一步会生成 benchmarks/RESULTS.md。在报告的 20 道题测试中，伴随文件回答 20 题全部正确，而直接使用视频时答对 19 题；同时，每道题平均使用的提示词 token 数为 303，而不是 3,066。这些是代码仓库中的基准测试结果，可能会因素材、模型、提示词和环境而异。

当前限制与路线图

README 将以下项目列为未来工作，而非当前功能：PyPI 版本、MCP 服务器、托管转换器、更多生成器后端、Node 或 TypeScript 引擎移植、自然素材基准测试扩展，以及签名伴随文件。目前应使用文档中基于 Git 的 Python 安装方式和现有 CLI，不要假定这些路线图组件已经可用。

总结

CDAF 将重复的视频分析转化为“验证后读取”的工作流。只需生成一次伴随文件，将其放在源视频旁，在每次使用资产时进行验证，然后把正文提供给下游智能体。该格式通过哈希值防止视频编辑后意外复用旧描述，同时利用摘要、时间戳、转录文本、屏幕文字和标签，让视频库更易于搜索和自动化处理。

CDAF 采用 MIT License。源代码、规范、示例、基准测试详情和智能体技能均可在 CDAF GitHub 代码仓库中获取。