视频理解桥 MarOrZou/qwen-video-skill

Qwen Video Skill

让没有视频理解能力的模型获得视频理解能力——把视频发给 Qwen3.8-Max，用文字描述回来。

如果你是 AI（DSH），请读这里

用户把这个文件发给你，是想让你帮他配置或使用视频理解。先确认信息，再按场景执行。

先确认

1. 视频理解服务是否已经配置？默认走阿里云百炼，模型为 qwen3.8-max，支持 OpenAI 兼容格式。
2. DASHSCOPE_API_KEY 是否已写入 video.js 同目录的 .env？没申请的话引导用户去阿里云百炼控制台注册。
3. 本地视频可能超过 10MB，是否已配置 OSS？（OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_BUCKET、OSS_REGION 或 OSS_ENDPOINT）

场景 A：在 DSH 里使用（当前安装方式）

1. 技能已经装在 ~/.codex/skills/qwen-video-skill/。
2. 用户发来视频时，运行：

node C:\Users\keyzo\.codex\skills\qwen-video-skill\video.js "<视频绝对路径>" "[问题]"

3. 超过 10MB 的本地视频会自动上传到 OSS，再用生成的 URL 调用模型。

场景 B：在普通项目里使用

1. 把 video.js 和 package.json 拷到项目根目录，运行 npm install。
2. 在项目根目录放一个 .env，填 DASHSCOPE_API_KEY、VIDEO_MODEL，按需填 OSS 配置。
3. 把 SKILL.md 的内容合并到项目的 AGENTS.md 或 CLAUDE.md。
4. 告诉用户：配置完成，以后直接发视频即可。

场景 C：用户只想了解这是什么

- video.js 读取本地视频 → 转成 Base64 或上传 OSS → 发给 Qwen3.8-Max → 返回文字描述
- 走 OpenAI 兼容格式，默认对接阿里云百炼
- 配置好之后直接发视频即可，无需手动打命令

如果你是人类，请读这里

这是什么

一个让不具备原生视频理解能力的模型也能「看视频」的脚本。配置好之后，直接把视频发给 Codex，AI 会调用 Qwen3.8-Max 把内容转成文字。

推荐视频理解服务

| 服务 | 模型 | 备注 |
| 阿里云百炼（推荐） | qwen3.8-max | 支持图片和视频理解 |
| 阿里云百炼 | qwen-vl-max 等 | 兼容 OpenAI 格式 |
| 其他 | 任意 OpenAI 兼容多模态模型 | 改 VIDEO_MODEL / DASHSCOPE_BASE_URL 即可 |

使用

本地视频：

node C:\Users\keyzo\.codex\skills\qwen-video-skill\video.js "C:\path\to\video.mp4" "描述这段视频"

远程视频：

node C:\Users\keyzo\.codex\skills\qwen-video-skill\video.js --url "https://example.com/video.mp4" "描述这段视频"

常用参数：

- --fps 0.1-10：抽帧频率，默认 2.0，运动场景调高，静态/长视频调低
- --max-tokens 2048：输出上限
- --upload-oss：强制本地视频走 OSS 上传

大文件自动上传 OSS

本地视频以 Base64 传入时上限约 10MB。超过上限时 video.js 会自动上传到阿里云 OSS，再把公网 URL 传给模型。

在 .env 中配置：

OSS_ACCESS_KEY_ID=你的AccessKeyId
OSS_ACCESS_KEY_SECRET=你的AccessKeySecret
OSS_BUCKET=你的Bucket名
OSS_REGION=oss-cn-shanghai
OSS_ENDPOINT=也可以直接填 Endpoint，和 OSS_REGION 二选一
OSS_PREFIX=codex-videos/
OSS_PUBLIC_BASE_URL=有公网域名/CDN 时填
OSS_URL_EXPIRES=3600

没配 OSS_PUBLIC_BASE_URL 时使用临时签名 URL（默认 1 小时有效）；配了则使用固定公网地址。

限制

- 视频时长：2 秒至 2 小时（Qwen3.8 系列）
- 远程 URL 最大 2GB
- 格式：MP4、AVI、MKV、MOV、FLV、WMV 等
- 不支持理解视频里的音频

手动配置

1. 把 video.js 和 package.json 拷到项目里，运行 npm install。
2. 创建 .env，填 DASHSCOPE_API_KEY、VIDEO_MODEL，按需填 OSS 配置。
3. 把 SKILL.md 放到 ~/.codex/skills/（或按项目 AGENTS/CLAUDE 约定接入）。

文件说明

| 文件 | 用途 |
| video.js | 核心脚本，OpenAI 兼容格式，调用 Qwen3.8-Max |
| SKILL.md | 技能说明，告诉 Codex 何时用 video.js |
| .env | 配置 API Key、模型和 OSS 凭证 |
| package.json | 依赖声明（dotenv、ali-oss） |