bytedance LAS 视频精细理解（las_long_video_understand）
基于大模型提供多维度、精细化的视频结构化理解。支持小时级（最大 3h）视频的全局理解、事件与行为识别、视频问答、高效摘要及结构化输出。
设计模式
本 skill 主要采用：
- Tool Wrapper：封装
lasutilCLI 调用 - Pipeline：包含 Step 0 → Step N 的顺序工作流
核心 API 与配置
- 算子 ID:
las_long_video_understand - API: 异步（
submit→poll） - 环境变量:
LAS_API_KEY(必填) - 支持时长: 最大支持 3h (10G) 视频。
详细参数与接口定义见 references/api.md。
Gotchas
- 不可精确预估：按 Token 计费，受视频时长和复杂度影响极大。
- 密钥安全：若聊天框屏蔽密钥，让用户在当前目录创建
env.sh并写入export LAS_API_KEY="..."，SDK 会自动读取。 - 免责声明：最终回复结果时必须包含："本方式的计费均为预估计费，与实际费用有差距，实际费用以运行后火山产生的账单为准。计费说明请参考 Volcengine LAS 定价。"，且禁止使用"实际费用"字眼描述预估价。
工作流（严格按步骤执行）
复制此清单并跟踪进度：
执行进度：
- [ ] Step 0: 前置检查
- [ ] Step 1: 初始化与准备
- [ ] Step 2: 预估价格
- [ ] Step 3: 提交异步任务
- [ ] Step 4: 轮询任务状态
- [ ] Step 5: 结果呈现
Step 0: 前置检查（⚠️ 必须在第一轮对话中完成）
在接受用户的任务后，不要立即开始执行，必须首先进行以下环境检查：
- 检查
LAS_API_KEY与LAS_REGION：确认环境变量或.env中是否已配置。- 若无，必须立即向用户索要（提示：
LAS_REGION常见为cn-beijing）。 - 注意：
LAS_REGION必须与您的 API Key 及 TOS Bucket 所在的地域完全一致。如果用户中途切换了 Region，必须提醒用户其 TOS Bucket 也需对应更换，否则会导致权限异常或上传失败。
- 若无，必须立即向用户索要（提示：
- 检查输入路径：
- 如果用户要求处理的是本地文件，则需要先通过 File API 上传至 TOS（只需
LAS_API_KEY，无需额外 TOS 凭证）。 - 如果算子的输出结果存放在 TOS 上，且用户需要下载回本地，则需要
VOLCENGINE_ACCESS_KEY和VOLCENGINE_SECRET_KEY。对于仅需要上传输入文件的场景，TOS 凭证不再必须。
- 如果用户要求处理的是本地文件，则需要先通过 File API 上传至 TOS（只需
- 确认无误后：才能进入下一步。
Step 1: 初始化与准备
环境初始化（Agent 必做）：
# 执行统一的环境初始化与更新脚本（会自动创建/激活虚拟环境，并检查更新）
source "$(dirname "$0")/scripts/env_init.sh" las_long_video_understand
workdir=$LAS_WORKDIR
如果网络问题导致更新失败，脚本会跳过检查，使用本地已安装的 SDK 继续执行。
- 处理本地文件时：先本地检查格式和时长，预估价格，用户确认后再上传：
计算预估价格并等待用户确认后，再执行上传：# 提前检查视频格式（避免参数错误） ./scripts/check_format.sh <local_path> # 本地使用 ffprobe 获取时长（无需上传即可预估价格） duration_sec=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:noprint_section=1 <local_path>)
上传成功后返回 JSON，取其中的# 用户确认后，上传到 TOS lasutil file-upload <local_path>tos_uri（格式tos://bucket/key）传给算子作为输入路径。
Step 2: 预估价格（⚠️ 必须获得用户确认）
本 skill 按 token 计费，由于视频长且分析复杂，提交前无法精确预估费用。
- 查阅 references/prices.md 的说明。
- 说明此任务产生的 token 量可能会非常大（特别是对于长视频）。
- 将计费单价告知用户并强制暂停执行，明确等待用户回复确认。在用户明确回复"继续"、"确认"等同意指令前，绝对禁止进入下一步（执行/提交任务）。提示：预估仅供参考，实际以火山账单为准。计费说明请参考 Volcengine LAS 定价。
Step 3: 提交异步任务 (Submit)
构造 data.json：
{
"video_url": "<url>",
"query": "请总结这个视频的主要内容",
"fps": 1.0,
"model_name": "doubao-seed-2-0-lite-260215"
}
执行命令：
data=$(cat "$workdir/data.json")
lasutil submit las_long_video_understand "$data" > "$workdir/submit.json"
task_id=$(cat "$workdir/submit.json" | jq -r '.metadata.task_id')
echo "Task ID: $task_id"
Step 4: 轮询任务状态 (Poll)
# 获取任务状态
lasutil poll las_long_video_understand "$task_id" > "$workdir/poll.json"
cat "$workdir/poll.json" | jq -r '.metadata.task_status'
- 如果状态是
PENDING或RUNNING，等待一段时间后再次执行上述命令。由于是长视频理解，耗时可能较长。 - 如果状态是
COMPLETED，继续 Step 5。 - 如果状态是
FAILED，向用户报告错误error_msg。
Step 4: 异步查询 (Poll)
⚠️ 异步任务与后台轮询约束：
如果环境支持后台任务，可以使用优化后的后台轮询脚本自动轮询直到完成：
mkdir -p "./output/${task_id}" ./scripts/poll_background.sh ${task_id} "./output/${task_id}" & disown脚本特性：
- 动态间隔：前 5 次 30s，5-10 次 60s，10 次后 120s
- 完成标记：生成
COMPLETED标记文件 - 适合长视频理解这类耗时较长的任务
如果环境不支持后台任务，手动轮询：
# 获取任务状态 lasutil poll las_long_video_understand "$task_id" > "$workdir/poll.json" cat "$workdir/poll.json" | jq -r '.metadata.task_status'- 如果状态是
PENDING或RUNNING，等待一段时间后再次执行上述命令。由于是长视频理解，耗时可能较长。 - 如果状态是
COMPLETED，继续 Step 5。 - 如果状态是
FAILED，向用户报告错误error_msg。
- 如果状态是
Step 5: 结果呈现
处理结果：
使用脚本自动生成结果展示（自动包含计费声明）：
./scripts/generate_result.md.sh ${task_id} "./output/${task_id}" <estimated_price>
手动处理：
# 解析最终摘要
cat "$workdir/poll.json" | jq -r '.data.final_summary'
# 可选：保存 clips 详情到本地
cat "$workdir/poll.json" | jq '.data.clips' > "./output/${task_id}/clips_detail.json"
向用户展示：
- 使用生成的 markdown 展示
- 呈现视频的
final_summary（最终摘要） - 如果有精彩片段问答或特定 query 回答，结合
clips提取并展示 - 自动包含计费声明 ✅